effect-machine 0.1.0 → 0.2.0

package/src/actor.ts

@@ -7,7 +7,7 @@
  * - Actor creation and event loop
  */
 import {
-  Clock,
+  Cause,
   Context,
   Effect,
   Exit,
@@ -16,22 +16,28 @@ import {
   MutableHashMap,
   Option,
   Queue,
+  Ref,
   Scope,
+  Stream,
   SubscriptionRef,
 } from "effect";
-import type { Stream } from "effect";
 
 import type { Machine, MachineRef } from "./machine.js";
-import type { InspectionEvent, Inspector } from "./inspection.js";
+import type { Inspector } from "./inspection.js";
 import { Inspector as InspectorTag } from "./inspection.js";
 import { processEventCore, runSpawnEffects, resolveTransition } from "./internal/transition.js";
-import type { ProcessEventHooks } from "./internal/transition.js";
+import type { ProcessEventError, ProcessEventHooks } from "./internal/transition.js";
+import { emitWithTimestamp } from "./internal/inspection.js";
 
 // Re-export for external use (cluster, persistence)
 export { resolveTransition, runSpawnEffects, processEventCore } from "./internal/transition.js";
-export type { ProcessEventHooks, ProcessEventResult } from "./internal/transition.js";
+export type {
+  ProcessEventError,
+  ProcessEventHooks,
+  ProcessEventResult,
+} from "./internal/transition.js";
 import type { GuardsDef, EffectsDef } from "./slot.js";
-import { DuplicateActorError } from "./errors.js";
+import { DuplicateActorError, UnprovidedSlotsError } from "./errors.js";
 import { INTERNAL_INIT_EVENT } from "./internal/utils.js";
 import type {
   ActorMetadata,
@@ -111,6 +117,24 @@ export interface ActorRef<State extends { readonly _tag: string }, Event> {
    */
   readonly changes: Stream.Stream<State>;
 
+  /**
+   * Wait for a state that matches predicate (includes current snapshot)
+   */
+  readonly waitFor: (predicate: (state: State) => boolean) => Effect.Effect<State>;
+
+  /**
+   * Wait for a final state (includes current snapshot)
+   */
+  readonly awaitFinal: Effect.Effect<State>;
+
+  /**
+   * Send event and wait for predicate or final state
+   */
+  readonly sendAndWait: (
+    event: Event,
+    predicate?: (state: State) => boolean,
+  ) => Effect.Effect<State>;
+
   /**
    * Subscribe to state changes (sync callback)
    * Returns unsubscribe function
@@ -162,15 +186,15 @@ export interface ActorSystem {
       id: string,
       // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Schema fields need wide acceptance
       machine: Machine<S, E, R, any, any, GD, EFD>,
-    ): Effect.Effect<ActorRef<S, E>, DuplicateActorError, R | Scope.Scope>;
+    ): Effect.Effect<ActorRef<S, E>, DuplicateActorError | UnprovidedSlotsError, R | Scope.Scope>;
 
     // Persistent machine overload
     <S extends { readonly _tag: string }, E extends { readonly _tag: string }, R>(
       id: string,
       machine: PersistentMachine<S, E, R>,
     ): Effect.Effect<
-      PersistentActorRef<S, E>,
-      PersistenceError | VersionConflictError | DuplicateActorError,
+      PersistentActorRef<S, E, R>,
+      PersistenceError | VersionConflictError | DuplicateActorError | UnprovidedSlotsError,
       R | Scope.Scope | PersistenceAdapterTag
     >;
   };
@@ -193,8 +217,8 @@ export interface ActorSystem {
     id: string,
     machine: PersistentMachine<S, E, R>,
   ) => Effect.Effect<
-    Option.Option<PersistentActorRef<S, E>>,
-    PersistenceError | DuplicateActorError,
+    Option.Option<PersistentActorRef<S, E, R>>,
+    PersistenceError | DuplicateActorError | UnprovidedSlotsError,
     R | Scope.Scope | PersistenceAdapterTag
   >;
 
@@ -243,7 +267,7 @@ export interface ActorSystem {
   >(
     ids: ReadonlyArray<string>,
     machine: PersistentMachine<S, E, R>,
-  ) => Effect.Effect<RestoreResult<S, E>, never, R | Scope.Scope | PersistenceAdapterTag>;
+  ) => Effect.Effect<RestoreResult<S, E, R>, never, R | Scope.Scope | PersistenceAdapterTag>;
 
   /**
    * Restore all persisted actors for a machine type.
@@ -265,7 +289,7 @@ export interface ActorSystem {
     machine: PersistentMachine<S, E, R>,
     options?: { filter?: (meta: ActorMetadata) => boolean },
   ) => Effect.Effect<
-    RestoreResult<S, E>,
+    RestoreResult<S, E, R>,
     PersistenceError,
     R | Scope.Scope | PersistenceAdapterTag
   >;
@@ -288,7 +312,11 @@ export type Listeners<S> = Set<(state: S) => void>;
  */
 export const notifyListeners = <S>(listeners: Listeners<S>, state: S): void => {
   for (const listener of listeners) {
-    listener(state);
+    try {
+      listener(state);
+    } catch {
+      // Ignore listener failures to avoid crashing the actor loop
+    }
   }
 };
 
@@ -307,50 +335,84 @@ export const buildActorRefCore = <
   machine: Machine<S, E, R, any, any, GD, EFD>,
   stateRef: SubscriptionRef.SubscriptionRef<S>,
   eventQueue: Queue.Queue<E>,
+  stoppedRef: Ref.Ref<boolean>,
   listeners: Listeners<S>,
   stop: Effect.Effect<void>,
-): ActorRef<S, E> =>
-  ({
+): ActorRef<S, E> => {
+  const send = Effect.fn("effect-machine.actor.send")(function* (event: E) {
+    const stopped = yield* Ref.get(stoppedRef);
+    if (stopped) {
+      return;
+    }
+    yield* Queue.offer(eventQueue, event);
+  });
+
+  const snapshot = SubscriptionRef.get(stateRef).pipe(
+    Effect.withSpan("effect-machine.actor.snapshot"),
+  );
+
+  const matches = Effect.fn("effect-machine.actor.matches")(function* (tag: S["_tag"]) {
+    const state = yield* SubscriptionRef.get(stateRef);
+    return state._tag === tag;
+  });
+
+  const can = Effect.fn("effect-machine.actor.can")(function* (event: E) {
+    const state = yield* SubscriptionRef.get(stateRef);
+    return resolveTransition(machine, state, event) !== undefined;
+  });
+
+  const waitFor = Effect.fn("effect-machine.actor.waitFor")(function* (
+    predicate: (state: S) => boolean,
+  ) {
+    const current = yield* SubscriptionRef.get(stateRef);
+    if (predicate(current)) {
+      return current;
+    }
+    const next = yield* stateRef.changes.pipe(Stream.filter(predicate), Stream.runHead);
+    return Option.getOrElse(next, () => current);
+  });
+
+  const awaitFinal = waitFor((state) => machine.finalStates.has(state._tag)).pipe(
+    Effect.withSpan("effect-machine.actor.awaitFinal"),
+  );
+
+  const sendAndWait = Effect.fn("effect-machine.actor.sendAndWait")(function* (
+    event: E,
+    predicate?: (state: S) => boolean,
+  ) {
+    yield* send(event);
+    if (predicate !== undefined) {
+      return yield* waitFor(predicate);
+    }
+    return yield* awaitFinal;
+  });
+
+  return {
     id,
-    send: (event) => Queue.offer(eventQueue, event),
+    send,
     state: stateRef,
     stop,
-    snapshot: SubscriptionRef.get(stateRef),
+    snapshot,
     snapshotSync: () => Effect.runSync(SubscriptionRef.get(stateRef)),
-    matches: (tag) => Effect.map(SubscriptionRef.get(stateRef), (s) => s._tag === tag),
+    matches,
     matchesSync: (tag) => Effect.runSync(SubscriptionRef.get(stateRef))._tag === tag,
-    can: (event) =>
-      Effect.map(
-        SubscriptionRef.get(stateRef),
-        (s) => resolveTransition(machine, s, event) !== undefined,
-      ),
+    can,
     canSync: (event) => {
       const state = Effect.runSync(SubscriptionRef.get(stateRef));
       return resolveTransition(machine, state, event) !== undefined;
     },
     changes: stateRef.changes,
+    waitFor,
+    awaitFinal,
+    sendAndWait,
     subscribe: (fn) => {
       listeners.add(fn);
       return () => {
         listeners.delete(fn);
       };
     },
-  });
-
-// ============================================================================
-// Inspection Helpers
-// ============================================================================
-
-/** Emit an inspection event with timestamp from Clock */
-const emitWithTimestamp = <S, E>(
-  inspector: Inspector<S, E> | undefined,
-  makeEvent: (timestamp: number) => InspectionEvent<S, E>,
-): Effect.Effect<void> =>
-  inspector === undefined
-    ? Effect.void
-    : Effect.flatMap(Clock.currentTimeMillis, (timestamp) =>
-        Effect.sync(() => inspector.onInspect(makeEvent(timestamp))),
-      );
+  };
+};
 
 // ============================================================================
 // Actor Creation and Event Loop
@@ -359,143 +421,142 @@ const emitWithTimestamp = <S, E>(
 /**
  * Create and start an actor for a machine
  */
-export const createActor = <
+export const createActor = Effect.fn("effect-machine.actor.spawn")(function* <
   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>,
-): Effect.Effect<ActorRef<S, E>, never, R> =>
-  Effect.withSpan("effect-machine.actor.spawn", {
-    attributes: { "effect_machine.actor.id": id },
-  })(
-    Effect.gen(function* () {
-      // Get optional inspector from context
-      const inspectorValue = Option.getOrUndefined(yield* Effect.serviceOption(InspectorTag)) as
-        | Inspector<S, E>
-        | undefined;
-
-      // Create self reference for sending events
-      const eventQueue = yield* Queue.unbounded<E>();
-      const self: MachineRef<E> = {
-        send: (event) => Queue.offer(eventQueue, event),
-      };
-
-      // Annotate span with initial state
-      yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", machine.initial._tag);
+>(id: string, machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>) {
+  yield* Effect.annotateCurrentSpan("effect_machine.actor.id", id);
 
-      // Emit spawn event
-      yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
-        type: "@machine.spawn",
-        actorId: id,
-        initialState: machine.initial,
-        timestamp,
-      }));
-
-      // Initialize state
-      const stateRef = yield* SubscriptionRef.make(machine.initial);
-      const listeners: Listeners<S> = new Set();
-
-      // Fork background effects (run for entire machine lifetime)
-      const backgroundFibers: Fiber.Fiber<void, never>[] = [];
-      const initEvent = { _tag: INTERNAL_INIT_EVENT } as E;
-      const { effects: effectSlots } = machine._createSlotAccessors({
-        state: machine.initial,
-        event: initEvent,
-        self,
-      });
+  const missing = machine._missingSlots();
+  if (missing.length > 0) {
+    return yield* new UnprovidedSlotsError({ slots: missing });
+  }
 
-      for (const bg of machine.backgroundEffects) {
-        const fiber = yield* Effect.fork(
-          bg.handler({ state: machine.initial, event: initEvent, self, effects: effectSlots }),
-        );
-        backgroundFibers.push(fiber);
+  // Get optional inspector from context
+  const inspectorValue = Option.getOrUndefined(yield* Effect.serviceOption(InspectorTag)) as
+    | Inspector<S, E>
+    | undefined;
+
+  // Create self reference for sending events
+  const eventQueue = yield* Queue.unbounded<E>();
+  const stoppedRef = yield* Ref.make(false);
+  const self: MachineRef<E> = {
+    send: Effect.fn("effect-machine.actor.self.send")(function* (event: E) {
+      const stopped = yield* Ref.get(stoppedRef);
+      if (stopped) {
+        return;
       }
+      yield* Queue.offer(eventQueue, event);
+    }),
+  };
 
-      // Create state scope for initial state's spawn effects
-      const stateScopeRef: { current: Scope.CloseableScope } = {
-        current: yield* Scope.make(),
-      };
+  // Annotate span with initial state
+  yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", machine.initial._tag);
+
+  // Emit spawn event
+  yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
+    type: "@machine.spawn",
+    actorId: id,
+    initialState: machine.initial,
+    timestamp,
+  }));
+
+  // Initialize state
+  const stateRef = yield* SubscriptionRef.make(machine.initial);
+  const listeners: Listeners<S> = new Set();
+
+  // Fork background effects (run for entire machine lifetime)
+  const backgroundFibers: Fiber.Fiber<void, never>[] = [];
+  const initEvent = { _tag: INTERNAL_INIT_EVENT } as E;
+  const ctx = { state: machine.initial, event: initEvent, self };
+  const { effects: effectSlots } = machine._slots;
+
+  for (const bg of machine.backgroundEffects) {
+    const fiber = yield* Effect.fork(
+      bg
+        .handler({ state: machine.initial, event: initEvent, self, effects: effectSlots })
+        .pipe(Effect.provideService(machine.Context, ctx)),
+    );
+    backgroundFibers.push(fiber);
+  }
 
-      // Run initial spawn effects
-      yield* runSpawnEffectsWithInspection(
-        machine,
-        machine.initial,
-        initEvent,
-        self,
-        stateScopeRef.current,
-        id,
-        inspectorValue,
-      );
-
-      // Check if initial state (after always) is final
-      if (machine.finalStates.has(machine.initial._tag)) {
-        // Close state scope and interrupt background effects
-        yield* Scope.close(stateScopeRef.current, Exit.void);
-        yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
-        yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
-          type: "@machine.stop",
-          actorId: id,
-          finalState: machine.initial,
-          timestamp,
-        }));
-        return buildActorRefCore(
-          id,
-          machine,
-          stateRef,
-          eventQueue,
-          listeners,
-          Queue.shutdown(eventQueue).pipe(Effect.asVoid),
-        );
-      }
+  // Create state scope for initial state's spawn effects
+  const stateScopeRef: { current: Scope.CloseableScope } = {
+    current: yield* Scope.make(),
+  };
 
-      // Start the event loop
-      const loopFiber = yield* Effect.fork(
-        eventLoop(
-          machine,
-          stateRef,
-          eventQueue,
-          self,
-          listeners,
-          backgroundFibers,
-          stateScopeRef,
-          id,
-          inspectorValue,
-        ),
-      );
+  // Run initial spawn effects
+  yield* runSpawnEffectsWithInspection(
+    machine,
+    machine.initial,
+    initEvent,
+    self,
+    stateScopeRef.current,
+    id,
+    inspectorValue,
+  );
 
-      return buildActorRefCore(
-        id,
-        machine,
-        stateRef,
-        eventQueue,
-        listeners,
-        Effect.gen(function* () {
-          const finalState = yield* SubscriptionRef.get(stateRef);
-          yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
-            type: "@machine.stop",
-            actorId: id,
-            finalState,
-            timestamp,
-          }));
-          yield* Queue.shutdown(eventQueue);
-          yield* Fiber.interrupt(loopFiber);
-          // Close state scope (interrupts spawn fibers)
-          yield* Scope.close(stateScopeRef.current, Exit.void);
-          // Interrupt background effects (in parallel)
-          yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
-        }).pipe(Effect.asVoid),
-      );
-    }),
+  // Check if initial state (after always) is final
+  if (machine.finalStates.has(machine.initial._tag)) {
+    // Close state scope and interrupt background effects
+    yield* Scope.close(stateScopeRef.current, Exit.void);
+    yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+    yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
+      type: "@machine.stop",
+      actorId: id,
+      finalState: machine.initial,
+      timestamp,
+    }));
+    yield* Ref.set(stoppedRef, true);
+    const stop = Ref.set(stoppedRef, true).pipe(
+      Effect.withSpan("effect-machine.actor.stop"),
+      Effect.asVoid,
+    );
+    return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, stop);
+  }
+
+  // Start the event loop
+  const loopFiber = yield* Effect.fork(
+    eventLoop(
+      machine,
+      stateRef,
+      eventQueue,
+      stoppedRef,
+      self,
+      listeners,
+      backgroundFibers,
+      stateScopeRef,
+      id,
+      inspectorValue,
+    ),
   );
 
+  const stop = Effect.gen(function* () {
+    const finalState = yield* SubscriptionRef.get(stateRef);
+    yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
+      type: "@machine.stop",
+      actorId: id,
+      finalState,
+      timestamp,
+    }));
+    yield* Ref.set(stoppedRef, true);
+    yield* Fiber.interrupt(loopFiber);
+    // Close state scope (interrupts spawn fibers)
+    yield* Scope.close(stateScopeRef.current, Exit.void);
+    // Interrupt background effects (in parallel)
+    yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+  }).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid);
+
+  return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, stop);
+});
+
 /**
  * Main event loop for the actor
  */
-const eventLoop = <
+const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* <
   S extends { readonly _tag: string },
   E extends { readonly _tag: string },
   R,
@@ -505,55 +566,56 @@ const eventLoop = <
   machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>,
   stateRef: SubscriptionRef.SubscriptionRef<S>,
   eventQueue: Queue.Queue<E>,
+  stoppedRef: Ref.Ref<boolean>,
   self: MachineRef<E>,
   listeners: Listeners<S>,
   backgroundFibers: Fiber.Fiber<void, never>[],
   stateScopeRef: { current: Scope.CloseableScope },
   actorId: string,
   inspector?: Inspector<S, E>,
-): Effect.Effect<void, never, R> =>
-  Effect.gen(function* () {
-    while (true) {
-      // Block waiting for next event - will fail with QueueShutdown when queue is shut down
-      const event = yield* Queue.take(eventQueue);
-
-      const currentState = yield* SubscriptionRef.get(stateRef);
-
-      // Process event in a span
-      const shouldStop = yield* Effect.withSpan("effect-machine.event.process", {
-        attributes: {
-          "effect_machine.actor.id": actorId,
-          "effect_machine.state.current": currentState._tag,
-          "effect_machine.event.type": event._tag,
-        },
-      })(
-        processEvent(
-          machine,
-          currentState,
-          event,
-          stateRef,
-          self,
-          listeners,
-          stateScopeRef,
-          actorId,
-          inspector,
-        ),
-      );
-
-      if (shouldStop) {
-        // Close state scope and interrupt background effects when reaching final state
-        yield* Scope.close(stateScopeRef.current, Exit.void);
-        yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
-        return;
-      }
+) {
+  while (true) {
+    // Block waiting for next event - will fail with QueueShutdown when queue is shut down
+    const event = yield* Queue.take(eventQueue);
+
+    const currentState = yield* SubscriptionRef.get(stateRef);
+
+    // Process event in a span
+    const shouldStop = yield* Effect.withSpan("effect-machine.event.process", {
+      attributes: {
+        "effect_machine.actor.id": actorId,
+        "effect_machine.state.current": currentState._tag,
+        "effect_machine.event.type": event._tag,
+      },
+    })(
+      processEvent(
+        machine,
+        currentState,
+        event,
+        stateRef,
+        self,
+        listeners,
+        stateScopeRef,
+        actorId,
+        inspector,
+      ),
+    );
+
+    if (shouldStop) {
+      // Close state scope and interrupt background effects when reaching final state
+      yield* Ref.set(stoppedRef, true);
+      yield* Scope.close(stateScopeRef.current, Exit.void);
+      yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+      return;
     }
-  });
+  }
+});
 
 /**
  * Process a single event, returning true if the actor should stop.
  * Wraps processEventCore with actor-specific concerns (inspection, listeners, state ref).
  */
-const processEvent = <
+const processEvent = Effect.fn("effect-machine.actor.processEvent")(function* <
   S extends { readonly _tag: string },
   E extends { readonly _tag: string },
   R,
@@ -569,89 +631,91 @@ const processEvent = <
   stateScopeRef: { current: Scope.CloseableScope },
   actorId: string,
   inspector?: Inspector<S, E>,
-): Effect.Effect<boolean, never, R> =>
-  Effect.gen(function* () {
-    // Emit event received
-    yield* emitWithTimestamp(inspector, (timestamp) => ({
-      type: "@machine.event",
-      actorId,
-      state: currentState,
-      event,
-      timestamp,
-    }));
-
-    // Build inspection hooks for processEventCore
-    const hooks: ProcessEventHooks<S, E> | undefined =
-      inspector === undefined
-        ? undefined
-        : {
-            onSpawnEffect: (state) =>
-              emitWithTimestamp(inspector, (timestamp) => ({
-                type: "@machine.effect",
-                actorId,
-                effectType: "spawn",
-                state,
-                timestamp,
-              })),
-            onTransition: (from, to, ev) =>
-              emitWithTimestamp(inspector, (timestamp) => ({
-                type: "@machine.transition",
-                actorId,
-                fromState: from,
-                toState: to,
-                event: ev,
-                timestamp,
-              })),
-          };
-
-    // Process event using shared core
-    const result = yield* processEventCore(
-      machine,
-      currentState,
-      event,
-      self,
-      stateScopeRef,
-      hooks,
-    );
-
-    if (!result.transitioned) {
-      yield* Effect.annotateCurrentSpan("effect_machine.transition.matched", false);
-      return false;
-    }
+) {
+  // Emit event received
+  yield* emitWithTimestamp(inspector, (timestamp) => ({
+    type: "@machine.event",
+    actorId,
+    state: currentState,
+    event,
+    timestamp,
+  }));
+
+  // Build inspection hooks for processEventCore
+  const hooks: ProcessEventHooks<S, E> | undefined =
+    inspector === undefined
+      ? undefined
+      : {
+          onSpawnEffect: (state) =>
+            emitWithTimestamp(inspector, (timestamp) => ({
+              type: "@machine.effect",
+              actorId,
+              effectType: "spawn",
+              state,
+              timestamp,
+            })),
+          onTransition: (from, to, ev) =>
+            emitWithTimestamp(inspector, (timestamp) => ({
+              type: "@machine.transition",
+              actorId,
+              fromState: from,
+              toState: to,
+              event: ev,
+              timestamp,
+            })),
+          onError: (info) =>
+            emitWithTimestamp(inspector, (timestamp) => ({
+              type: "@machine.error",
+              actorId,
+              phase: info.phase,
+              state: info.state,
+              event: info.event,
+              error: Cause.pretty(info.cause),
+              timestamp,
+            })),
+        };
+
+  // Process event using shared core
+  const result = yield* processEventCore(machine, currentState, event, self, stateScopeRef, hooks);
+
+  if (!result.transitioned) {
+    yield* Effect.annotateCurrentSpan("effect_machine.transition.matched", false);
+    return false;
+  }
 
-    yield* Effect.annotateCurrentSpan("effect_machine.transition.matched", true);
+  yield* Effect.annotateCurrentSpan("effect_machine.transition.matched", true);
 
-    // Update state ref and notify listeners
-    yield* SubscriptionRef.set(stateRef, result.newState);
-    notifyListeners(listeners, result.newState);
+  // Update state ref and notify listeners
+  yield* SubscriptionRef.set(stateRef, result.newState);
+  notifyListeners(listeners, result.newState);
 
-    if (result.lifecycleRan) {
-      yield* Effect.annotateCurrentSpan("effect_machine.state.from", result.previousState._tag);
-      yield* Effect.annotateCurrentSpan("effect_machine.state.to", result.newState._tag);
+  if (result.lifecycleRan) {
+    yield* Effect.annotateCurrentSpan("effect_machine.state.from", result.previousState._tag);
+    yield* Effect.annotateCurrentSpan("effect_machine.state.to", result.newState._tag);
 
-      // Transition inspection event emitted via hooks in processEventCore
+    // Transition inspection event emitted via hooks in processEventCore
 
-      // Check if new state is final
-      if (result.isFinal) {
-        yield* emitWithTimestamp(inspector, (timestamp) => ({
-          type: "@machine.stop",
-          actorId,
-          finalState: result.newState,
-          timestamp,
-        }));
-        return true;
-      }
+    // Check if new state is final
+    if (result.isFinal) {
+      yield* emitWithTimestamp(inspector, (timestamp) => ({
+        type: "@machine.stop",
+        actorId,
+        finalState: result.newState,
+        timestamp,
+      }));
+      return true;
     }
+  }
 
-    return false;
-  });
+  return false;
+});
 
 /**
  * Run spawn effects with actor-specific inspection and tracing.
  * Wraps the core runSpawnEffects with inspection events and spans.
  * @internal
  */
-const runSpawnEffectsWithInspection = <
+const runSpawnEffectsWithInspection = Effect.fn("effect-machine.actor.spawnEffects")(function* <
   S extends { readonly _tag: string },
   E extends { readonly _tag: string },
   R,
@@ -665,20 +729,33 @@ const runSpawnEffectsWithInspection = <
   stateScope: Scope.CloseableScope,
   actorId: string,
   inspector?: Inspector<S, E>,
-): Effect.Effect<void, never, R> =>
-  Effect.gen(function* () {
-    // Emit inspection event before running effects
-    yield* emitWithTimestamp(inspector, (timestamp) => ({
-      type: "@machine.effect",
-      actorId,
-      effectType: "spawn",
-      state,
-      timestamp,
-    }));
+) {
+  // Emit inspection event before running effects
+  yield* emitWithTimestamp(inspector, (timestamp) => ({
+    type: "@machine.effect",
+    actorId,
+    effectType: "spawn",
+    state,
+    timestamp,
+  }));
+
+  // Use shared core
+  const onError =
+    inspector === undefined
+      ? undefined
+      : (info: ProcessEventError<S, E>) =>
+          emitWithTimestamp(inspector, (timestamp) => ({
+            type: "@machine.error",
+            actorId,
+            phase: info.phase,
+            state: info.state,
+            event: info.event,
+            error: Cause.pretty(info.cause),
+            timestamp,
+          }));
 
-    // Use shared core
-    yield* runSpawnEffects(machine, state, event, self, stateScope);
-  });
+  yield* runSpawnEffects(machine, state, event, self, stateScope, onError);
+});
 
 // ============================================================================
 // ActorSystem Implementation
@@ -687,85 +764,102 @@ const runSpawnEffectsWithInspection = <
 /**
  * Internal implementation
  */
-const make = Effect.sync(() => {
+const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
   // MutableHashMap for O(1) spawn/stop/get operations
   const actors = MutableHashMap.empty<string, ActorRef<AnyState, unknown>>();
+  const spawnGate = yield* Effect.makeSemaphore(1);
+  const withSpawnGate = spawnGate.withPermits(1);
 
   /** Check for duplicate ID, register actor, add cleanup finalizer */
-  const registerActor = <T extends { stop: Effect.Effect<void> }>(
-    id: string,
-    actor: T,
-  ): Effect.Effect<T, DuplicateActorError, Scope.Scope> =>
-    Effect.gen(function* () {
-      // Check if actor already exists
-      if (MutableHashMap.has(actors, id)) {
-        return yield* new DuplicateActorError({ actorId: id });
-      }
+  const registerActor = Effect.fn("effect-machine.actorSystem.register")(function* <
+    T extends { stop: Effect.Effect<void> },
+  >(id: string, actor: T) {
+    // Check if actor already exists
+    if (MutableHashMap.has(actors, id)) {
+      // Stop the newly created actor to avoid leaks
+      yield* actor.stop;
+      return yield* new DuplicateActorError({ actorId: id });
+    }
 
-      // Register it - O(1)
-      MutableHashMap.set(actors, id, actor as unknown as ActorRef<AnyState, unknown>);
+    // Register it - O(1)
+    MutableHashMap.set(actors, id, actor as unknown as ActorRef<AnyState, unknown>);
 
-      // Register cleanup on scope finalization
-      yield* Effect.addFinalizer(() =>
-        Effect.gen(function* () {
-          yield* actor.stop;
-          MutableHashMap.remove(actors, id);
-        }),
-      );
+    // Register cleanup on scope finalization
+    yield* Effect.addFinalizer(
+      Effect.fn("effect-machine.actorSystem.register.finalizer")(function* () {
+        yield* actor.stop;
+        MutableHashMap.remove(actors, id);
+      }),
+    );
 
-      return actor;
-    });
+    return actor;
+  });
 
-  const spawnRegular = <
+  const spawnRegular = Effect.fn("effect-machine.actorSystem.spawnRegular")(function* <
     S extends { readonly _tag: string },
     E extends { readonly _tag: string },
     R,
     GD extends GuardsDef = Record<string, never>,
     EFD extends EffectsDef = Record<string, never>,
-  >(
-    id: string,
-    machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>,
-  ): Effect.Effect<ActorRef<S, E>, DuplicateActorError, R | Scope.Scope> =>
-    Effect.gen(function* () {
-      // Create and register the actor
-      const actor = yield* createActor(id, machine);
-      return yield* registerActor(id, actor);
-    });
-
-  const spawnPersistent = <
+  >(id: string, machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>) {
+    if (MutableHashMap.has(actors, id)) {
+      return yield* new DuplicateActorError({ actorId: id });
+    }
+    // Create and register the actor
+    const actor = yield* createActor(id, machine);
+    return yield* registerActor(id, actor);
+  });
+
+  const spawnPersistent = Effect.fn("effect-machine.actorSystem.spawnPersistent")(function* <
+    S extends { readonly _tag: string },
+    E extends { readonly _tag: string },
+    R,
+  >(id: string, persistentMachine: PersistentMachine<S, E, R>) {
+    if (MutableHashMap.has(actors, id)) {
+      return yield* new DuplicateActorError({ actorId: id });
+    }
+    const adapter = yield* PersistenceAdapterTag;
+
+    // Try to load existing snapshot
+    const maybeSnapshot = yield* adapter.loadSnapshot(
+      id,
+      persistentMachine.persistence.stateSchema,
+    );
+
+    // Load events after snapshot (or all events if no snapshot)
+    const events = yield* adapter.loadEvents(
+      id,
+      persistentMachine.persistence.eventSchema,
+      Option.isSome(maybeSnapshot) ? maybeSnapshot.value.version : undefined,
+    );
+
+    // Create and register the persistent actor
+    const actor = yield* createPersistentActor(id, persistentMachine, maybeSnapshot, events);
+    return yield* registerActor(id, actor);
+  });
+
+  const spawnImpl = Effect.fn("effect-machine.actorSystem.spawn")(function* <
     S extends { readonly _tag: string },
     E extends { readonly _tag: string },
     R,
+    GD extends GuardsDef = Record<string, never>,
+    EFD extends EffectsDef = Record<string, never>,
   >(
     id: string,
-    persistentMachine: PersistentMachine<S, E, R>,
-  ): Effect.Effect<
-    PersistentActorRef<S, E>,
-    PersistenceError | VersionConflictError | DuplicateActorError,
-    R | Scope.Scope | PersistenceAdapterTag
-  > =>
-    Effect.gen(function* () {
-      const adapter = yield* PersistenceAdapterTag;
-
-      // Try to load existing snapshot
-      const maybeSnapshot = yield* adapter.loadSnapshot(
-        id,
-        persistentMachine.persistence.stateSchema,
-      );
-
-      // Load events after snapshot (if any)
-      const events = Option.isSome(maybeSnapshot)
-        ? yield* adapter.loadEvents(
-            id,
-            persistentMachine.persistence.eventSchema,
-            maybeSnapshot.value.version,
-          )
-        : [];
-
-      // Create and register the persistent actor
-      const actor = yield* createPersistentActor(id, persistentMachine, maybeSnapshot, events);
-      return yield* registerActor(id, actor);
-    });
+    machine:
+      | Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>
+      | PersistentMachine<S, E, R>,
+  ) {
+    if (isPersistentMachine(machine)) {
+      // TypeScript can't narrow union with invariant generic params
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return yield* spawnPersistent(id, machine as PersistentMachine<S, E, R>);
+    }
+    return yield* spawnRegular(
+      id,
+      machine as Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>,
+    );
+  });
 
   // Type-safe overloaded spawn implementation
   function spawn<
@@ -777,13 +871,13 @@ const make = Effect.sync(() => {
   >(
     id: string,
     machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>,
-  ): Effect.Effect<ActorRef<S, E>, DuplicateActorError, R | Scope.Scope>;
+  ): Effect.Effect<ActorRef<S, E>, DuplicateActorError | UnprovidedSlotsError, R | Scope.Scope>;
   function spawn<S extends { readonly _tag: string }, E extends { readonly _tag: string }, R>(
     id: string,
     machine: PersistentMachine<S, E, R>,
   ): Effect.Effect<
-    PersistentActorRef<S, E>,
-    PersistenceError | VersionConflictError | DuplicateActorError,
+    PersistentActorRef<S, E, R>,
+    PersistenceError | VersionConflictError | DuplicateActorError | UnprovidedSlotsError,
     R | Scope.Scope | PersistenceAdapterTag
   >;
   function spawn<
@@ -798,140 +892,135 @@ const make = Effect.sync(() => {
       | Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>
       | PersistentMachine<S, E, R>,
   ):
-    | Effect.Effect<ActorRef<S, E>, DuplicateActorError, R | Scope.Scope>
+    | Effect.Effect<ActorRef<S, E>, DuplicateActorError | UnprovidedSlotsError, R | Scope.Scope>
     | Effect.Effect<
-        PersistentActorRef<S, E>,
-        PersistenceError | VersionConflictError | DuplicateActorError,
+        PersistentActorRef<S, E, R>,
+        PersistenceError | VersionConflictError | DuplicateActorError | UnprovidedSlotsError,
         R | Scope.Scope | PersistenceAdapterTag
       > {
-    if (isPersistentMachine(machine)) {
-      // TypeScript can't narrow union with invariant generic params
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      return spawnPersistent(id, machine as PersistentMachine<S, E, R>);
-    }
-    return spawnRegular(
-      id,
-      machine as Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>,
-    );
+    return withSpawnGate(spawnImpl(id, machine)) as
+      | Effect.Effect<ActorRef<S, E>, DuplicateActorError | UnprovidedSlotsError, R | Scope.Scope>
+      | Effect.Effect<
+          PersistentActorRef<S, E, R>,
+          PersistenceError | VersionConflictError | DuplicateActorError | UnprovidedSlotsError,
+          R | Scope.Scope | PersistenceAdapterTag
+        >;
   }
 
+  const restoreImpl = Effect.fn("effect-machine.actorSystem.restore")(function* <
+    S extends { readonly _tag: string },
+    E extends { readonly _tag: string },
+    R,
+  >(id: string, persistentMachine: PersistentMachine<S, E, R>) {
+    // Try to restore from persistence
+    const maybeActor = yield* restorePersistentActor(id, persistentMachine);
+
+    if (Option.isSome(maybeActor)) {
+      yield* registerActor(id, maybeActor.value);
+    }
+
+    return maybeActor;
+  });
   const restore = <S extends { readonly _tag: string }, E extends { readonly _tag: string }, R>(
     id: string,
     persistentMachine: PersistentMachine<S, E, R>,
-  ): Effect.Effect<
-    Option.Option<PersistentActorRef<S, E>>,
-    PersistenceError | DuplicateActorError,
-    R | Scope.Scope | PersistenceAdapterTag
-  > =>
-    Effect.gen(function* () {
-      // Try to restore from persistence
-      const maybeActor = yield* restorePersistentActor(id, persistentMachine);
+  ) => withSpawnGate(restoreImpl(id, persistentMachine));
 
-      if (Option.isSome(maybeActor)) {
-        yield* registerActor(id, maybeActor.value);
-      }
-
-      return maybeActor;
-    });
+  const get = Effect.fn("effect-machine.actorSystem.get")(function* (id: string) {
+    return yield* Effect.sync(() => MutableHashMap.get(actors, id));
+  });
 
-  const get = (id: string): Effect.Effect<Option.Option<ActorRef<AnyState, unknown>>> =>
-    Effect.sync(() => MutableHashMap.get(actors, id));
+  const stop = Effect.fn("effect-machine.actorSystem.stop")(function* (id: string) {
+    const maybeActor = MutableHashMap.get(actors, id);
+    if (Option.isNone(maybeActor)) {
+      return false;
+    }
 
-  const stop = (id: string): Effect.Effect<boolean> =>
-    Effect.gen(function* () {
-      const maybeActor = MutableHashMap.get(actors, id);
-      if (Option.isNone(maybeActor)) {
-        return false;
-      }
+    yield* maybeActor.value.stop;
+    MutableHashMap.remove(actors, id);
+    return true;
+  });
 
-      yield* maybeActor.value.stop;
-      MutableHashMap.remove(actors, id);
-      return true;
-    });
+  const listPersisted = Effect.fn("effect-machine.actorSystem.listPersisted")(function* () {
+    const adapter = yield* PersistenceAdapterTag;
+    if (adapter.listActors === undefined) {
+      return [];
+    }
+    return yield* adapter.listActors();
+  });
 
-  const listPersisted = (): Effect.Effect<
-    ReadonlyArray<ActorMetadata>,
-    PersistenceError,
-    PersistenceAdapterTag
-  > =>
-    Effect.gen(function* () {
-      const adapter = yield* PersistenceAdapterTag;
-      if (adapter.listActors === undefined) {
-        return [];
+  const restoreMany = Effect.fn("effect-machine.actorSystem.restoreMany")(function* <
+    S extends { readonly _tag: string },
+    E extends { readonly _tag: string },
+    R,
+  >(ids: ReadonlyArray<string>, persistentMachine: PersistentMachine<S, E, R>) {
+    const restored: PersistentActorRef<S, E, R>[] = [];
+    const failed: {
+      id: string;
+      error: PersistenceError | DuplicateActorError | UnprovidedSlotsError;
+    }[] = [];
+
+    for (const id of ids) {
+      // Skip if already running
+      if (MutableHashMap.has(actors, id)) {
+        continue;
       }
-      return yield* adapter.listActors();
-    });
 
-  const restoreMany = <S extends { readonly _tag: string }, E extends { readonly _tag: string }, R>(
-    ids: ReadonlyArray<string>,
-    persistentMachine: PersistentMachine<S, E, R>,
-  ): Effect.Effect<RestoreResult<S, E>, never, R | Scope.Scope | PersistenceAdapterTag> =>
-    Effect.gen(function* () {
-      const restored: PersistentActorRef<S, E>[] = [];
-      const failed: { id: string; error: PersistenceError | DuplicateActorError }[] = [];
-
-      for (const id of ids) {
-        // Skip if already running
-        if (MutableHashMap.has(actors, id)) {
-          continue;
-        }
-
-        const result = yield* Effect.either(restore(id, persistentMachine));
-        if (result._tag === "Left") {
-          failed.push({ id, error: result.left });
-        } else if (Option.isSome(result.right)) {
-          restored.push(result.right.value);
-        } else {
-          // No persisted state for this ID
-          failed.push({
-            id,
-            error: new PersistenceErrorClass({
-              operation: "restore",
-              actorId: id,
-              message: "No persisted state found",
-            }),
-          });
-        }
+      const result = yield* Effect.either(restore(id, persistentMachine));
+      if (result._tag === "Left") {
+        failed.push({ id, error: result.left });
+      } else if (Option.isSome(result.right)) {
+        restored.push(result.right.value);
+      } else {
+        // No persisted state for this ID
+        failed.push({
+          id,
+          error: new PersistenceErrorClass({
+            operation: "restore",
+            actorId: id,
+            message: "No persisted state found",
+          }),
+        });
       }
+    }
 
-      return { restored, failed };
-    });
+    return { restored, failed };
+  });
 
-  const restoreAll = <S extends { readonly _tag: string }, E extends { readonly _tag: string }, R>(
+  const restoreAll = Effect.fn("effect-machine.actorSystem.restoreAll")(function* <
+    S extends { readonly _tag: string },
+    E extends { readonly _tag: string },
+    R,
+  >(
     persistentMachine: PersistentMachine<S, E, R>,
     options?: { filter?: (meta: ActorMetadata) => boolean },
-  ): Effect.Effect<
-    RestoreResult<S, E>,
-    PersistenceError,
-    R | Scope.Scope | PersistenceAdapterTag
-  > =>
-    Effect.gen(function* () {
-      const adapter = yield* PersistenceAdapterTag;
-      if (adapter.listActors === undefined) {
-        return { restored: [], failed: [] };
-      }
+  ) {
+    const adapter = yield* PersistenceAdapterTag;
+    if (adapter.listActors === undefined) {
+      return { restored: [], failed: [] };
+    }
 
-      // Require explicit machineType to prevent cross-machine restores
-      const machineType = persistentMachine.persistence.machineType;
-      if (machineType === undefined) {
-        return yield* new PersistenceErrorClass({
-          operation: "restoreAll",
-          actorId: "*",
-          message: "restoreAll requires explicit machineType in persistence config",
-        });
-      }
+    // Require explicit machineType to prevent cross-machine restores
+    const machineType = persistentMachine.persistence.machineType;
+    if (machineType === undefined) {
+      return yield* new PersistenceErrorClass({
+        operation: "restoreAll",
+        actorId: "*",
+        message: "restoreAll requires explicit machineType in persistence config",
+      });
+    }
 
-      const allMetadata = yield* adapter.listActors();
+    const allMetadata = yield* adapter.listActors();
 
-      // Filter by machineType and optional user filter
-      let filtered = allMetadata.filter((meta) => meta.machineType === machineType);
-      if (options?.filter !== undefined) {
-        filtered = filtered.filter(options.filter);
-      }
+    // Filter by machineType and optional user filter
+    let filtered = allMetadata.filter((meta) => meta.machineType === machineType);
+    if (options?.filter !== undefined) {
+      filtered = filtered.filter(options.filter);
+    }
 
-      const ids = filtered.map((meta) => meta.id);
-      return yield* restoreMany(ids, persistentMachine);
-    });
+    const ids = filtered.map((meta) => meta.id);
+    return yield* restoreMany(ids, persistentMachine);
+  });
 
   return ActorSystem.of({ spawn, restore, get, stop, listPersisted, restoreMany, restoreAll });
 });
@@ -939,4 +1028,4 @@ const make = Effect.sync(() => {
 /**
  * Default ActorSystem layer
  */
-export const Default = Layer.effect(ActorSystem, make);
+export const Default = Layer.effect(ActorSystem, make());