fix: validate authoritative reservation records before decisions

[flyingrobots]

A malformed lock blob could make check x.md report an expired reservation with exit 0. Every refreshed snapshot now validates authoritative job/path records, semaphore metadata, and semaphore slots before normal commands use their fields. Errors produce structured store-read output with exit 2 before authoritative refs change. Doctor uses the same decoder to retain record findings without evaluating unsafe numeric input.

Validation follows the ref's role. Directory and semaphore generation tokens remain opaque. Stored decimal fields normalize leading zeros and reject values outside the nonnegative signed 64-bit range; capacity must be positive. Older lock records that omit family retain the zero default. A maximum family generation remains readable, but child admission refuses to increment it before overflow.

Fixes #33.

Validation:

• Observed the malformed-record RED before implementation: focused run 23 passed, 133 failed, including the reported expired/exit-0 result.
• Observed a separate doctor RED for duplicate fields and unsafe numeric records before sharing the decoder. Observed family-overflow RED with all four assertions failing, followed by all four passing.
• Final normal pre-push gate on 3584fe6: 979 passed, 0 failed. make lint and generated-executable consistency passed.
• Golden and boundary coverage includes live/expired records, legacy leading-zero timestamps/capacities, and maximum signed-64-bit capacity. Failure coverage exercises 11 normal command families, structured errors, unchanged authoritative refs, and suppressed wrapped-command execution.
• A deterministic corpus has 152 malformed lock, metadata, and slot fixtures, including missing/duplicate fields, unsafe arithmetic values, role confusion, invalid paths, and 36 seeded numeric mutations using seed 33. Each fixture checks normal fail-closed behavior and safe doctor diagnostics.

Two earlier full-suite attempts encountered host disk exhaustion and do not count as passing evidence. The final gate used a dedicated temporary directory after disk recovery. PYTHONPATH exposed the existing jsonschema installation to the suite's isolated HOME; no dependencies were installed.

[coderabbitai]

Warning

Review limit reached

Next included review available in 48 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 7549c929-e7ca-4abf-bf28-83cfcff3f9eb

📥 Commits

Reviewing files that changed from the base of the PR and between 01e39c3 and 3584fe6.

📒 Files selected for processing (9)

• CHANGELOG.md
• README.md
• bin/git-locks
• lib/050-the-snapshot.sh
• lib/055-record-validation.sh
• lib/080-families.sh
• lib/175-doctor.sh
• lib/990-main.sh
• test/test.sh

---

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.}