Luigit
repositories / smith

smith

There are many coding harnesses - but this one is fast

owned by admin

smith-core/src/frame.rs

Raw
//! Structurally traversed typed session frames (`SMH-SPEC-SPEC0001`, Sessions).
//!
//! File: `[SMH3, format=2, reserved=0: 8 bytes][frames...]`.
//! Format 2 requires atomic admission semantics; format-1 readers fail closed.
//! Frame, little endian: `[body_len u32][kind u16][version u16][header_crc u32]`
//! `[body_crc u32][payload][body_crc XOR 0x534d4833 u32]`.
//! `body_len` counts body CRC, payload, and completion marker (not the 12-byte
//! header). Header CRC-32 covers the first eight header bytes; body CRC-32
//! covers kind, version, and payload. Complete intact-boundary records with
//! damaged bodies are skipped by length; an untrustworthy header stops the
//! walk rather than scanning payload for marker-shaped bytes. Entries carry
//! 62 bytes of tightly packed fixed metadata followed by length-checked typed
//! content; format has no implicit padding, absent parent IDs are zero-filled.

use crate::session::{Entry, EntryFrame, EntryKind, SessionHeader};
use smith::error::{FrameFault, Result, SmithError};
use smith::id::{BranchId, EntryId, MessageId, SessionId, ToolCallId};
use smith::message::Role;
use std::io::{Read, Write};

mod commit;
mod nested;
mod payload;
pub(crate) use nested::validate as validate_nested_completion;
pub use payload::{NestedPayloadChunk, NestedPayloadPhase};
#[cfg(test)]
mod commit_tests;
pub use commit::ToolCompletionCheckpoint;
pub(crate) use commit::{member_offsets, validate as validate_completion};

/// Fixed file prologue, written once before the first framed record.
pub const FILE_PROLOGUE: [u8; 8] = *b"SMH3\x02\0\0\0";

/// Default frame size ceiling when no configuration is supplied.
pub const DEFAULT_MAX_FRAME_BYTES: usize = 1024 * 1024;
// Permit brief signal bursts; a reader that never progresses must fail closed.
const INTERRUPTED_READS_MAX: usize = 16;

/// Length of the independently checked frame header.
pub const HEADER_LEN: usize = 12;

/// Body checksum and completion marker bytes excluding payload.
pub const BODY_PREFIX_LEN: usize = 8;

/// Frame kind of a session entry payload.
pub const KIND_ENTRY: u16 = 1;

/// Supported version of the [`KIND_ENTRY`] payload schema.
/// Version 4 uses fixed metadata followed by typed binary content and
/// accompanies durable navigation records in the session protocol.
pub const VERSION_ENTRY: u16 = 4;

/// Frame kind of the session header payload.
pub const KIND_SESSION_HEADER: u16 = 2;

/// Supported version of the [`KIND_SESSION_HEADER`] payload schema.
pub const VERSION_SESSION_HEADER: u16 = 2;

/// An embedded, reconstructible entry-location hint.
pub const KIND_INDEX: u16 = 3;
/// Durable selection of a branch tip.
pub const KIND_SELECTION: u16 = 4;
/// Reconstructible selected-tip checkpoint kind.
pub const KIND_CHECKPOINT: u16 = 5;
/// Version of index, selection and checkpoint records.
pub const VERSION_NAV: u16 = 1;

/// Required atomic admission record: input, destination, FIFO placement and work identity.
pub const KIND_ADMISSION: u16 = 0x8001;
/// Required root-work claim and atomic settlement record.
pub const KIND_WORK: u16 = 0x8003;
/// Required atomic tool completion and root progress record.
pub const KIND_COMMIT: u16 = 0x8005;
/// Required atomic nested guest effect completion and root progress.
pub const KIND_NESTED_COMMIT: u16 = 0x8007;
/// Required same-ledger nested canonical payload chunk.
pub const KIND_NESTED_PAYLOAD: u16 = 0x8009;
/// Required source-attributed, read-only history scope boundary.
pub const KIND_ORIGIN: u16 = 0x800b;
/// Required atomic context-edit entry, typed content schema 2.
pub const KIND_CONTEXT_EDIT: u16 = 0x800d;
/// Prototype schema 2 adds identity-preserving tool-bearing replacements.
/// Schema 1 is intentionally unsupported; histories without edits are unchanged.
pub const VERSION_CONTEXT_EDIT: u16 = 2;
/// Required explicit causal intent, independent of chronological entry ancestry.
pub const KIND_CAUSAL_INTENT: u16 = 0x800f;
/// Admission wire schema version.
pub const VERSION_ADMISSION: u16 = 1;
/// Maximum caller deduplication key length in UTF-8 bytes.
pub const ADMISSION_KEY_BYTES_MAX: usize = 256;

/// A decoded session frame.
#[derive(Clone, PartialEq, Eq, Debug)]
pub enum Frame {
    /// Durable session identity; the first frame of a session file.
    Header {
        /// Decoded header.
        header: SessionHeader,
    },
    /// Source ledger scope; nested scopes preserve transitive fork provenance.
    Origin {
        /// Original session namespace, never adopted by the containing session.
        source: SessionId,
        /// True opens a source scope; false closes the matching scope.
        begin: bool,
    },
    /// A known session entry.
    Known {
        /// Decoded entry frame; its content stays typed binary bytes.
        entry: EntryFrame,
    },
    /// One atomic pending admission. Its entry identity is also its work identity;
    /// its parent fixes the destination, and physical commit order fixes FIFO placement.
    Admission {
        /// Admitted user message, already part of history.
        entry: EntryFrame,
        /// Session-scoped caller key, absent for an unkeyed submission.
        key: Option<String>,
    },
    /// Durable one-shot claim of admitted root work.
    Claim {
        /// Original admitted input identity.
        submission_id: EntryId,
    },
    /// Durable cooperative cancellation request, independent of terminal outcome.
    CancelIntent {
        /// Exact claimed root identity; never retargeted on recovery.
        submission_id: EntryId,
    },
    /// Atomic terminal outcome and optional assistant output.
    Settlement {
        /// Original admitted input identity.
        submission_id: EntryId,
        /// Successful stop, cancellation (`Abort`), or explicit failure (`None`).
        reason: Option<smith::stream::StopReason>,
        /// Final assistant message, never independently appended.
        output: Option<EntryFrame>,
    },
    /// One checksummed tool completion, mutation evidence, conversation result,
    /// and root-work checkpoint. Members never publish independently.
    Commit {
        /// Stable root and effect attribution.
        checkpoint: ToolCompletionCheckpoint,
        /// Ordered result, mutation evidence, and Tool-role conversation message.
        entries: Box<[EntryFrame; 3]>,
    },
    /// One nested completion whose typed identity is also its root checkpoint.
    NestedCommit {
        /// Bounded completion evidence; never published as an ordinary entry.
        entry: EntryFrame,
    },
    /// Immutable payload bytes, published only by a matching intent or completion reference.
    NestedPayload {
        /// Boxed frame-owned chunk keeps the existing small frame layout unchanged.
        chunk: Box<NestedPayloadChunk>,
    },
    /// Derived location hint; authoritative entry frames remain discoverable without it.
    Index {
        /// Entry identifier.
        id: EntryId,
        /// Absolute byte offset of its entry frame.
        offset: u64,
        /// Parent identity, independent of physical address.
        parent: Option<EntryId>,
        /// Absolute byte offset of its parent entry frame, if known.
        parent_offset: Option<u64>,
    },
    /// Append-only selection of an already recorded entry.
    Selection {
        /// Selected entry identifier.
        id: EntryId,
    },
    /// Reconstructible selected-tip location hint; never authoritative.
    Checkpoint {
        /// Selected entry identifier.
        id: EntryId,
        /// Its absolute entry-frame boundary.
        offset: u64,
    },
    /// A checksum-valid frame of a kind this build does not know.
    /// Kind, version, and payload are preserved so it round-trips unchanged.
    Unknown {
        /// Frame kind tag.
        kind: u16,
        /// Frame version tag.
        version: u16,
        /// Exact payload bytes as read.
        payload: Vec<u8>,
    },
}

impl Frame {
    pub(crate) fn requires_work_validation(&self) -> bool {
        if let Self::Known { entry } = self {
            return (matches!(entry.kind, EntryKind::Meta { .. })
                && nested::is_causal_intent(&entry.content))
                || (entry.content.first() == Some(&3)
                    && crate::content_codec::metadata_name(&entry.content)
                        .is_ok_and(|kind| kind.is_some_and(crate::metadata::lifecycle::reserved))
                    && matches!(crate::content_codec::EntryContentView::decode(&entry.content),
                    Ok(crate::content_codec::EntryContentView::Meta { kind, .. })
                        if crate::metadata::lifecycle::reserved(kind)));
        }
        matches!(
            self,
            Self::Origin { .. }
                | Self::Admission { .. }
                | Self::Claim { .. }
                | Self::CancelIntent { .. }
                | Self::Settlement { .. }
                | Self::Commit { .. }
                | Self::NestedCommit { .. }
                | Self::NestedPayload { .. }
        )
    }

    /// Ordered history members after validation of the complete enclosing frame.
    #[must_use]
    pub fn entries(&self) -> &[EntryFrame] {
        match self {
            Self::Known { entry }
            | Self::NestedCommit { entry }
            | Self::Admission { entry, .. }
            | Self::Settlement {
                output: Some(entry),
                ..
            } => std::slice::from_ref(entry),
            Self::Commit { entries, .. } => entries.as_slice(),
            _ => &[],
        }
    }

    pub(crate) fn positioned_entries(&self, at: u64) -> impl Iterator<Item = (u64, &EntryFrame)> {
        let offsets = match self {
            Self::Commit { entries, .. } => member_offsets(at, entries),
            Self::NestedCommit { .. } => [at + FRAME_PREFIX_LEN as u64; 3],
            _ => [at; 3],
        };
        offsets.into_iter().zip(self.entries())
    }

    /// Encode the full frame (length prefix, body prefix, payload) enforcing
    /// `max_frame_bytes` on the payload.
    ///
    /// # Errors
    ///
    /// Returns a [`FrameFault::TooLarge`] or [`FrameFault::Encode`] error.
    pub fn encode(&self, frame_bytes_max: usize) -> Result<Vec<u8>> {
        match self {
            Self::Header { header } => seal(
                KIND_SESSION_HEADER,
                VERSION_SESSION_HEADER,
                header_bytes(header),
                frame_bytes_max,
            ),
            Self::Origin { source, begin } => {
                let mut out = Vec::with_capacity(FRAME_PREFIX_LEN + 17 + 4);
                out.resize(FRAME_PREFIX_LEN, 0);
                out.extend_from_slice(&source.as_u128().to_le_bytes());
                out.push(u8::from(*begin));
                seal(KIND_ORIGIN, 1, out, frame_bytes_max)
            }
            Self::Known { entry } => encode_entry_fields(
                entry.id,
                entry.parent,
                entry.timestamp_ms,
                entry.kind,
                &entry.content,
                frame_bytes_max,
            ),
            Self::Admission { entry, key } => {
                encode_admission(entry, key.as_deref(), frame_bytes_max)
            }
            Self::CancelIntent { submission_id } => {
                let mut out = Vec::with_capacity(FRAME_PREFIX_LEN + 17 + 4);
                out.resize(FRAME_PREFIX_LEN, 0);
                out.extend_from_slice(&submission_id.as_u128().to_le_bytes());
                out.push(2);
                seal(KIND_WORK, 1, out, frame_bytes_max)
            }
            Self::Claim { submission_id } => {
                let mut out = Vec::with_capacity(FRAME_PREFIX_LEN + 17 + 4);
                out.resize(FRAME_PREFIX_LEN, 0);
                out.extend_from_slice(&submission_id.as_u128().to_le_bytes());
                out.push(0);
                seal(KIND_WORK, 1, out, frame_bytes_max)
            }
            Self::Settlement {
                submission_id,
                reason,
                output,
            } => encode_settlement(*submission_id, *reason, output.as_ref(), frame_bytes_max),
            Self::Commit {
                checkpoint,
                entries,
            } => commit::encode(checkpoint, entries, frame_bytes_max),
            Self::NestedCommit { entry } => nested::encode(entry, frame_bytes_max),
            Self::NestedPayload { chunk } => payload::encode(chunk, frame_bytes_max),
            Self::Index {
                id,
                offset,
                parent,
                parent_offset,
            } => {
                if frame_bytes_max < 48 {
                    return Err(too_large(frame_bytes_max, 48));
                }
                Ok(index_bytes(*id, *offset, *parent, *parent_offset).to_vec())
            }
            Self::Selection { id } => {
                let mut out = Vec::with_capacity(FRAME_PREFIX_LEN + 16 + 4);
                out.resize(FRAME_PREFIX_LEN, 0);
                out.extend_from_slice(&id.as_u128().to_le_bytes());
                seal(KIND_SELECTION, VERSION_NAV, out, frame_bytes_max)
            }
            Self::Checkpoint { id, offset } => {
                let mut out = Vec::with_capacity(FRAME_PREFIX_LEN + 24 + 4);
                out.resize(FRAME_PREFIX_LEN, 0);
                out.extend_from_slice(&id.as_u128().to_le_bytes());
                out.extend_from_slice(&offset.to_le_bytes());
                seal(KIND_CHECKPOINT, VERSION_NAV, out, frame_bytes_max)
            }
            Self::Unknown {
                kind,
                version,
                payload,
            } => {
                if payload.len() > frame_bytes_max {
                    return Err(too_large(frame_bytes_max, payload.len()));
                }
                let mut out = Vec::with_capacity(FRAME_PREFIX_LEN + payload.len() + 4);
                out.resize(FRAME_PREFIX_LEN, 0);
                out.extend_from_slice(payload);
                seal(*kind, *version, out, frame_bytes_max)
            }
        }
    }
}

fn encode_admission(
    entry: &EntryFrame,
    key: Option<&str>,
    frame_bytes_max: usize,
) -> Result<Vec<u8>> {
    let key_bytes = key.map(str::as_bytes);
    if key_bytes.is_some_and(|bytes| bytes.is_empty() || bytes.len() > ADMISSION_KEY_BYTES_MAX) {
        return Err(fault(schema(
            "admission key must contain 1..=256 UTF-8 bytes",
        )));
    }
    let entry_length = entry_payload_length(&entry.content, frame_bytes_max)?;
    let key_length = key_bytes.map_or(0, <[u8]>::len);
    let payload_length = entry_length
        .checked_add(2)
        .and_then(|length| length.checked_add(key_length))
        .ok_or_else(|| too_large(frame_bytes_max, usize::MAX))?;
    if payload_length > frame_bytes_max {
        return Err(too_large(frame_bytes_max, payload_length));
    }
    let mut out = Vec::with_capacity(FRAME_PREFIX_LEN + payload_length);
    out.resize(FRAME_PREFIX_LEN, 0);
    append_entry_payload(
        &mut out,
        entry.id,
        entry.parent,
        entry.timestamp_ms,
        entry.kind,
        &entry.content,
        frame_bytes_max,
    )?;
    let length =
        u16::try_from(key_length).map_err(|_| fault(schema("admission key length overflow")))?;
    out.extend_from_slice(&length.to_le_bytes());
    if let Some(bytes) = key_bytes {
        out.extend_from_slice(bytes);
    }
    seal(KIND_ADMISSION, VERSION_ADMISSION, out, frame_bytes_max)
}

fn encode_settlement(
    submission_id: EntryId,
    reason: Option<smith::stream::StopReason>,
    output: Option<&EntryFrame>,
    frame_bytes_max: usize,
) -> Result<Vec<u8>> {
    if let Some(entry) = output {
        validate_work_message(entry, Role::Assistant, usize::MAX)?;
    }
    let output_length = output.map_or(Ok(0), |entry| {
        entry_payload_length(&entry.content, frame_bytes_max)
    })?;
    let length = 18usize
        .checked_add(output_length)
        .ok_or_else(|| too_large(frame_bytes_max, usize::MAX))?;
    if length > frame_bytes_max {
        return Err(too_large(frame_bytes_max, length));
    }
    let tag = terminal_tag(reason)?;
    let mut out = Vec::with_capacity(FRAME_PREFIX_LEN + length + 4);
    out.resize(FRAME_PREFIX_LEN, 0);
    out.extend_from_slice(&submission_id.as_u128().to_le_bytes());
    out.push(1);
    out.push(tag);
    if let Some(entry) = output {
        append_entry_payload(
            &mut out,
            entry.id,
            entry.parent,
            entry.timestamp_ms,
            entry.kind,
            &entry.content,
            frame_bytes_max,
        )?;
    }
    seal(KIND_WORK, 1, out, frame_bytes_max)
}

pub(crate) fn validate_work_message(
    entry: &EntryFrame,
    role: Role,
    blocks_max: usize,
) -> Result<()> {
    use crate::content_codec::{BlockView, EntryContentView};
    let content = EntryContentView::decode(&entry.content)?;
    if content.kind() != entry.kind
        || !matches!(content, EntryContentView::Message(ref message) if message.role == role && message.blocks().len() <= blocks_max && message.blocks().all(|block| matches!(block, BlockView::Text(_))))
    {
        return Err(fault(schema(
            "work entry requires coherent text message with expected role and block bound",
        )));
    }
    Ok(())
}

fn terminal_tag(reason: Option<smith::stream::StopReason>) -> Result<u8> {
    use smith::stream::StopReason;
    match reason {
        None => Ok(0),
        Some(StopReason::EndTurn) => Ok(1),
        Some(StopReason::Limit) => Ok(2),
        Some(StopReason::Abort) => Ok(3),
        Some(StopReason::StopSequence) => Ok(4),
        Some(StopReason::Refusal) => Ok(5),
        Some(StopReason::ContentFilter) => Ok(6),
        Some(StopReason::ToolUse) => Err(fault(schema("tool-use is not terminal root work"))),
    }
}

/// Encode one fixed-width location hint without allocating.
#[must_use]
pub fn index_bytes(
    id: EntryId,
    offset: u64,
    parent: Option<EntryId>,
    parent_offset: Option<u64>,
) -> [u8; 68] {
    let mut out = [0u8; 68];
    out[4..6].copy_from_slice(&KIND_INDEX.to_le_bytes());
    out[6..8].copy_from_slice(&VERSION_NAV.to_le_bytes());
    out[16..32].copy_from_slice(&id.as_u128().to_le_bytes());
    out[32..40].copy_from_slice(&offset.to_le_bytes());
    out[40..56].copy_from_slice(&parent.map_or(0, |id| id.as_u128()).to_le_bytes());
    out[56..64].copy_from_slice(&parent_offset.unwrap_or(0).to_le_bytes());
    out[..4].copy_from_slice(&56_u32.to_le_bytes());
    let header_crc = crc32fast::hash(&out[..8]);
    out[8..12].copy_from_slice(&header_crc.to_le_bytes());
    let checksum = crc32(KIND_INDEX, VERSION_NAV, &out[16..64]);
    out[12..16].copy_from_slice(&checksum.to_le_bytes());
    out[64..68].copy_from_slice(&(checksum ^ COMPLETION).to_le_bytes());
    out
}

/// Encode a session record and its arena content bytes as a full entry
/// frame, without copying the content out of the arena first.
///
/// # Errors
///
/// Returns a [`FrameFault::TooLarge`] or [`FrameFault::Encode`] error.
pub fn encode_entry(entry: &Entry, content: &[u8], frame_bytes_max: usize) -> Result<Vec<u8>> {
    encode_entry_fields(
        entry.id,
        entry.parent,
        entry.timestamp_ms,
        entry.kind,
        content,
        frame_bytes_max,
    )
}

/// Bytes before a frame payload: length prefix, kind, version, checksum.
const FRAME_PREFIX_LEN: usize = HEADER_LEN + 4;

/// Fixed-size entry metadata is independent of the variable content span.
const ENTRY_METADATA_LEN: usize = 16 + 16 + 8 + 1 + 16 + 1 + 4;
const _: () = assert!(HEADER_LEN == 12, "frame header wire width changed");
const _: () = assert!(FRAME_PREFIX_LEN == 16, "frame prefix wire width changed");
const _: () = assert!(
    ENTRY_METADATA_LEN == 62,
    "entry metadata wire width changed"
);

fn header_bytes(header: &SessionHeader) -> Vec<u8> {
    let mut bytes = Vec::with_capacity(FRAME_PREFIX_LEN + 32 + 4);
    bytes.resize(FRAME_PREFIX_LEN, 0);
    bytes.extend_from_slice(&header.session_id.as_u128().to_le_bytes());
    bytes.extend_from_slice(&header.branch_id.as_u128().to_le_bytes());
    bytes
}

#[expect(
    clippy::large_types_passed_by_value,
    reason = "EntryKind is a compact Copy wire tag passed once to the encoder"
)]
fn encode_entry_fields(
    id: EntryId,
    parent: Option<EntryId>,
    timestamp_ms: i64,
    kind: EntryKind,
    content: &[u8],
    frame_bytes_max: usize,
) -> Result<Vec<u8>> {
    let payload_length = entry_payload_length(content, frame_bytes_max)?;
    let mut bytes = Vec::with_capacity(FRAME_PREFIX_LEN + payload_length);
    bytes.resize(FRAME_PREFIX_LEN, 0);
    append_entry_payload(
        &mut bytes,
        id,
        parent,
        timestamp_ms,
        kind,
        content,
        frame_bytes_max,
    )?;
    if !matches!(kind, EntryKind::Meta { .. }) {
        return seal(KIND_ENTRY, VERSION_ENTRY, bytes, frame_bytes_max);
    }
    if nested::is_causal_intent(content) {
        seal(KIND_CAUSAL_INTENT, 1, bytes, frame_bytes_max)
    } else if is_context_edit(&kind, content) {
        seal(
            KIND_CONTEXT_EDIT,
            VERSION_CONTEXT_EDIT,
            bytes,
            frame_bytes_max,
        )
    } else {
        seal(KIND_ENTRY, VERSION_ENTRY, bytes, frame_bytes_max)
    }
}

fn is_context_edit(kind: &EntryKind, content: &[u8]) -> bool {
    *kind == (EntryKind::Meta { compaction: false })
        && content.first() == Some(&4)
        && crate::content_codec::EntryContentView::decode(content).is_ok()
}

pub(crate) fn validate_entry_size(content: &[u8], frame_bytes_max: usize) -> Result<()> {
    let payload_length = entry_payload_length(content, frame_bytes_max)?;
    u32::try_from(content.len()).map_err(|_| too_large(frame_bytes_max, payload_length))?;
    Ok(())
}

fn entry_payload_length(content: &[u8], frame_bytes_max: usize) -> Result<usize> {
    let payload_length = ENTRY_METADATA_LEN
        .checked_add(content.len())
        .ok_or_else(|| too_large(frame_bytes_max, usize::MAX))?;
    if payload_length > frame_bytes_max {
        return Err(too_large(frame_bytes_max, payload_length));
    }
    Ok(payload_length)
}

#[expect(
    clippy::large_types_passed_by_value,
    reason = "EntryKind is a compact Copy wire tag passed once to the encoder"
)]
fn append_entry_payload(
    bytes: &mut Vec<u8>,
    id: EntryId,
    parent: Option<EntryId>,
    timestamp_ms: i64,
    kind: EntryKind,
    content: &[u8],
    frame_bytes_max: usize,
) -> Result<()> {
    if content.first() == Some(&4)
        && let Ok(view) = crate::content_codec::EntryContentView::decode(content)
        && view.kind() != kind
    {
        return Err(crate::context::invalid(
            "context edit metadata disagrees with content",
        ));
    }
    let payload_length = entry_payload_length(content, frame_bytes_max)?;
    let length =
        u32::try_from(content.len()).map_err(|_| too_large(frame_bytes_max, payload_length))?;
    bytes.extend_from_slice(&id.as_u128().to_le_bytes());
    bytes.extend_from_slice(&parent.map_or(0, |parent| parent.as_u128()).to_le_bytes());
    bytes.extend_from_slice(&timestamp_ms.to_le_bytes());
    let (tag, bits, flag) = match kind {
        EntryKind::Message { id, role } => (
            0,
            id.as_u128(),
            match role {
                Role::User => 0,
                Role::Assistant => 1,
                Role::System => 2,
                Role::Tool => 3,
            },
        ),
        EntryKind::ToolCall { call_id } => (1, call_id.as_u128(), 0),
        EntryKind::ToolResult { call_id, ok } => (2, call_id.as_u128(), u8::from(ok)),
        EntryKind::Meta { compaction } => (3, 0, u8::from(compaction)),
    };
    bytes.push(tag);
    bytes.extend_from_slice(&bits.to_le_bytes());
    bytes.push(flag);
    bytes.extend_from_slice(&length.to_le_bytes());
    bytes.extend_from_slice(content);
    Ok(())
}

fn decode_header(payload: &[u8]) -> std::result::Result<SessionHeader, FrameFault> {
    let bytes: [u8; 32] = payload
        .try_into()
        .map_err(|_| schema("invalid session header length"))?;
    Ok(SessionHeader {
        session_id: SessionId::from_u128(u128::from_le_bytes(
            bytes[..16]
                .try_into()
                .map_err(|_| schema("invalid session id"))?,
        )),
        branch_id: BranchId::from_u128(u128::from_le_bytes(
            bytes[16..]
                .try_into()
                .map_err(|_| schema("invalid branch id"))?,
        )),
    })
}

fn schema(message: &str) -> FrameFault {
    FrameFault::SchemaDecode {
        message: message.into(),
    }
}

#[expect(
    clippy::expect_used,
    reason = "fixed metadata width checked before slicing"
)]
fn decode_entry(payload: &[u8]) -> std::result::Result<EntryFrame, FrameFault> {
    let metadata = payload
        .get(..ENTRY_METADATA_LEN)
        .ok_or_else(|| schema("short entry metadata"))?;
    let bits = |slice: std::ops::Range<usize>| -> u128 {
        u128::from_le_bytes(metadata[slice].try_into().expect("fixed metadata width"))
    };
    let id = EntryId::from_u128(bits(0..16));
    let parent = match bits(16..32) {
        0 => None,
        bits => Some(EntryId::from_u128(bits)),
    };
    let timestamp_ms =
        i64::from_le_bytes(metadata[32..40].try_into().expect("fixed timestamp width"));
    let flag = metadata[57];
    let bool_flag = || match flag {
        0 => Ok(false),
        1 => Ok(true),
        _ => Err(schema("invalid metadata boolean")),
    };
    let kind = match metadata[40] {
        0 => EntryKind::Message {
            id: MessageId::from_u128(bits(41..57)),
            role: match flag {
                0 => Role::User,
                1 => Role::Assistant,
                2 => Role::System,
                3 => Role::Tool,
                _ => return Err(schema("invalid role")),
            },
        },
        1 if flag == 0 => EntryKind::ToolCall {
            call_id: ToolCallId::from_u128(bits(41..57)),
        },
        2 => EntryKind::ToolResult {
            call_id: ToolCallId::from_u128(bits(41..57)),
            ok: bool_flag()?,
        },
        3 if bits(41..57) == 0 => EntryKind::Meta {
            compaction: bool_flag()?,
        },
        _ => return Err(schema("invalid entry kind metadata")),
    };
    let content_len =
        u32::from_le_bytes(metadata[58..62].try_into().expect("fixed length width")) as usize;
    let content = payload
        .get(ENTRY_METADATA_LEN..)
        .ok_or_else(|| schema("missing content"))?;
    if content.len() != content_len {
        return Err(schema("entry content length mismatch"));
    }
    Ok(EntryFrame {
        id,
        parent,
        timestamp_ms,
        kind,
        content: content.to_vec(),
    })
}

/// Fill the reserved prefix of `out` (length, kind, version, checksum) for
/// the payload that follows it.
fn seal(kind: u16, version: u16, mut out: Vec<u8>, frame_bytes_max: usize) -> Result<Vec<u8>> {
    assert!(
        out.len() >= FRAME_PREFIX_LEN,
        "encoder must reserve the complete frame prefix before sealing"
    );
    let payload_len = out.len() - FRAME_PREFIX_LEN;
    if payload_len > frame_bytes_max {
        return Err(too_large(frame_bytes_max, payload_len));
    }
    let Ok(declared) = u32::try_from(BODY_PREFIX_LEN + payload_len) else {
        return Err(too_large(frame_bytes_max, payload_len));
    };
    let checksum = crc32(kind, version, &out[FRAME_PREFIX_LEN..]);
    out[..4].copy_from_slice(&declared.to_le_bytes());
    out[4..6].copy_from_slice(&kind.to_le_bytes());
    out[6..8].copy_from_slice(&version.to_le_bytes());
    let header_checksum = crc32fast::hash(&out[..8]);
    out[8..HEADER_LEN].copy_from_slice(&header_checksum.to_le_bytes());
    out[HEADER_LEN..FRAME_PREFIX_LEN].copy_from_slice(&checksum.to_le_bytes());
    out.extend_from_slice(&(checksum ^ COMPLETION).to_le_bytes());
    Ok(out)
}

/// Classify one frame body: verify the checksum first, then the kind and
/// version, then the payload schema.
const COMPLETION: u32 = 0x53_4d_48_33;

fn decode_ordinary_entry(payload: &[u8]) -> std::result::Result<Frame, FrameFault> {
    let entry = decode_entry(payload)?;
    if matches!(entry.kind, EntryKind::Meta { .. })
        && (is_context_edit(&entry.kind, &entry.content)
            || nested::is_causal_intent(&entry.content))
    {
        return Err(schema(
            "typed semantic entry requires required frame envelope",
        ));
    }
    Ok(Frame::Known { entry })
}

fn decode_body(kind: u16, version: u16, body: &[u8]) -> std::result::Result<Frame, FrameFault> {
    if body.len() < BODY_PREFIX_LEN {
        return Err(FrameFault::Malformed {
            declared_length: body.len(),
        });
    }
    let checksum = u32::from_le_bytes(
        body[..4]
            .try_into()
            .map_err(|_| schema("missing body checksum"))?,
    );
    let end = body.len() - 4;
    let published = u32::from_le_bytes(
        body[end..]
            .try_into()
            .map_err(|_| schema("missing completion"))?,
    );
    let payload = &body[4..end];
    if published != checksum ^ COMPLETION || checksum != crc32(kind, version, payload) {
        return Err(FrameFault::Checksum {
            declared_length: body.len(),
        });
    }
    match (kind, version) {
        (KIND_ENTRY, VERSION_ENTRY) => decode_ordinary_entry(payload),
        (KIND_CAUSAL_INTENT, 1) => nested::decode_intent(payload),
        (KIND_CONTEXT_EDIT, VERSION_CONTEXT_EDIT) => decode_context_edit(payload),
        (KIND_ADMISSION, VERSION_ADMISSION) => decode_admission(payload),
        (KIND_ORIGIN, 1) => {
            if payload.len() != 17 || payload[16] > 1 {
                return Err(schema("invalid origin scope boundary"));
            }
            Ok(Frame::Origin {
                source: SessionId::from_u128(u128::from_le_bytes(
                    payload[..16]
                        .try_into()
                        .map_err(|_| schema("origin identity"))?,
                )),
                begin: payload[16] == 1,
            })
        }
        (KIND_WORK, 1) => decode_work(payload),
        (KIND_COMMIT, 1) => commit::decode(payload),
        (KIND_NESTED_COMMIT, 1 | 2) => nested::decode(payload, version),
        (KIND_NESTED_PAYLOAD, 1) => self::payload::decode(payload),
        (kind, _) if kind & 0x8000 != 0 => Err(schema("unsupported required frame semantics")),
        (KIND_SESSION_HEADER, VERSION_SESSION_HEADER) => {
            decode_header(payload).map(|header| Frame::Header { header })
        }
        (KIND_INDEX, VERSION_NAV) if payload.len() == 48 => {
            let bits = |range: std::ops::Range<usize>| -> u128 {
                // Fixed width is checked by the payload length guard.
                u128::from_le_bytes(payload[range].try_into().unwrap_or([0; 16]))
            };
            let word = |range: std::ops::Range<usize>| -> u64 {
                u64::from_le_bytes(payload[range].try_into().unwrap_or([0; 8]))
            };
            let parent = bits(24..40);
            let parent_offset = word(40..48);
            if (parent == 0) != (parent_offset == 0) {
                return Err(schema("index parent address mismatch"));
            }
            Ok(Frame::Index {
                id: EntryId::from_u128(bits(0..16)),
                offset: word(16..24),
                parent: (parent != 0).then(|| EntryId::from_u128(parent)),
                parent_offset: (parent_offset != 0).then_some(parent_offset),
            })
        }
        (KIND_SELECTION, VERSION_NAV) if payload.len() == 16 => Ok(Frame::Selection {
            id: EntryId::from_u128(u128::from_le_bytes(
                payload.try_into().map_err(|_| schema("selection length"))?,
            )),
        }),
        (KIND_CHECKPOINT, VERSION_NAV) if payload.len() == 24 => Ok(Frame::Checkpoint {
            id: EntryId::from_u128(u128::from_le_bytes(
                payload[..16]
                    .try_into()
                    .map_err(|_| schema("checkpoint id"))?,
            )),
            offset: u64::from_le_bytes(
                payload[16..]
                    .try_into()
                    .map_err(|_| schema("checkpoint offset"))?,
            ),
        }),
        (KIND_INDEX | KIND_SELECTION | KIND_CHECKPOINT, VERSION_NAV) => {
            Err(schema("navigation length"))
        }
        _ => Ok(Frame::Unknown {
            kind,
            version,
            payload: payload.to_vec(),
        }),
    }
}

fn decode_context_edit(payload: &[u8]) -> std::result::Result<Frame, FrameFault> {
    let entry = decode_entry(payload)?;
    if !is_context_edit(&entry.kind, &entry.content) {
        return Err(schema("invalid required context edit"));
    }
    Ok(Frame::Known { entry })
}

fn validate_required_schema(kind: u16, version: u16) -> Result<()> {
    if kind & 0x8000 != 0
        && !matches!(
            (kind, version),
            (KIND_ADMISSION, VERSION_ADMISSION)
                | (KIND_CONTEXT_EDIT, VERSION_CONTEXT_EDIT)
                | (KIND_NESTED_COMMIT, 2)
                | (
                    KIND_WORK
                        | KIND_CAUSAL_INTENT
                        | KIND_COMMIT
                        | KIND_NESTED_COMMIT
                        | KIND_NESTED_PAYLOAD
                        | KIND_ORIGIN,
                    1
                )
        )
    {
        return Err(fault(schema(
            "unsupported required frame semantics; use a compatible Smith build",
        )));
    }
    Ok(())
}

fn decode_work(payload: &[u8]) -> std::result::Result<Frame, FrameFault> {
    use smith::stream::StopReason;
    let submission_id = EntryId::from_u128(u128::from_le_bytes(
        payload
            .get(..16)
            .ok_or_else(|| schema("short work identity"))?
            .try_into()
            .map_err(|_| schema("work identity"))?,
    ));
    match payload.get(16) {
        Some(0) if payload.len() == 17 => Ok(Frame::Claim { submission_id }),
        Some(2) if payload.len() == 17 => Ok(Frame::CancelIntent { submission_id }),
        Some(1) if payload.len() >= 18 => {
            let reason = match payload[17] {
                0 => None,
                1 => Some(StopReason::EndTurn),
                2 => Some(StopReason::Limit),
                3 => Some(StopReason::Abort),
                4 => Some(StopReason::StopSequence),
                5 => Some(StopReason::Refusal),
                6 => Some(StopReason::ContentFilter),
                _ => return Err(schema("unknown terminal outcome")),
            };
            let output = if payload.len() == 18 {
                None
            } else {
                let entry = decode_entry(&payload[18..])?;
                validate_work_message(&entry, Role::Assistant, usize::MAX)
                    .map_err(|_| schema("invalid terminal output"))?;
                Some(entry)
            };
            Ok(Frame::Settlement {
                submission_id,
                reason,
                output,
            })
        }
        _ => Err(schema("invalid work transition")),
    }
}

fn decode_admission(payload: &[u8]) -> std::result::Result<Frame, FrameFault> {
    let length = payload
        .get(58..62)
        .ok_or_else(|| schema("short admission metadata"))?;
    let content_length = u32::from_le_bytes(
        length
            .try_into()
            .map_err(|_| schema("admission content length"))?,
    ) as usize;
    let entry_end = ENTRY_METADATA_LEN
        .checked_add(content_length)
        .ok_or_else(|| schema("admission length overflow"))?;
    let key_length = payload
        .get(entry_end..entry_end + 2)
        .ok_or_else(|| schema("short admission key length"))?;
    let key_length = u16::from_le_bytes(
        key_length
            .try_into()
            .map_err(|_| schema("admission key length"))?,
    ) as usize;
    if key_length > ADMISSION_KEY_BYTES_MAX || payload.len() != entry_end + 2 + key_length {
        return Err(schema("admission key length mismatch"));
    }
    let entry = decode_entry(&payload[..entry_end])?;
    validate_work_message(&entry, Role::User, crate::store::ADMISSION_TEXT_BLOCKS_MAX)
        .map_err(|_| schema("admission requires coherent user text"))?;
    let key = if key_length == 0 {
        None
    } else {
        Some(
            std::str::from_utf8(&payload[entry_end + 2..])
                .map_err(|_| schema("admission key is not UTF-8"))?
                .to_owned(),
        )
    };
    Ok(Frame::Admission { entry, key })
}

/// Frames recovered from a frame stream, plus explicit damage.
///
/// Damage never discards the surrounding frames: a corrupt frame is reported
/// and skipped by its declared length, and the frames after it stay readable.
#[derive(Clone, PartialEq, Eq, Debug, Default)]
pub struct Recovery {
    /// Frames recovered in stream order.
    pub frames: Vec<Frame>,
    /// Damage reports, each locating its frame header by byte offset.
    /// Bounded repair and reporting scans retain at most their first report.
    pub damage: Vec<SmithError>,
    /// Total complete damaged frames observed, including reports not retained.
    pub damage_count: u64,
    /// Offset just past the last complete frame.
    pub good_end: u64,
    /// Offset where an incomplete trailing frame starts, if any.
    pub torn_tail_at: Option<u64>,
}

/// Read every complete frame from `reader` with per-frame bounded allocation.
///
/// A torn tail ends the walk and is reported through
/// [`Recovery::torn_tail_at`]; complete frames before it are always returned.
///
/// # Errors
/// Returns `FRAME_READ` when the reader fails for a reason other than EOF.
pub fn read_frames<R: Read>(reader: &mut R, frame_bytes_max: usize) -> Result<Recovery> {
    let mut frames = Vec::new();
    let mut recovery = visit_frames(reader, frame_bytes_max, |frame| {
        frames.push(frame);
        true
    })?;
    recovery.frames = frames;
    Ok(recovery)
}

/// Walk complete frames with one bounded buffer, without retaining earlier frames.
///
/// Returning `false` from `visit` ends the walk at the last complete boundary.
/// Damage and incomplete tails are reported separately from the visited records.
/// Read failures other than EOF return explicitly, never as torn tails.
///
/// # Errors
/// Returns `FRAME_READ` when the reader fails for a reason other than EOF.
pub fn visit_frames<R: Read>(
    reader: &mut R,
    frame_bytes_max: usize,
    visit: impl FnMut(Frame) -> bool,
) -> Result<Recovery> {
    let mut damage = Vec::new();
    let mut recovery = visit_frames_reporting(reader, frame_bytes_max, visit, |fault| {
        damage.push(fault);
        true
    })?;
    recovery.damage = damage;
    Ok(recovery)
}

/// Walk frames while reporting damage immediately instead of retaining it.
///
/// Returning `false` from either callback ends the walk at the last complete
/// boundary. The returned recovery never retains damage, so streaming callers
/// can fail or emit each fault with bounded memory.
///
/// # Errors
/// Returns `FRAME_READ` when the reader fails for a reason other than EOF.
pub fn visit_frames_reporting<R: Read>(
    reader: &mut R,
    frame_bytes_max: usize,
    mut visit: impl FnMut(Frame) -> bool,
    mut report_damage: impl FnMut(SmithError) -> bool,
) -> Result<Recovery> {
    let mut recovery = Recovery::default();
    let declared_limit = frame_bytes_max.saturating_add(BODY_PREFIX_LEN);
    loop {
        let offset = recovery.good_end;
        let mut header = [0u8; HEADER_LEN];
        match read_exact_or_eof(reader, &mut header) {
            Ok(true) => {}
            Ok(false) => break,
            Err(error) if error.kind() == std::io::ErrorKind::UnexpectedEof => {
                recovery.torn_tail_at = Some(offset);
                break;
            }
            Err(error) => return Err(read_error(&error)),
        }
        let header_crc =
            u32::from_le_bytes(header[8..12].try_into().map_err(|_| boundary(offset))?);
        if header_crc != crc32fast::hash(&header[..8]) {
            return Err(boundary(offset));
        }
        let declared =
            u32::from_le_bytes(header[..4].try_into().map_err(|_| boundary(offset))?) as usize;
        let kind = u16::from_le_bytes(header[4..6].try_into().map_err(|_| boundary(offset))?);
        let version = u16::from_le_bytes(header[6..8].try_into().map_err(|_| boundary(offset))?);
        validate_required_schema(kind, version)?;
        let total = HEADER_LEN as u64 + declared as u64;
        if declared > declared_limit {
            if matches!(
                kind,
                KIND_COMMIT
                    | KIND_NESTED_COMMIT
                    | KIND_NESTED_PAYLOAD
                    | KIND_ORIGIN
                    | KIND_CONTEXT_EDIT
                    | KIND_CAUSAL_INTENT
            ) {
                return Err(too_large(
                    frame_bytes_max,
                    declared.saturating_sub(BODY_PREFIX_LEN),
                ));
            }
            match skip_exact(reader, declared) {
                Ok(true) => {}
                Ok(false) => {
                    recovery.torn_tail_at = Some(offset);
                    break;
                }
                Err(error) => return Err(read_error(&error)),
            }
            recovery.good_end = offset + total;
            recovery.damage_count += 1;
            if !report_damage(located(
                FrameFault::TooLarge {
                    bytes_max: frame_bytes_max,
                    actual: declared.saturating_sub(BODY_PREFIX_LEN),
                },
                offset,
            )) {
                break;
            }
            continue;
        }
        let mut body = vec![0u8; declared];
        match reader.read_exact(&mut body) {
            Ok(()) => {}
            Err(error) if error.kind() == std::io::ErrorKind::UnexpectedEof => {
                recovery.torn_tail_at = Some(offset);
                break;
            }
            Err(error) => return Err(read_error(&error)),
        }
        let decoded = decode_body(kind, version, &body);
        recovery.good_end = offset + total;
        match decoded {
            Ok(frame) => {
                if !visit(frame) {
                    break;
                }
            }
            Err(f) => {
                if kind & 0x8000 != 0 {
                    return Err(located(f, offset));
                }
                recovery.damage_count += 1;
                if !report_damage(located(f, offset)) {
                    break;
                }
            }
        }
    }
    Ok(recovery)
}

/// Visit boundaries and fixed metadata with bounded checksum chunks.
///
/// Known frames carry empty content; read validated offsets for payloads.
///
/// # Errors
/// Returns an I/O or boundary error; damaged complete frames are reported.
pub fn visit_metadata_reporting(
    reader: &mut impl Read,
    max: usize,
    mut visit: impl FnMut(u64, Frame) -> Result<()>,
    mut damage: impl FnMut(SmithError) -> Result<()>,
) -> Result<Recovery> {
    let mut recovery = Recovery::default();
    loop {
        let at = recovery.good_end;
        let mut header = [0; HEADER_LEN];
        match read_exact_or_eof(reader, &mut header) {
            Ok(true) => {}
            Ok(false) => break,
            Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => {
                recovery.torn_tail_at = Some(at);
                break;
            }
            Err(e) => return Err(read_error(&e)),
        }
        if crc32fast::hash(&header[..8])
            != u32::from_le_bytes(header[8..12].try_into().map_err(|_| boundary(at))?)
        {
            return Err(boundary(at));
        }
        let len = u32::from_le_bytes(header[..4].try_into().map_err(|_| boundary(at))?) as usize;
        let kind = u16::from_le_bytes(header[4..6].try_into().map_err(|_| boundary(at))?);
        let version = u16::from_le_bytes(header[6..8].try_into().map_err(|_| boundary(at))?);
        validate_required_schema(kind, version)?;
        if len < BODY_PREFIX_LEN || len > max.saturating_add(BODY_PREFIX_LEN) {
            if kind & 0x8000 != 0 {
                return Err(too_large(max, len.saturating_sub(BODY_PREFIX_LEN)));
            }
            let skipped = std::io::copy(&mut reader.take(len as u64), &mut std::io::sink())
                .map_err(|e| read_error(&e))?;
            if skipped != len as u64 {
                recovery.torn_tail_at = Some(at);
                break;
            }
            recovery.good_end += HEADER_LEN as u64 + len as u64;
            metadata_fault(
                &mut recovery,
                &mut damage,
                FrameFault::TooLarge {
                    bytes_max: max,
                    actual: len.saturating_sub(BODY_PREFIX_LEN),
                },
                at,
            )?;
            continue;
        }
        if kind & 0x8000 != 0 {
            if !visit_required_metadata(
                reader,
                &MetadataFrame {
                    at,
                    len,
                    kind,
                    version,
                },
                &mut recovery,
                &mut visit,
            )? {
                break;
            }
            continue;
        }
        if !visit_optional_metadata(
            reader,
            &MetadataFrame {
                at,
                len,
                kind,
                version,
            },
            &mut recovery,
            &mut visit,
            &mut damage,
        )? {
            break;
        }
    }
    Ok(recovery)
}

#[derive(Clone, Copy)]
struct MetadataFrame {
    at: u64,
    len: usize,
    kind: u16,
    version: u16,
}

fn visit_required_metadata(
    reader: &mut impl Read,
    frame: &MetadataFrame,
    recovery: &mut Recovery,
    visit: &mut impl FnMut(u64, Frame) -> Result<()>,
) -> Result<bool> {
    let mut body = vec![0; frame.len];
    if !read_part(reader, &mut body, recovery)? {
        return Ok(false);
    }
    recovery.good_end += HEADER_LEN as u64 + frame.len as u64;
    match decode_body(frame.kind, frame.version, &body) {
        Ok(Frame::Known { mut entry }) => {
            // Causal intent itself requires work validation, even in an otherwise
            // forged admission-free history. Clearing preserves buffer capacity,
            // so retaining its bounded validated view adds no allocation.
            if !matches!(entry.kind, EntryKind::Meta { .. })
                || !nested::is_causal_intent(&entry.content)
            {
                entry.content.clear();
            }
            visit(frame.at, Frame::Known { entry })?;
        }
        Ok(Frame::Admission { mut entry, .. }) => {
            entry.content.clear();
            visit(frame.at, Frame::Admission { entry, key: None })?;
        }
        Ok(Frame::Settlement {
            submission_id,
            reason,
            output: Some(mut entry),
        }) => {
            entry.content.clear();
            visit(
                frame.at,
                Frame::Settlement {
                    submission_id,
                    reason,
                    output: Some(entry),
                },
            )?;
        }
        Ok(settlement @ Frame::Settlement { output: None, .. }) => visit(frame.at, settlement)?,
        Ok(claim @ (Frame::Claim { .. } | Frame::CancelIntent { .. })) => visit(frame.at, claim)?,
        Ok(
            commit @ (Frame::Commit { .. }
            | Frame::NestedCommit { .. }
            | Frame::NestedPayload { .. }
            | Frame::Origin { .. }),
        ) => {
            visit(frame.at, commit)?;
        }
        Ok(_) => return Err(fault(schema("invalid required frame"))),
        Err(error) => return Err(located(error, frame.at)),
    }
    Ok(true)
}

fn visit_optional_metadata(
    reader: &mut impl Read,
    frame: &MetadataFrame,
    recovery: &mut Recovery,
    visit: &mut impl FnMut(u64, Frame) -> Result<()>,
    damage: &mut impl FnMut(SmithError) -> Result<()>,
) -> Result<bool> {
    let mut checksum = [0; 4];
    if !read_part(reader, &mut checksum, recovery)? {
        return Ok(false);
    }
    let expected = u32::from_le_bytes(checksum);
    let payload_len = frame.len - BODY_PREFIX_LEN;
    let fixed = match (frame.kind, frame.version) {
        (KIND_ENTRY, VERSION_ENTRY) => payload_len.min(ENTRY_METADATA_LEN),
        (KIND_SESSION_HEADER, VERSION_SESSION_HEADER) => payload_len.min(32),
        (KIND_INDEX, VERSION_NAV) => payload_len.min(48),
        (KIND_SELECTION, VERSION_NAV) => payload_len.min(16),
        (KIND_CHECKPOINT, VERSION_NAV) => payload_len.min(24),
        _ => 0,
    };
    let mut prefix = [0u8; ENTRY_METADATA_LEN];
    if !read_part(reader, &mut prefix[..fixed], recovery)? {
        return Ok(false);
    }
    let mut hasher = crc32fast::Hasher::new();
    hasher.update(&frame.kind.to_le_bytes());
    hasher.update(&frame.version.to_le_bytes());
    hasher.update(&prefix[..fixed]);
    let mut chunk = [0u8; 8192];
    let mut left = payload_len - fixed;
    while left > 0 {
        let n = metadata_chunk_size(left, chunk.len());
        if !read_part(reader, &mut chunk[..n], recovery)? {
            return Ok(false);
        }
        hasher.update(&chunk[..n]);
        left -= n;
    }
    let mut marker = [0; 4];
    if !read_part(reader, &mut marker, recovery)? {
        return Ok(false);
    }
    recovery.good_end += HEADER_LEN as u64 + frame.len as u64;
    if hasher.finalize() != expected || u32::from_le_bytes(marker) != expected ^ COMPLETION {
        metadata_fault(
            recovery,
            damage,
            FrameFault::Checksum {
                declared_length: frame.len,
            },
            frame.at,
        )?;
        return Ok(true);
    }
    match decode_metadata_frame(
        frame.kind,
        frame.version,
        payload_len,
        &prefix[..fixed],
        checksum,
        marker,
    ) {
        Ok(decoded) => visit(frame.at, decoded)?,
        Err(error) => metadata_fault(recovery, damage, error, frame.at)?,
    }
    Ok(true)
}

fn metadata_chunk_size(left: usize, buffer_len: usize) -> usize {
    let size = left.min(buffer_len);
    assert!(
        size > 0,
        "nonempty metadata remainder yields a positive chunk"
    );
    size
}

fn metadata_fault(
    recovery: &mut Recovery,
    report: &mut impl FnMut(SmithError) -> Result<()>,
    fault: FrameFault,
    at: u64,
) -> Result<()> {
    recovery.damage_count += 1;
    report(located(fault, at))
}

fn read_part(reader: &mut impl Read, bytes: &mut [u8], recovery: &mut Recovery) -> Result<bool> {
    match reader.read_exact(bytes) {
        Ok(()) => Ok(true),
        Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => {
            recovery.torn_tail_at = Some(recovery.good_end);
            Ok(false)
        }
        Err(e) => Err(read_error(&e)),
    }
}

fn decode_metadata_frame(
    kind: u16,
    version: u16,
    payload_len: usize,
    prefix: &[u8],
    checksum: [u8; 4],
    marker: [u8; 4],
) -> std::result::Result<Frame, FrameFault> {
    if kind == KIND_ENTRY && version == VERSION_ENTRY {
        if prefix.len() != ENTRY_METADATA_LEN {
            return Err(schema("short entry metadata"));
        }
        let actual = u32::from_le_bytes(
            prefix[58..62]
                .try_into()
                .map_err(|_| schema("entry length"))?,
        ) as usize;
        if actual != payload_len - ENTRY_METADATA_LEN {
            return Err(schema("entry content length mismatch"));
        }
        let mut metadata = [0; ENTRY_METADATA_LEN];
        metadata.copy_from_slice(prefix);
        metadata[58..62].fill(0);
        return decode_entry(&metadata).map(|entry| Frame::Known { entry });
    }
    if !prefix.is_empty() && prefix.len() == payload_len {
        return decode_body(
            kind,
            version,
            &[&checksum[..], prefix, &marker[..]].concat(),
        );
    }
    if matches!(
        kind,
        KIND_SESSION_HEADER | KIND_INDEX | KIND_SELECTION | KIND_CHECKPOINT
    ) {
        Err(schema("navigation or header length"))
    } else {
        Ok(Frame::Unknown {
            kind,
            version,
            payload: Vec::new(),
        })
    }
}

/// Write a full frame to a writer with an enforced payload size limit.
///
/// # Errors
///
/// Returns a framing error when encoding or writing fails.
pub fn write_frame(writer: &mut impl Write, frame: &Frame, frame_bytes_max: usize) -> Result<()> {
    let bytes = frame.encode(frame_bytes_max)?;
    writer.write_all(&bytes).map_err(|e| {
        fault(FrameFault::Encode {
            message: e.to_string(),
        })
    })?;
    Ok(())
}

const fn fault(f: FrameFault) -> SmithError {
    SmithError::Frame {
        fault: f,
        offset: None,
    }
}

const fn located(f: FrameFault, offset: u64) -> SmithError {
    SmithError::Frame {
        fault: f,
        offset: Some(offset),
    }
}

const fn too_large(bytes_max: usize, actual: usize) -> SmithError {
    fault(FrameFault::TooLarge { bytes_max, actual })
}

fn boundary(offset: u64) -> SmithError {
    SmithError::Session {
        code: smith::error::SessionCode::FrameBoundary,
        message: format!(
            "untrustworthy frame header at byte {offset}; cannot locate the next record"
        ),
    }
}

fn read_error(error: &std::io::Error) -> SmithError {
    SmithError::Session {
        code: smith::error::SessionCode::FrameRead,
        message: error.to_string(),
    }
}

/// Read exactly `buf.len()` bytes. `Ok(false)` means clean end of stream,
/// `Err` means a partial read, which is a torn tail.
fn read_exact_or_eof<R: Read>(reader: &mut R, buffer: &mut [u8]) -> std::io::Result<bool> {
    let mut filled = 0;
    let mut interrupted_reads = 0;
    while filled < buffer.len() {
        match reader.read(&mut buffer[filled..]) {
            Ok(0) => {
                if filled == 0 {
                    return Ok(false);
                }
                return Err(std::io::Error::new(
                    std::io::ErrorKind::UnexpectedEof,
                    "torn frame",
                ));
            }
            Ok(n) => {
                assert!(n > 0, "successful nonempty read makes positive progress");
                filled += n;
                interrupted_reads = 0;
            }
            Err(e) if e.kind() == std::io::ErrorKind::Interrupted => {
                if interrupted_reads == INTERRUPTED_READS_MAX {
                    return Err(e);
                }
                interrupted_reads += 1;
            }
            Err(e) => return Err(e),
        }
    }
    Ok(true)
}

/// Discard `len` bytes through a bounded copy buffer. `false` means the
/// stream ended early; other read errors propagate.
fn skip_exact<R: Read>(reader: &mut R, len: usize) -> std::io::Result<bool> {
    let len = len as u64;
    std::io::copy(&mut reader.take(len), &mut std::io::sink()).map(|skipped| skipped == len)
}

/// CRC-32 (IEEE 802.3, reflected) over kind, version, and payload.
///
/// `crc32fast` is pure Rust with runtime CPU dispatch (SSE4.2 PCLMULQDQ
/// where present); the table loop it replaces measured 60-80x slower on
/// large frames, and this checksum covers every frame twice.
fn crc32(kind: u16, version: u16, payload: &[u8]) -> u32 {
    let mut hasher = crc32fast::Hasher::new();
    hasher.update(&kind.to_le_bytes());
    hasher.update(&version.to_le_bytes());
    hasher.update(payload);
    hasher.finalize()
}

#[cfg(test)]
#[expect(
    clippy::unwrap_used,
    clippy::panic,
    reason = "tests may panic on invariant violations"
)]
mod tests {
    use super::*;
    use crate::session::{EntryContent, EntryKind, Session};
    use smith::id::ToolCallId;
    use smith::message::{ContentBlock, Message, Role};
    use smith::structured::ToolArguments;

    fn message_frame(message: Message) -> EntryFrame {
        EntryFrame::new(None, &EntryContent::Message(message)).unwrap()
    }

    fn sample_entry(thinking: bool) -> EntryFrame {
        let mut msg = Message::with_text(Role::User, "hello");
        if thinking {
            msg.add_block(ContentBlock::thinking("internal"));
        }
        message_frame(msg)
    }

    fn known_bytes(text: &str) -> Vec<u8> {
        Frame::Known {
            entry: message_frame(Message::with_text(Role::User, text)),
        }
        .encode(DEFAULT_MAX_FRAME_BYTES)
        .unwrap()
    }

    fn text_of(frame: &Frame) -> String {
        match frame {
            Frame::Known { entry } => match EntryContent::decode(&entry.content).unwrap() {
                EntryContent::Message(m) => match &m.blocks[0] {
                    ContentBlock::Text(t) => t.clone(),
                    other => panic!("unexpected block {other:?}"),
                },
                other => panic!("unexpected content {other:?}"),
            },
            other => panic!("unexpected frame {other:?}"),
        }
    }

    fn read_all(bytes: &[u8], frame_bytes_max: usize) -> Recovery {
        read_frames(&mut &bytes[..], frame_bytes_max).unwrap()
    }

    struct FailingReader;

    impl Read for FailingReader {
        fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
            Err(std::io::Error::from(std::io::ErrorKind::Other))
        }
    }

    struct CountedBrokenReader {
        reads: usize,
    }

    impl Read for CountedBrokenReader {
        fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
            self.reads += 1;
            Err(std::io::ErrorKind::BrokenPipe.into())
        }
    }

    struct AlwaysInterruptedReader {
        reads: usize,
    }

    impl Read for AlwaysInterruptedReader {
        fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
            self.reads += 1;
            Err(std::io::ErrorKind::Interrupted.into())
        }
    }

    struct InterruptedOnceThenData {
        interrupted: bool,
        bytes: &'static [u8],
    }

    impl Read for InterruptedOnceThenData {
        fn read(&mut self, buffer: &mut [u8]) -> std::io::Result<usize> {
            if !self.interrupted {
                self.interrupted = true;
                return Err(std::io::ErrorKind::Interrupted.into());
            }
            let count = buffer.len().min(self.bytes.len());
            buffer[..count].copy_from_slice(&self.bytes[..count]);
            self.bytes = &self.bytes[count..];
            Ok(count)
        }
    }

    #[test]
    fn non_interruption_errors_propagate_without_retry() {
        let mut reader = CountedBrokenReader { reads: 0 };
        let error = read_exact_or_eof(&mut reader, &mut [0; 1]).unwrap_err();
        assert_eq!(error.kind(), std::io::ErrorKind::BrokenPipe);
        assert_eq!(reader.reads, 1);
    }

    #[test]
    fn repeated_interruptions_are_bounded_and_propagated() {
        let mut reader = AlwaysInterruptedReader { reads: 0 };
        let error = read_exact_or_eof(&mut reader, &mut [0; 1]).unwrap_err();
        assert_eq!(error.kind(), std::io::ErrorKind::Interrupted);
        assert_eq!(reader.reads, INTERRUPTED_READS_MAX + 1);
    }

    #[test]
    fn metadata_reader_accepts_frame_with_no_variable_payload_remainder() {
        let frame = Frame::Unknown {
            kind: 0x7fff,
            version: u16::MAX,
            payload: Vec::new(),
        };
        let bytes = frame.encode(DEFAULT_MAX_FRAME_BYTES).unwrap();
        let mut visited = Vec::new();
        let recovery = visit_metadata_reporting(
            &mut bytes.as_slice(),
            DEFAULT_MAX_FRAME_BYTES,
            |offset, frame| {
                visited.push((offset, frame));
                Ok(())
            },
            |_| Ok(()),
        )
        .unwrap();
        assert_eq!(visited, vec![(0, frame)]);
        assert_eq!(recovery.good_end, bytes.len() as u64);
    }

    #[test]
    fn interruption_before_data_retries_successfully() {
        let mut reader = InterruptedOnceThenData {
            interrupted: false,
            bytes: b"ok",
        };
        let mut bytes = [0; 2];
        assert!(read_exact_or_eof(&mut reader, &mut bytes).unwrap());
        assert_eq!(&bytes, b"ok");
    }

    #[test]
    fn read_errors_are_not_torn_tails() {
        let error =
            visit_frames(&mut FailingReader, DEFAULT_MAX_FRAME_BYTES, |_| true).unwrap_err();
        assert_eq!(error.code(), "FRAME_READ");
    }

    #[test]
    fn corrupt_frame_is_reported_and_neighbours_survive() {
        let mut bytes = known_bytes("before");
        let corrupt_at = bytes.len() as u64;
        let mut corrupt = known_bytes("corrupt");
        // Flip one payload byte: the length prefix stays intact, the checksum fails.
        let last = corrupt.len() - 1;
        corrupt[last] ^= 0xFF;
        bytes.extend_from_slice(&corrupt);
        bytes.extend_from_slice(&known_bytes("after"));

        let recovery = read_all(&bytes, DEFAULT_MAX_FRAME_BYTES);
        let texts: Vec<String> = recovery.frames.iter().map(text_of).collect();
        assert_eq!(texts, vec!["before".to_string(), "after".to_string()]);
        assert_eq!(recovery.damage.len(), 1);
        assert_eq!(recovery.damage[0].code(), "FRAME_CHECKSUM");
        assert_eq!(
            recovery.damage[0],
            SmithError::Frame {
                fault: FrameFault::Checksum {
                    declared_length: corrupt.len() - HEADER_LEN
                },
                offset: Some(corrupt_at),
            }
        );
        assert_eq!(recovery.good_end, bytes.len() as u64);
        assert_eq!(recovery.torn_tail_at, None);
    }

    #[test]
    fn damaged_header_never_scans_payload_for_a_frame_boundary() {
        let nested = known_bytes("spoofed boundary");
        let mut bytes = Frame::Unknown {
            kind: 99,
            version: 1,
            payload: nested,
        }
        .encode(DEFAULT_MAX_FRAME_BYTES)
        .unwrap();
        bytes[0] ^= 1;
        bytes.extend_from_slice(&known_bytes("after"));
        assert_eq!(
            read_frames(&mut bytes.as_slice(), DEFAULT_MAX_FRAME_BYTES)
                .unwrap_err()
                .code(),
            "FRAME_BOUNDARY"
        );
    }

    #[test]
    fn optional_future_frame_round_trips_byte_for_byte() {
        let future = Frame::Unknown {
            kind: 0x3EEF,
            version: 7,
            payload: vec![0xDE, 0xAD, 0x01, 0x02],
        };
        let bytes = future.encode(DEFAULT_MAX_FRAME_BYTES).unwrap();
        let recovery = read_all(&bytes, DEFAULT_MAX_FRAME_BYTES);
        assert!(recovery.damage.is_empty());
        assert_eq!(recovery.frames, vec![future]);
        assert_eq!(
            recovery.frames[0].encode(DEFAULT_MAX_FRAME_BYTES).unwrap(),
            bytes
        );
    }

    #[test]
    fn known_frame_round_trips_through_fixed_metadata() {
        let entry = sample_entry(true);
        let bytes = Frame::Known {
            entry: entry.clone(),
        }
        .encode(DEFAULT_MAX_FRAME_BYTES)
        .unwrap();
        let recovery = read_all(&bytes, DEFAULT_MAX_FRAME_BYTES);
        assert_eq!(recovery.frames, vec![Frame::Known { entry }]);
        assert_eq!(recovery.good_end, bytes.len() as u64);
    }

    #[test]
    fn admission_rejects_content_that_disagrees_with_user_metadata() {
        let mut entry = message_frame(Message::with_text(Role::User, "admitted"));
        let user_kind = entry.kind;
        entry.content = message_frame(Message::with_text(Role::Assistant, "forged")).content;
        entry.kind = user_kind;
        let bytes = Frame::Admission { entry, key: None }
            .encode(DEFAULT_MAX_FRAME_BYTES)
            .unwrap();

        assert!(read_frames(&mut std::io::Cursor::new(bytes), DEFAULT_MAX_FRAME_BYTES).is_err());
    }

    #[test]
    fn entry_frame_carries_fixed_metadata_and_raw_content() {
        let call_id = ToolCallId::new();
        let content = EntryContent::ToolResult {
            ok: true,
            output: "done".to_string(),
            call_id,
        };
        let entry = EntryFrame::new(None, &content).unwrap();
        assert_eq!(entry.kind, EntryKind::ToolResult { call_id, ok: true });
        assert_eq!(EntryContent::decode(&entry.content).unwrap(), content);
        let bytes = Frame::Known {
            entry: entry.clone(),
        }
        .encode(DEFAULT_MAX_FRAME_BYTES)
        .unwrap();
        assert_eq!(
            &bytes[FRAME_PREFIX_LEN + ENTRY_METADATA_LEN..bytes.len() - 4],
            entry.content
        );
        assert_eq!(
            u32::from_le_bytes(
                bytes[FRAME_PREFIX_LEN + 58..FRAME_PREFIX_LEN + 62]
                    .try_into()
                    .unwrap()
            ) as usize,
            entry.content.len()
        );

        // A session record frames straight from arena bytes, identically.
        let mut session = Session::new();
        let record = *session.append(&content).unwrap();
        let from_arena =
            encode_entry(&record, session.bytes(&record), DEFAULT_MAX_FRAME_BYTES).unwrap();
        let owned = Frame::Known {
            entry: EntryFrame {
                id: record.id,
                parent: record.parent,
                timestamp_ms: record.timestamp_ms,
                kind: record.kind,
                content: session.bytes(&record).to_vec(),
            },
        };
        assert_eq!(from_arena, owned.encode(DEFAULT_MAX_FRAME_BYTES).unwrap());
    }

    #[test]
    fn torn_tail_is_located_and_earlier_frames_kept() {
        let mut bytes = known_bytes("kept");
        let tail_at = bytes.len() as u64;
        bytes.extend_from_slice(&known_bytes("lost")[..6]);
        let recovery = read_all(&bytes, DEFAULT_MAX_FRAME_BYTES);
        assert_eq!(
            recovery.frames.iter().map(text_of).collect::<Vec<_>>(),
            vec!["kept".to_string()]
        );
        assert_eq!(recovery.torn_tail_at, Some(tail_at));
        assert_eq!(recovery.good_end, tail_at);

        // A partial length prefix is torn too, never a fabricated header.
        let mut short = known_bytes("kept");
        let short_tail = short.len() as u64;
        short.extend_from_slice(&[0xFF, 0xFF]);
        let recovery = read_all(&short, DEFAULT_MAX_FRAME_BYTES);
        assert_eq!(recovery.frames.len(), 1);
        assert_eq!(recovery.torn_tail_at, Some(short_tail));
    }

    #[test]
    fn oversized_complete_frame_is_skipped_by_length() {
        let mut bytes = Frame::Unknown {
            kind: 9,
            version: 1,
            payload: vec![0xAB; 5000],
        }
        .encode(6000)
        .unwrap();
        let skipped = bytes.len() as u64;
        bytes.extend_from_slice(&known_bytes("tail"));
        let recovery = read_all(&bytes, 1024);
        assert_eq!(
            recovery.frames.iter().map(text_of).collect::<Vec<_>>(),
            vec!["tail".to_string()]
        );
        assert_eq!(recovery.damage.len(), 1);
        assert_eq!(recovery.damage[0].code(), "FRAME_TOO_LARGE");
        assert_eq!(
            recovery.damage[0],
            SmithError::Frame {
                fault: FrameFault::TooLarge {
                    bytes_max: 1024,
                    actual: 5000
                },
                offset: Some(0),
            }
        );
        assert_eq!(recovery.good_end, bytes.len() as u64);
        assert_eq!(skipped, (HEADER_LEN + BODY_PREFIX_LEN + 5000) as u64);
    }

    #[test]
    fn oversized_truncated_frame_is_torn_not_scanned() {
        let mut bytes = Frame::Unknown {
            kind: 9,
            version: 1,
            payload: vec![0; 200],
        }
        .encode(300)
        .unwrap();
        bytes.truncate(HEADER_LEN + 10);
        let recovery = read_all(&bytes, 50);
        assert!(recovery.frames.is_empty());
        assert!(recovery.damage.is_empty());
        assert_eq!(recovery.torn_tail_at, Some(0));
    }

    #[test]
    fn declared_length_below_body_prefix_is_malformed() {
        let mut bytes = Frame::Unknown {
            kind: 9,
            version: 1,
            payload: vec![],
        }
        .encode(100)
        .unwrap();
        bytes[..4].copy_from_slice(&3_u32.to_le_bytes());
        let checksum = crc32fast::hash(&bytes[..8]);
        bytes[8..12].copy_from_slice(&checksum.to_le_bytes());
        bytes.truncate(HEADER_LEN + 3);
        bytes.extend_from_slice(&known_bytes("after"));
        let recovery = read_all(&bytes, DEFAULT_MAX_FRAME_BYTES);
        assert_eq!(recovery.damage.len(), 1);
        assert_eq!(recovery.damage[0].code(), "FRAME_MALFORMED");
        assert_eq!(recovery.frames.len(), 1);
    }

    #[test]
    fn future_entry_version_is_preserved_verbatim() {
        let payload = vec![0xA0]; // empty CBOR map
        let frame = Frame::Unknown {
            kind: KIND_ENTRY,
            version: VERSION_ENTRY + 1,
            payload,
        };
        let bytes = frame.encode(DEFAULT_MAX_FRAME_BYTES).unwrap();
        let recovery = read_all(&bytes, DEFAULT_MAX_FRAME_BYTES);
        assert!(recovery.damage.is_empty());
        assert_eq!(recovery.frames, vec![frame]);
        assert_eq!(
            recovery.frames[0].encode(DEFAULT_MAX_FRAME_BYTES).unwrap(),
            bytes
        );
    }

    #[test]
    fn checksum_valid_entry_with_bad_schema_is_schema_damage() {
        let frame = Frame::Unknown {
            kind: KIND_ENTRY,
            version: VERSION_ENTRY,
            payload: vec![0xA0], // valid CBOR, not an Entry
        };
        let bytes = frame.encode(DEFAULT_MAX_FRAME_BYTES).unwrap();
        let recovery = read_all(&bytes, DEFAULT_MAX_FRAME_BYTES);
        assert!(recovery.frames.is_empty());
        assert_eq!(recovery.damage[0].code(), "FRAME_SCHEMA");
    }

    #[test]
    fn old_frames_without_header_checksum_are_rejected_as_ambiguous() {
        // Old layout: [len][CBOR payload] with no kind, version, or checksum.
        let entry = sample_entry(false);
        let payload = Frame::Known { entry }
            .encode(DEFAULT_MAX_FRAME_BYTES)
            .unwrap();
        let mut bytes = u32::try_from(payload.len()).unwrap().to_le_bytes().to_vec();
        bytes.extend_from_slice(&payload);
        assert_eq!(
            read_frames(&mut bytes.as_slice(), DEFAULT_MAX_FRAME_BYTES)
                .unwrap_err()
                .code(),
            "FRAME_BOUNDARY"
        );
    }

    #[test]
    fn sequential_frames_consume_the_whole_stream() {
        let mut bytes = known_bytes("one");
        bytes.extend_from_slice(&known_bytes("two"));
        let recovery = read_all(&bytes, DEFAULT_MAX_FRAME_BYTES);
        assert_eq!(
            recovery.frames.iter().map(text_of).collect::<Vec<_>>(),
            vec!["one".to_string(), "two".to_string()]
        );
        assert_eq!(recovery.good_end, bytes.len() as u64);
    }

    #[test]
    fn encoding_rejects_frames_above_limit() {
        let big = message_frame({
            let mut m = Message::with_text(Role::User, "x");
            m.add_block(ContentBlock::text("y".repeat(4096)));
            m
        });
        let error = Frame::Known { entry: big }.encode(64).unwrap_err();
        assert!(
            matches!(error, SmithError::Frame { fault: FrameFault::TooLarge { bytes_max: 64, actual }, .. } if actual > 64)
        );
    }

    #[test]
    fn default_ceiling_admits_one_mebibyte_payloads_and_no_more() {
        let frame = |len| Frame::Unknown {
            kind: 9,
            version: 1,
            payload: vec![0; len],
        };
        let at_ceiling = frame(1 << 20).encode(DEFAULT_MAX_FRAME_BYTES).unwrap();
        assert_eq!(at_ceiling.len(), HEADER_LEN + BODY_PREFIX_LEN + (1 << 20));
        assert_eq!(
            frame((1 << 20) + 1).encode(DEFAULT_MAX_FRAME_BYTES),
            Err(too_large(1 << 20, (1 << 20) + 1))
        );
    }

    #[test]
    fn equivalent_inputs_encode_identically_despite_key_order() {
        let a = serde_json::json!({"path": "p", "content": {"b": 1, "a": 2}});
        let b = serde_json::json!({"content": {"a": 2, "b": 1}, "path": "p"});
        let call_id = ToolCallId::new();
        let e1 = EntryFrame::new(
            None,
            &EntryContent::ToolCall {
                name: "write".into(),
                input: ToolArguments::from_serializable(&a).unwrap(),
                call_id,
            },
        )
        .unwrap();
        let mut e2 = EntryFrame::new(
            None,
            &EntryContent::ToolCall {
                name: "write".into(),
                input: ToolArguments::from_serializable(&b).unwrap(),
                call_id,
            },
        )
        .unwrap();
        // Force identical ids/timestamps so only key order could differ.
        e2.id = e1.id;
        e2.timestamp_ms = e1.timestamp_ms;
        let b1 = Frame::Known { entry: e1 }.encode(1 << 20).unwrap();
        let b2 = Frame::Known { entry: e2 }.encode(1 << 20).unwrap();
        assert_eq!(b1, b2);
    }

    #[test]
    fn navigation_frames_round_trip_and_fixed_index_matches_heap_encoder() {
        let id = EntryId::from_u128(13);
        let parent = EntryId::from_u128(7);
        let index = Frame::Index {
            id,
            offset: 4096,
            parent: Some(parent),
            parent_offset: Some(128),
        };
        let bytes = index.encode(DEFAULT_MAX_FRAME_BYTES).unwrap();
        assert_eq!(bytes, index_bytes(id, 4096, Some(parent), Some(128)));
        let selection = Frame::Selection { id };
        let mut stream = bytes;
        stream.extend(selection.encode(DEFAULT_MAX_FRAME_BYTES).unwrap());
        let checkpoint = Frame::Checkpoint { id, offset: 4096 };
        stream.extend(checkpoint.encode(DEFAULT_MAX_FRAME_BYTES).unwrap());
        assert_eq!(
            read_all(&stream, DEFAULT_MAX_FRAME_BYTES).frames,
            vec![index, selection, checkpoint]
        );
    }

    #[test]
    fn header_frame_round_trips() {
        let header = SessionHeader {
            session_id: smith::id::SessionId::new(),
            branch_id: smith::id::BranchId::new(),
        };
        let bytes = Frame::Header { header }
            .encode(DEFAULT_MAX_FRAME_BYTES)
            .unwrap();
        let recovery = read_all(&bytes, DEFAULT_MAX_FRAME_BYTES);
        assert_eq!(recovery.frames, vec![Frame::Header { header }]);
        assert!(recovery.damage.is_empty());
    }

    #[test]
    fn checksum_matches_known_reference_value() {
        // CRC-32 of "123456789" is a published check value.
        assert_eq!(crc32(0x3231, 0x3433, b"56789"), 0xCBF4_3926);
    }
}

/// Frame stream round-trip law (`SMH-SPEC-SPEC0001`, Sessions).
#[cfg(test)]
mod properties {
    use super::*;
    use crate::session::properties::role;
    use crate::session::{EntryContent, EntryKind};
    use proptest::collection::vec;
    use proptest::prelude::*;
    use smith::id::{BranchId, EntryId, MessageId, SessionId, ToolCallId};
    use smith::message::Message;

    fn kind() -> impl Strategy<Value = EntryKind> {
        prop_oneof![
            (any::<u128>(), role()).prop_map(|(id, role)| EntryKind::Message {
                id: MessageId::from_u128(id),
                role,
            }),
            any::<u128>().prop_map(|id| EntryKind::ToolCall {
                call_id: ToolCallId::from_u128(id),
            }),
            (any::<u128>(), any::<bool>()).prop_map(|(id, ok)| EntryKind::ToolResult {
                call_id: ToolCallId::from_u128(id),
                ok,
            }),
            any::<bool>().prop_map(|compaction| EntryKind::Meta { compaction }),
        ]
    }

    /// Any frame this build writes: header, entry with opaque content bytes,
    /// or a frame of a kind it does not know.
    fn frame() -> impl Strategy<Value = Frame> {
        prop_oneof![
            (any::<u128>(), any::<u128>()).prop_map(|(session, branch)| Frame::Header {
                header: SessionHeader {
                    session_id: SessionId::from_u128(session),
                    branch_id: BranchId::from_u128(branch),
                },
            }),
            (
                any::<u128>(),
                proptest::option::of(any::<u128>()),
                any::<i64>(),
                kind(),
                vec(any::<u8>(), 0..64),
            )
                .prop_map(|(id, parent, timestamp_ms, kind, content)| Frame::Known {
                    entry: EntryFrame {
                        id: EntryId::from_u128(id),
                        parent: parent.map(EntryId::from_u128),
                        timestamp_ms,
                        kind,
                        content,
                    },
                }),
            (
                any::<u128>(),
                any::<u64>(),
                any::<u128>(),
                any::<u64>(),
                any::<bool>(),
            )
                .prop_map(|(id, offset, parent, parent_offset, has_parent)| {
                    Frame::Index {
                        id: EntryId::from_u128(id),
                        offset,
                        parent: has_parent.then(|| EntryId::from_u128(parent | 1)),
                        parent_offset: has_parent.then_some(parent_offset | 1),
                    }
                }),
            ("[a-z]{0,64}", proptest::option::of("[a-z]{1,64}")).prop_map(|(text, key)| {
                Frame::Admission {
                    entry: EntryFrame::new(
                        None,
                        &EntryContent::Message(Message::with_text(Role::User, text)),
                    )
                    .unwrap(),
                    key,
                }
            }),
            any::<u128>().prop_map(|id| Frame::Selection {
                id: EntryId::from_u128(id),
            }),
            (any::<u128>(), any::<u64>()).prop_map(|(id, offset)| Frame::Checkpoint {
                id: EntryId::from_u128(id),
                offset,
            }),
            (
                (0u16..0x8000u16, any::<u16>()).prop_filter(
                    "known frame versions decode through their schemas",
                    |(kind, version)| {
                        !matches!(
                            (*kind, *version),
                            (KIND_ENTRY, VERSION_ENTRY)
                                | (KIND_SESSION_HEADER, VERSION_SESSION_HEADER)
                                | (KIND_INDEX, VERSION_NAV)
                                | (KIND_SELECTION, VERSION_NAV)
                                | (KIND_CHECKPOINT, VERSION_NAV)
                        )
                    },
                ),
                vec(any::<u8>(), 0..64),
            )
                .prop_map(|((kind, version), payload)| Frame::Unknown {
                    kind,
                    version,
                    payload,
                }),
        ]
    }

    #[test]
    fn origin_required_version_and_corruption_fail_closed() {
        for version in [0, 2, u16::MAX] {
            let bytes = Frame::Unknown {
                kind: KIND_ORIGIN,
                version,
                payload: vec![0; 17],
            }
            .encode(DEFAULT_MAX_FRAME_BYTES)
            .unwrap();
            assert!(read_frames(&mut bytes.as_slice(), DEFAULT_MAX_FRAME_BYTES).is_err());
            assert!(
                visit_metadata_reporting(
                    &mut bytes.as_slice(),
                    DEFAULT_MAX_FRAME_BYTES,
                    |_, _| Ok(()),
                    |_| Ok(())
                )
                .is_err()
            );
        }
        let mut bytes = Frame::Origin {
            source: SessionId::new(),
            begin: true,
        }
        .encode(DEFAULT_MAX_FRAME_BYTES)
        .unwrap();
        bytes[HEADER_LEN + 4] ^= 1;
        assert!(read_frames(&mut bytes.as_slice(), DEFAULT_MAX_FRAME_BYTES).is_err());
        assert!(
            visit_metadata_reporting(
                &mut bytes.as_slice(),
                DEFAULT_MAX_FRAME_BYTES,
                |_, _| Ok(()),
                |_| Ok(())
            )
            .is_err()
        );
    }

    proptest! {
        #[test]
        fn origin_roundtrips_exact_namespace(id in any::<u128>(), begin in any::<bool>()) {
            let frame = Frame::Origin { source: SessionId::from_u128(id), begin };
            let encoded = frame.encode(DEFAULT_MAX_FRAME_BYTES).unwrap();
            prop_assert_eq!(encoded.len(), FRAME_PREFIX_LEN + 17 + 4);
            let decoded = read_frames(&mut encoded.as_slice(), DEFAULT_MAX_FRAME_BYTES).unwrap();
            prop_assert_eq!(decoded.frames, vec![frame.clone()]);
            let mut metadata = Vec::new();
            visit_metadata_reporting(&mut encoded.as_slice(), DEFAULT_MAX_FRAME_BYTES, |_, frame| { metadata.push(frame); Ok(()) }, Err).unwrap();
            prop_assert_eq!(metadata, vec![frame]);
        }

        #[test]
        fn cancellation_intent_roundtrips_exact_identity(id in any::<u128>()) {
            let frame = Frame::CancelIntent { submission_id: EntryId::from_u128(id) };
            let encoded = frame.encode(DEFAULT_MAX_FRAME_BYTES).unwrap();
            prop_assert_eq!(encoded.len(), FRAME_PREFIX_LEN + 17 + 4);
            let decoded = read_frames(&mut encoded.as_slice(), DEFAULT_MAX_FRAME_BYTES).unwrap();
            prop_assert_eq!(decoded.frames, vec![frame]);
        }

        #[test]
        fn visitor_and_eager_reader_agree_on_every_frame(frames in vec(frame(), 0..8)) {
            // SMH-SPEC-SPEC0001: Sessions, bounded sequential reads preserve semantics.
            let mut bytes = Vec::new();
            for frame in &frames {
                bytes.extend(frame.encode(DEFAULT_MAX_FRAME_BYTES).map_err(|e| TestCaseError::fail(e.to_string()))?);
            }
            let eager = read_frames(&mut bytes.as_slice(), DEFAULT_MAX_FRAME_BYTES).unwrap();
            let mut visited = Vec::new();
            let scan = visit_frames(&mut bytes.as_slice(), DEFAULT_MAX_FRAME_BYTES, |frame| {
                visited.push(frame);
                true
            }).unwrap();
            prop_assert_eq!(visited, eager.frames);
            prop_assert_eq!(scan.damage, eager.damage);
            prop_assert_eq!(scan.good_end, eager.good_end);
            prop_assert_eq!(scan.torn_tail_at, eager.torn_tail_at);
        }

        #[test]
        fn encoded_frame_streams_decode_to_the_same_frames(frames in vec(frame(), 0..8)) {
            let mut bytes = Vec::new();
            for frame in &frames {
                bytes.extend(
                    frame
                        .encode(DEFAULT_MAX_FRAME_BYTES)
                        .map_err(|e| TestCaseError::fail(e.to_string()))?,
                );
            }
            let recovery = read_frames(&mut bytes.as_slice(), DEFAULT_MAX_FRAME_BYTES).unwrap();
            prop_assert!(recovery.damage.is_empty(), "damage: {:?}", recovery.damage);
            prop_assert_eq!(recovery.torn_tail_at, None);
            prop_assert_eq!(recovery.good_end, bytes.len() as u64);
            let mut again = Vec::new();
            for frame in &recovery.frames {
                again.extend(
                    frame
                        .encode(DEFAULT_MAX_FRAME_BYTES)
                        .map_err(|e| TestCaseError::fail(e.to_string()))?,
                );
            }
            prop_assert_eq!(recovery.frames, frames);
            prop_assert_eq!(again, bytes);
        }

        #[test]
        fn frame_encoding_is_deterministic_and_zero_fills_absent_fields(frame in frame()) {
            // SMH-SPEC-SPEC0001: Sessions, deterministic encoding and reserved bytes.
            let first = frame
                .encode(DEFAULT_MAX_FRAME_BYTES)
                .map_err(|error| TestCaseError::fail(error.to_string()))?;
            let second = frame
                .encode(DEFAULT_MAX_FRAME_BYTES)
                .map_err(|error| TestCaseError::fail(error.to_string()))?;
            prop_assert_eq!(&first, &second);
            prop_assert_eq!(&FILE_PROLOGUE[5..], &[0, 0, 0]);
            match frame {
                Frame::Known { ref entry } if entry.parent.is_none() => {
                    prop_assert_eq!(
                        &first[FRAME_PREFIX_LEN + 16..FRAME_PREFIX_LEN + 32],
                        &[0; 16]
                    );
                }
                Frame::Index { parent: None, .. } => {
                    prop_assert_eq!(&first[40..64], &[0; 24]);
                }
                _ => {}
            }
        }

        #[test]
        fn a_frame_exactly_at_the_limit_round_trips_and_one_byte_less_rejects_it(frame in frame()) {
            let unlimited = frame
                .encode(DEFAULT_MAX_FRAME_BYTES)
                .map_err(|e| TestCaseError::fail(e.to_string()))?;
            let payload_len = unlimited.len() - HEADER_LEN - BODY_PREFIX_LEN;
            let declared = u32::from_le_bytes(unlimited[..4].try_into().unwrap());
            prop_assert_eq!(declared as usize, BODY_PREFIX_LEN + payload_len);
            let at_limit = frame
                .encode(payload_len)
                .map_err(|e| TestCaseError::fail(e.to_string()))?;
            prop_assert_eq!(&at_limit, &unlimited);
            let recovery = read_frames(&mut at_limit.as_slice(), payload_len).unwrap();
            prop_assert!(recovery.damage.is_empty(), "damage: {:?}", recovery.damage);
            prop_assert_eq!(recovery.frames, vec![frame.clone()]);
            if let Some(below) = payload_len.checked_sub(1) {
                let result = frame.encode(below);
                prop_assert!(result.is_err(), "below-limit frame was accepted");
                let recovery = read_frames(&mut at_limit.as_slice(), below).unwrap();
                prop_assert!(recovery.frames.is_empty());
                prop_assert_eq!(recovery.good_end, at_limit.len() as u64);
            }
        }
    }
}