effect-machine 0.11.0 → 0.13.0

package/dist/actor.js

@@ -1,9 +1,9 @@
 import { Inspector } from "./inspection.js";
-import { INTERNAL_INIT_EVENT } from "./internal/utils.js";
-import { ActorStoppedError, DuplicateActorError, NoReplyError } 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, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Scope, Semaphore, ServiceMap, Stream, SubscriptionRef } from "effect";
+import { ActorStoppedError, DuplicateActorError } from "./errors.js";
+import { createRuntime } from "./internal/runtime.js";
+import { Cause, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Schedule, Scope, Semaphore, ServiceMap, Stream, SubscriptionRef } from "effect";
 //#region src/actor.ts
 /**
 * Actor system: spawning, lifecycle, and event processing.
@@ -28,10 +28,11 @@ const notifyListeners = (listeners, state) => {
 /**
 * 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 +50,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 +68,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
@@ -126,12 +129,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)),
@@ -144,12 +162,41 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 		children: childrenMap
 	};
 };
+/** Build ProcessEventHooks from an inspector */
+const buildInspectionHooks = (actorId, inspector) => ({
+	onSpawnEffect: (state) => emitWithTimestamp(inspector, (timestamp) => ({
+		type: "@machine.effect",
+		actorId,
+		effectType: "spawn",
+		state,
+		timestamp
+	})),
+	onTransition: (from, to, ev) => emitWithTimestamp(inspector, (timestamp) => ({
+		type: "@machine.transition",
+		actorId,
+		fromState: from,
+		toState: to,
+		event: ev,
+		timestamp
+	})),
+	onError: (info) => emitWithTimestamp(inspector, (timestamp) => ({
+		type: "@machine.error",
+		actorId,
+		phase: info.phase,
+		state: info.state,
+		event: info.event,
+		error: Cause.pretty(info.cause),
+		timestamp
+	}))
+});
 /**
-* Create and start an actor for a machine
+* Create and start an actor for a machine.
+* Delegates to the shared runtime kernel with actor-specific lifecycle hooks.
 */
 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;
@@ -160,92 +207,149 @@ 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 hooks = inspectorValue !== void 0 ? buildInspectionHooks(id, inspectorValue) : void 0;
+	const machineWithState = initial !== machine.initial ? Object.create(machine, { initial: {
+		value: initial,
+		enumerable: true
+	} }) : machine;
 	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 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 {
+			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
+		};
 	};
-	const { effects: effectSlots } = machine._slots;
-	for (const bg of machine.backgroundEffects) {
-		const fiber = yield* Effect.forkDetach(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.forkDetach(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" });
+	/** Create a single runtime generation. machineForGen is machineWithState for initial, machine for restarts. */
+	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);
+			}));
+		})
+	})));
+	const runtime = yield* spawnGeneration(machineWithState);
+	runtimeRef.current = runtime;
+	const supervision = options?.supervision;
+	let supervisorFiber;
+	if (supervision !== void 0) supervisorFiber = yield* Effect.forkDetach(Effect.gen(function* () {
+		const step = yield* Schedule.toStepWithSleep(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* step(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);
+		}
+	}));
+	else yield* Effect.forkDetach(Deferred.await(runtime.exitDeferred).pipe(Effect.tap((exit) => Deferred.succeed(terminalExitDeferred, exit))));
+	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);
+	}).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(() => {
@@ -253,194 +357,6 @@ const settlePendingReplies = (pendingReplies, actorId) => Effect.sync(() => {
 	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,
-					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) 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) => ({
-			type: "@machine.effect",
-			actorId,
-			effectType: "spawn",
-			state,
-			timestamp
-		})),
-		onTransition: (from, to, ev) => emitWithTimestamp(inspector, (timestamp) => ({
-			type: "@machine.transition",
-			actorId,
-			fromState: from,
-			toState: to,
-			event: ev,
-			timestamp
-		})),
-		onError: (info) => emitWithTimestamp(inspector, (timestamp) => ({
-			type: "@machine.error",
-			actorId,
-			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);
-		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,
-				timestamp
-			}));
-			return {
-				shouldStop: true,
-				result
-			};
-		}
-	}
-	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
-	})));
-});
 /** Notify all system event listeners (sync). */
 const notifySystemListeners = (listeners, event) => {
 	for (const listener of listeners) try {
@@ -479,7 +395,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);
 			}
@@ -487,11 +404,23 @@ 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));
+		let actorRef;
+		const actor = yield* createActor(id, machine, {
+			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));
 	});
@@ -503,7 +432,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;
@@ -529,8 +459,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.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/dist/cluster/adapters/in-memory.d.ts

@@ -0,0 +1,28 @@
+import { PersistedEvent, PersistenceAdapter, Snapshot } from "../persistence.js";
+import { Effect, Layer, Ref } from "effect";
+
+//#region src/cluster/adapters/in-memory.d.ts
+interface EntityStore {
+  snapshot: Snapshot<unknown> | undefined;
+  events: Array<PersistedEvent<unknown>>;
+}
+/**
+ * Create an in-memory persistence adapter.
+ *
+ * Returns a Layer providing `PersistenceAdapter` and a ref
+ * to the backing store for test assertions.
+ *
+ * @example
+ * ```ts
+ * const { layer, storeRef } = yield* makeInMemoryPersistenceAdapter
+ * // Use layer to provide PersistenceAdapter
+ * // Inspect storeRef for test assertions
+ * ```
+ */
+declare const makeInMemoryPersistenceAdapter: Effect.Effect<{
+  adapter: PersistenceAdapter;
+  storeRef: Ref.Ref<Map<string, EntityStore>>;
+  layer: Layer.Layer<PersistenceAdapter, never, never>;
+}, never, never>;
+//#endregion
+export { makeInMemoryPersistenceAdapter };