rustynes_core/

nes.rs

//! `Nes` facade — the public entry point that owns the entire emulator.
//!
//! Per `docs/architecture.md` §Public API surface. Mirrors the surface
//! that `rustynes-frontend` and `rustynes-test-harness` will consume.

use alloc::vec::Vec;
use alloc::{format, vec};
use rustynes_cpu::Cpu;
use rustynes_mappers::RomError;
use rustynes_ppu::{PaletteInit, PpuRevision};
use sha2::{Digest, Sha256};

// `core::time::Duration` is identical to `std::time::Duration` (same Duration
// type, re-exported through std for convenience). Using the `core` path keeps
// the public API surface portable to `#![no_std]` consumers without changing
// any caller. See `docs/architecture.md` §149 (no_std + alloc migration).
use core::time::Duration;

use crate::Cpu2A03Revision;
use crate::Region;
use crate::bus::SystemBus;
use crate::controller::Buttons;
use crate::debug::{ApuDebugView, CpuDebugView, MapperDebugView, PpuDebugView};
use crate::genie::{GenieCode, GenieError};
use crate::input_device::InputDevice;
use crate::rewind::{REWIND_DEFAULT_KEYFRAME_PERIOD, REWIND_DEFAULT_MAX_BYTES, RewindRing};
use crate::save_state::{self, ROM_HASH_TAG_LEN, SnapshotError};

/// Nominal NTSC frame duration: `1 / 60.0988 Hz ≈ 16.6393 ms`.
///
/// Real hardware alternates 29780-cycle and 29781-cycle frames (the half
/// cycle averages to 60.0988 Hz); for wall-clock pacing we treat the
/// average as a single fixed-point interval and let small slips snap.
pub const FRAME_DURATION_NTSC: Duration = Duration::from_nanos(16_639_267);

/// Nominal PAL frame duration: `1 / 50.0070 Hz ≈ 19.9972 ms`.
pub const FRAME_DURATION_PAL: Duration = Duration::from_nanos(19_997_200);

/// Nominal Dendy frame duration: 50 Hz Russian famiclone, same as PAL.
pub const FRAME_DURATION_DENDY: Duration = Duration::from_nanos(19_997_200);

/// v2.1.7 P5 — power-on 2 KiB CPU work-RAM contents.
///
/// Real NES hardware powers up with unreliable RAM (nesdev "CPU power up
/// state"); a few titles read uninitialized RAM before writing it (*Final
/// Fantasy*'s RNG seed, *River City Ransom*, *Cybernoid*). This selects what
/// pattern the work RAM (and the open-bus latch) is filled with at power-on.
///
/// **Default-off / deterministic.** [`Default`] ([`Self::Zeroed`]) is the
/// established all-zero fill CI, the regression oracle, and save-state tests
/// use; the other variants are opt-in and still fully **deterministic** (no
/// wall-clock / OS RNG), so the `same config + ROM + input ⇒ bit-identical`
/// contract holds.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash, Default)]
pub enum PowerOnRam {
    /// Default. Work RAM + open bus power up all-zero (current behavior).
    #[default]
    Zeroed,
    /// Deterministic `xorshift64` randomization keyed on the seed (the existing
    /// developer mode; see [`Nes::from_rom_with_power_on_seed`]). Surfaces
    /// software that depends on a particular post-power-on RAM pattern.
    Seeded(u64),
    /// Fill every work-RAM byte (and the open-bus latch) with a single uniform
    /// byte — a documented known pattern (e.g. `0xFF`, the all-ones some
    /// consoles come up with). Deterministic.
    Filled(u8),
}

/// v2.1.7 P5 — power-on hardware configuration for a freshly-constructed or
/// power-cycled machine.
///
/// A small, forward-extensible bundle of the "what state does the silicon come
/// up in" knobs that are otherwise scattered. Currently just the work-RAM fill
/// ([`PowerOnRam`]); the PPU-revision and power-up-palette knobs are exposed as
/// their own setters on [`Nes`] since they live in the PPU. All fields default
/// to the established behavior, so [`PowerOnConfig::default`] is byte-identical.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash, Default)]
pub struct PowerOnConfig {
    /// Work-RAM power-on fill. Defaults to [`PowerOnRam::Zeroed`].
    pub ram: PowerOnRam,
}

/// v2.9.8 — which console wires the PPU's `/RESET` line.
///
/// The 2C02 is the same chip in every NTSC console; what differs is the board
/// around it. The `NESdev` "PPU power up state" page (§Famicom, and its closing
/// note on front- and top-loaders) documents two wirings:
///
/// - **NES (front-loader, NES-001)** — the CPU and PPU are reset together. At
///   power-on and on every press of Reset the PPU spends about 29,658 CPU
///   cycles (NTSC) in its warm-up state, ignoring writes to `$2000`, `$2001`,
///   `$2005` and `$2006`, and Reset clears PPUCTRL, PPUMASK, the scroll/address
///   latch and the read buffer.
/// - **Famicom** — the PPU's `/RESET` is tied to 5 V and only the CPU's rides
///   a 0.47 µF capacitor. At power-on the PPU therefore starts initialising
///   roughly one frame before the CPU leaves reset, which is longer than the
///   warm-up window, so the CPU's first instructions can already write the
///   masked registers. The Reset button reaches only the CPU: the PPU keeps
///   running and keeps its register state.
///
/// What this models, and what it does not:
///
/// - Power-on under [`Self::Famicom`] closes the warm-up window before the
///   first instruction ([`rustynes_ppu::Ppu::end_warmup`]). `NESdev` gives the
///   lead as "approximately one frame ... the exact timing has not been
///   measured, and may vary", so the PPU's frame position is left where the NES
///   model puts it rather than advanced by a guessed amount.
/// - A warm reset under [`Self::Famicom`] leaves the PPU untouched. The APU,
///   DMA unit and cartridge reset exactly as under [`Self::Nes`].
/// - The NES-101 top-loader shares the Famicom's reset wiring, but `NESdev` does
///   not document its power-on lead, so it is not offered as a separate model.
///
/// **Off by default.** [`Self::Nes`] is the model every release before v2.9.8
/// emulated, so the default build is byte-identical. The selection is a
/// host/config knob, never derived from the ROM: NES 2.0 has no console type
/// that distinguishes a Famicom from an NES, and the project does not guess a
/// console from a per-game list. It is not part of the save-state (the warm-up
/// counter it acts on already is), and like the other hardware knobs on [`Nes`]
/// it is re-applied by the host after a load or power-cycle.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash, Default)]
pub enum ConsoleModel {
    /// Default. Front-loading NES: the CPU and PPU share the reset line.
    #[default]
    Nes,
    /// Famicom: the PPU is never held in reset, so it leaves its warm-up before
    /// the CPU starts and ignores the Reset button.
    Famicom,
}

/// v1.1.0 beta.2 (Workstream C, T-110-C2) — one cycle-trace record.
///
/// The CPU register file + cycle count captured just before an instruction
/// executes. Recorded by [`Nes::run_frame`] while tracing is enabled (the
/// `debug-hooks` feature). The frontend disassembles the instruction at `pc`.
#[cfg(feature = "debug-hooks")]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TraceRec {
    /// Program counter at instruction fetch.
    pub pc: u16,
    /// Accumulator.
    pub a: u8,
    /// X index.
    pub x: u8,
    /// Y index.
    pub y: u8,
    /// Stack pointer.
    pub s: u8,
    /// Processor status bits.
    pub p: u8,
    /// CPU cycle count at fetch.
    pub cycle: u64,
}

/// The largest extra-scanline overclock the core accepts.
///
/// [`Nes::set_extra_scanlines`] clamps to it, and a movie's options record
/// above it is refused. 80 lines is the range the desktop's Settings field
/// has offered since v2.9.7; the value moved here at v2.9.9 (NC-11) so every
/// host and every file format meets the same bound.
pub const MAX_EXTRA_SCANLINES: u16 = 80;

/// The largest CPU-multiplier overclock the core accepts (v3.1.0,
/// `T-CPU-OVERCLOCK`).
///
/// [`Nes::set_cpu_overclock`] clamps to `1..=MAX_CPU_OVERCLOCK`, and a movie's
/// options record outside that range is refused. The bound is the master
/// clock: the CPU divider must stay at least 3 for the read / write split of
/// a cycle (NTSC 12 / 4 = 3), and `x4` is already four times the CPU time a
/// frame has.
pub const MAX_CPU_OVERCLOCK: u8 = 4;

/// Top-level NES emulator handle.
///
/// Owns the CPU, PPU, mapper, RAM, and controller stub. Construct via
/// [`Nes::from_rom`]; drive forward via [`Nes::run_frame`] or
/// [`Nes::step_instruction`]. The framebuffer can be sampled at any time via
/// [`Nes::framebuffer`].
// Several independent debug-hooks toggles (breakpoints / trace / exec log) push
// the bool count over clippy's threshold; they are genuinely independent flags.
#[allow(clippy::struct_excessive_bools)]
pub struct Nes {
    cpu: Cpu,
    bus: SystemBus,
    /// The ROM's persistent identity: SHA-256 of an iNES / NES 2.0 image's
    /// bytes AFTER its 16-byte header (trainer, PRG, CHR, anything trailing),
    /// or of the whole image for anything without the `NES\x1A` magic (FDS
    /// disks, NSF files). See [`Nes::rom_sha256`] for why the header is left
    /// out.
    rom_sha256: [u8; 32],
    /// SHA-256 of the complete image as constructed, header included. Only the
    /// Vs. System database consults it, as the fallback to its identity key
    /// ([`Nes::image_sha256`]).
    image_sha256: [u8; 32],
    /// Optional rewind ring buffer. Disabled by default — frontend opts in
    /// via [`Nes::enable_rewind`].
    rewind: Option<RewindRing>,
    /// v2.8.0 Phase 3 — when `false`, [`Nes::run_frame`] skips the rewind
    /// capture even with the ring armed. Run-ahead sets this for its
    /// hidden + visible frames so only the persistent timeline's frames
    /// land in the ring. Default `true` (byte-identical legacy behavior).
    rewind_capture_enabled: bool,
    /// v2.8.0 Phase 3 — reused scratch for the per-frame rewind capture
    /// (kills the ~320 KiB snapshot allocation per frame).
    rewind_snap_buf: Vec<u8>,
    /// v2.9.0 (re-audit NC-03) — reused scratch for the rollback backup every
    /// restore takes before it mutates anything (see `restore_inner`). Pooled
    /// because the quiet path runs once per frame under run-ahead.
    restore_backup: Vec<u8>,
    /// Optional per-CPU-instruction boot trace (Session-12 observability).
    /// Gated on the `cpu-boot-trace` cargo feature so the default build
    /// pays no memory or codegen cost. See
    /// `crates/rustynes-core/src/cpu_boot_trace.rs`.
    #[cfg(feature = "cpu-boot-trace")]
    cpu_boot_trace: Option<crate::cpu_boot_trace::CpuBootTrace>,
    /// v1.1.0 beta.2 (Workstream C) — exec/PC breakpoints checked in
    /// [`Nes::run_frame`]. Gated on `debug-hooks` so the default build's hot
    /// path is untouched. Output-only: a hit stops the frame early and records
    /// the PC; it never mutates emulation, so determinism holds.
    #[cfg(feature = "debug-hooks")]
    breakpoints: Vec<u16>,
    /// Whether breakpoints are armed (lets the UI keep its list but pause
    /// checking). Default `true`.
    #[cfg(feature = "debug-hooks")]
    breakpoints_enabled: bool,
    /// The PC that last hit a breakpoint, taken by the frontend to pause.
    #[cfg(feature = "debug-hooks")]
    break_hit: Option<u16>,
    /// The PC to skip the breakpoint check on for the next step, so a
    /// "continue" resumes *past* the instruction it stopped on instead of
    /// re-breaking. Unlike a blind "skip the first iteration", this only skips
    /// the exact resumed PC — so a breakpoint sitting at the frame's start PC
    /// (after a reset / save-state load / manual PC change) still fires.
    #[cfg(feature = "debug-hooks")]
    skip_breakpoint_at: Option<u16>,
    /// v1.1.0 beta.2 (T-110-C2) — cycle-trace ring buffer (most-recent
    /// [`Self::TRACE_CAP`] instructions). Recorded in `run_frame` while
    /// `trace_enabled`. Output-only.
    #[cfg(feature = "debug-hooks")]
    trace: alloc::collections::VecDeque<TraceRec>,
    /// Whether the cycle-trace logger is recording. Default `false`.
    #[cfg(feature = "debug-hooks")]
    trace_enabled: bool,
    /// v1.1.0 beta.3 (T-110-E2) — per-frame executed-PC log for the Lua
    /// `onExec` callback. Distinct from [`Self::trace`] (a 50k rolling buffer
    /// shared with the Trace Logger panel): this is **cleared every frame**, so
    /// `onExec` replays only this frame's PCs — no stale / duplicate dispatch.
    /// Output-only; recorded only while `exec_logging`.
    #[cfg(feature = "debug-hooks")]
    exec_log: Vec<u16>,
    /// Whether the per-frame exec-PC log is recording. Default `false`.
    #[cfg(feature = "debug-hooks")]
    exec_logging: bool,
    /// v2.4.0 item B — a monotonic marker that changes whenever this `Nes`
    /// jumps to a different point on its timeline.
    ///
    /// **Session-local, and deliberately NOT serialized.** The counter's only job
    /// is to be *different* after a discontinuity. Serializing it would put an
    /// OLD value back on restore, so loading a state saved earlier in the same
    /// session could hand a consumer a generation it has already seen — and the
    /// consumer would conclude nothing jumped at the exact moment something did.
    /// A session-local monotonic counter cannot do that: it only ever increases,
    /// so any restore produces a value no consumer has seen.
    ///
    /// It exists because the alternative — each consumer remembering the last
    /// `cycle()` it saw and noticing a non-monotonic step — cannot see a restore
    /// to a LATER state. The counter can, and needs no cooperation from any call
    /// site, which matters because two of the four timeline jumps (wasm
    /// load-state, and rewind) are not reachable from a patchable frontend call
    /// site at all.
    ///
    /// # It is NOT part of the save state, deliberately
    ///
    /// The counter is session-local: it is not written by `snapshot`, not read by
    /// `restore`, and a loaded state does not carry its own value across. What a
    /// restore does instead is **increment the live counter**, which is the
    /// correct reading of the event — "the timeline you were on has been replaced"
    /// — and is true regardless of which state was loaded.
    ///
    /// Serializing it would be actively wrong in two ways. Loading the same slot
    /// twice would restore the same generation twice, so a consumer comparing
    /// against its last-seen value would miss the second load entirely. And a
    /// value from another session says nothing about this one: the counter is only
    /// ever meaningful as a comparison against the previous value *this process*
    /// observed, which is why `timeline_generation()` documents that comparing it
    /// across two `Nes` instances is meaningless.
    ///
    /// A consequence worth stating: because it lives outside the snapshot, the
    /// `snapshot_schema_audit` test cannot see it, so nothing mechanical will
    /// notice if this reasoning is ever invalidated.
    timeline_generation: u64,
}

impl Nes {
    /// The current timeline generation — see the field's documentation.
    ///
    /// A consumer holds the last value it saw and clears itself when this
    /// differs. It is meaningless to compare across two different `Nes`
    /// instances: a fresh one starts at zero, which is why ROM changes are
    /// handled by their own hook (`DebuggerOverlay::clear_rom_bound_analysis`)
    /// rather than by this counter.
    #[must_use]
    pub const fn timeline_generation(&self) -> u64 {
        self.timeline_generation
    }

    /// Returns a reference to the internal WRAM.
    pub fn wram(&self) -> &[u8] {
        self.bus.ram.as_ref()
    }

    /// Returns a mutable reference to the internal WRAM.
    pub fn wram_mut(&mut self) -> &mut [u8] {
        self.bus.ram.as_mut()
    }

    /// Returns a reference to the cartridge SRAM (if any).
    pub fn sram(&self) -> &[u8] {
        self.bus.mapper.sram()
    }

    /// Returns a mutable reference to the cartridge SRAM (if any).
    pub fn sram_mut(&mut self) -> &mut [u8] {
        self.bus.mapper.sram_mut()
    }

    /// v2.9.6 — the cartridge's non-volatile data, what a battery save
    /// persists: [`Self::sram`] on almost every board, and the flash image on
    /// a self-flashable one (GTROM, a flashable UNROM 512), which has no RAM
    /// at `$6000`. Hosts that persist saves read and restore THIS, gated on
    /// [`Self::has_battery`]. `sram()` stays the `$6000` RAM that memory maps
    /// describe. See `Mapper::save_data`.
    pub fn save_data(&self) -> &[u8] {
        self.bus.mapper.save_data()
    }

    /// Mutable [`Self::save_data`], for loading a save.
    pub fn save_data_mut(&mut self) -> &mut [u8] {
        self.bus.mapper.save_data_mut()
    }

    /// v2.9.6 — return the save data to a never-saved cartridge: zeroed RAM,
    /// or the flash image as loaded.
    pub fn clear_save_data(&mut self) {
        self.bus.mapper.clear_save_data();
    }

    /// v2.7.3 — whether the cartridge has non-volatile save data: the header
    /// declares battery-backed PRG-RAM (iNES flags 6 bit 1), or (v2.9.6) the
    /// board is self-flashable and its flash is the save (GTROM, mapper 111,
    /// and flashable UNROM 512, mapper 30, whose headers need not set the
    /// bit). Persist [`Self::save_data`] when this is `true`.
    ///
    /// [`Self::sram`] is not the same question: several boards expose their
    /// work RAM through it whatever the header says (NROM returns its 8 KiB
    /// PRG-RAM for every image, and MMC1 and MMC3 allocate RAM by default). A
    /// host that persists save RAM to disk — the desktop frontend's `.sav`
    /// files — must gate on this, or a volatile cartridge acquires a save it
    /// never had and restores stale RAM across power cycles. Always `false`
    /// for an FDS disk (which has its own writable-disk save) and an NSF.
    #[must_use]
    pub const fn has_battery(&self) -> bool {
        self.bus.cart.has_battery
    }

    /// Returns a reference to the internal VRAM (nametables).
    pub fn vram(&self) -> &[u8] {
        self.bus.ppu.vram_ref()
    }

    /// Returns a mutable reference to the internal VRAM (nametables).
    pub fn vram_mut(&mut self) -> &mut [u8] {
        self.bus.ppu.vram_mut()
    }

    /// Build a new emulator from raw ROM bytes (iNES 1.0 or NES 2.0).
    ///
    /// # Errors
    ///
    /// Returns the underlying [`RomError`] if the bytes don't parse.
    pub fn from_rom(bytes: &[u8]) -> Result<Self, RomError> {
        let mut bus = SystemBus::new(bytes)?;
        // Cold-boot path: `Cpu::power_on()` seeds `S=$00`; the subsequent
        // `reset()`'s `S -= 3` (wrapping) lands at `$FD`, matching Mesen2's
        // power-up state. See `docs/audit/session-13-cpu-boot-fix-2026-05-21.md`.
        let mut cpu = Cpu::power_on();
        cpu.reset(&mut bus);
        Ok(Self {
            cpu,
            bus,
            rom_sha256: rom_identity_sha256(bytes),
            image_sha256: sha256_of(bytes),
            rewind: None,
            rewind_capture_enabled: true,
            rewind_snap_buf: Vec::new(),
            restore_backup: Vec::new(),
            #[cfg(feature = "cpu-boot-trace")]
            cpu_boot_trace: None,
            #[cfg(feature = "debug-hooks")]
            breakpoints: Vec::new(),
            #[cfg(feature = "debug-hooks")]
            breakpoints_enabled: true,
            #[cfg(feature = "debug-hooks")]
            break_hit: None,
            #[cfg(feature = "debug-hooks")]
            skip_breakpoint_at: None,
            #[cfg(feature = "debug-hooks")]
            trace: alloc::collections::VecDeque::new(),
            #[cfg(feature = "debug-hooks")]
            trace_enabled: false,
            #[cfg(feature = "debug-hooks")]
            exec_log: Vec::new(),
            #[cfg(feature = "debug-hooks")]
            exec_logging: false,
            timeline_generation: 0,
        })
    }

    /// Build an emulator with an explicit audio sample rate (the rate the
    /// CPAL stream is opened at).
    ///
    /// # 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 mut bus = SystemBus::with_sample_rate(bytes, sample_rate)?;
        // Cold-boot path: see comment in `from_rom`.
        let mut cpu = Cpu::power_on();
        cpu.reset(&mut bus);
        Ok(Self {
            cpu,
            bus,
            rom_sha256: rom_identity_sha256(bytes),
            image_sha256: sha256_of(bytes),
            rewind: None,
            rewind_capture_enabled: true,
            rewind_snap_buf: Vec::new(),
            restore_backup: Vec::new(),
            #[cfg(feature = "cpu-boot-trace")]
            cpu_boot_trace: None,
            #[cfg(feature = "debug-hooks")]
            breakpoints: Vec::new(),
            #[cfg(feature = "debug-hooks")]
            breakpoints_enabled: true,
            #[cfg(feature = "debug-hooks")]
            break_hit: None,
            #[cfg(feature = "debug-hooks")]
            skip_breakpoint_at: None,
            #[cfg(feature = "debug-hooks")]
            trace: alloc::collections::VecDeque::new(),
            #[cfg(feature = "debug-hooks")]
            trace_enabled: false,
            #[cfg(feature = "debug-hooks")]
            exec_log: Vec::new(),
            #[cfg(feature = "debug-hooks")]
            exec_logging: false,
            timeline_generation: 0,
        })
    }

    /// Build an emulator from a Famicom Disk System `.fds` disk image and a
    /// user-supplied 8 KiB BIOS (`disksys.rom`).
    ///
    /// The BIOS is never committed to this repo (it is Nintendo IP); the caller
    /// supplies it (a frontend BIOS prompt is Stage 2). Construction parses the
    /// disk container, builds the FDS device as the bus's mapper, and runs the
    /// standard cold-boot reset (the BIOS reset vector at `$FFFC` drives the
    /// disk-load sequence).
    ///
    /// Uses the default 44.1 kHz audio sample rate; use
    /// [`Nes::from_disk_with_sample_rate`] to pick the rate.
    ///
    /// # Errors
    ///
    /// Returns the underlying [`RomError`] if the disk image is unparseable or
    /// the BIOS is not exactly 8 KiB.
    pub fn from_disk(disk_bytes: &[u8], bios_bytes: &[u8]) -> Result<Self, RomError> {
        Self::from_disk_with_sample_rate(disk_bytes, bios_bytes, crate::bus::DEFAULT_SAMPLE_RATE)
    }

    /// Build an FDS emulator with an explicit audio sample rate. See
    /// [`Nes::from_disk`].
    ///
    /// The reported `rom_sha256` hashes the disk-image bytes (not the BIOS), so
    /// save-states / movies key off the disk the way cartridge builds key off
    /// the ROM. A host booting a SAVED (game-written) copy of the disk passes
    /// the pristine image's hash to [`Nes::set_rom_identity`] afterwards, so
    /// the identity does not move with the game's disk saves (v2.9.9, NF-17).
    ///
    /// # Errors
    ///
    /// Returns the underlying [`RomError`] if the disk image is unparseable or
    /// the BIOS is not exactly 8 KiB.
    pub fn from_disk_with_sample_rate(
        disk_bytes: &[u8],
        bios_bytes: &[u8],
        sample_rate: u32,
    ) -> Result<Self, RomError> {
        let mut bus = SystemBus::with_disk(disk_bytes, bios_bytes, sample_rate)?;
        // Cold-boot path: see comment in `from_rom`.
        let mut cpu = Cpu::power_on();
        cpu.reset(&mut bus);
        Ok(Self {
            cpu,
            bus,
            rom_sha256: sha256_of(disk_bytes),
            image_sha256: sha256_of(disk_bytes),
            rewind: None,
            rewind_capture_enabled: true,
            rewind_snap_buf: Vec::new(),
            restore_backup: Vec::new(),
            #[cfg(feature = "cpu-boot-trace")]
            cpu_boot_trace: None,
            #[cfg(feature = "debug-hooks")]
            breakpoints: Vec::new(),
            #[cfg(feature = "debug-hooks")]
            breakpoints_enabled: true,
            #[cfg(feature = "debug-hooks")]
            break_hit: None,
            #[cfg(feature = "debug-hooks")]
            skip_breakpoint_at: None,
            #[cfg(feature = "debug-hooks")]
            trace: alloc::collections::VecDeque::new(),
            #[cfg(feature = "debug-hooks")]
            trace_enabled: false,
            #[cfg(feature = "debug-hooks")]
            exec_log: Vec::new(),
            #[cfg(feature = "debug-hooks")]
            exec_logging: false,
            timeline_generation: 0,
        })
    }

    /// Build an emulator that plays an NSF-family music file: the classic
    /// `NESM\x1a` container or the chunked `NSFE` one, told apart by their magic
    /// in [`rustynes_mappers::parse_nsf`]. Expansion-chip audio declared in the
    /// header (VRC6, VRC7, FDS, MMC5, N163, 5B) is synthesized by the same cores
    /// the cartridge boards use. (Until v2.9.3 this comment said `NSFe` and
    /// expansion audio were deferred, which stopped being true in v2.1.x.)
    ///
    /// NSF files carry a ripped NES sound engine plus an `init`/`play` address
    /// pair, not a PPU program. Construction parses the file, installs a
    /// [`rustynes_mappers::NsfMapper`] (a synthetic 6502 driver + the program
    /// image) as the bus's mapper, and runs the standard cold-boot reset — the
    /// driver's reset vector calls `init` for the starting song. At the standard
    /// 60 Hz rate the driver enables vblank NMI and the NMI calls `play` once per
    /// frame; at any other header rate a mapper cycle-timer IRQ calls it
    /// instead (see `docs/mappers.md`). Audio is produced through the unchanged
    /// lockstep loop; there is no video.
    ///
    /// Uses the default 44.1 kHz sample rate; see
    /// [`Nes::from_nsf_with_sample_rate`].
    ///
    /// # Errors
    ///
    /// Returns the underlying [`RomError`] when the NSF header is malformed.
    pub fn from_nsf(nsf_bytes: &[u8]) -> Result<Self, RomError> {
        Self::from_nsf_with_sample_rate(nsf_bytes, crate::bus::DEFAULT_SAMPLE_RATE)
    }

    /// Build an NSF player with an explicit audio sample rate. See
    /// [`Nes::from_nsf`].
    ///
    /// # Errors
    ///
    /// Returns the underlying [`RomError`] when the NSF header is malformed.
    pub fn from_nsf_with_sample_rate(nsf_bytes: &[u8], sample_rate: u32) -> Result<Self, RomError> {
        let mut bus = SystemBus::with_nsf(nsf_bytes, sample_rate)?;
        let mut cpu = Cpu::power_on();
        cpu.reset(&mut bus);
        Ok(Self {
            cpu,
            bus,
            rom_sha256: sha256_of(nsf_bytes),
            image_sha256: sha256_of(nsf_bytes),
            rewind: None,
            rewind_capture_enabled: true,
            rewind_snap_buf: Vec::new(),
            restore_backup: Vec::new(),
            #[cfg(feature = "cpu-boot-trace")]
            cpu_boot_trace: None,
            #[cfg(feature = "debug-hooks")]
            breakpoints: Vec::new(),
            #[cfg(feature = "debug-hooks")]
            breakpoints_enabled: true,
            #[cfg(feature = "debug-hooks")]
            break_hit: None,
            #[cfg(feature = "debug-hooks")]
            skip_breakpoint_at: None,
            #[cfg(feature = "debug-hooks")]
            trace: alloc::collections::VecDeque::new(),
            #[cfg(feature = "debug-hooks")]
            trace_enabled: false,
            #[cfg(feature = "debug-hooks")]
            exec_log: Vec::new(),
            #[cfg(feature = "debug-hooks")]
            exec_logging: false,
            timeline_generation: 0,
        })
    }

    /// Number of selectable songs in the loaded NSF (0 for a cartridge / disk).
    #[must_use]
    pub fn nsf_song_count(&self) -> u8 {
        self.bus.nsf_song_count()
    }

    /// The currently-selected 0-based NSF song (0 for a cartridge / disk).
    #[must_use]
    pub fn nsf_current_song(&self) -> u8 {
        self.bus.nsf_current_song()
    }

    /// Select a 0-based NSF song and restart playback on it (re-runs `init` via
    /// a warm reset). No-op for a cartridge / disk.
    pub fn nsf_set_song(&mut self, song: u8) {
        if self.bus.nsf_set_song(song) {
            // Re-vector through the driver's reset entry so `init` runs for the
            // new track. Warm reset preserves the freshly-patched driver state.
            self.reset();
        }
    }

    /// Build an emulator with a **randomized power-on RAM** state (developer
    /// mode; Phase 7 / T-72-005).
    ///
    /// Identical to [`Nes::from_rom`] except the 2 KiB CPU work RAM and the
    /// open-bus latch are filled from a deterministic `xorshift64` PRNG keyed
    /// on `seed`, modelling the unreliable power-on RAM of real hardware
    /// (nesdev "CPU power up state"). Use this to shake out game/test code
    /// that depends on a particular post-power-on RAM pattern.
    ///
    /// The randomization is **seeded and deterministic** — the same `seed`
    /// yields the same state, so the `same seed + ROM + input ⇒ bit-identical`
    /// contract still holds. The default [`Nes::from_rom`] (zeroed RAM) is
    /// what CI, the regression oracle, and save-state tests use.
    ///
    /// # Errors
    ///
    /// Returns the underlying [`RomError`] if the bytes don't parse.
    pub fn from_rom_with_power_on_seed(bytes: &[u8], seed: u64) -> Result<Self, RomError> {
        Self::from_rom_with_power_on_config(
            bytes,
            PowerOnConfig {
                ram: PowerOnRam::Seeded(seed),
            },
        )
    }

    /// v2.1.7 P5 — build an emulator with an explicit [`PowerOnConfig`].
    ///
    /// Generalizes [`Nes::from_rom_with_power_on_seed`]: the caller chooses the
    /// power-on work-RAM fill ([`PowerOnRam::Zeroed`] / [`PowerOnRam::Seeded`] /
    /// [`PowerOnRam::Filled`]). The config is stored on the bus so a subsequent
    /// power-cycle re-applies the same fill (keeping `power_cycle == fresh
    /// boot`). All fills are **deterministic**, so the `same config + ROM + input
    /// ⇒ bit-identical` contract still holds. [`PowerOnConfig::default`]
    /// ([`PowerOnRam::Zeroed`]) is byte-identical to [`Nes::from_rom`].
    ///
    /// # Errors
    ///
    /// Returns the underlying [`RomError`] if the bytes don't parse.
    pub fn from_rom_with_power_on_config(
        bytes: &[u8],
        config: PowerOnConfig,
    ) -> Result<Self, RomError> {
        let mut nes = Self::from_rom(bytes)?;
        // RAM is not consulted during the reset sequence (only the $FFFC/D
        // vector is), so applying the fill after construction is correct.
        nes.bus.set_power_on_ram(config.ram);
        Ok(nes)
    }

    /// Reset (warm boot). Preserves WRAM; reloads PC from `$FFFC/D`.
    pub fn reset(&mut self) {
        // v2.4.0 item B — a warm reset lands somewhere else on the timeline, so a
        // reconstructed call stack and the access counters describe a run that no
        // longer exists.
        self.timeline_generation = self.timeline_generation.wrapping_add(1);
        self.bus.reset();
        self.cpu.reset(&mut self.bus);
    }

    /// Power-cycle (cold boot). Zeroes WRAM, re-rolls phase, reloads vectors.
    ///
    /// A cold boot of the CONSOLE, not of its configuration. The PPU and the
    /// APU are rebuilt to their power-on state, and since v2.9.8 every host
    /// setting stored on them survives: the custom or generated palette
    /// ([`Self::set_custom_palette`]), the overclock scanlines
    /// ([`Self::set_extra_scanlines`]), the fast dot path
    /// ([`Self::set_fast_dotloop`]), the OAM-decay model
    /// ([`Self::set_oam_decay`]), the APU channel mask, per-channel gain and
    /// filter model, and the armed state of the provenance stores (emptied
    /// below). The settings stored on the bus survived already: the die
    /// revisions, the console model, the Vs. DIP switches and PPU type, the
    /// mirroring override and the Four Score. The power-on FILLS
    /// ([`Self::set_power_on_ram`], [`Self::set_power_up_palette`]) are
    /// re-applied, as a fresh boot applies them. What a cold boot does clear
    /// is console state: RAM, registers, the mapper (battery RAM excepted),
    /// the controllers' latches, and any non-standard input device, which the
    /// host re-attaches. Until v2.9.8 the PPU and APU settings reverted to
    /// their defaults, and each host had to re-push them.
    pub fn power_cycle(&mut self) {
        // v2.4.0 item B — see `reset`; a cold boot is the larger discontinuity.
        self.timeline_generation = self.timeline_generation.wrapping_add(1);
        self.bus.power_cycle();
        // Cold-boot path: see comment in `from_rom`.
        self.cpu = Cpu::power_on();
        self.cpu.reset(&mut self.bus);
        // v2.3.2 "Lucid" — a cold boot ends the history both provenance stores
        // describe. Keep them armed (the user asked for them) but empty.
        #[cfg(feature = "debug-hooks")]
        {
            self.bus.ppu.clear_write_attribution();
            self.bus.ppu.clear_pixel_provenance();
            // v2.3.7 — same for audio: a cold boot ends the history the
            // register attribution describes.
            self.bus.apu.clear_audio_provenance_history();
        }
    }

    /// Run until the PPU finishes a frame. Returns the framebuffer slice.
    ///
    /// A CPU JAM ends the call early, as the 150,000-cycle budget does: the
    /// returned framebuffer is whatever the PPU had drawn, and later calls
    /// return at once until a reset. It does not panic (until v2.9.9 this
    /// section said it did; NC-15). Check [`Self::cpu`]'s `is_jammed` to tell
    /// a JAM from a completed frame.
    pub fn run_frame(&mut self) -> &[u8] {
        // Hard cap: at NTSC the frame budget is 29,780.5 CPU cycles. Run
        // up to 5x that before bailing — gives breathing room for late
        // VBL detection or DMA-stall heavy frames before declaring "stuck".
        //
        // v3.1.0: scaled by the CPU overclock, which puts up to
        // MAX_CPU_OVERCLOCK times as many CPU cycles into one frame.
        const MAX_CYCLES_PER_FRAME: u64 = 150_000;
        let max_cycles = MAX_CYCLES_PER_FRAME * u64::from(self.bus.cpu_overclock());
        let start = self.bus.cycle();
        // v2.3.7 "Overtone" — anchor this frame's mix trace. The trace is
        // per-frame (the index IS the cycle offset from here); the REGISTER
        // attribution deliberately is not, because "which instruction last wrote
        // $4003" has an answer that legitimately predates this frame.
        #[cfg(feature = "debug-hooks")]
        self.bus.apu.begin_audio_provenance_frame(start);
        // T-110-C3 — the event viewer shows one frame; reset the log per frame.
        #[cfg(feature = "debug-hooks")]
        if self.bus.event_logging() {
            self.bus.clear_events();
        }
        // T-110-E2 — the Lua onRead/onWrite access log is per-frame too.
        #[cfg(feature = "debug-hooks")]
        if self.bus.access_logging() {
            self.bus.clear_accesses();
        }
        // T-110-E1 — the Lua onNmi/onIrq interrupt-service log is per-frame too
        // (cleared here so a replay only ever sees this frame's services, never
        // a stale carry-over — mirrors the exec_log clear below).
        #[cfg(feature = "debug-hooks")]
        if self.bus.interrupt_logging() {
            self.bus.clear_interrupts();
        }
        // v1.6.0 Workstream A3 — reset the `TAStudio` lag-log "controller polled"
        // flag so was_input_polled_this_frame() reflects only this frame (a
        // frame that ends still-`false` is a lag frame). Output-only.
        #[cfg(feature = "debug-hooks")]
        self.bus.clear_controller_polled();
        // v1.4.0 Workstream D (D2) — start each frame with no event-breakpoint
        // hit so the frontend's "first hit of the frame" pause is per-frame.
        #[cfg(feature = "debug-hooks")]
        if self.bus.event_breakpoints() != 0 {
            self.bus.clear_event_break_hit();
        }
        // T-110-E2 — the Lua onExec exec-PC log is per-frame (cleared here so a
        // replay only ever sees this frame's PCs, never a stale carry-over).
        #[cfg(feature = "debug-hooks")]
        if self.exec_logging {
            self.exec_log.clear();
        }
        while !self.bus.take_frame_complete() {
            if self.cpu.is_jammed() {
                break;
            }
            if self.bus.cycle().wrapping_sub(start) > max_cycles {
                break;
            }
            #[cfg(feature = "debug-hooks")]
            {
                // v1.1.0 beta.2 (Workstream C) — exec/PC breakpoints. The
                // `skip_breakpoint_at` PC is stepped past exactly once (so a
                // "continue" resumes off the instruction it stopped on instead
                // of re-breaking in place); any OTHER breakpoint PC — including
                // one at the frame's starting PC after a reset / save-state load
                // / manual PC change — still fires immediately.
                if self.breakpoints_enabled && self.breakpoints.contains(&self.cpu.pc) {
                    if self.skip_breakpoint_at == Some(self.cpu.pc) {
                        self.skip_breakpoint_at = None;
                    } else {
                        // Hit: stop the (partial) frame and report the PC. No
                        // state mutated; the frame simply isn't completed.
                        self.break_hit = Some(self.cpu.pc);
                        self.skip_breakpoint_at = Some(self.cpu.pc);
                        return self.bus.framebuffer();
                    }
                } else {
                    self.skip_breakpoint_at = None;
                }
                // T-110-E2 — per-frame exec-PC log for Lua onExec (bounded by
                // MAX_CYCLES_PER_FRAME, so no explicit cap needed).
                if self.exec_logging {
                    self.exec_log.push(self.cpu.pc);
                }
                // v2.3.2 "Lucid" — push this instruction's `(pc, cycle)` down to
                // the PPU so any CIRAM / OAM / palette byte it goes on to write
                // is stamped with the instruction that caused it. Done here, in
                // the existing per-instruction debug block, rather than through a
                // new `CpuBus` hook: `run_frame` already holds both halves, so
                // this costs two stores and leaves `rustynes-cpu` untouched.
                //
                // Unconditional rather than gated on the store being armed: the
                // "is it armed?" question lives behind a `Box` on the other side
                // of a crate boundary, so testing it would cost about as much as
                // the two stores it would skip, in a block that already runs a
                // breakpoint scan per instruction.
                self.bus
                    .ppu
                    .set_attrib_context(self.cpu.pc, self.cpu.cycles);
                // v2.3.7 "Overtone" — the same push-down for audio, so
                // `Apu::write_register` can attribute a `$4000-$4017` write
                // without `rustynes-cpu` knowing the feature exists. Same
                // reasoning as the PPU line above: two unconditional stores are
                // cheaper than testing an arm behind a `Box` across a crate
                // boundary, in a block that already scans breakpoints.
                self.bus
                    .apu
                    .set_attrib_context(self.cpu.pc, self.cpu.cycles);
                // T-110-C2 — cycle trace: record the about-to-execute
                // instruction's CPU state (ring-capped, oldest dropped).
                if self.trace_enabled {
                    if self.trace.len() >= Self::TRACE_CAP {
                        self.trace.pop_front();
                    }
                    self.trace.push_back(TraceRec {
                        pc: self.cpu.pc,
                        a: self.cpu.a,
                        x: self.cpu.x,
                        y: self.cpu.y,
                        s: self.cpu.s,
                        p: self.cpu.p.bits(),
                        cycle: self.cpu.cycles,
                    });
                }
            }
            #[cfg(feature = "cpu-boot-trace")]
            self.cpu_boot_trace_record();
            self.cpu.step(&mut self.bus);
        }
        // Sample any attached Zapper's light detection from the completed
        // frame. This is a no-op (and the run loop above is byte-identical)
        // when no Zapper is attached, so the determinism contract holds.
        self.bus.sample_zapper_light();
        // After the frame completes, push state into the rewind ring so
        // the frontend's hold-F5 UX has somewhere to walk back from.
        // v2.8.0 Phase 3 — run-ahead suppresses the capture for its hidden
        // + visible frames via `set_rewind_capture(false)`.
        if self.rewind.is_some() && self.rewind_capture_enabled {
            self.rewind_capture();
        }
        self.bus.framebuffer()
    }

    /// v2.8.0 Phase 3 — enable/disable the per-frame rewind capture while
    /// the ring stays armed. Run-ahead turns it off around its hidden +
    /// visible frames so only persistent-timeline frames land in the ring.
    /// Default `true`; with no rewind ring armed this is a no-op.
    pub const fn set_rewind_capture(&mut self, enabled: bool) {
        self.rewind_capture_enabled = enabled;
    }

    /// Whether the per-frame rewind capture is currently armed.
    ///
    /// Added in v2.3.6 so a caller that needs to suppress capture temporarily can
    /// save and restore the *caller's* setting rather than assume the default.
    /// `rustynes-probe` does exactly that around a trial: its replayed frames
    /// never happened on the user's timeline, so they must not enter the ring —
    /// but nor may re-enabling capture afterwards turn it on for someone who had
    /// deliberately turned it off. Run-ahead predates this and still restores an
    /// unconditional `true`, which is correct only because nothing else disables
    /// capture today.
    #[must_use]
    pub const fn rewind_capture_enabled(&self) -> bool {
        self.rewind_capture_enabled
    }

    /// Step exactly one CPU instruction. For debuggers / step-through tools.
    pub fn step_instruction(&mut self) -> u8 {
        #[cfg(feature = "cpu-boot-trace")]
        self.cpu_boot_trace_record();
        // v2.3.2 "Lucid" — mirror `run_frame`'s write-attribution context push,
        // so single-stepping through a `$2007` store in the debugger attributes
        // the byte to the stepped instruction and not to whatever `run_frame`
        // last left latched.
        #[cfg(feature = "debug-hooks")]
        self.bus
            .ppu
            .set_attrib_context(self.cpu.pc, self.cpu.cycles);
        #[cfg(feature = "debug-hooks")]
        self.bus
            .apu
            .set_attrib_context(self.cpu.pc, self.cpu.cycles);
        self.cpu.step(&mut self.bus)
    }

    /// v1.1.0 beta.2 (Workstream C) — add an exec/PC breakpoint at `addr`.
    /// [`Nes::run_frame`] stops the frame the next time the program counter
    /// reaches `addr` (reportable via [`Nes::take_break_hit`]). Idempotent.
    /// `debug-hooks` only.
    #[cfg(feature = "debug-hooks")]
    pub fn add_breakpoint(&mut self, addr: u16) {
        if !self.breakpoints.contains(&addr) {
            self.breakpoints.push(addr);
        }
    }

    /// Remove a previously-added exec breakpoint (no-op if absent).
    #[cfg(feature = "debug-hooks")]
    pub fn remove_breakpoint(&mut self, addr: u16) {
        self.breakpoints.retain(|&a| a != addr);
    }

    /// Remove all breakpoints.
    #[cfg(feature = "debug-hooks")]
    pub fn clear_breakpoints(&mut self) {
        self.breakpoints.clear();
    }

    /// The current exec breakpoints (insertion order).
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    // `Vec` -> slice deref coercion is not const, so this can't be `const fn`
    // (clippy's `missing_const_for_fn` is a false positive here).
    #[allow(clippy::missing_const_for_fn)]
    pub fn breakpoints(&self) -> &[u16] {
        &self.breakpoints
    }

    /// Arm/disarm breakpoint checking without discarding the list. Default on.
    #[cfg(feature = "debug-hooks")]
    pub const fn set_breakpoints_enabled(&mut self, enabled: bool) {
        self.breakpoints_enabled = enabled;
    }

    /// Whether breakpoint checking is armed.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub const fn breakpoints_enabled(&self) -> bool {
        self.breakpoints_enabled
    }

    /// Take the PC that last hit a breakpoint (cleared on read). The frontend
    /// polls this after [`Nes::run_frame`] to pause when a breakpoint fired.
    #[cfg(feature = "debug-hooks")]
    pub const fn take_break_hit(&mut self) -> Option<u16> {
        self.break_hit.take()
    }

    /// v1.4.0 Workstream D (D2) — arm the event-driven breakpoint categories
    /// (a bit-OR of [`crate::EventBpKind::bit`]). `0` (default) disarms every
    /// category — the per-access taps are then a single cheap `mask == 0`
    /// early-out. Output-only: a hit pauses + reports but never mutates state.
    /// `debug-hooks` only.
    #[cfg(feature = "debug-hooks")]
    pub const fn set_event_breakpoints(&mut self, mask: u16) {
        self.bus.set_event_breakpoints(mask);
    }

    /// The armed event-breakpoint category mask.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub const fn event_breakpoints(&self) -> u16 {
        self.bus.event_breakpoints()
    }

    /// Take the first event-breakpoint hit of the current frame (cleared on
    /// read). The frontend polls this after [`Nes::run_frame`] to pause when an
    /// armed hardware event fired, reporting its kind + frame/cycle/scanline/dot.
    #[cfg(feature = "debug-hooks")]
    pub const fn take_event_break_hit(&mut self) -> Option<crate::EventBreakHit> {
        self.bus.take_event_break_hit()
    }

    /// Maximum cycle-trace ring depth (oldest records drop past this).
    #[cfg(feature = "debug-hooks")]
    pub const TRACE_CAP: usize = 50_000;

    /// v1.1.0 beta.2 (T-110-C2) — start/stop the cycle-trace logger. While on,
    /// each executed instruction's CPU state is pushed to a ring buffer (capped
    /// at [`Self::TRACE_CAP`]). Default off.
    #[cfg(feature = "debug-hooks")]
    pub const fn set_trace_enabled(&mut self, enabled: bool) {
        self.trace_enabled = enabled;
    }

    /// Whether the cycle-trace logger is recording.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub const fn trace_enabled(&self) -> bool {
        self.trace_enabled
    }

    /// Number of records currently in the trace ring.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub fn trace_len(&self) -> usize {
        self.trace.len()
    }

    /// Clear the trace ring.
    #[cfg(feature = "debug-hooks")]
    pub fn clear_trace(&mut self) {
        self.trace.clear();
    }

    /// Copy the trace ring oldest-first (for the trace panel / file export).
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub fn trace_records(&self) -> alloc::vec::Vec<TraceRec> {
        self.trace.iter().copied().collect()
    }

    /// Copy the most recent `n` trace records (oldest-first) — for the live
    /// trace panel's tail view, cheaper than [`Self::trace_records`] on a full
    /// ring.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub fn trace_tail_vec(&self, n: usize) -> alloc::vec::Vec<TraceRec> {
        let skip = self.trace.len().saturating_sub(n);
        self.trace.iter().skip(skip).copied().collect()
    }

    /// v1.1.0 beta.2 (T-110-C3) — start/stop the event viewer. While on, the bus
    /// records this frame's PPU/APU/mapper writes (with their PPU position); the
    /// log is reset at each [`Self::run_frame`]. Default off; output-only.
    #[cfg(feature = "debug-hooks")]
    pub const fn set_event_logging(&mut self, enabled: bool) {
        self.bus.set_event_logging(enabled);
    }

    /// Whether the event viewer is recording.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub const fn event_logging(&self) -> bool {
        self.bus.event_logging()
    }

    /// The current frame's captured events (for the event-viewer panel).
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    #[allow(clippy::missing_const_for_fn)] // slice deref is not const.
    pub fn events(&self) -> &[crate::bus::EventRec] {
        self.bus.events()
    }

    /// v2.3.2 "Lucid" — arm or disarm per-byte **write attribution** for the
    /// PPU's own memories (CIRAM, OAM, palette RAM).
    ///
    /// While armed, every write to those memories is stamped with the program
    /// counter and CPU cycle of the instruction that performed it, which is the
    /// edge the pixel-provenance panel walks to answer "which instruction put
    /// this byte here?". The Event Viewer records the CPU-side `$2000-$3FFF`
    /// write and the memory-access counter records a cycle stamp, but neither
    /// carries the PC *and* the resolved destination — see
    /// [`rustynes_ppu::provenance`] for why the two halves are recorded on
    /// opposite sides of the bus.
    ///
    /// Default off. Arming allocates
    /// [`rustynes_ppu::WriteAttribution::HEAP_BYTES`]; disarming frees it.
    /// Output-only, so emulation is bit-identical either way.
    #[cfg(feature = "debug-hooks")]
    pub fn set_write_attribution(&mut self, enabled: bool) {
        self.bus.ppu.set_write_attribution(enabled);
    }

    /// The write-attribution store, or `None` when not armed.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub fn write_attribution(&self) -> Option<&rustynes_ppu::WriteAttribution> {
        self.bus.ppu.write_attribution()
    }

    /// Forget the current frame's per-pixel provenance, keeping it armed.
    ///
    /// Called automatically on power-cycle and on both restore paths; exposed so
    /// a host that rewinds by other means can do the same.
    #[cfg(feature = "debug-hooks")]
    pub fn clear_pixel_provenance(&mut self) {
        self.bus.ppu.clear_pixel_provenance();
    }

    /// Forget every recorded write attribution, keeping the store armed.
    ///
    /// Call this after a save-state restore or a power-cycle: the restored bytes
    /// were not written by any instruction this session executed, and reporting
    /// the PCs that wrote those offsets before the restore would be a
    /// confidently wrong answer rather than an absent one.
    #[cfg(feature = "debug-hooks")]
    pub fn clear_write_attribution(&mut self) {
        self.bus.ppu.clear_write_attribution();
    }

    /// v2.3.2 "Lucid" phase 2 — arm or disarm **per-pixel provenance**.
    ///
    /// While armed, every emitted pixel records the layer that won the priority
    /// decision, the exact `$3Fxx` palette address behind its color, and the
    /// nametable / attribute / pattern addresses of the tile **actually on
    /// screen** — which `v` cannot answer, because by display time it has
    /// advanced two tiles past the pixel.
    ///
    /// Composes with [`Self::set_write_attribution`]: provenance says which
    /// bytes produced a pixel, attribution says which instruction wrote them.
    /// Each is useful alone; together they are the full causal chain.
    ///
    /// Default off. Arming allocates
    /// [`rustynes_ppu::PixelProvenanceFrame::HEAP_BYTES`]. Output-only, so
    /// emulation is bit-identical either way.
    #[cfg(feature = "debug-hooks")]
    pub fn set_pixel_provenance(&mut self, enabled: bool) {
        self.bus.ppu.set_pixel_provenance(enabled);
    }

    /// The current frame's per-pixel provenance, or `None` when not armed.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub fn pixel_provenance(&self) -> Option<&rustynes_ppu::PixelProvenanceFrame> {
        self.bus.ppu.pixel_provenance()
    }

    /// Arm or disarm **audio** provenance (v2.3.7 "Overtone").
    ///
    /// Off by default. Arming allocates the per-register write attribution and
    /// the per-CPU-cycle mix trace; disarming frees both. Output-only — nothing
    /// recorded is read back into synthesis or carried in the save state, so the
    /// deterministic audio contract is unaffected either way.
    #[cfg(feature = "debug-hooks")]
    pub fn set_audio_provenance(&mut self, enabled: bool) {
        self.bus.apu.set_audio_provenance(enabled);
    }

    /// Whether audio provenance is armed.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub const fn audio_provenance_armed(&self) -> bool {
        self.bus.apu.audio_provenance_armed()
    }

    /// The per-register write attribution — which instruction last wrote each of
    /// `$4000-$4017` — or `None` when disarmed.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub fn register_attribution(&self) -> Option<&rustynes_apu::provenance::RegisterAttribution> {
        self.bus.apu.register_attribution()
    }

    /// This frame's per-CPU-cycle mix trace, or `None` when disarmed.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub fn mix_trace(&self) -> Option<&rustynes_apu::provenance::MixTrace> {
        self.bus.apu.mix_trace()
    }

    /// Lift the audio provenance stores out for a same-timeline restore.
    ///
    /// The audio counterpart of [`Self::take_provenance`], and it exists for the
    /// identical reason: run-ahead's rollback runs AFTER the visible frame is
    /// produced and BEFORE the frontend releases the emulator lock, so a store
    /// the restore clears can never be observed by the UI. That is exactly how
    /// Pixel Provenance shipped non-functional from v2.3.2 to v2.3.6. Take
    /// before the restore, [`Self::put_audio_provenance`] after.
    ///
    /// Save-state loads and netplay rollback still clear, unchanged — those are
    /// genuine timeline changes. Run-ahead's rollback is not.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub fn take_audio_provenance(&mut self) -> rustynes_apu::provenance::AudioProvenanceStash {
        self.bus.apu.take_audio_provenance()
    }

    /// Put back stores taken by [`Self::take_audio_provenance`].
    #[cfg(feature = "debug-hooks")]
    pub fn put_audio_provenance(&mut self, stash: rustynes_apu::provenance::AudioProvenanceStash) {
        self.bus.apu.put_audio_provenance(stash);
    }

    /// v2.3.6 — move both provenance stores out, leaving them unarmed.
    ///
    /// For a host that performs a **same-timeline** restore whose result the user
    /// is about to inspect. [`Self::restore`] and [`Self::restore_quiet`] both
    /// clear the stores, which is correct when the restore replaces the timeline
    /// the records describe — and wrong for run-ahead, whose rollback is the last
    /// thing before the UI reads, so the clear discards the record for the frame
    /// actually on screen. Take before the restore, [`Self::put_provenance`]
    /// after.
    ///
    /// A move, not a copy: the stores are boxed, so this is two pointer moves.
    /// See [`rustynes_ppu::ProvenanceStash`].
    #[cfg(feature = "debug-hooks")]
    pub const fn take_provenance(&mut self) -> rustynes_ppu::ProvenanceStash {
        self.bus.ppu.take_provenance()
    }

    /// Put back stores taken by [`Self::take_provenance`].
    #[cfg(feature = "debug-hooks")]
    pub fn put_provenance(&mut self, stash: rustynes_ppu::ProvenanceStash) {
        self.bus.ppu.put_provenance(stash);
    }

    /// Resolve a PPU-space nametable address (`$2000-$3EFF`) to the physical
    /// internal-CIRAM offset it reads, applying the mapper's mirroring and any
    /// per-game mirroring override.
    ///
    /// This is what turns a [`rustynes_ppu::PixelProvenance::nt_addr`] into the
    /// key [`rustynes_ppu::WriteAttribution::ciram`] is indexed by, so the
    /// provenance panel can go from "this pixel's tile came from `$2002`" to
    /// "and instruction X wrote that byte" without reimplementing mirroring.
    ///
    /// Returns `None` for an address outside the nametable window.
    ///
    /// # Boards with mapper-supplied nametable memory
    ///
    /// On `MMC5` (`ExRAM` nametables) and 4-screen boards, some nametable writes are
    /// absorbed by the mapper via `PpuBus::write_nametable` and never reach
    /// internal CIRAM. This function still returns the CIRAM offset the standard
    /// mirroring would select, because the only way to know whether the mapper
    /// absorbed a particular write is to *perform* one — `write_nametable` takes
    /// `&mut self` and has side effects, and a read-only query has no business
    /// inventing one. Callers should treat a missing attribution on such a board
    /// as "the mapper owns this byte", which is what it means.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub fn ciram_offset_for_nametable_addr(&self, addr: u16) -> Option<usize> {
        let a = addr & 0x3FFF;
        if !(0x2000..0x3F00).contains(&a) {
            return None;
        }
        let nt_addr = if a >= 0x3000 { a - 0x1000 } else { a };
        Some((self.bus.resolve_nametable_address(nt_addr) as usize) & 0x07FF)
    }

    /// v1.1.0 beta.3 (T-110-E2) — start/stop the Lua bus-access log. While on,
    /// the bus records this frame's CPU reads + writes (with values); the log is
    /// reset at each [`Self::run_frame`]. Default off; output-only. Enabled by
    /// the scripting engine only while `onRead`/`onWrite` callbacks exist.
    #[cfg(feature = "debug-hooks")]
    pub const fn set_access_logging(&mut self, enabled: bool) {
        self.bus.set_access_logging(enabled);
    }

    /// Whether the bus-access log is recording.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub const fn access_logging(&self) -> bool {
        self.bus.access_logging()
    }

    /// The current frame's captured CPU bus accesses (for the Lua engine).
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    #[allow(clippy::missing_const_for_fn)] // slice deref is not const.
    pub fn accesses(&self) -> &[crate::bus::AccessRec] {
        self.bus.accesses()
    }

    /// v1.1.0 beta.3 (T-110-E2) — start/stop the per-frame exec-PC log for the
    /// Lua `onExec` callback. Independent of the Trace Logger (`set_trace_enabled`),
    /// so enabling it does not disturb the debugger's trace recording. Cleared
    /// every [`Self::run_frame`]; output-only.
    #[cfg(feature = "debug-hooks")]
    pub const fn set_exec_logging(&mut self, enabled: bool) {
        self.exec_logging = enabled;
    }

    /// Whether the per-frame exec-PC log is recording.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub const fn exec_logging(&self) -> bool {
        self.exec_logging
    }

    /// This frame's executed PCs, in execution order (for the Lua engine).
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    #[allow(clippy::missing_const_for_fn)] // slice deref is not const.
    pub fn exec_log(&self) -> &[u16] {
        &self.exec_log
    }

    /// `true` if the running program read a controller port (`$4016`/`$4017`)
    /// during the most recent [`Self::run_frame`] — the inverse of a `TAStudio`
    /// "lag frame" (v1.6.0 Workstream A3). The greenzone / piano-roll lag log
    /// queries this each frame. Output-only; `debug-hooks`-gated, so the
    /// shipped build is byte-identical and the determinism contract holds.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub const fn was_input_polled_this_frame(&self) -> bool {
        self.bus.controller_polled()
    }

    /// v1.2.0 (T-110-E1) — start/stop the per-frame interrupt-service log for
    /// the Lua `onNmi` / `onIrq` callbacks. The log records this frame's
    /// committed NMI / IRQ / BRK service entries (captured at the CPU's
    /// service-vector commit point, NOT the speculative poll sampler); it is
    /// cleared at each [`Self::run_frame`]. Default off; output-only. Enabled by
    /// the scripting engine only while `onNmi`/`onIrq` callbacks exist. Mirrors
    /// [`Self::set_exec_logging`].
    #[cfg(feature = "debug-hooks")]
    pub const fn set_interrupt_logging(&mut self, enabled: bool) {
        self.bus.set_interrupt_logging(enabled);
    }

    /// Whether the per-frame interrupt-service log is recording.
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    pub const fn interrupt_logging(&self) -> bool {
        self.bus.interrupt_logging()
    }

    /// This frame's committed interrupt-service entries, in service order (for
    /// the Lua engine). Mirrors [`Self::exec_log`] / [`Self::accesses`].
    #[cfg(feature = "debug-hooks")]
    #[must_use]
    #[allow(clippy::missing_const_for_fn)] // slice deref is not const.
    pub fn interrupt_log(&self) -> &[crate::bus::InterruptRec] {
        self.bus.interrupts()
    }

    /// Borrow the framebuffer (RGBA8, 256x240).
    #[must_use]
    pub fn framebuffer(&self) -> &[u8] {
        self.bus.framebuffer()
    }

    /// v1.7.0 "Forge" Workstream B (B3) — overwrite the RGBA8 output framebuffer
    /// (the Lua `emu:setScreenBuffer(t)` paints output only). Output-only; see
    /// [`rustynes_ppu::Ppu::debug_set_framebuffer`]. Reached only through the
    /// script crate's gated post-frame path, so the shipped build is
    /// byte-identical and the determinism contract holds. `debug-hooks`-gated.
    #[cfg(feature = "debug-hooks")]
    pub fn debug_set_framebuffer(&mut self, rgba: &[u8]) {
        self.bus.debug_set_framebuffer(rgba);
    }

    /// Borrow the parallel palette-index framebuffer (256x240 `u16`s, each
    /// `(emphasis << 6) | colour`) for the `NES_NTSC` composite filter.
    /// See [`rustynes_ppu::Ppu::index_framebuffer`].
    #[must_use]
    pub fn index_framebuffer(&self) -> &[u16] {
        self.bus.index_framebuffer()
    }

    /// v1.2.0 C3 (hd-pack) — borrow the per-pixel HD-pack tile-source buffer
    /// (256x240 [`rustynes_ppu::HdTileSource`] records). Each entry names the
    /// CHR tile that produced the pixel; the frontend HD-pack loader groups
    /// these by 8x8 cell, hashes the CHR bytes, and substitutes hi-res tiles.
    /// Output-only telemetry; the determinism contract is unaffected. See
    /// [`rustynes_ppu::Ppu::hd_tile_source`].
    #[cfg(feature = "hd-pack")]
    #[must_use]
    pub fn hd_tile_source(&self) -> &[rustynes_ppu::HdTileSource] {
        self.bus.hd_tile_source()
    }

    /// The frame's background scroll `(x, y)` in NES pixels, for offsetting
    /// parallax HD-pack `<background>` layers (see
    /// [`rustynes_ppu::Ppu::hd_bg_scroll`]). Output-only.
    #[cfg(feature = "hd-pack")]
    #[must_use]
    pub const fn hd_bg_scroll(&self) -> (i32, i32) {
        self.bus.ppu().hd_bg_scroll()
    }

    /// The per-frame NTSC composite colour phase consumed by the `NES_NTSC`
    /// filter (`0..=2` on NTSC; frame parity `0..=1` on PAL/Dendy). See
    /// [`rustynes_ppu::Ppu::ntsc_phase`].
    #[must_use]
    pub const fn ntsc_phase(&self) -> u8 {
        self.bus.ntsc_phase()
    }

    /// The completed-frame counter (PPU frames since power-on). A monotonic,
    /// deterministic, save-state-restored value — the frontend uses it to phase
    /// turbo/autofire so the strobe is reproducible under rollback / TAS replay.
    #[must_use]
    pub const fn frame(&self) -> u64 {
        self.bus.ppu().frame()
    }

    /// Borrow the underlying bus (debugger / tests).
    #[must_use]
    pub const fn bus(&self) -> &SystemBus {
        &self.bus
    }

    /// Mutably borrow the underlying bus (debugger / tests).
    pub const fn bus_mut(&mut self) -> &mut SystemBus {
        &mut self.bus
    }

    /// Assert or release the external /NMI pin. **Co-simulation only.**
    ///
    /// v2.5.1, [ADR 0038]. Rung 2's interrupt sweep needs the same stimulus on
    /// both sides, and this emulator had no way to receive it: its /NMI comes
    /// from the PPU and its /IRQ from the APU frame counter or a mapper, none of
    /// which exist at the CPU rung of the co-simulation.
    ///
    /// `true` asserts the pin. It is OR'd into the CPU's existing poll and
    /// consumed on the edge exactly as a PPU-generated NMI is, so the CPU cannot
    /// tell the two apart -- which is the property that makes the sweep test the
    /// CPU rather than the injection. It does **not** bypass the poll, force a
    /// vector, or short-circuit the sequence.
    ///
    /// Gated behind `cosim-interrupt-inject`, which nothing in the workspace
    /// enables. A default build does not contain this method or its state.
    ///
    /// [ADR 0038]: https://github.com/doublegate/RustyNES/blob/main/docs/adr/0038-cosim-interrupt-injection-api.md
    #[cfg(feature = "cosim-interrupt-inject")]
    pub const fn inject_nmi(&mut self, asserted: bool) {
        self.bus.set_inject_nmi(asserted);
    }

    /// Assert or release the external /IRQ pin. **Co-simulation only.**
    ///
    /// Level-sensitive, as the pin is: it is masked by `I` through the CPU's own
    /// logic, and a pulse shorter than a poll is missed. Holding it asserted
    /// across several cycles is how a real device drives it. See
    /// [`Self::inject_nmi`] for the contract and the ADR.
    #[cfg(feature = "cosim-interrupt-inject")]
    pub const fn inject_irq(&mut self, asserted: bool) {
        self.bus.set_inject_irq(asserted);
    }

    /// Borrow the CPU (debugger / tests).
    #[must_use]
    pub const fn cpu(&self) -> &Cpu {
        &self.cpu
    }

    /// Cumulative CPU cycle count.
    #[must_use]
    pub const fn cycle(&self) -> u64 {
        self.bus.cycle()
    }

    /// `true` when the CPU has executed a JAM/KIL/STP and is halted.
    ///
    /// (v2.0.0 beta.5: the `VsDualSystem` soft-lockstep driver guards its
    /// per-instruction stepping — the pre-existing debugger
    /// [`Self::step_instruction`] — on this.)
    #[must_use]
    pub const fn is_jammed(&self) -> bool {
        self.cpu.is_jammed()
    }

    /// Cartridge region (NTSC / PAL / Dendy / Multi). Drives wall-clock
    /// frame pacing in the frontend and clock dividers in the chip cores.
    #[must_use]
    pub const fn region(&self) -> Region {
        match self.bus.region() {
            rustynes_mappers::Region::Pal => Region::Pal,
            rustynes_mappers::Region::Dendy => Region::Dendy,
            // iNES 1.0 "Multi" cartridges are treated as NTSC for pacing
            // (matches the PPU / APU init in `SystemBus::with_sample_rate`).
            _ => Region::Ntsc,
        }
    }

    /// Length in bytes of the loaded cartridge's PRG-ROM (read-only metadata).
    ///
    /// Exposed for the Lua scripting `cart:prg_size()` query (and any other
    /// read-only consumer); does not touch deterministic state.
    #[must_use]
    pub const fn prg_rom_len(&self) -> usize {
        self.bus.prg_rom_len()
    }

    /// Length in bytes of the loaded cartridge's CHR-ROM (0 when the board uses
    /// CHR-RAM). Read-only metadata; backs the Lua `cart:chr_size()` query.
    #[must_use]
    pub const fn chr_rom_len(&self) -> usize {
        self.bus.chr_rom_len()
    }

    /// The loaded cartridge's iNES / NES 2.0 mapper id, after any load-time
    /// header correction (backs the Lua `cart:mapper_id()`, the ROM-info
    /// panel and the mobile `RomInfo`). A Famicom Disk System image reports
    /// 20 and an NSF 31, the ids their synthetic cartridges carry.
    ///
    /// v2.9.8 — read from the cartridge. It used to read the mapper's debug
    /// view, whose default `debug_info` names mapper 0, so every board
    /// without its own override (`UxROM`, CNROM, `AxROM`, ...) reported 0, and
    /// an NSF reported 0 rather than 31.
    #[must_use]
    pub const fn mapper_id(&self) -> u16 {
        self.bus.cart.mapper_id
    }

    /// v2.9.8 — the loaded cartridge's NES 2.0 submapper (0 for an iNES 1.0
    /// image, which has none), after any load-time header correction.
    #[must_use]
    pub const fn submapper(&self) -> u8 {
        self.bus.cart.submapper
    }

    /// Wall-clock frame duration for this cartridge's region. The frontend
    /// uses this to pace emulator advance independently of monitor refresh
    /// rate — without it, `Fifo` present mode on a 144 Hz monitor would
    /// run the emulator 2.4× too fast.
    #[must_use]
    pub const fn frame_duration(&self) -> Duration {
        match self.region() {
            Region::Pal => FRAME_DURATION_PAL,
            Region::Dendy => FRAME_DURATION_DENDY,
            Region::Ntsc => FRAME_DURATION_NTSC,
        }
    }

    /// Drain accumulated audio samples at the host sample rate. Call once per
    /// frame from the frontend's audio thread or batch driver.
    ///
    /// The samples are **bipolar and DC-blocked**, not the mixer's raw
    /// `[0.0, ~1.0]`: measured over 900 frames (v2.8.1), the 2A03 alone spans
    /// about `-0.385..0.223` with a zero mean, and expansion audio reaches
    /// further (a Namco 163 channel, `+/-0.870`). Nothing measured passes
    /// `+/-1.0`, so a frontend converting to `i16` should put full scale at
    /// `1.0`. This comment said `[0.0, ~1.0]` until v2.8.1.
    pub fn drain_audio(&mut self) -> Vec<f32> {
        self.bus.drain_audio()
    }

    /// Set the buttons currently held on player `port`. Ports 0/1 are the
    /// standard controllers (`$4016`/`$4017`); ports 2/3 are players 3/4 on
    /// the Four Score adapter (only polled when [`Self::set_four_score`] is
    /// on). The change takes effect on the next strobe edge.
    ///
    /// # Panics
    ///
    /// Panics if `port` is not in `0..=3`.
    pub const fn set_buttons(&mut self, port: usize, buttons: Buttons) {
        self.bus.set_buttons(port, buttons);
    }

    /// Get the buttons currently held on player `port` (0/1 = `$4016`/`$4017`;
    /// 2/3 = Four Score players 3/4). Read-only; does not advance emulator
    /// state.
    ///
    /// Used by the TAS movie recorder (`crate::movie`) to capture the inputs
    /// applied before each [`Self::run_frame`]. (Movies record players 1 & 2;
    /// Four Score players 3/4 are not part of the `.rnm` stream.)
    ///
    /// # Panics
    ///
    /// Panics if `port` is not in `0..=3`.
    #[must_use]
    pub const fn buttons(&self, port: usize) -> Buttons {
        self.bus.controller(port).buttons()
    }

    /// Enable/disable the Four Score 4-player adapter. Off by default; while
    /// off, controller reads are byte-identical to the standard two-pad
    /// behavior (the determinism contract and save-states are unaffected).
    /// When on, players 3/4 (ports 2/3) are multiplexed onto `$4016`/`$4017`
    /// across a 24-read serial sequence.
    pub const fn set_four_score(&mut self, enabled: bool) {
        self.bus.set_four_score(enabled);
    }

    /// Whether the Four Score adapter is currently enabled.
    #[must_use]
    pub const fn four_score(&self) -> bool {
        self.bus.four_score()
    }

    // --- Vs. System DIP switches + coin/service inputs ---

    /// True when the running cart is Nintendo Vs. System arcade hardware
    /// (NES 2.0 console type = Vs. System). The RGB PPU + DIP/coin inputs only
    /// take effect on such carts.
    #[must_use]
    pub fn is_vs_system(&self) -> bool {
        self.bus.is_vs_system()
    }

    /// True when the cart's header marks a Vs. `DualSystem` board (two CPUs /
    /// two PPUs; NES 2.0 byte-13 high nibble = Vs. hardware type 5/6).
    ///
    /// Detection only: this single-system core cannot boot a `DualSystem` title
    /// past its attract handshake, so the frontend uses this to surface a clear
    /// note. The two-CPU/two-PPU emulation is a documented v2.0 deferral
    /// (`docs/audit/vs-dualsystem-design-2026-06-11.md`).
    #[must_use]
    pub const fn is_vs_dual_system(&self) -> bool {
        self.bus.is_vs_dual_system()
    }

    /// Set the Vs. System 8-bit DIP-switch bank (switch 1 = bit 0 .. switch 8 =
    /// bit 7). Read through the upper bits of `$4016`/`$4017`. No effect on
    /// non-Vs. carts; the standard controller read stays byte-identical.
    pub const fn set_vs_dip(&mut self, dip: u8) {
        self.bus.set_vs_dip(dip);
    }

    /// Current Vs. System DIP-switch bank.
    #[must_use]
    pub const fn vs_dip(&self) -> u8 {
        self.bus.vs_dip()
    }

    /// Override the Vs. System PPU type and re-apply the output palette.
    ///
    /// iNES-1.0 Vs. dumps default to the 2C03 palette (no NES 2.0 byte-13);
    /// the per-game database ([`crate::vs_db`]) supplies the correct
    /// 2C04-000x / 2C05 type, which the frontend applies through this setter.
    /// Mostly the colour LUT the PPU emits through, but a 2C05 also returns
    /// its identification bits in `$2002` and swaps `$2000` / `$2001`, which
    /// game code reads -- so it is emulation state, and movies and netplay
    /// carry it (v2.9.8, [`crate::HardwareOptions`]). (Until v2.9.8 this said
    /// "never game logic", which the 2C05 path contradicts.) No effect on
    /// non-Vs. carts.
    pub const fn set_vs_ppu_type(&mut self, t: rustynes_mappers::VsPpuType) {
        self.bus.set_vs_ppu_type(t);
    }

    /// v2.9.8 — the Vs. System PPU type in effect: the header's, or the one a
    /// later [`Self::set_vs_ppu_type`] installed. [`rustynes_mappers::VsPpuType::None`]
    /// on every non-Vs. cart.
    ///
    /// Read by [`crate::HardwareOptions::capture`]: on a 2C05 the type also
    /// sets the `$2002` identification bits and swaps `$2000` / `$2001`, which
    /// game code reads, so a movie or a netplay peer must run the same one.
    #[must_use]
    pub const fn vs_ppu_type(&self) -> rustynes_mappers::VsPpuType {
        self.bus.cart.vs_ppu_type
    }

    /// v2.9.8 — the parsed cartridge description the machine was built from
    /// (mapper, submapper, mirroring, RAM sizes, console type ...), after any
    /// load-time header correction. Crate-internal: read by
    /// [`crate::BoardDescription::capture`].
    #[must_use]
    pub(crate) const fn cartridge(&self) -> &rustynes_mappers::Cartridge {
        &self.bus.cart
    }

    /// Latch a Vs. System coin insertion on the given acceptor (0 = #1, 1 = #2).
    /// Reads true for a real-hardware ~40-70 ms window; the frontend should
    /// clear it (see [`Self::clear_coin`]) after a few frames.
    pub const fn insert_coin(&mut self, acceptor: u8) {
        self.bus.insert_coin(acceptor);
    }

    /// Clear all latched Vs. System coin-insert signals.
    pub const fn clear_coin(&mut self) {
        self.bus.clear_coin();
    }

    /// Set / clear the Vs. System service button.
    pub const fn set_vs_service(&mut self, pressed: bool) {
        self.bus.set_vs_service(pressed);
    }

    // --- Famicom Disk System disk control (Stage 2b) ---

    /// Number of disk sides in the inserted FDS image. Returns 0 for cartridge
    /// builds (so a frontend can branch on "is this an FDS game?").
    #[must_use]
    pub fn disk_side_count(&self) -> usize {
        self.bus.disk_side_count()
    }

    /// The currently inserted FDS disk side index, or `None` when ejected (or
    /// for a cartridge build). A game that prompts "insert side B" is asking the
    /// user to call [`Self::set_disk_side`].
    #[must_use]
    pub fn inserted_disk_side(&self) -> Option<usize> {
        self.bus.inserted_disk_side()
    }

    /// Insert FDS side `i` (`Some(i)`) or eject the disk (`None`). Inserting
    /// resets the head and opens a short deterministic "not ready" window (the
    /// BIOS polls `$4032` and waits for ready); an out-of-range index is
    /// ignored. No-op on cartridge builds. This is how the user complies with a
    /// game's "insert side N" prompt.
    pub fn set_disk_side(&mut self, side: Option<usize>) {
        self.bus.set_disk_side(side);
    }

    /// Start recording the diagnostic FDS read-stream trace (the `$4031` disk-byte
    /// stream + `$4025` control writes + side changes). Off by default and
    /// observation-only — it never affects emulation, so the determinism contract
    /// holds. Drain it with [`Self::take_fds_trace`]. No-op on cartridge builds.
    /// Used by the `fds_trace` diagnostic harness to debug disk-read / side-swap
    /// failures (e.g. the Kid Icarus side-B `ERR.07` stall).
    pub fn enable_fds_trace(&mut self) {
        self.bus.enable_fds_trace();
    }

    /// Drain the accumulated FDS read-stream trace records. Empty for cartridge
    /// builds or when [`Self::enable_fds_trace`] was never called.
    #[must_use]
    pub fn take_fds_trace(&mut self) -> Vec<rustynes_mappers::FdsTraceRec> {
        self.bus.take_fds_trace()
    }

    /// Re-serialize the (possibly-modified) FDS disk image to the headerless
    /// `.fds` byte layout so the host can write it to a side-car `.fds.sav`
    /// (keyed by [`Self::rom_sha256`]; a console booted from that file reports
    /// the same key once the host calls [`Self::set_rom_identity`]). Empty for
    /// cartridge builds.
    #[must_use]
    pub fn disk_image_bytes(&self) -> Vec<u8> {
        self.bus.disk_image_bytes()
    }

    /// Whether the FDS disk image has unsaved writes since the last
    /// [`Self::clear_disk_dirty`]. A frontend checks this on quit / periodically
    /// to decide whether to persist the disk.
    #[must_use]
    pub fn disk_is_dirty(&self) -> bool {
        self.bus.disk_is_dirty()
    }

    /// Clear the FDS disk dirty flag after persisting the image.
    pub fn clear_disk_dirty(&mut self) {
        self.bus.clear_disk_dirty();
    }

    /// Mark the inserted FDS disk read-only (`true`) or writable (`false`,
    /// the default). Drives the `$4032` write-protect flag; a write-protected
    /// disk drops bytes in write mode without modifying the medium.
    pub fn set_disk_write_protected(&mut self, protected: bool) {
        self.bus.set_disk_write_protected(protected);
    }

    /// Attach a non-standard overlay input device on `port` (0 = `$4016`, 1 =
    /// `$4017`). Pass `None` to unplug it and return the port to the standard
    /// controller / Four Score path (byte-identical reads). Devices are
    /// unplugged on power-cycle.
    ///
    /// # Panics
    ///
    /// Panics if `port` is not in `0..=1`.
    pub fn set_expansion_device(&mut self, port: usize, device: Option<InputDevice>) {
        self.bus.set_expansion_device(port, device);
    }

    /// Borrow the overlay device attached to `port` (0 = `$4016`, 1 =
    /// `$4017`), if any.
    ///
    /// # Panics
    ///
    /// Panics if `port` is not in `0..=1`.
    #[must_use]
    pub const fn expansion_device(&self, port: usize) -> &Option<InputDevice> {
        self.bus.expansion_device(port)
    }

    /// Attach an Arkanoid "Vaus" paddle on `port` (typically port 1 / `$4017`)
    /// and set its position + fire state. `position` is the raw 8-bit
    /// potentiometer value (`$00` far-left .. `$FF` far-right); `fire` is the
    /// single button. Convenience wrapper that attaches the device if absent
    /// then updates it.
    ///
    /// # Panics
    ///
    /// Panics if `port` is not in `0..=1`.
    pub fn set_paddle(&mut self, port: usize, position: u8, fire: bool) {
        if !matches!(self.bus.expansion_device(port), Some(InputDevice::Vaus(_))) {
            self.bus.set_expansion_device(
                port,
                Some(InputDevice::Vaus(crate::input_device::VausState::new())),
            );
        }
        self.bus.set_paddle(port, position, fire);
    }

    /// Attach an NES Zapper light gun on `port` (typically port 1 / `$4017`)
    /// and set its aim point + trigger. `(x, y)` is the screen pixel the gun is
    /// aimed at (0..256, 0..240; out of range = off-screen); `trigger` is the
    /// trigger state. Convenience wrapper that attaches the device if absent
    /// then updates it.
    ///
    /// Light detection is sampled from the framebuffer at the end of each
    /// [`Self::run_frame`]; the determinism contract holds because the sample
    /// only runs when a Zapper is attached (the no-device path is unchanged).
    ///
    /// # Panics
    ///
    /// Panics if `port` is not in `0..=1`.
    pub fn set_zapper(&mut self, port: usize, x: u16, y: u16, trigger: bool) {
        if !matches!(
            self.bus.expansion_device(port),
            Some(InputDevice::Zapper(_))
        ) {
            self.bus.set_expansion_device(
                port,
                Some(InputDevice::Zapper(crate::input_device::ZapperState::new())),
            );
        }
        self.bus.set_zapper(port, x, y, trigger);
    }

    /// A3 (v2.2.3): enable the **beam-relative** Zapper light model.
    ///
    /// **Default ON since v2.3.6** (was off in v2.2.3-v2.3.5). See
    /// [`crate::bus::SystemBus::set_zapper_temporal_light`] for the model and
    /// for why it was promoted; in short, the light bit is a function of where
    /// the CRT beam is at the moment of the read (dark before the beam paints
    /// the aim row, lit for the ~19-26-scanline photodiode hold, dark after)
    /// instead of one answer for the whole frame — and the frame model made a
    /// *Duck Hunt* hit impossible.
    ///
    /// Pass `false` to restore the pre-v2.3.6 frame-granular behaviour.
    ///
    /// Deterministic either way: the temporal answer is a pure function of
    /// framebuffer + aim + current scanline and holds no extra state, so it
    /// adds nothing to serialize and cannot desync a save state or a netplay
    /// rollback.
    pub const fn set_zapper_temporal_light(&mut self, on: bool) {
        self.bus.set_zapper_temporal_light(on);
    }

    /// Whether the beam-relative Zapper light model is enabled (A3).
    #[must_use]
    pub const fn zapper_temporal_light(&self) -> bool {
        self.bus.zapper_temporal_light()
    }

    /// Drive the Famicom built-in **microphone** (read on `$4016` bit 2).
    ///
    /// The hardwired second Famicom controller carries a push-to-talk mic that
    /// games poll on `$4016.D2` (e.g. *Zelda*'s Pols Voice, *Kid Icarus*). Pass
    /// `pressed = true` while the frontend's mic key is held / an audio source
    /// crosses the loudness threshold. Additive and opt-in: `false` (the
    /// default) keeps the `$4016` read byte-identical to a stock NES.
    pub const fn set_microphone(&mut self, pressed: bool) {
        self.bus.set_microphone(pressed);
    }

    /// Attach an NES Power Pad / Family Fun Fitness mat on `port` (typically
    /// port 1 / `$4017`) and set its live button mask (bit `i` = mat button
    /// `i+1`, 0..=11). Convenience wrapper that attaches the device if absent
    /// then updates it. Opt-in: the no-device path stays byte-identical.
    ///
    /// # Panics
    ///
    /// Panics if `port` is not in `0..=1`.
    pub fn set_power_pad(&mut self, port: usize, buttons: u16) {
        if !matches!(
            self.bus.expansion_device(port),
            Some(InputDevice::PowerPad(_))
        ) {
            self.bus.set_expansion_device(
                port,
                Some(InputDevice::PowerPad(
                    crate::input_device::PowerPadState::new(),
                )),
            );
        }
        self.bus.set_power_pad(port, buttons);
    }

    /// v1.6.0 B3 — the latched standard-controller button bitmask for `port`
    /// (`0` = P1 / `$4016`, `1` = P2 / `$4017`; `2`/`3` are the Four Score
    /// players), in [`Buttons`](crate::Buttons) bit order (A = bit 0 .. Right =
    /// bit 7). Read-only and side-effect-free — it reads the latched state, not
    /// the shift register, so it never perturbs a controller poll. Exposed for
    /// the Lua `joypad.get` query.
    ///
    /// # Panics
    ///
    /// Panics if `port` is not in `0..=3`.
    #[must_use]
    pub fn controller_buttons(&self, port: usize) -> u8 {
        assert!(port <= 3, "controller port {port} out of range (0..=3)");
        self.bus.controller(port).buttons().bits()
    }

    /// v1.2.0 Workstream D — attach a SNES-style serial mouse on `port` (0 =
    /// `$4016`, 1 = `$4017`) and set its movement / buttons / sensitivity.
    /// `(dx, dy)` are the signed per-frame deltas (clamped to +/-127 on latch);
    /// `sensitivity` is 0 (low) / 1 (medium) / 2 (high). Convenience wrapper
    /// that attaches the device if absent then updates it. Opt-in: the no-device
    /// path stays byte-identical.
    ///
    /// # Panics
    ///
    /// Panics if `port` is not in `0..=1`.
    pub fn set_snes_mouse(
        &mut self,
        port: usize,
        dx: i16,
        dy: i16,
        left: bool,
        right: bool,
        sensitivity: u8,
    ) {
        if !matches!(
            self.bus.expansion_device(port),
            Some(InputDevice::SnesMouse(_))
        ) {
            self.bus.set_expansion_device(
                port,
                Some(InputDevice::SnesMouse(
                    crate::input_device::SnesMouseState::new(),
                )),
            );
        }
        self.bus
            .set_snes_mouse(port, dx, dy, left, right, sensitivity);
    }

    /// v1.2.0 Workstream D — attach a Famicom Family BASIC keyboard on `port`
    /// (typically port 1 / `$4017`) and set its pressed-key bitmap. `keys` is
    /// one byte per matrix row (`keys[row]` bits 0..=3 = column-half 0 keys,
    /// bits 4..=7 = column-half 1 keys); the frontend builds it from host keys.
    /// Convenience wrapper that attaches the device if absent then updates it.
    /// Opt-in: the no-device path stays byte-identical.
    ///
    /// # Panics
    ///
    /// Panics if `port` is not in `0..=1`.
    pub fn set_family_keyboard(&mut self, port: usize, keys: [u8; 9]) {
        if !matches!(
            self.bus.expansion_device(port),
            Some(InputDevice::FamilyKeyboard(_))
        ) {
            self.bus.set_expansion_device(
                port,
                Some(InputDevice::FamilyKeyboard(
                    crate::input_device::FamilyKeyboardState::new(),
                )),
            );
        }
        self.bus.set_family_keyboard(port, keys);
    }

    /// v1.3.0 Workstream F1 — attach a Bandai **Family Trainer** mat on `port`
    /// and set its 12-button mask (bit `i` = mat button `i+1`). The Family
    /// Trainer is layout-equivalent to the Power Pad and reuses its scan; this
    /// attaches the [`InputDevice::FamilyTrainer`] variant (distinct from
    /// [`Self::set_power_pad`] so the selected device round-trips through a
    /// save-state). Opt-in: the no-device path stays byte-identical.
    ///
    /// # Panics
    ///
    /// Panics if `port` is not in `0..=1`.
    pub fn set_family_trainer(&mut self, port: usize, buttons: u16) {
        if !matches!(
            self.bus.expansion_device(port),
            Some(InputDevice::FamilyTrainer(_))
        ) {
            self.bus.set_expansion_device(
                port,
                Some(InputDevice::FamilyTrainer(
                    crate::input_device::PowerPadState::new(),
                )),
            );
        }
        self.bus.set_family_trainer(port, buttons);
    }

    /// v1.3.0 Workstream F1 — attach a **Subor keyboard** on `port` and set its
    /// pressed-key bitmap (one byte per matrix row, like
    /// [`Self::set_family_keyboard`]). The Subor keyboard reuses the Family
    /// BASIC keyboard matrix scan; this attaches the
    /// [`InputDevice::SuborKeyboard`] variant. Opt-in: the no-device path stays
    /// byte-identical.
    ///
    /// # Panics
    ///
    /// Panics if `port` is not in `0..=1`.
    pub fn set_subor_keyboard(&mut self, port: usize, keys: [u8; 9]) {
        if !matches!(
            self.bus.expansion_device(port),
            Some(InputDevice::SuborKeyboard(_))
        ) {
            self.bus.set_expansion_device(
                port,
                Some(InputDevice::SuborKeyboard(
                    crate::input_device::FamilyKeyboardState::new(),
                )),
            );
        }
        self.bus.set_subor_keyboard(port, keys);
    }

    /// v1.3.0 Workstream F1 — attach a **Konami Hyper Shot** on `port` and set
    /// its 4-button mask (bit 0 = P1 Run, 1 = P1 Jump, 2 = P2 Run, 3 = P2 Jump).
    /// Opt-in: the no-device path stays byte-identical.
    ///
    /// # Panics
    ///
    /// Panics if `port` is not in `0..=1`.
    pub fn set_konami_hyper_shot(&mut self, port: usize, buttons: u8) {
        if !matches!(
            self.bus.expansion_device(port),
            Some(InputDevice::KonamiHyperShot(_))
        ) {
            self.bus.set_expansion_device(
                port,
                Some(InputDevice::KonamiHyperShot(
                    crate::input_device::KonamiHyperShotState::new(),
                )),
            );
        }
        self.bus.set_konami_hyper_shot(port, buttons);
    }

    /// v1.3.0 Workstream F1 — attach a **Bandai Hyper Shot** (Exciting Boxing
    /// punching bag) on `port` and set its 8-sensor mask (bits 0..=3 = the A=0
    /// group, bits 4..=7 = the A=1 group). Opt-in: the no-device path stays
    /// byte-identical.
    ///
    /// # Panics
    ///
    /// Panics if `port` is not in `0..=1`.
    pub fn set_bandai_hyper_shot(&mut self, port: usize, sensors: u8) {
        if !matches!(
            self.bus.expansion_device(port),
            Some(InputDevice::BandaiHyperShot(_))
        ) {
            self.bus.set_expansion_device(
                port,
                Some(InputDevice::BandaiHyperShot(
                    crate::input_device::BandaiHyperShotState::new(),
                )),
            );
        }
        self.bus.set_bandai_hyper_shot(port, sensors);
    }

    /// v1.1.0 beta.1 (T-110-B4) — set (`Some`) or clear (`None`) a per-game
    /// **nametable mirroring override**, a load-time correction for ROMs whose
    /// iNES header carries the wrong mirroring flag (supplied by the frontend's
    /// game database). `None` (default) defers to the mapper — byte-identical,
    /// so the determinism / `AccuracyCoin` contract and the core test suites are
    /// unaffected (they never set it). Persisted in the save-state. Does not
    /// affect mappers with on-cart VRAM (4-screen).
    pub const fn set_mirroring_override(&mut self, m: Option<rustynes_mappers::Mirroring>) {
        self.bus.set_mirroring_override(m);
    }

    /// v2.9.8 — the per-game nametable mirroring override in effect (`None` =
    /// the mapper decides). See [`Self::set_mirroring_override`].
    #[must_use]
    pub const fn mirroring_override(&self) -> Option<rustynes_mappers::Mirroring> {
        self.bus.mirroring_override()
    }

    /// Whether the loaded mapper's nametable mirroring is **hardwired** by the
    /// cartridge (solder pads / header bit) rather than controlled by the
    /// mapper's own registers at runtime.
    ///
    /// The frontend consults this before honoring a game-database mirroring
    /// correction: a static override is only valid for a hardwired board, and
    /// force-applying one to a mapper that switches mirroring itself (MMC1/3/5,
    /// `AxROM`, VRC, …) corrupts its rendering. See
    /// [`rustynes_mappers::Mapper::has_hardwired_mirroring`].
    #[must_use]
    pub fn mapper_has_hardwired_mirroring(&self) -> bool {
        self.bus.mapper_has_hardwired_mirroring()
    }

    /// Write a byte directly into CPU work RAM (`$0000-$1FFF`). Used by the
    /// frontend's raw RAM cheats (GameShark-style); applied *after*
    /// [`Self::run_frame`], so the deterministic core run loop is unchanged
    /// (the determinism contract holds for the no-cheat path). No-op outside
    /// system RAM.
    pub fn poke_ram(&mut self, addr: u16, value: u8) {
        self.bus.poke_ram(addr, value);
    }

    /// v1.7.0 "Forge" Workstream A1 — debugger writeback into the PPU bus
    /// (`$0000-$3FFF`): CHR pattern bytes (mapper `ppu_write`, a no-op on
    /// CHR-ROM), nametable tiles/attributes (mapper-absorbed, else CIRAM via the
    /// active mirroring), and palette RAM. The PPU-bus counterpart of
    /// [`Self::poke_ram`].
    ///
    /// Reached only through the frontend's gated post-frame poke path (the same
    /// caller-side, after-[`Self::run_frame`] stage the raw RAM cheats use), so
    /// the deterministic core run loop is unchanged and the no-edit path is
    /// byte-identical. `debug-hooks`-gated.
    #[cfg(feature = "debug-hooks")]
    pub fn debug_poke_ppu(&mut self, addr: u16, value: u8) {
        self.bus.debug_poke_ppu(addr, value);
    }

    /// v1.7.0 "Forge" Workstream A1 — debugger writeback for one OAM byte
    /// (`idx` = 0..256: byte 0 = Y, 1 = tile, 2 = attributes, 3 = X per
    /// sprite). `debug-hooks`-gated; reached only through the gated post-frame
    /// poke path, so the default build is byte-identical.
    #[cfg(feature = "debug-hooks")]
    pub const fn poke_oam_byte(&mut self, idx: u8, value: u8) {
        self.bus.debug_poke_oam(idx, value);
    }

    /// v1.7.0 "Forge" Workstream B (Lua API parity) — debugger/scripted
    /// writeback of the CPU register file (`a`/`x`/`y`/`s`/`p` bits/`pc`). The
    /// structured-state counterpart of [`Self::poke_ram`], backing the Lua
    /// `emu:setState(t)` field map (Mesen2 parity).
    ///
    /// Reached only through the frontend / script crate's gated post-frame poke
    /// path (the same caller-side, after-[`Self::run_frame`] stage the raw RAM
    /// cheats + the other `debug_poke_*` writebacks use), so the deterministic
    /// core run loop is unchanged and the no-edit path is byte-identical.
    /// `debug-hooks`-gated. `p` is taken as a raw status-bits byte (truncated to
    /// the defined flags, mirroring a `PLP` / save-state restore).
    #[cfg(feature = "debug-hooks")]
    // This is a runtime register-file mutator (the structured-state counterpart
    // of `poke_ram`); `const` adds no value and would needlessly constrain the
    // body, so the `missing_const_for_fn` suggestion is declined here.
    #[allow(clippy::missing_const_for_fn)]
    pub fn debug_set_cpu_state(&mut self, a: u8, x: u8, y: u8, s: u8, p_bits: u8, pc: u16) {
        self.cpu.a = a;
        self.cpu.x = x;
        self.cpu.y = y;
        self.cpu.s = s;
        self.cpu.p = rustynes_cpu::Status::from_bits_truncate(p_bits);
        self.cpu.pc = pc;
    }

    /// Read a byte from the CPU address space (`$0000-$FFFF`) for inspection,
    /// **without** the register side effects of a real CPU read — reading
    /// `$2002` does not clear the VBL flag / address latch and `$2007` does not
    /// advance the PPU read buffer. Used by the debugger and the Lua scripting
    /// API (`emu.read`); it observes state without advancing the emulator,
    /// preserving determinism.
    #[must_use]
    pub fn peek(&mut self, addr: u16) -> u8 {
        self.bus.debug_peek_cpu(addr)
    }

    /// v1.2.0 C3 (hd-pack) — side-effect-free read of the PPU bus
    /// (`$0000-$3FFF`): CHR pattern data, nametables, palette RAM. Used by the
    /// HD-pack compositor to hash a tile's 16 CHR bytes. Observes state without
    /// advancing the emulator, preserving determinism.
    #[cfg(feature = "hd-pack")]
    #[must_use]
    pub fn peek_ppu(&mut self, addr: u16) -> u8 {
        self.bus.debug_peek_ppu(addr)
    }

    /// Add a Game Genie code (6 or 8 characters, case-insensitive) that
    /// substitutes a byte the CPU reads from PRG-ROM (`$8000-$FFFF`).
    ///
    /// Codes are a runtime overlay — they are **not** part of the save-state
    /// and do not perturb the determinism contract when none are active. With
    /// codes active, the substituted bytes are part of the deterministic
    /// input (record a movie with the same codes to reproduce a run).
    ///
    /// # Errors
    ///
    /// Returns [`GenieError`] if the code string cannot be decoded.
    pub fn add_genie_code(&mut self, code: &str) -> Result<(), GenieError> {
        self.bus.add_genie_code(code)
    }

    /// Remove the active Game Genie code whose canonical (upper-case) string
    /// matches `code`. No-op if no such code is active.
    pub fn remove_genie_code(&mut self, code: &str) {
        self.bus.remove_genie_code(code);
    }

    /// Remove all active Game Genie codes.
    pub fn clear_genie_codes(&mut self) {
        self.bus.clear_genie_codes();
    }

    /// Iterate the active Game Genie codes (address-sorted).
    pub fn genie_codes(&self) -> impl Iterator<Item = &GenieCode> {
        self.bus.genie_codes()
    }

    /// Drain into a slice; returns the count copied.  Excess samples are
    /// dropped if `out` is smaller than the buffered count.
    pub fn drain_audio_into(&mut self, out: &mut [f32]) -> usize {
        self.bus.drain_audio_into(out)
    }

    /// The ROM's persistent identity: SHA-256 of an iNES / NES 2.0 image's
    /// bytes after its 16-byte header, or of the whole image for FDS and NSF.
    ///
    /// Everything that persists per game is keyed by it: save-state slot
    /// directories, the battery `.sav`, cheats, the `.rns` header's ROM tag
    /// ([`Self::rom_hash_tag`]), movies and netplay's ROM match. Computed once
    /// at construction; subsequent calls are O(1). A host that boots a saved
    /// copy of an FDS disk replaces it with the pristine disk's hash
    /// ([`Self::set_rom_identity`], v2.9.9), so a game's own disk saves never
    /// move its identity.
    ///
    /// **Why the header is excluded (v2.9.8).** Until v2.9.8 this hashed the
    /// whole image as constructed, which on the desktop is the image AFTER the
    /// game database corrected its header. Any change to those corrections
    /// therefore renamed a game's saves and invalidated its states, and v2.9.8
    /// alone changed them three times (the dirty-tail mapper nibble, the NES 2.0
    /// guard, the region promotion). The header is the one part of an image
    /// that load-time corrections rewrite; PRG and CHR never change, so an
    /// identity built from them survives every past and future correction, and
    /// two dumps of the same game with different headers share their saves.
    /// The maintainer accepted the one-time break this causes (2026-10-01).
    #[must_use]
    pub const fn rom_sha256(&self) -> &[u8; 32] {
        &self.rom_sha256
    }

    /// The identity [`Self::rom_sha256`] reports for a console built from
    /// `image`, computed without building one: SHA-256 of the bytes after the
    /// 16-byte header of an iNES / NES 2.0 image, of the whole image otherwise
    /// (FDS, NSF, UNIF).
    ///
    /// For a host that keys stores before, or without, constructing a console
    /// -- a library import that must not need the FDS BIOS, or a key
    /// migration (v2.9.9 re-audit NF-21: the mobile hosts keyed saves by the
    /// whole file's hash). It is the same function every constructor uses, so
    /// the two cannot drift. It does not include a later
    /// [`Self::set_rom_identity`].
    #[must_use]
    pub fn rom_identity_of(image: &[u8]) -> [u8; 32] {
        rom_identity_sha256(image)
    }

    /// SHA-256 of the complete image as constructed, header included.
    ///
    /// The Vs. System database ([`crate::vs_db`]) keeps a whole-file key on
    /// each row as a fallback to its identity key ([`Self::rom_sha256`]), so a
    /// row added from a dump that was never staged stays reachable;
    /// [`crate::vs_db::lookup`] consults both. Nothing else is keyed by it.
    /// Identical to [`Self::rom_sha256`] for FDS and NSF.
    #[must_use]
    pub const fn image_sha256(&self) -> &[u8; 32] {
        &self.image_sha256
    }

    /// Replace this console's persistent identity ([`Self::rom_sha256`]) with
    /// `sha256`, for a host that boots a game from a SAVED copy of its image.
    ///
    /// The case it exists for is a Famicom Disk System disk. FDS games save by
    /// writing to the disk, so a host persists the written image
    /// ([`Self::disk_image_bytes`]) and boots from THAT file on the next
    /// launch, which is how a disk game's progress carries over. Every
    /// constructor hashes the bytes it is given, so from the game's first disk
    /// save on, an `Nes` booted that way reported the MODIFIED disk's hash, and
    /// everything keyed on [`Self::rom_sha256`] changed identity with it:
    /// save-state slots and the `.rns` ROM tag ([`Self::rom_hash_tag`]),
    /// cheats, movies and `TAStudio`, netplay's ROM match, the HD-pack and
    /// per-game keys, the RA progress sidecar (v2.9.9 re-audit NF-17). The
    /// host knows the pristine image's hash (it keys the saved disk with it),
    /// so it passes that here, right after construction, and the console then
    /// reports the identity of the game rather than of one of its saves.
    ///
    /// Only the identity moves. [`Self::image_sha256`] stays the hash of the
    /// bytes actually loaded: its one consumer is the Vs. System database's
    /// whole-file fallback, which must describe the image in hand (and a disk
    /// never matches it). Emulation is untouched: nothing in the chips reads
    /// the identity.
    ///
    /// A setter rather than a constructor variant because the identity is the
    /// one field the host has to supply, and each image kind already has two
    /// constructors (with and without a sample rate); a setter covers all of
    /// them, including a host that builds the console through `Emu`. It is the
    /// host's word: the core cannot check that `sha256` belongs to an earlier
    /// state of the loaded image. Call it before anything is keyed on the
    /// identity (a movie recorded before the call stamps the old one).
    pub const fn set_rom_identity(&mut self, sha256: [u8; 32]) {
        self.rom_sha256 = sha256;
    }

    /// Truncated ROM hash tag stored in the save-state header.
    #[must_use]
    pub fn rom_hash_tag(&self) -> [u8; ROM_HASH_TAG_LEN] {
        let mut t = [0u8; ROM_HASH_TAG_LEN];
        t.copy_from_slice(&self.rom_sha256[..ROM_HASH_TAG_LEN]);
        t
    }

    /// Encode the entire emulator state into a `.rns` snapshot blob.
    ///
    /// Includes a versioned container header and the four chip + bus
    /// sections (`CPU `, `PPU `, `APU `, `MAP `, `BUS `), plus an optional
    /// `THM ` thumbnail section (128x120 RGBA8 nearest-neighbor downsample
    /// of the current framebuffer). The thumbnail is for UI slot pickers
    /// only -- per ADR 0003 it is NOT part of the deterministic save-state
    /// contract.
    #[must_use]
    pub fn snapshot(&self) -> Vec<u8> {
        let tag = self.rom_hash_tag();
        // The bus knows how to emit BUS / PPU / APU / MAP sections; we
        // splice the CPU section in at the end.
        let mut out = self.bus.snapshot(tag);
        let cpu_body = self.cpu.snapshot();
        save_state::write_section(
            &mut out,
            save_state::tag::CPU,
            rustynes_cpu::CPU_SNAPSHOT_VERSION,
            &cpu_body,
        );
        // Optional thumbnail. Body layout: width(u16 le) + height(u16 le) +
        // length(u32 le) + raw RGBA8. The fixed THUMBNAIL_LEN is what we
        // emit but the body carries the dimensions explicitly so future
        // bumps (different thumbnail sizes) can be detected by the reader.
        let thumb = self.thumbnail();
        let mut body = Vec::with_capacity(2 + 2 + 4 + save_state::THUMBNAIL_LEN);
        body.extend_from_slice(
            &u16::try_from(save_state::THUMBNAIL_WIDTH)
                .unwrap()
                .to_le_bytes(),
        );
        body.extend_from_slice(
            &u16::try_from(save_state::THUMBNAIL_HEIGHT)
                .unwrap()
                .to_le_bytes(),
        );
        body.extend_from_slice(&u32::try_from(thumb.len()).unwrap().to_le_bytes());
        body.extend_from_slice(&thumb);
        save_state::write_section(
            &mut out,
            save_state::tag::THM,
            save_state::THUMBNAIL_VERSION,
            &body,
        );
        out
    }

    /// v2.8.0 Phase 3 — [`Self::snapshot`] minus the `THM ` thumbnail
    /// section, encoded into a caller-owned reused buffer. The fast path
    /// for per-frame consumers (run-ahead, the netplay save-state ring):
    /// no allocation in steady state and no 61 KiB thumbnail build. The
    /// output parses with [`Self::restore`] / [`Self::restore_quiet`]
    /// exactly like a full snapshot (`THM ` is optional by format).
    pub fn snapshot_core_into(&self, out: &mut Vec<u8>) {
        let tag = self.rom_hash_tag();
        self.bus.snapshot_into(out, tag);
        let cpu_body = self.cpu.snapshot();
        save_state::write_section(
            out,
            save_state::tag::CPU,
            rustynes_cpu::CPU_SNAPSHOT_VERSION,
            &cpu_body,
        );
    }

    /// v2.3.3 — [`Self::snapshot_core_into`] with the PPU encoded **slim**
    /// (no framebuffer), for the rewind ring.
    ///
    /// The ring snapshots on every frame inside the frame budget and then XORs
    /// and LZ4-compresses the result. The framebuffer is 245,760 of the ~250 KB
    /// and is the worst possible payload for that scheme, since it changes
    /// every frame: the XOR never zeroes and the delta never compresses.
    /// Measured, that made rewind roughly double the produce-interval p95 and
    /// it was the cause of a user-visible judder report — see
    /// `docs/performance.md` v2.3.3 F3/F4.
    ///
    /// A blob written here restores every field except the framebuffer, so the
    /// caller must regenerate the image; [`Self::rewind_step_back`] runs one
    /// frame to do exactly that.
    pub fn snapshot_core_into_slim(&self, out: &mut Vec<u8>) {
        let tag = self.rom_hash_tag();
        self.bus.snapshot_into_slim(out, tag);
        let cpu_body = self.cpu.snapshot();
        save_state::write_section(
            out,
            save_state::tag::CPU,
            rustynes_cpu::CPU_SNAPSHOT_VERSION,
            &cpu_body,
        );
    }

    /// Generate a 128x120 RGBA8 thumbnail of the current framebuffer.
    ///
    /// Nearest-neighbor downsample (sample every 2nd pixel of every 2nd row).
    /// The 1/4-resolution result is small enough that storing it in slot
    /// files is cheap (61,440 bytes uncompressed, ~10-20 KiB after the
    /// LZ4 path the rewind ring uses if it is ever wired through there).
    ///
    /// Per ADR 0003: NOT part of the deterministic save-state contract.
    /// Different builds may produce different pixel-perfect framebuffers
    /// at the same cycle if post-pass filters change.
    #[must_use]
    pub fn thumbnail(&self) -> Vec<u8> {
        // Native NES framebuffer is 256x240 RGBA8 = 245,760 bytes. Source
        // stride is 256 * 4 = 1024 bytes.
        const SRC_W: usize = 256;
        let fb = self.bus.framebuffer();
        let mut out = Vec::with_capacity(save_state::THUMBNAIL_LEN);
        for ty in 0..save_state::THUMBNAIL_HEIGHT {
            let sy = ty * 2;
            for tx in 0..save_state::THUMBNAIL_WIDTH {
                let sx = tx * 2;
                let i = (sy * SRC_W + sx) * 4;
                // Source framebuffer is always at least 256*240*4 bytes
                // (allocated by Ppu::new), so this index is in-bounds.
                out.extend_from_slice(&fb[i..i + 4]);
            }
        }
        debug_assert_eq!(out.len(), save_state::THUMBNAIL_LEN);
        out
    }

    /// Extract a thumbnail from an `.rns` save-state blob without restoring
    /// it. Used by frontends to populate slot pickers.
    ///
    /// Returns `Ok(None)` if the blob is well-formed but contains no
    /// thumbnail section (older v0.9.0 slot files).
    ///
    /// # Errors
    ///
    /// Returns [`SnapshotError`] when the container header is malformed.
    pub fn extract_thumbnail(data: &[u8]) -> Result<Option<Vec<u8>>, SnapshotError> {
        let (_h, body_off) = save_state::parse_header(data)?;
        for s in save_state::SectionIter::new(&data[body_off..]) {
            let s = s?;
            if s.tag == save_state::tag::THM {
                // Body: width(u16) + height(u16) + length(u32) + bytes.
                if s.body.len() < 8 {
                    continue;
                }
                let w = u16::from_le_bytes([s.body[0], s.body[1]]) as usize;
                let h = u16::from_le_bytes([s.body[2], s.body[3]]) as usize;
                let n = u32::from_le_bytes([s.body[4], s.body[5], s.body[6], s.body[7]]) as usize;
                // Sanity: dimensions match what we currently emit, and the
                // declared length matches the body suffix.
                if w != save_state::THUMBNAIL_WIDTH
                    || h != save_state::THUMBNAIL_HEIGHT
                    || n != save_state::THUMBNAIL_LEN
                    || s.body.len() < 8 + n
                {
                    continue;
                }
                return Ok(Some(s.body[8..8 + n].to_vec()));
            }
        }
        Ok(None)
    }

    /// Apply a previously [`Self::snapshot`]ed blob.
    ///
    /// Loading from a different ROM is allowed (the embedded hash tag is
    /// only a sanity check), but the result is undefined unless the chip
    /// section bodies are appropriate for the running mapper.
    ///
    /// The header's ROM hash tag is NOT compared with the running ROM, by
    /// decision (v2.9.0 re-audit NL-01): the paragraph above has always
    /// allowed a load from a different ROM. (The decision first rested on a
    /// second reason too, that the tag hashed the whole file including its
    /// iNES header, so a header-only correction of the same dump would have
    /// refused every state. Since v2.9.8 the tag is the leading bytes of
    /// [`Self::rom_sha256`], which leaves the header out, so that reason no
    /// longer applies; the first still does.) The section-level validation is what keeps a foreign state from
    /// crashing the core; see `docs/frontend.md` § "Save state files".
    ///
    /// # Errors
    ///
    /// Returns [`SnapshotError`] for malformed inputs; the machine is then
    /// unchanged.
    pub fn restore(&mut self, data: &[u8]) -> Result<(), SnapshotError> {
        self.restore_inner(data, true)
    }

    /// Shared restore body; `clear_rewind` distinguishes user-driven loads
    /// ([`Self::restore`] — the ring is invalidated) from same-timeline
    /// machine restores ([`Self::restore_quiet`] — the ring stays).
    fn restore_inner(&mut self, data: &[u8], clear_rewind: bool) -> Result<(), SnapshotError> {
        // v2.4.0 item B — a timeline jump, but only when this is a LOUD restore.
        //
        // `clear_rewind` already draws exactly the distinction the counter needs,
        // so it is reused rather than duplicated: `true` means a user-driven load
        // that invalidates the rewind history, `false` means a same-timeline
        // machine-driven restore (run-ahead's per-frame rollback, netplay's
        // rollback-resimulate) where the history stays valid.
        //
        // A same-timeline restore must NOT bump. That is the same rule the
        // provenance stash follows from the other direction — every same-timeline
        // restore has to carry the state that lives outside the save state — and
        // getting it wrong here would clear a consumer's telemetry sixty times a
        // second under run-ahead, which is worse than the stale-telemetry defect
        // this counter exists to fix.
        //
        // Bumped BEFORE the restore can fail, deliberately. Before v2.7.4 a
        // failed restore could leave the machine partially applied, which is a
        // discontinuity whether or not it completed. A loud restore now rolls
        // back on failure (below), so a failed one leaves the timeline intact
        // and the bump costs a consumer one telemetry reset; keeping it
        // unconditional keeps this counter's rule simple.
        if clear_rewind {
            self.timeline_generation = self.timeline_generation.wrapping_add(1);
        }
        // v2.7.4 (frontend audit MOB-08) — a load is all-or-nothing. The stages
        // in `apply_snapshot` mutate as they go (the bus sections first, then
        // the CPU, then the clock check), so a blob rejected at a later stage
        // used to leave the earlier stages from the blob and the rest from the
        // running game: a machine that was neither, which the next frame
        // emulated. So the running machine is snapshotted first and put back
        // on failure.
        //
        // v2.9.0 (re-audit NC-03 / NL-01) — on BOTH paths. v2.7.4 skipped the
        // backup for quiet restores, on the stated premise that they "only ever
        // restore snapshots this core just wrote, which cannot fail these
        // checks". That premise was false: the libretro core routes EVERY
        // `retro_unserialize` through `restore_quiet` — a user's Load State, a
        // state written by an older core, a netplay peer's state, a truncated
        // or corrupt file — and the re-audit demonstrated a rejected CPU
        // section leaving the bus, PPU, APU and mapper from the rejected file
        // under the running game's CPU. The premise is also unenforceable: the
        // quiet/loud split is about the REWIND RING (same timeline or not), and
        // nothing about that choice says the bytes are trusted.
        //
        // The backup is the THM-less `snapshot_core_into` (the thumbnail is
        // ignored on restore) into a buffer pooled on the `Nes`, so the hot
        // path — run-ahead's and netplay's per-frame rollbacks — pays one
        // state copy and no allocation for the buffer in steady state. The
        // measured cost is recorded in `docs/frontend.md` § "Save state files".
        let mut backup = core::mem::take(&mut self.restore_backup);
        self.snapshot_core_into(&mut backup);
        let applied = self.apply_snapshot(data);
        if applied.is_err() {
            // Our own fresh snapshot always restores (the round-trip
            // invariant every save-state test pins); if it somehow did not,
            // the original error is still the one worth reporting. The core
            // has no logger (`no_std`), so the invariant is asserted in debug
            // and test builds rather than silently assumed.
            //
            // The invariant needs every value a running machine can hold to
            // pass the validators. v2.9.9's re-audit (NC-09) found one that
            // did not: a restored APU filter value accepted as merely finite
            // overflowed to NaN, after which this backup's own APU section was
            // refused part-way through the rollback. The validator now bounds
            // that state, so the backup is again a state the core produced.
            let rolled_back = self.apply_snapshot(&backup);
            debug_assert!(
                rolled_back.is_ok(),
                "rolling back to this core's own snapshot failed: {rolled_back:?}"
            );
        }
        self.restore_backup = backup;
        applied?;
        // Loading invalidates the rewind ring (the new state is unrelated
        // to what was buffered before).
        if clear_rewind && let Some(r) = &mut self.rewind {
            r.clear();
        }
        // v2.3.2 "Lucid" — and it invalidates write attribution for the same
        // reason, on BOTH restore paths. The restored bytes were not written by
        // any instruction this session executed, so the PCs recorded against
        // those offsets describe a timeline that no longer exists. Reporting
        // them would be a confidently wrong answer; reporting nothing until the
        // program writes again is the honest one.
        //
        // v2.3.6 CORRECTION. This comment used to end by claiming that under
        // run-ahead the clear "fires once per displayed frame, leaving exactly
        // the visible frame's writes — which is the timeline the user is looking
        // at". That was false about the two lines below it, which empty both
        // stores completely; and because run-ahead's rollback is the LAST thing
        // before the frontend releases the emulator lock, the wipe landed on the
        // visible frame's records before any UI could read them. The shipped
        // Pixel Provenance inspector therefore rendered an empty report for every
        // user with the default `run_ahead = 1`. The clear here is right and
        // stays; run-ahead now carries the stores AROUND it (`RunAhead::finish`
        // → `Nes::take_provenance` / `put_provenance`), which is what this
        // comment always claimed was happening.
        //
        // The per-pixel provenance frame is cleared for the same reason, and it
        // needs saying separately because the obvious analogy is wrong: the
        // framebuffer IS serialized and comes back consistent with the restored
        // state, while this frame is not. A restore landing mid-frame would
        // otherwise leave pre-restore tile and palette addresses for every pixel
        // above the current scanline, unmarked. (Review catch on PR #356.)
        #[cfg(feature = "debug-hooks")]
        {
            self.bus.ppu.clear_write_attribution();
            self.bus.ppu.clear_pixel_provenance();
            // v2.3.7 — the audio register attribution is the same kind of claim
            // about the same replaced timeline: a restored state's APU registers
            // were not written by any instruction this session executed, so
            // keeping their PCs would report a timeline that no longer exists.
            //
            // This was MISSING when audio provenance first landed, while
            // `docs/audio-provenance.md` already asserted that "save-state loads
            // and netplay rollback still clear" — prose describing behaviour the
            // code did not have, which is the exact failure that let Pixel
            // Provenance ship broken for four releases. Caught in review.
            //
            // Harmless for run-ahead: `RunAhead::finish` TAKES the store before
            // `restore_quiet` and puts it back after, so `audio_prov` is `None`
            // here and this call is a no-op on that path.
            self.bus.apu.clear_audio_provenance_history();
        }
        Ok(())
    }

    /// The mutating stages of a restore: the bus sections, then the CPU
    /// section, then the cross-section clock check. Not atomic by itself; see
    /// the backup in [`Self::restore_inner`], which both public restore paths
    /// go through.
    fn apply_snapshot(&mut self, data: &[u8]) -> Result<(), SnapshotError> {
        // Restore bus first — it consumes BUS / PPU / APU / MAP sections.
        self.bus.restore(data)?;
        // Then walk the sections again to find the CPU body.
        let (_h, body_off) = save_state::parse_header(data)?;
        let mut saw_cpu = false;
        for s in save_state::SectionIter::new(&data[body_off..]) {
            let s = s?;
            if s.tag == save_state::tag::CPU {
                if s.version != rustynes_cpu::CPU_SNAPSHOT_VERSION {
                    return Err(SnapshotError::VersionMismatch {
                        tag: save_state::tag_string(s.tag),
                        file_version: s.version,
                        chip_supports: rustynes_cpu::CPU_SNAPSHOT_VERSION,
                    });
                }
                self.cpu
                    .restore(s.body)
                    .map_err(|e| SnapshotError::SectionInvalid {
                        tag: save_state::tag_string(s.tag),
                        reason: format!("{e}"),
                    })?;
                saw_cpu = true;
            }
        }
        if !saw_cpu {
            return Err(SnapshotError::MissingSection("CPU ".into()));
        }
        // v2.7.0 -- the one cross-section invariant: the CPU's master clock and
        // the bus's PPU clock must be close enough that the next catch-up
        // terminates (see `SystemBus::check_restored_clocks`).
        self.bus.check_restored_clocks(self.cpu.master_clock())?;
        Ok(())
    }

    /// v2.8.0 Phase 3 — [`Self::restore`] WITHOUT clearing the rewind ring.
    ///
    /// For internal, machine-driven restores on the same timeline —
    /// run-ahead's per-frame rollback and netplay's rollback-resimulate —
    /// where the buffered rewind history remains exactly as valid as
    /// before. User-driven loads (save-state slots) keep using
    /// [`Self::restore`], which invalidates the ring.
    ///
    /// "Quiet" says nothing about whether the bytes are trusted: the libretro
    /// core routes every `retro_unserialize` here, including user state files.
    /// Since v2.9.0 a rejected blob therefore leaves the machine exactly as it
    /// was, on this path as on [`Self::restore`].
    ///
    /// # Errors
    ///
    /// Returns [`SnapshotError`] for malformed inputs; the machine is then
    /// unchanged.
    pub fn restore_quiet(&mut self, data: &[u8]) -> Result<(), SnapshotError> {
        self.restore_inner(data, false)
    }

    /// Enable the rewind ring buffer with default capacity (32 MiB) and
    /// keyframe period (60).
    pub fn enable_rewind(&mut self) {
        self.enable_rewind_with(REWIND_DEFAULT_MAX_BYTES, REWIND_DEFAULT_KEYFRAME_PERIOD);
    }

    /// Enable rewind with explicit byte budget + keyframe period.
    pub fn enable_rewind_with(&mut self, max_bytes: usize, keyframe_period: u32) {
        self.rewind = Some(RewindRing::new(max_bytes, keyframe_period));
    }

    /// Disable rewind and free the buffer.
    pub fn disable_rewind(&mut self) {
        self.rewind = None;
    }

    /// Enable the per-CPU-instruction boot trace fixture with the given
    /// [`CpuBootTrace`](crate::cpu_boot_trace::CpuBootTrace).  Records past
    /// the trace's capacity are silently dropped (see
    /// [`CpuBootTrace::overflow`](crate::cpu_boot_trace::CpuBootTrace::overflow)).
    /// See `crates/rustynes-core/src/cpu_boot_trace.rs` for usage.
    #[cfg(feature = "cpu-boot-trace")]
    pub fn enable_cpu_boot_trace(&mut self, trace: crate::cpu_boot_trace::CpuBootTrace) {
        self.cpu_boot_trace = Some(trace);
    }

    /// Take the accumulated CPU boot trace, leaving the slot empty.
    /// Returns `None` if tracing was never enabled.
    #[cfg(feature = "cpu-boot-trace")]
    #[must_use]
    pub const fn take_cpu_boot_trace(&mut self) -> Option<crate::cpu_boot_trace::CpuBootTrace> {
        self.cpu_boot_trace.take()
    }

    /// Borrow the in-flight CPU boot trace for inspection.
    #[cfg(feature = "cpu-boot-trace")]
    #[must_use]
    pub const fn cpu_boot_trace(&self) -> Option<&crate::cpu_boot_trace::CpuBootTrace> {
        self.cpu_boot_trace.as_ref()
    }

    /// Snapshot the current `(CPU register file + bus cycle + PPU
    /// position + opcode preview)` tuple into the CPU boot trace.
    ///
    /// Called from `run_frame` / `step_instruction` BEFORE the
    /// `Cpu::step` call.  The opcode + 2 operand bytes are peeked
    /// side-effect-free via `SystemBus::debug_peek_cpu` so the
    /// trace is non-perturbing.
    ///
    /// No-op if the trace was never enabled.
    #[cfg(feature = "cpu-boot-trace")]
    fn cpu_boot_trace_record(&mut self) {
        use crate::cpu_boot_trace::CpuBootRecord;
        let Some(trace) = self.cpu_boot_trace.as_mut() else {
            return;
        };
        let cycle = self.bus.cycle();
        // Range pre-check: skip the peek bookkeeping entirely if this
        // cycle is outside the configured window.  The trace's own
        // `maybe_push` re-checks; the pre-check is the hot-path
        // optimisation.
        if !trace.config().contains(cycle) {
            return;
        }
        let pc = self.cpu.pc;
        let opcode = self.bus.debug_peek_cpu(pc);
        let op1 = self.bus.debug_peek_cpu(pc.wrapping_add(1));
        let op2 = self.bus.debug_peek_cpu(pc.wrapping_add(2));
        let ppu = self.bus.ppu();
        let mut flags: u8 = 0;
        // Mesen2 exposes `cpu.nmiFlag` and `cpu.irqFlag` (its
        // own pending-interrupt latches) but not the
        // armed-vs-pending distinction; flag bit 0 means "PPU is
        // driving NMI line high" which is observable on both
        // sides at instruction-fetch boundary.
        if ppu.nmi_line() {
            flags |= 0x01;
        }
        let rec = CpuBootRecord {
            cycle,
            frame: u32::try_from(ppu.frame()).unwrap_or(u32::MAX),
            scanline: ppu.scanline(),
            dot: ppu.dot(),
            pc,
            a: self.cpu.a,
            x: self.cpu.x,
            y: self.cpu.y,
            p: self.cpu.p.bits(),
            s: self.cpu.s,
            opcode,
            op1,
            op2,
            flags,
        };
        trace.maybe_push(rec);
    }

    /// Push the current state onto the rewind ring. Frontends call this
    /// at the end of each completed frame.
    ///
    /// No-op if rewind is disabled.
    pub fn rewind_capture(&mut self) {
        if self.rewind.is_none() {
            return;
        }
        let frame = self.bus.ppu().frame();
        // v2.8.0 Phase 3 — the core fast path: no THM thumbnail (the ring
        // is never shown in a slot picker) and a reused buffer instead of
        // a fresh ~320 KiB allocation per frame. The ring still LZ4s /
        // delta-encodes the bytes itself.
        let mut buf = core::mem::take(&mut self.rewind_snap_buf);
        // v2.3.3 — SLIM: omit the framebuffer. See `snapshot_core_into_slim`.
        self.snapshot_core_into_slim(&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 it. Returns `true` on
    /// success, `false` if the ring is empty (or rewind is disabled).
    pub fn rewind_step_back(&mut self) -> bool {
        let Some(ring) = self.rewind.as_mut() else {
            return false;
        };
        let Some(result) = ring.pop_back() else {
            return false;
        };
        let bytes = match result {
            Ok(b) => b,
            Err(_e) => return false,
        };
        // Restore but keep the ring alive (don't let `restore` clear it,
        // because the user is mid-rewind).
        let saved_ring = self.rewind.take();
        let r = self.restore(&bytes);
        // Reattach the (possibly cleared, but cleared-by-us is fine) ring.
        self.rewind = saved_ring;
        if r.is_err() {
            return false;
        }
        // v2.3.3 — ring entries are SLIM, so the restore above left the
        // framebuffer holding whatever was last displayed; without an image the
        // picture would freeze while the state rewound. Regenerate it WITHOUT
        // changing the state this call is contracted to land on:
        //
        //   1. state is at frame N (restored above), framebuffer stale
        //   2. run one frame  -> renders exactly frame N's image, state N+1
        //   3. restore the same bytes -> state back to N
        //
        // Step 3 is what makes this exact rather than approximate, and it works
        // *because* the blob is slim: a slim restore does not touch the
        // framebuffer, so the image rendered in step 2 survives. The observable
        // contract is unchanged from before v2.3.3 — `cycle()` lands on the
        // snapshotted frame — which the `rewind_step_back_returns_prior_frames`
        // harness test pins.
        //
        // Capture is suppressed across step 2, or stepping back would push the
        // frame it just rendered and the ring would never drain.
        let saved_capture = self.rewind_capture_enabled;
        self.rewind_capture_enabled = false;
        self.run_frame();
        let saved_ring = self.rewind.take();
        let re = self.restore(&bytes);
        self.rewind = saved_ring;
        self.rewind_capture_enabled = saved_capture;
        re.is_ok()
    }

    /// Drop every buffered rewind entry. Called when the user releases
    /// the rewind key, so subsequent forward play overwrites — there's
    /// nothing to overwrite, but we want forward play to capture into a
    /// fresh ring rather than tail-of-old-history.
    pub fn rewind_clear(&mut self) {
        if let Some(r) = &mut self.rewind {
            r.clear();
        }
    }

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

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

    /// Approximate memory used by the rewind ring, in bytes.
    #[must_use]
    pub fn rewind_bytes_used(&self) -> usize {
        self.rewind.as_ref().map_or(0, RewindRing::bytes_used)
    }

    // -------------------------------------------------------------------
    // Debugger inspection API (Sprint 5-3). All read-only — these methods
    // MUST NOT advance emulator-visible state.
    // -------------------------------------------------------------------

    /// Snapshot the CPU register file.
    #[must_use]
    #[allow(clippy::missing_const_for_fn)] // `is_jammed` is const-callable but we're const-conservative.
    pub fn cpu_snapshot(&self) -> CpuDebugView {
        let c = &self.cpu;
        CpuDebugView {
            a: c.a,
            x: c.x,
            y: c.y,
            s: c.s,
            pc: c.pc,
            p: c.p.bits(),
            jammed: c.is_jammed(),
            cycles: c.cycles,
        }
    }

    /// Snapshot PPU state for the debugger.
    #[must_use]
    #[allow(clippy::missing_const_for_fn)]
    pub fn ppu_snapshot(&self) -> PpuDebugView {
        let ppu = self.bus.ppu();
        let regs = ppu.debug_registers();
        let (v, t, fine_x, w) = ppu.debug_scroll();
        PpuDebugView {
            dot: ppu.dot(),
            scanline: ppu.scanline(),
            frame: ppu.frame(),
            ctrl: regs[0],
            mask: regs[1],
            status: regs[2],
            oam_addr: regs[3],
            v,
            t,
            fine_x,
            w_toggle: w,
            sprite_size_16: ppu.sprite_size_16(),
            bg_pattern_base: ppu.bg_pattern_base(),
            sprite_pattern_base: ppu.sprite_pattern_base(),
            nmi_line: ppu.nmi_line(),
        }
    }

    /// Snapshot APU channel outputs and IRQ flags.
    #[must_use]
    pub fn apu_snapshot(&self) -> ApuDebugView {
        let apu = self.bus.apu();
        ApuDebugView {
            pulse1: apu.pulse1_out(),
            pulse2: apu.pulse2_out(),
            triangle: apu.triangle_out(),
            noise: apu.noise_out(),
            dmc: apu.dmc_out(),
            external: apu.external_out(),
            frame_irq: apu.frame_irq_pending(),
            dmc_irq: apu.dmc_irq_pending(),
        }
    }

    /// Set the APU per-channel enable mask (a UI playback overlay, NOT NES
    /// hardware state). Bit 0 = pulse 1, 1 = pulse 2, 2 = triangle, 3 = noise,
    /// 4 = DMC, 5 = external/mapper audio. A cleared bit mutes that channel.
    ///
    /// The default ([`rustynes_apu::CHANNEL_MASK_ALL`]) is byte-identical to
    /// the un-masked mixer — the deterministic per-frame audio is unchanged
    /// unless the frontend explicitly mutes a channel. This is never written
    /// into the save state, so it never affects determinism or round-trips.
    pub const fn set_apu_channel_mask(&mut self, mask: u8) {
        self.bus.apu_mut().set_channel_mask(mask);
    }

    /// Current APU per-channel enable mask. See [`Self::set_apu_channel_mask`].
    #[must_use]
    pub const fn apu_channel_mask(&self) -> u8 {
        self.bus.apu().channel_mask()
    }

    /// v1.4.0 Workstream C — set the APU per-channel output gain (a UI mixing
    /// overlay, NOT NES hardware state), generalizing [`Self::set_apu_channel_mask`].
    /// Index 0 = pulse 1, 1 = pulse 2, 2 = triangle, 3 = noise, 4 = DMC,
    /// 5 = external/mapper audio. Each gain is clamped to `0.0..=2.0`.
    ///
    /// The default ([`rustynes_apu::CHANNEL_GAIN_UNITY`], all `1.0`) is
    /// byte-identical to the un-scaled mixer — the deterministic per-frame audio
    /// is unchanged unless the frontend explicitly changes a gain. Never written
    /// into the save state, so it never affects determinism or round-trips.
    pub fn set_apu_channel_gain(&mut self, gain: [f32; 6]) {
        self.bus.apu_mut().set_channel_gain(gain);
    }

    /// v2.1.3 — select the APU analog output-filter model (see
    /// [`rustynes_apu::FilterModel`]). The default
    /// [`rustynes_apu::FilterModel::NesRf`] (NES front-loader: 90 + 440 Hz HPF +
    /// 14 kHz LPF) is byte-identical to the pre-v2.1.3 output; `Famicom` (37 Hz
    /// HPF) and `Clean` (~10 Hz DC-block) drop the aggressive 440 Hz high-pass
    /// for a fuller low end. Tonal only — channel content is unchanged, and the
    /// model is never written into the save state (a frontend/config concern,
    /// re-applied at load), so determinism and round-trips are unaffected.
    pub fn set_apu_filter_model(&mut self, model: rustynes_apu::FilterModel) {
        self.bus.apu_mut().set_filter_model(model);
    }

    /// v2.9.8 — the APU analog output-filter model last selected with
    /// [`Self::set_apu_filter_model`] (the default until one is). Survives a
    /// [`Self::power_cycle`].
    #[must_use]
    pub const fn apu_filter_model(&self) -> rustynes_apu::FilterModel {
        self.bus.apu().filter_model()
    }

    /// Current APU per-channel output gain. See [`Self::set_apu_channel_gain`].
    #[must_use]
    pub const fn apu_channel_gain(&self) -> [f32; 6] {
        self.bus.apu().channel_gain()
    }

    /// Borrow OAM (256 bytes = 64 sprites x 4 bytes).
    ///
    /// Returns a cloned `[u8; 256]` so the caller doesn't have to manage
    /// a borrow lifetime against `&self`.
    #[must_use]
    pub fn oam(&self) -> [u8; 256] {
        let mut out = [0u8; 256];
        let oam = self.bus.ppu().oam();
        out.copy_from_slice(&oam[..256]);
        out
    }

    /// One OAM byte (`index` = `0..=255`), without copying the whole 256-byte
    /// array — for single-byte readers (e.g. the Lua `memory:read_oam`) that
    /// would otherwise pay a full `oam()` copy per access. Read-only.
    #[must_use]
    pub fn oam_byte(&self, index: u8) -> u8 {
        self.bus.ppu().oam()[index as usize]
    }

    /// Borrow palette RAM (32 bytes).
    #[must_use]
    pub const fn palette_ram(&self) -> [u8; 32] {
        *self.bus.ppu().palette_ram()
    }

    /// v1.1.0 beta.1 — install (`Some`) or clear (`None`) a custom 64-entry base
    /// palette loaded from a `.pal` file. A frontend presentation override: it
    /// re-tints the displayed RGBA framebuffer via the PPU's colour LUT but does
    /// not touch any logical core state. `None` (the default) is byte-identical to
    /// the built-in palette, so `AccuracyCoin` + the commercial oracle (which never
    /// set one) are unaffected. Not part of the save-state.
    pub const fn set_custom_palette(&mut self, base: Option<[[u8; 3]; 64]>) {
        self.bus.set_custom_palette(base);
    }

    /// v2.9.8 — the custom base palette installed by
    /// [`Self::set_custom_palette`], or `None` for the built-in one. Survives a
    /// [`Self::power_cycle`].
    #[must_use]
    pub const fn custom_palette(&self) -> Option<[[u8; 3]; 64]> {
        self.bus.ppu().custom_palette()
    }

    /// v1.7.0 "Forge" Workstream F3 — set the PPU extra-scanlines overclock: the
    /// number of EXTRA idle vblank scanlines the PPU inserts per frame (at the
    /// existing dot resolution, Mesen2 `UpdateTimings`). Each extra line is pure
    /// additional CPU run-time — it renders nothing, sets/clears no PPU flag, and
    /// fires no VBL/NMI/A12 event, so the visible image is unchanged. `0` (the
    /// default) is **byte-identical** to stock NES timing — `AccuracyCoin`, the
    /// commercial oracle, and nestest (which never set it) are unaffected.
    /// **Off by default**; a frontend config knob, not part of the save-state.
    /// Distinct from the CPU-multiplier overclock ([`Self::set_cpu_overclock`],
    /// v3.1.0), which shortens the CPU cycle instead of lengthening the frame.
    ///
    /// Clamped to [`MAX_EXTRA_SCANLINES`] (v2.9.9, NC-11): the cap used to
    /// live only in the desktop frontend, so a movie's options record could
    /// set 65,535 lines and leave every `run_frame` ending on its cycle
    /// budget with no frame.
    pub const fn set_extra_scanlines(&mut self, lines: u16) {
        let lines = if lines > MAX_EXTRA_SCANLINES {
            MAX_EXTRA_SCANLINES
        } else {
            lines
        };
        self.bus.set_extra_scanlines(lines);
    }

    /// v3.1.0 (`T-CPU-OVERCLOCK`, FE-01) — set the CPU-multiplier overclock:
    /// the CPU runs `k` times faster against an unchanged PPU, so a game gets
    /// `k` times the CPU time per frame.
    ///
    /// It splits the region's master-clock CPU divider into `k` cycles whose
    /// lengths sum to exactly one stock cycle (NTSC 12 -> 6 / 4 / 3; PAL 16 at
    /// `x3` is 5, 5, 6 and Dendy 15 at `x4` is 3, 4, 4, 4), so the multiplier is
    /// exact on every region. Until the v3.1.0 review it divided with integer
    /// division, which made PAL `x3` run x3.2 and Dendy `x4` x5. The APU, the
    /// DMC, every mapper's CPU-cycle hook (the VRC / FME-7 / N163 IRQ
    /// counters) and the PPU's open-bus and post-reset timers stay at the
    /// STOCK rate, so the pitch, the music tempo and the cycle-timed raster
    /// IRQs are unchanged: what speeds up is the game's own code. DMA follows
    /// the APU's get/put phase, so a DMA takes about `k` times as many CPU
    /// cycles and the same real time.
    ///
    /// `1` (the default) is stock and byte-identical to a build without the
    /// option. `0` is treated as `1`, and values above [`MAX_CPU_OVERCLOCK`]
    /// clamp to it. Configuration, not save-state: the host re-applies it,
    /// and movies and netplay carry it in [`crate::HardwareOptions`]. Not
    /// hardware behaviour: no real console runs its CPU faster than its APU.
    pub const fn set_cpu_overclock(&mut self, k: u8) {
        let k = if k == 0 {
            1
        } else if k > MAX_CPU_OVERCLOCK {
            MAX_CPU_OVERCLOCK
        } else {
            k
        };
        self.bus.set_cpu_overclock(k);
    }

    /// v3.1.0 — the CPU-multiplier overclock (`1` = stock).
    #[must_use]
    pub const fn cpu_overclock(&self) -> u8 {
        self.bus.cpu_overclock()
    }

    /// v3.1.0 (`T-SPRITE-LIMIT`, FE-02) — draw the sprites beyond the eighth
    /// on a scanline, removing sprite flicker.
    ///
    /// **Render-only.** Sprite evaluation, secondary OAM, the overflow flag,
    /// sprite-0 hit and every real sprite fetch (with its A12 edges, which an
    /// MMC3 counts) are exactly stock, so the game sees no difference; only
    /// the picture does. The extra sprites draw behind all eight hardware ones.
    /// On the boards whose CHR reads have an effect (MMC2, MMC4, the J.Y.
    /// ASIC, Bandai 96, Nanjing 163; `Mapper::chr_reads_are_pure`) the option
    /// draws eight, as stock, because the extra pattern reads would change
    /// emulation there.
    ///
    /// Off by default. Configuration, not save-state; carried across a power
    /// cycle, and in movies and netplay by [`crate::HardwareOptions`] (the
    /// picture differs, so a movie's frame hashes and a netplay peer's desync
    /// checks depend on it).
    pub const fn set_sprite_limit_disabled(&mut self, disabled: bool) {
        self.bus.set_sprite_limit_disabled(disabled);
    }

    /// v3.1.0 — whether the sprites beyond the eighth are drawn.
    #[must_use]
    pub const fn sprite_limit_disabled(&self) -> bool {
        self.bus.sprite_limit_disabled()
    }

    /// v3.1.0 (`T-MMC3-NEC-OVERRIDE`, ACC-13) — run an MMC3 (mapper 4) under
    /// a chosen IRQ revision, or `None` for the one its header selects.
    ///
    /// The MMC3's two IRQ behaviours are mutually exclusive: the Sharp MMC3B
    /// / MMC3C (the default) asserts IRQ whenever a clock leaves the counter at
    /// 0 with IRQs enabled, so a latch of 0 fires every scanline. The MMC3A
    /// and non-Sharp MMC3B (`Mmc3Revision::Nec`) assert on a 1 -> 0 decrement
    /// and on a `$C001` reload to 0 (one IRQ per `$C001` write while `$C000`
    /// is 0, even if the counter was already 0), but not when the counter,
    /// already 0, reloads 0 by itself. A NES 2.0 header can say which (submapper 4); an iNES 1.0
    /// dump cannot, so this override is how a player runs a game, or blargg's
    /// `mmc3_test_2/6-MMC3_alt`, on the other chip. The default (`None`) is
    /// unchanged. Configuration, re-applied when a power cycle rebuilds the
    /// board, and carried in [`crate::HardwareOptions`]. Returns whether the
    /// board is one that applies it.
    pub fn set_mmc3_revision_override(
        &mut self,
        revision: Option<rustynes_mappers::Mmc3Revision>,
    ) -> bool {
        self.bus.set_mmc3_revision_override(revision)
    }

    /// v3.1.0 — the forced MMC3 IRQ revision (`None` = the header's).
    #[must_use]
    pub const fn mmc3_revision_override(&self) -> Option<rustynes_mappers::Mmc3Revision> {
        self.bus.mmc3_revision_override()
    }

    /// v1.7.0 F3 — the configured extra-scanline overclock count (`0` = stock).
    #[must_use]
    pub const fn extra_scanlines(&self) -> u16 {
        self.bus.extra_scanlines()
    }

    /// v2.1.8 A1 — enable or disable the specialized visible-scanline fast dot
    /// path (a pure performance optimization for the PPU's hottest per-dot
    /// case).
    ///
    /// The PPU dot FSM (`Ppu::tick`) is the emulator's single hottest function
    /// (~46% of a representative frame's self-time). This knob dispatches the
    /// common "clean" visible BG-render dots (visible scanline, dots `1..=256`,
    /// rendering stably enabled, no sub-dot disturbance) to a straight-line
    /// handler that runs the identical helper sequence with the statically-dead
    /// event branches pruned. **On by default since v2.2.3** (OFF through
    /// v2.2.2) and **byte-identical** to the exact path — proven bit-for-bit
    /// every frame by the differential test (`fast_dotloop_diff`) and the full
    /// `AccuracyCoin` / visual-regression / nestest oracle, and measured at
    /// **-11.3%** on the rendering-heavy `full_frame` bench. Setting it `false`
    /// selects the fully-general per-dot path and remains the fallback. A
    /// frontend/config knob, NOT part of the save-state.
    pub const fn set_fast_dotloop(&mut self, enabled: bool) {
        self.bus.set_fast_dotloop(enabled);
    }

    /// v2.1.8 A1 — whether the visible-scanline fast dot path is enabled
    /// (`true` = default since v2.2.3; both settings produce identical frames).
    #[must_use]
    pub const fn fast_dotloop(&self) -> bool {
        self.bus.fast_dotloop()
    }

    /// v2.1.4 F2.3 — enable or disable the optional OAM-decay accuracy model.
    ///
    /// The 2C02's OAM is dynamic RAM refreshed by sprite evaluation; with rendering
    /// disabled for a while its un-refreshed 8-byte rows decay to a fixed garbage
    /// pattern. This models that (à la Mesen2's `EnableOamDecay`): a row un-touched
    /// for > 3000 CPU cycles decays on the next read. **Off by default** and
    /// **byte-identical** to a decay-free core when off — `AccuracyCoin`, the
    /// commercial oracle, and the visual regression suites are unaffected. It is
    /// NTSC/Dendy-only (PAL's refresh cadence masks decay). Deterministic when on
    /// (driven off the PPU's monotonic dot counter — no wall-clock / OS RNG), and a
    /// frontend/config knob re-applied on load, NOT part of the save-state (the
    /// in-flight per-row ages are serialized as a relative age so a rollback stays
    /// deterministic; the enable flag is not).
    pub const fn set_oam_decay(&mut self, enabled: bool) {
        self.bus.set_oam_decay(enabled);
    }

    /// v2.1.4 F2.3 — whether the optional OAM-decay model is enabled (`false` =
    /// default, byte-identical to a decay-free core).
    #[must_use]
    pub const fn oam_decay_enabled(&self) -> bool {
        self.bus.oam_decay_enabled()
    }

    /// v2.1.7 P5 — select the emulated 2C02 die revision (see [`PpuRevision`]).
    ///
    /// The [`PpuRevision::default`] ([`PpuRevision::Rp2c02H`]) models no extra
    /// quirks, so at the default this is inert and the core is **byte-identical**
    /// to a build without it — `AccuracyCoin`, the commercial oracle, and the
    /// visual / audio regression suites are unaffected. Selecting
    /// [`PpuRevision::Rp2c02G`] additionally models the OAMADDR (`$2003`)
    /// write-during-rendering OAM corruption glitch (*Huge Insect*). The
    /// selection is stored so a power-cycle re-applies it; it is config, not
    /// save-state (the corruption *state* it can arm already round-trips via the
    /// v6 PPU snapshot tail). Deterministic. A frontend/config knob re-applied on
    /// load, mirroring [`Nes::set_oam_decay`].
    pub const fn set_ppu_revision(&mut self, revision: PpuRevision) {
        self.bus.set_ppu_revision(revision);
    }

    /// v2.1.7 P5 — the currently-selected 2C02 die revision (default
    /// [`PpuRevision::Rp2c02H`], byte-identical).
    #[must_use]
    pub const fn ppu_revision(&self) -> PpuRevision {
        self.bus.ppu_revision()
    }

    /// v2.9.8 — select the console whose reset wiring is modelled (see
    /// [`ConsoleModel`]).
    ///
    /// The selection is stored, so every later [`Nes::power_cycle`] and
    /// [`Nes::reset`] follows it. It also takes effect at once in one respect:
    /// selecting [`ConsoleModel::Famicom`] ends any PPU warm-up still in
    /// progress, because a Famicom's PPU is never held in reset while its CPU
    /// runs. A host that applies its configuration straight after building the
    /// machine (as the frontend does on every ROM load and power-cycle) thereby
    /// gets the Famicom power-on. Selecting [`ConsoleModel::Nes`] never re-arms
    /// a window that has already closed; it applies from the next reset.
    ///
    /// [`ConsoleModel::Nes`] is the default and is byte-identical to every
    /// earlier release. Deterministic; config, not save-state.
    pub const fn set_console_model(&mut self, model: ConsoleModel) {
        self.bus.set_console_model(model);
    }

    /// v2.9.8 — the currently-selected console reset wiring (default
    /// [`ConsoleModel::Nes`], byte-identical).
    #[must_use]
    pub const fn console_model(&self) -> ConsoleModel {
        self.bus.console_model()
    }

    /// v2.1.7 P5 — apply a power-up palette-RAM pattern (see [`PaletteInit`]).
    ///
    /// The 2C02's palette RAM is not cleared at power-on; this selects the
    /// power-up contents. [`PaletteInit::default`] ([`PaletteInit::Zeroed`])
    /// keeps the established all-zero power-up palette, so at the default this is
    /// **byte-identical**. [`PaletteInit::Blargg`] loads the canonical blargg
    /// power-up dump for software that samples uninitialized palette RAM. Writes
    /// only palette RAM (already part of the snapshot), so no snapshot change is
    /// needed; the selection is stored so a power-cycle re-applies it. Best
    /// called at power-on (palette RAM is preserved across a warm reset, like
    /// real hardware).
    pub const fn set_power_up_palette(&mut self, init: PaletteInit) {
        self.bus.set_power_up_palette(init);
    }

    /// v2.1.7 P5 — the currently-selected power-up palette pattern (default
    /// [`PaletteInit::Zeroed`], byte-identical).
    #[must_use]
    pub const fn power_up_palette(&self) -> PaletteInit {
        self.bus.power_up_palette()
    }

    /// v2.1.7 P5 — select the power-on work-RAM fill (see [`PowerOnRam`]).
    ///
    /// Applies the fill to the current 2 KiB work RAM (and open-bus latch)
    /// immediately and stores it so a power-cycle re-applies the same fill
    /// (`power_cycle == fresh boot`). [`PowerOnRam::default`]
    /// ([`PowerOnRam::Zeroed`]) is the established all-zero power-up state
    /// (**byte-identical**); the other variants are opt-in and deterministic,
    /// surfacing software that reads uninitialized RAM (*Final Fantasy* RNG,
    /// *River City Ransom*, *Cybernoid*). RAM is not consulted during reset, so
    /// applying it here is safe.
    pub fn set_power_on_ram(&mut self, ram: PowerOnRam) {
        self.bus.set_power_on_ram(ram);
    }

    /// v2.1.7 P5 — the currently-selected power-on work-RAM fill (default
    /// [`PowerOnRam::Zeroed`], byte-identical).
    #[must_use]
    pub const fn power_on_ram(&self) -> PowerOnRam {
        self.bus.power_on_ram()
    }

    /// v2.1.7 "Hardware Revisions & DMA Frontier" — select the emulated Ricoh
    /// 2A03 die revision, which gates the DMA unit's "unexpected DMA" extra
    /// halt-read on the DMC-halt-overlaps-OAM-halt cycle.
    ///
    /// **[`Cpu2A03Revision::Rp2A03G`] is the default** and is byte-identical to
    /// the core as it shipped before v2.1.7 (`AccuracyCoin` 141/141, nestest
    /// 0-diff, every committed DMA oracle ROM `Passed`).
    /// [`Cpu2A03Revision::Rp2A03H`] is a purely additive, opt-in accuracy knob
    /// that omits the extra read; its direction is an **unverified hypothesis**
    /// (no public reference emulator or test ROM models the 2A03 die-revision
    /// DMA difference — see the type docs and ADR 0033). It is deterministic and
    /// a config knob re-applied on load, NOT part of the save-state.
    pub const fn set_cpu_2a03_revision(&mut self, revision: Cpu2A03Revision) {
        self.bus.set_cpu_2a03_revision(revision);
    }

    /// v2.1.7 — the configured 2A03 die revision (default
    /// [`Cpu2A03Revision::Rp2A03G`], byte-identical to the pre-v2.1.7 core).
    #[must_use]
    pub const fn cpu_2a03_revision(&self) -> Cpu2A03Revision {
        self.bus.cpu_2a03_revision()
    }

    /// Mapper debug info (bank registers, IRQ counters, mirroring, ...).
    #[must_use]
    pub fn mapper_info(&self) -> MapperDebugView {
        self.bus.mapper_debug_info()
    }

    /// v1.4.0 Workstream C — the loaded mapper's on-cart expansion-audio chip
    /// name (e.g. `"VRC6"`, `"VRC7 (OPLL)"`, `"MMC5"`, `"Namco 163"`,
    /// `"Sunsoft 5B"`, `"FDS"`), or `None` when the board has no expansion audio
    /// (or the `mapper-audio` feature is compiled out). Used by the frontend to
    /// show the expansion-channel volume slider only when present, with a label.
    ///
    /// Discovery is dynamic: it consults the cached [`rustynes_mappers::MapperCaps`]
    /// `audio` flag (true only when the mapper overrides `mix_audio` with the
    /// feature on) and the mapper id to name the chip family.
    #[must_use]
    pub const fn expansion_audio_chip(&self) -> Option<&'static str> {
        if !self.bus.mapper_caps().audio {
            return None;
        }
        // The cartridge's id, not the debug view's (v2.9.8, see `mapper_id`).
        // Every board that overrides `mix_audio` also names its id in
        // `debug_info` today, so no label changes; the debug view simply is
        // not the place the mapper id is defined.
        Some(match self.mapper_id() {
            5 => "MMC5",
            19 | 210 => "Namco 163",
            20 => "FDS",
            24 | 26 => "VRC6",
            69 => "Sunsoft 5B",
            85 => "VRC7 (OPLL)",
            // The board overrides `mix_audio` but isn't one of the named
            // families above — surface a generic label so the slider still
            // appears (e.g. a future expansion-audio mapper).
            _ => "Expansion audio",
        })
    }

    /// Side-effect-free CPU bus peek (for the hex viewer).
    pub fn cpu_bus_peek(&mut self, addr: u16) -> u8 {
        self.bus.debug_peek_cpu(addr)
    }

    /// Side-effect-free PPU bus peek (for the hex viewer + visualizers).
    pub fn ppu_bus_peek(&mut self, addr: u16) -> u8 {
        self.bus.debug_peek_ppu(addr)
    }

    /// Render the 256 tiles of a CHR pattern table as RGBA8 (128x128).
    ///
    /// `table` selects which of the two pattern tables: 0 -> `$0000`,
    /// 1 -> `$1000`. Uses BG palette 0 ($3F00-$3F03) for grayscale-ish
    /// rendering. ~80 KiB cloned; only call when the PPU pattern viewer
    /// is open.
    pub fn pattern_table_rgba(&mut self, table: u8) -> Vec<u8> {
        const TILE_W: usize = 8;
        const SHEET_W: usize = 128;
        const SHEET_H: usize = 128;
        let base: u16 = if table & 1 == 0 { 0 } else { 0x1000 };
        let mut out = vec![0u8; SHEET_W * SHEET_H * 4];
        for tile_y in 0..16u16 {
            for tile_x in 0..16u16 {
                let tile_index = tile_y * 16 + tile_x;
                for row in 0..8u16 {
                    let lo = self.ppu_bus_peek(base + tile_index * 16 + row);
                    let hi = self.ppu_bus_peek(base + tile_index * 16 + row + 8);
                    for col in 0..8u16 {
                        let bit = 7 - col;
                        let p = ((hi >> bit) & 1) << 1 | ((lo >> bit) & 1);
                        let palette_byte = self.ppu_bus_peek(0x3F00 + u16::from(p));
                        let rgba = rustynes_ppu::nes_color_to_rgba(palette_byte & 0x3F);
                        let px = usize::from(tile_x) * TILE_W + usize::from(col);
                        let py = usize::from(tile_y) * TILE_W + usize::from(row);
                        let off = (py * SHEET_W + px) * 4;
                        out[off..off + 4].copy_from_slice(&rgba);
                    }
                }
            }
        }
        out
    }

    /// Render a nametable as RGBA8 (256x240).
    ///
    /// `nt` selects 0..=3 logical nametable. Uses the current
    /// BG pattern table base, attribute palette, and CHR data.
    pub fn nametable_rgba(&mut self, nt: u8) -> Vec<u8> {
        const FB_W: usize = 256;
        const FB_H: usize = 240;
        let nt = nt & 0x03;
        let nt_base = 0x2000u16 + u16::from(nt) * 0x400;
        let attr_base = nt_base + 0x3C0;
        let bg_base = self.bus.ppu().bg_pattern_base();
        let mut out = vec![0u8; FB_W * FB_H * 4];
        for ty in 0..30u16 {
            for tx in 0..32u16 {
                let nt_addr = nt_base + ty * 32 + tx;
                let tile_idx = self.ppu_bus_peek(nt_addr);
                let attr_addr = attr_base + (ty / 4) * 8 + (tx / 4);
                let attr_byte = self.ppu_bus_peek(attr_addr);
                let shift = ((ty & 2) << 1) | (tx & 2);
                let palette = u16::from((attr_byte >> shift) & 0x03);
                for row in 0..8u16 {
                    let lo = self.ppu_bus_peek(bg_base + u16::from(tile_idx) * 16 + row);
                    let hi = self.ppu_bus_peek(bg_base + u16::from(tile_idx) * 16 + row + 8);
                    for col in 0..8u16 {
                        let bit = 7 - col;
                        let p = ((hi >> bit) & 1) << 1 | ((lo >> bit) & 1);
                        let final_idx = if p == 0 {
                            self.ppu_bus_peek(0x3F00)
                        } else {
                            self.ppu_bus_peek(0x3F00 + palette * 4 + u16::from(p))
                        };
                        let rgba = rustynes_ppu::nes_color_to_rgba(final_idx & 0x3F);
                        let px = usize::from(tx * 8 + col);
                        let py = usize::from(ty * 8 + row);
                        let off = (py * FB_W + px) * 4;
                        out[off..off + 4].copy_from_slice(&rgba);
                    }
                }
            }
        }
        out
    }
}

/// The persistent identity of a cartridge image: SHA-256 of everything after
/// the 16-byte iNES / NES 2.0 header, or of the whole image when the `NES\x1A`
/// magic is absent. See [`Nes::rom_sha256`].
fn rom_identity_sha256(bytes: &[u8]) -> [u8; 32] {
    match bytes {
        [b'N', b'E', b'S', 0x1A, ..] if bytes.len() >= 16 => sha256_of(&bytes[16..]),
        _ => sha256_of(bytes),
    }
}

fn sha256_of(bytes: &[u8]) -> [u8; 32] {
    let mut h = Sha256::new();
    h.update(bytes);
    let out = h.finalize();
    let mut a = [0u8; 32];
    a.copy_from_slice(&out);
    a
}

#[cfg(test)]
mod tests {
    use super::*;

    /// 16-byte iNES header for a synthetic NROM ROM with `prg_kib`/`chr_kib`
    /// content, vertical mirroring.
    fn synth_nrom(prg_kib: usize, chr_kib: usize) -> Vec<u8> {
        let mut bytes = Vec::with_capacity(16 + prg_kib * 1024 + chr_kib * 1024);
        bytes.extend_from_slice(b"NES\x1A");
        bytes.push(u8::try_from(prg_kib / 16).unwrap());
        bytes.push(u8::try_from(chr_kib / 8).unwrap());
        bytes.push(0); // flags6
        bytes.push(0); // flags7
        bytes.extend_from_slice(&[0u8; 8]);

        // PRG payload: a tiny program at $C000 that loops forever (JMP $C000).
        // Since the reset vector reads $FFFC/D, we set those bytes too.
        let mut prg = vec![0u8; prg_kib * 1024];
        if prg_kib >= 16 {
            // 16 KiB PRG: $C000-$FFFF maps to bytes 0..$4000 of PRG.
            // JMP $C000 -> $4C $00 $C0
            prg[0] = 0x4C;
            prg[1] = 0x00;
            prg[2] = 0xC0;
            // Reset vector at $FFFC/D = end-of-PRG offsets.
            let len = prg.len();
            prg[len - 4] = 0x00;
            prg[len - 3] = 0xC0;
            // NMI vector at $FFFA/B: same.
            prg[len - 6] = 0x00;
            prg[len - 5] = 0xC0;
            // IRQ vector at $FFFE/F: same.
            prg[len - 2] = 0x00;
            prg[len - 1] = 0xC0;
        }
        bytes.extend_from_slice(&prg);
        bytes.extend_from_slice(&vec![0u8; chr_kib * 1024]);
        bytes
    }

    /// Synthetic NES 2.0 NROM with console type Vs. System and a byte-13 Vs.
    /// PPU type (low nibble).
    fn synth_vs_nrom(vs_ppu_low_nibble: u8) -> Vec<u8> {
        let mut rom = synth_nrom(16, 8);
        // Upgrade the header to NES 2.0 + console type Vs. System.
        rom[7] = 0x09; // bits 2-3 = 10 (NES 2.0), bits 0-1 = 01 (Vs. System)
        rom[13] = vs_ppu_low_nibble & 0x0F;
        rom
    }

    #[test]
    fn a_restored_cpu_ppu_clock_skew_is_rejected() {
        // v2.7.0: the fuzz target's first timeout. A `ppu_clock` restored far
        // from the CPU's `master_clock` made the next catch-up tick billions of
        // dots (behind) or never tick at all (ahead) -- a hang either way.
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).unwrap();
        nes.run_frame();
        let master = nes.cpu.master_clock();
        let live = nes.bus().ppu_clock_for_test();
        let live_skew = master.abs_diff(live);
        assert!(
            live_skew <= SystemBus::RESTORED_CLOCK_SKEW_MAX,
            "the running machine's own skew ({live_skew}) must be inside the bound"
        );
        assert!(
            Nes::from_rom(&rom)
                .unwrap()
                .restore_quiet(&nes.snapshot())
                .is_ok()
        );

        // Measured: a frame of this ROM leaves the pair a handful of master
        // clocks apart (4 at the time of writing), and `master_clock` itself
        // small, so the "behind" direction is exercised by moving the PPU
        // clock only as far as zero allows and the "ahead" direction carries
        // the bound.
        let max = SystemBus::RESTORED_CLOCK_SKEW_MAX;
        for (label, ppu_clock, ok) in [
            ("behind, as far as zero", master.saturating_sub(max), true),
            ("at the bound, ahead", master + max, true),
            ("past the bound, ahead", master + max + 1, false),
            ("far ahead", master + (1 << 40), false),
            ("u64::MAX", u64::MAX, false),
        ] {
            nes.bus_mut().set_ppu_clock_for_test(ppu_clock);
            let blob = nes.snapshot();
            let got = Nes::from_rom(&rom).unwrap().restore_quiet(&blob);
            assert_eq!(got.is_ok(), ok, "{label}: {got:?}");
        }
    }

    /// v2.9.0 re-audit NC-04: the clock check bounds the ABSOLUTE clocks, not
    /// only their skew.
    ///
    /// F-05's check accepted any pair within `RESTORED_CLOCK_SKEW_MAX` of each
    /// other, so a crafted state with BOTH clocks ~20,000 master clocks below
    /// 2^64 loaded. The CPU advances with `wrapping_add`, so its clock wrapped
    /// to a small value within a frame while the PPU's stayed near 2^64, and
    /// the catch-up loop (`while ppu_clock + div <= target`) never ran again:
    /// the frame counter froze, NMI never fired — the exact state F-05 set out
    /// to reject. Both clocks are shifted by the same amount here, so the skew
    /// is the running machine's own and only the new ceiling can reject it.
    #[test]
    fn restored_clocks_near_the_top_of_u64_are_rejected() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).unwrap();
        nes.run_frame();
        nes.run_frame();
        let master = nes.cpu.master_clock();
        let ppu = nes.bus().ppu_clock_for_test();

        // Shift both clocks by `shift` and return the snapshot. The CPU clock
        // has no setter, so its bytes are patched inside the CPU section's
        // body, where they must occur exactly once.
        let shifted = |nes: &mut Nes, shift: u64| {
            nes.bus_mut().set_ppu_clock_for_test(ppu + shift);
            let mut blob = nes.snapshot();
            let (_h, body_off) = save_state::parse_header(&blob).unwrap();
            let cpu_body_off = {
                let s = save_state::SectionIter::new(&blob[body_off..])
                    .map(Result::unwrap)
                    .find(|s| s.tag == save_state::tag::CPU)
                    .unwrap();
                s.body.as_ptr() as usize - blob.as_ptr() as usize
            };
            let needle = master.to_le_bytes();
            let hits: Vec<usize> = (cpu_body_off..blob.len() - 8)
                .filter(|&o| blob[o..o + 8] == needle)
                .collect();
            assert_eq!(hits.len(), 1, "master_clock must occur once: {hits:?}");
            blob[hits[0]..hits[0] + 8].copy_from_slice(&(master + shift).to_le_bytes());
            nes.bus_mut().set_ppu_clock_for_test(ppu);
            blob
        };

        let ceiling = SystemBus::RESTORED_CLOCK_MAX;
        for (label, shift, ok) in [
            ("unshifted", 0, true),
            (
                "a century of emulation",
                100 * 365 * 86_400 * 21_477_272,
                true,
            ),
            ("at the ceiling", ceiling - master.max(ppu), true),
            ("past the ceiling", ceiling - master.max(ppu) + 1, false),
            (
                "20,000 master clocks below 2^64",
                u64::MAX - 20_000 - master,
                false,
            ),
        ] {
            let blob = shifted(&mut nes, shift);
            let mut fresh = Nes::from_rom(&rom).unwrap();
            let got = fresh.restore_quiet(&blob);
            assert_eq!(got.is_ok(), ok, "{label}: {got:?}");
            if ok {
                // An accepted state must actually run: the frame counter moves.
                let f = fresh.frame();
                fresh.run_frame();
                fresh.run_frame();
                assert!(fresh.frame() > f, "{label}: the PPU stopped");
            }
        }
    }

    #[test]
    fn nes_cart_4016_read_is_byte_identical_with_and_without_vs_inputs() {
        // On a normal NES cart the Vs. DIP/coin/service overlay is a no-op, so
        // a $4016/$4017 read is byte-for-byte identical regardless of the Vs.
        // input state. Compare two freshly-built buses in lockstep.
        let rom = synth_nrom(16, 8);
        let mut a = Nes::from_rom(&rom).unwrap();
        let mut b = Nes::from_rom(&rom).unwrap();
        assert!(!a.is_vs_system());
        // Crank the Vs. inputs on `b` only.
        b.set_vs_dip(0xFF);
        b.insert_coin(0);
        b.insert_coin(1);
        b.set_vs_service(true);
        for addr in [0x4016u16, 0x4017, 0x4016, 0x4017] {
            assert_eq!(
                a.bus_mut().raw_cpu_read(addr),
                b.bus_mut().raw_cpu_read(addr),
                "Vs. inputs leaked into a normal-cart read of {addr:#06X}"
            );
        }
    }

    /// v1.6.0 Workstream A3 — the `TAStudio` lag-log flag: a frame in which the
    /// program never reads `$4016`/`$4017` is a lag frame; a controller read
    /// marks the frame polled; and the flag resets at the top of each frame.
    #[cfg(feature = "debug-hooks")]
    #[test]
    fn lag_flag_tracks_controller_reads_per_frame() {
        // synth_nrom is a pure `JMP $C000` loop — it never polls input.
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).unwrap();

        // A frame of pure JMP never reads a controller port => lag frame.
        nes.run_frame();
        assert!(
            !nes.was_input_polled_this_frame(),
            "a frame with no $4016/$4017 read must be a lag frame"
        );

        // A controller-port read marks the (current) frame as polled.
        let _ = nes.bus_mut().raw_cpu_read(0x4016);
        assert!(
            nes.was_input_polled_this_frame(),
            "a $4016 read must mark the frame polled"
        );

        // $4017 also counts, and the next frame's clear resets the flag.
        nes.run_frame();
        assert!(
            !nes.was_input_polled_this_frame(),
            "the flag must reset at the top of each frame"
        );
        let _ = nes.bus_mut().raw_cpu_read(0x4017);
        assert!(
            nes.was_input_polled_this_frame(),
            "a $4017 read must also mark the frame polled"
        );
    }

    #[test]
    fn vs_dip_switches_read_through_4016_and_4017() {
        // 2C03 Vs. cart (low nibble 0).
        let rom = synth_vs_nrom(0x0);
        let mut nes = Nes::from_rom(&rom).unwrap();
        assert!(nes.is_vs_system());
        // DIP = 0b1010_1010: sw2,4,6,8 on; sw1,3,5,7 off.
        nes.set_vs_dip(0b1010_1010);
        let v16 = nes.bus_mut().raw_cpu_read(0x4016);
        // $4016: DIP sw1 -> bit3 (off), sw2 -> bit4 (on).
        assert_eq!(v16 & 0x08, 0x00, "DIP sw1 off");
        assert_eq!(v16 & 0x10, 0x10, "DIP sw2 on");
        let v17 = nes.bus_mut().raw_cpu_read(0x4017);
        // $4017: DIP sw3..8 -> bits 2..7. DIP bits 2..7 = 0b101010.
        assert_eq!(v17 & 0xFC, 0b1010_1000 & 0xFC);
    }

    #[test]
    fn vs_coin_and_service_read_through_4016() {
        let rom = synth_vs_nrom(0x0);
        let mut nes = Nes::from_rom(&rom).unwrap();
        nes.set_vs_dip(0);
        // Coin acceptor #1 -> $4016 bit 5.
        nes.insert_coin(0);
        assert_eq!(nes.bus_mut().raw_cpu_read(0x4016) & 0x20, 0x20);
        // Acceptor #2 -> bit 6.
        nes.insert_coin(1);
        assert_eq!(nes.bus_mut().raw_cpu_read(0x4016) & 0x60, 0x60);
        nes.clear_coin();
        assert_eq!(nes.bus_mut().raw_cpu_read(0x4016) & 0x60, 0x00);
        // Service button -> bit 2.
        nes.set_vs_service(true);
        assert_eq!(nes.bus_mut().raw_cpu_read(0x4016) & 0x04, 0x04);
        nes.set_vs_service(false);
        assert_eq!(nes.bus_mut().raw_cpu_read(0x4016) & 0x04, 0x00);
    }

    #[test]
    fn game_genie_substitutes_on_cpu_read_path() {
        // 16 KiB NROM; plant the Zelda code's compare byte (0x22) at the PRG
        // address it targets ($9F41 -> $8000-$BFFF window -> PRG offset $1F41).
        let mut rom = synth_nrom(16, 8);
        rom[16 + 0x1F41] = 0x22;
        let mut nes = Nes::from_rom(&rom).expect("synthetic NROM parses");

        // No codes active: reads are the original byte (determinism contract).
        assert_eq!(nes.bus_mut().debug_peek_cpu(0x9F41), 0x22);
        assert_eq!(nes.bus_mut().peek_cpu(0x9F41), 0x22);
        assert_eq!(nes.genie_codes().count(), 0);

        // 8-char code substitutes only when the original matches compare (0x22),
        // on BOTH the production read path and the debugger peek path.
        nes.add_genie_code("YYKPOYZZ").expect("valid 8-char code");
        assert_eq!(
            nes.bus_mut().debug_peek_cpu(0x9F41),
            0x77,
            "debug peek substituted"
        );
        assert_eq!(
            nes.bus_mut().peek_cpu(0x9F41),
            0x77,
            "production read substituted"
        );
        assert_eq!(
            nes.bus_mut().debug_peek_cpu(0x9F40),
            0x00,
            "other address untouched"
        );

        // Removal (case-insensitive) restores the original byte.
        nes.remove_genie_code("yykpoyzz");
        assert_eq!(nes.bus_mut().debug_peek_cpu(0x9F41), 0x22);

        // 6-char code (no compare) always substitutes; $91D9 -> data 0xAD.
        nes.add_genie_code("SXIOPO").expect("valid 6-char code");
        assert_eq!(nes.bus_mut().debug_peek_cpu(0x91D9), 0xAD);
        nes.clear_genie_codes();
        assert_eq!(nes.bus_mut().debug_peek_cpu(0x91D9), 0x00);

        // A malformed code is rejected without mutating state.
        assert!(nes.add_genie_code("BADCODE!").is_err());
    }

    #[test]
    fn poke_ram_writes_system_ram_and_ignores_rom() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("synthetic NROM parses");
        nes.poke_ram(0x0042, 0xAB);
        assert_eq!(nes.bus_mut().debug_peek_cpu(0x0042), 0xAB);
        // Mirrored every $800 within $0000-$1FFF.
        assert_eq!(nes.bus_mut().debug_peek_cpu(0x0842), 0xAB);
        // A poke outside system RAM is a no-op (no panic; ROM space untouched).
        nes.poke_ram(0x8000, 0xFF);
        assert_ne!(nes.bus_mut().debug_peek_cpu(0x8000), 0xFF);
    }

    #[test]
    fn nes_set_buttons_then_strobe_reads_bits_in_order() {
        // T-51-005: end-to-end controller plumbing — the bus must shift the
        // latched button state out via $4016 in canonical order.
        //
        // Session-24 / Phase 3 update: `$4016` writes are deferred
        // (committed at the start of a later cycle by `Bus::cpu_clock`).
        // Direct-API callers that bypass CPU stepping must clock the bus
        // between the strobe pulse and the shift-out reads so the buffered
        // write commits. Two cycles are sufficient (one for the pending=1
        // commit, one as a margin in case the test's first write landed on
        // the pending=2 path). Until v2.9.8 these tests drove the removed
        // pre-v2.0.0 `tick_one_cpu_cycle`, which committed the strobe the
        // same way.
        use rustynes_cpu::Bus as _;
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        nes.set_buttons(0, Buttons::A | Buttons::SELECT | Buttons::DOWN);

        // Pulse the strobe latch (write 1 then 0 to $4016), driving the
        // bus enough cycles between writes for the deferred-write
        // commit to land.
        nes.bus_mut().cpu_write(0x4016, 1);
        nes.bus_mut().cpu_clock();
        nes.bus_mut().cpu_clock();
        nes.bus_mut().cpu_write(0x4016, 0);
        nes.bus_mut().cpu_clock();
        nes.bus_mut().cpu_clock();

        // 8 reads of $4016 should yield A, B, Select, Start, Up, Down, Left, Right.
        let expected = [1u8, 0, 1, 0, 0, 1, 0, 0];
        for &want in &expected {
            let v = nes.bus_mut().cpu_read(0x4016) & 1;
            assert_eq!(v, want);
        }
    }

    #[test]
    fn nes_set_buttons_port1_reads_via_4017_in_order() {
        // T-71-004 (Phase 7): player 2 plumbing. The strobe latch is shared
        // (writing `$4016` strobes BOTH pads); player 2 shifts out on `$4017`.
        // Mirrors `nes_set_buttons_then_strobe_reads_bits_in_order` for port 1.
        use rustynes_cpu::Bus as _;
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        nes.set_buttons(1, Buttons::B | Buttons::START | Buttons::RIGHT);

        nes.bus_mut().cpu_write(0x4016, 1);
        nes.bus_mut().cpu_clock();
        nes.bus_mut().cpu_clock();
        nes.bus_mut().cpu_write(0x4016, 0);
        nes.bus_mut().cpu_clock();
        nes.bus_mut().cpu_clock();

        // A, B, Select, Start, Up, Down, Left, Right.
        let expected = [0u8, 1, 0, 1, 0, 0, 0, 1];
        for (i, &want) in expected.iter().enumerate() {
            let v = nes.bus_mut().cpu_read(0x4017) & 1;
            assert_eq!(v, want, "$4017 read #{i}");
        }
    }

    #[test]
    fn nes_restrobe_relatches_current_buttons() {
        // T-71-004 (Phase 7): a fresh strobe re-samples the live button state
        // through the full bus (the per-`Controller` unit test in
        // `controller.rs` covers this at the chip level; this confirms it end
        // to end via `Nes::set_buttons` + `$4016`).
        use rustynes_cpu::Bus as _;
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");

        let strobe = |nes: &mut Nes| {
            nes.bus_mut().cpu_write(0x4016, 1);
            nes.bus_mut().cpu_clock();
            nes.bus_mut().cpu_clock();
            nes.bus_mut().cpu_write(0x4016, 0);
            nes.bus_mut().cpu_clock();
            nes.bus_mut().cpu_clock();
        };

        nes.set_buttons(0, Buttons::A);
        strobe(&mut nes);
        assert_eq!(nes.bus_mut().cpu_read(0x4016) & 1, 1, "A latched pressed");

        // Change state, then re-strobe: the new state must be visible.
        nes.set_buttons(0, Buttons::empty());
        strobe(&mut nes);
        assert_eq!(nes.bus_mut().cpu_read(0x4016) & 1, 0, "A latched released");
    }

    #[test]
    fn reading_4015_does_not_refresh_external_open_bus() {
        // T-72-006 (Phase 7): `$4015` reads return the APU status but do NOT
        // drive the external data bus (the APU status port is internal to the
        // 2A03 package). So a `$4015` read must leave the open-bus latch
        // unchanged — a subsequent open-bus-region read returns the prior
        // floating value, not the APU status. Per nesdev "Open bus behavior"
        // + AccuracyCoin `CPU Behavior :: Open Bus` Test 7.
        use rustynes_cpu::Bus as _;
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");

        // Drive a known value onto the external bus via a normal RAM read.
        nes.bus_mut().cpu_write(0x0010, 0xAB);
        assert_eq!(nes.bus_mut().cpu_read(0x0010), 0xAB);
        // $4018-$401F is open-bus region: returns (and re-latches) the value.
        assert_eq!(
            nes.bus_mut().cpu_read(0x4018),
            0xAB,
            "open-bus latch holds 0xAB"
        );

        // Read $4015 — must NOT refresh the external latch.
        let _ = nes.bus_mut().cpu_read(0x4015);

        // The latch is still 0xAB, not whatever APU status $4015 returned.
        assert_eq!(
            nes.bus_mut().cpu_read(0x4018),
            0xAB,
            "$4015 read must not drive the external data bus"
        );
    }

    #[test]
    fn nes_from_rom_constructs_and_resets() {
        let rom = synth_nrom(16, 8);
        let nes = Nes::from_rom(&rom).expect("parse + boot");
        assert_eq!(nes.cpu().pc, 0xC000);
    }

    #[test]
    fn power_on_randomization_is_opt_in_seeded_and_deterministic() {
        // T-72-005 (Phase 7): the default path leaves work RAM zeroed; the
        // seeded constructor randomizes it deterministically.
        let rom = synth_nrom(16, 8);

        // Default: RAM is zeroed.
        let mut default = Nes::from_rom(&rom).expect("parse + boot");
        for addr in (0x0000u16..0x0800).step_by(0x40) {
            assert_eq!(default.cpu_bus_peek(addr), 0, "default RAM must be zero");
        }

        // Seeded: RAM is not all-zero.
        let mut a = Nes::from_rom_with_power_on_seed(&rom, 1).expect("parse + boot");
        let dump_a: Vec<u8> = (0x0000u16..0x0100).map(|x| a.cpu_bus_peek(x)).collect();
        assert!(
            dump_a.iter().any(|&b| b != 0),
            "seeded RAM must not be all zero"
        );

        // Same seed -> identical RAM.
        let mut a2 = Nes::from_rom_with_power_on_seed(&rom, 1).expect("parse + boot");
        let dump_a2: Vec<u8> = (0x0000u16..0x0100).map(|x| a2.cpu_bus_peek(x)).collect();
        assert_eq!(
            dump_a, dump_a2,
            "same seed must yield identical power-on RAM"
        );

        // Different seed -> different RAM.
        let mut b = Nes::from_rom_with_power_on_seed(&rom, 0xDEAD_BEEF).expect("parse + boot");
        let dump_b: Vec<u8> = (0x0000u16..0x0100).map(|x| b.cpu_bus_peek(x)).collect();
        assert_ne!(dump_a, dump_b, "different seeds should differ");
    }

    #[test]
    fn power_on_config_defaults_byte_identical_and_variants_deterministic() {
        // v2.1.7 P5 — the PowerOnConfig surface. Default (Zeroed) must match the
        // plain constructor; Filled + Seeded must be deterministic and distinct.
        let rom = synth_nrom(16, 8);

        // Default config == from_rom (byte-identical work RAM).
        let mut zeroed =
            Nes::from_rom_with_power_on_config(&rom, PowerOnConfig::default()).expect("boot");
        assert_eq!(zeroed.power_on_ram(), PowerOnRam::Zeroed);
        for addr in (0x0000u16..0x0800).step_by(0x40) {
            assert_eq!(zeroed.cpu_bus_peek(addr), 0, "Zeroed config: RAM zero");
        }

        // Filled(0xFF): every work-RAM byte is 0xFF, deterministically.
        let mut filled = Nes::from_rom_with_power_on_config(
            &rom,
            PowerOnConfig {
                ram: PowerOnRam::Filled(0xFF),
            },
        )
        .expect("boot");
        assert_eq!(filled.power_on_ram(), PowerOnRam::Filled(0xFF));
        for addr in (0x0000u16..0x0800).step_by(0x40) {
            assert_eq!(filled.cpu_bus_peek(addr), 0xFF, "Filled(0xFF)");
        }

        // Seeded is deterministic and differs from Zeroed.
        let mut seeded = Nes::from_rom_with_power_on_config(
            &rom,
            PowerOnConfig {
                ram: PowerOnRam::Seeded(42),
            },
        )
        .expect("boot");
        let dump: Vec<u8> = (0x0000u16..0x0100)
            .map(|x| seeded.cpu_bus_peek(x))
            .collect();
        assert!(dump.iter().any(|&b| b != 0), "Seeded: not all zero");
    }

    #[test]
    fn ppu_revision_and_palette_default_byte_identical() {
        // v2.1.7 P5 — the PPU-revision + power-up-palette knobs default to the
        // byte-identical state, and toggling them is observable + power-cycle
        // durable.
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("boot");
        assert_eq!(nes.ppu_revision(), PpuRevision::Rp2c02H);
        assert_eq!(nes.power_up_palette(), PaletteInit::Zeroed);

        // Select the opt-in revision + Blargg palette; both must persist across a
        // power-cycle (the bus re-applies them after rebuilding the PPU).
        nes.set_ppu_revision(PpuRevision::Rp2c02G);
        nes.set_power_up_palette(PaletteInit::Blargg);
        nes.power_cycle();
        assert_eq!(
            nes.ppu_revision(),
            PpuRevision::Rp2c02G,
            "revision survives power-cycle"
        );
        assert_eq!(
            nes.power_up_palette(),
            PaletteInit::Blargg,
            "palette survives power-cycle"
        );
    }

    /// v2.9.8 — a ROM that writes PPUCTRL and PPUMASK exactly once, as its
    /// first four instructions, then idles. Whether those writes land is the
    /// whole observable difference between the two console models at power-on.
    ///
    /// ```text
    /// C000: A9 90     LDA #$90    ; NMI on, BG pattern table $1000
    /// C002: 8D 00 20  STA $2000
    /// C005: A9 01     LDA #$01    ; greyscale only: rendering stays off
    /// C007: 8D 01 20  STA $2001
    /// C00A: 4C 0A C0  JMP $C00A
    /// C00D: 40        RTI         ; NMI handler
    /// ```
    fn one_shot_ppu_write_rom() -> Vec<u8> {
        // (Two frames are run per check below, not one: the machine powers up
        // with the PPU at the end of the pre-render line, so the first
        // `run_frame` completes within a few cycles, before these writes.)
        let mut bytes = alloc::vec![0u8; 16 + 16 * 1024];
        bytes[0..4].copy_from_slice(b"NES\x1A");
        bytes[4] = 1; // 1x16 KiB PRG, CHR-RAM
        let prg = &mut bytes[16..];
        prg[0..14].copy_from_slice(&[
            0xA9, 0x90, 0x8D, 0x00, 0x20, 0xA9, 0x01, 0x8D, 0x01, 0x20, 0x4C, 0x0A, 0xC0, 0x40,
        ]);
        let len = prg.len();
        prg[len - 6] = 0x0D; // NMI -> $C00D (RTI)
        prg[len - 5] = 0xC0;
        prg[len - 4] = 0x00; // RESET -> $C000
        prg[len - 3] = 0xC0;
        prg[len - 2] = 0x0A; // IRQ -> $C00A
        prg[len - 1] = 0xC0;
        bytes
    }

    fn run_frames(nes: &mut Nes, n: u32) {
        for _ in 0..n {
            let _ = nes.run_frame();
        }
    }

    /// v2.9.8 — the console model's two documented effects, from `NESdev` "PPU
    /// power up state" (§Famicom and the front-/top-loader note):
    ///
    /// 1. At power-on the NES ignores `$2000`/`$2001` for ~29,658 CPU cycles,
    ///    so a write issued in the first few cycles is lost; on the Famicom the
    ///    PPU left reset about one frame earlier, so the same write lands.
    /// 2. The Reset button resets the PPU on the NES (PPUCTRL cleared, the
    ///    warm-up window re-armed) and does not reach it on the Famicom.
    #[test]
    fn famicom_console_model_ppu_leaves_reset_before_the_cpu() {
        let rom = one_shot_ppu_write_rom();

        // Default (NES): the model is NES, and the one-shot writes are dropped
        // inside the warm-up window — the established behaviour.
        let mut nes = Nes::from_rom(&rom).expect("boot");
        assert_eq!(nes.console_model(), ConsoleModel::Nes);
        run_frames(&mut nes, 2);
        assert_eq!(
            nes.bus().ppu().debug_registers()[..2],
            [0x00, 0x00],
            "NES: writes inside the warm-up window are ignored"
        );

        // Famicom, selected straight after construction the way the frontend
        // applies its config: the same writes land.
        let mut fc = Nes::from_rom(&rom).expect("boot");
        fc.set_console_model(ConsoleModel::Famicom);
        assert_eq!(fc.bus().ppu().warmup_cycles_remaining(), 0);
        run_frames(&mut fc, 2);
        assert_eq!(
            fc.bus().ppu().debug_registers()[..2],
            [0x90, 0x01],
            "Famicom: the PPU is past its warm-up when the CPU starts"
        );

        // Reset reaches only the CPU on a Famicom: PPUCTRL/PPUMASK survive and
        // no window is re-armed.
        fc.reset();
        assert_eq!(fc.bus().ppu().debug_registers()[..2], [0x90, 0x01]);
        assert_eq!(fc.bus().ppu().warmup_cycles_remaining(), 0);

        // On the NES, Reset clears PPUCTRL/PPUMASK and re-arms the window.
        let mut nes = Nes::from_rom(&rom).expect("boot");
        nes.set_console_model(ConsoleModel::Famicom);
        run_frames(&mut nes, 2);
        assert_eq!(nes.bus().ppu().debug_registers()[..2], [0x90, 0x01]);
        nes.set_console_model(ConsoleModel::Nes);
        nes.reset();
        assert_eq!(nes.bus().ppu().debug_registers()[..2], [0x00, 0x00]);
        assert!(nes.bus().ppu().warmup_cycles_remaining() > 29_000);

        // The selection survives a power cycle and is applied to the rebuilt
        // PPU before the CPU's first instruction.
        fc.power_cycle();
        assert_eq!(fc.console_model(), ConsoleModel::Famicom);
        assert_eq!(fc.bus().ppu().warmup_cycles_remaining(), 0);
        run_frames(&mut fc, 2);
        assert_eq!(fc.bus().ppu().debug_registers()[..2], [0x90, 0x01]);
    }

    #[test]
    fn nes_run_frame_completes_and_returns_framebuffer() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        let fb = nes.run_frame();
        assert_eq!(fb.len(), 256 * 240 * 4);
    }

    #[test]
    fn nes_run_two_frames_distinct_completion_latches() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        nes.run_frame();
        let cycles_after_one = nes.cycle();
        nes.run_frame();
        let cycles_after_two = nes.cycle();
        assert!(cycles_after_two > cycles_after_one);
    }

    #[test]
    fn nes_determinism_two_runs_match() {
        // T-24-002: same ROM + zero input + 60 frames -> bit-identical
        // framebuffer hash via FNV-1a.
        fn hash_fb(fb: &[u8]) -> u64 {
            let mut h: u64 = 0xCBF2_9CE4_8422_2325;
            for &b in fb {
                h ^= u64::from(b);
                h = h.wrapping_mul(0x0000_0100_0000_01B3);
            }
            h
        }
        let rom = synth_nrom(16, 8);
        let mut a = Nes::from_rom(&rom).unwrap();
        let mut b = Nes::from_rom(&rom).unwrap();
        let frames = 4;
        let mut hash_a = 0u64;
        let mut hash_b = 0u64;
        for _ in 0..frames {
            hash_a = hash_fb(a.run_frame());
            hash_b = hash_fb(b.run_frame());
        }
        assert_eq!(
            hash_a, hash_b,
            "two runs must produce identical framebuffer"
        );
    }

    fn fnv_hash(bytes: &[u8]) -> u64 {
        let mut h: u64 = 0xCBF2_9CE4_8422_2325;
        for &b in bytes {
            h ^= u64::from(b);
            h = h.wrapping_mul(0x0000_0100_0000_01B3);
        }
        h
    }

    #[test]
    fn snapshot_round_trip_preserves_framebuffer_and_cycle() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        for _ in 0..4 {
            nes.run_frame();
        }
        let cycle = nes.cycle();
        let fb_hash_before = fnv_hash(nes.framebuffer());
        let blob = nes.snapshot();

        // Drift the emulator forward 4 more frames so it looks different.
        for _ in 0..4 {
            nes.run_frame();
        }
        assert_ne!(nes.cycle(), cycle, "drift must move us off the snapshot");

        nes.restore(&blob).expect("restore");
        assert_eq!(nes.cycle(), cycle);
        assert_eq!(fnv_hash(nes.framebuffer()), fb_hash_before);
    }

    // ---------------------------------------------------------------------
    // Cartridge-RAM save-state sweep (core audit v2.9.2 AUD-02 and its
    // follow-up).
    //
    // The `.rns` container has no SRAM section: the `MAP ` section is the
    // mapper's own `save_state` blob and nothing else, so cartridge RAM
    // survives a save-state load, rewind step, run-ahead frame or netplay
    // rollback ONLY if the board writes it into that blob. AUD-02 found the
    // Konami VRC boards leaving theirs out; a one-off sweep then found the
    // same omission on boards outside that family. These tests are that sweep
    // made durable: they walk EVERY mapper id `rustynes_mappers::parse`
    // constructs, so a board added later is checked the day it lands rather
    // than the day its RAM goes missing in someone's rewind.
    // ---------------------------------------------------------------------

    use alloc::{boxed::Box, string::String};

    /// How a sweep image's header is encoded.
    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
    enum SweepHeader {
        /// iNES 1.0 (mapper ids 0-255 only). The parser defaults an iNES 1.0
        /// cart to 8 KiB PRG-RAM and, with no CHR-ROM, 8 KiB CHR-RAM.
        Ines1,
        /// NES 2.0 with this submapper, declaring 8 KiB battery PRG-NVRAM and,
        /// with no CHR-ROM, 8 KiB CHR-RAM. Covers ids 256-4095 and every
        /// submapper-selected variant of the lower ids.
        Nes2 { submapper: u8 },
    }

    /// Synthetic cartridge image for mapper `mapper_id`: `prg_kib` KiB PRG,
    /// `chr_kib` KiB CHR-ROM (`0` = none, so the board allocates CHR-RAM),
    /// battery flag set so boards that gate `sram()` on the battery bit
    /// expose their `$6000-$7FFF` RAM. Every 8 KiB PRG bank ends in a vector
    /// table pointing at a `JMP $E000` idle loop, so whichever bank a board
    /// maps at `$E000` on power-on, the CPU spins harmlessly.
    fn synth_board_rom(
        mapper_id: u16,
        header: SweepHeader,
        prg_kib: usize,
        chr_kib: usize,
    ) -> Vec<u8> {
        let mut bytes = Vec::with_capacity(16 + (prg_kib + chr_kib) * 1024);
        bytes.extend_from_slice(b"NES\x1A");
        bytes.push(u8::try_from(prg_kib / 16).expect("PRG size fits the header"));
        bytes.push(u8::try_from(chr_kib / 8).expect("CHR size fits the header"));
        let [id_lo, id_hi] = mapper_id.to_le_bytes();
        bytes.push(((id_lo & 0x0F) << 4) | 0x02); // flags6: battery
        match header {
            SweepHeader::Ines1 => {
                assert_eq!(id_hi, 0, "iNES 1.0 carries 8-bit mapper ids only");
                bytes.push(id_lo & 0xF0); // flags7: mapper high nibble
                bytes.extend_from_slice(&[0u8; 8]);
            }
            SweepHeader::Nes2 { submapper } => {
                bytes.push((id_lo & 0xF0) | 0x08); // flags7: NES 2.0 marker
                bytes.push((submapper << 4) | (id_hi & 0x0F)); // byte 8
                bytes.push(0); // byte 9: ROM size MSBs
                bytes.push(0x70); // byte 10: 8 KiB (64 << 7) battery PRG-NVRAM
                bytes.push(if chr_kib == 0 { 0x07 } else { 0x00 }); // byte 11: CHR-RAM
                bytes.extend_from_slice(&[0u8; 4]); // bytes 12-15: NTSC, no Vs.
            }
        }
        let mut prg = vec![0u8; prg_kib * 1024];
        for bank in prg.chunks_mut(8 * 1024) {
            bank[0] = 0x4C; // JMP $E000
            bank[1] = 0x00;
            bank[2] = 0xE0;
            let len = bank.len();
            for v in [len - 6, len - 4, len - 2] {
                bank[v] = 0x00;
                bank[v + 1] = 0xE0;
            }
        }
        bytes.extend_from_slice(&prg);
        bytes.extend_from_slice(&vec![0u8; chr_kib * 1024]);
        bytes
    }

    /// Result of trying to build one sweep configuration.
    enum SweepBoot {
        /// `parse` does not know the mapper id at all.
        Unsupported,
        /// Built with the first image shape the board accepted.
        Built(Box<Nes>),
        /// The id is known but no image shape was accepted (last error).
        Refused(String),
    }

    /// Build `mapper_id` under `header`, trying the image shapes in turn
    /// until the board's constructor accepts one. Most boards take the first
    /// (128 KiB PRG, the shape AUD-02's VRC pins used); a board with a fixed
    /// PRG size (NROM's 16/32 KiB, a 32 KiB-only discrete board) takes a later
    /// one. RAM sizes come from the header, not the ROM size, so the shape
    /// does not change what RAM the board allocates.
    fn sweep_boot(mapper_id: u16, header: SweepHeader, chr_ram: bool) -> SweepBoot {
        const PRG_KIB: [usize; 8] = [128, 32, 512, 256, 64, 16, 1024, 2048];
        const CHR_ROM_KIB: [usize; 5] = [128, 8, 256, 512, 1024];
        let chr_shapes: &[usize] = if chr_ram { &[0] } else { &CHR_ROM_KIB };
        let mut last = String::new();
        for &prg in &PRG_KIB {
            for &chr in chr_shapes {
                match Nes::from_rom(&synth_board_rom(mapper_id, header, prg, chr)) {
                    Ok(nes) => return SweepBoot::Built(Box::new(nes)),
                    Err(RomError::UnsupportedMapper(_)) => return SweepBoot::Unsupported,
                    Err(e) => last = alloc::format!("{prg} KiB PRG / {chr} KiB CHR: {e}"),
                }
            }
        }
        SweepBoot::Refused(last)
    }

    /// Byte `i` of the sweep's position-dependent pattern, `seed` keeping
    /// the PRG and CHR patterns distinct. Position-dependent so a shifted,
    /// truncated or aliased copy cannot pass for the real thing.
    fn sweep_pattern(i: usize, seed: u8) -> u8 {
        let le = i.to_le_bytes();
        le[0] ^ seed ^ le[1].rotate_left(3)
    }

    /// Where a probe found RAM.
    #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
    enum RamSite {
        /// PRG-RAM exposed through `Mapper::sram` (the whole buffer).
        PrgSram,
        /// PRG-RAM reachable at `$6000-$7FFF` but NOT exposed through
        /// `sram()` -- checked through the CPU window instead.
        PrgWindow,
        /// Writable CHR memory reachable at PPU `$0000-$1FFF`.
        ChrRam,
    }

    /// Describe the mismatch between two equal-length buffers, or `None`.
    fn sweep_diff(want: &[u8], got: &[u8]) -> Option<String> {
        let bad = want.iter().zip(got).filter(|(a, b)| a != b).count();
        let first = want.iter().zip(got).position(|(a, b)| a != b)?;
        Some(alloc::format!(
            "{bad} of {} bytes differ, first at +{first:#06x} (want {:#04x}, got {:#04x})",
            want.len(),
            want[first],
            got[first]
        ))
    }

    /// PRG-RAM round trip through the whole-machine snapshot. Returns the
    /// site probed (`None` when the board has no PRG-RAM the probe can reach)
    /// and the mismatch, if any.
    ///
    /// A board that exposes `sram()` is checked on the whole buffer, so RAM
    /// the CPU window cannot currently see (an unmapped page of a 32 KiB
    /// board, say) is covered too. A board that does not is probed at
    /// `$6000-$7FFF`: write the pattern, and if at least 2 KiB of it reads
    /// back (the smallest cartridge RAM; a mirrored 2 KiB part returns only
    /// its last alias), treat it as RAM and round-trip the window.
    fn sweep_prg_ram(nes: &mut Nes) -> (Option<RamSite>, Option<String>) {
        if !nes.sram().is_empty() {
            for (i, b) in nes.sram_mut().iter_mut().enumerate() {
                *b = sweep_pattern(i, 0xA5);
            }
            let want = nes.sram().to_vec();
            let blob = nes.snapshot();
            // Scribble with the complement, so every byte differs from what
            // the snapshot must bring back.
            for b in nes.sram_mut() {
                *b = !*b;
            }
            if let Err(e) = nes.restore(&blob) {
                return (
                    Some(RamSite::PrgSram),
                    Some(alloc::format!("restore: {e:?}")),
                );
            }
            return (Some(RamSite::PrgSram), sweep_diff(&want, nes.sram()));
        }
        let window = 0x6000u16..0x8000;
        for a in window.clone() {
            nes.bus
                .mapper
                .cpu_write(a, sweep_pattern(usize::from(a - 0x6000), 0xA5));
        }
        // Snapshot BEFORE reading back: the read below and the one after the
        // restore then both start from the snapshot's state, so a board whose
        // reads move state cannot make a correct restore look wrong.
        let blob = nes.snapshot();
        let want: Vec<u8> = window.clone().map(|a| nes.bus.mapper.cpu_read(a)).collect();
        let echoed = want
            .iter()
            .enumerate()
            .filter(|&(i, &b)| b == sweep_pattern(i, 0xA5))
            .count();
        if echoed < 0x800 {
            return (None, None);
        }
        for (a, w) in window.clone().zip(&want) {
            nes.bus.mapper.cpu_write(a, !w);
        }
        if let Err(e) = nes.restore(&blob) {
            return (
                Some(RamSite::PrgWindow),
                Some(alloc::format!("restore: {e:?}")),
            );
        }
        let got: Vec<u8> = window.map(|a| nes.bus.mapper.cpu_read(a)).collect();
        (Some(RamSite::PrgWindow), sweep_diff(&want, &got))
    }

    /// v3.1.0 — `debug_peek_ppu` is the debugger's and the HD-pack
    /// compositor's "side-effect-free" CHR read. On the five boards whose CHR
    /// reads change them (`Mapper::chr_reads_are_pure`), it used to flip the
    /// board: reading all of CHR on MMC2 or MMC4 (the pattern viewer does)
    /// passes tiles `$FD`/`$FE` and switches a CHR latch, so opening a debugger
    /// panel, or hashing a tile for an HD pack, changed the game. Every board's
    /// whole-machine state must be unchanged by a full sweep of peeks.
    #[test]
    fn debug_peek_ppu_changes_no_board() {
        // The five impure families' ids, and MMC3 (4) as a pure control.
        for id in [9u16, 10, 35, 90, 96, 163, 209, 211, 4] {
            let rom = synth_board_rom(id, SweepHeader::Ines1, 128, 128);
            let Ok(mut nes) = Nes::from_rom(&rom) else {
                panic!("mapper {id} builds");
            };
            nes.run_frame();
            let before = nes.snapshot();
            for a in 0u16..0x2000 {
                let _ = nes.bus.debug_peek_ppu(a);
            }
            let after = nes.snapshot();
            assert!(
                before == after,
                "mapper {id}: peeking CHR changed the machine ({} differing snapshot bytes)",
                before.iter().zip(&after).filter(|(a, b)| a != b).count()
            );
        }
    }

    /// CHR-RAM round trip through the whole-machine snapshot, through PPU
    /// `$0000-$1FFF` (there is no raw CHR accessor on `Mapper`). Returns
    /// `None` for the site when fewer than 1 KiB of the pattern reads back,
    /// i.e. the board has no writable CHR (a CHR-ROM board).
    ///
    /// Only the 8 KiB the power-on banking maps is checked; a board with more
    /// CHR-RAM than that is checked on its visible part. Every write lands
    /// before the snapshot and every read after it, from the same state on
    /// both sides: MMC2 and MMC4 flip their CHR latches on PPU reads of
    /// `$0FD8`/`$0FE8`, so a read sequence started from different latch
    /// states would compare different banks and fail a correct restore.
    fn sweep_chr_ram(nes: &mut Nes) -> (Option<RamSite>, Option<String>) {
        for a in 0u16..0x2000 {
            nes.bus
                .mapper
                .ppu_write(a, sweep_pattern(usize::from(a), 0x3C));
        }
        let blob = nes.snapshot();
        let want: Vec<u8> = (0u16..0x2000).map(|a| nes.bus.debug_peek_ppu(a)).collect();
        let echoed = want
            .iter()
            .enumerate()
            .filter(|&(i, &b)| b == sweep_pattern(i, 0x3C))
            .count();
        if echoed < 0x400 {
            return (None, None);
        }
        for (a, w) in (0u16..0x2000).zip(&want) {
            nes.bus.mapper.ppu_write(a, !w);
        }
        if let Err(e) = nes.restore(&blob) {
            return (
                Some(RamSite::ChrRam),
                Some(alloc::format!("restore: {e:?}")),
            );
        }
        let got: Vec<u8> = (0u16..0x2000).map(|a| nes.bus.debug_peek_ppu(a)).collect();
        (Some(RamSite::ChrRam), sweep_diff(&want, &got))
    }

    /// Mapper ids `parse` knows but cannot build under ANY sweep
    /// configuration, each with the reason. A board on this list is excluded
    /// from the sweep by name, never silently.
    const SWEEP_UNBUILDABLE: &[(u16, &str)] = &[];

    /// The sweep's `--nocapture` report: what was checked where, which built
    /// boards had no RAM the probes could reach, and which configurations a
    /// board refused (a CHR-ROM-only board refusing a CHR-RAM image, a
    /// fixed-size board refusing the larger PRG shapes). Printed, not
    /// asserted, so a reader can see the sweep's reach on every run.
    fn sweep_print_report(
        supported: &alloc::collections::BTreeSet<u16>,
        built: &alloc::collections::BTreeSet<u16>,
        checked: &alloc::collections::BTreeMap<u16, alloc::collections::BTreeSet<RamSite>>,
        refusals: &alloc::collections::BTreeMap<u16, Vec<String>>,
    ) {
        let no_ram: Vec<u16> = built
            .iter()
            .copied()
            .filter(|m| !checked.contains_key(m))
            .collect();
        std::println!(
            "cartridge-RAM sweep: {} supported ids, {} built, {} with RAM checked",
            supported.len(),
            built.len(),
            checked.len()
        );
        for site in [RamSite::PrgSram, RamSite::PrgWindow, RamSite::ChrRam] {
            let ids: Vec<u16> = checked
                .iter()
                .filter(|(_, s)| s.contains(&site))
                .map(|(m, _)| *m)
                .collect();
            std::println!("  {site:?} ({}): {ids:?}", ids.len());
        }
        std::println!("  no RAM reachable ({}): {no_ram:?}", no_ram.len());
        for (m, why) in refusals {
            std::println!(
                "  mapper {m}: {} configuration(s) refused, e.g. {}",
                why.len(),
                why[0]
            );
        }
    }

    /// Core audit v2.9.2 AUD-02 and its follow-up: every board's PRG-RAM and
    /// CHR-RAM must survive a whole-machine `snapshot` / `restore`.
    ///
    /// Sweeps every mapper id 0-4095 (NES 2.0, all 16 submappers; iNES 1.0
    /// too for 0-255), each with CHR-ROM and with CHR-RAM. For every
    /// configuration that builds it fills the board's RAM with a pattern,
    /// snapshots the `Nes`, scribbles the RAM with the complement, restores
    /// and compares. Supersedes the VRC-only pins AUD-02 added
    /// (`vrc_boards_snapshot_carries_{prg,chr}_ram`), and asserts those
    /// boards are still among the ones checked, so the sweep can never pass
    /// by checking less.
    ///
    /// Outside the sweep by construction, not by omission: the FDS (mapper
    /// 20) and NSF players do not come through `parse` (they load through
    /// `Nes::from_disk` / `Nes::from_nsf`), and both write their RAM into
    /// their own blobs (the `save_state` of `fds.rs` and `nsf.rs`).
    ///
    /// What it cannot see: PRG-RAM a board neither exposes through `sram()`
    /// nor maps at `$6000-$7FFF` at power-on (RAM behind a board-specific
    /// enable register), and CHR-RAM beyond the 8 KiB visible at power-on.
    /// The `--nocapture` output lists which boards were checked where.
    #[test]
    fn every_board_snapshot_carries_cartridge_ram() {
        use alloc::collections::{BTreeMap, BTreeSet};

        let mut supported: BTreeSet<u16> = BTreeSet::new();
        let mut built: BTreeSet<u16> = BTreeSet::new();
        let mut checked: BTreeMap<u16, BTreeSet<RamSite>> = BTreeMap::new();
        let mut failures: BTreeMap<(u16, RamSite), Vec<String>> = BTreeMap::new();
        let mut refusals: BTreeMap<u16, Vec<String>> = BTreeMap::new();

        for mapper_id in 0u16..4096 {
            let mut headers = Vec::new();
            if mapper_id < 256 {
                headers.push(SweepHeader::Ines1);
            }
            headers.extend((0u8..16).map(|submapper| SweepHeader::Nes2 { submapper }));
            'headers: for header in headers {
                for chr_ram in [false, true] {
                    let mut nes = match sweep_boot(mapper_id, header, chr_ram) {
                        // An unknown id: no other header builds it either.
                        SweepBoot::Unsupported => break 'headers,
                        SweepBoot::Refused(e) => {
                            supported.insert(mapper_id);
                            refusals
                                .entry(mapper_id)
                                .or_default()
                                .push(alloc::format!("{header:?} chr_ram={chr_ram}: {e}"));
                            continue;
                        }
                        SweepBoot::Built(nes) => nes,
                    };
                    supported.insert(mapper_id);
                    built.insert(mapper_id);
                    let tag = alloc::format!("{header:?} chr_ram={chr_ram}");
                    for (site, fail) in [sweep_prg_ram(&mut nes), sweep_chr_ram(&mut nes)] {
                        let Some(site) = site else { continue };
                        checked.entry(mapper_id).or_default().insert(site);
                        if let Some(fail) = fail {
                            failures
                                .entry((mapper_id, site))
                                .or_default()
                                .push(alloc::format!("{tag}: {fail}"));
                        }
                    }
                }
            }
        }

        sweep_print_report(&supported, &built, &checked, &refusals);

        // Nothing is skipped silently: an id that never built is either on
        // the explicit list, with its reason, or a failure.
        let unbuildable: Vec<u16> = supported.difference(&built).copied().collect();
        let listed: Vec<u16> = SWEEP_UNBUILDABLE.iter().map(|&(m, _)| m).collect();
        assert_eq!(
            unbuildable, listed,
            "mapper ids that no sweep configuration builds must be listed in \
             SWEEP_UNBUILDABLE with a reason: {refusals:?}"
        );

        // The sweep must keep covering what AUD-02 pinned by name (PRG-RAM on
        // the VRC boards 21-26/73/85, CHR-RAM on 21-26/85) and the boards its
        // follow-up fixed, or a regression in the probes could pass by
        // checking nothing.
        for m in [10u16, 21, 22, 23, 24, 25, 26, 73, 85] {
            assert!(
                checked
                    .get(&m)
                    .is_some_and(|s| s.contains(&RamSite::PrgSram)),
                "mapper {m}: PRG-RAM no longer checked through sram()"
            );
        }
        for m in [
            9u16, 10, 11, 19, 21, 22, 23, 24, 25, 26, 34, 69, 75, 85, 151,
        ] {
            assert!(
                checked
                    .get(&m)
                    .is_some_and(|s| s.contains(&RamSite::ChrRam)),
                "mapper {m}: CHR-RAM no longer checked"
            );
        }

        let report: Vec<String> = failures
            .iter()
            .map(|((m, site), v)| {
                alloc::format!("mapper {m} {site:?}: {} config(s), e.g. {}", v.len(), v[0])
            })
            .collect();
        assert!(
            failures.is_empty(),
            "cartridge RAM not restored from the snapshot on {} board/site pair(s):\n{}",
            failures.len(),
            report.join("\n")
        );
    }

    #[test]
    fn snapshot_is_deterministic_across_two_runs() {
        let rom = synth_nrom(16, 8);
        let mut a = Nes::from_rom(&rom).unwrap();
        let mut b = Nes::from_rom(&rom).unwrap();
        for _ in 0..3 {
            a.run_frame();
            b.run_frame();
        }
        assert_eq!(a.snapshot(), b.snapshot());
    }

    #[test]
    fn snapshot_header_carries_rom_hash_tag() {
        let rom = synth_nrom(16, 8);
        let nes = Nes::from_rom(&rom).unwrap();
        let blob = nes.snapshot();
        let (h, _off) = save_state::parse_header(&blob).unwrap();
        assert_eq!(h.rom_hash_tag, nes.rom_hash_tag());
    }

    /// v2.9.8 (ADR 0042): a `.rns` written by v2.9.7 or earlier carries
    /// container format 2 and is refused at the header with one typed error,
    /// before any section is looked at -- and the machine is left as it was.
    #[test]
    fn a_v2_9_7_container_is_refused_at_the_header() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        nes.run_frame();
        let mut old = nes.snapshot();
        let before = old.clone();
        // The container's format version is the u16 after the 8-byte magic.
        old[8..10].copy_from_slice(&2u16.to_le_bytes());
        let err = nes.restore(&old).unwrap_err();
        assert!(
            matches!(err, SnapshotError::FormatTooOld { got: 2, .. }),
            "expected FormatTooOld, got {err:?}"
        );
        assert_eq!(nes.snapshot(), before, "a refused load changed the machine");
    }

    #[test]
    fn restore_rejects_pre_v3_cpu_section_version() {
        // ADR 0028 (v2.0.0 rc.1): a slot file whose CPU section predates the
        // one-clock promote (schema version < CPU_SNAPSHOT_VERSION) must be
        // cleanly rejected via SnapshotError::VersionMismatch, not silently
        // accepted or upconverted. Simulate an old slot by taking a
        // freshly-emitted (current-version) snapshot and patching only the
        // CPU section's version byte down to a stale value -- everything
        // else (the body bytes, every other section) is untouched, so this
        // isolates the version-gate behavior from any layout difference.
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        for _ in 0..3 {
            nes.run_frame();
        }
        let current = nes.snapshot();
        let (_h, body_off) = save_state::parse_header(&current).unwrap();
        let mut stale = current[..body_off].to_vec();
        for s in save_state::SectionIter::new(&current[body_off..]) {
            let s = s.unwrap();
            let version = if s.tag == save_state::tag::CPU {
                assert_eq!(
                    s.version,
                    rustynes_cpu::CPU_SNAPSHOT_VERSION,
                    "fixture assumption: current build writes the current CPU version"
                );
                s.version - 1
            } else {
                s.version
            };
            save_state::write_section(&mut stale, s.tag, version, s.body);
        }
        let err = nes.restore(&stale).unwrap_err();
        assert!(
            matches!(
                err,
                SnapshotError::VersionMismatch { ref tag, .. } if tag == "CPU "
            ),
            "expected a CPU-tagged VersionMismatch, got {err:?}"
        );
    }

    /// v3.0.0: a state from another release fails a section's version
    /// check, not the container's (v2.9.9's states carry PPU section 11,
    /// where v3.0.0 reads 12), and the message must say which way the
    /// versions differ. Until v3.0.0 it gave only the two numbers, which
    /// players read as a damaged file.
    #[test]
    fn a_state_from_another_release_says_older_or_newer() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        nes.run_frame();
        let current = nes.snapshot();
        let (_h, body_off) = save_state::parse_header(&current).unwrap();
        for (delta, words) in [(-1i16, "older release"), (1, "newer release")] {
            let mut patched = current[..body_off].to_vec();
            for s in save_state::SectionIter::new(&current[body_off..]) {
                let s = s.unwrap();
                let version = if s.tag == save_state::tag::PPU {
                    u8::try_from(i16::from(s.version) + delta).unwrap()
                } else {
                    s.version
                };
                save_state::write_section(&mut patched, s.tag, version, s.body);
            }
            let err = nes.restore(&patched).unwrap_err();
            let text = format!("{err}");
            assert!(
                matches!(err, SnapshotError::VersionMismatch { ref tag, .. } if tag == "PPU "),
                "expected a PPU VersionMismatch, got {err:?}"
            );
            assert!(text.contains(words), "{text}");
        }
    }

    /// v2.7.4 (frontend audit MOB-08): a load that fails leaves the machine as
    /// it was. `restore_inner` applies the bus sections first and checks the
    /// CPU section after, so on v2.7.3 a blob rejected at the CPU stage left
    /// the bus from the blob and the CPU from the running game -- a machine
    /// that was neither, which the next frame then emulated. Every host hit
    /// it: desktop, libretro and both mobile apps. The rejected blob here is
    /// the stale-CPU-version one from the test above, taken at an earlier frame
    /// so its bus state really differs.
    #[test]
    fn a_failed_restore_leaves_the_machine_untouched() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        nes.run_frame();
        let earlier = nes.snapshot();
        for _ in 0..3 {
            nes.run_frame();
        }
        let before = nes.snapshot();
        assert_ne!(
            earlier, before,
            "the fixture must change state between frames"
        );

        let (_h, body_off) = save_state::parse_header(&earlier).unwrap();
        let mut rejected = earlier[..body_off].to_vec();
        for s in save_state::SectionIter::new(&earlier[body_off..]) {
            let s = s.unwrap();
            let version = if s.tag == save_state::tag::CPU {
                s.version - 1
            } else {
                s.version
            };
            save_state::write_section(&mut rejected, s.tag, version, s.body);
        }
        assert!(nes.restore(&rejected).is_err());
        assert_eq!(nes.snapshot(), before, "a failed load changed the machine");
        // And it still runs as the same machine.
        nes.run_frame();
    }

    /// `blob` with the version byte of its `CPU ` section decremented: a
    /// well-framed state that every stage before the CPU one accepts.
    fn with_stale_cpu_version(blob: &[u8]) -> Vec<u8> {
        let (_h, body_off) = save_state::parse_header(blob).unwrap();
        let mut out = blob[..body_off].to_vec();
        for s in save_state::SectionIter::new(&blob[body_off..]) {
            let s = s.unwrap();
            let version = if s.tag == save_state::tag::CPU {
                s.version - 1
            } else {
                s.version
            };
            save_state::write_section(&mut out, s.tag, version, s.body);
        }
        out
    }

    /// `blob` with byte `at` of its `MAP ` section's body set to `value`.
    fn with_map_byte(blob: &[u8], at: usize, value: u8) -> Vec<u8> {
        let (_h, body_off) = save_state::parse_header(blob).unwrap();
        let mut out = blob[..body_off].to_vec();
        for s in save_state::SectionIter::new(&blob[body_off..]) {
            let s = s.unwrap();
            if s.tag == save_state::tag::MAP {
                let mut body = s.body.to_vec();
                body[at] = value;
                save_state::write_section(&mut out, s.tag, s.version, &body);
            } else {
                save_state::write_section(&mut out, s.tag, s.version, s.body);
            }
        }
        out
    }

    /// v2.9.0 re-audit NC-02, at the whole-machine level: a GTROM (mapper 111)
    /// state carrying a bank the board cannot hold is refused by
    /// `Nes::restore`, and the machine keeps running. Before, `restore`
    /// returned `Ok(())` and the next CPU fetch from `$8000` panicked
    /// (`homebrew_boards.rs:570`, index 8,372,319 into 32 KiB in the
    /// re-audit's probe) — after the restore, so its rollback could not help.
    #[test]
    fn a_gtrom_state_with_an_impossible_bank_is_refused_and_the_game_runs_on() {
        let mut rom = synth_nrom(32, 0);
        rom[6] = 0xF0; // mapper low nibble F
        rom[7] = 0x60; // mapper high nibble 6: 0x6F = 111
        let mut donor = Nes::from_rom(&rom).expect("GTROM image");
        donor.run_frame();
        donor.run_frame();
        let good = donor.snapshot();
        // MAP body: version, prg_bank, chr_bank, nt_bank, ...
        for (at, value) in [(1, 0xFF), (2, 0xFF), (3, 0xFF)] {
            let bad = with_map_byte(&good, at, value);
            let mut nes = Nes::from_rom(&rom).unwrap();
            nes.run_frame();
            let before = nes.snapshot();
            assert!(
                nes.restore(&bad).is_err(),
                "MAP byte {at} = {value:#04x} must be refused"
            );
            assert!(
                nes.snapshot() == before,
                "a refused load changed the machine"
            );
            nes.run_frame();
            nes.run_frame();
        }
    }

    /// v2.9.0 re-audit NC-03 / NL-01: the QUIET restore is all-or-nothing too.
    ///
    /// v2.7.4 gave only the loud path a rollback, on the premise that a quiet
    /// restore "only ever restore[s] snapshots this core just wrote, which
    /// cannot fail these checks". libretro breaks that premise: every
    /// `retro_unserialize` -- a user's Load State, a state from an older core,
    /// a corrupt file -- goes through `restore_quiet`. The re-audit's probe
    /// showed a rejected CPU section leaving the bus, PPU, APU and mapper from
    /// the rejected file (frame 3000) under the running game's CPU (frame 5).
    ///
    /// Two rejection points are pinned, because they fail at different depths:
    /// the CPU section's version (after all four bus sections applied) and the
    /// cross-section clock check (after the CPU applied as well). Both must
    /// leave the machine byte-identical and the rewind ring untouched.
    #[test]
    fn a_failed_quiet_restore_leaves_the_machine_untouched() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        nes.enable_rewind_with(2 * 1024 * 1024, 1);
        nes.run_frame();
        nes.run_frame();
        let earlier = nes.snapshot();
        for _ in 0..3 {
            nes.run_frame();
        }
        let before = nes.snapshot();
        let ring_before = nes.rewind.as_ref().map(RewindRing::len);
        assert_ne!(
            earlier, before,
            "the fixture must change state between frames"
        );

        // A CPU/PPU clock skew the clock check rejects, carried by an
        // otherwise valid EARLIER state: every section decodes, so this fails
        // at the very last stage.
        let skewed = {
            let mut other = Nes::from_rom(&rom).unwrap();
            other.run_frame();
            other.run_frame();
            let far = other.cpu.master_clock() + (1 << 40);
            other.bus_mut().set_ppu_clock_for_test(far);
            other.snapshot()
        };

        for (label, blob) in [
            ("stale CPU version", with_stale_cpu_version(&earlier)),
            ("CPU/PPU clock skew", skewed),
        ] {
            assert!(nes.restore_quiet(&blob).is_err(), "{label}: must reject");
            // `assert!` rather than `assert_eq!`: a failure would otherwise
            // print two ~300 KB byte arrays.
            assert!(
                nes.snapshot() == before,
                "{label}: a failed quiet restore changed the machine"
            );
            assert_eq!(
                nes.rewind.as_ref().map(RewindRing::len),
                ring_before,
                "{label}: a quiet restore must leave the rewind ring alone"
            );
        }
        // And it still runs as the same machine.
        nes.run_frame();
    }

    #[test]
    fn rewind_step_back_restores_prior_frame() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).unwrap();
        nes.enable_rewind_with(2 * 1024 * 1024, 1);
        for _ in 0..6 {
            nes.run_frame();
        }
        let cycle_at_6 = nes.cycle();
        nes.run_frame();
        nes.run_frame();
        nes.run_frame();
        // 3 entries on the ring (frames 6..=8 captured at the END of each
        // run_frame — frame 5 was captured in the loop above).
        assert!(nes.rewind_step_back(), "first step back");
        assert!(nes.rewind_step_back(), "second step back");
        assert!(nes.rewind_step_back(), "third step back");
        // We've rewound past the 3 extra frames; cycle should equal the
        // state we captured at the end of frame 6 (i.e. frame 5's snap).
        assert_ne!(nes.cycle(), cycle_at_6, "captured frame 5, not frame 6");
    }

    // ---- v2.4.0 item B — the timeline generation counter ----

    /// A LOUD restore is a timeline jump and must bump the generation.
    ///
    /// This is the defect the counter exists for: v2.3.9 cleared stale debug
    /// telemetry on a ROM change and could not clear it on a save-state load,
    /// because two of the four jump paths are not reachable from a patchable
    /// frontend call site.
    #[test]
    fn a_loud_restore_bumps_the_timeline_generation() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).unwrap();
        nes.run_frame();
        let blob = nes.snapshot();
        let before = nes.timeline_generation();
        nes.run_frame();
        nes.restore(&blob).expect("restore");
        assert!(
            nes.timeline_generation() > before,
            "a user-driven load did not register as a timeline jump"
        );
    }

    /// A QUIET restore is the SAME timeline and must NOT bump.
    ///
    /// Run-ahead restores every frame and netplay rollback restores on every
    /// correction. Bumping here would clear a consumer's telemetry sixty times a
    /// second — worse than the stale-telemetry defect the counter fixes.
    #[test]
    fn a_quiet_restore_does_not_bump_the_timeline_generation() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).unwrap();
        nes.run_frame();
        let blob = nes.snapshot();
        let before = nes.timeline_generation();
        nes.run_frame();
        nes.restore_quiet(&blob).expect("quiet restore");
        assert_eq!(
            nes.timeline_generation(),
            before,
            "a same-timeline restore was reported as a jump; under run-ahead this \
             fires every frame"
        );
    }

    /// Rewind is a jump, and it reaches the counter without its own call site.
    #[test]
    fn rewind_bumps_the_timeline_generation() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).unwrap();
        nes.enable_rewind_with(2 * 1024 * 1024, 1);
        for _ in 0..4 {
            nes.run_frame();
        }
        let before = nes.timeline_generation();
        assert!(nes.rewind_step_back(), "step back");
        assert!(
            nes.timeline_generation() > before,
            "rewind did not register as a timeline jump"
        );
    }

    /// Reset and power-cycle are discontinuities too.
    #[test]
    fn reset_and_power_cycle_bump_the_timeline_generation() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).unwrap();
        let a = nes.timeline_generation();
        nes.reset();
        let b = nes.timeline_generation();
        assert!(b > a, "warm reset did not bump");
        nes.power_cycle();
        assert!(nes.timeline_generation() > b, "power cycle did not bump");
    }

    /// v2.9.8 — a power cycle keeps every host setting stored on the PPU and
    /// the APU, on a bare `Nes` with no host to re-push anything.
    ///
    /// `Nes::power_cycle` rebuilds both chips, and until v2.9.8 each of these
    /// reverted to its default there: the desktop re-pushed them after the
    /// cycle, the movie power-on (`power_on_for_movie`), libretro and mobile
    /// paths did not. One row per setting, each set to a NON-default value,
    /// so a row that reverts fails on its own.
    #[test]
    fn a_power_cycle_keeps_every_ppu_and_apu_setting() {
        type Setting = (&'static str, fn(&mut Nes), fn(&Nes) -> bool);
        const PAL: [[u8; 3]; 64] = [[0x12, 0x34, 0x56]; 64];
        const GAIN: [f32; 6] = [0.5, 1.5, 0.25, 2.0, 0.0, 0.75];
        let rows: [Setting; 7] = [
            (
                "custom palette",
                |n| n.set_custom_palette(Some(PAL)),
                |n| n.custom_palette() == Some(PAL),
            ),
            (
                "extra scanlines",
                |n| n.set_extra_scanlines(7),
                |n| n.extra_scanlines() == 7,
            ),
            (
                "fast dot path (off; on is the default)",
                |n| n.set_fast_dotloop(false),
                |n| !n.fast_dotloop(),
            ),
            (
                "OAM decay",
                |n| n.set_oam_decay(true),
                |n| n.oam_decay_enabled(),
            ),
            (
                "APU channel mask",
                |n| n.set_apu_channel_mask(0x15),
                |n| n.apu_channel_mask() == 0x15,
            ),
            (
                "APU channel gain",
                |n| n.set_apu_channel_gain(GAIN),
                |n| n.apu_channel_gain() == GAIN,
            ),
            (
                "APU filter model",
                |n| n.set_apu_filter_model(rustynes_apu::FilterModel::Famicom),
                |n| n.apu_filter_model() == rustynes_apu::FilterModel::Famicom,
            ),
        ];
        let rom = synth_nrom(16, 8);
        let mut lost = Vec::new();
        for (name, set, holds) in rows {
            let mut nes = Nes::from_rom(&rom).unwrap();
            assert!(!holds(&nes), "{name}: premise -- the default differs");
            set(&mut nes);
            assert!(holds(&nes), "{name}: the setter applies it");
            nes.run_frame();
            nes.power_cycle();
            if !holds(&nes) {
                lost.push(name);
            }
        }
        // Every row is checked before failing, so a regression names every
        // setting it drops rather than only the first.
        assert!(lost.is_empty(), "lost across a power cycle: {lost:?}");
    }

    /// v2.9.8 — the kept settings are not just remembered, they are in force:
    /// a power-cycled console with them set produces the frame and the audio a
    /// FRESH console with the same settings produces (`power_cycle == fresh
    /// boot`, with the host's configuration held constant). The palette and
    /// the filter change what is emitted, so a setting that was only stored,
    /// and not applied to the rebuilt chip, fails here.
    ///
    /// The channel gain and the OAM-decay model are left out on purpose, and
    /// are covered by the table above instead: a FRESH console can only
    /// receive a setting after `from_rom`'s reset sequence has run its first
    /// cycles at the default, whereas the power-cycled console runs those
    /// cycles with the setting already in force. For the gain that moves the
    /// last bits of the audio; for OAM decay, enabling the model stamps every
    /// row's age with the current cycle, which is 0 on the rebuilt PPU and a
    /// few cycles later on the fresh one, so the serialized ages differ. Both
    /// differences are the fix working. (Measured for the gain: applying it
    /// to both consoles after the cycle matches, carrying it through does not.
    /// For decay: the test passes with it removed and fails with it present.)
    #[test]
    fn a_power_cycled_console_with_settings_runs_as_a_fresh_one() {
        fn configure(n: &mut Nes) {
            n.set_custom_palette(Some([[0x40, 0x80, 0xC0]; 64]));
            n.set_apu_filter_model(rustynes_apu::FilterModel::Clean);
        }
        let rom = include_bytes!("../../../tests/roms/nestest/nestest.nes");
        let mut cycled = Nes::from_rom(rom).unwrap();
        configure(&mut cycled);
        for _ in 0..5 {
            cycled.run_frame();
        }
        let _ = cycled.drain_audio();
        cycled.power_cycle();
        let mut fresh = Nes::from_rom(rom).unwrap();
        configure(&mut fresh);
        for _ in 0..10 {
            cycled.run_frame();
            fresh.run_frame();
        }
        assert_eq!(cycled.framebuffer(), fresh.framebuffer(), "frame");
        assert_eq!(cycled.drain_audio(), fresh.drain_audio(), "audio");
        assert_eq!(cycled.snapshot(), fresh.snapshot(), "state");
    }

    /// v2.9.8 — the provenance stores stay armed across a power cycle (and
    /// are emptied, since a cold boot ends the history they describe), as the
    /// comment in `Nes::power_cycle` always said. They were dropped with the
    /// rebuilt chips until v2.9.8, which made that comment's clear a no-op.
    #[cfg(feature = "debug-hooks")]
    #[test]
    fn a_power_cycle_keeps_the_provenance_stores_armed() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).unwrap();
        nes.set_write_attribution(true);
        nes.set_pixel_provenance(true);
        nes.set_audio_provenance(true);
        nes.run_frame();
        nes.power_cycle();
        assert!(
            nes.bus.ppu.write_attribution().is_some(),
            "write attribution"
        );
        assert!(nes.bus.ppu.pixel_provenance().is_some(), "pixel provenance");
        assert!(nes.bus.apu.audio_provenance_armed(), "audio provenance");
    }

    /// v2.9.8 — a power cycle after a program has polled the controllers is
    /// a fresh boot (`power_cycle == fresh boot`).
    ///
    /// The controller ports remember the bus cycle of their last read
    /// (`port_read_cycle`, `u64::MAX` = never), which the CLK-run model
    /// compares with the current cycle. A power cycle reset the cycle counter
    /// to 0 but left those stamps from the old timeline, so the cycled
    /// console's state depended on how long it had run and differed from a
    /// fresh one; two netplay peers cycling from different states would carry
    /// different stamps.
    #[test]
    fn a_power_cycle_after_controller_reads_is_a_fresh_boot() {
        let mut rom = synth_nrom(16, 8);
        // $C000: LDA $4016 ; LDA $4017 ; JMP $C000
        rom[16..25].copy_from_slice(&[0xAD, 0x16, 0x40, 0xAD, 0x17, 0x40, 0x4C, 0x00, 0xC0]);
        let mut cycled = Nes::from_rom(&rom).unwrap();
        for _ in 0..3 {
            cycled.run_frame();
        }
        assert_ne!(
            cycled.bus.port_read_cycle(0),
            u64::MAX,
            "premise: the program polled the pad"
        );
        cycled.power_cycle();
        let fresh = Nes::from_rom(&rom).unwrap();
        assert!(
            cycled.snapshot() == fresh.snapshot(),
            "a power-cycled console must equal a fresh one"
        );
    }

    /// v2.9.8 — `mapper_id` reports the cartridge's mapper on every board.
    ///
    /// It used to read the mapper's DEBUG view, whose default `debug_info`
    /// names mapper 0, so every board without its own override -- `UxROM`,
    /// CNROM, `AxROM` among them -- claimed to be NROM to the Lua
    /// `cart:mapper_id()`, the ROM-info panel and the mobile `RomInfo`.
    #[test]
    fn mapper_id_reports_the_cartridge_mapper_on_every_board() {
        /// A NES 2.0 image of `mapper` / `submapper`: `prg16` x 16 KiB PRG and
        /// `chr8` x 8 KiB CHR-ROM (0 = 8 KiB CHR-RAM).
        fn image(mapper: u16, submapper: u8, prg16: u8, chr8: u8) -> Vec<u8> {
            let [lo, hi] = mapper.to_le_bytes();
            let mut rom = vec![0u8; 16];
            rom[..4].copy_from_slice(b"NES\x1A");
            rom[4] = prg16;
            rom[5] = chr8;
            rom[6] = (lo & 0x0F) << 4;
            rom[7] = (lo & 0xF0) | 0x08; // NES 2.0
            rom[8] = (submapper << 4) | (hi & 0x0F);
            if chr8 == 0 {
                rom[11] = 0x07; // 64 << 7 = 8 KiB CHR-RAM
            }
            rom.resize(
                16 + usize::from(prg16) * 0x4000 + usize::from(chr8) * 0x2000,
                0,
            );
            rom
        }
        for (mapper, submapper, prg16, chr8) in [
            (0u16, 0u8, 2u8, 1u8),
            (2, 1, 8, 0),
            (3, 2, 2, 4),
            (7, 0, 8, 0),
            (4, 0, 8, 8),
        ] {
            let nes = Nes::from_rom(&image(mapper, submapper, prg16, chr8))
                .unwrap_or_else(|e| panic!("mapper {mapper}: {e:?}"));
            assert_eq!(nes.mapper_id(), mapper, "mapper {mapper}");
            assert_eq!(nes.submapper(), submapper, "mapper {mapper} submapper");
            // The debugger's mapper panel reads the same id.
            assert_eq!(nes.mapper_info().mapper_id, mapper, "mapper {mapper} view");
        }
    }

    /// **The counter must not be serialized**, and this is the assertion that
    /// pins it.
    ///
    /// Serializing it would put an OLD value back on restore, so loading a state
    /// saved earlier in the same session could hand a consumer a generation it
    /// has already seen — and the consumer would conclude nothing jumped at the
    /// exact moment something did. This test reproduces precisely that shape:
    /// snapshot at generation N, advance the generation past N, then restore. If
    /// the counter round-tripped, the value would come back as N.
    #[test]
    fn a_restore_never_hands_back_a_generation_a_consumer_has_seen() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).unwrap();
        nes.run_frame();
        let blob = nes.snapshot();
        let at_snapshot = nes.timeline_generation();

        // Advance the generation well past the snapshot's value.
        for _ in 0..3 {
            nes.reset();
        }
        let seen = nes.timeline_generation();
        assert!(seen > at_snapshot);

        nes.restore(&blob).expect("restore");
        assert!(
            nes.timeline_generation() > seen,
            "the generation went BACKWARDS to {} (a consumer had already seen {seen}), \
             so the counter is being carried in the save state -- which defeats its \
             only purpose",
            nes.timeline_generation()
        );
    }

    #[test]
    fn rewind_disabled_no_op() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).unwrap();
        nes.run_frame();
        assert!(!nes.rewind_step_back());
        assert_eq!(nes.rewind_len(), 0);
    }

    #[cfg(feature = "debug-hooks")]
    #[test]
    fn breakpoint_stops_run_frame_at_pc() {
        let rom = synth_nrom(16, 8);
        // A PC the CPU provably reaches: the PC after the first 3 executed
        // instructions (a fresh run replays the same deterministic sequence).
        let mut probe = Nes::from_rom(&rom).expect("parse");
        for _ in 0..3 {
            probe.step_instruction();
        }
        let target = probe.cpu.pc;

        let mut nes = Nes::from_rom(&rom).expect("parse");
        // The PPU's frame-complete latch is set at power-on, so the first
        // `run_frame` returns immediately without iterating; warm past it.
        let _ = nes.run_frame();
        nes.add_breakpoint(target);
        nes.add_breakpoint(target); // idempotent
        assert_eq!(nes.breakpoints(), &[target]);

        let _ = nes.run_frame();
        assert_eq!(
            nes.take_break_hit(),
            Some(target),
            "stops at the breakpoint PC"
        );
        assert_eq!(nes.take_break_hit(), None, "hit cleared on read");

        // Resuming ("continue") steps past the stopped PC instead of
        // re-breaking in place, then hits the same PC again next loop.
        let _ = nes.run_frame();
        assert_eq!(
            nes.take_break_hit(),
            Some(target),
            "resume steps past, then re-hits on the next pass"
        );

        // Disarmed breakpoints don't fire (the frame runs to completion).
        nes.set_breakpoints_enabled(false);
        let _ = nes.run_frame();
        assert_eq!(nes.take_break_hit(), None, "disarmed: no break");

        // Removal empties the list.
        nes.remove_breakpoint(target);
        assert_eq!(nes.breakpoints(), []);

        // Regression (gemini #41): a breakpoint sitting at the frame's STARTING
        // PC must fire immediately — the old `first_iter` skip missed it.
        let mut nes2 = Nes::from_rom(&rom).expect("parse");
        let _ = nes2.run_frame(); // warm past the power-on frame-complete latch
        let start_pc = nes2.cpu.pc;
        nes2.add_breakpoint(start_pc);
        let _ = nes2.run_frame();
        assert_eq!(
            nes2.take_break_hit(),
            Some(start_pc),
            "breaks immediately when starting already on a breakpoint"
        );
    }

    #[cfg(feature = "debug-hooks")]
    #[test]
    fn trace_logger_records_while_enabled() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse");
        let _ = nes.run_frame(); // warm past the power-on frame-complete latch.
        assert_eq!(nes.trace_len(), 0, "off by default");
        nes.set_trace_enabled(true);
        let _ = nes.run_frame();
        assert!(nes.trace_len() > 0, "records while enabled");
        // Records carry the executed PCs (the synth ROM spins at $C000).
        let recs = nes.trace_records();
        assert!(recs.iter().any(|r| r.pc == 0xC000), "captured the loop PC");
        // The tail copy is bounded.
        assert!(nes.trace_tail_vec(4).len() <= 4);
        // Disabling stops growth; clearing empties.
        nes.set_trace_enabled(false);
        let n = nes.trace_len();
        let _ = nes.run_frame();
        assert_eq!(nes.trace_len(), n, "no new records when disabled");
        nes.clear_trace();
        assert_eq!(nes.trace_len(), 0);
    }

    #[cfg(feature = "debug-hooks")]
    #[test]
    fn event_viewer_records_writes_with_ppu_position() {
        use crate::bus::EventKind;
        // A tiny NROM that loops `LDA #$00 ; STA $2000 ; JMP $C000`, so it
        // generates a PPU-register write ($2000) every iteration.
        let mut bytes = alloc::vec![0u8; 16 + 16 * 1024];
        bytes[0..4].copy_from_slice(b"NES\x1A");
        bytes[4] = 1; // 1x16KB PRG
        bytes[5] = 1; // 1x8KB CHR (unused here)
        let prg = &mut bytes[16..16 + 16 * 1024];
        // $C000 maps to PRG offset 0.
        prg[0..8].copy_from_slice(&[0xA9, 0x00, 0x8D, 0x00, 0x20, 0x4C, 0x00, 0xC0]);
        let len = 16 * 1024;
        prg[len - 4] = 0x00; // reset vector lo
        prg[len - 3] = 0xC0; // reset vector hi -> $C000
        // CHR not appended (header says 1 bank but parse tolerates; use 0 banks).
        bytes[5] = 0;

        let mut nes = Nes::from_rom(&bytes).expect("parse");
        let _ = nes.run_frame(); // warm past the power-on frame-complete latch.
        assert!(nes.events().is_empty(), "off by default");
        nes.set_event_logging(true);
        let _ = nes.run_frame();
        let evs = nes.events();
        assert!(!evs.is_empty(), "the STA $2000 loop produces writes");
        assert!(
            evs.iter().all(|e| e.kind == EventKind::PpuWrite
                && e.addr == 0x2000
                && e.dot <= 340
                && e.value == 0x00),
            "all events are $2000 PPU writes of $00 with a sane dot"
        );
        // Reset per frame: the count stays one-frame-bounded. The event log is
        // capped at `EVENT_CAP` (20_000, private to the bus module) — distinct
        // from the looser instruction-trace `TRACE_CAP` — so assert that bound.
        let _ = nes.run_frame();
        assert!(nes.events().len() <= 20_000, "bounded by EVENT_CAP");
        nes.set_event_logging(false);
        assert!(!nes.event_logging());
    }

    /// v2.3.2 "Lucid" Phase 1 — the write-attribution oracle.
    ///
    /// The claim under test is the whole point of the feature: for a byte in the
    /// PPU's own memory, the store reports the PC of the instruction that put it
    /// there. The ROM is written so the answer is known independently — a single
    /// `STA $2007` at a fixed address — and the expectation is pinned to that
    /// address rather than to whatever the implementation happens to record.
    #[cfg(feature = "debug-hooks")]
    #[test]
    fn write_attribution_names_the_instruction_that_wrote_a_nametable_byte() {
        // NROM at $C000:
        //   C000: A9 21     LDA #$21        ; VRAM addr hi
        //   C002: 8D 06 20  STA $2006
        //   C005: A9 08     LDA #$08        ; VRAM addr lo -> $2108
        //   C007: 8D 06 20  STA $2006
        //   C00A: A9 5A     LDA #$5A        ; the byte
        //   C00C: 8D 07 20  STA $2007       <-- the write under test
        //   C00F: 4C 00 C0  JMP $C000       ; loop the whole sequence
        //
        // The sequence LOOPS rather than spinning after one pass, and the test
        // runs several frames, because the PPU ignores `$2000/$2001/$2005/$2006`
        // writes for ~29,658 CPU cycles after reset (the documented post-reset
        // mask window, `PpuRegion::post_reset_mask_cycles`). A single pass at
        // power-on would have its two `$2006` stores dropped, leaving `v == 0`,
        // and the `$2007` write would land in CHR space instead of a nametable.
        const STA_2007_PC: u16 = 0xC00C;
        const VRAM_ADDR: u16 = 0x2108;
        const VALUE: u8 = 0x5A;

        let mut bytes = alloc::vec![0u8; 16 + 16 * 1024];
        bytes[0..4].copy_from_slice(b"NES\x1A");
        bytes[4] = 1; // 1x16KB PRG
        bytes[5] = 0; // no CHR bank appended
        let prg = &mut bytes[16..16 + 16 * 1024];
        prg[0..18].copy_from_slice(&[
            0xA9, 0x21, // LDA #$21
            0x8D, 0x06, 0x20, // STA $2006
            0xA9, 0x08, // LDA #$08
            0x8D, 0x06, 0x20, // STA $2006
            0xA9, VALUE, // LDA #$5A
            0x8D, 0x07, 0x20, // STA $2007
            0x4C, 0x00, 0xC0, // JMP $C000
        ]);
        let len = 16 * 1024;
        prg[len - 4] = 0x00; // reset vector lo
        prg[len - 3] = 0xC0; // reset vector hi -> $C000

        let mut nes = Nes::from_rom(&bytes).expect("parse");
        assert!(
            nes.write_attribution().is_none(),
            "attribution is off by default"
        );
        nes.set_write_attribution(true);
        // Three frames: one to clear the post-reset write-mask window, the rest
        // so the loop's `$2006`/`$2007` sequence lands for real.
        for _ in 0..3 {
            let _ = nes.run_frame();
        }

        // Resolve the address the way the emulator does, through the mapper's
        // mirroring, rather than hardcoding `& 0x07FF`. The previous version of
        // this line claimed to do that and then hardcoded it anyway (review
        // catch on PR #356) — which would have masked a mirroring regression.
        let off = nes
            .ciram_offset_for_nametable_addr(VRAM_ADDR)
            .expect("a nametable address resolves to a CIRAM offset");
        let attrib = nes.write_attribution().expect("armed");
        let rec = attrib
            .ciram(off)
            .expect("the STA $2007 wrote this CIRAM byte");
        assert_eq!(
            rec.pc, STA_2007_PC,
            "the byte is attributed to the STA $2007, not to the $2006 stores \
             that set the address or to the LDA that loaded the value"
        );
        assert_eq!(rec.value, VALUE);
        // The byte really is there — attribution must describe a write that
        // actually happened, not a write the tap merely observed being issued.
        assert_eq!(nes.vram()[off], VALUE);
        // And the cycle stamp is a real one from this run.
        assert!(rec.cycle > 0, "cycle stamp taken from the executing CPU");

        // An untouched byte reports nothing rather than a plausible-looking zero.
        assert_eq!(attrib.ciram(off ^ 0x0400), None);

        // Disarming frees the store; re-arming starts clean.
        nes.set_write_attribution(false);
        assert!(nes.write_attribution().is_none());
    }

    /// v2.3.2 "Lucid" phase 2 — the per-pixel provenance oracle.
    ///
    /// Builds a screen out of a known nametable byte and a known palette, then
    /// checks that the record for a background pixel names the addresses that
    /// actually produced it. The load-bearing assertion is `nt_addr`: it must be
    /// the address of the tile ON SCREEN, which is two tiles behind whatever `v`
    /// holds at emit time — the single mistake this whole cascade exists to
    /// prevent.
    #[cfg(feature = "debug-hooks")]
    #[test]
    fn pixel_provenance_names_the_displayed_tile_not_the_fetch_pointer() {
        use rustynes_ppu::PixelLayer;

        // NROM with CHR-RAM. The program:
        //   * fills nametable $2000 with tile $01,
        //   * writes a non-zero pattern for tile $01 into CHR-RAM,
        //   * sets palette entry $3F01 to a known color,
        //   * enables background rendering,
        //   * spins.
        //
        // Assembled by hand below; addresses are named so the assertions can
        // reference the instruction rather than a magic number.
        let mut bytes = alloc::vec![0u8; 16 + 16 * 1024];
        bytes[0..4].copy_from_slice(b"NES\x1A");
        bytes[4] = 1; // 1x16KB PRG
        bytes[5] = 0; // 0 CHR banks => CHR-RAM, so the pattern is writable
        let prg = &mut bytes[16..16 + 16 * 1024];

        #[rustfmt::skip]
        let code: &[u8] = &[
            // --- Delay ~328k cycles (~11 frames) BEFORE touching any PPU
            // register. The PPU ignores $2000/$2001/$2005/$2006 writes for
            // ~29,658 CPU cycles after reset; setup that runs inside that window
            // has its $2006 address writes silently dropped, so every subsequent
            // $2007 lands somewhere unintended. Found by this test failing.
            0xA2, 0x00,                         // C000 LDX #$00
            0xA0, 0x00,                         // C002 LDY #$00
            0x88,                               // C004 DEY
            0xD0, 0xFD,                         // C005 BNE $C004
            0xCA,                               // C007 DEX
            0xD0, 0xF8,                         // C008 BNE $C002
            // --- CHR-RAM: tile $01 rows 0..7 low plane = $FF (all pixels idx 1)
            0xA9, 0x00, 0x8D, 0x06, 0x20,       // C00A LDA #$00 / STA $2006
            0xA9, 0x10, 0x8D, 0x06, 0x20,       // C00F LDA #$10 / STA $2006  -> $0010
            0xA2, 0x08,                         // C014 LDX #$08
            0xA9, 0xFF,                         // C016 LDA #$FF
            0x8D, 0x07, 0x20,                   // C018 STA $2007  (8x low plane)
            0xCA, 0xD0, 0xFA,                   // C01B DEX / BNE $C018
            // --- palette: $3F00 = $0F (black), $3F01 = $16 (red)
            0xA9, 0x3F, 0x8D, 0x06, 0x20,       // C01E LDA #$3F / STA $2006
            0xA9, 0x00, 0x8D, 0x06, 0x20,       // C023 LDA #$00 / STA $2006  -> $3F00
            0xA9, 0x0F, 0x8D, 0x07, 0x20,       // C028 LDA #$0F / STA $2007
            0xA9, 0x16, 0x8D, 0x07, 0x20,       // C02D LDA #$16 / STA $2007
            // --- nametable + attributes $2000..$23FF = $01
            0xA9, 0x20, 0x8D, 0x06, 0x20,       // C032 LDA #$20 / STA $2006
            0xA9, 0x00, 0x8D, 0x06, 0x20,       // C037 LDA #$00 / STA $2006  -> $2000
            0xA0, 0x04,                         // C03C LDY #$04     (4 x 256)
            0xA2, 0x00,                         // C03E LDX #$00
            0xA9, 0x01,                         // C040 LDA #$01
            0x8D, 0x07, 0x20,                   // C042 STA $2007
            0xCA, 0xD0, 0xFA,                   // C045 DEX / BNE $C042
            0x88, 0xD0, 0xF3,                   // C048 DEY / BNE $C03E
            // --- enable BG: $2000 = $00 (BG pattern table $0000, NT $2000),
            //     $2001 = $08 (show BG, but NOT the leftmost 8 px)
            0xA9, 0x00, 0x8D, 0x00, 0x20,       // C04B LDA #$00 / STA $2000
            0xA9, 0x08, 0x8D, 0x01, 0x20,       // C050 LDA #$08 / STA $2001
            0x4C, 0x55, 0xC0,                   // C055 JMP $C055  (spin)
        ];
        prg[..code.len()].copy_from_slice(code);
        let len = 16 * 1024;
        prg[len - 4] = 0x00; // reset vector -> $C000
        prg[len - 3] = 0xC0;

        let mut nes = Nes::from_rom(&bytes).expect("parse");
        // Enough frames for the delay loop, then the setup loops, to complete
        // and for rendering to be running steadily.
        for _ in 0..16 {
            let _ = nes.run_frame();
        }
        assert!(nes.pixel_provenance().is_none(), "off by default");
        nes.set_pixel_provenance(true);
        let _ = nes.run_frame();

        let prov = nes.pixel_provenance().expect("armed");

        // Pixel (16, 0) sits in tile column 2 of row 0, i.e. nametable $2002.
        let rec = prov.get(16, 0).expect("on-screen");
        assert_eq!(
            rec.layer,
            PixelLayer::Background,
            "the all-$FF pattern makes every BG pixel opaque"
        );
        assert_eq!(
            rec.nt_addr, 0x2002,
            "the record must name the tile ON SCREEN at x=16; `v` at emit time \
             has already advanced two tiles past it, so a value near $2004 here \
             would mean the cascade is not tracking the shifters"
        );
        assert_eq!(rec.at_addr, 0x23C0, "tile (2,0) -> attribute byte 0");
        assert_eq!(rec.bg_idx, 1, "low plane $FF, high plane $00 -> index 1");
        assert_eq!(rec.palette_addr, 0x3F01, "palette group 0, index 1");
        assert_eq!(rec.palette_index, 1);
        assert_eq!(rec.color, 0x16, "the red we wrote to $3F01");
        assert_eq!(rec.scanline, 0);
        assert_eq!(rec.dot, 17, "screen X is dot - 1");
        assert_eq!(
            rec.sprite_slot,
            rustynes_ppu::SPRITE_SLOT_NONE,
            "no sprites in this ROM"
        );
        // Fine-Y is 2, not 0, and that is correct: the ROM sets the scroll only
        // via `$2006 = $20, $00`, which loads `v = t = $2000` — and bits 12-14 of
        // a VRAM address ARE the fine-Y field, so `$2000` means fine-Y = 2. A ROM
        // that wanted row 0 would have written `$2005` afterwards. The record
        // reports what the hardware is actually displaying.
        assert_eq!(rec.fine_y, 2, "$2006 = $2000 puts fine-Y at 2");
        // Tile $01 base $0010, plus fine-Y 2.
        assert_eq!(rec.pattern_addr, 0x0012);

        // The cascade advances ONE TILE PER GROUP across the scanline — it is
        // not a single address held for the whole line, and not skewed by the
        // two dummy nametable fetches at dots 337-340.
        for (x, want_nt) in [(0usize, 0x2000u16), (8, 0x2001), (24, 0x2003), (40, 0x2005)] {
            assert_eq!(
                prov.get(x, 0).expect("on-screen").nt_addr,
                want_nt,
                "tile column at x={x}"
            );
        }

        // Off-screen queries answer `None` rather than clamping to a pixel the
        // caller did not ask about.
        assert_eq!(prov.get(256, 0), None);
        assert_eq!(prov.get(0, 240), None);

        nes.set_pixel_provenance(false);
        assert!(nes.pixel_provenance().is_none());
    }

    /// The two halves compose: provenance gives the palette index, attribution
    /// gives the instruction that wrote it. This is the end-to-end claim the
    /// feature exists to support.
    #[cfg(feature = "debug-hooks")]
    #[test]
    fn provenance_and_attribution_compose_into_a_causal_chain() {
        // Minimal ROM: set $3F00 (backdrop) to a known color from a known PC,
        // then spin. Rendering stays off, so every pixel is the backdrop and the
        // chain is unambiguous.
        //   C000: LDA #$3F / STA $2006
        //   C005: LDA #$00 / STA $2006      -> v = $3F00
        //   C00A: LDA #$21 / STA $2007      <-- the palette write
        //   C00F: JMP $C000
        const STA_2007_PC: u16 = 0xC00C;
        const COLOR: u8 = 0x21;

        let mut bytes = alloc::vec![0u8; 16 + 16 * 1024];
        bytes[0..4].copy_from_slice(b"NES\x1A");
        bytes[4] = 1;
        bytes[5] = 0;
        let prg = &mut bytes[16..16 + 16 * 1024];
        prg[0..18].copy_from_slice(&[
            0xA9, 0x3F, 0x8D, 0x06, 0x20, // LDA #$3F / STA $2006
            0xA9, 0x00, 0x8D, 0x06, 0x20, // LDA #$00 / STA $2006
            0xA9, COLOR, 0x8D, 0x07, 0x20, // LDA #$21 / STA $2007
            0x4C, 0x00, 0xC0, // JMP $C000
        ]);
        let len = 16 * 1024;
        prg[len - 4] = 0x00;
        prg[len - 3] = 0xC0;

        let mut nes = Nes::from_rom(&bytes).expect("parse");
        let _ = nes.run_frame();
        nes.set_pixel_provenance(true);
        nes.set_write_attribution(true);
        for _ in 0..3 {
            let _ = nes.run_frame();
        }

        // Step 1: which palette entry produced this pixel?
        let rec = nes
            .pixel_provenance()
            .and_then(|p| p.get(100, 100))
            .expect("armed and on-screen");
        assert_eq!(rec.layer, rustynes_ppu::PixelLayer::Backdrop);
        assert_eq!(rec.palette_index, 0, "the universal backdrop");
        assert_eq!(rec.color, COLOR);

        // Step 2: who wrote that palette entry?
        let who = nes
            .write_attribution()
            .and_then(|a| a.palette(rec.palette_index as usize))
            .expect("the STA $2007 wrote it");
        assert_eq!(
            who.pc, STA_2007_PC,
            "the chain closes: pixel -> palette entry -> writing instruction"
        );
        assert_eq!(who.value, COLOR);
    }

    /// An OAM DMA burst moves 256 bytes but has exactly one cause. The store
    /// must say so — attributing all 256 to the `STA $4014` that triggered them
    /// rather than inventing a per-byte PC that no instruction ever had.
    #[cfg(feature = "debug-hooks")]
    #[test]
    fn oam_dma_attributes_all_256_bytes_to_the_triggering_store() {
        // NROM at $C000:
        //   C000: A9 02     LDA #$02
        //   C002: 8D 14 40  STA $4014   <-- one instruction, 256 OAM bytes
        //   C005: 4C 00 C0  JMP $C000
        //
        // `$4014` is not subject to the PPU's post-reset write-mask window, so
        // this lands on the first pass; the loop just keeps it landing.
        const STA_4014_PC: u16 = 0xC002;

        let mut bytes = alloc::vec![0u8; 16 + 16 * 1024];
        bytes[0..4].copy_from_slice(b"NES\x1A");
        bytes[4] = 1;
        bytes[5] = 0;
        let prg = &mut bytes[16..16 + 16 * 1024];
        prg[0..8].copy_from_slice(&[
            0xA9, 0x02, // LDA #$02
            0x8D, 0x14, 0x40, // STA $4014
            0x4C, 0x00, 0xC0, // JMP $C000
        ]);
        let len = 16 * 1024;
        prg[len - 4] = 0x00;
        prg[len - 3] = 0xC0;

        let mut nes = Nes::from_rom(&bytes).expect("parse");
        // The first `run_frame` after power-on returns on the already-latched
        // frame-complete flag, executing almost no instructions — the same
        // warm-up the event-viewer tests need. Arm AFTER it, so the assertion
        // below is about a frame that actually ran code.
        let _ = nes.run_frame();
        nes.set_write_attribution(true);
        let _ = nes.run_frame();

        let attrib = nes.write_attribution().expect("armed");
        for idx in 0..=u8::MAX {
            let rec = attrib
                .oam(idx)
                .unwrap_or_else(|| panic!("OAM byte {idx} unattributed after a full DMA burst"));
            assert_eq!(
                rec.pc, STA_4014_PC,
                "OAM byte {idx} must name the STA $4014, not a synthesized PC"
            );
        }
    }

    /// A save-state restore must invalidate attribution: the restored bytes were
    /// not written by anything this session ran, so the honest answer is "no
    /// record", not the PC that wrote that offset on the abandoned timeline.
    #[cfg(feature = "debug-hooks")]
    #[test]
    fn write_attribution_is_invalidated_by_restore() {
        let mut bytes = alloc::vec![0u8; 16 + 16 * 1024];
        bytes[0..4].copy_from_slice(b"NES\x1A");
        bytes[4] = 1;
        bytes[5] = 0;
        let prg = &mut bytes[16..16 + 16 * 1024];
        // Same looping `$2006`/`$2007` ROM as the test above; see its comment for
        // why it loops and why three frames are needed.
        prg[0..18].copy_from_slice(&[
            0xA9, 0x21, 0x8D, 0x06, 0x20, 0xA9, 0x08, 0x8D, 0x06, 0x20, 0xA9, 0x5A, 0x8D, 0x07,
            0x20, 0x4C, 0x00, 0xC0,
        ]);
        let len = 16 * 1024;
        prg[len - 4] = 0x00;
        prg[len - 3] = 0xC0;

        let mut nes = Nes::from_rom(&bytes).expect("parse");
        nes.set_write_attribution(true);
        for _ in 0..3 {
            let _ = nes.run_frame();
        }
        let off = 0x0108usize;
        assert!(
            nes.write_attribution().and_then(|a| a.ciram(off)).is_some(),
            "precondition: the write was attributed"
        );

        let snap = nes.snapshot();
        nes.restore(&snap).expect("round-trip");
        assert!(
            nes.write_attribution().is_some(),
            "the store stays armed across a restore"
        );
        assert_eq!(
            nes.write_attribution().and_then(|a| a.ciram(off)),
            None,
            "but its records are dropped — they describe a timeline that the \
             restore replaced"
        );
    }

    #[cfg(feature = "debug-hooks")]
    #[test]
    fn event_viewer_records_ppu_reads() {
        use crate::bus::EventKind;
        // A tiny NROM that loops `LDA $2002 ; JMP $C000`, generating a PPU
        // STATUS read ($2002) every iteration (v1.5.0 Workstream A2 read tap).
        let mut bytes = alloc::vec![0u8; 16 + 16 * 1024];
        bytes[0..4].copy_from_slice(b"NES\x1A");
        bytes[4] = 1; // 1x16KB PRG
        let prg = &mut bytes[16..16 + 16 * 1024];
        // $C000: LDA $2002 ; JMP $C000
        prg[0..6].copy_from_slice(&[0xAD, 0x02, 0x20, 0x4C, 0x00, 0xC0]);
        let len = 16 * 1024;
        prg[len - 4] = 0x00;
        prg[len - 3] = 0xC0;

        let mut nes = Nes::from_rom(&bytes).expect("parse");
        let _ = nes.run_frame();
        nes.set_event_logging(true);
        let _ = nes.run_frame();
        let evs = nes.events();
        assert!(
            evs.iter()
                .any(|e| e.kind == EventKind::PpuRead && e.addr == 0x2002),
            "the LDA $2002 loop produces PPU reads"
        );
        assert!(
            evs.iter()
                .all(|e| e.kind.is_read() == (e.kind == EventKind::PpuRead)),
            "is_read is true only for PpuRead"
        );
        nes.set_event_logging(false);
    }

    #[cfg(feature = "debug-hooks")]
    #[test]
    fn event_breakpoint_fires_on_armed_category_only() {
        use crate::EventBpKind;
        // The same `LDA #$00 ; STA $2000 ; JMP $C000` loop — it issues a PPU
        // write every iteration but never an APU write or interrupt service.
        let mut bytes = alloc::vec![0u8; 16 + 16 * 1024];
        bytes[0..4].copy_from_slice(b"NES\x1A");
        bytes[4] = 1;
        bytes[5] = 0;
        let prg = &mut bytes[16..16 + 16 * 1024];
        prg[0..8].copy_from_slice(&[0xA9, 0x00, 0x8D, 0x00, 0x20, 0x4C, 0x00, 0xC0]);
        let len = 16 * 1024;
        prg[len - 4] = 0x00;
        prg[len - 3] = 0xC0;

        let mut nes = Nes::from_rom(&bytes).expect("parse");
        let _ = nes.run_frame(); // warm past the power-on frame-complete latch.

        // Default: nothing armed, no hits.
        assert_eq!(nes.event_breakpoints(), 0, "disarmed by default");
        let _ = nes.run_frame();
        assert_eq!(nes.take_event_break_hit(), None, "no hit while disarmed");

        // Arm an UNRELATED category (APU write): the $2000 loop never trips it.
        nes.set_event_breakpoints(EventBpKind::ApuWrite.bit());
        let _ = nes.run_frame();
        assert_eq!(
            nes.take_event_break_hit(),
            None,
            "wrong category does not fire"
        );

        // Arm PPU write: the very next frame must latch a hit with sane context.
        nes.set_event_breakpoints(EventBpKind::PpuWrite.bit());
        let _ = nes.run_frame();
        let hit = nes.take_event_break_hit().expect("PPU write fires");
        assert_eq!(hit.kind, EventBpKind::PpuWrite);
        assert_eq!(hit.addr, 0x2000, "the STA $2000 target");
        assert!(hit.dot <= 340, "dot in range");
        assert!(
            hit.scanline >= -1 && hit.scanline <= 260,
            "scanline in range"
        );
        // Cleared on read + only one (first) hit recorded per frame.
        assert_eq!(nes.take_event_break_hit(), None, "cleared on read");

        // Disarming all stops it firing again.
        nes.set_event_breakpoints(0);
        let _ = nes.run_frame();
        assert_eq!(nes.take_event_break_hit(), None, "disarmed: silent");
    }

    #[cfg(feature = "debug-hooks")]
    #[test]
    fn event_bp_kind_mask_and_labels_are_distinct() {
        use crate::EventBpKind;
        let all = EventBpKind::all();
        // Every category has a distinct bit and a non-empty label.
        let mut seen = 0u16;
        for k in all {
            assert_eq!(seen & k.bit(), 0, "{} bit collides", k.label());
            seen |= k.bit();
            assert_ne!(k.label(), "");
        }
        assert_eq!(seen.count_ones() as usize, all.len(), "11 distinct bits");
    }

    #[test]
    fn debug_snapshots_are_read_only() {
        // T-53-002+ -- inspection must not advance emulator state.
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        for _ in 0..2 {
            nes.run_frame();
        }
        let cycle_before = nes.cycle();
        let _cpu = nes.cpu_snapshot();
        let _ppu = nes.ppu_snapshot();
        let _apu = nes.apu_snapshot();
        let _oam = nes.oam();
        let _pal = nes.palette_ram();
        let _mapper = nes.mapper_info();
        // cpu_bus_peek and pattern_table_rgba take &mut so we exercise them too.
        let _byte = nes.cpu_bus_peek(0xC000);
        let _byte = nes.ppu_bus_peek(0x2000);
        let pt = nes.pattern_table_rgba(0);
        assert_eq!(pt.len(), 128 * 128 * 4, "pattern table RGBA size");
        let nt = nes.nametable_rgba(0);
        assert_eq!(nt.len(), 256 * 240 * 4, "nametable RGBA size");
        assert_eq!(nes.cycle(), cycle_before, "inspection MUST NOT tick CPU");
    }

    #[test]
    fn disassembler_round_trips_against_cpu_bus() {
        // Walk a small synthesized program through the disassembler.
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        let pc = nes.cpu().pc;
        // Take a fixed-size byte window via the peek API first; disasm
        // wants a `Fn`, and our peek is `FnMut`.
        let mut buf = [0u8; 16];
        for (i, b) in buf.iter_mut().enumerate() {
            *b = nes.cpu_bus_peek(pc.wrapping_add(u16::try_from(i).unwrap_or(0)));
        }
        let lines = rustynes_cpu::disassemble_at(
            |a| {
                let off = a.wrapping_sub(pc) as usize;
                buf.get(off).copied().unwrap_or(0)
            },
            pc,
            4,
        );
        assert_eq!(lines.len(), 4);
        // First instruction is JMP $C000 (0x4C 0x00 0xC0).
        assert_eq!(lines[0].addr, pc);
        assert_eq!(lines[0].mnemonic, "JMP");
    }

    #[test]
    fn rom_sha256_is_deterministic() {
        let rom = synth_nrom(16, 8);
        let nes_a = Nes::from_rom(&rom).unwrap();
        let nes_b = Nes::from_rom(&rom).unwrap();
        assert_eq!(nes_a.rom_sha256(), nes_b.rom_sha256());
        // Different ROM -> different hash.
        let mut other = synth_nrom(16, 8);
        other[0x10] = 0x99;
        let nes_c = Nes::from_rom(&other).unwrap();
        assert_ne!(nes_a.rom_sha256(), nes_c.rom_sha256());
    }

    /// v2.9.8: the persistent identity ignores the 16-byte header, so a
    /// load-time header correction cannot rename a game's saves; the
    /// whole-image hash (the Vs. database's fallback key) still sees the header.
    #[test]
    fn rom_identity_ignores_the_header_and_image_hash_does_not() {
        let rom = synth_nrom(16, 8);
        let mut reheaded = rom.clone();
        // Bytes 10-15 are unused padding in an iNES 1.0 header, so this is a
        // pure header edit on the same board.
        reheaded[12] = 0x01;
        let a = Nes::from_rom(&rom).unwrap();
        let b = Nes::from_rom(&reheaded).unwrap();
        assert_eq!(
            a.rom_sha256(),
            b.rom_sha256(),
            "header edit renamed the ROM"
        );
        assert_eq!(a.rom_hash_tag(), b.rom_hash_tag());
        assert_ne!(a.image_sha256(), b.image_sha256());
        // Exactly the body: the identity is SHA-256 of bytes[16..].
        assert_eq!(*a.rom_sha256(), sha256_of(&rom[16..]));
        assert_eq!(*a.image_sha256(), sha256_of(&rom));
    }

    /// v2.9.9 (NF-21) — `rom_identity_of` is the identity a console built
    /// from the same image reports, for each image kind.
    #[test]
    fn rom_identity_of_matches_the_built_console() {
        let rom = synth_nrom(16, 8);
        assert_eq!(
            Nes::rom_identity_of(&rom),
            *Nes::from_rom(&rom).unwrap().rom_sha256()
        );
        let disk = synth_fds_disk();
        let fds = Nes::from_disk(&disk, &synth_fds_bios()).unwrap();
        assert_eq!(Nes::rom_identity_of(&disk), *fds.rom_sha256());
        let nsf = synth_tone_nsf();
        let tune = Nes::from_nsf(&nsf).unwrap();
        assert_eq!(Nes::rom_identity_of(&nsf), *tune.rom_sha256());
        // And it is not the whole-file hash for a cartridge.
        assert_ne!(Nes::rom_identity_of(&rom), sha256_of(&rom));
    }

    /// A synthetic 8 KiB FDS BIOS: `JMP $E000` at the reset vector and an
    /// `RTI` for NMI / IRQ. Enough for the disk constructors to boot.
    fn synth_fds_bios() -> Vec<u8> {
        let mut bios = vec![0u8; 8 * 1024];
        bios[..3].copy_from_slice(&[0x4C, 0x00, 0xE0]); // $E000: JMP $E000
        bios[0x80] = 0x40; // $E080: RTI
        bios[0x1FFA..].copy_from_slice(&[0x80, 0xE0, 0x00, 0xE0, 0x80, 0xE0]);
        bios
    }

    /// A one-sided fwNES-headed disk: the disk-info block signature is all the
    /// container parser needs.
    fn synth_fds_disk() -> Vec<u8> {
        let mut disk = vec![0u8; 16 + 65_500];
        disk[..4].copy_from_slice(b"FDS\x1A");
        disk[4] = 1;
        disk[16] = 0x01;
        disk[17..31].copy_from_slice(b"*NINTENDO-HVC*");
        disk
    }

    /// v2.9.9 (NF-17) — a console booted from a saved copy of an FDS disk
    /// reports the pristine disk's identity once the host supplies it, so
    /// everything keyed on `rom_sha256` (slots and the `.rns` tag, cheats,
    /// movies, netplay, per-game keys, RA progress) survives the game's own
    /// disk saves. `image_sha256` keeps describing the bytes in hand.
    #[test]
    fn a_saved_disk_boot_reports_the_pristine_identity() {
        let bios = synth_fds_bios();
        let pristine = synth_fds_disk();
        let pristine_sha = *Nes::from_disk(&pristine, &bios).unwrap().rom_sha256();
        // The game wrote to its disk; the host boots the written image.
        let mut saved = pristine;
        saved[16 + 0x40] = 0x5A;
        let mut booted = Nes::from_disk(&saved, &bios).unwrap();
        let saved_sha = *booted.rom_sha256();
        assert_ne!(saved_sha, pristine_sha, "fixture: the images differ");

        booted.set_rom_identity(pristine_sha);
        assert_eq!(
            *booted.rom_sha256(),
            pristine_sha,
            "a disk save moved the game's identity"
        );
        assert_eq!(booted.rom_hash_tag()[..], pristine_sha[..ROM_HASH_TAG_LEN]);
        assert_eq!(
            *booted.image_sha256(),
            saved_sha,
            "the image hash must stay the bytes actually loaded"
        );
        // The identity is not state: a cold boot keeps it.
        booted.power_cycle();
        assert_eq!(*booted.rom_sha256(), pristine_sha);
    }

    #[test]
    fn thumbnail_has_expected_dimensions() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        nes.run_frame();
        let thumb = nes.thumbnail();
        assert_eq!(thumb.len(), save_state::THUMBNAIL_LEN);
        assert_eq!(
            save_state::THUMBNAIL_LEN,
            save_state::THUMBNAIL_WIDTH * save_state::THUMBNAIL_HEIGHT * 4
        );
    }

    #[test]
    fn snapshot_includes_thumbnail_section_extractable() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        for _ in 0..2 {
            nes.run_frame();
        }
        let blob = nes.snapshot();
        let extracted = Nes::extract_thumbnail(&blob).expect("blob is valid");
        let thumb = extracted.expect("snapshot must include THM section");
        assert_eq!(thumb.len(), save_state::THUMBNAIL_LEN);
        // Round-trip: thumbnail bytes must match the live framebuffer
        // downsample taken at the same cycle.
        assert_eq!(thumb, nes.thumbnail());
    }

    #[test]
    fn snapshot_round_trip_still_works_with_thumbnail() {
        // ADR-0003 invariant: adding THM must not perturb deterministic
        // restore. Re-runs the snapshot_round_trip test with the new
        // thumbnail section present in the blob.
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        for _ in 0..4 {
            nes.run_frame();
        }
        let cycle = nes.cycle();
        let fb_hash_before = fnv_hash(nes.framebuffer());
        let blob = nes.snapshot();
        for _ in 0..4 {
            nes.run_frame();
        }
        assert_ne!(nes.cycle(), cycle);
        nes.restore(&blob)
            .expect("restore must succeed with THM present");
        assert_eq!(nes.cycle(), cycle);
        assert_eq!(fnv_hash(nes.framebuffer()), fb_hash_before);
    }

    #[test]
    fn restore_accepts_v0_9_0_blob_without_thumbnail() {
        // ADR-0003 invariant: older slot files without a THM section must
        // still restore. Simulate a v0.9.0 blob by stripping the THM
        // section out of a freshly-emitted snapshot.
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        for _ in 0..3 {
            nes.run_frame();
        }
        let cycle = nes.cycle();
        let fb_hash = fnv_hash(nes.framebuffer());
        let with_thumb = nes.snapshot();

        // Reconstruct a blob without the THM section.
        let (_h, body_off) = save_state::parse_header(&with_thumb).unwrap();
        let mut without_thumb = with_thumb[..body_off].to_vec();
        for s in save_state::SectionIter::new(&with_thumb[body_off..]) {
            let s = s.unwrap();
            if s.tag == save_state::tag::THM {
                continue;
            }
            save_state::write_section(&mut without_thumb, s.tag, s.version, s.body);
        }
        assert!(without_thumb.len() < with_thumb.len());
        // Extract on the v0.9.0-shaped blob returns None for the thumbnail.
        let extracted = Nes::extract_thumbnail(&without_thumb).unwrap();
        assert!(extracted.is_none(), "v0.9.0 blob has no THM section");

        // Drift then restore from the v0.9.0-shaped blob.
        for _ in 0..2 {
            nes.run_frame();
        }
        nes.restore(&without_thumb)
            .expect("v0.9.0 blob must restore");
        assert_eq!(nes.cycle(), cycle);
        assert_eq!(fnv_hash(nes.framebuffer()), fb_hash);
    }

    #[test]
    fn restore_accepts_a_snapshot_followed_by_zero_padding() {
        // v2.8.0 (libretro audit §2.2, with §2.1). The libretro core reports a
        // `retro_serialize_size` with headroom for expansion devices, so the
        // frontend hands `retro_unserialize` this core's own state followed by
        // zeros. Both restore paths walk the sections (`SystemBus::restore`
        // for BUS/PPU/APU/MAP, then `apply_snapshot` for CPU), so both must end
        // at the padding rather than report it as a damaged section.
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        for _ in 0..3 {
            nes.run_frame();
        }
        let cycle = nes.cycle();
        let fb_hash = fnv_hash(nes.framebuffer());
        let mut blob = Vec::new();
        nes.snapshot_core_into(&mut blob);
        for pad in [1, 8, 9, 10, 26, 160] {
            let mut padded = blob.clone();
            padded.resize(blob.len() + pad, 0);
            nes.run_frame();
            nes.restore_quiet(&padded)
                .unwrap_or_else(|e| panic!("{pad} bytes of zero padding: {e:?}"));
            assert_eq!(nes.cycle(), cycle, "{pad}: cycle restored");
            assert_eq!(
                fnv_hash(nes.framebuffer()),
                fb_hash,
                "{pad}: framebuffer restored"
            );
        }
    }

    #[test]
    fn restore_rejects_every_truncation_even_with_the_zero_tail_rule() {
        // v2.8.0, review on #556 (agy). `SectionIter` now ends at an all-zero
        // tail, so the question is whether a TRUNCATED state (a short file:
        // a frontend passes `retro_unserialize` a buffer of the file's size
        // and does not pad it) could now pass as a complete one that happens
        // to end in zeros. Every proper prefix of a real snapshot is tried:
        // a cut inside a section leaves a tail that starts with a non-zero
        // tag and a length the remaining bytes cannot satisfy, and a cut on a
        // section boundary drops a required section. Every one is an error.
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse + boot");
        for _ in 0..3 {
            nes.run_frame();
        }
        let mut blob = Vec::new();
        nes.snapshot_core_into(&mut blob);
        let accepted: Vec<usize> = (0..blob.len())
            .filter(|&k| nes.restore_quiet(&blob[..k]).is_ok())
            .collect();
        assert!(
            accepted.is_empty(),
            "{} of {} truncations restored, first at {:?}",
            accepted.len(),
            blob.len(),
            accepted.first()
        );
        // The full state still restores after all those rejections.
        nes.restore_quiet(&blob)
            .expect("the untruncated state restores");
    }

    /// Build a minimal NSF (3 songs) whose `init` enables all APU channels and
    /// programs a steady pulse-1 tone, and whose `play` is a bare `RTS`. Loaded
    /// at $8000; init=$8000, play=$800C.
    fn synth_tone_nsf() -> Vec<u8> {
        let mut f = vec![0u8; 0x80];
        f[0..5].copy_from_slice(b"NESM\x1A");
        f[0x05] = 1; // version
        f[0x06] = 3; // total songs
        f[0x07] = 1; // starting song
        f[0x08] = 0x00;
        f[0x09] = 0x80; // load $8000
        f[0x0A] = 0x00;
        f[0x0B] = 0x80; // init $8000
        f[0x0C] = 0x0C;
        f[0x0D] = 0x80; // play $800C
        let program: &[u8] = &[
            // init ($8000): enable channels + a constant-volume pulse-1 tone.
            0xA9, 0x0F, 0x8D, 0x15, 0x40, // LDA #$0F; STA $4015
            0xA9, 0xBF, 0x8D, 0x00, 0x40, // LDA #$BF; STA $4000 (duty/const vol)
            0x60, // RTS
            0xA0, // padding so play lands at $800C
            // play ($800C):
            0x60, // RTS
        ];
        f.extend_from_slice(program);
        f
    }

    #[test]
    fn nsf_constructs_runs_and_selects_tracks() {
        let mut nes = Nes::from_nsf(&synth_tone_nsf()).expect("valid nsf builds");
        assert_eq!(nes.nsf_song_count(), 3);
        assert_eq!(nes.nsf_current_song(), 0);

        // Run several frames: the driver's reset vector runs `init` (enabling
        // the APU + pulse-1), then vblank NMI calls `play` each frame. Audio
        // must be produced and the run must not panic.
        let mut produced = 0usize;
        for _ in 0..8 {
            nes.run_frame();
            produced += nes.drain_audio().len();
        }
        assert!(produced > 0, "NSF playback must produce audio samples");

        // Track select clamps + restarts on the new song.
        nes.nsf_set_song(2);
        assert_eq!(nes.nsf_current_song(), 2);
        nes.run_frame();
        nes.nsf_set_song(99);
        assert_eq!(nes.nsf_current_song(), 2, "clamped to last song");
    }

    /// A minimal non-60-Hz NSF whose `play` routine increments zero-page `$00`,
    /// so a test can count how many times the cycle-timer IRQ drove `play`.
    fn synth_counting_nsf_50hz() -> Vec<u8> {
        let mut f = vec![0u8; 0x80];
        f[0..5].copy_from_slice(b"NESM\x1A");
        f[0x05] = 1; // version
        f[0x06] = 1; // 1 song
        f[0x07] = 1; // starting song
        f[0x08] = 0x00;
        f[0x09] = 0x80; // load $8000
        f[0x0A] = 0x00;
        f[0x0B] = 0x80; // init $8000
        f[0x0C] = 0x06;
        f[0x0D] = 0x80; // play $8006
        // NTSC play-speed divider $6E-$6F = 20000 µs (~50 Hz) — a non-standard
        // rate that selects the cycle-timer IRQ driver instead of vblank-NMI.
        f[0x6E] = 0x20;
        f[0x6F] = 0x4E; // 0x4E20 = 20000
        let program: &[u8] = &[
            // init ($8000): enable APU channels, RTS. (6 bytes)
            0xA9, 0x0F, 0x8D, 0x15, 0x40, 0x60, // play ($8006): INC $00; RTS
            0xE6, 0x00, 0x60,
        ];
        f.extend_from_slice(program);
        f
    }

    #[test]
    fn nsf_nonstandard_rate_drives_play_via_timer_irq() {
        let mut nes = Nes::from_nsf(&synth_counting_nsf_50hz()).expect("valid nsf");
        // 12 NTSC frames ≈ 0.2 s. A ~50 Hz play-timer IRQ must fire `play`
        // (INC $00) several times — proving the cycle-timer IRQ path works
        // end-to-end through `run_frame` — but FEWER than the 12 frames, since
        // 50 Hz is slower than the 60 Hz once-per-vblank rate.
        for _ in 0..12 {
            nes.run_frame();
        }
        let calls = nes.cpu_bus_peek(0x0000);
        assert!(
            calls > 0,
            "timer IRQ must drive `play` at the non-standard rate"
        );
        assert!(
            calls < 12,
            "50 Hz must call `play` fewer times than 60 Hz frames (got {calls})"
        );
    }

    /// v2.3.7: `$4014` and `$4016` must actually be attributed.
    ///
    /// Both sit inside the `$4000-$4017` window the audio-provenance table
    /// reserves slots for, and both are handled entirely on the bus — `Bus::write`
    /// routes only `$4000-$4013 | $4015 | $4017` to `Apu::write_register`, which
    /// is where attribution was recorded. So the two reserved slots could never
    /// be filled, while `docs/audio-provenance.md` and the `REG_COUNT` doc
    /// comment both stated they were "tracked anyway".
    ///
    /// Caught by the Antigravity reviewer on PR #404. This test fails without
    /// `Apu::record_bus_handled_register_write` being called from both bus arms:
    /// remove either call and the corresponding `get()` returns `None`.
    #[cfg(feature = "debug-hooks")]
    #[test]
    fn bus_handled_apu_window_writes_are_attributed() {
        // `Bus::write` is the ordinary CPU write path both addresses travel.
        use rustynes_cpu::Bus as _;

        let mut nes = Nes::from_rom(&synth_nrom(16, 8)).expect("nrom builds");
        nes.set_audio_provenance(true);
        assert!(nes.audio_provenance_armed(), "premise: armed");

        // Pin a known attribution context, then write both bus-handled
        // addresses through the ordinary CPU write path.
        nes.bus.apu.set_attrib_context(0xC123, 4_242);
        nes.bus.write(0x4014, 0x02); // OAM DMA page
        nes.bus.write(0x4016, 0x01); // controller strobe

        let attrib = nes
            .bus
            .apu
            .register_attribution()
            .expect("armed, so the table exists");

        let dma = attrib
            .get(0x4014)
            .expect("$4014 must be attributed — it is inside the reserved window");
        assert_eq!(dma.pc, 0xC123, "$4014 attributed to the wrong instruction");
        assert_eq!(dma.value, 0x02, "$4014 recorded the wrong value");

        let strobe = attrib
            .get(0x4016)
            .expect("$4016 must be attributed — it is inside the reserved window");
        assert_eq!(
            strobe.pc, 0xC123,
            "$4016 attributed to the wrong instruction"
        );
        assert_eq!(strobe.value, 0x01, "$4016 recorded the wrong value");

        // A genuine APU register still works — the new path is additive, not a
        // replacement for the one inside `write_register`.
        nes.bus.write(0x4015, 0x0F);
        assert_eq!(
            attrib_value(&nes, 0x4015),
            Some(0x0F),
            "the normal write_register attribution path must be unaffected"
        );
    }

    /// Small helper so the assertion above reads as one line.
    #[cfg(feature = "debug-hooks")]
    fn attrib_value(nes: &Nes, addr: u16) -> Option<u8> {
        nes.bus
            .apu
            .register_attribution()
            .and_then(|a| a.get(addr))
            .map(|w| w.value)
    }

    #[test]
    fn nsf_song_apis_are_inert_on_a_cartridge() {
        let mut nes = Nes::from_rom(&synth_nrom(16, 8)).expect("nrom builds");
        assert_eq!(nes.nsf_song_count(), 0);
        assert_eq!(nes.nsf_current_song(), 0);
        nes.nsf_set_song(1); // no-op, must not panic or reset spuriously
        assert_eq!(nes.nsf_current_song(), 0);
    }

    /// v2.3.6: the beam-relative Zapper model is ON by default.
    ///
    /// It shipped OFF in v2.2.3-v2.3.5 on the reasoning that no light-gun test
    /// ROM could adjudicate it and the supported titles were satisfied either
    /// way. The second half was false: under the frame-granular model *Duck
    /// Hunt* receives its "dark frame then bright frame" probe inverted and can
    /// never register a hit. See `SystemBus::set_zapper_temporal_light`.
    #[test]
    fn zapper_temporal_light_is_on_by_default() {
        let mut nes = Nes::from_rom(&synth_nrom(16, 8)).expect("nrom builds");
        assert!(
            nes.zapper_temporal_light(),
            "the beam-relative model must default ON from v2.3.6"
        );
        nes.set_zapper(1, 100, 120, false);
        // Toggling it off and back on must restore the default exactly.
        nes.set_zapper_temporal_light(false);
        assert!(!nes.zapper_temporal_light());
        nes.set_zapper_temporal_light(true);
        assert!(nes.zapper_temporal_light());
    }

    /// The timeline counter is session-local: a save state neither carries it nor
    /// restores it, and loading one ADVANCES the live counter instead.
    ///
    /// Documented on the field, and untestable by `snapshot_schema_audit` for the
    /// very reason that makes it true -- the counter lives outside the snapshot,
    /// so that audit cannot see it. Pinned here instead, because the two ways
    /// serializing it would be wrong are both silent: loading the same slot twice
    /// would restore the same generation twice and a consumer would miss the
    /// second load, and a value from another session means nothing in this one.
    #[test]
    fn the_timeline_counter_is_session_local_and_advances_on_restore() {
        let rom = synth_nrom(16, 8);
        let mut nes = Nes::from_rom(&rom).expect("parse");
        nes.run_frame();
        let state = nes.snapshot();
        let before = nes.timeline_generation();

        nes.restore(&state).expect("restore");
        let after_first = nes.timeline_generation();
        assert!(
            after_first > before,
            "a restore must advance the timeline counter: {before} -> {after_first}"
        );

        // The SECOND load of the SAME slot must advance it again. This is the
        // assertion that would fail if the counter were serialized -- the restored
        // value would be identical both times and a consumer comparing against its
        // last-seen value would never notice the second load.
        nes.restore(&state).expect("restore again");
        assert!(
            nes.timeline_generation() > after_first,
            "reloading the same slot must still register as a new timeline"
        );

        // And a snapshot taken now must not encode it: a fresh `Nes` restored from
        // this state starts its own count rather than adopting ours.
        let mut fresh = Nes::from_rom(&rom).expect("parse");
        assert_eq!(
            fresh.timeline_generation(),
            0,
            "a fresh Nes must start at zero"
        );
        fresh.restore(&nes.snapshot()).expect("restore into fresh");
        assert_eq!(
            fresh.timeline_generation(),
            1,
            "the fresh instance must count its own restores, not inherit a stored value"
        );
    }
}