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);
}
}