Struct Store 

pub struct Store<L: LogBackend = CanonicalLog> { /* private fields */ }

The workspace store — a LogBackend plus the Pipeline that produces its records. The default backend is CanonicalLog (real filesystem); tests and crash-injection harnesses parameterize with their own LogBackend implementation.

Implementations

impl Store<CanonicalLog>

pub fn open(path: impl AsRef<Path>) -> Result<Self, StoreError>

Open or create a workspace at path. Convenience constructor that wires a real filesystem-backed CanonicalLog.

Errors

• StoreError::Log on any filesystem / I/O failure during open, scan, or truncate.

pub fn open_in_workspace( data_root: impl AsRef<Path>, workspace_id: WorkspaceId, ) -> Result<Self, StoreError>

Open or create a workspace-partitioned store under a shared data_root. The log lands at data_root/<workspace_hex>/canonical.log per workspace-model.md § 4.2. Parent directories are created on demand.

Two Stores opened under the same data_root but different WorkspaceId values land in disjoint directories — per spec § 2 the partition is structural, not policy-enforced.

Errors

• StoreError::Log on any filesystem / I/O failure.

impl<L: LogBackend> Store<L>

pub fn from_backend(log: L) -> Result<Self, StoreError>

Construct a Store over an arbitrary LogBackend. On open, crash-shaped orphan bytes past the last durable CHECKPOINT are truncated (spec § 10 recovery step), non-recoverable tail corruption is rejected without truncation, and SYMBOL_* events from the committed log are replayed into the pipeline’s symbol table so workspace state fully reconstructs across process restarts.

Errors

• StoreError::Log on any backend I/O failure.
• StoreError::CorruptTail if non-recoverable bytes are found past the last durable CHECKPOINT.
• StoreError::Pipeline if replay of a SYMBOL_* record fails (log corruption).

pub fn log_len(&self) -> u64

Committed log length in bytes.

pub fn pipeline(&self) -> &Pipeline

Read-only view of the underlying pipeline. Used by callers that want to issue read-path queries (execute_query) or inspect pipeline state without owning the whole store.

pub fn pipeline_mut(&mut self) -> &mut Pipeline

Mutable view of the pipeline. Exposed so tests and downstream callers can call execute_query (which needs &self, not &mut self, but the mut accessor keeps the door open for future read-path methods that do require exclusive borrow).

pub fn commit_batch( &mut self, input: &str, now: ClockTime, ) -> Result<EpisodeId, StoreError>

Compile a batch of agent input and commit it atomically.

The two phases run under the workspace’s single-writer invariant:

1. Pipeline compiles the input into a Vec<CanonicalRecord>. On pipeline error the pipeline’s in-memory state is already auto-rolled-back (per Pipeline::compile_batch’s clone-on- write contract) and no log bytes have been written.
2. Records + a CHECKPOINT marker are appended to the log.
3. The log is fsynced. On success the batch is durable and the new Episode ID is returned; on fsync failure the log is truncated to its pre-batch offset and the pipeline’s in-memory state is restored from a snapshot taken before step 1.

Errors

• StoreError::Pipeline if parse / bind / semantic / emit rejected the batch. In-memory state is unchanged; log is untouched.
• StoreError::Log if the append / sync / truncate sequence failed at any step. In-memory pipeline state is restored to its pre-batch snapshot; log is truncated back to pre-batch.

pub fn commit_batch_with_metadata( &mut self, input: &str, now: ClockTime, metadata: &EpisodeMetadata, ) -> Result<EpisodeId, StoreError>

Commit a batch and attach agent-visible Episode metadata (label, parent_episode, retracts) per episode-semantics.md § 4.2 / § 5. Same commit semantics as Self::commit_batch; when metadata is non-empty, an EpisodeMeta canonical record is emitted immediately before the CHECKPOINT.

Errors

Same as Self::commit_batch. If metadata.label exceeds the 256-byte cap (spec § 4.3) the commit fails with a StoreError::InvalidEpisodeMetadata before any log writes.