effect-machine 0.4.0 → 0.7.0

package/dist-v3/internal/transition.js

@@ -0,0 +1,238 @@
+import { INTERNAL_ENTER_EVENT, isEffect } from "./utils.js";
+import { BuiltMachine } from "../machine.js";
+import { Cause, Effect, Exit, Scope } from "effect";
+
+//#region src-v3/internal/transition.ts
+/**
+* Transition execution and indexing.
+*
+* Combines:
+* - Transition execution logic (for event processing, simulation, test harness)
+* - Event processing core (shared between actor and cluster entity)
+* - O(1) indexed lookup by state/event tag
+*
+* @internal
+*/
+/**
+* Run a transition handler and return the new state.
+* Shared logic for executing handlers with proper context.
+*
+* Used by:
+* - executeTransition (actor event loop, testing)
+* - persistent-actor replay (restore, replayTo)
+*
+* @internal
+*/
+const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(function* (machine, transition, state, event, self, system) {
+	const ctx = {
+		state,
+		event,
+		self,
+		system
+	};
+	const { guards, effects } = machine._slots;
+	const handlerCtx = {
+		state,
+		event,
+		guards,
+		effects
+	};
+	const result = transition.handler(handlerCtx);
+	return isEffect(result) ? yield* result.pipe(Effect.provideService(machine.Context, ctx)) : result;
+});
+/**
+* Execute a transition for a given state and event.
+* Handles transition resolution, handler invocation, and guard/effect slot creation.
+*
+* Used by:
+* - processEvent in actor.ts (actual actor event loop)
+* - simulate in testing.ts (pure transition simulation)
+* - createTestHarness.send in testing.ts (step-by-step testing)
+*
+* @internal
+*/
+const executeTransition = Effect.fn("effect-machine.executeTransition")(function* (machine, currentState, event, self, system) {
+	const transition = resolveTransition(machine, currentState, event);
+	if (transition === void 0) return {
+		newState: currentState,
+		transitioned: false,
+		reenter: false
+	};
+	return {
+		newState: yield* runTransitionHandler(machine, transition, currentState, event, self, system),
+		transitioned: true,
+		reenter: transition.reenter === true
+	};
+});
+/**
+* Process a single event through the machine.
+*
+* Handles:
+* - Transition execution
+* - State scope lifecycle (close old, create new)
+* - Running spawn effects
+*
+* Optional hooks allow inspection/tracing without coupling to specific impl.
+*
+* @internal
+*/
+const processEventCore = Effect.fn("effect-machine.processEventCore")(function* (machine, currentState, event, self, stateScopeRef, system, hooks) {
+	const result = yield* executeTransition(machine, currentState, event, self, system).pipe(Effect.catchAllCause((cause) => {
+		if (Cause.isInterruptedOnly(cause)) return Effect.interrupt;
+		const onError = hooks?.onError;
+		if (onError === void 0) return Effect.failCause(cause).pipe(Effect.orDie);
+		return onError({
+			phase: "transition",
+			state: currentState,
+			event,
+			cause
+		}).pipe(Effect.zipRight(Effect.failCause(cause).pipe(Effect.orDie)));
+	}));
+	if (!result.transitioned) return {
+		newState: currentState,
+		previousState: currentState,
+		transitioned: false,
+		lifecycleRan: false,
+		isFinal: false
+	};
+	const newState = result.newState;
+	const runLifecycle = newState._tag !== currentState._tag || result.reenter;
+	if (runLifecycle) {
+		yield* Scope.close(stateScopeRef.current, Exit.void);
+		stateScopeRef.current = yield* Scope.make();
+		if (hooks?.onTransition !== void 0) yield* hooks.onTransition(currentState, newState, event);
+		if (hooks?.onSpawnEffect !== void 0) yield* hooks.onSpawnEffect(newState);
+		yield* runSpawnEffects(machine, newState, { _tag: INTERNAL_ENTER_EVENT }, self, stateScopeRef.current, system, hooks?.onError);
+	}
+	return {
+		newState,
+		previousState: currentState,
+		transitioned: true,
+		lifecycleRan: runLifecycle,
+		isFinal: machine.finalStates.has(newState._tag)
+	};
+});
+/**
+* Run spawn effects for a state (forked into state scope, auto-cancelled on state exit).
+*
+* @internal
+*/
+const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (machine, state, event, self, stateScope, system, onError) {
+	const spawnEffects = findSpawnEffects(machine, state._tag);
+	const ctx = {
+		state,
+		event,
+		self,
+		system
+	};
+	const { effects: effectSlots } = machine._slots;
+	const reportError = onError;
+	for (const spawnEffect of spawnEffects) {
+		const effect = spawnEffect.handler({
+			state,
+			event,
+			self,
+			effects: effectSlots,
+			system
+		}).pipe(Effect.provideService(machine.Context, ctx), Effect.catchAllCause((cause) => {
+			if (Cause.isInterruptedOnly(cause)) return Effect.interrupt;
+			if (reportError === void 0) return Effect.failCause(cause).pipe(Effect.orDie);
+			return reportError({
+				phase: "spawn",
+				state,
+				event,
+				cause
+			}).pipe(Effect.zipRight(Effect.failCause(cause).pipe(Effect.orDie)));
+		}));
+		yield* Effect.forkScoped(effect).pipe(Effect.provideService(Scope.Scope, stateScope));
+	}
+});
+/**
+* Resolve which transition should fire for a given state and event.
+* Uses indexed O(1) lookup. First matching transition wins.
+*/
+const resolveTransition = (machine, currentState, event) => {
+	return findTransitions(machine, currentState._tag, event._tag)[0];
+};
+const indexCache = /* @__PURE__ */ new WeakMap();
+/**
+* Invalidate cached index for a machine (call after mutation).
+*/
+const invalidateIndex = (machine) => {
+	indexCache.delete(machine);
+};
+/**
+* Build transition index from machine definition.
+* O(n) where n = number of transitions.
+*/
+const buildTransitionIndex = (transitions) => {
+	const index = /* @__PURE__ */ new Map();
+	for (const t of transitions) {
+		let stateMap = index.get(t.stateTag);
+		if (stateMap === void 0) {
+			stateMap = /* @__PURE__ */ new Map();
+			index.set(t.stateTag, stateMap);
+		}
+		let eventList = stateMap.get(t.eventTag);
+		if (eventList === void 0) {
+			eventList = [];
+			stateMap.set(t.eventTag, eventList);
+		}
+		eventList.push(t);
+	}
+	return index;
+};
+/**
+* Build spawn index from machine definition.
+*/
+const buildSpawnIndex = (effects) => {
+	const index = /* @__PURE__ */ new Map();
+	for (const e of effects) {
+		let stateList = index.get(e.stateTag);
+		if (stateList === void 0) {
+			stateList = [];
+			index.set(e.stateTag, stateList);
+		}
+		stateList.push(e);
+	}
+	return index;
+};
+/**
+* Get or build index for a machine.
+*/
+const getIndex = (machine) => {
+	let index = indexCache.get(machine);
+	if (index === void 0) {
+		index = {
+			transitions: buildTransitionIndex(machine.transitions),
+			spawn: buildSpawnIndex(machine.spawnEffects)
+		};
+		indexCache.set(machine, index);
+	}
+	return index;
+};
+/**
+* Find all transitions matching a state/event pair.
+* Returns empty array if no matches.
+*
+* Accepts both `Machine` and `BuiltMachine`.
+* O(1) lookup after first access (index is lazily built).
+*/
+const findTransitions = (input, stateTag, eventTag) => {
+	const index = getIndex(input instanceof BuiltMachine ? input._inner : input);
+	const specific = index.transitions.get(stateTag)?.get(eventTag) ?? [];
+	if (specific.length > 0) return specific;
+	return index.transitions.get("*")?.get(eventTag) ?? [];
+};
+/**
+* Find all spawn effects for a state.
+* Returns empty array if no matches.
+*
+* O(1) lookup after first access (index is lazily built).
+*/
+const findSpawnEffects = (machine, stateTag) => {
+	return getIndex(machine).spawn.get(stateTag) ?? [];
+};
+
+//#endregion
+export { executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler };

package/dist-v3/internal/utils.d.ts

@@ -0,0 +1,60 @@
+import { ActorSystem } from "../actor.js";
+import { Effect } from "effect";
+
+//#region src-v3/internal/utils.d.ts
+/**
+ * Extracts _tag from a tagged union member
+ */
+type TagOf<T> = T extends {
+  readonly _tag: infer Tag;
+} ? Tag : never;
+/**
+ * Extracts args type from a Data.taggedEnum constructor
+ */
+type ArgsOf<C> = C extends ((args: infer A) => unknown) ? A : never;
+/**
+ * Extracts return type from a Data.taggedEnum constructor
+ * @internal
+ */
+type InstanceOf<C> = C extends ((...args: unknown[]) => infer R) ? R : never;
+/**
+ * A tagged union constructor (from Data.taggedEnum)
+ */
+type TaggedConstructor<T extends {
+  readonly _tag: string;
+}> = (args: Omit<T, "_tag">) => T;
+/**
+ * Transition handler result - either a new state or Effect producing one
+ */
+type TransitionResult<State, R> = State | Effect.Effect<State, never, R>;
+/**
+ * Internal event tags used for lifecycle effect contexts.
+ * Prefixed with $ to distinguish from user events.
+ * @internal
+ */
+declare const INTERNAL_INIT_EVENT: "$init";
+declare const INTERNAL_ENTER_EVENT: "$enter";
+/**
+ * Extract _tag from a tagged value or constructor.
+ *
+ * Supports:
+ * - Plain values with `_tag` (MachineSchema empty structs)
+ * - Constructors with static `_tag` (MachineSchema non-empty structs)
+ * - Data.taggedEnum constructors (fallback via instantiation)
+ */
+declare const getTag: (constructorOrValue: {
+  _tag: string;
+} | ((...args: never[]) => {
+  _tag: string;
+})) => string;
+/** Check if a value is an Effect */
+declare const isEffect: (value: unknown) => value is Effect.Effect<unknown, unknown, unknown>;
+/**
+ * Stub ActorSystem that dies on any method call.
+ * Used in contexts where spawning/system access isn't supported
+ * (testing simulation, persistent actor replay).
+ * @internal
+ */
+declare const stubSystem: ActorSystem;
+//#endregion
+export { ArgsOf, INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, InstanceOf, TagOf, TaggedConstructor, TransitionResult, getTag, isEffect, stubSystem };

package/dist-v3/internal/utils.js

@@ -0,0 +1,51 @@
+import { Effect, Stream } from "effect";
+
+//#region src-v3/internal/utils.ts
+/**
+* Internal event tags used for lifecycle effect contexts.
+* Prefixed with $ to distinguish from user events.
+* @internal
+*/
+const INTERNAL_INIT_EVENT = "$init";
+const INTERNAL_ENTER_EVENT = "$enter";
+/**
+* Extract _tag from a tagged value or constructor.
+*
+* Supports:
+* - Plain values with `_tag` (MachineSchema empty structs)
+* - Constructors with static `_tag` (MachineSchema non-empty structs)
+* - Data.taggedEnum constructors (fallback via instantiation)
+*/
+const getTag = (constructorOrValue) => {
+	if ("_tag" in constructorOrValue && typeof constructorOrValue._tag === "string") return constructorOrValue._tag;
+	try {
+		return constructorOrValue()._tag;
+	} catch {
+		return constructorOrValue({})._tag;
+	}
+};
+/** Check if a value is an Effect */
+const isEffect = (value) => typeof value === "object" && value !== null && Effect.EffectTypeId in value;
+/**
+* Stub ActorSystem that dies on any method call.
+* Used in contexts where spawning/system access isn't supported
+* (testing simulation, persistent actor replay).
+* @internal
+*/
+const stubSystem = {
+	spawn: () => Effect.die("spawn not supported in stub system"),
+	restore: () => Effect.die("restore not supported in stub system"),
+	get: () => Effect.die("get not supported in stub system"),
+	stop: () => Effect.die("stop not supported in stub system"),
+	events: Stream.empty,
+	get actors() {
+		return /* @__PURE__ */ new Map();
+	},
+	subscribe: () => () => {},
+	listPersisted: () => Effect.die("listPersisted not supported in stub system"),
+	restoreMany: () => Effect.die("restoreMany not supported in stub system"),
+	restoreAll: () => Effect.die("restoreAll not supported in stub system")
+};
+
+//#endregion
+export { INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, getTag, isEffect, stubSystem };

package/dist-v3/machine.d.ts

@@ -0,0 +1,278 @@
+import { TransitionResult } from "./internal/utils.js";
+import { BrandedEvent, BrandedState, TaggedOrConstructor } from "./internal/brands.js";
+import { MachineEventSchema, MachineStateSchema, VariantsUnion } from "./schema.js";
+import { PersistenceConfig, PersistentMachine } from "./persistence/persistent-machine.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 "./persistence/index.js";
+import { ActorRef, ActorSystem } from "./actor.js";
+import { Cause, Context, Effect, Schedule, Schema, Scope } from "effect";
+
+//#region src-v3/machine.d.ts
+declare namespace machine_d_exports {
+  export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, PersistenceConfig, PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, Transition, TransitionHandler, findTransitions, make, spawn };
+}
+/**
+ * Self reference for sending events back to the machine
+ */
+interface MachineRef<Event> {
+  readonly send: (event: Event) => Effect.Effect<void>;
+  readonly spawn: <S2 extends {
+    readonly _tag: string;
+  }, E2 extends {
+    readonly _tag: string;
+  }, R2>(id: string, machine: BuiltMachine<S2, E2, R2>) => Effect.Effect<ActorRef<S2, E2>, DuplicateActorError, R2>;
+}
+/**
+ * Handler context passed to transition handlers
+ */
+interface HandlerContext<State, Event, GD extends GuardsDef, ED extends EffectsDef> {
+  readonly state: State;
+  readonly event: Event;
+  readonly guards: GuardSlots<GD>;
+  readonly effects: EffectSlots<ED>;
+}
+/**
+ * Handler context passed to state effect handlers (onEnter, spawn, background)
+ */
+interface StateHandlerContext<State, Event, ED extends EffectsDef> {
+  readonly state: State;
+  readonly event: Event;
+  readonly self: MachineRef<Event>;
+  readonly effects: EffectSlots<ED>;
+  readonly system: ActorSystem;
+}
+/**
+ * Transition handler function
+ */
+type TransitionHandler<S, E, NewState, GD extends GuardsDef, ED extends EffectsDef, R> = (ctx: HandlerContext<S, E, GD, ED>) => TransitionResult<NewState, R>;
+/**
+ * State effect handler function
+ */
+type StateEffectHandler<S, E, ED extends EffectsDef, R> = (ctx: StateHandlerContext<S, E, ED>) => Effect.Effect<void, never, R>;
+/**
+ * Transition definition
+ */
+interface Transition<State, Event, GD extends GuardsDef, ED extends EffectsDef, R> {
+  readonly stateTag: string;
+  readonly eventTag: string;
+  readonly handler: TransitionHandler<State, Event, State, GD, ED, R>;
+  readonly reenter?: boolean;
+}
+/**
+ * Spawn effect - state-scoped forked effect
+ */
+interface SpawnEffect<State, Event, ED extends EffectsDef, R> {
+  readonly stateTag: string;
+  readonly handler: StateEffectHandler<State, Event, ED, R>;
+}
+/**
+ * Background effect - runs for entire machine lifetime
+ */
+interface BackgroundEffect<State, Event, ED extends EffectsDef, R> {
+  readonly handler: StateEffectHandler<State, Event, ED, R>;
+}
+/** Options for `persist` */
+interface PersistOptions {
+  readonly snapshotSchedule: Schedule.Schedule<unknown, {
+    readonly _tag: string;
+  }>;
+  readonly journalEvents: boolean;
+  readonly machineType?: string;
+}
+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;
+  };
+  readonly event: MachineEventSchema<ED> & {
+    Type: E;
+  };
+  readonly guards?: GuardsSchema<GD>;
+  readonly effects?: EffectsSchema<EFD>;
+  readonly initial: S;
+}
+/** Check if a GuardsDef has any actual keys */
+type HasGuardKeys<GD extends GuardsDef> = [keyof GD] extends [never] ? false : GD extends Record<string, never> ? false : true;
+/** Check if an EffectsDef has any actual keys */
+type HasEffectKeys<EFD extends EffectsDef> = [keyof EFD] extends [never] ? false : EFD extends Record<string, never> ? false : true;
+/** Context type passed to guard/effect handlers */
+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.
+ *
+ * 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`.
+ */
+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;
+  persist(config: PersistOptions): PersistentMachine<State & {
+    readonly _tag: string;
+  }, Event & {
+    readonly _tag: string;
+  }, R>;
+}
+/**
+ * Machine definition with fluent builder API.
+ *
+ * Type parameters:
+ * - `State`: The state union type
+ * - `Event`: The event union type
+ * - `R`: Effect requirements
+ * - `_SD`: State schema definition (for compile-time validation)
+ * - `_ED`: Event schema definition (for compile-time validation)
+ * - `GD`: Guard definitions
+ * - `EFD`: Effect definitions
+ */
+declare class Machine<State, Event, R = never, _SD extends Record<string, Schema.Struct.Fields> = Record<string, Schema.Struct.Fields>, _ED extends Record<string, Schema.Struct.Fields> = Record<string, Schema.Struct.Fields>, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>> {
+  readonly initial: State;
+  /** @internal */
+  readonly _transitions: Array<Transition<State, Event, GD, EFD, R>>;
+  /** @internal */
+  readonly _spawnEffects: Array<SpawnEffect<State, Event, EFD, R>>;
+  /** @internal */
+  readonly _backgroundEffects: Array<BackgroundEffect<State, Event, EFD, R>>;
+  /** @internal */
+  readonly _finalStates: Set<string>;
+  /** @internal */
+  readonly _guardsSchema?: GuardsSchema<GD>;
+  /** @internal */
+  readonly _effectsSchema?: EffectsSchema<EFD>;
+  /** @internal */
+  readonly _guardHandlers: Map<string, (params: unknown, ctx: SlotContext<State, Event>) => boolean | Effect.Effect<boolean, never, R>>;
+  /** @internal */
+  readonly _effectHandlers: Map<string, (params: unknown, ctx: SlotContext<State, Event>) => Effect.Effect<void, never, R>>;
+  /** @internal */
+  readonly _slots: {
+    guards: GuardSlots<GD>;
+    effects: EffectSlots<EFD>;
+  };
+  readonly stateSchema?: Schema.Schema<State, unknown, never>;
+  readonly eventSchema?: Schema.Schema<Event, unknown, never>;
+  /**
+   * Context tag for accessing machine state/event/self in slot handlers.
+   * Uses shared module-level tag for all machines.
+   */
+  readonly Context: Context.Tag<MachineContext<State, Event, MachineRef<Event>>, MachineContext<State, Event, MachineRef<Event>>>;
+  get transitions(): ReadonlyArray<Transition<State, Event, GD, EFD, R>>;
+  get spawnEffects(): ReadonlyArray<SpawnEffect<State, Event, EFD, R>>;
+  get backgroundEffects(): ReadonlyArray<BackgroundEffect<State, Event, EFD, R>>;
+  get finalStates(): ReadonlySet<string>;
+  get guardsSchema(): GuardsSchema<GD> | undefined;
+  get effectsSchema(): EffectsSchema<EFD> | undefined;
+  /** @internal */
+  constructor(initial: State, stateSchema?: Schema.Schema<State, unknown, never>, eventSchema?: Schema.Schema<Event, unknown, never>, guardsSchema?: GuardsSchema<GD>, effectsSchema?: EffectsSchema<EFD>);
+  /** Register transition for a single state */
+  on<NS extends VariantsUnion<_SD> & BrandedState, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS, NE, RS, GD, EFD, never>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /** Register transition for multiple states (handler receives union of state types) */
+  on<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(states: NS, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS[number] extends TaggedOrConstructor<infer S> ? S : never, NE, RS, GD, EFD, never>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /**
+   * Like `on()`, but forces onEnter/spawn to run even when transitioning to the same state tag.
+   * Use this to restart timers, re-run spawned effects, or reset state-scoped effects.
+   */
+  /** Single state */
+  reenter<NS extends VariantsUnion<_SD> & BrandedState, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS, NE, RS, GD, EFD, never>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /** Multiple states */
+  reenter<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(states: NS, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS[number] extends TaggedOrConstructor<infer S> ? S : never, NE, RS, GD, EFD, never>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /**
+   * Register a wildcard transition that fires from any state when no specific transition matches.
+   * Specific `.on()` transitions always take priority over `.onAny()`.
+   */
+  onAny<NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(event: TaggedOrConstructor<NE>, handler: TransitionHandler<VariantsUnion<_SD> & BrandedState, NE, RS, GD, EFD, never>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /** @internal */
+  private addTransition;
+  /**
+   * State-scoped effect that is forked on state entry and automatically cancelled on state exit.
+   * Use effect slots defined via `Slot.Effects` for the actual work.
+   *
+   * @example
+   * ```ts
+   * const MyEffects = Slot.Effects({
+   *   fetchData: { url: Schema.String },
+   * });
+   *
+   * machine
+   *   .spawn(State.Loading, ({ effects, state }) => effects.fetchData({ url: state.url }))
+   *   .build({
+   *     fetchData: ({ url }, { self }) =>
+   *       Effect.gen(function* () {
+   *         yield* Effect.addFinalizer(() => Effect.log("Leaving Loading"));
+   *         const data = yield* Http.get(url);
+   *         yield* self.send(Event.Loaded({ data }));
+   *       }),
+   *   });
+   * ```
+   */
+  spawn<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, handler: StateEffectHandler<NS, VariantsUnion<_ED> & BrandedEvent, EFD, Scope.Scope>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /**
+   * State-scoped task that runs on entry and sends success/failure events.
+   * Interrupts do not emit failure events.
+   */
+  task<NS extends VariantsUnion<_SD> & BrandedState, A, E1, ES extends VariantsUnion<_ED> & BrandedEvent, EF extends VariantsUnion<_ED> & BrandedEvent>(state: TaggedOrConstructor<NS>, run: (ctx: StateHandlerContext<NS, VariantsUnion<_ED> & BrandedEvent, EFD>) => Effect.Effect<A, E1, Scope.Scope>, options: {
+    readonly onSuccess: (value: A, ctx: StateHandlerContext<NS, VariantsUnion<_ED> & BrandedEvent, EFD>) => ES;
+    readonly onFailure?: (cause: Cause.Cause<E1>, ctx: StateHandlerContext<NS, VariantsUnion<_ED> & BrandedEvent, EFD>) => EF;
+  }): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /**
+   * Machine-lifetime effect that is forked on actor spawn and runs until the actor stops.
+   * Use effect slots defined via `Slot.Effects` for the actual work.
+   *
+   * @example
+   * ```ts
+   * const MyEffects = Slot.Effects({
+   *   heartbeat: {},
+   * });
+   *
+   * machine
+   *   .background(({ effects }) => effects.heartbeat())
+   *   .build({
+   *     heartbeat: (_, { self }) =>
+   *       Effect.forever(
+   *         Effect.sleep("30 seconds").pipe(Effect.andThen(self.send(Event.Ping)))
+   *       ),
+   *   });
+   * ```
+   */
+  background(handler: StateEffectHandler<State, Event, EFD, Scope.Scope>): 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>>;
+  /** @internal Persist from raw Machine — prefer BuiltMachine.persist() */
+  persist(config: PersistOptions): PersistentMachine<State & {
+    readonly _tag: string;
+  }, Event & {
+    readonly _tag: string;
+  }, R>;
+  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 const make: typeof Machine.make;
+declare const spawn: {
+  <S extends {
+    readonly _tag: string;
+  }, E extends {
+    readonly _tag: string;
+  }, R>(machine: BuiltMachine<S, E, R>): Effect.Effect<ActorRef<S, E>, never, R>;
+  <S extends {
+    readonly _tag: string;
+  }, E extends {
+    readonly _tag: string;
+  }, R>(machine: BuiltMachine<S, E, R>, id: string): Effect.Effect<ActorRef<S, E>, never, R>;
+};
+//#endregion
+export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, type PersistenceConfig, type PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, Transition, TransitionHandler, findTransitions, machine_d_exports, make, spawn };