effect-machine 0.22.0 → 0.24.0

package/README.md

@@ -95,6 +95,10 @@ Effect Machine does not add an action queue or a second context system.
 
 Effect requirements remain in `R`. A machine cannot start until the application provides every required service. Effectful transition handlers must have `never` in their error channel. Convert expected failures to states or events.
 
+Machine-lifetime backgrounds can read `self.state` and `self.latestTransition`. These are the
+actor-owned subscription refs. They stay stable across supervision generations. Treat them as
+read-only and use `SubscriptionRef.get` or `SubscriptionRef.changes` to observe them.
+
 Read [the Effect model](./docs/effect-model.md) and [async work ownership](./docs/async-work.md).
 
 ## Guards and stable state
@@ -204,7 +208,8 @@ Read [Atom and UI integration](./docs/atom-and-ui.md) and browse [all examples](
 - Durability saves committed transitions.
 - Supervision restarts defects within an Effect `Schedule` budget.
 - Inspection reports events, named transition operations, transitions, named guards, tasks, Effects, errors, stops, and actor generations.
-- Dynamic Inspector hubs let lazy tools observe existing actors without actor restart or state duplication.
+- Typed `inspect` spawn options observe one actor.
+- `actor.system.inspect` lets a late tool observe all actors in one system.
 
 Read [Persistence and supervision](./docs/persistence-and-supervision.md) and [Inspection](./docs/inspection.md).
 

package/dist/actor.d.ts

@@ -1,5 +1,6 @@
 import { ExtractReply, ReplyTypeBrand } from "./internal/brands.js";
 import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.js";
+import { InspectorService } from "./inspection.js";
 import { ActorExit, Supervision } from "./supervision.js";
 import { Lifecycle, Machine } from "./machine.js";
 import { ProcessEventResult } from "./internal/transition.js";
@@ -238,11 +239,22 @@ interface ActorSystemService {
    * Returns an unsubscribe function.
    */
   readonly subscribe: (fn: SystemEventListener) => () => void;
+  /**
+   * Inspect all actors in this system.
+   *
+   * Registration affects future events only. The returned function removes the inspector.
+   */
+  readonly inspect: (inspector: InspectorService<{
+    readonly _tag: string;
+  }, {
+    readonly _tag: string;
+  }>) => () => void;
 }
 type SystemSpawnOptions<S, E, Input> = {
   readonly supervision?: Supervision.Policy;
   readonly lifecycle?: Lifecycle<S, E>;
   readonly hydrate?: S;
+  readonly inspect?: InspectorService<S, E>;
 } & ([Input] extends [void] ? {
   readonly input?: never;
 } : {
@@ -278,6 +290,7 @@ declare const createActor: <S extends {
   hydrated?: boolean;
   supervision?: Supervision.Policy;
   lifecycle?: Lifecycle<S, E>;
+  inspect?: InspectorService<S, E>;
   /** @internal Called by system after each restart — emits ActorRestarted system event */
   onRestart?: (generation: number, exit: ActorExit<unknown>) => Effect.Effect<void>;
 }) => Effect.Effect<ActorRef<S, E, O>, never, R>;

package/dist/actor.js

@@ -1,6 +1,6 @@
 import { ActorStoppedError, DuplicateActorError } from "./errors.js";
 import { resolveTransition, resolveTransitionEffect } from "./internal/transition.js";
-import { emitWithTimestamp, makeInspectionHooks } from "./internal/inspection.js";
+import { emitWithTimestamp, makeInspectionDispatcher, makeInspectionHooks } from "./internal/inspection.js";
 import { Inspector } from "./inspection.js";
 import { ActorExit } from "./supervision.js";
 import { createRuntime } from "./internal/runtime.js";
@@ -27,6 +27,7 @@ const actorSystemId = (id) => {
 	if (typeof id === "string") return id;
 	return id.id;
 };
+const systemInspectorsBySystem = /* @__PURE__ */ new WeakMap();
 /**
 * ActorSystem service tag
 */
@@ -259,6 +260,7 @@ const runSupervisionLoop = (cell, options) => Effect.gen(function* () {
 		const freshQueue = yield* Queue.unbounded();
 		yield* Ref.set(cell.eventQueueRef, freshQueue);
 		yield* SubscriptionRef.set(cell.stateRef, restartState);
+		yield* SubscriptionRef.set(cell.latestTransitionRef, void 0);
 		yield* Ref.set(cell.stoppedRef, false);
 		cell.children.clear();
 		const newRuntime = yield* options.spawnGeneration(cell.machine);
@@ -279,20 +281,21 @@ const runSupervisionLoop = (cell, options) => Effect.gen(function* () {
 */
 const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machine, options) {
 	const lifecycle = options.lifecycle;
-	const serviceContext = yield* Effect.context();
+	const capturedContext = yield* Effect.context();
 	const initial = options.initialState;
 	yield* Effect.annotateCurrentSpan("effect_machine.actor.id", id);
 	yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", initial._tag);
 	const { system, implicitSystemScope } = yield* resolveActorSystem();
-	const inspectorValue = Option.getOrUndefined(yield* Effect.serviceOption(Inspector));
+	const ambientInspector = Option.getOrUndefined(yield* Effect.serviceOption(Inspector));
+	const localInspector = options.inspect ?? ambientInspector;
+	const systemInspectors = systemInspectorsBySystem.get(system) ?? /* @__PURE__ */ new Set();
+	const inspectorValue = makeInspectionDispatcher(localInspector, systemInspectors);
+	const serviceContext = Context.add(capturedContext, Inspector, inspectorValue);
 	const childrenMap = /* @__PURE__ */ new Map();
 	const listeners = /* @__PURE__ */ new Set();
 	const transitionsPubSub = yield* PubSub.unbounded();
 	const generation = { current: 0 };
-	const inspectionHooks = (runtimeGeneration) => {
-		if (inspectorValue === void 0) return void 0;
-		return makeInspectionHooks(id, inspectorValue, () => runtimeGeneration);
-	};
+	const inspectionHooks = (runtimeGeneration) => makeInspectionHooks(id, inspectorValue, () => runtimeGeneration);
 	const stateRef = yield* SubscriptionRef.make(initial);
 	const lifecycleRef = yield* SubscriptionRef.make({ _tag: "Created" });
 	const latestTransitionRef = yield* SubscriptionRef.make(void 0);
@@ -322,8 +325,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	/** Build lifecycle hooks for a generation */
 	const buildRuntimeLifecycle = (runtimeGeneration) => {
 		let stopEmitted = false;
-		let onEvent = void 0;
-		if (inspectorValue !== void 0) onEvent = (state, event) => emitWithTimestamp(inspectorValue, (timestamp) => ({
+		const onEvent = (state, event) => emitWithTimestamp(inspectorValue, (timestamp) => ({
 			type: "@machine.event",
 			actorId: id,
 			generation: runtimeGeneration,
@@ -331,8 +333,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 			event,
 			timestamp
 		}));
-		let onFinal = void 0;
-		if (inspectorValue !== void 0) onFinal = (state) => Effect.gen(function* () {
+		const onFinal = (state) => Effect.gen(function* () {
 			stopEmitted = true;
 			yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
 				type: "@machine.stop",
@@ -342,8 +343,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 				timestamp
 			}));
 		});
-		let onInitialSpawnEffects = void 0;
-		if (inspectorValue !== void 0) onInitialSpawnEffects = (state) => emitWithTimestamp(inspectorValue, (timestamp) => ({
+		const onInitialSpawnEffects = (state) => emitWithTimestamp(inspectorValue, (timestamp) => ({
 			type: "@machine.effect",
 			actorId: id,
 			generation: runtimeGeneration,
@@ -354,12 +354,6 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		return {
 			onEvent,
 			onStateChange: (result, event) => Effect.gen(function* () {
-				const latest = result.transitions.at(-1);
-				if (latest !== void 0) yield* SubscriptionRef.set(latestTransitionRef, {
-					fromState: latest.previousState,
-					toState: latest.newState,
-					event: latest.event
-				});
 				notifyListeners(listeners, result.newState);
 				const durability = lifecycle?.durability;
 				if (durability === void 0 || !result.transitioned) return;
@@ -406,6 +400,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 			skipFinalizer: true,
 			cellResources: {
 				stateRef,
+				latestTransitionRef,
 				stoppedRef,
 				eventQueue: currentQueue
 			},
@@ -488,13 +483,14 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 	const withSpawnGate = (yield* Semaphore.make(1)).withPermits(1);
 	const eventPubSub = yield* PubSub.unbounded();
 	const eventListeners = /* @__PURE__ */ new Set();
+	const systemInspectors = /* @__PURE__ */ new Set();
 	const emitSystemEvent = (event) => Effect.sync(() => notifySystemListeners(eventListeners, event)).pipe(Effect.andThen(PubSub.publish(eventPubSub, event)), Effect.catchCause(() => Effect.void), Effect.asVoid);
 	yield* Effect.addFinalizer(() => {
 		const stops = [];
 		MutableHashMap.forEach(actorsMap, (actor) => {
 			stops.push(actor.stop);
 		});
-		return Effect.all(stops).pipe(Effect.andThen(PubSub.shutdown(eventPubSub)), Effect.asVoid);
+		return Effect.all(stops).pipe(Effect.andThen(Effect.sync(() => systemInspectors.clear())), Effect.andThen(PubSub.shutdown(eventPubSub)), Effect.asVoid);
 	});
 	/** Check for duplicate ID, register actor, attach scope cleanup if available */
 	const registerActor = Effect.fn("effect-machine.actorSystem.register")(function* (id, actor) {
@@ -558,6 +554,7 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 			hydrated: spawnOptions?.hydrate !== void 0,
 			supervision: spawnOptions?.supervision,
 			lifecycle: spawnOptions?.lifecycle,
+			inspect: spawnOptions?.inspect,
 			onRestart
 		});
 		actorRef = actor;
@@ -606,7 +603,7 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 		yield* actor.stop;
 		return true;
 	});
-	return ActorSystem.of({
+	const system = ActorSystem.of({
 		spawn,
 		get,
 		watch,
@@ -624,8 +621,16 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 			return () => {
 				eventListeners.delete(fn);
 			};
+		},
+		inspect: (inspector) => {
+			systemInspectors.add(inspector);
+			return () => {
+				systemInspectors.delete(inspector);
+			};
 		}
 	});
+	systemInspectorsBySystem.set(system, systemInspectors);
+	return system;
 });
 /**
 * Create an ActorSystem instance. Must be run in a Scope.

package/dist/cluster/entity-machine.js

@@ -55,6 +55,7 @@ const EntityMachine = { layer: (entity, machine, ...optionsArgument) => {
 		const versionRef = yield* Ref.make(persistCtx.initialVersion);
 		const computedInitial = initialState ?? machineInitial;
 		const stateRef = yield* SubscriptionRef.make(computedInitial);
+		const latestTransitionRef = yield* SubscriptionRef.make(void 0);
 		const stoppedRef = yield* Ref.make(false);
 		const eventQueue = yield* Queue.unbounded();
 		let hooks = void 0;
@@ -65,6 +66,7 @@ const EntityMachine = { layer: (entity, machine, ...optionsArgument) => {
 			childIdPrefix: `${entityId}/`,
 			cellResources: {
 				stateRef,
+				latestTransitionRef,
 				stoppedRef,
 				eventQueue
 			}

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 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 { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, GuardEvent, InspectionEvent, Inspector, InspectorHandler, InspectorService, OperationEvent, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
 import { ActorExit, DefectPhase, Supervision } from "./supervision.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 { ActorClient, ActorLifecycle, ActorRef, ActorRefSync, ActorScope, ActorSystem, ActorSystemKey, ActorSystemService, Default, SystemEvent, SystemEventListener, SystemSpawnOptions, TransitionInfo, actorSystemKey } 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, InspectorHub, InspectorService, OperationEvent, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, makeInspectorHub, 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, ActorSystemKey, 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, type InspectorHub, 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, actorSystemKey, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, makeInspectorHub, simulate, tracingInspector };
+export { type ActorClient, ActorExit, type ActorExit as ActorExitType, type ActorLifecycle, type ActorRef, type ActorRefSync, ActorScope, ActorStoppedError, type ActorSystemService as ActorSystem, Default as ActorSystemDefault, ActorSystemKey, 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, actorSystemKey, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };

package/dist/index.js

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

package/dist/inspection.d.ts

@@ -124,13 +124,6 @@ type InspectorHandler<S, E> = (event: InspectionEvent<S, E>) => void | Effect.Ef
 interface InspectorService<S, E> {
   readonly onInspect: InspectorHandler<S, E>;
 }
-/**
- * Dynamic Inspector fan-out for applications that load inspection consumers after actors start.
- */
-interface InspectorHub<S, E> {
-  readonly inspector: InspectorService<S, E>;
-  readonly register: (inspector: InspectorService<S, E>) => () => void;
-}
 declare const Inspector_base: Context.ServiceClass<Inspector, "effect-machine/inspection/Inspector", InspectorService<any, any>>;
 /**
  * Inspector service tag - optional service for machine introspection
@@ -156,17 +149,6 @@ declare const makeInspectorEffect: <S = {
   readonly _tag: string;
 }>(onInspect: (event: InspectionEvent<ResolveType<S>, ResolveType<E>>) => Effect.Effect<void>) => InspectorService<ResolveType<S>, ResolveType<E>>;
 declare const combineInspectors: <S, E>(...inspectors: ReadonlyArray<InspectorService<S, E>>) => InspectorService<S, E>;
-/**
- * Create an Inspector that accepts sinks throughout its lifetime.
- *
- * Provide `hub.inspector` before actor startup. Consumers can then register and unregister sinks
- * without restarting the actor. A sink failure does not affect the actor or other sinks.
- */
-declare const makeInspectorHub: <S = {
-  readonly _tag: string;
-}, E = {
-  readonly _tag: string;
-}>() => InspectorHub<ResolveType<S>, ResolveType<E>>;
 interface TracingInspectorOptions<S, E> {
   readonly spanName?: string | ((event: InspectionEvent<S, E>) => string);
   readonly attributes?: (event: InspectionEvent<S, E>) => Readonly<Record<string, string | number | boolean>>;
@@ -194,4 +176,4 @@ declare const collectingInspector: <S extends {
   readonly _tag: string;
 }>(events: InspectionEvent<S, E>[]) => InspectorService<S, E>;
 //#endregion
-export { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, GuardEvent, InspectionEvent, Inspector, InspectorHandler, InspectorHub, InspectorService, OperationEvent, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, makeInspectorHub, 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

@@ -1,3 +1,4 @@
+import { runInspectors } from "./internal/inspection.js";
 import { Context, Effect, Option } from "effect";
 //#region src/inspection.ts
 /**
@@ -15,39 +16,7 @@ var Inspector = class extends Context.Service()("effect-machine/inspection/Inspe
 */
 const makeInspector = (onInspect) => ({ onInspect });
 const makeInspectorEffect = (onInspect) => ({ onInspect });
-const inspectionEffect = (inspector, event) => Effect.suspend(() => {
-	const result = inspector.onInspect(event);
-	if (Effect.isEffect(result)) return result;
-	return Effect.void;
-});
-const combineInspectors = (...inspectors) => ({ onInspect: (event) => Effect.forEach(inspectors, (inspector) => inspectionEffect(inspector, event).pipe(Effect.ignoreCause), {
-	concurrency: 16,
-	discard: true
-}) });
-/**
-* Create an Inspector that accepts sinks throughout its lifetime.
-*
-* Provide `hub.inspector` before actor startup. Consumers can then register and unregister sinks
-* without restarting the actor. A sink failure does not affect the actor or other sinks.
-*/
-const makeInspectorHub = () => {
-	const inspectorByRegistration = /* @__PURE__ */ new Map();
-	const inspector = { onInspect: (event) => Effect.forEach(Array.from(inspectorByRegistration.values()), (registeredInspector) => inspectionEffect(registeredInspector, event).pipe(Effect.ignoreCause), {
-		concurrency: 16,
-		discard: true
-	}) };
-	const register = (registeredInspector) => {
-		const registration = Symbol();
-		inspectorByRegistration.set(registration, registeredInspector);
-		return () => {
-			inspectorByRegistration.delete(registration);
-		};
-	};
-	return {
-		inspector,
-		register
-	};
-};
+const combineInspectors = (...inspectors) => ({ onInspect: (event) => runInspectors(inspectors, event) });
 const inspectionSpanName = (event) => {
 	switch (event.type) {
 		case "@machine.spawn": return `Machine.inspect ${event.initialState._tag}`;
@@ -181,4 +150,4 @@ const collectingInspector = (events) => ({ onInspect: (event) => {
 	events.push(event);
 } });
 //#endregion
-export { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, makeInspectorHub, tracingInspector };
+export { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector };

package/dist/internal/inspection.d.ts

@@ -1,7 +1,17 @@
+import { InspectionEvent, InspectorService } from "../inspection.js";
 import { ProcessEventHooks } from "./transition.js";
-import { InspectorService } from "../inspection.js";
+import { Effect } from "effect";
 //#region src/internal/inspection.d.ts
+type Tagged = {
+  readonly _tag: string;
+};
+/** Run one inspector without letting its failure affect the machine. */
+declare const runInspector: <S, E>(inspector: InspectorService<S, E>, event: InspectionEvent<S, E>) => Effect.Effect<void, never, never>;
+/** Run inspectors in order and isolate each failure. */
+declare const runInspectors: <S, E>(inspectors: Iterable<InspectorService<S, E>>, event: InspectionEvent<S, E>) => Effect.Effect<void, never, never>;
+/** Build the actor-owned dispatcher for local and system inspection. */
+declare const makeInspectionDispatcher: <S extends Tagged, E extends Tagged>(localInspector: InspectorService<S, E> | undefined, systemInspectors: ReadonlySet<InspectorService<Tagged, Tagged>>) => InspectorService<S, E>;
 /** Adapt the Inspector service to the transition kernel. */
 declare const makeInspectionHooks: <S, E>(actorId: string, inspector: InspectorService<S, E>, getGeneration?: () => number) => ProcessEventHooks<S, E>;
 //#endregion
-export { makeInspectionHooks };
+export { makeInspectionDispatcher, makeInspectionHooks, runInspector, runInspectors };

package/dist/internal/inspection.js

@@ -1,14 +1,32 @@
 import { Cause, Clock, Effect } from "effect";
 //#region src/internal/inspection.ts
+const inspectorActivity = /* @__PURE__ */ new WeakMap();
+/** Run one inspector without letting its failure affect the machine. */
+const runInspector = Effect.fn("effect-machine.runInspector")(function* (inspector, event) {
+	const result = yield* Effect.try(() => inspector.onInspect(event)).pipe(Effect.orElseSucceed(() => void 0));
+	if (Effect.isEffect(result)) yield* result.pipe(Effect.ignoreCause);
+});
+/** Run inspectors in order and isolate each failure. */
+const runInspectors = Effect.fn("effect-machine.runInspectors")(function* (inspectors, event) {
+	for (const inspector of inspectors) yield* runInspector(inspector, event);
+});
+/** Build the actor-owned dispatcher for local and system inspection. */
+const makeInspectionDispatcher = (localInspector, systemInspectors) => {
+	const inspector = { onInspect: (event) => Effect.gen(function* () {
+		if (localInspector !== void 0) yield* runInspector(localInspector, event);
+		for (const systemInspector of systemInspectors) yield* runInspector(systemInspector, event);
+	}) };
+	inspectorActivity.set(inspector, () => localInspector !== void 0 || systemInspectors.size > 0);
+	return inspector;
+};
 /**
 * Emit an inspection event with timestamp from Clock.
 * @internal
 */
 const emitWithTimestamp = Effect.fn("effect-machine.emitWithTimestamp")(function* (inspector, makeEvent) {
-	if (inspector === void 0) return;
+	if (inspector === void 0 || inspectorActivity.get(inspector)?.() === false) return;
 	const event = makeEvent(yield* Clock.currentTimeMillis);
-	const result = yield* Effect.try(() => inspector.onInspect(event)).pipe(Effect.orElseSucceed(() => void 0));
-	if (Effect.isEffect(result)) yield* result.pipe(Effect.ignoreCause);
+	yield* runInspector(inspector, event);
 });
 /** Adapt the Inspector service to the transition kernel. */
 const makeInspectionHooks = (actorId, inspector, getGeneration = () => 0) => ({
@@ -60,4 +78,4 @@ const makeInspectionHooks = (actorId, inspector, getGeneration = () => 0) => ({
 	}))
 });
 //#endregion
-export { emitWithTimestamp, makeInspectionHooks };
+export { emitWithTimestamp, makeInspectionDispatcher, makeInspectionHooks, runInspector, runInspectors };

package/dist/internal/runtime.js

@@ -55,7 +55,7 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 	const generation = config.generation ?? 0;
 	const services = yield* Effect.context();
 	const fork = Effect.runForkWith(services);
-	const { stateRef, stoppedRef, eventQueue } = config.cellResources;
+	const { stateRef, latestTransitionRef, stoppedRef, eventQueue } = config.cellResources;
 	const pendingRequests = /* @__PURE__ */ new Set();
 	const exitDeferred = yield* Deferred.make();
 	const actorScope = yield* Scope.make();
@@ -72,6 +72,8 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 	let spawn = defaultSpawn;
 	if (onChildSpawned !== void 0) spawn = (childId, childMachine) => defaultSpawn(childId, childMachine).pipe(Effect.tap((child) => onChildSpawned(childId, child)));
 	const self = {
+		state: stateRef,
+		latestTransition: latestTransitionRef,
 		send: selfSend,
 		spawn,
 		reply: (value) => Effect.sync(() => {
@@ -117,6 +119,12 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 		else initialResult = initialProcessing;
 		if (initialResult.transitioned) {
 			yield* SubscriptionRef.set(stateRef, initialResult.newState);
+			const latest = initialResult.transitions.at(-1);
+			if (latest !== void 0) yield* SubscriptionRef.set(latestTransitionRef, {
+				fromState: latest.previousState,
+				toState: latest.newState,
+				event: latest.event
+			});
 			if (lifecycle?.onStateChange !== void 0) {
 				const stateChange = lifecycle.onStateChange(initialResult, initEvent);
 				if (isEffect(stateChange)) yield* stateChange;
@@ -164,7 +172,7 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 				return Effect.void;
 			})), Effect.asVoid)
 		};
-		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);
+		const loopFiber = yield* runtimeEventLoop(machine, stateRef, latestTransitionRef, 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(RuntimeExit.Defect(exit.cause, "background")).pipe(Effect.andThen(Ref.set(stoppedRef, true)), Effect.andThen(Fiber.interrupt(loopFiber)));
@@ -190,7 +198,7 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 	}).pipe(Effect.asVoid);
 	if (config.skipFinalizer !== true) yield* Effect.addFinalizer(() => stop);
 	return {
-		...makeHandle(actorId, stateRef, stoppedRef, eventQueue, pendingRequests, exitDeferred),
+		...makeHandle(actorId, stateRef, latestTransitionRef, stoppedRef, eventQueue, pendingRequests, exitDeferred),
 		stop: stop.pipe(Effect.provide(services)),
 		start: start.pipe(Effect.provide(services))
 	};
@@ -199,7 +207,7 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 * Build the runtime handle.
 * Shared between initial-final and normal paths.
 */
-const makeHandle = (actorId, stateRef, stoppedRef, eventQueue, pendingRequests, exitDeferred) => {
+const makeHandle = (actorId, stateRef, latestTransitionRef, stoppedRef, eventQueue, pendingRequests, exitDeferred) => {
 	const track = (deferred, settle) => {
 		pendingRequests.add(settle);
 		return Deferred.await(deferred).pipe(Effect.ensuring(Effect.sync(() => pendingRequests.delete(settle))));
@@ -261,6 +269,7 @@ const makeHandle = (actorId, stateRef, stoppedRef, eventQueue, pendingRequests,
 		},
 		getState: SubscriptionRef.get(stateRef),
 		stateRef,
+		latestTransitionRef,
 		stop: Effect.void,
 		start: Effect.void,
 		settlePendingRequests: settlePendingRequests(pendingRequests, actorId),
@@ -272,7 +281,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, generation, system, exitDeferred, hooks, deferredReplyRef, lifecycle, fork) {
+const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function* (machine, stateRef, latestTransitionRef, 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);
@@ -320,7 +329,15 @@ const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function*
 		let result;
 		if (isEffect(processing)) result = yield* processing;
 		else result = processing;
-		if (result.transitioned) yield* SubscriptionRef.set(stateRef, result.newState);
+		if (result.transitioned) {
+			yield* SubscriptionRef.set(stateRef, result.newState);
+			const latest = result.transitions.at(-1);
+			if (latest !== void 0) yield* SubscriptionRef.set(latestTransitionRef, {
+				fromState: latest.previousState,
+				toState: latest.newState,
+				event: latest.event
+			});
+		}
 		if (lifecycle?.onStateChange !== void 0 && result.transitioned) {
 			const stateChange = lifecycle.onStateChange(result, event);
 			if (isEffect(stateChange)) yield* stateChange;

package/dist/internal/utils.js

@@ -70,7 +70,8 @@ const stubSystem = {
 	get actors() {
 		return /* @__PURE__ */ new Map();
 	},
-	subscribe: () => () => {}
+	subscribe: () => () => {},
+	inspect: () => () => {}
 };
 //#endregion
 export { INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, getTag, isDeferReplyResult, isEffect, isReplyResult, makeDeferReply, makeReply, stubSystem };

package/dist/machine.d.ts

@@ -2,16 +2,21 @@ import { DeferReplyResult, ReplyResult, TransitionResult, makeDeferReply, makeRe
 import { BrandedEvent, BrandedState, ExtractReply, TaggedOrConstructor } from "./internal/brands.js";
 import { MachineEventSchema, MachineStateSchema, VariantsUnion } from "./schema.js";
 import { ActorStoppedError, DuplicateActorError } from "./errors.js";
+import { InspectorService } from "./inspection.js";
 import { Supervision } from "./supervision.js";
-import { ActorRef, ActorSystemService } from "./actor.js";
-import { Duration, Effect, Option, Schema, Scope } from "effect";
+import { ActorRef, ActorSystemService, TransitionInfo } from "./actor.js";
+import { Duration, Effect, Option, Schema, Scope, SubscriptionRef } from "effect";
 declare namespace machine_d_exports {
   export { DeferReplyResult, Durability, DurabilityCommit, FinalContext, GuardPredicate, HandlerContext, InputMakeConfig, Lifecycle, Machine, MachineRef, MakeConfig, Recovery, RecoveryContext, ReplayOptions, ReplyResult, SpawnOptions, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, TransitionHandler, deferReply, make, replay, reply, run, scoped, spawn };
 }
 /**
  * Self reference for sending events back to the machine
  */
-interface MachineRef<Event> {
+interface MachineRef<Event, State = never> {
+  /** Actor-owned current state. Consumers must treat this ref as read-only. */
+  readonly state: SubscriptionRef.SubscriptionRef<State>;
+  /** Actor-owned latest accepted transition. Consumers must treat this ref as read-only. */
+  readonly latestTransition: SubscriptionRef.SubscriptionRef<TransitionInfo<State, Event> | undefined>;
   readonly send: (event: Event) => Effect.Effect<void>;
   readonly spawn: <S2 extends {
     readonly _tag: string;
@@ -40,7 +45,7 @@ interface StateHandlerContext<State, Event> {
   readonly generation: number;
   readonly state: State;
   readonly event: Event;
-  readonly self: MachineRef<Event>;
+  readonly self: MachineRef<Event, State>;
   readonly system: ActorSystemService;
 }
 /**
@@ -325,6 +330,7 @@ type SpawnOptions<S, E, Input> = {
   readonly hydrate?: S;
   readonly supervision?: Supervision.Policy;
   readonly lifecycle?: Lifecycle<S, E>;
+  readonly inspect?: InspectorService<S, E>;
 } & ([Input] extends [void] ? {
   readonly input?: never;
 } : {
@@ -339,6 +345,7 @@ type SpawnOptions<S, E, Input> = {
  *
  * // With lifecycle (recovery + durability)
  * const actor = yield* Machine.spawn(machine, {
+ *   inspect: consoleInspector(),
  *   lifecycle: {
  *     recovery: { resolve: (ctx) => storage.get("actor-state") },
  *     durability: { save: (commit) => storage.set("actor-state", commit.nextState) },

package/dist/machine.js

@@ -443,7 +443,8 @@ const spawnImpl = Effect.fn("effect-machine.spawn")(function* (machine, idOrOpti
 		machineInitial,
 		hydrated: opts?.hydrate !== void 0,
 		supervision: opts?.supervision,
-		lifecycle: opts?.lifecycle
+		lifecycle: opts?.lifecycle,
+		inspect: opts?.inspect
 	});
 	const maybeScope = yield* Effect.serviceOption(ActorScope);
 	if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, actor.stop);
@@ -458,6 +459,7 @@ const spawnImpl = Effect.fn("effect-machine.spawn")(function* (machine, idOrOpti
 *
 * // With lifecycle (recovery + durability)
 * const actor = yield* Machine.spawn(machine, {
+*   inspect: consoleInspector(),
 *   lifecycle: {
 *     recovery: { resolve: (ctx) => storage.get("actor-state") },
 *     durability: { save: (commit) => storage.set("actor-state", commit.nextState) },

package/package.json

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