@multiplier-labs/stepflow 0.3.1 → 0.3.4

package/src/storage/sqlite.ts

@@ -2,10 +2,25 @@
  * SQLite storage adapter using better-sqlite3.
  *
  * Provides durable persistence for workflow runs, steps, and events.
+ *
+ * ## Module layout
+ *
+ *   - `SQLiteStorageAdapter` (this file) owns the better-sqlite3 connection,
+ *     the prepared-statement cache, and every method on `StorageAdapter`. It
+ *     is the only adapter class — unlike the Postgres adapter there is no
+ *     transaction-scoped twin, so no abstract CRUD base class is required.
+ *
+ *   - `sqlite-core.ts` holds the pure row-type interfaces and row mappers
+ *     (`mapRunRow`, `mapStepRow`, `mapEventRow`). The mappers route every
+ *     JSON-column parse through `safeParseField` / `safeParseOptionalField`
+ *     in `src/utils/safe-json.ts`, sharing the corruption-counter +
+ *     structured-warn behavior with the Postgres core (audit M2 / L3,
+ *     PR #52). The split mirrors `postgres-core.ts` so both adapters
+ *     expose mappers in the same shape.
  */
 
-import type Database from "better-sqlite3";
-import { generateId } from "../utils/id";
+import type Database from 'better-sqlite3';
+import { generateId } from '../utils/id';
 import type {
   StorageAdapter,
   WorkflowRunRecord,
@@ -14,9 +29,18 @@ import type {
   ListRunsOptions,
   ListEventsOptions,
   PaginatedResult,
-} from "./types";
-import type { RunStatus, StepStatus, WorkflowError } from "../core/types";
-import { sanitizeErrorForStorage } from "../utils/logger";
+} from './types';
+import type { Logger } from '../core/types';
+import { sanitizeErrorForStorage } from '../utils/logger';
+import type { MapperContext } from '../utils/safe-json';
+import {
+  mapRunRow,
+  mapStepRow,
+  mapEventRow,
+  type SQLiteRunRow,
+  type SQLiteStepRow,
+  type SQLiteEventRow,
+} from './sqlite-core';
 
 // ============================================================================
 // Schema SQL
@@ -36,6 +60,7 @@ CREATE TABLE IF NOT EXISTS workflow_runs (
   input_json TEXT NOT NULL,
   metadata_json TEXT NOT NULL,
   context_json TEXT NOT NULL,
+  completed_steps_json TEXT,
   error_json TEXT,
   created_at TEXT NOT NULL,
   started_at TEXT,
@@ -81,6 +106,22 @@ CREATE INDEX IF NOT EXISTS idx_workflow_events_run ON workflow_events(run_id);
 CREATE INDEX IF NOT EXISTS idx_workflow_events_run_ts ON workflow_events(run_id, timestamp);
 `;
 
+/**
+ * Columns added to {@link CREATE_TABLES_SQL} after the initial schema, expressed
+ * as `ALTER TABLE ADD COLUMN` migrations. SQLite's `CREATE TABLE IF NOT EXISTS`
+ * does not reconcile column lists against existing tables, so a deploy that ran
+ * an older version of this adapter will be missing any column added later. The
+ * adapter applies these on startup so existing databases stay usable across
+ * upgrades.
+ *
+ * Append-only: SQLite does not support DROP COLUMN or general ALTER COLUMN, so
+ * removing or changing an entry here would break upgrades from older versions.
+ * Only add new entries when a column is added to {@link CREATE_TABLES_SQL}.
+ */
+const SCHEMA_MIGRATIONS: ReadonlyArray<{ table: string; column: string; type: string }> = [
+  { table: 'workflow_runs', column: 'completed_steps_json', type: 'TEXT' },
+];
+
 // ============================================================================
 // Configuration
 // ============================================================================
@@ -106,6 +147,61 @@ export interface SQLiteStorageConfig {
    * Table names are always prefixed with 'workflow_'.
    */
   tablePrefix?: string;
+
+  /**
+   * Optional structured logger used to surface JSON corruption events.
+   * Without one, parse failures still increment the corruption counter
+   * exposed via `getJsonParseCorruptionCount()` but produce no log output.
+   */
+  logger?: Logger;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * better-sqlite3 raises `SqliteError { code: 'SQLITE_ERROR', message:
+ * 'duplicate column name: <name>' }` when an `ALTER TABLE ADD COLUMN` targets
+ * a column that already exists. Treat that as a benign no-op so concurrent
+ * startups (or any race between the {@link runMigrations} existence check and
+ * the ALTER) don't crash. All other errors propagate.
+ */
+function isDuplicateColumnError(err: unknown): boolean {
+  if (!err || typeof err !== 'object') return false;
+  const code = (err as { code?: unknown }).code;
+  const message = (err as { message?: unknown }).message;
+  return (
+    code === 'SQLITE_ERROR' &&
+    typeof message === 'string' &&
+    message.toLowerCase().includes('duplicate column name')
+  );
+}
+
+/**
+ * Resolve to `true` if `p` settles within a few microtask ticks of being
+ * inspected, otherwise `false`. Used by the deprecated async `transaction()`
+ * to detect callbacks that suspend on real async I/O — by the time we ask,
+ * the synchronous COMMIT has already run, so a still-pending promise means
+ * any post-await operations land outside the transaction.
+ */
+async function isPromiseSettled(p: Promise<unknown>): Promise<boolean> {
+  let settled = false;
+  p.then(
+    () => {
+      settled = true;
+    },
+    () => {
+      settled = true;
+    }
+  );
+  // Drain a handful of microtask ticks. `await Promise.resolve()` callbacks
+  // and other already-resolved continuations finish in 1-2 ticks; anything
+  // still pending after this is doing real async I/O (timers, network, etc.).
+  for (let i = 0; i < 5 && !settled; i++) {
+    await Promise.resolve();
+  }
+  return settled;
 }
 
 // ============================================================================
@@ -135,6 +231,7 @@ export interface SQLiteStorageConfig {
 export class SQLiteStorageAdapter implements StorageAdapter {
   private db: Database.Database;
   private prefix: string;
+  private logger: Logger | undefined;
 
   // Prepared statements (cached for performance)
   private stmts: {
@@ -158,16 +255,25 @@ export class SQLiteStorageAdapter implements StorageAdapter {
 
   constructor(config: SQLiteStorageConfig) {
     this.db = config.db;
-    this.prefix = config.tablePrefix ?? "workflow";
+    this.prefix = config.tablePrefix ?? 'workflow';
+    this.logger = config.logger;
 
     // Enable foreign keys
-    this.db.pragma("foreign_keys = ON");
+    this.db.pragma('foreign_keys = ON');
 
     // Create tables if needed
     if (config.autoCreateTables !== false) {
       this.createTables();
     }
 
+    // Always reconcile column-level migrations: the prepared statements below
+    // reference the latest schema, so an adapter sitting on top of an older
+    // table layout (e.g., a database created by a previous version, or a
+    // caller-managed schema with `autoCreateTables: false` that has not been
+    // hand-upgraded) would crash on the first INSERT/SELECT. Migrations are
+    // idempotent and skip tables that don't exist.
+    this.runMigrations();
+
     // Prepare statements
     this.prepareStatements();
   }
@@ -179,14 +285,47 @@ export class SQLiteStorageAdapter implements StorageAdapter {
     this.db.exec(CREATE_TABLES_SQL);
   }
 
+  /**
+   * Apply additive schema migrations to existing tables.
+   *
+   * `CREATE TABLE IF NOT EXISTS` is a no-op when the table already exists, so
+   * any column added to {@link CREATE_TABLES_SQL} after the initial schema is
+   * silently absent on databases created by older versions of this adapter.
+   * Without this step, the first INSERT/SELECT crashes with
+   * `SqliteError: table X has no column named Y`. This mirrors the
+   * `ALTER TABLE ADD COLUMN IF NOT EXISTS` block in `postgres.ts`'s
+   * `createTables()`.
+   *
+   * For each entry in {@link SCHEMA_MIGRATIONS}: if the table exists and the
+   * column does not, run `ALTER TABLE ADD COLUMN`. The ALTER is wrapped in a
+   * try/catch that tolerates `duplicate column` errors so concurrent startups
+   * (or any race between the existence check and the ALTER) do not crash.
+   * Other SQLite errors propagate.
+   */
+  private runMigrations(): void {
+    for (const { table, column, type } of SCHEMA_MIGRATIONS) {
+      const tableInfo = this.db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
+      // PRAGMA table_info on a missing table returns []; CREATE TABLE handles that case.
+      if (tableInfo.length === 0) continue;
+      if (tableInfo.some((col) => col.name === column)) continue;
+
+      try {
+        this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+      } catch (err) {
+        if (isDuplicateColumnError(err)) continue;
+        throw err;
+      }
+    }
+  }
+
   /**
    * Prepare all SQL statements for better performance.
    */
   private prepareStatements(): void {
     this.stmts = {
       insertRun: this.db.prepare(`
-        INSERT INTO workflow_runs (id, kind, status, parent_run_id, input_json, metadata_json, context_json, error_json, created_at, started_at, finished_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        INSERT INTO workflow_runs (id, kind, status, parent_run_id, input_json, metadata_json, context_json, completed_steps_json, error_json, created_at, started_at, finished_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `),
       getRun: this.db.prepare(`
         SELECT * FROM workflow_runs WHERE id = ?
@@ -195,6 +334,7 @@ export class SQLiteStorageAdapter implements StorageAdapter {
         UPDATE workflow_runs
         SET status = COALESCE(?, status),
             context_json = COALESCE(?, context_json),
+            completed_steps_json = COALESCE(?, completed_steps_json),
             error_json = COALESCE(?, error_json),
             started_at = COALESCE(?, started_at),
             finished_at = COALESCE(?, finished_at)
@@ -277,9 +417,7 @@ export class SQLiteStorageAdapter implements StorageAdapter {
   // Run Operations
   // ============================================================================
 
-  async createRun(
-    run: Omit<WorkflowRunRecord, "id" | "createdAt">,
-  ): Promise<WorkflowRunRecord> {
+  async createRun(run: Omit<WorkflowRunRecord, 'id' | 'createdAt'>): Promise<WorkflowRunRecord> {
     const id = generateId();
     const createdAt = new Date();
 
@@ -291,10 +429,11 @@ export class SQLiteStorageAdapter implements StorageAdapter {
       JSON.stringify(run.input),
       JSON.stringify(run.metadata),
       JSON.stringify(run.context),
+      run.completedSteps ? JSON.stringify(run.completedSteps) : null,
       run.error ? JSON.stringify(sanitizeErrorForStorage(run.error)) : null,
       createdAt.toISOString(),
       run.startedAt?.toISOString() ?? null,
-      run.finishedAt?.toISOString() ?? null,
+      run.finishedAt?.toISOString() ?? null
     );
 
     return {
@@ -306,59 +445,44 @@ export class SQLiteStorageAdapter implements StorageAdapter {
 
   async getRun(runId: string): Promise<WorkflowRunRecord | null> {
     const row = this.stmts!.getRun.get(runId) as SQLiteRunRow | undefined;
-    return row ? this.mapRunRow(row) : null;
+    return row ? mapRunRow(row, this.mapperCtx) : null;
   }
 
-  async updateRun(
-    runId: string,
-    updates: Partial<WorkflowRunRecord>,
-  ): Promise<void> {
+  async updateRun(runId: string, updates: Partial<WorkflowRunRecord>): Promise<void> {
     this.stmts!.updateRun.run(
       updates.status ?? null,
       updates.context ? JSON.stringify(updates.context) : null,
-      updates.error
-        ? JSON.stringify(sanitizeErrorForStorage(updates.error))
-        : null,
+      updates.completedSteps ? JSON.stringify(updates.completedSteps) : null,
+      updates.error ? JSON.stringify(sanitizeErrorForStorage(updates.error)) : null,
       updates.startedAt?.toISOString() ?? null,
       updates.finishedAt?.toISOString() ?? null,
-      runId,
+      runId
     );
   }
 
-  async listRuns(
-    options: ListRunsOptions = {},
-  ): Promise<PaginatedResult<WorkflowRunRecord>> {
+  async listRuns(options: ListRunsOptions = {}): Promise<PaginatedResult<WorkflowRunRecord>> {
     const limit = options.limit ?? 50;
     const offset = options.offset ?? 0;
     const kind = options.kind ?? null;
     const status = options.status ?? null;
-    const statusJson = status
-      ? JSON.stringify(Array.isArray(status) ? status : [status])
-      : null;
+    const statusJson = status ? JSON.stringify(Array.isArray(status) ? status : [status]) : null;
     const parentRunId = options.parentRunId ?? null;
 
     const rows = this.stmts!.listRuns.all(
-      kind,
-      kind,
-      statusJson,
-      statusJson,
-      parentRunId,
-      parentRunId,
-      limit,
-      offset,
+      kind, kind,
+      statusJson, statusJson,
+      parentRunId, parentRunId,
+      limit, offset
     ) as SQLiteRunRow[];
 
     const countResult = this.stmts!.countRuns.get(
-      kind,
-      kind,
-      statusJson,
-      statusJson,
-      parentRunId,
-      parentRunId,
+      kind, kind,
+      statusJson, statusJson,
+      parentRunId, parentRunId
     ) as { count: number };
 
     return {
-      items: rows.map((row) => this.mapRunRow(row)),
+      items: rows.map(row => mapRunRow(row, this.mapperCtx)),
       total: countResult.count,
       limit,
       offset,
@@ -369,9 +493,7 @@ export class SQLiteStorageAdapter implements StorageAdapter {
   // Step Operations
   // ============================================================================
 
-  async createStep(
-    step: Omit<WorkflowRunStepRecord, "id">,
-  ): Promise<WorkflowRunStepRecord> {
+  async createStep(step: Omit<WorkflowRunStepRecord, 'id'>): Promise<WorkflowRunStepRecord> {
     const id = generateId();
 
     this.stmts!.insertStep.run(
@@ -384,7 +506,7 @@ export class SQLiteStorageAdapter implements StorageAdapter {
       step.result !== undefined ? JSON.stringify(step.result) : null,
       step.error ? JSON.stringify(sanitizeErrorForStorage(step.error)) : null,
       step.startedAt?.toISOString() ?? null,
-      step.finishedAt?.toISOString() ?? null,
+      step.finishedAt?.toISOString() ?? null
     );
 
     return { ...step, id };
@@ -392,35 +514,30 @@ export class SQLiteStorageAdapter implements StorageAdapter {
 
   async getStep(stepId: string): Promise<WorkflowRunStepRecord | null> {
     const row = this.stmts!.getStep.get(stepId) as SQLiteStepRow | undefined;
-    return row ? this.mapStepRow(row) : null;
+    return row ? mapStepRow(row, this.mapperCtx) : null;
   }
 
-  async updateStep(
-    stepId: string,
-    updates: Partial<WorkflowRunStepRecord>,
-  ): Promise<void> {
+  async updateStep(stepId: string, updates: Partial<WorkflowRunStepRecord>): Promise<void> {
     this.stmts!.updateStep.run(
       updates.status ?? null,
       updates.attempt ?? null,
       updates.result !== undefined ? JSON.stringify(updates.result) : null,
-      updates.error
-        ? JSON.stringify(sanitizeErrorForStorage(updates.error))
-        : null,
+      updates.error ? JSON.stringify(sanitizeErrorForStorage(updates.error)) : null,
       updates.finishedAt?.toISOString() ?? null,
-      stepId,
+      stepId
     );
   }
 
   async getStepsForRun(runId: string): Promise<WorkflowRunStepRecord[]> {
     const rows = this.stmts!.getStepsForRun.all(runId) as SQLiteStepRow[];
-    return rows.map((row) => this.mapStepRow(row));
+    return rows.map(row => mapStepRow(row, this.mapperCtx));
   }
 
   // ============================================================================
   // Event Operations
   // ============================================================================
 
-  async saveEvent(event: Omit<WorkflowEventRecord, "id">): Promise<void> {
+  async saveEvent(event: Omit<WorkflowEventRecord, 'id'>): Promise<void> {
     const id = generateId();
 
     this.stmts!.insertEvent.run(
@@ -430,14 +547,11 @@ export class SQLiteStorageAdapter implements StorageAdapter {
       event.eventType,
       event.level,
       event.payload !== undefined ? JSON.stringify(event.payload) : null,
-      event.timestamp.toISOString(),
+      event.timestamp.toISOString()
     );
   }
 
-  async getEventsForRun(
-    runId: string,
-    options: ListEventsOptions = {},
-  ): Promise<WorkflowEventRecord[]> {
+  async getEventsForRun(runId: string, options: ListEventsOptions = {}): Promise<WorkflowEventRecord[]> {
     const limit = options.limit ?? 1000;
     const offset = options.offset ?? 0;
     const stepKey = options.stepKey ?? null;
@@ -445,15 +559,12 @@ export class SQLiteStorageAdapter implements StorageAdapter {
 
     const rows = this.stmts!.getEventsForRun.all(
       runId,
-      stepKey,
-      stepKey,
-      level,
-      level,
-      limit,
-      offset,
+      stepKey, stepKey,
+      level, level,
+      limit, offset
     ) as SQLiteEventRow[];
 
-    return rows.map((row) => this.mapEventRow(row));
+    return rows.map(row => mapEventRow(row, this.mapperCtx));
   }
 
   // ============================================================================
@@ -463,16 +574,36 @@ export class SQLiteStorageAdapter implements StorageAdapter {
   /**
    * Execute a function within a database transaction (async interface).
    *
-   * @deprecated Use `transactionSync()` instead. This method only works when
-   * the callback performs purely synchronous operations wrapped in async/await.
-   * If the callback awaits real async I/O (network, timers, etc.), it will
-   * throw an error. `transactionSync()` makes the synchronous requirement explicit.
+   * @deprecated Use {@link transactionSync} instead. better-sqlite3 transactions
+   * are synchronous: COMMIT happens the moment the callback returns control to
+   * `db.transaction(fn)()`. If the callback awaits real async I/O (network,
+   * timers, etc.), the COMMIT has already happened by the time the awaited work
+   * runs, so its operations are **not** transactional.
+   *
+   * To make the footgun visible the adapter installs a runtime guard: when the
+   * callback's promise has not settled by the time the COMMIT returns, the
+   * deprecated method emits a `console.warn` so that the misuse surfaces in
+   * production logs. The promise is still returned so existing callers keep
+   * working — switch to `transactionSync` to silence the warning.
    */
   async transaction<T>(fn: (tx: StorageAdapter) => Promise<T>): Promise<T> {
     let fnPromise!: Promise<T>;
     this.transactionSync(() => {
       fnPromise = fn(this);
     });
+
+    // COMMIT has already executed at this point. If the callback's promise is
+    // still pending, the callback is doing async work outside the transaction
+    // boundary — log a warning so the misuse is visible in production logs.
+    if (!(await isPromiseSettled(fnPromise))) {
+      console.warn(
+        '[SQLiteStorageAdapter] transaction() callback did not settle synchronously. ' +
+        'better-sqlite3 transactions are synchronous and the COMMIT has already executed; ' +
+        'any async work inside the callback is NOT transactional. ' +
+        'Use transactionSync() with purely synchronous operations instead.'
+      );
+    }
+
     return fnPromise;
   }
 
@@ -524,67 +655,31 @@ export class SQLiteStorageAdapter implements StorageAdapter {
    */
   async getInterruptedRuns(): Promise<WorkflowRunRecord[]> {
     const rows = this.stmts!.getInterruptedRuns.all() as SQLiteRunRow[];
-    return rows.map((row) => this.mapRunRow(row));
+    return rows.map(row => mapRunRow(row, this.mapperCtx));
   }
 
   /**
    * Get the last completed step for a run.
    * Useful for resuming from a checkpoint.
    */
-  async getLastCompletedStep(
-    runId: string,
-  ): Promise<WorkflowRunStepRecord | null> {
-    const row = this.stmts!.getLastCompletedStep.get(runId) as
-      | SQLiteStepRow
-      | undefined;
-    return row ? this.mapStepRow(row) : null;
+  async getLastCompletedStep(runId: string): Promise<WorkflowRunStepRecord | null> {
+    const row = this.stmts!.getLastCompletedStep.get(runId) as SQLiteStepRow | undefined;
+    return row ? mapStepRow(row, this.mapperCtx) : null;
   }
 
   // ============================================================================
   // Row Mapping
   // ============================================================================
-
-  private mapRunRow(row: SQLiteRunRow): WorkflowRunRecord {
-    return {
-      id: row.id,
-      kind: row.kind,
-      status: row.status as RunStatus,
-      parentRunId: row.parent_run_id ?? undefined,
-      input: JSON.parse(row.input_json),
-      metadata: JSON.parse(row.metadata_json),
-      context: JSON.parse(row.context_json),
-      error: row.error_json ? JSON.parse(row.error_json) : undefined,
-      createdAt: new Date(row.created_at),
-      startedAt: row.started_at ? new Date(row.started_at) : undefined,
-      finishedAt: row.finished_at ? new Date(row.finished_at) : undefined,
-    };
-  }
-
-  private mapStepRow(row: SQLiteStepRow): WorkflowRunStepRecord {
-    return {
-      id: row.id,
-      runId: row.run_id,
-      stepKey: row.step_key,
-      stepName: row.step_name,
-      status: row.status as StepStatus,
-      attempt: row.attempt,
-      result: row.result_json ? JSON.parse(row.result_json) : undefined,
-      error: row.error_json ? JSON.parse(row.error_json) : undefined,
-      startedAt: row.started_at ? new Date(row.started_at) : undefined,
-      finishedAt: row.finished_at ? new Date(row.finished_at) : undefined,
-    };
-  }
-
-  private mapEventRow(row: SQLiteEventRow): WorkflowEventRecord {
-    return {
-      id: row.id,
-      runId: row.run_id,
-      stepKey: row.step_key ?? undefined,
-      eventType: row.event_type,
-      level: row.level as "info" | "warn" | "error",
-      payload: row.payload_json ? JSON.parse(row.payload_json) : undefined,
-      timestamp: new Date(row.timestamp),
-    };
+  //
+  // The pure row mappers (`mapRunRow`, `mapStepRow`, `mapEventRow`) live in
+  // `./sqlite-core.ts`. Each call site here builds a `MapperContext` once via
+  // `this.mapperCtx` and hands it to the mapper, which extends it with
+  // `rowId` + `column` per JSON-parse so corruption logs identify the bad row
+  // (audit M2 / L3 — PR #52).
+
+  /** Mapper context paired with the adapter's component label + optional logger. */
+  private get mapperCtx(): MapperContext {
+    return { component: 'SQLiteStorageAdapter', logger: this.logger };
   }
 
   // ============================================================================
@@ -602,15 +697,9 @@ export class SQLiteStorageAdapter implements StorageAdapter {
    * Get database statistics.
    */
   getStats(): { runs: number; steps: number; events: number } {
-    const runsCount = this.db
-      .prepare("SELECT COUNT(*) as count FROM workflow_runs")
-      .get() as { count: number };
-    const stepsCount = this.db
-      .prepare("SELECT COUNT(*) as count FROM workflow_run_steps")
-      .get() as { count: number };
-    const eventsCount = this.db
-      .prepare("SELECT COUNT(*) as count FROM workflow_events")
-      .get() as { count: number };
+    const runsCount = this.db.prepare('SELECT COUNT(*) as count FROM workflow_runs').get() as { count: number };
+    const stepsCount = this.db.prepare('SELECT COUNT(*) as count FROM workflow_run_steps').get() as { count: number };
+    const eventsCount = this.db.prepare('SELECT COUNT(*) as count FROM workflow_events').get() as { count: number };
 
     return {
       runs: runsCount.count,
@@ -623,40 +712,6 @@ export class SQLiteStorageAdapter implements StorageAdapter {
 // ============================================================================
 // SQLite Row Types
 // ============================================================================
-
-interface SQLiteRunRow {
-  id: string;
-  kind: string;
-  status: string;
-  parent_run_id: string | null;
-  input_json: string;
-  metadata_json: string;
-  context_json: string;
-  error_json: string | null;
-  created_at: string;
-  started_at: string | null;
-  finished_at: string | null;
-}
-
-interface SQLiteStepRow {
-  id: string;
-  run_id: string;
-  step_key: string;
-  step_name: string;
-  status: string;
-  attempt: number;
-  result_json: string | null;
-  error_json: string | null;
-  started_at: string | null;
-  finished_at: string | null;
-}
-
-interface SQLiteEventRow {
-  id: string;
-  run_id: string;
-  step_key: string | null;
-  event_type: string;
-  level: string;
-  payload_json: string | null;
-  timestamp: string;
-}
+//
+// `SQLiteRunRow`, `SQLiteStepRow`, and `SQLiteEventRow` now live in
+// `./sqlite-core.ts` alongside their pure row mappers.