Luigit
repositories / smith

smith

There are many coding harnesses - but this one is fast

owned by admin

smith-core/src/store.rs

Raw
//! Durable session storage: append-only writer, incremental bounded loader,
//! and atomic repair publication (`SMH-SPEC-SPEC0001`, Sessions).

#[cfg(test)]
mod cancel_tests;
#[cfg(test)]
mod commit_tests;
#[cfg(test)]
mod lifecycle_tests;
#[cfg(test)]
mod nested_tests;
#[cfg(test)]
mod payload_tests;

use crate::frame::{
    FILE_PROLOGUE, Frame, Recovery, encode_entry, index_bytes, visit_frames,
    visit_frames_reporting, visit_metadata_reporting, write_frame,
};
use crate::session::{Entry, EntryFrame, Session};
use smith::config::Config;
use smith::error::{Result, SmithError};
use smith::id::{EntryId, SessionId};
use smith::tool::CancelHandle;

/// Pending durable work identity and its immutable destination.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct AdmissionReceipt {
    /// Session owning this admission.
    pub session_id: SessionId,
    /// Durable submission and initial work identity.
    pub submission_id: EntryId,
    /// Parent selected at admission, never inferred again on retry.
    pub destination: Option<EntryId>,
}

/// Durable root-work state; running work requires explicit recovery, never retry.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum WorkStatus {
    /// Accepted, not yet claimed.
    Queued,
    /// Claim persisted; completion unknown until a terminal record exists.
    Running,
    /// Completed stop or cancellation; `None` is explicit failure.
    Terminal(Option<smith::stream::StopReason>),
}

/// Bounded transitive source namespaces; ordinary sessions allocate no scope stack.
const ORIGIN_DEPTH_MAX: usize = 64;

#[derive(Default)]
struct OriginScopes {
    parents: Vec<(SessionId, u64, WorkLedger)>,
    current: u64,
    next: u64,
}

impl OriginScopes {
    fn boundary(&mut self, frame: &Frame, ledger: &mut WorkLedger) -> Result<bool> {
        let Frame::Origin { source, begin } = frame else {
            return Ok(false);
        };
        if *begin {
            if self.parents.len() == ORIGIN_DEPTH_MAX {
                return Err(admission_fault("source origin nesting exceeds 64 scopes"));
            }
            self.parents
                .push((*source, self.current, std::mem::take(ledger)));
            self.next += 1;
            self.current = self.next;
        } else {
            let (expected, parent, restored) = self
                .parents
                .pop()
                .ok_or_else(|| admission_fault("source origin close without open"))?;
            if expected != *source {
                return Err(admission_fault("source origin close mismatches namespace"));
            }
            // Unresolved source work remains evidence, never parent-owned pending work.
            *ledger = restored;
            self.current = parent;
        }
        Ok(true)
    }

    fn finish(&self) -> Result<()> {
        if self.parents.is_empty() {
            Ok(())
        } else {
            Err(admission_fault("unclosed source origin scope"))
        }
    }
}

#[derive(Clone, Copy, PartialEq, Eq)]
enum AdmissionMode {
    Queued,
    Foreground,
    Notification,
}

#[derive(Default)]
struct WorkLedger {
    lifecycle_root: Option<EntryId>,
    lifecycle_invocation: Option<EntryId>,
    lifecycle_effect: Option<EntryId>,
    lifecycle_ordinal: u16,
    live: Vec<(EntryId, WorkStatus)>,
    status: Option<WorkStatus>,
    output: Option<EntryId>,
    tool: Option<smith::id::ToolCallId>,
    nested: Option<(EntryId, smith::id::ToolCallId, u16)>,
    nested_progress: u16,
    tool_tip: Option<EntryId>,
    nested_causal: Option<crate::metadata::NestedCausality>,
    nested_parents: Vec<(
        (EntryId, smith::id::ToolCallId, u16),
        crate::metadata::NestedCausality,
    )>,
    payload: Option<PayloadProgress>,
    cancel_requested: bool,
    target_cancel_requested: bool,
}

/// One in-flight logical value: fixed owner and counters, never payload/history bytes.
struct PayloadProgress {
    root: EntryId,
    call: smith::id::ToolCallId,
    effect: EntryId,
    index: u16,
    phase: crate::frame::NestedPayloadPhase,
    bytes: usize,
    utf8_tail: [u8; 4],
    utf8_tail_len: u8,
}

impl PayloadProgress {
    fn validate_text(&mut self, mut bytes: &[u8]) -> Result<()> {
        while self.utf8_tail_len != 0 && !bytes.is_empty() {
            let length = usize::from(self.utf8_tail_len);
            if length == self.utf8_tail.len() {
                return Err(admission_fault("invalid UTF-8 payload"));
            }
            self.utf8_tail[length] = bytes[0];
            self.utf8_tail_len += 1;
            bytes = &bytes[1..];
            match std::str::from_utf8(&self.utf8_tail[..=length]) {
                Ok(_) => self.utf8_tail_len = 0,
                Err(error) if error.error_len().is_some() => {
                    return Err(admission_fault("invalid UTF-8 payload"));
                }
                Err(_) => {}
            }
        }
        if self.utf8_tail_len == 0
            && let Err(error) = std::str::from_utf8(bytes)
        {
            if error.error_len().is_some() {
                return Err(admission_fault("invalid UTF-8 payload"));
            }
            let tail = &bytes[error.valid_up_to()..];
            self.utf8_tail[..tail.len()].copy_from_slice(tail);
            self.utf8_tail_len =
                u8::try_from(tail.len()).map_err(|_| admission_fault("invalid UTF-8 tail"))?;
        }
        Ok(())
    }
}

impl WorkLedger {
    const fn unresolved(&self) -> bool {
        self.nested.is_some() || self.payload.is_some() || self.lifecycle_invocation.is_some()
    }

    #[expect(
        clippy::too_many_lines,
        reason = "one ordered work transition table keeps all required-frame laws visible"
    )]
    fn apply(&mut self, frame: &Frame, target: Option<&EntryId>) -> Result<()> {
        if self.payload.is_some()
            && !matches!(
                frame,
                Frame::NestedPayload { .. }
                    | Frame::CancelIntent { .. }
                    | Frame::Known { .. }
                    | Frame::NestedCommit { .. }
                    | Frame::Index { .. }
                    | Frame::Checkpoint { .. }
            )
        {
            return Err(admission_fault(
                "unresolved nested payload requires recovery",
            ));
        }
        match frame {
            Frame::NestedPayload { chunk } => self.observe_payload(chunk)?,
            Frame::Admission { entry, key } => {
                if key.as_deref().is_some_and(|key| {
                    key.is_empty() || key.len() > crate::frame::ADMISSION_KEY_BYTES_MAX
                }) {
                    return Err(admission_fault("invalid durable submission key"));
                }
                if self.live.len() == PENDING_ADMISSIONS_MAX {
                    return Err(admission_fault("too many live submissions"));
                }
                if self.live.capacity() == 0 {
                    self.live.reserve_exact(PENDING_ADMISSIONS_MAX);
                }
                self.live.push((entry.id, WorkStatus::Queued));
                if target == Some(&entry.id) {
                    self.status = Some(WorkStatus::Queued);
                }
            }
            Frame::Known { entry }
                if self
                    .live
                    .iter()
                    .any(|(_, state)| *state == WorkStatus::Running)
                    && completion_member(&entry.kind, &entry.content)? =>
            {
                return Err(admission_fault(
                    "admitted completion members require one semantic commit",
                ));
            }
            Frame::Claim { submission_id } => {
                if self.unresolved() {
                    return Err(admission_fault(
                        "unresolved lifecycle effect requires recovery",
                    ));
                }
                self.lifecycle_root = Some(*submission_id);
                if self.live.first() != Some(&(*submission_id, WorkStatus::Queued)) {
                    return Err(admission_fault("claim violates FIFO or work state"));
                }
                self.live[0].1 = WorkStatus::Running;
                if target == Some(submission_id) {
                    self.status = Some(WorkStatus::Running);
                }
            }
            Frame::CancelIntent { submission_id } => {
                if self.live.first() != Some(&(*submission_id, WorkStatus::Running))
                    || self.cancel_requested
                {
                    return Err(admission_fault(
                        "cancellation requires running work without prior intent",
                    ));
                }
                self.cancel_requested = true;
                if target == Some(submission_id) {
                    self.target_cancel_requested = true;
                }
            }
            Frame::Known { entry } => self.observe_tool_entry(entry)?,
            Frame::NestedCommit { entry } => self.complete_nested(entry)?,
            Frame::Commit { checkpoint, .. } => {
                if self.unresolved() {
                    return Err(admission_fault(
                        "unresolved nested effect requires recovery",
                    ));
                }
                self.tool = None;
                self.nested_progress = 0;
                if self.live.first() != Some(&(checkpoint.submission_id, WorkStatus::Running)) {
                    return Err(admission_fault("completion requires earliest claimed work"));
                }
            }
            Frame::Settlement {
                submission_id,
                reason,
                output,
            } => {
                if self.unresolved() {
                    return Err(admission_fault(
                        "unresolved nested effect requires recovery",
                    ));
                }
                if *reason == Some(smith::stream::StopReason::ToolUse) {
                    return Err(admission_fault("tool-use is not terminal root work"));
                }
                if self.live.first() != Some(&(*submission_id, WorkStatus::Running)) {
                    return Err(admission_fault("settlement requires earliest claimed work"));
                }
                if self.cancel_requested && *reason != Some(smith::stream::StopReason::Abort) {
                    return Err(admission_fault(
                        "cancelled work cannot settle as success or failure",
                    ));
                }
                self.live.remove(0);
                self.cancel_requested = false;
                if target == Some(submission_id) {
                    self.status = Some(WorkStatus::Terminal(*reason));
                    self.output = output.as_ref().map(|entry| entry.id);
                }
            }
            _ => {}
        }
        Ok(())
    }
    fn observe_tool_entry(&mut self, entry: &EntryFrame) -> Result<()> {
        if self.lifecycle_invocation.is_some()
            && !matches!(entry.kind, crate::session::EntryKind::Meta { .. })
        {
            return Err(admission_fault(
                "open lifecycle invocation cannot publish conversation",
            ));
        }
        if let crate::session::EntryKind::Message {
            role: smith::message::Role::User,
            ..
        } = entry.kind
            && !self
                .live
                .iter()
                .any(|(_, status)| *status == WorkStatus::Running)
        {
            self.lifecycle_root = Some(entry.id);
        }
        if let crate::session::EntryKind::ToolCall { call_id } = entry.kind {
            if self.unresolved() {
                return Err(admission_fault(
                    "unresolved nested effect requires recovery",
                ));
            }
            self.tool = Some(call_id);
            self.nested_progress = 0;
        }
        if !matches!(entry.kind, crate::session::EntryKind::Meta { .. }) {
            self.tool_tip = Some(entry.id);
            if self.payload.is_some() {
                return Err(admission_fault("payload chunks require matching intent"));
            }
            return Ok(());
        }
        let content = crate::content_codec::EntryContentView::decode(&entry.content)?;
        self.observe_tool_entry_content(entry.id, &content)?;
        self.tool_tip = Some(entry.id);
        Ok(())
    }

    fn observe_tool_entry_content(
        &mut self,
        id: EntryId,
        content: &crate::content_codec::EntryContentView<'_>,
    ) -> Result<()> {
        if let crate::content_codec::EntryContentView::Meta { kind, detail } = content
            && crate::metadata::lifecycle::reserved(kind)
        {
            return self.observe_lifecycle(id, kind, *detail);
        }
        if let crate::content_codec::EntryContentView::Meta {
            kind: crate::metadata::NOTIFICATION_QUEUE_KIND,
            detail,
        } = content
        {
            let intent = crate::metadata::notification_admission(*detail)
                .map_err(|_| admission_fault("invalid notification queue intent"))?;
            if self.live.first() != Some(&(intent.notifying_root, WorkStatus::Running))
                || !self
                    .live
                    .contains(&(intent.submission_id, WorkStatus::Queued))
            {
                return Err(admission_fault(
                    "notification queue intent requires exact running and queued roots",
                ));
            }
            return Ok(());
        }
        if self.lifecycle_invocation.is_some() {
            return Err(admission_fault(
                "open lifecycle invocation requires matching evidence",
            ));
        }
        if matches!(
            content,
            crate::content_codec::EntryContentView::Meta {
                kind: crate::metadata::NESTED_COMPLETION_KIND,
                ..
            }
        ) {
            return Err(admission_fault(
                "nested completion requires a semantic commit",
            ));
        }
        if let crate::content_codec::EntryContentView::Meta {
            kind: crate::metadata::NESTED_INTENT_KIND,
            detail,
        } = content
        {
            let (root, call, index) = crate::metadata::nested_identity(*detail)
                .map_err(|_| admission_fault("invalid nested intent identity"))?;
            let causal = crate::metadata::nested_causality(*detail)
                .map_err(|_| admission_fault("invalid causal intent"))?;
            if causal.is_some_and(|causal| causal.effect_id != id)
                || causal.and_then(|causal| causal.parent) != self.nested.map(|pending| pending.0)
                || self.live.first() != Some(&(root, WorkStatus::Running))
                || self.tool != Some(call)
                || (self.nested.is_some()
                    && !self.nested_causal.is_some_and(|causal| causal.invocation))
                || index != self.nested_progress
            {
                return Err(admission_fault(
                    "nested intent violates root, ownership, ordinal, or depth",
                ));
            }
            self.finish_payload(id, *detail, "input")?;
            if let Some(pending) = self.nested {
                if self.nested_parents.len() >= usize::from(crate::metadata::NESTED_EFFECTS_MAX) {
                    return Err(admission_fault("causal stack depth exceeded"));
                }
                if self.nested_parents.capacity() == 0 {
                    self.nested_parents
                        .try_reserve_exact(usize::from(crate::metadata::NESTED_EFFECTS_MAX))
                        .map_err(|_| admission_fault("causal stack allocation failed"))?;
                }
                let parent = self
                    .nested_causal
                    .ok_or_else(|| admission_fault("causal parent missing"))?;
                self.nested_parents.push((pending, parent));
            }
            self.nested = Some((id, call, index));
            self.nested_causal = causal;
            self.nested_progress = index + 1;
        } else if self.payload.is_some() {
            return Err(admission_fault("payload chunks require matching intent"));
        }
        Ok(())
    }

    fn observe_lifecycle<'a>(
        &mut self,
        id: EntryId,
        kind: &str,
        detail: impl smith::structured::StructuredValue<'a>,
    ) -> Result<()> {
        use crate::metadata::lifecycle as evidence;
        use smith::structured::Kind;
        crate::metadata::validate(kind, detail)
            .map_err(|_| admission_fault("invalid lifecycle evidence"))?;
        let root = evidence::identity(detail, "root_entry_id")
            .map_err(|_| admission_fault("invalid lifecycle root"))?;
        let invocation = evidence::identity(detail, "invocation_id")
            .map_err(|_| admission_fault("invalid lifecycle parent"))?;
        if self.lifecycle_root != Some(root)
            || self
                .live
                .first()
                .is_some_and(|entry| *entry != (root, WorkStatus::Running))
        {
            return Err(admission_fault(
                "lifecycle root must own actual running user/submission",
            ));
        }
        match kind {
            evidence::INVOCATION_INTENT => {
                if invocation != id || self.unresolved() {
                    return Err(admission_fault(
                        "duplicate or overlapping lifecycle invocation",
                    ));
                }
                self.lifecycle_invocation = Some(id);
                self.lifecycle_ordinal = 0;
            }
            evidence::INVOCATION_COMPLETION => {
                if self.lifecycle_invocation != Some(invocation) || self.lifecycle_effect.is_some()
                {
                    return Err(admission_fault("premature lifecycle invocation completion"));
                }
                self.lifecycle_invocation = None;
            }
            evidence::EFFECT_INTENT | evidence::EFFECT_COMPLETION => {
                let effect = evidence::identity(detail, "effect_id")
                    .map_err(|_| admission_fault("invalid lifecycle effect"))?;
                let ordinal = match detail
                    .field("ordinal")
                    .map_err(|_| admission_fault("invalid lifecycle ordinal"))?
                    .ok_or_else(|| admission_fault("missing lifecycle ordinal"))?
                    .kind()
                    .map_err(|_| admission_fault("invalid lifecycle ordinal"))?
                {
                    Kind::Unsigned(value) => u16::try_from(value)
                        .map_err(|_| admission_fault("invalid lifecycle ordinal"))?,
                    Kind::Signed(value) => u16::try_from(value)
                        .map_err(|_| admission_fault("invalid lifecycle ordinal"))?,
                    _ => return Err(admission_fault("invalid lifecycle ordinal")),
                };
                if self.lifecycle_invocation != Some(invocation) {
                    return Err(admission_fault(
                        "lifecycle effect has wrong invocation parent",
                    ));
                }
                if kind == evidence::EFFECT_INTENT {
                    if effect != id
                        || self.lifecycle_effect.is_some()
                        || ordinal != self.lifecycle_ordinal
                    {
                        return Err(admission_fault(
                            "duplicate or out-of-order lifecycle effect intent",
                        ));
                    }
                    self.lifecycle_effect = Some(effect);
                } else {
                    if self.lifecycle_effect != Some(effect) || ordinal != self.lifecycle_ordinal {
                        return Err(admission_fault(
                            "lifecycle completion requires matching intent",
                        ));
                    }
                    self.lifecycle_effect = None;
                    self.lifecycle_ordinal += 1;
                }
            }
            _ => return Err(admission_fault("unknown lifecycle evidence")),
        }
        Ok(())
    }

    fn observe_payload(&mut self, chunk: &crate::frame::NestedPayloadChunk) -> Result<()> {
        use crate::frame::NestedPayloadPhase;
        use crate::metadata::{NESTED_CHUNK_BYTES_MAX, NESTED_PAYLOAD_BYTES_MAX};
        chunk
            .validate()
            .map_err(|_| admission_fault("invalid payload chunk"))?;
        if self.live.first() != Some(&(chunk.submission_id, WorkStatus::Running))
            || self.tool != Some(chunk.call_id)
            || match chunk.phase {
                NestedPayloadPhase::Input => {
                    chunk.index != self.nested_progress
                        || (self.nested.is_some()
                            && !self.nested_causal.is_some_and(|causal| causal.invocation))
                }
                NestedPayloadPhase::Output => {
                    self.nested != Some((chunk.effect_id, chunk.call_id, chunk.index))
                }
            }
        {
            return Err(admission_fault(
                "payload chunk violates root, call, effect, or phase",
            ));
        }
        let progress = self.payload.get_or_insert(PayloadProgress {
            root: chunk.submission_id,
            call: chunk.call_id,
            effect: chunk.effect_id,
            index: chunk.index,
            phase: chunk.phase,
            bytes: 0,
            utf8_tail: [0; 4],
            utf8_tail_len: 0,
        });
        if (
            progress.root,
            progress.call,
            progress.effect,
            progress.index,
            progress.phase,
        ) != (
            chunk.submission_id,
            chunk.call_id,
            chunk.effect_id,
            chunk.index,
            chunk.phase,
        ) || usize::from(chunk.ordinal) != progress.bytes / NESTED_CHUNK_BYTES_MAX
            || !progress.bytes.is_multiple_of(NESTED_CHUNK_BYTES_MAX)
            || progress.bytes + chunk.bytes.len() > NESTED_PAYLOAD_BYTES_MAX
        {
            return Err(admission_fault(
                "payload chunk sequence, owner, or byte bound mismatch",
            ));
        }
        progress.validate_text(&chunk.bytes)?;
        progress.bytes += chunk.bytes.len();
        Ok(())
    }

    fn finish_payload<'a>(
        &mut self,
        effect: EntryId,
        detail: impl smith::structured::StructuredValue<'a>,
        field: &str,
    ) -> Result<()> {
        let value = detail
            .field(field)
            .map_err(|_| admission_fault("invalid payload field"))?
            .ok_or_else(|| admission_fault("missing payload field"))?;
        let reference = crate::metadata::nested_payload_ref(value)
            .map_err(|_| admission_fault("invalid payload reference"))?;
        match (reference, self.payload.as_ref()) {
            (None, None) => Ok(()),
            (Some(reference), Some(progress))
                if progress.effect == effect
                    && progress.utf8_tail_len == 0
                    && progress.bytes == reference.payload_bytes as usize
                    && matches!(
                        (field, progress.phase),
                        ("input", crate::frame::NestedPayloadPhase::Input)
                            | ("output", crate::frame::NestedPayloadPhase::Output)
                    ) =>
            {
                self.payload = None;
                Ok(())
            }
            _ => Err(admission_fault(
                "payload reference requires exactly complete owned chunks",
            )),
        }
    }

    fn complete_nested(&mut self, entry: &EntryFrame) -> Result<()> {
        crate::frame::validate_nested_completion(entry)
            .map_err(|_| admission_fault("invalid nested completion"))?;
        let crate::content_codec::EntryContentView::Meta { detail, .. } =
            crate::content_codec::EntryContentView::decode(&entry.content)?
        else {
            return Err(admission_fault("nested completion is not metadata"));
        };
        let (root, call, index) = crate::metadata::nested_identity(detail)
            .map_err(|_| admission_fault("invalid nested checkpoint"))?;
        let causal = crate::metadata::nested_causality(detail)
            .map_err(|_| admission_fault("invalid causal checkpoint"))?;
        let effect = causal
            .map(|causal| causal.effect_id)
            .or(entry.parent)
            .ok_or_else(|| admission_fault("completion requires intent"))?;
        if self.live.first() != Some(&(root, WorkStatus::Running))
            || self.nested != Some((effect, call, index))
            || causal != self.nested_causal
            || entry.parent != self.tool_tip
        {
            return Err(admission_fault(
                "nested completion requires matching durable intent",
            ));
        }
        self.finish_payload(effect, detail, "output")?;
        self.tool_tip = Some(entry.id);
        if let Some((pending, causal)) = self.nested_parents.pop() {
            self.nested = Some(pending);
            self.nested_causal = Some(causal);
        } else {
            self.nested = None;
            self.nested_causal = None;
        }
        Ok(())
    }
}

fn authorize_lifecycle_root(
    ledger: &mut WorkLedger,
    parent: Option<&EntryId>,
    content: &[u8],
    mut lookup: impl FnMut(EntryId) -> Result<Option<(Option<EntryId>, bool)>>,
) -> Result<()> {
    if content.first() != Some(&3)
        || ledger
            .live
            .iter()
            .any(|(_, status)| *status == WorkStatus::Running)
    {
        return Ok(());
    }
    if crate::content_codec::metadata_name(content)?
        != Some(crate::metadata::lifecycle::INVOCATION_INTENT)
    {
        return Ok(());
    }
    let crate::content_codec::EntryContentView::Meta {
        kind: crate::metadata::lifecycle::INVOCATION_INTENT,
        detail,
    } = crate::content_codec::EntryContentView::decode(content)?
    else {
        return Ok(());
    };
    let root = crate::metadata::lifecycle::identity(detail, "root_entry_id")
        .map_err(|_| admission_fault("invalid lifecycle root"))?;
    let mut cursor = parent.copied();
    while let Some(id) = cursor {
        let (parent, user) =
            lookup(id)?.ok_or_else(|| admission_fault("lifecycle root ancestry missing"))?;
        if id == root {
            if !user {
                return Err(admission_fault(
                    "lifecycle root is not a durable user entry",
                ));
            }
            ledger.lifecycle_root = Some(root);
            return Ok(());
        }
        cursor = parent;
    }
    Err(admission_fault(
        "lifecycle root is outside durable invocation ancestry",
    ))
}

#[expect(
    clippy::too_many_lines,
    reason = "one ordered memory validation table mirrors all durable work transitions"
)]
pub(crate) fn validate_memory_work(frames: &[Frame]) -> Result<()> {
    use crate::frame::validate_work_message;
    use smith::message::Role;
    if !frames.iter().any(Frame::requires_work_validation) {
        return Ok(());
    }
    let mut ledger = WorkLedger::default();
    let mut origins = OriginScopes::default();
    for (index, frame) in frames.iter().enumerate() {
        if origins.boundary(frame, &mut ledger)? {
            continue;
        }
        let before = &frames[..index];
        for entry in frame.entries() {
            if before
                .iter()
                .flat_map(Frame::entries)
                .any(|prior| prior.id == entry.id)
            {
                return Err(admission_fault("duplicate entry in work history"));
            }
            if entry.parent.is_some_and(|id| {
                !before
                    .iter()
                    .flat_map(Frame::entries)
                    .chain(
                        frame
                            .entries()
                            .iter()
                            .take_while(|prior| prior.id != entry.id),
                    )
                    .any(|prior| prior.id == id)
            }) {
                return Err(admission_fault(
                    "work history parent does not precede child",
                ));
            }
        }
        if let Frame::Known { entry } = frame {
            authorize_lifecycle_root(&mut ledger, entry.parent.as_ref(), &entry.content, |id| {
                Ok(before
                    .iter()
                    .flat_map(Frame::entries)
                    .find(|entry| entry.id == id)
                    .map(|entry| {
                        (
                            entry.parent,
                            matches!(
                                entry.kind,
                                crate::session::EntryKind::Message {
                                    role: Role::User,
                                    ..
                                }
                            ),
                        )
                    }))
            })?;
        }
        match frame {
            Frame::Commit {
                checkpoint,
                entries,
            } => validate_memory_completion(before, checkpoint, entries, &ledger)?,
            Frame::Admission { entry, key } => {
                validate_work_message(entry, Role::User, ADMISSION_TEXT_BLOCKS_MAX)?;
                if let Some(key) = key {
                    let mut scopes = OriginScopes::default();
                    let mut ignored = WorkLedger::default();
                    for prior in before {
                        scopes.boundary(prior, &mut ignored)?;
                        if scopes.current == origins.current
                            && matches!(prior, Frame::Admission { key: Some(prior_key), .. } if prior_key == key)
                        {
                            return Err(admission_fault("duplicate durable submission key"));
                        }
                    }
                }
            }
            Frame::Settlement {
                submission_id,
                output: Some(entry),
                ..
            } => {
                validate_work_message(entry, Role::Assistant, usize::MAX)?;
                let mut parent = entry.parent;
                let mut belongs = false;
                while let Some(id) = parent {
                    if ledger
                        .live
                        .iter()
                        .any(|(live, _)| *live == id && live != submission_id)
                    {
                        return Err(admission_fault(
                            "terminal branch includes another pending input",
                        ));
                    }
                    if &id == submission_id {
                        belongs = true;
                        break;
                    }
                    parent = before
                        .iter()
                        .flat_map(Frame::entries)
                        .find(|entry| entry.id == id)
                        .ok_or_else(|| missing_entry(id))?
                        .parent;
                }
                if !belongs {
                    return Err(admission_fault(
                        "terminal output does not descend from submission",
                    ));
                }
            }
            _ => {}
        }
        ledger.apply(frame, None)?;
    }
    origins.finish()
}

fn validate_memory_completion(
    before: &[Frame],
    checkpoint: &crate::frame::ToolCompletionCheckpoint,
    entries: &[EntryFrame; 3],
    ledger: &WorkLedger,
) -> Result<()> {
    crate::frame::validate_completion(checkpoint, entries)
        .map_err(|_| admission_fault("invalid completion members"))?;
    if ledger.unresolved() {
        return Err(admission_fault(
            "unresolved nested effect requires recovery",
        ));
    }
    let mut parent = entries[0].parent;
    let mut intent = false;
    while let Some(id) = parent {
        if id == checkpoint.submission_id {
            if intent {
                return Ok(());
            }
            break;
        }
        if ledger.live.iter().any(|(live, _)| *live == id) {
            return Err(admission_fault("completion includes another pending input"));
        }
        let prior = before
            .iter()
            .flat_map(Frame::entries)
            .find(|entry| entry.id == id)
            .ok_or_else(|| missing_entry(id))?;
        validate_completion_ancestor(&prior.kind, checkpoint.call_id, &mut intent)?;
        parent = prior.parent;
    }
    Err(admission_fault(
        "completion requires its root and one preceding intent",
    ))
}

/// Maximum live admitted work in one session.
pub const PENDING_ADMISSIONS_MAX: usize = 64;

/// Maximum text blocks accepted by one admitted submission.
pub const ADMISSION_TEXT_BLOCKS_MAX: usize = 1_024;

/// Maximum entries resident while preparing one admitted execution context.
///
/// The byte ceiling is [`Config::frame_bytes_max`], retaining one configured
/// session bound for both persisted frames and resident preparation.
pub const CLAIM_RESIDENT_ITEMS_MAX: usize = ADMISSION_TEXT_BLOCKS_MAX;
use std::fs::{File, OpenOptions};
use std::io::{BufReader, Read, Seek, SeekFrom, Write};
use std::path::{Path, PathBuf};

/// Exclusive access to one session, held on a sidecar lock file.
///
/// The lock lives beside the session file rather than on it, because repair
/// publishes a replacement inode: a lock taken on the data file would leave
/// a waiter holding a descriptor on the replaced inode, and its appends
/// would vanish. The sidecar is never replaced, so every participant
/// serializes on the same object and opens the data file only after winning.
#[derive(Debug)]
struct SessionLock {
    file: File,
    path: PathBuf,
}

impl SessionLock {
    /// Acquire the lock for `path`, creating parent directories and the
    /// sidecar as needed. Blocks while another holder owns the session.
    fn acquire(path: &Path) -> Result<Self> {
        Self::lock(path, false)
    }

    fn try_acquire(path: &Path) -> Result<Self> {
        Self::lock(path, true)
    }

    fn lock(path: &Path, nonblocking: bool) -> Result<Self> {
        if let Some(parent) = path.parent()
            && !parent.as_os_str().is_empty()
        {
            std::fs::create_dir_all(parent)
                .map_err(io_error(smith::error::StorageCode::StoreMkdir, parent))?;
        }
        let path = canonical_session_path(path)?;
        let file = OpenOptions::new()
            .read(true)
            .write(true)
            .create(true)
            .truncate(false)
            .open(lock_path(&path))
            .map_err(io_error(
                smith::error::StorageCode::StoreLockOpen,
                &lock_path(&path),
            ))?;
        if nonblocking {
            fs2::FileExt::try_lock_exclusive(&file).map_err(io_error(
                smith::error::StorageCode::StoreBusy,
                &lock_path(&path),
            ))?;
        } else {
            fs2::FileExt::lock_exclusive(&file).map_err(io_error(
                smith::error::StorageCode::StoreLock,
                &lock_path(&path),
            ))?;
        }
        Ok(Self { file, path })
    }

    fn path(&self) -> &Path {
        &self.path
    }
}

impl Drop for SessionLock {
    fn drop(&mut self) {
        // Best-effort unlock; the OS also releases on close.
        let _unlock_result: std::io::Result<()> = fs2::FileExt::unlock(&self.file);
    }
}

pub(crate) fn scratch_file(operation: &str) -> Result<(PathBuf, File)> {
    let (path, file) = new_temp_file(
        &std::env::temp_dir().join("smith-scratch"),
        operation,
        SessionId::new(),
    )?;
    std::fs::remove_file(&path).map_err(io_error(
        smith::error::StorageCode::StoreScratchRemove,
        &path,
    ))?;
    Ok((path, file))
}

/// Sidecar lock file path for a session file.
fn readers_path(path: &Path) -> PathBuf {
    let mut name = path.as_os_str().to_os_string();
    name.push(".readers.lock");
    PathBuf::from(name)
}

fn lock_path(path: &Path) -> PathBuf {
    let mut name = path.as_os_str().to_os_string();
    name.push(".lock");
    PathBuf::from(name)
}

/// Resolve existing data symlinks, or a new file's parent symlinks, before
/// deriving sidecar paths.
///
/// Unix rejects data files with multiple hard links.
/// Bind mounts and non-Unix hard-link aliases have no portable safe identity
/// query, so callers must not expose one session through them.
fn canonical_session_path(path: &Path) -> Result<PathBuf> {
    match std::fs::canonicalize(path) {
        Ok(path) => {
            reject_ambiguous_data_alias(&path)?;
            Ok(path)
        }
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
            if std::fs::symlink_metadata(path).is_ok() {
                return Err(io_error(smith::error::StorageCode::StoreCanonicalize, path)(error));
            }
            let parent = path
                .parent()
                .filter(|parent| !parent.as_os_str().is_empty())
                .unwrap_or_else(|| Path::new("."));
            let parent = std::fs::canonicalize(parent)
                .map_err(io_error(smith::error::StorageCode::StoreCanonicalize, path))?;
            let name = path.file_name().ok_or_else(|| {
                storage_fault(
                    smith::error::StorageCode::StoreCanonicalize,
                    path,
                    format!("{} has no file name", path.display()),
                )
            })?;
            Ok(parent.join(name))
        }
        Err(error) => Err(io_error(smith::error::StorageCode::StoreCanonicalize, path)(error)),
    }
}

#[cfg(unix)]
fn reject_ambiguous_data_alias(path: &Path) -> Result<()> {
    use std::os::unix::fs::MetadataExt;

    let metadata =
        std::fs::metadata(path).map_err(io_error(smith::error::StorageCode::StoreStat, path))?;
    if metadata.is_file() && metadata.nlink() > 1 {
        return Err(SmithError::Session {
            code: smith::error::SessionCode::SessionAmbiguousAlias,
            message: format!("{} has multiple hard links", path.display()),
        });
    }
    Ok(())
}

#[cfg(not(unix))]
fn reject_ambiguous_data_alias(_: &Path) -> Result<()> {
    Ok(())
}

fn validate_named_identity(path: &Path, session_id: SessionId) -> Result<()> {
    if let Some(named_id) = path
        .file_stem()
        .and_then(|stem| stem.to_str())
        .and_then(|stem| stem.parse::<SessionId>().ok())
        && named_id != session_id
    {
        return Err(SmithError::Session {
            code: smith::error::SessionCode::SessionIdMismatch,
            message: format!(
                "{} names session {named_id}, not {session_id}",
                path.display()
            ),
        });
    }
    Ok(())
}

fn reject_existing_target(path: &Path) -> Result<()> {
    match std::fs::symlink_metadata(path) {
        Ok(_) => Err(SmithError::Session {
            code: smith::error::SessionCode::SessionExists,
            message: format!("{} already exists", path.display()),
        }),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
        Err(error) => Err(io_error(smith::error::StorageCode::CreateStat, path)(error)),
    }
}

#[cfg(test)]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum PublicationCheckpoint {
    TempCreated,
    PartialWrite,
    CompletedWrite,
    TempSynced,
    Published,
    ParentSynced,
    Cleanup,
}

#[cfg(test)]
type PublicationHook = Box<dyn FnMut(PublicationCheckpoint)>;

#[cfg(test)]
thread_local! {
    static PUBLICATION_HOOK: std::cell::RefCell<Option<PublicationHook>> = const { std::cell::RefCell::new(None) };
    static PARENT_SYNC_FAILURE: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
}

#[cfg(test)]
fn run_publication_hook(point: PublicationCheckpoint) {
    PUBLICATION_HOOK.with(|hook| {
        if let Some(hook) = hook.borrow_mut().as_mut() {
            hook(point);
        }
    });
}

macro_rules! publication_checkpoint {
    ($point:ident) => {{
        #[cfg(test)]
        run_publication_hook(PublicationCheckpoint::$point);
    }};
}

#[cfg(test)]
fn set_publication_hook(hook: impl FnMut(PublicationCheckpoint) + 'static) {
    PUBLICATION_HOOK.with(|slot| *slot.borrow_mut() = Some(Box::new(hook)));
}

#[cfg(test)]
fn clear_publication_hook() {
    PUBLICATION_HOOK.with(|slot| *slot.borrow_mut() = None);
}

#[cfg(test)]
fn set_parent_sync_failure(fail: bool) {
    PARENT_SYNC_FAILURE.with(|slot| slot.set(fail));
}

fn new_temp_file(path: &Path, operation: &str, id: SessionId) -> Result<(PathBuf, File)> {
    let name = path.file_name().ok_or_else(|| {
        storage_fault(
            smith::error::StorageCode::CreateTmp,
            path,
            format!("{} has no file name", path.display()),
        )
    })?;
    let mut last = path.to_path_buf();
    for attempt in 0..128 {
        let mut temporary = name.to_os_string();
        temporary.push(format!(".smith-{operation}-{id}-{attempt}.tmp"));
        let temporary = path.with_file_name(temporary);
        last.clone_from(&temporary);
        let mut options = OpenOptions::new();
        options.read(true).write(true).create_new(true);
        #[cfg(unix)]
        {
            use std::os::unix::fs::OpenOptionsExt;
            options.mode(0o600);
        }
        match options.open(&temporary) {
            Ok(file) => return Ok((temporary, file)),
            Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {}
            Err(error) => {
                return Err(io_error(smith::error::StorageCode::CreateTmp, &temporary)(
                    error,
                ));
            }
        }
    }
    Err(storage_fault(
        smith::error::StorageCode::CreateTmp,
        &last,
        format!(
            "could not allocate a unique temporary beside {}",
            path.display()
        ),
    ))
}

/// Append-only session writer holding exclusive access to its session.
///
/// Opening repairs a torn tail (truncating to the last complete frame
/// boundary) before appending, so acknowledged appends are always
/// reachable by the loader. The lock serializes writers against each other
/// and against repair.
#[derive(Debug)]
pub struct SessionWriter {
    file: File,
    config: Config,
    path: PathBuf,
    /// A failed write or sync may have appended an unreachable frame prefix.
    poisoned: bool,
    /// Derived from acknowledged lifecycle metadata; never a separate persistence authority.
    lifecycle_open: bool,
    /// Last known entry boundary, used only for reconstructible hints.
    last: Option<(EntryId, u64)>,
    /// Hints since the last reconstructible selected-tip checkpoint.
    since_checkpoint: u16,
    /// Held for the writer's lifetime; released on drop.
    _lock: SessionLock,
}

impl SessionWriter {
    /// Open (creating parent directories) and lock the session file.
    ///
    /// # Errors
    ///
    /// Returns a configuration, locking, or input/output error.
    pub fn open<P: AsRef<Path>>(path: P, config: Config) -> Result<Self> {
        Self::open_with_recovery(path, config).map(|(writer, _)| writer)
    }

    /// Open and lock the session file, returning bounded damage/tail metadata.
    /// No frame payloads are retained by the durable open path.
    fn open_with_recovery<P: AsRef<Path>>(path: P, config: Config) -> Result<(Self, Recovery)> {
        // Win the lock before opening the data file, so a repair that is
        // publishing a replacement cannot hand out a stale descriptor.
        let lock = SessionLock::try_acquire(path.as_ref())?;
        Self::attach(lock.path().to_path_buf(), config, lock)
    }

    /// Take over an already-locked session file.
    fn attach(path: PathBuf, config: Config, lock: SessionLock) -> Result<(Self, Recovery)> {
        // Validation already names the offending field path.
        config.validate()?;
        let mut file = OpenOptions::new()
            .read(true)
            .write(true)
            .create(true)
            .truncate(false)
            .open(&path)
            .map_err(io_error(smith::error::StorageCode::StoreOpen, &path))?;
        // Drop a torn tail before appending so new frames stay reachable.
        // Complete but damaged frames are left in place and stay reported.
        if file
            .metadata()
            .map_err(io_error(smith::error::StorageCode::StoreStat, &path))?
            .len()
            == 0
        {
            file.write_all(&FILE_PROLOGUE)
                .map_err(io_error(smith::error::StorageCode::StoreWrite, &path))?;
            file.sync_data()
                .map_err(io_error(smith::error::StorageCode::StoreSync, &path))?;
        }
        let (recovery, lifecycle_open) = walk_file_bounded(&file, &path, config.frame_bytes_max)?;
        let (first, _) = SessionReader::open(&path)?.first(config.frame_bytes_max)?;
        if let Some(named_id) = path
            .file_stem()
            .and_then(|stem| stem.to_str())
            .and_then(|stem| stem.parse::<smith::id::SessionId>().ok())
            && let Some(Frame::Header { header }) = first
            && header.session_id != named_id
        {
            return Err(SmithError::Session {
                code: smith::error::SessionCode::SessionIdMismatch,
                message: format!(
                    "{} records session {}, not {named_id}",
                    path.display(),
                    header.session_id
                ),
            });
        }
        let len = file
            .metadata()
            .map_err(io_error(smith::error::StorageCode::StoreStat, &path))?
            .len();
        if recovery.good_end < len {
            let coordination = OpenOptions::new()
                .read(true)
                .write(true)
                .create(true)
                .truncate(false)
                .open(readers_path(&path))
                .map_err(io_error(
                    smith::error::StorageCode::StoreReaderLockOpen,
                    &readers_path(&path),
                ))?;
            fs2::FileExt::try_lock_exclusive(&coordination).map_err(io_error(
                smith::error::StorageCode::StoreReadersActive,
                &readers_path(&path),
            ))?;
            file.set_len(recovery.good_end)
                .map_err(io_error(smith::error::StorageCode::StoreTruncate, &path))?;
            file.sync_data()
                .map_err(io_error(smith::error::StorageCode::StoreSync, &path))?;
            fs2::FileExt::unlock(&coordination).map_err(io_error(
                smith::error::StorageCode::StoreReaderUnlock,
                &readers_path(&path),
            ))?;
        }
        // Complete records may have survived a failed sync or lost acknowledgement.
        // Establish the recovered persistence boundary before returning writable authority.
        file.sync_data()
            .map_err(io_error(smith::error::StorageCode::StoreSync, &path))?;
        let since_checkpoint = recovery_checkpoint_count(&file, &path, config.frame_bytes_max)?;
        file.seek(SeekFrom::Start(recovery.good_end))
            .map_err(io_error(smith::error::StorageCode::StoreSeek, &path))?;
        Ok((
            Self {
                file,
                config,
                path,
                poisoned: false,
                lifecycle_open,
                last: None,
                since_checkpoint,
                _lock: lock,
            },
            recovery,
        ))
    }

    /// Atomically append one validated context edit to the selected ancestry.
    /// Publication follows the existing writer's durable acknowledgement.
    ///
    /// # Errors
    /// Invalid targets, schema, tool pairing, bounds or persistence reject the batch.
    pub fn edit_context(&mut self, edits: &[crate::context::ContextEdit]) -> Result<EntryId> {
        let mut session =
            SessionReader::open(&self.path)?.selected_session(self.config.frame_bytes_max)?;
        session.edit_context_with(edits, |entry, content| {
            let bytes = encode_entry(entry, content, self.config.frame_bytes_max)?;
            self.write_entry_bytes(&bytes, entry.id, entry.parent)
        })
    }

    fn validate_context_edit(&self, parent: Option<&EntryId>, content: &[u8]) -> Result<()> {
        if content.first() != Some(&4) {
            return Ok(());
        }
        let crate::content_codec::EntryContentView::ContextEdit(batch) =
            crate::content_codec::EntryContentView::decode(content)?
        else {
            return Err(admission_fault("invalid context edit"));
        };
        let session =
            SessionReader::open(&self.path)?.selected_session(self.config.frame_bytes_max)?;
        if parent.copied() != session.selected_id() {
            return Err(admission_fault(
                "context edit does not extend selected ancestry",
            ));
        }
        session.validate_context_edits(&batch.materialize()?)?;
        Ok(())
    }

    /// Durably admit one user input without executing it.
    ///
    /// `None` destination selects the current tip only for new submissions;
    /// keyed retries retain their original destination after navigation.
    /// Pending work has no fabricated terminal outcome. This storage slice
    /// deliberately does not authorize an executor or automatic recovery retry.
    ///
    /// # Errors
    /// Rejects conflicting keys, invalid destinations, exceeded bounds, damaged
    /// history, or uncertain persistence. Reopen establishes a new sync boundary.
    pub fn admit(
        &mut self,
        input: &smith::message::Message,
        key: Option<&str>,
        destination: Option<EntryId>,
    ) -> Result<AdmissionReceipt> {
        self.admit_input(input, key, destination.as_ref(), AdmissionMode::Queued)
            .map(|admission| admission.work.receipt)
    }

    /// Admit foreground input without inventing a second pending-work queue.
    /// Keyed retries return their original state, including after settlement.
    ///
    /// # Errors
    /// Rejects new input while any root is unresolved, conflicting keys, or storage faults.
    pub fn admit_foreground(
        &mut self,
        text: &str,
        key: Option<&str>,
    ) -> Result<crate::control::Admission> {
        self.admit_input(
            &smith::message::Message::with_text(smith::message::Role::User, text),
            key,
            None,
            AdmissionMode::Foreground,
        )
    }

    /// Durably retain input and its original delivery mode during notification.
    /// Caller must serialize this command against the exact live notification phase.
    /// Root work stays Running; this method never claims or dispatches input.
    ///
    /// # Errors
    /// Rejects stale roots, conflicting retries, exceeded bounds and uncertain writes.
    pub fn admit_notification(
        &mut self,
        root: EntryId,
        text: &str,
        key: Option<&str>,
        delivery: crate::agent::Delivery,
    ) -> Result<crate::control::Admission> {
        self.ensure_certain()?;
        if self
            .inspect_work(root)?
            .is_none_or(|work| work.status != WorkStatus::Running)
        {
            return Err(admission_fault(
                "notification admission requires a running root",
            ));
        }
        let admission = self.admit_input(
            &smith::message::Message::with_text(smith::message::Role::User, text),
            key,
            None,
            AdmissionMode::Notification,
        )?;
        let intent = crate::control::NotificationAdmission {
            source: crate::control::AdmissionSource::Rpc,
            notifying_root: root,
            submission_id: admission.work.receipt.submission_id,
            delivery,
        };
        if !admission.is_new {
            let mut original = None;
            SessionReader::open(&self.path)?.scan_owned_reporting(
                self.config.frame_bytes_max,
                |frame| {
                    if let Frame::Known { entry } = frame
                        && let crate::session::EntryContent::Meta { kind, detail } =
                            crate::session::EntryContent::decode(&entry.content)?
                        && kind == crate::metadata::NOTIFICATION_QUEUE_KIND
                    {
                        let recorded: crate::control::NotificationAdmission =
                            detail.deserialize_as().map_err(|_| {
                                admission_fault("invalid notification admission metadata")
                            })?;
                        if recorded.submission_id == intent.submission_id {
                            original = Some(recorded);
                        }
                    }
                    Ok(true)
                },
                Err,
            )?;
            if original.is_some_and(|recorded| recorded.delivery != delivery) {
                return Err(admission_fault(
                    "submission key conflicts with original delivery mode",
                ));
            }
            return Ok(admission);
        }
        let detail = crate::metadata::encode(&intent)?;
        let entry = EntryFrame::from_content(
            Some(&intent.submission_id),
            &crate::session::EntryContentRef::Meta {
                kind: crate::metadata::NOTIFICATION_QUEUE_KIND,
                detail: &detail,
            },
        )?;
        self.append_frame(&Frame::Known { entry })?;
        Ok(admission)
    }

    fn validate_admission(&self, input: &smith::message::Message, key: Option<&str>) -> Result<()> {
        if input.role != smith::message::Role::User {
            return Err(admission_fault("submission input must be a user message"));
        }
        if key
            .is_some_and(|key| key.is_empty() || key.len() > crate::frame::ADMISSION_KEY_BYTES_MAX)
        {
            return Err(admission_fault(
                "submission key must contain 1..=256 UTF-8 bytes",
            ));
        }
        if input.blocks.len() > ADMISSION_TEXT_BLOCKS_MAX {
            return Err(admission_fault(
                "submission exceeds 1024 text blocks; reduce input before admission",
            ));
        }
        let mut input_bytes = 128usize;
        for block in &input.blocks {
            let smith::message::ContentBlock::Text(text) = block else {
                return Err(admission_fault(
                    "this admission slice accepts text input only",
                ));
            };
            input_bytes = input_bytes.saturating_add(text.len()).saturating_add(16);
        }
        input_bytes = input_bytes.saturating_add(key.map_or(0, str::len));
        if input_bytes > self.config.frame_bytes_max {
            return Err(admission_fault(
                "submission exceeds commit byte limit; reduce input before admission",
            ));
        }
        Ok(())
    }

    fn admit_input(
        &mut self,
        input: &smith::message::Message,
        key: Option<&str>,
        destination: Option<&EntryId>,
        mode: AdmissionMode,
    ) -> Result<crate::control::Admission> {
        self.ensure_certain()?;
        self.validate_admission(input, key)?;
        let destination = destination.copied();
        let reader = SessionReader::open(&self.path)?;
        let header = reader.header(self.config.frame_bytes_max)?;
        let mut original = None;
        let ledger = reader.work_ledger(self.config.frame_bytes_max, None)?;
        let pending_count = ledger.live.len();
        let recovery = reader.scan_owned_reporting(self.config.frame_bytes_max, |frame| {
            if let Frame::Admission { entry, key: recorded_key } = frame
                && key.is_some() && recorded_key.as_deref() == key {
                    if original.is_some() { return Err(admission_fault("duplicate durable submission key; verify the session before mutation")); }
                    let crate::session::EntryContent::Message(recorded) = crate::session::EntryContent::decode(&entry.content)? else {
                        return Err(admission_fault("admitted input is not a message; verify the session"));
                    };
                    if recorded.role != input.role || recorded.blocks != input.blocks || destination.is_some_and(|id| Some(id) != entry.parent) {
                        return Err(admission_fault("submission key conflicts with accepted input or explicit destination; use a new key"));
                    }
                    original = Some(AdmissionReceipt { session_id: header.session_id, submission_id: entry.id, destination: entry.parent });
            }
            Ok(true)
        }, Err)?;
        if recovery.torn_tail_at.is_some() {
            return Err(admission_fault(
                "session has pending incomplete data; close and reopen before admission",
            ));
        }
        if let Some(receipt) = original {
            let work = self.inspect_work(receipt.submission_id)?.ok_or_else(|| {
                admission_fault("keyed admission is absent from validated records")
            })?;
            return Ok(crate::control::Admission {
                work,
                is_new: false,
            });
        }
        if ledger.lifecycle_invocation.is_some() && mode != AdmissionMode::Notification {
            return Err(admission_fault(
                "unresolved lifecycle invocation requires recovery",
            ));
        }
        if mode == AdmissionMode::Foreground && pending_count != 0 {
            return Err(admission_fault(
                "BUSY: unresolved work blocks new foreground input",
            ));
        }
        if pending_count >= PENDING_ADMISSIONS_MAX {
            return Err(admission_fault(
                "pending admissions exceed 64 work items; settle work before admitting more",
            ));
        }
        let parent = if let Some(id) = destination {
            if reader
                .find_entry(id, self.config.frame_bytes_max)?
                .is_none()
            {
                return Err(missing_entry(id));
            }
            Some(id)
        } else {
            reader.selected_tip(self.config.frame_bytes_max)?
        };
        let entry = EntryFrame::from_content(
            parent.as_ref(),
            &crate::session::EntryContentRef::Message(input),
        )?;
        let receipt = AdmissionReceipt {
            session_id: header.session_id,
            submission_id: entry.id,
            destination: parent,
        };
        self.append_frame_authorized(
            &Frame::Admission {
                entry,
                key: key.map(str::to_owned),
            },
            mode == AdmissionMode::Notification,
        )?;
        Ok(crate::control::Admission {
            work: crate::control::WorkReceipt {
                receipt,
                status: WorkStatus::Queued,
                cancel_requested: false,
            },
            is_new: true,
        })
    }

    /// Inspect only state acknowledged by this writer, never uncertain buffered bytes.
    ///
    /// # Errors
    /// Rejects poisoned writer state, malformed history, or storage faults.
    pub fn inspect_work(&self, id: EntryId) -> Result<Option<crate::control::WorkReceipt>> {
        self.ensure_certain()?;
        SessionReader::open(&self.path)?.inspect_work(id, self.config.frame_bytes_max)
    }

    fn ensure_certain(&self) -> Result<()> {
        if self.poisoned {
            return Err(storage_fault(
                smith::error::StorageCode::StorePoisoned,
                &self.path,
                "writer persistence is uncertain; close and reopen before acknowledgement",
            ));
        }
        Ok(())
    }

    /// Append and sync cancellation intent for exactly one running root.
    /// No settlement, replay, or provider work occurs here.
    ///
    /// # Errors
    /// Rejects duplicate, queued, terminal, unknown, or uncertain work.
    pub fn request_cancel(&mut self, submission_id: EntryId) -> Result<()> {
        self.ensure_certain()?;
        self.append_frame(&Frame::CancelIntent { submission_id })
    }

    /// Prepare the exact admitted branch, then durably claim before any effect.
    ///
    /// # Errors
    /// Rejects non-FIFO, already claimed, malformed, or incomplete work.
    pub fn claim(&mut self, submission_id: EntryId) -> Result<Session> {
        self.ensure_certain()?;
        let reader = SessionReader::open(&self.path)?;
        let ledger = reader.work_ledger(self.config.frame_bytes_max, None)?;
        if ledger.live.first() != Some(&(submission_id, WorkStatus::Queued)) {
            return Err(admission_fault(
                "only earliest queued work may be claimed; running work requires recovery",
            ));
        }
        let session = self.prepare_claim_context(&reader, submission_id)?;
        self.append_frame(&Frame::Claim { submission_id })?;
        Ok(session)
    }

    /// Check resident context bounds without retaining archived payloads.
    fn prepare_claim_context(
        &self,
        reader: &SessionReader,
        submission_id: EntryId,
    ) -> Result<Session> {
        let mut items = 0usize;
        let mut bytes = 0usize;
        let mut has_edits = false;
        reader.replay_at(submission_id, self.config.frame_bytes_max, |entry| {
            items = items
                .checked_add(1)
                .ok_or_else(|| admission_fault("claim context item count overflow"))?;
            bytes = bytes
                .checked_add(entry.content.len())
                .ok_or_else(|| admission_fault("claim context byte count overflow"))?;
            has_edits |= entry.content.first() == Some(&4);
            Ok(())
        })?;
        let exceeded = || {
            admission_fault(
                "claim context exceeds resident preparation limits; compact history before execution",
            )
        };
        if !has_edits && (items > CLAIM_RESIDENT_ITEMS_MAX || bytes > self.config.frame_bytes_max) {
            return Err(exceeded());
        }
        let session = reader.context_at(self.config.frame_bytes_max, None, Some(&submission_id))?;
        if has_edits {
            // Raw edit bodies and replaced messages are file-backed, not preparation state.
            items = session.active_branch().entries().len();
            bytes = 0;
            for entry in session.active_branch().entries() {
                if matches!(entry.kind, crate::session::EntryKind::Message { .. }) {
                    continue;
                }
                let raw = session.raw_bytes(entry)?;
                if matches!(
                    Session::decode_content(entry, &raw)?,
                    crate::content_codec::EntryContentView::ContextEdit(_)
                ) {
                    continue;
                }
                bytes = bytes
                    .checked_add(raw.len())
                    .ok_or_else(|| admission_fault("claim context byte count overflow"))?;
            }
            let mut encoded = Vec::new();
            for message in session.projected_messages()? {
                encoded.clear();
                crate::session::EntryContentRef::Message(&message).encode_into(&mut encoded)?;
                bytes = bytes
                    .checked_add(encoded.len())
                    .ok_or_else(|| admission_fault("claim context byte count overflow"))?;
                if bytes > self.config.frame_bytes_max {
                    return Err(exceeded());
                }
            }
            if items > CLAIM_RESIDENT_ITEMS_MAX || bytes > self.config.frame_bytes_max {
                return Err(exceeded());
            }
        }
        Ok(session)
    }

    /// Commit terminal outcome and final assistant text as one bounded frame.
    ///
    /// # Errors
    /// Rejects invalid transitions or output ancestry before writing; uncertain writes poison this writer.
    pub fn settle(
        &mut self,
        submission_id: EntryId,
        reason: Option<smith::stream::StopReason>,
        output: Option<EntryFrame>,
    ) -> Result<()> {
        match self.settle_execution(submission_id, reason, output)? {
            crate::control::SettlementDisposition::Committed => Ok(()),
            crate::control::SettlementDisposition::CancelBeforeCommit => Err(SmithError::Cancelled),
        }
    }

    /// Settle with an explicit pre-commit cancellation rejection, not an I/O failure.
    ///
    /// # Errors
    /// Returns transition or storage faults; errors never authorize resident adoption.
    pub fn settle_execution(
        &mut self,
        submission_id: EntryId,
        reason: Option<smith::stream::StopReason>,
        output: Option<EntryFrame>,
    ) -> Result<crate::control::SettlementDisposition> {
        self.ensure_certain()?;
        let reader = SessionReader::open(&self.path)?;
        let ledger = reader.work_ledger(self.config.frame_bytes_max, Some(&submission_id))?;
        if ledger.status != Some(WorkStatus::Running) {
            return Err(admission_fault("settlement requires claimed work"));
        }
        if ledger.target_cancel_requested && reason != Some(smith::stream::StopReason::Abort) {
            return Ok(crate::control::SettlementDisposition::CancelBeforeCommit);
        }
        if let Some(entry) = &output {
            let parent = entry
                .parent
                .ok_or_else(|| admission_fault("terminal output requires a parent"))?;
            let mut belongs = false;
            reader.replay_at(parent, self.config.frame_bytes_max, |entry| {
                belongs |= entry.id == submission_id;
                if ledger
                    .live
                    .iter()
                    .any(|(id, _)| *id == entry.id && *id != submission_id)
                {
                    return Err(admission_fault(
                        "terminal branch includes another pending input",
                    ));
                }
                Ok(())
            })?;
            if !belongs
                || reader
                    .find_entry(entry.id, self.config.frame_bytes_max)?
                    .is_some()
            {
                return Err(admission_fault(
                    "terminal output has invalid identity or ancestry",
                ));
            }
        }
        let frame = Frame::Settlement {
            submission_id,
            reason,
            output,
        };
        self.append_frame(&frame)?;
        Ok(crate::control::SettlementDisposition::Committed)
    }

    /// Append one frame. The encoded size is checked against the configured
    /// limit before any bytes are written; a rejected frame leaves the file
    /// unchanged.
    ///
    /// # Errors
    ///
    /// Returns a framing error for oversized frames, or an input/output error.
    /// A write or sync error poisons this writer; later appends fail.
    pub fn append_frame(&mut self, frame: &Frame) -> Result<()> {
        self.append_frame_authorized(frame, false)
    }

    fn append_frame_authorized(
        &mut self,
        frame: &Frame,
        notification_admission: bool,
    ) -> Result<()> {
        if self.lifecycle_open
            && !matches!(frame, Frame::Known { .. } | Frame::CancelIntent { .. })
            && !(notification_admission && matches!(frame, Frame::Admission { .. }))
        {
            return Err(admission_fault(
                "open lifecycle invocation requires matching evidence",
            ));
        }

        if matches!(frame, Frame::Origin { .. }) {
            return Err(admission_fault(
                "source origin scopes are written only by fork publication",
            ));
        }
        if matches!(frame, Frame::Unknown { kind, .. } if kind & 0x8000 != 0) {
            return Err(admission_fault(
                "required semantic records require the typed writer boundary",
            ));
        }
        let bytes = frame.encode(self.config.frame_bytes_max)?;
        if let Frame::Known { entry } = frame {
            self.validate_context_edit(entry.parent.as_ref(), &entry.content)?;
            self.reject_flattened_completion(&entry.kind, &entry.content)?;
        }
        if let Frame::Commit {
            checkpoint,
            entries,
        } = frame
        {
            let reader = SessionReader::open(&self.path)?;
            let (mut proof, _, _) = reader.proof(self.config.frame_bytes_max, None)?;
            let ledger = reader.scan_work(self.config.frame_bytes_max, None, &mut proof)?;
            reader.validate_completion(
                checkpoint,
                entries,
                &ledger,
                &mut proof,
                self.config.frame_bytes_max,
            )?;
            for entry in entries.as_slice() {
                if proof.find(entry.id)?.is_some() {
                    return Err(admission_fault("duplicate completion member identity"));
                }
            }
        }
        if let Frame::Settlement { reason, .. } = frame {
            let ledger =
                SessionReader::open(&self.path)?.work_ledger(self.config.frame_bytes_max, None)?;
            if ledger.unresolved() {
                return Err(admission_fault(
                    "unresolved nested effect requires recovery",
                ));
            }
            if ledger.cancel_requested && *reason != Some(smith::stream::StopReason::Abort) {
                return Err(SmithError::Cancelled);
            }
        }
        if matches!(
            frame,
            Frame::NestedPayload { .. } | Frame::CancelIntent { .. }
        ) {
            let reader = SessionReader::open(&self.path)?;
            reader
                .work_ledger(self.config.frame_bytes_max, None)?
                .apply(frame, None)?;
        }
        if let Frame::Known { entry } = frame {
            self.validate_nested_entry(entry.id, entry.parent.as_ref(), &entry.content)?;
        }
        if let Frame::NestedCommit { entry } = frame {
            let reader = SessionReader::open(&self.path)?;
            let mut ledger = reader.work_ledger(self.config.frame_bytes_max, None)?;
            ledger.apply(frame, None)?;
            if reader
                .find_entry(entry.id, self.config.frame_bytes_max)?
                .is_some()
            {
                return Err(admission_fault("duplicate nested completion identity"));
            }
        }
        self.write(&bytes)?;
        if let Frame::Known { entry } = frame {
            update_lifecycle_open(&mut self.lifecycle_open, &entry.content);
        }
        Ok(())
    }

    /// Append one session record as an entry frame, framing its arena
    /// `content` bytes directly. Size limits apply as in
    /// [`SessionWriter::append_frame`].
    ///
    /// # Errors
    ///
    /// Returns a framing error for oversized frames, or an input/output error.
    /// A write or sync error poisons this writer; later appends fail.
    pub fn append_entry(&mut self, entry: &Entry, content: &[u8]) -> Result<()> {
        let bytes = encode_entry(entry, content, self.config.frame_bytes_max)?;
        self.validate_context_edit(entry.parent.as_ref(), content)?;
        self.reject_flattened_completion(&entry.kind, content)?;
        if self.lifecycle_open
            || matches!(
                crate::content_codec::EntryContentView::decode(content)?,
                crate::content_codec::EntryContentView::Meta {
                    kind: crate::metadata::NESTED_INTENT_KIND
                        | crate::metadata::NESTED_COMPLETION_KIND
                        | crate::metadata::lifecycle::INVOCATION_INTENT
                        | crate::metadata::lifecycle::INVOCATION_COMPLETION
                        | crate::metadata::lifecycle::EFFECT_INTENT
                        | crate::metadata::lifecycle::EFFECT_COMPLETION,
                    ..
                }
            )
        {
            self.validate_nested_entry(entry.id, entry.parent.as_ref(), content)?;
        }
        self.write_entry_bytes(&bytes, entry.id, entry.parent)?;
        update_lifecycle_open(&mut self.lifecycle_open, content);
        self.append_deferred_checkpoint(entry.id)?;
        Ok(())
    }

    fn validate_nested_entry(
        &self,
        id: EntryId,
        parent: Option<&EntryId>,
        content_bytes: &[u8],
    ) -> Result<()> {
        let content = crate::content_codec::EntryContentView::decode(content_bytes)?;
        if self.lifecycle_open
            && !matches!(content, crate::content_codec::EntryContentView::Meta { kind, .. } if crate::metadata::lifecycle::reserved(kind) || kind == crate::metadata::NOTIFICATION_QUEUE_KIND)
        {
            return Err(admission_fault(
                "open lifecycle invocation requires matching evidence",
            ));
        }
        if matches!(
            content,
            crate::content_codec::EntryContentView::Meta {
                kind: crate::metadata::NESTED_COMPLETION_KIND,
                ..
            }
        ) {
            return Err(admission_fault(
                "nested completion requires a semantic commit",
            ));
        }
        if matches!(
            content,
            crate::content_codec::EntryContentView::Meta {
                kind: crate::metadata::NESTED_INTENT_KIND
                    | crate::metadata::lifecycle::INVOCATION_INTENT
                    | crate::metadata::lifecycle::INVOCATION_COMPLETION
                    | crate::metadata::lifecycle::EFFECT_INTENT
                    | crate::metadata::lifecycle::EFFECT_COMPLETION
                    | crate::metadata::NOTIFICATION_QUEUE_KIND,
                ..
            }
        ) {
            let reader = SessionReader::open(&self.path)?;
            if reader
                .find_entry(id, self.config.frame_bytes_max)?
                .is_some()
            {
                return Err(admission_fault("duplicate nested intent identity"));
            }
            let mut ledger = reader.work_ledger(self.config.frame_bytes_max, None)?;
            if matches!(
                content,
                crate::content_codec::EntryContentView::Meta {
                    kind: crate::metadata::lifecycle::INVOCATION_INTENT,
                    ..
                }
            ) {
                let (mut proof, _, _) = reader.proof(self.config.frame_bytes_max, None)?;
                authorize_lifecycle_root(&mut ledger, parent, content_bytes, |id| {
                    let Some(record) = proof.find(id)? else {
                        return Ok(None);
                    };
                    let entry = reader.entry_at(record.offset, self.config.frame_bytes_max)?;
                    Ok(Some((
                        entry.parent,
                        matches!(
                            entry.kind,
                            crate::session::EntryKind::Message {
                                role: smith::message::Role::User,
                                ..
                            }
                        ),
                    )))
                })?;
            }
            ledger.observe_tool_entry_content(id, &content)?;
        }
        Ok(())
    }

    fn reject_flattened_completion(
        &self,
        kind: &crate::session::EntryKind,
        content: &[u8],
    ) -> Result<()> {
        if completion_member(kind, content)?
            && SessionReader::open(&self.path)?
                .work_ledger(self.config.frame_bytes_max, None)?
                .live
                .iter()
                .any(|(_, state)| *state == WorkStatus::Running)
        {
            return Err(admission_fault(
                "admitted completion members require one semantic commit",
            ));
        }
        Ok(())
    }

    #[expect(
        clippy::large_types_passed_by_value,
        reason = "Copy parent ID is consumed once to resolve an index hint"
    )]
    fn write_entry_bytes(
        &mut self,
        bytes: &[u8],
        id: EntryId,
        parent: Option<EntryId>,
    ) -> Result<()> {
        let parent_offset = parent.and_then(|id| {
            self.last
                .filter(|(last, _)| *last == id)
                .map(|(_, offset)| offset)
        });
        let offset = self
            .file
            .stream_position()
            .map_err(io_error(smith::error::StorageCode::StoreSeek, &self.path))?;
        self.write(bytes)?;
        self.last = Some((id, offset));
        if (parent.is_none() || parent_offset.is_some()) && self.config.frame_bytes_max >= 48 {
            self.write(&index_bytes(id, offset, parent, parent_offset))?;
        }
        self.since_checkpoint += 1;
        Ok(())
    }

    fn append_deferred_checkpoint(&mut self, id: EntryId) -> Result<()> {
        if self.since_checkpoint < 64 || self.lifecycle_open || self.config.frame_bytes_max < 24 {
            return Ok(());
        }
        let Some((last, offset)) = self.last else {
            return Err(admission_fault("entry checkpoint lacks last entry"));
        };
        assert_eq!(id, last, "checkpoint follows appended entry");
        self.append_frame(&Frame::Checkpoint { id, offset })?;
        self.since_checkpoint = 0;
        Ok(())
    }

    /// Persist a branch-tip selection, including when no new entry was appended.
    ///
    /// # Errors
    /// Returns `ENTRY_NOT_FOUND` for an absent entry or a storage fault.
    pub fn select_entry(&mut self, id: EntryId) -> Result<()> {
        let (_, offset) = SessionReader::open(&self.path)?
            .find_entry(id, self.config.frame_bytes_max)?
            .ok_or_else(|| missing_entry(id))?;
        self.append_frame(&Frame::Selection { id })?;
        if self.config.frame_bytes_max >= 24 {
            self.append_frame(&Frame::Checkpoint { id, offset })?;
            self.since_checkpoint = 0;
        }
        self.last = Some((id, offset));
        Ok(())
    }

    fn write(&mut self, bytes: &[u8]) -> Result<()> {
        self.io_step(smith::error::StorageCode::StoreWrite, |file| {
            file.write_all(bytes)
        })?;
        self.io_step(smith::error::StorageCode::StoreSync, |file| {
            file.sync_data()
        })
    }

    fn io_step(
        &mut self,
        code: smith::error::StorageCode,
        step: impl FnOnce(&mut File) -> std::io::Result<()>,
    ) -> Result<()> {
        if self.poisoned {
            return Err(storage_fault(
                smith::error::StorageCode::StorePoisoned,
                &self.path,
                format!("{} may contain a partial append", self.path.display()),
            ));
        }
        match step(&mut self.file) {
            Ok(()) => Ok(()),
            Err(error) => {
                self.poisoned = true;
                Err(io_error(code, &self.path)(error))
            }
        }
    }

    #[cfg(test)]
    fn write_step(&mut self, step: impl FnOnce(&mut File) -> Result<()>) -> Result<()> {
        if self.poisoned {
            return Err(storage_fault(
                smith::error::StorageCode::StorePoisoned,
                &self.path,
                format!("{} may contain a partial append", self.path.display()),
            ));
        }
        match step(&mut self.file) {
            Ok(()) => Ok(()),
            Err(error) => {
                self.poisoned = true;
                Err(error)
            }
        }
    }

    /// Path of the underlying session file.
    #[must_use]
    pub fn path(&self) -> &Path {
        &self.path
    }
}

/// A session file opened for use.
#[derive(Debug)]
pub struct OpenSession {
    /// Restored, or newly created, session state.
    pub session: Session,
    /// Locked writer positioned after the last complete frame.
    pub writer: SessionWriter,
    /// Damage and torn-tail metadata found while loading; `frames` is empty
    /// on bounded durable open, not a second copy of session history.
    pub recovery: Recovery,
}

/// Open a session file, writing a header frame when the file is new.
///
/// Reopening restores the persisted session and branch IDs, so state
/// reconstructed from the same file is identical on every load. A file that
/// holds frames but no header cannot be attributed to a session and fails
/// explicitly instead of silently becoming a new session.
///
/// # Errors
///
/// Returns [`SmithError::Session`] when the file holds frames but no header,
/// or a locking, framing, or input/output error.
pub fn open_session(path: &Path, config: Config) -> Result<OpenSession> {
    open_session_with_access(path, config, AdmissionAccess::Inspect)
}

/// Open a session for provider or tool execution.
///
/// Pending admissions remain inspectable but cannot enter an execution context
/// until durable settlement support exists.
///
/// # Errors
///
/// Returns [`SmithError::Session`] when a pending submission exists, the file
/// holds frames but no header, or storage access fails.
pub fn open_session_for_execution(path: &Path, config: Config) -> Result<OpenSession> {
    open_session_with_access(path, config, AdmissionAccess::Execute)
}

#[derive(Clone, Copy)]
enum AdmissionAccess {
    Inspect,
    Execute,
}

fn open_session_with_access(
    path: &Path,
    config: Config,
    admission_access: AdmissionAccess,
) -> Result<OpenSession> {
    let (mut writer, recovery) = SessionWriter::open_with_recovery(path, config)?;
    let reader = SessionReader::open(&writer.path)?;
    if matches!(admission_access, AdmissionAccess::Execute)
        && recovery.good_end > FILE_PROLOGUE.len() as u64
    {
        reader.reject_pending_admissions(writer.config.frame_bytes_max)?;
    }
    let session = if recovery.good_end > FILE_PROLOGUE.len() as u64 {
        reader.selected_session(writer.config.frame_bytes_max)?
    } else if recovery.damage.is_empty() {
        let session = path
            .file_stem()
            .and_then(|stem| stem.to_str())
            .and_then(|stem| stem.parse().ok())
            .map_or_else(Session::new, Session::new_with_id);
        writer.append_frame(&Frame::Header {
            header: session.header(),
        })?;
        session
    } else {
        return Err(SmithError::Session {
            code: smith::error::SessionCode::SessionHeaderMissing,
            message: format!("{} holds frames but no session header", path.display()),
        });
    };
    if let Some(id) = session.selected_id() {
        writer.last = reader
            .find_entry(id, writer.config.frame_bytes_max)?
            .map(|(_, offset)| (id, offset));
    }
    Ok(OpenSession {
        session,
        writer,
        recovery,
    })
}

/// Publish `session` as a new session file and open it for appending.
///
/// The file is written completely and then published by a no-replace hard
/// link, so an interrupted fork leaves no half-written session behind and an
/// existing path is never overwritten.
///
/// # Errors
///
/// Returns [`SmithError::Session`] when the target already holds a session,
/// or a locking, framing, or input/output error.
pub fn create_session(path: &Path, session: &Session, config: Config) -> Result<OpenSession> {
    config.validate()?;
    if session.source_edits().is_some() {
        return Err(crate::context::invalid(
            "file-backed working sets omit raw edit ancestors; fork through SessionReader",
        ));
    }
    if session
        .active_branch()
        .entries()
        .first()
        .is_some_and(|root| root.parent.is_some())
    {
        return Err(session_fault(
            smith::error::SessionCode::SessionIncompleteContext,
            "effective context omits earlier ancestors; fork through SessionReader",
        ));
    }
    let lock = SessionLock::acquire(path)?;
    let path = lock.path().to_path_buf();
    validate_named_identity(&path, session.id())?;
    reject_existing_target(&path)?;
    let (temporary, mut out) = new_temp_file(&path, "create", session.id())?;
    publication_checkpoint!(TempCreated);
    let written = (|| {
        out.write_all(&FILE_PROLOGUE)
            .map_err(io_error(smith::error::StorageCode::CreateWrite, &temporary))?;
        publication_checkpoint!(PartialWrite);
        write_frame(
            &mut out,
            &Frame::Header {
                header: session.header(),
            },
            config.frame_bytes_max,
        )?;
        for entry in session.active_branch().entries() {
            let bytes = encode_entry(entry, session.bytes(entry), config.frame_bytes_max)?;
            out.write_all(&bytes)
                .map_err(io_error(smith::error::StorageCode::CreateWrite, &temporary))?;
        }
        if let Some(id) = session.selected_id()
            && session
                .active_branch()
                .entries()
                .last()
                .map(|entry| entry.id)
                != Some(id)
        {
            write_frame(&mut out, &Frame::Selection { id }, config.frame_bytes_max)?;
        }
        publication_checkpoint!(CompletedWrite);
        out.sync_all()
            .map_err(io_error(smith::error::StorageCode::CreateSync, &temporary))?;
        publication_checkpoint!(TempSynced);
        Ok(())
    })();
    drop(out);
    if let Err(error) = written {
        // Preserve the write failure; temporary-file removal is best-effort cleanup.
        let _cleanup_result: std::io::Result<()> = std::fs::remove_file(&temporary);
        return Err(error);
    }
    publish_no_clobber(&temporary, &path)?;
    publication_checkpoint!(Cleanup);
    let (writer, recovery) = SessionWriter::attach(path, config, lock)?;
    let session =
        SessionReader::open(writer.path())?.selected_session(writer.config.frame_bytes_max)?;
    Ok(OpenSession {
        session,
        writer,
        recovery,
    })
}

/// Visit frames within the file size observed at open, without retaining history.
///
/// A live incomplete tail is reported but never repaired by this read-only path.
/// Callers must inspect damage and torn tails before treating a scan as complete.
///
/// # Errors
/// Returns an input/output error or the visitor's error.
pub fn scan_session(
    path: &Path,
    frame_bytes_max: usize,
    visit: impl FnMut(Frame) -> Result<()>,
) -> Result<Recovery> {
    SessionReader::open(path)?.scan(frame_bytes_max, visit)
}

/// Whether the per-session exclusive writer lock is currently held.
///
/// # Errors
/// Returns an I/O error if the lock file cannot be probed.
pub fn writer_active(path: &Path) -> Result<bool> {
    let path = canonical_session_path(path)?;
    let file = match OpenOptions::new()
        .read(true)
        .write(true)
        .open(lock_path(&path))
    {
        Ok(file) => file,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(false),
        Err(e) => {
            return Err(io_error(
                smith::error::StorageCode::StoreLockOpen,
                &lock_path(&path),
            )(e));
        }
    };
    match fs2::FileExt::try_lock_exclusive(&file) {
        Ok(()) => {
            fs2::FileExt::unlock(&file).map_err(io_error(
                smith::error::StorageCode::StoreUnlock,
                &lock_path(&path),
            ))?;
            Ok(false)
        }
        Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => Ok(true),
        Err(e) => Err(io_error(
            smith::error::StorageCode::StoreLock,
            &lock_path(&path),
        )(e)),
    }
}

/// A pinned file generation, independent of writer ownership.
///
/// Public observers hold a shared maintenance lock; internal source-only clones
/// pin already-validated immutable bytes by file descriptor.
/// Snapshot length is captured at scan start; subsequent appends require a new scan.
#[derive(Debug)]
pub struct SessionReader {
    file: File,
    readers: Option<File>,
    snapshot_len: u64,
    writer_active: bool,
}

impl Drop for SessionReader {
    fn drop(&mut self) {
        // Source-only clones pin immutable validated bytes by inode; observers
        // additionally hold the maintenance lock, explicitly released after fork.
        if let Some(readers) = &self.readers {
            let _unlock_result: std::io::Result<()> = fs2::FileExt::unlock(readers);
        }
    }
}

/// Read an immutable raw chunk without sharing a seek cursor across session clones.
pub(crate) fn read_raw_chunk(file: &File, bytes_max: usize) -> Result<Vec<u8>> {
    let length = file
        .metadata()
        .map_err(|_| crate::context::invalid("raw chunk metadata failed"))?
        .len();
    let length = usize::try_from(length)
        .map_err(|_| crate::context::invalid("raw chunk length overflow"))?;
    if length > bytes_max {
        return Err(crate::context::invalid("raw chunk exceeds frame bound"));
    }
    let mut bytes = vec![0; length];
    SnapshotRead {
        file,
        at: 0,
        end: length as u64,
    }
    .read_exact(&mut bytes)
    .map_err(|_| crate::context::invalid("raw chunk read failed"))?;
    Ok(bytes)
}

struct SnapshotRead<'a> {
    file: &'a File,
    at: u64,
    end: u64,
}

impl Read for SnapshotRead<'_> {
    fn read(&mut self, buffer: &mut [u8]) -> std::io::Result<usize> {
        let available = usize::try_from(self.end.saturating_sub(self.at))
            .unwrap_or(usize::MAX)
            .min(buffer.len());
        if available == 0 {
            return Ok(0);
        }
        #[cfg(unix)]
        let n = std::os::unix::fs::FileExt::read_at(self.file, &mut buffer[..available], self.at)?;
        #[cfg(windows)]
        let n =
            std::os::windows::fs::FileExt::seek_read(self.file, &mut buffer[..available], self.at)?;
        #[cfg(not(any(unix, windows)))]
        let n = {
            let mut clone = self.file.try_clone()?;
            clone.seek(SeekFrom::Start(self.at))?;
            clone.read(&mut buffer[..available])?
        };
        debug_assert!(
            n <= available,
            "snapshot reader must not advance beyond its validated byte window"
        );
        self.at += n as u64;
        Ok(n)
    }
}

#[cfg(test)]
thread_local! {
    static METADATA_PASSES: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
    static PROOF_VISITS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
    static CHECKPOINT_HITS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
}

// Fixed-width, offset-sorted structural proof. Scratch is unlinked before
// scanning; file size grows, resident memory does not. Only the sequential
// prologue walk can populate these records, never a magic-shaped payload.
struct Proof {
    file: File,
    path: PathBuf,
    len: u64,
    selected_checkpoint: Option<ProofEntry>,
    has_work: bool,
    cancel: Option<CancelHandle>,
}

#[derive(Clone, Copy)]
struct ProofEntry {
    id: EntryId,
    parent: Option<EntryId>,
    offset: u64,
    parent_offset: Option<u64>,
    compaction: bool,
}

impl Proof {
    const WIDTH: u64 = 49;

    fn check_cancelled(&self) -> Result<()> {
        if self.cancel.as_ref().is_some_and(CancelHandle::is_cancelled) {
            return Err(SmithError::Cancelled);
        }
        Ok(())
    }

    fn get(&mut self, index: u64) -> Result<ProofEntry> {
        self.check_cancelled()?;
        #[cfg(test)]
        PROOF_VISITS.with(|visits| visits.set(visits.get() + 1));
        self.file
            .seek(SeekFrom::Start(index * Self::WIDTH))
            .map_err(io_error(
                smith::error::StorageCode::StoreProofSeek,
                &self.path,
            ))?;
        let mut bytes = [0; 49];
        self.file.read_exact(&mut bytes).map_err(io_error(
            smith::error::StorageCode::StoreProofRead,
            &self.path,
        ))?;
        let id =
            EntryId::from_u128(u128::from_le_bytes(bytes[..16].try_into().map_err(
                |_| session_fault(smith::error::SessionCode::StoreProof, "short id"),
            )?));
        let parent =
            u128::from_le_bytes(bytes[16..32].try_into().map_err(|_| {
                session_fault(smith::error::SessionCode::StoreProof, "short parent")
            })?);
        let offset =
            u64::from_le_bytes(bytes[32..40].try_into().map_err(|_| {
                session_fault(smith::error::SessionCode::StoreProof, "short offset")
            })?);
        let parent_offset = u64::from_le_bytes(
            bytes[40..48]
                .try_into()
                .map_err(|_| session_fault(smith::error::SessionCode::StoreProof, "short hint"))?,
        );
        Ok(ProofEntry {
            id,
            parent: (parent != 0).then(|| EntryId::from_u128(parent)),
            offset,
            parent_offset: (parent_offset != 0).then_some(parent_offset),
            compaction: bytes[48] != 0,
        })
    }

    fn push(&mut self, entry: &ProofEntry) -> Result<()> {
        self.check_cancelled()?;
        self.file
            .seek(SeekFrom::Start(self.len * Self::WIDTH))
            .map_err(io_error(
                smith::error::StorageCode::StoreProofSeek,
                &self.path,
            ))?;
        self.file
            .write_all(&entry.id.as_u128().to_le_bytes())
            .map_err(io_error(
                smith::error::StorageCode::StoreProofWrite,
                &self.path,
            ))?;
        self.file
            .write_all(&entry.parent.map_or(0, |id| id.as_u128()).to_le_bytes())
            .map_err(io_error(
                smith::error::StorageCode::StoreProofWrite,
                &self.path,
            ))?;
        self.file
            .write_all(&entry.offset.to_le_bytes())
            .map_err(io_error(
                smith::error::StorageCode::StoreProofWrite,
                &self.path,
            ))?;
        self.file
            .write_all(&entry.parent_offset.unwrap_or(0).to_le_bytes())
            .map_err(io_error(
                smith::error::StorageCode::StoreProofWrite,
                &self.path,
            ))?;
        self.file
            .write_all(&[u8::from(entry.compaction)])
            .map_err(io_error(
                smith::error::StorageCode::StoreProofWrite,
                &self.path,
            ))?;
        self.len += 1;
        Ok(())
    }

    fn set_hint(&mut self, at: u64) -> Result<()> {
        self.check_cancelled()?;
        self.file
            .seek(SeekFrom::Start((self.len - 1) * Self::WIDTH + 40))
            .map_err(io_error(
                smith::error::StorageCode::StoreProofSeek,
                &self.path,
            ))?;
        self.file.write_all(&at.to_le_bytes()).map_err(io_error(
            smith::error::StorageCode::StoreProofWrite,
            &self.path,
        ))
    }

    fn find(&mut self, id: EntryId) -> Result<Option<ProofEntry>> {
        let mut found = None;
        for i in 0..self.len {
            self.check_cancelled()?;
            let record = self.get(i)?;
            if record.id == id {
                if found.is_some() {
                    return Err(session_fault(
                        smith::error::SessionCode::SessionDuplicateId,
                        format!("duplicate entry {id}"),
                    ));
                }
                found = Some(record);
            }
        }
        Ok(found)
    }

    fn at_offset(&mut self, offset: u64) -> Result<Option<ProofEntry>> {
        let (mut start, mut end) = (0, self.len);
        while start < end {
            self.check_cancelled()?;
            let middle = start + (end - start) / 2;
            let record = self.get(middle)?;
            match record.offset.cmp(&offset) {
                std::cmp::Ordering::Less => start = middle + 1,
                std::cmp::Ordering::Greater => end = middle,
                std::cmp::Ordering::Equal => return Ok(Some(record)),
            }
        }
        Ok(None)
    }

    fn parent(&mut self, child: &ProofEntry) -> Result<Option<ProofEntry>> {
        self.check_cancelled()?;
        let Some(id) = child.parent else {
            return Ok(None);
        };
        // The hint is usable only if it names a structurally proven entry,
        // matches the parent identity, and precedes the child. Identity lookup also
        // rejects duplicate IDs, including outside the selected branch.
        let hinted = child
            .parent_offset
            .and_then(|at| (at < child.offset).then_some(at));
        let target = hinted.map(|at| self.at_offset(at)).transpose()?.flatten();
        let found = self.find(id)?.ok_or_else(|| missing_entry(id))?;
        let parent = target
            .filter(|candidate| candidate.id == id && candidate.offset == found.offset)
            .unwrap_or(found);
        if parent.offset >= child.offset {
            return Err(session_fault(
                smith::error::SessionCode::SessionParent,
                "parent does not precede child",
            ));
        }
        Ok(Some(parent))
    }
}

fn completion_member(kind: &crate::session::EntryKind, content: &[u8]) -> Result<bool> {
    use crate::content_codec::EntryContentView;
    use crate::session::EntryKind;
    Ok(match kind {
        EntryKind::ToolResult { .. }
        | EntryKind::Message {
            role: smith::message::Role::Tool,
            ..
        } => true,
        EntryKind::Meta { compaction: false } => matches!(
            EntryContentView::decode(content)?,
            EntryContentView::Meta {
                kind: crate::session::TOOL_MUTATION_KIND | crate::metadata::NESTED_COMPLETION_KIND,
                ..
            }
        ),
        _ => false,
    })
}

fn prove_history(proof: &mut Proof, frame: &Frame, offset: u64) -> Result<Option<EntryId>> {
    let mut tip = None;
    for (offset, entry) in frame.positioned_entries(offset) {
        proof.push(&ProofEntry {
            id: entry.id,
            parent: entry.parent,
            offset,
            parent_offset: None,
            compaction: entry.kind == (crate::session::EntryKind::Meta { compaction: true }),
        })?;
        tip = Some(entry.id);
    }
    Ok(tip)
}

fn validate_completion_ancestor(
    kind: &crate::session::EntryKind,
    call_id: smith::id::ToolCallId,
    intent: &mut bool,
) -> Result<()> {
    use crate::session::EntryKind;
    match kind {
        EntryKind::ToolCall { call_id: found } if *found == call_id => {
            if *intent {
                return Err(admission_fault("completion has repeated tool intent"));
            }
            *intent = true;
        }
        EntryKind::ToolResult { call_id: found, .. } if *found == call_id => {
            return Err(admission_fault("tool completion already recorded"));
        }
        _ => {}
    }
    Ok(())
}

fn admission_fault(message: &str) -> SmithError {
    session_fault(smith::error::SessionCode::SessionIncompleteContext, message)
}

impl SessionReader {
    /// Reject execution startup while any durable submission remains pending.
    ///
    /// The scan retains at most one decoded frame, so it never materializes
    /// session history or exposes admitted input to an execution context.
    ///
    /// # Errors
    ///
    /// Returns an incomplete-context fault for a pending submission, or a
    /// storage or framing fault while scanning the pinned snapshot.
    pub fn reject_pending_admissions(&self, frame_bytes_max: usize) -> Result<()> {
        if !self.work_ledger(frame_bytes_max, None)?.live.is_empty() {
            return Err(admission_fault(
                "session has pending submission; settlement is required before execution",
            ));
        }
        Ok(())
    }

    /// Inspect one pending receipt with bounded frame residency and no execution.
    ///
    /// # Errors
    /// Returns storage, framing, or duplicate identity faults.
    pub fn receipt(
        &self,
        submission_id: EntryId,
        frame_bytes_max: usize,
    ) -> Result<Option<AdmissionReceipt>> {
        self.work_ledger(frame_bytes_max, Some(&submission_id))?;
        let header = self.header(frame_bytes_max)?;
        let mut receipt = None;
        self.scan_owned_reporting(
            frame_bytes_max,
            |frame| {
                if let Frame::Admission { entry, .. } = frame
                    && entry.id == submission_id
                {
                    if receipt.is_some() {
                        return Err(admission_fault(
                            "duplicate admission identity; verify the session",
                        ));
                    }
                    receipt = Some(AdmissionReceipt {
                        session_id: header.session_id,
                        submission_id,
                        destination: entry.parent,
                    });
                }
                Ok(true)
            },
            Err,
        )?;
        if let Some(receipt) = receipt {
            let (mut proof, _, _) = self.proof(frame_bytes_max, None)?;
            let admission = proof.find(receipt.submission_id)?.ok_or_else(|| {
                admission_fault("admission identity is absent from structural proof")
            })?;
            proof.parent(&admission)?;
        }
        Ok(receipt)
    }

    /// Validate required work transitions without scheduling or mutation.
    ///
    /// # Errors
    /// Returns storage, framing, ancestry, or work-state faults.
    pub fn validate_work(&self, frame_bytes_max: usize) -> Result<()> {
        self.proof(frame_bytes_max, None).map(|_| ())
    }

    /// Inspect durable status without scheduling or repairing work.
    ///
    /// # Errors
    /// Rejects invalid work transitions and damaged structural evidence.
    pub fn work_status(
        &self,
        submission_id: EntryId,
        frame_bytes_max: usize,
    ) -> Result<Option<WorkStatus>> {
        self.work_ledger(frame_bytes_max, Some(&submission_id))
            .map(|ledger| ledger.status)
    }

    /// Inspect a durable receipt and cancellation intent without executing work.
    ///
    /// # Errors
    /// Returns storage, framing, or work validation faults.
    pub fn inspect_work(
        &self,
        id: EntryId,
        frame_bytes_max: usize,
    ) -> Result<Option<crate::control::WorkReceipt>> {
        let Some(receipt) = self.receipt(id, frame_bytes_max)? else {
            return Ok(None);
        };
        let ledger = self.work_ledger(frame_bytes_max, Some(&id))?;
        let status = ledger
            .status
            .ok_or_else(|| admission_fault("admission has no work state"))?;
        Ok(Some(crate::control::WorkReceipt {
            receipt,
            status,
            cancel_requested: ledger.target_cancel_requested,
        }))
    }

    /// Read one complete redacted nested canonical value, inline or chunk-backed.
    /// Scans bounded frames; retains only this value (at most 32 MiB), never history.
    ///
    /// # Errors
    /// Rejects absent markers, damaged, incomplete, reordered, or cross-owner chunks.
    pub fn nested_payload(&self, id: EntryId, frame_bytes_max: usize) -> Result<String> {
        use crate::frame::NestedPayloadPhase;
        use smith::structured::{Kind, StructuredValue};
        self.validate_work(frame_bytes_max)?;
        let (entry, _) = self
            .find_entry(id, frame_bytes_max)?
            .ok_or_else(|| missing_entry(id))?;
        let crate::content_codec::EntryContentView::Meta { kind, detail } =
            crate::content_codec::EntryContentView::decode(&entry.content)?
        else {
            return Err(admission_fault("nested payload requires metadata"));
        };
        let (field, phase, effect) = match kind {
            crate::metadata::NESTED_INTENT_KIND => ("input", NestedPayloadPhase::Input, entry.id),
            crate::metadata::NESTED_COMPLETION_KIND => (
                "output",
                NestedPayloadPhase::Output,
                crate::metadata::nested_causality(detail)
                    .map_err(|_| admission_fault("invalid causal output"))?
                    .map(|causal| causal.effect_id)
                    .or(entry.parent)
                    .ok_or_else(|| admission_fault("nested output requires intent"))?,
            ),
            _ => return Err(admission_fault("entry has no nested payload")),
        };
        let value = detail
            .field(field)
            .map_err(|_| admission_fault("invalid payload"))?
            .ok_or_else(|| admission_fault("missing payload"))?;
        let Some(reference) = crate::metadata::nested_payload_ref(value)
            .map_err(|_| admission_fault("invalid payload reference"))?
        else {
            return match value
                .kind()
                .map_err(|_| admission_fault("invalid inline payload"))?
            {
                Kind::String(text) => Ok(text.to_owned()),
                _ => Err(admission_fault("invalid inline payload")),
            };
        };
        let identity = crate::metadata::nested_identity(detail)
            .map_err(|_| admission_fault("invalid payload owner"))?;
        let mut bytes = Vec::new();
        bytes
            .try_reserve_exact(reference.payload_bytes as usize)
            .map_err(|_| admission_fault("payload allocation failed"))?;
        self.scan_reporting(
            frame_bytes_max,
            |frame| {
                if let Frame::NestedPayload { chunk } = frame
                    && (chunk.submission_id, chunk.call_id, chunk.index) == identity
                    && chunk.effect_id == effect
                    && chunk.phase == phase
                {
                    if usize::from(chunk.ordinal)
                        != bytes
                            .len()
                            .div_ceil(crate::metadata::NESTED_CHUNK_BYTES_MAX)
                        || bytes.len() + chunk.bytes.len() > reference.payload_bytes as usize
                    {
                        return Err(admission_fault("invalid payload sequence"));
                    }
                    bytes.extend_from_slice(&chunk.bytes);
                }
                Ok(true)
            },
            Err,
        )?;
        if bytes.len() != reference.payload_bytes as usize {
            return Err(admission_fault("incomplete payload"));
        }
        String::from_utf8(bytes).map_err(|_| admission_fault("invalid UTF-8 payload"))
    }

    /// Inspect final assistant identity from an atomic terminal record.
    ///
    /// # Errors
    /// Returns storage, framing, or work-state faults without scheduling work.
    pub fn work_output(
        &self,
        submission_id: EntryId,
        frame_bytes_max: usize,
    ) -> Result<Option<EntryId>> {
        self.work_ledger(frame_bytes_max, Some(&submission_id))
            .map(|ledger| ledger.output)
    }

    fn work_ledger(&self, max: usize, target: Option<&EntryId>) -> Result<WorkLedger> {
        let (mut proof, _, _) = self.structural_proof(max, None)?;
        self.scan_work(max, target, &mut proof)
    }

    fn verify_submission_key(&self, key: &str, max: usize, scope: u64) -> Result<()> {
        let mut matches = 0usize;
        let mut origins = OriginScopes::default();
        let mut ignored = WorkLedger::default();
        self.scan_reporting(
            max,
            |frame| {
                origins.boundary(&frame, &mut ignored)?;
                if origins.current == scope
                    && let Frame::Admission {
                        key: Some(recorded),
                        ..
                    } = frame
                {
                    matches += usize::from(recorded == key);
                    if matches > 1 {
                        return Err(admission_fault("duplicate durable submission key"));
                    }
                }
                Ok(true)
            },
            Err,
        )?;
        Ok(())
    }

    fn scan_work(
        &self,
        max: usize,
        target: Option<&EntryId>,
        proof: &mut Proof,
    ) -> Result<WorkLedger> {
        let mut ledger = WorkLedger::default();
        let mut origins = OriginScopes::default();
        self.scan_reporting(
            max,
            |frame| {
                if origins.boundary(&frame, &mut ledger)? {
                    return Ok(true);
                }
                match &frame {
                    Frame::Commit {
                        checkpoint,
                        entries,
                    } => {
                        self.validate_completion(checkpoint, entries, &ledger, proof, max)?;
                    }
                    Frame::Admission { entry, key } => {
                        if let Some(key) = key {
                            self.verify_submission_key(key, max, origins.current)?;
                        }
                        let record = proof
                            .find(entry.id)?
                            .ok_or_else(|| missing_entry(entry.id))?;
                        proof.parent(&record)?;
                    }
                    Frame::Settlement {
                        submission_id,
                        output: Some(entry),
                        ..
                    } => {
                        let record = proof
                            .find(entry.id)?
                            .ok_or_else(|| missing_entry(entry.id))?;
                        let mut cursor = proof.parent(&record)?;
                        let mut belongs = false;
                        while let Some(parent) = cursor {
                            if ledger
                                .live
                                .iter()
                                .any(|(id, _)| *id == parent.id && id != submission_id)
                            {
                                return Err(admission_fault(
                                    "terminal branch includes another pending input",
                                ));
                            }
                            if &parent.id == submission_id {
                                belongs = true;
                                break;
                            }
                            cursor = proof.parent(&parent)?;
                        }
                        if !belongs {
                            return Err(admission_fault(
                                "terminal output does not descend from submission",
                            ));
                        }
                    }
                    _ => {}
                }
                if let Frame::Known { entry } = &frame {
                    authorize_lifecycle_root(
                        &mut ledger,
                        entry.parent.as_ref(),
                        &entry.content,
                        |id| {
                            let Some(record) = proof.find(id)? else {
                                return Ok(None);
                            };
                            let entry = self.entry_at(record.offset, max)?;
                            Ok(Some((
                                entry.parent,
                                matches!(
                                    entry.kind,
                                    crate::session::EntryKind::Message {
                                        role: smith::message::Role::User,
                                        ..
                                    }
                                ),
                            )))
                        },
                    )?;
                }
                ledger.apply(&frame, if origins.current == 0 { target } else { None })?;
                Ok(true)
            },
            Err,
        )?;
        origins.finish()?;
        Ok(ledger)
    }

    fn validate_completion(
        &self,
        checkpoint: &crate::frame::ToolCompletionCheckpoint,
        entries: &[EntryFrame; 3],
        ledger: &WorkLedger,
        proof: &mut Proof,
        limit: usize,
    ) -> Result<()> {
        crate::frame::validate_completion(checkpoint, entries)
            .map_err(|_| admission_fault("invalid completion members"))?;
        if ledger.unresolved() {
            return Err(admission_fault(
                "unresolved nested effect requires recovery",
            ));
        }
        if ledger.live.first() != Some(&(checkpoint.submission_id, WorkStatus::Running)) {
            return Err(admission_fault(
                "completion requires earliest claimed root work",
            ));
        }
        for entry in entries {
            // Finding each ID also rejects duplicates outside the selected branch.
            let _existing = proof.find(entry.id)?;
        }
        let mut parent = entries[0].parent;
        let mut intent = false;
        while let Some(id) = parent {
            let ancestor = proof.find(id)?.ok_or_else(|| missing_entry(id))?;
            if id == checkpoint.submission_id {
                if intent {
                    return Ok(());
                }
                break;
            }
            if ledger.live.iter().any(|(live, _)| *live == id) {
                return Err(admission_fault("completion includes another pending input"));
            }
            let prior = self.entry_at(ancestor.offset, limit)?;
            validate_completion_ancestor(&prior.kind, checkpoint.call_id, &mut intent)?;
            parent = proof.parent(&ancestor)?.map(|entry| entry.id);
        }
        Err(admission_fault(
            "completion requires its root and one preceding intent",
        ))
    }

    const fn snapshot_read(&self, at: u64) -> SnapshotRead<'_> {
        SnapshotRead {
            file: &self.file,
            at,
            end: self.snapshot_len,
        }
    }

    fn proof(
        &self,
        max: usize,
        cancel: Option<CancelHandle>,
    ) -> Result<(Proof, crate::session::SessionHeader, Option<EntryId>)> {
        let (mut proof, header, selected) = self.structural_proof(max, cancel)?;
        if proof.has_work {
            self.scan_work(max, None, &mut proof)?;
        }
        Ok((proof, header, selected))
    }

    fn structural_proof(
        &self,
        max: usize,
        cancel: Option<CancelHandle>,
    ) -> Result<(Proof, crate::session::SessionHeader, Option<EntryId>)> {
        let (path, file) = new_temp_file(
            &std::env::temp_dir().join("smith-proof"),
            "scan",
            SessionId::new(),
        )?;
        std::fs::remove_file(&path)
            .map_err(io_error(smith::error::StorageCode::StoreProofRemove, &path))?;
        let mut proof = Proof {
            file,
            path,
            len: 0,
            selected_checkpoint: None,
            has_work: false,
            cancel,
        };
        let mut header = None;
        let mut selected = None;
        let mut first = true;
        self.scan_metadata_positions(max, |offset, frame| {
            proof.check_cancelled()?;
            proof.has_work |= frame.requires_work_validation();
            match frame {
                Frame::Header { header: h } if first => header = Some(h),
                Frame::Header { .. } => {
                    return Err(session_fault(
                        smith::error::SessionCode::SessionHeaderDuplicate,
                        "duplicate header",
                    ));
                }
                ref history @ (Frame::Known { .. }
                | Frame::Admission { .. }
                | Frame::Settlement {
                    output: Some(_), ..
                }
                | Frame::Commit { .. }
                | Frame::NestedCommit { .. })
                    if header.is_some() =>
                {
                    selected = prove_history(&mut proof, history, offset)?;
                    proof.selected_checkpoint = None;
                }
                Frame::Index {
                    id,
                    offset: target,
                    parent,
                    parent_offset,
                } if header.is_some() => {
                    if let Some(previous) = (proof.len > 0)
                        .then(|| proof.get(proof.len - 1))
                        .transpose()?
                        && previous.id == id
                        && previous.offset == target
                        && previous.parent == parent
                        && let Some(parent_at) = parent_offset.filter(|at| *at < target)
                    {
                        proof.set_hint(parent_at)?;
                    }
                }
                Frame::Selection { id } if header.is_some() => {
                    selected = Some(id);
                    proof.selected_checkpoint = None;
                }
                Frame::Checkpoint { id, offset: target } if header.is_some() => {
                    if selected == Some(id) && target < offset {
                        proof.selected_checkpoint =
                            proof.at_offset(target)?.filter(|entry| entry.id == id);
                    }
                }
                Frame::Unknown { .. }
                | Frame::Origin { .. }
                | Frame::NestedPayload { .. }
                | Frame::Claim { .. }
                | Frame::CancelIntent { .. }
                | Frame::Settlement { output: None, .. }
                    if header.is_some() => {}
                _ => {
                    return Err(session_fault(
                        smith::error::SessionCode::SessionHeaderMissing,
                        "missing first header",
                    ));
                }
            }
            first = false;
            Ok(())
        })?;
        Ok((
            proof,
            header.ok_or_else(|| {
                session_fault(
                    smith::error::SessionCode::SessionHeaderMissing,
                    "missing first header",
                )
            })?,
            selected,
        ))
    }

    fn scan_metadata_positions(
        &self,
        max: usize,
        mut visit: impl FnMut(u64, Frame) -> Result<()>,
    ) -> Result<Recovery> {
        #[cfg(test)]
        METADATA_PASSES.with(|passes| passes.set(passes.get() + 1));
        let mut reader = BufReader::with_capacity(64 * 1024, self.snapshot_read(0));
        read_prologue(&mut reader)?;
        visit_metadata_reporting(
            &mut reader,
            max,
            |offset, frame| visit(offset + FILE_PROLOGUE.len() as u64, frame),
            |_| Ok(()),
        )
        .map(file_offsets)
    }

    fn source_snapshot(&self, snapshot_len: u64) -> Result<Self> {
        Ok(Self {
            file: self.file.try_clone().map_err(|error| {
                session_fault(
                    smith::error::SessionCode::SessionIncompleteContext,
                    error.to_string(),
                )
            })?,
            readers: None,
            snapshot_len,
            writer_active: self.writer_active,
        })
    }

    pub(crate) fn fork_context(
        &self,
        at: EntryId,
        tip: EntryId,
        bytes_max: usize,
    ) -> Result<Session> {
        let length = self
            .file
            .metadata()
            .map_err(|error| {
                session_fault(
                    smith::error::SessionCode::SessionIncompleteContext,
                    error.to_string(),
                )
            })?
            .len();
        let reader = self.source_snapshot(length)?;
        let mut retained = false;
        reader.replay_at(tip, bytes_max, |entry| {
            retained |= entry.id == at;
            Ok(())
        })?;
        if !retained {
            return Err(missing_entry(at));
        }
        reader.context_at(bytes_max, None, Some(&at))
    }

    // Raw inspection may include later acknowledged appends to the pinned inode.
    // This never changes the selected projection or its preceding-ancestry proof.
    pub(crate) fn appended_entry(
        &self,
        id: EntryId,
        bytes_max: usize,
    ) -> Result<Option<EntryFrame>> {
        let length = self
            .file
            .metadata()
            .map_err(|error| {
                session_fault(
                    smith::error::SessionCode::SessionIncompleteContext,
                    error.to_string(),
                )
            })?
            .len();
        if length < self.snapshot_len {
            return Err(crate::context::invalid(
                "pinned raw generation was truncated",
            ));
        }
        self.source_snapshot(length)?
            .find_entry(id, bytes_max)
            .map(|found| found.map(|(entry, _)| entry))
    }

    pub(crate) fn entry_at(&self, offset: u64, max: usize) -> Result<EntryFrame> {
        let mut file = self.snapshot_read(offset);
        let mut frame = None;
        let scan = visit_frames(&mut file, max, |found| {
            frame = Some(found);
            false
        })?;
        if let Some(fault) = scan.damage.into_iter().next() {
            return Err(fault);
        }
        match frame {
            Some(
                Frame::Known { entry }
                | Frame::Admission { entry, .. }
                | Frame::Settlement {
                    output: Some(entry),
                    ..
                },
            ) => Ok(entry),
            _ => Err(session_fault(
                smith::error::SessionCode::SessionParent,
                "entry boundary no longer contains entry",
            )),
        }
    }

    /// Scan structural frame boundaries from the fixed prologue, reporting
    /// absolute offsets without retaining a per-file index.
    fn scan_positions(
        &self,
        max: usize,
        mut visit: impl FnMut(u64, Frame) -> Result<()>,
    ) -> Result<Recovery> {
        struct Counted<'a, R> {
            inner: R,
            bytes: &'a std::cell::Cell<u64>,
        }
        impl<R: Read> Read for Counted<'_, R> {
            fn read(&mut self, buffer: &mut [u8]) -> std::io::Result<usize> {
                let n = self.inner.read(buffer)?;
                self.bytes.set(self.bytes.get() + n as u64);
                Ok(n)
            }
        }
        let bytes = std::cell::Cell::new(0);
        let mut reader = Counted {
            inner: BufReader::with_capacity(64 * 1024, self.snapshot_read(0)),
            bytes: &bytes,
        };
        read_prologue(&mut reader)?;
        let offset = std::cell::Cell::new(FILE_PROLOGUE.len() as u64);
        let mut failure = None;
        let mut damage = None;
        let mut scan = visit_frames_reporting(
            &mut reader,
            max,
            |frame| {
                let current = offset.replace(bytes.get());
                let result = match frame {
                    Frame::Commit { entries, .. } => {
                        let offsets = crate::frame::member_offsets(current, &entries);
                        offsets
                            .into_iter()
                            .zip(*entries)
                            .try_for_each(|(at, entry)| visit(at, Frame::Known { entry }))
                    }
                    Frame::NestedCommit { entry } => visit(
                        current + crate::frame::HEADER_LEN as u64 + 4,
                        Frame::Known { entry },
                    ),
                    frame => visit(current, frame),
                };
                match result {
                    Ok(()) => true,
                    Err(error) => {
                        failure = Some(error);
                        false
                    }
                }
            },
            |fault| {
                offset.set(bytes.get());
                if damage.is_none() {
                    damage = Some(fault);
                }
                true
            },
        )?;
        if let Some(error) = failure {
            return Err(error);
        }
        if let Some(error) = damage {
            scan.damage.push(error);
        }
        Ok(file_offsets(scan))
    }

    /// Find an entry identity by walking authoritative entry frames at structural
    /// boundaries; embedded indexes are hints, never the source of identity.
    ///
    /// # Errors
    /// Returns storage faults or a duplicate identity error.
    pub fn find_entry(&self, id: EntryId, max: usize) -> Result<Option<(EntryFrame, u64)>> {
        let mut found = None;
        self.scan_metadata_positions(max, |offset, frame| {
            for (offset, entry) in frame.positioned_entries(offset) {
                if entry.id != id {
                    continue;
                }
                if found.is_some() {
                    return Err(session_fault(
                        smith::error::SessionCode::SessionDuplicateId,
                        format!("duplicate entry {id}"),
                    ));
                }
                found = Some(offset);
            }
            Ok(())
        })?;
        found
            .map(|offset| self.entry_at(offset, max).map(|entry| (entry, offset)))
            .transpose()
    }

    /// Durable session and root-branch identity without materializing content.
    ///
    /// # Errors
    /// Returns a structural fault for an invalid or missing header.
    pub fn header(&self, max: usize) -> Result<crate::session::SessionHeader> {
        self.proof(max, None).map(|(_, header, _)| header)
    }

    /// Selected entry identity without materializing any content.
    ///
    /// # Errors
    /// Returns a structural fault for invalid selection or ancestry.
    pub fn selected_tip(&self, max: usize) -> Result<Option<EntryId>> {
        self.selected_tip_with_cancel(max, None)
    }

    /// Selected entry identity, checking cancellation at each bounded traversal boundary.
    ///
    /// # Errors
    /// Returns [`SmithError::Cancelled`] or a structural fault for invalid selection or ancestry.
    pub fn selected_tip_cancelled(
        &self,
        max: usize,
        cancel: &CancelHandle,
    ) -> Result<Option<EntryId>> {
        self.selected_tip_with_cancel(max, Some(cancel.clone()))
    }

    fn selected_tip_with_cancel(
        &self,
        max: usize,
        cancel: Option<CancelHandle>,
    ) -> Result<Option<EntryId>> {
        let (mut proof, _, selected) = self.proof(max, cancel)?;
        if let Some(id) = selected {
            proof.find(id)?.ok_or_else(|| missing_entry(id))?;
        }
        Ok(selected)
    }

    /// Selected effective context from latest compaction boundary to tip.
    /// Rootward ancestry is validated using a bounded, file-backed proof;
    /// only effective payloads become resident.
    ///
    /// # Errors
    /// Returns a fault for missing ancestry, invalid header or selection.
    pub fn selected_session(&self, max: usize) -> Result<Session> {
        self.selected_session_with_cancel(max, None)
    }

    fn selected_session_with_cancel(
        &self,
        max: usize,
        cancel: Option<CancelHandle>,
    ) -> Result<Session> {
        self.context_at(max, cancel, None)
    }

    fn context_at(
        &self,
        max: usize,
        cancel: Option<CancelHandle>,
        at: Option<&EntryId>,
    ) -> Result<Session> {
        let (mut proof, header, selected) = self.proof(max, cancel)?;
        let selected = at.copied().or(selected);
        let (scratch_path, mut offsets) = scratch_file("context")?;
        let mut length = 0u64;
        let mut has_edits = false;
        if let Some(id) = selected {
            let mut cursor = proof.find(id)?.ok_or_else(|| missing_entry(id))?;
            if let Some(hint) = proof
                .selected_checkpoint
                .filter(|hint| hint.id == id && hint.offset == cursor.offset)
            {
                cursor = hint;
                #[cfg(test)]
                CHECKPOINT_HITS.with(|hits| hits.set(hits.get() + 1));
            }
            let mut keep = true;
            loop {
                proof.check_cancelled()?;
                if keep {
                    has_edits |= self.entry_at(cursor.offset, max)?.content.first() == Some(&4);
                    offsets
                        .write_all(&cursor.offset.to_le_bytes())
                        .map_err(io_error(
                            smith::error::StorageCode::StoreScratchWrite,
                            &scratch_path,
                        ))?;
                    length += 1;
                    if cursor.compaction {
                        keep = false;
                    }
                }
                match proof.parent(&cursor)? {
                    Some(parent) => cursor = parent,
                    None => break,
                }
            }
        }
        let mut session = Session::from_chain(header, Vec::new())?;
        if has_edits {
            let reader = self.source_snapshot(self.snapshot_len)?;
            session.set_source(std::sync::Arc::new(reader), max);
        }
        for i in (0..length).rev() {
            proof.check_cancelled()?;
            offsets.seek(SeekFrom::Start(i * 8)).map_err(io_error(
                smith::error::StorageCode::StoreScratchSeek,
                &scratch_path,
            ))?;
            let mut bytes = [0; 8];
            offsets.read_exact(&mut bytes).map_err(io_error(
                smith::error::StorageCode::StoreScratchRead,
                &scratch_path,
            ))?;
            let offset = u64::from_le_bytes(bytes);
            let entry = self.entry_at(offset, max)?;
            if has_edits {
                session.push_sourced(&entry, offset)?;
            } else {
                session.push_restored(entry)?;
            }
        }
        Ok(session)
    }

    /// Replay a rooted chain in chronological order with bounded retained
    /// payload. One metadata pass validates structural offsets into a
    /// file-backed proof; parent lookups scan fixed-width proof records.
    ///
    /// # Errors
    /// Returns a missing-entry, ancestry, storage, or callback fault.
    pub fn replay_at(
        &self,
        id: EntryId,
        max: usize,
        visit: impl FnMut(EntryFrame) -> Result<()>,
    ) -> Result<()> {
        self.replay_at_with_cancel(id, max, None, visit)
    }

    /// Replay a rooted chain, observing cancellation between bounded reads.
    ///
    /// # Errors
    /// Returns [`SmithError::Cancelled`], a storage fault, or a callback fault.
    pub fn replay_at_cancelled(
        &self,
        id: EntryId,
        max: usize,
        cancel: &CancelHandle,
        visit: impl FnMut(EntryFrame) -> Result<()>,
    ) -> Result<()> {
        self.replay_at_with_cancel(id, max, Some(cancel.clone()), visit)
    }

    fn replay_at_with_cancel(
        &self,
        id: EntryId,
        max: usize,
        cancel: Option<CancelHandle>,
        mut visit: impl FnMut(EntryFrame) -> Result<()>,
    ) -> Result<()> {
        // Spill only physical addresses, never payloads. Unlink immediately:
        // the open descriptor owns the scratch lifetime even on early errors.
        let (mut proof, _, _) = self.proof(max, cancel)?;
        let (scratch_path, mut scratch) = scratch_file("replay")?;
        let mut cursor = proof.find(id)?.ok_or_else(|| missing_entry(id))?;
        let mut depth = 0u64;
        loop {
            proof.check_cancelled()?;
            scratch
                .write_all(&cursor.offset.to_le_bytes())
                .map_err(io_error(
                    smith::error::StorageCode::StoreScratchWrite,
                    &scratch_path,
                ))?;
            depth += 1;
            match proof.parent(&cursor)? {
                Some(parent) => cursor = parent,
                None => break,
            }
        }
        for position in (0..depth).rev() {
            proof.check_cancelled()?;
            scratch
                .seek(SeekFrom::Start(position * 8))
                .map_err(io_error(
                    smith::error::StorageCode::StoreScratchSeek,
                    &scratch_path,
                ))?;
            let mut address = [0; 8];
            scratch.read_exact(&mut address).map_err(io_error(
                smith::error::StorageCode::StoreScratchRead,
                &scratch_path,
            ))?;
            visit(self.entry_at(u64::from_le_bytes(address), max)?)?;
        }
        Ok(())
    }

    /// Fork one structurally reachable chain to a new independently named file.
    ///
    /// # Errors
    /// Returns a missing-entry, ancestry, publication or storage fault.
    pub fn fork_at(&self, id: EntryId, path: &Path, config: Config) -> Result<OpenSession> {
        self.fork_at_with_cancel(id, path, config, None)
    }

    /// Fork one rooted chain, observing cancellation between bounded traversal work.
    ///
    /// # Errors
    /// Returns [`SmithError::Cancelled`], a storage fault, or a publication fault.
    pub fn fork_at_cancelled(
        &self,
        id: EntryId,
        path: &Path,
        config: Config,
        cancel: &CancelHandle,
    ) -> Result<OpenSession> {
        self.fork_at_with_cancel(id, path, config, Some(cancel.clone()))
    }

    fn fork_at_with_cancel(
        &self,
        id: EntryId,
        path: &Path,
        config: Config,
        cancel: Option<CancelHandle>,
    ) -> Result<OpenSession> {
        if cancel.as_ref().is_some_and(CancelHandle::is_cancelled) {
            return Err(SmithError::Cancelled);
        }
        config.validate()?;
        let (mut proof, source_header, _) = self.proof(config.frame_bytes_max, cancel.clone())?;
        let mut selected = proof.find(id)?.ok_or_else(|| missing_entry(id))?;
        while let Some(parent) = proof.parent(&selected)? {
            selected = parent;
        }
        let inherited_work = proof.has_work;
        let source = path
            .file_stem()
            .and_then(|stem| stem.to_str())
            .and_then(|stem| stem.parse::<SessionId>().ok())
            .map_or_else(Session::new, Session::new_with_id);
        let lock = SessionLock::acquire(path)?;
        let target = lock.path().to_path_buf();
        validate_named_identity(&target, source.id())?;
        reject_existing_target(&target)?;
        let (temporary, mut out) = new_temp_file(&target, "fork", source.id())?;
        publication_checkpoint!(TempCreated);
        let written = (|| {
            out.write_all(&FILE_PROLOGUE)
                .map_err(io_error(smith::error::StorageCode::CreateWrite, &temporary))?;
            publication_checkpoint!(PartialWrite);
            write_frame(
                &mut out,
                &Frame::Header {
                    header: source.header(),
                },
                config.frame_bytes_max,
            )?;
            if inherited_work {
                self.copy_inherited_history(
                    &mut out,
                    id,
                    source_header.session_id,
                    config.frame_bytes_max,
                    cancel.as_ref(),
                )?;
            } else {
                self.replay_at_with_cancel(id, config.frame_bytes_max, cancel.clone(), |entry| {
                    write_frame(&mut out, &Frame::Known { entry }, config.frame_bytes_max)
                })?;
            }
            publication_checkpoint!(CompletedWrite);
            out.sync_all()
                .map_err(io_error(smith::error::StorageCode::CreateSync, &temporary))?;
            publication_checkpoint!(TempSynced);
            Ok(())
        })();
        drop(out);
        if let Err(error) = written {
            // Preserve the write failure; temporary-file removal is best-effort cleanup.
            let _cleanup_result: std::io::Result<()> = std::fs::remove_file(&temporary);
            return Err(error);
        }
        publish_no_clobber(&temporary, &target)?;
        publication_checkpoint!(Cleanup);
        let (writer, recovery) = SessionWriter::attach(target, config, lock)?;
        let session = Self::open(writer.path())?
            .selected_session_with_cancel(writer.config.frame_bytes_max, cancel)?;
        Ok(OpenSession {
            session,
            writer,
            recovery,
        })
    }

    /// Copy complete atomic boundaries through the chosen member, not later source work.
    fn copy_inherited_history(
        &self,
        out: &mut File,
        id: EntryId,
        source: SessionId,
        frame_bytes_max: usize,
        cancel: Option<&CancelHandle>,
    ) -> Result<()> {
        write_frame(
            out,
            &Frame::Origin {
                source,
                begin: true,
            },
            frame_bytes_max,
        )?;
        let mut origins = OriginScopes::default();
        let mut ignored = WorkLedger::default();
        self.scan_reporting(
            frame_bytes_max,
            |frame| {
                if cancel.is_some_and(CancelHandle::is_cancelled) {
                    return Err(SmithError::Cancelled);
                }
                if matches!(
                    frame,
                    Frame::Header { .. }
                        | Frame::Index { .. }
                        | Frame::Checkpoint { .. }
                        | Frame::Selection { .. }
                ) {
                    return Ok(true);
                }
                origins.boundary(&frame, &mut ignored)?;
                if origins.parents.len() >= ORIGIN_DEPTH_MAX {
                    return Err(admission_fault("fork exceeds source origin nesting bound"));
                }
                let selected = frame.entries().iter().any(|entry| entry.id == id);
                write_frame(out, &frame, frame_bytes_max)?;
                Ok(!selected)
            },
            Err,
        )?;
        // Selecting inherited history can stop inside a transitive scope.
        for (source, _, _) in origins.parents.iter().rev() {
            write_frame(
                out,
                &Frame::Origin {
                    source: *source,
                    begin: false,
                },
                frame_bytes_max,
            )?;
        }
        write_frame(
            out,
            &Frame::Origin {
                source,
                begin: false,
            },
            frame_bytes_max,
        )?;
        write_frame(out, &Frame::Selection { id }, frame_bytes_max)
    }

    #[expect(
        clippy::large_types_passed_by_value,
        reason = "Copy IDs and offsets are compared once while validating an index record"
    )]
    fn verify_index(
        &self,
        last: Option<(EntryId, u64, Option<EntryId>)>,
        id: EntryId,
        target: u64,
        parent: Option<EntryId>,
        parent_offset: Option<u64>,
        max: usize,
    ) -> Result<()> {
        if last != Some((id, target, parent)) {
            return Err(session_fault(
                smith::error::SessionCode::SessionIndex,
                "index target is not preceding entry boundary",
            ));
        }
        if let Some(parent) = parent {
            let (_, actual) = self
                .find_entry(parent, max)?
                .ok_or_else(|| missing_entry(parent))?;
            if parent_offset != Some(actual) || actual >= target {
                return Err(session_fault(
                    smith::error::SessionCode::SessionIndex,
                    "index parent offset or identity mismatch",
                ));
            }
        } else if parent_offset.is_some() {
            return Err(session_fault(
                smith::error::SessionCode::SessionIndex,
                "root index has parent offset",
            ));
        }
        Ok(())
    }

    /// Check every frame and content body in the pinned snapshot, including
    /// unrelated branches and all embedded location hints.
    ///
    /// # Errors
    /// Reports damaged frames, invalid ancestry/offsets, or a torn tail.
    #[expect(
        clippy::too_many_lines,
        reason = "full verification keeps one frame walk and its navigation proof together"
    )]
    pub fn verify_full(&self, max: usize) -> Result<()> {
        self.work_ledger(max, None)?;
        let mut first = true;
        let mut last_entry = None;
        let scan = self.scan_positions(max, |offset, frame| {
            match frame {
                Frame::Header { .. } if first => {}
                Frame::Header { .. } => {
                    return Err(session_fault(
                        smith::error::SessionCode::SessionHeaderDuplicate,
                        "duplicate header",
                    ));
                }
                Frame::Known { entry }
                | Frame::Admission { entry, .. }
                | Frame::Settlement {
                    output: Some(entry),
                    ..
                } if !first => {
                    // Full verification rejects duplicate identities even when the
                    // selected branch never references either copy.
                    self.find_entry(entry.id, max)?
                        .ok_or_else(|| missing_entry(entry.id))?;
                    let content = crate::content_codec::EntryContentView::decode(&entry.content)?;
                    if content.kind() != entry.kind {
                        return Err(session_fault(
                            smith::error::SessionCode::EntryKindMismatch,
                            format!("entry {} kind mismatch", entry.id),
                        ));
                    }
                    if let Some(parent) = entry.parent {
                        let (_, parent_offset) = self
                            .find_entry(parent, max)?
                            .ok_or_else(|| missing_entry(parent))?;
                        if parent_offset >= offset {
                            return Err(session_fault(
                                smith::error::SessionCode::SessionParent,
                                "parent does not precede child",
                            ));
                        }
                    }
                    last_entry = Some((entry.id, offset, entry.parent));
                }
                Frame::Index {
                    id,
                    offset: target,
                    parent,
                    parent_offset,
                } if !first => {
                    self.verify_index(last_entry, id, target, parent, parent_offset, max)?;
                    last_entry = None;
                }
                Frame::Selection { id } if !first => {
                    self.find_entry(id, max)?.ok_or_else(|| missing_entry(id))?;
                    last_entry = None;
                }
                Frame::Checkpoint { id, offset: target } if !first => {
                    if self
                        .find_entry(id, max)?
                        .is_none_or(|(_, actual)| actual != target)
                        || target >= offset
                    {
                        return Err(session_fault(
                            smith::error::SessionCode::SessionCheckpoint,
                            "checkpoint target is not an earlier entry boundary",
                        ));
                    }
                    last_entry = None;
                }
                Frame::Unknown { .. }
                | Frame::Origin { .. }
                | Frame::NestedPayload { .. }
                | Frame::Claim { .. }
                | Frame::CancelIntent { .. }
                | Frame::Settlement { output: None, .. }
                    if !first =>
                {
                    last_entry = None;
                }
                _ => {
                    return Err(session_fault(
                        smith::error::SessionCode::SessionHeaderMissing,
                        "missing first header",
                    ));
                }
            }
            first = false;
            Ok(())
        })?;
        if first {
            return Err(session_fault(
                smith::error::SessionCode::SessionHeaderMissing,
                "missing first header",
            ));
        }
        if let Some(fault) = scan.damage.into_iter().next() {
            return Err(fault);
        }
        if scan.torn_tail_at.is_some() {
            return Err(session_fault(
                smith::error::SessionCode::SessionTorn,
                "incomplete tail",
            ));
        }
        Ok(())
    }

    /// Open without taking the writer lock or modifying session content.
    ///
    /// # Errors
    /// Returns an input/output error for missing data or failed coordination.
    pub fn open(path: &Path) -> Result<Self> {
        Self::open_with_cancel(path, None)
    }

    /// Open a reader snapshot, observing cancellation while maintenance holds the reader lock.
    ///
    /// # Errors
    /// Returns [`SmithError::Cancelled`] or an input/output error for failed coordination.
    pub fn open_cancelled(path: &Path, cancel: &CancelHandle) -> Result<Self> {
        Self::open_with_cancel(path, Some(cancel))
    }

    fn open_with_cancel(path: &Path, cancel: Option<&CancelHandle>) -> Result<Self> {
        let path = canonical_session_path(path)?;
        let readers = OpenOptions::new()
            .read(true)
            .write(true)
            .create(true)
            .truncate(false)
            .open(readers_path(&path))
            .map_err(io_error(
                smith::error::StorageCode::StoreReaderLockOpen,
                &readers_path(&path),
            ))?;
        if let Some(cancel) = cancel {
            loop {
                if cancel.is_cancelled() {
                    return Err(SmithError::Cancelled);
                }
                match fs2::FileExt::try_lock_shared(&readers) {
                    Ok(()) => break,
                    Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
                        std::thread::sleep(std::time::Duration::from_millis(10));
                    }
                    Err(error) => {
                        return Err(io_error(
                            smith::error::StorageCode::StoreReaderLock,
                            &readers_path(&path),
                        )(error));
                    }
                }
            }
        } else {
            fs2::FileExt::lock_shared(&readers).map_err(io_error(
                smith::error::StorageCode::StoreReaderLock,
                &readers_path(&path),
            ))?;
        }
        let file =
            File::open(&path).map_err(io_error(smith::error::StorageCode::StoreOpen, &path))?;
        let snapshot_len = file
            .metadata()
            .map_err(io_error(smith::error::StorageCode::StoreStat, &path))?
            .len();
        let writer_active = writer_active(&path)?;
        Ok(Self {
            file,
            readers: Some(readers),
            snapshot_len,
            writer_active,
        })
    }

    /// Visit a consistent file-size snapshot with per-frame bounded allocation.
    ///
    /// # Errors
    /// Returns an I/O error or the visitor's error.
    pub fn scan(
        &self,
        frame_bytes_max: usize,
        mut visit: impl FnMut(Frame) -> Result<()>,
    ) -> Result<Recovery> {
        let mut reader = BufReader::with_capacity(64 * 1024, self.snapshot_read(0));
        read_prologue(&mut reader)?;
        let mut failure = None;
        let scan = visit_frames(&mut reader, frame_bytes_max, |frame| match visit(frame) {
            Ok(()) => true,
            Err(error) => {
                failure = Some(error);
                false
            }
        });
        let scan = file_offsets(scan?);
        if let Some(error) = failure {
            return Err(error);
        }
        Ok(scan)
    }

    /// Decode the first frame only, without reading the history.
    ///
    /// # Errors
    /// Returns an I/O error when the file cannot be read.
    pub fn first(&self, frame_bytes_max: usize) -> Result<(Option<Frame>, Recovery)> {
        let first_limit = u64::try_from(frame_bytes_max)
            .unwrap_or(u64::MAX)
            .saturating_add(
                u64::try_from(
                    FILE_PROLOGUE.len() + crate::frame::HEADER_LEN + crate::frame::BODY_PREFIX_LEN,
                )
                .unwrap_or(u64::MAX),
            )
            .min(self.snapshot_len);
        let mut reader = BufReader::new(self.snapshot_read(0).take(first_limit));
        read_prologue(&mut reader)?;
        let mut first = None;
        let scan = visit_frames(&mut reader, frame_bytes_max, |frame| {
            first = Some(frame);
            false
        })?;
        Ok((first, file_offsets(scan)))
    }

    /// Whether a writer owned this session when this reader acquired its snapshot.
    #[must_use]
    pub const fn writer_active(&self) -> bool {
        self.writer_active
    }

    /// File size of the pinned generation at reader acquisition.
    #[must_use]
    pub const fn file_size(&self) -> u64 {
        self.snapshot_len
    }

    /// Visit only containing-session records; source scopes remain available through raw scans.
    fn scan_owned_reporting(
        &self,
        frame_bytes_max: usize,
        mut visit: impl FnMut(Frame) -> Result<bool>,
        report_damage: impl FnMut(SmithError) -> Result<()>,
    ) -> Result<Recovery> {
        let mut origins = OriginScopes::default();
        let mut ignored = WorkLedger::default();
        let recovery = self.scan_reporting(
            frame_bytes_max,
            |frame| {
                if origins.boundary(&frame, &mut ignored)? || origins.current != 0 {
                    return Ok(true);
                }
                visit(frame)
            },
            report_damage,
        )?;
        origins.finish()?;
        Ok(recovery)
    }

    /// Scan a snapshot while reporting damage through `report_damage`.
    ///
    /// Unlike [`SessionReader::scan`], this method retains no damage, keeping
    /// callers that report or reject faults incrementally bounded.
    ///
    /// # Errors
    /// Returns an I/O error, visitor error, or damage-reporting error.
    pub fn scan_reporting(
        &self,
        frame_bytes_max: usize,
        mut visit: impl FnMut(Frame) -> Result<bool>,
        mut report_damage: impl FnMut(SmithError) -> Result<()>,
    ) -> Result<Recovery> {
        let mut reader = BufReader::with_capacity(64 * 1024, self.snapshot_read(0));
        read_prologue(&mut reader)?;
        let failure = std::cell::RefCell::new(None);
        let scan = visit_frames_reporting(
            &mut reader,
            frame_bytes_max,
            |frame| match visit(frame) {
                Ok(keep_going) => keep_going,
                Err(error) => {
                    *failure.borrow_mut() = Some(error);
                    false
                }
            },
            |damage| match report_damage(shift_damage(damage)) {
                Ok(()) => true,
                Err(error) => {
                    *failure.borrow_mut() = Some(error);
                    false
                }
            },
        )?;
        if let Some(error) = failure.into_inner() {
            return Err(error);
        }
        Ok(file_offsets(scan))
    }
}

/// Repair a session file by republishing only its complete frames.
///
/// Damaged frames are dropped; [`Recovery::damage_count`] counts all faults
/// while [`Recovery::damage`] retains only the first report.
/// An explicit selection whose entry is dropped fails before publication.
/// The original content stays intact if any step fails before publication.
/// Repair takes the session lock, so it waits for a live writer to finish
/// instead of replacing the file underneath it.
///
/// # Errors
///
/// Returns a locking, framing, or input/output error.
pub fn repair_session(path: &Path, frame_bytes_max: usize) -> Result<Recovery> {
    let lock = SessionLock::acquire(path)?;
    let path = lock.path();
    {
        let reader = SessionReader::open(path)?;
        let mut has_work = false;
        reader.scan_reporting(
            frame_bytes_max,
            |frame| {
                has_work |= frame.requires_work_validation();
                Ok(true)
            },
            |_| Ok(()),
        )?;
        if has_work {
            reader.validate_work(frame_bytes_max)?;
        }
    }
    let _coordination = maintenance_lock(path)?;
    let (temporary, mut out) = new_temp_file(path, "repair", SessionId::new())?;
    publication_checkpoint!(TempCreated);
    let written = (|| {
        out.write_all(&FILE_PROLOGUE)
            .map_err(io_error(smith::error::StorageCode::RepairWrite, &temporary))?;
        publication_checkpoint!(PartialWrite);
        let (mut recovery, selection, first_damage) =
            copy_repairable_frames(&mut out, path, frame_bytes_max)?;
        finish_repair_frames(
            &temporary,
            &mut out,
            selection.as_ref(),
            &mut recovery,
            first_damage,
            frame_bytes_max,
        )?;
        publication_checkpoint!(CompletedWrite);
        out.sync_all()
            .map_err(io_error(smith::error::StorageCode::RepairSync, &temporary))?;
        publication_checkpoint!(TempSynced);
        Ok(file_offsets(recovery))
    })();
    drop(out);
    let recovery = finish_repair_write(&temporary, written)?;
    if let Err(error) = std::fs::rename(&temporary, path) {
        // Preserve the publish failure; temporary-file removal is best-effort cleanup.
        let _cleanup_result: std::io::Result<()> = std::fs::remove_file(&temporary);
        return Err(io_error(smith::error::StorageCode::RepairPublish, path)(
            error,
        ));
    }
    publication_checkpoint!(Published);
    sync_parent(path)?;
    publication_checkpoint!(ParentSynced);
    // `rename` removed the temporary name as it published the replacement.
    publication_checkpoint!(Cleanup);
    drop(lock);
    Ok(recovery)
}

fn copy_repairable_frames(
    out: &mut File,
    path: &Path,
    frame_bytes_max: usize,
) -> Result<(Recovery, Option<EntryId>, Option<SmithError>)> {
    let mut source = BufReader::with_capacity(
        64 * 1024,
        File::open(path).map_err(io_error(smith::error::StorageCode::StoreOpen, path))?,
    );
    read_prologue(&mut source)?;
    let mut last = None;
    let mut count = 0u16;
    let mut selection = None;
    let mut has_header = false;
    let mut has_work = false;
    let mut first_damage = None;
    let mut failure = None;
    let recovery = visit_frames_reporting(
        &mut source,
        frame_bytes_max,
        |frame| {
            let result = (|| {
                match frame {
                    Frame::Index { .. } | Frame::Checkpoint { .. } => {}
                    Frame::Selection { id } => selection = Some(id),
                    Frame::Header { header } => {
                        has_header = true;
                        write_frame(out, &Frame::Header { header }, frame_bytes_max)?;
                    }
                    Frame::Known { entry } => repair_entry(
                        out,
                        path,
                        entry,
                        frame_bytes_max,
                        has_header,
                        &mut last,
                        &mut count,
                    )?,
                    admission @ Frame::Admission { .. } => {
                        has_work = true;
                        // Preserve the semantic boundary and key, not a flattened input.
                        if !has_header {
                            return Err(admission_fault("admission precedes session header"));
                        }
                        let offset = out
                            .stream_position()
                            .map_err(io_error(smith::error::StorageCode::StoreSeek, path))?;
                        if let Frame::Admission { entry, .. } = &admission {
                            last = Some((entry.id, offset));
                        }
                        write_frame(out, &admission, frame_bytes_max)?;
                    }
                    work @ (Frame::Claim { .. }
                    | Frame::CancelIntent { .. }
                    | Frame::Settlement { .. }
                    | Frame::Commit { .. }
                    | Frame::NestedCommit { .. }
                    | Frame::NestedPayload { .. }
                    | Frame::Origin { .. }) => {
                        has_work = true;
                        let offset = out
                            .stream_position()
                            .map_err(io_error(smith::error::StorageCode::StoreSeek, path))?;
                        if let Some((at, entry)) = work.positioned_entries(offset).last() {
                            last = Some((entry.id, at));
                        }
                        write_frame(out, &work, frame_bytes_max)?;
                    }
                    other @ Frame::Unknown { .. } => write_frame(out, &other, frame_bytes_max)?,
                }
                Ok(())
            })();
            if let Err(error) = result {
                failure = Some(error);
                false
            } else {
                true
            }
        },
        |damage| {
            if first_damage.is_none() {
                first_damage = Some(shift_damage(damage));
            }
            true
        },
    )?;
    if let Some(error) = failure {
        return Err(error);
    }
    if has_work && first_damage.is_some() {
        return Err(admission_fault(
            "damaged work evidence cannot be dropped by repair; retain source for explicit recovery",
        ));
    }
    Ok((recovery, selection, first_damage))
}

fn finish_repair_frames(
    temporary: &Path,
    out: &mut File,
    selection: Option<&EntryId>,
    recovery: &mut Recovery,
    first_damage: Option<SmithError>,
    frame_bytes_max: usize,
) -> Result<()> {
    finish_repair_selection(temporary, out, selection, frame_bytes_max)?;
    if let Some(damage) = first_damage {
        recovery.damage.push(damage);
    }
    Ok(())
}

fn finish_repair_write(temporary: &Path, written: Result<Recovery>) -> Result<Recovery> {
    match written {
        Ok(recovery) => Ok(recovery),
        Err(error) => {
            // Preserve the recovery failure; temporary-file removal is best-effort cleanup.
            let _cleanup_result: std::io::Result<()> = std::fs::remove_file(temporary);
            Err(error)
        }
    }
}

fn repair_entry(
    out: &mut File,
    path: &Path,
    entry: EntryFrame,
    max: usize,
    has_header: bool,
    last: &mut Option<(EntryId, u64)>,
    count: &mut u16,
) -> Result<()> {
    let offset = out
        .stream_position()
        .map_err(io_error(smith::error::StorageCode::RepairSeek, path))?;
    let id = entry.id;
    let parent = entry.parent;
    write_frame(out, &Frame::Known { entry }, max)?;
    let parent_offset =
        parent.and_then(|parent| last.filter(|(id, _)| *id == parent).map(|(_, at)| at));
    *last = Some((id, offset));
    if has_header && (parent.is_none() || parent_offset.is_some()) && max >= 48 {
        out.write_all(&index_bytes(id, offset, parent, parent_offset))
            .map_err(io_error(smith::error::StorageCode::RepairWrite, path))?;
    }
    *count += 1;
    if has_header && *count == 64 && max >= 24 {
        write_frame(out, &Frame::Checkpoint { id, offset }, max)?;
        *count = 0;
    }
    Ok(())
}

fn maintenance_lock(path: &Path) -> Result<File> {
    let file = OpenOptions::new()
        .read(true)
        .write(true)
        .create(true)
        .truncate(false)
        .open(readers_path(path))
        .map_err(io_error(
            smith::error::StorageCode::StoreReaderLockOpen,
            &readers_path(path),
        ))?;
    fs2::FileExt::try_lock_exclusive(&file).map_err(io_error(
        smith::error::StorageCode::StoreReadersActive,
        &readers_path(path),
    ))?;
    Ok(file)
}

fn finish_repair_selection(
    path: &Path,
    out: &mut File,
    selection: Option<&EntryId>,
    max: usize,
) -> Result<()> {
    let Some(&id) = selection else {
        return Ok(());
    };
    let mut source = BufReader::new(
        File::open(path).map_err(io_error(smith::error::StorageCode::RepairOpen, path))?,
    );
    read_prologue(&mut source)?;
    let mut found = None;
    visit_metadata_reporting(
        &mut source,
        max,
        |at, frame| {
            for (at, entry) in frame.positioned_entries(at + FILE_PROLOGUE.len() as u64) {
                if entry.id == id {
                    found = Some(at);
                }
            }
            Ok(())
        },
        |_| Ok(()),
    )?;
    let offset = found.ok_or_else(|| missing_entry(id))?;
    write_frame(out, &Frame::Selection { id }, max)?;
    if max >= 24 {
        write_frame(out, &Frame::Checkpoint { id, offset }, max)?;
    }
    Ok(())
}

fn recovery_checkpoint_count(file: &File, path: &Path, max: usize) -> Result<u16> {
    let mut reader = BufReader::new(
        file.try_clone()
            .map_err(io_error(smith::error::StorageCode::StoreOpen, path))?,
    );
    reader
        .seek(SeekFrom::Start(0))
        .map_err(io_error(smith::error::StorageCode::StoreSeek, path))?;
    read_prologue(&mut reader)?;
    let (path, file) = scratch_file("cadence")?;
    let mut proof = Proof {
        file,
        path,
        len: 0,
        selected_checkpoint: None,
        has_work: false,
        cancel: None,
    };
    let mut count = 0;
    visit_metadata_reporting(
        &mut reader,
        max,
        |offset, frame| {
            match frame {
                ref history @ (Frame::Known { .. }
                | Frame::Admission { .. }
                | Frame::Settlement {
                    output: Some(_), ..
                }
                | Frame::Commit { .. }
                | Frame::NestedCommit { .. }) => {
                    for (offset, entry) in
                        history.positioned_entries(offset + FILE_PROLOGUE.len() as u64)
                    {
                        proof.push(&ProofEntry {
                            id: entry.id,
                            parent: entry.parent,
                            offset,
                            parent_offset: None,
                            compaction: false,
                        })?;
                        count = (count + 1) % 64;
                    }
                }
                Frame::Checkpoint { id, offset: at }
                    if proof.at_offset(at)?.is_some_and(|entry| entry.id == id) =>
                {
                    count = 0;
                }
                _ => {}
            }
            Ok(())
        },
        |_| Ok(()),
    )?;
    Ok(count)
}

/// Walk an already-open file from its start using the shared frame reader.
///
/// # Errors
///
/// Returns an input/output error when the file cannot be re-read.
fn update_lifecycle_open(open: &mut bool, content: &[u8]) {
    if !matches!(
        crate::content_codec::metadata_name(content),
        Ok(Some(
            crate::metadata::lifecycle::INVOCATION_INTENT
                | crate::metadata::lifecycle::INVOCATION_COMPLETION
        ))
    ) {
        return;
    }
    if let Ok(crate::content_codec::EntryContentView::Meta { kind, .. }) =
        crate::content_codec::EntryContentView::decode(content)
    {
        match kind {
            crate::metadata::lifecycle::INVOCATION_INTENT => *open = true,
            crate::metadata::lifecycle::INVOCATION_COMPLETION => *open = false,
            _ => {}
        }
    }
}

fn walk_file_bounded(file: &File, path: &Path, frame_bytes_max: usize) -> Result<(Recovery, bool)> {
    let mut handle = file
        .try_clone()
        .map_err(io_error(smith::error::StorageCode::StoreOpen, path))?;
    handle
        .seek(SeekFrom::Start(0))
        .map_err(io_error(smith::error::StorageCode::StoreSeek, path))?;
    let mut reader = BufReader::with_capacity(64 * 1024, handle);
    read_prologue(&mut reader)?;
    let mut damage = None;
    let mut lifecycle_open = false;
    let mut recovery = visit_frames_reporting(
        &mut reader,
        frame_bytes_max,
        |frame| {
            if let Frame::Known { entry } = frame {
                update_lifecycle_open(&mut lifecycle_open, &entry.content);
            }
            true
        },
        |fault| {
            if damage.is_none() {
                damage = Some(fault);
            }
            true
        },
    )
    .map(file_offsets)?;
    if let Some(fault) = damage {
        recovery.damage.push(shift_damage(fault));
    }
    Ok((recovery, lifecycle_open))
}

fn read_prologue(reader: &mut impl Read) -> Result<()> {
    let mut magic = [0; FILE_PROLOGUE.len()];
    reader.read_exact(&mut magic).map_err(io_error(
        smith::error::StorageCode::SessionPrologue,
        Path::new("<session>"),
    ))?;
    if magic != FILE_PROLOGUE {
        return Err(SmithError::Session {
            code: smith::error::SessionCode::SessionPrologue,
            message: "invalid session format or version; expected SMH3 prologue".into(),
        });
    }
    Ok(())
}

fn file_offsets(mut recovery: Recovery) -> Recovery {
    recovery.good_end += FILE_PROLOGUE.len() as u64;
    recovery.torn_tail_at = recovery
        .torn_tail_at
        .map(|n| n + FILE_PROLOGUE.len() as u64);
    for damage in &mut recovery.damage {
        if let SmithError::Frame {
            offset: Some(n), ..
        } = damage
        {
            *n += FILE_PROLOGUE.len() as u64;
        }
    }
    recovery
}

const fn shift_damage(mut damage: SmithError) -> SmithError {
    if let SmithError::Frame {
        offset: Some(n), ..
    } = &mut damage
    {
        *n += FILE_PROLOGUE.len() as u64;
    }
    damage
}

/// Rename a synced temporary file into an absent target without any fallback.
///
/// `renamore::rename_exclusive` is `renameat2(RENAME_NOREPLACE)` on Linux,
/// `renamex_np(RENAME_EXCL)` on macOS, and `MoveFileExW` without replace flags
/// on Windows. Unsupported filesystems fail rather than weakening no-clobber.
fn publish_no_clobber(temporary: &Path, target: &Path) -> Result<()> {
    renamore::rename_exclusive(temporary, target)
        .map_err(io_error(smith::error::StorageCode::CreatePublish, target))?;
    publication_checkpoint!(Published);
    sync_parent(target)?;
    publication_checkpoint!(ParentSynced);
    Ok(())
}

fn sync_parent(path: &Path) -> Result<()> {
    let parent = path
        .parent()
        .filter(|p| !p.as_os_str().is_empty())
        .unwrap_or_else(|| Path::new("."));
    #[cfg(test)]
    if PARENT_SYNC_FAILURE.with(std::cell::Cell::get) {
        return Err(published_parent_sync_error(
            parent,
            "injected parent directory sync failure",
        ));
    }
    sync_directory(parent).map_err(|error| published_parent_sync_error(parent, error))
}

fn published_parent_sync_error(path: &Path, error: impl std::fmt::Display) -> SmithError {
    SmithError::Storage {
        code: smith::error::StorageCode::StoreDirSync,
        operation: smith::error::StorageOperation::SyncParentDirectoryAfterPublication,
        path: path.to_path_buf(),
        message: error.to_string(),
        publication: Some(smith::error::PublicationState::PublishedDurabilityUncertain),
    }
}

#[cfg(not(windows))]
fn sync_directory(path: &Path) -> std::io::Result<()> {
    File::open(path)?.sync_all()
}

#[cfg(windows)]
fn sync_directory(path: &Path) -> std::io::Result<()> {
    use std::os::windows::fs::OpenOptionsExt;

    // FILE_FLAG_BACKUP_SEMANTICS permits opening a directory handle safely.
    OpenOptions::new()
        .read(true)
        .custom_flags(0x0200_0000)
        .open(path)?
        .sync_all()
}

fn session_fault(code: smith::error::SessionCode, message: impl Into<String>) -> SmithError {
    SmithError::Session {
        code,
        message: message.into(),
    }
}

fn missing_entry(id: EntryId) -> SmithError {
    session_fault(
        smith::error::SessionCode::EntryNotFound,
        format!("entry {id} not found"),
    )
}

fn io_error(code: smith::error::StorageCode, path: &Path) -> impl Fn(std::io::Error) -> SmithError {
    storage_error(code, storage_operation(code), path)
}

const fn storage_operation(code: smith::error::StorageCode) -> smith::error::StorageOperation {
    use smith::error::{StorageCode, StorageOperation};
    match code {
        StorageCode::StoreCanonicalize => StorageOperation::Canonicalize,
        StorageCode::StoreStat | StorageCode::CreateStat => StorageOperation::Stat,
        StorageCode::StoreOpen
        | StorageCode::StoreLockOpen
        | StorageCode::StoreReaderLockOpen
        | StorageCode::RepairOpen => StorageOperation::Open,
        StorageCode::StoreRead
        | StorageCode::StoreProofRead
        | StorageCode::StoreScratchRead
        | StorageCode::FrameRead
        | StorageCode::SessionPrologue
        | StorageCode::FrameBoundary
        | StorageCode::AuthRead => StorageOperation::Read,
        StorageCode::StoreWrite
        | StorageCode::StoreProofWrite
        | StorageCode::StoreScratchWrite
        | StorageCode::CreateWrite
        | StorageCode::RepairWrite
        | StorageCode::StorePoisoned => StorageOperation::Write,
        StorageCode::StoreSeek
        | StorageCode::StoreProofSeek
        | StorageCode::StoreScratchSeek
        | StorageCode::RepairSeek => StorageOperation::Seek,
        StorageCode::StoreSync
        | StorageCode::CreateSync
        | StorageCode::RepairSync
        | StorageCode::StoreDirSync => StorageOperation::Sync,
        StorageCode::StoreTruncate => StorageOperation::Truncate,
        StorageCode::StoreMkdir | StorageCode::RuntimeDir => StorageOperation::CreateDirectory,
        StorageCode::AuthStore => StorageOperation::AuthStoreOperation,
        StorageCode::StoreLock
        | StorageCode::StoreBusy
        | StorageCode::StoreReaderLock
        | StorageCode::StoreReadersActive => StorageOperation::Lock,
        StorageCode::StoreUnlock | StorageCode::StoreReaderUnlock => StorageOperation::Unlock,
        StorageCode::StoreProofRemove
        | StorageCode::StoreScratchRemove
        | StorageCode::CreateTempRemove => StorageOperation::Remove,
        StorageCode::CreateTmp => StorageOperation::CreateTemporaryFile,
        StorageCode::CreatePublish | StorageCode::RepairPublish => StorageOperation::Publish,
    }
}

fn storage_fault(
    code: smith::error::StorageCode,
    path: &Path,
    message: impl Into<String>,
) -> SmithError {
    SmithError::Storage {
        code,
        operation: storage_operation(code),
        path: path.to_path_buf(),
        message: message.into(),
        publication: None,
    }
}

fn storage_error(
    code: smith::error::StorageCode,
    operation: smith::error::StorageOperation,
    path: &Path,
) -> impl Fn(std::io::Error) -> SmithError + '_ {
    move |e| SmithError::Storage {
        code,
        operation,
        path: path.to_path_buf(),
        message: e.to_string(),
        publication: None,
    }
}

#[cfg(test)]
#[expect(
    clippy::unwrap_used,
    clippy::panic,
    reason = "tests may panic on invariant violations"
)]
mod tests {
    use super::*;
    use crate::session::COMPACTION_KIND;
    use crate::session::{EntryContent, EntryFrame, EntryKind, Session};
    use smith::message::{ContentBlock, Message, Role};
    use smith::structured::{StructuredData, ToolArguments};
    use smith_alloc::{Scope, measure};
    use std::sync::Mutex;

    static MEASURING: Mutex<()> = Mutex::new(());

    fn tmp_path(name: &str) -> PathBuf {
        let dir = std::env::temp_dir().join(format!("smith_store_tests_{}", std::process::id()));
        std::fs::create_dir_all(&dir).unwrap();
        dir.join(name)
    }

    fn message(text: &str) -> EntryContent {
        EntryContent::Message(Message::with_text(Role::User, text))
    }

    fn entry(text: &str) -> EntryFrame {
        EntryFrame::new(None, &message(text)).unwrap()
    }

    fn text(entry: &EntryFrame) -> Option<String> {
        match EntryContent::decode(&entry.content).unwrap() {
            EntryContent::Message(m) => match &m.blocks[0] {
                ContentBlock::Text(t) => Some(t.clone()),
                _ => None,
            },
            _ => None,
        }
    }

    fn frame(text: &str) -> Frame {
        Frame::Known { entry: entry(text) }
    }

    fn file_bytes(frames: impl IntoIterator<Item = u8>) -> Vec<u8> {
        FILE_PROLOGUE.into_iter().chain(frames).collect()
    }

    #[test]
    fn receipt_rejects_admission_with_missing_parent() {
        let path = tmp_path("receipt-missing-admission-parent.smh");
        let _ = std::fs::remove_file(&path);
        let frame_bytes_max = Config::default_valid().frame_bytes_max;
        let header = Frame::Header {
            header: crate::session::SessionHeader {
                session_id: SessionId::new(),
                branch_id: smith::id::BranchId::new(),
            },
        }
        .encode(frame_bytes_max)
        .unwrap();
        let mut admitted = entry("pending");
        admitted.parent = Some(smith::id::EntryId::new());
        let admission = Frame::Admission {
            entry: admitted.clone(),
            key: Some("receipt-missing-parent".into()),
        }
        .encode(frame_bytes_max)
        .unwrap();
        let bytes = file_bytes(header.into_iter().chain(admission));
        std::fs::write(&path, bytes).unwrap();
        let reader = SessionReader::open(&path).unwrap();

        assert!(reader.receipt(admitted.id, frame_bytes_max).is_err());
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn receipt_rejects_admission_parent_that_follows_it() {
        let path = tmp_path("receipt-later-admission-parent.smh");
        let _ = std::fs::remove_file(&path);
        let frame_bytes_max = Config::default_valid().frame_bytes_max;
        let header = Frame::Header {
            header: crate::session::SessionHeader {
                session_id: SessionId::new(),
                branch_id: smith::id::BranchId::new(),
            },
        }
        .encode(frame_bytes_max)
        .unwrap();
        let parent = entry("later parent");
        let mut admitted = entry("pending");
        admitted.parent = Some(parent.id);
        let admission = Frame::Admission {
            entry: admitted.clone(),
            key: None,
        }
        .encode(frame_bytes_max)
        .unwrap();
        let later_parent = Frame::Known { entry: parent }
            .encode(frame_bytes_max)
            .unwrap();
        let bytes = file_bytes(header.into_iter().chain(admission).chain(later_parent));
        std::fs::write(&path, bytes).unwrap();
        let reader = SessionReader::open(&path).unwrap();

        assert!(reader.receipt(admitted.id, frame_bytes_max).is_err());
        let _ = std::fs::remove_file(path);
    }

    /// Eager frame collection belongs only in recovery assertions; durable
    /// product paths use `SessionReader`'s bounded readers directly.
    fn scanned_frames(path: &Path, frame_bytes_max: usize) -> Recovery {
        let reader = SessionReader::open(path).unwrap();
        let mut frames = Vec::new();
        let mut recovery = reader
            .scan(frame_bytes_max, |frame| {
                frames.push(frame);
                Ok(())
            })
            .unwrap();
        recovery.frames = frames;
        recovery
    }

    #[test]
    fn durable_selection_replays_and_forks_a_sibling_without_loading_unrelated_content() {
        let path = tmp_path("durable-selection.smh");
        let fork_path = tmp_path("durable-selection-fork.smh");
        let _ = std::fs::remove_file(&path);
        let _ = std::fs::remove_file(&fork_path);
        let cfg = Config::default_valid();
        let root = entry("root");
        let left = EntryFrame::new(Some(root.id), &message("left")).unwrap();
        let right = EntryFrame::new(Some(root.id), &message("right")).unwrap();
        {
            let mut opened = open_session(&path, cfg.clone()).unwrap();
            for entry in [&root, &left, &right] {
                opened
                    .writer
                    .append_frame(&Frame::Known {
                        entry: entry.clone(),
                    })
                    .unwrap();
            }
            opened.writer.select_entry(left.id).unwrap();
        }
        let reopened = open_session(&path, cfg.clone()).unwrap();
        assert_eq!(reopened.session.selected_id(), Some(left.id));
        assert_eq!(reopened.session.active_branch().entries().len(), 2);
        assert_eq!(
            reopened
                .session
                .content(&reopened.session.active_branch().entries()[1])
                .unwrap(),
            EntryContent::decode(&left.content).unwrap()
        );
        drop(reopened);
        let reader = SessionReader::open(&path).unwrap();
        let fork = reader.fork_at(right.id, &fork_path, cfg).unwrap();
        assert_eq!(fork.session.selected_id(), Some(right.id));
        assert_ne!(
            fork.session.id(),
            SessionReader::open(&path)
                .unwrap()
                .selected_session(Config::default_valid().frame_bytes_max)
                .unwrap()
                .id()
        );
        assert_eq!(
            fork.session
                .content(&fork.session.active_branch().entries()[1])
                .unwrap(),
            EntryContent::decode(&right.content).unwrap()
        );
        drop(fork);
        drop(reader);
        let _ = std::fs::remove_file(path);
        let _ = std::fs::remove_file(fork_path);
    }

    #[test]
    fn full_verification_detects_duplicate_ids_outside_selected_branch() {
        let path = tmp_path("duplicate-unselected.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let mut opened = open_session(&path, cfg.clone()).unwrap();
        let unselected = entry("one");
        let mut duplicate = entry("two");
        duplicate.id = unselected.id;
        for entry in [unselected, duplicate] {
            opened.writer.append_frame(&Frame::Known { entry }).unwrap();
        }
        drop(opened);
        let reader = SessionReader::open(&path).unwrap();
        assert_eq!(
            reader.verify_full(cfg.frame_bytes_max).unwrap_err().code(),
            "SESSION_DUPLICATE_ID"
        );
        drop(reader);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn missing_session_file_reports_storage_operation_path_and_source() {
        let path = tmp_path("missing-storage-error.smh");
        let _ = std::fs::remove_file(&path);
        let error = SessionReader::open(&path).unwrap_err();
        match error {
            SmithError::Storage {
                code,
                operation,
                path: actual,
                message,
                ..
            } => {
                assert_eq!(code, smith::error::StorageCode::StoreOpen);
                assert_eq!(operation.as_str(), "open");
                assert_eq!(actual, path);
                assert!(!message.is_empty());
            }
            other => panic!("expected storage error, got {other:?}"),
        }
        let _ = std::fs::remove_file(readers_path(&path));
    }

    #[test]
    fn missing_selected_entry_fails_open_without_retargeting_a_branch() {
        let path = tmp_path("missing-selected.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let mut opened = open_session(&path, cfg.clone()).unwrap();
        opened
            .writer
            .append_frame(&Frame::Known {
                entry: entry("valid"),
            })
            .unwrap();
        opened
            .writer
            .append_frame(&Frame::Selection { id: EntryId::new() })
            .unwrap();
        drop(opened);
        assert_eq!(
            open_session(&path, cfg).unwrap_err().code(),
            "ENTRY_NOT_FOUND"
        );
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn damaged_index_does_not_hide_following_entries() {
        let path = tmp_path("damaged-index.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let session = Session::new();
        let root = entry("root");
        let child = EntryFrame::new(Some(root.id), &message("child")).unwrap();
        let mut bytes = FILE_PROLOGUE.to_vec();
        bytes.extend(
            Frame::Header {
                header: session.header(),
            }
            .encode(cfg.frame_bytes_max)
            .unwrap(),
        );
        bytes.extend(
            Frame::Known {
                entry: root.clone(),
            }
            .encode(cfg.frame_bytes_max)
            .unwrap(),
        );
        let mut invalid = Frame::Index {
            id: root.id,
            offset: 8,
            parent: None,
            parent_offset: None,
        }
        .encode(cfg.frame_bytes_max)
        .unwrap();
        invalid[crate::frame::HEADER_LEN + 4] ^= 0x80;
        bytes.extend(invalid);
        bytes.extend(
            Frame::Known {
                entry: child.clone(),
            }
            .encode(cfg.frame_bytes_max)
            .unwrap(),
        );
        std::fs::write(&path, bytes).unwrap();
        let reader = SessionReader::open(&path).unwrap();
        assert_eq!(
            reader
                .selected_session(cfg.frame_bytes_max)
                .unwrap()
                .selected_id(),
            Some(child.id)
        );
        assert_eq!(
            reader.verify_full(cfg.frame_bytes_max).unwrap_err().code(),
            "FRAME_CHECKSUM"
        );
        drop(reader);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn repair_discards_stale_offsets_without_losing_authoritative_entries() {
        let path = tmp_path("repair-index-offset.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let mut opened = open_session(&path, cfg.clone()).unwrap();
        let record = *opened.session.append(&message("kept")).unwrap();
        opened
            .writer
            .append_entry(&record, opened.session.bytes(&record))
            .unwrap();
        let selected = record.id;
        drop(opened);
        let original = std::fs::read(&path).unwrap();
        let header_end = FILE_PROLOGUE.len()
            + Frame::Header {
                header: SessionReader::open(&path)
                    .unwrap()
                    .selected_session(cfg.frame_bytes_max)
                    .unwrap()
                    .header(),
            }
            .encode(cfg.frame_bytes_max)
            .unwrap()
            .len();
        let mut bytes = original[..header_end].to_vec();
        let mut damaged = Frame::Unknown {
            kind: 99,
            version: 1,
            payload: b"bad".to_vec(),
        }
        .encode(cfg.frame_bytes_max)
        .unwrap();
        damaged[crate::frame::HEADER_LEN + 4] ^= 1;
        bytes.extend(damaged);
        bytes.extend(&original[header_end..]);
        std::fs::write(&path, bytes).unwrap();
        repair_session(&path, cfg.frame_bytes_max).unwrap();
        let reader = SessionReader::open(&path).unwrap();
        reader.verify_full(cfg.frame_bytes_max).unwrap();
        assert_eq!(
            reader
                .selected_session(cfg.frame_bytes_max)
                .unwrap()
                .selected_id(),
            Some(selected)
        );
        drop(reader);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn reopen_keeps_only_effective_payload_after_compaction() {
        let path = tmp_path("effective-compaction.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let mut opened = open_session(&path, cfg.clone()).unwrap();
        let before = *opened
            .session
            .append(&message(&"x".repeat(400_000)))
            .unwrap();
        opened
            .writer
            .append_entry(&before, opened.session.bytes(&before))
            .unwrap();
        let compact = EntryContent::Meta {
            kind: COMPACTION_KIND.into(),
            detail: StructuredData::from_serializable(&serde_json::json!({"summary": ""})).unwrap(),
        };
        let boundary = *opened.session.append(&compact).unwrap();
        opened
            .writer
            .append_entry(&boundary, opened.session.bytes(&boundary))
            .unwrap();
        let after = *opened.session.append(&message("after")).unwrap();
        opened
            .writer
            .append_entry(&after, opened.session.bytes(&after))
            .unwrap();
        drop(opened);
        let reopened = open_session(&path, cfg).unwrap();
        assert_eq!(reopened.session.selected_id(), Some(after.id));
        assert_eq!(reopened.session.compaction_boundary(), Some(boundary.id));
        assert_eq!(reopened.session.active_branch().entries().len(), 2);
        assert!(reopened.session.bytes(&before).is_empty());
        drop(reopened);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn replay_visits_file_metadata_once_for_linear_history() {
        let path = tmp_path("replay-pass-count.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let mut opened = open_session(&path, cfg.clone()).unwrap();
        let mut parent = None;
        for _ in 0..96 {
            let e = EntryFrame::new(parent, &message("x")).unwrap();
            parent = Some(e.id);
            opened
                .writer
                .append_frame(&Frame::Known { entry: e })
                .unwrap();
        }
        drop(opened);
        let reader = SessionReader::open(&path).unwrap();
        METADATA_PASSES.with(|passes| passes.set(0));
        let mut visited = 0;
        reader
            .replay_at(parent.unwrap(), cfg.frame_bytes_max, |_| {
                visited += 1;
                Ok(())
            })
            .unwrap();
        assert_eq!(visited, 96);
        METADATA_PASSES
            .with(|passes| assert!(passes.get() <= 2, "{} metadata passes", passes.get()));
        drop(reader);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn effective_context_cannot_publish_a_broken_rooted_fork() {
        let path = tmp_path("partial-source.smh");
        let target = tmp_path("partial-target.smh");
        let _ = std::fs::remove_file(&path);
        let _ = std::fs::remove_file(&target);
        let cfg = Config::default_valid();
        let mut opened = open_session(&path, cfg.clone()).unwrap();
        let first = *opened.session.append(&message("before")).unwrap();
        opened
            .writer
            .append_entry(&first, opened.session.bytes(&first))
            .unwrap();
        let compact = EntryContent::Meta {
            kind: COMPACTION_KIND.into(),
            detail: StructuredData::from_serializable(&serde_json::json!({"summary": ""})).unwrap(),
        };
        let boundary = *opened.session.append(&compact).unwrap();
        opened
            .writer
            .append_entry(&boundary, opened.session.bytes(&boundary))
            .unwrap();
        drop(opened);
        let resumed = open_session(&path, cfg.clone()).unwrap();
        assert_eq!(
            create_session(&target, &resumed.session, cfg)
                .unwrap_err()
                .code(),
            "SESSION_INCOMPLETE_CONTEXT"
        );
        assert!(!target.exists());
        drop(resumed);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn snapshot_reads_pinned_inode_after_uncoordinated_replacement() {
        let path = tmp_path("pinned-generation.smh");
        let replacement = tmp_path("pinned-generation-replacement.smh");
        let _ = std::fs::remove_file(&path);
        let _ = std::fs::remove_file(&replacement);
        let cfg = Config::default_valid();
        let mut first = open_session(&path, cfg.clone()).unwrap();
        let root = entry("old");
        first
            .writer
            .append_frame(&Frame::Known {
                entry: root.clone(),
            })
            .unwrap();
        let old_id = first.session.id();
        drop(first);
        let snapshot = SessionReader::open(&path).unwrap();
        let newer = open_session(&replacement, cfg.clone()).unwrap();
        let new_id = newer.session.id();
        drop(newer);
        std::fs::rename(&replacement, &path).unwrap();
        assert_eq!(
            snapshot.selected_session(cfg.frame_bytes_max).unwrap().id(),
            old_id
        );
        assert_eq!(
            snapshot
                .find_entry(root.id, cfg.frame_bytes_max)
                .unwrap()
                .unwrap()
                .0
                .id,
            root.id
        );
        assert_eq!(
            SessionReader::open(&path)
                .unwrap()
                .selected_session(cfg.frame_bytes_max)
                .unwrap()
                .id(),
            new_id
        );
        drop(snapshot);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn replay_and_fork_visit_growth_is_quadratic_not_cubic() {
        fn visits(depth: usize) -> (usize, usize) {
            let path = tmp_path(&format!("growth-{depth}.smh"));
            let target = tmp_path(&format!("growth-fork-{depth}.smh"));
            let _ = std::fs::remove_file(&path);
            let _ = std::fs::remove_file(&target);
            let cfg = Config::default_valid();
            let mut opened = open_session(&path, cfg.clone()).unwrap();
            let mut parent = None;
            for _ in 0..depth {
                let entry = EntryFrame::new(parent, &message("x")).unwrap();
                parent = Some(entry.id);
                opened.writer.append_frame(&Frame::Known { entry }).unwrap();
            }
            drop(opened);
            let reader = SessionReader::open(&path).unwrap();
            PROOF_VISITS.with(|visits| visits.set(0));
            reader
                .replay_at(parent.unwrap(), cfg.frame_bytes_max, |_| Ok(()))
                .unwrap();
            let replay = PROOF_VISITS.with(std::cell::Cell::get);
            PROOF_VISITS.with(|visits| visits.set(0));
            let fork = reader.fork_at(parent.unwrap(), &target, cfg).unwrap();
            assert_eq!(fork.session.selected_id(), parent);
            let fork_visits = PROOF_VISITS.with(std::cell::Cell::get);
            drop(fork);
            drop(reader);
            let _ = std::fs::remove_file(path);
            let _ = std::fs::remove_file(target);
            (replay, fork_visits)
        }
        let small = visits(64);
        let large = visits(128);
        assert!(
            large.0 <= 5 * small.0,
            "replay proof visits: {small:?} -> {large:?}"
        );
        assert!(
            large.1 <= 5 * small.1,
            "fork proof visits: {small:?} -> {large:?}"
        );
    }

    #[test]
    fn create_keeps_selection_of_existing_ancestor() {
        let path = tmp_path("create-ancestor-selection.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let root = entry("root");
        let child = EntryFrame::new(Some(root.id), &message("child")).unwrap();
        let source = Session::from_frames(&[
            Frame::Header {
                header: Session::new().header(),
            },
            Frame::Known {
                entry: root.clone(),
            },
            Frame::Known { entry: child },
            Frame::Selection { id: root.id },
        ])
        .unwrap();
        let opened = create_session(&path, &source, cfg.clone()).unwrap();
        assert_eq!(opened.session.selected_id(), Some(root.id));
        drop(opened);
        let reopened = open_session(&path, cfg).unwrap();
        assert_eq!(reopened.session.selected_id(), Some(root.id));
        drop(reopened);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn valid_checkpoint_locates_selected_ancestor() {
        let path = tmp_path("selected-checkpoint-hint.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let root = entry("root");
        let child = EntryFrame::new(Some(root.id), &message("child")).unwrap();
        let mut opened = open_session(&path, cfg.clone()).unwrap();
        for record in [&root, &child] {
            opened
                .writer
                .append_frame(&Frame::Known {
                    entry: record.clone(),
                })
                .unwrap();
        }
        opened.writer.select_entry(root.id).unwrap();
        drop(opened);
        CHECKPOINT_HITS.with(|hits| hits.set(0));
        let reader = SessionReader::open(&path).unwrap();
        assert_eq!(
            reader
                .selected_session(cfg.frame_bytes_max)
                .unwrap()
                .selected_id(),
            Some(root.id)
        );
        CHECKPOINT_HITS.with(|hits| assert_eq!(hits.get(), 1));
        drop(reader);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn invalid_checkpoint_does_not_reset_writer_cadence() {
        let path = tmp_path("invalid-cadence.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let mut opened = open_session(&path, cfg.clone()).unwrap();
        for _ in 0..63 {
            let record = *opened.session.append(&message("turn")).unwrap();
            opened
                .writer
                .append_entry(&record, opened.session.bytes(&record))
                .unwrap();
        }
        opened
            .writer
            .append_frame(&Frame::Checkpoint {
                id: EntryId::new(),
                offset: 123,
            })
            .unwrap();
        drop(opened);
        let mut reopened = open_session(&path, cfg.clone()).unwrap();
        let record = *reopened.session.append(&message("last")).unwrap();
        reopened
            .writer
            .append_entry(&record, reopened.session.bytes(&record))
            .unwrap();
        drop(reopened);
        let mut count = 0;
        SessionReader::open(&path)
            .unwrap()
            .scan(cfg.frame_bytes_max, |frame| {
                if matches!(frame, Frame::Checkpoint { .. }) {
                    count += 1;
                }
                Ok(())
            })
            .unwrap();
        assert_eq!(count, 2);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn writer_publishes_reconstructible_checkpoints_at_the_cadence() {
        let path = tmp_path("checkpoint-cadence.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let mut opened = open_session(&path, cfg.clone()).unwrap();
        for _ in 0..63 {
            let record = *opened.session.append(&message("turn")).unwrap();
            opened
                .writer
                .append_entry(&record, opened.session.bytes(&record))
                .unwrap();
        }
        drop(opened);
        let mut reopened = open_session(&path, cfg.clone()).unwrap();
        let record = *reopened.session.append(&message("turn")).unwrap();
        reopened
            .writer
            .append_entry(&record, reopened.session.bytes(&record))
            .unwrap();
        let selected = reopened.session.selected_id();
        drop(reopened);
        let reader = SessionReader::open(&path).unwrap();
        let mut checkpoints = 0;
        reader
            .scan(cfg.frame_bytes_max, |frame| {
                if matches!(frame, Frame::Checkpoint { .. }) {
                    checkpoints += 1;
                }
                Ok(())
            })
            .unwrap();
        assert_eq!(checkpoints, 1);
        reader.verify_full(cfg.frame_bytes_max).unwrap();
        assert_eq!(
            reader
                .selected_session(cfg.frame_bytes_max)
                .unwrap()
                .selected_id(),
            selected
        );
        drop(reader);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn forged_checkpoint_is_ignored_for_resume_but_fails_full_verification() {
        let path = tmp_path("forged-checkpoint.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let mut opened = open_session(&path, cfg.clone()).unwrap();
        let root = entry("root");
        let child = EntryFrame::new(Some(root.id), &message("child")).unwrap();
        opened
            .writer
            .append_frame(&Frame::Known {
                entry: root.clone(),
            })
            .unwrap();
        opened
            .writer
            .append_frame(&Frame::Checkpoint {
                id: root.id,
                offset: FILE_PROLOGUE.len() as u64 + 1,
            })
            .unwrap();
        opened
            .writer
            .append_frame(&Frame::Known {
                entry: child.clone(),
            })
            .unwrap();
        drop(opened);
        let reader = SessionReader::open(&path).unwrap();
        assert_eq!(
            reader
                .selected_session(cfg.frame_bytes_max)
                .unwrap()
                .selected_id(),
            Some(child.id)
        );
        assert_eq!(
            reader.verify_full(cfg.frame_bytes_max).unwrap_err().code(),
            "SESSION_CHECKPOINT"
        );
        drop(reader);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn forged_index_never_hides_later_entries_and_full_verification_rejects_it() {
        let path = tmp_path("forged-index.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let mut opened = open_session(&path, cfg.clone()).unwrap();
        let root = entry("root");
        let child = EntryFrame::new(Some(root.id), &message("child")).unwrap();
        opened
            .writer
            .append_frame(&Frame::Known {
                entry: root.clone(),
            })
            .unwrap();
        opened
            .writer
            .append_frame(&Frame::Index {
                id: root.id,
                offset: FILE_PROLOGUE.len() as u64 + 1,
                parent: None,
                parent_offset: None,
            })
            .unwrap();
        opened
            .writer
            .append_frame(&Frame::Known {
                entry: child.clone(),
            })
            .unwrap();
        drop(opened);
        let reader = SessionReader::open(&path).unwrap();
        assert_eq!(
            reader
                .selected_session(cfg.frame_bytes_max)
                .unwrap()
                .selected_id(),
            Some(child.id)
        );
        assert_eq!(
            reader.verify_full(cfg.frame_bytes_max).unwrap_err().code(),
            "SESSION_INDEX"
        );
        drop(reader);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn create_validates_config_before_creating_session_files() {
        let path = tmp_path("config-before-effects/nested/session.smh");
        let _ = std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap());
        let mut config = Config::default_valid();
        config.frame_bytes_max = 0;
        assert!(create_session(&path, &Session::new(), config).is_err());
        assert!(!path.parent().unwrap().exists());
    }

    #[test]
    fn create_rejects_named_identity_mismatch_before_publication() {
        let session = Session::new();
        let path = tmp_path(&format!("{}.smh", smith::id::SessionId::new()));
        let _ = std::fs::remove_file(&path);
        assert_eq!(
            create_session(&path, &session, Config::default_valid())
                .unwrap_err()
                .code(),
            "SESSION_ID_MISMATCH"
        );
        assert!(!path.exists());
        let _ = std::fs::remove_file(lock_path(&path));
    }

    #[cfg(unix)]
    #[test]
    fn create_temp_symlink_cannot_truncate_its_target() {
        let path = tmp_path("create-temp-link.smh");
        let temporary = path.with_extension("smith-create.tmp");
        let victim = tmp_path("create-temp-victim");
        let _ = std::fs::remove_file(&path);
        let _ = std::fs::remove_file(&temporary);
        std::fs::write(&victim, b"do not truncate").unwrap();
        std::os::unix::fs::symlink(&victim, &temporary).unwrap();
        create_session(&path, &Session::new(), Config::default_valid()).unwrap();
        assert_eq!(std::fs::read(&victim).unwrap(), b"do not truncate");
        let _ = std::fs::remove_file(&path);
        let _ = std::fs::remove_file(&temporary);
        let _ = std::fs::remove_file(&victim);
    }

    #[cfg(unix)]
    #[test]
    fn repair_temp_symlink_cannot_truncate_its_target() {
        let path = tmp_path("repair-temp-link.smh");
        let temporary = path.with_extension("smith-repair.tmp");
        let victim = tmp_path("repair-temp-victim");
        let _ = std::fs::remove_file(&path);
        let _ = std::fs::remove_file(&temporary);
        std::fs::write(&path, file_bytes(frame("intact").encode(1 << 20).unwrap())).unwrap();
        std::fs::write(&victim, b"do not truncate").unwrap();
        std::os::unix::fs::symlink(&victim, &temporary).unwrap();
        repair_session(&path, Config::default_valid().frame_bytes_max).unwrap();
        assert_eq!(std::fs::read(&victim).unwrap(), b"do not truncate");
        let _ = std::fs::remove_file(&path);
        let _ = std::fs::remove_file(&temporary);
        let _ = std::fs::remove_file(&victim);
    }

    fn text_of(frame: &Frame) -> String {
        match frame {
            Frame::Known { entry } => text(entry).unwrap(),
            other => panic!("unexpected frame {other:?}"),
        }
    }

    #[cfg(target_arch = "x86_64")]
    #[test]
    fn observer_handle_has_constant_size_independent_of_history() {
        assert_eq!(std::mem::size_of::<SessionReader>(), 24);
    }

    #[test]
    fn reporting_scan_does_not_retain_streamed_damage() {
        let path = tmp_path("reporting-damage.smh");
        let _ = std::fs::remove_file(&path);
        let mut malformed = frame("bad").encode(1 << 20).unwrap();
        malformed[crate::frame::HEADER_LEN + 4] ^= 0xff;
        std::fs::write(&path, file_bytes(malformed.repeat(128))).unwrap();
        let reader = SessionReader::open(&path).unwrap();
        let mut reported = 0;
        let recovery = reader
            .scan_reporting(
                Config::default_valid().frame_bytes_max,
                |_| Ok(true),
                |_| {
                    reported += 1;
                    Ok(())
                },
            )
            .unwrap();
        assert_eq!(reported, 128);
        assert!(recovery.damage.is_empty());
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn reader_snapshot_keeps_initial_writer_ownership_and_length() {
        let path = tmp_path("reader-snapshot.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let mut writer = SessionWriter::open(&path, cfg.clone()).unwrap();
        writer.append_frame(&frame("before")).unwrap();
        let reader = SessionReader::open(&path).unwrap();
        assert!(reader.writer_active());
        let snapshot_len = reader.file_size();
        writer.append_frame(&frame("after")).unwrap();
        drop(writer);
        assert_eq!(reader.file_size(), snapshot_len);
        let mut frames = 0;
        reader
            .scan(cfg.frame_bytes_max, |_| {
                frames += 1;
                Ok(())
            })
            .unwrap();
        assert_eq!(frames, 1);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn streaming_scan_visits_entries_without_retaining_history() {
        // SMH-SPEC-SPEC0001: Sessions, Working sets; a snapshot never follows live appends.
        let path = tmp_path("stream_scan.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let mut writer = SessionWriter::open(&path, cfg.clone()).unwrap();
        for _ in 0..128 {
            writer.append_frame(&frame("entry")).unwrap();
        }
        let mut count = 0;
        let scan = scan_session(&path, cfg.frame_bytes_max, |frame| {
            assert!(matches!(frame, Frame::Known { .. }));
            count += 1;
            Ok(())
        })
        .unwrap();
        assert_eq!(count, 128);
        assert!(scan.damage.is_empty());
        assert_eq!(scan.torn_tail_at, None);
        let mut corrupt = File::options().append(true).open(&path).unwrap();
        corrupt.write_all(&[0, 1]).unwrap();
        let scan = scan_session(&path, cfg.frame_bytes_max, |_| Ok(())).unwrap();
        assert!(scan.torn_tail_at.is_some());
        drop(writer);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn append_load_round_trip_preserves_entries() {
        let path = tmp_path("round_trip.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let first = entry("one");
        let second = EntryFrame::new(Some(first.id), &message("two")).unwrap();
        {
            let mut opened = open_session(&path, cfg.clone()).unwrap();
            opened
                .writer
                .append_frame(&Frame::Known {
                    entry: first.clone(),
                })
                .unwrap();
            opened
                .writer
                .append_frame(&Frame::Known {
                    entry: second.clone(),
                })
                .unwrap();
        }
        let session = SessionReader::open(&path)
            .unwrap()
            .selected_session(cfg.frame_bytes_max)
            .unwrap();
        assert_eq!(
            session
                .active_branch()
                .entries()
                .iter()
                .map(|e| e.id)
                .collect::<Vec<_>>(),
            vec![first.id, second.id]
        );
        assert_eq!(session.selected_id(), Some(second.id));
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn successful_io_error_context_setup_does_not_allocate() {
        let path = Path::new("/tmp/smith-store-allocation-check");
        let _serial = MEASURING
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let (_, cost) = measure(Scope::IoRequest, || {
            let error = io_error(smith::error::StorageCode::StoreWrite, path);
            drop(std::hint::black_box(error));
        });
        assert_eq!(cost.allocations, 0);
        assert_eq!(cost.bytes, 0);
    }

    #[test]
    fn successful_write_does_not_allocate_error_context() {
        let path = tmp_path("write-allocation-check.smh");
        let _ = std::fs::remove_file(&path);
        let mut writer = SessionWriter::open(&path, Config::default_valid()).unwrap();
        let bytes = frame("allocation-check")
            .encode(Config::default_valid().frame_bytes_max)
            .unwrap();
        let _serial = MEASURING
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let (result, cost) = measure(Scope::IoRequest, || writer.write(&bytes));
        result.unwrap();
        assert_eq!(cost.allocations, 0);
        assert_eq!(cost.bytes, 0);
        drop(writer);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn torn_tail_is_truncated_on_open_and_appends_stay_visible() {
        let path = tmp_path("torn_tail.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        {
            let mut w = SessionWriter::open(&path, cfg.clone()).unwrap();
            w.append_frame(&frame("kept")).unwrap();
        }
        // Simulate a crash mid-append: partial header + payload bytes.
        let good = Frame::Known {
            entry: entry("kept"),
        }
        .encode(cfg.frame_bytes_max)
        .unwrap();
        let mut torn = good;
        torn.extend_from_slice(&[0x10, 0x00, 0x00, 0x00, 0xAA, 0xBB]);
        std::fs::write(&path, file_bytes(torn)).unwrap();
        {
            // Open repairs the tail, then a new append must be loadable.
            let mut w = SessionWriter::open(&path, cfg.clone()).unwrap();
            w.append_frame(&frame("after")).unwrap();
        }
        let frames = scanned_frames(&path, cfg.frame_bytes_max).frames;
        let texts: Vec<String> = frames
            .iter()
            .filter_map(|f| match f {
                Frame::Known { entry } => text(entry),
                _ => None,
            })
            .collect();
        assert_eq!(texts, vec!["kept".to_string(), "after".to_string()]);
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn loader_stops_at_torn_tail_without_header_fabrication() {
        let path = tmp_path("loader_torn.smh");
        let cfg = Config::default_valid();
        let good = frame("a").encode(cfg.frame_bytes_max).unwrap();
        let mut bytes = good;
        bytes.extend_from_slice(&[0xFF, 0xFF]); // partial header
        std::fs::write(&path, file_bytes(bytes)).unwrap();
        let frames = scanned_frames(&path, cfg.frame_bytes_max).frames;
        assert_eq!(frames.len(), 1);
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn reopening_a_multi_frame_session_keeps_every_frame() {
        let path = tmp_path("reopen_multi.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        {
            let mut w = SessionWriter::open(&path, cfg.clone()).unwrap();
            w.append_frame(&frame("one")).unwrap();
            w.append_frame(&frame("two")).unwrap();
        }
        {
            // Reopening must not mistake a later frame boundary for a torn tail.
            let mut w = SessionWriter::open(&path, cfg.clone()).unwrap();
            w.append_frame(&frame("three")).unwrap();
        }
        let recovery = scanned_frames(&path, cfg.frame_bytes_max);
        assert_eq!(recovery.frames.len(), 3);
        assert!(recovery.damage.is_empty());
        assert_eq!(recovery.torn_tail_at, None);
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn oversized_complete_frame_is_skipped_and_following_frames_reachable() {
        let path = tmp_path("oversized_skip.smh");
        // declared = 5000 > limit 1024, payload fully present, then a valid frame.
        let mut bytes = Frame::Unknown {
            kind: 9,
            version: 1,
            payload: vec![0xAB; 5000],
        }
        .encode(6000)
        .unwrap();
        bytes.extend_from_slice(&frame("tail").encode(1 << 20).unwrap());
        std::fs::write(&path, file_bytes(bytes)).unwrap();
        let recovery = scanned_frames(&path, 1024);
        assert_eq!(recovery.frames.len(), 1);
        assert!(matches!(recovery.frames[0], Frame::Known { .. }));
        assert_eq!(recovery.damage[0].code(), "FRAME_TOO_LARGE");
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn repair_reports_all_faults_without_retaining_their_frames() {
        let path = tmp_path("repair-multiple-faults.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let mut bytes = FILE_PROLOGUE.to_vec();
        for _ in 0..2 {
            let mut broken = frame("damaged").encode(cfg.frame_bytes_max).unwrap();
            broken[crate::frame::HEADER_LEN + 4] ^= 1;
            bytes.extend(broken);
        }
        std::fs::write(&path, bytes).unwrap();
        let recovery = repair_session(&path, cfg.frame_bytes_max).unwrap();
        assert_eq!(recovery.damage_count, 2);
        assert_eq!(recovery.damage.len(), 1);
        assert!(recovery.frames.is_empty());
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn repair_streams_unknown_frames_and_keeps_final_selection() {
        let path = tmp_path("repair-stream-selection.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let root = entry("root");
        let child = EntryFrame::new(Some(root.id), &message("child")).unwrap();
        let unknown = Frame::Unknown {
            kind: 0x7abc,
            version: 17,
            payload: vec![42; 1024],
        };
        let mut opened = open_session(&path, cfg.clone()).unwrap();
        for entry in [&root, &child] {
            opened
                .writer
                .append_frame(&Frame::Known {
                    entry: entry.clone(),
                })
                .unwrap();
        }
        opened.writer.append_frame(&unknown).unwrap();
        opened.writer.select_entry(root.id).unwrap();
        drop(opened);
        let recovery = repair_session(&path, cfg.frame_bytes_max).unwrap();
        assert!(
            recovery.frames.is_empty(),
            "repair must not retain historical frames"
        );
        let mut seen_unknown = false;
        SessionReader::open(&path)
            .unwrap()
            .scan(cfg.frame_bytes_max, |frame| {
                if frame == unknown {
                    seen_unknown = true;
                }
                Ok(())
            })
            .unwrap();
        assert!(seen_unknown);
        let reopened = open_session(&path, cfg).unwrap();
        assert_eq!(reopened.session.selected_id(), Some(root.id));
        drop(reopened);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn repair_rejects_damaged_explicit_selection_without_publication() {
        let dir = tmp_path("repair-selected-damaged");
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        let path = dir.join("session.smh");
        let cfg = Config::default_valid();
        let session = Session::new();
        let root = entry("root");
        let selected = EntryFrame::new(Some(root.id), &message("selected")).unwrap();
        let mut bytes = FILE_PROLOGUE.to_vec();
        for frame in [
            Frame::Header {
                header: session.header(),
            },
            Frame::Known {
                entry: root.clone(),
            },
            Frame::Known {
                entry: selected.clone(),
            },
            Frame::Selection { id: selected.id },
        ] {
            bytes.extend(frame.encode(cfg.frame_bytes_max).unwrap());
        }
        let selected_start = FILE_PROLOGUE.len()
            + Frame::Header {
                header: session.header(),
            }
            .encode(cfg.frame_bytes_max)
            .unwrap()
            .len()
            + Frame::Known { entry: root }
                .encode(cfg.frame_bytes_max)
                .unwrap()
                .len();
        let selected_checksum = selected_start + crate::frame::HEADER_LEN + 4;
        bytes[selected_checksum] ^= 1;
        std::fs::write(&path, &bytes).unwrap();
        let before_temps = std::fs::read_dir(&dir)
            .unwrap()
            .filter_map(std::result::Result::ok)
            .filter(|entry| {
                entry
                    .file_name()
                    .to_string_lossy()
                    .starts_with("session.smh.smith-repair-")
            })
            .count();

        let error = repair_session(&path, cfg.frame_bytes_max).unwrap_err();

        assert_eq!(error.code(), "ENTRY_NOT_FOUND");
        assert_eq!(std::fs::read(&path).unwrap(), bytes);
        let after_temps = std::fs::read_dir(&dir)
            .unwrap()
            .filter_map(std::result::Result::ok)
            .filter(|entry| {
                entry
                    .file_name()
                    .to_string_lossy()
                    .starts_with("session.smh.smith-repair-")
            })
            .count();
        assert_eq!(after_temps, before_temps);
        let _ = std::fs::remove_dir_all(dir);
    }

    #[test]
    fn repair_republishes_file_without_torn_tail() {
        let path = tmp_path("repair.smh");
        let cfg = Config::default_valid();
        let good = frame("a").encode(cfg.frame_bytes_max).unwrap();
        let mut bytes = good;
        bytes.extend_from_slice(&frame("b").encode(cfg.frame_bytes_max).unwrap()[..6]);
        std::fs::write(&path, file_bytes(bytes)).unwrap();
        let before = std::fs::metadata(&path).unwrap().len();
        let recovery = repair_session(&path, cfg.frame_bytes_max).unwrap();
        assert!(recovery.frames.is_empty());
        assert_eq!(recovery.torn_tail_at, Some(before - 6));
        let after = std::fs::metadata(&path).unwrap().len();
        assert!(after < before);
        assert_eq!(scanned_frames(&path, cfg.frame_bytes_max).frames.len(), 1);
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn writer_rejects_oversized_frame_without_touching_file() {
        let path = tmp_path("oversize_reject.smh");
        let _ = std::fs::remove_file(&path);
        let mut cfg = Config::default_valid();
        cfg.frame_bytes_max = 4096;
        {
            let mut w = SessionWriter::open(&path, cfg.clone()).unwrap();
            w.append_frame(&frame("small")).unwrap();
            let big = EntryFrame::new(
                None,
                &EntryContent::Message({
                    let mut m = Message::with_text(Role::User, "x");
                    m.add_block(ContentBlock::text("y".repeat(8192)));
                    m
                }),
            )
            .unwrap();
            let error = w.append_frame(&Frame::Known { entry: big }).unwrap_err();
            assert_eq!(error.code(), "FRAME_TOO_LARGE");
        }
        assert_eq!(scanned_frames(&path, cfg.frame_bytes_max).frames.len(), 1);
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn session_identity_mismatch_does_not_mutate_source() {
        // SMH-SPEC-SPEC0001: Sessions, identity independent of offsets and filenames.
        let original = Session::new();
        let path = tmp_path(&format!("{}.smh", original.id()));
        let renamed = tmp_path(&format!("{}.smh", smith::id::SessionId::new()));
        let _ = std::fs::remove_file(&path);
        let _ = std::fs::remove_file(&renamed);
        drop(open_session(&path, Config::default_valid()).unwrap());
        std::fs::rename(&path, &renamed).unwrap();
        let before = std::fs::read(&renamed).unwrap();
        assert_eq!(
            open_session(&renamed, Config::default_valid())
                .unwrap_err()
                .code(),
            "SESSION_ID_MISMATCH"
        );
        assert_eq!(std::fs::read(&renamed).unwrap(), before);
        let _ = std::fs::remove_file(renamed);
    }

    #[test]
    fn observer_prevents_implicit_tail_repair() {
        // SMH-SPEC-SPEC0001: Sessions, maintenance cannot invalidate a pinned reader.
        let path = tmp_path("observer_torn.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let mut writer = SessionWriter::open(&path, cfg.clone()).unwrap();
        writer.append_frame(&frame("intact")).unwrap();
        drop(writer);
        let mut tail = File::options().append(true).open(&path).unwrap();
        tail.write_all(&[0, 1]).unwrap();
        let before = std::fs::read(&path).unwrap();
        let observer = SessionReader::open(&path).unwrap();
        assert_eq!(
            SessionWriter::open(&path, cfg).unwrap_err().code(),
            "STORE_READERS_ACTIVE"
        );
        assert_eq!(std::fs::read(&path).unwrap(), before);
        drop(observer);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn observer_coexists_with_writer_but_blocks_replacement() {
        // SMH-SPEC-SPEC0001: Sessions, Access ownership and repair coordination.
        let path = tmp_path("observer_lock.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let mut writer = SessionWriter::open(&path, cfg.clone()).unwrap();
        writer.append_frame(&frame("one")).unwrap();
        let observer = SessionReader::open(&path).unwrap();
        assert_eq!(
            observer
                .scan(cfg.frame_bytes_max, |_| Ok(()))
                .unwrap()
                .good_end,
            std::fs::metadata(&path).unwrap().len()
        );
        assert_eq!(
            SessionWriter::open(&path, cfg.clone()).unwrap_err().code(),
            "STORE_BUSY"
        );
        drop(writer);
        assert_eq!(
            repair_session(&path, cfg.frame_bytes_max)
                .unwrap_err()
                .code(),
            "STORE_READERS_ACTIVE"
        );
        drop(observer);
        repair_session(&path, cfg.frame_bytes_max).unwrap();
        let _ = std::fs::remove_file(path);
    }

    #[cfg(unix)]
    #[test]
    fn symlinked_data_and_parent_paths_share_one_writer_lock() {
        let dir = tmp_path("symlinked-writer-lock");
        let real_dir = dir.join("real");
        let parent_alias = dir.join("parent-alias");
        let data_alias = dir.join("data-alias.smh");
        let real_path = real_dir.join("session.smh");
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&real_dir).unwrap();
        std::os::unix::fs::symlink(&real_dir, &parent_alias).unwrap();

        let writer = SessionWriter::open(&real_path, Config::default_valid()).unwrap();
        std::os::unix::fs::symlink(&real_path, &data_alias).unwrap();
        for alias in [&parent_alias.join("session.smh"), &data_alias] {
            assert_eq!(
                SessionWriter::open(alias, Config::default_valid())
                    .unwrap_err()
                    .code(),
                "STORE_BUSY"
            );
        }
        drop(writer);
        let _ = std::fs::remove_dir_all(dir);
    }

    #[cfg(unix)]
    #[test]
    fn multiply_linked_session_data_is_rejected() {
        let dir = tmp_path("multiply-linked-session");
        let path = dir.join("session.smh");
        let alias = dir.join("alias.smh");
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        drop(SessionWriter::open(&path, Config::default_valid()).unwrap());
        std::fs::hard_link(&path, &alias).unwrap();

        assert_eq!(
            SessionWriter::open(&path, Config::default_valid())
                .unwrap_err()
                .code(),
            "SESSION_AMBIGUOUS_ALIAS"
        );
        let _ = std::fs::remove_dir_all(dir);
    }

    #[test]
    fn failed_write_poisoning_rejects_later_appends() {
        let path = tmp_path("poisoned-writer.smh");
        let _ = std::fs::remove_file(&path);
        let mut writer = SessionWriter::open(&path, Config::default_valid()).unwrap();
        let healthy = writer.file.try_clone().unwrap();
        writer.file = File::open(path.parent().unwrap()).unwrap();
        assert_eq!(
            writer.append_frame(&frame("partial")).unwrap_err().code(),
            "STORE_WRITE"
        );
        writer.file = healthy;
        assert_eq!(
            writer.append_frame(&frame("later")).unwrap_err().code(),
            "STORE_POISONED"
        );
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn interrupted_context_edit_and_failed_sync_do_not_publish_live_projection() {
        use crate::context::{ContextEdit, ContextReplacement};
        for partial in [true, false] {
            let path = tmp_path(if partial {
                "context-partial.smh"
            } else {
                "context-sync.smh"
            });
            let _ = std::fs::remove_file(&path);
            let mut session = Session::new();
            let target = session
                .append(&EntryContent::Message(Message::with_text(
                    Role::User,
                    "original",
                )))
                .unwrap()
                .id;
            let mut opened = create_session(&path, &session, Config::default_valid()).unwrap();
            let before = opened.session.clone();
            let edits = [ContextEdit {
                target,
                replacement: Some(ContextReplacement::Text("replacement".into())),
            }];
            let error = opened.session.edit_context_with(&edits, |entry, content| {
                let bytes = encode_entry(entry, content, Config::default_valid().frame_bytes_max)?;
                opened.writer.write_step(|file| {
                    file.write_all(if partial {
                        &bytes[..bytes.len() / 2]
                    } else {
                        &bytes
                    })
                    .map_err(io_error(smith::error::StorageCode::StoreWrite, &path))?;
                    Err(storage_fault(
                        smith::error::StorageCode::StoreSync,
                        &path,
                        "injected edit persistence failure",
                    ))
                })
            });
            assert!(error.is_err());
            assert_eq!(opened.session, before);
            assert_eq!(
                opened.writer.edit_context(&edits).unwrap_err().code(),
                "STORE_POISONED"
            );
            drop(opened);
            if partial {
                let reader = SessionReader::open(&path).unwrap();
                assert_eq!(
                    reader
                        .selected_session(Config::default_valid().frame_bytes_max)
                        .unwrap()
                        .projected_messages()
                        .unwrap(),
                    before.projected_messages().unwrap()
                );
                drop(reader);
                let reopened = open_session(&path, Config::default_valid()).unwrap();
                assert_eq!(
                    reopened.session.projected_messages().unwrap(),
                    before.projected_messages().unwrap()
                );
            }
            let _ = std::fs::remove_file(&path);
        }
    }

    #[test]
    fn fault_injected_partial_write_and_sync_failure_poison_writers() {
        let partial_path = tmp_path("poisoned-partial-writer.smh");
        let sync_path = tmp_path("poisoned-sync-writer.smh");
        let _ = std::fs::remove_file(&partial_path);
        let _ = std::fs::remove_file(&sync_path);
        let bytes = frame("pending")
            .encode(Config::default_valid().frame_bytes_max)
            .unwrap();

        let mut partial = SessionWriter::open(&partial_path, Config::default_valid()).unwrap();
        assert_eq!(
            partial
                .write_step(|file| {
                    file.write_all(&bytes[..bytes.len() / 2]).map_err(io_error(
                        smith::error::StorageCode::StoreWrite,
                        &partial_path,
                    ))?;
                    Err(storage_fault(
                        smith::error::StorageCode::StoreWrite,
                        &partial_path,
                        "injected partial write failure",
                    ))
                })
                .unwrap_err()
                .code(),
            "STORE_WRITE"
        );
        assert_eq!(
            partial.append_frame(&frame("later")).unwrap_err().code(),
            "STORE_POISONED"
        );
        drop(partial);

        let mut sync = SessionWriter::open(&sync_path, Config::default_valid()).unwrap();
        assert_eq!(
            sync.write_step(|file| {
                file.write_all(&bytes)
                    .map_err(io_error(smith::error::StorageCode::StoreWrite, &sync_path))?;
                Err(storage_fault(
                    smith::error::StorageCode::StoreSync,
                    &sync_path,
                    "injected sync failure",
                ))
            })
            .unwrap_err()
            .code(),
            "STORE_SYNC"
        );
        assert_eq!(
            sync.append_frame(&frame("later")).unwrap_err().code(),
            "STORE_POISONED"
        );
        drop(sync);
        let _ = std::fs::remove_file(partial_path);
        let _ = std::fs::remove_file(sync_path);
    }

    #[test]
    fn lock_serializes_second_writer_handle() {
        let path = tmp_path("locked.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let writer = SessionWriter::open(&path, cfg).unwrap();
        // While the first writer holds the session, an independent handle
        // cannot take it: writers cannot interleave frames.
        let probe = OpenOptions::new()
            .read(true)
            .write(true)
            .open(lock_path(&path))
            .unwrap();
        assert!(fs2::FileExt::try_lock_exclusive(&probe).is_err());
        drop(writer);
        assert!(fs2::FileExt::try_lock_exclusive(&probe).is_ok());
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn repair_waits_for_a_live_writer_and_keeps_its_entries() {
        let path = tmp_path("repair_race.smh");
        let _ = std::fs::remove_file(&path);
        let _ = std::fs::remove_file(lock_path(&path));
        let cfg = Config::default_valid();
        let mut writer = SessionWriter::open(&path, cfg.clone()).unwrap();
        writer.append_frame(&frame("one")).unwrap();

        let repair_path = path.clone();
        let limit = cfg.frame_bytes_max;
        let (entered, repair_started) = std::sync::mpsc::sync_channel(1);
        let repair = std::thread::spawn(move || {
            entered.send(()).unwrap();
            repair_session(&repair_path, limit).unwrap()
        });

        // synchronize: the repair has started; the writer's lock holds it
        // until the drop, so an append now is still committed to the file
        // the repair will republish.
        repair_started
            .recv_timeout(std::time::Duration::from_secs(10))
            .unwrap();
        writer.append_frame(&frame("two")).unwrap();
        drop(writer);

        let recovery = repair.join().unwrap();
        assert!(recovery.frames.is_empty());
        let loaded = scanned_frames(&path, cfg.frame_bytes_max);
        let texts: Vec<String> = loaded.frames.iter().map(text_of).collect();
        assert_eq!(texts, vec!["one".to_string(), "two".to_string()]);
        let _ = std::fs::remove_file(&path);
        let _ = std::fs::remove_file(lock_path(&path));
    }

    #[test]
    fn unknown_frames_survive_write_and_load() {
        let path = tmp_path("unknown_frames.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let unknown = Frame::Unknown {
            kind: 0x4242,
            version: 3,
            payload: vec![1, 2, 3, 4, 5, 6],
        };
        {
            let mut w = SessionWriter::open(&path, cfg.clone()).unwrap();
            w.append_frame(&unknown).unwrap();
            w.append_frame(&frame("known")).unwrap();
        }
        let frames = scanned_frames(&path, cfg.frame_bytes_max).frames;
        assert_eq!(frames.len(), 2);
        match &frames[0] {
            Frame::Unknown {
                kind,
                version,
                payload,
            } => {
                assert_eq!(payload, &vec![1, 2, 3, 4, 5, 6]);
                assert_eq!((*kind, *version), (0x4242, 3));
            }
            other => panic!("expected unknown frame, got {other:?}"),
        }
        match &frames[1] {
            Frame::Known { entry } => assert_eq!(text(entry).as_deref(), Some("known")),
            other => panic!("expected known frame, got {other:?}"),
        }
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn end_to_end_tool_activity_persists_and_reconstructs() {
        let dir = tmp_path("e2e");
        std::fs::create_dir_all(&dir).unwrap();
        let workdir = dir.join("work");
        std::fs::create_dir_all(&workdir).unwrap();
        let session_path = dir.join("e2e.smh");
        let _ = std::fs::remove_file(&session_path);
        let cfg = Config::default_valid();
        let opened_id;
        {
            let opened = open_session(&session_path, cfg.clone()).unwrap();
            opened_id = opened.session.id();
            let mut ts = crate::tools::ToolSession::with_session(
                workdir.clone(),
                opened.session,
                opened.writer,
            );
            ts.invoke(
                "write",
                &ToolArguments::from_serializable(
                    &serde_json::json!({"path": "out/hello.txt", "content": "hi"}),
                )
                .unwrap(),
            )
            .unwrap();
            ts.invoke(
                "read",
                &ToolArguments::from_serializable(&serde_json::json!({"path": "out/hello.txt"}))
                    .unwrap(),
            )
            .unwrap();
        }
        let restored = SessionReader::open(&session_path)
            .unwrap()
            .selected_session(cfg.frame_bytes_max)
            .unwrap();
        assert_eq!(restored.id(), opened_id);
        assert_eq!(restored.active_branch().entries().len(), 6);
        // Tool call/result/completion triples stay adjacent and ordered.
        let kinds: Vec<&str> = restored
            .active_branch()
            .entries()
            .iter()
            .map(|e| match e.kind {
                EntryKind::ToolCall { .. } => "call",
                EntryKind::ToolResult { .. } => "result",
                _ => "other",
            })
            .collect();
        assert_eq!(
            kinds,
            vec!["call", "result", "other", "call", "result", "other"]
        );
        // The file effect actually happened under the invocation workdir.
        assert_eq!(
            std::fs::read_to_string(workdir.join("out/hello.txt")).unwrap(),
            "hi"
        );
        let _ = std::fs::remove_file(&session_path);
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn reopened_session_keeps_its_identity_and_replays_identically() {
        let path = tmp_path("identity.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let created = {
            let mut opened = open_session(&path, cfg.clone()).unwrap();
            opened.writer.append_frame(&frame("one")).unwrap();
            opened.session
        };
        let first = SessionReader::open(&path).unwrap();
        let second = SessionReader::open(&path).unwrap();
        let first_header = first.header(cfg.frame_bytes_max).unwrap();
        let second_header = second.header(cfg.frame_bytes_max).unwrap();
        assert_eq!(first_header.session_id, created.id());
        assert_eq!(first_header.branch_id, created.active_branch().id());
        assert_eq!(second_header.session_id, first_header.session_id);

        // Replay evidence is identical across independent durable readers.
        let records = |reader: &SessionReader| {
            let mut records = Vec::new();
            crate::trace::replay(reader, cfg.frame_bytes_max, |record| {
                records.push(record);
                Ok(())
            })
            .unwrap();
            records
        };
        assert_eq!(records(&first), records(&second));
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn forking_publishes_a_new_session_file_and_leaves_the_source_intact() {
        let dir = tmp_path("fork_dir");
        std::fs::create_dir_all(&dir).unwrap();
        let source_path = dir.join("source.smh");
        let fork_path = dir.join("fork.smh");
        let cfg = Config::default_valid();

        let (source_session, boundary_id, leaf_id) = {
            let mut opened = open_session(&source_path, cfg.clone()).unwrap();
            let root = *opened.session.append(&message("root")).unwrap();
            opened
                .writer
                .append_entry(&root, opened.session.bytes(&root))
                .unwrap();
            let boundary = *opened
                .session
                .append(&EntryContent::Meta {
                    kind: COMPACTION_KIND.to_string(),
                    detail: StructuredData::from_serializable(
                        &serde_json::json!({"summary": "", "kept": 1}),
                    )
                    .unwrap(),
                })
                .unwrap();
            opened
                .writer
                .append_entry(&boundary, opened.session.bytes(&boundary))
                .unwrap();
            let tip = *opened.session.append(&message("after")).unwrap();
            opened
                .writer
                .append_entry(&tip, opened.session.bytes(&tip))
                .unwrap();
            assert_ne!(root.id, tip.id);
            (opened.session, boundary.id, tip.id)
        };

        let source_reader = SessionReader::open(&source_path).unwrap();
        let fork_id = {
            let forked = source_reader
                .fork_at(boundary_id, &fork_path, cfg.clone())
                .unwrap();
            assert_ne!(forked.session.id(), source_session.id());
            assert_eq!(forked.session.selected_id(), Some(boundary_id));
            assert_eq!(forked.session.compaction_boundary(), Some(boundary_id));
            assert!(forked.recovery.damage.is_empty());
            forked.session.id()
        };

        // The fork is durable: reopening restores the same identity and leaf.
        {
            let reopened = open_session(&fork_path, cfg.clone()).unwrap();
            assert_eq!(reopened.session.id(), fork_id);
            assert_eq!(reopened.session.selected_id(), Some(boundary_id));
            assert_eq!(reopened.session.active_branch().entries().len(), 1);
            assert_eq!(reopened.session.compaction_boundary(), Some(boundary_id));
            // Full historical chain remains on disk, including pre-compaction content.
            let mut history = Vec::new();
            SessionReader::open(&fork_path)
                .unwrap()
                .replay_at(boundary_id, cfg.frame_bytes_max, |entry| {
                    history.push(entry);
                    Ok(())
                })
                .unwrap();
            assert_eq!(history.len(), 2);
            assert_eq!(
                history[0].content,
                source_session.bytes(&source_session.active_branch().entries()[0])
            );
        }

        // The source keeps its own identity, tip, and entry count.
        {
            let source_again = open_session(&source_path, cfg.clone()).unwrap();
            assert_eq!(source_again.session.id(), source_session.id());
            assert_eq!(source_again.session.selected_id(), Some(leaf_id));
            assert_eq!(source_again.session.active_branch().entries().len(), 2);
            let mut count = 0;
            SessionReader::open(&source_path)
                .unwrap()
                .replay_at(leaf_id, cfg.frame_bytes_max, |_| {
                    count += 1;
                    Ok(())
                })
                .unwrap();
            assert_eq!(count, 3);
        }

        // A populated target is refused instead of overwritten.
        let error = source_reader
            .fork_at(boundary_id, &fork_path, cfg)
            .unwrap_err();
        assert_eq!(error.code(), "SESSION_EXISTS");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn legacy_session_without_prologue_is_rejected_without_repair() {
        let path = tmp_path("legacy-no-prologue.smh");
        let bytes = frame("legacy").encode(1 << 20).unwrap();
        std::fs::write(&path, &bytes).unwrap();
        assert_eq!(
            open_session(&path, Config::default_valid())
                .unwrap_err()
                .code(),
            "SESSION_PROLOGUE"
        );
        assert_eq!(std::fs::read(&path).unwrap(), bytes);
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn session_file_without_header_is_rejected() {
        let path = tmp_path("headerless.smh");
        let cfg = Config::default_valid();
        std::fs::write(
            &path,
            file_bytes(frame("orphan").encode(cfg.frame_bytes_max).unwrap()),
        )
        .unwrap();
        let error = open_session(&path, cfg).unwrap_err();
        assert_eq!(error.code(), "SESSION_HEADER_MISSING");
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn cancellation_stops_replay_at_entry_boundary_and_leaves_no_fork() {
        let path = tmp_path("cancel-replay.smh");
        let fork = tmp_path("cancel-replay-fork.smh");
        let _ = std::fs::remove_file(&path);
        let _ = std::fs::remove_file(&fork);
        let config = Config::default_valid();
        let mut opened = open_session(&path, config.clone()).unwrap();
        let root = entry("root");
        let child = EntryFrame::new(Some(root.id), &message("child")).unwrap();
        for entry in [&root, &child] {
            opened
                .writer
                .append_frame(&Frame::Known {
                    entry: entry.clone(),
                })
                .unwrap();
        }
        drop(opened);
        let reader = SessionReader::open(&path).unwrap();
        let cancel = CancelHandle::new();
        let mut visited = 0;
        let error = reader
            .replay_at_cancelled(child.id, config.frame_bytes_max, &cancel, |_| {
                visited += 1;
                cancel.cancel();
                Ok(())
            })
            .unwrap_err();
        assert_eq!(error.code(), "CANCELLED");
        assert_eq!(visited, 1);
        assert_eq!(
            reader
                .fork_at_cancelled(child.id, &fork, config, &cancel)
                .unwrap_err()
                .code(),
            "CANCELLED"
        );
        assert!(!fork.exists());
        drop(reader);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn reader_drop_releases_an_inherited_snapshot_lock() {
        let path = tmp_path("reader-drop-unlocks-inherited-lock.smh");
        let _ = std::fs::remove_file(&path);
        let opened = open_session(&path, Config::default_valid()).unwrap();
        drop(opened);
        let reader = SessionReader::open(&path).unwrap();
        // A fork inherits this open-file description.  Closing only this process's
        // descriptor must still release the maintenance lock before the child execs.
        let inherited_readers = reader.readers.as_ref().unwrap().try_clone().unwrap();
        drop(reader);
        let coordination = maintenance_lock(&path).unwrap();
        drop(coordination);
        drop(inherited_readers);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn checkpoint_tail_snapshots_reopen_to_the_last_authoritative_entry() {
        let path = tmp_path("checkpoint-tail-snapshots.smh");
        let _ = std::fs::remove_file(&path);
        let cfg = Config::default_valid();
        let (before_checkpoint, selected, boundary, ancestry) = {
            let mut opened = open_session(&path, cfg.clone()).unwrap();
            let root = *opened.session.append(&message("root")).unwrap();
            opened
                .writer
                .append_entry(&root, opened.session.bytes(&root))
                .unwrap();
            let boundary = *opened
                .session
                .append(&EntryContent::Meta {
                    kind: COMPACTION_KIND.to_string(),
                    detail: StructuredData::from_serializable(
                        &serde_json::json!({"summary": "", "kept": 1}),
                    )
                    .unwrap(),
                })
                .unwrap();
            opened
                .writer
                .append_entry(&boundary, opened.session.bytes(&boundary))
                .unwrap();
            let mut ancestry = vec![root.id, boundary.id];
            for _ in 0..61 {
                let record = *opened.session.append(&message("turn")).unwrap();
                opened
                    .writer
                    .append_entry(&record, opened.session.bytes(&record))
                    .unwrap();
                ancestry.push(record.id);
            }
            let record = *opened.session.append(&message("selected")).unwrap();
            opened
                .writer
                .append_entry(&record, opened.session.bytes(&record))
                .unwrap();
            ancestry.push(record.id);
            (
                std::fs::read(&path).unwrap(),
                record.id,
                boundary.id,
                ancestry,
            )
        };
        let checkpoint = Frame::Checkpoint {
            id: selected,
            offset: 0,
        }
        .encode(cfg.frame_bytes_max)
        .unwrap();
        let checkpoint_at = before_checkpoint.len() - checkpoint.len();
        for end in checkpoint_at..before_checkpoint.len() {
            std::fs::write(&path, &before_checkpoint[..end]).unwrap();
            if end > checkpoint_at {
                assert_eq!(
                    SessionReader::open(&path)
                        .unwrap()
                        .scan(cfg.frame_bytes_max, |_| Ok(()))
                        .unwrap()
                        .torn_tail_at,
                    Some(u64::try_from(checkpoint_at).unwrap())
                );
            }
            let reopened = open_session(&path, cfg.clone()).unwrap();
            assert_eq!(reopened.session.selected_id(), Some(selected));
            assert_eq!(reopened.session.compaction_boundary(), Some(boundary));
            drop(reopened);
            let mut restored_ancestry = Vec::new();
            SessionReader::open(&path)
                .unwrap()
                .replay_at(selected, cfg.frame_bytes_max, |entry| {
                    restored_ancestry.push(entry.id);
                    Ok(())
                })
                .unwrap();
            assert_eq!(restored_ancestry, ancestry);
            assert_eq!(
                SessionReader::open(&path)
                    .unwrap()
                    .scan(cfg.frame_bytes_max, |_| Ok(()))
                    .unwrap()
                    .torn_tail_at,
                None
            );
        }
        let _ = std::fs::remove_file(path);
    }

    fn publication_fixture(path: &Path, cfg: &Config) -> (Vec<u8>, [EntryId; 3]) {
        let mut opened = open_session(path, cfg.clone()).unwrap();
        let root = *opened.session.append(&message("root")).unwrap();
        opened
            .writer
            .append_entry(&root, opened.session.bytes(&root))
            .unwrap();
        let boundary = *opened
            .session
            .append(&EntryContent::Meta {
                kind: COMPACTION_KIND.to_string(),
                detail: StructuredData::from_serializable(
                    &serde_json::json!({"summary": "", "kept": 1}),
                )
                .unwrap(),
            })
            .unwrap();
        opened
            .writer
            .append_entry(&boundary, opened.session.bytes(&boundary))
            .unwrap();
        let leaf = *opened.session.append(&message("leaf")).unwrap();
        opened
            .writer
            .append_entry(&leaf, opened.session.bytes(&leaf))
            .unwrap();
        opened
            .writer
            .append_frame(&Frame::Unknown {
                kind: 99,
                version: 1,
                payload: b"preserve me".to_vec(),
            })
            .unwrap();
        drop(opened);
        (
            std::fs::read(path).unwrap(),
            [root.id, boundary.id, leaf.id],
        )
    }

    fn assert_complete_publication(path: &Path, cfg: &Config, ids: [EntryId; 3], unknown: bool) {
        let reader = SessionReader::open(path).unwrap();
        reader.verify_full(cfg.frame_bytes_max).unwrap();
        let session = reader.selected_session(cfg.frame_bytes_max).unwrap();
        assert_eq!(session.selected_id(), Some(ids[2]));
        assert_eq!(session.compaction_boundary(), Some(ids[1]));
        let mut ancestry = Vec::new();
        reader
            .replay_at(ids[2], cfg.frame_bytes_max, |entry| {
                ancestry.push(entry.id);
                Ok(())
            })
            .unwrap();
        assert_eq!(ancestry, ids);
        assert_eq!(
            scanned_frames(path, cfg.frame_bytes_max)
                .frames
                .iter()
                .any(|frame| matches!(frame, Frame::Unknown { kind: 99, .. })),
            unknown
        );
    }

    fn publication_temps(dir: &Path, operation: &str) -> Vec<PathBuf> {
        std::fs::read_dir(dir)
            .unwrap()
            .map(|entry| entry.unwrap().path())
            .filter(|path| {
                path.file_name()
                    .and_then(|name| name.to_str())
                    .is_some_and(|name| name.contains(&format!(".smith-{operation}-")))
            })
            .collect()
    }

    #[test]
    fn fork_published_checkpoint_reopens_complete_history() {
        let dir = tmp_path("fork-hard-link-interval");
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        let source = dir.join("source.smh");
        let target = dir.join("fork.smh");
        let cfg = Config::default_valid();
        let (_, ids) = publication_fixture(&source, &cfg);
        let observed = std::rc::Rc::new(std::cell::Cell::new(false));
        let observed_at_hook = std::rc::Rc::clone(&observed);
        let target_at_hook = target.clone();
        set_publication_hook(move |point| {
            if point == PublicationCheckpoint::Published {
                observed_at_hook.set(true);
                assert!(SessionReader::open(&target_at_hook).is_ok());
            }
        });
        SessionReader::open(&source)
            .unwrap()
            .fork_at(ids[2], &target, cfg)
            .unwrap();
        clear_publication_hook();
        assert!(observed.get());
        let _ = std::fs::remove_dir_all(dir);
    }

    #[test]
    fn fork_and_repair_publication_interruptions_never_expose_partial_sessions() {
        use std::panic::{AssertUnwindSafe, catch_unwind, panic_any};

        let cfg = Config::default_valid();
        let points = [
            PublicationCheckpoint::TempCreated,
            PublicationCheckpoint::PartialWrite,
            PublicationCheckpoint::CompletedWrite,
            PublicationCheckpoint::TempSynced,
            PublicationCheckpoint::Published,
            PublicationCheckpoint::ParentSynced,
            PublicationCheckpoint::Cleanup,
        ];
        for point in points {
            let dir = tmp_path(&format!("publication-interrupt-{point:?}"));
            let _ = std::fs::remove_dir_all(&dir);
            std::fs::create_dir_all(&dir).unwrap();
            let source = dir.join("source.smh");
            let target = dir.join("fork.smh");
            let (before, ids) = publication_fixture(&source, &cfg);
            let reader = SessionReader::open(&source).unwrap();
            set_publication_hook(move |actual| {
                if actual == point {
                    // Panic simulates abrupt control-flow loss: fork's error cleanup is not run.
                    panic_any(actual);
                }
            });
            assert!(
                catch_unwind(AssertUnwindSafe(|| reader.fork_at(
                    ids[2],
                    &target,
                    cfg.clone()
                )))
                .is_err()
            );
            clear_publication_hook();
            assert_eq!(std::fs::read(&source).unwrap(), before);
            assert_complete_publication(&source, &cfg, ids, true);
            if matches!(
                point,
                PublicationCheckpoint::TempCreated
                    | PublicationCheckpoint::PartialWrite
                    | PublicationCheckpoint::CompletedWrite
                    | PublicationCheckpoint::TempSynced
            ) {
                assert!(!target.exists());
                assert!(SessionReader::open(&target).is_err());
                assert_eq!(publication_temps(&dir, "fork").len(), 1);
            } else {
                assert_complete_publication(&target, &cfg, ids, false);
            }
            drop(reader);
            let _ = std::fs::remove_dir_all(dir);
        }

        for point in points {
            let dir = tmp_path(&format!("repair-publication-interrupt-{point:?}"));
            let _ = std::fs::remove_dir_all(&dir);
            std::fs::create_dir_all(&dir).unwrap();
            let source = dir.join("source.smh");
            let (before, ids) = publication_fixture(&source, &cfg);
            set_publication_hook(move |actual| {
                if actual == point {
                    // Panic simulates abrupt control-flow loss: repair's error cleanup is not run.
                    panic_any(actual);
                }
            });
            assert!(
                catch_unwind(AssertUnwindSafe(|| repair_session(
                    &source,
                    cfg.frame_bytes_max
                )))
                .is_err()
            );
            clear_publication_hook();
            if matches!(
                point,
                PublicationCheckpoint::TempCreated
                    | PublicationCheckpoint::PartialWrite
                    | PublicationCheckpoint::CompletedWrite
                    | PublicationCheckpoint::TempSynced
            ) {
                assert_eq!(std::fs::read(&source).unwrap(), before);
                assert_complete_publication(&source, &cfg, ids, true);
                assert_eq!(publication_temps(&dir, "repair").len(), 1);
            } else {
                assert_complete_publication(&source, &cfg, ids, true);
                assert!(publication_temps(&dir, "repair").is_empty());
            }
            let _ = std::fs::remove_dir_all(dir);
        }
    }

    #[test]
    fn fork_publish_collision_preserves_target_and_temporary_source() {
        let dir = tmp_path("fork-publish-failure");
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        let source = dir.join("source.smh");
        let target = dir.join("fork.smh");
        let cfg = Config::default_valid();
        let (before, ids) = publication_fixture(&source, &cfg);
        let occupied = target.clone();
        set_publication_hook(move |point| {
            if point == PublicationCheckpoint::TempSynced {
                std::fs::write(&occupied, b"occupied during publish").unwrap();
            }
        });
        let error = SessionReader::open(&source)
            .unwrap()
            .fork_at(ids[2], &target, cfg)
            .unwrap_err();
        clear_publication_hook();
        match error {
            SmithError::Storage {
                code,
                operation,
                path,
                message,
                publication,
            } => {
                assert_eq!(code, smith::error::StorageCode::CreatePublish);
                assert_eq!(publication, None);
                assert_eq!(operation.as_str(), "publish");
                assert_eq!(path, target);
                assert!(!message.is_empty());
            }
            other => panic!("expected publication storage error, got {other:?}"),
        }
        assert_eq!(std::fs::read(&source).unwrap(), before);
        assert_eq!(std::fs::read(&target).unwrap(), b"occupied during publish");
        assert_eq!(publication_temps(&dir, "fork").len(), 1);
        let _ = std::fs::remove_dir_all(dir);
    }

    #[test]
    fn concurrent_publishers_choose_exactly_one_winner_without_overwrite() {
        use std::sync::{Arc, Barrier};

        let dir = tmp_path("concurrent-no-clobber-publication");
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        let target = dir.join("target.smh");
        let barrier = Arc::new(Barrier::new(4));
        let mut workers = Vec::new();
        for index in 0..4 {
            let temp = dir.join(format!("temp-{index}.smh"));
            let bytes = format!("publisher-{index}").into_bytes();
            let mut file = File::create(&temp).unwrap();
            file.write_all(&bytes).unwrap();
            file.sync_all().unwrap();
            let target = target.clone();
            let barrier = Arc::clone(&barrier);
            workers.push(std::thread::spawn(move || {
                barrier.wait();
                (bytes, temp.clone(), publish_no_clobber(&temp, &target))
            }));
        }
        let results: Vec<_> = workers
            .into_iter()
            .map(|worker| worker.join().unwrap())
            .collect();
        let winners: Vec<_> = results
            .iter()
            .filter(|(_, _, result)| result.is_ok())
            .collect();
        assert_eq!(winners.len(), 1);
        assert_eq!(std::fs::read(&target).unwrap(), winners[0].0);
        for (_, temp, result) in results {
            assert_eq!(temp.exists(), result.is_err());
        }
        let _ = std::fs::remove_dir_all(dir);
    }

    #[cfg(unix)]
    #[test]
    fn no_clobber_publication_never_leaves_an_alias() {
        use std::os::unix::fs::MetadataExt;

        let dir = tmp_path("no-clobber-publication-nlink");
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        let temp = dir.join("temp.smh");
        let target = dir.join("target.smh");
        std::fs::write(&temp, b"new").unwrap();
        publish_no_clobber(&temp, &target).unwrap();
        assert!(!temp.exists());
        assert_eq!(std::fs::metadata(&target).unwrap().nlink(), 1);

        std::fs::write(&temp, b"retry").unwrap();
        let before = std::fs::read(&target).unwrap();
        assert!(publish_no_clobber(&temp, &target).is_err());
        assert_eq!(std::fs::read(&target).unwrap(), before);
        assert_eq!(std::fs::metadata(&temp).unwrap().nlink(), 1);
        let _ = std::fs::remove_dir_all(dir);
    }

    #[test]
    fn parent_sync_failure_reports_published_durability_uncertain_on_wire() {
        let dir = tmp_path("fork-parent-sync-failure");
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        let source = dir.join("source.smh");
        let target = dir.join("fork.smh");
        let cfg = Config::default_valid();
        let (before, ids) = publication_fixture(&source, &cfg);
        set_parent_sync_failure(true);
        let error = SessionReader::open(&source)
            .unwrap()
            .fork_at(ids[2], &target, cfg.clone())
            .unwrap_err();
        set_parent_sync_failure(false);
        assert_eq!(std::fs::read(&source).unwrap(), before);
        assert_complete_publication(&target, &cfg, ids, false);
        assert_eq!(
            serde_json::to_string(&error).unwrap(),
            format!(
                r#"{{"Storage":{{"code":"STORE_DIR_SYNC","operation":"sync parent directory after publication","path":"{}","message":"injected parent directory sync failure","publication":"published-durability-uncertain"}}}}"#,
                dir.display()
            )
        );
        match error {
            SmithError::Storage { publication, .. } => assert_eq!(
                publication,
                Some(smith::error::PublicationState::PublishedDurabilityUncertain)
            ),
            other => panic!("expected published storage error, got {other:?}"),
        }
        let _ = std::fs::remove_dir_all(dir);
    }

    #[test]
    fn temporary_name_exhaustion_reports_final_attempt_without_mutation_or_leak() {
        let dir = tmp_path("temporary-name-exhaustion");
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        let path = dir.join("session.smh");
        let id = SessionId::from_u128(7);
        for attempt in 0..128 {
            std::fs::create_dir(
                path.with_file_name(format!("session.smh.smith-create-{id}-{attempt}.tmp")),
            )
            .unwrap();
        }
        let before = std::fs::read_dir(&dir).unwrap().count();
        let error = new_temp_file(&path, "create", id).unwrap_err();
        match error {
            SmithError::Storage {
                code,
                operation,
                path: attempted,
                message,
                ..
            } => {
                assert_eq!(code, smith::error::StorageCode::CreateTmp);
                assert_eq!(operation.as_str(), "create temporary file");
                assert_eq!(
                    attempted,
                    path.with_file_name(format!("session.smh.smith-create-{id}-127.tmp"))
                );
                assert!(!message.is_empty());
            }
            other => panic!("expected storage error, got {other:?}"),
        }
        assert!(!path.exists());
        assert_eq!(std::fs::read_dir(&dir).unwrap().count(), before);
        let _ = std::fs::remove_dir_all(dir);
    }

    #[test]
    fn uncertain_complete_admission_poison_stops_mutation_until_reopen() {
        let path = tmp_path("uncertain-admission");
        let mut opened = create_session(&path, &Session::new(), Config::default_valid()).unwrap();
        let entry = EntryFrame::new(
            None,
            &EntryContent::Message(Message::with_text(Role::User, "input")),
        )
        .unwrap();
        let id = entry.id;
        let frame = Frame::Admission {
            entry,
            key: Some("key".into()),
        };
        let bytes = frame
            .encode(Config::default_valid().frame_bytes_max)
            .unwrap();
        let error = opened.writer.write_step(|file| {
            file.write_all(&bytes).unwrap();
            Err(admission_fault(
                "injected uncertain persistence acknowledgement",
            ))
        });
        assert!(error.is_err());
        assert!(
            opened
                .writer
                .admit(&Message::with_text(Role::User, "input"), Some("key"), None)
                .is_err()
        );
        drop(opened);
        let mut recovered = open_session(&path, Config::default_valid()).unwrap();
        let receipt = recovered
            .writer
            .admit(&Message::with_text(Role::User, "input"), Some("key"), None)
            .unwrap();
        assert_eq!(receipt.submission_id, id);
        drop(recovered);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn header_len_matches_protocol() {
        assert_eq!(crate::frame::HEADER_LEN, 12);
        assert_eq!(crate::frame::BODY_PREFIX_LEN, 8);
    }
}