@typeonce/effect-machine 0.18.0 → 0.19.1

package/docs/agent-guide.md

@@ -1,1511 +1,400 @@
 # Effect Machine agent guide
 
-This is the model-facing reference for the currently published
-`@typeonce/effect-machine` API. Prefer these patterns over reconstructing the API
-from its internal implementation.
+Use this guide to model a statechart with `@typeonce/effect-machine`. It covers
+the decisions that shape the machine. Use the API reference for method
+signatures, history states, and choice states.
 
-## Design priorities
+Read [Effect Atom and React patterns](./effect-atom-react.md) when React needs
+to consume a machine. Keep React ownership and atom lookup out of the machine
+model.
 
-Prefer, in order: compile-time type safety, explicit and opinionated semantics,
-readable and concise machine models, and alignment with Effect core. Convenience
-must come from builders and inference rather than ambiguous omissions or weaker
-contracts. The package is pre-1.0, so improve or remove an existing API when a
-clearer long-term design replaces it; do not preserve an inferior design with
-aliases by default.
+## Create a machine
 
-Keep the core machine model local. Before adding a public name or capability,
-check Effect's existing modules and especially Cluster. Distributed identity,
-placement, discovery, transport, routing, delivery, sharding, and remote
-lifecycle belong to Cluster; expose integration through an explicit adapter
-instead of creating a similar local abstraction with different semantics.
-
-## Public imports
+Define schemas first, then states, events, the machine definition, and its
+handlers. Export the state descriptor, public event descriptor, and implemented
+machine. Tests, runtimes, and adapters can then use the same model.
 
 ```ts
 import { Machine } from "@typeonce/effect-machine"
-import { AtomMachine } from "@typeonce/effect-machine/reactivity"
-import { ClusterMachine } from "@typeonce/effect-machine/cluster"
-```
-
-Do not import the published package as `effect/unstable/machine`. The package is
-currently coupled to the exact Effect peer version listed in its `package.json`.
-
-## Definition order
-
-Use this order so inference has all schemas available when handlers are
-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 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.
-
-`Machine.make` returns a reusable definition. Each `handle` call creates one
-independent machine implementation and the result does not expose `handle`
-again. Put one implementation's complete behavior in a single handler tree;
-call `handle` again on the original definition for a separate production,
-testing, or simulation variant.
+import { Schema } from "effect"
 
-`Schema.TaggedUnion` avoids one class declaration per case:
+const CounterState = Schema.TaggedUnion({
+  Running: { count: Schema.Number }
+})
 
-```ts
-const State = Schema.TaggedUnion({
+export const CounterStates = Machine.states({
   Idle: {},
-  Saving: { draft: Draft },
-  Failed: { message: Schema.String }
+  Running: CounterState.cases.Running
 })
 
-const States = Machine.states(State.cases)
-export const Event = Machine.events(
+export const CounterEvents = Machine.events(
   Schema.TaggedUnion({
-    Save: {}
+    Start: {},
+    Increment: {},
+    Stop: {}
   })
 )
-export const Internal = Machine.internalEvents(
-  Schema.TaggedUnion({
-    Saved: { id: Schema.String },
-    SaveFailed: { message: Schema.String }
-  })
-)
-```
 
-Pass these descriptors to `Machine.make`; the event descriptor is the public
-handle, so do not introduce a tagged-union binding used only by an event helper.
-Construct new state values through the target or initial
-builder's `.from(...)` method. Both event constructors and state `.from(...)`
-defer schema construction until planning, so validation failures remain typed
-machine errors. Use
-`Schema.TaggedClass` when a case needs class methods or nominal class identity;
-the deferred constructors preserve that identity after decoding.
-
-## Hard invariants
-
-- `Machine.make({ initial })` expects a function, including for `Schema.Void`
-  input.
-- State, emit, input, and output schemas validate their runtime boundaries.
-  Event schemas provide decoders, but the local public/internal distinction is
-  a TypeScript boundary; Cluster additionally validates public commands at its
-  transport boundary.
-- Return snapshots or typed target-builder results from transitions. Do not
-  return raw decoded state values.
-- Transition and lifecycle callbacks are synchronous. Put asynchronous work in
-  an invoked Effect, logic process, or child machine and handle its lifecycle
-  with `onDone`, `onFailure`, and `onSnapshot`.
-- Put data on the narrowest state where it is valid. Put data shared by sibling
-  phases on their compound parent.
-- Declare finality only in the state definition. Do not put `type: "final"` in
-  a handler.
-- Every declared output schema needs a matching handler implementation before
-  planning or execution.
-- Handler `ancestors` keys are full dotted paths.
-- Invoke lifetimes follow state entry and exit, not the spelling of the target
-  builder.
-- Handle every typed invoked Effect failure with `onFailure`. Defects and
-  interruption terminate the owning machine.
-- Reuse an exported child descriptor for inline invocation, `sendTo`, and child
-  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. `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.
-
-## Canonical API choices
-
-Choose one helper from the intent, and reach for the lower-level form only when
-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 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 `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
-
-### Inline topology by default; extract only repeated states
-
-Prefer writing the complete topology inline in `Machine.states`. A one-off
-compound or parallel area is easier to understand in place, and extracting it
-does not improve its types. Use `Machine.state` only when the same active state
-definition is mounted more than once. Tagged schemas are already reusable and
-do not need `Machine.state`.
-
-```ts
-type TeamSlot = 1 | 2 | 3 | 4 | 5 | 6
-
-const TradingSlot = Machine.state({
-  initial: "Idle",
-  states: {
-    Idle: {},
-    InSession: State.cases.InSession,
-    Applying: State.cases.Applying
-  }
-})
-
-const States = Machine.states({
-  root: {
-    type: "parallel",
-    states: {
-      trading: {
-        type: "parallel",
-        states: {
-          slot1: TradingSlot,
-          slot2: TradingSlot,
-          slot3: TradingSlot,
-          slot4: TradingSlot,
-          slot5: TradingSlot,
-          slot6: TradingSlot
-        }
-      },
-      // Other explicit regions stay visible here.
+export const CounterMachine = Machine.make({
+  id: "Counter",
+  states: CounterStates.states,
+  events: CounterEvents,
+  initial: (to) => to.Idle()
+}).handle({
+  Idle: {
+    on: {
+      Start: (to) => to.full.Running().resolve(({ target }) => target.from({ count: 0 }))
     }
-  }
-})
-```
-
-`Machine.state` accepts one active atomic, compound, or parallel node. It
-checks child keys and the compound `initial` at the reusable definition. It is
-not a second model builder, does not define handlers, and does not accept
-history or choice nodes as roots. `Machine.states` remains the complete model
-boundary and captures every mount independently.
-
-For a finite family of paths, bind the template to that definition instead of
-maintaining a parallel string table:
-
-```ts
-const inSessionPath = <const Slot extends TeamSlot>(slot: Slot) =>
-  States.path(`root.trading.slot${slot}.InSession`)
-
-States.matches(snapshot, inSessionPath(slot))
-AtomMachine.matches(machineAtom, inSessionPath(slot))
-```
-
-`States.path` is a compile-time identity helper. It accepts a literal or a
-finite template-literal union only when every member is an active path in this
-tree. Renaming a slot or child therefore breaks the path helper at its
-definition rather than leaving a stale catalog.
-
-Use the definition-bound snapshot type when a query genuinely needs the full
-machine snapshot:
-
-```ts
-const offeredIfSlot = (
-  snapshot: Machine.Snapshot<typeof States>,
-  slot: TeamSlot
-) =>
-  !States.matches(snapshot, inSessionPath(slot))
-```
-
-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:
-
-```ts
-const States = Machine.states({
-  Idle: {},
-  Form: {
-    initial: "Editing",
-    states: {
-      Editing: {},
-      Saving: State.cases.Saving
+  },
+  Running: {
+    on: {
+      Increment: (to) => to.full.Running().resolve(({ state, target }) => target.from({ count: state.count + 1 })),
+      Stop: (to) => to.full.Idle()
     }
   }
 })
-
-initial: (to) => to.Form.initial.resolve(({ target }) => target((form) => form.Editing.from()))
 ```
 
-Schema-less states have the same control semantics as schema-backed states:
-they are active, targetable, matchable, receive lifecycle handlers, and appear
-in snapshots. They do not have a state value:
+Each step has one job:
 
-```ts
-Idle: {
-  on: {
-    Start: (to) =>
-      to.full.Form.initial.resolve(({ state, target }) => {
-        // state: undefined
-        return target.from((form) => form.Editing.from())
-      })
-  }
-}
+- `Machine.states` declares the state tree and the data owned by each state.
+- `Machine.events` declares the public messages the machine accepts and returns
+  typed event constructors.
+- `Machine.make` joins the state tree, event protocol, input, and initial state.
+- `.handle` implements the behavior of every active state and returns the
+  machine to export.
 
-States.matches(snapshot, "Form")              // allowed
-States.getSnapshot(snapshot, "Form")          // allowed
-States.get(snapshot, "Form")                  // type error: no value schema
-```
+Chain `.handle` from `Machine.make`. Do not store the intermediate definition
+when the module exports one machine implementation.
 
-For a schema-less path, builders expose only `.from(...)`; the direct callable
-form is reserved for already-decoded schema values. Structural ancestors are
-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.
+State builders construct the next snapshot. Use `.from(...)` when a state owns
+data. The machine validates that input through the state schema while it plans
+the transition.
 
-Use an atomic state when no child phase can be active beneath it.
+The examples below show one modeling decision at a time. They omit unchanged
+state and event declarations already shown above.
 
-Use a compound state when exactly one child phase is active. It must declare an
-`initial` child:
+Start the implemented machine at the application boundary and send events
+through the exported descriptor:
 
 ```ts
-const FormState = Schema.TaggedUnion({ Saving: { draft: Schema.String } })
-
-const FormStates = Machine.states({
-  Form: {
-    initial: "Editing",
-    states: {
-      Editing: {},
-      Saving: FormState.cases.Saving
-    }
-  }
-})
-```
+import { Effect } from "effect"
 
-Use a parallel state when every direct region is active:
+const program = Effect.gen(function*() {
+  const counter = yield* Machine.start(CounterMachine)
 
-```ts
-const ParallelStates = Machine.states({
-  Screen: {
-    type: "parallel",
-    states: {
-      network: {
-        initial: "Online",
-        states: {
-          Online: {},
-          Offline: {}
-        }
-      },
-      panel: {
-        initial: "Closed",
-        states: {
-          Closed: {},
-          Open: {}
-        }
-      }
-    }
-  }
+  yield* counter.send(CounterEvents.Start())
+  yield* counter.send(CounterEvents.Increment())
 })
 ```
 
-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.
+## Make impossible states unrepresentable
+
+A finite state describes how the machine behaves now. State data holds values
+needed while that mode is active.
 
-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
-computes its value:
+Do not model mutually exclusive modes with separate flags such as `loading`,
+`data`, and `error`. Those fields permit combinations such as loading with both
+data and an error. Put the modes in the state tree instead:
 
 ```ts
-const States = Machine.states({
-  Done: {
-    schema: State.cases.Done,
-    type: "final",
-    output: Schema.String
-  }
+const RequestState = Schema.TaggedUnion({
+  Ready: { value: Schema.String },
+  Failed: { message: Schema.String }
 })
 
-const machine = Machine.make({
-  states: States.states,
-  events: Machine.events(),
-  initial: (to) => to.Done().resolve(({ target }) => target.from())
-}).handle({
-  Done: {
-    output: () => "done"
-  }
+const RequestStates = Machine.states({
+  Idle: {},
+  Loading: {},
+  Ready: RequestState.cases.Ready,
+  Failed: RequestState.cases.Failed
 })
 ```
 
-Do not repeat `type: "final"` in `handle`. Execution APIs reject a machine
-until every declared output schema has an implementation.
-
-Enter a compound or parallel state through its declared initial configuration
-with `.initial`. This is available on top-level state methods under
-`target.full` and compatible nested state methods under `target.local` and
-`target.branch`; atomic and final state methods do not expose it:
-
-```ts
-Open: (to) => to.full.opened.initial.resolve(({ target }) => target.from({ teamId: "team-1" }))
-```
+The machine can now be `Loading`, `Ready`, or `Failed`. It cannot construct a
+snapshot that represents two of those modes at once.
 
-The definition-time `.initial` property is a topology value. The exact
-resolver `target` is still a callable runtime builder.
+Use this test when deciding between a state and a field: if the value changes
+which events the machine should handle, which work runs, or how the machine
+behaves, model it as a state. Otherwise, keep it as data on the state that owns
+it.
 
-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()`.
+## Put data on the lowest state that owns it
 
-When a declared initial child owns a schema, its parent implements
-`initialize`. The context's `builder` is already bound to that child, so it
-cannot accidentally select a state that differs from the definition:
+State data should exist only while it is valid. Put it on the lowest node whose
+active subtree needs it. If several sibling states need the same data, their
+compound parent owns it.
 
 ```ts
-opened: {
-  initialize: ({ state, builder }) =>
-    builder.from({ requestId: state.requestId })
-}
-```
-
-A parallel initializer supplies every schema-valued direct region with a
-fluent completion builder. Structural regions are omitted:
-
-```ts
-dashboard: {
-  initialize: ({ builder }) =>
-    builder.filters.from({ query: "" }).results.from({ page: 1 })
-}
-```
-
-Default entry then continues recursively. Nested compound and parallel owners
-provide their own `initialize` implementations. Missing implementations and
-incomplete parallel builders are reported at `handle(...)`. Builder `.from`
-inputs are decoded by the machine, so schema failures remain typed machine
-failures. An explicit snapshot target that manually selects all children does
-not use `initialize`.
-
-Declare a history pseudo-state below the active parent whose configuration it
-should remember. It has no schema, is excluded from active state identifiers,
-and is addressed only through `target.history`:
-
-```ts
-const States = Machine.states({
-  checkout: {
-    schema: Checkout,
-    initial: "shipping",
-    states: {
-      shipping: Shipping,
-      payment: {
-        schema: Payment,
-        initial: "cardEntry",
-        states: {
-          cardEntry: CardEntry,
-          verifying: Verifying
-        }
-      },
-      recent: { type: "history" },
-      exact: { type: "history", history: "deep" }
-    }
+const DocumentState = Schema.TaggedUnion({
+  Open: {
+    documentId: Schema.String,
+    draft: Schema.String
   },
-  support: Support
-})
-```
-
-Every history node needs a source-independent default for the first use. The
-default is a complete root snapshot containing the history owner:
-
-```ts
-checkout: {
-  history: {
-    recent: { default: () => initialCheckoutSnapshot },
-    exact: { default: () => initialCheckoutSnapshot }
+  SaveFailed: {
+    message: Schema.String
   }
-}
-```
-
-Target it without a value:
-
-```ts
-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
-value, so implement `initialize` only on paths required by shallow history:
-
-```ts
-payment: {
-  initialize: ({ state, builder }) =>
-    builder.from({ cardNumber: `attempt-${state.attempt}` })
-}
-```
-
-A nested default must include every ancestor above its owner and every region
-of any parallel ancestor. The containing branch is checked statically, so an
-unrelated root, a sibling compound branch, a direct-owner-only nested snapshot,
-or an incomplete parallel configuration is rejected. A canonical nested
-default looks like:
+})
 
-```ts
-Workspace: {
-  history: {
-    resume: {
-      default: ({ target }) =>
-        target.App.from({ workspaceId: "default" }, (app) =>
-          app.Workspace.from((workspace) => workspace.Editing.from()))
+const DocumentStates = Machine.states({
+  Closed: {},
+  Open: {
+    // Editing, Saving, and SaveFailed all need the document and draft.
+    schema: DocumentState.cases.Open,
+    initial: "Editing",
+    states: {
+      Editing: {},
+      Saving: {},
+      // Only this state owns an error message.
+      SaveFailed: DocumentState.cases.SaveFailed
     }
   }
-}
-```
-
-On first use from an inactive root, this complete configuration is entered. If
-a parallel ancestor is already active, unaffected active regions are retained.
-Once a history record exists, shallow or deep recorded restoration wins over
-the default.
-
-The machine's readiness type tracks missing defaults and shallow initializers.
-History is an overwriteable register, not a stack: restoration does not consume
-it, and the next parent exit replaces it. Entry actions and invokes run again;
-prior effects, machine instances, and timers are not rewound.
-
-## Choosing a target
-
-| Builder          | Use it when                                                                | What it preserves                                                                 |
-| ---------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `target.local`   | The destination is inside the nearest compound scope containing the source | The compound value, active ancestors, and unrelated parallel regions              |
-| `target.branch`  | The destination is elsewhere under the active top-level root               | Omitted current ancestor values and parallel regions                              |
-| `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`;
-unmentioned active regions are preserved.
-
-These describe configuration construction, not automatic process restart.
-Machine planning compares active paths and derives the actual exit and entry
-sets. A `target.full` result with the same active paths can update values without
-exiting shared states. To force the source to exit and enter again:
-
-```ts
-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
-narrowest builder that expresses the intended configuration change.
-
-Every state builder method has two construction forms:
-
-```ts
-target(decodedReady)
-target.from({ value: event.value })
-```
-
-The direct call accepts the schema's decoded `Type`. `.from` accepts its
-`~type.make.in`, so callers do not need to invoke a TaggedUnion case's `make`
-or instantiate a TaggedClass. The machine resolves `.from` with
-`schema.makeEffect` during planning. Constructor defaults and class identity
-are retained; refinement failures use `MachineSchemaDecodeError` at the state
-boundary rather than throwing synchronously. This applies recursively to
-initial, full, local, branch, compound, parallel, final, and `local.with`
-builders.
-
-If `{}` satisfies the schema's constructor input, omit it:
-
-```ts
-target.from()
-target.from((flow) => flow.Idle.from())
-```
-
-This shorthand also applies to schemas whose constructor fields are all
-optional or defaulted. It does not make required fields optional. Compound and
-parallel builders still require a callback selecting their active child or
-every active region. Omitted input is normalized to `{}` and still passes
-through `schema.makeEffect`, including refinements.
-
-## Reading state and structural ancestors
-
-`Machine.states` returns typed helpers:
-
-```ts
-States.get(snapshot, "Route.Ready")
-States.getWithParents(snapshot, "Route.Ready.Editing")
-States.getSnapshot(snapshot, "Route.Ready")
-States.matches(snapshot, "Route.Ready.Saving")
-```
-
-Snapshots returned by `getSnapshot` can be queried again with `get`,
-`getSnapshot`, or `matches`. Paths remain absolute and are restricted to the
-extracted snapshot and its descendants:
-
-```ts
-const ready = Option.getOrThrow(States.getSnapshot(snapshot, "Route.Ready"))
-States.matches(ready, "Route.Ready.Saving")
-```
-
-All paths are checked against the definition. `get` and `getWithParents` accept
-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
-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"]
-ancestors["Route.Ready.Editing"]
-```
-
-Do not guess short properties such as `ancestors.Ready`.
-
-### Inspecting the full transition configuration
-
-Event, `always`, and `onDone` transition contexts include a fully typed
-`snapshot`. It is the complete logical snapshot at the beginning of that
-microstep, before any selected transition is applied:
-
-```ts
-BufferReady: (to) =>
-  to.branches({
-    online: { target: to.local.Playing() },
-    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
-`States.getSnapshot` helpers for cross-region reads. Parallel transitions
-selected in one microstep receive the same capture. Synchronous handlers use
-that captured value and cannot consult live runtime state later.
-
-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
-pseudo-source, so the API does not fabricate a partial `Machine.Snapshot`.
-
-### State annotations
-
-Attach active-state metadata through Effect Schema:
-
-```ts
-const Saving = State.cases.Saving.annotate({
-  title: "Saving document",
-  description: "Persisting local changes to the server",
-  documentation: "https://docs.example.test/saving"
 })
 ```
 
-`Machine.stateNodes(machine)` returns the resolved annotation map. Choice and
-history definitions may declare an `annotations` object containing only
-`title`, `description`, and `documentation`. These values are descriptive;
-they cannot change behavior, identity, or targeting. Visualization may show a
-title, while the structural path remains authoritative.
-
-When sibling state payloads share fields, destructure away the source
-discriminator and construct the destination through its target builder:
-
-```ts
-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,
-and class identity. Prefer moving broadly shared data to the compound parent
-rather than copying it through every phase.
-
-## Planning, actions, raised events, and emissions
-
-A transition declares every possible branch and resolves the selected target
-synchronously:
-
-```ts
-Submit: (to) =>
-  to.branches({
-    valid: { target: to.local.Saving() },
-    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
-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
-destination while retaining queued commands, raised events, and emitted events.
+Do not copy `documentId` and `draft` into every child. Copies can disagree after
+a transition. Do not move `message` to `Open` either. That would allow an error
+message while `Editing` or `Saving` is active.
 
-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:
+## Put shared behavior on the lowest common ancestor
 
-```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
-enters again while its logical configuration is retained.
-
-Closed statechart and machine operations use `enqueue`:
+Hierarchy owns behavior as well as data. Define a transition on the lowest
+compound state whose children share it.
 
 ```ts
-Submit: (to) =>
-  to.local.Saving().resolve(({ target }, enqueue) => {
-    enqueue.emit(Emissions.SaveRequested())
-    return target.from()
+const DocumentEvents = Machine.events(
+  Schema.TaggedUnion({
+    Close: {}
   })
-```
-
-Declare emission constructors separately from machine inputs:
-
-```ts
-const Emissions = Machine.emittedEvents(SaveRequested, AuditRecorded)
-
-const definition = Machine.make({
-  events: Commands,
-  internalEvents: InternalEvents,
-  emittedEvents: Emissions,
-  // ...
-})
-```
-
-`enqueue.raise(...)` is a same-macrostep input to self. `enqueue.sendTo(...)`
-targets a machine mailbox and is processed later. `enqueue.emit(...)` is neither:
-it publishes a one-off outward notification. Observe it with
-`ref.emissions`, a hot non-replayed `Stream` that completes with the machine.
-`ref.changes` is stateful and begins with the current lifecycle snapshot.
-Use `Machine.prepare(machine)` to obtain `changes` and `emissions` before
-initialization. Subscribe to the desired stream and then evaluate
-`prepared.start`. `Machine.start(machine)` remains the one-step convenience
-when startup observation is unnecessary. Emissions are still never retained or
-replayed; state remains the representation for facts that must be retained.
-
-```ts
-const prepared = yield* Machine.prepare(machine)
-yield* prepared.emissions.pipe(
-  Stream.runForEach(handleEmission),
-  Effect.forkScoped({ startImmediately: true })
-)
-const ref = yield* prepared.start
-```
-
-`prepared.inspection` is a third, operational stream. It covers the root and
-its complete local ownership tree rather than one machine protocol. Subscribe
-before `prepared.start` when creation and initialization records matter:
-
-```ts
-const prepared = yield* Machine.prepare(machine)
-yield* prepared.inspection.pipe(
-  Stream.runForEach((event) => Console.log(event.sequence, event.subject.id, event._tag)),
-  Effect.forkScoped({ startImmediately: true })
 )
-const ref = yield* prepared.start
-```
-
-`Machine.Inspection.Event` is a closed union:
-
-- `Created`, `Initialized`, and `StartFailed` describe process startup;
-- `EventSent` records accepted mailbox delivery and `EventProcessed` records
-  the committed macrostep, including retained transitions, raised events,
-  emissions, commands, and entry/exit paths for each microstep;
-- `StateChanged` describes direct updates made by generic `Logic`;
-- `Emitted` records actual outward notification publication;
-- `ActivityStarted` and `ActivityStopped` describe Effect and timer invokes;
-- `Terminated` carries the final `done`, `error`, or `stopped` snapshot.
-
-Every record has a root-local `sequence`, `rootSessionId`, and `subject`.
-`deliveryId` correlates acceptance with processing; `macrostepId` correlates
-work caused by one statechart input. `source` is present for sends originating
-inside the inspected tree. `origin` distinguishes a root, state-owned invoke,
-and explicit spawn. Child machine and generic process protocols are erased to
-`unknown` because one stream can contain unrelated types.
-
-Inspection is hot, non-replayed, never fails, and completes with the prepared
-root. It is not a replacement for `changes`, which retains the latest lifecycle
-snapshot, or `emissions`, which remains the typed domain-notification channel.
-Invalid decoded inputs or emissions still fail the owning machine through its
-typed `MachineSchemaDecodeError`; inspection never turns validation into a
-throw or a stream failure.
-
-Session ids are deterministic and unique only inside one prepared local tree
-(`machine:0`, `machine:1`, ...). Do not persist them as globally unique actor
-ids. Distributed identity, placement, delivery, and request correlation belong
-to Effect Cluster and its entity, runner, shard, and request identifiers. A
-Cluster adapter may translate local inspection records into telemetry, but the
-core machine stream does not claim cross-node identity or ordering.
-
-For child-to-parent input, export a public builder protocol and reuse it at both
-composition boundaries:
 
-```ts
-export const ParentEvents = Machine.events(ChildFinished)
-
-const child = Machine.make({
-  events: ChildEvents,
-  parent: Machine.parent(ParentEvents),
-  // ...
+const DocumentMachine = Machine.make({
+  states: DocumentStates.states,
+  events: DocumentEvents,
+  initial: (to) => to.Closed()
 }).handle({
-  Working: {
+  Closed: {},
+  Open: {
     on: {
-      Finish: (to) =>
-        to.none.resolve(({ parent }, enqueue) => {
-          enqueue.sendTo(parent, ParentEvents.ChildFinished())
-        })
+      // All Open children close the document in the same way.
+      Close: (to) => to.full.Closed()
+    },
+    states: {
+      Editing: {},
+      Saving: {},
+      SaveFailed: {}
     }
   }
 })
-
-const parent = Machine.make({
-  events: Machine.events(ParentCommands, ParentEvents),
-  // ...
-})
-```
-
-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
-`AtomMachine.emissions(machineAtom)` for a root and
-`AtomMachine.childEmissions(childAtom)` for the currently active child. Both
-return streams requiring the corresponding `AtomRegistry`; emissions are not
-stored as atom state.
-
-Use `AtomMachine.inspection(machineAtom)` for root-scoped operational records.
-It installs the subscription before a fresh bridge starts, so initialization,
-owned children, and activities are visible without storing inspection records
-in atom state.
-
-For asynchronous validation or persistence, invoke an Effect or child machine
-from the state and handle its typed success or failure event in a later
-transition. This keeps `(state, event) => [nextState, commands]` synchronous.
-
-Plans have a discriminated completion result:
-
-```ts
-const planned = yield * Machine.plan(machine, state, event)
-if (planned.done) {
-  planned.output // schema-derived structural terminal union
-}
 ```
 
-When `done` is false, `output` is `undefined`. `MachineRef.join` and invoked
-child `onDone.output` use the same structural terminal union rather than adding
-an unconditional optional value. Output-less structural terminal paths
-contribute `undefined`; active atomic roots do not. Handler behavior can make
-the type conservative—for example, a root `onDone` transition can move away
-before that root becomes the machine's terminal result.
+The machine checks the deepest active state first, then its ancestors. Put a
+handler on a child when that state needs different behavior. Keep the shared
+case on the parent instead of repeating it in every child.
 
-`raise` queues an event for the same machine's current macrostep. `emit` queues
-an event for the parent. Both operations validate their schemas.
+## Treat events as the domain protocol
 
-## Public and internal event protocols
-
-`events` defines the protocol callers can send. `internalEvents` augments the
-union handled inside the statechart:
+An event tells the machine what was requested or what happened. Name events
+after domain actions and outcomes. Do not expose state setters such as
+`SetLoading` or `SetError`.
 
 ```ts
-const Events = Machine.events(
-  Schema.TaggedUnion({
-    Save: {}
-  })
-)
-const InternalEvents = Machine.internalEvents(
+export const CheckoutEvents = Machine.events(
   Schema.TaggedUnion({
-    Saved: { id: Schema.String },
-    SaveFailed: { message: Schema.String }
+    Submit: {},
+    Cancel: {}
   })
 )
 
-const definition = Machine.make({
-  states: States.states,
-  events: Events,
-  internalEvents: InternalEvents,
-  initial: (to) => to.Idle().resolve(({ target }) => target.from())
+const CheckoutMachine = Machine.make({
+  states: CheckoutStates.states,
+  events: CheckoutEvents,
+  initial: (to) => to.Editing()
+}).handle({
+  Editing: {
+    on: {
+      Submit: (to) => to.full.Submitting()
+    }
+  },
+  Submitting: {
+    on: {
+      // Cancel has meaning while work is in progress.
+      Cancel: (to) => to.full.Editing()
+    }
+  },
+  Complete: {}
 })
 ```
 
-Use the protocol-bound constructors at every machine delivery boundary:
+The sender requests `Submit`. The machine decides whether `Submit` has a
+transition in the current state. The sender does not choose `Submitting`.
 
-```ts
-yield* ref.send(Events.Save())
-enqueue.raise(InternalEvents.Saved({ id: "entry-1" }))
-```
+Carry facts that the machine cannot read from its current snapshot in the event
+payload. Do not copy current state into an event to help a handler reconstruct
+what the machine already knows.
 
-`Machine.events` exposes only public constructors;
-`Machine.internalEvents` exposes only machine-local constructors. Both flatten
-configured tagged unions and preserve tagged classes, finite discriminator
-unions, required inputs, and constructor defaults. A constructor returns an
-opaque instruction whose `_tag` is available for activity metadata. Its decoded
-fields are intentionally unavailable until the owning machine processes it.
+## Use parallel states only for independent modes
 
-Invalid constructor input fails `Machine.plan` or the running machine with
-`MachineSchemaDecodeError`; creating the instruction itself never performs
-schema validation. APIs that explicitly retain decoded events, such as manual
-model-testing scenarios or transport messages, can receive complete event
-objects directly.
-
-An open discriminator such as `_tag: Schema.String` cannot produce named
-constructors because its tag set is not finite. The schema still participates
-in the protocol; pass a complete event object at the delivery boundary.
-
-Use the exported utility types when another API must preserve the boundary:
+A compound state activates one direct child. A parallel state activates one
+child in every region. A parallel model therefore accepts the full product of
+those regions.
 
 ```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
-from `Machine.internalEvents`; outward notifications accept constructions from
-`Machine.emittedEvents`. The
-local planner and runtime intentionally share the complete decoder to support
-those internal deliveries, so JavaScript or `any` can bypass the local public
-distinction.
-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 `from.effect` for one-shot work. Lifecycle callbacks receive the typed
-Effect channels and can transition directly:
-
-```ts
-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 })))
+const ScreenStates = Machine.states({
+  Screen: {
+    type: "parallel",
+    states: {
+      connection: {
+        initial: "Online",
+        states: {
+          Online: {},
+          Offline: {}
+        }
+      },
+      panel: {
+        initial: "Closed",
+        states: {
+          Closed: {},
+          Open: {}
+        }
+      }
+    }
   }
 })
 ```
 
-The owning state scopes the child. Owner-driven interruption on state exit is
-normal cancellation and stale output is ignored. An Effect that defects or
-self-interrupts fails the parent. `onDone` is required when the output is not
-`never`; `onFailure` is required when the typed error is not `never`. Handlers
-are forbidden when their channel is `never`.
-
-The source may also be a function of the owning state's entry context when it
-needs `state`, `containingState`, `ancestors`, or the entry `event`. Source construction
-errors, defects, and interruption are machine failures rather than a second
-phase in `onFailure`.
-
-Use a Stream invocation for repeated values that are not themselves machine
-events. `onElement` maps each value into an owner transition, while `onDone`
-handles normal Stream completion and `onFailure` handles the typed Stream error:
-
-```ts
-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 })))
-  }
-})
-```
+This model permits all four combinations: online with a closed panel, online
+with an open panel, offline with a closed panel, and offline with an open panel.
 
-Element delivery is owner-scoped and backpressured: the Stream pulls again only
-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.
+If one combination would break a domain rule, do not repair it with a UI check
+or repeated cross-region conditions. Change the topology. A compound hierarchy
+can place a mode only under the parent where it is valid.
 
-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`.
+## Let states own running work
 
-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:
+Put asynchronous work on the state whose meaning requires that work. The
+machine starts the work when it enters the state and interrupts it when it exits.
+Handle expected success and failure as transitions.
 
 ```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 })))
-  }
+const LoadState = Schema.TaggedUnion({
+  Loading: { documentId: Schema.String },
+  Ready: { content: Schema.String },
+  Failed: { message: Schema.String }
 })
-```
 
-Inside `.handle(...)`, the constructor receives the owning machine's public
-input and declared parent protocol contextually. Sources and lifecycle handlers
-can send through `self` and `parent` without naming the definition:
+const LoadStates = Machine.states({
+  Idle: {},
+  Loading: LoadState.cases.Loading,
+  Ready: LoadState.cases.Ready,
+  Failed: LoadState.cases.Failed
+})
 
-```ts
-const machine = Machine.make({
-  events: Commands,
-  internalEvents: InternalEvents,
-  parent: Machine.parent(ParentEvents),
-  // ...
+const LoadMachine = Machine.make({
+  states: LoadStates.states,
+  events: Machine.events(),
+  initial: (to) => to.Idle()
 }).handle({
-  Saving: {
+  Idle: {},
+  Loading: {
     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)
-  }
+      from
+        .effect("load-document", ({ state }) => loadDocument(state.documentId))
+        .onDone((to) => to.full.Ready().resolve(({ output, target }) => target.from({ content: output })))
+        .onFailure((to) => to.full.Failed().resolve(({ error, target }) => target.from({ message: String(error) })))
+  },
+  Ready: {},
+  Failed: {}
 })
 ```
 
-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 its dedicated source selector:
-
-```ts
-machine.handle({
-  Waiting: {
-    invoke: (from) =>
-      from.timer("clear-status", "3 seconds")
-        .onDone((to) => to.full.Clear().resolve(({ target }) => target()))
-  }
-})
-```
+`loadDocument` may require Effect services. Those requirements remain on the
+implemented machine type, so the runtime must provide them when it starts the
+machine.
 
-The timer starts on state entry and is interrupted on exit. Its `onDone` is
-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.
+Do not start a promise inside a transition callback. A transition has no
+lifetime in which to own that work. A state does.
 
-## Invoked child statecharts
+## Keep transition decisions synchronous
 
-Create a complete child-statechart descriptor:
+A transition should choose the next state from the current snapshot and event.
+Use ordinary TypeScript conditions when one event has several valid outcomes.
 
 ```ts
-const Editor = Machine.child("editor", EditorMachine)
-```
-
-Invoke it from its owning state:
+const ReviewEvents = Machine.events(
+  Schema.TaggedUnion({
+    Evaluate: { score: Schema.Number }
+  })
+)
 
-```ts
-machine.handle({
-  Editing: {
-    invoke: (from) =>
-      from.child(Editor, { input: editorInput })
-        .onDone((to) => to.full.EditorDone().resolve(({ output, target }) => target.from({ output })))
-  }
+const ReviewMachine = Machine.make({
+  states: ReviewStates.states,
+  events: ReviewEvents,
+  initial: (to) => to.Pending()
+}).handle({
+  Pending: {
+    on: {
+      Evaluate: (to) =>
+        to
+          .branches({
+            accepted: { target: to.full.Accepted() },
+            rejected: { target: to.full.Rejected() }
+          })
+          .resolve(({ event, select }) =>
+            event.score >= 80
+              ? select.accepted.from()
+              : select.rejected.from()
+          )
+    }
+  },
+  Accepted: {},
+  Rejected: {}
 })
 ```
 
-Use `Editor` for:
-
-```ts
-Machine.sendTo(Editor, EditorEvent.Reset())
-parentRef.child(Editor)
-parentAtom.child(Editor)
-```
-
-Child emissions remain on the child's hot `emissions` stream; they are never
-delivered implicitly to the parent. A child sends an input explicitly with
-`enqueue.sendTo(parent, ParentEvents.Example())`. `onSnapshot`, `onDone`, and
-`onFailure` are direct parent transitions. Invoked child IDs must be unique
-while simultaneously active.
-
-Descriptors with the same id and machine identity address the same child, even
-when independently constructed. The descriptor objects themselves are not
-canonicalized. Prefer exporting one descriptor as the application boundary.
-Use the separate
-`Machine.childAddress<Event>(id)` constructor only for lower-level process
-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 fluent invocation definitions expose serializable ownership
-metadata:
-
-```ts
-Machine.activityDefinitions(machine)
-// [{ source: "Loading", id: "load-timeout", type: "timer",
-//    duration: "10s" }]
-```
-
-Child machines expose descriptor identity, never their runtime or
-implementation. Function-valued sources and durations are represented as
-dynamic because inspection must not evaluate user code.
-
-## AtomMachine and React
-
-`AtomMachine.make(machine, ...input)` works when the machine has no external
-service requirements. For an application runtime, the canonical form is to
-bind it once at the composition boundary:
-
-```ts
-const runtime = Atom.runtime(AppLayer)
-const machines = AtomMachine.bind(runtime)
-const machineAtom = machines.make(machine, input)
-```
-
-One bridge owns one machine instance per `AtomRegistry`. In React:
+Given the same snapshot and event, the handler should choose the same result.
+Do not read the clock, generate randomness, call a service, or await work while
+choosing a transition. Receive such values in an event or produce them through
+state-owned work first.
 
-1. Render a `RegistryProvider` from `@effect/atom-react`.
-2. Keep a component-owned bridge referentially stable, normally with
-   `useMemo`.
-3. Use scalar dependencies that define when the machine should restart.
-4. Expect a new bridge identity to create a new instance once mounted.
+## Test paths and invariants
 
-The root bridge shapes are:
-
-```ts
-machineAtom.state
-// Atom<AsyncResult<State, StartError>>
-
-machineAtom.result
-// Atom<AsyncResult<State, StartError | RuntimeError>>
-
-machineAtom.snapshot
-// Atom<AsyncResult<RuntimeSnapshot<State, RuntimeError, Output>, StartError>>
-```
-
-`state` remains a successful last-state value after a post-start runtime
-failure. Prefer `result` for ordinary fail-aware UI state. Use `snapshot` when
-the full lifecycle, completion output, cause, or stopped status matters.
-
-Use equality-aware selectors instead of repeating AsyncResult/Option unwrapping.
-Paths and selected values are inferred from the bridge snapshot, so do not pass
-the `DefinedStates` object:
-
-```ts
-AtomMachine.select(machineAtom, "Ready")
-AtomMachine.selectSnapshot(machineAtom, "Ready")
-AtomMachine.matches(machineAtom, "Ready.Saving")
-AtomMachine.selectChild(childAtom, "Editing")
-AtomMachine.selectSnapshotChild(childAtom, "Editing")
-AtomMachine.matchesChild(childAtom, "Editing")
-```
-
-`select` returns only the decoded state value. Use `selectSnapshot` when a
-component needs the selected node's compound or parallel child topology.
-
-Like ordinary Effect Atom combinators, each selector call returns a derived
-atom. Define it at a stable composition boundary or memoize it when constructing
-it inside a component.
-
-An invoked child bridge adds an inactivity axis. Keep the descriptor stable;
-the bridge uses Effect's `Atom.family` identity semantics:
-
-```ts
-const editorAtom = parentAtom.child(Editor)
-
-editorAtom.state
-// Atom<AsyncResult<Option<State>, StartError>>
-```
-
-`Option.none()` means the child is not currently active or has not become
-active yet. A child command while inactive fails with `ChildNotActiveError`.
-Use `AtomMachine.ChildMachineAtom<typeof Editor>` for a descriptor-based child prop,
-or `AtomMachine.ChildOf<typeof parentAtom, typeof Editor>` to infer the exact
-bridge from a parent.
-
-## Persistence
-
-Use `Machine.encodeSnapshot` and `Machine.decodeSnapshot` for validated logical
-statechart data. Persist machine identity and an application migration/version
-next to the encoded snapshot.
-
-The canonical resumption boundary is explicit:
-
-```ts
-const encoded = yield* Machine.encodeSnapshot(machine, snapshot)
-const decoded = yield* Machine.decodeSnapshot(machine, encoded)
-const ref = yield* Machine.resume(machine, decoded)
-```
-
-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
-state. It does not call the initial function, require machine input, or include
-initial-only failures and services in its Effect type.
-
-Encoding does not preserve:
-
-- running invokes or spawned children;
-- subscriptions, queued events, fibers, scopes, timers, or services;
-- the machine definition;
-- application migration metadata.
-
-`resume` reconstructs runtime ownership from logical state only:
-
-- no historical entry, transition, completion, eventless, raise, or emit work
-  is replayed;
-- completion and history records survive but do not retrigger `onDone`;
-- active-state invokes start once in ordinary ancestor/document order with
-  `Machine.InitialEvent`;
-- inline Effects restart, child machines start fresh from their normal initial
-  state, and timers restart their complete duration;
-- inactive invokes, spawned children, child snapshots, elapsed timer time, and
-  prior `RuntimeSnapshot` status/errors are not restored;
-- a final logical snapshot creates an immediately completed ref;
-- `resume` itself does not evaluate `always` or `onDone`, including transitions
-  newly enabled by a changed machine definition. Later events use ordinary
-  planning semantics.
-
-Use `AtomMachine.resume(machine, decoded)` or
-`AtomMachine.bind(runtime).resume(machine, decoded)` for the same contract in a
-lazy atom bridge. Registry disposal stops the fresh invokes and timers exactly
-as it does for `AtomMachine.make`.
-
-This is not durable runtime restoration. `ClusterMachine` has a separate
-checkpoint/planning contract and process-local restrictions; do not substitute
-`Machine.resume` for cluster recovery.
-
-## Testing machine semantics
-
-Import planner testing tools from the dedicated entrypoint:
+Test the statechart as a graph. Send domain events, inspect reached states, and
+state the rules that every trace must preserve. Do not duplicate the handler's
+branches inside the test.
 
 ```ts
 import { MachineTest } from "@typeonce/effect-machine/testing"
-```
-
-Use three distinct layers:
-
-1. `MachineTest.verify(machine, trace)` checks structural statechart and
-   planner lifecycle laws.
-2. `MachineTest.assertInvariants(machine, trace, laws)` checks application
-   semantics such as conservation, authorization, and exact state updates.
-3. Runtime command models check executed actions, invokes, timing, process
-   publication, and cancellation. Planner traces do not execute this work.
-
-Define semantic laws with a machine-bound builder so the callback receives the
-exact state and event types:
-
-```ts
-const invariant = MachineTest.invariants(machine)
-
-const laws = [
-  invariant.state("balance is never negative", ({ snapshot }) =>
-    snapshot.value.balance >= 0 || "negative balance"),
-  invariant.step("withdrawal is exact", ({ before, event, after }) =>
-    event._tag !== "Withdraw" ||
-    after.value.balance === before.value.balance - event.amount),
-  invariant.trace("all inputs were planned", ({ trace }) =>
-    trace.steps.length === trace.scenario.events.length)
-]
-```
-
-State laws observe settled states by default. Select `"microsteps"`, `"all"`,
-or `"final"` only when the law requires that evidence. A `when` condition with
-no matches is explicitly `untested`; use
-`require: { minObservations: 1 }` when the current trace must exercise it.
-Prefer `assertInvariants` inside FastCheck properties because it succeeds with
-`void`. Use `checkInvariants` when the test needs the per-law report.
-
-For systematic planner exploration, provide a finite abstraction explicitly:
-
-```ts
-const explored = yield * MachineTest.explore(machine, {
-  events: ({ snapshot }) => eventRepresentatives(snapshot),
-  stateKey: ({ snapshot }) => logicalStateKey(snapshot),
-  limits: { maxDepth: 20, maxStates: 1_000 },
-  invariants: laws
-})
-```
-
-The event callback returns concrete representatives, not schemas or
-arbitraries. Include meaningful boundary values based on the current snapshot.
-The key defines which snapshots are treated as equivalent; it must retain every
-piece of data that can change the future behavior being tested. A coarse key
-can make exploration finite but under-approximate behavior.
-
-`assertReachable` returns the shortest witness. `assertUnreachable` succeeds
-only when `explored.completeness` is `Complete`. Never interpret a truncated
-depth, state, or transition frontier as an unreachability proof. The explorer
-retains cycles as graph edges but does not enumerate every path around them;
-use a separate temporal/path model when a law depends on repeated traversal
-rather than logical-state reachability.
-
-Do not encode application invariants as guards merely to make them testable.
-Keep ordinary TypeScript branching in transition handlers unless a choice is
-part of the statechart topology. Invariants independently verify the resulting
-trace without changing production transition selection.
-
-### Live event causality
-
-Use a probe when a test must establish that one event was processed by a
-running statechart rather than merely accepted by its mailbox:
-
-```ts
-const ref = yield * Machine.start(machine)
-const probe = yield * MachineTest.probe(machine, ref)
-const step = yield * probe.sendAndAwait(event)
-```
-
-Inspect `step.before`, `step.after`, `step.plan`, `step.handled`, and
-`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
-commit, emissions, and invoke startup; it does not wait for an invoke or timer
-to complete. Application code should continue to use `MachineRef.send`.
-
-For generated runtime command sequences, select delivery behavior by name:
-
-```ts
-yield* MachineTest.runCausalCommands(probe, commands, causalModel)
-yield* MachineTest.runEnqueuedCommands(ref, commands, enqueueModel)
-```
-
-Prefer `runCausalCommands` for semantic and reference-model properties. Every
-accepted send produces a `SendProcessed` result containing its exact
-`ProbeStep`, including ignored and targetless events. A machine processing
-error fails that exact command and retains its checked prefix for shrinking.
-The next command does not begin until the submitted send's managed macrostep
-has completed.
-
-Use `probe.await.until(predicate)` in a causal model step only when the
-assertion also requires later timer, invoke, or child activity. It observes the
-current runtime snapshot before waiting for subsequent publications, so it
-does not miss work that completed immediately after the causal boundary.
-
-Use `runEnqueuedCommands` only when outstanding mailbox work is intentional,
-such as burst ordering and queue behavior. Its `RuntimeSynchronization`
-policies observe public snapshots but do not turn send acceptance into causal
-completion. Do not use the deprecated `runRuntimeCommands` name in new code;
-it is an alias for enqueue behavior and hides that important distinction.
-
-For semantic laws over live execution, bind runtime invariant constructors to
-the machine and use the law-oriented causal verifier:
-
-```ts
-const invariant = MachineTest.runtimeInvariants(machine)
-
-const laws = [
-  invariant.snapshot("balance never becomes negative", ({ snapshot }) =>
-    snapshot.state.value.balance >= 0
-  ),
-  invariant.command("stopped sends are rejected", ({ previous, result }) =>
-    previous?.result._tag !== "Stopped" || result._tag === "SendRejected"
+import { Effect, Option } from "effect"
+
+const testProgram = Effect.gen(function*() {
+  const define = MachineTest.invariants(CounterMachine)
+
+  const countNeverBecomesNegative = define.state(
+    "count never becomes negative",
+    ({ snapshot }) =>
+      !CounterStates.matches(snapshot, "Running") ||
+      CounterStates.get(snapshot, "Running").pipe(
+        Option.exists(({ count }) => count >= 0)
+      ) ||
+      "count became negative"
   )
-]
-
-yield* MachineTest.verifyCausalCommands(probe, commands, { invariants: laws })
-```
-
-Do not create a dummy model merely to run runtime laws. Continue to use
-`runCausalCommands` when an independent simplified model supplies exact
-expected results, then apply the same laws to its returned transcript with
-`assertRuntimeInvariants`. Conditional laws that must execute should declare
-`require.minObservations` so irrelevant generated commands cannot pass them
-vacuously.
-
-Use `assertPlannerRuntimeAgreement(machine, transcript)` only to check the
-managed runtime boundary against a fresh pure plan. It is not an independent
-business oracle and is intentionally an explicit operation rather than a
-generic conformance mode. Combine it with application runtime laws or a
-reference model when correctness of the expected behavior matters.
-
-## Common compiler errors
-
-### `initial` requires a static target
-
-Select the initial root separately from constructing its value:
-
-```ts
-initial: (to) => to.Idle().resolve(({ target }) => target.from())
-```
-
-### Invoked child expects events not accepted by the parent
-
-Export one parent-event protocol from the child boundary and compose it into
-the parent's public events:
-
-```ts
-export const ChildParentEvents = Machine.events(ChildFinished)
-
-// 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
-`events`. Handle the event as a child delivery or raised event; move it to
-`events` only if external callers should genuinely be allowed to send it.
-
-### Public and internal event tags overlap
-
-Give the cases distinct `_tag` values. The split is a protocol boundary, so one
-tag cannot be both externally sendable and machine-local.
-
-### Missing output implementation
-
-An output schema is a runtime contract, not an optional annotation. Add the
-corresponding nested handler:
-
-```ts
-Done: {
-  output: ({ state }) => state.value
-}
-```
-
-Keep `type: "final"` and `output: Schema...` in the state definition; do not
-repeat the final marker in this handler.
-
-### `type: "final"` is rejected by `handle`
-
-Move it to `Machine.states`. Definitions own statechart topology;
-handlers own behavior.
 
-### Parent property does not exist
-
-Use the structural ancestor's full path:
+  const trace = yield* MachineTest.run(CounterMachine, {
+    events: [
+      CounterEvents.Start(),
+      CounterEvents.Increment(),
+      CounterEvents.Increment()
+    ]
+  })
 
-```ts
-ancestors["Route.Ready"]
+  yield* MachineTest.verify(CounterMachine, trace)
+  yield* MachineTest.checkInvariants(CounterMachine, trace, [
+    countNeverBecomesNegative
+  ])
+})
 ```
 
-### Child descriptor types are unrelated
-
-Use the descriptor exported by the module that configured the child invocation.
-An independently created descriptor with the same id and machine identity also
-matches; the same id paired with a different machine remains a distinct child.
-
-### Child atom start error defaults to `unknown`
-
-`ChildMachineAtom<Child>` is suitable for a general boundary because its startup
-error defaults to `unknown`. Atoms created with an `AtomRuntime<R, E>` include
-`E` in their startup error type. Use `ChildOf<ParentAtom, Child>` to infer that
-exact channel from a parent instead of restating it manually.
-
-### Handler tree reaches a compiler instantiation limit
-
-`effect-machine` does not impose a fixed handler-tree depth. Inference follows
-the nested handler object until TypeScript reaches its normal, shape-dependent
-compiler resource or instantiation limits.
-
-## Unsupported and intentionally imperative features
-
-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 inline
-`invoke: (from) => from.timer(...)` chains for state-scoped timers. Do not
-invent undocumented state-node properties such as `guard`.
+Use pure planner traces for state and transition rules. Start a live machine
+and use `MachineTest.probe` when a test depends on timers, invoked work, raised
+events, or runtime scheduling.