Merge pull request #72 from git-stunts/fix/scoped-cache-acquisitions

feat: add scoped cache acquisitions

Author: flyingrobots

.github/workflows/ci.yml

@@ -55,5 +55,11 @@ jobs:
         run: docker compose build test-${{ matrix.runtime }}
       - name: Unit tests (${{ matrix.runtime }})
         run: docker compose run --rm test-${{ matrix.runtime }}
+      - name: Public type compatibility (Deno)
+        if: matrix.runtime == 'deno'
+        run: >-
+          docker compose run --rm test-deno
+          deno check --config test/types/deno.json
+          test/types/public-api-compatibility.ts
       - name: Integration tests (${{ matrix.runtime }})
         run: docker compose run --rm test-${{ matrix.runtime }} ${{ matrix.integration_cmd }}

ARCHITECTURE.md

@@ -187,7 +187,10 @@ The facade is orchestration glue. It is not the storage engine itself.
 - **`CacheSetRegistry` and `CacheSet`** — own cache index generations,
   compare-and-swap replacement, TTL, entry and logical-byte limits,
   approximate-LRU sweeps, coalesced touches, doctor, and authoritative repair
-  under `refs/cas/caches/*`.
+  under `refs/cas/caches/*`. `CacheAcquisitionRegistry` atomically verifies a
+  selected cache generation and creates a scoped anchor under
+  `refs/cas/cache-acquisitions/*`; acquisition release is explicit,
+  idempotent, and generation-checked.
 
 - **`ExpiringSetRegistry` and `ExpiringSet`** — own digest-only replay markers
   under `refs/cas/expiring/*`. Admission is atomic, membership reads are
@@ -447,21 +450,26 @@ make objects Git-reachable, but they encode different lifecycle contracts:
 | --- | --- | --- |
 | RootSet | `refs/cas/rootsets/*` | Caller-managed current generation |
 | CacheSet | `refs/cas/caches/*` | TTL/capacity/approximate-LRU managed cache |
+| Cache acquisition | `refs/cas/cache-acquisitions/*` | Explicit caller scope over one cache generation |
 | ExpiringSet | `refs/cas/expiring/*` | Expiry-only replay protection |
 | Publication | Caller-allowlisted ref | Application-controlled causal history |
 | Vault | `refs/cas/vault` | History-preserving named assets |
 
-High-level retention, CacheSet, ExpiringSet, and application publication
-operations return generation-scoped retention evidence. Replacing a parentless
-current-generation head releases old edges when no other ref or reflog reaches
-them; Git's normal grace and pruning policy still controls physical deletion.
+High-level retention, CacheSet, cache acquisition, ExpiringSet, and application
+publication operations return generation-scoped retention evidence. Replacing
+a parentless current-generation head releases old edges when no other ref or
+reflog reaches them; Git's normal grace and pruning policy still controls
+physical deletion. A cache acquisition temporarily retains the complete
+selected generation, not only the requested target, and must be released when
+consumption ends.
 
 ### Repository Diagnostics
 
 `cas.diagnostics.doctor()` reports total, anchored, orphaned, volatile, and
-unreachable object evidence plus managed-storage summaries. Ref and reflog
-reachability defines anchored objects; volatile objects come only from safe
-prune dry-run output for the selected expiry cutoff.
+unreachable object evidence plus managed-storage summaries, including active
+cache-acquisition count and age. Ref and reflog reachability defines anchored
+objects; volatile objects come only from safe prune dry-run output for the
+selected expiry cutoff.
 
 The report names limits Git cannot prove exactly, including per-owner
 deduplicated physical bytes and packed-object age. The inspection surface has

CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Scoped cache acquisitions** — `CacheSet.acquire()` now performs a bounded,
+  reference-only lookup and atomically anchors the selected cache generation
+  for an explicit caller lifetime. Acquisitions carry separate pinned
+  retention evidence, release idempotently with a generation check, expose
+  bounded inspection and operational cleanup, and appear in repository doctor
+  with count and age evidence. Clock skew leaves structurally valid retention
+  healthy while reporting an unknown age and explicit diagnostic issue.
+  Real-Git coverage proves active acquisitions
+  survive aggressive prune without making lookup reads scale with target graph
+  size. Canonical one-segment namespace refs, symbolic-ref preflight,
+  no-dereference mutations across ordinary managed refs and acquisition refs,
+  post-conflict ref-type checks, and hard Git inventory limits preserve
+  ownership boundaries under hostile or malformed refs. Unknown ref-type
+  evidence fails doctor health closed. Acquisition capabilities remain optional
+  on the base Git ref port, the existing retention-kind and diagnostic-kind
+  unions remain unchanged, and the new doctor group is type-optional for
+  compatibility with existing consumers. Production Git checked-delete
+  conflicts fail closed because Git 2.43 cannot atomically prove that a missing
+  direct ref is not an enumerator-invisible dangling symbolic ref.
+
 ### Documentation
 
 - **v6.2.0 publication evidence** — records the signed tag identity, successful

README.md

@@ -25,7 +25,8 @@ Unlike traditional LFS which moves files to external servers, `git-cas` treats t
   without vault history retaining every prior generation.
 - **Managed Cache Sets**: Applications can store handles under
   `refs/cas/caches/*` with TTL, entry and logical-byte limits, approximate LRU
-  eviction, immutable retention evidence, bounded inspection, and repair.
+  eviction, immutable retention evidence, bounded inspection, repair, and
+  scoped acquisitions that keep a selected generation reachable during use.
   Cache indexes and object reachability remain git-cas responsibilities.
 - **Expiry-Safe Replay Sets**: Security-sensitive markers can live under
   `refs/cas/expiring/*` with atomic add-if-absent, digest-only metadata, and
@@ -43,7 +44,7 @@ Unlike traditional LFS which moves files to external servers, `git-cas` treats t
 Existing v5 users should read [UPGRADING.md](./UPGRADING.md) and run
 `npm run upgrade` in dry-run mode before restoring old encrypted vault entries.
 For the release overview, see the
-[v6.2.0 Release Notes](./docs/releases/v6.2.0.md).
+[v6.3.0 Release Notes](./docs/releases/v6.3.0.md).
 
 ### 1. CLI Usage
 
@@ -103,6 +104,7 @@ The README is the front door. Detailed mechanics live in the guide set:
 | Assets, pages, bundles, retention, and publication      | [Application storage](./docs/API.md#application-storage)     |
 | GC retention for caches and derived state               | [Root Sets](./docs/API.md#root-sets)                         |
 | Managed TTL and capacity caches                         | [Cache Sets](./docs/API.md#cache-sets)                       |
+| Scoped protection while consuming a cache hit           | [Cache acquisitions](./docs/API.md#acquire-and-release)      |
 | Durable replay markers with expiry-only release         | [Expiring Sets](./docs/API.md#expiring-sets)                 |
 | Repository reachability and git-cas usage evidence      | [Repository Diagnostics](./docs/API.md#repository-diagnostics) |
 | v5 to v6 migration                                      | [Upgrading](./UPGRADING.md)                                  |
@@ -126,6 +128,10 @@ Core capabilities:
   compare-and-swap replacement, expiry, capacity eviction, retention
   witnesses, diagnostics, and repair. Reads do not write access metadata;
   callers opt into coalesced access updates with `touch()`.
+- **Scoped cache acquisitions**: `cache.acquire()` performs a reference-only
+  lookup and atomically anchors the selected cache generation for the caller's
+  explicit lifetime. `release()` is idempotent, while inspection and checked
+  cleanup make abandoned acquisition refs observable and recoverable.
 - **Expiry-safe replay lifecycle**: `expiringSets.open()` atomically retains
   digest-only replay markers through their declared window. `contains()` is
   read-only, and `sweep()` can release only markers whose expiry has passed.
@@ -137,8 +143,9 @@ Core capabilities:
   avoid re-encrypting data blobs.
 - **Operational diagnostics**: `cas.diagnostics.doctor()` streams repository
   object/ref evidence, classifies anchored, orphaned, and volatile objects,
-  and summarizes CacheSet, RootSet, ExpiringSet, and Vault usage without
-  mutating Git. The `git-cas doctor` CLI continues to validate vault health.
+  and summarizes cache acquisitions, CacheSet, RootSet, ExpiringSet, and Vault
+  usage without mutating Git. The `git-cas doctor` CLI continues to validate
+  vault health.
 
 ## Safety Snapshot
 
@@ -186,6 +193,8 @@ All three runtimes are tested in CI on every push. The hexagonal architecture is
 - **[v6.2.0 Release Notes](./docs/releases/v6.2.0.md)**: Opaque application
   storage, managed cache and replay lifecycles, retention evidence, and
   repository diagnostics.
+- **[v6.3.0 Release Notes](./docs/releases/v6.3.0.md)**: Lifetime-safe,
+  reference-only cache acquisitions with explicit release and doctor evidence.
 - **[Upgrading](./UPGRADING.md)**: Migration guide for v5 → v6.
 - **[Changelog](./CHANGELOG.md)**: Version history and migration notes.