effect-machine 0.18.0 → 0.20.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.
@@ -35,11 +36,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 +69,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 +87,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 +113,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 +169,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 +216,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 +229,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 +265,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 +275,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 +301,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 +324,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 +333,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 +374,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 +384,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 +437,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 +445,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 +496,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 +537,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

package/dist/atom.d.ts

@@ -0,0 +1,56 @@
+import { ActorLifecycle, ActorRef, TransitionInfo } from "./actor.js";
+import * as Atom from "effect/unstable/reactivity/Atom";
+import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
+//#region src/atom.d.ts
+/**
+ * A writable Atom projection of an actor.
+ *
+ * The Atom value is the current actor state. Atom writes send actor events.
+ */
+type ActorAtom<State, Event> = Atom.Writable<State, Event>;
+/**
+ * Make a writable Atom from an actor.
+ *
+ * The actor stays the single state owner. The Atom follows recovery,
+ * supervision restarts, and normal transitions through the actor's
+ * SubscriptionRef.
+ */
+declare const make: <State extends {
+  readonly _tag: string;
+}, Event, Output>(actor: ActorRef<State, Event, Output>) => ActorAtom<State, Event>;
+/**
+ * Select part of an actor state.
+ *
+ * The selected Atom stays writable. Writes still send events to the actor.
+ * The equality function controls when Atom subscribers receive a new value.
+ */
+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, CanAtom, can, latestTransition, lifecycle, make, select };

package/dist/atom.js

@@ -0,0 +1,47 @@
+import { dual } from "effect/Function";
+import * as Atom from "effect/unstable/reactivity/Atom";
+import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
+//#region src/atom.ts
+/**
+* Effect Atom integration for actors.
+*
+* The adapter keeps the actor as the state owner. Atom registries observe the
+* actor's SubscriptionRef and write events through its synchronous boundary.
+*/
+/**
+* Make a writable Atom from an actor.
+*
+* The actor stays the single state owner. The Atom follows recovery,
+* supervision restarts, and normal transitions through the actor's
+* SubscriptionRef.
+*/
+const make = (actor) => {
+	const state = Atom.subscriptionRef(actor.state);
+	return Atom.writable((get) => get(state), (_ctx, event) => actor.client.send(event));
+};
+/**
+* Select part of an actor state.
+*
+* The selected Atom stays writable. Writes still send events to the actor.
+* The equality function controls when Atom subscribers receive a new value.
+*/
+const select = dual((args) => Atom.isAtom(args[0]), (self, selector, equals = Object.is) => Atom.withEquality(Atom.map(self, selector), equals));
+/** Observe actor lifecycle without coupling it to domain state. */
+const lifecycle = (actor) => Atom.subscriptionRef(actor.lifecycle);
+/** Observe the latest accepted edge. The value remains after actor exit. */
+const latestTransition = (actor) => Atom.subscriptionRef(actor.latestTransition);
+/**
+* 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.
+*/
+const can = dual(2, (actor, event) => {
+	const state = Atom.subscriptionRef(actor.state);
+	return Atom.make((get) => {
+		get(state);
+		return actor.can(event);
+	}).pipe(Atom.withEquality((value, next) => AsyncResult.isSuccess(value) && AsyncResult.isSuccess(next) && Object.is(value.value, next.value)));
+});
+//#endregion
+export { can, latestTransition, lifecycle, make, select };

package/dist/cluster/entity-machine.d.ts

@@ -7,7 +7,7 @@ import { Rpc } from "effect/unstable/rpc";
 /**
  * Options for EntityMachine.layer
  */
-interface EntityMachineOptions<S> {
+interface EntityMachineBaseOptions<S> {
   /**
    * Initialize state from entity ID.
    * Called once when entity is first activated.
@@ -38,6 +38,12 @@ interface EntityMachineOptions<S> {
    */
   readonly persistence?: EntityPersistenceConfig;
 }
+type EntityMachineOptions<S, Input = void> = EntityMachineBaseOptions<S> & ([Input] extends [void] ? {
+  readonly input?: never;
+} : {
+  /** Map the entity ID to the machine input. */
+  readonly input: (entityId: string) => Input;
+});
 /**
  * Create an Entity layer that wires a machine to handle RPC calls.
  *
@@ -59,7 +65,7 @@ declare const EntityMachine: {
     readonly _tag: string;
   }, E extends {
     readonly _tag: string;
-  }, R, EntityType extends string, Rpcs extends Rpc.Any>(entity: Entity.Entity<EntityType, Rpcs>, machine: Machine<S, E, R, any, any>, options?: EntityMachineOptions<S>) => Layer.Layer<never, never, R>;
+  }, R, Input, Output, EntityType extends string, Rpcs extends Rpc.Any>(entity: Entity.Entity<EntityType, Rpcs>, machine: Machine<S, E, R, any, any, Input, Output>, ...optionsArgument: [Input] extends [void] ? [options?: EntityMachineOptions<S, Input>] : [options: EntityMachineOptions<S, Input>]) => Layer.Layer<never, never, R>;
 };
 //#endregion
-export { EntityMachine, EntityMachineOptions };
+export { EntityMachine, EntityMachineBaseOptions, EntityMachineOptions };

package/dist/cluster/entity-machine.js

@@ -35,7 +35,8 @@ import { Entity } from "effect/unstable/cluster";
 * })
 * ```
 */
-const EntityMachine = { layer: (entity, machine, options) => {
+const EntityMachine = { layer: (entity, machine, ...optionsArgument) => {
+	const options = optionsArgument[0];
 	const persistence = options?.persistence;
 	const build = Effect.gen(function* () {
 		const entityId = yield* Effect.serviceOption(Entity.CurrentAddress).pipe(Effect.map((opt) => {
@@ -43,23 +44,22 @@ const EntityMachine = { layer: (entity, machine, options) => {
 			return "";
 		}));
 		const inspector = Option.getOrUndefined(yield* Effect.serviceOption(Inspector));
+		const machineInitial = machine._initial(options?.input?.(entityId));
 		const existingSystem = yield* Effect.serviceOption(ActorSystem);
 		let system;
 		if (Option.isSome(existingSystem)) system = existingSystem.value;
 		else system = yield* makeSystem();
-		const persistCtx = yield* hydratePersistence(persistence, entity, entityId, machine, options?.initializeState);
+		const persistCtx = yield* hydratePersistence(persistence, entity, entityId, machine, machineInitial, options?.initializeState);
 		let initialState = persistCtx.hydratedState;
 		if (initialState === void 0 && options?.initializeState !== void 0) initialState = options.initializeState(entityId);
-		let machineWithState = machine;
-		if (initialState !== void 0) machineWithState = machine._withInitial(initialState);
 		const versionRef = yield* Ref.make(persistCtx.initialVersion);
-		const computedInitial = initialState ?? machine.initial;
+		const computedInitial = initialState ?? machineInitial;
 		const stateRef = yield* SubscriptionRef.make(computedInitial);
 		const stoppedRef = yield* Ref.make(false);
 		const eventQueue = yield* Queue.unbounded();
 		let hooks = void 0;
 		if (inspector !== void 0) hooks = makeInspectionHooks(entityId, inspector);
-		const runtime = yield* createRuntime(machineWithState, system, {
+		const runtime = yield* createRuntime(machine, system, {
 			actorId: entityId,
 			hooks,
 			childIdPrefix: `${entityId}/`,
@@ -152,7 +152,7 @@ const noPersistence = {
 	initialVersion: 0
 };
 /** Load snapshot/journal and compute hydrated state. */
-const hydratePersistence = (persistence, entityDef, entityId, machine, initializeState) => Effect.gen(function* () {
+const hydratePersistence = (persistence, entityDef, entityId, machine, machineInitial, initializeState) => Effect.gen(function* () {
 	if (persistence === void 0) return noPersistence;
 	const adapter = yield* PersistenceAdapter;
 	const key = {
@@ -164,7 +164,7 @@ const hydratePersistence = (persistence, entityDef, entityId, machine, initializ
 		let baseState;
 		if (Option.isSome(maybeSnapshot)) baseState = maybeSnapshot.value.state;
 		else if (initializeState !== void 0) baseState = initializeState(entityId);
-		else baseState = machine.initial;
+		else baseState = machineInitial;
 		let snapshotVersion = 0;
 		if (Option.isSome(maybeSnapshot)) snapshotVersion = maybeSnapshot.value.version;
 		const events = yield* adapter.loadEvents(key, snapshotVersion);

package/dist/cluster/index.d.ts

@@ -2,5 +2,5 @@ import { EntityPersistenceConfig, PersistedEvent, PersistenceAdapter, Persistenc
 import { makeInMemoryPersistenceAdapter } from "./adapters/in-memory.js";
 import { EntityRpcs, ToEntityOptions, toEntity } from "./to-entity.js";
 import { EntityActorRef, makeEntityActorRef } from "./entity-actor-ref.js";
-import { EntityMachine, EntityMachineOptions } from "./entity-machine.js";
-export { type EntityActorRef, EntityMachine, type EntityMachineOptions, type EntityPersistenceConfig, type EntityRpcs, type PersistedEvent, PersistenceAdapter, type PersistenceAdapterService as PersistenceAdapterInterface, type PersistenceKey, type Snapshot, type ToEntityOptions, makeEntityActorRef, makeInMemoryPersistenceAdapter, toEntity };
+import { EntityMachine, EntityMachineBaseOptions, EntityMachineOptions } from "./entity-machine.js";
+export { type EntityActorRef, EntityMachine, type EntityMachineBaseOptions, type EntityMachineOptions, type EntityPersistenceConfig, type EntityRpcs, type PersistedEvent, PersistenceAdapter, type PersistenceAdapterService as PersistenceAdapterInterface, type PersistenceKey, type Snapshot, type ToEntityOptions, makeEntityActorRef, makeInMemoryPersistenceAdapter, toEntity };