@typeonce/effect-machine 0.12.0 → 0.13.0

package/src/Machine.ts

@@ -7,6 +7,7 @@
 import type * as Cause from "effect/Cause"
 import type * as Duration from "effect/Duration"
 import type * as Effect from "effect/Effect"
+import type * as Exit from "effect/Exit"
 import type * as Option from "effect/Option"
 import type { Pipeable } from "effect/Pipeable"
 import { hasProperty } from "effect/Predicate"
@@ -840,6 +841,42 @@ type NodeMethod<
 > = Machine.NodeSchema<Node> extends never ? FromMethod<FromArguments, Result>
   : ((...args: Arguments) => Result) & FromMethod<FromArguments, Result>
 
+type NodeMethodWithInitial<
+  Node,
+  Arguments extends ReadonlyArray<unknown>,
+  Result,
+  FromArguments extends ReadonlyArray<unknown>,
+  Path extends string
+> = Machine.NodeSchema<Node> extends never ? {
+    readonly from: FromCallable<FromArguments, Machine.StateConstruction<Result>>
+    readonly initial: InitialTargetFactory<Node, Path>
+  }
+  :
+    & ((...args: Arguments) => Result)
+    & {
+      readonly from: FromCallable<FromArguments, Machine.StateConstruction<Result>>
+      readonly initial: InitialTargetFactory<Node, Path>
+    }
+
+interface InitialTargetMethod<
+  Node,
+  Path extends string
+> {
+  /** Enters this state through its declared initial configuration. */
+  readonly initial: InitialTargetFactory<Node, Path>
+}
+
+interface InitialTargetFactory<
+  Node,
+  Path extends string
+> {
+  (...args: WithNodeValue<Node, readonly []>): Machine.InitialTarget<Path>
+  readonly from: FromCallable<
+    WithNodeInput<Node, readonly []>,
+    Machine.StateConstruction<Machine.InitialTarget<Path>>
+  >
+}
+
 type NodeConstructionSelectorFromCallable<Node, Builder, Result> = Machine.NodeSchema<Node> extends never ? {
     <Selected extends ConstructionResult<Result>>(
       state: (builder: Builder) => Selected
@@ -847,15 +884,19 @@ type NodeConstructionSelectorFromCallable<Node, Builder, Result> = Machine.NodeS
   }
   : ConstructionSelectorFromCallable<NodeMakeInput<Node>, Builder, Result>
 
-type NestedTargetMethod<Node, Builder, Result> = Machine.NodeSchema<Node> extends never ? {
+type NestedTargetMethod<Node, Builder, Result, Path extends string> = Machine.NodeSchema<Node> extends never ? {
     readonly from: NodeConstructionSelectorFromCallable<Node, Builder, Result>
+    readonly initial: InitialTargetFactory<Node, Path>
   }
   :
     & (<Selected extends ConstructionResult<Result>>(
       value: NodeValue<Node>,
       state: (builder: Builder) => Selected
     ) => Selected)
-    & { readonly from: NodeConstructionSelectorFromCallable<Node, Builder, Result> }
+    & {
+      readonly from: NodeConstructionSelectorFromCallable<Node, Builder, Result>
+      readonly initial: InitialTargetFactory<Node, Path>
+    }
 
 type ConstructionSelectorFromCallable<Input, Builder, Result> = {} extends Input ? {
     <Selected extends ConstructionResult<Result>>(
@@ -1093,6 +1134,14 @@ type FullSnapshotResult<
   Path extends string = Machine.JoinPath<Prefix, StateId>
 > = Machine.SnapshotByIdentifierWithPath<States, StateId, Path>
 
+type InitialEntryStateKey<States extends Machine.StateSchemas> = {
+  readonly [Key in ActiveStateKey<States>]: States[Key] extends { readonly states: Machine.StateSchemas } ? Key : never
+}[ActiveStateKey<States>]
+
+type FullInitialTargetBuilder<States extends Machine.StateSchemas> = {
+  readonly [Key in InitialEntryStateKey<States>]: InitialTargetMethod<States[Key], Key>
+}
+
 type FullParallelBuilder<
   States extends Machine.StateSchemas,
   Prefix extends string,
@@ -1383,9 +1432,10 @@ type LocalTargetMethod<
     Source extends Path | `${Path}.${string}` ? NestedTargetMethod<
         Node,
         LocalTargetBuilderWithPrefix<AllStates, Children, Path, Source>,
-        LocalTargetResultWithPrefix<AllStates, Children, Path>
+        LocalTargetResultWithPrefix<AllStates, Children, Path>,
+        Path
       >
-    : NodeMethod<
+    : NodeMethodWithInitial<
       Node,
       WithNodeValue<Node, [
         states: (
@@ -1397,12 +1447,14 @@ type LocalTargetMethod<
         states: (
           builder: FullParallelBuilder<Children, Path>
         ) => SnapshotBuilderComplete<Machine.SnapshotRegionsWithPrefix<Children, Path>, boolean>
-      ]>
+      ]>,
+      Path
     >
   : Node extends { readonly states: infer Children extends Machine.StateSchemas } ? NestedTargetMethod<
       Node,
       LocalTargetBuilderWithPrefix<AllStates, Children, Path, Source>,
-      LocalTargetResultWithPrefix<AllStates, Children, Path>
+      LocalTargetResultWithPrefix<AllStates, Children, Path>,
+      Path
     >
   : NodeMethod<
     Node,
@@ -1497,10 +1549,11 @@ type BranchTargetMethod<
         & NestedTargetMethod<
           Node,
           BranchTargetBuilderWithPrefix<AllStates, Children, Path, Source>,
-          BranchTargetResultWithPrefix<AllStates, Children, Path>
+          BranchTargetResultWithPrefix<AllStates, Children, Path>,
+          Path
         >
         & BranchTargetBuilderWithPrefix<AllStates, Children, Path, Source>
-    : NodeMethod<
+    : NodeMethodWithInitial<
       Node,
       WithNodeValue<Node, [
         states: (
@@ -1512,13 +1565,15 @@ type BranchTargetMethod<
         states: (
           builder: FullParallelBuilder<Children, Path>
         ) => SnapshotBuilderComplete<Machine.SnapshotRegionsWithPrefix<Children, Path>, boolean>
-      ]>
+      ]>,
+      Path
     >
   : Node extends { readonly states: infer Children extends Machine.StateSchemas } ?
       & NestedTargetMethod<
         Node,
         BranchTargetBuilderWithPrefix<AllStates, Children, Path, Source>,
-        BranchTargetResultWithPrefix<AllStates, Children, Path>
+        BranchTargetResultWithPrefix<AllStates, Children, Path>,
+        Path
       >
       & BranchTargetBuilderWithPrefix<AllStates, Children, Path, Source>
   : NodeMethod<
@@ -1664,6 +1719,187 @@ export type RuntimeSnapshot<State, Error = never, Output = never> =
     readonly state: State
   }
 
+/**
+ * Live, root-scoped records describing one prepared machine tree.
+ *
+ * Inspection records deliberately erase machine-specific values to `unknown`:
+ * one stream may contain unrelated root, child-machine, and `Logic` protocols.
+ * The record structure remains a closed discriminated union, while typed
+ * application observation continues through `changes` and `emissions`.
+ *
+ * @category models
+ * @since 0.13.0
+ */
+export declare namespace Inspection {
+  /** Read-only identity of a local machine endpoint. */
+  export interface Endpoint {
+    readonly id: string
+    readonly sessionId: string
+  }
+
+  /** Read-only identity of a runtime represented in the inspection tree. */
+  export interface Subject extends Endpoint {
+    readonly kind: "Machine" | "Logic"
+  }
+
+  /** Causal origin of an inspected runtime. */
+  export type Origin =
+    | { readonly _tag: "Root" }
+    | {
+      readonly _tag: "Invoke"
+      readonly ownerPath: string
+      readonly invokeId: string
+    }
+    | {
+      readonly _tag: "Spawn"
+      readonly address: string | undefined
+    }
+
+  /** Causal owner of a send or emission. */
+  export type Causation =
+    | { readonly _tag: "Initialization" }
+    | { readonly _tag: "Macrostep"; readonly macrostepId: number }
+    | { readonly _tag: "Activity"; readonly activitySessionId: string }
+
+  /** Closed command projection safe for observation. */
+  export type Command =
+    | {
+      readonly _tag: "SendTo"
+      readonly target: Endpoint | { readonly id: string }
+      readonly event: unknown
+    }
+    | {
+      readonly _tag: "Stop"
+      readonly target: Endpoint | { readonly id: string }
+    }
+
+  /** One statechart microstep in a committed macrostep. */
+  export interface Microstep {
+    readonly event: unknown
+    readonly transitions: ReadonlyArray<Machine.RetainedTransition>
+    readonly raisedEvents: ReadonlyArray<unknown>
+    readonly emittedEvents: ReadonlyArray<unknown>
+    readonly commands: ReadonlyArray<Command>
+    readonly exitPaths: ReadonlyArray<string>
+    readonly entryPaths: ReadonlyArray<string>
+    readonly changed: boolean
+  }
+
+  /** Common ordering and identity fields for every record. */
+  export interface Base {
+    /** Total publication order within this prepared root. */
+    readonly sequence: number
+    /** Session id of the prepared root that owns this inspection stream. */
+    readonly rootSessionId: string
+    /** Runtime instance described by this record. */
+    readonly subject: Subject
+  }
+
+  /** Announces allocation of a root or owned process identity. */
+  export interface Created extends Base {
+    readonly _tag: "Created"
+    readonly parent: Subject | undefined
+    readonly origin: Origin
+    /** Compiled statechart definition; absent for generic `Logic`. */
+    readonly definition: Machine.Any | undefined
+  }
+
+  /** Announces successful initialization. */
+  export interface Initialized extends Base {
+    readonly _tag: "Initialized"
+    readonly snapshot: RuntimeSnapshot<unknown, unknown, unknown>
+    readonly initialEntryPaths: ReadonlyArray<string>
+    readonly microsteps: ReadonlyArray<Microstep>
+  }
+
+  /** Announces failure before an initial runtime snapshot exists. */
+  export interface StartFailed extends Base {
+    readonly _tag: "StartFailed"
+    readonly cause: Cause.Cause<unknown>
+  }
+
+  /** Announces acceptance of an event by a local mailbox. */
+  export interface EventSent extends Base {
+    readonly _tag: "EventSent"
+    readonly deliveryId: number
+    readonly source: Subject | undefined
+    readonly target: Endpoint
+    readonly event: unknown
+    readonly causedBy: Causation | undefined
+  }
+
+  /** Announces complete processing of one statechart mailbox event. */
+  export interface EventProcessed extends Base {
+    readonly _tag: "EventProcessed"
+    readonly macrostepId: number
+    readonly deliveryId: number
+    readonly source: Subject | undefined
+    readonly event: unknown
+    readonly before: RuntimeSnapshot<unknown, unknown, unknown>
+    readonly after: RuntimeSnapshot<unknown, unknown, unknown>
+    readonly handled: boolean
+    readonly configurationChanged: boolean
+    readonly microsteps: ReadonlyArray<Microstep>
+  }
+
+  /** Announces a direct state update made by generic `Logic`. */
+  export interface StateChanged extends Base {
+    readonly _tag: "StateChanged"
+    readonly before: unknown
+    readonly after: unknown
+    readonly causedByDeliveryId: number | undefined
+  }
+
+  /** Announces actual publication on a machine's domain emission stream. */
+  export interface Emitted extends Base {
+    readonly _tag: "Emitted"
+    readonly emission: unknown
+    readonly causedBy: Causation | undefined
+  }
+
+  /** Identity of one Effect or timer invocation run. */
+  export interface Activity {
+    readonly id: string
+    readonly sessionId: string
+    readonly owner: Subject
+    readonly ownerPath: string
+    readonly kind: "Effect" | "Timer"
+  }
+
+  /** Announces an Effect or timer invocation starting. */
+  export interface ActivityStarted extends Base {
+    readonly _tag: "ActivityStarted"
+    readonly activity: Activity
+  }
+
+  /** Announces an Effect or timer invocation outcome. */
+  export interface ActivityStopped extends Base {
+    readonly _tag: "ActivityStopped"
+    readonly activity: Activity
+    /** Success or failure from the invoke; interruption means its owner stopped it. */
+    readonly exit: Exit.Exit<unknown, unknown>
+  }
+
+  /** Announces a terminal local runtime snapshot. */
+  export interface Terminated extends Base {
+    readonly _tag: "Terminated"
+    readonly snapshot: RuntimeSnapshot<unknown, unknown, unknown>
+  }
+
+  /** Complete live inspection protocol. */
+  export type Event =
+    | Created
+    | Initialized
+    | StartFailed
+    | EventSent
+    | EventProcessed
+    | StateChanged
+    | Emitted
+    | ActivityStarted
+    | ActivityStopped
+    | Terminated
+}
+
 /**
  * Represents a classified terminal outcome derived from a runtime snapshot.
  *
@@ -1726,6 +1962,14 @@ export interface Prepared<out State, in Event, out Error, out Output, out Emitte
   /** Streams ephemeral notifications published after subscription. */
   readonly emissions: Stream.Stream<Emitted>
 
+  /**
+   * Streams ordered operational records for this root and every locally owned
+   * descendant. The stream is hot, non-replayed, never fails, and completes
+   * after the prepared root terminates. Subscribe before evaluating `start` to
+   * observe initialization.
+   */
+  readonly inspection: Stream.Stream<Inspection.Event>
+
   /** Initializes this machine once and returns its running reference. */
   readonly start: Effect.Effect<MachineRef<State, Event, Error, Output, Emitted>, StartError, StartRequirements>
 }
@@ -3843,6 +4087,23 @@ export declare namespace Machine {
     readonly parent: Extract<ParentPath<HistoryId>, StateIdentifier<States>>
   }
 
+  /**
+   * Transition instruction that enters a compound or parallel state through
+   * its declared initial configuration.
+   *
+   * @category models
+   * @since 0.13.0
+   */
+  export interface InitialTarget<StateId extends string> {
+    readonly [Topology.TargetTypeId]: typeof Topology.TargetTypeId
+    readonly [Topology.TargetSnapshotTypeId]?: never
+    readonly [Topology.InitialTargetTypeId]: typeof Topology.InitialTargetTypeId
+    readonly _tag: "InitialTarget"
+    readonly path: StateId
+    readonly value: never
+    readonly values?: never
+  }
+
   /** Branded transient target instruction used while constructing initial states. */
   export interface ChoiceTargetInstruction<ChoiceId extends string = string> {
     readonly [Topology.ChoiceTargetTypeId]: typeof Topology.ChoiceTargetTypeId
@@ -3873,7 +4134,9 @@ export declare namespace Machine {
    * @category utility types
    * @since 0.4.0
    */
-  export type FullTargetBuilder<States extends StateSchemas> = FullSnapshotBuilderWithPrefix<States>
+  export type FullTargetBuilder<States extends StateSchemas> = [InitialEntryStateKey<States>] extends [never] ?
+    FullSnapshotBuilderWithPrefix<States>
+    : FullSnapshotBuilderWithPrefix<States> & FullInitialTargetBuilder<States>
 
   /**
    * Builder for a complete fallback configuration containing a history owner.
@@ -4376,8 +4639,8 @@ export declare namespace Machine {
     ? NonNullable<Config[Key]> extends (...args: any) => infer Ret ? Ret : never
     : never
   /** Extracts the return value from an implicit initial child implementation. */
-  export type StateInitialReturn<Config> = Config extends { readonly initial?: infer Initial }
-    ? NonNullable<Initial> extends (...args: any) => infer Ret ? Ret : never
+  export type StateInitializeReturn<Config> = Config extends { readonly initialize?: infer Initialize }
+    ? NonNullable<Initialize> extends (...args: any) => infer Ret ? Ret : never
     : never
   /** Extracts the return values from a state's history defaults. */
   export type HistoryDefaultReturn<Config> = Config extends { readonly history?: infer History } ? {
@@ -4434,6 +4697,8 @@ export declare namespace Machine {
    */
   export type InvokeResolvedSource<Source> = Source extends (...args: any) => infer Resolved ? Resolved : Source
 
+  type InvokeFactoryResult<Source> = Source extends (...args: any) => infer Resolved ? Resolved : never
+
   type ChildMachineLogic<Child> = Child extends ChildMachine<string, infer M> ? Logic<
       Snapshot<States<M>>,
       EventInput<InputEvent<M>>,
@@ -4455,7 +4720,7 @@ export declare namespace Machine {
     : never
 
   export type InvokeLogic<Invoke> = Invoke extends { readonly effect: infer Source } ?
-    InvokeResolvedSource<Source> extends infer Fx extends Effect.Effect<any, any, any> ? Logic<
+    InvokeFactoryResult<Source> extends infer Fx extends Effect.Effect<any, any, any> ? Logic<
         void,
         never,
         Effect.Error<Fx>,
@@ -4600,7 +4865,6 @@ export declare namespace Machine {
     | Effect.Services<DoneReturn<Config>>
     | Effect.Services<StateActionReturn<Config, "entry">>
     | Effect.Services<StateActionReturn<Config, "exit">>
-    | Effect.Services<StateInitialReturn<Config>>
     | Effect.Services<HistoryDefaultReturn<Config>>
     | Effect.Services<ChoiceReturn<Config>>
     | InvokeRequirements<Config>
@@ -4611,12 +4875,12 @@ export declare namespace Machine {
     Emits extends ReadonlyArray<TaggedSchema>,
     Context
   > =
-    | ((context: Context, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => HandlerResult<States, any, any>)
+    | ((context: NoInfer<Context>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => HandlerResult<States, any, any>)
     | {
       readonly reenter?: boolean
       readonly targets?: ReadonlyArray<StateNodeIdentifier<States>>
       readonly transition: (
-        context: Context,
+        context: NoInfer<Context>,
         enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>
       ) => HandlerResult<States, any, any>
     }
@@ -4662,10 +4926,9 @@ export declare namespace Machine {
     & (
       | {
         readonly id: string
-        readonly effect: InvokeSource<
-          Effect.Effect<any, any, any>,
-          InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
-        >
+        readonly effect: (
+          context: InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
+        ) => Effect.Effect<any, any, any>
         readonly after?: never
         readonly logic?: never
         readonly child?: never
@@ -4749,60 +5012,6 @@ export declare namespace Machine {
     : { readonly onFailure?: never }
     : never
 
-  export type EffectInvokeArgs<
-    States extends StateSchemas,
-    Events extends ReadonlyArray<TaggedSchema>,
-    Emits extends ReadonlyArray<TaggedSchema>,
-    StateId extends StateIdentifier<States>,
-    Fx extends Effect.Effect<any, any, any>,
-    Source = Fx,
-    InputEvents extends ReadonlyArray<TaggedSchema> = Events,
-    ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
-  > =
-    & {
-      readonly id: InvokeLifecycleId
-      readonly effect: Source
-      readonly after?: never
-      readonly logic?: never
-      readonly child?: never
-      readonly address?: never
-      readonly onSnapshot?: never
-    }
-    & InvokeDoneRequirement<
-      Effect.Success<NoInfer<Fx>>,
-      InvokeTransition<
-        States,
-        Events,
-        Emits,
-        InvokeDoneContext<
-          States,
-          Events,
-          Emits,
-          StateId,
-          Effect.Success<NoInfer<Fx>>,
-          InputEvents,
-          ParentEvents
-        >
-      >
-    >
-    & InvokeFailureRequirement<
-      Effect.Error<NoInfer<Fx>>,
-      InvokeTransition<
-        States,
-        Events,
-        Emits,
-        InvokeFailureContext<
-          States,
-          Events,
-          Emits,
-          StateId,
-          Effect.Error<NoInfer<Fx>>,
-          InputEvents,
-          ParentEvents
-        >
-      >
-    >
-
   export type TimerInvokeArgs<
     States extends StateSchemas,
     Events extends ReadonlyArray<TaggedSchema>,
@@ -4988,7 +5197,7 @@ export declare namespace Machine {
     Raw
   > = Raw extends InvokeTyped<any, any, any, any, any> ? unknown
     : Raw extends { readonly effect: infer Source } ?
-      InvokeResolvedSource<Source> extends infer Fx extends Effect.Effect<any, any, any> ?
+      InvokeFactoryResult<Source> extends infer Fx extends Effect.Effect<any, any, any> ?
           & InvokeDoneRequirement<
             Effect.Success<Fx>,
             InvokeTransition<
@@ -5255,11 +5464,16 @@ export declare namespace Machine {
           ) => HandlerResult<States, any, any>
         }
     }
-    readonly initial?: StateInitialHandler<States, Events, Emits, StateId, InputEvents, ParentEvents>
+    readonly initialize?: StateInitializeHandler<States, Events, Emits, StateId, InputEvents, ParentEvents>
   } & ActiveOutputHandlerConfig<States, Events, StateId>
 
-  /** Values supplied when a statechart implicitly enters a state's initial children. */
-  export type StateInitialValue<
+  /**
+   * Values constructed for a state's schema-valued direct initial children.
+   *
+   * @category utility types
+   * @since 0.13.0
+   */
+  export type StateInitializeValue<
     States extends StateSchemas,
     StateId extends StateIdentifier<States>
   > = NodeByIdentifier<States, StateId> extends infer Node ?
@@ -5270,23 +5484,92 @@ export declare namespace Machine {
       }
     : Node extends { readonly states: infer Children extends StateSchemas; readonly initial: infer Initial } ?
       Initial extends ActiveStateKey<Children> ? NodeSchema<Children[Initial]> extends never ? never
-        : NodeValue<Children[Initial]>
+        : { readonly [Key in Initial]: NodeValue<Children[Initial]> }
       : never
     : never
     : never
 
-  /** Context passed to an implicit child-state initializer. */
-  export type StateInitialContext<
+  type StateInitializeCompoundBuilder<Node, Initial extends PropertyKey> = Node extends {
+    readonly states: infer Children extends StateSchemas
+  } ? Initial extends ActiveStateKey<Children> ? NodeSchema<Children[Initial]> extends never ? never
+      : NodeBuilderMethod<
+        Children[Initial],
+        readonly [value: NodeValue<Children[Initial]>],
+        SnapshotBuilderComplete<{ readonly [Key in Initial]: NodeValue<Children[Initial]> }>,
+        readonly [input: NodeMakeInput<Children[Initial]>],
+        SnapshotBuilderComplete<{ readonly [Key in Initial]: NodeValue<Children[Initial]> }, true>
+      >
+    : never
+    : never
+
+  type StateInitializeParallelBuilder<
+    Children extends StateSchemas,
+    Remaining extends ActiveStateKey<Children> = {
+      readonly [Key in ActiveStateKey<Children>]: NodeSchema<Children[Key]> extends never ? never : Key
+    }[ActiveStateKey<Children>],
+    Values = {},
+    Constructed extends boolean = false
+  > =
+    & SnapshotBuilderComplete<Values, Constructed>
+    & {
+      readonly [Key in Remaining]: NodeBuilderMethod<
+        Children[Key],
+        readonly [value: NodeValue<Children[Key]>],
+        StateInitializeParallelBuilder<
+          Children,
+          Exclude<Remaining, Key>,
+          Values & { readonly [Region in Key]: NodeValue<Children[Key]> },
+          Constructed
+        >,
+        readonly [input: NodeMakeInput<Children[Key]>],
+        StateInitializeParallelBuilder<
+          Children,
+          Exclude<Remaining, Key>,
+          Values & { readonly [Region in Key]: NodeValue<Children[Key]> },
+          true
+        >
+      >
+    }
+
+  /**
+   * Builder bound to the direct initial child or regions owned by a state.
+   *
+   * @category utility types
+   * @since 0.13.0
+   */
+  export type StateInitializeBuilder<
+    States extends StateSchemas,
+    StateId extends StateIdentifier<States>,
+    Node = NodeByIdentifier<States, StateId>
+  > = Node extends { readonly type: "parallel"; readonly states: infer Children extends StateSchemas } ?
+    StateInitializeParallelBuilder<Children>
+    : Node extends { readonly initial: infer Initial } ? StateInitializeCompoundBuilder<Node, Initial & PropertyKey>
+    : never
+
+  /**
+   * Context passed to an implicit child-state initializer.
+   *
+   * @category models
+   * @since 0.13.0
+   */
+  export type StateInitializeContext<
     States extends StateSchemas,
     Events extends ReadonlyArray<TaggedSchema>,
     Emits extends ReadonlyArray<TaggedSchema>,
     StateId extends StateIdentifier<States>,
     InputEvents extends ReadonlyArray<TaggedSchema> = Events,
     ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
-  > = StateActionContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
+  > = StateActionContext<States, Events, Emits, StateId, InputEvents, ParentEvents> & {
+    readonly builder: StateInitializeBuilder<States, StateId>
+  }
 
-  /** Initial child value implementation for a compound or parallel state. */
-  export type StateInitialHandler<
+  /**
+   * Initial child value implementation for a compound or parallel state.
+   *
+   * @category models
+   * @since 0.13.0
+   */
+  export type StateInitializeHandler<
     States extends StateSchemas,
     Events extends ReadonlyArray<TaggedSchema>,
     Emits extends ReadonlyArray<TaggedSchema>,
@@ -5294,9 +5577,9 @@ export declare namespace Machine {
     InputEvents extends ReadonlyArray<TaggedSchema> = Events,
     ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
   > = (
-    context: StateInitialContext<States, Events, Emits, StateId, InputEvents, ParentEvents>,
+    context: StateInitializeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>,
     enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>
-  ) => StateInitialValue<States, StateId>
+  ) => SnapshotBuilderComplete<StateInitializeValue<States, StateId>, boolean>
 
   /** Context used only when a history node has no previously captured record. */
   export interface HistoryDefaultContext<
@@ -5366,7 +5649,7 @@ export declare namespace Machine {
     readonly on?: never
     readonly onDone?: never
     readonly output?: never
-    readonly initial?: never
+    readonly initialize?: never
   }
 
   /**
@@ -5589,7 +5872,7 @@ export declare namespace Machine {
     | "entry"
     | "exit"
     | "history"
-    | "initial"
+    | "initialize"
     | "invoke"
     | "on"
     | "onDone"
@@ -5702,6 +5985,75 @@ export declare namespace Machine {
     : Result extends { readonly path: infer Path extends string } ? Path
     : never
 
+  type TransitionResultInitialTargetPath<Result> = IsAny<Result> extends true ? never
+    : Result extends Effect.Effect<infer Success, any, any> ? TransitionResultInitialTargetPath<Success>
+    : Result extends StateConstruction<infer Constructed> ? TransitionResultInitialTargetPath<Constructed>
+    : Result extends {
+      readonly [Topology.InitialTargetTypeId]: typeof Topology.InitialTargetTypeId
+      readonly _tag: "InitialTarget"
+    } ? Result extends { readonly path: infer Path extends string } ? Path : never
+    : never
+
+  type HandlerConfigInitialTargetPath<Config> = TransitionResultInitialTargetPath<
+    | EventHandlerReturn<Config>
+    | AlwaysReturn<Config>
+    | DoneReturn<Config>
+    | ChoiceReturn<Config>
+    | InvokeOutcomeReturn<InvokeReturn<Config>>
+  >
+
+  type RequiredInitializersForTargetPath<
+    AllStates extends StateSchemas,
+    Path
+  > = string extends Path ? never : Path extends StateIdentifier<AllStates> ? InitializerClosureForNode<
+      AllStates,
+      NodeByIdentifier<AllStates, Path>,
+      Path
+    >
+  : never
+
+  type HandlerInitializeValidationAtPath<Config, Path extends string> = HandlerConfigAtPath<Config, Path> extends
+    infer StateConfig ? [StateConfig] extends [never] ? HandlerValidationAtPath<Path, {
+        readonly initialize: HandlerValidationError<
+          "State requires initialize because a transition enters its declared initial configuration",
+          Path
+        >
+      }>
+    : "initialize" extends keyof StateConfig ? never
+    : HandlerValidationAtPath<Path, {
+      readonly initialize: HandlerValidationError<
+        "State requires initialize because a transition enters its declared initial configuration",
+        Path
+      >
+    }>
+    : never
+
+  type HandlerInitialTargetValidationForPaths<
+    AllStates extends StateSchemas,
+    Config,
+    Required
+  > = Types.UnionToIntersection<
+    Required extends string ? HandlerInitializeValidationAtPath<Config, Required> : unknown
+  >
+
+  type HandlerTreeInitialTargetPath<Config> = string extends keyof Config ? never
+    : Config extends object ? {
+        readonly [Key in keyof Config]:
+          | HandlerConfigInitialTargetPath<HandlerConfigPart<Config[Key]>>
+          | (Config[Key] extends { readonly states: infer Children } ? HandlerTreeInitialTargetPath<Children> : never)
+      }[keyof Config]
+    : never
+
+  type HandlerInitialTargetValidation<
+    AllStates extends StateSchemas,
+    Config
+  > = HandlerTreeInitialTargetPath<Config> extends infer TargetPath ? HandlerInitialTargetValidationForPaths<
+      AllStates,
+      Config,
+      RequiredInitializersForTargetPath<AllStates, TargetPath>
+    >
+    : unknown
+
   type DeclaredTransitionTarget<Transition> = Transition extends {
     readonly targets: infer Targets extends ReadonlyArray<string>
   } ? Targets[number]
@@ -5809,6 +6161,19 @@ export declare namespace Machine {
       : unknown
       : unknown)
 
+  type HandlerRequiredHistoryInitializeValidation<
+    AllStates extends StateSchemas,
+    StateId extends StateIdentifier<AllStates>,
+    Config
+  > = [HistoryIdentifier<AllStates>] extends [never] ? unknown
+    : StateId extends RequiredHistoryInitializers<AllStates> ? "initialize" extends keyof Config ? unknown : {
+        readonly initialize: HandlerValidationError<
+          "State requires initialize for shallow history restoration",
+          StateId
+        >
+      }
+    : unknown
+
   type HandlerNodeValidation<
     AllStates extends StateSchemas,
     Node,
@@ -5831,6 +6196,7 @@ export declare namespace Machine {
         & HandlerInvokeParentEventsValidation<InputEvents, StateId, Config>
         & HandlerChildrenValidation<Node, StateId, Config>
         & HandlerOutputRequirementValidation<AllStates, StateId, AvailableOutputStates, Config>
+        & HandlerRequiredHistoryInitializeValidation<AllStates, StateId, Config>
         & HandlerRuntimeValidation<Events, Emits, StateId, Config>
     : unknown
 
@@ -5944,7 +6310,7 @@ export declare namespace Machine {
     AllStates extends StateSchemas,
     StateId extends StateIdentifier<AllStates>,
     Config
-  > = StateId extends RequiredHistoryInitializers<AllStates> ? "initial" extends keyof Config ? true : false : true
+  > = StateId extends RequiredHistoryInitializers<AllStates> ? "initialize" extends keyof Config ? true : false : true
 
   type HandlerHasRequiredHistoryDefaults<Node, Config> = Node extends {
     readonly states: infer Children extends StateSchemas
@@ -5984,7 +6350,6 @@ export declare namespace Machine {
     | Effect.Error<DoneReturn<Config>>
     | Effect.Error<StateActionReturn<Config, "entry">>
     | Effect.Error<StateActionReturn<Config, "exit">>
-    | Effect.Error<StateInitialReturn<Config>>
     | Effect.Error<HistoryDefaultReturn<Config>>
     | Effect.Error<ChoiceReturn<Config>>
     | InvokeError<Config>
@@ -6107,6 +6472,11 @@ export declare namespace Machine {
             StateIdentifier<States>
           >
         >
+        & ([StateIdentifier<States>] extends [UnhandledStates] ? HandlerInitialTargetValidation<
+            States,
+            NoInfer<Config>
+          >
+          : unknown)
     ): HandleTreeResult<
       States,
       Events,
@@ -6728,7 +7098,7 @@ export const decodeSnapshot: <
   Machine.SnapshotDecodingServices<States>
 > = internal.decodeSnapshot as any
 
-type DynamicEffectInvokeSource<
+type EffectInvokeSource<
   States extends Machine.StateSchemas,
   Events extends ReadonlyArray<Machine.TaggedSchema>,
   Emits extends ReadonlyArray<Machine.TaggedSchema>,
@@ -6746,7 +7116,7 @@ type DynamicEffectInvokeSource<
   readonly onSnapshot?: never
 }
 
-type DynamicEffectDoneHandler<
+type EffectDoneHandler<
   States extends Machine.StateSchemas,
   Events extends ReadonlyArray<Machine.TaggedSchema>,
   Emits extends ReadonlyArray<Machine.TaggedSchema>,
@@ -6767,7 +7137,7 @@ type DynamicEffectDoneHandler<
   >
 >
 
-type DynamicEffectFailureHandler<
+type EffectFailureHandler<
   States extends Machine.StateSchemas,
   Events extends ReadonlyArray<Machine.TaggedSchema>,
   Emits extends ReadonlyArray<Machine.TaggedSchema>,
@@ -6788,7 +7158,7 @@ type DynamicEffectFailureHandler<
   >
 >
 
-type DynamicEffectInvokeResult<
+type EffectInvokeResult<
   States extends Machine.StateSchemas,
   Events extends ReadonlyArray<Machine.TaggedSchema>,
   Emits extends ReadonlyArray<Machine.TaggedSchema>,
@@ -6805,7 +7175,7 @@ type DynamicEffectInvokeResult<
 
 type InvokeChannelIsNever<Value> = IsAny<Value> extends true ? false : [Value] extends [never] ? true : false
 
-type BoundDynamicEffectInvokeSource<
+type BoundEffectInvokeSource<
   States extends Machine.StateSchemas,
   Events extends ReadonlyArray<Machine.TaggedSchema>,
   Emits extends ReadonlyArray<Machine.TaggedSchema>,
@@ -6825,7 +7195,7 @@ type BoundDynamicEffectInvokeSource<
   readonly onSnapshot?: never
 }
 
-type BoundDynamicEffectDoneHandler<
+type BoundEffectDoneHandler<
   States extends Machine.StateSchemas,
   Events extends ReadonlyArray<Machine.TaggedSchema>,
   Emits extends ReadonlyArray<Machine.TaggedSchema>,
@@ -6848,7 +7218,7 @@ type BoundDynamicEffectDoneHandler<
   >
 >
 
-type BoundDynamicEffectFailureHandler<
+type BoundEffectFailureHandler<
   States extends Machine.StateSchemas,
   Events extends ReadonlyArray<Machine.TaggedSchema>,
   Emits extends ReadonlyArray<Machine.TaggedSchema>,
@@ -6871,7 +7241,7 @@ type BoundDynamicEffectFailureHandler<
   >
 >
 
-type BoundDynamicEffectInvokeResult<
+type BoundEffectInvokeResult<
   States extends Machine.StateSchemas,
   Events extends ReadonlyArray<Machine.TaggedSchema>,
   Emits extends ReadonlyArray<Machine.TaggedSchema>,
@@ -6909,9 +7279,9 @@ export interface Invoker<
     ) => Effect.Effect<unknown, unknown, unknown>
   >(
     config:
-      & BoundDynamicEffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
+      & BoundEffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
       & {
-        readonly onDone: BoundDynamicEffectDoneHandler<
+        readonly onDone: BoundEffectDoneHandler<
           States,
           Events,
           Emits,
@@ -6920,7 +7290,7 @@ export interface Invoker<
           StateId,
           Source
         >
-        readonly onFailure: BoundDynamicEffectFailureHandler<
+        readonly onFailure: BoundEffectFailureHandler<
           States,
           Events,
           Emits,
@@ -6937,7 +7307,7 @@ export interface Invoker<
           "onFailure must be omitted when the Effect error is never"
         ]
       : []
-  ): BoundDynamicEffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
+  ): BoundEffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
   <
     StateId extends Machine.StateIdentifier<States>,
     const Source extends (
@@ -6945,9 +7315,9 @@ export interface Invoker<
     ) => Effect.Effect<unknown, never, unknown>
   >(
     config:
-      & BoundDynamicEffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
+      & BoundEffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
       & {
-        readonly onDone: BoundDynamicEffectDoneHandler<
+        readonly onDone: BoundEffectDoneHandler<
           States,
           Events,
           Emits,
@@ -6962,7 +7332,7 @@ export interface Invoker<
         "onDone must be omitted when the Effect output is never"
       ]
       : []
-  ): BoundDynamicEffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
+  ): BoundEffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
   <
     StateId extends Machine.StateIdentifier<States>,
     const Source extends (
@@ -6970,10 +7340,10 @@ export interface Invoker<
     ) => Effect.Effect<never, unknown, unknown>
   >(
     config:
-      & BoundDynamicEffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
+      & BoundEffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
       & {
         readonly onDone?: never
-        readonly onFailure: BoundDynamicEffectFailureHandler<
+        readonly onFailure: BoundEffectFailureHandler<
           States,
           Events,
           Emits,
@@ -6987,7 +7357,7 @@ export interface Invoker<
         "onFailure must be omitted when the Effect error is never"
       ]
       : []
-  ): BoundDynamicEffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
+  ): BoundEffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
   <
     StateId extends Machine.StateIdentifier<States>,
     const Source extends (
@@ -6995,33 +7365,12 @@ export interface Invoker<
     ) => Effect.Effect<never, never, unknown>
   >(
     config:
-      & BoundDynamicEffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
+      & BoundEffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
       & {
         readonly onDone?: never
         readonly onFailure?: never
       }
-  ): BoundDynamicEffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
-  <
-    StateId extends Machine.StateIdentifier<States>,
-    const Fx extends Effect.Effect<any, any, any>,
-    const Config extends object
-  >(
-    config:
-      & Config
-      & Machine.EffectInvokeArgs<
-        States,
-        Events,
-        Emits,
-        StateId,
-        Fx,
-        Fx,
-        InputEvents,
-        ParentEvents
-      >
-  ):
-    & Config
-    & Machine.InvokeOwned<States, Events, Emits, StateId>
-    & Machine.InvokeTyped<Effect.Success<Fx>, Effect.Error<Fx>, Effect.Services<Fx>, never>
+  ): BoundEffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
   <StateId extends Machine.StateIdentifier<States>, const Config extends object>(
     config: Config & Machine.TimerInvokeArgs<States, Events, Emits, StateId, InputEvents, ParentEvents>
   ): Config & Machine.InvokeOwned<States, Events, Emits, StateId> & Machine.InvokeTyped<void, never, never, never>
@@ -7133,12 +7482,13 @@ export interface Invoker<
  * is required only when the source has a typed failure channel.
  *
  * This constructor is an identity at runtime, but preserves lifecycle callback
- * inference through published declarations. Effects and durations may be
- * supplied directly or derived from the owning state's entry context. Dynamic
- * Effect sources infer the owner context, output, error, and service channels
- * together without a return annotation. Logic invocations require both a
- * lifecycle `id` and a typed communication `address`. Child descriptors already
- * own their identity, so `id` and `address` must not be repeated.
+ * inference through published declarations. Effect factories run when their
+ * owning state is entered and infer the owner context, output, error, and
+ * service channels together without a return annotation. Durations may be
+ * supplied directly or derived from the owning state's entry context. Logic
+ * invocations require both a lifecycle `id` and a typed communication
+ * `address`. Child descriptors already own their identity, so `id` and
+ * `address` must not be repeated.
  *
  * Owner references are intentionally non-sendable here because this standalone
  * constructor does not know the owning definition. When a callback sends to
@@ -7149,10 +7499,11 @@ export interface Invoker<
  * ```ts
  * invoke: Machine.invoke({
  *   id: "load",
- *   effect: Effect.tryPromise({
- *     try: () => fetch("/api/data").then((response) => response.json()),
- *     catch: (cause) => new LoadError({ cause })
- *   }),
+ *   effect: () =>
+ *     Effect.tryPromise({
+ *       try: () => fetch("/api/data").then((response) => response.json()),
+ *       catch: (cause) => new LoadError({ cause })
+ *     }),
  *   onDone: ({ output, target }) => target.full.Ready({ data: output }),
  *   onFailure: ({ error, target }) => target.full.Failed({ error })
  * })
@@ -7172,10 +7523,10 @@ export const invoke: {
     ) => Effect.Effect<unknown, unknown, unknown>
   >(
     config:
-      & DynamicEffectInvokeSource<States, Events, Emits, StateId, Source>
+      & EffectInvokeSource<States, Events, Emits, StateId, Source>
       & {
-        readonly onDone: DynamicEffectDoneHandler<States, Events, Emits, StateId, Source>
-        readonly onFailure: DynamicEffectFailureHandler<States, Events, Emits, StateId, Source>
+        readonly onDone: EffectDoneHandler<States, Events, Emits, StateId, Source>
+        readonly onFailure: EffectFailureHandler<States, Events, Emits, StateId, Source>
       },
     ..._validation: InvokeChannelIsNever<Effect.Success<ReturnType<Source>>> extends true ? [
         "onDone must be omitted when the Effect output is never"
@@ -7184,7 +7535,7 @@ export const invoke: {
           "onFailure must be omitted when the Effect error is never"
         ]
       : []
-  ): DynamicEffectInvokeResult<States, Events, Emits, StateId, Source>
+  ): EffectInvokeResult<States, Events, Emits, StateId, Source>
   <
     const States extends Machine.StateSchemas,
     const Events extends ReadonlyArray<Machine.TaggedSchema>,
@@ -7195,16 +7546,16 @@ export const invoke: {
     ) => Effect.Effect<unknown, never, unknown>
   >(
     config:
-      & DynamicEffectInvokeSource<States, Events, Emits, StateId, Source>
+      & EffectInvokeSource<States, Events, Emits, StateId, Source>
       & {
-        readonly onDone: DynamicEffectDoneHandler<States, Events, Emits, StateId, Source>
+        readonly onDone: EffectDoneHandler<States, Events, Emits, StateId, Source>
         readonly onFailure?: never
       },
     ..._validation: InvokeChannelIsNever<Effect.Success<ReturnType<Source>>> extends true ? [
         "onDone must be omitted when the Effect output is never"
       ]
       : []
-  ): DynamicEffectInvokeResult<States, Events, Emits, StateId, Source>
+  ): EffectInvokeResult<States, Events, Emits, StateId, Source>
   <
     const States extends Machine.StateSchemas,
     const Events extends ReadonlyArray<Machine.TaggedSchema>,
@@ -7215,16 +7566,16 @@ export const invoke: {
     ) => Effect.Effect<never, unknown, unknown>
   >(
     config:
-      & DynamicEffectInvokeSource<States, Events, Emits, StateId, Source>
+      & EffectInvokeSource<States, Events, Emits, StateId, Source>
       & {
         readonly onDone?: never
-        readonly onFailure: DynamicEffectFailureHandler<States, Events, Emits, StateId, Source>
+        readonly onFailure: EffectFailureHandler<States, Events, Emits, StateId, Source>
       },
     ..._validation: InvokeChannelIsNever<Effect.Error<ReturnType<Source>>> extends true ? [
         "onFailure must be omitted when the Effect error is never"
       ]
       : []
-  ): DynamicEffectInvokeResult<States, Events, Emits, StateId, Source>
+  ): EffectInvokeResult<States, Events, Emits, StateId, Source>
   <
     const States extends Machine.StateSchemas,
     const Events extends ReadonlyArray<Machine.TaggedSchema>,
@@ -7235,32 +7586,12 @@ export const invoke: {
     ) => Effect.Effect<never, never, unknown>
   >(
     config:
-      & DynamicEffectInvokeSource<States, Events, Emits, StateId, Source>
+      & EffectInvokeSource<States, Events, Emits, StateId, Source>
       & {
         readonly onDone?: never
         readonly onFailure?: never
       }
-  ): DynamicEffectInvokeResult<States, Events, Emits, StateId, Source>
-  <
-    const States extends Machine.StateSchemas,
-    const Events extends ReadonlyArray<Machine.TaggedSchema>,
-    const Emits extends ReadonlyArray<Machine.TaggedSchema>,
-    StateId extends Machine.StateIdentifier<States>,
-    const Fx extends Effect.Effect<any, any, any>,
-    const Config extends object
-  >(
-    config:
-      & Config
-      & Machine.EffectInvokeArgs<States, Events, Emits, StateId, Fx, Fx, readonly [], readonly []>
-  ):
-    & Config
-    & Machine.InvokeOwned<States, Events, Emits, StateId>
-    & Machine.InvokeTyped<
-      Effect.Success<Fx>,
-      Effect.Error<Fx>,
-      Effect.Services<Fx>,
-      never
-    >
+  ): EffectInvokeResult<States, Events, Emits, StateId, Source>
   <
     const States extends Machine.StateSchemas,
     const Events extends ReadonlyArray<Machine.TaggedSchema>,