effect-machine 0.18.0 → 0.20.0

package/dist/machine.js

@@ -1,9 +1,10 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
-import { getTag, makeDeferReply, makeReply } from "./internal/utils.js";
+import { INTERNAL_INIT_EVENT, getTag, makeDeferReply, makeReply } from "./internal/utils.js";
 import { getReplySchemas } from "./schema.js";
 import { makeEventAdvancement } from "./internal/event-advancement.js";
 import { executeTransition, shouldPostpone } from "./internal/transition.js";
 import { emitWithTimestamp } from "./internal/inspection.js";
+import { MachineInitialization } from "./internal/machine-initialization.js";
 import { Inspector } from "./inspection.js";
 import { ActorScope, createActor } from "./actor.js";
 import { Cause, Effect, Exit, Option, Random, Scope } from "effect";
@@ -14,6 +15,7 @@ var machine_exports = /* @__PURE__ */ __exportAll({
 	make: () => make,
 	replay: () => replay,
 	reply: () => reply,
+	run: () => run,
 	scoped: () => scoped,
 	spawn: () => spawn
 });
@@ -34,6 +36,7 @@ const emitTaskInspection = (input) => Effect.flatMap(Effect.serviceOption(Inspec
 	return emitWithTimestamp(inspector.value, (timestamp) => ({
 		type: "@machine.task",
 		actorId: input.actorId,
+		generation: input.generation,
 		state: input.state,
 		taskName: input.taskName,
 		phase: input.phase,
@@ -53,21 +56,27 @@ const emitTaskInspection = (input) => Effect.flatMap(Effect.serviceOption(Inspec
 */
 var Machine = class Machine {
 	initial;
+	#initialization;
 	#backgroundEffects;
 	#finalStates;
+	#finalOutputs;
 	#postponeRules;
 	stateSchema;
 	eventSchema;
 	#replySchemas;
 	#transitionIndex;
+	#immediateIndex;
 	#spawnIndex;
 	/** @internal */
 	constructor(initial, stateSchema, eventSchema) {
-		this.initial = initial;
+		this.#initialization = MachineInitialization.make(initial);
+		this.initial = MachineInitialization.staticValue(this.#initialization);
 		this.#backgroundEffects = [];
 		this.#finalStates = /* @__PURE__ */ new Set();
+		this.#finalOutputs = /* @__PURE__ */ new Map();
 		this.#postponeRules = [];
 		this.#transitionIndex = /* @__PURE__ */ new Map();
+		this.#immediateIndex = /* @__PURE__ */ new Map();
 		this.#spawnIndex = /* @__PURE__ */ new Map();
 		this.#replySchemas = getReplySchemas(eventSchema) ?? /* @__PURE__ */ new Map();
 		this.stateSchema = stateSchema;
@@ -79,8 +88,8 @@ var Machine = class Machine {
 		return this;
 	}
 	/** @internal */
-	scopeTransition(states, event, handler, reenter) {
-		for (const state of states) this.addTransition(state, event, handler, reenter);
+	scopeTransition(states, event, handler, reenter, guard) {
+		for (const state of states) this.addTransition(state, event, handler, reenter, guard);
 		return this;
 	}
 	on(stateOrStates, event, handler) {
@@ -88,6 +97,11 @@ var Machine = class Machine {
 		for (const s of states) this.addTransition(s, event, handler, false);
 		return this;
 	}
+	when(stateOrStates, event, predicate, handler) {
+		const states = toReadonlyArray(stateOrStates);
+		for (const state of states) this.addTransition(state, event, handler, false, predicate);
+		return this;
+	}
 	reenter(stateOrStates, event, handler) {
 		let states;
 		if (Array.isArray(stateOrStates)) states = stateOrStates;
@@ -95,6 +109,11 @@ var Machine = class Machine {
 		for (const s of states) this.addTransition(s, event, handler, true);
 		return this;
 	}
+	reenterWhen(stateOrStates, event, predicate, handler) {
+		const states = toReadonlyArray(stateOrStates);
+		for (const state of states) this.addTransition(state, event, handler, true, predicate);
+		return this;
+	}
 	/**
 	* Register a wildcard transition that fires from any state when no specific transition matches.
 	* Specific `.on()` transitions always take priority over `.onAny()`.
@@ -109,17 +128,59 @@ var Machine = class Machine {
 		this.registerTransition(transition);
 		return this;
 	}
+	/** Register a conditional wildcard transition. */
+	whenAny(event, predicate, handler) {
+		const transition = {
+			stateTag: "*",
+			eventTag: getTag(event),
+			handler,
+			reenter: false,
+			guard: predicate
+		};
+		this.registerTransition(transition);
+		return this;
+	}
 	/** @internal */
-	addTransition(state, event, handler, reenter) {
+	addTransition(state, event, handler, reenter, guard) {
 		const transition = {
 			stateTag: getTag(state),
 			eventTag: getTag(event),
 			handler,
-			reenter
+			reenter,
+			guard
 		};
 		this.registerTransition(transition);
 		return this;
 	}
+	immediate(stateOrStates, handler) {
+		const states = toReadonlyArray(stateOrStates);
+		for (const state of states) {
+			const stateTag = getTag(state);
+			const transitions = this.#immediateIndex.get(stateTag) ?? [];
+			transitions.push({
+				stateTag,
+				eventTag: "",
+				handler
+			});
+			this.#immediateIndex.set(stateTag, transitions);
+		}
+		return this;
+	}
+	immediateWhen(stateOrStates, predicate, handler) {
+		const states = toReadonlyArray(stateOrStates);
+		for (const state of states) {
+			const stateTag = getTag(state);
+			const transitions = this.#immediateIndex.get(stateTag) ?? [];
+			transitions.push({
+				stateTag,
+				eventTag: "",
+				handler,
+				guard: predicate
+			});
+			this.#immediateIndex.set(stateTag, transitions);
+		}
+		return this;
+	}
 	spawn(stateOrStates, handler) {
 		const states = toReadonlyArray(stateOrStates);
 		for (const s of states) {
@@ -137,14 +198,20 @@ var Machine = class Machine {
 	/** @internal */
 	_findTransitions(stateTag, eventTag) {
 		const specific = this.#transitionIndex.get(stateTag)?.get(eventTag) ?? [];
-		if (specific.length > 0) return specific;
-		return this.#transitionIndex.get("*")?.get(eventTag) ?? [];
+		const wildcard = this.#transitionIndex.get("*")?.get(eventTag) ?? [];
+		if (specific.length === 0) return wildcard;
+		if (wildcard.length === 0) return specific;
+		return [...specific, ...wildcard];
 	}
 	/** @internal */
 	_findSpawnEffects(stateTag) {
 		return this.#spawnIndex.get(stateTag) ?? [];
 	}
 	/** @internal */
+	_findImmediateTransitions(stateTag) {
+		return this.#immediateIndex.get(stateTag) ?? [];
+	}
+	/** @internal */
 	_backgroundEffectEntries() {
 		return this.#backgroundEffects.values();
 	}
@@ -153,6 +220,16 @@ var Machine = class Machine {
 		return this.#finalStates.has(stateTag);
 	}
 	/** @internal */
+	_initial(input) {
+		return MachineInitialization.resolve(this.#initialization, input);
+	}
+	/** @internal */
+	_output(state) {
+		const resolve = this.#finalOutputs.get(state._tag);
+		if (resolve === void 0) return state;
+		return resolve(state);
+	}
+	/** @internal */
 	_shouldPostpone(stateTag, eventTag) {
 		return this.#postponeRules.some((rule) => rule.stateTag === stateTag && rule.eventTag === eventTag);
 	}
@@ -164,20 +241,6 @@ var Machine = class Machine {
 	_replySchema(eventTag) {
 		return this.#replySchemas.get(eventTag);
 	}
-	/** @internal */
-	_withInitial(initial) {
-		const copy = new Machine(initial, this.stateSchema, this.eventSchema);
-		copy.#backgroundEffects.push(...this.#backgroundEffects);
-		for (const stateTag of this.#finalStates) copy.#finalStates.add(stateTag);
-		copy.#postponeRules.push(...this.#postponeRules);
-		for (const [stateTag, events] of this.#transitionIndex) {
-			const eventCopy = /* @__PURE__ */ new Map();
-			for (const [eventTag, transitions] of events) eventCopy.set(eventTag, transitions.slice());
-			copy.#transitionIndex.set(stateTag, eventCopy);
-		}
-		for (const [stateTag, effects] of this.#spawnIndex) copy.#spawnIndex.set(stateTag, effects.slice());
-		return copy;
-	}
 	registerTransition(transition) {
 		const events = this.#transitionIndex.get(transition.stateTag) ?? /* @__PURE__ */ new Map();
 		const transitions = events.get(transition.eventTag) ?? [];
@@ -189,6 +252,7 @@ var Machine = class Machine {
 		const handler = Effect.fn("effect-machine.task")(function* (ctx) {
 			yield* emitTaskInspection({
 				actorId: ctx.actorId,
+				generation: ctx.generation,
 				state: ctx.state,
 				taskName: options.name,
 				phase: "start"
@@ -197,6 +261,7 @@ var Machine = class Machine {
 			if (Exit.isSuccess(exit)) {
 				yield* emitTaskInspection({
 					actorId: ctx.actorId,
+					generation: ctx.generation,
 					state: ctx.state,
 					taskName: options.name,
 					phase: "success"
@@ -211,21 +276,35 @@ var Machine = class Machine {
 			if (Cause.hasInterruptsOnly(cause)) {
 				yield* emitTaskInspection({
 					actorId: ctx.actorId,
+					generation: ctx.generation,
 					state: ctx.state,
 					taskName: options.name,
 					phase: "interrupt"
 				});
 				return;
 			}
+			if (Cause.hasDies(cause) || Cause.hasInterrupts(cause)) {
+				yield* emitTaskInspection({
+					actorId: ctx.actorId,
+					generation: ctx.generation,
+					state: ctx.state,
+					taskName: options.name,
+					phase: "defect",
+					error: Cause.pretty(cause)
+				});
+				return yield* Effect.failCause(cause).pipe(Effect.orDie);
+			}
+			const error = Option.getOrThrow(Cause.findErrorOption(cause));
 			yield* emitTaskInspection({
 				actorId: ctx.actorId,
+				generation: ctx.generation,
 				state: ctx.state,
 				taskName: options.name,
 				phase: "failure",
 				error: Cause.pretty(cause)
 			});
 			if (options.onFailure !== void 0) {
-				yield* ctx.self.send(options.onFailure(cause, ctx));
+				yield* ctx.self.send(options.onFailure(error, ctx));
 				yield* Effect.yieldNow;
 				return;
 			}
@@ -316,9 +395,11 @@ var Machine = class Machine {
 		}
 		return this;
 	}
-	final(state) {
+	final(state, output) {
 		const stateTag = getTag(state);
 		this.#finalStates.add(stateTag);
+		if (output === void 0) this.#finalOutputs.set(stateTag, (finalState) => finalState);
+		else this.#finalOutputs.set(stateTag, (finalState) => output({ state: finalState }));
 		return this;
 	}
 	static make(config) {
@@ -340,8 +421,34 @@ var TransitionScope = class {
 		this.machine.scopeTransition(this.states, event, handler, true);
 		return this;
 	}
+	when(event, predicate, handler) {
+		this.machine.scopeTransition(this.states, event, handler, false, predicate);
+		return this;
+	}
+	reenterWhen(event, predicate, handler) {
+		this.machine.scopeTransition(this.states, event, handler, true, predicate);
+		return this;
+	}
 };
 const make = Machine.make;
+const spawnImpl = Effect.fn("effect-machine.spawn")(function* (machine, idOrOptions) {
+	let opts;
+	if (typeof idOrOptions === "string") opts = { id: idOrOptions };
+	else opts = idOrOptions;
+	const actorId = opts?.id ?? `actor-${(yield* Random.next).toString(36).slice(2)}`;
+	const machineInitial = machine._initial(opts?.input);
+	const initialState = opts?.hydrate ?? machineInitial;
+	const actor = yield* createActor(actorId, machine, {
+		initialState,
+		machineInitial,
+		hydrated: opts?.hydrate !== void 0,
+		supervision: opts?.supervision,
+		lifecycle: opts?.lifecycle
+	});
+	const maybeScope = yield* Effect.serviceOption(ActorScope);
+	if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, actor.stop);
+	return actor;
+});
 /**
 * Spawn an actor from a machine.
 *
@@ -358,20 +465,10 @@ const make = Machine.make;
 * });
 * ```
 */
-const spawn = Effect.fn("effect-machine.spawn")(function* (machine, idOrOptions) {
-	let opts;
-	if (typeof idOrOptions === "string") opts = { id: idOrOptions };
-	else opts = idOrOptions;
-	const actorId = opts?.id ?? `actor-${(yield* Random.next).toString(36).slice(2)}`;
-	const actor = yield* createActor(actorId, machine, {
-		initialState: opts?.hydrate,
-		supervision: opts?.supervision,
-		lifecycle: opts?.lifecycle
-	});
-	const maybeScope = yield* Effect.serviceOption(ActorScope);
-	if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, actor.stop);
-	return actor;
-});
+const spawn = spawnImpl;
+const runImpl = (machine, options) => Effect.acquireUseRelease(spawnImpl(machine, options), (actor) => actor.start.pipe(Effect.andThen(actor.awaitOutput)), (actor) => actor.stop);
+/** Run one actor to final output and always release its resources. */
+const run = runImpl;
 /**
 * Wrap an effect to provide an `ActorScope` from the current `Scope`.
 *
@@ -394,8 +491,10 @@ const spawn = Effect.fn("effect-machine.spawn")(function* (machine, idOrOptions)
 const scoped = (effect) => Effect.flatMap(Effect.service(Scope.Scope), (scope) => Effect.provideService(effect, ActorScope, scope));
 const replay = Effect.fn("effect-machine.replay")(function* (input, events, options) {
 	const machine = input;
+	const from = options?.from ?? machine._initial(options?.input);
+	const initial = yield* executeTransition(machine, from, { _tag: INTERNAL_INIT_EVENT });
 	const advancement = makeEventAdvancement({
-		initial: options?.from ?? machine.initial,
+		initial: initial.newState,
 		isFinal: (state) => machine._isFinal(state._tag),
 		shouldPostpone: (state, event) => shouldPostpone(machine, state._tag, event._tag),
 		postpone: (_state, event) => Effect.succeed({
@@ -416,4 +515,4 @@ const replay = Effect.fn("effect-machine.replay")(function* (input, events, opti
 const reply = makeReply;
 const deferReply = makeDeferReply;
 //#endregion
-export { Machine, deferReply, machine_exports, make, replay, reply, scoped, spawn };
+export { Machine, deferReply, machine_exports, make, replay, reply, run, scoped, spawn };

package/dist/supervision.d.ts

@@ -16,9 +16,10 @@ type DefectPhase = "transition" | "spawn" | "background" | "initial-spawn";
  * - `Stopped` — explicit `actor.stop` or `actor.drain`
  * - `Defect` — unhandled error in the runtime
  */
-type ActorExit<S> = {
+type ActorExit<S, O = S> = {
   readonly _tag: "Final";
   readonly state: S;
+  readonly output: O;
 } | {
   readonly _tag: "Stopped";
 } | {
@@ -28,7 +29,7 @@ type ActorExit<S> = {
 };
 /** Constructors for ActorExit */
 declare const ActorExit: {
-  readonly Final: <S>(state: S) => ActorExit<S>;
+  readonly Final: <S, O>(state: S, output: O) => ActorExit<S, O>;
   readonly Stopped: ActorExit<never>;
   readonly Defect: <S = never>(cause: Cause.Cause<unknown>, phase: DefectPhase) => ActorExit<S>;
 };

package/dist/supervision.js

@@ -12,9 +12,10 @@ import { Schedule } from "effect";
 */
 /** Constructors for ActorExit */
 const ActorExit = {
-	Final: (state) => ({
+	Final: (state, output) => ({
 		_tag: "Final",
-		state
+		state,
+		output
 	}),
 	Stopped: { _tag: "Stopped" },
 	Defect: (cause, phase) => ({

package/dist/testing.d.ts

@@ -2,7 +2,12 @@ import { AssertionError } from "./errors.js";
 import { Machine } from "./machine.js";
 import { Effect, SubscriptionRef } from "effect";
 //#region src/testing.d.ts
-type MachineInput<S, E, R> = Machine<S, E, R, any, any>;
+type MachineInput<S, E, R, Input = void> = Machine<S, E, R, any, any, Input, any>;
+type SimulationOptions<Input> = [Input] extends [void] ? {
+  readonly input?: never;
+} : {
+  readonly input: Input;
+};
 /**
  * Result of simulating events through a machine
  */
@@ -10,33 +15,18 @@ interface SimulationResult<S> {
   readonly states: ReadonlyArray<S>;
   readonly finalState: S;
 }
-/**
- * Simulate a sequence of events through a machine without running an actor.
- * Useful for testing state transitions in isolation.
- * Does not run task, spawn, or background effects.
- *
- * @example
- * ```ts
- * const result = yield* simulate(
- *   fetcherMachine,
- *   [
- *     Event.Fetch({ url: "https://example.com" }),
- *     Event._Done({ data: { foo: "bar" } })
- *   ]
- * )
- *
- * expect(result.finalState._tag).toBe("Success")
- * expect(result.states).toHaveLength(3) // Idle -> Loading -> Success
- * ```
- */
-declare const simulate: <S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}, R>(input: MachineInput<S, E, R>, events: readonly E[]) => Effect.Effect<{
-  states: S[];
-  finalState: S;
-}, never, never>;
+declare const simulate: {
+  <S extends {
+    readonly _tag: string;
+  }, E extends {
+    readonly _tag: string;
+  }, R>(input: MachineInput<S, E, R, void>, events: ReadonlyArray<E>, options?: SimulationOptions<void>): Effect.Effect<SimulationResult<S>, never, R>;
+  <S extends {
+    readonly _tag: string;
+  }, E extends {
+    readonly _tag: string;
+  }, R, Input>(input: MachineInput<S, E, R, Input>, events: ReadonlyArray<E>, options: SimulationOptions<Input>): Effect.Effect<SimulationResult<S>, never, R>;
+};
 /**
  * Assert that a machine can reach a specific state given a sequence of events
  */
@@ -44,7 +34,7 @@ declare const assertReaches: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R>(input: MachineInput<S, E, R>, events: readonly E[], expectedTag: string) => Effect.Effect<S, AssertionError, never>;
+}, R>(input: MachineInput<S, E, R, void>, events: readonly E[], expectedTag: string) => Effect.Effect<S, AssertionError, R>;
 /**
  * Assert that a machine follows a specific path of state tags
  *
@@ -61,10 +51,7 @@ declare const assertPath: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R>(input: MachineInput<S, E, R>, events: readonly E[], expectedPath: readonly string[]) => Effect.Effect<{
-  states: S[];
-  finalState: S;
-}, AssertionError, never>;
+}, R>(input: MachineInput<S, E, R, void>, events: readonly E[], expectedPath: readonly string[]) => Effect.Effect<SimulationResult<S>, AssertionError, R>;
 /**
  * Assert that a machine never reaches a specific state given a sequence of events
  *
@@ -82,10 +69,7 @@ declare const assertNeverReaches: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R>(input: MachineInput<S, E, R>, events: readonly E[], forbiddenTag: string) => Effect.Effect<{
-  states: S[];
-  finalState: S;
-}, AssertionError, never>;
+}, R>(input: MachineInput<S, E, R, void>, events: readonly E[], forbiddenTag: string) => Effect.Effect<SimulationResult<S>, AssertionError, R>;
 /**
  * Create a controllable test harness for a machine
  */
@@ -104,34 +88,22 @@ interface TestHarnessOptions<S, E> {
    */
   readonly onTransition?: (from: S, event: E, to: S) => void;
 }
-/**
- * Create a test harness for step-by-step testing.
- * Does not run task, spawn, or background effects.
- *
- * @example Basic usage
- * ```ts
- * const harness = yield* createTestHarness(machine)
- * yield* harness.send(Event.Start())
- * const state = yield* harness.getState
- * ```
- *
- * @example With transition observer
- * ```ts
- * const transitions: Array<{ from: string; event: string; to: string }> = []
- * const harness = yield* createTestHarness(machine, {
- *   onTransition: (from, event, to) =>
- *     transitions.push({ from: from._tag, event: event._tag, to: to._tag })
- * })
- * ```
- */
-declare const createTestHarness: <S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}, R>(input: MachineInput<S, E, R>, options?: TestHarnessOptions<S, E> | undefined) => Effect.Effect<{
-  state: SubscriptionRef.SubscriptionRef<S>;
-  send: (event: E) => Effect.Effect<S, never, never>;
-  getState: Effect.Effect<S, never, never>;
-}, never, never>;
+type InputTestHarnessOptions<S, E, Input> = TestHarnessOptions<S, E> & ([Input] extends [void] ? {
+  readonly input?: never;
+} : {
+  readonly input: Input;
+});
+declare const createTestHarness: {
+  <S extends {
+    readonly _tag: string;
+  }, E extends {
+    readonly _tag: string;
+  }, R>(input: MachineInput<S, E, R, void>, options?: InputTestHarnessOptions<S, E, void>): Effect.Effect<TestHarness<S, E>, never, R>;
+  <S extends {
+    readonly _tag: string;
+  }, E extends {
+    readonly _tag: string;
+  }, R, Input>(input: MachineInput<S, E, R, Input>, options: InputTestHarnessOptions<S, E, Input>): Effect.Effect<TestHarness<S, E>, never, R>;
+};
 //#endregion
-export { AssertionError, SimulationResult, TestHarness, TestHarnessOptions, assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate };
+export { AssertionError, InputTestHarnessOptions, SimulationOptions, SimulationResult, TestHarness, TestHarnessOptions, assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate };

package/dist/testing.js

@@ -1,39 +1,18 @@
-import { isEffect } from "./internal/utils.js";
+import { INTERNAL_INIT_EVENT } from "./internal/utils.js";
 import { AssertionError } from "./errors.js";
 import { makeEventAdvancement } from "./internal/event-advancement.js";
-import { executeTransition, executeTransitionImmediate, shouldPostpone } from "./internal/transition.js";
+import { executeTransition, shouldPostpone } from "./internal/transition.js";
 import { Effect, SubscriptionRef } from "effect";
-//#region src/testing.ts
-/**
-* Simulate a sequence of events through a machine without running an actor.
-* Useful for testing state transitions in isolation.
-* Does not run task, spawn, or background effects.
-*
-* @example
-* ```ts
-* const result = yield* simulate(
-*   fetcherMachine,
-*   [
-*     Event.Fetch({ url: "https://example.com" }),
-*     Event._Done({ data: { foo: "bar" } })
-*   ]
-* )
-*
-* expect(result.finalState._tag).toBe("Success")
-* expect(result.states).toHaveLength(3) // Idle -> Loading -> Success
-* ```
-*/
-const simulate = Effect.fn("effect-machine.simulate")(function* (input, events) {
+const simulate = Effect.fn("effect-machine.simulate")(function* (input, events, options) {
 	const machine = input;
-	const states = [machine.initial];
+	const machineInitial = machine._initial(options?.input);
+	const initial = yield* executeTransition(machine, machineInitial, { _tag: INTERNAL_INIT_EVENT });
+	const states = [initial.newState];
 	if (!machine._hasPostponeRules()) {
-		let state = machine.initial;
+		let state = initial.newState;
 		for (const event of events) {
 			if (machine._isFinal(state._tag)) break;
-			const execution = executeTransitionImmediate(machine, state, event);
-			let result;
-			if (isEffect(execution)) result = yield* execution;
-			else result = execution;
+			const result = yield* executeTransition(machine, state, event);
 			if (result.transitioned) {
 				state = result.newState;
 				states.push(state);
@@ -45,7 +24,7 @@ const simulate = Effect.fn("effect-machine.simulate")(function* (input, events)
 		};
 	}
 	const advancement = makeEventAdvancement({
-		initial: machine.initial,
+		initial: initial.newState,
 		isFinal: (state) => machine._isFinal(state._tag),
 		shouldPostpone: (state, event) => shouldPostpone(machine, state._tag, event._tag),
 		postpone: (_state, event) => Effect.succeed({
@@ -115,31 +94,13 @@ const assertNeverReaches = Effect.fn("effect-machine.assertNeverReaches")(functi
 	if (visitedIndex !== -1) return yield* AssertionError.make({ message: `Machine reached forbidden state "${forbiddenTag}" at position ${visitedIndex}.\nStates visited: ${result.states.map((s) => s._tag).join(" -> ")}` });
 	return result;
 });
-/**
-* Create a test harness for step-by-step testing.
-* Does not run task, spawn, or background effects.
-*
-* @example Basic usage
-* ```ts
-* const harness = yield* createTestHarness(machine)
-* yield* harness.send(Event.Start())
-* const state = yield* harness.getState
-* ```
-*
-* @example With transition observer
-* ```ts
-* const transitions: Array<{ from: string; event: string; to: string }> = []
-* const harness = yield* createTestHarness(machine, {
-*   onTransition: (from, event, to) =>
-*     transitions.push({ from: from._tag, event: event._tag, to: to._tag })
-* })
-* ```
-*/
 const createTestHarness = Effect.fn("effect-machine.createTestHarness")(function* (input, options) {
 	const machine = input;
-	const stateRef = yield* SubscriptionRef.make(machine.initial);
+	const machineInitial = machine._initial(options?.input);
+	const initial = yield* executeTransition(machine, machineInitial, { _tag: INTERNAL_INIT_EVENT });
+	const stateRef = yield* SubscriptionRef.make(initial.newState);
 	const advancement = makeEventAdvancement({
-		initial: machine.initial,
+		initial: initial.newState,
 		isFinal: (state) => machine._isFinal(state._tag),
 		shouldPostpone: (state, event) => shouldPostpone(machine, state._tag, event._tag),
 		postpone: (state, event) => Effect.succeed({