@typeonce/effect-machine 0.17.0 → 0.19.0

package/docs/agent-guide.md

@@ -54,12 +54,15 @@ testing, or simulation variant.
 
 ```ts
 const State = Schema.TaggedUnion({
-  Idle: {},
   Saving: { draft: Draft },
   Failed: { message: Schema.String }
 })
 
-const States = Machine.states(State.cases)
+const States = Machine.states({
+  Idle: {},
+  Saving: State.cases.Saving,
+  Failed: State.cases.Failed
+})
 export const Event = Machine.events(
   Schema.TaggedUnion({
     Save: {}
@@ -125,22 +128,38 @@ 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 any
-  declared `parent` use the owning definition's exact protocols; no intermediate
-  definition method is 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.
 
 ## Atomic, compound, parallel, and history states
 
+### Topology is a validity boundary
+
+Design the state tree so invalid domain situations cannot be constructed. A
+parallel node is not merely a convenient grouping of related concepts: it
+declares the Cartesian product of its regions. Every combination must be
+meaningful in snapshots, explicit targets, decoding, and resume.
+
+If a handler reads a sibling region to decide whether entering its target is
+legal, treat that as a topology smell and try a compound hierarchy first. Do
+not move the same invariant into a disabled UI control, redundant event field,
+or invoked-service failure. Cross-region reads remain useful for coordinating
+genuinely independent regions and for projecting snapshots into views.
+
+Place an invoked Effect or resource-dependent state beneath the state that
+guarantees the resource exists. Exiting the owner should structurally exit and
+interrupt all dependent work.
+
 ### Inline topology by default; extract only repeated states
 
 Prefer writing the complete topology inline in `Machine.states`. A one-off
@@ -218,8 +237,25 @@ 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:
+control-only atomic, compound, parallel, and final states. In particular, use
+`{}` instead of an empty tagged-union case or tagged class:
 
 ```ts
 const States = Machine.states({
@@ -243,11 +279,7 @@ in snapshots. They do not have a state value:
 ```ts
 Idle: {
   on: {
-    Start: (to) =>
-      to.full.Form.initial.resolve(({ state, target }) => {
-        // state: undefined
-        return target.from((form) => form.Editing.from())
-      })
+    Start: (to) => to.full.Form.initial
   }
 }
 
@@ -262,6 +294,13 @@ also omitted from `ancestors`; an immediate structural containing state is
 typed as `undefined`. Add `schema` when a state begins to own data or needs runtime
 validation and persistence for that data.
 
+Declare data-bearing states together with the named
+`const State = Schema.TaggedUnion(...)` pattern, then reference `State.cases`
+from the topology. This keeps the state value protocol visible and reusable.
+Use a named `Schema.TaggedClass` instead when a standalone state benefits from
+class identity. Do not bury one-off tagged schema declarations inside
+`Machine.states`.
+
 Use an atomic state when no child phase can be active beneath it.
 
 Use a compound state when exactly one child phase is active. It must declare an
@@ -311,6 +350,11 @@ Every parallel region needs an active state in initial and full snapshot
 builders. The same rule applies when a local or branch target enters an
 inactive nested parallel state.
 
+This is also a semantic product: `Online + Closed`, `Online + Open`,
+`Offline + Closed`, and `Offline + Open` are all valid configurations in the
+example above. If even one combination must be prevented for correctness, use
+a compound hierarchy or redesign the regions.
+
 Use `type: "final"` for a terminal leaf in `Machine.states`. A final
 child completes its compound parent. Put `onDone` on that completed parent,
 never on the final leaf. The definition owns the output schema and the handler
@@ -328,7 +372,7 @@ const States = Machine.states({
 const machine = Machine.make({
   states: States.states,
   events: Machine.events(),
-  initial: (to) => to.Done().resolve(({ target }) => target.from())
+  initial: (to) => to.Done()
 }).handle({
   Done: {
     output: () => "done"
@@ -348,6 +392,20 @@ with `.initial`. This is available on top-level state methods under
 Open: (to) => to.full.opened.initial.resolve(({ target }) => target.from({ teamId: "team-1" }))
 ```
 
+Return the `.initial` transition directly when the selected state owns no data
+and the transition has no commands to enqueue:
+
+```ts
+Close: (to) => to.full.closed.initial
+```
+
+Do not manually reconstruct the declared initial descendants at ordinary entry
+transitions. Reserve explicit descendant builders for deliberately non-default
+configurations and for replacing an already-active parallel root with one
+complete canonical configuration. `Machine.make({ initial })` still constructs
+the first complete snapshot through its initial selector; that selector
+statically restricts a compound node to its declared initial child.
+
 The definition-time `.initial` property is a topology value. The exact
 resolver `target` is still a callable runtime builder.
 
@@ -425,11 +483,11 @@ checkout: {
 Target it without a value:
 
 ```ts
-Resume: (to) => to.history.checkout.exact.resolve(({ target }) => target())
+Resume: (to) => to.history.checkout.exact
 ```
 
-Each declared history leaf is a topology value; the resolver's selected
-history builder remains callable to construct restoration evidence.
+Each declared history leaf is a topology value and can be returned directly
+when no resolver work is needed.
 
 Deep history restores the complete remembered subtree and its decoded values.
 Shallow history restores only parent and direct-child values. If the remembered
@@ -511,8 +569,11 @@ 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:
+When no resolver is needed and the selected builder supports zero-argument
+construction, return the selected target directly. This applies the same
+default construction as `target.from()`; the compiler rejects the shorthand
+when state data or nested configuration is required. Append `.reenter()` only
+when restart semantics are intentional:
 
 ```ts
 Finish: (to) => to.full.Done()
@@ -609,6 +670,11 @@ Use the existing `States.matches`, `States.get`, `States.getWithParents`, and
 selected in one microstep receive the same capture. Synchronous handlers use
 that captured value and cannot consult live runtime state later.
 
+Before using a cross-region read to permit or reject a target, verify that all
+combinations of the parallel regions are valid. If the check excludes an
+invalid combination, move the invariant into a compound hierarchy. Observer,
+view, diagnostic, and test queries do not have this concern.
+
 Do not expect `snapshot` in entry, exit, invoke, initializer, history-default,
 or choice contexts. Choice is an important soundness boundary: a startup or
 chained choice can run without a complete stable configuration containing the
@@ -886,7 +952,7 @@ const definition = Machine.make({
   states: States.states,
   events: Events,
   internalEvents: InternalEvents,
-  initial: (to) => to.Idle().resolve(({ target }) => target.from())
+  initial: (to) => to.Idle()
 })
 ```
 
@@ -919,8 +985,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
@@ -933,18 +1005,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: (to) => to.full.Saved().resolve(({ output, target }) => target.from({ entry: output })),
-  onFailure: (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 })))
+  }
 })
 ```
 
@@ -964,15 +1046,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: (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 }))
+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 })))
+  }
 })
 ```
 
@@ -985,16 +1069,18 @@ 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,
-error, and service channels together. No return annotation is needed:
+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
-invoke: Machine.invoke({
-  id: "load",
-  effect: ({ 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 }))
+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 })))
+  }
 })
 ```
 
@@ -1010,42 +1096,44 @@ const machine = Machine.make({
   // ...
 }).handle({
   Saving: {
-    invoke: Machine.invoke({
-      id: "notify-parent",
-      effect: () => saveDocument,
-      onDone: (to) =>
-        to.none.resolve(({ parent, self }, enqueue) => {
-          enqueue.sendTo(self, Commands.Save())
-          enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
-        }),
-      onFailure: (to) => to.none
-    })
+    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" }))
+          }))
+        .onFailure((to) => to.none)
   }
 })
 ```
 
-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.
+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: (to) => to.full.Clear().resolve(({ target }) => target())
+machine.handle({
+  Waiting: {
+    invoke: (from) =>
+      from.timer("clear-status", "3 seconds")
+        .onDone((to) => to.full.Clear())
+  }
 })
 ```
 
 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
 
@@ -1058,10 +1146,12 @@ const Editor = Machine.child("editor", EditorMachine)
 Invoke it from its owning state:
 
 ```ts
-invoke: Machine.invoke({
-  child: Editor,
-  input: editorInput,
-  onDone: (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 })))
+  }
 })
 ```
 
@@ -1089,7 +1179,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
@@ -1189,6 +1279,22 @@ const decoded = yield* Machine.decodeSnapshot(machine, encoded)
 const ref = yield* Machine.resume(machine, decoded)
 ```
 
+`Machine.Snapshot` is the decoded, process-local representation. It may retain
+`Schema.Class` instances and capabilities that cannot cross a JSON boundary.
+`Machine.EncodedSnapshot` is different: successful `encodeSnapshot` calls
+guarantee canonical `Schema.Json` for every active value, completion output,
+and history value. Schema codecs convert rich values such as `Date`, `bigint`,
+and `undefined` to their declared JSON forms. Cycles, functions, symbols, and
+opaque values without a JSON representation fail with the typed
+`MachineSchemaEncodeError`; they never become a later `JSON.stringify` defect.
+
+Keep DOM nodes, open handles, services, and similar capabilities in an Effect
+service or UI adapter. Local events may carry those values when they stay inside
+one process. Cluster public input events, persisted state, and completion
+outputs are transport protocols and must instead declare JSON-compatible
+encoded forms; use an explicit transform or `Schema.toCodecJson` where the
+canonical codec is the intended wire contract.
+
 Pass only a decoded `Machine.Snapshot` to `resume`; encoded or arbitrary
 transport data belongs at `decodeSnapshot`. Resumption validates and normalizes
 the logical snapshot again, then publishes it as the fresh runtime's first
@@ -1382,7 +1488,7 @@ reference model when correctness of the expected behavior matters.
 Select the initial root separately from constructing its value:
 
 ```ts
-initial: (to) => to.Idle().resolve(({ target }) => target.from())
+initial: (to) => to.Idle()
 ```
 
 ### Invoked child expects events not accepted by the parent
@@ -1467,6 +1573,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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeonce/effect-machine",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Schema-first state machines and statecharts for Effect",
   "author": "Sandro Maglione",
   "repository": {
@@ -46,14 +46,14 @@
     "provenance": true
   },
   "peerDependencies": {
-    "effect": "4.0.0-rc.109"
+    "effect": "4.0.0-rc.110"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.0",
-    "@effect/vitest": "4.0.0-rc.109",
+    "@effect/vitest": "4.0.0-rc.110",
     "@types/node": "25.7.0",
     "dprint": "0.55.2",
-    "effect": "4.0.0-rc.109",
+    "effect": "4.0.0-rc.110",
     "pagefind": "1.5.2",
     "tinybench": "2.9.0",
     "tstyche": "7.2.1",