@typeonce/effect-machine 0.16.0 → 0.18.0

package/docs/agent-guide.md

@@ -38,8 +38,9 @@ declared:
 1. Domain schemas used by state, and by event fields when they are shared.
 2. `Machine.states`, using a tagged state union and `.cases` when state
    schemas need to be reused.
-3. `Machine.events`, `Machine.internalEvents`, `Machine.emittedEvents`, and
-   `parentEvents`; pass `Schema.TaggedUnion({...})` or tagged classes directly.
+3. `Machine.events`, `Machine.internalEvents`, `Machine.emittedEvents`, and any
+   protocol passed to `Machine.parent` or `Machine.optionalParent`; pass
+   `Schema.TaggedUnion({...})` or tagged classes directly.
 4. `Machine.make({...}).handle({...})`.
 5. Child descriptors, then runtime, Atom, or Cluster adapters.
 
@@ -109,8 +110,9 @@ the deferred constructors preserve that identity after decoding.
   lookup. Independently constructed descriptors are equivalent only when both
   their id and machine identity match.
 - `events` is the public machine-input protocol. `internalEvents` contains
-  machine-local raised events. `parentEvents` describes the public events a
-  child may send to its owner. `emittedEvents` describes outward ephemeral
+  machine-local raised events. `parent: Machine.parent(events)` requires an
+  owner, while `parent: Machine.optionalParent(events)` permits a root and
+  exposes an optional owner. `emittedEvents` describes outward ephemeral
   notifications and is never delivered implicitly to a parent.
 - Event tags in `events` and `internalEvents` must be disjoint.
 - Event tags must also be unique within each protocol list.
@@ -123,17 +125,16 @@ its extra control is required:
 - Bind a shared Atom runtime once with `AtomMachine.bind(runtime)`, then use the
   returned `make` or `resume`. Use `AtomMachine.make(machine)` and
   `AtomMachine.resume(machine, snapshot)` for service-free machines.
-- Use one invocation object: `effect` for one-shot work, `stream` for repeated
-  externally produced values, `after` for a timer, `logic` for reusable process
-  logic, and `child` for a complete child
-  statechart. `Machine.invoke({...})` preserves owner state and source channels
-  across sibling lifecycle handlers. Inside `.handle(...)`, `self` and `parent`
-  use the owning definition's exact public input and `parentEvents` protocols.
-  The bound `definition.invoke({...})` form is equivalent, not required.
+- Use the state-local `invoke: (from) => ...` selector: `from.effect` for
+  one-shot work, `from.stream` for repeated externally produced values,
+  `from.timer` for a timer, `from.logic` for reusable process logic, and
+  `from.child` for a complete child statechart. Its chain preserves owner state
+  and source channels across lifecycle handlers. Inside `.handle(...)`, `self`
+  and any declared `parent` use the owning definition's exact protocols.
 - Use `Machine.child(id, machine)` for a complete statechart descriptor and
   `Machine.childAddress<Event>(id)` for a low-level process address. A logic
-  invocation is addressable only when `Machine.invoke` receives that
-  address explicitly.
+  invocation is addressable only when `from.logic` receives that address
+  explicitly.
 - Use the callback's `enqueue` argument for `raise`, `emit`, `sendTo`, and
   `stop`. These operations record closed machine commands and do not run Effects.
 
@@ -216,6 +217,22 @@ const offeredIfSlot = (
 Do not derive this type with `Parameters<typeof States.get>[0]`; that depends
 on overload order and does not express ownership by the state definition.
 
+The same extractor accepts a machine when that is the object exported at the
+consumer boundary. Use `Value` for a decoded schema-backed state payload and
+`SnapshotAt` for the snapshot rooted at one active path:
+
+```ts
+type Complete = Machine.Snapshot<typeof machine>
+type Session = Machine.Value<typeof States, "root.trading.InSession">
+type Trading = Machine.SnapshotAt<typeof machine, "root.trading">
+```
+
+`Value` accepts only paths that own a schema, matching `States.get`.
+`SnapshotAt` also accepts structural paths, matching `States.getSnapshot`.
+Both reject stale or misspelled paths. Prefer these definition- or
+machine-bound forms over `.cases.Case.Type`, `typeof States.states`, or
+composing `Machine.Machine.States` with raw-tree path extractors.
+
 An active state does not need a schema unless it owns data. Omit `schema` for
 control-only atomic, compound, parallel, and final states:
 
@@ -231,10 +248,7 @@ const States = Machine.states({
   }
 })
 
-initial: {
-  target: (to) => to.Form.initial(),
-  resolve: ({ target }) => target((form) => form.Editing.from())
-}
+initial: (to) => to.Form.initial.resolve(({ target }) => target((form) => form.Editing.from()))
 ```
 
 Schema-less states have the same control semantics as schema-backed states:
@@ -244,13 +258,11 @@ in snapshots. They do not have a state value:
 ```ts
 Idle: {
   on: {
-    Start: Machine.transition({
-      target: (to) => to.full.Form.initial(),
-      resolve: ({ state, target }) => {
+    Start: (to) =>
+      to.full.Form.initial.resolve(({ state, target }) => {
         // state: undefined
         return target.from((form) => form.Editing.from())
-      }
-    })
+      })
   }
 }
 
@@ -331,10 +343,7 @@ const States = Machine.states({
 const machine = Machine.make({
   states: States.states,
   events: Machine.events(),
-  initial: {
-    target: (to) => to.Done(),
-    resolve: ({ target }) => target.from()
-  }
+  initial: (to) => to.Done().resolve(({ target }) => target.from())
 }).handle({
   Done: {
     output: () => "done"
@@ -351,12 +360,12 @@ with `.initial`. This is available on top-level state methods under
 `target.branch`; atomic and final state methods do not expose it:
 
 ```ts
-Open: Machine.transition({
-  target: (to) => to.full.opened.initial(),
-  resolve: ({ target }) => target.from({ teamId: "team-1" })
-})
+Open: (to) => to.full.opened.initial.resolve(({ target }) => target.from({ teamId: "team-1" }))
 ```
 
+The definition-time `.initial` property is a topology value. The exact
+resolver `target` is still a callable runtime builder.
+
 The selected state's own value is passed directly to `initial(value)` or
 constructed inside planning with `initial.from(input)`. A structural selected
 state uses `initial()`.
@@ -431,12 +440,12 @@ checkout: {
 Target it without a value:
 
 ```ts
-Resume: Machine.transition({
-  target: (to) => to.history.checkout.exact(),
-  resolve: ({ target }) => target()
-})
+Resume: (to) => to.history.checkout.exact.resolve(({ target }) => target())
 ```
 
+Each declared history leaf is a topology value; the resolver's selected
+history builder remains callable to construct restoration evidence.
+
 Deep history restores the complete remembered subtree and its decoded values.
 Shallow history restores only parent and direct-child values. If the remembered
 child is compound, its configured initial child needs a freshly constructed
@@ -486,6 +495,22 @@ prior effects, machine instances, and timers are not rewound.
 | `target.full`    | The destination may be under any top-level root                            | Nothing is inferred for a newly selected root; build its complete active snapshot |
 | `target.history` | The destination is a declared history pseudo-state                         | Its parent's remembered configuration, or a source-independent complete default containing that owner before the first capture |
 
+Definition-time instructions that only identify topology are values:
+`to.none`, `to.full.Flow.initial`, `to.history.Flow.recent`, and
+`to.local.with`. State and choice destinations remain calls, such as
+`to.full.Running()` and `to.local.Routing()`, because those calls select the
+node. Resolver-time builders also remain callable because they construct and,
+for named branches, brand runtime evidence such as `select.unchanged()`.
+
+Use `to.local.with` when a descendant transition updates the nearest
+schema-backed compound value while retaining that same compound scope:
+
+```ts
+Play: (to) =>
+  to.local.with.resolve(({ containingState, target }) =>
+    target.from({ ...containingState, playing: true }, (flow) => flow.Playing.from()))
+```
+
 Entering an inactive parallel state through `target.local` or `target.branch`
 requires a complete callback with one selection per region. A parallel state
 that is already active remains partially addressable through `target.branch`;
@@ -497,11 +522,16 @@ sets. A `target.full` result with the same active paths can update values withou
 exiting shared states. To force the source to exit and enter again:
 
 ```ts
-Refresh: Machine.transition({
-  target: (to) => to.full.Ready(),
-  reenter: true,
-  resolve: ({ state, target }) => target.from({ value: state.value })
-})
+Refresh: (to) =>
+  to.full.Ready().resolve(({ state, target }) => target.from({ value: state.value }), { reenter: true })
+```
+
+When no resolver is needed, use the selected target directly and append
+`.reenter()` only when restart semantics are intentional:
+
+```ts
+Finish: (to) => to.full.Done()
+Restart: (to) => to.none.reenter()
 ```
 
 Do not use `target.full` merely because it is easiest to discover. Prefer the
@@ -561,8 +591,9 @@ only schema-backed paths; use `matches` or `getSnapshot` for any active path.
 `context.containingState` is the immediate typed state value (`undefined` at a
 root or when that state is schema-less). `context.ancestors` contains only
 valued structural ancestors. This is separate from `context.parent`, which is
-the owning machine target or `undefined` for a root machine. Use full state paths
-when another ancestor value is needed:
+present only when declared by the machine. `Machine.parent` makes it a required
+owning-machine target; `Machine.optionalParent` makes it a target or
+`undefined`. Use full state paths when another ancestor value is needed:
 
 ```ts
 ancestors["Route.Ready"]
@@ -578,16 +609,14 @@ Event, `always`, and `onDone` transition contexts include a fully typed
 microstep, before any selected transition is applied:
 
 ```ts
-BufferReady: Machine.transition({
-  branches: (to) => ({
+BufferReady: (to) =>
+  to.branches({
     online: { target: to.local.Playing() },
-    unchanged: { target: to.none() }
-  }),
-  resolve: ({ snapshot, select }) =>
+    unchanged: { target: to.none }
+  }).resolve(({ snapshot, select }) =>
     States.matches(snapshot, "Player.Network.Online")
       ? select.online.from()
       : select.unchanged()
-})
 ```
 
 Use the existing `States.matches`, `States.get`, `States.getWithParents`, and
@@ -622,13 +651,11 @@ When sibling state payloads share fields, destructure away the source
 discriminator and construct the destination through its target builder:
 
 ```ts
-Submit: Machine.transition({
-  target: (to) => to.local.Saving(),
-  resolve: ({ state, target }) => {
+Submit: (to) =>
+  to.local.Saving().resolve(({ state, target }) => {
     const { _tag: _, ...fields } = state
     return target.from({ ...fields, attempt: 1 })
-  }
-})
+  })
 ```
 
 The target schema remains responsible for defaults, transforms, refinements,
@@ -641,45 +668,66 @@ A transition declares every possible branch and resolves the selected target
 synchronously:
 
 ```ts
-Submit: Machine.transition({
-  branches: (to) => ({
+Submit: (to) =>
+  to.branches({
     valid: { target: to.local.Saving() },
-    invalid: { target: to.none() }
-  }),
-  resolve: ({ state, select }) => state.valid
+    invalid: { target: to.none }
+  }).resolve(({ state, select }) => state.valid
     ? select.valid.from({ draft: state.draft })
     : select.invalid()
-})
 ```
 
 Every installed event, `always`, `onDone`, choice, and invoke lifecycle handler
-must use `Machine.transition`. A direct transition declares one `target`. A
-branching transition declares every possible target in a named `branches`
-record, then uses ordinary TypeScript control flow in `resolve` to return one
+receives a bound `to` selector. A direct transition selects one target and calls
+its `resolve` method. A branching transition calls `to.branches` with every
+possible target, then uses ordinary TypeScript control flow in `resolve` to return one
 typed `select` builder. Branch keys are stable testing and inspection identities;
 an optional `title` controls presentation and otherwise defaults to the key.
-Selecting a branch whose target is `to.none()` handles the transition without a
+Selecting a branch whose target is `to.none` handles the transition without a
 destination while retaining queued commands, raised events, and emitted events.
 
+Set `declinable: true` only when the resolver may decide that its transition is
+not enabled. The flag adds a typed `decline()` capability to that resolver and
+permits its opaque result:
+
+```ts
+Submit: (to) =>
+  to.branches({
+    accepted: { target: to.local.Saving() },
+    consumed: { target: to.none }
+  }).resolve(({ event, select, decline }) => {
+    if (!belongsToThisState(event)) return decline()
+    return event.consume ? select.consumed() : select.accepted.from()
+  }, { declinable: true })
+```
+
+Declining discards that resolver's enqueue buffer and resumes hierarchical
+event or eventless selection at the next eligible ancestor. If no candidate
+accepts, the trigger is unhandled. This is deliberately different from
+`to.none`, which consumes the trigger. `decline()` is absent and its result is
+rejected unless the literal flag is present. Choice and initial routing remain
+total and cannot decline. Static inspection exposes the distinction through
+`TransitionDefinition.acceptance` without executing resolver code. Completion
+and invocation outcomes have no ancestor candidate; declining one ignores that
+lifecycle occurrence and leaves the current configuration active.
+
 The `branches` callback runs once when handlers are installed. Its record uses
 the deterministic ECMAScript property order for presentation and `branchIndex`;
 array-index and symbol keys are rejected. Treat the string key as semantic:
 reordering named properties may change their display index, but visualizers,
 coverage, and trace verification identify each branch by its key.
 
-`reenter: true` remains meaningful with `to.none()`: the source exits and
+`reenter: true` remains meaningful with `to.none`: the source exits and
 enters again while its logical configuration is retained.
 
 Closed statechart and machine operations use `enqueue`:
 
 ```ts
-Submit: Machine.transition({
-  target: (to) => to.local.Saving(),
-  resolve: ({ target }, enqueue) => {
+Submit: (to) =>
+  to.local.Saving().resolve(({ target }, enqueue) => {
     enqueue.emit(Emissions.SaveRequested())
     return target.from()
-  }
-})
+  })
 ```
 
 Declare emission constructors separately from machine inputs:
@@ -768,20 +816,15 @@ export const ParentEvents = Machine.events(ChildFinished)
 
 const child = Machine.make({
   events: ChildEvents,
-  parentEvents: ParentEvents,
+  parent: Machine.parent(ParentEvents),
   // ...
 }).handle({
   Working: {
     on: {
-      Finish: Machine.transition({
-        target: (to) => to.none(),
-        resolve: ({ parent }, enqueue) => {
-          if (parent !== undefined) {
-            enqueue.sendTo(parent, ParentEvents.ChildFinished())
-          }
-          return undefined
-        }
-      })
+      Finish: (to) =>
+        to.none.resolve(({ parent }, enqueue) => {
+          enqueue.sendTo(parent, ParentEvents.ChildFinished())
+        })
     }
   }
 })
@@ -792,12 +835,14 @@ const parent = Machine.make({
 })
 ```
 
-Invoking the child under a parent that lacks any required `parentEvents` case
-is a type error. Within child handlers, `parent` accepts only that protocol.
-The same child may run as a root, where `parent` is `undefined`. `self` accepts
-the machine's public inputs. Both are minimal `MachineTarget<Event>` values,
-provided by the shared `MachineReferences<InputEvents, ParentEvents>` handler
-context. Neither machine target is a structural state value; use
+Invoking the child under a parent that lacks any required parent event is a
+type error. Within child handlers, `parent` accepts only that protocol and is
+not optional. Root APIs reject the machine. Use
+`Machine.optionalParent(ParentEvents)` instead when the same definition must
+also run as a root; then `parent` is optional. With no declaration, callbacks
+have no `parent` property. `self` accepts the machine's public inputs. Both
+targets are minimal `MachineTarget<Event>` values. Neither machine target is a
+structural state value; use
 `containingState` and `ancestors` for statechart ancestry.
 
 Atom-backed machines retain the same transient semantics. Use
@@ -856,10 +901,7 @@ const definition = Machine.make({
   states: States.states,
   events: Events,
   internalEvents: InternalEvents,
-  initial: {
-    target: (to) => to.Idle(),
-    resolve: ({ target }) => target.from()
-  }
+  initial: (to) => to.Idle().resolve(({ target }) => target.from())
 })
 ```
 
@@ -892,8 +934,14 @@ Use the exported utility types when another API must preserve the boundary:
 ```ts
 type PublicEvent = Machine.Machine.InputEvent<typeof definition>
 type AnyHandledEvent = Machine.Machine.Event<typeof definition>
+type StartupInput = Machine.Machine.Input<typeof definition>
+type StartupInputSchema = Machine.Machine.InputSchema<typeof definition>
 ```
 
+`Input` is the decoded value accepted at startup. It is `never` for a machine
+whose input schema is `Schema.Void`; use `InputSchema` only when an API needs
+the schema object itself.
+
 `MachineRef.send`, `machineAtom.send`, and `Machine.plan` accept decoded public
 events or constructions returned by `Machine.events`. Transition handlers
 receive only decoded events. Raised events additionally accept constructions
@@ -906,23 +954,28 @@ Cluster RPC payloads are additionally decoded against the public `events`
 schemas at the transport boundary. Never repeat an `_tag` within a list or
 across both configuration lists.
 
+Do not extract `enqueue`, target builders, transition contexts, command or
+inspection unions, or event-construction `ReturnType`s into application helper
+APIs. Keep commands inside transition resolvers, where the owning state,
+protocols, references, and capabilities are inferred. Likewise, do not add
+Atom `State` or `Event` aliases: selectors infer from their bridge, while
+consumer props use `Snapshot`, `Value`, or `InputEvent` from the exported state
+definition or machine.
+
 ## Recoverable state-scoped work
 
-Use `Machine.invoke` with an `effect` for one-shot work. Lifecycle callbacks
-receive the typed Effect channels and can transition directly:
+Use `from.effect` for one-shot work. Lifecycle callbacks receive the typed
+Effect channels and can transition directly:
 
 ```ts
-invoke: Machine.invoke({
-  id: "save",
-  effect: () => SaveService.save(draft),
-  onDone: Machine.transition({
-    target: (to) => to.full.Saved(),
-    resolve: ({ output, target }) => target.from({ entry: output })
-  }),
-  onFailure: Machine.transition({
-    target: (to) => to.full.SaveFailed(),
-    resolve: ({ error, target }) => target.from({ message: error.message })
-  })
+machine.handle({
+  Saving: {
+    invoke: (from) =>
+      from.effect("save", () => SaveService.save(draft))
+        .onDone((to) => to.full.Saved().resolve(({ output, target }) => target.from({ entry: output })))
+        .onFailure((to) =>
+          to.full.SaveFailed().resolve(({ error, target }) => target.from({ message: error.message })))
+  }
 })
 ```
 
@@ -942,20 +995,17 @@ events. `onElement` maps each value into an owner transition, while `onDone`
 handles normal Stream completion and `onFailure` handles the typed Stream error:
 
 ```ts
-invoke: Machine.invoke({
-  id: "broadcast-channel",
-  stream: () => messages,
-  onElement: {
-    target: Machine.targetless,
-    resolve: ({ element }, enqueue) => {
-      enqueue.raise(Events.MessageReceived({ message: element }))
-    }
-  },
-  onDone: { target: Machine.targetless },
-  onFailure: Machine.transition({
-    target: (to) => to.full.Disconnected(),
-    resolve: ({ error, target }) => target.from({ error })
-  })
+machine.handle({
+  Listening: {
+    invoke: (from) =>
+      from.stream("broadcast-channel", () => messages)
+        .onElement((to) =>
+          to.none.resolve(({ element }, enqueue) => {
+            enqueue.raise(Events.MessageReceived({ message: element }))
+          }))
+        .onDone((to) => to.none)
+        .onFailure((to) => to.full.Disconnected().resolve(({ error, target }) => target.from({ error })))
+  }
 })
 ```
 
@@ -964,89 +1014,75 @@ after the selected parent macrostep commits. Exiting or reentering the owner
 interrupts the Stream and runs its finalizers. A later entry starts a fresh
 Stream. Stream defects and self-interruption fail the owning machine.
 
-The direct `{ target: Machine.targetless, resolve }` shorthand is available
-when a transition only enqueues commands. It is non-reentering and the resolver
-must return `undefined`. Keep `Machine.transition(...)` for full state selection,
-named branches, or reentry.
-
-When a source function reads `state`, `containingState`, `ancestors`, or the entry `event`,
-`Machine.invoke` infers that owner context and the returned Effect's output,
-error, and service channels together. No return annotation is needed:
-
-```ts
-invoke: Machine.invoke({
-  id: "load",
-  effect: ({ state }) => LoadService.load(state.userId),
-  onDone: Machine.transition({
-    target: (to) => to.full.Loaded(),
-    resolve: ({ output, target }) => target.from({ user: output })
-  }),
-  onFailure: Machine.transition({
-    target: (to) => to.full.LoadFailed(),
-    resolve: ({ error, target }) => target.from({ error })
-  })
+Use `to.none` when a transition keeps the current configuration. Call
+`to.none.resolve(...)` when it also enqueues commands; a block resolver may
+omit its return because it is contextually typed to return `undefined`.
+
+When a source function reads `state`, `containingState`, `ancestors`, or the
+entry `event`, `from.effect` infers that owner context and the returned Effect's
+output, error, and service channels together. No return annotation is needed:
+
+```ts
+machine.handle({
+  Loading: {
+    invoke: (from) =>
+      from.effect("load", ({ state }) => LoadService.load(state.userId))
+        .onDone((to) => to.full.Loaded().resolve(({ output, target }) => target.from({ user: output })))
+        .onFailure((to) => to.full.LoadFailed().resolve(({ error, target }) => target.from({ error })))
+  }
 })
 ```
 
 Inside `.handle(...)`, the constructor receives the owning machine's public
-input and `parentEvents` protocols contextually. Sources and lifecycle handlers
+input and declared parent protocol contextually. Sources and lifecycle handlers
 can send through `self` and `parent` without naming the definition:
 
 ```ts
 const machine = Machine.make({
   events: Commands,
   internalEvents: InternalEvents,
-  parentEvents: ParentEvents,
+  parent: Machine.parent(ParentEvents),
   // ...
 }).handle({
   Saving: {
-    invoke: Machine.invoke({
-      id: "notify-parent",
-      effect: () => saveDocument,
-      onDone: Machine.transition({
-        target: (to) => to.none(),
-        resolve: ({ parent, self }, enqueue) => {
-          enqueue.sendTo(self, Commands.Save())
-          if (parent !== undefined) {
+    invoke: (from) =>
+      from.effect("notify-parent", () => saveDocument)
+        .onDone((to) =>
+          to.none.resolve(({ parent, self }, enqueue) => {
+            enqueue.sendTo(self, Commands.Save())
             enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
-          }
-          return undefined
-        }
-      }),
-      onFailure: Machine.transition({
-        target: (to) => to.none(),
-        resolve: () => undefined
-      })
-    })
+          }))
+        .onFailure((to) => to.none)
   }
 })
 ```
 
-The machine-bound `definition.invoke(...)` form remains equivalent when the
-definition is already named. A direct `invoke: { ... }` object remains available
-when lifecycle handlers do not need source-derived context.
+The computation, logic, or child descriptor may be named separately. The
+invocation chain remains inline because it is bound to its owning state and
+machine protocols. Return an array of completed chains when a state owns more
+than one activity.
 
-A cancellable timer uses the same object:
+A cancellable timer uses its dedicated source selector:
 
 ```ts
-invoke: Machine.invoke({
-  id: "clear-status",
-  after: "3 seconds",
-  onDone: Machine.transition({
-    target: (to) => to.full.Clear(),
-    resolve: ({ target }) => target()
-  })
+machine.handle({
+  Waiting: {
+    invoke: (from) =>
+      from.timer("clear-status", "3 seconds")
+        .onDone((to) => to.full.Clear().resolve(({ target }) => target()))
+  }
 })
 ```
 
 The timer starts on state entry and is interrupted on exit. Its `onDone` is
-always required. `effect: () => Effect.sleep(...)` has the same scoped
-cancellation behavior, but `after` records timer intent and exposes a static
-duration through `Machine.activityDefinitions`. Effect sources are always
-factories evaluated when their state is entered. For reusable process logic,
-provide `logic`, a state-local lifecycle `id`, and a typed `address`. TypeScript
-checks the address protocol against the logic event protocol. Lifecycle ids and
-addresses serve different purposes and must both be explicit.
+always required. An Effect containing `Effect.sleep(...)` has the same scoped
+cancellation behavior, but `from.timer` records timer intent and exposes a
+static duration through `Machine.activityDefinitions`. Effect sources are
+always factories evaluated when their state is entered. For reusable process
+logic, pass a state-local lifecycle id plus `{ logic, address }` to
+`from.logic`. TypeScript checks the address protocol against the logic event
+protocol. Lifecycle ids and addresses serve different purposes and must both
+be explicit.
 
 ## Invoked child statecharts
 
@@ -1059,13 +1095,12 @@ const Editor = Machine.child("editor", EditorMachine)
 Invoke it from its owning state:
 
 ```ts
-invoke: Machine.invoke({
-  child: Editor,
-  input: editorInput,
-  onDone: Machine.transition({
-    target: (to) => to.full.EditorDone(),
-    resolve: ({ output, target }) => target.from({ output })
-  })
+machine.handle({
+  Editing: {
+    invoke: (from) =>
+      from.child(Editor, { input: editorInput })
+        .onDone((to) => to.full.EditorDone().resolve(({ output, target }) => target.from({ output })))
+  }
 })
 ```
 
@@ -1093,7 +1128,7 @@ logic that does not have a complete machine descriptor.
 ### Inspecting state-owned activities
 
 Use `Machine.activityDefinitions(machine)` to inspect invokes without running
-them. Static inline `Machine.invoke` definitions expose serializable ownership
+them. Static inline fluent invocation definitions expose serializable ownership
 metadata:
 
 ```ts
@@ -1313,9 +1348,10 @@ const step = yield * probe.sendAndAwait(event)
 ```
 
 Inspect `step.before`, `step.after`, `step.plan`, `step.handled`, and
-`step.configurationChanged`. An ignored event has `handled: false` and an
-empty microstep list, but still completes its acknowledgement. A targetless
-handler has `handled: true` even if its before and after snapshots are equal.
+`step.configurationChanged`. An ignored event, including one for which every
+eligible candidate declines, has `handled: false` and an empty microstep list,
+but still completes its acknowledgement. A targetless handler has
+`handled: true` even if its before and after snapshots are equal.
 
 Do not use a probe as a substitute for a domain completion event. The
 acknowledgement covers the submitted event's synchronous macrostep, state
@@ -1385,10 +1421,7 @@ reference model when correctness of the expected behavior matters.
 Select the initial root separately from constructing its value:
 
 ```ts
-initial: {
-  target: (to) => to.Idle(),
-  resolve: ({ target }) => target.from()
-}
+initial: (to) => to.Idle().resolve(({ target }) => target.from())
 ```
 
 ### Invoked child expects events not accepted by the parent
@@ -1399,13 +1432,16 @@ the parent's public events:
 ```ts
 export const ChildParentEvents = Machine.events(ChildFinished)
 
-// child
-parentEvents: ChildParentEvents
+// child-only machine
+parent: Machine.parent(ChildParentEvents)
 
 // parent
 events: Machine.events(Submit, ChildParentEvents)
 ```
 
+Use `Machine.optionalParent(ChildParentEvents)` only when the child is also a
+valid independent root and narrow `parent` before sending.
+
 ### An internal event is rejected by `send`
 
 This is intentional. Public input boundaries accept only schemas declared in
@@ -1470,6 +1506,6 @@ The current API does not include:
 - declarative first-class guards;
 - a complete inspectable graph for arbitrary transition Effects.
 
-Use ordinary TypeScript conditions for guards and an inline `Machine.invoke`
-with `after` for state-scoped timers. Do not invent undocumented state-node
-properties such as `guard`.
+Use ordinary TypeScript conditions for guards and inline
+`invoke: (from) => from.timer(...)` chains for state-scoped timers. Do not
+invent undocumented state-node properties such as `guard`.