@typeonce/effect-machine 0.18.0 → 0.19.1

package/dist/Machine.d.ts

@@ -183,6 +183,20 @@ export interface Definition<States extends Machine.StateSchemas, Events extends
      * captured by value, so later mutation of the supplied objects cannot alter
      * the resulting machine.
      *
+     * **Example**
+     *
+     * ```ts
+     * const counter = definition.handle({
+     *   Count: {
+     *     on: {
+     *       Increment: (to) =>
+     *         to.full.Count().resolve(({ event, state, target }) =>
+     *           target(new Count({ value: state.value + event.by })))
+     *     }
+     *   }
+     * })
+     * ```
+     *
      * @since 0.4.0
      */
     readonly handle: Machine.Handler<States, Events, Emits, Input, Machine.StateIdentifier<States>, never, never, InitialE, InitialR, FinalStates, Output, never, InputEvents, ParentEvents>;
@@ -384,8 +398,10 @@ export type MachineReferences<InputEvents extends ReadonlyArray<Machine.TaggedSc
 } : {});
 /**
  * Synchronous commands available while a machine transition is being
- * selected. Enqueuing only records statechart and machine operations; it never
- * executes an Effect.
+ * selected.
+ *
+ * Enqueuing records statechart and machine operations for the selected
+ * transition. It never executes an Effect while the transition is evaluated.
  *
  * @category models
  * @since 0.4.0
@@ -925,6 +941,9 @@ export type RuntimeSnapshot<State, Error = never, Output = never> = {
  * 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`.
+ * Records retain decoded local events and snapshots and are not themselves a
+ * stable JSON export format. Telemetry exporters must project process-local
+ * values into an explicit portable representation.
  *
  * @category models
  * @since 0.13.0
@@ -1735,8 +1754,11 @@ export declare namespace Machine {
      * @since 0.4.0
      */
     interface StateNodeAnnotations extends Schema.Annotations.Annotations {
+        /** Human-readable label used by visualization and documentation tooling. */
         readonly title?: string | undefined;
+        /** Short explanation of the state node's domain meaning. */
         readonly description?: string | undefined;
+        /** Longer documentation text associated with the state node. */
         readonly documentation?: string | undefined;
     }
     /** Descriptive annotations accepted by schema-less active and pseudo-states. */
@@ -1744,31 +1766,41 @@ export declare namespace Machine {
     /** @deprecated Use {@link SchemaLessStateAnnotations}. */
     type PseudoStateAnnotations = SchemaLessStateAnnotations;
     /**
-     * Configuration accepted for an atomic object state node. Omit `schema` when
-     * the state owns no value; a schema-less final may still declare `output`.
+     * Configuration accepted for an atomic object state node.
+     *
+     * Omit `schema` when the state owns no value. A schema-less final may still
+     * declare `output`.
      *
      * @category models
      * @since 0.4.0
      */
     type AtomicStateNodeConfig = {
+        /** Tagged schema that owns the state's decoded value. */
         readonly schema: TaggedSchema;
+        /** Declares an ordinary active state. Omitted values default to `"active"`. */
         readonly type?: "active";
+        /** Atomic active states cannot declare terminal output. */
         readonly output?: never;
+        /** Schema-backed states take their annotations from the schema. */
         readonly annotations?: never;
     } | {
         readonly schema: TaggedSchema;
         readonly type: "final";
+        /** Optional schema describing the terminal value produced by this final state. */
         readonly output?: Schema.Top;
         readonly annotations?: never;
     } | {
         readonly schema?: never;
         readonly type?: "active";
         readonly output?: never;
+        /** Descriptive metadata for a schema-less state. */
         readonly annotations?: SchemaLessStateAnnotations;
     } | {
         readonly schema?: never;
         readonly type: "final";
+        /** Optional schema describing the terminal value produced by this final state. */
         readonly output?: Schema.Top;
+        /** Descriptive metadata for a schema-less state. */
         readonly annotations?: SchemaLessStateAnnotations;
     };
     /**
@@ -1779,16 +1811,22 @@ export declare namespace Machine {
      * @since 0.4.0
      */
     type CompoundStateNodeConfig = {
+        /** Tagged schema that owns the compound state's decoded value. */
         readonly schema: TaggedSchema;
+        /** Compound states are ordinary active states. */
         readonly type?: "active";
+        /** Direct child selected when the compound state is entered initially. */
         readonly initial: string;
+        /** Nested state nodes owned by this compound state. */
         readonly states: StateTree;
+        /** Schema-backed states take their annotations from the schema. */
         readonly annotations?: never;
     } | {
         readonly schema?: never;
         readonly type?: "active";
         readonly initial: string;
         readonly states: StateTree;
+        /** Descriptive metadata for a schema-less state. */
         readonly annotations?: SchemaLessStateAnnotations;
     };
     /**
@@ -1799,16 +1837,22 @@ export declare namespace Machine {
      * @since 0.4.0
      */
     type ParallelStateNodeConfig = {
+        /** Tagged schema that owns the parallel state's decoded value. */
         readonly schema: TaggedSchema;
+        /** Selects parallel-region semantics for the node. */
         readonly type: "parallel";
+        /** Optional schema describing the value produced after every region completes. */
         readonly output?: Schema.Top;
+        /** Child regions that are entered and remain active simultaneously. */
         readonly states: StateTree;
+        /** Schema-backed states take their annotations from the schema. */
         readonly annotations?: never;
     } | {
         readonly schema?: never;
         readonly type: "parallel";
         readonly output?: Schema.Top;
         readonly states: StateTree;
+        /** Descriptive metadata for a schema-less state. */
         readonly annotations?: SchemaLessStateAnnotations;
     };
     /**
@@ -1824,9 +1868,16 @@ export declare namespace Machine {
      * @since 0.4.0
      */
     interface HistoryStateNodeConfig {
+        /** Selects history pseudo-state semantics. */
         readonly type: "history";
-        /** Defaults to shallow history. */
+        /**
+         * Restores only the direct child for shallow history or the complete
+         * descendant configuration for deep history.
+         *
+         * @defaultValue `"shallow"`
+         */
         readonly history?: "shallow" | "deep";
+        /** Descriptive metadata used by visualization and documentation tooling. */
         readonly annotations?: SchemaLessStateAnnotations;
     }
     /**
@@ -1840,7 +1891,9 @@ export declare namespace Machine {
      * @since 0.4.0
      */
     interface ChoiceStateNodeConfig {
+        /** Selects transient choice pseudo-state semantics. */
         readonly type: "choice";
+        /** Descriptive metadata used by visualization and documentation tooling. */
         readonly annotations?: SchemaLessStateAnnotations;
     }
     /**
@@ -2467,33 +2520,36 @@ export declare namespace Machine {
      */
     interface EncodedSnapshotState {
         readonly path: string;
-        readonly value?: unknown;
+        readonly value?: Schema.Json;
     }
     /**
      * Encoded output for one completed state path in a normalized machine
-     * snapshot. An omitted output represents `undefined`.
+     * snapshot. An omitted output means the final state declares no output
+     * schema; a declared `Schema.Void` or `Schema.Undefined` output encodes as
+     * canonical JSON `null`.
      *
      * @category models
      * @since 0.4.0
      */
     interface EncodedSnapshotCompletion {
         readonly path: string;
-        readonly output?: unknown;
+        readonly output?: Schema.Json;
     }
     /** Encoded values and paths retained by one history pseudo-state. */
     interface EncodedSnapshotHistoryEntry {
         readonly mode: "shallow" | "deep";
         readonly active: ReadonlyArray<string>;
-        readonly values: Readonly<Record<string, unknown>>;
+        readonly values: Readonly<Record<string, Schema.Json>>;
     }
     /**
      * Normalized data representation of a machine snapshot.
      *
      * **Details**
      *
-     * Active state and completion values use the encoded representations of
-     * their declared schemas. Runtime process state such as children, fibers,
-     * scopes, queues, and subscriptions is not included.
+     * Active state and completion values use the canonical JSON representations
+     * derived from their declared schemas. A successfully encoded snapshot is
+     * safe to pass to JSON-backed persistence and transport. Runtime process state
+     * such as children, fibers, scopes, queues, and subscriptions is not included.
      *
      * @category models
      * @since 0.4.0
@@ -2929,15 +2985,23 @@ export declare namespace Machine {
     };
     /**
      * Definition-time topology selector available to an ordinary transition.
+     *
      * Topology-only instructions (`none`, declared `initial` and history
-     * selections, and `local.with`) are values. State and choice destinations
-     * remain callable selection methods.
+     * selections, and `local.with`) are values.
+     *
+     * State and choice destinations remain callable selection methods so their
+     * target-specific resolver APIs retain exact inference.
      */
     interface TargetSelector<States extends StateSchemas, Source extends StateNodeIdentifier<States>> {
+        /** Handles the trigger without selecting a destination. */
         readonly none: SelectionValue<TargetBuilder<States, Source>["none"], never, "none">;
+        /** Selects a destination inside the nearest active compound scope. */
         readonly local: LocalTargetSelector<States, Source>;
+        /** Selects a destination elsewhere under the currently active root. */
         readonly branch: BranchTargetSelector<States, Source>;
+        /** Selects a complete destination under any top-level state. */
         readonly full: FullTargetSelector<States>;
+        /** Restores a shallow or deep history pseudo-state. */
         readonly history: HistorySelectionTree<States, States, "", HistoryTargetBuilder<States>>;
     }
     /** Definition-time selector that can choose only a valid top-level initial entry. */
@@ -2955,11 +3019,15 @@ export declare namespace Machine {
      * @since 0.4.0
      */
     type HandlerContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, EventTag extends TagOf<Events[number]>, E, R, InputEvents extends ReadonlyArray<TaggedSchema> = Events, ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []> = MachineReferences<InputEvents, ParentEvents> & {
+        /** Value owned by the state whose handler is running. */
         readonly state: StateByIdentifier<States, StateId>;
+        /** Value owned by the nearest schema-backed ancestor, when one exists. */
         readonly containingState: ParentStateValue<States, StateId>;
+        /** Schema-backed ancestor values keyed by their complete state paths. */
         readonly ancestors: ParentStateValues<States, StateId>;
         /** Complete logical configuration captured at the start of this microstep. */
         readonly snapshot: Snapshot<States>;
+        /** Event that selected this handler, narrowed by its `_tag`. */
         readonly event: EventByTag<Events, EventTag>;
         /**
          * Provides typed builders for choosing the next active state from this
@@ -2976,9 +3044,13 @@ export declare namespace Machine {
      * @since 0.4.0
      */
     type StateActionContext<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 []> = MachineReferences<InputEvents, ParentEvents> & {
+        /** Value owned by the state entering or exiting. */
         readonly state: StateByIdentifier<States, StateId>;
+        /** Value owned by the nearest schema-backed ancestor, when one exists. */
         readonly containingState: ParentStateValue<States, StateId>;
+        /** Schema-backed ancestor values keyed by their complete state paths. */
         readonly ancestors: ParentStateValues<States, StateId>;
+        /** Event or initial-entry marker responsible for the lifecycle action. */
         readonly event: LifecycleEvent<Events>;
     };
     /**
@@ -2988,9 +3060,13 @@ export declare namespace Machine {
      * @since 0.4.0
      */
     type InvokeContext<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 []> = MachineReferences<InputEvents, ParentEvents> & {
+        /** Value owned by the state that owns this invocation. */
         readonly state: StateByIdentifier<States, StateId>;
+        /** Value owned by the nearest schema-backed ancestor, when one exists. */
         readonly containingState: ParentStateValue<States, StateId>;
+        /** Schema-backed ancestor values keyed by their complete state paths. */
         readonly ancestors: ParentStateValues<States, StateId>;
+        /** Event or initial-entry marker responsible for starting the invocation. */
         readonly event: LifecycleEvent<Events>;
     };
     /**
@@ -3000,11 +3076,17 @@ export declare namespace Machine {
      * @since 0.4.0
      */
     type InvokeSnapshotContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, State, Error, Output, InputEvents extends ReadonlyArray<TaggedSchema> = Events, ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []> = MachineReferences<InputEvents, ParentEvents> & {
+        /** Parent-local invocation identifier. */
         readonly id: string;
+        /** Current value of the state that owns the invocation. */
         readonly state: StateByIdentifier<States, StateId>;
+        /** Value owned by the nearest schema-backed ancestor, when one exists. */
         readonly containingState: ParentStateValue<States, StateId>;
+        /** Schema-backed ancestor values keyed by their complete state paths. */
         readonly ancestors: ParentStateValues<States, StateId>;
+        /** Builders for selecting the owning machine's next state. */
         readonly target: TargetBuilder<States, StateId>;
+        /** Latest active lifecycle snapshot published by the invoked logic or child. */
         readonly snapshot: Extract<RuntimeSnapshot<State, Error, Output>, {
             readonly status: "active";
         }>;
@@ -3016,32 +3098,53 @@ export declare namespace Machine {
      * @since 0.4.0
      */
     type InvokeDoneContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, Output, InputEvents extends ReadonlyArray<TaggedSchema> = Events, ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []> = MachineReferences<InputEvents, ParentEvents> & {
+        /** Parent-local invocation identifier. */
         readonly id: string;
+        /** Current value of the state that owns the invocation. */
         readonly state: StateByIdentifier<States, StateId>;
+        /** Value owned by the nearest schema-backed ancestor, when one exists. */
         readonly containingState: ParentStateValue<States, StateId>;
+        /** Schema-backed ancestor values keyed by their complete state paths. */
         readonly ancestors: ParentStateValues<States, StateId>;
+        /** Complete owning-machine configuration captured for this transition. */
         readonly snapshot: Snapshot<States>;
+        /** Builders for selecting the owning machine's next state. */
         readonly target: TargetBuilder<States, StateId>;
+        /** Successful output produced by the invocation. */
         readonly output: Output;
     };
     /** Context passed to a Stream invocation's element transition. */
     type InvokeElementContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, Element, InputEvents extends ReadonlyArray<TaggedSchema> = Events, ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []> = MachineReferences<InputEvents, ParentEvents> & {
+        /** Parent-local invocation identifier. */
         readonly id: string;
+        /** Current value of the state that owns the Stream invocation. */
         readonly state: StateByIdentifier<States, StateId>;
+        /** Value owned by the nearest schema-backed ancestor, when one exists. */
         readonly containingState: ParentStateValue<States, StateId>;
+        /** Schema-backed ancestor values keyed by their complete state paths. */
         readonly ancestors: ParentStateValues<States, StateId>;
+        /** Complete owning-machine configuration captured for this transition. */
         readonly snapshot: Snapshot<States>;
+        /** Builders for selecting the owning machine's next state. */
         readonly target: TargetBuilder<States, StateId>;
+        /** Next element emitted by the invoked Stream. */
         readonly element: Element;
     };
     /** Context passed to an invocation typed-failure transition. */
     type InvokeFailureContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, Error, InputEvents extends ReadonlyArray<TaggedSchema> = Events, ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []> = MachineReferences<InputEvents, ParentEvents> & {
+        /** Parent-local invocation identifier. */
         readonly id: string;
+        /** Current value of the state that owns the invocation. */
         readonly state: StateByIdentifier<States, StateId>;
+        /** Value owned by the nearest schema-backed ancestor, when one exists. */
         readonly containingState: ParentStateValue<States, StateId>;
+        /** Schema-backed ancestor values keyed by their complete state paths. */
         readonly ancestors: ParentStateValues<States, StateId>;
+        /** Complete owning-machine configuration captured for this transition. */
         readonly snapshot: Snapshot<States>;
+        /** Builders for selecting the owning machine's next state. */
         readonly target: TargetBuilder<States, StateId>;
+        /** Typed failure produced by the invocation. */
         readonly error: Error;
     };
     /**
@@ -3051,11 +3154,15 @@ export declare namespace Machine {
      * @since 0.4.0
      */
     type AlwaysContext<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 []> = MachineReferences<InputEvents, ParentEvents> & {
+        /** Current value of the state evaluating the eventless transition. */
         readonly state: StateByIdentifier<States, StateId>;
+        /** Value owned by the nearest schema-backed ancestor, when one exists. */
         readonly containingState: ParentStateValue<States, StateId>;
+        /** Schema-backed ancestor values keyed by their complete state paths. */
         readonly ancestors: ParentStateValues<States, StateId>;
         /** Complete logical configuration captured at the start of this microstep. */
         readonly snapshot: Snapshot<States>;
+        /** Lifecycle event retained while the eventless transition is evaluated. */
         readonly event: LifecycleEvent<Events>;
         /**
          * Provides typed builders for choosing the next active state from this
@@ -3073,12 +3180,17 @@ export declare namespace Machine {
      * @since 0.4.0
      */
     type DoneContext<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 []> = MachineReferences<InputEvents, ParentEvents> & {
+        /** Current value of the state whose child configuration completed. */
         readonly state: StateByIdentifier<States, StateId>;
+        /** Value owned by the nearest schema-backed ancestor, when one exists. */
         readonly containingState: ParentStateValue<States, StateId>;
+        /** Schema-backed ancestor values keyed by their complete state paths. */
         readonly ancestors: ParentStateValues<States, StateId>;
         /** Complete logical configuration captured at the start of this microstep. */
         readonly snapshot: Snapshot<States>;
+        /** Lifecycle event retained while state completion is processed. */
         readonly event: LifecycleEvent<Events>;
+        /** Output produced by the completed final child or parallel regions. */
         readonly output: CompletionOutputByIdentifier<States, StateId>;
         /**
          * Provides typed builders for choosing the next active state after this
@@ -3091,11 +3203,15 @@ export declare namespace Machine {
     };
     /** Context passed to a transient choice resolver. There is no `state` value. */
     type ChoiceContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, ChoiceId extends ChoiceIdentifier<States>, InputEvents extends ReadonlyArray<TaggedSchema> = Events, ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []> = MachineReferences<InputEvents, ParentEvents> & {
+        /** Value owned by the choice node's immediate schema-backed parent. */
         readonly containingState: StateByIdentifier<States, Extract<ImmediateParentStateIdentifier<ChoiceId>, StateIdentifier<States>>>;
+        /** Schema-backed ancestor values keyed by their complete state paths. */
         readonly ancestors: {
             readonly [Parent in Extract<ParentStateIdentifier<ChoiceId>, ValuedStateIdentifier<States>>]: StateByIdentifier<States, Parent>;
         };
+        /** Lifecycle event that led to the transient choice. */
         readonly event: LifecycleEvent<Events>;
+        /** Builders for selecting the concrete destination of this choice. */
         readonly target: TargetBuilder<States, ChoiceId>;
     };
     /**
@@ -3105,9 +3221,13 @@ export declare namespace Machine {
      * @since 0.4.0
      */
     interface FinalOutputContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> {
+        /** Decoded value owned by the final state. */
         readonly state: StateByIdentifier<States, StateId>;
+        /** Value owned by the nearest schema-backed ancestor, when one exists. */
         readonly containingState: ParentStateValue<States, StateId>;
+        /** Schema-backed ancestor values keyed by their complete state paths. */
         readonly ancestors: ParentStateValues<States, StateId>;
+        /** Lifecycle event responsible for entering the final state. */
         readonly event: LifecycleEvent<Events>;
     }
     /**
@@ -3129,10 +3249,15 @@ export declare namespace Machine {
      * @since 0.4.0
      */
     interface ParallelOutputContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> {
+        /** Decoded value owned by the completed parallel state. */
         readonly state: StateByIdentifier<States, StateId>;
+        /** Value owned by the nearest schema-backed ancestor, when one exists. */
         readonly containingState: ParentStateValue<States, StateId>;
+        /** Schema-backed ancestor values keyed by their complete state paths. */
         readonly ancestors: ParentStateValues<States, StateId>;
+        /** Lifecycle event retained while parallel completion is processed. */
         readonly event: LifecycleEvent<Events>;
+        /** Completion output from every direct parallel region. */
         readonly outputs: ParallelOutputRegions<States, StateId>;
     }
     /**
@@ -3422,13 +3547,16 @@ export declare namespace Machine {
     });
     /** Context capability available only to explicitly declinable resolvers. */
     interface DeclineCapability {
+        /** Declines this candidate and continues hierarchical transition selection. */
         readonly decline: () => Declined;
     }
     type TransitionResolver<Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Context, Selection> = (context: TransitionResolveContext<Context, Selection>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined;
     type DeclinableTransitionResolver<Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Context, Selection> = (context: TransitionResolveContext<Context, Selection> & DeclineCapability, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => (SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined) | Declined;
     /** One named destination declared by a branching transition. */
     interface TransitionBranchInput<Selection extends TargetSelection<any, any, any> = TargetSelection<any, any, any>> {
+        /** Exact topology destination available to the branching resolver. */
         readonly target: Selection;
+        /** Optional human-readable branch label used by visualization tooling. */
         readonly title?: string;
     }
     /** Opaque evidence that a branching resolver selected one declared branch. */
@@ -3469,14 +3597,17 @@ export declare namespace Machine {
         };
     }
     type TransitionReenterOption<Reenter extends boolean> = [Reenter] extends [true] ? {
+        /** Forces the source state to exit and enter even when active paths remain unchanged. */
         readonly reenter?: boolean;
     } : {
         readonly reenter?: never;
     };
     type TransitionRequiredOptions<Reenter extends boolean> = TransitionReenterOption<Reenter> & {
+        /** Keeps the transition required. The resolver cannot return `decline()`. */
         readonly declinable?: false;
     };
     type TransitionDeclinableOptions<Reenter extends boolean> = TransitionReenterOption<Reenter> & {
+        /** Adds `decline()` to the resolver context and permits declining this candidate. */
         readonly declinable: true;
     };
     type BuiltTransition<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean, Result, Acceptance extends TransitionAcceptance> = TransitionTyped<States, Events, Emits, StateId, Context, Reenter, Acceptance> & TransitionBuilderEvidence<Result, Acceptance>;
@@ -3486,10 +3617,31 @@ export declare namespace Machine {
     interface TransitionResolveDeclinable<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean, Selection extends TargetSelection<any, any, any>> {
         (resolve: DeclinableTransitionResolver<Events, Emits, Context, Selection>, options: TransitionDeclinableOptions<Reenter>): BuiltTransition<States, Events, Emits, StateId, Context, Reenter, (SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined) | Declined, "declinable">;
     }
-    /** A selected transition target with target-specific resolver operations. */
+    /**
+     * A selected transition target with target-specific resolver operations.
+     *
+     * **Example** (Updating state while reentering)
+     *
+     * ```ts
+     * Reset: (to) =>
+     *   to.full.Ready().resolve(
+     *     ({ target }) => target.from(),
+     *     { reenter: true }
+     *   )
+     * ```
+     *
+     * @inlineType TransitionRequiredOptions
+     * @inlineType TransitionDeclinableOptions
+     * @inlineType TransitionReenterOption
+     */
     type TransitionTarget<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean, Acceptance extends TransitionAcceptance, Selection extends TargetSelection<any, any, any>> = Selection & (SelectionSupportsDefaultConstruction<Selection> extends true ? BuiltTransition<States, Events, Emits, StateId, Context, Reenter, SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined, "required"> : {}) & {
+        /**
+         * Evaluates state construction and queued commands only after this
+         * transition has been selected.
+         */
         readonly resolve: TransitionResolveRequired<States, Events, Emits, StateId, Context, Reenter, Selection> & ("declinable" extends Acceptance ? TransitionResolveDeclinable<States, Events, Emits, StateId, Context, Reenter, Selection> : {});
     } & ([Reenter] extends [true] ? SelectionSupportsDefaultConstruction<Selection> extends true ? {
+        /** Reenters the source using the selected target's default construction. */
         readonly reenter: () => BuiltTransition<States, Events, Emits, StateId, Context, Reenter, SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined, "required">;
     } : {} : {});
     /** @internal Type evidence retained by a machine initial-entry declaration. */
@@ -3498,8 +3650,11 @@ export declare namespace Machine {
     }
     /** A selected machine initial entry with its exact resolver target. */
     type InitialTransitionTarget<Input, Selection extends TargetSelection<any, any, any>> = Selection & (SelectionSupportsDefaultConstruction<Selection> extends true ? InitialBuilderEvidence<Selection> : {}) & {
+        /** Lazily constructs the selected initial state from decoded machine input. */
         readonly resolve: (resolve: (context: {
+            /** Decoded value supplied when the machine is started. */
             readonly input: Input;
+            /** Builder specialized to the selected initial destination. */
             readonly target: SelectionBuilder<Selection>;
         }) => SelectedTargetResult<Selection>) => InitialBuilderEvidence<Selection>;
     };
@@ -3525,7 +3680,9 @@ export declare namespace Machine {
     }
     /** Selector supplied to inline transition declarations. */
     type TransitionSelector<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean, Acceptance extends TransitionAcceptance> = TransitionSelectorNode<States, Events, Emits, StateId, Context, Reenter, Acceptance, TargetSelector<States, StateId>> & {
+        /** Declares a closed set of named destinations for one resolver. */
         readonly branches: <const Branches extends Readonly<Record<string, TransitionBranchInput>>>(branches: Branches & ValidateTransitionBranchRecord<NoInfer<Branches>>) => {
+            /** Resolves exactly one declared branch after this transition is selected. */
             readonly resolve: TransitionBranchesResolveRequired<States, Events, Emits, StateId, Context, Reenter, Branches> & ("declinable" extends Acceptance ? TransitionBranchesResolveDeclinable<States, Events, Emits, StateId, Context, Reenter, Branches> : {});
         };
     };
@@ -3630,13 +3787,18 @@ export declare namespace Machine {
     type InvokeBuilderResult<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, InputEvents extends ReadonlyArray<TaggedSchema>, ParentEvents extends ReadonlyArray<TaggedSchema>, Output, Error, Requirements, InitialError, ChildEmits, ChildParentEvent, Outcomes> = InvokeOwned<States, Events, Emits, StateId, InputEvents, ParentEvents> & InvokeTyped<Output, Error, Requirements, InitialError, ChildEmits, ChildParentEvent, Outcomes> & {
         readonly [InvokeBuilderTypeId]: true;
     };
+    /** Lifecycle handlers exposed according to the selected invocation source. */
     type InvokeBuilder<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, InputEvents extends ReadonlyArray<TaggedSchema>, ParentEvents extends ReadonlyArray<TaggedSchema>, Output, Error, Requirements, InitialError, ChildEmits, ChildParentEvent, Element, Pending extends string, SnapshotHandler, Outcomes = never> = ([Pending] extends [never] ? InvokeBuilderResult<States, Events, Emits, StateId, InputEvents, ParentEvents, Output, Error, Requirements, InitialError, ChildEmits, ChildParentEvent, Outcomes> : {}) & ("done" extends Pending ? {
+        /** Handles successful completion and exposes the invocation output. */
         readonly onDone: <const Handler extends InvokeTransition<States, Events, Emits, StateId, InvokeDoneContext<States, Events, Emits, StateId, Output, InputEvents, ParentEvents>>>(handler: Handler & InvokeTransition<States, Events, Emits, StateId, InvokeDoneContext<States, Events, Emits, StateId, Output, InputEvents, ParentEvents>>) => InvokeBuilder<States, Events, Emits, StateId, InputEvents, ParentEvents, Output, Error, Requirements, InitialError, ChildEmits, ChildParentEvent, Element, Exclude<Pending, "done">, SnapshotHandler, Outcomes | Handler>;
     } : {}) & ("failure" extends Pending ? {
+        /** Handles typed failure and exposes the invocation error. */
         readonly onFailure: <const Handler extends InvokeTransition<States, Events, Emits, StateId, InvokeFailureContext<States, Events, Emits, StateId, Error, InputEvents, ParentEvents>>>(handler: Handler & InvokeTransition<States, Events, Emits, StateId, InvokeFailureContext<States, Events, Emits, StateId, Error, InputEvents, ParentEvents>>) => InvokeBuilder<States, Events, Emits, StateId, InputEvents, ParentEvents, Output, Error, Requirements, InitialError, ChildEmits, ChildParentEvent, Element, Exclude<Pending, "failure">, SnapshotHandler, Outcomes | Handler>;
     } : {}) & ("element" extends Pending ? {
+        /** Handles each backpressured element emitted by an invoked Stream. */
         readonly onElement: <const Handler extends InvokeTransition<States, Events, Emits, StateId, InvokeElementContext<States, Events, Emits, StateId, Element, InputEvents, ParentEvents>>>(handler: Handler & InvokeTransition<States, Events, Emits, StateId, InvokeElementContext<States, Events, Emits, StateId, Element, InputEvents, ParentEvents>>) => InvokeBuilder<States, Events, Emits, StateId, InputEvents, ParentEvents, Output, Error, Requirements, InitialError, ChildEmits, ChildParentEvent, Element, Exclude<Pending, "element">, SnapshotHandler, Outcomes | Handler>;
     } : {}) & ([SnapshotHandler] extends [never] ? {} : {
+        /** Handles each active snapshot published by invoked logic or a child machine. */
         readonly onSnapshot: <const Handler extends SnapshotHandler>(handler: Handler & SnapshotHandler) => InvokeBuilder<States, Events, Emits, StateId, InputEvents, ParentEvents, Output, Error, Requirements, InitialError, ChildEmits, ChildParentEvent, Element, Pending, never, Outcomes | Handler>;
     });
     type EffectInvokeBuilder<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, InputEvents extends ReadonlyArray<TaggedSchema>, ParentEvents extends ReadonlyArray<TaggedSchema>, Source extends (...args: ReadonlyArray<any>) => Effect.Effect<any, any, any>> = InvokeBuilder<States, Events, Emits, StateId, InputEvents, ParentEvents, Effect.Success<ReturnType<Source>>, Effect.Error<ReturnType<Source>>, Effect.Services<ReturnType<Source>>, never, never, never, never, RequiredInvokeChannel<Effect.Success<ReturnType<Source>>, "done"> | RequiredInvokeChannel<Effect.Error<ReturnType<Source>>, "failure">, never>;
@@ -3650,20 +3812,59 @@ export declare namespace Machine {
      * chain becomes returnable from `invoke` only after every reachable required
      * channel has been handled.
      *
+     * **Example** (Invoking an Effect)
+     *
+     * ```ts
+     * invoke: (from) =>
+     *   from.effect("load-user", () => loadUser).onDone((to) =>
+     *     to.full.Ready().resolve(({ output, target }) => target.from({ user: output }))
+     *   ).onFailure((to) =>
+     *     to.full.Failed().resolve(({ error, target }) => target.from({ error }))
+     *   )
+     * ```
+     *
+     * @inlineType EffectInvokeBuilder
+     * @inlineType StreamInvokeBuilder
+     * @inlineType LogicInvokeBuilder
+     * @inlineType ChildInvokeBuilder
+     * @inlineType InvokeBuilder
+     *
      * @category models
      * @since 0.18.0
      */
     interface InvokeSelector<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 []> {
-        /** Starts a fresh Effect each time the owning state is entered. */
+        /**
+         * Starts a fresh Effect each time the owning state is entered.
+         *
+         * @param id Parent-local lifecycle identifier.
+         * @param source Lazy Effect factory evaluated on every entry.
+         */
         readonly effect: <const Source extends (context: InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>) => Effect.Effect<unknown, unknown, unknown>>(id: InvokeLifecycleId, source: Source) => EffectInvokeBuilder<States, Events, Emits, StateId, InputEvents, ParentEvents, Source>;
-        /** Starts a fresh, backpressured Stream each time the owning state is entered. */
+        /**
+         * Starts a fresh, backpressured Stream each time the owning state is entered.
+         *
+         * @param id Parent-local lifecycle identifier.
+         * @param source Lazy Stream factory evaluated on every entry.
+         */
         readonly stream: <const Source extends (context: InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>) => Stream.Stream<unknown, unknown, any>>(id: InvokeLifecycleId, source: Source) => StreamInvokeBuilder<States, Events, Emits, StateId, InputEvents, ParentEvents, Source>;
-        /** Starts a cancellable state-scoped timer. */
+        /**
+         * Starts a cancellable state-scoped timer.
+         *
+         * @param id Parent-local lifecycle identifier.
+         * @param duration Duration input or context-dependent duration factory.
+         */
         readonly timer: (id: InvokeLifecycleId, duration: InvokeSource<Duration.Input, InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>>) => InvokeBuilder<States, Events, Emits, StateId, InputEvents, ParentEvents, void, never, never, never, never, never, never, "done", never>;
-        /** Starts reusable process logic at a typed parent-local address. */
+        /**
+         * Starts reusable process logic at a typed parent-local address.
+         *
+         * @param id Parent-local lifecycle identifier.
+         * @param options Address and reusable logic value or factory.
+         */
         readonly logic: {
             <const Source extends (context: InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>) => unknown, Address extends ChildAddress<never>>(id: InvokeLifecycleId, options: {
+                /** Typed parent-local address used to send events to this logic. */
                 readonly address: Address & ChildAddress.Compatibility<Address, LogicEventOf<ReturnType<NoInfer<Source>>>>;
+                /** Context-dependent factory that returns reusable process logic. */
                 readonly logic: Source;
             }, ..._validation: ReturnType<Source> extends {
                 readonly initial: unknown;
@@ -3672,7 +3873,9 @@ export declare namespace Machine {
                 "logic factory must return Machine.Logic"
             ]): LogicInvokeBuilder<States, Events, Emits, StateId, InputEvents, ParentEvents, ReturnType<Source>>;
             <const Source, Address extends ChildAddress<never>>(id: InvokeLifecycleId, options: {
+                /** Typed parent-local address used to send events to this logic. */
                 readonly address: Address & ChildAddress.Compatibility<Address, LogicEventOf<NoInfer<Source>>>;
+                /** Reusable process logic started when the owning state enters. */
                 readonly logic: Source;
             }, ..._validation: Source extends {
                 readonly initial: unknown;
@@ -3681,11 +3884,17 @@ export declare namespace Machine {
                 "logic must implement Machine.Logic"
             ]): LogicInvokeBuilder<States, Events, Emits, StateId, InputEvents, ParentEvents, Source>;
         };
-        /** Starts a complete child statechart represented by a reusable descriptor. */
+        /**
+         * Starts a complete child statechart represented by a reusable descriptor.
+         *
+         * @param child Reusable descriptor created with `Machine.child`.
+         * @param options Input construction for a child with a non-void input schema.
+         */
         readonly child: <const Child extends ChildMachine.Any>(child: Child & (Child["machine"] extends EnsureExecutable<Machine.States<Child["machine"]>, Machine.UnhandledStates<Child["machine"]>, Machine.OutputStates<Child["machine"]>> ? unknown : never), ...options: InputSchema<Child["machine"]> extends typeof Schema.Void ? [options?: {
             readonly input?: never;
         }] : [
             options: {
+                /** Child input value or factory evaluated from the owning state context. */
                 readonly input: InvokeSource<Input<Child["machine"]>, InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>>;
             }
         ]) => ChildInvokeBuilder<States, Events, Emits, StateId, InputEvents, ParentEvents, Child>;
@@ -3705,9 +3914,11 @@ export declare namespace Machine {
     }) | ReadonlyArray<InvokeOwned<States, Events, Emits, StateId, InputEvents, ParentEvents> & {
         readonly [InvokeBuilderTypeId]: true;
     }>;
+    /** Output construction available to final and output-producing parallel states. */
     type OutputHandlerConfig<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, Context> = NodeByIdentifier<States, StateId> extends {
         readonly output: Schema.Top;
     } ? {
+        /** Constructs the decoded output declared by the state's `output` schema. */
         readonly output: (context: Context) => OutputByIdentifier<States, StateId>;
     } : {
         readonly output?: never;
@@ -3720,18 +3931,41 @@ export declare namespace Machine {
     /**
      * Configuration accepted for a non-final state.
      *
+     * **Example** (State actions, events, and invocation)
+     *
+     * ```ts
+     * machine.handle({
+     *   Loading: {
+     *     entry: (_, enqueue) => enqueue.emit({ _tag: "Started" }),
+     *     invoke: (from) =>
+     *       from.effect("load", () => load).onDone((to) => to.full.Ready()),
+     *     on: { Cancel: (to) => to.full.Idle() }
+     *   }
+     * })
+     * ```
+     *
+     * @inlineType ActiveOutputHandlerConfig
+     * @inlineType OutputHandlerConfig
+     *
      * @category models
      * @since 0.4.0
      */
     type ActiveStateConfig<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, E, R, InputEvents extends ReadonlyArray<TaggedSchema> = Events, ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []> = {
+        /** Runs synchronously when the state is entered and may enqueue commands. */
         readonly entry?: (context: StateActionContext<States, Events, Emits, StateId, InputEvents, ParentEvents>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => StateActionResult<any, any>;
+        /** Runs synchronously before the state is exited and may enqueue commands. */
         readonly exit?: (context: StateActionContext<States, Events, Emits, StateId, InputEvents, ParentEvents>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => StateActionResult<any, any>;
+        /** Starts state-owned Effect, Stream, timer, logic, or child lifecycles. */
         readonly invoke?: InvokeBuilderInput<States, Events, Emits, StateId, InputEvents, ParentEvents>;
+        /** Eventless transition evaluated after the state becomes stable. */
         readonly always?: TransitionConfig<States, Events, Emits, StateId, AlwaysContext<States, Events, Emits, StateId, InputEvents, ParentEvents>, false, TransitionAcceptance>;
+        /** Transition evaluated after this compound or parallel state completes. */
         readonly onDone?: TransitionConfig<States, Events, Emits, StateId, DoneContext<States, Events, Emits, StateId, InputEvents, ParentEvents>, false, TransitionAcceptance>;
+        /** Event handlers keyed by the `_tag` of the machine's public or internal events. */
         readonly on?: {
             readonly [EventTag in TagOf<Events[number]>]?: TransitionConfig<States, Events, Emits, StateId, HandlerContext<States, Events, Emits, StateId, EventTag, E, R, InputEvents, ParentEvents>, true, TransitionAcceptance>;
         };
+        /** Supplies missing direct initial-child values required by implicit entry and shallow history. */
         readonly initialize?: StateInitializeHandler<States, Events, Emits, StateId, InputEvents, ParentEvents>;
     } & ActiveOutputHandlerConfig<States, Events, StateId>;
     /**
@@ -3797,8 +4031,11 @@ export declare namespace Machine {
     type StateInitializeHandler<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 []> = (context: StateInitializeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => SnapshotBuilderComplete<StateInitializeValue<States, StateId>, boolean>;
     /** Context used only when a history node has no previously captured record. */
     interface HistoryDefaultContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, ParentId extends StateIdentifier<States>> {
+        /** Lifecycle event that attempted to restore this history node. */
         readonly event: LifecycleEvent<Events>;
+        /** Complete target builder rooted at the history owner. */
         readonly target: HistoryDefaultTargetBuilder<States, ParentId>;
+        /** State path whose child configuration is restored by this history node. */
         readonly owner: ParentId;
     }
     /**
@@ -3809,14 +4046,26 @@ export declare namespace Machine {
      * and provides every inactive ancestor and required parallel region.
      */
     type HistoryDefaultHandler<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, ParentId extends StateIdentifier<States>> = (context: HistoryDefaultContext<States, Events, Emits, ParentId>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => CompleteSnapshotContaining<States, ParentId> | StateConstruction<CompleteSnapshotContaining<States, ParentId>>;
-    /** Default implementations keyed by direct history child. */
+    /**
+     * Fallback implementation for one direct history pseudo-state.
+     *
+     * @inline
+     */
+    interface HistoryDefaultEntry<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, ParentId extends StateIdentifier<States>> {
+        /** Builds the complete fallback configuration used before history is first captured. */
+        readonly default: HistoryDefaultHandler<States, Events, Emits, ParentId>;
+    }
+    /**
+     * Default implementations keyed by direct history child.
+     *
+     * @inlineType HistoryDefaultEntry
+     */
     type HistoryDefaultConfig<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, ParentId extends StateIdentifier<States>, Children extends StateSchemas> = {
-        readonly [Key in HistoryStateKey<Children>]?: {
-            readonly default: HistoryDefaultHandler<States, Events, Emits, ParentId>;
-        };
+        readonly [Key in HistoryStateKey<Children>]?: HistoryDefaultEntry<States, Events, Emits, ParentId>;
     };
     /** Required implementation for a choice pseudo-state. */
     interface ChoiceStateConfig<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, ChoiceId extends ChoiceIdentifier<States>, InputEvents extends ReadonlyArray<TaggedSchema> = Events, ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []> {
+        /** Required transition that resolves this transient choice to a concrete destination. */
         readonly choice: TransitionConfig<States, Events, Emits, ChoiceId, ChoiceContext<States, Events, Emits, ChoiceId, InputEvents, ParentEvents>>;
         readonly entry?: never;
         readonly exit?: never;
@@ -3830,10 +4079,13 @@ export declare namespace Machine {
     /**
      * Configuration accepted for a final state.
      *
+     * @inlineType OutputHandlerConfig
+     *
      * @category models
      * @since 0.4.0
      */
     type FinalStateConfig<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 []> = {
+        /** Runs synchronously when the final state is entered and may enqueue commands. */
         readonly entry?: (context: StateActionContext<States, Events, Emits, StateId, InputEvents, ParentEvents>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => StateActionResult<any, any>;
         readonly exit?: never;
         readonly always?: never;
@@ -3871,6 +4123,7 @@ export declare namespace Machine {
     } : {
         readonly [Key in Path]?: Validation;
     };
+    /** Nested handler-tree structure shared by active and final state configs. */
     type HandlerNode<AllStates extends StateSchemas, Node, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, E, R, InputEvents extends ReadonlyArray<TaggedSchema>, ParentEvents extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<AllStates>> = HandlerNodeConfig<AllStates, Events, Emits, StateId, E, R, InputEvents, ParentEvents> & (StateId extends ChoiceIdentifier<AllStates> ? {
         readonly states?: never;
         readonly history?: never;
@@ -3878,7 +4131,9 @@ export declare namespace Machine {
         readonly states?: never;
         readonly history?: never;
     } : {
+        /** Child-state handlers nested according to the declared state topology. */
         readonly states?: HandlerTree<AllStates, Children, Events, Emits, E, R, InputEvents, ParentEvents, Extract<StateId, StateIdentifier<AllStates>>>;
+        /** First-use defaults keyed by direct history pseudo-state. */
         readonly history?: HistoryDefaultConfig<AllStates, Events, Emits, Extract<StateId, StateIdentifier<AllStates>>, Children>;
     } : {
         readonly states?: never;
@@ -4170,20 +4425,31 @@ export declare const state: StateConstructor;
  */
 export declare const states: StatesConstructor;
 type MakeConfig<States extends Machine.StateSchemas, InputEvents extends ReadonlyArray<Machine.TaggedSchema>, Emits extends ReadonlyArray<Machine.TaggedSchema>, Input extends Schema.Top, InitialE, InitialR, InternalEvents extends ReadonlyArray<Machine.TaggedSchema>, ParentDeclaration extends Parent.Any | undefined> = {
+    /** Stable definition identifier used by inspection and visualization. */
     readonly id?: string;
+    /** State topology and value schemas, normally supplied by `Machine.states`. */
     readonly states: States & DefineStateTreeInput<NoInfer<States>>;
+    /** Public events accepted by independently running machine references. */
     readonly events: Machine.EventProtocol<"public", InputEvents> & ValidateInputEventProtocol<NoInfer<InputEvents>>;
+    /** Machine-local events used by raised events and other internal deliveries. */
     readonly internalEvents?: Machine.EventProtocol<"internal", InternalEvents> & ValidateInternalEventProtocol<NoInfer<InputEvents>, NoInfer<InternalEvents>>;
+    /** Ephemeral notifications that handlers may publish to observers. */
     readonly emittedEvents?: Machine.EventProtocol<"emitted", Emits>;
+    /** Required or optional owning-machine protocol for this definition. */
     readonly parent?: ParentDeclaration;
+    /** Schema used to decode input before initial-state construction. */
     readonly input?: Input;
+    /** Target-first declaration that constructs the initial active configuration. */
     readonly initial: unknown;
 };
 type MakeResult<States extends Machine.StateSchemas, InputEvents extends ReadonlyArray<Machine.TaggedSchema>, Emits extends ReadonlyArray<Machine.TaggedSchema>, Input extends Schema.Top, InitialE, InitialR, InternalEvents extends ReadonlyArray<Machine.TaggedSchema>, ParentDeclaration extends Parent.Any | undefined> = Definition<States, readonly [...InputEvents, ...InternalEvents], Input, InitialE, InitialR, Machine.FinalStateFromDefinition<States>, Machine.TerminalOutput<States>, Emits, InputEvents, Machine.ParentEventsOf<ParentDeclaration>>;
+/** @inline */
 interface Make {
+    /** @param config Complete schema-first machine definition. */
     <const States extends Machine.StateSchemas, const InputEvents extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, InitialE = never, InitialR = never, const InternalEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const ParentDeclaration extends Parent.Any | undefined = undefined>(config: Omit<MakeConfig<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentDeclaration>, "initial"> & {
         readonly initial: Machine.InitialBuilderInput<States, Input["Type"]>;
     }, ..._validation: ValidateDefinedStates<NoInfer<States>>): MakeResult<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentDeclaration>;
+    /** @param config Invalid state tree retained only to report its validation error at the call site. */
     <const States extends Machine.StateSchemas, const InputEvents extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, InitialE = never, InitialR = never, const InternalEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const ParentDeclaration extends Parent.Any | undefined = undefined>(config: Omit<MakeConfig<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentDeclaration>, "states"> & {
         readonly states: InvalidDefinedStateTreeInput<States>;
     }): never;
@@ -4246,6 +4512,7 @@ interface Make {
  * ```
  *
  * @see {@link states} for typed state-tree helpers.
+ * @inlineType MakeConfig
  * @category constructors
  * @since 0.4.0
  */
@@ -4371,18 +4638,21 @@ export declare const emittedEvents: {
  *
  * **Details**
  *
- * Each active state value and completed output is encoded with the schema
- * declared for its state path. The result contains no process-local runtime
- * state.
+ * Each active state value and completed output is encoded with the canonical
+ * JSON codec derived from the schema declared for its state path. Success
+ * guarantees that every state, output, and history value is `Schema.Json`.
+ * Non-JSON values, including cyclic process-local capabilities, fail with
+ * {@link MachineSchemaEncodeError} at their declared boundary.
  *
  * **Gotchas**
  *
  * The encoded snapshot does not contain the machine definition, machine
  * version, running children, invoked process state, services, or subscriptions.
  * Store machine identity and migration metadata alongside the result when the
- * snapshot crosses deployment versions. Schema encoding does not by itself
- * guarantee JSON-compatible values; schemas used with JSON-backed storage must
- * have JSON-compatible encoded representations.
+ * snapshot crosses deployment versions. Opaque declarations without a JSON
+ * codec can encode only when their current value is already JSON-compatible.
+ * Define an explicit JSON codec or keep process-local capabilities outside the
+ * logical snapshot.
  *
  * **Example**
  *