feat: add machine introspection and tracing

Two-layer observability for effect-machine:

Layer 1: Effect Spans (OTel integration)
- effect-machine.actor.spawn - actor lifecycle span
- effect-machine.event.process - per-event processing span
- effect-machine.effect.{entry,exit,transition} - effect spans
- All spans include semantic attributes for state, event, actor ID

Layer 2: Inspector API (callback-based)
- InspectorService - optional context service
- InspectionEvent union: @machine.spawn, @machine.event,
  @machine.guard, @machine.transition, @machine.effect, @machine.stop
- Helpers: makeInspector(), collectingInspector(), consoleInspector()

Guard Naming for introspection:
- Guard.make(predicate, name?) - optional name param
- Guard.named(name, guard) - add name to existing guard
- Guard.and/or/not compose names: "and(guardA, guardB)"

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: cevr

src/combinators/on.ts

@@ -56,6 +56,7 @@ function onImpl<
       guard: normalizedOptions?.guard as unknown as
         | ((ctx: TransitionContext<State, Event>) => boolean)
         | undefined,
+      guardName: normalizedOptions?.guardName,
       effect: normalizedOptions?.effect as unknown as
         | ((ctx: TransitionContext<State, Event>) => Effect.Effect<void, never, R2>)
         | undefined,

src/index.ts

@@ -69,3 +69,21 @@ export type {
 } from "./internal/types.js";
 export { Guard, normalizeGuard } from "./internal/types.js";
 export type { Guard as GuardType } from "./internal/types.js";
+
+// Inspection / introspection
+export type {
+  EffectEvent,
+  EventReceivedEvent,
+  GuardEvaluatedEvent,
+  InspectionEvent,
+  Inspector,
+  SpawnEvent,
+  StopEvent,
+  TransitionEvent,
+} from "./inspection.js";
+export {
+  collectingInspector,
+  consoleInspector,
+  Inspector as InspectorService,
+  makeInspector,
+} from "./inspection.js";

src/inspection.ts

@@ -0,0 +1,150 @@
+import { Context } from "effect";
+
+// ============================================================================
+// Inspection Events
+// ============================================================================
+
+/**
+ * Event emitted when an actor is spawned
+ */
+export interface SpawnEvent<S> {
+  readonly type: "@machine.spawn";
+  readonly actorId: string;
+  readonly initialState: S;
+  readonly timestamp: number;
+}
+
+/**
+ * Event emitted when an actor receives an event
+ */
+export interface EventReceivedEvent<S, E> {
+  readonly type: "@machine.event";
+  readonly actorId: string;
+  readonly state: S;
+  readonly event: E;
+  readonly timestamp: number;
+}
+
+/**
+ * Event emitted when a guard is evaluated
+ */
+export interface GuardEvaluatedEvent<S, E> {
+  readonly type: "@machine.guard";
+  readonly actorId: string;
+  readonly state: S;
+  readonly event: E;
+  readonly guardName: string | undefined;
+  readonly guardIndex: number;
+  readonly result: boolean;
+  readonly timestamp: number;
+}
+
+/**
+ * Event emitted when a transition occurs
+ */
+export interface TransitionEvent<S, E> {
+  readonly type: "@machine.transition";
+  readonly actorId: string;
+  readonly fromState: S;
+  readonly toState: S;
+  readonly event: E;
+  readonly timestamp: number;
+}
+
+/**
+ * Event emitted when an entry/exit/transition effect runs
+ */
+export interface EffectEvent<S> {
+  readonly type: "@machine.effect";
+  readonly actorId: string;
+  readonly effectType: "entry" | "exit" | "transition";
+  readonly state: S;
+  readonly timestamp: number;
+}
+
+/**
+ * Event emitted when an actor stops
+ */
+export interface StopEvent<S> {
+  readonly type: "@machine.stop";
+  readonly actorId: string;
+  readonly finalState: S;
+  readonly timestamp: number;
+}
+
+/**
+ * Union of all inspection events
+ */
+export type InspectionEvent<S, E> =
+  | SpawnEvent<S>
+  | EventReceivedEvent<S, E>
+  | GuardEvaluatedEvent<S, E>
+  | TransitionEvent<S, E>
+  | EffectEvent<S>
+  | StopEvent<S>;
+
+// ============================================================================
+// Inspector Service
+// ============================================================================
+
+/**
+ * Inspector interface for observing machine behavior
+ */
+export interface Inspector<S, E> {
+  readonly onInspect: (event: InspectionEvent<S, E>) => void;
+}
+
+/**
+ * Inspector service tag - optional service for machine introspection
+ * Uses `any` types to allow variance flexibility when providing the service
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const Inspector = Context.GenericTag<Inspector<any, any>>("@effect/machine/Inspector");
+
+/**
+ * Create an inspector from a callback function
+ */
+export const makeInspector = <S, E>(
+  onInspect: (event: InspectionEvent<S, E>) => void,
+): Inspector<S, E> => ({ onInspect });
+
+// ============================================================================
+// Built-in Inspectors
+// ============================================================================
+
+/**
+ * Console inspector that logs events in a readable format
+ */
+export const consoleInspector = <
+  S extends { readonly _tag: string },
+  E extends { readonly _tag: string },
+>(): Inspector<S, E> =>
+  makeInspector((event) => {
+    const prefix = `[${event.actorId}]`;
+    switch (event.type) {
+      case "@machine.spawn":
+        console.log(prefix, "spawned →", event.initialState._tag);
+        break;
+      case "@machine.event":
+        console.log(prefix, "received", event.event._tag, "in", event.state._tag);
+        break;
+      case "@machine.guard":
+        console.log(prefix, "guard", event.guardName ?? `#${event.guardIndex}`, "→", event.result);
+        break;
+      case "@machine.transition":
+        console.log(prefix, event.fromState._tag, "→", event.toState._tag);
+        break;
+      case "@machine.effect":
+        console.log(prefix, event.effectType, "effect in", event.state._tag);
+        break;
+      case "@machine.stop":
+        console.log(prefix, "stopped in", event.finalState._tag);
+        break;
+    }
+  });
+
+/**
+ * Collecting inspector that stores events in an array for testing
+ */
+export const collectingInspector = <S, E>(events: InspectionEvent<S, E>[]): Inspector<S, E> =>
+  makeInspector((event) => events.push(event));