effect-machine 0.19.0 → 0.20.0

package/dist/index.d.ts

@@ -2,9 +2,9 @@ import { DeferReplyResult, ReplyResult } from "./internal/utils.js";
 import { Event, MachineEventSchema, MachineStateSchema, ReplyFields, State } from "./schema.js";
 import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, NoReplyError, PersistenceError, VersionConflictError } from "./errors.js";
 import { ActorExit, DefectPhase, Supervision } from "./supervision.js";
-import { Durability, DurabilityCommit, HandlerContext, Lifecycle, Machine, MachineRef, MakeConfig, Recovery, RecoveryContext, StateHandlerContext, TaskOptions, TimeoutConfig, machine_d_exports } from "./machine.js";
+import { Durability, DurabilityCommit, FinalContext, GuardPredicate, HandlerContext, InputMakeConfig, Lifecycle, Machine, MachineRef, MakeConfig, Recovery, RecoveryContext, ReplayOptions, SpawnOptions, StateHandlerContext, TaskOptions, TimeoutConfig, machine_d_exports } from "./machine.js";
 import { ProcessEventResult } from "./internal/transition.js";
-import { ActorRef, ActorRefSync, ActorScope, ActorSystem, ActorSystemService, 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, InspectorService, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
-export { ActorExit, type ActorRef, type ActorRefSync, ActorScope, ActorStoppedError, type ActorSystemService as ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type DefectPhase, type DeferReplyResult, DuplicateActorError, type Durability, type DurabilityCommit, type EffectEvent, type ErrorEvent, Event, type EventReceivedEvent, type HandlerContext, type InspectionEvent, type InspectorService as Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, type Lifecycle, machine_d_exports as Machine, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, NoReplyError, PersistenceError, type ProcessEventResult, type Recovery, type RecoveryContext, type ReplyFields, type ReplyResult, type SimulationResult, 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 TransitionEvent, type TransitionInfo, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };
+import { ActorClient, ActorLifecycle, ActorRef, ActorRefSync, ActorScope, ActorSystem, ActorSystemService, Default, SystemEvent, SystemEventListener, SystemSpawnOptions, TransitionInfo } from "./actor.js";
+import { InputTestHarnessOptions, SimulationOptions, SimulationResult, TestHarness, TestHarnessOptions, assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
+import { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, GuardEvent, InspectionEvent, Inspector, InspectorHandler, InspectorService, OperationEvent, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
+export { type ActorClient, ActorExit, type ActorExit as ActorExitType, type ActorLifecycle, type ActorRef, type ActorRefSync, ActorScope, ActorStoppedError, type ActorSystemService as ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type DefectPhase, type DeferReplyResult, DuplicateActorError, type Durability, type DurabilityCommit, type EffectEvent, type ErrorEvent, Event, type EventReceivedEvent, type FinalContext, type GuardEvent, type GuardPredicate, type HandlerContext, type InputMakeConfig, type InputTestHarnessOptions, type InspectionEvent, type InspectorService as Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, type Lifecycle, machine_d_exports as Machine, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, NoReplyError, type OperationEvent, PersistenceError, type ProcessEventResult, type Recovery, type RecoveryContext, type ReplayOptions, type ReplyFields, type ReplyResult, type SimulationOptions, type SimulationResult, type SpawnEvent, type SpawnOptions, State, type StateHandlerContext, type StopEvent, Supervision, type SystemEvent, type SystemEventListener, type SystemSpawnOptions, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TimeoutConfig, type TracingInspectorOptions, type TransitionEvent, type TransitionInfo, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };

package/dist/inspection.d.ts

@@ -10,6 +10,7 @@ type ResolveType<T> = T extends Schema.Schema<infer A> ? A : T;
 interface SpawnEvent<S> {
   readonly type: "@machine.spawn";
   readonly actorId: string;
+  readonly generation: number;
   readonly initialState: S;
   readonly timestamp: number;
 }
@@ -19,6 +20,7 @@ interface SpawnEvent<S> {
 interface EventReceivedEvent<S, E> {
   readonly type: "@machine.event";
   readonly actorId: string;
+  readonly generation: number;
   readonly state: S;
   readonly event: E;
   readonly timestamp: number;
@@ -29,17 +31,40 @@ interface EventReceivedEvent<S, E> {
 interface TransitionEvent<S, E> {
   readonly type: "@machine.transition";
   readonly actorId: string;
+  readonly generation: number;
   readonly fromState: S;
   readonly toState: S;
   readonly event: E;
   readonly timestamp: number;
 }
+/** Event emitted after a transition guard runs. */
+interface GuardEvent<S, E> {
+  readonly type: "@machine.guard";
+  readonly actorId: string;
+  readonly generation: number;
+  readonly state: S;
+  readonly event: E;
+  readonly guard: string;
+  readonly result: boolean;
+  readonly timestamp: number;
+}
+/** Event emitted before an accepted transition handler runs. */
+interface OperationEvent<S, E> {
+  readonly type: "@machine.operation";
+  readonly actorId: string;
+  readonly generation: number;
+  readonly operation: string;
+  readonly state: S;
+  readonly event: E;
+  readonly timestamp: number;
+}
 /**
  * Event emitted when a spawn effect runs
  */
 interface EffectEvent<S> {
   readonly type: "@machine.effect";
   readonly actorId: string;
+  readonly generation: number;
   readonly effectType: "spawn";
   readonly state: S;
   readonly timestamp: number;
@@ -47,9 +72,10 @@ interface EffectEvent<S> {
 interface TaskEvent<S> {
   readonly type: "@machine.task";
   readonly actorId: string;
+  readonly generation: number;
   readonly state: S;
   readonly taskName?: string;
-  readonly phase: "start" | "success" | "failure" | "interrupt";
+  readonly phase: "start" | "success" | "failure" | "defect" | "interrupt";
   readonly error?: string;
   readonly timestamp: number;
 }
@@ -59,6 +85,7 @@ interface TaskEvent<S> {
 interface ErrorEvent<S, E> {
   readonly type: "@machine.error";
   readonly actorId: string;
+  readonly generation: number;
   readonly phase: "transition" | "spawn";
   readonly state: S;
   readonly event: E;
@@ -71,13 +98,14 @@ interface ErrorEvent<S, E> {
 interface StopEvent<S> {
   readonly type: "@machine.stop";
   readonly actorId: string;
+  readonly generation: number;
   readonly finalState: S;
   readonly timestamp: number;
 }
 /**
  * Union of all inspection events
  */
-type InspectionEvent<S, E> = SpawnEvent<S> | EventReceivedEvent<S, E> | TransitionEvent<S, E> | EffectEvent<S> | TaskEvent<S> | ErrorEvent<S, E> | StopEvent<S>;
+type InspectionEvent<S, E> = SpawnEvent<S> | EventReceivedEvent<S, E> | TransitionEvent<S, E> | GuardEvent<S, E> | OperationEvent<S, E> | EffectEvent<S> | TaskEvent<S> | ErrorEvent<S, E> | StopEvent<S>;
 /**
  * Convenience alias for untyped inspection events.
  * Useful for general-purpose inspectors that don't need specific state/event types.
@@ -148,4 +176,4 @@ declare const collectingInspector: <S extends {
   readonly _tag: string;
 }>(events: InspectionEvent<S, E>[]) => InspectorService<S, E>;
 //#endregion
-export { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, InspectorHandler, InspectorService, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector };
+export { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, GuardEvent, InspectionEvent, Inspector, InspectorHandler, InspectorService, OperationEvent, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector };

package/dist/inspection.js

@@ -29,6 +29,8 @@ const inspectionSpanName = (event) => {
 		case "@machine.spawn": return `Machine.inspect ${event.initialState._tag}`;
 		case "@machine.event": return `Machine.inspect ${event.event._tag}`;
 		case "@machine.transition": return `Machine.inspect ${event.fromState._tag}->${event.toState._tag}`;
+		case "@machine.guard": return `Machine.inspect guard:${event.guard}`;
+		case "@machine.operation": return `Machine.inspect operation:${event.operation}`;
 		case "@machine.effect": return `Machine.inspect ${event.effectType}`;
 		case "@machine.task": return `Machine.inspect task:${event.phase}`;
 		case "@machine.error": return `Machine.inspect ${event.phase}`;
@@ -40,6 +42,8 @@ const inspectionTraceName = (event) => {
 		case "@machine.spawn": return `machine.spawn ${event.initialState._tag}`;
 		case "@machine.event": return `machine.event ${event.event._tag}`;
 		case "@machine.transition": return `machine.transition ${event.fromState._tag}->${event.toState._tag}`;
+		case "@machine.guard": return `machine.guard ${event.guard}`;
+		case "@machine.operation": return `machine.operation ${event.operation}`;
 		case "@machine.effect": return `machine.effect ${event.effectType}`;
 		case "@machine.task": {
 			let taskSuffix = "";
@@ -53,6 +57,7 @@ const inspectionTraceName = (event) => {
 const inspectionAttributes = (event) => {
 	const shared = {
 		"machine.actor.id": event.actorId,
+		"machine.actor.generation": event.generation,
 		"machine.inspection.type": event.type
 	};
 	switch (event.type) {
@@ -71,6 +76,19 @@ const inspectionAttributes = (event) => {
 			"machine.state.to": event.toState._tag,
 			"machine.event.tag": event.event._tag
 		};
+		case "@machine.guard": return {
+			...shared,
+			"machine.state.current": event.state._tag,
+			"machine.event.tag": event.event._tag,
+			"machine.guard.name": event.guard,
+			"machine.guard.result": event.result
+		};
+		case "@machine.operation": return {
+			...shared,
+			"machine.state.current": event.state._tag,
+			"machine.event.tag": event.event._tag,
+			"machine.operation.name": event.operation
+		};
 		case "@machine.effect": return {
 			...shared,
 			"machine.state.current": event.state._tag,
@@ -110,6 +128,7 @@ const tracingInspector = (options) => ({ onInspect: (event) => {
 		const currentSpan = yield* Effect.option(Effect.currentSpan);
 		if (Option.isSome(currentSpan)) currentSpan.value.event(traceName, BigInt(event.timestamp) * 1000000n, {
 			actorId: event.actorId,
+			generation: event.generation,
 			inspectionType: event.type
 		});
 	})().pipe(Effect.withSpan(spanName ?? inspectionSpanName(event), { attributes }));
@@ -123,6 +142,8 @@ const consoleInspector = () => makeInspectorEffect((event) => {
 		case "@machine.spawn": return Effect.log(`${prefix} spawned -> ${event.initialState._tag}`);
 		case "@machine.event": return Effect.log(`${prefix} received ${event.event._tag} in ${event.state._tag}`);
 		case "@machine.transition": return Effect.log(`${prefix} ${event.fromState._tag} -> ${event.toState._tag}`);
+		case "@machine.guard": return Effect.log(`${prefix} guard ${event.guard} -> ${String(event.result)}`);
+		case "@machine.operation": return Effect.log(`${prefix} operation ${event.operation} in ${event.state._tag}`);
 		case "@machine.effect": return Effect.log(`${prefix} ${event.effectType} effect in ${event.state._tag}`);
 		case "@machine.task": return Effect.log(`${prefix} task ${event.phase} ${event.taskName ?? "<unnamed>"} in ${event.state._tag}`);
 		case "@machine.error": return Effect.log(`${prefix} error in ${event.phase} ${event.state._tag} - ${String(event.error)}`);

package/dist/internal/inspection.d.ts

@@ -2,6 +2,6 @@ import { ProcessEventHooks } from "./transition.js";
 import { InspectorService } from "../inspection.js";
 //#region src/internal/inspection.d.ts
 /** Adapt the Inspector service to the transition kernel. */
-declare const makeInspectionHooks: <S, E>(actorId: string, inspector: InspectorService<S, E>) => ProcessEventHooks<S, E>;
+declare const makeInspectionHooks: <S, E>(actorId: string, inspector: InspectorService<S, E>, getGeneration?: () => number) => ProcessEventHooks<S, E>;
 //#endregion
 export { makeInspectionHooks };

package/dist/internal/inspection.js

@@ -11,10 +11,30 @@ const emitWithTimestamp = Effect.fn("effect-machine.emitWithTimestamp")(function
 	if (Effect.isEffect(result)) yield* result.pipe(Effect.ignoreCause);
 });
 /** Adapt the Inspector service to the transition kernel. */
-const makeInspectionHooks = (actorId, inspector) => ({
+const makeInspectionHooks = (actorId, inspector, getGeneration = () => 0) => ({
+	onGuard: (evaluation) => emitWithTimestamp(inspector, (timestamp) => ({
+		type: "@machine.guard",
+		actorId,
+		generation: getGeneration(),
+		state: evaluation.state,
+		event: evaluation.event,
+		guard: evaluation.guard,
+		result: evaluation.result,
+		timestamp
+	})),
+	onOperation: (operation) => emitWithTimestamp(inspector, (timestamp) => ({
+		type: "@machine.operation",
+		actorId,
+		generation: getGeneration(),
+		operation: operation.operation,
+		state: operation.state,
+		event: operation.event,
+		timestamp
+	})),
 	onSpawnEffect: (state) => emitWithTimestamp(inspector, (timestamp) => ({
 		type: "@machine.effect",
 		actorId,
+		generation: getGeneration(),
 		effectType: "spawn",
 		state,
 		timestamp
@@ -22,6 +42,7 @@ const makeInspectionHooks = (actorId, inspector) => ({
 	onTransition: (from, to, event) => emitWithTimestamp(inspector, (timestamp) => ({
 		type: "@machine.transition",
 		actorId,
+		generation: getGeneration(),
 		fromState: from,
 		toState: to,
 		event,
@@ -30,6 +51,7 @@ const makeInspectionHooks = (actorId, inspector) => ({
 	onError: (info) => emitWithTimestamp(inspector, (timestamp) => ({
 		type: "@machine.error",
 		actorId,
+		generation: getGeneration(),
 		phase: info.phase,
 		state: info.state,
 		event: info.event,

package/dist/internal/machine-definition.d.ts

@@ -4,6 +4,7 @@ interface Transition<State, Event, R> {
   readonly eventTag: string;
   readonly handler: TransitionHandler<State, Event, State, R>;
   readonly reenter?: boolean;
+  readonly guard?: GuardPredicate<State, Event, never>;
 }
 interface SpawnEffect<State, Event, R> {
   readonly stateTag: string;

package/dist/internal/machine-initialization.d.ts

@@ -0,0 +1,21 @@
+//#region src/internal/machine-initialization.d.ts
+/** How a machine creates the initial state for one actor. */
+type MachineInitialization<Input, State> = {
+  readonly _tag: "Static";
+  readonly state: State;
+} | {
+  readonly _tag: "Input";
+  readonly initialize: (input: Input) => State;
+};
+declare const make: <Input, State>(initial: State | ((input: Input) => State)) => MachineInitialization<Input, State>;
+/** Resolve one actor initial state. This is the only input erasure seam. */
+declare const resolve: <Input, State>(initialization: MachineInitialization<Input, State>, input: unknown) => State;
+/** Return the static value, or undefined for an input machine. */
+declare const staticValue: <Input, State>(initialization: MachineInitialization<Input, State>) => State | undefined;
+declare const MachineInitialization: {
+  make: typeof make;
+  resolve: typeof resolve;
+  staticValue: typeof staticValue;
+};
+//#endregion
+export { MachineInitialization };

package/dist/internal/machine-initialization.js

@@ -0,0 +1,27 @@
+//#region src/internal/machine-initialization.ts
+const make = (initial) => {
+	if (typeof initial === "function") return {
+		_tag: "Input",
+		initialize: initial
+	};
+	return {
+		_tag: "Static",
+		state: initial
+	};
+};
+/** Resolve one actor initial state. This is the only input erasure seam. */
+const resolve = (initialization, input) => {
+	if (initialization._tag === "Static") return initialization.state;
+	return initialization.initialize(input);
+};
+/** Return the static value, or undefined for an input machine. */
+const staticValue = (initialization) => {
+	if (initialization._tag === "Static") return initialization.state;
+};
+const MachineInitialization = {
+	make,
+	resolve,
+	staticValue
+};
+//#endregion
+export { MachineInitialization };

package/dist/internal/runtime.d.ts

@@ -1 +1,15 @@
-export {}
+import { DefectPhase } from "../supervision.js";
+//#region src/internal/runtime.d.ts
+/** Internal exit reason for one runtime generation. */
+type RuntimeExit<S> = {
+  readonly _tag: "Final";
+  readonly state: S;
+} | {
+  readonly _tag: "Stopped";
+} | {
+  readonly _tag: "Defect";
+  readonly cause: Cause.Cause<unknown>;
+  readonly phase: DefectPhase;
+};
+//#endregion
+export { RuntimeExit };

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 };