v6.5.7: Reuse bounded Git sessions for small streaming reads #115

Release milestone

v6.5.7

Outcome

Small bounded payloads requested through the streaming persistence contract reuse the repository-scoped git cat-file --batch-command session. Large payloads retain the existing genuine streaming path. This removes process-per-patch startup from downstream git-warp and Think reads without changing the public API, object identity, manifests, refs, or retention policy.

Current truth

• GitPersistenceAdapter.readBlob() already uses the persistent cat-file session. [cite: src/infrastructure/adapters/GitPersistenceAdapter.js#185-223@00661b07271d8ca7166c0b62beeb1408d72a3706]
• GitPersistenceAdapter.readBlobStream() always delegates to one-shot executeStream(["cat-file", "blob", oid]). [cite: src/infrastructure/adapters/GitPersistenceAdapter.js#238-245@00661b07271d8ca7166c0b62beeb1408d72a3706]
• Asset restore prefers readBlobStream() and buffers each verified chunk before returning it. [cite: src/domain/services/ChunkRepository.js#97-167@00661b07271d8ca7166c0b62beeb1408d72a3706]
• A fresh 6.5.6 process census observed 12 repeated readBlob() calls opening one persistent session, while 12 repeated readBlobStream() calls launched 12 one-shot streams.
• Downstream git-warp #847 measured 82.9 s to 8.9 s after metadata batching but retained 1,792 Git processes for about 1,745 patch payloads: perf: batch patch-chain and git-cas object reads git-warp#847

Scope

• Add a hard-bounded small-object route through the existing persistent cat-file session.
• Preserve one-shot streaming for objects above the explicit residency bound.
• Preserve missing-object, wrong-type, buffer-limit, lifecycle, cancellation, and close behavior.
• Add deterministic unit and real-Git process-topology tests.
• Record a committed witness and consumer obligation for git-warp.
• Prepare and publish git-cas v6.5.7 before git-warp consumes it.

Out of scope

• No public API or package-export change.
• No manifest, object, ref, retention, or migration change.
• No unbounded whole-object buffering.
• No new plumbing release or general-purpose streaming session protocol.
• No git-warp or Think publication in this repository.

Slices

• Write cycle design and RED process-topology tests.
• Implement the bounded hybrid adapter path.
• Prove unit, real-Git, Node/Bun/Deno, lint, package, and JSR gates.
• Merge the implementation, then cut and publish v6.5.7.

Design doc

docs/design/0058-bounded-stream-session-reads/bounded-stream-session-reads.md

Required proof

• Repeated small readBlobStream() calls use one persistent cat-file child, not one child per blob.
• An object above the configured bound remains on the streamed one-shot path and is not buffered.
• Content, chunk integrity, SHA-1/SHA-256 behavior, and error contracts remain identical.
• Adapter close leaves no active session or stream.
• Full release verification passes across Node, Bun, and Deno.

Release gate impact

This is an externally meaningful performance correction and requires a v6.5.7 changelog/release note, durable process-count witness, full release verification, npm provenance, signed tag, and downstream git-warp consumer checkpoint.