effect-machine 0.9.0 → 0.11.0

package/dist/internal/transition.js

@@ -18,7 +18,7 @@ import { Cause, Effect, Exit, Scope } from "effect";
 *
 * Used by:
 * - executeTransition (actor event loop, testing)
-* - persistent-actor replay (restore, replayTo)
+* - Machine.replay (event sourcing restore)
 *
 * @internal
 */
@@ -37,8 +37,18 @@ const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(fu
 		guards,
 		effects
 	};
-	const result = transition.handler(handlerCtx);
-	return isEffect(result) ? yield* result.pipe(Effect.provideService(machine.Context, ctx)) : result;
+	const raw = transition.handler(handlerCtx);
+	const resolved = isEffect(raw) ? yield* raw.pipe(Effect.provideService(machine.Context, ctx)) : raw;
+	if (resolved !== null && typeof resolved === "object" && "state" in resolved && "reply" in resolved && !("_tag" in resolved)) return {
+		newState: resolved.state,
+		hasReply: true,
+		reply: resolved.reply
+	};
+	return {
+		newState: resolved,
+		hasReply: false,
+		reply: void 0
+	};
 });
 /**
 * Execute a transition for a given state and event.
@@ -56,15 +66,28 @@ const executeTransition = Effect.fn("effect-machine.executeTransition")(function
 	if (transition === void 0) return {
 		newState: currentState,
 		transitioned: false,
-		reenter: false
+		reenter: false,
+		hasReply: false,
+		reply: void 0
 	};
+	const { newState, hasReply, reply } = yield* runTransitionHandler(machine, transition, currentState, event, self, system, actorId);
 	return {
-		newState: yield* runTransitionHandler(machine, transition, currentState, event, self, system, actorId),
+		newState,
 		transitioned: true,
-		reenter: transition.reenter === true
+		reenter: transition.reenter === true,
+		hasReply,
+		reply
 	};
 });
 /**
+* Check if an event should be postponed in the current state.
+* @internal
+*/
+const shouldPostpone = (machine, stateTag, eventTag) => {
+	for (const rule of machine.postponeRules) if (rule.stateTag === stateTag && rule.eventTag === eventTag) return true;
+	return false;
+};
+/**
 * Process a single event through the machine.
 *
 * Handles:
@@ -93,7 +116,10 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 		previousState: currentState,
 		transitioned: false,
 		lifecycleRan: false,
-		isFinal: false
+		isFinal: false,
+		hasReply: false,
+		reply: void 0,
+		postponed: false
 	};
 	const newState = result.newState;
 	const runLifecycle = newState._tag !== currentState._tag || result.reenter;
@@ -109,7 +135,10 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 		previousState: currentState,
 		transitioned: true,
 		lifecycleRan: runLifecycle,
-		isFinal: machine.finalStates.has(newState._tag)
+		isFinal: machine.finalStates.has(newState._tag),
+		hasReply: result.hasReply,
+		reply: result.reply,
+		postponed: false
 	};
 });
 /**
@@ -236,4 +265,4 @@ const findSpawnEffects = (machine, stateTag) => {
 	return getIndex(machine).spawn.get(stateTag) ?? [];
 };
 //#endregion
-export { executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler };
+export { executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler, shouldPostpone };

package/dist/internal/utils.d.ts

@@ -26,7 +26,12 @@ type TaggedConstructor<T extends {
 /**
  * Transition handler result - either a new state or Effect producing one
  */
-type TransitionResult<State, R> = State | Effect.Effect<State, never, R>;
+/** Reply tuple returned from transition handlers for ask support */
+interface TransitionReply<State> {
+  readonly state: State;
+  readonly reply: unknown;
+}
+type TransitionResult<State, R> = State | TransitionReply<State> | Effect.Effect<State | TransitionReply<State>, never, R>;
 /**
  * Internal event tags used for lifecycle effect contexts.
  * Prefixed with $ to distinguish from user events.
@@ -57,4 +62,4 @@ declare const isEffect: (value: unknown) => value is Effect.Effect<unknown, unkn
  */
 declare const stubSystem: ActorSystem;
 //#endregion
-export { ArgsOf, INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, InstanceOf, TagOf, TaggedConstructor, TransitionResult, getTag, isEffect, stubSystem };
+export { ArgsOf, INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, InstanceOf, TagOf, TaggedConstructor, TransitionReply, TransitionResult, getTag, isEffect, stubSystem };

package/dist/internal/utils.js

@@ -37,17 +37,13 @@ const isEffect = Effect.isEffect;
 */
 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 };

package/dist/machine.d.ts

@@ -2,21 +2,22 @@ import { EffectHandlers, EffectSlots, EffectsDef, EffectsSchema, GuardHandlers,
 import { TransitionResult } from "./internal/utils.js";
 import { BrandedEvent, BrandedState, TaggedOrConstructor } from "./internal/brands.js";
 import { MachineEventSchema, MachineStateSchema, VariantsUnion } from "./schema.js";
-import { PersistenceConfig, PersistentMachine } from "./persistence/persistent-machine.js";
 import { DuplicateActorError } from "./errors.js";
 import { findTransitions } from "./internal/transition.js";
 import { ActorRef, ActorSystem } from "./actor.js";
-import { Cause, Effect, Schedule, Schema, Scope, ServiceMap } from "effect";
+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, PersistOptions, PersistenceConfig, PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, Transition, TransitionHandler, findTransitions, make, spawn };
+  export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, make, replay, spawn };
 }
 /**
  * Self reference for sending events back to the machine
  */
 interface MachineRef<Event> {
   readonly send: (event: Event) => Effect.Effect<void>;
+  /** Fire-and-forget alias for send (OTP gen_server:cast). */
+  readonly cast: (event: Event) => Effect.Effect<void>;
   readonly spawn: <S2 extends {
     readonly _tag: string;
   }, E2 extends {
@@ -73,19 +74,23 @@ 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;
   readonly name?: string;
 }
+/**
+ * Configuration for `.timeout()` — gen_statem-style state timeouts.
+ *
+ * Entering the state starts a timer. Leaving cancels it.
+ * `.reenter()` restarts the timer with fresh state values.
+ */
+interface TimeoutConfig<State, Event> {
+  /** Duration before firing. Static or derived from current state. */
+  readonly duration: Duration.Input | ((state: State) => Duration.Input);
+  /** 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;
@@ -123,11 +128,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.
@@ -152,6 +152,11 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
   /** @internal */
   readonly _finalStates: Set<string>;
   /** @internal */
+  readonly _postponeRules: Array<{
+    readonly stateTag: string;
+    readonly eventTag: string;
+  }>;
+  /** @internal */
   readonly _guardsSchema?: GuardsSchema<GD>;
   /** @internal */
   readonly _effectsSchema?: EffectsSchema<EFD>;
@@ -175,6 +180,10 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
   get spawnEffects(): ReadonlyArray<SpawnEffect<State, Event, EFD, R>>;
   get backgroundEffects(): ReadonlyArray<BackgroundEffect<State, Event, EFD, R>>;
   get finalStates(): ReadonlySet<string>;
+  get postponeRules(): ReadonlyArray<{
+    readonly stateTag: string;
+    readonly eventTag: string;
+  }>;
   get guardsSchema(): GuardsSchema<GD> | undefined;
   get effectsSchema(): EffectsSchema<EFD> | undefined;
   /** @internal */
@@ -230,6 +239,28 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
    * Interrupts do not emit failure events.
    */
   task<NS extends VariantsUnion<_SD> & BrandedState, A, E1, ES extends VariantsUnion<_ED> & BrandedEvent, EF extends VariantsUnion<_ED> & BrandedEvent>(state: TaggedOrConstructor<NS>, run: (ctx: StateHandlerContext<NS, VariantsUnion<_ED> & BrandedEvent, EFD>) => Effect.Effect<A, E1, Scope.Scope>, options: TaskOptions<NS, VariantsUnion<_ED> & BrandedEvent, EFD, A, E1, ES, EF>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /**
+   * State timeout — gen_statem's `state_timeout`.
+   *
+   * Entering the state starts a timer. Leaving cancels it (via state scope).
+   * `.reenter()` restarts the timer with fresh state values.
+   * Compiles to `.task()` internally — preserves `@machine.task` inspection events.
+   *
+   * @example
+   * ```ts
+   * machine
+   *   .timeout(State.Loading, {
+   *     duration: Duration.seconds(30),
+   *     event: Event.Timeout,
+   *   })
+   *   // Dynamic duration from state
+   *   .timeout(State.Retrying, {
+   *     duration: (state) => Duration.seconds(state.backoff),
+   *     event: Event.GiveUp,
+   *   })
+   * ```
+   */
+  timeout<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, config: TimeoutConfig<NS, VariantsUnion<_ED> & BrandedEvent>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /**
    * Machine-lifetime effect that is forked on actor spawn and runs until the actor stops.
    * Use effect slots defined via `Slot.Effects` for the actual work.
@@ -251,6 +282,24 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
    * ```
    */
   background(handler: StateEffectHandler<State, Event, EFD, Scope.Scope>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /**
+   * Postpone events — gen_statem's event postpone.
+   *
+   * When a matching event arrives in the given state, it is buffered instead of
+   * processed. After the next state transition (tag change), all buffered events
+   * are drained through the loop in FIFO order.
+   *
+   * Reply-bearing events (from `call`/`ask`) in the postpone buffer are settled
+   * with `ActorStoppedError` on stop/interrupt/final-state.
+   *
+   * @example
+   * ```ts
+   * machine
+   *   .postpone(State.Connecting, Event.Data)           // single event
+   *   .postpone(State.Connecting, [Event.Data, Event.Cmd]) // multiple events
+   * ```
+   */
+  postpone<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, events: TaggedOrConstructor<VariantsUnion<_ED> & BrandedEvent> | ReadonlyArray<TaggedOrConstructor<VariantsUnion<_ED> & BrandedEvent>>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   final<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /**
    * Finalize the machine. Returns a `BuiltMachine` — the only type accepted by `Machine.spawn`.
@@ -259,12 +308,6 @@ 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> {
@@ -275,17 +318,33 @@ declare class TransitionScope<State, Event, R, _SD extends Record<string, Schema
   reenter<NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(event: TaggedOrConstructor<NE>, handler: TransitionHandler<SelectedState, NE, RS, GD, EFD, never>): TransitionScope<State, Event, R, _SD, _ED, GD, EFD, SelectedState>;
 }
 declare const make: typeof Machine.make;
-declare const spawn: {
-  <S extends {
-    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>;
 //#endregion
-export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, type PersistenceConfig, type PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, Transition, TransitionHandler, findTransitions, machine_d_exports, make, spawn };
+export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, machine_d_exports, make, replay, spawn };

package/dist/machine.js

@@ -1,11 +1,10 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
 import { Inspector } from "./inspection.js";
-import { getTag } from "./internal/utils.js";
+import { getTag, stubSystem } from "./internal/utils.js";
 import { ProvisionValidationError, SlotProvisionError } from "./errors.js";
-import { persist } from "./persistence/persistent-machine.js";
 import { emitWithTimestamp } from "./internal/inspection.js";
 import { MachineContextTag } from "./slot.js";
-import { findTransitions, invalidateIndex } from "./internal/transition.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
@@ -14,6 +13,7 @@ var machine_exports = /* @__PURE__ */ __exportAll({
 	Machine: () => Machine,
 	findTransitions: () => findTransitions,
 	make: () => make,
+	replay: () => replay,
 	spawn: () => spawn
 });
 const emitTaskInspection = (input) => Effect.flatMap(Effect.serviceOption(Inspector), (inspector) => Option.isNone(inspector) ? Effect.void : emitWithTimestamp(inspector.value, (timestamp) => ({
@@ -42,9 +42,6 @@ var BuiltMachine = class {
 	get initial() {
 		return this._inner.initial;
 	}
-	persist(config) {
-		return this._inner.persist(config);
-	}
 };
 /**
 * Machine definition with fluent builder API.
@@ -64,6 +61,7 @@ var Machine = class Machine {
 	/** @internal */ _spawnEffects;
 	/** @internal */ _backgroundEffects;
 	/** @internal */ _finalStates;
+	/** @internal */ _postponeRules;
 	/** @internal */ _guardsSchema;
 	/** @internal */ _effectsSchema;
 	/** @internal */ _guardHandlers;
@@ -88,6 +86,9 @@ var Machine = class Machine {
 	get finalStates() {
 		return this._finalStates;
 	}
+	get postponeRules() {
+		return this._postponeRules;
+	}
 	get guardsSchema() {
 		return this._guardsSchema;
 	}
@@ -101,6 +102,7 @@ var Machine = class Machine {
 		this._spawnEffects = [];
 		this._backgroundEffects = [];
 		this._finalStates = /* @__PURE__ */ new Set();
+		this._postponeRules = [];
 		this._guardsSchema = guardsSchema;
 		this._effectsSchema = effectsSchema;
 		this._guardHandlers = /* @__PURE__ */ new Map();
@@ -259,6 +261,36 @@ var Machine = class Machine {
 		return this.spawn(state, handler);
 	}
 	/**
+	* State timeout — gen_statem's `state_timeout`.
+	*
+	* Entering the state starts a timer. Leaving cancels it (via state scope).
+	* `.reenter()` restarts the timer with fresh state values.
+	* Compiles to `.task()` internally — preserves `@machine.task` inspection events.
+	*
+	* @example
+	* ```ts
+	* machine
+	*   .timeout(State.Loading, {
+	*     duration: Duration.seconds(30),
+	*     event: Event.Timeout,
+	*   })
+	*   // Dynamic duration from state
+	*   .timeout(State.Retrying, {
+	*     duration: (state) => Duration.seconds(state.backoff),
+	*     event: Event.GiveUp,
+	*   })
+	* ```
+	*/
+	timeout(state, config) {
+		const stateTag = getTag(state);
+		const resolveDuration = typeof config.duration === "function" ? config.duration : () => config.duration;
+		const resolveEvent = typeof config.event === "function" ? config.event : () => config.event;
+		return this.task(state, (ctx) => Effect.sleep(resolveDuration(ctx.state)), {
+			onSuccess: (_, ctx) => resolveEvent(ctx.state),
+			name: `$timeout:${stateTag}`
+		});
+	}
+	/**
 	* Machine-lifetime effect that is forked on actor spawn and runs until the actor stops.
 	* Use effect slots defined via `Slot.Effects` for the actual work.
 	*
@@ -282,6 +314,35 @@ var Machine = class Machine {
 		this._backgroundEffects.push({ handler });
 		return this;
 	}
+	/**
+	* Postpone events — gen_statem's event postpone.
+	*
+	* When a matching event arrives in the given state, it is buffered instead of
+	* processed. After the next state transition (tag change), all buffered events
+	* are drained through the loop in FIFO order.
+	*
+	* Reply-bearing events (from `call`/`ask`) in the postpone buffer are settled
+	* with `ActorStoppedError` on stop/interrupt/final-state.
+	*
+	* @example
+	* ```ts
+	* machine
+	*   .postpone(State.Connecting, Event.Data)           // single event
+	*   .postpone(State.Connecting, [Event.Data, Event.Cmd]) // multiple events
+	* ```
+	*/
+	postpone(state, events) {
+		const stateTag = getTag(state);
+		const eventList = Array.isArray(events) ? events : [events];
+		for (const ev of eventList) {
+			const eventTag = getTag(ev);
+			this._postponeRules.push({
+				stateTag,
+				eventTag
+			});
+		}
+		return this;
+	}
 	final(state) {
 		const stateTag = getTag(state);
 		this._finalStates.add(stateTag);
@@ -313,6 +374,7 @@ var Machine = class Machine {
 			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]);
@@ -320,10 +382,6 @@ var Machine = class Machine {
 		}
 		return new BuiltMachine(this);
 	}
-	/** @internal Persist from raw Machine — prefer BuiltMachine.persist() */
-	persist(config) {
-		return persist(config)(this);
-	}
 	static make(config) {
 		return new Machine(config.initial, config.state, config.event, config.guards, config.effects);
 	}
@@ -343,11 +401,68 @@ var TransitionScope = class {
 	}
 };
 const make = Machine.make;
-const spawn = Effect.fn("effect-machine.spawn")(function* (built, id) {
-	const actor = yield* createActor(id ?? `actor-${Math.random().toString(36).slice(2)}`, built._inner);
+/**
+* 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.
+*/
+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 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;
+	let state = options?.from ?? machine.initial;
+	const hasPostponeRules = machine.postponeRules.length > 0;
+	const postponed = [];
+	const dummySend = Effect.fn("effect-machine.replay.send")((_event) => Effect.void);
+	const self = {
+		send: dummySend,
+		cast: dummySend,
+		spawn: () => Effect.die("spawn not supported in replay")
+	};
+	for (const event of events) {
+		if (machine.finalStates.has(state._tag)) break;
+		if (hasPostponeRules && shouldPostpone(machine, state._tag, event._tag)) {
+			postponed.push(event);
+			continue;
+		}
+		const transition = resolveTransition(machine, state, event);
+		if (transition !== void 0) {
+			const result = yield* runTransitionHandler(machine, transition, state, event, self, stubSystem, "replay");
+			const previousTag = state._tag;
+			state = result.newState;
+			if ((state._tag !== previousTag || transition.reenter === true) && postponed.length > 0) {
+				let drainTag = previousTag;
+				while (state._tag !== drainTag && postponed.length > 0) {
+					if (machine.finalStates.has(state._tag)) break;
+					drainTag = state._tag;
+					const drained = postponed.splice(0);
+					for (const postponedEvent of drained) {
+						if (machine.finalStates.has(state._tag)) break;
+						if (shouldPostpone(machine, state._tag, postponedEvent._tag)) {
+							postponed.push(postponedEvent);
+							continue;
+						}
+						const pTransition = resolveTransition(machine, state, postponedEvent);
+						if (pTransition !== void 0) state = (yield* runTransitionHandler(machine, pTransition, state, postponedEvent, self, stubSystem, "replay")).newState;
+					}
+				}
+			}
+		}
+	}
+	return state;
+});
 //#endregion
-export { BuiltMachine, Machine, findTransitions, machine_exports, make, spawn };
+export { BuiltMachine, Machine, findTransitions, machine_exports, make, replay, spawn };

package/dist/testing.js

@@ -1,7 +1,7 @@
 import { stubSystem } from "./internal/utils.js";
 import { AssertionError } from "./errors.js";
 import { BuiltMachine } from "./machine.js";
-import { executeTransition } from "./internal/transition.js";
+import { executeTransition, shouldPostpone } from "./internal/transition.js";
 import { Effect, SubscriptionRef } from "effect";
 //#region src/testing.ts
 /**
@@ -26,18 +26,44 @@ import { Effect, SubscriptionRef } from "effect";
 */
 const simulate = Effect.fn("effect-machine.simulate")(function* (input, events) {
 	const machine = input instanceof BuiltMachine ? input._inner : input;
+	const dummySend = Effect.fn("effect-machine.testing.simulate.send")((_event) => Effect.void);
 	const dummySelf = {
-		send: Effect.fn("effect-machine.testing.simulate.send")((_event) => Effect.void),
+		send: dummySend,
+		cast: dummySend,
 		spawn: () => Effect.die("spawn not supported in simulation")
 	};
 	let currentState = machine.initial;
 	const states = [currentState];
+	const hasPostponeRules = machine.postponeRules.length > 0;
+	const postponed = [];
 	for (const event of events) {
+		if (hasPostponeRules && shouldPostpone(machine, currentState._tag, event._tag)) {
+			postponed.push(event);
+			continue;
+		}
 		const result = yield* executeTransition(machine, currentState, event, dummySelf, stubSystem, "simulation");
 		if (!result.transitioned) continue;
+		const prevTag = currentState._tag;
 		currentState = result.newState;
 		states.push(currentState);
 		if (machine.finalStates.has(currentState._tag)) break;
+		let drainTag = prevTag;
+		while (currentState._tag !== drainTag && postponed.length > 0) {
+			drainTag = currentState._tag;
+			const drained = postponed.splice(0);
+			for (const postponedEvent of drained) {
+				if (shouldPostpone(machine, currentState._tag, postponedEvent._tag)) {
+					postponed.push(postponedEvent);
+					continue;
+				}
+				const drainResult = yield* executeTransition(machine, currentState, postponedEvent, dummySelf, stubSystem, "simulation");
+				if (drainResult.transitioned) {
+					currentState = drainResult.newState;
+					states.push(currentState);
+					if (machine.finalStates.has(currentState._tag)) break;
+				}
+			}
+		}
 	}
 	return {
 		states,
@@ -113,20 +139,48 @@ const assertNeverReaches = Effect.fn("effect-machine.assertNeverReaches")(functi
 */
 const createTestHarness = Effect.fn("effect-machine.createTestHarness")(function* (input, options) {
 	const machine = input instanceof BuiltMachine ? input._inner : input;
+	const dummySend = Effect.fn("effect-machine.testing.harness.send")((_event) => Effect.void);
 	const dummySelf = {
-		send: Effect.fn("effect-machine.testing.harness.send")((_event) => Effect.void),
+		send: dummySend,
+		cast: dummySend,
 		spawn: () => Effect.die("spawn not supported in test harness")
 	};
 	const stateRef = yield* SubscriptionRef.make(machine.initial);
+	const hasPostponeRules = machine.postponeRules.length > 0;
+	const postponed = [];
 	return {
 		state: stateRef,
 		send: Effect.fn("effect-machine.testHarness.send")(function* (event) {
 			const currentState = yield* SubscriptionRef.get(stateRef);
+			if (hasPostponeRules && shouldPostpone(machine, currentState._tag, event._tag)) {
+				postponed.push(event);
+				return currentState;
+			}
 			const result = yield* executeTransition(machine, currentState, event, dummySelf, stubSystem, "test-harness");
 			if (!result.transitioned) return currentState;
+			const prevTag = currentState._tag;
 			const newState = result.newState;
 			yield* SubscriptionRef.set(stateRef, newState);
 			if (options?.onTransition !== void 0) options.onTransition(currentState, event, newState);
+			let drainTag = prevTag;
+			let currentTag = newState._tag;
+			while (currentTag !== drainTag && postponed.length > 0) {
+				drainTag = currentTag;
+				const drained = postponed.splice(0);
+				for (const postponedEvent of drained) {
+					const state = yield* SubscriptionRef.get(stateRef);
+					if (shouldPostpone(machine, state._tag, postponedEvent._tag)) {
+						postponed.push(postponedEvent);
+						continue;
+					}
+					const drainResult = yield* executeTransition(machine, state, postponedEvent, dummySelf, stubSystem, "test-harness");
+					if (drainResult.transitioned) {
+						yield* SubscriptionRef.set(stateRef, drainResult.newState);
+						currentTag = drainResult.newState._tag;
+						if (options?.onTransition !== void 0) options.onTransition(state, postponedEvent, drainResult.newState);
+					}
+				}
+			}
 			return newState;
 		}),
 		getState: SubscriptionRef.get(stateRef)