Skip to content

Commit c23b612

Browse files
doublegateclaude
andcommitted
docs: settle v3.0.0's records where CodeRabbit found them stale
CodeRabbit on review slice #588, the documentation findings: - AGENTS.md still said the board move "leaves open what v3.0.0 itself ships". ADR 0043 settled that (API major plus a release-candidate core), and the sentence now says so. - ADR 0043: the 2026-10-05 amendment lists v3.0.0's own breaks, while the 2026-10-01 amendment concluded that v3.0.0 "no longer carries the API break". Amendments are never rewritten, so the newer one now states that it supersedes that conclusion, and why. - docs/netplay-webrtc.md implied both peers of a mixed-version session get a reason. Only a protocol-6 peer can give one; a v2.9.9 peer ignores "RNE6" and still times out. Between two protocol-6 peers, both now name it (the mesh reply in d9885a5). - SECURITY.md declared v3.0.0 current while its table still called 2.9.x "the current line". 3.0.x is now current and 2.9.x is ship-forward. Its claim that v2.0.0 is "the one deliberate breaking release" was also stale; it now names v2.0.0, v2.9.8 and v3.0.0, and the epoch refusal. - VERSION-PLAN.md listed v3.0.0 under "Planned next (not yet released)" beside its own (current) row. That row is removed, and to-dos/plans/README.md marks the v3.0.0 plan and the v2.9.4-to-v3.0.0 line as shipped. The ROADMAP.md finding from the same review is fixed at its cause, in the bump script (separate commit). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014qfTKi2M3swo7qnwvYCkDj
1 parent 08dad45 commit c23b612

6 files changed

Lines changed: 26 additions & 10 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ Enforcement lives alongside the prose: `/ref-proj/` is gitignored/`.dockerignore
4343

4444
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`).
4545

46-
**Current release: 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). v2.9.2 triaged a fifth, AI-written audit of both repositories (`docs/audits/v2.9.2-full-audit-report.md`, 32 findings) in its ledger, `docs/audits/v2.9.2-full-audit-disposition.md`: 16 fixed red-first, 2 changed but verifiable only on a device (the Swift halves of AUD-10/14), and the rest refuted, declined or deferred with evidence. The sweep written for AUD-02 found that save states dropped the cartridge RAM of twelve board families; `every_board_snapshot_carries_cartridge_ram` now round-trips the RAM of all 174 mapper ids. It changes emulation behaviour in one deliberate place: an unmapped `$4020-$FFFF` read now updates the CPU's internal data bus (AUD-03). Opposing-direction cancel (AUD-08/09/10) is on by default, by the maintainer's decision (2026-09-28). The MiSTer CPU's /NMI edge detector ran on the DMA-stalled enable and lost an NMI raised inside a DMA (AUD-24, gate `dmanmi074`). v2.9.1 fixed `scripts/perf/ab_check.sh` (both sides had built into one target directory) and re-measured the old rejections; the dead NMI detector's per-dot call (−4.1% to −4.7% on palette frames) is removed in v2.9.8, which carries ADR 0042's removals (its 2026-10-01 amendment). The libretro core is built with `panic = "unwind"`, exercised by a C-ABI harness (`crates/rustynes-libretro/src/abi_tests.rs`), and patches a vendored `rust-libretro-sys` (`vendor/`). **AccuracyCoin 144/144 and nestest 0-diff** hold on the v2.9.2 tree, and the full `--features test-roms` suite passes 2,867 tests. v2.7.4's mobile changes, and v2.9.2's Swift, have a device checklist (`docs/mobile-v2.7.4-device-checklist.md`), consolidated at v2.9.3 into `docs/mobile-v2.9.3-run-sheet.md` with an emulator pre-run; the device run itself moved after v3.0.0 (maintainer, 2026-09-29). The co-simulation is **173 passed, 0 failed, 1 expected failure** on-die and **174 / 0 / 1** off-die (`USE_SDRAM=1`), each ONE frozen-worktree ladder run with nothing skipped; both bitstreams compile at fitter seed 2, chosen from eight per build at one build date (on-die +0.510 ns setup / +0.108 ns hold, off-die +0.390 / +0.081; the SDRAM read is +0.447 setup / +1.184 hold), and two clean compiles of each are byte-identical. The SDRAM pin constraints stay provisional until the SuperStation One's memory is read. **No hardware has run any bitstream**. The board session was planned on v2.9.2's bitstreams (`tools/stage_board_kit.sh` in the sibling stages what it needs); the maintainer moved it after v3.0.0 (2026-09-29), which leaves open what v3.0.0 itself ships, since [ADR 0041](docs/adr/0041-hardware-release-is-v3.0.0.md) defined it as the hardware-verified core (see its 2026-09-29 amendment). Per-release detail lives in `CHANGELOG.md` and the GitHub releases; it is deliberately not duplicated here.
46+
**Current release: 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). v2.9.2 triaged a fifth, AI-written audit of both repositories (`docs/audits/v2.9.2-full-audit-report.md`, 32 findings) in its ledger, `docs/audits/v2.9.2-full-audit-disposition.md`: 16 fixed red-first, 2 changed but verifiable only on a device (the Swift halves of AUD-10/14), and the rest refuted, declined or deferred with evidence. The sweep written for AUD-02 found that save states dropped the cartridge RAM of twelve board families; `every_board_snapshot_carries_cartridge_ram` now round-trips the RAM of all 174 mapper ids. It changes emulation behaviour in one deliberate place: an unmapped `$4020-$FFFF` read now updates the CPU's internal data bus (AUD-03). Opposing-direction cancel (AUD-08/09/10) is on by default, by the maintainer's decision (2026-09-28). The MiSTer CPU's /NMI edge detector ran on the DMA-stalled enable and lost an NMI raised inside a DMA (AUD-24, gate `dmanmi074`). v2.9.1 fixed `scripts/perf/ab_check.sh` (both sides had built into one target directory) and re-measured the old rejections; the dead NMI detector's per-dot call (−4.1% to −4.7% on palette frames) is removed in v2.9.8, which carries ADR 0042's removals (its 2026-10-01 amendment). The libretro core is built with `panic = "unwind"`, exercised by a C-ABI harness (`crates/rustynes-libretro/src/abi_tests.rs`), and patches a vendored `rust-libretro-sys` (`vendor/`). **AccuracyCoin 144/144 and nestest 0-diff** hold on the v2.9.2 tree, and the full `--features test-roms` suite passes 2,867 tests. v2.7.4's mobile changes, and v2.9.2's Swift, have a device checklist (`docs/mobile-v2.7.4-device-checklist.md`), consolidated at v2.9.3 into `docs/mobile-v2.9.3-run-sheet.md` with an emulator pre-run; the device run itself moved after v3.0.0 (maintainer, 2026-09-29). The co-simulation is **173 passed, 0 failed, 1 expected failure** on-die and **174 / 0 / 1** off-die (`USE_SDRAM=1`), each ONE frozen-worktree ladder run with nothing skipped; both bitstreams compile at fitter seed 2, chosen from eight per build at one build date (on-die +0.510 ns setup / +0.108 ns hold, off-die +0.390 / +0.081; the SDRAM read is +0.447 setup / +1.184 hold), and two clean compiles of each are byte-identical. The SDRAM pin constraints stay provisional until the SuperStation One's memory is read. **No hardware has run any bitstream**. The board session was planned on v2.9.2's bitstreams (`tools/stage_board_kit.sh` in the sibling stages what it needs); the maintainer moved it after v3.0.0 (2026-09-29). That settled what v3.0.0 ships: [ADR 0043](docs/adr/0043-v3-is-the-api-major-and-a-release-candidate-core.md) makes it the API major with a release-candidate core, and hardware verification moves to a later v3.x release (it supersedes [ADR 0041](docs/adr/0041-hardware-release-is-v3.0.0.md)'s hardware-verified v3.0.0). Per-release detail lives in `CHANGELOG.md` and the GitHub releases; it is deliberately not duplicated here.
4747

4848
- **Timebase (v2.0.0)** — the scheduler substrate is rewritten from a five-counter dot-lockstep model to a single canonical cycle counter, every CPU cycle clocked in two halves (`start_cycle` / `end_cycle`) with any bus access split between them, and the PPU caught up to each half (ADR 0002 / ADR 0029), now the *only* scheduler path. This is a MAJOR-boundary breaking change (ADR 0003): `.rns` save-state and `.rnm` movie format epochs bump (ADR 0028) — a pre-v2.0.0 `.rns` slot now fails to load with a clear error instead of silently misinterpreting stale bytes. Landed across five betas + rc.1 (PRs #217–223). Also new: core-level **Vs. `DualSystem`** dual-console support (`Emu::Dual`, `crates/rustynes-core`) for the four Vs. arcade cabinet boards — core-and-test-harness-only, frontend wiring deferred. The R1/R2 MMC3 IRQ-timing residual is by-design-deferred beyond this release with a mechanism-level finding recorded in ADR 0002 (not closed, not silently dropped). **AccuracyCoin now measures 141/141 (100.00%)**: the v2.0.1 upstream AccuracyCoin re-sync grew the catalog to 146 rows / 141 assigned tests and briefly opened two new PPU gaps ("ALE + Read" $0491, "Hybrid Addresses" $0492), which **v2.0.3** closed by promoting the 2-cycle-ALE PPU fetch model to the unconditional default (both experimental flags retired; additive `PPU_SNAPSHOT_VERSION` v5 tail). AccuracyCoin held 100% (139/139) throughout the v2.0.0 betas and final cut, dipped to 139/141 under the v2.0.1 re-sync, and is back to a full 141/141 from v2.0.3 onward.
4949

‎SECURITY.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ Report against the latest release or `main`.
1010
| Version | Supported | Notes |
1111
| ------------- | --------- | ----- |
1212
| main | Yes | Where fixes land first |
13-
| 2.9.x | Yes | The current line |
13+
| 3.0.x | Yes | The current line |
14+
| 2.9.x | Partial | Fixes are shipped forward into the current line, not backported |
1415
| 2.8.x | Partial | Fixes are shipped forward into the current line, not backported |
1516
| 2.7.x | Partial | Fixes are shipped forward into the current line, not backported |
1617
| 2.6.x | Partial | Fixes are shipped forward into the current line, not backported |
@@ -23,10 +24,13 @@ Report against the latest release or `main`.
2324
Two boundaries are worth stating explicitly, because they change what a report
2425
means rather than merely how old it is:
2526

26-
- **v2.0.0 "Timebase"** is the one deliberate breaking release (ADR 0003 /
27-
ADR 0028). A `.rns` save state or `.rnm` movie written before it is refused
28-
with a clear error rather than reinterpreted, so a pre-v2.0.0 parsing report
29-
is not reproducible against a current build by design.
27+
- **Three releases break formats by design.** v2.0.0 "Timebase" (ADR 0003 /
28+
ADR 0028), v2.9.8 "Vanguard" and v3.0.0 "Cornerstone" (ADR 0043 / 0044 /
29+
0045). A `.rns` save state or `.rnm` movie written before the current
30+
format is refused with a clear error rather than reinterpreted, so a parsing
31+
report against an older format is not reproducible against a current build
32+
by design. From v3.0.0 a movie or netplay peer from another emulation epoch
33+
is refused the same way.
3034
- **v2.2.9** relicensed the project to **GPL-3.0-or-later** (ADR 0036). That is
3135
a licensing correction, not a SemVer break — no public API or format moved.
3236

0 commit comments

Comments
 (0)