//! SMH-SPEC-SPEC0001: Sessions, bounded storage requests. //! //! Bounded storage requests: filesystem reads run on a dedicated worker. //! //! Callers own immutable results, never an open reader or ambient I/O in a //! core state transition. use smith::config::Config; use smith::error::{Result, SmithError}; use smith::id::EntryId; use smith::message::Message; use smith_alloc::{Scope, enter}; use smith_core::control::{Admission, ExecutionPhase, SettlementDisposition, WorkReceipt}; use smith_core::session::{EntryFrame, Session}; pub use smith_core::store::{AdmissionReceipt, WorkStatus}; use smith_core::store::{SessionReader, SessionWriter, open_session, open_session_for_execution}; use std::path::PathBuf; use std::sync::mpsc::{self, SyncSender}; /// Serialized operations on one session file. pub struct StorageWorker { tx: SyncSender<(Option, Request)>, thread: Option>, } enum Request { Open(Config, SyncSender>), OpenForExecution(Config, SyncSender>), Admit( Message, Option, SyncSender>, ), Foreground(String, Option, SyncSender>), Phase(SyncSender>>), SetPhase(EntryId, ExecutionPhase, SyncSender>), Notification( EntryId, String, Option, smith_core::agent::Delivery, SyncSender>, ), Inspect(EntryId, SyncSender>>), Abort(Option, SyncSender>), Register(EntryId, smith::tool::CancelHandle, SyncSender>), Unregister(EntryId, SyncSender>), Append(EntryFrame, SyncSender>), Commit(smith_core::frame::Frame, SyncSender>), Claim(EntryId, SyncSender>), Settle( EntryId, Option, Option, SyncSender>, ), Selected(usize, SyncSender>), Verify(usize, SyncSender>), Fork(EntryId, PathBuf, Config, SyncSender>), Window( EntryId, usize, usize, usize, SyncSender>>, ), } fn read_window( path: &std::path::Path, id: EntryId, start: usize, limit: usize, max: usize, ) -> Result> { SessionReader::open(path).and_then(|reader| { let mut result = Vec::with_capacity(limit); let mut position = 0; reader.replay_at(id, max, |entry| { if position >= start && result.len() < limit { result.push(entry); } position += 1; Ok(()) })?; Ok(result) }) } /// Durably admit one pending user message without scheduling execution. /// /// # Errors /// Returns writer-access, storage, or admission validation faults before any /// provider or tool work can start. pub fn admit( path: &std::path::Path, input: &Message, key: Option<&str>, ) -> Result { let mut opened = open_session(path, Config::default_valid())?; opened.writer.admit(input, key, None) } fn control_fault(message: &str) -> SmithError { SmithError::Session { code: smith::error::SessionCode::SessionIncompleteContext, message: message.into(), } } fn stopped() -> SmithError { SmithError::Session { code: smith::error::SessionCode::StorageWorkerStopped, message: "session storage worker stopped".into(), } } impl StorageWorker { /// Start a dedicated filesystem worker for `path`. #[must_use] #[expect( clippy::too_many_lines, reason = "one serialized request table owns writer acknowledgement and exact live-root binding" )] pub fn start(path: PathBuf) -> Self { let (tx, rx) = mpsc::sync_channel::<(Option, Request)>(1); let thread = std::thread::spawn(move || { let _session = enter(Scope::Session); let mut writer: Option = None; let mut live: Option<(EntryId, smith::tool::CancelHandle, ExecutionPhase)> = None; while let Ok((allocation_group, request)) = rx.recv() { let _allocation = allocation_group .as_ref() .map(smith_alloc::AllocationGroup::enter); let _request = enter(Scope::IoRequest); let execution_open = matches!(request, Request::OpenForExecution(..)); match request { Request::Open(config, reply) | Request::OpenForExecution(config, reply) => { let open = if execution_open { open_session_for_execution } else { open_session }; let result = if writer.is_some() { Err(control_fault( "writer already open; close backend before reopening", )) } else { open(&path, config).map(|opened| { writer = Some(opened.writer); opened.session }) }; // The requesting client may have stopped waiting. let _reply_result = reply.send(result); } Request::Foreground(text, key, reply) => { let result = writer .as_mut() .ok_or_else(stopped) .and_then(|writer| writer.admit_foreground(&text, key.as_deref())); let _reply_result = reply.send(result); } Request::Phase(reply) => { let _reply_result = reply.send(Ok(live.as_ref().map(|(id, _, phase)| (*id, *phase)))); } Request::SetPhase(id, phase, reply) => { let result = if let Some((bound, _, current)) = &mut live && *bound == id { *current = phase; Ok(()) } else { Err(control_fault("phase transition requires exact live root")) }; let _reply_result = reply.send(result); } Request::Notification(root, text, key, delivery, reply) => { let result = if live.as_ref().is_some_and(|(bound, _, phase)| { *bound == root && *phase == ExecutionPhase::Notifying }) { writer.as_mut().ok_or_else(stopped).and_then(|writer| { writer.admit_notification(root, &text, key.as_deref(), delivery) }) } else { Err(control_fault("notification window closed")) }; let _reply_result = reply.send(result); } Request::Inspect(id, reply) => { let result = writer .as_ref() .ok_or_else(stopped) .and_then(|writer| writer.inspect_work(id)); let _reply_result = reply.send(result); } Request::Abort(target, reply) => { let result = (|| { let id = target.or_else(|| live.as_ref().map(|(id, _, _)| *id)) .ok_or_else(|| control_fault("no live root is bound; explicit recovery identity required"))?; writer.as_mut().ok_or_else(stopped)?.request_cancel(id)?; if let Some((bound, cancel, _)) = &live && *bound == id { cancel.cancel(); } Ok(id) })(); let _reply_result = reply.send(result); } Request::Register(id, cancel, reply) => { let result = (|| { if live.is_some() { return Err(control_fault("a live root is already bound")); } let receipt = writer .as_ref() .ok_or_else(stopped)? .inspect_work(id)? .ok_or_else(|| control_fault("unknown root identity"))?; if receipt.status != WorkStatus::Running { return Err(control_fault( "only claimed running work may bind cancellation", )); } if receipt.cancel_requested { cancel.cancel(); } live = Some((id, cancel, ExecutionPhase::Running)); Ok(()) })(); let _reply_result = reply.send(result); } Request::Unregister(id, reply) => { if live.as_ref().is_some_and(|(bound, _, _)| *bound == id) { live = None; } let _reply_result = reply.send(Ok(())); } Request::Admit(input, key, reply) => { let result = writer .as_mut() .ok_or_else(stopped) .and_then(|writer| writer.admit(&input, key.as_deref(), None)); let _reply_result = reply.send(result); } Request::Claim(id, reply) => { let result = (|| { if writer.is_none() { writer = Some(open_session(&path, Config::default_valid())?.writer); } writer.as_mut().ok_or_else(stopped)?.claim(id) })(); let _reply_result = reply.send(result); } Request::Settle(id, reason, output, reply) => { let result = writer .as_mut() .ok_or_else(stopped) .and_then(|writer| writer.settle_execution(id, reason, output)); if matches!(result, Ok(SettlementDisposition::Committed)) && live.as_ref().is_some_and(|(bound, _, _)| *bound == id) { live = None; } let _reply_result = reply.send(result); } Request::Commit(frame, reply) => { let result = writer .as_mut() .ok_or_else(stopped) .and_then(|writer| writer.append_frame(&frame)); let _reply_result = reply.send(result); } Request::Append(entry, reply) => { let result = writer.as_mut().ok_or_else(stopped).and_then(|writer| { let record = smith_core::session::Entry { id: entry.id, parent: entry.parent, timestamp_ms: entry.timestamp_ms, kind: entry.kind, content: smith_core::session::Span { offset: 0, len: 0 }, }; writer.append_entry(&record, &entry.content) }); // The requesting client may have stopped waiting. let _reply_result = reply.send(result); } Request::Selected(max, reply) => { // The requesting client may have stopped waiting. let _reply_result = reply.send( SessionReader::open(&path) .and_then(|reader| reader.selected_session(max)), ); } Request::Verify(max, reply) => { // The requesting client may have stopped waiting. let _reply_result = reply.send( SessionReader::open(&path).and_then(|reader| reader.verify_full(max)), ); } Request::Fork(id, target, config, reply) => { // The requesting client may have stopped waiting. let _reply_result = reply.send( SessionReader::open(&path) .and_then(|reader| reader.fork_at(id, &target, config)) .map(|opened| opened.session), ); } Request::Window(id, start, limit, max, reply) => { // The requesting client may have stopped waiting. let _reply_result = reply.send(read_window(&path, id, start, limit, max)); } } } }); Self { tx, thread: Some(thread), } } fn request(&self, build: impl FnOnce(SyncSender>) -> Request) -> Result { let (tx, rx) = mpsc::sync_channel(1); self.tx .send((smith_alloc::AllocationGroup::current(), build(tx))) .map_err(|_| stopped())?; rx.recv().map_err(|_| stopped())? } /// Open or resume a writable session; keep writer ownership on worker. /// /// # Errors /// Returns a storage or worker fault. pub fn open(&self, config: Config) -> Result { self.request(|reply| Request::Open(config, reply)) } /// Open a session only when no durable submission is awaiting settlement. /// /// # Errors /// Returns an incomplete-context fault before provider, credential, or tool setup. pub fn open_for_execution(&self, config: Config) -> Result { self.request(|reply| Request::OpenForExecution(config, reply)) } /// Admit a user message through the same serialized writer as execution. /// /// # Errors /// Returns admission, persistence, or worker faults before acknowledging input. pub fn admit(&self, input: Message, key: Option) -> Result { self.request(|reply| Request::Admit(input, key, reply)) } /// Admit foreground input or inspect its original keyed receipt. /// /// # Errors /// Rejects new input while work remains unresolved or persistence is uncertain. pub fn admit_foreground(&self, text: &str, key: Option<&str>) -> Result { if text.len() > Config::default_valid().frame_bytes_max || key.is_some_and(|key| key.len() > smith_core::frame::ADMISSION_KEY_BYTES_MAX) { return Err(control_fault( "foreground input exceeds bounded storage request", )); } self.request(|reply| Request::Foreground(text.to_owned(), key.map(str::to_owned), reply)) } /// Inspect writer-acknowledged state, never an independent unfsynced reader. /// /// # Errors /// Rejects writer uncertainty or storage faults. pub fn inspect_work(&self, id: EntryId) -> Result> { self.request(|reply| Request::Inspect(id, reply)) } /// Inspect the executor-owned live phase without interpreting guest output. /// /// # Errors /// Returns storage worker availability faults. pub fn execution_phase(&self) -> Result> { self.request(Request::Phase) } /// Acknowledge a phase transition for exactly the bound root. /// /// # Errors /// Rejects stale identities or unavailable storage control. pub fn set_execution_phase(&self, id: EntryId, phase: ExecutionPhase) -> Result<()> { self.request(|reply| Request::SetPhase(id, phase, reply)) } /// Admit follow-up input while the exact root remains in notification cleanup. /// /// # Errors /// Rejects closed notification windows and durable admission faults. pub fn admit_notification( &self, root: EntryId, text: &str, key: Option<&str>, delivery: smith_core::agent::Delivery, ) -> Result { self.request(|reply| { Request::Notification(root, text.into(), key.map(str::to_owned), delivery, reply) }) } /// Sync cancellation intent before signalling the exact live root. /// /// # Errors /// Rejects duplicate, absent, queued, terminal, or uncertain work. pub fn abort(&self, id: Option) -> Result { self.request(|reply| Request::Abort(id, reply)) } /// Bind cancellation after claim and before the first execution effect. /// /// # Errors /// Rejects invalid work state, an occupied live binding, or uncertain storage. pub fn register_cancel(&self, id: EntryId, cancel: smith::tool::CancelHandle) -> Result<()> { self.request(|reply| Request::Register(id, cancel, reply)) } /// Release only this identity's live binding; never signal cancellation. /// /// # Errors /// Returns a worker communication fault. pub fn unregister_cancel(&self, id: EntryId) -> Result<()> { self.request(|reply| Request::Unregister(id, reply)) } /// Claim earliest queued root work before any dispatch. /// /// # Errors /// Returns storage or work-state faults without dispatching effects. pub fn claim(&self, id: EntryId) -> Result { self.request(|reply| Request::Claim(id, reply)) } /// Persist one core-owned terminal command atomically. /// /// # Errors /// Rejects non-settlement commands and invalid durable transitions. pub fn settle(&self, command: smith_core::frame::Frame) -> Result<()> { match self.settle_execution(command)? { SettlementDisposition::Committed => Ok(()), SettlementDisposition::CancelBeforeCommit => Err(SmithError::Cancelled), } } /// Serialize terminal commands against cancellation intent without false adoption. /// /// # Errors /// Returns invalid-command, transition, or storage faults. pub fn settle_execution( &self, command: smith_core::frame::Frame, ) -> Result { let smith_core::frame::Frame::Settlement { submission_id, reason, output, } = command else { return Err(stopped()); }; self.request(|reply| Request::Settle(submission_id, reason, output, reply)) } /// Acknowledge a typed completion, nested payload chunk, or chunk-publishing intent. /// Completion and root checkpoint remain one semantic frame. /// /// # Errors /// Rejects other commands, malformed members, invalid work state, or uncertain storage. pub fn commit_completion(&self, command: smith_core::frame::Frame) -> Result<()> { match &command { smith_core::frame::Frame::Commit { .. } | smith_core::frame::Frame::NestedCommit { .. } | smith_core::frame::Frame::NestedPayload { .. } => {} smith_core::frame::Frame::Known { entry } if matches!(smith_core::session::EntryContent::decode(&entry.content)?, smith_core::session::EntryContent::Meta { kind, .. } if kind == smith_core::metadata::NESTED_INTENT_KIND || smith_core::metadata::lifecycle::reserved(&kind)) => {} _ => return Err(stopped()), } self.request(|reply| Request::Commit(command, reply)) } /// Persist an entry before it becomes visible in the in-memory session. /// /// # Errors /// Returns a storage or worker fault. pub fn append(&self, entry: EntryFrame) -> Result<()> { self.request(|reply| Request::Append(entry, reply)) } /// Refresh the selected-context snapshot without retaining other branches. /// /// # Errors /// Returns a storage or worker fault. pub fn selected(&self, max: usize) -> Result { self.request(|reply| Request::Selected(max, reply)) } /// Verify the full file, not just the selected context. /// /// # Errors /// Returns an integrity or worker fault. pub fn verify(&self, max: usize) -> Result<()> { self.request(|reply| Request::Verify(max, reply)) } /// Fork a requested historical tip without reading on the caller thread. /// /// # Errors /// Returns a storage or worker fault. pub fn fork(&self, id: EntryId, target: PathBuf, config: Config) -> Result { self.request(|reply| Request::Fork(id, target, config, reply)) } /// Own a selected branch's bounded visible window, without retaining /// preceding or subsequent payloads. At most 64 entries per request. /// /// # Errors /// Returns a limit, ancestry, storage, or worker fault. pub fn window( &self, id: EntryId, start: usize, limit: usize, max: usize, ) -> Result> { if limit == 0 || limit > 64 { return Err(SmithError::Session { code: smith::error::SessionCode::StorageWindowLimit, message: "window limit must be 1..=64".into(), }); } self.request(|reply| Request::Window(id, start, limit, max, reply)) } } impl Drop for StorageWorker { fn drop(&mut self) { let (replacement, _rx) = mpsc::sync_channel(1); drop(std::mem::replace(&mut self.tx, replacement)); if let Some(thread) = self.thread.take() { // Drop cannot report a worker panic; closed requests report worker failure. let _join_result: std::thread::Result<()> = thread.join(); } } } #[cfg(test)] mod tests { use super::*; use smith::message::{Message, Role}; use smith_core::session::{EntryContent, EntryFrame}; #[test] #[cfg(target_arch = "x86_64")] fn completion_request_layout_is_exact() { assert_eq!(std::mem::size_of::(), 136); } fn history(path: &std::path::Path, entries: usize) -> EntryId { use smith_core::frame::Frame; use smith_core::store::SessionWriter; let session = Session::new(); let mut writer = SessionWriter::open(path, Config::default_valid()).unwrap(); writer .append_frame(&Frame::Header { header: session.header(), }) .unwrap(); let mut tip = None; for index in 0..entries { let entry = EntryFrame::new( tip, &EntryContent::Message(Message::with_text( Role::User, format!("{index} {}", "x".repeat(32 * 1024)), )), ) .unwrap(); tip = Some(entry.id); writer.append_frame(&Frame::Known { entry }).unwrap(); } writer.select_entry(tip.unwrap()).unwrap(); tip.unwrap() } #[test] fn worker_resumes_selected_context_and_reads_bounded_windows() { // SMH-SPEC-SPEC0001: Sessions, bounded working sets and replay. let dir = std::env::temp_dir().join(format!("smith-storage-worker-{}", std::process::id())); let _ = std::fs::remove_dir_all(&dir); std::fs::create_dir_all(&dir).unwrap(); let worker = StorageWorker::start(dir.join("session.smh")); let cfg = Config::default_valid(); let session = worker.open(cfg.clone()).unwrap(); assert!(session.selected_id().is_none()); // Writer lock remains on the worker after open, including idle periods. assert_eq!( smith_core::store::SessionWriter::open(dir.join("session.smh"), cfg.clone()) .unwrap_err() .code(), "STORE_BUSY" ); let root = EntryFrame::new( None, &EntryContent::Message(Message::with_text(Role::User, "root")), ) .unwrap(); let tip = EntryFrame::new( Some(root.id), &EntryContent::Message(Message::with_text(Role::Assistant, "tip")), ) .unwrap(); for entry in [&root, &tip] { worker.append(entry.clone()).unwrap(); } assert_eq!( worker.selected(cfg.frame_bytes_max).unwrap().selected_id(), Some(tip.id) ); worker.verify(cfg.frame_bytes_max).unwrap(); assert_eq!( worker .window(tip.id, 0, 2, cfg.frame_bytes_max) .unwrap() .into_iter() .map(|entry| entry.id) .collect::>(), [root.id, tip.id] ); assert_eq!( worker.window(tip.id, 1, 1, cfg.frame_bytes_max).unwrap()[0].id, tip.id ); assert_eq!( worker .window(tip.id, 0, 65, cfg.frame_bytes_max) .unwrap_err() .code(), "STORAGE_WINDOW_LIMIT" ); drop(worker); let _ = std::fs::remove_dir_all(dir); } #[test] fn request_propagates_root_allocation_observer_to_storage() { let root = std::env::temp_dir().join(format!( "smith-storage-observer-{}", smith::id::SessionId::new() )); std::fs::create_dir(&root).unwrap(); let path = root.join("session.smh"); let tip = history(&path, 1); let worker = StorageWorker::start(path); let group = smith_alloc::AllocationGroup::new().unwrap(); let before = smith_alloc::checkpoint().unwrap(); let guard = group.enter(); let rows = worker .window(tip, 0, 1, Config::default_valid().frame_bytes_max) .unwrap(); let local = smith_alloc::allocated_since(&before).unwrap(); let total = group.allocated().unwrap(); assert!( total.bytes > local.bytes + 32 * 1024, "storage allocations missing: {local:?} {total:?}" ); drop(rows); assert_eq!( group.allocated().unwrap(), total, "frees must not refund cumulative traffic" ); drop(guard); drop(worker); std::fs::remove_dir_all(root).unwrap(); } #[test] fn worker_window_peak_does_not_grow_with_history() { let root = std::env::temp_dir().join(format!("smith-storage-bounds-{}", std::process::id())); let _ = std::fs::remove_dir_all(&root); std::fs::create_dir_all(&root).unwrap(); let small_path = root.join("small.smh"); let large_path = root.join("large.smh"); let small_tip = history(&small_path, 4); let large_tip = history(&large_path, 128); let small_worker = StorageWorker::start(small_path); let large_worker = StorageWorker::start(large_path); let before = smith_alloc::snapshot(smith_alloc::Scope::IoRequest); let small_rows = small_worker .window(small_tip, 3, 1, Config::default_valid().frame_bytes_max) .unwrap(); let after_small = smith_alloc::snapshot(smith_alloc::Scope::IoRequest); let large_rows = large_worker .window(large_tip, 127, 1, Config::default_valid().frame_bytes_max) .unwrap(); let after_large = smith_alloc::snapshot(smith_alloc::Scope::IoRequest); assert_eq!((small_rows.len(), large_rows.len()), (1, 1)); assert!( after_small.allocations > before.allocations && after_large.allocations > after_small.allocations, "production worker requests must charge allocations to IoRequest" ); let retained = after_large.live; drop((small_rows, large_rows, small_worker, large_worker)); let released = smith_alloc::snapshot(smith_alloc::Scope::IoRequest).live; assert!( retained != released, "freeing rows outside worker scope must release their original IoRequest charge" ); let _ = std::fs::remove_dir_all(root); } }