Fix recursive tree OID read fanout and release v17.0.1

CHANGELOG.md

@@ -7,8 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [17.0.1] — 2026-05-22
+
 ### Fixed
 
+- Recursive Git tree OID reads now use one `git ls-tree -rz` call instead
+  of recursing through one-level tree iteration, restoring checkpoint-open
+  latency for Think-scale tree indexes while preserving git-warp's recursive
+  path-to-OID map contract, including prototype-like Git path names.
 - Continuum artifact ingestion now enforces artifact-kind/authority pairing at
   the domain policy layer, keeps review fixtures repo-neutral, and splits the
   JSON adapter into focused parser, validation, fixture, and Wesley inventory

docs/ROADMAP.md

@@ -4,9 +4,9 @@
 > See METHOD for the current process.
 > Completed items remain in `docs/ROADMAP/COMPLETED.md`. This file is kept for reference only.
 
-> **Current release on `main`:** v16.0.0
-> **Next intended release:** v16.0.1
-> **Last reconciled:** 2026-03-29 (v16.0.0 release. OG-014 streaming CAS blob storage, OG-015 JSR docs, deprecated TraversalService and createWriter removed.)
+> **Current release on `main`:** v17.0.1
+> **Next intended release:** v18.0.0
+> **Last reconciled:** 2026-05-22 (v17.0.1 patch. Recursive tree OID reads use one path-preserving Git command; v17.0.0 release delivered readings/worldlines, TypeScript source, and the generated npm type surface.)
 > **Completed milestones:** [docs/ROADMAP/COMPLETED.md](ROADMAP/COMPLETED.md)
 
 ---

docs/design/0150-path-keyed-boundary-accumulator-audit/path-keyed-boundary-accumulator-audit.md

@@ -0,0 +1,77 @@
+---
+cycle: 0150
+task_id: BND_path_keyed_boundary_accumulator_audit
+status: Planned
+sponsors:
+  human: James
+  agent: Codex
+started_at: 2026-05-22
+release_home: v18.0.0
+backlog:
+  - docs/method/backlog/bad-code/BND_path-keyed-object-accumulators.md
+---
+
+# Path-Keyed Boundary Accumulator Audit
+
+## Pull
+
+PR #93 fixed one concrete instance of a path-keyed plain object
+accumulator in recursive tree OID parsing. The finding is broader than
+that file: repository paths, transport field names, and generated
+artifact identifiers are untrusted data until a boundary has validated
+them.
+
+## Hill
+
+Every touched path-keyed accumulator at Git or transport boundaries
+uses a runtime-honest intermediate representation before exposing any
+record-shaped API.
+
+## Playback Questions
+
+- Which adapters accept path-like or identifier-like strings from Git,
+  transport, generated artifacts, or file input?
+- Which of those adapters write untrusted keys into plain objects before
+  validation?
+- Does each corrected site prove prototype-like keys are preserved as
+  data?
+- Does the public API shape stay stable where callers already expect a
+  record?
+
+## Design
+
+1. Inventory boundary files under `src/infrastructure/adapters/`,
+   transport codecs, and generated-artifact ingestion seams.
+2. Mark each path-keyed accumulator as safe, unsafe, or intentionally
+   record-shaped after validation.
+3. For unsafe sites, accumulate in `Map` or another typed runtime
+   collection before final materialization.
+4. Add focused tests for `__proto__`, `constructor`, and nested path
+   examples at each repaired boundary.
+
+## Non-Goals
+
+- Do not replace stable public record APIs solely for aesthetic reasons.
+- Do not create a generic helper before at least two real call sites
+  justify one.
+- Do not move parsing behavior into domain code.
+
+## Verification
+
+- Targeted tests for each repaired boundary.
+- `npm run lint`
+- `npm run typecheck`
+- `npm run test:local`
+
+## SSJS Scorecard
+
+- Runtime-backed forms: planned; untrusted key collections use real
+  runtime collections before record materialization.
+- Boundary validation: planned; validation remains in adapters and
+  parser seams.
+- Behavior ownership: planned; each boundary owns its own input shape.
+- Message parsing: green; no behavior depends on free-form messages.
+- Ambient time or entropy: green; no time or entropy is involved.
+- Fake shape trust or cast-cosplay: planned; no casts should be needed
+  for accumulator safety.
+

docs/design/0151-safe-path-map-materialization/safe-path-map-materialization.md

@@ -0,0 +1,72 @@
+---
+cycle: 0151
+task_id: PROTO_safe_path_map_materialization
+status: Planned
+sponsors:
+  human: James
+  agent: Codex
+started_at: 2026-05-22
+release_home: v18.0.0
+backlog:
+  - docs/method/backlog/cool-ideas/PROTO_safe-path-map-materialization.md
+---
+
+# Safe Path-Map Materialization
+
+## Pull
+
+The recursive tree OID parser now uses `Map<string, string>` before
+returning a public record. That pattern should be deliberate rather
+than rediscovered during each review.
+
+## Hill
+
+The repo has a documented pattern for path-keyed materialization that
+preserves existing record-shaped APIs without trusting untrusted keys as
+object structure.
+
+## Playback Questions
+
+- When is `Map` the right intermediate representation?
+- When is a null-prototype object acceptable?
+- Where should validation happen before materializing a public record?
+- What test cases prove the materialization is not prototype-sensitive?
+
+## Design
+
+The default pattern is:
+
+1. Parse or collect untrusted path-like inputs into `Map`.
+2. Validate each key and value as boundary data.
+3. Convert to a public record only at the adapter edge that already
+   promises a record.
+4. Test prototype-like keys and normal nested paths together.
+
+If repeated call sites appear, introduce a named helper with a narrow
+type signature and no `any`, `unknown`, or cast-cosplay. Until then,
+prefer local code that keeps each boundary easy to read.
+
+## Non-Goals
+
+- Do not introduce a universal collection abstraction.
+- Do not widen public APIs to `Map` without a separate compatibility
+  decision.
+- Do not normalize or reject valid Git path names merely because they
+  are awkward object keys.
+
+## Verification
+
+- Markdown docs lint for the pattern doc.
+- Focused unit tests if a helper is introduced.
+- Typecheck if any helper lands.
+
+## SSJS Scorecard
+
+- Runtime-backed forms: planned; `Map` is the explicit runtime form.
+- Boundary validation: planned; validation remains at the boundary.
+- Behavior ownership: green; materialization belongs to adapter edges.
+- Message parsing: green.
+- Ambient time or entropy: green.
+- Fake shape trust or cast-cosplay: planned; helper design must not
+  require casts.
+

docs/design/0152-review-bot-warning-policy/review-bot-warning-policy.md

@@ -0,0 +1,71 @@
+---
+cycle: 0152
+task_id: DX_review_bot_warning_policy
+status: Planned
+sponsors:
+  human: James
+  agent: Codex
+started_at: 2026-05-22
+release_home: v18.0.0
+backlog:
+  - docs/method/backlog/DX_review-bot-warning-policy.md
+---
+
+# Review Bot Warning Policy
+
+## Pull
+
+PR review bots can produce both useful findings and generic warnings.
+PR #93 had both: the prototype-like path issue was valid, while the
+docstring coverage warning did not map to this repository's gates.
+
+## Hill
+
+Contributors have a repo-visible rule for classifying review-bot
+warnings as required work, false positives, or backlog fuel.
+
+## Playback Questions
+
+- Does the warning map to a repository script, CI check, policy doc, or
+  product contract?
+- If the warning is valid, what RED test or failing gate proves it?
+- If the warning is false, what local evidence proves that answer?
+- If the warning is not a merge blocker but still useful, where does it
+  enter the backlog?
+
+## Design
+
+Add a contributor-facing review policy that requires:
+
+1. Verify the warning against current code.
+2. Search local scripts, workflows, and policy docs for an owning gate.
+3. Fix valid issues with RED/GREEN, docs, and commit evidence.
+4. Reply to false positives with file, command, and CI evidence.
+5. Convert useful but non-blocking warnings into backlog notes with a
+   design link.
+
+## Non-Goals
+
+- Do not turn generic bot suggestions into automatic policy.
+- Do not silence review bots globally.
+- Do not add documentation churn when no repo rule asks for it.
+
+## Verification
+
+- The policy doc links to the existing PR template and review hygiene
+  guidance.
+- Markdown lint passes.
+- A future PR feedback loop can cite the policy instead of relying on
+  chat-only precedent.
+
+## SSJS Scorecard
+
+- Runtime-backed forms: not applicable; docs/process slice.
+- Boundary validation: green; process requires local evidence before
+  adopting external warnings.
+- Behavior ownership: green; repo gates own repo policy.
+- Message parsing: green; bot text is evidence to verify, not authority.
+- Ambient time or entropy: green.
+- Fake shape trust or cast-cosplay: green; false positives require
+  inspectable proof.
+

docs/design/0153-recursive-tree-path-benchmark/recursive-tree-path-benchmark.md

@@ -0,0 +1,74 @@
+---
+cycle: 0153
+task_id: PERF_recursive_tree_path_benchmark
+status: Planned
+sponsors:
+  human: James
+  agent: Codex
+started_at: 2026-05-22
+release_home: v18.0.0
+backlog:
+  - docs/method/backlog/PERF_recursive-tree-path-benchmark.md
+---
+
+# Recursive Tree Path Benchmark
+
+## Pull
+
+The v17.0.1 release fix proved that recursive tree OID reads should use
+one `git ls-tree -rz` call. The next useful performance proof is a
+repeatable fixture that mixes depth, width, and awkward but valid path
+names.
+
+## Hill
+
+Recursive tree OID reading has a benchmark or regression fixture that
+proves single-command behavior and path integrity for deep, wide, and
+prototype-like path names.
+
+## Playback Questions
+
+- Does the reader still issue one recursive tree command for a large
+  fixture?
+- Are nested paths preserved exactly?
+- Are `__proto__` and `constructor` paths returned as data?
+- Does the fixture fail if recursive one-level fanout comes back?
+
+## Design
+
+Build a deterministic fixture with:
+
+- a deep path chain;
+- a wide sibling set;
+- prototype-like path segments;
+- enough entries to make process fanout visible.
+
+The test should count command invocations at the adapter seam and assert
+the returned path/OID map. If promoted to a benchmark, record the
+baseline command count and wall-clock envelope without making noisy
+timing a unit-test gate.
+
+## Non-Goals
+
+- Do not require a live external repository.
+- Do not make wall-clock timing the only correctness signal.
+- Do not broaden the recursive reader API.
+
+## Verification
+
+- Targeted adapter test or benchmark fixture.
+- `npm run test:local` if the fixture is a unit test.
+- `npm run benchmark:local` if it becomes a benchmark.
+
+## SSJS Scorecard
+
+- Runtime-backed forms: green; no new domain model is required.
+- Boundary validation: planned; fixture exercises adapter parsing only.
+- Behavior ownership: green; recursive tree command behavior belongs to
+  the Git adapter.
+- Message parsing: green; command output stays parser-owned.
+- Ambient time or entropy: green for deterministic tests; benchmark
+  timing is advisory only.
+- Fake shape trust or cast-cosplay: green; assertions inspect returned
+  path/OID data.
+

docs/method/backlog/DX_review-bot-warning-policy.md

@@ -0,0 +1,32 @@
+---
+id: DX_review-bot-warning-policy
+feature: tooling-release
+blocked_by: []
+blocks: []
+---
+
+# Review bot warning policy
+
+**Effort:** S
+
+## Design
+
+[0152 review bot warning policy](../../design/0152-review-bot-warning-policy/review-bot-warning-policy.md)
+
+## Problem
+
+PR #93 showed two different review-bot outcomes:
+
+- a real inline issue that needed RED/GREEN repair;
+- a generic docstring coverage warning that did not map to any local
+  script, workflow, or repository policy.
+
+The review loop needs a clear local rule for when warnings become work
+and when they should be answered as false positives with evidence.
+
+## Suggested Fix
+
+Document the evidence bundle required for review-bot false positives:
+local gate search, CI status, affected files, and the reason a proposed
+fix would add churn or violate local style. Fold this into contributor
+review-loop hygiene instead of relying on chat memory.

docs/method/backlog/PERF_recursive-tree-path-benchmark.md

@@ -0,0 +1,34 @@
+---
+id: PERF_recursive-tree-path-benchmark
+feature: trie-state-storage
+blocked_by: []
+blocks: []
+---
+
+# Recursive tree path edge-case benchmark
+
+**Effort:** M
+
+## Design
+
+[0153 recursive tree path benchmark](../../design/0153-recursive-tree-path-benchmark/recursive-tree-path-benchmark.md)
+
+## Problem
+
+The v17.0.1 fix reduced recursive tree OID reads to one `git ls-tree
+-rz` call and added correctness coverage for prototype-like path
+names. The remaining benchmark evidence focuses on fanout and Think
+latency, not a repeatable fixture that combines deep trees, wide trees,
+and unusual but valid Git path names.
+
+## Suggested Fix
+
+Add a benchmark or regression fixture that exercises recursive tree OID
+reads across:
+
+- deep nested paths;
+- wide sibling sets;
+- prototype-like path names;
+- enough entries to expose accidental process fanout.
+
+The benchmark should verify both runtime shape and path/OID integrity.