Explanation

The codegen pipeline

Source IrExporter.cs, CorpusReplay.cs, Trax.StateMachine.Testing/

A machine has two runtimes, the C# engine on the server and a TypeScript twin in the browser, and they must agree down to the byte. Writing both by hand means keeping two implementations in sync forever. The pipeline removes the second one: the machine is authored once in C#, and everything the frontend needs is generated from it.

The flow

C# machine (the source)
   -> IrExporter.Export  ->  <machine>.ir.json   (the IR: structure + guards + reducers as data)
        -> generators    ->  state / trigger types
                             context type per state
                             shape validators
                             a runnable, typed machine

The IR is the interchange contract. Because a declaratively authored machine records its guards, reducers, and context schema as data, the export is complete: a generator has everything it needs to build a working twin, not just the state diagram. The TypeScript side reads the same rule data and evaluates it through a small interpreter that mirrors the C# evaluators, so the generated machine runs exactly the rules the C# source declared. There is no hand-written binding layer.

What you write and what is generated

Per machine, you write one C# file: the state and trigger enums, the context and input records, and the Configure method. The state and trigger types, the context types, the validators and the runnable typed machine are generated from that file's IR. The only thing hand-written per frontend is the UI that drives the machine.

How much of that holds depends on how much of the machine fits the Rules vocabulary. Export refuses a machine that still has an edge on a delegate guard or reducer, or a state on a Holds validator, because the IR cannot carry it and the generated twin would disagree with the server on that edge. Logic the vocabulary cannot express goes in a custom rule or reduction (Rule.Custom, Reduction.Custom), which the IR names and each runtime binds a handler for. A machine that stays declarative generates its whole twin.

The differential corpus

Agreement on structure is not enough. A custom guard or reducer exists once per language, and the interpreters that run the declarative rules must agree too, so behaviour can still drift. The differential corpus catches that.

TypeScript is the oracle. It drives the engine over every reachable snapshot, discovered by walking the machine's own transitions from the initial snapshot plus a few declared seeds for states whose context arrives out of band, times every trigger, times a few representative samples per trigger. Each outcome is recorded as canonical wire on a transition, or as a rejection code. The result is committed as machines/<machine>/differential.json, and both engines replay it and must reproduce every outcome byte for byte. The turnstile machine's corpus is 18 cases and the checkout's 30, most of them rejections, which is what a hand-written fixture set never covers exhaustively.

The corpus is generated, never hand-written. Its inputs are authored in C#, in Configure, and exported into the IR's differential block, so the corpus is driven off the one C# source:

m.Differential(d => d
    .Sample(CheckoutTrigger.Pay, new JsonObject { ["receipt"] = "rcpt_1" })
    .EmptySample(CheckoutTrigger.Pay)
    .Seed(CheckoutState.Review, new JsonObject
    {
        ["items"] = new JsonArray("book"),
        ["total"] = 999,
        ["receipt"] = null,
    }));
  • Samples are a few representative inputs per trigger; a no-input case is always added. A guard that accepts quarter or dollar wants one input that passes, one that fails, and an empty one.
  • Seeds are a representative valid context for a state no trigger reaches (context that arrives through autosave rather than a transition). The initial state and everything reachable from it need none. A state may take several seeds, one per context worth starting from, and the corpus expands each of them; the same context twice for one state is refused at Build. A probe is different: it is crossed with every state once and never expanded, so it checks guards and validators where it lands but reaches nothing beyond.
  • Probes and outcome samples cover snapshots a client could send but no walk reaches, and the outputs of an invoked train.

IDifferentialBuilder lists the overloads. Regenerating the corpus is deliberate, and the git diff of the golden is the review of what changed. Each side replays the committed file on its own, so the C# suite needs no Node and the TypeScript suite needs no .NET.

The migration golden

When a machine bumps its version, a per-source-version migration upgrades an older stored snapshot on rehydrate (see Migrations); a missing step in the chain is a typed VERSION_MISMATCH, never a silent misread. Correctness against real stored shapes is pinned by the migration golden, machines/<machine>/migration.json: a committed set of stored older-version snapshots and the exact canonical wire each must become. Both engines replay it, so a migration that drops, renames, or reorders a surviving field fails, and the two runtimes cannot migrate the same draft differently.

The differential guards machine logic; the migration golden guards schema evolution. Because both are byte-exact comparisons over the canonical wire, a divergence is a hard failure, not a judgement call.

Generation and drift

One command runs the whole flow, trax machine generate: it exports the IR from the compiled machine in-process, then drives the engine's own generators to emit the twin and the corpus, each to its own output root. It reads only the IR it exports from the compiled machine, so there is no machine.json to edit. The generators ship inside the tool with the engine compiled in, so this needs only node (>= 22):

trax machine generate --assembly ./bin/MyApp.dll \
  --ir-out ./machines/checkout --twin-out ./web/src/app/checkout --corpus-out ./machines/checkout

The twin imports @traxsharp/state-machine, which the frontend installs from npm. Its header says which import it was generated with and how to change it. The package and the tool need not be at the same version: every release bumps both, mostly for changes that leave the IR alone. What has to match is the IR format, the contract between the IR and the engine that reads it, which changes only when that contract does. A twin generated with specifier imports records the format in its IR, and the installed package checks it when the twin is imported: a format it cannot read throws on load, saying whether to upgrade the package or regenerate, rather than run a machine it would read differently. An engine released before the check ignores the field, and the twin imports nothing it lacks. A twin generated with relative imports reaches into the engine checkout that generated it and records no format. After upgrading the tool, regenerate: trax machine check fails on a twin left from the previous tool. What changed in generate's defaults, and how to generate as before, is in Regenerate twins after the trax machine generate defaults changed.

trax machine check regenerates to a temporary location and fails on any drift. Generate and check are the same code path, so a passing check means the committed artifacts match the source. trax machine new scaffolds a machine.

Other languages

Every typed view is written from one model of the IR: which states and triggers there are, and which field becomes which type (an arrayOf constraint types a list's elements, a oneOf constraint limits a string to its values in the TypeScript view; the C# view keeps it a string, and the engine still checks the values). Each language has an emitter over that model, so a rule about the IR is decided once. --lang csharp writes the C# view, <Machine>.g.cs, for a .NET frontend: enums for the states and triggers, a record per context and input, the IR with its hash, and a typed client over Trax.StateMachine.Client that predicts with the machine built from that IR (IrMachine). The conformance kit holds that engine to the same answers as the C# and TypeScript ones.

A frontend in another language usually has the host's client manifest and not its assembly, so generate reads the IR from the manifest with --manifest in place of --assembly:

trax machine generate --manifest ./trax-client-manifest.json --machine checkout --twin-out ./App/Machines --lang csharp

SDK Reference

ExportIr | IDifferentialBuilder | Rules vocabulary | Migrations | trax machine