@typeonce/effect-machine 0.3.0 → 0.4.0

package/README.md

@@ -8,11 +8,11 @@ Schema-first state machines and statecharts for Effect.
 ## Installation
 
 ```sh
-pnpm add @typeonce/effect-machine effect@4.0.0-beta.102
+pnpm add @typeonce/effect-machine effect@4.0.0-beta.107
 ```
 
 `effect` is an exact peer dependency, not a bundled runtime dependency.
-Consumers must install `effect@4.0.0-beta.102`. Upgrading this package may
+Consumers must install `effect@4.0.0-beta.107`. Upgrading this package may
 require upgrading Effect in lockstep; do not override the peer to another beta.
 
 ## Entrypoints
@@ -66,6 +66,10 @@ const Counter = Machine.make({
 })
 ```
 
+Handler objects mirror the state definition recursively. `effect-machine` does
+not impose a fixed handler-tree depth; inference continues until TypeScript's
+normal, shape-dependent compiler limits.
+
 `initial` is always a function. For a machine with an input schema, the
 initializer receives the decoded input.
 
@@ -126,6 +130,27 @@ const machine = Machine.make({
 })
 ```
 
+Construct reusable events with `Machine.event` when the schema is owned by the
+machine protocol:
+
+```ts
+const save = Machine.event(machine, Command.cases.Save)
+yield * ref.send(save)
+```
+
+The schema constructor runs once and the decoded value is trusted by that
+machine and definitions derived from it with `handle`. This avoids decoding a
+known event again on every delivery. A configured `Schema.TaggedUnion` can use
+either the union schema itself or one of its `cases`. Treat the returned event
+as immutable; sending it to an unrelated machine goes through that machine's
+normal decoder.
+
+Ordinary values remain valid and are decoded at every boundary:
+
+```ts
+yield * ref.send({ _tag: "Save" })
+```
+
 Handlers and machine logic see the complete union. Local public APIs such as
 `MachineRef.send`, `machineAtom.send`, and `Machine.plan` expose only `events`
 in TypeScript. The local planner and runtime still share the complete event
@@ -147,7 +172,7 @@ masquerade as an internal result.
 
 ## Statechart structure
 
-`Machine.defineStates` accepts atomic, compound, parallel, final, and history
+`Machine.defineStates` accepts atomic, compound, parallel, final, choice, and history
 nodes:
 
 ```ts
@@ -205,6 +230,65 @@ Put data on the narrowest state where it is valid. If several sibling phases
 share data, prefer storing it on their compound parent instead of copying it
 into every child state.
 
+### Choice states
+
+A choice is a transient, targetable decision point. Declare it with only
+`type: "choice"`; it has no schema, value, children, lifecycle actions, invoke,
+or event handlers. A choice is therefore absent from `StateIdentifier`, stable
+snapshots, configurations, and encoded snapshots.
+
+```ts
+const States = Machine.defineStates({
+  Flow: {
+    schema: State.cases.Flow,
+    initial: "Routing",
+    states: {
+      Routing: { type: "choice" },
+      Approved: State.cases.Approved,
+      Rejected: State.cases.Rejected
+    }
+  }
+})
+
+const machine = Machine.make({
+  states: States.states,
+  events: [Event],
+  initial: () =>
+    States.initial.Flow(
+      State.cases.Flow.make({ score: 80 }),
+      (flow) => flow.Routing()
+    )
+}).handle({
+  Flow: {
+    states: {
+      Routing: {
+        choice: {
+          targets: ["Flow.Approved", "Flow.Rejected"],
+          transition: ({ parent, target }) =>
+            parent.score >= 70
+              ? target.local.Approved(State.cases.Approved.make({}))
+              : target.local.Rejected(State.cases.Rejected.make({}))
+        }
+      }
+    }
+  }
+})
+```
+
+The resolver is ordinary TypeScript or an `Effect`. It receives the triggering
+lifecycle event, typed parent values, target builders, and the normal planning
+capabilities, but no `state` because the choice itself has no state value. Its
+declared `targets` are both a compile-time bound and inspectable graph edges.
+The resolver must return one of them; missing, malformed, or undeclared targets
+fail planning. Choice implementations are required before execution APIs are
+available.
+
+Initial, event, completion, always, history-default, and other choice
+transitions settle in the same macrostep. Chained choices use the normal
+infinite-transition limit. Choice nodes never run entry or exit actions and
+never become active while their resolution remains visible in traces and
+coverage as a `choice` transition trigger.
+
 ### History states
 
 A history pseudo-state remembers the last active configuration of its parent.
@@ -254,6 +338,38 @@ machine.handle({
 })
 ```
 
+A history default is source-independent. It must construct a complete root
+configuration containing the history owner, including every inactive ancestor
+above a nested owner and every required region of a parallel ancestor. For a
+top-level owner, its owner snapshot is already a complete root snapshot.
+
+For example, a history node owned by `App.Workspace` can be targeted from an
+unrelated `Closed` root and supplies the complete `App` configuration on first
+use:
+
+```ts
+Workspace: {
+  history: {
+    resume: {
+      default: ({ target }) =>
+        target.App(
+          State.cases.App.make({ workspaceId: "default" }),
+          (app) =>
+            app.Workspace(
+              State.cases.Workspace.make({}),
+              (workspace) =>
+                workspace.Editing(State.cases.Editing.make({}))
+            )
+        )
+    }
+  }
+}
+```
+
+The containing branch is enforced statically: unrelated roots, sibling
+compound branches that omit the owner, owner-only nested snapshots, and
+incomplete parallel configurations are rejected.
+
 Deep history restores every remembered descendant value. Shallow history
 restores the parent and direct-child values, then follows normal initial paths.
 Only compound or parallel states that shallow restoration can enter implicitly
@@ -314,25 +430,58 @@ Refresh: {
 keyed by full dotted paths, such as `parents["Form.Editing"]`; `context.parent`
 provides the immediate parent directly and is `undefined` at a root state.
 
-## Planning Effects and staged actions
+Event, eventless, and completion transition contexts also expose `snapshot`, a
+read-only view of the complete logical configuration captured at the beginning
+of that transition microstep. This lets one parallel region inspect a sibling
+without copying active-state facts into parent values:
+
+```ts
+BufferReady: ;
+;(({ snapshot, target }) =>
+  States.matches(snapshot, "Player.Network.Online")
+    ? target.local.Playing(State.cases.Playing.make({}))
+    : undefined)
+```
+
+All non-conflicting handlers selected together observe the same captured
+snapshot. Handlers are synchronous and cannot read mutable live runtime state
+later. `snapshot` is intentionally absent from entry, exit,
+invoke, and choice contexts. In particular, startup and chained choices may run
+before a complete stable snapshot containing their pseudo-source exists.
 
-An Effect returned by a transition handler is part of planning. Use it to read
-services, choose a target, raise an event, or emit an event. Wrap external side
-effects in `Machine.action`; actions are staged during planning and run by the
-managed runtime before it publishes the next state.
+Effect Schema annotations are the metadata source for active states. Annotate
+the schema itself; `Machine.stateNodes` exposes the resolved annotation map:
+
+```ts
+const Saving = State.cases.Saving.annotate({
+  title: "Saving document",
+  description: "Persisting local changes to the server"
+})
+```
+
+Schema-less choice and history nodes accept only descriptive `title`,
+`description`, and `documentation` annotations. Titles may be used as display
+labels, but structural paths remain the only identity and targeting mechanism.
+
+## Synchronous transitions and actor commands
+
+Transition, entry, exit, choice, initial, and history callbacks are synchronous.
+They select state and may enqueue only explicit statechart or actor operations:
+raise an internal event, emit to the parent, send to an invoked child, or stop a
+child. Arbitrary Effects are not accepted at this boundary.
 
 ```ts
 const handlers = {
-  Save: ({ target }) => Machine.action(writeAuditLog, target.local.Saving.from())
+  Save: ({ target }, enqueue) => {
+    enqueue.emit(new SaveRequested({}))
+    return target.local.Saving.from()
+  }
 }
 ```
 
-The one-argument form returns `void` after staging. The two-argument form
-returns its second argument, which avoids a generator when an action and the
-next target are the whole transition.
-
-If an action fails, the runtime keeps the previously published state and
-suppresses emissions from that plan.
+Use `Machine.invokeEffect`, `Machine.invoke`, or an invoked child machine for
+asynchronous work. Their results return to the parent as typed events, keeping
+the transition core deterministic and synchronous.
 
 `Machine.plan` and `Machine.planInitial` return a `done` discriminator. When
 `done` is `true`, `output` is the schema-derived structural terminal union;
@@ -407,6 +556,14 @@ Descriptors are matched by id and machine identity, so independently created
 descriptors for the same pair address the same child without a global cache.
 Exporting one descriptor remains the clearest module boundary.
 
+`Machine.activityDefinitions(machine)` inspects state-owned work without
+executing it. Static descriptors report their source path, lifecycle id, and
+kind. Timers also report normalized duration and emitted event tag;
+`invokeEffect` mappings are described as dynamic; invoked machines expose only
+safe child identity. A function-valued `invoke` factory is reported as dynamic
+and is never evaluated during inspection. The result is serializable and does
+not contain Effects, closures, services, or child runtimes.
+
 ## Reactivity
 
 `AtomMachine.make` creates a lazy bridge backed by one running machine per
@@ -465,8 +622,38 @@ contain the machine definition, machine version, services, subscriptions, or
 running child processes. Store machine identity and migration/version metadata
 alongside it.
 
+Resume a decoded logical snapshot explicitly:
+
+```ts
+const encoded = yield * Machine.encodeSnapshot(machine, snapshot)
+const decoded = yield * Machine.decodeSnapshot(machine, encoded)
+const ref = yield * Machine.resume(machine, decoded)
+```
+
+`resume` does not call `initial`, require machine input, or replay entry,
+transition, completion, eventless, raised-event, or emitted-event work that
+produced the snapshot. The decoded snapshot is the first published logical
+state. A final snapshot immediately yields a completed ref with its output.
+
+Resumption creates a fresh runtime. Invokes owned by active states start once in
+normal ancestor/document order and receive `Machine.InitialEvent` as their
+lifecycle event. `invokeEffect` runs again, invoked machines start from their
+own initial state, and `Machine.after` timers restart from their full declared
+duration. Spawned children, queued events, subscriptions, fibers, scopes,
+elapsed timer time, child snapshots, and prior `RuntimeSnapshot` status/errors
+are not restored. Completion and history metadata remain logical state and are
+not replayed. A changed machine definition does not cause `resume` itself to
+evaluate newly enabled `always` or `onDone` transitions.
+
+Reactive applications use `AtomMachine.resume(machine, decoded)` for a
+service-free machine or `AtomMachine.bind(runtime).resume(machine, decoded)`
+for a service-backed machine. These bridges have the same lazy one-runtime-per-
+registry ownership and disposal behavior as `AtomMachine.make`.
+
 `ClusterMachine` provides a separate persisted entity adapter. Its process-local
-restrictions and delivery guarantees are documented on that API.
+restrictions, checkpoint planning, and delivery guarantees are documented on
+that API. `Machine.resume` is logical resumption, not durable process or cluster
+restoration.
 
 ## Current limits