@typeonce/effect-machine 0.12.0 → 0.14.0

package/README.md

@@ -34,7 +34,7 @@ Cluster and are exposed only through explicit integration boundaries.
 ## Install
 
 ```sh
-pnpm add @typeonce/effect-machine effect@4.0.0-rc.108
+pnpm add @typeonce/effect-machine effect@4.0.0-rc.109
 ```
 
 `effect` is an exact peer dependency. Install the version above and upgrade it
@@ -66,19 +66,31 @@ const CounterDefinition = Machine.make({
   id: "Counter",
   states: States.states,
   events: CounterEvent,
-  initial: () => States.initial.Idle.from()
+  initial: {
+    target: (to) => to.Idle(),
+    resolve: ({ target }) => target.from()
+  }
 })
 
 const Counter = CounterDefinition.handle({
   Idle: {
     on: {
-      Start: ({ target }) => target.full.Running.from({ count: 0 })
+      Start: Machine.transition({
+        target: (to) => to.full.Running(),
+        resolve: ({ target }) => target.from({ count: 0 })
+      })
     }
   },
   Running: {
     on: {
-      Increment: ({ state, target }) => target.full.Running.from({ count: state.count + 1 }),
-      Stop: ({ target }) => target.full.Idle.from()
+      Increment: Machine.transition({
+        target: (to) => to.full.Running(),
+        resolve: ({ state, target }) => target.from({ count: state.count + 1 })
+      }),
+      Stop: Machine.transition({
+        target: (to) => to.full.Idle(),
+        resolve: ({ target }) => target.from()
+      })
     }
   }
 })
@@ -111,8 +123,7 @@ Use this order to preserve inference and keep boundaries explicit:
 Use `.from(...)` when constructing a new state from fields:
 
 ```ts
-target.local.Saving.from({ draft: event.draft })
-States.initial.Form.from({ draft: "" }, (form) => form.Editing.from())
+target.from({ draft: event.draft })
 ```
 
 The machine runs these inputs through the state schema while planning. Schema
@@ -124,10 +135,12 @@ When sibling states share fields, remove the source discriminator and pass the
 remaining fields through the target schema:
 
 ```ts
-Submit: ;
-;(({ state, target }) => {
-  const { _tag: _, ...fields } = state
-  return target.local.Saving.from({ ...fields, attempt: 1 })
+Submit: Machine.transition({
+  target: (to) => to.local.Saving(),
+  resolve: ({ state, target }) => {
+    const { _tag: _, ...fields } = state
+    return target.from({ ...fields, attempt: 1 })
+  }
 })
 ```
 
@@ -144,7 +157,10 @@ const States = Machine.defineStates({
   }
 })
 
-States.initial.Form.from((form) => form.Editing.from())
+initial: {
+  target: (to) => to.Form.initial(),
+  resolve: ({ target }) => target((form) => form.Editing.from())
+}
 ```
 
 Schema-less states remain active, targetable, matchable, and visible through
@@ -181,7 +197,10 @@ const definition = Machine.make({
   events: CommandEvent,
   internalEvents: InternalEvent,
   emittedEvents: Emissions,
-  initial: () => States.initial.Idle.from()
+  initial: {
+    target: (to) => to.Idle(),
+    resolve: ({ target }) => target.from()
+  }
 })
 ```
 
@@ -227,6 +246,56 @@ const ref = yield * prepared.start
 not observe startup emissions. Preparation does not retain or replay an
 emission: the observer is simply subscribed before initialization begins.
 
+### Inspect a live machine tree
+
+`Machine.prepare(machine).inspection` is the operational counterpart to the
+domain-facing `changes` and `emissions` streams. It observes the prepared root
+and every locally owned child, `Logic` process, Effect, and timer in one total
+publication order:
+
+```ts
+const prepared = yield * Machine.prepare(checkout)
+
+yield * prepared.inspection.pipe(
+  Stream.runForEach((record) => Console.log(record.sequence, record.subject.id, record._tag)),
+  Effect.forkScoped({ startImmediately: true })
+)
+
+const checkoutRef = yield * prepared.start
+```
+
+For a handled input, the stream may expose values such as:
+
+```ts
+{ _tag: "EventSent", sequence: 2, deliveryId: 0,
+  subject: { id: "checkout", sessionId: "machine:0", kind: "Machine" },
+  source: undefined, target: { id: "checkout", sessionId: "machine:0" },
+  event: CheckoutEvents.Submit(), causedBy: undefined }
+
+{ _tag: "EventProcessed", sequence: 4, macrostepId: 0,
+  deliveryId: 0, handled: true, configurationChanged: true,
+  before: { status: "active", state: /* ... */ },
+  after: { status: "active", state: /* ... */ }, microsteps: [/* ... */] }
+```
+
+The closed `Machine.Inspection.Event` union also reports creation,
+initialization and startup failure, direct `Logic` state updates, outward
+emissions, Effect/timer activity lifecycles, and termination. Records erase
+unrelated child protocols to `unknown`; application-level observation remains
+typed through each reference's `changes` and `emissions`.
+
+The stream is hot, non-replayed, never fails, and completes after the root
+terminates. Subscribe before `prepared.start` to capture initialization. Local
+session ids are unique only inside that prepared ownership tree: `machine:0`
+is the root and later ids identify its descendants. They are intentionally not
+distributed identities. Cluster placement, routing, and correlation continue
+to use Cluster entity, runner, and request identities at the integration
+boundary.
+
+`AtomMachine.inspection(machineAtom)` provides the same root-scoped stream and
+starts a fresh atom-backed machine only after its inspection subscription is
+installed.
+
 Invalid event and emission constructions fail the machine with a typed
 `MachineSchemaDecodeError`; they do not throw from the constructor call.
 
@@ -243,16 +312,22 @@ const child = Machine.make({
   states: ChildStates.states,
   events: ChildEvents,
   parentEvents: ParentEvents,
-  initial: () => ChildStates.initial.Working.from()
+  initial: {
+    target: (to) => to.Working(),
+    resolve: ({ target }) => target.from()
+  }
 }).handle({
   Working: {
     on: {
-      Finish: ({ parent, target }, enqueue) => {
-        if (parent !== undefined) {
-          enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
+      Finish: Machine.transition({
+        target: (to) => to.full.Done(),
+        resolve: ({ parent, target }, enqueue) => {
+          if (parent !== undefined) {
+            enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
+          }
+          return target.from()
         }
-        return target.full.Done.from()
-      }
+      })
     }
   },
   Done: {}
@@ -326,9 +401,15 @@ State-scoped work starts on entry and is interrupted on exit:
 Loading: {
   invoke: Machine.invoke({
     id: "save-document",
-    effect: saveDocument,
-    onDone: ({ output, target }) => target.full.Saved({ id: output.id }),
-    onFailure: ({ error, target }) => target.full.Failed({ message: String(error) })
+    effect: () => saveDocument,
+    onDone: Machine.transition({
+      target: (to) => to.full.Saved(),
+      resolve: ({ output, target }) => target.from({ id: output.id })
+    }),
+    onFailure: Machine.transition({
+      target: (to) => to.full.Failed(),
+      resolve: ({ error, target }) => target.from({ message: String(error) })
+    })
   })
 }
 
@@ -336,7 +417,10 @@ Waiting: {
   invoke: Machine.invoke({
     id: "save-timeout",
     after: "3 seconds",
-    onDone: ({ target }) => target.full.Failed({ message: "Timed out" })
+    onDone: Machine.transition({
+      target: (to) => to.full.Failed(),
+      resolve: ({ target }) => target.from({ message: "Timed out" })
+    })
   })
 }
 ```
@@ -351,8 +435,14 @@ for state-dependent Effects:
 invoke: Machine.invoke({
   id: "load-document",
   effect: ({ state }) => loadDocument(state.documentId),
-  onDone: ({ output, target }) => target.full.Ready({ document: output }),
-  onFailure: ({ error, target }) => target.full.Failed({ message: error.message })
+  onDone: Machine.transition({
+    target: (to) => to.full.Ready(),
+    resolve: ({ output, target }) => target.from({ document: output })
+  }),
+  onFailure: Machine.transition({
+    target: (to) => to.full.Failed(),
+    resolve: ({ error, target }) => target.from({ message: error.message })
+  })
 })
 ```
 
@@ -378,8 +468,14 @@ const machine = definition.handle({
         parent === undefined
           ? Effect.void
           : parent.send(ParentEvents.SaveStarted()),
-      onDone: ({ target }) => target.none(),
-      onFailure: ({ target }) => target.none()
+      onDone: Machine.transition({
+        target: (to) => to.none(),
+        resolve: () => undefined
+      }),
+      onFailure: Machine.transition({
+        target: (to) => to.none(),
+        resolve: () => undefined
+      })
     })
   }
 })
@@ -393,8 +489,10 @@ lookup.
 `onDone` is required for a non-`never` output, and `onFailure` is required for a
 non-`never` typed error; each handler is omitted when its channel is `never`.
 Defects, interruption, and source-construction failures terminate the owning
-runtime. `effect: Effect.sleep(...)` is valid, but `after` keeps timers explicit
-and makes static durations visible through activity inspection.
+runtime. Effect sources are always factories evaluated when their state is
+entered. Use `effect: () => Effect.sleep(...)` for a generic Effect, while
+`after` keeps timers explicit and makes static durations visible through
+activity inspection.
 
 ## Reactivity
 
@@ -449,8 +547,10 @@ encoded snapshot.
 The testing entrypoint provides complementary layers:
 
 - `MachineTest.run` and `verify` inspect pure planner traces;
+- `coverage` reports exact transition-definition and conditional-branch hits;
 - invariants and generated scenarios check application laws;
-- `explore` performs bounded breadth-first state-space exploration;
+- `explore` performs bounded breadth-first state-space exploration and retains
+  exact transition-definition and branch coverage for every plan it computes;
 - `probe` causally acknowledges live runtime commands;
 - runtime command models cover timers, invokes, bursts, and scheduling.