@typeonce/effect-machine 0.20.0 → 0.22.0

package/README.md

@@ -149,16 +149,26 @@ parallel root.
 
 ### Construct state through builders
 
-Use `.from(...)` when constructing a new state from fields:
+Use `.from(...)` when constructing a new state from schema make input:
 
 ```ts
 target.from({ draft: event.draft })
 ```
 
 The machine runs these inputs through the state schema while planning. Schema
-defaults, refinements, and tagged-class identity are therefore preserved, and
-decode failures remain typed machine failures. Pass a value directly only when
-it is already decoded.
+defaults, transformations, refinements, and tagged-class identity are
+therefore preserved, and decode failures remain typed machine failures. This
+is the default construction path.
+
+Use `.decoded(...)` when the value is already a `Schema.Type`:
+
+```ts
+target.decoded(new Ready({ notice: null }))
+```
+
+The machine still validates the value against the schema's type side. It does
+not run encoded-input transformations again. State builders are not callable;
+the method name always makes the construction mode visible.
 
 When sibling states share fields, remove the source discriminator and pass the
 remaining fields through the target schema:
@@ -190,7 +200,7 @@ const States = Machine.states({
 const definition = Machine.make({
   states: States.states,
   events: Machine.events(),
-  initial: (to) => to.Form.initial.resolve(({ target }) => target((form) => form.Editing.from()))
+  initial: (to) => to.Form.initial.resolve(({ target }) => target.from((form) => form.Editing.from()))
 })
 ```
 
@@ -420,6 +430,106 @@ choice destinations remain calls such as `to.full.Running()`. Runtime named
 branch builders remain callable, including `select.unchanged()`, because their
 result carries the selected branch evidence.
 
+### Update an active scope value
+
+Use `to.local.update(...)` to replace the value owned by the nearest active
+compound scope without rebuilding its active child. Use
+`to.branch.<path>.update(...)` for a valued compound or parallel ancestor of the
+handler source:
+
+```ts
+const handlers = {
+  Increment: (to) => to.branch.root.session.update(({ current, owner }) => owner.from({ count: current.count + 1 }))
+}
+```
+
+The update keeps the exact active descendants, their values, history records,
+completion outputs, and unrelated parallel regions. It runs no exit or entry
+actions and does not restart state-owned work. Eventless stabilization still
+runs, so an `always` transition can react to the new value.
+
+The plain update method remains useful when topology does not change. It is
+also a static selection for a named branch:
+
+```ts
+to.branches({
+  changed: { target: to.local.update },
+  unchanged: { target: to.none }
+}).resolve(({ select, event }) =>
+  event.changed
+    ? select.changed.from({ count: event.count })
+    : select.unchanged()
+)
+```
+
+### Change topology and a retained owner together
+
+When a transition enters another child and also replaces a valued ancestor
+that stays active, declare both operations on the same target:
+
+```ts
+const handlers = {
+  CreatePlan: (to) =>
+    to.local.SavingPlan()
+      .updating(to.branch.Ready)
+      .resolve(({ current, event, owner, target }) =>
+        target.from({
+          request: { _tag: "Create", input: event.input }
+        }).update(
+          owner.decoded(new Ready({ ...current, notice: null }))
+        )
+      )
+}
+```
+
+`to.local.SavingPlan()` selects topology. `.updating(to.branch.Ready)` names
+the retained valued owner and makes its replacement mandatory: the resolver
+does not type-check unless destination construction finishes with
+`.update(...)`. `current` is that owner's decoded value from the
+pre-transition snapshot. `target` constructs the destination; `owner`
+constructs the complete replacement owner value.
+
+The topology change and owner replacement apply atomically in one microstep.
+The owner does not exit or reenter, its work is not restarted, and destination
+entry actions observe the new owner value. Eventless stabilization follows.
+Only one retained owner may be replaced by a combined target. A `full` target,
+or any target that exits the selected owner, does not expose `.updating`.
+Combined updates use a direct resolver in this release; named branches continue
+to support value-only updates.
+
+For a schema-less destination, construction remains explicit:
+
+```ts
+to.local.Idle()
+  .updating(to.branch.Ready)
+  .resolve(({ current, output, owner, target }) =>
+    target.from().update(
+      owner.decoded(
+        new Ready({
+          ...current,
+          day: output,
+          notice: "Plan changed."
+        })
+      )
+    )
+  )
+```
+
+Both values derive from the same pre-transition snapshot and are validated
+before lifecycle actions run. Competing transitions that write the same owner
+conflict; document order and hierarchy select one writer rather than applying
+last-write-wins behavior.
+
+The resolver must return `target.decoded(value)` or `target.from(input)`. It
+may return `decline()` only with `{ declinable: true }`. Pass `{ reenter: true }`
+on event or invocation transitions when the handler source should exit and
+enter again. Reentry applies to that source, not to the ancestor whose value
+changed.
+
+The selector omits `update` for schema-less scopes, atomic and final states,
+inactive branches, parallel sibling regions, and choice resolvers. Updating a
+parallel sibling requires an event handled by that region.
+
 Use `declinable: true` when a resolver may decide that its transition is not
 enabled. Only that resolver receives `decline()`, and its return type expands to
 accept the opaque declined result:

package/dist/Machine.d.ts

@@ -191,7 +191,7 @@ export interface Definition<States extends Machine.StateSchemas, Events extends
      *     on: {
      *       Increment: (to) =>
      *         to.full.Count().resolve(({ event, state, target }) =>
-     *           target(new Count({ value: state.value + event.by })))
+     *           target.decoded(new Count({ value: state.value + event.by })))
      *     }
      *   }
      * })
@@ -616,6 +616,15 @@ type FromMethod<Arguments extends ReadonlyArray<unknown>, Result> = {
      */
     readonly from: FromCallable<Arguments, Machine.StateConstruction<Result>>;
 };
+type DecodedMethod<Arguments extends ReadonlyArray<unknown>, Result> = {
+    /**
+     * Constructs the selected state from an already-decoded schema value. The
+     * machine validates the value against the schema's type side while planning.
+     *
+     * @since 0.22.0
+     */
+    readonly decoded: (...args: Arguments) => Result;
+};
 type ConstructionResult<Result> = Result | Machine.StateConstruction<Result>;
 type UnwrapConstruction<Result> = Result extends Machine.StateConstruction<infer Value> ? Value : Result;
 type NodeValue<Node> = [Machine.NodeSchema<Node>] extends [never] ? undefined : Machine.NodeSchema<Node>["Type"];
@@ -624,14 +633,14 @@ type WithNodeValue<Node, Rest extends ReadonlyArray<unknown>> = Machine.NodeSche
 type WithNodeInput<Node, Rest extends ReadonlyArray<unknown>> = Machine.NodeSchema<Node> extends never ? Rest : readonly [input: NodeMakeInput<Node>, ...Rest];
 type NodeBuilderMethod<Node, Arguments extends ReadonlyArray<unknown>, Result, FromArguments extends ReadonlyArray<unknown>, FromResult> = Machine.NodeSchema<Node> extends never ? {
     readonly from: FromCallable<FromArguments, FromResult>;
-} : ((...args: Arguments) => Result) & {
+} : DecodedMethod<Arguments, Result> & {
     readonly from: FromCallable<FromArguments, FromResult>;
 };
-type NodeMethod<Node, Arguments extends ReadonlyArray<unknown>, Result, FromArguments extends ReadonlyArray<unknown>> = Machine.NodeSchema<Node> extends never ? FromMethod<FromArguments, Result> : ((...args: Arguments) => Result) & FromMethod<FromArguments, Result>;
+type NodeMethod<Node, Arguments extends ReadonlyArray<unknown>, Result, FromArguments extends ReadonlyArray<unknown>> = Machine.NodeSchema<Node> extends never ? FromMethod<FromArguments, Result> : DecodedMethod<Arguments, Result> & FromMethod<FromArguments, Result>;
 type NodeMethodWithInitial<Node, Arguments extends ReadonlyArray<unknown>, Result, FromArguments extends ReadonlyArray<unknown>, Path extends string> = Machine.NodeSchema<Node> extends never ? {
     readonly from: FromCallable<FromArguments, Machine.StateConstruction<Result>>;
     readonly initial: InitialTargetFactory<Node, Path>;
-} : ((...args: Arguments) => Result) & {
+} : DecodedMethod<Arguments, Result> & {
     readonly from: FromCallable<FromArguments, Machine.StateConstruction<Result>>;
     readonly initial: InitialTargetFactory<Node, Path>;
 };
@@ -640,8 +649,8 @@ interface InitialTargetMethod<Node, Path extends string> {
     readonly initial: InitialTargetFactory<Node, Path>;
 }
 interface InitialTargetFactory<Node, Path extends string> {
-    (...args: WithNodeValue<Node, readonly []>): Machine.InitialTarget<Path>;
     readonly from: FromCallable<WithNodeInput<Node, readonly []>, Machine.StateConstruction<Machine.InitialTarget<Path>>>;
+    readonly decoded: (...args: WithNodeValue<Node, readonly []>) => Machine.InitialTarget<Path>;
 }
 type NodeConstructionSelectorFromCallable<Node, Builder, Result> = Machine.NodeSchema<Node> extends never ? {
     <Selected extends ConstructionResult<Result>>(state: (builder: Builder) => Selected): Machine.StateConstruction<UnwrapConstruction<Selected>>;
@@ -649,7 +658,8 @@ type NodeConstructionSelectorFromCallable<Node, Builder, Result> = Machine.NodeS
 type NestedTargetMethod<Node, Builder, Result, Path extends string> = Machine.NodeSchema<Node> extends never ? {
     readonly from: NodeConstructionSelectorFromCallable<Node, Builder, Result>;
     readonly initial: InitialTargetFactory<Node, Path>;
-} : (<Selected extends ConstructionResult<Result>>(value: NodeValue<Node>, state: (builder: Builder) => Selected) => Selected) & {
+} : {
+    readonly decoded: <Selected extends ConstructionResult<Result>>(value: NodeValue<Node>, state: (builder: Builder) => Selected) => Selected;
     readonly from: NodeConstructionSelectorFromCallable<Node, Builder, Result>;
     readonly initial: InitialTargetFactory<Node, Path>;
 };
@@ -662,7 +672,7 @@ type InitialSnapshotBuilderWithPrefix<States extends Machine.StateSchemas, Prefi
 } & {
     readonly [Key in ChoiceStateKey<States>]: () => Machine.ChoiceTargetInstruction<Machine.JoinPath<Prefix, Key>>;
 };
-type InitialSnapshotMethod<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string> = Machine.NodeSchema<States[StateId]> extends never ? FromMethod<InitialSnapshotFromArguments<States, StateId, Prefix>, InitialSnapshotResult<States, StateId, Prefix>> : ((...args: InitialSnapshotArguments<States, StateId, Prefix>) => InitialSnapshotResult<States, StateId, Prefix>) & FromMethod<InitialSnapshotFromArguments<States, StateId, Prefix>, InitialSnapshotResult<States, StateId, Prefix>>;
+type InitialSnapshotMethod<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string> = Machine.NodeSchema<States[StateId]> extends never ? FromMethod<InitialSnapshotFromArguments<States, StateId, Prefix>, InitialSnapshotResult<States, StateId, Prefix>> : DecodedMethod<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 {
     readonly type: "parallel";
     readonly states: infer Children extends Machine.StateSchemas;
@@ -711,7 +721,7 @@ type FullSnapshotBuilderWithPrefix<States extends Machine.StateSchemas, Prefix e
 } & {
     readonly [Key in ChoiceStateKey<States>]: () => Machine.ChoiceTargetInstruction<Machine.JoinPath<Prefix, Key>>;
 };
-type FullSnapshotMethod<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string> = Machine.NodeSchema<States[StateId]> extends never ? FromMethod<FullSnapshotFromArguments<States, StateId, Prefix>, FullSnapshotResult<States, StateId, Prefix>> : ((...args: FullSnapshotArguments<States, StateId, Prefix>) => FullSnapshotResult<States, StateId, Prefix>) & FromMethod<FullSnapshotFromArguments<States, StateId, Prefix>, FullSnapshotResult<States, StateId, Prefix>>;
+type FullSnapshotMethod<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string> = Machine.NodeSchema<States[StateId]> extends never ? FromMethod<FullSnapshotFromArguments<States, StateId, Prefix>, FullSnapshotResult<States, StateId, Prefix>> : DecodedMethod<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 {
     readonly type: "parallel";
     readonly states: infer Children extends Machine.StateSchemas;
@@ -774,7 +784,7 @@ type HistorySnapshotResult<States extends Machine.StateSchemas, StateId extends
 } ? Machine.ParallelSnapshot<Path, NodeValue<Node>, HistorySnapshotRegions<Children, Path, Owner>> : Node extends {
     readonly states: infer Children extends Machine.StateSchemas;
 } ? Machine.CompoundSnapshot<Path, NodeValue<Node>, HistorySnapshotWithPrefix<Children, Owner, Path>> : never : never;
-type HistorySnapshotMethod<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string, Owner extends string> = Machine.NodeSchema<States[StateId]> extends never ? FromMethod<HistorySnapshotFromArguments<States, StateId, Prefix, Owner>, HistorySnapshotResult<States, StateId, Prefix, Owner>> : ((...args: HistorySnapshotArguments<States, StateId, Prefix, Owner>) => HistorySnapshotResult<States, StateId, Prefix, Owner>) & FromMethod<HistorySnapshotFromArguments<States, StateId, Prefix, Owner>, HistorySnapshotResult<States, StateId, Prefix, Owner>>;
+type HistorySnapshotMethod<States extends Machine.StateSchemas, StateId extends ActiveStateKey<States>, Prefix extends string, Owner extends string> = Machine.NodeSchema<States[StateId]> extends never ? FromMethod<HistorySnapshotFromArguments<States, StateId, Prefix, Owner>, HistorySnapshotResult<States, StateId, Prefix, Owner>> : DecodedMethod<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>];
@@ -836,7 +846,8 @@ type LocalTargetBuilderForScope<States extends Machine.StateSchemas, Scope exten
      *
      * @since 0.4.0
      */
-    readonly with: (<Result extends ConstructionResult<LocalTargetResultWithPrefix<States, Children, Scope>>>(value: Machine.StateByIdentifier<States, Scope>, state: (builder: LocalTargetBuilderWithPrefix<States, Children, Scope, Source>) => Result) => Result) & {
+    readonly with: {
+        readonly decoded: <Result extends ConstructionResult<LocalTargetResultWithPrefix<States, Children, Scope>>>(value: Machine.StateByIdentifier<States, Scope>, state: (builder: LocalTargetBuilderWithPrefix<States, Children, Scope, Source>) => Result) => Result;
         readonly from: ConstructionSelectorFromCallable<Machine.SchemaByIdentifier<States, Scope>["~type.make.in"], LocalTargetBuilderWithPrefix<States, Children, Scope, Source>, LocalTargetResultWithPrefix<States, Children, Scope>>;
     };
 } : {}) : {};
@@ -2217,12 +2228,14 @@ export declare namespace Machine {
         readonly type: "direct";
         readonly target: Path | undefined;
         readonly selection: TransitionTargetSelection<Path | undefined>;
+        readonly updates: ReadonlyArray<string>;
     } | {
         readonly type: "branch";
         readonly key: string;
         readonly title: string;
         readonly target: Path | undefined;
         readonly selection: TransitionTargetSelection<Path | undefined>;
+        readonly updates: ReadonlyArray<string>;
     };
     /** The statically selected root entry for machine startup. */
     interface InitialDefinition<Path extends string = string> {
@@ -2234,9 +2247,10 @@ export declare namespace Machine {
      *
      * **Details**
      *
-     * Every branch exposes its selected target without executing its resolver.
-     * A compound local or branch target covers its descendants;
-     * `undefined` identifies an explicitly targetless branch.
+     * Every branch exposes its static selection without executing its resolver.
+     * A compound local or branch target covers its descendants. An `update`
+     * selection keeps `target` undefined and records its value owner in
+     * `selection.path`; `none` identifies an explicitly targetless branch.
      *
      * @category models
      * @since 0.4.0
@@ -2281,6 +2295,8 @@ export declare namespace Machine {
          * Choice microsteps retain each intermediate pseudo-state edge separately.
          */
         readonly resolvedTarget: TargetPath | undefined;
+        /** Retained valued owners replaced by this transition. */
+        readonly updates: ReadonlyArray<string>;
     }
     /**
      * Constructor arguments for a machine initial state function.
@@ -2841,6 +2857,38 @@ export declare namespace Machine {
             readonly [AncestorStateId in ValuedStateIdentifier<States>]: StateByIdentifier<States, AncestorStateId>;
         }>;
     }
+    /**
+     * Opaque instruction that replaces one active compound or parallel state's
+     * value without changing its active descendants.
+     *
+     * @category models
+     * @since 0.21.0
+     */
+    interface StateUpdate<States extends StateSchemas, StateId extends ValuedStateIdentifier<States>> {
+        readonly [Topology.StateUpdateTypeId]: {
+            readonly states: Types.Covariant<States>;
+            readonly owner: Types.Covariant<StateId>;
+        };
+    }
+    /**
+     * Opaque result that combines one topology target with one retained owner
+     * value replacement in the same microstep.
+     *
+     * @category models
+     * @since 0.22.0
+     */
+    interface CombinedTarget<Result, States extends StateSchemas, Owner extends ValuedStateIdentifier<States>> {
+        readonly [Topology.CombinedTargetTypeId]: {
+            readonly result: Types.Covariant<Result>;
+            readonly states: Types.Covariant<States>;
+            readonly owner: Types.Covariant<Owner>;
+        };
+    }
+    /** @internal */
+    type StateUpdateBuilder<States extends StateSchemas, StateId extends ValuedStateIdentifier<States>> = {
+        readonly decoded: (value: StateByIdentifier<States, StateId>) => StateUpdate<States, StateId>;
+        readonly from: FromCallable<readonly [input: SchemaByIdentifier<States, StateId>["~type.make.in"]], StateUpdate<States, StateId>>;
+    };
     /**
      * Opaque result returned by an explicitly targetless transition.
      *
@@ -3025,40 +3073,56 @@ export declare namespace Machine {
      * @category models
      * @since 0.14.0
      */
-    interface TargetSelection<out Result, out Path extends string | undefined = string | undefined, out Kind extends Topology.TargetSelectionKind = Topology.TargetSelectionKind> {
+    interface TargetSelection<out Result, out Path extends string | undefined = string | undefined, out Kind extends Topology.TargetSelectionKind = Topology.TargetSelectionKind, out Scope extends Topology.TargetSelectionScope | undefined = Topology.TargetSelectionScope | undefined> {
         readonly [Topology.TargetSelectionTypeId]: typeof Topology.TargetSelectionTypeId;
         readonly kind: Kind;
-        readonly scope: Topology.TargetSelectionScope | undefined;
+        readonly scope: Scope;
         readonly path: Path;
         readonly "~effect/Machine/TargetSelectionResult"?: Types.Covariant<Result>;
     }
-    type SelectionValue<Builder, Path extends string, Kind extends Topology.TargetSelectionKind = "state"> = TargetSelection<Builder, Path, Kind>;
-    type SelectionMethod<Builder, Path extends string, Kind extends Topology.TargetSelectionKind = "state"> = () => SelectionValue<Builder, Path, Kind>;
-    type InitialSelectionMethod<Builder, Path extends string> = Builder extends {
+    type SelectionValue<Builder, Path extends string, Kind extends Topology.TargetSelectionKind = "state", Scope extends Topology.TargetSelectionScope | undefined = Topology.TargetSelectionScope | undefined> = TargetSelection<Builder, Path, Kind, Scope>;
+    type SelectionMethod<Builder, Path extends string, Kind extends Topology.TargetSelectionKind = "state", Scope extends Topology.TargetSelectionScope | undefined = Topology.TargetSelectionScope | undefined> = () => SelectionValue<Builder, Path, Kind, Scope>;
+    type InitialSelectionMethod<Builder, Path extends string, Scope extends Topology.TargetSelectionScope> = Builder extends {
         readonly initial: infer Initial;
     } ? {
-        readonly initial: SelectionValue<Initial, Path, "initial">;
+        readonly initial: SelectionValue<Initial, Path, "initial", Scope>;
     } : {};
     type SelectionTreeWithPrefix<AllStates extends StateSchemas, States extends StateSchemas, Prefix extends string, Scope extends "local" | "branch", Builder> = {
         readonly [Key in Extract<ActiveStateKey<States> | ChoiceStateKey<States>, keyof Builder>]: SelectionNode<AllStates, States[Key], JoinPath<Prefix, Key>, Scope, Builder[Key]>;
     };
-    type SelectionNode<AllStates extends StateSchemas, Node, Path extends string, Scope extends "local" | "branch", Builder> = Node extends ChoiceStateNodeConfig ? SelectionMethod<Builder, Path, "choice"> : Node extends {
+    type SelectionNode<AllStates extends StateSchemas, Node, Path extends string, Scope extends "local" | "branch", Builder> = Node extends ChoiceStateNodeConfig ? SelectionMethod<Builder, Path, "choice", Scope> : Node extends {
         readonly states: infer Children extends StateSchemas;
-    } ? SelectionMethod<Builder, Path> & InitialSelectionMethod<Builder, Path> & SelectionTreeWithPrefix<AllStates, Children, Path, Scope, Builder> : SelectionMethod<Builder, Path>;
+    } ? SelectionMethod<Builder, Path, "state", Scope> & InitialSelectionMethod<Builder, Path, Scope> & SelectionTreeWithPrefix<AllStates, Children, Path, Scope, Builder> : SelectionMethod<Builder, Path, "state", Scope>;
+    /** @internal */
+    type StateUpdateSelectionForNode<AllStates extends StateSchemas, Node, Path extends string, Scope extends "local" | "branch"> = Node extends {
+        readonly states: StateSchemas;
+    } ? NodeSchema<Node> extends never ? {} : {
+        readonly update: SelectionValue<StateUpdateBuilder<AllStates, Extract<Path, ValuedStateIdentifier<AllStates>>>, Path, "update", Scope>;
+    } : {};
+    /** @internal */
+    type BranchUpdateSelectionPath<AllStates extends StateSchemas, Node, Path extends string, Rest extends string, Scope extends "local" | "branch" = "branch"> = StateUpdateSelectionForNode<AllStates, Node, Path, Scope> & (Node extends {
+        readonly states: infer Children extends StateSchemas;
+    } ? Rest extends `${infer Head}.${infer Tail}` ? Head extends keyof Children ? {
+        readonly [Key in Head]: BranchUpdateSelectionPath<AllStates, Children[Head], JoinPath<Path, Head>, Tail, Scope>;
+    } : {} : Rest extends keyof Children ? {
+        readonly [Key in Rest]: StateUpdateSelectionForNode<AllStates, Children[Rest], JoinPath<Path, Rest>, Scope>;
+    } : {} : {});
     type FullSelectionNode<AllStates extends StateSchemas, Node, Path extends StateIdentifier<AllStates>, Builder> = Node extends {
         readonly states: StateSchemas;
-    } ? SelectionMethod<Builder, Path> & InitialSelectionMethod<Builder, Path> : SelectionMethod<Builder, Path>;
+    } ? SelectionMethod<Builder, Path, "state", "full"> & InitialSelectionMethod<Builder, Path, "full"> : SelectionMethod<Builder, Path, "state", "full">;
     type FullTargetSelector<States extends StateSchemas> = {
         readonly [Key in Extract<ActiveStateKey<States>, keyof FullTargetBuilder<States>>]: FullSelectionNode<States, States[Key], Extract<Key, StateIdentifier<States>>, FullTargetBuilder<States>[Key]>;
     };
     type BranchTargetSelector<States extends StateSchemas, Source extends StateNodeIdentifier<States>, Root extends string = Source extends `${infer Head}.${string}` ? Head : Source> = Root extends ActiveStateKey<States> ? Root extends keyof BranchTargetBuilder<States, Source> ? {
-        readonly [Key in Root]: SelectionNode<States, States[Key], Key, "branch", BranchTargetBuilder<States, Source>[Key]>;
+        readonly [Key in Root]: SelectionNode<States, States[Key], Key, "branch", BranchTargetBuilder<States, Source>[Key]> & (Source extends ChoiceIdentifier<States> ? {} : Source extends `${Key}.${infer Rest}` ? BranchUpdateSelectionPath<States, States[Key], Key, Rest> : StateUpdateSelectionForNode<States, States[Key], Key, "branch">);
     } : {} : {};
-    type LocalTargetSelector<States extends StateSchemas, Source extends StateNodeIdentifier<States>> = NearestCompoundScope<States, Source> extends infer Scope extends StateIdentifier<States> ? ChildrenOf<States, Scope> extends infer Children extends StateSchemas ? LocalTargetBuilder<States, Source> extends infer Builder ? SelectionTreeWithPrefix<States, Children, Scope, "local", Builder> & ("with" extends keyof Builder ? {
-        readonly with: SelectionValue<Builder["with"], Scope>;
-    } : {}) : {} : {} : {};
+    type LocalTargetSelector<States extends StateSchemas, Source extends StateNodeIdentifier<States>> = NearestCompoundScope<States, Source> extends infer Scope ? [Scope] extends [never] ? {} : Scope extends StateIdentifier<States> ? ChildrenOf<States, Scope> extends infer Children extends StateSchemas ? LocalTargetBuilder<States, Source> extends infer Builder ? SelectionTreeWithPrefix<States, Children, Scope, "local", Builder> & ("with" extends keyof Builder ? {
+        readonly with: SelectionValue<Builder["with"], Scope, "state", "local">;
+    } : {}) & (Source extends ChoiceIdentifier<States> ? {} : Scope extends ValuedStateIdentifier<States> ? {
+        readonly update: SelectionValue<StateUpdateBuilder<States, Scope>, Scope, "update", "local">;
+    } : {}) : {} : {} : {} : {};
     type HistorySelectionTree<AllStates extends StateSchemas, States extends StateSchemas, Prefix extends string, Builder> = {
-        readonly [Key in Extract<HistoryContainingKey<States>, keyof Builder>]: States[Key] extends HistoryStateNodeConfig ? SelectionValue<Builder[Key], JoinPath<Prefix, Key>, "history"> : States[Key] extends {
+        readonly [Key in Extract<HistoryContainingKey<States>, keyof Builder>]: States[Key] extends HistoryStateNodeConfig ? SelectionValue<Builder[Key], JoinPath<Prefix, Key>, "history", "full"> : States[Key] extends {
             readonly states: infer Children extends StateSchemas;
         } ? HistorySelectionTree<AllStates, Children, JoinPath<Prefix, Key>, Builder[Key]> : never;
     };
@@ -3073,10 +3137,10 @@ export declare namespace Machine {
      */
     interface TargetSelector<States extends StateSchemas, Source extends StateNodeIdentifier<States>> {
         /** Handles the trigger without selecting a destination. */
-        readonly none: SelectionValue<TargetBuilder<States, Source>["none"], never, "none">;
-        /** Selects a destination inside the nearest active compound scope. */
+        readonly none: SelectionValue<TargetBuilder<States, Source>["none"], never, "none", "local">;
+        /** Selects a destination or updates the nearest active compound scope. */
         readonly local: LocalTargetSelector<States, Source>;
-        /** Selects a destination elsewhere under the currently active root. */
+        /** Selects a destination or updates a valued active ancestor under the current root. */
         readonly branch: BranchTargetSelector<States, Source>;
         /** Selects a complete destination under any top-level state. */
         readonly full: FullTargetSelector<States>;
@@ -3088,8 +3152,8 @@ export declare namespace Machine {
         readonly [Key in Extract<ActiveStateKey<States>, keyof InitialBuilder<States>>]: States[Key] extends {
             readonly states: StateSchemas;
         } ? {
-            readonly initial: SelectionValue<InitialBuilder<States>[Key], Key, "initial">;
-        } : SelectionMethod<InitialBuilder<States>[Key], Key>;
+            readonly initial: SelectionValue<InitialBuilder<States>[Key], Key, "initial", "initial">;
+        } : SelectionMethod<InitialBuilder<States>[Key], Key, "state", "initial">;
     };
     /**
      * Context passed to a state/event handler.
@@ -3365,14 +3429,14 @@ export declare namespace Machine {
      * **Details**
      *
      * Handlers return snapshots for complete state replacement, target builder
-     * results for path-safe partial transitions, or `target.none()` for an
-     * explicitly targetless transition. Raw decoded state values and `void` are
-     * not accepted at transition boundaries.
+     * results for path-safe partial transitions, state-value updates, or
+     * `target.none()` for an explicitly targetless transition. Raw decoded state
+     * values and `void` are not accepted at transition boundaries.
      *
      * @category utility types
      * @since 0.4.0
      */
-    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>>> | NoTarget;
+    type HandlerResult<States extends StateSchemas, E, R> = Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>> | ChoiceTarget<States, ChoiceIdentifier<States>> | StateUpdate<States, ValuedStateIdentifier<States>> | CombinedTarget<Target<States, StateIdentifier<States>> | Snapshot<States>, States, ValuedStateIdentifier<States>> | StateConstruction<Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>> | ChoiceTarget<States, ChoiceIdentifier<States>> | StateUpdate<States, ValuedStateIdentifier<States>>> | NoTarget;
     /** 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>>>;
     /**
@@ -3613,19 +3677,59 @@ export declare namespace Machine {
     }
     /** The only transition value accepted by machine handler APIs. */
     type TransitionConfig<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean = false, Acceptance extends TransitionAcceptance = "required"> = TransitionBuilderInput<States, Events, Emits, StateId, Context, Reenter, Acceptance>;
-    type SelectionBuilder<Selection> = Selection extends TargetSelection<infer Builder, any, any> ? Builder : never;
-    type SelectionKind<Selection> = Selection extends TargetSelection<any, any, infer Kind> ? Kind : never;
-    type SelectionPath<Selection> = Selection extends TargetSelection<any, infer Path, any> ? Path : never;
+    type SelectionBuilder<Selection> = Selection extends TargetSelection<infer Builder, any, any, any> ? Builder : never;
+    type SelectionKind<Selection> = Selection extends TargetSelection<any, any, infer Kind, any> ? Kind : never;
+    type SelectionPath<Selection> = Selection extends TargetSelection<any, infer Path, any, any> ? Path : never;
+    type SelectionScope<Selection> = Selection extends TargetSelection<any, any, any, infer Scope> ? Scope : never;
     type TargetBuilderResult<Builder> = (Builder extends (...args: any) => infer Result ? Result : never) | (Builder extends {
+        readonly decoded: (...args: any) => infer Result;
+    } ? Result : never) | (Builder extends {
         readonly from: (...args: any) => infer Result;
     } ? Result : never);
     type SelectedTargetResult<Selection> = SelectionBuilder<Selection> extends infer Builder ? TargetBuilderResult<Builder> : never;
+    type RetainedUpdateOwner<States extends StateSchemas, Source extends StateNodeIdentifier<States>, Selection> = Extract<ParentStateIdentifier<Source>, ParentStateIdentifier<Extract<SelectionPath<Selection>, string>> & ValuedStateIdentifier<States>>;
+    type RetainedOwnerSelector<Owner extends string> = () => TargetSelection<any, Owner, "state", "branch">;
+    /**
+     * Destination construction returned when a transition declares one retained
+     * valued owner with `.updating(...)`.
+     *
+     * @category models
+     * @since 0.22.0
+     */
+    interface UpdatingStateConstruction<Result, States extends StateSchemas, Owner extends ValuedStateIdentifier<States>> {
+        /** Combines the selected topology with the required owner replacement. */
+        readonly update: (update: StateUpdate<States, Owner>) => CombinedTarget<UnwrapConstruction<Result>, States, Owner>;
+    }
+    type UpdatingCallable<Callable, States extends StateSchemas, Owner extends ValuedStateIdentifier<States>> = Callable extends {
+        (...args: infer Arguments1): infer Result1;
+        (...args: infer Arguments2): infer Result2;
+    } ? {
+        (...args: Arguments1): UpdatingStateConstruction<Result1, States, Owner>;
+        (...args: Arguments2): UpdatingStateConstruction<Result2, States, Owner>;
+    } : Callable extends (...args: infer Arguments) => infer Result ? (...args: Arguments) => UpdatingStateConstruction<Result, States, Owner> : never;
+    type UpdatingTargetBuilder<Builder, States extends StateSchemas, Owner extends ValuedStateIdentifier<States>> = {
+        readonly [Key in keyof Builder]: Key extends "from" | "decoded" ? UpdatingCallable<Builder[Key], States, Owner> : Builder[Key];
+    };
     type SelectionSupportsDefaultConstruction<Selection> = SelectionKind<Selection> extends "none" ? true : SelectionBuilder<Selection> extends {
         readonly from: (...args: infer Args) => any;
-    } ? [] extends Args ? true : false : SelectionBuilder<Selection> extends (...args: infer Args) => any ? [] extends Args ? true : false : false;
+    } ? [] extends Args ? true : false : false;
     type TransitionResolveContext<Context, Selection> = Omit<Context, "target"> & (SelectionKind<Selection> extends "none" ? {} : {
         readonly target: SelectionBuilder<Selection>;
     });
+    type StateUpdateResolveContext<States extends StateSchemas, Context, Owner extends ValuedStateIdentifier<States>> = Omit<Context, "target"> & {
+        /** Decoded owner value from the pre-transition snapshot. */
+        readonly current: StateByIdentifier<States, Owner>;
+        /** Constructs the complete replacement for the selected owner. */
+        readonly owner: StateUpdateBuilder<States, Owner>;
+    };
+    type UpdatingTransitionResolveContext<States extends StateSchemas, Context, Selection, Owner extends ValuedStateIdentifier<States>> = Omit<Context, "target"> & {
+        /** Decoded owner value from the pre-transition snapshot. */
+        readonly current: StateByIdentifier<States, Owner>;
+        /** Constructs the selected topology and requires `.update(...)`. */
+        readonly target: UpdatingTargetBuilder<SelectionBuilder<Selection>, States, Owner>;
+        /** Constructs the complete replacement for the retained owner. */
+        readonly owner: StateUpdateBuilder<States, Owner>;
+    };
     /** Context capability available only to explicitly declinable resolvers. */
     interface DeclineCapability {
         /** Declines this candidate and continues hierarchical transition selection. */
@@ -3633,6 +3737,10 @@ export declare namespace Machine {
     }
     type TransitionResolver<Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Context, Selection> = (context: TransitionResolveContext<Context, Selection>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined;
     type DeclinableTransitionResolver<Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Context, Selection> = (context: TransitionResolveContext<Context, Selection> & DeclineCapability, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => (SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined) | Declined;
+    /** @internal */
+    type StateUpdateResolver<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Context, Owner extends ValuedStateIdentifier<States>> = (context: StateUpdateResolveContext<States, Context, Owner>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => StateUpdate<States, Owner>;
+    /** @internal */
+    type DeclinableStateUpdateResolver<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Context, Owner extends ValuedStateIdentifier<States>> = (context: StateUpdateResolveContext<States, Context, Owner> & DeclineCapability, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => StateUpdate<States, Owner> | Declined;
     /** One named destination declared by a branching transition. */
     interface TransitionBranchInput<Selection extends TargetSelection<any, any, any> = TargetSelection<any, any, any>> {
         /** Exact topology destination available to the branching resolver. */
@@ -3716,15 +3824,33 @@ export declare namespace Machine {
      * @inlineType TransitionReenterOption
      */
     type TransitionTarget<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean, Acceptance extends TransitionAcceptance, Selection extends TargetSelection<any, any, any>> = Selection & (SelectionSupportsDefaultConstruction<Selection> extends true ? BuiltTransition<States, Events, Emits, StateId, Context, Reenter, SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined, "required"> : {}) & {
-        /**
-         * Evaluates state construction and queued commands only after this
-         * transition has been selected.
-         */
+        /** Evaluates state construction after this transition is selected. */
         readonly resolve: TransitionResolveRequired<States, Events, Emits, StateId, Context, Reenter, Selection> & ("declinable" extends Acceptance ? TransitionResolveDeclinable<States, Events, Emits, StateId, Context, Reenter, Selection> : {});
     } & ([Reenter] extends [true] ? SelectionSupportsDefaultConstruction<Selection> extends true ? {
         /** Reenters the source using the selected target's default construction. */
         readonly reenter: () => BuiltTransition<States, Events, Emits, StateId, Context, Reenter, SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined, "required">;
-    } : {} : {});
+    } : {} : {}) & (SelectionKind<Selection> extends "state" ? SelectionScope<Selection> extends "local" | "branch" ? RetainedUpdateOwner<States, StateId, Selection> extends infer Owner extends ValuedStateIdentifier<States> ? [
+        Owner
+    ] extends [never] ? {} : {
+        /** Declares one valued owner retained by the selected topology. */
+        readonly updating: <SelectedOwner extends Owner>(owner: RetainedOwnerSelector<SelectedOwner>) => UpdatingTransitionTarget<States, Events, Emits, StateId, Context, Reenter, Acceptance, Selection, SelectedOwner>;
+    } : {} : {} : {});
+    /** A topology selection that requires one retained owner replacement. */
+    type UpdatingTransitionTarget<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean, Acceptance extends TransitionAcceptance, Selection extends TargetSelection<any, any, "state">, Owner extends ValuedStateIdentifier<States>> = Selection & {
+        /** @internal */
+        readonly "~effect/Machine/UpdatingTransitionTarget": Owner;
+        readonly resolve: ((resolve: (context: UpdatingTransitionResolveContext<States, Context, Selection, Owner>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => CombinedTarget<UnwrapConstruction<SelectedTargetResult<Selection>>, States, Owner>, options?: TransitionRequiredOptions<Reenter>) => BuiltTransition<States, Events, Emits, StateId, Context, Reenter, CombinedTarget<UnwrapConstruction<SelectedTargetResult<Selection>>, States, Owner>, "required">) & ("declinable" extends Acceptance ? (resolve: (context: UpdatingTransitionResolveContext<States, Context, Selection, Owner> & DeclineCapability, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => CombinedTarget<UnwrapConstruction<SelectedTargetResult<Selection>>, States, Owner> | Declined, options: TransitionDeclinableOptions<Reenter>) => BuiltTransition<States, Events, Emits, StateId, Context, Reenter, CombinedTarget<UnwrapConstruction<SelectedTargetResult<Selection>>, States, Owner> | Declined, "declinable"> : {});
+    };
+    /** @internal */
+    interface StateUpdateTransitionRequired<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean, Selection extends TargetSelection<any, any, "update">> {
+        (resolve: StateUpdateResolver<States, Events, Emits, Context, Extract<SelectionPath<Selection>, ValuedStateIdentifier<States>>>, options?: TransitionRequiredOptions<Reenter>): BuiltTransition<States, Events, Emits, StateId, Context, Reenter, SelectedTargetResult<Selection>, "required">;
+    }
+    /** @internal */
+    interface StateUpdateTransitionDeclinable<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean, Selection extends TargetSelection<any, any, "update">> {
+        (resolve: DeclinableStateUpdateResolver<States, Events, Emits, Context, Extract<SelectionPath<Selection>, ValuedStateIdentifier<States>>>, options: TransitionDeclinableOptions<Reenter>): BuiltTransition<States, Events, Emits, StateId, Context, Reenter, SelectedTargetResult<Selection> | Declined, "declinable">;
+    }
+    /** @internal */
+    type StateUpdateTransition<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean, Acceptance extends TransitionAcceptance, Selection extends TargetSelection<any, any, "update">> = Selection & StateUpdateTransitionRequired<States, Events, Emits, StateId, Context, Reenter, Selection> & ("declinable" extends Acceptance ? StateUpdateTransitionDeclinable<States, Events, Emits, StateId, Context, Reenter, Selection> : {});
     /** @internal Type evidence retained by a machine initial-entry declaration. */
     interface InitialBuilderEvidence<out Selection> {
         readonly [InitialBuilderTypeId]: Types.Covariant<Selection>;
@@ -3748,7 +3874,7 @@ export declare namespace Machine {
     type InitialSelector<States extends StateSchemas, Input = void> = InitialSelectorNode<Input, InitialTargetSelector<States>>;
     /** Target-first initial-entry declaration accepted by {@link make}. */
     type InitialBuilderInput<States extends StateSchemas, Input> = (to: InitialSelector<States, Input>) => InitialBuilderEvidence<TargetSelection<any, any, any>>;
-    type TransitionSelectorNode<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean, Acceptance extends TransitionAcceptance, Node> = Node extends (...args: infer Args) => infer Selection ? Selection extends TargetSelection<any, any, any> ? ((...args: Args) => TransitionTarget<States, Events, Emits, StateId, Context, Reenter, Acceptance, Selection>) & {
+    type TransitionSelectorNode<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean, Acceptance extends TransitionAcceptance, Node> = Node extends TargetSelection<any, any, "update"> ? StateUpdateTransition<States, Events, Emits, StateId, Context, Reenter, Acceptance, Node> : Node extends (...args: infer Args) => infer Selection ? Selection extends TargetSelection<any, any, any> ? ((...args: Args) => TransitionTarget<States, Events, Emits, StateId, Context, Reenter, Acceptance, Selection>) & {
         readonly [Key in keyof Node]: TransitionSelectorNode<States, Events, Emits, StateId, Context, Reenter, Acceptance, Node[Key]>;
     } : never : Node extends TargetSelection<any, any, any> ? TransitionTarget<States, Events, Emits, StateId, Context, Reenter, Acceptance, Node> : {
         readonly [Key in keyof Node]: TransitionSelectorNode<States, Events, Emits, StateId, Context, Reenter, Acceptance, Node[Key]>;
@@ -4580,13 +4706,13 @@ interface Make {
  * const counter = Machine.make({
  *   states: States.states,
  *   events: Events,
- *   initial: (to) => to.Count().resolve(({ target }) => target(new Count({ value: 0 })))
+ *   initial: (to) => to.Count().resolve(({ target }) => target.decoded(new Count({ value: 0 })))
  * }).handle({
  *   Count: {
  *     on: {
  *       Increment: (to) =>
  *         to.full.Count().resolve(({ event, state, target }) =>
- *           target(new Count({ value: state.value + event.by })))
+ *           target.decoded(new Count({ value: state.value + event.by })))
  *     }
  *   }
  * })
@@ -4810,7 +4936,16 @@ type TransitionBranchRecordError<Message extends string, Key extends PropertyKey
     readonly key: Key;
 };
 type InvalidStaticTransitionBranchKey<Branches> = Extract<keyof Branches, "" | number | symbol>;
-type ValidateTransitionBranchRecord<Branches> = [keyof Branches] extends [never] ? TransitionBranchRecordError<"Branch records must contain at least one branch"> : [InvalidStaticTransitionBranchKey<Branches>] extends [never] ? unknown : TransitionBranchRecordError<"Branch keys must be non-empty, non-index strings", InvalidStaticTransitionBranchKey<Branches>>;
+type InvalidUpdatingTransitionBranchKey<Branches> = {
+    readonly [Key in keyof Branches]: Branches[Key] extends {
+        readonly target: {
+            readonly "~effect/Machine/UpdatingTransitionTarget": string;
+        };
+    } ? Key : never;
+}[keyof Branches];
+type ValidateTransitionBranchRecord<Branches> = [keyof Branches] extends [never] ? TransitionBranchRecordError<"Branch records must contain at least one branch"> : [InvalidStaticTransitionBranchKey<Branches>] extends [never] ? [
+    InvalidUpdatingTransitionBranchKey<Branches>
+] extends [never] ? unknown : TransitionBranchRecordError<"Updating targets require a direct resolver", InvalidUpdatingTransitionBranchKey<Branches>> : TransitionBranchRecordError<"Branch keys must be non-empty, non-index strings", InvalidStaticTransitionBranchKey<Branches>>;
 /**
  * Plans the initial state for a machine without executing machine commands.
  *
@@ -4908,9 +5043,10 @@ export declare const initialDefinition: <M extends Machine.Any>(machine: M) => M
  *
  * Event handlers retain their handler-key order within each source state and
  * are followed by eventless and completion handlers. This function does not
- * execute resolvers. Every direct, named, and targetless branch exposes the
- * destination selected by its required static `target` declaration, while
- * `acceptance` reports whether the resolver may decline the transition.
+ * execute resolvers. Every branch exposes its static selection. State updates
+ * retain the updated owner in `selection.path` while leaving `target`
+ * undefined because they do not change topology. `acceptance` reports whether
+ * the resolver may decline the transition.
  *
  * @category getters
  * @since 0.4.0