Reference

IR format

Package Trax.StateMachineNamespace Trax.StateMachineSource IrExporter.cs, SchemaReflection.cs, ValueFormats.cs

IrExporter.Export(builtMachine) serializes a declaratively authored machine to its IR: one canonical JSON document (<machine>.ir.json) that carries identity, structure, per-state context schema, per-trigger input schema, and every transition's guard and reducer as data. The per-language generators read it. The output is canonical JSON, so the same machine always exports the same bytes. IMachine.ExportIr() calls it.

Signature

namespace Trax.StateMachine;
 
public static class IrExporter
{
    public static string Export<TState, TTrigger>(BuiltMachine<TState, TTrigger> machine)
        where TState : struct, Enum
        where TTrigger : struct, Enum;
}

Behavior

Export throws InvalidOperationException if the machine made no declarative call at all (nothing to serialize), or if it mixes the styles and any edge still has a C# delegate guard or reducer, or any state a Holds validator. The message names each offending edge and state. Rule.Custom and Reduction.Custom are exported by name. See Delegates and declarative rules.

Top level

FieldTypeMeaning
idstringthe machine's stable id
versionnumberthe definition version
initialStatestringthe start state
initialContextobjectthe context a new snapshot starts with, from StartsAt(state, initialContext), so a generated runtime reproduces it exactly
statesstring[]every state, sorted (ordinal)
triggersstring[]every trigger, sorted (ordinal)
committedStatesstring[]states a soft autosave must not overwrite
contextobjectstate name to its context schema
inputsobjecttrigger name to its input schema: only what a client may send, so only triggers that declared WithInput<T>. A trigger missing here takes no input (or, when effect-bound, the effect's receipt); an invoked train's output is under its outcome
invariantsobjectstate name to a per-state policy rule (the .Requires(...) on top of the schema); omitted when the machine has none
transitionsobject[]the edges, sorted by (from, trigger, to)
outcomesobjectoutcome trigger name to its outcome, for states that invoke a train; omitted when the machine invokes nothing
timersobject[]the timers of the timed states, sorted by state; omitted when the machine has none
differentialobjectthe test-only fuzzing inputs authored with .Differential(...): samples (per trigger), seeds (per state: the context itself, or a list of contexts when the state is seeded more than once), and contexts (probes). Omitted when the machine declares none, and stripped from the generated runtime machine (it drives only the cross-language differential test).

A schema (under context, inputs, or an outcome's output) is { "fields": [ { "name", "type", "nullable", "constraints", "minimum"?, "maximum"?, "enum"?, "enumExact"?, "format"?, "fields"?, "values"?, "keys"? } ] }, where type is one of string/number/integer/boolean/array/object (integer is a number with no fractional part, decided by its value) and constraints is an array of rules. An input's or output's constraints read the input ("source": "input"), a context's read the context. In an input or output schema, a field holding a record carries that record's fields, and so does an array of records, for its elements; a context schema is one level deep. A runtime validates an input against its schema before any guard reads it, and refuses unknown fields.

An integer field carries its CLR type's range as minimum and maximum (an int is -2147483648..2147483647, a byte 0..255), and a value outside it is refused. Both runtimes read a JSON number as a double, and past 2^53 two integers can read as one, so a bound that far out is the nearest double inside the CLR range: a long is -9223372036854774784..9223372036854774784, and the few values between that and long.MaxValue are refused with the values past it, which no runtime can tell apart. A dictionary field (an object) and a list whose elements are not records (an array) carry values, the schema each value or element is checked against: { "type", "nullable", "minimum"?, "maximum"?, "enum"?, "enumExact"?, "format"?, "fields"?, "values"?, "keys"? }, so a Dictionary<string, int> refuses {"a": "one"} and a List<long> refuses 1e19. Values with no fixed JSON type (an object[], a Dictionary<string, object>) carry no values and are any JSON, as a JsonObject field is.

A dictionary keyed by anything but a string also carries keys, the schema each key is checked against, in the same shape as values, as System.Text.Json reads a key of that type: an integer key is its digits (no leading zero or plus sign) within the key type's range, compared exactly as text, and an enum, Guid, date, time or char key carries its names or its format. A key type no schema can check (a TimeSpan, a bool, a fractional number, a [Flags] enum, a record) refuses to build, naming the field.

An input schema holds only the properties System.Text.Json sets when it reads the record: one with a public or init setter, a [JsonInclude] setter, or a parameter of the constructor it reads with. A computed get-only property (int Total => Qty * Price) is not an input field, so a client that sends it is refused as sending an unknown field.

An Int128 and a UInt128 stop strictly inside ±10^21, because a stored number is written as JavaScript writes it and an integer from 10^21 on gets an exponent, which those types do not read. A decimal, a float and a Half carry their CLR range the same way (a decimal refuses 1e30); a float's and a Half's bound is the larger of the type's maximum and the shortest text that reads back as it (3.4028235E+38 for a float), so the maximum round-trips. A double has none beyond being finite. A string field from a CLR enum carries enum, the names the server's JSON writes (camelCase, or a member's [JsonStringEnumMemberName]), and a value that is not one of them is refused. A member's own name is compared ignoring ASCII case; a name given with [JsonStringEnumMemberName] is also listed in enumExact and matches only as written, as System.Text.Json reads it. A [Flags] enum has no fixed JSON type and refuses to build, in an input, an output or a context: use a list of an enum without [Flags]. A string field whose CLR type gives its text a shape carries format:

formatCLR typeA value must be
uuidGuid32 hex digits in the hyphenated 8-4-4-4-12 form
date-timeDateTimeyyyy-MM-ddTHH:mm:ss, at most seven fraction digits, then nothing, Z or an offset of at most 14:00; a real day and time, whose UTC instant (when it has an offset) is inside years 1 to 9999
date-time-offsetDateTimeOffsetthe same, and one with no offset (read in the server's zone) is refused on the range's first and last day, where some zone would push it out
dateDateOnlyyyyy-MM-dd, a real day from year 1
timeTimeOnlyHH:mm:ss with at most seven fraction digits
durationTimeSpanthe ISO-8601 duration a timer reads (P1DT2H30M, PT0.5S): no years, months, weeks or sign
uriUriabsolute, in a form System.Uri reads the same on every platform: a scheme of two or more characters; then an authority (a host of dot-separated letter-digit-hyphen labels, a dotted IPv4 address or a bracketed IPv6 one, and an optional port of at most 65535, with no user) and a path, or a path alone; then an optional query and fragment. A file URI's host may be empty, and neither it nor a net.pipe one has a port; a scheme System.Uri parses with rules of its own takes an authority, except mailto, which takes one plain address. Every other character is an RFC 3986 unreserved or reserved one, or a %HH escape
charcharone UTF-16 code unit

Every digit is ASCII. Both runtimes check the same patterns and the same calendar, so a value gets one verdict in each; where the CLR reader is looser (a relative Uri, a time without seconds), the format is stricter.

The format's version

The IR's shape is versioned as a whole, apart from any machine's version: the IR format, a number the C# exporter and every engine declare (irFormatVersion in the TypeScript engine, IR_FORMAT_VERSION in the Rust one, held equal to the exporter's and to the schema's $id by a test). It changes only when the IR gains something an engine reading the previous format would misread or ignore, not with every release. The exported <machine>.ir.json does not carry it, so it moves no committed IR and no schema hash. A twin generated with specifier imports records it as irFormat in the IR it embeds, and the installed @traxsharp/state-machine refuses, when the twin is imported, a format newer than it reads or older than it still reads, saying whether to upgrade the package or regenerate. The C# IrMachine and the Rust engine refuse the same formats, and an irFormat that is not a number. An IR without irFormat is not checked.

The schema

The format is also written as a JSON Schema (draft 2020-12), conformance/ir.schema.json, and the schema is normative: an engine reads every document it accepts, and the exporter writes nothing it refuses. Every object in it is closed, so a field it does not name is refused rather than ignored. Both runtimes' tests check every IR the exporter writes against it, so a field added to the IR without the schema fails them.

A context or input field, a rule's field and a set step's field or input source may not be named __proto__, constructor or prototype, in any segment of a dotted path: an engine that keeps a context as a plain object would reach the object's prototype rather than a member. The schema refuses them, and every engine refuses to load an IR that names one.

Transitions

Each transition carries its structure plus its guard and reducer as data:

FieldTypePresent when
from / trigger / tostringalways
guardrulethe edge has a declarative guard (When(Rule)); absent when the edge has no guard
guardMessagestringBecause(...) was set
reducereductionthe edge has a declarative reducer (Reduce(Reduction)); absent when the edge has no reducer, which means the context is kept
effectobjectthe edge binds RunsOnce<T>; { "keyPrefix": <string> }. The effect's type is not exported: the IR reaches every client

A rule is a tagged object keyed by rule (present, absent, ofType, nonEmpty, oneOf, compare, count, length, boolEquals, arrayOf, all, any, custom); a reduction is keyed by reduce (keep, clear, reset, set, custom). See the data model for each shape.

A rule on a field carries source ("context" or "input") and field (the member's JSON name: its [JsonPropertyName] when it has one, else its name in camelCase). compare, count and length add op and a numeric value; op is gt, gte, lt, lte or eq. compare reads the number itself, count an array's length and length a string's:

{ "rule": "compare", "source": "input", "field": "rank", "op": "lt", "value": 13 }
{ "rule": "count", "source": "context", "field": "items", "op": "gte", "value": 1 }

A set reduction is a list of steps, each writing one context field. A step's value is either an input field ({ "input": <field> }, from .FromInput(...)) or a constant ({ "const": <JSON value> }, from .ToValue(...)):

{ "reduce": "set", "steps": [
  { "field": "paidWith", "value": { "input": "coin" } },
  { "field": "status", "value": { "const": "paid" } } ] }

Outcomes

A state that invokes a train adds three triggers of their own kind, named <State>.done, <State>.failed and <State>.cancelled. A trigger enum member cannot contain a dot, so they never collide with triggers, which lists only the machine's own. Each is an entry of outcomes:

FieldTypeMeaning
statestringthe invoking state
outcomestringdone, failed or cancelled
edgesobject[]{ "to", "guard"?, "reduce"? } in declaration order, which is the order they are tried in; failed and cancelled have exactly one, without a guard
outputschemaon done only: the schema of the train's output, the success outcome's input

failed and cancelled carry no input. A runtime refuses an outcome trigger on advance (OUTCOME_BOUND) and applies it through its outcome entry point (applyOutcome in the twin), through its own edges: an output that does not match output is INVALID_INPUT, the first edge whose guard holds is taken, and when none does the result is NO_TRANSITION, not GUARD_FAILED. The run's input mapping is not exported, and neither is the train's name: the twin never starts a train, and the IR it ships to a browser does not name the server's train interfaces. differential.samples may hold sample outputs under <State>.done. A machine that invokes nothing has no outcomes key, so its IR is unchanged.

"outcomes": {
  "Fetching.done": { "state": "Fetching", "outcome": "done",
    "edges": [
      { "to": "NeedsReview",
        "guard": { "rule": "boolEquals", "source": "input", "field": "unsure", "value": true },
        "reduce": { "reduce": "set", "steps": [ { "field": "fingerprint", "value": { "input": "fingerprint" } } ] } },
      { "to": "Fetched",
        "reduce": { "reduce": "set", "steps": [ { "field": "fingerprint", "value": { "input": "fingerprint" } } ] } }
    ],
    "output": { "fields": [
      { "name": "fingerprint", "type": "string", "nullable": false, "constraints": [] },
      { "name": "unsure", "type": "boolean", "nullable": false, "constraints": [] } ] } },
  "Fetching.failed": { "state": "Fetching", "outcome": "failed",
    "edges": [ { "to": "FetchFailed" } ] },
  "Fetching.cancelled": { "state": "Fetching", "outcome": "cancelled",
    "edges": [ { "to": "Cancelled" } ] }
}

Timers

A state declared with .After(...) adds a trigger of its own kind, <State>.after, which only the server fires. It is never in triggers or inputs, which name what a client sends. Each entry of timers:

FieldTypeMeaning
statestringthe timed state
triggerstringthe timer's trigger, <State>.after
targetstringthe state the timer moves the instance to
rulesstring[]the rules the timer acts under, sorted: the union of the rules of everything that enters the timed state, each written as the census writes it (AnyAuthenticated, Anonymous, Requires(Editor), Requires(one of A, B), RequiresPolicy(name), several joined by and, or undeclared for an event that declares none). An event entering the state contributes its rule, the start its rule when the state is the initial one, and a timer or an outcome entering it the rules its own source state was entered under
afterstringa fixed duration, as an ISO-8601 duration (PT10M); present when the timer has one
fieldobject{ "name", "min", "max" }: the context field the duration is read from when the state is entered, and its bounds as ISO-8601 durations; present instead of after
"timers": [
  { "state": "Review", "trigger": "Review.after", "target": "Expired",
    "rules": ["AnyAuthenticated", "Requires(Editor)"], "after": "PT10M" }
]

A runtime refuses a timer trigger on advance (TIMER_BOUND) and applies it through its timer entry point (applyTimer in the twin). The twin shows the due time and never fires it. A machine with no timer has no timers key, so its IR is unchanged.

Example

The turnstile, exported (its differential block left out):

{
  "id": "turnstile",
  "version": 1,
  "initialState": "Locked",
  "initialContext": {},
  "states": ["Locked", "Unlocked"],
  "triggers": ["Coin", "Push"],
  "committedStates": [],
  "context": {
    "Locked": { "fields": [] },
    "Unlocked": {
      "fields": [
        { "name": "paidWith", "type": "string", "nullable": false,
          "constraints": [ { "rule": "nonEmpty", "source": "context", "field": "paidWith" } ] }
      ]
    }
  },
  "inputs": {
    "Coin": { "fields": [ { "name": "coin", "type": "string", "nullable": false, "constraints": [] } ] }
  },
  "transitions": [
    { "from": "Locked", "trigger": "Coin", "to": "Unlocked",
      "guard": { "rule": "oneOf", "source": "input", "field": "coin", "values": ["quarter", "dollar"] },
      "guardMessage": "Only a quarter or a dollar is accepted.",
      "reduce": { "reduce": "set", "steps": [ { "field": "paidWith", "value": { "input": "coin" } } ] } },
    { "from": "Unlocked", "trigger": "Push", "to": "Locked", "reduce": { "reduce": "clear" } }
  ]
}

See also