symlog follow-up: analytics, remote sharing, and ergonomic extensions

muse symlog — Follow-up Items

Background

Issue #51 delivered the full symlog foundation: per-symbol journaling at commit time, muse symlog read CLI with filters, lifecycle management (expire/delete/GC), and @{N} ref resolution for muse code cat, muse symlog resolve, and muse symlog diff. All 55 test IDs (SL_01–SL_55) are green.

This issue captures the items explicitly deferred from #51 plus useful extensions that emerged during implementation.

Deferred from #51

1. Analytics commands — muse symlog coupling and muse symlog hotspots

The live symlog journal is a rich, already-written dataset. Two analytics commands can read it in O(1) per symbol without touching commit history:

muse symlog hotspots [--top N] [--file path] [--json] — ranks symbols by churn (number of symbol-modified entries in the journal). Complements muse code hotspots (which reads commit history) with a zero-scan alternative that is always up to date.

muse symlog coupling [--file path] [--json] — finds symbol pairs that share commit IDs across their logs (i.e. they always change together). Surfaced purely from symlog data, no AST traversal needed.

2. muse blame integration

muse blame "file.py::Symbol" currently reconstructs authorship by scanning commit history. With symlogs in place, the per-symbol change record already contains author and commit ID at each index. blame should prefer the symlog when available — O(1) per symbol instead of O(commits).

3. muse code narrative rewrite

muse code narrative "file.py::Symbol" generates a plain-English description of a symbol's lifecycle. It currently works from AST diffs across commits. The symlog journal is the canonical source of that history now — narrative should read from symlog entries, gaining richer metadata (operation, author, born-from chains).

4. Remote symlog sharing

Symlogs are currently local-only — they are not pushed or pulled. For teams sharing a MuseHub remote, symlogs are silently missing on clones. The correct design:

• muse push bundles .muse/symlogs/ alongside commits.
• muse pull merges incoming symlog entries (append-only, no conflicts).
• muse bundle create includes symlogs in the msgpack payload.

5. Symlog entries for non-code domains

The extractor returns {} for non-parseable files, so MIDI tracks, binary assets, and schema files produce no symlog entries. For music repos this is the wrong trade-off: a MIDI symbol (track::chorus) should produce a symlog entry when the Harmony domain plugin identifies a change. Deferred until the domain plugin API supports content-ID extraction for non-code artifacts.

6. Relative time syntax (@{1.day.ago}, @{yesterday})

@{N} addresses work by index. Git's reflog also supports relative time syntax (HEAD@{1.hour.ago}). Symlog --since/--until cover the filtering use case, but @{1.day.ago} as a direct ref specifier is more ergonomic in agent prompts.

New items from implementation

7. muse checkout-symbol "file.py::Symbol@{N}"

Restore a prior version of a single symbol to disk without touching any other file. The natural extension of muse code cat "addr@{N}" — cat reads, checkout restores. Critically useful for surgical recovery: "undo the change to this one function without reverting the whole commit."

8. muse symlog grep PATTERN [--file path] [--json]

Search symbol bodies across their full symlog history. Answers: "when did this symbol last contain the string deprecated?" or "which version of this function called session.add?" Reads object store bodies via resolve_symbol_body for each entry.

9. muse symlog show "file.py::Symbol@{N}"

Convenience alias for muse code cat "file.py::Symbol@{N}" with human-focused output: operation, author, timestamp header, then the full symbol body. Useful for interactive exploration ("show me what this function looked like two changes ago").

10. muse symlog stat [--file path] [--json]

Summary statistics for a symbol or file: total entries, operation breakdown (created/modified/deleted/renamed), most active author, first and last commit IDs, date range. Useful for code review context and agent decision-making.

11. Symlog entries for muse revert

muse revert records a reflog entry for the branch ref move, but writes no symlog entries for the symbols it touches. A revert of a commit that modified compute_total should produce a symbol-modified: revert <commit_id> entry in that symbol's log.

12. muse symlog prune-orphans [--dry-run] [--json]

Find symlog files whose symbol address no longer exists in the current snapshot and remove them. Analogous to muse gc for unreachable objects — keeps the .muse/symlogs/ tree clean after large-scale renames or file deletions.