effect-machine 0.11.0 → 0.12.0

package/dist/cluster/entity-machine.js

@@ -1,80 +1,195 @@
-import { processEventCore, runSpawnEffects } from "../internal/transition.js";
-import { ActorSystem } from "../actor.js";
-import { Effect, Option, Queue, Ref, Scope } from "effect";
+import { BuiltMachine, replay } from "../machine.js";
+import { ActorSystem, makeSystem } from "../actor.js";
+import { createRuntime } from "../internal/runtime.js";
+import { PersistenceAdapter } from "./persistence.js";
+import { 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 runtime = yield* createRuntime(machineWithState, system, {
+			actorId: entityId,
+			hooks: options?.hooks
 		});
-		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);
+				yield* pAdapter.saveSnapshot(key, {
+					state,
+					version,
+					timestamp: Date.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);
+				yield* pAdapter.saveSnapshot(key, {
+					state,
+					version,
+					timestamp: Date.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 eventValues = events.map((e) => e.event);
+			const hydratedState = yield* replay(new BuiltMachine(machine), eventValues, { 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: 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/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 };

package/dist/cluster/to-entity.js

@@ -1,4 +1,5 @@
 import { MissingSchemaError } from "../errors.js";
+import { Schema } from "effect";
 import { Entity } from "effect/unstable/cluster";
 import { Rpc } from "effect/unstable/rpc";
 //#region src/cluster/to-entity.ts
@@ -42,10 +43,21 @@ 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 }),
+		Rpc.make("WatchState", {
+			success: stateSchema,
+			stream: true
+		})
+	]);
 };
 //#endregion
 export { toEntity };

package/dist/errors.d.ts

@@ -53,5 +53,16 @@ declare const NoReplyError_base: Schema.ErrorClass<NoReplyError, Schema.TaggedSt
 }>, effect_Cause0.YieldableError>;
 /** ask() was used but the transition handler did not call reply */
 declare class NoReplyError extends NoReplyError_base {}
+declare const PersistenceError_base: Schema.ErrorClass<PersistenceError, Schema.TaggedStruct<"PersistenceError", {
+  readonly message: Schema.String;
+}>, effect_Cause0.YieldableError>;
+/** Persistence adapter operation failed */
+declare class PersistenceError extends PersistenceError_base {}
+declare const VersionConflictError_base: Schema.ErrorClass<VersionConflictError, Schema.TaggedStruct<"VersionConflictError", {
+  readonly expected: Schema.Number;
+  readonly actual: Schema.Number;
+}>, effect_Cause0.YieldableError>;
+/** 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, UnprovidedSlotsError, VersionConflictError };

package/dist/errors.js

@@ -39,5 +39,12 @@ var NoReplyError = class extends Schema.TaggedErrorClass()("NoReplyError", {
 	actorId: Schema.String,
 	eventTag: Schema.String
 }) {};
+/** Persistence adapter operation failed */
+var PersistenceError = class extends Schema.TaggedErrorClass()("PersistenceError", { message: Schema.String }) {};
+/** Optimistic locking failure — stored version doesn't match expected */
+var VersionConflictError = class extends Schema.TaggedErrorClass()("VersionConflictError", {
+	expected: Schema.Number,
+	actual: Schema.Number
+}) {};
 //#endregion
-export { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError };
+export { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError, VersionConflictError };

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import { EffectHandlers, EffectSlot, EffectSlots, EffectsDef, EffectsSchema, GuardHandlers, GuardSlot, GuardSlots, GuardsDef, GuardsSchema, MachineContext, Slot } from "./slot.js";
-import { Event, MachineEventSchema, MachineStateSchema, State } from "./schema.js";
+import { DeferReplyResult, ReplyResult } from "./internal/utils.js";
+import { Event, MachineEventSchema, MachineStateSchema, ReplyFields, State } from "./schema.js";
 import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.js";
 import { ProcessEventResult } from "./internal/transition.js";
 import { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, SpawnEffect, StateHandlerContext, TaskOptions, Transition, machine_d_exports } from "./machine.js";
 import { ActorRef, ActorRefSync, ActorSystem, Default, SystemEvent, SystemEventListener, TransitionInfo } from "./actor.js";
 import { SimulationResult, TestHarness, TestHarnessOptions, assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
 import { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, InspectorHandler, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
-export { type ActorRef, type ActorRefSync, ActorStoppedError, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type BuiltMachine, DuplicateActorError, type EffectEvent, type EffectSlots, type EffectsDef, type EffectsSchema, type ErrorEvent, Event, type EventReceivedEvent, type GuardHandlers, type GuardSlot, type GuardSlots, type GuardsDef, type GuardsSchema, type HandlerContext, type InspectionEvent, type Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, machine_d_exports as Machine, type MachineContext, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, MissingSchemaError, NoReplyError, type ProcessEventResult, type ProvideHandlers, ProvisionValidationError, type SimulationResult, Slot, type EffectHandlers as SlotEffectHandlers, type EffectSlot as SlotEffectSlot, SlotProvisionError, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, type SystemEvent, type SystemEventListener, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TracingInspectorOptions, type Transition, type TransitionEvent, type TransitionInfo, UnprovidedSlotsError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };
+export { type ActorRef, type ActorRefSync, ActorStoppedError, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type BuiltMachine, type DeferReplyResult, DuplicateActorError, type EffectEvent, type EffectSlots, type EffectsDef, type EffectsSchema, type ErrorEvent, Event, type EventReceivedEvent, type GuardHandlers, type GuardSlot, type GuardSlots, type GuardsDef, type GuardsSchema, type HandlerContext, type InspectionEvent, type Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, machine_d_exports as Machine, type MachineContext, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, MissingSchemaError, NoReplyError, type ProcessEventResult, type ProvideHandlers, ProvisionValidationError, type ReplyFields, type ReplyResult, type SimulationResult, Slot, type EffectHandlers as SlotEffectHandlers, type EffectSlot as SlotEffectSlot, SlotProvisionError, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, type SystemEvent, type SystemEventListener, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TracingInspectorOptions, type Transition, type TransitionEvent, type TransitionInfo, UnprovidedSlotsError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };

package/dist/internal/brands.d.ts

@@ -26,6 +26,19 @@ type FullStateBrand<D extends Record<string, unknown>> = StateBrand & SchemaIdBr
  * Full event brand: combines base event brand with schema-specific brand
  */
 type FullEventBrand<D extends Record<string, unknown>> = EventBrand & SchemaIdBrand<D>;
+/**
+ * Brand that carries the reply type for an event variant.
+ * Present only on events defined with Event.reply().
+ */
+type ReplyTypeId = "effect-machine/ReplyTypeId";
+interface ReplyTypeBrand<R> extends Brand.Brand<ReplyTypeId> {
+  readonly _ReplyType: R;
+}
+/**
+ * Extract the reply type from a branded event value.
+ * Returns `never` if the event has no reply schema.
+ */
+type ExtractReply<E> = E extends ReplyTypeBrand<infer R> ? R : never;
 /**
  * Value or constructor for a tagged type.
  * Accepts both plain values (empty structs) and constructor functions (non-empty structs).
@@ -34,4 +47,4 @@ type TaggedOrConstructor<T extends {
   readonly _tag: string;
 }> = T | ((...args: never[]) => T);
 //#endregion
-export { BrandedEvent, BrandedState, EventBrand, EventTypeId, FullEventBrand, FullStateBrand, SchemaIdBrand, StateBrand, StateTypeId, TaggedOrConstructor };
+export { BrandedEvent, BrandedState, EventBrand, EventTypeId, ExtractReply, FullEventBrand, FullStateBrand, ReplyTypeBrand, ReplyTypeId, SchemaIdBrand, StateBrand, StateTypeId, TaggedOrConstructor };

package/dist/internal/runtime.d.ts

@@ -0,0 +1,67 @@
+import { EffectsDef, GuardsDef, MachineContext } from "../slot.js";
+import { NoReplyError } from "../errors.js";
+import { ProcessEventHooks } from "./transition.js";
+import { Machine, MachineRef } from "../machine.js";
+import { ActorSystem } from "../actor.js";
+import { Deferred, Effect, Queue, Scope, SubscriptionRef } from "effect";
+
+//#region src/internal/runtime.d.ts
+/** @internal */
+type RuntimeQueuedEvent<E> = {
+  readonly _tag: "send";
+  readonly event: E;
+} | {
+  readonly _tag: "sendWait";
+  readonly event: E;
+  readonly done: Deferred.Deferred<void, unknown>;
+} | {
+  readonly _tag: "ask";
+  readonly event: E;
+  readonly reply: Deferred.Deferred<unknown, NoReplyError>;
+};
+/** @internal */
+interface RuntimeHandle<S, E> {
+  /** Enqueue a fire-and-forget event */
+  readonly send: (event: E) => Effect.Effect<void>;
+  /** Enqueue event and wait for processing to complete (for RPC Send). Fails on defect. */
+  readonly sendWait: (event: E) => Effect.Effect<void, unknown>;
+  /** Enqueue an ask event, returns the reply value */
+  readonly ask: (event: E) => Effect.Effect<unknown, NoReplyError>;
+  /** Get current state */
+  readonly getState: Effect.Effect<S>;
+  /** SubscriptionRef for state observation (WatchState streaming) */
+  readonly stateRef: SubscriptionRef.SubscriptionRef<S>;
+  /** Whether the runtime has stopped (final state reached) */
+  readonly isStopped: Effect.Effect<boolean>;
+  /** Stop the runtime (interrupt event loop, clean up) */
+  readonly stop: Effect.Effect<void>;
+}
+/** @internal */
+interface RuntimeConfig<S, E> {
+  readonly actorId: string;
+  readonly hooks?: ProcessEventHooks<S, E>;
+  /**
+   * Custom queue factory. Default: `Queue.unbounded()`.
+   * Use `Queue.sliding(n)` or `Queue.dropping(n)` for bounded queues.
+   */
+  readonly queueFactory?: Effect.Effect<Queue.Queue<RuntimeQueuedEvent<E>>>;
+}
+/**
+ * Create a runtime for a machine. Returns a handle for sending events
+ * and querying state. The runtime owns:
+ * - Single event queue (all events serialized)
+ * - Event loop fiber
+ * - Postpone buffer
+ * - Background effects
+ * - State scope (spawn effects)
+ * - Final state detection
+ *
+ * @internal
+ */
+declare const createRuntime: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, any, any, GD, EFD>, system: ActorSystem, config: RuntimeConfig<S, E>) => Effect.Effect<RuntimeHandle<S, E>, never, Scope.Scope | Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
+//#endregion
+export { RuntimeConfig, RuntimeHandle, RuntimeQueuedEvent, createRuntime };