@typeonce/effect-machine 0.21.0 → 0.23.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()))
 })
 ```
 
@@ -428,9 +438,9 @@ compound scope without rebuilding its active child. Use
 handler source:
 
 ```ts
-Increment: ;
-;((to) =>
-  to.branch.root.session.update(({ ancestors, target }) => target.from({ count: ancestors["root.session"].count + 1 })))
+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,
@@ -438,8 +448,8 @@ 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.
 
-`update` is callable when used directly and is also a static selection for a
-named branch:
+The plain update method remains useful when topology does not change. It is
+also a static selection for a named branch:
 
 ```ts
 to.branches({
@@ -452,10 +462,69 @@ to.branches({
 )
 ```
 
-The resolver must return `target(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.
+### 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

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> {
@@ -2282,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.
@@ -2850,12 +2865,30 @@ export declare namespace Machine {
      * @since 0.21.0
      */
     interface StateUpdate<States extends StateSchemas, StateId extends ValuedStateIdentifier<States>> {
-        readonly [Topology.StateUpdateTypeId]: typeof Topology.StateUpdateTypeId;
-        readonly path: StateId;
-        readonly value: StateByIdentifier<States, StateId>;
+        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>> = ((value: StateByIdentifier<States, StateId>) => StateUpdate<States, StateId>) & FromMethod<readonly [input: SchemaByIdentifier<States, StateId>["~type.make.in"]], StateUpdate<States, StateId>>;
+    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.
      *
@@ -3040,56 +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> = Node extends {
+    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">;
+        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> = StateUpdateSelectionForNode<AllStates, Node, Path> & (Node extends {
+    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>;
+        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>>;
+        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]> & (Source extends ChoiceIdentifier<States> ? {} : Source extends `${Key}.${infer Rest}` ? BranchUpdateSelectionPath<States, States[Key], Key, Rest> : StateUpdateSelectionForNode<States, States[Key], 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 ? [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>;
+        readonly with: SelectionValue<Builder["with"], Scope, "state", "local">;
     } : {}) & (Source extends ChoiceIdentifier<States> ? {} : Scope extends ValuedStateIdentifier<States> ? {
-        readonly update: SelectionValue<StateUpdateBuilder<States, Scope>, Scope, "update">;
+        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;
     };
@@ -3104,7 +3137,7 @@ 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">;
+        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 or updates a valued active ancestor under the current root. */
@@ -3119,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.
@@ -3403,7 +3436,7 @@ export declare namespace Machine {
      * @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>> | StateUpdate<States, ValuedStateIdentifier<States>> | StateConstruction<Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>> | ChoiceTarget<States, ChoiceIdentifier<States>> | StateUpdate<States, ValuedStateIdentifier<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>>>;
     /**
@@ -3644,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. */
@@ -3665,9 +3738,9 @@ 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<Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Context, Selection> = (context: TransitionResolveContext<Context, Selection>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => SelectedTargetResult<Selection>;
+    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<Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Context, Selection> = (context: TransitionResolveContext<Context, Selection> & DeclineCapability, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => SelectedTargetResult<Selection> | Declined;
+    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. */
@@ -3751,22 +3824,30 @@ 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<Events, Emits, Context, Selection>, options?: TransitionRequiredOptions<Reenter>): BuiltTransition<States, Events, Emits, StateId, Context, Reenter, SelectedTargetResult<Selection>, "required">;
+        (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<Events, Emits, Context, Selection>, options: TransitionDeclinableOptions<Reenter>): BuiltTransition<States, Events, Emits, StateId, Context, Reenter, SelectedTargetResult<Selection> | Declined, "declinable">;
+        (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> : {});
@@ -4625,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 })))
  *     }
  *   }
  * })
@@ -4855,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.
  *