A hand-edited snapshot passes the Rust suite the docs say would catch it

[blooop]

Question

docs/development.md tells a contributor that a hand-edited snapshot "fails in the Rust suite rather than in review". It does not. On #427, rust/devlaunch-core/tests/public_api_snapshots.rs passed 4/4 on a public-api.rest.txt that CI's public-api job then rejected.

The reason is that the two check different things. The local tests hold the partition — every row in exactly one file, promise rows at an api path, no row in both. Ordering is not a partition property, so a block placed in the wrong position satisfies every assertion and still fails CI's regeneration diff. In #427 the hand-edit put the DevpodHome struct block before the RepointFailure enum block; cargo public-api emits the enum first.

This matters more than one misplaced block, because it is the guidance a contributor acts on. cargo-public-api needs nightly and a pinned version, so a devcontainer cannot regenerate the files at all (pixi run cargo public-api → not installed; there is no rustup and the toolchain is a conda rust). Hand-editing is therefore the normal path in here, not an exception — and the one check available locally is documented as catching a class of error it cannot see.

Options

• Make the doc honest. Cheapest: say the local tests hold the partition, that ordering and rendering are CI's, and that a hand-edited snapshot is provisional until the public-api job agrees. Low cost, and it stops a contributor trusting a green suite.
• Make the test hold ordering too. The generator's order is a total order over rendered rows; if it is reproducible from the file alone, the test can assert the file is sorted the way the generator sorts. Establish that the rule really is derivable before building it — cargo public-api's ordering is its own, not plain sort, and encoding a guess would be worse than the gap.
• Make regeneration possible in the container. Probably out: it needs nightly plus a pinned cargo-public-api, and .devcontainer/ changes invalidate the prebuild (see AGENTS.md). Worth naming as rejected so nobody re-proposes it.

The first is almost certainly right on its own; the second only if the ordering rule turns out to be cheaply derivable.

Testing the outcome

If the doc changes: whatever guard the repo already uses for README/doc claims (test/test_agents_doc.py and its siblings are the precedent).

If the test changes: the red is #427's own misordered file — the exact bytes are in that PR's history, so the regression test writes itself.

Found by the review of #427, which is also where the misordering was caught — by CI, three hours after a green local suite.

[blooop]

Claimed 2026-08-29: build in progress from an interactive session (agent in an isolated worktree), managed by session devlaunch-2b. PR to follow. If you are another session looking at this ticket, pick a different one.

[blooop]

PR: #513

Option one, and only option one. The sentence in docs/development.md now says which half of the check is where: the Rust tests hold the partition, so a row filed in the wrong tier fails locally; ordering is not a partition property and nothing local sees it, so a block in the wrong position is caught only by CI's public-api regeneration diff. A hand-edited snapshot is therefore provisional until that job agrees, which the paragraph now says out loud alongside the note that the devcontainer has neither prerequisite and hand-editing is the only route there.

Option two is explicitly not taken. The ticket set its own bar, that the ordering rule be shown to be derivable from the file before anything is built on it, and it is not: cargo public-api's order is its own rather than plain sort, and encoding a guess at it would be worse than the gap. A test that asserts a wrong total order fails on correct regenerated files, which turns a documented gap into a guard people learn to override.

Option three stays rejected as the ticket already framed it: nightly plus a pinned cargo-public-api, and any .devcontainer/ change invalidates the prebuild.

The PR also carries the #319/#323 CLAUDE.md paragraphs as a separate commit; unrelated to this ticket, same small docs PR.