effect-machine 0.10.0 → 0.11.0

package/v3/dist/actor.js

@@ -1,11 +1,8 @@
 import { Inspector } from "./inspection.js";
 import { INTERNAL_INIT_EVENT } from "./internal/utils.js";
 import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.js";
-import { isPersistentMachine } from "./persistence/persistent-machine.js";
 import { emitWithTimestamp } from "./internal/inspection.js";
 import { processEventCore, resolveTransition, runSpawnEffects, shouldPostpone } from "./internal/transition.js";
-import { PersistenceAdapterTag, PersistenceError } from "./persistence/adapter.js";
-import { createPersistentActor, restorePersistentActor } from "./persistence/persistent-actor.js";
 import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Runtime, Scope, Stream, SubscriptionRef } from "effect";
 //#region src/actor.ts
 /**
@@ -31,7 +28,7 @@ const notifyListeners = (listeners, state) => {
 /**
 * Build core ActorRef methods shared between regular and persistent actors.
 */
-const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listeners, stop, system, childrenMap, pendingReplies) => {
+const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listeners, stop, system, childrenMap, pendingReplies, transitionsPubSub) => {
 	const send = Effect.fn("effect-machine.actor.send")(function* (event) {
 		if (yield* Ref.get(stoppedRef)) return;
 		yield* Queue.offer(eventQueue, {
@@ -121,6 +118,7 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 		matches,
 		can,
 		changes: stateRef.changes,
+		transitions: transitionsPubSub !== void 0 ? Stream.fromPubSub(transitionsPubSub) : Stream.empty,
 		waitFor,
 		awaitFinal,
 		sendAndWait,
@@ -151,7 +149,8 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 /**
 * Create and start an actor for a machine
 */
-const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machine) {
+const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machine, options) {
+	const initial = options?.initialState ?? machine.initial;
 	yield* Effect.annotateCurrentSpan("effect_machine.actor.id", id);
 	const existingSystem = yield* Effect.serviceOption(ActorSystem);
 	let system;
@@ -186,20 +185,20 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 			return child;
 		})
 	};
-	yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", machine.initial._tag);
+	yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", initial._tag);
 	yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
 		type: "@machine.spawn",
 		actorId: id,
-		initialState: machine.initial,
+		initialState: initial,
 		timestamp
 	}));
-	const stateRef = yield* SubscriptionRef.make(machine.initial);
+	const stateRef = yield* SubscriptionRef.make(initial);
 	const listeners = /* @__PURE__ */ new Set();
 	const backgroundFibers = [];
 	const initEvent = { _tag: INTERNAL_INIT_EVENT };
 	const ctx = {
 		actorId: id,
-		state: machine.initial,
+		state: initial,
 		event: initEvent,
 		self,
 		system
@@ -208,7 +207,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	for (const bg of machine.backgroundEffects) {
 		const fiber = yield* Effect.forkDaemon(bg.handler({
 			actorId: id,
-			state: machine.initial,
+			state: initial,
 			event: initEvent,
 			self,
 			effects: effectSlots,
@@ -217,14 +216,14 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		backgroundFibers.push(fiber);
 	}
 	const stateScopeRef = { current: yield* Scope.make() };
-	yield* runSpawnEffectsWithInspection(machine, machine.initial, initEvent, self, stateScopeRef.current, id, inspectorValue, system);
-	if (machine.finalStates.has(machine.initial._tag)) {
+	yield* runSpawnEffectsWithInspection(machine, initial, initEvent, self, stateScopeRef.current, id, inspectorValue, system);
+	if (machine.finalStates.has(initial._tag)) {
 		yield* Scope.close(stateScopeRef.current, Exit.void);
 		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
 		yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
 			type: "@machine.stop",
 			actorId: id,
-			finalState: machine.initial,
+			finalState: initial,
 			timestamp
 		}));
 		yield* Ref.set(stoppedRef, true);
@@ -232,7 +231,8 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, Ref.set(stoppedRef, true).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid), system, childrenMap, /* @__PURE__ */ new Set());
 	}
 	const pendingReplies = /* @__PURE__ */ new Set();
-	const loopFiber = yield* Effect.forkDaemon(eventLoop(machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, id, inspectorValue, system, pendingReplies));
+	const transitionsPubSub = yield* PubSub.unbounded();
+	const loopFiber = yield* Effect.forkDaemon(eventLoop(machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, id, inspectorValue, system, pendingReplies, transitionsPubSub));
 	return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, Effect.gen(function* () {
 		const finalState = yield* SubscriptionRef.get(stateRef);
 		yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
@@ -247,7 +247,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		yield* Scope.close(stateScopeRef.current, Exit.void);
 		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
 		if (implicitSystemScope !== void 0) yield* Scope.close(implicitSystemScope, Exit.void);
-	}).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid), system, childrenMap, pendingReplies);
+	}).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid), system, childrenMap, pendingReplies, transitionsPubSub);
 });
 /** Fail all pending call/ask Deferreds with ActorStoppedError. Safe to call multiple times. */
 const settlePendingReplies = (pendingReplies, actorId) => Effect.sync(() => {
@@ -260,7 +260,7 @@ const settlePendingReplies = (pendingReplies, actorId) => Effect.sync(() => {
 * Includes postpone buffer — events matching postpone rules are buffered
 * and drained after state tag changes (gen_statem semantics).
 */
-const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, actorId, inspector, system, pendingReplies) {
+const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, actorId, inspector, system, pendingReplies, transitionsPubSub) {
 	const postponed = [];
 	const hasPostponeRules = machine.postponeRules.length > 0;
 	const processQueued = Effect.fn("effect-machine.actor.processQueued")(function* (queued) {
@@ -303,6 +303,11 @@ const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine
 				}));
 				break;
 		}
+		if (result.transitioned) yield* PubSub.publish(transitionsPubSub, {
+			fromState: result.previousState,
+			toState: result.newState,
+			event
+		});
 		return {
 			shouldStop,
 			stateChanged: result.lifecycleRan
@@ -318,15 +323,21 @@ const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine
 			yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
 			return;
 		}
-		if (stateChanged && postponed.length > 0) {
+		let drainTriggered = stateChanged;
+		while (drainTriggered && postponed.length > 0) {
+			drainTriggered = false;
 			const drained = postponed.splice(0);
-			for (const entry of drained) if ((yield* processQueued(entry)).shouldStop) {
-				yield* Ref.set(stoppedRef, true);
-				settlePostponedBuffer(postponed, pendingReplies, actorId);
-				yield* settlePendingReplies(pendingReplies, actorId);
-				yield* Scope.close(stateScopeRef.current, Exit.void);
-				yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
-				return;
+			for (const entry of drained) {
+				const drain = yield* processQueued(entry);
+				if (drain.shouldStop) {
+					yield* Ref.set(stoppedRef, true);
+					settlePostponedBuffer(postponed, pendingReplies, actorId);
+					yield* settlePendingReplies(pendingReplies, actorId);
+					yield* Scope.close(stateScopeRef.current, Exit.void);
+					yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+					return;
+				}
+				if (drain.stateChanged) drainTriggered = true;
 			}
 		}
 	}
@@ -482,25 +493,7 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 		if (MutableHashMap.has(actorsMap, id)) return yield* new DuplicateActorError({ actorId: id });
 		return yield* registerActor(id, yield* createActor(id, built._inner));
 	});
-	const spawnPersistent = Effect.fn("effect-machine.actorSystem.spawnPersistent")(function* (id, persistentMachine) {
-		if (MutableHashMap.has(actorsMap, id)) return yield* new DuplicateActorError({ actorId: id });
-		const adapter = yield* PersistenceAdapterTag;
-		const maybeSnapshot = yield* adapter.loadSnapshot(id, persistentMachine.persistence.stateSchema);
-		return yield* registerActor(id, yield* createPersistentActor(id, persistentMachine, maybeSnapshot, yield* adapter.loadEvents(id, persistentMachine.persistence.eventSchema, Option.isSome(maybeSnapshot) ? maybeSnapshot.value.version : void 0)));
-	});
-	const spawnImpl = Effect.fn("effect-machine.actorSystem.spawn")(function* (id, machine) {
-		if (isPersistentMachine(machine)) return yield* spawnPersistent(id, machine);
-		return yield* spawnRegular(id, machine);
-	});
-	function spawn(id, machine) {
-		return withSpawnGate(spawnImpl(id, machine));
-	}
-	const restoreImpl = Effect.fn("effect-machine.actorSystem.restore")(function* (id, persistentMachine) {
-		const maybeActor = yield* restorePersistentActor(id, persistentMachine);
-		if (Option.isSome(maybeActor)) yield* registerActor(id, maybeActor.value);
-		return maybeActor;
-	});
-	const restore = (id, persistentMachine) => withSpawnGate(restoreImpl(id, persistentMachine));
+	const spawn = (id, machine) => withSpawnGate(spawnRegular(id, machine));
 	const get = Effect.fn("effect-machine.actorSystem.get")(function* (id) {
 		return yield* Effect.sync(() => MutableHashMap.get(actorsMap, id));
 	});
@@ -517,55 +510,8 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 		yield* actor.stop;
 		return true;
 	});
-	const listPersisted = Effect.fn("effect-machine.actorSystem.listPersisted")(function* () {
-		const adapter = yield* PersistenceAdapterTag;
-		if (adapter.listActors === void 0) return [];
-		return yield* adapter.listActors();
-	});
-	const restoreMany = Effect.fn("effect-machine.actorSystem.restoreMany")(function* (ids, persistentMachine) {
-		const restored = [];
-		const failed = [];
-		for (const id of ids) {
-			if (MutableHashMap.has(actorsMap, id)) continue;
-			const result = yield* Effect.either(restore(id, persistentMachine));
-			if (result._tag === "Left") failed.push({
-				id,
-				error: result.left
-			});
-			else if (Option.isSome(result.right)) restored.push(result.right.value);
-			else failed.push({
-				id,
-				error: new PersistenceError({
-					operation: "restore",
-					actorId: id,
-					message: "No persisted state found"
-				})
-			});
-		}
-		return {
-			restored,
-			failed
-		};
-	});
-	const restoreAll = Effect.fn("effect-machine.actorSystem.restoreAll")(function* (persistentMachine, options) {
-		const adapter = yield* PersistenceAdapterTag;
-		if (adapter.listActors === void 0) return {
-			restored: [],
-			failed: []
-		};
-		const machineType = persistentMachine.persistence.machineType;
-		if (machineType === void 0) return yield* new PersistenceError({
-			operation: "restoreAll",
-			actorId: "*",
-			message: "restoreAll requires explicit machineType in persistence config"
-		});
-		let filtered = (yield* adapter.listActors()).filter((meta) => meta.machineType === machineType);
-		if (options?.filter !== void 0) filtered = filtered.filter(options.filter);
-		return yield* restoreMany(filtered.map((meta) => meta.id), persistentMachine);
-	});
 	return ActorSystem.of({
 		spawn,
-		restore,
 		get,
 		stop,
 		events: Stream.fromPubSub(eventPubSub),
@@ -581,10 +527,7 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 			return () => {
 				eventListeners.delete(fn);
 			};
-		},
-		listPersisted,
-		restoreMany,
-		restoreAll
+		}
 	});
 });
 /**

package/v3/dist/index.d.ts

@@ -1,13 +1,9 @@
 import { EffectHandlers, EffectSlot, EffectSlots, EffectsDef, EffectsSchema, GuardHandlers, GuardSlot, GuardSlots, GuardsDef, GuardsSchema, MachineContext, Slot } from "./slot.js";
 import { Event, MachineEventSchema, MachineStateSchema, State } from "./schema.js";
-import { PersistenceConfig, PersistentMachine, isPersistentMachine } from "./persistence/persistent-machine.js";
 import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.js";
 import { ProcessEventResult } from "./internal/transition.js";
-import { PersistentActorRef, createPersistentActor, restorePersistentActor } from "./persistence/persistent-actor.js";
-import { ActorMetadata, PersistedEvent, PersistenceAdapter, PersistenceAdapterTag, PersistenceError, RestoreFailure, RestoreResult, Snapshot, VersionConflictError } from "./persistence/adapter.js";
-import { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter } from "./persistence/adapters/in-memory.js";
-import { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, ProvideHandlers, SpawnEffect, StateHandlerContext, TaskOptions, Transition, machine_d_exports } from "./machine.js";
-import { ActorRef, ActorRefSync, ActorSystem, Default, SystemEvent, SystemEventListener } from "./actor.js";
+import { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, SpawnEffect, StateHandlerContext, TaskOptions, Transition, machine_d_exports } from "./machine.js";
+import { ActorRef, ActorRefSync, ActorSystem, Default, SystemEvent, SystemEventListener, TransitionInfo } from "./actor.js";
 import { SimulationResult, TestHarness, TestHarnessOptions, assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
 import { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, InspectorHandler, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
-export { type ActorMetadata, type ActorRef, type ActorRefSync, ActorStoppedError, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type BuiltMachine, DuplicateActorError, type EffectEvent, type EffectSlots, type EffectsDef, type EffectsSchema, type ErrorEvent, Event, type EventReceivedEvent, type GuardHandlers, type GuardSlot, type GuardSlots, type GuardsDef, type GuardsSchema, type HandlerContext, InMemoryPersistenceAdapter, type InspectionEvent, type Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, machine_d_exports as Machine, type MachineContext, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, MissingSchemaError, NoReplyError, type PersistOptions, type PersistedEvent, type PersistenceAdapter, PersistenceAdapterTag, type PersistenceConfig, PersistenceError, type PersistentActorRef, type PersistentMachine, type ProcessEventResult, type ProvideHandlers, ProvisionValidationError, type RestoreFailure, type RestoreResult, type SimulationResult, Slot, type EffectHandlers as SlotEffectHandlers, type EffectSlot as SlotEffectSlot, SlotProvisionError, type Snapshot, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, type SystemEvent, type SystemEventListener, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TracingInspectorOptions, type Transition, type TransitionEvent, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, makeInspectorEffect, restorePersistentActor, simulate, tracingInspector };
+export { type ActorRef, type ActorRefSync, ActorStoppedError, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type BuiltMachine, DuplicateActorError, type EffectEvent, type EffectSlots, type EffectsDef, type EffectsSchema, type ErrorEvent, Event, type EventReceivedEvent, type GuardHandlers, type GuardSlot, type GuardSlots, type GuardsDef, type GuardsSchema, type HandlerContext, type InspectionEvent, type Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, machine_d_exports as Machine, type MachineContext, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, MissingSchemaError, NoReplyError, type ProcessEventResult, type ProvideHandlers, ProvisionValidationError, type SimulationResult, Slot, type EffectHandlers as SlotEffectHandlers, type EffectSlot as SlotEffectSlot, SlotProvisionError, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, type SystemEvent, type SystemEventListener, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TracingInspectorOptions, type Transition, type TransitionEvent, type TransitionInfo, UnprovidedSlotsError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };

package/v3/dist/index.js

@@ -1,13 +1,8 @@
 import { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
 import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.js";
-import { isPersistentMachine } from "./persistence/persistent-machine.js";
 import { Slot } from "./slot.js";
 import { machine_exports } from "./machine.js";
-import { PersistenceAdapterTag, PersistenceError, VersionConflictError } from "./persistence/adapter.js";
-import { createPersistentActor, restorePersistentActor } from "./persistence/persistent-actor.js";
 import { ActorSystem, Default } from "./actor.js";
 import { Event, State } from "./schema.js";
 import { assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
-import { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter } from "./persistence/adapters/in-memory.js";
-import "./persistence/index.js";
-export { ActorStoppedError, Default as ActorSystemDefault, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, InMemoryPersistenceAdapter, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceAdapterTag, PersistenceError, ProvisionValidationError, Slot, SlotProvisionError, State, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, makeInspectorEffect, restorePersistentActor, simulate, tracingInspector };
+export { ActorStoppedError, Default as ActorSystemDefault, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, MissingSchemaError, NoReplyError, ProvisionValidationError, Slot, SlotProvisionError, State, UnprovidedSlotsError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };

package/v3/dist/internal/utils.js

@@ -33,17 +33,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 };

package/v3/dist/machine.d.ts

@@ -2,15 +2,14 @@ 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, 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, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, make, replay, spawn };
 }
 /**
  * Self reference for sending events back to the machine
@@ -75,14 +74,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 +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.
@@ -322,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> {
@@ -338,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, TimeoutConfig, 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/v3/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.serviceOptional(Inspector).pipe(Effect.option), (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.
@@ -381,10 +378,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);
 	}
@@ -404,11 +397,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 };