@strav/durable 1.0.0-alpha.9 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/durable",
-  "version": "1.0.0-alpha.9",
+  "version": "1.0.1",
   "description": "Strav durable execution — crash-resumable sequential workflows on top of @strav/queue + Postgres. V1: sequential .step() with retries + saga compensation. V2 adds parallel/route/loop/sleep/waitForSignal.",
   "type": "module",
   "main": "./src/index.ts",
@@ -19,9 +19,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/kernel": "1.0.0-alpha.9",
-    "@strav/database": "1.0.0-alpha.9",
-    "@strav/queue": "1.0.0-alpha.9"
+    "@strav/kernel": "1.0.1",
+    "@strav/database": "1.0.1",
+    "@strav/queue": "1.0.1"
   },
   "peerDependencies": {
     "@types/bun": ">=1.3.14"

package/src/durable_runner.ts

@@ -2,7 +2,7 @@
  * `DurableRunner` — the engine that owns the durable execution state
  * machine.
  *
- * Three load-bearing methods:
+ * Four load-bearing methods:
  *
  *   1. `start(name, input)` — INSERTs a new run row, dispatches the
  *      first `DurableAdvanceJob` for it inside the same transaction
@@ -11,12 +11,11 @@
  *      queue.
  *
  *   2. `advance(runId)` — the job handler. Acquires a row lock,
- *      decides what step is next, looks for a completed journal
- *      entry to short-circuit (idempotent replay), runs the
- *      handler, journals the result, and either re-enqueues itself
- *      for the next step or — on failure — schedules a retry or
- *      kicks off compensation. The whole step body runs inside a
- *      DB transaction so partial writes can't escape.
+ *      resolves the node at `current_step`, dispatches by node-type
+ *      (`step` / `sleep` / `waitForSignal` / `parallel` / `route` /
+ *      `loop` / `childWorkflow`), journals the result, and either
+ *      re-enqueues itself, parks the run as `waiting`, or — on
+ *      terminal failure — kicks off compensation.
  *
  *   3. `compensate(runId)` — walks the journal in reverse order
  *      running each step's `compensate` callback. On clean
@@ -24,27 +23,44 @@
  *      compensation are logged but don't block the rest of the
  *      rollback (compensators must be idempotent).
  *
+ *   4. `signal(runId, signalName, payload?)` — wakes a run parked on
+ *      a `waitForSignal` node. Writes the journal entry, clears the
+ *      awaiting marker, dispatches an advance.
+ *
  * Apps don't usually call `advance` / `compensate` directly — the
  * `DurableAdvanceJob` and `DurableCompensateJob` classes wrap them.
  */
 
-import {
-  type Database,
-  PostgresDatabase,
-  type SchemaRegistry,
-} from '@strav/database'
+import { type Database, PostgresDatabase, type SchemaRegistry } from '@strav/database'
 import { type Logger, ulid } from '@strav/kernel'
 import type { JobClass, Queue } from '@strav/queue'
-import { RunNotFoundError } from './durable_error.ts'
-import type { DurableStep, DurableContext, RunSnapshot, RunStatus } from './types.ts'
+import { DurableError, RunNotFoundError } from './durable_error.ts'
+import type {
+  DurableContext,
+  DurableNode,
+  DurableStep,
+  RunSnapshot,
+  RunStatus,
+} from './types.ts'
 import type { WorkflowRegistry } from './workflow_registry.ts'
 
+interface RunState {
+  results: Record<string, unknown>
+  stepAttempts: Record<string, number>
+  /** `waitForSignal` markers — `{ [nodeName]: signalName }`. */
+  awaitingSignals?: Record<string, string>
+  /** Per-loop iteration state — `{ [nodeName]: { iteration, results[] } }`. */
+  loopState?: Record<string, { iteration: number; results: unknown[] }>
+  /** Per-child-workflow link — `{ [nodeName]: { childRunId } }`. */
+  childRunIds?: Record<string, string>
+}
+
 interface RunRow {
   id: string
   workflow_name: string
   input: Record<string, unknown> | string
   status: RunStatus
-  state: { results?: Record<string, unknown>; stepAttempts?: Record<string, number> } | string
+  state: RunState | string
   current_step: number
   result: Record<string, unknown> | string | null
   error: string | null
@@ -63,6 +79,22 @@ interface JournalRow {
   completed_at: Date
 }
 
+type Tx = { query: Database['query']; queryOne: Database['queryOne']; execute: Database['execute'] }
+
+type Outcome =
+  /** Node completed; advance cursor + re-dispatch. */
+  | { kind: 'completed'; value: unknown; attempt: number }
+  /** Node has retries left; re-dispatch with delay. */
+  | { kind: 'retry'; attempt: number; delaySec: number }
+  /** Node exhausted retries; journal + compensate. */
+  | { kind: 'failed'; attempt: number; error: string }
+  /**
+   * Node parked itself. `delaySec`, when set, schedules a wake-up
+   * advance — for sleep and child-workflow polling. Undefined for
+   * waitForSignal (an external `signal()` call resumes it).
+   */
+  | { kind: 'waiting'; delaySec?: number }
+
 export interface DurableRunnerOptions {
   db: PostgresDatabase
   queue: Queue
@@ -120,8 +152,6 @@ export class DurableRunner {
    * orphan either.
    */
   async start(workflowName: string, input: Record<string, unknown> = {}): Promise<string> {
-    // Validate workflow registration up-front so the caller sees a
-    // synchronous error rather than a never-advancing run row.
     this.registry.get(workflowName)
     const runId = ulid()
     await this.db.transaction(async (tx) => {
@@ -129,7 +159,7 @@ export class DurableRunner {
         `INSERT INTO "strav_workflow_runs"
            (id, workflow_name, input, status, state, current_step, result, error, created_at, updated_at)
          VALUES ($1, $2, $3::jsonb, 'pending', $4::jsonb, 0, NULL, NULL, now(), now())`,
-        [runId, workflowName, JSON.stringify(input), JSON.stringify({ results: {}, stepAttempts: {} })],
+        [runId, workflowName, JSON.stringify(input), JSON.stringify(emptyState())],
       )
       await this.queue.dispatch(this.advanceJob, { runId })
     })
@@ -148,133 +178,108 @@ export class DurableRunner {
   }
 
   /**
-   * Advance handler. Runs inside one transaction:
-   *
-   *   1. SELECT FOR UPDATE the run row (serializes concurrent advances).
-   *   2. Resolve the workflow + the step at `current_step`.
-   *   3. If a completed journal row already exists for this step,
-   *      treat the run as if the step just succeeded — bump
-   *      `current_step` and either enqueue the next or mark
-   *      `completed`.
-   *   4. Otherwise call the handler. On success: journal +
-   *      bump cursor + enqueue next (or mark `completed`). On
-   *      throw: track the attempt; if there are retries left,
-   *      enqueue a delayed advance; otherwise journal the failure
-   *      and kick off compensation.
+   * Advance handler. Loads the run, dispatches the current node by
+   * type, and either re-enqueues (`continue`), parks (`waiting`),
+   * retries with backoff, or kicks off compensation.
    */
   async advance(runId: string): Promise<void> {
-    const workflow = await this.db.transaction(async (tx) => {
+    const shouldContinue = await this.db.transaction(async (tx) => {
       const row = await tx.queryOne<RunRow>(
         `SELECT id, workflow_name, input, status, state, current_step, result, error, created_at, updated_at
          FROM "strav_workflow_runs" WHERE id = $1 FOR UPDATE`,
         [runId],
       )
       if (!row) throw new RunNotFoundError(runId)
-      if (row.status === 'completed' || row.status === 'failed') return null
+      if (row.status === 'completed' || row.status === 'failed') return false
 
       const wf = this.registry.get(row.workflow_name)
-      const state = parseJson(row.state) as {
-        results: Record<string, unknown>
-        stepAttempts: Record<string, number>
-      }
+      const state = parseJson(row.state) as RunState
+      ensureStateShape(state)
       const input = parseJson(row.input) as Record<string, unknown>
 
       if (row.current_step >= wf.steps.length) {
         await this.markCompleted(tx, runId, state.results)
-        return null
+        return false
       }
 
-      const step = wf.steps[row.current_step]!
+      const node = wf.steps[row.current_step] as DurableNode
 
-      // Idempotent replay — if we already journaled this step, skip
-      // the handler and just advance the cursor.
+      // Idempotent replay — if the node was already journaled
+      // completed, skip the handler.
       const journaled = await tx.queryOne<JournalRow>(
         `SELECT id, run_id, step_name, status, result, error, attempts, completed_at
          FROM "strav_workflow_journal" WHERE run_id = $1 AND step_name = $2`,
-        [runId, step.name],
+        [runId, node.name],
       )
       if (journaled?.status === 'completed') {
-        state.results[step.name] = parseJson(journaled.result)
+        state.results[node.name] = parseJson(journaled.result)
         await this.advanceCursor(tx, runId, row.current_step + 1, state)
-        // Continue outside the transaction so we don't hold the row
-        // lock across the next handler invocation.
-        return { wf, runId, status: 'continue' as const }
+        return true
       }
 
-      const attempt = (state.stepAttempts[step.name] ?? 0) + 1
+      const attempt = (state.stepAttempts[node.name] ?? 0) + 1
       const ctx: DurableContext = {
         input,
         results: state.results,
         runId,
         attempt,
       }
-      try {
-        const result = await step.handler(ctx)
-        await tx.execute(
-          `INSERT INTO "strav_workflow_journal"
-             (id, run_id, step_name, status, result, error, attempts, completed_at, created_at, updated_at)
-           VALUES ($1, $2, $3, 'completed', $4::jsonb, NULL, $5, now(), now(), now())`,
-          [ulid(), runId, step.name, JSON.stringify(result ?? null), attempt],
-        )
-        state.results[step.name] = result
-        delete state.stepAttempts[step.name]
-        await this.advanceCursor(tx, runId, row.current_step + 1, state)
-        return { wf, runId, status: 'continue' as const }
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err)
-        this.logger?.warn('Durable step failed', {
-          runId,
-          step: step.name,
-          attempt,
-          error: message,
-        })
-        if (attempt < step.maxAttempts) {
-          state.stepAttempts[step.name] = attempt
-          await tx.execute(
-            `UPDATE "strav_workflow_runs" SET state = $1::jsonb, updated_at = now() WHERE id = $2`,
-            [JSON.stringify(state), runId],
-          )
-          const delaySec = Math.max(0, step.backoff(attempt))
-          await this.queue.dispatchLater(delaySec, this.advanceJob, { runId })
-          return null
-        }
-        // Terminal — journal the failure, mark compensating, kick off
-        // compensation. The compensate handler walks back from the
-        // step BEFORE this one (no compensator for the step that
-        // just failed; there's nothing to roll back since the work
-        // didn't commit).
-        await tx.execute(
-          `INSERT INTO "strav_workflow_journal"
-             (id, run_id, step_name, status, result, error, attempts, completed_at, created_at, updated_at)
-           VALUES ($1, $2, $3, 'failed', NULL, $4, $5, now(), now(), now())`,
-          [ulid(), runId, step.name, message, attempt],
-        )
-        await tx.execute(
-          `UPDATE "strav_workflow_runs"
-             SET status = 'compensating', state = $1::jsonb, error = $2, updated_at = now()
-           WHERE id = $3`,
-          [JSON.stringify(state), message, runId],
-        )
-        await this.queue.dispatch(this.compensateJob, { runId })
-        return null
-      }
+      const outcome = await this.runNode(tx, node, ctx, state, runId, attempt)
+      return this.applyOutcome(tx, runId, row.current_step, node, state, outcome)
     })
 
-    // If the step succeeded (or was already journaled), re-enter to
-    // advance the next one. We do this OUTSIDE the original
-    // transaction so each step holds the row lock for the minimum
-    // necessary window — important when steps make external API
-    // calls that can be slow.
-    if (workflow?.status === 'continue') {
+    if (shouldContinue) {
       await this.queue.dispatch(this.advanceJob, { runId })
     }
   }
 
+  /**
+   * Wake a run parked on a `waitForSignal` node. Writes the journal
+   * entry with `payload` as the node's result, clears the awaiting
+   * marker, and dispatches a fresh advance job to resume the next
+   * node. No-op when no run is awaiting `signalName`.
+   */
+  async signal(runId: string, signalName: string, payload?: unknown): Promise<boolean> {
+    return this.db.transaction(async (tx) => {
+      const row = await tx.queryOne<RunRow>(
+        `SELECT id, workflow_name, input, status, state, current_step, result, error, created_at, updated_at
+         FROM "strav_workflow_runs" WHERE id = $1 FOR UPDATE`,
+        [runId],
+      )
+      if (!row) throw new RunNotFoundError(runId)
+      if (row.status !== 'waiting') return false
+      const state = parseJson(row.state) as RunState
+      ensureStateShape(state)
+      const awaiting = state.awaitingSignals ?? {}
+      const matchEntry = Object.entries(awaiting).find(([, name]) => name === signalName)
+      if (matchEntry === undefined) return false
+      const [nodeName] = matchEntry
+      // Journal the wake-up so replay sees the signal as already received.
+      await tx.execute(
+        `INSERT INTO "strav_workflow_journal"
+           (id, run_id, step_name, status, result, error, attempts, completed_at, created_at, updated_at)
+         VALUES ($1, $2, $3, 'completed', $4::jsonb, NULL, 1, now(), now(), now())`,
+        [ulid(), runId, nodeName, JSON.stringify(payload ?? null)],
+      )
+      delete awaiting[nodeName]
+      state.awaitingSignals = awaiting
+      state.results[nodeName] = payload ?? null
+      await tx.execute(
+        `UPDATE "strav_workflow_runs"
+           SET status = 'running', state = $1::jsonb, current_step = current_step + 1, updated_at = now()
+         WHERE id = $2`,
+        [JSON.stringify(state), runId],
+      )
+      await this.queue.dispatch(this.advanceJob, { runId })
+      return true
+    })
+  }
+
   /**
    * Compensate handler. Walks the journal in reverse, calling each
    * registered compensator. Compensators that throw are logged but
-   * don't halt the rollback — the rest still run. When the walk
-   * finishes the run lands in `failed`.
+   * don't halt the rollback. Only `step` nodes carry compensators in
+   * V2 — other node types are skipped.
    */
   async compensate(runId: string): Promise<void> {
     await this.db.transaction(async (tx) => {
@@ -287,7 +292,8 @@ export class DurableRunner {
       if (row.status !== 'compensating') return
 
       const wf = this.registry.get(row.workflow_name)
-      const state = parseJson(row.state) as { results: Record<string, unknown> }
+      const state = parseJson(row.state) as RunState
+      ensureStateShape(state)
       const input = parseJson(row.input) as Record<string, unknown>
 
       const journal = await tx.query<JournalRow>(
@@ -295,20 +301,16 @@ export class DurableRunner {
          FROM "strav_workflow_journal" WHERE run_id = $1 ORDER BY completed_at ASC`,
         [runId],
       )
-      // Build an ordered list of successfully-completed step names so we
-      // can walk back through `wf.steps` in declaration order and find
-      // each compensator. Failed-step rows are skipped — they hold no
-      // committed work to roll back.
-      const completedNames = new Set(
-        journal.filter((j) => j.status === 'completed').map((j) => j.step_name),
-      )
-      const stepsByName = new Map<string, DurableStep>(wf.steps.map((s) => [s.name, s]))
+      const completedNames = journal
+        .filter((j) => j.status === 'completed')
+        .map((j) => j.step_name)
+      const stepsByName = new Map<string, DurableNode>(wf.steps.map((s) => [s.name, s]))
 
       for (const name of [...completedNames].reverse()) {
-        const step = stepsByName.get(name)
-        if (!step?.compensate) continue
+        const node = stepsByName.get(name)
+        if (node?.type !== 'step' || !node.compensate) continue
         try {
-          await step.compensate({
+          await (node as DurableStep).compensate?.({
             input,
             results: state.results,
             runId,
@@ -332,10 +334,316 @@ export class DurableRunner {
     })
   }
 
+  // ─── Node-type dispatch ──────────────────────────────────────────────────
+
+  private async runNode(
+    tx: Tx,
+    node: DurableNode,
+    ctx: DurableContext,
+    state: RunState,
+    runId: string,
+    attempt: number,
+  ): Promise<Outcome> {
+    switch (node.type) {
+      case 'step':
+        return this.runStepLike(node, ctx, attempt, () => node.handler(ctx))
+      case 'sleep':
+        return this.runSleep(node, ctx, state, attempt)
+      case 'waitForSignal':
+        return this.runWaitForSignal(node, ctx, state)
+      case 'parallel':
+        return this.runStepLike(node, ctx, attempt, async () => {
+          const entries = Object.entries(node.branches)
+          const results = await Promise.all(
+            entries.map(async ([key, handler]) => [key, await handler(ctx)] as const),
+          )
+          return Object.fromEntries(results)
+        })
+      case 'route':
+        return this.runStepLike(node, ctx, attempt, async () => {
+          const key = await node.select(ctx)
+          const handler = node.branches[key]
+          if (handler === undefined) {
+            throw new DurableError(
+              `DurableRunner: route "${node.name}" returned unknown branch "${key}". Branches: ${Object.keys(node.branches).join(', ')}`,
+            )
+          }
+          const result = await handler(ctx)
+          return { branch: key, result }
+        })
+      case 'loop':
+        return this.runLoop(tx, node, ctx, state, runId, attempt)
+      case 'childWorkflow':
+        return this.runChildWorkflow(tx, node, ctx, state, runId, attempt)
+    }
+  }
+
+  /** Common retry/failure envelope for nodes that look like one handler. */
+  private async runStepLike(
+    node: { name: string; maxAttempts: number; backoff: (n: number) => number },
+    ctx: DurableContext,
+    attempt: number,
+    fn: () => Promise<unknown>,
+  ): Promise<Outcome> {
+    try {
+      const value = await fn()
+      return { kind: 'completed', value, attempt }
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err)
+      this.logger?.warn('Durable node failed', {
+        runId: ctx.runId,
+        node: node.name,
+        attempt,
+        error,
+      })
+      if (attempt < node.maxAttempts) {
+        return { kind: 'retry', attempt, delaySec: Math.max(0, node.backoff(attempt)) }
+      }
+      return { kind: 'failed', attempt, error }
+    }
+  }
+
+  private async runSleep(
+    node: import('./types.ts').DurableSleep,
+    ctx: DurableContext,
+    state: RunState,
+    attempt: number,
+  ): Promise<Outcome> {
+    const requested =
+      typeof node.delay === 'number' ? node.delay : await node.delay(ctx)
+    const delaySec = Math.max(0, Math.floor(requested))
+    const sleepKey = `__sleep__${node.name}`
+    const previouslyDispatched = (state as unknown as Record<string, unknown>)[sleepKey] as
+      | { dispatchedAt: number }
+      | undefined
+    if (previouslyDispatched !== undefined) {
+      const elapsedSec = (Date.now() - previouslyDispatched.dispatchedAt) / 1000
+      if (elapsedSec >= delaySec) {
+        return { kind: 'completed', value: { sleptSec: delaySec }, attempt }
+      }
+      // Spurious early wake-up — re-park.
+      return { kind: 'waiting', delaySec: Math.max(1, delaySec - elapsedSec) }
+    }
+    ;(state as unknown as Record<string, unknown>)[sleepKey] = { dispatchedAt: Date.now() }
+    return { kind: 'waiting', delaySec }
+  }
+
+  private async runWaitForSignal(
+    node: import('./types.ts').DurableWaitForSignal,
+    ctx: DurableContext,
+    state: RunState,
+  ): Promise<Outcome> {
+    const name = typeof node.signalName === 'string' ? node.signalName : node.signalName(ctx)
+    const awaiting = state.awaitingSignals ?? {}
+    awaiting[node.name] = name
+    state.awaitingSignals = awaiting
+    return { kind: 'waiting' }
+  }
+
+  private async runLoop(
+    tx: Tx,
+    node: import('./types.ts').DurableLoop,
+    ctx: DurableContext,
+    state: RunState,
+    runId: string,
+    attempt: number,
+  ): Promise<Outcome> {
+    const loops = state.loopState ?? {}
+    const slot = loops[node.name] ?? { iteration: 0, results: [] }
+    loops[node.name] = slot
+    state.loopState = loops
+
+    // Idempotent replay for this iteration — if the per-iteration
+    // journal row already exists, treat the iteration as done.
+    const iterName = `${node.name}#${slot.iteration}`
+    const iterJournal = await tx.queryOne<JournalRow>(
+      `SELECT id, run_id, step_name, status, result, error, attempts, completed_at
+       FROM "strav_workflow_journal" WHERE run_id = $1 AND step_name = $2`,
+      [runId, iterName],
+    )
+    if (iterJournal?.status === 'completed') {
+      slot.results.push(parseJson(iterJournal.result))
+      slot.iteration += 1
+    }
+
+    if (slot.iteration >= node.maxIterations) {
+      return { kind: 'failed', attempt, error: `loop exceeded maxIterations (${node.maxIterations})` }
+    }
+
+    let keepGoing: boolean
+    try {
+      keepGoing = await node.condition(ctx, slot.iteration)
+    } catch (err) {
+      return {
+        kind: 'failed',
+        attempt,
+        error: err instanceof Error ? err.message : String(err),
+      }
+    }
+    if (!keepGoing) {
+      return { kind: 'completed', value: [...slot.results], attempt }
+    }
+
+    try {
+      const value = await node.body({ ...ctx, iteration: slot.iteration })
+      // Journal this iteration before bumping; failure mid-write
+      // will replay this same iteration on resume (journal lookup
+      // above short-circuits).
+      await tx.execute(
+        `INSERT INTO "strav_workflow_journal"
+           (id, run_id, step_name, status, result, error, attempts, completed_at, created_at, updated_at)
+         VALUES ($1, $2, $3, 'completed', $4::jsonb, NULL, $5, now(), now(), now())`,
+        [ulid(), runId, iterName, JSON.stringify(value ?? null), attempt],
+      )
+      slot.results.push(value)
+      slot.iteration += 1
+      // Keep current_step pinned; re-dispatch advance to evaluate
+      // the next iteration in its own transaction.
+      await tx.execute(
+        `UPDATE "strav_workflow_runs" SET state = $1::jsonb, updated_at = now() WHERE id = $2`,
+        [JSON.stringify(state), runId],
+      )
+      // 'continue' via a sentinel — applyOutcome's `completed` path
+      // is reserved for cursor-advancing nodes; here we want to
+      // re-enter advance without moving the cursor.
+      return { kind: 'waiting', delaySec: 0 }
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err)
+      if (attempt < node.maxAttempts) {
+        return { kind: 'retry', attempt, delaySec: Math.max(0, node.backoff(attempt)) }
+      }
+      return { kind: 'failed', attempt, error }
+    }
+  }
+
+  private async runChildWorkflow(
+    tx: Tx,
+    node: import('./types.ts').DurableChildWorkflow,
+    ctx: DurableContext,
+    state: RunState,
+    runId: string,
+    attempt: number,
+  ): Promise<Outcome> {
+    const children = state.childRunIds ?? {}
+    state.childRunIds = children
+    let childId = children[node.name]
+
+    if (childId === undefined) {
+      let spec: { name: string; input?: Record<string, unknown> }
+      try {
+        spec = await node.start(ctx)
+      } catch (err) {
+        const error = err instanceof Error ? err.message : String(err)
+        if (attempt < 1) {
+          return { kind: 'retry', attempt, delaySec: 0 }
+        }
+        return { kind: 'failed', attempt, error }
+      }
+      childId = await this.start(spec.name, spec.input ?? {})
+      children[node.name] = childId
+      await tx.execute(
+        `UPDATE "strav_workflow_runs" SET state = $1::jsonb, updated_at = now() WHERE id = $2`,
+        [JSON.stringify(state), runId],
+      )
+      return { kind: 'waiting', delaySec: node.pollIntervalSec }
+    }
+
+    const child = await tx.queryOne<RunRow>(
+      `SELECT id, workflow_name, input, status, state, current_step, result, error, created_at, updated_at
+       FROM "strav_workflow_runs" WHERE id = $1`,
+      [childId],
+    )
+    if (!child) {
+      return {
+        kind: 'failed',
+        attempt,
+        error: `child workflow run "${childId}" disappeared`,
+      }
+    }
+    if (child.status === 'completed') {
+      return { kind: 'completed', value: parseJson(child.result), attempt }
+    }
+    if (child.status === 'failed') {
+      return {
+        kind: 'failed',
+        attempt,
+        error: child.error ?? 'child workflow failed without error message',
+      }
+    }
+    // pending / running / waiting / compensating → keep polling.
+    return { kind: 'waiting', delaySec: node.pollIntervalSec }
+  }
+
+  // ─── Outcome → state mutation ───────────────────────────────────────────
+
+  private async applyOutcome(
+    tx: Tx,
+    runId: string,
+    currentStep: number,
+    node: DurableNode,
+    state: RunState,
+    outcome: Outcome,
+  ): Promise<boolean> {
+    switch (outcome.kind) {
+      case 'completed':
+        await tx.execute(
+          `INSERT INTO "strav_workflow_journal"
+             (id, run_id, step_name, status, result, error, attempts, completed_at, created_at, updated_at)
+           VALUES ($1, $2, $3, 'completed', $4::jsonb, NULL, $5, now(), now(), now())`,
+          [ulid(), runId, node.name, JSON.stringify(outcome.value ?? null), outcome.attempt],
+        )
+        state.results[node.name] = outcome.value
+        delete state.stepAttempts[node.name]
+        if (node.type === 'loop' && state.loopState !== undefined) {
+          delete state.loopState[node.name]
+        }
+        if (node.type === 'childWorkflow' && state.childRunIds !== undefined) {
+          delete state.childRunIds[node.name]
+        }
+        clearSleepKey(state, node)
+        await this.advanceCursor(tx, runId, currentStep + 1, state)
+        return true
+      case 'retry':
+        state.stepAttempts[node.name] = outcome.attempt
+        await tx.execute(
+          `UPDATE "strav_workflow_runs" SET state = $1::jsonb, updated_at = now() WHERE id = $2`,
+          [JSON.stringify(state), runId],
+        )
+        await this.queue.dispatchLater(outcome.delaySec, this.advanceJob, { runId })
+        return false
+      case 'failed':
+        await tx.execute(
+          `INSERT INTO "strav_workflow_journal"
+             (id, run_id, step_name, status, result, error, attempts, completed_at, created_at, updated_at)
+           VALUES ($1, $2, $3, 'failed', NULL, $4, $5, now(), now(), now())`,
+          [ulid(), runId, node.name, outcome.error, outcome.attempt],
+        )
+        await tx.execute(
+          `UPDATE "strav_workflow_runs"
+             SET status = 'compensating', state = $1::jsonb, error = $2, updated_at = now()
+           WHERE id = $3`,
+          [JSON.stringify(state), outcome.error, runId],
+        )
+        await this.queue.dispatch(this.compensateJob, { runId })
+        return false
+      case 'waiting':
+        await tx.execute(
+          `UPDATE "strav_workflow_runs"
+             SET status = 'waiting', state = $1::jsonb, updated_at = now()
+           WHERE id = $2`,
+          [JSON.stringify(state), runId],
+        )
+        if (outcome.delaySec !== undefined) {
+          await this.queue.dispatchLater(outcome.delaySec, this.advanceJob, { runId })
+        }
+        return false
+    }
+  }
+
   // ─── Internal helpers ────────────────────────────────────────────────────
 
   private async markCompleted(
-    tx: Database | { execute: (s: string, p: unknown[]) => Promise<number> },
+    tx: Tx,
     runId: string,
     results: Record<string, unknown>,
   ): Promise<void> {
@@ -344,7 +652,7 @@ export class DurableRunner {
          SET status = 'completed', state = $1::jsonb, result = $2::jsonb, updated_at = now()
        WHERE id = $3`,
       [
-        JSON.stringify({ results, stepAttempts: {} }),
+        JSON.stringify({ ...emptyState(), results }),
         JSON.stringify(results),
         runId,
       ],
@@ -352,10 +660,10 @@ export class DurableRunner {
   }
 
   private async advanceCursor(
-    tx: { execute: (s: string, p: unknown[]) => Promise<number> },
+    tx: Tx,
     runId: string,
     nextStep: number,
-    state: { results: Record<string, unknown>; stepAttempts: Record<string, number> },
+    state: RunState,
   ): Promise<void> {
     await tx.execute(
       `UPDATE "strav_workflow_runs"
@@ -368,6 +676,22 @@ export class DurableRunner {
 
 // ─── Pure helpers ────────────────────────────────────────────────────────
 
+function emptyState(): RunState {
+  return { results: {}, stepAttempts: {} }
+}
+
+function ensureStateShape(state: RunState): void {
+  if (state.results === undefined) state.results = {}
+  if (state.stepAttempts === undefined) state.stepAttempts = {}
+}
+
+function clearSleepKey(state: RunState, node: DurableNode): void {
+  const key = `__sleep__${node.name}`
+  if (key in state) {
+    delete (state as unknown as Record<string, unknown>)[key]
+  }
+}
+
 function parseJson(value: unknown): unknown {
   if (value === null || value === undefined) return value
   if (typeof value === 'string') return JSON.parse(value)
@@ -375,7 +699,7 @@ function parseJson(value: unknown): unknown {
 }
 
 function toSnapshot(row: RunRow): RunSnapshot {
-  const state = parseJson(row.state) as { results?: Record<string, unknown> } | null
+  const state = parseJson(row.state) as RunState | null
   return {
     id: row.id,
     workflowName: row.workflow_name,

package/src/durable_workflow.ts

@@ -2,46 +2,58 @@
  * `DurableWorkflow` — the builder apps use to declare a named,
  * registered, crash-resumable workflow.
  *
- * Mirrors the `.step(name, handler, { compensate?, maxAttempts? })`
- * surface from `@strav/workflow` so simple migrations are mostly
- * copy-paste, but the semantics differ in three important ways:
+ * V1 surface: `.step(name, handler, options?)` — sequential, named,
+ * journaled, retried, optionally saga-compensated.
  *
- *   1. Workflows are *named* and live in a registry. Steps are looked
- *      up by name when an `advance` job picks them off the queue —
- *      apps don't pass closures to `runner.start()`.
+ * V2 surface adds five composite primitives that still occupy one
+ * cursor slot each:
  *
- *   2. Each step is its own crash boundary. A step that's already
- *      journaled completed is skipped on replay; a step that throws
- *      is retried up to `maxAttempts` with `backoff` (default
- *      exponential, capped at 60s); a step that exhausts its
- *      attempts triggers reverse-order saga compensation.
+ *   - `.sleep(name, delay)` — park for N seconds or a context-aware
+ *     deadline.
+ *   - `.waitForSignal(name, signalName)` — pause until
+ *     `runner.signal(runId, signalName, payload?)` fires.
+ *   - `.parallel(name, { branchA: fn, branchB: fn, ... })` — run
+ *     every branch in `Promise.all`; whole-or-nothing failure.
+ *   - `.route(name, select, branches)` — pick one branch by
+ *     predicate.
+ *   - `.loop(name, condition, body)` — iterate while `condition()`
+ *     holds; each iteration is its own journal row.
+ *   - `.childWorkflow(name, start)` — spawn another registered
+ *     workflow and wait on it.
  *
- *   3. Step handlers must be *resolvable across processes*. The
- *      registry holds the handler function; the queue payload carries
- *      only the run id + step name. Handlers can close over module-
- *      level state but NOT request-scoped variables — the
- *      `advance` job may run in a worker that never saw the request
- *      that started the workflow.
- *
- * V1 ships sequential `.step()` only. V2 adds `.parallel` / `.route`
- * / `.loop` / `.sleep` / `.waitForSignal` / `.childWorkflow`.
+ * Cursor model stays a flat integer (`current_step`) — every node,
+ * primitive or composite, occupies one slot. Internal sub-state
+ * (loop iteration counters, awaiting-signal names, child run ids)
+ * lives in the run row's `state` JSONB.
  */
 
 import { DurableError } from './durable_error.ts'
 import type {
+  DurableChildWorkflow,
+  DurableCompensator,
+  DurableContext,
+  DurableLoop,
+  DurableLoopContext,
+  DurableNode,
+  DurableParallel,
+  DurableRoute,
+  DurableSleep,
   DurableStep,
   DurableStepHandler,
   DurableStepOptions,
+  DurableWaitForSignal,
 } from './types.ts'
 
 const DEFAULT_MAX_ATTEMPTS = 3
+const DEFAULT_MAX_ITERATIONS = 1000
+const DEFAULT_CHILD_POLL_SEC = 2
 const MAX_BACKOFF_SECONDS = 60
 const defaultBackoff = (failedAttempt: number): number =>
   Math.min(2 ** failedAttempt, MAX_BACKOFF_SECONDS)
 
 export class DurableWorkflow {
   readonly name: string
-  private readonly _steps: DurableStep[] = []
+  private readonly _nodes: DurableNode[] = []
   private readonly _names = new Set<string>()
 
   constructor(name: string) {
@@ -51,9 +63,15 @@ export class DurableWorkflow {
     this.name = name
   }
 
-  /** Read-only snapshot of the queued steps. */
-  get steps(): readonly DurableStep[] {
-    return this._steps
+  /**
+   * Read-only snapshot of the declared nodes.
+   *
+   * Field is named `steps` for back-compat with V1 — every node
+   * (`step`, `sleep`, `parallel`, …) carries a `type` discriminator
+   * that callers branch on.
+   */
+  get steps(): readonly DurableNode[] {
+    return this._nodes
   }
 
   /**
@@ -70,28 +88,170 @@ export class DurableWorkflow {
    */
   step(name: string, handler: DurableStepHandler, options?: DurableStepOptions): this {
     this.claim(name)
-    const step: DurableStep = {
+    const node: DurableStep = {
       type: 'step',
       name,
       handler,
       maxAttempts: options?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
       backoff: options?.backoff ?? defaultBackoff,
     }
-    if (options?.compensate) step.compensate = options.compensate
-    this._steps.push(step)
+    if (options?.compensate) node.compensate = options.compensate
+    this._nodes.push(node)
+    return this
+  }
+
+  /**
+   * Park the run for `delay` seconds (or a context-aware function
+   * returning seconds). Marks the run `waiting`; the cursor advances
+   * once the delayed advance fires.
+   */
+  sleep(
+    name: string,
+    delay: number | ((ctx: DurableContext) => number | Promise<number>),
+  ): this {
+    this.claim(name)
+    const node: DurableSleep = { type: 'sleep', name, delay }
+    this._nodes.push(node)
+    return this
+  }
+
+  /**
+   * Pause until `runner.signal(runId, signalName, payload?)` fires.
+   * The payload becomes this node's result.
+   */
+  waitForSignal(
+    name: string,
+    signalName: string | ((ctx: DurableContext) => string),
+  ): this {
+    this.claim(name)
+    const node: DurableWaitForSignal = { type: 'waitForSignal', name, signalName }
+    this._nodes.push(node)
+    return this
+  }
+
+  /**
+   * Run every branch concurrently within a single advance. Returns
+   * a `{ [branchName]: result }` object. Any branch throw fails the
+   * whole node (retried + compensated together).
+   */
+  parallel(
+    name: string,
+    branches: Record<string, DurableStepHandler>,
+    options?: { maxAttempts?: number; backoff?: (failedAttempt: number) => number },
+  ): this {
+    this.claim(name)
+    if (Object.keys(branches).length === 0) {
+      throw new DurableError(
+        `DurableWorkflow("${this.name}").parallel("${name}"): at least one branch required.`,
+      )
+    }
+    const node: DurableParallel = {
+      type: 'parallel',
+      name,
+      branches,
+      maxAttempts: options?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+      backoff: options?.backoff ?? defaultBackoff,
+    }
+    this._nodes.push(node)
+    return this
+  }
+
+  /**
+   * Pick one branch by `select(ctx)` predicate. The chosen handler's
+   * return is the node's result; the chosen branch key is recorded
+   * in `results[name].branch`.
+   */
+  route(
+    name: string,
+    select: (ctx: DurableContext) => string | Promise<string>,
+    branches: Record<string, DurableStepHandler>,
+    options?: { maxAttempts?: number; backoff?: (failedAttempt: number) => number },
+  ): this {
+    this.claim(name)
+    if (Object.keys(branches).length === 0) {
+      throw new DurableError(
+        `DurableWorkflow("${this.name}").route("${name}"): at least one branch required.`,
+      )
+    }
+    const node: DurableRoute = {
+      type: 'route',
+      name,
+      select,
+      branches,
+      maxAttempts: options?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+      backoff: options?.backoff ?? defaultBackoff,
+    }
+    this._nodes.push(node)
+    return this
+  }
+
+  /**
+   * Repeat `body(ctx)` while `condition(ctx, iter)` returns true,
+   * up to `maxIterations` (default 1000). Each iteration is its own
+   * journal row keyed `<name>#<iter>` so a crash mid-loop resumes
+   * from the next un-journaled iteration. The node's result is the
+   * array of per-iteration returns.
+   */
+  loop(
+    name: string,
+    condition: (ctx: DurableContext, iter: number) => boolean | Promise<boolean>,
+    body: (ctx: DurableLoopContext) => Promise<unknown>,
+    options?: {
+      maxIterations?: number
+      maxAttempts?: number
+      backoff?: (failedAttempt: number) => number
+    },
+  ): this {
+    this.claim(name)
+    const node: DurableLoop = {
+      type: 'loop',
+      name,
+      condition,
+      body,
+      maxIterations: options?.maxIterations ?? DEFAULT_MAX_ITERATIONS,
+      maxAttempts: options?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+      backoff: options?.backoff ?? defaultBackoff,
+    }
+    this._nodes.push(node)
+    return this
+  }
+
+  /**
+   * Spawn a registered child workflow and wait for it to complete.
+   * The parent re-polls the child's status via a delayed advance —
+   * no parent_run_id column needed. Child `failed` propagates as a
+   * failure on this node.
+   */
+  childWorkflow(
+    name: string,
+    start: DurableChildWorkflow['start'],
+    options?: { pollIntervalSec?: number },
+  ): this {
+    this.claim(name)
+    const node: DurableChildWorkflow = {
+      type: 'childWorkflow',
+      name,
+      start,
+      pollIntervalSec: options?.pollIntervalSec ?? DEFAULT_CHILD_POLL_SEC,
+    }
+    this._nodes.push(node)
     return this
   }
 
-  /** Throw if the step name has already been used in this workflow. */
   private claim(name: string): void {
     if (!name) {
-      throw new DurableError(`DurableWorkflow("${this.name}"): step name must be non-empty.`)
+      throw new DurableError(`DurableWorkflow("${this.name}"): node name must be non-empty.`)
     }
     if (this._names.has(name)) {
       throw new DurableError(
-        `DurableWorkflow("${this.name}"): duplicate step name "${name}". Steps are journaled by name; collisions would break replay.`,
+        `DurableWorkflow("${this.name}"): duplicate node name "${name}". Nodes are journaled by name; collisions would break replay.`,
       )
     }
     this._names.add(name)
   }
 }
+
+// Re-export `DurableCompensator` so the index barrel doesn't need to
+// list it twice — it's part of `DurableStepOptions` and the
+// step-builder signature.
+export type { DurableCompensator }

package/src/index.ts

@@ -1,9 +1,16 @@
 // Public API of @strav/durable.
 //
-// Crash-resumable workflows on top of @strav/queue + Postgres. V1
-// ships sequential `.step()` with per-step retries and saga
-// compensation. V2 layers in parallel / route / loop / sleep /
-// waitForSignal / childWorkflow.
+// Crash-resumable workflows on top of @strav/queue + Postgres.
+// Builder surface on `DurableWorkflow`:
+//   - `.step(name, handler, opts?)` — sequential, retried, saga-compensated.
+//   - `.sleep(name, delay)` — park for a duration.
+//   - `.waitForSignal(name, signalName)` — pause until
+//     `runner.signal(runId, name, payload?)`.
+//   - `.parallel(name, branches)` — Promise.all-style fan-out.
+//   - `.route(name, select, branches)` — single-branch routing.
+//   - `.loop(name, condition, body)` — per-iteration journaled loop.
+//   - `.childWorkflow(name, start)` — spawn a registered workflow
+//     and wait for completion.
 
 export { defineDurable } from './define_durable.ts'
 export {
@@ -25,11 +32,19 @@ export { DurableWorkflow } from './durable_workflow.ts'
 export { JOURNAL_UNIQUE_INDEX, workflowJournalSchema } from './journal_schema.ts'
 export { workflowRunsSchema } from './runs_schema.ts'
 export type {
+  DurableChildWorkflow,
   DurableCompensator,
   DurableContext,
+  DurableLoop,
+  DurableLoopContext,
+  DurableNode,
+  DurableParallel,
+  DurableRoute,
+  DurableSleep,
   DurableStep,
   DurableStepHandler,
   DurableStepOptions,
+  DurableWaitForSignal,
   RunSnapshot,
   RunStatus,
 } from './types.ts'

package/src/types.ts

@@ -2,7 +2,7 @@
  * Public types for durable execution.
  *
  * A durable workflow is a *named*, registered definition: handlers are
- * keyed by step name so the runner can re-enter them across processes
+ * keyed by node name so the runner can re-enter them across processes
  * after a crash. Apps don't pass closures into `start()` — they pass
  * a workflow name + input.
  *
@@ -16,12 +16,31 @@
  * `durable:status` CLI command in a later slice).
  */
 
-export type RunStatus = 'pending' | 'running' | 'compensating' | 'completed' | 'failed'
+/**
+ * Run lifecycle states:
+ *
+ *   - `pending`     — row INSERTed; no advance has run yet.
+ *   - `running`     — a worker is mid-step or in-flight.
+ *   - `waiting`     — node parked itself (sleep, waitForSignal,
+ *                     childWorkflow). The cursor doesn't move until
+ *                     the wakeup condition fires.
+ *   - `compensating`— terminal failure; the saga is rolling back.
+ *   - `completed`   — every node finished; `result` populated.
+ *   - `failed`      — compensation done (or no compensation needed);
+ *                     `error` populated.
+ */
+export type RunStatus =
+  | 'pending'
+  | 'running'
+  | 'waiting'
+  | 'compensating'
+  | 'completed'
+  | 'failed'
 
 export interface DurableContext {
   /** Workflow input — the object passed to `DurableRunner.start(name, input)`. */
   readonly input: Record<string, unknown>
-  /** Results from every prior step, keyed by step name. */
+  /** Results from every prior node, keyed by node name. */
   readonly results: Record<string, unknown>
   /** Durable run id (the row PK). Useful for logging / correlation. */
   readonly runId: string
@@ -29,6 +48,12 @@ export interface DurableContext {
   readonly attempt: number
 }
 
+/** Context handed to a `.loop(...)` body — same as `DurableContext` plus the iteration counter. */
+export interface DurableLoopContext extends DurableContext {
+  /** 0-based iteration number. */
+  readonly iteration: number
+}
+
 export interface RunSnapshot {
   id: string
   workflowName: string
@@ -60,11 +85,12 @@ export interface DurableStepOptions {
   backoff?: (failedAttempt: number) => number
 }
 
+// ─── Node variants (V2) ──────────────────────────────────────────────────
+
 /**
- * Internal step record. Apps don't construct this directly — the
- * `DurableWorkflow` builder pushes one per `.step()` call. Exported
- * so tests and introspection tools can read the plan from
- * `workflow.steps`.
+ * One sequential step. The cursor advances by 1 once the handler
+ * succeeds. Failures retry up to `maxAttempts`; exhaustion triggers
+ * reverse-order saga compensation.
  */
 export interface DurableStep {
   type: 'step'
@@ -74,3 +100,116 @@ export interface DurableStep {
   maxAttempts: number
   backoff: (failedAttempt: number) => number
 }
+
+/**
+ * Park the run for a fixed duration. The runner schedules a delayed
+ * advance via `queue.dispatchLater(delaySec)` and marks the run as
+ * `waiting`. On wake-up the node is journaled and the cursor moves
+ * on.
+ *
+ * `delay` is either a number of seconds or a context-aware function
+ * that returns one (so apps can sleep until a wall-clock target
+ * encoded in `ctx.input` / `ctx.results`).
+ */
+export interface DurableSleep {
+  type: 'sleep'
+  name: string
+  delay: number | ((ctx: DurableContext) => number | Promise<number>)
+}
+
+/**
+ * Pause the run until an external `runner.signal(runId, signalName,
+ * payload?)` call fires. The signal's `payload` lands as the node's
+ * result. Useful for human-in-the-loop approvals, third-party
+ * webhooks, async-out / async-in handshakes.
+ *
+ * `signalName` is either a literal or a context-aware function (so
+ * the listener name can depend on `ctx.input`).
+ */
+export interface DurableWaitForSignal {
+  type: 'waitForSignal'
+  name: string
+  signalName: string | ((ctx: DurableContext) => string)
+}
+
+/**
+ * Run a set of named branches concurrently. Each branch is a single
+ * handler; the parallel node completes when every branch has — its
+ * result is `{ [branch]: result }`. If any branch throws, the WHOLE
+ * node fails and the failure path follows the same retry +
+ * compensation rules as `step`.
+ *
+ * V2 scope — no per-branch retries, no per-branch journaling. The
+ * whole `Promise.all(...)` runs inside one advance.
+ */
+export interface DurableParallel {
+  type: 'parallel'
+  name: string
+  branches: Record<string, DurableStepHandler>
+  maxAttempts: number
+  backoff: (failedAttempt: number) => number
+}
+
+/**
+ * Pick one of N named branches based on a `select(ctx)` predicate.
+ * The chosen branch's handler runs; its return lands as the node's
+ * result alongside the chosen key. Unknown selection keys throw.
+ */
+export interface DurableRoute {
+  type: 'route'
+  name: string
+  select: (ctx: DurableContext) => string | Promise<string>
+  branches: Record<string, DurableStepHandler>
+  maxAttempts: number
+  backoff: (failedAttempt: number) => number
+}
+
+/**
+ * Repeat `body(ctx, i)` while `condition(ctx, iter)` returns true,
+ * up to `maxIterations`. Each iteration is journaled separately
+ * (`<name>#<iter>`) so a crash mid-loop resumes from the next
+ * un-journaled iteration. The node's final result is the array of
+ * per-iteration returns.
+ */
+export interface DurableLoop {
+  type: 'loop'
+  name: string
+  condition: (ctx: DurableContext, iter: number) => boolean | Promise<boolean>
+  body: (ctx: DurableLoopContext) => Promise<unknown>
+  /** Safety ceiling on iterations. Default `1000`. */
+  maxIterations: number
+  maxAttempts: number
+  backoff: (failedAttempt: number) => number
+}
+
+/**
+ * Spawn a child workflow (by registered name) and wait for it to
+ * complete. The parent re-polls the child's status via a delayed
+ * advance — no parent_run_id column needed, no cross-row push. Child
+ * `failed` propagates as a failure on this node (which retries +
+ * compensates like any other).
+ *
+ * `start(ctx)` returns `{ name, input }` — the child workflow name
+ * (must be registered) and its input object.
+ */
+export interface DurableChildWorkflow {
+  type: 'childWorkflow'
+  name: string
+  start: (
+    ctx: DurableContext,
+  ) => Promise<{ name: string; input?: Record<string, unknown> }> | {
+    name: string
+    input?: Record<string, unknown>
+  }
+  /** How often the runner re-polls the child's status (seconds). Default `2`. */
+  pollIntervalSec: number
+}
+
+export type DurableNode =
+  | DurableStep
+  | DurableSleep
+  | DurableWaitForSignal
+  | DurableParallel
+  | DurableRoute
+  | DurableLoop
+  | DurableChildWorkflow