@typeonce/effect-machine 0.11.0 → 0.13.0

package/README.md

@@ -10,10 +10,31 @@ cluster adapter.
 > This is early-release software. Its API may change, and each release targets
 > one exact Effect beta.
 
+## Design principles
+
+- **Type-safe by construction:** reject invalid protocols, compositions, and
+  capabilities at compile time where possible, and preserve typed Effect
+  failures at runtime.
+- **Explicit and opinionated:** give different semantics different names and
+  contracts. Builders and inference remove ceremony without making behavior
+  depend on ambiguous omissions.
+- **Readable models:** keep schemas, topology, behavior, and effects concise
+  enough that a human can understand the complete model from its definition.
+- **Effect-native:** design toward eventual inclusion in Effect core and follow
+  its API shape, module boundaries, ownership, and failure conventions.
+
+The package is pre-1.0: a clearer or safer long-term API takes priority over
+backward compatibility. Breaking changes use minor releases, compatible fixes
+use patch releases, and compatibility aliases are not added by default.
+
+The core machine model remains local. Distributed identity, placement,
+transport, routing, delivery, and remote lifecycle semantics belong to Effect
+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
@@ -136,7 +157,7 @@ data, put it on their compound parent.
 
 ### Separate inputs, raised events, and emissions
 
-`events` is the public actor-input protocol. Events raised to the same machine
+`events` is the public machine-input protocol. Events raised to the same machine
 belong in `internalEvents`. Ephemeral outward notifications have their own
 `emittedEvents` protocol:
 
@@ -186,7 +207,7 @@ protocols but cannot expose a finite constructor set; pass a complete event
 object to `send` or `Machine.plan` for those events.
 
 `ref.emissions` is a hot `Stream`: it publishes only notifications produced
-after subscription, replays nothing, and completes when the actor terminates.
+after subscription, replays nothing, and completes when the machine terminates.
 Snapshots remain separate and stateful: `ref.changes` begins with the current
 lifecycle snapshot and then follows later changes. Use `Machine.prepare` when
 an observer must be installed before initial-entry actions run:
@@ -206,13 +227,63 @@ 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.
 
-### Send explicitly between actors
+### Send explicitly between machines
 
-`raise` targets the current machine in the same macrostep. `sendTo` targets an
-actor mailbox and is processed later. A child declares the subset of parent
+`raise` targets the current machine in the same macrostep. `sendTo` targets a
+machine mailbox and is processed later. A child declares the subset of parent
 inputs it may send with `parentEvents`:
 
 ```ts
@@ -244,15 +315,18 @@ const ParentInputs = Machine.events(Start, ParentEvents)
 The same child remains isolated and may be started as a root, where `parent` is
 `undefined`. When `Child` is invoked, the parent definition must accept every
 event in `parentEvents`; otherwise `.handle(...)` is a compile-time error.
-Inside the child, the parent reference accepts only those declared events.
-`emit` never sends to the parent: it only publishes on the emitting actor's
+Inside the child, the parent target accepts only those declared events.
+`emit` never sends to the parent: it only publishes on the emitting machine's
 `emissions` stream.
 
 Every handler also receives `self`, which can be targeted with `sendTo` when a
 later mailbox turn is required. Use `raise` instead for same-macrostep work.
+Both `self` and `parent` are minimal `Machine.MachineTarget<Event>` values. The
+shared `Machine.MachineReferences<InputEvents, ParentEvents>` context keeps
+their input protocols separate without exposing snapshot or lifecycle APIs.
 Structural state values use distinct names: `containingState` is the immediate
 valued state in the same statechart, while `ancestors` maps valued ancestor
-paths. `parent` always means the owning actor reference.
+paths. `parent` always means the owning machine target.
 
 ### Choose the target by scope
 
@@ -302,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) })
   })
@@ -369,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
 
@@ -401,7 +477,7 @@ const childEmissions = AtomMachine.childEmissions(counterAtom.child(Worker))
 ```
 
 These streams require the same `AtomRegistry`, follow the currently mounted
-actor instance, and do not replay notifications from an earlier subscription
+machine instance, and do not replay notifications from an earlier subscription
 or child instance.
 
 ## Persistence