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

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.