@dudousxd/nestjs-durable 0.26.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-durable",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Durable workflows for NestJS — module, decorators, discovery and boot recovery",
   "license": "MIT",
   "author": "Davide Carvalho",
@@ -24,7 +24,8 @@
     "@nestjs/core": "^10.0.0 || ^11.0.0",
     "class-transformer": "^0.5.0",
     "class-validator": "^0.14.0",
-    "reflect-metadata": "^0.2.0"
+    "reflect-metadata": "^0.2.0",
+    "zod": "^3.0.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
     "@dudousxd/durable-worker": {
@@ -38,9 +39,13 @@
     },
     "class-validator": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@testcontainers/redis": "10.18.0",
     "@nestjs/common": "11.1.26",
     "@nestjs/core": "11.1.26",
     "@nestjs/event-emitter": "3.1.0",
@@ -55,8 +60,10 @@
     "tsup": "8.3.5",
     "@dudousxd/nestjs-diagnostics": "^0.5.0",
     "@tanstack/intent": "^0.3.2",
-    "@dudousxd/durable-worker": "0.5.0",
-    "@dudousxd/nestjs-durable-core": "^0.43.0",
+    "@dudousxd/durable-worker": "0.6.0",
+    "@dudousxd/nestjs-durable-core": "^0.46.0",
+    "@dudousxd/nestjs-durable-dashboard": "0.25.0",
+    "@dudousxd/nestjs-durable-transport-bullmq": "0.12.0",
     "@dudousxd/nestjs-durable-transport-event-emitter": "^0.5.0"
   },
   "module": "./dist/index.js",

package/skills/durable-determinism/SKILL.md

@@ -3,9 +3,10 @@ name: durable-determinism
 description: >
   The one correctness rule for @dudousxd/nestjs-durable workflows — the run(ctx, input) body re-runs
   top-to-bottom on recovery, so it must be deterministic. Keep Date.now/Math.random/IO out of the
-  body and inside steps; use ctx.now()/ctx.random()/ctx.uuid() for checkpointed non-deterministic
-  values. Covers positional replay, NonDeterminismError, @Workflow version pinning + side-by-side
-  registration for breaking changes, exactly-once vs physical retry idempotency, and self-healing recovery.
+  body and inside dispatched ctx.step calls; use ctx.now() for a checkpointed timestamp and
+  ctx.sideEffect(fn) for any other non-deterministic capture (an id, a random draw). Covers
+  positional replay, NonDeterminismError, @Workflow version pinning + side-by-side registration for
+  breaking changes, exactly-once vs physical retry idempotency, and self-healing recovery.
 license: MIT
 metadata:
   type: core
@@ -19,45 +20,55 @@ metadata:
 Durability comes from **checkpoint + deterministic replay**. On recovery the engine re-runs the
 workflow body from the top; a step that already has a `completed` checkpoint returns its saved result
 instead of executing again. For that to be safe, **the body must be deterministic** — all
-non-determinism (clock, randomness, network, IO) lives inside steps.
+non-determinism (clock, randomness, network, IO) lives inside a dispatched `ctx.step`, or one of the
+two checkpointed capture helpers.
 
 ## Setup
 
-There is nothing to install for this rule — it governs how you write `run(ctx, input)`. The key
-helpers are checkpointed wrappers on `ctx`:
+There is nothing to install for this rule — it governs how you write `run(ctx, input)`. The two
+capture helpers are checkpointed wrappers on `ctx`:
 
 ```ts
 import type { WorkflowCtx } from '@dudousxd/nestjs-durable-core';
 
 async run(ctx: WorkflowCtx, input: unknown) {
-  const at = await ctx.now();      // checkpointed clock — same value on every replay
-  const r = await ctx.random();    // checkpointed Math.random()
-  const id = await ctx.uuid();     // checkpointed crypto.randomUUID()
+  const at = await ctx.now();                             // checkpointed clock — same value on every replay
+  const id = await ctx.sideEffect(() => crypto.randomUUID()); // checkpointed capture — author picks the generator
   // ...use these instead of the raw globals...
 }
 ```
 
 ## Core patterns
 
-### Side effects live in steps; the body is pure orchestration
+### Side effects live in a dispatched step; the body is pure orchestration
 
 ```ts
-// ✓ The body only calls steps and branches on their results.
+// ✓ The body only calls ctx.step and branches on results — real IO is inside a @Step handler.
 async run(ctx: WorkflowCtx, order: Order) {
-  const quote = await ctx.step('quote', () => this.pricing.fetch(order)); // IO checkpointed
-  if (quote.total > 1000) await ctx.step('review', () => this.flagForReview(order));
-  await ctx.step('charge', () => this.billing.charge(quote));
+  const quote = await ctx.step(this.pricing.fetch, order);          // dispatched, checkpointed
+  if (quote.total > 1000) await ctx.step(this.review.flag, order);
+  await ctx.step(this.billing.charge, quote);
+}
+```
+
+```ts
+@Injectable()
+export class PricingService {
+  @Step()
+  async fetch(order: Order) { /* real IO here */ }
 }
 ```
 
 The engine guarantees each step runs **exactly once logically**, even across crashes and deploys,
 because re-running the body short-circuits completed checkpoints.
 
-### Use ctx.now / ctx.random / ctx.uuid for non-deterministic values
+### Use ctx.now() / ctx.sideEffect(fn) for non-deterministic values
 
 A raw `Date.now()` or `Math.random()` in the body produces a different value on each replay and
-shifts later decisions, corrupting the run. The `ctx` wrappers capture the value as a checkpoint on
-first run and replay it verbatim.
+shifts later decisions, corrupting the run. `ctx.now()` captures the clock as a checkpoint on first
+run and replays it verbatim; `ctx.sideEffect(fn)` does the same for anything else — `fn` runs ONCE
+and its result is replayed thereafter (you pick the generator: `() => uuidv7()`, `() => ulid()`,
+`() => Math.random()`, a config/env read).
 
 ### Version-pinned replay for breaking changes
 
@@ -88,19 +99,21 @@ renews its lease while running, so a long step is not reclaimed out from under i
 ```ts
 // ✗ Wrong — different value on every replay; downstream branches diverge
 async run(ctx, order) {
-  if (Math.random() < 0.1) await ctx.step('sample', () => sample()); // replays differently
-  const ts = Date.now();                                             // changes each recovery
+  if (Math.random() < 0.1) await ctx.step(this.sampler.sample, order); // replays differently
+  const ts = Date.now();                                              // changes each recovery
 }
 
 // ✓ Correct — checkpointed sources are stable across replays
 async run(ctx, order) {
-  if ((await ctx.random()) < 0.1) await ctx.step('sample', () => sample());
+  if ((await ctx.sideEffect(() => Math.random())) < 0.1) {
+    await ctx.step(this.sampler.sample, order);
+  }
   const ts = await ctx.now();
 }
 ```
 
 The body re-runs on recovery; raw `Date.now()`/`Math.random()` are not checkpointed, so they shift
-the replay. Source: packages/core/src/workflow-ctx.ts (`now`, `random`, `uuid`).
+the replay. Source: packages/core/src/workflow-ctx.ts (`now`, `sideEffect`).
 
 ### 2. Editing a live workflow body without bumping `version`
 
@@ -109,8 +122,8 @@ the replay. Source: packages/core/src/workflow-ctx.ts (`now`, `random`, `uuid`).
 @Workflow({ name: 'checkout', version: '1' })
 class CheckoutWorkflow {
   async run(ctx, o) {
-    await ctx.step('audit', () => audit(o)); // NEW step inserted before existing ones
-    await ctx.step('charge', () => charge(o));
+    await ctx.step(this.audit.log, o);   // NEW step inserted before existing ones
+    await ctx.step(this.billing.charge, o);
   }
 }
 
@@ -123,22 +136,23 @@ Replay matches checkpoints by position; inserting/reordering steps under the sam
 `NonDeterminismError` for in-flight runs. Source: website/content/docs/concepts/durability.mdx
 ("Version-pinned replay"), packages/core/src/workflow-ctx.ts (`NonDeterminismError`).
 
-### 3. Assuming a remote step physically runs exactly once
+### 3. Assuming a dispatched step physically runs exactly once
 
 ```ts
 // ✗ Wrong — handler assumes it can never be called twice for the same step
-@DurableStep('payments.charge-card')
-async charge(input) {
+@Step('payments.charge-card')
+async charge(input: { orderId: string; amountCents: number }) {
   return { chargeId: await this.stripe.charge(input) }; // double-charge if checkpoint write is lost
 }
 
-// ✓ Correct — make the handler idempotent on the stable stepId
-@DurableStep('payments.charge-card')
-async charge(input, stepId: string) {
-  return { chargeId: await this.stripe.charge(input, { idempotencyKey: stepId }) };
+// ✓ Correct — derive a stable idempotency key from the input itself (a @Step handler has no
+// separate stepId parameter — it only receives `(input, log)`)
+@Step('payments.charge-card')
+async charge(input: { orderId: string; amountCents: number }) {
+  return { chargeId: await this.stripe.charge(input, { idempotencyKey: input.orderId }) };
 }
 ```
 
 The engine guarantees *logical* exactly-once, but a crash after the worker ran and before its
-checkpoint was written can physically re-run the step — dedupe on the stable `stepId`.
+checkpoint was written can physically re-run the step — dedupe on something stable in the input.
 Source: website/content/docs/concepts/durability.mdx ("Idempotency").

package/skills/durable-setup/SKILL.md

@@ -2,10 +2,11 @@
 name: durable-setup
 description: >
   Set up @dudousxd/nestjs-durable in a NestJS app — DurableModule.forRootAsync with a StateStore
-  + Transport, register @Workflow / @DurableStep providers, and start runs with WorkflowService.
+  + Transport, register @Workflow / @Step providers, and start runs with WorkflowService.
   Covers the zero-infra EventEmitterTransport + InMemoryStateStore default, start() enqueues vs
-  waitForRun() settles, autoSchema, worker:false API/worker split, DurableWorkerModule thin worker,
-  forRoot vs forRootAsync, app.enableShutdownHooks for graceful drain.
+  waitForRun() settles, autoSchema, drive:false dashboard/API-only replicas, DurableModule as a
+  thin worker (connection only, no store), forRoot vs forRootAsync, app.enableShutdownHooks for
+  graceful drain.
 license: MIT
 metadata:
   type: core
@@ -22,7 +23,8 @@ infrastructure (in-process transport, in-memory store) — swap the store/transp
 
 ## Setup
 
-Install the module plus its core peer, a transport, and zod (remote-step contracts use it):
+Install the module plus its core peer, a transport, and zod (optional `@Step({ input, output })`
+runtime schemas use it):
 
 ```bash
 pnpm add @dudousxd/nestjs-durable @dudousxd/nestjs-durable-core \
@@ -57,7 +59,7 @@ import { PaymentsWorker } from './payments.worker';
 export class AppModule {}
 ```
 
-`@Workflow` and `@DurableStep` providers are plain providers — list them in `providers` (or any
+`@Workflow` and `@Step` providers are plain providers — list them in `providers` (or any
 imported module) and `DurableModule`'s discovery registers them on the engine at boot.
 
 Enable shutdown hooks so the engine drains in-flight runs on deploy:
@@ -116,29 +118,35 @@ DurableModule.forRootAsync({
 
 ### Split API pods from worker pods
 
-For scale, run dispatch-only pods (`worker: false`) and worker pods (default `worker: true`) that
-share only the database. An API pod's `start` only enqueues; worker pods poll and run the body.
+`DurableModule.forRoot` is the ONE module; the role is inferred from which of `store`/`connection`
+you pass — nothing else to configure. For scale, run dispatch-only pods and driving pods that share
+only the database. An API pod's `start` only enqueues; driving pods poll and run the body.
 
 ```ts
-// API / dashboard pod: enqueue-only, never executes or recovers workflows
-DurableModule.forRoot({ store, transport, worker: false });
+// API / dashboard pod: enqueue-only, mounts the store but never processes or recovers workflows
+DurableModule.forRoot({ store, transport, drive: false });
 
-// Worker pod (default): runs the body, recovers orphaned runs, polls timers
-DurableModule.forRoot({ store, transport /* worker: true is the default */ });
+// Driving pod (default): runs the body, recovers orphaned runs, polls timers
+DurableModule.forRoot({ store, transport /* drive: true is the default */ });
 ```
 
-A store-less **thin worker** (BullMQ consumer only, no engine/store) uses `DurableWorkerModule`:
+A store-less **thin worker** (no engine/store — just registered handlers over a connection) passes
+`connection` with no `store`:
 
 ```ts
-import { DurableWorkerModule } from '@dudousxd/nestjs-durable';
+import { DurableModule } from '@dudousxd/nestjs-durable';
 
 @Module({
-  imports: [DurableWorkerModule.forRoot({ connection: 'redis://localhost:6379', groups: ['payments'] })],
-  providers: [PaymentsWorker], // @DurableStep handlers for the 'payments' group
+  imports: [DurableModule.forRoot({ connection: 'redis://localhost:6379', partition: 'payments' })],
+  providers: [PaymentsWorker], // @Step handlers this worker serves
 })
 export class WorkerAppModule {}
 ```
 
+`partition` is an optional isolation suffix on this worker's queues — omit it for a single-tenant
+deployment. An operator with no local body for a workflow dispatches to a live worker of the same
+name automatically; there's no `groups`/`remoteByConvention` flag to opt into.
+
 ## Common mistakes
 
 ### 1. Expecting `start` to return the workflow's result

package/skills/durable-signals-and-timers/SKILL.md

@@ -28,11 +28,14 @@ via `WorkflowService`:
 ```ts title="approval.workflow.ts"
 import { Workflow } from '@dudousxd/nestjs-durable';
 import type { WorkflowCtx } from '@dudousxd/nestjs-durable-core';
+import { NotificationsService } from './notifications.service';
 
 @Workflow({ name: 'approval', version: '1' })
 export class ApprovalWorkflow {
+  constructor(private readonly notifications: NotificationsService) {}
+
   async run(ctx: WorkflowCtx, order: { id: string }) {
-    await ctx.step('request', () => this.notify(order.id));
+    await ctx.step(this.notifications.requestApproval, order.id);
     // Pause until someone signals this token (or 24h passes).
     const decision = await ctx.waitForSignal<{ approved: boolean }>(
       `approve:${order.id}`,
@@ -43,6 +46,19 @@ export class ApprovalWorkflow {
 }
 ```
 
+```ts title="notifications.service.ts"
+import { Step } from '@dudousxd/nestjs-durable';
+import { Injectable } from '@nestjs/common';
+
+@Injectable()
+export class NotificationsService {
+  @Step()
+  async requestApproval(orderId: string) {
+    // email/Slack the approver
+  }
+}
+```
+
 ```ts title="approval.controller.ts"
 import { WorkflowService } from '@dudousxd/nestjs-durable';
 
@@ -93,21 +109,21 @@ export class WelcomeWorkflow {
 number of restarts; the timer poller resumes it when due. `duration` accepts `ms`-style strings.
 
 ```ts
-await ctx.step('draft', () => this.draft());
+await ctx.step(this.reports.draft, order.id);
 await ctx.sleep('7 days');           // durable — not setTimeout
-await ctx.step('send', () => this.send());
+await ctx.step(this.reports.send, order.id);
 ```
 
 ### Webhooks (third-party callbacks)
 
 `ctx.webhook()` mints a stable token + url **before** suspending, so you can hand the url to a third
-party, then `await wh.wait()` for the callback (delivered as `signal(token, body)`). Configure
-`webhookUrl` on the module to populate `wh.url`.
+party — inside a dispatched `ctx.step` — then `await wh.wait()` for the callback (delivered as
+`signal(token, body)`). Configure `webhookUrl` on the module to populate `wh.url`.
 
 ```ts
 const wh = ctx.webhook<{ status: string }>();
-await ctx.step('register', () => this.provider.callMeBack(wh.url)); // url is ready now
-const result = await wh.wait();                                     // resumes on the callback
+await ctx.step(this.provider.register, { callbackUrl: wh.url }); // url is ready now
+const result = await wh.wait();                                  // resumes on the callback
 ```
 
 ### signalWithStart — the accumulator pattern
@@ -132,13 +148,13 @@ await this.workflows.signalWithStart(
 // ✗ Wrong — a real timer is lost on restart; the delay is not durable
 async run(ctx, input) {
   await new Promise((r) => setTimeout(r, 7 * 86_400_000)); // gone if the process restarts
-  await ctx.step('send', () => this.send());
+  await ctx.step(this.reports.send, input);
 }
 
 // ✓ Correct — a durable timer the engine persists and resumes when due
 async run(ctx, input) {
   await ctx.sleep('7 days');
-  await ctx.step('send', () => this.send());
+  await ctx.step(this.reports.send, input);
 }
 ```
 

package/skills/durable-testing/SKILL.md

@@ -2,10 +2,11 @@
 name: durable-testing
 description: >
   Unit-test @dudousxd/nestjs-durable workflows with @dudousxd/nestjs-durable-testing — createTestEngine
-  gives an in-memory engine/store/transport + a controllable clock. Start runs with engine.start +
-  waitForRun, advance durable sleeps with tick(ms), inject failures with failOnce/failTimes to drive
-  retries, and assert with assertRunStatus, assertOutput, assertStepsRan, assertStepAttempts,
-  recordedSteps. No Postgres, no Redis, no real time.
+  gives an in-memory engine/store/transport + a controllable clock. Register a workflow body with
+  engine.register, serve its dispatched ctx.step calls with transport.handle, start runs with
+  engine.start + waitForRun, advance durable sleeps with tick(ms), inject failures with
+  failOnce/failTimes to drive retries, and assert with assertRunStatus, assertOutput, assertStepsRan,
+  assertStepAttempts, recordedSteps. No Postgres, no Redis, no real time.
 license: MIT
 metadata:
   type: core
@@ -20,6 +21,9 @@ metadata:
 transport, with a clock you control and assertions that read the recorded state back. No external
 infrastructure, no real waiting.
 
+Every `ctx.step` is dispatched — even in a test — so a step needs a fake worker handler registered on
+the test transport before the run reaches it.
+
 ## Setup
 
 ```bash
@@ -35,54 +39,90 @@ import {
 
 const t = createTestEngine(); // { engine, store, transport, clock, tick, run }
 
+t.transport.handle('reserve', async () => ({ reserved: true })); // fake worker for the dispatched step
+t.transport.handle('ship', async () => ({ shipped: true }));
+
 t.engine.register('checkout', '1', async (ctx) => {
-  await ctx.step('reserve', () => ({ reserved: true }));
-  return ctx.step('ship', () => ({ shipped: true }));
+  await ctx.step('reserve', { id: 'o1' });
+  return ctx.step('ship', { id: 'o1' });
 });
 
 const { runId } = await t.engine.start('checkout', { id: 'o1' }, 'run1'); // enqueues → pending
-await t.engine.waitForRun(runId);                                         // settles
+const result = await settle(t, runId);                                   // see "Settling a run" below
 await assertRunStatus(t.store, 'run1', 'completed');
 await assertOutput(t.store, 'run1', { shipped: true });
 ```
 
 `createTestEngine()` returns `{ engine, store, transport, clock, tick, run }`. Use the raw
 `engine.register(name, version, body)` to register a workflow body directly (no NestJS DI needed in a
-unit test), or wire a real `@Workflow` provider via a Nest testing module when you want DI.
+unit test) and `transport.handle(name, (input, log) => output)` to serve each `ctx.step` it dispatches
+by name — or wire real `@Workflow`/`@Step` providers via a Nest testing module when you want DI.
 
 ## Core patterns
 
+### Settling a run — a dispatched ctx.step suspends between hops
+
+Because every step is dispatched (even against the in-memory transport), a run legitimately goes
+`suspended` after EACH step and resumes asynchronously once its fake handler resolves — so a single
+`waitForRun` call after `start` often returns mid-chain, not at the run's actual resting point. Poll
+until the status stops changing:
+
+```ts
+import type { RunResult } from '@dudousxd/nestjs-durable-core';
+import type { TestEngine } from '@dudousxd/nestjs-durable-testing';
+
+async function settle(t: TestEngine, runId: string, max = 20): Promise<RunResult> {
+  let last: RunResult = { runId, status: 'pending' } as RunResult;
+  for (let i = 0; i < max; i += 1) {
+    await new Promise((r) => setImmediate(r)); // let a pending transport.handle result land
+    last = await t.engine.waitForRun(runId);
+    if (last.status !== 'suspended') return last;
+  }
+  return last; // still suspended after `max` hops — a real wait (sleep/signal), not more dispatch
+}
+```
+
+A workflow whose OWN resting point is `suspended` (a durable sleep, `waitForSignal`) returns that
+status from `settle` too — assert on it directly, same as the non-dispatched case.
+
 ### Control durable time with tick(ms)
 
 `tick(ms)` advances the clock and resumes any durable sleep now due — a 7-day sleep is tested
 instantly.
 
 ```ts
+t.transport.handle('draft', async () => undefined);
+t.transport.handle('send', async () => undefined);
 t.engine.register('digest', '1', async (ctx) => {
-  await ctx.step('draft', () => draft());
+  await ctx.step('draft', {});
   await ctx.sleep('7 days');
-  await ctx.step('send', () => send());
+  await ctx.step('send', {});
 });
 
 const { runId } = await t.engine.start('digest', {}, 'run1');
-await t.engine.waitForRun(runId);                 // settles on the durable sleep → suspended
-await t.tick(7 * 24 * 60 * 60 * 1000);            // the sleep is now due → completes
+await settle(t, runId);                           // rests on the durable sleep → suspended
+await assertRunStatus(t.store, 'run1', 'suspended');
+await t.tick(7 * 24 * 60 * 60 * 1000);             // the sleep is now due → resumes
+await settle(t, runId);
 await assertRunStatus(t.store, 'run1', 'completed');
 ```
 
 ### Inject crashes and drive retries
 
-`failOnce(value)` / `failTimes(n, value)` make a step throw before finally returning `value` — to
-exercise `retries` and resume.
+`failOnce(value)` / `failTimes(n, value)` build a fake handler that throws before finally returning
+`value` — hand it straight to `transport.handle` to exercise `retries` and resume. A zero/omitted
+`backoffMs` still needs a timer sweep to notice the retry is due, so `tick(0)` after the failure.
 
 ```ts
 import { failOnce, assertStepAttempts } from '@dudousxd/nestjs-durable-testing';
 
-t.engine.register('wf', '1', async (ctx) =>
-  ctx.step('charge', failOnce({ ok: true }), { retries: 3 }),
-);
+t.transport.handle('charge', failOnce({ ok: true }));
+t.engine.register('wf', '1', async (ctx) => ctx.step('charge', {}, { retries: 3 }));
+
 const { runId } = await t.engine.start('wf', {}, 'run1');
-await t.engine.waitForRun(runId);
+await settle(t, runId);
+await t.tick(0); // due retries (even a zero backoff) resume on the next timer sweep
+await settle(t, runId);
 await assertStepAttempts(t.store, 'run1', 'charge', 2); // failed once, then succeeded
 ```
 
@@ -98,23 +138,40 @@ All assertions read the store, so they work against any run the engine produced:
 
 ## Common mistakes
 
-### 1. Expecting `start` to run the body synchronously in a test
+### 1. Forgetting to register a transport.handle for a dispatched step
 
 ```ts
-// ✗ Wrong — start only enqueues; the run is still 'pending' here
-await t.engine.start('checkout', input, 'run1');
-await assertRunStatus(t.store, 'run1', 'completed'); // fails — body hasn't run yet
+// ✗ Wrong — no fake worker for 'reserve'; the step fails with "no handler for reserve"
+t.engine.register('checkout', '1', async (ctx) => ctx.step('reserve', {}));
+await t.engine.start('checkout', {}, 'run1');
+
+// ✓ Correct — every ctx.step name the body dispatches needs a matching transport.handle
+t.transport.handle('reserve', async () => ({ reserved: true }));
+t.engine.register('checkout', '1', async (ctx) => ctx.step('reserve', {}));
+```
+
+`ctx.step` is always dispatched — even in a test against the in-memory transport — so there is no
+"local" step that just runs inline. Source: packages/core/src/testing/in-memory-transport.ts (`handle`).
 
-// ✓ Correct — wait for the run to settle (or use t.run(...) which starts + waits)
+### 2. Expecting one waitForRun to reach a multi-step run's terminal state
+
+```ts
+// ✗ Wrong — resolves on the FIRST dispatched step's pending suspend, not the run's end state
 const { runId } = await t.engine.start('checkout', input, 'run1');
 await t.engine.waitForRun(runId);
+await assertRunStatus(t.store, 'run1', 'completed'); // often fails — still 'suspended' mid-chain
+
+// ✓ Correct — poll until the status stops changing (see "Settling a run" above)
+const { runId } = await t.engine.start('checkout', input, 'run1');
+await settle(t, runId);
 await assertRunStatus(t.store, 'run1', 'completed');
 ```
 
-`start` enqueues and returns `{ status: 'pending' }`; the body runs asynchronously, so pair it with
-`waitForRun` (or the harness's `run`). Source: packages/testing/src/harness.ts (`createTestEngine`).
+`waitForRun` resolves on the FIRST settled event, and a dispatch-pending suspend counts as settled —
+a run with several dispatched steps in sequence settles once per step. Source:
+packages/core/src/engine.ts (`waitForRun`).
 
-### 2. Using real time instead of tick() for a durable sleep
+### 3. Using real time instead of tick() for a durable sleep
 
 ```ts
 // ✗ Wrong — the durable sleep is suspended; real time never advances the engine's clock
@@ -123,14 +180,14 @@ await new Promise((r) => setTimeout(r, 1000)); // run stays suspended forever
 
 // ✓ Correct — advance the controllable clock so the sleep becomes due
 await t.engine.start('digest', {}, 'run1');
-await t.engine.waitForRun('run1'); // suspends on the sleep
+await settle(t, 'run1'); // suspends on the sleep
 await t.tick(7 * 24 * 60 * 60 * 1000);
 ```
 
 The test engine uses a `MutableClock`; only `tick(ms)` advances it and resumes due timers.
 Source: packages/testing/src/harness.ts (`tick`, `MutableClock`).
 
-### 3. Reusing the same runId across cases expecting a fresh run
+### 4. Reusing the same runId across cases expecting a fresh run
 
 ```ts
 // ✗ Wrong — start is idempotent by runId; reusing 'run1' returns the existing run, not a new one