@strav/durable 0.4.27

package/src/engine/suspended_run.ts

@@ -0,0 +1,24 @@
+/**
+ * Brain composition point — duck-typed, with no `@strav/brain` dependency.
+ *
+ * `@strav/brain`'s `AgentRunner.run()` returns either an `AgentResult` or a
+ * `SuspendedRun` ({ status: 'suspended', pendingToolCalls, state }). When a
+ * durable `.step` handler returns a `SuspendedRun`, the engine suspends the
+ * whole run and journals the snapshot; resuming the run re-enters the handler
+ * so it can call `runner.resume(...)`. The per-agent suspend nests inside the
+ * per-workflow suspend.
+ */
+
+/** A structural view of a `@strav/brain` `SuspendedRun`. */
+export interface SuspendedRunLike {
+  status: 'suspended'
+  state: unknown
+  pendingToolCalls: unknown
+}
+
+/** Structurally detect a brain `SuspendedRun` without importing `@strav/brain`. */
+export function isSuspendedRun(value: unknown): value is SuspendedRunLike {
+  if (typeof value !== 'object' || value === null) return false
+  const v = value as Record<string, unknown>
+  return v.status === 'suspended' && 'state' in v && 'pendingToolCalls' in v
+}

package/src/errors.ts

@@ -0,0 +1,21 @@
+import { StravError } from '@strav/kernel'
+
+/** Base error for the durable execution engine. */
+export class DurableError extends StravError {}
+
+/** Thrown when a run id does not exist. */
+export class RunNotFoundError extends DurableError {
+  constructor(public readonly runId: number) {
+    super(`Durable run ${runId} not found.`)
+  }
+}
+
+/** Thrown when a workflow name has no registered definition in this process. */
+export class WorkflowNotRegisteredError extends DurableError {
+  constructor(public readonly workflowName: string) {
+    super(
+      `Durable workflow "${workflowName}" is not registered. ` +
+        `Import the module that defines it before starting or advancing a run.`
+    )
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,16 @@
+import { DurableWorkflow } from './builder.ts'
+import { registry } from './registry.ts'
+
+/**
+ * Create a durable workflow and register it under `name`.
+ *
+ * @example
+ * export const milestone = durable('milestone')
+ *   .step('discover', async (ctx) => discover(ctx.input))
+ *   .step('ship', async (ctx) => ship(ctx))
+ */
+export function durable(name: string): DurableWorkflow {
+  const workflow = new DurableWorkflow(name)
+  registry.register(workflow)
+  return workflow
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+export { durable } from './helpers.ts'
+export { DurableWorkflow } from './builder.ts'
+export { Durable } from './durable.ts'
+export { registry } from './registry.ts'
+export { WorkflowRun } from './models/workflow_run.ts'
+export { runMachine } from './models/run_machine.ts'
+export { default as DurableProvider } from './providers/durable_provider.ts'
+export { ensureTables } from './schema.ts'
+export {
+  DurableError,
+  RunNotFoundError,
+  WorkflowNotRegisteredError,
+} from './errors.ts'
+export { WorkflowError, CompensationError } from '@strav/workflow'
+export type {
+  DurableContext,
+  DurableStep,
+  DurableStepHandler,
+  DurableLoopHandler,
+  DurableRouteResolver,
+  DurableParallelEntry,
+  DurableCompensator,
+  DurableStepOptions,
+  DurableLoopOptions,
+  SequentialStep,
+  ParallelStep,
+  RouteStep,
+  LoopStep,
+  SleepStep,
+  SignalStep,
+  ChildStep,
+  RunStatus,
+  JournalStatus,
+  StartResult,
+  ResumeResult,
+  RunStatusSnapshot,
+} from './types.ts'

package/src/models/index.ts

@@ -0,0 +1,3 @@
+export { WorkflowRun } from './workflow_run.ts'
+export { runMachine } from './run_machine.ts'
+export { loadJournal, writeJournal } from './journal.ts'

package/src/models/journal.ts

@@ -0,0 +1,54 @@
+import { sql } from '@strav/database'
+import type { JournalRecord, JournalWrite } from '../types.ts'
+import { parseJson } from '../util.ts'
+
+/**
+ * Load every journal entry for a run, keyed by `step_id`. Used (unlocked) at
+ * the start of an advance to short-circuit completed steps and sub-units.
+ */
+export async function loadJournal(runId: number): Promise<Map<string, JournalRecord>> {
+  const rows = (await sql`
+    SELECT "step_id", "status", "result", "error", "attempt"
+    FROM "_strav_workflow_journal"
+    WHERE "run_id" = ${runId}
+  `) as Record<string, unknown>[]
+
+  const map = new Map<string, JournalRecord>()
+  for (const r of rows) {
+    map.set(r.step_id as string, {
+      stepId: r.step_id as string,
+      status: r.status as JournalRecord['status'],
+      result: parseJson(r.result),
+      error: (r.error as string | null) ?? null,
+      attempt: Number(r.attempt),
+    })
+  }
+  return map
+}
+
+/**
+ * Append journal entries inside a transaction. `ON CONFLICT DO NOTHING` on
+ * `UNIQUE (run_id, step_id)` makes a redelivered step idempotent — the first
+ * write wins, later writes for the same `step_id` are no-ops.
+ */
+export async function writeJournal(
+  trx: { (strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown> },
+  runId: number,
+  writes: JournalWrite[]
+): Promise<void> {
+  for (const w of writes) {
+    await trx`
+      INSERT INTO "_strav_workflow_journal"
+        ("run_id", "step_id", "status", "result", "error", "attempt")
+      VALUES (
+        ${runId},
+        ${w.stepId},
+        ${w.status},
+        ${w.result === undefined ? null : JSON.stringify(w.result)},
+        ${w.error ?? null},
+        ${w.attempt}
+      )
+      ON CONFLICT ("run_id", "step_id") DO NOTHING
+    `
+  }
+}

package/src/models/run_machine.ts

@@ -0,0 +1,39 @@
+import { defineMachine } from '@strav/machine'
+
+/**
+ * The run-status lifecycle, modeled with `@strav/machine`.
+ *
+ *   pending → running ⇄ suspended
+ *                running → completed
+ *                running/suspended → compensating → failed
+ *                any non-terminal → canceled
+ *
+ * The engine writes status columns via raw SQL inside its atomic, locked
+ * transactions; this machine is the single declarative source of truth for
+ * which transitions are legal and powers the `WorkflowRun` `stateful()` model.
+ */
+export const runMachine = defineMachine({
+  field: 'status',
+  initial: 'pending',
+  states: [
+    'pending',
+    'running',
+    'suspended',
+    'compensating',
+    'completed',
+    'failed',
+    'canceled',
+  ],
+  transitions: {
+    begin: { from: 'pending', to: 'running' },
+    suspend: { from: 'running', to: 'suspended' },
+    wake: { from: 'suspended', to: 'running' },
+    complete: { from: 'running', to: 'completed' },
+    rollback: { from: ['running', 'suspended'], to: 'compensating' },
+    fail: { from: ['running', 'suspended', 'compensating'], to: 'failed' },
+    cancel: {
+      from: ['pending', 'running', 'suspended', 'compensating'],
+      to: 'canceled',
+    },
+  },
+})

package/src/models/workflow_run.ts

@@ -0,0 +1,36 @@
+import type { DateTime } from 'luxon'
+import { BaseModel, cast } from '@strav/database'
+import { stateful } from '@strav/machine'
+import type { Machine } from '@strav/machine'
+import { runMachine } from './run_machine.ts'
+
+/**
+ * ORM model over `_strav_workflow_runs` — the durable, queryable record of a
+ * workflow run (Albastr's "pollable open-Turn live record").
+ *
+ * Mixed with `stateful()` so a run's status is a first-class state machine:
+ * `run.is('running')`, `run.availableTransitions()`, `WorkflowRun.inState(...)`.
+ * The engine hot path writes status via raw SQL for atomicity; this model is
+ * for reads and for application code that wants to poll or query runs.
+ */
+export class WorkflowRun extends stateful(BaseModel, runMachine as Machine) {
+  static override get tableName(): string {
+    return '_strav_workflow_runs'
+  }
+
+  declare id: number
+  declare workflowName: string
+  @cast('json') declare input: Record<string, unknown>
+  declare status: string
+  @cast('json') declare state: Record<string, unknown>
+  declare currentStep: number
+  declare compensationCursor: number | null
+  declare parentRunId: number | null
+  declare parentStepId: string | null
+  declare awaitingSignal: string | null
+  declare wakeAt: DateTime | null
+  declare error: string | null
+  @cast('json') declare result: Record<string, unknown> | null
+  declare createdAt: DateTime
+  declare updatedAt: DateTime
+}

package/src/providers/durable_provider.ts

@@ -0,0 +1,31 @@
+import { ServiceProvider } from '@strav/kernel'
+import type { Application } from '@strav/kernel'
+import { Durable } from '../durable.ts'
+
+export interface DurableProviderOptions {
+  /** Whether to auto-create the durable engine tables. Default: `true`. */
+  ensureTables?: boolean
+}
+
+/**
+ * Registers the durable execution engine.
+ *
+ * On boot it creates the engine tables and registers the `durable:advance` /
+ * `durable:compensate` queue handlers. Run a `@strav/queue` `Worker` on the
+ * durable queue (default name `'durable'`) to actually process runs.
+ */
+export default class DurableProvider extends ServiceProvider {
+  readonly name = 'durable'
+  override readonly dependencies = ['database', 'queue']
+
+  constructor(private readonly options?: DurableProviderOptions) {
+    super()
+  }
+
+  override async boot(_app: Application): Promise<void> {
+    if (this.options?.ensureTables !== false) {
+      await Durable.ensureTables()
+    }
+    Durable.registerHandlers()
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,2 @@
+export { default as DurableProvider } from './durable_provider.ts'
+export type { DurableProviderOptions } from './durable_provider.ts'

package/src/registry.ts

@@ -0,0 +1,35 @@
+import type { DurableWorkflow } from './builder.ts'
+import { WorkflowNotRegisteredError } from './errors.ts'
+
+/**
+ * Process-wide registry of durable workflow definitions.
+ *
+ * A `durable:advance` queue job carries only a workflow *name* (not a
+ * closure), so the worker process must be able to look the definition up
+ * by name. Importing the module that calls `durable(...)` registers it.
+ */
+const workflows = new Map<string, DurableWorkflow>()
+
+export const registry = {
+  /** Register (or replace) a workflow definition by name. */
+  register(workflow: DurableWorkflow): void {
+    workflows.set(workflow.name, workflow)
+  },
+
+  /** Look up a workflow definition, throwing if it is not registered. */
+  get(name: string): DurableWorkflow {
+    const wf = workflows.get(name)
+    if (!wf) throw new WorkflowNotRegisteredError(name)
+    return wf
+  },
+
+  /** Whether a workflow name is registered. */
+  has(name: string): boolean {
+    return workflows.has(name)
+  },
+
+  /** Clear all registrations. For testing only. */
+  reset(): void {
+    workflows.clear()
+  },
+}

package/src/schema.ts

@@ -0,0 +1,70 @@
+import { sql } from '@strav/database'
+
+/**
+ * Create the durable engine's two tables if they do not exist.
+ *
+ * Follows the `@strav/queue` precedent — inline, idempotent DDL rather than
+ * a migration file (apps own their migrations directory). Safe to call on
+ * every boot. Post-1.0 schema changes must be additive
+ * (`ALTER TABLE ... ADD COLUMN IF NOT EXISTS`).
+ *
+ * - `_strav_workflow_runs`    — the durable record of a run; the pollable row.
+ * - `_strav_workflow_journal` — the per-step checkpoint log;
+ *   `UNIQUE (run_id, step_id)` is what makes redelivery idempotent.
+ */
+export async function ensureTables(): Promise<void> {
+  await sql`
+    CREATE TABLE IF NOT EXISTS "_strav_workflow_runs" (
+      "id"                  BIGSERIAL PRIMARY KEY,
+      "workflow_name"       VARCHAR(255) NOT NULL,
+      "input"               JSONB NOT NULL DEFAULT '{}',
+      "status"              VARCHAR(32)  NOT NULL DEFAULT 'pending',
+      "state"               JSONB NOT NULL DEFAULT '{}',
+      "current_step"        INT  NOT NULL DEFAULT 0,
+      "compensation_cursor" INT,
+      "parent_run_id"       BIGINT REFERENCES "_strav_workflow_runs"("id") ON DELETE CASCADE,
+      "parent_step_id"      VARCHAR(512),
+      "awaiting_signal"     VARCHAR(255),
+      "wake_at"             TIMESTAMPTZ,
+      "error"               TEXT,
+      "result"              JSONB,
+      "created_at"          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      "updated_at"          TIMESTAMPTZ NOT NULL DEFAULT NOW()
+    )
+  `
+
+  await sql`
+    CREATE INDEX IF NOT EXISTS "idx_strav_wf_runs_status"
+      ON "_strav_workflow_runs" ("status")
+  `
+
+  await sql`
+    CREATE INDEX IF NOT EXISTS "idx_strav_wf_runs_parent"
+      ON "_strav_workflow_runs" ("parent_run_id")
+  `
+
+  await sql`
+    CREATE TABLE IF NOT EXISTS "_strav_workflow_journal" (
+      "id"           BIGSERIAL PRIMARY KEY,
+      "run_id"       BIGINT NOT NULL REFERENCES "_strav_workflow_runs"("id") ON DELETE CASCADE,
+      "step_id"      VARCHAR(512) NOT NULL,
+      "status"       VARCHAR(16)  NOT NULL DEFAULT 'completed',
+      "result"       JSONB,
+      "error"        TEXT,
+      "attempt"      INT NOT NULL DEFAULT 1,
+      "completed_at" TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      UNIQUE ("run_id", "step_id")
+    )
+  `
+
+  await sql`
+    CREATE INDEX IF NOT EXISTS "idx_strav_wf_journal_run"
+      ON "_strav_workflow_journal" ("run_id")
+  `
+}
+
+/** Drop the durable engine's tables. For testing only. */
+export async function dropTables(): Promise<void> {
+  await sql`DROP TABLE IF EXISTS "_strav_workflow_journal"`
+  await sql`DROP TABLE IF EXISTS "_strav_workflow_runs"`
+}

package/src/types.ts

@@ -0,0 +1,216 @@
+import type { WorkflowContext } from '@strav/workflow'
+
+// ── Run + journal status ────────────────────────────────────────────────────
+
+/** Lifecycle status of a durable workflow run. */
+export type RunStatus =
+  | 'pending'
+  | 'running'
+  | 'suspended'
+  | 'compensating'
+  | 'completed'
+  | 'failed'
+  | 'canceled'
+
+/** Status of a single journal entry. */
+export type JournalStatus = 'completed' | 'failed'
+
+// ── Durable context ─────────────────────────────────────────────────────────
+
+/**
+ * Context passed to durable step handlers. Extends the `@strav/workflow`
+ * context (`input` + `results`) with durable-only accessors, so a plain
+ * `@strav/workflow` handler is copy-paste portable into a durable workflow.
+ */
+export interface DurableContext extends WorkflowContext {
+  /** The durable run id — stable across crashes/restarts. */
+  runId: number
+  /** The current retry attempt for the executing step (1-based). */
+  attempt: number
+  /** The name of the step currently executing. */
+  stepName: string
+  /** Read a completed step (or signal) result by name. */
+  signal<T = unknown>(name: string): T | undefined
+  /**
+   * The payload passed to the most recent `Durable.resume()` for this run.
+   * Used by a brain-agent step to resume a journaled `SuspendedRun`.
+   */
+  resumeData<T = unknown>(): T | undefined
+}
+
+// ── Handler signatures ──────────────────────────────────────────────────────
+
+/** Handler for sequential, parallel, and route steps. */
+export type DurableStepHandler = (ctx: DurableContext) => Promise<unknown>
+
+/** Handler for loop steps — receives the iteration input + context. */
+export type DurableLoopHandler = (input: unknown, ctx: DurableContext) => Promise<unknown>
+
+/** Route resolver — returns the branch key to dispatch to. */
+export type DurableRouteResolver = (ctx: DurableContext) => string | Promise<string>
+
+/** Compensation handler for saga-style rollback. */
+export type DurableCompensator = (ctx: DurableContext) => Promise<void>
+
+/** A single entry in a parallel step. */
+export interface DurableParallelEntry {
+  name: string
+  handler: DurableStepHandler
+  compensate?: DurableCompensator
+}
+
+// ── Step options ────────────────────────────────────────────────────────────
+
+export interface DurableStepOptions {
+  /** Saga compensation — run in reverse order if a later step fails. */
+  compensate?: DurableCompensator
+  /** Max total attempts before the step is declared failed. Default 3. */
+  maxRetries?: number
+  /** Backoff strategy between retries. Default 'exponential'. */
+  retryBackoff?: 'exponential' | 'linear'
+}
+
+export interface DurableLoopOptions {
+  maxIterations: number
+  until?: (result: unknown, iteration: number) => boolean
+  feedback?: (result: unknown) => unknown
+  mapInput?: (ctx: DurableContext) => unknown
+  maxRetries?: number
+  retryBackoff?: 'exponential' | 'linear'
+}
+
+// ── Step definitions ────────────────────────────────────────────────────────
+
+export interface SequentialStep {
+  type: 'step'
+  name: string
+  handler: DurableStepHandler
+  compensate?: DurableCompensator
+  maxRetries: number
+  retryBackoff: 'exponential' | 'linear'
+}
+
+export interface ParallelStep {
+  type: 'parallel'
+  name: string
+  entries: DurableParallelEntry[]
+  maxRetries: number
+  retryBackoff: 'exponential' | 'linear'
+}
+
+export interface RouteStep {
+  type: 'route'
+  name: string
+  resolver: DurableRouteResolver
+  branches: Record<string, DurableStepHandler>
+  maxRetries: number
+  retryBackoff: 'exponential' | 'linear'
+}
+
+export interface LoopStep {
+  type: 'loop'
+  name: string
+  handler: DurableLoopHandler
+  maxIterations: number
+  until?: (result: unknown, iteration: number) => boolean
+  feedback?: (result: unknown) => unknown
+  mapInput?: (ctx: DurableContext) => unknown
+  maxRetries: number
+  retryBackoff: 'exponential' | 'linear'
+}
+
+/** Durable timer — suspends the run and resumes after `duration`. */
+export interface SleepStep {
+  type: 'sleep'
+  name: string
+  duration: number | Date
+}
+
+/** Human-in-the-loop pause — suspends until `Durable.resume()` delivers the signal. */
+export interface SignalStep {
+  type: 'signal'
+  name: string
+  signal: string
+  timeout?: number
+}
+
+/** Spawn an independently durable child workflow and wait for it. */
+export interface ChildStep {
+  type: 'child'
+  name: string
+  childName: string
+  mapInput?: (ctx: DurableContext) => Record<string, unknown>
+}
+
+export type DurableStep =
+  | SequentialStep
+  | ParallelStep
+  | RouteStep
+  | LoopStep
+  | SleepStep
+  | SignalStep
+  | ChildStep
+
+// ── Public result shapes ────────────────────────────────────────────────────
+
+export interface StartResult {
+  runId: number
+  status: RunStatus
+}
+
+export interface ResumeResult {
+  /** Whether the signal was accepted (run suspended on a matching signal). */
+  accepted: boolean
+  status: RunStatus
+}
+
+export interface RunStatusSnapshot {
+  runId: number
+  workflowName: string
+  status: RunStatus
+  currentStep: number
+  totalSteps: number
+  awaitingSignal: string | null
+  wakeAt: string | null
+  results: Record<string, unknown>
+  error: string | null
+  parentRunId: number | null
+  children: RunStatusSnapshot[]
+}
+
+// ── Internal records ────────────────────────────────────────────────────────
+
+/** A hydrated `_strav_workflow_runs` row (snake_case columns → camelCase). */
+export interface RunRow {
+  id: number
+  workflowName: string
+  input: Record<string, unknown>
+  status: RunStatus
+  state: Record<string, unknown>
+  currentStep: number
+  compensationCursor: number | null
+  parentRunId: number | null
+  parentStepId: string | null
+  awaitingSignal: string | null
+  wakeAt: Date | null
+  error: string | null
+  result: Record<string, unknown> | null
+}
+
+/** A hydrated `_strav_workflow_journal` row. */
+export interface JournalRecord {
+  stepId: string
+  status: JournalStatus
+  result: unknown
+  error: string | null
+  attempt: number
+}
+
+/** A pending journal write produced by the step driver. */
+export interface JournalWrite {
+  stepId: string
+  status: JournalStatus
+  result?: unknown
+  error?: string
+  attempt: number
+}

package/src/util.ts

@@ -0,0 +1,25 @@
+/**
+ * Parse a JSONB column value. Bun's SQL driver may return a JSONB column as
+ * either an already-parsed object or a raw string depending on context — this
+ * normalizes both. `null`/`undefined` pass through unchanged.
+ */
+export function parseJson<T = unknown>(value: unknown): T {
+  if (value == null) return value as T
+  if (typeof value === 'string') {
+    try {
+      return JSON.parse(value) as T
+    } catch {
+      return value as T
+    }
+  }
+  return value as T
+}
+
+/** Compute the retry backoff delay (ms) for a given attempt number. */
+export function backoffDelay(
+  attempt: number,
+  strategy: 'exponential' | 'linear'
+): number {
+  if (strategy === 'linear') return attempt * 5_000
+  return Math.pow(2, attempt) * 1_000 + Math.random() * 1_000
+}

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "tests"]
+}