effect-machine 0.8.0 → 0.10.0

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,8 +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.
 *
@@ -23,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,
@@ -37,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.
@@ -51,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:
@@ -76,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);
@@ -93,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;
@@ -102,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
 	};
 });
 /**
@@ -117,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,
@@ -129,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,6 +264,5 @@ const findTransitions = (input, stateTag, eventTag) => {
 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,6 +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.
@@ -46,6 +45,5 @@ const stubSystem = {
 	restoreMany: () => Effect.die("restoreMany not supported in stub system"),
 	restoreAll: () => Effect.die("restoreAll not supported in stub system")
 };
-
 //#endregion
-export { INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, getTag, isEffect, stubSystem };
+export { INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, getTag, isEffect, stubSystem };