@typeonce/effect-machine 0.19.1 → 0.20.0

package/docs/agent-guide.md

@@ -315,6 +315,37 @@ machine.
 Do not start a promise inside a transition callback. A transition has no
 lifetime in which to own that work. A state does.
 
+### Choose state-owned or process-owned children
+
+Use `from.child(...)` when the child belongs to one state and must stop when
+that state exits. Use a child family and `children.spawn(...)` when runtime
+events determine the ids or cardinality and the children must survive owner
+state changes:
+
+```ts
+const Worker = Machine.childFamily(workerMachine)
+
+Commissioning: {
+  invoke: (from) =>
+    from.effect("start-workers", ({ children, state }) =>
+      Effect.forEach(
+        state.workers,
+        (input) => children.spawn(Worker(input.id), { input }),
+        { discard: true }
+      )
+    )
+    .onDone((to) => to.full.Running())
+    .onFailure((to) => to.full.Failed())
+}
+```
+
+The Effect owns the startup attempt. The machine process owns every child that
+starts successfully. Leaving `Commissioning` does not stop those children.
+Stop one with `children.stop(Worker(id))` inside an Effect or
+`enqueue.stop(Worker(id))` inside a transition. A duplicate active id fails
+instead of replacing the existing child, and a partially successful group is
+not rolled back automatically.
+
 ## Keep transition decisions synchronous
 
 A transition should choose the next state from the current snapshot and event.

package/docs/effect-atom-react.md

@@ -200,3 +200,31 @@ the inferred dialog events.
 
 Use `dialogId` in atom labels for diagnostics. Do not pass it into
 `dialogMachine` as unused fake input.
+
+## 4. Selecting process-owned child machines
+
+Bind a machine definition once when a parent owns a runtime-sized set of child
+machines:
+
+```ts
+const Plant = Machine.childFamily(plantMachine)
+
+export const centralMachineAtom = machineAtoms.make(centralMachine)
+
+export const plantScopeFamily = Atom.family((plantId: string) => {
+  const plant = centralMachineAtom.child(Plant(plantId))
+
+  return {
+    stateAtom: plant.state,
+    isBrokenAtom: AtomMachine.matchesChild(plant, "Broken"),
+    sendAtom: plant.send,
+    stopAtom: plant.stop
+  }
+})
+```
+
+`Plant(plantId)` may be reconstructed wherever the id is available. Child
+lookup and bridge reuse match by machine identity and id, not descriptor object
+identity. Before the parent spawns that child, selectors contain `Option.none`
+and `matchesChild` is `false`. They follow the child after startup and return to
+the inactive values after it stops.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeonce/effect-machine",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Schema-first state machines and statecharts for Effect",
   "author": "Sandro Maglione",
   "repository": {

package/src/Machine.ts

@@ -2265,7 +2265,15 @@ export declare namespace Logic {
    * @category models
    * @since 0.4.0
    */
-  export interface Spawn {
+  export 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<
@@ -2305,7 +2313,7 @@ export declare namespace Logic {
     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: {
@@ -2345,6 +2353,7 @@ export declare namespace Logic {
 
 const ChildAddressTypeId = "~effect/Machine/ChildAddress"
 const ChildAddressCompatibilityErrorTypeId = "~effect/Machine/ChildAddressCompatibilityError"
+const ChildParentCompatibilityErrorTypeId = "~effect/Machine/ChildParentCompatibilityError"
 const ChildMachineTypeId = "~effect/Machine/ChildMachine"
 type InvokeLifecycleId = string & { readonly [ChildAddressTypeId]?: never }
 
@@ -2389,6 +2398,95 @@ export declare namespace ChildMachine {
    */
   export 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
+   */
+  export 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
+   */
+  export 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
+   */
+  export 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
+   */
+  export 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
+   */
+  export 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
+   */
+  export 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.
    *
@@ -2418,6 +2516,34 @@ export declare namespace ChildMachine {
     : 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.
  *
@@ -4799,6 +4925,8 @@ export declare namespace Machine {
     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. */
@@ -8917,6 +9045,17 @@ export const logic: <
 export const child: <const Id extends string, M extends Machine.Any>(id: Id, machine: M) => ChildMachine<Id, M> =
   internal.child
 
+/**
+ * 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 const childFamily: <M extends Machine.Any>(machine: M) => ChildMachine.Family<M> = internal.childFamily
+
 /**
  * Creates a typed parent-local address for lower-level child process logic.
  *

package/src/internal/machine/atom.ts

@@ -342,15 +342,7 @@ const makeChildFromRefAtom = <Child extends Machine.ChildMachine.Any, StartError
     }
   )
 
-  const childFamily = Atom.family((nested: Machine.ChildMachine.Any) =>
-    makeChildFromRefAtom(
-      makeChildRefAtom(ref as any, nested),
-      nested
-    )
-  )
-  const child = <Nested extends Machine.ChildMachine.Any>(
-    nested: Nested
-  ): ChildMachineAtom<Nested, StartError> => childFamily(nested) as ChildMachineAtom<Nested, StartError>
+  const child = makeChildSelector<StartError>(ref as any)
 
   return {
     ref,
@@ -363,6 +355,30 @@ const makeChildFromRefAtom = <Child extends Machine.ChildMachine.Any, StartError
   }
 }
 
+const makeChildSelector = <StartError>(
+  parentRef: Atom.Atom<
+    AsyncResult.AsyncResult<Option.Option<Machine.MachineRef<any, any, any, any, any>>, StartError>
+  >
+) => {
+  const byMachine = new WeakMap<object, (id: string) => ChildMachineAtom<Machine.ChildMachine.Any, StartError>>()
+  return <Child extends Machine.ChildMachine.Any>(descriptor: Child): ChildMachineAtom<Child, StartError> => {
+    let family = byMachine.get(descriptor.machine)
+    if (family === undefined) {
+      const machine = descriptor.machine
+      const atoms = Atom.family((id: string) => {
+        const child = internalMachine.child(id, machine)
+        return makeChildFromRefAtom(
+          makeChildRefAtom(parentRef as any, child),
+          child
+        )
+      })
+      family = (id) => atoms(id) as ChildMachineAtom<Machine.ChildMachine.Any, StartError>
+      byMachine.set(machine, family)
+    }
+    return family(descriptor.id) as ChildMachineAtom<Child, StartError>
+  }
+}
+
 const makeFromRefAtom = <State, Event, Error, Output, StartError, Emitted>(
   ref: Atom.Atom<AsyncResult.AsyncResult<Machine.MachineRef<State, Event, Error, Output, Emitted>, StartError>>
 ): MachineAtom<State, Event, Error, Output, StartError, Emitted> => {
@@ -438,15 +454,7 @@ const makeFromRefAtom = <State, Event, Error, Output, StartError, Emitted>(
   )
 
   const optionalRef = Atom.mapResult(ref, Option.some)
-  const childFamily = Atom.family((descriptor: Machine.ChildMachine.Any) =>
-    makeChildFromRefAtom(
-      makeChildRefAtom(optionalRef as any, descriptor),
-      descriptor
-    )
-  )
-  const child = <Child extends Machine.ChildMachine.Any>(
-    descriptor: Child
-  ): ChildMachineAtom<Child, StartError> => childFamily(descriptor) as ChildMachineAtom<Child, StartError>
+  const child = makeChildSelector<StartError>(optionalRef as any)
 
   return {
     ref,

package/src/internal/machine/invocation.ts

@@ -7,7 +7,7 @@
 import * as Cause from "effect/Cause"
 import * as Effect from "effect/Effect"
 import * as Stream from "effect/Stream"
-import type { ChildMachine, Inspection, Logic, Machine } from "../../Machine.js"
+import type { ChildMachine, ChildOwner, Inspection, Logic, Machine } from "../../Machine.js"
 import * as Configuration from "./configuration.js"
 import { InfiniteTransitionError, MachineSchemaDecodeError, StoppedError } from "./errors.js"
 import * as InvocationEvent from "./invocationEvent.js"
@@ -63,6 +63,16 @@ const streamLogic = (
 const resolveValue = (value: unknown, context: Machine.InvokeContext<any, any, any, any>): unknown =>
   typeof value === "function" ? value(context) : value
 
+const makeChildOwner = (scope: Runtime.ProcessScope<any>): ChildOwner<any> => ({
+  spawn:
+    ((descriptor: ChildMachine.Any, options?: { readonly input?: unknown }) =>
+      (scope.spawn as any)(descriptor, options)) as ChildOwner<any>["spawn"],
+  sendTo: ((descriptor: ChildMachine.Any, event: unknown) => scope.sendTo(descriptor, event)) as ChildOwner<
+    any
+  >["sendTo"],
+  stop: ((descriptor: ChildMachine.Any) => scope.stopChild(descriptor)) as ChildOwner<any>["stop"]
+})
+
 const resolveOne = (
   raw: Record<PropertyKey, any>,
   context: Machine.InvokeContext<any, any, any, any>,
@@ -291,11 +301,13 @@ export const startAll = (
   paths: ReadonlyArray<string>,
   event: Machine.LifecycleEvent<any>
 ): Effect.Effect<void, any, any> | undefined => {
+  const children = makeChildOwner(scope)
   const effects = Planner.sortEntryPaths(machine, paths)
     .filter((path) => configuration.active.has(path))
     .flatMap((path) => {
       const context = {
         ...(Configuration.getMachineReferences(configuration) ?? { self: scope.self, parent: scope.parent }),
+        children,
         state: configuration.values.get(path),
         containingState: Configuration.getParentValue(machine, configuration, path),
         ancestors: Configuration.getParentValues(machine, configuration, path),

package/src/internal/machine/machine.ts

@@ -2124,15 +2124,30 @@ export const transition = <State, Event, Error = never, Requirements = never>(
 export const child = <const Id extends string, M extends Machine.Any>(
   id: Id,
   machine: M
+): ChildMachine<Id, M> =>
+  makeChild(id, machine, (input) =>
+    machine.input === undefined
+      ? (internalProcess.toProcessLogic as any)(machine)
+      : (internalProcess.toProcessLogic as any)(machine, input))
+
+const makeChild = <const Id extends string, M extends Machine.Any>(
+  id: Id,
+  machine: M,
+  makeLogic: (input?: unknown) => Logic<any, any, any, any, any, any>
 ): ChildMachine<Id, M> => ({
   [ChildMachineTypeId]: ChildMachineTypeId,
   id,
   machine,
-  [ChildMachineLogicTypeId]: (input) =>
+  [ChildMachineLogicTypeId]: makeLogic
+})
+
+export const childFamily = <M extends Machine.Any>(machine: M): ChildMachine.Family<M> => {
+  const makeLogic = (input?: unknown): Logic<any, any, any, any, any, any> =>
     machine.input === undefined
       ? (internalProcess.toProcessLogic as any)(machine)
       : (internalProcess.toProcessLogic as any)(machine, input)
-})
+  return (id) => makeChild(id, machine, makeLogic)
+}
 
 export const childAddress = <Event = never>(id: string): ChildAddress<Event> => id as ChildAddress<Event>
 
@@ -2174,10 +2189,7 @@ export const spawn: {
     SpawnError<Options>,
     ChildInitialError
   >
-} = ((
-  logic: Logic<any, any, any, any, any, any>,
-  options?: SpawnOptions
-) =>
+} = ((logic: Logic<any, any, any, any, any, any>, options?: SpawnOptions) =>
   Effect.flatMap(
     internalRuntime.MachineRuntime,
     (runtime) => options === undefined ? runtime.spawn(logic) : (runtime.spawn as any)(logic, options)

package/src/internal/machine/runtime.ts

@@ -18,9 +18,10 @@ import * as Scope from "effect/Scope"
 import * as Stream from "effect/Stream"
 import * as SynchronizedRef from "effect/SynchronizedRef"
 import type * as Take from "effect/Take"
-import type { Inspection, Machine as MachineDefinition, MachineTarget } from "../../Machine.js"
+import type { ChildMachine, Inspection, Machine as MachineDefinition, MachineTarget } from "../../Machine.js"
 import { ChildAlreadyExistsError, StoppedError } from "./errors.js"
 import * as InspectionRuntime from "./inspectionRuntime.js"
+import { ChildMachineLogicTypeId } from "./symbols.js"
 
 type ChildDescriptor = {
   readonly id: string
@@ -376,7 +377,7 @@ const sendMachineTarget = (
 export interface ProcessScope<Event> {
   readonly self: ProcessAddress<Event>
   readonly parent: ProcessAddress<unknown> | undefined
-  readonly spawn: ProcessSpawn
+  readonly spawn: ProcessSpawn<Event>
   readonly sendParent: (event: unknown) => Effect.Effect<void, StoppedError>
   readonly emit: (event: unknown) => Effect.Effect<void>
   readonly sendTo: {
@@ -552,7 +553,15 @@ export interface ProcessLogic<
   run(context: ProcessContext<State, Event>): Effect.Effect<Output, Error, Requirements>
 }
 
-export interface ProcessSpawn {
+export interface ProcessSpawn<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: ProcessLogic<ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError>
   ): Effect.Effect<
@@ -1207,6 +1216,14 @@ const makeChildRuntimeSync = (
     })
   }
 
+  function spawn<const Child extends ChildMachine.Any>(
+    child: Child & ChildMachine.Executable<Child> & ChildMachine.ParentCompatibility<Child, unknown>,
+    ...options: ChildMachine.SpawnArgs<Child>
+  ): Effect.Effect<
+    ChildMachine.Ref<Child>,
+    ChildAlreadyExistsError | ChildMachine.StartError<Child>,
+    ChildMachine.StartRequirements<Child>
+  >
   function spawn<ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError = never>(
     logic: ProcessLogic<ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError>
   ): Effect.Effect<
@@ -1232,32 +1249,44 @@ const makeChildRuntimeSync = (
     ChildAlreadyExistsError | ChildInitialError,
     Exclude<ChildRequirements, Scope.Scope>
   >
-  function spawn<ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError = never>(
-    logic: ProcessLogic<ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError>,
-    spawnOptions?: {
+  function spawn(
+    logicOrChild: ProcessLogic<any, any, any, any, any, any> | ChildMachine.Any,
+    options?: {
       readonly id: string
       readonly descriptor?: ChildDescriptor
       readonly onOutcome?: (
-        outcome: RuntimeOutcome<ChildState, ChildError, ChildOutput>
+        outcome: RuntimeOutcome<any, any, any>
       ) => Effect.Effect<void>
       readonly [activeSnapshotObserver]?: (
-        snapshot: Extract<RuntimeSnapshot<ChildState, ChildError, ChildOutput>, { readonly status: "active" }>
+        snapshot: Extract<RuntimeSnapshot<any, any, any>, { readonly status: "active" }>
       ) => Effect.Effect<void>
       readonly [sendParentOverride]?: (event: unknown) => Effect.Effect<void, StoppedError>
-    }
-  ): Effect.Effect<
-    MachineRef<ChildState, ChildEvent, ChildError, ChildOutput>,
-    ChildAlreadyExistsError | ChildInitialError,
-    Exclude<ChildRequirements, Scope.Scope>
-  > {
+    } | { readonly input?: unknown }
+  ): Effect.Effect<MachineRef<any, any, any, any>, any, any> {
+    const descriptor = typeof logicOrChild === "object" && logicOrChild !== null &&
+        ChildMachineLogicTypeId in logicOrChild
+      ? logicOrChild as ChildMachine.Any
+      : undefined
+    const logic = descriptor === undefined
+      ? logicOrChild as ProcessLogic<any, any, any, any, any, any>
+      : descriptor[ChildMachineLogicTypeId](
+        (options as { readonly input?: unknown } | undefined)?.input
+      ) as unknown as ProcessLogic<any, any, any, any, any, any>
+    const spawnOptions = descriptor === undefined
+      ? options as {
+        readonly id: string
+        readonly descriptor?: ChildDescriptor
+        readonly onOutcome?: (outcome: RuntimeOutcome<any, any, any>) => Effect.Effect<void>
+        readonly [activeSnapshotObserver]?: (
+          snapshot: Extract<RuntimeSnapshot<any, any, any>, { readonly status: "active" }>
+        ) => Effect.Effect<void>
+        readonly [sendParentOverride]?: (event: unknown) => Effect.Effect<void, StoppedError>
+      } | undefined
+      : { id: descriptor.id, descriptor }
     const token = Symbol()
     const key = spawnOptions?.id ?? token
     let startedChild: MachineRef<any, any, any, any> | undefined
-    return Effect.suspend((): Effect.Effect<
-      MachineRef<ChildState, ChildEvent, ChildError, ChildOutput>,
-      ChildAlreadyExistsError | ChildInitialError,
-      Exclude<ChildRequirements, Scope.Scope>
-    > => {
+    return Effect.suspend(() => {
       if (registry.closed) {
         return Effect.interrupt
       }

package/src/unstable/reactivity/AtomMachine.ts

@@ -148,9 +148,9 @@ export interface MachineAtom<State, Event, Error = never, Output = never, StartE
   readonly stop: Atom.Writable<AsyncResult.AsyncResult<void, StartError | NotReadyError>, void>
 
   /**
-   * Creates a reactive bridge for a directly invoked child machine.
-   * Reusing the same descriptor returns the same live bridge while it remains
-   * referenced.
+   * Creates a reactive bridge for a directly owned child machine.
+   * Descriptors with the same id and machine definition return the same live
+   * bridge while it remains referenced.
    *
    * @since 0.4.0
    */
@@ -206,7 +206,8 @@ export const childEmissions: <Child extends Machine.ChildMachine.Any, StartError
 > = internal.childEmissions
 
 /**
- * Reactive access to one invoked child machine selected by its descriptor.
+ * Reactive access to one directly owned child machine selected by its
+ * descriptor.
  *
  * **Details**
  *
@@ -295,8 +296,9 @@ export interface ChildMachineAtom<Child extends Machine.ChildMachine.Any, StartE
     void
   >
   /**
-   * Creates a reactive bridge for a directly owned nested child. Reusing the
-   * same descriptor returns the same live bridge while it remains referenced.
+   * Creates a reactive bridge for a directly owned nested child. Descriptors
+   * with the same id and machine definition return the same live bridge while
+   * it remains referenced.
    *
    * @since 0.4.0
    */
@@ -418,7 +420,7 @@ export const selectSnapshot: <
 > = internal.selectSnapshot
 
 /**
- * Selects the typed value for an active state path in an invoked child.
+ * Selects the typed value for an active state path in a directly owned child.
  *
  * Valid paths and their selected value types are inferred from the child
  * bridge. An inactive child produces `Option.none()`. Keep the returned atom
@@ -513,7 +515,7 @@ export const matches: <
 ) => Atom.Atom<AsyncResult.AsyncResult<boolean, StartError | Error>> = internal.matches
 
 /**
- * Returns whether a state path is active in an invoked child.
+ * Returns whether a state path is active in a directly owned child.
  *
  * Valid paths are inferred from the child bridge snapshot.
  * An inactive child produces `false`. Keep the returned atom stable when