XState

smthrs/xstate runs XState v5 state machines as an optional derived-state layer over rows Smithers already persists (not a backend, scheduler, or persisted actor): each frame, useSmithersMachine recomputes state as a pure fold over durable output and signal rows via XState’s pure initialTransition / transition functions. Nothing is persisted, so resume, fork, and rewind stay correct automatically. Use it when control flow outgrows plain conditionals (revision loops, approval ladders, multi-phase pipelines with re-entry) and you want state.matches(...) instead of hand-rolled row checks. For linear pipelines, ctx.outputs conditionals stay simpler.

import { setup, assign } from "xstate";
import { useSmithersMachine, taskOutput, approvalDecided, eventReceived, timedOut } from "smthrs/xstate";

const releaseMachine = setup({}).createMachine({
  context: { revision: 0 },
  initial: "researching",
  states: {
    researching: { on: { RESEARCH_DONE: "awaitingApproval" } },
    awaitingApproval: { on: { APPROVED: "drafting", REJECTED: "researching" } },
    drafting: {
      // Declares which <Task> this re-enterable state drives, so the lint
      // can verify its id is derived from context, not a bare constant.
      meta: { smithersTaskId: ({ revision }) => `draft-r${revision}` },
      on: {
        REVISE: { actions: assign({ revision: ({ context }) => context.revision + 1 }) },
        TIMEOUT: "done",
      },
    },
    done: { type: "final" },
  },
});

function Release() {
  const ctx = useCtx();
  // Event sources are pure functions of ctx, never of machine state.
  const state = useSmithersMachine(releaseMachine, {
    id: "release",
    input: ctx.input,
    events: [
      taskOutput(researchSchema, { nodeId: "research" }, () => ({ type: "RESEARCH_DONE" })),
      approvalDecided(gateSchema, { nodeId: "gate" }, (d) => (d.approved ? { type: "APPROVED" } : { type: "REJECTED" })),
      eventReceived("REVISE", reviseSchema, {}, (p) => ({ type: "REVISE", feedback: p.feedback })),
      timedOut(reviseWaitSchema, { scope: "revise" }, () => ({ type: "TIMEOUT" })),
    ],
  });
  const rev = state.context.revision;

  return (
    <Workflow name="release">
      {state.matches("researching") && (
        <Task id="research" output={researchSchema} agent={researcher}>Research {ctx.input.topic}</Task>
      )}
      {state.matches("awaitingApproval") && (
        <ApprovalGate id="gate" output={gateSchema} onDeny="continue" request={{ title: "Continue to drafting?" }} />
      )}
      {state.matches("drafting") && (
        <>
          {/* Machine re-entry never re-executes a completed (nodeId, iteration):
              version task identity from machine context instead. The lint
              enforces this: a state the machine can re-enter must declare
              meta.smithersTaskId as a context-derived function, not a bare
              constant, so this pairing stays checked rather than
              convention-only. */}
          <Task id={`draft-r${rev}`} output={draftSchema} agent={writer}>Write the draft.</Task>
          {/* Wake-and-park plumbing: keeps the run alive and wakes a frame on
              delivery. The REVISE events themselves come from the durable
              signal table, not from this node's output. */}
          <WaitForEvent id={`revise-r${rev}`} event="REVISE" output={reviseWaitSchema} timeoutMs={86_400_000} onTimeout="continue" tagged async />
        </>
      )}
    </Workflow>
  );
}

External events are ordinary signals: bunx smthrs signal RUN_ID REVISE --data '{...}'. There is no send(), no onDone prop, and no actor.

The fold

Each frame, useSmithersMachine(machine, { id, input, events }):

Collects events by evaluating each declared source against ctx.
Orders them by (provenance seq, declaration index, mapped-event subindex): causal arrival order with deterministic tiebreaks, a total order that is a pure function of rows on every branch.
Folds initialTransition(machine, input), then transition(machine, snapshot, event) per event. Returned actions are discarded; builtin assign applies inside transition. Events not accepted in the current state are discarded, matching live-actor semantics, as are events after the machine reaches a final state.
Returns the final MachineSnapshot; state.matches(), state.can(), state.context, state.hasTag() work as @xstate/react users expect.

Multiple machines per workflow: give each useSmithersMachine call a distinct id.

Event sources

Source	Reads	Notes
`taskOutput(output, { nodeId?, scope? }, map)`	Durable output rows via `ctx.outputRows`	One `map` call per row; return an event, an array, or `null` to skip. Only a written row triggers this: failed attempts write no row, and `(nodeId, iteration)` writes are upserts.
`approvalDecided(output, { nodeId?, scope? }, map)`	Approval decision rows	Denials persist a row only with `onDeny: "continue"`; a failing gate ends the branch and writes nothing.
`eventReceived(signalName, schema, { correlationId? }, map)`	Durable `_smithers_signals` rows via `ctx.signalRows`	Folds the signal table on the shared seq clock, so every delivered signal reaches the machine regardless of listener mount timing, even one delivered before its listener mounted. `correlationId` scopes the fold to matching-id signals, needed when one signal name backs multiple concurrent waits. Payloads failing `schema.safeParse` are skipped deterministically (same rows, same skips), so a malformed delivery can’t brick future renders. Rewinding past a delivered signal makes the machine forget it, like output rows.
`timedOut(output, { nodeId?, scope? }, map)`	Tagged `{ kind: "timeout" }` rows	Requires opting into the tagged wait-result envelope (`tagged` + `onTimeout: "continue"`); pointing `timedOut()` at a non-tagged wait is a hard render-time error (`TASK_OUTPUT_SCHEMA_INVALID`), never a silent no-op.

All sources are pure functions of ctx; deriving a source’s nodeId from the fold’s own output is circular and unsupported.

Constraints (enforced at mount)

A mount-time lint runs per machine identity (hot reload re-lints) and rejects machine features that can’t exist inside a durable fold, each with a typed error naming the Smithers-native alternative. No escape hatch.

Rejected	Use instead
`invoke`	A `<Task>`/`<Subflow>` writing an output row + `taskOutput()`
`spawn` / `spawnChild` (including inside `assign`)	`<Task>` execution + `taskOutput()`
`after`	`<WaitForEvent timeoutMs tagged onTimeout="continue">` + `timedOut()`, or `<Timer>`
`raise`	Model the step as machine states, or a real signal + `eventReceived()`
`sendTo`	Durable channels: outputs, approvals, signals
`emit`	Derive observers from the returned snapshot
`enqueueActions`	Plain `assign`; side effects in tasks
`stopChild` / `stop`	Stop rendering the task (unmounting is the durable equivalent)
`cancel`	`<WaitForEvent timeoutMs>` + `timedOut()`
Custom / `log` actions	Only `assign` runs in the fold; run side effects in tasks
A bare-constant `meta.smithersTaskId` on a state the machine can re-enter	Derive the id from context: `meta: { smithersTaskId: (context) => ... }` minted from an `assign` counter

Every callback in the fold (event mappers, context initializers, guards, assigners, machine output functions) must be pure, side-effect-free, free of time/randomness, and non-mutating of inputs; a throwing one fails the render with a typed SmithersError naming the machine and event/phase, instead of an anonymous crash deep inside the fold.

Listeners, re-entry, and final states

The signal table is the event source; listeners are wake-and-park plumbing. A parked <WaitForEvent> matters for liveness: an idle machine state with nothing rendered makes the graph quiescent and ends the run, so states awaiting external events should render a listener to keep the run parked and wake a frame on delivery. A missed wake delays the fold by one frame but never loses the event.
Machine re-entry never re-executes a completed Smithers task. A bare-constant task id in a re-enterable state deadlocks the machine on a cycle: no new row or event ever arrives, ending the run the same way as above. The lint requires meta.smithersTaskId be a function of context (see table above) for any state reachable back to itself through the machine’s transition graph, whether by a direct self-transition or a longer cycle.
Final states are derived-only. Smithers can finish while the machine is non-final (graph quiescent); a machine final state doesn’t cancel in-flight tasks (stop rendering them instead); snapshot.output isn’t the run output; a failure-flavored final state doesn’t fail the run.

Durability and time travel

The fold’s inputs are exactly the rows Smithers restores, so crash/resume recomputes an identical machine state; rewinding to an earlier frame yields the machine state those earlier rows imply; forked runs fold their copied row history and diverge cleanly with their own signals. One carve-out: an in-place payload replacement at the same (nodeId, iteration) (manual retry-task of a completed node, HumanTask reopen) keeps its seq but changes its payload, so folded history from that position reinterprets. The in-process cache validates by content hash and refolds automatically, but workflows feeding machines from replaceable tasks should prefer fork-and-migrate. The prefix cache key is (runId, machine id, reducer hash); the reducer hash content-hashes the machine (config + setup() implementations) plus every declared event source (kind, target, options, map/schema source). So one process hosting many runs (or a fork, which inherits its parent’s row history and machine id verbatim) never serves one run’s snapshot to another. The cache is bounded (LRU-evicted), so a long-running process doesn’t retain every historical snapshot. A mid-run machine or event-source edit can’t silently reuse a fold computed under the old reducer: it rides the acceptWorkflowChange gate, where a reducer-hash change for an already-folded (runId, id) logs a machine-history reinterpretation warning instead of reinterpreting silently.

Performance

Recomputing per frame is cheap: the prefix cache above folds only the new suffix each frame. The CI benchmark (packages/xstate/tests/fold-benchmark.test.js) folds 10,000 events on a parallel + nested-compound machine in well under a second of full-refold (~20µs/event), and proves incremental folding touches only the new suffix by counting actual transitions executed (immune to machine load), not by timing it; a wall-clock threshold is logged but stays deliberately generous and non-strict, since it isn’t the real gate. Practical limit: tens of thousands of events per machine per run; beyond that, summarize history into machine context via coarser events.

Visualization

Machines are plain XState, so Stately Studio import and xstate/graph static visualization work unmodified on the machine definition.

Start

Articles

Learn

Capabilities

Build Workflows

Run and Operate

Workflow Pack

Components

Integrations

Agent Support

Examples

Contributing

The fold

Event sources

Constraints (enforced at mount)

Listeners, re-entry, and final states

Durability and time travel

Performance

Visualization

​The fold

​Event sources

​Constraints (enforced at mount)

​Listeners, re-entry, and final states

​Durability and time travel

​Performance

​Visualization

The fold

Event sources

Constraints (enforced at mount)

Listeners, re-entry, and final states

Durability and time travel

Performance

Visualization