@typeonce/effect-machine 0.20.0 → 0.22.0

package/src/Machine.ts

@@ -286,7 +286,7 @@ export interface Definition<
    *     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 })))
    *     }
    *   }
    * })
@@ -972,6 +972,16 @@ 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
@@ -997,9 +1007,7 @@ type NodeBuilderMethod<
 > = Machine.NodeSchema<Node> extends never ? {
     readonly from: FromCallable<FromArguments, FromResult>
   }
-  :
-    & ((...args: Arguments) => Result)
-    & { readonly from: FromCallable<FromArguments, FromResult> }
+  : DecodedMethod<Arguments, Result> & { readonly from: FromCallable<FromArguments, FromResult> }
 
 type NodeMethod<
   Node,
@@ -1007,7 +1015,7 @@ type NodeMethod<
   Result,
   FromArguments extends ReadonlyArray<unknown>
 > = Machine.NodeSchema<Node> extends never ? FromMethod<FromArguments, Result>
-  : ((...args: Arguments) => Result) & FromMethod<FromArguments, Result>
+  : DecodedMethod<Arguments, Result> & FromMethod<FromArguments, Result>
 
 type NodeMethodWithInitial<
   Node,
@@ -1020,7 +1028,7 @@ type NodeMethodWithInitial<
     readonly initial: InitialTargetFactory<Node, Path>
   }
   :
-    & ((...args: Arguments) => Result)
+    & DecodedMethod<Arguments, Result>
     & {
       readonly from: FromCallable<FromArguments, Machine.StateConstruction<Result>>
       readonly initial: InitialTargetFactory<Node, Path>
@@ -1038,11 +1046,11 @@ 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 ? {
@@ -1056,15 +1064,14 @@ type NestedTargetMethod<Node, Builder, Result, Path extends string> = Machine.No
     readonly from: NodeConstructionSelectorFromCallable<Node, Builder, Result>
     readonly initial: InitialTargetFactory<Node, Path>
   }
-  :
-    & (<Selected extends ConstructionResult<Result>>(
+  : {
+    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>
-    }
+    ) => Selected
+    readonly from: NodeConstructionSelectorFromCallable<Node, Builder, Result>
+    readonly initial: InitialTargetFactory<Node, Path>
+  }
 
 type ConstructionSelectorFromCallable<Input, Builder, Result> = {} extends Input ? {
     <Selected extends ConstructionResult<Result>>(
@@ -1100,9 +1107,10 @@ type InitialSnapshotMethod<
     InitialSnapshotResult<States, StateId, Prefix>
   >
   :
-    & ((
-      ...args: InitialSnapshotArguments<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>
@@ -1242,9 +1250,10 @@ type FullSnapshotMethod<
     FullSnapshotResult<States, StateId, Prefix>
   >
   :
-    & ((
-      ...args: FullSnapshotArguments<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>
@@ -1416,9 +1425,10 @@ type HistorySnapshotMethod<
     HistorySnapshotResult<States, StateId, Prefix, Owner>
   >
   :
-    & ((
-      ...args: HistorySnapshotArguments<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>
@@ -1645,20 +1655,19 @@ type LocalTargetBuilderForScope<
          *
          * @since 0.4.0
          */
-        readonly with:
-          & (<Result extends ConstructionResult<LocalTargetResultWithPrefix<States, Children, Scope>>>(
+        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>
-            >
-          }
+          ) => Result
+          readonly from: ConstructionSelectorFromCallable<
+            Machine.SchemaByIdentifier<States, Scope>["~type.make.in"],
+            LocalTargetBuilderWithPrefix<States, Children, Scope, Source>,
+            LocalTargetResultWithPrefix<States, Children, Scope>
+          >
+        }
       } :
       {})
   : {}
@@ -3557,6 +3566,7 @@ export declare namespace Machine {
       readonly type: "direct"
       readonly target: Path | undefined
       readonly selection: TransitionTargetSelection<Path | undefined>
+      readonly updates: ReadonlyArray<string>
     }
     | {
       readonly type: "branch"
@@ -3564,6 +3574,7 @@ export declare namespace Machine {
       readonly title: string
       readonly target: Path | undefined
       readonly selection: TransitionTargetSelection<Path | undefined>
+      readonly updates: ReadonlyArray<string>
     }
 
   /** The statically selected root entry for machine startup. */
@@ -3577,9 +3588,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
@@ -3634,6 +3646,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>
   }
 
   /**
@@ -4461,6 +4475,54 @@ export declare namespace Machine {
     >
   }
 
+  /**
+   * Opaque instruction that replaces one active compound or parallel state's
+   * value without changing its active descendants.
+   *
+   * @category models
+   * @since 0.21.0
+   */
+  export 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
+   */
+  export 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.
    *
@@ -4692,23 +4754,36 @@ export declare namespace Machine {
   export interface TargetSelection<
     out Result,
     out Path extends string | undefined = string | undefined,
-    out Kind extends Topology.TargetSelectionKind = Topology.TargetSelectionKind
+    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 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"> = () =>
-    SelectionValue<Builder, Path, Kind>
+  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> = Builder extends { readonly initial: infer Initial } ? {
-      readonly initial: SelectionValue<Initial, Path, "initial">
+  type InitialSelectionMethod<
+    Builder,
+    Path extends string,
+    Scope extends Topology.TargetSelectionScope
+  > = Builder extends { readonly initial: infer Initial } ? {
+      readonly initial: SelectionValue<Initial, Path, "initial", Scope>
     }
     : {}
 
@@ -4737,13 +4812,62 @@ export declare namespace Machine {
   > = Node extends ChoiceStateNodeConfig ? SelectionMethod<
       Builder,
       Path,
-      "choice"
+      "choice",
+      Scope
     >
     : Node extends { readonly states: infer Children extends StateSchemas } ?
-        & SelectionMethod<Builder, Path>
-        & InitialSelectionMethod<Builder, Path>
+        & SelectionMethod<Builder, Path, "state", Scope>
+        & InitialSelectionMethod<Builder, Path, Scope>
         & SelectionTreeWithPrefix<AllStates, Children, Path, Scope, Builder>
-    : SelectionMethod<Builder, Path>
+    : 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,
@@ -4751,9 +4875,9 @@ export declare namespace Machine {
     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<
@@ -4769,13 +4893,17 @@ export declare namespace Machine {
     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">)
       }
     : {}
     : {}
@@ -4783,14 +4911,21 @@ export declare namespace Machine {
   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>
-            }
-            : {})
+  > = 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">
+                }
+              : {})
+        : {}
       : {}
     : {}
     : {}
@@ -4805,7 +4940,8 @@ export declare namespace Machine {
       SelectionValue<
         Builder[Key],
         JoinPath<Prefix, Key>,
-        "history"
+        "history",
+        "full"
       >
       : States[Key] extends { readonly states: infer Children extends StateSchemas } ? HistorySelectionTree<
           AllStates,
@@ -4830,10 +4966,10 @@ export declare namespace Machine {
     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>
@@ -4845,9 +4981,9 @@ export declare namespace Machine {
   type InitialTargetSelector<States extends StateSchemas> = {
     readonly [Key in Extract<ActiveStateKey<States>, keyof InitialBuilder<States>>]: States[Key] extends
       { readonly states: StateSchemas } ? {
-        readonly initial: SelectionValue<InitialBuilder<States>[Key], Key, "initial">
+        readonly initial: SelectionValue<InitialBuilder<States>[Key], Key, "initial", "initial">
       }
-      : SelectionMethod<InitialBuilder<States>[Key], Key>
+      : SelectionMethod<InitialBuilder<States>[Key], Key, "state", "initial">
   }
 
   /**
@@ -5243,9 +5379,9 @@ 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
@@ -5255,11 +5391,18 @@ export declare namespace Machine {
     | 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
 
@@ -5587,21 +5730,75 @@ export declare namespace Machine {
     Acceptance extends TransitionAcceptance = "required"
   > = TransitionBuilderInput<States, Events, Emits, StateId, Context, Reenter, Acceptance>
 
-  export type SelectionBuilder<Selection> = Selection extends TargetSelection<infer Builder, any, any> ? Builder : never
-  export type SelectionKind<Selection> = Selection extends TargetSelection<any, any, infer Kind> ? Kind : never
-  export type SelectionPath<Selection> = Selection extends TargetSelection<any, infer Path, any> ? Path : never
+  export type SelectionBuilder<Selection> = Selection extends TargetSelection<infer Builder, any, any, any> ? Builder
+    : never
+  export type SelectionKind<Selection> = Selection extends TargetSelection<any, any, infer Kind, any> ? Kind : never
+  export 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
   export 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)
   export 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
+   */
+  export 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
 
   export type TransitionResolveContext<
@@ -5611,6 +5808,31 @@ export declare namespace Machine {
     & 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. */
   export interface DeclineCapability {
     /** Declines this candidate and continues hierarchical transition selection. */
@@ -5639,6 +5861,30 @@ export declare namespace Machine {
     | (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. */
   export interface TransitionBranchInput<
     Selection extends TargetSelection<any, any, any> = TargetSelection<any, any, any>
@@ -5847,10 +6093,7 @@ export declare namespace Machine {
       >
       : {})
     & {
-      /**
-       * 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<
@@ -5879,6 +6122,165 @@ export declare namespace Machine {
         }
       : {}
       : {})
+    & (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. */
+  export 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. */
   export interface InitialBuilderEvidence<out Selection> {
@@ -5933,19 +6335,18 @@ export declare namespace Machine {
     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
-        >)
-        & {
-          readonly [Key in keyof Node]: TransitionSelectorNode<
+  > = 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,
@@ -5953,10 +6354,21 @@ export declare namespace Machine {
             Context,
             Reenter,
             Acceptance,
-            Node[Key]
-          >
-        }
-    : never
+            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,
@@ -8261,13 +8673,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 })))
  *     }
  *   }
  * })
@@ -8594,9 +9006,21 @@ type TransitionBranchRecordError<Message extends string, Key extends PropertyKey
 
 type InvalidStaticTransitionBranchKey<Branches> = Extract<keyof Branches, "" | number | symbol>
 
+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] ? unknown
+  : [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>
@@ -8760,9 +9184,10 @@ export const initialDefinition: <M extends Machine.Any>(machine: M) => Machine.I
  *
  * 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