effect-machine 0.13.0 → 0.15.0

package/README.md

@@ -39,14 +39,14 @@ const CheckoutEvent = Event({
   Cancel: {},
 });
 
-const CheckoutEffects = Slot.Effects({
-  chargeCard: { cartId: Schema.String, totalCents: Schema.Number },
+const CheckoutSlots = Slot.define({
+  chargeCard: Slot.fn({ cartId: Schema.String, totalCents: Schema.Number }),
 });
 
 const checkoutMachine = Machine.make({
   state: CheckoutState,
   event: CheckoutEvent,
-  effects: CheckoutEffects,
+  slots: CheckoutSlots,
   initial: CheckoutState.ReviewingCart({ cartId: "cart_123", totalCents: 4200 }),
 })
   .on(CheckoutState.ReviewingCart, CheckoutEvent.Submit, ({ state }) =>
@@ -61,8 +61,8 @@ const checkoutMachine = Machine.make({
   .onAny(CheckoutEvent.Cancel, ({ state }) =>
     CheckoutState.Failed.derive(state, { reason: "cancelled" }),
   )
-  .spawn(CheckoutState.ChargingCard, ({ effects, state }) =>
-    effects.chargeCard({ cartId: state.cartId, totalCents: state.totalCents }),
+  .spawn(CheckoutState.ChargingCard, ({ slots, state }) =>
+    slots.chargeCard({ cartId: state.cartId, totalCents: state.totalCents }),
   )
   .final(CheckoutState.Confirmed)
   .final(CheckoutState.Failed);
@@ -86,10 +86,11 @@ const actor =
   yield *
   Machine.spawn(checkoutMachine, {
     slots: {
-      chargeCard: ({ cartId, totalCents }, { self }) =>
+      chargeCard: ({ cartId, totalCents }) =>
         Effect.gen(function* () {
+          const ctx = yield* checkoutMachine.Context;
           const result = yield* PaymentService.charge(cartId, totalCents);
-          yield* self.send(
+          yield* ctx.self.send(
             result.ok
               ? CheckoutEvent.Charged({ receiptId: result.receiptId })
               : CheckoutEvent.Declined({ reason: result.error }),
@@ -97,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:
@@ -108,16 +110,21 @@ 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* () {
   const actor = yield* Machine.spawn(checkoutMachine, {
     slots: {
-      chargeCard: ({ cartId }, { self }) =>
-        self.send(CheckoutEvent.Charged({ receiptId: `rcpt_${cartId}` })),
+      chargeCard: ({ cartId }) =>
+        checkoutMachine.Context.pipe(
+          Effect.flatMap((ctx) =>
+            ctx.self.send(CheckoutEvent.Charged({ receiptId: `rcpt_${cartId}` })),
+          ),
+        ),
     },
   });
+  yield* actor.start;
 
   yield* actor.send(CheckoutEvent.Submit);
   const finalState = yield* actor.awaitFinal;
@@ -128,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(...)`)
@@ -135,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

@@ -1,9 +1,9 @@
 import { ExtractReply, ReplyTypeBrand } from "./internal/brands.js";
 import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.js";
-import { EffectsDef, GuardsDef } from "./slot.js";
+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 } 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. */
@@ -158,8 +167,10 @@ interface ActorSystem {
     readonly _tag: string;
   }, E extends {
     readonly _tag: string;
-  }, R>(id: string, machine: Machine<S, E, R, any, any, any, any>, options?: {
+  }, 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 lifecycle?: Lifecycle<S, E>;
   }) => Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>;
   /**
    * Get an existing actor by ID
@@ -202,7 +213,7 @@ declare const buildActorRefCore: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, any, any, GD, EFD>, 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.
@@ -211,9 +222,10 @@ declare const createActor: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, options?: {
+}, R, SD extends SlotsDef>(id: string, machine: Machine<S, E, R, any, any, SD>, options?: {
   initialState?: S;
-  supervision?: Supervision.Policy; /** @internal Called by system after each restart — emits ActorRestarted system event */
+  supervision?: Supervision.Policy;
+  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

@@ -1,7 +1,8 @@
-import { Inspector } from "./inspection.js";
+import { ActorStoppedError, DuplicateActorError } from "./errors.js";
 import { processEventCore, resolveTransition, runSpawnEffects } from "./internal/transition.js";
 import { emitWithTimestamp } from "./internal/inspection.js";
-import { ActorStoppedError, DuplicateActorError } from "./errors.js";
+import { Inspector } from "./inspection.js";
+import { materializeMachine } from "./machine.js";
 import { createRuntime } from "./internal/runtime.js";
 import { Cause, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Schedule, Scope, Semaphore, ServiceMap, Stream, SubscriptionRef } from "effect";
 //#region src/actor.ts
@@ -28,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);
@@ -115,6 +116,7 @@ const buildActorRefCore = (id, machine, stateRef, eventQueueRef, stoppedRef, lis
 		ask,
 		state: stateRef,
 		stop,
+		start,
 		snapshot,
 		matches,
 		can,
@@ -190,33 +192,87 @@ const buildInspectionHooks = (actorId, inspector) => ({
 	}))
 });
 /**
+* Resolve actor system from context, creating an implicit one if none exists.
+* @internal
+*/
+const resolveActorSystem = Effect.fn("effect-machine.resolveActorSystem")(function* () {
+	const existingSystem = yield* Effect.serviceOption(ActorSystem);
+	if (Option.isSome(existingSystem)) return {
+		system: existingSystem.value,
+		implicitSystemScope: void 0
+	};
+	const scope = yield* Scope.make();
+	return {
+		system: yield* make().pipe(Effect.provideService(Scope.Scope, scope)),
+		implicitSystemScope: scope
+	};
+});
+/**
+* Run the supervision loop for a supervised actor.
+* Observes exit deferred, applies restart policy, resets cell resources on restart.
+* @internal
+*/
+const runSupervisionLoop = (params) => Effect.gen(function* () {
+	const step = yield* Schedule.toStepWithSleep(params.supervision.schedule);
+	while (true) {
+		const currentRuntime = params.runtimeRef.current;
+		if (currentRuntime === void 0) return;
+		const generationExit = yield* Deferred.await(currentRuntime.exitDeferred);
+		if (generationExit._tag !== "Defect") {
+			yield* Deferred.succeed(params.terminalExitDeferred, generationExit);
+			return;
+		}
+		if (params.supervision.shouldRestart !== void 0 && !params.supervision.shouldRestart(generationExit)) {
+			yield* Deferred.succeed(params.terminalExitDeferred, generationExit);
+			return;
+		}
+		if ((yield* step(generationExit).pipe(Effect.exit))._tag === "Failure") {
+			yield* Deferred.succeed(params.terminalExitDeferred, generationExit);
+			return;
+		}
+		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);
+		yield* SubscriptionRef.set(params.stateRef, restartState);
+		yield* Ref.set(params.stoppedRef, false);
+		params.childrenMap.clear();
+		const machineForRestart = restartState !== params.machine.initial ? Object.create(params.machine, { initial: {
+			value: restartState,
+			enumerable: true
+		} }) : params.machine;
+		const newRuntime = yield* params.spawnGeneration(machineForRestart);
+		params.runtimeRef.current = newRuntime;
+		yield* newRuntime.start;
+		if (params.onRestart !== void 0) yield* params.onRestart(nextGeneration, generationExit);
+		notifyListeners(params.listeners, restartState);
+	}
+});
+/**
 * Create and start an actor for a machine.
 * Delegates to the shared runtime kernel with actor-specific lifecycle hooks.
 */
 const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machine, options) {
+	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 existingSystem = yield* Effect.serviceOption(ActorSystem);
-	let system;
-	let implicitSystemScope;
-	if (Option.isSome(existingSystem)) system = existingSystem.value;
-	else {
-		const scope = yield* Scope.make();
-		system = yield* make().pipe(Effect.provideService(Scope.Scope, scope));
-		implicitSystemScope = scope;
-	}
+	const { system, implicitSystemScope } = yield* resolveActorSystem();
 	const inspectorValue = Option.getOrUndefined(yield* Effect.serviceOption(Inspector));
 	const childrenMap = /* @__PURE__ */ new Map();
 	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,
@@ -228,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) => ({
@@ -240,8 +298,18 @@ 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 (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) {
 					yield* Effect.annotateCurrentSpan("effect_machine.state.from", result.previousState._tag);
@@ -293,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,
@@ -307,49 +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(Effect.gen(function* () {
-		const step = yield* Schedule.toStepWithSleep(supervision.schedule);
-		let generation = 0;
-		while (true) {
-			const currentRuntime = runtimeRef.current;
-			if (currentRuntime === void 0) return;
-			const generationExit = yield* Deferred.await(currentRuntime.exitDeferred);
-			if (generationExit._tag !== "Defect") {
-				yield* Deferred.succeed(terminalExitDeferred, generationExit);
-				return;
-			}
-			if (supervision.shouldRestart !== void 0 && !supervision.shouldRestart(generationExit)) {
-				yield* Deferred.succeed(terminalExitDeferred, generationExit);
-				return;
-			}
-			if ((yield* step(generationExit).pipe(Effect.exit))._tag === "Failure") {
-				yield* Deferred.succeed(terminalExitDeferred, generationExit);
-				return;
-			}
-			yield* settlePendingReplies(pendingReplies, id);
-			const freshQueue = yield* Queue.unbounded();
-			yield* Ref.set(eventQueueRef, freshQueue);
-			yield* SubscriptionRef.set(stateRef, machine.initial);
-			yield* Ref.set(stoppedRef, false);
-			childrenMap.clear();
-			runtimeRef.current = yield* spawnGeneration(machine);
-			generation++;
-			if (options?.onRestart !== void 0) yield* options.onRestart(generation, generationExit);
-			notifyListeners(listeners, machine.initial);
-		}
-	}));
-	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(() => {
@@ -406,9 +492,11 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 	});
 	const spawnRegular = Effect.fn("effect-machine.actorSystem.spawnRegular")(function* (id, machine, spawnOptions) {
 		if (MutableHashMap.has(actorsMap, id)) return yield* new DuplicateActorError({ actorId: id });
+		const materialized = spawnOptions?.slots !== void 0 ? materializeMachine(machine, spawnOptions.slots) : machine;
 		let actorRef;
-		const actor = yield* createActor(id, machine, {
+		const actor = yield* createActor(id, materialized, {
 			supervision: spawnOptions?.supervision,
+			lifecycle: spawnOptions?.lifecycle,
 			onRestart: spawnOptions?.supervision !== void 0 ? (generation, exit) => actorRef !== void 0 ? emitSystemEvent({
 				_tag: "ActorRestarted",
 				id,
@@ -418,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.d.ts

@@ -65,7 +65,7 @@ declare const EntityMachine: {
     readonly _tag: string;
   }, E extends {
     readonly _tag: string;
-  }, R, EntityType extends string, Rpcs extends Rpc.Any>(entity: Entity.Entity<EntityType, Rpcs>, machine: Machine<S, E, R, any, any, any, any>, options?: EntityMachineOptions<S, E>) => Layer.Layer<never, never, R>;
+  }, R, EntityType extends string, Rpcs extends Rpc.Any>(entity: Entity.Entity<EntityType, Rpcs>, machine: Machine<S, E, R, any, any, any>, options?: EntityMachineOptions<S, E>) => Layer.Layer<never, never, R>;
 };
 //#endregion
 export { EntityMachine, EntityMachineOptions };

package/dist/cluster/entity-machine.js

@@ -1,6 +1,6 @@
+import { replay } from "../machine.js";
 import { createRuntime } from "../internal/runtime.js";
 import { ActorSystem, makeSystem } from "../actor.js";
-import { replay } from "../machine.js";
 import { PersistenceAdapter } from "./persistence.js";
 import { Clock, Effect, Option, Queue, Ref, Stream, SubscriptionRef } from "effect";
 import { Entity } from "effect/unstable/cluster";
@@ -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/cluster/to-entity.d.ts

@@ -61,7 +61,7 @@ declare const toEntity: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R>(machine: Machine<S, E, R, any, any, any, any>, options: ToEntityOptions) => Entity.Entity<string, Rpc.Rpc<"Send", Schema.Struct<{
+}, R>(machine: Machine<S, E, R, any, any, any>, options: ToEntityOptions) => Entity.Entity<string, Rpc.Rpc<"Send", Schema.Struct<{
   event: Schema.Schema<E>;
 }>, Schema.Schema<S>, Schema.Never, never, never> | Rpc.Rpc<"Ask", Schema.Struct<{
   event: Schema.Schema<E>;

package/dist/errors.d.ts

@@ -24,7 +24,7 @@ declare const MissingMatchHandlerError_base: Schema.ErrorClass<MissingMatchHandl
 declare class MissingMatchHandlerError extends MissingMatchHandlerError_base {}
 declare const SlotProvisionError_base: Schema.ErrorClass<SlotProvisionError, Schema.TaggedStruct<"SlotProvisionError", {
   readonly slotName: Schema.String;
-  readonly slotType: Schema.Literals<readonly ["guard", "effect"]>;
+  readonly slotType: Schema.Literal<"slot">;
 }>, _$effect_Cause0.YieldableError>;
 /** Slot handler not found at runtime (internal error) */
 declare class SlotProvisionError extends SlotProvisionError_base {}
@@ -55,6 +55,13 @@ declare const PersistenceError_base: Schema.ErrorClass<PersistenceError, Schema.
 }>, _$effect_Cause0.YieldableError>;
 /** Persistence adapter operation failed */
 declare class PersistenceError extends PersistenceError_base {}
+declare const SlotCodecError_base: Schema.ErrorClass<SlotCodecError, Schema.TaggedStruct<"SlotCodecError", {
+  readonly slotName: Schema.String;
+  readonly phase: Schema.Literals<readonly ["input", "output"]>;
+  readonly message: Schema.String;
+}>, _$effect_Cause0.YieldableError>;
+/** Slot input/output schema validation failed */
+declare class SlotCodecError extends SlotCodecError_base {}
 declare const VersionConflictError_base: Schema.ErrorClass<VersionConflictError, Schema.TaggedStruct<"VersionConflictError", {
   readonly expected: Schema.Number;
   readonly actual: Schema.Number;
@@ -62,4 +69,4 @@ declare const VersionConflictError_base: Schema.ErrorClass<VersionConflictError,
 /** Optimistic locking failure — stored version doesn't match expected */
 declare class VersionConflictError extends VersionConflictError_base {}
 //#endregion
-export { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, SlotProvisionError, VersionConflictError };
+export { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, SlotCodecError, SlotProvisionError, VersionConflictError };

package/dist/errors.js

@@ -21,7 +21,7 @@ var MissingMatchHandlerError = class extends Schema.TaggedErrorClass()("MissingM
 /** Slot handler not found at runtime (internal error) */
 var SlotProvisionError = class extends Schema.TaggedErrorClass()("SlotProvisionError", {
 	slotName: Schema.String,
-	slotType: Schema.Literals(["guard", "effect"])
+	slotType: Schema.Literal("slot")
 }) {};
 /** Slot provision validation failed — missing or extra handlers */
 var ProvisionValidationError = class extends Schema.TaggedErrorClass()("ProvisionValidationError", {
@@ -39,10 +39,16 @@ var NoReplyError = class extends Schema.TaggedErrorClass()("NoReplyError", {
 }) {};
 /** Persistence adapter operation failed */
 var PersistenceError = class extends Schema.TaggedErrorClass()("PersistenceError", { message: Schema.String }) {};
+/** Slot input/output schema validation failed */
+var SlotCodecError = class extends Schema.TaggedErrorClass()("SlotCodecError", {
+	slotName: Schema.String,
+	phase: Schema.Literals(["input", "output"]),
+	message: Schema.String
+}) {};
 /** Optimistic locking failure — stored version doesn't match expected */
 var VersionConflictError = class extends Schema.TaggedErrorClass()("VersionConflictError", {
 	expected: Schema.Number,
 	actual: Schema.Number
 }) {};
 //#endregion
-export { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, SlotProvisionError, VersionConflictError };
+export { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, SlotCodecError, SlotProvisionError, VersionConflictError };

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { DeferReplyResult, ReplyResult } from "./internal/utils.js";
 import { Event, MachineEventSchema, MachineStateSchema, ReplyFields, State } from "./schema.js";
-import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, SlotProvisionError, VersionConflictError } from "./errors.js";
-import { EffectHandlers, EffectSlot, EffectSlots, EffectsDef, EffectsSchema, GuardHandlers, GuardSlot, GuardSlots, GuardsDef, GuardsSchema, MachineContext, Slot } from "./slot.js";
+import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, SlotCodecError, SlotProvisionError, VersionConflictError } from "./errors.js";
+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, ProvideHandlers, SlotContext, 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 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, PersistenceError, type ProcessEventResult, type ProvideHandlers, ProvisionValidationError, type ReplyFields, type ReplyResult, type SimulationResult, Slot, type SlotContext, type EffectHandlers as SlotEffectHandlers, type EffectSlot as SlotEffectSlot, SlotProvisionError, 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/index.js

@@ -1,9 +1,9 @@
+import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, SlotCodecError, SlotProvisionError, VersionConflictError } from "./errors.js";
 import { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
-import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, SlotProvisionError, VersionConflictError } from "./errors.js";
-import { ActorExit, Supervision } from "./supervision.js";
-import { ActorSystem, Default } from "./actor.js";
 import { Slot } from "./slot.js";
 import { machine_exports } from "./machine.js";
+import { ActorExit, Supervision } from "./supervision.js";
+import { ActorSystem, Default } from "./actor.js";
 import { Event, State } from "./schema.js";
 import { assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
-export { ActorExit, ActorStoppedError, Default as ActorSystemDefault, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, Slot, SlotProvisionError, State, Supervision, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };
+export { ActorExit, ActorStoppedError, Default as ActorSystemDefault, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, Slot, SlotCodecError, SlotProvisionError, State, Supervision, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };

package/dist/internal/runtime.d.ts

@@ -1,5 +1,5 @@
 import { NoReplyError } from "../errors.js";
-import { EffectsDef, GuardsDef, MachineContext } from "../slot.js";
+import { MachineContext, SlotsDef } from "../slot.js";
 import { ActorExit } from "../supervision.js";
 import { ProcessEventHooks, ProcessEventResult } from "./transition.js";
 import { Machine, MachineRef } from "../machine.js";
@@ -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, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, any, any, GD, EFD>, 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 };