rustynes_ppu/

snapshot.rs

//! Save-state encoding / decoding for the [`Ppu`].
//!
//! Hand-rolled little-endian binary so the crate stays free of `serde` and
//! `bincode`. The container format used by the bus to wrap this blob into
//! a tagged section lives in `rustynes_core::save_state`.
//!
//! Schema version 1 layout (all little-endian, top-down):
//!
//! - `version` u8
//! - region tag u8 (0=NTSC, 1=PAL, 2=Dendy)
//! - `ctrl` u8 / `mask` u8 / `mask_for_skip_check` u8 / `mask_skip_pipe1` u8 / `status` u8
//! - `oam_addr` u8 / `data_buffer` u8
//! - loopy: `v` u16 / `t` u16 / `x` u8 / `w` bool
//! - 2 KiB CIRAM (raw bytes)
//! - 256 B OAM (raw bytes)
//! - 32 B secondary OAM (raw bytes)
//! - 32 B palette RAM (raw bytes)
//! - `open_bus` u8 / 3× `open_bus_decay[i]` u32
//! - `nmi_line` / `suppress_vbl_this_frame` / `last_a12_level` u8
//! - `dot` u16 / `scanline` i16 / `frame` u64 / `frame_complete` bool
//! - `post_reset_mask_remaining` u32
//! - BG latches: `nt_latch` u8 / `at_latch` u8 / `bg_lo_latch` u8 / `bg_hi_latch` u8
//! - BG shifts (v2): `bg_shift_lo` u16 / `bg_shift_hi` u16 / `at_shift_lo` u16 /
//!   `at_shift_hi` u16. (v1 stored `at_shift_*` as u8 + two 1-bit feed bytes.)
//!
//! The versions' tails follow (see [`PPU_SNAPSHOT_VERSION`]). Since v2.9.8
//! (ADR 0042) only the current version is read; the per-version upconversion
//! this module used to carry is gone.
//! - `ex_attr_latch` (presence u8 + `palette` u8 + `chr_bank` u16)
//! - `bg_split_latch` (presence u8 + `nt_addr` u16 + `at_addr` u16 + `fine_y` u8 + `chr_bank` u8)
//! - sprite arrays: 8× `shift_lo` / `shift_hi` / `attr` / `x` / `spr_count` u8 / `spr_zero_in_line` bool
//! - `256*240*4` framebuffer bytes

use alloc::vec::Vec;
use thiserror::Error;

use crate::bus::{BgSplitState, ExAttribute};
use crate::ppu::{FRAMEBUFFER_LEN, Ppu, PpuRegion};
use crate::registers::{PpuCtrl, PpuMask, PpuStatus};

/// Schema version for the PPU snapshot blob.
///
/// - v1: 8-bit `at_shift_lo`/`at_shift_hi` + 1-bit `at_feed_lo`/`at_feed_hi`.
/// - v2: 16-bit `at_shift_lo`/`at_shift_hi` (lockstep with the pattern
///   shifters); the feed fields are gone.
///
/// **Since v2.9.8 (ADR 0042) `Ppu::restore` reads the current version only.**
/// The notes below on how each older version "upconverts" describe the
/// behaviour before then.
/// - v3 (W3-Stage-4 promotion, 2026-06-10): appends the
///   `mc-ppu-2007-render-buffer` rendering-time `$2007` PPUDATA
///   state-machine tail — `render_data_bus`, `ppudata_sm_countdown`,
///   `ppudata_v_inc_pending`, the raw (pre-h-flip) sprite pattern fetch
///   bytes, and the slot-0 garbage-NT ALE latch. Written unconditionally
///   (zeros when the feature is off) so the layout is identical across
///   feature builds; v1/v2 blobs upconvert with the tail at the inactive
///   defaults (the state the old clear-on-restore assumption imposed).
/// - v4 (v1.7.0 F3, 2026-06-18): appends the `extra_lines_remaining`
///   countdown for the in-flight PPU extra-scanlines overclock insertion.
///   At the default `extra_scanlines == 0` this is always `0`, so the
///   blob merely gains a zero `u16` and restore is behaviourally identical
///   to v3; a non-default countdown taken mid-insertion now round-trips
///   instead of restoring as `0` (which desynced). v1/v2/v3 blobs upconvert
///   with `extra_lines_remaining = 0` (no insertion in flight).
/// - v5 (v2.0.3, ADR 0030): appends the 2-cycle-ALE fetch model's in-flight
///   multiplexed-bus / octal-latch state — `octal_latch`, `address_bus`,
///   `ale_armed`, `pattern_latch_stale`, and the delayed-`CopyV` `copy_v_delay`
///   countdown. These fields carry a background fetch's ALE→read state and the
///   two modeled `$2006`/`$2007` corruption one-shots; a mid-render save/restore
///   (netplay rollback checkpoints, TAS/save-states) that landed with any of
///   them live restored them to the wrong value and desynced the re-simulated
///   framebuffer — exactly the class of bug the v3/v4 tails already fixed for
///   the `$2007` state machine and the overclock countdown. This is an ADDITIVE
///   save-state format change (a `.rns` gains the tail): v1..=4 blobs upconvert
///   with all five at their inactive defaults (`0`/`false`), i.e. the
///   "no fetch in flight" rest state, which is correct for any pre-v5 save taken
///   at rest. Not a *load-break* — a pre-v5 `.rns` still restores.
/// - v6 (v2.1.1, "Fathom"): appends the per-sprite shifter-halt flags
///   (`spr_halted[8]`), the 1-dot-delayed rendering gate
///   (`prev_rendering_enabled` / `rendering_enabled_delayed`), and the
///   OAM-corruption arming state (`oam_corruption_pending`,
///   `oam_corruption_index`, `oam_corruption_disabled`,
///   `oam_corruption_disabled_instant`). These fields were previously not
///   serialized; a frontend run-ahead `snapshot`/`restore` round-trip
///   landing with any of them live (mid-frame sprite-0 split, OAM
///   corruption arming) would restore stale constructor values and corrupt
///   rendering — the Wizards & Warriors half-blank playfield / stalled
///   audio class. v1..=5 blobs upconvert with `spr_halted = [true; 8]`
///   (halted = power-on default) and all others at `false`/`0`. Not a
///   *load-break* — a pre-v6 `.rns` still restores.
/// - v7 (v2.1.4 F2.3): appends the optional OAM-decay model's per-8-byte-row
///   last-touch timestamps (`oam_decay_cycles[32]`), stored as a **relative age**
///   (`now - timestamp` in CPU cycles) rather than the raw absolute value. The
///   absolute timestamps reference the free-running `dot_counter`, which is
///   deliberately NOT part of the save-state (it is cosmetic / re-derived); a raw
///   absolute value would be meaningless after a rollback/restore rebased that
///   counter, and would desync the decay clock. Encoding the age and reconstructing
///   `now - age` against the *live* counter on load makes a run-ahead / netplay
///   `snapshot`→`restore` byte-identical to the forward run (the property the
///   v3/v4/v5/v6 tails secured for the other mid-frame state). The enable flag
///   itself is a frontend/config knob (re-applied on load like `region` /
///   `active_palette`), so — matching the `extra_scanlines` precedent — it is NOT
///   serialized; only the in-flight ages are. At the default (decay off) the ages
///   are inert dead state, so the blob merely grows by 256 bytes and restore is
///   behaviourally identical. v1..=6 blobs upconvert by stamping every row as
///   freshly-touched at the live cycle (age 0), i.e. the rest state — correct for
///   any pre-v7 save. Not a *load-break* — a pre-v7 `.rns` still restores.
/// - v8 (run-ahead sprite-evaluation fix): appends the per-dot **sprite-evaluation
///   FSM** (`sprite_eval_read_latch`, `_n`, `_m`, `_found`, `_sec_idx`,
///   `_copying`, `_done`, `_overflow_search`, `_zero_found`, `_first_iter`), the
///   parallel **OAM-data-bus model** (`oam_bus_copybuffer`, `oam_bus_secondary[32]`,
///   `oam_bus_addr_h`, `oam_bus_addr_l`, `oam_bus_secondary_addr`,
///   `oam_bus_copy_done`, `oam_bus_sprite_in_range`, `oam_bus_overflow_counter`),
///   and the secondary-OAM clear-window write pointer `oam2_addr`. 50 bytes.
///
///   These are the mid-scanline working registers of dots 65..=256: the eval pass
///   walks primary OAM through `_n`/`_m`, stages each byte through
///   `sprite_eval_read_latch`, and commits in-range sprites into `secondary_oam`
///   at `_sec_idx`. `secondary_oam` itself was already serialized — but the
///   *pointers and phase* driving it were not, so a snapshot taken with an eval
///   pass in flight restored a full secondary-OAM buffer alongside a
///   power-on-default FSM. The frontend's run-ahead (`snapshot_core_into` →
///   N frames → `restore_quiet`, every visible frame, and ON BY DEFAULT at
///   `run_ahead = 1`) hit this every frame: the hidden frames advanced the FSM
///   and the rollback left that advance behind. Measured effect on the
///   `AccuracyCoin` battery: 141/141 headless but 138/141 through the desktop
///   frontend, failing exactly `Sprite Evaluation :: Arbitrary Sprite zero`
///   (error 2), `Sprite Evaluation :: Misaligned OAM behavior` (error 1), and
///   `PPU Behavior :: Rendering Flag Behavior` (error 2). Same bug class as the
///   v6 tail (which closed the Wizards & Warriors half-blank playfield), a
///   different uncovered field set.
///
///   Mesen2 serializes the same set — `_spriteIndex`, `_sprite0Added`,
///   `_sprite0Visible`, `_oamCopybuffer`, `_secondaryOamAddr`, `_spriteInRange`,
///   `_oamCopyDone`, `_overflowBugCounter` (`Core/NES/NesPpu.cpp`
///   `NesPpu<T>::Serialize`) — independent confirmation that this is live state,
///   not derived.
///
///   v1..=7 blobs upconvert to the constructor defaults (`0xFF` for the two read
///   latches, `[0xFF; 32]` for the parallel secondary OAM, `0`/`false` elsewhere)
///   — the at-rest state, and exactly what a pre-v8 restore left behind. NOTE
///   that `rustynes_core`'s `.rns` container is version-EXACT per section, so an
///   existing save state fails to load with a clear `VersionMismatch` rather than
///   silently misreading (ADR 0028); the in-function upconvert path serves direct
///   `Ppu::restore` callers.
///
///   Also on restore (ALL versions): the scanline-classification cache
///   (`cached_visible` / `cached_pre_render` / `cached_render_line`, keyed by
///   `flags_cached_scanline`) is INVALIDATED rather than serialized. It is a pure
///   function of `scanline` + `region`, both of which are serialized, so
///   recomputing it is equivalent and cheaper than carrying derived bytes — the
///   same choice Mesen2 makes in its `if(!s.IsSaving())` post-load fixup block.
/// - v11 (v2.9.5 "Caliper"): appends `spr_rearm_deferred` (1 byte), the dot-339
///   sprite re-arm an odd-frame skip defers past scanline 0's first pixel. It is
///   live only across the frame boundary, which is exactly where run-ahead and
///   save states snapshot. This is a `.rns` epoch, because the container compares
///   the PPU section version for equality (ADR 0028); v1..=10 blobs upconvert to
///   `false` on the direct `Ppu::restore` path.
/// - v12 (T-MMC3-BG-A12, for v3.0.0): appends `dot0_replaced` (1 byte), set
///   when the odd-frame skip replaces scanline 0's idle dot 0 with the last
///   dummy nametable tick, so that dot does not drive the background CHR
///   address (and its A12) the way a visible line's dot 0 does. Like
///   `spr_rearm_deferred` it is live only across the frame boundary, where
///   run-ahead and save states snapshot; dropping it would let a restored
///   frame raise A12 at a dot 0 the skip removed, which an MMC3 counts.
/// - v13 (v3.1.0, `T-SPRITE-LIMIT`): appends the extra sprites the "disable
///   sprite limit" option fetched for the next scanline: a count (1 byte,
///   `0..=MAX_EXTRA_SPRITES`) and four 56-byte arrays (pattern low, pattern
///   high, attributes, X). Render-only state, but it decides the next
///   scanline's picture, and a snapshot can fall between the fetch (dots
///   257-320) and that line, so it is carried rather than dropped, the rule
///   `snapshot_schema_audit.rs` exists for. All zero while the option is off.
///   No upconvert: v3.1.0 states are refused by BUS section 3 regardless.
pub const PPU_SNAPSHOT_VERSION: u8 = 13;

/// v2.3.3 — high bit of the version byte, marking a **slim** snapshot: every
/// field except the 245,760-byte framebuffer.
///
/// Exists for the rewind ring, which snapshots on *every* frame inside the
/// frame budget and then XORs and LZ4-compresses the result. The framebuffer
/// is 94% of those bytes and the worst possible payload for that scheme — it
/// changes every frame, so the XOR never zeroes and the delta never
/// compresses. Measured, rewind roughly doubled the produce-interval p95
/// (31.17 ms against 17.12 ms with it off) and was the cause of a
/// user-visible judder report; see `docs/performance.md` v2.3.3 F3/F4.
///
/// Encoded as a flag on the version byte rather than a new version number so
/// the on-disk format is untouched: every `.rns` ever written has the high bit
/// clear and still parses on exactly the path it always did. Slim snapshots
/// are in-memory only and are never written to a file.
///
/// A slim blob restores every other field and **leaves the framebuffer
/// untouched**, so the caller is responsible for producing an image — see
/// `Nes::rewind_step_back`, which runs one frame to regenerate it.
pub const PPU_SNAPSHOT_SLIM_FLAG: u8 = 0x80;

const CIRAM_LEN: usize = 0x800;
const OAM_LEN: usize = 0x100;
const SEC_OAM_LEN: usize = 32;
const PAL_LEN: usize = 32;

/// Errors returned by [`Ppu::restore`].
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum PpuSnapshotError {
    /// Blob is too short for the version-1 schema.
    #[error("PPU snapshot truncated at offset {0}")]
    Truncated(usize),
    /// The blob decoded completely with bytes left over (v2.9.9, NC-14:
    /// this used to be reported as `Truncated` at the end offset).
    #[error("PPU snapshot has {extra} unexpected trailing bytes after offset {consumed}")]
    TrailingBytes {
        /// Bytes the schema consumed.
        consumed: usize,
        /// Bytes left over.
        extra: usize,
    },
    /// The blob's version byte is not understood by this build.
    #[error("PPU snapshot unsupported version {0}")]
    UnsupportedVersion(u8),
    /// Region tag was not one of `0` (NTSC), `1` (PAL), `2` (Dendy).
    #[error("PPU snapshot has invalid region tag {0}")]
    InvalidRegion(u8),
    /// Optional struct presence byte was something other than 0 or 1.
    #[error("PPU snapshot has invalid optional presence byte {0}")]
    InvalidPresence(u8),
    /// v9 OAM2 fetch address was outside the 5-bit hardware counter's range.
    ///
    /// `oam2_fetch_addr` indexes the 32-byte secondary-OAM bus, and the
    /// hardware counter it models is 5 bits wide, so anything `>= 32` is a
    /// corrupt or hostile blob rather than a state this emulator can reach.
    /// Rejected at the boundary instead of masked, so a malformed file is
    /// reported rather than silently reinterpreted as a different state.
    #[error("PPU snapshot has out-of-range OAM2 fetch address {0} (max 31)")]
    InvalidOam2FetchAddr(u8),
    /// The in-range sprite count exceeded the eight sprites secondary OAM holds.
    ///
    /// `spr_count` bounds loops over the eight-slot sprite arrays
    /// (`spr_x`, `spr_halted`, the shift registers), so a value above 8 would
    /// restore without complaint and then index out of bounds on the next PPU
    /// dot -- a deferred panic, and on a `panic = "abort"` release build a
    /// process kill from a hand-edited save. Core audit IMP-01.
    #[error("PPU snapshot has out-of-range sprite count {0} (max 8)")]
    InvalidSprCount(u8),
    /// A counter or index held a value the PPU never produces.
    ///
    /// Each of these is incremented without a mask or used as an index, so a
    /// value past its range overflows or indexes out of bounds on a later dot.
    /// The limits are the ranges the running PPU keeps them in (fine X is the
    /// 3-bit `x` register; the sprite-evaluation and OAM-bus counters are
    /// reset at their wrap points). Found field by field by the v2.7.0
    /// `save_state` fuzz target (fine X: `ppu.rs:4788`, shift overflow, in
    /// 92,496 runs) and then swept for the rest rather than left to the
    /// fuzzer one run at a time.
    #[error("PPU snapshot field `{field}` is {value}, above its maximum {max}")]
    FieldOutOfRange {
        /// Which field.
        field: &'static str,
        /// The value found in the blob.
        value: u8,
        /// The largest value the PPU keeps it at.
        max: u8,
    },
    /// The raster position is outside the region's frame.
    ///
    /// `dot` runs 0..=340 and `scanline` -1..=the region's pre-render line
    /// (-1 is the power-on position). The per-dot advance only wraps at
    /// exactly those limits, so a position past either counts on until the
    /// integer overflows (a panic in dev profiles) and never produces a
    /// frame. Found by the v2.7.0 `save_state` fuzz target in 76,381 runs
    /// (`ppu.rs:6078`, `dot += 1`).
    #[error("PPU snapshot has out-of-range raster position dot {dot}, scanline {scanline}")]
    InvalidRasterPosition {
        /// The restored dot.
        dot: u16,
        /// The restored scanline.
        scanline: i16,
    },
}

/// Reject a restored `u8` above `max` (see [`PpuSnapshotError::FieldOutOfRange`]).
const fn bounded(field: &'static str, value: u8, max: u8) -> Result<u8, PpuSnapshotError> {
    if value > max {
        Err(PpuSnapshotError::FieldOutOfRange { field, value, max })
    } else {
        Ok(value)
    }
}

const fn region_to_u8(r: PpuRegion) -> u8 {
    match r {
        PpuRegion::Ntsc => 0,
        PpuRegion::Pal => 1,
        PpuRegion::Dendy => 2,
    }
}

const fn region_from_u8(v: u8) -> Result<PpuRegion, PpuSnapshotError> {
    match v {
        0 => Ok(PpuRegion::Ntsc),
        1 => Ok(PpuRegion::Pal),
        2 => Ok(PpuRegion::Dendy),
        other => Err(PpuSnapshotError::InvalidRegion(other)),
    }
}

struct W {
    buf: Vec<u8>,
}
impl W {
    fn u8(&mut self, v: u8) {
        self.buf.push(v);
    }
    fn u16(&mut self, v: u16) {
        self.buf.extend_from_slice(&v.to_le_bytes());
    }
    fn u32(&mut self, v: u32) {
        self.buf.extend_from_slice(&v.to_le_bytes());
    }
    fn u64(&mut self, v: u64) {
        self.buf.extend_from_slice(&v.to_le_bytes());
    }
    fn i16(&mut self, v: i16) {
        self.buf.extend_from_slice(&v.to_le_bytes());
    }
    fn bytes(&mut self, v: &[u8]) {
        self.buf.extend_from_slice(v);
    }
}

struct R<'a> {
    src: &'a [u8],
    pos: usize,
}
impl R<'_> {
    const fn need(&self, n: usize) -> Result<(), PpuSnapshotError> {
        if self.src.len() - self.pos < n {
            return Err(PpuSnapshotError::Truncated(self.pos));
        }
        Ok(())
    }
    fn u8(&mut self) -> Result<u8, PpuSnapshotError> {
        self.need(1)?;
        let v = self.src[self.pos];
        self.pos += 1;
        Ok(v)
    }
    fn u16(&mut self) -> Result<u16, PpuSnapshotError> {
        self.need(2)?;
        let v = u16::from_le_bytes([self.src[self.pos], self.src[self.pos + 1]]);
        self.pos += 2;
        Ok(v)
    }
    fn u32(&mut self) -> Result<u32, PpuSnapshotError> {
        self.need(4)?;
        let mut a = [0u8; 4];
        a.copy_from_slice(&self.src[self.pos..self.pos + 4]);
        self.pos += 4;
        Ok(u32::from_le_bytes(a))
    }
    fn u64(&mut self) -> Result<u64, PpuSnapshotError> {
        self.need(8)?;
        let mut a = [0u8; 8];
        a.copy_from_slice(&self.src[self.pos..self.pos + 8]);
        self.pos += 8;
        Ok(u64::from_le_bytes(a))
    }
    fn i16(&mut self) -> Result<i16, PpuSnapshotError> {
        self.need(2)?;
        let v = i16::from_le_bytes([self.src[self.pos], self.src[self.pos + 1]]);
        self.pos += 2;
        Ok(v)
    }
    fn bytes_into(&mut self, dst: &mut [u8]) -> Result<(), PpuSnapshotError> {
        self.need(dst.len())?;
        dst.copy_from_slice(&self.src[self.pos..self.pos + dst.len()]);
        self.pos += dst.len();
        Ok(())
    }
}

impl Ppu {
    /// Encode the PPU's mutable state into a versioned binary blob.
    // A flat, linear field-by-field encoder with per-version tail appends (v1
    // through v8); splitting it would only scatter the schema that is clearest read
    // top-to-bottom against the matching `restore` reader.
    #[allow(clippy::too_many_lines)]
    #[must_use]
    pub fn snapshot(&self) -> Vec<u8> {
        self.snapshot_with(false)
    }

    /// v2.3.3 — [`Ppu::snapshot`] without the framebuffer. See
    /// [`PPU_SNAPSHOT_SLIM_FLAG`].
    #[must_use]
    pub fn snapshot_slim(&self) -> Vec<u8> {
        self.snapshot_with(true)
    }

    /// Shared body writer for the full and slim encodings.
    // One long straight-line writer: every field in schema order. Splitting it
    // would make the field-order correspondence with the reader (and with the
    // ADR 0034 schema audit, which parses this body) harder to verify, which is
    // the opposite of what this code needs.
    #[allow(clippy::too_many_lines)]
    fn snapshot_with(&self, slim: bool) -> Vec<u8> {
        // Capacity hint: ~256 KiB framebuffer dominates the full encoding;
        // the slim one is ~4 KiB, so don't reserve for a buffer it omits.
        let mut w = W {
            buf: Vec::with_capacity(if slim { 4096 } else { FRAMEBUFFER_LEN + 4096 }),
        };
        w.u8(if slim {
            PPU_SNAPSHOT_VERSION | PPU_SNAPSHOT_SLIM_FLAG
        } else {
            PPU_SNAPSHOT_VERSION
        });
        w.u8(region_to_u8(self.region));

        w.u8(self.ctrl.bits());
        w.u8(self.mask.bits());
        w.u8(self.mask_for_skip_check.bits());
        w.u8(self.mask_skip_pipe1.bits());
        w.u8(self.status.bits());

        w.u8(self.oam_addr);
        w.u8(self.data_buffer);
        w.u16(self.v);
        w.u16(self.t);
        w.u8(self.x);
        w.u8(u8::from(self.w));

        // Memory blocks at fixed sizes — no length prefix needed (versioned schema).
        w.bytes(&self.ciram);
        w.bytes(&self.oam);
        w.bytes(&self.secondary_oam);
        w.bytes(&self.palette_ram);

        w.u8(self.open_bus);
        for d in self.open_bus_decay {
            w.u32(d);
        }

        w.u8(u8::from(self.nmi_line));
        w.u8(u8::from(self.suppress_vbl_this_frame));
        w.u8(u8::from(self.last_a12_level));

        w.u16(self.dot);
        w.i16(self.scanline);
        w.u64(self.frame);
        w.u8(u8::from(self.frame_complete));

        w.u32(self.post_reset_mask_remaining);

        w.u8(self.nt_latch);
        w.u8(self.at_latch);
        w.u8(self.bg_lo_latch);
        w.u8(self.bg_hi_latch);
        w.u16(self.bg_shift_lo);
        w.u16(self.bg_shift_hi);
        // v2: attribute shift registers widened to 16-bit (lockstep with
        // the pattern shifters); the v1 1-bit `at_feed_*` fields are gone.
        w.u16(self.at_shift_lo);
        w.u16(self.at_shift_hi);

        if let Some(ex) = self.ex_attr_latch {
            w.u8(1);
            w.u8(ex.palette);
            w.u16(ex.chr_bank);
        } else {
            w.u8(0);
            w.u8(0);
            w.u16(0);
        }
        if let Some(s) = self.bg_split_latch {
            w.u8(1);
            w.u16(s.nt_addr);
            w.u16(s.at_addr);
            w.u8(s.fine_y);
            w.u8(s.chr_bank);
        } else {
            w.u8(0);
            w.u16(0);
            w.u16(0);
            w.u8(0);
            w.u8(0);
        }

        w.bytes(&self.spr_shift_lo);
        w.bytes(&self.spr_shift_hi);
        w.bytes(&self.spr_attr);
        w.bytes(&self.spr_x);
        w.u8(self.spr_count);
        w.u8(u8::from(self.spr_zero_in_line));

        if !slim {
            w.bytes(&self.framebuffer);
        }

        // v3 (W3-Stage-4): the `mc-ppu-2007-render-buffer` PPUDATA
        // state-machine tail. Written unconditionally (zeros when the
        // feature is off) so the blob layout is feature-independent.
        {
            w.u8(self.render_data_bus);
            w.u8(self.ppudata_sm_countdown);
            w.u8(u8::from(self.ppudata_v_inc_pending));
            w.bytes(&self.spr_fetch_lo_raw);
            w.bytes(&self.spr_fetch_hi_raw);
            w.u16(self.ppudata_spr0_nt_addr);
        }
        // v3 (W3-Stage-4): the `mc-ppu-subpos` BG-reload freeze (the
        // `$2001`-write-commit delay that injects the BG serial-in '1's).
        // `bg_reload_render` re-syncs from the live mask when settled, but an
        // in-flight `mask_write_delay` countdown can straddle an instruction
        // boundary — serialize both so a restored state resumes the freeze
        // exactly.
        {
            w.u8(u8::from(self.bg_reload_render));
            w.u8(self.mask_write_delay);
        }

        // v4 (v1.7.0 F3): the in-flight extra-scanlines overclock countdown.
        // Always `0` at the default `extra_scanlines == 0`, so this is a
        // zero `u16` in the stock build (no behavioural change). The
        // configured count itself (`extra_scanlines`) stays a frontend knob
        // re-applied on restore, like `region` / `active_palette`.
        w.u16(self.extra_lines_remaining);

        // v5 (v2.0.3, ADR 0030): the 2-cycle-ALE fetch model's in-flight
        // multiplexed-bus / octal-latch state. All at rest (`0`/`false`) at a
        // clean fetch boundary, but a mid-render checkpoint (netplay rollback)
        // can land with `copy_v_delay`/`pattern_latch_stale`/`ale_armed` live —
        // serialize them (plus the latch + bus they splice through) so the
        // re-simulated frame is byte-identical to the forward run.
        {
            w.u8(self.octal_latch);
            w.u16(self.address_bus);
            w.u8(u8::from(self.ale_armed));
            w.u8(u8::from(self.pattern_latch_stale));
            w.u8(self.copy_v_delay);
        }

        // v6 (W&W run-ahead fix): the per-sprite shifter HALT state. Set by the
        // v2.0 sprite-shifter-counter model (a loaded-but-halted slot draws
        // immediately on re-enable), it persists across the frame boundary and
        // governs whether each of the 8 loaded sprites emits — so it is genuine
        // rendering state. It was previously unserialized, so a per-frame
        // save/restore (run-ahead, netplay rollback) drifted it: for a game that
        // toggles rendering mid-frame (Wizards & Warriors' sprite-0 status-bar
        // split), the drift accumulated into dropped/blinking sprites and a
        // half-rendered playfield. `true` (halted) is the power-on default.
        for h in &self.spr_halted {
            w.u8(u8::from(*h));
        }
        // v6 (cont.) — remaining unserialized cross-frame render state.
        w.u8(u8::from(self.prev_rendering_enabled));
        w.u8(u8::from(self.rendering_enabled_delayed));
        w.u8(u8::from(self.oam_corruption_pending));
        w.u8(self.oam_corruption_index);
        w.u8(u8::from(self.oam_corruption_disabled));
        w.u8(u8::from(self.oam_corruption_disabled_instant));

        // v7 (v2.1.4 F2.3): the optional OAM-decay model's per-row last-touch
        // timestamps, stored as a RELATIVE AGE (`now - timestamp`) so the decay
        // clock survives a rollback/restore that rebases the un-serialized
        // free-running `dot_counter`. `now` is the live CPU cycle (`dot_counter / 3`,
        // NTSC/Dendy divisor). `wrapping_sub` keeps the encode total even across the
        // (astronomically unlikely) u64 wrap. When decay is off these ages are inert
        // (never read on restore's decay path), but they still round-trip exactly.
        let now = self.dot_counter / 3;
        for ts in self.oam_decay_cycles {
            w.u64(now.wrapping_sub(ts));
        }

        // v8: the per-dot sprite-evaluation FSM + the parallel OAM-data-bus
        // model + the clear-window secondary-OAM write pointer. `secondary_oam`
        // (the buffer) was always serialized; these are the POINTERS AND PHASE
        // that fill it, and without them a mid-eval snapshot restored a full
        // buffer next to a reset walker. See the `PPU_SNAPSHOT_VERSION` rustdoc
        // for the run-ahead failure this closes and the Mesen2 cross-check.
        {
            w.u8(self.sprite_eval_read_latch);
            w.u8(self.sprite_eval_n);
            w.u8(self.sprite_eval_m);
            w.u8(self.sprite_eval_found);
            w.u8(self.sprite_eval_sec_idx);
            w.u8(u8::from(self.sprite_eval_copying));
            w.u8(u8::from(self.sprite_eval_done));
            w.u8(u8::from(self.sprite_eval_overflow_search));
            w.u8(u8::from(self.sprite_eval_zero_found));
            w.u8(u8::from(self.sprite_eval_first_iter));

            w.u8(self.oam_bus_copybuffer);
            w.bytes(&self.oam_bus_secondary);
            w.u8(self.oam_bus_addr_h);
            w.u8(self.oam_bus_addr_l);
            w.u8(self.oam_bus_secondary_addr);
            w.u8(u8::from(self.oam_bus_copy_done));
            w.u8(u8::from(self.oam_bus_sprite_in_range));
            w.u8(self.oam_bus_overflow_counter);

            w.u8(self.oam2_addr);
        }

        // v9 tail — the OAM2Address counter carried across sprite fetch plus
        // its "OAM2 Overflowed" freeze flag and the dot-257 latch.
        //
        // These are serialized rather than allowlisted as derived. They LOOK
        // derived (all three re-derive at dots 63/255/339 within a scanline),
        // and that reasoning is exactly wrong here: the whole behaviour they
        // model is what happens when rendering is DISABLED across those reset
        // dots, so a snapshot taken inside such a window carries state that
        // cannot be recomputed from anything else in the blob. Run-ahead
        // snapshots and restores every frame, so dropping them would silently
        // reintroduce the bug this release fixed.
        w.u8(self.oam2_fetch_addr);
        w.u8(u8::from(self.oam2_overflowed));
        w.u8(u8::from(self.oam2_fetch_frozen));

        // v10 tail — stage 2 of the rendering gate, which the dot-256 vertical
        // increment reads. Serialized for the same reason as the v9 fields
        // above: it LOOKS derivable from `rendering_enabled_delayed`, and is
        // not. The two differ for exactly one dot after any `$2001` rendering
        // edge, and that dot is the whole subject -- a run-ahead snapshot taken
        // there and restored from stage 1 would fire, or skip, the increment
        // the restored timeline must not.
        w.u8(u8::from(self.rendering_enabled_delayed2));

        // v11 tail — the odd-frame-deferred sprite re-arm (v2.9.5). It is set at
        // the pre-render skip and cleared after scanline 0's first pixel, so it
        // is live exactly across the frame boundary where run-ahead and save
        // states snapshot. Dropping it would draw that frame's scanline-0
        // sprites at their normal X instead of the composite PPU's X=0.
        w.u8(u8::from(self.spr_rearm_deferred));

        // v12 tail — the odd-frame skip replaced scanline 0's dot 0 (set at
        // the skip, consumed at that dot), live across the frame boundary.
        w.u8(u8::from(self.dot0_replaced));

        // v13 tail — the sprite-limit option's extra sprites for the next line.
        w.u8(self.spr_extra_count);
        w.bytes(&self.spr_extra_lo);
        w.bytes(&self.spr_extra_hi);
        w.bytes(&self.spr_extra_attr);
        w.bytes(&self.spr_extra_x);

        w.buf
    }

    /// Decode a previously [`Ppu::snapshot`]ed blob.
    ///
    /// # Errors
    ///
    /// Returns [`PpuSnapshotError`] on a malformed blob.
    // A flat, linear field-by-field decoder; splitting it would only scatter
    // the schema that is clearest read top-to-bottom against the matching
    // `snapshot` writer.
    #[allow(clippy::too_many_lines)]
    pub fn restore(&mut self, data: &[u8]) -> Result<(), PpuSnapshotError> {
        // A valid snapshot (only the current version loads since v2.9.8) always contains these fixed-size blocks (the
        // framebuffer, read unconditionally below at every version, dominates);
        // the version-specific tails only add to this. This is a *conservative
        // lower bound* — it deliberately omits the ~40 scalar register/latch
        // bytes and the spr shift arrays, so it can never reject a valid blob,
        // yet it rejects a clearly-truncated one BEFORE the version byte is read
        // (so short/garbled input reports `Truncated`, not a misleading
        // `UnsupportedVersion` on whatever byte sits at offset 0). `Truncated(0)`
        // matches the offset semantics `R::need` uses elsewhere (the position at
        // which a read ran out) — here, nothing valid was read.
        // v2.3.3 — a slim blob (high bit of the version byte) carries no
        // framebuffer, so the bound must drop that term for it. Read the flag
        // from byte 0 directly rather than through `R`, because this check
        // deliberately runs BEFORE the reader is constructed.
        const MIN_SLIM_SIZE: usize = 1 + CIRAM_LEN + OAM_LEN + SEC_OAM_LEN + PAL_LEN;
        const MIN_SNAPSHOT_SIZE: usize = MIN_SLIM_SIZE + FRAMEBUFFER_LEN;
        let is_slim = data
            .first()
            .is_some_and(|v| v & PPU_SNAPSHOT_SLIM_FLAG != 0);
        let min_size = if is_slim {
            MIN_SLIM_SIZE
        } else {
            MIN_SNAPSHOT_SIZE
        };
        if data.len() < min_size {
            return Err(PpuSnapshotError::Truncated(0));
        }
        let mut r = R { src: data, pos: 0 };
        let raw_version = r.u8()?;
        // v2.3.3 — the high bit marks a slim (framebuffer-less) blob; strip it
        // before the range check so the version rules are unchanged.
        let slim = raw_version & PPU_SNAPSHOT_SLIM_FLAG != 0;
        let version = raw_version & !PPU_SNAPSHOT_SLIM_FLAG;
        // Only the current version is read (v2.9.8, ADR 0042). Versions 1-10
        // used to be upconverted here, each missing tail restored to its
        // rest default; see `PPU_SNAPSHOT_VERSION` for what each added.
        if version != PPU_SNAPSHOT_VERSION {
            return Err(PpuSnapshotError::UnsupportedVersion(raw_version));
        }
        self.region = region_from_u8(r.u8()?)?;

        self.ctrl = PpuCtrl::from_bits_truncate(r.u8()?);
        self.mask = PpuMask::from_bits_truncate(r.u8()?);
        self.mask_for_skip_check = PpuMask::from_bits_truncate(r.u8()?);
        self.mask_skip_pipe1 = PpuMask::from_bits_truncate(r.u8()?);
        self.status = PpuStatus::from_bits_truncate(r.u8()?);

        self.oam_addr = r.u8()?;
        self.data_buffer = r.u8()?;
        self.v = r.u16()?;
        self.t = r.u16()?;
        self.x = bounded("x", r.u8()?, 7)?;
        self.w = r.u8()? != 0;

        r.bytes_into(&mut self.ciram)?;
        r.bytes_into(&mut self.oam)?;
        r.bytes_into(&mut self.secondary_oam)?;
        r.bytes_into(&mut self.palette_ram)?;

        self.open_bus = r.u8()?;
        for d in &mut self.open_bus_decay {
            *d = r.u32()?;
        }

        self.nmi_line = r.u8()? != 0;
        self.suppress_vbl_this_frame = r.u8()? != 0;
        self.last_a12_level = r.u8()? != 0;

        let dot = r.u16()?;
        let scanline = r.i16()?;
        // -1 is legal: power-on parks the PPU at (-1, 340), and a snapshot taken
        // before the first tick carries it; the advance wraps it to 0.
        if dot > 340 || !(-1..=self.region.prerender_line()).contains(&scanline) {
            return Err(PpuSnapshotError::InvalidRasterPosition { dot, scanline });
        }
        self.dot = dot;
        self.scanline = scanline;
        self.frame = r.u64()?;
        self.frame_complete = r.u8()? != 0;

        self.post_reset_mask_remaining = r.u32()?;

        self.nt_latch = r.u8()?;
        self.at_latch = r.u8()?;
        self.bg_lo_latch = r.u8()?;
        self.bg_hi_latch = r.u8()?;
        self.bg_shift_lo = r.u16()?;
        self.bg_shift_hi = r.u16()?;
        self.at_shift_lo = r.u16()?;
        self.at_shift_hi = r.u16()?;

        let ex_present = r.u8()?;
        let palette = r.u8()?;
        let chr_bank = r.u16()?;
        self.ex_attr_latch = match ex_present {
            0 => None,
            1 => Some(ExAttribute { palette, chr_bank }),
            other => return Err(PpuSnapshotError::InvalidPresence(other)),
        };
        let split_present = r.u8()?;
        let nt_addr = r.u16()?;
        let at_addr = r.u16()?;
        let fine_y = r.u8()?;
        let chr_bank8 = r.u8()?;
        self.bg_split_latch = match split_present {
            0 => None,
            1 => Some(BgSplitState {
                nt_addr,
                at_addr,
                fine_y,
                chr_bank: chr_bank8,
            }),
            other => return Err(PpuSnapshotError::InvalidPresence(other)),
        };

        r.bytes_into(&mut self.spr_shift_lo)?;
        r.bytes_into(&mut self.spr_shift_hi)?;
        r.bytes_into(&mut self.spr_attr)?;
        r.bytes_into(&mut self.spr_x)?;
        let spr_count = r.u8()?;
        if spr_count > 8 {
            return Err(PpuSnapshotError::InvalidSprCount(spr_count));
        }
        self.spr_count = spr_count;
        self.spr_zero_in_line = r.u8()? != 0;

        // Slim blobs carry no framebuffer; the existing one is left in place
        // and the caller regenerates the image.
        if !slim {
            r.bytes_into(&mut self.framebuffer)?;
        }

        // v3 (W3-Stage-4): the gated master-clock PPU tail.
        self.restore_stage4_tail(&mut r)?;

        // v4 (v1.7.0 F3): the in-flight extra-scanlines overclock countdown.
        let extra_lines_remaining = r.u16()?;
        // Clamped, not rejected. The configured `extra_scanlines` is a frontend
        // knob that is NOT serialized, so a real save made under a larger knob
        // legitimately carries a larger countdown; refusing it would reject a
        // good file. But a corrupt countdown under a live knob idles up to
        // 65,535 scanlines (~4 s) before the frame resumes (review finding on
        // #546), and the countdown never legitimately exceeds the knob it was
        // loaded from, so it is clamped to the knob this PPU now runs with. At
        // the default knob of 0 the insertion branch is unreachable and the
        // value is inert, so it is kept as-is -- `set_extra_scanlines` zeroes
        // it if the knob is later turned on.
        self.extra_lines_remaining = if self.extra_scanlines == 0 {
            extra_lines_remaining
        } else {
            extra_lines_remaining.min(self.extra_scanlines)
        };

        // v5 (v2.0.3, ADR 0030): the 2-cycle-ALE in-flight fetch state. A blob
        // taken mid-render round-trips the live values so the re-simulated
        // frame stays byte-identical (netplay rollback).
        self.octal_latch = r.u8()?;
        self.address_bus = r.u16()?;
        self.ale_armed = r.u8()? != 0;
        self.pattern_latch_stale = r.u8()? != 0;
        self.copy_v_delay = r.u8()?;

        // v6: per-sprite shifter halt state (see the write side).
        for h in &mut self.spr_halted {
            *h = r.u8()? != 0;
        }
        self.prev_rendering_enabled = r.u8()? != 0;
        self.rendering_enabled_delayed = r.u8()? != 0;
        self.oam_corruption_pending = r.u8()? != 0;
        self.oam_corruption_index = bounded("oam_corruption_index", r.u8()?, 0x20)?;
        self.oam_corruption_disabled = r.u8()? != 0;
        self.oam_corruption_disabled_instant = r.u8()? != 0;

        // v7 (v2.1.4 F2.3): the optional OAM-decay row timestamps, stored as a
        // relative age. Reconstruct the absolute timestamp against the LIVE counter
        // (`now = dot_counter / 3`, unchanged by restore) as `now - age`, so the
        // decay clock is preserved regardless of how the counter was rebased between
        // snapshot and restore (the rollback-determinism property).
        let now = self.dot_counter / 3;
        for ts in &mut self.oam_decay_cycles {
            let age = r.u64()?;
            *ts = now.wrapping_sub(age);
        }

        // v8: the per-dot sprite-evaluation FSM + parallel OAM-data-bus model +
        // the clear-window secondary-OAM pointer.
        self.sprite_eval_read_latch = r.u8()?;
        self.sprite_eval_n = bounded("sprite_eval_n", r.u8()?, 63)?;
        self.sprite_eval_m = bounded("sprite_eval_m", r.u8()?, 3)?;
        self.sprite_eval_found = bounded("sprite_eval_found", r.u8()?, 8)?;
        self.sprite_eval_sec_idx = bounded("sprite_eval_sec_idx", r.u8()?, 0x20)?;
        self.sprite_eval_copying = r.u8()? != 0;
        self.sprite_eval_done = r.u8()? != 0;
        self.sprite_eval_overflow_search = r.u8()? != 0;
        self.sprite_eval_zero_found = r.u8()? != 0;
        self.sprite_eval_first_iter = r.u8()? != 0;

        self.oam_bus_copybuffer = r.u8()?;
        r.bytes_into(&mut self.oam_bus_secondary)?;
        self.oam_bus_addr_h = bounded("oam_bus_addr_h", r.u8()?, 63)?;
        self.oam_bus_addr_l = bounded("oam_bus_addr_l", r.u8()?, 3)?;
        self.oam_bus_secondary_addr = bounded("oam_bus_secondary_addr", r.u8()?, 0x20)?;
        self.oam_bus_copy_done = r.u8()? != 0;
        self.oam_bus_sprite_in_range = r.u8()? != 0;
        self.oam_bus_overflow_counter = bounded("oam_bus_overflow_counter", r.u8()?, 3)?;

        self.oam2_addr = bounded("oam2_addr", r.u8()?, 0x1F)?;

        // v9: the `OAM2Address` counter and its two latched flags.
        // Range-check at the EDGE: this byte is untrusted input and is used
        // directly as an index into `oam_bus_secondary: [u8; 32]`.
        let fetch_addr = r.u8()?;
        if fetch_addr >= 32 {
            return Err(PpuSnapshotError::InvalidOam2FetchAddr(fetch_addr));
        }
        self.oam2_fetch_addr = fetch_addr;
        self.oam2_overflowed = r.u8()? != 0;
        self.oam2_fetch_frozen = r.u8()? != 0;

        // v10: stage 2 of the rendering gate.
        self.rendering_enabled_delayed2 = r.u8()? != 0;

        // v11: the deferred sprite re-arm (`true` only in the two dots after an
        // odd-frame skip).
        self.spr_rearm_deferred = r.u8()? != 0;

        // v12: the odd-frame skip replaced scanline 0's dot 0.
        self.dot0_replaced = r.u8()? != 0;

        // v13: the sprite-limit option's extra sprites for the next line.
        self.spr_extra_count = bounded(
            "spr_extra_count",
            r.u8()?,
            u8::try_from(crate::ppu::MAX_EXTRA_SPRITES).unwrap_or(u8::MAX),
        )?;
        r.bytes_into(&mut self.spr_extra_lo)?;
        r.bytes_into(&mut self.spr_extra_hi)?;
        r.bytes_into(&mut self.spr_extra_attr)?;
        r.bytes_into(&mut self.spr_extra_x)?;

        // Derived-cache fixup: the scanline-classification cache
        // is a pure function of `scanline` + `region`, so it is recomputed rather
        // than carried. Resetting the key to the `Ppu::new` sentinel forces the
        // next `tick` to refill it from the restored scanline; leaving a warm key
        // behind would let a cache filled under a different timeline satisfy the
        // `scanline == flags_cached_scanline` guard on the fast dot path.
        self.cached_visible = false;
        self.cached_pre_render = false;
        self.cached_render_line = false;
        #[cfg(feature = "ppu-idle-line-fast")]
        {
            self.cached_idle_line = false;
        }
        self.flags_cached_scanline = i16::MIN;

        // sanity: the schema-fixed sizes mean we should be at end of input now.
        if r.pos != data.len() {
            return Err(PpuSnapshotError::TrailingBytes {
                consumed: r.pos,
                extra: data.len() - r.pos,
            });
        }
        Ok(())
    }
}

impl Ppu {
    /// v3 (W3-Stage-4) tail decode: the `mc-ppu-2007-render-buffer` PPUDATA
    /// state machine + the `mc-ppu-subpos` BG-reload freeze. Bytes are
    /// always present in a v3 blob; fields whose cargo feature is off are
    /// consumed and discarded.
    fn restore_stage4_tail(&mut self, r: &mut R<'_>) -> Result<(), PpuSnapshotError> {
        let render_data_bus = r.u8()?;
        let ppudata_sm_countdown = r.u8()?;
        let ppudata_v_inc_pending = r.u8()? != 0;
        let mut spr_fetch_lo_raw = [0u8; 8];
        let mut spr_fetch_hi_raw = [0u8; 8];
        r.bytes_into(&mut spr_fetch_lo_raw)?;
        r.bytes_into(&mut spr_fetch_hi_raw)?;
        let ppudata_spr0_nt_addr = r.u16()?;
        {
            self.render_data_bus = render_data_bus;
            self.ppudata_sm_countdown = ppudata_sm_countdown;
            self.ppudata_v_inc_pending = ppudata_v_inc_pending;
            self.spr_fetch_lo_raw = spr_fetch_lo_raw;
            self.spr_fetch_hi_raw = spr_fetch_hi_raw;
            self.ppudata_spr0_nt_addr = ppudata_spr0_nt_addr;
        }
        let bg_reload_render = r.u8()? != 0;
        let mask_write_delay = r.u8()?;
        {
            self.bg_reload_render = bg_reload_render;
            self.mask_write_delay = mask_write_delay;
        }
        Ok(())
    }
}

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

    // Per-version tail sizes, in bytes. The synthesis tests below build an OLD
    // blob by truncating a CURRENT one, so every schema bump has to be
    // subtracted — and before these were named, that meant editing two
    // hand-computed literals and hoping they agreed. Naming them makes a bump
    // one edit here, and makes the composition checkable at a glance.
    //
    // Verified to sum: 23 + 2 + 6 + 14 + 256 + 50 + 3 + 1 + 1 = 356 = V3_TAIL..V11_TAIL.
    /// v3: W3-Stage-4 — `u8*3` + `[u8;8]*2` + u16 PPUDATA FSM + `u8*2` BG freeze.
    const V3_TAIL: usize = 23;
    /// v4: `u16 extra_lines_remaining`.
    const V4_TAIL: usize = 2;
    /// v5: 2-cycle-ALE fetch state — octal latch, address bus, three flags.
    const V5_TAIL: usize = 6;
    /// v6: render state — `[u8;8] spr_halted` + 6 bytes of gating/corruption.
    const V6_TAIL: usize = 14;
    /// v7: OAM decay — `[u64;32]` relative-age counters.
    const V7_TAIL: usize = 256;
    /// v8: sprite-evaluation FSM + the OAM data-bus model + `oam2_addr`.
    const V8_TAIL: usize = 50;
    /// v9: the `OAM2Address` counter — `oam2_fetch_addr` + two latched flags.
    const V9_TAIL: usize = 3;
    /// v10: stage 2 of the rendering gate (`rendering_enabled_delayed2`).
    const V10_TAIL: usize = 1;
    /// v11: the odd-frame-deferred sprite re-arm (`spr_rearm_deferred`).
    const V11_TAIL: usize = 1;
    /// v12: the odd-frame skip replaced scanline 0's dot 0 (`dot0_replaced`).
    const V12_TAIL: usize = 1;
    /// Everything a v1 blob does not carry, from `ex_attr_latch` onward.
    const V3_THROUGH_V12_TAILS: usize = V3_TAIL
        + V4_TAIL
        + V5_TAIL
        + V6_TAIL
        + V7_TAIL
        + V8_TAIL
        + V9_TAIL
        + V10_TAIL
        + V11_TAIL
        + V12_TAIL;

    /// v12: `dot0_replaced` must survive the round trip TRUE (a dropped or
    /// inverted byte would read back as the default `false`), and a v11 blob
    /// is refused.
    #[test]
    fn snapshot_v12_carries_the_replaced_dot_0() {
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.dot0_replaced = true;
        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.restore(&p.snapshot()).unwrap();
        assert!(q.dot0_replaced, "a true flag must survive the round trip");
        p.dot0_replaced = false;
        q.dot0_replaced = true;
        q.restore(&p.snapshot()).unwrap();
        assert!(!q.dot0_replaced, "a false flag must overwrite a stale true");
        let cur = p.snapshot();
        let mut v11 = cur[..cur.len() - V12_TAIL].to_vec();
        v11[0] = 11;
        assert!(matches!(
            q.restore(&v11),
            Err(PpuSnapshotError::UnsupportedVersion(11))
        ));
    }

    /// v11: `spr_rearm_deferred` is the reason for the epoch, and it is only
    /// ever `true` across the frame boundary, where every run-ahead and save
    /// snapshot is taken. The round trip must carry a TRUE value (the default
    /// `false` would survive an omitted or inverted byte), and a v10 blob is
    /// refused. Added in v2.9.5 at
    /// Copilot's review of #575.
    #[test]
    fn snapshot_v11_carries_the_deferred_sprite_rearm() {
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.spr_rearm_deferred = true;
        let blob = p.snapshot();
        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.restore(&blob).unwrap();
        assert!(
            q.spr_rearm_deferred,
            "a true deferral must survive the round trip"
        );

        p.spr_rearm_deferred = false;
        let blob = p.snapshot();
        q.spr_rearm_deferred = true;
        q.restore(&blob).unwrap();
        assert!(
            !q.spr_rearm_deferred,
            "a false deferral must overwrite a stale true"
        );

        // A v10 blob (the current blob minus the one-byte v11 tail) upconverted
        // to `false` until v2.9.8; it is refused now (ADR 0042).
        p.spr_rearm_deferred = true;
        let cur = p.snapshot();
        let mut v10 = cur[..cur.len() - V11_TAIL].to_vec();
        v10[0] = 10;
        assert!(matches!(
            q.restore(&v10),
            Err(PpuSnapshotError::UnsupportedVersion(10))
        ));
    }

    #[test]
    fn snapshot_round_trip() {
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.ciram[10] = 0xAB;
        p.oam[20] = 0xCD;
        p.palette_ram[5] = 0x21;
        p.framebuffer[100] = 0xEF;
        p.dot = 123;
        p.scanline = -1;
        p.frame = 42;
        p.ex_attr_latch = Some(ExAttribute {
            palette: 2,
            chr_bank: 0x123,
        });
        p.bg_split_latch = Some(BgSplitState {
            nt_addr: 0x2400,
            at_addr: 0x23C0,
            fine_y: 5,
            chr_bank: 7,
        });

        let blob = p.snapshot();

        let mut q = Ppu::new(PpuRegion::Pal);
        q.restore(&blob).unwrap();
        assert_eq!(q.region, PpuRegion::Ntsc);
        assert_eq!(q.ciram[10], 0xAB);
        assert_eq!(q.oam[20], 0xCD);
        assert_eq!(q.palette_ram[5], 0x21);
        assert_eq!(q.framebuffer[100], 0xEF);
        assert_eq!(q.dot, 123);
        assert_eq!(q.scanline, -1);
        assert_eq!(q.frame, 42);
        assert_eq!(
            q.ex_attr_latch,
            Some(ExAttribute {
                palette: 2,
                chr_bank: 0x123
            })
        );
        assert_eq!(
            q.bg_split_latch,
            Some(BgSplitState {
                nt_addr: 0x2400,
                at_addr: 0x23C0,
                fine_y: 5,
                chr_bank: 7,
            })
        );
    }

    #[test]
    fn snapshot_round_trips_16bit_attribute_shifters() {
        // v2 widened `at_shift_lo`/`at_shift_hi` from u8 to u16 (lockstep
        // with the BG pattern shifters; the 086ce4d left-edge palette
        // fix). Verify the full 16-bit value survives a round trip — a
        // regression that truncated to 8 bits would re-introduce the
        // attribute/pattern drift after a save-state load.
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.at_shift_lo = 0xAB12;
        p.at_shift_hi = 0xCD34;
        p.bg_shift_lo = 0x5678;
        p.bg_shift_hi = 0x9ABC;
        let blob = p.snapshot();
        assert_eq!(
            blob[0], PPU_SNAPSHOT_VERSION,
            "blob carries current version"
        );

        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.restore(&blob).unwrap();
        assert_eq!(q.at_shift_lo, 0xAB12);
        assert_eq!(q.at_shift_hi, 0xCD34);
        assert_eq!(q.bg_shift_lo, 0x5678);
        assert_eq!(q.bg_shift_hi, 0x9ABC);
    }

    /// v2.9.8 (ADR 0042): every older version is refused, whatever its
    /// length. Each is built the way the upconversion tests used to build
    /// them: the current blob minus the tails that version did not carry,
    /// with its version byte. (v1 also had a different attribute-shifter
    /// layout; its version byte alone is what is refused.)
    #[test]
    fn every_older_snapshot_version_is_refused() {
        let cur = Ppu::new(PpuRegion::Ntsc).snapshot();
        let tails = [
            V3_TAIL, V4_TAIL, V5_TAIL, V6_TAIL, V7_TAIL, V8_TAIL, V9_TAIL, V10_TAIL, V11_TAIL,
            V12_TAIL,
        ];
        assert_eq!(tails.iter().sum::<usize>(), V3_THROUGH_V12_TAILS);
        for v in 1..PPU_SNAPSHOT_VERSION {
            // Versions 1 and 2 carry none of the v3+ tails; version N >= 3
            // carries the tails up to and including its own.
            let carried = usize::from(v.saturating_sub(2));
            let missing: usize = tails[carried..].iter().sum();
            let mut old = cur[..cur.len() - missing].to_vec();
            old[0] = v;
            assert!(
                matches!(
                    Ppu::new(PpuRegion::Ntsc).restore(&old),
                    Err(PpuSnapshotError::UnsupportedVersion(got)) if got == v
                ),
                "a v{v} blob must be refused"
            );
        }
        // A slim blob of an older version is refused the same way.
        let mut slim = Ppu::new(PpuRegion::Ntsc).snapshot_slim();
        slim[0] = PPU_SNAPSHOT_SLIM_FLAG | (PPU_SNAPSHOT_VERSION - 1);
        assert!(Ppu::new(PpuRegion::Ntsc).restore(&slim).is_err());
    }

    #[test]
    fn snapshot_rejects_short_blob() {
        let mut p = Ppu::new(PpuRegion::Ntsc);
        assert!(matches!(
            p.restore(&[]).unwrap_err(),
            PpuSnapshotError::Truncated(_)
        ));
        // The regression this size guard prevents: a SHORT blob whose first byte
        // is an unknown version must be classified `Truncated` (the guard runs
        // before the version check), NOT `UnsupportedVersion(0xFF)`.
        assert!(matches!(
            p.restore(&[0xFF; 4]).unwrap_err(),
            PpuSnapshotError::Truncated(_)
        ));
    }

    #[test]
    fn snapshot_rejects_bad_version() {
        let mut p = Ppu::new(PpuRegion::Ntsc);
        // A full-size blob (past the truncation guard) whose version byte is
        // unknown must be rejected at the version check — not mistaken for a
        // truncated blob. (A short bad-version blob is a Truncated case,
        // covered by `snapshot_rejects_short_blob`.)
        let mut blob = p.snapshot();
        blob[0] = 0xFF;
        let err = p.restore(&blob).unwrap_err();
        assert!(matches!(err, PpuSnapshotError::UnsupportedVersion(0xFF)));
    }

    #[test]
    fn snapshot_is_deterministic() {
        let p = Ppu::new(PpuRegion::Ntsc);
        assert_eq!(p.snapshot(), p.snapshot());
    }

    #[test]
    fn a_corrupt_v9_oam2_fetch_address_is_rejected_not_indexed() {
        // `oam2_fetch_addr` is read from an untrusted blob and used as an index
        // into `oam_bus_secondary: [u8; 32]`. A hostile or corrupt save state
        // carrying >= 32 must be refused at the boundary -- not panic the
        // emulator, and not be silently masked into a DIFFERENT valid state.
        //
        // Reported as a blocking finding on the release PR. The hardware
        // counter is 5 bits, so no reachable run can produce such a value; only
        // a malformed file can.
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.oam2_fetch_addr = 0x1F; // the largest LEGAL value
        let good = p.snapshot();
        assert!(
            Ppu::new(PpuRegion::Ntsc).restore(&good).is_ok(),
            "31 is in range and must still load"
        );

        // Corrupt exactly that byte, leaving the rest of the blob intact.
        let idx = good
            .iter()
            .rposition(|&b| b == 0x1F)
            .expect("the fetch-address byte is in the blob");
        for bad_value in [32u8, 0x80, 0xFF] {
            let mut bad = good.clone();
            bad[idx] = bad_value;
            match Ppu::new(PpuRegion::Ntsc).restore(&bad) {
                Err(PpuSnapshotError::InvalidOam2FetchAddr(v)) => {
                    assert_eq!(v, bad_value, "the error names the offending byte");
                }
                Err(e) => panic!("wrong error for {bad_value}: {e}"),
                Ok(()) => panic!("restore ACCEPTED an out-of-range fetch address {bad_value}"),
            }
        }
    }

    #[test]
    fn a_corrupt_sprite_count_is_rejected_not_indexed() {
        // Core audit IMP-01. `spr_count` bounds loops over the eight-slot
        // sprite arrays, so a restored value above 8 panics on the next dot.
        // Locate the byte by DIFFERENCE rather than by searching for a value:
        // two snapshots that differ only in `spr_count` differ in exactly one
        // byte, and that is the field's offset.
        let mut a = Ppu::new(PpuRegion::Ntsc);
        a.spr_count = 3;
        let mut b = Ppu::new(PpuRegion::Ntsc);
        b.spr_count = 8; // the largest LEGAL value
        let (sa, sb) = (a.snapshot(), b.snapshot());
        let diffs: Vec<usize> = (0..sa.len()).filter(|&i| sa[i] != sb[i]).collect();
        assert_eq!(diffs.len(), 1, "spr_count is exactly one byte of the blob");
        let idx = diffs[0];
        assert!(
            Ppu::new(PpuRegion::Ntsc).restore(&sb).is_ok(),
            "8 is in range and must still load"
        );

        for bad_value in [9u8, 0x80, 0xFF] {
            let mut bad = sb.clone();
            bad[idx] = bad_value;
            match Ppu::new(PpuRegion::Ntsc).restore(&bad) {
                Err(PpuSnapshotError::InvalidSprCount(v)) => {
                    assert_eq!(v, bad_value, "the error names the offending byte");
                }
                Err(e) => panic!("wrong error for {bad_value}: {e}"),
                Ok(()) => panic!("restore ACCEPTED an out-of-range sprite count {bad_value}"),
            }
        }
    }

    #[test]
    fn an_out_of_range_raster_position_is_rejected() {
        // Found by the v2.7.0 fuzz target. Each legal extreme loads; one past
        // it, on either axis and for both frame heights, is refused.
        let decode = |region: PpuRegion, dot: u16, scanline: i16| {
            let mut p = Ppu::new(region);
            p.dot = dot;
            p.scanline = scanline;
            let blob = p.snapshot();
            Ppu::new(region).restore(&blob)
        };
        for region in [PpuRegion::Ntsc, PpuRegion::Pal] {
            let last = region.prerender_line();
            assert!(
                decode(region, 340, last).is_ok(),
                "{region:?}: the last dot loads"
            );
            assert!(
                decode(region, 340, -1).is_ok(),
                "{region:?}: the power-on position loads"
            );
            for (dot, scanline) in [
                (341, 0),
                (u16::MAX, 0),
                (0, last + 1),
                (0, -2),
                (0, i16::MIN),
            ] {
                assert!(
                    matches!(
                        decode(region, dot, scanline),
                        Err(PpuSnapshotError::InvalidRasterPosition { .. })
                    ),
                    "{region:?}: dot {dot}, scanline {scanline} must be rejected"
                );
            }
        }
    }

    #[test]
    fn every_ppu_counter_and_index_is_bounded_on_restore() {
        // v2.7.0. Each field is located by DIFFERENCE (two snapshots that
        // differ only in it), its largest kept value must load, and one past
        // it, 0x80 and 0xFF must each be refused with an error naming it.
        fn check(name: &'static str, max: u8, set: impl Fn(&mut Ppu, u8)) {
            let mut a = Ppu::new(PpuRegion::Ntsc);
            let mut b = Ppu::new(PpuRegion::Ntsc);
            set(&mut a, max.saturating_sub(1));
            set(&mut b, max);
            let (sa, sb) = (a.snapshot(), b.snapshot());
            let diffs: Vec<usize> = (0..sa.len()).filter(|&i| sa[i] != sb[i]).collect();
            assert_eq!(diffs.len(), 1, "{name} is one byte");
            let at = diffs[0];
            Ppu::new(PpuRegion::Ntsc)
                .restore(&sb)
                .unwrap_or_else(|e| panic!("{name} = {max} must load: {e}"));
            for bad in [max + 1, 0x80u8.max(max + 1), 0xFF] {
                let mut blob = sb.clone();
                blob[at] = bad;
                match Ppu::new(PpuRegion::Ntsc).restore(&blob) {
                    Err(PpuSnapshotError::FieldOutOfRange {
                        field,
                        value,
                        max: m,
                    }) => {
                        assert_eq!((field, value, m), (name, bad, max));
                    }
                    Err(e) => panic!("{name} = {bad}: wrong error {e}"),
                    Ok(()) => panic!("{name} = {bad}: restore ACCEPTED it"),
                }
            }
        }
        check("x", 7, |p, v| p.x = v);
        check("oam_corruption_index", 0x20, |p, v| {
            p.oam_corruption_index = v;
        });
        check("sprite_eval_n", 63, |p, v| p.sprite_eval_n = v);
        check("sprite_eval_m", 3, |p, v| p.sprite_eval_m = v);
        check("sprite_eval_found", 8, |p, v| p.sprite_eval_found = v);
        check("sprite_eval_sec_idx", 0x20, |p, v| {
            p.sprite_eval_sec_idx = v;
        });
        check("oam_bus_addr_h", 63, |p, v| p.oam_bus_addr_h = v);
        check("oam_bus_addr_l", 3, |p, v| p.oam_bus_addr_l = v);
        check("oam_bus_secondary_addr", 0x20, |p, v| {
            p.oam_bus_secondary_addr = v;
        });
        check("oam_bus_overflow_counter", 3, |p, v| {
            p.oam_bus_overflow_counter = v;
        });
        check("oam2_addr", 0x1F, |p, v| p.oam2_addr = v);
    }

    #[test]
    fn snapshot_round_trips_the_v9_oam2_counter_at_non_default_values() {
        // v9 added three OAM2 fields. The pre-existing round-trip tests leave
        // them at their power-on defaults (0 / false / false), so a reader and
        // writer that disagree about ORDER still round-trip cleanly: every
        // field reads back the value it already had. That is a test which
        // passes because nothing was distinguishable, not because anything was
        // verified -- the shape this project keeps paying for.
        //
        // `snapshot_schema_audit` cannot close it either: it checks that every
        // field is WRITTEN, never that the reader agrees about where.
        //
        // So set all three to values distinguishable from the defaults AND from
        // each other's types, then assert each one individually.
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.oam2_fetch_addr = 0x1B;
        p.oam2_overflowed = true;
        p.oam2_fetch_frozen = true;

        let blob = p.snapshot();
        assert_eq!(
            blob[0], PPU_SNAPSHOT_VERSION,
            "blob carries current version"
        );

        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.restore(&blob).unwrap();
        assert_eq!(q.oam2_fetch_addr, 0x1B, "OAM2 fetch address survives");
        assert!(q.oam2_overflowed, "the overflow flag survives");
        assert!(q.oam2_fetch_frozen, "the latched freeze flag survives");

        // The two flags are adjacent bools, so a reader that swapped them would
        // pass every assertion above. Pin the asymmetric case too.
        let mut r = Ppu::new(PpuRegion::Ntsc);
        r.oam2_fetch_addr = 0x07;
        r.oam2_overflowed = false;
        r.oam2_fetch_frozen = true;
        let mut t = Ppu::new(PpuRegion::Ntsc);
        t.restore(&r.snapshot()).unwrap();
        assert_eq!(t.oam2_fetch_addr, 0x07);
        assert!(!t.oam2_overflowed, "overflow flag is NOT the freeze flag");
        assert!(t.oam2_fetch_frozen, "freeze flag is NOT the overflow flag");
    }

    #[test]
    fn snapshot_round_trips_the_v6_tail_at_non_default_values() {
        // The v6 tail -- per-sprite `spr_halted` plus the six rendering /
        // OAM-corruption fields after it -- was round-tripped only at its
        // power-on defaults, so a reader that disagreed with the writer about
        // ORDER still passed: every field read back the value it already had.
        // `snapshot_schema_audit` proves only that each field is written.
        //
        // So flip ONE field at a time away from its default and compare the
        // whole tail after restore. A swapped pair of adjacent bools then
        // reads back as two wrong fields instead of two right ones.
        type Tail = ([bool; 8], bool, bool, bool, u8, bool, bool);
        fn tail(p: &Ppu) -> Tail {
            (
                p.spr_halted,
                p.prev_rendering_enabled,
                p.rendering_enabled_delayed,
                p.oam_corruption_pending,
                p.oam_corruption_index,
                p.oam_corruption_disabled,
                p.oam_corruption_disabled_instant,
            )
        }
        type Setter = fn(&mut Ppu);
        let cases: [(&str, Setter); 14] = [
            ("spr_halted[0]", |p| p.spr_halted[0] = false),
            ("spr_halted[1]", |p| p.spr_halted[1] = false),
            ("spr_halted[2]", |p| p.spr_halted[2] = false),
            ("spr_halted[3]", |p| p.spr_halted[3] = false),
            ("spr_halted[4]", |p| p.spr_halted[4] = false),
            ("spr_halted[5]", |p| p.spr_halted[5] = false),
            ("spr_halted[6]", |p| p.spr_halted[6] = false),
            ("spr_halted[7]", |p| p.spr_halted[7] = false),
            ("prev_rendering_enabled", |p| {
                p.prev_rendering_enabled = true;
            }),
            ("rendering_enabled_delayed", |p| {
                p.rendering_enabled_delayed = true;
            }),
            ("oam_corruption_pending", |p| {
                p.oam_corruption_pending = true;
            }),
            ("oam_corruption_index", |p| p.oam_corruption_index = 0x1F),
            ("oam_corruption_disabled", |p| {
                p.oam_corruption_disabled = true;
            }),
            ("oam_corruption_disabled_instant", |p| {
                p.oam_corruption_disabled_instant = true;
            }),
        ];
        let default_tail = tail(&Ppu::new(PpuRegion::Ntsc));
        for (name, set) in cases {
            let mut p = Ppu::new(PpuRegion::Ntsc);
            set(&mut p);
            let expected = tail(&p);
            assert_ne!(
                expected, default_tail,
                "{name}: the case must change something"
            );
            let mut q = Ppu::new(PpuRegion::Ntsc);
            q.restore(&p.snapshot()).unwrap();
            assert_eq!(
                tail(&q),
                expected,
                "{name} did not survive snapshot/restore"
            );
        }
    }

    #[test]
    fn snapshot_round_trips_sprite_evaluation_state() {
        // v8: a snapshot taken with a sprite-evaluation pass in flight (dots
        // 65..=256) must restore the FSM's pointers and phase, not just the
        // `secondary_oam` buffer they fill. Before this tail, run-ahead's
        // per-frame snapshot/restore silently reset the walker while keeping the
        // buffer, costing three AccuracyCoin tests on the desktop frontend.
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.sprite_eval_read_latch = 0x5A;
        p.sprite_eval_n = 37;
        p.sprite_eval_m = 2;
        p.sprite_eval_found = 6;
        p.sprite_eval_sec_idx = 25;
        p.sprite_eval_copying = true;
        p.sprite_eval_done = false;
        p.sprite_eval_overflow_search = true;
        p.sprite_eval_zero_found = true;
        p.sprite_eval_first_iter = false;
        p.oam_bus_copybuffer = 0xC3;
        p.oam_bus_secondary = [0x11; 32];
        p.oam_bus_secondary[7] = 0x99;
        p.oam_bus_addr_h = 41;
        p.oam_bus_addr_l = 3;
        p.oam_bus_secondary_addr = 18;
        p.oam_bus_copy_done = true;
        p.oam_bus_sprite_in_range = true;
        // 2, not the 5 this test used before v2.7.0: the running PPU loads the
        // counter with 3 and counts down, and restore now rejects anything
        // above 3. 2 is still distinct from every neighbouring field.
        p.oam_bus_overflow_counter = 2;
        p.oam2_addr = 12;

        let blob = p.snapshot();
        assert_eq!(
            blob[0], PPU_SNAPSHOT_VERSION,
            "blob carries current version"
        );

        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.restore(&blob).unwrap();
        assert_eq!(q.sprite_eval_read_latch, 0x5A);
        assert_eq!(q.sprite_eval_n, 37);
        assert_eq!(q.sprite_eval_m, 2);
        assert_eq!(q.sprite_eval_found, 6);
        assert_eq!(q.sprite_eval_sec_idx, 25);
        assert!(q.sprite_eval_copying);
        assert!(!q.sprite_eval_done);
        assert!(q.sprite_eval_overflow_search);
        assert!(q.sprite_eval_zero_found);
        assert!(!q.sprite_eval_first_iter);
        assert_eq!(q.oam_bus_copybuffer, 0xC3);
        assert_eq!(q.oam_bus_secondary[7], 0x99);
        assert_eq!(q.oam_bus_secondary[0], 0x11);
        assert_eq!(q.oam_bus_addr_h, 41);
        assert_eq!(q.oam_bus_addr_l, 3);
        assert_eq!(q.oam_bus_secondary_addr, 18);
        assert!(q.oam_bus_copy_done);
        assert!(q.oam_bus_sprite_in_range);
        assert_eq!(q.oam_bus_overflow_counter, 2);
        assert_eq!(q.oam2_addr, 12);
    }

    #[test]
    fn restore_invalidates_the_scanline_classification_cache() {
        // The cache is derived (a pure function of `scanline` + `region`) and so
        // deliberately NOT serialized. Restore must therefore reset its KEY to
        // the `Ppu::new` sentinel: a warm key inherited from another timeline
        // would otherwise satisfy the fast dot path's
        // `scanline == flags_cached_scanline` guard against a stale value.
        let p = Ppu::new(PpuRegion::Ntsc);
        let blob = p.snapshot();

        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.cached_visible = true;
        q.cached_pre_render = true;
        q.cached_render_line = true;
        q.flags_cached_scanline = 42;
        q.restore(&blob).unwrap();
        assert!(!q.cached_visible);
        assert!(!q.cached_pre_render);
        assert!(!q.cached_render_line);
        assert_eq!(q.flags_cached_scanline, i16::MIN);
    }

    #[test]
    fn snapshot_round_trips_extra_lines_remaining() {
        // v1.7.0 F3: a save-state taken mid-insertion (extra_lines_remaining
        // > 0) must restore the in-flight countdown, not reset it to 0.
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.set_extra_scanlines(8);
        p.extra_lines_remaining = 5;
        let blob = p.snapshot();
        assert_eq!(
            blob[0], PPU_SNAPSHOT_VERSION,
            "blob carries current version"
        );

        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.restore(&blob).unwrap();
        assert_eq!(q.extra_lines_remaining, 5);
    }

    #[test]
    fn a_restored_extra_lines_countdown_is_clamped_to_the_live_knob() {
        // Review finding on #546: a corrupt countdown under a live
        // extra-scanlines knob idled the PPU for up to 65,535 lines.
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.set_extra_scanlines(8);
        p.extra_lines_remaining = u16::MAX;
        let blob = p.snapshot();

        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.set_extra_scanlines(8);
        q.restore(&blob).unwrap();
        assert_eq!(q.extra_lines_remaining, 8, "clamped to the knob in force");

        // A countdown already inside the knob is untouched.
        p.extra_lines_remaining = 5;
        let mut r = Ppu::new(PpuRegion::Ntsc);
        r.set_extra_scanlines(8);
        r.restore(&p.snapshot()).unwrap();
        assert_eq!(r.extra_lines_remaining, 5);
    }

    #[test]
    fn snapshot_round_trips_2cycle_ale_fetch_state() {
        // v2.0.3 (ADR 0030): a checkpoint taken mid-render (netplay rollback)
        // can land with the 2-cycle-ALE fetch model's in-flight state live —
        // the octal latch / multiplexed bus, the ALE arm, and the two corruption
        // one-shots (`pattern_latch_stale`, the delayed-`CopyV` `copy_v_delay`).
        // They must round-trip so the re-simulated frame is byte-identical to the
        // forward run (else the peers desync). Regression pin for the promotion.
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.octal_latch = 0x19;
        p.address_bus = 0x2F19;
        p.ale_armed = true;
        p.pattern_latch_stale = true;
        p.copy_v_delay = 3;
        let blob = p.snapshot();

        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.restore(&blob).unwrap();
        assert_eq!(q.octal_latch, 0x19);
        assert_eq!(q.address_bus, 0x2F19);
        assert!(q.ale_armed);
        assert!(q.pattern_latch_stale);
        assert_eq!(q.copy_v_delay, 3);
    }

    /// v2.3.3 — a slim blob must be dramatically smaller, and the size
    /// difference must be exactly the framebuffer.
    #[test]
    fn slim_snapshot_omits_exactly_the_framebuffer() {
        let p = Ppu::new(PpuRegion::Ntsc);
        let full = p.snapshot();
        let slim = p.snapshot_slim();
        assert_eq!(
            full.len() - slim.len(),
            FRAMEBUFFER_LEN,
            "slim must differ from full by exactly the framebuffer"
        );
    }

    /// A slim blob restores every field EXCEPT the framebuffer, which it must
    /// leave untouched (the caller regenerates the image).
    #[test]
    fn slim_restore_preserves_the_existing_framebuffer() {
        let mut src = Ppu::new(PpuRegion::Ntsc);
        src.framebuffer[100] = 0xAB;
        src.spr_count = 5;
        let slim = src.snapshot_slim();

        let mut dst = Ppu::new(PpuRegion::Ntsc);
        dst.framebuffer[100] = 0xEF; // must survive the restore
        dst.spr_count = 0;
        dst.restore(&slim).expect("slim blob restores");
        assert_eq!(dst.spr_count, 5, "non-framebuffer state must restore");
        assert_eq!(
            dst.framebuffer[100], 0xEF,
            "slim restore must not touch the framebuffer"
        );
    }

    /// The flag must not disturb the existing format: a full blob still round
    /// trips its framebuffer, and its version byte has the flag clear.
    #[test]
    fn full_snapshot_is_unchanged_by_the_slim_flag() {
        let mut src = Ppu::new(PpuRegion::Ntsc);
        src.framebuffer[100] = 0xAB;
        let full = src.snapshot();
        assert_eq!(full[0] & PPU_SNAPSHOT_SLIM_FLAG, 0, "flag clear on full");
        assert_eq!(full[0], PPU_SNAPSHOT_VERSION);
        let mut dst = Ppu::new(PpuRegion::Ntsc);
        dst.restore(&full).expect("full blob restores");
        assert_eq!(dst.framebuffer[100], 0xAB);
    }

    /// A truncated slim blob must still be rejected — the relaxed minimum
    /// must not become a hole that accepts garbage.
    #[test]
    fn truncated_slim_blob_is_still_rejected() {
        let p = Ppu::new(PpuRegion::Ntsc);
        let slim = p.snapshot_slim();
        let mut dst = Ppu::new(PpuRegion::Ntsc);
        assert!(dst.restore(&slim[..slim.len() / 2]).is_err());
    }

    /// NC-14 (v2.9.9 re-audit): a blob with a byte appended is refused as
    /// trailing bytes, not as a truncation at its own end offset.
    #[test]
    fn a_long_blob_is_reported_as_trailing_bytes() {
        let p = Ppu::new(PpuRegion::Ntsc);
        let mut long = p.snapshot();
        let len = long.len();
        long.push(0);
        let mut dst = Ppu::new(PpuRegion::Ntsc);
        let err = dst.restore(&long).unwrap_err();
        assert!(
            matches!(err, PpuSnapshotError::TrailingBytes { consumed, extra: 1 } if consumed == len),
            "got {err:?}"
        );
    }

    #[test]
    fn snapshot_round_trips_oam_decay_ages() {
        // v2.1.4 F2.3: the optional OAM-decay per-row timestamps must round-trip.
        // They are stored as a RELATIVE AGE against the un-serialized `dot_counter`,
        // so the exact absolute value is preserved only when the restoring instance
        // shares the same live counter (the normal same-instance snapshot/restore).
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.set_oam_decay(true);
        p.dot_counter = 90_000; // now = 30_000 CPU cycles
        // Distinct per-row timestamps (ages 0, 3, 6, ... spread across the array).
        for (i, ts) in p.oam_decay_cycles.iter_mut().enumerate() {
            *ts = 30_000 - (i as u64 * 3);
        }
        let blob = p.snapshot();
        assert_eq!(
            blob[0], PPU_SNAPSHOT_VERSION,
            "blob carries current version"
        );

        // Restore into an instance with the SAME live counter → exact timestamps.
        let mut q = Ppu::new(PpuRegion::Pal);
        q.dot_counter = 90_000;
        q.restore(&blob).unwrap();
        assert_eq!(
            q.oam_decay_cycles, p.oam_decay_cycles,
            "absolute timestamps preserved when the live counter matches"
        );

        // Restore into an instance whose counter has been REBASED (the rollback
        // case): the *relative age* — what the decay clock actually consumes — must
        // be identical, even though the absolute timestamps differ.
        let mut q2 = Ppu::new(PpuRegion::Ntsc);
        q2.dot_counter = 3 * 1_000_000; // a wildly different base (now = 1_000_000)
        q2.restore(&blob).unwrap();
        let now_p = p.dot_counter / 3;
        let now_q2 = q2.dot_counter / 3;
        for i in 0..32 {
            let age_p = now_p.wrapping_sub(p.oam_decay_cycles[i]);
            let age_q2 = now_q2.wrapping_sub(q2.oam_decay_cycles[i]);
            assert_eq!(age_p, age_q2, "row {i} age preserved across counter rebase");
        }
    }

    #[test]
    fn snapshot_default_extra_lines_remaining_is_zero() {
        // At the default extra_scanlines == 0 the countdown is always 0, so
        // the v4 field is a zero u16 and restore is behaviourally identical.
        let p = Ppu::new(PpuRegion::Ntsc);
        assert_eq!(p.extra_lines_remaining, 0);
        let blob = p.snapshot();
        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.restore(&blob).unwrap();
        assert_eq!(q.extra_lines_remaining, 0);
    }

    #[test]
    fn set_extra_scanlines_resets_in_flight_countdown() {
        // Changing the configured count cancels any in-flight insertion so
        // the per-frame countdown cannot remain stale/out-of-bounds.
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.set_extra_scanlines(8);
        p.extra_lines_remaining = 6;
        p.set_extra_scanlines(2);
        assert_eq!(p.extra_lines_remaining, 0);
        p.extra_lines_remaining = 1;
        p.set_extra_scanlines(0); // disable
        assert_eq!(p.extra_lines_remaining, 0);
    }
}