You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
burn rebuild (sidecar index, classifier, content sidecars) and burn archive build|rebuild|status (SQLite read model) are both "rebuild derived state from the canonical ledger". The split is an implementation detail — users have to remember which derivation lives behind which verb. Collapse them under a single command shape so there is one mental model and one help screen for "fix my derived data".
Background
Today:
burn rebuild --index | --reclassify | --content [--force] lives in packages/cli/src/commands/rebuild.ts:1-80. Operates on the JSONL sidecar index, classifier output, and content sidecars.
burn archive build | rebuild | status [--json] lives in packages/cli/src/commands/archive.ts:1-115. Operates on the SQLite analytics read model.
Help block: packages/cli/src/cli.ts:42-44.
Conceptually both commands answer "the canonical ledger is the source of truth — please re-derive everything else from it." The archive command even acknowledges this in its own help text (archive.ts:19-25): "The archive is a disposable read model derived from ledger.jsonl."
Proposed shape
One verb, target as a positional:
burn rebuild <target> [flags]
Targets:
index Sidecar id/content fingerprint index (current --index)
classify Re-run the activity classifier (current --reclassify [--force])
content Reingest missing content sidecars (current --content)
archive Apply ledger tail to SQLite read model (current `archive build`)
archive --full Drop and rebuild SQLite from scratch (current `archive rebuild`)
all Run all targets in dependency order
burn rebuild status Schema versions, row counts, sync state for every
derived artifact (replaces `archive status`; also
shows index / sidecar / content state).
Open question: whether status should be a sibling subcommand or burn rebuild --status. Sibling reads better.
Implementation Steps
No users yet — this lands as a clean break with no deprecation alias path.
Add commands/rebuild.ts plumbing for the new positional-target shape.
Move the archive subcommand bodies (runBuild, runRebuild, runStatus in commands/archive.ts) into helpers callable from the new rebuild dispatcher. The underlying @relayburn/ledger calls (buildArchive, rebuildArchive, getArchiveStatus) stay where they are.
Implement rebuild status as a unified status report that prints:
Sidecar index: present? size? last rebuilt?
Classifier coverage: % of turns with activity set.
Content sidecars: count, total bytes, retention setting.
SQLite archive: schema version, ledger cursor, row counts (the existing archive status block).
rebuild all runs targets in dependency order: content → index → classify → archive. Document the order so the help is self-explanatory.
Help-block surgery in cli.ts to collapse the two help lines into one block.
Summary
burn rebuild(sidecar index, classifier, content sidecars) andburn archive build|rebuild|status(SQLite read model) are both "rebuild derived state from the canonical ledger". The split is an implementation detail — users have to remember which derivation lives behind which verb. Collapse them under a single command shape so there is one mental model and one help screen for "fix my derived data".Background
Today:
burn rebuild --index | --reclassify | --content [--force]lives inpackages/cli/src/commands/rebuild.ts:1-80. Operates on the JSONL sidecar index, classifier output, and content sidecars.burn archive build | rebuild | status [--json]lives inpackages/cli/src/commands/archive.ts:1-115. Operates on the SQLite analytics read model.packages/cli/src/cli.ts:42-44.Conceptually both commands answer "the canonical ledger is the source of truth — please re-derive everything else from it." The
archivecommand even acknowledges this in its own help text (archive.ts:19-25): "The archive is a disposable read model derived fromledger.jsonl."Proposed shape
One verb, target as a positional:
Open question: whether
statusshould be a sibling subcommand orburn rebuild --status. Sibling reads better.Implementation Steps
No users yet — this lands as a clean break with no deprecation alias path.
commands/rebuild.tsplumbing for the new positional-target shape.archivesubcommand bodies (runBuild,runRebuild,runStatusincommands/archive.ts) into helpers callable from the newrebuilddispatcher. The underlying@relayburn/ledgercalls (buildArchive,rebuildArchive,getArchiveStatus) stay where they are.rebuild statusas a unified status report that prints:activityset.archive statusblock).rebuild allruns targets in dependency order:content→index→classify→archive. Document the order so the help is self-explanatory.cli.tsto collapse the two help lines into one block.[Unreleased]entry. Sweep README / AGENTS.md / docs.archive.test.tsandrebuild.test.tsexercising the underlying paths; add arebuild statusintegration test.Risks / questions
archive buildis an incremental tail apply, not a rebuild. Consider:burn rebuild <target>with--fullto mean drop-and-rebuild, default = incremental apply, ORburn derive <target>as a less loaded verb. Probably overkill; staying withrebuildand treating--fullas the "scorched earth" flag is cleaner.rebuild-indexremoval — see cli: dropburn rebuild-index(already an alias forburn rebuild --index) #151 (the standalone alias) — should land first or as part of this. Once unified, no need for the dedicated alias.Out of scope
archiveschema itself; this is a CLI surface change, not a storage change.