xstate 6.0.0-alpha.44 → 6.0.0-alpha.46

package/dist/{createActor-f9cc6590.development.esm.js → createActor-f5277b31.development.esm.js}

@@ -218,6 +218,27 @@ const builtInActions = {
   }
 };
 
+const sourceKeyCaches = new WeakMap();
+
+/** @internal */
+function resolveRegisteredActorSource(actors, logic) {
+  let cache = sourceKeyCaches.get(actors);
+  if (!cache) {
+    cache = new Map();
+    for (const key of Object.keys(actors)) {
+      const registeredLogic = actors[key];
+      // Several source keys may intentionally share one implementation. The
+      // first key is its canonical persistence identity when spawning by the
+      // raw logic value, which cannot retain which alias was used to access it.
+      if (!cache.has(registeredLogic)) {
+        cache.set(registeredLogic, key);
+      }
+    }
+    sourceKeyCaches.set(actors, cache);
+  }
+  return cache.get(logic);
+}
+
 const subscriptions = /* #__PURE__ */new WeakMap();
 
 /**
@@ -665,21 +686,31 @@ function beginSpawnAllocation(actorScope) {
 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);
+function getRegisteredActors(actorScope) {
+  return actorScope.self.logic?.sources?.actors;
+}
+function resolveTransitionSpawnSource(actorScope, source) {
+  const registeredActors = getRegisteredActors(actorScope);
+  if (typeof source === 'string') {
+    const logic = registeredActors?.[source];
+    if (!logic) {
+      throw new Error(`Actor source '${source}' is not provided`);
     }
-    srcKeyCaches.set(registeredActors, cache);
+    return {
+      logic,
+      src: source
+    };
   }
-  return cache.get(logic);
+  if (!registeredActors) {
+    return {
+      logic: source,
+      src: undefined
+    };
+  }
+  return {
+    logic: source,
+    src: resolveRegisteredActorSource(registeredActors, source)
+  };
 }
 
 /**
@@ -827,17 +858,17 @@ function createTransitionEnqueue(actorScope, actions, internalEvents, actorSubsc
         internalEvents.push(raisedEvent);
       }
     },
-    spawn: (logic, options) => {
+    spawn: (source, options) => {
+      const {
+        logic,
+        src
+      } = resolveTransitionSpawnSource(actorScope, source);
       if (!createActors) {
         // TODO: replace this speculative placeholder with a typed inert actor ref.
         return {
-          id: options?.id ?? options?.registryKey ?? logic.id
+          id: options?.id ?? options?.registryKey ?? src ?? 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.
@@ -1272,6 +1303,45 @@ function parseDelayToMilliseconds(delay) {
   return parseDurationToMilliseconds(delay);
 }
 
+/**
+ * The ambiently installed system inspector. Set for the duration of a durable
+ * execution's transitions (`createDurable(..., { inspect })`), it makes the
+ * pure-transition machinery observable: freshly constructed runtime systems
+ * attach it, and snapshot systems created while it is set forward inspection
+ * to their base system instead of stubbing it out.
+ */
+let ambientInspector;
+
+/** @internal */
+function hasAmbientInspector() {
+  return ambientInspector !== undefined;
+}
+
+/** @internal */
+function getAmbientInspector() {
+  return ambientInspector;
+}
+
+/**
+ * Runs `fn` with systems it creates wired to `inspect` from construction, so
+ * creation-time inspection events (the root actor's own registration, actors
+ * spawned during the first transition) are observed too.
+ *
+ * @internal
+ */
+function withSystemInspector(inspect, fn) {
+  if (!inspect) {
+    return fn();
+  }
+  const previous = ambientInspector;
+  ambientInspector = inspect;
+  try {
+    return fn();
+  } finally {
+    ambientInspector = previous;
+  }
+}
+
 /** Snapshot-scoped actor identity and system view. @internal */
 
 const snapshotActorRefs = new WeakMap();
@@ -1334,6 +1404,7 @@ function getSnapshotChildren(snapshot) {
  * @internal
  */
 function createSnapshotSystem(baseSystem, children, baseState) {
+  const forwardInspection = hasAmbientInspector();
   const registeredActors = copyRegisteredActors(baseSystem, baseState);
   const keyedActors = new Map(baseState?.keyedActors ?? getKeyedActors(baseSystem));
   const reverseKeyedActors = new WeakMap();
@@ -1372,10 +1443,13 @@ function createSnapshotSystem(baseSystem, children, baseState) {
     },
     get: registryKey => keyedActors.get(registryKey),
     getAll: () => Object.fromEntries(keyedActors),
-    // Pure transition resolution must not leak topology inspection events into
-    // a live runtime system.
-    _hasInspectionObservers: () => false,
-    _sendInspectionEvent: () => {}
+    // Pure transition resolution must not leak topology inspection events
+    // into a live runtime system — planning branches stay silent. The one
+    // exception is a durable execution's own transitions (marked by the
+    // ambient inspector at creation time): there the pure path IS the
+    // execution, so inspection forwards to the base system's observers.
+    _hasInspectionObservers: forwardInspection ? () => baseSystem._hasInspectionObservers?.() ?? false : () => false,
+    _sendInspectionEvent: forwardInspection ? event => baseSystem._sendInspectionEvent(event) : () => {}
   });
   for (const [registryKey, actor] of keyedActors) {
     if (!actor) {
@@ -4403,6 +4477,10 @@ class RuntimeSystem {
     this._clock = options.clock;
     this._logger = options.logger;
     this.createActorRef = options.createActorRef;
+    const ambientInspector = getAmbientInspector();
+    if (ambientInspector) {
+      this.inspect(ambientInspector);
+    }
     this._snapshot = {
       _scheduledTimers: restoredSnapshot?.scheduler ?? emptyScheduledTimers,
       // System-level counters are process-local backstops; per-actor
@@ -5106,6 +5184,9 @@ class Actor {
     }
     this._inspectTransition(this._snapshot, event);
   }
+
+  /** @internal Emits the transition inspection event; used by the pure
+   * `transition()` path for snapshots driven outside a live actor. */
   _inspectTransition(snapshot, event) {
     if (this.system._hasInspectionObservers?.() ?? true) {
       this.system._sendInspectionEvent({
@@ -5654,4 +5735,4 @@ function createActor(logic, options) {
   return new Actor(logic, options);
 }
 
-export { formatTransition as $, Actor as A, checkStateIn as B, pathToStateValue as C, toObserver as D, executeEffects as E, isBuiltInExecutableAction as F, deliverEvent as G, runStep as H, stopActor as I, terminateActor as J, createInitEvent as K, createCustomEffect as L, XSTATE_LOGIC_EFFECT_START as M, XSTATE_LOGIC_EFFECT_RESOLVE as N, XSTATE_LOGIC_EFFECT_REJECT as O, createEmitEffect as P, allocateChildId as Q, assertChildIdFree as R, reserveChildId as S, STATE_DELIMITER as T, mapValues as U, createInvokeId as V, getDelayedTransitions as W, XSTATE_INIT as X, getEventDescriptorKey as Y, getCandidates as Z, evaluateCandidate as _, beginSpawnAllocation as a, NULL_EVENT as a0, toTransitionConfigArray as a1, createInvokeTimeoutEventId as a2, matchesActorSession as a3, formatRouteTransitions as a4, resolveStateValue as a5, getAllStateNodes as a6, createMachineSnapshot as a7, isInFinalState as a8, createInertActorScope as a9, getActorIdPrefix as aA, getAllOwnEvents as aB, matchesEvent as aC, encodeAddressSegment as aD, getRootActorId as aE, RUNTIME_OPERATIONS as aF, withExecutionIdentity as aG, getSnapshotActorRef as aH, setInertActorScopeSnapshot as aa, attachSnapshotActorRef as ab, macrostep as ac, isInertActorScope as ad, setSnapshotActorRef as ae, cloneMachineSnapshot as af, transitionNode as ag, getTransitionResult as ah, hasEffect as ai, createErrorPlatformEvent as aj, withActorSelf as ak, takeSpawnAllocationCounters as al, mergeActorIdCounters as am, createSpawnEffect as an, initialMicrostep as ao, toStatePath as ap, isStateId as aq, getStateNodeByPath as ar, getPersistedSnapshot as as, createRemoteActorRef as at, resolveReferencedActor as au, createInvokeTimeoutEvent as av, parseGeneratedActorId as aw, ACTOR_REF_TYPE as ax, getProperAncestors as ay, isRemoteActorRef as az, builtInActions as b, createTransitionEnqueue as c, deriveDeferredStarts as d, XSTATE_STOP as e, finalizeTransitionResult as f, XSTATE_TIMER as g, createSendToEffect as h, isLazyActorScope as i, isAtomicStateNode as j, createActor as k, createListenerLogic as l, matchesEventDescriptor as m, createSubscriptionLogic as n, listenerLogic as o, parseDelayToMilliseconds as p, getInitialSnapshot as q, resolveActionsWithContext as r, subscriptionLogic as s, toArray as t, getNextSnapshot as u, isMachineSnapshot as v, withActorScope as w, getStateNodes as x, getAllOwnEventDescriptors as y, matchesState as z };
+export { evaluateCandidate as $, Actor as A, checkStateIn as B, pathToStateValue as C, toObserver as D, executeEffects as E, isBuiltInExecutableAction as F, deliverEvent as G, runStep as H, stopActor as I, terminateActor as J, createInitEvent as K, createCustomEffect as L, XSTATE_LOGIC_EFFECT_START as M, XSTATE_LOGIC_EFFECT_RESOLVE as N, XSTATE_LOGIC_EFFECT_REJECT as O, createEmitEffect as P, resolveRegisteredActorSource as Q, allocateChildId as R, assertChildIdFree as S, reserveChildId as T, STATE_DELIMITER as U, mapValues as V, createInvokeId as W, XSTATE_INIT as X, getDelayedTransitions as Y, getEventDescriptorKey as Z, getCandidates as _, beginSpawnAllocation as a, formatTransition as a0, NULL_EVENT as a1, toTransitionConfigArray as a2, createInvokeTimeoutEventId as a3, matchesActorSession as a4, formatRouteTransitions as a5, resolveStateValue as a6, getAllStateNodes as a7, createMachineSnapshot as a8, isInFinalState as a9, getProperAncestors as aA, isRemoteActorRef as aB, getActorIdPrefix as aC, getAllOwnEvents as aD, matchesEvent as aE, encodeAddressSegment as aF, getRootActorId as aG, RUNTIME_OPERATIONS as aH, withSystemInspector as aI, getSnapshotActorRef as aJ, withExecutionIdentity as aK, createInertActorScope as aa, setInertActorScopeSnapshot as ab, attachSnapshotActorRef as ac, macrostep as ad, isInertActorScope as ae, setSnapshotActorRef as af, cloneMachineSnapshot as ag, transitionNode as ah, getTransitionResult as ai, hasEffect as aj, createErrorPlatformEvent as ak, withActorSelf as al, takeSpawnAllocationCounters as am, mergeActorIdCounters as an, createSpawnEffect as ao, initialMicrostep as ap, toStatePath as aq, isStateId as ar, getStateNodeByPath as as, getPersistedSnapshot as at, createRemoteActorRef as au, resolveReferencedActor as av, createInvokeTimeoutEvent as aw, parseGeneratedActorId as ax, ACTOR_REF_TYPE as ay, hasAmbientInspector as az, builtInActions as b, createTransitionEnqueue as c, deriveDeferredStarts as d, XSTATE_STOP as e, finalizeTransitionResult as f, XSTATE_TIMER as g, createSendToEffect as h, isLazyActorScope as i, isAtomicStateNode as j, createActor as k, createListenerLogic as l, matchesEventDescriptor as m, createSubscriptionLogic as n, listenerLogic as o, parseDelayToMilliseconds as p, getInitialSnapshot as q, resolveActionsWithContext as r, subscriptionLogic as s, toArray as t, getNextSnapshot as u, isMachineSnapshot as v, withActorScope as w, getStateNodes as x, getAllOwnEventDescriptors as y, matchesState as z };

package/dist/{createActor-1a3a1d14.development.cjs.js → createActor-f6e6146f.development.cjs.js}

@@ -220,6 +220,27 @@ const builtInActions = {
   }
 };
 
+const sourceKeyCaches = new WeakMap();
+
+/** @internal */
+function resolveRegisteredActorSource(actors, logic) {
+  let cache = sourceKeyCaches.get(actors);
+  if (!cache) {
+    cache = new Map();
+    for (const key of Object.keys(actors)) {
+      const registeredLogic = actors[key];
+      // Several source keys may intentionally share one implementation. The
+      // first key is its canonical persistence identity when spawning by the
+      // raw logic value, which cannot retain which alias was used to access it.
+      if (!cache.has(registeredLogic)) {
+        cache.set(registeredLogic, key);
+      }
+    }
+    sourceKeyCaches.set(actors, cache);
+  }
+  return cache.get(logic);
+}
+
 const subscriptions = /* #__PURE__ */new WeakMap();
 
 /**
@@ -667,21 +688,31 @@ function beginSpawnAllocation(actorScope) {
 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);
+function getRegisteredActors(actorScope) {
+  return actorScope.self.logic?.sources?.actors;
+}
+function resolveTransitionSpawnSource(actorScope, source) {
+  const registeredActors = getRegisteredActors(actorScope);
+  if (typeof source === 'string') {
+    const logic = registeredActors?.[source];
+    if (!logic) {
+      throw new Error(`Actor source '${source}' is not provided`);
     }
-    srcKeyCaches.set(registeredActors, cache);
+    return {
+      logic,
+      src: source
+    };
   }
-  return cache.get(logic);
+  if (!registeredActors) {
+    return {
+      logic: source,
+      src: undefined
+    };
+  }
+  return {
+    logic: source,
+    src: resolveRegisteredActorSource(registeredActors, source)
+  };
 }
 
 /**
@@ -829,17 +860,17 @@ function createTransitionEnqueue(actorScope, actions, internalEvents, actorSubsc
         internalEvents.push(raisedEvent);
       }
     },
-    spawn: (logic, options) => {
+    spawn: (source, options) => {
+      const {
+        logic,
+        src
+      } = resolveTransitionSpawnSource(actorScope, source);
       if (!createActors) {
         // TODO: replace this speculative placeholder with a typed inert actor ref.
         return {
-          id: options?.id ?? options?.registryKey ?? logic.id
+          id: options?.id ?? options?.registryKey ?? src ?? 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.
@@ -1274,6 +1305,45 @@ function parseDelayToMilliseconds(delay) {
   return parseDurationToMilliseconds(delay);
 }
 
+/**
+ * The ambiently installed system inspector. Set for the duration of a durable
+ * execution's transitions (`createDurable(..., { inspect })`), it makes the
+ * pure-transition machinery observable: freshly constructed runtime systems
+ * attach it, and snapshot systems created while it is set forward inspection
+ * to their base system instead of stubbing it out.
+ */
+let ambientInspector;
+
+/** @internal */
+function hasAmbientInspector() {
+  return ambientInspector !== undefined;
+}
+
+/** @internal */
+function getAmbientInspector() {
+  return ambientInspector;
+}
+
+/**
+ * Runs `fn` with systems it creates wired to `inspect` from construction, so
+ * creation-time inspection events (the root actor's own registration, actors
+ * spawned during the first transition) are observed too.
+ *
+ * @internal
+ */
+function withSystemInspector(inspect, fn) {
+  if (!inspect) {
+    return fn();
+  }
+  const previous = ambientInspector;
+  ambientInspector = inspect;
+  try {
+    return fn();
+  } finally {
+    ambientInspector = previous;
+  }
+}
+
 /** Snapshot-scoped actor identity and system view. @internal */
 
 const snapshotActorRefs = new WeakMap();
@@ -1336,6 +1406,7 @@ function getSnapshotChildren(snapshot) {
  * @internal
  */
 function createSnapshotSystem(baseSystem, children, baseState) {
+  const forwardInspection = hasAmbientInspector();
   const registeredActors = copyRegisteredActors(baseSystem, baseState);
   const keyedActors = new Map(baseState?.keyedActors ?? getKeyedActors(baseSystem));
   const reverseKeyedActors = new WeakMap();
@@ -1374,10 +1445,13 @@ function createSnapshotSystem(baseSystem, children, baseState) {
     },
     get: registryKey => keyedActors.get(registryKey),
     getAll: () => Object.fromEntries(keyedActors),
-    // Pure transition resolution must not leak topology inspection events into
-    // a live runtime system.
-    _hasInspectionObservers: () => false,
-    _sendInspectionEvent: () => {}
+    // Pure transition resolution must not leak topology inspection events
+    // into a live runtime system — planning branches stay silent. The one
+    // exception is a durable execution's own transitions (marked by the
+    // ambient inspector at creation time): there the pure path IS the
+    // execution, so inspection forwards to the base system's observers.
+    _hasInspectionObservers: forwardInspection ? () => baseSystem._hasInspectionObservers?.() ?? false : () => false,
+    _sendInspectionEvent: forwardInspection ? event => baseSystem._sendInspectionEvent(event) : () => {}
   });
   for (const [registryKey, actor] of keyedActors) {
     if (!actor) {
@@ -4405,6 +4479,10 @@ class RuntimeSystem {
     this._clock = options.clock;
     this._logger = options.logger;
     this.createActorRef = options.createActorRef;
+    const ambientInspector = getAmbientInspector();
+    if (ambientInspector) {
+      this.inspect(ambientInspector);
+    }
     this._snapshot = {
       _scheduledTimers: restoredSnapshot?.scheduler ?? emptyScheduledTimers,
       // System-level counters are process-local backstops; per-actor
@@ -5108,6 +5186,9 @@ class Actor {
     }
     this._inspectTransition(this._snapshot, event);
   }
+
+  /** @internal Emits the transition inspection event; used by the pure
+   * `transition()` path for snapshots driven outside a live actor. */
   _inspectTransition(snapshot, event) {
     if (this.system._hasInspectionObservers?.() ?? true) {
       this.system._sendInspectionEvent({
@@ -5714,6 +5795,7 @@ exports.getSnapshotActorRef = getSnapshotActorRef;
 exports.getStateNodeByPath = getStateNodeByPath;
 exports.getStateNodes = getStateNodes;
 exports.getTransitionResult = getTransitionResult;
+exports.hasAmbientInspector = hasAmbientInspector;
 exports.hasEffect = hasEffect;
 exports.initialMicrostep = initialMicrostep;
 exports.isAtomicStateNode = isAtomicStateNode;
@@ -5738,6 +5820,7 @@ exports.pathToStateValue = pathToStateValue;
 exports.reserveChildId = reserveChildId;
 exports.resolveActionsWithContext = resolveActionsWithContext;
 exports.resolveReferencedActor = resolveReferencedActor;
+exports.resolveRegisteredActorSource = resolveRegisteredActorSource;
 exports.resolveStateValue = resolveStateValue;
 exports.runStep = runStep;
 exports.setInertActorScopeSnapshot = setInertActorScopeSnapshot;
@@ -5754,3 +5837,4 @@ exports.transitionNode = transitionNode;
 exports.withActorScope = withActorScope;
 exports.withActorSelf = withActorSelf;
 exports.withExecutionIdentity = withExecutionIdentity;
+exports.withSystemInspector = withSystemInspector;

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

@@ -89,7 +89,6 @@ export declare class Actor<TLogic extends AnyActorLogic> implements ActorInstanc
     private _tryHandleExecutionError;
     private _next;
     private update;
-    private _inspectTransition;
     private _flushInitialEffects;
     /**
      * Subscribe an observer to an actor’s snapshot values.

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

@@ -1,7 +1,7 @@
 import { StandardSchemaV1 } from "./schema.types.js";
 import { StateMachine } from "./StateMachine.js";
 import { AnyActorRef, EventObject, AnyEventObject, Cast, MachineContext, ProvidedActor, StateValueFromStateSchema, ToChildren, MetaObject, StateSchema, DoNotInfer, RoutableStateId, Compute } from "./types.js";
-import { Sources, DelayMapFromNames, InferChildren, InferOutput, InferEvents, InferInternalEvents, Next_MachineConfig, Next_StateNodeConfig, ValidateDelayReferences, ValidateHistoryDefaults, ValidateStateTargets, ValidateTopLevelFinalOutputs, WidenLiterals, WithDefault } from "./types.v6.js";
+import { Sources, DelayMapFromNames, InferChildren, InferOutput, SchemaOrConfigOutput, InferEvents, InferInternalEvents, Next_MachineConfig, Next_StateNodeConfig, ValidateDelayReferences, ValidateHistoryDefaults, ValidateStateTargets, ValidateTopLevelFinalOutputs, WidenLiterals, WithDefault } from "./types.v6.js";
 type MergeChildren<TChildren extends Record<string, AnyActorRef | undefined>, TActor extends ProvidedActor> = [keyof TChildren] extends [never] ? Compute<ToChildren<TActor>> : Compute<TChildren>;
 type MachineIdentity<TConfig> = {
     readonly id: TConfig extends {
@@ -61,7 +61,7 @@ export declare function createMachine<TContextSchema extends StandardSchemaV1, c
 } & ValidateTopLevelFinalOutputs<TSS, InferOutput<TContextSchema, MachineContext>, InferEvents<TEventSchemaMap> | InferInternalEvents<TInternalEventSchemaMap>>): StateMachine<InferOutput<TContextSchema, MachineContext>, (InferEvents<TEventSchemaMap> | InferInternalEvents<TInternalEventSchemaMap>) | ([RoutableStateId<TSS>] extends [never] ? never : {
     type: 'xstate.route';
     to: RoutableStateId<TSS>;
-}), Cast<MergeChildren<InferChildren<TChildrenSchemaMap>, TActor>, Record<string, AnyActorRef | undefined>>, StateValueFromStateSchema<TSS>, TTag & string, TInput, InferOutput<TOutputSchema, unknown>, WithDefault<InferEvents<TEmittedSchemaMap>, AnyEventObject>, InferOutput<TMetaSchema, MetaObject>, // TMeta
+}), Cast<MergeChildren<InferChildren<TChildrenSchemaMap>, TActor>, Record<string, AnyActorRef | undefined>>, StateValueFromStateSchema<TSS>, TTag & string, TInput, SchemaOrConfigOutput<TOutputSchema, TSS>, WithDefault<InferEvents<TEmittedSchemaMap>, AnyEventObject>, InferOutput<TMetaSchema, MetaObject>, // TMeta
 TSS, // TStateSchema
 TActionMap, TActorMap, TGuardMap, DelayMapFromNames<TDelays, TDelayMap>, InferInternalEvents<TInternalEventSchemaMap>> & {
     states: TSS;
@@ -79,7 +79,7 @@ export declare function createMachine<TContext extends MachineContext = never, c
 } & ValidateTopLevelFinalOutputs<TSS, WidenLiterals<TContext>, InferEvents<TEventSchemaMap> | InferInternalEvents<TInternalEventSchemaMap>>): StateMachine<WidenLiterals<TContext>, (InferEvents<TEventSchemaMap> | InferInternalEvents<TInternalEventSchemaMap>) | ([RoutableStateId<TSS>] extends [never] ? never : {
     type: 'xstate.route';
     to: RoutableStateId<TSS>;
-}), Cast<MergeChildren<InferChildren<TChildrenSchemaMap>, TActor>, Record<string, AnyActorRef | undefined>>, StateValueFromStateSchema<TSS>, TTag & string, TInput, InferOutput<TOutputSchema, unknown>, WithDefault<InferEvents<TEmittedSchemaMap>, AnyEventObject>, InferOutput<TMetaSchema, MetaObject>, // TMeta
+}), Cast<MergeChildren<InferChildren<TChildrenSchemaMap>, TActor>, Record<string, AnyActorRef | undefined>>, StateValueFromStateSchema<TSS>, TTag & string, TInput, SchemaOrConfigOutput<TOutputSchema, TSS>, WithDefault<InferEvents<TEmittedSchemaMap>, AnyEventObject>, InferOutput<TMetaSchema, MetaObject>, // TMeta
 TSS, // TStateSchema
 TActionMap, TActorMap, TGuardMap, DelayMapFromNames<TDelays, TDelayMap>, InferInternalEvents<TInternalEventSchemaMap>> & {
     states: TSS;

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

@@ -1,6 +1,7 @@
 import { type EffectDescriptor } from "../effectDescriptor.js";
 import { type ActorSystemRuntime } from "../system.js";
-import type { AnyActor, AnyActorLogic, CustomExecutableActionObject, EventFromLogic, ExecutableActionObjectFromLogic, InputFrom, OutputFrom, SnapshotFrom } from "../types.js";
+import type { InspectionEvent } from "../inspection.js";
+import type { AnyActor, AnyActorLogic, AnyEventObject, CustomExecutableActionObject, EventFromLogic, ExecutableActionObjectFromLogic, InputFrom, OutputFrom, Snapshot, SnapshotFrom } from "../types.js";
 export interface DurableEffectMetadata {
     /** Stable within one durable execution. */
     id: string;
@@ -42,10 +43,11 @@ export interface DurableEffect<TEffect> extends DurableEffectMetadata {
  * operations keep their default local behavior.
  *
  * Events addressed to this execution's root actor do not reach `sendEvent`
- * during `executeEffects`: the execution captures them and resolves them
- * from that call for the durable loop to process before suspending. While
- * the loop is parked, a root-addressed event reaches `sendEvent` like any
- * other target, so the host enqueues it in its own mailbox.
+ * during `executeEffects`: the execution captures and retains them, and the
+ * execution's `waitForEvent()` hands them out before deferring to this
+ * adapter. While the loop is parked, a root-addressed event reaches
+ * `sendEvent` like any other target, so the host enqueues it in its own
+ * mailbox.
  */
 export interface DurableExecutionAdapter<TLogic extends AnyActorLogic> extends Partial<ActorSystemRuntime> {
     /**
@@ -62,8 +64,14 @@ export interface DurableExecutionAdapter<TLogic extends AnyActorLogic> extends P
      * source, input, event or target data beyond the runtime method arguments.
      */
     runtime?(metadata: DurableEffectMetadata, effect: ExecutableActionObjectFromLogic<TLogic>): Partial<ActorSystemRuntime>;
-    /** Waits durably for the next event addressed to this execution. */
-    waitForEvent(metadata: DurableWaitMetadata): EventFromLogic<TLogic> | PromiseLike<EventFromLogic<TLogic>>;
+    /**
+     * Waits durably for the next event addressed to this execution. Typed to
+     * also accept plain event objects: an adapter written against
+     * `AnyActorLogic` (a generic host library) cannot produce
+     * `EventFromLogic<TLogic>`, and the events a host relays are runtime data
+     * anyway — the execution narrows at its own boundary.
+     */
+    waitForEvent(metadata: DurableWaitMetadata): EventFromLogic<TLogic> | AnyEventObject | PromiseLike<EventFromLogic<TLogic> | AnyEventObject>;
     /** Index assigned to the first transition. Defaults to `0`. */
     transitionIndex?: number;
     /**
@@ -83,6 +91,13 @@ export declare class DurableExecutionCancelledError extends Error {
 export declare class DurableExecutionResumeError extends Error {
     constructor();
 }
+/**
+ * The snapshot type a durable execution hands back: the logic's own snapshot,
+ * intersected with the base `Snapshot` union so the `status`/`output`/`error`
+ * discriminant stays visible even when `TLogic` is an unresolved type
+ * parameter (a generic host library), where `SnapshotFrom` alone is opaque.
+ */
+export type DurableSnapshot<TLogic extends AnyActorLogic> = SnapshotFrom<TLogic> & Snapshot<OutputFrom<TLogic>>;
 export interface DurableExecution<TLogic extends AnyActorLogic> {
     /**
      * The logical address of this execution's root actor: the logic's own name,
@@ -101,11 +116,11 @@ export interface DurableExecution<TLogic extends AnyActorLogic> {
     /** Index assigned to the next transition. Persist this with checkpoints. */
     readonly nextTransitionIndex: number;
     initialTransition(...[input]: undefined extends InputFrom<TLogic> ? [input?: InputFrom<TLogic>] : [input: InputFrom<TLogic>]): [
-        snapshot: SnapshotFrom<TLogic>,
+        snapshot: DurableSnapshot<TLogic>,
         effects: DurableEffect<ExecutableActionObjectFromLogic<TLogic>>[]
     ];
     transition(snapshot: SnapshotFrom<TLogic>, event: EventFromLogic<TLogic>): [
-        snapshot: SnapshotFrom<TLogic>,
+        snapshot: DurableSnapshot<TLogic>,
         effects: DurableEffect<ExecutableActionObjectFromLogic<TLogic>>[]
     ];
     /**
@@ -113,8 +128,13 @@ export interface DurableExecution<TLogic extends AnyActorLogic> {
      * for addressing and inspection. `undefined` for snapshots this execution
      * has not seen (for example a freshly deserialized checkpoint that has not
      * been passed through `transition()` yet).
+     *
+     * With an `address`, returns the live actor at that logical address in the
+     * snapshot's actor tree instead — the root itself, one of its transitive
+     * children, or `undefined` when no live actor has that address (for
+     * example a timer firing for an actor that already completed).
      */
-    getActorRef(snapshot: SnapshotFrom<TLogic>): AnyActor | undefined;
+    getActorRef(snapshot: SnapshotFrom<TLogic>, address?: string): AnyActor | undefined;
     /**
      * Executes effects and resolves only when every runtime operation they
      * transitively initiated — including operations from live child actors
@@ -122,12 +142,18 @@ export interface DurableExecution<TLogic extends AnyActorLogic> {
      * failed operation rejects it. Operations are handed to the runtime one at
      * a time, in initiation order.
      *
-     * Resolves with the events addressed to this execution's root actor that
-     * were produced along the way, in order. Feed them back through
-     * `transition()` (and execute their effects) before durably waiting for an
-     * external event; `run()` does this automatically.
+     * Events addressed to this execution's root actor that were produced along
+     * the way are retained, in order, and handed out by `waitForEvent()`
+     * before it defers to the adapter — so the drive loop is just
+     * `transition(snapshot, await waitForEvent())` + `executeEffects`.
+     */
+    executeEffects(effects: readonly DurableEffect<ExecutableActionObjectFromLogic<TLogic>>[]): Promise<void>;
+    /**
+     * Resolves with the next event addressed to this execution's root actor:
+     * an event a prior `executeEffects` batch captured (an invoked actor
+     * completing, a child reporting up), or — once none are queued — whatever
+     * the adapter's durable wait produces.
      */
-    executeEffects(effects: readonly DurableEffect<ExecutableActionObjectFromLogic<TLogic>>[]): Promise<DurableRootEvent<EventFromLogic<TLogic>>[]>;
     waitForEvent(): Promise<EventFromLogic<TLogic>>;
     run(...[input]: undefined extends InputFrom<TLogic> ? [input?: InputFrom<TLogic>] : [input: InputFrom<TLogic>]): Promise<OutputFrom<TLogic>>;
 }
@@ -140,4 +166,13 @@ export interface DurableExecution<TLogic extends AnyActorLogic> {
  *
  * @experimental
  */
-export declare function createDurable<TLogic extends AnyActorLogic>(logic: TLogic, adapter: DurableExecutionAdapter<TLogic>): DurableExecution<TLogic>;
+export interface DurableExecutionOptions {
+    /**
+     * Observes the execution's inspection events — actor lifecycle, event
+     * routing, transitions — across the whole live actor tree. The host-side
+     * home for operation logs and instrumentation, so adapters stay pure
+     * physics.
+     */
+    inspect?: (inspectionEvent: InspectionEvent) => void;
+}
+export declare function createDurable<TLogic extends AnyActorLogic>(logic: TLogic, adapter: DurableExecutionAdapter<TLogic>, options?: DurableExecutionOptions): DurableExecution<TLogic>;

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

@@ -0,0 +1 @@
+export {};

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

@@ -5,7 +5,7 @@ import { type Actor, type RequiredActorOptionsKeys } from "./createActor.js";
 import { AnyActorRef, AnyActorLogic, ActorRefFromLogic, AnyStateNode, EventObject, AnyEventObject, EventDescriptor, ExtractEvent, MachineContext, ProvidedActor, RoutableStateId, StateSchema, StateValue, StateValueFromStateSchema, ToChildren, MetaObject, Cast, Compute, EnqueueObject, DoneActorEvent, DoneStateEvent, ErrorActorEvent, SystemRegistry, RegistryKeyForLogic, ActorOptions, Observer, Subscription, OutputArg, SnapshotEvent, SingleOrArray, AfterEvent, TimeoutEvent, ErrorEvent } from "./types.js";
 import { AnyActorSystem } from "./system.js";
 import { InspectionEvent } from "./inspection.js";
-import { ActionSchemas, DelayMapFromNames, GuardSchemas, InferChildren, InferActions, InferGuards, Sources, InferOutput, InferEvents, InferInternalEvents, Next_MachineConfig, Next_InvokeConfig, Next_StateNodeConfig, Next_TransitionConfigOrTarget, ValidateHistoryDefaults, ValidateStateTargets, WithDefault } from "./types.v6.js";
+import { ActionSchemas, DelayMapFromNames, GuardSchemas, InferChildren, InferActions, InferGuards, Sources, InferOutput, InferEvents, InferInternalEvents, Next_MachineConfig, Next_InvokeConfig, Next_StateNodeConfig, Next_TransitionConfigOrTarget, OutputFromConfig, ValidateHistoryDefaults, ValidateStateTargets, WithDefault } from "./types.v6.js";
 export type SetupConfig<TSchemas extends SetupSchemas, TStates extends Record<string, SetupStateSchema>, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TValidator extends ActorLogicValidator | undefined = ActorLogicValidator | undefined> = {
     validator?: TValidator;
     schemas?: TSchemas & SetupSchemas;
@@ -199,6 +199,20 @@ type SetupInput<TSchemas, TInputSchema extends StandardSchemaV1> = [
 type SetupOutput<TSchemas, TOutputSchema extends StandardSchemaV1> = [
     SetupSchema<TSchemas, 'output'>
 ] extends [never] ? InferOutput<TOutputSchema, unknown> : InferOutput<SetupSchema<TSchemas, 'output'>, unknown>;
+/**
+ * Whether an output schema was declared, either in `setup({ schemas })` or in
+ * the machine config's own `schemas.output`. A declared schema is always
+ * authoritative for the machine's output type.
+ */
+type HasOutputSchema<TSchemas, TOutputSchema extends StandardSchemaV1> = [
+    SetupSchema<TSchemas, 'output'>
+] extends [never] ? StandardSchemaV1 extends TOutputSchema ? false : true : true;
+/**
+ * The machine's output type. A declared output schema wins; otherwise the type
+ * is inferred from the config's `output` property (a mapper's return type, or
+ * the static value's type).
+ */
+type SetupOrConfigOutput<TSchemas, TOutputSchema extends StandardSchemaV1, TConfig> = HasOutputSchema<TSchemas, TOutputSchema> extends true ? SetupOutput<TSchemas, TOutputSchema> : OutputFromConfig<TConfig, SetupOutput<TSchemas, TOutputSchema>>;
 type SetupEmitted<TSchemas, TEmittedSchemaMap extends Record<string, StandardSchemaV1>> = [SetupSchemaMap<TSchemas, 'emitted'>] extends [never] ? WithDefault<InferEvents<TEmittedSchemaMap>, AnyEventObject> : WithDefault<InferEvents<SetupSchemaMap<TSchemas, 'emitted'>>, AnyEventObject>;
 type SetupMeta<TSchemas, TMetaSchema extends StandardSchemaV1> = [
     SetupSchema<TSchemas, 'meta'>
@@ -410,7 +424,7 @@ type StateTransitionFunction<TStateSchemas extends Record<string, SetupStateSche
     guards: TGuardMap;
     delays: TDelayMap;
     input: TInput;
-} & OutputArg<TExpressionEvent>, enq: EnqueueObject<TEvent, TEmitted, TSystemRegistry>) => StateTransitionResult<TStateSchemas, TContext, TContextShape, TMeta, TExpressionEvent, TChildren, TActionMap, TActorMap, TGuardMap, TDelayMap, TSystemRegistry, false> | void;
+} & OutputArg<TExpressionEvent>, enq: EnqueueObject<TEvent, TEmitted, TSystemRegistry, TActorMap>) => StateTransitionResult<TStateSchemas, TContext, TContextShape, TMeta, TExpressionEvent, TChildren, TActionMap, TActorMap, TGuardMap, TDelayMap, TSystemRegistry, false> | void;
 type StateTransitionResult<TStateSchemas extends Record<string, SetupStateSchema>, TContext extends MachineContext, TContextShape, TMeta extends MetaObject, TExpressionEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TSystemRegistry extends SystemRegistry, TAllowContextMapper extends boolean> = {
     target?: never;
     context?: StateTransitionContext<TAllowContextMapper, TContext, TContextShape, TContextShape, TContext, TExpressionEvent, TChildren, TActionMap, TActorMap, TGuardMap, TDelayMap, TSystemRegistry>;
@@ -485,7 +499,7 @@ export interface SetupReturn<TStates extends Record<string, SetupStateSchema> =
         to: RoutableStateId<Cast<TConfig, StateSchema>>;
     }), Cast<MergeChildren<SetupChildren<TSchemas, TChildrenSchemaMap>, TActor>, Record<string, AnyActorRef | undefined>>, StateValueFromStateSchema<MergeStateSchema<Cast<TConfig, StateSchema>, SetupStatesToStateSchema<TStates>>>, TTag & string, [
         SetupSchema<TSchemas, 'input'>
-    ] extends [never] ? TInput : SetupInput<TSchemas, TInputSchema>, SetupOutput<TSchemas, TOutputSchema>, SetupEmitted<TSchemas, TEmittedSchemaMap>, SetupMeta<TSchemas, TMetaSchema>, MergeStateSchema<Cast<TConfig, StateSchema>, SetupStatesToStateSchema<TStates>>, MergeSourceMaps<SetupActions<TSchemas, TSetupActionMap>, MergeSourceMaps<InferActions<TActionSchemaMap>, TActionMap>>, MergeSourceMaps<TSetupActorMap, TActorMap>, MergeSourceMaps<SetupGuards<TSchemas, TSetupGuardMap>, MergeSourceMaps<InferGuards<TGuardSchemaMap>, TGuardMap>>, DelayMapFromNames<TSetupDelays | TDelays, MergeSourceMaps<TSetupDelayMap, TDelayMap>>, SetupInternalEvents<TSchemas, TInternalEventSchemaMap>> & MachineIdentity<TConfig>;
+    ] extends [never] ? TInput : SetupInput<TSchemas, TInputSchema>, SetupOrConfigOutput<TSchemas, TOutputSchema, TConfig>, SetupEmitted<TSchemas, TEmittedSchemaMap>, SetupMeta<TSchemas, TMetaSchema>, MergeStateSchema<Cast<TConfig, StateSchema>, SetupStatesToStateSchema<TStates>>, MergeSourceMaps<SetupActions<TSchemas, TSetupActionMap>, MergeSourceMaps<InferActions<TActionSchemaMap>, TActionMap>>, MergeSourceMaps<TSetupActorMap, TActorMap>, MergeSourceMaps<SetupGuards<TSchemas, TSetupGuardMap>, MergeSourceMaps<InferGuards<TGuardSchemaMap>, TGuardMap>>, DelayMapFromNames<TSetupDelays | TDelays, MergeSourceMaps<TSetupDelayMap, TDelayMap>>, SetupInternalEvents<TSchemas, TInternalEventSchemaMap>> & MachineIdentity<TConfig>;
     /**
      * Creates a state node config bound to a specific setup-declared state,
      * addressed by a dotted path (e.g. `'loading'` or `'parent.child'`). The

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

@@ -31,6 +31,7 @@ export interface ExecutionIdentity {
     systemId: string;
     nextSessionId: number;
 }
+export { hasAmbientInspector, withSystemInspector } from "./inspectionAmbient.js";
 /**
  * Runtime operations used to execute effects.
  *
@@ -124,4 +125,3 @@ export declare function createRuntimeSystem<T extends ActorSystemInfo>(rootActor
     snapshot?: unknown;
     createActorRef: ActorSystem<T>['createActorRef'];
 }): ActorSystem<T>;
-export {};