effect-machine 0.9.0 → 0.11.0

package/v3/dist/index.d.ts

@@ -0,0 +1,9 @@
+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 { 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 };

package/v3/dist/index.js

@@ -0,0 +1,8 @@
+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 { 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 };

package/{dist-v3 → v3/dist}/inspection.d.ts

@@ -1,6 +1,6 @@
-import { Schema } from "effect";
+import { Context, Effect, Schema } from "effect";
 
-//#region src-v3/inspection.d.ts
+//#region src/inspection.d.ts
 /**
  * Resolve a type param: if it's a Schema, extract `.Type`; otherwise use as-is.
  */
@@ -45,6 +45,18 @@ interface EffectEvent<S> {
   readonly state: S;
   readonly timestamp: number;
 }
+/**
+ * Event emitted when a task lifecycle phase occurs
+ */
+interface TaskEvent<S> {
+  readonly type: "@machine.task";
+  readonly actorId: string;
+  readonly state: S;
+  readonly taskName?: string;
+  readonly phase: "start" | "success" | "failure" | "interrupt";
+  readonly error?: string;
+  readonly timestamp: number;
+}
 /**
  * Event emitted when a transition handler or spawn effect fails with a defect
  */
@@ -69,7 +81,7 @@ interface StopEvent<S> {
 /**
  * Union of all inspection events
  */
-type InspectionEvent<S, E> = SpawnEvent<S> | EventReceivedEvent<S, E> | TransitionEvent<S, E> | EffectEvent<S> | ErrorEvent<S, E> | StopEvent<S>;
+type InspectionEvent<S, E> = SpawnEvent<S> | EventReceivedEvent<S, E> | TransitionEvent<S, E> | EffectEvent<S> | TaskEvent<S> | ErrorEvent<S, E> | StopEvent<S>;
 /**
  * Convenience alias for untyped inspection events.
  * Useful for general-purpose inspectors that don't need specific state/event types.
@@ -81,19 +93,23 @@ type AnyInspectionEvent = InspectionEvent<{
 }, {
   readonly _tag: string;
 }>;
+/**
+ * Inspector handler — sync callback or Effect-returning callback.
+ */
+type InspectorHandler<S, E> = (event: InspectionEvent<S, E>) => void | Effect.Effect<void, never, never>;
 /**
  * Inspector interface for observing machine behavior
  */
 interface Inspector<S, E> {
-  readonly onInspect: (event: InspectionEvent<S, E>) => void;
+  readonly onInspect: InspectorHandler<S, E>;
 }
 /**
  * Inspector service tag - optional service for machine introspection
  * Uses `any` types to allow variance flexibility when providing the service
  */
-declare const Inspector: any;
+declare const Inspector: Context.Tag<Inspector<any, any>, Inspector<any, any>>;
 /**
- * Create an inspector from a callback function.
+ * Create an inspector from a sync callback function.
  *
  * Type params accept either raw tagged types or Schema constructors:
  * - `makeInspector(cb)` — defaults to `AnyInspectionEvent`
@@ -104,7 +120,36 @@ declare const makeInspector: <S = {
   readonly _tag: string;
 }, E = {
   readonly _tag: string;
-}>(onInspect: (event: InspectionEvent<ResolveType<S>, ResolveType<E>>) => void) => Inspector<ResolveType<S>, ResolveType<E>>;
+}>(onInspect: InspectorHandler<ResolveType<S>, ResolveType<E>>) => Inspector<ResolveType<S>, ResolveType<E>>;
+/**
+ * Create an inspector from an Effect-returning callback function.
+ */
+declare const makeInspectorEffect: <S = {
+  readonly _tag: string;
+}, E = {
+  readonly _tag: string;
+}>(onInspect: (event: InspectionEvent<ResolveType<S>, ResolveType<E>>) => Effect.Effect<void, never, never>) => Inspector<ResolveType<S>, ResolveType<E>>;
+/**
+ * Combine multiple inspectors into one. All run concurrently per event.
+ * Individual inspector failures are swallowed.
+ */
+declare const combineInspectors: <S, E>(...inspectors: ReadonlyArray<Inspector<S, E>>) => Inspector<S, E>;
+/**
+ * Options for the tracing inspector.
+ */
+interface TracingInspectorOptions<S, E> {
+  readonly spanName?: string | ((event: InspectionEvent<S, E>) => string);
+  readonly attributes?: (event: InspectionEvent<S, E>) => Readonly<Record<string, string | number | boolean>>;
+  readonly eventName?: (event: InspectionEvent<S, E>) => string;
+}
+/**
+ * Inspector that emits OpenTelemetry spans and events for each inspection event.
+ */
+declare const tracingInspector: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}>(options?: TracingInspectorOptions<S, E>) => Inspector<S, E>;
 /**
  * Console inspector that logs events in a readable format
  */
@@ -122,4 +167,4 @@ declare const collectingInspector: <S extends {
   readonly _tag: string;
 }>(events: InspectionEvent<S, E>[]) => Inspector<S, E>;
 //#endregion
-export { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, SpawnEvent, StopEvent, TransitionEvent, collectingInspector, consoleInspector, makeInspector };
+export { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, InspectorHandler, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector };

package/v3/dist/inspection.js

@@ -0,0 +1,156 @@
+import { Context, Effect, Option } from "effect";
+//#region src/inspection.ts
+/**
+* Inspector service tag - optional service for machine introspection
+* Uses `any` types to allow variance flexibility when providing the service
+*/
+const Inspector = Context.GenericTag("@effect/machine/Inspector");
+/**
+* Create an inspector from a sync callback function.
+*
+* Type params accept either raw tagged types or Schema constructors:
+* - `makeInspector(cb)` — defaults to `AnyInspectionEvent`
+* - `makeInspector<MyState, MyEvent>(cb)` — explicit tagged types
+* - `makeInspector<typeof MyState, typeof MyEvent>(cb)` — schema constructors (auto-extracts `.Type`)
+*/
+const makeInspector = (onInspect) => ({ onInspect });
+/**
+* Create an inspector from an Effect-returning callback function.
+*/
+const makeInspectorEffect = (onInspect) => ({ onInspect });
+/**
+* Run an inspector handler, handling both sync and Effect returns.
+* @internal
+*/
+const inspectionEffect = (inspector, event) => {
+	const result = inspector.onInspect(event);
+	return Effect.isEffect(result) ? result : Effect.void;
+};
+/**
+* Combine multiple inspectors into one. All run concurrently per event.
+* Individual inspector failures are swallowed.
+*/
+const combineInspectors = (...inspectors) => ({ onInspect: (event) => Effect.forEach(inspectors, (inspector) => inspectionEffect(inspector, event).pipe(Effect.catchAllCause(() => Effect.void)), {
+	concurrency: "unbounded",
+	discard: true
+}) });
+const inspectionSpanName = (event) => {
+	switch (event.type) {
+		case "@machine.spawn": return `Machine.inspect ${event.initialState._tag}`;
+		case "@machine.event": return `Machine.inspect ${event.event._tag}`;
+		case "@machine.transition": return `Machine.inspect ${event.fromState._tag}->${event.toState._tag}`;
+		case "@machine.effect": return `Machine.inspect ${event.effectType}`;
+		case "@machine.task": return `Machine.inspect task:${event.phase}`;
+		case "@machine.error": return `Machine.inspect ${event.phase}`;
+		case "@machine.stop": return `Machine.inspect ${event.finalState._tag}`;
+	}
+};
+const inspectionTraceName = (event) => {
+	switch (event.type) {
+		case "@machine.spawn": return `machine.spawn ${event.initialState._tag}`;
+		case "@machine.event": return `machine.event ${event.event._tag}`;
+		case "@machine.transition": return `machine.transition ${event.fromState._tag}->${event.toState._tag}`;
+		case "@machine.effect": return `machine.effect ${event.effectType}`;
+		case "@machine.task": return `machine.task ${event.phase}${event.taskName === void 0 ? "" : ` ${event.taskName}`}`;
+		case "@machine.error": return `machine.error ${event.phase}`;
+		case "@machine.stop": return `machine.stop ${event.finalState._tag}`;
+	}
+};
+const inspectionAttributes = (event) => {
+	const shared = {
+		"machine.actor.id": event.actorId,
+		"machine.inspection.type": event.type
+	};
+	switch (event.type) {
+		case "@machine.spawn": return {
+			...shared,
+			"machine.state.initial": event.initialState._tag
+		};
+		case "@machine.event": return {
+			...shared,
+			"machine.state.current": event.state._tag,
+			"machine.event.tag": event.event._tag
+		};
+		case "@machine.transition": return {
+			...shared,
+			"machine.state.from": event.fromState._tag,
+			"machine.state.to": event.toState._tag,
+			"machine.event.tag": event.event._tag
+		};
+		case "@machine.effect": return {
+			...shared,
+			"machine.state.current": event.state._tag,
+			"machine.effect.kind": event.effectType
+		};
+		case "@machine.task": return {
+			...shared,
+			"machine.state.current": event.state._tag,
+			"machine.task.phase": event.phase,
+			...event.taskName === void 0 ? {} : { "machine.task.name": event.taskName }
+		};
+		case "@machine.error": return {
+			...shared,
+			"machine.phase": event.phase,
+			"machine.state.current": event.state._tag
+		};
+		case "@machine.stop": return {
+			...shared,
+			"machine.state.final": event.finalState._tag
+		};
+	}
+};
+/**
+* Inspector that emits OpenTelemetry spans and events for each inspection event.
+*/
+const tracingInspector = (options) => ({ onInspect: (event) => {
+	const spanName = typeof options?.spanName === "function" ? options.spanName(event) : options?.spanName;
+	const traceName = options?.eventName?.(event) ?? inspectionTraceName(event);
+	const attributes = {
+		...inspectionAttributes(event),
+		...options?.attributes?.(event) ?? {}
+	};
+	return Effect.gen(function* () {
+		const currentSpan = yield* Effect.option(Effect.currentSpan);
+		if (Option.isSome(currentSpan)) currentSpan.value.event(traceName, BigInt(event.timestamp) * 1000000n, {
+			actorId: event.actorId,
+			inspectionType: event.type
+		});
+	}).pipe(Effect.withSpan(spanName ?? inspectionSpanName(event), { attributes }));
+} });
+/**
+* Console inspector that logs events in a readable format
+*/
+const consoleInspector = () => makeInspector((event) => {
+	const prefix = `[${event.actorId}]`;
+	switch (event.type) {
+		case "@machine.spawn":
+			console.log(prefix, "spawned →", event.initialState._tag);
+			break;
+		case "@machine.event":
+			console.log(prefix, "received", event.event._tag, "in", event.state._tag);
+			break;
+		case "@machine.transition":
+			console.log(prefix, event.fromState._tag, "→", event.toState._tag);
+			break;
+		case "@machine.effect":
+			console.log(prefix, event.effectType, "effect in", event.state._tag);
+			break;
+		case "@machine.task":
+			console.log(prefix, "task", event.phase, event.taskName ?? "<unnamed>", "in", event.state._tag);
+			break;
+		case "@machine.error":
+			console.log(prefix, "error in", event.phase, event.state._tag, "-", event.error);
+			break;
+		case "@machine.stop":
+			console.log(prefix, "stopped in", event.finalState._tag);
+			break;
+	}
+});
+/**
+* Collecting inspector that stores events in an array for testing
+*/
+const collectingInspector = (events) => ({ onInspect: (event) => {
+	events.push(event);
+} });
+//#endregion
+export { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector };

package/{dist-v3 → v3/dist}/internal/brands.d.ts

@@ -1,6 +1,6 @@
 import { Brand } from "effect";
 
-//#region src-v3/internal/brands.d.ts
+//#region src/internal/brands.d.ts
 declare const StateTypeId: unique symbol;
 declare const EventTypeId: unique symbol;
 type StateTypeId = typeof StateTypeId;

package/{dist-v3 → v3/dist}/internal/inspection.d.ts

@@ -1,7 +1,7 @@
 import { InspectionEvent, Inspector } from "../inspection.js";
 import { Effect } from "effect";
 
-//#region src-v3/internal/inspection.d.ts
+//#region src/internal/inspection.d.ts
 /**
  * Emit an inspection event with timestamp from Clock.
  * @internal

package/v3/dist/internal/inspection.js

@@ -0,0 +1,20 @@
+import { Clock, Effect } from "effect";
+//#region src/internal/inspection.ts
+/**
+* Emit an inspection event with timestamp from Clock.
+* @internal
+*/
+const emitWithTimestamp = Effect.fn("effect-machine.emitWithTimestamp")(function* (inspector, makeEvent) {
+	if (inspector === void 0) return;
+	const event = makeEvent(yield* Clock.currentTimeMillis);
+	const result = yield* Effect.sync(() => {
+		try {
+			return inspector.onInspect(event);
+		} catch {
+			return;
+		}
+	});
+	if (result !== void 0 && Effect.isEffect(result)) yield* result.pipe(Effect.catchAllCause(() => Effect.void));
+});
+//#endregion
+export { emitWithTimestamp };

package/{dist-v3 → v3/dist}/internal/transition.d.ts

@@ -1,9 +1,9 @@
-import { EffectsDef, GuardsDef } from "../slot.js";
+import { EffectsDef, GuardsDef, MachineContext } from "../slot.js";
 import { BuiltMachine, Machine, MachineRef, SpawnEffect, Transition } from "../machine.js";
 import { ActorSystem } from "../actor.js";
 import { Cause, Effect, Scope } from "effect";
 
-//#region src-v3/internal/transition.d.ts
+//#region src/internal/transition.d.ts
 /**
  * Result of executing a transition.
  */
@@ -29,7 +29,11 @@ declare const runTransitionHandler: <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>, transition: Transition<S, E, GD, EFD, R>, state: S, event: E, self: MachineRef<E>, system: ActorSystem) => Effect.Effect<S, never, Exclude<R, unknown>>;
+}, 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;
+  reply: unknown;
+}, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
  * Execute a transition for a given state and event.
  * Handles transition resolution, handler invocation, and guard/effect slot creation.
@@ -45,11 +49,13 @@ declare const executeTransition: <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>, currentState: S, event: E, self: MachineRef<E>, system: ActorSystem) => Effect.Effect<{
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, currentState: S, event: E, self: MachineRef<E>, system: ActorSystem, actorId: string) => Effect.Effect<{
   newState: S;
   transitioned: boolean;
   reenter: boolean;
-}, never, Exclude<R, unknown>>;
+  hasReply: boolean;
+  reply: unknown;
+}, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
  * Optional hooks for event processing inspection/tracing.
  */
@@ -84,7 +90,22 @@ interface ProcessEventResult<S> {
   readonly lifecycleRan: boolean;
   /** Whether new state is final */
   readonly isFinal: boolean;
+  /** Whether the handler provided a reply (structural, not value-based) */
+  readonly hasReply: 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) */
+  readonly postponed: boolean;
 }
+/**
+ * Check if an event should be postponed in the current state.
+ * @internal
+ */
+declare const shouldPostpone: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R>(machine: Machine<S, E, R, any, any, any, any>, stateTag: string, eventTag: string) => boolean;
 /**
  * Process a single event through the machine.
  *
@@ -103,13 +124,16 @@ declare const processEventCore: <S extends {
   readonly _tag: string;
 }, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, currentState: S, event: E, self: MachineRef<E>, stateScopeRef: {
   current: Scope.CloseableScope;
-}, system: ActorSystem, hooks?: ProcessEventHooks<S, E> | undefined) => Effect.Effect<{
-  newState: any;
+}, system: ActorSystem, actorId: string, hooks?: ProcessEventHooks<S, E> | undefined) => Effect.Effect<{
+  newState: S;
   previousState: S;
   transitioned: boolean;
-  lifecycleRan: any;
+  lifecycleRan: boolean;
   isFinal: boolean;
-}, unknown, unknown>;
+  hasReply: boolean;
+  reply: unknown;
+  postponed: boolean;
+}, never, Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
 /**
  * Run spawn effects for a state (forked into state scope, auto-cancelled on state exit).
  *
@@ -119,7 +143,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, onError?: ((info: ProcessEventError<S, E>) => Effect.Effect<void>) | undefined) => Effect.Effect<void, never, unknown>;
+}, 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>>;
 /**
  * Resolve which transition should fire for a given state and event.
  * Uses indexed O(1) lookup. First matching transition wins.
@@ -157,4 +181,4 @@ declare const findSpawnEffects: <S extends {
   readonly _tag: string;
 }, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(machine: Machine<S, E, R, any, any, GD, EFD>, stateTag: string) => ReadonlyArray<SpawnEffect<S, E, EFD, R>>;
 //#endregion
-export { ProcessEventError, ProcessEventHooks, ProcessEventResult, TransitionExecutionResult, executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler };
+export { ProcessEventError, ProcessEventHooks, ProcessEventResult, TransitionExecutionResult, executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler, shouldPostpone };

package/{dist-v3 → v3/dist}/internal/transition.js

@@ -1,7 +1,7 @@
 import { INTERNAL_ENTER_EVENT, isEffect } from "./utils.js";
 import { BuiltMachine } from "../machine.js";
 import { Cause, Effect, Exit, Scope } from "effect";
-//#region src-v3/internal/transition.ts
+//#region src/internal/transition.ts
 /**
 * Transition execution and indexing.
 *
@@ -22,8 +22,9 @@ import { Cause, Effect, Exit, Scope } from "effect";
 *
 * @internal
 */
-const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(function* (machine, transition, state, event, self, system) {
+const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(function* (machine, transition, state, event, self, system, actorId) {
 	const ctx = {
+		actorId,
 		state,
 		event,
 		self,
@@ -36,8 +37,18 @@ const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(fu
 		guards,
 		effects
 	};
-	const result = transition.handler(handlerCtx);
-	return isEffect(result) ? yield* result.pipe(Effect.provideService(machine.Context, ctx)) : result;
+	const raw = transition.handler(handlerCtx);
+	const resolved = isEffect(raw) ? yield* raw.pipe(Effect.provideService(machine.Context, ctx)) : raw;
+	if (resolved !== null && typeof resolved === "object" && "state" in resolved && "reply" in resolved && !("_tag" in resolved)) return {
+		newState: resolved.state,
+		hasReply: true,
+		reply: resolved.reply
+	};
+	return {
+		newState: resolved,
+		hasReply: false,
+		reply: void 0
+	};
 });
 /**
 * Execute a transition for a given state and event.
@@ -50,20 +61,33 @@ const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(fu
 *
 * @internal
 */
-const executeTransition = Effect.fn("effect-machine.executeTransition")(function* (machine, currentState, event, self, system) {
+const executeTransition = Effect.fn("effect-machine.executeTransition")(function* (machine, currentState, event, self, system, actorId) {
 	const transition = resolveTransition(machine, currentState, event);
 	if (transition === void 0) return {
 		newState: currentState,
 		transitioned: false,
-		reenter: false
+		reenter: false,
+		hasReply: false,
+		reply: void 0
 	};
+	const { newState, hasReply, reply } = yield* runTransitionHandler(machine, transition, currentState, event, self, system, actorId);
 	return {
-		newState: yield* runTransitionHandler(machine, transition, currentState, event, self, system),
+		newState,
 		transitioned: true,
-		reenter: transition.reenter === true
+		reenter: transition.reenter === true,
+		hasReply,
+		reply
 	};
 });
 /**
+* Check if an event should be postponed in the current state.
+* @internal
+*/
+const shouldPostpone = (machine, stateTag, eventTag) => {
+	for (const rule of machine.postponeRules) if (rule.stateTag === stateTag && rule.eventTag === eventTag) return true;
+	return false;
+};
+/**
 * Process a single event through the machine.
 *
 * Handles:
@@ -75,8 +99,8 @@ const executeTransition = Effect.fn("effect-machine.executeTransition")(function
 *
 * @internal
 */
-const processEventCore = Effect.fn("effect-machine.processEventCore")(function* (machine, currentState, event, self, stateScopeRef, system, hooks) {
-	const result = yield* executeTransition(machine, currentState, event, self, system).pipe(Effect.catchAllCause((cause) => {
+const processEventCore = Effect.fn("effect-machine.processEventCore")(function* (machine, currentState, event, self, stateScopeRef, system, actorId, hooks) {
+	const result = yield* executeTransition(machine, currentState, event, self, system, actorId).pipe(Effect.catchAllCause((cause) => {
 		if (Cause.isInterruptedOnly(cause)) return Effect.interrupt;
 		const onError = hooks?.onError;
 		if (onError === void 0) return Effect.failCause(cause).pipe(Effect.orDie);
@@ -92,7 +116,10 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 		previousState: currentState,
 		transitioned: false,
 		lifecycleRan: false,
-		isFinal: false
+		isFinal: false,
+		hasReply: false,
+		reply: void 0,
+		postponed: false
 	};
 	const newState = result.newState;
 	const runLifecycle = newState._tag !== currentState._tag || result.reenter;
@@ -101,14 +128,17 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 		stateScopeRef.current = yield* Scope.make();
 		if (hooks?.onTransition !== void 0) yield* hooks.onTransition(currentState, newState, event);
 		if (hooks?.onSpawnEffect !== void 0) yield* hooks.onSpawnEffect(newState);
-		yield* runSpawnEffects(machine, newState, { _tag: INTERNAL_ENTER_EVENT }, self, stateScopeRef.current, system, hooks?.onError);
+		yield* runSpawnEffects(machine, newState, { _tag: INTERNAL_ENTER_EVENT }, self, stateScopeRef.current, system, actorId, hooks?.onError);
 	}
 	return {
 		newState,
 		previousState: currentState,
 		transitioned: true,
 		lifecycleRan: runLifecycle,
-		isFinal: machine.finalStates.has(newState._tag)
+		isFinal: machine.finalStates.has(newState._tag),
+		hasReply: result.hasReply,
+		reply: result.reply,
+		postponed: false
 	};
 });
 /**
@@ -116,9 +146,10 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 *
 * @internal
 */
-const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (machine, state, event, self, stateScope, system, onError) {
+const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (machine, state, event, self, stateScope, system, actorId, onError) {
 	const spawnEffects = findSpawnEffects(machine, state._tag);
 	const ctx = {
+		actorId,
 		state,
 		event,
 		self,
@@ -128,6 +159,7 @@ const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (m
 	const reportError = onError;
 	for (const spawnEffect of spawnEffects) {
 		const effect = spawnEffect.handler({
+			actorId,
 			state,
 			event,
 			self,
@@ -233,4 +265,4 @@ const findSpawnEffects = (machine, stateTag) => {
 	return getIndex(machine).spawn.get(stateTag) ?? [];
 };
 //#endregion
-export { executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler };
+export { executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler, shouldPostpone };

package/{dist-v3 → v3/dist}/internal/utils.d.ts

@@ -1,7 +1,7 @@
 import { ActorSystem } from "../actor.js";
 import { Effect } from "effect";
 
-//#region src-v3/internal/utils.d.ts
+//#region src/internal/utils.d.ts
 /**
  * Extracts _tag from a tagged union member
  */
@@ -23,10 +23,15 @@ type InstanceOf<C> = C extends ((...args: unknown[]) => infer R) ? R : never;
 type TaggedConstructor<T extends {
   readonly _tag: string;
 }> = (args: Omit<T, "_tag">) => T;
+/** Reply tuple returned from transition handlers for ask support */
+interface TransitionReply<State> {
+  readonly state: State;
+  readonly reply: unknown;
+}
 /**
- * Transition handler result - either a new state or Effect producing one
+ * Transition handler result - either a new state, reply tuple, or Effect producing one
  */
-type TransitionResult<State, R> = State | Effect.Effect<State, never, R>;
+type TransitionResult<State, R> = State | TransitionReply<State> | Effect.Effect<State | TransitionReply<State>, never, R>;
 /**
  * Internal event tags used for lifecycle effect contexts.
  * Prefixed with $ to distinguish from user events.
@@ -57,4 +62,4 @@ declare const isEffect: (value: unknown) => value is Effect.Effect<unknown, unkn
  */
 declare const stubSystem: ActorSystem;
 //#endregion
-export { ArgsOf, INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, InstanceOf, TagOf, TaggedConstructor, TransitionResult, getTag, isEffect, stubSystem };
+export { ArgsOf, INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, InstanceOf, TagOf, TaggedConstructor, TransitionReply, TransitionResult, getTag, isEffect, stubSystem };

package/{dist-v3 → v3/dist}/internal/utils.js

@@ -1,5 +1,5 @@
 import { Effect, Stream } from "effect";
-//#region src-v3/internal/utils.ts
+//#region src/internal/utils.ts
 /**
 * Internal event tags used for lifecycle effect contexts.
 * Prefixed with $ to distinguish from user events.
@@ -33,17 +33,13 @@ const isEffect = (value) => typeof value === "object" && value !== null && Effec
 */
 const stubSystem = {
 	spawn: () => Effect.die("spawn not supported in stub system"),
-	restore: () => Effect.die("restore not supported in stub system"),
 	get: () => Effect.die("get not supported in stub system"),
 	stop: () => Effect.die("stop not supported in stub system"),
 	events: Stream.empty,
 	get actors() {
 		return /* @__PURE__ */ new Map();
 	},
-	subscribe: () => () => {},
-	listPersisted: () => Effect.die("listPersisted not supported in stub system"),
-	restoreMany: () => Effect.die("restoreMany not supported in stub system"),
-	restoreAll: () => Effect.die("restoreAll not supported in stub system")
+	subscribe: () => () => {}
 };
 //#endregion
 export { INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, getTag, isEffect, stubSystem };