effect-machine 0.11.0 → 0.12.0

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 { BuiltMachine, replay } from "../machine.js";
 import { ActorSystem } from "../actor.js";
-import { Effect, Option, Queue, Ref, Scope } from "effect";
+import { createRuntime } from "../internal/runtime.js";
+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
 		});
-		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 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 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

@@ -72,5 +72,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, UnprovidedSlotsError, VersionConflictError };

package/v3/dist/errors.js

@@ -39,5 +39,12 @@ var NoReplyError = class extends Schema.TaggedError()("NoReplyError", {
 	actorId: Schema.String,
 	eventTag: Schema.String
 }) {};
+/** Persistence adapter operation failed */
+var PersistenceError = class extends Schema.TaggedError()("PersistenceError", { message: Schema.String }) {};
+/** Optimistic locking failure — stored version doesn't match expected */
+var VersionConflictError = class extends Schema.TaggedError()("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/v3/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 { 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, 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/v3/dist/internal/brands.d.ts

@@ -29,6 +29,20 @@ 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().
+ */
+declare const ReplyTypeId: unique symbol;
+type ReplyTypeId = typeof 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).
@@ -37,4 +51,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/v3/dist/internal/runtime.d.ts

@@ -0,0 +1,65 @@
+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 } 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>;
+} | {
+  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) */
+  readonly sendWait: (event: E) => Effect.Effect<void>;
+  /** Enqueue an ask event, returns the reply value */
+  readonly ask: (event: E) => Effect.Effect<unknown, NoReplyError>;
+  /** Get current state */
+  readonly getState: Effect.Effect<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 };