effect-machine 0.19.0 → 0.21.0

package/dist/internal/runtime.js

@@ -2,7 +2,6 @@ import { INTERNAL_INIT_EVENT, isEffect } from "./utils.js";
 import { ActorStoppedError, NoReplyError } from "../errors.js";
 import { makeEventAdvancement } from "./event-advancement.js";
 import { processEventCoreImmediate, runSpawnEffects, shouldPostpone } from "./transition.js";
-import { ActorExit } from "../supervision.js";
 import { ActorSystem } from "../actor.js";
 import { Cause, Deferred, Effect, Exit, Fiber, Queue, Ref, Schema, Scope, SubscriptionRef } from "effect";
 //#region src/internal/runtime.ts
@@ -18,12 +17,24 @@ import { Cause, Deferred, Effect, Exit, Fiber, Queue, Ref, Schema, Scope, Subscr
 * - Reply settlement (call/ask Deferreds)
 * - Reply schema validation
 * - Lifecycle hooks for actor-specific concerns (inspection, listeners, etc.)
-* - ActorExit with exit reason (Final/Stopped/Defect) via exitDeferred
+* - RuntimeExit with exit reason (Final/Stopped/Defect) via exitDeferred
 *
 * Used by entity-machine and local actor (actor.ts delegates here).
 *
 * @internal
 */
+const RuntimeExit = {
+	Final: (state) => ({
+		_tag: "Final",
+		state
+	}),
+	Stopped: { _tag: "Stopped" },
+	Defect: (cause, phase) => ({
+		_tag: "Defect",
+		cause,
+		phase
+	})
+};
 /**
 * Create a runtime for a machine. Returns a handle for sending events
 * and querying state. The runtime owns:
@@ -41,6 +52,7 @@ import { Cause, Deferred, Effect, Exit, Fiber, Queue, Ref, Schema, Scope, Subscr
 */
 const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (machine, system, config) {
 	const { actorId, hooks, lifecycle } = config;
+	const generation = config.generation ?? 0;
 	const services = yield* Effect.context();
 	const fork = Effect.runForkWith(services);
 	const { stateRef, stoppedRef, eventQueue } = config.cellResources;
@@ -84,51 +96,78 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 			yield* Deferred.await(startDeferred);
 			return;
 		}
+		const initialSpawnDefectSignal = (cause) => Deferred.succeed(exitDeferred, RuntimeExit.Defect(cause, "initial-spawn")).pipe(Effect.andThen(Ref.set(stoppedRef, true)), Effect.andThen(Effect.suspend(() => {
+			const loopFiber = loopFiberRef.current;
+			if (loopFiber !== void 0) return Fiber.interrupt(loopFiber);
+			return Effect.void;
+		})), Effect.asVoid);
+		const initialState = yield* SubscriptionRef.get(stateRef);
+		const initialProcessing = processEventCoreImmediate(machine, initialState, initEvent, self, stateScopeRef, system, actorId, {
+			...hooks,
+			onSpawnDefect: initialSpawnDefectSignal
+		}, generation);
+		let initialResult;
+		if (isEffect(initialProcessing)) initialResult = yield* initialProcessing.pipe(Effect.catchCause((cause) => 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, RuntimeExit.Defect(cause, "transition"));
+			return yield* Effect.failCause(cause);
+		})));
+		else initialResult = initialProcessing;
+		if (initialResult.transitioned) {
+			yield* SubscriptionRef.set(stateRef, initialResult.newState);
+			if (lifecycle?.onStateChange !== void 0) {
+				const stateChange = lifecycle.onStateChange(initialResult, initEvent);
+				if (isEffect(stateChange)) yield* stateChange;
+			}
+			if (lifecycle?.onProcessed !== void 0) {
+				const processed = lifecycle.onProcessed(initialResult, initEvent);
+				if (isEffect(processed)) yield* processed;
+			}
+		}
+		const stableInitialState = initialResult.newState;
 		const backgroundFibers = [];
 		for (const bg of machine._backgroundEffectEntries()) {
 			const fiber = yield* bg.handler({
 				actorId,
-				state: machine.initial,
+				generation,
+				state: stableInitialState,
 				event: initEvent,
 				self,
 				system
 			}).pipe(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(() => {
-			const loopFiber = loopFiberRef.current;
-			if (loopFiber !== void 0) return Fiber.interrupt(loopFiber);
-			return Effect.void;
-		})), Effect.asVoid);
-		yield* runSpawnEffects(machine, machine.initial, initEvent, self, stateScopeRef.current, system, actorId, hooks?.onError, initialSpawnDefectSignal).pipe(Effect.catchCause((cause) => Effect.gen(function* () {
+		if (!initialResult.lifecycleRan && lifecycle?.onInitialSpawnEffects !== void 0) yield* lifecycle.onInitialSpawnEffects(stableInitialState);
+		if (!initialResult.lifecycleRan) yield* runSpawnEffects(machine, stableInitialState, initEvent, self, stateScopeRef.current, system, actorId, hooks?.onError, initialSpawnDefectSignal, generation).pipe(Effect.catchCause((cause) => 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"));
+			yield* Deferred.succeed(exitDeferred, RuntimeExit.Defect(cause, "initial-spawn"));
 			return yield* Effect.failCause(cause);
 		})));
-		if (machine._isFinal(machine.initial._tag)) {
-			if (lifecycle?.onFinal !== void 0) yield* lifecycle.onFinal(machine.initial);
+		if (machine._isFinal(stableInitialState._tag)) {
+			if (lifecycle?.onFinal !== void 0) yield* lifecycle.onFinal(stableInitialState);
 			yield* Ref.set(stoppedRef, true);
 			yield* Scope.close(stateScopeRef.current, Exit.void);
 			yield* Scope.close(actorScope, Exit.void);
-			yield* setExit(ActorExit.Final(machine.initial));
+			yield* setExit(RuntimeExit.Final(stableInitialState));
 			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(() => {
+			onSpawnDefect: (cause) => Deferred.succeed(exitDeferred, RuntimeExit.Defect(cause, "spawn")).pipe(Effect.andThen(Ref.set(stoppedRef, true)), Effect.andThen(Effect.suspend(() => {
 				const loopFiber = loopFiberRef.current;
 				if (loopFiber !== void 0) return Fiber.interrupt(loopFiber);
 				return Effect.void;
 			})), Effect.asVoid)
 		};
-		const loopFiber = yield* runtimeEventLoop(machine, stateRef, eventQueue, pendingRequests, stoppedRef, self, stateScopeRef, actorId, system, exitDeferred, augmentedHooks, deferredReplyRef, lifecycle, fork).pipe(Effect.provide(services), Effect.forkDetach);
+		const loopFiber = yield* runtimeEventLoop(machine, stateRef, eventQueue, pendingRequests, stoppedRef, self, stateScopeRef, actorId, generation, system, exitDeferred, augmentedHooks, deferredReplyRef, lifecycle, fork).pipe(Effect.provide(services), Effect.forkDetach);
 		loopFiberRef.current = loopFiber;
 		if (backgroundFibers.length > 0) yield* Effect.raceAll(backgroundFibers.map((fiber) => Fiber.await(fiber).pipe(Effect.flatMap((exit) => {
-			if (exit._tag === "Failure" && !Cause.hasInterruptsOnly(exit.cause)) return setExit(ActorExit.Defect(exit.cause, "background")).pipe(Effect.andThen(Ref.set(stoppedRef, true)), Effect.andThen(Fiber.interrupt(loopFiber)));
+			if (exit._tag === "Failure" && !Cause.hasInterruptsOnly(exit.cause)) return setExit(RuntimeExit.Defect(exit.cause, "background")).pipe(Effect.andThen(Ref.set(stoppedRef, true)), Effect.andThen(Fiber.interrupt(loopFiber)));
 			return Effect.never;
 		})))).pipe(Effect.forkIn(actorScope));
 		yield* Effect.forkDetach(Effect.gen(function* () {
@@ -137,7 +176,7 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 			else yield* Scope.close(actorScope, loopExit);
 		}));
 		yield* Deferred.succeed(startDeferred, void 0);
-	}).pipe(Effect.catchCause((cause) => Deferred.failCause(startDeferred, cause).pipe(Effect.andThen(Effect.failCause(cause)))));
+	}).pipe(Effect.catchCause((cause) => Ref.set(stoppedRef, true).pipe(Effect.andThen(Scope.close(stateScopeRef.current, Exit.void)), Effect.andThen(Scope.close(actorScope, Exit.void)), Effect.andThen(setExit(RuntimeExit.Defect(cause, "transition"))), Effect.andThen(Deferred.failCause(startDeferred, cause)), Effect.andThen(Effect.failCause(cause)))));
 	const stop = Effect.gen(function* () {
 		if (yield* Ref.get(stoppedRef)) return;
 		if (lifecycle?.onShutdown !== void 0) yield* lifecycle.onShutdown();
@@ -147,7 +186,7 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 		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);
+		yield* setExit(RuntimeExit.Stopped);
 	}).pipe(Effect.asVoid);
 	if (config.skipFinalizer !== true) yield* Effect.addFinalizer(() => stop);
 	return {
@@ -233,7 +272,7 @@ const settlePendingRequests = (pendingRequests, actorId) => Effect.gen(function*
 	for (const settle of pendingRequests) yield* settle(error);
 	pendingRequests.clear();
 });
-const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function* (machine, stateRef, eventQueue, pendingRequests, stoppedRef, self, stateScopeRef, actorId, system, exitDeferred, hooks, deferredReplyRef, lifecycle, fork) {
+const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function* (machine, stateRef, eventQueue, pendingRequests, stoppedRef, self, stateScopeRef, actorId, generation, system, exitDeferred, hooks, deferredReplyRef, lifecycle, fork) {
 	const forkEffect = fork ?? Effect.runFork;
 	/** Set the exit deferred exactly once. */
 	const setExit = (exit) => Deferred.succeed(exitDeferred, exit).pipe(Effect.asVoid);
@@ -248,7 +287,8 @@ const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function*
 			hasReply: false,
 			deferReply: false,
 			reply: void 0,
-			postponed: true
+			postponed: true,
+			transitions: []
 		};
 		let input = queued;
 		if (queued._tag === "call") {
@@ -276,7 +316,7 @@ const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function*
 	const processQueued = (currentState, queued) => Effect.gen(function* () {
 		const event = queued.event;
 		if (lifecycle?.onEvent !== void 0) yield* lifecycle.onEvent(currentState, event);
-		const processing = processEventCoreImmediate(machine, currentState, event, self, stateScopeRef, system, actorId, hooks);
+		const processing = processEventCoreImmediate(machine, currentState, event, self, stateScopeRef, system, actorId, hooks, generation);
 		let result;
 		if (isEffect(processing)) result = yield* processing;
 		else result = processing;
@@ -364,7 +404,8 @@ const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function*
 				hasReply: false,
 				deferReply: false,
 				reply: void 0,
-				postponed: false
+				postponed: false,
+				transitions: []
 			}));
 		}
 		yield* Scope.close(stateScopeRef.current, Exit.void);
@@ -373,7 +414,7 @@ const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function*
 	while (true) {
 		const queued = yield* Queue.take(eventQueue);
 		if (queued._tag === "drain") {
-			yield* shutdown(ActorExit.Stopped);
+			yield* shutdown(RuntimeExit.Stopped);
 			yield* Deferred.succeed(queued.done, void 0);
 			return;
 		}
@@ -382,7 +423,7 @@ const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function*
 			if (queued._tag === "sendWait") forkEffect(Deferred.failCause(queued.done, cause));
 			else if (queued._tag === "ask") forkEffect(Deferred.die(queued.reply, cause));
 			else if (queued._tag === "call") forkEffect(Deferred.failCause(queued.reply, cause));
-			return shutdown(ActorExit.Defect(cause, "transition")).pipe(Effect.andThen(Effect.failCause(cause)));
+			return shutdown(RuntimeExit.Defect(cause, "transition")).pipe(Effect.andThen(Effect.failCause(cause)));
 		}));
 		let stopped;
 		if (advancement === void 0) {
@@ -392,7 +433,7 @@ const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function*
 		} else stopped = (yield* catchEventDefect(advancement.advance(eventQueued))).stopped;
 		if (stopped) {
 			const finalState = yield* SubscriptionRef.get(stateRef);
-			yield* shutdown(ActorExit.Final(finalState));
+			yield* shutdown(RuntimeExit.Final(finalState));
 			return;
 		}
 	}

package/dist/internal/transition.d.ts

@@ -1,10 +1,35 @@
 import { Machine } from "../machine.js";
 import { Transition } from "./machine-definition.js";
 //#region src/internal/transition.d.ts
+interface ExecutedStep<S, E> {
+  readonly previousState: S;
+  readonly newState: S;
+  readonly event: E;
+  readonly transition: Transition<S, E, never>;
+}
+interface ExecutedTransition<S, E = unknown> {
+  readonly newState: S;
+  readonly transitioned: boolean;
+  readonly reenter: boolean;
+  readonly hasReply: boolean;
+  readonly deferReply: boolean;
+  readonly reply: unknown;
+  readonly transition?: Transition<S, E, never>;
+  readonly steps: ReadonlyArray<ExecutedStep<S, E>>;
+}
+declare const executeTransitionImmediate: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R>(machine: Machine<S, E, R, any, any, any, any>, currentState: S, event: E, hooks?: ProcessEventHooks<S, E>) => ExecutedTransition<S, E> | Effect.Effect<ExecutedTransition<S, E>>;
 /**
  * Optional hooks for event processing inspection/tracing.
  */
 interface ProcessEventHooks<S, E> {
+  /** Called after each guard candidate is evaluated. */
+  readonly onGuard?: (evaluation: GuardEvaluation<S, E>) => Effect.Effect<void>;
+  /** Called before an accepted transition handler runs. */
+  readonly onOperation?: (operation: TransitionOperation<S, E>) => Effect.Effect<void>;
   /** Called before running spawn effects */
   readonly onSpawnEffect?: (state: S) => Effect.Effect<void>;
   /** Called after transition completes */
@@ -14,6 +39,17 @@ interface ProcessEventHooks<S, E> {
   /** Called when a forked spawn fiber defects — signals the runtime to set exitDeferred */
   readonly onSpawnDefect?: (cause: Cause.Cause<unknown>) => Effect.Effect<void>;
 }
+interface GuardEvaluation<S, E> {
+  readonly guard: string;
+  readonly state: S;
+  readonly event: E;
+  readonly result: boolean;
+}
+interface TransitionOperation<S, E> {
+  readonly operation: string;
+  readonly state: S;
+  readonly event: E;
+}
 /**
  * Error info for inspection hooks.
  */
@@ -26,7 +62,7 @@ interface ProcessEventError<S, E> {
 /**
  * Result of processing an event through the machine.
  */
-interface ProcessEventResult<S> {
+interface ProcessEventResult<S, E = unknown> {
   /** New state after processing */
   readonly newState: S;
   /** Previous state before processing */
@@ -45,6 +81,12 @@ interface ProcessEventResult<S> {
   readonly reply?: unknown;
   /** Whether the event was postponed (buffered for retry after next state change) */
   readonly postponed: boolean;
+  /** Each accepted edge in the stable macrostep. */
+  readonly transitions: ReadonlyArray<{
+    readonly previousState: S;
+    readonly newState: S;
+    readonly event: E;
+  }>;
 }
 /**
  * Resolve which transition should fire for a given state and event.
@@ -54,6 +96,12 @@ declare const resolveTransition: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R>(machine: Machine<S, E, R, any, any>, currentState: S, event: E) => Transition<S, E, never> | undefined;
+}, R>(machine: Machine<S, E, R, any, any, any, any>, currentState: S, event: E) => Transition<S, E, never> | undefined;
+/** Resolve a transition with pure or Effect guards. */
+declare const resolveTransitionEffect: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R>(machine: Machine<S, E, R, any, any, any, any>, currentState: S, event: E) => Effect.Effect<Transition<S, E, never> | undefined>;
 //#endregion
-export { ProcessEventError, ProcessEventHooks, ProcessEventResult, resolveTransition };
+export { GuardEvaluation, ProcessEventError, ProcessEventHooks, ProcessEventResult, TransitionOperation, executeTransitionImmediate, resolveTransition, resolveTransitionEffect };

package/dist/internal/transition.js

@@ -11,14 +11,21 @@ import { Cause, Effect, Exit, Scope } from "effect";
 *
 * @internal
 */
-const completeTransition = (transition, resolved) => {
+const completeTransition = (currentState, event, transition, resolved) => {
 	if (isReplyResult(resolved)) return {
 		newState: resolved.state,
 		transitioned: true,
 		reenter: transition.reenter === true,
 		hasReply: true,
 		deferReply: false,
-		reply: resolved.reply
+		reply: resolved.reply,
+		transition,
+		steps: [{
+			previousState: currentState,
+			newState: resolved.state,
+			event,
+			transition
+		}]
 	};
 	if (isDeferReplyResult(resolved)) return {
 		newState: resolved.state,
@@ -26,7 +33,14 @@ const completeTransition = (transition, resolved) => {
 		reenter: transition.reenter === true,
 		hasReply: false,
 		deferReply: true,
-		reply: void 0
+		reply: void 0,
+		transition,
+		steps: [{
+			previousState: currentState,
+			newState: resolved.state,
+			event,
+			transition
+		}]
 	};
 	return {
 		newState: resolved,
@@ -34,7 +48,14 @@ const completeTransition = (transition, resolved) => {
 		reenter: transition.reenter === true,
 		hasReply: false,
 		deferReply: false,
-		reply: void 0
+		reply: void 0,
+		transition,
+		steps: [{
+			previousState: currentState,
+			newState: resolved,
+			event,
+			transition
+		}]
 	};
 };
 /**
@@ -50,8 +71,10 @@ const completeTransition = (transition, resolved) => {
 */
 const executeTransition = (machine, currentState, event) => Effect.suspend(() => {
 	const result = executeTransitionImmediate(machine, currentState, event);
-	if (isEffect(result)) return result;
-	return Effect.succeed(result);
+	let first;
+	if (isEffect(result)) first = result;
+	else first = Effect.succeed(result);
+	return first.pipe(Effect.flatMap((initialResult) => stabilizeTransition(machine, currentState, event, initialResult)));
 });
 /**
 * Execute a transition without adding an Effect boundary for a synchronous handler.
@@ -59,29 +82,98 @@ const executeTransition = (machine, currentState, event) => Effect.suspend(() =>
 *
 * @internal
 */
-const executeTransitionImmediate = (machine, currentState, event) => {
-	const transition = resolveTransition(machine, currentState, event);
-	if (transition === void 0) return {
-		newState: currentState,
-		transitioned: false,
-		reenter: false,
-		hasReply: false,
-		deferReply: false,
-		reply: void 0
-	};
-	const handlerCtx = {
-		state: currentState,
-		event
-	};
-	let raw;
+const executeTransitionCandidatesImmediate = (currentState, event, candidates, hooks) => {
+	let resolution;
 	try {
-		raw = transition.handler(handlerCtx);
+		resolution = evaluateTransitions(candidates, currentState, event);
 	} catch (defect) {
 		return Effect.die(defect);
 	}
-	if (isEffect(raw)) return raw.pipe(Effect.map((resolved) => completeTransition(transition, resolved)));
-	return completeTransition(transition, raw);
+	const executeResolved = (resolved) => {
+		const transition = resolved.transition;
+		if (transition === void 0) {
+			const unhandled = {
+				newState: currentState,
+				transitioned: false,
+				reenter: false,
+				hasReply: false,
+				deferReply: false,
+				reply: void 0,
+				transition: void 0,
+				steps: []
+			};
+			if (hooks?.onGuard === void 0 || resolved.evaluations.length === 0) return unhandled;
+			return Effect.forEach(resolved.evaluations, hooks.onGuard, { discard: true }).pipe(Effect.as(unhandled));
+		}
+		const runHandler = () => {
+			const handlerCtx = {
+				state: currentState,
+				event
+			};
+			let raw;
+			try {
+				raw = transition.handler(handlerCtx);
+			} catch (defect) {
+				return Effect.die(defect);
+			}
+			if (isEffect(raw)) return raw.pipe(Effect.map((value) => completeTransition(currentState, event, transition, value)));
+			return completeTransition(currentState, event, transition, raw);
+		};
+		const runInspectedHandler = () => {
+			if (hooks?.onOperation === void 0) return runHandler();
+			return hooks.onOperation({
+				operation: transition.handler.name || "<inline>",
+				state: currentState,
+				event
+			}).pipe(Effect.andThen(Effect.suspend(() => {
+				const result = runHandler();
+				if (isEffect(result)) return result;
+				return Effect.succeed(result);
+			})));
+		};
+		if (hooks?.onGuard === void 0 || resolved.evaluations.length === 0) return runInspectedHandler();
+		return Effect.forEach(resolved.evaluations, hooks.onGuard, { discard: true }).pipe(Effect.andThen(Effect.suspend(() => {
+			const result = runInspectedHandler();
+			if (isEffect(result)) return result;
+			return Effect.succeed(result);
+		})));
+	};
+	if (!isEffect(resolution)) return executeResolved(resolution);
+	return resolution.pipe(Effect.flatMap((resolved) => {
+		const result = executeResolved(resolved);
+		if (isEffect(result)) return result;
+		return Effect.succeed(result);
+	}));
 };
+const executeTransitionImmediate = (machine, currentState, event, hooks) => executeTransitionCandidatesImmediate(currentState, event, machine._findTransitions(currentState._tag, event._tag), hooks);
+const stabilizeTransition = (machine, initialState, event, result, hooks) => Effect.gen(function* () {
+	const steps = [...result.steps];
+	let stableState = result.newState;
+	let lifecycleRequired = result.reenter || stableState._tag !== initialState._tag;
+	let depth = 0;
+	while (true) {
+		const candidates = machine._findImmediateTransitions(stableState._tag);
+		if (candidates.length === 0) break;
+		depth += 1;
+		if (depth > 100) return yield* Effect.die(/* @__PURE__ */ new Error("Immediate transition limit exceeded. Check for an eventless loop."));
+		const immediate = executeTransitionCandidatesImmediate(stableState, event, candidates, hooks);
+		let next;
+		if (isEffect(immediate)) next = yield* immediate;
+		else next = immediate;
+		if (!next.transitioned) break;
+		if (next.reenter || next.newState._tag !== stableState._tag) lifecycleRequired = true;
+		steps.push(...next.steps);
+		stableState = next.newState;
+	}
+	return {
+		...result,
+		newState: stableState,
+		transitioned: steps.length > 0,
+		reenter: lifecycleRequired,
+		transition: steps.at(-1)?.transition,
+		steps
+	};
+});
 /**
 * Check if an event should be postponed in the current state.
 * @internal
@@ -99,12 +191,12 @@ const shouldPostpone = (machine, stateTag, eventTag) => machine._shouldPostpone(
 *
 * @internal
 */
-const processEventCore = (machine, currentState, event, self, stateScopeRef, system, actorId, hooks) => Effect.suspend(() => {
-	const processed = processEventCoreImmediate(machine, currentState, event, self, stateScopeRef, system, actorId, hooks);
+const processEventCore = (machine, currentState, event, self, stateScopeRef, system, actorId, hooks, generation = 0) => Effect.suspend(() => {
+	const processed = processEventCoreImmediate(machine, currentState, event, self, stateScopeRef, system, actorId, hooks, generation);
 	if (isEffect(processed)) return processed;
 	return Effect.succeed(processed);
 });
-const completeProcessedEvent = (machine, currentState, event, result, self, stateScopeRef, system, actorId, hooks) => {
+const completeProcessedEvent = (machine, currentState, event, result, self, stateScopeRef, system, actorId, hooks, generation = 0) => {
 	if (!result.transitioned) return {
 		newState: currentState,
 		previousState: currentState,
@@ -114,7 +206,8 @@ const completeProcessedEvent = (machine, currentState, event, result, self, stat
 		hasReply: false,
 		deferReply: false,
 		reply: void 0,
-		postponed: false
+		postponed: false,
+		transitions: []
 	};
 	const newState = result.newState;
 	const runLifecycle = newState._tag !== currentState._tag || result.reenter;
@@ -127,22 +220,59 @@ const completeProcessedEvent = (machine, currentState, event, result, self, stat
 		hasReply: result.hasReply,
 		deferReply: result.deferReply,
 		reply: result.reply,
-		postponed: false
+		postponed: false,
+		transitions: result.steps
 	};
-	if (!runLifecycle) return processed;
+	const observeTransitions = hooks?.onTransition;
+	if (!runLifecycle) {
+		if (observeTransitions === void 0 || result.steps.length === 0) return processed;
+		return Effect.forEach(result.steps, (step) => observeTransitions(step.previousState, step.newState, step.event), { discard: true }).pipe(Effect.as(processed));
+	}
 	return Effect.gen(function* () {
 		yield* Scope.close(stateScopeRef.current, Exit.void);
 		stateScopeRef.current = yield* Scope.make();
-		if (hooks?.onTransition !== void 0) yield* hooks.onTransition(currentState, newState, event);
+		if (observeTransitions !== void 0) yield* Effect.forEach(result.steps, (step) => observeTransitions(step.previousState, step.newState, step.event), { discard: true });
 		if (hooks?.onSpawnEffect !== void 0) yield* hooks.onSpawnEffect(newState);
-		yield* runSpawnEffects(machine, newState, { _tag: INTERNAL_ENTER_EVENT }, self, stateScopeRef.current, system, actorId, hooks?.onError, hooks?.onSpawnDefect);
+		yield* runSpawnEffects(machine, newState, { _tag: INTERNAL_ENTER_EVENT }, self, stateScopeRef.current, system, actorId, hooks?.onError, hooks?.onSpawnDefect, generation);
 		return processed;
 	});
 };
 /** @internal */
-const processEventCoreImmediate = (machine, currentState, event, self, stateScopeRef, system, actorId, hooks) => {
-	const execution = executeTransitionImmediate(machine, currentState, event);
-	const complete = (result) => completeProcessedEvent(machine, currentState, event, result, self, stateScopeRef, system, actorId, hooks);
+const processEventCoreImmediate = (machine, currentState, event, self, stateScopeRef, system, actorId, hooks, generation = 0) => {
+	const execution = executeTransitionImmediate(machine, currentState, event, hooks);
+	const complete = (result) => {
+		if (machine._findImmediateTransitions(result.newState._tag).length === 0) return completeProcessedEvent(machine, currentState, event, result, self, stateScopeRef, system, actorId, hooks, generation);
+		return Effect.gen(function* () {
+			const steps = [...result.steps];
+			let stableState = result.newState;
+			let lifecycleRequired = result.reenter || stableState._tag !== currentState._tag;
+			let depth = 0;
+			while (true) {
+				const candidates = machine._findImmediateTransitions(stableState._tag);
+				if (candidates.length === 0) break;
+				depth += 1;
+				if (depth > 100) return yield* Effect.die(/* @__PURE__ */ new Error("Immediate transition limit exceeded. Check for an eventless loop."));
+				const immediate = executeTransitionCandidatesImmediate(stableState, event, candidates, hooks);
+				let next;
+				if (isEffect(immediate)) next = yield* immediate;
+				else next = immediate;
+				if (!next.transitioned) break;
+				if (next.reenter || next.newState._tag !== stableState._tag) lifecycleRequired = true;
+				steps.push(...next.steps);
+				stableState = next.newState;
+			}
+			const processed = completeProcessedEvent(machine, currentState, event, {
+				...result,
+				newState: stableState,
+				transitioned: steps.length > 0,
+				reenter: lifecycleRequired,
+				transition: steps.at(-1)?.transition,
+				steps
+			}, self, stateScopeRef, system, actorId, hooks, generation);
+			if (isEffect(processed)) return yield* processed;
+			return processed;
+		});
+	};
 	if (!isEffect(execution)) return complete(execution);
 	return execution.pipe(Effect.catchCause((cause) => {
 		if (Cause.hasInterruptsOnly(cause)) return Effect.interrupt;
@@ -165,13 +295,14 @@ const processEventCoreImmediate = (machine, currentState, event, self, stateScop
 *
 * @internal
 */
-const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (machine, state, event, self, stateScope, system, actorId, onError, onSpawnDefect) {
+const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (machine, state, event, self, stateScope, system, actorId, onError, onSpawnDefect, generation = 0) {
 	const spawnEffects = machine._findSpawnEffects(state._tag);
 	const reportError = onError;
 	const defectSignal = onSpawnDefect;
 	for (const spawnEffect of spawnEffects) {
 		const effect = spawnEffect.handler({
 			actorId,
+			generation,
 			state,
 			event,
 			self,
@@ -197,7 +328,54 @@ const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (m
 * Uses indexed O(1) lookup. First matching transition wins.
 */
 const resolveTransition = (machine, currentState, event) => {
-	return machine._findTransitions(currentState._tag, event._tag)[0];
+	const resolution = evaluateTransitions(machine._findTransitions(currentState._tag, event._tag), currentState, event);
+	if (isEffect(resolution)) return Effect.runSync(Effect.die("Effect guards require actor.can(event). actor.client.canSync(event) is synchronous."));
+	return resolution.transition;
+};
+/** Resolve a transition with pure or Effect guards. */
+const resolveTransitionEffect = (machine, currentState, event) => {
+	const resolution = evaluateTransitions(machine._findTransitions(currentState._tag, event._tag), currentState, event);
+	if (isEffect(resolution)) return resolution.pipe(Effect.map((value) => value.transition));
+	return Effect.succeed(resolution.transition);
+};
+const evaluateTransitions = (candidates, currentState, event) => {
+	const ctx = {
+		state: currentState,
+		event
+	};
+	const loop = (index, evaluations) => {
+		const candidate = candidates[index];
+		if (candidate === void 0) return {
+			transition: void 0,
+			evaluations
+		};
+		if (candidate.guard === void 0) return {
+			transition: candidate,
+			evaluations
+		};
+		const guardName = candidate.guard.name || "<inline>";
+		const result = candidate.guard(ctx);
+		const continueWith = (passed) => {
+			const nextEvaluations = [...evaluations, {
+				guard: guardName,
+				state: currentState,
+				event,
+				result: passed
+			}];
+			if (passed) return {
+				transition: candidate,
+				evaluations: nextEvaluations
+			};
+			return loop(index + 1, nextEvaluations);
+		};
+		if (!isEffect(result)) return continueWith(result);
+		return result.pipe(Effect.flatMap((passed) => {
+			const next = continueWith(passed);
+			if (isEffect(next)) return next;
+			return Effect.succeed(next);
+		}));
+	};
+	return loop(0, []);
 };
 //#endregion
-export { executeTransition, executeTransitionImmediate, processEventCore, processEventCoreImmediate, resolveTransition, runSpawnEffects, shouldPostpone };
+export { executeTransition, executeTransitionImmediate, processEventCore, processEventCoreImmediate, resolveTransition, resolveTransitionEffect, runSpawnEffects, shouldPostpone };

package/dist/internal/utils.js

@@ -64,6 +64,7 @@ const isEffect = Effect.isEffect;
 const stubSystem = {
 	spawn: () => Effect.die("spawn not supported in stub system"),
 	get: () => Effect.die("get not supported in stub system"),
+	watch: () => Stream.die("watch not supported in stub system"),
 	stop: () => Effect.die("stop not supported in stub system"),
 	events: Stream.empty,
 	get actors() {