@typeonce/effect-machine 0.3.0 → 0.4.0

package/dist/Machine.d.ts

@@ -5,17 +5,21 @@
  */
 import type * as Cause from "effect/Cause";
 import type * as Duration from "effect/Duration";
-import * as Effect from "effect/Effect";
-import * as Option from "effect/Option";
-import { type Pipeable } from "effect/Pipeable";
+import type * as Effect from "effect/Effect";
+import type * as Option from "effect/Option";
+import type { Pipeable } from "effect/Pipeable";
 import type * as Schema from "effect/Schema";
 import type * as Scope from "effect/Scope";
 import type * as Stream from "effect/Stream";
 import type * as Types from "effect/Types";
-import type { ChildAlreadyExistsError, InfiniteTransitionError, MachineSchemaDecodeError, MachineSchemaEncodeError, ProcessLocalError, StartupError, StoppedError } from "./internal/machineErrors.js";
-import * as Model from "./internal/machineModel.js";
-import * as internalPlanner from "./internal/machinePlanner.js";
-import * as internalRuntime from "./internal/machineRuntime.js";
+import type * as Activities from "./internal/machine/activities.js";
+import type { ChildAlreadyExistsError, InfiniteTransitionError, MachineSchemaDecodeError, MachineSchemaEncodeError, StartupError, StoppedError } from "./internal/machine/machine.js";
+import * as internal from "./internal/machine/machine.js";
+import { InitialEventTypeId } from "./internal/machine/machine.js";
+import type { EnsureExecutable } from "./internal/machine/readiness.js";
+import type * as internalRuntime from "./internal/machine/runtime.js";
+import type * as StateDefinition from "./internal/machine/stateDefinition.js";
+import type * as Topology from "./internal/machine/topology.js";
 /**
  * String literal type used as the runtime type identifier for `Machine`
  * values.
@@ -40,7 +44,7 @@ declare const MachineTypeId: unique symbol;
  * @category type IDs
  * @since 4.0.0
  */
-export declare const InitialEventTypeId: typeof internalPlanner.InitialEventTypeId;
+export { InitialEventTypeId };
 /**
  * Synthetic event passed to entry, exit, always, invoke, and output callbacks
  * that run while the machine is settling its initial state.
@@ -131,13 +135,16 @@ export interface Machine<States extends Machine.StateSchemas, Events extends Rea
     /** @internal */
     readonly stateNodes: Machine.StateNodes;
     /** @internal */
-    readonly makeTargetBuilder: <Source extends Machine.StateIdentifier<States>>(source: Source) => Machine.TargetBuilder<States, Source>;
+    readonly makeTargetBuilder: <Source extends Machine.StateNodeIdentifier<States>>(source: Source) => Machine.TargetBuilder<States, Source>;
     /** @internal */
     readonly handlers: Machine.StateConfigs<States, Events, Emits, UnhandledStates, Machine.TagOf<Events[number]>, E, R>;
     /**
      * Adds typed state handlers and returns the refined machine definition.
      * Successive calls implement the remaining unhandled states while retaining
      * accumulated errors, services, final states, and output evidence.
+     * Event dispatch maps and transition descriptors are captured by value, so
+     * later mutation of the objects supplied to this call cannot alter the
+     * resulting machine.
      *
      * @since 4.0.0
      */
@@ -201,7 +208,7 @@ StartupError,
  * @category errors
  * @since 4.0.0
  */
-StoppedError } from "./internal/machineErrors.js";
+StoppedError } from "./internal/machine/machine.js";
 declare const RuntimeRequirementTypeId = "~effect/Machine/RuntimeRequirement";
 declare const ActionRequirementTypeId = "~effect/Machine/ActionRequirement";
 type MachineRuntimeRequirement = internalRuntime.MachineRuntime;
@@ -247,7 +254,7 @@ export type PlanningServices<Requirements> = Exclude<Requirements, ActionRequire
  */
 export type ExecutionServices<Requirements> = Exclude<PlanningServices<Requirements>, MachineRuntimeRequirement> | Exclude<ActionServices<Requirements>, MachineRuntimeRequirement>;
 /**
- * Runtime capability available to machine actions.
+ * Managed runtime capability used to deliver raised and emitted events.
  *
  * @category models
  * @since 4.0.0
@@ -266,6 +273,39 @@ export interface Runtime<in Events, in Emits> {
      */
     readonly sendParent: (event: Emits) => Effect.Effect<void, MachineSchemaDecodeError | StoppedError>;
 }
+/**
+ * Synchronous commands available while a machine transition is being
+ * selected. Enqueuing only records statechart and actor operations; it never
+ * executes an Effect.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface Enqueue<in Events, in Emits> {
+    /** Raises an event inside the current macrostep. */
+    readonly raise: (event: Events) => void;
+    /** Emits an event through the machine's parent boundary. */
+    readonly emit: (event: Emits) => void;
+    /** Sends an event to an invoked child after the transition is selected. */
+    readonly sendTo: {
+        <Child extends ChildMachine.Any>(child: Child, event: ChildMachine.Event<Child>): void;
+        <Address extends ChildAddress<never>>(child: Address, event: ChildAddress.Event<Address>): void;
+    };
+    /** Stops an invoked child after the transition is selected. */
+    readonly stop: {
+        <Child extends ChildMachine.Any>(child: Child): void;
+        <Event>(child: ChildAddress<Event>): void;
+    };
+}
+/** A closed actor command recorded by a synchronous machine transition. */
+export type Command = {
+    readonly _tag: "SendTo";
+    readonly child: ChildMachine.Any | ChildAddress<never>;
+    readonly event: unknown;
+} | {
+    readonly _tag: "Stop";
+    readonly child: ChildMachine.Any | ChildAddress<never>;
+};
 /**
  * Namespace containing type-level members associated with `Runtime`.
  *
@@ -273,7 +313,7 @@ export interface Runtime<in Events, in Emits> {
  */
 export declare namespace Runtime {
     /**
-     * Protocol annotation accepted by {@link runtime}.
+     * Protocol annotation for managed event delivery.
      *
      * @category models
      * @since 4.0.0
@@ -315,44 +355,66 @@ export declare namespace Runtime {
 }
 type ExcludeCompatibleRuntime<Requirements, Events, Emits> = Requirements extends Runtime.Requirement<infer RequiredEvents, infer RequiredEmits> ? IsAny<Requirements> extends true ? Requirements : [RequiredEvents] extends [Events] ? [RequiredEmits] extends [Emits] ? never : Requirements : Requirements : Requirements;
 type IncompatibleRuntime<Requirements, Events, Emits> = Requirements extends Runtime.Requirement<infer RequiredEvents, infer RequiredEmits> ? IsAny<Requirements> extends true ? never : [RequiredEvents] extends [Events] ? [RequiredEmits] extends [Emits] ? never : Requirements : Requirements : never;
-declare const InvokeTypeId: unique symbol;
-type StateDefinitionError<Message extends string> = {
+declare const InvokeTypeId: typeof internal.InvokeTypeId;
+type StateDefinitionError<Message extends string, Path extends PropertyKey = never, Details extends PropertyKey = never> = {
     readonly "~effect/Machine/DefinitionError": Message;
+    readonly path: Path;
+    readonly details: Details;
 };
 type ActiveStateKey<States extends Machine.StateSchemas> = Machine.ActiveStateKey<States>;
 type HistoryStateKey<States extends Machine.StateSchemas> = Machine.HistoryStateKey<States>;
-type ValidateStateTree<States extends Machine.StateSchemas, AllowHistory extends boolean = false> = {
-    readonly [Key in keyof States]: ValidateStateNode<States[Key], AllowHistory>;
+type ChoiceStateKey<States extends Machine.StateSchemas> = Machine.ChoiceStateKey<States>;
+type StateDefinitionPath<Prefix extends string, Key extends PropertyKey> = Key extends string ? Key extends "" ? Prefix extends "" ? "<empty>" : `${Prefix}.<empty>` : Prefix extends "" ? Key : `${Prefix}.${Key}` : Key extends number ? Prefix extends "" ? `${Key}` : `${Prefix}.${Key}` : Prefix extends "" ? "<symbol>" : `${Prefix}.<symbol>`;
+type ValidateStateKey<Key extends PropertyKey, Prefix extends string> = Key extends symbol ? StateDefinitionError<"State keys must be strings, not symbols", StateDefinitionPath<Prefix, Key>, Key> : Key extends number ? StateDefinitionError<"State keys cannot use numeric forms", StateDefinitionPath<Prefix, Key>, Key> : Key extends "" ? StateDefinitionError<"State keys cannot be empty", StateDefinitionPath<Prefix, Key>, Key> : Key extends "__proto__" ? StateDefinitionError<"The state key \"__proto__\" is not allowed", StateDefinitionPath<Prefix, Key>, Key> : Key extends `${string}.${string}` ? StateDefinitionError<"State keys cannot contain \".\"", StateDefinitionPath<Prefix, Key>, Key> : Key extends `${number}` ? StateDefinitionError<"State keys cannot use numeric forms", StateDefinitionPath<Prefix, Key>, Key> : unknown;
+type ValidateStateTree<States extends Machine.StateSchemas, AllowHistory extends boolean = false, Prefix extends string = ""> = {
+    readonly [Key in keyof States]: ValidateStateKey<Key, Prefix> & ValidateStateNode<States[Key], AllowHistory, StateDefinitionPath<Prefix, Key>>;
 };
-type ValidateStateNode<Node, AllowHistory extends boolean> = Node extends Machine.HistoryStateNodeConfig ? AllowHistory extends true ? ValidateHistoryStateNode<Node> : StateDefinitionError<"History states must be declared below an active parent state"> : Node extends Machine.TaggedSchema ? unknown : Node extends {
+type UnknownStateNodeProperty<Node, Kind extends StateDefinition.StateNodeKind> = Exclude<keyof Node, StateDefinition.AllowedStateNodeProperty<Kind>>;
+type ValidateExactStateNodeProperties<Node, Kind extends StateDefinition.StateNodeKind, Path extends PropertyKey> = [UnknownStateNodeProperty<Node, Kind>] extends [never] ? unknown : StateDefinitionError<"State nodes cannot declare properties outside their state kind", Path, Extract<UnknownStateNodeProperty<Node, Kind>, PropertyKey>>;
+type UnknownPseudoAnnotationProperty<Node> = Node extends {
+    readonly annotations: infer Annotations;
+} ? Exclude<keyof Annotations, StateDefinition.AllowedPseudoStateAnnotationProperty> : never;
+type ValidatePseudoStateAnnotations<Node, Path extends PropertyKey> = [UnknownPseudoAnnotationProperty<Node>] extends [
+    never
+] ? unknown : StateDefinitionError<"Pseudo-state annotations contain unknown properties", Path, Extract<UnknownPseudoAnnotationProperty<Node>, PropertyKey>>;
+type ValidateStateNode<Node, AllowHistory extends boolean, Path extends PropertyKey> = Node extends Machine.TaggedSchema ? unknown : Node extends Machine.HistoryStateNodeConfig ? ValidateExactStateNodeProperties<Node, "history", Path> & ValidatePseudoStateAnnotations<Node, Path> & (AllowHistory extends true ? ValidateHistoryStateNode<Node> : StateDefinitionError<"History states must be declared below an active parent state", Path>) : Node extends Machine.ChoiceStateNodeConfig ? ValidateExactStateNodeProperties<Node, "choice", Path> & ValidatePseudoStateAnnotations<Node, Path> & (AllowHistory extends true ? ValidateChoiceStateNode<Node> : StateDefinitionError<"Choice states must be declared below an active parent state", Path>) : Node extends {
     readonly schema: Machine.TaggedSchema;
-} ? ValidateStateNodeConfig<Node> : StateDefinitionError<"State nodes must be tagged schemas or state node configs">;
+} ? ValidateStateNodeConfig<Node, Path> : StateDefinitionError<"State nodes must be tagged schemas or state node configs", Path>;
 type ValidateHistoryStateNode<Node extends Machine.HistoryStateNodeConfig> = [
-    Extract<keyof Node, "schema" | "states" | "initial" | "output">
+    Extract<keyof Node, "schema" | "states" | "initial" | "output" | "choice">
 ] extends [never] ? unknown : StateDefinitionError<"History states cannot declare schemas, children, initial states, or output">;
+type ValidateChoiceStateNode<Node extends Machine.ChoiceStateNodeConfig> = [
+    Extract<keyof Node, "schema" | "states" | "initial" | "output" | "history">
+] extends [never] ? unknown : StateDefinitionError<"Choice states cannot declare schemas, children, initial states, output, or history">;
 type ValidateStateNodeConfig<Node extends {
     readonly schema: Machine.TaggedSchema;
-}> = Node extends {
+}, Path extends PropertyKey> = Node extends {
+    readonly type: "parallel";
+} ? ValidateExactStateNodeProperties<Node, "parallel", Path> & ValidateStateNodeWithChildren<Node, Node extends {
+    readonly states: infer Children;
+} ? Children : never, Path> : Node extends {
+    readonly type: "final";
+} ? ValidateExactStateNodeProperties<Node, "final", Path> & ValidateStateNodeWithoutChildren<Node> : Node extends {
     readonly states: infer Children;
-} ? ValidateStateNodeWithChildren<Node, Children> : ValidateStateNodeWithoutChildren<Node>;
+} ? ValidateExactStateNodeProperties<Node, "compound", Path> & ValidateStateNodeWithChildren<Node, Children, Path> : ValidateExactStateNodeProperties<Node, "atomic", Path> & ValidateStateNodeWithoutChildren<Node>;
 type ValidateOutputSchema<Node> = "output" extends keyof Node ? Node extends {
     readonly output: Schema.Top;
 } ? unknown : StateDefinitionError<"State output must be a schema"> : unknown;
 type ValidateStateNodeWithChildren<Node extends {
     readonly schema: Machine.TaggedSchema;
-}, Children> = Children extends Machine.StateSchemas ? Node extends {
+}, Children, Path extends PropertyKey> = Children extends Machine.StateSchemas ? Node extends {
     readonly type: "final";
 } ? StateDefinitionError<"Final states cannot declare child states"> : Node extends {
     readonly type: "parallel";
 } ? "initial" extends keyof Node ? StateDefinitionError<"Parallel states cannot declare an initial child"> : {
-    readonly states: ValidateStateTree<Children, true>;
-} & ValidateOutputSchema<Node> : "output" extends keyof Node ? StateDefinitionError<"Only final and parallel states can declare output"> : ValidateCompoundStateNode<Node, Children> : StateDefinitionError<"Child states must be a state tree">;
+    readonly states: ValidateStateTree<Children, true, Extract<Path, string>>;
+} & ValidateOutputSchema<Node> : "output" extends keyof Node ? StateDefinitionError<"Only final and parallel states can declare output"> : ValidateCompoundStateNode<Node, Children, Path> : StateDefinitionError<"Child states must be a state tree">;
 type ValidateCompoundStateNode<Node extends {
     readonly schema: Machine.TaggedSchema;
-}, Children extends Machine.StateSchemas> = Node extends {
+}, Children extends Machine.StateSchemas, Path extends PropertyKey> = Node extends {
     readonly initial: infer Initial;
-} ? Initial extends ActiveStateKey<Children> ? {
-    readonly states: ValidateStateTree<Children, true>;
+} ? Initial extends ActiveStateKey<Children> | ChoiceStateKey<Children> ? {
+    readonly states: ValidateStateTree<Children, true, Extract<Path, string>>;
 } : StateDefinitionError<"Compound initial must be one of its direct child keys"> : StateDefinitionError<"Compound states must declare an initial child">;
 type ValidateStateNodeWithoutChildren<Node extends {
     readonly schema: Machine.TaggedSchema;
@@ -362,7 +424,7 @@ type ValidateStateNodeWithoutChildren<Node extends {
 type DefineStateTreeInput<States extends Machine.StateSchemas> = {
     readonly [Key in keyof States]: DefineStateNodeInput<States[Key]>;
 };
-type DefineStateNodeInput<Node> = Node extends Machine.TaggedSchema ? Node : Node extends Machine.HistoryStateNodeConfig ? Machine.HistoryStateNodeConfig : Node extends {
+type DefineStateNodeInput<Node> = Node extends Machine.TaggedSchema ? Node : Node extends Machine.HistoryStateNodeConfig ? Machine.HistoryStateNodeConfig : Node extends Machine.ChoiceStateNodeConfig ? Machine.ChoiceStateNodeConfig : Node extends {
     readonly type: "parallel";
     readonly states: infer Children extends Machine.StateSchemas;
 } ? Omit<Node, "states"> & {
@@ -370,7 +432,7 @@ type DefineStateNodeInput<Node> = Node extends Machine.TaggedSchema ? Node : Nod
 } : Node extends {
     readonly states: infer Children extends Machine.StateSchemas;
 } ? Omit<Node, "initial" | "states"> & {
-    readonly initial: ActiveStateKey<Children>;
+    readonly initial: ActiveStateKey<Children> | ChoiceStateKey<Children>;
     readonly states: DefineStateTreeInput<Children>;
 } : Node;
 type ValidateDefinedStates<States extends Machine.StateSchemas> = [States] extends [
@@ -393,7 +455,7 @@ type DuplicateEventTag<Events extends ReadonlyArray<Machine.TaggedSchema>, Seen
 ] ? Machine.TagOf<Head> extends infer Tag extends PropertyKey ? Tag extends Seen ? Tag | DuplicateEventTag<Tail, Seen> : DuplicateEventTag<Tail, Seen | Tag> : never : never;
 type ValidateInputEventProtocol<InputEvents extends ReadonlyArray<Machine.TaggedSchema>, DuplicateInput extends PropertyKey = DuplicateEventTag<InputEvents>> = [DuplicateInput] extends [never] ? unknown : EventProtocolError<"Public event tags must be unique", DuplicateInput>;
 type ValidateInternalEventProtocol<InputEvents extends ReadonlyArray<Machine.TaggedSchema>, InternalEvents extends ReadonlyArray<Machine.TaggedSchema>, DuplicateInternal extends PropertyKey = DuplicateEventTag<InternalEvents>, Overlap extends PropertyKey = Extract<Machine.TagOf<InputEvents[number]>, Machine.TagOf<InternalEvents[number]>>> = [DuplicateInternal] extends [never] ? [Overlap] extends [never] ? unknown : EventProtocolError<"Public and internal event tags must be disjoint", Overlap> : EventProtocolError<"Internal event tags must be unique", DuplicateInternal>;
-declare const SnapshotBuilderStateTypeId: unique symbol;
+declare const SnapshotBuilderStateTypeId: typeof internal.SnapshotBuilderStateTypeId;
 declare const SnapshotBuilderConstructionTypeId: unique symbol;
 type SnapshotBuilderComplete<Regions, Constructed extends boolean = false> = {
     readonly [SnapshotBuilderStateTypeId]: Regions;
@@ -421,6 +483,8 @@ type ConstructionSelectorFromCallable<Input, Builder, Result> = {} extends Input
 } : <Selected extends ConstructionResult<Result>>(input: Input, state: (builder: Builder) => Selected) => Machine.StateConstruction<UnwrapConstruction<Selected>>;
 type InitialSnapshotBuilderWithPrefix<States extends Machine.StateSchemas, Prefix extends string = ""> = {
     readonly [Key in ActiveStateKey<States>]: InitialSnapshotMethod<States, Key, Prefix>;
+} & {
+    readonly [Key in ChoiceStateKey<States>]: () => Machine.ChoiceTargetInstruction<Machine.JoinPath<Prefix, Key>>;
 };
 type InitialSnapshotMethod<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string> = ((...args: InitialSnapshotArguments<States, StateId, Prefix>) => InitialSnapshotResult<States, StateId, Prefix>) & FromMethod<InitialSnapshotFromArguments<States, StateId, Prefix>, InitialSnapshotResult<States, StateId, Prefix>>;
 type InitialSnapshotArguments<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string, Path extends string = Machine.JoinPath<Prefix, StateId>> = States[StateId] extends infer Node ? Node extends {
@@ -432,10 +496,10 @@ type InitialSnapshotArguments<States extends Machine.StateSchemas, StateId exten
 ] : Node extends {
     readonly states: infer Children extends Machine.StateSchemas;
 } ? Node extends {
-    readonly initial: infer Initial extends ActiveStateKey<Children>;
+    readonly initial: infer Initial extends ActiveStateKey<Children> | ChoiceStateKey<Children>;
 } ? [
     value: Machine.NodeSchema<Node>["Type"],
-    state: (builder: Pick<InitialSnapshotBuilderWithPrefix<Children, Path>, Initial>) => InitialSnapshotResult<Children, Initial, Path>
+    state: (builder: Pick<InitialSnapshotBuilderWithPrefix<Children, Path>, Initial>) => InitialSelectableResult<Children, Initial, Path>
 ] : never : [value: Machine.NodeSchema<Node>["Type"]] : never;
 type InitialSnapshotFromArguments<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string, Path extends string = Machine.JoinPath<Prefix, StateId>> = States[StateId] extends infer Node ? Node extends {
     readonly type: "parallel";
@@ -446,10 +510,10 @@ type InitialSnapshotFromArguments<States extends Machine.StateSchemas, StateId e
 ] : Node extends {
     readonly states: infer Children extends Machine.StateSchemas;
 } ? Node extends {
-    readonly initial: infer Initial extends ActiveStateKey<Children>;
+    readonly initial: infer Initial extends ActiveStateKey<Children> | ChoiceStateKey<Children>;
 } ? [
     input: Machine.NodeSchema<Node>["~type.make.in"],
-    state: (builder: Pick<InitialSnapshotBuilderWithPrefix<Children, Path>, Initial>) => ConstructionResult<InitialSnapshotResult<Children, Initial, Path>>
+    state: (builder: Pick<InitialSnapshotBuilderWithPrefix<Children, Path>, Initial>) => ConstructionResult<InitialSelectableResult<Children, Initial, Path>>
 ] : never : [input: Machine.NodeSchema<Node>["~type.make.in"]] : never;
 type InitialSnapshotResult<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string, Path extends string = Machine.JoinPath<Prefix, StateId>> = States[StateId] extends infer Node ? Node extends {
     readonly type: "parallel";
@@ -457,8 +521,9 @@ type InitialSnapshotResult<States extends Machine.StateSchemas, StateId extends
 } ? Machine.ParallelSnapshot<Path, Machine.NodeSchema<Node>["Type"], InitialSnapshotRegionsWithPrefix<Children, Path>> : Node extends {
     readonly states: infer Children extends Machine.StateSchemas;
 } ? Node extends {
-    readonly initial: infer Initial extends ActiveStateKey<Children>;
-} ? Machine.CompoundSnapshot<Path, Machine.NodeSchema<Node>["Type"], InitialSnapshotResult<Children, Initial, Path>> : never : Machine.AtomicSnapshot<Path, Machine.NodeSchema<Node>["Type"]> : never;
+    readonly initial: infer Initial extends ActiveStateKey<Children> | ChoiceStateKey<Children>;
+} ? Machine.CompoundSnapshot<Path, Machine.NodeSchema<Node>["Type"], InitialSelectableResult<Children, Initial, Path>> : never : Machine.AtomicSnapshot<Path, Machine.NodeSchema<Node>["Type"]> : never;
+type InitialSelectableResult<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States> | ChoiceStateKey<States>, Prefix extends string> = StateId extends ChoiceStateKey<States> ? Machine.ChoiceTargetInstruction<Machine.JoinPath<Prefix, StateId>> : StateId extends ActiveStateKey<States> ? InitialSnapshotResult<States, StateId, Prefix> : never;
 type InitialSnapshotRegionsWithPrefix<States extends Machine.StateSchemas, Prefix extends string> = {
     readonly [Key in ActiveStateKey<States>]: InitialSnapshotResult<States, Key, Prefix>;
 };
@@ -473,6 +538,8 @@ type InitialParallelBuilder<States extends Machine.StateSchemas, Prefix extends
 };
 type FullSnapshotBuilderWithPrefix<States extends Machine.StateSchemas, Prefix extends string = ""> = {
     readonly [Key in ActiveStateKey<States>]: FullSnapshotMethod<States, Key, Prefix>;
+} & {
+    readonly [Key in ChoiceStateKey<States>]: () => Machine.ChoiceTargetInstruction<Machine.JoinPath<Prefix, Key>>;
 };
 type FullSnapshotMethod<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string> = ((...args: FullSnapshotArguments<States, StateId, Prefix>) => FullSnapshotResult<States, StateId, Prefix>) & FromMethod<FullSnapshotFromArguments<States, StateId, Prefix>, FullSnapshotResult<States, StateId, Prefix>>;
 type FullSnapshotArguments<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string, Path extends string = Machine.JoinPath<Prefix, StateId>> = States[StateId] extends infer Node ? Node extends {
@@ -485,7 +552,7 @@ type FullSnapshotArguments<States extends Machine.StateSchemas, StateId extends
     readonly states: infer Children extends Machine.StateSchemas;
 } ? [
     value: Machine.NodeSchema<Node>["Type"],
-    state: (builder: FullSnapshotBuilderWithPrefix<Children, Path>) => Machine.SnapshotWithPrefix<Children, Path>
+    state: (builder: FullSnapshotBuilderWithPrefix<Children, Path>) => Machine.SnapshotWithPrefix<Children, Path> | Machine.ChoiceTargetInstruction<Machine.ChoiceIdentifierWithPrefix<Children, Path>>
 ] : [value: Machine.NodeSchema<Node>["Type"]] : never;
 type FullSnapshotFromArguments<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string, Path extends string = Machine.JoinPath<Prefix, StateId>> = States[StateId] extends infer Node ? Node extends {
     readonly type: "parallel";
@@ -497,7 +564,7 @@ type FullSnapshotFromArguments<States extends Machine.StateSchemas, StateId exte
     readonly states: infer Children extends Machine.StateSchemas;
 } ? [
     input: Machine.NodeSchema<Node>["~type.make.in"],
-    state: (builder: FullSnapshotBuilderWithPrefix<Children, Path>) => ConstructionResult<Machine.SnapshotWithPrefix<Children, Path>>
+    state: (builder: FullSnapshotBuilderWithPrefix<Children, Path>) => ConstructionResult<Machine.SnapshotWithPrefix<Children, Path> | Machine.ChoiceTargetInstruction<Machine.ChoiceIdentifierWithPrefix<Children, Path>>>
 ] : [input: Machine.NodeSchema<Node>["~type.make.in"]] : never;
 type FullSnapshotResult<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string, Path extends string = Machine.JoinPath<Prefix, StateId>> = Machine.SnapshotByIdentifierWithPath<States, StateId, Path>;
 type FullParallelBuilder<States extends Machine.StateSchemas, Prefix extends string, Remaining extends ActiveStateKey<States> = ActiveStateKey<States>, Regions = {}, Constructed extends boolean = false> = SnapshotBuilderComplete<Regions, Constructed> & {
@@ -509,13 +576,68 @@ type FullParallelBuilder<States extends Machine.StateSchemas, Prefix extends str
         }, true>>;
     };
 };
+type HistorySnapshotArguments<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string, Owner extends string, Path extends string = Machine.JoinPath<Prefix, StateId>> = Path extends Owner ? FullSnapshotArguments<States, StateId, Prefix> : States[StateId] extends infer Node ? Node extends {
+    readonly type: "parallel";
+    readonly states: infer Children extends Machine.StateSchemas;
+} ? [
+    value: Machine.NodeSchema<Node>["Type"],
+    states: (builder: HistoryParallelBuilder<Children, Path, Owner>) => SnapshotBuilderComplete<HistorySnapshotRegions<Children, Path, Owner>>
+] : Node extends {
+    readonly states: infer Children extends Machine.StateSchemas;
+} ? [
+    value: Machine.NodeSchema<Node>["Type"],
+    state: (builder: HistorySnapshotBuilderWithPrefix<Children, Owner, Path>) => ConstructionResult<HistorySnapshotWithPrefix<Children, Owner, Path>>
+] : never : never;
+type HistorySnapshotFromArguments<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string, Owner extends string, Path extends string = Machine.JoinPath<Prefix, StateId>> = Path extends Owner ? FullSnapshotFromArguments<States, StateId, Prefix> : States[StateId] extends infer Node ? Node extends {
+    readonly type: "parallel";
+    readonly states: infer Children extends Machine.StateSchemas;
+} ? [
+    input: Machine.NodeSchema<Node>["~type.make.in"],
+    states: (builder: HistoryParallelBuilder<Children, Path, Owner>) => SnapshotBuilderComplete<HistorySnapshotRegions<Children, Path, Owner>, boolean>
+] : Node extends {
+    readonly states: infer Children extends Machine.StateSchemas;
+} ? [
+    input: Machine.NodeSchema<Node>["~type.make.in"],
+    state: (builder: HistorySnapshotBuilderWithPrefix<Children, Owner, Path>) => ConstructionResult<HistorySnapshotWithPrefix<Children, Owner, Path>>
+] : never : never;
+type HistorySnapshotResult<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string, Owner extends string, Path extends string = Machine.JoinPath<Prefix, StateId>> = Path extends Owner ? FullSnapshotResult<States, StateId, Prefix> : States[StateId] extends infer Node ? Node extends {
+    readonly type: "parallel";
+    readonly states: infer Children extends Machine.StateSchemas;
+} ? Machine.ParallelSnapshot<Path, Machine.NodeSchema<Node>["Type"], HistorySnapshotRegions<Children, Path, Owner>> : Node extends {
+    readonly states: infer Children extends Machine.StateSchemas;
+} ? Machine.CompoundSnapshot<Path, Machine.NodeSchema<Node>["Type"], HistorySnapshotWithPrefix<Children, Owner, Path>> : never : never;
+type HistorySnapshotMethod<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string, Owner extends string> = ((...args: HistorySnapshotArguments<States, StateId, Prefix, Owner>) => HistorySnapshotResult<States, StateId, Prefix, Owner>) & FromMethod<HistorySnapshotFromArguments<States, StateId, Prefix, Owner>, HistorySnapshotResult<States, StateId, Prefix, Owner>>;
+type HistorySnapshotWithPrefix<States extends Machine.StateSchemas, Owner extends string, Prefix extends string> = {
+    readonly [Key in ActiveStateKey<States>]: Owner extends Machine.JoinPath<Prefix, Key> | `${Machine.JoinPath<Prefix, Key>}.${string}` ? HistorySnapshotResult<States, Key, Prefix, Owner> : never;
+}[ActiveStateKey<States>];
+type HistorySnapshotBuilderWithPrefix<States extends Machine.StateSchemas, Owner extends string, Prefix extends string = ""> = {
+    readonly [Key in ActiveStateKey<States> as Owner extends Machine.JoinPath<Prefix, Key> | `${Machine.JoinPath<Prefix, Key>}.${string}` ? Key : never]: HistorySnapshotMethod<States, Key, Prefix, Owner>;
+};
+type HistorySnapshotRegions<States extends Machine.StateSchemas, Prefix extends string, Owner extends string> = {
+    readonly [Key in ActiveStateKey<States>]: Owner extends Machine.JoinPath<Prefix, Key> | `${Machine.JoinPath<Prefix, Key>}.${string}` ? HistorySnapshotResult<States, Key, Prefix, Owner> : FullSnapshotResult<States, Key, Prefix>;
+};
+type HistoryParallelBuilder<States extends Machine.StateSchemas, Prefix extends string, Owner extends string, Remaining extends ActiveStateKey<States> = ActiveStateKey<States>, Regions = {}, Constructed extends boolean = false> = SnapshotBuilderComplete<Regions, Constructed> & {
+    readonly [Key in Remaining]: Owner extends Machine.JoinPath<Prefix, Key> | `${Machine.JoinPath<Prefix, Key>}.${string}` ? ((...args: HistorySnapshotArguments<States, Key, Prefix, Owner>) => HistoryParallelBuilder<States, Prefix, Owner, Exclude<Remaining, Key>, Regions & {
+        readonly [Region in Key]: HistorySnapshotResult<States, Key, Prefix, Owner>;
+    }, Constructed>) & {
+        readonly from: FromCallable<HistorySnapshotFromArguments<States, Key, Prefix, Owner>, HistoryParallelBuilder<States, Prefix, Owner, Exclude<Remaining, Key>, Regions & {
+            readonly [Region in Key]: HistorySnapshotResult<States, Key, Prefix, Owner>;
+        }, true>>;
+    } : ((...args: FullSnapshotArguments<States, Key, Prefix>) => HistoryParallelBuilder<States, Prefix, Owner, Exclude<Remaining, Key>, Regions & {
+        readonly [Region in Key]: FullSnapshotResult<States, Key, Prefix>;
+    }, Constructed>) & {
+        readonly from: FromCallable<FullSnapshotFromArguments<States, Key, Prefix>, HistoryParallelBuilder<States, Prefix, Owner, Exclude<Remaining, Key>, Regions & {
+            readonly [Region in Key]: FullSnapshotResult<States, Key, Prefix>;
+        }, true>>;
+    };
+};
 type ParentPath<Path extends string> = Path extends `${infer Parent}.${infer Child}` ? Child extends `${string}.${string}` ? `${Parent}.${ParentPath<Child>}` : Parent : never;
 type IsCompoundNode<Node> = Node extends {
     readonly type: "parallel";
 } ? false : Node extends {
     readonly states: Machine.StateSchemas;
 } ? true : false;
-type NearestCompoundScope<States extends Machine.StateSchemas, Source extends Machine.StateIdentifier<States>> = IsCompoundNode<Machine.NodeByIdentifier<States, Source>> extends true ? Source : ParentPath<Source> extends infer Parent extends Machine.StateIdentifier<States> ? NearestCompoundScope<States, Parent> : never;
+type NearestCompoundScope<States extends Machine.StateSchemas, Source extends Machine.StateNodeIdentifier<States>> = Source extends Machine.StateIdentifier<States> ? IsCompoundNode<Machine.NodeByIdentifier<States, Source>> extends true ? Source : ParentPath<Source> extends infer Parent extends Machine.StateIdentifier<States> ? NearestCompoundScope<States, Parent> : never : ParentPath<Source> extends infer Parent extends Machine.StateIdentifier<States> ? NearestCompoundScope<States, Parent> : never;
 type ChildrenOf<States extends Machine.StateSchemas, Path extends Machine.StateIdentifier<States>> = Machine.NodeByIdentifier<States, Path> extends {
     readonly states: infer Children extends Machine.StateSchemas;
 } ? Children : never;
@@ -527,11 +649,13 @@ type LocalTargetResult<AllStates extends Machine.StateSchemas, States extends Ma
 } ? Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>> : LocalTargetResultWithPrefix<AllStates, Children, Path> : Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>>;
 type LocalTargetResultWithPrefix<AllStates extends Machine.StateSchemas, States extends Machine.StateSchemas, Prefix extends string> = {
     readonly [Key in ActiveStateKey<States>]: LocalTargetResult<AllStates, States, Key, Prefix>;
-}[ActiveStateKey<States>];
-type LocalTargetBuilderWithPrefix<AllStates extends Machine.StateSchemas, States extends Machine.StateSchemas, Prefix extends string, Source extends Machine.StateIdentifier<AllStates>> = {
+}[ActiveStateKey<States>] | Machine.ChoiceTarget<AllStates, Extract<Machine.JoinPath<Prefix, ChoiceStateKey<States>>, Machine.ChoiceIdentifier<AllStates>>>;
+type LocalTargetBuilderWithPrefix<AllStates extends Machine.StateSchemas, States extends Machine.StateSchemas, Prefix extends string, Source extends Machine.StateNodeIdentifier<AllStates>> = {
     readonly [Key in ActiveStateKey<States>]: LocalTargetMethod<AllStates, States, Key, Prefix, Source>;
+} & {
+    readonly [Key in ChoiceStateKey<States>]: () => Machine.ChoiceTarget<AllStates, Extract<Machine.JoinPath<Prefix, Key>, Machine.ChoiceIdentifier<AllStates>>>;
 };
-type LocalTargetMethod<AllStates extends Machine.StateSchemas, States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string, Source extends Machine.StateIdentifier<AllStates>, Path extends string = Machine.JoinPath<Prefix, StateId>> = States[StateId] extends infer Node ? Node extends {
+type LocalTargetMethod<AllStates extends Machine.StateSchemas, States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string, Source extends Machine.StateNodeIdentifier<AllStates>, Path extends string = Machine.JoinPath<Prefix, StateId>> = States[StateId] extends infer Node ? Node extends {
     readonly type: "parallel";
     readonly states: infer Children extends Machine.StateSchemas;
 } ? Source extends Path | `${Path}.${string}` ? (<Result extends ConstructionResult<LocalTargetResultWithPrefix<AllStates, Children, Path>>>(value: Machine.NodeSchema<Node>["Type"], state: (builder: LocalTargetBuilderWithPrefix<AllStates, Children, Path, Source>) => Result) => Result) & {
@@ -546,7 +670,7 @@ type LocalTargetMethod<AllStates extends Machine.StateSchemas, States extends Ma
 } : ((value: Machine.NodeSchema<Node>["Type"]) => Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>>) & FromMethod<[
     input: Machine.NodeSchema<Node>["~type.make.in"]
 ], Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>>> : never;
-type LocalTargetBuilderForScope<States extends Machine.StateSchemas, Scope extends Machine.StateIdentifier<States>, Source extends Machine.StateIdentifier<States>> = ChildrenOf<States, Scope> extends infer Children extends Machine.StateSchemas ? LocalTargetBuilderWithPrefix<States, Children, Scope, Source> & {
+type LocalTargetBuilderForScope<States extends Machine.StateSchemas, Scope extends Machine.StateIdentifier<States>, Source extends Machine.StateNodeIdentifier<States>> = ChildrenOf<States, Scope> extends infer Children extends Machine.StateSchemas ? LocalTargetBuilderWithPrefix<States, Children, Scope, Source> & {
     /**
      * Updates the value of the state containing the local group and moves to
      * one of the states inside it. Values in other active branches are kept.
@@ -564,11 +688,13 @@ type BranchTargetResult<AllStates extends Machine.StateSchemas, States extends M
 } ? Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>> : BranchTargetResultWithPrefix<AllStates, Children, Path> : Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>>;
 type BranchTargetResultWithPrefix<AllStates extends Machine.StateSchemas, States extends Machine.StateSchemas, Prefix extends string> = {
     readonly [Key in ActiveStateKey<States>]: BranchTargetResult<AllStates, States, Key, Prefix>;
-}[ActiveStateKey<States>];
-type BranchTargetBuilderWithPrefix<AllStates extends Machine.StateSchemas, States extends Machine.StateSchemas, Prefix extends string, Source extends Machine.StateIdentifier<AllStates>> = {
+}[ActiveStateKey<States>] | Machine.ChoiceTarget<AllStates, Extract<Machine.JoinPath<Prefix, ChoiceStateKey<States>>, Machine.ChoiceIdentifier<AllStates>>>;
+type BranchTargetBuilderWithPrefix<AllStates extends Machine.StateSchemas, States extends Machine.StateSchemas, Prefix extends string, Source extends Machine.StateNodeIdentifier<AllStates>> = {
     readonly [Key in ActiveStateKey<States>]: BranchTargetMethod<AllStates, States, Key, Prefix, Source>;
+} & {
+    readonly [Key in ChoiceStateKey<States>]: () => Machine.ChoiceTarget<AllStates, Extract<Machine.JoinPath<Prefix, Key>, Machine.ChoiceIdentifier<AllStates>>>;
 };
-type BranchTargetMethod<AllStates extends Machine.StateSchemas, States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string, Source extends Machine.StateIdentifier<AllStates>, Path extends string = Machine.JoinPath<Prefix, StateId>> = States[StateId] extends infer Node ? Node extends {
+type BranchTargetMethod<AllStates extends Machine.StateSchemas, States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string, Source extends Machine.StateNodeIdentifier<AllStates>, Path extends string = Machine.JoinPath<Prefix, StateId>> = States[StateId] extends infer Node ? Node extends {
     readonly type: "parallel";
     readonly states: infer Children extends Machine.StateSchemas;
 } ? Source extends Path | `${Path}.${string}` ? (<Result extends ConstructionResult<BranchTargetResultWithPrefix<AllStates, Children, Path>>>(value: Machine.NodeSchema<Node>["Type"], state: (builder: BranchTargetBuilderWithPrefix<AllStates, Children, Path, Source>) => Result) => Result) & {
@@ -583,7 +709,7 @@ type BranchTargetMethod<AllStates extends Machine.StateSchemas, States extends M
 } & BranchTargetBuilderWithPrefix<AllStates, Children, Path, Source> : ((value: Machine.NodeSchema<Node>["Type"]) => Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>>) & FromMethod<[
     input: Machine.NodeSchema<Node>["~type.make.in"]
 ], Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>>> : never;
-type BranchTargetBuilderForRoot<States extends Machine.StateSchemas, Root extends ActiveStateKey<States>, Source extends Machine.StateIdentifier<States>> = {
+type BranchTargetBuilderForRoot<States extends Machine.StateSchemas, Root extends ActiveStateKey<States>, Source extends Machine.StateNodeIdentifier<States>> = {
     readonly [Key in Root]: BranchTargetMethod<States, States, Key, "", Source>;
 };
 type HistoryContainingKey<States extends Machine.StateSchemas> = {
@@ -1002,6 +1128,7 @@ export declare namespace Machine {
         readonly emits: ReadonlyArray<TaggedSchema>;
         readonly input: Schema.Top | undefined;
         readonly id: string | undefined;
+        /** @internal */
         readonly stateNodes: StateNodes;
         /** @internal */
         readonly makeTargetBuilder: any;
@@ -1139,6 +1266,23 @@ export declare namespace Machine {
             readonly _tag: PropertyKey;
         };
     };
+    /**
+     * Descriptive annotations exposed for compiled state nodes.
+     *
+     * Schema-backed states resolve their complete Effect Schema annotation map.
+     * Pseudo-states accept only the descriptive fields below. Annotations never
+     * affect state identity, targeting, or runtime behavior.
+     *
+     * @category models
+     * @since 4.0.0
+     */
+    interface StateNodeAnnotations extends Schema.Annotations.Annotations {
+        readonly title?: string | undefined;
+        readonly description?: string | undefined;
+        readonly documentation?: string | undefined;
+    }
+    /** Descriptive annotations accepted by schema-less pseudo-states. */
+    type PseudoStateAnnotations = Pick<StateNodeAnnotations, "title" | "description" | "documentation">;
     /**
      * Configuration accepted for an atomic object state node.
      *
@@ -1183,6 +1327,9 @@ export declare namespace Machine {
      *
      * History nodes are transition targets only. They never become active and
      * therefore do not declare a state value schema or lifecycle handlers.
+     * Both recorded history and a first-use default can rebuild inactive
+     * ancestors. A default is a complete root configuration containing the
+     * history owner, so its validity is independent of the transition source.
      *
      * @category models
      * @since 4.0.0
@@ -1191,6 +1338,21 @@ export declare namespace Machine {
         readonly type: "history";
         /** Defaults to shallow history. */
         readonly history?: "shallow" | "deep";
+        readonly annotations?: PseudoStateAnnotations;
+    }
+    /**
+     * Transient decision pseudo-state resolved immediately when targeted.
+     *
+     * Choice nodes have no value and never belong to an active configuration.
+     * Their required `choice` implementation uses ordinary TypeScript or an
+     * Effect to select a typed target.
+     *
+     * @category models
+     * @since 4.0.0
+     */
+    interface ChoiceStateNodeConfig {
+        readonly type: "choice";
+        readonly annotations?: PseudoStateAnnotations;
     }
     /**
      * Configuration accepted for an object state node.
@@ -1198,10 +1360,13 @@ export declare namespace Machine {
      * @category models
      * @since 4.0.0
      */
-    type StateNodeConfig = AtomicStateNodeConfig | CompoundStateNodeConfig | ParallelStateNodeConfig | HistoryStateNodeConfig;
+    type StateNodeConfig = AtomicStateNodeConfig | CompoundStateNodeConfig | ParallelStateNodeConfig | HistoryStateNodeConfig | ChoiceStateNodeConfig;
     /**
      * Object state tree keyed by state path.
      *
+     * Keys must be non-empty, non-numeric strings without `.`. The
+     * prototype-mutating key `__proto__` and symbol keys are not accepted.
+     *
      * @category models
      * @since 4.0.0
      */
@@ -1284,33 +1449,171 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     type ValidateStateSchemas<States extends StateSchemas> = ValidateStateTree<States>;
+    /** Properties shared by every compiled state-node variant. */
+    interface StateNodeBase<Path extends string = string> {
+        readonly path: Path;
+        readonly key: string;
+        /** Resolved Effect Schema annotations, or descriptive pseudo-state annotations. */
+        readonly annotations: Readonly<StateNodeAnnotations> | undefined;
+        readonly order: number;
+    }
+    /** Runtime metadata for a compiled atomic state. */
+    interface AtomicStateNode<OwnPath extends string = string, ActivePath extends string = OwnPath> extends StateNodeBase<OwnPath> {
+        readonly type: "atomic";
+        readonly schema: TaggedSchema;
+        readonly output: undefined;
+        readonly history: undefined;
+        readonly parent: ActivePath | undefined;
+        readonly children: readonly [];
+        readonly initial: undefined;
+    }
+    /** Runtime metadata for a compiled compound state. */
+    interface CompoundStateNode<OwnPath extends string = string, ActivePath extends string = OwnPath, ChoicePath extends string = ActivePath> extends StateNodeBase<OwnPath> {
+        readonly type: "compound";
+        readonly schema: TaggedSchema;
+        readonly output: undefined;
+        readonly history: undefined;
+        readonly parent: ActivePath | undefined;
+        /** Active child paths. Pseudo-states are available through their `parent` relationship. */
+        readonly children: ReadonlyArray<ActivePath>;
+        readonly initial: ActivePath | ChoicePath;
+    }
+    /** Runtime metadata for a compiled parallel state. */
+    interface ParallelStateNode<OwnPath extends string = string, ActivePath extends string = OwnPath> extends StateNodeBase<OwnPath> {
+        readonly type: "parallel";
+        readonly schema: TaggedSchema;
+        readonly output: Schema.Top | undefined;
+        readonly history: undefined;
+        readonly parent: ActivePath | undefined;
+        /** Active child paths. Pseudo-states are available through their `parent` relationship. */
+        readonly children: ReadonlyArray<ActivePath>;
+        readonly initial: undefined;
+    }
+    /** Runtime metadata for a compiled final state. */
+    interface FinalStateNode<OwnPath extends string = string, ActivePath extends string = OwnPath> extends StateNodeBase<OwnPath> {
+        readonly type: "final";
+        readonly schema: TaggedSchema;
+        readonly output: Schema.Top | undefined;
+        readonly history: undefined;
+        readonly parent: ActivePath | undefined;
+        readonly children: readonly [];
+        readonly initial: undefined;
+    }
+    /** Runtime metadata for a compiled history pseudo-state. */
+    interface HistoryStateNode<OwnPath extends string = string, ActivePath extends string = string> extends StateNodeBase<OwnPath> {
+        readonly type: "history";
+        readonly schema: undefined;
+        readonly output: undefined;
+        readonly history: "shallow" | "deep";
+        readonly parent: ActivePath;
+        readonly children: readonly [];
+        readonly initial: undefined;
+    }
+    /** Runtime metadata for a compiled choice pseudo-state. */
+    interface ChoiceStateNode<OwnPath extends string = string, ActivePath extends string = string> extends StateNodeBase<OwnPath> {
+        readonly type: "choice";
+        readonly schema: undefined;
+        readonly output: undefined;
+        readonly history: undefined;
+        readonly parent: ActivePath;
+        readonly children: readonly [];
+        readonly initial: undefined;
+    }
     /**
      * Runtime metadata for a compiled state node.
      *
+     * The `type` discriminator narrows every kind-specific topology and schema
+     * property while preserving a uniform inspection shape.
+     *
      * @category models
      * @since 4.0.0
      */
-    interface StateNode {
-        readonly path: string;
-        readonly key: string;
-        readonly schema: TaggedSchema | undefined;
-        readonly output: Schema.Top | undefined;
-        readonly type: "atomic" | "compound" | "parallel" | "final" | "history";
-        readonly history: "shallow" | "deep" | undefined;
-        readonly parent: string | undefined;
-        readonly children: ReadonlyArray<string>;
-        readonly initial: string | undefined;
-        readonly order: number;
-    }
+    type ActiveStateNode<ActivePath extends string = string, ChoicePath extends string = ActivePath> = AtomicStateNode<ActivePath, ActivePath> | CompoundStateNode<ActivePath, ActivePath, ChoicePath> | ParallelStateNode<ActivePath, ActivePath> | FinalStateNode<ActivePath, ActivePath>;
+    type StateNode<ActivePath extends string = string, HistoryPath extends string = ActivePath, ChoicePath extends string = ActivePath> = ActiveStateNode<ActivePath, ChoicePath> | HistoryStateNode<HistoryPath, ActivePath> | ChoiceStateNode<ChoicePath, ActivePath>;
     /**
      * Runtime lookup table for state nodes.
      *
      * @category models
      * @since 4.0.0
      */
-    interface StateNodes {
-        readonly byPath: ReadonlyMap<string, StateNode>;
-        readonly roots: ReadonlyArray<string>;
+    interface StateNodes<ActivePath extends string = string, HistoryPath extends string = ActivePath, ChoicePath extends string = ActivePath> {
+        readonly byPath: ReadonlyMap<ActivePath | HistoryPath | ChoicePath, StateNode<ActivePath, HistoryPath, ChoicePath>>;
+        readonly roots: ReadonlyArray<ActivePath>;
+    }
+    /**
+     * Trigger that selects a registered transition handler.
+     *
+     * @category models
+     * @since 4.0.0
+     */
+    type TransitionTrigger<EventTag extends PropertyKey = PropertyKey> = {
+        readonly type: "event";
+        readonly event: EventTag;
+    } | {
+        readonly type: "always";
+    } | {
+        readonly type: "done";
+    } | {
+        readonly type: "choice";
+    };
+    /**
+     * Statically inspectable destination paths for a transition handler.
+     * A declared parent path covers every descendant below that state.
+     *
+     * @category models
+     * @since 4.0.0
+     */
+    type TransitionTargets<Path extends string = string> = {
+        readonly type: "dynamic";
+    } | {
+        readonly type: "declared";
+        readonly paths: ReadonlyArray<Path>;
+    };
+    /**
+     * Inspectable registration for a transition handler.
+     *
+     * **Details**
+     *
+     * Event, eventless, and completion handlers may declare an upper bound of
+     * possible target paths. A handler without that declaration is explicitly
+     * reported as dynamic. The source, trigger, and reentry behavior are
+     * available without executing the handler.
+     *
+     * @category models
+     * @since 4.0.0
+     */
+    interface TransitionDefinition<SourcePath extends string = string, EventTag extends PropertyKey = PropertyKey, TargetPath extends string = SourcePath> {
+        readonly source: SourcePath;
+        readonly trigger: TransitionTrigger<EventTag>;
+        readonly reenter: boolean;
+        readonly targets: TransitionTargets<TargetPath>;
+    }
+    /**
+     * Serializable description of state-owned work.
+     *
+     * Static invoke descriptors expose their lifecycle id and kind without
+     * retaining Effects, closures, services, or child runtimes. A function-valued
+     * invoke factory is reported as dynamic and is never evaluated by inspection.
+     *
+     * @category models
+     * @since 4.0.0
+     */
+    type ActivityDefinition<SourcePath extends string = string> = Activities.ActivityDefinition<SourcePath>;
+    /**
+     * Transition retained after hierarchy precedence and conflict resolution for
+     * one planned microstep.
+     *
+     * @category models
+     * @since 4.0.0
+     */
+    interface RetainedTransition<SourcePath extends string = string, EventTag extends PropertyKey = PropertyKey, TargetPath extends string = SourcePath> {
+        readonly source: SourcePath;
+        readonly trigger: TransitionTrigger<EventTag>;
+        readonly reenter: boolean;
+        /** Path returned by the handler, including a history pseudo-state. */
+        readonly target: TargetPath | undefined;
+        /** Concrete path used after resolving history, otherwise equal to `target`. */
+        readonly resolvedTarget: TargetPath | undefined;
     }
     /**
      * Constructor arguments for a machine initial state function.
@@ -1357,7 +1660,7 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     type StateIdentifierWithPrefix<States extends StateSchemas, Prefix extends string = ""> = {
-        readonly [Key in Extract<keyof States, string>]: States[Key] extends HistoryStateNodeConfig ? never : States[Key] extends {
+        readonly [Key in Extract<keyof States, string>]: States[Key] extends HistoryStateNodeConfig | ChoiceStateNodeConfig ? never : States[Key] extends {
             readonly states: infer Children;
         } ? Children extends StateSchemas ? JoinPath<Prefix, Key> | StateIdentifierWithPrefix<Children, JoinPath<Prefix, Key>> : JoinPath<Prefix, Key> : JoinPath<Prefix, Key>;
     }[Extract<keyof States, string>];
@@ -1368,20 +1671,39 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     type HistoryIdentifier<States extends StateSchemas> = HistoryIdentifierWithPrefix<States>;
+    /** Extracts the transition-only choice pseudo-state paths. */
+    type ChoiceIdentifier<States extends StateSchemas> = ChoiceIdentifierWithPrefix<States>;
+    /**
+     * Extracts every compiled state-node path, including history pseudo-states.
+     *
+     * @category utility types
+     * @since 4.0.0
+     */
+    type StateNodeIdentifier<States extends StateSchemas> = StateIdentifier<States> | HistoryIdentifier<States> | ChoiceIdentifier<States>;
     /** @internal */
     type HistoryIdentifierWithPrefix<States extends StateSchemas, Prefix extends string = ""> = {
         readonly [Key in Extract<keyof States, string>]: States[Key] extends HistoryStateNodeConfig ? JoinPath<Prefix, Key> : States[Key] extends {
             readonly states: infer Children extends StateSchemas;
         } ? HistoryIdentifierWithPrefix<Children, JoinPath<Prefix, Key>> : never;
     }[Extract<keyof States, string>];
+    /** @internal */
+    type ChoiceIdentifierWithPrefix<States extends StateSchemas, Prefix extends string = ""> = {
+        readonly [Key in Extract<keyof States, string>]: States[Key] extends ChoiceStateNodeConfig ? JoinPath<Prefix, Key> : States[Key] extends {
+            readonly states: infer Children extends StateSchemas;
+        } ? ChoiceIdentifierWithPrefix<Children, JoinPath<Prefix, Key>> : never;
+    }[Extract<keyof States, string>];
     /** Active keys directly declared in a state tree. */
     type ActiveStateKey<States extends StateSchemas> = {
-        readonly [Key in Extract<keyof States, string>]: States[Key] extends HistoryStateNodeConfig ? never : Key;
+        readonly [Key in Extract<keyof States, string>]: States[Key] extends HistoryStateNodeConfig | ChoiceStateNodeConfig ? never : Key;
     }[Extract<keyof States, string>];
     /** History pseudo-state keys directly declared in a state tree. */
     type HistoryStateKey<States extends StateSchemas> = {
         readonly [Key in Extract<keyof States, string>]: States[Key] extends HistoryStateNodeConfig ? Key : never;
     }[Extract<keyof States, string>];
+    /** Choice pseudo-state keys directly declared in a state tree. */
+    type ChoiceStateKey<States extends StateSchemas> = {
+        readonly [Key in Extract<keyof States, string>]: States[Key] extends ChoiceStateNodeConfig ? Key : never;
+    }[Extract<keyof States, string>];
     /**
      * Active states that must implement implicit initial-value construction for
      * shallow history restoration.
@@ -1392,12 +1714,20 @@ export declare namespace Machine {
     type RequiredHistoryInitializers<States extends StateSchemas> = [HistoryIdentifier<States>] extends [never] ? never : Extract<RequiredHistoryInitializersWithPrefix<States, States, "">, StateIdentifier<States>>;
     /** Active parent states that own one or more history pseudo-states. */
     type HistoryParentIdentifier<States extends StateSchemas> = HistoryIdentifier<States> extends infer HistoryId ? HistoryId extends string ? Extract<ImmediateParentStateIdentifier<HistoryId>, StateIdentifier<States>> : never : never;
+    /** Active parent states that own one or more choice pseudo-states. */
+    type ChoiceParentIdentifier<States extends StateSchemas> = ChoiceIdentifier<States> extends infer ChoiceId ? ChoiceId extends string ? Extract<ImmediateParentStateIdentifier<ChoiceId>, StateIdentifier<States>> : never : never;
     /** History defaults and implicit initializers that remain unimplemented. */
     type MissingHistoryImplementations<States extends StateSchemas, UnhandledStates extends StateIdentifier<States>> = Extract<UnhandledStates, HistoryParentIdentifier<States> | RequiredHistoryInitializers<States>>;
+    /** Choice-owning active parents that remain unimplemented. */
+    type MissingChoiceImplementations<States extends StateSchemas, UnhandledStates extends StateIdentifier<States>> = Extract<UnhandledStates, ChoiceParentIdentifier<States>>;
+    /** @internal Readiness proof for required choice resolvers. */
+    type EnsureChoiceImplementations<States extends StateSchemas, UnhandledStates extends StateIdentifier<States>> = [ChoiceIdentifier<States>] extends [never] ? unknown : [MissingChoiceImplementations<States, UnhandledStates>] extends [never] ? unknown : {
+        readonly "~effect/Machine/MissingChoiceImplementation": MissingChoiceImplementations<States, UnhandledStates>;
+    };
     /** @internal Readiness proof required by planning and managed execution. */
-    type EnsureHistoryImplementations<States extends StateSchemas, UnhandledStates extends StateIdentifier<States>> = [HistoryIdentifier<States>] extends [never] ? unknown : [MissingHistoryImplementations<States, UnhandledStates>] extends [never] ? unknown : {
+    type EnsureHistoryImplementations<States extends StateSchemas, UnhandledStates extends StateIdentifier<States>> = ([HistoryIdentifier<States>] extends [never] ? unknown : [MissingHistoryImplementations<States, UnhandledStates>] extends [never] ? unknown : {
         readonly "~effect/Machine/MissingHistoryImplementation": MissingHistoryImplementations<States, UnhandledStates>;
-    };
+    }) & EnsureChoiceImplementations<States, UnhandledStates>;
     /**
      * Extracts a state-tree node by state path.
      *
@@ -1443,13 +1773,6 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     type LifecycleEvent<Events extends ReadonlyArray<TaggedSchema>> = EventOf<Events> | InitialEvent;
-    /**
-     * Runtime capability specialized to a machine's event protocols.
-     *
-     * @category utility types
-     * @since 4.0.0
-     */
-    type RuntimeEffect<Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>> = Effect.Effect<Runtime<EventOf<Events>, EmitOf<Emits>>, never, Runtime.Requirement<EventOf<Events>, EmitOf<Emits>>>;
     /**
      * Extracts a state value from a state definition by identifier.
      *
@@ -1755,6 +2078,17 @@ export declare namespace Machine {
     } ? Children extends StateSchemas ? ParallelSnapshot<Path, NodeSchema<States[StateId]>["Type"], SnapshotRegionsWithPrefix<Children, Path>> : AtomicSnapshot<Path, NodeSchema<States[StateId]>["Type"]> : States[StateId] extends {
         readonly states: infer Children;
     } ? Children extends StateSchemas ? CompoundSnapshot<Path, NodeSchema<States[StateId]>["Type"], SnapshotWithPrefix<Children, Path>> : AtomicSnapshot<Path, NodeSchema<States[StateId]>["Type"]> : AtomicSnapshot<Path, NodeSchema<States[StateId]>["Type"]>;
+    /**
+     * Extracts a complete root snapshot whose selected configuration contains a
+     * particular active state.
+     *
+     * Parallel ancestors still require every region, while compound ancestors
+     * are narrowed to the branch leading to `Owner`.
+     *
+     * @category utility types
+     * @since 4.0.0
+     */
+    type CompleteSnapshotContaining<States extends StateSchemas, Owner extends StateIdentifier<States>> = HistorySnapshotWithPrefix<States, Owner, "">;
     /**
      * Extracts the union of statechart snapshots represented by a state
      * definition.
@@ -1798,7 +2132,11 @@ export declare namespace Machine {
      */
     type EventByTag<Events extends ReadonlyArray<TaggedSchema>, Tag extends TagOf<Events[number]>> = Extract<EventOf<Events>, {
         readonly _tag: Tag;
-    }>;
+    }> | (EventOf<Events> extends infer Event ? Event extends {
+        readonly _tag: infer EventTag extends PropertyKey;
+    } ? [EventTag] extends [Tag] ? never : [Tag] extends [EventTag] ? Omit<Event, "_tag"> & {
+        readonly _tag: Tag;
+    } : never : never : never);
     /**
      * Opaque state construction returned by a builder's `.from` method.
      *
@@ -1810,7 +2148,7 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     interface StateConstruction<Result> {
-        readonly [Model.StateConstructionTypeId]: Result;
+        readonly [Topology.StateConstructionTypeId]: Result;
     }
     /**
      * Machine-bound target instruction accepted from transition handlers.
@@ -1819,8 +2157,8 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     interface Target<States extends StateSchemas, StateId extends StateIdentifier<States>> {
-        readonly [Model.TargetTypeId]: typeof Model.TargetTypeId;
-        readonly [Model.TargetSnapshotTypeId]?: SnapshotByIdentifier<States, StateId>;
+        readonly [Topology.TargetTypeId]: typeof Topology.TargetTypeId;
+        readonly [Topology.TargetSnapshotTypeId]?: SnapshotByIdentifier<States, StateId>;
         readonly path: StateId;
         readonly value: StateByIdentifier<States, StateId>;
         readonly values?: Partial<{
@@ -1838,10 +2176,21 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     interface HistoryTarget<States extends StateSchemas, HistoryId extends HistoryIdentifier<States>> {
-        readonly [Model.HistoryTargetTypeId]: typeof Model.HistoryTargetTypeId;
+        readonly [Topology.HistoryTargetTypeId]: typeof Topology.HistoryTargetTypeId;
         readonly path: HistoryId;
         readonly parent: Extract<ParentPath<HistoryId>, StateIdentifier<States>>;
     }
+    /** Branded transient target instruction used while constructing initial states. */
+    interface ChoiceTargetInstruction<ChoiceId extends string = string> {
+        readonly [Topology.ChoiceTargetTypeId]: typeof Topology.ChoiceTargetTypeId;
+        readonly path: ChoiceId;
+        readonly parent: ParentPath<ChoiceId>;
+        readonly values?: Readonly<Record<string, unknown>>;
+    }
+    /** Transition instruction that enters a transient choice pseudo-state. */
+    interface ChoiceTarget<States extends StateSchemas, ChoiceId extends ChoiceIdentifier<States>> extends ChoiceTargetInstruction<ChoiceId> {
+        readonly parent: Extract<ParentPath<ChoiceId>, StateIdentifier<States>>;
+    }
     /** Builder containing only history pseudo-state paths. */
     type HistoryTargetBuilder<States extends StateSchemas> = HistoryTargetBuilderWithPrefix<States, States, "">;
     /**
@@ -1856,6 +2205,13 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     type FullTargetBuilder<States extends StateSchemas> = FullSnapshotBuilderWithPrefix<States>;
+    /**
+     * Builder for a complete fallback configuration containing a history owner.
+     *
+     * @category utility types
+     * @since 4.0.0
+     */
+    type HistoryDefaultTargetBuilder<States extends StateSchemas, Owner extends StateIdentifier<States>> = HistorySnapshotBuilderWithPrefix<States, Owner>;
     /**
      * Builder for source-local transition targets.
      *
@@ -1867,7 +2223,7 @@ export declare namespace Machine {
      * @category utility types
      * @since 4.0.0
      */
-    type LocalTargetBuilder<States extends StateSchemas, Source extends StateIdentifier<States>> = NearestCompoundScope<States, Source> extends infer Scope ? [Scope] extends [never] ? {} : Scope extends StateIdentifier<States> ? LocalTargetBuilderForScope<States, Scope, Source> : {} : {};
+    type LocalTargetBuilder<States extends StateSchemas, Source extends StateNodeIdentifier<States>> = NearestCompoundScope<States, Source> extends infer Scope ? [Scope] extends [never] ? {} : Scope extends StateIdentifier<States> ? LocalTargetBuilderForScope<States, Scope, Source> : {} : {};
     /**
      * Builder for partial transition targets within the active source root.
      *
@@ -1879,7 +2235,7 @@ export declare namespace Machine {
      * @category utility types
      * @since 4.0.0
      */
-    type BranchTargetBuilder<States extends StateSchemas, Source extends StateIdentifier<States>> = BranchTargetBuilderForRoot<States, Extract<RootStateIdentifier<Source>, ActiveStateKey<States>>, Source>;
+    type BranchTargetBuilder<States extends StateSchemas, Source extends StateNodeIdentifier<States>> = BranchTargetBuilderForRoot<States, Extract<RootStateIdentifier<Source>, ActiveStateKey<States>>, Source>;
     /**
      * Machine-bound target builders available in transition contexts.
      *
@@ -1899,7 +2255,7 @@ export declare namespace Machine {
      * @category models
      * @since 4.0.0
      */
-    interface TargetBuilder<States extends StateSchemas, Source extends StateIdentifier<States>> {
+    interface TargetBuilder<States extends StateSchemas, Source extends StateNodeIdentifier<States>> {
         /**
          * Moves to another state in the same local group. The value of the state
          * containing that group, and values in other active branches, are kept.
@@ -1931,42 +2287,19 @@ export declare namespace Machine {
         /** Restores a declared shallow or deep history pseudo-state. */
         readonly history: HistoryTargetBuilder<States>;
     }
-    /**
-     * Stages an Effect to run after the current machine step is planned.
-     *
-     * The two-argument overload returns `next` after staging the Effect, which is
-     * useful when a handler should stage one action and return a target without
-     * introducing an Effect generator.
-     *
-     * @category models
-     * @since 4.0.0
-     */
-    interface Action {
-        <E, R>(effect: Effect.Effect<void, E, R>): Effect.Effect<void, never, ActionRequirement<E, R>>;
-        <E, R, Next>(effect: Effect.Effect<void, E, R>, next: Next): Effect.Effect<Next, never, ActionRequirement<E, R>>;
-    }
-    /**
-     * Planning capabilities shared by transition and lifecycle callbacks.
-     *
-     * @category models
-     * @since 4.0.0
-     */
-    interface PlanningCapabilities<Events, Emits> {
-        readonly raise: (event: Events) => Effect.Effect<void, MachineSchemaDecodeError | StoppedError, Runtime.Requirement<Events, Emits>>;
-        readonly emit: (event: Emits) => Effect.Effect<void, MachineSchemaDecodeError | StoppedError, Runtime.Requirement<Events, Emits>>;
-    }
     /**
      * Context passed to a state/event handler.
      *
      * @category models
      * @since 4.0.0
      */
-    interface HandlerContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, EventTag extends TagOf<Events[number]>, E, R> extends PlanningCapabilities<EventOf<Events>, EmitOf<Emits>> {
+    interface HandlerContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, EventTag extends TagOf<Events[number]>, E, R> {
         readonly state: StateByIdentifier<States, StateId>;
         readonly parent: ParentStateValue<States, StateId>;
         readonly parents: ParentStateValues<States, StateId>;
+        /** Complete logical configuration captured at the start of this microstep. */
+        readonly snapshot: Snapshot<States>;
         readonly event: EventByTag<Events, EventTag>;
-        readonly runtime: RuntimeEffect<Events, Emits>;
         /**
          * Provides typed builders for choosing the next active state from this
          * handler. Each builder documents which existing state values it keeps.
@@ -1981,12 +2314,11 @@ export declare namespace Machine {
      * @category models
      * @since 4.0.0
      */
-    interface StateActionContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> extends PlanningCapabilities<EventOf<Events>, EmitOf<Emits>> {
+    interface StateActionContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> {
         readonly state: StateByIdentifier<States, StateId>;
         readonly parent: ParentStateValue<States, StateId>;
         readonly parents: ParentStateValues<States, StateId>;
         readonly event: LifecycleEvent<Events>;
-        readonly runtime: RuntimeEffect<Events, Emits>;
     }
     /**
      * Context passed to an invoked child process source.
@@ -1999,7 +2331,6 @@ export declare namespace Machine {
         readonly parent: ParentStateValue<States, StateId>;
         readonly parents: ParentStateValues<States, StateId>;
         readonly event: LifecycleEvent<Events>;
-        readonly runtime: RuntimeEffect<Events, Emits>;
     }
     /**
      * Context passed to an invoked child process active snapshot mapper.
@@ -2029,12 +2360,13 @@ export declare namespace Machine {
      * @category models
      * @since 4.0.0
      */
-    interface AlwaysContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> extends PlanningCapabilities<EventOf<Events>, EmitOf<Emits>> {
+    interface AlwaysContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> {
         readonly state: StateByIdentifier<States, StateId>;
         readonly parent: ParentStateValue<States, StateId>;
         readonly parents: ParentStateValues<States, StateId>;
+        /** Complete logical configuration captured at the start of this microstep. */
+        readonly snapshot: Snapshot<States>;
         readonly event: LifecycleEvent<Events>;
-        readonly runtime: RuntimeEffect<Events, Emits>;
         /**
          * Provides typed builders for choosing the next active state from this
          * eventless handler. Each builder documents which existing state values it
@@ -2050,13 +2382,14 @@ export declare namespace Machine {
      * @category models
      * @since 4.0.0
      */
-    interface DoneContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> extends PlanningCapabilities<EventOf<Events>, EmitOf<Emits>> {
+    interface DoneContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> {
         readonly state: StateByIdentifier<States, StateId>;
         readonly parent: ParentStateValue<States, StateId>;
         readonly parents: ParentStateValues<States, StateId>;
+        /** Complete logical configuration captured at the start of this microstep. */
+        readonly snapshot: Snapshot<States>;
         readonly event: LifecycleEvent<Events>;
         readonly output: CompletionOutputByIdentifier<States, StateId>;
-        readonly runtime: RuntimeEffect<Events, Emits>;
         /**
          * Provides typed builders for choosing the next active state after this
          * state completes. Each builder documents which existing state values it
@@ -2066,6 +2399,15 @@ export declare namespace Machine {
          */
         readonly target: TargetBuilder<States, StateId>;
     }
+    /** Context passed to a transient choice resolver. There is no `state` value. */
+    interface ChoiceContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, ChoiceId extends ChoiceIdentifier<States>> {
+        readonly parent: StateByIdentifier<States, Extract<ImmediateParentStateIdentifier<ChoiceId>, StateIdentifier<States>>>;
+        readonly parents: {
+            readonly [Parent in Extract<ParentStateIdentifier<ChoiceId>, StateIdentifier<States>>]: StateByIdentifier<States, Parent>;
+        };
+        readonly event: LifecycleEvent<Events>;
+        readonly target: TargetBuilder<States, ChoiceId>;
+    }
     /**
      * Context passed to a final state output function.
      *
@@ -2109,14 +2451,18 @@ export declare namespace Machine {
      * @category utility types
      * @since 4.0.0
      */
-    type StateActionResult<E, R> = void | Effect.Effect<void, E, R>;
+    type StateActionResult<E, R> = undefined;
     /**
      * Return value accepted from a machine initial state function.
      *
      * @category utility types
      * @since 4.0.0
      */
-    type InitialResult<States extends StateSchemas, E, R> = Snapshot<States> | StateConstruction<Snapshot<States>> | Effect.Effect<Snapshot<States> | StateConstruction<Snapshot<States>>, E, R>;
+    type InitialResult<States extends StateSchemas, E, R> = Snapshot<States> | InitialSnapshot<States> | StateConstruction<Snapshot<States> | InitialSnapshot<States>>;
+    /** Initial snapshots may transiently terminate in a declared choice node. */
+    type InitialSnapshot<States extends StateSchemas> = {
+        readonly [StateId in ActiveStateKey<States>]: InitialSnapshotResult<States, StateId, "">;
+    }[ActiveStateKey<States>];
     /**
      * Return value accepted from transition handlers.
      *
@@ -2129,7 +2475,9 @@ export declare namespace Machine {
      * @category utility types
      * @since 4.0.0
      */
-    type HandlerResult<States extends StateSchemas, E, R> = Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>> | StateConstruction<Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>>> | void | Effect.Effect<Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>> | StateConstruction<Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>>> | void, E, R>;
+    type HandlerResult<States extends StateSchemas, E, R> = Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>> | ChoiceTarget<States, ChoiceIdentifier<States>> | StateConstruction<Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>> | ChoiceTarget<States, ChoiceIdentifier<States>>> | void;
+    /** A choice resolver must always select a typed target synchronously. */
+    type ChoiceResult<States extends StateSchemas, E, R> = Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>> | ChoiceTarget<States, ChoiceIdentifier<States>> | StateConstruction<Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>> | ChoiceTarget<States, ChoiceIdentifier<States>>>;
     /**
      * Extracts the union of handler return values from a handler map.
      *
@@ -2177,6 +2525,12 @@ export declare namespace Machine {
             readonly default: (...args: any) => infer Ret;
         } ? Ret : never;
     }[keyof NonNullable<History>] : never;
+    /** Extracts the return value from a choice resolver. */
+    type ChoiceReturn<Config> = Config extends {
+        readonly choice: {
+            readonly transition: (...args: any) => infer Ret;
+        };
+    } ? Ret : never;
     /**
      * Extracts the return value from an event transition config.
      *
@@ -2303,7 +2657,7 @@ export declare namespace Machine {
      */
     type AlwaysReturn<Config> = Config extends {
         readonly always?: infer Always;
-    } ? NonNullable<Always> extends (...args: any) => infer Ret ? Ret : never : never;
+    } ? EventTransitionReturn<NonNullable<Always>> : never;
     /**
      * Extracts the return value from a state completion transition.
      *
@@ -2312,7 +2666,7 @@ export declare namespace Machine {
      */
     type DoneReturn<Config> = Config extends {
         readonly onDone?: infer OnDone;
-    } ? NonNullable<OnDone> extends (...args: any) => infer Ret ? Ret : never : never;
+    } ? EventTransitionReturn<NonNullable<OnDone>> : never;
     /**
      * Extracts the return value from a final state output function.
      *
@@ -2328,7 +2682,7 @@ export declare namespace Machine {
      * @category utility types
      * @since 4.0.0
      */
-    type ConfigServices<Config> = Effect.Services<EventHandlerReturn<Config>> | Effect.Services<AlwaysReturn<Config>> | Effect.Services<DoneReturn<Config>> | Effect.Services<StateActionReturn<Config, "entry">> | Effect.Services<StateActionReturn<Config, "exit">> | Effect.Services<StateInitialReturn<Config>> | Effect.Services<HistoryDefaultReturn<Config>> | InvokeRequirements<Config>;
+    type ConfigServices<Config> = Effect.Services<EventHandlerReturn<Config>> | Effect.Services<AlwaysReturn<Config>> | 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>;
     /**
      * Configuration for invoking a child process while a state is active.
      *
@@ -2344,6 +2698,8 @@ export declare namespace Machine {
             readonly requirements: Types.Covariant<ChildRequirements>;
             readonly initialError: Types.Covariant<ChildInitialError>;
         };
+        /** @internal Serializable descriptor metadata used by inspection. */
+        readonly [Activities.ActivityMetadataTypeId]?: Activities.StaticActivityMetadata;
         readonly id: string;
         /**
          * Optional parent-local address for sending events to this invocation.
@@ -2403,15 +2759,29 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     type ActiveStateConfig<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, E, R> = {
-        readonly entry?: (context: StateActionContext<States, Events, Emits, StateId>) => StateActionResult<any, any>;
-        readonly exit?: (context: StateActionContext<States, Events, Emits, StateId>) => StateActionResult<any, any>;
+        readonly entry?: (context: StateActionContext<States, Events, Emits, StateId>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => StateActionResult<any, any>;
+        readonly exit?: (context: StateActionContext<States, Events, Emits, StateId>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => StateActionResult<any, any>;
         readonly invoke?: InvokeDefinition<States, Events, Emits, StateId>;
-        readonly always?: (context: AlwaysContext<States, Events, Emits, StateId>) => HandlerResult<States, any, any>;
-        readonly onDone?: (context: DoneContext<States, Events, Emits, StateId>) => HandlerResult<States, any, any>;
+        readonly always?: ((context: AlwaysContext<States, Events, Emits, StateId>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => HandlerResult<States, any, any>) | {
+            /** Statically declared upper bound of possible target paths. */
+            readonly targets?: ReadonlyArray<StateNodeIdentifier<States>>;
+            readonly transition: (context: AlwaysContext<States, Events, Emits, StateId>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => HandlerResult<States, any, any>;
+        };
+        readonly onDone?: ((context: DoneContext<States, Events, Emits, StateId>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => HandlerResult<States, any, any>) | {
+            /** Statically declared upper bound of possible target paths. */
+            readonly targets?: ReadonlyArray<StateNodeIdentifier<States>>;
+            readonly transition: (context: DoneContext<States, Events, Emits, StateId>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => HandlerResult<States, any, any>;
+        };
         readonly on?: {
-            readonly [EventTag in TagOf<Events[number]>]?: ((context: HandlerContext<States, Events, Emits, StateId, EventTag, E, R>) => HandlerResult<States, any, any>) | {
+            readonly [EventTag in TagOf<Events[number]>]?: ((context: HandlerContext<States, Events, Emits, StateId, EventTag, E, R>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => HandlerResult<States, any, any>) | {
                 readonly reenter?: boolean;
-                readonly transition: (context: HandlerContext<States, Events, Emits, StateId, EventTag, E, R>) => HandlerResult<States, any, any>;
+                /**
+                 * Upper bound of state or history paths this handler may target.
+                 * Returning `void` is always permitted. Declaring a parent state also
+                 * permits concrete descendant targets below it.
+                 */
+                readonly targets?: ReadonlyArray<StateNodeIdentifier<States>>;
+                readonly transition: (context: HandlerContext<States, Events, Emits, StateId, EventTag, E, R>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => HandlerResult<States, any, any>;
             };
         };
         readonly initial?: StateInitialHandler<States, Events, Emits, StateId>;
@@ -2429,22 +2799,43 @@ export declare namespace Machine {
     /** Context passed to an implicit child-state initializer. */
     type StateInitialContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> = StateActionContext<States, Events, Emits, StateId>;
     /** Initial child value implementation for a compound or parallel state. */
-    type StateInitialHandler<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> = (context: StateInitialContext<States, Events, Emits, StateId>) => StateInitialValue<States, StateId> | Effect.Effect<StateInitialValue<States, StateId>, any, any>;
+    type StateInitialHandler<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> = (context: StateInitialContext<States, Events, Emits, StateId>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => StateInitialValue<States, StateId>;
     /** 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>> extends PlanningCapabilities<EventOf<Events>, EmitOf<Emits>> {
+    interface HistoryDefaultContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, ParentId extends StateIdentifier<States>> {
         readonly event: LifecycleEvent<Events>;
-        readonly runtime: RuntimeEffect<Events, Emits>;
-        readonly target: FullTargetBuilder<States>;
+        readonly target: HistoryDefaultTargetBuilder<States, ParentId>;
         readonly parent: ParentId;
     }
-    /** Typed fallback evaluated when a history node has no record yet. */
-    type HistoryDefaultHandler<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, ParentId extends StateIdentifier<States>> = (context: HistoryDefaultContext<States, Events, Emits, ParentId>) => SnapshotByIdentifier<States, ParentId> | StateConstruction<SnapshotByIdentifier<States, ParentId>> | Effect.Effect<SnapshotByIdentifier<States, ParentId> | StateConstruction<SnapshotByIdentifier<States, ParentId>>, any, any>;
+    /**
+     * Typed fallback evaluated when a history node has no record yet.
+     *
+     * The fallback constructs a complete root configuration containing the
+     * history owner. This makes the default independent of the transition source
+     * 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. */
     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>;
         };
     };
+    /** Required implementation for a choice pseudo-state. */
+    interface ChoiceStateConfig<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, ChoiceId extends ChoiceIdentifier<States>> {
+        readonly choice: {
+            /** Statically inspectable upper bound of every possible target. */
+            readonly targets: readonly [StateNodeIdentifier<States>, ...ReadonlyArray<StateNodeIdentifier<States>>];
+            readonly transition: (context: ChoiceContext<States, Events, Emits, ChoiceId>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => ChoiceResult<States, any, any>;
+        };
+        readonly entry?: never;
+        readonly exit?: never;
+        readonly invoke?: never;
+        readonly always?: never;
+        readonly on?: never;
+        readonly onDone?: never;
+        readonly output?: never;
+        readonly initial?: never;
+    }
     /**
      * Configuration accepted for a final state.
      *
@@ -2452,7 +2843,7 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     type FinalStateConfig<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> = {
-        readonly entry?: (context: StateActionContext<States, Events, Emits, StateId>) => StateActionResult<any, any>;
+        readonly entry?: (context: StateActionContext<States, Events, Emits, StateId>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => StateActionResult<any, any>;
         readonly exit?: never;
         readonly always?: never;
         readonly onDone?: never;
@@ -2467,27 +2858,45 @@ export declare namespace Machine {
     type HandlerConfig<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, E, R> = NodeByIdentifier<States, StateId> extends {
         readonly type: "final";
     } ? FinalStateConfig<States, Events, Emits, StateId> : ActiveStateConfig<States, Events, Emits, StateId, E, R>;
+    type HandlerNodeConfig<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Path extends StateNodeIdentifier<States>, E, R> = Path extends ChoiceIdentifier<States> ? ChoiceStateConfig<States, Events, Emits, Path> : Path extends StateIdentifier<States> ? HandlerConfig<States, Events, Emits, Path, E, R> : never;
     type HandlerChildren<Node> = Node extends {
         readonly states: infer Children extends StateSchemas;
     } ? Children : never;
-    type HandlerStateId<States extends StateSchemas, Path extends string> = StateIdentifierFromPath<States, Path>;
+    type HandlerNodeId<States extends StateSchemas, Path extends string> = Extract<Path, StateNodeIdentifier<States>>;
     type HandlerConfigPart<Config> = {
         readonly [Key in keyof Config as Key extends "states" ? never : Key]: Config[Key];
     };
-    type HandlerNode<AllStates extends StateSchemas, Node, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, E, R, StateId extends StateIdentifier<AllStates>> = HandlerConfig<AllStates, Events, Emits, StateId, E, R> & (HandlerChildren<Node> extends infer Children extends StateSchemas ? [Children] extends [never] ? {
+    type HandlerNodeChildrenConfig<Config> = "states" extends keyof Config ? Config extends {
+        readonly states?: infer Children;
+    } ? NonNullable<Children> : never : never;
+    type HandlerNodeByPath<States extends StateSchemas, Path extends string> = Path extends `${infer Head}.${infer Rest}` ? Head extends keyof States ? States[Head] extends {
+        readonly states: infer Children extends StateSchemas;
+    } ? HandlerNodeByPath<Children, Rest> : never : never : Path extends keyof States ? States[Path] : never;
+    type HandlerConfigAtPath<Config, Path extends string> = Path extends `${infer Head}.${infer Rest}` ? Head extends keyof Config ? HandlerConfigAtPath<HandlerNodeChildrenConfig<Config[Head]>, Rest> : never : Path extends keyof Config ? Config[Path] : never;
+    type HandlerValidationAtPath<Path extends string, Validation> = Path extends `${infer Head}.${infer Rest}` ? {
+        readonly [Key in Head]?: {
+            readonly states: HandlerValidationAtPath<Rest, Validation>;
+        };
+    } : {
+        readonly [Key in Path]?: Validation;
+    };
+    type HandlerNode<AllStates extends StateSchemas, Node, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, E, R, StateId extends StateNodeIdentifier<AllStates>> = HandlerNodeConfig<AllStates, Events, Emits, StateId, E, R> & (StateId extends ChoiceIdentifier<AllStates> ? {
+        readonly states?: never;
+        readonly history?: never;
+    } : HandlerChildren<Node> extends infer Children extends StateSchemas ? [Children] extends [never] ? {
         readonly states?: never;
         readonly history?: never;
     } : {
-        readonly states?: HandlerTree<AllStates, Children, Events, Emits, E, R, StateId>;
-        readonly history?: HistoryDefaultConfig<AllStates, Events, Emits, StateId, Children>;
+        readonly states?: HandlerTree<AllStates, Children, Events, Emits, E, R, Extract<StateId, StateIdentifier<AllStates>>>;
+        readonly history?: HistoryDefaultConfig<AllStates, Events, Emits, Extract<StateId, StateIdentifier<AllStates>>, Children>;
     } : {
         readonly states?: never;
         readonly history?: never;
     });
     type HandlerTree<AllStates extends StateSchemas, States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, E, R, Prefix extends string> = {
-        readonly [Key in ActiveStateKey<States>]?: HandlerNode<AllStates, States[Key], Events, Emits, E, R, HandlerStateId<AllStates, JoinPath<Prefix, Key>>>;
+        readonly [Key in ActiveStateKey<States> | ChoiceStateKey<States>]?: HandlerNode<AllStates, States[Key], Events, Emits, E, R, HandlerNodeId<AllStates, JoinPath<Prefix, Key>>>;
     };
-    type HandlerNodeConfigKey = "always" | "entry" | "exit" | "history" | "initial" | "invoke" | "on" | "onDone" | "output" | "states";
+    type HandlerNodeConfigKey = "always" | "choice" | "entry" | "exit" | "history" | "initial" | "invoke" | "on" | "onDone" | "output" | "states";
     type HandlerValidationError<Message extends string, Path extends string, Detail = unknown> = {
         readonly "~effect/Machine/HandlerError": readonly [message: Message, path: Path, detail: Detail];
     };
@@ -2525,19 +2934,36 @@ export declare namespace Machine {
             readonly [Key in UnknownKeys]: HandlerValidationError<"Handler config contains an event key that does not exist", StateId, Key>;
         };
     } : unknown;
-    type HandlerDepth = readonly [unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown];
-    type HandlerNextDepth<Depth extends ReadonlyArray<unknown>> = Depth extends readonly [unknown, ...infer Rest extends ReadonlyArray<unknown>] ? Rest : readonly [];
-    type HandlerChildrenValidation<AllStates extends StateSchemas, Node, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Prefix extends string, Config, AvailableOutputStates extends StateIdentifier<AllStates>, Depth extends ReadonlyArray<unknown>> = "states" extends keyof Config ? Depth extends readonly [] ? {
-        readonly states: HandlerValidationError<"Handler nesting exceeds the supported depth", Prefix>;
-    } : Config extends {
+    type TransitionResultTargetPath<Result> = IsAny<Result> extends true ? never : Result extends Effect.Effect<infer Success, any, any> ? TransitionResultTargetPath<Success> : Result extends StateConstruction<infer Constructed> ? TransitionResultTargetPath<Constructed> : Result extends {
+        readonly path: infer Path extends string;
+    } ? Path : never;
+    type DeclaredTransitionTarget<Transition> = Transition extends {
+        readonly targets: infer Targets extends ReadonlyArray<string>;
+    } ? Targets[number] : never;
+    type ExcludeDeclaredTransitionTarget<Returned, Declared extends string> = Returned extends string ? Returned extends Declared | `${Declared}.${string}` ? never : Returned : never;
+    type UndeclaredTransitionTarget<Transition> = "targets" extends keyof Transition ? ExcludeDeclaredTransitionTarget<TransitionResultTargetPath<EventTransitionReturn<Transition>>, DeclaredTransitionTarget<Transition>> : never;
+    type HandlerOnTargetValidationErrors<StateId extends string, On> = {
+        readonly [EventTag in keyof On as [UndeclaredTransitionTarget<On[EventTag]>] extends [never] ? never : EventTag]: HandlerValidationError<"Transition returns a target not listed in targets", StateId, readonly [event: EventTag, target: UndeclaredTransitionTarget<On[EventTag]>]>;
+    };
+    type HandlerOnTargetValidation<StateId extends string, Config> = "on" extends keyof Config ? Config extends {
+        readonly on?: infer On;
+    } ? HandlerOnTargetValidationErrors<StateId, NonNullable<On>> extends infer Errors ? keyof Errors extends never ? unknown : {
+        readonly on: Errors;
+    } : never : unknown : unknown;
+    type HandlerDirectTargetValidation<StateId extends string, Config, Trigger extends "always" | "onDone", Transition = Config extends {
+        readonly [Key in Trigger]?: infer Value;
+    } ? NonNullable<Value> : never, Undeclared extends string = UndeclaredTransitionTarget<Transition>> = Trigger extends keyof Config ? [Undeclared] extends [never] ? unknown : {
+        readonly [Key in Trigger]: HandlerValidationError<"Transition returns a target not listed in targets", StateId, readonly [trigger: Trigger, target: Undeclared]>;
+    } : unknown;
+    type HandlerChildrenValidation<Node, Prefix extends string, Config> = "states" extends keyof Config ? Config extends {
         readonly states?: infer ChildrenConfig;
     } ? HandlerChildren<Node> extends infer Children extends StateSchemas ? [Children] extends [never] ? {
         readonly states: HandlerValidationError<"Handler config contains child states for a state that has no children", Prefix>;
-    } : HandlerTreeValidation<AllStates, Children, Events, Emits, Prefix, NonNullable<ChildrenConfig>, AvailableOutputStates, HandlerNextDepth<Depth>> extends infer Validation ? unknown extends Validation ? unknown : {
+    } : HandlerUnknownStateKeyValidation<Children, Prefix, NonNullable<ChildrenConfig>> extends infer Validation ? unknown extends Validation ? unknown : {
         readonly states: Validation;
-    } : never : {
+    } : never : never : {
         readonly states: HandlerValidationError<"Handler config contains child states for a state that has no children", Prefix>;
-    } : unknown : unknown;
+    } : unknown;
     type HandlerOutputRequirementValidation<AllStates extends StateSchemas, StateId extends StateIdentifier<AllStates>, AvailableOutputStates extends StateIdentifier<AllStates>, Config> = ("onDone" extends keyof Config ? [
         Exclude<RequiredCompletionOutputStates<AllStates, StateId>, AvailableOutputStates>
     ] extends [never] ? unknown : {
@@ -2549,7 +2975,15 @@ export declare namespace Machine {
     ] extends [never] ? unknown : {
         readonly output: HandlerValidationError<"Handler config is missing a region output implementation required by parallel output", StateId, Exclude<RequiredParallelOutputStates<AllStates, StateId>, AvailableOutputStates>>;
     } : unknown : unknown);
-    type HandlerNodeValidation<AllStates extends StateSchemas, Node, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<AllStates>, Config, AvailableOutputStates extends StateIdentifier<AllStates>, Depth extends ReadonlyArray<unknown>> = HandlerUnknownConfigKeyValidation<StateId, Config> & HandlerOnKeyValidation<Events, StateId, Config> & HandlerInvokeOutputValidation<Events, StateId, Config> & HandlerInvokeEmitsValidation<Events, StateId, Config> & HandlerInvokeSnapshotValidation<Events, StateId, Config> & HandlerChildrenValidation<AllStates, Node, Events, Emits, StateId, Config, AvailableOutputStates, Depth> & HandlerOutputRequirementValidation<AllStates, StateId, AvailableOutputStates, Config> & HandlerRuntimeValidation<Events, Emits, StateId, Config>;
+    type HandlerNodeValidation<AllStates extends StateSchemas, Node, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<AllStates>, Config, AvailableOutputStates extends StateIdentifier<AllStates>> = StateId extends ChoiceIdentifier<AllStates> ? HandlerChoiceUnknownConfigKeyValidation<StateId, Config> & HandlerChoiceTargetValidation<StateId, Config> & HandlerRuntimeValidation<Events, Emits, StateId, Config> : StateId extends StateIdentifier<AllStates> ? HandlerUnknownConfigKeyValidation<StateId, Config> & HandlerOnKeyValidation<Events, StateId, Config> & HandlerOnTargetValidation<StateId, Config> & HandlerDirectTargetValidation<StateId, Config, "always"> & HandlerDirectTargetValidation<StateId, Config, "onDone"> & HandlerInvokeOutputValidation<Events, StateId, Config> & HandlerInvokeEmitsValidation<Events, StateId, Config> & HandlerInvokeSnapshotValidation<Events, StateId, Config> & HandlerChildrenValidation<Node, StateId, Config> & HandlerOutputRequirementValidation<AllStates, StateId, AvailableOutputStates, Config> & HandlerRuntimeValidation<Events, Emits, StateId, Config> : unknown;
+    type HandlerChoiceUnknownConfigKeyValidation<StateId extends string, Config, UnknownKeys extends string = Exclude<Extract<keyof Config, string>, "choice">> = [UnknownKeys] extends [never] ? unknown : {
+        readonly [Key in UnknownKeys]: HandlerValidationError<"Choice handler config contains an invalid key", StateId, Key>;
+    };
+    type HandlerChoiceTargetValidation<StateId extends string, Config> = Config extends {
+        readonly choice: infer Choice;
+    } ? [UndeclaredTransitionTarget<Choice>] extends [never] ? unknown : {
+        readonly choice: HandlerValidationError<"Choice resolver returns a target not listed in targets", StateId, UndeclaredTransitionTarget<Choice>>;
+    } : unknown;
     type HandlerInvokeOutputValidation<Events extends ReadonlyArray<TaggedSchema>, StateId extends string, Config> = [InvokeReturn<Config>] extends [never] ? unknown : [Exclude<InvokeOutput<InvokeReturn<Config>>, EventOf<Events> | void>] extends [never] ? unknown : {
         readonly invoke: HandlerValidationError<"Invoked child output must be a machine event or void", StateId, Exclude<InvokeOutput<InvokeReturn<Config>>, EventOf<Events> | void>>;
     };
@@ -2560,20 +2994,9 @@ export declare namespace Machine {
         readonly invoke: HandlerValidationError<"Invoked child snapshot mapper must return a machine event or undefined", StateId, Exclude<InvokeSnapshotEvent<InvokeReturn<Config>>, EventOf<Events> | undefined>>;
     };
     type HandlerRuntimeValidation<Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends string, Config, Incompatible = IncompatibleRuntime<ConfigServices<HandlerConfigPart<Config>>, EventOf<Events>, EmitOf<Emits>>> = [Incompatible] extends [never] ? unknown : HandlerValidationError<"Handler config requires an incompatible machine runtime", StateId, Incompatible>;
-    type HandlerTreeNodeValidationMap<AllStates extends StateSchemas, States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Prefix extends string, Config, AvailableOutputStates extends StateIdentifier<AllStates>, Depth extends ReadonlyArray<unknown>> = {
-        readonly [Key in Extract<Extract<keyof Config, string>, Extract<keyof States, string>>]?: HandlerNodeValidation<AllStates, States[Key], Events, Emits, HandlerStateId<AllStates, JoinPath<Prefix, Key>>, Config[Key], AvailableOutputStates, Depth>;
-    };
-    type HandlerTreeNodeValidationErrors<Validations> = {
-        readonly [Key in keyof Validations as unknown extends Validations[Key] ? never : Key]?: Validations[Key];
-    };
-    type HandlerTreeNodeValidations<AllStates extends StateSchemas, States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Prefix extends string, Config, AvailableOutputStates extends StateIdentifier<AllStates>, Depth extends ReadonlyArray<unknown>> = HandlerTreeNodeValidationMap<AllStates, States, Events, Emits, Prefix, Config, AvailableOutputStates, Depth> extends infer Validations ? HandlerTreeNodeValidationErrors<Validations> extends infer Errors ? keyof Errors extends never ? unknown : Errors : never : never;
-    type HandlerTreeValidation<AllStates extends StateSchemas, States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Prefix extends string, Config, AvailableOutputStates extends StateIdentifier<AllStates>, Depth extends ReadonlyArray<unknown> = HandlerDepth> = HandlerUnknownStateKeyValidation<States, Prefix, Config> & HandlerTreeNodeValidations<AllStates, States, Events, Emits, Prefix, Config, AvailableOutputStates, Depth>;
-    type HandlerNodeChildrenConfig<Config> = "states" extends keyof Config ? Config extends {
-        readonly states?: infer Children;
-    } ? NonNullable<Children> : never : never;
-    type HandlerTreeStateIds<AllStates extends StateSchemas, States extends StateSchemas, Prefix extends string, Config, Depth extends ReadonlyArray<unknown> = HandlerDepth> = {
-        readonly [Key in Extract<Extract<keyof Config, string>, Extract<keyof States, string>>]: HandlerImplementedStateId<AllStates, States[Key], HandlerStateId<AllStates, JoinPath<Prefix, Key>>, Config[Key]> | HandlerNodeChildStateIds<AllStates, States[Key], HandlerStateId<AllStates, JoinPath<Prefix, Key>>, Config[Key], Depth>;
-    }[Extract<Extract<keyof Config, string>, Extract<keyof States, string>>];
+    type HandlerNodeValidationAtPath<AllStates extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Config, AvailableOutputStates extends StateIdentifier<AllStates>, StateId extends StateNodeIdentifier<AllStates>, NodeConfig = HandlerConfigAtPath<Config, StateId>> = [NodeConfig] extends [never] ? never : HandlerNodeValidation<AllStates, HandlerNodeByPath<AllStates, StateId>, Events, Emits, StateId, NodeConfig, AvailableOutputStates> extends infer Validation ? unknown extends Validation ? never : HandlerValidationAtPath<StateId, Validation> : never;
+    type HandlerTreeNodeValidations<AllStates extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Config, AvailableOutputStates extends StateIdentifier<AllStates>> = Types.UnionToIntersection<StateNodeIdentifier<AllStates> extends infer StateId extends StateNodeIdentifier<AllStates> ? StateId extends StateNodeIdentifier<AllStates> ? HandlerNodeValidationAtPath<AllStates, Events, Emits, Config, AvailableOutputStates, StateId> : never : never>;
+    type HandlerTreeValidation<AllStates extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Config, AvailableOutputStates extends StateIdentifier<AllStates>> = HandlerUnknownStateKeyValidation<AllStates, "", Config> & HandlerTreeNodeValidations<AllStates, Events, Emits, Config, AvailableOutputStates>;
     type HandlerHasRequiredInitial<AllStates extends StateSchemas, StateId extends StateIdentifier<AllStates>, Config> = StateId extends RequiredHistoryInitializers<AllStates> ? "initial" extends keyof Config ? true : false : true;
     type HandlerHasRequiredHistoryDefaults<Node, Config> = Node extends {
         readonly states: infer Children extends StateSchemas;
@@ -2582,36 +3005,31 @@ export declare namespace Machine {
     } ? [
         Exclude<HistoryStateKey<Children>, Extract<keyof NonNullable<HistoryConfig>, string>>
     ] extends [never] ? true : false : false : true;
-    type HandlerImplementedStateId<AllStates extends StateSchemas, Node, StateId extends StateIdentifier<AllStates>, Config> = [HistoryIdentifier<AllStates>] extends [never] ? StateId : HandlerHasRequiredInitial<AllStates, StateId, Config> extends true ? HandlerHasRequiredHistoryDefaults<Node, Config> extends true ? StateId : never : never;
-    type HandlerNodeChildStateIds<AllStates extends StateSchemas, Node, Prefix extends string, Config, Depth extends ReadonlyArray<unknown>> = Depth extends readonly [] ? never : HandlerChildren<Node> extends infer Children extends StateSchemas ? [Children] extends [never] ? never : HandlerTreeStateIds<AllStates, Children, Prefix, HandlerNodeChildrenConfig<Config>, HandlerNextDepth<Depth>> : never;
-    type HandlerConfigError<Config> = Effect.Error<EventHandlerReturn<Config>> | Effect.Error<AlwaysReturn<Config>> | Effect.Error<DoneReturn<Config>> | Effect.Error<StateActionReturn<Config, "entry">> | Effect.Error<StateActionReturn<Config, "exit">> | Effect.Error<StateInitialReturn<Config>> | Effect.Error<HistoryDefaultReturn<Config>> | InvokeError<Config>;
-    type HandlerTreeError<AllStates extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, States extends StateSchemas, Prefix extends string, Config, Depth extends ReadonlyArray<unknown> = HandlerDepth> = {
-        readonly [Key in Extract<Extract<keyof Config, string>, Extract<keyof States, string>>]: HandlerConfigError<HandlerConfigPart<Config[Key]>> | HandlerNodeChildError<AllStates, Events, Emits, States[Key], HandlerStateId<AllStates, JoinPath<Prefix, Key>>, Config[Key], Depth>;
-    }[Extract<Extract<keyof Config, string>, Extract<keyof States, string>>];
-    type HandlerNodeChildError<AllStates extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Node, Prefix extends string, Config, Depth extends ReadonlyArray<unknown>> = Depth extends readonly [] ? never : HandlerChildren<Node> extends infer Children extends StateSchemas ? [Children] extends [never] ? never : HandlerTreeError<AllStates, Events, Emits, Children, Prefix, HandlerNodeChildrenConfig<Config>, HandlerNextDepth<Depth>> : never;
-    type HandlerTreeServices<AllStates extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, States extends StateSchemas, Prefix extends string, Config, Depth extends ReadonlyArray<unknown> = HandlerDepth> = {
-        readonly [Key in Extract<Extract<keyof Config, string>, Extract<keyof States, string>>]: ConfigServices<HandlerConfigPart<Config[Key]>> | HandlerNodeChildServices<AllStates, Events, Emits, States[Key], HandlerStateId<AllStates, JoinPath<Prefix, Key>>, Config[Key], Depth>;
-    }[Extract<Extract<keyof Config, string>, Extract<keyof States, string>>];
-    type HandlerNodeChildServices<AllStates extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Node, Prefix extends string, Config, Depth extends ReadonlyArray<unknown>> = Depth extends readonly [] ? never : HandlerChildren<Node> extends infer Children extends StateSchemas ? [Children] extends [never] ? never : HandlerTreeServices<AllStates, Events, Emits, Children, Prefix, HandlerNodeChildrenConfig<Config>, HandlerNextDepth<Depth>> : never;
-    type HandlerTreeOutputStates<AllStates extends StateSchemas, States extends StateSchemas, Prefix extends string, Config, Depth extends ReadonlyArray<unknown> = HandlerDepth> = {
-        readonly [Key in Extract<Extract<keyof Config, string>, Extract<keyof States, string>>]: HandlerOutputStates<AllStates, HandlerStateId<AllStates, JoinPath<Prefix, Key>>, HandlerConfigPart<Config[Key]>> | HandlerNodeChildOutputStates<AllStates, States[Key], HandlerStateId<AllStates, JoinPath<Prefix, Key>>, Config[Key], Depth>;
-    }[Extract<Extract<keyof Config, string>, Extract<keyof States, string>>];
-    type HandlerNodeChildOutputStates<AllStates extends StateSchemas, Node, Prefix extends string, Config, Depth extends ReadonlyArray<unknown>> = Depth extends readonly [] ? never : HandlerChildren<Node> extends infer Children extends StateSchemas ? [Children] extends [never] ? never : HandlerTreeOutputStates<AllStates, Children, Prefix, HandlerNodeChildrenConfig<Config>, HandlerNextDepth<Depth>> : never;
-    type HandleTreeResult<AllStates extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Input extends Schema.Top, UnhandledStates extends StateIdentifier<AllStates>, E, R, InitialE, InitialR, FinalStates extends StateIdentifier<AllStates>, Output, OutputStates extends StateIdentifier<AllStates>, InputEvents extends ReadonlyArray<TaggedSchema>, Config> = Machine<AllStates, Events, Input, Exclude<UnhandledStates, HandlerTreeStateIds<AllStates, AllStates, "", Config>>, E | HandlerTreeError<AllStates, Events, Emits, AllStates, "", Config>, ExcludeCompatibleRuntime<R | HandlerTreeServices<AllStates, Events, Emits, AllStates, "", Config>, EventOf<Events>, EmitOf<Emits>>, InitialE, InitialR, FinalStates, Output, Emits, OutputStates | Extract<HandlerTreeOutputStates<AllStates, AllStates, "", Config>, StateIdentifier<AllStates>>, InputEvents>;
+    type HandlerHasRequiredChoices<Node, Config> = Node extends {
+        readonly states: infer Children extends StateSchemas;
+    } ? [ChoiceStateKey<Children>] extends [never] ? true : Config extends {
+        readonly states?: infer ChildrenConfig;
+    } ? [
+        Exclude<ChoiceStateKey<Children>, Extract<keyof NonNullable<ChildrenConfig>, string>>
+    ] extends [never] ? true : false : false : true;
+    type HandlerImplementedStateId<AllStates extends StateSchemas, Node, StateId extends StateIdentifier<AllStates>, Config> = [HistoryIdentifier<AllStates> | ChoiceIdentifier<AllStates>] extends [never] ? StateId : HandlerHasRequiredInitial<AllStates, StateId, Config> extends true ? HandlerHasRequiredHistoryDefaults<Node, Config> extends true ? HandlerHasRequiredChoices<Node, Config> extends true ? StateId : never : never : never;
+    type HandlerConfigError<Config> = Effect.Error<EventHandlerReturn<Config>> | Effect.Error<AlwaysReturn<Config>> | 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>;
+    type HandlerNodeEvidence<AllStates extends StateSchemas, Config, StateId extends StateNodeIdentifier<AllStates>, NodeConfig = HandlerConfigAtPath<Config, StateId>> = [NodeConfig] extends [never] ? never : {
+        readonly stateId: StateId extends StateIdentifier<AllStates> ? HandlerImplementedStateId<AllStates, HandlerNodeByPath<AllStates, StateId>, StateId, NodeConfig> : never;
+        readonly error: HandlerConfigError<HandlerConfigPart<NodeConfig>>;
+        readonly services: ConfigServices<HandlerConfigPart<NodeConfig>>;
+        readonly outputState: StateId extends StateIdentifier<AllStates> ? HandlerOutputStates<AllStates, StateId, HandlerConfigPart<NodeConfig>> : never;
+    };
+    type HandlerTreeEvidence<AllStates extends StateSchemas, Config> = StateNodeIdentifier<AllStates> extends infer StateId extends StateNodeIdentifier<AllStates> ? StateId extends StateNodeIdentifier<AllStates> ? HandlerNodeEvidence<AllStates, Config, StateId> : never : never;
+    type HandleTreeResult<AllStates extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Input extends Schema.Top, UnhandledStates extends StateIdentifier<AllStates>, E, R, InitialE, InitialR, FinalStates extends StateIdentifier<AllStates>, Output, OutputStates extends StateIdentifier<AllStates>, InputEvents extends ReadonlyArray<TaggedSchema>, Config> = Machine<AllStates, Events, Input, Exclude<UnhandledStates, HandlerTreeEvidence<AllStates, Config>["stateId"]>, E | HandlerTreeEvidence<AllStates, Config>["error"], ExcludeCompatibleRuntime<R | HandlerTreeEvidence<AllStates, Config>["services"], EventOf<Events>, EmitOf<Emits>>, InitialE, InitialR, FinalStates, Output, Emits, OutputStates | Extract<HandlerTreeEvidence<AllStates, Config>["outputState"], StateIdentifier<AllStates>>, InputEvents>;
     /**
      * Adds state handlers from a root state object.
      *
-     * **Gotchas**
-     *
-     * Type inference traverses up to eight nested child-state objects. Deeper
-     * handler trees are rejected explicitly instead of silently dropping their
-     * error, service, final-state, or output channels.
-     *
      * @category combinators
      * @since 4.0.0
      */
     interface Handler<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Input extends Schema.Top, UnhandledStates extends StateIdentifier<States>, E, R, InitialE, InitialR, FinalStates extends StateIdentifier<States>, Output, OutputStates extends StateIdentifier<States>, InputEvents extends ReadonlyArray<TaggedSchema>> {
-        <const Config extends HandlerTree<States, States, Events, Emits, E, R, "">>(config: Config & HandlerTreeValidation<States, States, Events, Emits, "", NoInfer<Config>, OutputStates | Extract<HandlerTreeOutputStates<States, States, "", NoInfer<Config>>, StateIdentifier<States>>>): HandleTreeResult<States, Events, Emits, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, OutputStates, InputEvents, Config>;
+        <const Config extends HandlerTree<States, States, Events, Emits, E, R, "">>(config: Config & HandlerTreeValidation<States, Events, Emits, NoInfer<Config>, OutputStates | Extract<HandlerTreeEvidence<States, NoInfer<Config>>["outputState"], StateIdentifier<States>>>): HandleTreeResult<States, Events, Emits, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, OutputStates, InputEvents, Config>;
     }
     /**
      * Any state config.
@@ -2619,16 +3037,18 @@ export declare namespace Machine {
      * @category utility types
      * @since 4.0.0
      */
-    type AnyStateConfig = StateConfig<any, any, any, any, any, any, any>;
+    type AnyStateConfig = StateConfig<any, any, any, any, any, any, any> | ChoiceStateConfig<any, any, any, any>;
     /**
      * Runtime event-handler map stored for a single state tag.
      *
      * @category models
      * @since 4.0.0
      */
-    type EventHandlerMap<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, EventTag extends TagOf<Events[number]>, E, R> = Readonly<Record<PropertyKey, ((context: HandlerContext<States, Events, Emits, StateId, EventTag, E, R>) => HandlerResult<States, E, R>) | {
+    type EventHandlerMap<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, EventTag extends TagOf<Events[number]>, E, R> = Readonly<Record<PropertyKey, ((context: HandlerContext<States, Events, Emits, StateId, EventTag, E, R>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => HandlerResult<States, E, R>) | {
         readonly reenter?: boolean;
-        readonly transition: (context: HandlerContext<States, Events, Emits, StateId, EventTag, E, R>) => HandlerResult<States, E, R>;
+        /** Statically declared upper bound of possible target paths. */
+        readonly targets?: ReadonlyArray<StateNodeIdentifier<States>>;
+        readonly transition: (context: HandlerContext<States, Events, Emits, StateId, EventTag, E, R>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => HandlerResult<States, E, R>;
     }>>;
     /**
      * Runtime state config stored for a single state tag.
@@ -2637,11 +3057,17 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     interface StateConfig<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, EventTag extends TagOf<Events[number]>, E, R> {
-        readonly entry?: (context: StateActionContext<States, Events, Emits, StateId>) => StateActionResult<E, R>;
-        readonly exit?: (context: StateActionContext<States, Events, Emits, StateId>) => StateActionResult<E, R>;
+        readonly entry?: (context: StateActionContext<States, Events, Emits, StateId>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => StateActionResult<E, R>;
+        readonly exit?: (context: StateActionContext<States, Events, Emits, StateId>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => StateActionResult<E, R>;
         readonly invoke?: InvokeDefinition<States, Events, Emits, StateId>;
-        readonly always?: (context: AlwaysContext<States, Events, Emits, StateId>) => HandlerResult<States, E, R>;
-        readonly onDone?: (context: DoneContext<States, Events, Emits, StateId>) => HandlerResult<States, E, R>;
+        readonly always?: ((context: AlwaysContext<States, Events, Emits, StateId>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => HandlerResult<States, E, R>) | {
+            readonly targets?: ReadonlyArray<StateNodeIdentifier<States>>;
+            readonly transition: (context: AlwaysContext<States, Events, Emits, StateId>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => HandlerResult<States, E, R>;
+        };
+        readonly onDone?: ((context: DoneContext<States, Events, Emits, StateId>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => HandlerResult<States, E, R>) | {
+            readonly targets?: ReadonlyArray<StateNodeIdentifier<States>>;
+            readonly transition: (context: DoneContext<States, Events, Emits, StateId>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => HandlerResult<States, E, R>;
+        };
         readonly output?: ((context: FinalOutputContext<States, Events, StateId>) => unknown) | ((context: ParallelOutputContext<States, Events, StateId>) => unknown);
         readonly on?: EventHandlerMap<States, Events, Emits, StateId, EventTag, E, R>;
     }
@@ -2651,7 +3077,7 @@ export declare namespace Machine {
      * @category models
      * @since 4.0.0
      */
-    type StateConfigs<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, EventTag extends TagOf<Events[number]>, E, R> = Readonly<Record<PropertyKey, StateConfig<States, Events, Emits, StateId, EventTag, E, R>>>;
+    type StateConfigs<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, EventTag extends TagOf<Events[number]>, E, R> = Readonly<Record<PropertyKey, StateConfig<States, Events, Emits, StateId, EventTag, E, R> | ChoiceStateConfig<States, Events, Emits, ChoiceIdentifier<States>>>>;
 }
 /**
  * Returns `true` if a value is a `Machine`.
@@ -2769,6 +3195,35 @@ interface Make {
  * @since 4.0.0
  */
 export declare const make: Make;
+type EventConstructorArgs<EventSchema extends Machine.TaggedSchema> = {} extends EventSchema["~type.make.in"] ? [
+    input?: EventSchema["~type.make.in"]
+] : [input: EventSchema["~type.make.in"]];
+/**
+ * Constructs an event from a schema owned by a machine's protocol.
+ *
+ * **Details**
+ *
+ * The schema constructor runs exactly once. The resulting decoded event is
+ * trusted by this machine and definitions derived from it with `handle`, so
+ * repeated delivery does not decode the same already-constructed value again.
+ * Events supplied through ordinary `send` and `plan` calls remain untrusted
+ * and continue through full runtime schema validation.
+ * Treat the returned event as immutable after construction.
+ *
+ * The schema must be one of the machine's configured public or internal event
+ * schemas, or a case schema belonging to a configured `Schema.TaggedUnion`.
+ *
+ * **Example**
+ *
+ * ```ts
+ * const increment = Machine.event(counter, Increment, { by: 1 })
+ * yield* ref.send(increment)
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const event: <const M extends Machine.Any, const EventSchema extends Machine.TaggedSchema>(machine: M, schema: EventSchema & ([EventSchema["Type"]] extends [Machine.Event<M>] ? unknown : never), ...args: EventConstructorArgs<EventSchema>) => EventSchema["Type"];
 /**
  * Encodes a decoded machine snapshot into a normalized data representation.
  *
@@ -2984,48 +3439,120 @@ type InvokeMachineInput<Input extends Schema.Top> = Input extends typeof Schema.
  */
 export declare const invokeMachine: {
     <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, SnapshotEvent = never, DoneEvent = never, Id extends string = string, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(config: {
-        readonly child: ChildMachine<Id, Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents> & Machine.EnsureOutputImplementations<States, OutputStates> & Machine.EnsureHistoryImplementations<States, UnhandledStates>>;
+        readonly child: ChildMachine<Id, Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents> & EnsureExecutable<States, UnhandledStates, OutputStates>>;
         readonly snapshot?: (context: Machine.InvokeSnapshotContext<Machine.Snapshot<States>, E | ActionError<R> | InfiniteTransitionError | MachineSchemaDecodeError | StoppedError, Output>) => SnapshotEvent | undefined;
         readonly onDone: (context: Machine.InvokeDoneContext<Output>) => DoneEvent | undefined;
     } & InvokeMachineInput<Input>): Machine.InvokeConfig<any, any, any, any, SnapshotEvent, Machine.Snapshot<States>, Machine.EventOf<InputEvents>, E | ActionError<R> | InfiniteTransitionError | MachineSchemaDecodeError | StoppedError, ExcludeCompatibleRuntime<Exclude<ExecutionServices<InitialR | R>, internalRuntime.MachineRuntime>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>, Output, InitialE | E | ActionError<InitialR | R> | InfiniteTransitionError | MachineSchemaDecodeError | StartupError | StoppedError, Machine.EmitOf<Emits>, DoneEvent>;
     <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, SnapshotEvent = never, Id extends string = string, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(config: {
-        readonly child: ChildMachine<Id, Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents> & Machine.EnsureOutputImplementations<States, OutputStates> & Machine.EnsureHistoryImplementations<States, UnhandledStates>>;
+        readonly child: ChildMachine<Id, Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents> & EnsureExecutable<States, UnhandledStates, OutputStates>>;
         readonly snapshot?: (context: Machine.InvokeSnapshotContext<Machine.Snapshot<States>, E | ActionError<R> | InfiniteTransitionError | MachineSchemaDecodeError | StoppedError, Output>) => SnapshotEvent | undefined;
         readonly onDone?: never;
     } & InvokeMachineInput<Input>): Machine.InvokeConfig<any, any, any, any, SnapshotEvent, Machine.Snapshot<States>, Machine.EventOf<InputEvents>, E | ActionError<R> | InfiniteTransitionError | MachineSchemaDecodeError | StoppedError, ExcludeCompatibleRuntime<Exclude<ExecutionServices<InitialR | R>, internalRuntime.MachineRuntime>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>, Output, InitialE | E | ActionError<InitialR | R> | InfiniteTransitionError | MachineSchemaDecodeError | StartupError | StoppedError, Machine.EmitOf<Emits>>;
 };
 /**
- * Plans the initial state for a machine without running deferred actions.
+ * Plans the initial state for a machine without executing actor commands.
  *
  * **Details**
  *
- * The returned plan contains the settled initial snapshot, staged actions,
- * emitted events, and optional final output. Planning may evaluate transition
- * logic and follow completion, eventless, and raised-event steps, but it does
- * not execute effects passed to `action`.
+ * The returned plan contains the settled initial snapshot, actor commands,
+ * emitted events, optional final output, and every startup microstep. Planning
+ * may evaluate transition logic and follow completion, eventless, and
+ * raised-event steps. Transition callbacks are evaluated synchronously.
+ * `startingState` and `initialEntryPaths` describe the normalized
+ * configuration before entry callbacks and settlement begin.
  *
  * **Gotchas**
  *
- * Callers that execute a plan manually must run actions sequentially before
- * publishing its state or delivering its emitted events. `start` performs this
- * protocol automatically.
+ * `start` executes the closed command list as part of the managed actor commit
+ * protocol. Manual planners may inspect commands but need a running actor scope
+ * to execute child-addressed operations.
  *
  * @see {@link plan} for planning a received event.
  * @see {@link start} for the managed runtime protocol.
  * @category constructors
  * @since 4.0.0
  */
-export declare const planInitial: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents> & Machine.EnsureOutputImplementations<States, OutputStates> & Machine.EnsureHistoryImplementations<States, UnhandledStates>, ...args: [...Machine.InputArgs<Input>]) => Effect.Effect<{
+export declare const planInitial: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents> & EnsureExecutable<States, UnhandledStates, OutputStates>, ...args: [...Machine.InputArgs<Input>]) => Effect.Effect<{
+    readonly startingState: Machine.Snapshot<States>;
+    readonly initialEntryPaths: ReadonlyArray<Machine.StateIdentifier<States>>;
     readonly state: Machine.Snapshot<States>;
-    readonly actions: ReadonlyArray<Effect.Effect<void, ActionError<InitialR | R>, ActionServices<InitialR | R>>>;
+    readonly commands: ReadonlyArray<Command>;
     readonly emittedEvents: ReadonlyArray<Machine.EmitOf<Emits>>;
+    readonly microsteps: ReadonlyArray<{
+        readonly next: Machine.Snapshot<States>;
+        readonly event: Machine.EventOf<Events> | InitialEvent;
+        readonly transitions: ReadonlyArray<Machine.RetainedTransition<Machine.StateNodeIdentifier<States>, Machine.TagOf<Events[number]>, Machine.StateNodeIdentifier<States>>>;
+        readonly commands: ReadonlyArray<Command>;
+        readonly raisedEvents: ReadonlyArray<Machine.EventOf<Events>>;
+        readonly emittedEvents: ReadonlyArray<Machine.EmitOf<Emits>>;
+        readonly exitPaths: ReadonlyArray<string>;
+        readonly entryPaths: ReadonlyArray<string>;
+        readonly changed: boolean;
+    }>;
 } & ({
     readonly done: true;
     readonly output: Output;
 } | {
     readonly done: false;
     readonly output: undefined;
-}), InitialE | E | InfiniteTransitionError | MachineSchemaDecodeError | StartupError, ExcludeCompatibleRuntime<PlanningServices<InitialR | R>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>>;
+}), InitialE | E | InfiniteTransitionError | MachineSchemaDecodeError | StartupError, never>;
+/**
+ * Returns every compiled state node in definition order.
+ *
+ * **Details**
+ *
+ * The result includes atomic, compound, parallel, final, history, and choice
+ * nodes together with their resolved descriptive annotations. Use each node's
+ * `parent` property to reconstruct the complete hierarchy. Pseudo-states are
+ * intentionally omitted from `children` because they can never appear in an
+ * active configuration.
+ *
+ * @category getters
+ * @since 4.0.0
+ */
+export declare const stateNodes: <M extends Machine.Any>(machine: M) => ReadonlyArray<Machine.StateNode<Machine.StateIdentifier<Machine.States<M>>, Machine.HistoryIdentifier<Machine.States<M>>, Machine.ChoiceIdentifier<Machine.States<M>>>>;
+/**
+ * Returns every registered transition handler in state definition order.
+ *
+ * **Details**
+ *
+ * Event handlers retain their handler-key order within each source state and
+ * are followed by eventless and completion handlers. This function does not
+ * execute handlers. Object-form event, eventless, and completion handlers with
+ * a `targets` declaration expose those possible paths; handlers without one
+ * remain dynamic.
+ *
+ * @category getters
+ * @since 4.0.0
+ */
+export declare const transitionDefinitions: <M extends Machine.Any>(machine: M) => ReadonlyArray<Machine.TransitionDefinition<Machine.StateNodeIdentifier<Machine.States<M>>, Machine.TagOf<Machine.Events<M>[number]>, Machine.StateNodeIdentifier<Machine.States<M>>>>;
+/**
+ * Returns serializable descriptions of every state-owned activity.
+ *
+ * **Details**
+ *
+ * Static `invoke`, `invokeEffect`, `after`, and `invokeMachine` descriptors
+ * expose stable ownership and lifecycle metadata without serializing runtime
+ * values. Function-valued invoke factories are represented as dynamic and are
+ * never evaluated during inspection.
+ *
+ * @category getters
+ * @since 4.0.0
+ */
+export declare const activityDefinitions: <M extends Machine.Any>(machine: M) => ReadonlyArray<Machine.ActivityDefinition<Machine.StateIdentifier<Machine.States<M>>>>;
+/**
+ * Returns every state node active in a decoded snapshot, in definition order.
+ *
+ * **Details**
+ *
+ * Active compound ancestors and parallel regions are included together with
+ * their active descendants. History and choice pseudo-states are never active
+ * and are not returned.
+ *
+ * @category getters
+ * @since 4.0.0
+ */
+export declare const configuration: <M extends Machine.Any>(machine: M, state: Machine.Snapshot<Machine.States<M>>) => ReadonlyArray<Machine.ActiveStateNode<Machine.StateIdentifier<Machine.States<M>>, Machine.ChoiceIdentifier<Machine.States<M>>>>;
 /**
  * Returns the event tags handled by the current state snapshot.
  *
@@ -3034,7 +3561,7 @@ export declare const planInitial: <const States extends Machine.StateSchemas, co
  */
 export declare const enabled: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema>, const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents>, state: Machine.Snapshot<States>) => ReadonlyArray<Machine.TagOf<Events[number]>>;
 /**
- * Plans the next state snapshot without running deferred actions.
+ * Plans the next state snapshot synchronously.
  *
  * **Details**
  *
@@ -3045,25 +3572,25 @@ export declare const enabled: <const States extends Machine.StateSchemas, const
  *
  * **Gotchas**
  *
- * `plan` returns data; it does not implement the runtime commit protocol. Run
- * actions sequentially, publish `next` only after they succeed, and then
- * deliver `emittedEvents`. A failed action must retain the previously
- * published state and suppress emissions. Events with no enabled transition
- * are ignored and produce an unchanged plan.
+ * `plan` returns data; it does not implement the actor commit protocol.
+ * `start` executes child commands, publishes `next`, and then delivers
+ * `emittedEvents`. Events with no enabled transition are ignored and produce
+ * an unchanged plan.
  *
  * @see {@link planInitial} for planning machine startup.
  * @see {@link start} for managed execution and lifecycle observation.
  * @category combinators
  * @since 4.0.0
  */
-export declare const plan: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents> & Machine.EnsureOutputImplementations<States, OutputStates> & Machine.EnsureHistoryImplementations<States, UnhandledStates>, state: Machine.Snapshot<States>, event: Machine.EventOf<InputEvents>) => Effect.Effect<{
+export declare const plan: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents> & EnsureExecutable<States, UnhandledStates, OutputStates>, state: Machine.Snapshot<States>, event: Machine.EventOf<InputEvents>) => Effect.Effect<{
     readonly next: Machine.Snapshot<States>;
-    readonly actions: ReadonlyArray<Effect.Effect<void, ActionError<R>, ActionServices<R>>>;
+    readonly commands: ReadonlyArray<Command>;
     readonly emittedEvents: ReadonlyArray<Machine.EmitOf<Emits>>;
     readonly microsteps: ReadonlyArray<{
         readonly next: Machine.Snapshot<States>;
         readonly event: Machine.EventOf<Events> | InitialEvent;
-        readonly actions: ReadonlyArray<Effect.Effect<void, ActionError<R>, ActionServices<R>>>;
+        readonly transitions: ReadonlyArray<Machine.RetainedTransition<Machine.StateNodeIdentifier<States>, Machine.TagOf<Events[number]>, Machine.StateNodeIdentifier<States>>>;
+        readonly commands: ReadonlyArray<Command>;
         readonly raisedEvents: ReadonlyArray<Machine.EventOf<Events>>;
         readonly emittedEvents: ReadonlyArray<Machine.EmitOf<Emits>>;
         readonly exitPaths: ReadonlyArray<string>;
@@ -3076,67 +3603,7 @@ export declare const plan: <const States extends Machine.StateSchemas, const Eve
 } | {
     readonly done: false;
     readonly output: undefined;
-}), E | InfiniteTransitionError | MachineSchemaDecodeError, ExcludeCompatibleRuntime<PlanningServices<R>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>>;
-/**
- * Defers an effectful action until the current machine step is planned.
- *
- * **Details**
- *
- * The action's error and service requirements are retained in the machine
- * type without becoming requirements of `plan` or `planInitial`. The managed
- * runtime executes staged actions sequentially before publishing the planned
- * state. Pass a second argument when the planning Effect should return that
- * value after staging.
- *
- * **Example** (Typed staged action)
- *
- * ```ts
- * import { Context, Effect } from "effect"
- * import { Machine } from "@typeonce/effect-machine"
- *
- * class Audit extends Context.Service<Audit, {
- *   readonly write: Effect.Effect<void, "AuditError">
- * }>()("example/Audit") {}
- *
- * const writeAudit = Machine.action(
- *   Effect.flatMap(Audit, (audit) => audit.write)
- * )
- * ```
- *
- * @see {@link plan} for inspecting staged actions without executing them.
- * @category combinators
- * @since 4.0.0
- */
-export declare const action: Machine.Action;
-/**
- * Runs staged machine actions sequentially with the supplied runtime.
- *
- * **When to use**
- *
- * Use when you implement a commit protocol around `plan` or `planInitial` and
- * need to execute their staged actions before publishing the planned snapshot.
- *
- * **Gotchas**
- *
- * This function only runs actions. The caller remains responsible for
- * publishing the planned state and delivering planned emitted events after all
- * actions succeed. Process-local operations such as `spawn`, `sendTo`, and
- * `stopChild` fail with `ProcessLocalError` because no managed machine process
- * owns the actions.
- *
- * @see {@link plan} for creating a transition plan.
- * @see {@link planInitial} for creating an initial plan.
- * @category running
- * @since 4.0.0
- */
-export declare const runActions: <E, R, Events, Emits>(actions: Iterable<Effect.Effect<void, E, R>>, runtime: Runtime<Events, Emits>) => Effect.Effect<void, E | ProcessLocalError, Exclude<ExcludeCompatibleRuntime<R, Events, Emits>, MachineRuntimeRequirement>>;
-/**
- * Returns the typed runtime capability for the current machine.
- *
- * @category combinators
- * @since 4.0.0
- */
-export declare const runtime: <const Protocol extends Runtime.Protocol = {}>() => Effect.Effect<Runtime<Runtime.Events<Protocol>, Runtime.Emits<Protocol>>, never, Runtime.Requirement<Runtime.Events<Protocol>, Runtime.Emits<Protocol>>>;
+}), E | InfiniteTransitionError | MachineSchemaDecodeError, never>;
 /**
  * Creates a one-shot child process from an Effect.
  *
@@ -3256,15 +3723,14 @@ export declare const childAddress: <Event = never>(id: string) => ChildAddress<E
  *
  * **When to use**
  *
- * Use to create child processes from machine actions when the child
- * should be addressed or stopped by the owning machine instead of tied to a
- * single state's `invoke` lifecycle.
+ * Use from lower-level process logic to create children that should be
+ * addressed or stopped by the owning process instead of tied to a single
+ * state's `invoke` lifecycle.
  *
  * **Gotchas**
  *
- * This effect requires the machine runtime, so it only runs from machine
- * actions. A named child id must be unique for the current parent machine until
- * that child stops.
+ * This Effect requires a managed process runtime. A named child id must be
+ * unique for the current parent until that child stops.
  *
  * @see {@link invoke} for children that start and stop with a state.
  * @see {@link sendTo} for sending events to named children.
@@ -3312,11 +3778,10 @@ export declare const watch: <State, Event, Error = never, Output = never>(ref: M
  *
  * **Details**
  *
- * For each accepted event the runtime plans the complete macrostep, runs staged
- * actions sequentially, stops invokes for exited states, publishes the new
- * state, delivers emitted events, and then starts invokes for entered states.
- * If an action fails, the previous published state is retained and emissions
- * from that plan are suppressed.
+ * For each accepted event the runtime plans the complete synchronous
+ * macrostep, executes closed actor commands, stops invokes for exited states,
+ * publishes the new state, delivers emitted events, and then starts invokes
+ * for entered states.
  *
  * **Gotchas**
  *
@@ -3330,5 +3795,35 @@ export declare const watch: <State, Event, Error = never, Output = never>(ref: M
  * @category constructors
  * @since 4.0.0
  */
-export declare const start: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents> & Machine.EnsureOutputImplementations<States, OutputStates> & Machine.EnsureHistoryImplementations<States, UnhandledStates>, ...args: [...Machine.InputArgs<Input>]) => Effect.Effect<MachineRef<Machine.Snapshot<States>, Machine.EventOf<InputEvents>, E | ActionError<R> | InfiniteTransitionError | MachineSchemaDecodeError | StoppedError, Output>, InitialE | E | ActionError<InitialR | R> | InfiniteTransitionError | MachineSchemaDecodeError | StartupError | StoppedError, ExcludeCompatibleRuntime<ExecutionServices<InitialR | R>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>>;
+export declare const start: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents> & EnsureExecutable<States, UnhandledStates, OutputStates>, ...args: [...Machine.InputArgs<Input>]) => Effect.Effect<MachineRef<Machine.Snapshot<States>, Machine.EventOf<InputEvents>, E | ActionError<R> | InfiniteTransitionError | MachineSchemaDecodeError | StoppedError, Output>, InitialE | E | ActionError<InitialR | R> | InfiniteTransitionError | MachineSchemaDecodeError | StartupError | StoppedError, ExcludeCompatibleRuntime<ExecutionServices<InitialR | R>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>>;
+/**
+ * Starts a fresh managed runtime from a decoded logical snapshot.
+ *
+ * **Details**
+ *
+ * `resume` validates and normalizes the supplied snapshot before publishing it
+ * as the first state. It does not call the machine's initial function, replay
+ * entry or transition actions, re-deliver raised or emitted events, or
+ * re-evaluate historical completion and eventless transitions. Active-state
+ * invokes start once in ancestor and document order with {@link InitialEvent};
+ * delayed invokes restart their complete duration and invoked machines start
+ * from their own initial state.
+ *
+ * Only logical state, completion, and history metadata are resumed. Queues,
+ * scopes, subscriptions, fibers, spawned children, invoke progress, and prior
+ * runtime status are process-local and are not restored. A final snapshot
+ * immediately produces a completed ref with its current-machine output.
+ *
+ * Decode encoded data explicitly with {@link decodeSnapshot} before calling
+ * this function. Stable snapshots are hosted as supplied; newly enabled
+ * eventless or completion transitions in a changed machine definition are not
+ * evaluated merely because the runtime was resumed; only ordinary subsequent
+ * transition planning can enter and stabilize states.
+ *
+ * @see {@link decodeSnapshot} for the schema and transport boundary.
+ * @see {@link start} for ordinary initial startup.
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const resume: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents> & EnsureExecutable<States, UnhandledStates, OutputStates>, snapshot: Machine.Snapshot<States>) => Effect.Effect<MachineRef<Machine.Snapshot<States>, Machine.EventOf<InputEvents>, E | ActionError<R> | InfiniteTransitionError | MachineSchemaDecodeError | StoppedError, Output>, MachineSchemaDecodeError, ExcludeCompatibleRuntime<ExecutionServices<R>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>>;
 //# sourceMappingURL=Machine.d.ts.map