Explanation

State machines

Source Trax.StateMachine/, Trax.StateMachine.Persistence/

Trax.StateMachine represents a multi-step flow (a wizard, an application form, a checkout) as a small, language-neutral snapshot, so a C# backend and a TypeScript client agree on where a user is in the flow and the data that goes with it. The whole runtime state of an instance is a serializable snapshot that can be stored in Postgres and rebuilt from any point, so a user can start on one device and finish on another. Illegal (state, data) combinations are made unrepresentable, and neither the API nor the client can produce an unhandled exception.

Whether a piece of work wants a machine or a train is on Train or machine.

To build one, follow Author and serve a machine. Guards and reducers written as data are covered in Write guards and reducers as data, and a state that runs a train in Invoke a train from a state. A state can also start another machine and wait for it to end: Spawn a child machine from a state.

A machine can also be written as Gherkin features and a lexicon instead of a C# class: Trax derives its states, moves, guards, timers, access, the policies between machines and the views from the scenarios, and runs the same scenarios as tests. See Write machines as features, and How features become machines for what each part becomes. Serve features from the hub template serves them from a trax-hub project.

The two-document model

A machine has two documents, and most mistakes come from treating them as one.

DefinitionSnapshot
What it isthe machine's states, transitions, guards, and per-state context rulesone instance's current position and data
Where it livesin code (a C# or TypeScript MachineDefinition)in data (a Postgres row, a GraphQL payload)
How often it changesrarely (a deploy)constantly (every user action)
Crosses the wirenoyes

The definition is the program. The snapshot is the value it operates on. A snapshot has exactly four fields, always in this order: machine, version, state, context. state is the current step. context is the data for that step, and only that step, so its shape is discriminated by state.

The three guarantees

  1. Resumable from any point. A snapshot fully determines an instance. Rebuilding it is a Rehydrate of the stored JSON. There is no hidden in-memory state to reconstruct.
  2. Illegal states unrepresentable. Each state validates its own context on the way in (rehydrate) and on the way out (advance). A snapshot that claims a state but carries the wrong data is rejected as a typed error, never quietly accepted.
  3. The engine never throws. Every engine operation is total. This is a promise about the engine, not about the guards, reducers and effects you write, or about the host around it. Advance returns a transitioned or rejected result. Rehydrate returns an ok or error result. An unpermitted trigger, a failed guard, or malformed stored JSON all become typed values, never a throw. That includes JSON that parses but cannot be kept: Rehydrate refuses a number outside the range of a double (1e400) and a NUL character as MALFORMED, so an accepted snapshot always has a canonical wire and always fits a jsonb column.

A state or trigger token is matched by its exact declared name. "1", " Unlocked" and "Locked, Unlocked" are not aliases of Unlocked, as they would be to Enum.TryParse, and a rehydrated snapshot always carries the declared name, so the value that is stored and served is canonical.

Two runtimes, one behavior

The engine is implemented twice, once in C# (Trax.StateMachine) and once in TypeScript (@traxsharp/state-machine). They are kept identical not by generating one engine from the other but by a shared set of language-neutral conformance fixtures that both engines drive and must agree on. Only the result codes are contract; human-readable detail text is free to differ. Result codes lists every code a client can receive, the engine's and the persistence layer's.

The machine is authored in C#, which is the source of truth, and exported to a neutral IR (<machine>.ir.json). Common guards and reducers are authored declaratively and travel in the IR as data; a small interpreter on each side runs them, so they are single-sourced rather than hand-written per language. A guard or reducer the vocabulary cannot express is bound by name in the IR and hand-written once per runtime: in C# with CustomGuard(name, fn) / CustomReducer(name, fn), in TypeScript with customGuards / customReducers. A C# machine that names a custom rule or reduction with no handler bound fails at Build(), rather than refusing that edge forever. A guard or reducer written as a plain C# delegate cannot be carried by the IR at all, so export refuses a declarative machine that still has one, naming the edge, rather than emit it as an unconditional edge (see Delegate vs declarative). The snapshot itself carries only structure and data, never logic.

Agreement on structure is not enough on its own, because a custom guard exists once per language and the two interpreters must agree too. Two committed goldens, the differential corpus and the migration golden, are replayed by both engines and compared byte for byte; The codegen pipeline explains how they are produced and what each one catches. A byte-for-byte compare needs one serialization that both engines emit whatever built the snapshot: the canonical wire, RFC 8785 with the JSON.stringify number and string rules. It is also what makes a hash or a signature over a stored snapshot meaningful.

Persistence and run-once effects

The persistence layer is generic over a machine's (state, trigger) pair and stores the context in a real jsonb column. Its tables (snapshot_draft and effect_claim) ship as migrations in the core data providers, so registering UsePostgres or UseSqlite creates them. There is no manual DDL and no EnsureCreated step. A draft is scoped to its owner by a composite key, and every authoritative write carries an app-managed optimistic-concurrency token, so concurrent writers get a typed conflict rather than a lost update or a thrown exception.

Two write paths have different trust levels. Autosave is the soft path: the client sends a whole snapshot, the server validates it and stores it. Advance is the authoritative path: the client sends only a trigger, and the server re-drives the transition from the stored snapshot, never trusting a client-computed state. The soft path serves only machines with no server-side behaviour: a machine with an event or a start gated by a role or a policy, a timer, an invoked train, an effect, a guard, a reducer other than Keep, a custom guard or reducer, or a start that reduces its input refuses every save as SAVE_NOT_ALLOWED, and moves only through its declared events.

Autosave stores the context the client wrote, so any value an effect will act on has to be held to its true value by the state's rule, not just to its type. A checkout whose context carries a total holds total == items x price in every state; checking only that total is a number would let a browser save two items at one cent and have the charge take one cent. The State Machine sample shows the check and its test.

Some transitions carry an irreversible side effect: charge a card, send a letter, provision a resource. Trax records each one once per intent, even under retries, two devices, or a crash mid-flight, and a repeated send gets the recorded receipt instead of a second call. The call itself is at least once: a runner that dies after the downstream system acted, but before the receipt was written, leaves the effect to run again under the same key. Exactly-once delivery is only as good as the downstream system's handling of that key. A send marks the draft's row before it runs the effect, so two concurrent sends deliver once and nothing else writes the draft while the effect runs; the receipt, the move and the end of the mark are one write, and a retry replays the recorded result. A lease with a fence token keeps the mark live: if a runner marks the draft and then dies, the lease expires and the next send, or the outcome reconciler on any host that registers the effect, takes the mark over and runs the effect again under the same key, which the effect passes to the system it calls. A revived stuck runner is fenced out of recording over the new claimant's work. Effects is the reference.

Outside a machine, the same guarantee is IdempotentEffect, over the effect_claim ledger. There, reclaim happens on demand, on the next attempt at that intent, so an abandoned claim stays in effect_claim until someone tries again. EffectClaimSweeper releases every claim whose lease has expired, and Trax neither registers nor schedules it: a host that wants that backstop runs it itself, for example from a scheduled train, with the scoped IEffectClaimStore that AddStateMachines registers.

A draft has no natural end. A user can abandon a half-filled form, and a completed one lingers as a committed snapshot. A background sweep on every host that registers machines deletes a user's draft once it has been idle past DraftTtl or has lived past MaxDraftLifetime, so a returning user starts fresh rather than wedged behind a finished one. The sweep never deletes the record of something the server did (an instance in a state only the server puts it in), and a load never deletes. The defaults and every exception are under AddStateMachines options.

The frontend surface

A React engineer works through one hook. It owns the snapshot, persists after every successful step, and re-renders on every change, including a declined action, so the reason is never silently swallowed. Types flow from the machine's spec: the current step is a typed string, the context is discriminated by that step, and a trigger's input is required or forbidden at the type level. Persistence is driven by transitions, not by a decoupled timer, which is what prevents a save from landing after the state has already advanced past a terminal step. The TypeScript package is the reference.

Where the code lives

PieceLocation
C# engine (pure, total, dependency-free)Trax.StateMachine
C# persistence, run-once effects, mutation trainsTrax.StateMachine.Persistence
TypeScript engine, typed facade, React hookthe @traxsharp/state-machine package
Shared machines (the exported IR, differential and migration goldens) and the frontend generatorsthe shared machines directory and the codegen tools