Struct CheckpointWriter 

pub struct CheckpointWriter { /* private fields */ }

Writer-side handle to the per-session checkpoint event log. One instance per session; held as Arc<CheckpointWriter> and shared between the executor (lifecycle calls) and the metrics tick (count + cursor + flush calls).

Implementations

impl CheckpointWriter

pub fn new( path: PathBuf, session: String, started_at: String, invocation: u32, ) -> Self

Construct a fresh writer for a brand-new session. Emits the leading session_start record before returning. Subsequent declare_phase / lifecycle calls append events onto the same log.

pub fn from_existing( path: PathBuf, doc: Checkpoint, new_checkpoint_at: String, new_invocation: u32, ) -> Self

Restore a writer from a previously-written document on resume. The caller is responsible for having parsed and version-checked the document via super::storage::read. The restored writer keeps the existing phase entries and emits a fresh session_start event with the new invocation counter — appending continues onto the same JSONL log per SRD-44a.

pub fn disabled(path: PathBuf) -> Self

A resume-inert writer for dry-runs: no checkpoint.jsonl is created, no flock is taken, and every lifecycle event is dropped before it reaches disk. A dry-run short-circuits ops and may run against placeholder params, so persisting its phases as “completed” would poison a later --resume-latest (SRD-44) — this constructor guarantees it can’t. The file handle targets /dev/null purely to keep the struct total; append_event never writes to it.

pub fn declare_phase(&self, identity: PhaseIdentity, skip_eligible: bool)

Declare a phase the run plans to execute. Called during pre-map for every phase; idempotent (re-declaration is a no-op so the resume path can declare the same phases the saved doc already lists).

pub fn phase_started(&self, identity: &PhaseIdentity)

Mark a declared phase as Running.

pub fn phase_completed(&self, identity: &PhaseIdentity, duration_secs: f64)

Mark a declared phase as Completed with the given wall-clock duration.

pub fn phase_failed(&self, identity: &PhaseIdentity, error: &str)

Mark a declared phase as Failed. The error message is preserved for resume diagnostics.

pub fn update_op_counts(&self, identity: &PhaseIdentity, counts: OpCounts)

Record op-execution counts from the live activity. Called from the metrics tick callback for the currently-running phase. Folds into the matching PhaseEntry and emits one phase_progress event per call — the reader keeps only the most recent per identity when folding.

pub fn update_phase_hash( &self, identity: &PhaseIdentity, hash: [u8; 32], params_consumed: Option<String>, )

Set the program-canonical hash on a declared phase.

pub fn update_cursor(&self, identity: &PhaseIdentity, cursor_state: Value)

Record the latest cursor-state snapshot for a Tier 2 phase.

pub fn emit_scope_enter( &self, kind: &str, coords: BTreeMap<String, Value>, path: Vec<BTreeMap<String, Value>>, )

Emit a scope_enter event marking entry into a for_each / for_combinations / do_while / do_until iteration. Per SRD-44a §“Event taxonomy”, coords is the {var: value} map for THIS scope’s own bindings and path is the leaf-first chain of enclosing scopes’ coords — together they pin the executor’s position in the scenario tree at iteration time. Scope events are write-and-go: the in-memory mirror has no slot to fold them into (the reader’s fold is also a no-op today), so this is one direct append_event.

pub fn emit_scope_exit( &self, kind: &str, coords: BTreeMap<String, Value>, path: Vec<BTreeMap<String, Value>>, outcome: &str, )

Emit a scope_exit event marking the end of one iteration. outcome is "completed" when the iteration’s terminal action returned Ok, "interrupted" when it returned an error or the executor unwound through a stop signal. Same write-and-go shape as emit_scope_enter.

pub fn flush(&self) -> Result<(), String>

Force a fdatasync(2) on the underlying log. Per SRD-44a §“Writer behaviour”, lifecycle records (start / completed / failed) deserve a per-event sync; the periodic progress tick can batch. The runtime calls this at every phase-lifecycle boundary so a crash between ticks loses at most one tick’s worth of progress.

pub fn snapshot(&self) -> Checkpoint

Read-only snapshot of the current in-memory document. Useful for diagnostics and tests.

pub fn mark_run_reached_end(&self)

Record that the runner reached its session-end boundary (the convergence point right before run_finished()). Early error returns and interrupts never get here, so the flag cleanly separates “the run ended” from “the run was cut short” for Self::resume_hint.

pub fn resume_hint(&self) -> Option<String>

If the workload has incomplete phases declared checkpoint: idempotent, return a multi-line hint string the runtime can show the operator on exit.

pub fn path(&self) -> &Path

Path the writer flushes to.