feat(coordinator): reap orphaned base snapshots (image-refresh storage leak)

[nikhilunni]

What

Adds a coordinator sweeper that reaps orphaned per-image base snapshots — the storage leak behind the Jun-23/24 jump in GCS live-object bytes.

Why

Every enabled-image re-bake/RefreshImage captures a fresh base snapshot and swaps enabled_images.base_snapshot_id to it (upsert_enabled_image's ON CONFLICT). The prior base row is left dangling: session_id IS NULL, pointed to by no enabled_images row. Nothing deleted it:

• prune_session_snapshots (checkpoint retention) is session_id IS NOT NULL only.
• An orphan base keeps pinning its own disk+memory chunks via chunk-GC pin-set sources chore(web)(deps): bump the web-minor-patch group across 1 directory with 6 updates #3/chore(web)(deps): bump framer-motion from 11.18.2 to 12.38.0 in /web #4 (list_recoverable_snapshot_{disk,memory}_manifests — recoverable = TRUE, no session predicate).

So each refresh permanently leaked one base snapshot's chunks — 20–32 GB for the heavy dogfood images (dev-brain, dev-engrams). Prod currently holds 23 orphaned bases (~150 GB logical) dating back 9 days, none in any GC queue.

How

prune_orphan_base_snapshots — the session_id IS NULL mirror of prune_session_snapshots:

DELETE FROM snapshots s
WHERE s.session_id IS NULL
  AND s.created_at < NOW() - $grace
  AND s.id NOT IN (SELECT base_snapshot_id FROM enabled_images WHERE base_snapshot_id IS NOT NULL)

• Skips bases referenced by any enabled_images row, including soft-deleted (their chunk lineage is intentionally still pinned, ADR 0021 P1.8).
• Bumps chunk_generation in the same TX (GC-barrier symmetry). The existing chunk-GC (ADR 0016 Phase C) and snapshot-blob-GC (ADR 0028 addendum) sweeps then reclaim the now-unpinned chunks and portable snapshots/<id>/ blobs — this reaper deletes nothing in BlobStorage directly.
• The base_snapshot_id FK (REFERENCES snapshots(id), no ON DELETE) is a hard backstop against deleting an in-use base even if the predicate regressed.
• Spawned beside checkpoint_retention; grace via ENGRAM_BASE_SNAPSHOT_RETENTION_HOURS (default 24).

A sweeper (not an inline delete in RefreshImage) so it both drains the existing 23-orphan backlog and prevents future leaks, per the "scanner drives transitions" convention.

Test

Live-PG test wired into the existing Postgres-gated CI lane (checkpoint_reconcile_live_pg): a superseded orphan past grace is reaped; the current enabled-image base and a fresh orphan within grace are kept; session snapshots are untouched. Validated against a real Postgres locally (just check green: fmt + clippy -D warnings + 1270 workspace tests).

Also fixes the now-stale snapshot_blob_pin_set doc comment that asserted base rows are never deleted.

Scope notes

• No ADR — this is an incremental extension of the existing ADR-0016/0028 GC machinery, not a new decision. The broader idle-session GC the orphan investigation surfaced is a separate follow-up (different row population: session_id IS NOT NULL).
• No admin trigger — matches checkpoint_retention (its closest sibling); the 24h sweeper drains the backlog automatically. For immediate prod reclaim we can run the equivalent one-shot SQL out of band.

Roll

Coord-only; auto-rolls on merge. The 23 existing orphans age out within one grace window (24h) after deploy.

🤖 Generated with Claude Code