repositories / smith
smith
There are many coding harnesses - but this one is fast
owned by admin
smith-harness/src/storage.rs
Raw//! 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<smith_alloc::AllocationGroup>, Request)>,
thread: Option<std::thread::JoinHandle<()>>,
}
enum Request {
Open(Config, SyncSender<Result<Session>>),
OpenForExecution(Config, SyncSender<Result<Session>>),
Admit(
Message,
Option<String>,
SyncSender<Result<AdmissionReceipt>>,
),
Foreground(String, Option<String>, SyncSender<Result<Admission>>),
Phase(SyncSender<Result<Option<(EntryId, ExecutionPhase)>>>),
SetPhase(EntryId, ExecutionPhase, SyncSender<Result<()>>),
Notification(
EntryId,
String,
Option<String>,
smith_core::agent::Delivery,
SyncSender<Result<Admission>>,
),
Inspect(EntryId, SyncSender<Result<Option<WorkReceipt>>>),
Abort(Option<EntryId>, SyncSender<Result<EntryId>>),
Register(EntryId, smith::tool::CancelHandle, SyncSender<Result<()>>),
Unregister(EntryId, SyncSender<Result<()>>),
Append(EntryFrame, SyncSender<Result<()>>),
Commit(smith_core::frame::Frame, SyncSender<Result<()>>),
Claim(EntryId, SyncSender<Result<Session>>),
Settle(
EntryId,
Option<smith::stream::StopReason>,
Option<EntryFrame>,
SyncSender<Result<SettlementDisposition>>,
),
Selected(usize, SyncSender<Result<Session>>),
Verify(usize, SyncSender<Result<()>>),
Fork(EntryId, PathBuf, Config, SyncSender<Result<Session>>),
Window(
EntryId,
usize,
usize,
usize,
SyncSender<Result<Vec<EntryFrame>>>,
),
}
fn read_window(
path: &std::path::Path,
id: EntryId,
start: usize,
limit: usize,
max: usize,
) -> Result<Vec<EntryFrame>> {
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<AdmissionReceipt> {
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<smith_alloc::AllocationGroup>, Request)>(1);
let thread = std::thread::spawn(move || {
let _session = enter(Scope::Session);
let mut writer: Option<SessionWriter> = 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<T>(&self, build: impl FnOnce(SyncSender<Result<T>>) -> Request) -> Result<T> {
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<Session> {
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<Session> {
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<String>) -> Result<AdmissionReceipt> {
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<Admission> {
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<Option<WorkReceipt>> {
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<Option<(EntryId, ExecutionPhase)>> {
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<Admission> {
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<EntryId>) -> Result<EntryId> {
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<Session> {
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<SettlementDisposition> {
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<Session> {
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<Session> {
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<Vec<EntryFrame>> {
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::<Request>(), 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::<Vec<_>>(),
[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);
}
}