xstate 6.0.0-alpha.40 → 6.0.0-alpha.41

package/dist/{createActor-c0f78b8a.development.cjs.js → createActor-20615484.development.cjs.js}

@@ -58,6 +58,9 @@ const XSTATE_SPAWN = '@xstate.spawn';
 const XSTATE_STOP = '@xstate.stop';
 const XSTATE_TERMINATE = '@xstate.terminate';
 const XSTATE_TIMER = 'xstate.timer';
+const XSTATE_LOGIC_EFFECT_RESOLVE = 'xstate.logic.effect.resolve';
+const XSTATE_LOGIC_EFFECT_REJECT = 'xstate.logic.effect.reject';
+const XSTATE_LOGIC_EFFECT_START = 'xstate.logic.effect.start';
 
 /**
  * Returns an event that represents an implicit event that is sent after the
@@ -180,6 +183,118 @@ function reportUnhandledError(err) {
 
 const symbolObservable = (() => typeof Symbol === 'function' && Symbol.observable || '@@observable')();
 
+const emptySubscription = {
+  unsubscribe() {}
+};
+const restoreHint = 'or restore this snapshot with embedded children on the runtime that owns them.';
+
+/** @internal */
+function isRemoteActorRef(actorRef) {
+  return actorRef._remote === true;
+}
+
+/**
+ * The lifecycle-only snapshot a remote handle exposes. `active` is accurate
+ * by construction: a completion removes the child from its parent's
+ * `children`, so a handle only exists while the child is presumed active,
+ * and the terminal result arrives as a completion event instead of a
+ * snapshot. Full snapshots are a co-location capability.
+ */
+const remoteSnapshot = Object.freeze({
+  status: 'active',
+  output: undefined,
+  error: undefined
+});
+
+/**
+ * Creates a location-transparent handle to an actor whose state lives with
+ * another runtime. The handle is constructed from identity alone — no lookup
+ * — and every send routes through the system's runtime; its state is not
+ * synchronously readable.
+ *
+ * The surface is deliberately minimal: it covers every member the runtime
+ * reaches for a restored child (send/_send, lifecycle via start/_stop and
+ * system.stopActor, persistence, subscribe/on as inert subscriptions).
+ * Members that only make sense for a co-located actor (public stop(),
+ * select(), trigger) throw a descriptive error rather than being absent, so
+ * calling one reports what went wrong instead of a bare TypeError. Observable
+ * interop and _processingStatus are omitted entirely.
+ *
+ * @internal
+ */
+function createRemoteActorRef(system, options) {
+  const handle = {
+    _remote: true,
+    // Self-reference so context persistence recognizes the handle as an
+    // actor reference instead of recursing into it.
+    ref: undefined,
+    id: options.id,
+    address: options.address,
+    src: options.src,
+    registryKey: options.registryKey,
+    // A remote handle does not know the child's incarnation; the runtime that
+    // owns the child is the authority on completion staleness — unless the
+    // host supplied an incarnation token, which lets this side drop stale
+    // completions and lets journaled sends name the intended incarnation.
+    sessionId: undefined,
+    _incarnation: options.incarnation,
+    system,
+    _parent: options.parent,
+    // Round-trips through persistence verbatim (undefined stays undefined,
+    // so re-persisting is byte-stable); a remote handle cannot act on it
+    // locally.
+    _syncSnapshot: options.syncSnapshot,
+    send(event) {
+      void system.sendEvent(undefined, ref, event);
+    },
+    _send(event) {
+      throw new Error(`Remote actor '${options.address}' has no local mailbox to receive "${event.type}". Its state lives with another runtime; install a runtime that can reach it (via \`createDurable\`'s adapter runtime operations, or \`system.runtime\`) before sending, ${restoreHint}`);
+    },
+    getSnapshot() {
+      return remoteSnapshot;
+    },
+    getPersistedSnapshot() {
+      throw new Error(`Cannot persist remote actor '${options.address}' from here: its state lives with the runtime that owns it. Persist it there, ${restoreHint}`);
+    },
+    start() {},
+    _stop() {},
+    stop() {
+      throw new Error(`Cannot stop remote actor '${options.address}' directly: stopping is a co-located operation. Stop it through the system runtime that owns it (\`system.stopActor(ref)\`), ${restoreHint}`);
+    },
+    select() {
+      throw new Error(`Cannot select from remote actor '${options.address}': its snapshot is not synchronously readable because its state lives with another runtime. Read it on the runtime that owns it, ${restoreHint}`);
+    },
+    get trigger() {
+      throw new Error(`Remote actor '${options.address}' has no \`trigger\` shorthand: it requires a co-located actor. Use \`send(...)\`, which routes through the system runtime.`);
+    },
+    // Observation is a co-location capability: a remote handle never emits,
+    // so subscriptions are inert rather than errors — generic observers may
+    // attach to any ref.
+    subscribe() {
+      return emptySubscription;
+    },
+    on() {
+      return emptySubscription;
+    },
+    _isRunning() {
+      return false;
+    },
+    // The same shape Actor.toJSON produces, so serialized snapshots carry
+    // one actor-reference marker whether a child is co-located or remote.
+    toJSON() {
+      return {
+        xstate$type: ACTOR_REF_TYPE,
+        id: options.id,
+        address: options.address,
+        src: options.src
+      };
+    }
+  };
+  const ref = handle;
+  handle.ref = ref;
+  return ref;
+}
+
 function assertSendToEvent(event) {
   if (typeof event === 'string') {
     throw new Error(// eslint-disable-next-line @typescript-eslint/restrict-template-expressions
@@ -223,7 +338,12 @@ const subscriptions = /* #__PURE__ */new WeakMap();
  * Internal factory for actor logic that attaches to another actor on start
  * (`enq.listen()` / `enq.subscribeTo()`) and detaches when stopped.
  */
-function createAttachedLogic(attach) {
+function createAttachedLogic(attach,
+/**
+ * Names the logic so its generated actor ids get their own prefix, out of
+ * the id space that user sources allocate from.
+ */
+id) {
   const initialTransition = (input, _) => [{
     status: 'active',
     output: undefined,
@@ -231,6 +351,7 @@ function createAttachedLogic(attach) {
     input
   }, []];
   return {
+    id,
     start: (state, {
       self,
       system
@@ -329,7 +450,7 @@ function createListenerLogic() {
       }
       relayMappedToParent(self, system, () => mapper(emittedEvent));
     });
-  });
+  }, 'xstate.listener');
 }
 
 // Singleton logic instance
@@ -371,7 +492,7 @@ function createSubscriptionLogic() {
         // Actor completed without output (stopped); no action needed
       }
     });
-  });
+  }, 'xstate.subscription');
 }
 
 // Singleton logic instance
@@ -570,6 +691,17 @@ function pushBuiltInAction(actions, action, ...args) {
   actions.push(actionRecord);
   return actionRecord;
 }
+
+/** @internal Max-merges generated-id counter records, copy-on-write. */
+function mergeActorIdCounters(current, update) {
+  const merged = {
+    ...current
+  };
+  for (const key of Object.keys(update)) {
+    merged[key] = Math.max(merged[key] ?? 0, update[key]);
+  }
+  return merged;
+}
 function applyChildUpdate(snapshot, update, actorScope) {
   if (update.type === 'add') {
     return {
@@ -577,7 +709,10 @@ function applyChildUpdate(snapshot, update, actorScope) {
       children: {
         ...snapshot.children,
         [update.id]: update.actor
-      }
+      },
+      ...(update.counters && {
+        _nextActorIds: mergeActorIdCounters(snapshot._nextActorIds, update.counters)
+      })
     };
   }
   const children = {
@@ -605,15 +740,187 @@ function getTransitionActionRecord(action) {
   }
   return undefined;
 }
-function pushSpawnedChild(actions, actor, id) {
+function pushSpawnedChild(actions, actor, id, counters) {
   const action = pushBuiltInAction(actions, builtInActions['@xstate.spawn'], actor);
   action.childUpdate = {
     type: 'add',
     actor,
-    id: id ?? actor.id
+    id,
+    counters
   };
 }
+
+/**
+ * Spawn-allocation state shared by every enqueue object of one transition, so
+ * generated ids stay unique and resolvable across action functions and
+ * microsteps of the same event.
+ */
+
+const spawnAllocations = new WeakMap();
+const createSpawnAllocation = () => ({
+  counters: new Map(),
+  explicitIds: new Set(),
+  stoppedIds: new Set()
+});
+
+/**
+ * Starts a fresh spawn-allocation transaction for one logical transition.
+ * Called at every transition boundary so pure replays from the same snapshot
+ * allocate identical ids.
+ *
+ * @internal
+ */
+function beginSpawnAllocation(actorScope) {
+  spawnAllocations.set(actorScope, createSpawnAllocation());
+}
+
+// Read the raw snapshot: getSnapshot() throws while the actor initializes,
+// and entry actions run before any snapshot exists.
+function getWorkingSnapshotOf(actorScope) {
+  return actorScope.self._snapshot;
+}
+const srcKeyCaches = new WeakMap();
+function getRegisteredSrcKey(actorScope, logic) {
+  const registeredActors = actorScope.self.logic?.sources?.actors;
+  if (!registeredActors) {
+    return undefined;
+  }
+  let cache = srcKeyCaches.get(registeredActors);
+  if (!cache) {
+    cache = new Map();
+    for (const key of Object.keys(registeredActors)) {
+      cache.set(registeredActors[key], key);
+    }
+    srcKeyCaches.set(registeredActors, cache);
+  }
+  return cache.get(logic);
+}
+
+/**
+ * Internal helper actors (listeners, subscriptions) number their ids from
+ * system-level counters under `xstate.`-prefixed names; snapshot-owned
+ * children number from per-snapshot counters. The two spaces only stay
+ * collision-free because their prefixes are disjoint, so user sources must
+ * not enter the reserved namespace.
+ */
+function assertUnreservedPrefix(prefix) {
+  if (prefix.startsWith('xstate.')) {
+    throw new Error(`Child actor ids with the "xstate." prefix are reserved for internal actors; rename the "${prefix}" source or logic id.`);
+  }
+}
+
+/**
+ * The next free index for a prefix. The parent snapshot's persisted counter
+ * is always a floor, so a freed id is never handed out again — not even when
+ * an explicit id reserved a lower one earlier in the transition.
+ */
+function nextChildIndex(actorScope, allocation, prefix) {
+  return Math.max(allocation.counters.get(prefix) ?? 0, getWorkingSnapshotOf(actorScope)?._nextActorIds?.[prefix] ?? 0);
+}
+
+/**
+ * Allocates the next generated child id for the transition's allocation
+ * transaction, seeded from the parent snapshot's own persisted counters. This
+ * is the single allocator for snapshot-owned children (`enq.spawn` and
+ * context-factory spawns); a correct allocation cannot collide.
+ *
+ * @internal
+ */
+function allocateChildId(actorScope, src, localAllocation) {
+  if (!spawnAllocations.get(actorScope)) {
+    console.warn('A child id was generated outside a spawn-allocation transaction; ids may repeat across enqueue objects. Transition entry points must call beginSpawnAllocation().');
+  }
+  const allocation = spawnAllocations.get(actorScope) ?? localAllocation ?? createSpawnAllocation();
+  const prefix = getActorIdPrefix(src);
+  assertUnreservedPrefix(prefix);
+  const next = nextChildIndex(actorScope, allocation, prefix);
+  allocation.counters.set(prefix, next + 1);
+  return {
+    id: `${prefix}:${next}`,
+    counters: {
+      [prefix]: next + 1
+    }
+  };
+}
+
+/**
+ * Requires an explicit child id to be unoccupied before a spawn or invoke
+ * claims it: an address must name at most one live actor. An id is occupied
+ * when a child of this parent already holds it and this transition has not
+ * stopped that child, or when an earlier spawn of this transition claimed it.
+ *
+ * @internal
+ */
+function assertChildIdFree(actorScope, id, localAllocation) {
+  const allocation = spawnAllocations.get(actorScope) ?? localAllocation ?? createSpawnAllocation();
+  const existing = getWorkingSnapshotOf(actorScope)?.children?.[id];
+  // A terminated child no longer occupies its id: it relayed its completion
+  // and is removed from `children` right after the transition handling it,
+  // so the supervisor pattern — respawn under the same name while handling
+  // the child's done/error event — must not conflict with the outgoing
+  // entry. Remote handles never expose a terminal status locally; the
+  // completion event that removes one is the owning runtime's business.
+  const occupied = existing !== undefined && !allocation.stoppedIds.has(id) && existing.getSnapshot().status === 'active';
+  if (allocation.explicitIds.has(id) || occupied) {
+    throw new Error(`Cannot spawn child actor with id '${id}': the id is already in use by another child of '${actorScope.self.id}'. Stop the existing child before reusing its id.` );
+  }
+  allocation.explicitIds.add(id);
+}
+
+/**
+ * Records that this transition stopped a child, freeing its id for a later
+ * spawn or invoke of the same transition (the invoke restart pattern).
+ *
+ * @internal
+ */
+function recordStoppedChild(actorScope, actor) {
+  const allocation = spawnAllocations.get(actorScope);
+  if (allocation) {
+    allocation.stoppedIds.add(actor.id);
+    allocation.explicitIds.delete(actor.id);
+  }
+}
+
+/**
+ * Reserves an explicit generated-shaped id (`worker:5`) in the transaction
+ * and the parent snapshot, so live runs and pure replays allocate the same
+ * later ids even after this child is removed.
+ *
+ * @internal
+ */
+function reserveChildId(actorScope, id, localAllocation) {
+  const generated = parseGeneratedActorId(id);
+  if (!generated) {
+    return undefined;
+  }
+  assertUnreservedPrefix(generated.prefix);
+  const allocation = spawnAllocations.get(actorScope) ?? localAllocation ?? createSpawnAllocation();
+  // The requested id is used as asked, but numbering continues from the
+  // highest reservation: an explicit low id never rewinds the counter.
+  const next = Math.max(nextChildIndex(actorScope, allocation, generated.prefix), generated.index + 1);
+  allocation.counters.set(generated.prefix, next);
+  return {
+    [generated.prefix]: next
+  };
+}
+
+/**
+ * The counters allocated so far in the transition's transaction, for
+ * committing into a snapshot built outside `applyChildUpdate` (the
+ * pre-initial snapshot with context-factory spawns).
+ *
+ * @internal
+ */
+function takeSpawnAllocationCounters(actorScope) {
+  const counters = spawnAllocations.get(actorScope)?.counters;
+  if (!counters?.size) {
+    return undefined;
+  }
+  return Object.fromEntries(counters);
+}
 function createTransitionEnqueue(actorScope, actions, internalEvents, actorSubscriptions = false, createActors = true) {
+  // Paths that never begin a transaction keep a per-enqueue scope.
+  const localAllocation = spawnAllocations.get(actorScope) ?? createSpawnAllocation();
   const props = {
     cancel: id => {
       pushBuiltInAction(actions, builtInActions['@xstate.cancel'], actorScope, id);
@@ -641,11 +948,33 @@ function createTransitionEnqueue(actorScope, actions, internalEvents, actorSubsc
           id: options?.id ?? options?.registryKey ?? logic.id
         };
       }
+      // Recover the registered source key for setup-provided logic so the
+      // spawned child persists (and gets a deterministic id prefix) by key
+      // instead of by inline logic reference.
+      const src = getRegisteredSrcKey(actorScope, logic);
+      // Generated ids allocate from the parent snapshot's own counters
+      // through the transition's allocation transaction; explicit
+      // generated-shaped ids reserve their numbering the same way.
+      let id = options?.id;
+      let counters;
+      if (id === undefined) {
+        ({
+          id,
+          counters
+        } = allocateChildId(actorScope, src ?? logic, localAllocation));
+      } else {
+        assertChildIdFree(actorScope, id, localAllocation);
+        counters = reserveChildId(actorScope, id, localAllocation);
+      }
       const actor = actorScope.system.createActorRef(logic, {
         ...options,
+        ...(src !== undefined && {
+          src
+        }),
+        id,
         parent: actorScope.self
       });
-      pushSpawnedChild(actions, actor, options?.id);
+      pushSpawnedChild(actions, actor, id, counters);
       return actor;
     },
     sendTo: (actor, event, options) => {
@@ -665,6 +994,7 @@ function createTransitionEnqueue(actorScope, actions, internalEvents, actorSubsc
           type: 'remove',
           actor
         };
+        recordStoppedChild(actorScope, actor);
       }
     }
   };
@@ -1401,6 +1731,10 @@ function createMaterializedInertActorScope(actorLogic, sourceRef, sourceChildren
   });
   if (previousSelf?._parent) {
     self._parent = previousSelf._parent;
+    // `address` memoizes on first read assuming `_parent` is final; nothing
+    // reads it between construction and this assignment, but drop any memo so
+    // a future construction-time read cannot pin a root-shaped address.
+    self._address = undefined;
   }
   if (currentSnapshot) {
     self._snapshot = currentSnapshot;
@@ -1672,7 +2006,17 @@ function getEventDescriptorKey(event) {
   return legacyType ? `${event.type}|${legacyType}` : event.type;
 }
 function matchesActorSession(event, snapshot, actorId) {
-  return !snapshot.children[actorId] || !('sessionId' in event) || snapshot.children[actorId]?.sessionId === event.sessionId;
+  const child = snapshot.children[actorId];
+  if (!child || !('sessionId' in event)) {
+    return true;
+  }
+  if (isRemoteActorRef(child)) {
+    // Without a host-supplied incarnation token the runtime that owns the
+    // child is the authority on staleness; with one, a completion from a
+    // different incarnation of the same address is dropped here.
+    return child._incarnation === undefined || child._incarnation === event.sessionId;
+  }
+  return child.sessionId === event.sessionId;
 }
 function normalizeLegacyInternalEvent(event, machine) {
   if (event.type === 'xstate.done.actor' || event.type === 'xstate.error.actor' || event.type === 'xstate.snapshot.actor' || event.type === 'xstate.done.state' || event.type === 'xstate.after' || event.type === 'xstate.timeout' || event.type === 'xstate.timeout.actor') {
@@ -2258,9 +2602,17 @@ function narrowParallelDomain(domain, targetStates) {
 function getTransitionDomain(transition, snapshot, resolveTransition) {
   const targetStates = getEffectiveTargetStates(transition, snapshot, resolveTransition);
   const {
+    targets,
     reenter
   } = resolveTransition(transition);
-  if (targetStates.every(target => target === transition.source || isDescendant(target, transition.source))) {
+
+  // A history target that restores the source itself must exit and reenter
+  // the source (SCXML domain = the source's ancestor), unlike a plain
+  // non-reentering self-target: the enter set restores the stored
+  // configuration from outside the source, so the exit set must match or the
+  // source's invoked actors are re-created without being stopped.
+  const restoresSourceViaHistory = targets?.some(isHistoryNode) && targetStates.some(target => target === transition.source);
+  if (!restoresSourceViaHistory && targetStates.every(target => target === transition.source || isDescendant(target, transition.source))) {
     // Targets are contained within the source. A reentering transition
     // exits and reenters the source itself; otherwise the domain narrows
     // past parallel nodes so sibling regions are left untouched.
@@ -2629,6 +2981,7 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
             event,
             output: getEventOutput(event)
           }) : invokeDef.input;
+          assertChildIdFree(actorScope, invokeDef.id);
           const actor = actorScope.system.createActorRef(logic, {
             ...invokeDef,
             input,
@@ -2864,7 +3217,17 @@ function macrostep(snapshot, event, actorScope, internalQueue, initialMicrosteps
       return;
     }
     const child = nextSnapshot.children[actorId];
-    if (!child || child.sessionId !== sessionId) {
+    if (!child) {
+      return;
+    }
+    // The same staleness rule matchesActorSession applies to transition
+    // selection: a completion from a different incarnation must not remove
+    // the still-running child either.
+    if (isRemoteActorRef(child)) {
+      if (child._incarnation !== undefined && child._incarnation !== sessionId) {
+        return;
+      }
+    } else if (child.sessionId !== sessionId) {
       return;
     }
     const children = {
@@ -3236,6 +3599,7 @@ function createMachineSnapshot(config, machine, actorRef) {
     historyValue: compactSnapshotRecord(config.historyValue),
     _stateInputs: compactSnapshotRecord(config._stateInputs),
     _nextTimerId: config._nextTimerId ?? 0,
+    _nextActorIds: config._nextActorIds,
     matches: machineSnapshotMatches,
     hasTag: machineSnapshotHasTag,
     can: machineSnapshotCan,
@@ -3268,6 +3632,7 @@ function cloneMachineSnapshot(snapshot, config = {}) {
       historyValue: compactSnapshotRecord(configWithSnapshot.historyValue),
       _stateInputs: compactSnapshotRecord(configWithSnapshot._stateInputs),
       _nextTimerId: configWithSnapshot._nextTimerId ?? 0,
+      _nextActorIds: configWithSnapshot._nextActorIds,
       matches: machineSnapshotMatches,
       hasTag: machineSnapshotHasTag,
       can: machineSnapshotCan,
@@ -3316,18 +3681,46 @@ function getPersistedSnapshot(snapshot, options) {
   } = snapshot;
   const childrenJson = {};
   const timersJson = {};
+  const embedChildren = options?.embedChildren !== false;
   for (const id in children) {
     const child = children[id];
     if (typeof child.src !== 'string' && (!options || !('__unsafeAllowInlineActors' in options))) {
       throw new Error('An inline child actor cannot be persisted.');
     }
+    // Children are referenced by their logical address. Embedding the child
+    // state is the co-locating runtime's whole-tree checkpoint capability;
+    // remote handles never embed — their state lives with another runtime.
+    const embed = embedChildren && !isRemoteActorRef(child);
+    if (!embed && typeof child.src !== 'string') {
+      // Fail where it is actionable: a by-address reference without a
+      // registered source key could be persisted but never restored.
+      throw new Error(`Unable to persist child '${id}' by address: it requires a registered source key.`);
+    }
     childrenJson[id] = {
-      snapshot: child.getPersistedSnapshot(options),
+      address: child.address,
+      // The explicit marker disambiguates a by-address reference from a child
+      // whose own persisted snapshot happens to be undefined.
+      ...(embed ? {
+        snapshot: child.getPersistedSnapshot(options)
+      } : {
+        remote: true,
+        // Round-trips verbatim: the host that owns the child injects the
+        // token; XState never stamps one (a local sessionId would make
+        // persisted snapshots nondeterministic across replays).
+        incarnation: child._incarnation
+      }),
       src: child.src,
       registryKey: child.registryKey,
       syncSnapshot: child._syncSnapshot
     };
   }
+  const snapshotActor = getSnapshotActorRef(snapshot)?.actor;
+  // Only the wall clock is stamped into persisted timers: a custom clock's
+  // readings (a simulated clock, a monotonic counter) are meaningless in any
+  // other process, and restoring them under the wall clock would fire every
+  // pending delay instantly. Pure-transition snapshots have no local
+  // schedule and persist no timestamp.
+  const scheduledTimers = snapshotActor?.system?._clock?.now ? undefined : snapshotActor?.system?._snapshot?._scheduledTimers;
   for (const id in timers) {
     const timer = timers[id];
     let event = timer.event;
@@ -3352,17 +3745,28 @@ function getPersistedSnapshot(snapshot, options) {
         throw new Error(`Unable to persist timer '${id}': target actor '${timer.target.id}' is no longer addressable from this snapshot.`);
       }
     }
+    // A live runtime knows when the timer is due; persist the wall-clock
+    // start (dueAt - declared delay) so restore can honor the absolute
+    // deadline. Derived from dueAt, not the scheduling moment, so repeated
+    // persist/restore cycles keep the same deadline. Without a live schedule
+    // (a restored-but-never-started actor, a pure-transition snapshot) the
+    // timer's carried-in start — which only a wall-clock actor ever stamped —
+    // passes through, so re-persisting cannot push the deadline back.
+    const scheduled = scheduledTimers?.[`${snapshotActor.sessionId}.${id}`];
+    const startedAt = scheduled ? scheduled.dueAt - timer.delay : timer.startedAt;
     timersJson[id] = {
       id: timer.id,
       delay: timer.delay,
       type: timer.type,
       event,
-      target
+      target,
+      ...(startedAt !== undefined && {
+        startedAt
+      })
     };
   }
   const persisted = {
     ...jsonValues,
-    _nextActorId: getSnapshotActorRef(snapshot)?.systemState.snapshot._nextActorId,
     context: persistContext(context),
     children: childrenJson,
     timers: timersJson,
@@ -3390,7 +3794,7 @@ function persistContext(contextPart) {
           ...contextPart
         };
         copy[key] = {
-          xstate$$type: $$ACTOR_TYPE,
+          xstate$type: ACTOR_REF_TYPE,
           id: value.id
         };
       } else {
@@ -3657,6 +4061,106 @@ function matchesEventDescriptor(eventType, descriptor) {
   return true;
 }
 
+function getStepEffect(actor, key) {
+  return actor.getSnapshot().effects?.[key];
+}
+function waitForStep(actor, key) {
+  return new Promise((resolve, reject) => {
+    const subscription = actor.subscribe(snapshot => {
+      const effect = snapshot.effects?.[key];
+      if (effect?.status === 'done') {
+        subscription.unsubscribe();
+        resolve(effect.output);
+      } else if (effect?.status === 'error') {
+        subscription.unsubscribe();
+        reject(effect.error);
+      }
+    });
+  });
+}
+
+/**
+ * Runs one keyed step of an async actor with the built-in journal: the
+ * result is memoized in the actor's own snapshot (`effects[key]`), so a
+ * restored actor skips completed steps when its logic function re-runs.
+ * Custom runtimes that implement `runStep` use this for the default local
+ * behavior, the same way `deliverEvent` exposes local delivery.
+ *
+ * @experimental
+ */
+async function runStep(actor, key, exec, sendSelf = event => void actor.system.sendEvent(actor, actor, event)) {
+  const effect = getStepEffect(actor, key);
+  if (effect?.status === 'done') {
+    return effect.output;
+  }
+  if (effect?.status === 'error') {
+    throw effect.error;
+  }
+  if (effect?.status === 'active') {
+    return waitForStep(actor, key);
+  }
+  sendSelf({
+    type: XSTATE_LOGIC_EFFECT_START,
+    key
+  });
+  try {
+    const output = await exec();
+    sendSelf({
+      type: XSTATE_LOGIC_EFFECT_RESOLVE,
+      key,
+      output
+    });
+    return output;
+  } catch (error) {
+    sendSelf({
+      type: XSTATE_LOGIC_EFFECT_REJECT,
+      key,
+      error
+    });
+    throw error;
+  }
+}
+
+/**
+ * Delivers an event directly to a target actor, bypassing any installed host
+ * runtime. Custom runtimes use this for the default local delivery behavior
+ * inside their own `sendEvent` implementations.
+ *
+ * @experimental
+ */
+function deliverEvent(source, target, event) {
+  const runtimeTarget = target;
+  // The same guard local delivery has always applied: internal events may
+  // only originate from the actor itself, whichever runtime delivers them.
+  if (source !== target && runtimeTarget.logic?.isInternalEventType?.(event.type)) {
+    throw new Error(`Internal event "${event.type}" cannot be sent to actor "${target.id}" from outside.`);
+  }
+  runtimeTarget._lastSourceRef = source;
+  runtimeTarget._send(event);
+}
+
+/**
+ * Publishes an actor's terminal result, notifying its parent and observers.
+ * Custom runtimes use this for the default local behavior inside their own
+ * `terminateActor` implementations.
+ *
+ * @experimental
+ */
+function terminateActor(actor, termination) {
+  actor._terminate(termination);
+}
+
+/**
+ * Stops an actor without producing a completion result. Custom runtimes use
+ * this for the default local behavior inside their own `stopActor`
+ * implementations.
+ *
+ * @experimental
+ */
+function stopActor(actor) {
+  actor._stop();
+}
+
 let systemIdPrefix;
 let nextSystemId = 0;
 
@@ -3694,23 +4198,104 @@ function createSystemId() {
   return `${systemIdPrefix}:${(nextSystemId++).toString(36)}`;
 }
 
+/**
+ * Derives the deterministic id prefix for a generated actor id from its actor
+ * source: the registered source key when the source is a string, the logic's
+ * own `id` otherwise, with `x` as the last-resort prefix.
+ *
+ * @internal
+ */
+function getActorIdPrefix(src) {
+  if (typeof src === 'string') {
+    return src;
+  }
+  const logicId = src?.id;
+  // Anonymous machines get the placeholder id '(machine)'; only named logic
+  // earns a named id prefix.
+  return typeof logicId === 'string' && logicId.length && logicId !== '(machine)' ? logicId : 'x';
+}
+
+/**
+ * Encodes one actor id as an address segment. `/` separates segments, so it
+ * is percent-encoded, and the escape character `%` is escaped first so the
+ * encoding stays injective: the ids 'a/b' and 'a%2Fb' must not produce the
+ * same address.
+ *
+ * @internal
+ */
+function encodeAddressSegment(id) {
+  return id.includes('/') || id.includes('%') ? id.replaceAll('%', '%25').replaceAll('/', '%2F') : id;
+}
+
+/**
+ * Parses a generated-shaped actor id (`prefix:<n>`). This single definition is
+ * the determinism contract for id reservation: live allocation, replay, and
+ * restore must all agree on what counts as generated-shaped. Deliberately
+ * broader than ids a generated allocation could produce — over-reserving
+ * skips numbers, which is harmless, while under-reserving could collide.
+ *
+ * @internal
+ */
+function parseGeneratedActorId(id) {
+  const separator = id.lastIndexOf(':');
+  if (separator <= 0 || separator === id.length - 1) {
+    return undefined;
+  }
+  const index = Number(id.slice(separator + 1));
+  return Number.isSafeInteger(index) && index >= 0 ? {
+    prefix: id.slice(0, separator),
+    index
+  } : undefined;
+}
+
+/**
+ * The id (and address root segment) of the first parentless actor of a logic:
+ * the logic's own name, or `x:0` for anonymous logic.
+ *
+ * @internal
+ */
+function getRootActorId(src) {
+  const prefix = getActorIdPrefix(src);
+  return prefix === 'x' ? 'x:0' : prefix;
+}
+function getActorIdCounterKey(parent, prefix) {
+  return `${parent ? parent.address : ''}|${prefix}`;
+}
+function bumpActorIdCounter(system, counterKey, next) {
+  const counters = system._snapshot._nextActorIds;
+  if ((counters[counterKey] ?? 0) >= next) {
+    return;
+  }
+  // Copy-on-write: snapshot systems share this record by shallow `_snapshot`
+  // copies, so branches must not observe each other's allocations.
+  system._snapshot._nextActorIds = {
+    ...counters,
+    [counterKey]: next
+  };
+  markSystemSnapshotDirty(system);
+}
+
 /** @internal */
-function resolveActorId(system, requestedId) {
+function resolveActorId(system, requestedId, options) {
   if (requestedId !== undefined) {
-    const match = /^x:(\d+)$/.exec(requestedId);
-    const reservedId = match ? Number(match[1]) : undefined;
-    if (reservedId !== undefined && Number.isSafeInteger(reservedId)) {
-      const nextActorId = Math.max(system._snapshot._nextActorId, reservedId + 1);
-      if (nextActorId !== system._snapshot._nextActorId) {
-        system._snapshot._nextActorId = nextActorId;
-        markSystemSnapshotDirty(system);
-      }
+    const generated = parseGeneratedActorId(requestedId);
+    if (generated) {
+      bumpActorIdCounter(system, getActorIdCounterKey(options?.parent, generated.prefix), generated.index + 1);
+    } else if (!options?.parent) {
+      // Reserve a restored root's bare name so a later parentless actor of
+      // the same logic in this system numbers past it.
+      bumpActorIdCounter(system, getActorIdCounterKey(undefined, requestedId), 1);
     }
     return requestedId;
   }
-  const id = `x:${system._snapshot._nextActorId++}`;
-  markSystemSnapshotDirty(system);
-  return id;
+  const prefix = getActorIdPrefix(options?.src);
+  const counterKey = getActorIdCounterKey(options?.parent, prefix);
+  const counter = system._snapshot._nextActorIds[counterKey] ?? 0;
+  bumpActorIdCounter(system, counterKey, counter + 1);
+  // The first parentless actor of a logic gets the logic's own name; later
+  // parentless actors of the same logic in a shared system get numbered so
+  // addresses stay unique.
+  return !options?.parent && prefix !== 'x' && counter === 0 ? prefix : `${prefix}:${counter}`;
 }
 
 /** @internal */
@@ -3721,10 +4306,18 @@ function bookSessionId(system) {
 /**
  * Runtime operations used to execute effects.
  *
- * An external interpreter can override these operations while the default actor
- * system provides the local in-memory implementation.
+ * XState calculates pure transitions; a runtime executes their effects. The
+ * built-in local runtime is one implementation at the same level as any
+ * other: install a different one via `system.runtime` (for durable hosts,
+ * through `createDurable`'s adapter runtime operations).
  */
 
+/** @internal Every operation of `ActorSystemRuntime`, for runtime wrappers. */
+const RUNTIME_OPERATIONS = ['spawnActor', 'startActor', 'stopActor', 'terminateActor', 'emitEvent', 'scheduleTimer', 'cancelTimer', 'cancelAllTimers', 'deadLetter'
+// `runStep` and `sendEvent` are deliberately absent: durable executions
+// wire them separately, since a step awaits other runtime operations and
+// root-addressed sends are captured per batch.
+];
 const emptyScheduledTimers = Object.freeze({});
 function createScheduledTimerId(actor, id) {
   return `${actor.sessionId}.${id}`;
@@ -3785,7 +4378,10 @@ class RuntimeSystem {
     this.createActorRef = options.createActorRef;
     this._snapshot = {
       _scheduledTimers: restoredSnapshot?.scheduler ?? emptyScheduledTimers,
-      _nextActorId: restoredSnapshot?._nextActorId ?? 0
+      // System-level counters are process-local backstops; per-actor
+      // counters persist on each machine snapshot, and restored explicit ids
+      // reserve their numbering here via `resolveActorId`.
+      _nextActorIds: {}
     };
   }
 
@@ -3869,16 +4465,7 @@ class RuntimeSystem {
   // Delivers an event to the target actor. Used by both `_relay` (which also
   // records the send) and the scheduler's timer (which already recorded it).
   _deliver(source, target, event) {
-    const runtimeTarget = target;
-    const targetMachine = runtimeTarget.logic;
-    const isInternalEvent = typeof targetMachine?.isInternalEventType === 'function' && targetMachine.isInternalEventType(event.type);
-    if (isInternalEvent && source !== target) {
-      throw new Error(`Internal event "${event.type}" cannot be sent to actor "${target.id}" from outside.`);
-    }
-
-    // remember the last source for unified transition inspect event
-    runtimeTarget._lastSourceRef = source;
-    target._send(event);
+    deliverEvent(source, target, event);
   }
   _register(sessionId, actor) {
     if (actor === this._rootActor) {
@@ -3891,11 +4478,13 @@ class RuntimeSystem {
   }
   _unregister(actor) {
     let changed;
+    // Remote handles have no sessionId and are never in the session map;
+    // their registry cleanup happens through the keyed-actor path below.
     if (actor === this._rootActor) {
       changed = this._getRootActor() !== undefined;
-      changed = (this._children?.delete(actor.sessionId) ?? false) || changed;
+      changed = actor.sessionId !== undefined && (this._children?.delete(actor.sessionId) ?? false) || changed;
     } else {
-      changed = this._children?.delete(actor.sessionId) ?? false;
+      changed = actor.sessionId !== undefined && (this._children?.delete(actor.sessionId) ?? false);
     }
     const registryKey = this._reverseKeyedActors?.get(actor);
     if (registryKey !== undefined) {
@@ -3948,37 +4537,109 @@ class RuntimeSystem {
     };
     this._inspectionObservers.forEach(observer => observer.next?.(resolvedInspectionEvent));
   }
-  spawnActor() {}
+
+  // Unlike the other operations, spawn has no local work: local actors
+  // register with the system when they are constructed, so this only
+  // notifies a host runtime.
+  spawnActor(source, actor) {
+    return this.runtime?.spawnActor?.(source, actor);
+  }
   startActor(actor) {
+    const override = this.runtime?.startActor;
+    if (override) {
+      return override(actor);
+    }
     actor.start();
   }
   stopActor(actor) {
-    actor._stop();
+    const override = this.runtime?.stopActor;
+    if (override) {
+      return override(actor);
+    }
+    stopActor(actor);
   }
   terminateActor(actor, termination) {
-    actor._terminate(termination);
+    const override = this.runtime?.terminateActor;
+    if (override) {
+      return override(actor, termination);
+    }
+    terminateActor(actor, termination);
   }
   sendEvent(source, target, event) {
+    // Record for the inspection `sent[]` facet regardless of which runtime
+    // delivers, so host runtimes keep inspection parity.
     this._recordSent(source, target, event);
+    const override = this.runtime?.sendEvent;
+    if (override) {
+      return override(source, target, event);
+    }
     this._deliver(source, target, event);
   }
   emitEvent(source, event) {
+    const override = this.runtime?.emitEvent;
+    if (override) {
+      return override(source, event);
+    }
     source._emit(event);
   }
+  deadLetter(source, target, event, reason) {
+    this._sendInspectionEvent({
+      type: '@xstate.deadletter',
+      actorRef: target,
+      sourceRef: source,
+      event,
+      reason
+    });
+    const override = this.runtime?.deadLetter;
+    if (override) {
+      return override(source, target, event, reason);
+    }
+    {
+      console.warn(`Event "${event.type}" to actor "${target.id}" was not delivered (${reason}).`);
+    }
+  }
+  runStep(actor, key, exec) {
+    const override = this.runtime?.runStep;
+    if (override) {
+      return override(actor, key, exec);
+    }
+    return runStep(actor, key, exec);
+  }
   scheduleTimer(source, id, delay) {
+    const override = this.runtime?.scheduleTimer;
+    if (override) {
+      // The local scheduler records delayed sends for inspection inside
+      // `schedule`; keep that parity for host runtimes.
+      const timer = source.getSnapshot()?.timers?.[id];
+      if (timer) {
+        const target = timer.target === 'self' ? source : timer.target;
+        this._recordSent(source, target, timer.event, delay, id);
+      }
+      return override(source, id, delay);
+    }
     this.schedule(source, id, delay);
   }
   cancelTimer(source, id) {
+    const override = this.runtime?.cancelTimer;
+    if (override) {
+      return override(source, id);
+    }
     this.cancel(source, id);
   }
   cancelAllTimers(source) {
+    const override = this.runtime?.cancelAllTimers;
+    if (override) {
+      return override(source);
+    }
     this.cancelAll(source);
   }
   _relay(source, target, event) {
     if (transitionEffectTargets.length && transitionEffectTargets.includes(target)) {
       throw transitionEffectSignal;
     }
-    this.sendEvent(source, target, event);
+    // Returned so callers that can observe a host runtime's asynchronous
+    // delivery do; the built-in runtime delivers synchronously.
+    return this.sendEvent(source, target, event);
   }
   getSnapshot() {
     return {
@@ -4014,7 +4675,12 @@ function createRuntimeSystem(rootActor, options) {
 // oxlint-enable no-unused-vars
 
 let executingCustomAction = false;
-const $$ACTOR_TYPE = 1;
+
+/**
+ * Marks a serialized object as an actor reference (`xstate$type` in JSON
+ * output and persisted context).
+ */
+const ACTOR_REF_TYPE = 'actorRef';
 const emptyInspectionRecords = Object.freeze([]);
 
 // those values are currently used by @xstate/react directly so it's important to keep the assigned values in sync
@@ -4065,6 +4731,23 @@ function createActorRef(logic, options) {
  * or read snapshots.
  */
 class Actor {
+  /**
+   * The deterministic logical address of this actor within its system: the
+   * `/`-joined path of actor ids from the root. Stable across persistence and
+   * restore, unlike `sessionId`, which identifies one incarnation.
+   *
+   * `/` separates segments, so an id containing one (a state name with a
+   * slash reaches its invoked child's id) is percent-encoded to keep the
+   * path unambiguous.
+   */
+  get address() {
+    // `id` and `_parent` never change after construction, so the whole chain
+    // memoizes to O(1) amortized.
+    return this._address ??= this._parent ? `${this._parent.address}/${encodeAddressSegment(this.id)}` : encodeAddressSegment(this.id);
+  }
+
+  /** The system to which this actor belongs. */
+
   get trigger() {
     return this._trigger ??= new Proxy({}, {
       get: (_, eventType) => {
@@ -4127,7 +4810,7 @@ class Actor {
     this.registryKey = void 0;
     /** The globally unique process ID for this invocation. */
     this.sessionId = void 0;
-    /** The system to which this actor belongs. */
+    this._address = void 0;
     this.system = void 0;
     this._trigger = void 0;
     this._boundSend = void 0;
@@ -4162,7 +4845,10 @@ class Actor {
       this.system.inspect(toObserver(inspect));
     }
     this.sessionId = resolvedOptions._sessionId ?? bookSessionId(this.system);
-    this.id = resolveActorId(this.system, id);
+    this.id = resolveActorId(this.system, id, {
+      parent,
+      src: resolvedOptions.src ?? logic
+    });
     this.logger = options?.logger ?? this.system._logger;
     this.clock = options?.clock ?? this.system._clock;
     this._parent = parent;
@@ -4630,8 +5316,20 @@ class Actor {
     }
     if (this._restored) {
       const timers = this._snapshot.timers ?? {};
+      // startedAt is only persisted from — and only meaningful under — the
+      // wall clock; a custom clock (a simulated clock, a monotonic counter)
+      // restores every timer with its declared delay. The clamp bounds
+      // remaining time by the declared delay in case the wall clock moved
+      // backwards between persist and restore.
+      const wallClock = !this.system._clock.now;
+      const now = Date.now();
       for (const timer of Object.values(timers)) {
-        this.system.scheduleTimer(this, timer.id, timer.delay);
+        // A timer persisted from a live runtime carries its wall-clock start;
+        // honor the absolute deadline instead of restarting the full delay.
+        // Without a start (a pure-transition snapshot, or an older snapshot)
+        // the declared delay is all there is.
+        const delay = wallClock && timer.startedAt !== undefined ? Math.min(timer.delay, Math.max(0, timer.startedAt + timer.delay - now)) : timer.delay;
+        this.system.scheduleTimer(this, timer.id, delay);
       }
       this._restored = false;
     }
@@ -4791,13 +5489,7 @@ class Actor {
   /** @internal */
   _send(event) {
     if (this._processingStatus === ProcessingStatus.Stopped) {
-      // do nothing
-      {
-        // TODO: circular serialization issues
-        // const eventString = ''; //JSON.stringify(event);
-
-        console.warn(`Event "${event.type}" was sent to stopped actor "${this.id} (${this.sessionId})". This actor has already reached its final state, and will not transition.`);
-      }
+      this.system.deadLetter(this._lastSourceRef, this, event, 'stopped');
       return;
     }
     let mailbox = this.mailbox;
@@ -4822,10 +5514,17 @@ class Actor {
     }
     this.system._relay(undefined, this, event);
   }
+
+  /**
+   * Returns the actor's serializable logical identity: its `id`, `address`,
+   * and registered source key (when the actor was created from one).
+   */
   toJSON() {
     return {
-      xstate$$type: $$ACTOR_TYPE,
-      id: this.id
+      xstate$type: ACTOR_REF_TYPE,
+      id: this.id,
+      address: this.address,
+      src: typeof this.src === 'string' ? this.src : undefined
     };
   }
 
@@ -4854,10 +5553,16 @@ class Actor {
    * Read an actor’s snapshot synchronously.
    *
    * @remarks
-   * The snapshot represent an actor's last emitted value.
+   * The snapshot is the last value the actor published, not a query of its
+   * private state: the actor emits a snapshot when it transitions, and this
+   * returns that cached last emission. The read is coherent within one
+   * synchronous transition turn because event processing runs to completion;
+   * across asynchronous boundaries it may be stale, like any observed value.
    *
-   * When an actor receives an event, its internal state may change. An actor
-   * may emit a snapshot when a state transition occurs.
+   * Only co-located actors publish full snapshots. A location-transparent
+   * remote handle exposes lifecycle only ({ status, output?, error? }): while
+   * the handle exists among its parent's children the child is presumed
+   * `active`, and its terminal result arrives as a completion event.
    *
    * Note that some actors, such as callback actors generated with
    * `createCallbackLogic`, will not emit snapshots.
@@ -4914,14 +5619,21 @@ function createActor(logic, options) {
   return new Actor(logic, options);
 }
 
-exports.$$ACTOR_TYPE = $$ACTOR_TYPE;
+exports.ACTOR_REF_TYPE = ACTOR_REF_TYPE;
 exports.Actor = Actor;
 exports.NULL_EVENT = NULL_EVENT;
+exports.RUNTIME_OPERATIONS = RUNTIME_OPERATIONS;
 exports.STATE_DELIMITER = STATE_DELIMITER;
 exports.XSTATE_INIT = XSTATE_INIT;
+exports.XSTATE_LOGIC_EFFECT_REJECT = XSTATE_LOGIC_EFFECT_REJECT;
+exports.XSTATE_LOGIC_EFFECT_RESOLVE = XSTATE_LOGIC_EFFECT_RESOLVE;
+exports.XSTATE_LOGIC_EFFECT_START = XSTATE_LOGIC_EFFECT_START;
 exports.XSTATE_STOP = XSTATE_STOP;
 exports.XSTATE_TIMER = XSTATE_TIMER;
+exports.allocateChildId = allocateChildId;
+exports.assertChildIdFree = assertChildIdFree;
 exports.attachSnapshotActorRef = attachSnapshotActorRef;
+exports.beginSpawnAllocation = beginSpawnAllocation;
 exports.builtInActions = builtInActions;
 exports.checkStateIn = checkStateIn;
 exports.cloneMachineSnapshot = cloneMachineSnapshot;
@@ -4936,16 +5648,20 @@ exports.createInvokeTimeoutEvent = createInvokeTimeoutEvent;
 exports.createInvokeTimeoutEventId = createInvokeTimeoutEventId;
 exports.createListenerLogic = createListenerLogic;
 exports.createMachineSnapshot = createMachineSnapshot;
+exports.createRemoteActorRef = createRemoteActorRef;
 exports.createSendToEffect = createSendToEffect;
 exports.createSpawnEffect = createSpawnEffect;
 exports.createSubscriptionLogic = createSubscriptionLogic;
 exports.createTransitionEnqueue = createTransitionEnqueue;
+exports.deliverEvent = deliverEvent;
 exports.deriveDeferredStarts = deriveDeferredStarts;
+exports.encodeAddressSegment = encodeAddressSegment;
 exports.evaluateCandidate = evaluateCandidate;
 exports.executeEffects = executeEffects;
 exports.finalizeTransitionResult = finalizeTransitionResult;
 exports.formatRouteTransitions = formatRouteTransitions;
 exports.formatTransition = formatTransition;
+exports.getActorIdPrefix = getActorIdPrefix;
 exports.getAllOwnEventDescriptors = getAllOwnEventDescriptors;
 exports.getAllOwnEvents = getAllOwnEvents;
 exports.getAllStateNodes = getAllStateNodes;
@@ -4956,6 +5672,8 @@ exports.getInitialSnapshot = getInitialSnapshot;
 exports.getNextSnapshot = getNextSnapshot;
 exports.getPersistedSnapshot = getPersistedSnapshot;
 exports.getProperAncestors = getProperAncestors;
+exports.getRootActorId = getRootActorId;
+exports.getSnapshotActorRef = getSnapshotActorRef;
 exports.getStateNodeByPath = getStateNodeByPath;
 exports.getStateNodes = getStateNodes;
 exports.getTransitionResult = getTransitionResult;
@@ -4975,14 +5693,21 @@ exports.matchesActorSession = matchesActorSession;
 exports.matchesEvent = matchesEvent;
 exports.matchesEventDescriptor = matchesEventDescriptor;
 exports.matchesState = matchesState;
+exports.mergeActorIdCounters = mergeActorIdCounters;
 exports.parseDelayToMilliseconds = parseDelayToMilliseconds;
+exports.parseGeneratedActorId = parseGeneratedActorId;
 exports.pathToStateValue = pathToStateValue;
+exports.reserveChildId = reserveChildId;
 exports.resolveActionsWithContext = resolveActionsWithContext;
 exports.resolveReferencedActor = resolveReferencedActor;
 exports.resolveStateValue = resolveStateValue;
+exports.runStep = runStep;
 exports.setInertActorScopeSnapshot = setInertActorScopeSnapshot;
 exports.setSnapshotActorRef = setSnapshotActorRef;
+exports.stopActor = stopActor;
 exports.subscriptionLogic = subscriptionLogic;
+exports.takeSpawnAllocationCounters = takeSpawnAllocationCounters;
+exports.terminateActor = terminateActor;
 exports.toArray = toArray;
 exports.toObserver = toObserver;
 exports.toStatePath = toStatePath;