# sim/golden — Golden-Reference Comparison

Scripts, hooks, and notes for comparing RTL behavior against a software
golden reference (PS2 emulator).

The project-level reference strategy is locked in
`docs/decisions/0003-golden-reference.md`.

Current state (2026-04-17):

- **Live-emulator harness is parked.** Two attempts were made:
  DobieStation (blocked at runtime in the Emulator constructor) and PCSX2
  (blocked at CMake configuration on missing modern deps including SDL3,
  plutovg, plutosvg, ryml, Qt 6.10.1). See `third_party/DobieStation/NOTES.md`
  and `third_party/PCSX2/NOTES.md`.
- **The generated-golden path is the completed Phase 1 result.** End-to-end
  validated through `make test_compare`: clean run, deliberate corruption,
  and malformed input all produce the documented exit codes.
- Live-emulator comparison is deferred until either a fuller EE front end
  lands (Wave 3) or a low-friction live source becomes available.
- `docs/decisions/0003-golden-reference.md` is unchanged — multiple-references
  is still the strategy; only the phasing moved.

Implementation spec:

- `trace_compare_spec.md` — defines the first compare target, common-envelope
  shape, diff semantics, exit-code contract, and acceptance criteria.

Current implementation (Phase 1, NOP-sled target):

- `make_nop_golden.py` — generates the NOP-sled golden trace in the common
  envelope. Options: `--count`, `--reset-vector`, `-o`. Default matches the
  32-fetch window produced by `tb_ee_fetch_stub`.
- `trace_compare.py` — filtered order-based diff per spec. Exits 0/1/2/3 for
  pass / semantic mismatch / usage-or-missing / malformed.
- `dobiestation_runner/` — headless DobieStation harness. Builds cleanly;
  runtime blocked at Emulator constructor (see
  `third_party/DobieStation/NOTES.md`). Fetch tap is instrumented and ready
  to emit in this same envelope once the runtime block is resolved.

Expected content as this area grows:

- build/run notes for emulator-side tools,
- patches or instrumentation to emit traces in the chosen format,
- additional comparison scripts as new event classes come under diff,
- disagreement policy notes for "spec vs emulator" and later "emulator vs
  emulator" cases.