5+3 council: harden lance-graph-hydrate (fast-follow to merged #957)

[AdaWorldAPI]

Summary

PR #957 (the new lance-graph-hydrate crate) merged mid-council — before Phase 4 (fix) landed. This PR applies the council's findings as a fast-follow rather than reopening/amending #957.

Process: Full 5+3 council (.claude/agents/5+3-council.md) on the crate: Phase 0 spec → Phase 1 (5 savants in parallel, 26 distinct findings) → Phase 2 (consolidated into 20 committed decisions) → Phase 3 (3 reviewers on the consolidated draft, zero BLOCK, 6 FIX) → Phase 4/5 (this commit). Full record: .claude/plans/hydrate-crate-hardening-council-v1.md.

Real defects found and fixed

• Staging-nonce collision: pid+nanos alone can repeat within one clock tick — two concurrent calls could interleave writes into what each believed was its own private staging directory. New shared staging::staging_suffix() (pid + atomic counter + nanos), 1000-iteration uniqueness test.
• Resource leak on every I/O-failure path: neither hydrate_dir nor hydrate_file cleaned up their staging directory/file on a fetch/write error — only the two explicitly-handled paths (empty-prefix, checksum-mismatch) did. Now every path cleans up.
• Silent postcondition violation: hydrate_dir's empty-prefix cleanup discarded its own error on the Ok return path, so a filesystem failure there could leave debris while the function still claimed "leaves nothing." Now propagates.
• hydrate_file's actual danger case was unguarded: the existing AlreadyPublished check only ran at function entry. On POSIX, a file-onto-file rename silently clobbers an existing destination rather than failing — so the one check that mattered (immediately before the rename) didn't exist. Fixed.
• release_dir could never return Err: every failure was swallowed, making its own "missing directory returns zero, not an error" test vacuous by this repo's own falsifiability rule (nothing could make it fail). Now returns Err on a genuinely unreadable root, Ok(0) only for NotFound, with a real two-sided test pair.
• WarmMarker's format had no version tag and permissive arity (the >= N shape this repo's CLAUDE.md specifically warns against). Now v1 <mtime> <len>, exact 3-token arity, both a legacy-shaped 2-token line and a future 4-token line refused by tests.

Overclaims corrected (doc-only)

• LifecycleState was claimed "encoded as a transition guard, not caller discipline" — false, it appeared in zero function signatures anywhere in the crate. Corrected, and dirty::lifecycle_of() was added to actually start closing that gap.
• is_dirty was claimed to compare against "the version recorded at hydration time" — false, nothing records it; the version is and remains caller-supplied.
• The idempotency boundary was described with a singular "the condition," collapsing the doctrine's two conditions into one. Corrected to name both.
• copy.rs's module doc overclaimed the publish-by-rename mechanism was "generalized from hydration_probe.rs's proven mechanism" — that probe has no staging step at all; only the raw byte-copy property is actually inherited from it.

Board hygiene

New dated LATEST_STATE.md entry correcting the three wrong claims made in the original (now-merged) 2026-08-17 entry — that entry is left unedited per this repo's append-only rule.

Verification status

Same honest caveat as #957: this session's container cannot build the lance/arrow/aws-lc-rs sub-tree locally (repeated ENOSPC). The pure-std modules (lifecycle.rs, staging.rs, marker.rs's non-test code) were syntax/type-checked directly via rustc --emit=metadata — clean. The lance/object_store-touching changes were not locally compiled; deferred to this repo's CI, which I'll watch and fix on any failure.

Test plan

• CI (rust-test.yml et al.) compiles and runs the crate's now-larger test suite
• cargo clippy -p lance-graph-hydrate clean
• Confirm additive-only — no other workspace member touched

🤖 Generated with Claude Code

---

Generated by Claude Code

[coderabbitai]

Important

Review available on request

• 🔍 Trigger review

Reviews should be triggered manually for repositories with fewer than 10 stars. Select Trigger review above or comment @coderabbitai review to review the latest changes. For a full review, comment @coderabbitai full review.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f3a81b3d-c8e5-4963-9b98-c9b5901c3d57

---

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

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_760b927b-fd2e-4bdc-9f39-927ddeba27ad)

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.