effect-machine 0.11.0 → 0.13.0

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 };

package/dist/cluster/entity-machine.js

@@ -1,80 +1,206 @@
-import { processEventCore, runSpawnEffects } from "../internal/transition.js";
-import { ActorSystem } from "../actor.js";
-import { Effect, Option, Queue, Ref, Scope } from "effect";
+import { createRuntime } from "../internal/runtime.js";
+import { ActorSystem, makeSystem } from "../actor.js";
+import { replay } from "../machine.js";
+import { PersistenceAdapter } from "./persistence.js";
+import { Clock, Effect, Option, Queue, Ref, Stream, SubscriptionRef } from "effect";
 import { Entity } from "effect/unstable/cluster";
 //#region src/cluster/entity-machine.ts
 /**
 * EntityMachine adapter - wires a machine to a cluster Entity layer.
 *
+* Uses Entity.toLayerQueue for a single serialized mailbox per entity.
+* All events (external RPCs + internal self.send) go through the
+* runtime kernel's single queue — no split-mailbox race.
+*
+* Supports opt-in persistence (snapshot or journal strategy) for
+* state survival across entity deactivation/reactivation cycles.
+*
 * @module
 */
 /**
-* Process a single event through the machine using shared core.
-* Returns the new state after processing.
-*/
-const processEvent = Effect.fn("effect-machine.cluster.processEvent")(function* (machine, stateRef, event, self, stateScopeRef, system, hooks) {
-	const result = yield* processEventCore(machine, yield* Ref.get(stateRef), event, self, stateScopeRef, system, "*", hooks);
-	if (result.transitioned) yield* Ref.set(stateRef, result.newState);
-	return result.newState;
-});
-/**
 * 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" }) })
-* })
 * ```
 */
 const EntityMachine = { layer: (entity, machine, options) => {
-	const layer = Effect.fn("effect-machine.cluster.layer")(function* () {
+	const persistence = options?.persistence;
+	const build = Effect.gen(function* () {
 		const entityId = yield* Effect.serviceOption(Entity.CurrentAddress).pipe(Effect.map((opt) => opt._tag === "Some" ? opt.value.entityId : ""));
-		const initialState = options?.initializeState !== void 0 ? options.initializeState(entityId) : machine.initial;
 		const existingSystem = yield* Effect.serviceOption(ActorSystem);
-		if (Option.isNone(existingSystem)) return yield* Effect.die("EntityMachine requires ActorSystem in context");
-		const system = existingSystem.value;
-		const internalQueue = yield* Queue.unbounded();
-		const clusterSend = Effect.fn("effect-machine.cluster.self.send")(function* (event) {
-			yield* Queue.offer(internalQueue, event);
+		const system = Option.isSome(existingSystem) ? existingSystem.value : yield* makeSystem();
+		const persistCtx = yield* hydratePersistence(persistence, entity, entityId, machine, options?.initializeState);
+		const initialState = persistCtx.hydratedState ?? (options?.initializeState !== void 0 ? options.initializeState(entityId) : void 0);
+		const machineWithState = initialState !== void 0 ? Object.create(machine, { initial: {
+			value: initialState,
+			enumerable: true
+		} }) : machine;
+		const versionRef = yield* Ref.make(persistCtx.initialVersion);
+		const computedInitial = initialState ?? machine.initial;
+		const stateRef = yield* SubscriptionRef.make(computedInitial);
+		const stoppedRef = yield* Ref.make(false);
+		const eventQueue = yield* Queue.unbounded();
+		const runtime = yield* createRuntime(machineWithState, system, {
+			actorId: entityId,
+			hooks: options?.hooks,
+			childIdPrefix: `${entityId}/`,
+			cellResources: {
+				stateRef,
+				stoppedRef,
+				eventQueue
+			}
 		});
-		const self = {
-			send: clusterSend,
-			cast: clusterSend,
-			spawn: (childId, childMachine) => system.spawn(childId, childMachine).pipe(Effect.provideService(ActorSystem, system))
-		};
-		const stateRef = yield* Ref.make(initialState);
-		const stateScopeRef = { current: yield* Scope.make() };
-		yield* runSpawnEffects(machine, initialState, { _tag: "$init" }, self, stateScopeRef.current, system, entityId, options?.hooks?.onError);
-		const runInternalEvent = Effect.fn("effect-machine.cluster.internalEvent")(function* () {
-			yield* processEvent(machine, stateRef, yield* Queue.take(internalQueue), self, stateScopeRef, system, options?.hooks);
-		});
-		yield* Effect.forkScoped(Effect.forever(runInternalEvent()));
-		return entity.of({
-			Send: (envelope) => processEvent(machine, stateRef, envelope.payload.event, self, stateScopeRef, system, options?.hooks),
-			GetState: () => Ref.get(stateRef)
+		if (persistCtx.adapter !== void 0) {
+			const { adapter: pAdapter, key } = persistCtx;
+			const strategy = persistence?.strategy ?? "snapshot";
+			const schedule = persistence?.snapshotSchedule;
+			if (strategy === "snapshot") yield* SubscriptionRef.changes(runtime.stateRef).pipe(schedule !== void 0 ? Stream.schedule(schedule) : (s) => s, Stream.runForEach((state) => Effect.gen(function* () {
+				const version = yield* Ref.get(versionRef);
+				const now = yield* Clock.currentTimeMillis;
+				yield* pAdapter.saveSnapshot(key, {
+					state,
+					version,
+					timestamp: now
+				});
+			}).pipe(Effect.catch(() => Effect.void))), Effect.forkScoped);
+			yield* Effect.addFinalizer(() => Effect.gen(function* () {
+				const state = yield* SubscriptionRef.get(runtime.stateRef);
+				const version = yield* Ref.get(versionRef);
+				const now = yield* Clock.currentTimeMillis;
+				yield* pAdapter.saveSnapshot(key, {
+					state,
+					version,
+					timestamp: now
+				});
+			}).pipe(Effect.catch(() => Effect.void)));
+		}
+		return (mailbox, replier) => Effect.gen(function* () {
+			const hasPersistence = persistCtx.adapter !== void 0;
+			const journalCtx = hasPersistence && (persistence?.strategy ?? "snapshot") === "journal" ? {
+				adapter: persistCtx.adapter,
+				key: persistCtx.key
+			} : void 0;
+			while (true) {
+				const request = yield* Queue.take(mailbox);
+				switch (request.tag) {
+					case "Send": {
+						const event = request.payload.event;
+						yield* runtime.sendWait(event).pipe(Effect.orDie);
+						if (journalCtx !== void 0) yield* persistEvent(journalCtx.adapter, journalCtx.key, versionRef, event);
+						else if (hasPersistence) yield* Ref.update(versionRef, (v) => v + 1);
+						const state = yield* runtime.getState;
+						yield* replier.succeed(request, state);
+						break;
+					}
+					case "Ask": {
+						const event = request.payload.event;
+						const reply = yield* runtime.ask(event);
+						if (journalCtx !== void 0) yield* persistEvent(journalCtx.adapter, journalCtx.key, versionRef, event);
+						else if (hasPersistence) yield* Ref.update(versionRef, (v) => v + 1);
+						yield* replier.succeed(request, reply);
+						break;
+					}
+					case "GetState": {
+						const state = yield* runtime.getState;
+						yield* replier.succeed(request, state);
+						break;
+					}
+					case "WatchState":
+						yield* replier.succeed(request, SubscriptionRef.changes(runtime.stateRef));
+						break;
+					default: break;
+				}
+			}
 		});
 	});
-	return entity.toLayer(layer());
+	const clusterOptions = {};
+	if (options?.maxIdleTime !== void 0) clusterOptions.maxIdleTime = options.maxIdleTime;
+	if (options?.mailboxCapacity !== void 0) clusterOptions.mailboxCapacity = options.mailboxCapacity;
+	if (options?.disableFatalDefects !== void 0) clusterOptions.disableFatalDefects = options.disableFatalDefects;
+	if (options?.defectRetryPolicy !== void 0) clusterOptions.defectRetryPolicy = options.defectRetryPolicy;
+	return entity.toLayerQueue(build.pipe(Effect.orDie), Object.keys(clusterOptions).length > 0 ? clusterOptions : void 0);
 } };
+const noPersistence = {
+	adapter: void 0,
+	key: void 0,
+	hydratedState: void 0,
+	initialVersion: 0
+};
+/** Load snapshot/journal and compute hydrated state. */
+const hydratePersistence = (persistence, entityDef, entityId, machine, initializeState) => Effect.gen(function* () {
+	if (persistence === void 0) return noPersistence;
+	const adapter = yield* PersistenceAdapter;
+	const key = {
+		entityType: persistence.machineType ?? entityDef.type,
+		entityId
+	};
+	const maybeSnapshot = yield* adapter.loadSnapshot(key);
+	if ((persistence.strategy ?? "snapshot") === "journal") {
+		const baseState = Option.isSome(maybeSnapshot) ? maybeSnapshot.value.state : initializeState !== void 0 ? initializeState(entityId) : machine.initial;
+		const snapshotVersion = Option.isSome(maybeSnapshot) ? maybeSnapshot.value.version : 0;
+		const events = yield* adapter.loadEvents(key, snapshotVersion);
+		if (events.length > 0) {
+			const hydratedState = yield* replay(machine, events.map((e) => e.event), { from: baseState });
+			const lastEvent = events[events.length - 1];
+			return {
+				adapter,
+				key,
+				hydratedState,
+				initialVersion: lastEvent !== void 0 ? lastEvent.version : snapshotVersion
+			};
+		}
+		return {
+			adapter,
+			key,
+			hydratedState: Option.isSome(maybeSnapshot) ? maybeSnapshot.value.state : void 0,
+			initialVersion: snapshotVersion
+		};
+	}
+	if (Option.isSome(maybeSnapshot)) return {
+		adapter,
+		key,
+		hydratedState: maybeSnapshot.value.state,
+		initialVersion: maybeSnapshot.value.version
+	};
+	return {
+		adapter,
+		key,
+		hydratedState: void 0,
+		initialVersion: 0
+	};
+});
+/**
+* Append a single event to the journal, incrementing version.
+*
+* On failure: defects the entity activation. The cluster's defectRetryPolicy
+* restarts the entity, which rehydrates from the last consistent snapshot +
+* whatever events made it to the journal. This is correct because the in-memory
+* state has already advanced — we can't un-ring that bell — so the activation
+* is now unreliable and must restart.
+*/
+const persistEvent = (adapter, key, versionRef, event) => Effect.gen(function* () {
+	const expectedVersion = yield* Ref.get(versionRef);
+	const newVersion = expectedVersion + 1;
+	const persisted = {
+		event,
+		version: newVersion,
+		timestamp: yield* Clock.currentTimeMillis
+	};
+	yield* adapter.appendEvents(key, [persisted], expectedVersion);
+	yield* Ref.set(versionRef, newVersion);
+}).pipe(Effect.tapError((error) => Effect.logWarning("Journal append failed, defecting entity", {
+	key,
+	error
+})), Effect.orDie);
 //#endregion
 export { EntityMachine };

package/dist/cluster/index.d.ts

@@ -1,3 +1,6 @@
+import { EntityPersistenceConfig, PersistedEvent, PersistenceAdapter, PersistenceKey, Snapshot } from "./persistence.js";
+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";
-import { ToEntityOptions, toEntity } from "./to-entity.js";
-export { EntityMachine, type EntityMachineOptions, type ToEntityOptions, toEntity };
+export { type EntityActorRef, EntityMachine, type EntityMachineOptions, type EntityPersistenceConfig, type EntityRpcs, type PersistedEvent, PersistenceAdapter, type PersistenceAdapter as PersistenceAdapterInterface, type PersistenceKey, type Snapshot, type ToEntityOptions, makeEntityActorRef, makeInMemoryPersistenceAdapter, toEntity };

package/dist/cluster/index.js

@@ -1,3 +1,6 @@
+import { makeEntityActorRef } from "./entity-actor-ref.js";
+import { PersistenceAdapter } from "./persistence.js";
 import { EntityMachine } from "./entity-machine.js";
 import { toEntity } from "./to-entity.js";
-export { EntityMachine, toEntity };
+import { makeInMemoryPersistenceAdapter } from "./adapters/in-memory.js";
+export { EntityMachine, PersistenceAdapter, makeEntityActorRef, makeInMemoryPersistenceAdapter, toEntity };

package/dist/cluster/persistence.d.ts

@@ -0,0 +1,49 @@
+import { PersistenceError, VersionConflictError } from "../errors.js";
+import { Effect, Option, Schedule, ServiceMap } from "effect";
+
+//#region src/cluster/persistence.d.ts
+/** Namespaced key preventing cross-type collisions (e.g. Order/123 vs User/123). */
+interface PersistenceKey {
+  readonly entityType: string;
+  readonly entityId: string;
+}
+/** Stored state snapshot with version and timestamp. */
+interface Snapshot<S> {
+  readonly state: S;
+  readonly version: number;
+  readonly timestamp: number;
+}
+/** Stored event with version and timestamp. */
+interface PersistedEvent<E> {
+  readonly event: E;
+  readonly version: number;
+  readonly timestamp: number;
+}
+/** Persistence configuration for EntityMachineOptions. */
+interface EntityPersistenceConfig {
+  /** Persistence strategy. Default: "snapshot". */
+  readonly strategy?: "snapshot" | "journal";
+  /**
+   * Schedule controlling snapshot frequency.
+   * Only applies to snapshot strategy (or journal strategy's periodic snapshots).
+   * Default: save on every state change.
+   */
+  readonly snapshotSchedule?: Schedule.Schedule<any, any>;
+  /** Override entityType in the persistence key (defaults to Entity.type). */
+  readonly machineType?: string;
+}
+/** Storage backend for entity state persistence. */
+interface PersistenceAdapter {
+  /** Save a state snapshot. Fails with VersionConflictError if version is stale. */
+  readonly saveSnapshot: (key: PersistenceKey, snapshot: Snapshot<unknown>) => Effect.Effect<void, PersistenceError | VersionConflictError>;
+  /** Load the latest snapshot, or None if no snapshot exists. */
+  readonly loadSnapshot: (key: PersistenceKey) => Effect.Effect<Option.Option<Snapshot<unknown>>, PersistenceError>;
+  /** Append events to the journal. Fails with VersionConflictError if expectedVersion doesn't match. */
+  readonly appendEvents: (key: PersistenceKey, events: ReadonlyArray<PersistedEvent<unknown>>, expectedVersion: number) => Effect.Effect<void, PersistenceError | VersionConflictError>;
+  /** Load events from the journal, optionally after a given version. */
+  readonly loadEvents: (key: PersistenceKey, afterVersion?: number) => Effect.Effect<ReadonlyArray<PersistedEvent<unknown>>, PersistenceError>;
+}
+/** Service tag for PersistenceAdapter — resolve from context for shared infra. */
+declare const PersistenceAdapter: ServiceMap.Service<PersistenceAdapter, PersistenceAdapter>;
+//#endregion
+export { EntityPersistenceConfig, PersistedEvent, PersistenceAdapter, PersistenceKey, Snapshot };

package/dist/cluster/persistence.js

@@ -0,0 +1,18 @@
+import { ServiceMap } from "effect";
+//#region src/cluster/persistence.ts
+/**
+* Entity persistence types and adapter interface.
+*
+* Provides snapshot and event journal persistence for entity-machine
+* state across deactivation/reactivation cycles.
+*
+* Two strategies:
+* - **snapshot**: Save full state periodically. Simple, fast.
+* - **journal**: Append events inline, replay on reactivation. Full audit trail.
+*
+* @module
+*/
+/** Service tag for PersistenceAdapter — resolve from context for shared infra. */
+const PersistenceAdapter = ServiceMap.Service("@effect-machine/cluster/PersistenceAdapter");
+//#endregion
+export { PersistenceAdapter };

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

@@ -2,6 +2,7 @@ import { Machine } from "../machine.js";
 import { Schema } from "effect";
 import { Entity } from "effect/unstable/cluster";
 import { Rpc } from "effect/unstable/rpc";
+import * as _$effect_unstable_rpc_RpcSchema0 from "effect/unstable/rpc/RpcSchema";
 
 //#region src/cluster/to-entity.d.ts
 /**
@@ -16,12 +17,15 @@ interface ToEntityOptions {
 /**
  * Default RPC protocol for entity machines.
  *
- * - `Send` - Send event to machine, returns new state
+ * - `Send` - Send event to machine (fire-and-forget), returns new state
+ * - `Ask` - Send event and get domain reply (typed via Event.reply() schemas)
  * - `GetState` - Get current state
  */
 type EntityRpcs<StateSchema extends Schema.Top, EventSchema extends Schema.Top> = readonly [Rpc.Rpc<"Send", Schema.Struct<{
   readonly event: EventSchema;
-}>, StateSchema, typeof Schema.Never, never>, Rpc.Rpc<"GetState", typeof Schema.Void, StateSchema, typeof Schema.Never, never>];
+}>, StateSchema, typeof Schema.Never, never>, Rpc.Rpc<"Ask", Schema.Struct<{
+  readonly event: EventSchema;
+}>, typeof Schema.Unknown, typeof Schema.Never, never>, Rpc.Rpc<"GetState", typeof Schema.Void, StateSchema, typeof Schema.Never, never>];
 /**
  * Generate an Entity definition from a machine.
  *
@@ -59,6 +63,8 @@ declare const toEntity: <S extends {
   readonly _tag: string;
 }, R>(machine: Machine<S, E, R, any, any, any, any>, options: ToEntityOptions) => Entity.Entity<string, Rpc.Rpc<"Send", Schema.Struct<{
   event: Schema.Schema<E>;
-}>, Schema.Schema<S>, Schema.Never, never, never> | Rpc.Rpc<"GetState", Schema.Void, Schema.Schema<S>, Schema.Never, never, never>>;
+}>, Schema.Schema<S>, Schema.Never, never, never> | Rpc.Rpc<"Ask", Schema.Struct<{
+  event: Schema.Schema<E>;
+}>, Schema.Unknown, Schema.Never, never, never> | Rpc.Rpc<"GetState", Schema.Void, Schema.Schema<S>, Schema.Never, never, never> | Rpc.Rpc<"WatchState", Schema.Void, _$effect_unstable_rpc_RpcSchema0.Stream<Schema.Schema<S>, Schema.Never>, Schema.Never, never, never>>;
 //#endregion
 export { EntityRpcs, ToEntityOptions, toEntity };