Harden the existing reservation contract before the next feature release

[flyingrobots]

Process the 0.7.0 focused review as a hardening release before expanding feature breadth. The proposed product direction is cooperative path reservations for parallel workers, backed by Git without a daemon. The review supports exploring local coding-agent, generator, and build-runner integrations; it does not establish external adoption or a standalone business.

Evidence retained from the supplied review

The reviewer reconstructed 37 source files from locks.txt using declared byte counts and verified every SHA-256 against the packet index. The supplied suite ran on Linux x86_64 with Bash 5.2.37 and Git 2.47.3, using temporary repositories and isolated HOME/store settings without source modifications. It reported 451 passed, 1 failed.

The sole failure was list lines with non-ASCII text validates against schema/git-locks.schema.json. The environment had C, C.utf8, and POSIX, but not en_US.UTF-8. On the same resulting store, stdout validated under both requested locale configurations and preserved Unicode holder/path text. The unavailable locale produced a Bash warning on stderr; C.utf8 produced no stderr. The test merged stderr into the JSON it validated. This is separate from the focused code defects.

The focused probes showed wrong-path reservation, malformed-record expiry reporting, two invalid parent-replacement outcomes, and invalid capacity JSON. During issue triage on 2026-09-22, all five probe outcomes were independently reproduced on macOS with Bash 5.3.9 and Git 2.54.0, against 01e39c306362d7de26cec08f149d7f286e3733ce, which matched remote main. The full suite and packet reconstruction were not rerun during triage. Each defect issue includes self-contained reproduction details and source links.

These are bounded observations, not an exhaustive audit or a proof over every interleaving. The malformed-record probe establishes a read API violation, not successful competing admission. The partial-observation concern and historical-churn performance concern remain investigations.

Release hardening, in suggested order

• Preserve literal glob characters during path normalization #32 Preserve literal glob characters during path normalization
• Reject malformed stored records before liveness decisions #33 Reject malformed stored records before liveness decisions
• Preserve family invariants when replacing a parent acquisition #34 Preserve family invariants when replacing a parent acquisition
• Normalize semaphore capacity as decimal before storing or emitting JSON #35 Normalize semaphore capacity as decimal before storing or emitting JSON
• Make Unicode tests portable across installed UTF-8 locales #36 Make Unicode tests portable across installed UTF-8 locales
• Align introductory examples with time-bounded reservations and acquisition identity #37 Align introductory examples with time-bounded reservations and acquisition identity

Resolve the remaining correctness question

• Probe membership and generation coherence during partial multi-ref observation #38 Probe membership and generation coherence during partial multi-ref observation

Disposition of this investigation belongs in the release decision. If it finds a correctness hole, add the bounded fix and regression to the hardening gate. A passing stress test alone does not settle the read/commit argument.

Measure and validate the existing use case

• Benchmark historical directory-token growth after all locks are released #39 Benchmark historical directory-token growth after all locks are released
• Demonstrate two cooperating workers with understandable contention and safe cleanup #40 Demonstrate two cooperating workers with understandable contention and safe cleanup

Measure historical directory churn before adding storage optimizations. Run the cooperating-worker demo after the correctness fixes; retain actual integration feedback separately from a successful scripted demonstration.

Completion criteria

• The code defects have regressions and fixes, relevant validation passes, and the Unicode test behaves correctly in the reviewer's locale configuration.
• Introductory examples match current acquisition identity, cooperative participation, TTL, worktree namespace, and concurrent-read guarantees.
• The partial-observation investigation has an explicit evidenced disposition, with any blocking fixes tracked and completed before release.
• Benchmark and demonstration results state their environments and limitations. The release notes do not claim adoption or guarantees that have not been established.

This tracker records the review's recommendation to freeze breadth for one release. It does not close or rewrite existing feature proposals such as #2, #7, #9, or #10. Existing #20 remains a possible semaphore design comparison; the observation investigation does not predetermine that choice. No release version is selected by this issue.

Observation-phase correctness gate

• Bind family, semaphore, and prefix decisions to coherent reads #45: Bind family, semaphore, and prefix decisions to coherent reads. The Probe membership and generation coherence during partial multi-ref observation #38 study exposed synthetic planner-observation counterexamples in all three domains; real Git transactions committed states that violated independent invariants. A live Git schedule producing those observations remains unproven. Investigation completion does not complete this fix; keep this release correctness gate unresolved until the retained safety regressions pass.

Implementation PRs

All nine original work items now have PRs targeting main. All nine are ready for review and have passing individual lint/test gates; the completed benchmark retains 135 measured observations, and the locale PR also passed its dedicated Ubuntu missing-locale job. None has been merged, and a combined integration tree has not been validated. Release checklist items above remain open until their changes land and the release criteria are met.

Work item	PR
#32 Literal path identity	#48
#33 Authoritative record validation	#43
#34 Parent replacement invariants	#42
#35 Decimal semaphore capacity	#44
#36 Portable UTF-8 locale tests	#51
#37 Reservation contract and introductory examples	#46
#38 Membership observation study	#47
#39 Historical directory-token benchmark	#50
#40 Cooperating-worker demo	#49

The #38 study retained 21 failing production-safety cases out of 84 controlled mixed observations. Its passing harness/calibration checks do not turn those counterexamples into a passing safety result. #45 remains the separate, unresolved correctness gate.

The completed work used separate branches and worktrees. Regression fixes retain observed RED/GREEN evidence, with focused edge, seeded corpus/model, or bounded stress coverage appropriate to each lane. The worker demo is scripted integration evidence; external adoption remains unrun. Benchmark measurements are from the unchanged 0.7.0 baseline executable on a shared macOS host, with synthetic large stores calibrated against small real CLI histories. Rerun relevant integration and performance checks after the PRs land.

Status 2026-10-02

All nine implementation PRs (#42, #43, #44, #46, #47, #48, #49, #50, #51) are merged; main is a5c0acd, its CI is green, and bin/git-locks there matches a fresh make build from lib/. Each branch had main merged into it before its own merge, and make test and make test-docker now name the same six suites (test-docker has still not been executed: #89). The combined tree is therefore validated to the extent the ordinary suite validates it; the observation safety study is not part of that suite (#88).

Still open before a release:

• Bind family, semaphore, and prefix decisions to coherent reads #45 Bind family, semaphore, and prefix decisions to coherent reads (the correctness gate)
• The observation safety study is not a release gate: the release job needs only lint-and-test, and a green calibration can stand in for a safety result #88 Make the observation safety study a release gate and name the one artifact and its checks
• A --ttl at or near INT64_MAX writes a negative expires and bricks the store for every command #55 Writers accept a --ttl whose expiry overflows and brick the store the hardened reader now refuses (with Three integer grammars: --wait 08 crashes with raw bash text, 010 is octal, GIT_LOCKS_NOW=+5 poisons the store #56 for the other integer inputs)
• transact() cannot tell a lost race from a permanent failure: 200 retries, 48 s, 200 garbage blobs, then a fake refusal #52 transact() retries permanent failures 200 times (Critical in the 2026-10-02 audit, docs/audit/)
• with discards the outcome of its own release, so a reservation lost mid-command exits 0 #54 with exits 0 after losing its reservation mid-command
• Decide the version: Preserve family invariants when replacing a parent acquisition #34/fix: preserve family invariants during parent replacement #42 landed a BREAKING CHANGE (re-claiming a parent with stored descendants is refused), so the next release is 1.0.0 under SemVer or 0.8.0 if pre-1.0 is kept exempt
• Rerun the directory-token benchmark with recorded host conditions and pressure monitoring to replace the resource-confounded baseline #91 Replace the resource-confounded benchmark baseline before any performance-driven design choice
• Run the cooperating-worker adoption experiment defined in examples/cooperating-workers/README.md #90 Run the adoption experiment after the gates above; its result decides priority over Recursive WARP graph of locks: design wanted #2, git locks wait: block until paths are free without claiming, and watch: stream store changes as JSONL #7, History: who held a path, from the store's reflogs #9, Shared store over a remote: fetch, transact, push --atomic #10

Review of the merged set was a per-PR strict pass with red/green fixes plus CodeRabbit where it was not rate-limited; #92 asks what counts as independent review here.