@typeonce/effect-machine 0.10.0 → 0.12.0

package/README.md

@@ -10,6 +10,27 @@ 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
@@ -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,23 +207,33 @@ 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. Because `Machine.start`
-returns only after initialization, startup emissions are not observable from
-the returned ref; represent startup facts in state when they must be retained.
+lifecycle snapshot and then follows later changes. Use `Machine.prepare` when
+an observer must be installed before initial-entry actions run:
 
 ```ts
-const next = ref.emissions.pipe(Stream.take(1), Stream.runHead)
+const prepared = yield * Machine.prepare(machine)
+
+yield * prepared.emissions.pipe(
+  Stream.runForEach(handleEmission),
+  Effect.forkScoped({ startImmediately: true })
+)
+
+const ref = yield * prepared.start
 ```
 
+`Machine.start(machine)` remains the one-step convenience for callers that do
+not observe startup emissions. Preparation does not retain or replay an
+emission: the observer is simply subscribed before initialization begins.
+
 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
@@ -234,15 +265,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
 
@@ -322,6 +356,35 @@ invoke: Machine.invoke({
 })
 ```
 
+The standalone `Machine.invoke(...)` constructor does not know the owning
+definition, so its `self` and `parent` references are non-sendable. When an
+invocation callback sends through either reference, construct it through the
+owning definition so those references use its exact public input and
+`parentEvents` protocols:
+
+```ts
+const definition = Machine.make({
+  events: Commands,
+  internalEvents: InternalEvents,
+  parentEvents: ParentEvents
+  // ...
+})
+
+const machine = definition.handle({
+  Saving: {
+    invoke: definition.invoke({
+      id: "notify-parent",
+      effect: ({ parent }) =>
+        parent === undefined
+          ? Effect.void
+          : parent.send(ParentEvents.SaveStarted()),
+      onDone: ({ target }) => target.none(),
+      onFailure: ({ target }) => target.none()
+    })
+  }
+})
+```
+
 A direct `invoke: { ... }` object is also supported when its lifecycle handlers
 do not need source-derived context. Reuse one exported
 `Machine.child(id, machine)` descriptor for invocation, `sendTo`, and child
@@ -362,7 +425,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