ORCHCRAFT
Control flow · Established

State Machine

Also known as: Finite state machine, FSM, Statechart

A state machine models a process as a finite set of named states and the allowed transitions between them, so that at any moment the process is in exactly one known state and only valid moves are possible.

01Problem it solves

Processes tracked with ad hoc status flags drift into impossible combinations (paid but cancelled, shipped but unpaid), and the rules for what may happen next are spread across the codebase.

02Use when / Avoid when

Use when

  • An entity or run has a clear lifecycle with a limited set of states.
  • Invalid transitions must be rejected, not just discouraged.
  • The next step depends on the current state plus an incoming event.
  • You want the process to be visualisable and reviewable by non-engineers.

Avoid when

  • The flow is a one-way pipeline of tasks with dependencies; a DAG fits better.
  • The number of states explodes combinatorially; consider hierarchical or parallel statecharts, or a different model.
  • The logic is mostly open-ended reasoning with no stable states.

03How it works

  1. 1DeclareDefine states, events and allowed transitions, including terminal states.
  2. 2ReceiveAn event arrives for an instance in state S.
  3. 3GuardThe transition is checked against the definition and any guard conditions.
  4. 4TransitionThe instance moves to the new state and runs the associated actions.
  5. 5PersistThe new state is stored so the next event starts from it.

04Capabilities

CapabilityWhat it means
Explicit states and transitionsThe set of valid states and the allowed transitions between them are declared up front and enforced.
Runtime branchingThe next step is chosen at runtime from the current state, input or classification result.
Persistent execution stateProgress, variables and position in the workflow are stored outside process memory, so a crash does not lose where execution was.

05Tradeoffs

AspectYou gainYou pay
CorrectnessImpossible states become unrepresentable.Every new case requires changing the model explicitly.
ClarityThe process can be drawn, reviewed and tested exhaustively.Large flat machines become unreadable without hierarchy.

06Failure considerations

Failure modeMitigation
State explosion makes the model unmaintainable.Use hierarchical and parallel states, or split into cooperating machines.
Concurrent events race and apply transitions on stale state.Process events per instance sequentially or use optimistic concurrency on the state record.
A state has no exit (stuck instances).Validate reachability of terminal states and add timeouts to waiting states.

07Implementations

Examples of products and frameworks that implement this pattern. Listed as evidence, not endorsement.

ImplementationMechanism
LangGraphAgent frameworkStateGraph defines nodes and edges over a shared, typed state.
AWS Step FunctionsCloud workflow serviceAmazon States Language declares states and transitions.
XStateState machine libraryStatecharts with hierarchical and parallel states, guards and actions.
  • Combines withHuman-in-the-loopApproval flows map naturally to explicit pending, approved and rejected states.
  • Combines withRouterTransition guards in a state machine act as routing decisions based on current state.
  • Alternative toDAGChoose a DAG for acyclic task dependencies, a state machine when the flow loops or waits on events.
  • Combines withCheckpointingPersisting the current state of a machine is a checkpoint of the whole process.

09Requirements that lead here