rustynes_core/

vs_dualsystem.rs

// SPDX-License-Identifier: GPL-3.0-or-later
//
// Provenance: the Vs. DualSystem orchestration (main/sub stepping per `NesConsole::RunFrame` / `RunVsSubConsole`, the reset-time seed per `VsControlManager::Reset`, the main/sub bit per `UpdateMainSubBit`, and the coin routing per `VsControlManager`) is derived from Mesen2 (GPL-3.0-or-later). See docs/originality-and-provenance.md (Section 1) and NOTICE. Classified v2.9.9 (core re-audit NC-17, maintainer's decision 2026-10-04): the in-source citations below record the derivation and are kept as written.

//! Vs. `DualSystem` — two complete NES systems in one arcade cabinet
//! (v2.0.0 beta.5, Workstream C of the "Timebase" plan).
//!
//! The `DualSystem` boards (Vs. Tennis, Vs. Mahjong, Vs. Wrecking Crew,
//! Vs. Balloon Fight) carry **two CPUs, two PPUs, and two work RAMs**,
//! sharing a small inter-CPU communication signal, a 2 KiB work RAM, and
//! the coin/DIP panel — each half drives its own screen. `RustyNES` models
//! this as a wrapper over two byte-identical [`Nes`] instances:
//!
//! ```text
//! VsDualSystem
//! ├── main: Nes   (the primary cabinet half; $4016 bit 7 reads 0)
//! ├── sub:  Nes   (the secondary half;      $4016 bit 7 reads 0x80)
//! └── the comms latch + shared-WRAM ownership (wrapper-owned)
//! ```
//!
//! **The wrapper owns ALL cross-wiring** (the design rule from
//! `docs/audit/vs-dualsystem-design-2026-06-11.md`): the two buses never
//! hold references to each other. Each bus only *records* its `$4016`
//! bit-1 (main/sub comms signal) levels and *accepts* an external-IRQ
//! level; the wrapper polls the levels after every stepped instruction
//! and applies the protocol (IRQ wiring per Mesen2
//! `Core/NES/Mappers/VsSystem/VsControlManager.cpp`; memory model per
//! MAME `src/mame/nintendo/vsnes.cpp`, where the four `DualSystem` games
//! verifiably run):
//!
//! - a `$4016` bit-1 write going **LOW asserts the PARTNER console's
//!   external `/IRQ`**; going high clears it (`UpdateMainSubBit`; MAME:
//!   `cpu.set_input_line(0, (data & 2) ? CLEAR_LINE : ASSERT_LINE)`);
//! - the shared 2 KiB WRAM at `$6000-$67FF` (mirrored ×4 across the 8 KiB
//!   window) is **simultaneously visible to both CPUs** — MAME maps ONE
//!   RAM `.share("nvram")` into both address spaces with no access mux.
//!   (nesdev/Mesen2 document a `$4016`-bit-1 access mux instead, but
//!   Balloon Fight's boot handshake polls a mailbox the partner writes
//!   while the mux would deny it access — under exclusive routing the
//!   boot provably deadlocks, so the MAME model is adopted.) Realized as
//!   two per-console copies converged by draining each mapper's write log
//!   into the partner after every stepped instruction;
//! - coins 1/2 + service drive main; coins 3/4 drive sub;
//! - each console owns its own DIP bank (Mesen2's `dipSwitches >> 8` /
//!   MAME's `DSW0`/`DSW1` for the sub is realized structurally: two
//!   buses, two `vs_dip` bytes).
//!
//! **Stepping** mirrors Mesen2 `NesConsole::RunFrame` +
//! `RunVsSubConsole`: the main console steps one instruction, then the
//! sub runs until it is within a **5-CPU-cycle gap** of the main (or has
//! caught up to the main's frame count) — a *soft* lockstep. Both
//! consoles run the same deterministic one-clock core, so the interleave
//! is reproducible run-to-run (the determinism contract holds per
//! console; the 5-cycle tolerance is the documented coupling knob).
//!
//! **Out of scope by design** (stated in the plan + the design doc):
//! netplay (rollback assumes one state blob) and `RetroAchievements` (one
//! memory map) do not support the dual path. Audio: the frontend drains
//! the MAIN console's mixer (each cabinet half has its own speaker; the
//! sub's audio is synthesized but undrained until a frontend feature
//! surfaces it).

use alloc::boxed::Box;
use alloc::vec::Vec;

use crate::nes::Nes;
use crate::rewind::{REWIND_DEFAULT_KEYFRAME_PERIOD, REWIND_DEFAULT_MAX_BYTES, RewindRing};
use crate::save_state::SnapshotError;
use rustynes_mappers::RomError;

/// Container magic for the dual-system save-state (see
/// [`VsDualSystem::snapshot`]).
const SNAPSHOT_MAGIC: [u8; 4] = *b"RVSD";
/// Dual-container layout version.
const SNAPSHOT_VERSION: u16 = 1;

/// Two complete NES systems + the cabinet's cross-wiring. See the module
/// docs for the architecture and protocol.
pub struct VsDualSystem {
    main: Nes,
    sub: Nes,
    /// The MAIN console's last-applied `$4016` bit-1 level (the sub's
    /// `/IRQ` driver).
    main_bit1: bool,
    /// The SUB console's last-applied `$4016` bit-1 level (the main's
    /// `/IRQ` driver).
    sub_bit1: bool,
    /// Reusable scratch buffer for `pump_comms`'s shared-WRAM drain, in
    /// both directions. `Vec::drain` on the mapper side keeps the log's
    /// OWN capacity; this buffer keeps the WRAPPER side allocation-free
    /// too, once warmed up — `pump_comms` runs after every stepped
    /// instruction on a `DualSystem` cart, so a per-call heap allocation
    /// here would be a real hot-path cost, not a theoretical one.
    comms_scratch: Vec<(u16, u8)>,
    /// v2.9.1 (NL-09) — one console's snapshot on its way into the cabinet's
    /// container, reused by [`Self::snapshot_into`]. A console's encoder
    /// clears the buffer it is given (it writes its own header first), so the
    /// two blocks cannot be encoded straight into the container; they pass
    /// through this instead. Not state: never serialized, never compared.
    block_scratch: Vec<u8>,
    /// v3.1.0 (`T-PS-dual-runahead`, ADR 0032 amendment of 2026-10-07) — the
    /// cabinet's rewind ring, holding whole-cabinet `RVSD` containers.
    /// `None` (the default) until a frontend opts in with
    /// [`Self::enable_rewind`].
    ///
    /// The ring lives on the cabinet, not on either console, because the unit
    /// of rewind is the cabinet: the two consoles share a 2 KiB WRAM and drive
    /// each other's `/IRQ`, so stepping one back without the other produces a
    /// cabinet from two timelines. Each console's own [`Nes`] ring stays
    /// disabled. Not state: never serialized, never compared.
    rewind: Option<RewindRing>,
    /// When `false`, [`Self::run_frame`] skips the rewind capture. Run-ahead
    /// clears it across its hidden and visible frames, so the ring holds the
    /// persistent timeline only (the same contract as
    /// [`Nes::set_rewind_capture`]).
    rewind_capture_enabled: bool,
    /// Reused buffer for the per-frame rewind capture (a cabinet container is
    /// about 520 KB before the ring compresses it).
    rewind_snap_buf: Vec<u8>,
}

impl VsDualSystem {
    /// Construct the dual system from one ROM image. A proper `DualSystem`
    /// dump carries BOTH CPUs' programs (64 KiB PRG: main half then sub
    /// half — MAME's `prg` + `sub` regions; Mesen2's `prgOuter` split);
    /// the sub console's mapper banks the second half. A 32 KiB
    /// (main-half-only) dump constructs and runs, but its boot handshake
    /// cannot complete — the sub-CPU program is simply absent.
    ///
    /// The caller has already determined the cart is a `DualSystem` board
    /// (the SHA-keyed `vs_db` `dual_system` flag — see [`crate::Emu`]).
    ///
    /// # Errors
    ///
    /// Returns the underlying [`RomError`] if the bytes don't parse.
    pub fn from_rom(bytes: &[u8]) -> Result<Self, RomError> {
        Ok(Self::from_pair(
            Nes::from_rom(bytes)?,
            Nes::from_rom(bytes)?,
        ))
    }

    /// Construct the dual system with an explicit audio sample rate (the
    /// frontend's output-device rate), applied to BOTH consoles.
    ///
    /// The sample rate is baked into each `Nes` at construction (there is no
    /// runtime setter), so the desktop present path — which knows the cpal
    /// device rate — must build the pair through this constructor for the main
    /// console's audio to resample correctly. Otherwise identical to
    /// [`Self::from_rom`].
    ///
    /// # Errors
    ///
    /// Returns the underlying [`RomError`] if the bytes don't parse.
    pub fn from_rom_with_sample_rate(bytes: &[u8], sample_rate: u32) -> Result<Self, RomError> {
        Ok(Self::from_pair(
            Nes::from_rom_with_sample_rate(bytes, sample_rate)?,
            Nes::from_rom_with_sample_rate(bytes, sample_rate)?,
        ))
    }

    /// Wire two freshly-constructed consoles into a `DualSystem` cabinet: mark
    /// the sub half, provision the shared WRAM on both, and seed the reset-time
    /// bit-1 handshake. Shared by every constructor so the wiring can never
    /// drift between them.
    fn from_pair(main: Nes, sub: Nes) -> Self {
        let mut dual = Self {
            main,
            sub,
            main_bit1: false,
            sub_bit1: false,
            comms_scratch: Vec::new(),
            block_scratch: Vec::new(),
            rewind: None,
            rewind_capture_enabled: true,
            rewind_snap_buf: Vec::new(),
        };
        dual.wire();
        dual
    }

    /// Install the cabinet wiring on a freshly constructed or freshly
    /// power-cycled pair. Shared by [`Self::from_pair`] and
    /// [`Self::power_cycle`] (v2.9.8), so a power-cycled cabinet is wired
    /// exactly as a new one is.
    fn wire(&mut self) {
        let dual = self;
        // Cabinet wiring: mark the sub half (its $4016 bit 7 reads 0x80;
        // its mapper banks the second PRG half + upper CHR pages — the two
        // CPUs run different programs on real DualSystem boards) and
        // provision the shared 2 KiB WRAM on BOTH consoles (each holds a
        // copy; `pump_comms` converges them — the MAME `.share("nvram")`
        // model).
        dual.sub.bus_mut().set_vs_sub(true);
        dual.sub.bus_mut().set_vs_dual_sub();
        dual.main.bus_mut().enable_vs_dual_wram();
        dual.sub.bus_mut().enable_vs_dual_wram();
        // Reset-time seed (Mesen2 `VsControlManager::Reset`:
        // `UpdateMainSubBit(main ? 0x00 : 0x02)`): the main half boots with
        // its bit-1 signal LOW — which asserts the SUB's external /IRQ —
        // and the sub boots with its signal HIGH (the main's /IRQ clear).
        // Wrecking Crew requires this seed to progress past its handshake.
        dual.apply_main_bit1(false);
        dual.apply_sub_bit1(true);
    }

    /// Apply a MAIN-console bit-1 level: drive the sub's `/IRQ` (LOW
    /// asserts, per Mesen2 `UpdateMainSubBit` / MAME
    /// `(data & 2) ? CLEAR_LINE : ASSERT_LINE`).
    const fn apply_main_bit1(&mut self, level: bool) {
        self.main_bit1 = level;
        self.sub.bus_mut().set_vs_external_irq(!level);
    }

    /// Apply a SUB-console bit-1 level: drive the main's `/IRQ`.
    const fn apply_sub_bit1(&mut self, level: bool) {
        self.sub_bit1 = level;
        self.main.bus_mut().set_vs_external_irq(!level);
    }

    /// Drain both consoles' `$4016` comms levels + shared-WRAM write logs
    /// and apply the protocol. Called after every stepped instruction on
    /// either console, so partner-visible effects land with at most one
    /// instruction of latency (within the 5-cycle soft-lockstep window).
    fn pump_comms(&mut self) {
        if let Some(level) = self.main.bus_mut().take_vs_mainsub_edge() {
            self.apply_main_bit1(level);
        }
        if let Some(level) = self.sub.bus_mut().take_vs_mainsub_edge() {
            self.apply_sub_bit1(level);
        }
        // Converge the shared-WRAM copies (both directions). The logs are
        // usually empty; a handful of entries during the boot handshake and
        // per-frame gameplay exchange. `comms_scratch` is drained (not
        // replaced) each round, so its allocated capacity — and the
        // mapper-side log's own capacity, via `drain_vs_dual_wram_writes`'s
        // `Vec::drain` — survives across calls: steady-state, this loop is
        // allocation-free.
        self.main
            .bus_mut()
            .drain_vs_dual_wram_writes(&mut self.comms_scratch);
        for (off, val) in self.comms_scratch.drain(..) {
            self.sub.bus_mut().apply_vs_dual_wram_write(off, val);
        }
        self.sub
            .bus_mut()
            .drain_vs_dual_wram_writes(&mut self.comms_scratch);
        for (off, val) in self.comms_scratch.drain(..) {
            self.main.bus_mut().apply_vs_dual_wram_write(off, val);
        }
    }

    /// Run one MAIN-console frame with the sub console soft-locksteped to
    /// within a 5-CPU-cycle gap (Mesen2 `RunFrame` + `RunVsSubConsole`).
    ///
    /// Returns when the main console's PPU completes a frame (or its CPU
    /// jams / the frame budget trips — mirroring `Nes::run_frame`'s
    /// guards).
    pub fn run_frame(&mut self) {
        /// Same stuck-frame guard as `Nes::run_frame`.
        const MAX_CYCLES_PER_FRAME: u64 = 150_000;
        let start_frame = self.main.frame();
        let start_cycle = self.main.cycle();
        while self.main.frame() == start_frame {
            if self.main.is_jammed() {
                break;
            }
            if self.main.cycle().wrapping_sub(start_cycle) > MAX_CYCLES_PER_FRAME {
                break;
            }
            self.main.step_instruction();
            self.pump_comms();
            // Drain the sub to within the 5-cycle gap (or its frame parity).
            // The comparison must be overshoot-safe: an instruction advances
            // 2..=8 cycles, so the sub routinely lands AHEAD of the main by
            // a few cycles — a naive `wrapping_sub(..) > 5` then wraps to a
            // huge unsigned value and runs the sub away forever.
            while !self.sub.is_jammed()
                && (self.main.cycle() > self.sub.cycle().saturating_add(5)
                    || self.main.frame() > self.sub.frame())
            {
                self.sub.step_instruction();
                self.pump_comms();
            }
        }
        // Consume both PPUs' frame-complete latches so external users of the
        // underlying `Nes` (none today) never observe a stale latch.
        let _ = self.main.bus_mut().take_frame_complete();
        let _ = self.sub.bus_mut().take_frame_complete();
        // v3.1.0 — push the completed frame into the cabinet's rewind ring.
        if self.rewind.is_some() && self.rewind_capture_enabled {
            self.rewind_capture();
        }
    }

    /// The main console's 256x240 RGBA8 framebuffer (the left screen).
    #[must_use]
    pub fn main_framebuffer(&self) -> &[u8] {
        self.main.framebuffer()
    }

    /// The sub console's 256x240 RGBA8 framebuffer (the right screen).
    #[must_use]
    pub fn sub_framebuffer(&self) -> &[u8] {
        self.sub.framebuffer()
    }

    /// Route controller input: ports 0/1 (P1/P2) → the main console's
    /// ports 0/1; ports 2/3 (P3/P4) → the sub console's ports 0/1.
    pub const fn set_buttons(&mut self, port: usize, buttons: crate::Buttons) {
        match port {
            0 | 1 => self.main.set_buttons(port, buttons),
            2 | 3 => self.sub.set_buttons(port - 2, buttons),
            _ => {}
        }
    }

    /// Coin routing (Mesen2 `VsControlManager`): acceptors 0/1 latch on the
    /// MAIN console, 2/3 on the SUB console.
    pub const fn insert_coin(&mut self, acceptor: u8) {
        match acceptor {
            0 | 1 => self.main.insert_coin(acceptor),
            2 | 3 => self.sub.insert_coin(acceptor - 2),
            _ => {}
        }
    }

    /// Clear both consoles' latched coin signals.
    pub const fn clear_coin(&mut self) {
        self.main.clear_coin();
        self.sub.clear_coin();
    }

    /// The service button (main panel) / service-2 (sub panel).
    pub const fn set_vs_service(&mut self, panel: u8, pressed: bool) {
        match panel {
            0 => self.main.set_vs_service(pressed),
            1 => self.sub.set_vs_service(pressed),
            _ => {}
        }
    }

    /// Borrow the main console (read-only diagnostics).
    #[must_use]
    pub const fn main(&self) -> &Nes {
        &self.main
    }

    /// Borrow the sub console (read-only diagnostics).
    #[must_use]
    pub const fn sub(&self) -> &Nes {
        &self.sub
    }

    /// Mutably borrow the main console (debugger / diagnostics — e.g. the
    /// side-effect-free `debug_peek_cpu`, which needs `&mut` for the
    /// mapper's banked lookups). Cross-wiring stays wrapper-owned; don't
    /// drive `$4016` writes through this handle.
    #[must_use]
    pub const fn main_mut(&mut self) -> &mut Nes {
        &mut self.main
    }

    /// Mutably borrow the sub console (debugger / diagnostics; see
    /// [`Self::main_mut`]).
    #[must_use]
    pub const fn sub_mut(&mut self) -> &mut Nes {
        &mut self.sub
    }

    /// Simultaneously borrow both consoles (diagnostics — e.g. a tracing
    /// harness replicating the lockstep loop with instrumented pumping).
    #[must_use]
    pub const fn split_mut(&mut self) -> (&mut Nes, &mut Nes) {
        (&mut self.main, &mut self.sub)
    }

    /// v2.9.8 — power-cycle the whole cabinet: both consoles cold-boot and
    /// the cabinet wiring is installed again, so the result is the cabinet
    /// [`Self::from_rom`] builds (with each console's settings and battery
    /// RAM kept, as [`Nes::power_cycle`] keeps them).
    ///
    /// Power-cycling the two consoles alone is NOT enough, and that is why
    /// this exists. [`Nes::power_cycle`] rebuilds each mapper from the ROM,
    /// which drops the wiring construction installed on it: the sub
    /// console's second-half PRG / upper-CHR banking (`set_vs_dual_sub`) and
    /// both consoles' shared 2 KiB WRAM window (`enable_vs_dual_wram`). The
    /// sub then runs the MAIN program, fails its `$4016` identity check, and
    /// the boot handshake never completes. The wrapper's latches (the two
    /// bit-1 levels, and through them each console's external `/IRQ`) are
    /// re-seeded to their reset values, and the scratch buffers emptied.
    pub fn power_cycle(&mut self) {
        self.main.power_cycle();
        self.sub.power_cycle();
        self.comms_scratch.clear();
        self.block_scratch.clear();
        self.wire();
        // The ring describes the timeline the power cycle just ended.
        self.rewind_clear();
    }

    /// Serialize the dual system: a versioned container nesting the two
    /// standard [`Nes`] snapshots plus the wrapper's latch state.
    ///
    /// Layout: `RVSD` magic, `u16` version, latch byte
    /// (`bit0 = main_bit1, bit1 = sub_bit1`; bit 2 reserved — it carried
    /// a WRAM-ownership flag in a pre-release layout and is ignored on
    /// load), then two `u32`-length-prefixed `Nes` snapshots (main, sub).
    #[must_use]
    pub fn snapshot(&self) -> Vec<u8> {
        let main = self.main.snapshot();
        let sub = self.sub.snapshot();
        let mut out = Vec::with_capacity(4 + 2 + 1 + 8 + main.len() + sub.len());
        out.extend_from_slice(&SNAPSHOT_MAGIC);
        out.extend_from_slice(&SNAPSHOT_VERSION.to_le_bytes());
        let latch = u8::from(self.main_bit1) | (u8::from(self.sub_bit1) << 1);
        out.push(latch);
        #[allow(clippy::cast_possible_truncation)]
        out.extend_from_slice(&(main.len() as u32).to_le_bytes());
        out.extend_from_slice(&main);
        #[allow(clippy::cast_possible_truncation)]
        out.extend_from_slice(&(sub.len() as u32).to_le_bytes());
        out.extend_from_slice(&sub);
        out
    }

    /// v2.9.1 (libretro re-audit NL-09) — [`Self::snapshot`] without the two
    /// consoles' `THM ` thumbnails, encoded into a caller-owned buffer that is
    /// reused across calls. The libretro core's `retro_serialize` path.
    ///
    /// Same container, same layout, and it restores through [`Self::restore`]
    /// like a full snapshot: each console block is a
    /// [`Nes::snapshot_core_into`] blob, and `THM ` is optional by format. What
    /// it drops is the work nobody on this path reads. [`Self::snapshot`]
    /// builds a 128x120 RGBA thumbnail per console (the desktop's slot picker
    /// shows one; `RetroArch` never does), then a fresh buffer per console and a
    /// third for the container, about 645 KB allocated on every call. v2.9.0
    /// measured that at 314-1,630 us per call against 46-78 us for this shape
    /// (`docs/performance.md`); the A/B that adopted it is recorded there.
    ///
    /// `&mut self` only for the pooled scratch buffer; nothing emulated
    /// changes.
    pub fn snapshot_into(&mut self, out: &mut Vec<u8>) {
        out.clear();
        out.extend_from_slice(&SNAPSHOT_MAGIC);
        out.extend_from_slice(&SNAPSHOT_VERSION.to_le_bytes());
        out.push(u8::from(self.main_bit1) | (u8::from(self.sub_bit1) << 1));
        let mut scratch = core::mem::take(&mut self.block_scratch);
        for console in [&self.main, &self.sub] {
            console.snapshot_core_into(&mut scratch);
            #[allow(clippy::cast_possible_truncation)] // a console snapshot is ~260 KB
            out.extend_from_slice(&(scratch.len() as u32).to_le_bytes());
            out.extend_from_slice(&scratch);
        }
        self.block_scratch = scratch;
    }

    /// Restore a dual-system snapshot produced by [`Self::snapshot`] or
    /// [`Self::snapshot_into`].
    ///
    /// # Errors
    ///
    /// Returns [`SnapshotError`] on a bad container or when either nested
    /// console snapshot fails to restore. Both consoles are then unchanged
    /// (since v2.9.0; before it a rejected sub block left main restored).
    ///
    /// A successful restore empties the cabinet's rewind ring (v3.1.0): the
    /// entries describe the timeline the restore replaced, as
    /// [`Nes::restore`] treats its own ring.
    pub fn restore(&mut self, data: &[u8]) -> Result<(), SnapshotError> {
        self.restore_inner(data, false)?;
        self.rewind_clear();
        Ok(())
    }

    /// v3.1.0 (`T-PS-dual-runahead`) — [`Self::restore`] without its
    /// side effects: the cabinet's rewind ring is kept, and each console is
    /// restored with [`Nes::restore_quiet`] (no timeline-generation bump, no
    /// rewind clear). For restores that return to the cabinet's own
    /// timeline rather than replace it: run-ahead's rollback and a rewind
    /// step. Same container, same all-or-nothing contract.
    ///
    /// # Errors
    ///
    /// As [`Self::restore`].
    pub fn restore_quiet(&mut self, data: &[u8]) -> Result<(), SnapshotError> {
        self.restore_inner(data, true)
    }

    fn restore_inner(&mut self, data: &[u8], quiet: bool) -> Result<(), SnapshotError> {
        // A malformed dual container reports as an unsupported format with
        // the container version we could read (0 when even the header is
        // short) — the closest fit among the existing error variants until
        // rc.1's save-state rework gives the dual container its own.
        let fail = |got: u16| SnapshotError::UnsupportedFormat {
            got,
            max: SNAPSHOT_VERSION,
        };
        if data.len() < 4 + 2 + 1 + 4 || data[0..4] != SNAPSHOT_MAGIC {
            return Err(fail(0));
        }
        let version = u16::from_le_bytes([data[4], data[5]]);
        if version != SNAPSHOT_VERSION {
            return Err(fail(version));
        }
        let latch = data[6];
        let mut cursor = 7usize;
        let read_block = |cursor: &mut usize| -> Result<&[u8], SnapshotError> {
            let len_end = cursor.checked_add(4).ok_or_else(|| fail(version))?;
            let len_bytes: [u8; 4] = data
                .get(*cursor..len_end)
                .ok_or_else(|| fail(version))?
                .try_into()
                .map_err(|_| fail(version))?;
            let len = u32::from_le_bytes(len_bytes) as usize;
            let end = len_end.checked_add(len).ok_or_else(|| fail(version))?;
            let block = data.get(len_end..end).ok_or_else(|| fail(version))?;
            *cursor = end;
            Ok(block)
        };
        let main_block = read_block(&mut cursor)?;
        let sub_block = read_block(&mut cursor)?;
        // v2.9.0 (re-audit NC-05 / NL-01b) — all-or-nothing across BOTH
        // consoles. Each `Nes::restore` is atomic on its own (a rejected block
        // leaves that console untouched), but the pair was not: a valid main
        // block followed by a rejected sub block left main on the file's
        // timeline and sub on the running one, a cabinet from two timelines
        // whose shared WRAM is re-converged only on the success path below.
        // So main is snapshotted before it is restored and put back if the sub
        // block fails. The rollback is `restore_quiet` because the timeline
        // generation was already bumped (and main's rewind ring cleared) by
        // the loud restore that succeeded; neither can be un-done, and neither
        // is emulated state. A console's own snapshot always restores (the
        // round-trip invariant the save-state tests pin), asserted in debug
        // builds as `Nes::restore` does for its own backup.
        //
        // v2.9.1 (NL-09): a pooled backup buffer here was measured and
        // REJECTED -- the restore A/B moved by exactly its order-bias control
        // in both runs (-12.2% vs -11.1%, -10.6% vs -10.9%), so the one
        // allocation per restore is not where the time goes. Two full console
        // restores are.
        let mut main_backup = Vec::new();
        self.main.snapshot_core_into(&mut main_backup);
        let restore = |nes: &mut Nes, block: &[u8]| {
            if quiet {
                nes.restore_quiet(block)
            } else {
                nes.restore(block)
            }
        };
        restore(&mut self.main, main_block)?;
        if let Err(e) = restore(&mut self.sub, sub_block) {
            let rolled_back = self.main.restore_quiet(&main_backup);
            debug_assert!(
                rolled_back.is_ok(),
                "rolling the main console back to its own snapshot failed: {rolled_back:?}"
            );
            return Err(e);
        }
        // Re-derive the wrapper latch + re-drive the cross-console signals
        // (the buses' transient comms fields are not serialized; the wrapper
        // owns the authoritative copies).
        self.main_bit1 = (latch & 0x01) != 0;
        self.sub_bit1 = (latch & 0x02) != 0;
        self.sub.bus_mut().set_vs_sub(true);
        self.sub.bus_mut().set_vs_external_irq(!self.main_bit1);
        self.main.bus_mut().set_vs_external_irq(!self.sub_bit1);
        // Re-converge the shared-WRAM copies from ONE buffer: the nested
        // snapshots each carry a copy (identical at snapshot time — the
        // write logs are always drained within `run_frame`), but a restore
        // into a fresh wrapper must not trust both blindly. The main's
        // copy is authoritative; it is cloned onto the sub.
        let wram = self
            .main
            .bus_mut()
            .take_vs_dual_wram()
            .or_else(|| self.sub.bus_mut().take_vs_dual_wram())
            .unwrap_or_else(|| alloc::vec![0u8; 0x0800].into_boxed_slice());
        self.sub.bus_mut().set_vs_dual_wram(wram.clone());
        self.main.bus_mut().set_vs_dual_wram(wram);
        Ok(())
    }

    /// v3.1.0 (`T-PS-dual-runahead`) — enable the cabinet's rewind ring with
    /// the default byte budget and keyframe period.
    pub fn enable_rewind(&mut self) {
        self.enable_rewind_with(REWIND_DEFAULT_MAX_BYTES, REWIND_DEFAULT_KEYFRAME_PERIOD);
    }

    /// Enable the cabinet's rewind ring with an explicit byte budget and
    /// keyframe period. Replaces (and so empties) any ring already enabled.
    pub fn enable_rewind_with(&mut self, max_bytes: usize, keyframe_period: u32) {
        self.rewind = Some(RewindRing::new(max_bytes, keyframe_period));
    }

    /// Disable the cabinet's rewind ring and free its memory.
    pub fn disable_rewind(&mut self) {
        self.rewind = None;
        self.rewind_snap_buf = Vec::new();
    }

    /// `true` if the cabinet's rewind ring is enabled.
    #[must_use]
    pub const fn rewind_enabled(&self) -> bool {
        self.rewind.is_some()
    }

    /// Number of buffered rewind entries (0 when rewind is disabled).
    #[must_use]
    pub fn rewind_len(&self) -> usize {
        self.rewind.as_ref().map_or(0, RewindRing::len)
    }

    /// Turn the per-frame rewind capture in [`Self::run_frame`] on or off.
    /// Run-ahead turns it off across its hidden and visible frames, which
    /// are not the cabinet's timeline.
    pub const fn set_rewind_capture(&mut self, enabled: bool) {
        self.rewind_capture_enabled = enabled;
    }

    /// `true` while [`Self::run_frame`] captures into the rewind ring.
    #[must_use]
    pub const fn rewind_capture_enabled(&self) -> bool {
        self.rewind_capture_enabled
    }

    /// Push the cabinet's current state into the rewind ring, keyed by the
    /// main console's frame. [`Self::run_frame`] calls this after every
    /// frame while capture is on; a no-op while rewind is disabled.
    ///
    /// Each entry is a whole `RVSD` container ([`Self::snapshot_into`]):
    /// both consoles, framebuffers included, and the bit-1 latch. Unlike the
    /// single console's ring, which stores SLIM entries and re-renders the
    /// picture after a step back, the cabinet keeps the framebuffers in the
    /// entry. That is what makes a step back exact for BOTH screens without
    /// running the cabinet forward and back: a re-render would run the
    /// five-cycle soft lockstep for a frame and restore again, twice the
    /// work of a single console. The cost is two 245,760-byte framebuffers
    /// per entry, which the ring's XOR delta and LZ4 reduce to the pixels
    /// that changed since the last keyframe.
    pub fn rewind_capture(&mut self) {
        if self.rewind.is_none() {
            return;
        }
        let frame = self.main.frame();
        let mut buf = core::mem::take(&mut self.rewind_snap_buf);
        self.snapshot_into(&mut buf);
        if let Some(ring) = &mut self.rewind {
            ring.push(frame, &buf);
        }
        self.rewind_snap_buf = buf;
    }

    /// Pop the most recent rewind entry and restore the cabinet to it, both
    /// framebuffers included. Returns `true` on success and `false` when
    /// the ring is empty, rewind is disabled, or the entry fails to decode
    /// or restore (the cabinet is then unchanged, per [`Self::restore`]'s
    /// all-or-nothing contract).
    ///
    /// The restore is quiet ([`Self::restore_quiet`]): the ring survives,
    /// since the user is mid-rewind.
    pub fn rewind_step_back(&mut self) -> bool {
        let Some(ring) = self.rewind.as_mut() else {
            return false;
        };
        let Some(Ok(bytes)) = ring.pop_back() else {
            return false;
        };
        self.restore_quiet(&bytes).is_ok()
    }

    /// Drop every buffered rewind entry (the ring stays enabled).
    pub fn rewind_clear(&mut self) {
        if let Some(ring) = &mut self.rewind {
            ring.clear();
        }
    }
}

/// The top-level emulator: one standard console, or a Vs. `DualSystem` pair.
///
/// v2.0.0 beta.5 — the API reshape scoped to the major (the plan's
/// Workstream C/D): a NEW `rustynes-core` consumer would construct via
/// [`Emu::from_rom`] and match on the variant; every existing single-console
/// surface lives unchanged on [`Nes`]. **`rustynes-frontend` does NOT yet
/// consume this type** — it still constructs `Nes` directly
/// (`Nes::from_rom`/`from_rom_with_sample_rate`), so the `DualSystem` path
/// is core-and-test-harness-only in this release; wiring the desktop/mobile
/// UI onto `Emu` (dual-console rendering + 4-port input routing) is
/// explicitly deferred, tracked as a beta.5 known gap (see the beta.5
/// CHANGELOG entry and `docs/audit/vs-dualsystem-combined-dumps-2026-07-02.md`
/// for the current disposition).
pub enum Emu {
    /// A standard single-console system (every cart except the four
    /// `DualSystem` boards).
    Single(Box<Nes>),
    /// A Vs. `DualSystem` cabinet (two consoles + the cross-wiring).
    Dual(Box<VsDualSystem>),
}

impl Emu {
    /// Construct the right emulator shape for the ROM: a
    /// [`VsDualSystem`] when the SHA-keyed `vs_db` flags the cart as a
    /// `DualSystem` board, else a standard [`Nes`].
    ///
    /// # Errors
    ///
    /// Returns the underlying [`RomError`] if the bytes don't parse.
    pub fn from_rom(bytes: &[u8]) -> Result<Self, RomError> {
        let nes = Nes::from_rom(bytes)?;
        // Two detection sources, OR'd: the NES 2.0 header (byte-13 high
        // nibble = Vs. hardware type 5/6) and the SHA-keyed `vs_db` record.
        // The db is load-bearing — the circulating DualSystem dumps are
        // iNES 1.0 (no byte 13), so the header alone can never flag them.
        let db_dual = crate::vs_db::lookup(&nes).is_some_and(|e| e.dual_system);
        if nes.is_vs_dual_system() || db_dual {
            // Reuse the probe as the MAIN console; parse once more for the SUB
            // (two parses total, not three). `from_pair` applies the cabinet
            // wiring to the pair.
            let sub = Nes::from_rom(bytes)?;
            Ok(Self::Dual(Box::new(VsDualSystem::from_pair(nes, sub))))
        } else {
            Ok(Self::Single(Box::new(nes)))
        }
    }

    /// Like [`Self::from_rom`], but bakes the frontend's audio sample rate into
    /// the console(s) — the desktop present path uses this so a `DualSystem`
    /// cabinet's main-console audio resamples to the cpal device rate.
    ///
    /// # Errors
    ///
    /// Returns the underlying [`RomError`] if the bytes don't parse.
    pub fn from_rom_with_sample_rate(bytes: &[u8], sample_rate: u32) -> Result<Self, RomError> {
        let nes = Nes::from_rom_with_sample_rate(bytes, sample_rate)?;
        let db_dual = crate::vs_db::lookup(&nes).is_some_and(|e| e.dual_system);
        if nes.is_vs_dual_system() || db_dual {
            // Reuse the probe as MAIN; parse once more for SUB (two parses, not
            // three).
            let sub = Nes::from_rom_with_sample_rate(bytes, sample_rate)?;
            Ok(Self::Dual(Box::new(VsDualSystem::from_pair(nes, sub))))
        } else {
            Ok(Self::Single(Box::new(nes)))
        }
    }
}