xstate 6.0.0-alpha.21 → 6.0.0-alpha.22

package/dist/{index-d39fb138.development.esm.js → index-44d8c2d1.development.esm.js}

@@ -54,6 +54,8 @@ const XSTATE_INIT = '@xstate.init';
 const XSTATE_START = '@xstate.start';
 const XSTATE_SPAWN = '@xstate.spawn';
 const XSTATE_STOP = '@xstate.stop';
+const XSTATE_TERMINATE = '@xstate.terminate';
+const XSTATE_TIMER = 'xstate.timer';
 
 /**
  * Returns an event that represents an implicit event that is sent after the
@@ -158,34 +160,40 @@ function reportUnhandledError(err) {
 
 const symbolObservable = (() => typeof Symbol === 'function' && Symbol.observable || '@@observable')();
 
+function assertSendToEvent(event) {
+  if (typeof event === 'string') {
+    throw new Error(// eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+    `Only event objects may be used with sendTo; use sendTo({ type: "${event}" }) instead` );
+  }
+}
 const builtInActions = {
-  // No-op: creation/registration are eager and pure; the start is a separate
-  // deferred `@xstate.start` effect (see `deriveDeferredStarts`).
-  ['@xstate.spawn']: _actor => {},
+  // Actor refs are created while resolving the next snapshot. Starting is a
+  // separate deferred effect so the returned list remains execution-complete.
+  ['@xstate.spawn']: actor => {
+    return actor.system.spawnActor(actor._parent, actor);
+  },
   ['@xstate.start']: actor => {
-    actor.start();
+    return actor.system.startActor(actor);
   },
-  ['@xstate.raise']: (actorScope, event, options) => {
-    actorScope.system.scheduler.schedule(actorScope.self, actorScope.self, event, options?.delay ?? 0, options?.id);
+  ['@xstate.raise']: (actorScope, _event, options) => {
+    return actorScope.system.scheduleTimer(actorScope.self, options.id, options?.delay ?? 0);
   },
   ['@xstate.sendTo']: (actorScope, actor, event, options) => {
-    if (typeof event === 'string') {
-      throw new Error(// eslint-disable-next-line @typescript-eslint/restrict-template-expressions
-      `Only event objects may be used with sendTo; use sendTo({ type: "${event}" }) instead` );
-    }
+    assertSendToEvent(event);
     if (options?.delay !== undefined) {
-      actorScope.system.scheduler.schedule(actorScope.self, actor, event, options?.delay ?? 0, options?.id);
+      return actorScope.system.scheduleTimer(actorScope.self, options.id, options?.delay ?? 0);
     } else {
-      actorScope.defer(() => {
-        actorScope.system._relay(actorScope.self, actor, event);
-      });
+      return actorScope.system._relay(actorScope.self, actor, event);
     }
   },
   ['@xstate.cancel']: (actorScope, sendId) => {
-    actorScope.system.scheduler.cancel(actorScope.self, sendId);
+    return actorScope.system.cancelTimer(actorScope.self, sendId);
   },
   ['@xstate.stop']: (actorScope, actor) => {
-    actorScope.stopChild(actor);
+    return actorScope.system.stopActor(actor);
+  },
+  ['@xstate.terminate']: (actor, termination) => {
+    return actor.system.terminateActor(actor, termination);
   }
 };
 
@@ -349,12 +357,109 @@ function createSubscriptionLogic() {
 // Singleton logic instance
 const subscriptionLogic = /* #__PURE__ */createSubscriptionLogic();
 
-const builtInExecutableAction = Symbol('xstate.builtInExecutableAction');
-function brandBuiltInExecutableAction(action) {
-  Object.defineProperty(action, builtInExecutableAction, {
-    value: true
-  });
-  return action;
+function execCustomEffect() {
+  return this.action?.(...this.args);
+}
+function execEmitEffect(runtime = this.source.system) {
+  return runtime.emitEvent(this.source, this.event);
+}
+
+/** @internal Creates an emitted-event effect. */
+function createEmitEffect(actorScope, event) {
+  return {
+    kind: 'emit',
+    exec: execEmitEffect,
+    type: event.type,
+    source: actorScope.self,
+    event,
+    params: undefined,
+    args: []
+  };
+}
+
+/** @internal Creates a directly executable user effect. */
+function createCustomEffect(type, action, params) {
+  return {
+    kind: 'action',
+    exec: action,
+    type,
+    action: action,
+    params,
+    args: []
+  };
+}
+function execSpawnEffect(runtime = this.actor.system) {
+  return runtime.spawnActor(this.source, this.actor);
+}
+function execStartEffect(runtime = this.actor.system) {
+  return runtime.startActor(this.actor);
+}
+function execStopEffect(runtime = this.source.system) {
+  return runtime.stopActor(this.actor);
+}
+function execTerminateEffect(runtime = this.actor.system) {
+  const termination = this.status === 'done' ? {
+    status: 'done',
+    output: this.output,
+    error: undefined
+  } : {
+    status: 'error',
+    output: undefined,
+    error: this.error
+  };
+  return runtime.terminateActor(this.actor, termination);
+}
+function execRaiseEffect(runtime = this.source.system) {
+  return runtime.scheduleTimer(this.source, this.id, this.delay ?? 0);
+}
+function execSendToEffect(runtime = this.source.system) {
+  assertSendToEvent(this.event);
+  if (this.delay !== undefined) {
+    return runtime.scheduleTimer(this.source, this.id, this.delay);
+  }
+  return runtime.sendEvent(this.source, this.target, this.event);
+}
+function execCancelEffect(runtime = this.source.system) {
+  return runtime.cancelTimer(this.source, this.id);
+}
+function updateLogicalTimers(snapshot, effect, actorScope) {
+  if (!isBuiltInExecutableAction(effect)) {
+    return snapshot;
+  }
+  if (effect.type === '@xstate.cancel') {
+    if (!snapshot.timers?.[effect.id]) {
+      return snapshot;
+    }
+    const timers = {
+      ...snapshot.timers
+    };
+    delete timers[effect.id];
+    return {
+      ...snapshot,
+      timers
+    };
+  }
+  if (effect.type !== '@xstate.raise' && effect.type !== '@xstate.sendTo' || effect.delay === undefined) {
+    return snapshot;
+  }
+  let nextTimerId = snapshot._nextTimerId ?? 0;
+  const id = effect.id ?? `xstate.timer.auto.${nextTimerId++}`;
+  effect.id = id;
+  const target = effect.type === '@xstate.raise' || effect.target === actorScope.self ? 'self' : effect.target;
+  return {
+    ...snapshot,
+    timers: {
+      ...snapshot.timers,
+      [id]: {
+        id,
+        delay: effect.delay,
+        type: effect.type,
+        event: effect.event,
+        target
+      }
+    },
+    _nextTimerId: nextTimerId
+  };
 }
 function mergeContextPatch(context, patch) {
   return {
@@ -363,43 +468,55 @@ function mergeContextPatch(context, patch) {
   };
 }
 function pushBuiltInAction(actions, action, ...args) {
-  actions.push({
+  const actionRecord = {
     action,
     args
-  });
+  };
+  actions.push(actionRecord);
+  return actionRecord;
 }
-function registerSpawnedChild(actor, id) {
-  return Object.assign(function registerChild(args) {
+function applyChildUpdate(snapshot, update, actorScope) {
+  if (update.type === 'add') {
     return {
+      ...snapshot,
       children: {
-        ...args.children,
-        [id]: actor
+        ...snapshot.children,
+        [update.id]: update.actor
       }
     };
-  }, {
-    _special: true
-  });
-}
-function unregisterChild(actor) {
-  return Object.assign(function removeChild(args) {
-    const children = {
-      ...args.children
-    };
-    for (const key of Object.keys(children)) {
-      if (children[key] === actor) {
-        delete children[key];
-      }
+  }
+  const children = {
+    ...snapshot.children
+  };
+  let owned = update.actor._parent === actorScope.self;
+  for (const key of Object.keys(children)) {
+    if (children[key] === update.actor) {
+      owned = true;
+      delete children[key];
     }
-    return {
-      children
-    };
-  }, {
-    _special: true
-  });
+  }
+  if (!owned) {
+    throw new Error(`Cannot stop child actor ${update.actor.id} of ${actorScope.self.id} because it is not a child` );
+  }
+  actorScope.system._unregister(update.actor);
+  return {
+    ...snapshot,
+    children
+  };
+}
+function getTransitionActionRecord(action) {
+  if (typeof action === 'object' && action !== null && 'action' in action && typeof action.action === 'function') {
+    return action;
+  }
+  return undefined;
 }
 function pushSpawnedChild(actions, actor, id) {
-  pushBuiltInAction(actions, builtInActions['@xstate.spawn'], actor);
-  actions.push(registerSpawnedChild(actor, id ?? actor.id));
+  const action = pushBuiltInAction(actions, builtInActions['@xstate.spawn'], actor);
+  action.childUpdate = {
+    type: 'add',
+    actor,
+    id: id ?? actor.id
+  };
 }
 function createTransitionEnqueue(actorScope, actions, internalEvents, actorSubscriptions = false, createActors = true) {
   const props = {
@@ -429,7 +546,7 @@ function createTransitionEnqueue(actorScope, actions, internalEvents, actorSubsc
           id: options?.id ?? options?.registryKey ?? logic.id
         };
       }
-      const actor = createActor(logic, {
+      const actor = actorScope.system.createActorRef(logic, {
         ...options,
         parent: actorScope.self
       });
@@ -448,8 +565,11 @@ function createTransitionEnqueue(actorScope, actions, internalEvents, actorSubsc
     },
     stop: actor => {
       if (actor) {
-        pushBuiltInAction(actions, builtInActions['@xstate.stop'], actorScope, actor);
-        actions.push(unregisterChild(actor));
+        const action = pushBuiltInAction(actions, builtInActions['@xstate.stop'], actorScope, actor);
+        action.childUpdate = {
+          type: 'remove',
+          actor
+        };
       }
     }
   };
@@ -461,7 +581,7 @@ function createTransitionEnqueue(actorScope, actions, internalEvents, actorSubsc
           eventType,
           mapper
         };
-        const listenerActor = createActor(listenerLogic, {
+        const listenerActor = actorScope.system.createActorRef(listenerLogic, {
           input,
           parent: actorScope.self
         });
@@ -476,7 +596,7 @@ function createTransitionEnqueue(actorScope, actions, internalEvents, actorSubsc
           actor,
           mappers: normalizedMappers
         };
-        const subscriptionActor = createActor(subscriptionLogic, {
+        const subscriptionActor = actorScope.system.createActorRef(subscriptionLogic, {
           input,
           parent: actorScope.self
         });
@@ -495,6 +615,9 @@ function getBuiltInActionFields(action, args) {
       {
         const [actor] = args;
         return {
+          kind: 'builtin',
+          exec: execSpawnEffect,
+          source: actor._parent,
           actor,
           id: actor.id,
           logic: actor.logic,
@@ -506,6 +629,9 @@ function getBuiltInActionFields(action, args) {
       {
         const [, event, options] = args;
         return {
+          kind: 'builtin',
+          exec: execRaiseEffect,
+          source: args[0].self,
           event,
           id: options?.id,
           delay: options?.delay
@@ -515,6 +641,9 @@ function getBuiltInActionFields(action, args) {
       {
         const [, target, event, options] = args;
         return {
+          kind: 'builtin',
+          exec: execSendToEffect,
+          source: args[0].self,
           target,
           event,
           id: options?.id,
@@ -525,6 +654,9 @@ function getBuiltInActionFields(action, args) {
       {
         const [, id] = args;
         return {
+          kind: 'builtin',
+          exec: execCancelEffect,
+          source: args[0].self,
           id
         };
       }
@@ -532,7 +664,11 @@ function getBuiltInActionFields(action, args) {
       {
         const [, actor] = args;
         return {
-          actor
+          kind: 'builtin',
+          exec: execStopEffect,
+          source: args[0].self,
+          actor,
+          id: actor.id
         };
       }
     default:
@@ -540,19 +676,91 @@ function getBuiltInActionFields(action, args) {
   }
 }
 function createStartEffect(actor) {
-  const action = builtInActions['@xstate.start'];
   const args = [actor];
-  return brandBuiltInExecutableAction({
+  return {
+    kind: 'builtin',
+    exec: execStartEffect,
     type: XSTATE_START,
-    params: {
-      action,
-      args
-    },
+    source: actor._parent,
+    params: undefined,
     args,
-    exec: action.bind(null, actor),
     actor,
     id: actor.id
-  });
+  };
+}
+function createSpawnEffect(actor) {
+  const args = [actor];
+  return {
+    kind: 'builtin',
+    exec: execSpawnEffect,
+    type: XSTATE_SPAWN,
+    source: actor._parent,
+    params: undefined,
+    args,
+    actor,
+    id: actor.id,
+    logic: actor.logic,
+    src: actor.src,
+    input: actor.options?.input
+  };
+}
+
+/** @internal Creates an immediate actor-to-actor delivery effect. */
+function createSendToEffect(actorScope, target, event) {
+  const args = [actorScope, target, event, {}];
+  return {
+    kind: 'builtin',
+    exec: execSendToEffect,
+    type: '@xstate.sendTo',
+    source: actorScope.self,
+    target,
+    event,
+    id: undefined,
+    delay: undefined,
+    params: undefined,
+    args
+  };
+}
+
+/** @internal Creates the terminal lifecycle effect for an actor. */
+function createTerminationEffect(actorScope, snapshot) {
+  if (snapshot.status !== 'done' && snapshot.status !== 'error') {
+    throw new Error('Cannot terminate an active or stopped actor');
+  }
+  const termination = snapshot.status === 'done' ? {
+    status: 'done',
+    output: snapshot.output,
+    error: undefined
+  } : {
+    status: 'error',
+    output: undefined,
+    error: snapshot.error
+  };
+  const args = [actorScope.self, termination];
+  return {
+    kind: 'builtin',
+    exec: execTerminateEffect,
+    type: XSTATE_TERMINATE,
+    source: actorScope.self,
+    actor: actorScope.self,
+    id: actorScope.self.id,
+    ...termination,
+    params: undefined,
+    args
+  };
+}
+
+/**
+ * Ensures that a newly terminal snapshot has exactly one ordered actor
+ * termination effect.
+ *
+ * @internal
+ */
+function finalizeTransitionResult(actorScope, previousSnapshot, [nextSnapshot, effects]) {
+  const becameTerminal = nextSnapshot.status === 'done' || nextSnapshot.status === 'error';
+  const wasTerminal = previousSnapshot?.status === 'done' || previousSnapshot?.status === 'error';
+  const hasTerminationEffect = effects.some(effect => typeof effect === 'object' && effect !== null && 'type' in effect && effect.type === XSTATE_TERMINATE);
+  return becameTerminal && !wasTerminal && !hasTerminationEffect ? [nextSnapshot, [...effects, createTerminationEffect(actorScope, nextSnapshot)]] : [nextSnapshot, effects];
 }
 
 /**
@@ -581,14 +789,19 @@ function deriveDeferredStarts(effects) {
   return [...attachedStarts, ...childStarts];
 }
 function isBuiltInExecutableAction(action) {
-  return action[builtInExecutableAction] === true;
+  return action.kind === 'builtin';
+}
+
+/** Executes transition effects sequentially, awaiting each runtime operation. */
+async function executeEffects(effects, runtime) {
+  for (const effect of effects) {
+    await effect.exec(runtime);
+  }
 }
 function resolveActionsWithContext(currentSnapshot, event, actorScope, actions) {
   let intermediateSnapshot = currentSnapshot;
   const executableActions = [];
   for (const action of actions) {
-    const isInline = typeof action === 'function';
-    const resolvedAction = isInline ? action : typeof action === 'object' && 'action' in action && typeof action.action === 'function' ? action.action.bind(null, ...action.args) : false;
     const actionArgs = {
       context: intermediateSnapshot.context,
       event,
@@ -600,20 +813,29 @@ function resolveActionsWithContext(currentSnapshot, event, actorScope, actions)
       actions: currentSnapshot.machine.implementations.actions,
       actorSources: currentSnapshot.machine.implementations.actorSources
     };
+    const isInline = typeof action === 'function';
+    const actionRecord = getTransitionActionRecord(action);
+    const resolvedAction = isInline ? action : actionRecord ? actionRecord.action.bind(null, ...actionRecord.args) : false;
     let actionParams = undefined;
     if (typeof action === 'object' && action !== null) {
       const {
         type: _,
+        childUpdate: _childUpdate,
         ...emittedEventParams
       } = action;
       actionParams = emittedEventParams;
     }
+    if (actionRecord?.childUpdate) {
+      intermediateSnapshot = applyChildUpdate(intermediateSnapshot, actionRecord.childUpdate, actorScope);
+    }
     if (resolvedAction && '_special' in resolvedAction) {
       executableActions.push({
+        kind: 'action',
+        exec: execCustomEffect,
         type: typeof action === 'object' ? 'action' in action && typeof action.action === 'function' ? action.action.name ?? '(anonymous)' : action.type ?? '(anonymous)' : action.name || '(anonymous)',
         params: actionParams,
         args: [],
-        exec: undefined
+        action: undefined
       });
       const specialAction = resolvedAction;
       const res = specialAction(actionArgs, emptyEnqueueObject);
@@ -635,14 +857,26 @@ function resolveActionsWithContext(currentSnapshot, event, actorScope, actions)
     }
     if (!resolvedAction || !('resolve' in resolvedAction)) {
       const builtInFields = typeof action === 'object' && action !== null && 'action' in action && typeof action.action === 'function' ? getBuiltInActionFields(action.action, action.args) : undefined;
+      const isEmittedEvent = typeof action === 'object' && action !== null && !actionRecord;
       const executableAction = {
+        kind: builtInFields ? 'builtin' : isEmittedEvent ? 'emit' : 'action',
         type: typeof action === 'object' ? 'action' in action && typeof action.action === 'function' ? action.action.name ?? '(anonymous)' : action.type : action.name || '(anonymous)',
-        params: actionParams,
+        params: builtInFields ? undefined : actionParams,
         args: typeof action === 'object' && 'action' in action ? action.args : [],
-        exec: resolvedAction || (typeof action === 'object' && action !== null ? () => actorScope.defer(() => actorScope.emit(action)) : undefined),
+        ...(builtInFields ? {} : isEmittedEvent ? {
+          source: actorScope.self,
+          event: action
+        } : {
+          action: actionRecord?.action ?? (isInline ? action : undefined)
+        }),
+        ...(!builtInFields ? {
+          exec: isEmittedEvent ? execEmitEffect : execCustomEffect
+        } : {}),
         ...builtInFields
       };
-      executableActions.push(builtInFields ? brandBuiltInExecutableAction(executableAction) : executableAction);
+      const typedExecutableAction = executableAction;
+      intermediateSnapshot = updateLogicalTimers(intermediateSnapshot, typedExecutableAction, actorScope);
+      executableActions.push(typedExecutableAction);
       continue;
     }
   }
@@ -1432,6 +1666,17 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
       return [[wrappedAction], undefined, undefined];
     };
     let nextState = currentSnapshot;
+    const getInvokeStopActions = (stateNode, children) => {
+      const actions = [];
+      const enqueue = createTransitionEnqueue(actorScope, actions, []);
+      for (const invokeDef of stateNode.invoke) {
+        const child = children[invokeDef.id];
+        if (child) {
+          enqueue.stop(child);
+        }
+      }
+      return actions;
+    };
     const exitStates = () => {
       const statesToExit = computeExitSet(filteredTransitions, mutStateNodeSet, currentSnapshot, event, actorScope);
       statesToExit.sort((a, b) => b.order - a.order);
@@ -1453,7 +1698,7 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
       }
       for (const exitStateNode of statesToExit) {
         const stateInput = getStateInput(currentSnapshot, exitStateNode.id);
-        const [exitActions, nextContext, internalEvents] = exitStateNode.exit ? getStateActionsAndContext(exitStateNode.exit, nextState.context, currentSnapshot.children, stateInput) : [[]];
+        const [exitActions, nextContext, internalEvents] = exitStateNode.exit ? getStateActionsAndContext(exitStateNode.exit, nextState.context, currentSnapshot.children, stateInput) : [[], undefined, undefined];
         if (internalEvents?.length) {
           internalQueue.push(...internalEvents);
         }
@@ -1465,12 +1710,11 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
         const [resolvedState, resolvedActions] = resolveActionsWithContext(nextState, event, actorScope, exitActions);
         nextState = resolvedState;
         executableActions.push(...resolvedActions);
-        for (const def of exitStateNode.invoke) {
-          const childActor = nextState.children[def.id];
-          if (childActor && !childActor._isExternal) {
-            actorScope.stopChild(childActor);
-          }
-          delete nextState.children[def.id];
+        const invokeStopActions = getInvokeStopActions(exitStateNode, nextState.children);
+        if (invokeStopActions.length) {
+          const [stoppedState, stopEffects] = resolveActionsWithContext(nextState, event, actorScope, invokeStopActions);
+          nextState = stoppedState;
+          executableActions.push(...stopEffects);
         }
         mutStateNodeSet.delete(exitStateNode);
       }
@@ -1641,7 +1885,7 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
       }
       const completedNodes = new Set();
       const children = {
-        ...currentSnapshot.children
+        ...nextState.children
       };
       for (const stateNodeToEnter of [...statesToEnter].sort((a, b) => a.order - b.order)) {
         mutStateNodeSet.add(stateNodeToEnter);
@@ -1668,7 +1912,7 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
             event,
             output: getEventOutput(event)
           }) : invokeDef.input;
-          const actor = createActor(logic, {
+          const actor = actorScope.system.createActorRef(logic, {
             ...invokeDef,
             input,
             parent: actorScope.self,
@@ -1797,6 +2041,12 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
       const [resolvedState, resolvedActions] = resolveActionsWithContext(nextState, event, actorScope, allExitActions);
       nextState = resolvedState;
       executableActions.push(...resolvedActions);
+      const [stoppedState, stopEffects] = stopChildren(nextState, event, actorScope);
+      nextState = stoppedState;
+      executableActions.push(...stopEffects);
+      const [withoutTimers, cancelEffects] = cancelTimers(nextState, event, actorScope);
+      nextState = withoutTimers;
+      executableActions.push(...cancelEffects);
     }
     if (historyValue === currentSnapshot.historyValue && currentSnapshot._nodes.length === mutStateNodeSet.size && currentSnapshot._nodes.every(node => mutStateNodeSet.has(node))) {
       // If context was changed (e.g. by entry actions during self-transition),
@@ -1870,9 +2120,27 @@ function getTransitionResult(transition, snapshot, event, actorScope, options) {
     input: resolvedInput
   };
 }
-function macrostep(snapshot, event, actorScope, internalQueue) {
+function macrostep(snapshot, event, actorScope, internalQueue, initialMicrosteps = []) {
   let nextSnapshot = snapshot;
-  const microsteps = [];
+  const microsteps = initialMicrosteps.slice();
+  function completeMacrostep() {
+    const effects = microsteps.flatMap(([, actions]) => actions);
+    const starts = deriveDeferredStarts(effects);
+    const shouldTerminate = (snapshot.status === 'active' || initialMicrosteps.length > 0) && (nextSnapshot.status === 'done' || nextSnapshot.status === 'error');
+    if (starts.length || shouldTerminate) {
+      const terminalEffects = shouldTerminate ? [...starts, createTerminationEffect(actorScope, nextSnapshot)] : starts;
+      if (microsteps.length) {
+        const [lastSnapshot, lastEffects] = microsteps.at(-1);
+        microsteps[microsteps.length - 1] = [lastSnapshot, [...lastEffects, ...terminalEffects]];
+      } else {
+        microsteps.push([nextSnapshot, terminalEffects]);
+      }
+    }
+    return {
+      snapshot: nextSnapshot,
+      microsteps
+    };
+  }
   function addMicrostep(step, transitions) {
     // collect microsteps; surfaced on the enclosing '@xstate.transition' event
     // via its `microsteps[]` facet (there is no standalone microstep event)
@@ -1884,20 +2152,39 @@ function macrostep(snapshot, event, actorScope, internalQueue) {
 
   // Handle stop event
   if (event.type === XSTATE_STOP) {
-    nextSnapshot = cloneMachineSnapshot(stopChildren(nextSnapshot, actorScope), {
+    const [stoppedChildrenSnapshot, stopEffects] = stopChildren(nextSnapshot, event, actorScope);
+    const [withoutTimers, cancelEffects] = cancelTimers(stoppedChildrenSnapshot, event, actorScope);
+    nextSnapshot = cloneMachineSnapshot(withoutTimers, {
       status: 'stopped'
     });
-    addMicrostep([nextSnapshot, []], []);
-    return {
-      snapshot: nextSnapshot,
-      microsteps
-    };
+    addMicrostep([nextSnapshot, [...stopEffects, ...cancelEffects]], []);
+    return completeMacrostep();
   }
   let nextEvent = event;
+  if (event.type === XSTATE_TIMER) {
+    const timer = nextSnapshot.timers[event.id];
+    if (!timer) {
+      return completeMacrostep();
+    }
+    const timers = {
+      ...nextSnapshot.timers
+    };
+    delete timers[timer.id];
+    nextSnapshot = cloneMachineSnapshot(nextSnapshot, {
+      timers
+    });
+    if (timer.type === '@xstate.raise') {
+      internalQueue.push(timer.event);
+      addMicrostep([nextSnapshot, []], []);
+    } else {
+      const target = timer.target === 'self' ? actorScope.self : timer.target;
+      addMicrostep([nextSnapshot, [createSendToEffect(actorScope, target, timer.event)]], []);
+    }
+  }
 
   // Assume the state is at rest (no raised events)
   // Determine the next state based on the next microstep
-  if (nextEvent.type !== XSTATE_INIT) {
+  if (nextEvent.type !== XSTATE_INIT && nextEvent.type !== XSTATE_TIMER) {
     const currentEvent = nextEvent;
     const isErr = isErrorEvent(currentEvent);
     const transitions = nextSnapshot.machine.getTransitionData(nextSnapshot, currentEvent, actorScope.self);
@@ -1910,10 +2197,7 @@ function macrostep(snapshot, event, actorScope, internalQueue) {
         error: currentEvent.error
       });
       addMicrostep([nextSnapshot, []], []);
-      return {
-        snapshot: nextSnapshot,
-        microsteps
-      };
+      return completeMacrostep();
     }
     const step = microstep(transitions, snapshot, actorScope, nextEvent, false,
     // isInitial
@@ -1951,13 +2235,7 @@ function macrostep(snapshot, event, actorScope, internalQueue) {
     shouldSelectEventlessTransitions = nextSnapshot !== previousState;
     addMicrostep(step, enabledTransitions);
   }
-  if (nextSnapshot.status !== 'active' && nextSnapshot.children) {
-    stopChildren(nextSnapshot, actorScope);
-  }
-  return {
-    snapshot: nextSnapshot,
-    microsteps
-  };
+  return completeMacrostep();
 }
 
 /**
@@ -2017,17 +2295,29 @@ function transitionToHasEffect(transitionTo, context, event, snapshot, self, imp
   }
   return res !== undefined;
 }
-function stopChildren(snapshot, actorScope) {
+function stopChildren(snapshot, event, actorScope) {
   let children;
   if (!snapshot.children || (children = Object.values(snapshot.children).filter(Boolean)).length === 0) {
-    return snapshot;
+    return [snapshot, []];
   }
+  const actions = [];
+  const enqueue = createTransitionEnqueue(actorScope, actions, []);
   for (const child of children) {
-    actorScope.stopChild(child);
+    enqueue.stop(child);
   }
-  return cloneMachineSnapshot(snapshot, {
-    children: {}
-  });
+  return resolveActionsWithContext(snapshot, event, actorScope, actions);
+}
+function cancelTimers(snapshot, event, actorScope) {
+  const timerIds = Object.keys(snapshot.timers);
+  if (!timerIds.length) {
+    return [snapshot, []];
+  }
+  const actions = [];
+  const enqueue = createTransitionEnqueue(actorScope, actions, []);
+  for (const id of timerIds) {
+    enqueue.cancel(id);
+  }
+  return resolveActionsWithContext(snapshot, event, actorScope, actions);
 }
 function selectEventlessTransitions(snapshot, event, actorScope) {
   const enabledTransitionSet = new Set();
@@ -2072,6 +2362,129 @@ function evaluateCandidate(candidate, event, snapshot, stateNode, self) {
   return true;
 }
 
+/** @internal */
+const snapshotActorRef = Symbol('xstate.snapshotActorRef');
+
+/** Snapshot-scoped actor identity and system view. @internal */
+
+function getSnapshotChildren(snapshot) {
+  return 'children' in snapshot && snapshot.children ? snapshot.children : {};
+}
+
+/**
+ * Creates the isolated receptionist/id view used by a pure branch. Scheduling,
+ * relaying and clocks remain delegated to the snapshot's execution system.
+ *
+ * @internal
+ */
+function createSnapshotSystem(baseSystem, self, children, baseState) {
+  const registeredActors = new Map(baseState?.children ?? baseSystem.children);
+  const keyedActors = new Map(baseState?.keyedActors ?? Object.entries(baseSystem.getAll()).filter(entry => !!entry[1]));
+  const reverseKeyedActors = new WeakMap();
+  let booksSelf = true;
+  const system = {
+    ...baseSystem,
+    children: registeredActors,
+    keyedActors,
+    reverseKeyedActors,
+    _snapshot: {
+      ...(baseState?.snapshot ?? baseSystem._snapshot)
+    },
+    _bookId: () => {
+      if (booksSelf) {
+        booksSelf = false;
+        return self.sessionId ?? self.id;
+      }
+      return `x:${system._snapshot._nextActorId++}`;
+    },
+    _register: (sessionId, actor) => {
+      registeredActors.set(sessionId, actor);
+      return sessionId;
+    },
+    _unregister: actor => {
+      if (actor.sessionId) {
+        registeredActors.delete(actor.sessionId);
+      }
+      const registryKey = reverseKeyedActors.get(actor);
+      if (registryKey !== undefined && keyedActors.get(registryKey) === actor) {
+        keyedActors.delete(registryKey);
+      }
+      reverseKeyedActors.delete(actor);
+    },
+    _set: (registryKey, actor) => {
+      const existing = keyedActors.get(registryKey);
+      if (existing && existing !== actor) {
+        throw new Error(`Actor with registry key '${String(registryKey)}' already exists.`);
+      }
+      keyedActors.set(registryKey, actor);
+      reverseKeyedActors.set(actor, registryKey);
+    },
+    get: registryKey => keyedActors.get(registryKey),
+    getAll: () => Object.fromEntries(keyedActors),
+    // Pure transition resolution must not leak topology inspection events into
+    // a live runtime system.
+    _sendInspectionEvent: () => {}
+  };
+  for (const [registryKey, actor] of keyedActors) {
+    reverseKeyedActors.set(actor, registryKey);
+  }
+  for (const actor of Object.values(children)) {
+    if (!actor) {
+      continue;
+    }
+    if (actor.sessionId) {
+      registeredActors.set(actor.sessionId, actor);
+    }
+    const registryKey = actor.registryKey;
+    if (registryKey) {
+      keyedActors.set(registryKey, actor);
+      reverseKeyedActors.set(actor, registryKey);
+    }
+  }
+  return system;
+}
+
+/** Returns the actor identity associated with a transition snapshot. @internal */
+function getSnapshotActorRef(snapshot) {
+  return snapshot[snapshotActorRef];
+}
+
+/**
+ * Copies an internal actor association without rebuilding its system view.
+ *
+ * @internal
+ */
+function copySnapshotActorRef(source, target) {
+  const ref = getSnapshotActorRef(source);
+  if (ref) {
+    Object.defineProperty(target, snapshotActorRef, {
+      configurable: true,
+      value: ref
+    });
+  }
+}
+
+/**
+ * Associates a transition snapshot with an actor and an immutable system view.
+ * The internal association is excluded from enumeration and persistence.
+ *
+ * @internal
+ */
+function setSnapshotActorRef(snapshot, actor, baseSystem = actor.system) {
+  const system = createSnapshotSystem(baseSystem, actor, getSnapshotChildren(snapshot));
+  Object.defineProperty(snapshot, snapshotActorRef, {
+    configurable: true,
+    value: {
+      actor,
+      systemState: {
+        children: system.children,
+        keyedActors: system.keyedActors,
+        snapshot: system._snapshot
+      }
+    }
+  });
+}
+
 function isMachineSnapshot(value) {
   return !!value && typeof value === 'object' && 'machine' in value && 'value' in value;
 }
@@ -2094,6 +2507,7 @@ const machineSnapshotToJSON = function toJSON() {
   const {
     _nodes: nodes,
     _stateInputs,
+    [snapshotActorRef]: _actorRef,
     tags,
     machine,
     getMeta,
@@ -2130,8 +2544,8 @@ function collectTags(stateNodes) {
   }
   return tags;
 }
-function createMachineSnapshot(config, machine) {
-  return {
+function createMachineSnapshot(config, machine, actorRef) {
+  const snapshot = {
     status: config.status,
     output: config.output,
     error: config.error,
@@ -2141,8 +2555,10 @@ function createMachineSnapshot(config, machine) {
     value: config.value ?? getStateValue(machine.root, config._nodes),
     tags: collectTags(config._nodes),
     children: config.children,
+    timers: config.timers ?? {},
     historyValue: config.historyValue || {},
     _stateInputs: config._stateInputs || {},
+    _nextTimerId: config._nextTimerId ?? 0,
     matches: machineSnapshotMatches,
     hasTag: machineSnapshotHasTag,
     can: machineSnapshotCan,
@@ -2150,6 +2566,10 @@ function createMachineSnapshot(config, machine) {
     getInputs: machineSnapshotGetInputs,
     toJSON: machineSnapshotToJSON
   };
+  if (actorRef) {
+    setSnapshotActorRef(snapshot, actorRef);
+  }
+  return snapshot;
 }
 function cloneMachineSnapshot(snapshot, config = {}) {
   const configWithSnapshot = {
@@ -2157,7 +2577,7 @@ function cloneMachineSnapshot(snapshot, config = {}) {
     ...config
   };
   if ((config._nodes ?? snapshot._nodes) === snapshot._nodes) {
-    return {
+    const clonedSnapshot = {
       status: configWithSnapshot.status,
       output: configWithSnapshot.output,
       error: configWithSnapshot.error,
@@ -2167,8 +2587,10 @@ function cloneMachineSnapshot(snapshot, config = {}) {
       value: snapshot.value,
       tags: snapshot.tags,
       children: configWithSnapshot.children,
+      timers: configWithSnapshot.timers ?? {},
       historyValue: configWithSnapshot.historyValue || {},
       _stateInputs: configWithSnapshot._stateInputs || {},
+      _nextTimerId: configWithSnapshot._nextTimerId ?? 0,
       matches: machineSnapshotMatches,
       hasTag: machineSnapshotHasTag,
       can: machineSnapshotCan,
@@ -2176,11 +2598,15 @@ function cloneMachineSnapshot(snapshot, config = {}) {
       getInputs: machineSnapshotGetInputs,
       toJSON: machineSnapshotToJSON
     };
+    copySnapshotActorRef(snapshot, clonedSnapshot);
+    return clonedSnapshot;
   }
-  return createMachineSnapshot({
+  const clonedSnapshot = createMachineSnapshot({
     ...configWithSnapshot,
     value: undefined
   }, snapshot.machine);
+  copySnapshotActorRef(snapshot, clonedSnapshot);
+  return clonedSnapshot;
 }
 function serializeHistoryValue(historyValue) {
   const result = {};
@@ -2201,6 +2627,7 @@ function getPersistedSnapshot(snapshot, options) {
     tags,
     machine,
     children,
+    timers,
     context,
     can,
     hasTag,
@@ -2211,6 +2638,7 @@ function getPersistedSnapshot(snapshot, options) {
     ...jsonValues
   } = snapshot;
   const childrenJson = {};
+  const timersJson = {};
   for (const id in children) {
     const child = children[id];
     if (typeof child.src !== 'string' && (!options || !('__unsafeAllowInlineActors' in options))) {
@@ -2223,10 +2651,36 @@ function getPersistedSnapshot(snapshot, options) {
       syncSnapshot: child._syncSnapshot
     };
   }
+  for (const id in timers) {
+    const timer = timers[id];
+    let target;
+    if (timer.target === 'self') {
+      target = 'self';
+    } else {
+      const childId = Object.entries(children).find(([, child]) => child === timer.target)?.[0];
+      if (childId) {
+        target = childId;
+      } else if (timer.target === getSnapshotActorRef(snapshot)?.actor._parent) {
+        target = {
+          type: 'parent'
+        };
+      } else {
+        throw new Error(`Unable to persist timer '${id}': target actor '${timer.target.id}' is no longer addressable from this snapshot.`);
+      }
+    }
+    timersJson[id] = {
+      id: timer.id,
+      delay: timer.delay,
+      type: timer.type,
+      event: timer.event,
+      target
+    };
+  }
   const persisted = {
     ...jsonValues,
     context: persistContext(context),
     children: childrenJson,
+    timers: timersJson,
     historyValue: serializeHistoryValue(jsonValues.historyValue)
   };
   if (_stateInputs && Object.keys(_stateInputs).length > 0) {
@@ -2493,11 +2947,17 @@ function matchesEventDescriptor(eventType, descriptor) {
   return true;
 }
 
-function createScheduledEventId(actor, id) {
+/**
+ * Runtime operations used to execute effects.
+ *
+ * An external interpreter can override these operations while the default actor
+ * system provides the local in-memory implementation.
+ */
+
+function createScheduledTimerId(actor, id) {
   return `${actor.sessionId}.${id}`;
 }
 function createRuntimeSystem(rootActor, options) {
-  let idCounter = 0;
   const children = new Map();
   const keyedActors = new Map();
   const reverseKeyedActors = new WeakMap();
@@ -2525,42 +2985,50 @@ function createRuntimeSystem(rootActor, options) {
     });
   };
   const scheduler = {
-    schedule: (source, target, event, delay, id = Math.random().toString(36).slice(2)) => {
-      recordSent(source, target, event, delay, id);
-      const scheduledEvent = {
+    schedule: (source, id, delay) => {
+      const existingId = createScheduledTimerId(source, id);
+      if (timerMap[existingId] !== undefined) {
+        scheduler.cancel(source, id);
+      }
+      const timer = source.getSnapshot()?.timers?.[id];
+      if (timer) {
+        const target = timer.target === 'self' ? source : timer.target;
+        recordSent(source, target, timer.event, delay, id);
+      }
+      const scheduledAt = Date.now();
+      const scheduledTimer = {
         source,
-        target,
-        event,
         delay,
         id,
-        startedAt: Date.now()
+        scheduledAt,
+        dueAt: scheduledAt + delay
       };
-      const scheduledEventId = createScheduledEventId(source, id);
-      system._snapshot._scheduledEvents[scheduledEventId] = scheduledEvent;
+      const scheduledTimerId = createScheduledTimerId(source, id);
+      system._snapshot._scheduledTimers[scheduledTimerId] = scheduledTimer;
       const timeout = clock.setTimeout(() => {
-        delete timerMap[scheduledEventId];
-        delete system._snapshot._scheduledEvents[scheduledEventId];
-
-        // The send was already recorded at schedule time on the sender's
-        // transition, so deliver without re-recording.
-        deliver(source, target, event);
+        delete timerMap[scheduledTimerId];
+        delete system._snapshot._scheduledTimers[scheduledTimerId];
+        deliver(source, source, {
+          type: XSTATE_TIMER,
+          id
+        });
       }, delay);
-      timerMap[scheduledEventId] = timeout;
+      timerMap[scheduledTimerId] = timeout;
     },
     cancel: (source, id) => {
-      const scheduledEventId = createScheduledEventId(source, id);
-      const timeout = timerMap[scheduledEventId];
-      delete timerMap[scheduledEventId];
-      delete system._snapshot._scheduledEvents[scheduledEventId];
+      const scheduledTimerId = createScheduledTimerId(source, id);
+      const timeout = timerMap[scheduledTimerId];
+      delete timerMap[scheduledTimerId];
+      delete system._snapshot._scheduledTimers[scheduledTimerId];
       if (timeout !== undefined) {
         clock.clearTimeout(timeout);
       }
     },
     cancelAll: actor => {
-      for (const scheduledEventId in system._snapshot._scheduledEvents) {
-        const scheduledEvent = system._snapshot._scheduledEvents[scheduledEventId];
-        if (scheduledEvent.source === actor) {
-          scheduler.cancel(actor, scheduledEvent.id);
+      for (const scheduledTimerId in system._snapshot._scheduledTimers) {
+        const scheduledTimer = system._snapshot._scheduledTimers[scheduledTimerId];
+        if (scheduledTimer.source === actor) {
+          scheduler.cancel(actor, scheduledTimer.id);
         }
       }
     }
@@ -2593,9 +3061,10 @@ function createRuntimeSystem(rootActor, options) {
     reverseKeyedActors,
     keyedActors,
     _snapshot: {
-      _scheduledEvents: (options?.snapshot && options.snapshot.scheduler) ?? {}
+      _scheduledTimers: (options?.snapshot && options.snapshot.scheduler) ?? {},
+      _nextActorId: 0
     },
-    _bookId: () => `x:${idCounter++}`,
+    _bookId: () => `x:${system._snapshot._nextActorId++}`,
     _register: (sessionId, actor) => {
       children.set(sessionId, actor);
       return sessionId;
@@ -2604,7 +3073,9 @@ function createRuntimeSystem(rootActor, options) {
       children.delete(actor.sessionId);
       const registryKey = reverseKeyedActors.get(actor);
       if (registryKey !== undefined) {
-        keyedActors.delete(registryKey);
+        if (keyedActors.get(registryKey) === actor) {
+          keyedActors.delete(registryKey);
+        }
         reverseKeyedActors.delete(actor);
       }
     },
@@ -2632,35 +3103,48 @@ function createRuntimeSystem(rootActor, options) {
       };
     },
     _sendInspectionEvent: sendInspectionEvent,
-    _relay: (source, target, event) => {
+    createActorRef: options.createActorRef,
+    spawnActor: () => {},
+    startActor: actor => {
+      actor.start();
+    },
+    stopActor: actor => {
+      actor._stop();
+    },
+    terminateActor: (actor, termination) => {
+      actor._terminate(termination);
+    },
+    sendEvent: (source, target, event) => {
       recordSent(source, target, event);
       deliver(source, target, event);
     },
+    emitEvent: (source, event) => source._emit(event),
+    scheduleTimer: (source, id, delay) => scheduler.schedule(source, id, delay),
+    cancelTimer: (source, id) => scheduler.cancel(source, id),
+    cancelAllTimers: source => scheduler.cancelAll(source),
+    _relay: (source, target, event) => system.sendEvent(source, target, event),
     scheduler,
     getSnapshot: () => {
       return {
-        _scheduledEvents: {
-          ...system._snapshot._scheduledEvents
+        _scheduledTimers: {
+          ...system._snapshot._scheduledTimers
         }
       };
     },
     start: () => {
-      const scheduledEvents = system._snapshot._scheduledEvents;
-      system._snapshot._scheduledEvents = {};
-      for (const scheduledId in scheduledEvents) {
+      const scheduledTimers = system._snapshot._scheduledTimers;
+      system._snapshot._scheduledTimers = {};
+      for (const scheduledId in scheduledTimers) {
         const {
           source,
-          target,
-          event,
-          delay,
+          dueAt,
           id
-        } = scheduledEvents[scheduledId];
-        scheduler.schedule(source, target, event, delay, id);
+        } = scheduledTimers[scheduledId];
+        system.scheduleTimer(source, id, Math.max(0, dueAt - Date.now()));
       }
     },
     _clock: clock,
-    _logger: logger,
-    _timerStrategy: options.timers
+    _logger: logger
   };
   return system;
 }
@@ -2695,22 +3179,13 @@ function safeCall(fn, arg) {
     reportUnhandledError(err);
   }
 }
-function isExecutableActionObject(effect) {
-  return typeof effect === 'object' && effect !== null && 'args' in effect && 'exec' in effect;
-}
 function executeExecutableEffects(effects, actorScope) {
   if (!effects?.length) {
-    return [];
+    return;
   }
-  const logicEffects = [];
   for (const effect of effects) {
-    if (isExecutableActionObject(effect)) {
-      actorScope.actionExecutor(effect);
-    } else {
-      logicEffects.push(effect);
-    }
+    actorScope.actionExecutor(effect);
   }
-  return logicEffects;
 }
 
 /**
@@ -2776,8 +3251,7 @@ class Actor {
     this.src = void 0;
     // array of functions to defer
     this._deferred = [];
-    // pending effects (timers) from a persisted snapshot, rescheduled on `start()`
-    this._pendingEffects = void 0;
+    this._restored = false;
     const resolvedOptions = {
       ...defaultOptions,
       ...options
@@ -2794,7 +3268,7 @@ class Actor {
     this.system = parent ? parent.system : resolvedOptions._systemRef?.current ?? createRuntimeSystem(this, {
       clock,
       logger,
-      timers: resolvedOptions.timers
+      createActorRef: (childLogic, childOptions) => createActor(childLogic, childOptions)
     });
     if (!parent && resolvedOptions._systemRef && !resolvedOptions._systemRef.current) {
       resolvedOptions._systemRef.current = this.system;
@@ -2827,15 +3301,7 @@ class Actor {
         }
         child._stop();
       },
-      emit: emittedEvent => {
-        for (const listeners of [this.eventListeners.get(emittedEvent.type), this.eventListeners.get('*')]) {
-          if (listeners) {
-            for (const handler of listeners) {
-              safeCall(handler, emittedEvent);
-            }
-          }
-        }
-      },
+      emit: emittedEvent => this.system.emitEvent(this, emittedEvent),
       actionExecutor: action => {
         const exec = () => {
           // Record every executed action for the '@xstate.transition' inspection
@@ -2844,13 +3310,10 @@ class Actor {
             type: action.type,
             params: action.params
           });
-          if (!action.exec) {
-            return;
-          }
           const saveExecutingCustomAction = executingCustomAction;
           try {
             executingCustomAction = true;
-            action.exec();
+            void action.exec();
           } finally {
             executingCustomAction = saveExecutingCustomAction;
           }
@@ -2883,38 +3346,29 @@ class Actor {
 
     // prepare to collect initial microsteps during initialTransition
     this._collectedMicrosteps = [];
-    let persistedState = options?.snapshot ?? options?.state;
-    if (persistedState && typeof persistedState === 'object' && '_pendingEffects' in persistedState) {
-      // Pending effects are restored by this actor on `start()`; the logic
-      // only sees the rest of the persisted snapshot.
-      const {
-        _pendingEffects,
-        ...rest
-      } = persistedState;
-      this._pendingEffects = _pendingEffects;
-      persistedState = rest;
-    }
+    const persistedState = options?.snapshot ?? options?.state;
+    this._restored = persistedState !== undefined;
     try {
       if (persistedState) {
-        this._snapshot = this.logic.restoreSnapshot ? this.logic.restoreSnapshot(persistedState, this._actorScope) : persistedState;
+        this._setSnapshot(this.logic.restoreSnapshot ? this.logic.restoreSnapshot(persistedState, this._actorScope) : persistedState);
       } else if (options?._inert) {
         // Inert actors (createInertActorScope) only anchor a scope for pure
         // transition functions; computing an initial snapshot here would run
         // init-time side effects (context factories, entry) a second time.
       } else {
-        const [snapshot, effects] = this.logic.initialTransition(this.options?.input, this._actorScope);
-        this._snapshot = snapshot;
+        const [snapshot, effects] = finalizeTransitionResult(this._actorScope, undefined, this.logic.initialTransition(this.options?.input, this._actorScope));
+        this._setSnapshot(snapshot);
         this._initialEffects = effects;
       }
     } catch (err) {
       // if we get here then it means that we assign a value to this._snapshot that is not of the correct type
       // we can't get the true `TSnapshot & { status: 'error'; }`, it's impossible
       // so right now this is a lie of sorts
-      this._snapshot = {
+      this._setSnapshot({
         status: 'error',
         output: undefined,
         error: err
-      };
+      });
       // discard any functions deferred during the failed initial snapshot
       // computation so they can't run against an inconsistent actor
       this._deferred.length = 0;
@@ -2935,12 +3389,17 @@ class Actor {
       snapshot: this._snapshot
     });
   }
+  /** Associates each live snapshot with this actor for later pure transitions. */
+  _setSnapshot(snapshot) {
+    this._snapshot = snapshot;
+    setSnapshotActorRef(snapshot, this);
+  }
   _setErrorSnapshot(err, snapshot = this._snapshot) {
-    this._snapshot = {
+    this._setSnapshot({
       ...snapshot,
       status: 'error',
       error: err
-    };
+    });
   }
 
   /** Recover via the logic's error event if possible; otherwise error out. */
@@ -2958,11 +3417,10 @@ class Actor {
       return false;
     }
     try {
-      const [nextSnapshot, effects] = this.logic.transition(snapshot, errorEvent, this._actorScope);
-      this._snapshot = nextSnapshot;
-      const logicEffects = executeExecutableEffects(effects, this._actorScope);
+      const [nextSnapshot, effects] = finalizeTransitionResult(this._actorScope, snapshot, this.logic.transition(snapshot, errorEvent, this._actorScope));
+      this._setSnapshot(nextSnapshot);
+      executeExecutableEffects(effects, this._actorScope);
       this.update(nextSnapshot, errorEvent);
-      this.logic.executeEffects?.(logicEffects, this._actorScope);
       return true;
     } catch {
       return false;
@@ -2975,7 +3433,7 @@ class Actor {
   }
   update(snapshot, event) {
     // Update state
-    this._snapshot = snapshot;
+    this._setSnapshot(snapshot);
 
     // Execute deferred effects
     for (let i = 0; i < this._deferred.length; i++) {
@@ -2993,6 +3451,7 @@ class Actor {
           return;
         }
         this._setErrorSnapshot(err, snapshot);
+        this._error(err);
         break;
       }
     }
@@ -3001,26 +3460,6 @@ class Actor {
       case 'active':
         this._next(snapshot);
         break;
-      case 'done':
-        {
-          // next observers are meant to be notified about done snapshots
-          // this can be seen as something that is different from how observable work
-          // but with observables `complete` callback is called without any arguments
-          // it's more ergonomic for XState to treat a done snapshot as a "next" value
-          // and the completion event as something that is separate,
-          // something that merely follows emitting that done snapshot
-          this._next(snapshot);
-          this._stopProcedure();
-          this._complete();
-          const doneEvent = createDoneActorEvent(this.id, this._snapshot.output);
-          if (this._parent) {
-            this.system._relay(this, this._parent, doneEvent);
-          }
-          break;
-        }
-      case 'error':
-        this._error(this._snapshot.error);
-        break;
     }
     this.system._sendInspectionEvent({
       type: '@xstate.transition',
@@ -3045,8 +3484,7 @@ class Actor {
     }
     this._forceDeferredActions = true;
     try {
-      const logicEffects = executeExecutableEffects(this._initialEffects, this._actorScope);
-      this.logic.executeEffects?.(logicEffects, this._actorScope);
+      executeExecutableEffects(this._initialEffects, this._actorScope);
       this._initialEffects = undefined;
       return true;
     } catch (err) {
@@ -3217,6 +3655,14 @@ class Actor {
       case 'done':
         // a state machine can be "done" upon initialization (it could reach a final state using initial microsteps)
         // we still need to complete observers, flush deferreds etc
+        if (this._restored) {
+          // Restoration does not replay the transition that originally
+          // terminated the actor, and must not notify the parent again.
+          this._next(this._snapshot);
+          this._stopProcedure();
+          this._complete();
+          return this;
+        }
         if (!this._flushInitialEffects()) {
           return this;
         }
@@ -3230,33 +3676,31 @@ class Actor {
     if (!this._parent) {
       this.system.start();
     }
+    if (!this._flushInitialEffects()) {
+      return this;
+    }
     if (this.logic.start) {
       try {
-        this.logic.start(this._snapshot, this._actorScope);
+        this.logic.start(this._snapshot, this._actorScope, {
+          restored: this._restored
+        });
       } catch (err) {
         this._setErrorSnapshot(err);
         this._error(err);
         return this;
       }
     }
-    if (!this._flushInitialEffects()) {
-      return this;
-    }
 
     // TODO: this notifies all subscribers but usually this is redundant
     // there is no real change happening here
     // we need to rethink if this needs to be refactored
     this.update(this._snapshot, initEvent);
-    if (this._pendingEffects) {
-      const strategy = this.options.timers ?? this.system._timerStrategy ?? 'resume';
-      for (const effect of this._pendingEffects) {
-        // Re-execute the pending effect with its remaining delay. Only
-        // self-targeted raises exist today; other effect types are ignored.
-        if (effect.type === '@xstate.raise') {
-          this.system.scheduler.schedule(this, this, effect.event, resolveRestoredTimerDelay(strategy, effect), effect.id);
-        }
+    if (this._restored) {
+      const timers = this._snapshot.timers ?? {};
+      for (const timer of Object.values(timers)) {
+        this.system.scheduleTimer(this, timer.id, timer.delay);
       }
-      this._pendingEffects = undefined;
+      this._restored = false;
     }
     this.mailbox.start();
     return this;
@@ -3265,7 +3709,7 @@ class Actor {
     let nextState;
     let caughtError;
     try {
-      nextState = this.logic.transition(this._snapshot, event, this._actorScope);
+      nextState = finalizeTransitionResult(this._actorScope, this._snapshot, this.logic.transition(this._snapshot, event, this._actorScope));
     } catch (err) {
       // we wrap it in a box so we can rethrow it later even if falsy value gets caught here
       caughtError = {
@@ -3280,10 +3724,9 @@ class Actor {
     try {
       const [nextSnapshot, effects] = nextState;
       snapshot = nextSnapshot;
-      this._snapshot = snapshot;
-      const logicEffects = executeExecutableEffects(effects, this._actorScope);
+      this._setSnapshot(snapshot);
+      executeExecutableEffects(effects, this._actorScope);
       this.update(snapshot, event);
-      this.logic.executeEffects?.(logicEffects, this._actorScope);
     } catch (err) {
       this._recoverOrError(err, snapshot);
       return;
@@ -3294,6 +3737,35 @@ class Actor {
     }
   }
 
+  /** @internal */
+  _emit(event) {
+    for (const listeners of [this.eventListeners.get(event.type), this.eventListeners.get('*')]) {
+      if (listeners) {
+        for (const handler of listeners) {
+          safeCall(handler, event);
+        }
+      }
+    }
+  }
+
+  /** @internal */
+  _terminate(termination) {
+    if (termination.status === 'done') {
+      // The terminal snapshot is published before observer completion and the
+      // parent notification, matching actor lifecycle order.
+      this._next(this._snapshot);
+      this._stopProcedure();
+      this._complete();
+      if (this._parent) {
+        this.system._relay(this, this._parent, createDoneActorEvent(this.id, termination.output));
+      }
+      return;
+    }
+    if (termination.status === 'error') {
+      this._error(termination.error);
+    }
+  }
+
   /** @internal */
   _stop() {
     if (this._processingStatus === ProcessingStatus.Stopped) {
@@ -3302,6 +3774,7 @@ class Actor {
     this.mailbox.clear();
     if (this._processingStatus === ProcessingStatus.NotStarted) {
       this._processingStatus = ProcessingStatus.Stopped;
+      this.system._unregister(this);
       return this;
     }
     this.mailbox.enqueue({
@@ -3360,7 +3833,7 @@ class Actor {
     }
 
     // Cancel all delayed events
-    this.system.scheduler.cancelAll(this);
+    this.system.cancelAllTimers(this);
 
     // TODO: mailbox.reset
     this.mailbox.clear();
@@ -3421,35 +3894,7 @@ class Actor {
    */
 
   getPersistedSnapshot(options) {
-    const persisted = this.logic.getPersistedSnapshot(this._snapshot, options);
-
-    // Capture this actor's pending self-targeted effects (delayed
-    // events/transitions) as serialized action descriptors plus their
-    // runtime progress, so they can be restored on `start()`.
-    const scheduledEvents = this.system._snapshot._scheduledEvents;
-    let pendingEffects;
-    const now = Date.now();
-    for (const key in scheduledEvents) {
-      const scheduled = scheduledEvents[key];
-      if (scheduled.source === this && scheduled.target === this) {
-        (pendingEffects ??= []).push({
-          type: '@xstate.raise',
-          event: scheduled.event,
-          id: scheduled.id,
-          delay: scheduled.delay,
-          startedAt: scheduled.startedAt,
-          elapsed: Math.max(0, now - scheduled.startedAt)
-        });
-      }
-    }
-
-    // If this actor was restored but not yet started, its pending effects
-    // are not in the scheduler yet — carry them through as-is.
-    pendingEffects ??= this._pendingEffects;
-    return pendingEffects ? {
-      ...persisted,
-      _pendingEffects: pendingEffects
-    } : persisted;
+    return this.logic.getPersistedSnapshot(this._snapshot, options);
   }
   [symbolObservable]() {
     return this;
@@ -3476,20 +3921,6 @@ class Actor {
     return this._snapshot;
   }
 }
-function resolveRestoredTimerDelay(strategy, effect) {
-  if (typeof strategy === 'function') {
-    return strategy(effect);
-  }
-  switch (strategy) {
-    case 'restart':
-      return effect.delay;
-    case 'absolute':
-      return Math.max(0, effect.startedAt + effect.delay - Date.now());
-    case 'resume':
-    default:
-      return Math.max(0, effect.delay - effect.elapsed);
-  }
-}
 /**
  * Creates a new actor instance for the given actor logic with the provided
  * options, if any.
@@ -3545,63 +3976,27 @@ function getEffectState(self) {
   }
   return state;
 }
-function executeLogicEffects(effects, actorScope) {
-  if (!effects?.length) {
+function executeLogicEffect(self, key, effect) {
+  const state = getEffectState(self);
+  if (key !== undefined && state.has(key)) {
     return;
   }
-  for (const effect of effects) {
-    switch (effect.type) {
-      case 'emit':
-        actorScope.emit(effect.event);
-        break;
-      case 'sendBack':
-        {
-          const parent = actorScope.self._parent;
-          if (parent) {
-            actorScope.system._relay(actorScope.self, parent, effect.event);
-          }
-          break;
-        }
-      case 'raise':
-        actorScope.system._relay(actorScope.self, actorScope.self, effect.event);
-        break;
-      case 'effect':
-        {
-          if (!effect.key) {
-            const cleanup = effect.exec();
-            if (typeof cleanup === 'function') {
-              getEffectState(actorScope.self).set(Symbol(), {
-                cleanup
-              });
-            }
-            break;
-          }
-          const state = getEffectState(actorScope.self);
-          if (state.has(effect.key)) {
-            break;
-          }
-          const cleanup = effect.exec();
-          state.set(effect.key, {
-            cleanup: typeof cleanup === 'function' ? cleanup : undefined
-          });
-          break;
-        }
-      case 'cleanupEffects':
-        {
-          const state = effectStates.get(actorScope.self);
-          if (!state) {
-            break;
-          }
-          for (const {
-            cleanup
-          } of state.values()) {
-            cleanup?.();
-          }
-          effectStates.delete(actorScope.self);
-          break;
-        }
-    }
+  const cleanup = effect();
+  state.set(key ?? Symbol(), {
+    cleanup: typeof cleanup === 'function' ? cleanup : undefined
+  });
+}
+function cleanupLogicEffects(self) {
+  const state = effectStates.get(self);
+  if (!state) {
+    return;
+  }
+  for (const {
+    cleanup
+  } of state.values()) {
+    cleanup?.();
   }
+  effectStates.delete(self);
 }
 function resolveContext(context, input) {
   return typeof context === 'function' ? context({
@@ -3618,9 +4013,7 @@ function createLogic(config) {
         ...snapshot,
         status: 'stopped',
         input: undefined
-      }, [{
-        type: 'cleanupEffects'
-      }]];
+      }, [createCustomEffect('xstate.logic.cleanup', () => cleanupLogicEffects(actorScope.self))]];
     }
     if (event.type === XSTATE_LOGIC_EFFECT_START) {
       return [{
@@ -3663,43 +4056,33 @@ function createLogic(config) {
       if (snapshot.effects?.[key]) {
         return;
       }
-      effects.push({
-        type: 'effect',
-        key,
-        exec
-      });
+      effects.push(createCustomEffect('xstate.logic.effect', (runtime = actorScope.self.system) => executeLogicEffect(actorScope.self, key, () => exec(runtime)), {
+        key
+      }));
       trackedEffects[key] = {
         status: 'active'
       };
     };
     const enq = {
       emit: emitted => {
-        effects.push({
-          type: 'emit',
-          event: emitted
-        });
+        effects.push(createEmitEffect(actorScope, emitted));
       },
       sendBack: sentEvent => {
-        effects.push({
-          type: 'sendBack',
-          event: sentEvent
-        });
+        const parent = actorScope.self._parent;
+        if (parent) {
+          effects.push(createSendToEffect(actorScope, parent, sentEvent));
+        }
       },
       raise: raisedEvent => {
-        effects.push({
-          type: 'raise',
-          event: raisedEvent
-        });
+        effects.push(createSendToEffect(actorScope, actorScope.self, raisedEvent));
       },
       effect: (keyOrExec, maybeExec) => {
         if (typeof keyOrExec === 'string') {
           enqueueEffect(keyOrExec, maybeExec);
           return;
         }
-        effects.push({
-          type: 'effect',
-          exec: keyOrExec
-        });
+        const exec = keyOrExec;
+        effects.push(createCustomEffect('xstate.logic.effect', (runtime = actorScope.self.system) => executeLogicEffect(actorScope.self, undefined, () => exec(runtime))));
       }
     };
     const patch = config.run({
@@ -3724,18 +4107,23 @@ function createLogic(config) {
         ...trackedEffects
       };
     }
-    return [nextSnapshot, effects];
+    return finalizeTransitionResult(actorScope, snapshot, [nextSnapshot, effects]);
   };
   const logic = {
     id: config.id,
     config,
     transition,
-    start: (snapshot, actorScope) => {
+    start: (snapshot, actorScope, options) => {
+      if (!options?.restored) {
+        return;
+      }
       const [nextSnapshot, effects] = transition(snapshot, createInitEvent(snapshot.input), actorScope);
       Object.assign(snapshot, nextSnapshot);
-      executeLogicEffects(effects, actorScope);
+      for (const effect of effects) {
+        actorScope.actionExecutor(effect);
+      }
     },
-    initialTransition: (input, _) => {
+    initialTransition: (input, actorScope) => {
       const context = resolveContext(config.context, input);
       const snapshot = {
         status: 'active',
@@ -3746,14 +4134,13 @@ function createLogic(config) {
       if (context !== undefined) {
         snapshot.context = context;
       }
-      return [{
+      return transition({
         ...snapshot
-      }, []];
+      }, createInitEvent(input), actorScope);
     },
     getInitialSnapshot: (actorScope, input) => logic.initialTransition(input, actorScope)[0],
     getPersistedSnapshot: snapshot => snapshot,
-    restoreSnapshot: snapshot => snapshot,
-    executeEffects: executeLogicEffects
+    restoreSnapshot: snapshot => snapshot
   };
   return logic;
 }
@@ -4013,7 +4400,6 @@ function createObservableLogic(observableCreatorOrConfig) {
         self,
         system
       } = args;
-      const emit = args.emit;
       switch (event.type) {
         case XSTATE_OBSERVABLE_NEXT:
           {
@@ -4044,28 +4430,32 @@ function createObservableLogic(observableCreatorOrConfig) {
             }
           };
       }
-      enq.effect('observable', () => {
+      if (event.type !== XSTATE_INIT) {
+        return;
+      }
+      enq.effect((runtime = system) => {
         const actorSelf = self;
+        const sendSelf = event => void runtime.sendEvent(actorSelf, actorSelf, event);
         const subscription = observableCreator({
           input,
           system,
           self: self,
-          emit: emit
+          emit: event => void runtime.emitEvent(actorSelf, event)
         }).subscribe({
           next: value => {
-            system._relay(actorSelf, actorSelf, {
+            sendSelf({
               type: XSTATE_OBSERVABLE_NEXT,
               data: value
             });
           },
           error: err => {
-            system._relay(actorSelf, actorSelf, {
+            sendSelf({
               type: XSTATE_OBSERVABLE_ERROR,
               data: err
             });
           },
           complete: () => {
-            system._relay(actorSelf, actorSelf, {
+            sendSelf({
               type: XSTATE_OBSERVABLE_COMPLETE
             });
           }
@@ -4134,26 +4524,26 @@ function createEventObservableLogic(lazyObservableOrConfig) {
   // TODO: event types
   const logic = {
     config: lazyObservable,
-    transition: (state, event) => {
+    transition: (state, event, actorScope) => {
       if (state.status !== 'active') {
         return [state, []];
       }
       switch (event.type) {
         case XSTATE_OBSERVABLE_ERROR:
-          return [{
+          return finalizeTransitionResult(actorScope, state, [{
             ...state,
             status: 'error',
             error: event.data,
             input: undefined,
             _subscription: undefined
-          }, []];
+          }, []]);
         case XSTATE_OBSERVABLE_COMPLETE:
-          return [{
+          return finalizeTransitionResult(actorScope, state, [{
             ...state,
             status: 'done',
             input: undefined,
             _subscription: undefined
-          }, []];
+          }, []]);
         case XSTATE_STOP:
           state._subscription.unsubscribe();
           return [{
@@ -4188,7 +4578,9 @@ function createEventObservableLogic(lazyObservableOrConfig) {
         input: state.input,
         system,
         self,
-        emit
+        emit: event => {
+          void emit(event);
+        }
       }).subscribe({
         next: value => {
           if (self._parent) {
@@ -4389,8 +4781,9 @@ function createAsyncLogic(asyncLogic) {
       if (event.type !== XSTATE_INIT) {
         return;
       }
-      enq.effect(() => {
+      enq.effect((runtime = system) => {
         const actorSelf = self;
+        const sendSelf = event => void runtime.sendEvent(actorSelf, actorSelf, event);
         const controller = new AbortController();
         const timeout = config.timeout;
         const timeoutMs = parseDelayToMilliseconds(timeout);
@@ -4399,7 +4792,7 @@ function createAsyncLogic(asyncLogic) {
             return;
           }
           controller.abort();
-          system._relay(actorSelf, actorSelf, {
+          sendSelf({
             type: XSTATE_ASYNC_REJECT,
             data: new TimeoutError(timeout)
           });
@@ -4415,7 +4808,7 @@ function createAsyncLogic(asyncLogic) {
           self: self,
           signal: controller.signal
         }, {
-          emit: enq.emit,
+          emit: event => void runtime.emitEvent(actorSelf, event),
           step: async (key, exec) => {
             const effect = self.getSnapshot().effects?.[key];
             if (effect?.status === 'done') {
@@ -4427,20 +4820,20 @@ function createAsyncLogic(asyncLogic) {
             if (effect?.status === 'active') {
               return waitForEffect(self, key);
             }
-            system._relay(actorSelf, actorSelf, {
+            sendSelf({
               type: XSTATE_LOGIC_EFFECT_START,
               key
             });
             try {
               const output = await exec();
-              system._relay(actorSelf, actorSelf, {
+              sendSelf({
                 type: XSTATE_LOGIC_EFFECT_RESOLVE,
                 key,
                 output
               });
               return output;
             } catch (error) {
-              system._relay(actorSelf, actorSelf, {
+              sendSelf({
                 type: XSTATE_LOGIC_EFFECT_REJECT,
                 key,
                 error
@@ -4454,7 +4847,7 @@ function createAsyncLogic(asyncLogic) {
           if (self.getSnapshot().status !== 'active') {
             return;
           }
-          system._relay(actorSelf, actorSelf, {
+          sendSelf({
             type: XSTATE_ASYNC_RESOLVE,
             data: response
           });
@@ -4463,7 +4856,7 @@ function createAsyncLogic(asyncLogic) {
           if (self.getSnapshot().status !== 'active') {
             return;
           }
-          system._relay(actorSelf, actorSelf, {
+          sendSelf({
             type: XSTATE_ASYNC_REJECT,
             data: errorData
           });
@@ -4492,4 +4885,4 @@ function createEmptyActor() {
   return createActor(emptyLogic);
 }
 
-export { transitionNode as $, Actor as A, createLogic as B, createAsyncLogic as C, createListenerLogic as D, listenerLogic as E, createSubscriptionLogic as F, subscriptionLogic as G, resolveReferencedActor as H, mapValues as I, createInvokeId as J, getDelayedTransitions as K, evaluateCandidate as L, formatTransition as M, NULL_EVENT as N, toTransitionConfigArray as O, ProcessingStatus as P, createInvokeTimeoutEvent as Q, getCandidates as R, STATE_DELIMITER as S, TimeoutError as T, formatRouteTransitions as U, resolveStateValue as V, getAllStateNodes as W, XSTATE_INIT as X, createMachineSnapshot as Y, isInFinalState as Z, cloneMachineSnapshot as _, XSTATE_STOP as a, getTransitionResult as a0, hasEffect as a1, createErrorPlatformEvent as a2, toStatePath as a3, isStateId as a4, getStateNodeByPath as a5, getPersistedSnapshot as a6, $$ACTOR_TYPE as a7, builtInActions as b, createTransitionEnqueue as c, deriveDeferredStarts as d, createActor as e, macrostep as f, createInitEvent as g, initialMicrostep as h, isAtomicStateNode as i, getProperAncestors as j, isMachineSnapshot as k, getStateNodes as l, matchesEventDescriptor as m, getAllOwnEventDescriptors as n, matchesState as o, parseDelayToMilliseconds as p, checkStateIn as q, resolveActionsWithContext as r, pathToStateValue as s, toArray as t, toObserver as u, isBuiltInExecutableAction as v, createEmptyActor as w, createCallbackLogic as x, createObservableLogic as y, createEventObservableLogic as z };
+export { getCandidates as $, Actor as A, isBuiltInExecutableAction as B, createEmptyActor as C, createCallbackLogic as D, createObservableLogic as E, createEventObservableLogic as F, createLogic as G, createAsyncLogic as H, createListenerLogic as I, listenerLogic as J, createSubscriptionLogic as K, subscriptionLogic as L, resolveReferencedActor as M, setSnapshotActorRef as N, getSnapshotActorRef as O, createSnapshotSystem as P, mapValues as Q, createInvokeId as R, STATE_DELIMITER as S, TimeoutError as T, getDelayedTransitions as U, evaluateCandidate as V, formatTransition as W, XSTATE_INIT as X, NULL_EVENT as Y, toTransitionConfigArray as Z, createInvokeTimeoutEvent as _, XSTATE_STOP as a, formatRouteTransitions as a0, resolveStateValue as a1, getAllStateNodes as a2, createMachineSnapshot as a3, isInFinalState as a4, cloneMachineSnapshot as a5, transitionNode as a6, getTransitionResult as a7, hasEffect as a8, createErrorPlatformEvent as a9, toStatePath as aa, isStateId as ab, getStateNodeByPath as ac, getPersistedSnapshot as ad, $$ACTOR_TYPE as ae, builtInActions as b, createTransitionEnqueue as c, deriveDeferredStarts as d, XSTATE_TIMER as e, finalizeTransitionResult as f, createSendToEffect as g, createActor as h, isAtomicStateNode as i, macrostep as j, createInitEvent as k, createSpawnEffect as l, matchesEventDescriptor as m, initialMicrostep as n, getProperAncestors as o, parseDelayToMilliseconds as p, isMachineSnapshot as q, resolveActionsWithContext as r, getStateNodes as s, toArray as t, getAllOwnEventDescriptors as u, matchesState as v, checkStateIn as w, pathToStateValue as x, toObserver as y, executeEffects as z };