release: v3.2.0 "Confluence"

.github/release-notes/v3.2.0.md

@@ -0,0 +1,63 @@
+# RustyNES v3.2.0 — "Confluence"
+
+Every v3.2.0 branch, both repositories, brought into one release. It adds 17 mapper families (191 to 208), among them the Bandai Datach with its barcode reader, and five more families are Curated on local-dump evidence. Five emulation defects are fixed: the VRC4's IRQ mode was read inverted, VRC2 mirroring had settings the chip does not have, *Fire Hawk* lost its single-screen mirroring on an iNES 1.0 header, mapper 290 did not boot, and a 24C02 EEPROM lost its word address across a START. An AI-made remediation branch was audited change by change before anything was kept: its byte-identical speed-ups are kept, and measured against the tree it joined: the APU mixes 2-6% faster and an MMC3 read about 9% faster, while its larger claims did not hold and two cartridge reads got slower for a reason not yet found; a 47% audio slowdown it introduced was found and removed; four of the five features it broke are fixed and kept, and Android audio is back on its blocking write, with the non-blocking version a ticket. Netplay moves to protocol 8, libretro save states shrink from 260 KB to about 16 KB, and new save files are owner-only. The MiSTer core gains sixteen boards, the Four Score, the Arkanoid controller, Game Genie cheats, more than eight sprites per line and custom palettes. **Movies and netplay from v3.1.x are refused, and so are v3.1.x save states of Bandai FCG games.**
+
+## Breaking changes
+
+- **Movies and netplay from v3.1.x are refused**: `EMULATION_EPOCH` rises from 3 to 4, because the mapper 290, 24C02, VRC4 IRQ, VRC2 and *Fire Hawk* fixes change what the bus sees. Save states are not affected by the epoch.
+- **v3.1.x save states of Bandai FCG games are refused** (mappers 16, 153, 157 and 159): their state now carries each serial EEPROM's protocol position, so a state taken mid-transaction resumes it instead of leaving the chip idle, which could make rewind, run-ahead and netplay rollback diverge. Other boards' states are unchanged.
+- **Netplay protocol 8 (`"RNE8"`)**: lost inputs are resent as one datagram per run of frames. A v3.1.x peer is refused as another emulator version.
+- **The `Mapper` trait requires `ppu_peek`** (a side-effect-free PPU read for the debugger), so a mapper implemented outside this repository must add it. `cpu_peek`, `may_unmap_prg_rom`, `is_save_data_dirty`, `clear_save_data_dirty` and three barcode-reader methods are added with defaults.
+
+## Fixed
+
+- **The VRC4's IRQ runs in the mode the game asks for** (mappers 21, 23 and 25): bit 2 of the IRQ control register was read inverted, so a raster split got a counter about 114 times too fast.
+- **VRC2 mirroring has two settings, not four**, and mappers 23 and 25 with NES 2.0 submapper 3 are built as the VRC2.
+- ***Fire Hawk* gets its single-screen mirroring from an iNES 1.0 header** (mapper 71, submapper 0, at the first `$9000` write).
+- **Mapper 290 (*Asder 20-in-1*) boots**, and **a 24C02 EEPROM keeps its word address across a START** (mappers 16 and 157).
+- **FDS disk games keep their saves on Android and iOS**, and **the Android screen stays on during play**.
+
+## Added
+
+- **Mapper 157, the Bandai Datach Joint ROM System**, with a barcode reader for the games that read cards.
+- **16 more families**: the MMC3-derived 114, 116, 165, 182, 197 and 215; FFE 6, 8 and 17; Tengen 158; TXC 172 and 173; Taito 207; the 235 multicarts and Waixing 252 (all Curated), and the 230 multicart (BestEffort). Mappers 47, 121, 154, 191 and 243 move to Curated. The split is now 51 Core, 130 Curated and 27 BestEffort: 181 of 208 families are accuracy-gated.
+- **Famicom-only carts boot as a Famicom in the coverage sweep**, so ten dumps listed as blank now draw.
+
+## Changed
+
+- **Libretro save states are about 16 KB instead of 260 KB**: the framebuffer is no longer stored, and a full-size state still loads.
+- **New save files are owner-only on Linux and macOS** (`0o600`).
+- **rustls 0.23.46**, for four TLS advisories published during the release (RUSTSEC-2026-0346 to 0349), in the netplay WebSocket and HTTP clients.
+- **The APU mixes 2-6% faster with expansion audio and 2-3% faster without**, byte-identical, in two independent A/B runs.
+- **An MMC3 cartridge read is about 9% faster, and run-ahead on an MMC3 game about 5%**, from cached bank offsets; byte-identical, two independent runs. Whole-frame time and the PPU do not change measurably. MMC5 and Sunsoft FME-7 reads measure 4.7% and 6% slower although neither read function changed; the cause is not established (`docs/performance.md`, "v3.2.0 import").
+
+## The AI remediation branch, audited
+
+An unpushed agent branch arrived with 61 audit findings already applied. Nothing was merged as is. Every change was read against the code it replaced, and each defect found has a test that fails without the fix. Kept: 20 as written, 14 corrected. Reverted: 4, the audio ring write behind the 47% slowdown, an MMC5 IRQ change under which the IRQ stopped firing in real play, and two unmeasured libretro rewrites; an FDS audio formula change inside a kept finding was reverted too, because it moved every FDS game's audio. Rejected: 10, including six of its seven FPGA findings, which did not hold when re-derived in simulation and synthesis. The ledger is `docs/audits/v3.2.0-round2-audit-disposition.md`; the report's "certified" and "100% bit-accurate" claims are recorded as unverified, and two of them were tested and are false.
+
+## The MiSTer core
+
+- **Release candidate, not hardware-verified.** No hardware has run either bitstream.
+- **Sixteen more boards**: UN1ROM, Nichibutsu UNROM, CPROM, J87, CNROM 185, GxROM, Jaleco JF-11/14, Color Dreams, NINA-03/06, Camerica 71 (including *Fire Hawk*) and 232, mapper 34, Namco 108, TxSROM, TQROM and MMC1 SUROM (off-die). Each is gated against the emulator, and thirteen against a commercial game's frame (SUROM's off-die only).
+- **The Four Score, the Arkanoid controller and Game Genie cheats**, gated against goldens exported with the same device.
+- **More than eight sprites per line** (on-die build) and **custom `.pal` palettes** with the emulator's emphasis model.
+- **The oracle pin moves to v3.2.0**: all 842 golden artifacts from 188 stems reproduce byte for byte.
+- **The co-simulation ladder**: 259 passed, 0 failed, 3 expected failures on-die and 260 / 0 / 5 off-die (v3.1.0: 212 / 0 / 1 and 213 / 0 / 1), each one run of a frozen tree, nothing skipped. The new expected failures are named and graded both ways: two commercial frames still differ from the emulator's, by one pixel (a sprite at X=255 on its last row) and by three scanlines of a mid-frame raster change, neither yet attributed; off-die, two more are a CHR-RAM read-back defect that predates this release (`T-MISTER-OFFDIE-CHRRAM`).
+- **New bitstreams at fitter seed 4**, chosen from eight seeds swept on build date 261014 by the rule both builds share: the on-die build's binding margin chooses, and the off-die build must close at the chosen seed. Seeds 5 and 6 lead on-die but do not close off-die; seeds 1 (v3.1.0's) and 4 tie next, and only 4 closes off-die. Each was compiled twice to the same bytes:
+  - on-die `RustyNES_MiSTer-v3.2.0.rbf`, md5 `e24820de2e302d3f6912524b3c97a2be` (+0.213 ns setup, +0.079 ns hold);
+  - off-die `RustyNES_MiSTer-v3.2.0-offdie.rbf`, md5 `c33ae2b14e5b8e07a68b4335c728ca03` (+0.038 / +0.080 ns). The +0.038 ns path is inside the FPGA (the SDRAM controller's read data into the CPU), so board delay does not consume it; the SDRAM read capture itself has +0.453 ns setup and +1.180 ns hold over all four timing corners, assuming zero board delay.
+
+## Verification
+
+- `--features test-roms,commercial-roms`: 3,669 passed, 0 failed, 16 ignored, across 176 test binaries.
+- The local commercial suites: `external_real_games` 60/0, `external_extended` 169/0, `external_coverage` 6/0 over every staged dump, 25 of them baselined new in this release.
+- Every clippy, rustdoc, `no_std` and wasm invocation CI runs (23), clean.
+- AccuracyCoin 146/146, nestest 0-diff, the epoch fingerprint at epoch 4, now recorded as the released epoch.
+
+## Install
+
+- Download the pre-built binaries for Linux, macOS, and Windows below.
+- The MiSTer core bitstreams are attached below, as a release candidate, not hardware-verified. The on-die build is `RustyNES_MiSTer-v3.2.0.rbf`, also attached under its datecoded name, and the off-die build is `RustyNES_MiSTer-v3.2.0-offdie.rbf`.
+- 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.

.github/workflows/ci.yml

@@ -892,10 +892,17 @@ jobs:
       # build script panics before a single Rust line is compiled. The NDK path
       # prefix matches `android.yml`'s (`$ANDROID_NDK_LATEST_HOME`, then
       # `toolchains/llvm/prebuilt/linux-x86_64/...`).
+      #
+      # The --target carries an API level since the runner image moved to NDK
+      # 30 (October 2026): its sys/cdefs.h fails with "Unversioned target
+      # triples are not supported!" for plain `aarch64-linux-android`, which
+      # is the triple bindgen hands clang. 26 is the Android app's minSdk and
+      # the `--platform 26` cargo-ndk builds with, so the bindings see the
+      # same headers the shipped core is built against.
       - name: Point bindgen at the NDK sysroot
         if: matrix.target == 'aarch64-linux-android'
         run: |
-          echo "BINDGEN_EXTRA_CLANG_ARGS_aarch64_linux_android=--sysroot=$ANDROID_NDK_LATEST_HOME/toolchains/llvm/prebuilt/linux-x86_64/sysroot" >> "$GITHUB_ENV"
+          echo "BINDGEN_EXTRA_CLANG_ARGS_aarch64_linux_android=--target=aarch64-linux-android26 --sysroot=$ANDROID_NDK_LATEST_HOME/toolchains/llvm/prebuilt/linux-x86_64/sysroot" >> "$GITHUB_ENV"
       # Provision the aarch64 glibc headers for bindgen (see the matrix note).
       # `libc6-dev-arm64-cross` lands the aarch64 glibc headers under
       # `/usr/aarch64-linux-gnu/include`; `--sysroot` sends clang there instead of
@@ -1042,7 +1049,8 @@ jobs:
 
   # v2.9.4 — the eight fuzz targets under fuzz/ were built by nobody: no
   # workflow mentioned them, so a target could stop compiling and nothing would
-  # say so. This builds all eight and runs each for a FIXED number of inputs from
+  # say so. This builds them all (nine since v3.2.0's `movie_import`, the five
+  # foreign-movie importers) and runs each for a FIXED number of inputs from
   # a FIXED seed, so a run is reproducible and a failure is a real crash, not a
   # time-box artifact. It starts from an empty corpus (fuzz/corpus is local).
   # Measured on the maintainer's machine with the local corpus: ~70 s for all
@@ -1051,7 +1059,7 @@ jobs:
   # libFuzzer needs nightly; the fuzz crate is its own workspace (fuzz/Cargo.toml),
   # so the project pin in rust-toolchain.toml does not apply to it.
   fuzz:
-    name: fuzz (8 targets, fixed seed)
+    name: fuzz (9 targets, fixed seed)
     needs: [changes, setup]
     if: ${{ needs.changes.outputs.code == 'true' && needs.setup.outputs.heavy == 'true' }}
     runs-on: ubuntu-26.04
@@ -1065,7 +1073,7 @@ jobs:
           toolchain: nightly
           apt: "false"
           cache-key: fuzz
-      - uses: taiki-e/install-action@v2.87.26
+      - uses: taiki-e/install-action@v2.87.27
         with:
           tool: cargo-fuzz
       - name: Build and run every fuzz target
@@ -1082,7 +1090,7 @@ jobs:
           cargo +nightly fuzz build -O --target x86_64-unknown-linux-gnu
           targets=$(cargo +nightly fuzz list)
           n=$(printf '%s\n' "$targets" | grep -c .)
-          [ "$n" -ge 8 ] || { echo "::error::expected at least 8 fuzz targets, found $n"; exit 1; }
+          [ "$n" -ge 9 ] || { echo "::error::expected at least 9 fuzz targets, found $n"; exit 1; }
           # Run EVERY target even after one crashes, so a single run reports
           # all of them rather than the first (agy on #574).
           failed=""
@@ -1129,7 +1137,7 @@ jobs:
         with:
           components: llvm-tools-preview
           cache-key: coverage
-      - uses: taiki-e/install-action@v2.87.26
+      - uses: taiki-e/install-action@v2.87.27
         with:
           tool: cargo-llvm-cov
       - run: cargo llvm-cov --workspace --lib --summary-only --fail-under-lines 70

.github/workflows/security.yml

@@ -76,7 +76,7 @@ jobs:
       # Reason 2 was an ACTIVE constraint until the v1.3.0 pin bump (1.86 vs
       # cargo-audit's 1.88); it is slack today and can bind again after an MSRV
       # change in either direction, so it is kept rather than deleted as history.
-      - uses: taiki-e/install-action@v2.87.26
+      - uses: taiki-e/install-action@v2.87.27
         with:
           tool: cargo-audit
       - run: cargo audit
@@ -92,7 +92,7 @@ jobs:
       # Prebuilt binary for the same two reasons as the audit job above: it is
       # much faster than compiling cargo-deny, and it keeps the security gate
       # independent of this repo's rustc pin. Policy lives in `deny.toml`.
-      - uses: taiki-e/install-action@v2.87.26
+      - uses: taiki-e/install-action@v2.87.27
         with:
           tool: cargo-deny
       - run: cargo deny check

.gitignore

@@ -352,6 +352,10 @@ WARP.md
 # 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/