Problem
@git-stunts/plumbing currently models every Git invocation as a one-shot command: stdin is closed immediately and consumers receive stdout plus process completion. That contract forces callers performing repeated object reads, tree writes, or bulk imports to spawn one Git process per operation.
The git-warp access spike in git-stunts/git-warp#763 found that stock Git's long-lived protocols (cat-file --batch-command, mktree --batch, and fast-import) preserve the required Git semantics while removing the dominant process/setup overhead. The plumbing package should expose the process/session primitive needed to use those protocols without replacing its existing one-shot runner API.
Proposed contract
Add an optional, additive duplex session port:
CommandSessionRunner.open(options) -> CommandSession
CommandSession
stdout: AsyncIterable<Uint8Array>
finished: Promise<exit result>
write(bytes): Promise<void>
closeInput(): void
terminate(): void
The built-in Node, Bun, and Deno adapters should implement the port. Existing custom one-shot runners must remain source- and behavior-compatible; requesting a session from a runner that does not support sessions must fail with a structured unsupported-capability error.
Expose low-level protocol session constructors for stock Git. Protocol framing/parsing may be factored into focused wrappers for:
git cat-file --batch-commandgit mktree --batchgit fast-import
Ownership boundary
Plumbing owns:
- child-process lifecycle;
- stdin backpressure and early-termination errors;
- bounded stderr and process completion;
- timeout and abort behavior;
- raw Git protocol mechanics.
Plumbing does not own:
- session reuse policy;
- object retention or anchoring;
- cache admission, eviction, or materialization policy;
- git-cas workspace/checkpoint semantics.
Those policies belong to @git-stunts/git-cas and its callers.
Acceptance criteria
Evidence
The benchmark design and results are in git-stunts/git-warp#763 and docs/topics/git-perf.md in that PR.
Problem
@git-stunts/plumbingcurrently models every Git invocation as a one-shot command: stdin is closed immediately and consumers receive stdout plus process completion. That contract forces callers performing repeated object reads, tree writes, or bulk imports to spawn one Git process per operation.The git-warp access spike in git-stunts/git-warp#763 found that stock Git's long-lived protocols (
cat-file --batch-command,mktree --batch, andfast-import) preserve the required Git semantics while removing the dominant process/setup overhead. The plumbing package should expose the process/session primitive needed to use those protocols without replacing its existing one-shot runner API.Proposed contract
Add an optional, additive duplex session port:
The built-in Node, Bun, and Deno adapters should implement the port. Existing custom one-shot runners must remain source- and behavior-compatible; requesting a session from a runner that does not support sessions must fail with a structured unsupported-capability error.
Expose low-level protocol session constructors for stock Git. Protocol framing/parsing may be factored into focused wrappers for:
git cat-file --batch-commandgit mktree --batchgit fast-importOwnership boundary
Plumbing owns:
Plumbing does not own:
Those policies belong to
@git-stunts/git-casand its callers.Acceptance criteria
executeandexecuteStreambehavior remains compatible.write()honors stream backpressure and rejects after closure/failure.finishedsettles exactly once for success, spawn failure, timeout, abort, and early exit.Evidence
The benchmark design and results are in git-stunts/git-warp#763 and
docs/topics/git-perf.mdin that PR.