Add explicit runtime command semantics (#87)

Author: SandroMaglione

.changeset/tidy-runtimes-flow.md

@@ -0,0 +1,5 @@
+---
+"@typeonce/effect-machine": minor
+---
+
+Add explicitly named causal and enqueue-oriented runtime command runners. Causal command tests now retain an exact probe step for every processed send, support probe-bound asynchronous waits, attribute processing failures to the submitted command, and format replayable causal transcripts. Deprecate the ambiguous `runRuntimeCommands` and `formatRuntimeTranscript` names in favor of their explicit enqueue-oriented replacements.

README.md

@@ -774,6 +774,43 @@ 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.
+
 ## Current limits
 
 Declarative first-class guards are not part of the current API. Ordinary

docs/agent-guide.md

@@ -815,6 +815,31 @@ acknowledgement covers the submitted event's synchronous macrostep, state
 commit, emissions, and invoke startup; it does not wait for an invoke or timer
 to complete. Application code should continue to use `MachineRef.send`.
 
+For generated runtime command sequences, select delivery behavior by name:
+
+```ts
+yield* MachineTest.runCausalCommands(probe, commands, causalModel)
+yield* MachineTest.runEnqueuedCommands(ref, commands, enqueueModel)
+```
+
+Prefer `runCausalCommands` for semantic and reference-model properties. Every
+accepted send produces a `SendProcessed` result containing its exact
+`ProbeStep`, including ignored and targetless events. A machine processing
+error fails that exact command and retains its checked prefix for shrinking.
+The next command does not begin until the submitted send's managed macrostep
+has completed.
+
+Use `probe.await.until(predicate)` in a causal model step only when the
+assertion also requires later timer, invoke, or child activity. It observes the
+current runtime snapshot before waiting for subsequent publications, so it
+does not miss work that completed immediately after the causal boundary.
+
+Use `runEnqueuedCommands` only when outstanding mailbox work is intentional,
+such as burst ordering and queue behavior. Its `RuntimeSynchronization`
+policies observe public snapshots but do not turn send acceptance into causal
+completion. Do not use the deprecated `runRuntimeCommands` name in new code;
+it is an alias for enqueue behavior and hides that important distinction.
+
 ## Common compiler errors
 
 ### `initial` is not callable

src/internal/testing/machine/probe.ts

@@ -49,6 +49,18 @@ export const probe = <M extends AnyMachine, Error, Output>(
   return Effect.succeed(Object.freeze({
     machine,
     ref,
+    await: Object.freeze({
+      none: { _tag: "None" } as const,
+      until: (
+        predicate: (
+          snapshot: Machine.RuntimeSnapshot<
+            Machine.Machine.Snapshot<Machine.Machine.States<M>>,
+            Error,
+            Output
+          >
+        ) => boolean
+      ) => ({ _tag: "Until", predicate } as const)
+    }),
     sendAndAwait: (event: Machine.Machine.InputEvent<M>) =>
       acknowledged.call(ref, event).pipe(
         Effect.map(({ after, before, plan }) => {