Skip to content

Add burn archive vacuum for SQLite maintenance #104

@willwashburn

Description

@willwashburn

Context

PR #78 shipped burn archive build | rebuild | status but deliberately left vacuum off for the foundation PR:

burn archive vacuum (one-liner; trivial to add when needed).

Issue #40 lists vacuum in the proposed command set:

burn archive vacuum — runs SQLite maintenance if needed.

Over time, archive.sqlite accumulates free pages from INSERT OR REPLACE churn (every stamp re-fold rewrites turn rows; rebuild drops + recreates rows). Without periodic VACUUM, the on-disk file grows beyond what the row count implies. On a developer laptop this is fine for months; on a long-running CI/orchestration host it eventually becomes worth the one-shot reclaim.

Proposal

  1. Add a vacuumArchive() function to packages/ledger/src/archive.ts that opens the archive, runs VACUUM, and reports before/after file size.
  2. Add a burn archive vacuum subcommand in packages/cli/src/commands/archive.ts that calls it and prints a one-line summary (or JSON via --json):
    archive: vacuumed 12.3 MB -> 4.1 MB (reclaimed 8.2 MB)
    
  3. Acquire the same lock the build path uses so we don't VACUUM mid-build.
  4. No-op gracefully if the archive doesn't exist (print a hint to run burn archive build first).

Tests:

  • Vacuum reduces file size after a build/rebuild churn.
  • Concurrent vacuum + build serialize via the lock without corruption.
  • Vacuum on a missing archive exits cleanly with a hint.
  • --json shape: { before_bytes, after_bytes, reclaimed_bytes }.

Acceptance criteria

  • burn archive vacuum exists, documented in command help, and has unit + CLI tests.
  • Output (text and --json) includes before/after sizes.
  • Concurrent build is safely serialized.
  • No-op-with-hint path when archive is missing.

Out of scope

  • Auto-vacuum heuristics (e.g. vacuum after N rebuilds). Manual command first; automation later if measurements justify it.
  • Schema changes.

Refs

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions