effect-machine 0.12.0 → 0.14.0

package/dist/machine.d.ts

@@ -1,15 +1,16 @@
-import { EffectHandlers, EffectSlots, EffectsDef, EffectsSchema, GuardHandlers, GuardSlots, GuardsDef, GuardsSchema, MachineContext } from "./slot.js";
 import { DeferReplyResult, 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 { MachineContext, ProvideSlots, SlotCalls, SlotsDef, SlotsSchema } from "./slot.js";
+import { Supervision } from "./supervision.js";
 import { findTransitions } from "./internal/transition.js";
 import { ActorRef, ActorSystem } from "./actor.js";
-import { Cause, Duration, Effect, Schema, Scope, ServiceMap } from "effect";
+import { Cause, Duration, Effect, Option, Schema, Scope, ServiceMap } from "effect";
 
 //#region src/machine.d.ts
 declare namespace machine_d_exports {
-  export { BackgroundEffect, BuiltMachine, DeferReplyResult, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, ReplyResult, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, make, replay, reply, spawn };
+  export { BackgroundEffect, DeferReplyResult, HandlerContext, Machine, MachineRef, MakeConfig, PersistConfig, ReplyResult, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, 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>) => Effect.Effect<ActorRef<S2, E2>, DuplicateActorError, R2>;
   /**
    * Settle a deferred reply from a spawn handler.
    * Only usable when the transition handler returned `Machine.deferReply(state)`.
@@ -33,21 +34,20 @@ interface MachineRef<Event> {
 /**
  * Handler context passed to transition handlers
  */
-interface HandlerContext<State, Event, GD extends GuardsDef, ED extends EffectsDef> {
+interface HandlerContext<State, Event, SD extends SlotsDef = Record<string, never>> {
   readonly state: State;
   readonly event: Event;
-  readonly guards: GuardSlots<GD>;
-  readonly effects: EffectSlots<ED>;
+  readonly slots: SlotCalls<SD>;
 }
 /**
  * Handler context passed to state effect handlers (onEnter, spawn, background)
  */
-interface StateHandlerContext<State, Event, ED extends EffectsDef> {
+interface StateHandlerContext<State, Event, SD extends SlotsDef = Record<string, never>> {
   readonly actorId: string;
   readonly state: State;
   readonly event: Event;
   readonly self: MachineRef<Event>;
-  readonly effects: EffectSlots<ED>;
+  readonly slots: SlotCalls<SD>;
   readonly system: ActorSystem;
 }
 /**
@@ -55,38 +55,66 @@ interface StateHandlerContext<State, Event, ED extends EffectsDef> {
  * When Reply is concrete (event has a reply schema), handler must return Machine.reply().
  * When Reply is never, handler returns plain state.
  */
-type TransitionHandler<S, E, NewState, GD extends GuardsDef, ED extends EffectsDef, R, Reply = never> = (ctx: HandlerContext<S, E, GD, ED>) => TransitionResult<NewState, R, Reply>;
+type TransitionHandler<S, E, NewState, SD extends SlotsDef, R, Reply = never> = (ctx: HandlerContext<S, E, SD>) => TransitionResult<NewState, R, Reply>;
 /**
  * State effect handler function
  */
-type StateEffectHandler<S, E, ED extends EffectsDef, R> = (ctx: StateHandlerContext<S, E, ED>) => Effect.Effect<void, never, R>;
+type StateEffectHandler<S, E, SD extends SlotsDef, R> = (ctx: StateHandlerContext<S, E, SD>) => Effect.Effect<void, never, R>;
 /**
  * Transition definition
  */
-interface Transition<State, Event, GD extends GuardsDef, ED extends EffectsDef, R> {
+interface Transition<State, Event, SD extends SlotsDef, R> {
   readonly stateTag: string;
   readonly eventTag: string;
-  readonly handler: TransitionHandler<State, Event, State, GD, ED, R>;
+  readonly handler: TransitionHandler<State, Event, State, SD, R>;
   readonly reenter?: boolean;
 }
 /**
  * Spawn effect - state-scoped forked effect
  */
-interface SpawnEffect<State, Event, ED extends EffectsDef, R> {
+interface SpawnEffect<State, Event, SD extends SlotsDef, R> {
   readonly stateTag: string;
-  readonly handler: StateEffectHandler<State, Event, ED, R>;
+  readonly handler: StateEffectHandler<State, Event, SD, R>;
 }
 /**
  * Background effect - runs for entire machine lifetime
  */
-interface BackgroundEffect<State, Event, ED extends EffectsDef, R> {
-  readonly handler: StateEffectHandler<State, Event, ED, R>;
+interface BackgroundEffect<State, Event, SD extends SlotsDef, R> {
+  readonly handler: StateEffectHandler<State, Event, SD, R>;
 }
-interface TaskOptions<State, Event, ED extends EffectsDef, A, E1, ES, EF> {
-  readonly onSuccess: (value: A, ctx: StateHandlerContext<State, Event, ED>) => ES;
-  readonly onFailure?: (cause: Cause.Cause<E1>, ctx: StateHandlerContext<State, Event, ED>) => EF;
+interface TaskOptions<State, Event, SD extends SlotsDef, A, E1, ES, EF> {
+  readonly onSuccess?: (value: A, ctx: StateHandlerContext<State, Event, SD>) => ES;
+  readonly onFailure?: (cause: Cause.Cause<E1>, ctx: StateHandlerContext<State, Event, SD>) => EF;
   readonly name?: string;
 }
+/**
+ * Local persistence configuration for Machine.spawn.
+ *
+ * Fully-resolved callbacks — no service dependency.
+ * Separate from cluster EntityPersistence which uses a service-based adapter.
+ */
+interface PersistConfig<S> {
+  /** Load saved state on actor start (and restart). Returns None for cold start. */
+  readonly load: () => Effect.Effect<Option.Option<S>>;
+  /** Save state after each transition. Runs inline (blocks next event). */
+  readonly save: (state: S) => Effect.Effect<void>;
+  /** Optional filter — return false to skip saving for this transition. */
+  readonly shouldSave?: (state: S, previousState: S) => boolean;
+  /**
+   * Called after load() returns Some(state). Inspect the restored state
+   * and decide how to proceed before the machine starts.
+   *
+   * Return Some(state) to use that state, or None to discard and start fresh.
+   * Called on both initial spawn and supervision restart.
+   * Receives `initial` (machine.initial) for comparison.
+   *
+   * Use cases: validate persisted state against external systems,
+   * migrate schema changes, downgrade to a safe state on partial corruption.
+   */
+  readonly onRestore?: (state: S, context: {
+    readonly initial: S;
+  }) => Effect.Effect<Option.Option<S>>;
+}
 /**
  * Configuration for `.timeout()` — gen_statem-style state timeouts.
  *
@@ -99,44 +127,26 @@ 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> {
+interface MakeConfig<SD extends Record<string, Schema.Struct.Fields>, ED extends Record<string, Schema.Struct.Fields>, S extends BrandedState, E extends BrandedEvent, SLD extends SlotsDef = Record<string, never>> {
   readonly state: MachineStateSchema<SD> & {
     Type: S;
   };
   readonly event: MachineEventSchema<ED> & {
     Type: E;
   };
-  readonly guards?: GuardsSchema<GD>;
-  readonly effects?: EffectsSchema<EFD>;
+  readonly slots?: SlotsSchema<SLD>;
   readonly initial: S;
+  /** Validate slot inputs/outputs at runtime. Default: true. Set to false for hot paths. */
+  readonly slotValidation?: boolean;
 }
-/** 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.
+ * 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, SD extends SlotsDef>(machine: Machine<S, E, R, any, any, SD>, handlers?: Record<string, any>) => Machine<S, E, never, any, any, SD>;
 /**
  * Machine definition with fluent builder API.
  *
@@ -146,17 +156,16 @@ declare class BuiltMachine<State, Event, R = never> {
  * - `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
+ * - `SD`: Slot 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>> {
+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>, SD extends SlotsDef = Record<string, never>> {
   readonly initial: State;
   /** @internal */
-  readonly _transitions: Array<Transition<State, Event, GD, EFD, R>>;
+  readonly _transitions: Array<Transition<State, Event, SD, R>>;
   /** @internal */
-  readonly _spawnEffects: Array<SpawnEffect<State, Event, EFD, R>>;
+  readonly _spawnEffects: Array<SpawnEffect<State, Event, SD, R>>;
   /** @internal */
-  readonly _backgroundEffects: Array<BackgroundEffect<State, Event, EFD, R>>;
+  readonly _backgroundEffects: Array<BackgroundEffect<State, Event, SD, R>>;
   /** @internal */
   readonly _finalStates: Set<string>;
   /** @internal */
@@ -165,18 +174,13 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
     readonly eventTag: string;
   }>;
   /** @internal */
-  readonly _guardsSchema?: GuardsSchema<GD>;
-  /** @internal */
-  readonly _effectsSchema?: EffectsSchema<EFD>;
+  readonly _slotsSchema?: SlotsSchema<SD>;
   /** @internal */
-  readonly _guardHandlers: Map<string, (params: unknown, ctx: SlotContext<State, Event>) => boolean | Effect.Effect<boolean, never, R>>;
+  readonly _slotHandlers: Map<string, (params: unknown) => unknown | Effect.Effect<unknown, never, R>>;
   /** @internal */
-  readonly _effectHandlers: Map<string, (params: unknown, ctx: SlotContext<State, Event>) => Effect.Effect<void, never, R>>;
+  readonly _slots: SlotCalls<SD>;
   /** @internal */
-  readonly _slots: {
-    guards: GuardSlots<GD>;
-    effects: EffectSlots<EFD>;
-  };
+  readonly _slotValidation: boolean;
   readonly stateSchema?: Schema.Schema<State>;
   readonly eventSchema?: Schema.Schema<Event>;
   /** @internal */
@@ -186,70 +190,72 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
    * Uses shared module-level tag for all machines.
    */
   readonly Context: ServiceMap.Service<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 transitions(): ReadonlyArray<Transition<State, Event, SD, R>>;
+  get spawnEffects(): ReadonlyArray<SpawnEffect<State, Event, SD, R>>;
+  get backgroundEffects(): ReadonlyArray<BackgroundEffect<State, Event, SD, R>>;
   get finalStates(): ReadonlySet<string>;
   get postponeRules(): ReadonlyArray<{
     readonly stateTag: string;
     readonly eventTag: string;
   }>;
-  get guardsSchema(): GuardsSchema<GD> | undefined;
-  get effectsSchema(): EffectsSchema<EFD> | undefined;
+  get slotsSchema(): SlotsSchema<SD> | undefined;
   get replySchemas(): ReadonlyMap<string, Schema.Decoder<unknown>>;
   /** @internal */
-  constructor(initial: State, stateSchema?: Schema.Schema<State>, eventSchema?: Schema.Schema<Event>, guardsSchema?: GuardsSchema<GD>, effectsSchema?: EffectsSchema<EFD>);
-  from<NS extends VariantsUnion<_SD> & BrandedState, R1>(state: TaggedOrConstructor<NS>, build: (scope: TransitionScope<State, Event, R, _SD, _ED, GD, EFD, NS>) => R1): Machine<State, Event, R, _SD, _ED, GD, EFD>;
-  from<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>, R1>(states: NS, build: (scope: TransitionScope<State, Event, R, _SD, _ED, GD, EFD, NS[number] extends TaggedOrConstructor<infer S extends VariantsUnion<_SD> & BrandedState> ? S : never>) => R1): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  constructor(initial: State, stateSchema?: Schema.Schema<State>, eventSchema?: Schema.Schema<Event>, slotsSchema?: SlotsSchema<SD>, slotValidation?: boolean);
+  from<NS extends VariantsUnion<_SD> & BrandedState, R1>(state: TaggedOrConstructor<NS>, build: (scope: TransitionScope<State, Event, R, _SD, _ED, SD, NS>) => R1): Machine<State, Event, R, _SD, _ED, SD>;
+  from<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>, R1>(states: NS, build: (scope: TransitionScope<State, Event, R, _SD, _ED, SD, NS[number] extends TaggedOrConstructor<infer S extends VariantsUnion<_SD> & BrandedState> ? S : never>) => R1): Machine<State, Event, R, _SD, _ED, SD>;
   /** @internal */
-  scopeTransition<NS extends VariantsUnion<_SD> & BrandedState, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(states: ReadonlyArray<TaggedOrConstructor<NS>>, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS, NE, RS, GD, EFD, never, ExtractReply<NE>>, reenter: boolean): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  scopeTransition<NS extends VariantsUnion<_SD> & BrandedState, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(states: ReadonlyArray<TaggedOrConstructor<NS>>, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS, NE, RS, SD, never, ExtractReply<NE>>, reenter: boolean): Machine<State, Event, R, _SD, _ED, SD>;
   /** 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, ExtractReply<NE>>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  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, SD, never, ExtractReply<NE>>): Machine<State, Event, R, _SD, _ED, SD>;
   /** 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, ExtractReply<NE>>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  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, SD, never, ExtractReply<NE>>): Machine<State, Event, R, _SD, _ED, SD>;
   /**
    * 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, ExtractReply<NE>>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  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, SD, never, ExtractReply<NE>>): Machine<State, Event, R, _SD, _ED, SD>;
   /** 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, ExtractReply<NE>>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  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, SD, never, ExtractReply<NE>>): Machine<State, Event, R, _SD, _ED, SD>;
   /**
    * 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>;
+  onAny<NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(event: TaggedOrConstructor<NE>, handler: TransitionHandler<VariantsUnion<_SD> & BrandedState, NE, RS, SD, never>): Machine<State, Event, R, _SD, _ED, SD>;
   /** @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 }));
-   *       }),
-   *   });
+   * machine.spawn(State.Loading, ({ self, state }) =>
+   *   Effect.gen(function* () {
+   *     yield* Effect.addFinalizer(() => Effect.log("Leaving Loading"));
+   *     const data = yield* Http.get(state.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>;
+  /** Single state */
+  spawn<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, handler: StateEffectHandler<NS, VariantsUnion<_ED> & BrandedEvent, SD, Scope.Scope>): Machine<State, Event, R, _SD, _ED, SD>;
+  /** Multiple states */
+  spawn<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>>(states: NS, handler: StateEffectHandler<NS[number] extends TaggedOrConstructor<infer S> ? S : never, VariantsUnion<_ED> & BrandedEvent, SD, Scope.Scope>): Machine<State, Event, R, _SD, _ED, SD>;
   /**
    * State-scoped task that runs on entry and sends success/failure events.
    * Interrupts do not emit failure events.
+   *
+   * Supports multi-state and shorthand overloads:
+   * - `.task(State.X, run, { onSuccess, onFailure })` — explicit mapping
+   * - `.task(State.X, run, { onFailure })` — shorthand when run returns Event directly
+   * - `.task([State.X, State.Y], run, opts)` — multi-state
    */
-  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: TaskOptions<NS, VariantsUnion<_ED> & BrandedEvent, EFD, A, E1, ES, EF>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /** Single state — onSuccess optional (defaults to identity when task returns Event) */
+  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, SD>) => Effect.Effect<A, E1, Scope.Scope>, options: TaskOptions<NS, VariantsUnion<_ED> & BrandedEvent, SD, A, E1, ES, EF>): Machine<State, Event, R, _SD, _ED, SD>;
+  /** Multiple states, explicit onSuccess */
+  task<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>, A, E1, ES extends VariantsUnion<_ED> & BrandedEvent, EF extends VariantsUnion<_ED> & BrandedEvent>(states: NS, run: (ctx: StateHandlerContext<NS[number] extends TaggedOrConstructor<infer S> ? S : never, VariantsUnion<_ED> & BrandedEvent, SD>) => Effect.Effect<A, E1, Scope.Scope>, options: TaskOptions<NS[number] extends TaggedOrConstructor<infer S> ? S : never, VariantsUnion<_ED> & BrandedEvent, SD, A, E1, ES, EF>): Machine<State, Event, R, _SD, _ED, SD>;
   /**
    * State timeout — gen_statem's `state_timeout`.
    *
@@ -271,28 +277,20 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
    *   })
    * ```
    */
-  timeout<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, config: TimeoutConfig<NS, VariantsUnion<_ED> & BrandedEvent>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  timeout<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, config: TimeoutConfig<NS, VariantsUnion<_ED> & BrandedEvent>): Machine<State, Event, R, _SD, _ED, SD>;
   /**
    * 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)))
-   *       ),
-   *   });
+   * machine.background(({ 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>;
+  background(handler: StateEffectHandler<State, Event, SD, Scope.Scope>): Machine<State, Event, R, _SD, _ED, SD>;
   /**
    * Postpone events — gen_statem's event postpone.
    *
@@ -310,54 +308,64 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
    *   .postpone(State.Connecting, [Event.Data, Event.Cmd]) // multiple events
    * ```
    */
-  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>;
+  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, SD>;
+  final<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>): Machine<State, Event, R, _SD, _ED, SD>;
+  static make<SD extends Record<string, Schema.Struct.Fields>, ED extends Record<string, Schema.Struct.Fields>, S extends BrandedState, E extends BrandedEvent, SLD extends SlotsDef = Record<string, never>>(config: MakeConfig<SD, ED, S, E, SLD>): Machine<S, E, never, SD, ED, SLD>;
 }
-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> {
+declare class TransitionScope<State, Event, R, _SD extends Record<string, Schema.Struct.Fields>, _ED extends Record<string, Schema.Struct.Fields>, SD extends SlotsDef, SelectedState extends VariantsUnion<_SD> & BrandedState> {
   private readonly machine;
   private readonly states;
-  constructor(machine: Machine<State, Event, R, _SD, _ED, GD, EFD>, states: ReadonlyArray<TaggedOrConstructor<SelectedState>>);
-  on<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>;
-  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>;
+  constructor(machine: Machine<State, Event, R, _SD, _ED, SD>, states: ReadonlyArray<TaggedOrConstructor<SelectedState>>);
+  on<NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(event: TaggedOrConstructor<NE>, handler: TransitionHandler<SelectedState, NE, RS, SD, never, ExtractReply<NE>>): TransitionScope<State, Event, R, _SD, _ED, SD, SelectedState>;
+  reenter<NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(event: TaggedOrConstructor<NE>, handler: TransitionHandler<SelectedState, NE, RS, SD, never, ExtractReply<NE>>): TransitionScope<State, Event, R, _SD, _ED, SD, SelectedState>;
 }
 declare const make: typeof 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.
+ * For machines with slots, pass implementations via `{ slots: { ... } }`.
  *
- * Persistence is composed in userland by observing `actor.changes`
- * and saving snapshots to your own storage.
+ * @example
+ * ```ts
+ * // No slots
+ * const actor = yield* Machine.spawn(machine);
+ *
+ * // With slots
+ * const actor = yield* Machine.spawn(machine, {
+ *   slots: { canRetry: ({ max }) => attempts < max },
+ * });
+ *
+ * // With persistence
+ * const actor = yield* Machine.spawn(machine, {
+ *   persist: {
+ *     load: () => storage.get("actor-state"),
+ *     save: (state) => storage.set("actor-state", state),
+ *   },
+ * });
+ * ```
  */
 declare const spawn: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R>(machine: BuiltMachine<S, E, R>, idOrOptions?: string | {
+}, R, SD extends SlotsDef = Record<string, never>>(machine: Machine<S, E, R, any, any, SD>, options?: string | {
   id?: string;
   hydrate?: S;
+  slots?: ProvideSlots<SD, any>;
+  supervision?: Supervision.Policy;
+  persist?: PersistConfig<S>;
 }) => 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?: {
-  from?: S;
-}) => Effect.Effect<S, never, R>;
+declare const replay: {
+  <S extends {
+    readonly _tag: string;
+  }, E extends {
+    readonly _tag: string;
+  }, R, SD extends SlotsDef = Record<string, never>>(machine: Machine<S, E, R, any, any, SD>, events: ReadonlyArray<E>, options?: {
+    from?: S;
+    slots?: ProvideSlots<SD, any>;
+  }): Effect.Effect<S, never, R>;
+};
 declare const reply: <State, Reply>(state: State, reply: Reply) => ReplyResult<State, Reply>;
 declare const deferReply: <State>(state: State) => DeferReplyResult<State>;
 //#endregion
-export { BackgroundEffect, BuiltMachine, type DeferReplyResult, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, type ReplyResult, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, machine_d_exports, make, replay, reply, spawn };
+export { BackgroundEffect, type DeferReplyResult, HandlerContext, Machine, MachineRef, MakeConfig, PersistConfig, type ReplyResult, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, machine_d_exports, make, materializeMachine, replay, reply, spawn };