Accepted8 Nov 2026
0050. One report per seed on every platform, with the Python engine's digest definitions
Context and Problem Statement#
The Java simulator now writes a run's whole report, through its provenance: the versions, the
seed, the scenario and its overrides, inputDigest (the SHA-256 of the design simulated, as
canonical JSON) and resultDigest (the same over the summary, time series, parts, links and
window). Reports from both engines will sit side by side in the database: stored runs are not
migrated. The Python engine promised the same digest for the same input, seed and engine version
only on the same platform and Python version, and its provenance names python and simpy. What
should a Java report promise about repeating itself, what does its digest mean beside a Python
report's, and what does its provenance name?
Decision Drivers#
- A run repeated anywhere should give the same report; a support question should not depend on the machine.
- Where a Java run and a Python run of the same input meet (a comparison, a re-run), the app should say truthfully why their digests differ.
- The provenance should say truthfully what ran.
- Java's
Math.log,expandpowmay differ in the last place by platform;StrictMath's may not.
Considered Options#
- Keep the digests' definitions, each naming a result within one engine; make every Java report a function of its input and seed alone; name the Java runtime in the provenance
- Keep the digests' definitions and the Python engine's promise (same platform only)
- New digests, over the Java's own JSON writing
Decision Outcome#
Chosen option: "Keep the digests' definitions, each naming a result within one engine; make every Java report a function of its input and seed alone; name the Java runtime in the provenance".
- One report per seed. A Java run is deterministic for a given seed on every platform and
JVM: the same document, scenario, seed and engine version give the same report, but for the
provenance's
wallSecondsandjava.- Every transcendental function in the engine and the model goes through
StrictMath; one ArchUnit rule (StrictMathRule), checked in each module, refusesMath.log,exp,powand the like. The random streams already did (ADR-0047). - What the report lists, it lists in an order fixed by the design or by sorting, never by a hash table's iteration.
- A run is one thread, and reads no clock but for
wallSeconds.
- Every transcendental function in the engine and the model goes through
- A digest names a result within one engine. The digests keep their definitions: SHA-256 of
canonical JSON (sorted keys, no spaces, Python's spelling of floats),
inputDigestover the design simulated andresultDigestover the summary, time series, parts, links and window. A Java run and a Python run of the same input and seed agree to the parity bar (ADR-0049) but need not share aresultDigest; they share it where every number agrees to the last bit, as in all twelve runs replayed today, which is measured, not promised: the parity report (docs/validation/java-parity.md, later in stage 4) will say how many template runs share it. TheirinputDigests match. - Where digests are compared:
- A run comparison warns, for the same inputs and seed with other digests, of "different engine
builds or platforms". When one run is Python's and the other Java's (only one provenance has
java), it names the two engines instead, whatever the inputs and seeds, as it names two engine versions. - The web app's re-run says "Reproduced exactly" for an equal digest; otherwise it now names both engine versions when they differ, and suggests a different engine, build or platform when they do not. The Java engine's version becomes 1.0.0 at stage 4's end, so the versions tell the engines apart from then.
- The golden files' check and the performance records (
scripts/perf.py) compare the Python engine's digests with its own. The stage-4 speed report compares Java with Python by its figures, not its digests. - Share links, the check action's comment, sweep rows, the benchmark harness's predictions and the MCP server's run id show or store a digest and compare none.
- The re-run's promise of the same digest is worded "on the same engine" now: the API's
reference (
docs/api.md), the report's Markdown export and the re-run's Javadoc (RunController,RunChanges). The component guide's determinism test runs one engine twice (docs/extending-components.md), so it stands.
- A run comparison warns, for the same inputs and seed with other digests, of "different engine
builds or platforms". When one run is Python's and the other Java's (only one provenance has
- The provenance names the Java runtime:
java(thejava.versionproperty, such as25.0.3) in place ofpython;simpygoes, and no kernel version takes its place: SimPy was a dependency that could change results, the Java kernel is the engine's own code, andengineVersionnames it. - The report's version is 1.15 from this change:
EngineVersions.REPORT, which/metaserves and the Java simulator writes. Until the Java worker writes runs (a later slice of stage 4) the Python workers still store 1.14 reports. Every reader accepts both shapes: the engine readsengineVersion,seed,resultDigestandjavaof a provenance, and neitherpythonnorsimpy; the web app declarespythonandsimpyoptional andjava(1.15+), and otherwise passes the version through. The golden files'REPORT_VERSION, the Python engine's 1.14, is no longer checked.
Status (10 Nov 2026): the Java worker writes every run since stage 4 (ADR-0053), so new runs store 1.15 reports; the 1.14 reports the Python workers stored stay readable.
Consequences#
- Good, because a Java run reproduces on any machine, which the Python engine could not promise.
- Good, because a Java run beside a Python run of the same input is named for what it is, not taken for another build of one engine.
- Good, because the provenance says which runtime ran the report.
- Bad, because
StrictMathis slower thanMath's intrinsics on some functions; the simulator's speed is measured againstdocs/performance.mdwith it. - Bad, because
/metasays 1.15 while the Python workers still store 1.14 reports, until the Java worker replaces them; nothing reads the version but to show it. - Neutral: the report's model note keeps its words ("on the same platform") while the replays
hold Java to Python's report; it is still true, if less than Java promises. The determinism
notes in
docs/architecture.mdanddocs/simulation-model.mdchange when the Java worker writes runs.
Confirmation#
SimulationCasesTestscompares both digests exactly for every recorded run, and fails at/provenance/resultDigestwith the window left out of it (checked); it checks the version and thejavakey the Java writes.ReportRecordKeysTestschecks the report records against the Java simulator's reports as well as the golden files' (ADR-0039), and readsjavaback from one.StrictMathRulefails on aMath.expcall (checked in the model).ComparisonWarningsTestsand the web app'sreproduction.test.tscheck the two places that meet both engines' digests.
Pros and Cons of the Options#
Keep the Python engine's promise#
- Good, because nothing changes.
- Bad, because it promises less than Java can keep, for no gain.
New digests#
- Good, because the Java would owe nothing to Python's spelling of floats.
- Bad, because no Java report's digest would equal a Python report's, so every stored run would look different from its re-run, even where the figures agree to the last bit.