Two builds from identical inputs emit generated files that differ byte for byte — what causes that?

Reproducible emission means one thing: the same inputs produce the same bytes. It sounds like a purity exercise until you try to check that committed output still matches its input, at which point it becomes the precondition for the check. ## Where the instability comes from The inputs did not change, so the variation was introduced by the generator. It comes from two families. **Ordering the generator inherited instead of chose:** - Walking a **hash-keyed collection** of declarations, whose iteration order is not part of its contract and may differ between runs or between environments. - **Parallel work** whose results are appended as each unit finishes, so output order tracks completion order. - Deduplicating through a set and emitting in whatever order the set yields. - Sorting names with a **locale-dependent or case-folding comparison**, so the same list orders differently on a differently configured machine. - Synthesized names drawn from a **counter that advances in visit order**, which makes every downstream reference shift when the visit order shifts. **Environment the generator recorded instead of the inputs:** - A **generation timestamp** in the header — the single most common cause, and the one that guarantees a change on every run. - **Absolute paths**, host names, user names, or a working-directory-dependent path in a comment. - A **generator version string** embedded in output, which is defensible but means every toolchain bump rewrites every file. - Any value read from the clock, the random source or the environment during emission. ## Why it is worth fixing | Cost | What it looks like day to day | |---|---| | Diff noise | Every rebuild shows hundreds of changed files; the one real change hides inside them | | Merge conflicts | Two people rebuild, and reordered members conflict although neither changed behaviour | | Cache misses | A build cache keyed on file contents re-runs everything downstream of the output | | No drift check | "Re-derive and compare with what is committed" always reports a difference, so it is switched off | | Hard bisection | Comparing two builds' outputs cannot isolate a change, because everything differs | The fourth row is the one that matters most, because it removes the only cheap guard against committed output drifting away from its inputs. ## Making emission deterministic 1. **Order from the input.** Collect declarations, then sort by a total order derived from the input — a fully qualified name compared by code point, or the declaration's position in its description — before emitting anything. Never let a collection's iteration order decide file content. 2. **Merge parallel results in a fixed order.** Parallelism is fine; appending in completion order is not. Assign each unit an index up front and assemble by index. 3. **Emit no clock, path or identity.** If a header must carry a version, derive it from the inputs or the declared generator version, not from the moment of emission. The build already records when it ran. 4. **Pin the comparison.** Sort by an ordering that does not vary with locale or case-folding configuration. 5. **Derive synthesized names from the input.** A name built from a hash of the input element is stable; a name built from a visit counter is only as stable as the visit order. 6. **Test it.** Emit twice into different directories and compare byte for byte, as an ordinary test. It catches every item above and costs one test. ## What determinism does not mean It does not mean output never changes — a changed input should change the output, and that is the signal you were protecting. It does not mean the emitted text must be minimal or canonical in any formal sense; two generators may legitimately emit different but equivalent source for the same input. The property is narrower and entirely practical: **this generator, these inputs, these bytes, every time**. Anything the output records that did not come from the inputs is a candidate for deletion, and a header timestamp is almost always the first one to go.