@typeonce/effect-machine 0.14.1 → 0.16.0

package/docs/agent-guide.md

@@ -35,15 +35,19 @@ currently coupled to the exact Effect peer version listed in its `package.json`.
 Use this order so inference has all schemas available when handlers are
 declared:
 
-1. Domain schemas used by state and event fields.
-2. Tagged schemas for states that own data.
-3. Tagged public-event, internal-event, parent-event, and emitted-event schemas.
-4. `Machine.defineStates`.
-5. `Machine.make`, including input, `events`, `internalEvents`, `parentEvents`,
-   `emittedEvents`, and the initial function.
-6. One or more `.handle(...)` calls.
-7. Child descriptors.
-8. Runtime, Atom, or Cluster adapters.
+1. Domain schemas used by state, and by event fields when they are shared.
+2. `Machine.states`, using a tagged state union and `.cases` when state
+   schemas need to be reused.
+3. `Machine.events`, `Machine.internalEvents`, `Machine.emittedEvents`, and
+   `parentEvents`; pass `Schema.TaggedUnion({...})` or tagged classes directly.
+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.
 
 `Schema.TaggedUnion` avoids one class declaration per case:
 
@@ -54,22 +58,23 @@ const State = Schema.TaggedUnion({
   Failed: { message: Schema.String }
 })
 
-const Event = Schema.TaggedUnion({
-  Save: {}
-})
-
-const InternalEvent = Schema.TaggedUnion({
-  Saved: { id: Schema.String },
-  SaveFailed: { message: Schema.String }
-})
-
-const States = Machine.defineStates(State.cases)
-const Events = Machine.events(Event)
-const InternalEvents = Machine.internalEvents(InternalEvent)
+const States = Machine.states(State.cases)
+export const Event = Machine.events(
+  Schema.TaggedUnion({
+    Save: {}
+  })
+)
+export const Internal = Machine.internalEvents(
+  Schema.TaggedUnion({
+    Saved: { id: Schema.String },
+    SaveFailed: { message: Schema.String }
+  })
+)
 ```
 
-Pass these descriptors to `Machine.make` and export `Events` instead of the raw
-event schema. Construct new state values through the target or initial
+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
@@ -118,12 +123,13 @@ 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, `after` for a timer,
-  `logic` for reusable process logic, and `child` for a complete child
+- 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. Use `definition.invoke({...})` when a
-  callback uses `self` or `parent`; the bound constructor preserves the
-  definition's exact public input and `parentEvents` protocols.
+  across sibling lifecycle handlers. Inside `.handle(...)`, `self` and `parent`
+  use the owning definition's exact public input and `parentEvents` protocols.
+  The bound `definition.invoke({...})` form is equivalent, not required.
 - Use `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
@@ -133,11 +139,88 @@ its extra control is required:
 
 ## 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.
+    }
+  }
+})
+```
+
+`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.
+
 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.defineStates({
+const States = Machine.states({
   Idle: {},
   Form: {
     initial: "Editing",
@@ -190,7 +273,7 @@ Use a compound state when exactly one child phase is active. It must declare an
 ```ts
 const FormState = Schema.TaggedUnion({ Saving: { draft: Schema.String } })
 
-const FormStates = Machine.defineStates({
+const FormStates = Machine.states({
   Form: {
     initial: "Editing",
     states: {
@@ -204,7 +287,7 @@ const FormStates = Machine.defineStates({
 Use a parallel state when every direct region is active:
 
 ```ts
-const ParallelStates = Machine.defineStates({
+const ParallelStates = Machine.states({
   Screen: {
     type: "parallel",
     states: {
@@ -231,13 +314,13 @@ 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.
 
-Use `type: "final"` for a terminal leaf in `Machine.defineStates`. A final
+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:
 
 ```ts
-const States = Machine.defineStates({
+const States = Machine.states({
   Done: {
     schema: State.cases.Done,
     type: "final",
@@ -311,7 +394,7 @@ should remember. It has no schema, is excluded from active state identifiers,
 and is addressed only through `target.history`:
 
 ```ts
-const States = Machine.defineStates({
+const States = Machine.states({
   checkout: {
     schema: Checkout,
     initial: "shipping",
@@ -455,7 +538,7 @@ through `schema.makeEffect`, including refinements.
 
 ## Reading state and structural ancestors
 
-`Machine.defineStates` returns typed helpers:
+`Machine.states` returns typed helpers:
 
 ```ts
 States.get(snapshot, "Route.Ready")
@@ -496,21 +579,14 @@ microstep, before any selected transition is applied:
 
 ```ts
 BufferReady: Machine.transition({
-  cases: (branch) => [
-    branch({
-      title: "online",
-      when: ({ snapshot }) =>
-        States.matches(snapshot, "Player.Network.Online")
-          ? Option.some(undefined)
-          : Option.none(),
-      target: (to) => to.local.Playing(),
-      resolve: ({ target }) => target.from()
-    })
-  ],
-  otherwise: {
-    target: (to) => to.none(),
-    resolve: () => undefined
-  }
+  branches: (to) => ({
+    online: { target: to.local.Playing() },
+    unchanged: { target: to.none() }
+  }),
+  resolve: ({ snapshot, select }) =>
+    States.matches(snapshot, "Player.Network.Online")
+      ? select.online.from()
+      : select.unchanged()
 })
 ```
 
@@ -566,30 +642,30 @@ synchronously:
 
 ```ts
 Submit: Machine.transition({
-  cases: (branch) => [
-    branch({
-      title: "valid",
-      when: ({ state }) => state.valid ? Option.some(state.draft) : Option.none(),
-      target: (to) => to.local.Saving(),
-      resolve: ({ match, target }) => target.from({ draft: match })
-    })
-  ],
-  otherwise: {
-    target: (to) => to.none(),
-    resolve: () => undefined
-  }
+  branches: (to) => ({
+    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
-must use `Machine.transition`. Each direct branch declares one `target`; a
-conditional transition declares ordered `cases` and a required `otherwise`.
-Construct each case with the locally supplied `branch` function. Every call
-independently infers its `when` match and target, so a transition may declare
-any number of heterogeneous cases without losing resolver inference. `when`
-returns `Option.some(match)` to select a case and expose `match` in its resolver.
-Selecting `to.none()` handles the transition without a destination, while
-retaining queued commands, raised events, and emitted events.
+must use `Machine.transition`. A direct transition declares one `target`. A
+branching transition declares every possible target in a named `branches`
+record, then uses ordinary TypeScript control flow in `resolve` to return one
+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.
+
+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.
@@ -764,8 +840,17 @@ an event for the parent. Both operations validate their schemas.
 union handled inside the statechart:
 
 ```ts
-const Events = Machine.events(Event)
-const InternalEvents = Machine.internalEvents(InternalEvent)
+const Events = Machine.events(
+  Schema.TaggedUnion({
+    Save: {}
+  })
+)
+const InternalEvents = Machine.internalEvents(
+  Schema.TaggedUnion({
+    Saved: { id: Schema.String },
+    SaveFailed: { message: Schema.String }
+  })
+)
 
 const definition = Machine.make({
   states: States.states,
@@ -852,6 +937,38 @@ needs `state`, `containingState`, `ancestors`, or the entry `event`. Source cons
 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
+invoke: Machine.invoke({
+  id: "broadcast-channel",
+  stream: () => messages,
+  onElement: {
+    target: Machine.targetless,
+    resolve: ({ element }, enqueue) => {
+      enqueue.raise(Events.MessageReceived({ message: element }))
+    }
+  },
+  onDone: { target: Machine.targetless },
+  onFailure: Machine.transition({
+    target: (to) => to.full.Disconnected(),
+    resolve: ({ error, target }) => target.from({ error })
+  })
+})
+```
+
+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.
+
+The direct `{ target: Machine.targetless, resolve }` shorthand is available
+when a transition only enqueues commands. It is non-reentering and the resolver
+must return `undefined`. Keep `Machine.transition(...)` for full state selection,
+named branches, or reentry.
+
 When a source function reads `state`, `containingState`, `ancestors`, or the entry `event`,
 `Machine.invoke` infers that owner context and the returned Effect's output,
 error, and service channels together. No return annotation is needed:
@@ -871,29 +988,30 @@ invoke: Machine.invoke({
 })
 ```
 
-The standalone constructor cannot know the owning machine's input protocols,
-so its `self` and `parent` references are non-sendable. When a source sends
-through either reference, use the owning definition's bound constructor:
+Inside `.handle(...)`, the constructor receives the owning machine's public
+input and `parentEvents` protocols contextually. Sources and lifecycle handlers
+can send through `self` and `parent` without naming the definition:
 
 ```ts
-const definition = Machine.make({
+const machine = Machine.make({
   events: Commands,
   internalEvents: InternalEvents,
   parentEvents: ParentEvents,
   // ...
-})
-
-const machine = definition.handle({
+}).handle({
   Saving: {
-    invoke: definition.invoke({
+    invoke: Machine.invoke({
       id: "notify-parent",
-      effect: ({ parent }) =>
-        parent === undefined
-          ? Effect.void
-          : parent.send(ParentEvents.SaveStarted()),
+      effect: () => saveDocument,
       onDone: Machine.transition({
         target: (to) => to.none(),
-        resolve: () => undefined
+        resolve: ({ parent, self }, enqueue) => {
+          enqueue.sendTo(self, Commands.Save())
+          if (parent !== undefined) {
+            enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
+          }
+          return undefined
+        }
       }),
       onFailure: Machine.transition({
         target: (to) => to.none(),
@@ -904,8 +1022,9 @@ const machine = definition.handle({
 })
 ```
 
-A direct `invoke: { ... }` object remains available when lifecycle handlers do
-not need source-derived context.
+The machine-bound `definition.invoke(...)` form remains equivalent when the
+definition is already named. A direct `invoke: { ... }` object remains available
+when lifecycle handlers do not need source-derived context.
 
 A cancellable timer uses the same object:
 
@@ -1314,7 +1433,7 @@ repeat the final marker in this handler.
 
 ### `type: "final"` is rejected by `handle`
 
-Move it to `Machine.defineStates`. Definitions own statechart topology;
+Move it to `Machine.states`. Definitions own statechart topology;
 handlers own behavior.
 
 ### Parent property does not exist

package/package.json

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