The previous commit wired the emulator job to read the committed
examples/*.nes directly, with the rationale that the `examples`
job's reproducibility diff would catch "stale committed ROMs"
at PR time. That reasoning is wrong and defeats the point of
the emulator harness.
Failure mode: a compiler change lands with correctly-rebuilt
ROMs (passing the examples job) but introduces a rendering
regression that flips a golden. The emulator job would catch
this today because it runs the harness against freshly-compiled
ROMs. With the previous commit's shortcut, the harness would
boot the committed ROMs — which the PR author just rebuilt to
match — so the mismatch wouldn't show up until a second commit
touched anything else. That's exactly the kind of silent-failure
hole the golden harness exists to plug.
Fix: emulator job rebuilds the compiler (toolchain + cache +
`cargo build --release`) and compiles every .ne into the
workspace before running the harness, same as the pre-ROMs-
committed era. The committed ROMs keep their review/demo role
(clone-and-play, diff visibility in PRs) but the test job
always validates the working compiler, not a frozen snapshot.
CLAUDE.md updated to match: the harness runs against whatever
sits in examples/*.nes, so iterating locally still means
rebuilding the ROM(s) you care about first.
https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
The compiler is deterministic: rebuilding any example produces
a byte-identical ROM, verified across all 22 examples and all
four mappers (NROM, MMC1, UxROM, MMC3). That means the .nes
files are reproducible artefacts and can live next to their
sources without drift.
Benefits:
- Users can clone the repo and open any example in an emulator
without installing a Rust toolchain or running the compiler.
- The emulator harness can trust examples/*.nes directly, so its
CI job no longer needs a compiler build or a "compile all
examples" loop — it just boots jsnes against the committed
ROMs and diffs each against its golden.
- ROM diffs in PRs are now meaningful: "this compiler change
flipped 17 bytes in hello_sprite.nes" is visible review
signal, not hidden behind the emulator golden.
Guard rails so the ROMs don't drift from their sources:
- .gitignore no longer excludes *.nes.
- The `examples` CI job rebuilds every .ne into /tmp and fails
loudly (with a GitHub error annotation pointing at the exact
cargo command to rerun) if any committed ROM differs.
- scripts/pre-commit does the same check locally.
- CLAUDE.md now states that editing a .ne file requires
rebuilding its .nes in the same commit, so future agents
won't miss the invariant.
Total footprint: 22 ROMs, 624 KB (avg 28 KB each — most are
NROM 24 KB; two banked examples are larger).
https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
New top-level `CLAUDE.md` so future AI agents (and humans) don't have
to rederive the project conventions from the existing docs. Covers:
- The phase layout under `src/` and the expectation that every
module has a co-located `tests.rs`.
- The core `cargo` commands and the fact that `fmt` and `clippy`
are mandatory before committing.
- The jsnes emulator harness end-to-end:
- File layout (`harness.html`, `run_examples.mjs`, `goldens/`,
`actual/`).
- How to run it locally (build release compiler, compile every
example, `npm install`, `node run_examples.mjs`).
- How to update goldens with `UPDATE_GOLDENS=1` and the rules for
when that's allowed.
- The procedure for adding a new example (build, golden, verify,
README).
- What the harness catches (codegen / runtime / PPU / APU / asset
regressions) vs. what it doesn't (input, beyond frame 180).
- How the CI job in `.github/workflows/ci.yml` wires everything up
and uploads `actual/` on failure.
- Zero-page allocation rules (runtime reserves `$00-$0F`,
palette/bg reserves `$11-$17` conditionally, user vars `$10+` or
`$18+`, IR temps `$80+`) so the next agent doesn't accidentally
collide with the runtime.
- "Things to avoid" list: no backwards-compat shims, no silencing
goldens without understanding the diff, no committing the
gitignored harness directories.
https://claude.ai/code/session_012fKB251HvEUQwG3tizFyqt
