effect-machine 0.12.0 → 0.13.0

package/v3/dist/machine.d.ts

@@ -1,15 +1,16 @@
-import { EffectHandlers, EffectSlots, EffectsDef, EffectsSchema, GuardHandlers, GuardSlots, GuardsDef, GuardsSchema, MachineContext } from "./slot.js";
+import { Supervision } from "./supervision.js";
 import { ReplyResult, TransitionResult } from "./internal/utils.js";
 import { BrandedEvent, BrandedState, ExtractReply, TaggedOrConstructor } from "./internal/brands.js";
 import { MachineEventSchema, MachineStateSchema, VariantsUnion } from "./schema.js";
 import { DuplicateActorError } from "./errors.js";
+import { EffectHandlers, EffectSlots, EffectsDef, EffectsSchema, GuardHandlers, GuardSlots, GuardsDef, GuardsSchema, MachineContext } from "./slot.js";
 import { findTransitions } from "./internal/transition.js";
 import { ActorRef, ActorSystem } from "./actor.js";
 import { Cause, Context, Duration, Effect, Schema, Scope } from "effect";
 
 //#region src/machine.d.ts
 declare namespace machine_d_exports {
-  export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, ReplyResult, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, make, replay, reply, spawn };
+  export { BackgroundEffect, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, ReplyResult, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, make, materializeMachine, replay, reply, spawn };
 }
 /**
  * Self reference for sending events back to the machine
@@ -22,7 +23,7 @@ interface MachineRef<Event> {
     readonly _tag: string;
   }, E2 extends {
     readonly _tag: string;
-  }, R2>(id: string, machine: BuiltMachine<S2, E2, R2>) => Effect.Effect<ActorRef<S2, E2>, DuplicateActorError, R2>;
+  }, R2>(id: string, machine: Machine<S2, E2, R2, any, any, any, any>) => Effect.Effect<ActorRef<S2, E2>, DuplicateActorError, R2>;
 }
 /**
  * Handler context passed to transition handlers
@@ -93,9 +94,6 @@ interface TimeoutConfig<State, Event> {
   /** Event to send when the timer fires. Static or derived from current state. */
   readonly event: Event | ((state: State) => Event);
 }
-type IsAny<T> = 0 extends 1 & T ? true : false;
-type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) : false;
-type NormalizeR<T> = IsAny<T> extends true ? T : IsUnknown<T> extends true ? never : T;
 interface MakeConfig<SD extends Record<string, Schema.Struct.Fields>, ED extends Record<string, Schema.Struct.Fields>, S extends BrandedState, E extends BrandedEvent, GD extends GuardsDef, EFD extends EffectsDef> {
   readonly state: MachineStateSchema<SD> & {
     Type: S;
@@ -115,22 +113,14 @@ type HasEffectKeys<EFD extends EffectsDef> = [keyof EFD] extends [never] ? false
 type SlotContext<State, Event> = MachineContext<State, Event, MachineRef<Event>>;
 /** Combined handlers for build() - guards and effects only */
 type ProvideHandlers<State, Event, GD extends GuardsDef, EFD extends EffectsDef, R> = (HasGuardKeys<GD> extends true ? GuardHandlers<GD, SlotContext<State, Event>, R> : object) & (HasEffectKeys<EFD> extends true ? EffectHandlers<EFD, SlotContext<State, Event>, R> : object);
-/** Whether the machine has any guard or effect slots */
-type HasSlots<GD extends GuardsDef, EFD extends EffectsDef> = HasGuardKeys<GD> extends true ? true : HasEffectKeys<EFD>;
 /**
- * A finalized machine ready for spawning.
+ * Bind slot handlers to a machine, returning a fresh copy with handlers installed.
+ * If no handlers provided and machine has no slots, returns the machine as-is.
+ * Validates that all required slots are provided and no extra slots are given.
  *
- * Created by calling `.build()` on a `Machine`. This is the only type
- * accepted by `Machine.spawn` and `ActorSystem.spawn` (regular overload).
- * Testing utilities (`simulate`, `createTestHarness`, etc.) still accept `Machine`.
+ * @internal — used by spawn, replay, simulate, test harness, entity-machine
  */
-declare class BuiltMachine<State, Event, R = never> {
-  /** @internal */
-  readonly _inner: Machine<State, Event, R, any, any, any, any>;
-  /** @internal */
-  constructor(machine: Machine<State, Event, R, any, any, any, any>);
-  get initial(): State;
-}
+declare const materializeMachine: <S, E, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, any, any, GD, EFD>, handlers?: Record<string, any>) => Machine<S, E, never, any, any, GD, EFD>;
 /**
  * Machine definition with fluent builder API.
  *
@@ -306,13 +296,6 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
    */
   postpone<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, events: TaggedOrConstructor<VariantsUnion<_ED> & BrandedEvent> | ReadonlyArray<TaggedOrConstructor<VariantsUnion<_ED> & BrandedEvent>>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   final<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
-  /**
-   * Finalize the machine. Returns a `BuiltMachine` — the only type accepted by `Machine.spawn`.
-   *
-   * - Machines with slots: pass implementations as the first argument.
-   * - Machines without slots: call with no arguments.
-   */
-  build<R2 = never>(...args: HasSlots<GD, EFD> extends true ? [handlers: ProvideHandlers<State, Event, GD, EFD, R2>] : [handlers?: ProvideHandlers<State, Event, GD, EFD, R2>]): BuiltMachine<State, Event, R | NormalizeR<R2>>;
   static make<SD extends Record<string, Schema.Struct.Fields>, ED extends Record<string, Schema.Struct.Fields>, S extends BrandedState, E extends BrandedEvent, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(config: MakeConfig<SD, ED, S, E, GD, EFD>): Machine<S, E, never, SD, ED, GD, EFD>;
 }
 declare class TransitionScope<State, Event, R, _SD extends Record<string, Schema.Struct.Fields>, _ED extends Record<string, Schema.Struct.Fields>, GD extends GuardsDef, EFD extends EffectsDef, SelectedState extends VariantsUnion<_SD> & BrandedState> {
@@ -323,34 +306,33 @@ declare class TransitionScope<State, Event, R, _SD extends Record<string, Schema
   reenter<NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(event: TaggedOrConstructor<NE>, handler: TransitionHandler<SelectedState, NE, RS, GD, EFD, never, ExtractReply<NE>>): TransitionScope<State, Event, R, _SD, _ED, GD, EFD, SelectedState>;
 }
 declare const make: typeof Machine.make;
+type AnyMachine<S, E, R> = Machine<S, E, R, any, any, any, any>;
 /**
- * Spawn an actor from a built machine.
+ * Spawn an actor from a machine.
  *
  * Options:
  * - `id` — custom actor ID (default: random)
  * - `hydrate` — restore from a previously-saved state snapshot.
- *   The actor starts in the hydrated state and re-runs spawn effects
- *   for that state (timers, scoped resources, etc.). Transition history
- *   is not replayed — only the current state's entry effects run.
- *
- * Persistence is composed in userland by observing `actor.changes`
- * and saving snapshots to your own storage.
+ * - `slots` — slot handler implementations for slotful machines.
  */
 declare const spawn: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R>(machine: BuiltMachine<S, E, R>, idOrOptions?: string | {
+}, R>(machine: AnyMachine<S, E, R>, options?: string | {
   id?: string;
   hydrate?: S;
+  slots?: Record<string, any>;
+  supervision?: Supervision.Policy;
 }) => Effect.Effect<ActorRef<S, E>, never, R>;
 declare const replay: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R>(machine: BuiltMachine<S, E, R>, events: ReadonlyArray<E>, options?: {
+}, R>(machine: AnyMachine<S, E, R>, events: ReadonlyArray<E>, options?: {
   from?: S;
+  slots?: Record<string, any>;
 }) => Effect.Effect<S, never, R>;
 declare const reply: <State, Reply>(state: State, reply: Reply) => ReplyResult<State, Reply>;
 //#endregion
-export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, type ReplyResult, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, machine_d_exports, make, replay, reply, spawn };
+export { BackgroundEffect, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, type ReplyResult, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, machine_d_exports, make, materializeMachine, replay, reply, spawn };

package/v3/dist/machine.js

@@ -1,18 +1,18 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
-import { Inspector } from "./inspection.js";
 import { getTag, makeReply, stubSystem } from "./internal/utils.js";
 import { ProvisionValidationError, SlotProvisionError } from "./errors.js";
+import { findTransitions, invalidateIndex, resolveTransition, runTransitionHandler, shouldPostpone } from "./internal/transition.js";
 import { emitWithTimestamp } from "./internal/inspection.js";
+import { Inspector } from "./inspection.js";
 import { MachineContextTag } from "./slot.js";
-import { findTransitions, invalidateIndex, resolveTransition, runTransitionHandler, shouldPostpone } from "./internal/transition.js";
 import { createActor } from "./actor.js";
 import { Cause, Effect, Exit, Option, Scope } from "effect";
 //#region src/machine.ts
 var machine_exports = /* @__PURE__ */ __exportAll({
-	BuiltMachine: () => BuiltMachine,
 	Machine: () => Machine,
 	findTransitions: () => findTransitions,
 	make: () => make,
+	materializeMachine: () => materializeMachine,
 	replay: () => replay,
 	reply: () => reply,
 	spawn: () => spawn
@@ -27,22 +27,49 @@ const emitTaskInspection = (input) => Effect.flatMap(Effect.serviceOptional(Insp
 	timestamp
 })));
 /**
-* A finalized machine ready for spawning.
+* Bind slot handlers to a machine, returning a fresh copy with handlers installed.
+* If no handlers provided and machine has no slots, returns the machine as-is.
+* Validates that all required slots are provided and no extra slots are given.
 *
-* Created by calling `.build()` on a `Machine`. This is the only type
-* accepted by `Machine.spawn` and `ActorSystem.spawn` (regular overload).
-* Testing utilities (`simulate`, `createTestHarness`, etc.) still accept `Machine`.
+* @internal — used by spawn, replay, simulate, test harness, entity-machine
 */
-var BuiltMachine = class {
-	/** @internal */
-	_inner;
-	/** @internal */
-	constructor(machine) {
-		this._inner = machine;
-	}
-	get initial() {
-		return this._inner.initial;
+const materializeMachine = (machine, handlers) => {
+	if (handlers === void 0) {
+		const hasGuards = machine._guardsSchema !== void 0 && Object.keys(machine._guardsSchema.definitions).length > 0;
+		const hasEffects = machine._effectsSchema !== void 0 && Object.keys(machine._effectsSchema.definitions).length > 0;
+		if (hasGuards || hasEffects) {
+			const missing = [];
+			if (machine._guardsSchema !== void 0) missing.push(...Object.keys(machine._guardsSchema.definitions));
+			if (machine._effectsSchema !== void 0) missing.push(...Object.keys(machine._effectsSchema.definitions));
+			throw new ProvisionValidationError({
+				missing,
+				extra: []
+			});
+		}
+		return machine;
 	}
+	const requiredSlots = /* @__PURE__ */ new Set();
+	if (machine._guardsSchema !== void 0) for (const name of Object.keys(machine._guardsSchema.definitions)) requiredSlots.add(name);
+	if (machine._effectsSchema !== void 0) for (const name of Object.keys(machine._effectsSchema.definitions)) requiredSlots.add(name);
+	const providedSlots = new Set(Object.keys(handlers));
+	const missing = [];
+	const extra = [];
+	for (const name of requiredSlots) if (!providedSlots.has(name)) missing.push(name);
+	for (const name of providedSlots) if (!requiredSlots.has(name)) extra.push(name);
+	if (missing.length > 0 || extra.length > 0) throw new ProvisionValidationError({
+		missing,
+		extra
+	});
+	const result = new Machine(machine.initial, machine.stateSchema, machine.eventSchema, machine._guardsSchema, machine._effectsSchema);
+	result._transitions = [...machine._transitions];
+	result._finalStates = new Set(machine._finalStates);
+	result._spawnEffects = [...machine._spawnEffects];
+	result._backgroundEffects = [...machine._backgroundEffects];
+	result._postponeRules = [...machine._postponeRules];
+	result._replySchemas = machine._replySchemas;
+	if (machine._guardsSchema !== void 0) for (const name of Object.keys(machine._guardsSchema.definitions)) result._guardHandlers.set(name, handlers[name]);
+	if (machine._effectsSchema !== void 0) for (const name of Object.keys(machine._effectsSchema.definitions)) result._effectHandlers.set(name, handlers[name]);
+	return result;
 };
 /**
 * Machine definition with fluent builder API.
@@ -350,41 +377,6 @@ var Machine = class Machine {
 		this._finalStates.add(stateTag);
 		return this;
 	}
-	/**
-	* Finalize the machine. Returns a `BuiltMachine` — the only type accepted by `Machine.spawn`.
-	*
-	* - Machines with slots: pass implementations as the first argument.
-	* - Machines without slots: call with no arguments.
-	*/
-	build(...args) {
-		const handlers = args[0];
-		if (handlers !== void 0) {
-			const requiredSlots = /* @__PURE__ */ new Set();
-			if (this._guardsSchema !== void 0) for (const name of Object.keys(this._guardsSchema.definitions)) requiredSlots.add(name);
-			if (this._effectsSchema !== void 0) for (const name of Object.keys(this._effectsSchema.definitions)) requiredSlots.add(name);
-			const providedSlots = new Set(Object.keys(handlers));
-			const missing = [];
-			const extra = [];
-			for (const name of requiredSlots) if (!providedSlots.has(name)) missing.push(name);
-			for (const name of providedSlots) if (!requiredSlots.has(name)) extra.push(name);
-			if (missing.length > 0 || extra.length > 0) throw new ProvisionValidationError({
-				missing,
-				extra
-			});
-			const result = new Machine(this.initial, this.stateSchema, this.eventSchema, this._guardsSchema, this._effectsSchema);
-			result._transitions = [...this._transitions];
-			result._finalStates = new Set(this._finalStates);
-			result._spawnEffects = [...this._spawnEffects];
-			result._backgroundEffects = [...this._backgroundEffects];
-			result._postponeRules = [...this._postponeRules];
-			result._replySchemas = this._replySchemas;
-			const anyHandlers = handlers;
-			if (this._guardsSchema !== void 0) for (const name of Object.keys(this._guardsSchema.definitions)) result._guardHandlers.set(name, anyHandlers[name]);
-			if (this._effectsSchema !== void 0) for (const name of Object.keys(this._effectsSchema.definitions)) result._effectHandlers.set(name, anyHandlers[name]);
-			return new BuiltMachine(result);
-		}
-		return new BuiltMachine(this);
-	}
 	static make(config) {
 		return new Machine(config.initial, config.state, config.event, config.guards, config.effects);
 	}
@@ -405,27 +397,25 @@ var TransitionScope = class {
 };
 const make = Machine.make;
 /**
-* Spawn an actor from a built machine.
+* Spawn an actor from a machine.
 *
 * Options:
 * - `id` — custom actor ID (default: random)
 * - `hydrate` — restore from a previously-saved state snapshot.
-*   The actor starts in the hydrated state and re-runs spawn effects
-*   for that state (timers, scoped resources, etc.). Transition history
-*   is not replayed — only the current state's entry effects run.
-*
-* Persistence is composed in userland by observing `actor.changes`
-* and saving snapshots to your own storage.
+* - `slots` — slot handler implementations for slotful machines.
 */
-const spawn = Effect.fn("effect-machine.spawn")(function* (built, idOrOptions) {
-	const opts = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
-	const actor = yield* createActor(opts?.id ?? `actor-${Math.random().toString(36).slice(2)}`, built._inner, { initialState: opts?.hydrate });
+const spawn = Effect.fn("effect-machine.spawn")(function* (machine, options) {
+	const opts = typeof options === "string" ? { id: options } : options;
+	const actor = yield* createActor(opts?.id ?? `actor-${Math.random().toString(36).slice(2)}`, materializeMachine(machine, opts?.slots), {
+		initialState: opts?.hydrate,
+		supervision: opts?.supervision
+	});
 	const maybeScope = yield* Effect.serviceOption(Scope.Scope);
 	if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, actor.stop);
 	return actor;
 });
-const replay = Effect.fn("effect-machine.replay")(function* (built, events, options) {
-	const machine = built._inner;
+const replay = Effect.fn("effect-machine.replay")(function* (input, events, options) {
+	const machine = materializeMachine(input, options?.slots);
 	let state = options?.from ?? machine.initial;
 	const hasPostponeRules = machine.postponeRules.length > 0;
 	const postponed = [];
@@ -469,4 +459,4 @@ const replay = Effect.fn("effect-machine.replay")(function* (built, events, opti
 });
 const reply = makeReply;
 //#endregion
-export { BuiltMachine, Machine, findTransitions, machine_exports, make, replay, reply, spawn };
+export { Machine, findTransitions, machine_exports, make, materializeMachine, replay, reply, spawn };

package/v3/dist/supervision.d.ts

@@ -0,0 +1,97 @@
+import { Cause, Duration, Schedule } from "effect";
+
+//#region src/supervision.d.ts
+/**
+ * Where in the actor lifecycle a defect occurred.
+ *
+ * - `transition` — during event handler execution
+ * - `spawn` — during state spawn effect execution
+ * - `background` — in a background effect fiber
+ * - `initial-spawn` — during initial state spawn effects (before event loop)
+ */
+type DefectPhase = "transition" | "spawn" | "background" | "initial-spawn";
+/**
+ * Terminal exit reason for an actor generation.
+ *
+ * - `Final` — machine reached a final state normally
+ * - `Stopped` — explicit `actor.stop` or `actor.drain`
+ * - `Defect` — unhandled error in the runtime
+ */
+type ActorExit<S> = {
+  readonly _tag: "Final";
+  readonly state: S;
+} | {
+  readonly _tag: "Stopped";
+} | {
+  readonly _tag: "Defect";
+  readonly cause: Cause.Cause<unknown>;
+  readonly phase: DefectPhase;
+};
+/** Constructors for ActorExit */
+declare const ActorExit: {
+  readonly Final: <S>(state: S) => ActorExit<S>;
+  readonly Stopped: ActorExit<never>;
+  readonly Defect: <S = never>(cause: Cause.Cause<unknown>, phase: DefectPhase) => ActorExit<S>;
+};
+/**
+ * Phase state for supervised actors. Serializes concurrent stop/restart/drain.
+ *
+ * Transitions:
+ * - `Running` → crash → `Restarting` → new runtime → `Running`
+ * - `Running` → explicit stop/drain → `Stopping` → `Terminated`
+ * - `Restarting` → explicit stop → `Stopping` → `Terminated`
+ *
+ * @internal
+ */
+type CellPhase<S> = {
+  readonly _tag: "Running";
+  readonly generation: number;
+} | {
+  readonly _tag: "Restarting";
+  readonly generation: number;
+} | {
+  readonly _tag: "Stopping";
+} | {
+  readonly _tag: "Terminated";
+  readonly exit: ActorExit<S>;
+};
+declare namespace Supervision {
+  /**
+   * Supervision policy for actor restart behavior.
+   *
+   * `schedule` controls restart timing and budget — schedule exhaustion means terminal stop.
+   * `shouldRestart` optionally classifies defects — return `false` to stop immediately
+   * without consuming the schedule.
+   */
+  interface Policy {
+    /** Schedule that controls restart timing. Exhaustion = terminal stop. */
+    readonly schedule: Schedule.Schedule<unknown>;
+    /**
+     * Optional classifier: given a defect exit, decide whether to restart or stop immediately.
+     * Default: always restart (let schedule handle budget).
+     */
+    readonly shouldRestart?: (exit: Extract<ActorExit<unknown>, {
+      readonly _tag: "Defect";
+    }>) => boolean;
+  }
+  /** No supervision — crashes are terminal. */
+  const none: Policy;
+  /**
+   * Restart on defect with max restarts within a window, optional backoff.
+   *
+   * @example
+   * ```ts
+   * Supervision.restart() // unlimited restarts, no backoff
+   * Supervision.restart({ maxRestarts: 3 }) // 3 restarts then terminal
+   * Supervision.restart({ maxRestarts: 3, within: "1 minute" }) // 3 within 1 min
+   * Supervision.restart({ backoff: Schedule.exponential("100 millis") })
+   * ```
+   */
+  const restart: (options?: {
+    readonly maxRestarts?: number;
+    readonly within?: Duration.DurationInput;
+    readonly backoff?: Schedule.Schedule<unknown>;
+  }) => Policy;
+}
+//#endregion
+export { ActorExit, CellPhase, DefectPhase, Supervision };

package/v3/dist/supervision.js

@@ -0,0 +1,42 @@
+import { Schedule } from "effect";
+//#region src/supervision.ts
+/**
+* Supervision types for actor lifecycle management.
+*
+* Core concepts:
+* - `ActorExit<S>` — why an actor stopped (final, explicit stop, or defect)
+* - `DefectPhase` — where in the lifecycle a defect occurred
+* - `Supervision.Policy` — Schedule-based restart policy
+* - `CellPhase<S>` — internal phase machine for serializing stop/restart/drain
+*
+* @module
+*/
+/** Constructors for ActorExit */
+const ActorExit = {
+	Final: (state) => ({
+		_tag: "Final",
+		state
+	}),
+	Stopped: { _tag: "Stopped" },
+	Defect: (cause, phase) => ({
+		_tag: "Defect",
+		cause,
+		phase
+	})
+};
+let Supervision;
+(function(_Supervision) {
+	_Supervision.none = { schedule: Schedule.recurs(0) };
+	_Supervision.restart = (options) => {
+		let schedule = Schedule.forever;
+		if (options?.maxRestarts !== void 0) {
+			const recurs = Schedule.recurs(options.maxRestarts);
+			if (options.within !== void 0) schedule = Schedule.intersect(recurs, Schedule.windowed(options.within));
+			else schedule = recurs;
+		}
+		if (options?.backoff !== void 0) schedule = Schedule.intersect(schedule, options.backoff);
+		return { schedule };
+	};
+})(Supervision || (Supervision = {}));
+//#endregion
+export { ActorExit, Supervision };

package/v3/dist/testing.d.ts

@@ -1,11 +1,10 @@
-import { EffectsDef, GuardsDef, MachineContext } from "./slot.js";
 import { AssertionError } from "./errors.js";
-import { BuiltMachine, Machine, MachineRef } from "./machine.js";
+import { EffectsDef, GuardsDef, MachineContext } from "./slot.js";
+import { Machine, MachineRef } from "./machine.js";
 import { Effect, SubscriptionRef } from "effect";
 
 //#region src/testing.d.ts
-/** Accept either Machine or BuiltMachine for testing utilities. */
-type MachineInput<S, E, R, GD extends GuardsDef, EFD extends EffectsDef> = Machine<S, E, R, any, any, GD, EFD> | BuiltMachine<S, E, R>;
+type MachineInput<S, E, R, GD extends GuardsDef, EFD extends EffectsDef> = Machine<S, E, R, any, any, GD, EFD>;
 /**
  * Result of simulating events through a machine
  */
@@ -37,7 +36,9 @@ declare const simulate: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[]) => Effect.Effect<{
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], options?: {
+  slots?: Record<string, any>;
+} | undefined) => Effect.Effect<{
   states: S[];
   finalState: S;
 }, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
@@ -48,7 +49,9 @@ declare const assertReaches: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], expectedTag: string) => Effect.Effect<S, AssertionError, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], expectedTag: string, options?: {
+  slots?: Record<string, any>;
+} | undefined) => Effect.Effect<S, AssertionError, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
  * Assert that a machine follows a specific path of state tags
  *
@@ -65,7 +68,9 @@ declare const assertPath: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], expectedPath: readonly string[]) => Effect.Effect<{
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], expectedPath: readonly string[], options?: {
+  slots?: Record<string, any>;
+} | undefined) => Effect.Effect<{
   states: S[];
   finalState: S;
 }, AssertionError, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
@@ -86,7 +91,9 @@ declare const assertNeverReaches: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], forbiddenTag: string) => Effect.Effect<{
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], forbiddenTag: string, options?: {
+  slots?: Record<string, any>;
+} | undefined) => Effect.Effect<{
   states: S[];
   finalState: S;
 }, AssertionError, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
@@ -133,7 +140,9 @@ declare const createTestHarness: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, options?: TestHarnessOptions<S, E> | undefined) => Effect.Effect<{
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, options?: (TestHarnessOptions<S, E> & {
+  slots?: Record<string, any>;
+}) | undefined) => Effect.Effect<{
   state: SubscriptionRef.SubscriptionRef<S>;
   send: (event: E) => Effect.Effect<S, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
   getState: Effect.Effect<S, never, never>;

package/v3/dist/testing.js

@@ -1,9 +1,18 @@
 import { stubSystem } from "./internal/utils.js";
 import { AssertionError } from "./errors.js";
-import { BuiltMachine } from "./machine.js";
 import { executeTransition, shouldPostpone } from "./internal/transition.js";
+import { materializeMachine } from "./machine.js";
 import { Effect, SubscriptionRef } from "effect";
 //#region src/testing.ts
+/** Create a dummy MachineRef for testing utilities (no real send/spawn). */
+const makeDummySelf = (label) => {
+	const dummySend = Effect.fn(`effect-machine.testing.${label}.send`)((_event) => Effect.void);
+	return {
+		send: dummySend,
+		cast: dummySend,
+		spawn: () => Effect.die(`spawn not supported in ${label}`)
+	};
+};
 /**
 * Simulate a sequence of events through a machine without running an actor.
 * Useful for testing state transitions in isolation.
@@ -24,14 +33,9 @@ import { Effect, SubscriptionRef } from "effect";
 * expect(result.states).toHaveLength(3) // Idle -> Loading -> Success
 * ```
 */
-const simulate = Effect.fn("effect-machine.simulate")(function* (input, events) {
-	const machine = input instanceof BuiltMachine ? input._inner : input;
-	const dummySend = Effect.fn("effect-machine.testing.simulate.send")((_event) => Effect.void);
-	const dummySelf = {
-		send: dummySend,
-		cast: dummySend,
-		spawn: () => Effect.die("spawn not supported in simulation")
-	};
+const simulate = Effect.fn("effect-machine.simulate")(function* (input, events, options) {
+	const machine = materializeMachine(input, options?.slots);
+	const dummySelf = makeDummySelf("simulate");
 	let currentState = machine.initial;
 	const states = [currentState];
 	const hasPostponeRules = machine.postponeRules.length > 0;
@@ -73,8 +77,8 @@ const simulate = Effect.fn("effect-machine.simulate")(function* (input, events)
 /**
 * Assert that a machine can reach a specific state given a sequence of events
 */
-const assertReaches = Effect.fn("effect-machine.assertReaches")(function* (input, events, expectedTag) {
-	const result = yield* simulate(input, events);
+const assertReaches = Effect.fn("effect-machine.assertReaches")(function* (input, events, expectedTag, options) {
+	const result = yield* simulate(input, events, options);
 	if (result.finalState._tag !== expectedTag) return yield* new AssertionError({ message: `Expected final state "${expectedTag}" but got "${result.finalState._tag}". States visited: ${result.states.map((s) => s._tag).join(" -> ")}` });
 	return result.finalState;
 });
@@ -90,8 +94,8 @@ const assertReaches = Effect.fn("effect-machine.assertReaches")(function* (input
 * )
 * ```
 */
-const assertPath = Effect.fn("effect-machine.assertPath")(function* (input, events, expectedPath) {
-	const result = yield* simulate(input, events);
+const assertPath = Effect.fn("effect-machine.assertPath")(function* (input, events, expectedPath, options) {
+	const result = yield* simulate(input, events, options);
 	const actualPath = result.states.map((s) => s._tag);
 	if (actualPath.length !== expectedPath.length) return yield* new AssertionError({ message: `Path length mismatch. Expected ${expectedPath.length} states but got ${actualPath.length}.\nExpected: ${expectedPath.join(" -> ")}\nActual:   ${actualPath.join(" -> ")}` });
 	for (let i = 0; i < expectedPath.length; i++) if (actualPath[i] !== expectedPath[i]) return yield* new AssertionError({ message: `Path mismatch at position ${i}. Expected "${expectedPath[i]}" but got "${actualPath[i]}".\nExpected: ${expectedPath.join(" -> ")}\nActual:   ${actualPath.join(" -> ")}` });
@@ -110,8 +114,8 @@ const assertPath = Effect.fn("effect-machine.assertPath")(function* (input, even
 * )
 * ```
 */
-const assertNeverReaches = Effect.fn("effect-machine.assertNeverReaches")(function* (input, events, forbiddenTag) {
-	const result = yield* simulate(input, events);
+const assertNeverReaches = Effect.fn("effect-machine.assertNeverReaches")(function* (input, events, forbiddenTag, options) {
+	const result = yield* simulate(input, events, options);
 	const visitedIndex = result.states.findIndex((s) => s._tag === forbiddenTag);
 	if (visitedIndex !== -1) return yield* new AssertionError({ message: `Machine reached forbidden state "${forbiddenTag}" at position ${visitedIndex}.\nStates visited: ${result.states.map((s) => s._tag).join(" -> ")}` });
 	return result;
@@ -138,13 +142,8 @@ const assertNeverReaches = Effect.fn("effect-machine.assertNeverReaches")(functi
 * ```
 */
 const createTestHarness = Effect.fn("effect-machine.createTestHarness")(function* (input, options) {
-	const machine = input instanceof BuiltMachine ? input._inner : input;
-	const dummySend = Effect.fn("effect-machine.testing.harness.send")((_event) => Effect.void);
-	const dummySelf = {
-		send: dummySend,
-		cast: dummySend,
-		spawn: () => Effect.die("spawn not supported in test harness")
-	};
+	const machine = materializeMachine(input, options?.slots);
+	const dummySelf = makeDummySelf("harness");
 	const stateRef = yield* SubscriptionRef.make(machine.initial);
 	const hasPostponeRules = machine.postponeRules.length > 0;
 	const postponed = [];