effect-machine 0.11.0 → 0.12.0

package/dist/internal/runtime.js

@@ -0,0 +1,248 @@
+import { INTERNAL_INIT_EVENT } from "./utils.js";
+import { NoReplyError } from "../errors.js";
+import { processEventCore, runSpawnEffects, shouldPostpone } from "./transition.js";
+import { ActorSystem } from "../actor.js";
+import { Deferred, Effect, Exit, Fiber, Queue, Ref, Schema, Scope, SubscriptionRef } from "effect";
+//#region src/internal/runtime.ts
+/**
+* Shared runtime kernel for machine event processing.
+*
+* Provides a single-queue event loop with:
+* - Sequential event processing (no split-mailbox race)
+* - Postpone buffer with drain-on-state-change (gen_statem)
+* - Background effect lifecycle
+* - Spawn effect lifecycle (per-state scope)
+* - Final state detection → stop
+* - Reply settlement (call/ask Deferreds)
+* - Reply schema validation
+*
+* Used by entity-machine. Local actor (actor.ts) has its own event loop
+* with additional concerns (inspection, listeners, subscription ref, etc.)
+* that will be migrated to use this kernel in a future refactor.
+*
+* @internal
+*/
+/**
+* Create a runtime for a machine. Returns a handle for sending events
+* and querying state. The runtime owns:
+* - Single event queue (all events serialized)
+* - Event loop fiber
+* - Postpone buffer
+* - Background effects
+* - State scope (spawn effects)
+* - Final state detection
+*
+* @internal
+*/
+const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (machine, system, config) {
+	const { actorId, hooks } = config;
+	const stateRef = yield* SubscriptionRef.make(machine.initial);
+	const stoppedRef = yield* Ref.make(false);
+	const eventQueue = yield* config.queueFactory ?? Queue.unbounded();
+	const deferredReplyRef = { current: void 0 };
+	const selfSend = Effect.fn("effect-machine.runtime.self.send")(function* (event) {
+		if (!(yield* Ref.get(stoppedRef))) yield* Queue.offer(eventQueue, {
+			_tag: "send",
+			event
+		});
+	});
+	const self = {
+		send: selfSend,
+		cast: selfSend,
+		spawn: (childId, childMachine) => system.spawn(`${actorId}/${childId}`, childMachine).pipe(Effect.provideService(ActorSystem, system)),
+		reply: (value) => Effect.sync(() => {
+			const deferred = deferredReplyRef.current;
+			if (deferred !== void 0) {
+				deferredReplyRef.current = void 0;
+				Effect.runFork(Deferred.succeed(deferred, value));
+				return true;
+			}
+			return false;
+		})
+	};
+	const stateScopeRef = { current: yield* Scope.make() };
+	const backgroundFibers = [];
+	const initEvent = { _tag: INTERNAL_INIT_EVENT };
+	const ctx = {
+		actorId,
+		state: machine.initial,
+		event: initEvent,
+		self,
+		system
+	};
+	const { effects: effectSlots } = machine._slots;
+	for (const bg of machine.backgroundEffects) {
+		const fiber = yield* Effect.forkDetach(bg.handler({
+			actorId,
+			state: machine.initial,
+			event: initEvent,
+			self,
+			effects: effectSlots,
+			system
+		}).pipe(Effect.provideService(machine.Context, ctx)));
+		backgroundFibers.push(fiber);
+	}
+	yield* runSpawnEffects(machine, machine.initial, initEvent, self, stateScopeRef.current, system, actorId, hooks?.onError);
+	if (machine.finalStates.has(machine.initial._tag)) {
+		yield* Ref.set(stoppedRef, true);
+		yield* Scope.close(stateScopeRef.current, Exit.void);
+		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+		return makeHandle(stateRef, stoppedRef, eventQueue, machine);
+	}
+	const loopFiber = yield* Effect.forkDetach(runtimeEventLoop(machine, stateRef, eventQueue, stoppedRef, self, backgroundFibers, stateScopeRef, actorId, system, hooks, deferredReplyRef));
+	const stop = Effect.gen(function* () {
+		if (yield* Ref.get(stoppedRef)) return;
+		yield* Ref.set(stoppedRef, true);
+		yield* Fiber.interrupt(loopFiber);
+		yield* Scope.close(stateScopeRef.current, Exit.void);
+		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+	}).pipe(Effect.asVoid);
+	yield* Effect.addFinalizer(() => stop);
+	return {
+		...makeHandle(stateRef, stoppedRef, eventQueue, machine),
+		stop
+	};
+});
+/**
+* Build the runtime handle (send/ask/getState/isStopped).
+* Shared between initial-final and normal paths.
+*/
+const makeHandle = (stateRef, stoppedRef, eventQueue, _machine) => ({
+	send: (event) => Effect.gen(function* () {
+		if (!(yield* Ref.get(stoppedRef))) yield* Queue.offer(eventQueue, {
+			_tag: "send",
+			event
+		});
+	}),
+	sendWait: (event) => Effect.gen(function* () {
+		if (!(yield* Ref.get(stoppedRef))) {
+			const done = yield* Deferred.make();
+			yield* Queue.offer(eventQueue, {
+				_tag: "sendWait",
+				event,
+				done
+			});
+			yield* Deferred.await(done);
+		}
+	}),
+	ask: (event) => Effect.gen(function* () {
+		if (yield* Ref.get(stoppedRef)) return yield* new NoReplyError({
+			actorId: "stopped",
+			eventTag: event._tag
+		});
+		const reply = yield* Deferred.make();
+		yield* Queue.offer(eventQueue, {
+			_tag: "ask",
+			event,
+			reply
+		});
+		return yield* Deferred.await(reply);
+	}),
+	getState: SubscriptionRef.get(stateRef),
+	stateRef,
+	isStopped: Ref.get(stoppedRef),
+	stop: Effect.void
+});
+const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function* (machine, stateRef, eventQueue, stoppedRef, self, backgroundFibers, stateScopeRef, actorId, system, hooks, deferredReplyRef) {
+	const postponed = [];
+	const hasPostponeRules = machine.postponeRules.length > 0;
+	const processQueued = Effect.fn("effect-machine.runtime.processQueued")(function* (queued) {
+		const event = queued.event;
+		const currentState = yield* SubscriptionRef.get(stateRef);
+		if (hasPostponeRules && shouldPostpone(machine, currentState._tag, event._tag)) {
+			postponed.push({
+				_tag: "send",
+				event
+			});
+			if (queued._tag === "sendWait") yield* Deferred.succeed(queued.done, void 0);
+			return {
+				shouldStop: false,
+				stateChanged: false
+			};
+		}
+		const result = yield* processEventCore(machine, currentState, event, self, stateScopeRef, system, actorId, hooks);
+		if (result.transitioned) yield* SubscriptionRef.set(stateRef, result.newState);
+		switch (queued._tag) {
+			case "sendWait":
+				yield* Deferred.succeed(queued.done, void 0);
+				break;
+			case "ask":
+				if (result.hasReply) {
+					const replySchema = machine._replySchemas?.get(event._tag);
+					if (replySchema !== void 0) {
+						let decoded;
+						try {
+							decoded = Schema.decodeUnknownSync(replySchema)(result.reply);
+						} catch (decodeError) {
+							yield* Deferred.die(queued.reply, decodeError);
+							return yield* Effect.die(decodeError);
+						}
+						yield* Deferred.succeed(queued.reply, decoded);
+					} else yield* Deferred.succeed(queued.reply, result.reply);
+				} else if (result.deferReply && deferredReplyRef !== void 0) deferredReplyRef.current = queued.reply;
+				else yield* Deferred.fail(queued.reply, new NoReplyError({
+					actorId,
+					eventTag: event._tag
+				}));
+				break;
+		}
+		return {
+			shouldStop: result.isFinal && result.lifecycleRan,
+			stateChanged: result.lifecycleRan
+		};
+	});
+	while (true) {
+		const queued = yield* Queue.take(eventQueue);
+		const { shouldStop, stateChanged } = yield* processQueued(queued).pipe(Effect.catchCause((cause) => {
+			if (queued._tag === "sendWait") Effect.runFork(Deferred.failCause(queued.done, cause));
+			else if (queued._tag === "ask") Effect.runFork(Deferred.die(queued.reply, cause));
+			return Effect.failCause(cause);
+		}));
+		if (shouldStop) {
+			yield* Ref.set(stoppedRef, true);
+			settlePostponed(postponed, actorId);
+			const remaining = yield* Queue.takeAll(eventQueue);
+			for (const entry of remaining) if (entry._tag === "sendWait") Effect.runFork(Deferred.succeed(entry.done, void 0));
+			else if (entry._tag === "ask") Effect.runFork(Deferred.fail(entry.reply, new NoReplyError({
+				actorId,
+				eventTag: entry.event._tag
+			})));
+			yield* Scope.close(stateScopeRef.current, Exit.void);
+			yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+			return;
+		}
+		let drainTriggered = stateChanged;
+		while (drainTriggered && postponed.length > 0) {
+			drainTriggered = false;
+			const drained = postponed.splice(0);
+			for (const entry of drained) {
+				const drain = yield* processQueued(entry);
+				if (drain.shouldStop) {
+					yield* Ref.set(stoppedRef, true);
+					settlePostponed(postponed, actorId);
+					const remaining2 = yield* Queue.takeAll(eventQueue);
+					for (const r of remaining2) if (r._tag === "sendWait") Effect.runFork(Deferred.succeed(r.done, void 0));
+					else if (r._tag === "ask") Effect.runFork(Deferred.fail(r.reply, new NoReplyError({
+						actorId,
+						eventTag: r.event._tag
+					})));
+					yield* Scope.close(stateScopeRef.current, Exit.void);
+					yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+					return;
+				}
+				if (drain.stateChanged) drainTriggered = true;
+			}
+		}
+	}
+});
+/** Settle all pending Deferreds in the postpone buffer on shutdown. */
+const settlePostponed = (postponed, actorId) => {
+	for (const entry of postponed) if (entry._tag === "ask") Effect.runFork(Deferred.fail(entry.reply, new NoReplyError({
+		actorId,
+		eventTag: entry.event._tag
+	})));
+	else if (entry._tag === "sendWait") Effect.runFork(Deferred.succeed(entry.done, void 0));
+	postponed.length = 0;
+};
+//#endregion
+export { createRuntime };

package/dist/internal/transition.d.ts

@@ -32,6 +32,7 @@ declare const runTransitionHandler: <S extends {
 }, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, transition: Transition<S, E, GD, EFD, R>, state: S, event: E, self: MachineRef<E>, system: ActorSystem, actorId: string) => Effect.Effect<{
   newState: S;
   hasReply: boolean;
+  deferReply: boolean;
   reply: unknown;
 }, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
@@ -54,6 +55,7 @@ declare const executeTransition: <S extends {
   transitioned: boolean;
   reenter: boolean;
   hasReply: boolean;
+  deferReply: boolean;
   reply: unknown;
 }, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
@@ -92,6 +94,8 @@ interface ProcessEventResult<S> {
   readonly isFinal: boolean;
   /** Whether the handler provided a reply (structural, not value-based) */
   readonly hasReply: boolean;
+  /** Whether the handler deferred the reply to a spawn handler (Machine.deferReply) */
+  readonly deferReply: boolean;
   /** Domain reply value from handler (used by ask). Only meaningful when hasReply is true. */
   readonly reply?: unknown;
   /** Whether the event was postponed (buffered for retry after next state change) */
@@ -131,6 +135,7 @@ declare const processEventCore: <S extends {
   lifecycleRan: boolean;
   isFinal: boolean;
   hasReply: boolean;
+  deferReply: boolean;
   reply: unknown;
   postponed: boolean;
 }, never, Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;

package/dist/internal/transition.js

@@ -1,4 +1,4 @@
-import { INTERNAL_ENTER_EVENT, isEffect } from "./utils.js";
+import { INTERNAL_ENTER_EVENT, isDeferReplyResult, isEffect, isReplyResult } from "./utils.js";
 import { BuiltMachine } from "../machine.js";
 import { Cause, Effect, Exit, Scope } from "effect";
 //#region src/internal/transition.ts
@@ -39,14 +39,22 @@ const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(fu
 	};
 	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 {
+	if (isReplyResult(resolved)) return {
 		newState: resolved.state,
 		hasReply: true,
+		deferReply: false,
 		reply: resolved.reply
 	};
+	if (isDeferReplyResult(resolved)) return {
+		newState: resolved.state,
+		hasReply: false,
+		deferReply: true,
+		reply: void 0
+	};
 	return {
 		newState: resolved,
 		hasReply: false,
+		deferReply: false,
 		reply: void 0
 	};
 });
@@ -68,14 +76,16 @@ const executeTransition = Effect.fn("effect-machine.executeTransition")(function
 		transitioned: false,
 		reenter: false,
 		hasReply: false,
+		deferReply: false,
 		reply: void 0
 	};
-	const { newState, hasReply, reply } = yield* runTransitionHandler(machine, transition, currentState, event, self, system, actorId);
+	const { newState, hasReply, deferReply, reply } = yield* runTransitionHandler(machine, transition, currentState, event, self, system, actorId);
 	return {
 		newState,
 		transitioned: true,
 		reenter: transition.reenter === true,
 		hasReply,
+		deferReply,
 		reply
 	};
 });
@@ -118,6 +128,7 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 		lifecycleRan: false,
 		isFinal: false,
 		hasReply: false,
+		deferReply: false,
 		reply: void 0,
 		postponed: false
 	};
@@ -137,6 +148,7 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 		lifecycleRan: runLifecycle,
 		isFinal: machine.finalStates.has(newState._tag),
 		hasReply: result.hasReply,
+		deferReply: result.deferReply,
 		reply: result.reply,
 		postponed: false
 	};

package/dist/internal/utils.d.ts

@@ -23,15 +23,51 @@ type InstanceOf<C> = C extends ((...args: unknown[]) => infer R) ? R : never;
 type TaggedConstructor<T extends {
   readonly _tag: string;
 }> = (args: Omit<T, "_tag">) => T;
+declare const ReplyResultSymbol: unique symbol;
+type ReplyResultSymbol = typeof ReplyResultSymbol;
 /**
- * Transition handler result - either a new state or Effect producing one
+ * Branded reply result from a transition handler.
+ * Created via `Machine.reply(state, value)`.
  */
-/** Reply tuple returned from transition handlers for ask support */
-interface TransitionReply<State> {
+interface ReplyResult<State, Reply> {
   readonly state: State;
-  readonly reply: unknown;
+  readonly reply: Reply;
+  readonly [ReplyResultSymbol]: true;
 }
-type TransitionResult<State, R> = State | TransitionReply<State> | Effect.Effect<State | TransitionReply<State>, never, R>;
+/**
+ * Create a reply result for ask-bearing event handlers.
+ */
+declare const makeReply: <State, Reply>(state: State, reply: Reply) => ReplyResult<State, Reply>;
+/**
+ * Type guard for ReplyResult (symbol-based, replaces duck-typing).
+ */
+declare const isReplyResult: (value: unknown) => value is ReplyResult<unknown, unknown>;
+declare const DeferReplySymbol: unique symbol;
+type DeferReplySymbol = typeof DeferReplySymbol;
+/**
+ * Branded deferred reply result from a transition handler.
+ * Signals that the reply will be settled later by `self.reply()` in a spawn handler.
+ * Created via `Machine.deferReply(state)`.
+ */
+interface DeferReplyResult<State> {
+  readonly state: State;
+  readonly [DeferReplySymbol]: true;
+}
+/**
+ * Create a deferred reply result. Handler returns this to signal
+ * "spawn handler will call self.reply(value) later".
+ */
+declare const makeDeferReply: <State>(state: State) => DeferReplyResult<State>;
+/**
+ * Type guard for DeferReplyResult.
+ */
+declare const isDeferReplyResult: (value: unknown) => value is DeferReplyResult<unknown>;
+/**
+ * Transition handler result.
+ * - When Reply is `never`: handler returns plain State (no reply allowed)
+ * - When Reply is concrete: handler must return ReplyResult via Machine.reply()
+ */
+type TransitionResult<State, R, Reply = never> = [Reply] extends [never] ? State | Effect.Effect<State, never, R> : ReplyResult<State, Reply> | DeferReplyResult<State> | Effect.Effect<ReplyResult<State, Reply> | DeferReplyResult<State>, never, R>;
 /**
  * Internal event tags used for lifecycle effect contexts.
  * Prefixed with $ to distinguish from user events.
@@ -62,4 +98,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, TransitionReply, TransitionResult, getTag, isEffect, stubSystem };
+export { ArgsOf, DeferReplyResult, DeferReplySymbol, INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, InstanceOf, ReplyResult, ReplyResultSymbol, TagOf, TaggedConstructor, TransitionResult, getTag, isDeferReplyResult, isEffect, isReplyResult, makeDeferReply, makeReply, stubSystem };

package/dist/internal/utils.js

@@ -4,6 +4,32 @@ import { Effect, Stream } from "effect";
 * Internal utilities for effect-machine.
 * @internal
 */
+const ReplyResultSymbol = Symbol.for("effect-machine/ReplyResult");
+/**
+* Create a reply result for ask-bearing event handlers.
+*/
+const makeReply = (state, reply) => ({
+	state,
+	reply,
+	[ReplyResultSymbol]: true
+});
+/**
+* Type guard for ReplyResult (symbol-based, replaces duck-typing).
+*/
+const isReplyResult = (value) => value !== null && typeof value === "object" && ReplyResultSymbol in value;
+const DeferReplySymbol = Symbol.for("effect-machine/DeferReply");
+/**
+* Create a deferred reply result. Handler returns this to signal
+* "spawn handler will call self.reply(value) later".
+*/
+const makeDeferReply = (state) => ({
+	state,
+	[DeferReplySymbol]: true
+});
+/**
+* Type guard for DeferReplyResult.
+*/
+const isDeferReplyResult = (value) => value !== null && typeof value === "object" && DeferReplySymbol in value;
 /**
 * Internal event tags used for lifecycle effect contexts.
 * Prefixed with $ to distinguish from user events.
@@ -46,4 +72,4 @@ const stubSystem = {
 	subscribe: () => () => {}
 };
 //#endregion
-export { INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, getTag, isEffect, stubSystem };
+export { INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, getTag, isDeferReplyResult, isEffect, isReplyResult, makeDeferReply, makeReply, stubSystem };

package/dist/machine.d.ts

@@ -1,6 +1,6 @@
 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 { DeferReplyResult, ReplyResult, TransitionResult } from "./internal/utils.js";
+import { BrandedEvent, BrandedState, ExtractReply, TaggedOrConstructor } from "./internal/brands.js";
 import { MachineEventSchema, MachineStateSchema, VariantsUnion } from "./schema.js";
 import { DuplicateActorError } from "./errors.js";
 import { findTransitions } from "./internal/transition.js";
@@ -9,7 +9,7 @@ import { Cause, Duration, Effect, Schema, Scope, ServiceMap } from "effect";
 
 //#region src/machine.d.ts
 declare namespace machine_d_exports {
-  export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, make, replay, spawn };
+  export { BackgroundEffect, BuiltMachine, DeferReplyResult, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, ReplyResult, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, make, replay, reply, spawn };
 }
 /**
  * Self reference for sending events back to the machine
@@ -23,6 +23,12 @@ interface MachineRef<Event> {
   }, E2 extends {
     readonly _tag: string;
   }, R2>(id: string, machine: BuiltMachine<S2, E2, R2>) => Effect.Effect<ActorRef<S2, E2>, DuplicateActorError, R2>;
+  /**
+   * Settle a deferred reply from a spawn handler.
+   * Only usable when the transition handler returned `Machine.deferReply(state)`.
+   * Returns true if a pending reply was settled, false if none was pending.
+   */
+  readonly reply: (value: unknown) => Effect.Effect<boolean>;
 }
 /**
  * Handler context passed to transition handlers
@@ -45,9 +51,11 @@ interface StateHandlerContext<State, Event, ED extends EffectsDef> {
   readonly system: ActorSystem;
 }
 /**
- * Transition handler function
+ * Transition handler function.
+ * When Reply is concrete (event has a reply schema), handler must return Machine.reply().
+ * When Reply is never, handler returns plain state.
  */
-type TransitionHandler<S, E, NewState, GD extends GuardsDef, ED extends EffectsDef, R> = (ctx: HandlerContext<S, E, GD, ED>) => TransitionResult<NewState, R>;
+type TransitionHandler<S, E, NewState, GD extends GuardsDef, ED extends EffectsDef, R, Reply = never> = (ctx: HandlerContext<S, E, GD, ED>) => TransitionResult<NewState, R, Reply>;
 /**
  * State effect handler function
  */
@@ -171,6 +179,8 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
   };
   readonly stateSchema?: Schema.Schema<State>;
   readonly eventSchema?: Schema.Schema<Event>;
+  /** @internal */
+  readonly _replySchemas: ReadonlyMap<string, Schema.Decoder<unknown>>;
   /**
    * Context tag for accessing machine state/event/self in slot handlers.
    * Uses shared module-level tag for all machines.
@@ -186,24 +196,25 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
   }>;
   get guardsSchema(): GuardsSchema<GD> | undefined;
   get effectsSchema(): EffectsSchema<EFD> | undefined;
+  get replySchemas(): ReadonlyMap<string, Schema.Decoder<unknown>>;
   /** @internal */
   constructor(initial: State, stateSchema?: Schema.Schema<State>, eventSchema?: Schema.Schema<Event>, 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>;
+  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, ExtractReply<NE>>, 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>;
+  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, ExtractReply<NE>>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /** Register transition for multiple states (handler receives union of state types) */
-  on<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(states: NS, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS[number] extends TaggedOrConstructor<infer S> ? S : never, NE, RS, GD, EFD, never>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  on<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(states: NS, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS[number] extends TaggedOrConstructor<infer S> ? S : never, NE, RS, GD, EFD, never, ExtractReply<NE>>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /**
    * Like `on()`, but forces onEnter/spawn to run even when transitioning to the same state tag.
    * Use this to restart timers, re-run spawned effects, or reset state-scoped effects.
    */
   /** Single state */
-  reenter<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>;
+  reenter<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, ExtractReply<NE>>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /** Multiple states */
-  reenter<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(states: NS, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS[number] extends TaggedOrConstructor<infer S> ? S : never, NE, RS, GD, EFD, never>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  reenter<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(states: NS, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS[number] extends TaggedOrConstructor<infer S> ? S : never, NE, RS, GD, EFD, never, ExtractReply<NE>>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /**
    * Register a wildcard transition that fires from any state when no specific transition matches.
    * Specific `.on()` transitions always take priority over `.onAny()`.
@@ -314,8 +325,8 @@ declare class TransitionScope<State, Event, R, _SD extends Record<string, Schema
   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>;
+  on<NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(event: TaggedOrConstructor<NE>, handler: TransitionHandler<SelectedState, NE, RS, GD, EFD, never, ExtractReply<NE>>): 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, ExtractReply<NE>>): TransitionScope<State, Event, R, _SD, _ED, GD, EFD, SelectedState>;
 }
 declare const make: typeof Machine.make;
 /**
@@ -346,5 +357,7 @@ declare const replay: <S extends {
 }, R>(machine: BuiltMachine<S, E, R>, events: ReadonlyArray<E>, options?: {
   from?: S;
 }) => Effect.Effect<S, never, R>;
+declare const reply: <State, Reply>(state: State, reply: Reply) => ReplyResult<State, Reply>;
+declare const deferReply: <State>(state: State) => DeferReplyResult<State>;
 //#endregion
-export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, machine_d_exports, make, replay, spawn };
+export { BackgroundEffect, BuiltMachine, type DeferReplyResult, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, type ReplyResult, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, machine_d_exports, make, replay, reply, spawn };

package/dist/machine.js

@@ -1,6 +1,6 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
 import { Inspector } from "./inspection.js";
-import { getTag, stubSystem } from "./internal/utils.js";
+import { getTag, makeDeferReply, makeReply, stubSystem } from "./internal/utils.js";
 import { ProvisionValidationError, SlotProvisionError } from "./errors.js";
 import { emitWithTimestamp } from "./internal/inspection.js";
 import { MachineContextTag } from "./slot.js";
@@ -11,9 +11,11 @@ import { Cause, Effect, Exit, Option, Scope } from "effect";
 var machine_exports = /* @__PURE__ */ __exportAll({
 	BuiltMachine: () => BuiltMachine,
 	Machine: () => Machine,
+	deferReply: () => deferReply,
 	findTransitions: () => findTransitions,
 	make: () => make,
 	replay: () => replay,
+	reply: () => reply,
 	spawn: () => spawn
 });
 const emitTaskInspection = (input) => Effect.flatMap(Effect.serviceOption(Inspector), (inspector) => Option.isNone(inspector) ? Effect.void : emitWithTimestamp(inspector.value, (timestamp) => ({
@@ -69,6 +71,7 @@ var Machine = class Machine {
 	/** @internal */ _slots;
 	stateSchema;
 	eventSchema;
+	/** @internal */ _replySchemas;
 	/**
 	* Context tag for accessing machine state/event/self in slot handlers.
 	* Uses shared module-level tag for all machines.
@@ -95,6 +98,9 @@ var Machine = class Machine {
 	get effectsSchema() {
 		return this._effectsSchema;
 	}
+	get replySchemas() {
+		return this._replySchemas;
+	}
 	/** @internal */
 	constructor(initial, stateSchema, eventSchema, guardsSchema, effectsSchema) {
 		this.initial = initial;
@@ -105,6 +111,7 @@ var Machine = class Machine {
 		this._postponeRules = [];
 		this._guardsSchema = guardsSchema;
 		this._effectsSchema = effectsSchema;
+		this._replySchemas = eventSchema?._replySchemas ?? /* @__PURE__ */ new Map();
 		this._guardHandlers = /* @__PURE__ */ new Map();
 		this._effectHandlers = /* @__PURE__ */ new Map();
 		this.stateSchema = stateSchema;
@@ -375,6 +382,7 @@ var Machine = class Machine {
 			result._spawnEffects = [...this._spawnEffects];
 			result._backgroundEffects = [...this._backgroundEffects];
 			result._postponeRules = [...this._postponeRules];
+			result._replySchemas = this._replySchemas;
 			const anyHandlers = handlers;
 			if (this._guardsSchema !== void 0) for (const name of Object.keys(this._guardsSchema.definitions)) result._guardHandlers.set(name, anyHandlers[name]);
 			if (this._effectsSchema !== void 0) for (const name of Object.keys(this._effectsSchema.definitions)) result._effectHandlers.set(name, anyHandlers[name]);
@@ -430,7 +438,8 @@ const replay = Effect.fn("effect-machine.replay")(function* (built, events, opti
 	const self = {
 		send: dummySend,
 		cast: dummySend,
-		spawn: () => Effect.die("spawn not supported in replay")
+		spawn: () => Effect.die("spawn not supported in replay"),
+		reply: () => Effect.succeed(false)
 	};
 	for (const event of events) {
 		if (machine.finalStates.has(state._tag)) break;
@@ -464,5 +473,7 @@ const replay = Effect.fn("effect-machine.replay")(function* (built, events, opti
 	}
 	return state;
 });
+const reply = makeReply;
+const deferReply = makeDeferReply;
 //#endregion
-export { BuiltMachine, Machine, findTransitions, machine_exports, make, replay, spawn };
+export { BuiltMachine, Machine, deferReply, findTransitions, machine_exports, make, replay, reply, spawn };