effect-machine 0.10.0 → 0.12.0

package/dist/actor.js

@@ -1,12 +1,9 @@
 import { Inspector } from "./inspection.js";
 import { INTERNAL_INIT_EVENT } from "./internal/utils.js";
 import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.js";
-import { isPersistentMachine } from "./persistence/persistent-machine.js";
 import { emitWithTimestamp } from "./internal/inspection.js";
 import { processEventCore, resolveTransition, runSpawnEffects, shouldPostpone } from "./internal/transition.js";
-import { PersistenceAdapterTag, PersistenceError } from "./persistence/adapter.js";
-import { createPersistentActor, restorePersistentActor } from "./persistence/persistent-actor.js";
-import { Cause, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Scope, Semaphore, ServiceMap, Stream, SubscriptionRef } from "effect";
+import { Cause, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Schema, Scope, Semaphore, ServiceMap, Stream, SubscriptionRef } from "effect";
 //#region src/actor.ts
 /**
 * Actor system: spawning, lifecycle, and event processing.
@@ -29,9 +26,9 @@ 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) => {
+const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listeners, stop, system, childrenMap, pendingReplies, transitionsPubSub) => {
 	const send = Effect.fn("effect-machine.actor.send")(function* (event) {
 		if (yield* Ref.get(stoppedRef)) return;
 		yield* Queue.offer(eventQueue, {
@@ -119,6 +116,7 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 		matches,
 		can,
 		changes: SubscriptionRef.changes(stateRef),
+		transitions: transitionsPubSub !== void 0 ? Stream.fromPubSub(transitionsPubSub) : Stream.empty,
 		waitFor,
 		awaitFinal,
 		sendAndWait,
@@ -149,7 +147,8 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 /**
 * Create and start an actor for a machine
 */
-const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machine) {
+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);
 	const existingSystem = yield* Effect.serviceOption(ActorSystem);
 	let system;
@@ -164,6 +163,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	const eventQueue = yield* Queue.unbounded();
 	const stoppedRef = yield* Ref.make(false);
 	const childrenMap = /* @__PURE__ */ new Map();
+	const deferredReplyRef = { current: void 0 };
 	const selfSend = Effect.fn("effect-machine.actor.self.send")(function* (event) {
 		if (yield* Ref.get(stoppedRef)) return;
 		yield* Queue.offer(eventQueue, {
@@ -182,22 +182,31 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 				childrenMap.delete(childId);
 			}));
 			return child;
+		}),
+		reply: (value) => Effect.sync(() => {
+			const deferred = deferredReplyRef.current;
+			if (deferred !== void 0) {
+				deferredReplyRef.current = void 0;
+				Effect.runFork(Deferred.succeed(deferred, value));
+				return true;
+			}
+			return false;
 		})
 	};
-	yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", machine.initial._tag);
+	yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", initial._tag);
 	yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
 		type: "@machine.spawn",
 		actorId: id,
-		initialState: machine.initial,
+		initialState: initial,
 		timestamp
 	}));
-	const stateRef = yield* SubscriptionRef.make(machine.initial);
+	const stateRef = yield* SubscriptionRef.make(initial);
 	const listeners = /* @__PURE__ */ new Set();
 	const backgroundFibers = [];
 	const initEvent = { _tag: INTERNAL_INIT_EVENT };
 	const ctx = {
 		actorId: id,
-		state: machine.initial,
+		state: initial,
 		event: initEvent,
 		self,
 		system
@@ -206,7 +215,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	for (const bg of machine.backgroundEffects) {
 		const fiber = yield* Effect.forkDetach(bg.handler({
 			actorId: id,
-			state: machine.initial,
+			state: initial,
 			event: initEvent,
 			self,
 			effects: effectSlots,
@@ -215,14 +224,14 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		backgroundFibers.push(fiber);
 	}
 	const stateScopeRef = { current: yield* Scope.make() };
-	yield* runSpawnEffectsWithInspection(machine, machine.initial, initEvent, self, stateScopeRef.current, id, inspectorValue, system);
-	if (machine.finalStates.has(machine.initial._tag)) {
+	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: machine.initial,
+			finalState: initial,
 			timestamp
 		}));
 		yield* Ref.set(stoppedRef, true);
@@ -230,7 +239,8 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		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 loopFiber = yield* Effect.forkDetach(eventLoop(machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, id, inspectorValue, system, pendingReplies));
+	const transitionsPubSub = yield* PubSub.unbounded();
+	const loopFiber = yield* Effect.forkDetach(eventLoop(machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, id, inspectorValue, system, pendingReplies, transitionsPubSub, deferredReplyRef));
 	return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, Effect.gen(function* () {
 		const finalState = yield* SubscriptionRef.get(stateRef);
 		yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
@@ -245,7 +255,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		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);
+	}).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(() => {
@@ -258,7 +268,7 @@ const settlePendingReplies = (pendingReplies, actorId) => Effect.sync(() => {
 * 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) {
+const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, actorId, inspector, system, pendingReplies, transitionsPubSub, deferredReplyRef) {
 	const postponed = [];
 	const hasPostponeRules = machine.postponeRules.length > 0;
 	const processQueued = Effect.fn("effect-machine.actor.processQueued")(function* (queued) {
@@ -274,6 +284,7 @@ const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine
 					lifecycleRan: false,
 					isFinal: false,
 					hasReply: false,
+					deferReply: false,
 					reply: void 0,
 					postponed: true
 				};
@@ -294,13 +305,30 @@ const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine
 				yield* Deferred.succeed(queued.reply, result);
 				break;
 			case "ask":
-				if (result.hasReply) yield* Deferred.succeed(queued.reply, result.reply);
+				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 if (result.deferReply) deferredReplyRef.current = queued.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
@@ -316,15 +344,21 @@ const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine
 			yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
 			return;
 		}
-		if (stateChanged && postponed.length > 0) {
+		let drainTriggered = stateChanged;
+		while (drainTriggered && postponed.length > 0) {
+			drainTriggered = false;
 			const drained = postponed.splice(0);
-			for (const entry of drained) if ((yield* processQueued(entry)).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;
+			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;
 			}
 		}
 	}
@@ -480,25 +514,7 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 		if (MutableHashMap.has(actorsMap, id)) return yield* new DuplicateActorError({ actorId: id });
 		return yield* registerActor(id, yield* createActor(id, built._inner));
 	});
-	const spawnPersistent = Effect.fn("effect-machine.actorSystem.spawnPersistent")(function* (id, persistentMachine) {
-		if (MutableHashMap.has(actorsMap, id)) return yield* new DuplicateActorError({ actorId: id });
-		const adapter = yield* PersistenceAdapterTag;
-		const maybeSnapshot = yield* adapter.loadSnapshot(id, persistentMachine.persistence.stateSchema);
-		return yield* registerActor(id, yield* createPersistentActor(id, persistentMachine, maybeSnapshot, yield* adapter.loadEvents(id, persistentMachine.persistence.eventSchema, Option.isSome(maybeSnapshot) ? maybeSnapshot.value.version : void 0)));
-	});
-	const spawnImpl = Effect.fn("effect-machine.actorSystem.spawn")(function* (id, machine) {
-		if (isPersistentMachine(machine)) return yield* spawnPersistent(id, machine);
-		return yield* spawnRegular(id, machine);
-	});
-	function spawn(id, machine) {
-		return withSpawnGate(spawnImpl(id, machine));
-	}
-	const restoreImpl = Effect.fn("effect-machine.actorSystem.restore")(function* (id, persistentMachine) {
-		const maybeActor = yield* restorePersistentActor(id, persistentMachine);
-		if (Option.isSome(maybeActor)) yield* registerActor(id, maybeActor.value);
-		return maybeActor;
-	});
-	const restore = (id, persistentMachine) => withSpawnGate(restoreImpl(id, persistentMachine));
+	const spawn = (id, machine) => withSpawnGate(spawnRegular(id, machine));
 	const get = Effect.fn("effect-machine.actorSystem.get")(function* (id) {
 		return yield* Effect.sync(() => MutableHashMap.get(actorsMap, id));
 	});
@@ -515,55 +531,8 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 		yield* actor.stop;
 		return true;
 	});
-	const listPersisted = Effect.fn("effect-machine.actorSystem.listPersisted")(function* () {
-		const adapter = yield* PersistenceAdapterTag;
-		if (adapter.listActors === void 0) return [];
-		return yield* adapter.listActors();
-	});
-	const restoreMany = Effect.fn("effect-machine.actorSystem.restoreMany")(function* (ids, persistentMachine) {
-		const restored = [];
-		const failed = [];
-		for (const id of ids) {
-			if (MutableHashMap.has(actorsMap, id)) continue;
-			const result = yield* Effect.result(restore(id, persistentMachine));
-			if (result._tag === "Failure") failed.push({
-				id,
-				error: result.failure
-			});
-			else if (Option.isSome(result.success)) restored.push(result.success.value);
-			else failed.push({
-				id,
-				error: new PersistenceError({
-					operation: "restore",
-					actorId: id,
-					message: "No persisted state found"
-				})
-			});
-		}
-		return {
-			restored,
-			failed
-		};
-	});
-	const restoreAll = Effect.fn("effect-machine.actorSystem.restoreAll")(function* (persistentMachine, options) {
-		const adapter = yield* PersistenceAdapterTag;
-		if (adapter.listActors === void 0) return {
-			restored: [],
-			failed: []
-		};
-		const machineType = persistentMachine.persistence.machineType;
-		if (machineType === void 0) return yield* new PersistenceError({
-			operation: "restoreAll",
-			actorId: "*",
-			message: "restoreAll requires explicit machineType in persistence config"
-		});
-		let filtered = (yield* adapter.listActors()).filter((meta) => meta.machineType === machineType);
-		if (options?.filter !== void 0) filtered = filtered.filter(options.filter);
-		return yield* restoreMany(filtered.map((meta) => meta.id), persistentMachine);
-	});
 	return ActorSystem.of({
 		spawn,
-		restore,
 		get,
 		stop,
 		events: Stream.fromPubSub(eventPubSub),
@@ -579,15 +548,17 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 			return () => {
 				eventListeners.delete(fn);
 			};
-		},
-		listPersisted,
-		restoreMany,
-		restoreAll
+		}
 	});
 });
 /**
+* 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 };

package/dist/cluster/adapters/in-memory.js

@@ -0,0 +1,79 @@
+import { VersionConflictError } from "../../errors.js";
+import { PersistenceAdapter } from "../persistence.js";
+import { Effect, Layer, Option, Ref } from "effect";
+//#region src/cluster/adapters/in-memory.ts
+/**
+* In-memory persistence adapter for testing and development.
+*
+* Backed by a simple Map — state is lost on process exit.
+* Supports both snapshot and journal strategies with proper
+* version checking (CAS on appends, monotonic on snapshots).
+*
+* @module
+*/
+const makeKey = (key) => `${key.entityType}/${key.entityId}`;
+const getOrCreate = (store, key) => {
+	let entry = store.get(key);
+	if (entry === void 0) {
+		entry = {
+			snapshot: void 0,
+			events: []
+		};
+		store.set(key, entry);
+	}
+	return entry;
+};
+/**
+* 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
+* ```
+*/
+const makeInMemoryPersistenceAdapter = Effect.gen(function* () {
+	const store = /* @__PURE__ */ new Map();
+	const storeRef = yield* Ref.make(store);
+	const adapter = {
+		saveSnapshot: (key, snapshot) => Effect.gen(function* () {
+			const entry = getOrCreate(yield* Ref.get(storeRef), makeKey(key));
+			if (entry.snapshot !== void 0 && snapshot.version < entry.snapshot.version) return yield* new VersionConflictError({
+				expected: snapshot.version,
+				actual: entry.snapshot.version
+			});
+			entry.snapshot = snapshot;
+		}),
+		loadSnapshot: (key) => Effect.gen(function* () {
+			const entry = (yield* Ref.get(storeRef)).get(makeKey(key));
+			return Option.fromNullishOr(entry?.snapshot);
+		}),
+		appendEvents: (key, events, expectedVersion) => Effect.gen(function* () {
+			const entry = getOrCreate(yield* Ref.get(storeRef), makeKey(key));
+			const lastEvent = entry.events[entry.events.length - 1];
+			const currentVersion = lastEvent !== void 0 ? lastEvent.version : 0;
+			if (currentVersion !== expectedVersion) return yield* new VersionConflictError({
+				expected: expectedVersion,
+				actual: currentVersion
+			});
+			for (const event of events) entry.events.push(event);
+		}),
+		loadEvents: (key, afterVersion) => Effect.gen(function* () {
+			const entry = (yield* Ref.get(storeRef)).get(makeKey(key));
+			if (entry === void 0) return [];
+			if (afterVersion === void 0) return entry.events;
+			return entry.events.filter((e) => e.version > afterVersion);
+		})
+	};
+	return {
+		adapter,
+		storeRef,
+		layer: Layer.succeed(PersistenceAdapter, adapter)
+	};
+});
+//#endregion
+export { makeInMemoryPersistenceAdapter };

package/dist/cluster/entity-actor-ref.d.ts

@@ -0,0 +1,56 @@
+import { ExtractReply, ReplyTypeBrand } from "../internal/brands.js";
+import { ActorStoppedError, NoReplyError } from "../errors.js";
+import { EntityRpcs } from "./to-entity.js";
+import { Effect, Stream } from "effect";
+import { RpcClient } from "effect/unstable/rpc";
+
+//#region src/cluster/entity-actor-ref.d.ts
+/**
+ * Typed client wrapper for remote entity machines.
+ *
+ * Unlike local `ActorRef`, this communicates over cluster RPCs.
+ * Only operations that make sense over the network are exposed.
+ *
+ * @example
+ * ```ts
+ * const ref = makeEntityActorRef(client, "order-123")
+ * yield* ref.send(OrderEvent.Ship({ trackingId: "abc" }))
+ * const state = yield* ref.snapshot
+ * yield* ref.waitFor((s) => s._tag === "Shipped")
+ * ```
+ */
+interface EntityActorRef<State extends {
+  readonly _tag: string;
+}, Event extends {
+  readonly _tag: string;
+}> {
+  readonly entityId: string;
+  /** Send event. Returns new state after processing. */
+  readonly send: (event: Event) => Effect.Effect<State>;
+  /** Send event and get typed domain reply (via Event.reply() schema). */
+  readonly ask: <E extends Event & ReplyTypeBrand<unknown>>(event: E) => Effect.Effect<ExtractReply<E>, NoReplyError>;
+  /** Get current state. */
+  readonly snapshot: Effect.Effect<State>;
+  /** Stream of state changes (via WatchState streaming RPC). */
+  readonly watch: Stream.Stream<State>;
+  /** Wait for a state matching the predicate. Snapshots first, then watches stream. */
+  readonly waitFor: (predicate: (state: State) => boolean) => Effect.Effect<State, ActorStoppedError>;
+}
+/**
+ * Create an EntityActorRef from a RPC client.
+ *
+ * @example
+ * ```ts
+ * const makeClient = yield* Entity.makeTestClient(entity, entityLayer)
+ * const client = yield* makeClient("order-123")
+ * const ref = makeEntityActorRef(client, "order-123")
+ * yield* ref.send(OrderEvent.Process)
+ * ```
+ */
+declare const makeEntityActorRef: <State extends {
+  readonly _tag: string;
+}, Event extends {
+  readonly _tag: string;
+}, Rpcs extends EntityRpcs<any, any>[number]>(client: RpcClient.RpcClient<Rpcs>, entityId: string) => EntityActorRef<State, Event>;
+//#endregion
+export { EntityActorRef, makeEntityActorRef };

package/dist/cluster/entity-actor-ref.js

@@ -0,0 +1,33 @@
+import { ActorStoppedError } from "../errors.js";
+import { Effect, Option, Stream } from "effect";
+//#region src/cluster/entity-actor-ref.ts
+/**
+* Create an EntityActorRef from a RPC client.
+*
+* @example
+* ```ts
+* const makeClient = yield* Entity.makeTestClient(entity, entityLayer)
+* const client = yield* makeClient("order-123")
+* const ref = makeEntityActorRef(client, "order-123")
+* yield* ref.send(OrderEvent.Process)
+* ```
+*/
+const makeEntityActorRef = (client, entityId) => {
+	const c = client;
+	return {
+		entityId,
+		send: (event) => c.Send({ event }),
+		ask: ((event) => c.Ask({ event })),
+		snapshot: c.GetState(),
+		watch: c.WatchState(),
+		waitFor: (predicate) => Effect.gen(function* () {
+			const current = yield* c.GetState();
+			if (predicate(current)) return current;
+			const result = yield* c.WatchState().pipe(Stream.filter(predicate), Stream.take(1), Stream.runHead);
+			if (Option.isSome(result)) return result.value;
+			return yield* new ActorStoppedError({ actorId: entityId });
+		})
+	};
+};
+//#endregion
+export { makeEntityActorRef };

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

@@ -1,7 +1,7 @@
-import { EffectsDef, GuardsDef } from "../slot.js";
 import { ProcessEventHooks } from "../internal/transition.js";
 import { Machine } from "../machine.js";
-import { Layer } from "effect";
+import { EntityPersistenceConfig } from "./persistence.js";
+import { Duration, Layer, Schedule } from "effect";
 import { Entity } from "effect/unstable/cluster";
 import { Rpc } from "effect/unstable/rpc";
 
@@ -13,77 +13,59 @@ interface EntityMachineOptions<S, E> {
   /**
    * Initialize state from entity ID.
    * Called once when entity is first activated.
-   *
-   * @example
-   * ```ts
-   * EntityMachine.layer(OrderEntity, orderMachine, {
-   *   initializeState: (entityId) => OrderState.Pending({ orderId: entityId }),
-   * })
-   * ```
    */
   readonly initializeState?: (entityId: string) => S;
   /**
    * Optional hooks for inspection/tracing.
-   * Called at specific points during event processing.
-   *
-   * @example
-   * ```ts
-   * EntityMachine.layer(OrderEntity, orderMachine, {
-   *   hooks: {
-   *     onTransition: (from, to, event) =>
-   *       Effect.log(`Transition: ${from._tag} -> ${to._tag}`),
-   *     onSpawnEffect: (state) =>
-   *       Effect.log(`Running spawn effects for ${state._tag}`),
-   *     onError: ({ phase, state }) =>
-   *       Effect.log(`Defect in ${phase} at ${state._tag}`),
-   *   },
-   * })
-   * ```
    */
   readonly hooks?: ProcessEventHooks<S, E>;
+  /**
+   * Maximum idle time before entity deactivation.
+   * Forwarded to Entity.toLayerQueue.
+   */
+  readonly maxIdleTime?: Duration.Input;
+  /**
+   * Mailbox capacity. Default: "unbounded".
+   * Forwarded to Entity.toLayerQueue.
+   */
+  readonly mailboxCapacity?: number | "unbounded";
+  /**
+   * Disable fatal defects (defects won't crash the entity activation).
+   * Forwarded to Entity.toLayerQueue.
+   */
+  readonly disableFatalDefects?: boolean;
+  /**
+   * Retry policy for defects (schedule for restarting after defect).
+   * Forwarded to Entity.toLayerQueue.
+   */
+  readonly defectRetryPolicy?: Schedule.Schedule<any, unknown>;
+  /**
+   * Persistence configuration. When set, requires PersistenceAdapter in R.
+   */
+  readonly persistence?: EntityPersistenceConfig;
 }
 /**
  * Create an Entity layer that wires a machine to handle RPC calls.
  *
- * The layer:
- * - Maintains state via Ref per entity instance
- * - Resolves transitions using the indexed lookup
- * - Evaluates guards in registration order
- * - Runs lifecycle effects (onEnter/spawn)
- * - Processes internal events from spawn effects
+ * Uses `Entity.toLayerQueue` for a single serialized mailbox per entity.
+ * The runtime kernel handles event processing, postpone, background effects,
+ * spawn effects, and final state detection.
  *
  * @example
  * ```ts
- * const OrderEntity = toEntity(orderMachine, {
- *   type: "Order",
- *   stateSchema: OrderState,
- *   eventSchema: OrderEvent,
- * })
+ * const OrderEntity = toEntity(orderMachine, { type: "Order" })
  *
  * const OrderEntityLayer = EntityMachine.layer(OrderEntity, orderMachine, {
  *   initializeState: (entityId) => OrderState.Pending({ orderId: entityId }),
  * })
- *
- * // Use in cluster
- * const program = Effect.gen(function* () {
- *   const client = yield* ShardingClient.client(OrderEntity)
- *   yield* client.Send("order-123", { event: OrderEvent.Ship({ trackingId: "abc" }) })
- * })
  * ```
  */
 declare const EntityMachine: {
-  /**
-   * Create a layer that wires a machine to an Entity.
-   *
-   * @param entity - Entity created via toEntity()
-   * @param machine - Machine with all effects provided
-   * @param options - Optional configuration (state initializer, inspection hooks)
-   */
   layer: <S extends {
     readonly _tag: string;
   }, E extends {
     readonly _tag: string;
-  }, R, GD extends GuardsDef, EFD extends EffectsDef, EntityType extends string, Rpcs extends Rpc.Any>(entity: Entity.Entity<EntityType, Rpcs>, machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, options?: EntityMachineOptions<S, E>) => Layer.Layer<never, never, R>;
+  }, R, EntityType extends string, Rpcs extends Rpc.Any>(entity: Entity.Entity<EntityType, Rpcs>, machine: Machine<S, E, R, any, any, any, any>, options?: EntityMachineOptions<S, E>) => Layer.Layer<never, never, R>;
 };
 //#endregion
 export { EntityMachine, EntityMachineOptions };