@shipfox/api-workflows 2.0.0

package/src/db/run-timeout.test.ts

@@ -0,0 +1,102 @@
+import {WORKFLOWS_WORKFLOW_RUN_TERMINATED} from '@shipfox/api-workflows-dto';
+import {eq} from 'drizzle-orm';
+import type {JobExecutionStatus} from '#core/entities/job-execution.js';
+import {db} from '#db/db.js';
+import {jobExecutions} from '#db/schema/job-executions.js';
+import {jobs} from '#db/schema/jobs.js';
+import {workflowsOutbox} from '#db/schema/outbox.js';
+import {failWorkflowRunAsTimedOut} from '#db/workflow-runs.js';
+import {jobFactory} from '#test/index.js';
+
+async function insertExecution(jobId: string, sequence: number, status: JobExecutionStatus) {
+  const [row] = await db()
+    .insert(jobExecutions)
+    .values({jobId, sequence, name: `firing #${sequence}`, status, triggerEvents: []})
+    .returning();
+  if (!row) throw new Error('insertExecution: no row returned');
+  return row;
+}
+
+function readJob(jobId: string) {
+  return db()
+    .select()
+    .from(jobs)
+    .where(eq(jobs.id, jobId))
+    .limit(1)
+    .then((rows) => rows[0]);
+}
+
+describe('failWorkflowRunAsTimedOut', () => {
+  it('drives a running listener job, its execution, and the run to timed out', async () => {
+    const job = await jobFactory.create({}, {transient: {status: 'running'}});
+    await db()
+      .update(jobs)
+      .set({mode: 'listening', listenerStatus: 'listening'})
+      .where(eq(jobs.id, job.id));
+    await db().delete(jobExecutions).where(eq(jobExecutions.jobId, job.id));
+    const execution = await insertExecution(job.id, 1, 'running');
+
+    const run = await failWorkflowRunAsTimedOut({runAttemptId: job.workflowRunAttemptId});
+
+    const storedJob = await readJob(job.id);
+    const [storedExecution] = await db()
+      .select()
+      .from(jobExecutions)
+      .where(eq(jobExecutions.id, execution.id));
+    expect(run.status).toBe('failed');
+    expect(storedJob?.status).toBe('failed');
+    expect(storedJob?.statusReason).toBe('timed_out');
+    expect(storedJob?.listenerStatus).toBe('resolved');
+    expect(storedJob?.resolutionReason).toBe('cancelled');
+    expect(storedExecution?.status).toBe('failed');
+    expect(storedExecution?.statusReason).toBe('timed_out');
+    expect(storedExecution?.timedOutAt).not.toBeNull();
+  });
+
+  it('emits a run-terminated outbox event with the failed status', async () => {
+    const job = await jobFactory.create({}, {transient: {status: 'running'}});
+
+    const run = await failWorkflowRunAsTimedOut({runAttemptId: job.workflowRunAttemptId});
+
+    const terminated = await db()
+      .select()
+      .from(workflowsOutbox)
+      .where(eq(workflowsOutbox.eventType, WORKFLOWS_WORKFLOW_RUN_TERMINATED));
+    const forRun = terminated.filter(
+      (row) => (row.payload as Record<string, unknown>).workflowRunId === run.id,
+    );
+    expect(forRun).toHaveLength(1);
+    expect(forRun[0]?.payload).toMatchObject({workflowRunId: run.id, status: 'failed'});
+  });
+
+  it('leaves an already-resolved listener job untouched', async () => {
+    const job = await jobFactory.create({}, {transient: {status: 'succeeded'}});
+    await db()
+      .update(jobs)
+      .set({mode: 'listening', listenerStatus: 'resolved', resolutionReason: 'until'})
+      .where(eq(jobs.id, job.id));
+
+    await failWorkflowRunAsTimedOut({runAttemptId: job.workflowRunAttemptId});
+
+    const storedJob = await readJob(job.id);
+    expect(storedJob?.status).toBe('succeeded');
+    expect(storedJob?.resolutionReason).toBe('until');
+  });
+
+  it('is idempotent once the run is terminal', async () => {
+    const job = await jobFactory.create({}, {transient: {status: 'running'}});
+
+    await failWorkflowRunAsTimedOut({runAttemptId: job.workflowRunAttemptId});
+    const second = await failWorkflowRunAsTimedOut({runAttemptId: job.workflowRunAttemptId});
+
+    const terminated = await db()
+      .select()
+      .from(workflowsOutbox)
+      .where(eq(workflowsOutbox.eventType, WORKFLOWS_WORKFLOW_RUN_TERMINATED));
+    const forRun = terminated.filter(
+      (row) => (row.payload as Record<string, unknown>).workflowRunId === second.id,
+    );
+    expect(second.status).toBe('failed');
+    expect(forRun).toHaveLength(1);
+  });
+});

package/src/db/runner-lease-table.ts

@@ -0,0 +1,39 @@
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {integer, pgEnum, pgTableCreator, text, timestamp, uuid} from 'drizzle-orm/pg-core';
+
+const pgTable = pgTableCreator((name) => `runners_${name}`);
+
+export const runnerSessionScopeEnum = pgEnum('runners_runner_session_scope', ['workspace']);
+export const runnerSessionRegistrationTokenKindEnum = pgEnum(
+  'runners_runner_session_registration_token_kind',
+  ['manual', 'ephemeral'],
+);
+
+export const runnerSessions = pgTable('runner_sessions', {
+  id: uuidv7PrimaryKey(),
+  workspaceId: uuid('workspace_id').notNull(),
+  scope: runnerSessionScopeEnum('scope').notNull().default('workspace'),
+  registrationTokenId: uuid('registration_token_id').notNull(),
+  registrationTokenKind:
+    runnerSessionRegistrationTokenKindEnum('registration_token_kind').notNull(),
+  provisionerId: uuid('provisioner_id'),
+  provisionedRunnerId: text('provisioned_runner_id'),
+  labels: text('labels').array().notNull(),
+  maxClaims: integer('max_claims'),
+  claimsUsed: integer('claims_used').notNull().default(0),
+  createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+  updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+});
+
+export const runningJobExecutions = pgTable('running_jobs', {
+  id: uuidv7PrimaryKey(),
+  workspaceId: uuid('workspace_id').notNull(),
+  workflowRunId: uuid('workflow_run_id').notNull(),
+  workflowRunAttemptId: uuid('workflow_run_attempt_id').notNull(),
+  jobId: uuid('job_id').notNull(),
+  jobExecutionId: uuid('job_execution_id').notNull(),
+  projectId: uuid('project_id').notNull(),
+  runnerSessionId: uuid('runner_session_id').notNull(),
+  requiredLabels: text('required_labels').array().notNull(),
+  runnerLabels: text('runner_labels').array().notNull(),
+});

package/src/db/schema/common.ts

@@ -0,0 +1,3 @@
+import {pgTableCreator} from 'drizzle-orm/pg-core';
+
+export const pgTable = pgTableCreator((name) => `workflows_${name}`);

package/src/db/schema/job-executions.ts

@@ -0,0 +1,85 @@
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {sql} from 'drizzle-orm';
+import {
+  index,
+  integer,
+  jsonb,
+  pgEnum,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from 'drizzle-orm/pg-core';
+import {toJobStatusReason} from '#core/entities/job.js';
+import type {JobExecution, WorkflowExecutionEvent} from '#core/entities/job-execution.js';
+import type {PersistedEvaluationTraceEntry} from '#core/entities/step.js';
+import {pgTable} from './common.js';
+import {jobStatusReasonEnum, jobs} from './jobs.js';
+
+export const jobExecutionStatusEnum = pgEnum('workflows_job_execution_status', [
+  'pending',
+  'running',
+  'succeeded',
+  'failed',
+  'cancelled',
+]);
+
+export const jobExecutions = pgTable(
+  'job_executions',
+  {
+    id: uuidv7PrimaryKey(),
+    jobId: uuid('job_id')
+      .notNull()
+      .references(() => jobs.id, {onDelete: 'cascade'}),
+    sequence: integer('sequence').notNull(),
+    name: text('name').notNull(),
+    runner: jsonb('runner').$type<string[]>(),
+    status: jobExecutionStatusEnum('status').notNull().default('pending'),
+    statusReason: jobStatusReasonEnum('status_reason'),
+    triggerEvents: jsonb('trigger_events').notNull().default([]).$type<WorkflowExecutionEvent[]>(),
+    outputs: jsonb('outputs').$type<Record<string, unknown> | null>(),
+    evaluationTrace: jsonb('evaluation_trace').$type<readonly PersistedEvaluationTraceEntry[]>(),
+    version: integer('version').notNull().default(1),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+    queuedAt: timestamp('queued_at', {withTimezone: true}),
+    startedAt: timestamp('started_at', {withTimezone: true}),
+    finishedAt: timestamp('finished_at', {withTimezone: true}),
+    timedOutAt: timestamp('timed_out_at', {withTimezone: true}),
+  },
+  (table) => [
+    index('workflows_job_executions_job_id_idx').on(table.jobId),
+    // Partial index backing the running-executions depth gauge, which counts on
+    // every Prometheus scrape. Indexes only active rows so the count stays cheap
+    // as the historical table grows.
+    index('workflows_job_executions_running_idx')
+      .on(table.status)
+      .where(sql`${table.status} = 'running'`),
+    uniqueIndex('workflows_job_executions_job_sequence_uq').on(table.jobId, table.sequence),
+  ],
+);
+
+export type JobExecutionDb = typeof jobExecutions.$inferSelect;
+export type JobExecutionCreateDb = typeof jobExecutions.$inferInsert;
+
+export function toJobExecution(row: JobExecutionDb): JobExecution {
+  return {
+    id: row.id,
+    jobId: row.jobId,
+    sequence: row.sequence,
+    name: row.name,
+    runner: row.runner as string[] | null,
+    status: row.status,
+    statusReason: toJobStatusReason(row.statusReason),
+    triggerEvents: row.triggerEvents,
+    outputs: row.outputs,
+    evaluationTrace: row.evaluationTrace ?? null,
+    version: row.version,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+    queuedAt: row.queuedAt,
+    startedAt: row.startedAt,
+    finishedAt: row.finishedAt,
+    timedOutAt: row.timedOutAt,
+  };
+}

package/src/db/schema/job-listener-events.ts

@@ -0,0 +1,58 @@
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {index, jsonb, pgEnum, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import type {JobListenerEvent} from '#core/entities/job-listener-event.js';
+import {pgTable} from './common.js';
+import {jobExecutions} from './job-executions.js';
+import {jobs} from './jobs.js';
+
+export const jobListenerEventDispositionEnum = pgEnum('workflows_job_listener_event_disposition', [
+  'fire',
+  'resolve',
+]);
+
+export const jobListenerEvents = pgTable(
+  'job_listener_events',
+  {
+    id: uuidv7PrimaryKey(),
+    jobId: uuid('job_id')
+      .notNull()
+      .references(() => jobs.id, {onDelete: 'cascade'}),
+    disposition: jobListenerEventDispositionEnum('disposition').notNull(),
+    eventRef: text('event_ref').notNull(),
+    deliveryId: text('delivery_id').notNull(),
+    source: text('source').notNull(),
+    event: text('event').notNull(),
+    payload: jsonb('payload').notNull(),
+    receivedAt: timestamp('received_at', {withTimezone: true}).notNull(),
+    consumedByExecutionId: uuid('consumed_by_execution_id').references(() => jobExecutions.id, {
+      onDelete: 'set null',
+    }),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('workflows_job_listener_events_job_event_ref_unique').on(
+      table.jobId,
+      table.eventRef,
+    ),
+    index('workflows_job_listener_events_job_received_idx').on(table.jobId, table.receivedAt),
+  ],
+);
+
+export type JobListenerEventDb = typeof jobListenerEvents.$inferSelect;
+export type JobListenerEventCreateDb = typeof jobListenerEvents.$inferInsert;
+
+export function toJobListenerEvent(row: JobListenerEventDb): JobListenerEvent {
+  return {
+    id: row.id,
+    jobId: row.jobId,
+    disposition: row.disposition,
+    eventRef: row.eventRef,
+    deliveryId: row.deliveryId,
+    source: row.source,
+    event: row.event,
+    payload: row.payload,
+    receivedAt: row.receivedAt,
+    consumedByExecutionId: row.consumedByExecutionId,
+    createdAt: row.createdAt,
+  };
+}

package/src/db/schema/jobs.ts

@@ -0,0 +1,136 @@
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {sql} from 'drizzle-orm';
+import {
+  bigint,
+  boolean,
+  index,
+  integer,
+  jsonb,
+  pgEnum,
+  text,
+  timestamp,
+  uuid,
+} from 'drizzle-orm/pg-core';
+import {
+  JOB_STATUS_REASONS,
+  type Job,
+  type JobListeningTrigger,
+  toJobStatusReason,
+} from '#core/entities/job.js';
+import type {PersistedEvaluationTraceEntry} from '#core/entities/step.js';
+import {pgTable} from './common.js';
+import {workflowRunAttempts} from './workflow-run-attempts.js';
+
+export const jobStatusEnum = pgEnum('workflows_job_status', [
+  'pending',
+  'running',
+  'succeeded',
+  'failed',
+  'cancelled',
+  'skipped',
+]);
+
+export const jobStatusReasonEnum = pgEnum('workflows_job_status_reason', JOB_STATUS_REASONS);
+
+export const jobModeEnum = pgEnum('workflows_job_mode', ['one_shot', 'listening']);
+
+export const jobCheckoutContentsEnum = pgEnum('workflows_checkout_contents', ['read', 'write']);
+
+export const jobOnResolveEnum = pgEnum('workflows_job_on_resolve', ['finish', 'cancel']);
+
+export const listenerStatusEnum = pgEnum('workflows_listener_status', [
+  'inactive',
+  'listening',
+  'resolved',
+]);
+
+export const resolutionReasonEnum = pgEnum('workflows_resolution_reason', [
+  'until',
+  'timeout',
+  'max_executions',
+  'cancelled',
+]);
+
+export const jobs = pgTable(
+  'jobs',
+  {
+    id: uuidv7PrimaryKey(),
+    workflowRunAttemptId: uuid('workflow_run_attempt_id')
+      .notNull()
+      .references(() => workflowRunAttempts.id, {onDelete: 'cascade'}),
+    key: text('key').notNull(),
+    mode: jobModeEnum('mode').notNull().default('one_shot'),
+    name: text('name'),
+    status: jobStatusEnum('status').notNull().default('pending'),
+    statusReason: jobStatusReasonEnum('status_reason'),
+    carriedOver: boolean('carried_over').notNull().default(false),
+    checkoutPersistCredentials: boolean('checkout_persist_credentials').notNull(),
+    checkoutPermissionsContents: jobCheckoutContentsEnum('checkout_permissions_contents').notNull(),
+    success: text('success'),
+    evaluationTrace: jsonb('evaluation_trace').$type<readonly PersistedEvaluationTraceEntry[]>(),
+    executionTimeoutMs: integer('execution_timeout_ms'),
+    listeningTimeoutMs: bigint('listening_timeout_ms', {mode: 'number'}),
+    maxExecutions: integer('max_executions'),
+    onResolve: jobOnResolveEnum('on_resolve'),
+    batchDebounceMs: integer('batch_debounce_ms'),
+    batchMaxSize: integer('batch_max_size'),
+    batchMaxWaitMs: integer('batch_max_wait_ms'),
+    listenerStatus: listenerStatusEnum('listener_status').notNull().default('inactive'),
+    resolutionReason: resolutionReasonEnum('resolution_reason'),
+    listeningOn: jsonb('listening_on').$type<JobListeningTrigger[]>(),
+    listeningUntil: jsonb('listening_until').$type<JobListeningTrigger[]>(),
+    outputs: jsonb('outputs').$type<Record<string, unknown> | null>(),
+    dependencies: jsonb('dependencies').notNull().$type<string[]>(),
+    runner: jsonb('runner').$type<string[]>(),
+    position: integer('position').notNull(),
+    version: integer('version').notNull().default(1),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    index('workflows_jobs_workflow_run_attempt_id_idx').on(table.workflowRunAttemptId),
+    index('workflows_jobs_active_listeners_idx')
+      .on(table.listenerStatus)
+      .where(sql`${table.listenerStatus} = 'listening'`),
+  ],
+);
+
+export type JobDb = typeof jobs.$inferSelect;
+export type JobCreateDb = typeof jobs.$inferInsert;
+
+export function toJob(row: JobDb): Job {
+  return {
+    id: row.id,
+    workflowRunAttemptId: row.workflowRunAttemptId,
+    key: row.key,
+    name: row.name,
+    mode: row.mode,
+    status: row.status,
+    statusReason: toJobStatusReason(row.statusReason),
+    carriedOver: row.carriedOver,
+    checkout: {
+      permissions: {contents: row.checkoutPermissionsContents},
+      persistCredentials: row.checkoutPersistCredentials,
+    },
+    success: row.success,
+    evaluationTrace: row.evaluationTrace ?? null,
+    executionTimeoutMs: row.executionTimeoutMs,
+    listeningTimeoutMs: row.listeningTimeoutMs,
+    maxExecutions: row.maxExecutions,
+    onResolve: row.onResolve,
+    batchDebounceMs: row.batchDebounceMs,
+    batchMaxSize: row.batchMaxSize,
+    batchMaxWaitMs: row.batchMaxWaitMs,
+    listenerStatus: row.listenerStatus,
+    resolutionReason: row.resolutionReason,
+    listeningOn: row.listeningOn,
+    listeningUntil: row.listeningUntil,
+    outputs: row.outputs,
+    dependencies: row.dependencies as string[],
+    runner: row.runner as string[] | null,
+    position: row.position,
+    version: row.version,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}

package/src/db/schema/outbox.ts

@@ -0,0 +1,4 @@
+import {createOutboxTable} from '@shipfox/node-outbox';
+import {pgTable} from './common.js';
+
+export const workflowsOutbox = createOutboxTable(pgTable);

package/src/db/schema/step-attempts.ts

@@ -0,0 +1,99 @@
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {sql} from 'drizzle-orm';
+import {
+  check,
+  foreignKey,
+  integer,
+  jsonb,
+  text,
+  timestamp,
+  unique,
+  uuid,
+} from 'drizzle-orm/pg-core';
+import type {
+  PersistedEvaluationTraceEntry,
+  StepAttempt,
+  StepAttemptLogOutcome,
+  StepAttemptStatus,
+} from '#core/entities/step.js';
+import {pgTable} from './common.js';
+import {stepStatusEnum, steps} from './steps.js';
+
+// Append-only execution history. One row per dispatched attempt of a step,
+// inserted `running` at dispatch and finalized terminal at report. `steps` holds
+// the fast current projection; this table is the audit trail and — via the
+// unique (step_id, attempt) constraint — the idempotency anchor.
+export const stepAttempts = pgTable(
+  'step_attempts',
+  {
+    id: uuidv7PrimaryKey(),
+    stepId: uuid('step_id')
+      .notNull()
+      .references(() => steps.id, {onDelete: 'cascade'}),
+    jobExecutionId: uuid('job_execution_id').notNull(),
+    attempt: integer('attempt').notNull(),
+    executionOrder: integer('execution_order').notNull(),
+    // Reuses the step status enum, but a row is created only once dispatched, so
+    // it is never 'pending'.
+    status: stepStatusEnum('status').notNull(),
+    config: jsonb('config').$type<Record<string, unknown>>(),
+    evaluationTrace: jsonb('evaluation_trace').$type<readonly PersistedEvaluationTraceEntry[]>(),
+    output: jsonb('output').$type<Record<string, unknown>>(),
+    response: text('response'),
+    error: jsonb('error').$type<Record<string, unknown>>(),
+    exitCode: integer('exit_code'),
+    logOutcome: text('log_outcome').$type<StepAttemptLogOutcome>(),
+    gateResult: jsonb('gate_result').$type<Record<string, unknown>>(),
+    restartFeedback: text('restart_feedback'),
+    startedAt: timestamp('started_at', {withTimezone: true}).notNull().defaultNow(),
+    finishedAt: timestamp('finished_at', {withTimezone: true}),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    unique('workflows_step_attempts_step_id_attempt_uq').on(table.stepId, table.attempt),
+    unique('workflows_step_attempts_job_execution_id_execution_order_uq').on(
+      table.jobExecutionId,
+      table.executionOrder,
+    ),
+    foreignKey({
+      name: 'workflows_step_attempts_step_id_job_execution_id_workflows_steps_fk',
+      columns: [table.stepId, table.jobExecutionId],
+      foreignColumns: [steps.id, steps.jobExecutionId],
+    }).onDelete('cascade'),
+    check('workflows_step_attempts_attempt_positive_ck', sql`${table.attempt} > 0`),
+    check('workflows_step_attempts_execution_order_positive_ck', sql`${table.executionOrder} > 0`),
+    check(
+      'workflows_step_attempts_status_dispatched_ck',
+      sql`${table.status} NOT IN ('pending', 'skipped')`,
+    ),
+    check(
+      'workflows_step_attempts_log_outcome_ck',
+      sql`${table.logOutcome} IS NULL OR ${table.logOutcome} IN ('drained', 'abandoned')`,
+    ),
+  ],
+);
+
+export type StepAttemptDb = typeof stepAttempts.$inferSelect;
+export type StepAttemptCreateDb = typeof stepAttempts.$inferInsert;
+
+export function toStepAttempt(row: StepAttemptDb): StepAttempt {
+  return {
+    id: row.id,
+    stepId: row.stepId,
+    attempt: row.attempt,
+    executionOrder: row.executionOrder,
+    status: row.status as StepAttemptStatus,
+    config: (row.config as Record<string, unknown>) ?? null,
+    evaluationTrace: row.evaluationTrace ?? null,
+    output: (row.output as Record<string, unknown>) ?? null,
+    response: row.response ?? null,
+    error: (row.error as Record<string, unknown>) ?? null,
+    exitCode: row.exitCode ?? null,
+    logOutcome: row.logOutcome ?? null,
+    gateResult: (row.gateResult as Record<string, unknown>) ?? null,
+    restartFeedback: row.restartFeedback ?? null,
+    startedAt: row.startedAt,
+    finishedAt: row.finishedAt ?? null,
+    createdAt: row.createdAt,
+  };
+}

package/src/db/schema/steps.ts

@@ -0,0 +1,99 @@
+import type {WorkflowExpression} from '@shipfox/expression';
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {sql} from 'drizzle-orm';
+import {
+  check,
+  foreignKey,
+  index,
+  integer,
+  jsonb,
+  pgEnum,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from 'drizzle-orm/pg-core';
+import {
+  type PersistedEvaluationTraceEntry,
+  STEP_STATUS_REASONS,
+  type Step,
+  type StepConfigDispatchPlan,
+  toStepStatusReason,
+} from '#core/entities/step.js';
+import {pgTable} from './common.js';
+import {jobExecutions} from './job-executions.js';
+
+export const stepStatusEnum = pgEnum('workflows_step_status', [
+  'pending',
+  'running',
+  'succeeded',
+  'failed',
+  'cancelled',
+  'skipped',
+]);
+
+export const stepStatusReasonEnum = pgEnum('workflows_step_status_reason', STEP_STATUS_REASONS);
+
+export const steps = pgTable(
+  'steps',
+  {
+    id: uuidv7PrimaryKey(),
+    jobExecutionId: uuid('job_execution_id').notNull(),
+    key: text('key'),
+    name: text('name').notNull(),
+    sourceLocation: jsonb('source_location').$type<Step['sourceLocation']>(),
+    status: stepStatusEnum('status').notNull().default('pending'),
+    statusReason: stepStatusReasonEnum('status_reason'),
+    evaluationTrace: jsonb('evaluation_trace').$type<readonly PersistedEvaluationTraceEntry[]>(),
+    type: text('type').notNull(),
+    config: jsonb('config').notNull().$type<Record<string, unknown>>(),
+    condition: jsonb('condition').$type<WorkflowExpression>(),
+    configPlan: jsonb('config_plan').$type<StepConfigDispatchPlan>(),
+    authoredConfig: jsonb('authored_config').$type<Record<string, unknown>>(),
+    error: jsonb('error').$type<Record<string, unknown>>(),
+    position: integer('position').notNull(),
+    version: integer('version').notNull().default(1),
+    // Execution-attempt identity, distinct from the optimistic `version` counter.
+    // Starts at 1 and is bumped only on durable rewind.
+    currentAttempt: integer('current_attempt').notNull().default(1),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    index('workflows_steps_job_execution_id_idx').on(table.jobExecutionId),
+    uniqueIndex('workflows_steps_id_job_execution_id_uq').on(table.id, table.jobExecutionId),
+    check('workflows_steps_current_attempt_positive_ck', sql`${table.currentAttempt} > 0`),
+    foreignKey({
+      name: 'workflows_steps_job_execution_id_workflows_job_executions_id_fk',
+      columns: [table.jobExecutionId],
+      foreignColumns: [jobExecutions.id],
+    }).onDelete('cascade'),
+  ],
+);
+
+export type StepDb = typeof steps.$inferSelect;
+export type StepCreateDb = typeof steps.$inferInsert;
+
+export function toStep(row: StepDb): Step {
+  return {
+    id: row.id,
+    jobExecutionId: row.jobExecutionId,
+    key: row.key,
+    name: row.name,
+    sourceLocation: row.sourceLocation ?? null,
+    status: row.status,
+    statusReason: toStepStatusReason(row.statusReason),
+    evaluationTrace: row.evaluationTrace ?? null,
+    type: row.type,
+    config: row.config as Record<string, unknown>,
+    condition: (row.condition as WorkflowExpression) ?? null,
+    configPlan: row.configPlan ?? null,
+    authoredConfig: (row.authoredConfig as Record<string, unknown>) ?? null,
+    error: (row.error as Record<string, unknown>) ?? null,
+    position: row.position,
+    version: row.version,
+    currentAttempt: row.currentAttempt,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}