effect-machine 0.11.0 → 0.13.0

package/dist/internal/runtime.js

@@ -0,0 +1,357 @@
+import { INTERNAL_INIT_EVENT } from "./utils.js";
+import { processEventCore, runSpawnEffects, shouldPostpone } from "./transition.js";
+import { NoReplyError } from "../errors.js";
+import { ActorExit } from "../supervision.js";
+import { ActorSystem } from "../actor.js";
+import { Cause, Deferred, Effect, Exit, Fiber, Option, Queue, Ref, Schema, Scope, SubscriptionRef } from "effect";
+//#region src/internal/runtime.ts
+/**
+* Shared runtime kernel for machine event processing.
+*
+* Provides a single-queue event loop with:
+* - Sequential event processing (no split-mailbox race)
+* - Postpone buffer with drain-on-state-change (gen_statem)
+* - Background effect lifecycle (under actorScope fault boundary)
+* - Spawn effect lifecycle (per-state scope)
+* - Final state detection → stop
+* - Reply settlement (call/ask Deferreds)
+* - Reply schema validation
+* - Lifecycle hooks for actor-specific concerns (inspection, listeners, etc.)
+* - ActorExit with exit reason (Final/Stopped/Defect) via exitDeferred
+*
+* Used by entity-machine and local actor (actor.ts delegates here).
+*
+* @internal
+*/
+/**
+* Create a runtime for a machine. Returns a handle for sending events
+* and querying state. The runtime owns:
+* - Event loop fiber
+* - Postpone buffer
+* - Background effects (under actorScope)
+* - State scope (spawn effects)
+* - Final state detection
+* - Exit reason via exitDeferred
+*
+* Resources (stateRef, eventQueue, stoppedRef) are either cell-provided
+* or allocated fresh by the runtime.
+*
+* @internal
+*/
+const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (machine, system, config) {
+	const { actorId, hooks, lifecycle } = config;
+	const services = yield* Effect.services();
+	const fork = Effect.runForkWith(services);
+	const stateRef = config.cellResources?.stateRef ?? (yield* SubscriptionRef.make(machine.initial));
+	const stoppedRef = config.cellResources?.stoppedRef ?? (yield* Ref.make(false));
+	const eventQueue = config.cellResources?.eventQueue ?? (yield* config.queueFactory ?? Queue.unbounded());
+	const exitDeferred = yield* Deferred.make();
+	const actorScope = yield* Scope.make();
+	const deferredReplyRef = { current: void 0 };
+	const selfSend = Effect.fn("effect-machine.runtime.self.send")(function* (event) {
+		if (!(yield* Ref.get(stoppedRef))) yield* Queue.offer(eventQueue, {
+			_tag: "send",
+			event
+		});
+	});
+	const childPrefix = config.childIdPrefix ?? "";
+	const defaultSpawn = (childId, childMachine) => system.spawn(`${childPrefix}${childId}`, childMachine).pipe(Effect.provideService(ActorSystem, system));
+	const onChildSpawned = config.onChildSpawned;
+	const self = {
+		send: selfSend,
+		cast: selfSend,
+		spawn: onChildSpawned !== void 0 ? (childId, childMachine) => defaultSpawn(childId, childMachine).pipe(Effect.tap((child) => onChildSpawned(childId, child))) : defaultSpawn,
+		reply: (value) => Effect.sync(() => {
+			const deferred = deferredReplyRef.current;
+			if (deferred !== void 0) {
+				deferredReplyRef.current = void 0;
+				fork(Deferred.succeed(deferred, value));
+				return true;
+			}
+			return false;
+		})
+	};
+	const stateScopeRef = { current: yield* Scope.make() };
+	const backgroundFibers = [];
+	const initEvent = { _tag: INTERNAL_INIT_EVENT };
+	const ctx = {
+		actorId,
+		state: machine.initial,
+		event: initEvent,
+		self,
+		system
+	};
+	const { effects: effectSlots } = machine._slots;
+	for (const bg of machine.backgroundEffects) {
+		const fiber = yield* bg.handler({
+			actorId,
+			state: machine.initial,
+			event: initEvent,
+			self,
+			effects: effectSlots,
+			system
+		}).pipe(Effect.provideService(machine.Context, ctx), Effect.forkIn(actorScope));
+		backgroundFibers.push(fiber);
+	}
+	if (lifecycle?.onInitialSpawnEffects !== void 0) yield* lifecycle.onInitialSpawnEffects(machine.initial);
+	const loopFiberRef = { current: void 0 };
+	const initialSpawnDefectSignal = (cause) => Deferred.succeed(exitDeferred, ActorExit.Defect(cause, "initial-spawn")).pipe(Effect.andThen(Ref.set(stoppedRef, true)), Effect.andThen(Effect.suspend(() => loopFiberRef.current !== void 0 ? Fiber.interrupt(loopFiberRef.current) : Effect.void)), Effect.asVoid);
+	yield* runSpawnEffects(machine, machine.initial, initEvent, self, stateScopeRef.current, system, actorId, hooks?.onError, initialSpawnDefectSignal).pipe(Effect.catchCause((cause) => {
+		return Effect.gen(function* () {
+			yield* Ref.set(stoppedRef, true);
+			yield* Scope.close(stateScopeRef.current, Exit.void);
+			yield* Scope.close(actorScope, Exit.void);
+			yield* Deferred.succeed(exitDeferred, ActorExit.Defect(cause, "initial-spawn"));
+			return yield* Effect.failCause(cause);
+		});
+	}));
+	/** Set the exit deferred exactly once. */
+	const setExit = (exit) => Deferred.succeed(exitDeferred, exit).pipe(Effect.asVoid);
+	if (machine.finalStates.has(machine.initial._tag)) {
+		if (lifecycle?.onFinal !== void 0) yield* lifecycle.onFinal(machine.initial);
+		yield* Ref.set(stoppedRef, true);
+		yield* Scope.close(stateScopeRef.current, Exit.void);
+		yield* Scope.close(actorScope, Exit.void);
+		yield* setExit(ActorExit.Final(machine.initial));
+		return makeHandle(stateRef, stoppedRef, eventQueue, exitDeferred, actorScope);
+	}
+	const augmentedHooks = {
+		...hooks,
+		onSpawnDefect: (cause) => Deferred.succeed(exitDeferred, ActorExit.Defect(cause, "spawn")).pipe(Effect.andThen(Ref.set(stoppedRef, true)), Effect.andThen(Effect.suspend(() => loopFiberRef.current !== void 0 ? Fiber.interrupt(loopFiberRef.current) : Effect.void)), Effect.asVoid)
+	};
+	const loopFiber = yield* Effect.forkDetach(runtimeEventLoop(machine, stateRef, eventQueue, stoppedRef, self, stateScopeRef, actorId, system, exitDeferred, augmentedHooks, deferredReplyRef, lifecycle, config.wrapProcess, fork));
+	loopFiberRef.current = loopFiber;
+	if (backgroundFibers.length > 0) yield* Effect.raceAll(backgroundFibers.map((fiber) => Fiber.await(fiber).pipe(Effect.flatMap((exit) => {
+		if (exit._tag === "Failure" && !Cause.hasInterruptsOnly(exit.cause)) return setExit(ActorExit.Defect(exit.cause, "background")).pipe(Effect.andThen(Ref.set(stoppedRef, true)), Effect.andThen(Fiber.interrupt(loopFiber)));
+		return Effect.never;
+	})))).pipe(Effect.forkIn(actorScope));
+	yield* Effect.forkDetach(Effect.gen(function* () {
+		const loopExit = yield* Fiber.await(loopFiber);
+		if (loopExit._tag === "Success") yield* Scope.close(actorScope, Exit.void);
+		else yield* Scope.close(actorScope, loopExit);
+	}));
+	const stop = Effect.gen(function* () {
+		if (yield* Ref.get(stoppedRef)) return;
+		if (lifecycle?.onShutdown !== void 0) yield* lifecycle.onShutdown();
+		yield* Ref.set(stoppedRef, true);
+		yield* Fiber.interrupt(loopFiber);
+		yield* Scope.close(stateScopeRef.current, Exit.void);
+		yield* Scope.close(actorScope, Exit.void);
+		yield* setExit(ActorExit.Stopped);
+	}).pipe(Effect.asVoid);
+	if (config.skipFinalizer !== true) yield* Effect.addFinalizer(() => stop);
+	return {
+		...makeHandle(stateRef, stoppedRef, eventQueue, exitDeferred, actorScope),
+		stop
+	};
+});
+/**
+* Build the runtime handle (send/ask/getState/isStopped).
+* Shared between initial-final and normal paths.
+*/
+const makeHandle = (stateRef, stoppedRef, eventQueue, exitDeferred, actorScope) => ({
+	send: (event) => Effect.gen(function* () {
+		if (!(yield* Ref.get(stoppedRef))) yield* Queue.offer(eventQueue, {
+			_tag: "send",
+			event
+		});
+	}),
+	sendWait: (event) => Effect.gen(function* () {
+		if (!(yield* Ref.get(stoppedRef))) {
+			const done = yield* Deferred.make();
+			yield* Queue.offer(eventQueue, {
+				_tag: "sendWait",
+				event,
+				done
+			});
+			yield* Deferred.await(done);
+		}
+	}),
+	ask: (event) => Effect.gen(function* () {
+		if (yield* Ref.get(stoppedRef)) return yield* new NoReplyError({
+			actorId: "stopped",
+			eventTag: event._tag
+		});
+		const reply = yield* Deferred.make();
+		yield* Queue.offer(eventQueue, {
+			_tag: "ask",
+			event,
+			reply
+		});
+		return yield* Deferred.await(reply);
+	}),
+	getState: SubscriptionRef.get(stateRef),
+	stateRef,
+	isStopped: Ref.get(stoppedRef),
+	stop: Effect.void,
+	_queue: eventQueue,
+	_stoppedRef: stoppedRef,
+	exitDeferred,
+	actorScope
+});
+const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function* (machine, stateRef, eventQueue, stoppedRef, self, stateScopeRef, actorId, system, exitDeferred, hooks, deferredReplyRef, lifecycle, wrapProcess, fork) {
+	const forkEffect = fork ?? Effect.runFork;
+	/** Set the exit deferred exactly once. */
+	const setExit = (exit) => Deferred.succeed(exitDeferred, exit).pipe(Effect.asVoid);
+	const postponed = [];
+	const hasPostponeRules = machine.postponeRules.length > 0;
+	const processQueued = Effect.fn("effect-machine.runtime.processQueued")(function* (queued) {
+		const event = queued.event;
+		const currentState = yield* SubscriptionRef.get(stateRef);
+		if (hasPostponeRules && shouldPostpone(machine, currentState._tag, event._tag)) {
+			if (queued._tag === "call") {
+				const postponedResult = {
+					newState: currentState,
+					previousState: currentState,
+					transitioned: false,
+					lifecycleRan: false,
+					isFinal: false,
+					hasReply: false,
+					deferReply: false,
+					reply: void 0,
+					postponed: true
+				};
+				yield* Deferred.succeed(queued.reply, postponedResult);
+			}
+			if (queued._tag === "sendWait") yield* Deferred.succeed(queued.done, void 0);
+			postponed.push({
+				_tag: "send",
+				event
+			});
+			return {
+				shouldStop: false,
+				stateChanged: false,
+				result: {
+					newState: currentState,
+					previousState: currentState,
+					transitioned: false,
+					lifecycleRan: false,
+					isFinal: false,
+					hasReply: false,
+					deferReply: false,
+					reply: void 0,
+					postponed: true
+				}
+			};
+		}
+		if (lifecycle?.onEvent !== void 0) yield* lifecycle.onEvent(currentState, event);
+		const result = yield* processEventCore(machine, currentState, event, self, stateScopeRef, system, actorId, hooks);
+		if (result.transitioned) yield* SubscriptionRef.set(stateRef, result.newState);
+		if (lifecycle?.onStateChange !== void 0 && result.transitioned) yield* lifecycle.onStateChange(result, event);
+		switch (queued._tag) {
+			case "call":
+				yield* Deferred.succeed(queued.reply, result);
+				break;
+			case "sendWait":
+				yield* Deferred.succeed(queued.done, void 0);
+				break;
+			case "ask":
+				if (result.hasReply) {
+					const replySchema = machine._replySchemas?.get(event._tag);
+					if (replySchema !== void 0) {
+						let decoded;
+						try {
+							decoded = Schema.decodeUnknownSync(replySchema)(result.reply);
+						} catch (decodeError) {
+							yield* Deferred.die(queued.reply, decodeError);
+							return yield* Effect.die(decodeError);
+						}
+						yield* Deferred.succeed(queued.reply, decoded);
+					} else yield* Deferred.succeed(queued.reply, result.reply);
+				} else if (result.deferReply && deferredReplyRef !== void 0) deferredReplyRef.current = queued.reply;
+				else yield* Deferred.fail(queued.reply, new NoReplyError({
+					actorId,
+					eventTag: event._tag
+				}));
+				break;
+		}
+		if (lifecycle?.onProcessed !== void 0 && result.transitioned) yield* lifecycle.onProcessed(result, event);
+		const shouldStop = result.isFinal && result.lifecycleRan;
+		if (shouldStop && lifecycle?.onFinal !== void 0) yield* lifecycle.onFinal(result.newState);
+		return {
+			shouldStop,
+			stateChanged: result.lifecycleRan,
+			result
+		};
+	});
+	const shutdown = (exitReason) => Effect.gen(function* () {
+		yield* Ref.set(stoppedRef, true);
+		if (lifecycle?.onShutdown !== void 0) yield* lifecycle.onShutdown();
+		settlePostponed(postponed, actorId, forkEffect);
+		const remaining = [];
+		let next = yield* Queue.poll(eventQueue);
+		while (Option.isSome(next)) {
+			remaining.push(next.value);
+			next = yield* Queue.poll(eventQueue);
+		}
+		for (const entry of remaining) if (entry._tag === "sendWait") forkEffect(Deferred.succeed(entry.done, void 0));
+		else if (entry._tag === "ask") forkEffect(Deferred.fail(entry.reply, new NoReplyError({
+			actorId,
+			eventTag: entry.event._tag
+		})));
+		else if (entry._tag === "call") {
+			const currentState = yield* SubscriptionRef.get(stateRef);
+			forkEffect(Deferred.succeed(entry.reply, {
+				newState: currentState,
+				previousState: currentState,
+				transitioned: false,
+				lifecycleRan: false,
+				isFinal: machine.finalStates.has(currentState._tag),
+				hasReply: false,
+				deferReply: false,
+				reply: void 0,
+				postponed: false
+			}));
+		}
+		yield* Scope.close(stateScopeRef.current, Exit.void);
+		yield* setExit(exitReason);
+	});
+	while (true) {
+		const queued = yield* Queue.take(eventQueue);
+		if (queued._tag === "drain") {
+			yield* shutdown(ActorExit.Stopped);
+			yield* Deferred.succeed(queued.done, void 0);
+			return;
+		}
+		const eventQueued = queued;
+		const processInner = processQueued(eventQueued);
+		const { shouldStop, stateChanged } = yield* (wrapProcess !== void 0 ? Effect.gen(function* () {
+			return yield* wrapProcess(yield* SubscriptionRef.get(stateRef), eventQueued.event, processInner);
+		}) : processInner).pipe(Effect.catchCause((cause) => {
+			if (queued._tag === "sendWait") forkEffect(Deferred.failCause(queued.done, cause));
+			else if (queued._tag === "ask") forkEffect(Deferred.die(queued.reply, cause));
+			else if (queued._tag === "call") forkEffect(Deferred.failCause(queued.reply, cause));
+			return shutdown(ActorExit.Defect(cause, "transition")).pipe(Effect.andThen(Effect.failCause(cause)));
+		}));
+		if (shouldStop) {
+			const finalState = yield* SubscriptionRef.get(stateRef);
+			yield* shutdown(ActorExit.Final(finalState));
+			return;
+		}
+		let drainTriggered = stateChanged;
+		while (drainTriggered && postponed.length > 0) {
+			drainTriggered = false;
+			const drained = postponed.splice(0);
+			for (const entry of drained) {
+				const drain = yield* processQueued(entry);
+				if (drain.shouldStop) {
+					const finalState = yield* SubscriptionRef.get(stateRef);
+					yield* shutdown(ActorExit.Final(finalState));
+					return;
+				}
+				if (drain.stateChanged) drainTriggered = true;
+			}
+		}
+	}
+});
+/** Settle all pending Deferreds in the postpone buffer on shutdown. */
+const settlePostponed = (postponed, actorId, forkFn) => {
+	for (const entry of postponed) if (entry._tag === "ask") forkFn(Deferred.fail(entry.reply, new NoReplyError({
+		actorId,
+		eventTag: entry.event._tag
+	})));
+	else if (entry._tag === "sendWait") forkFn(Deferred.succeed(entry.done, void 0));
+	postponed.length = 0;
+};
+//#endregion
+export { createRuntime };

package/dist/internal/transition.d.ts

@@ -1,5 +1,5 @@
 import { EffectsDef, GuardsDef, MachineContext } from "../slot.js";
-import { BuiltMachine, Machine, MachineRef, SpawnEffect, Transition } from "../machine.js";
+import { Machine, MachineRef, SpawnEffect, Transition } from "../machine.js";
 import { ActorSystem } from "../actor.js";
 import { Cause, Effect, Scope } from "effect";
 
@@ -32,6 +32,7 @@ declare const runTransitionHandler: <S extends {
 }, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, transition: Transition<S, E, GD, EFD, R>, state: S, event: E, self: MachineRef<E>, system: ActorSystem, actorId: string) => Effect.Effect<{
   newState: S;
   hasReply: boolean;
+  deferReply: boolean;
   reply: unknown;
 }, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
@@ -54,6 +55,7 @@ declare const executeTransition: <S extends {
   transitioned: boolean;
   reenter: boolean;
   hasReply: boolean;
+  deferReply: boolean;
   reply: unknown;
 }, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
@@ -66,6 +68,8 @@ interface ProcessEventHooks<S, E> {
   readonly onTransition?: (from: S, to: S, event: E) => Effect.Effect<void>;
   /** Called when a transition handler or spawn effect fails with a defect */
   readonly onError?: (info: ProcessEventError<S, E>) => Effect.Effect<void>;
+  /** Called when a forked spawn fiber defects — signals the runtime to set exitDeferred */
+  readonly onSpawnDefect?: (cause: Cause.Cause<unknown>) => Effect.Effect<void>;
 }
 /**
  * Error info for inspection hooks.
@@ -92,6 +96,8 @@ interface ProcessEventResult<S> {
   readonly isFinal: boolean;
   /** Whether the handler provided a reply (structural, not value-based) */
   readonly hasReply: boolean;
+  /** Whether the handler deferred the reply to a spawn handler (Machine.deferReply) */
+  readonly deferReply: boolean;
   /** Domain reply value from handler (used by ask). Only meaningful when hasReply is true. */
   readonly reply?: unknown;
   /** Whether the event was postponed (buffered for retry after next state change) */
@@ -131,6 +137,7 @@ declare const processEventCore: <S extends {
   lifecycleRan: boolean;
   isFinal: boolean;
   hasReply: boolean;
+  deferReply: boolean;
   reply: unknown;
   postponed: boolean;
 }, never, Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
@@ -143,7 +150,7 @@ declare const runSpawnEffects: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, state: S, event: E, self: MachineRef<E>, stateScope: Scope.Closeable, system: ActorSystem, actorId: string, onError?: ((info: ProcessEventError<S, E>) => Effect.Effect<void>) | undefined) => Effect.Effect<void, never, Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, state: S, event: E, self: MachineRef<E>, stateScope: Scope.Closeable, system: ActorSystem, actorId: string, onError?: ((info: ProcessEventError<S, E>) => Effect.Effect<void>) | undefined, onSpawnDefect?: ((cause: Cause.Cause<unknown>) => Effect.Effect<void>) | undefined) => Effect.Effect<void, never, Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
 /**
  * Resolve which transition should fire for a given state and event.
  * Uses indexed O(1) lookup. First matching transition wins.
@@ -161,14 +168,13 @@ declare const invalidateIndex: (machine: object) => void;
  * Find all transitions matching a state/event pair.
  * Returns empty array if no matches.
  *
- * Accepts both `Machine` and `BuiltMachine`.
  * O(1) lookup after first access (index is lazily built).
  */
 declare const findTransitions: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: Machine<S, E, R, any, any, GD, EFD> | BuiltMachine<S, E, R>, stateTag: string, eventTag: string) => ReadonlyArray<Transition<S, E, GD, EFD, R>>;
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(machine: Machine<S, E, R, any, any, GD, EFD>, stateTag: string, eventTag: string) => ReadonlyArray<Transition<S, E, GD, EFD, R>>;
 /**
  * Find all spawn effects for a state.
  * Returns empty array if no matches.

package/dist/internal/transition.js

@@ -1,5 +1,4 @@
-import { INTERNAL_ENTER_EVENT, isEffect } from "./utils.js";
-import { BuiltMachine } from "../machine.js";
+import { INTERNAL_ENTER_EVENT, isDeferReplyResult, isEffect, isReplyResult } from "./utils.js";
 import { Cause, Effect, Exit, Scope } from "effect";
 //#region src/internal/transition.ts
 /**
@@ -39,14 +38,22 @@ const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(fu
 	};
 	const raw = transition.handler(handlerCtx);
 	const resolved = isEffect(raw) ? yield* raw.pipe(Effect.provideService(machine.Context, ctx)) : raw;
-	if (resolved !== null && typeof resolved === "object" && "state" in resolved && "reply" in resolved && !("_tag" in resolved)) return {
+	if (isReplyResult(resolved)) return {
 		newState: resolved.state,
 		hasReply: true,
+		deferReply: false,
 		reply: resolved.reply
 	};
+	if (isDeferReplyResult(resolved)) return {
+		newState: resolved.state,
+		hasReply: false,
+		deferReply: true,
+		reply: void 0
+	};
 	return {
 		newState: resolved,
 		hasReply: false,
+		deferReply: false,
 		reply: void 0
 	};
 });
@@ -68,14 +75,16 @@ const executeTransition = Effect.fn("effect-machine.executeTransition")(function
 		transitioned: false,
 		reenter: false,
 		hasReply: false,
+		deferReply: false,
 		reply: void 0
 	};
-	const { newState, hasReply, reply } = yield* runTransitionHandler(machine, transition, currentState, event, self, system, actorId);
+	const { newState, hasReply, deferReply, reply } = yield* runTransitionHandler(machine, transition, currentState, event, self, system, actorId);
 	return {
 		newState,
 		transitioned: true,
 		reenter: transition.reenter === true,
 		hasReply,
+		deferReply,
 		reply
 	};
 });
@@ -118,6 +127,7 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 		lifecycleRan: false,
 		isFinal: false,
 		hasReply: false,
+		deferReply: false,
 		reply: void 0,
 		postponed: false
 	};
@@ -128,7 +138,7 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 		stateScopeRef.current = yield* Scope.make();
 		if (hooks?.onTransition !== void 0) yield* hooks.onTransition(currentState, newState, event);
 		if (hooks?.onSpawnEffect !== void 0) yield* hooks.onSpawnEffect(newState);
-		yield* runSpawnEffects(machine, newState, { _tag: INTERNAL_ENTER_EVENT }, self, stateScopeRef.current, system, actorId, hooks?.onError);
+		yield* runSpawnEffects(machine, newState, { _tag: INTERNAL_ENTER_EVENT }, self, stateScopeRef.current, system, actorId, hooks?.onError, hooks?.onSpawnDefect);
 	}
 	return {
 		newState,
@@ -137,6 +147,7 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 		lifecycleRan: runLifecycle,
 		isFinal: machine.finalStates.has(newState._tag),
 		hasReply: result.hasReply,
+		deferReply: result.deferReply,
 		reply: result.reply,
 		postponed: false
 	};
@@ -146,7 +157,7 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 *
 * @internal
 */
-const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (machine, state, event, self, stateScope, system, actorId, onError) {
+const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (machine, state, event, self, stateScope, system, actorId, onError, onSpawnDefect) {
 	const spawnEffects = findSpawnEffects(machine, state._tag);
 	const ctx = {
 		actorId,
@@ -157,6 +168,7 @@ const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (m
 	};
 	const { effects: effectSlots } = machine._slots;
 	const reportError = onError;
+	const defectSignal = onSpawnDefect;
 	for (const spawnEffect of spawnEffects) {
 		const effect = spawnEffect.handler({
 			actorId,
@@ -167,13 +179,14 @@ const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (m
 			system
 		}).pipe(Effect.provideService(machine.Context, ctx), Effect.catchCause((cause) => {
 			if (Cause.hasInterruptsOnly(cause)) return Effect.interrupt;
-			if (reportError === void 0) return Effect.failCause(cause).pipe(Effect.orDie);
-			return reportError({
+			const report = reportError !== void 0 ? reportError({
 				phase: "spawn",
 				state,
 				event,
 				cause
-			}).pipe(Effect.andThen(Effect.failCause(cause).pipe(Effect.orDie)));
+			}) : Effect.void;
+			const signal = defectSignal !== void 0 ? defectSignal(cause) : Effect.void;
+			return report.pipe(Effect.andThen(signal), Effect.andThen(Effect.failCause(cause).pipe(Effect.orDie)));
 		}));
 		yield* Effect.forkScoped(effect).pipe(Effect.provideService(Scope.Scope, stateScope));
 	}
@@ -246,11 +259,10 @@ const getIndex = (machine) => {
 * Find all transitions matching a state/event pair.
 * Returns empty array if no matches.
 *
-* Accepts both `Machine` and `BuiltMachine`.
 * O(1) lookup after first access (index is lazily built).
 */
-const findTransitions = (input, stateTag, eventTag) => {
-	const index = getIndex(input instanceof BuiltMachine ? input._inner : input);
+const findTransitions = (machine, stateTag, eventTag) => {
+	const index = getIndex(machine);
 	const specific = index.transitions.get(stateTag)?.get(eventTag) ?? [];
 	if (specific.length > 0) return specific;
 	return index.transitions.get("*")?.get(eventTag) ?? [];

package/dist/internal/utils.d.ts

@@ -23,15 +23,51 @@ type InstanceOf<C> = C extends ((...args: unknown[]) => infer R) ? R : never;
 type TaggedConstructor<T extends {
   readonly _tag: string;
 }> = (args: Omit<T, "_tag">) => T;
+declare const ReplyResultSymbol: unique symbol;
+type ReplyResultSymbol = typeof ReplyResultSymbol;
 /**
- * Transition handler result - either a new state or Effect producing one
+ * Branded reply result from a transition handler.
+ * Created via `Machine.reply(state, value)`.
  */
-/** Reply tuple returned from transition handlers for ask support */
-interface TransitionReply<State> {
+interface ReplyResult<State, Reply> {
   readonly state: State;
-  readonly reply: unknown;
+  readonly reply: Reply;
+  readonly [ReplyResultSymbol]: true;
 }
-type TransitionResult<State, R> = State | TransitionReply<State> | Effect.Effect<State | TransitionReply<State>, never, R>;
+/**
+ * Create a reply result for ask-bearing event handlers.
+ */
+declare const makeReply: <State, Reply>(state: State, reply: Reply) => ReplyResult<State, Reply>;
+/**
+ * Type guard for ReplyResult (symbol-based, replaces duck-typing).
+ */
+declare const isReplyResult: (value: unknown) => value is ReplyResult<unknown, unknown>;
+declare const DeferReplySymbol: unique symbol;
+type DeferReplySymbol = typeof DeferReplySymbol;
+/**
+ * Branded deferred reply result from a transition handler.
+ * Signals that the reply will be settled later by `self.reply()` in a spawn handler.
+ * Created via `Machine.deferReply(state)`.
+ */
+interface DeferReplyResult<State> {
+  readonly state: State;
+  readonly [DeferReplySymbol]: true;
+}
+/**
+ * Create a deferred reply result. Handler returns this to signal
+ * "spawn handler will call self.reply(value) later".
+ */
+declare const makeDeferReply: <State>(state: State) => DeferReplyResult<State>;
+/**
+ * Type guard for DeferReplyResult.
+ */
+declare const isDeferReplyResult: (value: unknown) => value is DeferReplyResult<unknown>;
+/**
+ * Transition handler result.
+ * - When Reply is `never`: handler returns plain State (no reply allowed)
+ * - When Reply is concrete: handler must return ReplyResult via Machine.reply()
+ */
+type TransitionResult<State, R, Reply = never> = [Reply] extends [never] ? State | Effect.Effect<State, never, R> : ReplyResult<State, Reply> | DeferReplyResult<State> | Effect.Effect<ReplyResult<State, Reply> | DeferReplyResult<State>, never, R>;
 /**
  * Internal event tags used for lifecycle effect contexts.
  * Prefixed with $ to distinguish from user events.
@@ -62,4 +98,4 @@ declare const isEffect: (value: unknown) => value is Effect.Effect<unknown, unkn
  */
 declare const stubSystem: ActorSystem;
 //#endregion
-export { ArgsOf, INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, InstanceOf, TagOf, TaggedConstructor, TransitionReply, TransitionResult, getTag, isEffect, stubSystem };
+export { ArgsOf, DeferReplyResult, DeferReplySymbol, INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, InstanceOf, ReplyResult, ReplyResultSymbol, TagOf, TaggedConstructor, TransitionResult, getTag, isDeferReplyResult, isEffect, isReplyResult, makeDeferReply, makeReply, stubSystem };

package/dist/internal/utils.js

@@ -4,6 +4,32 @@ import { Effect, Stream } from "effect";
 * Internal utilities for effect-machine.
 * @internal
 */
+const ReplyResultSymbol = Symbol.for("effect-machine/ReplyResult");
+/**
+* Create a reply result for ask-bearing event handlers.
+*/
+const makeReply = (state, reply) => ({
+	state,
+	reply,
+	[ReplyResultSymbol]: true
+});
+/**
+* Type guard for ReplyResult (symbol-based, replaces duck-typing).
+*/
+const isReplyResult = (value) => value !== null && typeof value === "object" && ReplyResultSymbol in value;
+const DeferReplySymbol = Symbol.for("effect-machine/DeferReply");
+/**
+* Create a deferred reply result. Handler returns this to signal
+* "spawn handler will call self.reply(value) later".
+*/
+const makeDeferReply = (state) => ({
+	state,
+	[DeferReplySymbol]: true
+});
+/**
+* Type guard for DeferReplyResult.
+*/
+const isDeferReplyResult = (value) => value !== null && typeof value === "object" && DeferReplySymbol in value;
 /**
 * Internal event tags used for lifecycle effect contexts.
 * Prefixed with $ to distinguish from user events.
@@ -46,4 +72,4 @@ const stubSystem = {
 	subscribe: () => () => {}
 };
 //#endregion
-export { INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, getTag, isEffect, stubSystem };
+export { INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, getTag, isDeferReplyResult, isEffect, isReplyResult, makeDeferReply, makeReply, stubSystem };