@multiplier-labs/stepflow 0.3.1 → 0.3.4

package/src/storage/postgres.ts

@@ -1,98 +1,75 @@
 /**
  * PostgreSQL storage adapter using Kysely.
  *
- * Provides durable persistence for workflow runs, steps, and events
- * with support for distributed deployments and connection pooling.
+ * Provides durable persistence for workflow runs, steps, and events with
+ * support for distributed deployments and connection pooling.
+ *
+ * ## Module layout
+ *
+ *   - `PostgresStorageAdapter` (this file) owns the `pg.Pool` / Kysely
+ *     instance, runs schema migrations on `initialize()`, and implements all
+ *     non-CRUD methods: connection lifecycle (`close`, `transaction`),
+ *     workflow-level operations (`dequeueRun`, `cleanupStaleRuns`,
+ *     `markRunsAsFailed`, `getStats`, `deleteRun`, `deleteOldRuns`,
+ *     `getInterruptedRuns`, `getLastCompletedStep`), and the
+ *     `stepflow_step_results` accessors.
+ *
+ *   - `PostgresTransactionAdapter` (this file) is a thin shell used by
+ *     `PostgresStorageAdapter.transaction()`. It binds a transaction-scoped
+ *     Kysely query builder; everything else comes from the shared core.
+ *     Exported only for regression tests.
+ *
+ *   - `PostgresStorageCore` (./postgres-core.ts) holds the shared CRUD
+ *     methods (`createRun`, `getRun`, `updateRun`, `listRuns`, `createStep`,
+ *     `getStep`, `updateStep`, `getStepsForRun`, `saveEvent`,
+ *     `getEventsForRun`), the row mappers, and the JSON-parse helpers. Both
+ *     classes here extend it.
  */
 
-import type { Kysely as KyselyType } from "kysely";
-import type { Pool, PoolConfig } from "pg";
-import { loadPostgresDeps } from "../utils/postgres-deps.js";
+import type { Kysely as KyselyType } from 'kysely';
+import type { Pool, PoolConfig } from 'pg';
+import type { Logger } from '../core/types.js';
+import { loadPostgresDeps } from '../utils/postgres-deps.js';
 
 // Lazy-loaded dependencies - populated by loadPostgresDeps() during initialize()
 let Kysely: any;
 let PostgresDialect: any;
 let sql: any;
 let pgModule: any;
-import { generateId } from "../utils/id.js";
+import { generateId } from '../utils/id.js';
 import type {
   StorageAdapter,
   WorkflowRunRecord,
   WorkflowRunStepRecord,
-  WorkflowEventRecord,
-  ListRunsOptions,
-  ListEventsOptions,
-  PaginatedResult,
-  CreateRunInput,
-  UpdateRunInput,
   StepResult,
-  ExtendedWorkflowRunRecord,
-  ExtendedRunStatus,
   ExtendedStepStatus,
-} from "./types.js";
-import type { RunStatus, StepStatus, WorkflowError } from "../core/types.js";
-import { sanitizeErrorForStorage } from "../utils/logger.js";
+} from './types.js';
+import {
+  PostgresStorageCore,
+  mapRunRow,
+  mapStepRow,
+  safeParseOptionalField,
+  type CoreSchemaQueryBuilder,
+  type PostgresCoreDatabase,
+  type SchemaQueryBuilder,
+  type WorkflowRunsTable,
+  type WorkflowRunStepsTable,
+} from './postgres-core.js';
 
 /** Strip `stack` from a generic error record before persistence. */
-function stripStack<T extends Record<string, unknown>>(
-  error: T,
-): Omit<T, "stack"> {
+function stripStack<T extends Record<string, unknown>>(error: T): Omit<T, 'stack'> {
   const { stack: _stack, ...rest } = error;
-  return rest as Omit<T, "stack">;
+  return rest as Omit<T, 'stack'>;
 }
 
 // ============================================================================
 // Database Types (Kysely schema)
 // ============================================================================
-
-/** Kysely row type for the workflow_runs table. */
-interface WorkflowRunsTable {
-  id: string;
-  /** Workflow kind identifier (e.g. 'order-processing'). */
-  kind: string;
-  /** Current run status (maps to RunStatus). */
-  status: string;
-  /** Parent run ID for child workflows, null for top-level runs. */
-  parent_run_id: string | null;
-  /** JSON-serialized input payload. */
-  input_json: string;
-  /** JSON-serialized arbitrary metadata. */
-  metadata_json: string;
-  /** JSON-serialized workflow context (accumulated step results). */
-  context_json: string;
-  /** JSON-serialized output payload, null until run completes. */
-  output_json: string | null;
-  /** JSON-serialized error object, null unless run failed. */
-  error_json: string | null;
-  /** Execution priority (lower number = higher precedence). */
-  priority: number;
-  /** Workflow-level timeout in milliseconds, null for no timeout. */
-  timeout_ms: number | null;
-  created_at: Date;
-  started_at: Date | null;
-  finished_at: Date | null;
-}
-
-/** Kysely row type for the workflow_run_steps table. */
-interface WorkflowRunStepsTable {
-  id: string;
-  /** Foreign key to workflow_runs.id. */
-  run_id: string;
-  /** Unique step identifier within the workflow definition. */
-  step_key: string;
-  /** Human-readable step name. */
-  step_name: string;
-  /** Current step status (maps to StepStatus). */
-  status: string;
-  /** Current retry attempt number (1-based). */
-  attempt: number;
-  /** JSON-serialized step result, null until step completes. */
-  result_json: string | null;
-  /** JSON-serialized error object, null unless step failed. */
-  error_json: string | null;
-  started_at: Date | null;
-  finished_at: Date | null;
-}
+//
+// The `runs`, `workflow_run_steps`, and `workflow_events` table shapes live
+// in `./postgres-core.ts` so the shared CRUD core can target them without
+// re-declaration. The full `StepflowDatabase` schema below adds the
+// adapter-only `stepflow_step_results` table (extended storage).
 
 /** Kysely row type for the stepflow_step_results table (extended storage). */
 interface StepflowStepResultsTable {
@@ -113,26 +90,7 @@ interface StepflowStepResultsTable {
   completed_at: Date | null;
 }
 
-/** Kysely row type for the workflow_events table. */
-interface WorkflowEventsTable {
-  id: string;
-  /** Foreign key to workflow_runs.id. */
-  run_id: string;
-  /** Step key that emitted this event, null for run-level events. */
-  step_key: string | null;
-  /** Event type identifier (e.g. 'run.started', 'step.completed'). */
-  event_type: string;
-  /** Severity level: 'info', 'warn', or 'error'. */
-  level: string;
-  /** JSON-serialized event payload, null if no extra data. */
-  payload_json: string | null;
-  timestamp: Date;
-}
-
-interface StepflowDatabase {
-  runs: WorkflowRunsTable;
-  workflow_run_steps: WorkflowRunStepsTable;
-  workflow_events: WorkflowEventsTable;
+interface StepflowDatabase extends PostgresCoreDatabase {
   stepflow_step_results: StepflowStepResultsTable;
 }
 
@@ -172,6 +130,13 @@ export interface PostgresStorageConfig {
    * @default true
    */
   autoMigrate?: boolean;
+
+  /**
+   * 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;
 }
 
 // ============================================================================
@@ -216,39 +181,59 @@ export interface PostgresStorageConfig {
  * const storage = new PostgresStorageAdapter({ pool });
  * ```
  */
-export class PostgresStorageAdapter implements StorageAdapter {
+export class PostgresStorageAdapter extends PostgresStorageCore {
   private db!: KyselyType<StepflowDatabase>;
   private pool!: Pool;
   private ownsPool = false;
-  private schema: string;
   private autoMigrate: boolean;
   private initialized = false;
   private config: PostgresStorageConfig;
 
   constructor(config: PostgresStorageConfig) {
-    this.schema = config.schema ?? "public";
-    if (!/^[a-zA-Z_][a-zA-Z0-9_]{0,62}$/.test(this.schema)) {
+    const schema = config.schema ?? 'public';
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]{0,62}$/.test(schema)) {
       throw new Error(
-        `Invalid schema name "${this.schema}". Schema must start with a letter or underscore, ` +
-          `contain only alphanumeric characters and underscores, and be at most 63 characters.`,
+        `Invalid schema name "${schema}". Schema must start with a letter or underscore, ` +
+        `contain only alphanumeric characters and underscores, and be at most 63 characters.`
       );
     }
+    super(schema, config.logger);
     this.autoMigrate = config.autoMigrate !== false;
     this.config = config;
   }
 
   /**
-   * Get a schema-scoped query builder.
-   * All queries MUST use this instead of this.db directly to respect config.schema.
+   * Core-tables query builder consumed by `PostgresStorageCore`. Returns the
+   * schema-scoped Kysely view typed against the three core tables, which is
+   * what the shared CRUD methods need.
    */
-  private get qb() {
+  protected override get qb(): CoreSchemaQueryBuilder {
+    return this.db.withSchema(this.schema) as unknown as CoreSchemaQueryBuilder;
+  }
+
+  /**
+   * Extended query builder for adapter-only tables (currently
+   * `stepflow_step_results`). Kept separate from `qb` so the base class stays
+   * typed against the core schema.
+   */
+  private get extQb(): SchemaQueryBuilder<StepflowDatabase> {
     return this.db.withSchema(this.schema);
   }
 
+  /** Tag used by shared row mappers in `console.warn` messages. */
+  protected override get warnLabel(): string {
+    return 'PostgresStorageAdapter';
+  }
+
+  /** Override of `PostgresStorageCore.ensureReady()` — enforces `initialize()`. */
+  protected override ensureReady(): void {
+    this.ensureInitialized();
+  }
+
   private ensureInitialized(): void {
     if (!this.initialized) {
       throw new Error(
-        "PostgresStorageAdapter is not initialized. Call initialize() before using the adapter.",
+        'PostgresStorageAdapter is not initialized. Call initialize() before using the adapter.'
       );
     }
   }
@@ -272,16 +257,14 @@ export class PostgresStorageAdapter implements StorageAdapter {
       this.pool = this.config.pool;
       this.ownsPool = false;
     } else if (this.config.connectionString) {
-      this.pool = new pgModule.Pool({
-        connectionString: this.config.connectionString,
-      });
+      this.pool = new pgModule.Pool({ connectionString: this.config.connectionString });
       this.ownsPool = true;
     } else if (this.config.poolConfig) {
       this.pool = new pgModule.Pool(this.config.poolConfig);
       this.ownsPool = true;
     } else {
       throw new Error(
-        "PostgresStorageConfig must include either pool, connectionString, or poolConfig",
+        'PostgresStorageConfig must include either pool, connectionString, or poolConfig'
       );
     }
 
@@ -312,15 +295,54 @@ export class PostgresStorageAdapter implements StorageAdapter {
   // Schema Creation
   // ============================================================================
 
+  /**
+   * Run a single migration step. Tolerates only known-benign Postgres errors
+   * (duplicate object codes that map to "already applied"), and rethrows
+   * everything else with a clear message so partial-state upgrades are not
+   * silently swallowed.
+   */
+  protected async runMigration(label: string, fn: () => Promise<unknown>): Promise<void> {
+    try {
+      await fn();
+    } catch (err) {
+      if (PostgresStorageAdapter.isBenignMigrationError(err)) {
+        return;
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`Schema migration failed (${label}): ${message}`, { cause: err });
+    }
+  }
+
+  /**
+   * Postgres SQLSTATE codes that indicate a migration step has already been
+   * applied (object already exists). These are safe to ignore on idempotent
+   * re-runs; everything else must propagate.
+   *
+   * - 42701: duplicate_column
+   * - 42P07: duplicate_table
+   * - 42P06: duplicate_schema
+   * - 42710: duplicate_object (e.g., index, constraint)
+   */
+  private static readonly BENIGN_MIGRATION_CODES = new Set([
+    '42701',
+    '42P07',
+    '42P06',
+    '42710',
+  ]);
+
+  private static isBenignMigrationError(err: unknown): boolean {
+    if (!err || typeof err !== 'object') return false;
+    const code = (err as { code?: unknown }).code;
+    return typeof code === 'string' && PostgresStorageAdapter.BENIGN_MIGRATION_CODES.has(code);
+  }
+
   /**
    * Create the workflow tables if they don't exist.
    */
   private async createTables(): Promise<void> {
     // Create schema if not public
-    if (this.schema !== "public") {
-      await sql`CREATE SCHEMA IF NOT EXISTS ${sql.ref(this.schema)}`.execute(
-        this.db,
-      );
+    if (this.schema !== 'public') {
+      await sql`CREATE SCHEMA IF NOT EXISTS ${sql.ref(this.schema)}`.execute(this.db);
     }
 
     // Create runs table with new columns
@@ -347,16 +369,15 @@ export class PostgresStorageAdapter implements StorageAdapter {
     `.execute(this.db);
 
     // Add new columns if they don't exist (for migrations)
-    await sql`
-      ALTER TABLE ${sql.table(`${this.schema}.runs`)}
-      ADD COLUMN IF NOT EXISTS output_json JSONB,
-      ADD COLUMN IF NOT EXISTS priority INTEGER NOT NULL DEFAULT 0,
-      ADD COLUMN IF NOT EXISTS timeout_ms INTEGER
-    `
-      .execute(this.db)
-      .catch(() => {
-        // Ignore if columns already exist or syntax not supported
-      });
+    await this.runMigration(
+      `add columns to ${this.schema}.runs`,
+      () => sql`
+        ALTER TABLE ${sql.table(`${this.schema}.runs`)}
+        ADD COLUMN IF NOT EXISTS output_json JSONB,
+        ADD COLUMN IF NOT EXISTS priority INTEGER NOT NULL DEFAULT 0,
+        ADD COLUMN IF NOT EXISTS timeout_ms INTEGER
+      `.execute(this.db)
+    );
 
     // Create indexes for runs
     await sql`
@@ -473,321 +494,14 @@ export class PostgresStorageAdapter implements StorageAdapter {
   }
 
   // ============================================================================
-  // Run Operations
-  // ============================================================================
-
-  /**
-   * Create a new workflow run.
-   * Supports both legacy and new CreateRunInput interfaces.
-   */
-  async createRun(
-    run: CreateRunInput | Omit<WorkflowRunRecord, "id" | "createdAt">,
-  ): Promise<WorkflowRunRecord> {
-    this.ensureInitialized();
-    const id = "id" in run && run.id ? run.id : generateId();
-    const createdAt = new Date();
-
-    await this.qb
-      .insertInto("runs")
-      .values({
-        id,
-        kind: run.kind,
-        status: run.status,
-        parent_run_id: "parentRunId" in run ? (run.parentRunId ?? null) : null,
-        input_json: JSON.stringify(run.input),
-        metadata_json: JSON.stringify(run.metadata ?? {}),
-        context_json: JSON.stringify(run.context ?? {}), // Default to empty object
-        output_json: null,
-        error_json:
-          "error" in run && run.error
-            ? JSON.stringify(sanitizeErrorForStorage(run.error))
-            : null,
-        priority: "priority" in run ? (run.priority ?? 0) : 0,
-        timeout_ms: "timeoutMs" in run ? (run.timeoutMs ?? null) : null,
-        created_at: createdAt,
-        started_at: null,
-        finished_at: null,
-      })
-      .execute();
-
-    return {
-      id,
-      kind: run.kind,
-      status: run.status as RunStatus,
-      parentRunId: "parentRunId" in run ? run.parentRunId : undefined,
-      input: run.input,
-      context: run.context ?? {},
-      output: undefined,
-      error: undefined,
-      metadata: run.metadata ?? {},
-      priority: "priority" in run ? (run.priority ?? 0) : 0,
-      timeoutMs: "timeoutMs" in run ? run.timeoutMs : undefined,
-      createdAt,
-    };
-  }
-
-  async getRun(runId: string): Promise<WorkflowRunRecord | null> {
-    this.ensureInitialized();
-    const row = await this.qb
-      .selectFrom("runs")
-      .selectAll()
-      .where("id", "=", runId)
-      .executeTakeFirst();
-
-    return row ? this.mapRunRow(row) : null;
-  }
-
-  /**
-   * Update a workflow run.
-   * Supports both legacy Partial<WorkflowRunRecord> and new UpdateRunInput interfaces.
-   */
-  async updateRun(
-    runId: string,
-    updates: UpdateRunInput | Partial<WorkflowRunRecord>,
-  ): Promise<void> {
-    this.ensureInitialized();
-    const updateData: Partial<WorkflowRunsTable> = {};
-
-    if (updates.status !== undefined) {
-      updateData.status = updates.status;
-    }
-    if (updates.context !== undefined) {
-      updateData.context_json = JSON.stringify(updates.context);
-    }
-    if ("output" in updates && updates.output !== undefined) {
-      updateData.output_json = JSON.stringify(updates.output);
-    }
-    if (updates.error !== undefined) {
-      updateData.error_json = JSON.stringify(
-        sanitizeErrorForStorage(updates.error),
-      );
-    }
-    if (updates.startedAt !== undefined) {
-      updateData.started_at = updates.startedAt;
-    }
-    if (updates.finishedAt !== undefined) {
-      updateData.finished_at = updates.finishedAt;
-    }
-
-    if (Object.keys(updateData).length > 0) {
-      await this.qb
-        .updateTable("runs")
-        .set(updateData)
-        .where("id", "=", runId)
-        .execute();
-    }
-  }
-
-  /**
-   * List workflow runs with filtering and pagination.
-   */
-  /**
-   * Apply common run filters to a Kysely query builder.
-   * Used by both the data query and count query in listRuns to avoid duplication.
-   */
-  private applyRunsFilters<T extends { where(col: any, op: any, val: any): T }>(
-    query: T,
-    options: ListRunsOptions,
-  ): T {
-    if (options.kind) {
-      query = query.where("kind", "=", options.kind);
-    }
-    if (options.status) {
-      const statuses = Array.isArray(options.status)
-        ? options.status
-        : [options.status];
-      query = query.where("status", "in", statuses);
-    }
-    if (options.parentRunId !== undefined) {
-      query = query.where("parent_run_id", "=", options.parentRunId);
-    }
-    return query;
-  }
-
-  async listRuns(
-    options: ListRunsOptions = {},
-  ): Promise<PaginatedResult<WorkflowRunRecord>> {
-    this.ensureInitialized();
-    const limit = options.limit ?? 50;
-    const offset = options.offset ?? 0;
-
-    let query = this.applyRunsFilters(
-      this.qb.selectFrom("runs").selectAll(),
-      options,
-    );
-
-    const countQuery = this.applyRunsFilters(
-      this.qb.selectFrom("runs").select(sql<number>`count(*)`.as("count")),
-      options,
-    );
-
-    const countResult = (await countQuery.executeTakeFirst()) as
-      | { count?: string | number }
-      | undefined;
-    const total = Number(countResult?.count ?? 0);
-
-    // Order
-    const orderBy = options.orderBy ?? "createdAt";
-    const orderDirection = options.orderDirection ?? "desc";
-    const orderColumn =
-      orderBy === "createdAt"
-        ? "created_at"
-        : orderBy === "startedAt"
-          ? "started_at"
-          : "finished_at";
-
-    query = query.orderBy(orderColumn, orderDirection);
-
-    // Apply pagination
-    query = query.limit(limit).offset(offset);
-
-    const rows = await query.execute();
-
-    return {
-      items: rows.map((row) => this.mapRunRow(row)),
-      total,
-    };
-  }
-
-  // ============================================================================
-  // Step Operations
-  // ============================================================================
-
-  async createStep(
-    step: Omit<WorkflowRunStepRecord, "id">,
-  ): Promise<WorkflowRunStepRecord> {
-    this.ensureInitialized();
-    const id = generateId();
-
-    await this.qb
-      .insertInto("workflow_run_steps")
-      .values({
-        id,
-        run_id: step.runId,
-        step_key: step.stepKey,
-        step_name: step.stepName,
-        status: step.status,
-        attempt: step.attempt,
-        result_json:
-          step.result !== undefined ? JSON.stringify(step.result) : null,
-        error_json: step.error
-          ? JSON.stringify(sanitizeErrorForStorage(step.error))
-          : null,
-        started_at: step.startedAt ?? null,
-        finished_at: step.finishedAt ?? null,
-      })
-      .execute();
-
-    return { ...step, id };
-  }
-
-  async getStep(stepId: string): Promise<WorkflowRunStepRecord | null> {
-    this.ensureInitialized();
-    const row = await this.qb
-      .selectFrom("workflow_run_steps")
-      .selectAll()
-      .where("id", "=", stepId)
-      .executeTakeFirst();
-
-    return row ? this.mapStepRow(row) : null;
-  }
-
-  async updateStep(
-    stepId: string,
-    updates: Partial<WorkflowRunStepRecord>,
-  ): Promise<void> {
-    this.ensureInitialized();
-    const updateData: Partial<WorkflowRunStepsTable> = {};
-
-    if (updates.status !== undefined) {
-      updateData.status = updates.status;
-    }
-    if (updates.attempt !== undefined) {
-      updateData.attempt = updates.attempt;
-    }
-    if (updates.result !== undefined) {
-      updateData.result_json = JSON.stringify(updates.result);
-    }
-    if (updates.error !== undefined) {
-      updateData.error_json = JSON.stringify(
-        sanitizeErrorForStorage(updates.error),
-      );
-    }
-    if (updates.finishedAt !== undefined) {
-      updateData.finished_at = updates.finishedAt;
-    }
-
-    if (Object.keys(updateData).length > 0) {
-      await this.qb
-        .updateTable("workflow_run_steps")
-        .set(updateData)
-        .where("id", "=", stepId)
-        .execute();
-    }
-  }
-
-  async getStepsForRun(runId: string): Promise<WorkflowRunStepRecord[]> {
-    this.ensureInitialized();
-    const rows = await this.qb
-      .selectFrom("workflow_run_steps")
-      .selectAll()
-      .where("run_id", "=", runId)
-      .orderBy("started_at", "asc")
-      .execute();
-
-    return rows.map((row) => this.mapStepRow(row));
-  }
-
-  // ============================================================================
-  // Event Operations
+  // Run / Step / Event CRUD
   // ============================================================================
-
-  async saveEvent(event: Omit<WorkflowEventRecord, "id">): Promise<void> {
-    this.ensureInitialized();
-    const id = generateId();
-
-    await this.qb
-      .insertInto("workflow_events")
-      .values({
-        id,
-        run_id: event.runId,
-        step_key: event.stepKey ?? null,
-        event_type: event.eventType,
-        level: event.level,
-        payload_json:
-          event.payload !== undefined ? JSON.stringify(event.payload) : null,
-        timestamp: event.timestamp,
-      })
-      .execute();
-  }
-
-  async getEventsForRun(
-    runId: string,
-    options: ListEventsOptions = {},
-  ): Promise<WorkflowEventRecord[]> {
-    this.ensureInitialized();
-    const limit = options.limit ?? 1000;
-    const offset = options.offset ?? 0;
-
-    let query = this.qb
-      .selectFrom("workflow_events")
-      .selectAll()
-      .where("run_id", "=", runId);
-
-    if (options.stepKey) {
-      query = query.where("step_key", "=", options.stepKey);
-    }
-
-    if (options.level) {
-      query = query.where("level", "=", options.level);
-    }
-
-    query = query.orderBy("timestamp", "asc").limit(limit).offset(offset);
-
-    const rows = await query.execute();
-
-    return rows.map((row) => this.mapEventRow(row));
-  }
+  //
+  // The CRUD methods (`createRun`, `getRun`, `updateRun`, `listRuns`,
+  // `createStep`, `getStep`, `updateStep`, `getStepsForRun`, `saveEvent`,
+  // `getEventsForRun`) are inherited from `PostgresStorageCore`. Each call
+  // routes through `this.qb` (overridden above) and `this.ensureReady()`
+  // which calls `this.ensureInitialized()`.
 
   // ============================================================================
   // Transaction Support
@@ -800,7 +514,7 @@ export class PostgresStorageAdapter implements StorageAdapter {
     this.ensureInitialized();
     return await this.db.transaction().execute(async (trx) => {
       // Create a transactional adapter wrapper
-      const txAdapter = new PostgresTransactionAdapter(trx, this.schema);
+      const txAdapter = new PostgresTransactionAdapter(trx, this.schema, this.logger);
       return await fn(txAdapter);
     });
   }
@@ -816,8 +530,8 @@ export class PostgresStorageAdapter implements StorageAdapter {
   async deleteOldRuns(olderThan: Date): Promise<number> {
     this.ensureInitialized();
     const result = await this.qb
-      .deleteFrom("runs")
-      .where("created_at", "<", olderThan)
+      .deleteFrom('runs')
+      .where('created_at', '<', olderThan)
       .executeTakeFirst();
 
     return Number(result.numDeletedRows);
@@ -834,33 +548,31 @@ export class PostgresStorageAdapter implements StorageAdapter {
   async getInterruptedRuns(): Promise<WorkflowRunRecord[]> {
     this.ensureInitialized();
     const rows = await this.qb
-      .selectFrom("runs")
+      .selectFrom('runs')
       .selectAll()
-      .where("status", "in", ["queued", "running"])
-      .orderBy("created_at", "asc")
+      .where('status', 'in', ['queued', 'running'])
+      .orderBy('created_at', 'asc')
       .execute();
 
-    return rows.map((row) => this.mapRunRow(row));
+    return rows.map(row => mapRunRow(row as WorkflowRunsTable, this.mapperCtx));
   }
 
   /**
    * Get the last completed step for a run.
    * Useful for resuming from a checkpoint.
    */
-  async getLastCompletedStep(
-    runId: string,
-  ): Promise<WorkflowRunStepRecord | null> {
+  async getLastCompletedStep(runId: string): Promise<WorkflowRunStepRecord | null> {
     this.ensureInitialized();
     const row = await this.qb
-      .selectFrom("workflow_run_steps")
+      .selectFrom('workflow_run_steps')
       .selectAll()
-      .where("run_id", "=", runId)
-      .where("status", "=", "succeeded")
-      .orderBy("finished_at", "desc")
+      .where('run_id', '=', runId)
+      .where('status', '=', 'succeeded')
+      .orderBy('finished_at', 'desc')
       .limit(1)
       .executeTakeFirst();
 
-    return row ? this.mapStepRow(row) : null;
+    return row ? mapStepRow(row as WorkflowRunStepsTable, this.mapperCtx) : null;
   }
 
   // ============================================================================
@@ -874,15 +586,12 @@ export class PostgresStorageAdapter implements StorageAdapter {
    * @param workflowKinds - Optional list of workflow kinds to filter by
    * @returns The dequeued run, or null if no runs are available
    */
-  async dequeueRun(
-    workflowKinds?: string[],
-  ): Promise<WorkflowRunRecord | null> {
+  async dequeueRun(workflowKinds?: string[]): Promise<WorkflowRunRecord | null> {
     this.ensureInitialized();
     // Use raw SQL for FOR UPDATE SKIP LOCKED
-    const kindFilter =
-      workflowKinds && workflowKinds.length > 0
-        ? sql`AND kind = ANY(${workflowKinds}::text[])`
-        : sql``;
+    const kindFilter = workflowKinds && workflowKinds.length > 0
+      ? sql`AND kind = ANY(${workflowKinds}::text[])`
+      : sql``;
 
     const result = await sql<WorkflowRunsTable>`
       UPDATE ${sql.table(`${this.schema}.runs`)}
@@ -898,148 +607,40 @@ export class PostgresStorageAdapter implements StorageAdapter {
     `.execute(this.db);
 
     const row = result.rows[0];
-    return row ? this.mapRunRow(row) : null;
+    return row ? mapRunRow(row, this.mapperCtx) : null;
   }
 
   // ============================================================================
-  // Row Mapping
+  // Row Mapping (adapter-only tables)
   // ============================================================================
-
-  private mapRunRow(row: WorkflowRunsTable): WorkflowRunRecord {
-    return {
-      id: row.id,
-      kind: row.kind,
-      status: row.status as RunStatus,
-      parentRunId: row.parent_run_id ?? undefined,
-      input:
-        typeof row.input_json === "string"
-          ? JSON.parse(row.input_json)
-          : row.input_json,
-      context:
-        typeof row.context_json === "string"
-          ? JSON.parse(row.context_json)
-          : row.context_json,
-      output: row.output_json
-        ? typeof row.output_json === "string"
-          ? JSON.parse(row.output_json)
-          : row.output_json
-        : undefined,
-      error: row.error_json
-        ? typeof row.error_json === "string"
-          ? JSON.parse(row.error_json)
-          : row.error_json
-        : undefined,
-      metadata:
-        typeof row.metadata_json === "string"
-          ? JSON.parse(row.metadata_json)
-          : row.metadata_json,
-      priority: row.priority ?? 0,
-      timeoutMs: row.timeout_ms ?? 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,
-    };
-  }
-
-  /**
-   * Map a database row to an extended workflow run record.
-   */
-  private mapExtendedRunRow(row: WorkflowRunsTable): ExtendedWorkflowRunRecord {
-    return {
-      id: row.id,
-      kind: row.kind,
-      status: row.status as ExtendedRunStatus,
-      input:
-        typeof row.input_json === "string"
-          ? JSON.parse(row.input_json)
-          : row.input_json,
-      metadata:
-        typeof row.metadata_json === "string"
-          ? JSON.parse(row.metadata_json)
-          : row.metadata_json,
-      context:
-        typeof row.context_json === "string"
-          ? JSON.parse(row.context_json)
-          : row.context_json,
-      output: row.output_json
-        ? typeof row.output_json === "string"
-          ? JSON.parse(row.output_json)
-          : row.output_json
-        : undefined,
-      error: row.error_json
-        ? typeof row.error_json === "string"
-          ? JSON.parse(row.error_json)
-          : row.error_json
-        : undefined,
-      priority: row.priority ?? 0,
-      timeoutMs: row.timeout_ms ?? 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,
-    };
-  }
+  //
+  // Mappers and JSON-parse helpers for the three core tables live in
+  // `./postgres-core.ts`. The single mapper kept here covers
+  // `stepflow_step_results`, the only table outside the core schema.
 
   private mapStepResultRow(row: StepflowStepResultsTable): StepResult {
+    const ctx = this.mapperCtx;
     return {
       id: row.id,
       runId: row.run_id,
       stepName: row.step_name,
       status: row.status as ExtendedStepStatus,
-      output: row.output_json
-        ? typeof row.output_json === "string"
-          ? JSON.parse(row.output_json)
-          : row.output_json
-        : undefined,
-      error: row.error_json
-        ? typeof row.error_json === "string"
-          ? JSON.parse(row.error_json)
-          : row.error_json
-        : undefined,
+      output: safeParseOptionalField(row.output_json, {
+        ...ctx,
+        rowId: row.id,
+        column: 'output_json',
+      }) as Record<string, unknown> | undefined,
+      error: safeParseOptionalField(row.error_json, {
+        ...ctx,
+        rowId: row.id,
+        column: 'error_json',
+      }) as Record<string, unknown> | undefined,
       attempt: row.attempt,
       startedAt: row.started_at ? new Date(row.started_at) : undefined,
       completedAt: row.completed_at ? new Date(row.completed_at) : undefined,
     };
   }
 
-  private mapStepRow(row: WorkflowRunStepsTable): 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
-        ? typeof row.result_json === "string"
-          ? JSON.parse(row.result_json)
-          : row.result_json
-        : undefined,
-      error: row.error_json
-        ? typeof row.error_json === "string"
-          ? JSON.parse(row.error_json)
-          : 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: WorkflowEventsTable): 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
-        ? typeof row.payload_json === "string"
-          ? JSON.parse(row.payload_json)
-          : row.payload_json
-        : undefined,
-      timestamp: new Date(row.timestamp),
-    };
-  }
-
   // ============================================================================
   // New WorkflowStorage Methods
   // ============================================================================
@@ -1050,7 +651,10 @@ export class PostgresStorageAdapter implements StorageAdapter {
    */
   async deleteRun(id: string): Promise<void> {
     this.ensureInitialized();
-    await this.qb.deleteFrom("runs").where("id", "=", id).execute();
+    await this.qb
+      .deleteFrom('runs')
+      .where('id', '=', id)
+      .execute();
   }
 
   /**
@@ -1112,16 +716,13 @@ export class PostgresStorageAdapter implements StorageAdapter {
   /**
    * Get a specific step result by run ID and step name.
    */
-  async getStepResult(
-    runId: string,
-    stepName: string,
-  ): Promise<StepResult | undefined> {
+  async getStepResult(runId: string, stepName: string): Promise<StepResult | undefined> {
     this.ensureInitialized();
-    const row = await this.qb
-      .selectFrom("stepflow_step_results")
+    const row = await this.extQb
+      .selectFrom('stepflow_step_results')
       .selectAll()
-      .where("run_id", "=", runId)
-      .where("step_name", "=", stepName)
+      .where('run_id', '=', runId)
+      .where('step_name', '=', stepName)
       .executeTakeFirst();
 
     return row ? this.mapStepResultRow(row) : undefined;
@@ -1132,52 +733,46 @@ export class PostgresStorageAdapter implements StorageAdapter {
    */
   async getStepResults(runId: string): Promise<StepResult[]> {
     this.ensureInitialized();
-    const rows = await this.qb
-      .selectFrom("stepflow_step_results")
+    const rows = await this.extQb
+      .selectFrom('stepflow_step_results')
       .selectAll()
-      .where("run_id", "=", runId)
-      .orderBy("started_at", "asc")
+      .where('run_id', '=', runId)
+      .orderBy('started_at', 'asc')
       .execute();
 
-    return rows.map((row) => this.mapStepResultRow(row));
+    return rows.map(row => this.mapStepResultRow(row));
   }
 
   /**
    * Save or update a step result.
    * Uses upsert to handle both new and existing results.
    */
-  async saveStepResult(
-    result: Omit<StepResult, "id"> & { id?: string },
-  ): Promise<void> {
+  async saveStepResult(result: Omit<StepResult, 'id'> & { id?: string }): Promise<void> {
     this.ensureInitialized();
     const id = result.id ?? generateId();
 
-    await this.qb
-      .insertInto("stepflow_step_results")
+    await this.extQb
+      .insertInto('stepflow_step_results')
       .values({
         id,
         run_id: result.runId,
         step_name: result.stepName,
         status: result.status,
         output_json: result.output ? JSON.stringify(result.output) : null,
-        error_json: result.error
-          ? JSON.stringify(stripStack(result.error))
-          : null,
+        error_json: result.error ? JSON.stringify(stripStack(result.error)) : null,
         attempt: result.attempt,
         started_at: result.startedAt ?? null,
         completed_at: result.completedAt ?? null,
       })
-      .onConflict((oc) =>
-        oc.columns(["run_id", "step_name"]).doUpdateSet({
+      .onConflict(oc =>
+        oc.columns(['run_id', 'step_name']).doUpdateSet({
           status: result.status,
           output_json: result.output ? JSON.stringify(result.output) : null,
-          error_json: result.error
-            ? JSON.stringify(stripStack(result.error))
-            : null,
+          error_json: result.error ? JSON.stringify(stripStack(result.error)) : null,
           attempt: result.attempt,
           started_at: result.startedAt ?? null,
           completed_at: result.completedAt ?? null,
-        }),
+        })
       )
       .execute();
   }
@@ -1191,20 +786,11 @@ export class PostgresStorageAdapter implements StorageAdapter {
    */
   async getStats(): Promise<{ runs: number; steps: number; events: number }> {
     this.ensureInitialized();
-    const [runsCount, stepsCount, eventsCount] = (await Promise.all([
-      this.qb
-        .selectFrom("runs")
-        .select(sql`count(*)`.as("count"))
-        .executeTakeFirst(),
-      this.qb
-        .selectFrom("workflow_run_steps")
-        .select(sql`count(*)`.as("count"))
-        .executeTakeFirst(),
-      this.qb
-        .selectFrom("workflow_events")
-        .select(sql`count(*)`.as("count"))
-        .executeTakeFirst(),
-    ])) as { count?: string | number }[];
+    const [runsCount, stepsCount, eventsCount] = await Promise.all([
+      this.qb.selectFrom('runs').select(sql`count(*)`.as('count')).executeTakeFirst(),
+      this.qb.selectFrom('workflow_run_steps').select(sql`count(*)`.as('count')).executeTakeFirst(),
+      this.qb.selectFrom('workflow_events').select(sql`count(*)`.as('count')).executeTakeFirst(),
+    ]) as { count?: string | number }[];
 
     return {
       runs: Number(runsCount?.count ?? 0),
@@ -1220,328 +806,27 @@ export class PostgresStorageAdapter implements StorageAdapter {
 
 /**
  * A StorageAdapter wrapper for use within transactions.
- * This is used internally by PostgresStorageAdapter.transaction().
+ *
+ * Used internally by `PostgresStorageAdapter.transaction()`. All CRUD methods
+ * are inherited from `PostgresStorageCore`; this class only binds the
+ * transaction-scoped query builder.
+ *
+ * Exported for regression testing; not part of the public API.
  */
-class PostgresTransactionAdapter implements StorageAdapter {
-  private qb: ReturnType<KyselyType<StepflowDatabase>["withSchema"]>;
-
-  constructor(
-    private trx: KyselyType<StepflowDatabase>,
-    private schema: string,
-  ) {
-    this.qb = trx.withSchema(schema);
-  }
-
-  async createRun(
-    run: CreateRunInput | Omit<WorkflowRunRecord, "id" | "createdAt">,
-  ): Promise<WorkflowRunRecord> {
-    const id = "id" in run && run.id ? run.id : generateId();
-    const createdAt = new Date();
-
-    await this.qb
-      .insertInto("runs")
-      .values({
-        id,
-        kind: run.kind,
-        status: run.status,
-        parent_run_id: "parentRunId" in run ? (run.parentRunId ?? null) : null,
-        input_json: JSON.stringify(run.input),
-        metadata_json: JSON.stringify(run.metadata ?? {}),
-        context_json: JSON.stringify(run.context ?? {}),
-        output_json: null,
-        error_json:
-          "error" in run && run.error
-            ? JSON.stringify(sanitizeErrorForStorage(run.error))
-            : null,
-        priority: "priority" in run ? (run.priority ?? 0) : 0,
-        timeout_ms: "timeoutMs" in run ? (run.timeoutMs ?? null) : null,
-        created_at: createdAt,
-        started_at: null,
-        finished_at: null,
-      })
-      .execute();
-
-    return {
-      id,
-      kind: run.kind,
-      status: run.status as RunStatus,
-      parentRunId: "parentRunId" in run ? run.parentRunId : undefined,
-      input: run.input,
-      context: run.context ?? {},
-      output: undefined,
-      error: undefined,
-      metadata: run.metadata ?? {},
-      priority: "priority" in run ? (run.priority ?? 0) : 0,
-      timeoutMs: "timeoutMs" in run ? run.timeoutMs : undefined,
-      createdAt,
-    };
-  }
-
-  async getRun(runId: string): Promise<WorkflowRunRecord | null> {
-    const row = await this.qb
-      .selectFrom("runs")
-      .selectAll()
-      .where("id", "=", runId)
-      .executeTakeFirst();
-
-    return row ? this.mapRunRow(row) : null;
-  }
-
-  async updateRun(
-    runId: string,
-    updates: UpdateRunInput | Partial<WorkflowRunRecord>,
-  ): Promise<void> {
-    const updateData: Partial<WorkflowRunsTable> = {};
-
-    if (updates.status !== undefined) updateData.status = updates.status;
-    if (updates.context !== undefined)
-      updateData.context_json = JSON.stringify(updates.context);
-    if ("output" in updates && updates.output !== undefined)
-      updateData.output_json = JSON.stringify(updates.output);
-    if (updates.error !== undefined)
-      updateData.error_json = JSON.stringify(
-        sanitizeErrorForStorage(updates.error as WorkflowError),
-      );
-    if (updates.startedAt !== undefined)
-      updateData.started_at = updates.startedAt;
-    if (updates.finishedAt !== undefined)
-      updateData.finished_at = updates.finishedAt;
-
-    if (Object.keys(updateData).length > 0) {
-      await this.qb
-        .updateTable("runs")
-        .set(updateData)
-        .where("id", "=", runId)
-        .execute();
-    }
-  }
-
-  async listRuns(
-    options: ListRunsOptions = {},
-  ): Promise<PaginatedResult<WorkflowRunRecord>> {
-    const limit = options.limit ?? 50;
-    const offset = options.offset ?? 0;
-
-    let query = this.qb.selectFrom("runs").selectAll();
-
-    if (options.kind) query = query.where("kind", "=", options.kind);
-    if (options.status) {
-      const statuses = Array.isArray(options.status)
-        ? options.status
-        : [options.status];
-      query = query.where("status", "in", statuses);
-    }
-    if (options.parentRunId !== undefined) {
-      query = query.where("parent_run_id", "=", options.parentRunId);
-    }
-
-    const orderColumn =
-      (options.orderBy ?? "createdAt") === "createdAt"
-        ? "created_at"
-        : options.orderBy === "startedAt"
-          ? "started_at"
-          : "finished_at";
-    const orderDirection = options.orderDirection ?? "desc";
-
-    query = query
-      .orderBy(orderColumn, orderDirection)
-      .limit(limit)
-      .offset(offset);
-
-    const rows = await query.execute();
-
-    return {
-      items: rows.map((row) => this.mapRunRow(row)),
-      total: rows.length, // Simplified for transaction context
-    };
-  }
-
-  async createStep(
-    step: Omit<WorkflowRunStepRecord, "id">,
-  ): Promise<WorkflowRunStepRecord> {
-    const id = generateId();
-
-    await this.qb
-      .insertInto("workflow_run_steps")
-      .values({
-        id,
-        run_id: step.runId,
-        step_key: step.stepKey,
-        step_name: step.stepName,
-        status: step.status,
-        attempt: step.attempt,
-        result_json:
-          step.result !== undefined ? JSON.stringify(step.result) : null,
-        error_json: step.error
-          ? JSON.stringify(sanitizeErrorForStorage(step.error))
-          : null,
-        started_at: step.startedAt ?? null,
-        finished_at: step.finishedAt ?? null,
-      })
-      .execute();
+export class PostgresTransactionAdapter extends PostgresStorageCore {
+  private readonly _qb: CoreSchemaQueryBuilder;
 
-    return { ...step, id };
+  constructor(trx: KyselyType<StepflowDatabase>, schema: string, logger?: Logger) {
+    super(schema, logger);
+    this._qb = trx.withSchema(schema) as unknown as CoreSchemaQueryBuilder;
   }
 
-  async getStep(stepId: string): Promise<WorkflowRunStepRecord | null> {
-    const row = await this.qb
-      .selectFrom("workflow_run_steps")
-      .selectAll()
-      .where("id", "=", stepId)
-      .executeTakeFirst();
-
-    return row ? this.mapStepRow(row) : null;
+  protected override get qb(): CoreSchemaQueryBuilder {
+    return this._qb;
   }
 
-  async updateStep(
-    stepId: string,
-    updates: Partial<WorkflowRunStepRecord>,
-  ): Promise<void> {
-    const updateData: Partial<WorkflowRunStepsTable> = {};
-
-    if (updates.status !== undefined) updateData.status = updates.status;
-    if (updates.attempt !== undefined) updateData.attempt = updates.attempt;
-    if (updates.result !== undefined)
-      updateData.result_json = JSON.stringify(updates.result);
-    if (updates.error !== undefined)
-      updateData.error_json = JSON.stringify(
-        sanitizeErrorForStorage(updates.error as WorkflowError),
-      );
-    if (updates.finishedAt !== undefined)
-      updateData.finished_at = updates.finishedAt;
-
-    if (Object.keys(updateData).length > 0) {
-      await this.qb
-        .updateTable("workflow_run_steps")
-        .set(updateData)
-        .where("id", "=", stepId)
-        .execute();
-    }
-  }
-
-  async getStepsForRun(runId: string): Promise<WorkflowRunStepRecord[]> {
-    const rows = await this.qb
-      .selectFrom("workflow_run_steps")
-      .selectAll()
-      .where("run_id", "=", runId)
-      .orderBy("started_at", "asc")
-      .execute();
-
-    return rows.map((row) => this.mapStepRow(row));
-  }
-
-  async saveEvent(event: Omit<WorkflowEventRecord, "id">): Promise<void> {
-    const id = generateId();
-
-    await this.qb
-      .insertInto("workflow_events")
-      .values({
-        id,
-        run_id: event.runId,
-        step_key: event.stepKey ?? null,
-        event_type: event.eventType,
-        level: event.level,
-        payload_json:
-          event.payload !== undefined ? JSON.stringify(event.payload) : null,
-        timestamp: event.timestamp,
-      })
-      .execute();
-  }
-
-  async getEventsForRun(
-    runId: string,
-    options: ListEventsOptions = {},
-  ): Promise<WorkflowEventRecord[]> {
-    let query = this.qb
-      .selectFrom("workflow_events")
-      .selectAll()
-      .where("run_id", "=", runId);
-
-    if (options.stepKey) query = query.where("step_key", "=", options.stepKey);
-    if (options.level) query = query.where("level", "=", options.level);
-
-    const rows = await query
-      .orderBy("timestamp", "asc")
-      .limit(options.limit ?? 1000)
-      .offset(options.offset ?? 0)
-      .execute();
-
-    return rows.map((row) => this.mapEventRow(row));
-  }
-
-  private mapRunRow(row: WorkflowRunsTable): WorkflowRunRecord {
-    return {
-      id: row.id,
-      kind: row.kind,
-      status: row.status as RunStatus,
-      parentRunId: row.parent_run_id ?? undefined,
-      input:
-        typeof row.input_json === "string"
-          ? JSON.parse(row.input_json)
-          : row.input_json,
-      context:
-        typeof row.context_json === "string"
-          ? JSON.parse(row.context_json)
-          : row.context_json,
-      output: row.output_json
-        ? typeof row.output_json === "string"
-          ? JSON.parse(row.output_json)
-          : row.output_json
-        : undefined,
-      error: row.error_json
-        ? typeof row.error_json === "string"
-          ? JSON.parse(row.error_json)
-          : row.error_json
-        : undefined,
-      metadata:
-        typeof row.metadata_json === "string"
-          ? JSON.parse(row.metadata_json)
-          : row.metadata_json,
-      priority: row.priority ?? 0,
-      timeoutMs: row.timeout_ms ?? 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: WorkflowRunStepsTable): 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
-        ? typeof row.result_json === "string"
-          ? JSON.parse(row.result_json)
-          : row.result_json
-        : undefined,
-      error: row.error_json
-        ? typeof row.error_json === "string"
-          ? JSON.parse(row.error_json)
-          : 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: WorkflowEventsTable): 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
-        ? typeof row.payload_json === "string"
-          ? JSON.parse(row.payload_json)
-          : row.payload_json
-        : undefined,
-      timestamp: new Date(row.timestamp),
-    };
+  protected override get warnLabel(): string {
+    return 'PostgresTransactionAdapter';
   }
 }