@multiplier-labs/stepflow 0.3.3 → 0.3.4

package/src/storage/postgres.ts

@@ -1,12 +1,34 @@
 /**
  * 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 type { Logger } from '../core/types.js';
 import { loadPostgresDeps } from '../utils/postgres-deps.js';
 
 // Lazy-loaded dependencies - populated by loadPostgresDeps() during initialize()
@@ -19,19 +41,20 @@ 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';
+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'> {
@@ -42,55 +65,11 @@ function stripStack<T extends Record<string, unknown>>(error: T): 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 {
@@ -111,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;
 }
 
@@ -170,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;
 }
 
 // ============================================================================
@@ -214,35 +181,55 @@ 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, ` +
+        `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(
@@ -308,6 +295,47 @@ 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.
    */
@@ -341,14 +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`
@@ -465,287 +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
@@ -758,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);
     });
   }
@@ -798,7 +554,7 @@ export class PostgresStorageAdapter implements StorageAdapter {
       .orderBy('created_at', 'asc')
       .execute();
 
-    return rows.map(row => this.mapRunRow(row));
+    return rows.map(row => mapRunRow(row as WorkflowRunsTable, this.mapperCtx));
   }
 
   /**
@@ -816,7 +572,7 @@ export class PostgresStorageAdapter implements StorageAdapter {
       .limit(1)
       .executeTakeFirst();
 
-    return row ? this.mapStepRow(row) : null;
+    return row ? mapStepRow(row as WorkflowRunStepsTable, this.mapperCtx) : null;
   }
 
   // ============================================================================
@@ -851,94 +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
   // ============================================================================
@@ -1016,7 +718,7 @@ export class PostgresStorageAdapter implements StorageAdapter {
    */
   async getStepResult(runId: string, stepName: string): Promise<StepResult | undefined> {
     this.ensureInitialized();
-    const row = await this.qb
+    const row = await this.extQb
       .selectFrom('stepflow_step_results')
       .selectAll()
       .where('run_id', '=', runId)
@@ -1031,7 +733,7 @@ export class PostgresStorageAdapter implements StorageAdapter {
    */
   async getStepResults(runId: string): Promise<StepResult[]> {
     this.ensureInitialized();
-    const rows = await this.qb
+    const rows = await this.extQb
       .selectFrom('stepflow_step_results')
       .selectAll()
       .where('run_id', '=', runId)
@@ -1049,7 +751,7 @@ export class PostgresStorageAdapter implements StorageAdapter {
     this.ensureInitialized();
     const id = result.id ?? generateId();
 
-    await this.qb
+    await this.extQb
       .insertInto('stepflow_step_results')
       .values({
         id,
@@ -1104,248 +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;
-  }
+export class PostgresTransactionAdapter extends PostgresStorageCore {
+  private readonly _qb: CoreSchemaQueryBuilder;
 
-  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();
-    }
+  constructor(trx: KyselyType<StepflowDatabase>, schema: string, logger?: Logger) {
+    super(schema, logger);
+    this._qb = trx.withSchema(schema) as unknown as CoreSchemaQueryBuilder;
   }
 
-  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
-    };
+  protected override get qb(): CoreSchemaQueryBuilder {
+    return this._qb;
   }
 
-  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();
-
-    return { ...step, id };
-  }
-
-  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;
-  }
-
-  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';
   }
 }