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<S>(root: impl Into<PathBuf>, source: &S) -> Self

where S: StateSchemaSource + ?Sized,

Creates an empty run configuration using TimeAxisMetadata::default.

The schema is derived from a live SystemState or supplied directly as a SystemStateSchema. It is cloned only as an Arc-backed metadata handle; no scientific payload is cloned or retained.

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

Merges 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_storage(self, storage: StateStreamStorage) -> Self

Uses one persistence policy for concise stream declarations.

Storage supplied directly through StateStreamConfig::new remains stream-specific and takes precedence. Streams constructed with storage == None require this shared policy.

pub fn with_configuration(self, configuration: &ResolvedConfiguration) -> Self

Merges one resolved configuration into the recording’s user metadata.

Fixed and swept values retain their resolved JSON representation. The synthetic ordinal entry is always set from the configuration and therefore replaces any same-named input entry. Configuration values also replace same-named caller metadata, while unrelated metadata and RNG records are preserved. On a key collision, the most recently supplied source wins.

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 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 open_or_resume_from_latest_checkpoint( self, decoders: JsonPayloadDecoderRegistry, ) -> Result<(SystemStateWriter, Option<SystemState>), StorageError>

Creates a new recording or automatically resumes matching incomplete output from its newest complete-state checkpoint.

The checkpoint stream is inferred from the declared stream schemas. On continuation, records later than the restored checkpoint are removed from every stream before writing restarts. Existing output without a complete checkpoint is rejected.

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 temporary publication state is reconciled. Only the highest temporary 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. Every stream is rewound to that checkpoint iteration. Writer threads begin only after reconstruction and rewind succeed.

Trait Implementations

impl Debug for SystemStateWriterBuilder

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

Formats the value using the given formatter.