symlog write silently skipped when URL-encoded symbol name exceeds 255-byte filename limit

symlog write fails silently when symbol path exceeds OS filename limit

Background

When committing a markdown file whose section headings are long, Muse emits a warning and skips the symbol journal entry:

⚠️ symlog write failed for commit sha256:bb322b… — symbol journal may be
incomplete: [Errno 63] File name too long:
'/Users/gabriel/ecosystem/muse/.muse/symlogs/docs/issues/mwp-5-clone-retry-503.md/
MWP-5%20%E2%80%94%20Clone%2Ffetch%2Fpull%20honor%20Retry-After%20with%20a%20bounded%20poll%20%28fixes%20RC-5%29.
Phases%20%E2%80%94%20load-bearing%2C%20TDD%2C%20never%20skip%20ahead.Phase%205%20%E2%80%94%20real-urllib%20E2E%20%2B%20docs%20%2B%20close%20%E2%9C%85'

The commit itself succeeds and is content-addressed correctly. Only the symlog entry for that symbol is missing — muse code symbol-log for the long-heading symbol will show no history.

Trigger: the symlog filename is derived by URL-encoding the symbol address (file.md::Section Heading). On macOS (APFS) and Linux (ext4/xfs) the per-component filename limit is 255 bytes. A long section heading with multi-byte Unicode (em-dashes —, encoded as %E2%80%94, slashes, parentheses) blows past this quickly.

Root cause

The symlog writer constructs a filesystem path by joining the repo-relative file path with the URL-encoded symbol name and a .jsonl extension. No length check is performed before the open() call. [Errno 63] File name too long is caught and re-emitted as a warning, so the commit is not aborted — but the journal entry is permanently missing for that symbol.

Relevant code path (unverified exact line — run muse code grep "symlog" --json):

muse/core/symlog.py  (or equivalent)

Goal

1. Detect when the constructed symlog filename would exceed the OS limit (255 bytes per component is the POSIX minimum; use that as the ceiling).
2. Fall back to a deterministic truncation or hash-based filename that stays within the limit while remaining unique and human-readable where possible.
3. The muse code symbol-log command must return correct history for symbols with long names — no silent gaps.
4. The warning is replaced by either: (a) no output (silent success via the fallback), or (b) a debug-level log if the fallback fires, never a user-visible warning on a clean commit.

Proposed fix

Option A — truncate + hash suffix (recommended)

filename = encode(symbol_name)
if len(filename) > MAX_COMPONENT_BYTES:
    truncated = filename[:200]          # leave room for suffix
    suffix    = sha256(symbol_name)[:8] # collision-resistant short hash
    filename  = f"{truncated}_{suffix}"

The truncated prefix stays human-readable in ls output; the hash suffix guarantees uniqueness even across symbols that share a long common prefix.

Option B — always hash long names

If the symbol name exceeds a threshold, use sha256(full_name).hex() as the filename entirely and store the original name inside the .jsonl payload. Loses human-readability but is simpler to implement correctly.

Either option must be accompanied by a migration that renames any existing overlong paths (unlikely in practice — the error prevents them from being written in the first place, so no existing corrupt entries to fix).

Acceptance criteria

• Committing a file with a section heading long enough to exceed 255 bytes (URL-encoded) produces no warning and a correct symlog entry.
• muse code symbol-log "docs/issues/long-heading-file.md::Long Section…" returns the expected history.
• Existing short-name symlogs are unaffected (no regression).
• Unit test covering the boundary: symbol name at 254 bytes, 255 bytes, and 256 bytes (encoded) all produce valid filenames.

Out of scope

• Changing the symlog storage format (.jsonl per symbol) — the format is fine.
• Handling the rare case where the directory component (the file path portion) also exceeds 255 bytes — that would require a separate path-component truncation pass and is not triggered by today's codebase.