@strav/durable 0.4.31 → 1.0.0-alpha.9

package/src/engine/finalize.ts

@@ -1,111 +0,0 @@
-import { transaction } from '@strav/database'
-import type { RunRow } from '../types.ts'
-import { writeJournal } from '../models/journal.ts'
-import { enqueueAdvance, enqueueCompensate } from './enqueue.ts'
-import { lockRun, type Tx } from './run_store.ts'
-
-/** Merge a result patch into a run's accumulated state. */
-export function applyPatch(
-  state: Record<string, unknown>,
-  patch: Record<string, unknown>
-): Record<string, unknown> {
-  return { ...state, ...patch }
-}
-
-/**
- * Transition a run into compensation, rolling back from the step before the
- * one that failed. If nothing was completed before it, fail the run directly.
- */
-export async function beginCompensation(
-  trx: Tx,
-  run: RunRow,
-  failedStepIndex: number,
-  failure: string
-): Promise<void> {
-  const cursor = failedStepIndex - 1
-  if (cursor < 0) {
-    await failRun(trx, run, failure)
-    return
-  }
-  await trx`
-    UPDATE "_strav_workflow_runs"
-    SET "status" = 'compensating', "compensation_cursor" = ${cursor},
-        "error" = ${failure}, "updated_at" = NOW()
-    WHERE "id" = ${run.id}
-  `
-  await enqueueCompensate(trx, run.id, cursor)
-}
-
-/** Mark a run failed and, if it is a child, propagate failure to its parent. */
-export async function failRun(trx: Tx, run: RunRow, failure: string): Promise<void> {
-  await trx`
-    UPDATE "_strav_workflow_runs"
-    SET "status" = 'failed', "error" = ${failure}, "updated_at" = NOW()
-    WHERE "id" = ${run.id}
-  `
-  if (run.parentRunId != null) {
-    await finalizeChildIntoParent(trx, run, 'failed')
-  }
-}
-
-/**
- * Complete a run. Opens its own transaction (called as the terminal advance).
- * If the run is a child, fan in: write its result into the parent journal and
- * resume the parent — all in the same transaction, so the parent's
- * continuation job is visible only once the child result is.
- */
-export async function completeRun(runId: number): Promise<void> {
-  await transaction(async (trx: Tx) => {
-    const run = await lockRun(trx, runId)
-    if (!run || run.status !== 'running') return
-    await trx`
-      UPDATE "_strav_workflow_runs"
-      SET "status" = 'completed', "result" = ${JSON.stringify(run.state)},
-          "updated_at" = NOW()
-      WHERE "id" = ${runId}
-    `
-    if (run.parentRunId != null) {
-      await finalizeChildIntoParent(trx, run, 'completed')
-    }
-  })
-}
-
-/**
- * Fan a finished child run into its parent. Locks the parent (child→parent
- * lock order is consistent everywhere, so no deadlock).
- */
-export async function finalizeChildIntoParent(
-  trx: Tx,
-  childRun: RunRow,
-  outcome: 'completed' | 'failed'
-): Promise<void> {
-  const parentId = childRun.parentRunId
-  const childStepId = childRun.parentStepId
-  if (parentId == null || childStepId == null) return
-
-  const parent = await lockRun(trx, parentId)
-  if (!parent || parent.status !== 'suspended') return
-
-  const parentStepIndex = parent.currentStep
-
-  if (outcome === 'completed') {
-    await writeJournal(trx, parentId, [
-      { stepId: childStepId, status: 'completed', result: childRun.state, attempt: 1 },
-    ])
-    const newState = applyPatch(parent.state, { [childStepId]: childRun.state })
-    const next = parentStepIndex + 1
-    await trx`
-      UPDATE "_strav_workflow_runs"
-      SET "status" = 'running', "state" = ${JSON.stringify(newState)},
-          "current_step" = ${next}, "updated_at" = NOW()
-      WHERE "id" = ${parentId}
-    `
-    await enqueueAdvance(trx, parentId, next)
-  } else {
-    const failure = `child workflow "${childRun.workflowName}" failed`
-    await writeJournal(trx, parentId, [
-      { stepId: childStepId, status: 'failed', error: failure, attempt: 1 },
-    ])
-    await beginCompensation(trx, parent, parentStepIndex, failure)
-  }
-}

package/src/engine/index.ts

@@ -1,20 +0,0 @@
-export { advanceHandler } from './advance_handler.ts'
-export type { AdvancePayload } from './advance_handler.ts'
-export { compensateHandler } from './compensate_handler.ts'
-export type { CompensatePayload } from './compensate_handler.ts'
-export { runDurableStep } from './step_driver.ts'
-export type { StepOutcome } from './step_driver.ts'
-export { runCompensator } from './compensation_driver.ts'
-export { buildContext } from './context.ts'
-export { isSuspendedRun } from './suspended_run.ts'
-export type { SuspendedRunLike } from './suspended_run.ts'
-export { enqueueAdvance, enqueueCompensate } from './enqueue.ts'
-export { loadRun, lockRun, hydrateRun } from './run_store.ts'
-export type { Tx } from './run_store.ts'
-export {
-  applyPatch,
-  beginCompensation,
-  completeRun,
-  failRun,
-  finalizeChildIntoParent,
-} from './finalize.ts'

package/src/engine/run_store.ts

@@ -1,42 +0,0 @@
-import { sql } from '@strav/database'
-import type { RunRow } from '../types.ts'
-import { parseJson } from '../util.ts'
-
-/** A Bun SQL transaction handle (tagged-template callable). */
-export type Tx = (strings: TemplateStringsArray, ...values: unknown[]) => Promise<unknown>
-
-/** Hydrate a raw `_strav_workflow_runs` row into a typed `RunRow`. */
-export function hydrateRun(row: Record<string, unknown>): RunRow {
-  return {
-    id: Number(row.id),
-    workflowName: row.workflow_name as string,
-    input: parseJson<Record<string, unknown>>(row.input) ?? {},
-    status: row.status as RunRow['status'],
-    state: parseJson<Record<string, unknown>>(row.state) ?? {},
-    currentStep: Number(row.current_step),
-    compensationCursor:
-      row.compensation_cursor == null ? null : Number(row.compensation_cursor),
-    parentRunId: row.parent_run_id == null ? null : Number(row.parent_run_id),
-    parentStepId: (row.parent_step_id as string | null) ?? null,
-    awaitingSignal: (row.awaiting_signal as string | null) ?? null,
-    wakeAt: (row.wake_at as Date | null) ?? null,
-    error: (row.error as string | null) ?? null,
-    result: parseJson<Record<string, unknown>>(row.result) ?? null,
-  }
-}
-
-/** Load a run by id (unlocked read). */
-export async function loadRun(runId: number): Promise<RunRow | null> {
-  const rows = (await sql`
-    SELECT * FROM "_strav_workflow_runs" WHERE "id" = ${runId}
-  `) as Record<string, unknown>[]
-  return rows.length > 0 ? hydrateRun(rows[0]!) : null
-}
-
-/** Load a run `FOR UPDATE` inside a transaction (row-locked). */
-export async function lockRun(trx: Tx, runId: number): Promise<RunRow | null> {
-  const rows = (await trx`
-    SELECT * FROM "_strav_workflow_runs" WHERE "id" = ${runId} FOR UPDATE
-  `) as Record<string, unknown>[]
-  return rows.length > 0 ? hydrateRun(rows[0]!) : null
-}

package/src/engine/step_driver.ts

@@ -1,291 +0,0 @@
-import type {
-  DurableContext,
-  DurableStep,
-  JournalRecord,
-  JournalWrite,
-} from '../types.ts'
-import { backoffDelay } from '../util.ts'
-import { isSuspendedRun } from './suspended_run.ts'
-
-/**
- * The result of executing one top-level step. The engine applies it
- * atomically in Phase B (a row-locked transaction).
- */
-export type StepOutcome =
-  /** Step (and all sub-units) completed — journal results and move forward. */
-  | { kind: 'advance'; journal: JournalWrite[]; resultPatch: Record<string, unknown> }
-  /** A durable timer — journal, move forward, enqueue a delayed continuation. */
-  | { kind: 'sleep'; journal: JournalWrite[]; resultPatch: Record<string, unknown>; wakeAt: Date }
-  /** Suspend awaiting an external signal (human-in-the-loop). */
-  | { kind: 'suspend-signal'; signal: string }
-  /** Suspend on a brain agent `SuspendedRun` — resume re-enters this step. */
-  | { kind: 'suspend-agent'; stepName: string; snapshot: unknown }
-  /** Spawn a child workflow and wait for it. */
-  | { kind: 'await-child'; childName: string; childInput: Record<string, unknown>; childStepId: string }
-  /** Step failed but retries remain — re-enqueue the same step with backoff. */
-  | { kind: 'retry'; journal: JournalWrite[]; attempt: number; backoffMs: number; failure: string }
-  /** Step failed terminally — begin saga compensation. */
-  | { kind: 'compensate'; journal: JournalWrite[]; failure: string }
-
-type RetryableStep = {
-  name: string
-  maxRetries: number
-  retryBackoff: 'exponential' | 'linear'
-}
-
-function message(err: unknown): string {
-  return err instanceof Error ? err.message : String(err)
-}
-
-/** Decide between retry and compensation when a step's handler throws. */
-function failureOutcome(
-  step: RetryableStep,
-  attempt: number,
-  err: unknown,
-  partialJournal: JournalWrite[]
-): StepOutcome {
-  const failure = message(err)
-  if (attempt < step.maxRetries) {
-    return {
-      kind: 'retry',
-      journal: partialJournal,
-      attempt: attempt + 1,
-      backoffMs: backoffDelay(attempt, step.retryBackoff),
-      failure,
-    }
-  }
-  return {
-    kind: 'compensate',
-    journal: [
-      ...partialJournal,
-      { stepId: step.name, status: 'failed', error: failure, attempt },
-    ],
-    failure,
-  }
-}
-
-/**
- * Execute one top-level step against the journal. Completed sub-units
- * (parallel entries, loop iterations, the route decision) are read back from
- * the journal rather than re-run, so redelivery fast-forwards to the first
- * incomplete unit.
- */
-export async function runDurableStep(
-  step: DurableStep,
-  ctx: DurableContext,
-  journal: Map<string, JournalRecord>
-): Promise<StepOutcome> {
-  switch (step.type) {
-    case 'step':
-      return runSequential(step, ctx)
-    case 'parallel':
-      return runParallel(step, ctx, journal)
-    case 'route':
-      return runRoute(step, ctx, journal)
-    case 'loop':
-      return runLoop(step, ctx, journal)
-    case 'sleep':
-      return runSleep(step)
-    case 'signal':
-      return { kind: 'suspend-signal', signal: step.signal }
-    case 'child':
-      return runChild(step, ctx)
-  }
-}
-
-// ── step ────────────────────────────────────────────────────────────────────
-
-async function runSequential(
-  step: Extract<DurableStep, { type: 'step' }>,
-  ctx: DurableContext
-): Promise<StepOutcome> {
-  try {
-    const result = await step.handler(ctx)
-    if (isSuspendedRun(result)) {
-      return { kind: 'suspend-agent', stepName: step.name, snapshot: result }
-    }
-    return {
-      kind: 'advance',
-      journal: [{ stepId: step.name, status: 'completed', result, attempt: ctx.attempt }],
-      resultPatch: { [step.name]: result },
-    }
-  } catch (err) {
-    return failureOutcome(step, ctx.attempt, err, [])
-  }
-}
-
-// ── parallel ────────────────────────────────────────────────────────────────
-
-async function runParallel(
-  step: Extract<DurableStep, { type: 'parallel' }>,
-  ctx: DurableContext,
-  journal: Map<string, JournalRecord>
-): Promise<StepOutcome> {
-  const settled = await Promise.all(
-    step.entries.map(async entry => {
-      const jid = `${step.name}#${entry.name}`
-      const existing = journal.get(jid)
-      if (existing?.status === 'completed') {
-        return { entry, ok: true as const, result: existing.result, fresh: false }
-      }
-      try {
-        const result = await entry.handler(ctx)
-        return { entry, ok: true as const, result, fresh: true }
-      } catch (err) {
-        return { entry, ok: false as const, err, fresh: true }
-      }
-    })
-  )
-
-  const writes: JournalWrite[] = []
-  const resultPatch: Record<string, unknown> = {}
-  let firstError: unknown
-
-  for (const s of settled) {
-    if (s.ok) {
-      resultPatch[s.entry.name] = s.result
-      if (s.fresh) {
-        writes.push({
-          stepId: `${step.name}#${s.entry.name}`,
-          status: 'completed',
-          result: s.result,
-          attempt: ctx.attempt,
-        })
-      }
-    } else if (firstError === undefined) {
-      firstError = s.err
-    }
-  }
-
-  if (firstError === undefined) {
-    writes.push({
-      stepId: step.name,
-      status: 'completed',
-      result: resultPatch,
-      attempt: ctx.attempt,
-    })
-    return { kind: 'advance', journal: writes, resultPatch }
-  }
-  return failureOutcome(step, ctx.attempt, firstError, writes)
-}
-
-// ── route ───────────────────────────────────────────────────────────────────
-
-async function runRoute(
-  step: Extract<DurableStep, { type: 'route' }>,
-  ctx: DurableContext,
-  journal: Map<string, JournalRecord>
-): Promise<StepOutcome> {
-  const routeJid = `${step.name}#route`
-  const writes: JournalWrite[] = []
-  let routeKey: string
-
-  const existingRoute = journal.get(routeJid)
-  try {
-    if (existingRoute?.status === 'completed') {
-      routeKey = existingRoute.result as string
-    } else {
-      routeKey = await step.resolver(ctx)
-      writes.push({ stepId: routeJid, status: 'completed', result: routeKey, attempt: ctx.attempt })
-    }
-  } catch (err) {
-    return failureOutcome(step, ctx.attempt, err, [])
-  }
-
-  const branch = step.branches[routeKey]
-  try {
-    let result: unknown = null
-    const existingBranch = journal.get(step.name)
-    if (existingBranch?.status === 'completed') {
-      result = existingBranch.result
-    } else if (branch) {
-      result = await branch(ctx)
-    }
-    writes.push({ stepId: step.name, status: 'completed', result, attempt: ctx.attempt })
-    return {
-      kind: 'advance',
-      journal: writes,
-      resultPatch: branch ? { [step.name]: result } : {},
-    }
-  } catch (err) {
-    // Persist the route decision so a retry takes the same branch.
-    return failureOutcome(step, ctx.attempt, err, writes)
-  }
-}
-
-// ── loop ────────────────────────────────────────────────────────────────────
-
-async function runLoop(
-  step: Extract<DurableStep, { type: 'loop' }>,
-  ctx: DurableContext,
-  journal: Map<string, JournalRecord>
-): Promise<StepOutcome> {
-  let currentInput: unknown = step.mapInput ? step.mapInput(ctx) : ctx.input
-  let lastResult: unknown
-  let ran = false
-  const writes: JournalWrite[] = []
-
-  for (let i = 0; i < step.maxIterations; i++) {
-    ran = true
-    const jid = `${step.name}#iter${i}`
-    const existing = journal.get(jid)
-
-    if (existing?.status === 'completed') {
-      lastResult = existing.result
-    } else {
-      try {
-        lastResult = await step.handler(currentInput, ctx)
-      } catch (err) {
-        return failureOutcome(step, ctx.attempt, err, writes)
-      }
-      writes.push({ stepId: jid, status: 'completed', result: lastResult, attempt: ctx.attempt })
-    }
-
-    if (step.until?.(lastResult, i + 1)) break
-    if (step.feedback) currentInput = step.feedback(lastResult)
-  }
-
-  writes.push({ stepId: step.name, status: 'completed', result: lastResult ?? null, attempt: ctx.attempt })
-  return {
-    kind: 'advance',
-    journal: writes,
-    resultPatch: ran ? { [step.name]: lastResult } : {},
-  }
-}
-
-// ── sleep ───────────────────────────────────────────────────────────────────
-
-function runSleep(step: Extract<DurableStep, { type: 'sleep' }>): StepOutcome {
-  const wakeAt =
-    step.duration instanceof Date
-      ? step.duration
-      : new Date(Date.now() + step.duration)
-  return {
-    kind: 'sleep',
-    journal: [
-      {
-        stepId: step.name,
-        status: 'completed',
-        result: { wakeAt: wakeAt.toISOString() },
-        attempt: 1,
-      },
-    ],
-    resultPatch: {},
-    wakeAt,
-  }
-}
-
-// ── child ───────────────────────────────────────────────────────────────────
-
-function runChild(
-  step: Extract<DurableStep, { type: 'child' }>,
-  ctx: DurableContext
-): StepOutcome {
-  const childInput = step.mapInput ? step.mapInput(ctx) : ctx.input
-  return {
-    kind: 'await-child',
-    childName: step.childName,
-    childInput,
-    childStepId: step.name,
-  }
-}

package/src/engine/suspended_run.ts

@@ -1,24 +0,0 @@
-/**
- * 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

@@ -1,21 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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/models/index.ts

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

package/src/models/journal.ts

@@ -1,54 +0,0 @@
-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

@@ -1,39 +0,0 @@
-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

@@ -1,36 +0,0 @@
-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
-}