@typeonce/effect-machine 0.4.0 → 0.5.0

package/README.md

@@ -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
 
@@ -655,6 +656,211 @@ 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
 
 Declarative first-class guards are not part of the current API. Ordinary