effect-machine 0.11.0 → 0.13.0

package/v3/dist/internal/transition.js

@@ -1,5 +1,4 @@
-import { INTERNAL_ENTER_EVENT, isEffect } from "./utils.js";
-import { BuiltMachine } from "../machine.js";
+import { INTERNAL_ENTER_EVENT, isDeferReplyResult, isEffect, isReplyResult } from "./utils.js";
 import { Cause, Effect, Exit, Scope } from "effect";
 //#region src/internal/transition.ts
 /**
@@ -39,14 +38,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 +75,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 +127,7 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 		lifecycleRan: false,
 		isFinal: false,
 		hasReply: false,
+		deferReply: false,
 		reply: void 0,
 		postponed: false
 	};
@@ -128,7 +138,7 @@ 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, actorId, hooks?.onError);
+		yield* runSpawnEffects(machine, newState, { _tag: INTERNAL_ENTER_EVENT }, self, stateScopeRef.current, system, actorId, hooks?.onError, hooks?.onSpawnDefect);
 	}
 	return {
 		newState,
@@ -137,6 +147,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
 	};
@@ -146,7 +157,7 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 *
 * @internal
 */
-const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (machine, state, event, self, stateScope, system, actorId, onError) {
+const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (machine, state, event, self, stateScope, system, actorId, onError, onSpawnDefect) {
 	const spawnEffects = findSpawnEffects(machine, state._tag);
 	const ctx = {
 		actorId,
@@ -157,6 +168,7 @@ const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (m
 	};
 	const { effects: effectSlots } = machine._slots;
 	const reportError = onError;
+	const defectSignal = onSpawnDefect;
 	for (const spawnEffect of spawnEffects) {
 		const effect = spawnEffect.handler({
 			actorId,
@@ -167,13 +179,14 @@ const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (m
 			system
 		}).pipe(Effect.provideService(machine.Context, ctx), Effect.catchAllCause((cause) => {
 			if (Cause.isInterruptedOnly(cause)) return Effect.interrupt;
-			if (reportError === void 0) return Effect.failCause(cause).pipe(Effect.orDie);
-			return reportError({
+			const report = reportError !== void 0 ? reportError({
 				phase: "spawn",
 				state,
 				event,
 				cause
-			}).pipe(Effect.zipRight(Effect.failCause(cause).pipe(Effect.orDie)));
+			}) : Effect.void;
+			const signal = defectSignal !== void 0 ? defectSignal(cause) : Effect.void;
+			return report.pipe(Effect.zipRight(signal), Effect.zipRight(Effect.failCause(cause).pipe(Effect.orDie)));
 		}));
 		yield* Effect.forkScoped(effect).pipe(Effect.provideService(Scope.Scope, stateScope));
 	}
@@ -246,11 +259,10 @@ const getIndex = (machine) => {
 * Find all transitions matching a state/event pair.
 * Returns empty array if no matches.
 *
-* Accepts both `Machine` and `BuiltMachine`.
 * O(1) lookup after first access (index is lazily built).
 */
 const findTransitions = (input, stateTag, eventTag) => {
-	const index = getIndex(input instanceof BuiltMachine ? input._inner : input);
+	const index = getIndex(input);
 	const specific = index.transitions.get(stateTag)?.get(eventTag) ?? [];
 	if (specific.length > 0) return specific;
 	return index.transitions.get("*")?.get(eventTag) ?? [];

package/v3/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;
-/** Reply tuple returned from transition handlers for ask support */
-interface TransitionReply<State> {
+declare const ReplyResultSymbol: unique symbol;
+type ReplyResultSymbol = typeof ReplyResultSymbol;
+/**
+ * Branded reply result from a transition handler.
+ * Created via `Machine.reply(state, value)`.
+ */
+interface ReplyResult<State, Reply> {
+  readonly state: State;
+  readonly reply: Reply;
+  readonly [ReplyResultSymbol]: true;
+}
+/**
+ * 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 reply: unknown;
+  readonly [DeferReplySymbol]: true;
 }
 /**
- * Transition handler result - either a new state, reply tuple, or Effect producing one
+ * 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> = State | TransitionReply<State> | Effect.Effect<State | TransitionReply<State>, never, R>;
+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/v3/dist/internal/utils.js

@@ -1,5 +1,31 @@
 import { Effect, Stream } from "effect";
 //#region src/internal/utils.ts
+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.
@@ -42,4 +68,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/v3/dist/machine.d.ts

@@ -1,15 +1,16 @@
-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 { Supervision } from "./supervision.js";
+import { 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 { 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, Duration, Effect, Schema, Scope } 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, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, ReplyResult, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, make, materializeMachine, replay, reply, spawn };
 }
 /**
  * Self reference for sending events back to the machine
@@ -22,7 +23,7 @@ interface MachineRef<Event> {
     readonly _tag: string;
   }, E2 extends {
     readonly _tag: string;
-  }, R2>(id: string, machine: BuiltMachine<S2, E2, R2>) => Effect.Effect<ActorRef<S2, E2>, DuplicateActorError, R2>;
+  }, R2>(id: string, machine: Machine<S2, E2, R2, any, any, any, any>) => Effect.Effect<ActorRef<S2, E2>, DuplicateActorError, R2>;
 }
 /**
  * Handler context passed to transition handlers
@@ -45,9 +46,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
  */
@@ -91,9 +94,6 @@ interface TimeoutConfig<State, Event> {
   /** 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;
 interface MakeConfig<SD extends Record<string, Schema.Struct.Fields>, ED extends Record<string, Schema.Struct.Fields>, S extends BrandedState, E extends BrandedEvent, GD extends GuardsDef, EFD extends EffectsDef> {
   readonly state: MachineStateSchema<SD> & {
     Type: S;
@@ -113,22 +113,14 @@ type HasEffectKeys<EFD extends EffectsDef> = [keyof EFD] extends [never] ? false
 type SlotContext<State, Event> = MachineContext<State, Event, MachineRef<Event>>;
 /** Combined handlers for build() - guards and effects only */
 type ProvideHandlers<State, Event, GD extends GuardsDef, EFD extends EffectsDef, R> = (HasGuardKeys<GD> extends true ? GuardHandlers<GD, SlotContext<State, Event>, R> : object) & (HasEffectKeys<EFD> extends true ? EffectHandlers<EFD, SlotContext<State, Event>, R> : object);
-/** Whether the machine has any guard or effect slots */
-type HasSlots<GD extends GuardsDef, EFD extends EffectsDef> = HasGuardKeys<GD> extends true ? true : HasEffectKeys<EFD>;
 /**
- * A finalized machine ready for spawning.
+ * Bind slot handlers to a machine, returning a fresh copy with handlers installed.
+ * If no handlers provided and machine has no slots, returns the machine as-is.
+ * Validates that all required slots are provided and no extra slots are given.
  *
- * Created by calling `.build()` on a `Machine`. This is the only type
- * accepted by `Machine.spawn` and `ActorSystem.spawn` (regular overload).
- * Testing utilities (`simulate`, `createTestHarness`, etc.) still accept `Machine`.
+ * @internal — used by spawn, replay, simulate, test harness, entity-machine
  */
-declare class BuiltMachine<State, Event, R = never> {
-  /** @internal */
-  readonly _inner: Machine<State, Event, R, any, any, any, any>;
-  /** @internal */
-  constructor(machine: Machine<State, Event, R, any, any, any, any>);
-  get initial(): State;
-}
+declare const materializeMachine: <S, E, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, any, any, GD, EFD>, handlers?: Record<string, any>) => Machine<S, E, never, any, any, GD, EFD>;
 /**
  * Machine definition with fluent builder API.
  *
@@ -171,6 +163,8 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
   };
   readonly stateSchema?: Schema.Schema<State, unknown, never>;
   readonly eventSchema?: Schema.Schema<Event, unknown, never>;
+  /** @internal */
+  readonly _replySchemas: ReadonlyMap<string, Schema.Schema.Any>;
   /**
    * Context tag for accessing machine state/event/self in slot handlers.
    * Uses shared module-level tag for all machines.
@@ -186,24 +180,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.Schema.Any>;
   /** @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>;
+  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()`.
@@ -301,50 +296,43 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
    */
   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`.
-   *
-   * - Machines with slots: pass implementations as the first argument.
-   * - Machines without slots: call with no arguments.
-   */
-  build<R2 = never>(...args: HasSlots<GD, EFD> extends true ? [handlers: ProvideHandlers<State, Event, GD, EFD, R2>] : [handlers?: ProvideHandlers<State, Event, GD, EFD, R2>]): BuiltMachine<State, Event, R | NormalizeR<R2>>;
   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>;
+  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;
+type AnyMachine<S, E, R> = Machine<S, E, R, any, any, any, any>;
 /**
- * Spawn an actor from a built machine.
+ * Spawn an actor from a machine.
  *
  * Options:
  * - `id` — custom actor ID (default: random)
  * - `hydrate` — restore from a previously-saved state snapshot.
- *   The actor starts in the hydrated state and re-runs spawn effects
- *   for that state (timers, scoped resources, etc.). Transition history
- *   is not replayed — only the current state's entry effects run.
- *
- * Persistence is composed in userland by observing `actor.changes`
- * and saving snapshots to your own storage.
+ * - `slots` — slot handler implementations for slotful machines.
  */
 declare const spawn: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R>(machine: BuiltMachine<S, E, R>, idOrOptions?: string | {
+}, R>(machine: AnyMachine<S, E, R>, options?: string | {
   id?: string;
   hydrate?: S;
+  slots?: Record<string, any>;
+  supervision?: Supervision.Policy;
 }) => Effect.Effect<ActorRef<S, E>, never, R>;
 declare const replay: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R>(machine: BuiltMachine<S, E, R>, events: ReadonlyArray<E>, options?: {
+}, R>(machine: AnyMachine<S, E, R>, events: ReadonlyArray<E>, options?: {
   from?: S;
+  slots?: Record<string, any>;
 }) => Effect.Effect<S, never, R>;
+declare const reply: <State, Reply>(state: State, reply: Reply) => ReplyResult<State, Reply>;
 //#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, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, type ReplyResult, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, machine_d_exports, make, materializeMachine, replay, reply, spawn };

package/v3/dist/machine.js

@@ -1,19 +1,20 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
-import { Inspector } from "./inspection.js";
-import { getTag, stubSystem } from "./internal/utils.js";
+import { getTag, makeReply, stubSystem } from "./internal/utils.js";
 import { ProvisionValidationError, SlotProvisionError } from "./errors.js";
+import { findTransitions, invalidateIndex, resolveTransition, runTransitionHandler, shouldPostpone } from "./internal/transition.js";
 import { emitWithTimestamp } from "./internal/inspection.js";
+import { Inspector } from "./inspection.js";
 import { MachineContextTag } from "./slot.js";
-import { findTransitions, invalidateIndex, resolveTransition, runTransitionHandler, shouldPostpone } from "./internal/transition.js";
 import { createActor } from "./actor.js";
 import { Cause, Effect, Exit, Option, Scope } from "effect";
 //#region src/machine.ts
 var machine_exports = /* @__PURE__ */ __exportAll({
-	BuiltMachine: () => BuiltMachine,
 	Machine: () => Machine,
 	findTransitions: () => findTransitions,
 	make: () => make,
+	materializeMachine: () => materializeMachine,
 	replay: () => replay,
+	reply: () => reply,
 	spawn: () => spawn
 });
 const emitTaskInspection = (input) => Effect.flatMap(Effect.serviceOptional(Inspector).pipe(Effect.option), (inspector) => Option.isNone(inspector) ? Effect.void : emitWithTimestamp(inspector.value, (timestamp) => ({
@@ -26,22 +27,49 @@ const emitTaskInspection = (input) => Effect.flatMap(Effect.serviceOptional(Insp
 	timestamp
 })));
 /**
-* A finalized machine ready for spawning.
+* Bind slot handlers to a machine, returning a fresh copy with handlers installed.
+* If no handlers provided and machine has no slots, returns the machine as-is.
+* Validates that all required slots are provided and no extra slots are given.
 *
-* Created by calling `.build()` on a `Machine`. This is the only type
-* accepted by `Machine.spawn` and `ActorSystem.spawn` (regular overload).
-* Testing utilities (`simulate`, `createTestHarness`, etc.) still accept `Machine`.
+* @internal — used by spawn, replay, simulate, test harness, entity-machine
 */
-var BuiltMachine = class {
-	/** @internal */
-	_inner;
-	/** @internal */
-	constructor(machine) {
-		this._inner = machine;
-	}
-	get initial() {
-		return this._inner.initial;
+const materializeMachine = (machine, handlers) => {
+	if (handlers === void 0) {
+		const hasGuards = machine._guardsSchema !== void 0 && Object.keys(machine._guardsSchema.definitions).length > 0;
+		const hasEffects = machine._effectsSchema !== void 0 && Object.keys(machine._effectsSchema.definitions).length > 0;
+		if (hasGuards || hasEffects) {
+			const missing = [];
+			if (machine._guardsSchema !== void 0) missing.push(...Object.keys(machine._guardsSchema.definitions));
+			if (machine._effectsSchema !== void 0) missing.push(...Object.keys(machine._effectsSchema.definitions));
+			throw new ProvisionValidationError({
+				missing,
+				extra: []
+			});
+		}
+		return machine;
 	}
+	const requiredSlots = /* @__PURE__ */ new Set();
+	if (machine._guardsSchema !== void 0) for (const name of Object.keys(machine._guardsSchema.definitions)) requiredSlots.add(name);
+	if (machine._effectsSchema !== void 0) for (const name of Object.keys(machine._effectsSchema.definitions)) requiredSlots.add(name);
+	const providedSlots = new Set(Object.keys(handlers));
+	const missing = [];
+	const extra = [];
+	for (const name of requiredSlots) if (!providedSlots.has(name)) missing.push(name);
+	for (const name of providedSlots) if (!requiredSlots.has(name)) extra.push(name);
+	if (missing.length > 0 || extra.length > 0) throw new ProvisionValidationError({
+		missing,
+		extra
+	});
+	const result = new Machine(machine.initial, machine.stateSchema, machine.eventSchema, machine._guardsSchema, machine._effectsSchema);
+	result._transitions = [...machine._transitions];
+	result._finalStates = new Set(machine._finalStates);
+	result._spawnEffects = [...machine._spawnEffects];
+	result._backgroundEffects = [...machine._backgroundEffects];
+	result._postponeRules = [...machine._postponeRules];
+	result._replySchemas = machine._replySchemas;
+	if (machine._guardsSchema !== void 0) for (const name of Object.keys(machine._guardsSchema.definitions)) result._guardHandlers.set(name, handlers[name]);
+	if (machine._effectsSchema !== void 0) for (const name of Object.keys(machine._effectsSchema.definitions)) result._effectHandlers.set(name, handlers[name]);
+	return result;
 };
 /**
 * Machine definition with fluent builder API.
@@ -69,6 +97,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 +124,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;
@@ -109,6 +141,7 @@ var Machine = class Machine {
 		this._effectHandlers = /* @__PURE__ */ new Map();
 		this.stateSchema = stateSchema;
 		this.eventSchema = eventSchema;
+		this._replySchemas = eventSchema?._replySchemas ?? /* @__PURE__ */ new Map();
 		this._slots = {
 			guards: this._guardsSchema !== void 0 ? this._guardsSchema._createSlots((name, params) => Effect.flatMap(Effect.serviceOptional(this.Context).pipe(Effect.orDie), (ctx) => {
 				const handler = this._guardHandlers.get(name);
@@ -344,40 +377,6 @@ var Machine = class Machine {
 		this._finalStates.add(stateTag);
 		return this;
 	}
-	/**
-	* Finalize the machine. Returns a `BuiltMachine` — the only type accepted by `Machine.spawn`.
-	*
-	* - Machines with slots: pass implementations as the first argument.
-	* - Machines without slots: call with no arguments.
-	*/
-	build(...args) {
-		const handlers = args[0];
-		if (handlers !== void 0) {
-			const requiredSlots = /* @__PURE__ */ new Set();
-			if (this._guardsSchema !== void 0) for (const name of Object.keys(this._guardsSchema.definitions)) requiredSlots.add(name);
-			if (this._effectsSchema !== void 0) for (const name of Object.keys(this._effectsSchema.definitions)) requiredSlots.add(name);
-			const providedSlots = new Set(Object.keys(handlers));
-			const missing = [];
-			const extra = [];
-			for (const name of requiredSlots) if (!providedSlots.has(name)) missing.push(name);
-			for (const name of providedSlots) if (!requiredSlots.has(name)) extra.push(name);
-			if (missing.length > 0 || extra.length > 0) throw new ProvisionValidationError({
-				missing,
-				extra
-			});
-			const result = new Machine(this.initial, this.stateSchema, this.eventSchema, this._guardsSchema, this._effectsSchema);
-			result._transitions = [...this._transitions];
-			result._finalStates = new Set(this._finalStates);
-			result._spawnEffects = [...this._spawnEffects];
-			result._backgroundEffects = [...this._backgroundEffects];
-			result._postponeRules = [...this._postponeRules];
-			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]);
-			return new BuiltMachine(result);
-		}
-		return new BuiltMachine(this);
-	}
 	static make(config) {
 		return new Machine(config.initial, config.state, config.event, config.guards, config.effects);
 	}
@@ -398,27 +397,25 @@ var TransitionScope = class {
 };
 const make = Machine.make;
 /**
-* Spawn an actor from a built machine.
+* Spawn an actor from a machine.
 *
 * Options:
 * - `id` — custom actor ID (default: random)
 * - `hydrate` — restore from a previously-saved state snapshot.
-*   The actor starts in the hydrated state and re-runs spawn effects
-*   for that state (timers, scoped resources, etc.). Transition history
-*   is not replayed — only the current state's entry effects run.
-*
-* Persistence is composed in userland by observing `actor.changes`
-* and saving snapshots to your own storage.
+* - `slots` — slot handler implementations for slotful machines.
 */
-const spawn = Effect.fn("effect-machine.spawn")(function* (built, idOrOptions) {
-	const opts = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
-	const actor = yield* createActor(opts?.id ?? `actor-${Math.random().toString(36).slice(2)}`, built._inner, { initialState: opts?.hydrate });
+const spawn = Effect.fn("effect-machine.spawn")(function* (machine, options) {
+	const opts = typeof options === "string" ? { id: options } : options;
+	const actor = yield* createActor(opts?.id ?? `actor-${Math.random().toString(36).slice(2)}`, materializeMachine(machine, opts?.slots), {
+		initialState: opts?.hydrate,
+		supervision: opts?.supervision
+	});
 	const maybeScope = yield* Effect.serviceOption(Scope.Scope);
 	if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, actor.stop);
 	return actor;
 });
-const replay = Effect.fn("effect-machine.replay")(function* (built, events, options) {
-	const machine = built._inner;
+const replay = Effect.fn("effect-machine.replay")(function* (input, events, options) {
+	const machine = materializeMachine(input, options?.slots);
 	let state = options?.from ?? machine.initial;
 	const hasPostponeRules = machine.postponeRules.length > 0;
 	const postponed = [];
@@ -460,5 +457,6 @@ const replay = Effect.fn("effect-machine.replay")(function* (built, events, opti
 	}
 	return state;
 });
+const reply = makeReply;
 //#endregion
-export { BuiltMachine, Machine, findTransitions, machine_exports, make, replay, spawn };
+export { Machine, findTransitions, machine_exports, make, materializeMachine, replay, reply, spawn };