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

package/dist/{createActor-25900f76.cjs.js → createActor-c91c9ffe.cjs.js}

@@ -166,11 +166,11 @@ function isRemoteActorRef(actorRef) {
  * JSON (`actor.toJSON()`): plain data carrying an address, not an actor.
  */
 function isSerializedActorRef(target) {
-  if (typeof target !== 'object' || target === null || Array.isArray(target) || typeof target.$actor !== 'string') {
+  if (typeof target !== 'object' || target === null || Array.isArray(target) || typeof target['@actor'] !== 'string') {
     return false;
   }
   for (const key in target) {
-    if (key !== '$actor' && key !== 'incarnation') {
+    if (key !== '@actor' && key !== 'incarnation') {
       return false;
     }
   }
@@ -186,7 +186,7 @@ function getAddressId(address) {
 
 /** @internal The error reported when no live actor has a serialized address. */
 function createMissingAddressError(target) {
-  return new Error(xstateError(50, ...(target.incarnation === undefined ? [target.$actor] : [target.$actor, target.incarnation])) );
+  return new Error(xstateError(50, ...(target.incarnation === undefined ? [target['@actor']] : [target['@actor'], target.incarnation])) );
 }
 
 /**
@@ -195,7 +195,7 @@ function createMissingAddressError(target) {
  * without one follows whichever actor is live at the address.
  */
 function resolveSerializedActorRef(system, target) {
-  const live = system._getByAddress?.(target.$actor);
+  const live = system._getByAddress?.(target['@actor']);
   return live && (target.incarnation === undefined || live.sessionId === target.incarnation) ? live : undefined;
 }
 
@@ -248,7 +248,7 @@ function createInertActorRef(options) {
         throw new Error(xstateError(51, id));
       }
       return {
-        $actor: address
+        '@actor': address
       };
     }
   };
@@ -334,7 +334,7 @@ function createRemoteActorRef(system, options) {
     // one actor-reference shape whether a child is co-located or remote.
     toJSON() {
       return {
-        $actor: options.address
+        '@actor': options.address
       };
     }
   };
@@ -454,7 +454,7 @@ function deliverEvent(source, target, event) {
         throw error;
       }
       void system.deadLetter(source, undefined, event, 'missingTarget', {
-        targetId: getAddressId(serialized.$actor),
+        targetId: getAddressId(serialized['@actor']),
         error
       });
       return;
@@ -2114,6 +2114,18 @@ function withSystemInspector(inspect, fn) {
 
 /** Snapshot-scoped actor identity and system view. @internal */
 
+// Each view's execution system and whether it forwards inspection. Views
+// never chain: they all inherit from the execution system directly.
+const snapshotSystemViews = new WeakMap();
+// Facilities owned by the execution rather than by one snapshot's view. A view
+// reads and writes them on the execution system, so timers, listeners and the
+// runtime installed through any snapshot are visible through every other.
+const executionFacilities = ['runtime', '_timerMap', '_rejectionListeners', '_inspectionObservers', '_emissionListeners'];
+// The durable execution that owns each execution system.
+/** A durable execution, as the owner of the views its transitions create. @internal */
+
+const executionOwners = new WeakMap();
+let ambientExecutionOwner;
 const snapshotActorRefs = new WeakMap();
 const lazySnapshotActorRefs = new WeakMap();
 const emptyKeyedActors = new Map();
@@ -2173,12 +2185,22 @@ function getSnapshotChildren(snapshot) {
  *
  * @internal
  */
-function createSnapshotSystem(baseSystem, children, baseState) {
-  const forwardInspection = hasAmbientInspector();
+function createSnapshotSystem(baseSystem, children, baseState, owner) {
+  const baseView = snapshotSystemViews.get(baseSystem);
+  const baseExecutionSystem = baseView?.executionSystem ?? baseSystem;
+  // The runtime system under every view. A view runs its methods against the
+  // execution system's facilities.
+  const rootSystem = baseView?.rootSystem ?? baseSystem;
+  const forks = owner !== undefined && executionOwners.get(baseExecutionSystem) !== owner;
+  // A view an execution owns reports to that execution's inspector.
+  const forwardInspection = owner ? !!owner.inspect : hasAmbientInspector() && (baseView?.forwardInspection ?? true);
   const registeredActors = copyRegisteredActors(baseSystem, baseState);
   const keyedActors = new Map(baseState?.keyedActors ?? getKeyedActors(baseSystem));
   const reverseKeyedActors = new WeakMap();
-  const system = Object.assign(Object.create(baseSystem), {
+  // The view's execution system; adoption can make the view its own.
+  const execution = () => snapshotSystemViews.get(system).executionSystem;
+  const forwards = () => snapshotSystemViews.get(system).forwardInspection;
+  const system = Object.assign(Object.create(baseExecutionSystem), {
     children: registeredActors,
     keyedActors,
     reverseKeyedActors,
@@ -2213,15 +2235,38 @@ function createSnapshotSystem(baseSystem, children, baseState) {
     },
     get: registryKey => keyedActors.get(registryKey),
     getAll: () => Object.fromEntries(keyedActors),
-    onEmitted: listener => baseSystem.onEmitted(listener),
-    _notifyEmitted: (actorRef, event) => baseSystem._notifyEmitted(actorRef, event),
+    onEmitted: listener => rootSystem.onEmitted.call(execution(), listener),
+    _notifyEmitted: (actorRef, event) => rootSystem._notifyEmitted.call(execution(), actorRef, event),
     // Pure transition resolution must not leak topology inspection events
     // into a live runtime system — planning branches stay silent. The one
     // exception is a durable execution's own transitions (marked by the
     // ambient inspector at creation time): there the pure path IS the
-    // execution, so inspection forwards to the base system's observers.
-    _hasInspectionObservers: forwardInspection ? () => baseSystem._hasInspectionObservers?.() ?? false : () => false,
-    _sendInspectionEvent: forwardInspection ? event => baseSystem._sendInspectionEvent(event) : () => {}
+    // execution, so inspection forwards to the execution system's observers.
+    _hasInspectionObservers: () => forwards() && (rootSystem._hasInspectionObservers?.call(execution()) ?? false),
+    _sendInspectionEvent: event => {
+      if (forwards()) {
+        rootSystem._sendInspectionEvent.call(execution(), event);
+      }
+    }
+  });
+  const executionSystem = forks ? system : baseExecutionSystem;
+  if (forks) {
+    forkFacilities(system, baseExecutionSystem, owner);
+  } else {
+    for (const key of executionFacilities) {
+      Object.defineProperty(system, key, {
+        configurable: true,
+        get: () => execution()[key],
+        set: value => {
+          execution()[key] = value;
+        }
+      });
+    }
+  }
+  snapshotSystemViews.set(system, {
+    executionSystem,
+    rootSystem,
+    forwardInspection
   });
   for (const [registryKey, actor] of keyedActors) {
     if (!actor) {
@@ -2245,6 +2290,83 @@ function createSnapshotSystem(baseSystem, children, baseState) {
   return system;
 }
 
+/**
+ * Makes `system` the execution system of `owner`, a new incarnation: it gets
+ * the owner's runtime and the pending timers it saw, and starts with no
+ * listeners or inspectors, so nothing registered on another execution
+ * observes it.
+ */
+function forkFacilities(system, from, owner) {
+  const timers = from._timerMap;
+  for (const key of executionFacilities) {
+    Object.defineProperty(system, key, {
+      configurable: true,
+      writable: true,
+      value: key === 'runtime' ? owner.runtime : key === '_timerMap' && timers ? {
+        ...timers
+      } : undefined
+    });
+  }
+  executionOwners.set(system, owner);
+  if (owner.inspect) {
+    system.inspect(owner.inspect);
+  }
+}
+
+/**
+ * Makes `owner` own `system` before it installs its runtime there, and
+ * returns whether it does. An unowned view forks in place, so the install
+ * never reaches the system it was derived from. A system another execution
+ * owns is left alone.
+ *
+ * @internal
+ */
+function adoptSystem(system, owner) {
+  const view = snapshotSystemViews.get(system);
+  const current = executionOwners.get(view?.executionSystem ?? system);
+  if (current === owner) {
+    if (view) {
+      view.forwardInspection = !!owner.inspect;
+    }
+    return true;
+  }
+  // A system another execution owns stays with it.
+  if (current) {
+    return false;
+  }
+  if (!view) {
+    executionOwners.set(system, owner);
+    return true;
+  }
+  forkFacilities(system, view.executionSystem, owner);
+  view.executionSystem = system;
+  view.forwardInspection = !!owner.inspect;
+  return true;
+}
+
+/**
+ * Runs `fn` as a transition of `owner`. A view it derives from a system the
+ * owner does not own forks into the owner's own execution system.
+ *
+ * @internal
+ */
+function withExecutionOwner(owner, fn) {
+  const previous = ambientExecutionOwner;
+  ambientExecutionOwner = owner;
+  try {
+    return fn();
+  } finally {
+    ambientExecutionOwner = previous;
+  }
+}
+
+/** Hands the ambient owner to the first scope that asks for it. @internal */
+function takeExecutionOwner() {
+  const owner = ambientExecutionOwner;
+  ambientExecutionOwner = undefined;
+  return owner;
+}
+
 /** Returns the actor identity associated with a transition snapshot. @internal */
 function getSnapshotActorRef(snapshot) {
   const existing = snapshotActorRefs.get(snapshot);
@@ -2438,8 +2560,9 @@ function setInertActorScopeSnapshot(actorScope, snapshot, attachActorRef = true)
   const lazyState = getLazyInertActorState(actorScope);
   if (lazyState) {
     lazyState.snapshot = snapshot;
-    if (lazyState.materialized) {
-      lazyState.materialized.self._snapshot = snapshot;
+    const scope = lazyState.materialized ?? lazyState.identityScope;
+    if (scope) {
+      scope.self._snapshot = snapshot;
     }
   } else {
     actorScope.self._snapshot = snapshot;
@@ -2474,6 +2597,15 @@ function attachSnapshotActorRef(actorScope, snapshot) {
   setLazySnapshotActorRef(snapshot, create);
   return snapshot;
 }
+/** Records the materialized scope and releases its consumed source. */
+function commitMaterialization(state, scope) {
+  // Dropping the consumed source keeps this scope from retaining earlier snapshots.
+  state.sourceRef = undefined;
+  state.sourceChildren = {};
+  state.materialized = scope;
+  state.materialize = () => scope;
+  return scope;
+}
 const lazyInertActorState = Symbol();
 const snapshotActorScopes = new WeakMap();
 let inertActorMaterializationObserver;
@@ -2518,12 +2650,14 @@ const lazyInertActorScopePrototype = {
     return materializeInertActorScope(this).actionExecutor;
   }
 };
-function createMaterializedInertActorScope(actorLogic, sourceRef, sourceChildren, currentSnapshot, sourceSelf) {
+
+/** Creates a transactional planning scope backed by an inert actor. */
+function createMaterializedInertActorScope(actorLogic, sourceRef, sourceChildren, currentSnapshot, sourceSelf, owner) {
   inertActorMaterializationObserver?.();
   const snapshotRef = sourceRef?.();
   const previousSelf = sourceSelf ?? snapshotRef?.actor;
   const baseSystem = previousSelf?.system;
-  const system = previousSelf && baseSystem ? createSnapshotSystem(baseSystem, sourceChildren, sourceSelf ? undefined : snapshotRef?.systemState) : undefined;
+  const system = previousSelf && baseSystem ? createSnapshotSystem(baseSystem, sourceChildren, sourceSelf ? undefined : snapshotRef?.systemState, owner) : undefined;
   const self = createActor(actorLogic, {
     _inert: true,
     ...(previousSelf ? {
@@ -2543,12 +2677,8 @@ function createMaterializedInertActorScope(actorLogic, sourceRef, sourceChildren
     // a future construction-time read cannot pin a root-shaped address.
     self._address = undefined;
   }
-  if (currentSnapshot) {
-    self._snapshot = currentSnapshot;
-  }
-
   // Reuse the branch actor's scope while keeping planning transactional.
-  return Object.create(self._actorScope, {
+  const scope = Object.create(self._actorScope, {
     defer: {
       value: () => {}
     },
@@ -2557,8 +2687,20 @@ function createMaterializedInertActorScope(actorLogic, sourceRef, sourceChildren
     },
     actionExecutor: {
       value: () => {}
+    },
+    _snapshot: {
+      enumerable: true,
+      configurable: true,
+      get: () => self._snapshot,
+      set: snapshot => {
+        self._snapshot = snapshot;
+      }
     }
   });
+  if (currentSnapshot) {
+    scope._snapshot = currentSnapshot;
+  }
+  return scope;
 }
 
 /** @internal */
@@ -2573,22 +2715,34 @@ function createInertActorScope(actorLogic, snapshot, sourceSelf, sourceActorScop
     sourceChildren: isMachineSnapshot(snapshot) ? snapshot.children : {},
     identityProvider: sourceState?.identityProvider ?? sourceRef,
     parent: sourceSelf?._parent ?? sourceState?.parent ?? eagerSourceRef?.actor._parent,
+    // Only the outermost scope of an owned transition belongs to the owner;
+    // scopes for its intermediate snapshots inherit it, and nested pure
+    // transitions run unowned.
+    owner: sourceActorScope ? sourceState?.owner : takeExecutionOwner(),
     parentKnown: !!sourceSelf || !!sourceState?.parentKnown || !!eagerSourceRef || !snapshot
   };
-  state.materialize = () => state.materialized ??= createMaterializedInertActorScope(actorLogic, state.sourceRef, state.sourceChildren, state.snapshot, sourceSelf);
+  state.materialize = () => {
+    const scope = createMaterializedInertActorScope(actorLogic, state.sourceRef, state.sourceChildren, state.snapshot, sourceSelf, state.owner);
+    return commitMaterialization(state, scope);
+  };
   if (!state.identityProvider && !snapshot) {
     const identitySnapshot = {};
-    const identitySourceRef = state.sourceRef;
-    const identitySourceChildren = state.sourceChildren;
-    let identityScope;
     let identityRef;
-    const getIdentityScope = () => identityScope ??= createMaterializedInertActorScope(actorLogic, identitySourceRef, identitySourceChildren, undefined, sourceSelf);
+    const getIdentityScope = () => {
+      if (!state.identityScope) {
+        state.identityScope = createMaterializedInertActorScope(actorLogic, state.sourceRef, state.sourceChildren, undefined, sourceSelf, state.owner);
+        if (state.snapshot !== undefined) {
+          state.identityScope.self._snapshot = state.snapshot;
+        }
+      }
+      return state.identityScope;
+    };
     state.materialize = () => {
       const scope = getIdentityScope();
       if (state.snapshot !== undefined) {
         scope.self._snapshot = state.snapshot;
       }
-      return state.materialized = scope;
+      return commitMaterialization(state, scope);
     };
     state.identityProvider = () => {
       if (identityRef) {
@@ -4561,6 +4715,8 @@ const machineSnapshotToJSON = function toJSON() {
   const {
     nodes,
     _stateInputs,
+    _nextTimerId,
+    _nextActorIds,
     tags,
     machine,
     getMeta,
@@ -4679,6 +4835,8 @@ function getPersistedSnapshot(snapshot, options) {
   const {
     nodes,
     _stateInputs,
+    _nextTimerId,
+    _nextActorIds,
     tags,
     machine,
     children,
@@ -4805,6 +4963,11 @@ function getPersistedSnapshot(snapshot, options) {
   if (_stateInputs && Object.keys(_stateInputs).length > 0) {
     persisted.stateInputs = _stateInputs;
   }
+  // Stores such as Convex reject `_`-prefixed field names.
+  persisted.nextTimerId = _nextTimerId;
+  if (_nextActorIds && Object.keys(_nextActorIds).length > 0) {
+    persisted.nextActorIds = _nextActorIds;
+  }
   if (machine.version !== undefined) {
     persisted.machine = {
       id: machine.id,
@@ -4827,7 +4990,7 @@ function persistContext(contextPart, getActorId, path = 'context', ancestors = [
         };
         // The address lets refs to non-children still route after restore.
         copy[key] = {
-          $actor: value.address
+          '@actor': value.address
         };
       } else {
         const valuePath = Array.isArray(contextPart) ? `${path}[${key}]` : `${path}.${key}`;
@@ -5460,11 +5623,18 @@ class RuntimeSystem {
   // Records a send on the *sender's* transition for the `sent[]` inspection
   // facet. Captures the send when it is initiated (including delayed sends that
   // may never deliver), keyed to the source actor's in-flight transition.
+  // A send made with no transition in flight (a callback's `sendBack`, a value
+  // an observable relays to its parent) is not recorded: no transition reports
+  // it, so it would be held until the source's next transition, or for as long
+  // as the source lives if it never makes one.
   _recordSent(source, target, event, delay, id) {
     if (!this._inspectionObservers?.size || !source) {
       return;
     }
     const inspectionSource = source;
+    if (!inspectionSource._inTransition) {
+      return;
+    }
     const collected = inspectionSource._collectedSent ??= [];
     collected.push({
       targetRef: target,
@@ -5701,9 +5871,9 @@ class RuntimeSystem {
       } else if (
       // A live actor of another incarnation is stale locally; an
       // address this system cannot see may belong to a host runtime.
-      this._getByAddress(target.$actor) || !this.runtime?.sendEvent) {
+      this._getByAddress(target['@actor']) || !this.runtime?.sendEvent) {
         return this.deadLetter(source, undefined, event, 'missingTarget', {
-          targetId: getAddressId(target.$actor),
+          targetId: getAddressId(target['@actor']),
           error: createMissingAddressError(target)
         });
       }
@@ -5987,6 +6157,12 @@ class Actor {
     this._collectedActions = void 0;
     /** @internal Events relayed to other actors during the in-flight transition. */
     this._collectedSent = void 0;
+    /**
+     * @internal Whether a transition is in flight: while the actor starts,
+     * processes an event, or recovers from an execution error. Sends are recorded
+     * for `sent[]` only then.
+     */
+    this._inTransition = false;
     this._initialEffects = void 0;
     this.registryKey = void 0;
     /** The globally unique process ID for this invocation. */
@@ -6059,9 +6235,14 @@ class Actor {
         // transition functions; computing an initial snapshot here would run
         // init-time side effects (context factories, entry) a second time.
       } else {
-        const [snapshot, effects] = finalizeTransitionResult(this._actorScope, undefined, this.logic.initialTransition(this.options?.input, this._actorScope));
-        this._setSnapshot(snapshot);
-        this._initialEffects = effects.length ? effects : undefined;
+        this._inTransition = true;
+        try {
+          const [snapshot, effects] = finalizeTransitionResult(this._actorScope, undefined, this.logic.initialTransition(this.options?.input, this._actorScope));
+          this._setSnapshot(snapshot);
+          this._initialEffects = effects.length ? effects : undefined;
+        } finally {
+          this._inTransition = false;
+        }
       }
     } catch (err) {
       // Restored logic may keep its snapshot shape on restore failures (e.g.
@@ -6214,6 +6395,8 @@ class Actor {
     if (!errorEvent) {
       return false;
     }
+    const inTransition = this._inTransition;
+    this._inTransition = true;
     try {
       const [nextSnapshot, effects] = finalizeTransitionResult(this._actorScope, snapshot, this.logic.transition(snapshot, errorEvent, this._actorScope));
       this._setSnapshot(nextSnapshot);
@@ -6222,6 +6405,8 @@ class Actor {
       return true;
     } catch {
       return false;
+    } finally {
+      this._inTransition = inTransition;
     }
   }
   _next(snapshot) {
@@ -6433,6 +6618,15 @@ class Actor {
 
   /** Starts the Actor from the initial state */
   start() {
+    const inTransition = this._inTransition;
+    this._inTransition = true;
+    try {
+      return this._start();
+    } finally {
+      this._inTransition = inTransition;
+    }
+  }
+  _start() {
     if (this._processingStatus === ProcessingStatus.Running) {
       // Do not restart the service if it is already started
       return this;
@@ -6548,7 +6742,16 @@ class Actor {
     this.mailbox?.start();
     return this;
   }
-  _process({
+  _process(item) {
+    const inTransition = this._inTransition;
+    this._inTransition = true;
+    try {
+      this._processEvent(item);
+    } finally {
+      this._inTransition = inTransition;
+    }
+  }
+  _processEvent({
     event,
     sourceRef
   }) {
@@ -6785,12 +6988,12 @@ class Actor {
   }
 
   /**
-   * Returns the actor's serializable logical identity: `{ $actor: address }`.
+   * Returns the actor's serializable logical identity: `{ "@actor": address }`.
    * The result can be used as an `enq.sendTo(...)` target.
    */
   toJSON() {
     return {
-      $actor: this.address
+      '@actor': this.address
     };
   }
 
@@ -6914,6 +7117,7 @@ exports.XSTATE_LOGIC_EFFECT_START = XSTATE_LOGIC_EFFECT_START;
 exports.XSTATE_STOP = XSTATE_STOP;
 exports.XSTATE_STOP_EFFECT = XSTATE_STOP_EFFECT;
 exports.XSTATE_TIMER = XSTATE_TIMER;
+exports.adoptSystem = adoptSystem;
 exports.allocateChildId = allocateChildId;
 exports.assertChildIdFree = assertChildIdFree;
 exports.assertUnreservedSourceName = assertUnreservedSourceName;
@@ -7011,5 +7215,6 @@ exports.toTransitionConfigArray = toTransitionConfigArray;
 exports.transitionNode = transitionNode;
 exports.withActorSelf = withActorSelf;
 exports.withExecutionIdentity = withExecutionIdentity;
+exports.withExecutionOwner = withExecutionOwner;
 exports.withSystemInspector = withSystemInspector;
 exports.xstateError = xstateError;

package/dist/declarations/src/createActor.d.ts

@@ -163,7 +163,9 @@ export declare class Actor<TLogic extends AnyActorLogic> implements ActorInstanc
     select<TSelected>(selector: (snapshot: SnapshotFrom<TLogic>) => TSelected, equalityFn?: (a: TSelected, b: TSelected) => boolean): Readable<TSelected>;
     /** Starts the Actor from the initial state */
     start(): this;
+    private _start;
     private _process;
+    private _processEvent;
     private _warnedUnhandledTypes?;
     private _reportUnhandledEvent;
     /** Stops the Actor and unsubscribe all listeners. */
@@ -185,7 +187,7 @@ export declare class Actor<TLogic extends AnyActorLogic> implements ActorInstanc
      */
     private _sendPublic;
     /**
-     * Returns the actor's serializable logical identity: `{ $actor: address }`.
+     * Returns the actor's serializable logical identity: `{ "@actor": address }`.
      * The result can be used as an `enq.sendTo(...)` target.
      */
     toJSON(): SerializedActorRef;

package/dist/declarations/src/createMachine.d.ts

@@ -4,8 +4,11 @@ import type { Spawner } from "./spawn.js";
 import type { ActorLogicValidator } from "./validation.types.js";
 import { AnyActorRef, AnyStateMachine, EventObject, AnyEventObject, MachineContext, ProvidedActor, StateValueFromStateSchema, ToChildren, MetaObject, StateSchema, RoutableStateId } from "./types.js";
 import type { Cast, DoNotInfer, Compute } from "./typeUtils.js";
-import { ChildCompletionEvents, Sources, DelayMapFromNames, InferChildren, InferMachineInput, InferOutput, SchemaOrConfigOutput, InferEvents, InferInternalEvents, Next_MachineConfig, Next_StateNodeConfig, ValidateDelayReferences, ValidateEventDescriptors, ValidateHistoryDefaults, ValidateInvokeInputs, ValidateVersionedMachineId, ValidateStateTargets, ValidateTopLevelFinalOutputs, WidenLiterals, WithDefault } from "./types.v6.js";
+import { ChildCompletionEvents, Sources, DelayMapFromNames, InferChildren, InferredInvokeChildren, InferMachineInput, InferOutput, SchemaOrConfigOutput, InferEvents, InferInternalEvents, Next_MachineConfig, Next_StateNodeConfig, ValidateDelayReferences, ValidateEventDescriptors, ValidateHistoryDefaults, ValidateInvokeInputs, ValidateVersionedMachineId, ValidateStateTargets, ValidateTopLevelFinalOutputs, WidenLiterals, WithDefault } from "./types.v6.js";
 type MergeChildren<TChildren extends Record<string, AnyActorRef | undefined>, TActor extends ProvidedActor> = [keyof TChildren] extends [never] ? Compute<ToChildren<TActor>> : Compute<TChildren>;
+type ConfigActors<TConfig, TActorMap extends Sources['actors']> = TConfig extends {
+    actors: infer TActors extends Sources['actors'];
+} ? TActors : TActorMap;
 type MachineIdentity<TConfig> = {
     readonly id: TConfig extends {
         id: infer TId extends string;
@@ -66,7 +69,7 @@ export declare function createMachine<TContextSchema extends StandardSchemaV1, c
 } & ValidateTopLevelFinalOutputs<TSS, InferOutput<TContextSchema, MachineContext>, InferEvents<TEventSchemaMap> | InferInternalEvents<TInternalEventSchemaMap>>): [TSS] extends [never] ? AnyStateMachine : StateMachine<InferOutput<TContextSchema, MachineContext>, (InferEvents<TEventSchemaMap> | InferInternalEvents<TInternalEventSchemaMap>) | ([RoutableStateId<TSS>] extends [never] ? never : {
     type: 'xstate.route';
     to: RoutableStateId<TSS>;
-}), Cast<MergeChildren<InferChildren<TChildrenSchemaMap>, TActor>, Record<string, AnyActorRef | undefined>>, StateValueFromStateSchema<TSS>, TTag & string, InferMachineInput<TInputSchema>, SchemaOrConfigOutput<TOutputSchema, TSS>, WithDefault<InferEvents<TEmittedSchemaMap>, AnyEventObject>, InferOutput<TMetaSchema, MetaObject>, // TMeta
+}), Cast<MergeChildren<InferChildren<TChildrenSchemaMap>, TActor> & InferredInvokeChildren<TSS, ConfigActors<TSS, TActorMap>>, Record<string, AnyActorRef | undefined>>, StateValueFromStateSchema<TSS>, TTag & string, InferMachineInput<TInputSchema>, SchemaOrConfigOutput<TOutputSchema, TSS>, WithDefault<InferEvents<TEmittedSchemaMap>, AnyEventObject>, InferOutput<TMetaSchema, MetaObject>, // TMeta
 TSS, // TStateSchema
 TActionMap, TActorMap, TGuardMap, DelayMapFromNames<TDelays, TDelayMap>, InferInternalEvents<TInternalEventSchemaMap>, TransitionMetaFromSchemas<TMetaSchema, TTransitionMetaSchema>> & {
     states: TSS;
@@ -84,7 +87,7 @@ export declare function createMachine<TContext extends MachineContext = never, c
 } & ValidateTopLevelFinalOutputs<TSS, WidenLiterals<TContext>, InferEvents<TEventSchemaMap> | InferInternalEvents<TInternalEventSchemaMap>>): [TSS] extends [never] ? AnyStateMachine : StateMachine<WidenLiterals<TContext>, (InferEvents<TEventSchemaMap> | InferInternalEvents<TInternalEventSchemaMap>) | ([RoutableStateId<TSS>] extends [never] ? never : {
     type: 'xstate.route';
     to: RoutableStateId<TSS>;
-}), Cast<MergeChildren<InferChildren<TChildrenSchemaMap>, TActor>, Record<string, AnyActorRef | undefined>>, StateValueFromStateSchema<TSS>, TTag & string, InferMachineInput<TInputSchema>, SchemaOrConfigOutput<TOutputSchema, TSS>, WithDefault<InferEvents<TEmittedSchemaMap>, AnyEventObject>, InferOutput<TMetaSchema, MetaObject>, // TMeta
+}), Cast<MergeChildren<InferChildren<TChildrenSchemaMap>, TActor> & InferredInvokeChildren<TSS, ConfigActors<TSS, TActorMap>>, Record<string, AnyActorRef | undefined>>, StateValueFromStateSchema<TSS>, TTag & string, InferMachineInput<TInputSchema>, SchemaOrConfigOutput<TOutputSchema, TSS>, WithDefault<InferEvents<TEmittedSchemaMap>, AnyEventObject>, InferOutput<TMetaSchema, MetaObject>, // TMeta
 TSS, // TStateSchema
 TActionMap, TActorMap, TGuardMap, DelayMapFromNames<TDelays, TDelayMap>, InferInternalEvents<TInternalEventSchemaMap>, TransitionMetaFromSchemas<TMetaSchema, TTransitionMetaSchema>> & {
     states: TSS;

package/dist/declarations/src/durable/index.d.ts

@@ -1,7 +1,7 @@
 import { type ExecutableEffectDescriptor } from "../effectDescriptor.js";
 import { type ActorSystemRuntime } from "../system.js";
 import type { InspectionEvent } from "../inspection.js";
-import type { AnyActor, AnyActorLogic, AnyEventObject, CustomExecutableEffect, EventFromLogic, ExecutableEffectFrom, InputFrom, OutputFrom, Snapshot, SnapshotFrom } from "../types.js";
+import type { AnyActor, AnyActorLogic, AnyEventObject, CustomExecutableEffect, EventFromLogic, ExecutableEffectFrom, InputFrom, OutputFrom, SerializedActorRef, Snapshot, SnapshotFrom } from "../types.js";
 /** @experimental */
 export interface DurableEffectMetadata {
     /** Stable within one durable execution. */
@@ -26,6 +26,28 @@ export interface DurableRootEvent<TEvent> {
     event: TEvent;
     source: AnyActor | undefined;
 }
+/**
+ * A root-addressed event that the execution received but has not processed,
+ * stored in a checkpoint. `source` is the sender's logical address.
+ *
+ * @experimental
+ */
+export interface DurableInboxEntry {
+    event: AnyEventObject;
+    source: SerializedActorRef | undefined;
+}
+/**
+ * Everything needed to resume an execution: the persisted snapshot, the next
+ * transition index and the events received but not yet processed. Persist
+ * the whole object atomically and pass it to `restore()`.
+ *
+ * @experimental
+ */
+export interface DurableCheckpoint {
+    snapshot: Snapshot<unknown>;
+    nextTransitionIndex: number;
+    inbox: DurableInboxEntry[];
+}
 /** @experimental */
 export interface DurableEffect<TEffect> extends DurableEffectMetadata {
     effect: TEffect;
@@ -148,13 +170,26 @@ export interface DurableExecution<TLogic extends AnyActorLogic> {
     /** Index assigned to the next transition. Persist this with checkpoints. */
     readonly nextTransitionIndex: number;
     /**
-     * Restores a checkpoint on a fresh execution. Returns effects that start
-     * active embedded children and re-arm pending root timers; execute them
-     * with `executeEffects` before waiting or processing the next event.
-     * Does not send a machine event, replay entry actions, or advance the
-     * transition index. Restoration effect IDs use `restore:<index>:<effect>`.
+     * Returns a checkpoint of `snapshot`: its persisted form, the next
+     * transition index and the inbox of root events captured by settled
+     * `executeEffects` batches but not yet taken by `waitForEvent()`. Call it
+     * after `executeEffects` resolves. Inbox event payloads are stored as they
+     * are, so they must be serializable data, like timer events in persisted
+     * snapshots. Lifecycle events for children no longer in `snapshot` are
+     * dropped, and child snapshot updates are not stored: a restored child
+     * reports its current snapshot when it starts.
+     */
+    checkpoint(snapshot: SnapshotFrom<TLogic>, options?: unknown): DurableCheckpoint;
+    /**
+     * Restores a checkpoint on a fresh execution. Accepts a `checkpoint()`
+     * result, whose inbox `waitForEvent()` hands out first, or a bare persisted
+     * snapshot. Returns effects that start active embedded children and re-arm
+     * pending root timers; execute them with `executeEffects` before waiting or
+     * processing the next event. Does not send a machine event, replay entry
+     * actions, or advance the transition index. Restoration effect IDs use
+     * `restore:<index>:<effect>`.
      */
-    restore(persistedSnapshot: Snapshot<unknown>): [
+    restore(checkpoint: DurableCheckpoint | Snapshot<unknown>): [
         snapshot: DurableSnapshot<TLogic>,
         effects: DurableEffect<ExecutableEffectFrom<TLogic>>[]
     ];
@@ -196,7 +231,7 @@ export interface DurableExecution<TLogic extends AnyActorLogic> {
      * an event a prior `executeEffects` batch captured (an invoked actor
      * completing, a child reporting up), or — once none are queued — whatever
      * the adapter's durable wait produces. With `captureRootEvents: false`,
-     * always delegates to the adapter's wait.
+     * delegates to the adapter's wait once a restored inbox is empty.
      */
     waitForEvent(): Promise<EventFromLogic<TLogic>>;
     run(...[input]: undefined extends InputFrom<TLogic> ? [input?: InputFrom<TLogic>] : [input: InputFrom<TLogic>]): Promise<OutputFrom<TLogic>>;