effect-machine 0.11.0 → 0.13.0

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

package/v3/dist/cluster/entity-machine.js

@@ -1,80 +1,164 @@
-import { processEventCore, runSpawnEffects } from "../internal/transition.js";
+import { stubSystem } from "../internal/utils.js";
+import { replay } from "../machine.js";
+import { createRuntime } from "../internal/runtime.js";
 import { ActorSystem } from "../actor.js";
-import { Effect, Option, Queue, Ref, Scope } from "effect";
+import { PersistenceAdapter } from "./persistence.js";
+import { Effect, Option, Ref } from "effect";
 import { Entity } from "@effect/cluster";
 //#region src/cluster/entity-machine.ts
 /**
 * EntityMachine adapter - wires a machine to a cluster Entity layer.
 *
+* Uses the runtime kernel for a single serialized event loop per entity.
+* All events (external RPCs + internal self.send) go through the
+* runtime kernel's single queue — no split-mailbox race.
+*
+* v3 uses `entity.toLayer` with handler objects (no `toLayerQueue`/`toLayerMailbox`).
+* Supports opt-in persistence (snapshot or journal strategy).
+*
 * @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
+* 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" }) })
-* })
 * ```
 */
 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 : stubSystem;
+		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 runtime = yield* createRuntime(machineWithState, system, {
+			actorId: entityId,
+			hooks: options?.hooks,
+			childIdPrefix: `${entityId}/`
 		});
-		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()));
+		if (persistCtx.adapter !== void 0) {
+			const { adapter: pAdapter, key } = persistCtx;
+			yield* Effect.addFinalizer(() => Effect.gen(function* () {
+				const state = yield* runtime.getState;
+				const version = yield* Ref.get(versionRef);
+				yield* pAdapter.saveSnapshot(key, {
+					state,
+					version,
+					timestamp: Date.now()
+				});
+			}).pipe(Effect.catchAll(() => Effect.void)));
+		}
+		const hasPersistence = persistCtx.adapter !== void 0;
+		const journalCtx = hasPersistence && (persistence?.strategy ?? "snapshot") === "journal" ? {
+			adapter: persistCtx.adapter,
+			key: persistCtx.key
+		} : void 0;
 		return entity.of({
-			Send: (envelope) => processEvent(machine, stateRef, envelope.payload.event, self, stateScopeRef, system, options?.hooks),
-			GetState: () => Ref.get(stateRef)
+			Send: (envelope) => Effect.gen(function* () {
+				yield* runtime.sendWait(envelope.payload.event);
+				if (journalCtx !== void 0) yield* persistEvent(journalCtx.adapter, journalCtx.key, versionRef, envelope.payload.event);
+				else if (hasPersistence) yield* Ref.update(versionRef, (v) => v + 1);
+				return yield* runtime.getState;
+			}),
+			Ask: (envelope) => Effect.gen(function* () {
+				const reply = yield* runtime.ask(envelope.payload.event);
+				if (journalCtx !== void 0) yield* persistEvent(journalCtx.adapter, journalCtx.key, versionRef, envelope.payload.event);
+				else if (hasPersistence) yield* Ref.update(versionRef, (v) => v + 1);
+				return reply;
+			}),
+			GetState: () => runtime.getState
 		});
 	});
-	return entity.toLayer(layer());
+	const clusterOptions = {};
+	if (options?.maxIdleTime !== void 0) clusterOptions.maxIdleTime = options.maxIdleTime;
+	if (options?.concurrency !== void 0) clusterOptions.concurrency = options.concurrency;
+	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.toLayer(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 from the last consistent snapshot.
+*/
+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: Date.now()
+	};
+	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/v3/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 { 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 };
+import { EntityRpcs, ToEntityOptions, toEntity } from "./to-entity.js";
+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/v3/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/v3/dist/cluster/persistence.d.ts

@@ -0,0 +1,48 @@
+import { PersistenceError, VersionConflictError } from "../errors.js";
+import { Context, Effect, Option, Schedule } 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.
+   * 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: Context.Tag<PersistenceAdapter, PersistenceAdapter>;
+//#endregion
+export { EntityPersistenceConfig, PersistedEvent, PersistenceAdapter, PersistenceKey, Snapshot };

package/v3/dist/cluster/persistence.js

@@ -0,0 +1,14 @@
+import { Context } from "effect";
+//#region src/cluster/persistence.ts
+/**
+* Entity persistence types and adapter interface (v3).
+*
+* Provides snapshot and event journal persistence for entity-machine
+* state across deactivation/reactivation cycles.
+*
+* @module
+*/
+/** Service tag for PersistenceAdapter — resolve from context for shared infra. */
+const PersistenceAdapter = Context.GenericTag("@effect-machine/cluster/PersistenceAdapter");
+//#endregion
+export { PersistenceAdapter };

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

@@ -15,12 +15,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.Schema.Any, EventSchema extends Schema.Schema.Any> = 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.
  *

package/v3/dist/cluster/to-entity.js

@@ -1,4 +1,5 @@
 import { MissingSchemaError } from "../errors.js";
+import { Schema } from "effect";
 import { Entity } from "@effect/cluster";
 import { Rpc } from "@effect/rpc";
 //#region src/cluster/to-entity.ts
@@ -42,10 +43,17 @@ const toEntity = (machine, options) => {
 	const stateSchema = machine.stateSchema;
 	const eventSchema = machine.eventSchema;
 	if (stateSchema === void 0 || eventSchema === void 0) throw new MissingSchemaError({ operation: "toEntity" });
-	return Entity.make(options.type, [Rpc.make("Send", {
-		payload: { event: eventSchema },
-		success: stateSchema
-	}), Rpc.make("GetState", { success: stateSchema })]);
+	return Entity.make(options.type, [
+		Rpc.make("Send", {
+			payload: { event: eventSchema },
+			success: stateSchema
+		}),
+		Rpc.make("Ask", {
+			payload: { event: eventSchema },
+			success: Schema.Unknown
+		}),
+		Rpc.make("GetState", { success: stateSchema })
+	]);
 };
 //#endregion
 export { toEntity };

package/v3/dist/errors.d.ts

@@ -8,13 +8,6 @@ declare const DuplicateActorError_base: Schema.TaggedErrorClass<DuplicateActorEr
 }>;
 /** Attempted to spawn/restore actor with ID already in use */
 declare class DuplicateActorError extends DuplicateActorError_base {}
-declare const UnprovidedSlotsError_base: Schema.TaggedErrorClass<UnprovidedSlotsError, "UnprovidedSlotsError", {
-  readonly _tag: Schema.tag<"UnprovidedSlotsError">;
-} & {
-  slots: Schema.Array$<typeof Schema.String>;
-}>;
-/** Machine has unprovided effect slots */
-declare class UnprovidedSlotsError extends UnprovidedSlotsError_base {}
 declare const MissingSchemaError_base: Schema.TaggedErrorClass<MissingSchemaError, "MissingSchemaError", {
   readonly _tag: Schema.tag<"MissingSchemaError">;
 } & {
@@ -24,6 +17,8 @@ declare const MissingSchemaError_base: Schema.TaggedErrorClass<MissingSchemaErro
 declare class MissingSchemaError extends MissingSchemaError_base {}
 declare const InvalidSchemaError_base: Schema.TaggedErrorClass<InvalidSchemaError, "InvalidSchemaError", {
   readonly _tag: Schema.tag<"InvalidSchemaError">;
+} & {
+  message: typeof Schema.String;
 }>;
 /** State/Event schema has no variants */
 declare class InvalidSchemaError extends InvalidSchemaError_base {}
@@ -72,5 +67,20 @@ declare const NoReplyError_base: Schema.TaggedErrorClass<NoReplyError, "NoReplyE
 }>;
 /** ask() was used but the transition handler did not call reply */
 declare class NoReplyError extends NoReplyError_base {}
+declare const PersistenceError_base: Schema.TaggedErrorClass<PersistenceError, "PersistenceError", {
+  readonly _tag: Schema.tag<"PersistenceError">;
+} & {
+  message: typeof Schema.String;
+}>;
+/** Persistence adapter operation failed */
+declare class PersistenceError extends PersistenceError_base {}
+declare const VersionConflictError_base: Schema.TaggedErrorClass<VersionConflictError, "VersionConflictError", {
+  readonly _tag: Schema.tag<"VersionConflictError">;
+} & {
+  expected: typeof Schema.Number;
+  actual: typeof Schema.Number;
+}>;
+/** Optimistic locking failure — stored version doesn't match expected */
+declare class VersionConflictError extends VersionConflictError_base {}
 //#endregion
-export { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError };
+export { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, SlotProvisionError, VersionConflictError };