effect-machine 0.12.0 → 0.13.0

package/dist/internal/runtime.js

@@ -1,8 +1,9 @@
 import { INTERNAL_INIT_EVENT } from "./utils.js";
-import { NoReplyError } from "../errors.js";
 import { processEventCore, runSpawnEffects, shouldPostpone } from "./transition.js";
+import { NoReplyError } from "../errors.js";
+import { ActorExit } from "../supervision.js";
 import { ActorSystem } from "../actor.js";
-import { Deferred, Effect, Exit, Fiber, Queue, Ref, Schema, Scope, SubscriptionRef } from "effect";
+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.
@@ -10,35 +11,42 @@ import { Deferred, Effect, Exit, Fiber, Queue, Ref, Schema, Scope, SubscriptionR
 * 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
+* - 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. Local actor (actor.ts) has its own event loop
-* with additional concerns (inspection, listeners, subscription ref, etc.)
-* that will be migrated to use this kernel in a future refactor.
+* 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:
-* - Single event queue (all events serialized)
 * - Event loop fiber
 * - Postpone buffer
-* - Background effects
+* - 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 } = config;
-	const stateRef = yield* SubscriptionRef.make(machine.initial);
-	const stoppedRef = yield* Ref.make(false);
-	const eventQueue = yield* config.queueFactory ?? Queue.unbounded();
+	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, {
@@ -46,15 +54,18 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 			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: (childId, childMachine) => system.spawn(`${actorId}/${childId}`, childMachine).pipe(Effect.provideService(ActorSystem, system)),
+		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;
-				Effect.runFork(Deferred.succeed(deferred, value));
+				fork(Deferred.succeed(deferred, value));
 				return true;
 			}
 			return false;
@@ -72,34 +83,65 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 	};
 	const { effects: effectSlots } = machine._slots;
 	for (const bg of machine.backgroundEffects) {
-		const fiber = yield* Effect.forkDetach(bg.handler({
+		const fiber = yield* bg.handler({
 			actorId,
 			state: machine.initial,
 			event: initEvent,
 			self,
 			effects: effectSlots,
 			system
-		}).pipe(Effect.provideService(machine.Context, ctx)));
+		}).pipe(Effect.provideService(machine.Context, ctx), Effect.forkIn(actorScope));
 		backgroundFibers.push(fiber);
 	}
-	yield* runSpawnEffects(machine, machine.initial, initEvent, self, stateScopeRef.current, system, actorId, hooks?.onError);
+	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* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
-		return makeHandle(stateRef, stoppedRef, eventQueue, machine);
+		yield* Scope.close(actorScope, Exit.void);
+		yield* setExit(ActorExit.Final(machine.initial));
+		return makeHandle(stateRef, stoppedRef, eventQueue, exitDeferred, actorScope);
 	}
-	const loopFiber = yield* Effect.forkDetach(runtimeEventLoop(machine, stateRef, eventQueue, stoppedRef, self, backgroundFibers, stateScopeRef, actorId, system, hooks, deferredReplyRef));
+	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* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+		yield* Scope.close(actorScope, Exit.void);
+		yield* setExit(ActorExit.Stopped);
 	}).pipe(Effect.asVoid);
-	yield* Effect.addFinalizer(() => stop);
+	if (config.skipFinalizer !== true) yield* Effect.addFinalizer(() => stop);
 	return {
-		...makeHandle(stateRef, stoppedRef, eventQueue, machine),
+		...makeHandle(stateRef, stoppedRef, eventQueue, exitDeferred, actorScope),
 		stop
 	};
 });
@@ -107,7 +149,7 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 * Build the runtime handle (send/ask/getState/isStopped).
 * Shared between initial-final and normal paths.
 */
-const makeHandle = (stateRef, stoppedRef, eventQueue, _machine) => ({
+const makeHandle = (stateRef, stoppedRef, eventQueue, exitDeferred, actorScope) => ({
 	send: (event) => Effect.gen(function* () {
 		if (!(yield* Ref.get(stoppedRef))) yield* Queue.offer(eventQueue, {
 			_tag: "send",
@@ -141,28 +183,65 @@ const makeHandle = (stateRef, stoppedRef, eventQueue, _machine) => ({
 	getState: SubscriptionRef.get(stateRef),
 	stateRef,
 	isStopped: Ref.get(stoppedRef),
-	stop: Effect.void
+	stop: Effect.void,
+	_queue: eventQueue,
+	_stoppedRef: stoppedRef,
+	exitDeferred,
+	actorScope
 });
-const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function* (machine, stateRef, eventQueue, stoppedRef, self, backgroundFibers, stateScopeRef, actorId, system, hooks, deferredReplyRef) {
+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
 			});
-			if (queued._tag === "sendWait") yield* Deferred.succeed(queued.done, void 0);
 			return {
 				shouldStop: false,
-				stateChanged: 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;
@@ -186,29 +265,67 @@ const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function*
 				}));
 				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: result.isFinal && result.lifecycleRan,
-			stateChanged: result.lifecycleRan
+			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);
-		const { shouldStop, stateChanged } = yield* processQueued(queued).pipe(Effect.catchCause((cause) => {
-			if (queued._tag === "sendWait") Effect.runFork(Deferred.failCause(queued.done, cause));
-			else if (queued._tag === "ask") Effect.runFork(Deferred.die(queued.reply, cause));
-			return Effect.failCause(cause);
+		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) {
-			yield* Ref.set(stoppedRef, true);
-			settlePostponed(postponed, actorId);
-			const remaining = yield* Queue.takeAll(eventQueue);
-			for (const entry of remaining) if (entry._tag === "sendWait") Effect.runFork(Deferred.succeed(entry.done, void 0));
-			else if (entry._tag === "ask") Effect.runFork(Deferred.fail(entry.reply, new NoReplyError({
-				actorId,
-				eventTag: entry.event._tag
-			})));
-			yield* Scope.close(stateScopeRef.current, Exit.void);
-			yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+			const finalState = yield* SubscriptionRef.get(stateRef);
+			yield* shutdown(ActorExit.Final(finalState));
 			return;
 		}
 		let drainTriggered = stateChanged;
@@ -218,16 +335,8 @@ const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function*
 			for (const entry of drained) {
 				const drain = yield* processQueued(entry);
 				if (drain.shouldStop) {
-					yield* Ref.set(stoppedRef, true);
-					settlePostponed(postponed, actorId);
-					const remaining2 = yield* Queue.takeAll(eventQueue);
-					for (const r of remaining2) if (r._tag === "sendWait") Effect.runFork(Deferred.succeed(r.done, void 0));
-					else if (r._tag === "ask") Effect.runFork(Deferred.fail(r.reply, new NoReplyError({
-						actorId,
-						eventTag: r.event._tag
-					})));
-					yield* Scope.close(stateScopeRef.current, Exit.void);
-					yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+					const finalState = yield* SubscriptionRef.get(stateRef);
+					yield* shutdown(ActorExit.Final(finalState));
 					return;
 				}
 				if (drain.stateChanged) drainTriggered = true;
@@ -236,12 +345,12 @@ const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function*
 	}
 });
 /** Settle all pending Deferreds in the postpone buffer on shutdown. */
-const settlePostponed = (postponed, actorId) => {
-	for (const entry of postponed) if (entry._tag === "ask") Effect.runFork(Deferred.fail(entry.reply, new NoReplyError({
+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") Effect.runFork(Deferred.succeed(entry.done, void 0));
+	else if (entry._tag === "sendWait") forkFn(Deferred.succeed(entry.done, void 0));
 	postponed.length = 0;
 };
 //#endregion

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";
 
@@ -68,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.
@@ -148,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.
@@ -166,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, isDeferReplyResult, isEffect, isReplyResult } from "./utils.js";
-import { BuiltMachine } from "../machine.js";
 import { Cause, Effect, Exit, Scope } from "effect";
 //#region src/internal/transition.ts
 /**
@@ -139,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,
@@ -158,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,
@@ -169,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,
@@ -179,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));
 	}
@@ -258,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/machine.d.ts

@@ -1,15 +1,16 @@
-import { EffectHandlers, EffectSlots, EffectsDef, EffectsSchema, GuardHandlers, GuardSlots, GuardsDef, GuardsSchema, MachineContext } from "./slot.js";
 import { DeferReplyResult, ReplyResult, TransitionResult } from "./internal/utils.js";
 import { BrandedEvent, BrandedState, ExtractReply, TaggedOrConstructor } from "./internal/brands.js";
 import { MachineEventSchema, MachineStateSchema, VariantsUnion } from "./schema.js";
 import { DuplicateActorError } from "./errors.js";
+import { EffectHandlers, EffectSlots, EffectsDef, EffectsSchema, GuardHandlers, GuardSlots, GuardsDef, GuardsSchema, MachineContext } from "./slot.js";
+import { Supervision } from "./supervision.js";
 import { findTransitions } from "./internal/transition.js";
 import { ActorRef, ActorSystem } from "./actor.js";
 import { Cause, Duration, Effect, Schema, Scope, ServiceMap } from "effect";
 
 //#region src/machine.d.ts
 declare namespace machine_d_exports {
-  export { BackgroundEffect, BuiltMachine, DeferReplyResult, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, ReplyResult, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, make, replay, reply, spawn };
+  export { BackgroundEffect, DeferReplyResult, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, ReplyResult, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, make, materializeMachine, replay, reply, spawn };
 }
 /**
  * Self reference for sending events back to the machine
@@ -22,7 +23,7 @@ interface MachineRef<Event> {
     readonly _tag: string;
   }, E2 extends {
     readonly _tag: string;
-  }, R2>(id: string, machine: BuiltMachine<S2, E2, R2>) => Effect.Effect<ActorRef<S2, E2>, DuplicateActorError, R2>;
+  }, R2>(id: string, machine: Machine<S2, E2, R2, any, any, any, any>) => Effect.Effect<ActorRef<S2, E2>, DuplicateActorError, R2>;
   /**
    * Settle a deferred reply from a spawn handler.
    * Only usable when the transition handler returned `Machine.deferReply(state)`.
@@ -99,9 +100,6 @@ interface TimeoutConfig<State, Event> {
   /** Event to send when the timer fires. Static or derived from current state. */
   readonly event: Event | ((state: State) => Event);
 }
-type IsAny<T> = 0 extends 1 & T ? true : false;
-type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) : false;
-type NormalizeR<T> = IsAny<T> extends true ? T : IsUnknown<T> extends true ? never : T;
 interface MakeConfig<SD extends Record<string, Schema.Struct.Fields>, ED extends Record<string, Schema.Struct.Fields>, S extends BrandedState, E extends BrandedEvent, GD extends GuardsDef, EFD extends EffectsDef> {
   readonly state: MachineStateSchema<SD> & {
     Type: S;
@@ -121,22 +119,14 @@ type HasEffectKeys<EFD extends EffectsDef> = [keyof EFD] extends [never] ? false
 type SlotContext<State, Event> = MachineContext<State, Event, MachineRef<Event>>;
 /** Combined handlers for build() - guards and effects only */
 type ProvideHandlers<State, Event, GD extends GuardsDef, EFD extends EffectsDef, R> = (HasGuardKeys<GD> extends true ? GuardHandlers<GD, SlotContext<State, Event>, R> : object) & (HasEffectKeys<EFD> extends true ? EffectHandlers<EFD, SlotContext<State, Event>, R> : object);
-/** Whether the machine has any guard or effect slots */
-type HasSlots<GD extends GuardsDef, EFD extends EffectsDef> = HasGuardKeys<GD> extends true ? true : HasEffectKeys<EFD>;
 /**
- * A finalized machine ready for spawning.
+ * Bind slot handlers to a machine, returning a fresh copy with handlers installed.
+ * If no handlers provided and machine has no slots, returns the machine as-is.
+ * Validates that all required slots are provided and no extra slots are given.
  *
- * Created by calling `.build()` on a `Machine`. This is the only type
- * accepted by `Machine.spawn` and `ActorSystem.spawn` (regular overload).
- * Testing utilities (`simulate`, `createTestHarness`, etc.) still accept `Machine`.
+ * @internal — used by spawn, replay, simulate, test harness, entity-machine
  */
-declare class BuiltMachine<State, Event, R = never> {
-  /** @internal */
-  readonly _inner: Machine<State, Event, R, any, any, any, any>;
-  /** @internal */
-  constructor(machine: Machine<State, Event, R, any, any, any, any>);
-  get initial(): State;
-}
+declare const materializeMachine: <S, E, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, any, any, GD, EFD>, handlers?: Record<string, any>) => Machine<S, E, never, any, any, GD, EFD>;
 /**
  * Machine definition with fluent builder API.
  *
@@ -312,13 +302,6 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
    */
   postpone<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, events: TaggedOrConstructor<VariantsUnion<_ED> & BrandedEvent> | ReadonlyArray<TaggedOrConstructor<VariantsUnion<_ED> & BrandedEvent>>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   final<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
-  /**
-   * Finalize the machine. Returns a `BuiltMachine` — the only type accepted by `Machine.spawn`.
-   *
-   * - Machines with slots: pass implementations as the first argument.
-   * - Machines without slots: call with no arguments.
-   */
-  build<R2 = never>(...args: HasSlots<GD, EFD> extends true ? [handlers: ProvideHandlers<State, Event, GD, EFD, R2>] : [handlers?: ProvideHandlers<State, Event, GD, EFD, R2>]): BuiltMachine<State, Event, R | NormalizeR<R2>>;
   static make<SD extends Record<string, Schema.Struct.Fields>, ED extends Record<string, Schema.Struct.Fields>, S extends BrandedState, E extends BrandedEvent, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(config: MakeConfig<SD, ED, S, E, GD, EFD>): Machine<S, E, never, SD, ED, GD, EFD>;
 }
 declare class TransitionScope<State, Event, R, _SD extends Record<string, Schema.Struct.Fields>, _ED extends Record<string, Schema.Struct.Fields>, GD extends GuardsDef, EFD extends EffectsDef, SelectedState extends VariantsUnion<_SD> & BrandedState> {
@@ -330,34 +313,72 @@ declare class TransitionScope<State, Event, R, _SD extends Record<string, Schema
 }
 declare const make: typeof Machine.make;
 /**
- * Spawn an actor from a built machine.
+ * Spawn an actor directly without ActorSystem ceremony.
+ * Accepts a `Machine` directly. For slotful machines, pass `{ slots }` in options.
+ *
+ * **Single actor, no registry.** Caller manages lifetime via `actor.stop`.
+ * If a `Scope` exists in context, cleanup attaches automatically on scope close.
  *
- * Options:
- * - `id` — custom actor ID (default: random)
- * - `hydrate` — restore from a previously-saved state snapshot.
- *   The actor starts in the hydrated state and re-runs spawn effects
- *   for that state (timers, scoped resources, etc.). Transition history
- *   is not replayed — only the current state's entry effects run.
+ * For registry, lookup by ID, persistence, or multi-actor coordination,
+ * use `ActorSystemService` / `system.spawn` instead.
  *
- * Persistence is composed in userland by observing `actor.changes`
- * and saving snapshots to your own storage.
+ * @example
+ * ```ts
+ * // Fire-and-forget — caller manages lifetime
+ * const actor = yield* Machine.spawn(machine.build());
+ * yield* actor.send(Event.Start);
+ * yield* actor.awaitFinal;
+ * yield* actor.stop;
+ *
+ * // Scope-aware — auto-cleans up on scope close
+ * yield* Effect.scoped(Effect.gen(function* () {
+ *   const actor = yield* Machine.spawn(machine.build());
+ *   yield* actor.send(Event.Start);
+ *   // actor.stop called automatically when scope closes
+ * }));
+ * ```
+ */
+type AnyMachine<S, E, R> = Machine<S, E, R, any, any, any, any>;
+/**
+ * Spawn an actor from a machine.
+ *
+ * For machines with slots, pass implementations via `{ slots: { ... } }`.
+ *
+ * @example
+ * ```ts
+ * // No slots
+ * const actor = yield* Machine.spawn(machine);
+ *
+ * // With slots
+ * const actor = yield* Machine.spawn(machine, {
+ *   slots: { canRetry: ({ max }, { state }) => state.attempts < max },
+ * });
+ *
+ * // With hydration
+ * const actor = yield* Machine.spawn(machine, { hydrate: savedState });
+ * ```
  */
 declare const spawn: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R>(machine: BuiltMachine<S, E, R>, idOrOptions?: string | {
+}, R>(machine: AnyMachine<S, E, R>, options?: string | {
   id?: string;
   hydrate?: S;
+  slots?: Record<string, any>;
+  supervision?: Supervision.Policy;
 }) => Effect.Effect<ActorRef<S, E>, never, R>;
-declare const replay: <S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}, R>(machine: BuiltMachine<S, E, R>, events: ReadonlyArray<E>, options?: {
-  from?: S;
-}) => Effect.Effect<S, never, R>;
+declare const replay: {
+  <S extends {
+    readonly _tag: string;
+  }, E extends {
+    readonly _tag: string;
+  }, R>(machine: AnyMachine<S, E, R>, events: ReadonlyArray<E>, options?: {
+    from?: S;
+    slots?: Record<string, any>;
+  }): Effect.Effect<S, never, R>;
+};
 declare const reply: <State, Reply>(state: State, reply: Reply) => ReplyResult<State, Reply>;
 declare const deferReply: <State>(state: State) => DeferReplyResult<State>;
 //#endregion
-export { BackgroundEffect, BuiltMachine, type DeferReplyResult, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, type ReplyResult, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, machine_d_exports, make, replay, reply, spawn };
+export { BackgroundEffect, type DeferReplyResult, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, type ReplyResult, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, machine_d_exports, make, materializeMachine, replay, reply, spawn };