effect-machine 0.10.0 → 0.12.0

package/v3/dist/internal/runtime.js

@@ -0,0 +1,236 @@
+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 } 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* Ref.make(machine.initial);
+	const stoppedRef = yield* Ref.make(false);
+	const eventQueue = yield* config.queueFactory ?? Queue.unbounded();
+	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(childId, childMachine).pipe(Effect.provideService(ActorSystem, system))
+	};
+	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.forkDaemon(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.forkDaemon(runtimeEventLoop(machine, stateRef, eventQueue, stoppedRef, self, backgroundFibers, stateScopeRef, actorId, system, hooks));
+	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: Ref.get(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) {
+	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* Ref.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* Ref.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 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.catchAllCause((cause) => {
+			if (queued._tag === "sendWait") Effect.runFork(Deferred.succeed(queued.done, void 0));
+			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/v3/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/v3/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/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.
@@ -33,17 +59,13 @@ const isEffect = (value) => typeof value === "object" && value !== null && Effec
 */
 const stubSystem = {
 	spawn: () => Effect.die("spawn not supported in stub system"),
-	restore: () => Effect.die("restore not supported in stub system"),
 	get: () => Effect.die("get not supported in stub system"),
 	stop: () => Effect.die("stop not supported in stub system"),
 	events: Stream.empty,
 	get actors() {
 		return /* @__PURE__ */ new Map();
 	},
-	subscribe: () => () => {},
-	listPersisted: () => Effect.die("listPersisted not supported in stub system"),
-	restoreMany: () => Effect.die("restoreMany not supported in stub system"),
-	restoreAll: () => Effect.die("restoreAll not supported in stub system")
+	subscribe: () => () => {}
 };
 //#endregion
-export { INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, getTag, isEffect, stubSystem };
+export { INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, getTag, isDeferReplyResult, isEffect, isReplyResult, makeDeferReply, makeReply, stubSystem };

package/v3/dist/machine.d.ts

@@ -1,16 +1,15 @@
 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 { ReplyResult, TransitionResult } from "./internal/utils.js";
+import { BrandedEvent, BrandedState, ExtractReply, 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 { findTransitions } from "./internal/transition.js";
 import { ActorRef, ActorSystem } from "./actor.js";
-import { Cause, Context, Duration, Effect, Schedule, Schema, Scope } from "effect";
+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, PersistOptions, PersistenceConfig, PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, make, spawn };
+  export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, ReplyResult, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, make, replay, reply, spawn };
 }
 /**
  * Self reference for sending events back to the machine
@@ -46,9 +45,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
  */
@@ -75,14 +76,6 @@ interface SpawnEffect<State, Event, ED extends EffectsDef, R> {
 interface BackgroundEffect<State, Event, ED extends EffectsDef, R> {
   readonly handler: StateEffectHandler<State, Event, ED, R>;
 }
-/** Options for `persist` */
-interface PersistOptions {
-  readonly snapshotSchedule: Schedule.Schedule<unknown, {
-    readonly _tag: string;
-  }>;
-  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;
@@ -137,11 +130,6 @@ declare class BuiltMachine<State, Event, R = never> {
   /** @internal */
   constructor(machine: Machine<State, Event, R, any, any, any, any>);
   get initial(): State;
-  persist(config: PersistOptions): PersistentMachine<State & {
-    readonly _tag: string;
-  }, Event & {
-    readonly _tag: string;
-  }, R>;
 }
 /**
  * Machine definition with fluent builder API.
@@ -185,6 +173,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.
@@ -200,24 +190,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()`.
@@ -322,33 +313,44 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
    * - 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>>;
-  /** @internal Persist from raw Machine — prefer BuiltMachine.persist() */
-  persist(config: PersistOptions): PersistentMachine<State & {
-    readonly _tag: string;
-  }, Event & {
-    readonly _tag: string;
-  }, 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>;
+  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;
-declare const spawn: {
-  <S extends {
-    readonly _tag: string;
-  }, E extends {
-    readonly _tag: string;
-  }, R>(machine: BuiltMachine<S, E, R>): Effect.Effect<ActorRef<S, E>, never, R>;
-  <S extends {
-    readonly _tag: string;
-  }, E extends {
-    readonly _tag: string;
-  }, R>(machine: BuiltMachine<S, E, R>, id: string): Effect.Effect<ActorRef<S, E>, never, R>;
-};
+/**
+ * Spawn an actor from a built 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.
+ */
+declare const spawn: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R>(machine: BuiltMachine<S, E, R>, idOrOptions?: string | {
+  id?: string;
+  hydrate?: S;
+}) => 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?: {
+  from?: S;
+}) => 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, PersistOptions, type PersistenceConfig, type PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, machine_d_exports, make, spawn };
+export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, type ReplyResult, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, machine_d_exports, make, replay, reply, spawn };