rustynes_core/

save_state.rs

//! Save-state container format for `RustyNES` v2.
//!
//! Per `CLAUDE.md` "Open questions worth knowing": tagged-section per chip
//! with version byte; cross-version compatibility is best-effort, not
//! guaranteed.
//!
//! # On-wire layout
//!
//! ```text
//! HEADER (16 bytes):
//!     magic       : "RUSTYNES"  (8 bytes)
//!     format ver  : u16 little-endian  (currently 3 -- see [`FORMAT_VERSION`])
//!     rom sha-256 : truncated to 6 bytes (sanity tag, not authoritative)
//!
//! BODY (sections in any order, each):
//!     tag         : [u8; 4]  e.g. b"CPU ", b"PPU ", b"APU ", b"MAP "
//!     version     : u8       per-section schema version
//!     length      : u32 little-endian (body bytes after this length field)
//!     body        : `length` bytes
//! ```
//!
//! Determinism: every `snapshot()` for a given `(seed, ROM, input sequence)`
//! produces bit-identical bytes. Loading is order-independent.

use alloc::{format, string::String, vec::Vec};
use thiserror::Error;

/// Magic header bytes — first 8 bytes of every `.rns` file.
pub const MAGIC: &[u8; 8] = b"RUSTYNES";

/// Current container-format version.
///
/// - v1 (v0.9.0 ..): the tagged-section container as documented above.
/// - **v2 (v2.0.0 "Timebase" rc.1, ADR 0028)**: marks the MAJOR-boundary
///   line. The container's own on-wire layout is unchanged (this field
///   only guards forward-compat -- a reader rejects any blob whose
///   `format_version` exceeds its own [`FORMAT_VERSION`]); the real
///   v2.0.0-line rejection happens per-section, via the strict version
///   equality checks each chip's snapshot module already enforces (see
///   `rustynes_cpu::CPU_SNAPSHOT_VERSION`'s v3 bump for the concrete
///   example). This bump exists so a `.rns` file's header alone signals
///   which release line produced it, without needing to inspect every
///   section.
/// - **v3 (v2.9.8, ADR 0042)**: the second epoch. The layout is unchanged
///   again; what changes is that a reader now also refuses any blob OLDER
///   than [`MIN_FORMAT_VERSION`], with [`SnapshotError::FormatTooOld`]. v2.9.8
///   removed every legacy-format reader in the section decoders (BUS section
///   2, and the PPU, APU and mapper upconversions), and several sections kept
///   their version numbers because their layouts did not move, so without a
///   container check a v2.9.7 file would be refused only at whichever section
///   happened to come first. One header check gives one clear message.
pub const FORMAT_VERSION: u16 = 3;

/// Oldest container-format version this build reads.
///
/// Since v2.9.8 that is the current one only (ADR 0042, following ADR 0028's
/// v2.0.0 epoch). A `.rns` file from v2.9.7 or earlier carries 2 (or 1) and
/// is refused at the header.
pub const MIN_FORMAT_VERSION: u16 = 3;

/// Length of the truncated ROM SHA-256 we embed in the header (sanity tag).
pub const ROM_HASH_TAG_LEN: usize = 6;

/// Header byte length.
pub const HEADER_LEN: usize = 8 + 2 + ROM_HASH_TAG_LEN;

/// Section tags. The fixed-width 4-byte format keeps parsing trivial and
/// avoids string allocation on the hot path.
pub mod tag {
    /// CPU (2A03 / 6502) state.
    pub const CPU: [u8; 4] = *b"CPU ";
    /// PPU (2C02) state.
    pub const PPU: [u8; 4] = *b"PPU ";
    /// APU (2A03 audio) state.
    pub const APU: [u8; 4] = *b"APU ";
    /// Mapper state (delegates to `Mapper::save_state`).
    pub const MAP: [u8; 4] = *b"MAP ";
    /// Bus / scheduler state (RAM, DMA, NMI edge latches, cycle counter).
    pub const BUS: [u8; 4] = *b"BUS ";
    /// Optional UI thumbnail (128x120 RGBA8 nearest-neighbor of the current
    /// framebuffer). NOT part of the deterministic save-state contract --
    /// frontends use it for slot pickers. See ADR 0003.
    pub const THM: [u8; 4] = *b"THM ";
}

/// Thumbnail width in pixels (1/2 native NES width).
pub const THUMBNAIL_WIDTH: usize = 128;
/// Thumbnail height in pixels (1/2 native NES height).
pub const THUMBNAIL_HEIGHT: usize = 120;
/// Thumbnail byte length (`THUMBNAIL_WIDTH * THUMBNAIL_HEIGHT * 4`, RGBA8).
pub const THUMBNAIL_LEN: usize = THUMBNAIL_WIDTH * THUMBNAIL_HEIGHT * 4;
/// Body version byte for the `THM ` section.
pub const THUMBNAIL_VERSION: u8 = 1;

/// v3.0.0 — which way a section version differs, in words a player can act
/// on ([`SnapshotError::VersionMismatch`]).
const fn section_version_hint(file_version: u8, this_build: u8) -> &'static str {
    if file_version < this_build {
        "it was saved by an older release of RustyNES, whose states this version \
         cannot load; re-create it from the game or an in-game save"
    } else {
        "it was saved by a newer release of RustyNES; load it with that version"
    }
}

/// Errors produced by save-state encode / decode.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum SnapshotError {
    /// The blob is shorter than the header.
    #[error("save state truncated: header needs {expected} bytes, got {got}")]
    HeaderTruncated {
        /// Expected byte count.
        expected: usize,
        /// Actual byte count.
        got: usize,
    },

    /// The magic prefix is wrong.
    #[error("save state magic mismatch: expected {:?}, got {got:?}", MAGIC)]
    BadMagic {
        /// Bytes observed at the magic offset.
        got: [u8; 8],
    },

    /// The container format version is outside the range we understand.
    #[error("save state container format version {got} not supported (max {max})")]
    UnsupportedFormat {
        /// Version we read.
        got: u16,
        /// Highest version we accept.
        max: u16,
    },

    /// The container is from an older release whose save states this build no
    /// longer reads (v2.9.8, ADR 0042: v2.9.7 and earlier).
    #[error(
        "save state container format version {got} is from an older release; this build reads version {min} and later"
    )]
    FormatTooOld {
        /// Version we read.
        got: u16,
        /// Oldest version we accept ([`MIN_FORMAT_VERSION`]).
        min: u16,
    },

    /// A section body is shorter than its declared length.
    #[error("save state section {tag} body truncated: declared {declared} bytes, got {got}")]
    SectionTruncated {
        /// 4-byte tag (printable ASCII).
        tag: String,
        /// Declared length.
        declared: usize,
        /// Bytes actually available.
        got: usize,
    },

    /// A section had a version this build does not handle.
    ///
    /// Every section reader accepts only its current layout (v2.9.8, ADR
    /// 0042), so this is what a state saved by another release of `RustyNES`
    /// fails with, when its container format is still current: v2.9.8's and
    /// v2.9.9's states, at v3.0.0. The message therefore says which way the
    /// versions differ (v3.0.0; until then it gave only the two numbers, and
    /// players read it as a damaged file).
    #[error(
        "save state section {tag} version {file_version} not supported (this build reads \
         {chip_supports}): {}",
        section_version_hint(*file_version, *chip_supports)
    )]
    VersionMismatch {
        /// 4-byte tag (printable ASCII).
        tag: String,
        /// Version recorded in the file.
        file_version: u8,
        /// Highest version the running chip accepts.
        chip_supports: u8,
    },

    /// A section's body failed internal consistency checks.
    #[error("save state section {tag}: {reason}")]
    SectionInvalid {
        /// 4-byte tag (printable ASCII).
        tag: String,
        /// Free-form reason.
        reason: String,
    },

    /// A required section was missing.
    #[error("save state missing required section {0}")]
    MissingSection(String),

    /// A section blob ran past EOF.
    #[error("save state truncated mid-section at offset {0}")]
    Eof(usize),
}

impl SnapshotError {
    /// Construct a [`Self::SectionInvalid`] with a borrowed tag.
    pub fn invalid(tag: [u8; 4], reason: impl Into<String>) -> Self {
        Self::SectionInvalid {
            tag: tag_string(tag),
            reason: reason.into(),
        }
    }
}

/// Render a 4-byte tag back into a `String` (lossy — non-ASCII becomes `?`).
#[must_use]
pub fn tag_string(t: [u8; 4]) -> String {
    let mut s = String::with_capacity(4);
    for b in t {
        s.push(if (0x20..=0x7E).contains(&b) {
            char::from(b)
        } else {
            '?'
        });
    }
    s
}

/// Cursor-style binary writer used by chip snapshot encoders.
///
/// Little-endian for all multi-byte integers; bools are 1 byte (`0` / `1`);
/// optional values are tagged with a presence byte.
#[derive(Debug, Default)]
pub struct BinWriter {
    buf: Vec<u8>,
}

impl BinWriter {
    /// Empty writer.
    #[must_use]
    pub const fn new() -> Self {
        Self { buf: Vec::new() }
    }

    /// Pre-sized writer.
    #[must_use]
    pub fn with_capacity(cap: usize) -> Self {
        Self {
            buf: Vec::with_capacity(cap),
        }
    }

    /// Take the inner buffer.
    #[must_use]
    pub fn into_vec(self) -> Vec<u8> {
        self.buf
    }

    /// Currently-accumulated byte count.
    #[must_use]
    pub const fn len(&self) -> usize {
        self.buf.len()
    }

    /// `true` if no bytes have been written.
    #[must_use]
    pub const fn is_empty(&self) -> bool {
        self.buf.is_empty()
    }

    /// Append one byte.
    pub fn u8(&mut self, v: u8) {
        self.buf.push(v);
    }

    /// Append a u16 little-endian.
    pub fn u16(&mut self, v: u16) {
        self.buf.extend_from_slice(&v.to_le_bytes());
    }

    /// Append a u32 little-endian.
    pub fn u32(&mut self, v: u32) {
        self.buf.extend_from_slice(&v.to_le_bytes());
    }

    /// Append a u64 little-endian.
    pub fn u64(&mut self, v: u64) {
        self.buf.extend_from_slice(&v.to_le_bytes());
    }

    /// Append an i16 little-endian.
    pub fn i16(&mut self, v: i16) {
        self.buf.extend_from_slice(&v.to_le_bytes());
    }

    /// Append a bool as 1 byte.
    pub fn bool(&mut self, v: bool) {
        self.buf.push(u8::from(v));
    }

    /// Append a raw byte slice.
    pub fn bytes(&mut self, v: &[u8]) {
        self.buf.extend_from_slice(v);
    }

    /// Append a length-prefixed byte slice (u32 le length).
    pub fn lp_bytes(&mut self, v: &[u8]) {
        self.u32(u32::try_from(v.len()).expect("slice too large for save state"));
        self.bytes(v);
    }
}

/// Cursor-style binary reader, the inverse of [`BinWriter`].
#[derive(Debug)]
pub struct BinReader<'a> {
    src: &'a [u8],
    pos: usize,
}

impl<'a> BinReader<'a> {
    /// New reader.
    #[must_use]
    pub const fn new(src: &'a [u8]) -> Self {
        Self { src, pos: 0 }
    }

    /// Bytes remaining.
    #[must_use]
    pub const fn remaining(&self) -> usize {
        self.src.len() - self.pos
    }

    /// `true` if the cursor is at end-of-input.
    #[must_use]
    pub const fn is_empty(&self) -> bool {
        self.remaining() == 0
    }

    /// Current byte offset.
    #[must_use]
    pub const fn pos(&self) -> usize {
        self.pos
    }

    const fn need(&self, n: usize) -> Result<(), SnapshotError> {
        if self.remaining() < n {
            return Err(SnapshotError::Eof(self.pos));
        }
        Ok(())
    }

    /// Read one byte.
    ///
    /// # Errors
    ///
    /// Returns [`SnapshotError::Eof`] on EOF.
    pub fn u8(&mut self) -> Result<u8, SnapshotError> {
        self.need(1)?;
        let v = self.src[self.pos];
        self.pos += 1;
        Ok(v)
    }

    /// Read a u16 little-endian.
    ///
    /// # Errors
    ///
    /// Returns [`SnapshotError::Eof`] on EOF.
    pub fn u16(&mut self) -> Result<u16, SnapshotError> {
        self.need(2)?;
        let v = u16::from_le_bytes([self.src[self.pos], self.src[self.pos + 1]]);
        self.pos += 2;
        Ok(v)
    }

    /// Read a u32 little-endian.
    ///
    /// # Errors
    ///
    /// Returns [`SnapshotError::Eof`] on EOF.
    pub fn u32(&mut self) -> Result<u32, SnapshotError> {
        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))
    }

    /// Read a u64 little-endian.
    ///
    /// # Errors
    ///
    /// Returns [`SnapshotError::Eof`] on EOF.
    pub fn u64(&mut self) -> Result<u64, SnapshotError> {
        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))
    }

    /// Read an i16 little-endian.
    ///
    /// # Errors
    ///
    /// Returns [`SnapshotError::Eof`] on EOF.
    pub fn i16(&mut self) -> Result<i16, SnapshotError> {
        self.need(2)?;
        let v = i16::from_le_bytes([self.src[self.pos], self.src[self.pos + 1]]);
        self.pos += 2;
        Ok(v)
    }

    /// Read a bool (any non-zero byte counts as true).
    ///
    /// # Errors
    ///
    /// Returns [`SnapshotError::Eof`] on EOF.
    pub fn bool(&mut self) -> Result<bool, SnapshotError> {
        Ok(self.u8()? != 0)
    }

    /// Read `n` bytes (returns a borrowed slice).
    ///
    /// # Errors
    ///
    /// Returns [`SnapshotError::Eof`] on EOF.
    pub fn take(&mut self, n: usize) -> Result<&'a [u8], SnapshotError> {
        self.need(n)?;
        let s = &self.src[self.pos..self.pos + n];
        self.pos += n;
        Ok(s)
    }

    /// Read into a fixed-length destination.
    ///
    /// # Errors
    ///
    /// Returns [`SnapshotError::Eof`] on EOF.
    pub fn read_into(&mut self, dst: &mut [u8]) -> Result<(), SnapshotError> {
        let s = self.take(dst.len())?;
        dst.copy_from_slice(s);
        Ok(())
    }

    /// Read a length-prefixed byte slice (u32 le length followed by the bytes).
    ///
    /// # Errors
    ///
    /// Returns [`SnapshotError::Eof`] on EOF.
    pub fn lp_bytes(&mut self) -> Result<&'a [u8], SnapshotError> {
        let n = self.u32()? as usize;
        self.take(n)
    }
}

/// Encode a section header (`tag` + `version` + `length`) into `out` and
/// then append the body bytes.
pub fn write_section(out: &mut Vec<u8>, tag: [u8; 4], version: u8, body: &[u8]) {
    out.extend_from_slice(&tag);
    out.push(version);
    let len = u32::try_from(body.len()).expect("section body too large");
    out.extend_from_slice(&len.to_le_bytes());
    out.extend_from_slice(body);
}

/// Decoded view of one section's metadata + body slice.
#[derive(Debug, Clone, Copy)]
pub struct Section<'a> {
    /// Tag bytes (e.g. `b"CPU "`).
    pub tag: [u8; 4],
    /// Per-section schema version.
    pub version: u8,
    /// Body slice (does NOT include the header itself).
    pub body: &'a [u8],
}

/// Header decoded from the start of the blob.
#[derive(Debug, Clone)]
pub struct Header {
    /// Container format version (matches [`FORMAT_VERSION`] when written by
    /// this build).
    pub format_version: u16,
    /// Truncated ROM SHA-256 sanity tag.
    pub rom_hash_tag: [u8; ROM_HASH_TAG_LEN],
}

/// Parse the 16-byte header.
///
/// # Errors
///
/// - [`SnapshotError::HeaderTruncated`] if `bytes` is shorter than 16 bytes.
/// - [`SnapshotError::BadMagic`] on a bad prefix.
/// - [`SnapshotError::UnsupportedFormat`] if the format version is past
///   [`FORMAT_VERSION`].
pub fn parse_header(bytes: &[u8]) -> Result<(Header, usize), SnapshotError> {
    if bytes.len() < HEADER_LEN {
        return Err(SnapshotError::HeaderTruncated {
            expected: HEADER_LEN,
            got: bytes.len(),
        });
    }
    let mut magic = [0u8; 8];
    magic.copy_from_slice(&bytes[..8]);
    if &magic != MAGIC {
        return Err(SnapshotError::BadMagic { got: magic });
    }
    let format_version = u16::from_le_bytes([bytes[8], bytes[9]]);
    if format_version > FORMAT_VERSION {
        return Err(SnapshotError::UnsupportedFormat {
            got: format_version,
            max: FORMAT_VERSION,
        });
    }
    if format_version < MIN_FORMAT_VERSION {
        return Err(SnapshotError::FormatTooOld {
            got: format_version,
            min: MIN_FORMAT_VERSION,
        });
    }
    let mut rom_hash_tag = [0u8; ROM_HASH_TAG_LEN];
    rom_hash_tag.copy_from_slice(&bytes[10..16]);
    Ok((
        Header {
            format_version,
            rom_hash_tag,
        },
        HEADER_LEN,
    ))
}

/// Iterate sections starting at `bytes` (which should begin immediately
/// after the header).
pub struct SectionIter<'a> {
    src: &'a [u8],
    pos: usize,
}

impl<'a> SectionIter<'a> {
    /// New section iterator at the start of the body.
    #[must_use]
    pub const fn new(body: &'a [u8]) -> Self {
        Self { src: body, pos: 0 }
    }
}

impl<'a> Iterator for SectionIter<'a> {
    type Item = Result<Section<'a>, SnapshotError>;

    fn next(&mut self) -> Option<Self::Item> {
        if self.pos >= self.src.len() {
            return None;
        }
        // v2.8.0 (libretro audit §2.2) -- an all-zero tail is padding, not a
        // section. No tag this format writes contains a zero byte (every tag is
        // four printable ASCII characters, `write_section`'s only callers use
        // `tag::*` literals), so a run of zeros that reaches the end of the blob
        // cannot begin a section. The libretro core pads to its advertised
        // `retro_serialize_size`, which reserves room for expansion devices;
        // without this, whether its own state loaded back depended on the
        // padding length mod 9. Any non-zero byte in the tail still reaches the
        // header parse below and errors as before. Cost: the scan below runs
        // only when a tag would start with a zero byte, which no written tag
        // does, and at most once, because either outcome ends the iteration.
        //
        // And a zero byte where a tag starts is never a section, padding or
        // not (review on #556, CodeRabbit): without this, nine zero bytes
        // framed as an empty zero-tagged section, which restore skips as an
        // unknown tag, so a crafted blob of such headers followed by one
        // non-zero byte re-ran the scan above once per header -- quadratic.
        // Now the scan runs at most once: the tail is padding, or the blob is
        // rejected here.
        if self.src[self.pos] == 0 {
            let at = self.pos;
            self.pos = self.src.len();
            if self.src[at..].iter().all(|&b| b == 0) {
                return None;
            }
            return Some(Err(SnapshotError::SectionInvalid {
                tag: String::from("(zero)"),
                reason: format!(
                    "a section tag cannot start with a zero byte (offset {at}), and the \
                     bytes after it are not all padding"
                ),
            }));
        }
        // tag(4) + version(1) + len(4) = 9-byte section header.
        if self.src.len() - self.pos < 9 {
            let at = self.pos;
            self.pos = self.src.len(); // fuse, as for a bad length below
            return Some(Err(SnapshotError::Eof(at)));
        }
        let mut tag = [0u8; 4];
        tag.copy_from_slice(&self.src[self.pos..self.pos + 4]);
        let version = self.src[self.pos + 4];
        let mut len_bytes = [0u8; 4];
        len_bytes.copy_from_slice(&self.src[self.pos + 5..self.pos + 9]);
        let len = u32::from_le_bytes(len_bytes) as usize;
        let body_start = self.pos + 9;
        // `checked_add`, not `+` (core audit IMP-03). `len` is an untrusted
        // `u32` from the file; where `usize` is 32 bits (`wasm32`, the
        // `thumbv7em` no_std target) `body_start + len` can wrap to a small
        // value that passes the bounds test below and slices the wrong bytes,
        // or panics in a debug build. On 64-bit hosts it cannot overflow, which
        // is why no native test ever saw it.
        let body_end = match body_start.checked_add(len) {
            Some(end) if end <= self.src.len() => end,
            _ => {
                // Fuse: a malformed length leaves `pos` unable to advance, so
                // without this every later `next()` would return the same
                // error forever -- an infinite iterator for any caller that
                // skips errors rather than stopping on the first.
                let got = self.src.len() - body_start;
                self.pos = self.src.len();
                return Some(Err(SnapshotError::SectionTruncated {
                    tag: tag_string(tag),
                    declared: len,
                    got,
                }));
            }
        };
        let body = &self.src[body_start..body_end];
        self.pos = body_end;
        Some(Ok(Section { tag, version, body }))
    }
}

/// Build the 16-byte header into `out`.
pub fn write_header(out: &mut Vec<u8>, rom_hash_tag: [u8; ROM_HASH_TAG_LEN]) {
    out.extend_from_slice(MAGIC);
    out.extend_from_slice(&FORMAT_VERSION.to_le_bytes());
    out.extend_from_slice(&rom_hash_tag);
}

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

    #[test]
    fn header_round_trip() {
        let mut out = Vec::new();
        write_header(&mut out, [1, 2, 3, 4, 5, 6]);
        assert_eq!(out.len(), HEADER_LEN);
        let (h, off) = parse_header(&out).unwrap();
        assert_eq!(h.format_version, FORMAT_VERSION);
        assert_eq!(h.rom_hash_tag, [1, 2, 3, 4, 5, 6]);
        assert_eq!(off, HEADER_LEN);
    }

    #[test]
    fn header_rejects_bad_magic() {
        let mut out = Vec::new();
        out.extend_from_slice(b"NOTRUSTY");
        out.extend_from_slice(&[0u8; HEADER_LEN - 8]);
        assert!(matches!(
            parse_header(&out),
            Err(SnapshotError::BadMagic { .. })
        ));
    }

    #[test]
    fn header_rejects_too_new_format() {
        let mut out = Vec::new();
        out.extend_from_slice(MAGIC);
        out.extend_from_slice(&u16::MAX.to_le_bytes());
        out.extend_from_slice(&[0u8; ROM_HASH_TAG_LEN]);
        assert!(matches!(
            parse_header(&out),
            Err(SnapshotError::UnsupportedFormat { .. })
        ));
    }

    /// v2.9.8 (ADR 0042): a container from v2.9.7 or earlier (format 2, or
    /// the pre-v2.0.0 format 1) is refused at the header, with the typed
    /// "older release" error rather than a section-level one.
    #[test]
    fn header_rejects_formats_older_than_the_minimum() {
        for old in 0..MIN_FORMAT_VERSION {
            let mut out = Vec::new();
            out.extend_from_slice(MAGIC);
            out.extend_from_slice(&old.to_le_bytes());
            out.extend_from_slice(&[0u8; ROM_HASH_TAG_LEN]);
            assert!(matches!(
                parse_header(&out),
                Err(SnapshotError::FormatTooOld { got, min })
                    if got == old && min == MIN_FORMAT_VERSION
            ));
        }
        assert_eq!(MIN_FORMAT_VERSION, FORMAT_VERSION);
    }

    #[test]
    fn section_iter_round_trip() {
        let mut out = Vec::new();
        write_section(&mut out, *b"AAAA", 1, &[1, 2, 3]);
        write_section(&mut out, *b"BBBB", 7, &[4, 5, 6, 7, 8]);
        let mut it = SectionIter::new(&out);
        let s1 = it.next().unwrap().unwrap();
        assert_eq!(&s1.tag, b"AAAA");
        assert_eq!(s1.version, 1);
        assert_eq!(s1.body, &[1, 2, 3]);
        let s2 = it.next().unwrap().unwrap();
        assert_eq!(&s2.tag, b"BBBB");
        assert_eq!(s2.version, 7);
        assert_eq!(s2.body, &[4, 5, 6, 7, 8]);
        assert!(it.next().is_none());
    }

    #[test]
    fn section_iter_stops_after_a_malformed_section() {
        // Core audit IMP-03 follow-on. A malformed section cannot advance
        // `pos`, so an unfused iterator returns the same error on every call
        // and a caller that skips errors (`.filter_map(Result::ok)`, `.flatten()`)
        // never terminates. Each case must yield exactly one error, then end.
        let mut good = Vec::new();
        write_section(&mut good, *b"AAAA", 1, &[1, 2, 3]);

        // A header declaring a body of u32::MAX bytes -- the IMP-03 shape.
        let mut huge = good.clone();
        huge.extend_from_slice(b"BBBB");
        huge.push(1);
        huge.extend_from_slice(&u32::MAX.to_le_bytes());
        // A header cut short, under the 9-byte minimum.
        let mut short = good.clone();
        short.extend_from_slice(b"CCCC");

        for (name, blob) in [("huge length", &huge), ("short header", &short)] {
            let mut it = SectionIter::new(blob);
            assert!(it.next().unwrap().is_ok(), "{name}: the good section reads");
            assert!(it.next().unwrap().is_err(), "{name}: the bad one errors");
            assert!(it.next().is_none(), "{name}: and the iterator then ENDS");
            // The skip-errors caller terminates and sees only the good section.
            assert_eq!(SectionIter::new(blob).flatten().count(), 1, "{name}");
        }
    }

    #[test]
    fn section_iter_ends_at_an_all_zero_tail() {
        // v2.8.0 (libretro audit §2.2). A libretro frontend hands
        // `retro_unserialize` a buffer of `retro_serialize_size` bytes, and the
        // core reserves headroom there for expansion devices, so a state the
        // core wrote comes back followed by zeros. No section tag is ever
        // zero (every tag is four printable ASCII bytes), so a tail that is
        // zero from here to the end cannot be the start of a section: it is
        // padding, and the blob has ended.
        //
        // Before this, 1-8 zero bytes read as a truncated header (`Eof`), a
        // multiple of 9 read as empty sections named "\0\0\0\0", and any other
        // count errored after those -- so whether a padded state loaded
        // depended on the padding length mod 9.
        let mut good = Vec::new();
        write_section(&mut good, *b"AAAA", 1, &[1, 2, 3]);
        write_section(&mut good, *b"BBBB", 7, &[4, 5, 6, 7, 8]);
        for pad in 1..=64 {
            let mut padded = good.clone();
            padded.resize(good.len() + pad, 0);
            let sections: Vec<_> = SectionIter::new(&padded)
                .collect::<Result<_, _>>()
                .unwrap_or_else(|e| panic!("{pad} zero bytes of padding: {e:?}"));
            assert_eq!(
                sections.len(),
                2,
                "{pad} zero bytes: exactly the real sections"
            );
            assert_eq!(&sections[1].tag, b"BBBB");
        }
    }

    #[test]
    fn no_section_tag_contains_a_zero_byte() {
        // The invariant the all-zero-tail rule rests on. A tag with a zero byte
        // in it could, at the end of a blob, be mistaken for padding; pinned
        // here so a new tag cannot quietly break it.
        for t in [tag::CPU, tag::PPU, tag::APU, tag::MAP, tag::BUS, tag::THM] {
            assert!(
                t.iter().all(|b| b.is_ascii_graphic() || *b == b' '),
                "section tag {t:?} must be four printable ASCII bytes"
            );
        }
    }

    #[test]
    fn section_iter_rejects_zero_tagged_headers_in_one_step() {
        // Review on #556 (CodeRabbit). Nine zero bytes used to frame an empty
        // section with tag 00 00 00 00, which restore skips as unknown; with
        // the padding rule, a blob of many such headers ending in one non-zero
        // byte re-scanned the zero run once per header. A zero byte where a
        // tag starts is now rejected on the spot, so the iterator yields one
        // error and stops, however many headers follow.
        let mut blob = Vec::new();
        write_section(&mut blob, *b"AAAA", 1, &[1, 2, 3]);
        let real = blob.len();
        blob.resize(real + 9 * 10_000, 0);
        blob.push(0x5A);
        let items: Vec<_> = SectionIter::new(&blob).collect();
        assert_eq!(items.len(), 2, "the real section, then exactly one error");
        assert!(items[0].is_ok());
        match &items[1] {
            Err(SnapshotError::SectionInvalid { reason, .. }) => assert!(
                reason.contains(&format!("offset {real}")),
                "the error names where the zero tag starts: {reason}"
            ),
            other => panic!("expected SectionInvalid, got {other:?}"),
        }
        // A single zero-tagged header followed by a real section, which the
        // old iterator skipped past, is rejected the same way.
        let mut blob = vec![0_u8; 9];
        write_section(&mut blob, *b"AAAA", 1, &[1]);
        assert!(SectionIter::new(&blob).next().is_some_and(|r| r.is_err()));
    }

    #[test]
    fn section_iter_still_rejects_a_tail_that_is_not_all_zero() {
        // The other half: padding is recognised by being ENTIRELY zero, so a
        // tail with one non-zero byte, wherever it falls (first byte, last
        // byte, past a section-sized run of zeros), is still parsed as section
        // data. The iterator yields at least one item past the real section for
        // it -- an error, or, where the bytes happen to form a well-framed
        // header, an unknown-tag section that callers ignore, exactly as
        // before this change. What it must never do is end silently.
        let mut good = Vec::new();
        write_section(&mut good, *b"AAAA", 1, &[1, 2, 3]);
        for (len, at) in [(1, 0), (8, 7), (20, 0), (20, 19), (40, 25)] {
            let mut tail = good.clone();
            tail.resize(good.len() + len, 0);
            tail[good.len() + at] = 0x5A;
            assert!(
                SectionIter::new(&tail).count() > 1,
                "a {len}-byte tail with a non-zero byte at {at} must not read as padding"
            );
        }
        // And the short cases, which cannot frame a header, are errors.
        for (len, at) in [(1, 0), (8, 7), (8, 0)] {
            let mut tail = good.clone();
            tail.resize(good.len() + len, 0);
            tail[good.len() + at] = 0x5A;
            assert!(
                SectionIter::new(&tail).any(|s| s.is_err()),
                "a {len}-byte non-zero tail is a truncated header"
            );
        }
    }

    #[test]
    fn binwriter_round_trip() {
        let mut w = BinWriter::new();
        w.u8(0x12);
        w.u16(0x3456);
        w.u32(0x789A_BCDE);
        w.u64(0xFEED_FACE_CAFE_BEEF);
        w.bool(true);
        w.bool(false);
        w.bytes(&[0xAA, 0xBB]);
        let buf = w.into_vec();
        let mut r = BinReader::new(&buf);
        assert_eq!(r.u8().unwrap(), 0x12);
        assert_eq!(r.u16().unwrap(), 0x3456);
        assert_eq!(r.u32().unwrap(), 0x789A_BCDE);
        assert_eq!(r.u64().unwrap(), 0xFEED_FACE_CAFE_BEEF);
        assert!(r.bool().unwrap());
        assert!(!r.bool().unwrap());
        assert_eq!(r.take(2).unwrap(), &[0xAA, 0xBB]);
        assert!(r.is_empty());
    }

    #[test]
    fn binreader_eof_errors() {
        let buf = [0x12u8];
        let mut r = BinReader::new(&buf);
        assert!(r.u8().is_ok());
        assert!(matches!(r.u8(), Err(SnapshotError::Eof(_))));
    }
}