Slice 18: Cross-environment determinism replay test (CI)

[Jamerrone]

Parent

#1

What to build

The gold-standard cross-environment determinism test (PRD: "the gold-standard test"). After this slice, CI runs both the Node CLI demo and the browser demo from the same shared game-data, same seed, same input transcript — and byte-compares their per-tick snapshots. CI fails loudly on the first divergent tick with the divergence highlighted.

Demoable outcome: CI runs the test; the test runs Node demo → snapshots node/tick-0000.json … tick-NNNN.json; runs browser demo → snapshots browser/tick-0000.json … tick-NNNN.json; byte-compares each pair; passes. If a determinism breaker is introduced (e.g. a Plugin author starts using Math.random() or transcendentals in tick code), the test fails at the first divergent tick with a unified diff and the offending tick number printed.

End-to-end behaviour the slice must produce:

• A CI test harness (single test file, implementation team's choice of runner) that:
  • Invokes the Node CLI demo (Slice 16) and collects per-tick snapshots into one directory.
  • Invokes the browser demo (Slice 17) in a headless browser and collects per-tick snapshots into a parallel directory.
  • Byte-compares each tick-NNNN.json pair in numeric order.
  • On the first mismatch: prints (first divergent tick: N), a unified diff of the two JSON snapshots, and fails the test.
  • Asserts both runs produced the same number of ticks before either completion or divergence.
• A "negative test" fixture that deliberately introduces a determinism breaker (e.g. a fake System using Math.random via a back-channel that bypasses the dev-mode Proxy) and verifies the harness fails it loudly — i.e. proves the harness can catch real breakers.
• CI wiring (GitHub Actions, or whatever the team picks — note any setup in the README outline for Slice 20).

Acceptance criteria

• CI test invokes both Node and browser demos against the same shared game-data, same seed, same input transcript.
• Test asserts both runs produced the same final tick number and the same number of snapshots.
• Test byte-compares each tick-NNNN.json pair; reports the first divergent tick number on failure.
• On failure, the output includes a unified diff of the divergent snapshot JSON for fast inspection.
• A negative-test fixture deliberately introducing a determinism breaker fails the harness with the documented output.
• CI configuration (workflow file or equivalent) runs this test on every PR.
• No regressions on tests from earlier slices.
• Test runs in under 60 seconds (or a documented ceiling — adjust if shared game-data set runs longer; the goal is fast CI feedback).

Blocked by

• Slice 16: Node CLI reference demo + shared game-data set #17
• Slice 17: Browser reference demo + reference Renderer #18