Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-0004: Determinism by construction

Status: Accepted · 2026-10-08

Context

Golden-file conformance, reproducible bug reports, safe caching and CI-regenerated docs images all require identical output across platforms and runs.

Decision

Ordered collections only; transcendental math through libm; a specified PRNG (SplitMix64) with seeds from element ids and random_seed; quantization of absolute positions once at encode time; total-order sorts with tie-breakers; budgets in work units, not time; golden files compared byte for byte on Linux, macOS and Windows. Enforced by clippy disallowed-types/disallowed-methods. Details: determinism.

Consequences

  • Slightly more verbose code (BTreeMap, math::sin); negligible performance cost.
  • Byte-exact goldens are possible for formats and stitch renders.

Alternatives considered

  • Tolerance-only comparisons everywhere: hides real regressions and makes images flaky. Rejected except for VectorCraft UI screenshots, which we do not control.

Amendment, 2026-10-14

The decision first named a CI job that would compare output hashes across Linux, macOS, Windows and wasm. CI compares each operating system’s outputs with the golden files instead, and builds the WebAssembly target without running it (cross-platform check).