durability/workflows

That shape is exactly what durable workflow runtimes (Temporal, Restate, similar) want from a library they're embedding. The workflow's own ledger records that effect E was started, persists the result, and replays the workflow code with E's output already in hand. A lash turn driven from inside such a workflow gets the same property: the turn's state-machine progress survives crashes, redeployments, and worker migrations because the workflow runtime owns the persistence and lash owns nothing the workflow can't replay.

The standard LashRuntime wraps the sansio machine with its own async I/O loop — it calls providers, schedules tools, runs RLM exec. Embedders who only need in-process durability through session persistence never see sansio. Embedders integrating with an external orchestrator drive sansio directly.

Progress is the host's hook for durable persistence: every time the machine commits new messages or mode-step events, it emits a Progress effect before continuing. Workflow runtimes treat each Progress as an activity boundary; in-process embedders fold it into their own persistence loop. Prose finalization is an outcome, not a low-level SessionEvent::Message { kind: "final" } side channel.

Use the id as your workflow's idempotency key. A Temporal activity keyed by (session_id, turn_id, effect_id) never runs twice for the same logical effect: the first attempt persists its result, replay reads from history. The same property holds for Restate's invocation keys and any other workflow runtime that supports keyed deduplication.

EffectId is local to one turn. Across turns, the counter resets to 1; pair it with the enclosing turn id to construct globally unique keys.

impl<M: ModeProtocol> TurnMachine<M> {
    pub fn checkpoint(&self) -> TurnCheckpoint<M>;

    pub fn restore_from_checkpoint(
        config: TurnMachineConfig<M>,
        checkpoint: TurnCheckpoint<M>,
    ) -> Self;
}

TurnCheckpoint<M> is fully serde-compatible. Fields:

• state: MachineState<M> — the waiting variant, with the data each retains.
• pending_effects: Vec<CheckpointEffect<M>> — fire-and-forget effects queued but not yet drained (Emit, Log, Progress).
• next_effect_id: u64 — counter, preserves id determinism.
• messages: Vec<Message> — prompt history committed so far.
• events: Vec<SessionEventRecord<M::Event>> — semantic event log committed so far.
• mode_iteration, mode_run_offset — turn position.
• cumulative_usage: TokenUsage — running token totals for this turn.
• termination: TurnTerminationPolicyState — max-turns / forced-final state.
• synced_mode_iteration: Option<usize> — last iteration the execution surface was synced.

The TurnMachineConfig passed to restore_from_checkpoint is not serialised — it carries the protocol driver, projector, tool registry, system prompt builder, and other host-owned plugins. The host reconstructs it the same way it built it for new(), then hands it back alongside the deserialised checkpoint. This is intentional: the config is what makes the abstract machine concrete, and it lives at the same layer as the workflow runtime that's driving the machine.

• Mid-LLM crash → restore yields a new LlmCall with the same EffectId and identical request. The workflow's activity for that id is the same lookup and produces the same response.
• Post-LLM crash, pre-checkpoint → restore yields the pending Checkpoint effect, not another LlmCall. The model is not re-invoked.
• Mid-tool-batch crash → restore yields a ToolCalls effect carrying every original call. Tools that completed in the partial batch are surfaced to the host via the response shape (each CompletedToolCall includes its outcome). Hosts can short-circuit completed calls by id and only re-invoke the pending ones.
• RLM exec crash → restore yields an ExecCode effect with the original code block and the driver's trajectory state. The exec result contains the parallel tool outputs in their structured form (success / failure / cancellation); no replayed ToolCallStarted events leak from the previous attempt.
• Plugin checkpoint crash → restore yields the Checkpoint effect again. The on_empty resume action is preserved, so a checkpoint that contributed no messages still finishes the turn the same way.

// `workflow.run_activity(...)` is whatever the runtime exposes for
// durable side effects — keyed by effect_id for idempotency.

let mut machine = TurnMachine::new(config, messages, events, mode_run_offset);

while !machine.is_done() {
    while let Some(effect) = machine.poll_effect() {
        match effect {
            Effect::LlmCall { id, request } => {
                let response = workflow
                    .run_activity(("llm", turn_id, id), || invoke_llm(request))
                    .await;
                machine.handle_response(Response::LlmComplete {
                    id,
                    result: response,
                    text_streamed: false,
                });
            }
            Effect::ToolCalls { id, calls } => {
                let results = workflow
                    .run_activity(("tools", turn_id, id), || run_tool_batch(calls))
                    .await;
                machine.handle_response(Response::ToolResults { id, results });
            }
            Effect::Progress { messages, events, .. } => {
                workflow.persist(turn_id, messages, events).await;
            }
            Effect::Done { messages, events, .. } => {
                workflow.finalize(turn_id, messages, events).await;
            }
            // … the remaining variants follow the same pattern.
            _ => {}
        }
    }
    // Snapshot the machine at every iteration so a worker crash
    // resumes against the latest waiting state, not the turn start.
    workflow.persist_checkpoint(turn_id, machine.checkpoint()).await;
}

The shape matches Temporal's workflow + activity split and Restate's handler + side-effect split with no glue layer: each effect becomes one durable activity, the machine snapshot becomes one workflow-state write, and the EffectId is the key that joins them.

Sessions opened through the regular LashCore / LashSession path also get durability through the session store, but at a coarser grain: a turn either commits to the store atomically or fails as a whole. Use sansio directly when you need crash recovery inside a turn — when a single LLM call is expensive enough to replay, or when a tool batch can run for minutes and you can't afford to lose its partial progress.