perf: reuse bounded Git object sessions

[flyingrobots]

Problem

git-cas currently starts a fresh Git process for each blob read, exact tree lookup, blob write, and tree write. The immutable caches added in v6.5.0 and v6.5.1 remove repeated work only after a cache hit; cold bounded reads and incremental materialization still pay process startup for every distinct support object.

@git-stunts/plumbing v3.2.0 now provides typed long-lived cat-file, mktree, and fast-import sessions. git-cas must own those sessions behind its persistence adapter, preserve bounded residency, and close them deterministically.

Required invariants

• git-cas owns process reuse; callers receive no raw session or mutable Git authority.
• Object content remains immutable by OID and ref reads remain uncached.
• Tree-object reuse is bounded by both entry count and estimated bytes.
• Streaming payload APIs remain streaming and do not become whole-object materialization.
• Session failure cannot poison later operations silently.
• Close is explicit, idempotent, waits for active operations, and releases local child processes only.
• Adapters without the new plumbing capability retain the existing command-per-operation fallback.

Scope

• Upgrade to @git-stunts/plumbing 3.2.0.
• Add lazy typed session ownership to GitPersistenceAdapter.
• Route bounded blob/object metadata reads, tree-object reads, blob writes, and tree writes through reusable protocols where lawful.
• Add exact path lookup over bounded immutable tree objects without materializing application graphs.
• Add ContentAddressableStore.close() and async-disposal support.
• Publish command-count, wall-time, and bounded-memory evidence.
• Update architecture, API, changelog, release, witness, and retro records.

Acceptance criteria

• A cold selected bundle read uses O(1) Git child processes for session-capable object protocols rather than one process per support object.
• Repeated exact lookups of the same immutable tree hit a count-and-byte-bounded cache.
• Large payload restore still uses readBlobStream() and obeys existing memory limits.
• Concurrent calls share serialized protocol sessions safely.
• Session errors are surfaced, invalidated, and retryable through a fresh session when lawful.
• close() is idempotent and no Git child remains after it resolves.
• Node, Bun, and Deno tests pass.
• Stable real-Git performance tests gate command/process regressions.
• v6.5.2 is published to npm before git-warp adopts it.

Non-goals

• Implementing Git object storage or packfile logic.
• Caching refs or mutable collection metadata.
• Moving cache ownership into git-warp.
• Completing path-local persistent bundle derivation tracked by design: path-local persistent bundle derivation #86.
• Replacing @git-stunts/plumbing or stock Git.

Downstream

This unblocks the git-warp v19 materialization path and its CPU plus larger-than-memory benchmark gates.

[coderabbitai]

🔗 Related PRs

#63 - Add structured bundle and page storage [merged]
#64 - Add managed CacheSet lifecycle [merged]
#73 - release: prepare git-cas v6.3.0 [merged]
#82 - feat(bundles): add bounded lazy reference reads [merged]
#83 - release: prepare git-cas v6.5.0 [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]

Completion evidence

All acceptance criteria are now implemented, regression-gated, reviewed, and published.

• GitPersistenceAdapter owns lazy typed sessions, count-and-byte-bounded immutable caches, and capability-detected fallbacks without exposing raw Git authority. [cite: src/infrastructure/adapters/GitPersistenceAdapter.js#41-81@fb3d3c2b620bae11d52e8ecc7a78a7ea07f27e24] [cite: src/infrastructure/adapters/GitPersistenceAdapter.js#89-179@fb3d3c2b620bae11d52e8ecc7a78a7ea07f27e24]
• Bounded metadata/blob/tree reads use persistent protocols when available, exact tree lookup reuses bounded immutable tree objects, and payload streaming remains on executeStream rather than becoming a whole-object session read. [cite: src/infrastructure/adapters/GitPersistenceAdapter.js#187-307@fb3d3c2b620bae11d52e8ecc7a78a7ea07f27e24] [cite: test/unit/infrastructure/adapters/GitPersistenceAdapter.sessions.test.js#201-309@fb3d3c2b620bae11d52e8ecc7a78a7ea07f27e24]
• The pool coalesces one session per protocol, serializes retirement/invalidation, retries once only after lawful teardown, and surfaces poisoned or aggregate failures instead of silently reusing a broken process. [cite: src/infrastructure/adapters/GitObjectSessionPool.js#17-70@fb3d3c2b620bae11d52e8ecc7a78a7ea07f27e24] [cite: src/infrastructure/adapters/GitObjectSessionPool.js#120-241@fb3d3c2b620bae11d52e8ecc7a78a7ea07f27e24] [cite: src/infrastructure/adapters/GitObjectSessionPool.js#244-316@fb3d3c2b620bae11d52e8ecc7a78a7ea07f27e24]
• Explicit close is idempotent, drains active operations and streams, closes or terminates children, clears bounded residency, and is exposed by the root facade as local-resource release only. [cite: src/infrastructure/adapters/GitPersistenceAdapter.js#499-569@fb3d3c2b620bae11d52e8ecc7a78a7ea07f27e24] [cite: index.js#615-638@fb3d3c2b620bae11d52e8ecc7a78a7ea07f27e24] [cite: test/unit/infrastructure/adapters/GitPersistenceAdapter.sessions.test.js#524-769@fb3d3c2b620bae11d52e8ecc7a78a7ea07f27e24]
• Stable real-Git gates require semantic equality, exactly one persistent cat-file process for selected reads, exactly one scoped fast-import process for bounded page batches, and fewer total processes than fallback. [cite: test/integration/bundle-reference-performance.test.js#166-218@fb3d3c2b620bae11d52e8ecc7a78a7ea07f27e24]
• The committed diagnostic and witness publish reproducible wall-time, process-count, worker CPU, and worker peak-RSS observations. The bounded git-cas claim is explicit; graph-wide/process-tree memory remains correctly assigned to downstream git-warp #758. [cite: scripts/diagnostics/measure-git-object-sessions.js#142-260@fb3d3c2b620bae11d52e8ecc7a78a7ea07f27e24] [cite: docs/design/0052-persistent-git-object-sessions/witness/verification.md#109-187@fb3d3c2b620bae11d52e8ecc7a78a7ea07f27e24]
• v6.5.2 is signed, passed the complete Node/Bun/Deno release workflow, is published to npm as latest with SLSA provenance, and has a final GitHub Release. [cite: docs/design/0052-persistent-git-object-sessions/witness/release-publication.md#7-61@fb3d3c2b620bae11d52e8ecc7a78a7ea07f27e24]

The remaining work is downstream adoption and end-to-end git-warp proof, not unfinished git-cas scope. Closing as completed.