Struct RunContext 

pub struct RunContext {
    pub run_id: RunId,
    pub run_store: Arc<dyn RunStore>,
    pub replay_store: Option<Arc<dyn ReplayStore>>,
    pub replay_cursor: Option<Arc<Mutex<ReplayCursor>>>,
    pub binding_digests: Arc<HashMap<String, BindingDigest>>,
    pub resume: bool,
    pub last_failure: Arc<Mutex<Option<LastFailure>>>,
}

Pairs a RunId with the RunStore used to persist its trace.

Threaded from the server entry points (POST /v1/tasks, POST /v1/tasks/:id/runs) down through TaskApplication::handle_with_run / TaskLaunchService::launch / EngineDispatcher (issue #13 run_id propagation) so every step the dispatcher runs can be appended to RunRecord.step_entries and the run’s id exposed to workers via Ctx.meta.runtime["run_id"]. Kept as a distinct type — rather than a new field on TaskApplicationInput — so the pre-existing exhaustive struct literal in mlua-swarm-cli’s MCP adapter (TaskApplicationInput { .. }, no run_ctx) keeps compiling unchanged: callers that don’t care about run tracing keep calling TaskApplication::handle / TaskLaunchService::launch, which pass None through internally.

Fields

run_id: RunId

The Run this dispatch’s steps should be traced into.

run_store: Arc<dyn RunStore>

Where to append StepEntry rows as steps are dispatched.

replay_store: Option<Arc<dyn ReplayStore>>

Optional ReplayStore the engine will append a Ctx-snapshot + step-output row to after every completed step (see crate::store::replay for the primitive). None (the default) disables logging entirely — pre-replay callers keep their behavior byte-for-byte.

replay_cursor: Option<Arc<Mutex<ReplayCursor>>>

Optional ReplayCursor the engine consults BEFORE dispatching each step. When present and the cursor has a matching row for (step_ref, input_hash, occurrence), the engine returns the stored DispatchOutcome::Pass(value) verbatim and skips the Adapter spawn — this is the replay-hit path. None (the default) disables replay entirely.

binding_digests: Arc<HashMap<String, BindingDigest>>

Run-pinned replay identity component, keyed by logical agent name.

resume: bool

Whether this dispatch is a resume / rerun-from of an existing Run rather than an initial launch. false (the default) marks an initial launch. Set to true ONLY by the server’s resume and rerun-from handlers — it is the sole, explicit signal that decides a backfilled snapshot’s SnapshotOrigin (never inferred from replay-cursor or step-entry state, whose wiring is free to change).

last_failure: Arc<Mutex<Option<LastFailure>>>

GH #76 error surface: shared single-slot breadcrumb the dispatcher writes when a step aborts the flow (DispatchOutcome::Blocked → EvalError). Read by the enclosing crate::service::task_launch::TaskLaunchService::launch map_err closure to populate the structured crate::service::task_launch::TaskLaunchError::FlowEval variant’s failed_step / verdict_value fields. None (the default) means no aborting step was recorded — either the run succeeded, or an error path fired that does not go through the dispatcher’s Blocked arm (e.g. EvalError raised by flow-ir itself before dispatch). Behind std::sync::Mutex to match the replay_cursor sibling (same crate-level convention — dispatcher writes are short critical sections, no .await held across).

Implementations

impl RunContext

pub fn new(run_id: RunId, run_store: Arc<dyn RunStore>) -> Self

Construct a RunContext with just the RunStore wired — the same shape all pre-replay callers use (replay_store / replay_cursor both None). Preserved as a convenience so a caller that never opts into replay can keep constructing RunContext positionally.

pub fn set_last_failure(&self, failure: LastFailure)

GH #76 error surface: write the aborting-step breadcrumb (last-write-wins). Called by [crate::blueprint::EngineDispatcher::dispatch]’s Blocked arm BEFORE it maps the outcome to EvalError::DispatcherError. Silently succeeds if the mutex is poisoned — this is an observability breadcrumb, not a load-bearing invariant, and a poisoned mutex here must never prevent the primary abort error from propagating (same fail-open convention as the sibling append_step_entry warn-and-swallow at EngineDispatcher::dispatch).

pub async fn snapshot_partial_ctx(&self) -> Value

GH #76 error surface: reconstruct a partial-ctx snapshot from the step-entry trace persisted so far — the in-tree substitute for a full storage.snapshot() from flow-ir (upstream carry).

Shape: { "steps": { "<step_id>": { "step_ref": ..., "status": ..., "binding_digest": ..., "at": ... } } } — a JSON object keyed by each dispatched StepId with its recorded StepEntry metadata. This is metadata-level, NOT value-level (no StepEntry carries the step’s actual OUTPUT value; that requires upstream mlua-flow-ir support to expose storage.snapshot() on error). Consumers who need value-level partial ctx must wait for the upstream carry — see the FlowEval partial_ctx field rustdoc.

Returns Value::Null if the store lookup fails (e.g. the row was deleted between dispatch and error surfacing) — the caller’s partial_ctx: Option<Value> field wraps this so Null is distinguishable from “no snapshot attempt at all”.

pub fn with_replay_store(self, store: Arc<dyn ReplayStore>) -> Self

Builder-style setter: attach a ReplayStore to log every completed step’s Ctx snapshot + output into.

pub fn with_replay_cursor(self, cursor: Arc<Mutex<ReplayCursor>>) -> Self

Builder-style setter: attach a ReplayCursor the dispatcher consults for a hit before dispatching each step.

pub fn with_binding_digests( self, digests: HashMap<String, BindingDigest>, ) -> Self

Attach immutable binding digests so replay keys distinguish the same step/input executed under different Runner/Agent/Context snapshots.

pub fn with_resume(self) -> Self

Builder-style setter: mark this dispatch as a resume / rerun-from of an existing Run (see Self::resume). Called only by the server’s resume and rerun-from handlers; every other construction site leaves the default false (initial launch).

Trait Implementations

impl Clone for RunContext

fn clone(&self) -> RunContext

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RunContext

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

Formats the value using the given formatter.