@typeonce/effect-machine 0.14.1 → 0.15.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
@@ -121,9 +126,9 @@ its extra control is required:
 - Use one invocation object: `effect` for one-shot work, `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 +138,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 +272,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 +286,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 +313,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 +393,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 +537,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")
@@ -764,8 +846,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,
@@ -871,29 +962,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 +996,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 +1407,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.15.0",
   "description": "Schema-first state machines and statecharts for Effect",
   "author": "Sandro Maglione",
   "repository": {