Fix recursive tree OID read fanout and release v17.0.1

[flyingrobots]

Summary

• Replace recursive git-cas one-level tree walking with a dedicated one-shot git ls-tree -rz reader for recursive tree OID maps.
• Keep blob reads on git-cas readBlobStream() while preserving git-warp's path-to-OID contract.
• Prepare v17.0.1 release metadata and align the release policy ratchet/roadmap.

Profiling Evidence

• Before: codex-think --remember --brief --limit=1 --json --verbose was ~69s, with recursive checkpoint tree reads doing ~1,200+ nested ls-tree stream setups per open/materialize pass.
• After: the same CLI path is ~34s locally; instrumented Think read shows two ls-tree -rz calls totaling ~87ms.
• Remaining Think cost is outside the tree-walk fanout: ~9.7s materialization and ~11.5s from listRecentStoredEntries(limit: 2000).

Test plan

• npm run lint
• npm run typecheck
• npm run test:local
• npm run test:coverage:ci
• npm run release:preflight
• pre-push Ironclad M9 gates

ADR checks

• This PR does not implement ADR 2 without satisfying ADR 3.
• This PR does not touch persisted op formats; no ADR 3 readiness issue is required.
• This PR does not touch wire compatibility; canonical-only op rejection is unchanged.
• This PR does not touch schema constants; patch and checkpoint namespaces remain distinct.

[coderabbitai]

Warning

Rate limit exceeded

@flyingrobots has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 15 minutes and 42 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6ddb3e86-e4a9-4bfa-abf9-74f29a5935f4

📥 Commits

Reviewing files that changed from the base of the PR and between c495654 and a085efd.

📒 Files selected for processing (14)

• CHANGELOG.md
• docs/design/0150-path-keyed-boundary-accumulator-audit/path-keyed-boundary-accumulator-audit.md
• docs/design/0151-safe-path-map-materialization/safe-path-map-materialization.md
• docs/design/0152-review-bot-warning-policy/review-bot-warning-policy.md
• docs/design/0153-recursive-tree-path-benchmark/recursive-tree-path-benchmark.md
• docs/method/backlog/DX_review-bot-warning-policy.md
• docs/method/backlog/PERF_recursive-tree-path-benchmark.md
• docs/method/backlog/README.md
• docs/method/backlog/bad-code/BND_path-keyed-object-accumulators.md
• docs/method/backlog/bad-code/README.md
• docs/method/backlog/bad-code/RELEASE_TRIAGE.md
• docs/method/backlog/cool-ideas/PROTO_safe-path-map-materialization.md
• src/infrastructure/adapters/GitRecursiveTreeOidReaderAdapter.ts
• test/unit/infrastructure/adapters/GitGraphAdapter.coverage.test.ts

📝 Walkthrough

Walkthrough

This PR optimizes recursive Git tree OID reads by introducing a dedicated GitRecursiveTreeOidReaderAdapter that executes a single git ls-tree -rz command instead of iterating through one-level tree reads. The adapter is wired into GitGraphAdapter via GitCasGraphReaderAdapter delegation, test coverage is updated to verify single-call execution patterns, architectural decisions are documented in parity specs, and the package is released as v17.0.1.

Changes

Recursive tree OID optimization via single git ls-tree call

Layer / File(s)	Summary
Recursive tree OID reader adapter implementation src/infrastructure/adapters/GitRecursiveTreeOidReaderAdapter.ts	New GitRecursiveTreeOidReaderAdapter executes git ls-tree -rz <treeOid> with retry, parses null-separated output into path→OID records, filters out tree entries, validates each entry's metadata and path, and wraps parse/execution errors with Git classification and context.
Adapter refactoring and wiring src/infrastructure/adapters/GitCasGraphReaderAdapter.ts, src/infrastructure/adapters/GitGraphAdapter.ts	GitCasGraphReaderAdapter accepts injected treeOidReader and delegates readTreeOids() to it. GitGraphAdapter instantiates GitRecursiveTreeOidReaderAdapter and injects it into GitCasGraphReaderAdapter during construction, replacing internal recursive traversal.
Test coverage for single-call execution test/unit/infrastructure/adapters/GitGraphAdapter.coverage.test.ts, test/unit/infrastructure/adapters/GitGraphAdapter.gitCasPersistence.test.ts	readTree() and readTreeOids() tests updated to stub execute for ls-tree -rz output; assertions verify single execute calls and no/reduced executeStream usage. Nested-tree and malformed-entry scenarios updated. Parity tests verify GitRecursiveTreeOidReaderAdapter wiring and usage patterns.
Git-cas adapter parity documentation and validation docs/method/backlog/v17.0.0/INFRA_git-cas-adapter-parity.md, test/unit/scripts/uniform-git-cas-closeout.test.ts	Parity doc clarifies git-cas one-level APIs are not equivalent to git-warp recursive reads due to process fan-out; describes delegation through GitRecursiveTreeOidReaderAdapter using single recursive git ls-tree -rz to maintain path contract. Test assertions verify documentation mentions the new adapter and single ls-tree -rz call.
Release versioning and metadata CHANGELOG.md, docs/ROADMAP.md, package.json, jsr.json, test/unit/scripts/release-policy-shape.test.ts	Package version bumped to 17.0.1. CHANGELOG documents the recursive tree OID optimization under Fixed. Roadmap updated to current v17.0.1 and next v18.0.0 with reconciliation date and notes. Release-policy tests updated to assert version 17.0.1 and roadmap metadata.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• git-stunts/git-warp#85: Both PRs modify the recursive tree OID read code path in GitGraphAdapter and readTreeOids behavior, with overlapping integration at the same tree-OID scanning checkpoint.

Poem

🐰 A single command leaps where many steps once trod,
ls-tree -rz gathers all the paths with one swift nod,
No more recursive fanning—just one call to Git's goad,
The checkpoint opens faster on this optimized road! 🚀✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately captures the main change: fixing the recursive tree OID read fanout issue and releasing v17.0.1, which aligns with the changeset's primary objective.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The pull request description includes all required template sections with comprehensive detail: Summary, Test plan, and all four ADR checks completed.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/v17-recursive-tree-read

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[flyingrobots]

@codex Self-review complete against origin/main after clean worktree check and git fetch --all --prune.

Severity	Count	Summary
Critical	0	No correctness, data-loss, release-blocking, or CI-blocking defects found.
Major	0	No semantic regression found in recursive tree OID reads or release metadata.
Minor	0	No maintainability issues requiring branch changes found.
Nit	0	No Markdown, whitespace, or style violations found in the reviewed diff.

Reviewed diff: origin/main...HEAD. The new GitRecursiveTreeOidReaderAdapter keeps readTreeOids() recursive/path-preserving with a single git ls-tree -rz call, preserves retry/error wrapping, and covers malformed record branches through adapter tests. Release metadata is aligned for 17.0.1, and local release preflight passed before this review.

No mitigation prompts are required because there are no unresolved self-review findings.

[github-actions]

Release Preflight

• package version: 17.0.1
• prerelease: false
• npm dist-tag on release: latest
• npm pack dry-run: passed
• jsr publish dry-run: passed

If you tag this commit as v17.0.1, release workflow will publish.

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@src/infrastructure/adapters/GitRecursiveTreeOidReaderAdapter.ts`:
- Around line 56-64: The oids accumulator in parseRecursiveTreeOidOutput is
created as a plain object (oids = {}) and can be poisoned by git paths like
"__proto__" or "constructor"; change oids to a null-prototype map (e.g., const
oids = Object.create(null)) or use a Map to safely store oids[entry.path] for
non-tree entries; update references in the same function (where you assign
oids[entry.path] = entry.oid and later read from oids) and keep
parseRecursiveTreeEntry and TREE_OBJECT_TYPE logic unchanged.

🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1f2921e1-cee1-4828-94ca-b5e68fa818f4

📥 Commits

Reviewing files that changed from the base of the PR and between 6d4a0d6 and c495654.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (12)

• CHANGELOG.md
• docs/ROADMAP.md
• docs/method/backlog/v17.0.0/INFRA_git-cas-adapter-parity.md
• jsr.json
• package.json
• src/infrastructure/adapters/GitCasGraphReaderAdapter.ts
• src/infrastructure/adapters/GitGraphAdapter.ts
• src/infrastructure/adapters/GitRecursiveTreeOidReaderAdapter.ts
• test/unit/infrastructure/adapters/GitGraphAdapter.coverage.test.ts
• test/unit/infrastructure/adapters/GitGraphAdapter.gitCasPersistence.test.ts
• test/unit/scripts/release-policy-shape.test.ts
• test/unit/scripts/uniform-git-cas-closeout.test.ts

[flyingrobots]

Feedback Resolution Summary

Issue	Source	Severity	Resolution	SHA
Prototype-like Git path names in recursive tree OID accumulator	CodeRabbit inline thread	Major	Reproduced with a RED test, switched the accumulator to Map<string, string>, and covered __proto__/constructor paths.	00cb0403
Release note for the feedback fix	Processor cleanup	Docs	Updated the 17.0.1 CHANGELOG entry to mention prototype-like Git path names.	74111785

Verification: targeted adapter tests, npm run lint, npm run typecheck, npm run release:preflight, and pre-push Ironclad M9 gates all passed.

[github-actions]

Release Preflight

• package version: 17.0.1
• prerelease: false
• npm dist-tag on release: latest
• npm pack dry-run: passed
• jsr publish dry-run: passed

If you tag this commit as v17.0.1, release workflow will publish.

[flyingrobots]

@coderabbitai Follow-up on the pre-merge warnings in the summary comment:

Warning	Outcome	Evidence
Description check missing ## ADR checks	Addressed in PR metadata	The PR body now includes the repository template's ## ADR checks section with the four required confirmations.
Docstring Coverage 0.00% below 80.00%	Treated as a false positive for this repository	package.json has no docstring/Typedoc coverage gate, .github/workflows/ci.yml enforces test coverage rather than docstring coverage, and all required PR checks are green. Adding docstring churn is not aligned with the local TypeScript style gates for this branch.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@flyingrobots: Both follow-ups are well-evidenced — thank you for the clear triage.

1. ## ADR checks section — Confirmed resolved. With the four required confirmations now in the PR body, that warning is fully addressed.

2. Docstring Coverage 0.00% — Agreed, treating this as a false positive is the correct call. Since the CI pipeline gates on test coverage rather than docstring/TypeDoc coverage and no such threshold exists in package.json or the workflow, the warning was noise from the summary heuristic rather than a real enforcement signal. No action needed on the branch.

Everything looks clean for merge. 🐇✨

[github-actions]

Release Preflight

• package version: 17.0.1
• prerelease: false
• npm dist-tag on release: latest
• npm pack dry-run: passed
• jsr publish dry-run: passed

If you tag this commit as v17.0.1, release workflow will publish.