@typeonce/effect-machine 0.12.0 → 0.13.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
@@ -227,6 +227,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.
 
@@ -326,7 +376,7 @@ State-scoped work starts on entry and is interrupted on exit:
 Loading: {
   invoke: Machine.invoke({
     id: "save-document",
-    effect: saveDocument,
+    effect: () => saveDocument,
     onDone: ({ output, target }) => target.full.Saved({ id: output.id }),
     onFailure: ({ error, target }) => target.full.Failed({ message: String(error) })
   })
@@ -393,8 +443,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