xstate 6.0.0-beta.1 → 6.0.0-beta.2

package/docs/backend-workflows.md

@@ -56,7 +56,7 @@ The same rule applies to writes the workflow makes. Pass an idempotency key to t
 
 ## Durable steps
 
-Async logic that runs several external calls can record each one on the snapshot with `enq.step(...)` — this page's pattern is hostless durability, where the snapshot is the journal, and `enq.step` is built for it (on a [durable host](durable-execution.md), write plain promise actors instead):
+Async logic that runs several external calls can record each one on the snapshot with `enq.step(...)`. This page's pattern is hostless durability, where the snapshot is the journal, and `enq.step` is built for it (on a [durable host](durable-execution.md), write plain promise actors instead):
 
 ```ts
 const fulfillOrder = createAsyncLogic({
@@ -91,7 +91,7 @@ Store the version alongside the snapshot so a restored workflow is either migrat
 
 ## Request-response endpoints
 
-Some endpoints have to answer with the result, not just acknowledge the event. Start the actor, send the event and wait for the snapshot you need:
+Some endpoints have to answer with the result, not only acknowledge the event. Start the actor, send the event and wait for the snapshot you need:
 
 ```ts
 import { waitFor } from 'xstate';
@@ -111,7 +111,7 @@ const settled = await waitFor(
 
 ## Long delays across restarts
 
-Pending delayed transitions are part of the snapshot: `snapshot.timers` lists each one with its declared delay and the event it will deliver. A snapshot persisted from a running actor also records each timer's wall-clock start (`scheduledAt`), and restoring it schedules the remaining time toward the original deadline — a timer already past due fires immediately, so a three-day `after` survives deploys. The deadline only holds while some process restores the actor and stays up; for timers that must fire with no process running, use a durable host that owns timer scheduling.
+Pending delayed transitions are part of the snapshot: `snapshot.timers` lists each one with its declared delay and the event it will deliver. A snapshot persisted from a running actor also records each timer's wall-clock start (`scheduledAt`), and restoring it schedules the remaining time toward the original deadline. A timer already past due fires immediately, so a three-day `after` survives deploys. The deadline only holds while some process restores the actor and stays up; for timers that must fire with no process running, use a durable host that owns timer scheduling.
 
 For deadlines that must respect real time, persist the scheduled and due times next to the snapshot and have the host (a scheduler, a queue with a visibility timeout, or a cron job) deliver the event when it is due. Keep short delays such as debounces and retry backoffs inside the machine, where restarting the delay has little effect.
 

package/docs/durable-execution.md

@@ -39,8 +39,8 @@ const durable = createDurable(machine, {
 const output = await durable.run(input);
 ```
 
-Runtime operations you omit keep their local behavior — spawned machine
-children run in this process, for example.
+Runtime operations you omit keep their local behavior. For example, spawned machine
+children run in this process.
 
 `enqueueRootEvent` is the narrow hook most co-located hosts need: it receives
 events sent to the execution root while the loop is parked, or at any time
@@ -53,8 +53,8 @@ runtime.
 The primary durable unit for async work is the actor itself: a developer
 writes a normal promise (`fromPromise`, `createAsyncLogic`) and invokes it;
 the `runLogic` operation hands the host the whole body as one journal
-entry. The actor's identity — `address`, string `src` key and serializable
-`input` — crosses any boundary, so a host either wraps the provided `exec`
+entry. The actor's identity (`address`, string `src` key and serializable
+`input`) crosses any boundary, so a host either wraps the provided `exec`
 in its own step primitive, or ignores it entirely and re-runs the
 registered logic on a remote executor from `(src, input)` alone; the output
 flows back as the actor's ordinary completion event. No step vocabulary
@@ -65,7 +65,7 @@ runLogic: (actor, exec) => ctx.run(actor.address, exec)          // in-process j
 runLogic: (actor) => activities.runLogic(actor.src, actor.getSnapshot().input) // remote executor
 ```
 
-Custom actions follow the same rule — durability crosses a boundary as
+Custom actions follow the same rule: durability crosses a boundary as
 declared identity plus serializable data, never as a closure. An action
 enqueued as a named function with serializable arguments
 (`enq(notifyApprover, context.orderId)`) carries `(type, args)` in its
@@ -75,19 +75,19 @@ descriptor, so a remote-executor host can dispatch it worker-side and ignore
 by its effect ID. Work heavy enough to deserve an activity is usually an
 actor, not an action.
 
-For finer granularity — several independently-journaled awaits — split into
+For finer granularity (several independently-journaled awaits), split into
 separate invoked actors: each actor is its own journal entry, and the states
 between them make the progress visible. Do not reach for `enq.step` on a
-durable host; it is the [hostless durability](actor-logic.md) tool — the
-snapshot is its journal — and on a durable host it only duplicates what
+durable host; it is the [hostless durability](actor-logic.md) tool (the
+snapshot is its journal), and on a durable host it only duplicates what
 `runLogic` already provides. When restored snapshots that carry step results
 do run under a durable host, `enq.step` routes through the `runStep`
 operation:
-implement it to journal steps in the host's journal — a memoized result
-replays without re-running the step — and the built-in
+implement it to journal steps in the host's journal (a memoized result
+replays without re-running the step), and the built-in
 snapshot memoization steps aside. Unlike other operations, a step is an
 orchestration frame that may itself await runtime operations of the same
-execution, so it is never serialized behind them — and for the same reason
+execution, so it is never serialized behind them. For the same reason,
 `executeEffects` resolves without awaiting it. The `runStep` helper exported
 from `xstate` exposes the built-in behavior. `exec` is a closure over live
 execution state: run it in this process and journal its result; it cannot be
@@ -99,7 +99,7 @@ either race its durable wait against the pending `runLogic`/`runStep`
 promises it created (the natural shape when they map to the engine's own
 step primitives), or drain them to empty first. An in-flight step ends by
 completing its actor, and that completion event cannot satisfy a durable
-wait that was already registered with the engine — the run deadlocks until
+wait that was already registered with the engine, so the run deadlocks until
 its idle timeout. The in-process loop above needs none of this, because any
 later event resolves its wait. Operations initiated by live child
 actors (parent sends, timers, terminations) route to your implementations
@@ -120,19 +120,38 @@ while (state.status === 'active') {
 reporting up), and only when none are queued defers to the adapter's durable
 wait.
 
-Checkpoint with `getPersistedSnapshot(state)` after `executeEffects`
-resolves, and persist `durable.nextTransitionIndex` alongside; pass it as
-`transitionIndex` when recreating the execution from a checkpoint instead of
-replaying from the beginning. Restore the checkpoint before entering the loop:
+Checkpoint with `durable.checkpoint(state)` after `executeEffects` resolves,
+and persist the whole result atomically. A checkpoint holds three things:
+
+- `snapshot`: the persisted snapshot. `checkpoint(state, options)` passes
+  `options` to the logic's `getPersistedSnapshot`.
+- `nextTransitionIndex`: the index the next transition gets.
+- `inbox`: root-addressed events that settled batches captured and
+  `waitForEvent()` has not handed out yet, such as a child's
+  `xstate.done.actor` or an event a child sent to its parent. Each entry's
+  `source` is the sender's address, `{ '@actor': address }`.
+
+Without the inbox, an event captured in the last batch exists only in memory.
+A child that completed during that batch is not restarted on restore, so its
+completion would never arrive.
+
+Inbox event payloads are stored as they are and must be serializable data,
+like timer events in a persisted snapshot. Child snapshot updates
+(`xstate.snapshot.actor`) are not stored: a restored active child reports its
+current snapshot when it starts. Completion, error and timeout events for a
+child that is no longer in the snapshot, or that a later transition replaced,
+are dropped.
+
+Restore the checkpoint on a fresh execution before entering the loop:
 
 <!-- checkpoint restoration contract from packages/core/src/durable/index.ts -->
 
 ```ts
-const resumed = createDurable(machine, {
-  ...adapter,
-  transitionIndex: checkpoint.nextTransitionIndex
-});
-let [state, effects] = resumed.restore(checkpoint.snapshot);
+await db.save(durable.checkpoint(state));
+
+// later, on any worker
+const resumed = createDurable(machine, adapter);
+let [state, effects] = resumed.restore(await db.load());
 await resumed.executeEffects(effects);
 
 while (state.status === 'active') {
@@ -141,6 +160,12 @@ while (state.status === 'active') {
 }
 ```
 
+The resumed execution continues from the checkpoint's `nextTransitionIndex`,
+and `waitForEvent()` hands out the inbox before the adapter's wait. If the
+adapter also sets `transitionIndex`, it must equal the checkpoint's
+`nextTransitionIndex`. `restore()` also accepts a bare persisted snapshot; pass
+`transitionIndex` to `createDurable` in that case.
+
 `restore()` rehydrates the snapshot and attaches the adapter across the actor
 tree. It returns effects that start active embedded children and re-arm pending
 root timers. Nothing starts until `executeEffects()` runs. Completed children
@@ -188,14 +213,14 @@ of a local child. Session ids embed a random per-process system id, so a
 host that journals the execution's own events (rather than only external
 ones) must pin `executionId` on the adapter: session ids become
 `<executionId>:<n>`, a deterministic function of actor-creation order, and a
-replayed execution re-creates the same ids — a journaled completion still
+replayed execution re-creates the same ids, so a journaled completion still
 matches the child the replay re-creates. Uniqueness across executions is the
 host's responsibility. For a remote child the owning runtime is the authority on
 staleness by default; a host that stores an opaque `incarnation` token on
 the persisted child entry gets the same guard on the referencing side. The
 token is the owner's `sessionId` for the child and the restored handle
-carries it as its own `sessionId` — one incarnation identity, one rule: a
-ref that knows its incarnation compares it, one that does not defers to the
+carries it as its own `sessionId`. A
+ref that knows its incarnation compares it; one that does not defers to the
 owner. `sendTo` effect descriptors journal the target's token so a send
 replayed after the address was reincarnated is detectable.
 
@@ -277,11 +302,11 @@ timer is no longer pending is ignored.
 ordered effects with stable IDs such as `0:0` and `1:0`, and event waits with
 IDs such as `event:0`. Memoize or deduplicate each operation using that ID:
 replaying the same events from the beginning reconstructs the same snapshots,
-effects, waits and IDs — not just the same resulting snapshot, but the same
-effects in the same order, which is what hosts that match journal entries
+effects, waits and IDs. This means the same effects in the same order, not
+only the same resulting snapshot, which is what hosts that match journal entries
 positionally (Temporal, Restate) depend on. Each `DurableEffect` also carries a serializable
-`descriptor` — actor references replaced by `{ $actor: address, incarnation? }` and actor sources by
-source keys — for journaling; payload fields such as `event` and `input` pass
+`descriptor` for journaling, with actor references replaced by `{ '@actor': address, incarnation? }` and actor sources by
+source keys; payload fields such as `event` and `input` pass
 through by reference and are only as serializable as their values.
 
 Every inter-actor edge is an asynchronous handoff to the runtime.
@@ -305,9 +330,9 @@ pairwise sender-to-receiver ordering: for a given pair of actors, events sent
 from the first to the second are enqueued in send order, and an undeliverable
 event is dead-lettered rather than retried. This matches the Erlang and Akka
 defaults. A dead letter is reported through the `deadLetter` runtime
-operation (and the `onRejectedEvent` hook) — observability, not
+operation (and the `onRejectedEvent` hook). This is for observability, not
 retry. Ordering is not transitive
-across intermediaries. The durable path is stronger — the handoff queue serializes
+across intermediaries. The durable path is stronger: the handoff queue serializes
 every operation of an execution globally. A host `sendEvent` that routes
 remotely is responsible for preserving pairwise ordering on its transport.
 
@@ -320,11 +345,11 @@ children. Incarnations of local children do not survive persist and restore
 unless `executionId` is pinned.
 
 Because every handoff queues, a runtime operation must never await another
-runtime operation of the same execution through the actor system — it would
+runtime operation of the same execution through the actor system, because it would
 wait behind itself. The `deliverEvent`, `stopActor` and `terminateActor`
 helpers exported from `xstate` expose the local behaviors and are always safe
 to call directly. An implemented runtime operation replaces the local
-behavior entirely, including its bookkeeping — a `stopActor` that only journals
+behavior entirely, including its bookkeeping. A `stopActor` that only journals
 must call the `stopActor` helper for the local stop cascade, and a `sendEvent`
 that routes locally must call `deliverEvent`. When a remote runtime can
 deliver the same completion more than once (retries, replays), the host is
@@ -332,7 +357,7 @@ responsible for deduplicating before handing it to the execution.
 
 By default, events addressed to the root actor do not reach `sendEvent` during
 `executeEffects`: the execution captures and retains them, and
-`waitForEvent()` hands them out — in capture order — before deferring to the
+`waitForEvent()` hands them out in capture order before deferring to the
 adapter. While the loop is parked in the adapter's wait, a root-addressed
 event reaches `enqueueRootEvent`, or `sendEvent` when the adapter implements
 the broader routing override, and belongs in the host's mailbox. Producing one
@@ -360,7 +385,7 @@ Change the state of other actors only at the top of the drive loop.
 
 ### Journaling rules
 
-A journaled step's closure must contain only the external side effect —
+A journaled step's closure must contain only the external side effect:
 nothing that re-enters the engine's journal, and nothing that mutates local
 actors.
 
@@ -373,8 +398,8 @@ actors.
   the runtime operations make.
 - **Local actor mutations stay outside the journal.** A journaled closure is
   skipped on replay: calling `deliverEvent`, `stopActor`, or starting an
-  actor inside one rebuilds a different actor tree than the recorded run —
-  silently, with no error. Re-run local mutations unjournaled on every
+  actor inside one rebuilds a different actor tree than the recorded run,
+  silently and with no error. Re-run local mutations unjournaled on every
   replay; journal only work that must not run twice.
 
 A per-effect `runtime(metadata, effect)` factory is available for hosts that
@@ -396,7 +421,7 @@ I/O:
 different effect sequence on replay, and nothing detects the divergence.
 Perform such work inside journaled operations (the host's `executeAction`,
 where the recorded result replays), or derive values deterministically from
-what the snapshot already carries — addresses and effect IDs are stable
+what the snapshot already carries. Addresses and effect IDs are stable
 across replays and make good seeds and idempotency keys.
 
 ```ts
@@ -416,27 +441,26 @@ entry: ({ context }, enq) => {
 `getPersistedSnapshot(snapshot)` embeds each child's persisted state: the
 whole-tree checkpoint of a runtime that co-locates the tree.
 `getPersistedSnapshot(snapshot, { embedChildren: false })` instead references
-children by logical address, leaving each child's state — including its own
-subtree — with the runtime that owns it; the option applies to the whole
+children by logical address, leaving each child's state (including its own
+subtree) with the runtime that owns it; the option applies to the whole
 tree, not per placement boundary. Restoring an address-only child produces a
 location-transparent handle: sends route through the system runtime, its
 snapshot exposes lifecycle only (a full snapshot is the last value an actor
 published, which only co-located actors observe), `subscribe` and `on` are
 inert (observation is co-location), and completion staleness for it is the
 owning runtime's responsibility. Persisting a handle from the referencing
-side throws — its state lives with the runtime that owns it. A restored handle keeps its
-persisted address verbatim — the owning runtime's identity for the child.
+side throws, because its state lives with the runtime that owns it. A restored handle keeps its
+persisted address verbatim as the owning runtime's identity for the child.
 
 `durable.getActorRef(snapshot)` returns the root actor reference behind a
 snapshot this execution produced, for addressing and inspection.
 `durable.getActorRef(snapshot, address)` resolves a logical address against
-the snapshot's live actor tree instead — the tool for hosts whose mailbox
-stores addresses as strings and must deliver to the actor behind one —
-returning `undefined` when no live actor has that address (a timer firing
+the snapshot's live actor tree instead. Use it in hosts whose mailbox
+stores addresses as strings and must deliver to the actor behind one. It returns `undefined` when no live actor has that address (a timer firing
 for an actor that already completed).
 
 `createDurable(logic, adapter, { inspect })` observes the execution's
-inspection events — the `@xstate.actor` / `@xstate.transition` protocol,
+inspection events (the `@xstate.actor` / `@xstate.transition` protocol)
 across the whole live actor tree, including transitions computed by the pure
 path. This is host observability, not part of the durable contract: use it
 for operation logs, tracing and test instrumentation, and keep the adapter
@@ -447,7 +471,7 @@ itself pure physics.
 When the machine declares a runtime validator, an external event whose payload
 fails its schema is rejected at the boundary: `transition()` returns the
 snapshot unchanged together with a `@xstate.deadLetter` effect, and never
-throws. Replay stays total — replaying a poisoned queued event produces the
+throws. Replay stays total: replaying a poisoned queued event produces the
 same unchanged snapshot and the same rejection effect every time.
 
 The effect executes through the `deadLetter` runtime operation, so a host
@@ -491,8 +515,8 @@ the effects and the runtime installation. `createActor` is the built-in
 in-process runtime over the same pure relations; `createDurable` is the
 journaled one.
 
-Effects are plain objects — each has a serializable `descriptor` and an
-`exec(runtime)` method — so a host may take `[snapshot, effects]` from the
+Effects are plain objects. Each has a serializable `descriptor` and an
+`exec(runtime)` method, so a host may take `[snapshot, effects]` from the
 pure APIs and execute them entirely its own way. Dropping `executeEffects`
 means providing its four services yourself: transitive settlement (an
 effect's operations trigger further operations; "executed" must mean the

package/docs/errors.md

@@ -551,7 +551,7 @@ Unable to send event to actor '{address}' (incarnation '{incarnation}'): no live
 
 Values: the address, and the incarnation when the reference has one.
 
-A serialized actor reference (`{ $actor }`) points to an actor that is not running in this system, or to an earlier incarnation of it. Check that the actor is running, or refresh the stored reference.
+A serialized actor reference (`{ '@actor' }`) points to an actor that is not running in this system, or to an earlier incarnation of it. Check that the actor is running, or refresh the stored reference.
 
 ## E51
 
@@ -616,7 +616,7 @@ Values: the address.
 ## E57
 
 ```text
-State key "{key}" contains "." — nest the states or escape it as "{escapedKey}".
+State key "{key}" contains ".". Nest the states or escape it as "{escapedKey}".
 ```
 
 Values: the state key.

package/docs/examples.md

@@ -9,61 +9,61 @@ These examples use XState v6 syntax: transition functions that return `{ target,
 
 ## Start here
 
-- [counter](https://github.com/statelyai/xstate/tree/next/examples/counter) — the smallest useful machine: `increment` and `decrement` transitions updating one context value, wired to plain DOM.
-- [toggle](https://github.com/statelyai/xstate/tree/next/examples/toggle) — two states and one event, with no context at all.
-- [fetch](https://github.com/statelyai/xstate/tree/next/examples/fetch) — `idle` / `loading` / `success` / `failure` around `createAsyncLogic(...)` invoked by the `loading` state.
+- [counter](https://github.com/statelyai/xstate/tree/next/examples/counter): the smallest useful machine: `increment` and `decrement` transitions updating one context value, wired to plain DOM.
+- [toggle](https://github.com/statelyai/xstate/tree/next/examples/toggle): two states and one event, with no context at all.
+- [fetch](https://github.com/statelyai/xstate/tree/next/examples/fetch): `idle` / `loading` / `success` / `failure` around `createAsyncLogic(...)` invoked by the `loading` state.
 
 ## UI patterns
 
-- [stopwatch](https://github.com/statelyai/xstate/tree/next/examples/stopwatch) — `createCallbackLogic(...)` invoked by the `running` state sends a tick every 10ms; leaving the state clears the interval.
-- [timer](https://github.com/statelyai/xstate/tree/next/examples/timer) — the same ticking pattern, plus events that adjust the duration while the timer is stopped.
-- [tiles](https://github.com/statelyai/xstate/tree/next/examples/tiles) — a sliding tile puzzle with named guards deciding whether two tiles are adjacent.
-- [snake-react](https://github.com/statelyai/xstate/tree/next/examples/snake-react) — a game loop as an invoked callback actor, with the whole board in context.
-- [tic-tac-toe-react](https://github.com/statelyai/xstate/tree/next/examples/tic-tac-toe-react) — turn taking and win detection in a `playing` state, with a `RESET` transition on the machine root.
-- [todomvc-react](https://github.com/statelyai/xstate/tree/next/examples/todomvc-react) — the TodoMVC spec, with the todo list and the active filter held in context.
-- [friends-list-react](https://github.com/statelyai/xstate/tree/next/examples/friends-list-react) — a parent machine that spawns one child actor per friend and keeps their refs in context.
-- [trivia-game-example](https://github.com/statelyai/xstate/tree/next/examples/trivia-game-example) — a quiz whose navigation actions are supplied with `machine.provide(...)` so the machine stays free of router imports.
+- [stopwatch](https://github.com/statelyai/xstate/tree/next/examples/stopwatch): `createCallbackLogic(...)` invoked by the `running` state sends a tick every 10ms; leaving the state clears the interval.
+- [timer](https://github.com/statelyai/xstate/tree/next/examples/timer): the same ticking pattern, plus events that adjust the duration while the timer is stopped.
+- [tiles](https://github.com/statelyai/xstate/tree/next/examples/tiles): a sliding tile puzzle with named guards deciding whether two tiles are adjacent.
+- [snake-react](https://github.com/statelyai/xstate/tree/next/examples/snake-react): a game loop as an invoked callback actor, with the whole board in context.
+- [tic-tac-toe-react](https://github.com/statelyai/xstate/tree/next/examples/tic-tac-toe-react): turn taking and win detection in a `playing` state, with a `RESET` transition on the machine root.
+- [todomvc-react](https://github.com/statelyai/xstate/tree/next/examples/todomvc-react): the TodoMVC spec, with the todo list and the active filter held in context.
+- [friends-list-react](https://github.com/statelyai/xstate/tree/next/examples/friends-list-react): a parent machine that spawns one child actor per friend and keeps their refs in context.
+- [trivia-game-example](https://github.com/statelyai/xstate/tree/next/examples/trivia-game-example): a quiz whose navigation actions are supplied with `machine.provide(...)` so the machine stays free of router imports.
 
 ## 7GUIs
 
 Ports of the [7GUIs](https://eugenkiss.github.io/7guis/) benchmark tasks, in React and Vue:
 
-- [7guis-counter-react](https://github.com/statelyai/xstate/tree/next/examples/7guis-counter-react) and [7guis-1-counter-vue](https://github.com/statelyai/xstate/tree/next/examples/7guis-1-counter-vue) — the counter task.
-- [7guis-temperature-react](https://github.com/statelyai/xstate/tree/next/examples/7guis-temperature-react) and [7guis-2-temperature-vue](https://github.com/statelyai/xstate/tree/next/examples/7guis-2-temperature-vue) — two fields that convert into each other without looping.
-- [7guis-flight-booker-react](https://github.com/statelyai/xstate/tree/next/examples/7guis-flight-booker-react) — trip type, date validation and a booking request as invoked async logic.
+- [7guis-counter-react](https://github.com/statelyai/xstate/tree/next/examples/7guis-counter-react) and [7guis-1-counter-vue](https://github.com/statelyai/xstate/tree/next/examples/7guis-1-counter-vue): the counter task.
+- [7guis-temperature-react](https://github.com/statelyai/xstate/tree/next/examples/7guis-temperature-react) and [7guis-2-temperature-vue](https://github.com/statelyai/xstate/tree/next/examples/7guis-2-temperature-vue): two fields that convert into each other without looping.
+- [7guis-flight-booker-react](https://github.com/statelyai/xstate/tree/next/examples/7guis-flight-booker-react): trip type, date validation and a booking request as invoked async logic.
 
 ## XState Store
 
 [XState Store](choose-xstate.md) examples, for state that needs events but not states:
 
-- [store-counter-react](https://github.com/statelyai/xstate/tree/next/examples/store-counter-react) — a module-level store read with `useSelector`.
-- [local-store-counter-react](https://github.com/statelyai/xstate/tree/next/examples/local-store-counter-react) — the same store created per component with `useStore`.
-- [store-tic-tac-toe](https://github.com/statelyai/xstate/tree/next/examples/store-tic-tac-toe) — a full game in one store, including derived win and draw outcomes.
+- [store-counter-react](https://github.com/statelyai/xstate/tree/next/examples/store-counter-react): a module-level store read with `useSelector`.
+- [local-store-counter-react](https://github.com/statelyai/xstate/tree/next/examples/local-store-counter-react): the same store created per component with `useStore`.
+- [store-tic-tac-toe](https://github.com/statelyai/xstate/tree/next/examples/store-tic-tac-toe): a full game in one store, including derived win and draw outcomes.
 
 ## Backends and persistence
 
-- [express-workflow](https://github.com/statelyai/xstate/tree/next/examples/express-workflow) — an Express API that starts a workflow, restores it from a persisted snapshot on each request, sends the event and persists the result. The pattern behind [backend workflows](backend-workflows.md).
-- [persisted-donut-maker](https://github.com/statelyai/xstate/tree/next/examples/persisted-donut-maker) — a multi-step recipe machine whose snapshot is written to disk and restored on the next run.
-- [mongodb-persisted-state](https://github.com/statelyai/xstate/tree/next/examples/mongodb-persisted-state) — the same machine with MongoDB as the snapshot store, plus a queue that serializes writes.
-- [mongodb-credit-check-api](https://github.com/statelyai/xstate/tree/next/examples/mongodb-credit-check-api) — a credit check API where each external service is `createAsyncLogic(...)` with a Zod input schema.
+- [express-workflow](https://github.com/statelyai/xstate/tree/next/examples/express-workflow): an Express API that starts a workflow, restores it from a persisted snapshot on each request, sends the event and persists the result. The pattern behind [backend workflows](backend-workflows.md).
+- [persisted-donut-maker](https://github.com/statelyai/xstate/tree/next/examples/persisted-donut-maker): a multi-step recipe machine whose snapshot is written to disk and restored on the next run.
+- [mongodb-persisted-state](https://github.com/statelyai/xstate/tree/next/examples/mongodb-persisted-state): the same machine with MongoDB as the snapshot store, plus a queue that serializes writes.
+- [mongodb-credit-check-api](https://github.com/statelyai/xstate/tree/next/examples/mongodb-credit-check-api): a credit check API where each external service is `createAsyncLogic(...)` with a Zod input schema.
 
 ## Serverless Workflow ports
 
 Ports of the [Serverless Workflow specification](https://github.com/serverlessworkflow/specification/tree/main/examples) examples, each a single runnable `main.ts`. They are the densest collection of workflow shapes in the repository. Use them to see how a particular orchestration pattern looks as a statechart.
 
-- [workflow-hello](https://github.com/statelyai/xstate/tree/next/examples/workflow-hello) — the minimum: one final state with `output`.
-- [workflow-async-function](https://github.com/statelyai/xstate/tree/next/examples/workflow-async-function) — one invoked async function with typed input taken from the workflow's own input.
-- [workflow-parallel](https://github.com/statelyai/xstate/tree/next/examples/workflow-parallel) — two branches running at once, joining when both are done.
-- [workflow-event-based](https://github.com/statelyai/xstate/tree/next/examples/workflow-event-based) — waiting for one of several events, with a named delay as the deadline.
-- [workflow-check-inbox](https://github.com/statelyai/xstate/tree/next/examples/workflow-check-inbox) — a root-level callback actor that sends a `reminder` event on an interval, driving a check-then-notify cycle back to `Idle`.
-- [workflow-credit-check](https://github.com/statelyai/xstate/tree/next/examples/workflow-credit-check) and [workflow-applicant-request](https://github.com/statelyai/xstate/tree/next/examples/workflow-applicant-request) — decision workflows that branch on the result of an invoked service.
-- [workflow-book-lending](https://github.com/statelyai/xstate/tree/next/examples/workflow-book-lending) — a long-running flow that waits on human events between service calls, with a delayed transition for the wait and a nested checkout region.
-- [workflow-provision-orders](https://github.com/statelyai/xstate/tree/next/examples/workflow-provision-orders) — order provisioning with a nested `Exception` state whose children handle each kind of missing field.
-- [workflow-purchase-order-deadline](https://github.com/statelyai/xstate/tree/next/examples/workflow-purchase-order-deadline) — a deadline on the whole order, with retries handled by an external retry policy library.
-- [workflow-car-vitals](https://github.com/statelyai/xstate/tree/next/examples/workflow-car-vitals) — several checks invoked together while the car is on, re-run on a delayed transition.
-- [workflow-accumulate-room-readings](https://github.com/statelyai/xstate/tree/next/examples/workflow-accumulate-room-readings) — readings collected into context until a delayed transition ends the window and reports them.
-- [workflow-monitor-patient](https://github.com/statelyai/xstate/tree/next/examples/workflow-monitor-patient) — a single monitoring state whose event handlers react to each kind of vital sign alert.
-- [workflow-media-scanner](https://github.com/statelyai/xstate/tree/next/examples/workflow-media-scanner) — a file scanning pipeline split across modules.
+- [workflow-hello](https://github.com/statelyai/xstate/tree/next/examples/workflow-hello): the minimum: one final state with `output`.
+- [workflow-async-function](https://github.com/statelyai/xstate/tree/next/examples/workflow-async-function): one invoked async function with typed input taken from the workflow's own input.
+- [workflow-parallel](https://github.com/statelyai/xstate/tree/next/examples/workflow-parallel): two branches running at once, joining when both are done.
+- [workflow-event-based](https://github.com/statelyai/xstate/tree/next/examples/workflow-event-based): waiting for one of several events, with a named delay as the deadline.
+- [workflow-check-inbox](https://github.com/statelyai/xstate/tree/next/examples/workflow-check-inbox): a root-level callback actor that sends a `reminder` event on an interval, driving a check-then-notify cycle back to `Idle`.
+- [workflow-credit-check](https://github.com/statelyai/xstate/tree/next/examples/workflow-credit-check) and [workflow-applicant-request](https://github.com/statelyai/xstate/tree/next/examples/workflow-applicant-request): decision workflows that branch on the result of an invoked service.
+- [workflow-book-lending](https://github.com/statelyai/xstate/tree/next/examples/workflow-book-lending): a long-running flow that waits on human events between service calls, with a delayed transition for the wait and a nested checkout region.
+- [workflow-provision-orders](https://github.com/statelyai/xstate/tree/next/examples/workflow-provision-orders): order provisioning with a nested `Exception` state whose children handle each kind of missing field.
+- [workflow-purchase-order-deadline](https://github.com/statelyai/xstate/tree/next/examples/workflow-purchase-order-deadline): a deadline on the whole order, with retries handled by an external retry policy library.
+- [workflow-car-vitals](https://github.com/statelyai/xstate/tree/next/examples/workflow-car-vitals): several checks invoked together while the car is on, re-run on a delayed transition.
+- [workflow-accumulate-room-readings](https://github.com/statelyai/xstate/tree/next/examples/workflow-accumulate-room-readings): readings collected into context until a delayed transition ends the window and reports them.
+- [workflow-monitor-patient](https://github.com/statelyai/xstate/tree/next/examples/workflow-monitor-patient): a single monitoring state whose event handlers react to each kind of vital sign alert.
+- [workflow-media-scanner](https://github.com/statelyai/xstate/tree/next/examples/workflow-media-scanner): a file scanning pipeline split across modules.
 
 The remaining `workflow-*` directories cover the rest of the specification's examples: [workflow-async-subflow](https://github.com/statelyai/xstate/tree/next/examples/workflow-async-subflow), [workflow-car-auction-bids](https://github.com/statelyai/xstate/tree/next/examples/workflow-car-auction-bids), [workflow-event-based-service](https://github.com/statelyai/xstate/tree/next/examples/workflow-event-based-service), [workflow-event-greeting](https://github.com/statelyai/xstate/tree/next/examples/workflow-event-greeting), [workflow-filling-water](https://github.com/statelyai/xstate/tree/next/examples/workflow-filling-water), [workflow-finalize-college-app](https://github.com/statelyai/xstate/tree/next/examples/workflow-finalize-college-app), [workflow-greeting](https://github.com/statelyai/xstate/tree/next/examples/workflow-greeting), [workflow-math-problem](https://github.com/statelyai/xstate/tree/next/examples/workflow-math-problem), [workflow-monitor-job](https://github.com/statelyai/xstate/tree/next/examples/workflow-monitor-job), [workflow-new-patient-onboarding](https://github.com/statelyai/xstate/tree/next/examples/workflow-new-patient-onboarding), [workflow-reusing-functions](https://github.com/statelyai/xstate/tree/next/examples/workflow-reusing-functions) and [workflow-send-cloudevent](https://github.com/statelyai/xstate/tree/next/examples/workflow-send-cloudevent).
 

package/docs/fsm.md

@@ -153,7 +153,8 @@ from `xstate` adds the runtime to your bundle.
 - A transition can be a state name, `{ target, context }`, or a function that
   receives `{ context, event }` and returns `{ target, context }`. Return
   `undefined` from a function for no transition.
-- Context updates are shallow patches.
+- Only own entries in `states` and `on` define transitions. A state inherited from the `states` prototype has no outgoing transitions, like an undeclared state. Transition targets are not validated.
+- Context updates are shallow patches. A patch adds its own enumerable string and symbol keys even when a new value is `undefined` or matches an inherited value. If the target is unchanged, a patch whose keys already exist with `Object.is`-equal values keeps the current snapshot.
 - `types<T>()` adds types without runtime validation. Setup schema values are
   ignored by the FSM runtime; state `schemas.input` is accepted for upgrade
   compatibility but no input is consumed by this pure API.

package/docs/guards.md

@@ -38,7 +38,7 @@ Do not fetch data in a guard. Invoke an actor, store the result in context, then
 
 ## Named guards
 
-Define reusable guards on `setup(...)` or the machine's `guards`. A named guard is a plain predicate function: it receives only the arguments you pass it and knows nothing about the machine. The caller decides what the guard sees — pass values from `context` or the event explicitly.
+Define reusable guards on `setup(...)` or the machine's `guards`. A named guard is a plain predicate function: it receives only the arguments you pass it and knows nothing about the machine. The caller decides what the guard sees: pass values from `context` or the event explicitly.
 
 ```ts
 const orderMachine = createMachine({

package/docs/index.md

@@ -1,4 +1,4 @@
-# XState 6.0.0-beta.1
+# XState 6.0.0-beta.2
 
 These docs match the installed xstate package. Start with the [quick start](quick-start.md) or the [agent guide](agents.md).
 For differences from v5, read the [migration guide](xstate-v5-to-v6.md).

package/docs/invoke.md

@@ -112,7 +112,7 @@ const machine = s.createMachine({
 
 Keep the helper call inline: its enclosing state supplies narrowed context, ancestor context, state input and transition targets. In this example, `context.userId` is `string` and `event.output` is `{ name: string }`.
 
-For an async `src`, `schemas.input` types the actor input, `schemas.output` checks the function's resolved value and types `onDone.event.output`, and `schemas.error` types `onError.event.error`. Omit the output schema to infer output from the async return value. The function receives `{ input, signal, self, system }` and the async enqueue object, including `emit` and `step`, just like `createAsyncLogic`. Its input comes from the invoke's static value or input mapper; parent context stays in the mapper and transition handlers.
+For an async `src`, `schemas.input` types the actor input, `schemas.output` checks the function's resolved value and types `onDone.event.output`, and `schemas.error` types `onError.event.error`. Omit the output schema to infer output from the async return value. The function receives `{ input, signal, self, system }` and the async enqueue object, including `emit` and `step`, as `createAsyncLogic` does. Its input comes from the invoke's static value or input mapper; parent context stays in the mapper and transition handlers.
 
 You can also pass an existing actor logic value, including machine and callback logic:
 
@@ -124,6 +124,14 @@ invoke: s.createInvoke({
 })
 ```
 
+A bare inline invoke such as `{ src: loadUserLogic, onDone }` cannot correlate
+that specific logic with its completion output. With no registered actor
+sources, its `onDone.event.output` is `unknown`, so TypeScript requires
+narrowing before it can be used. For a typed output, use
+`s.createInvoke({ src: loadUserLogic, onDone })` as above, or register the logic
+in `setup({ actors: { loadUserLogic } })` and invoke it with
+`src: 'loadUserLogic'`. Prefer one of these typed forms when generating code.
+
 For a logic value, its own schemas determine input, output, error and snapshot types. Declare schemas on that logic rather than repeating them on the invoke.
 
 The helper requires `input` when the source's input type excludes `undefined`. Pass a static value or a mapper returning that input type. Logic that accepts `undefined` can omit `input`.
@@ -306,7 +314,31 @@ Invoke also is not the right tool when the child must outlive the state, or when
 
 Provide named actor logic through `setup({ actors })` or `createMachine({ actors })`. XState correlates `src` with `input`, so a static or mapped input is checked against that logic's input type, and `onDone` sees the output type of that logic.
 
-Declare child ids with `schemas.children` to type `children` and to check that each `id` receives compatible logic:
+For a literal invoke `id` and a named or inline actor source, XState infers the
+child reference in `snapshot.children`. The child may be absent when the invoke
+state is inactive, so check for `undefined` before sending an event:
+
+```ts
+import { createActor, setup, types } from 'xstate';
+
+const paymentMachine = setup({
+  schemas: { events: { retry: types<{}>() } }
+}).createMachine({ initial: 'idle', states: { idle: {} } });
+
+const parent = setup({ actors: { paymentMachine } }).createMachine({
+  invoke: { id: 'payment', src: 'paymentMachine' }
+});
+
+const payment = createActor(parent).getSnapshot().children.payment;
+payment?.send({ type: 'retry' });
+```
+
+Declare child ids with `schemas.children` when the child contract must also be
+available inside machine callbacks. This also checks that each declared `id`
+receives compatible logic. For dynamic IDs, keep the returned child reference
+from `enq.spawn(...)` in context instead of indexing `snapshot.children` with
+an arbitrary string. Spawned children have a separately managed lifetime; see
+[Spawn](spawn.md):
 
 ```ts
 setup({}).createMachine({

package/docs/persistence.md

@@ -25,6 +25,12 @@ const restored = restoreActor(
 ).start();
 ```
 
+In Vue, keep a machine passed to `restoreActor` out of deep reactive state.
+Store it in `shallowRef(machine)` or create it with `markRaw(machine)`. XState
+also accepts a reactive Proxy around a machine, but a raw machine avoids
+wrapping its state nodes and is the recommended way to hold actor logic in Vue.
+See [Vue input and restored snapshots](https://stately.ai/docs/xstate/v6/vue/input-and-snapshots).
+
 Pass `system` (a `createSystem()` result) to restore the actor into that system.
 
 A restored snapshot is opaque: restoring runs no transitions and re-executes no actions. `always` transitions and choice states in the restored configuration are not re-evaluated until the next event, even if their guards would now pass. Development builds warn when the restored state has eventless transitions.
@@ -47,11 +53,11 @@ By default a persisted snapshot embeds each child's persisted state, producing a
 const persisted = actor.getPersistedSnapshot({ embedChildren: false });
 ```
 
-The option applies to the whole tree, not to a single placement boundary. Persisting by address requires each child to have a registered source key (a string `src`); `spawn(actors.worker)`, `enq.spawn(actors.worker)` and `enq.spawn('worker')` retain that key, while inline actor logic cannot be referenced by address. The string form makes the exact identity explicit when aliases share logic. Restoring an address-only child produces a location-transparent handle: sends to it route through the [system runtime](durable-execution.md), and its snapshot exposes lifecycle only, since a full snapshot is the last value an actor published and only co-located actors observe it. Install the system runtime before sending to a restored handle — without one, there is no route to the actor it references.
+The option applies to the whole tree, not to a single placement boundary. Persisting by address requires each child to have a registered source key (a string `src`); `spawn(actors.worker)`, `enq.spawn(actors.worker)` and `enq.spawn('worker')` retain that key, while inline actor logic cannot be referenced by address. The string form makes the exact identity explicit when aliases share logic. Restoring an address-only child produces a location-transparent handle: sends to it route through the [system runtime](durable-execution.md), and its snapshot exposes lifecycle only, since a full snapshot is the last value an actor published and only co-located actors observe it. Install the system runtime before sending to a restored handle. Without one, there is no route to the actor it references.
 
 Persisted children changed shape in v6: each entry carries an `address` field and either an embedded `snapshot` or a `remote: true` marker. A remote entry may also carry an opaque `incarnation` token, round-tripped verbatim: XState never stamps one, but a host that does gets stale-completion protection on the referencing side and the token on journaled `sendTo` descriptors. Snapshots persisted by v5 or by v6 alphas use other shapes and are not read on restore; discard them or convert them before restoring. See the [migration guide](xstate-v5-to-v6.md#29-names-changed-during-the-v6-prereleases).
 
-A timer persisted from a running actor carries its wall-clock start (`scheduledAt`), and restoring the snapshot schedules the remaining time toward the original deadline — a timer past due fires immediately. Snapshots produced only by pure transitions carry no timestamp, so restoring one restarts each timer with its declared delay. A [durable execution](durable-execution.md) records timer starts when scheduling effects succeed; await `executeEffects()` before persisting its checkpoint to preserve deadlines. A custom adapter clock must use the same time origin when restoring.
+A timer persisted from a running actor carries its wall-clock start (`scheduledAt`), and restoring the snapshot schedules the remaining time toward the original deadline. A timer past due fires immediately. Snapshots produced only by pure transitions carry no timestamp, so restoring one restarts each timer with its declared delay. A [durable execution](durable-execution.md) records timer starts when scheduling effects succeed; await `executeEffects()` before persisting its checkpoint to preserve deadlines. A custom adapter clock must use the same time origin when restoring.
 
 For a host-driven durable loop, use `execution.restore(persistedSnapshot)` from
 `xstate/durable`, then `execution.executeEffects(effects)` to resume embedded
@@ -59,13 +65,13 @@ children and pending timers. Persist `execution.nextTransitionIndex` with the
 checkpoint and pass it to the next execution's adapter. See
 [durable checkpoint restoration](durable-execution.md).
 
-An actor's address is the `/`-joined path of actor ids from the root, such as `order/worker:0`. It is stable across persistence and restore, unlike `sessionId`, which identifies one incarnation. Generated child ids are recorded in each snapshot's `_nextActorIds`, so restored actors keep numbering where they left off.
+An actor's address is the `/`-joined path of actor ids from the root, such as `order/worker:0`. It is stable across persistence and restore, unlike `sessionId`, which identifies one incarnation. Generated child ids are recorded in each snapshot's `nextActorIds`, so restored actors keep numbering where they left off.
 
 ## Compatibility
 
 A persisted snapshot is a plain JSON-shaped object. Restoring one is lenient: XState reads the fields it knows and does not check a format marker.
 
-These envelope fields are stable across 6.x releases: `status`, `value`, `context`, `output`, `error`, `historyValue`, `stateInputs`, `children`, `timers` and `machine`. The [persisted snapshot JSON Schema](https://github.com/statelyai/xstate/blob/next/packages/core/src/persistedSnapshot.schema.json) (draft 2020-12) describes them. Nested machine children carry their own envelope in `children[id].snapshot`. A child entry's `src` is the registered source key the child restores from. A child invoked with inline logic has no `src`; it restores through the invoke definition with its id among the restored active states, and restoring fails when no active state, or more than one, invokes that id. Fields prefixed with `_`, such as `_nextActorIds`, are private. They round-trip verbatim; do not read or write them.
+These envelope fields are stable across 6.x releases: `status`, `value`, `context`, `output`, `error`, `historyValue`, `stateInputs`, `children`, `timers` and `machine`. The [persisted snapshot JSON Schema](https://github.com/statelyai/xstate/blob/next/packages/core/src/persistedSnapshot.schema.json) (draft 2020-12) describes them. Nested machine children carry their own envelope in `children[id].snapshot`. A child entry's `src` is the registered source key the child restores from. A child invoked with inline logic has no `src`; it restores through the invoke definition with its id among the restored active states, and restoring fails when no active state, or more than one, invokes that id. `nextTimerId` and `nextActorIds` are private. They round-trip verbatim; do not read or write them. No field name in the envelope starts with `$` or `_`, so it can be stored in document databases such as Convex and MongoDB that reserve those prefixes.
 
 `timers` is a list of pending timers in scheduling order. A delayed `enq.raise(...)` or `enq.sendTo(...)` entry carries its `id`, or a `seq` number when scheduled without one. Built-in `after` and `timeout` timers have neither; their `event` (`xstate.after`, `xstate.timeout.state` or `xstate.timeout.actor`) identifies them.
 
@@ -95,15 +101,15 @@ In development builds, `getPersistedSnapshot()` warns once per call with the pat
 
 `Date` values are not reported. `JSON.stringify` writes them as ISO strings, and `JSON.parse` does not turn them back into `Date` objects. Convert them on restore if your context needs `Date` instances.
 
-Actor refs in `context` persist as `{ $actor: address }` and are not reported. A ref that names one of the snapshot's children restores to that child.
+Actor refs in `context` persist as `{ '@actor': address }` and are not reported. A ref that names one of the snapshot's children restores to that child.
 
-`$actor` is a reserved key in persisted context. On restore, any object in `context` whose keys are exactly `$actor` (and optionally `incarnation`) is read as a serialized actor ref: without an `incarnation`, it becomes the live child at that address, if there is one. Objects with other keys alongside `$actor` stay plain data. Do not store application data as an object with only an `$actor` key.
+`@actor` is a reserved key in persisted context. On restore, any object in `context` whose keys are exactly `@actor` (and optionally `incarnation`) is read as a serialized actor ref: without an `incarnation`, it becomes the live child at that address, if there is one. Objects with other keys alongside `@actor` stay plain data. Do not store application data as an object with only an `@actor` key.
 
 ### Serialized actor refs
 
-An actor ref serializes with `JSON.stringify` as `{ $actor: address }` (the `SerializedActorRef` type, which also allows an optional string `incarnation`). This shape appears when a ref travels in an event payload, such as a `replyTo` field, and the event is persisted or crosses a process boundary. A serialized ref in `context` keeps its address across persistence and restore.
+An actor ref serializes with `JSON.stringify` as `{ '@actor': address }` (the `SerializedActorRef` type, which also allows an optional string `incarnation`). This shape appears when a ref travels in an event payload, such as a `replyTo` field, and the event is persisted or crosses a process boundary. A serialized ref in `context` keeps its address across persistence and restore.
 
-A serialized ref is a valid `enq.sendTo(...)` target. The event is delivered to the live actor at the ref's `$actor` address, including an actor restored after the ref was serialized. If no live actor has that address, the event becomes a dead letter with reason `'missingTarget'`.
+A serialized ref is a valid `enq.sendTo(...)` target. The event is delivered to the live actor at the ref's `@actor` address, including an actor restored after the ref was serialized. If no live actor has that address, the event becomes a dead letter with reason `'missingTarget'`.
 
 ```ts
 const server = createMachine({
@@ -154,8 +160,8 @@ const checkoutVersions = machineVersions([
       children: z.object({}),
       historyValue: z.object({}),
       timers: z.tuple([]),
-      _nextActorIds: z.record(z.string(), z.number()).optional(),
-      _nextTimerId: z.number(),
+      nextActorIds: z.record(z.string(), z.number()).optional(),
+      nextTimerId: z.number(),
       stateInputs: z.undefined().optional(),
       machine: z.object({
         id: z.literal('checkout'),