@typeonce/effect-machine 0.3.0 → 0.5.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
@@ -21,10 +21,11 @@ require upgrading Effect in lockstep; do not override the peer to another beta.
 import { Machine } from "@typeonce/effect-machine"
 import { ClusterMachine } from "@typeonce/effect-machine/cluster"
 import { AtomMachine } from "@typeonce/effect-machine/reactivity"
+import { MachineTest } from "@typeonce/effect-machine/testing"
 ```
 
 Each ESM entrypoint is independent and tree-shakeable. Importing the root does
-not load the reactivity or cluster adapters.
+not load the reactivity, cluster, or testing modules.
 
 ## First machine
 
@@ -66,6 +67,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 +131,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 +173,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 +231,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 +339,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 +431,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)
+```
 
-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.
+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.
+
+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 +557,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 +623,243 @@ 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.
+
+## Property-based semantic invariants
+
+`MachineTest.verify` checks statechart structure and planner lifecycle laws.
+Application semantics belong in invariants that can be reused across generated
+scenarios and, in future, bounded exploration:
+
+```ts
+import { MachineTest } from "@typeonce/effect-machine/testing"
+import { Effect } from "effect"
+
+const invariant = MachineTest.invariants(accountMachine)
+const laws = [
+  invariant.state(
+    "balance is never negative",
+    ({ snapshot }) =>
+      snapshot.value.balance >= 0 ||
+      `negative balance: ${snapshot.value.balance}`
+  ),
+  invariant.step(
+    "withdrawal removes exactly its amount",
+    ({ before, event, after }) =>
+      event._tag !== "Withdraw" ||
+      after.value.balance === before.value.balance - event.amount
+  )
+]
+
+const generated = MachineTest.scenarios(accountMachine, {
+  minEvents: 0,
+  maxEvents: 30
+})
+
+it.effect.prop(
+  "preserves account laws",
+  { scenario: generated.arbitrary },
+  ({ scenario }) =>
+    MachineTest.run(accountMachine, scenario).pipe(
+      Effect.tap((trace) => MachineTest.verify(accountMachine, trace)),
+      Effect.flatMap((trace) => MachineTest.assertInvariants(accountMachine, trace, laws))
+    )
+)
+```
+
+State invariants observe settled startup and public-event states by default.
+Set `observe` to `"microsteps"`, `"all"`, or `"final"` for a different scope.
+Use `when` for conditional laws. A condition with no matches is reported as
+`untested`; add `require: { minObservations: 1 }` when a particular trace must
+exercise it. `checkInvariants` returns this report, while `assertInvariants`
+returns `void` for direct use in property tests. Failures retain the complete
+shrunk trace and precise event, microstep, configuration, and observation
+location.
+
+These APIs inspect planner evidence. Staged action effects, invokes, timing,
+and process scheduling require the runtime command-model APIs instead.
+
+Use bounded exploration when random scenarios should be complemented by a
+systematic search over concrete event representatives:
+
+```ts
+const explored = yield * MachineTest.explore(accountMachine, {
+  events: ({ snapshot }) => [
+    new Deposit({ amount: 1 }),
+    new Withdraw({ amount: snapshot.value.balance }),
+    new Withdraw({ amount: snapshot.value.balance + 1 })
+  ],
+  stateKey: ({ snapshot }) => `${snapshot.value._tag}:${snapshot.value.balance}`,
+  limits: {
+    maxDepth: 20,
+    maxStates: 1_000,
+    maxTransitions: 10_000
+  },
+  invariants: laws
+})
+
+const rejected = yield * MachineTest.assertReachable(
+  explored,
+  "insufficient funds rejection",
+  ({ configuration }) => configuration.includes("Rejected")
+)
+
+console.log(rejected.trace.scenario.events) // shortest witness
+```
+
+Exploration is breadth-first, so each retained node owns its shortest trace.
+It is exhaustive only for the concrete events returned by `events` and the
+equivalence relation defined by `stateKey`. Equal keys intentionally collapse
+snapshots and only the first representative is expanded. Results distinguish
+`Complete` from `Truncated` and retain the depth, state, or transition frontier
+that hit a limit. An unreachability assertion succeeds only for a complete
+result; otherwise it fails as inconclusive. Cycles are retained as graph edges,
+but exploration does not enumerate every cyclic path. Invariants are checked
+on startup and on each planned edge extending a node's shortest trace.
+
+## Causal runtime probes
+
+Pure traces do not execute invokes or the managed runtime. When a test needs to
+prove that one live event has actually left the mailbox, attach a testing-only
+probe to a statechart reference:
+
+```ts
+const ref = yield * Machine.start(machine)
+const probe = yield * MachineTest.probe(machine, ref)
+
+const step = yield * probe.sendAndAwait(new CancelRequested({}))
+
+assert.strictEqual(step.handled, false)
+assert.deepStrictEqual(step.before, step.after)
+```
+
+`sendAndAwait` completes after that event's synchronous macrostep and managed
+commit work. It also completes for ignored events, which publish no snapshot
+and therefore cannot be synchronized by waiting for `ref.changes`.
+
+The step retains the exact runtime plan, before/after logical snapshots, and
+whether the event was handled or changed/reentered the active configuration.
+It does not wait for timers or invoked processes to finish. Production code
+continues to use enqueue-only `ref.send`; probes are exported only from the
+separate testing entry point.
+
+For command-model and property tests, choose the delivery semantics explicitly.
+`runCausalCommands` requires a probe and completes every accepted send before
+checking it or starting the next command:
+
+```ts
+const transcript = yield * MachineTest.runCausalCommands(
+  probe,
+  commands,
+  {
+    initialModel,
+    transition: (model, command) =>
+      Effect.succeed({
+        model: updateModel(model, command),
+        expected: expectedResult(model, command)
+      }),
+    assert: ({ actual, expected }) =>
+      Effect.sync(() => {
+        if (actual.result._tag === "SendProcessed") {
+          assert.deepStrictEqual(actual.result.step.after, expected.snapshot)
+          assert.strictEqual(actual.result.step.handled, expected.handled)
+        }
+      })
+  }
+)
+```
+
+A causal model step needs no synchronization policy. Use the probe-bound
+`probe.await.until(...)` only for later asynchronous work such as a timer,
+invoke result, or child delivery. The predicate sees the exact runtime snapshot
+type. `actual.awaited` retains every snapshot tested by that explicit wait.
+
+Use `runEnqueuedCommands(ref, ...)` when the property intentionally submits
+bursts or retains outstanding mailbox work. Its model steps continue to use
+`RuntimeSynchronization`. The old `runRuntimeCommands` and
+`formatRuntimeTranscript` names are deprecated aliases for the enqueue-oriented
+runner and formatter because their delivery semantics were not visible.
+
+### Runtime invariants and planner agreement
+
+Planner invariants and runtime invariants are deliberately separate. Runtime
+laws inspect causal command evidence, explicit asynchronous observations, and
+runtime status without requiring a duplicate reference model:
+
+```ts
+const invariant = MachineTest.runtimeInvariants(machine)
+const laws = [
+  invariant.snapshot("count never becomes negative", ({ snapshot }) => snapshot.state.value.count >= 0),
+  invariant.command(
+    "every accepted add is processed",
+    ({ command, result }) =>
+      command._tag !== "Send" || command.event._tag !== "Add" ||
+      result._tag === "SendProcessed"
+  )
+]
+
+const transcript = yield * MachineTest.verifyCausalCommands(
+  probe,
+  commands,
+  { invariants: laws }
+)
+```
+
+Use the existing `runCausalCommands` when a simplified application model
+provides exact expected results. Its returned transcript implements the same
+model-independent evidence interface, so reusable runtime laws compose with
+it directly:
+
+```ts
+const transcript = yield * MachineTest.runCausalCommands(probe, commands, model)
+
+yield * MachineTest.assertRuntimeInvariants(machine, transcript, laws)
+yield * MachineTest.assertPlannerRuntimeAgreement(machine, transcript)
+```
+
+`checkRuntimeInvariants` returns an aggregate report; `assertRuntimeInvariants`
+fails with every predicate and non-vacuity violation. Snapshot laws observe the
+initial and post-command snapshots by default. Select `"awaited"`, `"all"`, or
+`"final"` explicitly when a law targets observations retained by
+`probe.await.until` or only the final runtime snapshot.
+
+`assertPlannerRuntimeAgreement` is an explicit consistency check, not an
+application oracle. For each processed send it freshly plans from the receipt's
+`before` snapshot and compares handled/change flags, the public next snapshots,
+completion, command counts, emitted events, and public microstep evidence. It
+does not prove that the planner implements the intended business rules; use a
+reference model and runtime invariants for that.
 
 ## Current limits