Conformance oracle #
Reference traces recorded from XState 6.0.0-beta.3 (design §9). The plusthree kernel replays them through from_json and must reproduce them exactly. The traces are committed, so Rust CI never needs Node.
There are two trace versions. Version 1 records one machine through XState's pure API. Version 2 records a whole actor system run live: invoked and spawned children, messaging, dead letters, persisted-snapshot round trips and the inspection stream. Each trace says its version; a reader for one version must reject the other. The recorder writes version 1 for every case that needs nothing from version 2, so the version 1 corpus is unchanged.
cd conformance
npm ci
npm run regen # rewrite every fixture under traces/
npm run check # fail if any fixture differs from a fresh recording, or an export does not load
node src/show.mjs traces/hand/history/shallow-history-basic.json # human-readable view
| Path | What |
|---|---|
cases/*.mjs |
Hand-written cases: a machine, a script, and the XState test they come from. One file per topic. |
src/generator.mjs |
Seeded random charts and scripts. RANDOM_SEEDS selects the committed corpus. |
src/recorder.mjs |
Runs a case through XState's pure API and builds a version 1 trace. |
src/system.mjs |
Runs a case as a live actor system and builds a version 2 trace. |
src/vocab.mjs |
The named guards, actions, actor operations and child logic cases may use (the JS half of the replay registry). |
schema/trace.schema.json |
JSON Schema for a trace. regen validates every trace against it. |
traces/hand/<topic>/<name>.json, traces/random/seed-NNNN.json, traces/random-actors/seed-NNNN.json |
The fixtures. traces/index.json lists version 1 traces under hand and random, version 2 traces under system. |
exported/*.json, src/exported.mjs |
Machines exported by plusthree's to_json (design §7), with events and the state values they reach. npm run check loads each in XState and checks the values; the Rust tests check that plusthree's export and values match. |
NOTES.md |
XState behavior that surprised us, and recorder decisions that follow from it. |
How a trace is recorded #
The recorder loads the case with machineFromJSON and drives it with XState's pure API (getInitialMicrosteps, getMicrosteps), which returns every microstep's snapshot, effects and transitions. It plays the host: it keeps the simulated clock and the scheduled timers, delivers due timers as xstate.timer events, and handles execution errors the way Actor does. A live actor on a SimulatedClock runs the same script alongside; after every step the recorder checks that the live actor has the same value, context, status, output, timers and executed effects, so the host behavior in the trace is XState's own.
To see entered and exited states, the recorder loads an instrumented copy of the machine: each state's entry and exit actions start with a marker action. The markers become the microstep's entered/exited lists and are removed from effects. The trace stores the machine without markers.
Trace format, version 1 #
A trace is one JSON object. schema/trace.schema.json is the normative shape; this section gives the meaning. Any change to the meaning of a field bumps version.
{
"format": "plusthree-conformance-trace",
"version": 1,
"xstate": "6.0.0-beta.3",
"name": "shallow-history-basic",
"description": "...",
"origin": { "kind": "hand", "group": "history", "ref": "history.test.ts: ..." }, // or { "kind": "random", "seed": 7, "attempt": 0 }
"machine": { /* MachineJSON, loaded with machineFromJSON */ },
"steps": [ /* step 0 is always the initial transition */ ]
}
Steps #
A step is one input from the script and everything it caused.
{ "input": { "init": true }, "now": 0, "macrosteps": [ M ] } // step 0 only
{ "input": { "event": { "type": "GO" } }, "now": 0, "macrosteps": [ M ] } // exactly one
{ "input": { "advance": 50 }, "now": 50, "macrosteps": [ M, ... ] } // zero or more
init: the initial transition (xstate.init), at time 0.event: send the event to the machine. Events are plain objects:typeplus payload fields.advance: move the clock forward byadvancems. Every timer due at or before the new time fires, one macrostep each, in order of due time, ties broken by scheduling order (the order the host saw the schedule effects). Firing removes the timer before the macrostep runs. A timer scheduled while advancing fires in the same advance if it is due in time.nowis the clock after the step.
Macrosteps #
{
"event": { "type": "xstate.timer", "id": "ping" }, // what the macrostep processed
"at": 80, // clock time it ran
"handled": true,
"error": { "message": "guard failed", "recovered": true }, // only when an execution error happened
"microsteps": [ ... ],
"snapshot": { ... } // state after the macrostep
}
eventis{"type":"xstate.init"}, the script event, or a timer notification{"type":"xstate.timer", ...key}wherekeyis the timer key (below).handledis false exactly when XState'sisUnhandled()holds: no transition was enabled, no effects, snapshot unchanged. A done or error machine ignores every event:handled: falseand no microsteps.error: the macrostep threw an execution error (only thefailguard throws). All of its work is discarded. If any active state declaresonError, the macrostep reruns from the pre-event snapshot with{"type":"xstate.error.execution","error":message}andrecoveredis true;microstepsare those of the rerun. Otherwiserecoveredis false,microstepsis empty, and the snapshot is the pre-event snapshot with statuserror.
Microsteps #
{
"kind": "internal",
"event": { "type": "NEXT" },
"transitions": [ { "source": "m.a", "event": "NEXT", "index": 0, "targets": ["m.b"], "reenter": false } ],
"exited": ["m.a"],
"entered": ["m.b"],
"exitedOnDone": ["m.b", "m"], // optional
"effects": [ ... ],
"value": "b", // StateValue after the microstep
"context": { }
}
kind says where the microstep came from:
| kind | Position | Meaning |
|---|---|---|
init |
first of the init macrostep | Enters the initial configuration. No transitions. |
event |
first of an event macrostep | Selection for the external event. Empty when nothing is enabled. |
timer |
first of a timer macrostep | Consumes the timer: a delayed raise or after timer puts its event on the internal queue. No transitions, no effects. |
error |
first of a recovered macrostep | Selection for xstate.error.execution. |
eventless |
later | Eventless (always) transitions. Selected before the internal queue is read. |
internal |
later | The next internal event (raised, xstate.done.state, xstate.after) was dequeued. Empty when nothing is enabled: XState still counts it as a microstep. |
event: the event dequeued for selection; present forevent,internalanderror.transitions: the transitions taken, after conflict resolution, in selection order. A transition is identified by itssourcestate id, itseventdescriptor (an event name, a wildcard such asuser.*or*,""foralways,xstate.after,xstate.done.state, orxstate.error.*foronError), andindex, its position in the source's JSON list for that descriptor (on[descriptor],always,onError). Forafter,delayis the after key andindexcounts within that key's list.targetsare the resolved target state ids (a history state appears as itself, not as what it restored).reenteris the transition's flag.exited: states whose exit ran, in exit order (deepest first, reverse document order).entered: states entered, in document order.exitedOnDone: when the microstep completes the machine (enters a top-level final state), XState then runs the exit actions of every active state, deepest first. Those states are listed here. They stay in the snapshot's value. Absent means empty.effects: effects in execution order, entry/exit markers removed. The macrostep's effect list is the concatenation over its microsteps.value,context: the snapshot after this microstep.
Effects #
XState's describeExecutableEffect descriptors, without actor references (the source is always this machine) and without undefined fields:
| Effect | Shape |
|---|---|
| custom action | {"kind":"action","type":"rec","params":{...}} |
| emitted event | {"kind":"emit","event":{...}} |
delayed raise, after timer |
{"kind":"builtin","type":"@xstate.raise","event":{...},"delay":50,"id":"t1"}; seq instead of id for an anonymous delayed raise; neither for an after timer, whose event {"type":"xstate.after","delay":50,"stateId":"m.a"} identifies it |
| cancel | {"kind":"builtin","type":"@xstate.cancel", ...key} |
| terminate | {"kind":"builtin","type":"@xstate.terminate","status":"done","output":...}, last effect of the macrostep that completes the machine |
Immediate raises are not effects: their events go to the internal queue and show up as internal microsteps.
Snapshot #
{
"value": { "p": { "a": "a1", "b": "b2" } },
"context": { "n": 1 },
"status": "active", // active | done | error
"output": { }, // when done and defined
"error": "guard failed", // when status is error
"history": { "m.on.hist": ["m.on.second"] },
"timers": [ { "key": { "id": "t1" }, "event": { "type": "PING" }, "delay": 50, "due": 80 } ]
}
historymaps each history state that has a value to the stored state ids (shallow: children of the parent; deep: atomic descendants).timersare XState's logical timers in snapshot order.keyis the timer key:{"id"}for a delayed raise with an id,{"seq"}for one without (numbered per machine from 0),{"event"}for anaftertimer.dueis when the host fires it; it is absent when the host has no such timer scheduled (see NOTES.md).- Compare
valueobjects as maps: XState does not keep their keys in document order.
Trace format, version 2 #
Version 2 records a root machine and every actor it creates, run live with createActor on a SimulatedClock. A version 2 trace has the version 1 top-level fields with "version": 2, plus:
{
"input": { "name": "ada" }, // optional: the root actor's input
"actors": { // optional: the actor registry, by source name
"child": { "kind": "machine", "machine": { /* MachineJSON */ } },
"fetch": { "kind": "async" },
"pinger": { "kind": "callback", "start": [{ "type": "READY" }], "reply": { "PING": [{ "type": "PONG" }] } }
}
}
invoke.src and the spawn operation name a registry entry. The kinds (see src/vocab.mjs):
| Kind | Behavior |
|---|---|
machine |
A MachineJSON machine, with the same vocabulary as the root. It may invoke and spawn registry entries itself. |
async |
Async logic. With resolve: V it resolves with V, with reject: "msg" it rejects with that message, with echo: true it resolves with its input; each settles a microtask after it starts. With none of them the script settles it. timeout: ms is the logic's own timeout (it rejects with XState's TimeoutError message). |
callback |
Callback logic. On start it sends each start event to its parent; when it receives an event whose type is a key of reply, it sends those events to its parent. Its events reach the parent through the callback actor's own xstate.callback.sendBack macrostep. |
Addresses #
Every actor is named by its address: the root's id, then each child id down the tree, joined by / (parent/worker/leaf). Children without an explicit id get XState's generated ids, <src>:<n>.
Steps #
The step inputs of version 1 (init, event, advance), and:
{ "event": { "type": "PING" }, "to": "parent/child" } // send from outside to a running child (default: the root)
{ "resolve": "parent/fetch", "output": { "v": 1 } } // settle a pending async child
{ "reject": "parent/fetch", "error": "network down" }
{ "restore": true } // persist the root, restore a new actor from it, start it
{ "stop": true } // stop the root actor
- After each input the recorder lets promise callbacks run before the next input, so async completions and their effects belong to the step that caused them.
advancefires due timers one deadline at a time (equal deadlines together), letting promise callbacks run after each deadline.restoretakesgetPersistedSnapshot()of the root after a JSON round trip and records it as the step'spersistedfield: golden data for the persisted snapshot format (design §7). The old system is then dropped unobserved, as if its host crashed, andrestoreActorstarts a new one frompersistedon the same clock.
A step records:
{
"input": { ... },
"now": 120,
"persisted": { ... }, // restore steps only
"macrosteps": [ M, ... ], // every actor macrostep, in the order XState published them
"inspection": [ I, ... ], // the inspection stream
"deadLetters": [ D, ... ] // optional: rejected events
}
Macrosteps #
One entry per actor macrostep, in the order XState emitted its @xstate.transition inspection event. That order is XState's: an event to an idle actor is processed synchronously while the sender is still executing its effects, so a child's macrostep can come before the sender's (NOTES.md).
A machine actor's macrostep has the version 1 fields and meaning, plus actor (its address). Its microsteps are XState's own, captured from the live transition. snapshot is the actor's snapshot after the macrostep. Differences from version 1:
restored: true: the actor was restored from a persisted snapshot and started without computing a transition.microstepsis empty.uninspected: true: the actor's initial transition threw and did not recover, so XState published no@xstate.transitionevent. These are listed at the end of the step. The snapshot then is{"status": "error", "error": ...}, without value or context.- A microstep
kindcan bestop: the actor processedxstate.stop. A stopped machine runs no exit actions; the stop macrostep only cancels its timers and stops its own children. Its snapshot has statusstopped. - A done or error actor gets no macrostep for later events: the runtime rejects them (a dead letter with reason
stopped). Version 1 records an ignored macrostep instead. - The first microstep of an initial transition that recovered through the root's
onErroris the pre-initial snapshot; the second, of kinderror, selects the error event.
An async or callback actor's macrostep has no microsteps:
{ "actor": "parent/fetch", "logic": "async", "event": { "type": "xstate.async.resolve", "data": 1 }, "at": 0,
"snapshot": { "status": "done", "output": 1 } }
Effects #
The version 1 effects, and (sources are omitted; it is always the actor that produced the effect):
| Effect | Shape |
|---|---|
| spawn | {"kind":"builtin","type":"@xstate.spawn","actor":"parent/c","id":"c","src":"child","input":...} |
| start, stop | {"kind":"builtin","type":"@xstate.start","actor":"parent/c","id":"c"}, likewise @xstate.stop |
| sendTo | {"kind":"builtin","type":"@xstate.sendTo","target":"parent","event":{...}}, with delay and id or seq for a delayed send (a logical timer of the sender) |
| dead letter | {"kind":"builtin","type":"@xstate.deadLetter","targetId":"nobody","event":{...},"reason":"missingTarget"} |
| log | {"kind":"builtin","type":"@xstate.log","args":[...]} |
When a delayed sendTo fires, its timer microstep has the immediate @xstate.sendTo effect that delivers it.
Events #
Events are recorded as plain data. Actor events (xstate.done.actor, xstate.error.actor, xstate.snapshot.actor, xstate.timeout.actor) lose their sessionId, a random per-run token; actorId names the child. Errors are recorded by message. The snapshot of xstate.snapshot.actor is {status, value, context, output?, error?} for a machine, and the logic's own snapshot otherwise.
Snapshot #
A machine snapshot has the version 1 fields, and:
statuscan bestopped.children: child id to its registry source name, when the machine has children.- A timer of a delayed sendTo has
target, the target's address. duecomes from the live system's scheduler.
Inspection #
The step's inspection list is XState's inspection stream in order, normalized:
{ "type": "@xstate.actor", "actor": "parent/c", "parent": "parent", "id": "c", "src": "child",
"snapshot": { "status": "active", "value": "idle", "context": {} } }
{ "type": "@xstate.transition", "macrostep": 3, "source": "parent", "event": { "type": "PING" },
"microsteps": [ /* transitions, as in microsteps */ ],
"actions": [ { "type": "@xstate.sendTo" }, { "type": "rec", "params": { "label": "x" } } ],
"sent": [ { "target": "parent", "event": { "type": "PONG" } } ] }
@xstate.actor: an actor was created.parentis absent for the root andsrcfor logic not named in the registry (the root).snapshotis the creation snapshot, in brief.@xstate.transition:macrostepis the index of the step's macrostep it belongs to; that macrostep'ssnapshotis the transition's snapshot.sourceis the sender's address (absent for external events and the root's init).eventis the event XState reports; it differs from the macrostep'seventfor a recovered error (xstate.error.execution).microstepsare the transitions taken,actionsthe executed effects in order (custom actions with their params, emitted events by their type, built-ins by type only; entry/exit markers removed), andsentthe events sent to other actors or scheduled, including delayed raises.
Dead letters #
deadLetters lists XState's onRejectedEvent reports in order: {macrostep, source?, target?, targetId?, event, reason}. macrostep is how many of the step's macrosteps were recorded before the rejection. Reasons seen: missingTarget (unknown child, empty registry key, parent of the root), stopped (event to a stopped, done or error actor).
Actor operations #
MachineJSON has no serialized form for sendTo, spawn or stop. Version 2 fixtures name these operations like custom actions, and the Rust registry implements them with enq.send_to, enq.spawn and enq.stop:
| Operation | Params | Effect |
|---|---|---|
sendTo |
to, event, optional delay, id |
Sends event. to is {"child": id}, {"parent": true} (sendParent), {"system": registryKey} or {"self": true}. A missing target is a dead letter. |
spawn |
src, optional id, registryKey, input, syncSnapshot |
Spawns the registry entry src. |
stop |
child |
Stops the child with that id; nothing if there is none. |
assignFrom |
key, path |
Sets context[key] to the value at path (an array of keys) in the event being processed, null if missing; errors become their message. Used to read input from xstate.init, output from xstate.done.actor, error from xstate.error.actor, and snapshots. |
The recorder rewrites each operation into a @code action for an evaluator before loading the machine, so it runs inside the transition with enq, as a code-defined v6 action would; the trace stores the machine as written. Operations are actions, so they appear in entry, exit and transition actions, and they take part in the context-patch order of version 1 (assignFrom patches like @xstate.assign).
Invoke id, src, registryKey, input (a literal), onDone, onError, onSnapshot, timeout and onTimeout, and state timeout/onTimeout, are MachineJSON features. Children's completion can also be handled with on and a matches: {"actorId": id} pattern on xstate.done.actor, xstate.error.actor and xstate.snapshot.actor.
Vocabulary #
Cases use only MachineJSON features plus this fixed vocabulary, so the Rust registry can implement it identically. Expressions (@expr, @code) are not used.
Guards ("guard": {"type": ..., "params": ...}), evaluated against the context before the microstep and the event being processed:
| Guard | Params | True when |
|---|---|---|
ctxEq |
key, value |
context[key] deep-equals value; a missing key counts as null |
ctxLt |
key, value |
context[key] is a number and less than value |
eventEq |
key, value |
event[key] deep-equals value; a missing key counts as null |
is |
value |
value is true |
fail |
message |
never returns: throws an execution error with message |
@xstate.not |
guard |
the inner guard is false (built in) |
@xstate.stateIn |
stateId |
the state with that id is active (built in) |
Actions (in entry, exit and transition actions):
| Action | Effect |
|---|---|
{"type":"rec","params":P} |
records a custom action effect with params P; does nothing else |
{"type":"@xstate.assign","context":{...}} |
merges a literal patch into context |
{"type":"@xstate.raise","event":E} |
raises E on the internal queue |
{"type":"@xstate.raise","event":E,"delay":ms,"id"?:id} |
schedules a delayed raise (a logical timer) |
{"type":"@xstate.cancel","id":id} |
cancels the timer with that id |
{"type":"@xstate.emit","event":E} |
emits E |
Transitions use target ("sibling", ".child", "#id", or an array), reenter, guard, matches (shallow payload equality), a literal context patch, and actions. Guarded arrays select the first enabled candidate. Within one transition, the context patch applies first, then actions in order.
Other features used: initial, type (parallel, final, history with history: shallow|deep and a default target, choice with when branches), always, after with millisecond keys or names from the machine's delays map, onError, final output, and wildcard descriptors (*, prefix.*). State completion is handled with "on": {"xstate.done.state": {"matches": {"stateId": "<id of the completed state>"}, ...}}, since MachineJSON has no state-level onDone.
Incrementing context. XState runs custom actions after the transition and ignores their return value, and @xstate.assign only takes literals without an expression evaluator. An increment is therefore written as a guarded array over the possible values: [{"guard": ctxEq(n, 0), "context": {"n": 1}}, {"guard": ctxEq(n, 1), "context": {"n": 2}}, ...] (inc in cases/util.mjs; the generator counts modulo 3).
The random corpus #
src/generator.mjs builds a chart and a script from a seed: depth up to 5, compound, parallel, final, shallow and deep history states, always, after, delayed raises and cancels, reenter, guards and guarded arrays, wildcards, multi-target transitions into parallel regions, transitions between regions and to ancestors and descendants, and done handlers. Scripts mix events (with a random payload field p) and clock advances. The comments in the generator list the rules that keep every macrostep finite. A chart XState rejects, or one whose macrostep does not settle within 1000 microsteps, is replaced by the next attempt for the same seed (origin.attempt).
generateSystemCase builds version 2 cases (traces/random-actors/, seeds SYSTEM_SEEDS): a generated root chart decorated, from a separate random stream, with invokes of a generated child machine, an async child and a callback child (with input, onDone, onError, onSnapshot, invoke timeouts), sends to children (including missing ones), spawns and stops, and replies from children; scripts add async settlements and persist/restore steps. Settling an async actor that is not pending does nothing. The generator comments list the extra rules that keep the system finite.
To grow the corpus, extend RANDOM_SEEDS or SYSTEM_SEEDS and run npm run regen. Changing the generator changes existing random traces; that is fine, review the counts rather than the diffs.
Adding a hand case #
A topic file that exports version = 2 holds version 2 cases, which may also have actors and input. Add an entry to the topic file in cases/ (or a new file): name (unique, kebab-case), description, ref (the XState test or issue), machine (must have an id), and script. JavaScript reorders integer-like object keys, so when key order matters (several after delays, design §2 D6) write machine as a JSON string: the trace then stores it in the written order. Run npm run regen and read the result with src/show.mjs before committing; if XState does something surprising, write it down in NOTES.md.
Re-pinning XState #
Change the version in package.json and XSTATE_VERSION in src/recorder.mjs, npm install, npm run regen, and review the trace diff. Every changed trace is a semantic change the kernel must follow or allow-list (design §9.5).