Remove, delete, prune and compact: branch.remove, project.delete, branch.prune, store.compact #511

Answers #411 and is #446 A8. Owner direction (2026-10-30): no automatic compaction. Space comes back only through explicit SDK calls.

The full spec is core/docs/issues/511/README.md on the PR #507 branch (issue506-store-backends-remote). It builds on the #506 Store model, where runtime.project.remove was renamed runtime.project.delete on 2026-10-30.

The four calls

Each call is one attempt, with no retry. The CLI gets the same verbs.

Why removal can't simply delete

• Stored data is shared and can't be changed or deleted in place.
  • Packs are trigger-immutable, and read_immutable depends on that.
  • Each pack is written by one Save, then reused by later Commits of any project through dedup and delta bases. Delta bases are referenced only by ID, possibly across projects.
• History is shared too. Forks share Commits; merges and Layers point into other Branches.
• Branch names can't be reused safely as-is, because a Branch's ID is derived from its name (BranchId::named). See D1.
• No Store table records mounts, and some roots live outside the Store: mounted bases, in-flight Saves and reads, macOS NFS exports (raised by jiangkoumo on layerfs rm/compact: retire Branches and reclaim unreachable Store history #411). Compact therefore requires the Store closed, which covers all of them.

Findings (diagnostic, one read-only sample, 2026-10-30)

• Dedup is already strong: 260.5 GB of files across all Commits become 688 MB after dedup and 237.4 MB on disk.
• History rows cost about 0.7 KB per Commit (0.55 MB in all). The space is in file data, much of it in a few Commits and in intermediate trees.
• Bounds: these are upper bounds from per-Commit "stored first" attribution. Compact's dry run gives the exact figure.

Builds on

• A1's reachability walk (SnapshotClosure, proposed by SSK015 on layerfs rm/compact: retire Branches and reclaim unreachable Store history #411). Compact reuses it, plus physical dependencies (delta bases, pooled ordinals).

• A1's backing question: the visited set is the new file's own indexed, on-disk object_location table.

• cadorn's requirements (layerfs rm/compact: retire Branches and reclaim unreachable Store history #411):

  • typed refusal while mounted: MountsActive;
  • Branch gone from listings at once;
  • collection the caller triggers and observes: store.compact with its report and dry run;
  • an SDK call, named branch.remove here.

  The one difference: removing a Branch that another Branch forked from is allowed (D7), since the fork keeps what it uses.

Owner decisions

• D1 · Reuse of a removed Branch's name. Recommended: new Branches get a generation in their ID (format change). Alternative: refuse reuse while the tombstone exists.
• D2 · project.delete in a shared Store hides instead of deleting rows (recommended).
• D3 · Writers check at admission that their open file is still the Store's (inode), else Replaced. Recommended; it also closes pull's opener race.
• D4 · PostgreSQL compact later. Remove, delete and prune work on PostgreSQL now.
• D5 · A pruned Commit keeps change counts and bytes, not a full path list (recommended).
• D6 · Schema version bump (removed_ms, deleted_ms, pruned_ms, partial unique indexes, change summary) with a one-time upgrade on open.
• D7 · Allow removing a Branch that another Branch forked from (recommended).

Done when

• the four calls, CLI verbs and Connect actions (Remove…, Delete…, Prune history…, Compact… with a dry run) are built;
• on a fixture Store (cross-project dedup, a cross-project delta base, a fork sharing Commits, a merge, Layers, pruned Commits, pooled leaves), every kept Commit and Layer reads identically after compact, merge bases are unchanged, and the dry run equals the real run;
• remove, delete and prune each take one short write;
• measured on copies of r2-examples-clone and services under the agent measurement policy: exact bytes freed against the bounds above, and compact's wall time.

Out of scope: automatic collection, in-place sweep, PostgreSQL compaction, remote-side compaction (push the compacted file), and pruning main's Layers.