Struct SystemStateWriter 

pub struct SystemStateWriter { /* private fields */ }

Exclusive queued writer for all persistent streams in one recording.

This type is intentionally non-Clone. It owns the only writer handles and the only legal transition from running metadata to a terminal status. It owns no SystemState and never extends a payload borrow beyond one synchronous SystemStateWriter::observe_state call.

Implementations

impl SystemStateWriter

pub fn builder( root: impl Into<PathBuf>, spec: &SystemStateSchema, ) -> SystemStateWriterBuilder

Begins configuring a new exclusive state-recording directory.

pub fn recording_directory(&self) -> &Path

Returns the recording directory exactly as configured.

pub fn stream_names(&self) -> impl ExactSizeIterator<Item = &str>

Iterates logical stream names in deterministic declaration order.

pub fn observe_state(&mut self, state: &SystemState) -> Result<(), StorageError>

Offers the current live state to every configured sampling stream.

The writer first reads only the state’s iteration. Streams that are not due perform no field lookup, payload borrow, serialization, allocation, or queue operation. Every due stream encodes its selected fields before bounded queue admission, so backpressure retains only owned bytes and never extends a scientific payload borrow.

Errors

Returns state or payload serialization errors from a due stream, queue-limit and ordering errors, or the writer’s authoritative terminal failure.

pub fn flush_stream_to_storage(&self, stream: &str) -> Result<(), StorageError>

Durably seals every record accepted earlier by one logical stream.

This is an ordered per-stream checkpoint barrier, not merely a buffered file flush. A non-empty open chunk is synchronized, prepared in the sole metadata document, renamed to its sealed filename, and directory-synced before this method returns.

pub fn complete_recording(self) -> Result<CompletedRecording, StorageError>

Drains every stream, seals all chunks, and atomically publishes complete metadata.

The method consumes the coordinator, making repeated finish or sampling impossible in safe Rust. If a writer fails, all remaining writers are still drained and a best-effort failed metadata transition is attempted before the originating writer error is returned.

pub fn complete_recording_with_terminal_metadata( self, terminal_metadata: Map<String, Value>, ) -> Result<CompletedRecording, StorageError>

Completes the recording and atomically commits values known only at the terminal boundary.

Terminal values are stored separately from immutable creation-time user metadata and therefore cannot silently replace task parameters.

pub fn complete_recording_with_final_state( self, state: &SystemState, ) -> Result<CompletedRecording, StorageError>

Records one final state to every stream exactly once, then completes.

This terminal observation is independent of the sampling interval. A stream already recorded at the same iteration is skipped, while a non-aligned final iteration is encoded once. The writer therefore owns both interval-based and terminal sampling decisions; the simulation supplies only a borrowed state.

pub fn complete_recording_with_final_state_and_terminal_metadata( self, state: &SystemState, terminal_metadata: Map<String, Value>, ) -> Result<CompletedRecording, StorageError>

Records the final state exactly once and atomically commits terminal user metadata with successful status and operational timing.

pub fn mark_recording_failed( self, message: impl Into<String>, ) -> Result<(), StorageError>

Drains every stream and atomically records an intentional failed run.

This is appropriate when the simulation itself fails after storage has started. The supplied message is structural recording metadata and must not be empty or whitespace-only. Successfully accepted records remain as immutable chunks and are listed in the failed metadata, but StoredStateSeriesReader deliberately reconstructs only completed runs.

If a writer also fails, its error takes precedence as the returned and persisted reason; the caller’s message would no longer describe the authoritative storage termination.

pub fn mark_recording_failed_with_terminal_metadata( self, message: impl Into<String>, terminal_metadata: Map<String, Value>, ) -> Result<(), StorageError>

Records an intentional failure with terminal-only user metadata.