feat(bundles): add bounded lazy reference reads#82
Conversation
|
@codex self-code review complete.
Review scope: Evidence:
Please confirm the review posture and call out any contrary finding with file/line evidence. |
|
Warning Review limit reachedYou’ve reached a temporary PR review limit under our Fair Usage Limits Policy. Next review available in: 18 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (6)
📝 WalkthroughWalkthroughThe change adds direct bundle member-reference APIs, bounded coalescing caches for immutable Git and descriptor reads, stronger bundle traversal validation, and improved compare-and-swap conflict classification for root-set updates. Documentation, typings, unit tests, and real-Git performance tests are included. ChangesDirect bundle references
Bounded immutable-read caching
Observed root-set conflicts
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant Caller
participant ContentAddressableStore
participant BundleService
participant GitPersistenceAdapter
Caller->>ContentAddressableStore: iterateMemberReferences(options)
ContentAddressableStore->>BundleService: iterateMemberReferences(options)
BundleService->>GitPersistenceAdapter: read cached tree and object metadata
GitPersistenceAdapter-->>BundleService: coalesced immutable metadata
BundleService-->>ContentAddressableStore: direct BundleMemberReference values
ContentAddressableStore-->>Caller: async reference stream
Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/design/0050-lazy-bundle-reference-reads/witness/verification.md`:
- Around line 109-113: The verification evidence around the pre-fix Docker
stress run and repaired 500-iteration result lacks reproducible provenance. Add
a compact provenance block or exact linked records covering Docker
image/configuration, git-warp revision, Node and pnpm versions, host, fixture
parameters, and command invocations for each result, while keeping the evidence
in the durable design verification document.
In `@src/domain/services/RootSetPersistence.js`:
- Around line 56-59: Update the observed-advance comparison in the
RootSetPersistence conflict classification to compare normalized OIDs rather
than raw strings. Use Oid’s canonical lowercase representation for both
actualHeadOid and expectedHeadOid, while preserving the existing validity and
exact-update-arguments checks.
In `@src/helpers/boundedPromiseCache.js`:
- Around line 53-64: Prevent oversized resolved entries from evicting unrelated
cache contents: in the resolution flow of BoundedPromiseCache around
`#resolvedWeight` and `#totalWeight`, remove the entry immediately when its
individual weight exceeds maxWeight before adding it to the total or calling
`#evict`. In test/unit/helpers/boundedPromiseCache.test.js lines 94-105, add
coverage that caches a small resident entry and verifies it remains cached
across repeated reads of an oversized value.
In `@test/unit/helpers/boundedPromiseCache.test.js`:
- Around line 94-105: Strengthen the test for oversized values in the bounded
cache by first creating a small resident entry, then reading the oversized
value, and finally reading the resident again. In the test around
BoundedPromiseCache, use separate factories and assert the resident factory is
called only once, confirming the oversized result does not evict existing
residents.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: a673453d-cbf2-4d98-afe1-c0c2a582de9a
📒 Files selected for processing (20)
ARCHITECTURE.mdCHANGELOG.mdREADME.mddocs/API.mddocs/design/0050-lazy-bundle-reference-reads/lazy-bundle-reference-reads.mddocs/design/0050-lazy-bundle-reference-reads/witness/verification.mddocs/design/README.mdindex.d.tsindex.jssrc/domain/services/BundleService.jssrc/domain/services/RootSetPersistence.jssrc/helpers/boundedPromiseCache.jssrc/infrastructure/adapters/GitPersistenceAdapter.jstest/integration/bundle-reference-performance.test.jstest/unit/domain/services/BundleService.test.jstest/unit/domain/services/RootSetPersistence.test.jstest/unit/facade/ContentAddressableStore.application-storage.test.jstest/unit/helpers/boundedPromiseCache.test.jstest/unit/infrastructure/adapters/GitPersistenceAdapter.readTree.test.jstest/unit/types/declaration-accuracy.test.js
📜 Review details
🧰 Additional context used
📓 Path-based instructions (4)
docs/design/**
📄 CodeRabbit inference engine (AGENTS.md)
Use
docs/design/directory for durable design contracts and proof plans
Files:
docs/design/README.mddocs/design/0050-lazy-bundle-reference-reads/witness/verification.mddocs/design/0050-lazy-bundle-reference-reads/lazy-bundle-reference-reads.md
ARCHITECTURE.md
📄 CodeRabbit inference engine (AGENTS.md)
Use
ARCHITECTURE.mdas the authoritative structural reference (Facade, Domain, Ports)
Files:
ARCHITECTURE.md
README.md
📄 CodeRabbit inference engine (AGENTS.md)
Use
README.mdas the public front door, core value prop, and quick start documentation
Files:
README.md
CHANGELOG.md
📄 CodeRabbit inference engine (AGENTS.md)
Use
CHANGELOG.mdto record the historical truth of merged behavior
Files:
CHANGELOG.md
🧠 Learnings (3)
📚 Learning: 2026-02-28T19:21:13.982Z
Learnt from: flyingrobots
Repo: git-stunts/git-cas PR: 15
File: test/unit/domain/services/CasService.envelope.test.js:326-330
Timestamp: 2026-02-28T19:21:13.982Z
Learning: In fuzz tests for cryptographic operations, use a seeded PRNG (e.g., xorshift32) for control-flow variables such as plaintext size selection and recipient index selection to ensure reproducibility. Continue to use randomBytes() for cryptographic keys and nonces to preserve realistic randomness and avoid security anti-patterns. This guideline applies to test files that perform fuzz testing of crypto logic; implement a consistent seed setup (e.g., fixed seed in test initialization) and document the rationale to enable deterministic replays across runs.
Applied to files:
test/unit/types/declaration-accuracy.test.jstest/unit/facade/ContentAddressableStore.application-storage.test.jstest/unit/domain/services/BundleService.test.jstest/integration/bundle-reference-performance.test.jstest/unit/helpers/boundedPromiseCache.test.jstest/unit/infrastructure/adapters/GitPersistenceAdapter.readTree.test.jstest/unit/domain/services/RootSetPersistence.test.js
📚 Learning: 2026-03-30T19:53:48.000Z
Learnt from: flyingrobots
Repo: git-stunts/git-cas PR: 29
File: docs/design/TR-010-planning-index-consistency-review.md:121-131
Timestamp: 2026-03-30T19:53:48.000Z
Learning: In this repo, CHANGELOG.md entries should be user-facing and descriptive (bullet points) rather than cycle-ID headings (e.g., use a phrase like “Planning-index consistency review” instead of a “TR-010 — …” heading). When searching the changelog, don’t rely on grepping for cycle IDs (e.g., “TR-010”) because it may cause false negatives; search for the descriptive keywords/phrases from the bullet entries instead.
Applied to files:
CHANGELOG.md
📚 Learning: 2026-07-13T17:00:46.222Z
Learnt from: flyingrobots
Repo: git-stunts/git-cas PR: 65
File: src/domain/helpers/isCanonicalCollectionKey.js:21-35
Timestamp: 2026-07-13T17:00:46.222Z
Learning: In git-stunts/git-cas, the codebase is intended to run on multiple JavaScript runtimes (Node, Bun, and Deno), not just Node. During code review, don’t suggest replacing existing portable helper logic with newer Node-only built-ins (e.g., Node 20+ APIs like `String.prototype.isWellFormed()`) unless the change preserves Bun/Deno compatibility (via portable/polyfill implementations or safe runtime gating). If a file includes manual implementations (such as `src/domain/helpers/isCanonicalCollectionKey.js`), treat them as intentional to avoid requiring a higher host built-in baseline.
Applied to files:
src/helpers/boundedPromiseCache.jssrc/domain/services/BundleService.jssrc/infrastructure/adapters/GitPersistenceAdapter.jssrc/domain/services/RootSetPersistence.js
🪛 ast-grep (0.44.1)
test/integration/bundle-reference-performance.test.js
[warning] 9-9: Importing child_process exposes a command-execution surface; ensure any command/argument built from input is validated, and prefer execFile/spawn with an argument array over exec.
Context: import { spawnSync } from 'node:child_process';
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').
(detect-child-process)
🪛 LanguageTool
docs/design/0050-lazy-bundle-reference-reads/lazy-bundle-reference-reads.md
[style] ~315-~315: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ge reference from a resolved member? 3. Can it consume a manifest without materiali...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🔇 Additional comments (21)
test/integration/bundle-reference-performance.test.js (1)
1-152: LGTM!docs/design/0050-lazy-bundle-reference-reads/witness/verification.md (1)
1-108: LGTM!Also applies to: 115-133, 155-167
index.d.ts (1)
567-571: LGTM!Also applies to: 1463-1471, 1493-1497
index.js (1)
219-223: LGTM!Also applies to: 493-497
docs/API.md (1)
1080-1119: LGTM!docs/design/0050-lazy-bundle-reference-reads/lazy-bundle-reference-reads.md (1)
1-351: LGTM!docs/design/README.md (1)
14-14: LGTM!README.md (1)
141-142: LGTM!CHANGELOG.md (1)
10-25: LGTM!test/unit/types/declaration-accuracy.test.js (1)
124-136: LGTM!test/unit/facade/ContentAddressableStore.application-storage.test.js (1)
38-40: LGTM!src/domain/services/BundleService.js (2)
114-152: LGTM!Also applies to: 234-234, 615-619
15-15: 🎯 Functional Correctness | 🔴 Critical | ⚡ Quick winRemove the duplicate
DEFAULT_CLOCKdeclaration.Line 15 declares the same
consttwice in module scope, causing a parse-time “already been declared” error and preventing every bundle API from loading.Proposed fix
const DEFAULT_CLOCK = Object.freeze({ now: () => new Date() }); -const DEFAULT_CLOCK = Object.freeze({ now: () => new Date() });> Likely an incorrect or invalid review comment.test/unit/domain/services/BundleService.test.js (1)
266-336: LGTM!src/domain/services/RootSetPersistence.js (1)
4-4: LGTM!Also applies to: 15-55, 60-72, 276-280, 314-337
test/unit/domain/services/RootSetPersistence.test.js (1)
71-84: LGTM!Also applies to: 100-125, 217-245
src/helpers/boundedPromiseCache.js (1)
1-52: LGTM!Also applies to: 65-102
test/unit/helpers/boundedPromiseCache.test.js (1)
1-93: LGTM!Also applies to: 106-124
src/infrastructure/adapters/GitPersistenceAdapter.js (1)
7-7: LGTM!Also applies to: 19-22, 31-50, 157-165, 223-268
test/unit/infrastructure/adapters/GitPersistenceAdapter.readTree.test.js (1)
91-114: LGTM!Also applies to: 147-213
ARCHITECTURE.md (1)
377-378: LGTM!
|
@codex follow-up self-review after CodeRabbit requested changes: The initial zero-finding review missed three valid issues: non-canonical OID comparison, oversized-value cache eviction ordering, and incomplete benchmark provenance. All are now repaired; the fourth thread duplicated the cache regression request.
Evidence:
No further self-review findings remain. Please confirm the updated review posture against 3969e46. |
1 participant
Summary
getMemberReference()anditerateMemberReferences()for selected-path bundle access without recursive support-graph validationWhy
git-warp reads a small causal support slice from materialization bundles, but git-cas 6.4.0 recursively validated every nested support object. On the retained-property fixture, one selected read issued 192 Git commands and took approximately 3-5 seconds. This API gives consumers an explicit integrity/performance boundary suitable for bounded reads.
Measured impact
The stable regression contract uses Git command counts rather than host-sensitive latency thresholds.
Integrity boundary
Direct reads validate the root summary, every selected child summary, the persisted descriptor-byte budget, the direct Git edge, and the selected target's object type/existence. They intentionally do not recurse through nested target support.
[cite:
src/domain/services/BundleService.js#114-155@7ddbda5d369b4c0694b1bbf337834a7fc6e776cb][cite:
src/domain/services/BundleService.js#229-275@7ddbda5d369b4c0694b1bbf337834a7fc6e776cb]Verification
pnpm run release:verify: 14/14 steps passed; 6,619 tests observed across Node, Bun, and Denogit diff --check origin/main...HEAD: passed[cite:
src/helpers/boundedPromiseCache.js#35-101@f1d219973d40bfa8a728093d39f793c3486037ad][cite:
src/domain/services/RootSetPersistence.js#267-337@d7841acbaffbc4c5b14c78d31d3dc65ac4618cce]Closes #81.
Related upstream diagnostic-loss defect: git-stunts/plumbing#9.