@dudousxd/nestjs-durable 0.22.0 → 0.22.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-durable",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "Durable workflows for NestJS — module, decorators, discovery and boot recovery",
   "license": "MIT",
   "author": "Davide Carvalho",
@@ -13,7 +13,8 @@
   "main": "./dist/index.cjs",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "peerDependencies": {
     "@dudousxd/durable-worker": ">=0.1.0 <1.0.0",
@@ -53,9 +54,10 @@
     "zod": "3.25.76",
     "tsup": "8.3.5",
     "@dudousxd/nestjs-diagnostics": "^0.5.0",
-    "@dudousxd/nestjs-durable-core": "^0.37.0",
+    "@tanstack/intent": "^0.3.2",
     "@dudousxd/nestjs-durable-transport-event-emitter": "^0.5.0",
-    "@dudousxd/durable-worker": "0.3.1"
+    "@dudousxd/durable-worker": "0.3.3",
+    "@dudousxd/nestjs-durable-core": "^0.38.0"
   },
   "module": "./dist/index.js",
   "exports": {
@@ -70,6 +72,9 @@
       }
     }
   },
+  "keywords": [
+    "tanstack-intent"
+  ],
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc -p tsconfig.json --noEmit"

package/skills/durable-determinism/SKILL.md

@@ -0,0 +1,144 @@
+---
+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.
+license: MIT
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-durable"
+  library_version: 0.22.0
+  framework: nestjs
+---
+
+# Determinism & replay — the one rule
+
+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.
+
+## 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`:
+
+```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()
+  // ...use these instead of the raw globals...
+}
+```
+
+## Core patterns
+
+### Side effects live in steps; the body is pure orchestration
+
+```ts
+// ✓ The body only calls steps and branches on their results.
+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));
+}
+```
+
+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
+
+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.
+
+### Version-pinned replay for breaking changes
+
+Replay is **positional**: reordering or inserting steps while runs are in flight would corrupt them.
+A run resumes on the `version` it started on, so during a breaking change register both versions side
+by side — in-flight runs drain on the old, new runs start on the new.
+
+```ts
+@Workflow({ name: 'checkout', version: '1' })
+export class CheckoutWorkflowV1 { /* old body, kept until in-flight runs drain */ }
+
+@Workflow({ name: 'checkout', version: '2' })
+export class CheckoutWorkflowV2 { /* new body */ }
+```
+
+A run whose version is no longer registered fails loudly rather than silently corrupting.
+
+### Recovery is automatic and self-healing
+
+`DurableModule` wires `engine.recoverIncomplete()` — it runs on boot **and** periodically (the
+`TimerPoller`), so a run orphaned by a crashed worker is reclaimed within ~`leaseMs`. A live worker
+renews its lease while running, so a long step is not reclaimed out from under it.
+
+## Common mistakes
+
+### 1. Reading the clock or randomness directly in the body
+
+```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
+}
+
+// ✓ Correct — checkpointed sources are stable across replays
+async run(ctx, order) {
+  if ((await ctx.random()) < 0.1) await ctx.step('sample', () => sample());
+  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`).
+
+### 2. Editing a live workflow body without bumping `version`
+
+```ts
+// ✗ Wrong — insert a step into v1 while runs are in flight → positions shift, runs corrupt
+@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));
+  }
+}
+
+// ✓ Correct — ship the change as a new version, keep v1 registered until its runs drain
+@Workflow({ name: 'checkout', version: '2' })
+class CheckoutWorkflowV2 { /* new body */ }
+```
+
+Replay matches checkpoints by position; inserting/reordering steps under the same version throws a
+`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
+
+```ts
+// ✗ Wrong — handler assumes it can never be called twice for the same step
+@DurableStep('payments.charge-card')
+async charge(input) {
+  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 }) };
+}
+```
+
+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`.
+Source: website/content/docs/concepts/durability.mdx ("Idempotency").

package/skills/durable-setup/SKILL.md

@@ -0,0 +1,189 @@
+---
+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.
+  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.
+license: MIT
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-durable"
+  library_version: 0.22.0
+  framework: nestjs
+---
+
+# Durable setup (NestJS module wiring)
+
+Install `@dudousxd/nestjs-durable`, register `DurableModule` with a store + transport, declare your
+workflow/step providers, and start runs with `WorkflowService`. The defaults below use zero
+infrastructure (in-process transport, in-memory store) — swap the store/transport for production.
+
+## Setup
+
+Install the module plus its core peer, a transport, and zod (remote-step contracts use it):
+
+```bash
+pnpm add @dudousxd/nestjs-durable @dudousxd/nestjs-durable-core \
+  @dudousxd/nestjs-durable-transport-event-emitter @nestjs/event-emitter zod
+```
+
+Register the module. `forRootAsync` lets the factory inject providers (here `EventEmitter2`); the
+module is `global`, so `WorkflowService` is injectable everywhere without re-importing.
+
+```ts title="app.module.ts"
+import { DurableModule } from '@dudousxd/nestjs-durable';
+import { InMemoryStateStore } from '@dudousxd/nestjs-durable-core';
+import { EventEmitterTransport } from '@dudousxd/nestjs-durable-transport-event-emitter';
+import { Module } from '@nestjs/common';
+import { EventEmitter2, EventEmitterModule } from '@nestjs/event-emitter';
+import { CheckoutWorkflow } from './checkout.workflow';
+import { PaymentsWorker } from './payments.worker';
+
+@Module({
+  imports: [
+    EventEmitterModule.forRoot(),
+    DurableModule.forRootAsync({
+      inject: [EventEmitter2],
+      useFactory: (emitter: EventEmitter2) => ({
+        store: new InMemoryStateStore(),
+        transport: new EventEmitterTransport(emitter),
+      }),
+    }),
+  ],
+  providers: [CheckoutWorkflow, PaymentsWorker], // discovered by DurableModule on boot
+})
+export class AppModule {}
+```
+
+`@Workflow` and `@DurableStep` 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:
+
+```ts title="main.ts"
+const app = await NestFactory.create(AppModule);
+app.enableShutdownHooks(); // engine releases run leases on OnApplicationShutdown
+await app.listen(3000);
+```
+
+## Core patterns
+
+### Start a run, then (optionally) wait for it
+
+`start` **enqueues** the run and returns immediately with `{ runId, status: 'pending' }` — a worker
+runs the body, so the HTTP handler never blocks. Pass the workflow **class** for a typed input.
+
+```ts
+import { WorkflowService } from '@dudousxd/nestjs-durable';
+
+@Controller('checkout')
+export class CheckoutController {
+  constructor(private readonly workflows: WorkflowService) {}
+
+  @Post()
+  async checkout(@Body() order: Order) {
+    const { runId } = await this.workflows.start(CheckoutWorkflow, order); // returns now
+    return { runId };
+  }
+
+  @Post('sync')
+  async checkoutSync(@Body() order: Order) {
+    const { runId } = await this.workflows.start(CheckoutWorkflow, order);
+    return this.workflows.waitForRun(runId); // resolves once the run settles
+  }
+}
+```
+
+### forRoot vs forRootAsync, and the production store/transport
+
+`forRoot(options)` takes a static options object; `forRootAsync({ useFactory, inject })` builds them
+from injected providers (a config service, an ORM connection). For production, swap the in-memory
+store for an ORM `StateStore` and the event-emitter transport for BullMQ:
+
+```ts
+DurableModule.forRootAsync({
+  inject: [MikroORM],
+  useFactory: (orm: MikroORM) => ({
+    store: new MikroOrmStateStore(orm),                // persists checkpoints to Postgres/MySQL
+    transport: new BullMQTransport({ connection }),    // cross-process / Python steps
+    autoSchema: false,                                 // run migrations instead in production
+    leaseMs: 30_000,                                   // recovery lease > your longest resume step
+  }),
+});
+```
+
+### 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.
+
+```ts
+// API / dashboard pod: enqueue-only, never executes or recovers workflows
+DurableModule.forRoot({ store, transport, worker: false });
+
+// Worker pod (default): runs the body, recovers orphaned runs, polls timers
+DurableModule.forRoot({ store, transport /* worker: true is the default */ });
+```
+
+A store-less **thin worker** (BullMQ consumer only, no engine/store) uses `DurableWorkerModule`:
+
+```ts
+import { DurableWorkerModule } from '@dudousxd/nestjs-durable';
+
+@Module({
+  imports: [DurableWorkerModule.forRoot({ connection: 'redis://localhost:6379', groups: ['payments'] })],
+  providers: [PaymentsWorker], // @DurableStep handlers for the 'payments' group
+})
+export class WorkerAppModule {}
+```
+
+## Common mistakes
+
+### 1. Expecting `start` to return the workflow's result
+
+```ts
+// ✗ Wrong — `start` enqueues; `result` is { runId, status: 'pending' }, never the run output
+const result = await this.workflows.start(CheckoutWorkflow, order);
+return result.output; // undefined
+
+// ✓ Correct — await the outcome with waitForRun when you need it inline
+const { runId } = await this.workflows.start(CheckoutWorkflow, order);
+return this.workflows.waitForRun(runId); // resolves once the run settles
+```
+
+`start` creates the run as `'pending'` and a worker runs the body asynchronously; only `waitForRun`
+resolves with the settled outcome. Source: packages/nestjs/src/workflow.service.ts.
+
+### 2. Leaving `autoSchema` on in production
+
+```ts
+// ✗ Wrong — auto-creates durable tables on every boot against the prod DB
+DurableModule.forRoot({ store, transport }); // autoSchema defaults to true
+
+// ✓ Correct — disable it and create the schema from a migration
+DurableModule.forRoot({ store, transport, autoSchema: false });
+```
+
+`autoSchema` defaults to `true` and calls `store.ensureSchema()` on boot — fine for dev, but in
+production you want the store adapter's `ensure*DurableSchema()` run as a migration instead.
+Source: packages/nestjs/src/durable.module.ts (`autoSchema`).
+
+### 3. Forgetting to register the workflow/step as a provider
+
+```ts
+// ✗ Wrong — the class is decorated but never provided, so discovery never finds it
+@Module({ imports: [DurableModule.forRoot({ store, transport })] })
+export class AppModule {} // start('checkout', ...) → unknown workflow
+
+// ✓ Correct — list it (or import a module that provides it)
+@Module({
+  imports: [DurableModule.forRoot({ store, transport })],
+  providers: [CheckoutWorkflow, PaymentsWorker],
+})
+export class AppModule {}
+```
+
+`DurableModule` registers workflows/steps by scanning DI providers on boot; an unprovided class is
+invisible to the engine. Source: packages/nestjs/src/durable.module.ts (DiscoveryModule + registrars).

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

@@ -0,0 +1,181 @@
+---
+name: durable-signals-and-timers
+description: >
+  Pause and resume @dudousxd/nestjs-durable workflows — ctx.waitForSignal(token) resumed by
+  WorkflowService.signal(token, payload), ctx.waitForEvent(name, { match }) resumed by
+  publishEvent(name, payload), @OnEvent / @Workflow({ onEvent }) event-triggered starts,
+  durable ctx.sleep(duration) / ctx.sleepUntil(date), ctx.webhook() for third-party callbacks, and
+  signalWithStart for the durable-entity/accumulator pattern. Covers the timeoutMs determinism caveat.
+license: MIT
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-durable"
+  library_version: 0.22.0
+  framework: nestjs
+---
+
+# Signals, events & durable timers
+
+Workflows pause on durable primitives and resume when an external event arrives — a signal, a named
+event, a timer, or a webhook callback. The run is `suspended` (consuming nothing) while it waits and
+survives restarts.
+
+## Setup
+
+Inside a workflow body you await the wait primitive; outside (a controller, a webhook) you deliver
+via `WorkflowService`:
+
+```ts title="approval.workflow.ts"
+import { Workflow } from '@dudousxd/nestjs-durable';
+import type { WorkflowCtx } from '@dudousxd/nestjs-durable-core';
+
+@Workflow({ name: 'approval', version: '1' })
+export class ApprovalWorkflow {
+  async run(ctx: WorkflowCtx, order: { id: string }) {
+    await ctx.step('request', () => this.notify(order.id));
+    // Pause until someone signals this token (or 24h passes).
+    const decision = await ctx.waitForSignal<{ approved: boolean }>(
+      `approve:${order.id}`,
+      { timeoutMs: 24 * 60 * 60 * 1000 },
+    );
+    return decision.approved ? 'shipped' : 'rejected';
+  }
+}
+```
+
+```ts title="approval.controller.ts"
+import { WorkflowService } from '@dudousxd/nestjs-durable';
+
+@Controller('approvals')
+export class ApprovalController {
+  constructor(private readonly workflows: WorkflowService) {}
+
+  @Post(':orderId')
+  approve(@Param('orderId') orderId: string, @Body() body: { approved: boolean }) {
+    return this.workflows.signal(`approve:${orderId}`, body); // resumes the suspended run
+  }
+}
+```
+
+## Core patterns
+
+### Signals (point-to-point) vs events (named pub/sub)
+
+- `ctx.waitForSignal<T>(token, { timeoutMs? })` waits on an exact `token`; deliver with
+  `workflows.signal(token, payload)`. One token, one waiting run.
+- `ctx.waitForEvent<T>(name, { match?, timeoutMs? })` waits on a named event with optional `match`
+  filtering; `workflows.publishEvent(name, payload)` fans out to every run whose `match` the payload
+  satisfies (and starts any `@OnEvent` workflows). Returns how many runs it touched.
+
+```ts
+const order = await ctx.waitForEvent<Order>('order.paid', { match: { orderId: id } });
+// elsewhere: await workflows.publishEvent('order.paid', { orderId: id, amount });
+```
+
+### Event-triggered workflow starts
+
+`@Workflow({ onEvent })` or `@OnEvent(...)` start a **fresh run** whenever the event is published —
+the payload becomes the run's input. `debounce` / `batch` coalesce bursts.
+
+```ts
+import { Workflow, OnEvent } from '@dudousxd/nestjs-durable';
+
+@OnEvent('user.registered', 'user.invited')
+@Workflow({ name: 'welcome', version: '1', debounce: '30s' })
+export class WelcomeWorkflow {
+  async run(ctx: WorkflowCtx, user: { id: string }) { /* ... */ }
+}
+```
+
+### Durable timers
+
+`ctx.sleep(duration)` and `ctx.sleepUntil(date)` suspend the run durably — a 7-day sleep survives any
+number of restarts; the timer poller resumes it when due. `duration` accepts `ms`-style strings.
+
+```ts
+await ctx.step('draft', () => this.draft());
+await ctx.sleep('7 days');           // durable — not setTimeout
+await ctx.step('send', () => this.send());
+```
+
+### 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`.
+
+```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
+```
+
+### signalWithStart — the accumulator pattern
+
+`signalWithStart` ensures a run exists, then delivers a signal race-free — one long-lived run per key
+fed by many calls.
+
+```ts
+await this.workflows.signalWithStart(
+  AggregatorWorkflow,
+  { key },
+  `aggregator:${key}`,                 // stable runId
+  { token: `event:${key}`, payload: event },
+);
+```
+
+## Common mistakes
+
+### 1. Using setTimeout / a cron instead of ctx.sleep
+
+```ts
+// ✗ 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());
+}
+
+// ✓ 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());
+}
+```
+
+`ctx.sleep`/`sleepUntil` record a durable timer checkpoint and suspend; the timer poller resumes the
+run — a raw `setTimeout` dies with the process. Source: packages/core/src/workflow-ctx.ts
+(`sleep`, `sleepUntil`, `suspendUntil`).
+
+### 2. Adding `{ timeoutMs }` to a live waitForSignal
+
+```ts
+// A run started under this (unbounded wait = 1 logical position):
+await ctx.waitForSignal('approve');
+
+// ✗ Wrong — adding a timeout makes it consume TWO positions, shifting every later step's seq
+await ctx.waitForSignal('approve', { timeoutMs: 60_000 }); // in-flight runs corrupt
+
+// ✓ Correct — treat the timeout change as a new @Workflow version
+@Workflow({ name: 'approval', version: '2' })
+```
+
+A bounded wait consumes two logical positions (deadline + wait), an unbounded one consumes one, so
+toggling `timeoutMs` is a positional (versioned) change. Source: packages/core/src/workflow-ctx.ts
+(determinism note above `consumeBuffered`).
+
+### 3. Signalling a token that doesn't match the waiting run
+
+```ts
+// Workflow waits on a per-order token:
+await ctx.waitForSignal(`approve:${order.id}`);
+
+// ✗ Wrong — signalling a different token leaves the run suspended forever
+await this.workflows.signal('approve', body);
+
+// ✓ Correct — the signal token must match the waited token exactly
+await this.workflows.signal(`approve:${order.id}`, body);
+```
+
+`signal(token, payload)` resolves only the run waiting on that exact token; a mismatched token is
+buffered and the run never wakes. Source: packages/nestjs/src/workflow.service.ts (`signal`),
+packages/core/src/workflow-ctx.ts (`waitForSignal`).

package/skills/durable-testing/SKILL.md

@@ -0,0 +1,146 @@
+---
+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.
+license: MIT
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-durable"
+  library_version: 0.22.0
+  framework: nestjs
+---
+
+# Testing durable workflows
+
+`@dudousxd/nestjs-durable-testing` runs a whole workflow in a unit test against an in-memory store and
+transport, with a clock you control and assertions that read the recorded state back. No external
+infrastructure, no real waiting.
+
+## Setup
+
+```bash
+pnpm add -D @dudousxd/nestjs-durable-testing
+```
+
+```ts title="checkout.spec.ts"
+import {
+  createTestEngine,
+  assertRunStatus,
+  assertOutput,
+} from '@dudousxd/nestjs-durable-testing';
+
+const t = createTestEngine(); // { engine, store, transport, clock, tick, run }
+
+t.engine.register('checkout', '1', async (ctx) => {
+  await ctx.step('reserve', () => ({ reserved: true }));
+  return ctx.step('ship', () => ({ shipped: true }));
+});
+
+const { runId } = await t.engine.start('checkout', { id: 'o1' }, 'run1'); // enqueues → pending
+await t.engine.waitForRun(runId);                                         // settles
+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.
+
+## Core patterns
+
+### 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.engine.register('digest', '1', async (ctx) => {
+  await ctx.step('draft', () => draft());
+  await ctx.sleep('7 days');
+  await ctx.step('send', () => 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 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.
+
+```ts
+import { failOnce, assertStepAttempts } from '@dudousxd/nestjs-durable-testing';
+
+t.engine.register('wf', '1', async (ctx) =>
+  ctx.step('charge', failOnce({ ok: true }), { retries: 3 }),
+);
+const { runId } = await t.engine.start('wf', {}, 'run1');
+await t.engine.waitForRun(runId);
+await assertStepAttempts(t.store, 'run1', 'charge', 2); // failed once, then succeeded
+```
+
+### Assertions
+
+All assertions read the store, so they work against any run the engine produced:
+
+- `assertRunStatus(store, runId, status)` — terminal/suspended status.
+- `assertOutput(store, runId, expected)` — the run's final output.
+- `assertStepsRan(store, runId, names)` — which steps recorded checkpoints.
+- `assertStepAttempts(store, runId, stepName, attempts)` — attempt count for retries.
+- `recordedSteps(store, runId)` — the list of recorded step names.
+
+## Common mistakes
+
+### 1. Expecting `start` to run the body synchronously in a test
+
+```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
+
+// ✓ Correct — wait for the run to settle (or use t.run(...) which starts + waits)
+const { runId } = await t.engine.start('checkout', input, 'run1');
+await t.engine.waitForRun(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`).
+
+### 2. 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
+await t.engine.start('digest', {}, 'run1');
+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 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
+
+```ts
+// ✗ Wrong — start is idempotent by runId; reusing 'run1' returns the existing run, not a new one
+await t.engine.start('wf', a, 'run1');
+await t.engine.start('wf', b, 'run1'); // same run — input b is ignored
+
+// ✓ Correct — give each logical run a distinct id (or omit it for a random one)
+await t.engine.start('wf', a, 'run1');
+await t.engine.start('wf', b, 'run2');
+```
+
+A `runId` makes `start` idempotent (a redelivery returns the existing run), so distinct cases need
+distinct ids. Source: packages/nestjs/src/workflow.service.ts (`start` idempotency by `runId`).

package/skills/durable-workflows/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: durable-workflows
+description: >
+  Author durable workflows with @dudousxd/nestjs-durable — @Workflow({ name, version }) classes with a
+  run(ctx, input) body, local ctx.step(name, fn, opts) checkpoints, typed remote steps via remoteStep
+  + ctx.call handled by @DurableStep('name'), step retries/backoff, FatalError to stop retrying,
+  Promise.all fan-out, saga compensate undo callbacks, and run tags. Covers step vs ctx.call vs
+  sub-process log.sub annotations and constructor dependency injection inside a workflow class.
+license: MIT
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-durable"
+  library_version: 0.22.0
+  framework: nestjs
+---
+
+# Authoring durable workflows
+
+A workflow is a provider decorated with `@Workflow`; its `run(ctx, input)` method is the
+deterministic body the engine executes and replays. Work happens in **steps** — local
+(`ctx.step`) or remote (`ctx.call`) — each a durable checkpoint.
+
+## Setup
+
+```ts title="checkout.workflow.ts"
+import { Workflow, DurableStep } from '@dudousxd/nestjs-durable';
+import { remoteStep, FatalError } from '@dudousxd/nestjs-durable-core';
+import type { WorkflowCtx } from '@dudousxd/nestjs-durable-core';
+import { Injectable } from '@nestjs/common';
+import { z } from 'zod';
+
+// 1. A typed remote step: the `name` is the contract a handler registers under.
+export const chargeCard = remoteStep({
+  name: 'payments.charge-card',
+  input: z.object({ orderId: z.string(), amountCents: z.number().int() }),
+  output: z.object({ chargeId: z.string() }),
+  retries: 3,
+});
+
+// 2. The workflow — plain linear code; ctx primitives are the only durable surface.
+@Workflow({ name: 'checkout', version: '1' })
+export class CheckoutWorkflow {
+  constructor(private readonly inventory: InventoryService) {} // normal DI
+
+  async run(ctx: WorkflowCtx, order: { id: string; total: number }) {
+    // Local step: runs in-process, checkpointed, retried up to `retries`.
+    await ctx.step('reserveStock', () => this.inventory.reserve(order.id), { retries: 3 });
+    // Remote step: dispatched over the transport, may run in another process/language.
+    const charge = await ctx.call(chargeCard, { orderId: order.id, amountCents: order.total });
+    return { chargeId: charge.chargeId };
+  }
+}
+
+// 3. A provider method handles the remote step in-process (with an in-process transport).
+@Injectable()
+export class PaymentsWorker {
+  @DurableStep('payments.charge-card')
+  async charge(input: { orderId: string; amountCents: number }) {
+    return { chargeId: `ch_${input.orderId}` };
+  }
+}
+```
+
+Register all three as providers (see the durable-setup skill).
+
+## Core patterns
+
+### Local step vs remote step
+
+- `ctx.step(name, fn, opts?)` runs `fn` **here** and checkpoints its return value. Use for local IO
+  (DB writes, calling a service the app owns).
+- `ctx.call(remoteStep, input, opts?)` dispatches over the transport to a handler registered under
+  the same `name` (a `@DurableStep` method, another process, or a Python worker). Inputs/outputs are
+  validated against the `remoteStep` zod schemas at the boundary.
+
+Both are first-class checkpoints: on crash/replay a `completed` one returns its saved result instead
+of re-executing.
+
+### Retries, backoff, and FatalError
+
+Per-step retry config lives in `opts`; throw `FatalError` to stop retrying a business failure a retry
+can't fix.
+
+```ts
+await ctx.step('charge', async () => {
+  const res = await this.stripe.charge(order);
+  if (res.declined) throw new FatalError('card declined', 'declined'); // fails the run now
+  return res;
+}, { retries: 5, backoff: 'exp', backoffMs: 200, jitter: true });
+```
+
+`StepOptions` fields: `retries`, `backoff` (`'fixed'` | `'exp'`), `backoffMs`, `backoffMaxMs`,
+`jitter`, `timeoutMs` (remote liveness), `compensate` (saga).
+
+### Fan-out and sagas
+
+Run steps concurrently with `Promise.all` — each step's position is taken in the synchronous prefix,
+so replay stays deterministic:
+
+```ts
+const [a, b] = await Promise.all([
+  ctx.step('a', () => doA()),
+  ctx.step('b', () => doB()),
+]);
+```
+
+Register a saga `compensate` undo on a step; if the run later fails, compensations run in reverse:
+
+```ts
+await ctx.step('reserve', () => this.inventory.reserve(id), {
+  compensate: () => this.inventory.release(id), // runs on later run failure, newest-first
+});
+```
+
+### Steps vs sub-process events
+
+A `ctx.step` / `ctx.call` is a durable, independently-replayed checkpoint. For pure visibility
+*inside* one step, emit sub-process events on the step logger — they are annotations, not
+checkpoints, and re-run if the step retries:
+
+```ts
+await ctx.step('process-batch', async (log) => {
+  for (const item of batch) {
+    await handle(item);
+    log.sub(item.id, 'ok'); // shown under the step; NOT a separate checkpoint
+  }
+});
+```
+
+## Common mistakes
+
+### 1. Doing durable work directly in the body instead of in a step
+
+```ts
+// ✗ Wrong — the write re-runs on every replay (not checkpointed)
+async run(ctx, order) {
+  await this.db.insert(order);        // re-executed each recovery → duplicate rows
+  return { ok: true };
+}
+
+// ✓ Correct — wrap side effects in a step so they checkpoint and run exactly once logically
+async run(ctx, order) {
+  await ctx.step('persist', () => this.db.insert(order));
+  return { ok: true };
+}
+```
+
+Only `ctx.step`/`ctx.call`/`ctx.transaction` results are checkpointed; raw work in the body re-runs
+on replay. Source: website/content/docs/concepts/durability.mdx.
+
+### 2. Mismatching the remoteStep `name` and the @DurableStep handler
+
+```ts
+// ✗ Wrong — handler name ≠ the remoteStep name, so ctx.call(chargeCard) finds no handler
+export const chargeCard = remoteStep({ name: 'payments.charge-card', /* ... */ });
+@DurableStep('payments.charge')                 // typo / mismatch
+async charge(input) { /* ... */ }
+
+// ✓ Correct — the string is the contract; it must match byte-for-byte
+@DurableStep('payments.charge-card')
+async charge(input) { /* ... */ }
+```
+
+The `name` string is the routing contract between `remoteStep`/`ctx.call` and the handler.
+Source: packages/core/src/remote-step-factory.ts, packages/nestjs/src/decorators.ts (`DurableStep`).
+
+### 3. Throwing a plain Error when you meant to stop retrying
+
+```ts
+// ✗ Wrong — a plain Error is retried up to `retries`, wasting attempts on an unfixable failure
+await ctx.step('charge', async () => {
+  if (card.declined) throw new Error('declined'); // retried 5x
+}, { retries: 5 });
+
+// ✓ Correct — FatalError fails the run immediately, no further attempts
+import { FatalError } from '@dudousxd/nestjs-durable-core';
+await ctx.step('charge', async () => {
+  if (card.declined) throw new FatalError('declined', 'card_declined');
+}, { retries: 5 });
+```
+
+Any thrown error is retried to the step's limit; only `FatalError` short-circuits retries.
+Source: packages/core/src/workflow-ctx.ts (`step` retry loop), packages/core/src/errors.ts.