v6.3.0: Bounded scoped cache acquisitions

[flyingrobots]

Release milestone

v6.3.0

Outcome

A cache consumer can acquire a live CacheSet entry through a bounded, reference-only lookup and hold an explicit scoped anchor to the exact observed cache generation until an idempotent release. This closes the correctness and performance gap blocking git-warp's handle-first materialization path.

Current truth

• CacheSet.get() resolves every hit target to recompute logical bytes, so a bundle target can trigger complete recursive support-graph validation instead of a bounded metadata lookup. [cite: src/domain/services/CacheSet.js#37-51@432c5d9effb12c9f66536f1386791bb4421f3cea]
• CacheIndex.getEntry() and BundleService.getMemberReference() already provide reference-only targeted traversal, but CacheSet does not expose that bounded path to consumers. [cite: src/domain/services/CacheIndex.js#61-67@432c5d9effb12c9f66536f1386791bb4421f3cea] [cite: src/domain/services/BundleService.js#100-123@432c5d9effb12c9f66536f1386791bb4421f3cea]
• A cache hit carries an observation witness for the cache ref/generation, but no lifetime lease; replacement or eviction can make that generation unreachable while a caller is still consuming it. [cite: src/domain/services/CacheSet.js#482-497@432c5d9effb12c9f66536f1386791bb4421f3cea]
• RootSet generations are parentless current-generation commits, so anchoring the exact observed generation is sufficient to preserve its reachable index and targets. [cite: src/domain/services/RootSetPersistence.js#40-58@432c5d9effb12c9f66536f1386791bb4421f3cea]

Scope

• Add a bounded CacheSet.acquire(key) contract.
• Return a scoped acquisition containing the cache hit/target and an idempotent release().
• Anchor the exact observed cache generation before returning.
• Add atomic ref deletion support at the Git ref port/adapter boundary.
• Make abandoned acquisition refs inspectable and repairable/cleanable by git-cas.
• Prove lookup cost does not scale with the target support graph.
• Prove replacement/eviction plus aggressive pruning cannot invalidate an active acquisition.
• Document the lifecycle, error contract, and release obligations.

Out of scope

• Changing ordinary CacheSet.get() compatibility semantics.
• Application-owned pin refs or CAS object management.
• Redefining cache TTL/LRU policy.
• Solving git-warp's full causal-slice materialization in this repository.

Slices

• Design the acquisition/ref lifecycle and abandoned-acquisition cleanup.
• Write failing unit and real-Git integration tests.
• Implement the domain value/service, ports, adapters, declarations, docs, and diagnostics.
• Produce witness evidence, self-review, independent Code Lawyer review, and release verification.
• Publish v6.3.0 and hand the API to git-warp.

Design doc

docs/design/0048-scoped-cache-acquisitions/scoped-cache-acquisitions.md

Required proof

• Instrumented real-Git test showing acquisition reads remain bounded as an unrelated nested target support graph grows.
• Race test showing an acquired generation remains reachable through replacement/eviction and aggressive prune until release.
• Idempotent release and stale-acquisition cleanup tests.
• Existing CacheSet compatibility suite remains green.
• npm test, lint/type surface checks, and release verification pass.

Release gate impact

Additive public API and declarations, GitRefPort adapter extension, cache diagnostics/repair behavior, README and CHANGELOG updates, generated API surface verification, and npm v6.3.0 publication.

[coderabbitai]

🔗 Related PRs

#61 - Design the application storage and cache ownership boundary [merged]
#62 - feat: add opaque application asset handles [merged]
#64 - Add managed CacheSet lifecycle [merged]
#65 - Add expiry-safe replay sets [merged]
#68 - docs: record git-cas v6.2.0 publication [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[flyingrobots]

Completed.

@git-stunts/git-cas@6.3.0 is published to npm, and the downstream handoff is merged in git-warp PR #756 as a97d03ce67fa3a8d8547f18d210e11c1c8f48af4.

Downstream source evidence:

• git-warp now depends on @git-stunts/git-cas ^6.3.0. [cite: package.json#120@a97d03ce67fa3a8d8547f18d210e11c1c8f48af4]
• The Git-backed materialization adapter uses CacheSet.acquire(), decodes the retained bundle while the acquisition is active, and releases on decode/validation failure. [cite: src/infrastructure/adapters/GitCasMaterializationStoreAdapter.ts#163-188@a97d03ce67fa3a8d8547f18d210e11c1c8f48af4]
• Live handle resolution returns operation-scoped acquisitions on warm hits and reacquires the exact retained generation after a cold materialization. [cite: src/domain/services/controllers/MaterializeLiveStrategy.ts#55-101@a97d03ce67fa3a8d8547f18d210e11c1c8f48af4]
• The real-Git integration proves that generation A survives cache replacement, expired reflogs, and git prune --expire=now while acquired; after release, A becomes prunable while generation B remains retained. [cite: test/integration/infrastructure/adapters/GitCasMaterializationStoreAdapter.integration.test.ts#87-132@a97d03ce67fa3a8d8547f18d210e11c1c8f48af4]

Release: https://www.npmjs.com/package/@git-stunts/git-cas/v/6.3.0
Downstream merge: git-stunts/git-warp#756