@systemfsoftware/xstate 0.0.0-stage → 6.0.0-beta.65

package/dist/durable.d.ts

@@ -0,0 +1,211 @@
+import { t as EffectDescriptor } from "./effectDescriptor-EvNuy6U3.js";
+import { Ar as ActorSystemRuntime, Br as InspectionEvent, C as AnyActor, D as AnyEventObject, Jt as OutputFrom, Ot as InputFrom, X as CustomExecutableActionObject, _n as SnapshotFrom, gt as EventFromLogic, hn as Snapshot, w as AnyActorLogic, yt as ExecutableActionObjectFromLogic } from "./types-B2EAwOk-.js";
+/** @experimental */
+export interface DurableEffectMetadata {
+  /** Stable within one durable execution. */
+  id: string;
+  transitionIndex: number;
+  effectIndex: number;
+}
+/** @experimental */
+export interface DurableWaitMetadata {
+  /** Stable within one durable execution. */
+  id: string;
+  transitionIndex: number;
+}
+/**
+ * An event addressed to a durable execution's root actor, captured while
+ * effects settled. `source` is the live reference of the sending actor when
+ * one initiated the send.
+ *
+ * @experimental
+ */
+export interface DurableRootEvent<TEvent> {
+  event: TEvent;
+  source: AnyActor | undefined;
+}
+/** @experimental */
+export interface DurableEffect<TEffect> extends DurableEffectMetadata {
+  effect: TEffect;
+  /**
+   * Serializable view of the effect: actor references replaced by logical
+   * addresses and actor sources by source keys, for journaling and
+   * deduplication. Payload fields are only as serializable as their values.
+   */
+  descriptor: EffectDescriptor;
+}
+/**
+ * A durable host adapter: the runtime operations that execute this
+ * execution's effects, plus the durable loop hooks.
+ *
+ * The runtime operations (`sendEvent`, `scheduleTimer`, …) are installed on
+ * the actor system of every snapshot the execution produces, including
+ * children created during transitions and actors rehydrated from restored
+ * snapshots. Operations initiated by live child actors (parent sends,
+ * timers, terminations) route to them without any per-actor wiring; omitted
+ * operations keep their default local behavior.
+ *
+ * Events addressed to this execution's root actor do not reach `sendEvent`
+ * during `executeEffects`: the execution captures and retains them, and the
+ * execution's `waitForEvent()` hands them out before deferring to this
+ * adapter. While the loop is parked, a root-addressed event reaches
+ * `enqueueRootEvent`, or the broader `sendEvent` override when implemented,
+ * so the host can place it in its own mailbox.
+ *
+ * @experimental
+ */
+export interface DurableExecutionAdapter<TLogic extends AnyActorLogic> extends Partial<ActorSystemRuntime> {
+  /**
+   * Absolute clock in milliseconds, defaulting to Date.now. Checkpoints and
+   * resumed executions must use the same time origin. Replay hosts should
+   * return the recorded scheduling time rather than the replay's wall clock.
+   */
+  now?(): number;
+  /**
+   * Accepts a timer synchronously, or fulfills its promise when registration
+   * accepts the timer and its delay begins. For a new timer, that acceptance
+   * time is read through now() and persisted. Retried/restored timers retain
+   * their original deadline; hosts must honor it during registration.
+   */
+  scheduleTimer?: ActorSystemRuntime['scheduleTimer'];
+  /**
+   * Enqueues an event addressed to this execution's root while the durable
+   * loop is parked in `waitForEvent()`. Use this when the host only owns the
+   * root mailbox; implementing `sendEvent` instead takes ownership of delivery
+   * for every target and must use `deliverEvent` for co-located actors.
+   */
+  enqueueRootEvent?(source: AnyActor | undefined, event: AnyEventObject): void | PromiseLike<void>;
+  /**
+   * Executes a custom action as a durable host step or activity. The host
+   * should identify the action by `type` and memoize or deduplicate it using
+   * `metadata.id`.
+   */
+  executeAction(action: CustomExecutableActionObject, metadata: DurableEffectMetadata, runtime: Partial<ActorSystemRuntime>): void | PromiseLike<void>;
+  /**
+   * Creates the runtime used by one effect, for hosts that key operations by
+   * effect ID. Overrides the adapter's runtime operations
+   * operation-by-operation; operations it omits keep their behavior. The
+   * complete effect is provided for hosts that need serializable actor
+   * source, input, event or target data beyond the runtime method arguments.
+   */
+  runtime?(metadata: DurableEffectMetadata, effect: ExecutableActionObjectFromLogic<TLogic>): Partial<ActorSystemRuntime>;
+  /**
+   * Waits durably for the next event addressed to this execution. Typed to
+   * also accept plain event objects: an adapter written against
+   * `AnyActorLogic` (a generic host library) cannot produce
+   * `EventFromLogic<TLogic>`, and the events a host relays are runtime data
+   * anyway — the execution narrows at its own boundary.
+   */
+  waitForEvent(metadata: DurableWaitMetadata): EventFromLogic<TLogic> | AnyEventObject | PromiseLike<EventFromLogic<TLogic> | AnyEventObject>;
+  /** Index assigned to the first transition. Defaults to `0`. */
+  transitionIndex?: number;
+  /**
+   * Pins this execution's actor identity. Session ids become
+   * `<executionId>:<n>`, a deterministic function of actor-creation order, so
+   * a replay re-creates the same session ids and journaled completion events
+   * (which carry the producing incarnation's `sessionId`) still match the
+   * children the replay re-creates. Without it, session ids embed a random
+   * per-process system id and journaled internal events go stale across
+   * replays. Uniqueness across executions is the host's responsibility.
+   */
+  executionId?: string;
+}
+/** @experimental */
+export declare class DurableExecutionCancelledError extends Error {
+  constructor();
+}
+/** @experimental */
+export declare class DurableExecutionResumeError extends Error {
+  constructor();
+}
+/**
+ * The snapshot type a durable execution hands back: the logic's own snapshot,
+ * intersected with the base `Snapshot` union so the `status`/`output`/`error`
+ * discriminant stays visible even when `TLogic` is an unresolved type
+ * parameter (a generic host library), where `SnapshotFrom` alone is opaque.
+ *
+ * @experimental
+ */
+export type DurableSnapshot<TLogic extends AnyActorLogic> = SnapshotFrom<TLogic> & Snapshot<OutputFrom<TLogic>>;
+/** @experimental */
+export interface DurableExecution<TLogic extends AnyActorLogic> {
+  /**
+   * The logical address of this execution's root actor: the logic's own name,
+   * or `x:0` for anonymous logic. Known before any transition runs, so hosts
+   * can label mailboxes and wire messages without a snapshot.
+   */
+  readonly rootAddress: string;
+  /** The machine's id, for pinning a journal to the logic that produced it. */
+  readonly machineId: string;
+  /**
+   * The machine's declared `version`. Persist it with the execution and
+   * reject a worker whose machine version differs: a changed machine
+   * reorders effect ids, and memoized results silently misalign.
+   */
+  readonly machineVersion: string | undefined;
+  /** Index assigned to the next transition. Persist this with checkpoints. */
+  readonly nextTransitionIndex: number;
+  /**
+   * Restores a checkpoint on a fresh execution. Returns effects that start
+   * active embedded children and re-arm pending root timers; execute them
+   * with `executeEffects` before waiting or processing the next event.
+   * Does not send a machine event, replay entry actions, or advance the
+   * transition index. Restoration effect IDs use `restore:<index>:<effect>`.
+   */
+  restore(persistedSnapshot: Snapshot<unknown>): [snapshot: DurableSnapshot<TLogic>, effects: DurableEffect<ExecutableActionObjectFromLogic<TLogic>>[]];
+  initialTransition(...[input]: undefined extends InputFrom<TLogic> ? [input?: InputFrom<TLogic>] : [input: InputFrom<TLogic>]): [snapshot: DurableSnapshot<TLogic>, effects: DurableEffect<ExecutableActionObjectFromLogic<TLogic>>[]];
+  transition(snapshot: SnapshotFrom<TLogic>, event: EventFromLogic<TLogic>): [snapshot: DurableSnapshot<TLogic>, effects: DurableEffect<ExecutableActionObjectFromLogic<TLogic>>[]];
+  /**
+   * Returns the actor reference behind a snapshot produced by this execution,
+   * for addressing and inspection. `undefined` for snapshots this execution
+   * has not seen (for example a freshly deserialized checkpoint that has not
+   * been passed through `restore()` or `transition()` yet).
+   *
+   * With an `address`, returns the live actor at that logical address in the
+   * snapshot's actor tree instead — the root itself, one of its transitive
+   * children, or `undefined` when no live actor has that address (for
+   * example a timer firing for an actor that already completed).
+   */
+  getActorRef(snapshot: SnapshotFrom<TLogic>, address?: string): AnyActor | undefined;
+  /**
+   * Executes effects and resolves only when every runtime operation they
+   * transitively initiated — including operations from live child actors
+   * reacting to delivered events — has been accepted by the runtime; a
+   * failed operation rejects it. Operations are handed to the runtime one at
+   * a time, in initiation order.
+   *
+   * Events addressed to this execution's root actor that were produced along
+   * the way are retained, in order, and handed out by `waitForEvent()`
+   * before it defers to the adapter — so the drive loop is just
+   * `transition(snapshot, await waitForEvent())` + `executeEffects`.
+   */
+  executeEffects(effects: readonly DurableEffect<ExecutableActionObjectFromLogic<TLogic>>[]): Promise<void>;
+  /**
+   * Resolves with the next event addressed to this execution's root actor:
+   * an event a prior `executeEffects` batch captured (an invoked actor
+   * completing, a child reporting up), or — once none are queued — whatever
+   * the adapter's durable wait produces.
+   */
+  waitForEvent(): Promise<EventFromLogic<TLogic>>;
+  run(...[input]: undefined extends InputFrom<TLogic> ? [input?: InputFrom<TLogic>] : [input: InputFrom<TLogic>]): Promise<OutputFrom<TLogic>>;
+}
+/**
+ * Creates a host-neutral durable execution around pure actor transitions.
+ *
+ * The returned transition methods only calculate snapshots and tag their
+ * effects. Persistence, retries, messaging, timers and child execution remain
+ * responsibilities of the adapter.
+ *
+ * @experimental
+ */
+export interface DurableExecutionOptions {
+  /**
+   * Observes the execution's inspection events — actor lifecycle, event
+   * routing, transitions — across the whole live actor tree. The host-side
+   * home for operation logs and instrumentation, so adapters stay pure
+   * physics.
+   */
+  inspect?: (inspectionEvent: InspectionEvent) => void;
+}
+/** @experimental */
+export declare function createDurable<TLogic extends AnyActorLogic>(logic: TLogic, adapter: DurableExecutionAdapter<TLogic>, options?: DurableExecutionOptions): DurableExecution<TLogic>;

package/dist/durable.mjs

@@ -0,0 +1,283 @@
+import { i as initialTransition, o as transition, s as getEffectDescriptor } from "./transition-ZMXyPI-x.mjs";
+import { K as setInertActorScopeSnapshot, O as createStartEffect, Q as recordTimerStart, U as attachSnapshotActorRef, W as createInertActorScope, Z as getTimerStart, bt as withSystemInspector, ct as encodeAddressSegment, ft as withExecutionIdentity, ht as deliverEvent, k as createTimerEffect, pt as getSnapshotActorRef, rt as isRemoteActorRef, st as RUNTIME_OPERATIONS, ut as getRootActorId } from "./createActor-BGHd7i8Q.mjs";
+// src/durable/index.ts
+/** @experimental */
+var DurableExecutionCancelledError = class extends Error {
+	constructor() {
+		super("Durable execution was stopped");
+		this.name = "DurableExecutionCancelledError";
+	}
+};
+/** @experimental */
+var DurableExecutionResumeError = class extends Error {
+	constructor() {
+		super("run() can only start a fresh durable execution; resume checkpoints with restore() and the explicit transition loop");
+		this.name = "DurableExecutionResumeError";
+	}
+};
+/** @experimental */
+function createDurable(logic, adapter, options) {
+	let nextTransitionIndex = adapter.transitionIndex ?? 0;
+	const startingTransitionIndex = nextTransitionIndex;
+	let restored = false;
+	const now = () => adapter.now?.() ?? Date.now();
+	const observedRoots = /* @__PURE__ */ new WeakSet();
+	let lastTransitionIndex = nextTransitionIndex === 0 ? void 0 : nextTransitionIndex - 1;
+	const restoredTimerDeadlines = /* @__PURE__ */ new WeakMap();
+	if (!Number.isSafeInteger(nextTransitionIndex) || nextTransitionIndex < 0) throw new RangeError("transitionIndex must be a non-negative safe integer");
+	const tagEffects = (effects, restoring = false) => {
+		const transitionIndex = restoring ? nextTransitionIndex : nextTransitionIndex++;
+		lastTransitionIndex = restoring ? lastTransitionIndex ?? transitionIndex : transitionIndex;
+		return effects.map((effect, effectIndex) => {
+			const tagged = {
+				id: `${restoring ? "restore:" : ""}${transitionIndex}:${effectIndex}`,
+				transitionIndex,
+				effectIndex,
+				effect
+			};
+			let descriptor;
+			Object.defineProperty(tagged, "descriptor", {
+				enumerable: true,
+				get: () => descriptor ??= getEffectDescriptor(effect)
+			});
+			return tagged;
+		});
+	};
+	const rootAddress = encodeAddressSegment(getRootActorId(logic));
+	const machineId = logic.id ?? rootAddress;
+	const machineVersion = logic.version;
+	const executionIdentity = adapter.executionId ? {
+		systemId: adapter.executionId,
+		nextSessionId: 0
+	} : void 0;
+	const systemRuntime = {};
+	for (const operation of [
+		...RUNTIME_OPERATIONS,
+		"sendEvent",
+		"runStep",
+		"runLogic"
+	]) {
+		const impl = adapter[operation];
+		if (impl) systemRuntime[operation] = impl.bind(adapter);
+	}
+	const hasSystemRuntime = Object.keys(systemRuntime).length > 0 || !!adapter.enqueueRootEvent;
+	let currentBatch;
+	const pendingRootEvents = [];
+	let operationTail = Promise.resolve();
+	const track = (batch, operation) => {
+		batch.pending.add(operation);
+		operation.catch((error) => {
+			batch.failures.push(error);
+		}).then(() => batch.pending.delete(operation));
+		return operation;
+	};
+	const handOff = (batch, run) => {
+		const operation = operationTail.then(run).then(() => void 0);
+		operationTail = operation.catch(() => {});
+		return track(batch, operation);
+	};
+	const dispatch = (run) => currentBatch ? handOff(currentBatch, run) : run();
+	const drain = async (batch) => {
+		while (batch.pending.size) await Promise.allSettled([...batch.pending]);
+	};
+	const settle = async (batch) => {
+		await drain(batch);
+		if (batch.failures.length) throw batch.failures[0];
+	};
+	function wrapRuntime(runtime, localDeliveryFallback, fallbackToActorSystem = false, timerDeadline) {
+		const wrapped = {};
+		for (const operation of RUNTIME_OPERATIONS) {
+			const impl = runtime[operation] ?? (fallbackToActorSystem ? (...args) => {
+				return (operation === "spawnActor" ? args[1] : args[0]).system[operation](...args);
+			} : void 0);
+			if (impl) wrapped[operation] = (...args) => dispatch(() => {
+				if (operation === "scheduleTimer" && timerDeadline) args[2] = Math.min(timerDeadline.delay, Math.max(0, timerDeadline.deadline - now()));
+				if (operation === "scheduleTimer") {
+					const timer = args[0].getSnapshot()?.timers?.[args[1]];
+					if (timer) {
+						const previousStart = getTimerStart(timer);
+						if (previousStart !== void 0 && !timerDeadline) args[2] = Math.min(timer.delay, Math.max(0, previousStart + timer.delay - now()));
+						const result = impl(...args);
+						if (result) return Promise.resolve(result).then(() => {
+							recordTimerStart(timer, previousStart ?? now());
+						});
+						recordTimerStart(timer, previousStart ?? now());
+						return;
+					}
+				}
+				return impl(...args);
+			});
+		}
+		if (runtime.runStep) wrapped.runStep = runtime.runStep;
+		if (runtime.runLogic) wrapped.runLogic = runtime.runLogic;
+		wrapped.sendEvent = (source, target, event) => {
+			if (!currentBatch && target.address === rootAddress && !runtime.sendEvent && adapter.enqueueRootEvent) return dispatch(() => adapter.enqueueRootEvent(source, event));
+			if (!currentBatch && target.address === rootAddress && !runtime.sendEvent) throw new Error(`A root-addressed event ("${event.type}") was produced while the durable loop was parked, but the adapter has no enqueueRootEvent or sendEvent to receive it. Implement enqueueRootEvent to place root-addressed events in the host's mailbox.`);
+			if (currentBatch && target.address === rootAddress) {
+				currentBatch.rootEvents.push({
+					event,
+					source
+				});
+				return;
+			}
+			const impl = runtime.sendEvent;
+			if (impl) return dispatch(() => impl(source, target, event));
+			if (localDeliveryFallback) return dispatch(() => deliverEvent(source, target, event));
+			throw new TypeError(`The durable runtime does not support the sendEvent operation (target '${target.address}')`);
+		};
+		return wrapped;
+	}
+	const wrappedSystemRuntime = hasSystemRuntime ? wrapRuntime(systemRuntime, true) : void 0;
+	function findByAddress(actor, address) {
+		if (actor.address === address) return actor;
+		if (!address.startsWith(`${actor.address}/`)) return;
+		const children = actor.getSnapshot().children;
+		for (const child of Object.values(children ?? {})) {
+			const found = child && findByAddress(child, address);
+			if (found) return found;
+		}
+	}
+	const inspect = options?.inspect;
+	function wireInspection(system) {
+		if (inspect && !system._hasInspectionObservers?.()) system.inspect(inspect);
+	}
+	function installSystemRuntime(snapshot, recursive = false) {
+		if (snapshot.status === "error") {
+			const root = getSnapshotActorRef(snapshot)?.actor;
+			if (root && !observedRoots.has(root)) {
+				root.subscribe({ error() {} });
+				observedRoots.add(root);
+			}
+		}
+		if (wrappedSystemRuntime || inspect) {
+			const ref = getSnapshotActorRef(snapshot)?.actor;
+			const systems = /* @__PURE__ */ new Set();
+			const visit = (actor) => {
+				if (!systems.has(actor.system)) {
+					systems.add(actor.system);
+					if (wrappedSystemRuntime) actor.system.runtime = wrappedSystemRuntime;
+					wireInspection(actor.system);
+				}
+				if (recursive) {
+					const children = actor.getSnapshot().children;
+					for (const child of Object.values(children ?? {})) if (child) visit(child);
+				}
+			};
+			if (ref) visit(ref);
+			if (!recursive || !ref) {
+				const children = snapshot.children;
+				for (const child of Object.values(children ?? {})) if (child) visit(child);
+			}
+		}
+		return snapshot;
+	}
+	const execution = {
+		rootAddress,
+		machineId,
+		machineVersion,
+		get nextTransitionIndex() {
+			return nextTransitionIndex;
+		},
+		restore(persistedSnapshot) {
+			if (restored || nextTransitionIndex !== startingTransitionIndex || currentBatch) throw new Error("restore() requires a fresh durable execution");
+			const { snapshot, scope } = withSystemInspector(inspect, () => withExecutionIdentity(executionIdentity, () => {
+				const scope = createInertActorScope(logic);
+				const snapshot = logic.restoreSnapshot ? logic.restoreSnapshot(persistedSnapshot, scope) : persistedSnapshot;
+				setInertActorScopeSnapshot(scope, snapshot, false);
+				return {
+					snapshot: installSystemRuntime(attachSnapshotActorRef(scope, snapshot), true),
+					scope
+				};
+			}));
+			const effects = [];
+			if (snapshot.status === "active") {
+				const { children, timers } = snapshot;
+				for (const child of Object.values(children ?? {})) if (child && !isRemoteActorRef(child) && child.getSnapshot().status === "active") effects.push(createStartEffect(child));
+				for (const timer of Object.values(timers ?? {})) {
+					const effect = createTimerEffect(scope, timer, timer.delay);
+					if (timer.startedAt !== void 0) restoredTimerDeadlines.set(effect, {
+						deadline: timer.startedAt + timer.delay,
+						delay: timer.delay
+					});
+					effects.push(effect);
+				}
+			}
+			restored = true;
+			return [snapshot, tagEffects(effects, true)];
+		},
+		initialTransition(...args) {
+			if (restored) throw new Error("initialTransition() cannot initialize a restored execution");
+			const [snapshot, effects] = withSystemInspector(inspect, () => withExecutionIdentity(executionIdentity, () => initialTransition(logic, ...args)));
+			return [installSystemRuntime(snapshot), tagEffects(effects)];
+		},
+		transition(snapshot, event) {
+			const [nextSnapshot, effects] = withSystemInspector(inspect, () => withExecutionIdentity(executionIdentity, () => transition(logic, snapshot, event)));
+			return [installSystemRuntime(nextSnapshot), tagEffects(effects)];
+		},
+		getActorRef(snapshot, address) {
+			const root = getSnapshotActorRef(snapshot)?.actor;
+			if (!root || address === void 0) return root;
+			return findByAddress(root, address);
+		},
+		async executeEffects(effects) {
+			if (currentBatch) throw new Error("executeEffects calls must not overlap: await the previous call before starting the next batch.");
+			const batch = {
+				rootEvents: [],
+				failures: [],
+				pending: /* @__PURE__ */ new Set()
+			};
+			currentBatch = batch;
+			const fallbackRuntime = hasSystemRuntime ? void 0 : {};
+			try {
+				for (const tagged of effects) {
+					const { effect } = tagged;
+					const metadata = {
+						id: tagged.id,
+						transitionIndex: tagged.transitionIndex,
+						effectIndex: tagged.effectIndex
+					};
+					const perEffectRuntime = adapter.runtime?.(metadata, effect);
+					const timerDeadline = restoredTimerDeadlines.get(effect);
+					const runtime = perEffectRuntime || timerDeadline ? wrapRuntime({
+						...systemRuntime,
+						...perEffectRuntime
+					}, hasSystemRuntime, !!perEffectRuntime || hasSystemRuntime, timerDeadline) : fallbackRuntime;
+					if (effect.kind === "action") await adapter.executeAction(effect, metadata, runtime ?? wrappedSystemRuntime ?? {});
+					else await effect.exec(runtime);
+				}
+				await settle(batch);
+				pendingRootEvents.push(...batch.rootEvents);
+			} catch (error) {
+				await drain(batch);
+				throw error;
+			} finally {
+				currentBatch = void 0;
+			}
+		},
+		async waitForEvent() {
+			if (lastTransitionIndex === void 0) throw new Error("Cannot wait for an event before the first transition or restore");
+			const queued = pendingRootEvents.shift();
+			if (queued) return queued.event;
+			return adapter.waitForEvent({
+				id: restored && nextTransitionIndex === 0 ? "event:restore:0" : `event:${lastTransitionIndex}`,
+				transitionIndex: lastTransitionIndex
+			});
+		},
+		async run(...args) {
+			if (restored || startingTransitionIndex !== 0 || nextTransitionIndex !== startingTransitionIndex) throw new DurableExecutionResumeError();
+			let [snapshot, effects] = execution.initialTransition(...args);
+			await execution.executeEffects(effects);
+			while (snapshot.status === "active") {
+				const event = await execution.waitForEvent();
+				[snapshot, effects] = execution.transition(snapshot, event);
+				await execution.executeEffects(effects);
+			}
+			const terminalSnapshot = snapshot;
+			if (terminalSnapshot.status === "done") return terminalSnapshot.output;
+			if (terminalSnapshot.status === "error") throw terminalSnapshot.error;
+			throw new DurableExecutionCancelledError();
+		}
+	};
+	return execution;
+}
+export { DurableExecutionCancelledError, DurableExecutionResumeError, createDurable };

package/dist/effectDescriptor-EvNuy6U3.d.ts

@@ -0,0 +1,91 @@
+import { vt as ExecutableActionObject } from "./types-B2EAwOk-.js";
+/**
+ * A serializable view of an executable effect. Actor references are replaced
+ * by their logical addresses and actor sources by their registered source
+ * keys, so a durable host can journal, deduplicate, and route effects without
+ * holding live actor references. Payload fields (`event`, `input`, `params`,
+ * `output`, `error`) pass through by reference and are only as serializable
+ * as their values.
+ *
+ * @experimental
+ */
+type EffectDescriptor = {
+  kind: 'builtin';
+  type: '@xstate.spawn';
+  source: string | undefined;
+  actor: string;
+  id: string;
+  src: string;
+  input: unknown;
+} | {
+  kind: 'builtin';
+  type: '@xstate.start';
+  source: string | undefined;
+  actor: string;
+  id: string;
+} | {
+  kind: 'builtin';
+  type: '@xstate.raise';
+  source: string;
+  event: unknown;
+  id: string | undefined;
+  delay: number | undefined;
+} | {
+  kind: 'builtin';
+  type: '@xstate.sendTo';
+  source: string;
+  target: string;
+  /** The target's incarnation token, when the target is a remote handle that carries one. */
+  incarnation: string | undefined;
+  event: unknown;
+  id: string | undefined;
+  delay: number | undefined;
+} | {
+  kind: 'builtin';
+  type: '@xstate.cancel';
+  source: string;
+  id: string;
+} | {
+  kind: 'builtin';
+  type: '@xstate.stop';
+  source: string;
+  actor: string;
+  id: string;
+} | {
+  kind: 'builtin';
+  type: '@xstate.terminate';
+  source: string;
+  actor: string;
+  id: string;
+  status: 'done' | 'error';
+  output: unknown;
+  error: unknown;
+} | {
+  kind: 'builtin';
+  type: '@xstate.deadLetter';
+  source: string | undefined;
+  target: string | undefined;
+  event: unknown;
+  reason: string;
+  issues: unknown;
+  error: unknown;
+} | {
+  kind: 'emit';
+  type: string;
+  source: string;
+  event: unknown;
+} | {
+  kind: 'action';
+  type: string;
+  params: unknown;
+};
+/**
+ * Returns the serializable descriptor for an executable effect: the same
+ * discriminants (`kind`, `type`) with actor references replaced by logical
+ * addresses and actor sources by source keys. Payload fields pass through by
+ * reference.
+ *
+ * @experimental
+ */
+declare function getEffectDescriptor(effect: ExecutableActionObject): EffectDescriptor;
+export { getEffectDescriptor as n, EffectDescriptor as t };