Struct SystemStateWriterBuilder 

pub struct SystemStateWriterBuilder { /* private fields */ }

Builder for one exclusive state-recording directory.

The builder owns only paths, immutable configuration, and a cheap shared SystemStateSchema handle. It opens no files and starts no threads before SystemStateWriterBuilder::create_new_recording, SystemStateWriterBuilder::continue_existing_recording, or SystemStateWriterBuilder::continue_recording_from_latest_checkpoint.

Implementations

impl SystemStateWriterBuilder

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

Creates an empty run configuration using TimeAxisMetadata::default.

spec is cloned only as an Arc-backed metadata handle. No scientific state or payload exists in this builder.

pub fn with_time_axis_metadata(self, time: TimeAxisMetadata) -> Self

Replaces the run’s temporal-coordinate documentation.

pub fn with_user_metadata(self, metadata: Map<String, Value>) -> Self

Replaces caller-owned metadata persisted under user_metadata.

Values must already be JSON-compatible. This metadata is structurally separate from scientific payloads and is written only to metadata.json.

pub fn with_shared_stream_limits( self, max_chunk_bytes: NonZeroU64, queue_bytes: NonZeroU64, ) -> Self

Uses one chunk target and one bounded-queue budget for concise stream declarations.

Limits supplied directly through StateStreamConfig::new remain stream-specific and take precedence. Streams added through SystemStateWriterBuilder::add_sampled_state_stream require these shared limits.

pub fn with_task_parameters(self, parameters: &TaskParameters) -> Self

Records one resolved task dictionary as the recording’s user metadata.

Fixed and swept values retain their resolved JSON representation. The synthetic task_ordinal entry is always set from the task itself and therefore replaces any same-named input entry.

pub fn add_state_stream(self, stream: StateStreamConfig) -> Self

Appends one logical stream declaration in deterministic metadata order.

Duplicate names or directories are reported at start so fluent builder assembly remains infallible.

pub fn add_sampled_state_stream<I, K>( self, name: impl Into<String>, fields: I, sampling_interval: SamplingInterval, ) -> Self

where I: IntoIterator<Item = K>, K: Into<String>,

Adds a sampled stream using writer-wide storage limits.

The logical name is also its relative output directory. Applications needing a different directory or per-stream limits can use SystemStateWriterBuilder::add_state_stream with an explicit StateStreamConfig.

pub fn create_new_recording(self) -> Result<SystemStateWriter, StorageError>

Validates the complete run, creates its exclusive output root, starts each bounded writer, and publishes initial metadata atomically.

Errors

Returns StorageError::RecordingDirectoryExists rather than replacing any existing filesystem entry. Configuration, state-key selection, directory creation, thread startup, JSON, and metadata durability failures retain their precise StorageError context. If startup fails after the root is created, the path is retained as diagnostic evidence and is never silently removed.

pub fn continue_existing_recording( self, ) -> Result<SystemStateWriter, StorageError>

Continues append writing in an existing running recording directory.

The complete builder configuration is compared with authoritative metadata before any chunk is recovered. Only the highest open chunk in each stream may be examined. This append-only entry point does not reconstruct scientific state; callers requiring a verified checkpoint must use Self::continue_recording_from_latest_checkpoint.

pub fn continue_recording_from_latest_checkpoint( self, stream: &str, decoders: JsonPayloadDecoderRegistry, ) -> Result<(SystemStateWriter, SystemState), StorageError>

Resumes a run and reconstructs its newest complete checkpoint state.

stream must cover the builder’s complete state specification, and decoders must cover every field. The returned state owns all decoded payloads. When reconstruction selects a sealed chunk, its exact byte count and SHA-256 checksum are verified before its final record is decoded. Writer threads begin only after reconstruction succeeds.

Trait Implementations

impl Debug for SystemStateWriterBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.