ADR 0003: Output is deterministic and pinned by goldens

• Status: accepted
• Date: 2026-09-23

Context

A code generator that changes bytes for the same input destroys trust: every release produces a diff storm, and "did my change alter the output?" has no answer.

Decision

No timestamps, no randomness, no environment leakage in generated files. Iteration is over BTreeMaps and sorted collections; the OpenAPI document is serialized from serde_json maps, which sort keys. Every example under examples/ commits its full rendered output under <example>/golden/ plus a MANIFEST with a sha256 hash per file. CI runs the conformance check on every push; authors regenerate with mosaic conformance --update.

Consequences

• Any behavior change that alters output is visible in the golden diff — the change and its consequences are reviewed together.
• "Did the rendering change?" is answerable in one git diff.
• Regeneration is a deliberate act, not an accident.

Proof

cargo test -p mosaic-conformance → examples_match_goldens (runs in CI on every push; fails on any byte difference, stale golden, or manifest mismatch).