xstate 6.0.0-alpha.49 → 6.0.0-alpha.50

package/dist/{createActor-268165d4.esm.js → createActor-ad3a1abe.esm.js}

@@ -498,6 +498,25 @@ function createEmitEffect(actorScope, event) {
     args: []
   };
 }
+function execDeadLetterEffect(runtime = this.target.system) {
+  return runtime.deadLetter(this.source, this.target, this.event, this.reason, this.detail);
+}
+
+/** @internal Creates a dead-letter effect for a boundary-rejected event. */
+function createDeadLetterEffect(actorScope, source, event, reason, detail) {
+  return {
+    kind: 'builtin',
+    type: '@xstate.deadLetter',
+    exec: execDeadLetterEffect,
+    source,
+    target: actorScope.self,
+    event,
+    reason,
+    detail,
+    params: undefined,
+    args: []
+  };
+}
 
 /** @internal Creates a directly executable user effect. */
 function createCustomEffect(type, action, params) {
@@ -4225,21 +4244,42 @@ async function runStep(actor, key, exec, sendSelf = event => void actor.system.s
  * @experimental
  */
 function deliverEvent(source, target, event) {
-  assertEventCanBeSent(source, target, event);
+  if (rejectUndeliverableEvent(source, target, event)) {
+    return;
+  }
   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.
+ * Returns the boundary error preventing this delivery, if any: an internal
+ * event type cannot cross an actor boundary from an external sender.
  */
-function assertEventCanBeSent(source, target, event) {
+function getEventBoundaryError(source, target, event) {
   const runtimeTarget = target;
   if (source !== target && runtimeTarget.logic?.isInternalEventType?.(event.type)) {
-    throw new Error(`Internal event "${event.type}" cannot be sent to actor "${target.id}" from outside.`);
+    return new Error(`Internal event "${event.type}" cannot be sent to actor "${target.id}" from outside.`);
+  }
+  return undefined;
+}
+
+/**
+ * Rejects an event that must not cross the delivery boundary — an internal
+ * event type sent from outside its owning actor — by reporting it as a dead
+ * letter. Returns `true` when the event was rejected and must not be
+ * delivered. Host runtimes must call this before taking ownership of
+ * delivery.
+ */
+function rejectUndeliverableEvent(source, target, event) {
+  const error = getEventBoundaryError(source, target, event);
+  if (error) {
+    void target.system.deadLetter(source, target, event, 'internalEvent', {
+      error
+    });
+    return true;
   }
+  return false;
 }
 
 /**
@@ -4440,6 +4480,19 @@ function bookSessionId(system) {
  * other: install a different one via `system.runtime` (for durable hosts,
  * through `createDurable`'s adapter runtime operations).
  */
+/**
+ * Why an event was not delivered: `'invalidEvent'` (payload failed its
+ * declared schema), `'internalEvent'` (an internal event type sent from
+ * outside its owning actor) or `'stopped'` (the target actor already
+ * stopped). Hosts may report additional reasons.
+ */
+
+/** Extra detail attached to a dead letter. */
+
+/**
+ * Describes an event that was rejected at the delivery boundary instead of
+ * being delivered to its target actor (a dead letter).
+ */
 
 /** @internal Every operation of `ActorSystemRuntime`, for runtime wrappers. */
 const RUNTIME_OPERATIONS = ['spawnActor', 'startActor', 'stopActor', 'terminateActor', 'emitEvent', 'scheduleTimer', 'cancelTimer', 'cancelAllTimers', 'deadLetter'
@@ -4502,6 +4555,7 @@ class RuntimeSystem {
     this._clock = void 0;
     this._logger = void 0;
     this.createActorRef = void 0;
+    this._onRejectedEvent = options.onRejectedEvent;
     const restoredSnapshot = typeof options.snapshot === 'object' && options.snapshot !== null ? options.snapshot : undefined;
     this._clock = options.clock;
     this._logger = options.logger;
@@ -4700,7 +4754,9 @@ class RuntimeSystem {
     terminateActor(actor, termination);
   }
   sendEvent(source, target, event) {
-    assertEventCanBeSent(source, target, event);
+    if (rejectUndeliverableEvent(source, target, event)) {
+      return;
+    }
     // Record for the inspection `sent[]` facet regardless of which runtime
     // delivers, so host runtimes keep inspection parity.
     this._recordSent(source, target, event);
@@ -4717,17 +4773,29 @@ class RuntimeSystem {
     }
     source._emit(event);
   }
-  deadLetter(source, target, event, reason) {
+  deadLetter(source, target, event, reason, detail) {
     this._sendInspectionEvent({
       type: '@xstate.deadletter',
       actorRef: target,
       sourceRef: source,
       event,
-      reason
+      reason,
+      issues: detail?.issues,
+      error: detail?.error
+    });
+    this._onRejectedEvent?.({
+      event,
+      targetRef: target,
+      targetId: target.id,
+      sourceRef: source,
+      eventOrigin: source ? 'actor' : 'external',
+      reason,
+      issues: detail?.issues,
+      error: detail?.error
     });
     const override = this.runtime?.deadLetter;
     if (override) {
-      return override(source, target, event, reason);
+      return override(source, target, event, reason, detail);
     }
   }
   runStep(actor, key, exec) {
@@ -4974,7 +5042,8 @@ class Actor {
       clock,
       logger,
       snapshot: resolvedOptions.snapshot ?? resolvedOptions.state,
-      createActorRef
+      createActorRef,
+      onRejectedEvent: resolvedOptions.onRejectedEvent
     });
     if (!parent && resolvedOptions._systemRef && !resolvedOptions._systemRef.current) {
       resolvedOptions._systemRef.current = this.system;
@@ -5755,4 +5824,4 @@ function createActor(logic, options) {
   return new Actor(logic, options);
 }
 
-export { matchesActorSession as $, Actor as A, XSTATE_LOGIC_EFFECT_START as B, XSTATE_LOGIC_EFFECT_RESOLVE as C, XSTATE_LOGIC_EFFECT_REJECT as D, finalizeTransitionResult as E, createEmitEffect as F, createSendToEffect as G, XSTATE_INIT as H, withActorScope as I, XSTATE_TIMER as J, isLazyActorScope as K, resolveRegisteredActorSource as L, allocateChildId as M, assertChildIdFree as N, reserveChildId as O, mapValues as P, createInvokeId as Q, getDelayedTransitions as R, STATE_DELIMITER as S, getEventDescriptorKey as T, getCandidates as U, evaluateCandidate as V, formatTransition as W, XSTATE_STOP as X, NULL_EVENT as Y, toTransitionConfigArray as Z, createInvokeTimeoutEventId as _, createListenerLogic as a, formatRouteTransitions as a0, resolveStateValue as a1, getAllStateNodes as a2, createMachineSnapshot as a3, isInFinalState as a4, createInertActorScope as a5, setInertActorScopeSnapshot as a6, beginSpawnAllocation as a7, attachSnapshotActorRef as a8, macrostep as a9, getAllOwnEvents as aA, matchesEvent as aB, encodeAddressSegment as aC, getRootActorId as aD, RUNTIME_OPERATIONS as aE, withSystemInspector as aF, getSnapshotActorRef as aG, withExecutionIdentity as aH, isInertActorScope as aa, setSnapshotActorRef as ab, cloneMachineSnapshot as ac, transitionNode as ad, getTransitionResult as ae, hasEffect as af, createErrorPlatformEvent as ag, withActorSelf as ah, resolveActionsWithContext as ai, takeSpawnAllocationCounters as aj, mergeActorIdCounters as ak, createSpawnEffect as al, initialMicrostep as am, toStatePath as an, isStateId as ao, getStateNodeByPath as ap, getPersistedSnapshot as aq, createRemoteActorRef as ar, resolveReferencedActor as as, createInvokeTimeoutEvent as at, parseGeneratedActorId as au, ACTOR_REF_TYPE as av, hasAmbientInspector as aw, getProperAncestors as ax, isRemoteActorRef as ay, getActorIdPrefix as az, createSubscriptionLogic as b, createActor as c, getNextSnapshot as d, isMachineSnapshot as e, getStateNodes as f, getInitialSnapshot as g, getAllOwnEventDescriptors as h, isAtomicStateNode as i, matchesState as j, checkStateIn as k, listenerLogic as l, matchesEventDescriptor as m, pathToStateValue as n, toObserver as o, parseDelayToMilliseconds as p, executeEffects as q, isBuiltInExecutableAction as r, subscriptionLogic as s, toArray as t, deliverEvent as u, runStep as v, stopActor as w, terminateActor as x, createInitEvent as y, createCustomEffect as z };
+export { createInvokeTimeoutEventId as $, Actor as A, createCustomEffect as B, XSTATE_LOGIC_EFFECT_START as C, XSTATE_LOGIC_EFFECT_RESOLVE as D, XSTATE_LOGIC_EFFECT_REJECT as E, finalizeTransitionResult as F, createEmitEffect as G, createSendToEffect as H, XSTATE_INIT as I, withActorScope as J, XSTATE_TIMER as K, isLazyActorScope as L, resolveRegisteredActorSource as M, allocateChildId as N, assertChildIdFree as O, reserveChildId as P, mapValues as Q, createInvokeId as R, STATE_DELIMITER as S, getDelayedTransitions as T, getEventDescriptorKey as U, getCandidates as V, evaluateCandidate as W, XSTATE_STOP as X, formatTransition as Y, NULL_EVENT as Z, toTransitionConfigArray as _, createListenerLogic as a, matchesActorSession as a0, formatRouteTransitions as a1, resolveStateValue as a2, getAllStateNodes as a3, createMachineSnapshot as a4, isInFinalState as a5, createInertActorScope as a6, setInertActorScopeSnapshot as a7, beginSpawnAllocation as a8, attachSnapshotActorRef as a9, getActorIdPrefix as aA, getAllOwnEvents as aB, matchesEvent as aC, encodeAddressSegment as aD, getRootActorId as aE, RUNTIME_OPERATIONS as aF, withSystemInspector as aG, getSnapshotActorRef as aH, withExecutionIdentity as aI, macrostep as aa, isInertActorScope as ab, setSnapshotActorRef as ac, cloneMachineSnapshot as ad, transitionNode as ae, getTransitionResult as af, hasEffect as ag, createErrorPlatformEvent as ah, withActorSelf as ai, resolveActionsWithContext as aj, takeSpawnAllocationCounters as ak, mergeActorIdCounters as al, createSpawnEffect as am, initialMicrostep as an, toStatePath as ao, isStateId as ap, getStateNodeByPath as aq, getPersistedSnapshot as ar, createRemoteActorRef as as, resolveReferencedActor as at, createInvokeTimeoutEvent as au, parseGeneratedActorId as av, ACTOR_REF_TYPE as aw, hasAmbientInspector as ax, getProperAncestors as ay, isRemoteActorRef as az, createSubscriptionLogic as b, createActor as c, getNextSnapshot as d, isMachineSnapshot as e, getStateNodes as f, getInitialSnapshot as g, getAllOwnEventDescriptors as h, isAtomicStateNode as i, matchesState as j, checkStateIn as k, listenerLogic as l, matchesEventDescriptor as m, pathToStateValue as n, toObserver as o, parseDelayToMilliseconds as p, executeEffects as q, isBuiltInExecutableAction as r, subscriptionLogic as s, toArray as t, deliverEvent as u, runStep as v, stopActor as w, terminateActor as x, createInitEvent as y, createDeadLetterEffect as z };

package/dist/{createActor-a1e0dffb.development.cjs.js → createActor-ea9a560c.development.cjs.js}

@@ -501,6 +501,25 @@ function createEmitEffect(actorScope, event) {
     args: []
   };
 }
+function execDeadLetterEffect(runtime = this.target.system) {
+  return runtime.deadLetter(this.source, this.target, this.event, this.reason, this.detail);
+}
+
+/** @internal Creates a dead-letter effect for a boundary-rejected event. */
+function createDeadLetterEffect(actorScope, source, event, reason, detail) {
+  return {
+    kind: 'builtin',
+    type: '@xstate.deadLetter',
+    exec: execDeadLetterEffect,
+    source,
+    target: actorScope.self,
+    event,
+    reason,
+    detail,
+    params: undefined,
+    args: []
+  };
+}
 
 /** @internal Creates a directly executable user effect. */
 function createCustomEffect(type, action, params) {
@@ -4257,21 +4276,42 @@ async function runStep(actor, key, exec, sendSelf = event => void actor.system.s
  * @experimental
  */
 function deliverEvent(source, target, event) {
-  assertEventCanBeSent(source, target, event);
+  if (rejectUndeliverableEvent(source, target, event)) {
+    return;
+  }
   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.
+ * Returns the boundary error preventing this delivery, if any: an internal
+ * event type cannot cross an actor boundary from an external sender.
  */
-function assertEventCanBeSent(source, target, event) {
+function getEventBoundaryError(source, target, event) {
   const runtimeTarget = target;
   if (source !== target && runtimeTarget.logic?.isInternalEventType?.(event.type)) {
-    throw new Error(`Internal event "${event.type}" cannot be sent to actor "${target.id}" from outside.`);
+    return new Error(`Internal event "${event.type}" cannot be sent to actor "${target.id}" from outside.`);
+  }
+  return undefined;
+}
+
+/**
+ * Rejects an event that must not cross the delivery boundary — an internal
+ * event type sent from outside its owning actor — by reporting it as a dead
+ * letter. Returns `true` when the event was rejected and must not be
+ * delivered. Host runtimes must call this before taking ownership of
+ * delivery.
+ */
+function rejectUndeliverableEvent(source, target, event) {
+  const error = getEventBoundaryError(source, target, event);
+  if (error) {
+    void target.system.deadLetter(source, target, event, 'internalEvent', {
+      error
+    });
+    return true;
   }
+  return false;
 }
 
 /**
@@ -4472,6 +4512,19 @@ function bookSessionId(system) {
  * other: install a different one via `system.runtime` (for durable hosts,
  * through `createDurable`'s adapter runtime operations).
  */
+/**
+ * Why an event was not delivered: `'invalidEvent'` (payload failed its
+ * declared schema), `'internalEvent'` (an internal event type sent from
+ * outside its owning actor) or `'stopped'` (the target actor already
+ * stopped). Hosts may report additional reasons.
+ */
+
+/** Extra detail attached to a dead letter. */
+
+/**
+ * Describes an event that was rejected at the delivery boundary instead of
+ * being delivered to its target actor (a dead letter).
+ */
 
 /** @internal Every operation of `ActorSystemRuntime`, for runtime wrappers. */
 const RUNTIME_OPERATIONS = ['spawnActor', 'startActor', 'stopActor', 'terminateActor', 'emitEvent', 'scheduleTimer', 'cancelTimer', 'cancelAllTimers', 'deadLetter'
@@ -4534,6 +4587,7 @@ class RuntimeSystem {
     this._clock = void 0;
     this._logger = void 0;
     this.createActorRef = void 0;
+    this._onRejectedEvent = options.onRejectedEvent;
     const restoredSnapshot = typeof options.snapshot === 'object' && options.snapshot !== null ? options.snapshot : undefined;
     this._clock = options.clock;
     this._logger = options.logger;
@@ -4732,7 +4786,9 @@ class RuntimeSystem {
     terminateActor(actor, termination);
   }
   sendEvent(source, target, event) {
-    assertEventCanBeSent(source, target, event);
+    if (rejectUndeliverableEvent(source, target, event)) {
+      return;
+    }
     // Record for the inspection `sent[]` facet regardless of which runtime
     // delivers, so host runtimes keep inspection parity.
     this._recordSent(source, target, event);
@@ -4749,17 +4805,29 @@ class RuntimeSystem {
     }
     source._emit(event);
   }
-  deadLetter(source, target, event, reason) {
+  deadLetter(source, target, event, reason, detail) {
     this._sendInspectionEvent({
       type: '@xstate.deadletter',
       actorRef: target,
       sourceRef: source,
       event,
-      reason
+      reason,
+      issues: detail?.issues,
+      error: detail?.error
+    });
+    this._onRejectedEvent?.({
+      event,
+      targetRef: target,
+      targetId: target.id,
+      sourceRef: source,
+      eventOrigin: source ? 'actor' : 'external',
+      reason,
+      issues: detail?.issues,
+      error: detail?.error
     });
     const override = this.runtime?.deadLetter;
     if (override) {
-      return override(source, target, event, reason);
+      return override(source, target, event, reason, detail);
     }
     {
       console.warn(`Event "${event.type}" to actor "${target.id}" was not delivered (${reason}).`);
@@ -5009,7 +5077,8 @@ class Actor {
       clock,
       logger,
       snapshot: resolvedOptions.snapshot ?? resolvedOptions.state,
-      createActorRef
+      createActorRef,
+      onRejectedEvent: resolvedOptions.onRejectedEvent
     });
     if (!parent && resolvedOptions._systemRef && !resolvedOptions._systemRef.current) {
       resolvedOptions._systemRef.current = this.system;
@@ -5815,6 +5884,7 @@ exports.checkStateIn = checkStateIn;
 exports.cloneMachineSnapshot = cloneMachineSnapshot;
 exports.createActor = createActor;
 exports.createCustomEffect = createCustomEffect;
+exports.createDeadLetterEffect = createDeadLetterEffect;
 exports.createEmitEffect = createEmitEffect;
 exports.createErrorPlatformEvent = createErrorPlatformEvent;
 exports.createInertActorScope = createInertActorScope;

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

@@ -60,6 +60,15 @@ export type EffectDescriptor = {
     status: 'done' | 'error';
     output: unknown;
     error: unknown;
+} | {
+    kind: 'builtin';
+    type: '@xstate.deadLetter';
+    source: string | undefined;
+    target: string;
+    event: unknown;
+    reason: string;
+    issues: unknown;
+    error: unknown;
 } | {
     kind: 'emit';
     type: string;

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

@@ -20,7 +20,7 @@ export { isMachineSnapshot, type MachineSnapshot } from "./State.js";
 export { StateMachine } from "./StateMachine.js";
 export { StateNode } from "./StateNode.js";
 export { getStateNodes } from "./stateUtils.js";
-export type { ActorSystem, ActorSystemRuntime, AnyActorSystem } from "./system.js";
+export type { ActorSystem, ActorSystemRuntime, AnyActorSystem, DeadLetterDetail, EventRejection, EventRejectionReason } from "./system.js";
 export { toPromise } from "./toPromise.js";
 export type * from "./types.js";
 export { SpecialTargets } from "./types.js";

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

@@ -1,4 +1,6 @@
 import { ActorRefLike, AnyActorLogic, AnyEventObject, AnyTransitionDefinition, Snapshot } from "./types.js";
+import type { StandardSchemaV1 } from "./schema.types.js";
+import type { EventRejectionReason } from "./system.js";
 /**
  * A record of a single action executed during a transition.
  *
@@ -89,21 +91,36 @@ export interface TransitionInspectionEvent extends BaseInspectionEventProperties
     sent: SentRecord[];
 }
 /**
- * A lossless, two-event inspection protocol:
+ * Emitted when an event could not be delivered to its target actor (a dead
+ * letter): a send to a stopped actor, an invalid external event payload, or
+ * an internal event type sent from outside its owning actor.
  *
- * - `@xstate.actor` — actor topology (identity + parent), drawable up front.
- * - `@xstate.transition` — every transition facet: event, snapshot, source,
- *   microsteps, executed actions, and sent/scheduled events.
+ * A dead letter is not an actor error: the target actor's snapshot is
+ * unchanged.
  */
-/** Emitted when an event could not be delivered to its target actor. */
 export interface DeadLetterInspectionEvent extends BaseInspectionEventProperties {
     type: '@xstate.deadletter';
     /** The actor that sent the event, or `undefined` when sent externally. */
     sourceRef: ActorRefLike | undefined;
     /** The undelivered event. */
     event: AnyEventObject;
-    /** Why the event was not delivered, such as `'stopped'`. */
-    reason: string;
+    /**
+     * Why the event was not delivered: `'stopped'`, `'invalidEvent'` or
+     * `'internalEvent'`.
+     */
+    reason: EventRejectionReason;
+    /** Standard Schema issues for `'invalidEvent'` dead letters. */
+    issues?: readonly StandardSchemaV1.Issue[];
+    /** The underlying error describing a delivery-boundary rejection. */
+    error?: Error;
 }
+/**
+ * A lossless inspection protocol:
+ *
+ * - `@xstate.actor` — actor topology (identity + parent), drawable up front.
+ * - `@xstate.transition` — every transition facet: event, snapshot, source,
+ *   microsteps, executed actions, and sent/scheduled events.
+ * - `@xstate.deadletter` — events that could not be delivered.
+ */
 export type InspectionEvent = ActorInspectionEvent | TransitionInspectionEvent | DeadLetterInspectionEvent;
 export {};

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

@@ -18,10 +18,13 @@ export declare function runStep<TStepOutput>(actor: AnyActor, key: string, exec:
  */
 export declare function deliverEvent(source: AnyActor | undefined, target: AnyActor, event: AnyEventObject): void;
 /**
- * Ensures internal events cannot cross an actor boundary from an external
- * sender. Host runtimes must call this before taking ownership of delivery.
+ * Rejects an event that must not cross the delivery boundary — an internal
+ * event type sent from outside its owning actor — by reporting it as a dead
+ * letter. Returns `true` when the event was rejected and must not be
+ * delivered. Host runtimes must call this before taking ownership of
+ * delivery.
  */
-export declare function assertEventCanBeSent(source: AnyActor | undefined, target: AnyActor, event: AnyEventObject): void;
+export declare function rejectUndeliverableEvent(source: AnyActor | undefined, target: AnyActor, event: AnyEventObject): boolean;
 /**
  * Publishes an actor's terminal result, notifying its parent and observers.
  * Custom runtimes use this for the default local behavior inside their own

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

@@ -1,4 +1,5 @@
 import type { InspectionEvent } from "./inspection.js";
+import type { StandardSchemaV1 } from "./schema.types.js";
 import { AnyEventObject, ActorTermination, ActorSystemInfo, AnyActor, Observer, EventObject, Subscription } from "./types.js";
 interface ScheduledTimer {
     id: string;
@@ -40,6 +41,37 @@ export { hasAmbientInspector, withSystemInspector } from "./inspectionAmbient.js
  * other: install a different one via `system.runtime` (for durable hosts,
  * through `createDurable`'s adapter runtime operations).
  */
+/**
+ * Why an event was not delivered: `'invalidEvent'` (payload failed its
+ * declared schema), `'internalEvent'` (an internal event type sent from
+ * outside its owning actor) or `'stopped'` (the target actor already
+ * stopped). Hosts may report additional reasons.
+ */
+export type EventRejectionReason = 'invalidEvent' | 'internalEvent' | 'stopped' | (string & {});
+/** Extra detail attached to a dead letter. */
+export interface DeadLetterDetail {
+    /** Standard Schema issues for `invalidEvent` rejections. */
+    issues?: readonly StandardSchemaV1.Issue[];
+    /** The underlying error describing the rejection. */
+    error?: Error;
+}
+/**
+ * Describes an event that was rejected at the delivery boundary instead of
+ * being delivered to its target actor (a dead letter).
+ */
+export interface EventRejection extends DeadLetterDetail {
+    /** The event that was rejected. */
+    event: AnyEventObject;
+    /** The actor the event was addressed to. */
+    targetRef: AnyActor | undefined;
+    /** The `id` of the target actor. */
+    targetId: string | undefined;
+    /** The actor that sent the event, or `undefined` for an external send. */
+    sourceRef: AnyActor | undefined;
+    /** Whether the event came from outside the system or from another actor. */
+    eventOrigin: 'external' | 'actor';
+    reason: EventRejectionReason;
+}
 export interface ActorSystemRuntime {
     /** Publishes a newly created actor to the runtime. */
     spawnActor(source: AnyActor | undefined, actor: AnyActor): void | PromiseLike<void>;
@@ -82,10 +114,12 @@ export interface ActorSystemRuntime {
     runStep(actor: AnyActor, key: string, exec: () => unknown | PromiseLike<unknown>): unknown | PromiseLike<unknown>;
     /**
      * Reports an undeliverable event. Delivery stays at-most-once — this is
-     * observability, not retry: the default logs in development and emits an
-     * inspection event.
+     * observability, not retry: the default logs in development, emits an
+     * inspection event and calls the root actor's `onRejectedEvent` hook.
+     * `detail` carries validation issues and the underlying error for events
+     * rejected at the delivery boundary.
      */
-    deadLetter(source: AnyActor | undefined, target: AnyActor, event: AnyEventObject, reason: string): void | PromiseLike<void>;
+    deadLetter(source: AnyActor | undefined, target: AnyActor, event: AnyEventObject, reason: EventRejectionReason, detail?: DeadLetterDetail): void | PromiseLike<void>;
     /** Cancels all logical timers owned by an actor. */
     cancelAllTimers(source: AnyActor): void | PromiseLike<void>;
 }
@@ -124,4 +158,5 @@ export declare function createRuntimeSystem<T extends ActorSystemInfo>(rootActor
     logger: (...args: any[]) => void;
     snapshot?: unknown;
     createActorRef: ActorSystem<T>['createActorRef'];
+    onRejectedEvent?: (rejection: EventRejection) => void;
 }): ActorSystem<T>;

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

@@ -5,7 +5,7 @@ import { AsyncActorLogic } from "./actors/promise.js";
 import type { Actor } from "./createActor.js";
 import { InspectionEvent } from "./inspection.js";
 import { Spawner } from "./spawn.js";
-import type { ActorSystemRuntime, AnyActorSystem, Clock } from "./system.js";
+import type { ActorSystemRuntime, AnyActorSystem, Clock, DeadLetterDetail, EventRejection, EventRejectionReason } from "./system.js";
 import { Sources, Next_StateNodeConfig } from "./types.v6.js";
 import { StandardSchemaV1 } from "./schema.types.js";
 import { builtInActions } from "./actions.js";
@@ -628,7 +628,7 @@ export interface ActorOptions<TLogic extends AnyActorLogic> {
      *
      * @remarks
      * If a callback function is provided, it can accept an inspection event
-     * argument. The inspection protocol has two event types:
+     * argument. The inspection protocol has three event types:
      *
      * - `@xstate.actor` - An actor ref was created in the system (announces actor
      *   topology: identity + parent).
@@ -636,6 +636,11 @@ export interface ActorOptions<TLogic extends AnyActorLogic> {
      *   transition with flat, always-present fields: `event`, `snapshot`,
      *   `sourceRef`, `microsteps`, executed `actions`, and `sent`/scheduled
      *   events.
+     * - `@xstate.deadletter` - An event could not be delivered: the target actor
+     *   stopped, the payload failed its declared schema, or an internal event
+     *   type was sent from outside its owning actor. Carries the `event`,
+     *   `sourceRef`, `reason`, and — for boundary rejections — `issues` and
+     *   `error`.
      *
      * @example
      *
@@ -705,6 +710,15 @@ export interface ActorOptions<TLogic extends AnyActorLogic> {
      * ```
      */
     inspect?: Observer<InspectionEvent> | ((inspectionEvent: InspectionEvent) => void);
+    /**
+     * A dead-letter hook called whenever an event is rejected at the delivery
+     * boundary of this actor system — an invalid external event payload or an
+     * internal event type sent from outside its owning actor. Rejected events
+     * are never delivered and never error the target actor.
+     *
+     * Only observed when this actor is the root of its system.
+     */
+    onRejectedEvent?: (rejection: EventRejection) => void;
 }
 export type AnyActor = ActorInstance<any, any, any, any>;
 /** @deprecated Use `AnyActor` instead. */
@@ -1185,6 +1199,24 @@ export type TerminateExecutableActionObject = BaseExecutableActionObject & {
     id: string;
     args: Parameters<(typeof builtInActions)['@xstate.terminate']>;
 } & ActorTermination;
+/**
+ * An executable effect that reports an event rejected at the delivery boundary
+ * (a dead letter). The snapshot paired with this effect is unchanged.
+ */
+export interface DeadLetterExecutableActionObject extends BaseExecutableActionObject {
+    kind: 'builtin';
+    type: '@xstate.deadLetter';
+    /** The actor that sent the event, or `undefined` for an external send. */
+    source: AnyActor | undefined;
+    /** The actor that rejected the event. */
+    target: AnyActor;
+    /** The rejected event. */
+    event: AnyEventObject;
+    /** Why the event was rejected, such as `'invalidEvent'`. */
+    reason: EventRejectionReason;
+    detail?: DeadLetterDetail;
+    args: [];
+}
 export type BuiltInExecutableActionObject = Values<{
     '@xstate.spawn': SpawnExecutableActionObject;
     '@xstate.start': StartExecutableActionObject;
@@ -1193,6 +1225,7 @@ export type BuiltInExecutableActionObject = Values<{
     '@xstate.cancel': CancelExecutableActionObject;
     '@xstate.stop': StopExecutableActionObject;
     '@xstate.terminate': TerminateExecutableActionObject;
+    '@xstate.deadLetter': DeadLetterExecutableActionObject;
 }>;
 export type SpecialExecutableAction = BuiltInExecutableActionObject;
 type TransitionExecutableActionObject<TType extends string = never> = BuiltInExecutableActionObject | EmitExecutableActionObject | CustomExecutableActionObject<TType | (string & {})>;

package/dist/{effectDescriptor-7ff6802f.development.cjs.js → effectDescriptor-16b6f3b4.cjs.js}

@@ -1,6 +1,6 @@
 'use strict';
 
-var createActor = require('./createActor-a1e0dffb.development.cjs.js');
+var createActor = require('./createActor-27fd819f.cjs.js');
 
 function attachMicrostepActorRefs(microsteps, actorScope, inputSnapshot) {
   if (!microsteps.length) {
@@ -267,6 +267,17 @@ function getEffectDescriptor(effect) {
         output: effect.output,
         error: effect.error
       };
+    case '@xstate.deadLetter':
+      return {
+        kind: 'builtin',
+        type: '@xstate.deadLetter',
+        source: effect.source?.address,
+        target: effect.target.address,
+        event: effect.event,
+        reason: effect.reason,
+        issues: effect.detail?.issues,
+        error: effect.detail?.error
+      };
   }
 }
 

package/dist/{effectDescriptor-39d22100.development.esm.js → effectDescriptor-38598bd3.development.esm.js}

@@ -1,4 +1,4 @@
-import { a5 as createInertActorScope, a6 as setInertActorScopeSnapshot, E as finalizeTransitionResult, a8 as attachSnapshotActorRef, y as createInitEvent, aw as hasAmbientInspector, a7 as beginSpawnAllocation, a9 as macrostep, al as createSpawnEffect, am as initialMicrostep, i as isAtomicStateNode, ax as getProperAncestors, ay as isRemoteActorRef, az as getActorIdPrefix } from './createActor-88709f74.development.esm.js';
+import { a6 as createInertActorScope, a7 as setInertActorScopeSnapshot, F as finalizeTransitionResult, a9 as attachSnapshotActorRef, y as createInitEvent, ax as hasAmbientInspector, a8 as beginSpawnAllocation, aa as macrostep, am as createSpawnEffect, an as initialMicrostep, i as isAtomicStateNode, ay as getProperAncestors, az as isRemoteActorRef, aA as getActorIdPrefix } from './createActor-74e185ee.development.esm.js';
 
 function attachMicrostepActorRefs(microsteps, actorScope, inputSnapshot) {
   if (!microsteps.length) {
@@ -265,6 +265,17 @@ function getEffectDescriptor(effect) {
         output: effect.output,
         error: effect.error
       };
+    case '@xstate.deadLetter':
+      return {
+        kind: 'builtin',
+        type: '@xstate.deadLetter',
+        source: effect.source?.address,
+        target: effect.target.address,
+        event: effect.event,
+        reason: effect.reason,
+        issues: effect.detail?.issues,
+        error: effect.detail?.error
+      };
   }
 }
 

package/dist/{effectDescriptor-be348e50.cjs.js → effectDescriptor-40ca302f.development.cjs.js}

@@ -1,6 +1,6 @@
 'use strict';
 
-var createActor = require('./createActor-b4dd05ae.cjs.js');
+var createActor = require('./createActor-ea9a560c.development.cjs.js');
 
 function attachMicrostepActorRefs(microsteps, actorScope, inputSnapshot) {
   if (!microsteps.length) {
@@ -267,6 +267,17 @@ function getEffectDescriptor(effect) {
         output: effect.output,
         error: effect.error
       };
+    case '@xstate.deadLetter':
+      return {
+        kind: 'builtin',
+        type: '@xstate.deadLetter',
+        source: effect.source?.address,
+        target: effect.target.address,
+        event: effect.event,
+        reason: effect.reason,
+        issues: effect.detail?.issues,
+        error: effect.detail?.error
+      };
   }
 }