@strav/durable 0.4.31 → 1.0.0-alpha.8

package/src/durable.ts

@@ -1,268 +0,0 @@
-import { sql, transaction } from '@strav/database'
-import { Queue } from '@strav/queue'
-import { registry } from './registry.ts'
-import { ensureTables } from './schema.ts'
-import { configureDurable, type DurableConfig } from './config.ts'
-import { RunNotFoundError } from './errors.ts'
-import type {
-  ResumeResult,
-  RunStatus,
-  RunStatusSnapshot,
-  StartResult,
-} from './types.ts'
-import { writeJournal } from './models/journal.ts'
-import {
-  advanceHandler,
-  applyPatch,
-  compensateHandler,
-  enqueueAdvance,
-  enqueueCompensate,
-  loadRun,
-  lockRun,
-  type AdvancePayload,
-  type CompensatePayload,
-  type Tx,
-} from './engine/index.ts'
-
-/** Drop engine-internal keys so `results` reads like a `@strav/workflow` context. */
-function publicResults(state: Record<string, unknown>): Record<string, unknown> {
-  const out: Record<string, unknown> = {}
-  for (const [key, value] of Object.entries(state)) {
-    if (!key.startsWith('__strav_')) out[key] = value
-  }
-  return out
-}
-
-async function cancelRecursive(trx: Tx, runId: number): Promise<void> {
-  await trx`
-    UPDATE "_strav_workflow_runs"
-    SET "status" = 'canceled', "updated_at" = NOW()
-    WHERE "id" = ${runId}
-      AND "status" IN ('pending', 'running', 'suspended', 'compensating')
-  `
-  const children = (await trx`
-    SELECT "id" FROM "_strav_workflow_runs" WHERE "parent_run_id" = ${runId}
-  `) as Record<string, unknown>[]
-  for (const child of children) {
-    await cancelRecursive(trx, Number(child.id))
-  }
-}
-
-/**
- * Static facade for the durable execution engine.
- *
- * @example
- * await Durable.start('milestone', { projectId: 42 })
- * const snapshot = await Durable.status(runId)
- * await Durable.resume(runId, 'founder-signoff', { approved: true })
- */
-export class Durable {
-  /** Create the engine's tables (`_strav_workflow_runs`, `_strav_workflow_journal`). */
-  static async ensureTables(): Promise<void> {
-    await ensureTables()
-  }
-
-  /** Override engine configuration (queue name, job timeout, max attempts). */
-  static configure(patch: Partial<DurableConfig>): void {
-    configureDurable(patch)
-  }
-
-  /**
-   * Register the `durable:advance` / `durable:compensate` queue handlers.
-   * Called by `DurableProvider.boot`; idempotent.
-   */
-  static registerHandlers(): void {
-    Queue.handle('durable:advance', async (payload: unknown) => {
-      await advanceHandler(payload as AdvancePayload)
-    })
-    Queue.handle('durable:compensate', async (payload: unknown) => {
-      await compensateHandler(payload as CompensatePayload)
-    })
-  }
-
-  /**
-   * Start a new durable run. Inserts the run row and enqueues the first
-   * step's `durable:advance` job in a single transaction. Returns immediately
-   * — the workflow runs on the queue.
-   */
-  static async start(
-    workflowName: string,
-    input: Record<string, unknown> = {},
-    opts?: { parentRunId?: number; parentStepId?: string }
-  ): Promise<StartResult> {
-    registry.get(workflowName) // throws if not registered
-
-    return await transaction(async (trx: Tx) => {
-      const rows = (await trx`
-        INSERT INTO "_strav_workflow_runs"
-          ("workflow_name", "input", "status", "state", "current_step",
-           "parent_run_id", "parent_step_id")
-        VALUES (
-          ${workflowName}, ${JSON.stringify(input)}, 'running', '{}', 0,
-          ${opts?.parentRunId ?? null}, ${opts?.parentStepId ?? null}
-        )
-        RETURNING "id"
-      `) as Record<string, unknown>[]
-      const runId = Number(rows[0]!.id)
-      await enqueueAdvance(trx, runId, 0)
-      return { runId, status: 'running' as RunStatus }
-    })
-  }
-
-  /**
-   * Deliver a signal to a suspended run.
-   *
-   * - `waitForSignal` step → journals the payload, advances past the step.
-   * - A suspended brain-agent `.step` → stores the payload and re-enters the
-   *   step so the handler can call `runner.resume(...)`.
-   *
-   * Returns `{ accepted: false }` if the run is not suspended on a matching
-   * signal (idempotent — a duplicate or mismatched signal is a no-op).
-   */
-  static async resume(
-    runId: number,
-    signal: string,
-    data?: unknown
-  ): Promise<ResumeResult> {
-    return await transaction(async (trx: Tx) => {
-      const run = await lockRun(trx, runId)
-      if (!run) throw new RunNotFoundError(runId)
-      if (run.status !== 'suspended' || run.awaitingSignal !== signal) {
-        return { accepted: false, status: run.status }
-      }
-
-      const step = registry.get(run.workflowName).steps[run.currentStep]
-      if (!step) return { accepted: false, status: run.status }
-
-      if (step.type === 'signal') {
-        await writeJournal(trx, runId, [
-          { stepId: step.name, status: 'completed', result: data ?? null, attempt: 1 },
-        ])
-        const newState = applyPatch(run.state, { [step.name]: data ?? null })
-        const next = run.currentStep + 1
-        await trx`
-          UPDATE "_strav_workflow_runs"
-          SET "status" = 'running', "awaiting_signal" = NULL,
-              "state" = ${JSON.stringify(newState)}, "current_step" = ${next},
-              "updated_at" = NOW()
-          WHERE "id" = ${runId}
-        `
-        await enqueueAdvance(trx, runId, next)
-        return { accepted: true, status: 'running' as RunStatus }
-      }
-
-      if (step.type === 'step') {
-        // A suspended brain agent — re-enter the same step with the resume data.
-        const newState = applyPatch(run.state, { __strav_resume__: data ?? null })
-        await trx`
-          UPDATE "_strav_workflow_runs"
-          SET "status" = 'running', "awaiting_signal" = NULL,
-              "state" = ${JSON.stringify(newState)}, "updated_at" = NOW()
-          WHERE "id" = ${runId}
-        `
-        await enqueueAdvance(trx, runId, run.currentStep)
-        return { accepted: true, status: 'running' as RunStatus }
-      }
-
-      return { accepted: false, status: run.status }
-    })
-  }
-
-  /** Snapshot a run's live state (and one level of child runs). */
-  static async status(runId: number): Promise<RunStatusSnapshot> {
-    const run = await loadRun(runId)
-    if (!run) throw new RunNotFoundError(runId)
-
-    const totalSteps = registry.has(run.workflowName)
-      ? registry.get(run.workflowName).steps.length
-      : 0
-
-    const childRows = (await sql`
-      SELECT "id" FROM "_strav_workflow_runs"
-      WHERE "parent_run_id" = ${runId} ORDER BY "id"
-    `) as Record<string, unknown>[]
-    const children: RunStatusSnapshot[] = []
-    for (const child of childRows) {
-      children.push(await Durable.status(Number(child.id)))
-    }
-
-    return {
-      runId: run.id,
-      workflowName: run.workflowName,
-      status: run.status,
-      currentStep: run.currentStep,
-      totalSteps,
-      awaitingSignal: run.awaitingSignal,
-      wakeAt: run.wakeAt ? run.wakeAt.toISOString() : null,
-      results: publicResults(run.state),
-      error: run.error,
-      parentRunId: run.parentRunId,
-      children,
-    }
-  }
-
-  /** List runs, most recent first, optionally filtered by status / parent. */
-  static async list(filter?: {
-    status?: RunStatus
-    parentRunId?: number
-  }): Promise<RunStatusSnapshot[]> {
-    const status = filter?.status ?? null
-    const parentRunId = filter?.parentRunId ?? null
-    const rows = (await sql`
-      SELECT "id" FROM "_strav_workflow_runs"
-      WHERE (${status}::text IS NULL OR "status" = ${status})
-        AND (${parentRunId}::bigint IS NULL OR "parent_run_id" = ${parentRunId})
-      ORDER BY "id" DESC
-    `) as Record<string, unknown>[]
-
-    const snapshots: RunStatusSnapshot[] = []
-    for (const row of rows) {
-      snapshots.push(await Durable.status(Number(row.id)))
-    }
-    return snapshots
-  }
-
-  /** Cancel a run and all of its descendant child runs. */
-  static async cancel(runId: number): Promise<void> {
-    await transaction(async (trx: Tx) => {
-      await cancelRecursive(trx, runId)
-    })
-  }
-
-  /**
-   * Re-enqueue runs that are `running` / `compensating` but have no live
-   * `_strav_jobs` row — e.g. a job that dead-lettered. Returns the count
-   * recovered. Safe to run periodically (e.g. via the `@strav/queue` Scheduler).
-   */
-  static async recover(): Promise<number> {
-    const rows = (await sql`
-      SELECT r."id", r."status", r."current_step", r."compensation_cursor"
-      FROM "_strav_workflow_runs" r
-      WHERE r."status" IN ('running', 'compensating')
-        AND NOT EXISTS (
-          SELECT 1 FROM "_strav_jobs" j
-          WHERE j."job" IN ('durable:advance', 'durable:compensate')
-            AND (j."payload"->>'runId')::bigint = r."id"
-        )
-    `) as Record<string, unknown>[]
-
-    let recovered = 0
-    for (const row of rows) {
-      const runId = Number(row.id)
-      await transaction(async (trx: Tx) => {
-        if (row.status === 'running') {
-          await enqueueAdvance(trx, runId, Number(row.current_step))
-        } else if (row.compensation_cursor != null) {
-          await enqueueCompensate(trx, runId, Number(row.compensation_cursor))
-        }
-      })
-      recovered++
-    }
-    return recovered
-  }
-
-  /** Clear the workflow registry. For testing only. */
-  static reset(): void {
-    registry.reset()
-  }
-}

package/src/engine/advance_handler.ts

@@ -1,154 +0,0 @@
-import { transaction } from '@strav/database'
-import { registry } from '../registry.ts'
-import { loadJournal, writeJournal } from '../models/journal.ts'
-import { buildContext } from './context.ts'
-import { enqueueAdvance } from './enqueue.ts'
-import { applyPatch, beginCompensation, completeRun } from './finalize.ts'
-import { loadRun, lockRun, type Tx } from './run_store.ts'
-import { runDurableStep, type StepOutcome } from './step_driver.ts'
-
-/** Payload of a `durable:advance` job. */
-export interface AdvancePayload {
-  runId: number
-  stepIndex: number
-  attempt?: number
-}
-
-/**
- * The `durable:advance` queue handler — runs one top-level step of a run.
- *
- * Phase A (no lock): load the run, guard against stale redelivery, execute the
- * step. The step handler may take minutes — no row lock is held during it.
- * Phase B (`applyOutcome`, row-locked transaction): apply the outcome —
- * journal, advance/suspend/retry/compensate, enqueue the continuation — atomically.
- */
-export async function advanceHandler(payload: AdvancePayload): Promise<void> {
-  const { runId, stepIndex } = payload
-  const attempt = payload.attempt ?? 1
-
-  const run = await loadRun(runId)
-  if (!run) return
-  // Only a `running` run advances; `suspended`/terminal/`compensating` runs
-  // are handled by resume / the compensation chain / not at all.
-  if (run.status !== 'running') return
-  // Stale redelivery — the run already moved past this step.
-  if (run.currentStep !== stepIndex) return
-
-  const workflow = registry.get(run.workflowName)
-  const steps = workflow.steps
-
-  // Past the last step — the run is done.
-  if (stepIndex >= steps.length) {
-    await completeRun(runId)
-    return
-  }
-
-  const step = steps[stepIndex]!
-  const journal = await loadJournal(runId)
-  const ctx = buildContext(run, attempt, step.name)
-  const outcome = await runDurableStep(step, ctx, journal)
-  await applyOutcome(runId, stepIndex, outcome)
-}
-
-/** Phase B — apply a step outcome atomically under a `FOR UPDATE` lock. */
-async function applyOutcome(
-  runId: number,
-  stepIndex: number,
-  outcome: StepOutcome
-): Promise<void> {
-  await transaction(async (trx: Tx) => {
-    const run = await lockRun(trx, runId)
-    // Re-check under the lock: a resume / cancel / concurrent duplicate may
-    // have moved the run since Phase A.
-    if (!run || run.status !== 'running' || run.currentStep !== stepIndex) return
-
-    switch (outcome.kind) {
-      case 'advance': {
-        await writeJournal(trx, runId, outcome.journal)
-        const newState = applyPatch(run.state, outcome.resultPatch)
-        delete newState['__strav_resume__']
-        const next = stepIndex + 1
-        await trx`
-          UPDATE "_strav_workflow_runs"
-          SET "state" = ${JSON.stringify(newState)}, "current_step" = ${next},
-              "updated_at" = NOW()
-          WHERE "id" = ${runId}
-        `
-        await enqueueAdvance(trx, runId, next)
-        break
-      }
-
-      case 'sleep': {
-        await writeJournal(trx, runId, outcome.journal)
-        const newState = applyPatch(run.state, outcome.resultPatch)
-        const next = stepIndex + 1
-        const delay = Math.max(0, outcome.wakeAt.getTime() - Date.now())
-        await trx`
-          UPDATE "_strav_workflow_runs"
-          SET "state" = ${JSON.stringify(newState)}, "current_step" = ${next},
-              "wake_at" = ${outcome.wakeAt}, "updated_at" = NOW()
-          WHERE "id" = ${runId}
-        `
-        await enqueueAdvance(trx, runId, next, { delay })
-        break
-      }
-
-      case 'suspend-signal': {
-        await trx`
-          UPDATE "_strav_workflow_runs"
-          SET "status" = 'suspended', "awaiting_signal" = ${outcome.signal},
-              "updated_at" = NOW()
-          WHERE "id" = ${runId}
-        `
-        break
-      }
-
-      case 'suspend-agent': {
-        const newState = applyPatch(run.state, { [outcome.stepName]: outcome.snapshot })
-        await trx`
-          UPDATE "_strav_workflow_runs"
-          SET "status" = 'suspended', "awaiting_signal" = ${outcome.stepName},
-              "state" = ${JSON.stringify(newState)}, "updated_at" = NOW()
-          WHERE "id" = ${runId}
-        `
-        break
-      }
-
-      case 'await-child': {
-        const childRows = (await trx`
-          INSERT INTO "_strav_workflow_runs"
-            ("workflow_name", "input", "status", "state", "current_step",
-             "parent_run_id", "parent_step_id")
-          VALUES (
-            ${outcome.childName}, ${JSON.stringify(outcome.childInput)},
-            'running', '{}', 0, ${runId}, ${outcome.childStepId}
-          )
-          RETURNING "id"
-        `) as Record<string, unknown>[]
-        const childId = Number(childRows[0]!.id)
-        await enqueueAdvance(trx, childId, 0)
-        await trx`
-          UPDATE "_strav_workflow_runs"
-          SET "status" = 'suspended', "updated_at" = NOW()
-          WHERE "id" = ${runId}
-        `
-        break
-      }
-
-      case 'retry': {
-        await writeJournal(trx, runId, outcome.journal)
-        await enqueueAdvance(trx, runId, stepIndex, {
-          attempt: outcome.attempt,
-          delay: outcome.backoffMs,
-        })
-        break
-      }
-
-      case 'compensate': {
-        await writeJournal(trx, runId, outcome.journal)
-        await beginCompensation(trx, run, stepIndex, outcome.failure)
-        break
-      }
-    }
-  })
-}

package/src/engine/compensate_handler.ts

@@ -1,70 +0,0 @@
-import { transaction } from '@strav/database'
-import { registry } from '../registry.ts'
-import type { JournalWrite } from '../types.ts'
-import { loadJournal, writeJournal } from '../models/journal.ts'
-import { buildContext } from './context.ts'
-import { enqueueCompensate } from './enqueue.ts'
-import { failRun } from './finalize.ts'
-import { loadRun, lockRun, type Tx } from './run_store.ts'
-import { runCompensator } from './compensation_driver.ts'
-
-/** Payload of a `durable:compensate` job. */
-export interface CompensatePayload {
-  runId: number
-  compensateIndex: number
-}
-
-/**
- * The `durable:compensate` queue handler — rolls back one step of a failed
- * run. The chain walks `compensation_cursor` downward; each step's compensation
- * is journaled (`<step>#compensate`), so rollback resumes crash-safely. When
- * the cursor reaches below zero the run is marked `failed`.
- */
-export async function compensateHandler(payload: CompensatePayload): Promise<void> {
-  const { runId, compensateIndex } = payload
-
-  const run = await loadRun(runId)
-  if (!run) return
-  if (run.status !== 'compensating') return
-  if (run.compensationCursor !== compensateIndex) return
-
-  // Phase A — run the compensator outside the transaction (it may be slow).
-  let writes: JournalWrite[] = []
-  if (compensateIndex >= 0) {
-    const step = registry.get(run.workflowName).steps[compensateIndex]
-    if (step) {
-      const journal = await loadJournal(runId)
-      const alreadyDone =
-        journal.get(`${step.name}#compensate`)?.status === 'completed'
-      if (!alreadyDone) {
-        writes = await runCompensator(step, buildContext(run, 1, step.name), journal)
-      }
-    }
-  }
-
-  // Phase B — record the compensation and advance the cursor atomically.
-  await transaction(async (trx: Tx) => {
-    const locked = await lockRun(trx, runId)
-    if (
-      !locked ||
-      locked.status !== 'compensating' ||
-      locked.compensationCursor !== compensateIndex
-    ) {
-      return
-    }
-
-    if (writes.length > 0) await writeJournal(trx, runId, writes)
-
-    const next = compensateIndex - 1
-    if (next < 0) {
-      await failRun(trx, locked, locked.error ?? 'workflow failed')
-    } else {
-      await trx`
-        UPDATE "_strav_workflow_runs"
-        SET "compensation_cursor" = ${next}, "updated_at" = NOW()
-        WHERE "id" = ${runId}
-      `
-      await enqueueCompensate(trx, runId, next)
-    }
-  })
-}

package/src/engine/compensation_driver.ts

@@ -1,61 +0,0 @@
-import type {
-  DurableContext,
-  DurableStep,
-  JournalRecord,
-  JournalWrite,
-} from '../types.ts'
-
-function message(err: unknown): string {
-  return err instanceof Error ? err.message : String(err)
-}
-
-/**
- * Run the compensator(s) for one step during saga rollback.
- *
- * Mirrors `@strav/workflow`'s compensation surface: only `step` (sequential)
- * and `parallel` entries carry compensators, and only journaled-completed
- * units are compensated. The result is a single `<step>#compensate` journal
- * write — so the compensation chain is itself crash-safe (a redelivered
- * compensate job sees the marker and skips).
- *
- * A throwing compensator is best-effort: its error is recorded on the journal
- * row and the rollback still advances (it does not get stuck).
- */
-export async function runCompensator(
-  step: DurableStep,
-  ctx: DurableContext,
-  journal: Map<string, JournalRecord>
-): Promise<JournalWrite[]> {
-  const errors: string[] = []
-
-  if (step.type === 'step') {
-    if (journal.get(step.name)?.status === 'completed' && step.compensate) {
-      try {
-        await step.compensate(ctx)
-      } catch (err) {
-        errors.push(message(err))
-      }
-    }
-  } else if (step.type === 'parallel') {
-    for (const entry of step.entries) {
-      const done = journal.get(`${step.name}#${entry.name}`)?.status === 'completed'
-      if (done && entry.compensate) {
-        try {
-          await entry.compensate(ctx)
-        } catch (err) {
-          errors.push(`${entry.name}: ${message(err)}`)
-        }
-      }
-    }
-  }
-  // route / loop / sleep / signal / child have no compensators.
-
-  return [
-    {
-      stepId: `${step.name}#compensate`,
-      status: errors.length > 0 ? 'failed' : 'completed',
-      error: errors.length > 0 ? errors.join('; ') : undefined,
-      attempt: 1,
-    },
-  ]
-}

package/src/engine/context.ts

@@ -1,36 +0,0 @@
-import type { DurableContext, RunRow } from '../types.ts'
-
-const INTERNAL_PREFIX = '__strav_'
-
-/**
- * Build the `DurableContext` handed to step handlers from a run row.
- *
- * `results` is the run's accumulated `state` with engine-internal keys
- * (e.g. `__strav_resume__`) filtered out, so it reads exactly like a
- * `@strav/workflow` context. `resumeData()` exposes the raw resume payload.
- */
-export function buildContext(
-  run: RunRow,
-  attempt: number,
-  stepName: string
-): DurableContext {
-  const rawState = run.state ?? {}
-  const results: Record<string, unknown> = {}
-  for (const [key, value] of Object.entries(rawState)) {
-    if (!key.startsWith(INTERNAL_PREFIX)) results[key] = value
-  }
-
-  return {
-    input: run.input ?? {},
-    results,
-    runId: run.id,
-    attempt,
-    stepName,
-    signal<T = unknown>(name: string): T | undefined {
-      return results[name] as T | undefined
-    },
-    resumeData<T = unknown>(): T | undefined {
-      return rawState['__strav_resume__'] as T | undefined
-    },
-  }
-}

package/src/engine/enqueue.ts

@@ -1,62 +0,0 @@
-import { getConfig } from '../config.ts'
-
-/**
- * Enqueue durable jobs by INSERTing directly into `_strav_jobs` on the caller's
- * transaction handle.
- *
- * This is a deliberate, documented coupling to `@strav/queue`'s table. It is
- * NOT done via `Queue.push` because `Queue.push` runs its INSERT on a separate
- * connection — outside the engine's transaction — which would break the atomic
- * `{ journal write + run-row update + next-job enqueue }` commit that the whole
- * crash-safety story depends on. The clean long-term fix is an upstream
- * `Queue.pushTx(trx, ...)`; until then, the INSERT shape is replicated here.
- */
-
-/** A Bun SQL transaction handle (tagged-template callable). */
-type Tx = (strings: TemplateStringsArray, ...values: unknown[]) => Promise<unknown>
-
-async function enqueueJob(
-  trx: Tx,
-  job: string,
-  payload: unknown,
-  delay: number
-): Promise<void> {
-  const cfg = getConfig()
-  const availableAt = delay > 0 ? new Date(Date.now() + delay) : new Date()
-  await trx`
-    INSERT INTO "_strav_jobs"
-      ("queue", "job", "payload", "max_attempts", "timeout", "available_at")
-    VALUES (
-      ${cfg.queue},
-      ${job},
-      ${JSON.stringify(payload)},
-      ${cfg.maxAttempts},
-      ${cfg.jobTimeout},
-      ${availableAt}
-    )
-  `
-}
-
-/** Enqueue a `durable:advance` continuation for a run at a given step index. */
-export async function enqueueAdvance(
-  trx: Tx,
-  runId: number,
-  stepIndex: number,
-  opts?: { attempt?: number; delay?: number }
-): Promise<void> {
-  await enqueueJob(
-    trx,
-    'durable:advance',
-    { runId, stepIndex, attempt: opts?.attempt ?? 1 },
-    opts?.delay ?? 0
-  )
-}
-
-/** Enqueue a `durable:compensate` job for a run at a given compensation cursor. */
-export async function enqueueCompensate(
-  trx: Tx,
-  runId: number,
-  compensateIndex: number
-): Promise<void> {
-  await enqueueJob(trx, 'durable:compensate', { runId, compensateIndex }, 0)
-}