Compound staging-workspace admission into one retained generation

[flyingrobots]

Design

• PERF-0060 - Compound Workspace Admission
• Draft implementation: Batch compound workspace admission into one retained generation #124

Symptom

The released bounded write APIs remove per-item Git children, but a downstream dependency-ordered materialization still publishes one workspace RootSet generation per page or bundle wave. In the current git-warp v19 reference corpus, batching reduces cold materialization from 781 to 139 Git children, yet the survivor census still includes 60 hash-object, 21 commit-tree, 22 symbolic-ref, and 21 checked update-ref operations. Most are repeated temporary-retention publication, not irreducible content construction.

Root cause

StagingWorkspace.pages.putBatch() and bundles.putOrderedBatch() correctly guarantee that every returned handle is anchored before it escapes. A caller constructing a dependency graph must await each wave to obtain content-addressed child handles, so each wave independently installs the workspace's growing target set. The substrate has no bounded compound admission in which provisional handles remain private until one final generation anchors the whole successful operation.

Required behavior

• Add a generic, bounded staging-workspace compound operation for dependency-ordered page and bundle batches.
• Keep every provisional handle scoped to the callback; return no caller-visible result until one exact RootSet generation anchors all newly staged targets together with prior workspace targets.
• Reuse one operation-owned Git object scope across the compound operation without exposing Plumbing or Git sessions above git-cas.
• Serialize compound sub-operations deterministically, enforce an explicit operation bound, reject escaped use after closure, and preserve earliest-failure behavior.
• If construction, callback execution, session closure, target resolution, or final retention fails, do not move the workspace ref and do not return a partial result. Dangling immutable objects may remain for normal Git reclamation.
• Preserve existing singleton and batch APIs, handles, exact target ordering, checked-ref conflict semantics, release/promote behavior, SHA-1/SHA-256 identity, and storage format.
• Prove immediate prune safety after success and prove no generation movement on failure.
• Benchmark sequential retained waves versus compound admission with identical semantic digests and stable process topology.

Non-goals

• No cross-workspace transaction.
• No storage-format or migration change.
• No manual Git object encoding.
• No weakening of the rule that handles returned outside the compound operation are already retained.
• No git-warp-specific trie or graph vocabulary in git-cas.

Downstream acceptance

After release, git-stunts/git-warp#852 may adopt this capability behind its materialization workspace adapter. The v19 performance corpus must retain exact semantic fingerprints and existing migrated-v18 read compatibility while materially reducing cold and incremental Git children again.