@typeonce/effect-machine 0.19.1 → 0.21.0

package/README.md

@@ -420,6 +420,47 @@ 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
+Increment: ;
+;((to) =>
+  to.branch.root.session.update(({ ancestors, target }) => target.from({ count: ancestors["root.session"].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.
+
+`update` is callable when used directly and 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()
+)
+```
+
+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.
+
+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:
@@ -582,6 +623,46 @@ entered. Use an Effect containing `Effect.sleep(...)` for generic work, while
 `from.timer(...)` keeps timer intent explicit and makes static durations visible
 through activity inspection.
 
+### Spawn dynamic child machines
+
+Use `from.child(...)` when a state owns a fixed child lifecycle. Use the
+`children` context inside an invoked Effect when the machine process owns an
+open set of children that must survive state changes:
+
+```ts
+const Plant = Machine.childFamily(plantMachine)
+
+const central = Machine.make({
+  events: Machine.events(ResourcesOffered, PlantBroken)
+  // ...
+}).handle({
+  Commissioning: {
+    invoke: (from) =>
+      from.effect("commission-wave", ({ children, state }) =>
+        Effect.forEach(
+          state.plants,
+          (input) => children.spawn(Plant(input.id), { input }),
+          { discard: true }
+        ))
+        .onDone((to) => to.full.Operating())
+        .onFailure((to) => to.full.CommissioningFailed())
+  }
+})
+```
+
+`children.spawn` completes after initialization. The new child remains owned
+by the machine process after the commissioning Effect completes or its state
+exits. `children.sendTo` and `children.stop` address one active child from an
+Effect; transition resolvers use `enqueue.sendTo` and `enqueue.stop` with the
+same descriptor. Duplicate active ids fail with `ChildAlreadyExistsError` and
+do not replace the existing child. Earlier successful spawns remain active if
+a later spawn in the same wave fails.
+
+The child machine's declared `Machine.parent(...)` events must be accepted by
+the owner. This is checked at each spawn call even though ids and cardinality
+remain dynamic. `scope.spawn(child, { input })` provides the same descriptor
+form for lower-level process logic, where the process event protocol is known.
+
 ## Reactivity
 
 `AtomMachine` runs one lazy machine instance per `AtomRegistry`:
@@ -603,6 +684,15 @@ The bridge exposes `ref`, `snapshot`, `state`, fail-aware `result`, writable
 equality-aware derivations. React applications using `@effect/atom-react` need
 a `RegistryProvider`.
 
+Descriptors reconstructed from a `Machine.childFamily` resolve the same child
+bridge by machine identity and id:
+
+```ts
+const Plant = Machine.childFamily(plantMachine)
+const plantAtom = centralAtom.child(Plant(selectedPlantId))
+const brokenAtom = AtomMachine.matchesChild(plantAtom, "Broken")
+```
+
 Emissions stay streams rather than becoming retained atom state:
 
 ```ts
@@ -679,20 +769,6 @@ import { MachineTest } from "@typeonce/effect-machine/testing"
 
 Each ESM entrypoint is independent and tree-shakeable.
 
-## Examples
-
-Every package directly under [`examples/`](./examples) has its own lockfile and
-`check` script.
-
-| Example                             | What it demonstrates                                                                                                                                                                                          |
-| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Playground](./examples/playground) | Five focused React examples: atomic turnstile commands, state-scoped traffic-light timers, hierarchical microwave safety, a resource-owned media player, and a worker-hosted machine synchronized across tabs |
-| [Pokémon](./examples/pokemon)       | Compound workflow states, invoked child machines, typed emissions, Atom reactivity, and a live Effect service                                                                                                 |
-| [Platformer](./examples/platformer) | Nested parallel statecharts, typed deep history, raised events, state-scoped timers, deterministic model tests, and a playable SVG adapter                                                                    |
-
-The playground is the shortest path from one concept to working code. The
-standalone examples show larger composition and ownership boundaries.
-
 ## Reference and development
 
 - [API reference](https://effect-machine.typeonce.dev)

package/dist/Machine.d.ts

@@ -1258,7 +1258,8 @@ export declare namespace Logic {
      * @category models
      * @since 0.4.0
      */
-    interface Spawn {
+    interface Spawn<OwnerEvent = unknown> {
+        <const Child extends ChildMachine.Any>(child: Child & ChildMachine.Executable<Child> & ChildMachine.ParentCompatibility<Child, OwnerEvent>, ...options: ChildMachine.SpawnArgs<Child>): Effect.Effect<ChildMachine.Ref<Child>, ChildAlreadyExistsError | ChildMachine.StartError<Child>, ChildMachine.StartRequirements<Child>>;
         <ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError = never>(logic: Logic<ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError>): Effect.Effect<MachineRef<ChildState, ChildEvent, ChildError, ChildOutput>, ChildInitialError, Exclude<ChildRequirements, Scope.Scope>>;
         <ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, Options extends SpawnOptions, ChildInitialError = never>(logic: Logic<ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError>, options: Options & ChildAddress.OptionsCompatibility<Options, ChildEvent>): Effect.Effect<MachineRef<ChildState, ChildEvent, ChildError, ChildOutput>, SpawnIdError<Options> | ChildInitialError, Exclude<ChildRequirements, Scope.Scope>>;
     }
@@ -1274,7 +1275,7 @@ export declare namespace Logic {
         /** Address of the owning process, when one exists. */
         readonly parent: Address<unknown> | undefined;
         /** Starts a child process owned by this scope. */
-        readonly spawn: Spawn;
+        readonly spawn: Spawn<Event>;
         /** Sends an event to a machine target or typed parent-local child address. */
         readonly sendTo: {
             <TargetEvent>(target: MachineTarget<TargetEvent>, event: TargetEvent): Effect.Effect<void, StoppedError>;
@@ -1302,6 +1303,7 @@ export declare namespace Logic {
 }
 declare const ChildAddressTypeId = "~effect/Machine/ChildAddress";
 declare const ChildAddressCompatibilityErrorTypeId = "~effect/Machine/ChildAddressCompatibilityError";
+declare const ChildParentCompatibilityErrorTypeId = "~effect/Machine/ChildParentCompatibilityError";
 declare const ChildMachineTypeId = "~effect/Machine/ChildMachine";
 type InvokeLifecycleId = string & {
     readonly [ChildAddressTypeId]?: never;
@@ -1342,6 +1344,68 @@ export declare namespace ChildMachine {
      * @since 0.4.0
      */
     type Any = ChildMachine<string, Machine.Any>;
+    /**
+     * Bound constructor for an open family of child descriptors that share one
+     * machine definition.
+     *
+     * @category models
+     * @since 0.20.0
+     */
+    interface Family<M extends Machine.Any> {
+        <const Id extends string>(id: Id): ChildMachine<Id, M>;
+    }
+    /**
+     * Ensures a child machine's declared owner protocol is accepted by the
+     * process that will own it.
+     *
+     * @category utility types
+     * @since 0.20.0
+     */
+    type ParentCompatibility<Child extends Any, OwnerEvent> = Child extends ChildMachine<string, infer M> ? Machine.Any extends M ? {
+        readonly [ChildParentCompatibilityErrorTypeId]: {
+            readonly child: unknown;
+            readonly owner: OwnerEvent;
+        };
+    } : [Machine.EventOf<Machine.ParentEvents<M>>] extends [OwnerEvent] ? unknown : {
+        readonly [ChildParentCompatibilityErrorTypeId]: {
+            readonly child: Machine.EventOf<Machine.ParentEvents<M>>;
+            readonly owner: OwnerEvent;
+        };
+    } : never;
+    /**
+     * Ensures the selected child machine has complete handlers and outputs.
+     *
+     * @category utility types
+     * @since 0.20.0
+     */
+    type Executable<Child extends Any> = Child["machine"] extends EnsureExecutable<Machine.States<Child["machine"]>, Machine.UnhandledStates<Child["machine"]>, Machine.OutputStates<Child["machine"]>> ? unknown : never;
+    /**
+     * Startup arguments accepted while spawning a child machine.
+     *
+     * @category utility types
+     * @since 0.20.0
+     */
+    type SpawnArgs<Child extends Any> = Machine.InputSchema<Child["machine"]> extends typeof Schema.Void ? [
+        options?: {
+            readonly input?: never;
+        }
+    ] : [options: {
+        readonly input: Machine.Input<Child["machine"]>;
+    }];
+    /**
+     * Typed failures that may occur before a spawned child becomes active.
+     *
+     * @category utility types
+     * @since 0.20.0
+     */
+    type StartError<Child extends Any> = Child extends ChildMachine<string, infer M> ? Machine.InitialError<M> | Machine.Error<M> | ActionError<Machine.InitialServices<M> | Machine.Services<M>> | InfiniteTransitionError | MachineSchemaDecodeError | StartupError | StoppedError : never;
+    /**
+     * Services needed to initialize a spawned child machine.
+     *
+     * @category utility types
+     * @since 0.20.0
+     */
+    type StartRequirements<Child extends Any> = Child extends ChildMachine<string, infer M> ? Exclude<ExcludeCompatibleRuntime<Exclude<ExecutionServices<Machine.InitialServices<M> | Machine.Services<M>>, MachineRuntimeRequirement>, Machine.Event<M>, Machine.Emit<M>>, Scope.Scope> : never;
     /**
      * Running machine reference selected by a child descriptor.
      *
@@ -1357,6 +1421,21 @@ export declare namespace ChildMachine {
      */
     type Event<Child> = Child extends ChildMachine<string, infer M> ? Machine.EventInput<Machine.InputEvent<M>> : never;
 }
+/**
+ * Effectful operations for child machines owned directly by the current
+ * machine process.
+ *
+ * @category models
+ * @since 0.20.0
+ */
+export interface ChildOwner<OwnerEvent> {
+    /** Starts a process-owned child and returns once initialization succeeds. */
+    readonly spawn: <const Child extends ChildMachine.Any>(child: Child & ChildMachine.Executable<Child> & ChildMachine.ParentCompatibility<Child, OwnerEvent>, ...options: ChildMachine.SpawnArgs<Child>) => Effect.Effect<ChildMachine.Ref<Child>, ChildAlreadyExistsError | ChildMachine.StartError<Child>, ChildMachine.StartRequirements<Child>>;
+    /** Sends an event to one active child. Missing children are ignored. */
+    readonly sendTo: <Child extends ChildMachine.Any>(child: Child, event: ChildMachine.Event<Child>) => Effect.Effect<void, StoppedError>;
+    /** Stops one active child. Missing children are ignored. */
+    readonly stop: <Child extends ChildMachine.Any>(child: Child) => Effect.Effect<void>;
+}
 /**
  * Parent-local address for a child process that can receive events.
  *
@@ -2155,9 +2234,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
@@ -2762,6 +2842,20 @@ 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]: typeof Topology.StateUpdateTypeId;
+        readonly path: StateId;
+        readonly value: StateByIdentifier<States, StateId>;
+    }
+    /** @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>>;
     /**
      * Opaque result returned by an explicitly targetless transition.
      *
@@ -2966,6 +3060,20 @@ export declare namespace Machine {
     type SelectionNode<AllStates extends StateSchemas, Node, Path extends string, Scope extends "local" | "branch", Builder> = Node extends ChoiceStateNodeConfig ? SelectionMethod<Builder, Path, "choice"> : Node extends {
         readonly states: infer Children extends StateSchemas;
     } ? SelectionMethod<Builder, Path> & InitialSelectionMethod<Builder, Path> & SelectionTreeWithPrefix<AllStates, Children, Path, Scope, Builder> : SelectionMethod<Builder, Path>;
+    /** @internal */
+    type StateUpdateSelectionForNode<AllStates extends StateSchemas, Node, Path extends string> = Node extends {
+        readonly states: StateSchemas;
+    } ? NodeSchema<Node> extends never ? {} : {
+        readonly update: SelectionValue<StateUpdateBuilder<AllStates, Extract<Path, ValuedStateIdentifier<AllStates>>>, Path, "update">;
+    } : {};
+    /** @internal */
+    type BranchUpdateSelectionPath<AllStates extends StateSchemas, Node, Path extends string, Rest extends string> = StateUpdateSelectionForNode<AllStates, Node, Path> & (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>;
+    } : {} : Rest extends keyof Children ? {
+        readonly [Key in Rest]: StateUpdateSelectionForNode<AllStates, Children[Rest], JoinPath<Path, Rest>>;
+    } : {} : {});
     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>;
@@ -2973,11 +3081,13 @@ export declare namespace Machine {
         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>);
     } : {} : {};
-    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 ? {
+    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>;
-    } : {}) : {} : {} : {};
+    } : {}) & (Source extends ChoiceIdentifier<States> ? {} : Scope extends ValuedStateIdentifier<States> ? {
+        readonly update: SelectionValue<StateUpdateBuilder<States, Scope>, Scope, "update">;
+    } : {}) : {} : {} : {} : {};
     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 states: infer Children extends StateSchemas;
@@ -2995,9 +3105,9 @@ 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. */
+        /** 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>;
@@ -3060,6 +3170,8 @@ export declare namespace Machine {
      * @since 0.4.0
      */
     type InvokeContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, InputEvents extends ReadonlyArray<TaggedSchema> = Events, ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []> = MachineReferences<InputEvents, ParentEvents> & {
+        /** Process-owned child operations for dynamic child machine lifecycles. */
+        readonly children: ChildOwner<EventOf<InputEvents>>;
         /** Value owned by the state that owns this invocation. */
         readonly state: StateByIdentifier<States, StateId>;
         /** Value owned by the nearest schema-backed ancestor, when one exists. */
@@ -3284,14 +3396,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>> | 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>>>;
     /**
@@ -3552,6 +3664,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<Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Context, Selection> = (context: TransitionResolveContext<Context, Selection>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => SelectedTargetResult<Selection>;
+    /** @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;
     /** 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. */
@@ -3644,6 +3760,16 @@ export declare namespace Machine {
         /** Reenters the source using the selected target's default construction. */
         readonly reenter: () => BuiltTransition<States, Events, Emits, StateId, Context, Reenter, SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined, "required">;
     } : {} : {});
+    /** @internal */
+    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">;
+    }
+    /** @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">;
+    }
+    /** @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>;
@@ -3667,7 +3793,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]>;
@@ -4827,9 +4953,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
@@ -4989,6 +5116,16 @@ export declare const logic: <State, Event = never, Output = void, Error = never,
  * @since 0.4.0
  */
 export declare const child: <const Id extends string, M extends Machine.Any>(id: Id, machine: M) => ChildMachine<Id, M>;
+/**
+ * Binds one machine definition to an open family of runtime child ids.
+ *
+ * Descriptors created by the returned function are interchangeable with
+ * {@link child} descriptors for the same id and machine definition.
+ *
+ * @category constructors
+ * @since 0.20.0
+ */
+export declare const childFamily: <M extends Machine.Any>(machine: M) => ChildMachine.Family<M>;
 /**
  * Creates a typed parent-local address for lower-level child process logic.
  *