effect-machine 0.14.0 → 0.15.1

package/README.md

@@ -98,6 +98,7 @@ const actor =
         }),
     },
   });
+yield * actor.start;
 ```
 
 The same machine can run with different slot implementations in tests, local apps, or production. Slots are accepted everywhere the machine runs:
@@ -109,7 +110,7 @@ The same machine can run with different slot implementations in tests, local app
 
 ## Running Actors
 
-`Machine.spawn` gives you a live actor with a queue and lifecycle management.
+`Machine.spawn` allocates an actor but does not start it. Call `actor.start` to fork the event loop, background effects, and spawn effects. Events sent before `start()` are queued.
 
 ```ts
 const program = Effect.gen(function* () {
@@ -123,6 +124,7 @@ const program = Effect.gen(function* () {
         ),
     },
   });
+  yield* actor.start;
 
   yield* actor.send(CheckoutEvent.Submit);
   const finalState = yield* actor.awaitFinal;
@@ -133,6 +135,7 @@ Effect.runPromise(Effect.scoped(program));
 
 Key actor operations:
 
+- `start` forks the event loop (idempotent, required after `Machine.spawn`)
 - `send(event)` queues and returns immediately
 - `call(event)` returns full transition info
 - `ask(event)` returns a typed domain reply (requires `Event.reply(...)`)
@@ -140,7 +143,7 @@ Key actor operations:
 - `stop` interrupts now; `drain` processes the remaining queue first
 - `watch(other)` completes when another actor stops
 
-For named actors or shared lookup, use an actor system:
+For named actors or shared lookup, use an actor system. `system.spawn` auto-starts — no `actor.start` needed:
 
 ```ts
 import { ActorSystemDefault, ActorSystemService } from "effect-machine";

package/dist/actor.d.ts

@@ -3,7 +3,7 @@ import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.j
 import { ProvideSlots, SlotsDef } from "./slot.js";
 import { ActorExit, Supervision } from "./supervision.js";
 import { ProcessEventError, ProcessEventHooks, ProcessEventResult, processEventCore, resolveTransition, runSpawnEffects } from "./internal/transition.js";
-import { Machine, PersistConfig } from "./machine.js";
+import { Lifecycle, Machine } from "./machine.js";
 import { RuntimeQueuedEvent } from "./internal/runtime.js";
 import { Deferred, Effect, Layer, Option, PubSub, Queue, Ref, Scope, ServiceMap, Stream, SubscriptionRef } from "effect";
 
@@ -54,6 +54,15 @@ interface ActorRef<State extends {
   readonly state: SubscriptionRef.SubscriptionRef<State>;
   /** Stop the actor gracefully. */
   readonly stop: Effect.Effect<void>;
+  /**
+   * Start the actor — fork event loop, background effects, spawn effects.
+   * Idempotent: first caller runs initialization, subsequent callers await completion.
+   * Events sent before start() are queued and processed when start() runs.
+   *
+   * Called automatically by `system.spawn`. For `Machine.spawn`, the caller
+   * must call `start` explicitly.
+   */
+  readonly start: Effect.Effect<void>;
   /** Get current state snapshot. */
   readonly snapshot: Effect.Effect<State>;
   /** Check if current state matches tag. */
@@ -161,7 +170,7 @@ interface ActorSystem {
   }, R, SD extends SlotsDef = Record<string, never>>(id: string, machine: Machine<S, E, R, any, any, SD>, options?: {
     readonly supervision?: Supervision.Policy;
     readonly slots?: ProvideSlots<SD, any>;
-    readonly persist?: PersistConfig<S>;
+    readonly lifecycle?: Lifecycle<S, E>;
   }) => Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>;
   /**
    * Get an existing actor by ID
@@ -204,7 +213,7 @@ declare const buildActorRefCore: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, SD extends SlotsDef>(id: string, machine: Machine<S, E, R, any, any, SD>, stateRef: SubscriptionRef.SubscriptionRef<S>, eventQueueRef: Ref.Ref<Queue.Queue<QueuedEvent<E>>>, stoppedRef: Ref.Ref<boolean>, listeners: Listeners<S>, stop: Effect.Effect<void>, system: ActorSystem, childrenMap: ReadonlyMap<string, ActorRef<AnyState, unknown>>, pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, transitionsPubSub: PubSub.PubSub<TransitionInfo<S, E>> | undefined, exitDeferred: Deferred.Deferred<ActorExit<S>, never>) => ActorRef<S, E>;
+}, R, SD extends SlotsDef>(id: string, machine: Machine<S, E, R, any, any, SD>, stateRef: SubscriptionRef.SubscriptionRef<S>, eventQueueRef: Ref.Ref<Queue.Queue<QueuedEvent<E>>>, stoppedRef: Ref.Ref<boolean>, listeners: Listeners<S>, stop: Effect.Effect<void>, start: Effect.Effect<void>, system: ActorSystem, childrenMap: ReadonlyMap<string, ActorRef<AnyState, unknown>>, pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, transitionsPubSub: PubSub.PubSub<TransitionInfo<S, E>> | undefined, exitDeferred: Deferred.Deferred<ActorExit<S>, never>) => ActorRef<S, E>;
 /**
  * Create and start an actor for a machine.
  * Delegates to the shared runtime kernel with actor-specific lifecycle hooks.
@@ -216,7 +225,7 @@ declare const createActor: <S extends {
 }, R, SD extends SlotsDef>(id: string, machine: Machine<S, E, R, any, any, SD>, options?: {
   initialState?: S;
   supervision?: Supervision.Policy;
-  persist?: PersistConfig<S>; /** @internal Called by system after each restart — emits ActorRestarted system event */
+  lifecycle?: Lifecycle<S, E>; /** @internal Called by system after each restart — emits ActorRestarted system event */
   onRestart?: (generation: number, exit: ActorExit<unknown>) => Effect.Effect<void>;
 } | undefined) => Effect.Effect<ActorRef<S, E>, never, never>;
 /** Fail all pending call/ask Deferreds with ActorStoppedError. Safe to call multiple times. */

package/dist/actor.js

@@ -29,7 +29,7 @@ const notifyListeners = (listeners, state) => {
 /**
 * Build core ActorRef methods.
 */
-const buildActorRefCore = (id, machine, stateRef, eventQueueRef, stoppedRef, listeners, stop, system, childrenMap, pendingReplies, transitionsPubSub, exitDeferred) => {
+const buildActorRefCore = (id, machine, stateRef, eventQueueRef, stoppedRef, listeners, stop, start, system, childrenMap, pendingReplies, transitionsPubSub, exitDeferred) => {
 	const send = Effect.fn("effect-machine.actor.send")(function* (event) {
 		if (yield* Ref.get(stoppedRef)) return;
 		const q = yield* Ref.get(eventQueueRef);
@@ -116,6 +116,7 @@ const buildActorRefCore = (id, machine, stateRef, eventQueueRef, stoppedRef, lis
 		ask,
 		state: stateRef,
 		stop,
+		start,
 		snapshot,
 		matches,
 		can,
@@ -191,18 +192,6 @@ const buildInspectionHooks = (actorId, inspector) => ({
 	}))
 });
 /**
-* Load persisted state and run onRestore hook if present.
-* Returns the resolved initial state (loaded, restored, or fallback to machineInitial).
-* @internal
-*/
-const loadAndRestore = (persist, machineInitial) => Effect.gen(function* () {
-	const loaded = yield* persist.load();
-	if (Option.isNone(loaded)) return machineInitial;
-	if (persist.onRestore === void 0) return loaded.value;
-	const restored = yield* persist.onRestore(loaded.value, { initial: machineInitial });
-	return Option.getOrElse(restored, () => machineInitial);
-});
-/**
 * Resolve actor system from context, creating an implicit one if none exists.
 * @internal
 */
@@ -225,7 +214,6 @@ const resolveActorSystem = Effect.fn("effect-machine.resolveActorSystem")(functi
 */
 const runSupervisionLoop = (params) => Effect.gen(function* () {
 	const step = yield* Schedule.toStepWithSleep(params.supervision.schedule);
-	let generation = 0;
 	while (true) {
 		const currentRuntime = params.runtimeRef.current;
 		if (currentRuntime === void 0) return;
@@ -242,7 +230,17 @@ const runSupervisionLoop = (params) => Effect.gen(function* () {
 			yield* Deferred.succeed(params.terminalExitDeferred, generationExit);
 			return;
 		}
-		const restartState = params.persist !== void 0 ? yield* loadAndRestore(params.persist, params.machine.initial) : params.machine.initial;
+		const nextGeneration = params.generationRef.get() + 1;
+		params.generationRef.set(nextGeneration);
+		let restartState = params.machine.initial;
+		if (params.lifecycle?.recovery !== void 0) {
+			const resolved = yield* params.lifecycle.recovery.resolve({
+				actorId: params.id,
+				generation: nextGeneration,
+				machineInitial: params.machine.initial
+			});
+			if (Option.isSome(resolved)) restartState = resolved.value;
+		}
 		yield* settlePendingReplies(params.pendingReplies, params.id);
 		const freshQueue = yield* Queue.unbounded();
 		yield* Ref.set(params.eventQueueRef, freshQueue);
@@ -255,8 +253,8 @@ const runSupervisionLoop = (params) => Effect.gen(function* () {
 		} }) : params.machine;
 		const newRuntime = yield* params.spawnGeneration(machineForRestart);
 		params.runtimeRef.current = newRuntime;
-		generation++;
-		if (params.onRestart !== void 0) yield* params.onRestart(generation, generationExit);
+		yield* newRuntime.start;
+		if (params.onRestart !== void 0) yield* params.onRestart(nextGeneration, generationExit);
 		notifyListeners(params.listeners, restartState);
 	}
 });
@@ -265,8 +263,8 @@ const runSupervisionLoop = (params) => Effect.gen(function* () {
 * Delegates to the shared runtime kernel with actor-specific lifecycle hooks.
 */
 const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machine, options) {
-	const persist = options?.persist;
-	const initial = options?.initialState ?? (persist !== void 0 ? yield* loadAndRestore(persist, machine.initial) : machine.initial);
+	const lifecycle = options?.lifecycle;
+	const initial = options?.initialState ?? machine.initial;
 	yield* Effect.annotateCurrentSpan("effect_machine.actor.id", id);
 	yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", initial._tag);
 	const { system, implicitSystemScope } = yield* resolveActorSystem();
@@ -275,12 +273,6 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	const pendingReplies = /* @__PURE__ */ new Set();
 	const listeners = /* @__PURE__ */ new Set();
 	const transitionsPubSub = yield* PubSub.unbounded();
-	yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
-		type: "@machine.spawn",
-		actorId: id,
-		initialState: initial,
-		timestamp
-	}));
 	const hooks = inspectorValue !== void 0 ? buildInspectionHooks(id, inspectorValue) : void 0;
 	const machineWithState = initial !== machine.initial ? Object.create(machine, { initial: {
 		value: initial,
@@ -292,9 +284,11 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	const eventQueueRef = yield* Ref.make(initialQueue);
 	const terminalExitDeferred = yield* Deferred.make();
 	let stopEmitted = false;
+	let generation = 0;
 	const runtimeRef = { current: void 0 };
+	const supervisorFiberRef = { current: void 0 };
 	/** Build lifecycle hooks for a generation */
-	const buildLifecycle = () => {
+	const buildRuntimeLifecycle = () => {
 		stopEmitted = false;
 		return {
 			onEvent: inspectorValue !== void 0 ? (state, event) => emitWithTimestamp(inspectorValue, (timestamp) => ({
@@ -304,10 +298,17 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 				event,
 				timestamp
 			})) : void 0,
-			onStateChange: (result, _event) => Effect.gen(function* () {
+			onStateChange: (result, event) => Effect.gen(function* () {
 				notifyListeners(listeners, result.newState);
-				if (persist !== void 0 && result.transitioned) {
-					if (persist.shouldSave === void 0 || persist.shouldSave(result.newState, result.previousState)) yield* persist.save(result.newState);
+				if (lifecycle?.durability !== void 0 && result.transitioned) {
+					const durability = lifecycle.durability;
+					if (durability.shouldSave === void 0 || durability.shouldSave(result.newState, result.previousState)) yield* durability.save({
+						actorId: id,
+						generation,
+						previousState: result.previousState,
+						nextState: result.newState,
+						event
+					});
 				}
 				yield* Effect.annotateCurrentSpan("effect_machine.transition.matched", true);
 				if (result.lifecycleRan) {
@@ -360,7 +361,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 			stoppedRef,
 			eventQueue: currentQueue
 		},
-		lifecycle: buildLifecycle(),
+		lifecycle: buildRuntimeLifecycle(),
 		wrapProcess: (state, event, inner) => Effect.withSpan("effect-machine.event.process", { attributes: {
 			"effect_machine.actor.id": id,
 			"effect_machine.state.current": state._tag,
@@ -374,34 +375,67 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 			}));
 		})
 	})));
-	const runtime = yield* spawnGeneration(machineWithState);
-	runtimeRef.current = runtime;
+	runtimeRef.current = yield* spawnGeneration(machineWithState);
 	const supervision = options?.supervision;
-	let supervisorFiber;
-	if (supervision !== void 0) supervisorFiber = yield* Effect.forkDetach(runSupervisionLoop({
-		supervision,
-		machine,
-		id,
-		runtimeRef,
-		terminalExitDeferred,
-		pendingReplies,
-		eventQueueRef,
-		stateRef,
-		stoppedRef,
-		childrenMap,
-		listeners,
-		spawnGeneration,
-		persist,
-		onRestart: options?.onRestart
-	}));
-	else yield* Effect.forkDetach(Deferred.await(runtime.exitDeferred).pipe(Effect.tap((exit) => Deferred.succeed(terminalExitDeferred, exit))));
-	return buildActorRefCore(id, machine, stateRef, eventQueueRef, stoppedRef, listeners, Effect.gen(function* () {
-		if (supervisorFiber !== void 0) yield* Fiber.interrupt(supervisorFiber);
+	const stop = Effect.gen(function* () {
+		if (supervisorFiberRef.current !== void 0) yield* Fiber.interrupt(supervisorFiberRef.current);
 		const currentRuntime = runtimeRef.current;
 		if (currentRuntime !== void 0) yield* currentRuntime.stop;
 		yield* Deferred.succeed(terminalExitDeferred, { _tag: "Stopped" });
 		if (implicitSystemScope !== void 0) yield* Scope.close(implicitSystemScope, Exit.void);
-	}).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid), system, childrenMap, pendingReplies, transitionsPubSub, terminalExitDeferred);
+	}).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid);
+	const isHydrated = options?.initialState !== void 0;
+	return buildActorRefCore(id, machine, stateRef, eventQueueRef, stoppedRef, listeners, stop, Effect.gen(function* () {
+		if (lifecycle?.recovery !== void 0 && !isHydrated) {
+			const resolved = yield* lifecycle.recovery.resolve({
+				actorId: id,
+				generation,
+				machineInitial: machine.initial
+			});
+			if (Option.isSome(resolved)) {
+				yield* SubscriptionRef.set(stateRef, resolved.value);
+				runtimeRef.current = yield* spawnGeneration(Object.create(machine, { initial: {
+					value: resolved.value,
+					enumerable: true
+				} }));
+			}
+		}
+		const currentState = yield* SubscriptionRef.get(stateRef);
+		yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
+			type: "@machine.spawn",
+			actorId: id,
+			initialState: currentState,
+			timestamp
+		}));
+		if (supervision !== void 0) supervisorFiberRef.current = yield* Effect.forkDetach(runSupervisionLoop({
+			supervision,
+			machine,
+			id,
+			runtimeRef,
+			terminalExitDeferred,
+			pendingReplies,
+			eventQueueRef,
+			stateRef,
+			stoppedRef,
+			childrenMap,
+			listeners,
+			spawnGeneration,
+			lifecycle,
+			generationRef: {
+				get: () => generation,
+				set: (g) => {
+					generation = g;
+				}
+			},
+			onRestart: options?.onRestart
+		}));
+		else {
+			const currentRuntime = runtimeRef.current;
+			if (currentRuntime !== void 0) yield* Effect.forkDetach(Deferred.await(currentRuntime.exitDeferred).pipe(Effect.tap((exit) => Deferred.succeed(terminalExitDeferred, exit))));
+		}
+		const currentRuntime = runtimeRef.current;
+		if (currentRuntime !== void 0) yield* currentRuntime.start;
+	}).pipe(Effect.withSpan("effect-machine.actor.start"), Effect.asVoid), system, childrenMap, pendingReplies, transitionsPubSub, terminalExitDeferred);
 });
 /** Fail all pending call/ask Deferreds with ActorStoppedError. Safe to call multiple times. */
 const settlePendingReplies = (pendingReplies, actorId) => Effect.sync(() => {
@@ -462,7 +496,7 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 		let actorRef;
 		const actor = yield* createActor(id, materialized, {
 			supervision: spawnOptions?.supervision,
-			persist: spawnOptions?.persist,
+			lifecycle: spawnOptions?.lifecycle,
 			onRestart: spawnOptions?.supervision !== void 0 ? (generation, exit) => actorRef !== void 0 ? emitSystemEvent({
 				_tag: "ActorRestarted",
 				id,
@@ -472,7 +506,9 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 			}) : Effect.void : void 0
 		});
 		actorRef = actor;
-		return yield* registerActor(id, actor);
+		yield* registerActor(id, actor);
+		yield* actor.start.pipe(Effect.catchCause((cause) => actor.stop.pipe(Effect.andThen(Effect.failCause(cause)))));
+		return actor;
 	});
 	const spawn = (id, machine, options) => withSpawnGate(spawnRegular(id, machine, options));
 	const get = Effect.fn("effect-machine.actorSystem.get")(function* (id) {

package/dist/cluster/entity-machine.js

@@ -60,6 +60,7 @@ const EntityMachine = { layer: (entity, machine, options) => {
 				eventQueue
 			}
 		});
+		yield* runtime.start;
 		if (persistCtx.adapter !== void 0) {
 			const { adapter: pAdapter, key } = persistCtx;
 			const strategy = persistence?.strategy ?? "snapshot";

package/dist/index.d.ts

@@ -4,8 +4,8 @@ import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaEr
 import { HasSlotKeys, MachineContext, ProvideSlots, Slot, SlotCall, SlotCalls, SlotFnDef, SlotHandler, SlotInvocation, SlotRequest, SlotResult, SlotsDef, SlotsSchema } from "./slot.js";
 import { ActorExit, CellPhase, DefectPhase, Supervision } from "./supervision.js";
 import { ProcessEventResult } from "./internal/transition.js";
-import { BackgroundEffect, HandlerContext, Machine, MachineRef, MakeConfig, SpawnEffect, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, machine_d_exports } from "./machine.js";
+import { BackgroundEffect, Durability, DurabilityCommit, HandlerContext, Lifecycle, Machine, MachineRef, MakeConfig, Recovery, RecoveryContext, SpawnEffect, StateHandlerContext, TaskOptions, TimeoutConfig, 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 { ActorExit, type ActorRef, type ActorRefSync, ActorStoppedError, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type CellPhase, type DefectPhase, type DeferReplyResult, DuplicateActorError, type EffectEvent, type ErrorEvent, Event, type EventReceivedEvent, type HandlerContext, type HasSlotKeys, 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, PersistenceError, type ProcessEventResult, type ProvideSlots, ProvisionValidationError, type ReplyFields, type ReplyResult, type SimulationResult, Slot, type SlotCall, type SlotCalls, SlotCodecError, type SlotFnDef, type SlotHandler, type SlotInvocation, SlotProvisionError, type SlotRequest, type SlotResult, type SlotsDef, type SlotsSchema, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, Supervision, type SystemEvent, type SystemEventListener, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TimeoutConfig, type TracingInspectorOptions, type Transition, type TransitionEvent, type TransitionInfo, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };
+export { ActorExit, type ActorRef, type ActorRefSync, ActorStoppedError, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type CellPhase, type DefectPhase, type DeferReplyResult, DuplicateActorError, type Durability, type DurabilityCommit, type EffectEvent, type ErrorEvent, Event, type EventReceivedEvent, type HandlerContext, type HasSlotKeys, type InspectionEvent, type Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, type Lifecycle, machine_d_exports as Machine, type MachineContext, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, type ProcessEventResult, type ProvideSlots, ProvisionValidationError, type Recovery, type RecoveryContext, type ReplyFields, type ReplyResult, type SimulationResult, Slot, type SlotCall, type SlotCalls, SlotCodecError, type SlotFnDef, type SlotHandler, type SlotInvocation, SlotProvisionError, type SlotRequest, type SlotResult, type SlotsDef, type SlotsSchema, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, Supervision, type SystemEvent, type SystemEventListener, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TimeoutConfig, type TracingInspectorOptions, type Transition, type TransitionEvent, type TransitionInfo, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };

package/dist/internal/runtime.d.ts

@@ -55,6 +55,12 @@ interface RuntimeHandle<S, E> {
   readonly isStopped: Effect.Effect<boolean>;
   /** Stop the runtime (interrupt event loop, clean up) */
   readonly stop: Effect.Effect<void>;
+  /**
+   * Start the runtime — fork event loop, background effects, spawn effects.
+   * Idempotent: first caller runs initialization, subsequent callers await completion.
+   * Events sent before start() are queued and processed when start() runs.
+   */
+  readonly start: Effect.Effect<void>;
   /** @internal — raw event queue for direct enqueue (actor.ts uses this for pendingReplies tracking) */
   readonly _queue: Queue.Queue<RuntimeQueuedEvent<E>>;
   /** @internal — stopped ref for direct access */
@@ -137,6 +143,19 @@ declare const createRuntime: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, SD extends SlotsDef>(machine: Machine<S, E, R, any, any, SD>, system: ActorSystem, config: RuntimeConfig<S, E>) => Effect.Effect<RuntimeHandle<S, E>, never, Scope.Scope | Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
+}, R, SD extends SlotsDef>(machine: Machine<S, E, R, any, any, SD>, system: ActorSystem, config: RuntimeConfig<S, E>) => Effect.Effect<{
+  stop: Effect.Effect<void, never, never>;
+  start: Effect.Effect<void, unknown, Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
+  send: (event: E) => Effect.Effect<void>;
+  sendWait: (event: E) => Effect.Effect<void, unknown>;
+  ask: (event: E) => Effect.Effect<unknown, NoReplyError>;
+  getState: Effect.Effect<S, never, never>;
+  stateRef: SubscriptionRef.SubscriptionRef<S>;
+  isStopped: Effect.Effect<boolean>;
+  _queue: Queue.Queue<RuntimeQueuedEvent<E>, never>;
+  _stoppedRef: Ref.Ref<boolean>;
+  exitDeferred: Deferred.Deferred<ActorExit<S>, never>;
+  actorScope: Scope.Closeable;
+}, never, Scope.Scope>;
 //#endregion
 export { ProcessQueuedResult, RuntimeCellResources, RuntimeConfig, RuntimeHandle, RuntimeLifecycleHooks, RuntimeQueuedEvent, createRuntime };

package/dist/internal/runtime.js

@@ -72,7 +72,6 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 		})
 	};
 	const stateScopeRef = { current: yield* Scope.make() };
-	const backgroundFibers = [];
 	const initEvent = { _tag: INTERNAL_INIT_EVENT };
 	const ctx = {
 		actorId,
@@ -82,59 +81,71 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 		system
 	};
 	const slots = machine._slots;
-	for (const bg of machine.backgroundEffects) {
-		const fiber = yield* bg.handler({
-			actorId,
-			state: machine.initial,
-			event: initEvent,
-			self,
-			slots,
-			system
-		}).pipe(Effect.provideService(machine.Context, ctx), Effect.forkIn(actorScope));
-		backgroundFibers.push(fiber);
-	}
-	if (lifecycle?.onInitialSpawnEffects !== void 0) yield* lifecycle.onInitialSpawnEffects(machine.initial);
 	const loopFiberRef = { current: void 0 };
-	const initialSpawnDefectSignal = (cause) => Deferred.succeed(exitDeferred, ActorExit.Defect(cause, "initial-spawn")).pipe(Effect.andThen(Ref.set(stoppedRef, true)), Effect.andThen(Effect.suspend(() => loopFiberRef.current !== void 0 ? Fiber.interrupt(loopFiberRef.current) : Effect.void)), Effect.asVoid);
-	yield* runSpawnEffects(machine, machine.initial, initEvent, self, stateScopeRef.current, system, actorId, hooks?.onError, initialSpawnDefectSignal).pipe(Effect.catchCause((cause) => {
-		return Effect.gen(function* () {
+	/** Set the exit deferred exactly once. */
+	const setExit = (exit) => Deferred.succeed(exitDeferred, exit).pipe(Effect.asVoid);
+	const startDeferred = yield* Deferred.make();
+	const startedRef = yield* Ref.make(false);
+	const start = Effect.gen(function* () {
+		if (yield* Ref.getAndSet(startedRef, true)) {
+			yield* Deferred.await(startDeferred);
+			return;
+		}
+		const backgroundFibers = [];
+		for (const bg of machine.backgroundEffects) {
+			const fiber = yield* bg.handler({
+				actorId,
+				state: machine.initial,
+				event: initEvent,
+				self,
+				slots,
+				system
+			}).pipe(Effect.provideService(machine.Context, ctx), Effect.forkIn(actorScope));
+			backgroundFibers.push(fiber);
+		}
+		if (lifecycle?.onInitialSpawnEffects !== void 0) yield* lifecycle.onInitialSpawnEffects(machine.initial);
+		const initialSpawnDefectSignal = (cause) => Deferred.succeed(exitDeferred, ActorExit.Defect(cause, "initial-spawn")).pipe(Effect.andThen(Ref.set(stoppedRef, true)), Effect.andThen(Effect.suspend(() => loopFiberRef.current !== void 0 ? Fiber.interrupt(loopFiberRef.current) : Effect.void)), Effect.asVoid);
+		yield* runSpawnEffects(machine, machine.initial, initEvent, self, stateScopeRef.current, system, actorId, hooks?.onError, initialSpawnDefectSignal).pipe(Effect.catchCause((cause) => {
+			return Effect.gen(function* () {
+				yield* Ref.set(stoppedRef, true);
+				yield* Scope.close(stateScopeRef.current, Exit.void);
+				yield* Scope.close(actorScope, Exit.void);
+				yield* Deferred.succeed(exitDeferred, ActorExit.Defect(cause, "initial-spawn"));
+				return yield* Effect.failCause(cause);
+			});
+		}));
+		if (machine.finalStates.has(machine.initial._tag)) {
+			if (lifecycle?.onFinal !== void 0) yield* lifecycle.onFinal(machine.initial);
 			yield* Ref.set(stoppedRef, true);
 			yield* Scope.close(stateScopeRef.current, Exit.void);
 			yield* Scope.close(actorScope, Exit.void);
-			yield* Deferred.succeed(exitDeferred, ActorExit.Defect(cause, "initial-spawn"));
-			return yield* Effect.failCause(cause);
-		});
-	}));
-	/** Set the exit deferred exactly once. */
-	const setExit = (exit) => Deferred.succeed(exitDeferred, exit).pipe(Effect.asVoid);
-	if (machine.finalStates.has(machine.initial._tag)) {
-		if (lifecycle?.onFinal !== void 0) yield* lifecycle.onFinal(machine.initial);
-		yield* Ref.set(stoppedRef, true);
-		yield* Scope.close(stateScopeRef.current, Exit.void);
-		yield* Scope.close(actorScope, Exit.void);
-		yield* setExit(ActorExit.Final(machine.initial));
-		return makeHandle(stateRef, stoppedRef, eventQueue, exitDeferred, actorScope);
-	}
-	const augmentedHooks = {
-		...hooks,
-		onSpawnDefect: (cause) => Deferred.succeed(exitDeferred, ActorExit.Defect(cause, "spawn")).pipe(Effect.andThen(Ref.set(stoppedRef, true)), Effect.andThen(Effect.suspend(() => loopFiberRef.current !== void 0 ? Fiber.interrupt(loopFiberRef.current) : Effect.void)), Effect.asVoid)
-	};
-	const loopFiber = yield* Effect.forkDetach(runtimeEventLoop(machine, stateRef, eventQueue, stoppedRef, self, stateScopeRef, actorId, system, exitDeferred, augmentedHooks, deferredReplyRef, lifecycle, config.wrapProcess, fork));
-	loopFiberRef.current = loopFiber;
-	if (backgroundFibers.length > 0) yield* Effect.raceAll(backgroundFibers.map((fiber) => Fiber.await(fiber).pipe(Effect.flatMap((exit) => {
-		if (exit._tag === "Failure" && !Cause.hasInterruptsOnly(exit.cause)) return setExit(ActorExit.Defect(exit.cause, "background")).pipe(Effect.andThen(Ref.set(stoppedRef, true)), Effect.andThen(Fiber.interrupt(loopFiber)));
-		return Effect.never;
-	})))).pipe(Effect.forkIn(actorScope));
-	yield* Effect.forkDetach(Effect.gen(function* () {
-		const loopExit = yield* Fiber.await(loopFiber);
-		if (loopExit._tag === "Success") yield* Scope.close(actorScope, Exit.void);
-		else yield* Scope.close(actorScope, loopExit);
-	}));
+			yield* setExit(ActorExit.Final(machine.initial));
+			yield* Deferred.succeed(startDeferred, void 0);
+			return;
+		}
+		const augmentedHooks = {
+			...hooks,
+			onSpawnDefect: (cause) => Deferred.succeed(exitDeferred, ActorExit.Defect(cause, "spawn")).pipe(Effect.andThen(Ref.set(stoppedRef, true)), Effect.andThen(Effect.suspend(() => loopFiberRef.current !== void 0 ? Fiber.interrupt(loopFiberRef.current) : Effect.void)), Effect.asVoid)
+		};
+		const loopFiber = yield* Effect.forkDetach(runtimeEventLoop(machine, stateRef, eventQueue, stoppedRef, self, stateScopeRef, actorId, system, exitDeferred, augmentedHooks, deferredReplyRef, lifecycle, config.wrapProcess, fork));
+		loopFiberRef.current = loopFiber;
+		if (backgroundFibers.length > 0) yield* Effect.raceAll(backgroundFibers.map((fiber) => Fiber.await(fiber).pipe(Effect.flatMap((exit) => {
+			if (exit._tag === "Failure" && !Cause.hasInterruptsOnly(exit.cause)) return setExit(ActorExit.Defect(exit.cause, "background")).pipe(Effect.andThen(Ref.set(stoppedRef, true)), Effect.andThen(Fiber.interrupt(loopFiber)));
+			return Effect.never;
+		})))).pipe(Effect.forkIn(actorScope));
+		yield* Effect.forkDetach(Effect.gen(function* () {
+			const loopExit = yield* Fiber.await(loopFiber);
+			if (loopExit._tag === "Success") yield* Scope.close(actorScope, Exit.void);
+			else yield* Scope.close(actorScope, loopExit);
+		}));
+		yield* Deferred.succeed(startDeferred, void 0);
+	}).pipe(Effect.catchCause((cause) => Deferred.failCause(startDeferred, cause).pipe(Effect.andThen(Effect.failCause(cause)))));
 	const stop = Effect.gen(function* () {
 		if (yield* Ref.get(stoppedRef)) return;
 		if (lifecycle?.onShutdown !== void 0) yield* lifecycle.onShutdown();
 		yield* Ref.set(stoppedRef, true);
-		yield* Fiber.interrupt(loopFiber);
+		const loopFiber = loopFiberRef.current;
+		if (loopFiber !== void 0) yield* Fiber.interrupt(loopFiber);
 		yield* Scope.close(stateScopeRef.current, Exit.void);
 		yield* Scope.close(actorScope, Exit.void);
 		yield* setExit(ActorExit.Stopped);
@@ -142,7 +153,8 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 	if (config.skipFinalizer !== true) yield* Effect.addFinalizer(() => stop);
 	return {
 		...makeHandle(stateRef, stoppedRef, eventQueue, exitDeferred, actorScope),
-		stop
+		stop,
+		start
 	};
 });
 /**
@@ -184,6 +196,7 @@ const makeHandle = (stateRef, stoppedRef, eventQueue, exitDeferred, actorScope)
 	stateRef,
 	isStopped: Ref.get(stoppedRef),
 	stop: Effect.void,
+	start: Effect.void,
 	_queue: eventQueue,
 	_stoppedRef: stoppedRef,
 	exitDeferred,

package/dist/machine.d.ts

@@ -10,7 +10,7 @@ import { Cause, Duration, Effect, Option, Schema, Scope, ServiceMap } from "effe
 
 //#region src/machine.d.ts
 declare namespace machine_d_exports {
-  export { BackgroundEffect, DeferReplyResult, HandlerContext, Machine, MachineRef, MakeConfig, PersistConfig, ReplyResult, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, make, materializeMachine, replay, reply, spawn };
+  export { BackgroundEffect, DeferReplyResult, Durability, DurabilityCommit, HandlerContext, Lifecycle, Machine, MachineRef, MakeConfig, Recovery, RecoveryContext, ReplyResult, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, make, materializeMachine, replay, reply, spawn };
 }
 /**
  * Self reference for sending events back to the machine
@@ -88,32 +88,39 @@ interface TaskOptions<State, Event, SD extends SlotsDef, A, E1, ES, EF> {
   readonly name?: string;
 }
 /**
- * Local persistence configuration for Machine.spawn.
+ * Recovery resolves the initial state for a generation. Runs during actor.start.
  *
- * Fully-resolved callbacks — no service dependency.
- * Separate from cluster EntityPersistence which uses a service-based adapter.
+ * For initial start (generation 0): loads persisted state.
+ * For supervision restart (generation 1+): reloads state after crash.
  */
-interface PersistConfig<S> {
-  /** Load saved state on actor start (and restart). Returns None for cold start. */
-  readonly load: () => Effect.Effect<Option.Option<S>>;
-  /** Save state after each transition. Runs inline (blocks next event). */
-  readonly save: (state: S) => Effect.Effect<void>;
-  /** Optional filter — return false to skip saving for this transition. */
+interface Recovery<S> {
+  readonly resolve: (ctx: RecoveryContext<S>) => Effect.Effect<Option.Option<S>>;
+}
+interface RecoveryContext<S> {
+  readonly actorId: string;
+  readonly generation: number;
+  readonly machineInitial: S;
+}
+/**
+ * Durability saves state after committed transitions. Runs during runtime.
+ */
+interface Durability<S, E> {
+  readonly save: (commit: DurabilityCommit<S, E>) => Effect.Effect<void>;
   readonly shouldSave?: (state: S, previousState: S) => boolean;
-  /**
-   * Called after load() returns Some(state). Inspect the restored state
-   * and decide how to proceed before the machine starts.
-   *
-   * Return Some(state) to use that state, or None to discard and start fresh.
-   * Called on both initial spawn and supervision restart.
-   * Receives `initial` (machine.initial) for comparison.
-   *
-   * Use cases: validate persisted state against external systems,
-   * migrate schema changes, downgrade to a safe state on partial corruption.
-   */
-  readonly onRestore?: (state: S, context: {
-    readonly initial: S;
-  }) => Effect.Effect<Option.Option<S>>;
+}
+interface DurabilityCommit<S, E> {
+  readonly actorId: string;
+  readonly generation: number;
+  readonly previousState: S;
+  readonly nextState: S;
+  readonly event: E;
+}
+/**
+ * Actor lifecycle configuration.
+ */
+interface Lifecycle<S, E> {
+  readonly recovery?: Recovery<S>;
+  readonly durability?: Durability<S, E>;
 }
 /**
  * Configuration for `.timeout()` — gen_statem-style state timeouts.
@@ -335,11 +342,11 @@ declare const make: typeof Machine.make;
  *   slots: { canRetry: ({ max }) => attempts < max },
  * });
  *
- * // With persistence
+ * // With lifecycle (recovery + durability)
  * const actor = yield* Machine.spawn(machine, {
- *   persist: {
- *     load: () => storage.get("actor-state"),
- *     save: (state) => storage.set("actor-state", state),
+ *   lifecycle: {
+ *     recovery: { resolve: (ctx) => storage.get("actor-state") },
+ *     durability: { save: (commit) => storage.set("actor-state", commit.nextState) },
  *   },
  * });
  * ```
@@ -353,7 +360,7 @@ declare const spawn: <S extends {
   hydrate?: S;
   slots?: ProvideSlots<SD, any>;
   supervision?: Supervision.Policy;
-  persist?: PersistConfig<S>;
+  lifecycle?: Lifecycle<S, E>;
 }) => Effect.Effect<ActorRef<S, E>, never, R>;
 declare const replay: {
   <S extends {
@@ -368,4 +375,4 @@ declare const replay: {
 declare const reply: <State, Reply>(state: State, reply: Reply) => ReplyResult<State, Reply>;
 declare const deferReply: <State>(state: State) => DeferReplyResult<State>;
 //#endregion
-export { BackgroundEffect, type DeferReplyResult, HandlerContext, Machine, MachineRef, MakeConfig, PersistConfig, type ReplyResult, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, machine_d_exports, make, materializeMachine, replay, reply, spawn };
+export { BackgroundEffect, type DeferReplyResult, Durability, DurabilityCommit, HandlerContext, Lifecycle, Machine, MachineRef, MakeConfig, Recovery, RecoveryContext, type ReplyResult, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, machine_d_exports, make, materializeMachine, replay, reply, spawn };