effect-machine 0.3.1 → 0.3.2

package/dist/cluster/entity-machine.d.ts

@@ -0,0 +1,90 @@
+import { EffectsDef, GuardsDef } from "../slot.js";
+import { ProcessEventHooks } from "../internal/transition.js";
+import { Machine } from "../machine.js";
+import "../actor.js";
+import { Layer } from "effect";
+import { Entity } from "@effect/cluster";
+import { Rpc } from "@effect/rpc";
+
+//#region src/cluster/entity-machine.d.ts
+/**
+ * Options for EntityMachine.layer
+ */
+interface EntityMachineOptions<S, E> {
+  /**
+   * Initialize state from entity ID.
+   * Called once when entity is first activated.
+   *
+   * @example
+   * ```ts
+   * EntityMachine.layer(OrderEntity, orderMachine, {
+   *   initializeState: (entityId) => OrderState.Pending({ orderId: entityId }),
+   * })
+   * ```
+   */
+  readonly initializeState?: (entityId: string) => S;
+  /**
+   * Optional hooks for inspection/tracing.
+   * Called at specific points during event processing.
+   *
+   * @example
+   * ```ts
+   * EntityMachine.layer(OrderEntity, orderMachine, {
+   *   hooks: {
+   *     onTransition: (from, to, event) =>
+   *       Effect.log(`Transition: ${from._tag} -> ${to._tag}`),
+   *     onSpawnEffect: (state) =>
+   *       Effect.log(`Running spawn effects for ${state._tag}`),
+   *     onError: ({ phase, state }) =>
+   *       Effect.log(`Defect in ${phase} at ${state._tag}`),
+   *   },
+   * })
+   * ```
+   */
+  readonly hooks?: ProcessEventHooks<S, E>;
+}
+/**
+ * Create an Entity layer that wires a machine to handle RPC calls.
+ *
+ * The layer:
+ * - Maintains state via Ref per entity instance
+ * - Resolves transitions using the indexed lookup
+ * - Evaluates guards in registration order
+ * - Runs lifecycle effects (onEnter/spawn)
+ * - Processes internal events from spawn effects
+ *
+ * @example
+ * ```ts
+ * const OrderEntity = toEntity(orderMachine, {
+ *   type: "Order",
+ *   stateSchema: OrderState,
+ *   eventSchema: OrderEvent,
+ * })
+ *
+ * const OrderEntityLayer = EntityMachine.layer(OrderEntity, orderMachine, {
+ *   initializeState: (entityId) => OrderState.Pending({ orderId: entityId }),
+ * })
+ *
+ * // Use in cluster
+ * const program = Effect.gen(function* () {
+ *   const client = yield* ShardingClient.client(OrderEntity)
+ *   yield* client.Send("order-123", { event: OrderEvent.Ship({ trackingId: "abc" }) })
+ * })
+ * ```
+ */
+declare const EntityMachine: {
+  /**
+   * Create a layer that wires a machine to an Entity.
+   *
+   * @param entity - Entity created via toEntity()
+   * @param machine - Machine with all effects provided
+   * @param options - Optional configuration (state initializer, inspection hooks)
+   */
+  layer: <S extends {
+    readonly _tag: string;
+  }, E extends {
+    readonly _tag: string;
+  }, R, GD extends GuardsDef, EFD extends EffectsDef, EntityType extends string, Rpcs extends Rpc.Any>(entity: Entity.Entity<EntityType, Rpcs>, machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, options?: EntityMachineOptions<S, E>) => Layer.Layer<never, never, R>;
+};
+//#endregion
+export { EntityMachine, EntityMachineOptions };

package/dist/cluster/entity-machine.js

@@ -0,0 +1,74 @@
+import { processEventCore, runSpawnEffects } from "../internal/transition.js";
+import "../actor.js";
+import { Effect, Queue, Ref, Scope } from "effect";
+import { Entity } from "@effect/cluster";
+
+//#region src/cluster/entity-machine.ts
+/**
+* EntityMachine adapter - wires a machine to a cluster Entity layer.
+*
+* @module
+*/
+/**
+* Process a single event through the machine using shared core.
+* Returns the new state after processing.
+*/
+const processEvent = Effect.fn("effect-machine.cluster.processEvent")(function* (machine, stateRef, event, self, stateScopeRef, hooks) {
+	const result = yield* processEventCore(machine, yield* Ref.get(stateRef), event, self, stateScopeRef, hooks);
+	if (result.transitioned) yield* Ref.set(stateRef, result.newState);
+	return result.newState;
+});
+/**
+* Create an Entity layer that wires a machine to handle RPC calls.
+*
+* The layer:
+* - Maintains state via Ref per entity instance
+* - Resolves transitions using the indexed lookup
+* - Evaluates guards in registration order
+* - Runs lifecycle effects (onEnter/spawn)
+* - Processes internal events from spawn effects
+*
+* @example
+* ```ts
+* const OrderEntity = toEntity(orderMachine, {
+*   type: "Order",
+*   stateSchema: OrderState,
+*   eventSchema: OrderEvent,
+* })
+*
+* const OrderEntityLayer = EntityMachine.layer(OrderEntity, orderMachine, {
+*   initializeState: (entityId) => OrderState.Pending({ orderId: entityId }),
+* })
+*
+* // Use in cluster
+* const program = Effect.gen(function* () {
+*   const client = yield* ShardingClient.client(OrderEntity)
+*   yield* client.Send("order-123", { event: OrderEvent.Ship({ trackingId: "abc" }) })
+* })
+* ```
+*/
+const EntityMachine = { layer: (entity, machine, options) => {
+	const layer = Effect.fn("effect-machine.cluster.layer")(function* () {
+		const entityId = yield* Effect.serviceOption(Entity.CurrentAddress).pipe(Effect.map((opt) => opt._tag === "Some" ? opt.value.entityId : ""));
+		const initialState = options?.initializeState !== void 0 ? options.initializeState(entityId) : machine.initial;
+		const internalQueue = yield* Queue.unbounded();
+		const self = { send: Effect.fn("effect-machine.cluster.self.send")(function* (event) {
+			yield* Queue.offer(internalQueue, event);
+		}) };
+		const stateRef = yield* Ref.make(initialState);
+		const stateScopeRef = { current: yield* Scope.make() };
+		yield* runSpawnEffects(machine, initialState, { _tag: "$init" }, self, stateScopeRef.current, options?.hooks?.onError);
+		const runInternalEvent = Effect.fn("effect-machine.cluster.internalEvent")(function* () {
+			yield* processEvent(machine, stateRef, yield* Queue.take(internalQueue), self, stateScopeRef, options?.hooks);
+		});
+		yield* Effect.forkScoped(Effect.forever(runInternalEvent()));
+		return entity.of({
+			Send: (envelope) => processEvent(machine, stateRef, envelope.payload.event, self, stateScopeRef, options?.hooks),
+			GetState: () => Ref.get(stateRef)
+		});
+	});
+	return entity.toLayer(layer());
+} };
+
+//#endregion
+export { EntityMachine };

package/dist/cluster/index.d.ts

@@ -0,0 +1,3 @@
+import { EntityMachine, EntityMachineOptions } from "./entity-machine.js";
+import { ToEntityOptions, toEntity } from "./to-entity.js";
+export { EntityMachine, type EntityMachineOptions, type ToEntityOptions, toEntity };

package/dist/cluster/index.js

@@ -0,0 +1,4 @@
+import { EntityMachine } from "./entity-machine.js";
+import { toEntity } from "./to-entity.js";
+
+export { EntityMachine, toEntity };

package/dist/cluster/to-entity.d.ts

@@ -0,0 +1,64 @@
+import { Machine } from "../machine.js";
+import { Schema } from "effect";
+import { Entity } from "@effect/cluster";
+import { Rpc } from "@effect/rpc";
+
+//#region src/cluster/to-entity.d.ts
+/**
+ * Options for toEntity.
+ */
+interface ToEntityOptions {
+  /**
+   * Entity type name (e.g., "Order", "User")
+   */
+  readonly type: string;
+}
+/**
+ * Default RPC protocol for entity machines.
+ *
+ * - `Send` - Send event to machine, returns new state
+ * - `GetState` - Get current state
+ */
+type EntityRpcs<StateSchema extends Schema.Schema.Any, EventSchema extends Schema.Schema.Any> = readonly [Rpc.Rpc<"Send", Schema.Struct<{
+  readonly event: EventSchema;
+}>, StateSchema, typeof Schema.Never, never>, Rpc.Rpc<"GetState", typeof Schema.Void, StateSchema, typeof Schema.Never, never>];
+/**
+ * Generate an Entity definition from a machine.
+ *
+ * Creates an Entity with a standard RPC protocol:
+ * - `Send(event)` - Process event through machine, returns new state
+ * - `GetState()` - Returns current state
+ *
+ * Schemas are read from the machine - must use `Machine.make({ state, event, initial })`.
+ *
+ * @example
+ * ```ts
+ * const OrderState = State({
+ *   Pending: { orderId: Schema.String },
+ *   Shipped: { trackingId: Schema.String },
+ * })
+ *
+ * const OrderEvent = Event({
+ *   Ship: { trackingId: Schema.String },
+ * })
+ *
+ * const orderMachine = Machine.make({
+ *   state: OrderState,
+ *   event: OrderEvent,
+ *   initial: OrderState.Pending({ orderId: "" }),
+ * }).pipe(
+ *   Machine.on(OrderState.Pending, OrderEvent.Ship, ...),
+ * )
+ *
+ * const OrderEntity = toEntity(orderMachine, { type: "Order" })
+ * ```
+ */
+declare const toEntity: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R>(machine: Machine<S, E, R, any, any, any, any>, options: ToEntityOptions) => Entity.Entity<string, Rpc.Rpc<"Send", Schema.Struct<{
+  event: Schema.Schema<E, unknown, never>;
+}>, Schema.Schema<S, unknown, never>, typeof Schema.Never, never> | Rpc.Rpc<"GetState", typeof Schema.Void, Schema.Schema<S, unknown, never>, typeof Schema.Never, never>>;
+//#endregion
+export { EntityRpcs, ToEntityOptions, toEntity };

package/dist/cluster/to-entity.js

@@ -0,0 +1,53 @@
+import { MissingSchemaError } from "../errors.js";
+import { Entity } from "@effect/cluster";
+import { Rpc } from "@effect/rpc";
+
+//#region src/cluster/to-entity.ts
+/**
+* Generate Entity definition from a machine.
+*
+* @module
+*/
+/**
+* Generate an Entity definition from a machine.
+*
+* Creates an Entity with a standard RPC protocol:
+* - `Send(event)` - Process event through machine, returns new state
+* - `GetState()` - Returns current state
+*
+* Schemas are read from the machine - must use `Machine.make({ state, event, initial })`.
+*
+* @example
+* ```ts
+* const OrderState = State({
+*   Pending: { orderId: Schema.String },
+*   Shipped: { trackingId: Schema.String },
+* })
+*
+* const OrderEvent = Event({
+*   Ship: { trackingId: Schema.String },
+* })
+*
+* const orderMachine = Machine.make({
+*   state: OrderState,
+*   event: OrderEvent,
+*   initial: OrderState.Pending({ orderId: "" }),
+* }).pipe(
+*   Machine.on(OrderState.Pending, OrderEvent.Ship, ...),
+* )
+*
+* const OrderEntity = toEntity(orderMachine, { type: "Order" })
+* ```
+*/
+const toEntity = (machine, options) => {
+	const stateSchema = machine.stateSchema;
+	const eventSchema = machine.eventSchema;
+	if (stateSchema === void 0 || eventSchema === void 0) throw new MissingSchemaError({ operation: "toEntity" });
+	return Entity.make(options.type, [Rpc.make("Send", {
+		payload: { event: eventSchema },
+		success: stateSchema
+	}), Rpc.make("GetState", { success: stateSchema })]);
+};
+
+//#endregion
+export { toEntity };

package/dist/errors.d.ts

@@ -0,0 +1,61 @@
+import { Schema } from "effect";
+
+//#region src/errors.d.ts
+declare const DuplicateActorError_base: Schema.TaggedErrorClass<DuplicateActorError, "DuplicateActorError", {
+  readonly _tag: Schema.tag<"DuplicateActorError">;
+} & {
+  actorId: typeof Schema.String;
+}>;
+/** Attempted to spawn/restore actor with ID already in use */
+declare class DuplicateActorError extends DuplicateActorError_base {}
+declare const UnprovidedSlotsError_base: Schema.TaggedErrorClass<UnprovidedSlotsError, "UnprovidedSlotsError", {
+  readonly _tag: Schema.tag<"UnprovidedSlotsError">;
+} & {
+  slots: Schema.Array$<typeof Schema.String>;
+}>;
+/** Machine has unprovided effect slots */
+declare class UnprovidedSlotsError extends UnprovidedSlotsError_base {}
+declare const MissingSchemaError_base: Schema.TaggedErrorClass<MissingSchemaError, "MissingSchemaError", {
+  readonly _tag: Schema.tag<"MissingSchemaError">;
+} & {
+  operation: typeof Schema.String;
+}>;
+/** Operation requires schemas attached to machine */
+declare class MissingSchemaError extends MissingSchemaError_base {}
+declare const InvalidSchemaError_base: Schema.TaggedErrorClass<InvalidSchemaError, "InvalidSchemaError", {
+  readonly _tag: Schema.tag<"InvalidSchemaError">;
+}>;
+/** State/Event schema has no variants */
+declare class InvalidSchemaError extends InvalidSchemaError_base {}
+declare const MissingMatchHandlerError_base: Schema.TaggedErrorClass<MissingMatchHandlerError, "MissingMatchHandlerError", {
+  readonly _tag: Schema.tag<"MissingMatchHandlerError">;
+} & {
+  tag: typeof Schema.String;
+}>;
+/** $match called with missing handler for tag */
+declare class MissingMatchHandlerError extends MissingMatchHandlerError_base {}
+declare const SlotProvisionError_base: Schema.TaggedErrorClass<SlotProvisionError, "SlotProvisionError", {
+  readonly _tag: Schema.tag<"SlotProvisionError">;
+} & {
+  slotName: typeof Schema.String;
+  slotType: Schema.Literal<["guard", "effect"]>;
+}>;
+/** Slot handler not found at runtime (internal error) */
+declare class SlotProvisionError extends SlotProvisionError_base {}
+declare const ProvisionValidationError_base: Schema.TaggedErrorClass<ProvisionValidationError, "ProvisionValidationError", {
+  readonly _tag: Schema.tag<"ProvisionValidationError">;
+} & {
+  missing: Schema.Array$<typeof Schema.String>;
+  extra: Schema.Array$<typeof Schema.String>;
+}>;
+/** Machine.build() validation failed - missing or extra handlers */
+declare class ProvisionValidationError extends ProvisionValidationError_base {}
+declare const AssertionError_base: Schema.TaggedErrorClass<AssertionError, "AssertionError", {
+  readonly _tag: Schema.tag<"AssertionError">;
+} & {
+  message: typeof Schema.String;
+}>;
+/** Assertion failed in testing utilities */
+declare class AssertionError extends AssertionError_base {}
+//#endregion
+export { AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError };

package/dist/errors.js

@@ -0,0 +1,38 @@
+import { Schema } from "effect";
+
+//#region src/errors.ts
+/**
+* Typed error classes for effect-machine.
+*
+* All errors extend Schema.TaggedError for:
+* - Type-safe catching via Effect.catchTag
+* - Serialization support
+* - Composable error handling
+*
+* @module
+*/
+/** Attempted to spawn/restore actor with ID already in use */
+var DuplicateActorError = class extends Schema.TaggedError()("DuplicateActorError", { actorId: Schema.String }) {};
+/** Machine has unprovided effect slots */
+var UnprovidedSlotsError = class extends Schema.TaggedError()("UnprovidedSlotsError", { slots: Schema.Array(Schema.String) }) {};
+/** Operation requires schemas attached to machine */
+var MissingSchemaError = class extends Schema.TaggedError()("MissingSchemaError", { operation: Schema.String }) {};
+/** State/Event schema has no variants */
+var InvalidSchemaError = class extends Schema.TaggedError()("InvalidSchemaError", {}) {};
+/** $match called with missing handler for tag */
+var MissingMatchHandlerError = class extends Schema.TaggedError()("MissingMatchHandlerError", { tag: Schema.String }) {};
+/** Slot handler not found at runtime (internal error) */
+var SlotProvisionError = class extends Schema.TaggedError()("SlotProvisionError", {
+	slotName: Schema.String,
+	slotType: Schema.Literal("guard", "effect")
+}) {};
+/** Machine.build() validation failed - missing or extra handlers */
+var ProvisionValidationError = class extends Schema.TaggedError()("ProvisionValidationError", {
+	missing: Schema.Array(Schema.String),
+	extra: Schema.Array(Schema.String)
+}) {};
+/** Assertion failed in testing utilities */
+var AssertionError = class extends Schema.TaggedError()("AssertionError", { message: Schema.String }) {};
+
+//#endregion
+export { AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError };

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { EffectHandlers, EffectSlot, EffectSlots, EffectsDef, EffectsSchema, GuardHandlers, GuardSlot, GuardSlots, GuardsDef, GuardsSchema, MachineContext, Slot } from "./slot.js";
+import { Event, MachineEventSchema, MachineStateSchema, State } from "./schema.js";
+import { PersistenceConfig, PersistentMachine, isPersistentMachine } from "./persistence/persistent-machine.js";
+import { PersistentActorRef, createPersistentActor, restorePersistentActor } from "./persistence/persistent-actor.js";
+import { AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.js";
+import { ActorMetadata, PersistedEvent, PersistenceAdapter, PersistenceAdapterTag, PersistenceError, RestoreFailure, RestoreResult, Snapshot, VersionConflictError } from "./persistence/adapter.js";
+import { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter } from "./persistence/adapters/in-memory.js";
+import "./persistence/index.js";
+import { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, ProvideHandlers, SpawnEffect, StateHandlerContext, Transition, machine_d_exports } from "./machine.js";
+import { ActorRef, ActorSystem, Default } from "./actor.js";
+import { SimulationResult, TestHarness, TestHarnessOptions, assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
+import { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, SpawnEvent, StopEvent, TransitionEvent, collectingInspector, consoleInspector, makeInspector } from "./inspection.js";
+export { type ActorMetadata, type ActorRef, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type BuiltMachine, DuplicateActorError, type EffectEvent, type EffectSlots, type EffectsDef, type EffectsSchema, type ErrorEvent, Event, type EventReceivedEvent, type GuardHandlers, type GuardSlot, type GuardSlots, type GuardsDef, type GuardsSchema, type HandlerContext, InMemoryPersistenceAdapter, type InspectionEvent, type Inspector, Inspector as InspectorService, InvalidSchemaError, machine_d_exports as Machine, type MachineContext, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, MissingSchemaError, type PersistOptions, type PersistedEvent, type PersistenceAdapter, PersistenceAdapterTag, type PersistenceConfig, PersistenceError, type PersistentActorRef, type PersistentMachine, type ProvideHandlers, ProvisionValidationError, type RestoreFailure, type RestoreResult, type SimulationResult, Slot, type EffectHandlers as SlotEffectHandlers, type EffectSlot as SlotEffectSlot, SlotProvisionError, type Snapshot, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, type TestHarness, type TestHarnessOptions, type Transition, type TransitionEvent, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, restorePersistentActor, simulate };

package/dist/index.js

@@ -0,0 +1,14 @@
+import { Inspector, collectingInspector, consoleInspector, makeInspector } from "./inspection.js";
+import { AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.js";
+import { isPersistentMachine } from "./persistence/persistent-machine.js";
+import { Slot } from "./slot.js";
+import { machine_exports } from "./machine.js";
+import { PersistenceAdapterTag, PersistenceError, VersionConflictError } from "./persistence/adapter.js";
+import { createPersistentActor, restorePersistentActor } from "./persistence/persistent-actor.js";
+import { ActorSystem, Default } from "./actor.js";
+import { Event, State } from "./schema.js";
+import { assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
+import { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter } from "./persistence/adapters/in-memory.js";
+import "./persistence/index.js";
+
+export { Default as ActorSystemDefault, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, InMemoryPersistenceAdapter, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, MissingSchemaError, PersistenceAdapterTag, PersistenceError, ProvisionValidationError, Slot, SlotProvisionError, State, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, restorePersistentActor, simulate };

package/dist/inspection.d.ts

@@ -0,0 +1,125 @@
+import { Context, Schema } from "effect";
+
+//#region src/inspection.d.ts
+/**
+ * Resolve a type param: if it's a Schema, extract `.Type`; otherwise use as-is.
+ */
+type ResolveType<T> = T extends Schema.Schema<infer A, infer _I, infer _R> ? A : T;
+/**
+ * Event emitted when an actor is spawned
+ */
+interface SpawnEvent<S> {
+  readonly type: "@machine.spawn";
+  readonly actorId: string;
+  readonly initialState: S;
+  readonly timestamp: number;
+}
+/**
+ * Event emitted when an actor receives an event
+ */
+interface EventReceivedEvent<S, E> {
+  readonly type: "@machine.event";
+  readonly actorId: string;
+  readonly state: S;
+  readonly event: E;
+  readonly timestamp: number;
+}
+/**
+ * Event emitted when a transition occurs
+ */
+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 a spawn effect runs
+ */
+interface EffectEvent<S> {
+  readonly type: "@machine.effect";
+  readonly actorId: string;
+  readonly effectType: "spawn";
+  readonly state: S;
+  readonly timestamp: number;
+}
+/**
+ * Event emitted when a transition handler or spawn effect fails with a defect
+ */
+interface ErrorEvent<S, E> {
+  readonly type: "@machine.error";
+  readonly actorId: string;
+  readonly phase: "transition" | "spawn";
+  readonly state: S;
+  readonly event: E;
+  readonly error: string;
+  readonly timestamp: number;
+}
+/**
+ * Event emitted when an actor stops
+ */
+interface StopEvent<S> {
+  readonly type: "@machine.stop";
+  readonly actorId: string;
+  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> | ErrorEvent<S, E> | StopEvent<S>;
+/**
+ * Convenience alias for untyped inspection events.
+ * Useful for general-purpose inspectors that don't need specific state/event types.
+ * State and event fields are typed as `{ readonly _tag: string }` so discriminated
+ * access to `_tag` works without casting.
+ */
+type AnyInspectionEvent = InspectionEvent<{
+  readonly _tag: string;
+}, {
+  readonly _tag: string;
+}>;
+/**
+ * Inspector interface for observing machine behavior
+ */
+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
+ */
+declare const Inspector: Context.Tag<Inspector<any, any>, Inspector<any, any>>;
+/**
+ * Create an inspector from a callback function.
+ *
+ * Type params accept either raw tagged types or Schema constructors:
+ * - `makeInspector(cb)` — defaults to `AnyInspectionEvent`
+ * - `makeInspector<MyState, MyEvent>(cb)` — explicit tagged types
+ * - `makeInspector<typeof MyState, typeof MyEvent>(cb)` — schema constructors (auto-extracts `.Type`)
+ */
+declare const makeInspector: <S = {
+  readonly _tag: string;
+}, E = {
+  readonly _tag: string;
+}>(onInspect: (event: InspectionEvent<ResolveType<S>, ResolveType<E>>) => void) => Inspector<ResolveType<S>, ResolveType<E>>;
+/**
+ * Console inspector that logs events in a readable format
+ */
+declare const consoleInspector: () => Inspector<{
+  readonly _tag: string;
+}, {
+  readonly _tag: string;
+}>;
+/**
+ * Collecting inspector that stores events in an array for testing
+ */
+declare const collectingInspector: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}>(events: InspectionEvent<S, E>[]) => Inspector<S, E>;
+//#endregion
+export { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, SpawnEvent, StopEvent, TransitionEvent, collectingInspector, consoleInspector, makeInspector };

package/dist/inspection.js

@@ -0,0 +1,50 @@
+import { Context } from "effect";
+
+//#region src/inspection.ts
+/**
+* Inspector service tag - optional service for machine introspection
+* Uses `any` types to allow variance flexibility when providing the service
+*/
+const Inspector = Context.GenericTag("@effect/machine/Inspector");
+/**
+* Create an inspector from a callback function.
+*
+* Type params accept either raw tagged types or Schema constructors:
+* - `makeInspector(cb)` — defaults to `AnyInspectionEvent`
+* - `makeInspector<MyState, MyEvent>(cb)` — explicit tagged types
+* - `makeInspector<typeof MyState, typeof MyEvent>(cb)` — schema constructors (auto-extracts `.Type`)
+*/
+const makeInspector = (onInspect) => ({ onInspect });
+/**
+* Console inspector that logs events in a readable format
+*/
+const consoleInspector = () => 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.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.error":
+			console.log(prefix, "error in", event.phase, event.state._tag, "-", event.error);
+			break;
+		case "@machine.stop":
+			console.log(prefix, "stopped in", event.finalState._tag);
+			break;
+	}
+});
+/**
+* Collecting inspector that stores events in an array for testing
+*/
+const collectingInspector = (events) => ({ onInspect: (event) => events.push(event) });
+
+//#endregion
+export { Inspector, collectingInspector, consoleInspector, makeInspector };

package/dist/internal/brands.d.ts

@@ -0,0 +1,40 @@
+import { Brand } from "effect";
+
+//#region src/internal/brands.d.ts
+declare const StateTypeId: unique symbol;
+declare const EventTypeId: unique symbol;
+type StateTypeId = typeof StateTypeId;
+type EventTypeId = typeof EventTypeId;
+interface StateBrand extends Brand.Brand<StateTypeId> {}
+interface EventBrand extends Brand.Brand<EventTypeId> {}
+type BrandedState = {
+  readonly _tag: string;
+} & StateBrand;
+type BrandedEvent = {
+  readonly _tag: string;
+} & EventBrand;
+declare const SchemaIdTypeId: unique symbol;
+type SchemaIdTypeId = typeof SchemaIdTypeId;
+/**
+ * Brand that captures the schema definition type D.
+ * Two schemas with identical definition shapes will have compatible brands.
+ * Different definitions = incompatible brands.
+ */
+interface SchemaIdBrand<_D extends Record<string, unknown>> extends Brand.Brand<SchemaIdTypeId> {}
+/**
+ * Full state brand: combines base state brand with schema-specific brand
+ */
+type FullStateBrand<D extends Record<string, unknown>> = StateBrand & SchemaIdBrand<D>;
+/**
+ * Full event brand: combines base event brand with schema-specific brand
+ */
+type FullEventBrand<D extends Record<string, unknown>> = EventBrand & SchemaIdBrand<D>;
+/**
+ * Value or constructor for a tagged type.
+ * Accepts both plain values (empty structs) and constructor functions (non-empty structs).
+ */
+type TaggedOrConstructor<T extends {
+  readonly _tag: string;
+}> = T | ((...args: never[]) => T);
+//#endregion
+export { BrandedEvent, BrandedState, EventBrand, EventTypeId, FullEventBrand, FullStateBrand, SchemaIdBrand, StateBrand, StateTypeId, TaggedOrConstructor };

package/dist/internal/inspection.d.ts

@@ -0,0 +1,11 @@
+import { InspectionEvent, Inspector } from "../inspection.js";
+import { Effect } from "effect";
+
+//#region src/internal/inspection.d.ts
+/**
+ * Emit an inspection event with timestamp from Clock.
+ * @internal
+ */
+declare const emitWithTimestamp: <S, E>(inspector: Inspector<S, E> | undefined, makeEvent: (timestamp: number) => InspectionEvent<S, E>) => Effect.Effect<void, never, never>;
+//#endregion
+export { emitWithTimestamp };