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

package/dist/{createActor-f3afd774.cjs.js → createActor-9538c7f8.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(`Only event objects may be used with sendTo`);
@@ -2002,13 +1890,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') {
@@ -3205,11 +3090,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 = {
@@ -3501,6 +3382,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) {
@@ -3680,10 +3673,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,
@@ -4096,14 +4091,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);
 }
 
 /**
@@ -4165,6 +4167,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
@@ -4281,9 +4309,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) {
@@ -4329,7 +4358,7 @@ class RuntimeSystem {
   }
   constructor(_rootActor, options) {
     this._rootActor = _rootActor;
-    this._identity = {
+    this._identity = ambientExecutionIdentity ?? {
       systemId: createSystemId(),
       nextSessionId: 0
     };
@@ -4533,6 +4562,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);
@@ -4569,6 +4599,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) {
@@ -5643,6 +5680,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;
@@ -5673,3 +5711,4 @@ exports.toTransitionConfigArray = toTransitionConfigArray;
 exports.transitionNode = transitionNode;
 exports.withActorScope = withActorScope;
 exports.withActorSelf = withActorSelf;
+exports.withExecutionIdentity = withExecutionIdentity;