@typeonce/effect-machine 0.16.0 → 0.17.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.
@@ -127,9 +129,9 @@ its extra control is required:
   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.
+  across sibling lifecycle handlers. Inside `.handle(...)`, `self` and any
+  declared `parent` use the owning definition's exact protocols; no intermediate
+  definition method is required.
 - 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
@@ -231,10 +233,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 +243,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 +328,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 +345,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 +425,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 +480,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 +507,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 +576,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 +594,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 +636,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 +653,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 +801,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 +820,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 +886,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())
 })
 ```
 
@@ -915,14 +942,9 @@ receive the typed Effect channels and can transition directly:
 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 })
-  })
+  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 }))
 })
 ```
 
@@ -945,17 +967,12 @@ handles normal Stream completion and `onFailure` handles the typed Stream error:
 invoke: Machine.invoke({
   id: "broadcast-channel",
   stream: () => messages,
-  onElement: {
-    target: Machine.targetless,
-    resolve: ({ element }, enqueue) => {
+  onElement: (to) =>
+    to.none.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 })
-  })
+    }),
+  onDone: (to) => to.none,
+  onFailure: (to) => to.full.Disconnected().resolve(({ error, target }) => target.from({ error }))
 })
 ```
 
@@ -964,10 +981,9 @@ 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.
+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`,
 `Machine.invoke` infers that owner context and the returned Effect's output,
@@ -977,54 +993,40 @@ error, and service channels together. No return annotation is needed:
 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 })
-  })
+  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) => {
+      onDone: (to) =>
+        to.none.resolve(({ parent, self }, enqueue) => {
           enqueue.sendTo(self, Commands.Save())
-          if (parent !== undefined) {
-            enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
-          }
-          return undefined
-        }
-      }),
-      onFailure: Machine.transition({
-        target: (to) => to.none(),
-        resolve: () => undefined
-      })
+          enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
+        }),
+      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 standard `Machine.invoke(...)` form retains the owning machine protocols
+even when the definition is named separately. A direct `invoke: { ... }` object
+remains available when lifecycle handlers do not need source-derived context.
 
 A cancellable timer uses the same object:
 
@@ -1032,10 +1034,7 @@ A cancellable timer uses the same object:
 invoke: Machine.invoke({
   id: "clear-status",
   after: "3 seconds",
-  onDone: Machine.transition({
-    target: (to) => to.full.Clear(),
-    resolve: ({ target }) => target()
-  })
+  onDone: (to) => to.full.Clear().resolve(({ target }) => target())
 })
 ```
 
@@ -1062,10 +1061,7 @@ Invoke it from its owning state:
 invoke: Machine.invoke({
   child: Editor,
   input: editorInput,
-  onDone: Machine.transition({
-    target: (to) => to.full.EditorDone(),
-    resolve: ({ output, target }) => target.from({ output })
-  })
+  onDone: (to) => to.full.EditorDone().resolve(({ output, target }) => target.from({ output }))
 })
 ```
 
@@ -1313,9 +1309,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 +1382,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 +1393,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

package/package.json

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