effect-machine 0.14.0 → 0.15.1

package/dist/machine.js

@@ -395,11 +395,11 @@ const make = 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) },
 *   },
 * });
 * ```
@@ -409,7 +409,7 @@ const spawn = Effect.fn("effect-machine.spawn")(function* (machine, idOrOptions)
 	const actor = yield* createActor(opts?.id ?? `actor-${(yield* Random.next).toString(36).slice(2)}`, materializeMachine(machine, opts?.slots), {
 		initialState: opts?.hydrate,
 		supervision: opts?.supervision,
-		persist: opts?.persist
+		lifecycle: opts?.lifecycle
 	});
 	const maybeScope = yield* Effect.serviceOption(Scope.Scope);
 	if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, actor.stop);

package/dist/schema.d.ts

@@ -12,14 +12,19 @@ type ReplySchemaSymbol = typeof ReplySchemaSymbol;
 type ReplyFields<F extends Schema.Struct.Fields, RS extends Schema.Schema<unknown>> = F & {
   readonly [ReplySchemaSymbol]: RS;
 };
+/**
+ * Payload fields that actually flow through constructors and runtime values.
+ * Reply schema metadata is type-only and must not leak into payload shapes.
+ */
+type PayloadFields<F extends Schema.Struct.Fields> = { readonly [K in keyof F as K extends ReplySchemaSymbol ? never : K]: F[K] };
 /**
  * Extract the TypeScript type from a TaggedStruct schema
  */
-type TaggedStructType<Tag extends string, Fields extends Schema.Struct.Fields> = Schema.Schema.Type<Schema.TaggedStruct<Tag, Fields>>;
+type TaggedStructType<Tag extends string, Fields extends Schema.Struct.Fields> = Schema.Schema.Type<Schema.TaggedStruct<Tag, PayloadFields<Fields>>>;
 /**
  * Build variant schemas type from definition
  */
-type VariantSchemas<D extends Record<string, Schema.Struct.Fields>> = { readonly [K in keyof D & string]: Schema.TaggedStruct<K, D[K]> };
+type VariantSchemas<D extends Record<string, Schema.Struct.Fields>> = { readonly [K in keyof D & string]: Schema.TaggedStruct<K, PayloadFields<D[K]>> };
 /**
  * Build union type from variant schemas.
  * Reply-bearing variants carry ReplyTypeBrand<R> for ask() inference.
@@ -50,8 +55,8 @@ type VariantReplyBrand<Fields extends Schema.Struct.Fields> = Fields extends {
  */
 type VariantConstructors<D extends Record<string, Schema.Struct.Fields>, Brand> = { readonly [K in keyof D & string]: IsEmptyFields<D[K]> extends true ? TaggedStructType<K, D[K]> & Brand & VariantReplyBrand<D[K]> & {
   readonly derive: (source: object) => TaggedStructType<K, D[K]> & Brand;
-} : ((args: Schema.Struct.Type<D[K]>) => TaggedStructType<K, D[K]> & Brand & VariantReplyBrand<D[K]>) & {
-  readonly derive: (source: object, partial?: Partial<Schema.Struct.Type<D[K]>>) => TaggedStructType<K, D[K]> & Brand;
+} : ((args: Schema.Struct.Type<PayloadFields<D[K]>>) => TaggedStructType<K, D[K]> & Brand & VariantReplyBrand<D[K]>) & {
+  readonly derive: (source: object, partial?: Partial<Schema.Struct.Type<PayloadFields<D[K]>>>) => TaggedStructType<K, D[K]> & Brand;
   readonly _tag: K;
 } };
 /**
@@ -111,7 +116,9 @@ interface MachineSchemaBase<D extends Record<string, Schema.Struct.Fields>, Bran
  * The D type parameter captures the definition, creating a unique brand
  * per distinct schema definition shape.
  */
-type MachineStateSchema<D extends Record<string, Schema.Struct.Fields>> = Schema.Codec<VariantsUnion<D> & FullStateBrand<D>, unknown, never, never> & MachineSchemaBase<D, FullStateBrand<D>> & VariantConstructors<D, FullStateBrand<D>>;
+type MachineStateSchema<D extends Record<string, Schema.Struct.Fields>> = Schema.Codec<VariantsUnion<D> & FullStateBrand<D>, unknown, never, never> & MachineSchemaBase<D, FullStateBrand<D>> & VariantConstructors<D, FullStateBrand<D>> & {
+  /** Unbranded schema for persistence — same structure without FullStateBrand. */readonly plain: Schema.Schema<VariantsUnion<D>>;
+};
 /**
  * Schema-first event definition (same structure as state, different brand)
  *

package/dist/schema.js

@@ -123,6 +123,7 @@ const createMachineSchema = (definition) => {
 		variants,
 		_definition,
 		_replySchemas: replySchemas,
+		plain: schema,
 		$is,
 		$match,
 		derive,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-machine",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/cevr/effect-machine.git"

package/v3/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 { Context, Deferred, Effect, Layer, Option, PubSub, Queue, Ref, Scope, Stream, SubscriptionRef } from "effect";
 
@@ -54,6 +54,12 @@ 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.
+   * Called automatically by `system.spawn`. For `Machine.spawn`, the caller
+   * must call `start` explicitly. Events sent before start() are queued.
+   */
+  readonly start: Effect.Effect<void>;
   /** Get current state snapshot. */
   readonly snapshot: Effect.Effect<State>;
   /** Check if current state matches tag. */
@@ -161,7 +167,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 +210,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 +222,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/v3/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
 */
@@ -242,7 +231,15 @@ 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;
+		let restartState = params.machine.initial;
+		if (params.lifecycle?.recovery !== void 0) {
+			const resolved = yield* params.lifecycle.recovery.resolve({
+				actorId: params.id,
+				generation: generation + 1,
+				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,6 +252,7 @@ const runSupervisionLoop = (params) => Effect.gen(function* () {
 		} }) : params.machine;
 		const newRuntime = yield* params.spawnGeneration(machineForRestart);
 		params.runtimeRef.current = newRuntime;
+		yield* newRuntime.start;
 		generation++;
 		if (params.onRestart !== void 0) yield* params.onRestart(generation, 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,6 +284,7 @@ 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 };
 	/** Build lifecycle hooks for a generation */
 	const buildLifecycle = () => {
@@ -304,10 +297,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) {
@@ -374,34 +374,62 @@ 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.forkDaemon(runSupervisionLoop({
-		supervision,
-		machine,
-		id,
-		runtimeRef,
-		terminalExitDeferred,
-		pendingReplies,
-		eventQueueRef,
-		stateRef,
-		stoppedRef,
-		childrenMap,
-		listeners,
-		spawnGeneration,
-		persist,
-		onRestart: options?.onRestart
-	}));
-	else yield* Effect.forkDaemon(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 supervisorFiberRef = { current: void 0 };
+	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.forkDaemon(runSupervisionLoop({
+			supervision,
+			machine,
+			id,
+			runtimeRef,
+			terminalExitDeferred,
+			pendingReplies,
+			eventQueueRef,
+			stateRef,
+			stoppedRef,
+			childrenMap,
+			listeners,
+			spawnGeneration,
+			lifecycle,
+			onRestart: options?.onRestart
+		}));
+		else {
+			const currentRuntime = runtimeRef.current;
+			if (currentRuntime !== void 0) yield* Effect.forkDaemon(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 +490,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 +500,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.catchAllCause((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/v3/dist/cluster/entity-machine.js

@@ -50,6 +50,7 @@ const EntityMachine = { layer: (entity, machine, options) => {
 			hooks: options?.hooks,
 			childIdPrefix: `${entityId}/`
 		});
+		yield* runtime.start;
 		if (persistCtx.adapter !== void 0) {
 			const { adapter: pAdapter, key } = persistCtx;
 			yield* Effect.addFinalizer(() => Effect.gen(function* () {

package/v3/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/v3/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>>;
+  _stoppedRef: Ref.Ref<boolean>;
+  exitDeferred: Deferred.Deferred<ActorExit<S>, never>;
+  actorScope: Scope.CloseableScope;
+}, never, Scope.Scope>;
 //#endregion
 export { ProcessQueuedResult, RuntimeCellResources, RuntimeConfig, RuntimeHandle, RuntimeLifecycleHooks, RuntimeQueuedEvent, createRuntime };

package/v3/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.catchAllCause((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.catchAllCause((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.forkDaemon(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.isInterruptedOnly(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.forkDaemon(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.forkDaemon(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.isInterruptedOnly(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.forkDaemon(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.catchAllCause((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,