@strav/durable 0.4.31 → 1.0.0-alpha.8

package/src/types.ts

@@ -1,216 +1,76 @@
-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.
+ * 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
+ * after a crash. Apps don't pass closures into `start()` — they pass
+ * a workflow name + input.
+ *
+ * `DurableContext` is what each step handler receives. `results` is the
+ * accumulated typed return of every prior step; `runId` lets apps log
+ * + correlate with the durable record; `attempt` is 1-based and lets
+ * apps switch behavior on retry (e.g. tighten timeouts).
+ *
+ * `RunSnapshot` is what `DurableRunner.find(runId)` returns — the
+ * shape app code uses to poll a run from outside (UI status pages, the
+ * `durable:status` CLI command in a later slice).
  */
-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 ──────────────────────────────────────────────────────
+export type RunStatus = 'pending' | 'running' | 'compensating' | 'completed' | 'failed'
 
-/** Handler for sequential, parallel, and route steps. */
-export type DurableStepHandler = (ctx: DurableContext) => Promise<unknown>
+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. */
+  readonly results: Record<string, unknown>
+  /** Durable run id (the row PK). Useful for logging / correlation. */
+  readonly runId: string
+  /** 1-based retry counter for this step. `1` on first run. */
+  readonly attempt: number
+}
 
-/** Handler for loop steps — receives the iteration input + context. */
-export type DurableLoopHandler = (input: unknown, ctx: DurableContext) => Promise<unknown>
+export interface RunSnapshot {
+  id: string
+  workflowName: string
+  status: RunStatus
+  input: Record<string, unknown>
+  results: Record<string, unknown>
+  currentStep: number
+  result: Record<string, unknown> | null
+  error: string | null
+  createdAt: Date
+  updatedAt: Date
+}
 
-/** Route resolver — returns the branch key to dispatch to. */
-export type DurableRouteResolver = (ctx: DurableContext) => string | Promise<string>
+/** Step handler — receives the durable context, returns the step's result. */
+export type DurableStepHandler = (ctx: DurableContext) => Promise<unknown>
 
-/** Compensation handler for saga-style rollback. */
+/** Saga rollback handler. Same context shape; return ignored. */
 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'
+  /** Hard cap on attempts. Default `3`. Includes the first attempt. */
+  maxAttempts?: number
+  /**
+   * Backoff function — input is the attempt number that just failed
+   * (1-based), output is the delay in seconds before the next attempt.
+   * Default: exponential `2 ** attempt` capped at 60s.
+   */
+  backoff?: (failedAttempt: number) => number
 }
 
-// ── Step definitions ────────────────────────────────────────────────────────
-
-export interface SequentialStep {
+/**
+ * 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`.
+ */
+export interface DurableStep {
   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
+  maxAttempts: number
+  backoff: (failedAttempt: number) => number
 }

package/src/workflow_registry.ts

@@ -0,0 +1,49 @@
+/**
+ * `WorkflowRegistry` — name → `DurableWorkflow` lookup used by the
+ * advance / compensate handlers.
+ *
+ * Mirrors `JobRegistry` from `@strav/queue`: explicit registration on
+ * an instance, no module-singleton state. Each app builds one
+ * registry, registers its workflows, and hands it to the runner.
+ *
+ * Duplicate-name registration throws — the runner journals steps by
+ * (run, step name), so silently shadowing a registered workflow with
+ * a different shape would corrupt replays.
+ */
+
+import { DurableError, WorkflowNotRegisteredError } from './durable_error.ts'
+import type { DurableWorkflow } from './durable_workflow.ts'
+
+export class WorkflowRegistry {
+  private readonly workflows = new Map<string, DurableWorkflow>()
+
+  register(workflow: DurableWorkflow): this {
+    if (this.workflows.has(workflow.name)) {
+      throw new DurableError(
+        `WorkflowRegistry: workflow "${workflow.name}" is already registered. Refusing to shadow — re-name the workflow or restart the registry.`,
+      )
+    }
+    this.workflows.set(workflow.name, workflow)
+    return this
+  }
+
+  registerAll(workflows: readonly DurableWorkflow[]): this {
+    for (const wf of workflows) this.register(wf)
+    return this
+  }
+
+  /** Look up a workflow by name. Throws when missing. */
+  get(name: string): DurableWorkflow {
+    const wf = this.workflows.get(name)
+    if (!wf) throw new WorkflowNotRegisteredError(name, [...this.workflows.keys()])
+    return wf
+  }
+
+  has(name: string): boolean {
+    return this.workflows.has(name)
+  }
+
+  names(): string[] {
+    return [...this.workflows.keys()]
+  }
+}

package/CHANGELOG.md

@@ -1,26 +0,0 @@
-# @strav/durable
-
-## 0.4.26
-
-Initial release — durable, crash-resumable workflow execution.
-
-- `durable(name)` builder mirroring the `@strav/workflow` authoring API
-  (`.step` / `.parallel` / `.route` / `.loop` + `compensate`), plus durable-only
-  step types `.sleep`, `.waitForSignal`, and `.childWorkflow`.
-- Explicit-journal execution model (DBOS/Inngest style, no determinism sandbox):
-  every step is checkpointed to `_strav_workflow_journal`; `UNIQUE (run_id, step_id)`
-  makes redelivery idempotent.
-- Queue-driven progression — one top-level step = one `durable:advance`
-  `@strav/queue` job; the journal write + run-row update + next-job enqueue
-  commit in a single transaction, so the engine inherits crash-safety from the
-  queue. A workflow killed mid-execution resumes from the first incomplete step.
-- Suspend/resume: `waitForSignal` parks a run for an unbounded time holding no
-  process; `Durable.resume()` delivers the signal.
-- Durable timers via `.sleep` (survives process restarts).
-- Independently durable, parent-linked child workflows.
-- Journaled saga compensation — rollback is itself crash-safe.
-- Composes with `@strav/brain` — a step returning a `SuspendedRun` suspends the
-  run; resume re-enters the step (duck-typed, no `@strav/brain` dependency).
-- `WorkflowRun` — a `stateful()` ORM model over the run record, with a
-  `@strav/machine` run-status lifecycle.
-- `Durable.start` / `resume` / `status` / `list` / `cancel` / `recover`.

package/src/builder.ts

@@ -1,158 +0,0 @@
-import { DurableError } from './errors.ts'
-import type {
-  DurableStep,
-  DurableStepHandler,
-  DurableLoopHandler,
-  DurableRouteResolver,
-  DurableParallelEntry,
-  DurableStepOptions,
-  DurableLoopOptions,
-} from './types.ts'
-
-const DEFAULT_MAX_RETRIES = 3
-
-/**
- * Durable workflow builder.
- *
- * Mirrors the `@strav/workflow` authoring API (`.step` / `.parallel` /
- * `.route` / `.loop` + `compensate`) so plain workflow code is copy-paste
- * portable, and adds durable-only step types: `.sleep`, `.waitForSignal`,
- * and `.childWorkflow`.
- *
- * Built workflows are flat ordered step lists — there is no re-runnable
- * function body, so durability needs no determinism sandbox.
- *
- * @example
- * durable('milestone')
- *   .step('discover', async (ctx) => discover(ctx.input))
- *   .parallel('build', [
- *     { name: 'api', handler: async (ctx) => buildApi(ctx) },
- *     { name: 'ui',  handler: async (ctx) => buildUi(ctx) },
- *   ])
- *   .waitForSignal('signoff', 'founder-signoff')
- *   .step('ship', async (ctx) => ship(ctx))
- */
-export class DurableWorkflow {
-  readonly name: string
-  private readonly _steps: DurableStep[] = []
-  private readonly _names = new Set<string>()
-
-  constructor(name: string) {
-    this.name = name
-  }
-
-  /** The ordered, immutable step list. */
-  get steps(): readonly DurableStep[] {
-    return this._steps
-  }
-
-  private claim(name: string): void {
-    if (this._names.has(name)) {
-      throw new DurableError(
-        `Duplicate step name "${name}" in durable workflow "${this.name}".`
-      )
-    }
-    this._names.add(name)
-  }
-
-  /** Add a sequential step. Its result is stored in `ctx.results[name]`. */
-  step(name: string, handler: DurableStepHandler, options?: DurableStepOptions): this {
-    this.claim(name)
-    this._steps.push({
-      type: 'step',
-      name,
-      handler,
-      compensate: options?.compensate,
-      maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES,
-      retryBackoff: options?.retryBackoff ?? 'exponential',
-    })
-    return this
-  }
-
-  /** Run multiple handlers in parallel; each result is stored under its entry name. */
-  parallel(
-    name: string,
-    entries: DurableParallelEntry[],
-    options?: Pick<DurableStepOptions, 'maxRetries' | 'retryBackoff'>
-  ): this {
-    this.claim(name)
-    if (entries.length === 0) {
-      throw new DurableError(`Parallel step "${name}" must have at least one entry.`)
-    }
-    this._steps.push({
-      type: 'parallel',
-      name,
-      entries,
-      maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES,
-      retryBackoff: options?.retryBackoff ?? 'exponential',
-    })
-    return this
-  }
-
-  /** Route to a branch based on a resolver's return value. */
-  route(
-    name: string,
-    resolver: DurableRouteResolver,
-    branches: Record<string, DurableStepHandler>,
-    options?: Pick<DurableStepOptions, 'maxRetries' | 'retryBackoff'>
-  ): this {
-    this.claim(name)
-    this._steps.push({
-      type: 'route',
-      name,
-      resolver,
-      branches,
-      maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES,
-      retryBackoff: options?.retryBackoff ?? 'exponential',
-    })
-    return this
-  }
-
-  /** Run a handler in a loop until a condition is met or max iterations reached. */
-  loop(name: string, handler: DurableLoopHandler, options: DurableLoopOptions): this {
-    this.claim(name)
-    this._steps.push({
-      type: 'loop',
-      name,
-      handler,
-      maxIterations: options.maxIterations,
-      until: options.until,
-      feedback: options.feedback,
-      mapInput: options.mapInput,
-      maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
-      retryBackoff: options.retryBackoff ?? 'exponential',
-    })
-    return this
-  }
-
-  /** Durable timer — suspend the run and resume after `duration` (ms or a Date). */
-  sleep(name: string, duration: number | Date): this {
-    this.claim(name)
-    this._steps.push({ type: 'sleep', name, duration })
-    return this
-  }
-
-  /**
-   * Suspend the run until `Durable.resume(runId, signal, data)` is called.
-   * Holds no process while suspended — resumes exactly, even days later.
-   */
-  waitForSignal(name: string, signal: string, options?: { timeout?: number }): this {
-    this.claim(name)
-    this._steps.push({ type: 'signal', name, signal, timeout: options?.timeout })
-    return this
-  }
-
-  /**
-   * Spawn an independently durable child workflow and wait for it to finish.
-   * The child result is stored in `ctx.results[name]`.
-   */
-  childWorkflow(
-    name: string,
-    childName: string,
-    mapInput?: (ctx: import('./types.ts').DurableContext) => Record<string, unknown>
-  ): this {
-    this.claim(name)
-    this._steps.push({ type: 'child', name, childName, mapInput })
-    return this
-  }
-}

package/src/config.ts

@@ -1,36 +0,0 @@
-/** Engine-wide configuration for `@strav/durable`. */
-export interface DurableConfig {
-  /**
-   * The `@strav/queue` queue name durable jobs are dispatched on. Run a
-   * `Worker({ queue })` on this name to process durable workflows. Keeping
-   * it separate from app jobs lets durable work be scaled independently.
-   */
-  queue: string
-  /**
-   * Per-job timeout (ms) for `durable:advance` / `durable:compensate` jobs.
-   * Must comfortably exceed the slowest single step (e.g. an LLM call).
-   */
-  jobTimeout: number
-  /**
-   * Queue-level max attempts for durable jobs. This insures against *process
-   * crashes* only — application-level step retries are handled by the engine
-   * via the journal `attempt` count, independently of this.
-   */
-  maxAttempts: number
-}
-
-const config: DurableConfig = {
-  queue: 'durable',
-  jobTimeout: 600_000,
-  maxAttempts: 5,
-}
-
-/** Read the current durable engine configuration. */
-export function getConfig(): DurableConfig {
-  return config
-}
-
-/** Override durable engine configuration. Call before booting workers. */
-export function configureDurable(patch: Partial<DurableConfig>): void {
-  Object.assign(config, patch)
-}