Skip to content

cli: unify burn rebuild and burn archive under one "rebuild derived state" verb #153

Description

@willwashburn

Summary

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.

  1. Add commands/rebuild.ts plumbing for the new positional-target shape.
  2. 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.
  3. 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).
  4. rebuild all runs targets in dependency order: contentindexclassifyarchive. Document the order so the help is self-explanatory.
  5. Help-block surgery in cli.ts to collapse the two help lines into one block.
  6. CHANGELOG [Unreleased] entry. Sweep README / AGENTS.md / docs.
  7. Tests: keep archive.test.ts and rebuild.test.ts exercising the underlying paths; add a rebuild status integration test.

Risks / questions

  • Naming. "rebuild" implies destructive; the current archive build is an incremental tail apply, not a rebuild. Consider:
    • burn rebuild <target> with --full to mean drop-and-rebuild, default = incremental apply, OR
    • burn derive <target> as a less loaded verb. Probably overkill; staying with rebuild and treating --full as the "scorched earth" flag is cleaner.
  • rebuild-index removal — see cli: drop burn rebuild-index (already an alias for burn 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

  • Adding new derived-data targets (e.g. a separate quality cache).
  • The archive schema itself; this is a CLI surface change, not a storage change.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions