diff --git a/.github/release-notes/v3.7.1.md b/.github/release-notes/v3.7.1.md new file mode 100644 index 000000000..eb094baef --- /dev/null +++ b/.github/release-notes/v3.7.1.md @@ -0,0 +1,53 @@ +# RustyNES v3.7.1 — "Imprint" + +A patch release on v3.7.0 "Spindle": every file in both repositories now names its copyright holder and licence (REUSE 3.3, checked in CI), the test ROMs whose authors stated no licence are no longer called public domain, and the Android and iOS apps and the web site now carry the licence and the third-party notices the core's licences require. Each hosted match gets its own spectator id. On the MiSTer core, the FDS drive and the disk and battery saves are fixed, the battery-save fix covering a loss present in every MiSTer release so far. **Save states from v3.7.0's off-die MiSTer build are refused** (its save layout changed); the emulator's save states, movies and netplay are unchanged: the emulation epoch stays 10 and netplay protocol 10. + +## Licensing, made honest and checkable + +- **Every file names its holder and licence** ([REUSE 3.3](https://reuse.software/spec-3.3/)), in both repositories. A root `REUSE.toml` labels first-party work (`DoubleGate`, GPL-3.0-or-later) and every third-party class with the holder and licence its own evidence gives, and `LICENSES/` holds exactly the licence texts those labels use. Existing SPDX headers win; the 37 files derived from other emulators keep their upstream holders (Mesen2, TriCNES, puNES, FCEUX, Nestopia UE, emu2413, blip_buf, Lua, ares, Bisqwit), as `NOTICE` records them. A `reuse` CI job runs on every push and pull request, and an unlabelled file added to `tests/roms/`, `screenshots/`, `vendor/` or `ref-docs/` fails it. Check locally with `uvx reuse lint`. +- **The test ROMs are no longer called public domain.** The repository said blargg's suites, kevtris's nestest and the ROMs mirrored from `christopherpow/nes-test-roms` were public domain. No source supports that: the suites' readme files state no licence, the NESdev page that was cited has no licence wording, and the mirror has no LICENSE or README. The ROMs stay, labelled `LicenseRef-NoStatedLicense` with their real authors (copyright remains theirs; RustyNES grants no licence to them), and every place that made the claim now says what was checked. Other ROMs carry real licences: AccuracyCoin MIT, Holy Mapperel zlib, Brad Smith's audio tests his own permissive grant. Screenshots of commercial games are labelled as their publishers' work, not covered by the GPL. +- **The notices the apps owe.** The core contains code derived from MIT- and ISC-licensed projects, whose licences require their notices in every copy, and the GPL requires its own text with the binary. The desktop archives always carried `LICENSE` and `NOTICE`; now the Android app (About, "Open-source licenses"), the iOS app (About) and the web site (`LICENSE.txt` and `NOTICE.txt`, linked from the demo, the privacy page and every handbook page) do too, each copied from the repository at build time and checked in its build. The RetroArch core, which the libretro buildbot builds and distributes, does not yet (`T-LIBRETRO-NOTICES`, v3.8.0). +- **Two records corrected:** ares, whose colour integration the generated palette follows, is ISC-licensed, not "BSD-2-Clause / Apache-2.0" (that read the licences of components ares bundles), and its ISC notice is now in `NOTICE`; and the Bisqwit NTSC filter names its author, Joel Yliluoma. + +## Fixed + +- **Each hosted match gets its own spectator id.** With the relay match id left empty, v3.7.0 minted a random id, saved it and reused it for every later match, so anyone once given it could watch every match the host played afterwards (viewers present no key). Each hosted session now gets a fresh id, shown in the netplay panel and the status bar, and none is saved; an id v3.7.0 saved is cleared the first time this version loads its settings. **If you host from v3.7.0, the id you handed out stops working.** The saved id is recognised by its shape, 32 lowercase hex digits, so an id you typed yourself in exactly that shape is cleared too, with a note on stderr; a typed id of any other shape is kept and reused as before. +- **Spectators see a match to its end when it ends in an error.** The host sent its last, shorter batch of confirmed frames to the relay only when the player left, so a session that ended in an error dropped up to seven frames and relay viewers stopped short of the players. +- **On Android and iOS, a desync whose peer never sends its forensics is given up on after 10 seconds**, as on the desktop, instead of holding the session and its socket until the player left netplay. +- **A hidden window no longer floods the terminal** with `render error: surface unavailable: occluded` (macOS reports a minimised or covered window's surface that way), and frames it never shows are no longer staged. +- From re-reading every bot review on the pull requests closed since v3.4.1: a FIFO or device named as the palette file or as the header editor's target is refused instead of hanging the window; MMC5 save states with impossible scanline-detector values are refused; a splits file with two `game` or `category` lines is an error; the debugger no longer panics on a malformed cc65 `.dbg` or DWARF file; a `.zip` claiming a huge entry reserves at most 4 MiB up front; `cargo full-native` on Windows on ARM overrides a user's own target flags. + +## Changed + +- **New icons everywhere but Help -> About**: the icon pack's "RN" cartridge art is the window icon, `rustynes.exe`'s icon, a new `RustyNES.app` in the macOS archive, the Linux `.desktop` entry, the browser tab and installable web app, and the Android and iOS app icons. +- **Rust 1.100**, with the libretro buildbot on the same release (its Windows x64 job builds the `synchronization` import library Rust 1.100 links, which the image's MinGW lacks). +- **Every dependency at its newest compatible release**, in one change in place of four Dependabot pull requests. +- CI: the cargo cache keeps dependencies again (it had stored nothing since v1.2.0), Android CI compiles the Rust once per run instead of three times and now compile-checks the baseline-profile module, a closed pull request's caches are deleted, the PR reviewer waits out another repository's review for its shared lock, and a scheduled job deletes superseded deployments and the documentation-preview environments of deleted branches, which GitHub keeps forever (668 deployments and 37 environments had piled up). + +## The MiSTer core + +- **The FDS drive**, from v3.7.0's known issues and five review rounds, each fix pinned by a claim that failed on the earlier RTL: a side's end stops the head instead of writing into the next side's bytes, and `$4030.D6` reports the end of head, on a real image's zero fill too; a write after a read paused inside a block stores every byte (8 of 19 were dropped); a write after a motor restart waits for ready; the host port is free while the motor is stopped (a `.sav` load and a write-back both hung); a side the image lacks gives no disk, and a download too short for a side is refused. +- **Disk and battery saves.** An unsaved disk write survives a console reset before the OSD opens, and so does an unsaved battery save, which every MiSTer release so far lost that way; a later cartridge can no longer be saved into the previous one's vdisk; no save transfer starts on the clock a download begins. +- **Save states from v3.7.0's off-die build are refused**, with the reason: the save engine's layout changed (fingerprint `D4E792FE` to `6C9E7051`). The Lite build's states load. +- **Known issues, ticketed for v3.7.2** (`T-MISTER-SAVE-XFER-ACROSS-LOAD`): a battery write-back or load already under way when a new cartridge loads keeps going, and could land in the new game's `.sav` (a window of a few milliseconds after the OSD opens). Choosing its fix depends on how the MiSTer framework orders a new `.sav` mount, which only hardware can settle. Three narrower cases, outside any BIOS or game path, ride with it: a write to a side's end followed by a read without a motor restart reads the next side's bytes; an OSD save on the exact clock a mount arrives writes before the load; an FDS save abandoned by a size-0 mount may lose its unsaved flag. +- **The co-simulation ladder runs from a job pool** (`LADDER_JOBS`), giving the serial ladder's verdict for every gate in about a third of the time; and the core's tree is REUSE 3.3 compliant, its MiSTer framework files labelled from their own headers. +- **New bitstreams**, compiled from the MiSTer core's release tree at fitter seed 7 and attached here and to the [MiSTer core's v3.7.1 release](https://github.com/doublegate/RustyNES_MiSTer/releases/tag/v3.7.1): `RustyNES_MiSTer-v3.7.1.rbf` (off-die, md5 `968f18dace1266d64592f633316c6326`) and `RustyNES_MiSTer-v3.7.1-lite.rbf` (on-die, md5 `df781b3291dc7a8f1eeb3e94481f5ed8`). Seed 7 closes timing on both builds, worst of the four corners: on-die setup +0.195 ns and hold +0.117 ns, off-die +0.109 ns and +0.119 ns. **The seed sweep was partial**: seeds 1-16 were started on both builds, but on a heavily loaded host one compile took about 80 minutes, and the full sweep would have pushed the release-day compiles past midnight, where the build date (a constant in the design) changes and the sweep no longer describes the bitstream. Once seed 7 was found to close both builds, the maintainer chose to stop and pin it. Only seeds 1, 7 and 12 were measured on both builds, so seed 7 is a closing seed, not the best of sixteen. Ladders on the release RTL: off-die 428 passed, on-die 356 passed, none failed. +- **Release candidate, not hardware-verified.** No hardware has run any bitstream. + +## Verification + +- The full suite with the test ROMs and the local commercial corpus: 4,151 passed, 0 failed, 20 ignored, in 206 binaries. No golden, snapshot or epoch fingerprint moved. clippy clean for the workspace, every frontend feature set and the WebAssembly builds; `cargo deny`, the `no_std` core build and the hosted services' tests pass. `reuse lint` passes in both repositories. +- The licensing gates were each shown able to fail: an unlabelled file planted in each guarded directory fails `reuse lint`; the provenance audit, which resolves each derived file's REUSE record the way REUSE does, fails on a dropped upstream holder, a later override and a dead path; the Android test fails with the asset copy unhooked; the iOS build checks the bundle. +- MiSTer: each FDS and save fix red on the earlier RTL and caught again by a mutant; both ladders as above; the release audits pass on the bumped tree. + +## Deferred to v3.7.2 + +- The parallel coverage boot's timing run, which needs a quiet host (the cut day's seed sweep held this one), and the `test-roms` LTO A/B, which needs a CI dispatch input first. Neither changes an assertion. + +## Install + +- Download the pre-built binaries for Linux, macOS, and Windows below. The macOS archive now holds a `RustyNES.app`, signed ad hoc but not notarized: allow it once in System Settings > Privacy & Security, or run `xattr -dr com.apple.quarantine RustyNES.app`. +- The MiSTer bitstreams, a release candidate and not hardware-verified, are attached below: copy `RustyNES_MiSTer-v3.7.1.rbf` (off-die, needs the SDRAM add-on) or `RustyNES_MiSTer-v3.7.1-lite.rbf` (on-die) to the MiSTer's `_Console` folder. +- The WebAssembly build is live at [doublegate.github.io/RustyNES](https://doublegate.github.io/RustyNES/). +- The RetroArch core is in RetroArch's Online Updater on the platforms the libretro buildbot publishes to. +- Licensed under GPL-3.0-or-later; the third-party notices are in `NOTICE`. diff --git a/.github/workflows/preview-env-cleanup.yml b/.github/workflows/preview-env-cleanup.yml new file mode 100644 index 000000000..884655b31 --- /dev/null +++ b/.github/workflows/preview-env-cleanup.yml @@ -0,0 +1,113 @@ +# Delete what preview deployments leave behind (2026-11-15). +# +# The Docs7 GitHub App deploys every pull request's branch to an environment +# named "Docs7 Preview: ", and GitHub Pages and the Copilot agent add +# deployments of their own. GitHub never deletes an environment or a +# deployment: a superseded deployment is only marked inactive, and an +# environment, created the first time a deployment names it, stays forever. By +# 2026-11-15 this repository held 668 deployments and 37 environments, 33 of +# them previews of branches long merged and deleted. +# +# Two jobs, because they need different credentials: +# +# - `deployments` deletes every INACTIVE deployment except the newest one of each +# environment that still exists, plus every deployment whose environment is +# gone. It keeps each environment's newest SUCCESS deployment as well (the +# live one, while a newer one is in flight or after it failed) and never +# touches one in a transient state. It needs `deployments: write`, which +# GITHUB_TOKEN has. +# - `environments` deletes a "Docs7 Preview: " environment once +# no longer exists and no open pull request has it as its head, and nothing +# else. Deleting an environment needs the repository's Administration +# permission (write), which GITHUB_TOKEN cannot be granted, so it uses +# ENV_CLEANUP_TOKEN: a fine-grained personal access token scoped to this +# repository with Administration: read and write. Without it the job says so +# and changes nothing. +# +# WHERE THE TOKEN LIVES. ENV_CLEANUP_TOKEN is a secret of the `preview-cleanup` +# ENVIRONMENT, not a repository secret, and that environment's deployment branch +# policy allows the default branch only. Then GitHub itself withholds the token +# from a run on any other ref -- a branch whose copy of this file was edited and +# dispatched by hand included -- whatever that copy says. The `if:` on each job +# skips a run on another ref as well, before it starts. (Security review, +# 2026-11-15: workflow_dispatch can run any branch's version of a workflow.) The +# environment adds one deployment per run; the `deployments` job deletes all but +# its newest. +# +# Every trigger runs this workflow as it is on the DEFAULT branch -- a branch +# deletion, the schedule and a dispatch all do -- so no pull request's code ever +# runs with the token. There is deliberately no `pull_request` trigger. +name: Preview environment cleanup + +on: + # A merged pull request's branch is deleted, which is when its preview goes + # stale. + delete: + schedule: + - cron: "17 6 * * *" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: preview-env-cleanup + cancel-in-progress: false + +jobs: + deployments: + name: Delete inactive deployments + # 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. `!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: >- + !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 + timeout-minutes: 30 + 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: + persist-credentials: false + - name: Delete inactive deployments + env: + GH_TOKEN: ${{ github.token }} + run: scripts/ci/prune-deployments.sh "$GITHUB_REPOSITORY" --apply + + environments: + name: Delete stale preview environments + if: >- + github.ref == format('refs/heads/{0}', github.event.repository.default_branch) + && (github.event_name != 'delete' || github.event.ref_type == 'branch') + # The token is this environment's secret; its branch policy is main only. + environment: preview-cleanup + runs-on: ubuntu-26.04 + timeout-minutes: 15 + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + - name: Delete stale preview environments + env: + GH_TOKEN: ${{ secrets.ENV_CLEANUP_TOKEN }} + run: | + if [ -z "$GH_TOKEN" ]; then + msg="ENV_CLEANUP_TOKEN is not set in the preview-cleanup environment: no environment was deleted. Add a fine-grained token scoped to this repository with Administration: read and write as that environment's secret, with the environment limited to the default branch (see this workflow's header)." + echo "::warning::$msg" + echo "$msg" >> "$GITHUB_STEP_SUMMARY" + exit 0 + fi + scripts/ci/prune-preview-environments.sh "$GITHUB_REPOSITORY" --apply diff --git a/.gitignore b/.gitignore index 177da142f..93c7e3a04 100644 --- a/.gitignore +++ b/.gitignore @@ -1,82 +1,56 @@ # ============================================================================= # .gitignore — RustyNES -# (negations `!` must follow the broad rule they re-include — order matters) +# +# ORDER MATTERS: a `!` negation re-includes only what the rules ABOVE it +# ignored, and a later rule ignores again. Keep a new rule on the correct side +# of the negations it interacts with (the golden, coverage and nestest +# re-includes below). +# +# A bare pattern (no `/` except a trailing one) matches at ANY depth. Before +# adding one, check it against the tree: `git ls-files -ci --exclude-standard` +# lists the tracked files an ignore rule would hide. # ============================================================================= # --- Rust / Cargo --- /target/ -/target/doc/ -/target/criterion/ -# Nested per-crate target/ dirs (build output; the root /target/ rule is anchored). +# Nested per-crate target/ dirs (the root /target/ rule is anchored). crates/*/target/ **/*.rs.bk *.bench -# This workspace ships a binary app — commit the lock (re-include it). -# -# `Cargo.lock` with no slash matches at ANY depth, so the re-include below has -# to name every lockfile we keep. That was written when there was exactly one. -# `crates/rustynes-cosim` is EXCLUDED from the workspace, so it resolves its own -# dependency graph into its own lockfile — which this rule was silently -# ignoring, leaving CI to re-resolve it on every run. That crate emits the -# goldens an external NES implementation is verified against, and its manifest -# records the emulator version, not the resolve, so a dependency moving under it -# would be invisible in exactly the artifact meant to establish provenance. +# Track the lockfiles of the binary workspace and of `crates/rustynes-cosim`, +# which is excluded from the workspace and resolves its own graph. The cosim +# crate emits the goldens an external NES implementation is verified against, +# so its resolve is provenance and must not move unrecorded (v2.4.2). The bare +# `Cargo.lock` matches at any depth: name every lockfile that is kept. Cargo.lock !/Cargo.lock !/crates/rustynes-cosim/Cargo.lock -# Golden-export output. `nes_golden_export` writes these wherever `--out` points, -# and none of them belong in the tree: they are reproducible from a pinned -# commit, and a committed copy is a copy that drifts. -# -# The re-include below is not decoration. A BARE pattern matches at any depth, -# which is exactly how `Cargo.lock` silently ignored the excluded crate's -# lockfile until v2.4.2 -- so the committed golden trees are named explicitly, -# and a binary golden deliberately added there will not be swallowed. +# --- Golden-export output --- +# `nes_golden_export` and the sibling's gates write these wherever `--out` +# points. They are reproducible from a pinned commit, so none belong in the +# tree. When a co-simulation rung adds a format, add its suffix here (the list +# fell behind four times); check with +# for s in ckpt obs boot index_fb ram ram_init fetch apu dut; do +# git check-ignore -q "x.$s.bin" || echo "NOT IGNORED: $s"; done +# `*.ram.bin` does not match `.ram_init.bin`; both are needed. *.ckpt.bin *.obs.bin *.boot.bin *.index_fb.bin *.ram.bin -# Three artifacts this list had grown apart from, found by testing each suffix -# against `git check-ignore` rather than by reading the list. `*.ram.bin` does -# NOT match `.ram_init.bin` -- the suffixes differ -- so the seeded work -# RAM every gate now requires was never covered; `irq.csv` has been uncovered -# since v2.4.2; `fetch.bin` arrived with v2.5.4. Each was verified to match -# nothing tracked before being added. *.ram_init.bin *.fetch.bin *.irq.csv -# A FIFTH, found the same way in v2.6.5. The sibling's `cpu-bus-gate` writes -# `.dut.bin` -- the DUT's own capture, compared against `.obs.bin` -- -# and its output path is a variable, so a run pointed at this tree offers a file -# this list did not name. A 134 M-cycle window is 2.0 GB. Verified to match -# nothing tracked before being added. *.dut.bin -# A FOURTH, found the same way and for the same reason: `apu.bin` arrived with -# rung 4 (the 2A03's per-cycle channel levels) at v2.5.9 and was never added, so -# every APU golden the sibling's gates consume has been offered for commit since. -# Verified to match nothing tracked before being added. -# -# The pattern here is now four for four: this list grows when a rung adds a -# format, and nothing makes it. Checking is one line -- -# for s in ckpt obs boot index_fb ram ram_init fetch apu; do -# git check-ignore -q "x.$s.bin" || echo "NOT IGNORED: $s"; done -# -- and reading the list instead is what missed the previous three. *.apu.bin -# Broader than its siblings, and knowingly so: `nes_golden_export` names this -# `.manifest.txt`, with no suffix that distinguishes it from any other -# manifest. Nothing tracked matches it today. If a manifest ever needs tracking, -# re-include it explicitly rather than narrowing this -- a bare pattern matching -# at any depth is what the note above is about. +# Deliberately broad: the exporter names it `.manifest.txt`. If a +# manifest ever needs tracking, re-include it explicitly. *.manifest.txt +# The committed golden trees, named so a golden added there is not swallowed. !/golden/** !/crates/rustynes-test-harness/golden/** -# (The vendored TriCNES harness used to be BUILT in place under golden/, and two -# negations here kept its bin/ + obj/ out. It left the repository in v3.0.1, so -# they went with it.) - # --- Native build & FFI artifacts --- *.so *.dylib @@ -85,12 +59,9 @@ Cargo.lock *.a *.lib *.pdb -# Apple debug symbols. The libretro Apple jobs (osx / ios / tvos) and the iOS -# xcframework build emit `.dylib.dSYM` bundles next to the library, and -# the buildbot additionally zips them for upload — `*.dylib` above covers the -# library but neither the bundle directory nor the archive. Building any Apple -# libretro target locally (`crates/rustynes-libretro/Makefile`) leaves both in -# the working tree. +# Apple debug symbols: the libretro Apple jobs and the iOS xcframework build +# leave `.dylib.dSYM` bundles (and the buildbot's zip of them) beside the +# library. *.dSYM/ *.dSYM.zip @@ -99,34 +70,30 @@ Cargo.lock /dist/ *.wasm wasm-pack.log -# trunk build output (regenerated by `trunk build`; never committed). /crates/rustynes-frontend/web/dist/ -# v1.5.0 Workstream G — the Emscripten rcheevos→wasm side module -# (`scripts/cheevos/build_rcheevos_wasm.sh` output). The `.wasm` (above) + -# `.js` glue are build artifacts: rebuild on demand, never commit. The hand- -# written loader (`ra_glue.js`) + the dir's README ARE committed. +# The Emscripten rcheevos side module's JS glue +# (`scripts/cheevos/build_rcheevos_wasm.sh`); the hand-written `ra_glue.js` and +# the directory's README are tracked. /crates/rustynes-frontend/web/cheevos/rcheevos.js -# --- Node.js (web frontend) --- +# --- Node.js --- node_modules/ package-lock.json -# v3.4.0 — the hosted services (`services/hosted/`) are deployed from CI-tested -# code, so their lockfile IS committed: `npm ci` must reproduce the exact -# dependency tree the tests ran against (the same reasoning as `Cargo.lock`). +yarn.lock +pnpm-lock.yaml +# The hosted services are deployed from CI-tested code, so `npm ci` must +# reproduce the tree the tests ran against: their lockfile is tracked. !/services/hosted/package-lock.json -# wrangler's local dev state (miniflare storage, temp bundles), and local -# secrets for `wrangler dev` (never committed). +# wrangler's local dev state and `wrangler dev` secrets. /services/hosted/.wrangler/ /services/hosted/.dev.vars -yarn.lock -pnpm-lock.yaml -# --- Python (helper scripts under scripts/, icon generator under assets/) --- +# --- Python --- __pycache__/ *.pyc .venv/ venv/ -# Icon generator default output dir (regenerated by make_icon.py). +# Icon generator default output (make_icon.py). /assets/RustyNES_Icon/out/ # --- Platform packages --- @@ -135,15 +102,13 @@ venv/ *.flatpak *.msi *.appx -# insta reference snapshots also end in `.snap`; the ROM suites compare against -# these committed fixtures, so re-include them (overrides the Snapcraft `*.snap`). +# insta's committed reference snapshots also end in `.snap`: re-include them +# (`/**/` also matches zero directories). Pending or rejected ones +# (`.snap.new`) are accepted or deleted, never committed. !**/snapshots/**/*.snap -!**/snapshots/*.snap -# ...but insta's pending/rejected snapshots (`.snap.new`) are transient — accept -# them into `.snap` (`cargo insta accept`) or delete; never commit. *.snap.new -# --- Fuzzing (commit the harnesses; ignore the build/corpus) --- +# --- Fuzzing (commit the harnesses; ignore the build and corpus) --- fuzz/ !/fuzz/ /fuzz/target/ @@ -153,39 +118,33 @@ fuzz/ corpus/ artifacts/ -# --- ROMs & media (copyright) --- -# The broad `*.nes`/`*.fds` rules ignore ALL ROMs; re-include the committable -# test-ROM suites under tests/roms/ (licences per file in REUSE.toml and -# tests/roms/LICENSES.md), then HARD-exclude the commercial -# dumps + the large fetched clone (NEVER committed — Nintendo copyright). +# --- ROMs, disks, music, patches (copyright) --- +# All ROMs are ignored; the committable test-ROM suites under tests/roms/ are +# re-included (licences per file in REUSE.toml and tests/roms/LICENSES.md). +# Commercial dumps, BestEffort boot-smoke ROMs included, live under +# tests/roms/external/ and are NEVER committed. *.nes *.fds !/tests/roms/**/*.nes -/tests/roms/external/ -# The same path as a SYMLINK (how a git worktree points at the main tree's -# dumps): a pattern ending in `/` matches only a directory, so the link showed -# as untracked in every agent worktree and could be staged by accident (v2.9.8). +# No trailing slash: a git worktree reaches the main tree's dumps through a +# SYMLINK at this path, which a `dir/` pattern does not match (v2.9.8). /tests/roms/external /tests/roms/nes-test-roms/ /game-roms/ - -# coverage tool's cached library-header scan (developer-local; ~25k headers) -/scripts/coverage/.library-index.json *.qd *.nsf *.nsfe *.nsf2 -# User-supplied palette files (v1.1.0 .pal loading) — none committed +# User-supplied palettes; none are committed. *.pal -# ROM soft-patches (v1.2.0 ingest: auto-applied .ips/.ups/.bps beside a ROM). -# User-supplied, copyright-adjacent — never committed (mirrors the ROM policy). +# ROM soft-patches (auto-applied beside a ROM) and the live-patch recorder's +# RAM-pin sidecar: user material, handled like the ROMs. *.ips *.ups *.bps -# v3.7.0 live-patch recorder: the RAM-pin sidecar written beside a .bps. *.pins.toml -# --- TAS movie files (may contain copyrighted content) --- +# --- TAS movies (may contain copyrighted content) --- *.rnm *.rnmproj *.rnmb @@ -194,21 +153,20 @@ artifacts/ *.bk2 *.tasproj -# --- Save / state / input / dumps / cheats --- +# --- Saves, states, input recordings, dumps, cheats --- *.rns *.sav *.srm *.state *.savestate *.snapshot -*.quick*.state *.rec *.input *.ram *.dump *.cht -# --- Game database files --- +# --- Game databases --- *.db *.sqlite *.sqlite-journal @@ -217,28 +175,27 @@ artifacts/ *.dat *.xml !assets/**/*.xml -# v1.2.0 in-app ROM-Database editor writes a user overlay to the OS data dir; -# ignore a stray copy if the app is ever run from the repo root. +# The ROM-Database editor's user overlay, if the app is run from the repo root. game_db_user.txt +# The NES 2.0 DB the Game Genie re-key reads at build time. +scripts/gg/nes20db.xml # --- Logs / debug / test output --- *.log -# Keep the kevtris nestest golden trace despite the broad *.log ignore. +# The kevtris nestest golden trace is tracked despite `*.log`. !/tests/roms/nestest/nestest.log -*.test.log *.golden test-output/ /tests/captures/ /tests/framework/enhanced-validator/target/ -/tests/framework/*.exe /tests/framework/test_rom_validator # --- Coverage / profiling --- *.gcno *.gcda coverage/ -# ...but NOT the committed coverage tooling (the `coverage/` rule above is for -# code-coverage artifact dirs; the cache JSON stays ignored via its rule above). +# `coverage/` is for coverage-artifact dirs, not the committed tooling; the +# tooling's library-header cache and bytecode stay ignored. !/scripts/coverage/ !/scripts/coverage/** /scripts/coverage/.library-index.json @@ -248,54 +205,50 @@ perf.data perf.data.old flamegraph.svg /perf-logs/ -# PGO / profile-guided-optimization artifacts (v1.2.0 pgo.yml + scripts/pgo/). -# The instrument/train profiles are regenerated by the recipe; never committed. +# PGO profiles (pgo.yml, scripts/pgo/), regenerated by the recipe. *.profraw *.profdata /pgo-data/ -/target/pgo/ -# --- Documentation (build output + local-only references) --- +# --- Documentation build output and local-only references --- /docs/_site/ -# Engine-development audit history (the C1 IRQ saga, DMA investigations, the -# v2.0 promotion logs, ...) — kept locally, NOT in the public repo. The v1.0.0 -# synthesis handoff lives at docs/v1.0.0-synthesis-handoff-*.md instead. +# MkDocs Material's social-card and privacy plugin cache (`mkdocs build`). +/.cache/ +# Engine-development audit history, kept locally, not in the public repo. /docs/audit/ -# Large local NESdev wiki mirror (~208M, reference only). +# The local NESdev wiki mirror (~208 MB, reference only). /nesdev_wiki/ +# Third-party Alliance Memory SDRAM datasheets, marked "Confidential": kept on +# disk only, never redistributed (ref-docs/2026-11-15-sdram-datasheet-sources.md). +/ref-docs/Datasheets/*.pdf -# --- Reference projects (external cloned repos) — REFERENCE FIREWALL --- +# --- REFERENCE FIREWALL --- # ref-proj/ held local clones of reference emulators used ONLY as black-box -# behavioral oracles. Their licenses are project-specific: Mesen2, puNES, FCEUX, -# and GeraNES are copyleft (GPL), and reproducing that source makes RustyNES a -# derivative work (which it now is, GPL-3.0-or-later); TriCNES is MIT. The -# directory has been REMOVED from disk and stays ignored here as a firewall guard -# so the copyleft source can never re-enter the working tree. Do NOT re-clone -# reference-emulator source into the repo; implement hardware behavior from -# docs/test ROMs. (The MIT TriCNES source was vendored until v3.0.1 and now lives -# outside the repository at ~/reference-oracles/; guardrails section 3a.) See -# docs/ai-emulator-provenance-guardrails.md and the "MOST IMPORTANT RULE" of AGENTS.md. +# behavioural oracles. Mesen2, puNES, FCEUX and GeraNES are GPL; reproducing +# their source is what made RustyNES a derivative work (now GPL-3.0-or-later). +# The directory was REMOVED from disk and stays ignored as a guard so that +# source can never re-enter the working tree. Do NOT re-clone reference-emulator +# source into the repo; implement hardware behaviour from docs and test ROMs. +# (TriCNES, MIT, lives outside the repository at ~/reference-oracles/; +# guardrails section 3a.) See docs/ai-emulator-provenance-guardrails.md and the +# "MOST IMPORTANT RULE" of AGENTS.md. /ref-proj/ -# --- Temporary files --- +# --- Temporary, merge and backup files --- /tmp/ /temp/ *.tmp - -# --- Merge / patch artifacts (git conflict + `git apply --reject` leftovers) --- +# git conflict and `git apply --reject` leftovers. *.orig *.rej -# Pre-edit backups. The workspace rules have an agent copy a file aside before -# instrumenting it (`cp file file.bak`, `.preedit`) so cleanup restores -# its own snapshot rather than a `git checkout` over uncommitted work. Those -# copies are never commit material. Checked in v2.9.6: nothing tracked matches. +# Pre-edit snapshots (`cp file file.bak`, `.preedit`) an agent takes +# before instrumenting a file. *.bak *.preedit -# insta's pending inline-snapshot file (the `.snap.new` rule below covers the -# file-snapshot equivalent). +# insta's pending inline-snapshot file. *.pending-snap -# --- Environment --- +# --- Environment / secrets --- .env .env.local @@ -313,40 +266,30 @@ flamegraph.svg Thumbs.db Desktop.ini -# --- Android (v1.8.0) --- -# The android/ Gradle module has its own .gitignore (build/, .gradle/, jniLibs/, -# keystore.properties, local.properties, the wrapper jar); these belt-and-suspenders -# rules cover the same outputs if a tool scans from the repo root. The committed -# Gradle wrapper (gradlew[.bat] + gradle-wrapper.jar) and keystore.properties.example -# are intentionally tracked. +# --- Android --- +# android/ has its own .gitignore; these cover the same outputs for a tool +# scanning from the root. The Gradle wrapper and keystore.properties.example +# are tracked. android/**/build/ **/.gradle/ android/local.properties -# Release upload-signing secrets (v2.0.4 signing config: `rootProject.file( -# "keystore.properties")` or the `RUSTYNES_UPLOAD_*` env vars). Ignore the props -# file anywhere, plus any keystore blob — a maintainer secret, NEVER committed. -# The tracked `keystore.properties.example` template is intentionally kept. +android/app/src/main/jniLibs/ +# Upload-signing secrets: the properties file at any depth, and any keystore. keystore.properties -android/keystore.properties *.jks *.keystore -android/app/src/main/jniLibs/ -# --- iOS (v1.9.0 "Sunrise") --- -# The xcframework + the UniFFI-generated Swift surface + the XcodeGen-generated -# Xcode project are all BUILD ARTIFACTS (regenerated by -# scripts/build-ios-xcframework.sh); never committed. The hand-written SwiftUI -# sources, project.yml, Info.plist, entitlements, PrivacyInfo, the bridging -# header, and ios/Generated/.gitkeep ARE tracked. +# --- iOS --- +# The xcframework, the UniFFI-generated Swift and the XcodeGen project are +# build artifacts (scripts/build-ios-xcframework.sh). The SwiftUI sources, +# project.yml, Info.plist, entitlements, PrivacyInfo, the bridging header and +# ios/Generated/.gitkeep are tracked. ios/RustyNESFFI.xcframework/ ios/Generated/RustyNESCore.swift ios/RustyNES.xcodeproj/ ios/build/ *.ipa -# fastlane local output (the generated docs + the last-run report). The Play -# Console listing under `fastlane/metadata/` (v2.0.4 — title / descriptions / -# changelogs, en-US + es-ES) is version-controlled source and IS tracked; only the -# generated report / README / test output below are ignored. +# fastlane output; the store listing under fastlane/metadata/ is tracked. fastlane/report.xml fastlane/README.md fastlane/test_output/ @@ -354,58 +297,18 @@ fastlane/test_output/ # --- Pre-commit --- .pre-commit-cache/ -# --- AI assistant local files --- +# --- AI assistants and agent scratch --- CLAUDE.local.md /.claude/ +.agents/ WARP.md /.warp/ - -# Local scratch / salvage working dir (data/docs/logs pulled from /tmp triage); not -# part of the repo. -/salvaged/ -# v3.2.0: an AI agent's /tmp-salvage scratch from the agy/Codex remediation -# branch (session transcripts, a /tmp listing, the author's address). Kept in the -# gitignored salvaged/ above; it must never be committed under this name either. -/salvaged_tmp/ - -# NOTE: BestEffort boot-smoke ROMs (homebrew/unlicensed/multicart) are no longer -# a separate tree — they live under the already-ignored tests/roms/external/ -# alongside every other staged dump (the coverage harness discovers ONE external/ -# ROM tree; only the *screenshots* are tier-split, into screenshots/besteffort/). - -# --- Wiki (Separate Repo) --- -# RustyNES.wiki/ is a standalone clone of the GitHub Wiki repo -# (github.com/doublegate/RustyNES.wiki.git) checked out inside this tree to -# author/build the wiki; it carries its own .git and must never be committed -# into the main repository. -/RustyNES.wiki/ - -# Game Genie header-robust re-key: NES 2.0 DB is a build-time input, never committed -scripts/gg/nes20db.xml -scripts/gg/__pycache__/ - -# Antigravity PR reviewer: scratch workspace for the on-disk diff handoff. When a PR's -# diff is too large to inline in the prompt, scripts/agy-review.sh writes it here so agy -# can READ it with its file tools instead of the review being truncated to the argv -# ceiling. Created and removed within a single run; never committed. +# The Antigravity PR reviewer's on-disk diff handoff (scripts/agy-review.sh), +# created and removed within one run. /.agy-review-work/ - -# AccuracyCoin sub-test ROM builds. `scripts/accuracycoin-build/build_sub_test_rom.py` -# defaults its scratch to /tmp, but `--build-dir` can point in-tree, and the nesasm -# toolchain drops listing/symbol sidecars beside whatever it assembles. The ROMs it -# produces under tests/roms/AccuracyCoin/sub-tests/ ARE committed (with their -# BUILD-PROVENANCE.tsv); the intermediates never are. -/accuracycoin-build/ -tests/roms/**/*.lst -tests/roms/**/*.fns -tests/roms/**/*.nl -.agents/ - -# Agent review scratch in the repo root: PR-thread dumps and one-shot patch scripts -# an agent writes while working a review round (`cr_*`, `fix_*.py`, `*_comments.json`, -# `threads.json`, `pr_*.txt`). Thirteen of them sat untracked after #544, one -# `git add -A` from landing in history. Root-anchored so nothing under `scripts/` or -# `crates/` can match. +# Review-round scratch an agent writes in the root: PR-thread dumps and one-shot +# patch scripts (thirteen sat untracked after #544). Root-anchored so nothing +# under scripts/ or crates/ matches. /cr_*.json /cr_*.txt /fix_*.py @@ -413,10 +316,20 @@ tests/roms/**/*.nl /threads.json /unresolved_threads.txt /pr_*.txt +# Local salvage of /tmp scratch, never part of the repo under either name +# (salvaged_tmp/ held session transcripts and the author's address, v3.2.0). +/salvaged/ +/salvaged_tmp/ -# MkDocs Material's social-card and privacy plugins write their download/render -# cache here on every local `mkdocs build` (web.yml builds the handbook in CI). -/.cache/ +# --- Wiki (separate repository) --- +# A clone of github.com/doublegate/RustyNES.wiki.git, with its own .git. +/RustyNES.wiki/ -# Third-party Alliance Memory SDRAM datasheets, marked "Confidential": kept on disk only, never redistributed (see ref-docs/2026-11-15-sdram-datasheet-sources.md). -/ref-docs/Datasheets/*.pdf +# --- AccuracyCoin sub-test ROM builds --- +# The built ROMs under tests/roms/AccuracyCoin/sub-tests/ are tracked (with +# BUILD-PROVENANCE.tsv); an in-tree `--build-dir` and the nesasm listing and +# symbol sidecars are not. +/accuracycoin-build/ +tests/roms/**/*.lst +tests/roms/**/*.fns +tests/roms/**/*.nl diff --git a/AGENTS.md b/AGENTS.md index 506276c64..ac02b5949 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,7 +41,7 @@ Enforcement lives alongside the prose: `/ref-proj/` is gitignored/`.dockerignore RustyNES is a cycle-accurate Nintendo Entertainment System emulator written in pure Rust. The accuracy bar is Mesen2 / higan / ares: tight lockstep scheduling at PPU-dot resolution on a master-clock-precise timebase, sub-instruction PPU events visible to subsequent CPU code, and a lookup-table non-linear audio mixer with band-limited synthesis. The frontend is pure Rust (`winit` + `wgpu` + `cpal` + `egui`). -**Current release: v3.7.0 "Spindle"** (2026-11-10). **No hardware has run any MiSTer bitstream** (ADR 0043). What each release added, and the full release-line chain back to v3.0.0, are in `docs/agents/release-line.md`; suite counts, the mapper matrix and per-release detail live in `docs/STATUS.md`, `CHANGELOG.md` and the GitHub releases. +**Current release: v3.7.1 "Imprint"** (2026-11-15). **No hardware has run any MiSTer bitstream** (ADR 0043). What each release added, and the full release-line chain back to v3.0.0, are in `docs/agents/release-line.md`; suite counts, the mapper matrix and per-release detail live in `docs/STATUS.md`, `CHANGELOG.md` and the GitHub releases. Platform builds (Android sideload, iOS TestFlight, the libretro core), the 208-family mapper breadth and release automation: `docs/agents/release-line.md`. @@ -191,7 +191,7 @@ that is a reason to add a new topic file — not a reason to grow this section b - `ref-docs/` is immutable. Research updates go in dated supplemental files. - ADRs go in `docs/adr/` (Michael Nygard format). - `rustynes-core` re-exports the public types from the chip crates; downstream consumers (`rustynes-frontend`, `rustynes-test-harness`) should depend on `rustynes-core` rather than the chip crates directly. -- Engine-lineage "v2.x" narrative is upstream history, never a current RustyNES release version. The current release is **v3.7.0 "Spindle"** (2026-11-10). **Never claim any version *later* than v3.7.0 is released.** The two distinct "v2.0"s are explained in `docs/agents/release-line.md`. +- Engine-lineage "v2.x" narrative is upstream history, never a current RustyNES release version. The current release is **v3.7.1 "Imprint"** (2026-11-15). **Never claim any version *later* than v3.7.1 is released.** The two distinct "v2.0"s are explained in `docs/agents/release-line.md`. - `to-dos/ROADMAP.md` is the planning entry point (detail: `docs/agents/conventions.md`). - The v1.0.0 release + GitHub Pages/CI + post-release record is in `docs/v1.0.0-synthesis-handoff-2026-06-13.md` — read it before touching CI, Pages, or release tooling. Full per-release history is in `CHANGELOG.md`. - **Markdownlint is a CI gate** (pinned `markdownlint-cli v0.50.0`): verify with `pre-commit run markdownlint --all-files`, and never lint or reformat the `.markdownlintignore` trees (the whitespace hooks still cover our own frozen trees, `docs/archive/` and `to-dos/plans/`, by design: `.pre-commit-config.yaml`). Keep the RetroAchievements User-Agent's leading `RustyNES/` token (`RA_USER_AGENT`, regression-tested). Detail: `docs/agents/conventions.md`. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 00a14bfce..a12a57940 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -2,7 +2,7 @@ **Document Version:** 2.1.0 **Last Updated:** 2026-10-07 -**Applies to:** RustyNES v3.7.0 (the scheduling model is v2.0.0 "Timebase" onward) +**Applies to:** RustyNES v3.7.1 (the scheduling model is v2.0.0 "Timebase" onward) This document fixes the high-level architecture of RustyNES. The per-subsystem specs under `docs/` (`cpu-6502.md`, `ppu-2c02.md`, `apu-2a03.md`, `mappers.md`, `scheduler.md`) take these decisions as given and elaborate one chip each. After reading this you should know the workspace shape, the scheduling model, the public boundary, and the load-bearing invariants. The canonical, always-current architecture spec is [`docs/architecture.md`](docs/architecture.md); this file is the top-level companion. diff --git a/CHANGELOG.md b/CHANGELOG.md index eb4a25563..622f07ff6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,7 @@ # Changelog -This is the concise, readable summary of notable changes to RustyNES — a few -tight highlights per release, and **the complete list of releases**. The format -is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and the +This is the record of notable, user-visible changes to RustyNES, newest first, +and **the complete list of releases**. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). **Where the deep per-release detail lives, stated accurately.** @@ -26,6 +25,8 @@ cycle-accurate core later replaced. ## [Unreleased] +## [3.7.1] - 2026-11-15 - "Imprint" (every file labelled with its holder and licence, the notices the apps owe, the MiSTer core's FDS and battery-save fixes, and a fresh spectator id per hosted match) + ### Changed - **The Android and iOS apps and the web site carry the licence and the @@ -59,7 +60,6 @@ cycle-accurate core later replaced. are no longer tracked; `ref-docs/2026-11-15-sdram-datasheet-sources.md` gives their public download locations. The iOS store copyright line no longer says "MIT OR Apache-2.0". - - **Rust 1.100.0** (from 1.99.1), with the libretro buildbot on the same release (`.gitlab-ci.yml`), the workspace `rust-version`, the two standalone manifests, the Worker image's base and the comments that name @@ -75,6 +75,30 @@ cycle-accurate core later replaced. image's MinGW does not ship, so its Windows x64 job now builds that import library (three functions from `api-ms-win-core-synch-l1-2-0.dll`) with `dlltool` before the build. +- **Preview deployments and their environments no longer pile up** + (`.github/workflows/preview-env-cleanup.yml`). The Docs7 documentation + previews deploy each pull request's branch to an environment named + `Docs7 Preview: `; GitHub never deletes an environment and only marks + a superseded deployment inactive, so by 2026-11-15 the repository held 668 + deployments and 37 environments, 33 of them previews of long-merged branches. + Those 33 environments and 665 superseded deployments were deleted (the newest + deployment of each live environment kept: the Pages site, Docs7 Production, + the open release branch's preview). On every branch deletion, daily and on + demand, `scripts/ci/prune-deployments.sh` now deletes every deployment but + the newest and the newest successful one of each environment that still + exists (the live one while a newer deployment is in flight or failed), never + one still running, failing closed if any listing fails; an environment that + has been deleted keeps none of its deployments. It reads them through + GraphQL and deletes them in batches of 50 mutations (300 in 31 seconds, + against about five minutes for the first 360 at one REST call at a time), + and `scripts/ci/prune-preview-environments.sh` deletes a preview environment once + its branch is gone and no open pull request uses it. Deleting an environment + needs the Administration permission, which the workflow's own token cannot + have, so that job needs an `ENV_CLEANUP_TOKEN` secret (a fine-grained token + for this repository with Administration: read and write), kept in a + `preview-cleanup` environment whose deployment branches are limited to + `main`, so GitHub withholds it from any other branch's copy of the + workflow; it says so in its run summary until the secret exists. - **A pull request's CI caches are deleted when it closes** (`.github/workflows/cache-cleanup.yml`). They could never be restored again, but counted against the repository's 10 GB cache limit until @@ -137,8 +161,9 @@ cycle-accurate core later replaced. services: wrangler 4.160.1, the Workers vitest plugin 1.8.0 and current Workers types; CI tests them on Node 26, now the active LTS. The RA proxy image moves to Python 3.15. CI: taiki-e/install-action 2.90.3; the ruff - pre-commit hook 0.17.4. The Rust toolchain stays at 1.99.1, still the - newest stable release, and nothing user-visible changes in emulation: + pre-commit hook 0.17.4. This sweep left the Rust toolchain at 1.99.1, then + the newest stable release (the move to 1.100.0 is the entry above), and + nothing user-visible changes in emulation: the full suite with the commercial corpus passes with no golden, snapshot or frame moved, so the emulation epoch stays 10. - **CI (contributors): the cargo cache keeps dependencies again.** It had @@ -223,6 +248,47 @@ moves a frame, a sample or a bus cycle, so the emulation epoch stays 10. answers. The forensics report now says the peer sent no state, and the session is released. +### The MiSTer core (`RustyNES_MiSTer`) + +- **The FDS drive, from the v3.7.0 known issues and five review rounds.** A + side's end stops the head instead of writing into the next side, and + `$4030.D6` reports the end of head, on a real image's zero fill too; a write + after a read paused inside a block stores every byte (8 of 19 were dropped); + a write after a motor restart waits for ready; the host port is free while + the motor is stopped (a `.sav` load and a write-back both hung); a side the + image lacks gives no disk, and a download too short for a side is refused. +- **Disk and battery saves.** An unsaved disk write or battery save survives a + console reset before the OSD opens (the battery case lost saves in every + MiSTer release so far); a later cartridge can no longer be saved into the + previous one's vdisk; no save transfer starts on the clock a download begins. +- **Save states from v3.7.0's off-die build are refused**: the save engine's + layout changed (fingerprint `D4E792FE` to `6C9E7051`). The Lite build's + fingerprint is unchanged. +- **Known issues** (`T-MISTER-SAVE-XFER-ACROSS-LOAD`, v3.7.2): + - A battery write-back or load already under way when a new cartridge loads + keeps going. Its remaining blocks can be written into the NEW game's `.sav`, + and a load can write the old game's save into the new game's running + PRG-RAM. The window is the few milliseconds a transfer takes after the OSD + opens; to stay clear of it, wait a moment after closing the OSD before + loading another game. + - An OSD save requested on the exact clock a `.sav` mount arrives writes the + old RAM into the newly mounted file before loading it. + - Two FDS cases outside any BIOS or game path: a write to a side's end then a + read without a motor restart reads the next side's bytes; an FDS save + abandoned by a size-0 mount may lose its unsaved flag, so those writes are + not saved. +- New bitstreams for both builds, a release candidate: no hardware has run + any MiSTer bitstream. + +### Notes + +- **Deferred to v3.7.2:** the parallel coverage boot's timing measurement + (`T-TEST-COVERAGE-PARALLEL`; the code shipped in v3.7.0's follow-up, only + the quiet-host timing run is outstanding, and the cut day's seed sweep + held the host) and the `test-roms` LTO A/B (`T-CI-TESTROMS-LTO`; CI needs + a dispatch input for the profile override first). Neither changes an + assertion. + ## [3.7.0] - 2026-11-10 - "Spindle" (the Famicom Disk System on the MiSTer core, spectators through the hosted relay, desync forensics and live ROM patching) ### Breaking @@ -1663,6 +1729,11 @@ bitstreams are unchanged. 512 KiB), but nothing ever reset the flag, so after the first change the comparison ran every second again. A failed write is still retried. +- **New MiSTer bitstreams at fitter seed 7**, on-die and off-die, each + compiled twice to the same bytes: a release candidate, not + hardware-verified. The co-simulation ladder reads 260 passed, 0 failed, 3 + expected failures on-die and 263 / 0 / 3 off-die (detail, md5s and timing + margins in `.github/release-notes/v3.3.0.md`). - **The IRQ-timing trace goldens are a test now** (the `irq-timing-trace` developer feature). The fixture rewrote its 21 committed traces on every run and compared nothing, so they caught no regression; 19 of them no diff --git a/Cargo.lock b/Cargo.lock index 04492c5df..5719e33e4 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4576,7 +4576,7 @@ dependencies = [ [[package]] name = "rustynes-android" -version = "3.7.0" +version = "3.7.1" dependencies = [ "android-activity", "android_logger", @@ -4594,7 +4594,7 @@ dependencies = [ [[package]] name = "rustynes-apu" -version = "3.7.0" +version = "3.7.1" dependencies = [ "bitflags 2.13.2", "criterion", @@ -4607,7 +4607,7 @@ dependencies = [ [[package]] name = "rustynes-cheevos" -version = "3.7.0" +version = "3.7.1" dependencies = [ "cc", "libc", @@ -4616,7 +4616,7 @@ dependencies = [ [[package]] name = "rustynes-core" -version = "3.7.0" +version = "3.7.1" dependencies = [ "bitflags 2.13.2", "criterion", @@ -4633,7 +4633,7 @@ dependencies = [ [[package]] name = "rustynes-cpu" -version = "3.7.0" +version = "3.7.1" dependencies = [ "bitflags 2.13.2", "criterion", @@ -4644,7 +4644,7 @@ dependencies = [ [[package]] name = "rustynes-dap" -version = "3.7.0" +version = "3.7.1" dependencies = [ "base64 0.23.1", "gimli", @@ -4655,7 +4655,7 @@ dependencies = [ [[package]] name = "rustynes-frontend" -version = "3.7.0" +version = "3.7.1" dependencies = [ "anstyle", "arboard", @@ -4717,18 +4717,18 @@ dependencies = [ [[package]] name = "rustynes-gamedb" -version = "3.7.0" +version = "3.7.1" dependencies = [ "rustynes-core", ] [[package]] name = "rustynes-gfx-shaders" -version = "3.7.0" +version = "3.7.1" [[package]] name = "rustynes-hdpack" -version = "3.7.0" +version = "3.7.1" dependencies = [ "lewton", "png", @@ -4739,7 +4739,7 @@ dependencies = [ [[package]] name = "rustynes-ios" -version = "3.7.0" +version = "3.7.1" dependencies = [ "bytemuck", "cpal", @@ -4753,7 +4753,7 @@ dependencies = [ [[package]] name = "rustynes-libretro" -version = "3.7.0" +version = "3.7.1" dependencies = [ "libc", "rust-libretro", @@ -4763,7 +4763,7 @@ dependencies = [ [[package]] name = "rustynes-mappers" -version = "3.7.0" +version = "3.7.1" dependencies = [ "bitflags 2.13.2", "criterion", @@ -4775,7 +4775,7 @@ dependencies = [ [[package]] name = "rustynes-mcp" -version = "3.7.0" +version = "3.7.1" dependencies = [ "base64 0.23.1", "hex", @@ -4792,7 +4792,7 @@ dependencies = [ [[package]] name = "rustynes-mobile" -version = "3.7.0" +version = "3.7.1" dependencies = [ "getrandom 0.4.3", "rustynes-core", @@ -4809,7 +4809,7 @@ dependencies = [ [[package]] name = "rustynes-netplay" -version = "3.7.0" +version = "3.7.1" dependencies = [ "criterion", "futures-util", @@ -4830,7 +4830,7 @@ dependencies = [ [[package]] name = "rustynes-ppu" -version = "3.7.0" +version = "3.7.1" dependencies = [ "bitflags 2.13.2", "criterion", @@ -4842,21 +4842,21 @@ dependencies = [ [[package]] name = "rustynes-probe" -version = "3.7.0" +version = "3.7.1" dependencies = [ "rustynes-core", ] [[package]] name = "rustynes-ra" -version = "3.7.0" +version = "3.7.1" dependencies = [ "rustynes-cheevos", ] [[package]] name = "rustynes-script" -version = "3.7.0" +version = "3.7.1" dependencies = [ "mlua", "piccolo", @@ -4867,7 +4867,7 @@ dependencies = [ [[package]] name = "rustynes-test-harness" -version = "3.7.0" +version = "3.7.1" dependencies = [ "insta", "png", diff --git a/Cargo.toml b/Cargo.toml index 247a3e985..a8232836f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -79,7 +79,7 @@ default-members = ["crates/rustynes-libretro"] # `release-auto.yml` reads the `## [X.Y.Z]` line for BOTH the release body # fallback and the title codename — so the date and quoted codename are load- # bearing, not decoration. -version = "3.7.0" +version = "3.7.1" edition = "2024" # The toolchain is 1.100 (rust-toolchain.toml), and every crate inherits this # floor, the libretro path included: the libretro buildbot follows the same pin diff --git a/OVERVIEW.md b/OVERVIEW.md index 8d9afb6ff..e8aaac14c 100644 --- a/OVERVIEW.md +++ b/OVERVIEW.md @@ -2,7 +2,7 @@ **Document Version:** 2.1.0 **Last Updated:** 2026-10-06 -**Applies to:** RustyNES v3.7.0 +**Applies to:** RustyNES v3.7.1 --- @@ -22,9 +22,9 @@ RustyNES is the **definitive NES emulator for the modern era** — combining cycle-perfect accuracy with a complete contemporary feature set and the safety guarantees of Rust. It is more than an emulator: it is a platform for NES preservation, competitive online play, tool-assisted speedrunning, and homebrew development. -As of **v1.0.0**, that vision was realized: RustyNES clears the Mesen2 / higan / ares accuracy bar, ships a polished desktop application and a browser build, and supports the full platform surface — netplay, achievements, TAS movies, a debugger, FDS, and arcade (Vs. / PlayChoice-10) hardware. Since then the additive v1.x line added three more platforms (native Android, iOS / iPadOS, and a Libretro / RetroArch core), **v2.0.0 "Timebase"** replaced the scheduler substrate with the one-clock / every-cycle-bus-access model (ADR 0029 — the first designated breaking release), and the v2.1.x → v2.3.x lines deepened accuracy, presentation, and analysis tooling. The current release is **v3.7.0 "Spindle"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — the RetroArch core loads on Apple Silicon Macs again. Built on **v3.4.1 "Beacon"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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. Built on **v2.9.5 "Caliper"** — every open accuracy item measured, then fixed or closed: four fixes red first (the `apu_test` frame-counter coincidence, the composite 2C02 scanline-0 sprite glitch, OAM DMA filling the PPU I/O latch, KS7032 at `$6000`), 49 unreferenced test ROMs gated, the MMC3 M2-edge filter lever tried and refuted, and a save-state epoch (`PPU_SNAPSHOT_VERSION` 11). Built on **v2.9.4 "Plumb"** — the records made true, and CI made to run what it only linted: v3.0.0 decided as the API major with a release-candidate core (ADR 0043), CI now running 63 feature-gated tests it never ran, the eight fuzz targets and a 70% line-coverage floor, the mapper tiers, store status and deferred-features catalogue corrected against the code, and the OAM-decay model recorded as derived from Mesen2. Built on **v2.9.3 "Handset"** — the old review threads closed and the mobile run prepared: every dependency moved to its newest release (egui 0.36 with wgpu 30, rcheevos 12.5.0), all 244 review threads left unanswered on PRs #7-#97 answered and the ten findings that still held fixed (Action 53 multicarts rebuilt to the NESdev spec, and a ROM header editor that no longer rewrites bytes you did not edit or saves mappers from 16 up as the wrong mapper), and the Android unit tests and the iOS renderer added to CI. Built on **v2.9.2 "Candidate"** — the full audit acted on, and the release-candidate pair: all 32 findings of a fifth audit have a verdict and 16 are fixed, save states keep the cartridge RAM of twelve board families they used to drop, the MiSTer core no longer loses an NMI raised inside a DMA, and both bitstreams are cut for the SuperStation One session. Built on **v2.9.1 "Hone"** — what the optimisation bars measure, and what clears them: the A/B tool had been timing the old code on both sides of every code comparison and is fixed, a two-screen Vs. cabinet saves about 9x faster, the off-die MiSTer build keeps CHR in its own SDRAM bank, and both bitstreams are pinned at fitter seed 2 and rebuild byte-identically. Built on **v2.9.0 "Survey"** — every audit re-checked, and the SuperStation One surveyed: a Power Cycle no longer erases your save, the off-die MiSTer build boots without the menu core, and 39 new audit findings are fixed or dispositioned. Built on **v2.8.4 "Tether"** — the MiSTer core's SDRAM build, made trustworthy: its controller now reads data on the edge the memory presents it (every off-die read would have been wrong on hardware, and only the new SDRAM timing constraints could see it), the power-up sequence and CAS-latency-3 reads follow the datasheet, the arbiter can no longer return the wrong byte or lose a write, the off-die bitstream builds from a script, both builds are swept and pinned at fitter seed 5, and the co-simulation ladder runs all 165 gates from a clean checkout. Built on **v2.8.3 "Rivet"** — the MiSTer core's reset, area and comments, measured: every reset is released on the clock that uses it and the timing analysis now checks each release, the CPU is about 4% smaller by two exact rewrites the fit report confirmed, four false comments are corrected, and the co-simulation ladder runs from a fresh checkout (164 of its 165 gates; the last needs a hand-built ROM no generator produces). Built on **v2.8.2 "Solder"** — the MiSTer core's on-die RTL, corrected against the oracle and the wiki: an MMC3 IRQ acknowledge is no longer lost to a same-edge counter clock, SNROM's battery RAM obeys its CHR-line enable, the triangle and noise drop a reload landing on a length clock, a `$2002` read leaves the byte it returned on the data bus, and the emulator's MMC1 no longer ignores a reset written on the cycle after another write. Built on **v2.8.1 "Gasket"** — the libretro core fits the frontends around it: four-player games work through a Four Score option, a controller works again after its port leaves the Zapper, RetroArch no longer reads past the core's input-descriptor list, expansion audio no longer clips, the core declares UNIF images, and the Makefile honours PREFIX, platform=win, DEBUG and CARGO_TARGET_DIR. Built on **v2.8.0 "Bulkhead"** — the libretro core stops a fault at its own boundary: an internal error no longer closes RetroArch, save states survive plugging in a Zapper, closing a game withdraws its memory maps, the core loads from any libretro frontend, and the save state now carries the 2A03 internal data bus. Built on **v2.7.6 "Recount"** — the v2.7.5 deletions measured one at a time: the six performance proposals v2.7.5 bounded only together were each measured alone, where the benchmarks reach them: five are zero, and the sixth, the pulse sweep-mute check, bounds at about 0.2%, and the cheap byte-identical way to take it measured slower; the fast render path now asserts a rendering-history invariant it used to re-write; and the libretro buildbot builds macOS again and gains 32-bit Windows, 32-bit Linux and webOS targets. Built on **v2.7.5 "Tally"** — every audit claim closed with a measurement or a reason: the core audit's twelve performance proposals were closed, eleven of them by measurement, and one adopted (the audio buffer keeps its capacity between frames); 18 dead bus methods and the unused ApuBus trait are deprecated; and the core and frontend ledgers have no open row. Built on **v2.7.4 "Pocket"** — the mobile apps survive what a phone does to them: an internal error no longer closes the Android or iOS app, battery saves persist on both, the apps pause and give up audio when they should, and saves are written so a dying phone keeps the last good one. Built on **v2.7.3 "Hearth"** — the desktop and web frontends keep what they are given: battery saves persist on the desktop, a Lua script can no longer hang or exhaust the emulator, script HTTP cannot reach local services by default, and audio survives a device change. Built on **v2.7.2 "Bankroll"** — cartridge memory, every bank a cartridge has and nothing it has not: MMC1 reaches SUROM / SXROM, MMC5 banks its PRG-RAM, Namco 163 selects nametables, and `$6000-$7FFF` reads open bus where a board has nothing there. Built on **v2.7.1 "Keepsake"** — six cartridge boards now hand RetroArch their battery save instead of an empty one, every user file the frontend writes is written atomically, and three mapper files are now recorded as derived from Mesen2 and puNES. Built on **v2.7.0 "Palisade"** — a corrupt or hand-edited save state now fails at restore with a typed error instead of crashing the emulator one tick later, pulse 1 no longer mutes on the `$4001 = $08` sweep idiom, and the save-state fuzz target can finally reach what it exists to find. Built on **v2.6.23 "Pulse"** — the access does not increment, it pulses the load already there: the CHR-during-rendering gate closes at 61,440 of 61,440 pixels, and **no hardware has run any bitstream** — built on **v2.6.22 "Rigging"**, the instruments for the board, built before the board: AccuracyCoin reads back from hardware as bytes rather than as a photograph, the catalog turns out to carry 149 rows and 144 results so the headline no longer depends on when the run was sampled (at the same 144/144), and a `rom_sha256` recorded in every golden manifest and compared to nothing is now rung 0 — built on **v2.6.21 "Steward"**, which brought battery saves, the CHR-during-rendering gate RED at 32,861 of 61,440 pixels, and the deploy loop the runbook prescribed and **v2.6.20 "Telltale"**, itself on **v2.6.19 "Accession"** and **v2.6.18 "Errata"**, built on **v2.6.17 "Terminus"**. The never-tagged v2.4.0 "Concordance" shipped inside **v2.4.1 "Fabric"** — this sentence had attached that fact to whichever release was current, carried forward by three mechanical version bumps, and said it of v2.4.2, v2.4.3 and v2.4.4 in turn. +As of **v1.0.0**, that vision was realized: RustyNES clears the Mesen2 / higan / ares accuracy bar, ships a polished desktop application and a browser build, and supports the full platform surface — netplay, achievements, TAS movies, a debugger, FDS, and arcade (Vs. / PlayChoice-10) hardware. Since then the additive v1.x line added three more platforms (native Android, iOS / iPadOS, and a Libretro / RetroArch core), **v2.0.0 "Timebase"** replaced the scheduler substrate with the one-clock / every-cycle-bus-access model (ADR 0029 — the first designated breaking release), and the v2.1.x → v2.3.x lines deepened accuracy, presentation, and analysis tooling. The current release is **v3.7.1 "Imprint"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — the RetroArch core loads on Apple Silicon Macs again. Built on **v3.4.1 "Beacon"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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. Built on **v2.9.5 "Caliper"** — every open accuracy item measured, then fixed or closed: four fixes red first (the `apu_test` frame-counter coincidence, the composite 2C02 scanline-0 sprite glitch, OAM DMA filling the PPU I/O latch, KS7032 at `$6000`), 49 unreferenced test ROMs gated, the MMC3 M2-edge filter lever tried and refuted, and a save-state epoch (`PPU_SNAPSHOT_VERSION` 11). Built on **v2.9.4 "Plumb"** — the records made true, and CI made to run what it only linted: v3.0.0 decided as the API major with a release-candidate core (ADR 0043), CI now running 63 feature-gated tests it never ran, the eight fuzz targets and a 70% line-coverage floor, the mapper tiers, store status and deferred-features catalogue corrected against the code, and the OAM-decay model recorded as derived from Mesen2. Built on **v2.9.3 "Handset"** — the old review threads closed and the mobile run prepared: every dependency moved to its newest release (egui 0.36 with wgpu 30, rcheevos 12.5.0), all 244 review threads left unanswered on PRs #7-#97 answered and the ten findings that still held fixed (Action 53 multicarts rebuilt to the NESdev spec, and a ROM header editor that no longer rewrites bytes you did not edit or saves mappers from 16 up as the wrong mapper), and the Android unit tests and the iOS renderer added to CI. Built on **v2.9.2 "Candidate"** — the full audit acted on, and the release-candidate pair: all 32 findings of a fifth audit have a verdict and 16 are fixed, save states keep the cartridge RAM of twelve board families they used to drop, the MiSTer core no longer loses an NMI raised inside a DMA, and both bitstreams are cut for the SuperStation One session. Built on **v2.9.1 "Hone"** — what the optimisation bars measure, and what clears them: the A/B tool had been timing the old code on both sides of every code comparison and is fixed, a two-screen Vs. cabinet saves about 9x faster, the off-die MiSTer build keeps CHR in its own SDRAM bank, and both bitstreams are pinned at fitter seed 2 and rebuild byte-identically. Built on **v2.9.0 "Survey"** — every audit re-checked, and the SuperStation One surveyed: a Power Cycle no longer erases your save, the off-die MiSTer build boots without the menu core, and 39 new audit findings are fixed or dispositioned. Built on **v2.8.4 "Tether"** — the MiSTer core's SDRAM build, made trustworthy: its controller now reads data on the edge the memory presents it (every off-die read would have been wrong on hardware, and only the new SDRAM timing constraints could see it), the power-up sequence and CAS-latency-3 reads follow the datasheet, the arbiter can no longer return the wrong byte or lose a write, the off-die bitstream builds from a script, both builds are swept and pinned at fitter seed 5, and the co-simulation ladder runs all 165 gates from a clean checkout. Built on **v2.8.3 "Rivet"** — the MiSTer core's reset, area and comments, measured: every reset is released on the clock that uses it and the timing analysis now checks each release, the CPU is about 4% smaller by two exact rewrites the fit report confirmed, four false comments are corrected, and the co-simulation ladder runs from a fresh checkout (164 of its 165 gates; the last needs a hand-built ROM no generator produces). Built on **v2.8.2 "Solder"** — the MiSTer core's on-die RTL, corrected against the oracle and the wiki: an MMC3 IRQ acknowledge is no longer lost to a same-edge counter clock, SNROM's battery RAM obeys its CHR-line enable, the triangle and noise drop a reload landing on a length clock, a `$2002` read leaves the byte it returned on the data bus, and the emulator's MMC1 no longer ignores a reset written on the cycle after another write. Built on **v2.8.1 "Gasket"** — the libretro core fits the frontends around it: four-player games work through a Four Score option, a controller works again after its port leaves the Zapper, RetroArch no longer reads past the core's input-descriptor list, expansion audio no longer clips, the core declares UNIF images, and the Makefile honours PREFIX, platform=win, DEBUG and CARGO_TARGET_DIR. Built on **v2.8.0 "Bulkhead"** — the libretro core stops a fault at its own boundary: an internal error no longer closes RetroArch, save states survive plugging in a Zapper, closing a game withdraws its memory maps, the core loads from any libretro frontend, and the save state now carries the 2A03 internal data bus. Built on **v2.7.6 "Recount"** — the v2.7.5 deletions measured one at a time: the six performance proposals v2.7.5 bounded only together were each measured alone, where the benchmarks reach them: five are zero, and the sixth, the pulse sweep-mute check, bounds at about 0.2%, and the cheap byte-identical way to take it measured slower; the fast render path now asserts a rendering-history invariant it used to re-write; and the libretro buildbot builds macOS again and gains 32-bit Windows, 32-bit Linux and webOS targets. Built on **v2.7.5 "Tally"** — every audit claim closed with a measurement or a reason: the core audit's twelve performance proposals were closed, eleven of them by measurement, and one adopted (the audio buffer keeps its capacity between frames); 18 dead bus methods and the unused ApuBus trait are deprecated; and the core and frontend ledgers have no open row. Built on **v2.7.4 "Pocket"** — the mobile apps survive what a phone does to them: an internal error no longer closes the Android or iOS app, battery saves persist on both, the apps pause and give up audio when they should, and saves are written so a dying phone keeps the last good one. Built on **v2.7.3 "Hearth"** — the desktop and web frontends keep what they are given: battery saves persist on the desktop, a Lua script can no longer hang or exhaust the emulator, script HTTP cannot reach local services by default, and audio survives a device change. Built on **v2.7.2 "Bankroll"** — cartridge memory, every bank a cartridge has and nothing it has not: MMC1 reaches SUROM / SXROM, MMC5 banks its PRG-RAM, Namco 163 selects nametables, and `$6000-$7FFF` reads open bus where a board has nothing there. Built on **v2.7.1 "Keepsake"** — six cartridge boards now hand RetroArch their battery save instead of an empty one, every user file the frontend writes is written atomically, and three mapper files are now recorded as derived from Mesen2 and puNES. Built on **v2.7.0 "Palisade"** — a corrupt or hand-edited save state now fails at restore with a typed error instead of crashing the emulator one tick later, pulse 1 no longer mutes on the `$4001 = $08` sweep idiom, and the save-state fuzz target can finally reach what it exists to find. Built on **v2.6.23 "Pulse"** — the access does not increment, it pulses the load already there: the CHR-during-rendering gate closes at 61,440 of 61,440 pixels, and **no hardware has run any bitstream** — built on **v2.6.22 "Rigging"**, the instruments for the board, built before the board: AccuracyCoin reads back from hardware as bytes rather than as a photograph, the catalog turns out to carry 149 rows and 144 results so the headline no longer depends on when the run was sampled (at the same 144/144), and a `rom_sha256` recorded in every golden manifest and compared to nothing is now rung 0 — built on **v2.6.21 "Steward"**, which brought battery saves, the CHR-during-rendering gate RED at 32,861 of 61,440 pixels, and the deploy loop the runbook prescribed and **v2.6.20 "Telltale"**, itself on **v2.6.19 "Accession"** and **v2.6.18 "Errata"**, built on **v2.6.17 "Terminus"**. The never-tagged v2.4.0 "Concordance" shipped inside **v2.4.1 "Fabric"** — this sentence had attached that fact to whichever release was current, carried forward by three mechanical version bumps, and said it of v2.4.2, v2.4.3 and v2.4.4 in turn. -> RustyNES's emulation core descends from an extensively-documented accuracy program. Where this and related docs reference deep "v1.x"/"v2.x" engine narrative, read it as upstream engine lineage (engineering history), not as RustyNES release versions. Two distinct "v2.0"s exist and must not be conflated: the engine-lineage v2.0 master-clock work shipped as RustyNES **v1.0.0**, while RustyNES's own **v2.0.0 "Timebase"** (2026-07-03) is the later release that *replaced* that same scheduler. The current release is **v3.7.0**. +> RustyNES's emulation core descends from an extensively-documented accuracy program. Where this and related docs reference deep "v1.x"/"v2.x" engine narrative, read it as upstream engine lineage (engineering history), not as RustyNES release versions. Two distinct "v2.0"s exist and must not be conflated: the engine-lineage v2.0 master-clock work shipped as RustyNES **v1.0.0**, while RustyNES's own **v2.0.0 "Timebase"** (2026-07-03) is the later release that *replaced* that same scheduler. The current release is **v3.7.1**. --- diff --git a/README.md b/README.md index bc0d8f915..3345188ae 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@

- Build Status License: GPL-3.0-or-later Version Rust: 1.100
+ Build Status License: GPL-3.0-or-later Version Rust: 1.100
AccuracyCoin nestest Mapper families Try in browser
Platform

@@ -30,12 +30,6 @@ Android, iOS and RetroArch, all on one bit-deterministic core. **[Play it in your browser](https://doublegate.github.io/RustyNES/)**, no install required. -**Upgrading from v2.x?** v3.0.0 "Cornerstone" is a major release. Save states -and movies made by earlier versions are refused, netplay needs both sides on the -same emulation epoch, and saves are keyed to the ROM without its header. -[The v3.0.0 release notes](.github/release-notes/v3.0.0.md) list every change by -audience: players, RetroArch, mobile and the Rust crates. - > **Development note: AI-assisted.** RustyNES is built with LLM tooling under a > human-directed, test-driven workflow, with public test ROMs as the oracle. See > [`docs/originality-and-provenance.md`](docs/originality-and-provenance.md) for @@ -93,9 +87,9 @@ audience: players, RetroArch, mobile and the Rust crates. Pre-built binaries for every release are on the [Releases page](https://github.com/doublegate/RustyNES/releases): Linux `x86_64`, -macOS (Apple silicon) and Windows `x86_64`. From v2.9.7 they are the full -native build: RetroAchievements, Lua scripting, HD packs, A/V recording (with -`ffmpeg` on your `PATH`) and the debugger telemetry are all included. +macOS (Apple silicon) and Windows `x86_64`. They are the full native build: +RetroAchievements, Lua scripting, HD packs, A/V recording (with `ffmpeg` on +your `PATH`) and the debugger telemetry are all included. ```bash # Linux / macOS @@ -105,7 +99,10 @@ Expand-Archive rustynes--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.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).

Six commercial titles rendered by the MiSTer core's RTL under Verilator, each byte-identical to this emulator @@ -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 diff --git a/ROADMAP.md b/ROADMAP.md index 14f20c6f3..ca6d6ac49 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -2,13 +2,13 @@ **Document Version:** 2.0.4 **Last Updated:** 2026-10-06 -**Project Status:** v3.7.0 "Spindle" released — 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"** (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) and **v3.6.1 "Threshold"** (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) and **v3.6.0 "Octave"** (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) and **v3.5.1 "Reprise"** (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) and **v3.5.0 "Chorus"** (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) and **v3.4.2 "Countersign"** (the RetroArch core loads on Apple Silicon Macs again) and **v3.4.1 "Beacon"** (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) and **v3.4.0 "Waypoint"** (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) and **v3.3.0 "Plumbline"** (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) and **v3.2.0 "Confluence"** (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) and **v3.1.0 "Bellwether"** (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) and **v3.0.1 "Mortar"** (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) and **v3.0.0 "Cornerstone"** (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) and **v2.9.9 "Ballast"** (the release candidate for v3.0.0: all four audit scopes re-run, MMC3 and MMC5 by their documentation, audio exact across save states, and the MiSTer core moved onto it with the release-candidate bitstream pair; the tenth release of the v2.9.x line and the sixth of the line to v3.0.0 (ADR 0043, amended)) and **v2.9.8 "Vanguard"** (v3.0.0's breaking changes landed early) and **v2.9.7 "Tandem"** (the desktop's features on the web and on phones). **No hardware has run any bitstream**; the mobile device runs and the SuperStation One board session move after v3.0.0 (maintainer, 2026-09-29). +**Project Status:** v3.7.1 "Imprint" released — 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"** (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) and **v3.6.2 "Latchkey"** (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) and **v3.6.1 "Threshold"** (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) and **v3.6.0 "Octave"** (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) and **v3.5.1 "Reprise"** (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) and **v3.5.0 "Chorus"** (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) and **v3.4.2 "Countersign"** (the RetroArch core loads on Apple Silicon Macs again) and **v3.4.1 "Beacon"** (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) and **v3.4.0 "Waypoint"** (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) and **v3.3.0 "Plumbline"** (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) and **v3.2.0 "Confluence"** (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) and **v3.1.0 "Bellwether"** (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) and **v3.0.1 "Mortar"** (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) and **v3.0.0 "Cornerstone"** (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) and **v2.9.9 "Ballast"** (the release candidate for v3.0.0: all four audit scopes re-run, MMC3 and MMC5 by their documentation, audio exact across save states, and the MiSTer core moved onto it with the release-candidate bitstream pair; the tenth release of the v2.9.x line and the sixth of the line to v3.0.0 (ADR 0043, amended)) and **v2.9.8 "Vanguard"** (v3.0.0's breaking changes landed early) and **v2.9.7 "Tandem"** (the desktop's features on the web and on phones). **No hardware has run any bitstream**; the mobile device runs and the SuperStation One board session move after v3.0.0 (maintainer, 2026-09-29). --- ## Where we are -RustyNES is well past v1.0.0. The current release is **v3.7.0 "Spindle"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — the RetroArch core loads on Apple Silicon Macs again. Built on **v3.4.1 "Beacon"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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. Built on **v2.9.5 "Caliper"** — every open accuracy item measured, then fixed or closed: four fixes red first (the `apu_test` frame-counter coincidence, the composite 2C02 scanline-0 sprite glitch, OAM DMA filling the PPU I/O latch, KS7032 at `$6000`), 49 unreferenced test ROMs gated, the MMC3 M2-edge filter lever tried and refuted, and a save-state epoch (`PPU_SNAPSHOT_VERSION` 11). Built on **v2.9.4 "Plumb"** — the records made true, and CI made to run what it only linted: v3.0.0 decided as the API major with a release-candidate core (ADR 0043), CI now running 63 feature-gated tests it never ran, the eight fuzz targets and a 70% line-coverage floor, the mapper tiers, store status and deferred-features catalogue corrected against the code, and the OAM-decay model recorded as derived from Mesen2. Built on **v2.9.3 "Handset"** — the old review threads closed and the mobile run prepared: every dependency moved to its newest release (egui 0.36 with wgpu 30, rcheevos 12.5.0), all 244 review threads left unanswered on PRs #7-#97 answered and the ten findings that still held fixed (Action 53 multicarts rebuilt to the NESdev spec, and a ROM header editor that no longer rewrites bytes you did not edit or saves mappers from 16 up as the wrong mapper), and the Android unit tests and the iOS renderer added to CI. Built on **v2.9.2 "Candidate"** — the full audit acted on, and the release-candidate pair: all 32 findings of a fifth audit have a verdict and 16 are fixed, save states keep the cartridge RAM of twelve board families they used to drop, the MiSTer core no longer loses an NMI raised inside a DMA, and both bitstreams are cut for the SuperStation One session. Built on **v2.9.1 "Hone"** — what the optimisation bars measure, and what clears them: the A/B tool had been timing the old code on both sides of every code comparison and is fixed, a two-screen Vs. cabinet saves about 9x faster, the off-die MiSTer build keeps CHR in its own SDRAM bank, and both bitstreams are pinned at fitter seed 2 and rebuild byte-identically. Built on **v2.9.0 "Survey"** — every audit re-checked, and the SuperStation One surveyed: a Power Cycle no longer erases your save, the off-die MiSTer build boots without the menu core, and 39 new audit findings are fixed or dispositioned. Built on **v2.8.4 "Tether"** — the MiSTer core's SDRAM build, made trustworthy: its controller now reads data on the edge the memory presents it (every off-die read would have been wrong on hardware, and only the new SDRAM timing constraints could see it), the power-up sequence and CAS-latency-3 reads follow the datasheet, the arbiter can no longer return the wrong byte or lose a write, the off-die bitstream builds from a script, both builds are swept and pinned at fitter seed 5, and the co-simulation ladder runs all 165 gates from a clean checkout. Built on **v2.8.3 "Rivet"** — the MiSTer core's reset, area and comments, measured: every reset is released on the clock that uses it and the timing analysis now checks each release, the CPU is about 4% smaller by two exact rewrites the fit report confirmed, four false comments are corrected, and the co-simulation ladder runs from a fresh checkout (164 of its 165 gates; the last needs a hand-built ROM no generator produces). **No hardware has run any bitstream.** +RustyNES is well past v1.0.0. The current release is **v3.7.1 "Imprint"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — the RetroArch core loads on Apple Silicon Macs again. Built on **v3.4.1 "Beacon"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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. Built on **v2.9.5 "Caliper"** — every open accuracy item measured, then fixed or closed: four fixes red first (the `apu_test` frame-counter coincidence, the composite 2C02 scanline-0 sprite glitch, OAM DMA filling the PPU I/O latch, KS7032 at `$6000`), 49 unreferenced test ROMs gated, the MMC3 M2-edge filter lever tried and refuted, and a save-state epoch (`PPU_SNAPSHOT_VERSION` 11). Built on **v2.9.4 "Plumb"** — the records made true, and CI made to run what it only linted: v3.0.0 decided as the API major with a release-candidate core (ADR 0043), CI now running 63 feature-gated tests it never ran, the eight fuzz targets and a 70% line-coverage floor, the mapper tiers, store status and deferred-features catalogue corrected against the code, and the OAM-decay model recorded as derived from Mesen2. Built on **v2.9.3 "Handset"** — the old review threads closed and the mobile run prepared: every dependency moved to its newest release (egui 0.36 with wgpu 30, rcheevos 12.5.0), all 244 review threads left unanswered on PRs #7-#97 answered and the ten findings that still held fixed (Action 53 multicarts rebuilt to the NESdev spec, and a ROM header editor that no longer rewrites bytes you did not edit or saves mappers from 16 up as the wrong mapper), and the Android unit tests and the iOS renderer added to CI. Built on **v2.9.2 "Candidate"** — the full audit acted on, and the release-candidate pair: all 32 findings of a fifth audit have a verdict and 16 are fixed, save states keep the cartridge RAM of twelve board families they used to drop, the MiSTer core no longer loses an NMI raised inside a DMA, and both bitstreams are cut for the SuperStation One session. Built on **v2.9.1 "Hone"** — what the optimisation bars measure, and what clears them: the A/B tool had been timing the old code on both sides of every code comparison and is fixed, a two-screen Vs. cabinet saves about 9x faster, the off-die MiSTer build keeps CHR in its own SDRAM bank, and both bitstreams are pinned at fitter seed 2 and rebuild byte-identically. Built on **v2.9.0 "Survey"** — every audit re-checked, and the SuperStation One surveyed: a Power Cycle no longer erases your save, the off-die MiSTer build boots without the menu core, and 39 new audit findings are fixed or dispositioned. Built on **v2.8.4 "Tether"** — the MiSTer core's SDRAM build, made trustworthy: its controller now reads data on the edge the memory presents it (every off-die read would have been wrong on hardware, and only the new SDRAM timing constraints could see it), the power-up sequence and CAS-latency-3 reads follow the datasheet, the arbiter can no longer return the wrong byte or lose a write, the off-die bitstream builds from a script, both builds are swept and pinned at fitter seed 5, and the co-simulation ladder runs all 165 gates from a clean checkout. Built on **v2.8.3 "Rivet"** — the MiSTer core's reset, area and comments, measured: every reset is released on the clock that uses it and the timing analysis now checks each release, the CPU is about 4% smaller by two exact rewrites the fit report confirmed, four false comments are corrected, and the co-simulation ladder runs from a fresh checkout (164 of its 165 gates; the last needs a hand-built ROM no generator produces). **No hardware has run any bitstream.** **This root ROADMAP is a historical snapshot of the v1.0.0 cut.** For the authoritative, current forward roadmap see **[`to-dos/ROADMAP.md`](to-dos/ROADMAP.md)**; for the authoritative current-state pass counts and platform matrix see **[`docs/STATUS.md`](docs/STATUS.md)**; for the full per-release history see **[`CHANGELOG.md`](CHANGELOG.md)**. Many of the "post-1.0 directions" listed further down (mobile, Lua scripting, TAS editor, Vs. DualSystem, HD packs, hosted netplay) have since shipped — the tables below record what was **done at v1.0.0**, not the current feature set. diff --git a/SECURITY.md b/SECURITY.md index 19daa42a0..4d9eb0ef6 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,7 +2,7 @@ ## Supported Versions -The current release is **v3.7.0 "Spindle"**. Built on **v3.6.2 "Latchkey"** and **v3.6.1 "Threshold"** and **v3.6.0 "Octave"** and **v3.5.1 "Reprise"** and **v3.5.0 "Chorus"** and **v3.4.2 "Countersign"** and **v3.4.1 "Beacon"** and **v3.4.0 "Waypoint"** and **v3.3.0 "Plumbline"** and **v3.2.0 "Confluence"** and **v3.1.0 "Bellwether"** and **v3.0.1 "Mortar"** and **v3.0.0 "Cornerstone"** and **v2.9.9 "Ballast"** and **v2.9.8 "Vanguard"** and **v2.9.7 "Tandem"** and **v2.9.6 "Roster"** and **v2.9.5 "Caliper"** and **v2.9.4 "Plumb"** and **v2.9.3 "Handset"** and **v2.9.2 "Candidate"** and **v2.9.1 "Hone"** and **v2.9.0 "Survey"** and **v2.8.4 "Tether"** and **v2.8.3 "Rivet"** and **v2.8.2 "Solder"** and **v2.8.1 "Gasket"** and **v2.8.0 "Bulkhead"** and **v2.7.6 "Recount"** and **v2.7.5 "Tally"** and **v2.7.4 "Pocket"** and **v2.7.3 "Hearth"** and **v2.7.2 "Bankroll"** and **v2.7.1 "Keepsake"** and **v2.7.0 "Palisade"** and **v2.6.23 "Pulse"** and **v2.6.22 "Rigging"** and **v2.6.21 "Steward"** and **v2.6.20 "Telltale"** and **v2.6.19 "Accession"** and **v2.6.18 "Errata"** and **v2.6.17 "Terminus"** and **v2.6.16 "Interlock"** and **v2.6.15 "Warrant"** and **v2.6.14 "Docket"** and **v2.6.13 "Slack"** and **v2.6.12 "Groundwork"** and **v2.6.11 "Exposure"** and **v2.6.10 "Inference"** and **v2.6.9 "Abeyance"** and **v2.6.8 "Arrears"** and **v2.6.7 "Detent"** and **v2.6.6 "Chassis"** and **v2.6.5 "Muster"** and **v2.6.4 "Rubric"** and **v2.6.3 "Mainspring"** and **v2.6.2 "Witness"** and **v2.6.1 "Interleave"** and **v2.6.0 "Assay"** and **v2.5.9 "Overture"** and **v2.5.8 "Blanking"** and **v2.5.7 "Collimation"** and **v2.5.6 "Vestige"** and **v2.5.5 "Raster"** and **v2.5.4 "Escapement"** and **v2.5.3 "Hysteresis"** and **v2.5.2 "Dormant"** and **v2.5.1 "Retrace"** and **v2.5.0 "Rungwork"** and **v2.4.9 "Plumbline II"** and **v2.4.8 "Palimpsest"** and **v2.4.7 "Keystone"** and **v2.4.6 "Abacus"** and **v2.4.5 "Compass"** and **v2.4.4 "Ignition"** and **v2.4.3 "Touchstone"** and **v2.4.2 "Cairn"** and **v2.4.1 "Fabric"**, which also carries the never-tagged v2.4.0 "Concordance". RustyNES ships from `main` on a +The current release is **v3.7.1 "Imprint"**. Built on **v3.7.0 "Spindle"** and **v3.6.2 "Latchkey"** and **v3.6.1 "Threshold"** and **v3.6.0 "Octave"** and **v3.5.1 "Reprise"** and **v3.5.0 "Chorus"** and **v3.4.2 "Countersign"** and **v3.4.1 "Beacon"** and **v3.4.0 "Waypoint"** and **v3.3.0 "Plumbline"** and **v3.2.0 "Confluence"** and **v3.1.0 "Bellwether"** and **v3.0.1 "Mortar"** and **v3.0.0 "Cornerstone"** and **v2.9.9 "Ballast"** and **v2.9.8 "Vanguard"** and **v2.9.7 "Tandem"** and **v2.9.6 "Roster"** and **v2.9.5 "Caliper"** and **v2.9.4 "Plumb"** and **v2.9.3 "Handset"** and **v2.9.2 "Candidate"** and **v2.9.1 "Hone"** and **v2.9.0 "Survey"** and **v2.8.4 "Tether"** and **v2.8.3 "Rivet"** and **v2.8.2 "Solder"** and **v2.8.1 "Gasket"** and **v2.8.0 "Bulkhead"** and **v2.7.6 "Recount"** and **v2.7.5 "Tally"** and **v2.7.4 "Pocket"** and **v2.7.3 "Hearth"** and **v2.7.2 "Bankroll"** and **v2.7.1 "Keepsake"** and **v2.7.0 "Palisade"** and **v2.6.23 "Pulse"** and **v2.6.22 "Rigging"** and **v2.6.21 "Steward"** and **v2.6.20 "Telltale"** and **v2.6.19 "Accession"** and **v2.6.18 "Errata"** and **v2.6.17 "Terminus"** and **v2.6.16 "Interlock"** and **v2.6.15 "Warrant"** and **v2.6.14 "Docket"** and **v2.6.13 "Slack"** and **v2.6.12 "Groundwork"** and **v2.6.11 "Exposure"** and **v2.6.10 "Inference"** and **v2.6.9 "Abeyance"** and **v2.6.8 "Arrears"** and **v2.6.7 "Detent"** and **v2.6.6 "Chassis"** and **v2.6.5 "Muster"** and **v2.6.4 "Rubric"** and **v2.6.3 "Mainspring"** and **v2.6.2 "Witness"** and **v2.6.1 "Interleave"** and **v2.6.0 "Assay"** and **v2.5.9 "Overture"** and **v2.5.8 "Blanking"** and **v2.5.7 "Collimation"** and **v2.5.6 "Vestige"** and **v2.5.5 "Raster"** and **v2.5.4 "Escapement"** and **v2.5.3 "Hysteresis"** and **v2.5.2 "Dormant"** and **v2.5.1 "Retrace"** and **v2.5.0 "Rungwork"** and **v2.4.9 "Plumbline II"** and **v2.4.8 "Palimpsest"** and **v2.4.7 "Keystone"** and **v2.4.6 "Abacus"** and **v2.4.5 "Compass"** and **v2.4.4 "Ignition"** and **v2.4.3 "Touchstone"** and **v2.4.2 "Cairn"** and **v2.4.1 "Fabric"**, which also carries the never-tagged v2.4.0 "Concordance". RustyNES ships from `main` on a rolling patch cadence rather than maintaining long-lived release branches, so security fixes land in the next patch release rather than being backported. Report against the latest release or `main`. diff --git a/SUPPORT.md b/SUPPORT.md index 1f8edf792..341abe578 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -94,7 +94,7 @@ A: RustyNES is a cycle-accurate NES emulator written in pure Rust, clearing the **Q: Can I use RustyNES now?** -A: Yes. RustyNES is well past its first stable release — the current release is **v3.7.0 "Spindle"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — the RetroArch core loads on Apple Silicon Macs again. Built on **v3.4.1 "Beacon"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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. Built on **v2.9.5 "Caliper"** — every open accuracy item measured, then fixed or closed: four fixes red first (the `apu_test` frame-counter coincidence, the composite 2C02 scanline-0 sprite glitch, OAM DMA filling the PPU I/O latch, KS7032 at `$6000`), 49 unreferenced test ROMs gated, the MMC3 M2-edge filter lever tried and refuted, and a save-state epoch (`PPU_SNAPSHOT_VERSION` 11). Built on **v2.9.4 "Plumb"** — the records made true, and CI made to run what it only linted: v3.0.0 decided as the API major with a release-candidate core (ADR 0043), CI now running 63 feature-gated tests it never ran, the eight fuzz targets and a 70% line-coverage floor, the mapper tiers, store status and deferred-features catalogue corrected against the code, and the OAM-decay model recorded as derived from Mesen2. Built on **v2.9.3 "Handset"** — the old review threads closed and the mobile run prepared: every dependency moved to its newest release (egui 0.36 with wgpu 30, rcheevos 12.5.0), all 244 review threads left unanswered on PRs #7-#97 answered and the ten findings that still held fixed (Action 53 multicarts rebuilt to the NESdev spec, and a ROM header editor that no longer rewrites bytes you did not edit or saves mappers from 16 up as the wrong mapper), and the Android unit tests and the iOS renderer added to CI. Built on **v2.9.2 "Candidate"** — the full audit acted on, and the release-candidate pair: all 32 findings of a fifth audit have a verdict and 16 are fixed, save states keep the cartridge RAM of twelve board families they used to drop, the MiSTer core no longer loses an NMI raised inside a DMA, and both bitstreams are cut for the SuperStation One session. Built on **v2.9.1 "Hone"** — what the optimisation bars measure, and what clears them: the A/B tool had been timing the old code on both sides of every code comparison and is fixed, a two-screen Vs. cabinet saves about 9x faster, the off-die MiSTer build keeps CHR in its own SDRAM bank, and both bitstreams are pinned at fitter seed 2 and rebuild byte-identically. Built on **v2.9.0 "Survey"** — every audit re-checked, and the SuperStation One surveyed: a Power Cycle no longer erases your save, the off-die MiSTer build boots without the menu core, and 39 new audit findings are fixed or dispositioned. Built on **v2.8.4 "Tether"** — the MiSTer core's SDRAM build, made trustworthy: its controller now reads data on the edge the memory presents it (every off-die read would have been wrong on hardware, and only the new SDRAM timing constraints could see it), the power-up sequence and CAS-latency-3 reads follow the datasheet, the arbiter can no longer return the wrong byte or lose a write, the off-die bitstream builds from a script, both builds are swept and pinned at fitter seed 5, and the co-simulation ladder runs all 165 gates from a clean checkout. Built on **v2.8.3 "Rivet"** — the MiSTer core's reset, area and comments, measured: every reset is released on the clock that uses it and the timing analysis now checks each release, the CPU is about 4% smaller by two exact rewrites the fit report confirmed, four false comments are corrected, and the co-simulation ladder runs from a fresh checkout (164 of its 165 gates; the last needs a hand-built ROM no generator produces). **No hardware has run any bitstream.** +A: Yes. RustyNES is well past its first stable release — the current release is **v3.7.1 "Imprint"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — the RetroArch core loads on Apple Silicon Macs again. Built on **v3.4.1 "Beacon"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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. Built on **v2.9.5 "Caliper"** — every open accuracy item measured, then fixed or closed: four fixes red first (the `apu_test` frame-counter coincidence, the composite 2C02 scanline-0 sprite glitch, OAM DMA filling the PPU I/O latch, KS7032 at `$6000`), 49 unreferenced test ROMs gated, the MMC3 M2-edge filter lever tried and refuted, and a save-state epoch (`PPU_SNAPSHOT_VERSION` 11). Built on **v2.9.4 "Plumb"** — the records made true, and CI made to run what it only linted: v3.0.0 decided as the API major with a release-candidate core (ADR 0043), CI now running 63 feature-gated tests it never ran, the eight fuzz targets and a 70% line-coverage floor, the mapper tiers, store status and deferred-features catalogue corrected against the code, and the OAM-decay model recorded as derived from Mesen2. Built on **v2.9.3 "Handset"** — the old review threads closed and the mobile run prepared: every dependency moved to its newest release (egui 0.36 with wgpu 30, rcheevos 12.5.0), all 244 review threads left unanswered on PRs #7-#97 answered and the ten findings that still held fixed (Action 53 multicarts rebuilt to the NESdev spec, and a ROM header editor that no longer rewrites bytes you did not edit or saves mappers from 16 up as the wrong mapper), and the Android unit tests and the iOS renderer added to CI. Built on **v2.9.2 "Candidate"** — the full audit acted on, and the release-candidate pair: all 32 findings of a fifth audit have a verdict and 16 are fixed, save states keep the cartridge RAM of twelve board families they used to drop, the MiSTer core no longer loses an NMI raised inside a DMA, and both bitstreams are cut for the SuperStation One session. Built on **v2.9.1 "Hone"** — what the optimisation bars measure, and what clears them: the A/B tool had been timing the old code on both sides of every code comparison and is fixed, a two-screen Vs. cabinet saves about 9x faster, the off-die MiSTer build keeps CHR in its own SDRAM bank, and both bitstreams are pinned at fitter seed 2 and rebuild byte-identically. Built on **v2.9.0 "Survey"** — every audit re-checked, and the SuperStation One surveyed: a Power Cycle no longer erases your save, the off-die MiSTer build boots without the menu core, and 39 new audit findings are fixed or dispositioned. Built on **v2.8.4 "Tether"** — the MiSTer core's SDRAM build, made trustworthy: its controller now reads data on the edge the memory presents it (every off-die read would have been wrong on hardware, and only the new SDRAM timing constraints could see it), the power-up sequence and CAS-latency-3 reads follow the datasheet, the arbiter can no longer return the wrong byte or lose a write, the off-die bitstream builds from a script, both builds are swept and pinned at fitter seed 5, and the co-simulation ladder runs all 165 gates from a clean checkout. Built on **v2.8.3 "Rivet"** — the MiSTer core's reset, area and comments, measured: every reset is released on the clock that uses it and the timing analysis now checks each release, the CPU is about 4% smaller by two exact rewrites the fit report confirmed, four false comments are corrected, and the co-simulation ladder runs from a fresh checkout (164 of its 165 gates; the last needs a hand-built ROM no generator produces). **No hardware has run any bitstream.** **Q: How accurate is RustyNES?** diff --git a/VERSION-PLAN.md b/VERSION-PLAN.md index 00fab13b5..f714b1190 100644 --- a/VERSION-PLAN.md +++ b/VERSION-PLAN.md @@ -1,6 +1,6 @@ # RustyNES Version Plan -**Current release: v3.7.0 "Spindle"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — the RetroArch core loads on Apple Silicon Macs again. Built on **v3.4.1 "Beacon"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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. Built on **v2.9.5 "Caliper"** — every open accuracy item measured, then fixed or closed: four fixes red first (the `apu_test` frame-counter coincidence, the composite 2C02 scanline-0 sprite glitch, OAM DMA filling the PPU I/O latch, KS7032 at `$6000`), 49 unreferenced test ROMs gated, the MMC3 M2-edge filter lever tried and refuted, and a save-state epoch (`PPU_SNAPSHOT_VERSION` 11). Built on **v2.9.4 "Plumb"** — the records made true, and CI made to run what it only linted: v3.0.0 decided as the API major with a release-candidate core (ADR 0043), CI now running 63 feature-gated tests it never ran, the eight fuzz targets and a 70% line-coverage floor, the mapper tiers, store status and deferred-features catalogue corrected against the code, and the OAM-decay model recorded as derived from Mesen2. Built on **v2.9.3 "Handset"** — the old review threads closed and the mobile run prepared: every dependency moved to its newest release (egui 0.36 with wgpu 30, rcheevos 12.5.0), all 244 review threads left unanswered on PRs #7-#97 answered and the ten findings that still held fixed (Action 53 multicarts rebuilt to the NESdev spec, and a ROM header editor that no longer rewrites bytes you did not edit or saves mappers from 16 up as the wrong mapper), and the Android unit tests and the iOS renderer added to CI. Built on **v2.9.2 "Candidate"** — the full audit acted on, and the release-candidate pair: all 32 findings of a fifth audit have a verdict and 16 are fixed, save states keep the cartridge RAM of twelve board families they used to drop, the MiSTer core no longer loses an NMI raised inside a DMA, and both bitstreams are cut for the SuperStation One session. Built on **v2.9.1 "Hone"** — what the optimisation bars measure, and what clears them: the A/B tool had been timing the old code on both sides of every code comparison and is fixed, a two-screen Vs. cabinet saves about 9x faster, the off-die MiSTer build keeps CHR in its own SDRAM bank, and both bitstreams are pinned at fitter seed 2 and rebuild byte-identically. Built on **v2.9.0 "Survey"** — every audit re-checked, and the SuperStation One surveyed: a Power Cycle no longer erases your save, the off-die MiSTer build boots without the menu core, and 39 new audit findings are fixed or dispositioned. Built on **v2.8.4 "Tether"** — the MiSTer core's SDRAM build, made trustworthy: its controller now reads data on the edge the memory presents it (every off-die read would have been wrong on hardware, and only the new SDRAM timing constraints could see it), the power-up sequence and CAS-latency-3 reads follow the datasheet, the arbiter can no longer return the wrong byte or lose a write, the off-die bitstream builds from a script, both builds are swept and pinned at fitter seed 5, and the co-simulation ladder runs all 165 gates from a clean checkout. Built on **v2.8.3 "Rivet"** — the MiSTer core's reset, area and comments, measured: every reset is released on the clock that uses it and the timing analysis now checks each release, the CPU is about 4% smaller by two exact rewrites the fit report confirmed, four false comments are corrected, and the co-simulation ladder runs from a fresh checkout (164 of its 165 gates; the last needs a hand-built ROM no generator produces). Built on **v2.8.2 "Solder"** — the MiSTer core's on-die RTL, corrected against the oracle and the wiki: an MMC3 IRQ acknowledge is no longer lost to a same-edge counter clock, SNROM's battery RAM obeys its CHR-line enable, the triangle and noise drop a reload landing on a length clock, a `$2002` read leaves the byte it returned on the data bus, and the emulator's MMC1 no longer ignores a reset written on the cycle after another write. **No hardware has run any bitstream.** +**Current release: v3.7.1 "Imprint"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — the RetroArch core loads on Apple Silicon Macs again. Built on **v3.4.1 "Beacon"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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. Built on **v2.9.5 "Caliper"** — every open accuracy item measured, then fixed or closed: four fixes red first (the `apu_test` frame-counter coincidence, the composite 2C02 scanline-0 sprite glitch, OAM DMA filling the PPU I/O latch, KS7032 at `$6000`), 49 unreferenced test ROMs gated, the MMC3 M2-edge filter lever tried and refuted, and a save-state epoch (`PPU_SNAPSHOT_VERSION` 11). Built on **v2.9.4 "Plumb"** — the records made true, and CI made to run what it only linted: v3.0.0 decided as the API major with a release-candidate core (ADR 0043), CI now running 63 feature-gated tests it never ran, the eight fuzz targets and a 70% line-coverage floor, the mapper tiers, store status and deferred-features catalogue corrected against the code, and the OAM-decay model recorded as derived from Mesen2. Built on **v2.9.3 "Handset"** — the old review threads closed and the mobile run prepared: every dependency moved to its newest release (egui 0.36 with wgpu 30, rcheevos 12.5.0), all 244 review threads left unanswered on PRs #7-#97 answered and the ten findings that still held fixed (Action 53 multicarts rebuilt to the NESdev spec, and a ROM header editor that no longer rewrites bytes you did not edit or saves mappers from 16 up as the wrong mapper), and the Android unit tests and the iOS renderer added to CI. Built on **v2.9.2 "Candidate"** — the full audit acted on, and the release-candidate pair: all 32 findings of a fifth audit have a verdict and 16 are fixed, save states keep the cartridge RAM of twelve board families they used to drop, the MiSTer core no longer loses an NMI raised inside a DMA, and both bitstreams are cut for the SuperStation One session. Built on **v2.9.1 "Hone"** — what the optimisation bars measure, and what clears them: the A/B tool had been timing the old code on both sides of every code comparison and is fixed, a two-screen Vs. cabinet saves about 9x faster, the off-die MiSTer build keeps CHR in its own SDRAM bank, and both bitstreams are pinned at fitter seed 2 and rebuild byte-identically. Built on **v2.9.0 "Survey"** — every audit re-checked, and the SuperStation One surveyed: a Power Cycle no longer erases your save, the off-die MiSTer build boots without the menu core, and 39 new audit findings are fixed or dispositioned. Built on **v2.8.4 "Tether"** — the MiSTer core's SDRAM build, made trustworthy: its controller now reads data on the edge the memory presents it (every off-die read would have been wrong on hardware, and only the new SDRAM timing constraints could see it), the power-up sequence and CAS-latency-3 reads follow the datasheet, the arbiter can no longer return the wrong byte or lose a write, the off-die bitstream builds from a script, both builds are swept and pinned at fitter seed 5, and the co-simulation ladder runs all 165 gates from a clean checkout. Built on **v2.8.3 "Rivet"** — the MiSTer core's reset, area and comments, measured: every reset is released on the clock that uses it and the timing analysis now checks each release, the CPU is about 4% smaller by two exact rewrites the fit report confirmed, four false comments are corrected, and the co-simulation ladder runs from a fresh checkout (164 of its 165 gates; the last needs a hand-built ROM no generator produces). Built on **v2.8.2 "Solder"** — the MiSTer core's on-die RTL, corrected against the oracle and the wiki: an MMC3 IRQ acknowledge is no longer lost to a same-edge counter clock, SNROM's battery RAM obeys its CHR-line enable, the triangle and noise drop a reload landing on a length clock, a `$2002` read leaves the byte it returned on the data bus, and the emulator's MMC1 no longer ignores a reset written on the cycle after another write. **No hardware has run any bitstream.** RustyNES follows [Semantic Versioning 2.0.0](https://semver.org/). @@ -173,7 +173,8 @@ The 1.x line was **additive / off-by-default** — every release stayed byte-ide | **v2.7.6 "Recount"** | The v2.7.5 deletions measured one at a time -- a measurement release between the v2.7.x and v2.8.x audit lines. v2.7.5 bounded six of the core audit's proposals (§3.1 A/B/C, the IMP-06 stores, §3.5b, §3.6) only in one combined ceiling; each was re-run alone, twice, with the A/B/A control. Five are zero; §3.5b had never been reached (the bench ROMs are silent, 0 sweep-mute checks per frame), and on `spritecans.nes` bounds at about 0.2%, with the cheap byte-identical candidate 0.67% slower, so it is rejected. Three of the IMP-06 stores re-wrote fields the fast path's guard already requires, and are now a `debug_assert!` pinned by a unit test (no ROM reaches the violating state). §3.1 B and C are dead work that goes with the v2.9.0 deprecation decision. Also ships #554 (contributed): the macOS buildbot jobs build again, and 32-bit Windows, 32-bit Linux and webOS targets were added. Plan: `to-dos/plans/v2.7.6-recount-plan.md` | | **v2.8.0 "Bulkhead"** | The libretro core stops a fault at its own boundary -- the first release of the v2.8.x audit line, from the libretro audit's FFI-safety findings (L-1.1 to L-1.5, L-2.1, L-2.2, L-2.4), each shown failing in a new C-ABI harness that drives the core as a frontend does. The core was built `panic = "abort"`, so its handlers were dead code; it now unwinds on every supported build path (+0.1% instructions per frame; a direct `cargo build --release` still aborts, and now warns and logs it), and every emulating callback contains a panic, stops the game and keeps the console so RetroArch's memory pointers stay valid. `serialize_size` reserves room for the largest expansion device on both ports (a Zapper no longer breaks every later save) and the reader treats an all-zero tail as padding; unload withdraws the memory maps; the vendored `rust-libretro-sys` writes out `retro_game_info`, so the core loads without `GET_GAME_INFO_EXT`. The save state gains the 2A03 internal data bus (older states still load), and the schema audit now covers the bus. No emulation behaviour change; AccuracyCoin 144/144, nestest 0-diff. Plan: `to-dos/plans/v2.8.0-bulkhead-plan.md` | | **v3.0.1 "Mortar"** | A maintenance release on v3.0.0, plan [`v3.0.1-mortar-plan.md`](to-dos/plans/v3.0.1-mortar-plan.md). Mapper 45's CHR-RAM is unbanked, so *Famicom Yarou Vol.1* draws its menu (T-GA23C-CHRRAM; `EMULATION_EPOCH` 2 refuses v3.0.0 movies and netplay peers). The MiSTer core's dot-0 A12 rule is gated on whether cycle 0 was rendering, found by a new odd-frame stimulus (`mapper4mmc3oddskip080`, plus an /IRQ-rise comparison); new bitstreams at seed 2 / 261007, a release candidate, not hardware-verified. Rust 1.99 and every dependency at its newest, the libretro buildbot included once test pipeline 119614 passed 15/15. Every bot review left unanswered since PR #1 answered (473 verdicts, 80 fixes). The shared Bisqwit NTSC pass recorded as derived; the TriCNES source moved out of the repository. The plan to v4.0.0 written from 29 maintainer decisions | -| **v3.7.0 "Spindle"** (current) | A minor release on v3.6.2, plan [`v3.7.0-plan.md`](to-dos/plans/v3.7.0-plan.md). The MiSTer core gains the Famicom Disk System on its off-die build (Phase F4b, from the NESdev pages and black-box comparison; disk writes persist through the HPS; the Lite build carries none), with two save-engine races fixed on the way. Netplay gains opt-in desync forensics that name the frame, section and byte where two peers first differ, and spectators who join a match from any point through a Durable Object relay carrying only confirmed inputs (protocol 10: v3.6.x peers are refused). The debugger edits PRG/CHR-ROM live, and every edit is recorded as a BPS patch with a RAM-pin sidecar; `rustynes patch-regress` replays a movie on the clean and patched ROM. Both mobile apps gain the 20-band EQ, the Game Genie code database and the per-game correction switch, and iOS box art, a home-screen widget and external-display play (the Swift compiled by the iOS CI Simulator build; no device has run it). A Vs. DualSystem state round-trips under overclock; the three-way CPU-target benchmark found no build faster than the baseline. No frame, sample or bus cycle moved, so the epoch stays 10. | +| **v3.7.0 "Spindle"** | A minor release on v3.6.2, plan [`v3.7.0-plan.md`](to-dos/plans/v3.7.0-plan.md). The MiSTer core gains the Famicom Disk System on its off-die build (Phase F4b, from the NESdev pages and black-box comparison; disk writes persist through the HPS; the Lite build carries none), with two save-engine races fixed on the way. Netplay gains opt-in desync forensics that name the frame, section and byte where two peers first differ, and spectators who join a match from any point through a Durable Object relay carrying only confirmed inputs (protocol 10: v3.6.x peers are refused). The debugger edits PRG/CHR-ROM live, and every edit is recorded as a BPS patch with a RAM-pin sidecar; `rustynes patch-regress` replays a movie on the clean and patched ROM. Both mobile apps gain the 20-band EQ, the Game Genie code database and the per-game correction switch, and iOS box art, a home-screen widget and external-display play (the Swift compiled by the iOS CI Simulator build; no device has run it). A Vs. DualSystem state round-trips under overclock; the three-way CPU-target benchmark found no build faster than the baseline. No frame, sample or bus cycle moved, so the epoch stays 10. | +| **v3.7.1 "Imprint"** (current) | A patch release on v3.7.0, plan [`v3.7.1-plan.md`](to-dos/plans/v3.7.1-plan.md). Licensing made honest and checkable: every file in both repositories carries its copyright holder and licence (REUSE 3.3, a root `REUSE.toml` and `LICENSES/`, linted in CI), the blargg, nestest and aggregated test ROMs are recorded as having no stated licence instead of being called public domain, ares is recorded as ISC with its notice, and the Android and iOS apps and the web site now carry `LICENSE` and `NOTICE` (the libretro core does not yet: `T-LIBRETRO-NOTICES`). The MiSTer core's FDS drive stops at a side's end with `$4030.D6` end of head, stores every byte of a write after a paused read, and waits for ready after a motor restart; disk and battery saves survive a console reset and no longer cross into another cartridge's vdisk; four narrow save and drive edge cases ship as known issues (`T-MISTER-SAVE-XFER-ACROSS-LOAD`, v3.7.2). Each hosted match gets its own spectator id; Rust 1.100; the ladder runs from a job pool. In the emulator no frame, sample or bus cycle moved, so the epoch stays 10; the MiSTer core's FDS drive behaviour changes on purpose, and its off-die save-state fingerprint changed (D4E792FE to 6C9E7051), so v3.7.0 off-die states are refused. | | **v3.6.2 "Latchkey"** | A patch release on v3.6.1, plan [`v3.6.2-plan.md`](to-dos/plans/v3.6.2-plan.md). AccuracyCoin re-synced to upstream `66e87112` (one new test, revisions to three) and passed 147 of 147, with the mirror ROM rebuilt and the epoch fingerprint recording each probe ROM's hash; *Rad Racer*'s stray right-side tiles hidden by a per-game correction that departs from hardware on purpose, on by default for its three dumps and switchable off, recorded in movies (`.rnm` format 8) and netplay (ADR 0051, `T-RADRACER-COHERENT-COPY`), raising the emulation epoch to 10; a first attempt that changed every game's attribute read rested on a wrong diagnosis and is withdrawn in both cores (ADR 0030 withdrawal); on the MiSTer core, the three save-engine region races reported on sibling #72 each confirmed by a stimulus and fixed, with their mutants caught (`T-MISTER-REGION-RACE`), and an MMC5 idle-restart stimulus whose mutant is caught (`T-MISTER-MMC5-IDLE-STIM`). Not hardware-verified | | **v3.6.1 "Threshold"** | A patch release on v3.6.0, plan [`v3.6.1-plan.md`](to-dos/plans/v3.6.1-plan.md). Every dependency at its newest compatible release in one change (superseding seven Dependabot PRs); the MMC5's background-fetch window ended on line 240's idle rule and the vertical-blank notice sent on every frame, in both cores (`T-MMC5-WINDOW-END`); the MMC5 split's first two tiles of a frame taken from row `$5201 + 0`, an oracle defect the MiSTer core's new stimulus found; a TAStudio project bounded by its decoded size (`T-TAS-PROJECT-DECODE-BOUND`); and, on the MiSTer core, save states tied to their region (`T-MISTER-REGION-SAVESTATE`), the MMC5 on PAL's and Dendy's pre-render line (`T-MISTER-PAL-MMC5-PRERENDER`) and a measured fitter-settings comparison (`T-MISTER-FITTER-PRESSURE`). `EMULATION_EPOCH` 9 refuses v3.6.0 movies and netplay peers (nothing recorded moved; raised by v3.5.1's precedent) | | **v3.6.0 "Octave"** | The sixth release of the v3.1 to v4.0 line, plan [`v3.6.0-plan.md`](to-dos/plans/v3.6.0-plan.md); the codename is provisional. The noise channel plays at its documented pitch: every period is CPU cycles between shifts, and RustyNES had counted it in APU cycles since v1.0.0, so the noise ran about an octave low (found by the MiSTer core's PAL work, ledger 9.1 and 9.2; both cores fixed; measured against Nestopia as a black box). NSF files play again at 60 Hz and MMC5 NSFs play at all. `EMULATION_EPOCH` 8 refuses v3.5.1 movies and netplay peers. The libretro core declares Core Options v2, offers float audio, the CPU overclock, the sprite limit and the Vs. DIP switches, and ends every state with a 16-byte record of the emulation options. `rustynes-dap` debugs cc65 and llvm-mos homebrew at source level over DAP or GDB RSP; `rustynes stems` and `rustynes nsf-rip` arrive. Android targets API 37 with non-blocking audio; iOS writes saves durably. The MiSTer core runs PAL and Dendy consoles at full speed (ADR 0050, no board run), and v3.5.x MiSTer states are refused. | diff --git a/android/app/build.gradle.kts b/android/app/build.gradle.kts index 533cc0ccb..d8b0b23f1 100644 --- a/android/app/build.gradle.kts +++ b/android/app/build.gradle.kts @@ -119,8 +119,8 @@ android { // `scripts/release-automation/bump_release.py` from now on, starting // with the 3.0.0 cut. versionCode = MAJOR * 10000 + MINOR * 100 + // PATCH, so 20909 still rises past 20004. - versionCode = 30700 - versionName = "3.7.0" + versionCode = 30701 + versionName = "3.7.1" // No abiFilters here — set per buildType so release ships arm64 only // while debug keeps x86_64 for the emulator. // PLAY_BUILD is set per-flavor below (`false` for `foss`, `true` for `play`), diff --git a/crates/rustynes-cosim/Cargo.lock b/crates/rustynes-cosim/Cargo.lock index 1255e0110..6ac91fca4 100644 --- a/crates/rustynes-cosim/Cargo.lock +++ b/crates/rustynes-cosim/Cargo.lock @@ -98,7 +98,7 @@ dependencies = [ [[package]] name = "rustynes-apu" -version = "3.7.0" +version = "3.7.1" dependencies = [ "bitflags", "libm", @@ -107,7 +107,7 @@ dependencies = [ [[package]] name = "rustynes-core" -version = "3.7.0" +version = "3.7.1" dependencies = [ "bitflags", "lz4_flex", @@ -121,7 +121,7 @@ dependencies = [ [[package]] name = "rustynes-cosim" -version = "3.7.0" +version = "3.7.1" dependencies = [ "rustynes-core", "sha2", @@ -129,7 +129,7 @@ dependencies = [ [[package]] name = "rustynes-cpu" -version = "3.7.0" +version = "3.7.1" dependencies = [ "bitflags", "thiserror", @@ -137,7 +137,7 @@ dependencies = [ [[package]] name = "rustynes-mappers" -version = "3.7.0" +version = "3.7.1" dependencies = [ "bitflags", "rustynes-apu", @@ -146,7 +146,7 @@ dependencies = [ [[package]] name = "rustynes-ppu" -version = "3.7.0" +version = "3.7.1" dependencies = [ "bitflags", "libm", diff --git a/crates/rustynes-cosim/Cargo.toml b/crates/rustynes-cosim/Cargo.toml index 184d22e3b..3e2b8e087 100644 --- a/crates/rustynes-cosim/Cargo.toml +++ b/crates/rustynes-cosim/Cargo.toml @@ -8,7 +8,7 @@ description = "RustyNES as a co-simulation oracle for an external HDL device-und # The duplication is PINNED, not merely noticed: `cosim_manifest_audit.rs` in # `rustynes-test-harness` asserts these values still match the workspace's, so # drift fails a test instead of accumulating quietly. -version = "3.7.0" +version = "3.7.1" edition = "2024" rust-version = "1.100" license = "GPL-3.0-or-later" diff --git a/crates/rustynes-libretro/rustynes_libretro.info b/crates/rustynes-libretro/rustynes_libretro.info index 29743c241..ee4e08c5e 100644 --- a/crates/rustynes-libretro/rustynes_libretro.info +++ b/crates/rustynes-libretro/rustynes_libretro.info @@ -5,7 +5,7 @@ supported_extensions = "nes|fds|unf|unif" corename = "RustyNES" license = "GPLv3+" permissions = "" -display_version = "v3.7.0" +display_version = "v3.7.1" categories = "Emulator" # Hardware Information diff --git a/docs/SALVAGE_MANIFEST.md b/docs/SALVAGE_MANIFEST.md index e990da3f9..ae4a05ef4 100644 --- a/docs/SALVAGE_MANIFEST.md +++ b/docs/SALVAGE_MANIFEST.md @@ -733,3 +733,17 @@ which belong to other projects; the zellij log and harness cache-state JSON. - **Not taken**: `v37/` (350 MB, in use: the MiSTer FDS agent's ladder logs, briefs and commit drafts; it goes at the v3.7.0 release cleanup); `v362/ac-src/`, a clean clone of upstream AccuracyCoin at `66e8711` with no local changes, regenerable from GitHub; and this run's own dry-run report and plan. - **Outside the scratch, by the maintainer's choice: nothing.** The dry run found only regenerable leftovers: 5 Kotlin daemon logs, 52 `rustynes-atomic-*` unit-test temp directories, `/tmp/RustyNES` (14 more copies of the synthetic test FDS BIOS and two Vs. *Balloon Fight* screenshots, which are commercial-ROM output and must never be committed) and about 1,900 weak type-only matches (compiler `.s` temporaries, pytest directories). 5,874 matches in other projects' agent scratch were left alone. The 12 files under the workspace-root slug that mention RustyNES belong to two other sessions' workspace work and only name it in passing. - **Then, before a reboot the same day:** the maintainer paused all work, so `v37/` was no longer in use. Its 350 MB (the v3.7.0 agent briefs, the MiSTer FDS agent's ladder logs and commit drafts, the CPU-target benchmark logs) was copied with `cp -a` to the same destination, beside this run's dry-run report and plan. `diff -rq` against the source showed no difference, and `/tmp` was then wiped by the reboot. + +## Copy 2026-11-14 (by hand, during v3.7.1) + +- Source: this session's scratchpad (`/tmp/claude-/-home--Code-OSS-Public-Projects-RustyNES/f63c2db0-35e3-4aad-8889-12b0db5b7fc3/scratchpad/`), 931 MB: the v3.7.0 re-release and v3.7.1 working files (`v37/`, `v37w4b/`, `r1100/`, `poolsmoke/`, `wrangler-dry/` and smaller). Scope set by the maintainer: the curated set below. +- Destination: `salvaged/tmp-scratch/f63c2db0/scratchpad/`, same relative paths (gitignored), by `rsync -a --no-links --backup --suffix=.pre-20261114`. A COPY: the release still uses the scratch. +- **Copied**: 1,065 files, 136 MB, each `cmp`-checked against its source afterwards. They include the v3.7.1 release-ladder logs (`v37w4b/rel371/{off,on}.log`: off-die 427/0/12, on-die 356/0/4), the ladder-pool equality logs (`v37w4b/eq/`), the seed-sweep logs, the Rust 1.100 gate scripts and logs (`r1100/`), the review replies and PR bodies, and the `.preedit` / `.premut` snapshots. Three existing destination files differed (`msg-docs.txt`, `pr-body.md`, `r5-summary.md`); the older versions are kept as `*.pre-20261114`. `--no-links` skipped one symlink (`v37w4b/ci/shimtest/nonode/cargo`, a test shim) and so cannot repeat the 2026-11-04 self-link trap. +- **Not taken (regenerable)**: `v37w4b/mkvenv/` (a Python venv, 149 MB), `v37w4b/site/` (a built MkDocs site), `v37w4b/deps/` (downloaded tools, among them `trunk-0.22.1`, already past the 10-day mark), `linasset/` (the published v3.7.0 Linux binary), `v37/android-ndk/` (190 MB), `v37w4b/ci/copt/.oracle-pinned/` (a clone of the oracle), and the FDS golden exports in `v37w4b/fdsfix/{rdy,fg,gold}/` (350 MB, which the oracle exporter can regenerate). +- Outside the scratch: nothing. The dry run found 927 matches in other projects' agent scratch (VeridianOS 715, MosquitoMagnet-PiHat 173, hekate 24, and 11 under the workspace-root slug, which are other sessions' `opendeck` and `ffctl` work) and left them alone. + +## Evidence 2026-11-14: `salvaged/evidence/v3.7.1-fds-side-end/` (written in place, during v3.7.1) + +- Written directly by the sibling #77 agent while measuring the oracle's FDS end of side; no `/tmp` source. 97 files, 223 MB, gitignored. +- `p14/`: the `fdsprobe551` (read past the end) and `fdsprobe552` (write past the end) images, their probe-built BIOS stubs, the MiSTer core's logs and RAM dumps, and the decoders (`dec.py`, `dec2.py`). `dense/`: the dense-probe images (`mkfds_dense.py`) and the oracle runs (`od551*`) that showed the oracle's side ends about 100 transfers (read) / 200 (write) after the last original block, with `$4030.D6` rising. This is the evidence behind ledger 3.138, the maintainer's "bound fix + D6" choice and `T-MISTER-FDS-RAW-STREAM`. +- The BIOS files are generated probe stubs (md5 prefixes 1ad14360, d3266154, 217c9eee, 55c698cb), not Nintendo's `disksys.rom` (ca30b50f). Nothing here is commercial-ROM output. diff --git a/docs/STATUS.md b/docs/STATUS.md index 8da635613..9ce7e3e19 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -1,6 +1,6 @@ # RustyNES — Project Status Matrix -> **Current release: v3.7.0** (2026-11-10) — **"Spindle"**, 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. Built on **v2.9.5 "Caliper"** (2026-09-29) — every open accuracy item measured, then fixed or closed: four fixes red first (the `apu_test` frame-counter coincidence, the composite 2C02 scanline-0 sprite glitch, OAM DMA filling the PPU I/O latch, KS7032 at `$6000`), 49 unreferenced test ROMs gated, the MMC3 M2-edge filter lever tried and refuted, and a save-state epoch (`PPU_SNAPSHOT_VERSION` 11). Built on **v2.9.4 "Plumb"** (2026-09-29) — the records made true, and CI made to run what it only linted: v3.0.0 decided as the API major with a release-candidate core (ADR 0043), CI now running 63 feature-gated tests it never ran, the eight fuzz targets and a 70% line-coverage floor, the mapper tiers, store status and deferred-features catalogue corrected against the code, and the OAM-decay model recorded as derived from Mesen2. Built on **v2.9.3 "Handset"** (2026-09-29) — the old review threads closed and the mobile run prepared: every dependency moved to its newest release (egui 0.36 with wgpu 30, rcheevos 12.5.0), all 244 review threads left unanswered on PRs #7-#97 answered and the ten findings that still held fixed (Action 53 multicarts rebuilt to the NESdev spec, and a ROM header editor that no longer rewrites bytes you did not edit or saves mappers from 16 up as the wrong mapper), and the Android unit tests and the iOS renderer added to CI. The mobile device runs and the SuperStation One board session move after v3.0.0 (maintainer, 2026-09-29). Built on **v2.9.2 "Candidate"** (2026-09-28) — the full audit acted on, and the release-candidate pair: all 32 findings of a fifth audit have a verdict and 16 are fixed, save states keep the cartridge RAM of twelve board families they used to drop, the MiSTer core no longer loses an NMI raised inside a DMA, and both bitstreams are cut for the SuperStation One session. Built on **v2.9.1 "Hone"** (2026-09-27) — what the optimisation bars measure, and what clears them: the A/B tool had been timing the old code on both sides of every code comparison and is fixed, a two-screen Vs. cabinet saves about 9x faster, the off-die MiSTer build keeps CHR in its own SDRAM bank, and both bitstreams are pinned at fitter seed 2 and rebuild byte-identically. Built on **v2.9.0 "Survey"** (2026-09-26) — every audit re-checked, and the SuperStation One surveyed: a Power Cycle no longer erases your save, the off-die MiSTer build boots without the menu core, and 39 new audit findings are fixed or dispositioned. Built on **v2.8.4 "Tether"** (2026-09-26) — the MiSTer core's SDRAM build, made trustworthy: its controller now reads data on the edge the memory presents it (every off-die read would have been wrong on hardware, and only the new SDRAM timing constraints could see it), the power-up sequence and CAS-latency-3 reads follow the datasheet, the arbiter can no longer return the wrong byte or lose a write, the off-die bitstream builds from a script, both builds are swept and pinned at fitter seed 5, and the co-simulation ladder runs all 165 gates from a clean checkout. Built on **v2.8.3 "Rivet"** (2026-09-25) — the MiSTer core's reset, area and comments, measured: every reset is released on the clock that uses it and the timing analysis now checks each release, the CPU is about 4% smaller by two exact rewrites the fit report confirmed, four false comments are corrected, and the co-simulation ladder runs from a fresh checkout (164 of its 165 gates; the last needs a hand-built ROM no generator produces). Built on **v2.8.2 "Solder"** (2026-09-25) — the MiSTer core's on-die RTL, corrected against the oracle and the wiki: an MMC3 IRQ acknowledge is no longer lost to a same-edge counter clock, SNROM's battery RAM obeys its CHR-line enable, the triangle and noise drop a reload landing on a length clock, a `$2002` read leaves the byte it returned on the data bus, and the emulator's MMC1 no longer ignores a reset written on the cycle after another write. Built on **v2.8.1 "Gasket"** (2026-09-25) — the libretro core fits the frontends around it: four-player games work through a Four Score option, a controller works again after its port leaves the Zapper, RetroArch no longer reads past the core's input-descriptor list, expansion audio no longer clips, the core declares UNIF images, and the Makefile honours PREFIX, platform=win, DEBUG and CARGO_TARGET_DIR. Built on **v2.8.0 "Bulkhead"** (2026-09-25) — the libretro core stops a fault at its own boundary: an internal error no longer closes RetroArch, save states survive plugging in a Zapper, closing a game withdraws its memory maps, the core loads from any libretro frontend, and the save state now carries the 2A03 internal data bus. Built on **v2.7.6 "Recount"** (2026-09-24) — the v2.7.5 deletions measured one at a time: the six performance proposals v2.7.5 bounded only together were each measured alone, where the benchmarks reach them: five are zero, and the sixth, the pulse sweep-mute check, bounds at about 0.2%, and the cheap byte-identical way to take it measured slower; the fast render path now asserts a rendering-history invariant it used to re-write; and the libretro buildbot builds macOS again and gains 32-bit Windows, 32-bit Linux and webOS targets. Built on **v2.7.5 "Tally"** (2026-09-24) — every audit claim closed with a measurement or a reason: the core audit's twelve performance proposals were closed, eleven of them by measurement, and one adopted (the audio buffer keeps its capacity between frames); 18 dead bus methods and the unused ApuBus trait are deprecated; and the core and frontend ledgers have no open row. Built on **v2.7.4 "Pocket"** (2026-09-24) — the mobile apps survive what a phone does to them: an internal error no longer closes the Android or iOS app, battery saves persist on both, the apps pause and give up audio when they should, and saves are written so a dying phone keeps the last good one. Built on **v2.7.3 "Hearth"** (2026-09-23) — the desktop and web frontends keep what they are given: battery saves persist on the desktop, a Lua script can no longer hang or exhaust the emulator, script HTTP cannot reach local services by default, and audio survives a device change. Built on **v2.7.2 "Bankroll"** (2026-09-23) — cartridge memory, every bank a cartridge has and nothing it has not: MMC1 reaches SUROM / SXROM, MMC5 banks its PRG-RAM, Namco 163 selects nametables, and `$6000-$7FFF` reads open bus where a board has nothing there. Built on **v2.7.1 "Keepsake"** (2026-09-23) — six cartridge boards now hand RetroArch their battery save instead of an empty one, every user file the frontend writes is written atomically, and three mapper files are now recorded as derived from Mesen2 and puNES. Built on **v2.7.0 "Palisade"** (2026-09-23) — a corrupt or hand-edited save state now fails at restore with a typed error instead of crashing the emulator one tick later, pulse 1 no longer mutes on the `$4001 = $08` sweep idiom, and the save-state fuzz target can finally reach what it exists to find. Built on **v2.6.23 "Pulse"** (2026-09-20) — the access does not increment, it pulses the load already there. A `$2007` access during rendering pulses the rendering pipeline's existing load rather than computing a private increment, and resolving against that same value is what closed the CHR-during-rendering divergence in the MiSTer sibling: `chrram-live` went from **32,861 of 61,440 differing pixels**, red for eight releases, to "All 61440 pixels match", and `chrram-fetch` from 21,941 to 18. Eleven prior variants had been measured correctly and the conclusion drawn from them was wrong — they swept what the `$2007` arm computes and never what it computes it from. The emulation core is unchanged, so **AccuracyCoin 144/144 and nestest 0-diff hold by construction** and were re-run anyway. The bitstream is re-cut at fitter seed 4 (+0.421 ns setup / +0.112 ns hold) and **no hardware has run it**. The board session is now **v2.9.2** and the hardware-verified core **v3.0.0**, after three audit lines ([ADR 0041](adr/0041-hardware-release-is-v3.0.0.md)). Built on **v2.6.22 "Rigging"** — the instruments for the board, built before the board. **No hardware has run any bitstream**; the session with the board (then planned as "Shakedown"; since ADR 0041, v2.9.2) is the hardware half and this is the non-hardware half of it, cut separately so that name keeps meaning what it says. AccuracyCoin now reads back from hardware as BYTES rather than as a photograph — a mirror ROM copies its result vector into the battery-backed save window, with a byte budget that proves the patch moved nothing and a simulation control that proves it changed no answer. The catalog turned out to have **149 rows and 144 results**: five `Power On State` rows share upstream's omit-sentinel, and counting them made the headline a function of *when the run was sampled*. **144/144 and nestest 0-diff are unchanged** — the count stopped depending on the sampling instant. And the `46199ae4` re-sync turned out to have been half-done: three goldens described a ROM no longer in the tree, which no gate could see because `rom_sha256` was written into every manifest and compared to nothing. Built on **v2.6.21 "Steward"** — the board arrives, and the core is not ready for it. Battery saves exist for the first time; the CHR-during-rendering gate the retrospective audit asked for is added and is **RED at 32,861 of 61,440 pixels**, with the obvious fix measured insufficient at 715 recovered; two gates existed that nothing ran; and the deploy loop the runbook prescribed was built, which found two defects in its own spec. The emulation core is unchanged, so **AccuracyCoin 144/144 and nestest 0-diff hold by construction**. Built on **v2.6.20 "Telltale"** — the counter had no reader, and two knobs turned out to be one decision. The FPGA core's OAM2 address counter was write-only for a release, so `$2004`'s post-fetch rest value was a hardcoded index 0; making it observable took the DUT to **AccuracyCoin 149 of 149** and the co-simulation ladder to **150 of 150, 0 failed**. Restoring the increment window v2.6.19 had narrowed then broke sprite rendering by six pixels, because the window and the deleted dot-257 latch are ONE decision with two self-consistent answers and only one of them is the hardware's. The shipped configuration restores the latch: window 256, the dot-257 freeze latch back and consumed by sprite fetch, and `$2004` reading the live counter. A CHR-RAM write gate was added. **v2.6.21 corrects this sentence: it did NOT close the coverage the audit named.** The audit named writes *while rendering is enabled*, and PROGRAM53 writes with `PPUMASK = 0` and renders afterwards. The real case is gated at v2.6.21 and is RED -- 32,861 of 61,440 pixels. The emulation core is unchanged, so **144/144 and nestest 0-diff hold by construction**. Built on **v2.6.19 "Accession"** — the DUT absorbs two releases of oracle behaviour, and the seed rule catches something for the first time. The FPGA core implements the OAM2 address counter it never had and stops acting on a `$2001` change that lands during dot 256 -- AccuracyCoin on the DUT **148 of 149**, the ladder **147 of 147**. The fitter pin is re-derived over ten seeds and stays at 3. (The contemporaneous claim that seed 1 stopped closing is withdrawn -- that sweep recompiled in place and was order-dependent; seed 1 closes, and seed 8 is the one that does not.) The emulation core is unchanged, so **AccuracyCoin 144/144 and nestest 0-diff hold by construction**. Built on **v2.6.18** (2026-09-12) — **"Errata"**, the recorded cause was wrong in three ways, and the last AccuracyCoin entry closes at 144/144 -- a `$2001` change during dot N must not act on dot N, at the dot-256 vertical increment and the dot-339 OAM2 reset. Built on **v2.6.17** (2026-09-11) — **"Terminus"**, the accuracy battery grows to 144 assigned tests and one of the new ones names the dots a write lands on -- this core is two dots early, measured twice on two independent `$2001` writes, and moving it is refuted by the gate this version wrote in advance, so the documented compensation stays and 143 of 144 ships. Built on **v2.6.16 "Interlock"** (2026-09-04) — the arbiter's numbers describe a stimulus, not the console -- and the console meets the CPU's deadline at zero margin, on every one of 240,303 requests, where the gate said it missed by four. Built on **v2.6.15 "Warrant"** (2026-09-04) — the claims v2.7.0 will make become checkable, and the instrument pays the oracle back. Built on **v2.6.14 "Docket"** (2026-09-03) — the submission checklist becomes auditable, and auditing it finds five boxes already true, two ticked on evidence that expired, and one that could never have been ticked honestly. v2.7.0 IS the submission, so the list in `to-dos/mister/contribution-checklist.md` decides whether the core is ready -- and it had 30 boxes, 16 unticked, and FOURTEEN OF THOSE SIXTEEN saying nothing at all about why. That ambiguity is the defect: an unticked box with no reason cannot be told apart from work outstanding, work blocked outside this repository, and WORK ALREADY DONE AND NEVER TICKED, and the third case occurred five times -- the provenance CI job, the SPDX sweep, the firewall statement, the AccuracyCoin vector and the preservation-value case were all true and all unticked, so the list reported the project as further from submission than it is by a fifth of its own length. ONE BOX COULD NEVER HAVE BEEN TICKED HONESTLY: it asked that `docs/provenance.md` state "that no NES core was ever opened", and that same document's section Do not self-certify forbids exactly that class of finished claim, so satisfying the box required writing the one sentence the provenance rules exist to prevent -- a wrong requirement rather than a missing tick, and only reading every item found it. RE-MEASURING THE TICKED HALF found two more, which is v2.6.9's lesson in a different document: `RustyNES.sdc` still said "there is exactly one core clock", true of v2.6.3 and false since v2.6.13, which added a 4x SDRAM clock and a phase-shifted pin clock that the shipped timing report names alongside it; and the `.qsf` entry said all 109 pin assignments come from `sys/sys.tcl`, where 109 is what that script supplies before stopping short of the I/O board, so a core must also source one of two 36-assignment variants -- 145 in total, from two scripts. THE ALARMING READING OF THE FIRST WAS CHECKED BEFORE IT WAS WRITTEN DOWN: it looks as though the framework's `set_clock_groups -exclusive` might be cutting the console-to-SDRAM crossing and leaving ADR 0039's safety argument unfalsifiable, and it is not -- exclusive cuts paths BETWEEN groups, all three outputs match one glob, and v2.6.13's own -24.769 ns measurement of that crossing is only observable because those paths are analysed. THE NAMING DIVERGENCE IS MEASURED RATHER THAN PARAPHRASED, from `Main_MiSTer/file_io.cpp` instead of the wiki: `get_display_name` searches for the literal underscore-two-zero and TRUNCATES THE DISPLAY NAME THERE, taking the rest as a datecode, and `DirentComp` groups by that truncated name -- so a version-named bitstream makes every release a SEPARATE CORE ENTRY, named for the version rather than the core, ordered alphabetically, which puts v2.6.9 after v2.6.13. The fix is one line and is NOT taken here, because version-naming is a maintainer decision with a stated rationale and reversing it is not an audit's call. THE TASK BOARD HAD THE SAME DEFECT AND ONE ROW WORSE: four delivered items never ticked, a hardware row still naming a version seven releases past, and an SDRAM row whose precondition -- "after a board exists" -- v2.6.13 simply did not follow, having accepted the controller against a behavioural model written from the datasheet instead; that is rung 7's own recorded lesson repeating one row below where it is written, since the blocker applied to hardware ACCEPTANCE rather than to building the thing. A CLAIM v2.6.13 SHIPPED IS RETRACTED: answering a review finding, I wrote that MMC1 was the sixth approved family and not yet implemented, and the cartridge decodes mapper 1 at three sites with a registered gate green since rung 7 opened -- asserted from memory inside a reply correcting somebody else's reading of the same line. The gate that keeps all this true asserts a SHAPE rather than a judgement and is demonstrated by five mutations, one of which proves the continuation-line folding load-bearing by producing nine false violations without it. The bitstream is BYTE-IDENTICAL to v2.6.13's, which is the point: the only sibling change is a comment, and an identical artifact demonstrates it. The emulation core is unchanged, so AccuracyCoin 141/141 and nestest 0-diff hold by construction. Built on **v2.6.13 "Slack"** (2026-09-03) — the cartridge outgrows the die, and three consumers want the same bus. An SDR SDRAM controller, a behavioural part model, a four-way arbiter and a console bridge, all written from the AS4C32M16SB-7 datasheet revision 1.4 -- no third-party controller read, ADR 0037 applying. The budget the previous step worked to was a single figure read off the fetch structure and never measured; `nes_top`'s `CHR_LAT` sweep asks the console directly, and there are THREE answers: a background or sprite fetch tolerates 28 cycles and uses 17, the PPUDATA data port tolerates 8, and the CPU sampling at mc7 has 24 -- four cycles of every budget going to the console-domain crossing, which is not optional, because publishing a runtime modulo combinationally into an 11.64 ns domain costs -24.769 ns of setup. The PPUDATA port could never fit, half its budget being the crossing, so it leaves the shared bus entirely: `ppu2c02` gains `BUFFER_HANDSHAKE` and fills its read buffer through a port of its own on the arbiter, affordable because the CPU does not read that buffer until its next PPUDATA access. THAT FIX SHIPPED A DEFECT ONLY A BANKED CARTRIDGE COULD SEE -- the request carried the RAW fourteen bits the PPU presents, which is right by coincidence on NROM because the mapper's translation is the identity there, and reads BANK ZERO on everything else; `ppu-misc-2007-stress` passed off-die throughout while the two CNROM gates read a zero byte where the oracle reads one, one and two. The fix REMOVES the address rather than correcting it: `cart.sv` already publishes the translation for the fetch path, so the request carries none and there is one source of truth for where CHR lives instead of two that agree only on NROM. A DELETION WAS THEN REFUTED BY ONE CYCLE: with the address fixed, a control issuing at a flat +7 passed both gates, which read as the anti-contention deferral buying nothing, so it was removed -- and the deployed code issued at +6, and both gates failed again. The control and the code differed by a single cycle, which is the measurement of how thin the CPU's off-die deadline is and the concrete argument for scheduling the bus rather than arbitrating it. Two INFERRED LATCHES that Verilator cannot see: `ppu2c02` assigned two signals only under `BUFFER_HANDSHAKE`, so in the shipped on-die build the only assignment either reached was the reset branch, and a variable holding its previous value on every live path is a latch -- Quartus said so twice while the lint gate stayed green, and the comment beside them asserted the defect as a virtue ("outside BUFFER_HANDSHAKE neither signal ever moves", which is true and is exactly the condition). And a defect in the HARNESS: `USE_SDRAM` reaches Verilator as `-G` rather than as a file, so make ran ONE binary under both configurations' names and a log labelled on-die was the off-die build, reproducing the off-die failures exactly -- closed with a stamp-file prerequisite, demonstrated by mutation. THE OPEN ROW: accesses no longer auto-precharge, a hit costs 6 cycles against 10 for a miss, tRAS's 120 us MAXIMUM is respected by an early close in idle, and two defects came out of the rewrite -- re-entering idle with the request still asserted issued every access TWICE, and subtracting one from CAS the way the other waits are computed broke every read to all zeroes, CAS being "data appears at cycle N" rather than a command-to-command gap. Two MiSTer tickets close: `sdram_sz` is consumed VALIDITY BIT FIRST, so `absent` is deliberately not `!present` and a power-on all zeroes cannot read as "no board" (gated exhaustively over all 65,536 values), and `status_menumask` is computed rather than tied off, greying Reset whenever the console is already held in reset. OFF THE DIE THE CONSOLE PASSES 142 OF 142, every gate the on-die build passes, with better timing margin and 384 fewer M10K blocks -- and it still SHIPS ON the die, because an off-die core cannot run at all without the SDRAM add-on while rung 7's five mapper families fit on the die at 468 of 553 blocks. The emulation core is unchanged, so AccuracyCoin 141/141 and nestest 0-diff hold by construction. Built on **v2.6.12 "Groundwork"** (2026-09-02) — the bitstream was an NROM-only console. Rung 7 landed five mapper families and 142 co-simulation gates verify them, and the layer that turns that RTL into a bitstream was never told: `rtl/emu.sv` left `cart_mapper`, `cart_prg_16k_banks` and `cart_chr_8k_banks` unconnected, so Quartus tied all three to GND -- mapper 0 for EVERY cartridge, `prg_8k_count = 0` collapsing PRG to an 8 KiB window, and CHR forced to RAM. The declared 256 KiB PRG and 128 KiB CHR were implemented as 8 KiB each; connecting three wires takes block memory from 666,061 to 3,680,717 bits and timing still closes at all four corners. NOTHING COULD HAVE CAUGHT IT: simulation cannot, because `emu.sv` is not in the testbench file list and the harness drives those ports itself, so all 142 gates exercised a correctly-configured cartridge; and Quartus DID say so three times, in messages that cite an INSTANCE path rather than a file and are absent from the "0 errors, N warnings" tally, so the existing checker read 0 of 125. Two gates close that -- one fails on an unconnected pin of any module this repository declares, the other pins the warning SET rather than its count -- and both are demonstrated to fail by mutation. The `hps_io` tie-off audit that followed raised nine `T-MISTER-*` tickets, and annotating each with a blocker turned "none of these landed" into a measurement: not one is blocked on EFFORT, so the list is the rung-6 agenda rather than a backlog. `T-MISTER-SAVE` was attempted and refuted -- every save route terminates in `hps_io`, which no gate here instantiates. The emulation core is unchanged, so AccuracyCoin 141/141 and nestest 0-diff hold by construction. Built on **v2.6.11 "Exposure"** (2026-09-02) — a picture is a gate the ladder did not have. All 141 co-simulation gates THEN IN THE SUITE were green (it ends this release at 142, the one it added) and TWO OF SIX commercial games rendered wrong -- a CHR-RAM write was taking the shared-pin composite address built for FETCHES instead of `v`, so the layout was right and the tiles were scrambled. The split is exactly CHR-ROM against CHR-RAM, which named the mechanism before any tracing, and a CONTROL says it is not v2.6.10's regression: the pre-M10K-fix RTL differs by the IDENTICAL 16,565 pixels, so the defect dates from the cartridge landing in v2.6.9. It was not UNREACHED -- the DUT asserts `chr_wr` 9,600 times in the Battletoads run -- it was UNCOMPARED: only THREE of the 141 gates compare a framebuffer, all three ship CHR-ROM, every other gate is CPU-side, and AccuracyCoin, the widest gate in the suite, is CHR-ROM too. The rung-7 gates' own comment says what they are for -- "these gates are about BANKING and nothing else" -- and it was accurate, and it was the whole coverage. Six commercial titles now render byte-identically to the oracle over all 61,440 pixels, published as a montage built by a script that REFUSES to publish a tile that differs from the oracle. The v2.6.10 bitstream carries the defect and a published version is immutable, so the corrected `.rbf` ships here. The same release finds EIGHT release leads describing v2.6.10 with v2.6.9's summary, and v2.6.9 gone from the lineage entirely, with `docs/STATUS.md` naming v2.6.10 under the codename "Abeyance" -- every existing check passing CORRECTLY, because they pin the version TOKEN and the token was right. Prose cannot be audited; an ORDERING can, so two gates are added and both are demonstrated to fail by mutation. The emulation core is unchanged, so AccuracyCoin 141/141 and nestest 0-diff hold by construction. Rung 6 does NOT close -- no DE10-Nano and no SuperStation One are attached to this machine, confirmed by checking rather than assumed. Built on **v2.6.10 "Inference"** (2026-09-01) — the cartridge meets the synthesiser. Five cartridge boards verified across 141 co-simulation gates had **never been through Quartus**, and Analysis & Synthesis refused the design: `chr` was written from TWO `always_ff` blocks, which cannot infer as one M10K, so 128 KB of CHR stayed in flip-flops -- **1,048,576 registers against roughly 166,000**. Simulation cannot ask this question: Verilator accepts both forms without complaint. It is v2.6.6's finding one layer out -- that release established that an M10K read is REGISTERED, this one that a correctly registered memory still will not infer with two writers. The fitter was also throttling itself under Auto Fit while the `.qsf` carried no optimisation assignments at all: at full effort **all six seeds close** where two had failed, so the effort settings move the whole distribution across zero and the seed only picks where in it you land -- and the project had been pinned to seed 4, the WORST of the six. Pinned at seed 3, +0.531 ns setup and +0.099 ns hold, byte-identical across two independent compiles. The bitstream v2.6.9 could not produce ships here. Built on **v2.6.9 "Abeyance"** (2026-08-31) — an exclusion hides improvement as well as regression, and both denied co-simulation streams close. The larger one was never the console: `apuconflict039` had been carried for seven releases as a declared diagnostic whose bus surface "carries nine divergences BY DESIGN", and the nine were a defect in the HARNESS -- on a cycle the CPU is held, the testbench built its record's bus data from a stale local rather than from the RTL's own latch. Taking it from the latch makes the stream IDENTICAL on all 357,361 overlapping cycles and all 88 checkpoints, and the local is now dead and deleted. The phrase "by design" is what stopped anyone re-checking it, because it reads as a property of the thing under test when it was a property of the instrument reading it. The other stream differs on EXACTLY ONE cycle, a documented and attributed OAM-corruption asymmetry -- and carrying that needed an instrument the suite did not have, because the PLANNED mechanism was refuted by its own mutation pass: an allowance by checkpoint index cannot work on a rolling hash, since one divergent cycle poisons every checkpoint after it, so allowing the first differing window simply moved the failure to the next one and allowing the rest is the all-or-nothing deny it was meant to replace. A per-cycle nine-field comparator with a scoped allowance costs ONE cycle of coverage instead of seventy-one checkpoints -- 357,360 of 357,361, against nothing at all before -- and it fails BOTH ways, so a DUT that improves cannot leave a stale allowance quietly hiding coverage; six mutations confirm it, including a cycle outside the compared window being REFUSED rather than allowed to match nothing. The emulation core is unchanged, so AccuracyCoin 141/141 and nestest 0-diff hold by construction and were re-run anyway. Rung 6 does NOT close -- no DE10-Nano and no SuperStation One are attached to this machine, confirmed by checking rather than assumed. Built on **v2.6.8 "Arrears"** (2026-08-31) — the gates the previous release fixed and never widened. A deny list is an assertion about the THING UNDER TEST, so v2.6.7 changing both the DUT and the harness re-opened every exclusion -- and nothing re-measured one. FOUR of the six denied checkpoint streams were passing (`irqlat048`, `ppuvbl023`, `ppuvbl024`, `ppuvbl025`), and THREE of those were not run by the suite at all, so removing them from the deny list was INERT until they were also iterated. The nestest gate compared 265,000 cycles against a 5,062,688-cycle golden -- correct while caveat C6 was open, left behind the moment it closed -- and all 5,062,680 overlapping cycles now match, with the window DERIVED from the manifest. CAVEAT C4 CLOSES by demonstration: nestest raises `nmi_line` on 3,592 cycles and had no nine-field comparison at all, so wiring it makes an `o.nmi_line` mutation CAUGHT at checkpoint 28 of 1,237 while the bus gate passes the identical run. Suite 128 passed, 0 failed, 0 skipped; nine-field comparisons 51 -> 57. The emulation core is unchanged, so AccuracyCoin 141/141 and nestest 0-diff hold by construction. Rung 6 does NOT close -- no board is attached, confirmed by checking. Built on **v2.6.7 "Detent"** (2026-08-30) — the bitstream becomes a published release artifact and a one-cycle disagreement is pinned to the cycle it happens on. Every release from here ships a `.rbf` -- committed to the sibling's `releases/` and attached to the GitHub release on BOTH repositories -- reversing v2.6.6, which produced one and withheld it because no hardware had run it: the MiSTer distribution mechanism reads that path out of the REPOSITORY, so an empty `releases/` describes an undistributable core rather than a cautious one, and the caution moves from an absence into a disclosure naming what the ladder cannot reach by construction (the PPU gate compares the pre-palette index and the APU gate per-channel integer levels, so the palette, the video timing constants, the audio absolute level and its band-limiting all sit downstream of every gate). The build is REPRODUCIBLE and that is now measured rather than argued -- a from-scratch compile and an incremental one produce a byte-identical bitstream -- which is also how v2.6.6's published slack figures came to be WITHDRAWN: no corner of a clean rebuild reproduces them, the innocent explanation (a different timing corner) was checked first and refuted, and the correct pair is +0.108 ns setup and +0.042 ns hold at the binding corner. THE RELEASE GATE WAS READING THE WRONG CORNER -- Slow 100C is not the binding one on this design, so a bitstream failing at Slow -40C would have passed while the gate reported three times the real margin -- and the checker that reads it was wrong twice before mutation found both: it first extracted ZERO rows from both summary tables and reported that as "no negative slack", then, once fixed, reported FOURTEEN clocks from a report emptied of its data, having run past the closing rule into the next tables. Caveat C2 splits in two. The first residual was a TRACE OBSERVATION POINT -- the harness built its record after eight of a CPU cycle's twelve master clocks while the oracle reads at end-of-cycle, and the frame-counter interrupt asserts on the final edge -- and closing it took checkpoint comparisons from 3 to 11 and failures at one checkpoint from 30 to 3. The second is REAL, and the FIRST fix for it was REFUTED in a way that found the right one: moving all four effects of the write one cycle later to match the oracle drops blargg from 11/11 to 4 of 11, one of the seven being the ROM written to probe exactly that timing. Read as a measurement that PROVES the sequencer's maturation is correctly placed, which leaves only the other effects the same write schedules -- so separating ONLY the interrupt clear lands it at write+3, the documented cycle, while the frame counter's zeroing stays put. Checkpoint streams go from 11 identical to 52 of 58 and the suite from 87 to 122, with blargg still 11/11 and the bus still matching on all 2,680,239 overlapping cycles. The checkpoint gate is registered over 51 comparisons and STATES ITS BLIND SPOT: not one gated golden ever raises an NMI, so it cannot catch an nmi_line defect, and the attempt to close that hole found a FOURTH divergence cluster that three goldens had been hiding inside a "26 skipped" tally line. The emulation core is unchanged, so AccuracyCoin 141/141 and nestest 0-diff hold by construction. Rung 6 does NOT close -- no DE10-Nano and no SuperStation One are attached to this machine, confirmed by checking rather than assumed. Built on **v2.6.6 "Chassis"** (2026-08-29) — the console becomes a MiSTer core -- `sys/` vendored byte-identical against `Template_MiSTer@3ea1134c` (57 files, 0 content differences), a top level, a clock, a palette, video sync and an audio mixer, compiled by Quartus 17.0.2 into a Cyclone V bitstream with 0 errors, timing CLOSED, and a warning count taken from 111 to THREE -- all three inside the vendored framework or Quartus's own megafunction, none of them citing this project's RTL (worst setup +0.086 ns and worst hold +0.096 ns at the binding corners, seed 3 -- v2.6.7 also withdraws the +0.363/+0.245 v2.6.6 published, which a clean rebuild of that configuration reproduces at no corner, TNS 0.000 on every clock; the console's own clock +13.514 ns at an Fmax of 30.26 MHz against the 21.477272 MHz it needs). The emulation core is unchanged, so the co-simulation suite is an ACCEPTANCE CRITERION rather than a formality -- 87 passed, 0 failed -- and it earned that immediately, because the cartridge memories had to be rewritten: an M10K read is REGISTERED, so 40 KiB of asynchronously-read cartridge was 393,216 registers against roughly 166,000 available, under a comment claiming it inferred block RAM from the source style alone, and the README had stated the correct rule since v2.4.3. Two defects were found only by asking whether the outputs would work on real hardware: the audio would have been a full-scale DC rail, because the mixer output is unipolar with silence at zero and the framework maps unsigned silence to -32768, and two OSD scanline options did nothing because VGA_SL was tied to zero. And a convention enforced by a glob has no error message: sys_top.sdc groups the core clock by matching the hierarchical name pattern *|pll|pll_inst|altera_pll_i|*, so a differently-named PLL matched no group at all and every crossing to the framework audio, HDMI and HPS domains was analysed as synchronous -- -13.901 ns of slack and -422,601 ns of TNS on a design whose Fmax was already above requirement, with the compile succeeding and the Assembler reporting 0 errors and 0 warnings throughout. Built on **v2.6.5 "Muster"** (2026-08-29) — rung 5 closes — the AccuracyCoin status vector is identical entry for entry across all 146 entries, with 146 of 146 executed on both sides and none NotRun, where the same gate read 5 of 146 at the version's start. A muster is a roll call where every name is called AND answered, which is the two-clause acceptance exactly. Five PPU defects close the last six differing entries and four were invisible to every gate that existed when the version opened: the background shift registers' RELOAD and their shift clock need SEPARATE gates (with one shared gate the serial-in test was not merely failing but ARITHMETICALLY UNREACHABLE, since reload dots are absolute and the reload discards the low seven bits, so a serial-in one can never reach bit 7 on any alignment — and modelling both structures reproduces BOTH measured shifter values); the sprite X counters are NOT gated on rendering, which AccuracyCoin states outright and the ROM that states it passes either way, because it expects no hit at X=254 and a sprite shoved 18 dots right is also off the line; the PPUADDR second-write v-copy is DELAYED, as the wiki says inside the write sequence itself, swept 1 to 4 dots against a control at 8 and 12 that fails; and the pre-render line CLEARS secondary OAM, without which scanline 0 draws what scanline 239 left — no sprite can ever render on scanline 0, because OAM Y is one less than the display row, and a sprite-0 probe over the full 134 M-cycle battery found 24 hits with four of them there; and the octal latch holding across the read dot, which is verified by exactly ONE gate and was unverifiable until the v-copy delay landed, the two composing the hybrid address together and neither producing it alone. A DIAGNOSIS IS RETRACTED: the residual was read as a two-dot CPU/PPU alignment error from comparing dot spans across two instruments, and at the committed alignment the two consoles execute identical pc, bus_addr and bus_access for 1,695,131 cycles while a two-dot shift moves the first fork back to 593,228 and takes the differing share from 5.13% to 66.80%. The oracle changes on the default path, so AccuracyCoin 141/141 (RAM decoder) and nestest 0-diff are VERIFIED, not asserted. Built on **v2.6.4 "Rubric"** (2026-08-26) — OAM DMA lands and all nine AccuracyCoin disagreements close, every rule that closed the last three stated by the test ROM and by neither nesdev page — and then the gate that certified them is measured to cover 88 of 146 entries. The emulation core is unchanged. Built on **v2.6.3 "Mainspring"** (2026-08-25) — the DUT runs on one master clock, and four enables that were never enabling — plus AccuracyCoin end to end and a status vector that names its disagreements by test. The emulation core is unchanged. Built on **v2.6.2 "Witness"** (2026-08-24) — rung 4 closes: blargg APU battery 11/11 on the co-simulation DUT, six defects no self-written gate could see, and a suite that had been asserting nothing for five minor releases. The emulation core is unchanged. Built on **v2.6.1 "Interleave"** (2026-08-24) — the DMC and its DMA cycle steal in the MiSTer co-simulation DUT, cycle-exact on the bus. The emulation core is unchanged. Built on **v2.6.0 "Assay"** (2026-08-24) — the triangle, the noise channel and the sweep unit **in the MiSTer co-simulation DUT** — and an audit of how much of the APU was fitted to the oracle rather than derived from documentation. The emulation core is unchanged. Built on **v2.5.9 "Overture"** (2026-08-24) — rung 4 opens: the two pulse channels, the frame counter, and four ROM defects the stimulus measurement found first. Built on **v2.5.8 "Blanking"** (2026-08-24) — VBlank, NMI and the PPUSTATUS race close rung 3 — and both fixes were deletions. Built on **v2.5.7 "Collimation"** (2026-08-24) — sprite rendering closes exact — the phase was wrong by two dots, and every window was compensating. Built on **v2.5.6 "Vestige"** (2026-08-23) — Sprite evaluation closes: all 59,993 overlapping cycles match, nine of nine behavioural mutants caught and two proved inert (announced as seven of eight at the cut), and the fix is a byte index that outlives the walk that set it. Built on **v2.5.5 "Raster"** (2026-08-23) — the first full frame, and three blind spots in the stimulus that fed it. Built on **v2.5.4 "Escapement"** (2026-08-23) — the background fetch pipeline, and an access two dots early that five gates could not see. Built on **v2.5.3 "Hysteresis"** (2026-08-23) — toggling rendering takes effect three dots after the write, and four instruments to prove it. Built on **v2.5.2 "Dormant"** (2026-08-23) — the 2C02 register file, and a gate that passed while testing nothing. Built on **v2.5.1 "Retrace"** (2026-08-23) — the interrupt sweep closes rung 2, and a gate reported a pass it could not have earned. Built on **v2.5.0 "Rungwork"** (2026-08-23) — the 6502 rung, and the two gates it cannot reach. Built on **v2.4.9 "Plumbline II"** (2026-08-23) — the bus half of rung 2, and what it found the day it existed. Built on **v2.4.8 "Palimpsest"** (2026-08-23) — read-modify-write, and a gate that cannot see its own subject. Built on **v2.4.7 "Keystone"** (2026-08-23) — the stack closes, and a dead line proves itself dead. Built on **v2.4.6 "Abacus"** (2026-08-22) — the core learns arithmetic. Built on **v2.4.5 "Compass"** (2026-08-22) — the core reaches memory, and chooses. Built on **v2.4.4 "Ignition"** (2026-08-22) — the first real RTL -- the 6502's eight-cycle reset and the implied opcode group, matching the oracle on all seven CPU fields (29 +> **Current release: v3.7.1** (2026-11-15) — **"Imprint"**, 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. Built on **v2.9.5 "Caliper"** (2026-09-29) — every open accuracy item measured, then fixed or closed: four fixes red first (the `apu_test` frame-counter coincidence, the composite 2C02 scanline-0 sprite glitch, OAM DMA filling the PPU I/O latch, KS7032 at `$6000`), 49 unreferenced test ROMs gated, the MMC3 M2-edge filter lever tried and refuted, and a save-state epoch (`PPU_SNAPSHOT_VERSION` 11). Built on **v2.9.4 "Plumb"** (2026-09-29) — the records made true, and CI made to run what it only linted: v3.0.0 decided as the API major with a release-candidate core (ADR 0043), CI now running 63 feature-gated tests it never ran, the eight fuzz targets and a 70% line-coverage floor, the mapper tiers, store status and deferred-features catalogue corrected against the code, and the OAM-decay model recorded as derived from Mesen2. Built on **v2.9.3 "Handset"** (2026-09-29) — the old review threads closed and the mobile run prepared: every dependency moved to its newest release (egui 0.36 with wgpu 30, rcheevos 12.5.0), all 244 review threads left unanswered on PRs #7-#97 answered and the ten findings that still held fixed (Action 53 multicarts rebuilt to the NESdev spec, and a ROM header editor that no longer rewrites bytes you did not edit or saves mappers from 16 up as the wrong mapper), and the Android unit tests and the iOS renderer added to CI. The mobile device runs and the SuperStation One board session move after v3.0.0 (maintainer, 2026-09-29). Built on **v2.9.2 "Candidate"** (2026-09-28) — the full audit acted on, and the release-candidate pair: all 32 findings of a fifth audit have a verdict and 16 are fixed, save states keep the cartridge RAM of twelve board families they used to drop, the MiSTer core no longer loses an NMI raised inside a DMA, and both bitstreams are cut for the SuperStation One session. Built on **v2.9.1 "Hone"** (2026-09-27) — what the optimisation bars measure, and what clears them: the A/B tool had been timing the old code on both sides of every code comparison and is fixed, a two-screen Vs. cabinet saves about 9x faster, the off-die MiSTer build keeps CHR in its own SDRAM bank, and both bitstreams are pinned at fitter seed 2 and rebuild byte-identically. Built on **v2.9.0 "Survey"** (2026-09-26) — every audit re-checked, and the SuperStation One surveyed: a Power Cycle no longer erases your save, the off-die MiSTer build boots without the menu core, and 39 new audit findings are fixed or dispositioned. Built on **v2.8.4 "Tether"** (2026-09-26) — the MiSTer core's SDRAM build, made trustworthy: its controller now reads data on the edge the memory presents it (every off-die read would have been wrong on hardware, and only the new SDRAM timing constraints could see it), the power-up sequence and CAS-latency-3 reads follow the datasheet, the arbiter can no longer return the wrong byte or lose a write, the off-die bitstream builds from a script, both builds are swept and pinned at fitter seed 5, and the co-simulation ladder runs all 165 gates from a clean checkout. Built on **v2.8.3 "Rivet"** (2026-09-25) — the MiSTer core's reset, area and comments, measured: every reset is released on the clock that uses it and the timing analysis now checks each release, the CPU is about 4% smaller by two exact rewrites the fit report confirmed, four false comments are corrected, and the co-simulation ladder runs from a fresh checkout (164 of its 165 gates; the last needs a hand-built ROM no generator produces). Built on **v2.8.2 "Solder"** (2026-09-25) — the MiSTer core's on-die RTL, corrected against the oracle and the wiki: an MMC3 IRQ acknowledge is no longer lost to a same-edge counter clock, SNROM's battery RAM obeys its CHR-line enable, the triangle and noise drop a reload landing on a length clock, a `$2002` read leaves the byte it returned on the data bus, and the emulator's MMC1 no longer ignores a reset written on the cycle after another write. Built on **v2.8.1 "Gasket"** (2026-09-25) — the libretro core fits the frontends around it: four-player games work through a Four Score option, a controller works again after its port leaves the Zapper, RetroArch no longer reads past the core's input-descriptor list, expansion audio no longer clips, the core declares UNIF images, and the Makefile honours PREFIX, platform=win, DEBUG and CARGO_TARGET_DIR. Built on **v2.8.0 "Bulkhead"** (2026-09-25) — the libretro core stops a fault at its own boundary: an internal error no longer closes RetroArch, save states survive plugging in a Zapper, closing a game withdraws its memory maps, the core loads from any libretro frontend, and the save state now carries the 2A03 internal data bus. Built on **v2.7.6 "Recount"** (2026-09-24) — the v2.7.5 deletions measured one at a time: the six performance proposals v2.7.5 bounded only together were each measured alone, where the benchmarks reach them: five are zero, and the sixth, the pulse sweep-mute check, bounds at about 0.2%, and the cheap byte-identical way to take it measured slower; the fast render path now asserts a rendering-history invariant it used to re-write; and the libretro buildbot builds macOS again and gains 32-bit Windows, 32-bit Linux and webOS targets. Built on **v2.7.5 "Tally"** (2026-09-24) — every audit claim closed with a measurement or a reason: the core audit's twelve performance proposals were closed, eleven of them by measurement, and one adopted (the audio buffer keeps its capacity between frames); 18 dead bus methods and the unused ApuBus trait are deprecated; and the core and frontend ledgers have no open row. Built on **v2.7.4 "Pocket"** (2026-09-24) — the mobile apps survive what a phone does to them: an internal error no longer closes the Android or iOS app, battery saves persist on both, the apps pause and give up audio when they should, and saves are written so a dying phone keeps the last good one. Built on **v2.7.3 "Hearth"** (2026-09-23) — the desktop and web frontends keep what they are given: battery saves persist on the desktop, a Lua script can no longer hang or exhaust the emulator, script HTTP cannot reach local services by default, and audio survives a device change. Built on **v2.7.2 "Bankroll"** (2026-09-23) — cartridge memory, every bank a cartridge has and nothing it has not: MMC1 reaches SUROM / SXROM, MMC5 banks its PRG-RAM, Namco 163 selects nametables, and `$6000-$7FFF` reads open bus where a board has nothing there. Built on **v2.7.1 "Keepsake"** (2026-09-23) — six cartridge boards now hand RetroArch their battery save instead of an empty one, every user file the frontend writes is written atomically, and three mapper files are now recorded as derived from Mesen2 and puNES. Built on **v2.7.0 "Palisade"** (2026-09-23) — a corrupt or hand-edited save state now fails at restore with a typed error instead of crashing the emulator one tick later, pulse 1 no longer mutes on the `$4001 = $08` sweep idiom, and the save-state fuzz target can finally reach what it exists to find. Built on **v2.6.23 "Pulse"** (2026-09-20) — the access does not increment, it pulses the load already there. A `$2007` access during rendering pulses the rendering pipeline's existing load rather than computing a private increment, and resolving against that same value is what closed the CHR-during-rendering divergence in the MiSTer sibling: `chrram-live` went from **32,861 of 61,440 differing pixels**, red for eight releases, to "All 61440 pixels match", and `chrram-fetch` from 21,941 to 18. Eleven prior variants had been measured correctly and the conclusion drawn from them was wrong — they swept what the `$2007` arm computes and never what it computes it from. The emulation core is unchanged, so **AccuracyCoin 144/144 and nestest 0-diff hold by construction** and were re-run anyway. The bitstream is re-cut at fitter seed 4 (+0.421 ns setup / +0.112 ns hold) and **no hardware has run it**. The board session is now **v2.9.2** and the hardware-verified core **v3.0.0**, after three audit lines ([ADR 0041](adr/0041-hardware-release-is-v3.0.0.md)). Built on **v2.6.22 "Rigging"** — the instruments for the board, built before the board. **No hardware has run any bitstream**; the session with the board (then planned as "Shakedown"; since ADR 0041, v2.9.2) is the hardware half and this is the non-hardware half of it, cut separately so that name keeps meaning what it says. AccuracyCoin now reads back from hardware as BYTES rather than as a photograph — a mirror ROM copies its result vector into the battery-backed save window, with a byte budget that proves the patch moved nothing and a simulation control that proves it changed no answer. The catalog turned out to have **149 rows and 144 results**: five `Power On State` rows share upstream's omit-sentinel, and counting them made the headline a function of *when the run was sampled*. **144/144 and nestest 0-diff are unchanged** — the count stopped depending on the sampling instant. And the `46199ae4` re-sync turned out to have been half-done: three goldens described a ROM no longer in the tree, which no gate could see because `rom_sha256` was written into every manifest and compared to nothing. Built on **v2.6.21 "Steward"** — the board arrives, and the core is not ready for it. Battery saves exist for the first time; the CHR-during-rendering gate the retrospective audit asked for is added and is **RED at 32,861 of 61,440 pixels**, with the obvious fix measured insufficient at 715 recovered; two gates existed that nothing ran; and the deploy loop the runbook prescribed was built, which found two defects in its own spec. The emulation core is unchanged, so **AccuracyCoin 144/144 and nestest 0-diff hold by construction**. Built on **v2.6.20 "Telltale"** — the counter had no reader, and two knobs turned out to be one decision. The FPGA core's OAM2 address counter was write-only for a release, so `$2004`'s post-fetch rest value was a hardcoded index 0; making it observable took the DUT to **AccuracyCoin 149 of 149** and the co-simulation ladder to **150 of 150, 0 failed**. Restoring the increment window v2.6.19 had narrowed then broke sprite rendering by six pixels, because the window and the deleted dot-257 latch are ONE decision with two self-consistent answers and only one of them is the hardware's. The shipped configuration restores the latch: window 256, the dot-257 freeze latch back and consumed by sprite fetch, and `$2004` reading the live counter. A CHR-RAM write gate was added. **v2.6.21 corrects this sentence: it did NOT close the coverage the audit named.** The audit named writes *while rendering is enabled*, and PROGRAM53 writes with `PPUMASK = 0` and renders afterwards. The real case is gated at v2.6.21 and is RED -- 32,861 of 61,440 pixels. The emulation core is unchanged, so **144/144 and nestest 0-diff hold by construction**. Built on **v2.6.19 "Accession"** — the DUT absorbs two releases of oracle behaviour, and the seed rule catches something for the first time. The FPGA core implements the OAM2 address counter it never had and stops acting on a `$2001` change that lands during dot 256 -- AccuracyCoin on the DUT **148 of 149**, the ladder **147 of 147**. The fitter pin is re-derived over ten seeds and stays at 3. (The contemporaneous claim that seed 1 stopped closing is withdrawn -- that sweep recompiled in place and was order-dependent; seed 1 closes, and seed 8 is the one that does not.) The emulation core is unchanged, so **AccuracyCoin 144/144 and nestest 0-diff hold by construction**. Built on **v2.6.18** (2026-09-12) — **"Errata"**, the recorded cause was wrong in three ways, and the last AccuracyCoin entry closes at 144/144 -- a `$2001` change during dot N must not act on dot N, at the dot-256 vertical increment and the dot-339 OAM2 reset. Built on **v2.6.17** (2026-09-11) — **"Terminus"**, the accuracy battery grows to 144 assigned tests and one of the new ones names the dots a write lands on -- this core is two dots early, measured twice on two independent `$2001` writes, and moving it is refuted by the gate this version wrote in advance, so the documented compensation stays and 143 of 144 ships. Built on **v2.6.16 "Interlock"** (2026-09-04) — the arbiter's numbers describe a stimulus, not the console -- and the console meets the CPU's deadline at zero margin, on every one of 240,303 requests, where the gate said it missed by four. Built on **v2.6.15 "Warrant"** (2026-09-04) — the claims v2.7.0 will make become checkable, and the instrument pays the oracle back. Built on **v2.6.14 "Docket"** (2026-09-03) — the submission checklist becomes auditable, and auditing it finds five boxes already true, two ticked on evidence that expired, and one that could never have been ticked honestly. v2.7.0 IS the submission, so the list in `to-dos/mister/contribution-checklist.md` decides whether the core is ready -- and it had 30 boxes, 16 unticked, and FOURTEEN OF THOSE SIXTEEN saying nothing at all about why. That ambiguity is the defect: an unticked box with no reason cannot be told apart from work outstanding, work blocked outside this repository, and WORK ALREADY DONE AND NEVER TICKED, and the third case occurred five times -- the provenance CI job, the SPDX sweep, the firewall statement, the AccuracyCoin vector and the preservation-value case were all true and all unticked, so the list reported the project as further from submission than it is by a fifth of its own length. ONE BOX COULD NEVER HAVE BEEN TICKED HONESTLY: it asked that `docs/provenance.md` state "that no NES core was ever opened", and that same document's section Do not self-certify forbids exactly that class of finished claim, so satisfying the box required writing the one sentence the provenance rules exist to prevent -- a wrong requirement rather than a missing tick, and only reading every item found it. RE-MEASURING THE TICKED HALF found two more, which is v2.6.9's lesson in a different document: `RustyNES.sdc` still said "there is exactly one core clock", true of v2.6.3 and false since v2.6.13, which added a 4x SDRAM clock and a phase-shifted pin clock that the shipped timing report names alongside it; and the `.qsf` entry said all 109 pin assignments come from `sys/sys.tcl`, where 109 is what that script supplies before stopping short of the I/O board, so a core must also source one of two 36-assignment variants -- 145 in total, from two scripts. THE ALARMING READING OF THE FIRST WAS CHECKED BEFORE IT WAS WRITTEN DOWN: it looks as though the framework's `set_clock_groups -exclusive` might be cutting the console-to-SDRAM crossing and leaving ADR 0039's safety argument unfalsifiable, and it is not -- exclusive cuts paths BETWEEN groups, all three outputs match one glob, and v2.6.13's own -24.769 ns measurement of that crossing is only observable because those paths are analysed. THE NAMING DIVERGENCE IS MEASURED RATHER THAN PARAPHRASED, from `Main_MiSTer/file_io.cpp` instead of the wiki: `get_display_name` searches for the literal underscore-two-zero and TRUNCATES THE DISPLAY NAME THERE, taking the rest as a datecode, and `DirentComp` groups by that truncated name -- so a version-named bitstream makes every release a SEPARATE CORE ENTRY, named for the version rather than the core, ordered alphabetically, which puts v2.6.9 after v2.6.13. The fix is one line and is NOT taken here, because version-naming is a maintainer decision with a stated rationale and reversing it is not an audit's call. THE TASK BOARD HAD THE SAME DEFECT AND ONE ROW WORSE: four delivered items never ticked, a hardware row still naming a version seven releases past, and an SDRAM row whose precondition -- "after a board exists" -- v2.6.13 simply did not follow, having accepted the controller against a behavioural model written from the datasheet instead; that is rung 7's own recorded lesson repeating one row below where it is written, since the blocker applied to hardware ACCEPTANCE rather than to building the thing. A CLAIM v2.6.13 SHIPPED IS RETRACTED: answering a review finding, I wrote that MMC1 was the sixth approved family and not yet implemented, and the cartridge decodes mapper 1 at three sites with a registered gate green since rung 7 opened -- asserted from memory inside a reply correcting somebody else's reading of the same line. The gate that keeps all this true asserts a SHAPE rather than a judgement and is demonstrated by five mutations, one of which proves the continuation-line folding load-bearing by producing nine false violations without it. The bitstream is BYTE-IDENTICAL to v2.6.13's, which is the point: the only sibling change is a comment, and an identical artifact demonstrates it. The emulation core is unchanged, so AccuracyCoin 141/141 and nestest 0-diff hold by construction. Built on **v2.6.13 "Slack"** (2026-09-03) — the cartridge outgrows the die, and three consumers want the same bus. An SDR SDRAM controller, a behavioural part model, a four-way arbiter and a console bridge, all written from the AS4C32M16SB-7 datasheet revision 1.4 -- no third-party controller read, ADR 0037 applying. The budget the previous step worked to was a single figure read off the fetch structure and never measured; `nes_top`'s `CHR_LAT` sweep asks the console directly, and there are THREE answers: a background or sprite fetch tolerates 28 cycles and uses 17, the PPUDATA data port tolerates 8, and the CPU sampling at mc7 has 24 -- four cycles of every budget going to the console-domain crossing, which is not optional, because publishing a runtime modulo combinationally into an 11.64 ns domain costs -24.769 ns of setup. The PPUDATA port could never fit, half its budget being the crossing, so it leaves the shared bus entirely: `ppu2c02` gains `BUFFER_HANDSHAKE` and fills its read buffer through a port of its own on the arbiter, affordable because the CPU does not read that buffer until its next PPUDATA access. THAT FIX SHIPPED A DEFECT ONLY A BANKED CARTRIDGE COULD SEE -- the request carried the RAW fourteen bits the PPU presents, which is right by coincidence on NROM because the mapper's translation is the identity there, and reads BANK ZERO on everything else; `ppu-misc-2007-stress` passed off-die throughout while the two CNROM gates read a zero byte where the oracle reads one, one and two. The fix REMOVES the address rather than correcting it: `cart.sv` already publishes the translation for the fetch path, so the request carries none and there is one source of truth for where CHR lives instead of two that agree only on NROM. A DELETION WAS THEN REFUTED BY ONE CYCLE: with the address fixed, a control issuing at a flat +7 passed both gates, which read as the anti-contention deferral buying nothing, so it was removed -- and the deployed code issued at +6, and both gates failed again. The control and the code differed by a single cycle, which is the measurement of how thin the CPU's off-die deadline is and the concrete argument for scheduling the bus rather than arbitrating it. Two INFERRED LATCHES that Verilator cannot see: `ppu2c02` assigned two signals only under `BUFFER_HANDSHAKE`, so in the shipped on-die build the only assignment either reached was the reset branch, and a variable holding its previous value on every live path is a latch -- Quartus said so twice while the lint gate stayed green, and the comment beside them asserted the defect as a virtue ("outside BUFFER_HANDSHAKE neither signal ever moves", which is true and is exactly the condition). And a defect in the HARNESS: `USE_SDRAM` reaches Verilator as `-G` rather than as a file, so make ran ONE binary under both configurations' names and a log labelled on-die was the off-die build, reproducing the off-die failures exactly -- closed with a stamp-file prerequisite, demonstrated by mutation. THE OPEN ROW: accesses no longer auto-precharge, a hit costs 6 cycles against 10 for a miss, tRAS's 120 us MAXIMUM is respected by an early close in idle, and two defects came out of the rewrite -- re-entering idle with the request still asserted issued every access TWICE, and subtracting one from CAS the way the other waits are computed broke every read to all zeroes, CAS being "data appears at cycle N" rather than a command-to-command gap. Two MiSTer tickets close: `sdram_sz` is consumed VALIDITY BIT FIRST, so `absent` is deliberately not `!present` and a power-on all zeroes cannot read as "no board" (gated exhaustively over all 65,536 values), and `status_menumask` is computed rather than tied off, greying Reset whenever the console is already held in reset. OFF THE DIE THE CONSOLE PASSES 142 OF 142, every gate the on-die build passes, with better timing margin and 384 fewer M10K blocks -- and it still SHIPS ON the die, because an off-die core cannot run at all without the SDRAM add-on while rung 7's five mapper families fit on the die at 468 of 553 blocks. The emulation core is unchanged, so AccuracyCoin 141/141 and nestest 0-diff hold by construction. Built on **v2.6.12 "Groundwork"** (2026-09-02) — the bitstream was an NROM-only console. Rung 7 landed five mapper families and 142 co-simulation gates verify them, and the layer that turns that RTL into a bitstream was never told: `rtl/emu.sv` left `cart_mapper`, `cart_prg_16k_banks` and `cart_chr_8k_banks` unconnected, so Quartus tied all three to GND -- mapper 0 for EVERY cartridge, `prg_8k_count = 0` collapsing PRG to an 8 KiB window, and CHR forced to RAM. The declared 256 KiB PRG and 128 KiB CHR were implemented as 8 KiB each; connecting three wires takes block memory from 666,061 to 3,680,717 bits and timing still closes at all four corners. NOTHING COULD HAVE CAUGHT IT: simulation cannot, because `emu.sv` is not in the testbench file list and the harness drives those ports itself, so all 142 gates exercised a correctly-configured cartridge; and Quartus DID say so three times, in messages that cite an INSTANCE path rather than a file and are absent from the "0 errors, N warnings" tally, so the existing checker read 0 of 125. Two gates close that -- one fails on an unconnected pin of any module this repository declares, the other pins the warning SET rather than its count -- and both are demonstrated to fail by mutation. The `hps_io` tie-off audit that followed raised nine `T-MISTER-*` tickets, and annotating each with a blocker turned "none of these landed" into a measurement: not one is blocked on EFFORT, so the list is the rung-6 agenda rather than a backlog. `T-MISTER-SAVE` was attempted and refuted -- every save route terminates in `hps_io`, which no gate here instantiates. The emulation core is unchanged, so AccuracyCoin 141/141 and nestest 0-diff hold by construction. Built on **v2.6.11 "Exposure"** (2026-09-02) — a picture is a gate the ladder did not have. All 141 co-simulation gates THEN IN THE SUITE were green (it ends this release at 142, the one it added) and TWO OF SIX commercial games rendered wrong -- a CHR-RAM write was taking the shared-pin composite address built for FETCHES instead of `v`, so the layout was right and the tiles were scrambled. The split is exactly CHR-ROM against CHR-RAM, which named the mechanism before any tracing, and a CONTROL says it is not v2.6.10's regression: the pre-M10K-fix RTL differs by the IDENTICAL 16,565 pixels, so the defect dates from the cartridge landing in v2.6.9. It was not UNREACHED -- the DUT asserts `chr_wr` 9,600 times in the Battletoads run -- it was UNCOMPARED: only THREE of the 141 gates compare a framebuffer, all three ship CHR-ROM, every other gate is CPU-side, and AccuracyCoin, the widest gate in the suite, is CHR-ROM too. The rung-7 gates' own comment says what they are for -- "these gates are about BANKING and nothing else" -- and it was accurate, and it was the whole coverage. Six commercial titles now render byte-identically to the oracle over all 61,440 pixels, published as a montage built by a script that REFUSES to publish a tile that differs from the oracle. The v2.6.10 bitstream carries the defect and a published version is immutable, so the corrected `.rbf` ships here. The same release finds EIGHT release leads describing v2.6.10 with v2.6.9's summary, and v2.6.9 gone from the lineage entirely, with `docs/STATUS.md` naming v2.6.10 under the codename "Abeyance" -- every existing check passing CORRECTLY, because they pin the version TOKEN and the token was right. Prose cannot be audited; an ORDERING can, so two gates are added and both are demonstrated to fail by mutation. The emulation core is unchanged, so AccuracyCoin 141/141 and nestest 0-diff hold by construction. Rung 6 does NOT close -- no DE10-Nano and no SuperStation One are attached to this machine, confirmed by checking rather than assumed. Built on **v2.6.10 "Inference"** (2026-09-01) — the cartridge meets the synthesiser. Five cartridge boards verified across 141 co-simulation gates had **never been through Quartus**, and Analysis & Synthesis refused the design: `chr` was written from TWO `always_ff` blocks, which cannot infer as one M10K, so 128 KB of CHR stayed in flip-flops -- **1,048,576 registers against roughly 166,000**. Simulation cannot ask this question: Verilator accepts both forms without complaint. It is v2.6.6's finding one layer out -- that release established that an M10K read is REGISTERED, this one that a correctly registered memory still will not infer with two writers. The fitter was also throttling itself under Auto Fit while the `.qsf` carried no optimisation assignments at all: at full effort **all six seeds close** where two had failed, so the effort settings move the whole distribution across zero and the seed only picks where in it you land -- and the project had been pinned to seed 4, the WORST of the six. Pinned at seed 3, +0.531 ns setup and +0.099 ns hold, byte-identical across two independent compiles. The bitstream v2.6.9 could not produce ships here. Built on **v2.6.9 "Abeyance"** (2026-08-31) — an exclusion hides improvement as well as regression, and both denied co-simulation streams close. The larger one was never the console: `apuconflict039` had been carried for seven releases as a declared diagnostic whose bus surface "carries nine divergences BY DESIGN", and the nine were a defect in the HARNESS -- on a cycle the CPU is held, the testbench built its record's bus data from a stale local rather than from the RTL's own latch. Taking it from the latch makes the stream IDENTICAL on all 357,361 overlapping cycles and all 88 checkpoints, and the local is now dead and deleted. The phrase "by design" is what stopped anyone re-checking it, because it reads as a property of the thing under test when it was a property of the instrument reading it. The other stream differs on EXACTLY ONE cycle, a documented and attributed OAM-corruption asymmetry -- and carrying that needed an instrument the suite did not have, because the PLANNED mechanism was refuted by its own mutation pass: an allowance by checkpoint index cannot work on a rolling hash, since one divergent cycle poisons every checkpoint after it, so allowing the first differing window simply moved the failure to the next one and allowing the rest is the all-or-nothing deny it was meant to replace. A per-cycle nine-field comparator with a scoped allowance costs ONE cycle of coverage instead of seventy-one checkpoints -- 357,360 of 357,361, against nothing at all before -- and it fails BOTH ways, so a DUT that improves cannot leave a stale allowance quietly hiding coverage; six mutations confirm it, including a cycle outside the compared window being REFUSED rather than allowed to match nothing. The emulation core is unchanged, so AccuracyCoin 141/141 and nestest 0-diff hold by construction and were re-run anyway. Rung 6 does NOT close -- no DE10-Nano and no SuperStation One are attached to this machine, confirmed by checking rather than assumed. Built on **v2.6.8 "Arrears"** (2026-08-31) — the gates the previous release fixed and never widened. A deny list is an assertion about the THING UNDER TEST, so v2.6.7 changing both the DUT and the harness re-opened every exclusion -- and nothing re-measured one. FOUR of the six denied checkpoint streams were passing (`irqlat048`, `ppuvbl023`, `ppuvbl024`, `ppuvbl025`), and THREE of those were not run by the suite at all, so removing them from the deny list was INERT until they were also iterated. The nestest gate compared 265,000 cycles against a 5,062,688-cycle golden -- correct while caveat C6 was open, left behind the moment it closed -- and all 5,062,680 overlapping cycles now match, with the window DERIVED from the manifest. CAVEAT C4 CLOSES by demonstration: nestest raises `nmi_line` on 3,592 cycles and had no nine-field comparison at all, so wiring it makes an `o.nmi_line` mutation CAUGHT at checkpoint 28 of 1,237 while the bus gate passes the identical run. Suite 128 passed, 0 failed, 0 skipped; nine-field comparisons 51 -> 57. The emulation core is unchanged, so AccuracyCoin 141/141 and nestest 0-diff hold by construction. Rung 6 does NOT close -- no board is attached, confirmed by checking. Built on **v2.6.7 "Detent"** (2026-08-30) — the bitstream becomes a published release artifact and a one-cycle disagreement is pinned to the cycle it happens on. Every release from here ships a `.rbf` -- committed to the sibling's `releases/` and attached to the GitHub release on BOTH repositories -- reversing v2.6.6, which produced one and withheld it because no hardware had run it: the MiSTer distribution mechanism reads that path out of the REPOSITORY, so an empty `releases/` describes an undistributable core rather than a cautious one, and the caution moves from an absence into a disclosure naming what the ladder cannot reach by construction (the PPU gate compares the pre-palette index and the APU gate per-channel integer levels, so the palette, the video timing constants, the audio absolute level and its band-limiting all sit downstream of every gate). The build is REPRODUCIBLE and that is now measured rather than argued -- a from-scratch compile and an incremental one produce a byte-identical bitstream -- which is also how v2.6.6's published slack figures came to be WITHDRAWN: no corner of a clean rebuild reproduces them, the innocent explanation (a different timing corner) was checked first and refuted, and the correct pair is +0.108 ns setup and +0.042 ns hold at the binding corner. THE RELEASE GATE WAS READING THE WRONG CORNER -- Slow 100C is not the binding one on this design, so a bitstream failing at Slow -40C would have passed while the gate reported three times the real margin -- and the checker that reads it was wrong twice before mutation found both: it first extracted ZERO rows from both summary tables and reported that as "no negative slack", then, once fixed, reported FOURTEEN clocks from a report emptied of its data, having run past the closing rule into the next tables. Caveat C2 splits in two. The first residual was a TRACE OBSERVATION POINT -- the harness built its record after eight of a CPU cycle's twelve master clocks while the oracle reads at end-of-cycle, and the frame-counter interrupt asserts on the final edge -- and closing it took checkpoint comparisons from 3 to 11 and failures at one checkpoint from 30 to 3. The second is REAL, and the FIRST fix for it was REFUTED in a way that found the right one: moving all four effects of the write one cycle later to match the oracle drops blargg from 11/11 to 4 of 11, one of the seven being the ROM written to probe exactly that timing. Read as a measurement that PROVES the sequencer's maturation is correctly placed, which leaves only the other effects the same write schedules -- so separating ONLY the interrupt clear lands it at write+3, the documented cycle, while the frame counter's zeroing stays put. Checkpoint streams go from 11 identical to 52 of 58 and the suite from 87 to 122, with blargg still 11/11 and the bus still matching on all 2,680,239 overlapping cycles. The checkpoint gate is registered over 51 comparisons and STATES ITS BLIND SPOT: not one gated golden ever raises an NMI, so it cannot catch an nmi_line defect, and the attempt to close that hole found a FOURTH divergence cluster that three goldens had been hiding inside a "26 skipped" tally line. The emulation core is unchanged, so AccuracyCoin 141/141 and nestest 0-diff hold by construction. Rung 6 does NOT close -- no DE10-Nano and no SuperStation One are attached to this machine, confirmed by checking rather than assumed. Built on **v2.6.6 "Chassis"** (2026-08-29) — the console becomes a MiSTer core -- `sys/` vendored byte-identical against `Template_MiSTer@3ea1134c` (57 files, 0 content differences), a top level, a clock, a palette, video sync and an audio mixer, compiled by Quartus 17.0.2 into a Cyclone V bitstream with 0 errors, timing CLOSED, and a warning count taken from 111 to THREE -- all three inside the vendored framework or Quartus's own megafunction, none of them citing this project's RTL (worst setup +0.086 ns and worst hold +0.096 ns at the binding corners, seed 3 -- v2.6.7 also withdraws the +0.363/+0.245 v2.6.6 published, which a clean rebuild of that configuration reproduces at no corner, TNS 0.000 on every clock; the console's own clock +13.514 ns at an Fmax of 30.26 MHz against the 21.477272 MHz it needs). The emulation core is unchanged, so the co-simulation suite is an ACCEPTANCE CRITERION rather than a formality -- 87 passed, 0 failed -- and it earned that immediately, because the cartridge memories had to be rewritten: an M10K read is REGISTERED, so 40 KiB of asynchronously-read cartridge was 393,216 registers against roughly 166,000 available, under a comment claiming it inferred block RAM from the source style alone, and the README had stated the correct rule since v2.4.3. Two defects were found only by asking whether the outputs would work on real hardware: the audio would have been a full-scale DC rail, because the mixer output is unipolar with silence at zero and the framework maps unsigned silence to -32768, and two OSD scanline options did nothing because VGA_SL was tied to zero. And a convention enforced by a glob has no error message: sys_top.sdc groups the core clock by matching the hierarchical name pattern *|pll|pll_inst|altera_pll_i|*, so a differently-named PLL matched no group at all and every crossing to the framework audio, HDMI and HPS domains was analysed as synchronous -- -13.901 ns of slack and -422,601 ns of TNS on a design whose Fmax was already above requirement, with the compile succeeding and the Assembler reporting 0 errors and 0 warnings throughout. Built on **v2.6.5 "Muster"** (2026-08-29) — rung 5 closes — the AccuracyCoin status vector is identical entry for entry across all 146 entries, with 146 of 146 executed on both sides and none NotRun, where the same gate read 5 of 146 at the version's start. A muster is a roll call where every name is called AND answered, which is the two-clause acceptance exactly. Five PPU defects close the last six differing entries and four were invisible to every gate that existed when the version opened: the background shift registers' RELOAD and their shift clock need SEPARATE gates (with one shared gate the serial-in test was not merely failing but ARITHMETICALLY UNREACHABLE, since reload dots are absolute and the reload discards the low seven bits, so a serial-in one can never reach bit 7 on any alignment — and modelling both structures reproduces BOTH measured shifter values); the sprite X counters are NOT gated on rendering, which AccuracyCoin states outright and the ROM that states it passes either way, because it expects no hit at X=254 and a sprite shoved 18 dots right is also off the line; the PPUADDR second-write v-copy is DELAYED, as the wiki says inside the write sequence itself, swept 1 to 4 dots against a control at 8 and 12 that fails; and the pre-render line CLEARS secondary OAM, without which scanline 0 draws what scanline 239 left — no sprite can ever render on scanline 0, because OAM Y is one less than the display row, and a sprite-0 probe over the full 134 M-cycle battery found 24 hits with four of them there; and the octal latch holding across the read dot, which is verified by exactly ONE gate and was unverifiable until the v-copy delay landed, the two composing the hybrid address together and neither producing it alone. A DIAGNOSIS IS RETRACTED: the residual was read as a two-dot CPU/PPU alignment error from comparing dot spans across two instruments, and at the committed alignment the two consoles execute identical pc, bus_addr and bus_access for 1,695,131 cycles while a two-dot shift moves the first fork back to 593,228 and takes the differing share from 5.13% to 66.80%. The oracle changes on the default path, so AccuracyCoin 141/141 (RAM decoder) and nestest 0-diff are VERIFIED, not asserted. Built on **v2.6.4 "Rubric"** (2026-08-26) — OAM DMA lands and all nine AccuracyCoin disagreements close, every rule that closed the last three stated by the test ROM and by neither nesdev page — and then the gate that certified them is measured to cover 88 of 146 entries. The emulation core is unchanged. Built on **v2.6.3 "Mainspring"** (2026-08-25) — the DUT runs on one master clock, and four enables that were never enabling — plus AccuracyCoin end to end and a status vector that names its disagreements by test. The emulation core is unchanged. Built on **v2.6.2 "Witness"** (2026-08-24) — rung 4 closes: blargg APU battery 11/11 on the co-simulation DUT, six defects no self-written gate could see, and a suite that had been asserting nothing for five minor releases. The emulation core is unchanged. Built on **v2.6.1 "Interleave"** (2026-08-24) — the DMC and its DMA cycle steal in the MiSTer co-simulation DUT, cycle-exact on the bus. The emulation core is unchanged. Built on **v2.6.0 "Assay"** (2026-08-24) — the triangle, the noise channel and the sweep unit **in the MiSTer co-simulation DUT** — and an audit of how much of the APU was fitted to the oracle rather than derived from documentation. The emulation core is unchanged. Built on **v2.5.9 "Overture"** (2026-08-24) — rung 4 opens: the two pulse channels, the frame counter, and four ROM defects the stimulus measurement found first. Built on **v2.5.8 "Blanking"** (2026-08-24) — VBlank, NMI and the PPUSTATUS race close rung 3 — and both fixes were deletions. Built on **v2.5.7 "Collimation"** (2026-08-24) — sprite rendering closes exact — the phase was wrong by two dots, and every window was compensating. Built on **v2.5.6 "Vestige"** (2026-08-23) — Sprite evaluation closes: all 59,993 overlapping cycles match, nine of nine behavioural mutants caught and two proved inert (announced as seven of eight at the cut), and the fix is a byte index that outlives the walk that set it. Built on **v2.5.5 "Raster"** (2026-08-23) — the first full frame, and three blind spots in the stimulus that fed it. Built on **v2.5.4 "Escapement"** (2026-08-23) — the background fetch pipeline, and an access two dots early that five gates could not see. Built on **v2.5.3 "Hysteresis"** (2026-08-23) — toggling rendering takes effect three dots after the write, and four instruments to prove it. Built on **v2.5.2 "Dormant"** (2026-08-23) — the 2C02 register file, and a gate that passed while testing nothing. Built on **v2.5.1 "Retrace"** (2026-08-23) — the interrupt sweep closes rung 2, and a gate reported a pass it could not have earned. Built on **v2.5.0 "Rungwork"** (2026-08-23) — the 6502 rung, and the two gates it cannot reach. Built on **v2.4.9 "Plumbline II"** (2026-08-23) — the bus half of rung 2, and what it found the day it existed. Built on **v2.4.8 "Palimpsest"** (2026-08-23) — read-modify-write, and a gate that cannot see its own subject. Built on **v2.4.7 "Keystone"** (2026-08-23) — the stack closes, and a dead line proves itself dead. Built on **v2.4.6 "Abacus"** (2026-08-22) — the core learns arithmetic. Built on **v2.4.5 "Compass"** (2026-08-22) — the core reaches memory, and chooses. Built on **v2.4.4 "Ignition"** (2026-08-22) — the first real RTL -- the 6502's eight-cycle reset and the implied opcode group, matching the oracle on all seven CPU fields (29 > records, `RustyNES_MiSTer@7f092bd`). The oracle settled a question our own > prose could not: reset is EIGHT cycles, and `docs/cpu-6502.md` said both > seven and eight. The emulation core is untouched. 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 72319f438..16660dfc7 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/agents/release-line.md b/docs/agents/release-line.md index faf7ac2b7..4cc3630d2 100644 --- a/docs/agents/release-line.md +++ b/docs/agents/release-line.md @@ -4,7 +4,7 @@ > > **Read this file when the task touches release narrative, the platform apps, format epochs or version history.** -**Current release: 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 ([ADR 0043](../adr/0043-v3-is-the-api-major-and-a-release-candidate-core.md)). **No hardware has run any MiSTer bitstream**: hardware verification moves to a later v3.x release (ADR 0043 supersedes [ADR 0041](../adr/0041-hardware-release-is-v3.0.0.md)'s hardware-verified v3.0.0), and the SDRAM pin constraints stay provisional until the SuperStation One's memory is read. Suite counts, mapper matrix and per-release detail live in `docs/STATUS.md`, `CHANGELOG.md` and the GitHub releases; they are deliberately not duplicated here. The earlier release-by-release narrative and other condensed paragraphs are archived verbatim in `docs/history/AGENTS-archive.md`. +**Current release: 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 ([ADR 0043](../adr/0043-v3-is-the-api-major-and-a-release-candidate-core.md)). **No hardware has run any MiSTer bitstream**: hardware verification moves to a later v3.x release (ADR 0043 supersedes [ADR 0041](../adr/0041-hardware-release-is-v3.0.0.md)'s hardware-verified v3.0.0), and the SDRAM pin constraints stay provisional until the SuperStation One's memory is read. Suite counts, mapper matrix and per-release detail live in `docs/STATUS.md`, `CHANGELOG.md` and the GitHub releases; they are deliberately not duplicated here. The earlier release-by-release narrative and other condensed paragraphs are archived verbatim in `docs/history/AGENTS-archive.md`. > **New here since v0.8.x?** The emulation core was replaced with the cycle-accurate engine and the repo was re-cut as v1.0.0. Read `docs/v1.0.0-synthesis-handoff-2026-06-13.md` first — it explains what changed, the `rustynes-*` architecture, where everything moved, and the hard constraints. Then update `AGENTS.md` (and this file, where the detail lives) + your memory as you work. @@ -32,4 +32,4 @@ Everything else about the release line is in `CHANGELOG.md`. **Engine-lineage versioning (read carefully).** The core descends from an accuracy program whose internal "v1.x / v2.x" milestones are folded into RustyNES stages v0.9.0–v0.9.7 → the v1.0.0 production cut. Read deep-narrative "v2.0" anchors from before 2026-07-03 (the master-clock refactor, old ADRs / audit logs under `docs/`) as **upstream engine lineage**, never as RustyNES release versions — that engine-lineage v2.0 work shipped as the v1.0.0 production core (2026-06-13) and is a *different* thing from RustyNES's own **v2.0.0 "Timebase"** release (2026-07-03), which replaces that same dot-lockstep scheduler with the one-clock model. `docs/STATUS.md` is the authoritative per-suite pass-count + mapper matrix. -- When relabeling old engine "v2.x" narrative for users, present it as upstream lineage/history — **never as a current RustyNES release version.** The current release is **v3.7.0 "Spindle"** (2026-11-10). **Never claim any version *later* than v3.7.0 is released.** Two distinct "v2.0"s exist and must not be conflated: the **engine-lineage v2.0** master-clock work shipped as the **v1.0.0** production core (2026-06-13) and was the only scheduler through v1.10.0; RustyNES's own **v2.0.0 "Timebase"** (2026-07-03) is a different milestone that REPLACES that dot-lockstep scheduler with the one-clock, every-cycle-bus-access model (ADR 0002 / 0028 / 0029) and broke byte-identity and save-state compatibility, by design (v2.9.8 later broke save, movie and API compatibility again, ahead of v3.0.0). The per-release narrative that used to be inlined here is in `CHANGELOG.md`, the per-release notes under `.github/release-notes/`, and the published GitHub releases — three places that are maintained, against one copy here that was not. +- When relabeling old engine "v2.x" narrative for users, present it as upstream lineage/history — **never as a current RustyNES release version.** The current release is **v3.7.1 "Imprint"** (2026-11-15). **Never claim any version *later* than v3.7.1 is released.** Two distinct "v2.0"s exist and must not be conflated: the **engine-lineage v2.0** master-clock work shipped as the **v1.0.0** production core (2026-06-13) and was the only scheduler through v1.10.0; RustyNES's own **v2.0.0 "Timebase"** (2026-07-03) is a different milestone that REPLACES that dot-lockstep scheduler with the one-clock, every-cycle-bus-access model (ADR 0002 / 0028 / 0029) and broke byte-identity and save-state compatibility, by design (v2.9.8 later broke save, movie and API compatibility again, ahead of v3.0.0). The per-release narrative that used to be inlined here is in `CHANGELOG.md`, the per-release notes under `.github/release-notes/`, and the published GitHub releases — three places that are maintained, against one copy here that was not. 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 000000000..abb88f4f0 --- /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 ae5fc4692..168291999 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,34 @@ 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. +> **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 +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 +176,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 +197,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 +205,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 +369,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 +394,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 +405,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 +434,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 +449,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 +494,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 +515,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`. diff --git a/ios/project.yml b/ios/project.yml index 6f3e71686..4ace5db3f 100644 --- a/ios/project.yml +++ b/ios/project.yml @@ -45,7 +45,7 @@ settings: # 2.0.8 through v2.9.9, since nothing moved it), and moved by # `scripts/release-automation/bump_release.py` from now on, starting with # the 3.0.0 cut. - MARKETING_VERSION: "3.7.0" + MARKETING_VERSION: "3.7.1" # The build (not marketing) number. Each TestFlight upload needs a UNIQUE one; # the fastlane `beta` lane overrides this with the CI run number at build time # (xcargs CURRENT_PROJECT_VERSION), so this checked-in "1" is only the local / diff --git a/scripts/ci/prune-deployments.sh b/scripts/ci/prune-deployments.sh new file mode 100644 index 000000000..68c8deba3 --- /dev/null +++ b/scripts/ci/prune-deployments.sh @@ -0,0 +1,159 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: GPL-3.0-or-later +# +# Delete superseded deployments, keeping the newest one of every environment. +# +# WHY THIS EXISTS +# =============== +# GitHub keeps every deployment forever. Each Docs7 preview of each pull +# request push, each GitHub Pages publish and each Copilot agent run adds one, +# and a superseded deployment is only marked inactive. By 2026-11-15 this +# repository held 668 (263 from Docs7, 405 from Pages and Copilot), and each +# preview branch's deployments also kept its environment alive. +# +# WHAT IS KEPT, AND WHAT GOES +# =========================== +# - KEPT: the newest deployment of every environment that still exists, whatever +# its state, AND its newest SUCCESS deployment, which is the live one while a +# newer deployment is in flight or after it failed (the live Pages site, Docs7 +# Production, an open pull request's preview). A deployment in a transient +# state (queued, pending, in progress, waiting) is never touched anywhere. +# - DELETED: every other deployment. GitHub only deletes an inactive deployment, +# so one in another state (an older `success`, a `failure` or an `error`) is +# first marked `inactive`; that is safe because a newer SUCCESS deployment of +# the same environment is kept, or the environment itself is gone. +# +# Needs `deployments: write` (GITHUB_TOKEN can have it). Deployments and their +# latest status come from GraphQL, 100 per request: the REST list carries no +# state, and one REST call per deployment took several minutes for 668. +# +# Usage: GH_TOKEN= prune-deployments.sh [--apply] +# Without --apply it prints the counts it would act on and changes nothing. +set -euo pipefail + +repo="${1:?usage: prune-deployments.sh [--apply]}" +apply="${2:-}" +owner="${repo%%/*}" name="${repo#*/}" + +# id environment createdAt latest state node id, every deployment. +# shellcheck disable=SC2016 # $owner, $name and $endCursor are GraphQL variables, not shell ones. +rows="$(gh api graphql --paginate -F owner="$owner" -F name="$name" -f query=' + query($owner: String!, $name: String!, $endCursor: String) { + repository(owner: $owner, name: $name) { + deployments(first: 100, after: $endCursor) { + pageInfo { hasNextPage endCursor } + nodes { id databaseId environment createdAt latestStatus { state } } + } + } + }' --jq '.data.repository.deployments.nodes[] | [.databaseId, .environment, .createdAt, (.latestStatus.state // "NONE"), .id] | @tsv')" +# Listed AFTER the deployments (Antigravity and CodeRabbit on #666): GitHub +# creates an environment at or before its first deployment, so every deployment +# listed above has its environment in this later list unless it was really +# deleted. Listed first, an environment created between the two calls looked +# deleted, and its first, live deployment was deleted with it. +# Captured into a variable first, so a failure on any page fails the script +# (`mapfile < <(gh ...)` would hide it and leave a truncated list; Antigravity +# on #666). `rows` below is captured the same way. +env_list="$(gh api --paginate "repos/$repo/environments?per_page=100" --jq '.environments[].name')" +mapfile -t envs <<< "$env_list" +if [ -z "$env_list" ]; then + echo "::error::no environments listed for $repo; refusing to guess which deployments are live" >&2 + exit 1 +fi + +total="$(printf '%s\n' "$rows" | grep -c . || true)" +if [ "$total" -eq 0 ]; then + echo "no deployments in $repo"; exit 0 +fi + +# Kept, for each EXISTING environment: its newest deployment AND its newest +# SUCCESS deployment. The two differ while a newer deployment is still in +# flight or after it failed, and then the older SUCCESS one is the LIVE one: +# keeping only the newest marked the live deployment inactive and deleted it +# (Antigravity on #666). And anywhere, a deployment in a transient state is +# never touched: it is still running. +keep_ids="$(printf '%s\n' "$rows" | python3 -c ' +import sys +envs = set(sys.argv[1:]) +transient = {"IN_PROGRESS", "QUEUED", "PENDING", "WAITING", "NONE"} +newest, newest_ok, keep = {}, {}, set() +for line in sys.stdin: + did, env, created, state, _ = line.rstrip("\n").split("\t") + if state in transient: + keep.add(did) + if env not in envs: + continue + # createdAt has one-second granularity: break a tie on the id, which grows. + key = (created, int(did)) + if env not in newest or key > newest[env][0]: + newest[env] = (key, did) + if state == "SUCCESS" and (env not in newest_ok or key > newest_ok[env][0]): + newest_ok[env] = (key, did) +keep |= {did for _, did in newest.values()} | {did for _, did in newest_ok.values()} +print("\n".join(sorted(keep))) +' "${envs[@]}")" + +# Mark the not-yet-inactive ones inactive (REST, one call each: they are few, +# since GitHub marks a superseded deployment inactive itself), then delete in +# batches of GraphQL `deleteDeployment` mutations, 50 aliased per request: 668 +# deletions took about ten minutes one REST call at a time. +# Membership tests read the whole list (`grep -xF ... >/dev/null`, never `grep -q`): +# `-q` exits at the first match, the `printf` feeding it then dies of SIGPIPE +# once the list outgrows the pipe buffer, and under pipefail the pipeline fails +# -- a match reported as a miss (CodeRabbit on #666; reproduced with 20,000 +# names). +kept=0 marked=0 would=0 failed=0 +del_ids=() +while IFS=$'\t' read -r did env created state nid; do + if printf '%s\n' "$keep_ids" | grep -xF -- "$did" >/dev/null; then + kept=$((kept + 1)); continue + fi + if [ "$apply" != "--apply" ]; then + would=$((would + 1)); continue + fi + if [ "$state" != "INACTIVE" ]; then + if gh api -X POST "repos/$repo/deployments/$did/statuses" -f state=inactive --silent; then + marked=$((marked + 1)) + else + echo "::warning::could not mark deployment $did ($env, $created) inactive"; failed=$((failed + 1)); continue + fi + fi + del_ids+=("$nid") +done <<< "$rows" + +deleted=0 +# gh writes the JSON response to stdout and its own messages to stderr; kept +# apart, a partial batch failure (`data` and `errors` both present) still +# parses, and counts what was deleted (Antigravity on #666). +err_file="$(mktemp)" +trap 'rm -f "$err_file"' EXIT +for ((i = 0; i < ${#del_ids[@]}; i += 50)); do + chunk=("${del_ids[@]:i:50}") + # The request goes in as a JSON body on stdin, not `-f query=...`: a 50-mutation + # query is over 4 KiB, past the per-argument limit some hosts impose on argv + # ("too long argument ... arg-max-len (4128)" here, 2026-11-15). + # A GraphQL error exits 0 with an `errors` array, so count what succeeded + # from the response, not from the exit status. + out="$(python3 -c ' +import json, sys +ids = sys.argv[1:] +body = " ".join(f"d{n}: deleteDeployment(input: {{id: \"{i}\"}}) {{ clientMutationId }}" for n, i in enumerate(ids)) +print(json.dumps({"query": "mutation { " + body + " }"})) +' "${chunk[@]}" | gh api graphql --input - 2>"$err_file" || true)" + ok="$(printf '%s' "$out" | python3 -c ' +import json, sys +try: + d = json.load(sys.stdin) +except Exception: + print(0); sys.exit() +data = d.get("data") or {} +print(sum(1 for v in data.values() if v is not None)) +')" + deleted=$((deleted + ok)) + if [ "$ok" -ne "${#chunk[@]}" ]; then + failed=$((failed + ${#chunk[@]} - ok)) + echo "::warning::batch at $i: deleted $ok of ${#chunk[@]}: $(head -c 300 "$err_file") $(printf '%s' "$out" | head -c 300)" + fi +done +echo "of $total deployments: kept $kept (the newest of each environment), deleted $deleted (marked inactive first: $marked), would delete $would, failed $failed" +[ "$failed" -eq 0 ] diff --git a/scripts/ci/prune-preview-environments.sh b/scripts/ci/prune-preview-environments.sh new file mode 100644 index 000000000..02515aac4 --- /dev/null +++ b/scripts/ci/prune-preview-environments.sh @@ -0,0 +1,125 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: GPL-3.0-or-later +# +# Delete the Docs7 preview environments whose branch is gone. +# +# WHY THIS EXISTS +# =============== +# The Docs7 GitHub App (Context7's documentation previews) deploys every pull +# request's branch to an environment named "Docs7 Preview: ". GitHub +# creates an environment the first time a deployment names it and never deletes +# one, and Docs7 only marks its old deployments inactive, so every branch that +# ever had a pull request left a permanent environment behind: 33 of them by +# 2026-11-15, deleted by hand then, with 263 Docs7 deployments under them. +# +# Only "Docs7 Preview: " environments are touched, and only when +# no longer exists AND no open pull request has it as its head. "Docs7 +# Production", "github-pages", "copilot" and anything else are never touched. +# +# THE TOKEN +# ========= +# Deleting an environment needs the repository's Administration permission +# (write), which a workflow's GITHUB_TOKEN cannot be granted (it is not one of +# the `permissions:` keys), so this needs a fine-grained personal access token +# scoped to this repository with Administration: read and write, in +# ENV_CLEANUP_TOKEN (see .github/workflows/preview-env-cleanup.yml for why it is +# only ever used from the default branch). Listing needs no such permission. +# +# Usage: GH_TOKEN= prune-preview-environments.sh [--apply] +# Without --apply it prints what it would delete and changes nothing. +set -euo pipefail + +repo="${1:?usage: prune-preview-environments.sh [--apply]}" +apply="${2:-}" +prefix='Docs7 Preview: ' + +# Every listing is captured into a variable BEFORE it becomes an array: a plain +# assignment fails the script under `set -e` when `gh` fails on any page, where +# `mapfile < <(gh ...)` would hide the failure and leave a truncated list -- +# and a truncated branch or pull-request list here means deleting a live +# preview (Antigravity on #666). Every environment, every page. +env_list="$(gh api --paginate "repos/$repo/environments?per_page=100" --jq '.environments[].name')" +mapfile -t envs <<< "$env_list" +if [ -z "$env_list" ]; then + # A repository with Pages always has at least `github-pages`; zero means the + # listing failed or the token cannot read environments, not that all is clean. + echo "::error::no environments listed for $repo; refusing to report it clean" >&2 + exit 1 +fi +pr_list="$(gh api --paginate "repos/$repo/pulls?state=open&per_page=100" --jq '.[].head.ref')" +open_heads=() +# An empty listing (no open pull requests) must give no heads, not one empty +# one (Antigravity on #666). +[ -z "$pr_list" ] || mapfile -t open_heads <<< "$pr_list" +# Every branch name in one paginated GraphQL query (100 per request), rather +# than a REST lookup per preview environment. +owner="${repo%%/*}" rname="${repo#*/}" +# shellcheck disable=SC2016 # $owner, $name and $endCursor are GraphQL variables, not shell ones. +branch_list="$(gh api graphql --paginate -F owner="$owner" -F name="$rname" -f query=' + query($owner: String!, $name: String!, $endCursor: String) { + repository(owner: $owner, name: $name) { + refs(refPrefix: "refs/heads/", first: 100, after: $endCursor) { + pageInfo { hasNextPage endCursor } + nodes { name } + } + } + }' --jq '.data.repository.refs.nodes[].name')" +mapfile -t branches <<< "$branch_list" +if [ -z "$branch_list" ]; then + echo "::error::no branches listed for $repo; refusing to treat every preview as stale" >&2 + exit 1 +fi + +# Membership tests read the whole list (`grep -xF ... >/dev/null`, never `grep -q`): +# `-q` exits at the first match, the `printf` feeding it then dies of SIGPIPE +# once the list outgrows the pipe buffer, and under pipefail the pipeline fails +# -- a match reported as a miss (CodeRabbit on #666; reproduced with 20,000 +# names). +kept=0 deleted=0 would=0 failed=0 +for name in "${envs[@]}"; do + case "$name" in "$prefix"*) ;; *) continue ;; esac + branch="${name#"$prefix"}" + if [ -z "$branch" ]; then + echo "keep $name (no branch name to check)"; kept=$((kept + 1)); continue + fi + if printf '%s\n' "${open_heads[@]}" | grep -xF -- "$branch" >/dev/null; then + echo "keep $name (an open pull request's head)"; kept=$((kept + 1)); continue + fi + if printf '%s\n' "${branches[@]}" | grep -xF -- "$branch" >/dev/null; then + echo "keep $name (the branch still exists)"; kept=$((kept + 1)); continue + fi + # Recheck just before acting (CodeRabbit on #666): the lists above are a + # snapshot, and a branch recreated, or a pull request opened, since then + # must not lose its preview. One branch lookup and one pull-request lookup + # per candidate; there are few. A failed lookup counts as "still in use". + enc_branch="$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$branch")" + # `gh api` exits non-zero on the 404 that means "gone", so its exit status + # cannot be the test (under pipefail it discarded the status line, and every + # candidate looked "could not be checked"); the response's status line is. + status="$(gh api -i "repos/$repo/branches/$enc_branch" 2>/dev/null || true)" + status="${status%%$'\n'*}" + case "$status" in *" 404"*) ;; *) + echo "keep $name (the branch exists, or could not be checked, on a recheck)"; kept=$((kept + 1)); continue ;; + esac + # Every open pull request's head, whoever owns it: a `head=owner:branch` + # filter misses a fork's `alice:topic`, whose preview Docs7 also names + # "Docs7 Preview: topic" (CodeRabbit on #666). + if ! heads_now="$(gh api --paginate "repos/$repo/pulls?state=open&per_page=100" --jq '.[].head.ref')" \ + || printf '%s\n' "$heads_now" | grep -xF -- "$branch" >/dev/null; then + echo "keep $name (an open pull request, or a failed check, on a recheck)"; kept=$((kept + 1)); continue + fi + enc_env="$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$name")" + if [ "$apply" = "--apply" ]; then + # One failed delete is recorded and the run goes on to the rest, failing at + # the end (Antigravity on #666), as prune-deployments.sh does. + if gh api -X DELETE "repos/$repo/environments/$enc_env" --silent; then + echo "delete $name"; deleted=$((deleted + 1)) + else + echo "::warning::could not delete environment $name"; failed=$((failed + 1)) + fi + else + echo "would delete $name"; would=$((would + 1)) + fi +done +echo "kept $kept, deleted $deleted, would delete $would, failed $failed (of ${#envs[@]} environments)" +[ "$failed" -eq 0 ] diff --git a/services/hosted/package-lock.json b/services/hosted/package-lock.json index b75222662..ef46bac51 100644 --- a/services/hosted/package-lock.json +++ b/services/hosted/package-lock.json @@ -1,12 +1,12 @@ { "name": "rustynes-hosted", - "version": "3.7.0", + "version": "3.7.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "rustynes-hosted", - "version": "3.7.0", + "version": "3.7.1", "license": "GPL-3.0-or-later", "devDependencies": { "@cloudflare/vitest-plugin": "1.8.0", diff --git a/services/hosted/package.json b/services/hosted/package.json index f6db9135c..b4a50f8a1 100644 --- a/services/hosted/package.json +++ b/services/hosted/package.json @@ -1,6 +1,6 @@ { "name": "rustynes-hosted", - "version": "3.7.0", + "version": "3.7.1", "private": true, "description": "RustyNES hosted services: the netplay signalling lobby (Durable Object), Cloudflare TURN credential minting, and the browser RetroAchievements proxy.", "license": "GPL-3.0-or-later", diff --git a/services/hosted/wrangler.jsonc b/services/hosted/wrangler.jsonc index c89f55ab5..9e9e78e16 100644 --- a/services/hosted/wrangler.jsonc +++ b/services/hosted/wrangler.jsonc @@ -101,7 +101,7 @@ // leading `RustyNES/` token: RetroAchievements identifies and allowlists // the client by it, and src/ra.ts refuses to forward without it. Bump the // product and rcheevos versions with each release. - "RA_USER_AGENT": "RustyNES/3.7.0 (Web wasm32) rcheevos/12.5.0", + "RA_USER_AGENT": "RustyNES/3.7.1 (Web wasm32) rcheevos/12.5.0", // Abuse guards (README.md "Spend guards"; src/budget.ts): forwarded calls // per client IP per rolling hour, `login2` calls per IP per hour, and // forwarded calls per UTC day, all callers together. diff --git a/to-dos/ROADMAP.md b/to-dos/ROADMAP.md index 331c4c7aa..e534affa2 100644 --- a/to-dos/ROADMAP.md +++ b/to-dos/ROADMAP.md @@ -57,7 +57,7 @@ v2.8.0 → v0.9.7; the synthesis itself = **v1.0.0**. ## Status -- **Current release:** **RustyNES v3.7.0 "Spindle"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — the RetroArch core loads on Apple Silicon Macs again. Built on **v3.4.1 "Beacon"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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. Built on **v2.9.5 "Caliper"** — every open accuracy item measured, then fixed or closed: four fixes red first (the `apu_test` frame-counter coincidence, the composite 2C02 scanline-0 sprite glitch, OAM DMA filling the PPU I/O latch, KS7032 at `$6000`), 49 unreferenced test ROMs gated, the MMC3 M2-edge filter lever tried and refuted, and a save-state epoch (`PPU_SNAPSHOT_VERSION` 11). Built on **v2.9.4 "Plumb"** — the records made true, and CI made to run what it only linted: v3.0.0 decided as the API major with a release-candidate core (ADR 0043), CI now running 63 feature-gated tests it never ran, the eight fuzz targets and a 70% line-coverage floor, the mapper tiers, store status and deferred-features catalogue corrected against the code, and the OAM-decay model recorded as derived from Mesen2. Built on **v2.9.3 "Handset"** — the old review threads closed and the mobile run prepared: every dependency moved to its newest release (egui 0.36 with wgpu 30, rcheevos 12.5.0), all 244 review threads left unanswered on PRs #7-#97 answered and the ten findings that still held fixed (Action 53 multicarts rebuilt to the NESdev spec, and a ROM header editor that no longer rewrites bytes you did not edit or saves mappers from 16 up as the wrong mapper), and the Android unit tests and the iOS renderer added to CI. Built on **v2.9.2 "Candidate"** — the full audit acted on, and the release-candidate pair: all 32 findings of a fifth audit have a verdict and 16 are fixed, save states keep the cartridge RAM of twelve board families they used to drop, the MiSTer core no longer loses an NMI raised inside a DMA, and both bitstreams are cut for the SuperStation One session. Built on **v2.9.1 "Hone"** — what the optimisation bars measure, and what clears them: the A/B tool had been timing the old code on both sides of every code comparison and is fixed, a two-screen Vs. cabinet saves about 9x faster, the off-die MiSTer build keeps CHR in its own SDRAM bank, and both bitstreams are pinned at fitter seed 2 and rebuild byte-identically. Built on **v2.9.0 "Survey"** — every audit re-checked, and the SuperStation One surveyed: a Power Cycle no longer erases your save, the off-die MiSTer build boots without the menu core, and 39 new audit findings are fixed or dispositioned. Built on **v2.8.4 "Tether"** — the MiSTer core's SDRAM build, made trustworthy: its controller now reads data on the edge the memory presents it (every off-die read would have been wrong on hardware, and only the new SDRAM timing constraints could see it), the power-up sequence and CAS-latency-3 reads follow the datasheet, the arbiter can no longer return the wrong byte or lose a write, the off-die bitstream builds from a script, both builds are swept and pinned at fitter seed 5, and the co-simulation ladder runs all 165 gates from a clean checkout. Built on **v2.8.3 "Rivet"** — the MiSTer core's reset, area and comments, measured: every reset is released on the clock that uses it and the timing analysis now checks each release, the CPU is about 4% smaller by two exact rewrites the fit report confirmed, four false comments are corrected, and the co-simulation ladder runs from a fresh checkout (164 of its 165 gates; the last needs a hand-built ROM no generator produces). **No hardware has run any bitstream.** +- **Current release:** **RustyNES v3.7.1 "Imprint"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — the RetroArch core loads on Apple Silicon Macs again. Built on **v3.4.1 "Beacon"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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"** — 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. Built on **v2.9.5 "Caliper"** — every open accuracy item measured, then fixed or closed: four fixes red first (the `apu_test` frame-counter coincidence, the composite 2C02 scanline-0 sprite glitch, OAM DMA filling the PPU I/O latch, KS7032 at `$6000`), 49 unreferenced test ROMs gated, the MMC3 M2-edge filter lever tried and refuted, and a save-state epoch (`PPU_SNAPSHOT_VERSION` 11). Built on **v2.9.4 "Plumb"** — the records made true, and CI made to run what it only linted: v3.0.0 decided as the API major with a release-candidate core (ADR 0043), CI now running 63 feature-gated tests it never ran, the eight fuzz targets and a 70% line-coverage floor, the mapper tiers, store status and deferred-features catalogue corrected against the code, and the OAM-decay model recorded as derived from Mesen2. Built on **v2.9.3 "Handset"** — the old review threads closed and the mobile run prepared: every dependency moved to its newest release (egui 0.36 with wgpu 30, rcheevos 12.5.0), all 244 review threads left unanswered on PRs #7-#97 answered and the ten findings that still held fixed (Action 53 multicarts rebuilt to the NESdev spec, and a ROM header editor that no longer rewrites bytes you did not edit or saves mappers from 16 up as the wrong mapper), and the Android unit tests and the iOS renderer added to CI. Built on **v2.9.2 "Candidate"** — the full audit acted on, and the release-candidate pair: all 32 findings of a fifth audit have a verdict and 16 are fixed, save states keep the cartridge RAM of twelve board families they used to drop, the MiSTer core no longer loses an NMI raised inside a DMA, and both bitstreams are cut for the SuperStation One session. Built on **v2.9.1 "Hone"** — what the optimisation bars measure, and what clears them: the A/B tool had been timing the old code on both sides of every code comparison and is fixed, a two-screen Vs. cabinet saves about 9x faster, the off-die MiSTer build keeps CHR in its own SDRAM bank, and both bitstreams are pinned at fitter seed 2 and rebuild byte-identically. Built on **v2.9.0 "Survey"** — every audit re-checked, and the SuperStation One surveyed: a Power Cycle no longer erases your save, the off-die MiSTer build boots without the menu core, and 39 new audit findings are fixed or dispositioned. Built on **v2.8.4 "Tether"** — the MiSTer core's SDRAM build, made trustworthy: its controller now reads data on the edge the memory presents it (every off-die read would have been wrong on hardware, and only the new SDRAM timing constraints could see it), the power-up sequence and CAS-latency-3 reads follow the datasheet, the arbiter can no longer return the wrong byte or lose a write, the off-die bitstream builds from a script, both builds are swept and pinned at fitter seed 5, and the co-simulation ladder runs all 165 gates from a clean checkout. Built on **v2.8.3 "Rivet"** — the MiSTer core's reset, area and comments, measured: every reset is released on the clock that uses it and the timing analysis now checks each release, the CPU is about 4% smaller by two exact rewrites the fit report confirmed, four false comments are corrected, and the co-simulation ladder runs from a fresh checkout (164 of its 165 gates; the last needs a hand-built ROM no generator produces). **No hardware has run any bitstream.** - **The v4.x lines after v4.0.0 (drafted 2026-10-17):** the power-user line v4.1.0-v4.5.0 ([`plans/v4.x-power-user-line-plan.md`](plans/v4.x-power-user-line-plan.md), D33), then the agents-and-scale line v4.6.0-v4.9.0 ([`plans/v4.x-agents-and-scale-line-plan.md`](plans/v4.x-agents-and-scale-line-plan.md), D34): language models playing the games, fuzzing and optimal-run search at scale, and a GPU lane core behind a measured go/no-go. - **The line after v3.0.0 (drafted 2026-10-07):** [`plans/v3.1-to-v4.0-line-plan.md`](plans/v3.1-to-v4.0-line-plan.md) indexes v3.1.0 → v4.0.0, with one plan file per release and the maintainer's 29 decisions (D1-D29) tabled there. In order (D29 moved the hardware release to the end of v3.9.x the same day): - v3.0.1 "Mortar" (released 2026-10-07); @@ -74,7 +74,7 @@ v2.8.0 → v0.9.7; the synthesis itself = **v1.0.0**. - **Programme after v2.4.0 — the v2.4.1 → v2.5.0 "Fabric" line, and the v2.6–v2.9 programme behind it** *(since 2026-09-22 the programme ends at v3.0.0; ADR 0041)*. An **independently-written NES core in SystemVerilog for MiSTer FPGA and the Retro Remake SuperStation One, verified against RustyNES as an oracle.** Not a port, and it cannot be one: a MiSTer core is SystemVerilog compiled by Quartus 17.0.2 into a Cyclone V bitstream. The reference firewall therefore extends to HDL — `NES_MiSTer` and `fpganes` `rtl/` are **strict black boxes**, instantiable as opaque modules to compare *outputs*, never readable as source. **v2.5.0 is scoped to "the 6502 rung closes"** — the co-simulation harness plus a cycle-exact 6502, gated, **as planned**, on nestest 0-diff and per-cycle bus equality — of which **per-cycle bus equality was achieved and nestest 0-diff was not**: it stops at a `$2002` read where *both sides address it* and only the data differs, because the DUT has no PPU. That and the 5 M-cycle window are **reclassified as rung-3 acceptance criteria** rather than carried as v2.5.0 debt — because the arithmetic does not support more: a from-scratch cycle-accurate NES core is **7–13 months FTE** against a two-to-four-week window at demonstrated cadence. PPU, APU and MiSTer integration are **v2.6–v2.9**; stating that now is better than discovering it at v2.4.6. The design is **replay, not lockstep** (the determinism contract makes a pre-recorded trace exactly the trace a lockstep run would produce, and `Nes` has no per-cycle step to lockstep *with*), **no DPI-C** (it would put `` `ifdef SIMULATION `` guards into RTL that must also pass Quartus — the exact construct that lets a simulated netlist drift from the synthesised one), and **hash first, capture on divergence** (a 4200-frame AccuracyCoin run is ~7.5 GB of per-cycle CSV; 4096-cycle hash checkpoints are ~480 KB). **Two risks are accepted in writing:** the core may be **declined as a duplicate** — `NES_MiSTer` already scores 121/125 on AccuracyCoin, and *real Famicom AV hardware also scores ~121/125*, so there is no published accuracy headroom; and **the oracle can be wrong**, since 141/141 is not "matches silicon", so every rung is labelled by whether it has an **independent** oracle. Retro Remake is a planned fallback home, not a contingency. See ADR 0037, `docs/mister.md`, and [`plans/v2.5.0-fabric-plan.md`](plans/v2.5.0-fabric-plan.md). - **Programme after v2.5.0 — the v2.5.1 → v2.7.0 line: the rest of the console, and a contributable package.** The Fabric line is delivered and the 6502 rung is closed; this line builds the PPU, APU, mappers and MiSTer integration, and takes the core to a state worth submitting to MiSTer-devel. **Maintainer decisions, 2026-08-23:** hardware is **both boards eventually** — a DE10-Nano **plus the SDRAM add-on** (mandatory: the NES reads cartridge ROM directly and the onboard DDR3 is too slow) and a SuperStation One (128 MB integrated), with **one `.rbf` booting both** turning "SS1 runs MiSTer cores unmodified" from an inherited claim into a measured one; mappers are **the top six** — NROM, MMC1, UxROM, CNROM, MMC3, AxROM, ~90% of the licensed library by title count, explicitly **not** FDS, expansion audio, or the remaining ~168 families; and v2.7.0 is **scoped to what genuinely fits**, with the arithmetic stated up front (**rung 3 8–16 wk · rung 4 4–8 wk · rung 5 2–4 wk + a 4–12 wk tail · rung 6 2–4 wk · rung 7 4–8 wk = 20–40 weeks FTE** before the AccuracyCoin tail, across twenty release slots — **milestones, not dates**). **Rung 6 comes before rung 7 deliberately**: NROM at 327 Kb fits on-chip, so hardware bring-up needs no memory controller, and getting a board in the loop before writing the SDRAM controller de-risks the second largest technical item. Two v2.5.0 gates — **nestest 0-diff and the 5 M-cycle window** — are not carried as debt but reclassified as **rung-3 acceptance criteria**: both stop at a `$2002` read where *both sides address it* and only the data differs, because the DUT has no PPU. The contribution requirements were **fetched from the MiSTer-devel wiki rather than recalled**, and one line of it is the whole case for this programme: on AI-generated code the project asks for *"a minimum reasonable bar for readability and… evidence of quality and accuracy testing"* — the co-simulation apparatus **is** that evidence, and no incumbent core can show its equivalent. See [`plans/v2.7.0-mister-core-plan.md`](plans/v2.7.0-mister-core-plan.md), [`mister/`](mister/), and the four dated research files in `ref-docs/`. *Superseded 2026-09-22 by ADR 0041: the hardware-verified core and the contribution package are v3.0.0.* - **Historical detail — v2.2.4** (2026-07-24) — a **libretro / RetroArch distribution** cut whose purpose is that the RustyNES core **builds and installs cleanly through the Libretro buildbot** () for in-RetroArch use. **Zero emulation-core changes** — the deterministic `#![no_std]` chip stack, save-state / TAS / netplay formats, and every golden vector are byte-identical to v2.2.3, so **AccuracyCoin holds 141/141 (100.00%)**, nestest 0-diff, by construction. The work is a libretro-completeness audit + metadata correction: the core is confirmed to inherit every v2.2.3 change automatically (the fast-dot-path default, the `PPU_SNAPSHOT_VERSION` 8 / APU v4 save-state schema handled transparently by the dynamic `snapshot_core_into` sizing, the `Mapper::mix_audio` i32 widening, the Zapper model, and the `mNNN_` mapper rename), and both buildbot cross-ABIs the GitHub gate models — `x86_64-pc-windows-gnu` and `aarch64-linux-android` — build clean. `rustynes_libretro.info` (the metadata RetroArch's core downloader reads) is corrected: **`disk_control` `false` → `true`** (the FDS multi-side Disk Control interface has been wired since the buildbot recipe landed, but was advertised as absent — the real fix), `display_version` `v1.0.0` → `v2.2.4`, and the mapper count `168` → `172`. Also: the reviewer-tooling standardization onto the shared Antigravity template rides along (`scripts/agy-review.sh` + workflow). Documented libretro follow-up: **core options** (region / overscan / palette / accuracy toggles) remain unexposed (`core_options = "false"` is accurate, not stale) — a deliberate future enhancement, not a v2.2.4 gap. See `docs/STATUS.md` (single source of truth) + `CHANGELOG.md` `[2.2.4]` + `docs/libretro/`. -- **Release line since v2.1.0:** the v2.1.x **"Fathom"** accuracy line (v2.1.0 → v2.1.10) → **v2.2.0 "Capstone"** (the milestone cut closing the "deepen the existing project" run) → **v2.2.1** (housekeeping) → **v2.2.2 "Conduit"** (build / distribution / CI-integrity) → **v2.2.3 "Datum"** (performance appraisal + the last two Holy Mapperel residuals closed) → **v2.2.4 "Cartridge"** (the libretro/RetroArch distribution cut) → **v2.2.5 "Colophon"** → **v2.2.6 "Almanac"** → **v2.2.7 "Timbre II"** → **v2.2.8 "Aperture II"** → **v2.2.9 "Studio II"** → **v2.3.0 "Datum II"** → **v2.3.1 "Plumb Line"** → **v2.3.2 "Lucid"** → **v2.3.3 "Cadence"** → **v2.3.4 "Ledger"** → **v2.3.5 "Manifest"** → **v2.3.6 "Sounding"** → **v2.3.7 "Overtone"** → **v2.3.8 "Parallax"** → **v2.3.9 "Crucible"** → the **v2.4.x "Fabric"** co-simulation line (**v2.4.1 "Fabric"** → **v2.4.2 "Cairn"** → **v2.4.3 "Touchstone"** → **v2.4.4 "Ignition"** → **v2.4.5 "Compass"** → **v2.4.6 "Abacus"** → **v2.4.7 "Keystone"** → **v2.4.8 "Palimpsest"** → **v2.4.9 "Plumbline II"** → **v2.5.0 "Rungwork"** → **v2.5.1 "Retrace"** → **v2.5.2 "Dormant"** → **v2.5.3 "Hysteresis"** → **v2.5.4 "Escapement"** → **v2.5.5 "Raster"** → **v2.5.6 "Vestige"** → **v2.5.7 "Collimation"** → **v2.5.8 "Blanking"** → **v2.5.9 "Overture"** → **v2.6.0 "Assay"** → **v2.6.1 "Interleave"** → **v2.6.2 "Witness"** → **v2.6.3 "Mainspring"** → **v2.6.4 "Rubric"** → **v2.6.5 "Muster"** → **v2.6.6 "Chassis"** → **v2.6.7 "Detent"** (the bitstream becomes a published, reproducible release artifact and a one-cycle disagreement is attributed rather than fitted away) → **v2.6.8 "Arrears"** (the gates the previous release fixed and never widened: four of six denied checkpoint streams had been passing unnoticed, three of them not run by the suite at all, and nestest widens 19x and gains the nine-field comparison that closes the gate's stated `nmi_line` blind spot) → **v2.6.9 "Abeyance"** (an exclusion hides improvement as well as regression -- both denied co-simulation streams close, and the larger one was a defect in the HARNESS rather than the console, carried for seven releases behind the phrase "by design") → **v2.6.10 "Inference"** (the cartridge meets the synthesiser, and simulation could not have asked the question -- rung 7's five boards had never been through Quartus, and `chr` written from two separate `always_ff` blocks could not infer as an M10K, so 128 KB stayed in flip-flops: 1,048,576 registers against roughly 166,000. The fix is behaviourally invisible -- 141 gates unchanged -- and the release carries the bitstream the previous one could not produce) → **v2.6.11 "Exposure"** (a picture is a gate the ladder did not have -- all 141 co-simulation gates green and two of six commercial games rendering wrong, because only THREE of those gates compare a framebuffer and all three ship CHR-ROM, so a CHR-RAM write taking the shared-pin composite address built for fetches was reached 9,600 times and compared never)) -> **v2.6.12 "Groundwork"** (the bitstream was an NROM-only console -- `emu.sv` left `cart_mapper`, `cart_prg_16k_banks` and `cart_chr_8k_banks` unconnected, so Quartus tied all three to GND and the fitted cartridge was mapper 0 with 8 KiB of PRG and 8 KiB of CHR against a declared 256 and 128; no gate could see it because `emu.sv` is not in the testbench file list, so all 142 gates exercised a correctly-configured cartridge, and Quartus said so three times in messages that cite an instance path rather than a file) -> **v2.6.13 "Slack"** (the cartridge outgrows the die -- an SDR SDRAM controller, a behavioural part model, a four-way arbiter and a console bridge written from the AS4C32M16SB-7 datasheet, and three consumers measured to three different budgets rather than the one figure the previous step assumed; the PPUDATA port leaves the shared bus through a handshake and that fix shipped a defect only a banked cartridge could see, the request carrying the raw PPU address where the mapper's translation was needed, so every banked-CHR board read bank zero; off the die the console passes 142 of 142 and it still ships on the die, because an off-die core cannot run without the add-on) -> **v2.6.14 "Docket"** (the submission checklist becomes auditable -- 30 boxes, 16 unticked and fourteen of those saying nothing about why, so an unticked box could not be told apart from work outstanding, work blocked elsewhere, and work already done and never ticked; the third case occurred five times. One box asked `docs/provenance.md` to state that no NES core was ever opened, which that document's own Do-not-self-certify section forbids, so it could only have been ticked by writing the sentence the provenance rules exist to prevent. Re-measuring the ticked half found two claims that had expired, the task board four delivered items never ticked and an SDRAM precondition the previous release did not follow, and its claim that MMC1 was unimplemented is retracted) → **v2.6.15 "Warrant"** (the claims the submission will make become checkable, and the instrument pays the oracle back — the `.rbf` name this core shipped would have distributed NOTHING, because `Distribution_MiSTer`'s builder skips any file whose stem does not end in `_` plus eight digits, so an accepted core would appear in the Cores table and ship nothing with no error anywhere; two of the four R1/R2 residuals ADR 0002 closed turn out never to have been IRQ-timing residuals, resting on an assertion blargg WITHDREW in the successor ROM; `sys/` verbatim, the `.qsf`'s single seed table and the bitstream name all become checks instead of claims; the nine rung-1 gates run in CI against a PINNED oracle commit, so the accuracy evidence stops being a document describing a check a reader cannot run; `cpu_interrupts_v2` lands on the DUT as the first INDEPENDENT interrupt oracle, five of five; and `T-ORACLE-001`'s opening claim is retracted — RustyNES does clock the MMC3 counter on the pre-render line, which `2-details` sub-test 8 has asserted all along) → **v2.6.16 "Interlock"** (the arbiter's numbers describe a stimulus, not the console: the gate's worst case issues a CHR and a PRG request on the same cycle and the running console never does — zero coincidences and a minimum separation of two over fifteen million SDRAM cycles — so both published figures are wrong about it in opposite directions, the CPU MEETING its deadline at 24 against 24 on all 240,303 requests where the gate said it missed by four, and the fetch reaching 23 against a derived 22 that a `CHR_LAT` sweep shows understates the real tolerance by at least nine cycles; the slot-scheduled arbiter this version was scoped around is therefore NOT built, and is still worth building because zero margin means one added cycle anywhere breaks the CPU) → **v2.6.17 "Terminus"** (a write lands where the cycle ENDS, and this core does not move to meet it. The AccuracyCoin and TriCNES oracles re-sync to upstream, and the battery grows 141 → 144 assigned tests across two new pages that RE-HOME eleven existing PPU tests, so a re-sync is not an append and a suite-keyed baseline has to be regenerated rather than extended. `OAM2Address` becomes a live counter through sprite fetch and the frozen fetch reads index 0 for every byte, closing two of the three new tests and carrying an approved SAVE-STATE EPOCH — `PPU_SNAPSHOT_VERSION` 8 → 9, so pre-v9 `.rns` states no longer load. The third names the dots its two `$2001` writes land on, which is how the core came to be measured TWO DOTS EARLY on both: a 6502 commits a write at phi2, the last of a CPU cycle's three PPU dots, and this core applies PPU register writes at M2-low, the first. The move was then MADE, measured against a first-difference control captured beforehand, and NOT ADOPTED — the write alone reads 141/144 and breaks the independent `ppu_vbl_nmi/10-even_odd_timing`, and the best combination found reads 142/144 against the 143/144 that ships, for a save-state epoch and six re-baselined goldens. `mask_for_skip_check` is PROVEN to be a compensation for the placement — under phi2 it needs one delay stage rather than two — and two of its three dependants are still un-re-derived, so adopting the mechanism now would replace a documented compensation with an undocumented one. `Misaligned OAM2 Address` was also found to be passing via TWO CANCELLING ERRORS, both since fixed independently. Ships one core fix nothing in the corpus could see — the misaligned-OAM `+4 & $FC` realignment, reached 114 times per battery run out of 56,953,944 out-of-range branches and pinned by a targeted test because no ROM's verdict moves — plus `terminus_control.rs` as a standing first-difference gate. The follow-up version the write-placement work had been scoped into is FOLDED here: that split existed because Terminus was to be a scheduler change with its own ADR and a full re-baseline, and the refutation means it is not — so v2.6.17 carries both). v2.6.18 "Errata" closes the last AccuracyCoin entry on top of it, and v2.6.19 "Accession" carried both into the FPGA core, v2.6.20 "Telltale" made the OAM2 counter observable, v2.6.21 "Steward" gave the core battery saves and gated CHR writes during rendering, v2.6.22 "Rigging" built the instruments a board would need before the board existed, v2.6.23 "Pulse" closed the CHR-during-rendering divergence by making the `$2007` access pulse the rendering pipeline's load instead of computing its own, and v2.7.0 "Palisade", the first of the ADR 0041 audit line, made a corrupt save state fail at restore rather than one tick later, stopped pulse 1 muting on the `$4001 = $08` sweep idiom, and gave the save-state fuzz target the reach to find five defects the audit had not, v2.7.1 "Keepsake" stopped six cartridge boards writing an empty battery save and moved every user file the frontend writes onto the atomic writer, v2.7.2 "Bankroll" gave MMC1, MMC5 and Namco 163 the banks their boards have and made `$6000-$7FFF` read open bus on the 205 board variants with nothing there, v2.7.3 "Hearth" made the desktop keep battery saves, closed three ways around the Lua sandbox, gated script HTTP destinations, and brought audio back after a device change, v2.7.4 "Pocket" kept the Android and iOS apps alive through an internal error, gave both battery saves, paused them and released audio when they leave the screen, and made their saves atomic, v2.7.5 "Tally" closed the core audit's twelve performance proposals (eleven by measurement, one adopted: the audio buffer keeps its capacity), deprecated 18 dead bus methods and `ApuBus`, and closed the core and frontend ledgers, v2.7.6 "Recount" measured alone the six deletions v2.7.5 had bounded only together (five zero; the sixth, never reached by the benchmarks before, bounds at 0.2%), turned three redundant fast-path stores into an assertion, and shipped the contributed libretro buildbot fixes and targets, v2.8.0 "Bulkhead" opened the v2.8.x libretro + RTL audit line: the libretro core unwinds and contains a panic at its own boundary, keeps save states the right size with a Zapper, withdraws its memory maps on unload, loads through the standard `retro_game_info` via a vendored binding, and the save state carries the internal data bus, v2.8.1 "Gasket" closed the libretro audit: Four Score, four described ports (the list now NULL-terminated, where RetroArch had read past it), the Zapper unplugged, unclipped expansion audio, UNIF, and a Makefile that honours its callers, v2.8.2 "Solder" corrected the MiSTer core's on-die RTL against the oracle and the wiki (MMC3 acknowledge, SNROM PRG-RAM, the triangle and noise reload drop, the `$2002` latch) and found the audit's MMC1 finding inverted: the emulator was the one ignoring a reset, and v2.8.3 "Rivet" released every reset on the clock that uses it, cut the CPU by about 4% with two exact rewrites the fit report confirmed, and made the ladder run from a fresh checkout (164 of its 165 gates, a claim v2.8.4 found overstated), and v2.8.4 "Tether" closed the v2.8.x line: it found every off-die read would have been sampled a clock late on hardware (the SDRAM model and controller shared the error, and only the new SDRAM timing constraints could see it) and fixed both, pinned both builds at fitter seed 5 after a sweep of each, and made the ladder run all 165 gates from a clean checkout, and v2.9.0 "Survey" opened the v2.9.x line by re-running all four audits (139 rows re-verified, none regressed, 39 new findings fixed or dispositioned), including a Power Cycle that erased the battery save and an off-die MiSTer build that hung under `bootcore=`, v2.9.1 "Hone" found that the A/B tool had been timing the old code on both sides and re-measured what it had rejected, made a Vs. cabinet save-state about 9x faster, moved the off-die build's CHR into its own SDRAM bank, and pinned both builds at fitter seed 2 with two byte-identical clean compiles each, v2.9.2 "Candidate" triaged a fifth, 32-finding audit of both repositories (16 fixed, each finding with its evidence in its ledger), made save states keep the cartridge RAM of twelve board families that dropped it, fixed the MiSTer CPU losing an NMI raised inside a DMA, and cut the release-candidate bitstream pair for the SuperStation One session, v2.9.3 "Handset" moved every dependency to its newest release, answered all 244 review threads left open on PRs #7-#97 and fixed the ten findings that still held (mapper 28 rebuilt, a header editor that writes only what you change), and prepared the mobile device run, which the maintainer then moved after v3.0.0 with the board session, v2.9.4 "Plumb" recorded v3.0.0 as the API major with a release-candidate core (ADR 0043), made CI run the feature-gated tests, fuzz targets and a coverage floor it had only linted or never had, and corrected the records against the code, v2.9.5 "Caliper" gave every open accuracy item an outcome: blargg's `apu_test` frame-counter coincidence, the composite 2C02's odd-frame scanline-0 sprite pixel, OAM DMA filling the PPU I/O latch and KS7032's `$6000` window fixed red first, 49 unreferenced test ROMs gated, the MMC3 M2-edge filter lever tried and refuted, and a save-state epoch (`PPU_SNAPSHOT_VERSION` 11), v2.9.6 "Roster" added seventeen mapper families from their NESdev pages (174 → 191), promoted GTROM to Curated with a modelled SST39SF040 whose saves persist, corrected mapper 4's NES 2.0 submappers (MMC6, NEC, MC-ACC, T9552), and re-baselined the local commercial suites, which had drifted unread since about v2.0.0, v2.9.7 "Tandem" brought the desktop's features to the web and phones (battery saves in the browser, Vs. DualSystem on web and mobile, FDS and NSF on mobile), made the release binaries the full native build, and fixed a PPU A12 defect real games exposed: the PPU reported one pulse per scanline where the console makes eight, so Acclaim's MC-ACC, the J.Y. ASIC and mapper 91 had counted eight times slow, v2.9.8 "Vanguard" carried v3.0.0's planned breaking changes ahead of it (a save identity that ignores the header, older save states and movies refused, movies and netplay that record the machine, the ADR 0042 API removals), booted every one of 748 staged dumps and fixed the defects that turned up, and made the game database's corrections reach every platform, v2.9.9 "Ballast", the release candidate for v3.0.0, re-ran all four audits and fixed what they found, raised the MMC3 IRQ by the NESdev rule (T-ORACLE-001) and gave the MMC5 the chip's CHR set selection (which fixed *Uchuu Keibitai SDF*), made audio exact across a save state, moved the MiSTer core's oracle pin onto it with the APU and PPU parity that opened, and cut the release-candidate bitstream pair at seed 6 (a seed-8 pair was withdrawn when the RTL changed after it), v3.0.0 "Cornerstone", the API major, gathered every break since v2.x in one place, made movies and netplay carry a core timing epoch so a version that emulates differently is refused with a reason (ADR 0045), took the last struct-extensibility breaks, closed blargg's `4-scanline_timing` in the emulator and the MiSTer core (T-MMC3-BG-A12), and shipped that core as a release candidate, not hardware-verified, and v3.0.1 "Mortar" unbanked *Famicom Yarou Vol.1*'s CHR-RAM (raising the emulation epoch to 2), reached the MiSTer core's odd-frame A12 exception with a new test ROM that found a one-cycle defect, moved the toolchain and the libretro buildbot to Rust 1.99, answered every bot review left since PR #1, recorded the shared Bisqwit NTSC pass as derived and moved the TriCNES source out of the repository, and wrote the plan to v4.0.0 (`to-dos/plans/v3.1-to-v4.0-line-plan.md`), and v3.1.0 "Bellwether" re-synced AccuracyCoin to upstream `f5f41dc2` and fixed the two defects it found (raising the epoch to 3), made the CPU overclock and the sprite-limit option work and travel with movies and netplay, corrected PAL emphasis and the alternate MMC3, gave the Vs. cabinet rewind and run-ahead, and matched the MiSTer core to all of it, including a `$2006` timing rule it had never been tested against, and v3.2.0 "Confluence" brought every v3.2.0 branch in both repositories into one release: 17 mapper families (191 to 208, with the Bandai Datach), the VRC4 IRQ mode read the right way round and the VRC2 and *Fire Hawk* mirroring fixes (raising the epoch to 4), an AI remediation branch audited change by change before anything was kept, netplay protocol 8, libretro states of about 16 KB, and sixteen more boards, the Four Score, the Arkanoid controller, Game Genie cheats and custom palettes on the MiSTer core, and v3.3.0 "Plumbline" settled v3.2.0's leftovers and re-measured its claims: CHR-RAM writes through the bank registers on seven boards and mapper 71's documented decode (raising the epoch to 5), v3.1.x Bandai states loading again, a withdrawn v3.2.0 performance figure, IRQ trace goldens that gate, and two off-die MiSTer fixes, v3.4.0 "Waypoint" authenticated every native netplay datagram (protocol 9, protection against off-path forgery), bounded the rollback window and brought three and four players to the desktop, held RetroAchievements hardcore to RA's full block list, shipped the hosted lobby, TURN credentials and RA proxy as code (deployed in v3.4.1), halved the window thread's CPU, moved to egui 0.37, and, on the MiSTer core, made the off-die build the headline, added save states and rewind held to the oracle cycle for cycle with a layout fingerprint, slot-scheduled the SDRAM arbiter and added MMC2/MMC4, FME-7 with 5B audio, VRC2/VRC4 and the Zapper, the epoch staying 5, and v3.4.1 "Beacon" put the hosted lobby live with the browser and mobile builds pointing at it, held the TURN relay off after Cloudflare kept honouring expired and revoked credentials (the RA proxy deployed switched off until RetroAchievements answers the integration request), fixed the browser RetroAchievements packaging, made the MiSTer release assets version-named, and fixed the save engine's two cartridge-change defects and v3.4.0's two build findings, the epoch still 5; v3.4.2 "Countersign" made the RetroArch core load on Apple Silicon Macs again by no longer stripping the arm64 build after the linker signs it, changing nothing else; v3.5.0 "Chorus" made movies record every input the core takes (`.rnm` format 7: the Zapper and the other expansion devices, the microphone, Vs. coins, disk swaps and barcode scans; netplay protocol 9 unchanged), gave Lua a WebSocket client and real shared memory, added an MCP server over the headless core (`rustynes-mcp`), speedrun auto-timing with a memory-export interface and `rustynes dump-check`, brought the desktop A/V sync offset, Multi-Disk bundles, rebindable peripheral keys, browser drag-and-drop and DualSystem in the embed, switched the hosted TURN relay back on, and fixed the MMC5 scanline IRQ, which came a whole line early (epoch 6); on the MiSTer core it added the MMC5, the VRC6 and Namco 163 with their audio, the VRC7 (silent; its FM moves to v3.8.0) and the Bandai FCG boards, all off the die only under the new Lite tier, and the Famicom keyboard, P2 microphone and Power Pad; v3.5.1 "Reprise" made the MMC5's split-screen and extended-attribute CHR banks apply only while the PPU renders, in both cores, released a key held while it is rebound, refused devices and pipes as files to open, and closed the rest of the v3.5.0 review's residue; v3.6.0 "Octave" put the noise channel at its documented pitch in both cores (about an octave higher; epoch 8), made NSF files play again, ran the MiSTer core's PAL and Dendy consoles at full speed, and added a source-level homebrew debugger, audio stems, NSF ripping and libretro Core Options v2; v3.6.1 "Threshold" moved every dependency to its newest compatible release in one change, ended the MMC5's background-fetch window where rendering ends in both cores, took the MMC5 split's first two tiles of a frame from the right row (an oracle defect the MiSTer core's new stimulus found), bounded a TAStudio project by its decoded size, and, on the MiSTer core, tied save states to their region and gave the MMC5 PAL's and Dendy's pre-render line, raising the epoch to 9 (v3.6.0 movies and netplay peers refused) though nothing recorded moved; v3.6.2 "Latchkey" re-synced AccuracyCoin to upstream `66e87112` and passed all 147 of its scored tests, and hid *Rad Racer*'s stray right-side tiles with a switchable per-game correction that departs from hardware on purpose (ADR 0051; a first attempt that changed every game's attribute read rested on a wrong diagnosis and was withdrawn), raising the epoch to 10; and v3.7.0 "Spindle", the current release, brought the Famicom Disk System to the MiSTer core's off-die build, let spectators join a match from any point through the hosted relay, added opt-in desync forensics (netplay protocol 10, so v3.6.x peers are refused), recorded live PRG/CHR-ROM edits as BPS patches, and gave both mobile apps the desktop's equalizer, code database and correction switch, with box art, a widget and external display on iOS; nothing a frame, sample or bus cycle shows moved, so the epoch stays 10. AccuracyCoin held **141/141** through v2.6.16, read **143/144 (99.31%)** at v2.6.17, where the upstream re-sync grew the battery to 144 assigned tests and `Frozen OAM2 Increment` was the single named failure, and read **144/144 (100.00%)** from v2.6.18 — **a score v3.1.0 showed was overstated**: the old ROM's `Misaligned OAM behavior` fail path fell through to a pass, hiding a real failure in every one of those releases; on upstream `f5f41dc2` the core reads **146/146** with that failure fixed, and on upstream `66e87112` (v3.6.2) **147/147** — and the number was never always *by construction*: v2.3.4, v2.3.7, v2.3.9, the rung-3 releases v2.5.4-v2.5.6 and v2.6.17 change the core, so for those it is **verified** rather than inherited, and saying which is which is the point. **Full per-release detail is in `CHANGELOG.md` and `docs/STATUS.md` (the single source of truth)** — the entries below (v2.1.0 "Fathom" was the prior anchor here; v2.0.8 → v2.0.1) are the older historical trail, retained rather than duplicated. +- **Release line since v2.1.0:** the v2.1.x **"Fathom"** accuracy line (v2.1.0 → v2.1.10) → **v2.2.0 "Capstone"** (the milestone cut closing the "deepen the existing project" run) → **v2.2.1** (housekeeping) → **v2.2.2 "Conduit"** (build / distribution / CI-integrity) → **v2.2.3 "Datum"** (performance appraisal + the last two Holy Mapperel residuals closed) → **v2.2.4 "Cartridge"** (the libretro/RetroArch distribution cut) → **v2.2.5 "Colophon"** → **v2.2.6 "Almanac"** → **v2.2.7 "Timbre II"** → **v2.2.8 "Aperture II"** → **v2.2.9 "Studio II"** → **v2.3.0 "Datum II"** → **v2.3.1 "Plumb Line"** → **v2.3.2 "Lucid"** → **v2.3.3 "Cadence"** → **v2.3.4 "Ledger"** → **v2.3.5 "Manifest"** → **v2.3.6 "Sounding"** → **v2.3.7 "Overtone"** → **v2.3.8 "Parallax"** → **v2.3.9 "Crucible"** → the **v2.4.x "Fabric"** co-simulation line (**v2.4.1 "Fabric"** → **v2.4.2 "Cairn"** → **v2.4.3 "Touchstone"** → **v2.4.4 "Ignition"** → **v2.4.5 "Compass"** → **v2.4.6 "Abacus"** → **v2.4.7 "Keystone"** → **v2.4.8 "Palimpsest"** → **v2.4.9 "Plumbline II"** → **v2.5.0 "Rungwork"** → **v2.5.1 "Retrace"** → **v2.5.2 "Dormant"** → **v2.5.3 "Hysteresis"** → **v2.5.4 "Escapement"** → **v2.5.5 "Raster"** → **v2.5.6 "Vestige"** → **v2.5.7 "Collimation"** → **v2.5.8 "Blanking"** → **v2.5.9 "Overture"** → **v2.6.0 "Assay"** → **v2.6.1 "Interleave"** → **v2.6.2 "Witness"** → **v2.6.3 "Mainspring"** → **v2.6.4 "Rubric"** → **v2.6.5 "Muster"** → **v2.6.6 "Chassis"** → **v2.6.7 "Detent"** (the bitstream becomes a published, reproducible release artifact and a one-cycle disagreement is attributed rather than fitted away) → **v2.6.8 "Arrears"** (the gates the previous release fixed and never widened: four of six denied checkpoint streams had been passing unnoticed, three of them not run by the suite at all, and nestest widens 19x and gains the nine-field comparison that closes the gate's stated `nmi_line` blind spot) → **v2.6.9 "Abeyance"** (an exclusion hides improvement as well as regression -- both denied co-simulation streams close, and the larger one was a defect in the HARNESS rather than the console, carried for seven releases behind the phrase "by design") → **v2.6.10 "Inference"** (the cartridge meets the synthesiser, and simulation could not have asked the question -- rung 7's five boards had never been through Quartus, and `chr` written from two separate `always_ff` blocks could not infer as an M10K, so 128 KB stayed in flip-flops: 1,048,576 registers against roughly 166,000. The fix is behaviourally invisible -- 141 gates unchanged -- and the release carries the bitstream the previous one could not produce) → **v2.6.11 "Exposure"** (a picture is a gate the ladder did not have -- all 141 co-simulation gates green and two of six commercial games rendering wrong, because only THREE of those gates compare a framebuffer and all three ship CHR-ROM, so a CHR-RAM write taking the shared-pin composite address built for fetches was reached 9,600 times and compared never)) -> **v2.6.12 "Groundwork"** (the bitstream was an NROM-only console -- `emu.sv` left `cart_mapper`, `cart_prg_16k_banks` and `cart_chr_8k_banks` unconnected, so Quartus tied all three to GND and the fitted cartridge was mapper 0 with 8 KiB of PRG and 8 KiB of CHR against a declared 256 and 128; no gate could see it because `emu.sv` is not in the testbench file list, so all 142 gates exercised a correctly-configured cartridge, and Quartus said so three times in messages that cite an instance path rather than a file) -> **v2.6.13 "Slack"** (the cartridge outgrows the die -- an SDR SDRAM controller, a behavioural part model, a four-way arbiter and a console bridge written from the AS4C32M16SB-7 datasheet, and three consumers measured to three different budgets rather than the one figure the previous step assumed; the PPUDATA port leaves the shared bus through a handshake and that fix shipped a defect only a banked cartridge could see, the request carrying the raw PPU address where the mapper's translation was needed, so every banked-CHR board read bank zero; off the die the console passes 142 of 142 and it still ships on the die, because an off-die core cannot run without the add-on) -> **v2.6.14 "Docket"** (the submission checklist becomes auditable -- 30 boxes, 16 unticked and fourteen of those saying nothing about why, so an unticked box could not be told apart from work outstanding, work blocked elsewhere, and work already done and never ticked; the third case occurred five times. One box asked `docs/provenance.md` to state that no NES core was ever opened, which that document's own Do-not-self-certify section forbids, so it could only have been ticked by writing the sentence the provenance rules exist to prevent. Re-measuring the ticked half found two claims that had expired, the task board four delivered items never ticked and an SDRAM precondition the previous release did not follow, and its claim that MMC1 was unimplemented is retracted) → **v2.6.15 "Warrant"** (the claims the submission will make become checkable, and the instrument pays the oracle back — the `.rbf` name this core shipped would have distributed NOTHING, because `Distribution_MiSTer`'s builder skips any file whose stem does not end in `_` plus eight digits, so an accepted core would appear in the Cores table and ship nothing with no error anywhere; two of the four R1/R2 residuals ADR 0002 closed turn out never to have been IRQ-timing residuals, resting on an assertion blargg WITHDREW in the successor ROM; `sys/` verbatim, the `.qsf`'s single seed table and the bitstream name all become checks instead of claims; the nine rung-1 gates run in CI against a PINNED oracle commit, so the accuracy evidence stops being a document describing a check a reader cannot run; `cpu_interrupts_v2` lands on the DUT as the first INDEPENDENT interrupt oracle, five of five; and `T-ORACLE-001`'s opening claim is retracted — RustyNES does clock the MMC3 counter on the pre-render line, which `2-details` sub-test 8 has asserted all along) → **v2.6.16 "Interlock"** (the arbiter's numbers describe a stimulus, not the console: the gate's worst case issues a CHR and a PRG request on the same cycle and the running console never does — zero coincidences and a minimum separation of two over fifteen million SDRAM cycles — so both published figures are wrong about it in opposite directions, the CPU MEETING its deadline at 24 against 24 on all 240,303 requests where the gate said it missed by four, and the fetch reaching 23 against a derived 22 that a `CHR_LAT` sweep shows understates the real tolerance by at least nine cycles; the slot-scheduled arbiter this version was scoped around is therefore NOT built, and is still worth building because zero margin means one added cycle anywhere breaks the CPU) → **v2.6.17 "Terminus"** (a write lands where the cycle ENDS, and this core does not move to meet it. The AccuracyCoin and TriCNES oracles re-sync to upstream, and the battery grows 141 → 144 assigned tests across two new pages that RE-HOME eleven existing PPU tests, so a re-sync is not an append and a suite-keyed baseline has to be regenerated rather than extended. `OAM2Address` becomes a live counter through sprite fetch and the frozen fetch reads index 0 for every byte, closing two of the three new tests and carrying an approved SAVE-STATE EPOCH — `PPU_SNAPSHOT_VERSION` 8 → 9, so pre-v9 `.rns` states no longer load. The third names the dots its two `$2001` writes land on, which is how the core came to be measured TWO DOTS EARLY on both: a 6502 commits a write at phi2, the last of a CPU cycle's three PPU dots, and this core applies PPU register writes at M2-low, the first. The move was then MADE, measured against a first-difference control captured beforehand, and NOT ADOPTED — the write alone reads 141/144 and breaks the independent `ppu_vbl_nmi/10-even_odd_timing`, and the best combination found reads 142/144 against the 143/144 that ships, for a save-state epoch and six re-baselined goldens. `mask_for_skip_check` is PROVEN to be a compensation for the placement — under phi2 it needs one delay stage rather than two — and two of its three dependants are still un-re-derived, so adopting the mechanism now would replace a documented compensation with an undocumented one. `Misaligned OAM2 Address` was also found to be passing via TWO CANCELLING ERRORS, both since fixed independently. Ships one core fix nothing in the corpus could see — the misaligned-OAM `+4 & $FC` realignment, reached 114 times per battery run out of 56,953,944 out-of-range branches and pinned by a targeted test because no ROM's verdict moves — plus `terminus_control.rs` as a standing first-difference gate. The follow-up version the write-placement work had been scoped into is FOLDED here: that split existed because Terminus was to be a scheduler change with its own ADR and a full re-baseline, and the refutation means it is not — so v2.6.17 carries both). v2.6.18 "Errata" closes the last AccuracyCoin entry on top of it, and v2.6.19 "Accession" carried both into the FPGA core, v2.6.20 "Telltale" made the OAM2 counter observable, v2.6.21 "Steward" gave the core battery saves and gated CHR writes during rendering, v2.6.22 "Rigging" built the instruments a board would need before the board existed, v2.6.23 "Pulse" closed the CHR-during-rendering divergence by making the `$2007` access pulse the rendering pipeline's load instead of computing its own, and v2.7.0 "Palisade", the first of the ADR 0041 audit line, made a corrupt save state fail at restore rather than one tick later, stopped pulse 1 muting on the `$4001 = $08` sweep idiom, and gave the save-state fuzz target the reach to find five defects the audit had not, v2.7.1 "Keepsake" stopped six cartridge boards writing an empty battery save and moved every user file the frontend writes onto the atomic writer, v2.7.2 "Bankroll" gave MMC1, MMC5 and Namco 163 the banks their boards have and made `$6000-$7FFF` read open bus on the 205 board variants with nothing there, v2.7.3 "Hearth" made the desktop keep battery saves, closed three ways around the Lua sandbox, gated script HTTP destinations, and brought audio back after a device change, v2.7.4 "Pocket" kept the Android and iOS apps alive through an internal error, gave both battery saves, paused them and released audio when they leave the screen, and made their saves atomic, v2.7.5 "Tally" closed the core audit's twelve performance proposals (eleven by measurement, one adopted: the audio buffer keeps its capacity), deprecated 18 dead bus methods and `ApuBus`, and closed the core and frontend ledgers, v2.7.6 "Recount" measured alone the six deletions v2.7.5 had bounded only together (five zero; the sixth, never reached by the benchmarks before, bounds at 0.2%), turned three redundant fast-path stores into an assertion, and shipped the contributed libretro buildbot fixes and targets, v2.8.0 "Bulkhead" opened the v2.8.x libretro + RTL audit line: the libretro core unwinds and contains a panic at its own boundary, keeps save states the right size with a Zapper, withdraws its memory maps on unload, loads through the standard `retro_game_info` via a vendored binding, and the save state carries the internal data bus, v2.8.1 "Gasket" closed the libretro audit: Four Score, four described ports (the list now NULL-terminated, where RetroArch had read past it), the Zapper unplugged, unclipped expansion audio, UNIF, and a Makefile that honours its callers, v2.8.2 "Solder" corrected the MiSTer core's on-die RTL against the oracle and the wiki (MMC3 acknowledge, SNROM PRG-RAM, the triangle and noise reload drop, the `$2002` latch) and found the audit's MMC1 finding inverted: the emulator was the one ignoring a reset, and v2.8.3 "Rivet" released every reset on the clock that uses it, cut the CPU by about 4% with two exact rewrites the fit report confirmed, and made the ladder run from a fresh checkout (164 of its 165 gates, a claim v2.8.4 found overstated), and v2.8.4 "Tether" closed the v2.8.x line: it found every off-die read would have been sampled a clock late on hardware (the SDRAM model and controller shared the error, and only the new SDRAM timing constraints could see it) and fixed both, pinned both builds at fitter seed 5 after a sweep of each, and made the ladder run all 165 gates from a clean checkout, and v2.9.0 "Survey" opened the v2.9.x line by re-running all four audits (139 rows re-verified, none regressed, 39 new findings fixed or dispositioned), including a Power Cycle that erased the battery save and an off-die MiSTer build that hung under `bootcore=`, v2.9.1 "Hone" found that the A/B tool had been timing the old code on both sides and re-measured what it had rejected, made a Vs. cabinet save-state about 9x faster, moved the off-die build's CHR into its own SDRAM bank, and pinned both builds at fitter seed 2 with two byte-identical clean compiles each, v2.9.2 "Candidate" triaged a fifth, 32-finding audit of both repositories (16 fixed, each finding with its evidence in its ledger), made save states keep the cartridge RAM of twelve board families that dropped it, fixed the MiSTer CPU losing an NMI raised inside a DMA, and cut the release-candidate bitstream pair for the SuperStation One session, v2.9.3 "Handset" moved every dependency to its newest release, answered all 244 review threads left open on PRs #7-#97 and fixed the ten findings that still held (mapper 28 rebuilt, a header editor that writes only what you change), and prepared the mobile device run, which the maintainer then moved after v3.0.0 with the board session, v2.9.4 "Plumb" recorded v3.0.0 as the API major with a release-candidate core (ADR 0043), made CI run the feature-gated tests, fuzz targets and a coverage floor it had only linted or never had, and corrected the records against the code, v2.9.5 "Caliper" gave every open accuracy item an outcome: blargg's `apu_test` frame-counter coincidence, the composite 2C02's odd-frame scanline-0 sprite pixel, OAM DMA filling the PPU I/O latch and KS7032's `$6000` window fixed red first, 49 unreferenced test ROMs gated, the MMC3 M2-edge filter lever tried and refuted, and a save-state epoch (`PPU_SNAPSHOT_VERSION` 11), v2.9.6 "Roster" added seventeen mapper families from their NESdev pages (174 → 191), promoted GTROM to Curated with a modelled SST39SF040 whose saves persist, corrected mapper 4's NES 2.0 submappers (MMC6, NEC, MC-ACC, T9552), and re-baselined the local commercial suites, which had drifted unread since about v2.0.0, v2.9.7 "Tandem" brought the desktop's features to the web and phones (battery saves in the browser, Vs. DualSystem on web and mobile, FDS and NSF on mobile), made the release binaries the full native build, and fixed a PPU A12 defect real games exposed: the PPU reported one pulse per scanline where the console makes eight, so Acclaim's MC-ACC, the J.Y. ASIC and mapper 91 had counted eight times slow, v2.9.8 "Vanguard" carried v3.0.0's planned breaking changes ahead of it (a save identity that ignores the header, older save states and movies refused, movies and netplay that record the machine, the ADR 0042 API removals), booted every one of 748 staged dumps and fixed the defects that turned up, and made the game database's corrections reach every platform, v2.9.9 "Ballast", the release candidate for v3.0.0, re-ran all four audits and fixed what they found, raised the MMC3 IRQ by the NESdev rule (T-ORACLE-001) and gave the MMC5 the chip's CHR set selection (which fixed *Uchuu Keibitai SDF*), made audio exact across a save state, moved the MiSTer core's oracle pin onto it with the APU and PPU parity that opened, and cut the release-candidate bitstream pair at seed 6 (a seed-8 pair was withdrawn when the RTL changed after it), v3.0.0 "Cornerstone", the API major, gathered every break since v2.x in one place, made movies and netplay carry a core timing epoch so a version that emulates differently is refused with a reason (ADR 0045), took the last struct-extensibility breaks, closed blargg's `4-scanline_timing` in the emulator and the MiSTer core (T-MMC3-BG-A12), and shipped that core as a release candidate, not hardware-verified, and v3.0.1 "Mortar" unbanked *Famicom Yarou Vol.1*'s CHR-RAM (raising the emulation epoch to 2), reached the MiSTer core's odd-frame A12 exception with a new test ROM that found a one-cycle defect, moved the toolchain and the libretro buildbot to Rust 1.99, answered every bot review left since PR #1, recorded the shared Bisqwit NTSC pass as derived and moved the TriCNES source out of the repository, and wrote the plan to v4.0.0 (`to-dos/plans/v3.1-to-v4.0-line-plan.md`), and v3.1.0 "Bellwether" re-synced AccuracyCoin to upstream `f5f41dc2` and fixed the two defects it found (raising the epoch to 3), made the CPU overclock and the sprite-limit option work and travel with movies and netplay, corrected PAL emphasis and the alternate MMC3, gave the Vs. cabinet rewind and run-ahead, and matched the MiSTer core to all of it, including a `$2006` timing rule it had never been tested against, and v3.2.0 "Confluence" brought every v3.2.0 branch in both repositories into one release: 17 mapper families (191 to 208, with the Bandai Datach), the VRC4 IRQ mode read the right way round and the VRC2 and *Fire Hawk* mirroring fixes (raising the epoch to 4), an AI remediation branch audited change by change before anything was kept, netplay protocol 8, libretro states of about 16 KB, and sixteen more boards, the Four Score, the Arkanoid controller, Game Genie cheats and custom palettes on the MiSTer core, and v3.3.0 "Plumbline" settled v3.2.0's leftovers and re-measured its claims: CHR-RAM writes through the bank registers on seven boards and mapper 71's documented decode (raising the epoch to 5), v3.1.x Bandai states loading again, a withdrawn v3.2.0 performance figure, IRQ trace goldens that gate, and two off-die MiSTer fixes, v3.4.0 "Waypoint" authenticated every native netplay datagram (protocol 9, protection against off-path forgery), bounded the rollback window and brought three and four players to the desktop, held RetroAchievements hardcore to RA's full block list, shipped the hosted lobby, TURN credentials and RA proxy as code (deployed in v3.4.1), halved the window thread's CPU, moved to egui 0.37, and, on the MiSTer core, made the off-die build the headline, added save states and rewind held to the oracle cycle for cycle with a layout fingerprint, slot-scheduled the SDRAM arbiter and added MMC2/MMC4, FME-7 with 5B audio, VRC2/VRC4 and the Zapper, the epoch staying 5, and v3.4.1 "Beacon" put the hosted lobby live with the browser and mobile builds pointing at it, held the TURN relay off after Cloudflare kept honouring expired and revoked credentials (the RA proxy deployed switched off until RetroAchievements answers the integration request), fixed the browser RetroAchievements packaging, made the MiSTer release assets version-named, and fixed the save engine's two cartridge-change defects and v3.4.0's two build findings, the epoch still 5; v3.4.2 "Countersign" made the RetroArch core load on Apple Silicon Macs again by no longer stripping the arm64 build after the linker signs it, changing nothing else; v3.5.0 "Chorus" made movies record every input the core takes (`.rnm` format 7: the Zapper and the other expansion devices, the microphone, Vs. coins, disk swaps and barcode scans; netplay protocol 9 unchanged), gave Lua a WebSocket client and real shared memory, added an MCP server over the headless core (`rustynes-mcp`), speedrun auto-timing with a memory-export interface and `rustynes dump-check`, brought the desktop A/V sync offset, Multi-Disk bundles, rebindable peripheral keys, browser drag-and-drop and DualSystem in the embed, switched the hosted TURN relay back on, and fixed the MMC5 scanline IRQ, which came a whole line early (epoch 6); on the MiSTer core it added the MMC5, the VRC6 and Namco 163 with their audio, the VRC7 (silent; its FM moves to v3.8.0) and the Bandai FCG boards, all off the die only under the new Lite tier, and the Famicom keyboard, P2 microphone and Power Pad; v3.5.1 "Reprise" made the MMC5's split-screen and extended-attribute CHR banks apply only while the PPU renders, in both cores, released a key held while it is rebound, refused devices and pipes as files to open, and closed the rest of the v3.5.0 review's residue; v3.6.0 "Octave" put the noise channel at its documented pitch in both cores (about an octave higher; epoch 8), made NSF files play again, ran the MiSTer core's PAL and Dendy consoles at full speed, and added a source-level homebrew debugger, audio stems, NSF ripping and libretro Core Options v2; v3.6.1 "Threshold" moved every dependency to its newest compatible release in one change, ended the MMC5's background-fetch window where rendering ends in both cores, took the MMC5 split's first two tiles of a frame from the right row (an oracle defect the MiSTer core's new stimulus found), bounded a TAStudio project by its decoded size, and, on the MiSTer core, tied save states to their region and gave the MMC5 PAL's and Dendy's pre-render line, raising the epoch to 9 (v3.6.0 movies and netplay peers refused) though nothing recorded moved; v3.6.2 "Latchkey" re-synced AccuracyCoin to upstream `66e87112` and passed all 147 of its scored tests, and hid *Rad Racer*'s stray right-side tiles with a switchable per-game correction that departs from hardware on purpose (ADR 0051; a first attempt that changed every game's attribute read rested on a wrong diagnosis and was withdrawn), raising the epoch to 10; v3.7.0 "Spindle" brought the Famicom Disk System to the MiSTer core's off-die build, let spectators join a match from any point through the hosted relay, added opt-in desync forensics (netplay protocol 10, so v3.6.x peers are refused), recorded live PRG/CHR-ROM edits as BPS patches, and gave both mobile apps the desktop's equalizer, code database and correction switch, with box art, a widget and external display on iOS; nothing a frame, sample or bus cycle shows moved, so the epoch stays 10; and v3.7.1 "Imprint", the current release, labelled every file with its copyright holder and licence (REUSE 3.3), stopped calling the test ROMs whose authors stated no licence public domain, shipped the licence notices in the Android and iOS apps and on the web site, fixed the MiSTer core's FDS drive and battery saves, and gave each hosted match its own spectator id; in the emulator again nothing a frame, sample or bus cycle shows moved, so the epoch stays 10, while the MiSTer core's FDS drive does change on purpose (the head stops at a side's end, `$4030.D6`), refusing v3.7.0's off-die save states. AccuracyCoin held **141/141** through v2.6.16, read **143/144 (99.31%)** at v2.6.17, where the upstream re-sync grew the battery to 144 assigned tests and `Frozen OAM2 Increment` was the single named failure, and read **144/144 (100.00%)** from v2.6.18 — **a score v3.1.0 showed was overstated**: the old ROM's `Misaligned OAM behavior` fail path fell through to a pass, hiding a real failure in every one of those releases; on upstream `f5f41dc2` the core reads **146/146** with that failure fixed, and on upstream `66e87112` (v3.6.2) **147/147** — and the number was never always *by construction*: v2.3.4, v2.3.7, v2.3.9, the rung-3 releases v2.5.4-v2.5.6 and v2.6.17 change the core, so for those it is **verified** rather than inherited, and saying which is which is the point. **Full per-release detail is in `CHANGELOG.md` and `docs/STATUS.md` (the single source of truth)** — the entries below (v2.1.0 "Fathom" was the prior anchor here; v2.0.8 → v2.0.1) are the older historical trail, retained rather than duplicated. - **Historical detail — v2.0.8 "Harbor"** (2026-07-09) (the preceding release is v2.9.9 "Ballast"; see the release line above) — the eighth release of the **v2.0.x mobile-finalization train** and the **iOS release candidate** ("Harborlight"), the final release of the iOS finalization window (**v2.0.5 → v2.0.8**). A **host / iOS-only** cut: the cycle-accurate core is **unchanged and byte-identical to v2.0.7** (AccuracyCoin still **141/141, 100.00%**; nestest 0-diff; `#![no_std]` chip stack untouched). It stages the App Store scaffolding for v2.1.0: version-controlled **App Store Connect listing metadata** (`fastlane/metadata/ios/{en-US,es-ES}/`, mirroring the Android tree, files-only), a **dormant App Store `release` lane** in `fastlane/Fastfile` that stages the build + listing but **does not submit** (`submit_for_review: false`) and is **not** CI-wired (the interim channel stays **TestFlight**), and an **App-Review §4.7 self-audit** (no bundled/downloadable ROMs, ownership notice, searchable library, 4+ rating) in `docs/ios-v2.0.8-readiness.md`. Version bump (workspace `2.0.7 → 2.0.8`; iOS `MARKETING_VERSION → 2.0.8`). **No store submission** (that is v2.1.0); screenshots, real signing, the listing upload, and the App-Review submission are the **maintainer / v2.0.9 / v2.1.0** closeout. See `docs/STATUS.md` (single source of truth) + `CHANGELOG.md` `[2.0.8]` + `docs/ios-v2.0.8-readiness.md` + `to-dos/plans/v2.0.5-v2.0.8-ios-finalization-plan.md`. - **Earlier in the train:** **RustyNES v2.0.7 "Harbor"** (2026-07-09) — the seventh release of the **v2.0.x mobile-finalization train** and the **third iOS finalization release** ("Trim"), continuing the iOS window (**v2.0.5 → v2.0.8**). A **host / iOS-only** cut: the cycle-accurate core is **unchanged and byte-identical to v2.0.6** (AccuracyCoin still **141/141, 100.00%**; nestest 0-diff; `#![no_std]` chip stack untouched). It wires the **App Store submission floor** (Apple mandates the **iOS 26 SDK / Xcode 26** for every App Store Connect upload from **2026-04-28**, so the tag-gated iOS CI now selects the newest Xcode 26.x on the runner — a build-SDK pin, non-breaking fallback on older images), **reconciles the deployment target `iOS 15.0 → 17.0`** to match the code's real API floor (`NavigationStack` iOS 16 + `.topBarTrailing` iOS 17, unguarded at 12+ sites — the prior 15.0 was never buildable), and **re-audits `PrivacyInfo.xcprivacy`** against the v2.0.6 crash reporter (no new data type / required-reason API — local-only, backup-excluded, off by default). Version bump (workspace `2.0.6 → 2.0.7`; iOS `MARKETING_VERSION → 2.0.7`). **TestFlight-only** (App Store + AltStore PAL deferred to v2.1.0); on-device profiling + the Xcode-26 archive are a **maintainer / v2.0.9** step. See `docs/STATUS.md` (single source of truth) + `CHANGELOG.md` `[2.0.7]` + `docs/ios-v2.0.7-readiness.md` + `to-dos/plans/v2.0.5-v2.0.8-ios-finalization-plan.md`. - **Earlier in the train:** **RustyNES v2.0.6 "Harbor"** (2026-07-09) — the sixth release of the **v2.0.x mobile-finalization train** and the **second iOS finalization release** ("Parity"), continuing the iOS window (**v2.0.5 → v2.0.8**). A **host / iOS-only** cut: the cycle-accurate core is **unchanged and byte-identical to v2.0.5** (AccuracyCoin still **141/141, 100.00%**; nestest 0-diff; `#![no_std]` chip stack untouched), so no accuracy / save-state / determinism number moves. It adds a **new opt-in, privacy-first crash-reporting surface** (off by default — the iOS analogue of the Android v1.8.8 `CrashReporter`, closing the v1.9.9 iOS-applicable deferral): **Settings → Diagnostics** installs an uncaught-`NSException` handler that writes **local** crash logs the user can view + copy in-app — **nothing is uploaded**, so the "Data Not Collected" privacy label is unchanged (EN + ES); the handler re-checks the live opt-in at crash time so opting out stops new logs immediately. It also records the **feature-parity re-verification** of the v1.9.x host features (Game Center, CloudKit save sync, MFi controllers, capture / PiP, accessibility) against the unchanged v2.0.0 bridge surface. Version bump (workspace `2.0.5 → 2.0.6`; iOS `MARKETING_VERSION → 2.0.6`). **TestFlight-only** (App Store + AltStore PAL deferred to v2.1.0); on-device crash-capture verification is a **maintainer / v2.0.9** step. See `docs/STATUS.md` (single source of truth) + `CHANGELOG.md` `[2.0.6]` + `docs/ios-v2.0.6-readiness.md` + `to-dos/plans/v2.0.5-v2.0.8-ios-finalization-plan.md`. @@ -1506,17 +1506,21 @@ re-minted: `T-PS-dual-runahead` (ADR 0032; **DONE v3.1.0**), `T-MISTER-SAVESTATE | `T-DEBUGGER-MMC5-SPLIT-PEEK` | The debugger's nametable view during an MMC5 vertical split shows the byte `ppu_peek` returns, which follows the per-tile CHR latches mid-line; the #630 reply promised this ticket and it was never filed | closed-PR review sweep (#654, 2026-11-12) | v3.8.0 | | `T-DAP-REVIEW-631` | Nine #631 findings left open: the S-register wrap in `nsf_rip` and the debugger, `nsf_rip`'s call-chain ids, GDB `vCont`, GDB SIGINT with `swbreak`, Android audio focus, two iOS `DurableWrite` items, the stems error paths, and the dap-fixture churn (each listed in the #631 sweep comment) | closed-PR review sweep (#654, 2026-11-12) | v3.8.0 | | `T-MISTER-CLOSED-PR-SWEEP` | The sibling findings the sweep recorded on MiSTer #64-#73 (each PR's sweep comment lists them with locations on `a18f191`): among them `want_cap` held on a collision (`emu.sv`), FME-7 WRAM without a battery bit, mapper 21 submapper 0 ignoring VRC4's W bit, `key_alt` stuck across the OSD, `pll_region` S_DONE_WR's guard, six F3b module gates absent from hosted CI, and `ss_mutations.json` R1 no longer applying | closed-PR review sweep (#654, 2026-11-12) | after the MiSTer v3.7.0 release | -| `T-MISTER-FDS-SIDE-BOUND` | The MiSTer FDS drive wrote past a side's end: through the next side's bytes in SDRAM, then wrapped at 65,536 onto the side's own start; the OSD could select a side the image lacks; a headered download of under one side was accepted. Known issue in the v3.7.0 bitstreams. **FIXED on sibling `feat/v3.7.1-fds-fixes` `0db3130`** (the documented end-of-head: ready drops and the head re-seeks; a missing side is no disk; under 65,500 bytes refused), `emu-hps-gate` fds claims 12-14, each red first | Antigravity on sibling #74 (2026-11-12) | v3.7.1 | +| `T-MISTER-FDS-SIDE-BOUND` | The MiSTer FDS drive wrote past a side's end: through the next side's bytes in SDRAM, then wrapped at 65,536 onto the side's own start; the OSD could select a side the image lacks; a headered download of under one side was accepted. Known issue in the v3.7.0 bitstreams. **FIXED on sibling `feat/v3.7.1-fds-fixes` `0db3130`** (the documented end-of-head: ready drops and the head re-seeks; a missing side is no disk; under 65,500 bytes refused), `emu-hps-gate` fds claims 12-14, each red first. **Corrected 2026-11-14 (`1dca747`):** the re-seek with the motor held matched neither the pages nor the oracle; the drive now stops at the side's end, `$4030.D6` (end of head) rises, and nothing more is stored until a motor restart (maintainer's choice, "bound fix + D6"; probes `fdsprobe551`/`fdsprobe552`, claim 18). The off-die save-state fingerprint moves D4E792FE -> 6C9E7051, so v3.7.0 off-die states are refused | Antigravity on sibling #74 (2026-11-12) | v3.7.1 | | `T-MISTER-FDS-DIRTY-RESET` | The FDS disk's dirty flag cleared on the console reset, so a disk write followed by a reset before the OSD opened was never saved. Known issue in the v3.7.0 bitstreams. **FIXED on sibling `feat/v3.7.1-fds-fixes` `2df4f50`** (`fds_save` keeps its own sticky copy in the system's reset), `emu-hps-gate` fds claim 11, red first. `save_ctl`'s `bram_dirty` shared the reset, so a cartridge's battery save was lost the same way in every MiSTer release: **FIXED** on the same branch (`039c7a6`) with the same sticky copy (the `blargg` scenario now holds the console in reset across the OSD open; red on the old RTL) | Antigravity on sibling #74 (2026-11-12) | v3.7.1 | | `T-MISTER-FDS-SAVE-ABORT` | `mounted_ok` outlived a cartridge change, so an FDS loaded later with no mount of its own could be saved into the previous image's vdisk: **FIXED** (`2df4f50`, claim 9 reworked, red first; safe because every load through the `FS3` entry remounts, `user_io.cpp`; MGL and boot autoload not verified). FDS RAM writes also wrote `cart.sv`'s PRG-RAM and set `bram_dirty`: **FIXED** (`ram_writable` gated by `!is_fds`; the first check was blind, a $6000 write added to `fdshpsread` made it see the defect). The BIOS-download hang is **REFUTED**: `host_req` is held as a level and the reset clears the port's `h_done`, so the request is served again (claim 10, landing the download with a request out, passes on the unchanged RTL; its `h_done` mutant fails it); withdrawn from both v3.7.0 release bodies and the sibling README on 2026-11-12 | Antigravity on sibling #74 (2026-11-12) | v3.7.1 | | `T-MISTER-FDS-DRIVE-EDGES` | Drive edge cases Antigravity raised on sibling #74 (2026-11-12). **FIXED on sibling `feat/v3.7.1-fds-fixes` `347c8c3`**, each settled by a run: a write continued from a read paused inside a block dropped 8 of its 19 bytes (now ends at `$4025.4`; claim 15); a program holding the drive enabled with the motor stopped hung a `.sav` load and a write-back (the host port is free while the motor is stopped, which stores nothing; claim 16); the write clock ran through a restart's re-seek at a stale offset (it waits for ready; a restart with the head at the start is ready at once; bus stems `fdsprobe528`/`fdsprobe527`, the oracle's behaviour on points the pages leave open, maintainer's choice 2026-11-13). `crc_err` is unreachable with `.fds` images; the eject counter was not needed. The "gate gap" here said `fdsedge550` compared only /IRQ rises; it is bus-gated, and its program reads block 3 back for only 16 bytes (corrected 2026-11-12) | Antigravity on sibling #74 (2026-11-12) | v3.7.1 | +| `T-MISTER-FDS-RAW-STREAM` | The oracle's FDS side is a raw stream built from the image's blocks at load (block, CRC, 100-byte gap), ending about 100 transfers (read) / about 200 (write, uncharacterised) after the ORIGINAL last block; the `.fds` zero fill is not part of it. The MiSTer core keeps its 65,500-byte side (ledger 3.138, maintainer 2026-11-14). Model it, or settle it on hardware (`T-FDS-WIKI-DIVERGENCE`). Evidence: `salvaged/evidence/v3.7.1-fds-side-end/` | measured 2026-11-14 (sibling #77) | v3.8.0 | +| `T-MISTER-SAVE-XFER-ACROSS-LOAD` | `save_ctl.sv` lets a battery write-back (`S_SAVE`) or load (`S_LOAD`) already under way run across a cartridge download (`abort`) and the next mount (`mount_now`). `fds_save.sv` stops one instead. If `Main_MiSTer` mounts the new cartridge's `.sav` on vdisk 0 before serving the rest of a pending write, the old game's remaining blocks land in the NEW game's file. A load in flight can also write the old file into the new cartridge's running PRG-RAM, and a switch to an FDS image cuts `save_ctl` off the vdisk mux for its 2^24-clock watchdog (`save_busy` holds save states and rewind for about 0.8 s). The window is the few milliseconds a write-back takes after the OSD opens. Every core-side remedy loses data in some case: abandoning a transfer leaves the old file half-written, and holding the download with `ioctl_wait` deadlocks unless the framework serves SD while it waits. Settle the framework's ordering on hardware, then choose. Found by Antigravity on sibling PR #77 (third round, on 15df0d0); not reproduced. The same round's three narrow suggestions ride with this ticket: guard `fds.sv`'s read-to-write handoff on `!sk`, so a read not yet started is not treated as mid-block; clear `spun` and `eoh` when the disk is ejected; and match `check_golden_provenance.py`'s `mkfds` fallback by stem before `bios_sha256`. **Added 2026-11-15** (Antigravity's fifth round on sibling PR #77, on `22747c0`; maintainer: ticket, merge #77), verified at the code where stated: (a) `fds.sv`: a write that reaches the side's end sets `eoh` but leaves `ph` in `P_DATA` (or the phase it was in), so a switch to READ without a motor restart takes `ph_rd = P_DATA` and `rd_byte = disk_q` at `side_base + 65500`, the next side's first byte, instead of `$00` (verified; the review's fix: `ph <= P_TRAIL` wherever a write sets `eoh`); (b) `save_ctl.sv`: `starting` and `S_IDLE` do not wait on `mount_now`, unlike `fds_save`'s `go`, so an OSD save requested on the very clock a mount with a file arrives starts `S_SAVE` and writes the old RAM into the newly mounted file before the load (verified); (c) `fds_save.sv`: a save start clears `dirty` and `disk_dirty`, and a size-0 mount (`!load_ok`) that abandons `S_SFILL`/`S_STX` leaves both clear with the modified disk still in SDRAM, so the unsaved writes are never saved (from the review; not traced). Gate for each: an `emu-hps-gate` or `save_ctl` claim that fails first, a mutant, both ladders | ticketed 2026-11-14 (maintainer: ticket, do not change in v3.7.1) | v3.7.2 | +| `T-MISTER-SYS-RESYNC` | Re-vendor the sibling's `sys/` (the MiSTer framework, MiSTer-devel/Template_MiSTer) from the pin `3ea1134` to upstream. Upstream is 5 commits ahead (9c8eadb framebuffer parameters in `emu_ports.vh`, afd7808 analog audio pins from registers, 5dda373 `yc_out` registers the sine values rather than their indexes, 76dd8f5 per-player force-feedback request in `hps_io`, e901a9f analog RT/LT input), touching 6 files (`emu_ports.vh`, `hps_io.sv`, `mcp23009.sv`, `sys_analog.tcl`, `sys_top.v`, `yc_out.sv`); none changes a licence line (checked for the REUSE work, sibling #79). `emu_ports.vh` is the `emu` module's port list, so the sync can change the core's interface, and `sys_top.v` changes every bitstream. Gate: `tb/sys_manifest.sha256` and `docs/sys-vendoring.md` updated to the new pin; `REUSE.toml`'s per-file `sys/` labels re-read against the new headers; Verilator lint and pin-check, `emu-hps-gate` and both ladders as before; a seed sweep with both builds closing timing. The YC-output and analog-audio fixes can only be confirmed on hardware (D29), and are recorded so. **Decided 2026-11-15 (maintainer: re-vendor if it does not break anything; scheduled after v3.7.1 ships, on its own branch, because the builds close timing at few seeds and a framework change can move that)** | sibling #79 review | v3.7.2 | +| `T-REUSE-FOLLOWUPS` | The non-blocking suggestions from the last review rounds of the licensing PRs, left for a small follow-up so they did not start another round (oracle #664, #665; maintainer rule: merge on green). (1) `provenance_record_audit.rs`: the effective annotation of a `// Provenance:` file must also list a `DoubleGate` holder, or an `aggregate` entry naming only the upstream holder silently drops the project's copyright (the `.rs` files carry no in-file copyright line). (2) `ci.yml` `ci-success`: check `needs.reuse.result == 'success'` explicitly, like `changes`. (3) Decide one convention for derived files' licence expressions: `palette_gen.rs` is `GPL-3.0-or-later AND ISC` while the MIT- and LGPL-derived files record their upstream licence only in `SPDX-FileComment`; either add `AND MIT` / `AND LGPL-2.1-or-later` to those or state why ISC is different. (4) `scripts/agy-review-selftest.sh` (oracle, sibling and the reviewer template): also assert `AGY_LOCK_WAIT` is at least one review's worst-case hold (retries x per-attempt cap + the pauses), not only that the sum fits `timeout-minutes`. (5) `AGY-REVIEWER.md` / the template README: say that 1860 s is sized for one review ahead in the queue, not two | #664 / #665 final review rounds | v3.7.2 | | `T-FDS-WIKI-DIVERGENCE` | The MiSTer FDS work (Phase F4b, sibling `cef0080`) compared the oracle's FDS outputs with the NESdev pages and found ten places where they differ. They are listed in the sibling's `docs/oracle-vs-documentation.md` ledger 3.137: `$4020-$402F` / `$4034-$403F` read `$00`, not open bus; `$4030.D3` always 0, not the `$4025.D3` arrangement; a block's CRC returns the bytes written to `$4024`, not the CRC register; the disk IRQ in write mode is unprobed; gain changes take effect at once, not only at wave position 0; master volumes 2/3, 2/4 and 2/5 are rounded; `$4087.6` force carry does not step every clock; the `$4089.7` hold stops the wave; `$4023.1` is ignored; wave-RAM reads return bits 7-6 = 00, not 01. The MiSTer core follows the pages, and the gating stimuli avoid every row, so neither core is checked there. Check each row against a public FDS test ROM or published hardware evidence before changing anything. Then fix the confirmed rows in one change with one `EMULATION_EPOCH` rise, and re-export the MiSTer FDS goldens. `fds.rs` is Provenance-headered, so each fix is written from the page, never by rewording the derived region. Gate: per row, a red test from the evidence, then green; unconfirmed rows recorded with the reason. **Decided 2026-11-08 (maintainer): a ticket for v3.8.0; v3.7.0 ships as built and names the divergence in its notes** **Two more rows, 2026-11-12** (sibling `b4eda18`, recorded in `3aef852`): the v3.7.0 review measured, by black-box bus trace against the pinned oracle `9c62143c`, two places the NESdev pages do not address. (11) A read resumed just before a run of `$00` bytes: the oracle passes over them, the MiSTer core delivers them. (12) A block overwritten from inside, then read back past its old length: the oracle returns the bytes as written with no CRC, the MiSTer core synthesises a CRC at the length the header gives. The maintainer chose option A (keep the MiSTer core's behaviour, record both, build neither); ledger 3.137 lists options A-D, what building each would take, and the trigger to reopen (a game or disk tool that reaches either case, or hardware evidence). Rows 11 and 12 belong to this ticket, but are not fixed by it unless that trigger fires | v3.7.0 MiSTer FDS (ledger 3.137) | v3.8.0 | -| `T-TEST-COVERAGE-PARALLEL` | `external_coverage_boot_smoke` (`crates/rustynes-test-harness/tests/external_coverage.rs`) is one `#[test]` that boots every staged commercial ROM in a serial loop, so it runs on one core: 6,493 s (about 108 minutes) of the v3.7.0 full release suite, while cargo runs test binaries one at a time and the other cores sit idle. Each boot builds its own `Nes`, and determinism holds per ROM, so the boots can run in parallel without changing a result: split the list across `std::thread::scope` workers (no new dependency), keep the per-ROM `catch_unwind`, and sort the combined failure list so the report stays deterministic. Snapshot names are already explicit, so they do not depend on the thread. Gate: on the full local corpus, the parallel sweep reports exactly the serial sweep's per-ROM results (the same snapshots, the same failure list, including a planted failure), and its wall time is measured and recorded. **Decided 2026-11-11 (maintainer): post-release, not in the v3.7.0 release PR** (changing a gate mid-release would mean re-running the suite to prove it). **CODE LANDED, MEASUREMENT PENDING** (maintainer 2026-11-11: write the code now, measure later): `parallel_map_ordered` + `RUSTYNES_COVERAGE_JOBS`, its ordering test mutation-checked; a smoke run on the 7 mapper-007 ROMs gave the same outcome and SKIP lines serially (53.2 s) and on 4 workers (17.0 s, on a loaded machine, so not a measurement). Still to do on a quiet host: the full-corpus serial-vs-parallel equality run with a planted failure, and the recorded wall times. **Slotted 2026-11-12:** v3.7.1 if the maintainer cuts it (`plans/v3.7.1-plan.md`), else v3.8.0 | v3.7.0 full-suite run | v3.7.1 (proposed), else v3.8.0 | -| `T-MISTER-LADDER-PARALLEL` | The sibling's co-simulation ladder (`tb/regress.sh`, 2,621 lines) runs every stimulus in series, each one a single-threaded Verilator model, so a ladder uses about one core of twenty: the v3.7.0 off-die ladder was about 40% through after five hours. The models build in parallel (`-j 0`); only the runs are serial. First, time every stimulus and record the table. Then run independent stimuli from a job pool (`wait -n` or `xargs -P`), longest first, after every model is built; give each stimulus its own scratch and output paths; print each stimulus's output in registry order, so the PASS / FAIL / XFAIL tally and the log read exactly as before; and refuse to run beside a mutation harness, which rewrites the RTL. Also measure, and adopt only on evidence: `-O3 -march=native`, clang, PGO of the Verilated C++ (now `-O2`), and Verilator `--threads` (likely a loss on a design this small). Do not change `--x-initial`, which alters what an uninitialised register holds. `OBJCACHE=ccache` speeds rebuilds only. Gate: on both builds the parallel ladder gives the serial ladder's verdict for every stimulus, a planted FAIL included, and the wall times are recorded; the sibling's CI ladder adopts the pool too. **Decided 2026-11-11 (maintainer): post-release, not inside v3.7.0's ladder runs**. **CODE LANDED, MEASUREMENT PENDING** (maintainer 2026-11-11: write the code now, measure later): sibling branch `feat/v3.7.1-ladder-parallel` adds `LADDER_JOBS` (default 1, the serial path unchanged), per-gate SCRATCH, the first gate of each target in the foreground, per-ROM locks, ordered replay before TOTAL, barriers before the VRC6 audio copy and `sdram-budgets`, and the refusal beside `tb/mutate.sh`. Its functions, driven against a throwaway Makefile, gave a log identical to the serial one and 4.60 s against 1.57 s on 4 jobs. Still to do on a quiet host: the per-stimulus timing table, longest-first ordering, the full serial-against-pool verdict comparison on both builds with a planted FAIL, the build-flag measurements, and the CI ladder. **MEASURED 2026-11-12, PARTIAL** (sibling `ee28245`, README): both ladders ran through the pool (`89a0609` cherry-picked onto the review fixes' RTL `0635bd5` in a throwaway worktree) at `LADDER_JOBS=6`: on-die 356 / 0 / 4 in 1 h 25 min, off-die (`USE_SDRAM=1`) 425 / 0 / 12 in 2 h 51 min, golden provenance 295 / 0 in both, against about ten hours serial for the v3.7.0 off-die ladder. Every verdict, in order, equals the serial run of the same gates on the previous commit `fc81dd1` (355 / 0 / 4 and 421 / 0 / 12); the only differences are the gates `0635bd5` added. That is the maintainer's chosen comparison, not a same-commit one: the serial runs on `0635bd5` were stopped at his request. Still to do: a same-commit serial-against-pool run with a planted FAIL, the per-stimulus timing table and longest-first ordering, the build-flag measurements, and `ladder.yml` (a `jobs` input, default 6, and a timeout of about twice the pooled off-die run; it is 300 minutes now) | v3.7.0 ladder runs | v3.7.1 (proposed), else v3.8.0 | -| `T-MOBILE-FORENSICS-DEADLINE` | On the mobile bridge, a netplay session that ends on a checksum mismatch with desync forensics on stays in `netplay_ended`, its UDP socket and forensic buffers included, until `np_forensics()` produces a report or the host calls `np_leave()`. If the peer did not opt in or stops answering, nothing reclaims it. The desktop drops the ended session after `FORENSICS_DEADLINE` (10 s, `NetplayUi::tick_investigating`). Give the bridge the same deadline, so `np_forensics()` reports "no report" and releases the session once it passes. Gate: a bridge test where the peer never answers, which sees the session released after the deadline and the socket closed. Found by Antigravity on #646 (round 5) | v3.7.0 review (#646) | v3.7.1 (proposed), else v3.8.0 | -| `T-CI-TESTROMS-LTO` | `test-roms` compiles about 55 release test binaries with the workspace's `lto = "fat"`, `codegen-units = 1`: 7 min 56 s of compile before about 12.5 min of tests (main run 43133040884), the critical path of every accuracy PR. A CI-only `CARGO_PROFILE_RELEASE_LTO` / `CARGO_PROFILE_RELEASE_CODEGEN_UNITS` override changes no assertion, but may slow the tests by losing cross-crate inlining, sign unknown. Gate: the job dispatched twice with and twice without the override on a quiet day; adopted only on a consistent net gain in both pairs (`docs/agents/ci-and-release.md`, the 2026-11-12 cost audit, PR #650) | CI cost audit (#650) | v3.7.1 (proposed), else v3.8.0 | -| `T-CI-ANDROID-ONE-NDK` | Android CI compiles the same Rust three times per run: `kotlin-unit-tests` and `gradle-bundle` re-run cargo-ndk through Gradle's `cargoNdkBuild` after `cross-build` has built and uploaded the libraries (`docs/agents/ci-and-release.md`, PR #650). Feed the uploaded `.so` files to Gradle with a property that skips `cargoNdkBuild` and `uniffiBindgen`. Gate: one cargo-ndk build per run, the app and its JVM tests unchanged. **IN PROGRESS 2026-11-12** (branch `ci/android-single-ndk`, no commit yet) | CI cost audit (#650) | merged #651 (`9cfc9f40`) | -| `T-CI-CACHE-PR-EVICT` | After #650 fixed the cargo cache, the oracle's Actions cache reached 103 entries and 9.42 GB of the 10 GB per-repository limit (2026-11-12), `main`'s `v1-rust-*` caches 117-908 MB each; PR-scoped caches therefore evict `main`'s warm ones. A `pull_request: closed` job deletes only that PR's `refs/pull//merge` caches | CI cost audit follow-up (2026-11-12) | v3.7.1 (proposed), else v3.8.0 | +| `T-TEST-COVERAGE-PARALLEL` | `external_coverage_boot_smoke` (`crates/rustynes-test-harness/tests/external_coverage.rs`) is one `#[test]` that boots every staged commercial ROM in a serial loop, so it runs on one core: 6,493 s (about 108 minutes) of the v3.7.0 full release suite, while cargo runs test binaries one at a time and the other cores sit idle. Each boot builds its own `Nes`, and determinism holds per ROM, so the boots can run in parallel without changing a result: split the list across `std::thread::scope` workers (no new dependency), keep the per-ROM `catch_unwind`, and sort the combined failure list so the report stays deterministic. Snapshot names are already explicit, so they do not depend on the thread. Gate: on the full local corpus, the parallel sweep reports exactly the serial sweep's per-ROM results (the same snapshots, the same failure list, including a planted failure), and its wall time is measured and recorded. **Decided 2026-11-11 (maintainer): post-release, not in the v3.7.0 release PR** (changing a gate mid-release would mean re-running the suite to prove it). **CODE LANDED, MEASUREMENT PENDING** (maintainer 2026-11-11: write the code now, measure later): `parallel_map_ordered` + `RUSTYNES_COVERAGE_JOBS`, its ordering test mutation-checked; a smoke run on the 7 mapper-007 ROMs gave the same outcome and SKIP lines serially (53.2 s) and on 4 workers (17.0 s, on a loaded machine, so not a measurement). Still to do on a quiet host: the full-corpus serial-vs-parallel equality run with a planted failure, and the recorded wall times. **Slotted 2026-11-12:** v3.7.1 if the maintainer cuts it (`plans/v3.7.1-plan.md`), else v3.8.0 | v3.7.0 full-suite run | v3.7.2 (deferred from v3.7.1 on 2026-11-15: the timing run needs a quiet host) | +| `T-MISTER-LADDER-PARALLEL` | The sibling's co-simulation ladder (`tb/regress.sh`, 2,621 lines) runs every stimulus in series, each one a single-threaded Verilator model, so a ladder uses about one core of twenty: the v3.7.0 off-die ladder was about 40% through after five hours. The models build in parallel (`-j 0`); only the runs are serial. First, time every stimulus and record the table. Then run independent stimuli from a job pool (`wait -n` or `xargs -P`), longest first, after every model is built; give each stimulus its own scratch and output paths; print each stimulus's output in registry order, so the PASS / FAIL / XFAIL tally and the log read exactly as before; and refuse to run beside a mutation harness, which rewrites the RTL. Also measure, and adopt only on evidence: `-O3 -march=native`, clang, PGO of the Verilated C++ (now `-O2`), and Verilator `--threads` (likely a loss on a design this small). Do not change `--x-initial`, which alters what an uninitialised register holds. `OBJCACHE=ccache` speeds rebuilds only. Gate: on both builds the parallel ladder gives the serial ladder's verdict for every stimulus, a planted FAIL included, and the wall times are recorded; the sibling's CI ladder adopts the pool too. **Decided 2026-11-11 (maintainer): post-release, not inside v3.7.0's ladder runs**. **CODE LANDED, MEASUREMENT PENDING** (maintainer 2026-11-11: write the code now, measure later): sibling branch `feat/v3.7.1-ladder-parallel` adds `LADDER_JOBS` (default 1, the serial path unchanged), per-gate SCRATCH, the first gate of each target in the foreground, per-ROM locks, ordered replay before TOTAL, barriers before the VRC6 audio copy and `sdram-budgets`, and the refusal beside `tb/mutate.sh`. Its functions, driven against a throwaway Makefile, gave a log identical to the serial one and 4.60 s against 1.57 s on 4 jobs. Still to do on a quiet host: the per-stimulus timing table, longest-first ordering, the full serial-against-pool verdict comparison on both builds with a planted FAIL, the build-flag measurements, and the CI ladder. **MEASURED 2026-11-12, PARTIAL** (sibling `ee28245`, README): both ladders ran through the pool (`89a0609` cherry-picked onto the review fixes' RTL `0635bd5` in a throwaway worktree) at `LADDER_JOBS=6`: on-die 356 / 0 / 4 in 1 h 25 min, off-die (`USE_SDRAM=1`) 425 / 0 / 12 in 2 h 51 min, golden provenance 295 / 0 in both, against about ten hours serial for the v3.7.0 off-die ladder. Every verdict, in order, equals the serial run of the same gates on the previous commit `fc81dd1` (355 / 0 / 4 and 421 / 0 / 12); the only differences are the gates `0635bd5` added. That is the maintainer's chosen comparison, not a same-commit one: the serial runs on `0635bd5` were stopped at his request. Still to do: a same-commit serial-against-pool run with a planted FAIL, the per-stimulus timing table and longest-first ordering, the build-flag measurements, and `ladder.yml` (a `jobs` input, default 6, and a timeout of about twice the pooled off-die run; it is 300 minutes now) | v3.7.0 ladder runs | v3.7.1 (the pool and `ladder.yml`'s `jobs` input, sibling #76); anything the row still lists as to do, v3.7.2 | +| `T-MOBILE-FORENSICS-DEADLINE` | On the mobile bridge, a netplay session that ends on a checksum mismatch with desync forensics on stays in `netplay_ended`, its UDP socket and forensic buffers included, until `np_forensics()` produces a report or the host calls `np_leave()`. If the peer did not opt in or stops answering, nothing reclaims it. The desktop drops the ended session after `FORENSICS_DEADLINE` (10 s, `NetplayUi::tick_investigating`). Give the bridge the same deadline, so `np_forensics()` reports "no report" and releases the session once it passes. Gate: a bridge test where the peer never answers, which sees the session released after the deadline and the socket closed. Found by Antigravity on #646 (round 5) | v3.7.0 review (#646) | v3.7.1 (#659) | +| `T-CI-TESTROMS-LTO` | `test-roms` compiles about 55 release test binaries with the workspace's `lto = "fat"`, `codegen-units = 1`: 7 min 56 s of compile before about 12.5 min of tests (main run 43133040884), the critical path of every accuracy PR. A CI-only `CARGO_PROFILE_RELEASE_LTO` / `CARGO_PROFILE_RELEASE_CODEGEN_UNITS` override changes no assertion, but may slow the tests by losing cross-crate inlining, sign unknown. Gate: the job dispatched twice with and twice without the override on a quiet day; adopted only on a consistent net gain in both pairs (`docs/agents/ci-and-release.md`, the 2026-11-12 cost audit, PR #650) | CI cost audit (#650) | v3.7.2 (deferred from v3.7.1 on 2026-11-15: needs a CI dispatch input first) | +| `T-CI-ANDROID-ONE-NDK` | Android CI compiles the same Rust three times per run: `kotlin-unit-tests` and `gradle-bundle` re-run cargo-ndk through Gradle's `cargoNdkBuild` after `cross-build` has built and uploaded the libraries (`docs/agents/ci-and-release.md`, PR #650). Feed the uploaded `.so` files to Gradle with a property that skips `cargoNdkBuild` and `uniffiBindgen`. Gate: one cargo-ndk build per run, the app and its JVM tests unchanged. **DONE in v3.7.1** (#651, `9cfc9f40`) | CI cost audit (#650) | merged #651 (`9cfc9f40`) | +| `T-CI-CACHE-PR-EVICT` | After #650 fixed the cargo cache, the oracle's Actions cache reached 103 entries and 9.42 GB of the 10 GB per-repository limit (2026-11-12), `main`'s `v1-rust-*` caches 117-908 MB each; PR-scoped caches therefore evict `main`'s warm ones. A `pull_request: closed` job deletes only that PR's `refs/pull//merge` caches | CI cost audit follow-up (2026-11-12) | v3.7.1 (#658) | | `T-CI-MAIN-CACHE-SIZE` | `main` alone held 21 Actions caches, 9.86 GB of the 10 GB limit (2026-11-12, after every PR cache had been evicted), so any PR's caches evict `main`'s warm ones within hours whatever `T-CI-CACHE-PR-EVICT` does at close. Measure which keys are largest (the `v1-rust-*` caches were 117-908 MB each), then trim what they save (target dirs per job, duplicate keys) until `main` fits with headroom; record before and after | `T-CI-CACHE-PR-EVICT` measurement (2026-11-12) | v3.8.0 | | `T-LIBRETRO-NOTICES` | The libretro core ships without the licence and the third-party notices. The desktop archives carry `LICENSE` and `NOTICE` (release.yml), and since #664 so do the Android and iOS apps and the web site, but the core is built and distributed by the libretro buildbot from `.gitlab-ci.yml`, whose central ci-templates ship only the core library and its archive; `rustynes_libretro.info` carries only `license = "GPLv3+"`. The core contains the same MIT- and ISC-licensed derived code (TriCNES, emu2413, Lua, ares ...), whose licences require their notices in every copy, and the GPL requires its text with the binary. Options: ask libretro whether ci-templates or the `.info` can carry a notices file; or state in the libretro docs page (docs.libretro.com, synced through `docs/libretro/UPSTREAM_SYNC.md`) where the notices are, with a link to `NOTICE`. Gate: a buildbot core archive, or the page every core's users are pointed to, carries or links both texts. Found 2026-11-15 by the notice audit on #664 | #664 notice audit | v3.8.0 | | `T-ICONS-PACK` | The icon pack's "RN" cartridge art as the icon of every build: window, Windows `.exe` (embedded `.ico`), macOS `RustyNES.app` (new, ad-hoc signed), Linux `share/` (`.desktop` + hicolor), web, Android, iOS, README and docs site. Help -> About keeps the old gear-and-peripherals art (#656) | maintainer, 2026-11-12 | v3.7.1 | diff --git a/to-dos/plans/v3.7.1-plan.md b/to-dos/plans/v3.7.1-plan.md index f5613a8ed..c639a54d9 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: the spectator id, and faster gates (PROPOSED) - -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. +# 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 +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) @@ -27,6 +41,22 @@ gate. The codename is asked at the cut. stays 10 (`"RN10"`) and save states, movies and sessions carry over. The MiSTer core's FDS and battery-save fixes (rows 14-17) change RTL, so the release carries a seed sweep and new bitstreams (row 13). + **One MiSTer exception (2026-11-14):** the end-of-side fix (sibling + `1dca747`) adds the drive's end-of-head flag to the off-die save state, so + that build's fingerprint moves `D4E792FE` -> `6C9E7051` and **v3.7.0 + off-die save states are refused** by v3.7.1. The on-die (Lite) build's + stays `BEE10697`. The release notes must say so. + **One known issue ships (2026-11-14, maintainer: ticket it):** + `T-MISTER-SAVE-XFER-ACROSS-LOAD`. A battery write-back still running when + a new cartridge loads keeps going, and could land in the new game's `.sav` + (a window of a few milliseconds after the OSD opens). The release notes + name it as a known issue. **Three more ride with it (2026-11-15, + maintainer: ticket, merge #77)**, from Antigravity's fifth round on + `22747c0`, each real and each outside any BIOS or game path: a write that + reaches a side's end and then switches to read without a motor restart + reads the next side's bytes; `save_ctl` can start an OSD save on the clock + a `.sav` mount arrives; `fds_save` may lose unsaved disk writes when a + size-0 mount abandons a save in progress. The notes name all four. - **The rest is cheap, and pays off at v3.8.0.** The ladder pool cuts a ladder from about ten hours serial to under three (sibling `ee28245`). The parallel coverage boot targets 108 minutes of the full suite (#648). Both @@ -60,10 +90,10 @@ gate. The codename is asked at the cut. | # | Item | Gate | | --- | --- | --- | | 3 | `T-MOBILE-FORENSICS-DEADLINE`: the bridge drops a session that ended on a checksum mismatch once a deadline passes, as the desktop does (`FORENSICS_DEADLINE`, 10 s, `crates/rustynes-frontend/src/netplay_ui.rs`) | A bridge test where the peer never answers: `np_forensics()` reports no report after the deadline, the session is released and the socket closed; the mutant without the deadline fails it | -| 4 | `T-TEST-COVERAGE-PARALLEL`: measure the parallel boot from #648 | On the full local corpus, `RUSTYNES_COVERAGE_JOBS=1` and the parallel default give the same per-ROM results and the same sorted failure list, a planted failure included; both wall times recorded in `docs/performance.md` or the ticket, on a quiet host | +| 4 | `T-TEST-COVERAGE-PARALLEL`: measure the parallel boot from #648 | On the full local corpus, `RUSTYNES_COVERAGE_JOBS=1` and the parallel default give the same per-ROM results and the same sorted failure list, a planted failure included; both wall times recorded in `docs/performance.md` or the ticket, on a quiet host **Deferred to v3.7.2 (2026-11-15):** its gate needs a quiet host, and the release's seed sweep (row 13) held this one with six Quartus compiles for most of the cut day; a measurement on a loaded host is not a measurement (Risks). The code is on `main` (#648) and its ordering test is mutation-checked; only the timing run is outstanding | | 5 | The CI cost audit (#650, **merged** `8669b2cc`): the cargo cache, the platform-gated `full-build`, the schedule-run fix, the `opll.rs` lint | #650's own checks green; merged before the cut | | 6 | `T-CI-ANDROID-ONE-NDK`, **merged** (#651, `9cfc9f40`) | One cargo-ndk build per Android run; `kotlin-unit-tests` and `gradle-bundle` unchanged in result | -| 7 | `T-CI-TESTROMS-LTO`, an A/B | `test-roms` dispatched twice with `CARGO_PROFILE_RELEASE_LTO` overridden and twice without, on a quiet day; adopted only if both pairs show a net gain; recorded either way | +| 7 | `T-CI-TESTROMS-LTO`, an A/B | `test-roms` dispatched twice with `CARGO_PROFILE_RELEASE_LTO` overridden and twice without, on a quiet day; adopted only if both pairs show a net gain; recorded either way **Deferred to v3.7.2 (2026-11-15):** `ci.yml` has no dispatch input to override the profile, so the A/B needs that input first and then four full `test-roms` dispatches on a quiet day; it changes CI time only, no assertion, so it does not hold the release | | 8 | `T-TOOLCHAIN-1100`, only if Rust 1.100 is stable before the cut. **Done** (`chore/v3.7.1-rust-1.100`): 1.100.0 stable 2026-11-12; every pin moved together, the new clippy findings fixed (all 19 `cargo clippy` steps in `ci.yml`), full suite 4,270 / 0 / 29 on 1.100. Buildbot gate met: pipelines 135319, 135671 and 135681 failed only `libretro-build-windows-x64`, on `cannot find -lsynchronization` (Rust 1.100's std for `x86_64-pc-windows-gnu` links it; the image's GNU MinGW does not ship it). The job now builds that import library with `dlltool` (`.gitlab-ci.yml`), and pipeline 135698 passed all 15 jobs | `rust-toolchain.toml` and `.gitlab-ci.yml` moved together; every clippy feature set and the full suite on 1.100; a buildbot branch pipeline green on all 15 jobs before the merge | | 9 | `T-CI-CACHE-PR-EVICT`: delete a PR's Actions caches when it closes. Measured 2026-11-12, after #650's cache fix: 103 caches, 9.42 GB of the 10 GB per-repository limit, `main`'s `v1-rust-*` caches 117-908 MB each, so new caches start evicting `main`'s warm ones (least recently used goes first) | A `pull_request: closed` workflow that deletes only caches whose ref is `refs/pull//merge` (`gh cache delete` with `actions: write`); one closed PR's caches observed gone and `main`'s untouched; usage recorded before and after | | 9a | `T-ICONS-PACK` (maintainer, 2026-11-12): the icon pack (`assets/RustyNES_Icon_Pack/`) is the icon of every build, and Help -> About keeps the old gear-and-peripherals art. Covers the window icon, Windows `.exe` resource, a new macOS `RustyNES.app`, Linux `share/` files, web, Android, iOS, README and docs site (#656) | #656's CI green, including `full-build` (the Windows icon compile with `RUSTYNES_REQUIRE_EXE_ICON=1`, and the `.app`'s plist lint and `codesign --verify`) and the Android job; the release notes carry the Gatekeeper note for the ad-hoc-signed `.app`; **the maintainer downloads the release `.app` on the M5 Max and launches it** | @@ -125,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 |