-x86_64-pc-windows-msvc.zip; .\rustynes.exe path\to
```
Launch it without a ROM and use **F12**, the File menu, or drag and drop a
-`.nes` / `.fds` onto the window.
+`.nes`, `.fds`, `.unf` or `.zip` onto the window. The macOS archive also holds
+a `RustyNES.app`, signed ad hoc rather than notarized: allow it once in System
+Settings > Privacy & Security, or run
+`xattr -dr com.apple.quarantine RustyNES.app`.
### Build from source
@@ -172,7 +169,7 @@ in `crates/rustynes-frontend/web`.
- **Self-flashing homebrew boards** (GTROM, UNROM 512) emulate their SST39SF040
flash chip, so games that save by rewriting their own ROM keep those saves.
- **Battery saves** persist on desktop, Android and iOS, and in the browser
- (`IndexedDB`, from v2.9.7).
+ (`IndexedDB`).
- **Famicom Disk System** with a user-supplied `disksys.rom`, and **UNIF** boards
mapped to their iNES numbers.
- **Header corrections on every platform:** a built-in game database fixes known
@@ -203,7 +200,7 @@ in `crates/rustynes-frontend/web`.
- **TAStudio:** a piano-roll editor with a save-state greenzone, lag log,
markers and branches, and movie import from FCEUX, BizHawk and others.
Movies record every input the core takes, expansion devices, the microphone,
- Vs. coins, disk swaps and barcode scans included (`.rnm` format 7).
+ Vs. coins, disk swaps and barcode scans included.
- **Speedrun timing:** splits from RAM conditions, timed in master-clock cycles,
with a fixed-layout memory interface for splitters
([`docs/memory-export-interface.md`](docs/memory-export-interface.md)), and
@@ -293,29 +290,27 @@ to player 1 automatically.
| Suite | Result |
| --- | --- |
-| **AccuracyCoin** | **147/147 (100.00%)** at upstream `66e87112` since v3.6.2, read from RAM rather than the screen. The v3.1.0 re-sync to `f5f41dc2` (146/146) showed that the 144/144 reported before it was overstated: the older ROM's `Misaligned OAM behavior` fail path fell through to a pass, hiding a real failure the re-sync found and fixed |
+| **AccuracyCoin** | **147/147 (100.00%)** at upstream `66e87112`, read from RAM rather than the screen |
| `nestest` | 0-diff against the Nintendulator log |
| blargg `cpu_interrupts_v2` | 5/5, and the unstable-store tests 6/6 |
| blargg APU (NTSC and PAL) | 11/11 and 10/10 |
| blargg `apu_test` frame-counter probes | 10/10 |
-| blargg MMC3 (`mmc3_test_2`) | 5/6 strict, including `4-scanline_timing` (all 13 sub-tests) since v3.0.0; `6-MMC3_alt` tests the NEC revision, which the Sharp default is not, by design |
+| blargg MMC3 (`mmc3_test_2`) | 5/6 strict, `4-scanline_timing` included (all 13 sub-tests); `6-MMC3_alt` tests the NEC revision, which the Sharp default is not, by design |
| `region_timing` | 4/4, including PAL's 3.2:1 ratio |
| Holy Mapperel | every committed variant reports detail code `0000` |
-| Commercial-ROM oracle | 99 titles, SHA-256-pinned, byte-identical frames |
-
-The last MMC3 interrupt-timing residual, `mmc3_test_2/4-scanline_timing`, closed
-in v3.0.0 (T-MMC3-BG-A12): every sub-test of the battery's MMC3 suite now passes
-except the deliberate other-revision case. Every remaining known approximation is
-listed, with its evidence, in [`docs/accuracy-ledger.md`](docs/accuracy-ledger.md),
-and the per-suite detail is in [`docs/STATUS.md`](docs/STATUS.md).
+| Commercial-ROM oracle | SHA-256-pinned dumps you supply, checked for byte-identical frames and audio |
-When a document and a passing test ROM disagree, the ROM wins: that is this
-project's definition of cycle-accurate.
+[`docs/STATUS.md`](docs/STATUS.md) is the single source of truth for the
+per-suite counts; every remaining known approximation is listed, with its
+evidence, in [`docs/accuracy-ledger.md`](docs/accuracy-ledger.md). When a
+document and a passing test ROM disagree, the ROM wins: that is this project's
+definition of cycle-accurate.
**Mapper tiers.** Of the 208 families, 181 are *accuracy-gated*: 51 Core and 130
Curated, each backed by a test ROM, a commercial dump, or a precise register
description with a synthetic fixture. The other 27 are *BestEffort*: their
documentation is thin, and a CI gate keeps them out of every accuracy claim.
+[`docs/mappers.md`](docs/mappers.md) gives each family's tier and evidence.
---
@@ -367,9 +362,12 @@ detailed in [`docs/architecture.md`](docs/architecture.md) and
| `rustynes-hdpack`, `rustynes-gfx-shaders` | HD packs and the shared WGSL shaders |
| `rustynes-mobile`, `rustynes-android`, `rustynes-ios` | The mobile bridge and platform glue |
| `rustynes-libretro` | The RetroArch core |
+| `rustynes-gamedb` | The per-game header-correction database |
| `rustynes-mcp` | A Model Context Protocol server over the headless core (`rustynes-mcp`) |
| `rustynes-dap` | A Debug Adapter Protocol server and GDB stub for cc65 / llvm-mos homebrew (`rustynes-dap`) |
+| `rustynes-probe` | Deterministic re-simulation: replay under a variation and find the first divergence |
| `rustynes-test-harness` | Integration tests and the accuracy oracles |
+| `rustynes-cosim` | The co-simulation oracle for the MiSTer core (outside the workspace) |
---
@@ -392,33 +390,39 @@ detailed in [`docs/architecture.md`](docs/architecture.md) and
## Current release
-RustyNES's current release is **v3.7.1 "Imprint"** (2026-11-15) — every file labelled with its copyright holder and licence (REUSE 3.3), the test ROMs whose authors stated no licence no longer called public domain, the licence notices shipped in the Android and iOS apps and on the web site, the MiSTer core's FDS drive and battery saves fixed, and a fresh spectator id for each hosted match. Built on **v3.7.0 "Spindle"** (2026-11-10) — the Famicom Disk System on the MiSTer core, spectators who join a match through the hosted relay, opt-in desync forensics, live ROM edits recorded as BPS patches, and the mobile extras. Built on **v3.6.2 "Latchkey"** (2026-11-06) — the latest AccuracyCoin, passed in full (147 of 147), and *Rad Racer*'s stray tiles at the right of the road and the horizon hidden by a switchable per-game correction that departs from hardware on purpose, raising the emulation epoch to 10. Built on **v3.6.1 "Threshold"** (2026-11-05) — every dependency at its newest compatible release in one change, the MMC5's background-fetch window ended where rendering ends in both cores, the MMC5 split's first two tiles taken from the right row, a TAStudio project bounded by its decoded size, and, on the MiSTer core, save states tied to their region and the MMC5 on PAL and Dendy. Built on **v3.6.0 "Octave"** (2026-10-28) — the noise channel plays at its documented pitch (about an octave higher than before, in every game that uses it; epoch 8), NSF files play again, the MiSTer core runs PAL and Dendy consoles at full speed, and a source-level homebrew debugger, audio stems, NSF ripping and libretro Core Options v2 arrive. Built on **v3.5.1 "Reprise"** (2026-10-23) — the MMC5's split-screen and extended-attribute CHR banks apply only while the PPU renders, in both cores, a key held while it is rebound is released, and devices and pipes are refused as files to open. Built on **v3.5.0 "Chorus"** (2026-10-22) — creator tools: movies record every input the core takes (.rnm format 7), Lua gains WebSockets and real shared memory, an MCP server, speedrun auto-timing and dump checks arrive, the MMC5 scanline IRQ is fixed (epoch 6), and the MiSTer core adds the MMC5, VRC6, Namco 163, VRC7 (silent) and Bandai FCG boards, off the die only. Built on **v3.4.2 "Countersign"** (2026-10-20) — the RetroArch core loads on Apple Silicon Macs again. Built on **v3.4.1 "Beacon"** (2026-10-19) — the hosted netplay lobby live with the browser and mobile builds pointing at it (the TURN relay deployed but held off: Cloudflare kept honouring expired and revoked credentials), the browser RetroAchievements build fixed (web RA held until RetroAchievements answers the integration request), version-named MiSTer release assets, and the MiSTer save engine's cartridge-change defects and v3.4.0's two build findings fixed. Built on **v3.4.0 "Waypoint"** (2026-10-18) — netplay authenticated and three and four players on the desktop, RetroAchievements hardcore held to RA's full block list, the hosted services shipped as code (deployed in v3.4.1), the window thread's CPU halved, and the MiSTer core's headline build made the off-die one, with save states, rewind and Phase F3a's boards. Built on **v3.3.0 "Plumbline"** (2026-10-16) — v3.2.0's leftovers settled and its claims re-measured: CHR-RAM writes go through the bank registers on seven boards, mapper 71 decodes its bank select as documented, v3.1.x Bandai states load again, a v3.2.0 performance figure is withdrawn, the IRQ trace goldens became a test, and, in simulation, the MiSTer core's off-die build reads CHR-RAM back and loads CHR correctly. Built on **v3.2.0 "Confluence"** (2026-10-15) — every v3.2.0 branch in both repositories brought into one release: 17 mapper families (208 in all), the VRC4 IRQ fix, an AI remediation branch audited change by change, netplay protocol 8, slim libretro states, and sixteen more boards on the MiSTer core. Built on **v3.1.0 "Bellwether"** (2026-10-08) — the AccuracyCoin re-sync and an honest 146/146, the CPU overclock and the sprite-limit option in movies and netplay, PAL emphasis, the alternate MMC3, rewind and run-ahead on the Vs. cabinet, and the MiSTer core matched to all of it. Built on **v3.0.1 "Mortar"** (2026-10-07) — a maintenance release: one game's graphics fixed, the MiSTer core's last MMC3 rule exception tested, Rust 1.99 everywhere, every unanswered bot review answered, and the plan to v4.0.0. Built on **v3.0.0 "Cornerstone"** (2026-10-06) — the API major: every break since v2.x in one place, a core timing epoch for movies and netplay, the last MMC3 timing gap closed in both cores, and a release-candidate MiSTer core. Built on **v2.9.9 "Ballast"** (2026-10-04) — the release candidate for v3.0.0: the audits re-run, MMC3 and MMC5 by their documentation, audio exact across save states, and the MiSTer core moved onto it. Built on **v2.9.8 "Vanguard"** (2026-10-02) — the preparation release for v3.0.0: v3.0.0's breaking changes landed early (a save identity that ignores the header, old states and movies refused, movies and netplay that record the machine, the API removals), every staged game was booted and the defects found were fixed, and the game database's corrections reach every platform. Built on **v2.9.7 "Tandem"** (2026-09-30) — the desktop's features on the web and on phones, the release binaries built with every native feature, and a PPU A12 fix found by real games: Acclaim's MC-ACC games, the J.Y. ASIC and mapper 91 now count at their documented rates. Built on **v2.9.6 "Roster"** (2026-09-30) — seventeen mapper families written from their NESdev pages (174 → 191), GTROM promoted to Curated with a modelled flash chip whose saves persist, mapper 4's NES 2.0 submappers corrected (MMC6, NEC, MC-ACC, T9552), and the local commercial suites re-baselined after drifting unread since about v2.0.0.
+RustyNES's current release is **v3.7.1 "Imprint"** (2026-11-15). What it
+changed is in [`CHANGELOG.md`](CHANGELOG.md), which lists every release back to
+v0.1.0, and in the [release notes](.github/release-notes/); the binaries are on
+the [Releases page](https://github.com/doublegate/RustyNES/releases).
-**v3.0.0 is the API major** ([ADR 0043](docs/adr/0043-v3-is-the-api-major-and-a-release-candidate-core.md)).
-It gathers every breaking change since v2.x, most of them made early in v2.9.8 and
-v2.9.9, and adds the last: movies and netplay carry an emulation epoch
-([ADR 0045](docs/adr/0045-a-core-timing-epoch-guards-movies-and-netplay.md)), and
-four more public structs became `#[non_exhaustive]`. Its
-[release notes](.github/release-notes/v3.0.0.md) restate every break by audience.
-
-The per-release detail, back to v0.1.0, is in [`CHANGELOG.md`](CHANGELOG.md) and
-on the [Releases page](https://github.com/doublegate/RustyNES/releases).
+**Compatibility.** `.rnm` movies and netplay sessions carry the emulation
+epoch they were made under
+([ADR 0045](docs/adr/0045-a-core-timing-epoch-guards-movies-and-netplay.md)). A
+release that changes what the emulator produces raises it, and a movie or peer
+from a different epoch is refused with its reason rather than replayed wrong.
+Save states are not tied to the epoch; they carry their own format version,
+and a state a release can no longer read is refused, which its CHANGELOG entry
+says.
---
## Roadmap
-**v3.0.0 has shipped**: the API major with a release-candidate MiSTer core
-([ADR 0043](docs/adr/0043-v3-is-the-api-major-and-a-release-candidate-core.md)).
-Next is **v3.x, hardware verification**: the MiSTer core on a SuperStation One,
-the mobile apps on real devices, and the fixes each produces
-([`v3.x-hardware-verification-plan.md`](to-dos/plans/v3.x-hardware-verification-plan.md)).
-A change that alters what the emulator produces raises the emulation epoch, so
-v3.x releases that emulate identically still share movies and netplay.
+The plan is [`to-dos/ROADMAP.md`](to-dos/ROADMAP.md), with one plan file per
+release in [`to-dos/plans/`](to-dos/plans/README.md), indexed by the
+[v3.1-to-v4.0 line plan](to-dos/plans/v3.1-to-v4.0-line-plan.md). In outline:
+
+- **v3.7.2:** the MiSTer core's open save-transfer issue and the deferred
+ timing runs.
+- **v3.8.0:** the residuals, and the rest of the console on the MiSTer core.
+- **v3.9.0:** the MiSTer RTL feature freeze and its release-candidate pair.
+- **The hardware release** (the last v3.9.x): the MiSTer core on a SuperStation
+ One and the mobile apps on real devices, with the fixes each produces
+ ([`v3.x-hardware-verification-plan.md`](to-dos/plans/v3.x-hardware-verification-plan.md)).
+- **v4.0.0:** the remaining public enums made `#[non_exhaustive]`, and MiSTer
+ feature parity.
-The full plan is [`to-dos/ROADMAP.md`](to-dos/ROADMAP.md), with one plan per
-release in [`to-dos/plans/`](to-dos/plans/README.md). A free mobile store listing
-may follow later, with no monetization of any kind.
+A free mobile store listing may follow, with no monetization of any kind.
---
@@ -431,14 +435,13 @@ ported to an FPGA: what can be built is a new implementation checked against thi
one, cycle by cycle.
Its co-simulation ladder covers the 6502, the bus and interrupts, the 2C02, the
-2A03, AccuracyCoin parity and twenty-one iNES mappers. Each release attaches a
-timing-closed bitstream pair; v3.3.0's (on-die and off-die, both at fitter seed 7,
-each compiled twice to the same bytes) is a **release candidate, not
-hardware-verified**. Its co-simulation ladder reads 260 passed, 0 failed, 3
-expected failures on-die and 263 / 0 / 3 off-die. **No hardware has run any
-bitstream yet**, so a booting core, a synced display, audible sound and a working
-pad are not claimed. The details, and what
-each rung can and cannot verify, are in [`docs/mister.md`](docs/mister.md).
+2A03, AccuracyCoin parity, the mappers it implements, save states and the
+Famicom Disk System. Each release attaches a timing-closed bitstream pair, an
+off-die build and an on-die "Lite" build, as a **release candidate, not
+hardware-verified**; the release notes give each pair's ladder result and
+timing margins. **No hardware has run any bitstream yet**, so a booting core, a
+synced display, audible sound and a working pad are not claimed. The details,
+and what each rung can and cannot verify, are in [`docs/mister.md`](docs/mister.md).
@@ -485,13 +488,17 @@ and [`docs/ai-emulator-provenance-guardrails.md`](docs/ai-emulator-provenance-gu
Reference emulators are black-box oracles: their output may be compared, and their
source is never read.
-Permissive components (emu2413, TriCNES, `rcheevos`, blip_buf and the bundled
-fonts) are credited in `NOTICE`. The test ROMs under `tests/roms/` are CC0, MIT,
+Permissive components (emu2413, TriCNES, `rcheevos`, blip_buf,
+`rust-libretro-sys`, `libretro.h`, Lua, ares and the bundled fonts) are credited
+in `NOTICE`. The test ROMs under `tests/roms/` are CC0, MIT,
zlib or similarly permissive where their authors licensed them; blargg's and
kevtris's suites and the ROMs mirrored from `christopherpow/nes-test-roms` state no
licence and are redistributed as test material that the GPL does not cover
([`tests/roms/LICENSES.md`](tests/roms/LICENSES.md)). **No commercial ROMs are
included**: dumps for the commercial-ROM oracle must come from cartridges you own.
+Screenshots of commercial games, including two images in this README, show
+their publishers' artwork, which the GPL does not cover and no licence here
+grants.
The tree follows the [REUSE 3.3](https://reuse.software/spec-3.3/) specification:
every file's copyright and licence are stated in its own SPDX header or in
From acdf36ab0aca787cbacdfe35d4840021c4b72acb Mon Sep 17 00:00:00 2001
From: DoubleGate
Date: Sun, 15 Nov 2026 22:26:32 -0500
Subject: [PATCH 15/18] docs(mister): the co-simulation boundary as it stands,
history archived
docs/mister.md had become a release diary: a header describing the plan
up to v3.0.0, reverse-dated sections from v2.5.1 to v2.6.15, and gate
counts from v2.6.x. At the maintainer's request it now describes the
MiSTer co-simulation boundary as it is at v3.7.1 (1,494 -> 677 lines).
Nothing is lost. docs/archive/mister-history-v2.5-to-v3.0.md holds the
whole previous file verbatim, under a frozen-file header. A diff
confirms the only other changes: the H1, and 14 relative link targets
rewritten for the archive's directory. docs/archive/ is already in
.markdownlintignore and mkdocs' exclude_docs, and REUSE's docs/** default
covers it.
The new outline:
- a "No hardware has run any bitstream" callout (ADR 0043);
- what the core is and is not;
- the two builds (FDS off-die only);
- the HDL firewall, kept verbatim;
- rustynes-cosim, golden formats and the manifest;
- the null-DUT gate;
- replay rather than lockstep, and hash first;
- gate versus diagnostic;
- how the ladder runs (fetch-goldens and VERIFY=1, golden-provenance,
LADDER_JOBS, xfail, CKPT_DENY);
- where oracle disagreements are recorded;
- a current rung table;
- pointers.
No count is restated: the ladder figures live in the sibling README and
each release's notes.
Corrected while restating, each checked against the code:
- the null-DUT tests live in rustynes-cosim/src/lib.rs (the cited
tests/null_dut_self_diff.rs no longer exists);
- the golden-format table gains .fetch.bin, .apu.bin, .ext_audio.bin,
.index_fb_frames.bin, .ppu_state.csv and .ram_init.bin;
- all six mandatory trace features are listed (two were);
- the manifest description gains bios_sha256, the counts,
sprite_limit_off and press_start;
- the Zapper stimulus and its refusals are described.
One gap is recorded, not fixed. The firewall section (like ADR 0037)
says CI carries "a path denylist plus an identifier grep". The sibling's
ci.yml has the directory denylist (NES_MiSTer, fpganes) and an SPDX
check, and no identifier grep exists there or here; re-checked by hand.
The sentence stays as written, with a dated note under it, for the
maintainer to decide between adding the grep and amending the ADR.
Gates:
- markdownlint passed on both files.
- Tests:
- release_state_prose_audit 9/0;
- personal_path_audit 2/0;
- mister_source_map_audit 6/0.
- reuse lint 4135/4135.
- 32 relative links checked, 0 broken.
- No mister.md#anchor link exists anywhere in the repository, so no stub
headings were needed.
Co-Authored-By: Claude Opus 5.5
---
docs/archive/mister-history-v2.5-to-v3.0.md | 1519 +++++++++++++++++
docs/mister.md | 1665 +++++--------------
2 files changed, 1943 insertions(+), 1241 deletions(-)
create mode 100644 docs/archive/mister-history-v2.5-to-v3.0.md
diff --git a/docs/archive/mister-history-v2.5-to-v3.0.md b/docs/archive/mister-history-v2.5-to-v3.0.md
new file mode 100644
index 00000000..abb88f4f
--- /dev/null
+++ b/docs/archive/mister-history-v2.5-to-v3.0.md
@@ -0,0 +1,1519 @@
+# MiSTer co-simulation: the release record, v2.4.1 to v3.0.x
+
+**Frozen. Do not edit.** This is the text of `docs/mister.md` as it stood on
+2026-11-15, before that file was rewritten to describe the co-simulation
+boundary as it is at v3.7.1 "Imprint". It is kept so that nothing the old file
+said is lost: the per-release sections (v2.5.1 to v2.6.15), the rung records
+(rungs 1, 4 and 5), the two pre-RTL risks settled at v2.4.3, and the original
+wording of every reference section the rewrite restated.
+
+What changed on the way here, and nothing else:
+
+- The original H1 title, *"MiSTer FPGA and SuperStation One - the co-simulation
+ boundary"*, is replaced by this file's own title and note.
+- Relative link targets are rewritten for this directory (`adr/...` became
+ `../adr/...`, `../to-dos/...` became `../../to-dos/...`, `accuracy-ledger.md`
+ became `../accuracy-ledger.md`). Link text and every other byte are as they
+ were.
+
+Everything below the rule is a historical record. Counts, release numbers and
+"now" statements are true of the release each section names, not of the current
+tree. Phrases such as "the section at the top of this file" refer to the old
+file's layout. The banner directly below the rule ("Spec, not history") applied
+to the live file, not to this copy. For the current state, read
+[`../mister.md`](../mister.md) and the sibling repository's `README.md`.
+
+---
+
+**Spec, not history.** Update this file in the same change as any behaviour
+change to `crates/rustynes-cosim` or the golden formats it emits.
+
+**Decision records:** [ADR 0037](../adr/0037-mister-fpga-core-independent-hdl-implementation.md)
+(the programme and the HDL firewall) ·
+[ADR 0038](../adr/0038-cosim-interrupt-injection-api.md) (the interrupt-injection API).
+**Execution plan:** the line to **v3.0.0**, which shipped on 2026-10-06 ([ADR 0041](../adr/0041-hardware-release-is-v3.0.0.md), as amended by ADR 0043):
+[`v2.7.x`](../../to-dos/plans/v2.7.x-core-frontend-audit-plan.md) (the core and frontend audits; oracle-only, so the bitstream does not change),
+[`v2.8.x`](../../to-dos/plans/v2.8.x-libretro-rtl-audit-plan.md) (the RTL audit and the off-die build),
+[`v2.9.x`](../../to-dos/plans/v2.9.x-final-audit-and-hardware-plan.md) (the board) and
+[`v3.0.0`](../../to-dos/plans/v3.0.0-cornerstone-plan.md), which ADR 0043 made the API major with a
+release-candidate core; the hardware-verified core is the later
+[`v3.x`](../../to-dos/plans/v3.x-hardware-verification-plan.md) release. Before that,
+[`to-dos/plans/v2.7.0-mister-core-plan.md`](../../to-dos/plans/v2.7.0-mister-core-plan.md) (superseded)
+-- which **superseded** [`v2.5.0-fabric-plan.md`](../../to-dos/plans/v2.5.0-fabric-plan.md),
+which is delivered.
+**Execution tracking:** [`to-dos/mister/`](../../to-dos/mister/).
+**Research archive:** [`to-dos/plans/research/v2.5.0-research-mister-fpga.md`](../../to-dos/plans/research/v2.5.0-research-mister-fpga.md),
+plus four dated files in `ref-docs/` (contribution requirements, the MiSTer
+framework, the hardware **source map**, and alternative FPGA targets).
+**Device-under-test:** (private).
+
+## The ladder becomes something a reviewer can run (v2.6.15)
+
+Rung 6 is blocked on hardware and v2.7.0 now waits for it, so this release is
+about the other half of a submission: not what the core does, but what a
+reviewer can **check** about it.
+
+The contributing page states the bar for AI-assisted code in one sentence --
+*"Fully AI generated code should meet a minimum reasonable bar for readability
+and include some evidence of quality and accuracy testing."* This programme's
+evidence is 148 co-simulation gates -- 142 at the start of v2.6.15, plus the five
+it added and the one v2.6.16 added. Every gate but five carries a mutation
+record; the exceptions are the five blargg `cpu_interrupts_v2` verdict gates
+v2.6.15 added, which are independent-oracle verdicts with no mutation recorded
+against them (no rung document and neither `tb/mutate.sh` nor
+`tb/mutate_apu.sh` names them; noted at v3.0.1). 147 of them run on the die; the 148th measures the off-die memory system and reports N/A
+there, because a gate on the SDRAM path cannot exist in a build with no SDRAM. And
+`tb/regress.sh` says in its own header that it *"is NOT a CI gate and cannot
+be"*, because it needs the oracle's goldens and a cargo build of a crate in
+another repository. So the strongest thing here was a set of **documents
+describing checks a reader cannot run**.
+
+`docs/golden-fetching.md` in the sibling specified the fix and carried
+`Status: NOT BUILT`. The smallest end-to-end slice is now built: the nine
+opcode-group ROMs export from a **pinned** oracle commit (`tb/ORACLE_COMMIT`)
+and compare in CI. It is a subset -- no PPU, no APU, no AccuracyCoin, no nestest
+-- and the job's name says so, because a job that looks like a gate and is not
+is the defect this programme keeps finding in itself.
+
+**Pinning is the point rather than a caveat.** The determinism contract covers
+the framebuffer and the audio and says nothing about trace-format stability, so
+an unpinned oracle could turn the sibling red for a reason unrelated to its RTL.
+Green there means green against one recorded commit, and moving the pin is a
+deliberate edit.
+
+### The first independent interrupt oracle
+
+`docs/rung5-accuracycoin.md` carries the sentence this closes: *"Rung 4 had
+blargg as an independent check and it found six defects no self-written gate
+could see; rung 5 has no equivalent, and that is the single most important
+sentence in this document."* Interrupts had the same hole -- every interrupt
+gate compares the DUT against RustyNES, so a shared error between them is
+invisible by construction.
+
+`cpu_interrupts_v2`'s five single-purpose ROMs are now verdict gates, on
+**mapper 0** (the combined ROM is mapper 1; the singles are not, which removes
+MMC1 as a variable). `5-branch_delays_irq` is the sharpest of them: *"A taken
+non-page-crossing branch ignores IRQ during its last clock, so that next
+instruction executes before the IRQ."* That is the exact behaviour v2.6.7
+changed in the **oracle** -- caveat C6, `skip_irq_sample_q` -- from documentation
+reasoning alone, with no ROM adjudicating it. This one adjudicates it, on both
+consoles.
+
+Alignment is **recorded rather than assumed**: blargg's readme says
+`2-nmi_and_brk` *"Occasionally fails on NES due to PPU-CPU synchronization"*, so
+its verdict is alignment-sensitive by design and a pass is a pass at the shipped
+alignment, not an absolute one.
+
+### `T-ORACLE-001`'s opening claim is retracted
+
+The ticket says RustyNES never clocks the MMC3 counter on the pre-render line.
+It does. `mmc3_test_2/2-details` sub-test 8 is, verbatim, *"Counter should be
+clocked 241 times in PPU frame"* -- 240 visible plus the pre-render line -- and
+RustyNES passes it, as it has every release.
+
+The claim came from `--ppu-state-trace`, and the ticket's own *instrument traps*
+section says why that instrument cannot answer the question: it carries no CHR
+address column, so it reports what the sprite state was and never what address
+was driven. **A trace that could not see the event was read as evidence the
+event did not happen.** This is the second time an instrument has been mistaken
+for its subject here -- v2.6.9's `apuconflict039` was the first, where nine
+divergences "by design" were a defect in the testbench.
+
+The verdicts are unchanged: the oracle still fails `4-scanline_timing` at
+sub-test 3 and the DUT at sub-test 12, so on that ROM the DUT is still the more
+accurate of the two and `mapper4mmc3irq065` stays unregistered. Only the
+explanation was wrong.
+
+### Three claims that became checks
+
+`sys/` verbatim rested on **one measurement taken at v2.6.6** plus a manual
+procedure nothing ran -- eight releases, several of them touching the build. It
+now pins all 57 files and catches a changed, a missing **and a stray** file; the
+third mode is why the directory is enumerated rather than the manifest merely
+walked, and it is not hypothetical, since `sys/README.md` and `sys/.gitkeep`
+both lived there through v2.6.5. Re-verified against upstream in the same pass:
+`Template_MiSTer`'s HEAD **is** the pinned commit and a clone reports 0
+differences -- two claims, measured separately, because a vendored tree can be
+faithful to a commit upstream has moved past.
+
+The `.qsf` published **two** seed sweeps disagreeing about the pinned seed's
+margin by 0.155 ns, one of them a number the current RTL cannot reproduce. And
+the bitstream **name** turned out not to be a style question at all: the
+distribution builder skips any file whose stem does not end in an underscore
+plus eight digits, so a version-named core would have appeared in the Cores
+table and shipped nothing.
+
+## Rung 4 OPENS: the pulse channels and the frame counter (v2.5.9)
+
+Both pulses -- timer, 8-step duty sequencer, length counter, envelope, the
+sweep MUTE -- plus the frame counter in both modes with its IRQ and the
+`$4015`/`$4017` register file. Triangle, noise and DMC are v2.6.0/v2.6.1.
+
+**The partition was fixed before the rung** (the sibling's `docs/rung4-apu.md`),
+because the APU is the hardest chip here to gate honestly: what it produces is
+an analog level and what an emulator computes is a number. Gates are the
+`$4015` read value, the `/IRQ` pin and each channel's **integer** DAC input;
+`MixRecord`'s `f32` mix fields, the sequencer step index and `apu_phase` are
+diagnostics. `--apu-trace` on `nes_golden_export` exports the integer levels
+only.
+
+**The stimulus measurement found four ROM defects before any gate ran** --
+length index 3 is 2 and not 254, the 6502 boots with I set so `CLI` is
+mandatory, two channels at one volume are indistinguishable, and power-on work
+RAM is seeded rather than zeroed. Four findings in the DUT: the duty sequencer
+counts UP, the 4-step constants must be consistently 0-based, `$4017` bit 7
+clocks a quarter and half frame IMMEDIATELY, and the `$4017` reset delay depends
+on bit 7 -- which the wiki's "3 or 4 CPU clock cycles" does not settle.
+
+`apulen027` is exact on both surfaces; `apupulse026`'s bus surface is 3 and its
+channel levels 1,000 -- **500 runs of exactly two cycles, one per edge**, a
+uniform one-tick `$4003` write-parity sensitivity the first stimulus hid. Two
+fixes tried, both rejected by measurement. v2.6.0's first item. **Nine of ten
+mutations CAUGHT**, the two exceptions both indicting the stimulus.
+
+## Rung 7 opens: the cartridge, and two PPU defects A12 found (v2.6.9)
+
+**Five boards land** -- UxROM (2), CNROM (3), AxROM (7), MMC1 (1) and MMC3 (4)
+-- in one `rtl/cart/cart.sv` whose mapper number is a runtime INPUT, because on
+MiSTer the header arrives with the game and a parameter would need a different
+bitstream per cartridge. All five match the oracle on every cycle and every
+checkpoint, and nine of nine mutations are CAUGHT.
+
+**"Five" here is rung 7's boards, not the console's.** NROM landed at rung 5, so
+the core supports **six**: NROM, MMC1, UxROM, CNROM, MMC3 and AxROM. Both counts
+are correct and they are easy to reconcile wrongly -- a reviewer did, reading
+this line against the sibling's six commercial captures.
+
+**Half the earlier "rung 7 is blocked" claim was wrong, and this corrects it.**
+Rung 7 has two parts and only one ever needed hardware: the SDRAM controller,
+whose acceptance is read/write timing against a real part. The mapper logic is
+pure logic, verifiable exactly as rungs 1-5 were. Treating them as one item
+deferred five boards behind a blocker that never applied to them.
+
+**The MMC3 scanline counter is the first thing in this core's history to consume
+PPU A12, and it found two PPU defects on its first day** -- both invisible for
+four releases because nothing had looked:
+
+- `dummy_fetch` named the RECORD dots (337, 339), not the fetch. A fetch is two
+ dots, so on the even dots the address fell through to `v_addr` and the PPU put
+ `v` itself on the CHR bus; `v` bit 12 is `fine_y[0]`, which alternates every
+ scanline.
+- The **idle dot**. With the first fixed the extras moved rather than vanished,
+ to dot 0 -- the only dot of a rendering line that drives no fetch, and so the
+ only one still reaching the same fallback.
+
+Filtered A12 clocks went 1,445 -> **965, every one at dot 261**. The wiki
+gives 241 clocks per frame, and `965 = 241 x 4 + 1` -- four frames plus one
+clock, the run not ending on a frame boundary. Interrupts taken went 218-vs-158 to
+**158 and 158**, with byte-identical work RAM, and the DUT/oracle divergence
+from 10,821 cycles to 950.
+
+**The residual was two things wearing one appearance, and blargg separated
+them.** `mmc3_test_2` scores **4 of 6 on the DUT and 4 of 6 on the oracle,
+failing the same two ROMs** -- `6-MMC3_alt` correctly, since it is NEC rev B and
+both target Sharp rev A. Within `4-scanline_timing` the oracle fails sub-test #3
+(its documented, permanently-deferred 1-cycle bracket, ADR 0002 F5.0) and the
+DUT fails #2, *"Scanline 0 IRQ should occur later when `$2000=$08`"*.
+
+So part of the offset is the oracle's own residual, which must NOT be fitted to
+-- that is the failure the v2.6.0 audit named. The other part is a real DUT
+defect, **shown pre-existing by control**: with both PPU fixes reverted it still
+fails #2. It is left open with a 27-second reproducer and a validated pass/fail
+signal, rather than tuned away against a reference that is itself off on the
+same axis.
+
+## An exclusion hides improvement as well as regression (v2.6.9)
+
+The co-simulation suite gates most goldens on a rolling per-cycle **checkpoint**
+hash, and carried a **deny list** of streams excluded from it. v2.6.8 established
+that such a list is an *assertion about the thing under test* — one that v2.6.7
+had invalidated twice over by changing both the DUT and the harness — and
+re-measured six entries, retiring four. v2.6.9 goes one level down, to the
+mechanism, and finds two things.
+
+**First, "by design" was a claim about the instrument.** `apuconflict039`'s bus
+surface had been excluded since v2.6.2 under a note saying it "carries nine
+divergences **by design**". **Six of the nine had already closed** and nobody
+could see it, because a denied stream is denied in both directions. The **three
+that remained** were a defect in the **harness**: on a cycle
+where the CPU is held, `tb/cpu_main.cpp` built the trace record's `bus_data` from
+a stale local rather than from the RTL's own open-bus latch. The two differ on
+exactly one rule, and it is a rule the RTL already implements correctly — a read
+of the APU status register is *internal to the 2A03* and does not drive the
+external lines, so the latch holds across it while a local tracking what the CPU
+*received* does not. Reading the latch makes the stream **identical on all
+357,361 overlapping cycles and all 88 checkpoints**.
+
+The release plan predicted a **DUT defect** here and reasoned from the correct
+rule to get there. The reasoning was sound, the rule was right, and the defect
+was one layer further out — which is the standing lesson: a measurement
+disagreeing with a rule you are confident in can indict the measurement.
+
+**Second, a denied stream is denied ENTIRELY**, so a golden whose divergence is
+one cycle out of 357,361 forfeits the other 357,360 — and an entry that silently
+*improves* is exactly as invisible as one that silently regresses.
+
+The planned fix was an allowance by **checkpoint index**, and it was implemented,
+run, and **refuted**: `tb/checkpoint.h` chains its FNV-1a, so one divergent cycle
+poisons every checkpoint after it. Allowing the first differing window moved the
+failure to the next one; allowing the rest is the all-or-nothing deny it was
+meant to replace. The allowance moved to a new **per-cycle** nine-field
+comparator, `tb/obs_diff9.py --allow-cycle`, where an attributed difference costs
+**one cycle instead of seventy-one checkpoints**.
+
+It fails **both ways**, which is what makes it adoptable: an allowed cycle that
+stops differing is a FAILURE, so an improving DUT cannot leave a stale allowance
+quietly hiding coverage. Six mutations confirm it, including a cycle named
+outside the compared window being **refused** rather than allowed to match
+nothing.
+
+The one remaining entry, `ppuoamcorrupt052`, differs on exactly one cycle —
+70,627 — which is the documented OAM-corruption asymmetry where **the DUT
+implements more of the documented rule than the oracle does** and no available
+gate can adjudicate. It is allowed and named, not resolved.
+
+## The bitstream is published from v2.6.7 (maintainer decision, 2026-08-30)
+
+**Every release from v2.6.7 ships a `.rbf`** — committed to the sibling's
+`releases/` and attached as an asset to the GitHub release on **both**
+repositories. This reverses v2.6.6, which produced a bitstream and deliberately
+did not publish it.
+
+**Why the reversal is right.** The MiSTer distribution mechanism reads the
+`.rbf` out of the *repository*'s `releases/` — since v2.6.15 as
+`releases/RustyNES_YYYYMMDD.rbf`, the only form both MiSTer parsers accept (the
+GitHub releases carry the same bytes version-named, `RustyNES_MiSTer-vX.Y.Z.rbf`
+and, from v3.4.0, `RustyNES_MiSTer-vX.Y.Z-lite.rbf`; every release's assets
+were renamed to that form on 2026-10-18; the sibling's
+`docs/bitstream-release.md`) — so an empty
+`releases/` does not describe a cautious core — it describes an undistributable
+one, withheld from exactly the people who own the boards this project does not.
+And a claim nobody made is not the same as a claim marked unverified: only the
+second is usable. So the caution moves from an absence into a disclosure.
+
+**What every release body must therefore state**, because it is what the ladder
+does and does not reach:
+
+- **No hardware has run the bitstream** (true until rung 6 closes). A booting
+ core, a synced display, audible audio and a working controller are not claimed.
+- The co-simulation ladder establishes per-cycle agreement with a 141/141
+ emulator on the declared compare surfaces, and AccuracyCoin agreement entry for
+ entry across all 146 entries.
+- **Unverified by construction**: the PPU gate compares the *pre-palette* index
+ and the APU gate compares *per-channel integer levels*, so the palette, the
+ video timing constants, the audio's absolute level and its band-limiting are
+ downstream of every gate. That partition is deliberate — it is what stops a
+ palette difference masquerading as a rendering one — and its price is that
+ those four properties have no evidence behind them until a board runs the file.
+- The Quartus version, device, error and warning counts, worst setup and hold
+ slack, and the **pinned fitter seed**. The seed is load-bearing: two compiles of
+ identical RTL have landed a framework HDMI path at +0.386 ns and −0.086 ns, so
+ "timing closes" without a pinned seed is a statement about one placement.
+
+**Mechanism.** `scripts/release-rbf.sh ` in the sibling builds, verifies and
+uploads. It checks errors and per-clock slack **against the reports rather than
+the exit code**, because Quartus has been observed to abort after the resource
+summary and still exit 0. Full procedure and rationale:
+`RustyNES_MiSTer/docs/bitstream-release.md`.
+
+**One artifact, two boards.** The SuperStation One is a Cyclone V console that
+forks `Distribution_MiSTer` and consumes MiSTer cores directly, so the same
+`.rbf` is what both take. Whether the *identical file* boots both is a hardware
+claim and stays deferred.
+
+## Rung 3 CLOSES: VBlank, NMI, the `$2002` race (v2.5.8)
+
+The VBlank flag's full CPU-visible behaviour — the set, the clear, the
+destructive read, `suppress_vbl` for the one-clock-before race, and **the PPU's
+/NMI wired to the CPU for the first time**. Four ROMs carry it, every one with
+its stimulus measured from the oracle's trace before any gate ran; a first
+draft put a handler inside the power-on NOP slide and reset executed it, both
+sides agreeing because both read the same wrong ROM.
+
+**Both structural fixes were deletions.** The testbench's cycle split was
+`[2 pre-dots | access | 1 post]` and the oracle's is `[1 | access | 2]`
+(`read_split(12) = (5,7)`): a ~2-dot /NMI pulse from a read racing the VBL set
+was invisible to the DUT's end-of-cycle sample, and `PPU_LEAD=3` +
+`ACCESS_DOT=1` (same absolute access dot, moved boundary) fixed it — the
+pulse-stretcher built first was measured dead and deleted. And
+`render_for_skip` — v2.5.7's deferred skip-check delay — does not exist: the
+oracle's two-PPU-clock rule plus the commit-edge sampling asymmetry lands
+exactly on the rendering enable, so the extra tap was deleted and the pipe
+shrank to one stage. `ppuvbl024` had caught the DUT skipping ten pre-renders
+the oracle never skipped, invisible to the bus gate for eight frames because
+NMI delivery quantizes away single-dot drifts.
+
+**Twelve of twelve mutations CAUGHT** — the last via a cadence-breaking frame,
+because its one firing landing (enable at pre-render dot 338, odd frame) is
+unreachable by any fixed-cadence ROM: the 3-dot CPU quantum and the skip's
+1-dot drift lock odd-frame landings to one residue mod 3.
+
+**Reproducing it:** none of these is a CI gate, so the exact invocations and
+the non-zero count each prints are recorded in the sibling's
+`docs/rung3-ppu.md` under *Reproducing v2.5.8, exactly* -- including that
+`--irq-trace` is **mandatory** for every PPU golden export, without which no
+`obs.bin` is written and the bus gate cannot run at all.
+
+**nestest 0-diff at 5,002,992 cycles — the 5M window closes**, and with it
+rung 3's acceptance criteria in full. The harness serves open-bus `$40` for
+`$4016`/`$4017`; the next divergence anywhere is an APU or controller surface,
+which is rung 4. Full record: the sibling's `docs/rung3-ppu.md`.
+
+## Rung 3 continues: sprite rendering, and the phase (v2.5.7)
+
+Sprite rendering, priority, the sprite-0 hit and its no-hit-at-x=255 quirk, the
+left-8 masks, the garbage nametable fetches and the 337/339 dummies — and the
+release's real finding: **the CPU–PPU power-on phase was wrong by two dots, and
+every OAM window was compensating.** The boot traces agreed on `scanline`/`dot`
+at every instruction boundary while the per-cycle mappings differed by exactly
+two — a phase error hidden by an equal record-point offset, two errors
+cancelling. `PPU_LEAD=2` (the earlier sweep tried 0 and 3; the answer sat
+between them) moves every window from documented-minus-three to
+**documented-minus-one, which is registered-assignment semantics and no residual
+fudge** — the code came to what the RTL's comments had claimed all along.
+
+**Every gate in the rung is exact for the first time**: `ppuspr019/020/021`
+119,115 cycles each, `ppuscroll` 49,998, `ppusprender` 119,114, `ppusprite`
+59,993, `ppuregs` 12,841, fetch traces 7,058 / 88,685 (the v2.5.4 narrowing is
+**removed** — sprite fetches and the dummies are compared now), all three index
+framebuffers 61,440, `nestest` 59,554 — plus **`ppu-phase-gate`**, new: the
+inverse of `cpu-gate`'s skip list, `scanline`/`dot` only over twelve frames,
+98,562 records, the only gate that can see the **odd-frame skipped dot**'s
+one-dot-per-odd-frame drift (implemented this release; five mutations CAUGHT).
+
+**All ten of the rung's mutation catalog are CAUGHT**, re-run in full at the
+corrected phase — the tenth (sprite-0 flag read from the register only) by
+`ppuspr020` at exactly one divergence, the read landing on the hit dot. Also
+found by instrument rather than argument: `PPU_SUBDOT` (master-clock-resolution
+clocking, built to test the half-dot between `read_split` and `write_split` —
+unobservable, now measured) exposed **a register file gated by nothing**; fixed
+with `cpu_ce`, a one-clock commit strobe, latent until v2.6.5 where a held
+address would have latched twelve times per access. Deferred with owners named:
+the VBlank-race stimulus and the skip-check delay (v2.5.8), `chr_wr` (v2.6.3).
+Full record: the sibling's `docs/rung3-ppu.md`.
+
+## Rung 3 continues: sprite evaluation (v2.5.6)
+
+The evaluation FSM, secondary OAM, the eight-sprite limit, the documented
+overflow-search bug and the wiki's step 4. **All 59,993 overlapping cycles
+match**, with **seven of eight mutations CAUGHT** and the baseline verified
+passing first. The programme plan named this the hardest single item in it.
+
+**The gate observed a model the diagnostic did not expose**, and that is the
+finding worth carrying out of this step. `ppu-state-trace` carries
+`sprite_eval_n`, `sprite_eval_m` and `sprite_eval_found`, which belong to the
+oracle's *real* evaluation FSM. What a CPU read of `$2004` returns does not come
+from that machine: it comes from `tick_oam_bus`, a second, side-effect-free model
+kept alongside it. So two edits made faithful to the traced fields each moved the
+DUT **away** from the observable — 41 → 112 and 39 → 68 — and were reverted as
+regressions. Adding `oam_bus_copybuffer` to `PpuStateRecord` at schema 2 is what
+made every later measurement valid; it immediately showed the FSM sitting frozen
+at `n = 34` while the bus kept walking for the rest of the line.
+
+**One of those two regressions was then right.** The overflow halt had been
+measured while phase 4 was itself mis-implemented, so it moved the DUT into a
+broken destination. Re-measured against a correct phase 4 it is worth 28 of the
+39. *A change rejected against a broken baseline is not a rejected change.*
+
+**And the fix that closed it is the opposite of the obvious one.** The wiki says
+phase 4 copies `OAM[n][0]`, but pinning the byte index to 0 is right on scanline
+55 and wrong on scanline 58: phase 4 advances only the high half of the address,
+so the low half keeps whatever ended the walk. Three of the four paths that
+finish evaluation clear it; the sprite-eval bug path does not.
+
+**Two mutants are INERT rather than uncaught, and a first pass got that wrong.**
+The `eval_ovf_cnt` reset was reported as fixing a latent defect the stimulus
+could not reach; the stale count in fact cannot occur — a probe fires zero times
+at 528 window ends while its inverted predicate fires 528, the trace is
+byte-identical without the reset, and the bound is structural (88 decide steps to
+the latest hit, consumed by 91, in a 96-step window). It is kept as defensive
+code, not as a fix. The second inert mutant is out of *scope* rather than
+unreachable: `sprite_overflow` reaches the CPU only via `$2002`, which this ROM
+never reads. Both were classified by byte comparison, because NOT CAUGHT has
+meant four different things here.
+
+Detail: `docs/rung3-ppu.md` in the sibling repository.
+
+## Rung 3 continues: background rendering (v2.5.5)
+
+The shift registers, the fine-X multiplexer, the palette lookup and a per-pixel
+index — the first full frame this core has drawn.
+
+**Gate:** `ppurender` **all 61,440 pixels match**, **fifteen mutations all
+CAUGHT**, baseline verified passing first. The surface is the **index**
+framebuffer, pre-palette, so a palette-table difference cannot masquerade as a
+rendering one — different bugs, different rungs.
+
+**The oracle needed no change at all.** `index_fb.bin` has been exported since
+v2.4.1: the third rung step in a row costing the oracle side nothing, which is
+what choosing the compare surface *before* the rung buys.
+
+**The fault was one pixel, and the incomplete fix identified the mechanism.** The
+first run differed on 46,730 of 61,440 pixels, which reads as a broken renderer
+and was not: 13 distinct values on both sides, near-identical histograms, and
+`act[x] == ref[x-1]`. The shift registers and the dot counter advance on the same
+edge, so the documented "shift on dots 2-257" applied each shift one dot after
+the pixel that should show it. Moving only the shift window took the first wrong
+pixel from x=9 to x=17 — one tile further in — which is what proved the reload
+was out of phase too. The resolution **removes** a register: the reload is the
+pattern-high fetch's own dot, so it takes `chr_din` directly.
+
+**Five NOT CAUGHT mutations indicted the stimulus, not the gate** — and one of
+them three times, for three different reasons: horizontal arrangement aliasing
+the nametables, a zero coarse-X scroll whose only wrap `copy_x` undid before it
+reached a pixel, and a fill whose 256-period ramp made both nametables
+byte-identical. Each fix looked like it had closed the hole. **Re-run mutations
+after a stimulus change, not only after a code change.**
+
+`fb_diff.py` refuses a reference frame too uniform to test anything and is
+demonstrated firing in all four paths; the window is **read** from the oracle's
+manifest rather than transcribed. `docs/golden-fetching.md` in the sibling
+repository now specifies the standing note that had sat across six releases —
+including the requirement that golden fetching use a **pinned oracle commit**.
+That pin is not a detail: the determinism contract covers the framebuffer and
+audio and says *nothing* about trace-format stability, so an unpinned fetcher
+would turn the DUT's CI red for a reason unrelated to its RTL.
+
+## Rung 3 continues: the background fetch pipeline (v2.5.4)
+
+NT / AT / pattern-low / pattern-high fetches on the documented 8-dot cadence,
+compared against the oracle as an **address-bus** trace -- real pins, so a
+correct chip cannot differ, which is what makes it a gate rather than a
+diagnostic under `docs/rung3-ppu.md`'s partition.
+
+**Gate:** `ppufetch` **6,247 background fetches / 0 divergences** on scanline,
+dot and address, across two rendering windows. **Eight mutations, all CAUGHT**,
+baseline verified passing first.
+
+**The comparison was narrowed and said so on every run.** At this release a
+rendering scanline issued 154 fetches and the gate compared the 136 background
+ones (dots 1-256 and 321-336), excluding sprite fetches and the two dummy
+nametable reads; `fetch_diff.py` printed the excluded count for both sides
+because a narrowing that is not announced reads as full coverage. **The
+narrowing is gone as of v2.5.7** -- `COMPARED_DOT_SPANS` is `(1, 340)`, sprite
+fetches and the dummies included.
+
+**The finding: the CPU access was presented two dots early, and no existing gate
+could see it.** The DUT issued one extra nametable fetch at the leading edge of
+each rendering window and dropped one at the trailing edge, both by the same two
+dots -- one quantity wrong by one constant, not two faults. The cause was in
+`tb/cpu_main.cpp`, which presented the access on the second of the cycle's three
+PPU dots; a 6502 commits a write and samples a read at **phi2**, the third.
+
+Five gates stayed green across the move, **in both directions**: rung 1's
+registers on nine ROMs, rung 2's per-cycle bus, the interrupt sweep, and the
+v2.5.2 register and v2.5.3 scroll gates. That is not evidence the shift was
+harmless. Every one of them reads state **once per CPU cycle**, so a uniform
+two-dot shift in when a write lands *inside* a cycle moves nothing they compare.
+This is the rung's first gate keyed to the DOT counter, and the first that could
+see it.
+
+**nestest more than doubled.** Rung 2's window was bounded at 27,396 cycles by a
+missing peripheral -- nestest reads `$2002` there and the testbench had no PPU to
+answer. With the register file answering it now matches for **59,554 cycles**,
+2.18x the old extent, and the bound is an artifact budget rather than a wall.
+
+**Two mutations came back NOT CAUGHT against a correct gate**, because the ROM
+rendered from `$2000` with `PPUCTRL = 0` and so held `v[11]` and `ctrl[4]` at
+zero throughout. The gate was not blind; the stimulus was. A second rendering
+window at `$2800` with background patterns at `$1000` took the fetch count from
+3,099 to 6,247 and both mutations to CAUGHT.
+
+**Also closed: four trace features had never been linted.** No CI invocation
+named `cpu-boot-trace`, `irq-timing-trace`, `ppu-state-trace` or the new
+`ppu-fetch-trace`, and `--workspace --all-targets` reaches default features
+only, so the `rustynes-cosim` clippy step compiled those modules **as
+dependencies**, where warnings are not denied. One explicit step per feature
+now; `ppu-state-trace` had **six** `-D warnings` errors waiting in it.
+
+## Rung 3 continues: the scroll address logic (v2.5.3)
+
+`inc_x`, `inc_y`, `copy_x` and `copy_y` at their documented dots, the
+`$2007`-during-rendering dual increment, and -- found by the rung rather than
+planned into it -- **a 3-dot delay on toggling rendering**.
+
+**Gates:** `ppuscroll` **19,813 records / 0 divergences**; rung 2's bus
+comparison on the same ROM **49,993 of 49,993 cycles matching** on `pc`,
+`bus_addr`, `bus_data` and `bus_access`; phase identical throughout.
+
+> "Toggling rendering takes effect approximately 3-4 dots after the write. This
+> delay is required by Battletoads to avoid a crash."
+> -- `nesdev_wiki/PPU_registers.xhtml`
+
+This core applied a `$2001` write immediately. The rendering window was a full
+CPU cycle too wide **at both ends**, costing exactly one coarse-X increment and
+invisible to everything except a read-back of `v`.
+
+**Both implementations were self-consistent; only the documentation could say
+which was wrong.** The oracle can be wrong -- here it was not, and that was
+established rather than assumed, which is the rung-labelling rule from ADR 0037
+doing its job.
+
+**Four instruments, each killing the previous hypothesis**, and the order
+mattered more than any one of them:
+
+1. `tb/phase_delta.py` over every instruction boundary: the phase offset was
+ constant, then zero once the *testbench* was fixed -- **and the gate still
+ failed**. That proved the two faults independent and stopped an alignment
+ change being credited with a fix it had not made.
+2. Rung 2's bus gate on `ppuscroll`: 3 of 49,993 cycles diverged, all read-back
+ *values*, with the `$2001` writes byte-identical. Write-timing refuted.
+3. `ppu-state-trace` on the oracle -- the designated **diagnostic** -- showed `v`
+ incrementing at 112, 120, 128, 136, 144 **and 152**. The sixth increment was
+ at the END of the window, not the start.
+4. The wiki adjudicated.
+
+**The diagnostic never became a gate**, which is what `docs/rung3-ppu.md`
+reserves it for.
+
+## Rung 3 has started (v2.5.2)
+
+`rtl/ppu2c02.sv` implements the 2C02's CPU-visible register file: `$2000-$2007`
+with `$2008-$3FFF` mirroring, the VRAM/palette bus and its read buffer, palette
+and nametable mirroring, OAM, and the data-bus latch. **12,840 records, 0
+divergences, 8 mutations all caught.**
+
+The compare surface is CPU-visible reads, carried by rung 2's **existing** bus
+comparison -- a step that needs no new oracle format cannot be failed by one.
+`docs/rung3-ppu.md` in the sibling was written **before** the rung and fixes
+which fields may fail it (`index_framebuffer`, register reads, `nmi_line`, public
+test ROMs) and which may only explain a failure (`ppu-state-trace`, `v`/`t`/`x`/`w`,
+shift registers, anything RGBA).
+
+**The step also landed a behaviour the plan did not anticipate**: writes to
+PPUCTRL, PPUMASK, PPUSCROLL and PPUADDR are ignored for **~29,658 CPU clocks**
+after reset. Not modelling it made the DUT disagree on every VRAM and palette
+access while open bus and OAM stayed correct -- so the register file *looked*
+right.
+
+**And the ROM passed on its first run while testing nothing.** Four defects, each
+making both sides agree about a behaviour neither was being asked about; all four
+found by mutation, none visible by reading. The lesson is recorded in the
+sibling's `docs/rung3-ppu.md`: a passing gate is evidence only once something has
+been shown to make it fail.
+
+## Rung 2 is closed (v2.5.1)
+
+Its interrupt half was the last piece. `tb/interrupt_sweep.py` asserts /NMI,
+/IRQ, or **both together** before instruction K and holds it, for every K across
+a hazard program, driving identical stimulus into both sides: **60 injection
+points, 0 divergences** on all seven CPU fields.
+
+It found two defects, and the second is the one worth remembering. A hardware
+interrupt pushed a return address **one byte too high**, because `AM_BRK` fell
+through a generic operand-fetch increment shared with every other addressing
+mode. `BRK` and a hardware interrupt share that mode and *disagree* about it --
+`BRK` advances over its second byte, an interrupt does not -- so for `BRK` two
+writers assigned the same value and the fault was invisible. **`BRK` passing
+186/186 is what kept it hidden**: the only opcode exercising the mode was the one
+on which the bug did not show.
+
+The oracle side is [ADR 0038](../adr/0038-cosim-interrupt-injection-api.md)'s
+`cosim-interrupt-inject` feature. Its precondition -- that a default build emits
+none of it -- is **measured, with a live control**: `inject_` appears 0 times in
+the expanded default core and **17** times with the feature on. The control is not
+ceremony. The ADR's original command piped a missing `cargo-expand` through
+`grep -c`, which reports the 0 it is looking for while measuring nothing.
+
+**Two v2.5.0 gates remain open and are reclassified, not carried.** nestest 0-diff
+and the 5 M-cycle window both stop at a `$2002` read where *both sides address it*
+and only the data differs -- the DUT has no PPU. They are rung-3 acceptance
+criteria.
+
+---
+
+## What this is, and what it is not
+
+RustyNES is **not** being ported to FPGA. A MiSTer core is SystemVerilog compiled
+by Quartus 17.0.2 into a Cyclone V bitstream; Rust does not become a bitstream.
+
+What the "Fabric" line builds is a **new NES implementation in SystemVerilog,
+written from public hardware documentation**, in a sibling repository
+([`doublegate/RustyNES_MiSTer`](https://github.com/doublegate/RustyNES_MiSTer),
+private), with **RustyNES as its verification oracle**. This document specifies
+the boundary between the two - the one part that lives in this repository.
+
+When this section was written (2026-08-20, first shipped in v2.4.2), the sibling repository held only the
+rung-0 harness and **no RTL**, which was the ladder's design rather than a gap:
+the testbench had to be shown able to recognise agreement before anything was
+compared. It has carried RTL since v2.4.4 and now holds a complete core (see the
+release sections above). Two of its harness files matter to readers of this
+document, because they are the other half of what is specified here.
+
+`tb/checkpoint.h` reimplements this repository's checkpoint encoding in C++, and
+`tb/checkpoint_selftest.cpp` asserts it against **the same hardcoded vector**
+`the_wire_encoding_is_pinned_to_a_fixed_vector` pins on this side. That pairing
+is the whole guard against the top-ranked risk at this rung: a packing
+disagreement between the two halves produces a hash mismatch that is
+indistinguishable from a wrong DUT, and would be debugged as one. **Changing
+`Observable::encode` here without changing `checkpoint.h` there breaks
+co-simulation in the way that is hardest to diagnose** - so the selftest is the
+first thing to run after touching either.
+
+Its licence audit also settled a question this side had left open. ADR 0037
+recorded that a GPL-2.0-**only** file anywhere in the MiSTer framework's `sys/`
+would force the RTL to GPL-2.0-or-later. All 57 files of an upstream clone were
+read at v2.4.3: **there is no such file**, and four are GPL-3.0-or-later -
+including `hps_io.sv`, which no core functions without. v2.6.6 re-verified this
+against the tree actually vendored (`Template_MiSTer@3ea1134c`): **40** HDL files,
+the same four GPL-3.0-or-later, nine GPL-2.0-or-later, **zero** GPL-2.0-only (the
+sibling's `docs/licence-audit-2026-08-20.md`, "Re-verified at v2.6.6"). GPL-2.0-or-later combines upward and GPL-3.0-or-later does not
+reduce, so the combined bitstream must be **GPL-3.0-or-later**, which is already
+this project's licence. The hedge is inverted by the evidence rather than
+confirmed by it.
+
+## The firewall applies to HDL
+
+`NES_MiSTer` and `fpganes` `rtl/` are **strict black boxes**: never opened, read,
+quoted or transcribed. This is the same rule
+`docs/ai-emulator-provenance-guardrails.md` states for emulator source, extended
+to hardware description.
+
+- **Permitted:** instantiating a third-party core as an opaque testbench module
+ and comparing its *outputs* against ours.
+- **Not permitted:** reading its source, constants, tables, identifier names or
+ comments - not "for reference", not once.
+- **Anything unimplementable from documentation escalates to a new ADR before any
+ source is opened.**
+
+Enforcement is mechanical rather than dispositional: the repositories stay
+physically outside the workspace, and CI carries a path denylist plus an
+identifier grep - the same shape as the `/ref-proj/` guard.
+
+## `crates/rustynes-cosim`
+
+A pure wrapper over `rustynes-core`. It adds **no** core API and changes **no**
+core behaviour; it is additive, absent from the default build, and its presence
+cannot move AccuracyCoin or nestest.
+
+### It is excluded from the workspace, deliberately
+
+`rustynes-cosim` is in the root manifest's `[workspace] exclude`, not its
+`members`. That is not tidiness — it is the only mechanism that makes the
+isolation real.
+
+The crate enables `cpu-boot-trace` and `irq-timing-trace` on `rustynes-core`, and
+**cargo unifies features across a workspace build**. As a member, it made
+`cargo build --workspace` compile the core once with the union, so every
+workspace build linked the **instrumented** per-cycle PPU tick loop —
+`irq-timing-trace` selects a different `for sub_dot in 0..3` loop, not an inert
+branch. CI's accuracy battery is `cargo test --workspace --release --features
+test-roms`, so it was validating a scheduler no user runs.
+
+The measured cost was +1.2% to +1.9% on `full_frame`, *below* this project's 3%
+adoption bar. Stated precisely because it shows the fix was never about speed: a
+gate pointed at the wrong code path is wrong at any percentage.
+
+**What exclusion costs, and how each cost is closed:**
+
+| Cost | Closed by |
+|---|---|
+| Cannot use `field.workspace = true`; version/edition/license/lints duplicated | `cosim_manifest_audit.rs` asserts every duplicated value equals the workspace's |
+| Someone re-adds it to `members` | the same audit asserts it is still in `exclude` |
+| `cargo fmt --all` / `clippy --workspace` / `test --workspace` do not reach it | explicit `fmt`, `clippy` and `test` steps in `ci.yml` |
+| Its dependencies leave the workspace `cargo deny` graph | today only `sha2`, already in the graph; re-check if that changes |
+
+The clippy step justified itself immediately, reporting a `must_use_candidate`
+that `cargo clippy --workspace` had never surfaced.
+
+### Crate types
+
+`["rlib", "staticlib", "cdylib"]` - `rlib` so the golden-export binary and the
+crate's own tests use the safe Rust API directly, `staticlib`/`cdylib` so a
+Verilator C++ testbench links the same code through the C ABI.
+
+### The trace features are mandatory
+
+`Cargo.toml` enables `cpu-boot-trace` and `irq-timing-trace` unconditionally
+rather than re-exposing them as this crate's own optional features.
+
+A build without them would compile, link, run, and export **empty** goldens - an
+absence of signal that reads exactly like agreement. Making them mandatory turns
+that into a compile error.
+
+A side effect worth recording: **no CI invocation previously enabled either
+feature for clippy**, so `cpu_boot_trace.rs` and `irq_trace.rs` had never passed
+the lint gate. Adding this crate surfaced six pre-existing findings in them.
+
+### The power-on frame latch
+
+The PPU is constructed at dot 340 of the pre-render line, so the 7-cycle reset
+sequence ticks past the frame wrap and leaves `frame_complete` latched. **The
+first `run_frame()` after construction therefore consumes that latch and returns
+without stepping a single cycle** - measured, not inferred: frame 0 advances the
+cycle counter by 0, frames 1..3 by ~29,780 each.
+
+Every other caller in the workspace runs thousands of frames, so one lost frame is
+invisible to them. It is not invisible to a golden export: a bare
+`for _ in 0..n { run_frame() }` would emit an (n-1)-frame golden under a manifest
+claiming n.
+
+`Oracle::advance_frames(n)` therefore gates on the **frame counter**, not the call
+count, and bails out on a jammed CPU. The behaviour is pinned by
+`the_first_run_frame_after_power_on_advances_nothing`, so a future core change
+that removes the quirk fails a test that names it rather than silently altering
+every golden's length.
+
+## Golden formats
+
+`nes_golden_export --rom --out ` writes, under ``:
+
+| File | Format | Consumed by |
+|---|---|---|
+| `.boot.bin` | `CpuBootTrace` binary - 12-byte magic `RUSTYNES_CPU`, schema version, packed records | `cpu_boot_trace_diff` |
+| `.irq.csv` | per-CPU-cycle IRQ/bus CSV, two samples per cycle | `scripts/irq_trace_cross_diff.py` |
+| `.index_fb.bin` | 256x240 little-endian `u16`, **pre-palette** | the testbench's frame comparison |
+| `.ram.bin` | 2 KiB CPU work RAM | `accuracy_coin_catalog::decode_results` |
+| `.ckpt.bin` | rolling per-cycle hash checkpoints, `(u64 through_cycle, u64 hash)` LE, headerless | `checkpoint_diff` |
+| `.obs.bin` | full-capture observable stream, repeated 16-byte records | the testbench's self-diff, and a located-window re-run |
+| `.manifest.txt` | provenance | humans, and the drift guard below |
+
+The framebuffer is exported **pre-palette** on purpose: a palette difference must
+not be able to masquerade as a rendering difference. That is the failure mode
+v2.3.8 "Parallax" was built to prevent.
+
+### The manifest is not decoration
+
+The determinism contract covers the framebuffer and audio. It says **nothing**
+about trace-format stability, and `cpu_boot_trace` is at schema version 1 with a
+history of being reshaped. A routine RustyNES accuracy fix can therefore change a
+golden and turn the FPGA repository's CI red for a reason unrelated to its RTL.
+
+The manifest records the ROM SHA-256, the seed, the **requested and actually
+simulated** frame counts, the `run_frame()` call count, the cumulative CPU cycle
+count, and the emulator version - so a red diff is attributable to the right side
+of the boundary in one look rather than by bisecting two repositories.
+
+Requested and actual are recorded separately because they can legitimately differ:
+a ROM that jams stops advancing frames, and the export still succeeds. What must
+never happen is the manifest claiming a frame count that was not simulated.
+
+### Input-device and cheat stimuli (v3.2.0)
+
+Item 8 of v3.2.0 gives the MiSTer core a Four Score, an Arkanoid (Vaus) paddle
+and Game Genie style cheats, and each needs a golden with the same device
+attached on this side. Three exporter flags attach them for the whole run:
+
+| Flag | Attaches | Manifest line |
+|---|---|---|
+| `--four-score P1:P2:P3:P4` | the Four Score, with four pads' button bytes (two hex digits each, `Buttons` bit order) | `four_score = 01:82:44:a8` |
+| `--vaus POS:FIRE` | an NES (7-pin) Arkanoid controller on `$4017`: knob position (two hex digits) and fire (`0`/`1`) | `vaus = a7:1` |
+| `--genie CODE` (repeatable) | a 6- or 8-letter Game Genie code | `genie = SXIOPO,YYKPOYZZ` |
+
+They call the emulator's existing models (`Nes::set_four_score`,
+`Nes::set_paddle`, `Nes::add_genie_code`) and change no emulated behaviour of
+their own, so `EMULATION_EPOCH` does not move. The manifest gains a line only
+when a flag is given, so every earlier manifest is byte-identical. The inputs
+are held **constant** for the run: a frame-windowed schedule would need the
+DUT's testbench to reproduce the frame boundaries, and a stimulus ROM that reads
+the device every frame exercises every bit of it anyway.
+
+Three combinations are refused rather than exported: `--four-score` with
+`--press-start` (both write port 1's buttons), `--four-score` with `--vaus` (the
+NESdev Arkanoid page: "No version is compatible with four player adapters"), and
+two codes patching one address (the emulator keeps one code per address, so the
+manifest would list a code that never applied). The parsers, the refusals, the
+manifest lines and the attach path are tested in the binary's `device_tests`;
+the attach test runs a ROM that strobes the ports and reads them back, so a flag
+that parsed and attached nothing fails it.
+
+## The null-DUT gate
+
+`crates/rustynes-cosim/tests/null_dut_self_diff.rs` is rung 0's half of the
+ladder that lives here: feed RustyNES's own golden back in as if it were the DUT
+and require zero divergences. It asserts three things, and the second and third
+exist because the first alone proves less than it appears to.
+
+- **Two independent exports are byte-identical** across the boot trace, the index
+ framebuffer, work RAM, the cycle count and the call count. This is the
+ determinism contract observed at this crate's boundary; if it fails, a
+ pre-generated golden is *not* the trace a lockstep run would produce and
+ replay-as-oracle is unsound.
+- **A one-bit corruption is caught.** A comparator that always reports agreement
+ passes a self-diff trivially.
+- **Five frames is five NTSC frames' worth of cycles**, in six `run_frame()`
+ calls. Checked in integer half-cycles, without trusting the counter that
+ produced the number.
+
+Verified against the real `cpu_boot_trace_diff` CLI as well as in-process: it
+reports `All 5464 aligned records match` and exits 0 on the self-diff, and on a
+one-bit corruption reports the divergence at cycle 561, PC `$C419`, naming the
+field and both values. The zero therefore comes from a tool that can tell the
+difference, not from one that cannot.
+
+The other half of rung 0 -- hash-checkpoint agreement with full capture over a
+100k-cycle window, and the Verilator side of the writers -- is v2.4.2.
+
+## Replay, not lockstep
+
+Build time: RustyNES emits goldens. Run time: Verilator runs the DUT, the C++
+testbench writes **the same byte formats**, and the diff CLIs that already exist
+compare them.
+
+The determinism contract makes this *equivalent* to lockstep - same seed + ROM +
+input yields a bit-identical framebuffer and audio, so a pre-recorded trace is
+exactly the trace a lockstep run would have produced. It is additionally better in
+two ways: goldens are re-diffable without re-simulating, and the two sides can run
+on different machines at different times.
+
+`scripts/mesen2_cpu_boot_trace.lua` already writes `cpu_boot_trace` from a foreign
+emulator, so the FPGA testbench is the format's **third** writer, not its first.
+
+### No DPI-C
+
+DPI-C would push `import "DPI-C"` into RTL that must also pass Quartus, then
+require `` `ifdef SIMULATION `` guards - the exact construct that lets a simulated
+netlist drift from the synthesised one.
+
+Instead, observation ports live in `tb/nes_top_cosim.sv`, **never listed in
+`files.qip`**, plus Verilator `--public-flat-rd` hierarchical reads. Net synthesis
+impact: zero.
+
+### Hash first, capture on divergence
+
+A 4200-frame AccuracyCoin run is ~125 M CPU cycles, which as per-cycle CSV is
+~7.5 GB per side. Both sides instead chain a 64-bit hash over the per-cycle tuple
+and compare checkpoints every 4096 cycles - **~480 KB** for a full run. On the
+first mismatch, re-run only that window with full capture and waveforms.
+
+Implemented in `crates/rustynes-cosim/src/checkpoint.rs`. **Measured on a real
+export** rather than projected: 3 frames of AccuracyCoin is 89,343 CPU cycles,
+which is **5,372,427 bytes** of `irq.csv` against **352 bytes** of `ckpt.bin` -
+a factor of **15,263**.
+
+#### What is hashed, and what deliberately is not
+
+`CycleRecord` carries 29 fields, and most of them are *`RustyNES`'s model*, not
+hardware. `checkpoint::Observable` is the subset an external device-under-test
+can genuinely produce, and `Observable::from_cycle_record` is the single place
+the partition is applied - so widening it has to pass
+`model_internal_state_cannot_cause_a_divergence`, which perturbs every dropped
+field at once and asserts the hash does not move.
+
+| In | Why |
+|---|---|
+| `cpu_cycle` | the axis both sides count on |
+| `bus_access`, `bus_addr`, `bus_data` | pin-visible |
+| `put_cycle` | the R/W phase half of the M2 cycle - pin-visible |
+| `nmi_line` | a pin |
+| `irq_line_at_low`, `irq_line_at_high` | the /IRQ pin, sampled twice per cycle |
+| `pc` | **not** pin-visible; see below |
+
+Two caveats are stated rather than buried.
+
+**The IRQ line is one wire.** `CycleRecord` splits its samples into
+`irq_pending_mapper_*` and `irq_pending_apu_*`, which is `RustyNES` *attributing*
+the assertion to a source. Hardware has a single wire-OR'd /IRQ input and cannot
+make that distinction, so the pairs are OR'd before hashing. Hashing them apart
+would fail a correct DUT for disagreeing about something it cannot observe.
+
+**`pc` is DUT-observable, not pin-observable.** The 6502 does not expose its
+program counter. It is in because the testbench wrapper can expose the internal
+register and rung 1 compares it directly - but a `pc`-only mismatch means
+something weaker than a bus mismatch.
+
+`ppu_scanline`, `ppu_dot`, `ppu_frame` and `a12_events` are out. `a12_events` is
+the sharpest case: A12 transitions genuinely are observable on the cartridge
+connector, so it is excluded for **scope**, not observability, and becomes a gate
+when the PPU rung opens.
+
+#### The hash must be reimplementable in ten lines of C++
+
+The top risk at rung 0 is a format-packing mismatch masquerading as an RTL bug.
+So the hash is **FNV-1a 64** - chosen for exactly one property, that a testbench
+can reimplement it without a library - and `Observable::encode` defines a fixed
+**16-byte little-endian** layout with an explicit zero pad byte, so the C++ side
+cannot hash uninitialised struct padding. Both are pinned to a hardcoded vector
+by `the_wire_encoding_is_pinned_to_a_fixed_vector`; a reordered field fails that
+test rather than producing a phantom RTL defect on the next co-simulation run.
+
+#### Three answers, and the third is the point
+
+`checkpoint_diff ` exits `0` identical,
+`1` diverged (printing the window to re-run), `2` usage/IO, and **`3`
+inconclusive**. A truncated run, a DUT that stopped early, and two runs at
+different intervals all produce "no divergence was found", and reporting that as
+agreement is this project's recurring failure. A green job must mean the streams
+were compared and matched, never that there was nothing to compare.
+
+Cycle **alignment is checked before the hash**: two streams checkpointing at
+different cycles cover different spans, so a hash difference between them says
+nothing, and calling it a divergence would send a full-capture re-run at a window
+where nothing is wrong.
+
+#### The gate: checkpoints agree with full capture
+
+Checkpoints approximate "where do these two runs first differ", traded for four
+orders of magnitude of disk, and the scheme is worthless if the approximation
+can disagree with the answer. `first_full_capture_difference` computes the answer
+directly; `localisation_is_consistent` states the contract, as a function rather
+than as prose here.
+
+| full capture says | the comparison must |
+|---|---|
+| identical | report `Identical` - anything else is a false positive, and a gate that cries wolf gets switched off |
+| first differs at `k` | **not** report `Identical` - that false negative passes a wrong DUT |
+| first differs at `k`, and it reports `Diverged` | name a window **containing `k`** |
+| first differs at `k` | `Inconclusive` is an acceptable, honest refusal |
+| identical | `Inconclusive` is **not** acceptable |
+
+The third row is the one worth the effort. A divergence report naming the wrong
+window sends a full-capture re-run somewhere nothing is wrong, spends the
+debugging budget, and returns "no problem here" - which reads as evidence the DUT
+is fine.
+
+A sweep drives 331 cases across every run length around the interval boundary,
+corrupting a different observable field at a different position each time. It
+found a real defect on its first run: **a divergence at cycle zero was reported
+in a window that did not contain it.** `after_cycle` was a `u64` in which `0`
+meant both "no prior checkpoint" and "cycle zero", so the first window read as
+`(0, 0]` - empty. It is now `Option`, and `Divergence::contains` is offered
+so call sites do not reimplement a boundary that is half-open at one end and
+open-ended at the other.
+
+#### The CSV cannot re-derive the checkpoints, so `.obs.bin` exists
+
+Found by trying to build the rung-0 self-diff on the CSV. `irq.csv` carries **23
+columns**, and neither `pc` nor `put_cycle_post` is among them - two of the nine
+observable fields are simply absent. So an external testbench reading the CSV
+cannot reproduce the checkpoint hashes, and "feed `RustyNES`'s golden back in as
+if it were the DUT and get zero divergences" was not implementable as designed.
+
+`.obs.bin` closes that: repeated 16-byte records in the **same wire
+encoding the hash folds**, headerless. It is the only artifact the checkpoints
+can be independently re-derived from, and it is also the input a re-run of a
+located window consumes - so it would have been needed regardless.
+
+Additive. The CSV is untouched, which matters because `scripts/irq_trace_cross_diff.py`
+and the committed `golden/irq_trace/*.csv` both depend on its shape.
+
+`Observable::decode` is the inverse, and it **refuses what it does not
+understand**: a non-zero reserved pad byte, an undefined flag bit, an unknown
+bus-access code, a short record, a stream length that is not a multiple of 16.
+None of that is pedantry - reading a record from a newer producer as though
+nothing had changed is how a *format* divergence gets reported as a *DUT*
+divergence.
+
+The stream is emitted even when the checkpoints are refused for overflow. A hash
+over a truncated trace claims a coverage it does not have; the records
+themselves are just records, and are worth keeping for a re-run.
+
+#### The rung-0 self-diff, measured
+
+The oracle's own output fed back in as though it were the DUT, across the
+repository boundary:
+
+```console
+$ tb/selfdiff_check.sh
+1/3 exporting goldens from the oracle
+2/3 re-deriving checkpoints on this side
+re-derived 22 checkpoints from 89335 records
+3/3 comparing
+checkpoints match: 22 compared, 0 divergences
+
+negative control: one flipped bit must be located
+DIVERGED at checkpoint 10
+ window to re-run with full capture: cycles (40967, 45063] (4096 cycles)
+
+rung 0 self-diff: agreement recognised, and disagreement located
+```
+
+89,335 records of AccuracyCoin, re-derived in C++ from `.obs.bin` alone, hashing
+to byte-identical checkpoints. The negative control runs **in the same
+invocation**, because a positive control alone is satisfiable by a comparison
+that always agrees.
+
+It is not in CI: it needs both repositories and a test ROM. It exits **77** and
+says why when it cannot run - a skip that reports itself, never a silent pass.
+
+#### A capacity-limited trace refuses rather than truncating
+
+`IrqTrace::push` silently drops records once it reaches the capacity it was armed
+with, advancing an `overflow` counter nobody has to read. A checkpoint stream
+computed over a dropped-record trace hashes *fewer cycles than it claims*, and
+the two sides then disagree for a reason that has nothing to do with the DUT -
+which is worse than useless, because it looks like a legitimate divergence. So
+`Oracle::take_checkpoints` returns `CheckpointError::TraceOverflowed` naming the
+capacity to retry with, `rn_write_checkpoints` returns `-5`, and the exporter
+aborts rather than writing a short stream.
+
+#### One take, two artifacts
+
+`Bus::take_irq_trace` **moves** the trace out, so asking for the CSV and then the
+checkpoints yields `None` for whichever came second - and `None` is
+indistinguishable from "never armed". `Oracle::take_irq_artifacts` derives both
+from a single take; the hazard is pinned by
+`taking_the_csv_first_leaves_no_trace_for_checkpoints` so it is a documented
+behaviour rather than a surprise.
+
+## What is a gate and what is diagnostic
+
+| Surface | Role | Why |
+|---|---|---|
+| nestest 7 CPU fields | **gate** | independent oracle - RustyNES is 0-diff against the Nintendulator log |
+| per-cycle bus / IRQ samples | **gate** | where 6502 implementations actually die |
+| `index_framebuffer` | **gate** | pre-palette, so palette cannot masquerade as rendering |
+| `MixRecord` integer channel levels | **gate** | 0-15 per channel, 0-127 DMC |
+| AccuracyCoin RAM status vector | **gate** | compared entry for entry, including `Skipped` / `NotRun` |
+| `ppu-state-trace` FSM fields | **diagnostic only** | encodes RustyNES's *modelling choices*, not hardware facts |
+| mixed `f32` audio output | **diagnostic only** | the non-linear mixer and BLEP resampler are software artifacts |
+
+The two "diagnostic only" rows are the load-bearing ones. Gating on
+`ppu-state-trace` would force the HDL to transliterate a Rust data structure - bad
+hardware, and an odd form of self-derivation given the black-box premise. Gating on
+mixed `f32` audio would either force the HDL to reproduce a software resampler or
+produce permanent unresolvable false failures.
+
+**Partition every trace field into hardware-observable versus model-internal
+before the PPU rung starts.**
+
+## The oracle can be wrong
+
+141/141 on AccuracyCoin is not "matches silicon". Where RustyNES is wrong,
+co-simulation will drive the RTL confidently toward its bug.
+
+Every rung is therefore labelled by whether it has an **independent** oracle:
+nestest (Nintendulator) and the blargg ROMs do; trace fields with no Mesen2
+counterpart do not, and are advisory only.
+
+### It happened, at rung 5 (2026-08-25)
+
+This stopped being a stated risk and became a measurement.
+
+`rtl/cpu_bus.sv` was written from `nesdev_wiki/CPU_memory_map.xhtml` and
+`Open_bus_behavior.xhtml` and run against this emulator. The two agreed on
+`$4016`, `$4017`, `$5000` and `$5C34` — including the open-bus value, which the
+DUT *derives* from a latch where the testbench had hardcoded `$40` — and
+disagreed only in `$6000-$7FFF`.
+
+**The DUT was right.** An NROM board decodes nothing there, so the window reads
+open bus. `crates/rustynes-mappers/src/m000_nrom.rs` allocates 8 KiB of PRG-RAM
+unconditionally so accesses "don't fall off the edge", which is the iNES-era
+emulator default the wiki names as a problem in its own words — and it lists
+games that break on the WRAM answer, *Low G Man* and *Battletoads & Double
+Dragon* among them.
+
+Three things this establishes, in order of how much they matter:
+
+1. **The ladder can catch the oracle.** That was asserted when the programme was
+ planned and is now demonstrated, which is a different kind of claim.
+2. **The correct response was to record, not to fix.** Changing it alters
+ shipped behaviour on every iNES-header NROM cartridge and needs the NES 2.0
+ WRAM-size field, the per-game database and the full accuracy battery. It is
+ in [`accuracy-ledger.md`](../accuracy-ledger.md) with its citation.
+3. **The gate ROM was narrowed rather than the DUT bent.** `busopen045` reads
+ `$4020-$5FFF` and not `$6000-$7FFF`, because a gate that fails for the
+ oracle's limitation rather than the DUT's teaches the wrong lesson and
+ eventually gets switched off.
+
+## The two risks that had to be settled before any RTL
+
+Both were settled in v2.4.3, and **both were answered by evidence that
+contradicted what the plan assumed**. That is the point of running the
+experiment rather than reasoning about it.
+
+### Risk 1 — the `sys/` licence, which inverted its own hedge
+
+The plan required this *before any RTL is written*, because relicensing after ten
+thousand lines exist is precisely the failure
+`docs/originality-and-provenance.md` documents. Every file under
+`Template_MiSTer`'s `sys/` was read and classified by its own grant, with comment
+markers stripped and whitespace collapsed before matching.
+
+| Classification | Files |
+|---|---|
+| GPL-2.0-or-later | 9 |
+| **GPL-3.0-or-later** | **4** |
+| GPL by reference, no version stated | 4 |
+| Copyright, no grant | 4 |
+| No header | 36 |
+| **GPL-2.0-only** | **0** |
+| | **57 total** |
+
+The hedge was that a GPL-2.0-**only** file would force the RTL *down* to
+GPL-2.0-or-later. There is no such file, and the binding constraint runs the
+other way: `ddr_svc.sv`, `hps_io.sv`, `scandoubler.v` and `sd_card.sv` are
+GPL-3.0-or-later, and **`hps_io.sv` is not optional** — it is how a core receives
+a ROM from the HPS and how the OSD reaches it. GPL-2.0-or-later may be combined
+into a GPL-3 work because "or later" permits the upgrade; GPL-3.0-or-later cannot
+be reduced to GPL-2.
+
+**The combined bitstream must be GPL-3.0-or-later, which is already RustyNES's
+licence.** No relicensing is needed.
+
+### Risk 4 — the Quartus subset, fitted rather than read
+
+Quartus 17.0.2's SystemVerilog subset is materially narrower than Verilator's,
+and a construct rejected after ten thousand lines exist invalidates not one file
+but the style every file was written in. The acceptance criterion was never "it
+compiles" — it was a fitted netlist **and its resource report**, because only the
+second catches a 2 KiB memory that became 16,384 flip-flops, and Quartus does
+that silently.
+
+Quartus Prime Lite 17.0.2 Build 602, device 5CSEBA6U23I7, defaults throughout:
+
+```text
+Analysis & Synthesis was successful. 0 errors, 0 warnings
+Fitter was successful. 0 errors, 4 warnings
+
+Total block memory bits ; 16,384 / 5,662,720 ( < 1 % )
+M10K blocks ; 2 / 553
+Total registers ; 29
+Logic utilization (ALMs) ; 17 / 41,910 ( < 1 % )
+```
+
+**29 registers, not 16,413.** The inference style that worked is a
+`logic [7:0] mem [0:2047]` with one synchronous read port on a registered
+address, one synchronous write port, and **no asynchronous read** — an async read
+is the usual reason an array becomes registers. Quartus produced a Simple Dual
+Port ALTSYNCRAM unaided, populated its MIF from the `initial` block (which is how
+a boot ROM lands *inside* the block), and one-hot encoded the `enum` as a state
+machine.
+
+**This is now the required style, and every commit adding a memory quotes its
+resource line** — because the failure is silent in isolation and only becomes
+unfittable in aggregate.
+
+Nine constructs are **fitted**. Plain `case`, `priority case` and `$bits` are
+deliberately left *documented*: the kitchen sink does not exercise them, and
+"near-certainly fine" is the phrase the subset policy exists to refuse.
+Extending the subset means extending that module and re-fitting.
+
+The four fitter warnings are 58 unconstrained pins and a missing `.sdc`, in a
+module with no pinout and no timing constraints. Timing closure is a rung-6
+question.
+
+## Rung 1 — the 6502, and where it has actually got to
+
+Nine opcode groups have closed. **2115 records across nine ROMs** on rung 1,
+**4537 cycles** on the per-cycle bus gate, and **27,388 cycles of nestest** --
+all matching the oracle, and `pc` agreeing on **3551 of 3551** cycles.
+
+**Two of v2.5.0's stated gates do not close, and neither is a defect.** nestest
+0-diff over the whole run and per-cycle equality over a 5 M-cycle window both
+need a PPU: nestest reads `$2002` at cycle 27396, *both sides address it*, and
+only the data differs -- a missing peripheral, rung 3 by design. The
+interrupt-injection sweep has no oracle-side stimulus at all, so the pins, the
+hijack and delayed-`I` are implemented and **not oracle-verified**; `BRK` is,
+because a software interrupt needs no pin. `docs/adr/0038-cosim-interrupt-injection-api.md`
+records the decision that would unblock the sweep, and the two preconditions
+that void it. The RTL lives in the sibling
+repository; `RustyNES_MiSTer/docs/rung1-6502.md` is its detailed record.
+
+| release | scope | records |
+|---|---|---|
+| v2.4.4 "Ignition" | the eight-cycle reset and the single-byte implied group | 147 |
+| v2.4.5 "Compass" | immediate / zero page / absolute; loads, stores, all eight branches | 140 |
+| v2.4.6 "Abacus" | three indexed modes with the page-cross penalty; `ADC`/`SBC`; the compares | 286 |
+| v2.4.7 "Keystone" | the stack group, `JSR`/`RTS`/`RTI`, `JMP` and its page-boundary bug | 179 |
+| v2.4.8 "Palimpsest" | read-modify-write: `ASL`/`LSR`/`ROL`/`ROR` and `INC`/`DEC`, accumulator plus four memory modes | 358 |
+| v2.4.9 "Plumbline II" | the logical group; the undocumented opcodes; **and rung 2's bus half** | 236 + 317 |
+
+The earlier ROMs are re-run on every change, which is how the v2.4.5 datapath
+rewrite was shown not to regress v2.4.4.
+
+The counts are **measured** -- each one from running `cpu-gate` against a freshly
+exported golden -- rather than carried forward from the release that introduced
+the ROM. `opgroup1` closed v2.4.4 over a 0..64 cycle window and was
+reported then as 29 records; v2.4.5 widened every ROM's window to catch the
+addressing modes, and the same ROM now yields 147. Both numbers are true of
+different windows, which is exactly why a table mixing them would not add up --
+the totals here are all measured under the current windows.
+
+### What the rung has established beyond the opcodes
+
+**The DUT is the third writer of `CpuBootTrace`**, after the oracle itself and
+`scripts/mesen2_cpu_boot_trace.lua`. `cpu_boot_trace_diff` reads it with no
+modification, and `--skip-fields` already existed -- so the entire rung has
+needed **no oracle-side change**. That is the payoff of replay-rather-than-
+lockstep stated concretely: the comparison tooling does not know one side is
+hardware.
+
+**The oracle corrected our own specification.** `docs/cpu-6502.md` said reset was
+a 7-cycle sequence in one section and 8 in another. An independent implementation
+written *from that document* implemented seven and diverged on its first record.
+Reset is eight; the document is fixed. A second implementation built from a spec
+is a way of testing that spec, and this is what it found on day one.
+
+**Three tests read correctly and verified nothing**, each found by mutation and
+not by reading:
+
+- `TXS` after `TSX` -- a wrongly-flagging `TXS` computes exactly the flags `TSX`
+ had already left, so the wrong answer coincided with the right one.
+- A store and load in the *same* addressing mode -- self-consistent under any
+ address mutation, so it tests round-tripping rather than addressing.
+- A read of RAM the program had not written -- the oracle powers on with
+ deterministic **seeded** work RAM while a flat-memory testbench starts at zero,
+ so the divergence had nothing to do with the CPU.
+
+Designing each case so the **wrong answer differs from the right one** is now the
+default rather than a correction.
+
+### What CI does and does not check
+
+The sibling repository's `cpu-smoke` builds the core and runs the ROMs to
+completion, and its workflow step name says it is **not** the accuracy gate --
+because the oracle's goldens are not vendored there. They are reproducible from a
+pinned oracle commit, and a second copy would be a drifting copy.
+
+The accuracy comparison is `make -C tb cpu-gate GOLDEN=...`. Automating it needs
+golden fetching from a pinned commit, which is **not built yet and is not
+pretended to be**. That is the largest remaining hole in this rung's
+infrastructure and it is named here rather than left to be discovered.
+
+### Still open
+
+**The gap below is CLOSED as of v2.4.9.** `make -C tb cpu-bus-gate` catches both
+mutations, and the section is kept rather than deleted because the reasoning is
+what makes the gate's scope legible.
+
+Read-modify-write closed in v2.4.8 -- but its **double write did not**, in the
+sense that nothing at rung 1 verifies it. Two mutations (skip the dummy write; emit
+the modified value instead of the old one) both come back **NOT CAUGHT**,
+because neither changes a register, a flag, the final memory contents or the
+cycle count, and those are the only things `CpuBootTrace` carries.
+
+That is scoped to **v2.4.9**, beside the undocumented opcodes, rather than left
+to v2.5.0: the bus half of rung 2 needs no new RTL. `Observable` already exists
+on both sides with a byte-identical encoding, the oracle already emits it as
+`.obs.bin`, and `cpu6502` already exposes its whole bus. Wiring a writer produced
+**7 divergences across 793 cycles** on a program rung 1 scores 358/358 -- two
+causes, one harness fidelity (the testbench zeroes RAM the oracle seeds, so every
+dummy read of unwritten memory diverges) and one a genuine per-cycle access
+difference where instruction boundaries still agree.
+
+> **Historical, as of v2.4.9.** The two paragraphs below were true when written
+> and are both superseded: the undocumented opcodes landed in v2.4.9, rung 2's
+> bus half is live, and nestest now runs to 27,388 cycles. Kept rather than
+> deleted because the reasoning still explains why the rung was scoped that way
+> -- but the authoritative status is the section at the top of this file.
+
+The undocumented opcodes are **not** delivered and also move to v2.4.9.
+
+Rung 1's own gate -- nestest 0-diff over >= 8000 instructions -- is not met yet:
+the five ROMs are hand-built opcode groups, not nestest. Rung 2, the per-cycle
+bus and interrupt comparison, has not begun.
+
+### Rung 1 gets an independent oracle (v2.6.3)
+
+The whole rung above was measured against ROMs **written in this project**, and
+the section before this one says exactly what that cannot cover. That limitation
+is now partly lifted.
+
+blargg's `instr_test-v5/rom_singles` — sixteen third-party ROMs, ~2.68 M cycles
+each, predating this programme by two decades and between them exercising all
+256 opcodes — runs as a standing section of the sibling's `regress.sh`, compared
+on rung 2's per-cycle bus surface. **16 of 16 exact**, taking the suite from 50
+gates to **66**.
+
+It is the first *independent* oracle rung 1 has had, and it earned that
+description immediately by finding **three defects the self-written corpus had
+missed**, none of them in the undocumented opcodes the battery was run to
+validate:
+
+| ROM | defect |
+| --- | --- |
+| `06-absolute` | `RRA` fed its `ADC` stage the carry from *before* the instruction rather than the one the rotate produced |
+| `08-ind_x` | the 8-cycle indirect RMW forms addressed the indexed target during their *pointer* fetch cycles |
+| `03-immediate` | the PPU I/O-bus latch never decayed — a 2C02 defect, reached from a CPU ROM, three rungs after rung 3 closed |
+
+The `RRA` finding is the one worth carrying forward, because of what it says
+about compare surfaces rather than about the 6502. **The instruction's own bus
+trace was identical on both sides** — read `$FF`, dummy-write `$FF`, write
+`$7F` — and the divergence appeared nine cycles later in the `STA` that spilled
+the accumulator, off by exactly one. A gate on the memory side of
+read-modify-write would have passed it, and so would this rung's own
+register-boundary trace had the next instruction not stored the accumulator
+straight away.
+
+Two hooks were needed to run third-party ROMs at all, and both are about **not
+transcribing a number**: the window comes from each golden's own manifest rather
+than a `CYCLES_` line, and the board's `$6000-$7FFF` work RAM is presented
+per-ROM (blargg reports through it) rather than by default — NROM has none, which
+is the oracle defect recorded above.
+
+## Rung 5 — the console, and the master-clock substrate
+
+NROM, the work RAM, the CPU bus, the controller ports and DMC DMA are landed and
+gated in the sibling; `nes_top` assembles them, carries **no observation ports**,
+and as of v2.6.3 **divides one 21.477272 MHz master clock** rather than taking
+its clock enables from the testbench.
+
+### The divider is this repository's own substrate, in SystemVerilog
+
+The obvious shape — a modulo-`CPU_DIV` phase counter with the dot at
+`phase[1:0] == 3` — looks equivalent on NTSC and is a dead end. PAL is 16 master
+clocks per CPU cycle and 5 per dot, i.e. **3.2 dots per CPU cycle**, and no
+counter that restarts each CPU cycle can hold a fractional ratio.
+
+`Bus::run_ppu_to` does not do that. It keeps `master_clock` and `ppu_clock` as
+**independent accumulators in master-clock units** and emits a dot whenever
+`ppu_clock + ppu_divider <= master_clock`, letting dot boundaries drift across
+the CPU cycle — which is exactly what PAL does. The DUT copies that structure, so
+retargeting is a parameter change (NTSC 12/4, PAL 16/5, Dendy 15/5).
+
+Two constants come from `Cpu` rather than from a sweep. `read_split(12)` is
+(5, 7) and `write_split(12)` is (7, 5) — `CPU_DIV/2 ∓ PPU_OFFSET` — with the PPU
+run to that point minus `PPU_OFFSET`. On NTSC a read observes at master clock 5
+and a write commits at 7, and **both fall inside the same dot**, which is why the
+DUT's earlier read/write placement sweep measured them onto one dot: this model
+predicted it. `PPU_OFFSET` is also applied as a real phase offset between the
+accumulators, so a cycle's last dot commits *before* the CPU rather than on the
+same edge.
+
+### What it found: an enable that is constant is not an enable
+
+The DUT's testbench used to tie `ce` high and pulse `clk` once per CPU cycle. The
+clock was doing the gating the enable was supposed to do, so **any `always_ff`
+not gated by `ce` was correct only by accident** — under a real master clock each
+fires twelve times. Four sites, two of them previously unknown:
+
+| site | symptom |
+|---|---|
+| PPU CPU-register block (v2.5.7) | a held address latched twelve times per access |
+| open-bus decay reload | refresh never observed; `$2002` read `$00` for `$1F` |
+| DMC DMA acknowledge | the sample pointer advanced by **twelve** per byte; 91% of cycles diverged |
+| frame-counter IRQ set points | `/IRQ` rose eleven master clocks early; the CPU took the interrupt **one instruction sooner** |
+
+The last was caught by blargg's `08.irq_timing` — third-party, so an independent
+oracle rather than our own trace agreeing with itself.
+
+### A fix that worked, and was rejected
+
+Delaying the APU's `/IRQ` by one cycle in `nes_top` also produced 66 of 66, and
+is **indistinguishable from the real fix by gate result**. It was not adopted:
+`Cpu::handle_interrupts` samples IRQ at phi2 into `mc_run_irq` and dispatches on
+`mc_prev_run_irq` — the one-cycle register this codebase calls
+"second-to-last-cycle recognition" — and the DUT's `cpu6502.sv` already
+implements exactly that, correctly gated. A second delay outside it would have
+cancelled an APU-side error rather than corrected it.
+
+**This is the general hazard of an oracle-defined compare surface**, stated once
+so rungs 6 and 7 inherit it: a fix that greens the gate is not evidence the fix
+is right. Continuing to look for a cause after the symptom cleared is the only
+thing that separated the two here.
+
+### Where the three-way disagreements are recorded
+
+The sibling's `docs/oracle-vs-documentation.md` is the umbrella ledger: per
+subsystem, where the DUT, this emulator and the public documentation differed,
+which won, and why — using the same six categories as the APU chapter that
+preceded it. It carries the one entry so far where **this emulator** was the one
+that was wrong (NROM's PRG-RAM window), and the sharpest category-1 entry yet:
+the PPU's open-bus decay deadline, where the documentation says 3-30 ms, this
+emulator uses 558.7 ms, and the DUT's corpus forces >= 523.4 ms.
+
+### AccuracyCoin runs end to end, and the gate is a status vector
+
+The full run now completes on the DUT — **17,868,316 cycles**, where it
+previously halted early — which is what "first end-to-end AccuracyCoin run"
+in the plan's v2.6.3 row asked for.
+
+The comparison is `accuracycoin_status`, on this side. It reads a work-RAM
+dump, decodes it against the 146-entry catalog in
+`accuracy_coin_catalog.rs`, and reports by test rather than by address. It
+filters in both modes rather than dumping all 146 rows: given one dump it
+prints the entries that are **not a clean `Pass`**, and given two it prints only
+the entries where they **disagree**. The vector is decoded in full either way --
+what is filtered is the output, not the comparison. First
+measurement: **137 of 146 entries agree, 9 differ**, six of those sharing one
+failure code — five `SH`-group stores and Open Bus — which reads as one shared
+address-bus cause rather than six independent defects.
+
+**Producing the vector is v2.6.3's deliverable. Making the two agree is
+v2.6.4**, and the plan says so in its own acceptance row.
+
+**The "six sharing one failure code" reading was wrong, and v2.6.4 measured why.**
+AccuracyCoin's `TEST_Fail` reports `(ErrorCode << 2) | 2` and the runner sets
+`ErrorCode` to 1 before *every* test routine, so the code is an index **within
+one routine**: `Open Bus`'s code 7 is its own seventh assertion and `SHA (abs),Y`'s
+code 7 is that routine's seventh. Two entries sharing a code share nothing. What
+actually closed the five `SH` entries was the SH group's RDY-conditional store
+and its addressing-mode-dependent dummy cycle — a real shared cause, identified
+from the opcodes. `Open Bus` was untouched by that work and remained, which
+should have refuted the shape argument at the time.
+
+**And the number underneath the agreement.** Once all nine closed, the vector
+reported identical entry for entry across all 146 — with **58 of those entries
+`NotRun` on both sides**. The comparator was right; the run window was short.
+Broken down by suite, 600 frames reaches the CPU catalog and stops partway
+through `CPU Interrupts`, so the run asked the DUT nothing about the APU, PPU,
+sprite-evaluation or PPU-misc suites — the chips rungs 3 and 4 exist for.
+Measured rather than estimated, **4500 frames reaches all 146** (134,012,761
+cycles), and that is the golden the gate now uses. A pass count is a claim about
+what ran, and what ran has to be measured separately.
+
+Decoding the codes properly is also what closed two of the last three, in
+v2.6.4: `Open Bus` (a `$4015` read does not drive the data bus, and its D5 is
+open bus) and `Interrupt flag latency` (the interrupt poll is the second-to-last
+cycle, and branches poll before cycles 2 and 4 but never before 3). Both rules
+are stated by the test ROM's own comments and by neither of the nesdev pages the
+implementation was written from. `NMI Overlap BRK` is carried to v2.6.5 with its
+disagreement measured per sweep step rather than as one byte — see the sibling's
+`docs/rung5-accuracycoin.md`.
+
+Two properties are worth recording, because both are about what the comparison
+*refuses* rather than what it reports:
+
+- **It is not a RAM byte-compare, deliberately.** Comparing 2 KiB of work RAM
+ answers a different question and answers it wrongly in both directions: it
+ reports scratch bytes — a stack slot, a loop counter, a result the ROM is
+ about to overwrite — as failures, and it reports two runs that never started
+ the battery as a *pass*, because two idle title screens have identical RAM.
+- **An all-`NotRun` vector is refused with a non-zero exit.** That case — two
+ vectors agreeing on 146 entries of nothing — is precisely the shape of the
+ vacuous status-address assertion v2.6.2 found in the NTSC blargg suite, which
+ reported 11/11 for five minor releases while asserting nothing. A comparison
+ that cannot distinguish *agreed* from *never ran* is not a gate.
+
+Reaching the run cost **two false passes before a real one**: AccuracyCoin idles
+on its title screen until START is pressed, and only the framebuffer half of the
+export had a guard that refused an idle capture. The manifest now records
+`press_start` — as `A:B`, or the literal `none` — because a controller press
+changes what the ROM *executes*, and a manifest omitting it describes an idle
+title screen and an 88-result battery identically.
+
+## Rung 4 — the 2A03, and the audit it prompted
+
+Rung 4 opened at v2.5.9 with the two pulse channels and the frame counter, and
+**v2.6.0 "Assay"** adds the triangle, the noise channel and the sweep unit. Eleven
+gate ROMs, 35 of 35 mutations CAUGHT, and 30 gates green across rungs 1–4.
+
+Detail lives in the sibling repository (`docs/rung4-apu.md`), but two things
+belong here because they are about the *programme*, not about the APU.
+
+### The oracle is an emulator, and rung 4 is where that stopped being abstract
+
+Every rung-4 gate compares the DUT against RustyNES. A shared error between the
+two is therefore invisible **by construction**: the DUT is tuned until it agrees,
+and agreement with a wrong reference is indistinguishable from correctness.
+
+`docs/apu-oracle-vs-documentation.md` in the sibling repo is the response —
+a standing ledger of every place the DUT follows the oracle rather than the NESdev
+wiki, sorted by risk, each with the documentation text it is measured against and
+the independent check that would adjudicate it. Its maintenance rule is the load-
+bearing part: **an item closes only when a gate exercises it *and* a mutation
+against it is CAUGHT.**
+
+The independent check was run at v2.6.0 for the first time: **the oracle passes
+blargg's APU battery 29/29**. That is recorded per item rather than as a headline,
+because it means different things in different places — for two items it moved
+suspicion off the oracle and onto the RTL, and for one there is no adjudicating
+ROM at all, which is itself the finding.
+
+### Two errors that were cancelling, and what that says about mutation testing
+
+The `$4017` reset delay had been keyed on the mode bit, which the wiki never
+mentions. It was exact *only* in combination with a second constant held one tick
+off its documented value; either correction alone costs 2 cycles, in opposite
+directions. The fitted rule was not merely unfalsified by the stimulus — it was
+**load-bearing for a second error**, which is why it survived both a mutation
+catalog and a documentation audit that looked directly at it.
+
+This is the third time the programme has found two errors cancelling (v2.5.7's
+`PPU_LEAD`, v2.6.0's own observation point), and the first where one propped up
+the other rather than merely coinciding with it. **A green mutation catalog does
+not establish that constants are individually right** — only that the combination
+in the tree is not detectably wrong on the current stimulus. Cross-checking each
+constant against documentation is a separate activity, and rung 4 is where the
+programme learned to do it.
diff --git a/docs/mister.md b/docs/mister.md
index ae5fc469..ce6c0fdf 100644
--- a/docs/mister.md
+++ b/docs/mister.md
@@ -1,601 +1,33 @@
# MiSTer FPGA and SuperStation One - the co-simulation boundary
**Spec, not history.** Update this file in the same change as any behaviour
-change to `crates/rustynes-cosim` or the golden formats it emits.
-
-**Decision records:** [ADR 0037](adr/0037-mister-fpga-core-independent-hdl-implementation.md)
-(the programme and the HDL firewall) ·
-[ADR 0038](adr/0038-cosim-interrupt-injection-api.md) (the interrupt-injection API).
-**Execution plan:** the line to **v3.0.0**, which shipped on 2026-10-06 ([ADR 0041](adr/0041-hardware-release-is-v3.0.0.md), as amended by ADR 0043):
-[`v2.7.x`](../to-dos/plans/v2.7.x-core-frontend-audit-plan.md) (the core and frontend audits; oracle-only, so the bitstream does not change),
-[`v2.8.x`](../to-dos/plans/v2.8.x-libretro-rtl-audit-plan.md) (the RTL audit and the off-die build),
-[`v2.9.x`](../to-dos/plans/v2.9.x-final-audit-and-hardware-plan.md) (the board) and
-[`v3.0.0`](../to-dos/plans/v3.0.0-cornerstone-plan.md), which ADR 0043 made the API major with a
-release-candidate core; the hardware-verified core is the later
-[`v3.x`](../to-dos/plans/v3.x-hardware-verification-plan.md) release. Before that,
-[`to-dos/plans/v2.7.0-mister-core-plan.md`](../to-dos/plans/v2.7.0-mister-core-plan.md) (superseded)
--- which **superseded** [`v2.5.0-fabric-plan.md`](../to-dos/plans/v2.5.0-fabric-plan.md),
-which is delivered.
+change to `crates/rustynes-cosim` or the golden formats it emits. It describes
+the boundary as it stands at v3.7.1 "Imprint". How each part of it was built,
+release by release from v2.4.1 to v3.0.x, is in the frozen
+[`archive/mister-history-v2.5-to-v3.0.md`](archive/mister-history-v2.5-to-v3.0.md);
+per-release detail after that is in `CHANGELOG.md` and the release notes.
+
+> **No hardware has run any bitstream.** Every `.rbf` attached to a release is a
+> **release candidate, not hardware-verified**
+> ([ADR 0043](adr/0043-v3-is-the-api-major-and-a-release-candidate-core.md)).
+> Timing closure and a reproducible bitstream are claimed. A booting core, a
+> synced display, audible audio and a working controller are not.
+
+**Decision records:**
+[ADR 0037](adr/0037-mister-fpga-core-independent-hdl-implementation.md) (the
+programme and the HDL firewall) ·
+[ADR 0038](adr/0038-cosim-interrupt-injection-api.md) (the interrupt-injection
+API) · [ADR 0039](adr/0039-sdram-clock-domain.md) (the SDRAM clock domain) ·
+[ADR 0040](adr/0040-public-release-metadata-is-outside-the-reference-firewall.md)
+(what may be said about a black-boxed core) ·
+[ADR 0041](adr/0041-hardware-release-is-v3.0.0.md) as amended by ADR 0043 (v3.0.0
+is the API major with a release-candidate core).
+**Hardware verification:** planned for a later v3.x release,
+[`to-dos/plans/v3.x-hardware-verification-plan.md`](../to-dos/plans/v3.x-hardware-verification-plan.md).
**Execution tracking:** [`to-dos/mister/`](../to-dos/mister/).
-**Research archive:** [`to-dos/plans/research/v2.5.0-research-mister-fpga.md`](../to-dos/plans/research/v2.5.0-research-mister-fpga.md),
-plus four dated files in `ref-docs/` (contribution requirements, the MiSTer
-framework, the hardware **source map**, and alternative FPGA targets).
**Device-under-test:** (private).
-
-## The ladder becomes something a reviewer can run (v2.6.15)
-
-Rung 6 is blocked on hardware and v2.7.0 now waits for it, so this release is
-about the other half of a submission: not what the core does, but what a
-reviewer can **check** about it.
-
-The contributing page states the bar for AI-assisted code in one sentence --
-*"Fully AI generated code should meet a minimum reasonable bar for readability
-and include some evidence of quality and accuracy testing."* This programme's
-evidence is 148 co-simulation gates -- 142 at the start of v2.6.15, plus the five
-it added and the one v2.6.16 added. Every gate but five carries a mutation
-record; the exceptions are the five blargg `cpu_interrupts_v2` verdict gates
-v2.6.15 added, which are independent-oracle verdicts with no mutation recorded
-against them (no rung document and neither `tb/mutate.sh` nor
-`tb/mutate_apu.sh` names them; noted at v3.0.1). 147 of them run on the die; the 148th measures the off-die memory system and reports N/A
-there, because a gate on the SDRAM path cannot exist in a build with no SDRAM. And
-`tb/regress.sh` says in its own header that it *"is NOT a CI gate and cannot
-be"*, because it needs the oracle's goldens and a cargo build of a crate in
-another repository. So the strongest thing here was a set of **documents
-describing checks a reader cannot run**.
-
-`docs/golden-fetching.md` in the sibling specified the fix and carried
-`Status: NOT BUILT`. The smallest end-to-end slice is now built: the nine
-opcode-group ROMs export from a **pinned** oracle commit (`tb/ORACLE_COMMIT`)
-and compare in CI. It is a subset -- no PPU, no APU, no AccuracyCoin, no nestest
--- and the job's name says so, because a job that looks like a gate and is not
-is the defect this programme keeps finding in itself.
-
-**Pinning is the point rather than a caveat.** The determinism contract covers
-the framebuffer and the audio and says nothing about trace-format stability, so
-an unpinned oracle could turn the sibling red for a reason unrelated to its RTL.
-Green there means green against one recorded commit, and moving the pin is a
-deliberate edit.
-
-### The first independent interrupt oracle
-
-`docs/rung5-accuracycoin.md` carries the sentence this closes: *"Rung 4 had
-blargg as an independent check and it found six defects no self-written gate
-could see; rung 5 has no equivalent, and that is the single most important
-sentence in this document."* Interrupts had the same hole -- every interrupt
-gate compares the DUT against RustyNES, so a shared error between them is
-invisible by construction.
-
-`cpu_interrupts_v2`'s five single-purpose ROMs are now verdict gates, on
-**mapper 0** (the combined ROM is mapper 1; the singles are not, which removes
-MMC1 as a variable). `5-branch_delays_irq` is the sharpest of them: *"A taken
-non-page-crossing branch ignores IRQ during its last clock, so that next
-instruction executes before the IRQ."* That is the exact behaviour v2.6.7
-changed in the **oracle** -- caveat C6, `skip_irq_sample_q` -- from documentation
-reasoning alone, with no ROM adjudicating it. This one adjudicates it, on both
-consoles.
-
-Alignment is **recorded rather than assumed**: blargg's readme says
-`2-nmi_and_brk` *"Occasionally fails on NES due to PPU-CPU synchronization"*, so
-its verdict is alignment-sensitive by design and a pass is a pass at the shipped
-alignment, not an absolute one.
-
-### `T-ORACLE-001`'s opening claim is retracted
-
-The ticket says RustyNES never clocks the MMC3 counter on the pre-render line.
-It does. `mmc3_test_2/2-details` sub-test 8 is, verbatim, *"Counter should be
-clocked 241 times in PPU frame"* -- 240 visible plus the pre-render line -- and
-RustyNES passes it, as it has every release.
-
-The claim came from `--ppu-state-trace`, and the ticket's own *instrument traps*
-section says why that instrument cannot answer the question: it carries no CHR
-address column, so it reports what the sprite state was and never what address
-was driven. **A trace that could not see the event was read as evidence the
-event did not happen.** This is the second time an instrument has been mistaken
-for its subject here -- v2.6.9's `apuconflict039` was the first, where nine
-divergences "by design" were a defect in the testbench.
-
-The verdicts are unchanged: the oracle still fails `4-scanline_timing` at
-sub-test 3 and the DUT at sub-test 12, so on that ROM the DUT is still the more
-accurate of the two and `mapper4mmc3irq065` stays unregistered. Only the
-explanation was wrong.
-
-### Three claims that became checks
-
-`sys/` verbatim rested on **one measurement taken at v2.6.6** plus a manual
-procedure nothing ran -- eight releases, several of them touching the build. It
-now pins all 57 files and catches a changed, a missing **and a stray** file; the
-third mode is why the directory is enumerated rather than the manifest merely
-walked, and it is not hypothetical, since `sys/README.md` and `sys/.gitkeep`
-both lived there through v2.6.5. Re-verified against upstream in the same pass:
-`Template_MiSTer`'s HEAD **is** the pinned commit and a clone reports 0
-differences -- two claims, measured separately, because a vendored tree can be
-faithful to a commit upstream has moved past.
-
-The `.qsf` published **two** seed sweeps disagreeing about the pinned seed's
-margin by 0.155 ns, one of them a number the current RTL cannot reproduce. And
-the bitstream **name** turned out not to be a style question at all: the
-distribution builder skips any file whose stem does not end in an underscore
-plus eight digits, so a version-named core would have appeared in the Cores
-table and shipped nothing.
-
-## Rung 4 OPENS: the pulse channels and the frame counter (v2.5.9)
-
-Both pulses -- timer, 8-step duty sequencer, length counter, envelope, the
-sweep MUTE -- plus the frame counter in both modes with its IRQ and the
-`$4015`/`$4017` register file. Triangle, noise and DMC are v2.6.0/v2.6.1.
-
-**The partition was fixed before the rung** (the sibling's `docs/rung4-apu.md`),
-because the APU is the hardest chip here to gate honestly: what it produces is
-an analog level and what an emulator computes is a number. Gates are the
-`$4015` read value, the `/IRQ` pin and each channel's **integer** DAC input;
-`MixRecord`'s `f32` mix fields, the sequencer step index and `apu_phase` are
-diagnostics. `--apu-trace` on `nes_golden_export` exports the integer levels
-only.
-
-**The stimulus measurement found four ROM defects before any gate ran** --
-length index 3 is 2 and not 254, the 6502 boots with I set so `CLI` is
-mandatory, two channels at one volume are indistinguishable, and power-on work
-RAM is seeded rather than zeroed. Four findings in the DUT: the duty sequencer
-counts UP, the 4-step constants must be consistently 0-based, `$4017` bit 7
-clocks a quarter and half frame IMMEDIATELY, and the `$4017` reset delay depends
-on bit 7 -- which the wiki's "3 or 4 CPU clock cycles" does not settle.
-
-`apulen027` is exact on both surfaces; `apupulse026`'s bus surface is 3 and its
-channel levels 1,000 -- **500 runs of exactly two cycles, one per edge**, a
-uniform one-tick `$4003` write-parity sensitivity the first stimulus hid. Two
-fixes tried, both rejected by measurement. v2.6.0's first item. **Nine of ten
-mutations CAUGHT**, the two exceptions both indicting the stimulus.
-
-## Rung 7 opens: the cartridge, and two PPU defects A12 found (v2.6.9)
-
-**Five boards land** -- UxROM (2), CNROM (3), AxROM (7), MMC1 (1) and MMC3 (4)
--- in one `rtl/cart/cart.sv` whose mapper number is a runtime INPUT, because on
-MiSTer the header arrives with the game and a parameter would need a different
-bitstream per cartridge. All five match the oracle on every cycle and every
-checkpoint, and nine of nine mutations are CAUGHT.
-
-**"Five" here is rung 7's boards, not the console's.** NROM landed at rung 5, so
-the core supports **six**: NROM, MMC1, UxROM, CNROM, MMC3 and AxROM. Both counts
-are correct and they are easy to reconcile wrongly -- a reviewer did, reading
-this line against the sibling's six commercial captures.
-
-**Half the earlier "rung 7 is blocked" claim was wrong, and this corrects it.**
-Rung 7 has two parts and only one ever needed hardware: the SDRAM controller,
-whose acceptance is read/write timing against a real part. The mapper logic is
-pure logic, verifiable exactly as rungs 1-5 were. Treating them as one item
-deferred five boards behind a blocker that never applied to them.
-
-**The MMC3 scanline counter is the first thing in this core's history to consume
-PPU A12, and it found two PPU defects on its first day** -- both invisible for
-four releases because nothing had looked:
-
-- `dummy_fetch` named the RECORD dots (337, 339), not the fetch. A fetch is two
- dots, so on the even dots the address fell through to `v_addr` and the PPU put
- `v` itself on the CHR bus; `v` bit 12 is `fine_y[0]`, which alternates every
- scanline.
-- The **idle dot**. With the first fixed the extras moved rather than vanished,
- to dot 0 -- the only dot of a rendering line that drives no fetch, and so the
- only one still reaching the same fallback.
-
-Filtered A12 clocks went 1,445 -> **965, every one at dot 261**. The wiki
-gives 241 clocks per frame, and `965 = 241 x 4 + 1` -- four frames plus one
-clock, the run not ending on a frame boundary. Interrupts taken went 218-vs-158 to
-**158 and 158**, with byte-identical work RAM, and the DUT/oracle divergence
-from 10,821 cycles to 950.
-
-**The residual was two things wearing one appearance, and blargg separated
-them.** `mmc3_test_2` scores **4 of 6 on the DUT and 4 of 6 on the oracle,
-failing the same two ROMs** -- `6-MMC3_alt` correctly, since it is NEC rev B and
-both target Sharp rev A. Within `4-scanline_timing` the oracle fails sub-test #3
-(its documented, permanently-deferred 1-cycle bracket, ADR 0002 F5.0) and the
-DUT fails #2, *"Scanline 0 IRQ should occur later when `$2000=$08`"*.
-
-So part of the offset is the oracle's own residual, which must NOT be fitted to
--- that is the failure the v2.6.0 audit named. The other part is a real DUT
-defect, **shown pre-existing by control**: with both PPU fixes reverted it still
-fails #2. It is left open with a 27-second reproducer and a validated pass/fail
-signal, rather than tuned away against a reference that is itself off on the
-same axis.
-
-## An exclusion hides improvement as well as regression (v2.6.9)
-
-The co-simulation suite gates most goldens on a rolling per-cycle **checkpoint**
-hash, and carried a **deny list** of streams excluded from it. v2.6.8 established
-that such a list is an *assertion about the thing under test* — one that v2.6.7
-had invalidated twice over by changing both the DUT and the harness — and
-re-measured six entries, retiring four. v2.6.9 goes one level down, to the
-mechanism, and finds two things.
-
-**First, "by design" was a claim about the instrument.** `apuconflict039`'s bus
-surface had been excluded since v2.6.2 under a note saying it "carries nine
-divergences **by design**". **Six of the nine had already closed** and nobody
-could see it, because a denied stream is denied in both directions. The **three
-that remained** were a defect in the **harness**: on a cycle
-where the CPU is held, `tb/cpu_main.cpp` built the trace record's `bus_data` from
-a stale local rather than from the RTL's own open-bus latch. The two differ on
-exactly one rule, and it is a rule the RTL already implements correctly — a read
-of the APU status register is *internal to the 2A03* and does not drive the
-external lines, so the latch holds across it while a local tracking what the CPU
-*received* does not. Reading the latch makes the stream **identical on all
-357,361 overlapping cycles and all 88 checkpoints**.
-
-The release plan predicted a **DUT defect** here and reasoned from the correct
-rule to get there. The reasoning was sound, the rule was right, and the defect
-was one layer further out — which is the standing lesson: a measurement
-disagreeing with a rule you are confident in can indict the measurement.
-
-**Second, a denied stream is denied ENTIRELY**, so a golden whose divergence is
-one cycle out of 357,361 forfeits the other 357,360 — and an entry that silently
-*improves* is exactly as invisible as one that silently regresses.
-
-The planned fix was an allowance by **checkpoint index**, and it was implemented,
-run, and **refuted**: `tb/checkpoint.h` chains its FNV-1a, so one divergent cycle
-poisons every checkpoint after it. Allowing the first differing window moved the
-failure to the next one; allowing the rest is the all-or-nothing deny it was
-meant to replace. The allowance moved to a new **per-cycle** nine-field
-comparator, `tb/obs_diff9.py --allow-cycle`, where an attributed difference costs
-**one cycle instead of seventy-one checkpoints**.
-
-It fails **both ways**, which is what makes it adoptable: an allowed cycle that
-stops differing is a FAILURE, so an improving DUT cannot leave a stale allowance
-quietly hiding coverage. Six mutations confirm it, including a cycle named
-outside the compared window being **refused** rather than allowed to match
-nothing.
-
-The one remaining entry, `ppuoamcorrupt052`, differs on exactly one cycle —
-70,627 — which is the documented OAM-corruption asymmetry where **the DUT
-implements more of the documented rule than the oracle does** and no available
-gate can adjudicate. It is allowed and named, not resolved.
-
-## The bitstream is published from v2.6.7 (maintainer decision, 2026-08-30)
-
-**Every release from v2.6.7 ships a `.rbf`** — committed to the sibling's
-`releases/` and attached as an asset to the GitHub release on **both**
-repositories. This reverses v2.6.6, which produced a bitstream and deliberately
-did not publish it.
-
-**Why the reversal is right.** The MiSTer distribution mechanism reads the
-`.rbf` out of the *repository*'s `releases/` — since v2.6.15 as
-`releases/RustyNES_YYYYMMDD.rbf`, the only form both MiSTer parsers accept (the
-GitHub releases carry the same bytes version-named, `RustyNES_MiSTer-vX.Y.Z.rbf`
-and, from v3.4.0, `RustyNES_MiSTer-vX.Y.Z-lite.rbf`; every release's assets
-were renamed to that form on 2026-10-18; the sibling's
-`docs/bitstream-release.md`) — so an empty
-`releases/` does not describe a cautious core — it describes an undistributable
-one, withheld from exactly the people who own the boards this project does not.
-And a claim nobody made is not the same as a claim marked unverified: only the
-second is usable. So the caution moves from an absence into a disclosure.
-
-**What every release body must therefore state**, because it is what the ladder
-does and does not reach:
-
-- **No hardware has run the bitstream** (true until rung 6 closes). A booting
- core, a synced display, audible audio and a working controller are not claimed.
-- The co-simulation ladder establishes per-cycle agreement with a 141/141
- emulator on the declared compare surfaces, and AccuracyCoin agreement entry for
- entry across all 146 entries.
-- **Unverified by construction**: the PPU gate compares the *pre-palette* index
- and the APU gate compares *per-channel integer levels*, so the palette, the
- video timing constants, the audio's absolute level and its band-limiting are
- downstream of every gate. That partition is deliberate — it is what stops a
- palette difference masquerading as a rendering one — and its price is that
- those four properties have no evidence behind them until a board runs the file.
-- The Quartus version, device, error and warning counts, worst setup and hold
- slack, and the **pinned fitter seed**. The seed is load-bearing: two compiles of
- identical RTL have landed a framework HDMI path at +0.386 ns and −0.086 ns, so
- "timing closes" without a pinned seed is a statement about one placement.
-
-**Mechanism.** `scripts/release-rbf.sh ` in the sibling builds, verifies and
-uploads. It checks errors and per-clock slack **against the reports rather than
-the exit code**, because Quartus has been observed to abort after the resource
-summary and still exit 0. Full procedure and rationale:
-`RustyNES_MiSTer/docs/bitstream-release.md`.
-
-**One artifact, two boards.** The SuperStation One is a Cyclone V console that
-forks `Distribution_MiSTer` and consumes MiSTer cores directly, so the same
-`.rbf` is what both take. Whether the *identical file* boots both is a hardware
-claim and stays deferred.
-
-## Rung 3 CLOSES: VBlank, NMI, the `$2002` race (v2.5.8)
-
-The VBlank flag's full CPU-visible behaviour — the set, the clear, the
-destructive read, `suppress_vbl` for the one-clock-before race, and **the PPU's
-/NMI wired to the CPU for the first time**. Four ROMs carry it, every one with
-its stimulus measured from the oracle's trace before any gate ran; a first
-draft put a handler inside the power-on NOP slide and reset executed it, both
-sides agreeing because both read the same wrong ROM.
-
-**Both structural fixes were deletions.** The testbench's cycle split was
-`[2 pre-dots | access | 1 post]` and the oracle's is `[1 | access | 2]`
-(`read_split(12) = (5,7)`): a ~2-dot /NMI pulse from a read racing the VBL set
-was invisible to the DUT's end-of-cycle sample, and `PPU_LEAD=3` +
-`ACCESS_DOT=1` (same absolute access dot, moved boundary) fixed it — the
-pulse-stretcher built first was measured dead and deleted. And
-`render_for_skip` — v2.5.7's deferred skip-check delay — does not exist: the
-oracle's two-PPU-clock rule plus the commit-edge sampling asymmetry lands
-exactly on the rendering enable, so the extra tap was deleted and the pipe
-shrank to one stage. `ppuvbl024` had caught the DUT skipping ten pre-renders
-the oracle never skipped, invisible to the bus gate for eight frames because
-NMI delivery quantizes away single-dot drifts.
-
-**Twelve of twelve mutations CAUGHT** — the last via a cadence-breaking frame,
-because its one firing landing (enable at pre-render dot 338, odd frame) is
-unreachable by any fixed-cadence ROM: the 3-dot CPU quantum and the skip's
-1-dot drift lock odd-frame landings to one residue mod 3.
-
-**Reproducing it:** none of these is a CI gate, so the exact invocations and
-the non-zero count each prints are recorded in the sibling's
-`docs/rung3-ppu.md` under *Reproducing v2.5.8, exactly* -- including that
-`--irq-trace` is **mandatory** for every PPU golden export, without which no
-`obs.bin` is written and the bus gate cannot run at all.
-
-**nestest 0-diff at 5,002,992 cycles — the 5M window closes**, and with it
-rung 3's acceptance criteria in full. The harness serves open-bus `$40` for
-`$4016`/`$4017`; the next divergence anywhere is an APU or controller surface,
-which is rung 4. Full record: the sibling's `docs/rung3-ppu.md`.
-
-## Rung 3 continues: sprite rendering, and the phase (v2.5.7)
-
-Sprite rendering, priority, the sprite-0 hit and its no-hit-at-x=255 quirk, the
-left-8 masks, the garbage nametable fetches and the 337/339 dummies — and the
-release's real finding: **the CPU–PPU power-on phase was wrong by two dots, and
-every OAM window was compensating.** The boot traces agreed on `scanline`/`dot`
-at every instruction boundary while the per-cycle mappings differed by exactly
-two — a phase error hidden by an equal record-point offset, two errors
-cancelling. `PPU_LEAD=2` (the earlier sweep tried 0 and 3; the answer sat
-between them) moves every window from documented-minus-three to
-**documented-minus-one, which is registered-assignment semantics and no residual
-fudge** — the code came to what the RTL's comments had claimed all along.
-
-**Every gate in the rung is exact for the first time**: `ppuspr019/020/021`
-119,115 cycles each, `ppuscroll` 49,998, `ppusprender` 119,114, `ppusprite`
-59,993, `ppuregs` 12,841, fetch traces 7,058 / 88,685 (the v2.5.4 narrowing is
-**removed** — sprite fetches and the dummies are compared now), all three index
-framebuffers 61,440, `nestest` 59,554 — plus **`ppu-phase-gate`**, new: the
-inverse of `cpu-gate`'s skip list, `scanline`/`dot` only over twelve frames,
-98,562 records, the only gate that can see the **odd-frame skipped dot**'s
-one-dot-per-odd-frame drift (implemented this release; five mutations CAUGHT).
-
-**All ten of the rung's mutation catalog are CAUGHT**, re-run in full at the
-corrected phase — the tenth (sprite-0 flag read from the register only) by
-`ppuspr020` at exactly one divergence, the read landing on the hit dot. Also
-found by instrument rather than argument: `PPU_SUBDOT` (master-clock-resolution
-clocking, built to test the half-dot between `read_split` and `write_split` —
-unobservable, now measured) exposed **a register file gated by nothing**; fixed
-with `cpu_ce`, a one-clock commit strobe, latent until v2.6.5 where a held
-address would have latched twelve times per access. Deferred with owners named:
-the VBlank-race stimulus and the skip-check delay (v2.5.8), `chr_wr` (v2.6.3).
-Full record: the sibling's `docs/rung3-ppu.md`.
-
-## Rung 3 continues: sprite evaluation (v2.5.6)
-
-The evaluation FSM, secondary OAM, the eight-sprite limit, the documented
-overflow-search bug and the wiki's step 4. **All 59,993 overlapping cycles
-match**, with **seven of eight mutations CAUGHT** and the baseline verified
-passing first. The programme plan named this the hardest single item in it.
-
-**The gate observed a model the diagnostic did not expose**, and that is the
-finding worth carrying out of this step. `ppu-state-trace` carries
-`sprite_eval_n`, `sprite_eval_m` and `sprite_eval_found`, which belong to the
-oracle's *real* evaluation FSM. What a CPU read of `$2004` returns does not come
-from that machine: it comes from `tick_oam_bus`, a second, side-effect-free model
-kept alongside it. So two edits made faithful to the traced fields each moved the
-DUT **away** from the observable — 41 → 112 and 39 → 68 — and were reverted as
-regressions. Adding `oam_bus_copybuffer` to `PpuStateRecord` at schema 2 is what
-made every later measurement valid; it immediately showed the FSM sitting frozen
-at `n = 34` while the bus kept walking for the rest of the line.
-
-**One of those two regressions was then right.** The overflow halt had been
-measured while phase 4 was itself mis-implemented, so it moved the DUT into a
-broken destination. Re-measured against a correct phase 4 it is worth 28 of the
-39. *A change rejected against a broken baseline is not a rejected change.*
-
-**And the fix that closed it is the opposite of the obvious one.** The wiki says
-phase 4 copies `OAM[n][0]`, but pinning the byte index to 0 is right on scanline
-55 and wrong on scanline 58: phase 4 advances only the high half of the address,
-so the low half keeps whatever ended the walk. Three of the four paths that
-finish evaluation clear it; the sprite-eval bug path does not.
-
-**Two mutants are INERT rather than uncaught, and a first pass got that wrong.**
-The `eval_ovf_cnt` reset was reported as fixing a latent defect the stimulus
-could not reach; the stale count in fact cannot occur — a probe fires zero times
-at 528 window ends while its inverted predicate fires 528, the trace is
-byte-identical without the reset, and the bound is structural (88 decide steps to
-the latest hit, consumed by 91, in a 96-step window). It is kept as defensive
-code, not as a fix. The second inert mutant is out of *scope* rather than
-unreachable: `sprite_overflow` reaches the CPU only via `$2002`, which this ROM
-never reads. Both were classified by byte comparison, because NOT CAUGHT has
-meant four different things here.
-
-Detail: `docs/rung3-ppu.md` in the sibling repository.
-
-## Rung 3 continues: background rendering (v2.5.5)
-
-The shift registers, the fine-X multiplexer, the palette lookup and a per-pixel
-index — the first full frame this core has drawn.
-
-**Gate:** `ppurender` **all 61,440 pixels match**, **fifteen mutations all
-CAUGHT**, baseline verified passing first. The surface is the **index**
-framebuffer, pre-palette, so a palette-table difference cannot masquerade as a
-rendering one — different bugs, different rungs.
-
-**The oracle needed no change at all.** `index_fb.bin` has been exported since
-v2.4.1: the third rung step in a row costing the oracle side nothing, which is
-what choosing the compare surface *before* the rung buys.
-
-**The fault was one pixel, and the incomplete fix identified the mechanism.** The
-first run differed on 46,730 of 61,440 pixels, which reads as a broken renderer
-and was not: 13 distinct values on both sides, near-identical histograms, and
-`act[x] == ref[x-1]`. The shift registers and the dot counter advance on the same
-edge, so the documented "shift on dots 2-257" applied each shift one dot after
-the pixel that should show it. Moving only the shift window took the first wrong
-pixel from x=9 to x=17 — one tile further in — which is what proved the reload
-was out of phase too. The resolution **removes** a register: the reload is the
-pattern-high fetch's own dot, so it takes `chr_din` directly.
-
-**Five NOT CAUGHT mutations indicted the stimulus, not the gate** — and one of
-them three times, for three different reasons: horizontal arrangement aliasing
-the nametables, a zero coarse-X scroll whose only wrap `copy_x` undid before it
-reached a pixel, and a fill whose 256-period ramp made both nametables
-byte-identical. Each fix looked like it had closed the hole. **Re-run mutations
-after a stimulus change, not only after a code change.**
-
-`fb_diff.py` refuses a reference frame too uniform to test anything and is
-demonstrated firing in all four paths; the window is **read** from the oracle's
-manifest rather than transcribed. `docs/golden-fetching.md` in the sibling
-repository now specifies the standing note that had sat across six releases —
-including the requirement that golden fetching use a **pinned oracle commit**.
-That pin is not a detail: the determinism contract covers the framebuffer and
-audio and says *nothing* about trace-format stability, so an unpinned fetcher
-would turn the DUT's CI red for a reason unrelated to its RTL.
-
-## Rung 3 continues: the background fetch pipeline (v2.5.4)
-
-NT / AT / pattern-low / pattern-high fetches on the documented 8-dot cadence,
-compared against the oracle as an **address-bus** trace -- real pins, so a
-correct chip cannot differ, which is what makes it a gate rather than a
-diagnostic under `docs/rung3-ppu.md`'s partition.
-
-**Gate:** `ppufetch` **6,247 background fetches / 0 divergences** on scanline,
-dot and address, across two rendering windows. **Eight mutations, all CAUGHT**,
-baseline verified passing first.
-
-**The comparison was narrowed and said so on every run.** At this release a
-rendering scanline issued 154 fetches and the gate compared the 136 background
-ones (dots 1-256 and 321-336), excluding sprite fetches and the two dummy
-nametable reads; `fetch_diff.py` printed the excluded count for both sides
-because a narrowing that is not announced reads as full coverage. **The
-narrowing is gone as of v2.5.7** -- `COMPARED_DOT_SPANS` is `(1, 340)`, sprite
-fetches and the dummies included.
-
-**The finding: the CPU access was presented two dots early, and no existing gate
-could see it.** The DUT issued one extra nametable fetch at the leading edge of
-each rendering window and dropped one at the trailing edge, both by the same two
-dots -- one quantity wrong by one constant, not two faults. The cause was in
-`tb/cpu_main.cpp`, which presented the access on the second of the cycle's three
-PPU dots; a 6502 commits a write and samples a read at **phi2**, the third.
-
-Five gates stayed green across the move, **in both directions**: rung 1's
-registers on nine ROMs, rung 2's per-cycle bus, the interrupt sweep, and the
-v2.5.2 register and v2.5.3 scroll gates. That is not evidence the shift was
-harmless. Every one of them reads state **once per CPU cycle**, so a uniform
-two-dot shift in when a write lands *inside* a cycle moves nothing they compare.
-This is the rung's first gate keyed to the DOT counter, and the first that could
-see it.
-
-**nestest more than doubled.** Rung 2's window was bounded at 27,396 cycles by a
-missing peripheral -- nestest reads `$2002` there and the testbench had no PPU to
-answer. With the register file answering it now matches for **59,554 cycles**,
-2.18x the old extent, and the bound is an artifact budget rather than a wall.
-
-**Two mutations came back NOT CAUGHT against a correct gate**, because the ROM
-rendered from `$2000` with `PPUCTRL = 0` and so held `v[11]` and `ctrl[4]` at
-zero throughout. The gate was not blind; the stimulus was. A second rendering
-window at `$2800` with background patterns at `$1000` took the fetch count from
-3,099 to 6,247 and both mutations to CAUGHT.
-
-**Also closed: four trace features had never been linted.** No CI invocation
-named `cpu-boot-trace`, `irq-timing-trace`, `ppu-state-trace` or the new
-`ppu-fetch-trace`, and `--workspace --all-targets` reaches default features
-only, so the `rustynes-cosim` clippy step compiled those modules **as
-dependencies**, where warnings are not denied. One explicit step per feature
-now; `ppu-state-trace` had **six** `-D warnings` errors waiting in it.
-
-## Rung 3 continues: the scroll address logic (v2.5.3)
-
-`inc_x`, `inc_y`, `copy_x` and `copy_y` at their documented dots, the
-`$2007`-during-rendering dual increment, and -- found by the rung rather than
-planned into it -- **a 3-dot delay on toggling rendering**.
-
-**Gates:** `ppuscroll` **19,813 records / 0 divergences**; rung 2's bus
-comparison on the same ROM **49,993 of 49,993 cycles matching** on `pc`,
-`bus_addr`, `bus_data` and `bus_access`; phase identical throughout.
-
-> "Toggling rendering takes effect approximately 3-4 dots after the write. This
-> delay is required by Battletoads to avoid a crash."
-> -- `nesdev_wiki/PPU_registers.xhtml`
-
-This core applied a `$2001` write immediately. The rendering window was a full
-CPU cycle too wide **at both ends**, costing exactly one coarse-X increment and
-invisible to everything except a read-back of `v`.
-
-**Both implementations were self-consistent; only the documentation could say
-which was wrong.** The oracle can be wrong -- here it was not, and that was
-established rather than assumed, which is the rung-labelling rule from ADR 0037
-doing its job.
-
-**Four instruments, each killing the previous hypothesis**, and the order
-mattered more than any one of them:
-
-1. `tb/phase_delta.py` over every instruction boundary: the phase offset was
- constant, then zero once the *testbench* was fixed -- **and the gate still
- failed**. That proved the two faults independent and stopped an alignment
- change being credited with a fix it had not made.
-2. Rung 2's bus gate on `ppuscroll`: 3 of 49,993 cycles diverged, all read-back
- *values*, with the `$2001` writes byte-identical. Write-timing refuted.
-3. `ppu-state-trace` on the oracle -- the designated **diagnostic** -- showed `v`
- incrementing at 112, 120, 128, 136, 144 **and 152**. The sixth increment was
- at the END of the window, not the start.
-4. The wiki adjudicated.
-
-**The diagnostic never became a gate**, which is what `docs/rung3-ppu.md`
-reserves it for.
-
-## Rung 3 has started (v2.5.2)
-
-`rtl/ppu2c02.sv` implements the 2C02's CPU-visible register file: `$2000-$2007`
-with `$2008-$3FFF` mirroring, the VRAM/palette bus and its read buffer, palette
-and nametable mirroring, OAM, and the data-bus latch. **12,840 records, 0
-divergences, 8 mutations all caught.**
-
-The compare surface is CPU-visible reads, carried by rung 2's **existing** bus
-comparison -- a step that needs no new oracle format cannot be failed by one.
-`docs/rung3-ppu.md` in the sibling was written **before** the rung and fixes
-which fields may fail it (`index_framebuffer`, register reads, `nmi_line`, public
-test ROMs) and which may only explain a failure (`ppu-state-trace`, `v`/`t`/`x`/`w`,
-shift registers, anything RGBA).
-
-**The step also landed a behaviour the plan did not anticipate**: writes to
-PPUCTRL, PPUMASK, PPUSCROLL and PPUADDR are ignored for **~29,658 CPU clocks**
-after reset. Not modelling it made the DUT disagree on every VRAM and palette
-access while open bus and OAM stayed correct -- so the register file *looked*
-right.
-
-**And the ROM passed on its first run while testing nothing.** Four defects, each
-making both sides agree about a behaviour neither was being asked about; all four
-found by mutation, none visible by reading. The lesson is recorded in the
-sibling's `docs/rung3-ppu.md`: a passing gate is evidence only once something has
-been shown to make it fail.
-
-## Rung 2 is closed (v2.5.1)
-
-Its interrupt half was the last piece. `tb/interrupt_sweep.py` asserts /NMI,
-/IRQ, or **both together** before instruction K and holds it, for every K across
-a hazard program, driving identical stimulus into both sides: **60 injection
-points, 0 divergences** on all seven CPU fields.
-
-It found two defects, and the second is the one worth remembering. A hardware
-interrupt pushed a return address **one byte too high**, because `AM_BRK` fell
-through a generic operand-fetch increment shared with every other addressing
-mode. `BRK` and a hardware interrupt share that mode and *disagree* about it --
-`BRK` advances over its second byte, an interrupt does not -- so for `BRK` two
-writers assigned the same value and the fault was invisible. **`BRK` passing
-186/186 is what kept it hidden**: the only opcode exercising the mode was the one
-on which the bug did not show.
-
-The oracle side is [ADR 0038](adr/0038-cosim-interrupt-injection-api.md)'s
-`cosim-interrupt-inject` feature. Its precondition -- that a default build emits
-none of it -- is **measured, with a live control**: `inject_` appears 0 times in
-the expanded default core and **17** times with the feature on. The control is not
-ceremony. The ADR's original command piped a missing `cargo-expand` through
-`grep -c`, which reports the 0 it is looking for while measuring nothing.
-
-**Two v2.5.0 gates remain open and are reclassified, not carried.** nestest 0-diff
-and the 5 M-cycle window both stop at a `$2002` read where *both sides address it*
-and only the data differs -- the DUT has no PPU. They are rung-3 acceptance
-criteria.
-
----
+**Agent notes:** [`agents/mister-cosim.md`](agents/mister-cosim.md) (measured
+findings and traps, read on demand).
## What this is, and what it is not
@@ -608,34 +40,86 @@ written from public hardware documentation**, in a sibling repository
private), with **RustyNES as its verification oracle**. This document specifies
the boundary between the two - the one part that lives in this repository.
-When this section was written (2026-08-20, first shipped in v2.4.2), the sibling repository held only the
-rung-0 harness and **no RTL**, which was the ladder's design rather than a gap:
-the testbench had to be shown able to recognise agreement before anything was
-compared. It has carried RTL since v2.4.4 and now holds a complete core (see the
-release sections above). Two of its harness files matter to readers of this
-document, because they are the other half of what is specified here.
-
-`tb/checkpoint.h` reimplements this repository's checkpoint encoding in C++, and
+The sibling holds a complete console: a cycle-exact 6502, the 2C02, the 2A03,
+the mappers it implements, the Famicom Disk System, save states and rewind, all
+wrapped in the MiSTer framework (`sys/`, vendored verbatim). Its `README.md` is
+the current feature list. Each release compiles a pair of bitstreams from it
+and attaches them to the GitHub release of **both** repositories, as release
+candidates.
+
+**It may be declined as a duplicate.** `NES_MiSTer` already exists, and the
+sibling's README records that the incumbent's accuracy work in September 2026
+made the case for a second core weaker, not stronger. The comparison number is
+re-measured against the current incumbent, on the same AccuracyCoin build,
+before any submission is sent (the sibling's `docs/bringup-log.md` row F1, and
+`docs/submission-case.md`). Public release metadata about a black-boxed core is
+outside the firewall; its source is inside it (ADR 0040).
+
+**Licence.** The combined bitstream is **GPL-3.0-or-later**, which is already
+this project's licence. The framework's `sys/` carries GPL-3.0-or-later files
+that no core functions without (`hps_io.sv` among them) and no GPL-2.0-only file;
+GPL-2.0-or-later combines upward and GPL-3.0-or-later does not reduce. The audit
+and its re-verification against the vendored tree are the sibling's
+`docs/licence-audit-2026-08-20.md`. This states the licence the bitstream must
+carry; it is not a claim that the work is license-clean, which is for a human
+reviewer to establish (`docs/originality-and-provenance.md`).
+
+**The checkpoint encoding has two implementations.** `tb/checkpoint.h` in the
+sibling reimplements this repository's checkpoint encoding in C++, and
`tb/checkpoint_selftest.cpp` asserts it against **the same hardcoded vector**
`the_wire_encoding_is_pinned_to_a_fixed_vector` pins on this side. That pairing
-is the whole guard against the top-ranked risk at this rung: a packing
-disagreement between the two halves produces a hash mismatch that is
-indistinguishable from a wrong DUT, and would be debugged as one. **Changing
+is the guard against a packing disagreement between the two halves, which
+produces a hash mismatch indistinguishable from a wrong DUT. **Changing
`Observable::encode` here without changing `checkpoint.h` there breaks
co-simulation in the way that is hardest to diagnose** - so the selftest is the
first thing to run after touching either.
-Its licence audit also settled a question this side had left open. ADR 0037
-recorded that a GPL-2.0-**only** file anywhere in the MiSTer framework's `sys/`
-would force the RTL to GPL-2.0-or-later. All 57 files of an upstream clone were
-read at v2.4.3: **there is no such file**, and four are GPL-3.0-or-later -
-including `hps_io.sv`, which no core functions without. v2.6.6 re-verified this
-against the tree actually vendored (`Template_MiSTer@3ea1134c`): **40** HDL files,
-the same four GPL-3.0-or-later, nine GPL-2.0-or-later, **zero** GPL-2.0-only (the
-sibling's `docs/licence-audit-2026-08-20.md`, "Re-verified at v2.6.6"). GPL-2.0-or-later combines upward and GPL-3.0-or-later does not
-reduce, so the combined bitstream must be **GPL-3.0-or-later**, which is already
-this project's licence. The hedge is inverted by the evidence rather than
-confirmed by it.
+## The two builds
+
+Both builds come from one RTL tree and differ in where cartridge memory lives.
+The sibling's `README.md` ("The two builds") is the authoritative table; in
+summary:
+
+| | `RustyNES` (headline, off-die) | `RustyNES_Lite` (on-die) |
+|---|---|---|
+| Cartridge memory | off the die, in the SDRAM add-on (`USE_SDRAM` = 1) | on the die, in M10K (`USE_SDRAM` = 0) |
+| SDRAM add-on on a DE10-Nano | required | not required |
+| Boards | every mapper number the core implements, the **Famicom Disk System**, every expansion-audio block | the smaller set that fits on the die; the rest are refused as "Unsupported mapper" |
+| Size limit | bounded by the SDRAM | 256 KiB PRG / 128 KiB CHR |
+| More than eight sprites per line | no | yes |
+| `releases/` file | `RustyNES_YYYYMMDD.rbf` | `RustyNES_Lite_YYYYMMDD.rbf` |
+| GitHub release asset | `RustyNES_MiSTer-.rbf` | `RustyNES_MiSTer--lite.rbf` |
+
+**The FDS is off-die only.** Both builds keep the core name `RustyNES`, so they
+share `games/RustyNES/` and its saves; a save state is refused by a build whose
+chain layout or memory map differs (each state carries a fingerprint). The
+`releases/` name is the only form both MiSTer parsers accept, which is why the
+datecoded name is kept in the repository while the GitHub assets are
+version-named (the sibling's `docs/bitstream-release.md`).
+
+**One artifact, two boards.** The SuperStation One forks `Distribution_MiSTer`
+and consumes MiSTer cores directly, so the same `.rbf` is what both a DE10-Nano
+and a SuperStation One take. Whether the identical file boots both is a
+hardware claim and is not made.
+
+**How a pair is produced.** `scripts/release-rbf.sh` in the sibling verifies a
+compile against the Quartus **reports** rather than its exit code (Quartus has
+aborted after the resource summary and still exited 0): no errors, no negative
+slack on any of the four timing corners, an unchanged warning set, and a
+datecode that agrees with HEAD. `BUILD_DATE` is a constant in the design, so a
+compile on a new day is a new placement; the fitter seed is pinned per release
+and each build is compiled twice from a clean database and required to be
+byte-identical (`scripts/double-compile.sh`). The pinned seed, the margins and
+each file's md5 are in that release's notes, here (`.github/release-notes/`) and
+in the sibling's `README.md` and `CHANGELOG.md`.
+
+**Unverified by construction.** Every gate compares something upstream of the
+video timing constants, the audio's absolute level, its band-limiting, and the
+`sys/` menu options (aspect, scaling, crop). That partition is deliberate - it
+is what stops a palette or mixer difference masquerading as a rendering or
+channel one - and its price is that those properties have no evidence behind
+them until a board runs the file. The palette itself is gated (`palette-gate`
+compares `palette.sv`'s output entry for entry).
## The firewall applies to HDL
@@ -655,6 +139,28 @@ Enforcement is mechanical rather than dispositional: the repositories stay
physically outside the workspace, and CI carries a path denylist plus an
identifier grep - the same shape as the `/ref-proj/` guard.
+> **Enforcement as found on 2026-11-15.** The sibling's `.github/workflows/ci.yml`
+> carries the path denylist (it fails if a directory named `NES_MiSTer` or
+> `fpganes` is in the tree) and a check that every RTL file carries a
+> `GPL-3.0-or-later` SPDX identifier. No identifier grep for a black-boxed
+> core's names was found there or in this repository's workflows. The rule
+> above is unchanged; the gap is recorded for the maintainer.
+
+The same rule, as the project states it in
+[`agents/provenance-firewall.md`](agents/provenance-firewall.md) and the sibling
+states it in `docs/provenance.md`, covers **any other NES `rtl/`** as well. Two
+further terms bind HDL work:
+
+- **The firewall is per-region, not per-repo.** Files in this repository carrying
+ a `// Provenance:` header disclose a region derived from a GPL reference
+ emulator, and those regions are black boxes for HDL work even though the file
+ is ours: writing SystemVerilog from them would launder the original expression
+ into the DUT through this repository. List them with
+ `grep -rln "^// Provenance:" crates`; the command is the authority.
+- **The TriCNES exception does not lift the HDL rule.** TriCNES may be consulted
+ under the terms in `agents/provenance-firewall.md`, and only for this
+ emulator; it opens no HDL source.
+
## `crates/rustynes-cosim`
A pure wrapper over `rustynes-core`. It adds **no** core API and changes **no**
@@ -664,20 +170,17 @@ cannot move AccuracyCoin or nestest.
### It is excluded from the workspace, deliberately
`rustynes-cosim` is in the root manifest's `[workspace] exclude`, not its
-`members`. That is not tidiness — it is the only mechanism that makes the
-isolation real.
-
-The crate enables `cpu-boot-trace` and `irq-timing-trace` on `rustynes-core`, and
-**cargo unifies features across a workspace build**. As a member, it made
-`cargo build --workspace` compile the core once with the union, so every
-workspace build linked the **instrumented** per-cycle PPU tick loop —
-`irq-timing-trace` selects a different `for sub_dot in 0..3` loop, not an inert
-branch. CI's accuracy battery is `cargo test --workspace --release --features
-test-roms`, so it was validating a scheduler no user runs.
-
-The measured cost was +1.2% to +1.9% on `full_frame`, *below* this project's 3%
-adoption bar. Stated precisely because it shows the fix was never about speed: a
-gate pointed at the wrong code path is wrong at any percentage.
+`members`. That is the only mechanism that makes the isolation real.
+
+The crate enables trace features on `rustynes-core`, and **cargo unifies
+features across a workspace build**. As a member, it made `cargo build
+--workspace` compile the core with the union, so every workspace build linked
+the **instrumented** per-cycle PPU tick loop - `irq-timing-trace` selects a
+different loop, not an inert branch - and the accuracy battery
+(`cargo test --workspace --release --features test-roms`) validated a scheduler
+no user runs. The measured cost was small (+1.2% to +1.9% on `full_frame`, below
+the 3% adoption bar), which shows the fix was never about speed: a gate pointed
+at the wrong code path is wrong at any percentage.
**What exclusion costs, and how each cost is closed:**
@@ -688,9 +191,6 @@ gate pointed at the wrong code path is wrong at any percentage.
| `cargo fmt --all` / `clippy --workspace` / `test --workspace` do not reach it | explicit `fmt`, `clippy` and `test` steps in `ci.yml` |
| Its dependencies leave the workspace `cargo deny` graph | today only `sha2`, already in the graph; re-check if that changes |
-The clippy step justified itself immediately, reporting a `must_use_candidate`
-that `cargo clippy --workspace` had never surfaced.
-
### Crate types
`["rlib", "staticlib", "cdylib"]` - `rlib` so the golden-export binary and the
@@ -699,140 +199,155 @@ Verilator C++ testbench links the same code through the C ABI.
### The trace features are mandatory
-`Cargo.toml` enables `cpu-boot-trace` and `irq-timing-trace` unconditionally
-rather than re-exposing them as this crate's own optional features.
+`Cargo.toml` enables `cpu-boot-trace`, `irq-timing-trace`, `ppu-fetch-trace`,
+`cpu-instr-cycle-trace`, `cosim-interrupt-inject` (ADR 0038) and `debug-hooks`
+on `rustynes-core` unconditionally, rather than re-exposing them as this crate's
+own optional features. A build without them would compile, link, run, and export
+**empty** goldens - an absence of signal that reads exactly like agreement.
+Making them mandatory turns that into a compile error. Each one's comment in
+`Cargo.toml` records how it was shown to change no emulated output.
-A build without them would compile, link, run, and export **empty** goldens - an
-absence of signal that reads exactly like agreement. Making them mandatory turns
-that into a compile error.
-
-A side effect worth recording: **no CI invocation previously enabled either
-feature for clippy**, so `cpu_boot_trace.rs` and `irq_trace.rs` had never passed
-the lint gate. Adding this crate surfaced six pre-existing findings in them.
+The one optional feature, `ppu-state-trace`, is **off by default** and is a
+diagnostic: it compiles out the core's fast dot path, and the default build is
+the control that `tests/fast_path_does_not_bypass_the_fetch_trace.rs` needs.
### The power-on frame latch
The PPU is constructed at dot 340 of the pre-render line, so the 7-cycle reset
sequence ticks past the frame wrap and leaves `frame_complete` latched. **The
first `run_frame()` after construction therefore consumes that latch and returns
-without stepping a single cycle** - measured, not inferred: frame 0 advances the
-cycle counter by 0, frames 1..3 by ~29,780 each.
-
-Every other caller in the workspace runs thousands of frames, so one lost frame is
-invisible to them. It is not invisible to a golden export: a bare
-`for _ in 0..n { run_frame() }` would emit an (n-1)-frame golden under a manifest
-claiming n.
+without stepping a single cycle.**
-`Oracle::advance_frames(n)` therefore gates on the **frame counter**, not the call
-count, and bails out on a jammed CPU. The behaviour is pinned by
-`the_first_run_frame_after_power_on_advances_nothing`, so a future core change
+A bare `for _ in 0..n { run_frame() }` would emit an (n-1)-frame golden under a
+manifest claiming n. `Oracle::advance_frames(n)` therefore gates on the **frame
+counter**, not the call count, and bails out on a jammed CPU. The behaviour is
+pinned by `the_first_run_frame_after_power_on_advances_nothing`, so a core change
that removes the quirk fails a test that names it rather than silently altering
every golden's length.
## Golden formats
-`nes_golden_export --rom --out ` writes, under ``:
+`nes_golden_export --rom --out ` writes, under ``, the
+artifacts its flags arm (the binary's module documentation and its usage
+message list every flag):
| File | Format | Consumed by |
|---|---|---|
| `.boot.bin` | `CpuBootTrace` binary - 12-byte magic `RUSTYNES_CPU`, schema version, packed records | `cpu_boot_trace_diff` |
| `.irq.csv` | per-CPU-cycle IRQ/bus CSV, two samples per cycle | `scripts/irq_trace_cross_diff.py` |
-| `.index_fb.bin` | 256x240 little-endian `u16`, **pre-palette** | the testbench's frame comparison |
-| `.ram.bin` | 2 KiB CPU work RAM | `accuracy_coin_catalog::decode_results` |
| `.ckpt.bin` | rolling per-cycle hash checkpoints, `(u64 through_cycle, u64 hash)` LE, headerless | `checkpoint_diff` |
-| `.obs.bin` | full-capture observable stream, repeated 16-byte records | the testbench's self-diff, and a located-window re-run |
+| `.obs.bin` | full-capture observable stream, repeated 16-byte records | the testbench's self-diff and bus gates, and a located-window re-run |
+| `.index_fb.bin` | 256x240 little-endian `u16`, **pre-palette** | the testbench's frame comparison |
+| `.index_fb_frames.bin` | every frame's index framebuffer in order (`--fb-every-frame`) | per-frame picture gates |
+| `.fetch.bin` | per-dot PPU bus addresses, 12-byte records (`--fetch-trace`) | the PPU fetch gates |
+| `.apu.bin` | per-CPU-cycle **integer** channel levels, 16-byte records (`--apu-trace`) | the APU gates |
+| `.ext_audio.bin` | per-CPU-cycle expansion audio, 12-byte records (`--ext-audio-trace`) | the expansion-audio gate |
+| `.ppu_state.csv` | per-dot PPU model state (`--ppu-state-trace`, feature-gated) | **diagnosis only** |
+| `.ram_init.bin` | 2 KiB CPU work RAM **before** execution | the testbench, so its memory starts where the oracle's does |
+| `.ram.bin` | 2 KiB CPU work RAM after the run | `accuracy_coin_catalog::decode_results` |
| `.manifest.txt` | provenance | humans, and the drift guard below |
The framebuffer is exported **pre-palette** on purpose: a palette difference must
-not be able to masquerade as a rendering difference. That is the failure mode
-v2.3.8 "Parallax" was built to prevent.
+not be able to masquerade as a rendering difference. A trace that is armed and
+fills its capacity is refused rather than written short (see *A
+capacity-limited trace refuses*, below).
### The manifest is not decoration
The determinism contract covers the framebuffer and audio. It says **nothing**
-about trace-format stability, and `cpu_boot_trace` is at schema version 1 with a
-history of being reshaped. A routine RustyNES accuracy fix can therefore change a
-golden and turn the FPGA repository's CI red for a reason unrelated to its RTL.
-
-The manifest records the ROM SHA-256, the seed, the **requested and actually
-simulated** frame counts, the `run_frame()` call count, the cumulative CPU cycle
-count, and the emulator version - so a red diff is attributable to the right side
-of the boundary in one look rather than by bisecting two repositories.
-
-Requested and actual are recorded separately because they can legitimately differ:
-a ROM that jams stops advancing frames, and the export still succeeds. What must
-never happen is the manifest claiming a frame count that was not simulated.
-
-### Input-device and cheat stimuli (v3.2.0)
-
-Item 8 of v3.2.0 gives the MiSTer core a Four Score, an Arkanoid (Vaus) paddle
-and Game Genie style cheats, and each needs a golden with the same device
-attached on this side. Three exporter flags attach them for the whole run:
+about trace-format stability, and `cpu_boot_trace` has a history of being
+reshaped. A routine RustyNES accuracy fix can therefore change a golden and turn
+the sibling red for a reason unrelated to its RTL.
+
+The manifest records the ROM SHA-256 (and, for a disk image booted with
+`--bios`, the BIOS's), the seed, the **requested and actually simulated** frame
+counts, the `run_frame()` call count, the cumulative CPU cycle count, the
+checkpoint interval and counts, and the emulator version - so a red diff is
+attributable to the right side of the boundary in one look rather than by
+bisecting two repositories. Requested and actual are recorded separately because
+they can legitimately differ: a ROM that jams stops advancing frames, and the
+export still succeeds. What must never happen is the manifest claiming a frame
+count that was not simulated.
+
+A run option that changes what the ROM **executes** is recorded in the manifest:
+`press_start` (as `A:B`, or `none`), the stimulus devices, `sprite_limit_off`.
+Lines for options added later are written only when the option is given, so every
+earlier manifest stays byte-identical.
+
+### Input-device and cheat stimuli
+
+The input and cheat gates need a golden with the same device attached on this
+side. These exporter flags attach one for the whole run:
| Flag | Attaches | Manifest line |
|---|---|---|
| `--four-score P1:P2:P3:P4` | the Four Score, with four pads' button bytes (two hex digits each, `Buttons` bit order) | `four_score = 01:82:44:a8` |
| `--vaus POS:FIRE` | an NES (7-pin) Arkanoid controller on `$4017`: knob position (two hex digits) and fire (`0`/`1`) | `vaus = a7:1` |
+| `--zapper X:Y:TRIG` | an NES Zapper on `$4017`: aim point (two hex digits each) and trigger (`0`/`1`) | `zapper = 0a:7f:0` |
| `--genie CODE` (repeatable) | a 6- or 8-letter Game Genie code | `genie = SXIOPO,YYKPOYZZ` |
They call the emulator's existing models (`Nes::set_four_score`,
-`Nes::set_paddle`, `Nes::add_genie_code`) and change no emulated behaviour of
-their own, so `EMULATION_EPOCH` does not move. The manifest gains a line only
-when a flag is given, so every earlier manifest is byte-identical. The inputs
+`Nes::set_paddle`, `Nes::set_zapper`, `Nes::add_genie_code`) and change no
+emulated behaviour of their own, so `EMULATION_EPOCH` does not move. The inputs
are held **constant** for the run: a frame-windowed schedule would need the
DUT's testbench to reproduce the frame boundaries, and a stimulus ROM that reads
the device every frame exercises every bit of it anyway.
-Three combinations are refused rather than exported: `--four-score` with
+These requests are refused rather than exported: `--four-score` with
`--press-start` (both write port 1's buttons), `--four-score` with `--vaus` (the
-NESdev Arkanoid page: "No version is compatible with four player adapters"), and
-two codes patching one address (the emulator keeps one code per address, so the
-manifest would list a code that never applied). The parsers, the refusals, the
+NESdev Arkanoid page: "No version is compatible with four player adapters"),
+`--zapper` with `--vaus` or `--four-score` (all three use port 2, and the last
+attached device would win it), two codes patching one address (the emulator
+keeps one code per address, so the manifest would list a code that never
+applied), and an undecodable code. The parsers, the refusals, the
manifest lines and the attach path are tested in the binary's `device_tests`;
the attach test runs a ROM that strobes the ports and reads them back, so a flag
that parsed and attached nothing fails it.
## The null-DUT gate
-`crates/rustynes-cosim/tests/null_dut_self_diff.rs` is rung 0's half of the
-ladder that lives here: feed RustyNES's own golden back in as if it were the DUT
-and require zero divergences. It asserts three things, and the second and third
-exist because the first alone proves less than it appears to.
+Rung 0's half of the ladder that lives here: feed RustyNES's own golden back in
+as if it were the DUT and require zero divergences. Its tests are in
+`crates/rustynes-cosim/src/lib.rs`, and the second and third exist because the
+first alone proves less than it appears to.
- **Two independent exports are byte-identical** across the boot trace, the index
- framebuffer, work RAM, the cycle count and the call count. This is the
- determinism contract observed at this crate's boundary; if it fails, a
- pre-generated golden is *not* the trace a lockstep run would produce and
- replay-as-oracle is unsound.
-- **A one-bit corruption is caught.** A comparator that always reports agreement
- passes a self-diff trivially.
+ framebuffer, work RAM, the cycle count and the call count
+ (`the_null_dut_self_diff_is_zero_across_every_format`). This is the determinism
+ contract observed at this crate's boundary; if it fails, a pre-generated golden
+ is *not* the trace a lockstep run would produce and replay-as-oracle is
+ unsound.
+- **A one-bit corruption is caught**
+ (`a_single_flipped_bit_is_not_mistaken_for_agreement`). A comparator that always
+ reports agreement passes a self-diff trivially.
- **Five frames is five NTSC frames' worth of cycles**, in six `run_frame()`
- calls. Checked in integer half-cycles, without trusting the counter that
- produced the number.
-
-Verified against the real `cpu_boot_trace_diff` CLI as well as in-process: it
-reports `All 5464 aligned records match` and exits 0 on the self-diff, and on a
-one-bit corruption reports the divergence at cycle 561, PC `$C419`, naming the
-field and both values. The zero therefore comes from a tool that can tell the
-difference, not from one that cannot.
+ calls (`five_frames_requested_is_five_frames_of_cycles`), checked in integer
+ half-cycles without trusting the counter that produced the number.
-The other half of rung 0 -- hash-checkpoint agreement with full capture over a
-100k-cycle window, and the Verilator side of the writers -- is v2.4.2.
+The cross-repository half is the sibling's `tb/selfdiff_check.sh`: it exports
+goldens from the oracle, re-derives the checkpoints in C++ from `.obs.bin`
+alone, compares them, and then, **in the same invocation**, flips one bit and
+requires the divergence to be located - because a positive control alone is
+satisfiable by a comparison that always agrees. It needs both repositories and a
+test ROM, so it is not in CI; it exits **77** and says why when it cannot run, a
+skip that reports itself rather than a silent pass.
## Replay, not lockstep
Build time: RustyNES emits goldens. Run time: Verilator runs the DUT, the C++
-testbench writes **the same byte formats**, and the diff CLIs that already exist
-compare them.
+testbench writes **the same byte formats**, and the diff tools compare them.
The determinism contract makes this *equivalent* to lockstep - same seed + ROM +
input yields a bit-identical framebuffer and audio, so a pre-recorded trace is
exactly the trace a lockstep run would have produced. It is additionally better in
two ways: goldens are re-diffable without re-simulating, and the two sides can run
-on different machines at different times.
+on different machines at different times. `Nes` exposes `run_frame()` and
+`step_instruction()` and nothing finer, so lockstep would also need new core API
+on the hot path.
-`scripts/mesen2_cpu_boot_trace.lua` already writes `cpu_boot_trace` from a foreign
-emulator, so the FPGA testbench is the format's **third** writer, not its first.
+The DUT is the **third** writer of `CpuBootTrace`, after the oracle itself and
+`scripts/mesen2_cpu_boot_trace.lua`; `cpu_boot_trace_diff` reads it unmodified.
+The comparison tooling does not know one side is hardware.
### No DPI-C
@@ -848,17 +363,16 @@ impact: zero.
A 4200-frame AccuracyCoin run is ~125 M CPU cycles, which as per-cycle CSV is
~7.5 GB per side. Both sides instead chain a 64-bit hash over the per-cycle tuple
-and compare checkpoints every 4096 cycles - **~480 KB** for a full run. On the
-first mismatch, re-run only that window with full capture and waveforms.
-
-Implemented in `crates/rustynes-cosim/src/checkpoint.rs`. **Measured on a real
-export** rather than projected: 3 frames of AccuracyCoin is 89,343 CPU cycles,
-which is **5,372,427 bytes** of `irq.csv` against **352 bytes** of `ckpt.bin` -
-a factor of **15,263**.
+and compare checkpoints every 4096 cycles (`DEFAULT_INTERVAL`) - **~480 KB** for
+a full run at 16 bytes a checkpoint. On the first mismatch, re-run only that
+window with full capture and waveforms. Implemented in
+`crates/rustynes-cosim/src/checkpoint.rs`; measured on a real export, 3 frames of
+AccuracyCoin (89,343 CPU cycles) is 5,372,427 bytes of `irq.csv` against 352
+bytes of `ckpt.bin`.
#### What is hashed, and what deliberately is not
-`CycleRecord` carries 29 fields, and most of them are *`RustyNES`'s model*, not
+`CycleRecord` carries many fields, and most of them are *RustyNES's model*, not
hardware. `checkpoint::Observable` is the subset an external device-under-test
can genuinely produce, and `Observable::from_cycle_record` is the single place
the partition is applied - so widening it has to pass
@@ -874,10 +388,8 @@ field at once and asserts the hash does not move.
| `irq_line_at_low`, `irq_line_at_high` | the /IRQ pin, sampled twice per cycle |
| `pc` | **not** pin-visible; see below |
-Two caveats are stated rather than buried.
-
**The IRQ line is one wire.** `CycleRecord` splits its samples into
-`irq_pending_mapper_*` and `irq_pending_apu_*`, which is `RustyNES` *attributing*
+`irq_pending_mapper_*` and `irq_pending_apu_*`, which is RustyNES *attributing*
the assertion to a source. Hardware has a single wire-OR'd /IRQ input and cannot
make that distinction, so the pairs are OR'd before hashing. Hashing them apart
would fail a correct DUT for disagreeing about something it cannot observe.
@@ -887,20 +399,20 @@ program counter. It is in because the testbench wrapper can expose the internal
register and rung 1 compares it directly - but a `pc`-only mismatch means
something weaker than a bus mismatch.
-`ppu_scanline`, `ppu_dot`, `ppu_frame` and `a12_events` are out. `a12_events` is
-the sharpest case: A12 transitions genuinely are observable on the cartridge
-connector, so it is excluded for **scope**, not observability, and becomes a gate
-when the PPU rung opens.
+`ppu_scanline`, `ppu_dot`, `ppu_frame` and `a12_events` are out of the hash.
+A12 transitions are observable on the cartridge connector, so they are excluded
+for **scope**, not observability; the PPU's address bus is compared through
+`.fetch.bin` instead.
#### The hash must be reimplementable in ten lines of C++
-The top risk at rung 0 is a format-packing mismatch masquerading as an RTL bug.
-So the hash is **FNV-1a 64** - chosen for exactly one property, that a testbench
-can reimplement it without a library - and `Observable::encode` defines a fixed
-**16-byte little-endian** layout with an explicit zero pad byte, so the C++ side
-cannot hash uninitialised struct padding. Both are pinned to a hardcoded vector
-by `the_wire_encoding_is_pinned_to_a_fixed_vector`; a reordered field fails that
-test rather than producing a phantom RTL defect on the next co-simulation run.
+The format-packing mismatch masquerading as an RTL bug is the risk this guards.
+So the hash is **FNV-1a 64** - chosen because a testbench can reimplement it
+without a library - and `Observable::encode` defines a fixed **16-byte
+little-endian** layout with an explicit zero pad byte, so the C++ side cannot
+hash uninitialised struct padding. Both are pinned to a hardcoded vector by
+`the_wire_encoding_is_pinned_to_a_fixed_vector`; a reordered field fails that
+test rather than producing a phantom RTL defect.
#### Three answers, and the third is the point
@@ -916,13 +428,12 @@ different cycles cover different spans, so a hash difference between them says
nothing, and calling it a divergence would send a full-capture re-run at a window
where nothing is wrong.
-#### The gate: checkpoints agree with full capture
+#### Checkpoints must agree with full capture
Checkpoints approximate "where do these two runs first differ", traded for four
orders of magnitude of disk, and the scheme is worthless if the approximation
can disagree with the answer. `first_full_capture_difference` computes the answer
-directly; `localisation_is_consistent` states the contract, as a function rather
-than as prose here.
+directly; `localisation_is_consistent` states the contract as a function.
| full capture says | the comparison must |
|---|---|
@@ -932,85 +443,44 @@ than as prose here.
| first differs at `k` | `Inconclusive` is an acceptable, honest refusal |
| identical | `Inconclusive` is **not** acceptable |
-The third row is the one worth the effort. A divergence report naming the wrong
-window sends a full-capture re-run somewhere nothing is wrong, spends the
-debugging budget, and returns "no problem here" - which reads as evidence the DUT
-is fine.
-
-A sweep drives 331 cases across every run length around the interval boundary,
-corrupting a different observable field at a different position each time. It
-found a real defect on its first run: **a divergence at cycle zero was reported
-in a window that did not contain it.** `after_cycle` was a `u64` in which `0`
-meant both "no prior checkpoint" and "cycle zero", so the first window read as
-`(0, 0]` - empty. It is now `Option`, and `Divergence::contains` is offered
-so call sites do not reimplement a boundary that is half-open at one end and
-open-ended at the other.
+A divergence report naming the wrong window sends a full-capture re-run
+somewhere nothing is wrong and returns "no problem here", which reads as evidence
+the DUT is fine. A sweep in `checkpoint.rs` drives every run length around the
+interval boundary, corrupting a different observable field at a different
+position each time. The window before the first checkpoint is `Option`
+(`None` = no prior checkpoint), so a divergence at cycle zero is located inside
+its window, and `Divergence::contains` is offered so call sites do not
+reimplement a boundary that is half-open at one end and open-ended at the other.
#### The CSV cannot re-derive the checkpoints, so `.obs.bin` exists
-Found by trying to build the rung-0 self-diff on the CSV. `irq.csv` carries **23
-columns**, and neither `pc` nor `put_cycle_post` is among them - two of the nine
-observable fields are simply absent. So an external testbench reading the CSV
-cannot reproduce the checkpoint hashes, and "feed `RustyNES`'s golden back in as
-if it were the DUT and get zero divergences" was not implementable as designed.
-
-`.obs.bin` closes that: repeated 16-byte records in the **same wire
-encoding the hash folds**, headerless. It is the only artifact the checkpoints
-can be independently re-derived from, and it is also the input a re-run of a
-located window consumes - so it would have been needed regardless.
-
-Additive. The CSV is untouched, which matters because `scripts/irq_trace_cross_diff.py`
-and the committed `golden/irq_trace/*.csv` both depend on its shape.
+`irq.csv` does not carry `pc` or `put_cycle_post`, so an external testbench
+reading the CSV cannot reproduce the checkpoint hashes. `.obs.bin` is
+repeated 16-byte records in the **same wire encoding the hash folds**,
+headerless: the only artifact the checkpoints can be independently re-derived
+from, and the input a re-run of a located window consumes. The CSV is kept
+unchanged, because `scripts/irq_trace_cross_diff.py` and the committed
+`crates/rustynes-test-harness/golden/irq_trace/*.csv` depend on its shape.
`Observable::decode` is the inverse, and it **refuses what it does not
understand**: a non-zero reserved pad byte, an undefined flag bit, an unknown
bus-access code, a short record, a stream length that is not a multiple of 16.
-None of that is pedantry - reading a record from a newer producer as though
-nothing had changed is how a *format* divergence gets reported as a *DUT*
-divergence.
+Reading a record from a newer producer as though nothing had changed is how a
+*format* divergence gets reported as a *DUT* divergence.
The stream is emitted even when the checkpoints are refused for overflow. A hash
over a truncated trace claims a coverage it does not have; the records
themselves are just records, and are worth keeping for a re-run.
-#### The rung-0 self-diff, measured
-
-The oracle's own output fed back in as though it were the DUT, across the
-repository boundary:
-
-```console
-$ tb/selfdiff_check.sh
-1/3 exporting goldens from the oracle
-2/3 re-deriving checkpoints on this side
-re-derived 22 checkpoints from 89335 records
-3/3 comparing
-checkpoints match: 22 compared, 0 divergences
-
-negative control: one flipped bit must be located
-DIVERGED at checkpoint 10
- window to re-run with full capture: cycles (40967, 45063] (4096 cycles)
-
-rung 0 self-diff: agreement recognised, and disagreement located
-```
-
-89,335 records of AccuracyCoin, re-derived in C++ from `.obs.bin` alone, hashing
-to byte-identical checkpoints. The negative control runs **in the same
-invocation**, because a positive control alone is satisfiable by a comparison
-that always agrees.
-
-It is not in CI: it needs both repositories and a test ROM. It exits **77** and
-says why when it cannot run - a skip that reports itself, never a silent pass.
-
#### A capacity-limited trace refuses rather than truncating
-`IrqTrace::push` silently drops records once it reaches the capacity it was armed
-with, advancing an `overflow` counter nobody has to read. A checkpoint stream
-computed over a dropped-record trace hashes *fewer cycles than it claims*, and
-the two sides then disagree for a reason that has nothing to do with the DUT -
-which is worse than useless, because it looks like a legitimate divergence. So
-`Oracle::take_checkpoints` returns `CheckpointError::TraceOverflowed` naming the
-capacity to retry with, `rn_write_checkpoints` returns `-5`, and the exporter
-aborts rather than writing a short stream.
+`IrqTrace::push` drops records once it reaches the capacity it was armed with,
+advancing an `overflow` counter. A checkpoint stream computed over a
+dropped-record trace hashes *fewer cycles than it claims*, and the two sides then
+disagree for a reason that has nothing to do with the DUT. So
+`Oracle::take_checkpoints` returns `CheckpointError::TraceOverflowed`,
+`rn_write_checkpoints` returns `-5`, and the exporter aborts rather than writing a
+short stream. The APU trace is refused the same way, before anything is written.
#### One take, two artifacts
@@ -1018,17 +488,17 @@ aborts rather than writing a short stream.
checkpoints yields `None` for whichever came second - and `None` is
indistinguishable from "never armed". `Oracle::take_irq_artifacts` derives both
from a single take; the hazard is pinned by
-`taking_the_csv_first_leaves_no_trace_for_checkpoints` so it is a documented
-behaviour rather than a surprise.
+`taking_the_csv_first_leaves_no_trace_for_checkpoints`.
## What is a gate and what is diagnostic
| Surface | Role | Why |
|---|---|---|
-| nestest 7 CPU fields | **gate** | independent oracle - RustyNES is 0-diff against the Nintendulator log |
-| per-cycle bus / IRQ samples | **gate** | where 6502 implementations actually die |
+| nestest CPU fields | **gate** | independent oracle - RustyNES is 0-diff against the Nintendulator log |
+| per-cycle bus / IRQ samples (`.obs.bin`, `.ckpt.bin`) | **gate** | where 6502 implementations actually die |
+| per-dot PPU addresses (`.fetch.bin`) | **gate** | real pins, so a correct chip cannot differ |
| `index_framebuffer` | **gate** | pre-palette, so palette cannot masquerade as rendering |
-| `MixRecord` integer channel levels | **gate** | 0-15 per channel, 0-127 DMC |
+| integer channel levels (`.apu.bin`) | **gate** | 0-15 per channel, 0-127 DMC |
| AccuracyCoin RAM status vector | **gate** | compared entry for entry, including `Skipped` / `NotRun` |
| `ppu-state-trace` FSM fields | **diagnostic only** | encodes RustyNES's *modelling choices*, not hardware facts |
| mixed `f32` audio output | **diagnostic only** | the non-linear mixer and BLEP resampler are software artifacts |
@@ -1039,456 +509,169 @@ hardware, and an odd form of self-derivation given the black-box premise. Gating
mixed `f32` audio would either force the HDL to reproduce a software resampler or
produce permanent unresolvable false failures.
-**Partition every trace field into hardware-observable versus model-internal
-before the PPU rung starts.**
+**Every trace field is partitioned into hardware-observable versus model-internal
+before any gate reads it.** A diagnostic may explain a failure; it never becomes
+a gate.
+
+**AccuracyCoin is a status vector, not a RAM compare.** The sibling's gate reads
+the work-RAM dump through `accuracycoin_status`, which decodes it against the
+catalog in `accuracy_coin_catalog.rs` and reports by test. Comparing 2 KiB of
+work RAM answers a different question wrongly in both directions: it reports
+scratch bytes as failures, and it reports two runs that never started the
+battery as a pass. An all-`NotRun` vector is refused with a non-zero exit, and
+the golden uses a window measured to reach every scored entry. **A pass count is
+a claim about what ran**, so the coverage number is read alongside the agreement
+number.
+
+## How the ladder is run
+
+The ladder is the sibling's `tb/regress.sh`: every co-simulation gate, run
+against a golden directory, ending in one `TOTAL` line of passed, failed and
+expected-fail gates, with skips counted and named.
+
+```sh
+# In the sibling repository.
+tb/fetch-goldens.sh # clone the pinned oracle, export goldens/
+VERIFY=1 tb/fetch-goldens.sh # regenerate elsewhere, compare byte for byte
+ORACLE=.oracle-pinned bash tb/regress.sh # on-die ladder, against the pin
+ORACLE=.oracle-pinned USE_SDRAM=1 LADDER_JOBS=6 bash tb/regress.sh # off-die, pooled
+```
+
+**The pin.** `tb/fetch-goldens.sh` reads a full 40-hex-digit oracle commit from
+`tb/ORACLE_COMMIT`, clones that commit into `.oracle-pinned/` (or uses
+`ORACLE_DIR`), and exports every row of `tb/golden-recipes.tsv` into `goldens/`
+(gitignored; `GOLDEN_DIR` overrides it). **Pinning is the point rather than a
+caveat**: the determinism contract says nothing about trace-format stability, so
+an unpinned oracle could turn the sibling red for a reason unrelated to its RTL.
+Green means green against one recorded commit, and moving the pin is a
+deliberate edit. `VERIFY=1` regenerates into scratch, leaves `goldens/`
+untouched, and passes only if every artifact of every stem reproduces byte for
+byte - which is how a moved pin is shown not to have moved a golden. Each
+release records the pin and the `VERIFY=1` result.
+
+**The goldens are the oracle's output, not a copy in the sibling.** Nothing from
+this repository is vendored there: a second copy would be a drifting copy. The
+`golden-provenance` gate compares every golden manifest's `rom_sha256` against
+the ROM actually in the oracle checkout, and names each STALE or UNRESOLVED
+golden rather than folding it into a count.
+
+**The job pool.** `LADDER_JOBS=N` (N > 1) runs up to N gates at once; unset or 1
+runs them one at a time. The log is replayed in gate order and the tally is
+summed per gate, so a pooled run reads as the serial one. Each gate gets its own
+scratch directory, a gate whose Verilator model is not yet built runs alone, and
+gates naming the same ROM take a per-ROM lock. The pool and the in-place RTL
+mutators (`tb/mutate.sh`, `tb/mutate_apu.sh`, `tb/mutate_gate.py`) exclude each
+other through `tb/scratch/rtl-mutation.lock`. The pool's acceptance test is the
+serial run's verdict for every gate, on both builds, with a planted failure.
+
+**Expected failures are graded both ways.** `run_xfail` runs the gate in full and
+fails the suite **if it starts passing**, so a stale allowance cannot hide
+coverage. Checkpoint streams that are not compared are listed in `CKPT_DENY` in
+`tb/regress.sh`, each with its reason recorded beside it; where a stream is
+denied, the stem is compared another way (per cycle by `tb/obs_diff9.py`, or on
+the bus and the cycle of every /IRQ rise by `tb/irq_rise_diff.py`). A per-cycle
+allowance fails both ways too: an allowed cycle that stops differing is a
+failure.
+
+**Where it runs.** `regress.sh` is not a hosted CI gate and says so: it needs the
+goldens (gigabytes) and a cargo build of this repository's `rustynes-cosim`.
+The sibling's hosted `ci.yml` runs the selftests, the `sys/` and provenance
+checks, the RTL lint and subset check, the module gates and rung 1 against the
+pinned oracle, and its job names say it is a subset. The whole ladder runs by
+hand or through the sibling's `ladder.yml`, a manual-dispatch workflow on a
+self-hosted runner.
+
+**Where the current pass counts live.** Not here: counts go stale. The sibling's
+`README.md` carries the current release's ladder row (on-die and off-die,
+passed / failed / expected-fail), the run that produced it and the RTL it ran
+on; each release's notes in `.github/release-notes/` carry the same figures for
+that release.
## The oracle can be wrong
-141/141 on AccuracyCoin is not "matches silicon". Where RustyNES is wrong,
-co-simulation will drive the RTL confidently toward its bug.
+RustyNES passing AccuracyCoin in full is not "matches silicon". Where RustyNES is
+wrong, co-simulation will drive the RTL confidently toward its bug.
Every rung is therefore labelled by whether it has an **independent** oracle:
-nestest (Nintendulator) and the blargg ROMs do; trace fields with no Mesen2
+nestest (Nintendulator) and the blargg ROMs do; trace fields with no third-party
counterpart do not, and are advisory only.
-### It happened, at rung 5 (2026-08-25)
-
-This stopped being a stated risk and became a measurement.
-
-`rtl/cpu_bus.sv` was written from `nesdev_wiki/CPU_memory_map.xhtml` and
-`Open_bus_behavior.xhtml` and run against this emulator. The two agreed on
-`$4016`, `$4017`, `$5000` and `$5C34` — including the open-bus value, which the
-DUT *derives* from a latch where the testbench had hardcoded `$40` — and
-disagreed only in `$6000-$7FFF`.
-
-**The DUT was right.** An NROM board decodes nothing there, so the window reads
-open bus. `crates/rustynes-mappers/src/m000_nrom.rs` allocates 8 KiB of PRG-RAM
-unconditionally so accesses "don't fall off the edge", which is the iNES-era
-emulator default the wiki names as a problem in its own words — and it lists
-games that break on the WRAM answer, *Low G Man* and *Battletoads & Double
-Dragon* among them.
-
-Three things this establishes, in order of how much they matter:
-
-1. **The ladder can catch the oracle.** That was asserted when the programme was
- planned and is now demonstrated, which is a different kind of claim.
-2. **The correct response was to record, not to fix.** Changing it alters
+**It has happened.** `rtl/cpu_bus.sv` was written from
+`nesdev_wiki/CPU_memory_map.xhtml` and `Open_bus_behavior.xhtml` and disagreed
+with this emulator only in `$6000-$7FFF`. **The DUT was right.** An NROM board
+decodes nothing there, so the window reads open bus;
+`crates/rustynes-mappers/src/m000_nrom.rs` allocates 8 KiB of PRG-RAM
+unconditionally, the iNES-era emulator default the wiki names as a problem, and
+it lists games that break on the WRAM answer, *Low G Man* and *Battletoads &
+Double Dragon* among them. Three rules follow:
+
+1. **The ladder can catch the oracle.** That is demonstrated, not asserted.
+2. **The response is to record, not to fix on the spot.** Changing it alters
shipped behaviour on every iNES-header NROM cartridge and needs the NES 2.0
WRAM-size field, the per-game database and the full accuracy battery. It is
in [`accuracy-ledger.md`](accuracy-ledger.md) with its citation.
-3. **The gate ROM was narrowed rather than the DUT bent.** `busopen045` reads
+3. **The gate ROM is narrowed rather than the DUT bent.** `busopen045` reads
`$4020-$5FFF` and not `$6000-$7FFF`, because a gate that fails for the
oracle's limitation rather than the DUT's teaches the wrong lesson and
eventually gets switched off.
-## The two risks that had to be settled before any RTL
-
-Both were settled in v2.4.3, and **both were answered by evidence that
-contradicted what the plan assumed**. That is the point of running the
-experiment rather than reasoning about it.
-
-### Risk 1 — the `sys/` licence, which inverted its own hedge
-
-The plan required this *before any RTL is written*, because relicensing after ten
-thousand lines exist is precisely the failure
-`docs/originality-and-provenance.md` documents. Every file under
-`Template_MiSTer`'s `sys/` was read and classified by its own grant, with comment
-markers stripped and whitespace collapsed before matching.
-
-| Classification | Files |
-|---|---|
-| GPL-2.0-or-later | 9 |
-| **GPL-3.0-or-later** | **4** |
-| GPL by reference, no version stated | 4 |
-| Copyright, no grant | 4 |
-| No header | 36 |
-| **GPL-2.0-only** | **0** |
-| | **57 total** |
-
-The hedge was that a GPL-2.0-**only** file would force the RTL *down* to
-GPL-2.0-or-later. There is no such file, and the binding constraint runs the
-other way: `ddr_svc.sv`, `hps_io.sv`, `scandoubler.v` and `sd_card.sv` are
-GPL-3.0-or-later, and **`hps_io.sv` is not optional** — it is how a core receives
-a ROM from the HPS and how the OSD reaches it. GPL-2.0-or-later may be combined
-into a GPL-3 work because "or later" permits the upgrade; GPL-3.0-or-later cannot
-be reduced to GPL-2.
-
-**The combined bitstream must be GPL-3.0-or-later, which is already RustyNES's
-licence.** No relicensing is needed.
-
-### Risk 4 — the Quartus subset, fitted rather than read
-
-Quartus 17.0.2's SystemVerilog subset is materially narrower than Verilator's,
-and a construct rejected after ten thousand lines exist invalidates not one file
-but the style every file was written in. The acceptance criterion was never "it
-compiles" — it was a fitted netlist **and its resource report**, because only the
-second catches a 2 KiB memory that became 16,384 flip-flops, and Quartus does
-that silently.
-
-Quartus Prime Lite 17.0.2 Build 602, device 5CSEBA6U23I7, defaults throughout:
-
-```text
-Analysis & Synthesis was successful. 0 errors, 0 warnings
-Fitter was successful. 0 errors, 4 warnings
-
-Total block memory bits ; 16,384 / 5,662,720 ( < 1 % )
-M10K blocks ; 2 / 553
-Total registers ; 29
-Logic utilization (ALMs) ; 17 / 41,910 ( < 1 % )
-```
-
-**29 registers, not 16,413.** The inference style that worked is a
-`logic [7:0] mem [0:2047]` with one synchronous read port on a registered
-address, one synchronous write port, and **no asynchronous read** — an async read
-is the usual reason an array becomes registers. Quartus produced a Simple Dual
-Port ALTSYNCRAM unaided, populated its MIF from the `initial` block (which is how
-a boot ROM lands *inside* the block), and one-hot encoded the `enum` as a state
-machine.
-
-**This is now the required style, and every commit adding a memory quotes its
-resource line** — because the failure is silent in isolation and only becomes
-unfittable in aggregate.
-
-Nine constructs are **fitted**. Plain `case`, `priority case` and `$bits` are
-deliberately left *documented*: the kitchen sink does not exercise them, and
-"near-certainly fine" is the phrase the subset policy exists to refuse.
-Extending the subset means extending that module and re-fitting.
-
-The four fitter warnings are 58 unconstrained pins and a missing `.sdc`, in a
-module with no pinout and no timing constraints. Timing closure is a rung-6
-question.
-
-## Rung 1 — the 6502, and where it has actually got to
-
-Nine opcode groups have closed. **2115 records across nine ROMs** on rung 1,
-**4537 cycles** on the per-cycle bus gate, and **27,388 cycles of nestest** --
-all matching the oracle, and `pc` agreeing on **3551 of 3551** cycles.
-
-**Two of v2.5.0's stated gates do not close, and neither is a defect.** nestest
-0-diff over the whole run and per-cycle equality over a 5 M-cycle window both
-need a PPU: nestest reads `$2002` at cycle 27396, *both sides address it*, and
-only the data differs -- a missing peripheral, rung 3 by design. The
-interrupt-injection sweep has no oracle-side stimulus at all, so the pins, the
-hijack and delayed-`I` are implemented and **not oracle-verified**; `BRK` is,
-because a software interrupt needs no pin. `docs/adr/0038-cosim-interrupt-injection-api.md`
-records the decision that would unblock the sweep, and the two preconditions
-that void it. The RTL lives in the sibling
-repository; `RustyNES_MiSTer/docs/rung1-6502.md` is its detailed record.
-
-| release | scope | records |
-|---|---|---|
-| v2.4.4 "Ignition" | the eight-cycle reset and the single-byte implied group | 147 |
-| v2.4.5 "Compass" | immediate / zero page / absolute; loads, stores, all eight branches | 140 |
-| v2.4.6 "Abacus" | three indexed modes with the page-cross penalty; `ADC`/`SBC`; the compares | 286 |
-| v2.4.7 "Keystone" | the stack group, `JSR`/`RTS`/`RTI`, `JMP` and its page-boundary bug | 179 |
-| v2.4.8 "Palimpsest" | read-modify-write: `ASL`/`LSR`/`ROL`/`ROR` and `INC`/`DEC`, accumulator plus four memory modes | 358 |
-| v2.4.9 "Plumbline II" | the logical group; the undocumented opcodes; **and rung 2's bus half** | 236 + 317 |
-
-The earlier ROMs are re-run on every change, which is how the v2.4.5 datapath
-rewrite was shown not to regress v2.4.4.
-
-The counts are **measured** -- each one from running `cpu-gate` against a freshly
-exported golden -- rather than carried forward from the release that introduced
-the ROM. `opgroup1` closed v2.4.4 over a 0..64 cycle window and was
-reported then as 29 records; v2.4.5 widened every ROM's window to catch the
-addressing modes, and the same ROM now yields 147. Both numbers are true of
-different windows, which is exactly why a table mixing them would not add up --
-the totals here are all measured under the current windows.
-
-### What the rung has established beyond the opcodes
-
-**The DUT is the third writer of `CpuBootTrace`**, after the oracle itself and
-`scripts/mesen2_cpu_boot_trace.lua`. `cpu_boot_trace_diff` reads it with no
-modification, and `--skip-fields` already existed -- so the entire rung has
-needed **no oracle-side change**. That is the payoff of replay-rather-than-
-lockstep stated concretely: the comparison tooling does not know one side is
-hardware.
-
-**The oracle corrected our own specification.** `docs/cpu-6502.md` said reset was
-a 7-cycle sequence in one section and 8 in another. An independent implementation
-written *from that document* implemented seven and diverged on its first record.
-Reset is eight; the document is fixed. A second implementation built from a spec
-is a way of testing that spec, and this is what it found on day one.
-
-**Three tests read correctly and verified nothing**, each found by mutation and
-not by reading:
-
-- `TXS` after `TSX` -- a wrongly-flagging `TXS` computes exactly the flags `TSX`
- had already left, so the wrong answer coincided with the right one.
-- A store and load in the *same* addressing mode -- self-consistent under any
- address mutation, so it tests round-tripping rather than addressing.
-- A read of RAM the program had not written -- the oracle powers on with
- deterministic **seeded** work RAM while a flat-memory testbench starts at zero,
- so the divergence had nothing to do with the CPU.
-
-Designing each case so the **wrong answer differs from the right one** is now the
-default rather than a correction.
-
-### What CI does and does not check
-
-The sibling repository's `cpu-smoke` builds the core and runs the ROMs to
-completion, and its workflow step name says it is **not** the accuracy gate --
-because the oracle's goldens are not vendored there. They are reproducible from a
-pinned oracle commit, and a second copy would be a drifting copy.
-
-The accuracy comparison is `make -C tb cpu-gate GOLDEN=...`. Automating it needs
-golden fetching from a pinned commit, which is **not built yet and is not
-pretended to be**. That is the largest remaining hole in this rung's
-infrastructure and it is named here rather than left to be discovered.
-
-### Still open
-
-**The gap below is CLOSED as of v2.4.9.** `make -C tb cpu-bus-gate` catches both
-mutations, and the section is kept rather than deleted because the reasoning is
-what makes the gate's scope legible.
-
-Read-modify-write closed in v2.4.8 -- but its **double write did not**, in the
-sense that nothing at rung 1 verifies it. Two mutations (skip the dummy write; emit
-the modified value instead of the old one) both come back **NOT CAUGHT**,
-because neither changes a register, a flag, the final memory contents or the
-cycle count, and those are the only things `CpuBootTrace` carries.
-
-That is scoped to **v2.4.9**, beside the undocumented opcodes, rather than left
-to v2.5.0: the bus half of rung 2 needs no new RTL. `Observable` already exists
-on both sides with a byte-identical encoding, the oracle already emits it as
-`.obs.bin`, and `cpu6502` already exposes its whole bus. Wiring a writer produced
-**7 divergences across 793 cycles** on a program rung 1 scores 358/358 -- two
-causes, one harness fidelity (the testbench zeroes RAM the oracle seeds, so every
-dummy read of unwritten memory diverges) and one a genuine per-cycle access
-difference where instruction boundaries still agree.
-
-> **Historical, as of v2.4.9.** The two paragraphs below were true when written
-> and are both superseded: the undocumented opcodes landed in v2.4.9, rung 2's
-> bus half is live, and nestest now runs to 27,388 cycles. Kept rather than
-> deleted because the reasoning still explains why the rung was scoped that way
-> -- but the authoritative status is the section at the top of this file.
-
-The undocumented opcodes are **not** delivered and also move to v2.4.9.
-
-Rung 1's own gate -- nestest 0-diff over >= 8000 instructions -- is not met yet:
-the five ROMs are hand-built opcode groups, not nestest. Rung 2, the per-cycle
-bus and interrupt comparison, has not begun.
-
-### Rung 1 gets an independent oracle (v2.6.3)
-
-The whole rung above was measured against ROMs **written in this project**, and
-the section before this one says exactly what that cannot cover. That limitation
-is now partly lifted.
-
-blargg's `instr_test-v5/rom_singles` — sixteen third-party ROMs, ~2.68 M cycles
-each, predating this programme by two decades and between them exercising all
-256 opcodes — runs as a standing section of the sibling's `regress.sh`, compared
-on rung 2's per-cycle bus surface. **16 of 16 exact**, taking the suite from 50
-gates to **66**.
-
-It is the first *independent* oracle rung 1 has had, and it earned that
-description immediately by finding **three defects the self-written corpus had
-missed**, none of them in the undocumented opcodes the battery was run to
-validate:
-
-| ROM | defect |
-| --- | --- |
-| `06-absolute` | `RRA` fed its `ADC` stage the carry from *before* the instruction rather than the one the rotate produced |
-| `08-ind_x` | the 8-cycle indirect RMW forms addressed the indexed target during their *pointer* fetch cycles |
-| `03-immediate` | the PPU I/O-bus latch never decayed — a 2C02 defect, reached from a CPU ROM, three rungs after rung 3 closed |
-
-The `RRA` finding is the one worth carrying forward, because of what it says
-about compare surfaces rather than about the 6502. **The instruction's own bus
-trace was identical on both sides** — read `$FF`, dummy-write `$FF`, write
-`$7F` — and the divergence appeared nine cycles later in the `STA` that spilled
-the accumulator, off by exactly one. A gate on the memory side of
-read-modify-write would have passed it, and so would this rung's own
-register-boundary trace had the next instruction not stored the accumulator
-straight away.
-
-Two hooks were needed to run third-party ROMs at all, and both are about **not
-transcribing a number**: the window comes from each golden's own manifest rather
-than a `CYCLES_` line, and the board's `$6000-$7FFF` work RAM is presented
-per-ROM (blargg reports through it) rather than by default — NROM has none, which
-is the oracle defect recorded above.
-
-## Rung 5 — the console, and the master-clock substrate
-
-NROM, the work RAM, the CPU bus, the controller ports and DMC DMA are landed and
-gated in the sibling; `nes_top` assembles them, carries **no observation ports**,
-and as of v2.6.3 **divides one 21.477272 MHz master clock** rather than taking
-its clock enables from the testbench.
-
-### The divider is this repository's own substrate, in SystemVerilog
-
-The obvious shape — a modulo-`CPU_DIV` phase counter with the dot at
-`phase[1:0] == 3` — looks equivalent on NTSC and is a dead end. PAL is 16 master
-clocks per CPU cycle and 5 per dot, i.e. **3.2 dots per CPU cycle**, and no
-counter that restarts each CPU cycle can hold a fractional ratio.
-
-`Bus::run_ppu_to` does not do that. It keeps `master_clock` and `ppu_clock` as
-**independent accumulators in master-clock units** and emits a dot whenever
-`ppu_clock + ppu_divider <= master_clock`, letting dot boundaries drift across
-the CPU cycle — which is exactly what PAL does. The DUT copies that structure, so
-retargeting is a parameter change (NTSC 12/4, PAL 16/5, Dendy 15/5).
-
-Two constants come from `Cpu` rather than from a sweep. `read_split(12)` is
-(5, 7) and `write_split(12)` is (7, 5) — `CPU_DIV/2 ∓ PPU_OFFSET` — with the PPU
-run to that point minus `PPU_OFFSET`. On NTSC a read observes at master clock 5
-and a write commits at 7, and **both fall inside the same dot**, which is why the
-DUT's earlier read/write placement sweep measured them onto one dot: this model
-predicted it. `PPU_OFFSET` is also applied as a real phase offset between the
-accumulators, so a cycle's last dot commits *before* the CPU rather than on the
-same edge.
-
-### What it found: an enable that is constant is not an enable
-
-The DUT's testbench used to tie `ce` high and pulse `clk` once per CPU cycle. The
-clock was doing the gating the enable was supposed to do, so **any `always_ff`
-not gated by `ce` was correct only by accident** — under a real master clock each
-fires twelve times. Four sites, two of them previously unknown:
-
-| site | symptom |
-|---|---|
-| PPU CPU-register block (v2.5.7) | a held address latched twelve times per access |
-| open-bus decay reload | refresh never observed; `$2002` read `$00` for `$1F` |
-| DMC DMA acknowledge | the sample pointer advanced by **twelve** per byte; 91% of cycles diverged |
-| frame-counter IRQ set points | `/IRQ` rose eleven master clocks early; the CPU took the interrupt **one instruction sooner** |
-
-The last was caught by blargg's `08.irq_timing` — third-party, so an independent
-oracle rather than our own trace agreeing with itself.
-
-### A fix that worked, and was rejected
-
-Delaying the APU's `/IRQ` by one cycle in `nes_top` also produced 66 of 66, and
-is **indistinguishable from the real fix by gate result**. It was not adopted:
-`Cpu::handle_interrupts` samples IRQ at phi2 into `mc_run_irq` and dispatches on
-`mc_prev_run_irq` — the one-cycle register this codebase calls
-"second-to-last-cycle recognition" — and the DUT's `cpu6502.sv` already
-implements exactly that, correctly gated. A second delay outside it would have
-cancelled an APU-side error rather than corrected it.
-
-**This is the general hazard of an oracle-defined compare surface**, stated once
-so rungs 6 and 7 inherit it: a fix that greens the gate is not evidence the fix
-is right. Continuing to look for a cause after the symptom cleared is the only
-thing that separated the two here.
-
-### Where the three-way disagreements are recorded
-
-The sibling's `docs/oracle-vs-documentation.md` is the umbrella ledger: per
-subsystem, where the DUT, this emulator and the public documentation differed,
-which won, and why — using the same six categories as the APU chapter that
-preceded it. It carries the one entry so far where **this emulator** was the one
-that was wrong (NROM's PRG-RAM window), and the sharpest category-1 entry yet:
-the PPU's open-bus decay deadline, where the documentation says 3-30 ms, this
-emulator uses 558.7 ms, and the DUT's corpus forces >= 523.4 ms.
-
-### AccuracyCoin runs end to end, and the gate is a status vector
-
-The full run now completes on the DUT — **17,868,316 cycles**, where it
-previously halted early — which is what "first end-to-end AccuracyCoin run"
-in the plan's v2.6.3 row asked for.
-
-The comparison is `accuracycoin_status`, on this side. It reads a work-RAM
-dump, decodes it against the 146-entry catalog in
-`accuracy_coin_catalog.rs`, and reports by test rather than by address. It
-filters in both modes rather than dumping all 146 rows: given one dump it
-prints the entries that are **not a clean `Pass`**, and given two it prints only
-the entries where they **disagree**. The vector is decoded in full either way --
-what is filtered is the output, not the comparison. First
-measurement: **137 of 146 entries agree, 9 differ**, six of those sharing one
-failure code — five `SH`-group stores and Open Bus — which reads as one shared
-address-bus cause rather than six independent defects.
-
-**Producing the vector is v2.6.3's deliverable. Making the two agree is
-v2.6.4**, and the plan says so in its own acceptance row.
-
-**The "six sharing one failure code" reading was wrong, and v2.6.4 measured why.**
-AccuracyCoin's `TEST_Fail` reports `(ErrorCode << 2) | 2` and the runner sets
-`ErrorCode` to 1 before *every* test routine, so the code is an index **within
-one routine**: `Open Bus`'s code 7 is its own seventh assertion and `SHA (abs),Y`'s
-code 7 is that routine's seventh. Two entries sharing a code share nothing. What
-actually closed the five `SH` entries was the SH group's RDY-conditional store
-and its addressing-mode-dependent dummy cycle — a real shared cause, identified
-from the opcodes. `Open Bus` was untouched by that work and remained, which
-should have refuted the shape argument at the time.
-
-**And the number underneath the agreement.** Once all nine closed, the vector
-reported identical entry for entry across all 146 — with **58 of those entries
-`NotRun` on both sides**. The comparator was right; the run window was short.
-Broken down by suite, 600 frames reaches the CPU catalog and stops partway
-through `CPU Interrupts`, so the run asked the DUT nothing about the APU, PPU,
-sprite-evaluation or PPU-misc suites — the chips rungs 3 and 4 exist for.
-Measured rather than estimated, **4500 frames reaches all 146** (134,012,761
-cycles), and that is the golden the gate now uses. A pass count is a claim about
-what ran, and what ran has to be measured separately.
-
-Decoding the codes properly is also what closed two of the last three, in
-v2.6.4: `Open Bus` (a `$4015` read does not drive the data bus, and its D5 is
-open bus) and `Interrupt flag latency` (the interrupt poll is the second-to-last
-cycle, and branches poll before cycles 2 and 4 but never before 3). Both rules
-are stated by the test ROM's own comments and by neither of the nesdev pages the
-implementation was written from. `NMI Overlap BRK` is carried to v2.6.5 with its
-disagreement measured per sweep step rather than as one byte — see the sibling's
-`docs/rung5-accuracycoin.md`.
-
-Two properties are worth recording, because both are about what the comparison
-*refuses* rather than what it reports:
-
-- **It is not a RAM byte-compare, deliberately.** Comparing 2 KiB of work RAM
- answers a different question and answers it wrongly in both directions: it
- reports scratch bytes — a stack slot, a loop counter, a result the ROM is
- about to overwrite — as failures, and it reports two runs that never started
- the battery as a *pass*, because two idle title screens have identical RAM.
-- **An all-`NotRun` vector is refused with a non-zero exit.** That case — two
- vectors agreeing on 146 entries of nothing — is precisely the shape of the
- vacuous status-address assertion v2.6.2 found in the NTSC blargg suite, which
- reported 11/11 for five minor releases while asserting nothing. A comparison
- that cannot distinguish *agreed* from *never ran* is not a gate.
-
-Reaching the run cost **two false passes before a real one**: AccuracyCoin idles
-on its title screen until START is pressed, and only the framebuffer half of the
-export had a guard that refused an idle capture. The manifest now records
-`press_start` — as `A:B`, or the literal `none` — because a controller press
-changes what the ROM *executes*, and a manifest omitting it describes an idle
-title screen and an 88-result battery identically.
-
-## Rung 4 — the 2A03, and the audit it prompted
-
-Rung 4 opened at v2.5.9 with the two pulse channels and the frame counter, and
-**v2.6.0 "Assay"** adds the triangle, the noise channel and the sweep unit. Eleven
-gate ROMs, 35 of 35 mutations CAUGHT, and 30 gates green across rungs 1–4.
-
-Detail lives in the sibling repository (`docs/rung4-apu.md`), but two things
-belong here because they are about the *programme*, not about the APU.
-
-### The oracle is an emulator, and rung 4 is where that stopped being abstract
-
-Every rung-4 gate compares the DUT against RustyNES. A shared error between the
-two is therefore invisible **by construction**: the DUT is tuned until it agrees,
-and agreement with a wrong reference is indistinguishable from correctness.
-
-`docs/apu-oracle-vs-documentation.md` in the sibling repo is the response —
-a standing ledger of every place the DUT follows the oracle rather than the NESdev
-wiki, sorted by risk, each with the documentation text it is measured against and
-the independent check that would adjudicate it. Its maintenance rule is the load-
-bearing part: **an item closes only when a gate exercises it *and* a mutation
-against it is CAUGHT.**
-
-The independent check was run at v2.6.0 for the first time: **the oracle passes
-blargg's APU battery 29/29**. That is recorded per item rather than as a headline,
-because it means different things in different places — for two items it moved
-suspicion off the oracle and onto the RTL, and for one there is no adjudicating
-ROM at all, which is itself the finding.
-
-### Two errors that were cancelling, and what that says about mutation testing
-
-The `$4017` reset delay had been keyed on the mode bit, which the wiki never
-mentions. It was exact *only* in combination with a second constant held one tick
-off its documented value; either correction alone costs 2 cycles, in opposite
-directions. The fitted rule was not merely unfalsified by the stimulus — it was
-**load-bearing for a second error**, which is why it survived both a mutation
-catalog and a documentation audit that looked directly at it.
-
-This is the third time the programme has found two errors cancelling (v2.5.7's
-`PPU_LEAD`, v2.6.0's own observation point), and the first where one propped up
-the other rather than merely coinciding with it. **A green mutation catalog does
-not establish that constants are individually right** — only that the combination
-in the tree is not detectably wrong on the current stimulus. Cross-checking each
-constant against documentation is a separate activity, and rung 4 is where the
-programme learned to do it.
+**A fix that greens the gate is not evidence the fix is right**, on an
+oracle-defined compare surface: a compensating delay outside the real cause can
+produce the same verdict. And **a green mutation catalog does not establish that
+constants are individually right** - only that the combination in the tree is
+not detectably wrong on the current stimulus. Cross-checking each constant
+against documentation is a separate activity.
+
+**Where disagreements are recorded.** Each place the DUT, this emulator and the
+public documentation differed, which one won, and why:
+
+- the sibling's `docs/oracle-vs-documentation.md` - the umbrella three-way
+ ledger (the CPU, the PPU, the bus, the cartridge and the system substrate);
+- the sibling's `docs/apu-oracle-vs-documentation.md` - the APU's deeper chapter,
+ in the same categories; an item closes only when a gate exercises it **and** a
+ mutation against it is caught;
+- this repository's [`accuracy-ledger.md`](accuracy-ledger.md) - where the oracle
+ itself was found wrong.
+
+## Rung status
+
+Strictly ordered: a rung may not start until the one below is green. This is the
+state at v3.7.1, from the sibling's `README.md` ("The verification ladder") and
+its `docs/rung*.md`; those are authoritative if they disagree with this table.
+
+| Rung | Gate | Independent oracle? | Status |
+|---|---|---|---|
+| 0 · harness | null-DUT self-diff = 0 across every format | n/a | closed |
+| 1 · 6502 functional | nestest 0-diff; per-cycle bus equality over blargg's `instr_test-v5` | **yes** - Nintendulator, blargg | closed |
+| 2 · 6502 cycle-exact | per-cycle bus equality + swept interrupt injection (ADR 0038) | partial - blargg `cpu_interrupts_v2` | closed |
+| 3 · 2C02 | pre-palette `index_framebuffer` equality, fetch and register gates | no | closed |
+| 4 · 2A03 | integer channel levels, **not** the mixed `f32`; bus equality on blargg's battery | **yes** - blargg's APU suites | closed |
+| 5 · NROM + AccuracyCoin | status vector identical **entry for entry** | no | closed |
+| 6 · MiSTer integration | boots on hardware from one `.rbf` | n/a | **open** - no board has run it; `docs/bringup.md` reads NOT RUN |
+| 7 · mappers + SDRAM | per-board bus and frame equality; SDRAM timing against a real part | no | banking green and shipped; the SDRAM path is unverified on hardware |
+
+Rungs 0-5 are pure simulation and need no hardware. Rung 7's SDRAM controller
+runs the headline build and its ladder, but its pin constraints are provisional
+and its read capture assumes zero board delay (the sibling's `docs/sdram.md`).
+
+Per-rung records, in the sibling: `docs/rung1-6502.md`, `docs/rung3-ppu.md`,
+`docs/rung4-apu.md`, `docs/rung5-accuracycoin.md`, `docs/rung6-integration.md`,
+`docs/rung7-mappers.md`. How rungs 1 to 5 were closed, release by release, is in
+[`archive/mister-history-v2.5-to-v3.0.md`](archive/mister-history-v2.5-to-v3.0.md).
+
+## Where to read more
+
+- **The sibling repository**,
+ [`doublegate/RustyNES_MiSTer`](https://github.com/doublegate/RustyNES_MiSTer)
+ (private): `README.md` (current features, the two builds, the current ladder
+ row, installation), `docs/provenance.md`, `docs/bitstream-release.md`,
+ `docs/golden-fetching.md`, `docs/rtl-subset-policy.md` (the Quartus 17.0.2
+ subset, fitted rather than read), `docs/bringup.md`.
+- **Agent notes:** [`agents/mister-cosim.md`](agents/mister-cosim.md) - measured
+ findings and traps for this boundary, each with its evidence.
+- **History:**
+ [`archive/mister-history-v2.5-to-v3.0.md`](archive/mister-history-v2.5-to-v3.0.md)
+ (frozen) for v2.4.1 to v3.0.x, and `CHANGELOG.md` after that.
+- **Each bitstream pair's md5, seed and timing margins:** that release's notes in
+ [`.github/release-notes/`](../.github/release-notes/), and the sibling's
+ `README.md` and `CHANGELOG.md`.
From 768f435b6d084bfd08e7e157306a263e0ba07035 Mon Sep 17 00:00:00 2001
From: DoubleGate
Date: Sun, 15 Nov 2026 22:38:32 -0500
Subject: [PATCH 16/18] docs(adr): ADR 0037 amendment, the identifier grep is
built and what it cannot catch
ADR 0037's Consequences claim the HDL black-box rule is enforced by "a
path denylist and identifier grep in CI". Only the denylist existed (see
the dated note added to docs/mister.md in acdf36ab). The maintainer
chose to build the grep rather than amend the claim away. It is the
sibling's tb/check_hdl_firewall.py, in its CI from v3.7.1 (sibling PR
#80).
A dated amendment records three things:
- the decision;
- the grep's scope: names, repository paths and the author's handle, in
rtl/, tb/ and the Quartus build inputs, with documentation out of
scope;
- what it does not do.
It is a tripwire for references, not evidence that nothing was copied.
It cannot match those cores' module, signal or constant names without
reading their source, which this ADR forbids. Independence rests on the
rule, the escalation ladder and human and outside review, and a green
run is never to be cited as showing the RTL independent.
The ADR's original text is unchanged; the amendment is appended, as this
ADR's earlier amendments were.
docs/mister.md: the "enforcement as found" note is replaced by one that
says what the grep is, in the same terms, and links the amendment's
anchor (checked against GitHub's slug rule).
markdownlint passed on both files.
Co-Authored-By: Claude Opus 5.5
---
...fpga-core-independent-hdl-implementation.md | 8 ++++++++
docs/mister.md | 18 ++++++++++++------
2 files changed, 20 insertions(+), 6 deletions(-)
diff --git a/docs/adr/0037-mister-fpga-core-independent-hdl-implementation.md b/docs/adr/0037-mister-fpga-core-independent-hdl-implementation.md
index 72319f43..16660dfc 100644
--- a/docs/adr/0037-mister-fpga-core-independent-hdl-implementation.md
+++ b/docs/adr/0037-mister-fpga-core-independent-hdl-implementation.md
@@ -172,3 +172,11 @@ board will run the core.
**Decision (the maintainer, 2026-11-06).** Keep the RTL (sibling `8aae36b`, `rtl/ppu2c02.sv`'s `ale_hi` and `at_read_dot`) and declare the read. The rule it implements is the one ADR 0030's amendment states in prose, and the agent reports taking nothing from the functions beyond it. That is recorded as a claim for human and outside review, not a certification. The declaration is in the sibling: the site comment in `rtl/ppu2c02.sv` and the "Disclosures: oracle source read during v3.6.2" section of its `docs/provenance.md` (sibling `bf41f56`), and in a new sibling `NOTICE` carrying TriCNES's MIT notice, added whether or not the register is judged a derivative (CodeRabbit on #640).
**What does not change.** D15 still requires the amendment BEFORE a derived region is read. This one records a read after the fact and authorises nothing further. The next agent brief for sibling PPU work states the rule explicitly.
+
+## Amendment (2026-11-15): what the identifier grep does and does not catch
+
+**Context.** The Consequences above say the black-box rule is mitigated by "a path denylist and identifier grep in CI". Rewriting `docs/mister.md` on 2026-11-15 found that only the denylist existed: the sibling's CI failed on a `NES_MiSTer` or `fpganes` directory in the tree, and nothing grepped the sources.
+
+**Decision (the maintainer, 2026-11-15).** Build the grep rather than amend the claim away. The sibling's `tb/check_hdl_firewall.py` (v3.7.1), run with its self-test in its CI, fails when a black-boxed core's name, repository path or author's handle appears in `rtl/`, `tb/` or the Quartus build inputs (`*.qsf`, `*.qip`, `*.sdc`, `*.tcl`). Documentation is out of scope, since it names `NES_MiSTer` legitimately (the stock core for hardware A/B tests, the firewall statement itself).
+
+**What it does not do.** It is a tripwire for references, not evidence that nothing was copied. It cannot search for those cores' module, signal or constant names, because building that list would mean reading their source, which this ADR forbids. Logic transcribed with every name changed passes it. The rule itself, the escalation ladder, and human and outside review remain what independence rests on; a green run of this check is never to be cited as showing the RTL is independent. Its failure message says not to reword or delete a matching line: an attribution means derived code, which goes to the maintainer.
diff --git a/docs/mister.md b/docs/mister.md
index ce6c0fdf..16829199 100644
--- a/docs/mister.md
+++ b/docs/mister.md
@@ -139,12 +139,18 @@ Enforcement is mechanical rather than dispositional: the repositories stay
physically outside the workspace, and CI carries a path denylist plus an
identifier grep - the same shape as the `/ref-proj/` guard.
-> **Enforcement as found on 2026-11-15.** The sibling's `.github/workflows/ci.yml`
-> carries the path denylist (it fails if a directory named `NES_MiSTer` or
-> `fpganes` is in the tree) and a check that every RTL file carries a
-> `GPL-3.0-or-later` SPDX identifier. No identifier grep for a black-boxed
-> core's names was found there or in this repository's workflows. The rule
-> above is unchanged; the gap is recorded for the maintainer.
+> **What the identifier grep is (2026-11-15).** Until v3.7.1 the sibling's CI
+> carried only the path denylist (it fails if a directory named `NES_MiSTer`
+> or `fpganes` is in the tree) and an SPDX-header check; the grep was claimed
+> here and not built. v3.7.1 adds it: `tb/check_hdl_firewall.py`, run with its
+> self-test in the sibling's CI, fails when a black-boxed core's name,
+> repository path or author's handle appears in `rtl/`, `tb/` or the Quartus
+> build inputs. **It is a tripwire for references, not evidence that nothing
+> was copied.** It cannot match those cores' module, signal or constant names,
+> since listing them would mean reading their source; logic transcribed with
+> every name changed passes it. Independence rests on the rule and on review,
+> as [ADR 0037's amendment of 2026-11-15](adr/0037-mister-fpga-core-independent-hdl-implementation.md#amendment-2026-11-15-what-the-identifier-grep-does-and-does-not-catch)
+> records.
The same rule, as the project states it in
[`agents/provenance-firewall.md`](agents/provenance-firewall.md) and the sibling
From 47a2d8dd3326dafef531a2e079c4f382cab712f8 Mon Sep 17 00:00:00 2001
From: DoubleGate
Date: Mon, 16 Nov 2026 01:45:28 -0500
Subject: [PATCH 17/18] ci(cleanup): grant the deployments job actions: read
for the environment list
prune-deployments.sh lists the live environments
(GET /repos/{repo}/environments) to decide which deployments are still
an environment's newest, and fails closed when that list comes back
empty. For GITHUB_TOKEN that endpoint needs the Actions read
permission, which the job did not grant. The listing would be refused,
and the cleanup would exit before changing anything on every run,
quietly, since a failed run of a scheduled job is easy to miss
(CodeRabbit on #666, outside-diff comment on bff4cd0).
This adds actions: read to that job only. The workflow's top-level
permissions stay at contents: read. The environments job uses
ENV_CLEANUP_TOKEN, not GITHUB_TOKEN, so it is unaffected.
Verification is limited to actionlint, which is clean. The first real
run happens on main after this PR merges; its log will show the
listing succeed or fail.
Co-Authored-By: Claude Opus 5.5
---
.github/workflows/preview-env-cleanup.yml | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/.github/workflows/preview-env-cleanup.yml b/.github/workflows/preview-env-cleanup.yml
index c8ad53c7..87051102 100644
--- a/.github/workflows/preview-env-cleanup.yml
+++ b/.github/workflows/preview-env-cleanup.yml
@@ -72,6 +72,11 @@ jobs:
permissions:
contents: read
deployments: write
+ # `GET /repos/{repo}/environments` (prune-deployments.sh's list of live
+ # environments) is an Actions-read endpoint for GITHUB_TOKEN. Without it
+ # the listing is refused, the script fails closed, and the cleanup
+ # deletes nothing on every run (CodeRabbit on #666).
+ actions: read
steps:
- uses: actions/checkout@v7
with:
From 5087416002ec9125624e9a044b440acde8dba663 Mon Sep 17 00:00:00 2001
From: DoubleGate
Date: Mon, 16 Nov 2026 02:55:23 -0500
Subject: [PATCH 18/18] ci(cleanup),docs(plan): skip deployments after a
cancel; record v3.7.1's outcome
Antigravity's 06:57 UTC round on #666.
preview-env-cleanup.yml: the deployments job ran on `always() && ...`,
so it ran whether `environments` failed, was skipped or succeeded. But
`always()` is also true after a run is cancelled, so a cancel during
`environments` still started the deletions. It is now `!cancelled()`,
which keeps the failed-or-skipped behaviour and stops after a cancel.
actionlint is clean.
to-dos/plans/v3.7.1-plan.md still read as an uncut proposal: "whether to
cut it is the maintainer's call", and every sprint status was a dash.
The opening paragraph now says it was cut on 2026-11-15 as "Imprint" and
names CHANGELOG [3.7.1] as the record. An outcome list states:
- rows 4 and 7 are deferred to v3.7.2;
- row 13's sweep was partial;
- what shipped beyond the plan.
Row 11 (longest-first ladder ordering) is marked as not found rather
than done. The release tree's tb/regress.sh has no duration ordering;
the pool drains per build directory instead. The sprint table's statuses
say the same, and the rows below keep their original wording as the
plan of record.
Gates: markdownlint passed; release_state_prose_audit 9/0,
release_anchor_audit 18/0.
Co-Authored-By: Claude Opus 5.5
---
.github/workflows/preview-env-cleanup.yml | 7 +++---
to-dos/plans/v3.7.1-plan.md | 30 +++++++++++++++++------
2 files changed, 26 insertions(+), 11 deletions(-)
diff --git a/.github/workflows/preview-env-cleanup.yml b/.github/workflows/preview-env-cleanup.yml
index 87051102..884655b3 100644
--- a/.github/workflows/preview-env-cleanup.yml
+++ b/.github/workflows/preview-env-cleanup.yml
@@ -60,11 +60,12 @@ jobs:
# After `environments`, so one run removes a stale preview's environment AND
# its deployments (listed before, the environment still existed and its
# newest deployment was kept until the next run), and so this sees the
- # deployment that job's own `environment:` just created. `always()`: it runs
- # when that job is skipped or fails too (Antigravity on #666).
+ # deployment that job's own `environment:` just created. `!cancelled()`: it
+ # runs when that job is skipped or fails too (Antigravity on #666), but not
+ # after a run is cancelled, which `always()` would still start it for.
needs: environments
if: >-
- always()
+ !cancelled()
&& github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
&& (github.event_name != 'delete' || github.event.ref_type == 'branch')
runs-on: ubuntu-26.04
diff --git a/to-dos/plans/v3.7.1-plan.md b/to-dos/plans/v3.7.1-plan.md
index 6f457bf3..c639a54d 100644
--- a/to-dos/plans/v3.7.1-plan.md
+++ b/to-dos/plans/v3.7.1-plan.md
@@ -1,11 +1,25 @@
# v3.7.1 "Imprint": the spectator id, faster gates, the MiSTer FDS fixes, and honest licensing (CUT 2026-11-15)
-A patch release after v3.7.0 "Spindle" (2026-11-10), proposed on 2026-11-12.
-**Whether to cut it is the maintainer's call**: nothing here is started
-because of this plan. If it is not cut, every row moves to
-[`v3.8.0-plan.md`](v3.8.0-plan.md), section "Carry-overs", with the same
-gate. The codename is asked at the cut.
+A patch release after v3.7.0 "Spindle" (2026-11-10), proposed on 2026-11-12
+and **cut on 2026-11-15 as "Imprint"** (the maintainer's codename).
+
+**Outcome.** [`CHANGELOG.md`](../../CHANGELOG.md) `[3.7.1]` is the record of
+what shipped; this plan is kept as written below, as the plan of record.
+- **Deferred to v3.7.2:** row 4 (the parallel coverage boot's timing run, which
+ needs a quiet host) and row 7 (the `test-roms` LTO A/B, which needs a
+ dispatch input).
+- **Not found in the release tree:** row 11 (longest-first ordering). The
+ ladder pool drains per build directory instead, and `tb/regress.sh` has no
+ duration ordering, so the row is carried forward rather than marked done.
+- **Row 13:** the release sweep was partial. Seed 7 is pinned, and only
+ seeds 1, 7 and 12 were measured on both builds; see the CHANGELOG.
+- **Added during the release, not planned here:**
+ - REUSE 3.3 compliance in both repositories, with the apps' notices;
+ - the preview-deployment cleanup workflow;
+ - the HDL firewall's identifier grep in the sibling's CI (ADR 0037's
+ amendment of 2026-11-15);
+ - README and CHANGELOG sweeps in both repositories.
## Why a patch release (the recommendation)
@@ -141,6 +155,6 @@ gate. The codename is asked at the cut.
| Sprint | Deliverable | Gate | Status |
| --- | --- | --- | --- |
-| 3.7.1-S1 | Rows 1-9 (oracle) | their gates | — |
-| 3.7.1-S2 | Rows 10-12 and 14-17 (sibling), after #74 | their gates | — |
-| 3.7.1-S3 | Row 13, the release sweep and bitstreams, last | its gate | — |
+| 3.7.1-S1 | Rows 1-9 (oracle) | their gates | done, except rows 4 and 7 (v3.7.2) |
+| 3.7.1-S2 | Rows 10-12 and 14-17 (sibling), after #74 | their gates | done, except row 11 (see Outcome) |
+| 3.7.1-S3 | Row 13, the release sweep and bitstreams, last | its gate | done: seed 7, partial sweep |