effect-machine 0.9.0 → 0.10.0

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.

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

@@ -1,22 +1,24 @@
+import { EffectHandlers, EffectSlots, EffectsDef, EffectsSchema, GuardHandlers, GuardSlots, GuardsDef, GuardsSchema, MachineContext } from "./slot.js";
 import { TransitionResult } from "./internal/utils.js";
 import { BrandedEvent, BrandedState, TaggedOrConstructor } from "./internal/brands.js";
 import { MachineEventSchema, MachineStateSchema, VariantsUnion } from "./schema.js";
 import { PersistenceConfig, PersistentMachine } from "./persistence/persistent-machine.js";
 import { DuplicateActorError } from "./errors.js";
-import { EffectHandlers, EffectSlots, EffectsDef, EffectsSchema, GuardHandlers, GuardSlots, GuardsDef, GuardsSchema, MachineContext } from "./slot.js";
 import { findTransitions } from "./internal/transition.js";
 import { ActorRef, ActorSystem } from "./actor.js";
-import { Cause, Context, Effect, Schedule, Schema, Scope } from "effect";
+import { Cause, Context, Duration, Effect, Schedule, Schema, Scope } from "effect";
 
-//#region src-v3/machine.d.ts
+//#region src/machine.d.ts
 declare namespace machine_d_exports {
-  export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, PersistenceConfig, PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, Transition, TransitionHandler, findTransitions, make, spawn };
+  export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, PersistenceConfig, PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, make, spawn };
 }
 /**
  * Self reference for sending events back to the machine
  */
 interface MachineRef<Event> {
   readonly send: (event: Event) => Effect.Effect<void>;
+  /** Fire-and-forget alias for send (OTP gen_server:cast). */
+  readonly cast: (event: Event) => Effect.Effect<void>;
   readonly spawn: <S2 extends {
     readonly _tag: string;
   }, E2 extends {
@@ -36,6 +38,7 @@ interface HandlerContext<State, Event, GD extends GuardsDef, ED extends EffectsD
  * Handler context passed to state effect handlers (onEnter, spawn, background)
  */
 interface StateHandlerContext<State, Event, ED extends EffectsDef> {
+  readonly actorId: string;
   readonly state: State;
   readonly event: Event;
   readonly self: MachineRef<Event>;
@@ -80,6 +83,23 @@ interface PersistOptions {
   readonly journalEvents: boolean;
   readonly machineType?: string;
 }
+interface TaskOptions<State, Event, ED extends EffectsDef, A, E1, ES, EF> {
+  readonly onSuccess: (value: A, ctx: StateHandlerContext<State, Event, ED>) => ES;
+  readonly onFailure?: (cause: Cause.Cause<E1>, ctx: StateHandlerContext<State, Event, ED>) => EF;
+  readonly name?: string;
+}
+/**
+ * Configuration for `.timeout()` — gen_statem-style state timeouts.
+ *
+ * Entering the state starts a timer. Leaving cancels it.
+ * `.reenter()` restarts the timer with fresh state values.
+ */
+interface TimeoutConfig<State, Event> {
+  /** Duration before firing. Static or derived from current state. */
+  readonly duration: Duration.DurationInput | ((state: State) => Duration.DurationInput);
+  /** Event to send when the timer fires. Static or derived from current state. */
+  readonly event: Event | ((state: State) => Event);
+}
 type IsAny<T> = 0 extends 1 & T ? true : false;
 type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) : false;
 type NormalizeR<T> = IsAny<T> extends true ? T : IsUnknown<T> extends true ? never : T;
@@ -146,6 +166,11 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
   /** @internal */
   readonly _finalStates: Set<string>;
   /** @internal */
+  readonly _postponeRules: Array<{
+    readonly stateTag: string;
+    readonly eventTag: string;
+  }>;
+  /** @internal */
   readonly _guardsSchema?: GuardsSchema<GD>;
   /** @internal */
   readonly _effectsSchema?: EffectsSchema<EFD>;
@@ -169,10 +194,18 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
   get spawnEffects(): ReadonlyArray<SpawnEffect<State, Event, EFD, R>>;
   get backgroundEffects(): ReadonlyArray<BackgroundEffect<State, Event, EFD, R>>;
   get finalStates(): ReadonlySet<string>;
+  get postponeRules(): ReadonlyArray<{
+    readonly stateTag: string;
+    readonly eventTag: string;
+  }>;
   get guardsSchema(): GuardsSchema<GD> | undefined;
   get effectsSchema(): EffectsSchema<EFD> | undefined;
   /** @internal */
   constructor(initial: State, stateSchema?: Schema.Schema<State, unknown, never>, eventSchema?: Schema.Schema<Event, unknown, never>, guardsSchema?: GuardsSchema<GD>, effectsSchema?: EffectsSchema<EFD>);
+  from<NS extends VariantsUnion<_SD> & BrandedState, R1>(state: TaggedOrConstructor<NS>, build: (scope: TransitionScope<State, Event, R, _SD, _ED, GD, EFD, NS>) => R1): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  from<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>, R1>(states: NS, build: (scope: TransitionScope<State, Event, R, _SD, _ED, GD, EFD, NS[number] extends TaggedOrConstructor<infer S extends VariantsUnion<_SD> & BrandedState> ? S : never>) => R1): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /** @internal */
+  scopeTransition<NS extends VariantsUnion<_SD> & BrandedState, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(states: ReadonlyArray<TaggedOrConstructor<NS>>, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS, NE, RS, GD, EFD, never>, reenter: boolean): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /** Register transition for a single state */
   on<NS extends VariantsUnion<_SD> & BrandedState, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS, NE, RS, GD, EFD, never>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /** Register transition for multiple states (handler receives union of state types) */
@@ -219,10 +252,29 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
    * State-scoped task that runs on entry and sends success/failure events.
    * Interrupts do not emit failure events.
    */
-  task<NS extends VariantsUnion<_SD> & BrandedState, A, E1, ES extends VariantsUnion<_ED> & BrandedEvent, EF extends VariantsUnion<_ED> & BrandedEvent>(state: TaggedOrConstructor<NS>, run: (ctx: StateHandlerContext<NS, VariantsUnion<_ED> & BrandedEvent, EFD>) => Effect.Effect<A, E1, Scope.Scope>, options: {
-    readonly onSuccess: (value: A, ctx: StateHandlerContext<NS, VariantsUnion<_ED> & BrandedEvent, EFD>) => ES;
-    readonly onFailure?: (cause: Cause.Cause<E1>, ctx: StateHandlerContext<NS, VariantsUnion<_ED> & BrandedEvent, EFD>) => EF;
-  }): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  task<NS extends VariantsUnion<_SD> & BrandedState, A, E1, ES extends VariantsUnion<_ED> & BrandedEvent, EF extends VariantsUnion<_ED> & BrandedEvent>(state: TaggedOrConstructor<NS>, run: (ctx: StateHandlerContext<NS, VariantsUnion<_ED> & BrandedEvent, EFD>) => Effect.Effect<A, E1, Scope.Scope>, options: TaskOptions<NS, VariantsUnion<_ED> & BrandedEvent, EFD, A, E1, ES, EF>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /**
+   * State timeout — gen_statem's `state_timeout`.
+   *
+   * Entering the state starts a timer. Leaving cancels it (via state scope).
+   * `.reenter()` restarts the timer with fresh state values.
+   * Compiles to `.task()` internally — preserves `@machine.task` inspection events.
+   *
+   * @example
+   * ```ts
+   * machine
+   *   .timeout(State.Loading, {
+   *     duration: Duration.seconds(30),
+   *     event: Event.Timeout,
+   *   })
+   *   // Dynamic duration from state
+   *   .timeout(State.Retrying, {
+   *     duration: (state) => Duration.seconds(state.backoff),
+   *     event: Event.GiveUp,
+   *   })
+   * ```
+   */
+  timeout<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, config: TimeoutConfig<NS, VariantsUnion<_ED> & BrandedEvent>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /**
    * Machine-lifetime effect that is forked on actor spawn and runs until the actor stops.
    * Use effect slots defined via `Slot.Effects` for the actual work.
@@ -244,6 +296,24 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
    * ```
    */
   background(handler: StateEffectHandler<State, Event, EFD, Scope.Scope>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /**
+   * Postpone events — gen_statem's event postpone.
+   *
+   * When a matching event arrives in the given state, it is buffered instead of
+   * processed. After the next state transition (tag change), all buffered events
+   * are drained through the loop in FIFO order.
+   *
+   * Reply-bearing events (from `call`/`ask`) in the postpone buffer are settled
+   * with `ActorStoppedError` on stop/interrupt/final-state.
+   *
+   * @example
+   * ```ts
+   * machine
+   *   .postpone(State.Connecting, Event.Data)           // single event
+   *   .postpone(State.Connecting, [Event.Data, Event.Cmd]) // multiple events
+   * ```
+   */
+  postpone<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, events: TaggedOrConstructor<VariantsUnion<_ED> & BrandedEvent> | ReadonlyArray<TaggedOrConstructor<VariantsUnion<_ED> & BrandedEvent>>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   final<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /**
    * Finalize the machine. Returns a `BuiltMachine` — the only type accepted by `Machine.spawn`.
@@ -260,6 +330,13 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
   }, R>;
   static make<SD extends Record<string, Schema.Struct.Fields>, ED extends Record<string, Schema.Struct.Fields>, S extends BrandedState, E extends BrandedEvent, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(config: MakeConfig<SD, ED, S, E, GD, EFD>): Machine<S, E, never, SD, ED, GD, EFD>;
 }
+declare class TransitionScope<State, Event, R, _SD extends Record<string, Schema.Struct.Fields>, _ED extends Record<string, Schema.Struct.Fields>, GD extends GuardsDef, EFD extends EffectsDef, SelectedState extends VariantsUnion<_SD> & BrandedState> {
+  private readonly machine;
+  private readonly states;
+  constructor(machine: Machine<State, Event, R, _SD, _ED, GD, EFD>, states: ReadonlyArray<TaggedOrConstructor<SelectedState>>);
+  on<NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(event: TaggedOrConstructor<NE>, handler: TransitionHandler<SelectedState, NE, RS, GD, EFD, never>): TransitionScope<State, Event, R, _SD, _ED, GD, EFD, SelectedState>;
+  reenter<NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(event: TaggedOrConstructor<NE>, handler: TransitionHandler<SelectedState, NE, RS, GD, EFD, never>): TransitionScope<State, Event, R, _SD, _ED, GD, EFD, SelectedState>;
+}
 declare const make: typeof Machine.make;
 declare const spawn: {
   <S extends {
@@ -274,4 +351,4 @@ declare const spawn: {
   }, R>(machine: BuiltMachine<S, E, R>, id: string): Effect.Effect<ActorRef<S, E>, never, R>;
 };
 //#endregion
-export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, type PersistenceConfig, type PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, Transition, TransitionHandler, findTransitions, machine_d_exports, make, spawn };
+export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, type PersistenceConfig, type PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, machine_d_exports, make, spawn };