@humwick/server 0.0.0-stage → 0.130.1

package/node_modules/@humwick/kernel/workflow-journal.ts

@@ -0,0 +1,922 @@
+import type { Database } from "bun:sqlite";
+import { Buffer } from "node:buffer";
+import type { Clock, JsonValue, WaitCondition, WorkflowStatusName } from "./contract";
+
+/**
+ * Durable-workflow storage catalog (RFC 0001 / S4 §6), owned by the kernel.
+ *
+ * The step journal is deliberately independent of the scoped event log: bus
+ * retention may discard observer events, while an open workflow's replay source
+ * must live forever. This idempotent DDL is the single source of truth; `src/`
+ * installs it through the strangler re-export in `src/db/workflow-journal-schema.ts`
+ * so fresh and upgraded databases converge on exactly the same table and index
+ * shapes. The kernel never imports `src/`.
+ */
+export const WORKFLOW_JOURNAL_SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS workflow_instances (
+    id TEXT PRIMARY KEY CHECK (length(id) > 0),
+    module_name TEXT NOT NULL CHECK (length(module_name) > 0),
+    workflow_name TEXT NOT NULL CHECK (length(workflow_name) > 0),
+    idempotency_key TEXT NOT NULL CHECK (length(idempotency_key) > 0),
+    input TEXT NOT NULL CHECK (json_valid(input)),
+    initial_state TEXT NOT NULL CHECK (json_valid(initial_state)),
+    start_step TEXT NOT NULL CHECK (length(start_step) > 0),
+    status TEXT NOT NULL DEFAULT 'pending'
+      CHECK (status IN ('pending', 'running', 'sleeping', 'waiting', 'done', 'failed', 'canceled')),
+    sleep_until INTEGER,
+    wait_for TEXT CHECK (wait_for IS NULL OR (json_valid(wait_for) AND json_type(wait_for) = 'object')),
+    output TEXT CHECK (output IS NULL OR json_valid(output)),
+    failure TEXT CHECK (failure IS NULL OR json_valid(failure)),
+    journal_cursor INTEGER NOT NULL DEFAULT 0 CHECK (journal_cursor >= 0),
+    journal_pruned_through INTEGER NOT NULL DEFAULT 0 CHECK (journal_pruned_through >= 0),
+    executor_lease_owner TEXT,
+    executor_lease_token TEXT,
+    executor_lease_version INTEGER NOT NULL DEFAULT 0 CHECK (executor_lease_version >= 0),
+    executor_lease_acquired_at INTEGER,
+    executor_lease_expires_at INTEGER,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    closed_at INTEGER,
+    retention_until INTEGER,
+    -- Generic owner column (KAPI-1 / decision 3): the creator's actor, stamped from
+    -- ctx.principal.actor at ctx.workflows.start. NULL for system/migrated instances (the
+    -- accepted "creator-invisible" divergence). Unlocks a generic per-creator filter that
+    -- lives only in module entity fields today.
+    created_by TEXT,
+    -- Pause control flag (KAPI-1, Option A): orthogonal to status, so the underlying
+    -- pending/running/sleeping/waiting is preserved verbatim. When non-NULL the driver
+    -- work-lists AND the lease-acquire predicate skip the instance, so a paused instance
+    -- runs no further steps; resume clears it and the original deadline/condition fires.
+    paused_at INTEGER,
+    CHECK (journal_pruned_through <= journal_cursor),
+    CHECK (
+      (executor_lease_owner IS NULL AND executor_lease_token IS NULL
+        AND executor_lease_acquired_at IS NULL AND executor_lease_expires_at IS NULL)
+      OR
+      (executor_lease_owner IS NOT NULL AND executor_lease_token IS NOT NULL
+        AND executor_lease_acquired_at IS NOT NULL AND executor_lease_expires_at > executor_lease_acquired_at)
+    ),
+    UNIQUE(module_name, workflow_name, idempotency_key)
+  );
+  CREATE INDEX IF NOT EXISTS idx_workflow_instances_open
+    ON workflow_instances(status, updated_at);
+  CREATE INDEX IF NOT EXISTS idx_workflow_instances_timer
+    ON workflow_instances(status, sleep_until) WHERE sleep_until IS NOT NULL;
+  CREATE INDEX IF NOT EXISTS idx_workflow_instances_wait
+    ON workflow_instances(status) WHERE wait_for IS NOT NULL;
+  CREATE INDEX IF NOT EXISTS idx_workflow_instances_lease
+    ON workflow_instances(status, executor_lease_expires_at);
+  CREATE INDEX IF NOT EXISTS idx_workflow_instances_retention
+    ON workflow_instances(status, retention_until) WHERE retention_until IS NOT NULL;
+  CREATE INDEX IF NOT EXISTS idx_workflow_instances_creator
+    ON workflow_instances(created_by, status);
+  -- O(1) empty-path probe for the periodic journal prune (#3018): only closed instances that still
+  -- hold journal rows live here, so drained history never slows the lock-free EXISTS.
+  CREATE INDEX IF NOT EXISTS idx_workflow_instances_prunable
+    ON workflow_instances(retention_until)
+    WHERE retention_until IS NOT NULL AND status IN ('done', 'failed', 'canceled')
+      AND journal_cursor > journal_pruned_through;
+
+  CREATE TABLE IF NOT EXISTS workflow_step_journal (
+    instance_id TEXT NOT NULL REFERENCES workflow_instances(id),
+    seq INTEGER NOT NULL CHECK (seq > 0),
+    step_index INTEGER NOT NULL CHECK (step_index >= 0),
+    step_name TEXT NOT NULL CHECK (length(step_name) > 0),
+    attempt INTEGER NOT NULL CHECK (attempt > 0),
+    outcome TEXT NOT NULL CHECK (outcome IN ('completed', 'failed')),
+    state_snapshot TEXT NOT NULL CHECK (json_valid(state_snapshot)),
+    result TEXT NOT NULL CHECK (json_valid(result)),
+    sleep_until INTEGER,
+    wait_for TEXT CHECK (wait_for IS NULL OR (json_valid(wait_for) AND json_type(wait_for) = 'object')),
+    started_at INTEGER NOT NULL,
+    completed_at INTEGER NOT NULL CHECK (completed_at >= started_at),
+    PRIMARY KEY (instance_id, seq)
+  );
+  CREATE UNIQUE INDEX IF NOT EXISTS idx_workflow_step_journal_attempt
+    ON workflow_step_journal(instance_id, step_index, attempt);
+  CREATE INDEX IF NOT EXISTS idx_workflow_step_journal_step
+    ON workflow_step_journal(instance_id, step_index, outcome);
+`;
+
+/** How long a closed run's journal is kept before the prune job may delete it (#3018). */
+export const WORKFLOW_JOURNAL_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+
+const WORKFLOW_JOURNAL_COLUMNS = `
+  instance_id, seq, step_index, step_name, attempt, outcome, state_snapshot, result,
+  sleep_until, wait_for, started_at, completed_at
+`;
+
+/** True when `column` already exists on `table` (via `PRAGMA table_info`). */
+function columnExists(db: Database, table: string, column: string): boolean {
+  const cols = db.query(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
+  return cols.some((c) => c.name === column);
+}
+
+/**
+ * Install the journal catalog on the given handle, rebuilding the original cascading
+ * FK without data loss. Mirrors `ensureEventLogSchema(db)` (`event-log.ts`): the catalog
+ * is kernel-owned and installed on the caller's shared connection.
+ */
+export function ensureWorkflowJournalSchema(db: Database): void {
+  const tableSql = (db.query(`SELECT sql FROM sqlite_master
+    WHERE type = 'table' AND name = 'workflow_step_journal'`).get() as { sql?: string } | undefined)?.sql;
+  const hasDeleteCascade = tableSql?.toUpperCase().includes("ON DELETE CASCADE") ?? false;
+  const instancesExists = (db.query(`SELECT 1 FROM sqlite_master
+    WHERE type = 'table' AND name = 'workflow_instances'`).get() as unknown) != null;
+
+  db.transaction(() => {
+    // Additive column migration for pre-existing databases (KAPI-1): a bare
+    // `CREATE TABLE IF NOT EXISTS` cannot add a column to an already-present table, and the new
+    // `idx_workflow_instances_creator` index in the DDL references `created_by`, so the columns
+    // must land BEFORE the schema blob runs its index creation. A fresh database skips this — the
+    // columns are already in the CREATE TABLE below.
+    if (instancesExists) {
+      if (!columnExists(db, "workflow_instances", "created_by")) {
+        db.run("ALTER TABLE workflow_instances ADD COLUMN created_by TEXT");
+      }
+      if (!columnExists(db, "workflow_instances", "paused_at")) {
+        db.run("ALTER TABLE workflow_instances ADD COLUMN paused_at INTEGER");
+      }
+    }
+
+    if (hasDeleteCascade) {
+      db.run("ALTER TABLE workflow_step_journal RENAME TO workflow_step_journal_cascade_legacy");
+      // Explicit index names survive a table rename and would make the canonical
+      // CREATE INDEX IF NOT EXISTS statements skip the replacement table.
+      db.run("DROP INDEX IF EXISTS idx_workflow_step_journal_attempt");
+      db.run("DROP INDEX IF EXISTS idx_workflow_step_journal_step");
+    }
+
+    db.run(WORKFLOW_JOURNAL_SCHEMA_SQL);
+
+    if (hasDeleteCascade) {
+      db.run(`INSERT INTO workflow_step_journal (${WORKFLOW_JOURNAL_COLUMNS})
+        SELECT ${WORKFLOW_JOURNAL_COLUMNS} FROM workflow_step_journal_cascade_legacy`);
+      db.run("DROP TABLE workflow_step_journal_cascade_legacy");
+    }
+
+    // #3018 backfill: runs closed before retention was stamped at close get the same window, so the
+    // bounded prune job drains them. Probe first: an UPDATE takes the write lock even when it matches
+    // nothing, and a persistence constructed under cross-process contention must not block on that.
+    const unstamped = db.query(`SELECT EXISTS(SELECT 1 FROM workflow_instances
+      WHERE status IN ('done', 'failed', 'canceled') AND retention_until IS NULL) AS n`).get() as { n: number };
+    if (unstamped.n) {
+      db.query(`UPDATE workflow_instances SET retention_until = COALESCE(closed_at, updated_at) + ?
+        WHERE status IN ('done', 'failed', 'canceled') AND retention_until IS NULL`).run(WORKFLOW_JOURNAL_RETENTION_MS);
+    }
+  })();
+}
+
+/** The lease fields granted to an executor when it seeds/claims an instance (M0: seed only). */
+export interface WorkflowExecutorLease {
+  readonly owner: string;
+  readonly token: string;
+  readonly acquiredAt: number;
+  readonly expiresAt: number;
+  readonly version?: number;
+}
+
+/** M2 acquire/reclaim inputs: who is claiming, with which fresh token, at what time and TTL. */
+export interface AcquireLeaseParams {
+  readonly instanceId: string;
+  readonly owner: string;
+  readonly token: string;
+  readonly now: number;
+  readonly ttlMs: number;
+}
+
+/** M2 renew inputs: the holder's own token (its fence identity) and the fresh expiry window. */
+export interface RenewLeaseParams {
+  readonly instanceId: string;
+  readonly token: string;
+  readonly now: number;
+  readonly ttlMs: number;
+}
+
+/** The minimal instance seed M0 needs — the M1 `ctx.workflows.start` path will supersede this. */
+export interface WorkflowInstanceSeed {
+  readonly id: string;
+  readonly moduleName: string;
+  readonly workflowName: string;
+  readonly idempotencyKey: string;
+  readonly input: JsonValue;
+  readonly initialState: JsonValue;
+  readonly startStep: string;
+  readonly status?: WorkflowStatusName;
+  readonly lease?: WorkflowExecutorLease;
+  /** The creator's actor, stamped into `created_by` at `ctx.workflows.start`. Absent for
+   *  system/migrated seeds — those land `created_by = NULL` (accepted creator-invisible divergence). */
+  readonly createdBy?: string | null;
+}
+
+/**
+ * One step attempt's memoization payload: the state snapshot + serialized `StepResult` +
+ * outcome, plus the transition (next status and any `sleepUntil`/`waitFor`) that advances
+ * the owning instance. Written together with the instance cursor bump in one statement pair.
+ */
+export interface WorkflowStepCommitRecord {
+  readonly instanceId: string;
+  readonly stepIndex: number;
+  readonly stepName: string;
+  readonly attempt: number;
+  readonly outcome: "completed" | "failed";
+  readonly state: JsonValue;
+  readonly result: JsonValue;
+  readonly nextStatus: WorkflowStatusName;
+  readonly startedAt?: number;
+  readonly sleepUntil?: number | null;
+  readonly waitFor?: WaitCondition | null;
+  readonly output?: JsonValue | null;
+  readonly failure?: JsonValue | null;
+}
+
+/** Raw `workflow_instances` row shape (M0 exposes the raw row; strict codecs live in `src/`). */
+export interface WorkflowInstanceRow {
+  id: string;
+  module_name: string;
+  workflow_name: string;
+  idempotency_key: string;
+  input: string;
+  initial_state: string;
+  start_step: string;
+  status: string;
+  sleep_until: number | null;
+  wait_for: string | null;
+  output: string | null;
+  failure: string | null;
+  journal_cursor: number;
+  journal_pruned_through: number;
+  executor_lease_owner: string | null;
+  executor_lease_token: string | null;
+  executor_lease_version: number;
+  executor_lease_acquired_at: number | null;
+  executor_lease_expires_at: number | null;
+  created_at: number;
+  updated_at: number;
+  closed_at: number | null;
+  retention_until: number | null;
+  created_by: string | null;
+  paused_at: number | null;
+}
+
+/** Raw `workflow_step_journal` row shape. */
+export interface WorkflowStepJournalRow {
+  instance_id: string;
+  seq: number;
+  step_index: number;
+  step_name: string;
+  attempt: number;
+  outcome: string;
+  state_snapshot: string;
+  result: string;
+  sleep_until: number | null;
+  wait_for: string | null;
+  started_at: number;
+  completed_at: number;
+}
+
+/** Raised when the executor lease/fence predicate fails inside the step-commit transaction. */
+export class WorkflowLeaseLostError extends Error {
+  constructor(readonly instanceId: string, readonly leaseToken: string) {
+    super(`workflow instance '${instanceId}' lease/fence check failed for token '${leaseToken}'`);
+    this.name = "WorkflowLeaseLostError";
+  }
+}
+
+/** Raised when a failed run cannot be reopened because retention already pruned (part of) its journal (#3018). */
+export class WorkflowHistoryExpiredError extends Error {
+  constructor(readonly instanceId: string) {
+    super(`workflow instance '${instanceId}' cannot be reopened: its journal history was pruned (history-expired)`);
+    this.name = "WorkflowHistoryExpiredError";
+  }
+}
+
+/**
+ * Raised when a step memoization write collides with an already-journaled attempt — the
+ * `workflow_step_journal` PRIMARY KEY `(instance_id, seq)` or the `(instance_id, step_index,
+ * attempt)` unique index. This is the durability guardrail that a memoized step is never written
+ * twice; the M0 review flagged that the underlying SqliteError should not escape untyped, so the
+ * commit wraps the constraint abort in this error instead.
+ */
+export class WorkflowStepConflictError extends Error {
+  constructor(readonly instanceId: string, readonly seq: number, options?: ErrorOptions) {
+    super(`workflow instance '${instanceId}' already has a journaled step at seq ${seq}`, options);
+    this.name = "WorkflowStepConflictError";
+  }
+}
+
+/** True for a SQLite UNIQUE/PRIMARY KEY constraint violation raised by the journal INSERT. */
+function isSqliteConstraintViolation(error: unknown): boolean {
+  const code = (error as { code?: unknown } | null)?.code;
+  if (typeof code === "string" && code.startsWith("SQLITE_CONSTRAINT")) return true;
+  return error instanceof Error && /constraint failed/i.test(error.message);
+}
+
+/**
+ * Raised when a lease op or the step-commit transaction cannot obtain SQLite's write lock within the
+ * connection's `busy_timeout` — a real multi-process/multi-connection contention signal (`SQLITE_BUSY`
+ * / `SQLITE_BUSY_SNAPSHOT`). It is DISTINCT from {@link WorkflowLeaseLostError}: a busy driver still
+ * holds whatever lease it held (nothing was written — a busy on the COMMIT tx rolls the whole tx back),
+ * so the runtime must back off and retry the tick, NEVER conclude it lost its lease. The M4 kill-9
+ * chaos harness is what surfaces this under real cross-process contention; M0–M3's single-thread
+ * `bun:sqlite` tests never could. Handled as a typed relinquish alongside the M2/M3 lease errors.
+ */
+export class WorkflowContendedError extends Error {
+  constructor(readonly instanceId: string, readonly operation: string, options?: ErrorOptions) {
+    super(`workflow instance '${instanceId}' storage was contended (SQLITE_BUSY) during ${operation}`, options);
+    this.name = "WorkflowContendedError";
+  }
+}
+
+/** True for a SQLite write-lock contention (`SQLITE_BUSY`) surfaced under multi-connection load. */
+export function isSqliteBusy(error: unknown): boolean {
+  const code = (error as { code?: unknown } | null)?.code;
+  if (typeof code === "string" && code.startsWith("SQLITE_BUSY")) return true;
+  return error instanceof Error && /database is locked|database table is locked/i.test(error.message);
+}
+
+/** Default `PRAGMA busy_timeout` (ms): under contention a writer BLOCKS-and-retries for this long
+ *  before surfacing `SQLITE_BUSY`, which is what makes most cross-process contention resolve without
+ *  a typed relinquish at all. Injectable via {@link WorkflowJournalOptions.busyTimeoutMs} so a test
+ *  can force immediate contention with `0`. */
+const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
+
+export interface WorkflowJournalOptions {
+  readonly db: Database;
+  readonly clock: Clock;
+  /** `PRAGMA busy_timeout` in ms for this connection; defaults to {@link DEFAULT_BUSY_TIMEOUT_MS}.
+   *  `null` leaves it to the connection's owner (a borrowed, shared handle). */
+  readonly busyTimeoutMs?: number | null;
+  /** Internal gateway-reader construction: catalog installation belongs to the writer op. */
+  readonly installSchema?: boolean;
+}
+
+/** {@link WorkflowJournalPersistence.listInstances} filters — every field optional so the same op
+ *  serves an unfiltered admin sweep and a narrow `{module, status}` view alike (KAPI-1 / G-A). */
+export interface ListInstancesOptions {
+  readonly module?: string;
+  readonly workflow?: string;
+  readonly status?: WorkflowStatusName;
+  /** Keyed owner filter (KAPI-1 Wave 2 / G-M1). When set, only rows whose `created_by` equals it
+   *  are returned — the SQL equality also excludes NULL-owner (system/migrated) rows, so the control
+   *  module's non-admin owner-scoping is fail-closed AND a keyed lookup over the base's
+   *  `(created_by, status)` index rather than a ragged post-fetch filter. Omitted → no owner filter
+   *  (the admin cross-creator sweep). Additive: existing callers are unaffected. */
+  readonly createdBy?: string;
+  readonly cursor?: string;
+  readonly limit?: number;
+}
+
+export interface WorkflowInstancePage {
+  readonly items: readonly WorkflowInstanceRow[];
+  readonly cursor?: string;
+}
+
+export const DEFAULT_INSTANCE_PAGE_SIZE = 50;
+export const MAX_INSTANCE_PAGE_SIZE = 200;
+
+function resolveInstancePageLimit(limit: number | undefined): number {
+  const resolved = limit ?? DEFAULT_INSTANCE_PAGE_SIZE;
+  if (!Number.isInteger(resolved) || resolved < 1 || resolved > MAX_INSTANCE_PAGE_SIZE) {
+    throw new RangeError(`workflow instance list limit must be an integer from 1 to ${MAX_INSTANCE_PAGE_SIZE}`);
+  }
+  return resolved;
+}
+
+interface InstanceCursorPayload {
+  readonly v: 1;
+  readonly updatedAt: number;
+  readonly id: string;
+}
+
+/** Opaque, unsigned `(updated_at, id)` continuation token. Unlike {@link EntityPersistence}'s
+ *  cursor this carries no HMAC: this accessor is the raw persistence-layer read (no transport
+ *  exposure yet — that's KAPI-1's later transport-wiring task), so tamper-resistance is not yet a
+ *  requirement; a malformed cursor fails closed with a clear error either way. */
+function encodeInstanceCursor(row: Pick<WorkflowInstanceRow, "updated_at" | "id">): string {
+  const payload: InstanceCursorPayload = { v: 1, updatedAt: row.updated_at, id: row.id };
+  return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+
+function decodeInstanceCursor(cursor: string): InstanceCursorPayload {
+  try {
+    const payload = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")) as Partial<InstanceCursorPayload>;
+    if (payload.v !== 1 || typeof payload.updatedAt !== "number" || typeof payload.id !== "string") throw new Error();
+    return payload as InstanceCursorPayload;
+  } catch {
+    throw new TypeError("invalid workflow instance list cursor");
+  }
+}
+
+/**
+ * Kernel-owned durable-workflow storage, constructed like {@link EntityPersistence} /
+ * {@link EventLogPersistence}: it installs its catalog on the injected handle at
+ * construction and exposes the in-transaction primitives the step commit composes
+ * (the lease fence and the memoization write), plus seed/read helpers for M0.
+ */
+export class WorkflowJournalPersistence {
+  readonly #db: Database;
+  readonly #clock: Clock;
+
+  constructor(options: WorkflowJournalOptions) {
+    this.#db = options.db;
+    this.#clock = options.clock;
+    // The journal's FK (workflow_step_journal.instance_id → workflow_instances.id) is only
+    // enforced when the handle honors foreign keys; enable it up front so a journal row can
+    // never outlive its instance, regardless of construction order with EntityPersistence.
+    this.#db.run("PRAGMA foreign_keys = ON");
+    // Multi-process contention (M4): a contended writer BLOCKS for up to busy_timeout before SQLite
+    // surfaces SQLITE_BUSY, so a generous window resolves nearly all cross-connection contention
+    // transparently; whatever still surfaces is caught and typed as WorkflowContendedError. This is
+    // per-connection, so every driver's handle sets it. WAL (writer + concurrent readers) is a
+    // db-file property the on-disk caller sets; on `:memory:` the pragma is a harmless no-op.
+    if (options.busyTimeoutMs !== null) {
+      const busyTimeoutMs = options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS;
+      this.#db.run(`PRAGMA busy_timeout = ${Math.max(0, Math.trunc(busyTimeoutMs))}`);
+    }
+    if (options.installSchema !== false) ensureWorkflowJournalSchema(this.#db);
+  }
+
+  /** Run a single-statement lease write, converting a `SQLITE_BUSY` write-lock contention into the
+   *  typed {@link WorkflowContendedError} so a contended tick backs off cleanly instead of leaking a
+   *  raw SqliteError that would abort the wakeup/recover loop. */
+  #leaseWrite(operation: string, instanceId: string, run: () => number): number {
+    try {
+      return run();
+    } catch (error) {
+      if (isSqliteBusy(error)) throw new WorkflowContendedError(instanceId, operation, { cause: error });
+      throw error;
+    }
+  }
+
+  /** Insert a workflow instance (M0 seed path). Returns the stored row. */
+  createInstance(seed: WorkflowInstanceSeed, now = this.#clock.now()): WorkflowInstanceRow {
+    const lease = seed.lease;
+    if (lease && !(lease.expiresAt > lease.acquiredAt)) {
+      throw new RangeError("workflow lease expiresAt must be greater than acquiredAt");
+    }
+    this.#db.query(`INSERT INTO workflow_instances (
+      id, module_name, workflow_name, idempotency_key, input, initial_state, start_step, status,
+      executor_lease_owner, executor_lease_token, executor_lease_version,
+      executor_lease_acquired_at, executor_lease_expires_at, created_at, updated_at, created_by
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
+      seed.id,
+      seed.moduleName,
+      seed.workflowName,
+      seed.idempotencyKey,
+      JSON.stringify(seed.input),
+      JSON.stringify(seed.initialState),
+      seed.startStep,
+      seed.status ?? "pending",
+      lease?.owner ?? null,
+      lease?.token ?? null,
+      lease?.version ?? 0,
+      lease?.acquiredAt ?? null,
+      lease?.expiresAt ?? null,
+      now,
+      now,
+      seed.createdBy ?? null,
+    );
+    return this.getInstance(seed.id)!;
+  }
+
+  /** The raw instance row, or `undefined` when absent. */
+  getInstance(id: string): WorkflowInstanceRow | undefined {
+    return this.#db.query("SELECT * FROM workflow_instances WHERE id = ?").get(id) as WorkflowInstanceRow | undefined;
+  }
+
+  /** The raw instance row for a `(module, workflow, idempotency_key)` identity, or `undefined`. */
+  getInstanceByIdentity(moduleName: string, workflowName: string, idempotencyKey: string): WorkflowInstanceRow | undefined {
+    return this.#db.query(`SELECT * FROM workflow_instances
+      WHERE module_name = ? AND workflow_name = ? AND idempotency_key = ?`)
+      .get(moduleName, workflowName, idempotencyKey) as WorkflowInstanceRow | undefined;
+  }
+
+  /**
+   * Module-agnostic, cursor-paginated instance list (KAPI-1 / G-A): `{module?, workflow?, status?}`
+   * filters over `workflow_instances`, ordered `(updated_at, id)` ascending so `idx_workflow_instances_open`
+   * (or the plain `status` equality scan when `module`-only) serves the query and pagination is
+   * stable even when several rows share an `updated_at` tick. Raw rows — no owner-scoping or
+   * redaction; the control module applies `created_by` filtering and DTO gating on top.
+   */
+  listInstances(options: ListInstancesOptions = {}): WorkflowInstancePage {
+    const limit = resolveInstancePageLimit(options.limit);
+    const clauses: string[] = [];
+    const bindings: Array<string | number> = [];
+    if (options.module !== undefined) {
+      clauses.push("module_name = ?");
+      bindings.push(options.module);
+    }
+    if (options.workflow !== undefined) {
+      clauses.push("workflow_name = ?");
+      bindings.push(options.workflow);
+    }
+    if (options.status !== undefined) {
+      clauses.push("status = ?");
+      bindings.push(options.status);
+    }
+    if (options.createdBy !== undefined) {
+      // Equality (not `IS`) so a NULL-owner row NEVER matches a non-admin owner filter — the
+      // control module's fail-closed creator scoping (G-M1) rides this exclusion.
+      clauses.push("created_by = ?");
+      bindings.push(options.createdBy);
+    }
+    if (options.cursor !== undefined) {
+      const { updatedAt, id } = decodeInstanceCursor(options.cursor);
+      clauses.push("(updated_at > ? OR (updated_at = ? AND id > ?))");
+      bindings.push(updatedAt, updatedAt, id);
+    }
+    const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+    bindings.push(limit + 1);
+    const rows = this.#db.query(`SELECT * FROM workflow_instances ${where}
+      ORDER BY updated_at ASC, id ASC LIMIT ?`).all(...bindings) as WorkflowInstanceRow[];
+    const hasMore = rows.length > limit;
+    const items = rows.slice(0, limit);
+    return {
+      items,
+      ...(hasMore ? { cursor: encodeInstanceCursor(items[items.length - 1]!) } : {}),
+    };
+  }
+
+  /**
+   * Seed an instance idempotently on `UNIQUE(module_name, workflow_name, idempotency_key)`: the
+   * first `start` for a key inserts the `pending` row; a later `start` with the same key is a
+   * no-op insert that returns the SAME existing row (never a second run, no double-start). This is
+   * the ratified `ctx.workflows.start` dedupe. Returns the stored row and whether it was created.
+   */
+  createInstanceIfAbsent(seed: WorkflowInstanceSeed, now = this.#clock.now()): { instance: WorkflowInstanceRow; created: boolean } {
+    const lease = seed.lease;
+    if (lease && !(lease.expiresAt > lease.acquiredAt)) {
+      throw new RangeError("workflow lease expiresAt must be greater than acquiredAt");
+    }
+    const changes = this.#db.query(`INSERT INTO workflow_instances (
+      id, module_name, workflow_name, idempotency_key, input, initial_state, start_step, status,
+      executor_lease_owner, executor_lease_token, executor_lease_version,
+      executor_lease_acquired_at, executor_lease_expires_at, created_at, updated_at, created_by
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(module_name, workflow_name, idempotency_key) DO NOTHING`).run(
+      seed.id,
+      seed.moduleName,
+      seed.workflowName,
+      seed.idempotencyKey,
+      JSON.stringify(seed.input),
+      JSON.stringify(seed.initialState),
+      seed.startStep,
+      seed.status ?? "pending",
+      lease?.owner ?? null,
+      lease?.token ?? null,
+      lease?.version ?? 0,
+      lease?.acquiredAt ?? null,
+      lease?.expiresAt ?? null,
+      now,
+      now,
+      seed.createdBy ?? null,
+    ).changes;
+    const instance = this.getInstanceByIdentity(seed.moduleName, seed.workflowName, seed.idempotencyKey);
+    if (!instance) throw new Error("workflow instance insert did not produce a row");
+    return { instance, created: changes === 1 };
+  }
+
+  /**
+   * Transition an OPEN instance to the terminal `canceled` status. Returns `true` when it moved,
+   * `false` when the instance is absent or already terminal. This is a control-plane transition,
+   * not a step commit — it needs no journal memo row, and the fold projects the terminal status
+   * straight from the instance row.
+   */
+  cancelInstance(id: string, now = this.#clock.now()): boolean {
+    const changes = this.#db.query(`UPDATE workflow_instances
+      SET status = 'canceled', updated_at = ?, closed_at = ?, retention_until = ?
+      WHERE id = ? AND status IN ('pending', 'running', 'sleeping', 'waiting')`)
+      .run(now, now, now + WORKFLOW_JOURNAL_RETENTION_MS, id).changes;
+    return changes === 1;
+  }
+
+  /**
+   * Transition an OPEN instance to the terminal `failed` status with a JSON failure payload.
+   * Like {@link cancelInstance} this is a control-plane transition, not a step commit: M1 has no
+   * retry driver (that is M3), so an unhandled step throw terminates the instance here. Returns
+   * `true` when it moved, `false` when the instance is absent or already terminal.
+   */
+  failInstance(id: string, failure: JsonValue, now = this.#clock.now()): boolean {
+    const changes = this.#db.query(`UPDATE workflow_instances
+      SET status = 'failed', failure = ?, updated_at = ?, closed_at = ?, retention_until = ?
+      WHERE id = ? AND status IN ('pending', 'running', 'sleeping', 'waiting')`)
+      .run(JSON.stringify(failure), now, now, now + WORKFLOW_JOURNAL_RETENTION_MS, id).changes;
+    return changes === 1;
+  }
+
+  /**
+   * Pause an OPEN instance (KAPI-1 control primitive, Option A). Sets `paused_at` WITHOUT touching
+   * `status`, so the underlying `pending`/`running`/`sleeping`/`waiting` — and any `sleep_until`/
+   * `wait_for` deadline — is preserved verbatim. While `paused_at` is non-NULL the driver work-lists
+   * ({@link listResumable}/{@link listDueSleepers}/{@link listWaiters}) AND the lease-acquire
+   * predicate ({@link acquireLease}) skip the instance, so it runs no further steps. OPEN-guarded and
+   * idempotent like {@link cancelInstance}: returns `true` when it newly paused, `false` when the
+   * instance is absent, terminal, or already paused. This is a control-plane transition, not a step
+   * commit — it needs no journal memo. Authorization (owner check / system twin) is the caller's job,
+   * mirroring the timers `cancel`/`cancelMirror` split; the primitive itself is authz-free.
+   */
+  pauseInstance(id: string, now = this.#clock.now()): boolean {
+    const changes = this.#db.query(`UPDATE workflow_instances
+      SET paused_at = ?, updated_at = ?
+      WHERE id = ? AND status IN ('pending', 'running', 'sleeping', 'waiting') AND paused_at IS NULL`)
+      .run(now, now, id).changes;
+    return changes === 1;
+  }
+
+  /**
+   * Resume a paused instance: clear `paused_at` so the driver work-lists and lease-acquire predicate
+   * see it again. The preserved `sleep_until`/`wait_for` then fires on the next tick — a due sleeper
+   * fires immediately (late by design; durable, not real-time). Idempotent: returns `true` when it
+   * cleared a pause, `false` when the instance was not paused (absent or never paused). Not
+   * status-guarded — clearing the flag on a terminal instance is a harmless no-op (the work-lists
+   * exclude terminal rows regardless), so cancel/terminal remains absorbing.
+   */
+  resumeInstance(id: string, now = this.#clock.now()): boolean {
+    const changes = this.#db.query(`UPDATE workflow_instances
+      SET paused_at = NULL, updated_at = ?
+      WHERE id = ? AND paused_at IS NOT NULL`)
+      .run(now, id).changes;
+    return changes === 1;
+  }
+
+  /**
+   * Re-open a `failed` instance so the runtime re-drives it from its last good journal cursor
+   * (memoized steps replay via the fold; only the failed step re-runs). Sets `status = 'pending'`,
+   * clears `failure` AND `closed_at`, and clears the executor lease (bumping the version so any stale
+   * token is fenced off) so a driver can reclaim it. Guarded `WHERE status = 'failed'` and idempotent:
+   * a second reopen on an already-open instance is a no-op (`false`). Like the other control
+   * primitives it carries no authorization — that is the control module's job. Returns `true` when it
+   * re-opened, `false` when the instance is absent or not `failed`.
+   */
+  reopenInstance(id: string, now = this.#clock.now()): boolean {
+    // The pruned-floor guard lives in the UPDATE so a prune cannot slip between check and reopen.
+    const changes = this.#db.query(`UPDATE workflow_instances SET
+      status = 'pending', failure = NULL, closed_at = NULL, retention_until = NULL,
+      executor_lease_owner = NULL, executor_lease_token = NULL,
+      executor_lease_acquired_at = NULL, executor_lease_expires_at = NULL,
+      executor_lease_version = executor_lease_version + 1, updated_at = ?
+      WHERE id = ? AND status = 'failed' AND journal_pruned_through = 0`)
+      .run(now, id).changes;
+    if (changes === 1) return true;
+    const row = this.#db.query("SELECT status, journal_pruned_through AS pruned FROM workflow_instances WHERE id = ?")
+      .get(id) as { status: string; pruned: number } | undefined;
+    // A pruned history cannot be replayed (resume would hit a gap): refuse loudly, keep the failed row.
+    if (row?.status === "failed" && row.pruned > 0) throw new WorkflowHistoryExpiredError(id);
+    return false;
+  }
+
+  /** All journal rows for an instance in commit order. */
+  listSteps(instanceId: string): WorkflowStepJournalRow[] {
+    return this.#db.query("SELECT * FROM workflow_step_journal WHERE instance_id = ? ORDER BY seq ASC")
+      .all(instanceId) as WorkflowStepJournalRow[];
+  }
+
+  /**
+   * (a) of the step commit: re-check the executor lease/fence by SQL predicate inside the
+   * caller-owned transaction. Never trusts a pre-transaction read — the predicate re-evaluates
+   * `executor_lease_token` and `executor_lease_expires_at` against the live row. A row that no
+   * longer matches (reclaimed, fenced, or expired) yields `changes !== 1` and aborts.
+   */
+  fenceLeaseInTransaction(instanceId: string, leaseToken: string, now: number): void {
+    if (!this.#db.inTransaction) {
+      throw new Error("workflow lease fence must run inside a synchronous SQLite transaction");
+    }
+    const result = this.#db.query(`UPDATE workflow_instances SET updated_at = ?
+      WHERE id = ? AND executor_lease_token = ? AND executor_lease_expires_at > ?`)
+      .run(now, instanceId, leaseToken, now);
+    if (result.changes !== 1) throw new WorkflowLeaseLostError(instanceId, leaseToken);
+  }
+
+  /**
+   * M2 acquire / reclaim: atomically claim an OPEN instance IF it is currently unleased OR its
+   * lease has expired (`expires_at <= now`). A live lease held by another driver blocks the claim
+   * — this returns `false` and the contender must back off, never steal. The claim writes a fresh
+   * unique token + expiry and bumps `executor_lease_version`, so any prior holder's token is
+   * fenced off (its later commit/renew no longer matches). This one predicate is BOTH the
+   * cold-start acquire and the crash-recovery reclaim of an expired lease: a single-writer guard
+   * enforced in SQL, not by trusting a pre-read. Returns whether the caller now holds the lease.
+   *
+   * The `paused_at IS NULL` predicate here is the pause TOCTOU fix: a pause that lands AFTER a
+   * work-list query ({@link listDueSleepers} et al.) already returned this id, but BEFORE the driver
+   * acquires, still blocks the acquire — so a paused instance can never be leased and thus can never
+   * fire "one more time." Gating only the work-lists would leave that race open; gating the acquire
+   * (and the inner `#drive` loop) closes it.
+   */
+  acquireLease(params: AcquireLeaseParams): boolean {
+    if (!(params.ttlMs > 0)) throw new RangeError("workflow lease ttlMs must be a positive number");
+    const expiresAt = params.now + params.ttlMs;
+    const changes = this.#leaseWrite("acquireLease", params.instanceId, () => this.#db.query(`UPDATE workflow_instances SET
+      executor_lease_owner = ?, executor_lease_token = ?,
+      executor_lease_acquired_at = ?, executor_lease_expires_at = ?,
+      executor_lease_version = executor_lease_version + 1, updated_at = ?
+      WHERE id = ? AND status IN ('pending', 'running', 'sleeping', 'waiting')
+        AND paused_at IS NULL
+        AND (executor_lease_token IS NULL OR executor_lease_expires_at <= ?)`)
+      .run(params.owner, params.token, params.now, expiresAt, params.now, params.instanceId, params.now).changes);
+    return changes === 1;
+  }
+
+  /**
+   * M2 renew: the holding driver extends its expiry while it makes progress, so a long-running or
+   * multi-step drive never lets the lease lapse under a competitor. Succeeds only while the caller
+   * STILL holds the token (token identity is the fence): a reclaim by another driver rotated the
+   * token, so a stale holder's renew returns `false` and it must relinquish. Returns whether the
+   * lease was extended.
+   */
+  renewLease(params: RenewLeaseParams): boolean {
+    if (!(params.ttlMs > 0)) throw new RangeError("workflow lease ttlMs must be a positive number");
+    const expiresAt = params.now + params.ttlMs;
+    // A renew that hits SQLITE_BUSY is NOT a lost lease — the holder still owns its (token-pinned)
+    // lease, the extend UPDATE simply did not land. Surface it as WorkflowContendedError so the
+    // driver backs off this tick keeping its lease, rather than mistaking contention for a fence-off.
+    const changes = this.#leaseWrite("renewLease", params.instanceId, () => this.#db.query(`UPDATE workflow_instances SET
+      executor_lease_expires_at = ?, updated_at = ?
+      WHERE id = ? AND executor_lease_token = ?`)
+      .run(expiresAt, params.now, params.instanceId, params.token).changes);
+    return changes === 1;
+  }
+
+  /**
+   * M2 release: relinquish the lease the caller holds so a later driver (or an M3 timer/wait
+   * wakeup) can reacquire immediately without waiting out the TTL. Clears the lease columns and
+   * bumps the version. A no-op (`false`) when the caller no longer holds the token — e.g. it was
+   * already reclaimed. Never touches instance status; it is a lease-only relinquish.
+   */
+  releaseLease(instanceId: string, token: string, now = this.#clock.now()): boolean {
+    // Release is best-effort cleanup called from a `finally`, so it must NEVER throw: a contended
+    // release just leaves the lease to lapse via its TTL (recovery reclaims it then), which is safe.
+    try {
+      const changes = this.#db.query(`UPDATE workflow_instances SET
+        executor_lease_owner = NULL, executor_lease_token = NULL,
+        executor_lease_acquired_at = NULL, executor_lease_expires_at = NULL,
+        executor_lease_version = executor_lease_version + 1, updated_at = ?
+        WHERE id = ? AND executor_lease_token = ?`)
+        .run(now, instanceId, token).changes;
+      return changes === 1;
+    } catch (error) {
+      if (isSqliteBusy(error)) return false;
+      throw error;
+    }
+  }
+
+  /**
+   * The crash-recovery work-list: ids of OPEN, actively-drivable instances (`pending`/`running`)
+   * whose executor lease is absent or expired at `now`. A live-leased instance is excluded — a
+   * slow-but-alive driver still owns it, and recovery must never double-run a step it is inside.
+   * Parked `sleeping`/`waiting` instances are excluded too: their wakeup is the M3 timer/wait
+   * driver's job, not a blind resume. Ordered oldest-touched first so recovery drains fairly.
+   * Every work-list is scoped to ONE module: a driver must never scan another module's instances (#3006).
+   */
+  listResumable(moduleName: string, now: number): string[] {
+    return (this.#db.query(`SELECT id FROM workflow_instances
+      WHERE module_name = ? AND status IN ('pending', 'running') AND paused_at IS NULL
+        AND (executor_lease_token IS NULL OR executor_lease_expires_at <= ?)
+      ORDER BY updated_at ASC`).all(moduleName, now) as Array<{ id: string }>).map((row) => row.id);
+  }
+
+  /**
+   * A SINGLE-QUERY, SINGLE-`now` classification of this module's residual OPEN work for a boot/OFF
+   * reconcile (#1447 finding C, round-7). Returns BOTH signals the reconcile decision needs, computed in
+   * ONE statement against ONE `now`, so they can NEVER disagree across the lease-expiry boundary:
+   *   • `reclaimableCount` — OPEN (`pending`/`running`, unpaused) instances that are RECLAIMABLE right now
+   *     — the exact predicate (and thus the count) of {@link listResumable}, module-scoped: lease absent
+   *     OR expired at `now` (`executor_lease_expires_at <= now`). A boot/OFF reconcile uses this to tell
+   *     "genuinely converged" from "recover() returned [] only because a CONTENDED acquire
+   *     ({@link WorkflowContendedError}) was swallowed to a no-op, even though the instance is drivable
+   *     NOW" — the latter needs a short retry, not a false convergence.
+   *   • `nextLiveLeaseExpiry` — the earliest executor-lease expiry among the REST (still-LIVE leases,
+   *     `executor_lease_token IS NOT NULL AND executor_lease_expires_at > now`) — instances a plain
+   *     {@link recover}/{@link listResumable} cannot yet reclaim. `undefined` when none. A crash before a
+   *     step's journal commit leaves such an instance holding the dead driver's lease; the OFF reconcile
+   *     schedules a bounded retry AT this expiry, when {@link listResumable} legitimately includes the
+   *     now-EXPIRED lease — instead of FORCE-CLEARING a lease it cannot prove is dead (round-4: a lease
+   *     held by a LIVE concurrent process, e.g. a restart-overlap or different-port-same-DB peer, must
+   *     never be cleared, or its step body double-drives, violating the M2 single-writer invariant).
+   *
+   * ── Why one query (round-6 → round-7) ──────────────────────────────────────────────────────────────
+   * READ-ONLY (never mutates a lease) and module-scoped. Every OPEN instance is classified into EXACTLY
+   * ONE bucket at `now`: reclaimable-now (`<= now`) XOR live-leased (`> now`). So
+   * `reclaimableCount === 0 && nextLiveLeaseExpiry === undefined` means there is GENUINELY no open work —
+   * never a boundary artifact. The prior two-read design (a `countReclaimable` and a `nextLiveLeaseExpiry`
+   * each sampling the clock/DB independently) let a lease expire BETWEEN the reads: reclaimable-count at
+   * E-1 = 0 AND live-lease at E = undefined → a FALSE convergence that stranded an acknowledged close
+   * with the ticker OFF. One statement + one `now` bound closes that gap by construction.
+   */
+  snapshotReconcileResidual(moduleName: string, now: number): { reclaimableCount: number; nextLiveLeaseExpiry: number | undefined } {
+    const row = this.#db.query(`SELECT
+        SUM(CASE WHEN executor_lease_token IS NULL OR executor_lease_expires_at <= ? THEN 1 ELSE 0 END) AS reclaimable,
+        MIN(CASE WHEN executor_lease_token IS NOT NULL AND executor_lease_expires_at > ? THEN executor_lease_expires_at ELSE NULL END) AS liveExpiry
+      FROM workflow_instances
+      WHERE module_name = ? AND status IN ('pending', 'running') AND paused_at IS NULL`)
+      .get(now, now, moduleName) as { reclaimable: number | null; liveExpiry: number | null };
+    return { reclaimableCount: row.reclaimable ?? 0, nextLiveLeaseExpiry: row.liveExpiry ?? undefined };
+  }
+
+  /**
+   * The M3 timer work-list: ids of `sleeping` instances whose `sleep_until` is DUE (`<= now`) and
+   * whose executor lease is absent or expired — the acquire-able, fire-able sleepers. This is the
+   * SQL half of the "no instance is due but un-acquirable" gate: the same lease predicate as
+   * {@link acquireLease}, so a row this returns can be claimed (unless a rival claims it first).
+   * Both durable timers (`StepResult.sleepUntil`) and retry backoffs park as sleeping rows, so this
+   * one predicate fires both. Ordered earliest-due first so the closest deadline fires first.
+   */
+  listDueSleepers(moduleName: string, now: number): string[] {
+    return (this.#db.query(`SELECT id FROM workflow_instances
+      WHERE module_name = ? AND status = 'sleeping' AND sleep_until IS NOT NULL AND sleep_until <= ? AND paused_at IS NULL
+        AND (executor_lease_token IS NULL OR executor_lease_expires_at <= ?)
+      ORDER BY sleep_until ASC`).all(moduleName, now, now) as Array<{ id: string }>).map((row) => row.id);
+  }
+
+  /**
+   * The M3 wait work-list: ids of `waiting` instances whose executor lease is absent or expired.
+   * Unlike a sleeper, a waiter's DUENESS (is its {@link WaitCondition} satisfied?) is not a pure
+   * SQL predicate — it depends on events/commands the journal does not own — so this returns the
+   * acquire-able candidates and the runtime applies the satisfaction predicate. Same lease gate as
+   * {@link acquireLease} so a returned row is claimable. Ordered oldest-armed first for fairness.
+   */
+  listWaiters(moduleName: string, now: number): string[] {
+    return (this.#db.query(`SELECT id FROM workflow_instances
+      WHERE module_name = ? AND status = 'waiting' AND wait_for IS NOT NULL AND paused_at IS NULL
+        AND (executor_lease_token IS NULL OR executor_lease_expires_at <= ?)
+      ORDER BY updated_at ASC`).all(moduleName, now) as Array<{ id: string }>).map((row) => row.id);
+  }
+
+  /**
+   * (d) of the step commit: insert the immutable memoization row at `journal_cursor + 1` and
+   * advance the instance's status, cursor, and transition columns — one statement pair inside
+   * the caller-owned transaction so the journal row and the cursor bump are never torn apart.
+   */
+  recordStepInTransaction(record: WorkflowStepCommitRecord, completedAt = this.#clock.now()): number {
+    if (!this.#db.inTransaction) {
+      throw new Error("workflow step journal must be written inside a synchronous SQLite transaction");
+    }
+    const cursorRow = this.#db.query("SELECT journal_cursor FROM workflow_instances WHERE id = ?")
+      .get(record.instanceId) as { journal_cursor: number } | undefined;
+    if (!cursorRow) throw new Error(`workflow instance '${record.instanceId}' does not exist`);
+
+    const seq = cursorRow.journal_cursor + 1;
+    const startedAt = record.startedAt ?? completedAt;
+    // The INSTANCE schedule and the immutable JOURNAL-ROW schedule are decoupled. A completed step
+    // records its own `sleepUntil`/`waitFor` on both. A FAILED attempt's row must carry neither
+    // (the codec forbids a failed record from scheduling a timer/wait), yet the instance may still
+    // need to park `sleeping` until a retry backoff elapses — so the row columns come from the
+    // outcome-gated values while the instance columns come straight from the record.
+    const instanceSleepUntil = record.sleepUntil ?? null;
+    const instanceWaitForText = record.waitFor == null ? null : JSON.stringify(record.waitFor);
+    const rowSleepUntil = record.outcome === "failed" ? null : instanceSleepUntil;
+    const rowWaitForText = record.outcome === "failed" ? null : instanceWaitForText;
+
+    try {
+      this.#db.query(`INSERT INTO workflow_step_journal (
+        instance_id, seq, step_index, step_name, attempt, outcome, state_snapshot, result,
+        sleep_until, wait_for, started_at, completed_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
+        record.instanceId,
+        seq,
+        record.stepIndex,
+        record.stepName,
+        record.attempt,
+        record.outcome,
+        JSON.stringify(record.state),
+        JSON.stringify(record.result),
+        rowSleepUntil,
+        rowWaitForText,
+        startedAt,
+        completedAt,
+      );
+    } catch (error) {
+      // A UNIQUE/PRIMARY KEY collision here means this step attempt is already memoized: surface
+      // it as the typed conflict rather than leaking a raw SqliteError (M0 review nit). The throw
+      // aborts the caller-owned transaction, rolling back the entity + event writes with it.
+      if (isSqliteConstraintViolation(error)) throw new WorkflowStepConflictError(record.instanceId, seq, { cause: error });
+      throw error;
+    }
+
+    const outputText = record.output == null ? null : JSON.stringify(record.output);
+    const failureText = record.failure == null ? null : JSON.stringify(record.failure);
+    this.#db.query(`UPDATE workflow_instances SET
+      status = ?, journal_cursor = ?, sleep_until = ?, wait_for = ?, output = ?, failure = ?, updated_at = ?,
+      closed_at = CASE WHEN ? IN ('done', 'failed', 'canceled') THEN ? ELSE closed_at END,
+      retention_until = CASE WHEN ? IN ('done', 'failed', 'canceled') THEN ? ELSE retention_until END
+      WHERE id = ?`).run(
+      record.nextStatus,
+      seq,
+      instanceSleepUntil,
+      instanceWaitForText,
+      outputText,
+      failureText,
+      completedAt,
+      record.nextStatus,
+      completedAt,
+      record.nextStatus,
+      completedAt + WORKFLOW_JOURNAL_RETENTION_MS,
+      record.instanceId,
+    );
+    return seq;
+  }
+}
+
+export function createWorkflowJournalPersistence(options: WorkflowJournalOptions): WorkflowJournalPersistence {
+  return new WorkflowJournalPersistence(options);
+}