xstate 6.0.0-beta.0 → 6.0.0-beta.2

package/docs/serialization.md

@@ -85,7 +85,7 @@ const machine = machineFromJSON(definition, {
 
 The second argument supplies the runtime sources the definition refers to: `actions`, `guards`, `actors`, `delays`, and `evaluators` for code expressions. Invokes keep their string `src` names, so a machine built this way can be cloned with different actors through [`provide()`](setup-and-provide.md), including when restoring its children. Deserialization still requires an implementation for every referenced actor; provide the initial implementations in the second argument, then override them by name.
 
-Actions in JSON are objects. The built-in vocabulary is `{ type: '@xstate.raise', event, id?, delay? }`, `{ type: '@xstate.emit', event }`, `{ type: '@xstate.assign', context }`, `{ type: '@xstate.cancel', id }` and `{ type: '@xstate.log', args }`. Any other `{ type, params }` object is a custom action resolved against the `actions` sources. Guards are `{ type, params? }` references resolved against `guards`. Two guard types are built in: `{ type: '@xstate.not', params: { guard } }` negates another guard reference or expression, and `{ type: '@xstate.stateIn', params: { stateId: '#id' } }` is true while the state node with that `id` is active (the same check as `snapshot.matches('#id')`). Source names, and the names of `actions`, `guards` and `delays` defined in the JSON, may not start with `xstate.` or `@xstate.`; those prefixes are reserved for built-in names. Because the runtime invokes these references itself, a JSON-referenced guard receives the transition arguments object first and the declared `params` second — unlike code-authored machines, where guards are plain functions called by your own transition code.
+Actions in JSON are objects. The built-in vocabulary is `{ type: '@xstate.raise', event, id?, delay? }`, `{ type: '@xstate.emit', event }`, `{ type: '@xstate.assign', context }`, `{ type: '@xstate.cancel', id }` and `{ type: '@xstate.log', args }`. Any other `{ type, params }` object is a custom action resolved against the `actions` sources. Guards are `{ type, params? }` references resolved against `guards`. Two guard types are built in: `{ type: '@xstate.not', params: { guard } }` negates another guard reference or expression, and `{ type: '@xstate.stateIn', params: { stateId: '#id' } }` is true while the state node with that `id` is active (the same check as `snapshot.matches('#id')`). Source names, and the names of `actions`, `guards` and `delays` defined in the JSON, may not start with `xstate.` or `@xstate.`; those prefixes are reserved for built-in names. Because the runtime invokes these references itself, a JSON-referenced guard receives the transition arguments object first and the declared `params` second. This differs from code-authored machines, where guards are plain functions called by your own transition code.
 
 Machines built from JSON round-trip losslessly. The loader copies the definition, and each serialization returns a fresh copy. Mutating either copy does not change the machine.
 

package/docs/setup-and-provide.md

@@ -140,8 +140,8 @@ Validation can be installed, replaced or disabled by a derived setup. Installing
 
 Where a validation failure surfaces depends on which side of the delivery boundary produced the invalid value:
 
-- **Events arriving from outside the actor** — from `actor.send` or from another actor — are rejected at the boundary when their payload fails its schema, or when the event type is undeclared and `unknownEvents` is `'error'`. The event is never delivered: the actor does not transition, does not error, and no API throws. The rejection is reported to the `onRejectedEvent` dead-letter hook on `createActor` options and as a development-mode console warning. In pure `transition(...)` calls, the snapshot is returned unchanged together with a `@xstate.deadLetter` effect carrying the rejection.
-- **Values the actor produces itself** — input, context, output, emitted events and delayed raised events — error the actor when they fail their schema, and pure `transition(...)`/`initialTransition(...)` throw an `ActorValidationError`. These are machine bugs.
+- **Events arriving from outside the actor** (from `actor.send` or from another actor) are rejected at the boundary when their payload fails its schema, or when the event type is undeclared and `unknownEvents` is `'error'`. The event is never delivered: the actor does not transition, does not error, and no API throws. The rejection is reported to the `onRejectedEvent` dead-letter hook on `createActor` options and as a development-mode console warning. In pure `transition(...)` calls, the snapshot is returned unchanged together with a `@xstate.deadLetter` effect carrying the rejection.
+- **Values the actor produces itself** (input, context, output, emitted events and delayed raised events) error the actor when they fail their schema, and pure `transition(...)`/`initialTransition(...)` throw an `ActorValidationError`. These are machine bugs.
 
 ## Sources on the machine
 
@@ -175,7 +175,7 @@ idle: {
 }
 ```
 
-Named actions and guards are plain functions called with only their params — nothing is injected. Pass values from `context` or the event explicitly. Declare param types on the function itself, or with `schemas.actions` and `schemas.guards` so the params are checked before the implementations exist:
+Named actions and guards are plain functions called with only their params. Nothing is injected. Pass values from `context` or the event explicitly. Declare param types on the function itself, or with `schemas.actions` and `schemas.guards` so the params are checked before the implementations exist:
 
 ```ts
 setup({

package/docs/spawn.md

@@ -46,7 +46,7 @@ The name is checked against `actors`; its required input and returned actor refe
 
 Passing the logic value remains convenient: `enq.spawn(actors.upload, options)`. XState recovers its registered name when possible. Inline unregistered logic may run but cannot be durably persisted.
 
-Spawning with an `id` that a live child of the same parent already uses throws: an address names at most one live actor. Stop the existing child first — an id stopped earlier in the same transition is free to reuse, and a child that completed on its own frees its id for the transition handling its completion. Generate ids from something stable, such as a file or participant id.
+Spawning with an `id` that a live child of the same parent already uses throws: an address names at most one live actor. Stop the existing child first. An id stopped earlier in the same transition is free to reuse, and a child that completed on its own frees its id for the transition handling its completion. Generate ids from something stable, such as a file or participant id.
 
 ## Where you can spawn
 

package/docs/system-transitions.md

@@ -67,8 +67,8 @@ actor's macrostep. Microsteps are atomic; system snapshots contain no unfinished
 microstep or continuation state. A UI presenting individual completed
 microsteps within a macrostep needs a separate tracing interface.
 
-Snapshot actor references are data: `{ $actor, incarnation }`, the same shape as `SerializedActorRef`, with a string `incarnation`. Use `$actor`
-as `actorPath`, for example `snapshot.actors[snapshot.root].snapshot.children.worker.$actor`.
+Snapshot actor references are data: `{ '@actor': address, incarnation }`, the same shape as `SerializedActorRef`, with a string `incarnation`. Use `@actor`
+as `actorPath`, for example `snapshot.actors[snapshot.root].snapshot.children.worker["@actor"]`.
 Paths encode IDs; avoid concatenating unescaped IDs. Replacing an actor at the
 same path allocates a fresh incarnation.
 
@@ -101,7 +101,7 @@ Select a pending timer in a simulator with its current occurrence:
 
 ```ts
 const selected = snapshot.timers.find((timer) => timer.dueAt === 6000)!;
-const [next] = systemTransition(systemLogic, snapshot, selected.source.$actor, {
+const [next] = systemTransition(systemLogic, snapshot, selected.source["@actor"], {
   type: 'xstate.timer',
   occurrence: selected.occurrence
 });
@@ -128,7 +128,7 @@ using the source actor's definition and saved input; the host owns the
 external implementation. Its result reenters as a correlated input:
 
 ```ts
-const [resolved] = systemTransition(systemLogic, pendingSnapshot, effect.source.$actor, {
+const [resolved] = systemTransition(systemLogic, pendingSnapshot, effect.source["@actor"], {
   type: 'xstate.system.effect.result',
   effectId: effect.id,
   event: { type: 'xstate.async.resolve', data: result }
@@ -150,8 +150,8 @@ input, outputs, events and effect arguments are JSON-compatible. Actor reference
 state-node references, errors and named mappers use data markers. Errors retain
 name/message. Undefined properties follow ordinary JSON rules. Cycles,
 unregistered functions, live actors, class instances, symbols, bigint and
-nonfinite numbers are rejected. `$actor`, `$stateNode`, `$error` and
-`$systemMapper` marker shapes are reserved. Logic versions must match on replay.
+nonfinite numbers are rejected. `@actor`, `@stateNode`, `@error` and
+`@systemMapper` marker shapes are reserved. Logic versions must match on replay.
 
 Transition functions, guards and mappers must be deterministic and pure.
 Read external values from input/events and virtual time from `system._clock.now()`.

package/docs/tutorial.md

@@ -430,7 +430,7 @@ Nothing about the machine changes. A UI reads snapshots and sends events.
 
 ```html
 <p id="status">stopped</p>
-<p id="title">—</p>
+<p id="title"></p>
 <button id="play">Play</button> <button id="pause">Pause</button>
 <button id="stop">Stop</button> <button id="previous">Previous</button>
 <button id="next">Next</button> <button id="mute">Mute</button>
@@ -475,7 +475,7 @@ Frameworks work the same way, with a hook or store binding instead of manual sub
 
 You built one machine with context, guards, invoked async logic, hierarchy, parallel regions, delayed events, emitted events and a UI. From here:
 
-- [Statecharts](statecharts.md) — nested, parallel and history states
-- [Actors](actors.md) — spawning, communication and actor systems
-- [Frameworks](frameworks.md) — bindings for React, Vue, Svelte and Solid
-- [Testing](testing.md) — testing machines and the actors that run them
+- [Statecharts](statecharts.md): nested, parallel and history states
+- [Actors](actors.md): spawning, communication and actor systems
+- [Frameworks](frameworks.md): bindings for React, Vue, Svelte and Solid
+- [Testing](testing.md): testing machines and the actors that run them

package/docs/typescript.md

@@ -49,6 +49,12 @@ adding explicit type annotations.
 
 For an actor used in one state, `invoke: s.createInvoke({ src, input, onDone })` infers input and completion output from `src`. Keep the helper inline in `s.createMachine(...)` to also infer that state's narrowed context, ancestor context, state input and transition target requirements. The helper works alongside named actor sources. See [typed inline invokes](invoke.md#typed-inline-invokes).
 
+A bare inline `invoke: { src: logic, onDone }` cannot correlate its source with
+the output; with no registered actor sources it has `event.output: unknown`.
+Use `s.createInvoke(...)` or a source registered in `setup({ actors })` when
+reading the output. This is especially important for generated machine code:
+the bare form cannot infer the output type from `src`.
+
 An async function can be used directly as `src`. Declare `schemas.input`, `schemas.output`, and `schemas.error` on the invoke to type the function and its lifecycle handlers together. Without `schemas.output`, `onDone.event.output` infers from the async return value.
 
 Public schema event keys create typed methods on `actor.trigger`; internal
@@ -84,6 +90,9 @@ When `schemas.events` is declared, each key in an `on` map must match a
 declared event type. Matching wildcards (`'*'`, `'user.*'`) and known reserved
 machine descriptors are allowed; misspelled or invented reserved prefixes are rejected. Without `schemas.events`, any key is accepted.
 
+An empty `schemas.events: {}` means the machine has no public events. Final
+state output callbacks still receive the declared context and input types.
+
 ```ts
 on: {
   toggel: { target: 'active' }

package/docs/xstate-v5-to-v6.md

@@ -79,12 +79,12 @@ Beyond simplifying the action/guard surface, v6 introduces a number of features
 
 ## 1. Inline functions replace action creators
 
-This is the largest change. Action creators (`assign`, `raise`, `sendTo`, `emit`, `log`, `cancel`, `enqueueActions`, `spawnChild`, `stopChild`, `forwardTo`, `sendParent`) are **no longer exported**.
+This is the largest change. Action creators (`assign`, `raise`, `sendTo`, `emit`, `log`, `cancel`, `enqueueActions`, `spawnChild`, `stopChild`, `forwardTo`, `sendParent`) are no longer exported.
 
-In v6, every `entry`, `exit`, and transition handler is a **single function** that receives `(args, enq)` where `enq` is a queue of side effects. The function can also **return** an object that the engine applies after it runs:
+In v6, every `entry`, `exit`, and transition handler is a **single function** that receives `(args, enq)` where `enq` is a queue of side effects. The function can also return an object that the engine applies after it runs:
 
 - **Transition handlers** (`on`, `always`, `after`, `onTimeout`, `onDone`, `onError`) - may return a target, a new `context`, `reenter`, or `meta`.
-- **Entry / exit actions** - may return a new `context` (or `children`). They **cannot** return a `target`; entry/exit cannot transition.
+- **Entry / exit actions** - may return a new `context` (or `children`). They cannot return a `target`; entry/exit cannot transition.
 
 Returned `context` values are patches. XState merges a patch into the current context at the top level (`{ ...context, ...patch }`): omitted keys keep their current values, and a nested object in the patch replaces the current value of that key. If a transition targets a state with a narrower `schemas.context`, the patch type requires the keys needed to satisfy that state's context.
 
@@ -241,7 +241,7 @@ An **entry / exit action** may return:
 | `context`  | shallow context patch       |
 | `children` | replacement children record |
 
-Returning nothing (`undefined`) means "no changes". For transition handlers specifically, returning nothing without calling `enq` also means **the event is treated as unhandled at this state** - useful for inline guarding. A handler that calls `enq` is taken even when it returns nothing, so check the condition first:
+Returning nothing (`undefined`) means "no changes". For transition handlers specifically, returning nothing without calling `enq` also means the event is treated as unhandled at this state - useful for inline guarding. A handler that calls `enq` is taken even when it returns nothing, so check the condition first:
 
 ```ts
 // v6 - guard inline by returning undefined
@@ -294,6 +294,26 @@ on: {
 }
 ```
 
+### Transitions inside parallel regions
+
+A transition whose targets stay inside one region of a parallel state exits
+and reenters that region only. In v5 the same transition, when it reentered
+its source or targeted a child state, exited the whole parallel state and
+reset every sibling region to its initial state. v6 leaves the siblings where
+they are. A transition declared on a sibling region for the same event still
+runs, because the two exit sets no longer overlap.
+
+```ts
+// Parallel state `p` with regions `a` and `b`.
+// Event `t`: `a` reenters itself; `b.b1` moves to `b.b2`.
+// v5 after `t`: { a: 'a1', b: 'b1' }: `b` was reset when `p` was exited.
+// v6 after `t`: { a: 'a1', b: 'b2' }: only `a` was exited.
+```
+
+Reset the sibling regions explicitly if the v5 behavior was intended: target
+the parallel state itself, or list a target in every region.
+`@xstate/scxml` keeps the SCXML exit semantics for SCXML sources.
+
 ---
 
 ## 2. Guards
@@ -552,7 +572,7 @@ These inferred typestates work as follows. See [Typestates](typestates.md) for t
 
 <!-- setup state contracts from SetupStateSchema in packages/core/src/setup.ts -->
 
-`setup()` still exists in v6 and still accepts `actions`, `guards`, `actors`, and `delays` (merged into every machine created from it). What changed: `types` is replaced by `schemas`, and `setup()` gains a `states` key for declaring **state contracts**. A contract can provide state-level schemas plus structural metadata and defaults such as `type`, `initial`, `history`, `target`, `id`, and `route`. This types `createMachine` and `createStateConfig`, including the `initial: { target, input }` form and transitions targeting those states. Setups that declare only schemas remain permissive for compatibility.
+`setup()` still exists in v6 and still accepts `actions`, `guards`, `actors`, and `delays` (merged into every machine created from it). What changed: `types` is replaced by `schemas`, and `setup()` gains a `states` key for declaring **state contracts**. A contract can provide state-level schemas plus structural metadata and defaults such as `type`, `initial`, `history`, `target`, `id`, and `route`. This types `createMachine` and `createStateConfig`, including the `initial: { target, input }` form and transitions targeting those states. Setups that declare only schemas don't require state contracts, but unknown literal transition targets are still type errors.
 
 ```ts
 // v6 - setup with root schemas and state-level input schemas
@@ -717,7 +737,7 @@ const fetchUser = createAsyncLogic({
 });
 ```
 
-`enq.step(key, exec)` records each step's outcome on the snapshot under `effects[key]`, so on rehydration the step is **not re-executed** - the previous result is replayed. This makes async logic durable across restarts.
+`enq.step(key, exec)` records each step's outcome on the snapshot under `effects[key]`, so on rehydration the step is not re-executed - the previous result is replayed. This makes async logic durable across restarts.
 
 When `timeout` elapses, the logic aborts and rejects with `TimeoutError` (also exported):
 
@@ -922,8 +942,8 @@ on: {
 
 ## 12. Internal events
 
-Events declared in `schemas.internalEvents` can be **raised** internally but
-are **rejected** by the public actor protocol. Wildcard patterns are supported.
+Events declared in `schemas.internalEvents` can be raised internally but
+are rejected by the public actor protocol. Wildcard patterns are supported.
 
 ```ts
 const machine = createMachine({
@@ -994,7 +1014,7 @@ states: {
 
 The function must resolve to a target - returning `undefined` throws "must resolve to a target".
 
-Choice states are entered automatically by routing **into** them. They cannot themselves declare `invoke`, `after`, `on`, or `entry`/`exit` (machine creation rejects these).
+Choice states are entered automatically by routing into them. They cannot themselves declare `invoke`, `after`, `on`, or `entry`/`exit` (machine creation rejects these).
 
 ---
 
@@ -1026,7 +1046,7 @@ State `timeout` and `createAsyncLogic({ timeout })` accept `number` (ms) or `str
 | Seconds           | `'5s'`, `'1.5s'`                                               | integer or decimal + `s` suffix |
 | ISO 8601 duration | `'PT5S'`, `'PT1M30S'`, `'PT2H'`, `'P1D'`, `'P1W'`, `'P1DT12H'` | always starts with `P`          |
 
-Plain `'5m'`, `'1h'`, `'1d'`, `'1w'` (without the `P`/`PT` prefix) are **not** accepted - use the ISO 8601 form for anything beyond seconds and milliseconds.
+Plain `'5m'`, `'1h'`, `'1d'`, `'1w'` (without the `P`/`PT` prefix) are not accepted - use the ISO 8601 form for anything beyond seconds and milliseconds.
 
 `after` delays accept the same duration formats. A string delay is resolved against the machine's named `delays` first; only strings that don't match a named delay are parsed as durations.
 
@@ -1058,13 +1078,18 @@ Transition arrays are not accepted by the authoring APIs. Use a single
 transition function to select among targets. Serialized transition arrays are
 still accepted by `machineFromJSON(...)`.
 
+A chain of eventless transitions that never settles ends the actor in v6. The
+actor processes at most 1000 microsteps per event and then fails with
+`InfiniteTransitionError`, so `snapshot.status` is `'error'`. v5 ran such a
+loop until the process ran out of memory.
+
 ---
 
 ## 16. Removed top-level exports
 
 <!-- exports removed from and added to packages/core/src/index.ts on the v6 branch (relative to main / v5) -->
 
-These exports have been **removed** from `xstate`:
+These exports have been removed from `xstate`:
 
 - Action creators (entire `actions.ts` module): `assign`, `raise`, `sendTo`, `sendParent`, `forwardTo`, `emit`, `log`, `cancel`, `enqueueActions`, `spawnChild`, `stopChild`, `stop`, plus their `*Action`/`*Params` types
 - Guard combinators and helpers: `and`, `or`, `not`, `stateIn`
@@ -1091,7 +1116,7 @@ These exports have been **removed** from `xstate`:
 
 `SetupReturn`, the type returned by `setup(...)`, is still exported, but its type parameters changed, so a v5 `SetupReturn<TContext, TEvent, ...>` annotation no longer type-checks. Use `typeof yourSetup` to name the type of a specific setup.
 
-These exports have been **added**:
+These exports have been added:
 
 - `setup` (reshaped - see §4) and `createSystem` for typed system registries
 - Setup state contract types: `SetupStateSchema`, `SetupStateSchemas`, `SetupStateType`
@@ -1250,7 +1275,7 @@ on: {
 
 ## 20. Persistence / rehydration
 
-Persisted snapshots round-trip through `JSON.stringify` and rehydrate via `restoreActor(machine, persisted)` from `xstate/persist`. The internal shape changed, so v5 persisted snapshots are **not** binary-compatible with v6 - drain or migrate stored state during your rollout.
+Persisted snapshots round-trip through `JSON.stringify` and rehydrate via `restoreActor(machine, persisted)` from `xstate/persist`. The internal shape changed, so v5 persisted snapshots are not binary-compatible with v6 - drain or migrate stored state during your rollout.
 
 ```ts
 import { restoreActor } from 'xstate/persist';
@@ -1271,7 +1296,7 @@ Child actors, async logic with effects, and listener-resume semantics are all pa
 
 The host serializes the payload. Development builds warn when `context`, `output`, `error`, or state input holds a value that does not survive a JSON round-trip: functions, symbols, `BigInt`, `Map`, `Set`, cycles, `NaN`, and `Infinity`. Persisting a snapshot whose `context` contains a circular reference throws an error that names the actor and the context path. See [Persistence](persistence.md) for the format rules.
 
-Actor refs in persisted `context` are stored as `{ "$actor": "<address>" }`. v5 stored them as `{ "xstate$$type": 1, "id": "<id>" }`; v6 does not read that shape, so convert those entries with [`machineVersions`](persistence.md#migrate-machine-versions) before restoring v5 snapshots.
+Actor refs in persisted `context` are stored as `{ "@actor": "<address>" }`. v5 stored them as `{ "xstate$$type": 1, "id": "<id>" }`; v6 does not read that shape, so convert those entries with [`machineVersions`](persistence.md#migrate-machine-versions) before restoring v5 snapshots.
 
 ### Snapshot versioning
 
@@ -1606,13 +1631,143 @@ It runs these transforms in order. `--transform name,name` selects a subset.
 | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `rename-imports`      | Renames `interpret` to `createActor`, `Interpreter` to `Actor`, and `fromCallback`, `fromObservable`, and `fromEventObservable` to their `create*Logic` names, and the executable action types to their executable effect names, including usages. Import aliases are kept.                                                                  |
 | `string-targets`      | Wraps bare string transition values under `on`, `after`, `onDone`, `onError`, and `always` in `{ target: '...' }` inside `createMachine` and `createStateConfig` configs.                                                                                                   |
-| `types-to-schemas`    | Converts `types: {} as { ... }` to `schemas` with `types<T>()` entries. Events become a map only when they are written as an inline union literal.                                                                                                                         |
+| `types-to-schemas`    | Converts `types: {} as { ... }` and the per-key form `types: { context: {} as C, events: {} as E }` to `schemas` with `types<T>()` entries. Events become a map when they are written as a union of object literals with a string-literal `type`, inline or through type aliases declared in the same file. Other event types become `events: types<E>()`, which loads but does not type-check as a v6 event map, so the entry is reported as a manual site to rewrite as a map by hand. A `types` value in any other shape, such as a variable, is reported as a manual site. |
+| `lower-actions`       | Rewrites transition objects that have `actions` or `guard`, and transition arrays, as one transition function `(args, enq) => { ... }`; non-function `entry` and `exit` values as one function; and the action creators and guard combinators inside them (`assign`, `enqueueActions`, `raise`, `sendTo`, `sendParent`, `forwardTo`, `emit`, `log`, `cancel`, `stopChild`, `spawnChild`, `and`, `or`, `not`, `stateIn`) as `enq` calls, context patches and boolean expressions, following named implementations and module-level constants defined in the same file. Named actions and guards keep their v5 signatures; the generated code calls them as `enq(args.actions.name, args, params)` and `args.guards.name(args, params)`. A named `assign` action becomes a function that returns a context patch. Moves an object-literal second `createMachine` argument into the config, and rewrites `fromPromise(fn)` as `createAsyncLogic({ run: fn })` when `fn` does not read `system` or `emit`. Removes the `'xstate'` imports it leaves unused. A transition, `entry`, or `exit` value that contains anything it cannot rewrite, such as an `enqueueActions` callback that passes `enqueue` as a value or returns early, a guard or action defined in another file, or a named `assign` that `provide()` overrides, is left unchanged and reported by the transforms below. |
 | `report-removed-apis` | Reports, without rewriting, uses of `assign`, `raise`, `sendTo`, `sendParent`, `forwardTo`, `emit`, `log`, `cancel`, `spawnChild`, `stop`, `stopChild`, `enqueueActions`, `and`, `or`, `not`, `stateIn`, `fromPromise`, `fromTransition`, `toObserver`, `pathToStateValue`, and `SpecialTargets`, with a suggested replacement. |
 | `report-id-path-targets` | Reports, without rewriting, `#a.b` targets and `matches('#a.b')` or `stateIn('#a.b')` arguments that are not whole state ids of the machine config that contains them. References outside a `createMachine` or `createStateConfig` config are always reported. v6 resolves `#` targets by exact id only. |
+| `suffixed-lifecycle-events` | Rewrites `on` keys that use suffixed v5 lifecycle event types to the category type with `matches`: `'xstate.done.actor.job': { target: 'done' }` becomes `'xstate.done.actor': { matches: { actorId: 'job' }, target: 'done' }`, and the same for `xstate.error.actor.<id>`, `xstate.snapshot.<id>` and `xstate.done.state.<id>` (with `stateId`). A function transition moves under `to`. Reports `xstate.after.<delay>.<id>` keys, keys whose category type is already handled in the same `on`, transitions that are not object or function literals, and suffixed type strings elsewhere in the file, such as `event.type === 'xstate.done.actor.job'`. See [Internal lifecycle events](#internal-lifecycle-events). |
+| `report-inspection-events` | Reports, without rewriting, string literals naming v5 inspection event types: `@xstate.event`, `@xstate.snapshot`, `@xstate.action`, `@xstate.microstep`, and `@xstate.deadletter`. v6 emits only `@xstate.actor` and `@xstate.transition`, so comparisons against the old types never match; TypeScript reports them only when the handler is typed with `InspectionEvent`. Scans every file, including files that do not import `xstate`. |
+| `report-action-shapes` | Reports, without rewriting, `entry` and `exit` values that are not functions (strings, arrays, objects, identifiers, or calls such as `assign(...)`), and `actions`, `guard`, and `cond` keys on transition objects under `on`, `after`, `always`, `onDone`, `onError`, `onSnapshot`, or an object `initial`, including each element of a transition array, and the transition arrays themselves. v6 rejects these shapes: `entry` and `exit` take a single function `(args, enq) => { ... }`, and transitions queue effects on `enq` and return `{ target }` or `undefined` instead of listing `actions` and `guard`. |
+| `report-implementations` | Reports, without rewriting, a second argument to `createMachine(config, implementations)` that `lower-actions` did not move into the config, such as a variable. v6 ignores the second argument. |
+
+`string-targets` wraps string elements inside transition arrays but keeps the arrays. `lower-actions` rewrites a transition array as one function when any element has `actions` or `guard`; `report-action-shapes` reports the arrays that remain. The v6 `createMachine` types reject transition arrays in `on` and `always` (for example, `on: { X: [ … ] }`); replace each with one transition function (§15, §16).
+
+`lower-actions` converts the action creators and guard combinators it can resolve in the file. Rewrite the reported ones as inline functions by hand (§1, §2). The transforms read and write imports from `'xstate'` only.
+
+### Exit codes and JSON output
+
+`migrate` exits with one of these codes:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | No manual migration is needed. |
+| `1` | Usage error, or the transformed output failed the syntax check and was not written. |
+| `2` | Manual migration is needed. At least one transform reported a site. |
+
+`--json` prints one JSON report to stdout instead of the text summary. `manualSites` lists each reported site:
+
+```json
+{
+  "filesChanged": 1,
+  "files": [{ "filePath": "...", "changed": true, "transforms": [{ "name": "...", "changed": true, "notes": [] }] }],
+  "manualSites": [{ "file": "...", "line": 12, "column": 7, "api": "assign", "hint": "...", "transform": "report-removed-apis" }]
+}
+```
+
+### Check behavior with `baseline` and `verify`
+
+<!-- commands, flags and report fields from packages/xstate-codemod/src/verify/cli.ts, run.ts, diff.ts and deltas.ts -->
+
+`baseline` and `verify` check that a migrated machine behaves like the v5 original. `baseline` loads the v5 module under XState v5, generates event sequences, and records a trace of each one. `verify` loads the migrated module under XState v6, replays the same sequences, and compares the traces step by step. The codemod package includes both XState versions and resolves `'xstate'` imports in the loaded file to the matching one, so the project can have either version installed.
+
+Record the baseline before `migrate` rewrites the file:
+
+```bash
+npx @xstate/codemod baseline src/checkout.ts --out .xstate-migrate/checkout.json
+npx @xstate/codemod migrate src/checkout.ts
+# fix the reported manual sites
+npx @xstate/codemod verify --baseline .xstate-migrate/checkout.json src/checkout.ts
+```
+
+When both versions exist as separate files, `verify v5-file v6-file` records the baseline and replays it in one run.
+
+The loaded module must export the machine. `--export name` selects an export. Otherwise the commands use the `default` export, then the first export that is actor logic. When the module exports more than one machine and `--export` is not passed, the baseline's `notes` and the text output name the exports and the one used.
+
+#### Sequences
+
+Sequences come from the v5 machine's shortest paths, its simple paths, and seeded random walks. Random walks also advance a simulated clock to the next pending timer, so they cover delayed transitions. `--walks` (default `25`), `--steps` (default `12`), and `--seed` (default `1`) control the walks. `--max-sequences` (default `200`) caps the total. Simple paths grow quickly with payload cases and parallel states; when `baseline` fails with `CHILD_TIMEOUT`, pass `--no-simple-paths` to skip them. The baseline stores the setting as `simplePaths: false` in `options`.
+
+While an actor runs, in both versions, `Date.now()` returns `1700000000000` plus the simulated clock's time, `performance.now()` returns the simulated clock's time, and `Math.random()` returns values from a generator seeded by `--seed` and the sequence index. A machine that stores these values in `context` records the same values under v5 and v6. `new Date()` without arguments still reads the real clock.
+
+Events are sent as `{ type }` unless an events file supplies payloads. Pass `--events events.json`, an object that maps each event type to a list of payloads:
+
+```json
+{ "ADD_ITEM": [{ "type": "ADD_ITEM", "sku": "A1" }, { "type": "ADD_ITEM", "sku": "B2" }] }
+```
+
+Event types without cases are listed in the report under `eventsWithoutCases`. When a guard throws because an event has no payload, the graph traversal that hit it is dropped and the event is left out of the random walks that reach it; each such case is listed under `generationErrors`. Add payload cases for those events to cover the transitions behind them. A graph traversal that hits its limit, usually because `context` changes on every step, is also listed there; random walks still cover those paths.
+
+#### Trace
+
+The baseline records, for the state after start and after each step:
+
+- `value`, `context`, `status`, `output`, and `error`
+- `processed`: every event the root actor processed during the step, in order, including raised, delayed, and done events
+- `children`: the live child actors, by id and source
+- `sent`: events sent to other actors, with the target id and delay
+- `emitted`: events emitted with `emit`
+- `actions`: custom actions run, by type and params
+
+Before comparison, events are normalized: suffixed v5 lifecycle event types such as `xstate.done.actor.<id>` become the v6 category types with their `actorId`, `stateId`, or `delay` fields, `xstate.init` is dropped, `sessionId` fields are removed, and generated child ids are replaced by `(anon)`. Functions and symbols in `context` and `output` are replaced by markers and counted under `nonSerializable`.
+
+`verify` compares every field except `actions` by default. `--compare +actions` adds it. Inline v6 actions have no stable type, so `actions` differ after most migrations. When both versions end a step with `status: 'error'`, only `status` and `error` are compared for that step, because a v6 errored snapshot has no `value`. For each sequence, the first mismatching field at a step is reported as one diff. An unclassified diff ends that sequence. A classified diff is recorded and the comparison continues, so an intentional difference cannot hide a later one.
+
+#### Stubs
+
+Invoked and spawned actors that are referenced by name are replaced by stubs. A stub defaults to `"pending"`, a promise that never settles. Pass `--stubs stubs.json` to script outcomes and delays:
+
+```json
+{
+  "actors": { "fetchUser": { "done": { "id": 1 } }, "saveOrder": { "error": "boom" }, "poll": "pending" },
+  "delays": { "RETRY": 100 }
+}
+```
+
+`done` resolves with the given output, and `error` rejects with the given value. `{}` resolves with `undefined`, and `{ "done": null }` resolves with `null`. `delays` sets named delays on both versions.
+
+A baseline records one outcome per actor. To cover both the `onDone` and `onError` paths, record a second baseline with a different `--stubs` file.
+
+#### Input
+
+Pass `--input input.json` when the machine reads `input`. The file's JSON value is passed as `createActor(logic, { input })` in both versions. `baseline` stores the input in the baseline file, and `verify --baseline` uses it unless `--input` is passed.
+
+When the machine errors at start, `baseline` and `verify` print `start: machine errored at start: <error>`, and `baseline --json` reports the message as `startError`. A machine that builds `context` from `input` errors this way when no input is passed.
+
+#### Results
+
+`verify` exits with one of these codes:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Equivalent. Every diff, if any, matched an intentional delta. |
+| `1` | Usage error. |
+| `3` | Diverged. At least one diff is `unclassified`. |
+| `4` | A module failed to load or run. `error` has the phase (`baseline` or `replay`), a code such as `EXPORT_NOT_FOUND`, and the message. |
+
+The default output is a summary and the first five unclassified diffs. `--json` prints the full report. Each entry in `diffs` has the sequence id, the step, the `field`, the v5 value as `expected`, the v6 value as `actual`, a `witness` (the events and clock advances that reproduce the step), and a `classification`. A `status` diff where either side errored also has a `detail` with the error message of each errored side.
+
+A diff that matches a known v6 change is classified with a rule instead of `unclassified`:
+
+| Rule | Diff |
+| --- | --- |
+| `anonymous-child-id` | Child or send-target ids that differ only by a generated suffix. |
+| `error-string-shape` | Error strings with the same message after the prefix is removed. |
+| `context-reference` | `context` that is equal after removing actor-reference keys (`@actor`). |
+| `done-event-session` | Processed events that are equal after dropping `sessionId`. |
+| `final-state-output` | `output` that is undefined in v5 and set in v6, because v6 uses a top-level final state's `output` when the root has none (see [Machine output](#machine-output)). |
+| `root-send-parent` | `status` and `error` where v5 errored with `Unable to send event to actor '#_parent'` and v6 did not, because v6 makes a send to a missing parent a dead letter (see [Sending to a missing target](#sending-to-a-missing-target)). Later fields of that step, such as `value`, can still differ. |
+
+Fix the v6 code for each unclassified diff. Do not edit the baseline.
 
-`string-targets` wraps string elements inside transition arrays but keeps the arrays. The v6 `createMachine` types reject transition arrays in `on` and `always` (for example, `on: { X: [ … ] }`), and no transform reports them. Find them by hand and replace each with one transition function (§15, §16).
+#### Limits
 
-The codemod does not convert action creators or guard combinators. Rewrite each reported `assign`, `raise`, `sendTo`, or other action creator as an inline function by hand (§1, §2). The transforms read and write imports from `'xstate'` only.
+- Actor logic written inline in `invoke.src` or `spawn` cannot be stubbed. It runs for real in both versions, and its source is listed under `unstubbed`.
+- Actions run for real. Side effects inside them, such as network requests or writes, happen during `baseline` and `verify`.
+- `actions` are not compared unless `--compare +actions` is passed. v6 records an `emit` as an action named after the emitted event, so `+actions` reports a diff on every emitting step.
+- Random walks advance the simulated clock to the next pending timer only. The v6 clock also fires timers scheduled during a jump and the v5 clock does not, so a longer jump would diverge on clock behavior alone.
+- An equivalent result covers the generated sequences only. Behavior that needs an event payload or actor outcome missing from the events and stubs files is not exercised.
+- A transition that reenters its own parallel region reports a `value` diff that is not classified. v5 reset the sibling regions and v6 leaves them in place (see "Transitions inside parallel regions"). Confirm that the v6 value is the intended one, or add explicit targets for the siblings.
+- A machine whose eventless transitions never settle makes `baseline` fail with `CHILD_CRASH` and an out-of-memory message, because v5 has no microstep limit. v6 ends the actor with `InfiniteTransitionError` instead. Fix the loop in the v5 machine before recording a baseline.
 
 ### Running v5 and v6 side by side
 
@@ -1629,7 +1784,7 @@ import { createMachine as createV5Machine } from 'xstate';
 import { createMachine } from 'xstate-v6';
 ```
 
-Migrate one file at a time: run the codemod on it, finish the manual changes, then change its `'xstate'` imports to `'xstate-v6'`. When no v5 imports remain, remove the alias and install `xstate@beta` as `xstate`.
+Migrate one file at a time: run the codemod on it, finish the manual changes, then change its `'xstate'` imports to `'xstate-v6'`. `verify` resolves `'xstate'`, `'xstate/*'`, `'xstate-v6'`, and `'xstate-v6/*'` imports in the migrated file to its own XState v6, so it works before or after the import change. When no v5 imports remain, remove the alias and install `xstate@beta` as `xstate`.
 
 ---
 
@@ -1685,7 +1840,7 @@ Code written against a v6 alpha uses names that changed before the beta. The old
 | `xstate.system.cancelEffect`, `xstate.logic.cleanup` effects | `@xstate.cancelEffect`, `@xstate.cleanup`                |
 | `xstate.logic.effect`, `xstate.log` system effects           | `@xstate.effect`, `@xstate.log`                          |
 | suffixed `xstate.done.actor.<id>` etc. descriptors           | category types with `matches` (see [Internal lifecycle events](#internal-lifecycle-events)) |
-| `{ xstate$type: 'actorRef', id, address, src }`              | `{ $actor: address }` (`SerializedActorRef`)             |
+| `{ xstate$type: 'actorRef', id, address, src }`              | `{ '@actor': address }` (`SerializedActorRef`; `$actor` in 6.0.0-beta.1) |
 | persisted timer `startedAt`                                  | `scheduledAt`                                            |
 | `snapshot.timers` record keyed by generated ids (`xstate.after.<delay>.<stateId>`, `xstate.timeout.state.<stateId>`, `xstate.timer.auto.<n>`) | list; built-in timers have no `id`, delayed sends without an `id` carry `seq` |
 | `scheduleTimer(source, id, delay)`, `cancelTimer(source, id)`, `{ type: 'xstate.timer', id }` | `scheduleTimer(source, timer, delay)`, `cancelTimer(source, timer)`, `{ type: 'xstate.timer', ...timer }` (`TimerKey`) |
@@ -1825,7 +1980,9 @@ In v5, an undeclared delay name resolved to `undefined`, and the delayed transit
 
 ## Migration checklist
 
+- [ ] Record a behavior baseline for each machine file with `xstate-codemod baseline` (§27)
 - [ ] Run `xstate-codemod migrate --dry`, apply it, and migrate the APIs it reports by hand (§27)
+- [ ] Run `xstate-codemod verify --baseline` on each migrated file and fix every unclassified diff (§27)
 - [ ] Replace every `assign({...})` with an inline function returning a shallow `{ context: {...} }` patch
 - [ ] Replace every `raise`, `sendTo`, `sendParent`, `forwardTo`, `emit`, `log`, `cancel`, `spawnChild`, `stopChild` with the corresponding `enq.*` call
 - [ ] Replace `enqueueActions(...)` with a regular inline `(args, enq) => { ... }` function

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xstate",
-  "version": "6.0.0-beta.0",
+  "version": "6.0.0-beta.2",
   "description": "Finite State Machines and Statecharts for the Modern Web.",
   "main": "dist/xstate.cjs.js",
   "bin": {