effect-machine 0.10.0 → 0.12.0

package/v3/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, Context, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Runtime, Scope, Stream, SubscriptionRef } from "effect";
+import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Runtime, Schema, Scope, Stream, SubscriptionRef } from "effect";
 //#region src/actor.ts
 /**
 * Actor system: spawning, lifecycle, and event processing.
@@ -31,7 +28,7 @@ const notifyListeners = (listeners, state) => {
 /**
 * Build core ActorRef methods shared between regular and persistent actors.
 */
-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, {
@@ -121,6 +118,7 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 		matches,
 		can,
 		changes: stateRef.changes,
+		transitions: transitionsPubSub !== void 0 ? Stream.fromPubSub(transitionsPubSub) : Stream.empty,
 		waitFor,
 		awaitFinal,
 		sendAndWait,
@@ -151,7 +149,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;
@@ -186,20 +185,20 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 			return child;
 		})
 	};
-	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
@@ -208,7 +207,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	for (const bg of machine.backgroundEffects) {
 		const fiber = yield* Effect.forkDaemon(bg.handler({
 			actorId: id,
-			state: machine.initial,
+			state: initial,
 			event: initEvent,
 			self,
 			effects: effectSlots,
@@ -217,14 +216,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);
@@ -232,7 +231,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.forkDaemon(eventLoop(machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, id, inspectorValue, system, pendingReplies));
+	const transitionsPubSub = yield* PubSub.unbounded();
+	const loopFiber = yield* Effect.forkDaemon(eventLoop(machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, id, inspectorValue, system, pendingReplies, transitionsPubSub));
 	return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, Effect.gen(function* () {
 		const finalState = yield* SubscriptionRef.get(stateRef);
 		yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
@@ -247,7 +247,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(() => {
@@ -260,7 +260,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) {
 	const postponed = [];
 	const hasPostponeRules = machine.postponeRules.length > 0;
 	const processQueued = Effect.fn("effect-machine.actor.processQueued")(function* (queued) {
@@ -276,6 +276,7 @@ const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine
 					lifecycleRan: false,
 					isFinal: false,
 					hasReply: false,
+					deferReply: false,
 					reply: void 0,
 					postponed: true
 				};
@@ -296,13 +297,29 @@ 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);
-				else yield* Deferred.fail(queued.reply, new NoReplyError({
+				if (result.hasReply) {
+					const replySchema = machine._replySchemas?.get(event._tag);
+					if (replySchema !== void 0) {
+						let decoded;
+						try {
+							decoded = Schema.decodeUnknownSync(replySchema)(result.reply);
+						} catch (decodeError) {
+							yield* Deferred.die(queued.reply, decodeError);
+							return yield* Effect.die(decodeError);
+						}
+						yield* Deferred.succeed(queued.reply, decoded);
+					} else yield* Deferred.succeed(queued.reply, result.reply);
+				} else yield* Deferred.fail(queued.reply, new NoReplyError({
 					actorId,
 					eventTag: event._tag
 				}));
 				break;
 		}
+		if (result.transitioned) yield* PubSub.publish(transitionsPubSub, {
+			fromState: result.previousState,
+			toState: result.newState,
+			event
+		});
 		return {
 			shouldStop,
 			stateChanged: result.lifecycleRan
@@ -318,15 +335,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;
 			}
 		}
 	}
@@ -482,25 +505,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));
 	});
@@ -517,55 +522,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.either(restore(id, persistentMachine));
-			if (result._tag === "Left") failed.push({
-				id,
-				error: result.left
-			});
-			else if (Option.isSome(result.right)) restored.push(result.right.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),
@@ -581,10 +539,7 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 			return () => {
 				eventListeners.delete(fn);
 			};
-		},
-		listPersisted,
-		restoreMany,
-		restoreAll
+		}
 	});
 });
 /**

package/v3/dist/cluster/adapters/in-memory.d.ts

@@ -0,0 +1,15 @@
+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>>;
+}
+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/v3/dist/cluster/adapters/in-memory.js

@@ -0,0 +1,62 @@
+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 (v3).
+*
+* @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;
+};
+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.fromNullable(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/v3/dist/cluster/entity-actor-ref.d.ts

@@ -0,0 +1,49 @@
+import { ExtractReply, ReplyTypeBrand } from "../internal/brands.js";
+import { NoReplyError } from "../errors.js";
+import { Effect } 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 = yield* EntityActorRef.make(OrderEntity, OrderEntityLayer, "order-123")
+ * yield* ref.send(OrderEvent.Ship({ trackingId: "abc" }))
+ * const state = yield* ref.snapshot
+ * ```
+ */
+interface EntityActorRef<State extends {
+  readonly _tag: string;
+}, Event extends {
+  readonly _tag: string;
+}> {
+  readonly entityId: string;
+  /** Send event (fire-and-forget). 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>;
+}
+/**
+ * Create an EntityActorRef from a test client factory and entity ID.
+ *
+ * @example
+ * ```ts
+ * const makeClient = yield* Entity.makeTestClient(entity, entityLayer)
+ * const ref = yield* makeEntityActorRef(makeClient, "order-123")
+ * yield* ref.send(OrderEvent.Process)
+ * ```
+ */
+declare const makeEntityActorRef: <State extends {
+  readonly _tag: string;
+}, Event extends {
+  readonly _tag: string;
+}>(client: RpcClient.RpcClient<any>, entityId: string) => EntityActorRef<State, Event>;
+//#endregion
+export { EntityActorRef, makeEntityActorRef };

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

@@ -0,0 +1,19 @@
+//#region src/cluster/entity-actor-ref.ts
+/**
+* Create an EntityActorRef from a test client factory and entity ID.
+*
+* @example
+* ```ts
+* const makeClient = yield* Entity.makeTestClient(entity, entityLayer)
+* const ref = yield* makeEntityActorRef(makeClient, "order-123")
+* yield* ref.send(OrderEvent.Process)
+* ```
+*/
+const makeEntityActorRef = (client, entityId) => ({
+	entityId,
+	send: (event) => client.Send({ event }),
+	ask: ((event) => client.Ask({ event })),
+	snapshot: client.GetState()
+});
+//#endregion
+export { makeEntityActorRef };

package/v3/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/cluster";
 import { Rpc } from "@effect/rpc";
 
@@ -13,77 +13,62 @@ 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.toLayer.
+   */
+  readonly maxIdleTime?: Duration.DurationInput;
+  /**
+   * Concurrency for handler execution.
+   * Forwarded to Entity.toLayer.
+   */
+  readonly concurrency?: number | "unbounded";
+  /**
+   * Mailbox capacity. Default: "unbounded".
+   * Forwarded to Entity.toLayer.
+   */
+  readonly mailboxCapacity?: number | "unbounded";
+  /**
+   * Disable fatal defects (defects won't crash the entity activation).
+   * Forwarded to Entity.toLayer.
+   */
+  readonly disableFatalDefects?: boolean;
+  /**
+   * Retry policy for defects (schedule for restarting after defect).
+   * Forwarded to Entity.toLayer.
+   */
+  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
+ * v3: Uses `Entity.toLayer` with handler objects backed by the runtime kernel.
  *
  * @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 };