Module churn 

The self-describing content pattern that makes a TORN FILE detectable.

Why this is in the SDK and not in whichever crate happens to write it. This is a contract between a WRITER and a CHECKER, and its failure mode if the two ever disagree is the worst one available: churn verify reports “NONE torn” because it no longer recognises a tear. A safety check that passes because it stopped working is worse than no check, because somebody trusts it.

The two halves used to be one expression written twice in services/shell - tolerable while both copies sat a few hundred lines apart in one file, where anybody editing one saw the other. Backgrounding churn puts the writer in services/copier and leaves the checker in the shell, in different crates that deliberately do not share headers. So the pattern moves here, where there is exactly one of it and both callers name the same function.

What the pattern is. Every byte encodes the generation that wrote it:

byte[k] = (gen + k) mod 251

A file written wholly in one generation satisfies that for every k. A file holding a MIX of two generations breaks it at exactly the byte where the tear happened, so the checker learns gen from byte 0 and then walks the rest.

251 is the largest prime under 256, and the primality is doing work. A prime stride does not align with the 508-byte block payload, so a tear landing on a block boundary still lands mid-pattern and stays visible instead of reading as a continuation.

This is the half that structural checking cannot reach: drives check validates the tree, the bitmap and the CRCs, and none of that can tell whether a file holds the first half of one write and the second half of another. The permitted-outcome table says a whole-file write must be old-complete or new-complete and never a mix; this is what makes that claim testable.

Functions

byte_at

The byte a file written in generation gen must hold at offset k.

fill

Fill buf with one generation’s content, end to end.

first_divergence

The first offset in data that does NOT match the generation recorded in its byte 0, if any.

generation

The generation for the ith write of a churn run.