Problem
The low-level staging APIs intentionally return unanchored handles. That is honest for one object, but a consumer building a large multi-object graph has no git-cas-owned way to keep early staged assets reachable while later assets and aggregate bundles are still being constructed.
The current git-warp retained-property path demonstrates the gap:
- Stage each property shard.
- Build the property bundle.
- Include that bundle in a materialization workspace checkpoint.
- Promote the terminal materialization.
Default Git GC grace protects recent objects in normal operation, but early shards remain unreachable for the entire build. A concurrent immediate-expiry prune can remove them before the final workspace checkpoint. git-warp must not solve this by managing refs, RootSets, or CAS cache entries itself.
Desired Contract
Provide a git-cas-owned scoped staging workspace (name TBD) that:
- Incrementally anchors staged assets, pages, and bundles under one temporary RootSet-backed lease.
- Builds aggregate bundles whose members remain reachable throughout construction.
- Returns retention evidence for the active workspace generation.
- Transfers or promotes the final root into a cache or publication without consumer-managed reachability.
- Releases all temporary roots idempotently on success or failure.
- Supports TTL renewal and doctor visibility for abandoned workspaces.
- Documents the irreducible Git object-write-to-ref-update micro-window and the required GC grace invariant.
Illustrative shape only:
const workspace = await cas.workspaces.open({
namespace: "git-warp/materializations",
ttl: "2h",
});
const shard = await workspace.assets.stage(...);
const root = await workspace.bundles.putOrdered(...);
const retained = await workspace.promote({
target: cache,
key,
handle: root.handle,
});
await workspace.release();Acceptance Evidence
- An integration test runs a long multi-member build while GC runs with a supported grace policy and proves every staged dependency survives through promotion.
- Failure-injection tests prove release after asset, bundle, checkpoint, and promotion failures.
- Doctor reports workspace object count, logical bytes, age, expiry, and active or abandoned posture.
- A reachability test proves the consumer never writes Git objects or refs directly.
- Documentation distinguishes ordinary supported GC from unsafe concurrent
git prune --expire=now.
Downstream
Blocks closing the final lifecycle caveat in git-warp's v19 retained-property materialization work and preserves the invariant that git-warp owns zero CAS reachability machinery.
Problem
The low-level staging APIs intentionally return unanchored handles. That is honest for one object, but a consumer building a large multi-object graph has no git-cas-owned way to keep early staged assets reachable while later assets and aggregate bundles are still being constructed.
The current git-warp retained-property path demonstrates the gap:
Default Git GC grace protects recent objects in normal operation, but early shards remain unreachable for the entire build. A concurrent immediate-expiry prune can remove them before the final workspace checkpoint. git-warp must not solve this by managing refs, RootSets, or CAS cache entries itself.
Desired Contract
Provide a git-cas-owned scoped staging workspace (name TBD) that:
Illustrative shape only:
Acceptance Evidence
git prune --expire=now.Downstream
Blocks closing the final lifecycle caveat in git-warp's v19 retained-property materialization work and preserves the invariant that git-warp owns zero CAS reachability machinery.