xstate 6.0.0-alpha.40 → 6.0.0-alpha.43

package/dist/{StateMachine-76ee1d6e.development.cjs.js → StateMachine-16d7ee93.development.cjs.js}

@@ -1,13 +1,21 @@
 'use strict';
 
-var createActor = require('./createActor-c0f78b8a.development.cjs.js');
-var dist_xstateActors = require('./index-3d1368f7.development.cjs.js');
+var createActor = require('./createActor-1a3a1d14.development.cjs.js');
+var dist_xstateActors = require('./index-e0ba4813.development.cjs.js');
 
 function createSpawner(actorScope, actors, spawnedChildren) {
   return (src, options) => {
     const referencedSrc = Object.entries(actors).find(([, logic]) => logic === src)?.[0];
+    // Generated ids come from the same transaction allocator as `enq.spawn`,
+    // so context-factory allocations persist with the snapshot and never
+    // collide with later spawns.
+    const id = options?.id ?? createActor.allocateChildId(actorScope, referencedSrc ?? src).id;
+    if (options?.id !== undefined) {
+      createActor.assertChildIdFree(actorScope, options.id);
+      createActor.reserveChildId(actorScope, options.id);
+    }
     const actor = actorScope.system.createActorRef(src, {
-      id: options?.id,
+      id,
       parent: actorScope.self,
       syncSnapshot: options?.syncSnapshot,
       input: options?.input,
@@ -410,6 +418,16 @@ function formatInitialTransition(stateNode, _target) {
 }
 
 const STATE_IDENTIFIER = '#';
+function findEventSchema(schemas, eventType) {
+  if (!schemas) {
+    return undefined;
+  }
+  if (Object.hasOwn(schemas, eventType)) {
+    return schemas[eventType];
+  }
+  const descriptor = Object.keys(schemas).find(key => createActor.matchesEventDescriptor(eventType, key));
+  return descriptor === undefined ? undefined : schemas[descriptor];
+}
 let emptyCanActor;
 let emptyCanActorScope;
 function getEmptyCanActor() {
@@ -454,6 +472,12 @@ class StateMachine {
   config, sources, validator) {
     this.config = config;
     this.validator = validator;
+    /**
+     * @internal Type-only marker for the actor's internal event protocol. Not
+     * `declare` (the build's babel pipeline rejects declare class fields); the
+     * one `undefined` property this emits per machine instance is inert.
+     */
+    this._internalEventType = void 0;
     /** The machine's own version. */
     this.version = void 0;
     this.schemas = void 0;
@@ -592,9 +616,10 @@ class StateMachine {
           }
           const event = value;
           const eventSchemas = this.schemas?.events;
+          const internalEventSchemas = this.schemas?.internalEvents;
           const isFrameworkEvent = event.type.startsWith('xstate.') || event.type.startsWith('@xstate.');
-          const schema = eventSchemas && Object.hasOwn(eventSchemas, event.type) ? eventSchemas[event.type] : undefined;
-          if (eventSchemas && !schema && !isFrameworkEvent) {
+          const schema = findEventSchema(internalEventSchemas, event.type) ?? findEventSchema(eventSchemas, event.type);
+          if ((eventSchemas || internalEventSchemas) && !schema && !isFrameworkEvent) {
             return {
               issues: [{
                 message: `Unknown event '${event.type}' for machine '${this.id}' version '${this.version}'.`
@@ -630,7 +655,7 @@ class StateMachine {
         }
       }
     };
-    this.internalEventDescriptors = this.config.internalEvents ?? [];
+    this.internalEventDescriptors = [...Object.keys(this.schemas?.internalEvents ?? {}), ...(this.config.internalEvents ?? [])];
     this.options = {
       maxIterations: Infinity,
       ...this.config.options
@@ -726,6 +751,7 @@ class StateMachine {
     if (usesInertScope) {
       createActor.setInertActorScopeSnapshot(resolvedActorScope, snapshot, false);
     }
+    createActor.beginSpawnAllocation(resolvedActorScope);
     const fastSnapshot = this._transitionFast(snapshot, event, resolvedActorScope);
     if (fastSnapshot) {
       if (usesInertScope) {
@@ -921,6 +947,14 @@ class StateMachine {
           ...nextState.children,
           ...children
         };
+        // Commit the transaction counters so context-factory allocations
+        // persist with the snapshot: a freed id is never handed out again
+        // after a restore or in a fresh replay process. (The spawner already
+        // registered each child for string-id resolution.)
+        const counters = createActor.takeSpawnAllocationCounters(actorScope);
+        if (counters) {
+          nextState._nextActorIds = createActor.mergeActorIdCounters(nextState._nextActorIds, counters);
+        }
       }
       return nextState;
     }
@@ -944,6 +978,7 @@ class StateMachine {
     }
     const usesInertScope = !actorScope;
     const resolvedActorScope = actorScope ?? createActor.createInertActorScope(this);
+    createActor.beginSpawnAllocation(resolvedActorScope);
     const initEvent = createActor.createInitEvent(input); // TODO: fix;
     const internalQueue = [];
     const preInitialState = this._getPreInitialState(resolvedActorScope, initEvent);
@@ -1035,6 +1070,31 @@ class StateMachine {
     const snapshotChildren = snapshotData.children;
     for (const actorId of Object.keys(snapshotChildren)) {
       const actorData = snapshotChildren[actorId];
+      if (actorData.remote === true && actorData.address !== undefined) {
+        if (typeof actorData.src !== 'string') {
+          // Fail loudly instead of fabricating a source key that hosts would
+          // route by.
+          throw new Error(`Unable to restore remote child '${actorId}': a child referenced by address requires a registered source key.`);
+        }
+        // The child's state lives with another runtime; restore a
+        // location-transparent handle constructed from its identity alone.
+        // The handle keeps its persisted address verbatim: the owning
+        // runtime's identity for the child wins over the local parent chain.
+        const handle = createActor.createRemoteActorRef(resolvedActorScope.system, {
+          id: actorId,
+          address: actorData.address,
+          src: actorData.src,
+          parent: resolvedActorScope.self,
+          registryKey: actorData.registryKey,
+          syncSnapshot: actorData.syncSnapshot,
+          incarnation: actorData.incarnation
+        });
+        if (actorData.registryKey) {
+          resolvedActorScope.system._set(actorData.registryKey, handle);
+        }
+        children[actorId] = handle;
+        continue;
+      }
       const childState = actorData.snapshot;
       const src = actorData.src;
       const logic = typeof src === 'string' ? createActor.resolveReferencedActor(this, src) : src;
@@ -1130,12 +1190,30 @@ class StateMachine {
     const nodes = Array.from(createActor.getAllStateNodes(createActor.getStateNodes(this.root, snapshotData.value)));
     const {
       version: _persistedSnapshotVersion,
+      // The legacy system-wide counter: superseded by per-snapshot
+      // `_nextActorIds` plus the child-id fold below; dropped so old and new
+      // snapshots round-trip to the same shape.
+      _nextActorId: _legacyNextActorId,
       ...persistedRest
     } = snapshot;
+    // Fold generated-shaped child ids into the counters as a floor: snapshots
+    // persisted before per-actor counters (or hand-crafted ones) still must
+    // never reuse a live child's id.
+    let restoredCounters = persistedRest._nextActorIds;
+    for (const childId of Object.keys(snapshotChildren)) {
+      const generated = createActor.parseGeneratedActorId(childId);
+      if (generated && (restoredCounters?.[generated.prefix] ?? 0) <= generated.index) {
+        restoredCounters = {
+          ...restoredCounters,
+          [generated.prefix]: generated.index + 1
+        };
+      }
+    }
     const restoredSnapshot = createActor.createMachineSnapshot({
       ...persistedRest,
       children,
       timers,
+      _nextActorIds: restoredCounters,
       _nodes: nodes,
       value: snapshotData.value,
       historyValue: revivedHistoryValue,
@@ -1150,7 +1228,7 @@ class StateMachine {
       for (const key of Object.keys(contextPart)) {
         const value = contextPart[key];
         if (value && typeof value === 'object') {
-          if ('xstate$$type' in value && value.xstate$$type === createActor.$$ACTOR_TYPE) {
+          if ('xstate$type' in value && value.xstate$type === createActor.ACTOR_REF_TYPE) {
             contextPart[key] = children[value.id];
             continue;
           }

package/dist/{StateMachine-f8c7feca.development.esm.js → StateMachine-1ea29688.development.esm.js}

@@ -1,11 +1,19 @@
-import { S as STATE_DELIMITER, I as mapValues, t as toArray, J as createInvokeId, K as getDelayedTransitions, L as getEventDescriptorKey, M as getCandidates, N as evaluateCandidate, O as formatTransition, P as NULL_EVENT, Q as toTransitionConfigArray, R as createInvokeTimeoutEventId, T as matchesActorSession, U as formatRouteTransitions, V as resolveStateValue, W as getAllStateNodes, v as getStateNodes, Y as createMachineSnapshot, Z as isInFinalState, _ as createInertActorScope, $ as setInertActorScopeSnapshot, a0 as attachSnapshotActorRef, a1 as macrostep, a2 as isInertActorScope, a3 as setSnapshotActorRef, a4 as cloneMachineSnapshot, a5 as transitionNode, e as XSTATE_TIMER, m as matchesEventDescriptor, a6 as getTransitionResult, a7 as hasEffect, a8 as createErrorPlatformEvent, a9 as withActorSelf, r as resolveActionsWithContext, F as createInitEvent, aa as createSpawnEffect, ab as initialMicrostep, ac as toStatePath, ad as isStateId, ae as getStateNodeByPath, af as getPersistedSnapshot, ag as resolveReferencedActor, ah as createInvokeTimeoutEvent, ai as $$ACTOR_TYPE, j as createActor } from './createActor-2a03d4b2.development.esm.js';
-import { g as assertValid } from './index-17f889df.development.esm.js';
+import { Q as allocateChildId, R as assertChildIdFree, S as reserveChildId, T as STATE_DELIMITER, U as mapValues, t as toArray, V as createInvokeId, W as getDelayedTransitions, Y as getEventDescriptorKey, Z as getCandidates, _ as evaluateCandidate, $ as formatTransition, a0 as NULL_EVENT, a1 as toTransitionConfigArray, a2 as createInvokeTimeoutEventId, a3 as matchesActorSession, a4 as formatRouteTransitions, a5 as resolveStateValue, a6 as getAllStateNodes, x as getStateNodes, a7 as createMachineSnapshot, a8 as isInFinalState, a9 as createInertActorScope, aa as setInertActorScopeSnapshot, a as beginSpawnAllocation, ab as attachSnapshotActorRef, ac as macrostep, ad as isInertActorScope, ae as setSnapshotActorRef, af as cloneMachineSnapshot, ag as transitionNode, g as XSTATE_TIMER, m as matchesEventDescriptor, ah as getTransitionResult, ai as hasEffect, aj as createErrorPlatformEvent, ak as withActorSelf, r as resolveActionsWithContext, al as takeSpawnAllocationCounters, am as mergeActorIdCounters, K as createInitEvent, an as createSpawnEffect, ao as initialMicrostep, ap as toStatePath, aq as isStateId, ar as getStateNodeByPath, as as getPersistedSnapshot, at as createRemoteActorRef, au as resolveReferencedActor, av as createInvokeTimeoutEvent, aw as parseGeneratedActorId, ax as ACTOR_REF_TYPE, k as createActor } from './createActor-f9cc6590.development.esm.js';
+import { g as assertValid } from './index-f284cc7b.development.esm.js';
 
 function createSpawner(actorScope, actors, spawnedChildren) {
   return (src, options) => {
     const referencedSrc = Object.entries(actors).find(([, logic]) => logic === src)?.[0];
+    // Generated ids come from the same transaction allocator as `enq.spawn`,
+    // so context-factory allocations persist with the snapshot and never
+    // collide with later spawns.
+    const id = options?.id ?? allocateChildId(actorScope, referencedSrc ?? src).id;
+    if (options?.id !== undefined) {
+      assertChildIdFree(actorScope, options.id);
+      reserveChildId(actorScope, options.id);
+    }
     const actor = actorScope.system.createActorRef(src, {
-      id: options?.id,
+      id,
       parent: actorScope.self,
       syncSnapshot: options?.syncSnapshot,
       input: options?.input,
@@ -408,6 +416,16 @@ function formatInitialTransition(stateNode, _target) {
 }
 
 const STATE_IDENTIFIER = '#';
+function findEventSchema(schemas, eventType) {
+  if (!schemas) {
+    return undefined;
+  }
+  if (Object.hasOwn(schemas, eventType)) {
+    return schemas[eventType];
+  }
+  const descriptor = Object.keys(schemas).find(key => matchesEventDescriptor(eventType, key));
+  return descriptor === undefined ? undefined : schemas[descriptor];
+}
 let emptyCanActor;
 let emptyCanActorScope;
 function getEmptyCanActor() {
@@ -452,6 +470,12 @@ class StateMachine {
   config, sources, validator) {
     this.config = config;
     this.validator = validator;
+    /**
+     * @internal Type-only marker for the actor's internal event protocol. Not
+     * `declare` (the build's babel pipeline rejects declare class fields); the
+     * one `undefined` property this emits per machine instance is inert.
+     */
+    this._internalEventType = void 0;
     /** The machine's own version. */
     this.version = void 0;
     this.schemas = void 0;
@@ -590,9 +614,10 @@ class StateMachine {
           }
           const event = value;
           const eventSchemas = this.schemas?.events;
+          const internalEventSchemas = this.schemas?.internalEvents;
           const isFrameworkEvent = event.type.startsWith('xstate.') || event.type.startsWith('@xstate.');
-          const schema = eventSchemas && Object.hasOwn(eventSchemas, event.type) ? eventSchemas[event.type] : undefined;
-          if (eventSchemas && !schema && !isFrameworkEvent) {
+          const schema = findEventSchema(internalEventSchemas, event.type) ?? findEventSchema(eventSchemas, event.type);
+          if ((eventSchemas || internalEventSchemas) && !schema && !isFrameworkEvent) {
             return {
               issues: [{
                 message: `Unknown event '${event.type}' for machine '${this.id}' version '${this.version}'.`
@@ -628,7 +653,7 @@ class StateMachine {
         }
       }
     };
-    this.internalEventDescriptors = this.config.internalEvents ?? [];
+    this.internalEventDescriptors = [...Object.keys(this.schemas?.internalEvents ?? {}), ...(this.config.internalEvents ?? [])];
     this.options = {
       maxIterations: Infinity,
       ...this.config.options
@@ -724,6 +749,7 @@ class StateMachine {
     if (usesInertScope) {
       setInertActorScopeSnapshot(resolvedActorScope, snapshot, false);
     }
+    beginSpawnAllocation(resolvedActorScope);
     const fastSnapshot = this._transitionFast(snapshot, event, resolvedActorScope);
     if (fastSnapshot) {
       if (usesInertScope) {
@@ -919,6 +945,14 @@ class StateMachine {
           ...nextState.children,
           ...children
         };
+        // Commit the transaction counters so context-factory allocations
+        // persist with the snapshot: a freed id is never handed out again
+        // after a restore or in a fresh replay process. (The spawner already
+        // registered each child for string-id resolution.)
+        const counters = takeSpawnAllocationCounters(actorScope);
+        if (counters) {
+          nextState._nextActorIds = mergeActorIdCounters(nextState._nextActorIds, counters);
+        }
       }
       return nextState;
     }
@@ -942,6 +976,7 @@ class StateMachine {
     }
     const usesInertScope = !actorScope;
     const resolvedActorScope = actorScope ?? createInertActorScope(this);
+    beginSpawnAllocation(resolvedActorScope);
     const initEvent = createInitEvent(input); // TODO: fix;
     const internalQueue = [];
     const preInitialState = this._getPreInitialState(resolvedActorScope, initEvent);
@@ -1033,6 +1068,31 @@ class StateMachine {
     const snapshotChildren = snapshotData.children;
     for (const actorId of Object.keys(snapshotChildren)) {
       const actorData = snapshotChildren[actorId];
+      if (actorData.remote === true && actorData.address !== undefined) {
+        if (typeof actorData.src !== 'string') {
+          // Fail loudly instead of fabricating a source key that hosts would
+          // route by.
+          throw new Error(`Unable to restore remote child '${actorId}': a child referenced by address requires a registered source key.`);
+        }
+        // The child's state lives with another runtime; restore a
+        // location-transparent handle constructed from its identity alone.
+        // The handle keeps its persisted address verbatim: the owning
+        // runtime's identity for the child wins over the local parent chain.
+        const handle = createRemoteActorRef(resolvedActorScope.system, {
+          id: actorId,
+          address: actorData.address,
+          src: actorData.src,
+          parent: resolvedActorScope.self,
+          registryKey: actorData.registryKey,
+          syncSnapshot: actorData.syncSnapshot,
+          incarnation: actorData.incarnation
+        });
+        if (actorData.registryKey) {
+          resolvedActorScope.system._set(actorData.registryKey, handle);
+        }
+        children[actorId] = handle;
+        continue;
+      }
       const childState = actorData.snapshot;
       const src = actorData.src;
       const logic = typeof src === 'string' ? resolveReferencedActor(this, src) : src;
@@ -1128,12 +1188,30 @@ class StateMachine {
     const nodes = Array.from(getAllStateNodes(getStateNodes(this.root, snapshotData.value)));
     const {
       version: _persistedSnapshotVersion,
+      // The legacy system-wide counter: superseded by per-snapshot
+      // `_nextActorIds` plus the child-id fold below; dropped so old and new
+      // snapshots round-trip to the same shape.
+      _nextActorId: _legacyNextActorId,
       ...persistedRest
     } = snapshot;
+    // Fold generated-shaped child ids into the counters as a floor: snapshots
+    // persisted before per-actor counters (or hand-crafted ones) still must
+    // never reuse a live child's id.
+    let restoredCounters = persistedRest._nextActorIds;
+    for (const childId of Object.keys(snapshotChildren)) {
+      const generated = parseGeneratedActorId(childId);
+      if (generated && (restoredCounters?.[generated.prefix] ?? 0) <= generated.index) {
+        restoredCounters = {
+          ...restoredCounters,
+          [generated.prefix]: generated.index + 1
+        };
+      }
+    }
     const restoredSnapshot = createMachineSnapshot({
       ...persistedRest,
       children,
       timers,
+      _nextActorIds: restoredCounters,
       _nodes: nodes,
       value: snapshotData.value,
       historyValue: revivedHistoryValue,
@@ -1148,7 +1226,7 @@ class StateMachine {
       for (const key of Object.keys(contextPart)) {
         const value = contextPart[key];
         if (value && typeof value === 'object') {
-          if ('xstate$$type' in value && value.xstate$$type === $$ACTOR_TYPE) {
+          if ('xstate$type' in value && value.xstate$type === ACTOR_REF_TYPE) {
             contextPart[key] = children[value.id];
             continue;
           }

package/dist/{StateMachine-6082c3cf.esm.js → StateMachine-b13b4b09.esm.js}

@@ -1,11 +1,19 @@
-import { S as STATE_DELIMITER, I as mapValues, t as toArray, J as createInvokeId, K as getDelayedTransitions, L as getEventDescriptorKey, M as getCandidates, N as evaluateCandidate, O as formatTransition, P as NULL_EVENT, Q as toTransitionConfigArray, R as createInvokeTimeoutEventId, T as matchesActorSession, U as formatRouteTransitions, V as resolveStateValue, W as getAllStateNodes, v as getStateNodes, Y as createMachineSnapshot, Z as isInFinalState, _ as createInertActorScope, $ as setInertActorScopeSnapshot, a0 as attachSnapshotActorRef, a1 as macrostep, a2 as isInertActorScope, a3 as setSnapshotActorRef, a4 as cloneMachineSnapshot, a5 as transitionNode, e as XSTATE_TIMER, m as matchesEventDescriptor, a6 as getTransitionResult, a7 as hasEffect, a8 as createErrorPlatformEvent, a9 as withActorSelf, r as resolveActionsWithContext, F as createInitEvent, aa as createSpawnEffect, ab as initialMicrostep, ac as toStatePath, ad as isStateId, ae as getStateNodeByPath, af as getPersistedSnapshot, ag as resolveReferencedActor, ah as createInvokeTimeoutEvent, ai as $$ACTOR_TYPE, j as createActor } from './createActor-a211c276.esm.js';
-import { g as assertValid } from './index-7020402e.esm.js';
+import { Q as allocateChildId, R as assertChildIdFree, S as reserveChildId, T as STATE_DELIMITER, U as mapValues, t as toArray, V as createInvokeId, W as getDelayedTransitions, Y as getEventDescriptorKey, Z as getCandidates, _ as evaluateCandidate, $ as formatTransition, a0 as NULL_EVENT, a1 as toTransitionConfigArray, a2 as createInvokeTimeoutEventId, a3 as matchesActorSession, a4 as formatRouteTransitions, a5 as resolveStateValue, a6 as getAllStateNodes, x as getStateNodes, a7 as createMachineSnapshot, a8 as isInFinalState, a9 as createInertActorScope, aa as setInertActorScopeSnapshot, a as beginSpawnAllocation, ab as attachSnapshotActorRef, ac as macrostep, ad as isInertActorScope, ae as setSnapshotActorRef, af as cloneMachineSnapshot, ag as transitionNode, g as XSTATE_TIMER, m as matchesEventDescriptor, ah as getTransitionResult, ai as hasEffect, aj as createErrorPlatformEvent, ak as withActorSelf, r as resolveActionsWithContext, al as takeSpawnAllocationCounters, am as mergeActorIdCounters, K as createInitEvent, an as createSpawnEffect, ao as initialMicrostep, ap as toStatePath, aq as isStateId, ar as getStateNodeByPath, as as getPersistedSnapshot, at as createRemoteActorRef, au as resolveReferencedActor, av as createInvokeTimeoutEvent, aw as parseGeneratedActorId, ax as ACTOR_REF_TYPE, k as createActor } from './createActor-973c72ad.esm.js';
+import { g as assertValid } from './index-b478f443.esm.js';
 
 function createSpawner(actorScope, actors, spawnedChildren) {
   return (src, options) => {
     const referencedSrc = Object.entries(actors).find(([, logic]) => logic === src)?.[0];
+    // Generated ids come from the same transaction allocator as `enq.spawn`,
+    // so context-factory allocations persist with the snapshot and never
+    // collide with later spawns.
+    const id = options?.id ?? allocateChildId(actorScope, referencedSrc ?? src).id;
+    if (options?.id !== undefined) {
+      assertChildIdFree(actorScope, options.id);
+      reserveChildId(actorScope, options.id);
+    }
     const actor = actorScope.system.createActorRef(src, {
-      id: options?.id,
+      id,
       parent: actorScope.self,
       syncSnapshot: options?.syncSnapshot,
       input: options?.input,
@@ -390,6 +398,16 @@ function formatInitialTransition(stateNode, _target) {
 }
 
 const STATE_IDENTIFIER = '#';
+function findEventSchema(schemas, eventType) {
+  if (!schemas) {
+    return undefined;
+  }
+  if (Object.hasOwn(schemas, eventType)) {
+    return schemas[eventType];
+  }
+  const descriptor = Object.keys(schemas).find(key => matchesEventDescriptor(eventType, key));
+  return descriptor === undefined ? undefined : schemas[descriptor];
+}
 let emptyCanActor;
 let emptyCanActorScope;
 function getEmptyCanActor() {
@@ -434,6 +452,12 @@ class StateMachine {
   config, sources, validator) {
     this.config = config;
     this.validator = validator;
+    /**
+     * @internal Type-only marker for the actor's internal event protocol. Not
+     * `declare` (the build's babel pipeline rejects declare class fields); the
+     * one `undefined` property this emits per machine instance is inert.
+     */
+    this._internalEventType = void 0;
     /** The machine's own version. */
     this.version = void 0;
     this.schemas = void 0;
@@ -561,9 +585,10 @@ class StateMachine {
           }
           const event = value;
           const eventSchemas = this.schemas?.events;
+          const internalEventSchemas = this.schemas?.internalEvents;
           const isFrameworkEvent = event.type.startsWith('xstate.') || event.type.startsWith('@xstate.');
-          const schema = eventSchemas && Object.hasOwn(eventSchemas, event.type) ? eventSchemas[event.type] : undefined;
-          if (eventSchemas && !schema && !isFrameworkEvent) {
+          const schema = findEventSchema(internalEventSchemas, event.type) ?? findEventSchema(eventSchemas, event.type);
+          if ((eventSchemas || internalEventSchemas) && !schema && !isFrameworkEvent) {
             return {
               issues: [{
                 message: `Unknown event '${event.type}' for machine '${this.id}' version '${this.version}'.`
@@ -599,7 +624,7 @@ class StateMachine {
         }
       }
     };
-    this.internalEventDescriptors = this.config.internalEvents ?? [];
+    this.internalEventDescriptors = [...Object.keys(this.schemas?.internalEvents ?? {}), ...(this.config.internalEvents ?? [])];
     this.options = {
       maxIterations: Infinity,
       ...this.config.options
@@ -695,6 +720,7 @@ class StateMachine {
     if (usesInertScope) {
       setInertActorScopeSnapshot(resolvedActorScope, snapshot, false);
     }
+    beginSpawnAllocation(resolvedActorScope);
     const fastSnapshot = this._transitionFast(snapshot, event, resolvedActorScope);
     if (fastSnapshot) {
       if (usesInertScope) {
@@ -890,6 +916,14 @@ class StateMachine {
           ...nextState.children,
           ...children
         };
+        // Commit the transaction counters so context-factory allocations
+        // persist with the snapshot: a freed id is never handed out again
+        // after a restore or in a fresh replay process. (The spawner already
+        // registered each child for string-id resolution.)
+        const counters = takeSpawnAllocationCounters(actorScope);
+        if (counters) {
+          nextState._nextActorIds = mergeActorIdCounters(nextState._nextActorIds, counters);
+        }
       }
       return nextState;
     }
@@ -913,6 +947,7 @@ class StateMachine {
     }
     const usesInertScope = !actorScope;
     const resolvedActorScope = actorScope ?? createInertActorScope(this);
+    beginSpawnAllocation(resolvedActorScope);
     const initEvent = createInitEvent(input); // TODO: fix;
     const internalQueue = [];
     const preInitialState = this._getPreInitialState(resolvedActorScope, initEvent);
@@ -1004,6 +1039,31 @@ class StateMachine {
     const snapshotChildren = snapshotData.children;
     for (const actorId of Object.keys(snapshotChildren)) {
       const actorData = snapshotChildren[actorId];
+      if (actorData.remote === true && actorData.address !== undefined) {
+        if (typeof actorData.src !== 'string') {
+          // Fail loudly instead of fabricating a source key that hosts would
+          // route by.
+          throw new Error(`Unable to restore remote child '${actorId}': a child referenced by address requires a registered source key.`);
+        }
+        // The child's state lives with another runtime; restore a
+        // location-transparent handle constructed from its identity alone.
+        // The handle keeps its persisted address verbatim: the owning
+        // runtime's identity for the child wins over the local parent chain.
+        const handle = createRemoteActorRef(resolvedActorScope.system, {
+          id: actorId,
+          address: actorData.address,
+          src: actorData.src,
+          parent: resolvedActorScope.self,
+          registryKey: actorData.registryKey,
+          syncSnapshot: actorData.syncSnapshot,
+          incarnation: actorData.incarnation
+        });
+        if (actorData.registryKey) {
+          resolvedActorScope.system._set(actorData.registryKey, handle);
+        }
+        children[actorId] = handle;
+        continue;
+      }
       const childState = actorData.snapshot;
       const src = actorData.src;
       const logic = typeof src === 'string' ? resolveReferencedActor(this, src) : src;
@@ -1096,12 +1156,30 @@ class StateMachine {
     const nodes = Array.from(getAllStateNodes(getStateNodes(this.root, snapshotData.value)));
     const {
       version: _persistedSnapshotVersion,
+      // The legacy system-wide counter: superseded by per-snapshot
+      // `_nextActorIds` plus the child-id fold below; dropped so old and new
+      // snapshots round-trip to the same shape.
+      _nextActorId: _legacyNextActorId,
       ...persistedRest
     } = snapshot;
+    // Fold generated-shaped child ids into the counters as a floor: snapshots
+    // persisted before per-actor counters (or hand-crafted ones) still must
+    // never reuse a live child's id.
+    let restoredCounters = persistedRest._nextActorIds;
+    for (const childId of Object.keys(snapshotChildren)) {
+      const generated = parseGeneratedActorId(childId);
+      if (generated && (restoredCounters?.[generated.prefix] ?? 0) <= generated.index) {
+        restoredCounters = {
+          ...restoredCounters,
+          [generated.prefix]: generated.index + 1
+        };
+      }
+    }
     const restoredSnapshot = createMachineSnapshot({
       ...persistedRest,
       children,
       timers,
+      _nextActorIds: restoredCounters,
       _nodes: nodes,
       value: snapshotData.value,
       historyValue: revivedHistoryValue,
@@ -1116,7 +1194,7 @@ class StateMachine {
       for (const key of Object.keys(contextPart)) {
         const value = contextPart[key];
         if (value && typeof value === 'object') {
-          if ('xstate$$type' in value && value.xstate$$type === $$ACTOR_TYPE) {
+          if ('xstate$type' in value && value.xstate$type === ACTOR_REF_TYPE) {
             contextPart[key] = children[value.id];
             continue;
           }