State Machine Modeling

Concept of the skill

What it is: State-machine modeling is the discipline of making one lifecycle's legal behavior explicit before implementation — what an entity can be, what can happen to it, which happenings are legal in which state, and what must be true before and after each transition. The whole point is to move the rules for "what can follow what" out of scattered if-blocks and into one inspectable model, so that the set of reachable conditions is a deliberate enumeration rather than the accidental product of every boolean someone added.

Mental model — five primitives:

• States — the mutually exclusive conditions one entity or workflow can occupy.
• Events or commands — what triggers change.
• Transitions — the map from (current state, event) to a next state or a deterministic rejection.
• Guards — pure conditions that must hold before a transition can fire.
• Actions / side effects — work attached to entry, exit, or the transition itself; never the state change.

Analogy: Treat the lifecycle like a railway switchboard — the current track segment and signal determine which next track is legal, while maintenance work and passenger notifications happen after the routing decision is made.

Why it exists: Without an explicit machine, lifecycle rules scatter across booleans, if branches, handlers, jobs, and UI checks. That implicit machine admits impossible combinations, makes retries ambiguous, and leaves future implementers guessing which transitions are legal.

What it is NOT: It is not broad domain discovery, persistence schema design, HTTP resource design, frontend state-location strategy, or post-failure debugging. Those skills compose with this one after the lifecycle model is clear.

Common misconception: A workflow engine, statechart library, or agent framework does not remove the need to model the lifecycle. It may run the model, persist progress, visualize it, or recover after crashes — but it does not decide the domain's legal states, guards, invariants, retries, or compensation semantics for you.

Coverage

Define legal lifecycle behavior for a domain object, UI flow, background job, integration, agent workflow, or distributed process. Covers:

• Core finite state machine — states, initial state, terminal states, events/commands, transitions, guards, self-transitions, internal transitions, and deterministic handling of illegal events (a rejected/error trap state, a deterministic error response, or an idempotent no-effect acknowledgement).
• State invariants — per-state facts, cross-transition facts, forbidden combinations, and "was once" constraints (e.g. "a refunded order was once paid").
• Actions and side effects — entry actions, exit actions, transition actions, and state-bound async invocations: long-running async effects (a fetch, a subscription, a spawned child machine) whose lifecycle is bound to a state — started on entry and cancelled on exit, so a fire-and-forget effect can't outlive the state that launched it. Plus retries, timeouts, cancellation, idempotency, and compensation.
• Statecharts (Harel) — hierarchical/nested states, orthogonal/parallel regions, history states, and the escalation point where a flat machine causes state explosion or transition duplication.
• Implementation tier — discriminated unions or sealed types + a transition function, a persisted status + transition guard, a statechart/workflow library, an actor system, or a durable-execution engine.
• Verification — the transition matrix, reachability checks, invalid-transition tests, model-based tests, and machine-definition versioning checks for in-flight long-running instances.

Philosophy of the skill

State modeling prevents boolean sprawl. When a workflow has several flags that can combine into impossible conditions, the model is already a state machine — just an implicit and unsafe one. N independent booleans represent 2^N possible combinations, most of which are nonsense (isPaid && isRefunded && isPending); the discipline replaces them with one explicit lifecycle value whose variants are the handful of states that can actually occur.

States are durations; events are instants. A state describes a condition that holds for some span of time (submitting, paid, waiting_for_approval). An event or command is the instantaneous occurrence that may move the machine (submit.clicked, payment.authorized, approval.timed_out). This is why Submit is a bad state name and Submitting can be a good one.

The governing principle, attributed to Yaron Minsky, is make illegal states unrepresentable. Pursue it in three descending tiers — use the strongest your language and runtime allow:

1. Unrepresentable — encode the lifecycle as a closed sum type / discriminated union / sealed class / enum, with per-state data living only in the state that owns it, so the type system itself rejects nonsense at compile time and exhaustive handling fails type-checking when a new state is added but unhandled (TypeScript discriminated unions on a status literal, Rust enums with per-variant fields, F#/OCaml variants, Kotlin sealed classes; the typestate pattern threads the state through the type so a method only exists on the state that allows it).
2. Impossible — where the type system can't carry the full lifecycle, route every mutation through one transition authority (state, event) -> next state | rejected, so there is exactly one place that can change state and no other code path can produce an illegal combination.
3. Detectable — where a transition crosses a process, service, vendor, or user boundary and can't be prevented locally, make the violation loud: reject deterministically with a machine-actionable error and an observable signal an operator can alert on. Never make an unexpected event a silent no-op.

Separate decision from effect. The transition decision should be pure and replayable: given the same state, event, and guard inputs, it returns the same next state or rejection. Side effects happen after the transition decision is accepted, carry idempotency keys where retries are possible, and are attached deliberately to entry, exit, or the transition itself.

Method

1. Name the lifecycle owner. Identify the entity/workflow whose state is being modeled, who owns the transition rules, and the single authority allowed to change state. Pick the shape that holds the state — a single status field for a flat single-axis FSM, or a structured state value (a sum type, or a record of concurrent region values) when there are parallel regions or per-state data. "One field" is the flat-FSM special case, not a universal requirement.
2. List observable states as durations/conditions, not events. Prefer nouns, adjectives, or present-participle conditions (pending_payment, paid, submitting, cancelled) over instantaneous verbs (pay, ship, submit). Keep them mutually exclusive. Mark the initial state and terminal states.
3. Record state data and invariants. For each state, write what data exists only in that state and what must always be true. Put shared data outside the variant; put per-state data inside it. Invariants are the spec the transition function enforces (e.g. "a refunded order was once paid").
4. List events and commands. Name what can trigger a transition — user commands, external events, scheduled events, timeout events, retry events, cancellation events, compensation events. Model a timeout as an event (payment.timed_out), not as ambient if (now > deadline) checks.
5. Build the transition matrix. For every state x event pair, record a next state, self-transition, internal action, or explicit rejection reason. Blank cells are the bug: every event in every state is either handled or deliberately refused.
6. Add guards. Write the condition required for each conditional transition (approve only fires when amount <= limit). Guards must be pure predicates over known state, event data, clock inputs, permissions, or already-loaded facts.
7. Attach side effects deliberately. Use transition actions for work caused by one edge, entry actions for work required no matter which edge entered the state, and exit actions for cleanup required no matter which edge leaves it. If async work should live only while a state is active, model it as a state-bound invocation or child actor whose result, cancellation, and error events are explicit.
8. Model reliability states. Name retryable, waiting, timeout, cancelled, failed, compensated, and terminal-success states where they are real domain outcomes. Include retry budget, backoff owner, max attempts, and terminal failure behavior.
9. Define duplicate and stale-event behavior. If the same event can arrive twice, record the event identity, idempotency key, current-state check, and replay response. If stale/out-of-order events can arrive after the machine moved on, reject or ignore them deterministically and document which.
10. Escalate from flat FSM to statechart when needed. Use hierarchy for shared transitions, orthogonal regions for independent axes, and history states for resumable nested flows. Do not hand-roll hierarchy and parallelism in scattered switch statements.
11. Split communicating machines when one machine has multiple owners. Treat a running machine as an actor when it owns internal state, processes events sequentially, and communicates with other machines by sending events. Do not let sibling actors mutate each other's internal state directly.
12. Choose the implementation tier (see "Choosing an Implementation"). The model comes first; the engine is the runtime.
13. Write transition verification before implementation. Test allowed transitions, forbidden transitions, guard failures, idempotent retries, stale events, terminal states, and reachability of every non-terminal state.

Transition Matrix

The transition matrix is the central verification artifact. It turns vague lifecycle prose into a complete decision table — every (state x event) cell is handled or explicitly refused.

Rules:

• A state with no inbound transition is unreachable unless it is the initial state.
• A non-terminal state with no outbound transition is a trap unless intentionally modeled as waiting for external input.
• A terminal state may accept read-only/idempotent events, but it should reject lifecycle-changing events.
• Every rejection should be deterministic enough for an API, job, UI, or operator to branch on without parsing prose.

Flat FSM vs Statechart — when to escalate

A flat finite state machine is the right tool until state explosion forces a richer formalism. The trigger: when independent concerns multiply. Three independent binary axes — online/offline and idle/syncing and authed/anon — already imply 2 x 2 x 2 = 8 flat states, and each new axis doubles it. When the state count grows multiplicatively or the same transition is duplicated across many states, lift to a statechart (David Harel, 1987 — the formalism behind UML state machines and XState).

Reach for a statechart formalism or library — XState v5 is the dominant JS/TS implementation, SCXML is the W3C interchange standard, UML state machines are the diagram form — rather than hand-rolling hierarchy and parallelism, which are exactly the features hand-written switch statements get wrong. Stay flat when the state set is small and single-axis; the statechart is overhead you only earn when explosion or transition-duplication appears.

Actors and State-Bound Work

A running machine can be treated as an actor: it owns internal state, receives events, emits events or snapshots, and processes messages through its transition logic. This is useful when a lifecycle decomposes into independent machines — parent/child UI flows, worker pools, background jobs, distributed process managers, or agent workflows. The actor boundary is ownership: other actors send events; they do not reach in and mutate state.

Use state-bound invocations for async work whose lifetime is tied to a state. Entering loading may invoke a fetch actor; leaving loading stops or cancels that actor, and any completion/error event is handled explicitly. This prevents ghost side effects — a response from a request started in loading arriving after the user cancelled and flipping a now-cancelled entity back to loaded. Use spawned or durable child actors only when work must outlive the state that started it, and then model the stop, cancellation, stale-result, and compensation paths. (Invoked actors are also a decomposition lever: when one machine grows unwieldy, split a self-contained concern into its own machine the parent invokes, rather than inlining its states.)

Choosing an Implementation: in-process, persisted, or durable

Modeling the lifecycle is independent of how you run it. Decide deliberately:

Upstream-displacement check. For the long-running, distributed, crash-survivable case, a hand-rolled persisted state machine is increasingly the wrong implementation. Durable-execution engines automatically persist not just the state but the execution position — every local variable, loop counter, and branch — and resume on different infrastructure exactly where a crash left off, eliminating the plumbing (DB writes per transition, switch/case dispatch, timeout scheduling, recovery logic) that hand-rolled machines rarely get fully correct. Temporal's own framing is that this lets you "eliminate or avoid state machines altogether" at the implementation layer. DBOS checkpoints workflow progress; the OpenAI Agents SDK documents durable integrations with Dapr, Temporal, Restate, and DBOS; LangGraph positions itself as infrastructure for long-running stateful agents. This does not displace this skill: the conceptual lifecycle — the states, the legal transitions, the guards, the invariants, the idempotency rules, the compensation steps — is exactly what you still design here and then hand to the engine. A saga coordinates a distributed transaction and compensates failed steps (the saga itself carries no state); a process manager is a state machine that drives that coordination by reacting to events plus current state. Model the lifecycle; then pick the tier.

Agent and LLM Workflows — don't let the prompt be the state store

An LLM agent loop is a state machine whether or not you model it as one: it occupies a step, an event (a tool result, a user reply, a model turn) drives the next step, and some condition terminates it. The recurring failure is letting the prompt / conversation history be the implicit state store — "where the agent is" is inferred by re-reading the transcript each turn. History is lossy, unbounded, token-expensive, and non-deterministic, so the agent re-does completed steps, skips required ones, and has no crash-resumable position. Apply the same discipline:

• Deterministic state authority — keep the loop's state (current step, accumulated results, retry counts, what tools have run) in an explicit, inspectable structure the model reads from, not in free-form chat history it re-derives. The transcript is the event log; the state is the fold over it.
• Explicit stopping conditions — terminate on a modeled terminal state or a hard turn/step budget, never "until the model decides it's done." An unbounded loop with no terminal state is the agent equivalent of a blank transition-matrix cell.
• Checkpoints — persist state at each step so a crashed or interrupted run resumes from its last committed position rather than restarting. This is the durable-execution tier applied to an agent.
• Durable, idempotent integrations — side effects an agent triggers (a payment, an email, a write) follow the same idempotency-key and expected-version rules as any distributed machine, because the model may retry a step.

Anthropic's workflow/agent distinction reinforces the boundary: predefined, known code paths should be workflows (deterministic transition authority); open-ended tasks where the number of steps can't be hardcoded need agents with guardrails, checkpoints, and stopping conditions. Frameworks encode exactly this shape — LangGraph models the agent as a graph with checkpointed state; the OpenAI Agents SDK runs a turn loop with explicit run/stopping conditions; Temporal/DBOS supply durable execution for the orchestration. Keep transition authority deterministic when the path is safety-critical; let the model make judgments inside explicit guard/action slots, but do not let prompt text become the only state store.

Reliability, Delivery, and Versioning (persisted & distributed machines)

Once a machine outlives a single process — a persisted status column, a queue-driven worker, a durable workflow — the network stops cooperating and the transition function must defend itself.

The reasoning behind the table:

• Duplicate events — at-least-once delivery means the same event can arrive twice. The transition function must be idempotent: re-applying paid to an already-paid order is a no-effect acknowledgement, never a second charge. Carry an idempotency key on the command so the receiver dedupes by identity rather than guessing from state.
• Stale / out-of-order events — an event computed against an old snapshot can arrive after the state has moved on. Guard with an expected-version / fencing token (optimistic concurrency): reject a transition whose expected version no longer matches the current one, so a slow or replayed writer can't clobber a newer state. Durable-execution and event-sourced systems lean on this as the core safety check.
• In-flight machine-definition versioning — when the state-machine definition itself changes while instances are mid-flight, decide per instance: drain on the old definition, or migrate deterministically to the new one. Durable engines expose explicit versioning APIs (e.g. Temporal's patched/getVersion and Worker Versioning) for exactly this; a hand-rolled persisted machine must version its definition and record the migration policy, or in-flight instances silently take transitions they were never designed for.

These are why a hand-rolled persisted machine is hard to get right, and why the durable-execution tier is often the better home for the long-running, distributed case.

Verification

• [ ] States are mutually exclusive unless explicitly modeled as orthogonal/parallel regions.
• [ ] State names are durations/conditions, not instantaneous events or actions.
• [ ] Every state has written invariants, and per-state data exists only in the states where it is valid.
• [ ] Every transition has an event/command trigger (or a modeled timeout) — no transitions fire from ambient time checks.
• [ ] The transition matrix has no blank cells: every state x event pair is handled or explicitly rejected.
• [ ] Guards are explicit, pure, and separate from side effects.
• [ ] Side effects are attached deliberately to entry, exit, transition actions, or state-bound invocations, and carry idempotency where retries are possible.
• [ ] Async/invoked work that can outlive its starting state has explicit cancellation, stale-result, or compensation behavior, so a late completion cannot mutate a state it no longer belongs to.
• [ ] Terminal, retryable, waiting, cancelled, failed, and compensating states are named where relevant.
• [ ] Unexpected events produce a deterministic rejection or a modeled trap/error state — never a silent no-op.
• [ ] Illegal states are unrepresentable in types where the language allows; otherwise illegal transitions are impossible (single transition function) or at least detectable (loud rejection).
• [ ] Tests cover allowed transitions, forbidden transitions, guard failures, duplicate events, stale events, and terminal-state behavior.
• [ ] Every non-terminal state is reachable from the initial state and can progress or intentionally wait.
• [ ] State explosion or duplicated transitions triggered a statechart/hierarchy review rather than hand-enumeration.
• [ ] For persisted/distributed machines: duplicate events are deduped (idempotency key), stale events are rejected by an expected-version / fencing token, and a machine-definition-versioning policy exists for in-flight instances.
• [ ] The implementation tier (in-process / persisted / durable) is a deliberate choice.
• [ ] If the lifecycle drives an LLM/agent loop, state authority lives in an explicit machine (checkpointed state, deterministic transitions, explicit stopping conditions) rather than being inferred from the prompt/conversation history.
• [ ] Cross-boundary transition behavior is verified with system-interface-contracts; test-level choices are verified with testing-strategy; frontend state-location questions are out of scope and route to state-management.

Anti-Patterns

Key Sources

Reach for these when a decision needs more than this skill carries:

• "Make illegal states unrepresentable" — Yaron Minsky (Jane Street / OCaml); the type-driven framing behind the Unrepresentable tier. Operationalizes via TypeScript narrowing/exhaustiveness, Rust typestate, and sealed/sum types. https://www.cs.cornell.edu/courses/cs3110/2013fa/lectures/27/lecture27_Minsky_EffectiveML.pdf ; https://www.typescriptlang.org/docs/handbook/2/narrowing
• Statecharts — David Harel, "Statecharts: A Visual Formalism for Complex Systems" (1987); the origin of hierarchy, orthogonal regions, and history states. https://www.sciencedirect.com/science/article/pii/0167642387900359
• SCXML — the W3C State Chart XML interchange standard; statechart semantics for events, guards, parallel regions, onentry/onexit, history states, and transition selection. https://www.w3.org/TR/scxml/
• UML state machines — OMG UML 2.5.1; the formal state-machine notation family. https://www.omg.org/spec/UML
• XState / Stately — the dominant JS/TS statechart implementation; docs cover invoked actors, history, parallel states, and model-based/path testing. https://stately.ai/docs ; https://stately.ai/docs/actors ; https://stately.ai/docs/invoke ; https://stately.ai/docs/graph
• AWS Step Functions — managed state-machine workflow service; the Amazon States Language. https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html
• Durable execution — Temporal (incl. Worker Versioning for in-flight instances), DBOS, Restate, Inngest; engines that persist execution position and expose in-flight versioning APIs. https://docs.temporal.io/ ; https://docs.dbos.dev/python/tutorials/workflow-tutorial
• Agent-workflow state — LangGraph (graph + checkpointed state), the OpenAI Agents SDK (turn loop with explicit run/stopping conditions), and Anthropic's "Building Effective Agents" (workflow-vs-agent distinction); the home of the "don't let the prompt be the state store" rule. https://docs.langchain.com/oss/python/langgraph/durable-execution ; https://openai.github.io/openai-agents-python/running_agents/ ; https://www.anthropic.com/engineering/building-effective-agents
• Saga / process manager — Garcia-Molina & Salem, "Sagas" (1987); Hohpe & Woolf, Enterprise Integration Patterns (the process-manager pattern); Microservices.io and AWS prescriptive guidance for compensation, orchestration vs choreography. https://microservices.io/patterns/data/saga.html ; https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/saga.html ; https://www.enterpriseintegrationpatterns.com/patterns/messaging/ProcessManager.html

Do NOT Use When

Skill Graph context

<!-- skill-graph-context:start (generated — do not edit by hand) -->

Classification

• Subject: software-architecture
• Public: true
• Domain: modeling/state-machines
• Scope: Use when formalizing one lifecycle's legal behavior: states, events/commands, transitions, guards, state invariants, invalid states, side effects, retries, timeouts, compensation, statecharts, actor-style communicating machines, state-bound async invocations, implementation tier, and transition verification. Includes flat finite state machines, hierarchical/parallel statecharts, and the design decision of whether to implement the lifecycle as in-process types, a persisted transition guard, a workflow/statechart library, an actor system, or a durable-execution workflow. Excludes broad domain-event discovery, persistence schema design, HTTP endpoint design, frontend state-placement decisions, and telemetry instrumentation after the lifecycle is settled.

When to use

• model the order fulfillment status lifecycle so invalid transitions are impossible
• this status field keeps growing flags - should it become a state machine?
• define guards and side effects for onboarding steps
• find impossible states in this workflow before we implement it
• these four booleans are multiplying into states that should never exist - how do I collapse them?

Not for

• discover the domain events and policies for the whole business process
• create database tables and constraints for this lifecycle
• decide whether this React form state should live in the URL, context, or a global store
• instrument metrics and traces for an existing workflow
• debug why this job got stuck yesterday

Related skills

• Verify with: system-interface-contracts, testing-strategy
• Related: observability-modeling, api-design, debugging, event-storming, system-interface-contracts, testing-strategy, state-management

Keywords

• state machine, statechart, lifecycle states, transitions, guards, finite state machine, invalid states, status field, workflow invariants, state explosion

<!-- skill-graph-context:end -->