README.md

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: type plus payload fields.
  • advance: move the clock forward by advance ms. 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. now is 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
}
  • event is {"type":"xstate.init"}, the script event, or a timer notification {"type":"xstate.timer", ...key} where key is the timer key (below).
  • handled is false exactly when XState's isUnhandled() holds: no transition was enabled, no effects, snapshot unchanged. A done or error machine ignores every event: handled: false and no microsteps.
  • error: the macrostep threw an execution error (only the fail guard throws). All of its work is discarded. If any active state declares onError, the macrostep reruns from the pre-event snapshot with {"type":"xstate.error.execution","error":message} and recovered is true; microsteps are those of the rerun. Otherwise recovered is false, microsteps is empty, and the snapshot is the pre-event snapshot with status error.

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 for event, internal and error.
  • transitions: the transitions taken, after conflict resolution, in selection order. A transition is identified by its source state id, its event descriptor (an event name, a wildcard such as user.* or *, "" for always, xstate.after, xstate.done.state, or xstate.error.* for onError), and index, its position in the source's JSON list for that descriptor (on[descriptor], always, onError). For after, delay is the after key and index counts within that key's list. targets are the resolved target state ids (a history state appears as itself, not as what it restored). reenter is 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 } ]
}
  • history maps each history state that has a value to the stored state ids (shallow: children of the parent; deep: atomic descendants).
  • timers are XState's logical timers in snapshot order. key is the timer key: {"id"} for a delayed raise with an id, {"seq"} for one without (numbered per machine from 0), {"event"} for an after timer. due is when the host fires it; it is absent when the host has no such timer scheduled (see NOTES.md).
  • Compare value objects 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.
  • advance fires due timers one deadline at a time (equal deadlines together), letting promise callbacks run after each deadline.
  • restore takes getPersistedSnapshot() of the root after a JSON round trip and records it as the step's persisted field: golden data for the persisted snapshot format (design §7). The old system is then dropped unobserved, as if its host crashed, and restoreActor starts a new one from persisted on 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. microsteps is empty.
  • uninspected: true: the actor's initial transition threw and did not recover, so XState published no @xstate.transition event. These are listed at the end of the step. The snapshot then is {"status": "error", "error": ...}, without value or context.
  • A microstep kind can be stop: the actor processed xstate.stop. A stopped machine runs no exit actions; the stop macrostep only cancels its timers and stops its own children. Its snapshot has status stopped.
  • 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 onError is the pre-initial snapshot; the second, of kind error, 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:

  • status can be stopped.
  • 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.
  • due comes 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. parent is absent for the root and src for logic not named in the registry (the root). snapshot is the creation snapshot, in brief.
  • @xstate.transition: macrostep is the index of the step's macrostep it belongs to; that macrostep's snapshot is the transition's snapshot. source is the sender's address (absent for external events and the root's init). event is the event XState reports; it differs from the macrostep's event for a recovered error (xstate.error.execution). microsteps are the transitions taken, actions the executed effects in order (custom actions with their params, emitted events by their type, built-ins by type only; entry/exit markers removed), and sent the 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).