effect-machine 0.19.0 → 0.21.0

package/dist/actor.js

@@ -1,9 +1,10 @@
 import { ActorStoppedError, DuplicateActorError } from "./errors.js";
-import { resolveTransition } from "./internal/transition.js";
+import { resolveTransition, resolveTransitionEffect } from "./internal/transition.js";
 import { emitWithTimestamp, makeInspectionHooks } from "./internal/inspection.js";
 import { Inspector } from "./inspection.js";
+import { ActorExit } from "./supervision.js";
 import { createRuntime } from "./internal/runtime.js";
-import { Context, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Schedule, Scope, Semaphore, Stream, SubscriptionRef } from "effect";
+import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Schedule, Scope, Semaphore, Stream, SubscriptionRef } from "effect";
 //#region src/actor.ts
 /**
 * Actor system: spawning, lifecycle, and event processing.
@@ -13,6 +14,19 @@ import { Context, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option,
 * - ActorSystem service (spawn/stop/get actors)
 * - Actor creation and event loop
 */
+/** A typed identity for an actor stored in an ActorSystem. */
+var ActorSystemKey = class {
+	id;
+	constructor(id) {
+		this.id = id;
+	}
+};
+/** Create a typed ActorSystem identity. */
+const actorSystemKey = (id) => new ActorSystemKey(id);
+const actorSystemId = (id) => {
+	if (typeof id === "string") return id;
+	return id.id;
+};
 /**
 * ActorSystem service tag
 */
@@ -35,11 +49,20 @@ const notifyListeners = (listeners, state) => {
 		listener(state);
 	} catch {}
 };
+const toActorExit = (machine, exit) => {
+	if (exit._tag === "Final") return ActorExit.Final(exit.state, machine._output(exit.state));
+	if (exit._tag === "Defect") return {
+		_tag: "Defect",
+		cause: exit.cause,
+		phase: exit.phase
+	};
+	return { _tag: "Stopped" };
+};
 /**
 * Build core ActorRef methods.
 */
-const buildActorRefCore = (cell, stop, start) => {
-	const { id, machine, stateRef, runtimeRef, listeners, system } = cell;
+const buildActorRefCore = (cell, stop, start, serviceContext) => {
+	const { id, machine, stateRef, runtimeRef, listeners, system, lifecycleRef, latestTransitionRef } = cell;
 	const send = (event) => Effect.gen(function* () {
 		const runtime = runtimeRef.current;
 		if (runtime !== void 0) yield* runtime.send(event);
@@ -59,7 +82,8 @@ const buildActorRefCore = (cell, stop, start) => {
 			reply: void 0,
 			postponed: false,
 			lifecycleRan: false,
-			isFinal: machine._isFinal(currentState._tag)
+			isFinal: machine._isFinal(currentState._tag),
+			transitions: []
 		};
 	});
 	const call = (event) => Effect.suspend(() => {
@@ -76,10 +100,11 @@ const buildActorRefCore = (cell, stop, start) => {
 	const matches = Effect.fn("effect-machine.actor.matches")(function* (tag) {
 		return (yield* SubscriptionRef.get(stateRef))._tag === tag;
 	});
-	const can = Effect.fn("effect-machine.actor.can")(function* (event) {
+	const canEffect = Effect.fn("effect-machine.actor.can")(function* (event) {
 		const state = yield* SubscriptionRef.get(stateRef);
-		return resolveTransition(machine, state, event) !== void 0;
+		return (yield* resolveTransitionEffect(machine, state, event)) !== void 0;
 	});
+	const can = (event) => canEffect(event).pipe(Effect.provide(serviceContext));
 	const waitFor = Effect.fn("effect-machine.actor.waitFor")(function* (predicateOrState) {
 		let predicate;
 		if (typeof predicateOrState === "function" && !("_tag" in predicateOrState)) predicate = predicateOrState;
@@ -101,18 +126,53 @@ const buildActorRefCore = (cell, stop, start) => {
 		return result;
 	});
 	const awaitFinal = waitFor((state) => machine._isFinal(state._tag)).pipe(Effect.withSpan("effect-machine.actor.awaitFinal"));
+	const awaitOutput = Deferred.await(cell.terminalExitDeferred).pipe(Effect.flatMap((exit) => {
+		if (exit._tag === "Final") return Effect.succeed(exit.output);
+		if (exit._tag === "Defect") return Effect.die(Cause.squash(exit.cause));
+		return ActorStoppedError.make({ actorId: id });
+	}), Effect.withSpan("effect-machine.actor.awaitOutput"));
 	const sendAndWait = Effect.fn("effect-machine.actor.sendAndWait")(function* (event, predicateOrState) {
 		yield* send(event);
 		if (predicateOrState !== void 0) return yield* waitFor(predicateOrState);
 		return yield* awaitFinal;
 	});
 	const transitions = Stream.fromPubSub(cell.transitions);
+	const subscribe = (listener) => {
+		listeners.add(listener);
+		return () => {
+			listeners.delete(listener);
+		};
+	};
+	const sendClient = (event) => {
+		runtimeRef.current?.sendSync(event);
+	};
+	const stopClient = () => {
+		Effect.runFork(stop);
+	};
+	const getSnapshot = () => Effect.runSync(SubscriptionRef.get(stateRef));
+	const matchesClient = (tag) => getSnapshot()._tag === tag;
+	const canSync = (event) => resolveTransition(machine, getSnapshot(), event) !== void 0;
+	const getLifecycle = () => Effect.runSync(SubscriptionRef.get(lifecycleRef));
+	const getLatestTransition = () => Effect.runSync(SubscriptionRef.get(latestTransitionRef));
+	const client = {
+		send: sendClient,
+		stop: stopClient,
+		getSnapshot,
+		matches: matchesClient,
+		canSync,
+		can: (event) => Effect.runPromise(can(event)),
+		getLifecycle,
+		getLatestTransition,
+		subscribe
+	};
 	return {
 		id,
 		send,
 		call,
 		ask,
 		state: stateRef,
+		lifecycle: lifecycleRef,
+		latestTransition: latestTransitionRef,
 		stop,
 		start,
 		snapshot,
@@ -122,26 +182,20 @@ const buildActorRefCore = (cell, stop, start) => {
 		transitions,
 		waitFor,
 		awaitFinal,
+		awaitOutput,
 		sendAndWait,
-		subscribe: (fn) => {
-			listeners.add(fn);
-			return () => {
-				listeners.delete(fn);
-			};
-		},
+		subscribe,
+		client,
 		awaitExit: Deferred.await(cell.terminalExitDeferred),
 		drain: Effect.suspend(() => runtimeRef.current?.drain ?? Effect.void),
 		sync: {
-			send: (event) => {
-				runtimeRef.current?.sendSync(event);
-			},
-			stop: () => Effect.runFork(stop),
-			snapshot: () => Effect.runSync(SubscriptionRef.get(stateRef)),
-			matches: (tag) => Effect.runSync(SubscriptionRef.get(stateRef))._tag === tag,
-			can: (event) => {
-				const state = Effect.runSync(SubscriptionRef.get(stateRef));
-				return resolveTransition(machine, state, event) !== void 0;
-			}
+			send: sendClient,
+			stop: stopClient,
+			snapshot: getSnapshot,
+			matches: matchesClient,
+			can: canSync,
+			lifecycle: getLifecycle,
+			latestTransition: getLatestTransition
 		},
 		system,
 		children: cell.children
@@ -175,7 +229,7 @@ const runSupervisionLoop = (cell, options) => Effect.gen(function* () {
 		if (currentRuntime === void 0) return;
 		const generationExit = yield* Deferred.await(currentRuntime.exitDeferred);
 		if (generationExit._tag !== "Defect") {
-			yield* Deferred.succeed(cell.terminalExitDeferred, generationExit);
+			yield* Deferred.succeed(cell.terminalExitDeferred, toActorExit(cell.machine, generationExit));
 			return;
 		}
 		if (options.supervision.shouldRestart !== void 0 && !options.supervision.shouldRestart(generationExit)) {
@@ -188,26 +242,33 @@ const runSupervisionLoop = (cell, options) => Effect.gen(function* () {
 		}
 		const nextGeneration = cell.generation.current + 1;
 		cell.generation.current = nextGeneration;
-		let restartState = cell.machine.initial;
+		let restartState = cell.machineInitial;
 		if (options.lifecycle?.recovery !== void 0) {
 			const resolved = yield* options.lifecycle.recovery.resolve({
 				actorId: cell.id,
 				generation: nextGeneration,
-				machineInitial: cell.machine.initial
+				machineInitial: cell.machineInitial
 			});
 			if (Option.isSome(resolved)) restartState = resolved.value;
 		}
 		yield* currentRuntime.settlePendingRequests;
+		yield* SubscriptionRef.set(cell.lifecycleRef, {
+			_tag: "Starting",
+			generation: nextGeneration
+		});
 		const freshQueue = yield* Queue.unbounded();
 		yield* Ref.set(cell.eventQueueRef, freshQueue);
 		yield* SubscriptionRef.set(cell.stateRef, restartState);
 		yield* Ref.set(cell.stoppedRef, false);
 		cell.children.clear();
-		let machineForRestart = cell.machine;
-		if (restartState !== cell.machine.initial) machineForRestart = cell.machine._withInitial(restartState);
-		const newRuntime = yield* options.spawnGeneration(machineForRestart);
+		const newRuntime = yield* options.spawnGeneration(cell.machine);
 		cell.runtimeRef.current = newRuntime;
 		yield* newRuntime.start;
+		const restartExit = yield* Deferred.poll(newRuntime.exitDeferred);
+		if (Option.isNone(restartExit)) yield* SubscriptionRef.set(cell.lifecycleRef, {
+			_tag: "Active",
+			generation: nextGeneration
+		});
 		if (options.onRestart !== void 0) yield* options.onRestart(nextGeneration, generationExit);
 		notifyListeners(cell.listeners, restartState);
 	}
@@ -217,9 +278,9 @@ const runSupervisionLoop = (cell, options) => Effect.gen(function* () {
 * Delegates to the shared runtime kernel with actor-specific lifecycle hooks.
 */
 const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machine, options) {
-	const lifecycle = options?.lifecycle;
+	const lifecycle = options.lifecycle;
 	const serviceContext = yield* Effect.context();
-	const initial = options?.initialState ?? machine.initial;
+	const initial = options.initialState;
 	yield* Effect.annotateCurrentSpan("effect_machine.actor.id", id);
 	yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", initial._tag);
 	const { system, implicitSystemScope } = yield* resolveActorSystem();
@@ -227,22 +288,24 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	const childrenMap = /* @__PURE__ */ new Map();
 	const listeners = /* @__PURE__ */ new Set();
 	const transitionsPubSub = yield* PubSub.unbounded();
-	let hooks = void 0;
-	if (inspectorValue !== void 0) hooks = makeInspectionHooks(id, inspectorValue);
-	let machineWithState = machine;
-	if (initial !== machine.initial) machineWithState = machine._withInitial(initial);
+	const generation = { current: 0 };
+	const inspectionHooks = (runtimeGeneration) => {
+		if (inspectorValue === void 0) return void 0;
+		return makeInspectionHooks(id, inspectorValue, () => runtimeGeneration);
+	};
 	const stateRef = yield* SubscriptionRef.make(initial);
+	const lifecycleRef = yield* SubscriptionRef.make({ _tag: "Created" });
+	const latestTransitionRef = yield* SubscriptionRef.make(void 0);
 	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 generation = { current: 0 };
 	const runtimeRef = { current: void 0 };
 	const supervisorFiberRef = { current: void 0 };
 	const cell = {
 		id,
 		machine,
+		machineInitial: options.machineInitial,
 		stateRef,
 		stoppedRef,
 		eventQueueRef,
@@ -251,16 +314,19 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		listeners,
 		children: childrenMap,
 		transitions: transitionsPubSub,
+		lifecycleRef,
+		latestTransitionRef,
 		system,
 		generation
 	};
 	/** Build lifecycle hooks for a generation */
-	const buildRuntimeLifecycle = () => {
-		stopEmitted = false;
+	const buildRuntimeLifecycle = (runtimeGeneration) => {
+		let stopEmitted = false;
 		let onEvent = void 0;
 		if (inspectorValue !== void 0) onEvent = (state, event) => emitWithTimestamp(inspectorValue, (timestamp) => ({
 			type: "@machine.event",
 			actorId: id,
+			generation: runtimeGeneration,
 			state,
 			event,
 			timestamp
@@ -271,6 +337,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 			yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
 				type: "@machine.stop",
 				actorId: id,
+				generation: runtimeGeneration,
 				finalState: state,
 				timestamp
 			}));
@@ -279,32 +346,39 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		if (inspectorValue !== void 0) onInitialSpawnEffects = (state) => emitWithTimestamp(inspectorValue, (timestamp) => ({
 			type: "@machine.effect",
 			actorId: id,
+			generation: runtimeGeneration,
 			effectType: "spawn",
 			state,
 			timestamp
 		}));
 		return {
 			onEvent,
-			onStateChange: (result, event) => {
+			onStateChange: (result, event) => Effect.gen(function* () {
+				const latest = result.transitions.at(-1);
+				if (latest !== void 0) yield* SubscriptionRef.set(latestTransitionRef, {
+					fromState: latest.previousState,
+					toState: latest.newState,
+					event: latest.event
+				});
 				notifyListeners(listeners, result.newState);
 				const durability = lifecycle?.durability;
 				if (durability === void 0 || !result.transitioned) return;
 				if (!(durability.shouldSave === void 0 || durability.shouldSave(result.newState, result.previousState))) return;
-				return durability.save({
+				yield* durability.save({
 					actorId: id,
-					generation: generation.current,
+					generation: runtimeGeneration,
 					previousState: result.previousState,
 					nextState: result.newState,
 					event
 				});
-			},
-			onProcessed: (result, event) => {
+			}),
+			onProcessed: (result, _event) => {
 				if (!result.transitioned || transitionsPubSub.subscribers.size === 0) return;
-				return PubSub.publish(transitionsPubSub, {
-					fromState: result.previousState,
-					toState: result.newState,
-					event
-				}).pipe(Effect.asVoid);
+				return Effect.forEach(result.transitions, (transition) => PubSub.publish(transitionsPubSub, {
+					fromState: transition.previousState,
+					toState: transition.newState,
+					event: transition.event
+				}), { discard: true });
 			},
 			onFinal,
 			onShutdown: () => Effect.gen(function* () {
@@ -313,6 +387,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 					yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
 						type: "@machine.stop",
 						actorId: id,
+						generation: runtimeGeneration,
 						finalState,
 						timestamp
 					}));
@@ -322,45 +397,52 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		};
 	};
 	/** 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: buildRuntimeLifecycle(),
-		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);
-			}));
-		})
-	})));
-	runtimeRef.current = yield* spawnGeneration(machineWithState);
-	const supervision = options?.supervision;
+	const spawnGeneration = (machineForGen) => {
+		const runtimeGeneration = generation.current;
+		return Ref.get(eventQueueRef).pipe(Effect.flatMap((currentQueue) => createRuntime(machineForGen, system, {
+			actorId: id,
+			generation: runtimeGeneration,
+			hooks: inspectionHooks(runtimeGeneration),
+			skipFinalizer: true,
+			cellResources: {
+				stateRef,
+				stoppedRef,
+				eventQueue: currentQueue
+			},
+			lifecycle: buildRuntimeLifecycle(runtimeGeneration),
+			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);
+				}));
+			})
+		})));
+	};
+	runtimeRef.current = yield* spawnGeneration(machine);
+	const supervision = options.supervision;
 	const stop = Effect.fn("effect-machine.actor.stop")(function* () {
 		if (supervisorFiberRef.current !== void 0) yield* Fiber.interrupt(supervisorFiberRef.current);
 		const currentRuntime = runtimeRef.current;
 		if (currentRuntime !== void 0) yield* currentRuntime.stop;
-		yield* Deferred.succeed(terminalExitDeferred, { _tag: "Stopped" });
+		yield* Deferred.succeed(terminalExitDeferred, ActorExit.Stopped);
 		if (implicitSystemScope !== void 0) yield* Scope.close(implicitSystemScope, Exit.void);
 	})().pipe(Effect.provide(serviceContext), Effect.asVoid);
-	const isHydrated = options?.initialState !== void 0;
+	const isHydrated = options.hydrated === true;
 	const start = Effect.fn("effect-machine.actor.start")(function* () {
+		yield* SubscriptionRef.set(lifecycleRef, {
+			_tag: "Starting",
+			generation: generation.current
+		});
 		if (lifecycle?.recovery !== void 0 && !isHydrated) {
 			const resolved = yield* lifecycle.recovery.resolve({
 				actorId: id,
 				generation: generation.current,
-				machineInitial: machine.initial
+				machineInitial: options.machineInitial
 			});
 			if (Option.isSome(resolved)) {
 				yield* SubscriptionRef.set(stateRef, resolved.value);
-				const recoveredMachine = machine._withInitial(resolved.value);
-				const newRuntime = yield* spawnGeneration(recoveredMachine);
+				const newRuntime = yield* spawnGeneration(machine);
 				runtimeRef.current = newRuntime;
 			}
 		}
@@ -368,6 +450,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
 			type: "@machine.spawn",
 			actorId: id,
+			generation: generation.current,
 			initialState: currentState,
 			timestamp
 		}));
@@ -375,16 +458,24 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 			supervision,
 			spawnGeneration,
 			lifecycle,
-			onRestart: options?.onRestart
+			onRestart: options.onRestart
 		}));
 		else {
 			const currentRuntime = runtimeRef.current;
-			if (currentRuntime !== void 0) yield* Effect.forkDetach(Deferred.await(currentRuntime.exitDeferred).pipe(Effect.tap((exit) => Deferred.succeed(terminalExitDeferred, exit))));
+			if (currentRuntime !== void 0) yield* Effect.forkDetach(Deferred.await(currentRuntime.exitDeferred).pipe(Effect.tap((exit) => Deferred.succeed(terminalExitDeferred, toActorExit(machine, exit)))));
 		}
 		const currentRuntime = runtimeRef.current;
-		if (currentRuntime !== void 0) yield* currentRuntime.start;
+		if (currentRuntime !== void 0) {
+			yield* currentRuntime.start;
+			const currentExit = yield* Deferred.poll(currentRuntime.exitDeferred);
+			if (Option.isNone(currentExit)) yield* SubscriptionRef.set(lifecycleRef, {
+				_tag: "Active",
+				generation: generation.current
+			});
+		}
 	})().pipe(Effect.provide(serviceContext), Effect.asVoid);
-	return buildActorRefCore(cell, stop, start);
+	yield* Effect.forkDetach(Deferred.await(terminalExitDeferred).pipe(Effect.flatMap((exit) => SubscriptionRef.set(lifecycleRef, exit)), Effect.provide(serviceContext)));
+	return buildActorRefCore(cell, stop, start, serviceContext);
 });
 /** Notify all system event listeners (sync). */
 const notifySystemListeners = (listeners, event) => {
@@ -418,6 +509,17 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 			id,
 			actor: actorRef
 		});
+		yield* Effect.forkDetach(actorRef.awaitExit.pipe(Effect.flatMap((exit) => {
+			const registered = MutableHashMap.get(actorsMap, id);
+			if (Option.isNone(registered) || registered.value !== actorRef) return Effect.void;
+			MutableHashMap.remove(actorsMap, id);
+			return emitSystemEvent({
+				_tag: "ActorStopped",
+				id,
+				actor: actorRef,
+				exit
+			});
+		})));
 		const maybeScope = yield* Effect.serviceOption(ActorScope);
 		if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, Effect.gen(function* () {
 			if (MutableHashMap.has(actorsMap, id)) {
@@ -448,7 +550,12 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 				exit
 			});
 		};
+		const machineInitial = machine._initial(spawnOptions?.input);
+		const initialState = spawnOptions?.hydrate ?? machineInitial;
 		const actor = yield* createActor(id, machine, {
+			initialState,
+			machineInitial,
+			hydrated: spawnOptions?.hydrate !== void 0,
 			supervision: spawnOptions?.supervision,
 			lifecycle: spawnOptions?.lifecycle,
 			onRestart
@@ -458,11 +565,34 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 		yield* actor.start.pipe(Effect.catchCause((cause) => actor.stop.pipe(Effect.andThen(Effect.failCause(cause)))));
 		return actor;
 	});
-	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));
-	});
-	const stop = Effect.fn("effect-machine.actorSystem.stop")(function* (id) {
+	const spawn = (idOrKey, machine, options) => {
+		const id = actorSystemId(idOrKey);
+		return withSpawnGate(spawnRegular(id, machine, options));
+	};
+	function get(idOrKey) {
+		return Effect.sync(() => MutableHashMap.get(actorsMap, actorSystemId(idOrKey)));
+	}
+	const sameActor = (left, right) => {
+		if (Option.isNone(left)) return Option.isNone(right);
+		return Option.isSome(right) && Object.is(left.value, right.value);
+	};
+	function watch(idOrKey) {
+		const id = actorSystemId(idOrKey);
+		return Stream.callback((queue) => Effect.acquireRelease(Effect.sync(() => {
+			const unsubscribe = (event) => {
+				if (event.id !== id) return;
+				if (event._tag === "ActorSpawned") Queue.offerUnsafe(queue, Option.some(event.actor));
+				else if (event._tag === "ActorStopped") Queue.offerUnsafe(queue, Option.none());
+			};
+			eventListeners.add(unsubscribe);
+			Queue.offerUnsafe(queue, MutableHashMap.get(actorsMap, id));
+			return () => {
+				eventListeners.delete(unsubscribe);
+			};
+		}), (unsubscribe) => Effect.sync(unsubscribe))).pipe(Stream.changesWith(sameActor));
+	}
+	const stop = Effect.fn("effect-machine.actorSystem.stop")(function* (idOrKey) {
+		const id = actorSystemId(idOrKey);
 		const maybeActor = MutableHashMap.get(actorsMap, id);
 		if (Option.isNone(maybeActor)) return false;
 		const actor = maybeActor.value;
@@ -479,6 +609,7 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 	return ActorSystem.of({
 		spawn,
 		get,
+		watch,
 		stop,
 		events: Stream.fromPubSub(eventPubSub),
 		get actors() {
@@ -506,4 +637,4 @@ const makeSystem = make;
 */
 const Default = Layer.effect(ActorSystem, make());
 //#endregion
-export { ActorScope, ActorSystem, Default, createActor, makeSystem };
+export { ActorScope, ActorSystem, ActorSystemKey, Default, actorSystemKey, createActor, makeSystem };

package/dist/atom.d.ts

@@ -1,5 +1,8 @@
-import { ActorRef } from "./actor.js";
+import { ActorLifecycle, ActorRef, ActorSystemKey, ActorSystemService, TransitionInfo } from "./actor.js";
+import * as Option from "effect/Option";
 import * as Atom from "effect/unstable/reactivity/Atom";
+import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
+import * as Cause from "effect/Cause";
 //#region src/atom.d.ts
 /**
  * A writable Atom projection of an actor.
@@ -7,6 +10,32 @@ import * as Atom from "effect/unstable/reactivity/Atom";
  * The Atom value is the current actor state. Atom writes send actor events.
  */
 type ActorAtom<State, Event> = Atom.Writable<State, Event>;
+/** A reactive ActorSystem lookup for one typed actor identity. */
+type ActorLookupAtom<State extends {
+  readonly _tag: string;
+}, Event, Output> = Atom.Atom<AsyncResult.AsyncResult<Option.Option<ActorRef<State, Event, Output>>, Cause.NoSuchElementError>>;
+/** A Suspense-ready actor acquisition that follows later actor generations. */
+type ActorAcquireAtom<State extends {
+  readonly _tag: string;
+}, Event, Output> = Atom.Atom<AsyncResult.AsyncResult<ActorRef<State, Event, Output>, Cause.NoSuchElementError>>;
+/** Observe the current ActorRef for one ActorSystem key. */
+declare const fromSystem: {
+  <State extends {
+    readonly _tag: string;
+  }, Event, Output>(key: ActorSystemKey<State, Event, Output>): (system: ActorSystemService) => ActorLookupAtom<State, Event, Output>;
+  <State extends {
+    readonly _tag: string;
+  }, Event, Output>(system: ActorSystemService, key: ActorSystemKey<State, Event, Output>): ActorLookupAtom<State, Event, Output>;
+};
+/** Suspend while an ActorSystem key is absent and follow later generations. */
+declare const acquire: {
+  <State extends {
+    readonly _tag: string;
+  }, Event, Output>(key: ActorSystemKey<State, Event, Output>): (system: ActorSystemService) => ActorAcquireAtom<State, Event, Output>;
+  <State extends {
+    readonly _tag: string;
+  }, Event, Output>(system: ActorSystemService, key: ActorSystemKey<State, Event, Output>): ActorAcquireAtom<State, Event, Output>;
+};
 /**
  * Make a writable Atom from an actor.
  *
@@ -16,7 +45,7 @@ type ActorAtom<State, Event> = Atom.Writable<State, Event>;
  */
 declare const make: <State extends {
   readonly _tag: string;
-}, Event>(actor: ActorRef<State, Event>) => ActorAtom<State, Event>;
+}, Event, Output>(actor: ActorRef<State, Event, Output>) => ActorAtom<State, Event>;
 /**
  * Select part of an actor state.
  *
@@ -27,5 +56,29 @@ declare const select: {
   <State, Selection>(selector: (state: State) => Selection, equals?: (value: Selection, next: Selection) => boolean): <Event>(self: ActorAtom<State, Event>) => ActorAtom<Selection, Event>;
   <State, Event, Selection>(self: ActorAtom<State, Event>, selector: (state: State) => Selection, equals?: (value: Selection, next: Selection) => boolean): ActorAtom<Selection, Event>;
 };
+/** Observe actor lifecycle without coupling it to domain state. */
+declare const lifecycle: <State extends {
+  readonly _tag: string;
+}, Event, Output>(actor: ActorRef<State, Event, Output>) => Atom.Atom<ActorLifecycle<State, Output>>;
+/** Observe the latest accepted edge. The value remains after actor exit. */
+declare const latestTransition: <State extends {
+  readonly _tag: string;
+}, Event, Output>(actor: ActorRef<State, Event, Output>) => Atom.Atom<TransitionInfo<State, Event> | undefined>;
+/** A reactive result for whether an actor can accept one event. */
+type CanAtom = Atom.Atom<AsyncResult.AsyncResult<boolean>>;
+/**
+ * Observe whether an event has an enabled transition.
+ *
+ * The Atom reevaluates after each actor state change. It supports pure and
+ * Effect predicates. Effect predicates use the context captured by the actor.
+ */
+declare const can: {
+  <Event>(event: Event): <State extends {
+    readonly _tag: string;
+  }, Output>(actor: ActorRef<State, Event, Output>) => CanAtom;
+  <State extends {
+    readonly _tag: string;
+  }, Event, Output>(actor: ActorRef<State, Event, Output>, event: Event): CanAtom;
+};
 //#endregion
-export { ActorAtom, make, select };
+export { ActorAcquireAtom, ActorAtom, ActorLookupAtom, CanAtom, acquire, can, fromSystem, latestTransition, lifecycle, make, select };