//! 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, } /// 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), } /// 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 { 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, lifecycle_invocation: Option, lifecycle_effect: Option, lifecycle_ordinal: u16, live: Vec<(EntryId, WorkStatus)>, status: Option, output: Option, tool: Option, nested: Option<(EntryId, smith::id::ToolCallId, u16)>, nested_progress: u16, tool_tip: Option, nested_causal: Option, nested_parents: Vec<( (EntryId, smith::id::ToolCallId, u16), crate::metadata::NestedCausality, )>, payload: Option, 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, 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::lock(path, false) } fn try_acquire(path: &Path) -> Result { Self::lock(path, true) } fn lock(path: &Path, nonblocking: bool) -> Result { 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 { 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::().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; #[cfg(test)] thread_local! { static PUBLICATION_HOOK: std::cell::RefCell> = const { std::cell::RefCell::new(None) }; static PARENT_SYNC_FAILURE: std::cell::Cell = 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>(path: P, config: Config) -> Result { 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>(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::().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 { 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, ) -> Result { 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 { 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 { 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 { 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> { 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 { 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 { 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, output: Option, ) -> 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, output: Option, ) -> Result { 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, ) -> 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 { 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 { 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 { 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 { 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 { 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 { 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, 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> { 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 { 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 = const { std::cell::Cell::new(0) }; static PROOF_VISITS: std::cell::Cell = const { std::cell::Cell::new(0) }; static CHECKPOINT_HITS: std::cell::Cell = 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, has_work: bool, cancel: Option, } #[derive(Clone, Copy)] struct ProofEntry { id: EntryId, parent: Option, offset: u64, parent_offset: Option, 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 { 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> { 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> { 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> { 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 { 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> { 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> { 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> { 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> { 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 { 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> { self.work_ledger(frame_bytes_max, Some(&submission_id)) .map(|ledger| ledger.output) } fn work_ledger(&self, max: usize, target: Option<&EntryId>) -> Result { 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 { 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, ) -> Result<(Proof, crate::session::SessionHeader, Option)> { 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, ) -> Result<(Proof, crate::session::SessionHeader, Option)> { 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 { #[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 { 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 { 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> { 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 { 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 { struct Counted<'a, R> { inner: R, bytes: &'a std::cell::Cell, } impl Read for Counted<'_, R> { fn read(&mut self, buffer: &mut [u8]) -> std::io::Result { 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> { 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 { 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> { 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> { self.selected_tip_with_cancel(max, Some(cancel.clone())) } fn selected_tip_with_cancel( &self, max: usize, cancel: Option, ) -> Result> { 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 { self.selected_session_with_cancel(max, None) } fn selected_session_with_cancel( &self, max: usize, cancel: Option, ) -> Result { self.context_at(max, cancel, None) } fn context_at( &self, max: usize, cancel: Option, at: Option<&EntryId>, ) -> Result { 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, 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 { 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 { 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, ) -> Result { 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::().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)>, id: EntryId, target: u64, parent: Option, parent_offset: Option, 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::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::open_with_cancel(path, Some(cancel)) } fn open_with_cancel(path: &Path, cancel: Option<&CancelHandle>) -> Result { 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 { 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, 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, report_damage: impl FnMut(SmithError) -> Result<()>, ) -> Result { 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, mut report_damage: impl FnMut(SmithError) -> Result<()>, ) -> Result { 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 { 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, Option)> { 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, 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) -> Result { 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 { 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 { 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(""), ))?; 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) -> 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, ) -> 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 { 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) -> Vec { 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::(), 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![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 = 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 = 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, [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 { 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); } }