xstate 6.0.0-alpha.41 → 6.0.0-alpha.44

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

@@ -1,7 +1,7 @@
 'use strict';
 
-var createActor = require('./createActor-20615484.development.cjs.js');
-var dist_xstateActors = require('./index-d42efc07.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) => {
@@ -418,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() {
@@ -462,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;
@@ -600,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}'.`
@@ -638,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

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

@@ -1,5 +1,5 @@
-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-c97c04c9.development.esm.js';
-import { g as assertValid } from './index-b5b1b2bc.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) => {
@@ -416,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() {
@@ -460,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;
@@ -598,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}'.`
@@ -636,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

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

@@ -1,5 +1,5 @@
-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-a3f7750f.esm.js';
-import { g as assertValid } from './index-a8ce72f1.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) => {
@@ -398,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() {
@@ -442,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;
@@ -569,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}'.`
@@ -607,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

package/dist/{StateMachine-8e73d782.cjs.js → StateMachine-fcc48e11.cjs.js}

@@ -1,7 +1,7 @@
 'use strict';
 
-var createActor = require('./createActor-f3afd774.cjs.js');
-var dist_xstateActors = require('./index-7fd92683.cjs.js');
+var createActor = require('./createActor-9538c7f8.cjs.js');
+var dist_xstateActors = require('./index-ba7170ba.cjs.js');
 
 function createSpawner(actorScope, actors, spawnedChildren) {
   return (src, options) => {
@@ -400,6 +400,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() {
@@ -444,6 +454,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;
@@ -571,9 +587,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}'.`
@@ -609,7 +626,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

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

@@ -183,118 +183,6 @@ function reportUnhandledError(err) {
 
 const symbolObservable = (() => typeof Symbol === 'function' && Symbol.observable || '@@observable')();
 
-const emptySubscription = {
-  unsubscribe() {}
-};
-const restoreHint = 'or restore this snapshot with embedded children on the runtime that owns them.';
-
-/** @internal */
-function isRemoteActorRef(actorRef) {
-  return actorRef._remote === true;
-}
-
-/**
- * The lifecycle-only snapshot a remote handle exposes. `active` is accurate
- * by construction: a completion removes the child from its parent's
- * `children`, so a handle only exists while the child is presumed active,
- * and the terminal result arrives as a completion event instead of a
- * snapshot. Full snapshots are a co-location capability.
- */
-const remoteSnapshot = Object.freeze({
-  status: 'active',
-  output: undefined,
-  error: undefined
-});
-
-/**
- * Creates a location-transparent handle to an actor whose state lives with
- * another runtime. The handle is constructed from identity alone — no lookup
- * — and every send routes through the system's runtime; its state is not
- * synchronously readable.
- *
- * The surface is deliberately minimal: it covers every member the runtime
- * reaches for a restored child (send/_send, lifecycle via start/_stop and
- * system.stopActor, persistence, subscribe/on as inert subscriptions).
- * Members that only make sense for a co-located actor (public stop(),
- * select(), trigger) throw a descriptive error rather than being absent, so
- * calling one reports what went wrong instead of a bare TypeError. Observable
- * interop and _processingStatus are omitted entirely.
- *
- * @internal
- */
-function createRemoteActorRef(system, options) {
-  const handle = {
-    _remote: true,
-    // Self-reference so context persistence recognizes the handle as an
-    // actor reference instead of recursing into it.
-    ref: undefined,
-    id: options.id,
-    address: options.address,
-    src: options.src,
-    registryKey: options.registryKey,
-    // A remote handle does not know the child's incarnation; the runtime that
-    // owns the child is the authority on completion staleness — unless the
-    // host supplied an incarnation token, which lets this side drop stale
-    // completions and lets journaled sends name the intended incarnation.
-    sessionId: undefined,
-    _incarnation: options.incarnation,
-    system,
-    _parent: options.parent,
-    // Round-trips through persistence verbatim (undefined stays undefined,
-    // so re-persisting is byte-stable); a remote handle cannot act on it
-    // locally.
-    _syncSnapshot: options.syncSnapshot,
-    send(event) {
-      void system.sendEvent(undefined, ref, event);
-    },
-    _send(event) {
-      throw new Error(`Remote actor '${options.address}' has no local mailbox to receive "${event.type}". Its state lives with another runtime; install a runtime that can reach it (via \`createDurable\`'s adapter runtime operations, or \`system.runtime\`) before sending, ${restoreHint}`);
-    },
-    getSnapshot() {
-      return remoteSnapshot;
-    },
-    getPersistedSnapshot() {
-      throw new Error(`Cannot persist remote actor '${options.address}' from here: its state lives with the runtime that owns it. Persist it there, ${restoreHint}`);
-    },
-    start() {},
-    _stop() {},
-    stop() {
-      throw new Error(`Cannot stop remote actor '${options.address}' directly: stopping is a co-located operation. Stop it through the system runtime that owns it (\`system.stopActor(ref)\`), ${restoreHint}`);
-    },
-    select() {
-      throw new Error(`Cannot select from remote actor '${options.address}': its snapshot is not synchronously readable because its state lives with another runtime. Read it on the runtime that owns it, ${restoreHint}`);
-    },
-    get trigger() {
-      throw new Error(`Remote actor '${options.address}' has no \`trigger\` shorthand: it requires a co-located actor. Use \`send(...)\`, which routes through the system runtime.`);
-    },
-    // Observation is a co-location capability: a remote handle never emits,
-    // so subscriptions are inert rather than errors — generic observers may
-    // attach to any ref.
-    subscribe() {
-      return emptySubscription;
-    },
-    on() {
-      return emptySubscription;
-    },
-    _isRunning() {
-      return false;
-    },
-    // The same shape Actor.toJSON produces, so serialized snapshots carry
-    // one actor-reference marker whether a child is co-located or remote.
-    toJSON() {
-      return {
-        xstate$type: ACTOR_REF_TYPE,
-        id: options.id,
-        address: options.address,
-        src: options.src
-      };
-    }
-  };
-  const ref = handle;
-  handle.ref = ref;
-  return ref;
-}
-
 function assertSendToEvent(event) {
   if (typeof event === 'string') {
     throw new Error(// eslint-disable-next-line @typescript-eslint/restrict-template-expressions
@@ -2010,13 +1898,10 @@ function matchesActorSession(event, snapshot, actorId) {
   if (!child || !('sessionId' in event)) {
     return true;
   }
-  if (isRemoteActorRef(child)) {
-    // Without a host-supplied incarnation token the runtime that owns the
-    // child is the authority on staleness; with one, a completion from a
-    // different incarnation of the same address is dropped here.
-    return child._incarnation === undefined || child._incarnation === event.sessionId;
-  }
-  return child.sessionId === event.sessionId;
+  // One rule: a ref that knows its incarnation compares it; a remote handle
+  // without a host-supplied token (sessionId undefined) defers to the
+  // runtime that owns the child.
+  return child.sessionId === undefined || child.sessionId === event.sessionId;
 }
 function normalizeLegacyInternalEvent(event, machine) {
   if (event.type === 'xstate.done.actor' || event.type === 'xstate.error.actor' || event.type === 'xstate.snapshot.actor' || event.type === 'xstate.done.state' || event.type === 'xstate.after' || event.type === 'xstate.timeout' || event.type === 'xstate.timeout.actor') {
@@ -3223,11 +3108,7 @@ function macrostep(snapshot, event, actorScope, internalQueue, initialMicrosteps
     // The same staleness rule matchesActorSession applies to transition
     // selection: a completion from a different incarnation must not remove
     // the still-running child either.
-    if (isRemoteActorRef(child)) {
-      if (child._incarnation !== undefined && child._incarnation !== sessionId) {
-        return;
-      }
-    } else if (child.sessionId !== sessionId) {
+    if (child.sessionId !== undefined && child.sessionId !== sessionId) {
       return;
     }
     const children = {
@@ -3519,6 +3400,118 @@ function evaluateCandidate(candidate, event, snapshot, stateNode, actorScope, se
   return true;
 }
 
+const emptySubscription = {
+  unsubscribe() {}
+};
+const restoreHint = 'or restore this snapshot with embedded children on the runtime that owns them.';
+
+/** @internal */
+function isRemoteActorRef(actorRef) {
+  return actorRef._remote === true;
+}
+
+/**
+ * The lifecycle-only snapshot a remote handle exposes. `active` is accurate
+ * by construction: a completion removes the child from its parent's
+ * `children`, so a handle only exists while the child is presumed active,
+ * and the terminal result arrives as a completion event instead of a
+ * snapshot. Full snapshots are a co-location capability.
+ */
+const remoteSnapshot = Object.freeze({
+  status: 'active',
+  output: undefined,
+  error: undefined
+});
+
+/**
+ * Creates a location-transparent handle to an actor whose state lives with
+ * another runtime. The handle is constructed from identity alone — no lookup
+ * — and every send routes through the system's runtime; its state is not
+ * synchronously readable.
+ *
+ * The surface is deliberately minimal: it covers every member the runtime
+ * reaches for a restored child (send/_send, lifecycle via start/_stop and
+ * system.stopActor, persistence, subscribe/on as inert subscriptions).
+ * Members that only make sense for a co-located actor (public stop(),
+ * select(), trigger) throw a descriptive error rather than being absent, so
+ * calling one reports what went wrong instead of a bare TypeError. Observable
+ * interop and _processingStatus are omitted entirely.
+ *
+ * @internal
+ */
+function createRemoteActorRef(system, options) {
+  const handle = {
+    _remote: true,
+    // Self-reference so context persistence recognizes the handle as an
+    // actor reference instead of recursing into it.
+    ref: undefined,
+    id: options.id,
+    address: options.address,
+    src: options.src,
+    registryKey: options.registryKey,
+    // The host-supplied incarnation token, when present: the owner's
+    // sessionId for this child, letting this side drop stale completions and
+    // journaled sends name the intended incarnation. Without one the handle
+    // does not know the child's incarnation and the owning runtime is the
+    // authority on staleness.
+    sessionId: options.incarnation,
+    system,
+    _parent: options.parent,
+    // Round-trips through persistence verbatim (undefined stays undefined,
+    // so re-persisting is byte-stable); a remote handle cannot act on it
+    // locally.
+    _syncSnapshot: options.syncSnapshot,
+    send(event) {
+      void system.sendEvent(undefined, ref, event);
+    },
+    _send(event) {
+      throw new Error(`Remote actor '${options.address}' has no local mailbox to receive "${event.type}". Its state lives with another runtime; install a runtime that can reach it (via \`createDurable\`'s adapter runtime operations, or \`system.runtime\`) before sending, ${restoreHint}`);
+    },
+    getSnapshot() {
+      return remoteSnapshot;
+    },
+    getPersistedSnapshot() {
+      throw new Error(`Cannot persist remote actor '${options.address}' from here: its state lives with the runtime that owns it. Persist it there, ${restoreHint}`);
+    },
+    start() {},
+    _stop() {},
+    stop() {
+      throw new Error(`Cannot stop remote actor '${options.address}' directly: stopping is a co-located operation. Stop it through the system runtime that owns it (\`system.stopActor(ref)\`), ${restoreHint}`);
+    },
+    select() {
+      throw new Error(`Cannot select from remote actor '${options.address}': its snapshot is not synchronously readable because its state lives with another runtime. Read it on the runtime that owns it, ${restoreHint}`);
+    },
+    get trigger() {
+      throw new Error(`Remote actor '${options.address}' has no \`trigger\` shorthand: it requires a co-located actor. Use \`send(...)\`, which routes through the system runtime.`);
+    },
+    // Observation is a co-location capability: a remote handle never emits,
+    // so subscriptions are inert rather than errors — generic observers may
+    // attach to any ref.
+    subscribe() {
+      return emptySubscription;
+    },
+    on() {
+      return emptySubscription;
+    },
+    _isRunning() {
+      return false;
+    },
+    // The same shape Actor.toJSON produces, so serialized snapshots carry
+    // one actor-reference marker whether a child is co-located or remote.
+    toJSON() {
+      return {
+        xstate$type: ACTOR_REF_TYPE,
+        id: options.id,
+        address: options.address,
+        src: options.src
+      };
+    }
+  };
+  const ref = handle;
+  handle.ref = ref;
+  return ref;
+}
+
 const emptySnapshotRecord = Object.freeze({});
 function compactSnapshotRecord(value) {
   if (value === emptySnapshotRecord) {
@@ -3704,10 +3697,12 @@ function getPersistedSnapshot(snapshot, options) {
         snapshot: child.getPersistedSnapshot(options)
       } : {
         remote: true,
-        // Round-trips verbatim: the host that owns the child injects the
-        // token; XState never stamps one (a local sessionId would make
-        // persisted snapshots nondeterministic across replays).
-        incarnation: child._incarnation
+        // A remote handle's sessionId IS the host-supplied incarnation
+        // token, round-tripped verbatim. A local child persisted by
+        // address never stamps its own sessionId: that value is this
+        // incarnation's, not a durable identity, and it would make
+        // persisted snapshots nondeterministic across replays.
+        incarnation: isRemoteActorRef(child) ? child.sessionId : undefined
       }),
       src: child.src,
       registryKey: child.registryKey,
@@ -4129,14 +4124,21 @@ async function runStep(actor, key, exec, sendSelf = event => void actor.system.s
  * @experimental
  */
 function deliverEvent(source, target, event) {
+  assertEventCanBeSent(source, target, event);
+  const runtimeTarget = target;
+  runtimeTarget._lastSourceRef = source;
+  runtimeTarget._send(event);
+}
+
+/**
+ * Ensures internal events cannot cross an actor boundary from an external
+ * sender. Host runtimes must call this before taking ownership of delivery.
+ */
+function assertEventCanBeSent(source, target, event) {
   const runtimeTarget = target;
-  // The same guard local delivery has always applied: internal events may
-  // only originate from the actor itself, whichever runtime delivers them.
   if (source !== target && runtimeTarget.logic?.isInternalEventType?.(event.type)) {
     throw new Error(`Internal event "${event.type}" cannot be sent to actor "${target.id}" from outside.`);
   }
-  runtimeTarget._lastSourceRef = source;
-  runtimeTarget._send(event);
 }
 
 /**
@@ -4198,6 +4200,32 @@ function createSystemId() {
   return `${systemIdPrefix}:${(nextSystemId++).toString(36)}`;
 }
 
+/**
+ * The identity a durable execution pins on every system its transitions
+ * create. Shared across all transitions (and replays) of one execution, so
+ * session ids become a deterministic function of actor-creation order:
+ * `<executionId>:0`, `<executionId>:1`, … A replayed execution re-creates
+ * the same session ids, so journaled completion events (which carry the
+ * producing incarnation's `sessionId`) still match the children the replay
+ * re-creates.
+ */
+
+let ambientExecutionIdentity;
+
+/** @internal Runs `fn` with systems it creates pinned to `identity`. */
+function withExecutionIdentity(identity, fn) {
+  if (!identity) {
+    return fn();
+  }
+  const previous = ambientExecutionIdentity;
+  ambientExecutionIdentity = identity;
+  try {
+    return fn();
+  } finally {
+    ambientExecutionIdentity = previous;
+  }
+}
+
 /**
  * Derives the deterministic id prefix for a generated actor id from its actor
  * source: the registered source key when the source is a string, the logic's
@@ -4314,9 +4342,10 @@ function bookSessionId(system) {
 
 /** @internal Every operation of `ActorSystemRuntime`, for runtime wrappers. */
 const RUNTIME_OPERATIONS = ['spawnActor', 'startActor', 'stopActor', 'terminateActor', 'emitEvent', 'scheduleTimer', 'cancelTimer', 'cancelAllTimers', 'deadLetter'
-// `runStep` and `sendEvent` are deliberately absent: durable executions
-// wire them separately, since a step awaits other runtime operations and
-// root-addressed sends are captured per batch.
+// `runLogic`, `runStep` and `sendEvent` are deliberately absent: durable
+// executions wire them separately, since logic bodies and steps await
+// other runtime operations and root-addressed sends are captured per
+// batch.
 ];
 const emptyScheduledTimers = Object.freeze({});
 function createScheduledTimerId(actor, id) {
@@ -4362,7 +4391,7 @@ class RuntimeSystem {
   }
   constructor(_rootActor, options) {
     this._rootActor = _rootActor;
-    this._identity = {
+    this._identity = ambientExecutionIdentity ?? {
       systemId: createSystemId(),
       nextSessionId: 0
     };
@@ -4566,6 +4595,7 @@ class RuntimeSystem {
     terminateActor(actor, termination);
   }
   sendEvent(source, target, event) {
+    assertEventCanBeSent(source, target, event);
     // Record for the inspection `sent[]` facet regardless of which runtime
     // delivers, so host runtimes keep inspection parity.
     this._recordSent(source, target, event);
@@ -4605,6 +4635,13 @@ class RuntimeSystem {
     }
     return runStep(actor, key, exec);
   }
+  runLogic(actor, exec) {
+    const override = this.runtime?.runLogic;
+    if (override) {
+      return override(actor, exec);
+    }
+    return exec();
+  }
   scheduleTimer(source, id, delay) {
     const override = this.runtime?.scheduleTimer;
     if (override) {
@@ -5685,6 +5722,7 @@ exports.isInFinalState = isInFinalState;
 exports.isInertActorScope = isInertActorScope;
 exports.isLazyActorScope = isLazyActorScope;
 exports.isMachineSnapshot = isMachineSnapshot;
+exports.isRemoteActorRef = isRemoteActorRef;
 exports.isStateId = isStateId;
 exports.listenerLogic = listenerLogic;
 exports.macrostep = macrostep;
@@ -5715,3 +5753,4 @@ exports.toTransitionConfigArray = toTransitionConfigArray;
 exports.transitionNode = transitionNode;
 exports.withActorScope = withActorScope;
 exports.withActorSelf = withActorSelf;
+exports.withExecutionIdentity = withExecutionIdentity;