effect-machine 0.11.0 → 0.13.0

package/v3/dist/errors.js

@@ -12,12 +12,10 @@ import { Schema } from "effect";
 */
 /** Attempted to spawn/restore actor with ID already in use */
 var DuplicateActorError = class extends Schema.TaggedError()("DuplicateActorError", { actorId: Schema.String }) {};
-/** Machine has unprovided effect slots */
-var UnprovidedSlotsError = class extends Schema.TaggedError()("UnprovidedSlotsError", { slots: Schema.Array(Schema.String) }) {};
 /** Operation requires schemas attached to machine */
 var MissingSchemaError = class extends Schema.TaggedError()("MissingSchemaError", { operation: Schema.String }) {};
 /** State/Event schema has no variants */
-var InvalidSchemaError = class extends Schema.TaggedError()("InvalidSchemaError", {}) {};
+var InvalidSchemaError = class extends Schema.TaggedError()("InvalidSchemaError", { message: Schema.String }) {};
 /** $match called with missing handler for tag */
 var MissingMatchHandlerError = class extends Schema.TaggedError()("MissingMatchHandlerError", { tag: Schema.String }) {};
 /** Slot handler not found at runtime (internal error) */
@@ -39,5 +37,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, VersionConflictError };

package/v3/dist/index.d.ts

@@ -1,9 +1,11 @@
+import { ActorExit, CellPhase, DefectPhase, Supervision } from "./supervision.js";
+import { ReplyResult } from "./internal/utils.js";
+import { Event, MachineEventSchema, MachineStateSchema, ReplyFields, State } from "./schema.js";
+import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, SlotProvisionError, VersionConflictError } from "./errors.js";
 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 { 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 { BackgroundEffect, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, SlotContext, SpawnEffect, StateHandlerContext, TaskOptions, TimeoutConfig, 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 { ActorExit, type ActorRef, type ActorRefSync, ActorStoppedError, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type CellPhase, type DefectPhase, 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, PersistenceError, type ProcessEventResult, type ProvideHandlers, ProvisionValidationError, type ReplyFields, type ReplyResult, type SimulationResult, Slot, type SlotContext, type EffectHandlers as SlotEffectHandlers, type EffectSlot as SlotEffectSlot, SlotProvisionError, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, Supervision, type SystemEvent, type SystemEventListener, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TimeoutConfig, type TracingInspectorOptions, type Transition, type TransitionEvent, type TransitionInfo, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };

package/v3/dist/index.js

@@ -1,8 +1,9 @@
+import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, SlotProvisionError, VersionConflictError } from "./errors.js";
 import { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
-import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.js";
 import { Slot } from "./slot.js";
 import { machine_exports } from "./machine.js";
+import { ActorExit, Supervision } from "./supervision.js";
 import { ActorSystem, Default } from "./actor.js";
 import { Event, State } from "./schema.js";
 import { assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
-export { ActorStoppedError, Default as ActorSystemDefault, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, MissingSchemaError, NoReplyError, ProvisionValidationError, Slot, SlotProvisionError, State, UnprovidedSlotsError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };
+export { ActorExit, ActorStoppedError, Default as ActorSystemDefault, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, Slot, SlotProvisionError, State, Supervision, VersionConflictError, 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,142 @@
+import { ActorExit } from "../supervision.js";
+import { NoReplyError } from "../errors.js";
+import { EffectsDef, GuardsDef, MachineContext } from "../slot.js";
+import { ProcessEventHooks, ProcessEventResult } from "./transition.js";
+import { Machine, MachineRef } from "../machine.js";
+import { ActorSystem } from "../actor.js";
+import { Deferred, Effect, Queue, Ref, 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>;
+} | {
+  readonly _tag: "call";
+  readonly event: E;
+  readonly reply: Deferred.Deferred<ProcessEventResult<{
+    readonly _tag: string;
+  }>, unknown>;
+} | {
+  readonly _tag: "ask";
+  readonly event: E;
+  readonly reply: Deferred.Deferred<unknown, NoReplyError>;
+} | {
+  readonly _tag: "drain";
+  readonly done: Deferred.Deferred<void, never>;
+};
+/**
+ * Resources owned by the actor cell (stable across generations).
+ * When provided, createRuntime uses these instead of allocating its own.
+ * @internal
+ */
+interface RuntimeCellResources<S, E> {
+  readonly stateRef: SubscriptionRef.SubscriptionRef<S>;
+  readonly eventQueue: Queue.Queue<RuntimeQueuedEvent<E>>;
+  readonly stoppedRef: Ref.Ref<boolean>;
+}
+/** @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>;
+  /** SubscriptionRef for state observation */
+  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 — raw event queue for direct enqueue (actor.ts uses this for pendingReplies tracking) */
+  readonly _queue: Queue.Queue<RuntimeQueuedEvent<E>>;
+  /** @internal — stopped ref for direct access */
+  readonly _stoppedRef: Ref.Ref<boolean>;
+  /**
+   * Exit deferred — set exactly once with the exit reason when the runtime stops.
+   * Final state → ActorExit.Final, explicit stop → ActorExit.Stopped, defect → ActorExit.Defect.
+   */
+  readonly exitDeferred: Deferred.Deferred<ActorExit<S>, never>;
+  /**
+   * Actor scope — owns background fibers for this generation.
+   * Closing this scope interrupts all background fibers.
+   */
+  readonly actorScope: Scope.CloseableScope;
+}
+/** @internal */
+interface RuntimeLifecycleHooks<S, E> {
+  /** Before processEventCore — actor emits @machine.event inspection */
+  readonly onEvent?: (state: S, event: E) => Effect.Effect<void>;
+  /** After SubscriptionRef.set on transition — actor notifies listeners, annotates spans */
+  readonly onStateChange?: (result: ProcessEventResult<S>, event: E) => Effect.Effect<void>;
+  /** After reply settlement when transition occurred — actor publishes to transitionsPubSub */
+  readonly onProcessed?: (result: ProcessEventResult<S>, event: E) => Effect.Effect<void>;
+  /** When final state detected in event loop — actor emits @machine.stop */
+  readonly onFinal?: (state: S) => Effect.Effect<void>;
+  /** Before stop resource cleanup — actor emits @machine.stop, settles pending replies */
+  readonly onShutdown?: () => Effect.Effect<void>;
+  /** Before initial spawn effects — actor emits @machine.effect inspection */
+  readonly onInitialSpawnEffects?: (state: S) => Effect.Effect<void>;
+}
+/** @internal */
+interface RuntimeConfig<S, E> {
+  readonly actorId: string;
+  readonly hooks?: ProcessEventHooks<S, E>;
+  /**
+   * Cell-owned resources. When provided, the runtime uses the cell's stateRef,
+   * eventQueue, and stoppedRef instead of creating its own.
+   * Used by actor.ts for supervision (cell owns stable resources across generations).
+   */
+  readonly cellResources?: RuntimeCellResources<S, E>;
+  /**
+   * Custom queue factory. Default: `Queue.unbounded()`.
+   * Use `Queue.sliding(n)` or `Queue.dropping(n)` for bounded queues.
+   * Ignored when cellResources is provided.
+   */
+  readonly queueFactory?: Effect.Effect<Queue.Queue<RuntimeQueuedEvent<E>>>;
+  /** Lifecycle callbacks for actor-specific concerns */
+  readonly lifecycle?: RuntimeLifecycleHooks<S, E>;
+  /** Wrap each processQueued invocation — actor uses for span annotations */
+  readonly wrapProcess?: (state: S, event: E, inner: Effect.Effect<ProcessQueuedResult<S>>) => Effect.Effect<ProcessQueuedResult<S>>;
+  /** Called after self.spawn succeeds — actor tracks children */
+  readonly onChildSpawned?: (childId: string, child: unknown) => Effect.Effect<void>;
+  /** Skip registering stop as scope finalizer — actor manages its own lifecycle */
+  readonly skipFinalizer?: boolean;
+  /** Prefix for child actor IDs in self.spawn. Entity-machine uses `${actorId}/`. Default: no prefix. */
+  readonly childIdPrefix?: string;
+}
+/** @internal */
+interface ProcessQueuedResult<S> {
+  readonly shouldStop: boolean;
+  readonly stateChanged: boolean;
+  readonly result: ProcessEventResult<S>;
+}
+/**
+ * Create a runtime for a machine. Returns a handle for sending events
+ * and querying state. The runtime owns:
+ * - Event loop fiber
+ * - Postpone buffer
+ * - Background effects
+ * - State scope (spawn effects)
+ * - Final state detection
+ * - Exit reason via exitDeferred
+ *
+ * Resources (stateRef, eventQueue, stoppedRef) are either cell-provided
+ * or allocated fresh by the runtime.
+ *
+ * @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 { ProcessQueuedResult, RuntimeCellResources, RuntimeConfig, RuntimeHandle, RuntimeLifecycleHooks, RuntimeQueuedEvent, createRuntime };

package/v3/dist/internal/runtime.js

@@ -0,0 +1,335 @@
+import { INTERNAL_INIT_EVENT } from "./utils.js";
+import { NoReplyError } from "../errors.js";
+import { processEventCore, runSpawnEffects, shouldPostpone } from "./transition.js";
+import { ActorExit } from "../supervision.js";
+import { ActorSystem } from "../actor.js";
+import { Cause, Deferred, Effect, Exit, Fiber, Queue, Ref, Schema, Scope, SubscriptionRef } from "effect";
+//#region src/internal/runtime.ts
+/**
+* Shared runtime kernel for machine event processing.
+*
+* Provides a single-queue event loop with:
+* - Sequential event processing (no split-mailbox race)
+* - Postpone buffer with drain-on-state-change (gen_statem)
+* - Background effect lifecycle (under actorScope fault boundary)
+* - Spawn effect lifecycle (per-state scope)
+* - Final state detection → stop
+* - Reply settlement (call/ask Deferreds)
+* - Reply schema validation
+* - Lifecycle hooks for actor-specific concerns (inspection, listeners, etc.)
+* - ActorExit with exit reason (Final/Stopped/Defect) via exitDeferred
+*
+* Used by entity-machine and local actor (actor.ts delegates here).
+*
+* @internal
+*/
+/**
+* Create a runtime for a machine. Returns a handle for sending events
+* and querying state. The runtime owns:
+* - Event loop fiber
+* - Postpone buffer
+* - Background effects
+* - State scope (spawn effects)
+* - Final state detection
+* - Exit reason via exitDeferred
+*
+* Resources (stateRef, eventQueue, stoppedRef) are either cell-provided
+* or allocated fresh by the runtime.
+*
+* @internal
+*/
+const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (machine, system, config) {
+	const { actorId, hooks, lifecycle } = config;
+	const stateRef = config.cellResources?.stateRef ?? (yield* SubscriptionRef.make(machine.initial));
+	const stoppedRef = config.cellResources?.stoppedRef ?? (yield* Ref.make(false));
+	const eventQueue = config.cellResources?.eventQueue ?? (yield* config.queueFactory ?? Queue.unbounded());
+	const exitDeferred = yield* Deferred.make();
+	const actorScope = yield* Scope.make();
+	const selfSend = Effect.fn("effect-machine.runtime.self.send")(function* (event) {
+		if (!(yield* Ref.get(stoppedRef))) yield* Queue.offer(eventQueue, {
+			_tag: "send",
+			event
+		});
+	});
+	const childPrefix = config.childIdPrefix ?? "";
+	const defaultSpawn = (childId, childMachine) => system.spawn(`${childPrefix}${childId}`, childMachine).pipe(Effect.provideService(ActorSystem, system));
+	const onChildSpawned = config.onChildSpawned;
+	const self = {
+		send: selfSend,
+		cast: selfSend,
+		spawn: onChildSpawned !== void 0 ? (childId, childMachine) => defaultSpawn(childId, childMachine).pipe(Effect.tap((child) => onChildSpawned(childId, child))) : defaultSpawn
+	};
+	const stateScopeRef = { current: yield* Scope.make() };
+	const backgroundFibers = [];
+	const initEvent = { _tag: INTERNAL_INIT_EVENT };
+	const ctx = {
+		actorId,
+		state: machine.initial,
+		event: initEvent,
+		self,
+		system
+	};
+	const { effects: effectSlots } = machine._slots;
+	for (const bg of machine.backgroundEffects) {
+		const fiber = yield* Effect.forkDaemon(bg.handler({
+			actorId,
+			state: machine.initial,
+			event: initEvent,
+			self,
+			effects: effectSlots,
+			system
+		}).pipe(Effect.provideService(machine.Context, ctx)));
+		backgroundFibers.push(fiber);
+	}
+	if (lifecycle?.onInitialSpawnEffects !== void 0) yield* lifecycle.onInitialSpawnEffects(machine.initial);
+	const loopFiberRef = { current: void 0 };
+	const initialSpawnDefectSignal = (cause) => Deferred.succeed(exitDeferred, ActorExit.Defect(cause, "initial-spawn")).pipe(Effect.zipRight(Ref.set(stoppedRef, true)), Effect.zipRight(Effect.suspend(() => loopFiberRef.current !== void 0 ? Fiber.interrupt(loopFiberRef.current) : Effect.void)), Effect.asVoid);
+	yield* runSpawnEffects(machine, machine.initial, initEvent, self, stateScopeRef.current, system, actorId, hooks?.onError, initialSpawnDefectSignal).pipe(Effect.catchAllCause((cause) => {
+		return Effect.gen(function* () {
+			yield* Ref.set(stoppedRef, true);
+			yield* Scope.close(stateScopeRef.current, Exit.void);
+			yield* Scope.close(actorScope, Exit.void);
+			yield* Deferred.succeed(exitDeferred, ActorExit.Defect(cause, "initial-spawn"));
+			return yield* Effect.failCause(cause);
+		});
+	}));
+	/** Set the exit deferred exactly once. */
+	const setExit = (exit) => Deferred.succeed(exitDeferred, exit).pipe(Effect.asVoid);
+	if (machine.finalStates.has(machine.initial._tag)) {
+		if (lifecycle?.onFinal !== void 0) yield* lifecycle.onFinal(machine.initial);
+		yield* Ref.set(stoppedRef, true);
+		yield* Scope.close(stateScopeRef.current, Exit.void);
+		yield* Scope.close(actorScope, Exit.void);
+		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+		yield* setExit(ActorExit.Final(machine.initial));
+		return makeHandle(stateRef, stoppedRef, eventQueue, exitDeferred, actorScope);
+	}
+	const augmentedHooks = {
+		...hooks,
+		onSpawnDefect: (cause) => Deferred.succeed(exitDeferred, ActorExit.Defect(cause, "spawn")).pipe(Effect.zipRight(Ref.set(stoppedRef, true)), Effect.zipRight(Effect.suspend(() => loopFiberRef.current !== void 0 ? Fiber.interrupt(loopFiberRef.current) : Effect.void)), Effect.asVoid)
+	};
+	const loopFiber = yield* Effect.forkDaemon(runtimeEventLoop(machine, stateRef, eventQueue, stoppedRef, self, stateScopeRef, actorId, system, exitDeferred, augmentedHooks, lifecycle, config.wrapProcess));
+	loopFiberRef.current = loopFiber;
+	if (backgroundFibers.length > 0) yield* Effect.forkDaemon(Effect.raceAll(backgroundFibers.map((fiber) => Fiber.await(fiber).pipe(Effect.flatMap((exit) => {
+		if (exit._tag === "Failure" && !Cause.isInterruptedOnly(exit.cause)) return setExit(ActorExit.Defect(exit.cause, "background")).pipe(Effect.zipRight(Ref.set(stoppedRef, true)), Effect.zipRight(Fiber.interrupt(loopFiber)));
+		return Effect.never;
+	})))).pipe(Effect.catchAllCause(() => Effect.void)));
+	const stop = Effect.gen(function* () {
+		if (yield* Ref.get(stoppedRef)) return;
+		if (lifecycle?.onShutdown !== void 0) yield* lifecycle.onShutdown();
+		yield* Ref.set(stoppedRef, true);
+		yield* Fiber.interrupt(loopFiber);
+		yield* Scope.close(stateScopeRef.current, Exit.void);
+		yield* Scope.close(actorScope, Exit.void);
+		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+		yield* setExit(ActorExit.Stopped);
+	}).pipe(Effect.asVoid);
+	if (config.skipFinalizer !== true) yield* Effect.addFinalizer(() => stop);
+	return {
+		...makeHandle(stateRef, stoppedRef, eventQueue, exitDeferred, actorScope),
+		stop
+	};
+});
+/**
+* Build the runtime handle (send/ask/getState/isStopped).
+* Shared between initial-final and normal paths.
+*/
+const makeHandle = (stateRef, stoppedRef, eventQueue, exitDeferred, actorScope) => ({
+	send: (event) => Effect.gen(function* () {
+		if (!(yield* Ref.get(stoppedRef))) yield* Queue.offer(eventQueue, {
+			_tag: "send",
+			event
+		});
+	}),
+	sendWait: (event) => Effect.gen(function* () {
+		if (!(yield* Ref.get(stoppedRef))) {
+			const done = yield* Deferred.make();
+			yield* Queue.offer(eventQueue, {
+				_tag: "sendWait",
+				event,
+				done
+			});
+			yield* Deferred.await(done);
+		}
+	}),
+	ask: (event) => Effect.gen(function* () {
+		if (yield* Ref.get(stoppedRef)) return yield* new NoReplyError({
+			actorId: "stopped",
+			eventTag: event._tag
+		});
+		const reply = yield* Deferred.make();
+		yield* Queue.offer(eventQueue, {
+			_tag: "ask",
+			event,
+			reply
+		});
+		return yield* Deferred.await(reply);
+	}),
+	getState: SubscriptionRef.get(stateRef),
+	stateRef,
+	isStopped: Ref.get(stoppedRef),
+	stop: Effect.void,
+	_queue: eventQueue,
+	_stoppedRef: stoppedRef,
+	exitDeferred,
+	actorScope
+});
+const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function* (machine, stateRef, eventQueue, stoppedRef, self, stateScopeRef, actorId, system, exitDeferred, hooks, lifecycle, wrapProcess) {
+	/** Set the exit deferred exactly once. */
+	const setExit = (exit) => Deferred.succeed(exitDeferred, exit).pipe(Effect.asVoid);
+	const postponed = [];
+	const hasPostponeRules = machine.postponeRules.length > 0;
+	const processQueued = Effect.fn("effect-machine.runtime.processQueued")(function* (queued) {
+		const event = queued.event;
+		const currentState = yield* SubscriptionRef.get(stateRef);
+		if (hasPostponeRules && shouldPostpone(machine, currentState._tag, event._tag)) {
+			if (queued._tag === "call") {
+				const postponedResult = {
+					newState: currentState,
+					previousState: currentState,
+					transitioned: false,
+					lifecycleRan: false,
+					isFinal: false,
+					hasReply: false,
+					deferReply: false,
+					reply: void 0,
+					postponed: true
+				};
+				yield* Deferred.succeed(queued.reply, postponedResult);
+			}
+			if (queued._tag === "sendWait") yield* Deferred.succeed(queued.done, void 0);
+			postponed.push({
+				_tag: "send",
+				event
+			});
+			return {
+				shouldStop: false,
+				stateChanged: false,
+				result: {
+					newState: currentState,
+					previousState: currentState,
+					transitioned: false,
+					lifecycleRan: false,
+					isFinal: false,
+					hasReply: false,
+					deferReply: false,
+					reply: void 0,
+					postponed: true
+				}
+			};
+		}
+		if (lifecycle?.onEvent !== void 0) yield* lifecycle.onEvent(currentState, event);
+		const result = yield* processEventCore(machine, currentState, event, self, stateScopeRef, system, actorId, hooks);
+		if (result.transitioned) yield* SubscriptionRef.set(stateRef, result.newState);
+		if (lifecycle?.onStateChange !== void 0 && result.transitioned) yield* lifecycle.onStateChange(result, event);
+		switch (queued._tag) {
+			case "call":
+				yield* Deferred.succeed(queued.reply, result);
+				break;
+			case "sendWait":
+				yield* Deferred.succeed(queued.done, void 0);
+				break;
+			case "ask":
+				if (result.hasReply) {
+					const replySchema = machine._replySchemas?.get(event._tag);
+					if (replySchema !== void 0) {
+						let decoded;
+						try {
+							decoded = Schema.decodeUnknownSync(replySchema)(result.reply);
+						} catch (decodeError) {
+							yield* Deferred.die(queued.reply, decodeError);
+							return yield* Effect.die(decodeError);
+						}
+						yield* Deferred.succeed(queued.reply, decoded);
+					} else yield* Deferred.succeed(queued.reply, result.reply);
+				} else yield* Deferred.fail(queued.reply, new NoReplyError({
+					actorId,
+					eventTag: event._tag
+				}));
+				break;
+		}
+		if (lifecycle?.onProcessed !== void 0 && result.transitioned) yield* lifecycle.onProcessed(result, event);
+		const shouldStop = result.isFinal && result.lifecycleRan;
+		if (shouldStop && lifecycle?.onFinal !== void 0) yield* lifecycle.onFinal(result.newState);
+		return {
+			shouldStop,
+			stateChanged: result.lifecycleRan,
+			result
+		};
+	});
+	const shutdown = (exitReason) => Effect.gen(function* () {
+		yield* Ref.set(stoppedRef, true);
+		if (lifecycle?.onShutdown !== void 0) yield* lifecycle.onShutdown();
+		settlePostponed(postponed, actorId);
+		const remaining = yield* Queue.takeAll(eventQueue);
+		for (const entry of remaining) if (entry._tag === "sendWait") Effect.runFork(Deferred.succeed(entry.done, void 0));
+		else if (entry._tag === "ask") Effect.runFork(Deferred.fail(entry.reply, new NoReplyError({
+			actorId,
+			eventTag: entry.event._tag
+		})));
+		else if (entry._tag === "call") {
+			const currentState = yield* SubscriptionRef.get(stateRef);
+			Effect.runFork(Deferred.succeed(entry.reply, {
+				newState: currentState,
+				previousState: currentState,
+				transitioned: false,
+				lifecycleRan: false,
+				isFinal: machine.finalStates.has(currentState._tag),
+				hasReply: false,
+				deferReply: false,
+				reply: void 0,
+				postponed: false
+			}));
+		}
+		yield* Scope.close(stateScopeRef.current, Exit.void);
+		yield* setExit(exitReason);
+	});
+	while (true) {
+		const queued = yield* Queue.take(eventQueue);
+		if (queued._tag === "drain") {
+			yield* shutdown(ActorExit.Stopped);
+			yield* Deferred.succeed(queued.done, void 0);
+			return;
+		}
+		const eventQueued = queued;
+		const processInner = processQueued(eventQueued);
+		const { shouldStop, stateChanged } = yield* (wrapProcess !== void 0 ? Effect.gen(function* () {
+			return yield* wrapProcess(yield* SubscriptionRef.get(stateRef), eventQueued.event, processInner);
+		}) : processInner).pipe(Effect.catchAllCause((cause) => {
+			if (queued._tag === "sendWait") Effect.runFork(Deferred.succeed(queued.done, void 0));
+			else if (queued._tag === "ask") Effect.runFork(Deferred.die(queued.reply, cause));
+			else if (queued._tag === "call") Effect.runFork(Deferred.failCause(queued.reply, cause));
+			return shutdown(ActorExit.Defect(cause, "transition")).pipe(Effect.zipRight(Effect.failCause(cause)));
+		}));
+		if (shouldStop) {
+			const finalState = yield* SubscriptionRef.get(stateRef);
+			yield* shutdown(ActorExit.Final(finalState));
+			return;
+		}
+		let drainTriggered = stateChanged;
+		while (drainTriggered && postponed.length > 0) {
+			drainTriggered = false;
+			const drained = postponed.splice(0);
+			for (const entry of drained) {
+				const drain = yield* processQueued(entry);
+				if (drain.shouldStop) {
+					const finalState = yield* SubscriptionRef.get(stateRef);
+					yield* shutdown(ActorExit.Final(finalState));
+					return;
+				}
+				if (drain.stateChanged) drainTriggered = true;
+			}
+		}
+	}
+});
+/** Settle all pending Deferreds in the postpone buffer on shutdown. */
+const settlePostponed = (postponed, actorId) => {
+	for (const entry of postponed) if (entry._tag === "ask") Effect.runFork(Deferred.fail(entry.reply, new NoReplyError({
+		actorId,
+		eventTag: entry.event._tag
+	})));
+	else if (entry._tag === "sendWait") Effect.runFork(Deferred.succeed(entry.done, void 0));
+	postponed.length = 0;
+};
+//#endregion
+export { createRuntime };

package/v3/dist/internal/transition.d.ts

@@ -1,5 +1,5 @@
 import { EffectsDef, GuardsDef, MachineContext } from "../slot.js";
-import { BuiltMachine, Machine, MachineRef, SpawnEffect, Transition } from "../machine.js";
+import { Machine, MachineRef, SpawnEffect, Transition } from "../machine.js";
 import { ActorSystem } from "../actor.js";
 import { Cause, Effect, Scope } from "effect";
 
@@ -32,6 +32,7 @@ declare const runTransitionHandler: <S extends {
 }, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, transition: Transition<S, E, GD, EFD, R>, state: S, event: E, self: MachineRef<E>, system: ActorSystem, actorId: string) => Effect.Effect<{
   newState: S;
   hasReply: boolean;
+  deferReply: boolean;
   reply: unknown;
 }, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
@@ -54,6 +55,7 @@ declare const executeTransition: <S extends {
   transitioned: boolean;
   reenter: boolean;
   hasReply: boolean;
+  deferReply: boolean;
   reply: unknown;
 }, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
@@ -66,6 +68,8 @@ interface ProcessEventHooks<S, E> {
   readonly onTransition?: (from: S, to: S, event: E) => Effect.Effect<void>;
   /** Called when a transition handler or spawn effect fails with a defect */
   readonly onError?: (info: ProcessEventError<S, E>) => Effect.Effect<void>;
+  /** Called when a forked spawn fiber defects — signals the runtime to set exitDeferred */
+  readonly onSpawnDefect?: (cause: Cause.Cause<unknown>) => Effect.Effect<void>;
 }
 /**
  * Error info for inspection hooks.
@@ -92,6 +96,8 @@ interface ProcessEventResult<S> {
   readonly isFinal: boolean;
   /** Whether the handler provided a reply (structural, not value-based) */
   readonly hasReply: boolean;
+  /** Whether the handler deferred the reply to a spawn handler (Machine.deferReply) */
+  readonly deferReply: boolean;
   /** Domain reply value from handler (used by ask). Only meaningful when hasReply is true. */
   readonly reply?: unknown;
   /** Whether the event was postponed (buffered for retry after next state change) */
@@ -131,6 +137,7 @@ declare const processEventCore: <S extends {
   lifecycleRan: boolean;
   isFinal: boolean;
   hasReply: boolean;
+  deferReply: boolean;
   reply: unknown;
   postponed: boolean;
 }, never, Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
@@ -143,7 +150,7 @@ declare const runSpawnEffects: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, state: S, event: E, self: MachineRef<E>, stateScope: Scope.CloseableScope, system: ActorSystem, actorId: string, onError?: ((info: ProcessEventError<S, E>) => Effect.Effect<void>) | undefined) => Effect.Effect<void, never, Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, state: S, event: E, self: MachineRef<E>, stateScope: Scope.CloseableScope, system: ActorSystem, actorId: string, onError?: ((info: ProcessEventError<S, E>) => Effect.Effect<void>) | undefined, onSpawnDefect?: ((cause: Cause.Cause<unknown>) => Effect.Effect<void>) | undefined) => Effect.Effect<void, never, Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
 /**
  * Resolve which transition should fire for a given state and event.
  * Uses indexed O(1) lookup. First matching transition wins.
@@ -161,14 +168,13 @@ declare const invalidateIndex: (machine: object) => void;
  * Find all transitions matching a state/event pair.
  * Returns empty array if no matches.
  *
- * Accepts both `Machine` and `BuiltMachine`.
  * O(1) lookup after first access (index is lazily built).
  */
 declare const findTransitions: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: Machine<S, E, R, any, any, GD, EFD> | BuiltMachine<S, E, R>, stateTag: string, eventTag: string) => ReadonlyArray<Transition<S, E, GD, EFD, R>>;
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: Machine<S, E, R, any, any, GD, EFD>, stateTag: string, eventTag: string) => ReadonlyArray<Transition<S, E, GD, EFD, R>>;
 /**
  * Find all spawn effects for a state.
  * Returns empty array if no matches.