Outcome
Structured bundle consumers can inspect direct member references without recursively validating every nested support graph, while complete validation remains explicit and unchanged. Repeated reads of immutable bundle metadata are coalesced through a fixed-memory git-cas-owned cache so targeted reads do not spawn one Git process per repeated edge/descriptor lookup.
Why this is urgent
A real git-warp retained-property benchmark on a four-node fixture currently performs 192 Git commands for one exact read under @git-stunts/git-cas@6.4.0:
- 79
ls-tree
- 103
cat-file
- 10 ref/history commands
- approximately 3–5 seconds wall time
- zero graph replay
- no whole-state materialization
A controlled A/B changed only materialization-manifest iteration from complete target validation to git-cas's existing internal direct-edge iterator. The same read fell to 92 Git commands and 1.44 seconds, with identical output, zero replay, and no whole-state cache. This proves eager recursive target validation accounts for roughly half the hot-path cost, while repeated immutable metadata reads account for much of the remainder.
Current contract
iterateMembers() intentionally validates every member support graph and must retain that behavior. [cite: docs/API.md#1107-1118@b6cd2b3f]- git-cas already has internal
getMemberReference() and iterateMemberReferences() primitives that validate bundle structure and direct Git edges without recursively resolving targets. [cite: src/domain/services/BundleService.js#102-130@b6cd2b3f] [cite: src/domain/services/BundleService.js#204-230@b6cd2b3f]
GitPersistenceAdapter.readTreeEntry() currently executes a new git ls-tree for every edge lookup, including repeated lookups in the same immutable tree. [cite: src/infrastructure/adapters/GitPersistenceAdapter.js#141-154@b6cd2b3f]readObjectType() and readObjectSize() independently invoke object-info reads even when the same immutable OID was just inspected. [cite: src/infrastructure/adapters/GitPersistenceAdapter.js#185-215@b6cd2b3f]
Required design
- Add a public, explicitly named
BundleMemberReference API for targeted and streamed direct-edge inspection.
- Preserve
getMember(), iterateMembers(), openMember(), and resolveRoot() complete-validation semantics.
- Document that a member reference proves bundle structure plus the direct Git edge, while target contents/support are validated when dereferenced or by complete-validation APIs.
- Coalesce repeated immutable tree/object-info/descriptor reads inside git-cas with a fixed residency bound; no unbounded process-lifetime map.
- Keep corruption detection fail-closed and preserve all existing safety limits.
- Add real-Git command-count tests for direct-reference lookup, repeated lookup, and full validation.
- Publish before git-warp adopts the capability.
Acceptance proof
- Direct-reference manifest iteration does not recursively walk nested member graphs.
- Repeated targeted reads use bounded memory and materially reduce
ls-tree / cat-file process count.
- Full
iterateMembers() still detects nested corruption.
- Unit, integration, declaration-accuracy, docs, lint, and package checks pass.
- Before/after command counts and wall/CPU measurements are attached to the PR.
Outcome
Structured bundle consumers can inspect direct member references without recursively validating every nested support graph, while complete validation remains explicit and unchanged. Repeated reads of immutable bundle metadata are coalesced through a fixed-memory git-cas-owned cache so targeted reads do not spawn one Git process per repeated edge/descriptor lookup.
Why this is urgent
A real git-warp retained-property benchmark on a four-node fixture currently performs 192 Git commands for one exact read under
@git-stunts/git-cas@6.4.0:ls-treecat-fileA controlled A/B changed only materialization-manifest iteration from complete target validation to git-cas's existing internal direct-edge iterator. The same read fell to 92 Git commands and 1.44 seconds, with identical output, zero replay, and no whole-state cache. This proves eager recursive target validation accounts for roughly half the hot-path cost, while repeated immutable metadata reads account for much of the remainder.
Current contract
iterateMembers()intentionally validates every member support graph and must retain that behavior. [cite:docs/API.md#1107-1118@b6cd2b3f]getMemberReference()anditerateMemberReferences()primitives that validate bundle structure and direct Git edges without recursively resolving targets. [cite:src/domain/services/BundleService.js#102-130@b6cd2b3f] [cite:src/domain/services/BundleService.js#204-230@b6cd2b3f]GitPersistenceAdapter.readTreeEntry()currently executes a newgit ls-treefor every edge lookup, including repeated lookups in the same immutable tree. [cite:src/infrastructure/adapters/GitPersistenceAdapter.js#141-154@b6cd2b3f]readObjectType()andreadObjectSize()independently invoke object-info reads even when the same immutable OID was just inspected. [cite:src/infrastructure/adapters/GitPersistenceAdapter.js#185-215@b6cd2b3f]Required design
BundleMemberReferenceAPI for targeted and streamed direct-edge inspection.getMember(),iterateMembers(),openMember(), andresolveRoot()complete-validation semantics.Acceptance proof
ls-tree/cat-fileprocess count.iterateMembers()still detects nested corruption.