effect-machine 0.12.0 → 0.13.0

package/v3/dist/actor.js

@@ -1,9 +1,10 @@
-import { Inspector } from "./inspection.js";
-import { INTERNAL_INIT_EVENT } from "./internal/utils.js";
-import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.js";
+import { ActorStoppedError, DuplicateActorError } from "./errors.js";
+import { processEventCore, resolveTransition, runSpawnEffects } from "./internal/transition.js";
 import { emitWithTimestamp } from "./internal/inspection.js";
-import { processEventCore, resolveTransition, runSpawnEffects, shouldPostpone } from "./internal/transition.js";
-import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Runtime, Schema, Scope, Stream, SubscriptionRef } from "effect";
+import { Inspector } from "./inspection.js";
+import { materializeMachine } from "./machine.js";
+import { createRuntime } from "./internal/runtime.js";
+import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Schedule, Scope, Stream, SubscriptionRef } from "effect";
 //#region src/actor.ts
 /**
 * Actor system: spawning, lifecycle, and event processing.
@@ -11,7 +12,7 @@ import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, O
 * Combines:
 * - ActorRef interface (running actor handle)
 * - ActorSystem service (spawn/stop/get actors)
-* - Actor creation and event loop
+* - Actor creation (delegates to runtime kernel)
 */
 /**
 * ActorSystem service tag
@@ -26,12 +27,13 @@ const notifyListeners = (listeners, state) => {
 	} catch {}
 };
 /**
-* Build core ActorRef methods shared between regular and persistent actors.
+* Build core ActorRef methods.
 */
-const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listeners, stop, system, childrenMap, pendingReplies, transitionsPubSub) => {
+const buildActorRefCore = (id, machine, stateRef, eventQueueRef, stoppedRef, listeners, stop, system, childrenMap, pendingReplies, transitionsPubSub, exitDeferred) => {
 	const send = Effect.fn("effect-machine.actor.send")(function* (event) {
 		if (yield* Ref.get(stoppedRef)) return;
-		yield* Queue.offer(eventQueue, {
+		const q = yield* Ref.get(eventQueueRef);
+		yield* Queue.offer(q, {
 			_tag: "send",
 			event
 		});
@@ -49,7 +51,8 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 		}
 		const reply = yield* Deferred.make();
 		pendingReplies.add(reply);
-		yield* Queue.offer(eventQueue, {
+		const q = yield* Ref.get(eventQueueRef);
+		yield* Queue.offer(q, {
 			_tag: "call",
 			event,
 			reply
@@ -66,7 +69,8 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 		if (yield* Ref.get(stoppedRef)) return yield* new ActorStoppedError({ actorId: id });
 		const reply = yield* Deferred.make();
 		pendingReplies.add(reply);
-		yield* Queue.offer(eventQueue, {
+		const q = yield* Ref.get(eventQueueRef);
+		yield* Queue.offer(q, {
 			_tag: "ask",
 			event,
 			reply
@@ -85,10 +89,8 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 		const current = yield* SubscriptionRef.get(stateRef);
 		if (predicate(current)) return current;
 		const done = yield* Deferred.make();
-		const rt = yield* Effect.runtime();
-		const runFork = Runtime.runFork(rt);
 		const listener = (state) => {
-			if (predicate(state)) runFork(Deferred.succeed(done, state));
+			if (predicate(state)) Effect.runFork(Deferred.succeed(done, state));
 		};
 		listeners.add(listener);
 		const afterSubscribe = yield* SubscriptionRef.get(stateRef);
@@ -128,12 +130,27 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 				listeners.delete(fn);
 			};
 		},
+		awaitExit: Deferred.await(exitDeferred),
+		watch: (other) => other.awaitExit,
+		drain: Effect.gen(function* () {
+			if (yield* Ref.get(stoppedRef)) return;
+			const q = yield* Ref.get(eventQueueRef);
+			const done = yield* Deferred.make();
+			yield* Queue.offer(q, {
+				_tag: "drain",
+				done
+			});
+			yield* Deferred.await(done);
+		}).pipe(Effect.asVoid),
 		sync: {
 			send: (event) => {
-				if (!Effect.runSync(Ref.get(stoppedRef))) Effect.runSync(Queue.offer(eventQueue, {
-					_tag: "send",
-					event
-				}));
+				if (!Effect.runSync(Ref.get(stoppedRef))) {
+					const q = Effect.runSync(Ref.get(eventQueueRef));
+					Effect.runSync(Queue.offer(q, {
+						_tag: "send",
+						event
+					}));
+				}
 			},
 			stop: () => Effect.runFork(stop),
 			snapshot: () => Effect.runSync(SubscriptionRef.get(stateRef)),
@@ -147,11 +164,13 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 	};
 };
 /**
-* Create and start an actor for a machine
+* Create and start an actor for a machine.
+* Uses the shared runtime kernel with lifecycle hooks for actor-specific concerns.
 */
 const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machine, options) {
 	const initial = options?.initialState ?? machine.initial;
 	yield* Effect.annotateCurrentSpan("effect_machine.actor.id", id);
+	yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", initial._tag);
 	const existingSystem = yield* Effect.serviceOption(ActorSystem);
 	let system;
 	let implicitSystemScope;
@@ -162,298 +181,180 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		implicitSystemScope = scope;
 	}
 	const inspectorValue = Option.getOrUndefined(yield* Effect.serviceOption(Inspector));
-	const eventQueue = yield* Queue.unbounded();
-	const stoppedRef = yield* Ref.make(false);
 	const childrenMap = /* @__PURE__ */ new Map();
-	const selfSend = Effect.fn("effect-machine.actor.self.send")(function* (event) {
-		if (yield* Ref.get(stoppedRef)) return;
-		yield* Queue.offer(eventQueue, {
-			_tag: "send",
-			event
-		});
-	});
-	const self = {
-		send: selfSend,
-		cast: selfSend,
-		spawn: (childId, childMachine) => Effect.gen(function* () {
-			const child = yield* system.spawn(childId, childMachine).pipe(Effect.provideService(ActorSystem, system));
-			childrenMap.set(childId, child);
-			const maybeScope = yield* Effect.serviceOption(Scope.Scope);
-			if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, Effect.sync(() => {
-				childrenMap.delete(childId);
-			}));
-			return child;
-		})
-	};
-	yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", initial._tag);
+	const pendingReplies = /* @__PURE__ */ new Set();
+	const listeners = /* @__PURE__ */ new Set();
+	const transitionsPubSub = yield* PubSub.unbounded();
 	yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
 		type: "@machine.spawn",
 		actorId: id,
 		initialState: initial,
 		timestamp
 	}));
-	const stateRef = yield* SubscriptionRef.make(initial);
-	const listeners = /* @__PURE__ */ new Set();
-	const backgroundFibers = [];
-	const initEvent = { _tag: INTERNAL_INIT_EVENT };
-	const ctx = {
-		actorId: id,
-		state: initial,
-		event: initEvent,
-		self,
-		system
-	};
-	const { effects: effectSlots } = machine._slots;
-	for (const bg of machine.backgroundEffects) {
-		const fiber = yield* Effect.forkDaemon(bg.handler({
-			actorId: id,
-			state: initial,
-			event: initEvent,
-			self,
-			effects: effectSlots,
-			system
-		}).pipe(Effect.provideService(machine.Context, ctx)));
-		backgroundFibers.push(fiber);
-	}
-	const stateScopeRef = { current: yield* Scope.make() };
-	yield* runSpawnEffectsWithInspection(machine, initial, initEvent, self, stateScopeRef.current, id, inspectorValue, system);
-	if (machine.finalStates.has(initial._tag)) {
-		yield* Scope.close(stateScopeRef.current, Exit.void);
-		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
-		yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
-			type: "@machine.stop",
-			actorId: id,
-			finalState: initial,
-			timestamp
-		}));
-		yield* Ref.set(stoppedRef, true);
-		if (implicitSystemScope !== void 0) yield* Scope.close(implicitSystemScope, Exit.void);
-		return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, Ref.set(stoppedRef, true).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid), system, childrenMap, /* @__PURE__ */ new Set());
-	}
-	const pendingReplies = /* @__PURE__ */ new Set();
-	const transitionsPubSub = yield* PubSub.unbounded();
-	const loopFiber = yield* Effect.forkDaemon(eventLoop(machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, id, inspectorValue, system, pendingReplies, transitionsPubSub));
-	return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, Effect.gen(function* () {
-		const finalState = yield* SubscriptionRef.get(stateRef);
-		yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
-			type: "@machine.stop",
-			actorId: id,
-			finalState,
-			timestamp
-		}));
-		yield* Ref.set(stoppedRef, true);
-		yield* Fiber.interrupt(loopFiber);
-		yield* settlePendingReplies(pendingReplies, id);
-		yield* Scope.close(stateScopeRef.current, Exit.void);
-		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
-		if (implicitSystemScope !== void 0) yield* Scope.close(implicitSystemScope, Exit.void);
-	}).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid), system, childrenMap, pendingReplies, transitionsPubSub);
-});
-/** Fail all pending call/ask Deferreds with ActorStoppedError. Safe to call multiple times. */
-const settlePendingReplies = (pendingReplies, actorId) => Effect.sync(() => {
-	const error = new ActorStoppedError({ actorId });
-	for (const deferred of pendingReplies) Effect.runFork(Deferred.fail(deferred, error));
-	pendingReplies.clear();
-});
-/**
-* Main event loop for the actor.
-* Includes postpone buffer — events matching postpone rules are buffered
-* and drained after state tag changes (gen_statem semantics).
-*/
-const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, actorId, inspector, system, pendingReplies, transitionsPubSub) {
-	const postponed = [];
-	const hasPostponeRules = machine.postponeRules.length > 0;
-	const processQueued = Effect.fn("effect-machine.actor.processQueued")(function* (queued) {
-		const event = queued.event;
-		const currentState = yield* SubscriptionRef.get(stateRef);
-		if (hasPostponeRules && shouldPostpone(machine, currentState._tag, event._tag)) {
-			postponed.push(queued);
-			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);
-			}
-			return {
-				shouldStop: false,
-				stateChanged: false
-			};
-		}
-		const { shouldStop, result } = yield* Effect.withSpan("effect-machine.event.process", { attributes: {
-			"effect_machine.actor.id": actorId,
-			"effect_machine.state.current": currentState._tag,
-			"effect_machine.event.type": event._tag
-		} })(processEvent(machine, currentState, event, stateRef, self, listeners, stateScopeRef, actorId, inspector, system));
-		switch (queued._tag) {
-			case "call":
-				yield* Deferred.succeed(queued.reply, result);
-				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 yield* Deferred.fail(queued.reply, new NoReplyError({
-					actorId,
-					eventTag: event._tag
-				}));
-				break;
-		}
-		if (result.transitioned) yield* PubSub.publish(transitionsPubSub, {
-			fromState: result.previousState,
-			toState: result.newState,
-			event
-		});
-		return {
-			shouldStop,
-			stateChanged: result.lifecycleRan
-		};
-	});
-	while (true) {
-		const { shouldStop, stateChanged } = yield* processQueued(yield* Queue.take(eventQueue));
-		if (shouldStop) {
-			yield* Ref.set(stoppedRef, true);
-			settlePostponedBuffer(postponed, pendingReplies, actorId);
-			yield* settlePendingReplies(pendingReplies, actorId);
-			yield* Scope.close(stateScopeRef.current, Exit.void);
-			yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
-			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) {
-					yield* Ref.set(stoppedRef, true);
-					settlePostponedBuffer(postponed, pendingReplies, actorId);
-					yield* settlePendingReplies(pendingReplies, actorId);
-					yield* Scope.close(stateScopeRef.current, Exit.void);
-					yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
-					return;
-				}
-				if (drain.stateChanged) drainTriggered = true;
-			}
-		}
-	}
-});
-/**
-* Settle all reply-bearing entries in the postpone buffer on shutdown.
-* Call entries already had their Deferred settled with the postponed result
-* (so their pendingReplies entry is already removed). Ask/send entries
-* with Deferreds are settled via the pendingReplies registry.
-*/
-const settlePostponedBuffer = (postponed, _pendingReplies, _actorId) => {
-	postponed.length = 0;
-};
-/**
-* Process a single event, returning true if the actor should stop.
-* Wraps processEventCore with actor-specific concerns (inspection, listeners, state ref).
-*/
-const processEvent = Effect.fn("effect-machine.actor.processEvent")(function* (machine, currentState, event, stateRef, self, listeners, stateScopeRef, actorId, inspector, system) {
-	yield* emitWithTimestamp(inspector, (timestamp) => ({
-		type: "@machine.event",
-		actorId,
-		state: currentState,
-		event,
-		timestamp
-	}));
-	const result = yield* processEventCore(machine, currentState, event, self, stateScopeRef, system, actorId, inspector === void 0 ? void 0 : {
-		onSpawnEffect: (state) => emitWithTimestamp(inspector, (timestamp) => ({
+	const hooks = inspectorValue === void 0 ? void 0 : {
+		onSpawnEffect: (state) => emitWithTimestamp(inspectorValue, (timestamp) => ({
 			type: "@machine.effect",
-			actorId,
+			actorId: id,
 			effectType: "spawn",
 			state,
 			timestamp
 		})),
-		onTransition: (from, to, ev) => emitWithTimestamp(inspector, (timestamp) => ({
+		onTransition: (from, to, ev) => emitWithTimestamp(inspectorValue, (timestamp) => ({
 			type: "@machine.transition",
-			actorId,
+			actorId: id,
 			fromState: from,
 			toState: to,
 			event: ev,
 			timestamp
 		})),
-		onError: (info) => emitWithTimestamp(inspector, (timestamp) => ({
+		onError: (info) => emitWithTimestamp(inspectorValue, (timestamp) => ({
 			type: "@machine.error",
-			actorId,
+			actorId: id,
 			phase: info.phase,
 			state: info.state,
 			event: info.event,
 			error: Cause.pretty(info.cause),
 			timestamp
 		}))
-	});
-	if (!result.transitioned) {
-		yield* Effect.annotateCurrentSpan("effect_machine.transition.matched", false);
+	};
+	const machineWithState = initial !== machine.initial ? Object.create(machine, { initial: {
+		value: initial,
+		enumerable: true
+	} }) : machine;
+	const stateRef = yield* SubscriptionRef.make(initial);
+	const stoppedRef = yield* Ref.make(false);
+	const initialQueue = yield* Queue.unbounded();
+	const eventQueueRef = yield* Ref.make(initialQueue);
+	const terminalExitDeferred = yield* Deferred.make();
+	let stopEmitted = false;
+	const runtimeRef = { current: void 0 };
+	/** Build lifecycle hooks for a generation */
+	const buildLifecycle = () => {
+		stopEmitted = false;
 		return {
-			shouldStop: false,
-			result
-		};
-	}
-	yield* Effect.annotateCurrentSpan("effect_machine.transition.matched", true);
-	yield* SubscriptionRef.set(stateRef, result.newState);
-	notifyListeners(listeners, result.newState);
-	if (result.lifecycleRan) {
-		yield* Effect.annotateCurrentSpan("effect_machine.state.from", result.previousState._tag);
-		yield* Effect.annotateCurrentSpan("effect_machine.state.to", result.newState._tag);
-		if (result.isFinal) {
-			yield* emitWithTimestamp(inspector, (timestamp) => ({
-				type: "@machine.stop",
-				actorId,
-				finalState: result.newState,
+			onEvent: inspectorValue !== void 0 ? (state, event) => emitWithTimestamp(inspectorValue, (timestamp) => ({
+				type: "@machine.event",
+				actorId: id,
+				state,
+				event,
 				timestamp
+			})) : void 0,
+			onStateChange: (result, _event) => Effect.gen(function* () {
+				notifyListeners(listeners, result.newState);
+				yield* Effect.annotateCurrentSpan("effect_machine.transition.matched", true);
+				if (result.lifecycleRan) {
+					yield* Effect.annotateCurrentSpan("effect_machine.state.from", result.previousState._tag);
+					yield* Effect.annotateCurrentSpan("effect_machine.state.to", result.newState._tag);
+				}
+			}),
+			onProcessed: (result, event) => result.transitioned ? PubSub.publish(transitionsPubSub, {
+				fromState: result.previousState,
+				toState: result.newState,
+				event
+			}).pipe(Effect.asVoid) : Effect.void,
+			onFinal: inspectorValue !== void 0 ? (state) => Effect.gen(function* () {
+				stopEmitted = true;
+				yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
+					type: "@machine.stop",
+					actorId: id,
+					finalState: state,
+					timestamp
+				}));
+			}) : void 0,
+			onShutdown: () => Effect.gen(function* () {
+				if (!stopEmitted) {
+					const finalState = yield* SubscriptionRef.get(stateRef);
+					yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
+						type: "@machine.stop",
+						actorId: id,
+						finalState,
+						timestamp
+					}));
+				}
+				yield* settlePendingReplies(pendingReplies, id);
+			}),
+			onInitialSpawnEffects: inspectorValue !== void 0 ? (state) => emitWithTimestamp(inspectorValue, (timestamp) => ({
+				type: "@machine.effect",
+				actorId: id,
+				effectType: "spawn",
+				state,
+				timestamp
+			})) : void 0
+		};
+	};
+	/** Create a single runtime generation */
+	const spawnGeneration = (machineForGen) => Ref.get(eventQueueRef).pipe(Effect.flatMap((currentQueue) => createRuntime(machineForGen, system, {
+		actorId: id,
+		hooks,
+		skipFinalizer: true,
+		cellResources: {
+			stateRef,
+			stoppedRef,
+			eventQueue: currentQueue
+		},
+		lifecycle: buildLifecycle(),
+		wrapProcess: (state, event, inner) => Effect.withSpan("effect-machine.event.process", { attributes: {
+			"effect_machine.actor.id": id,
+			"effect_machine.state.current": state._tag,
+			"effect_machine.event.type": event._tag
+		} })(inner.pipe(Effect.tap((r) => Effect.annotateCurrentSpan("effect_machine.transition.matched", r.result.transitioned)))),
+		onChildSpawned: (childId, child) => Effect.gen(function* () {
+			childrenMap.set(childId, child);
+			const maybeScope = yield* Effect.serviceOption(Scope.Scope);
+			if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, Effect.sync(() => {
+				childrenMap.delete(childId);
 			}));
-			return {
-				shouldStop: true,
-				result
-			};
+		})
+	})));
+	const supervision = options?.supervision;
+	const runtime = yield* spawnGeneration(machineWithState);
+	runtimeRef.current = runtime;
+	let supervisorFiber;
+	if (supervision !== void 0) supervisorFiber = yield* Effect.forkDaemon(Effect.gen(function* () {
+		const driver = yield* Schedule.driver(supervision.schedule);
+		let generation = 0;
+		while (true) {
+			const currentRuntime = runtimeRef.current;
+			if (currentRuntime === void 0) return;
+			const generationExit = yield* Deferred.await(currentRuntime.exitDeferred);
+			if (generationExit._tag !== "Defect") {
+				yield* Deferred.succeed(terminalExitDeferred, generationExit);
+				return;
+			}
+			if (supervision.shouldRestart !== void 0 && !supervision.shouldRestart(generationExit)) {
+				yield* Deferred.succeed(terminalExitDeferred, generationExit);
+				return;
+			}
+			if ((yield* driver.next(generationExit).pipe(Effect.exit))._tag === "Failure") {
+				yield* Deferred.succeed(terminalExitDeferred, generationExit);
+				return;
+			}
+			yield* settlePendingReplies(pendingReplies, id);
+			const freshQueue = yield* Queue.unbounded();
+			yield* Ref.set(eventQueueRef, freshQueue);
+			yield* SubscriptionRef.set(stateRef, machine.initial);
+			yield* Ref.set(stoppedRef, false);
+			childrenMap.clear();
+			runtimeRef.current = yield* spawnGeneration(machine);
+			generation++;
+			if (options?.onRestart !== void 0) yield* options.onRestart(generation, generationExit);
+			notifyListeners(listeners, machine.initial);
 		}
-	}
-	return {
-		shouldStop: false,
-		result
-	};
-});
-/**
-* Run spawn effects with actor-specific inspection and tracing.
-* Wraps the core runSpawnEffects with inspection events and spans.
-* @internal
-*/
-const runSpawnEffectsWithInspection = Effect.fn("effect-machine.actor.spawnEffects")(function* (machine, state, event, self, stateScope, actorId, inspector, system) {
-	yield* emitWithTimestamp(inspector, (timestamp) => ({
-		type: "@machine.effect",
-		actorId,
-		effectType: "spawn",
-		state,
-		timestamp
 	}));
-	yield* runSpawnEffects(machine, state, event, self, stateScope, system, actorId, inspector === void 0 ? void 0 : (info) => emitWithTimestamp(inspector, (timestamp) => ({
-		type: "@machine.error",
-		actorId,
-		phase: info.phase,
-		state: info.state,
-		event: info.event,
-		error: Cause.pretty(info.cause),
-		timestamp
-	})));
+	else yield* Deferred.await(runtime.exitDeferred).pipe(Effect.tap((exit) => Deferred.succeed(terminalExitDeferred, exit)), Effect.catchAllCause(() => Effect.void), Effect.fork);
+	return buildActorRefCore(id, machine, stateRef, eventQueueRef, stoppedRef, listeners, Effect.gen(function* () {
+		if (supervisorFiber !== void 0) yield* Fiber.interrupt(supervisorFiber);
+		const currentRuntime = runtimeRef.current;
+		if (currentRuntime !== void 0) yield* currentRuntime.stop;
+		yield* Deferred.succeed(terminalExitDeferred, { _tag: "Stopped" });
+		if (implicitSystemScope !== void 0) yield* Scope.close(implicitSystemScope, Exit.void);
+	}).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid), system, childrenMap, pendingReplies, transitionsPubSub, terminalExitDeferred);
+});
+/** Fail all pending call/ask Deferreds with ActorStoppedError. Safe to call multiple times. */
+const settlePendingReplies = (pendingReplies, actorId) => Effect.sync(() => {
+	const error = new ActorStoppedError({ actorId });
+	for (const deferred of pendingReplies) Effect.runFork(Deferred.fail(deferred, error));
+	pendingReplies.clear();
 });
 /** Notify all system event listeners (sync). */
 const notifySystemListeners = (listeners, event) => {
@@ -474,7 +375,6 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 		});
 		return Effect.all(stops, { concurrency: "unbounded" }).pipe(Effect.zipRight(PubSub.shutdown(eventPubSub)), Effect.asVoid);
 	});
-	/** Check for duplicate ID, register actor, attach scope cleanup if available */
 	const registerActor = Effect.fn("effect-machine.actorSystem.register")(function* (id, actor) {
 		if (MutableHashMap.has(actorsMap, id)) {
 			yield* actor.stop;
@@ -493,7 +393,8 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 				yield* emitSystemEvent({
 					_tag: "ActorStopped",
 					id,
-					actor: actorRef
+					actor: actorRef,
+					exit: { _tag: "Stopped" }
 				});
 				MutableHashMap.remove(actorsMap, id);
 			}
@@ -501,11 +402,24 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 		}));
 		return actor;
 	});
-	const spawnRegular = Effect.fn("effect-machine.actorSystem.spawnRegular")(function* (id, built) {
+	const spawnRegular = Effect.fn("effect-machine.actorSystem.spawnRegular")(function* (id, machine, spawnOptions) {
 		if (MutableHashMap.has(actorsMap, id)) return yield* new DuplicateActorError({ actorId: id });
-		return yield* registerActor(id, yield* createActor(id, built._inner));
+		const materialized = materializeMachine(machine, spawnOptions?.slots);
+		let actorRef;
+		const actor = yield* createActor(id, materialized, {
+			supervision: spawnOptions?.supervision,
+			onRestart: spawnOptions?.supervision !== void 0 ? (generation, exit) => actorRef !== void 0 ? emitSystemEvent({
+				_tag: "ActorRestarted",
+				id,
+				actor: actorRef,
+				generation,
+				exit
+			}) : Effect.void : void 0
+		});
+		actorRef = actor;
+		return yield* registerActor(id, actor);
 	});
-	const spawn = (id, machine) => withSpawnGate(spawnRegular(id, machine));
+	const spawn = (id, machine, options) => withSpawnGate(spawnRegular(id, machine, options));
 	const get = Effect.fn("effect-machine.actorSystem.get")(function* (id) {
 		return yield* Effect.sync(() => MutableHashMap.get(actorsMap, id));
 	});
@@ -517,7 +431,8 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 		yield* emitSystemEvent({
 			_tag: "ActorStopped",
 			id,
-			actor
+			actor,
+			exit: { _tag: "Stopped" }
 		});
 		yield* actor.stop;
 		return true;
@@ -543,8 +458,13 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 	});
 });
 /**
+* Create an ActorSystem instance. Must be run in a Scope.
+* @internal — use Default layer for normal usage
+*/
+const makeSystem = make;
+/**
 * Default ActorSystem layer
 */
-const Default = Layer.scoped(ActorSystem, make());
+const Default = Layer.effect(ActorSystem, make());
 //#endregion
-export { ActorSystem, Default, buildActorRefCore, createActor, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };
+export { ActorSystem, Default, buildActorRefCore, createActor, makeSystem, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };

package/v3/dist/cluster/entity-machine.js

@@ -1,7 +1,7 @@
 import { stubSystem } from "../internal/utils.js";
-import { BuiltMachine, replay } from "../machine.js";
-import { ActorSystem } from "../actor.js";
+import { replay } from "../machine.js";
 import { createRuntime } from "../internal/runtime.js";
+import { ActorSystem } from "../actor.js";
 import { PersistenceAdapter } from "./persistence.js";
 import { Effect, Option, Ref } from "effect";
 import { Entity } from "@effect/cluster";
@@ -47,7 +47,8 @@ const EntityMachine = { layer: (entity, machine, options) => {
 		const versionRef = yield* Ref.make(persistCtx.initialVersion);
 		const runtime = yield* createRuntime(machineWithState, system, {
 			actorId: entityId,
-			hooks: options?.hooks
+			hooks: options?.hooks,
+			childIdPrefix: `${entityId}/`
 		});
 		if (persistCtx.adapter !== void 0) {
 			const { adapter: pAdapter, key } = persistCtx;
@@ -110,8 +111,7 @@ const hydratePersistence = (persistence, entityDef, entityId, machine, initializ
 		const snapshotVersion = Option.isSome(maybeSnapshot) ? maybeSnapshot.value.version : 0;
 		const events = yield* adapter.loadEvents(key, snapshotVersion);
 		if (events.length > 0) {
-			const eventValues = events.map((e) => e.event);
-			const hydratedState = yield* replay(new BuiltMachine(machine), eventValues, { from: baseState });
+			const hydratedState = yield* replay(machine, events.map((e) => e.event), { from: baseState });
 			const lastEvent = events[events.length - 1];
 			return {
 				adapter,