@pattern-stack/codegen 0.4.1 → 0.4.3

package/runtime/subsystems/jobs/job-orchestrator.protocol.ts

@@ -0,0 +1,179 @@
+/**
+ * IJobOrchestrator — the primary port for the job orchestration domain
+ * (ADR-022, JOB-2).
+ *
+ * Consumers (use cases, event subscribers) inject this via
+ * `@Inject(JOB_ORCHESTRATOR)` and call `start` / `cancel` / `replay`.
+ * Concrete backends (JOB-3 Drizzle, JOB-4 Memory) satisfy this contract.
+ *
+ * Single-layer architecture reminder: there is no `IJobQueue` executor port.
+ * The orchestrator writes `job_run` rows directly; the `JobWorker` of JOB-3
+ * polls `job_run` via `SELECT ... FOR UPDATE SKIP LOCKED`.
+ */
+import type { JobRunRow } from './job-orchestration.schema';
+import type { JobHandlerMeta, ParentClosePolicy } from './job-handler.base';
+
+/**
+ * Public return type for orchestrator reads. Re-exported as `JobRun` so
+ * protocols and consumer code don't import the raw Drizzle row name.
+ */
+export type JobRun = JobRunRow;
+
+export interface StartOptions {
+  /**
+   * Optional scope attachment. `listForScope` queries use this pair; the
+   * column is free-text (no CHECK constraint) — type safety for `entityType`
+   * lives at the TS layer via JOB-7's generated `ScopeEntityType` union.
+   */
+  scope?: { entityType: string; entityId: string };
+
+  /** Overrides the pool declared in `@JobHandler({ pool })` metadata. */
+  pool?: string;
+
+  /** Schedule the run. When omitted, run as soon as the worker claims it. */
+  runAt?: Date;
+
+  /** 0 = default; higher values claimed first by `ORDER BY priority DESC`. */
+  priority?: number;
+
+  /** Free-form routing/audit tags. Persisted on `job_run.tags`. */
+  tags?: Record<string, string>;
+
+  /** Must align with `triggerSourceEnum` values landed in JOB-1. */
+  triggerSource?: 'manual' | 'schedule' | 'event' | 'parent';
+
+  /** Optional reference to the triggering event, schedule, etc. */
+  triggerRef?: string;
+
+  /**
+   * What happens to this run's children if this run reaches a terminal
+   * state. Stored on the child at spawn time; see `ParentClosePolicy`.
+   */
+  parentClosePolicy?: ParentClosePolicy;
+
+  /** Internal — set by `ctx.spawnChild`. User code should not pass this. */
+  parentRunId?: string;
+
+  /**
+   * Multi-tenancy opt-in (JOB-8). When `JobsDomainModule` is configured
+   * with `multiTenant: true`, this field is required:
+   *   - `string` — tenant the run belongs to (written to `job_run.tenant_id`).
+   *   - `null`   — cross-tenant background work; row persisted with NULL.
+   *   - `undefined` — throws `MissingTenantIdError` at the backend.
+   * When `multiTenant: false`, the field is ignored and the column is
+   * always written as `NULL`.
+   */
+  tenantId?: string | null;
+}
+
+export interface CancelOptions {
+  /**
+   * Conceptually defaults to `true` for root cancellation — cascading via
+   * `root_run_id` is the expected behaviour when an operator cancels a
+   * run. Backends in JOB-3/JOB-4 implement the default; callers passing
+   * `false` opt into "cancel only this node, leave descendants".
+   */
+  cascade?: boolean;
+  reason?: string;
+
+  /**
+   * Multi-tenancy gate (JOB-8). When `multiTenant: true`, the backend
+   * additionally filters `WHERE tenant_id = :tenantId` — cancelling a run
+   * that belongs to a different tenant is a **no-op** (not an error), so
+   * cross-tenant cancellation attempts are silent rather than leaking
+   * existence information. `undefined` throws `MissingTenantIdError`;
+   * explicit `null` matches `tenant_id IS NULL` rows.
+   */
+  tenantId?: string | null;
+}
+
+/**
+ * Boot-time upsert payload — one entry per registered `@JobHandler` class.
+ * Constructed by `JobWorkerModule.onModuleInit` from `HandlerRegistry.getAll()`
+ * and handed to the orchestrator so each backend can persist `job` definitions
+ * in whatever way it stores them (Drizzle: `ON CONFLICT (type) DO UPDATE`
+ * gated by metadata content; memory: populate `MemoryJobStore.jobs`).
+ */
+export interface JobUpsertEntry {
+  type: string;
+  meta: JobHandlerMeta<unknown>;
+  /**
+   * Handler class constructor — the memory backend keeps a reference for
+   * `tick()` execution. Drizzle backend ignores this (worker resolves the
+   * class via `JOB_HANDLER_REGISTRY` at claim time).
+   */
+  handlerClass: new (...args: unknown[]) => unknown;
+}
+
+/**
+ * Pool definition surface as the orchestrator needs it for boot-time row
+ * materialisation. Defined locally here (not imported from
+ * `pool-config.loader.ts`) so the protocol layer keeps zero dependencies on
+ * runtime config wiring — the loader's `PoolDefinition` is structurally
+ * compatible.
+ */
+export interface JobPoolDef {
+  queue: string;
+  concurrency: number;
+  reserved: boolean;
+  description?: string;
+}
+
+export interface IJobOrchestrator {
+  /**
+   * Create a `pending` `job_run` row and return it. Does NOT block waiting
+   * for the worker to pick the run up; consumers that need completion
+   * semantics should subscribe to the emitted completion event.
+   *
+   * **Optional `tx` last-arg** (added 2026-04-22 for ADR-023 BRIDGE-7):
+   * pass an in-flight Drizzle transaction to thread the row insert + any
+   * dedupe/collision lookups onto an existing tx. Used by
+   * `EventFlowService.publishAndStart` to bundle the outbox insert,
+   * eager `job_run`, and `bridge_delivery` Case-B pre-write into one
+   * atomic transaction. Memory backend ignores the parameter (its
+   * "transaction" is a process-wide mutex). Drizzle backend uses the
+   * standard `tx ?? this.db` pattern.
+   */
+  start(
+    type: string,
+    input: unknown,
+    opts?: StartOptions,
+    tx?: import('../events/event-bus.protocol').DrizzleTransaction,
+  ): Promise<JobRun>;
+
+  /**
+   * Cancel a run (and, by default, its entire root-run subtree). Idempotent
+   * — cancelling an already-terminal run is a no-op.
+   */
+  cancel(runId: string, opts?: CancelOptions): Promise<void>;
+
+  /**
+   * Re-run from the policy declared in `@JobHandler({ replayFrom })`.
+   * Returns the new `job_run` row (replay always spawns a fresh row —
+   * the original is preserved for audit).
+   */
+  replay(runId: string): Promise<JobRun>;
+
+  /**
+   * Boot-time materialisation of `job` definitions from `@JobHandler`
+   * metadata. Called once per process by `JobWorkerModule.onModuleInit`.
+   *
+   * Drizzle backend: hash-gated `INSERT … ON CONFLICT (type) DO UPDATE …
+   * WHERE` (Q3 resolution 2026-04-19). The `UPDATE` branch executes only
+   * when one of the persisted metadata fields differs from the incoming
+   * payload; `version` bumps only on a real change; concurrent boots with
+   * identical content are idempotent no-ops.
+   *
+   * Memory backend: populates `MemoryJobStore.jobs` and the in-process
+   * handler-class registry consumed by `MemoryJobOrchestrator.tick`.
+   *
+   * Returns the orphaned types — types present in DB but absent from
+   * `entries`. The caller (boot validator) decides whether to throw or
+   * warn. Memory backend always returns `[]` (Q4 resolution 2026-04-19 —
+   * validator skipped in memory mode).
+   */
+  upsertJobRows(
+    entries: JobUpsertEntry[],
+    poolConfig: ReadonlyMap<string, JobPoolDef>,
+  ): Promise<{ orphaned: string[] }>;
+}

package/runtime/subsystems/jobs/job-run-service.drizzle-backend.ts

@@ -0,0 +1,171 @@
+/**
+ * DrizzleJobRunService — scope-oriented reads and bulk operations against
+ * `job_run` (ADR-022, JOB-3).
+ *
+ * Separate from the orchestrator because the access pattern differs: this
+ * service scans by `(scope_entity_type, scope_entity_id)` via
+ * `idx_job_run_scope`, whereas orchestrator mutates individual runs by id.
+ */
+import { Inject, Injectable } from '@nestjs/common';
+import { and, asc, desc, eq, inArray, isNull } from 'drizzle-orm';
+import type { DrizzleClient } from '../../types/drizzle';
+import { DRIZZLE } from '../../constants/tokens';
+import { jobRuns, type JobRunRow } from './job-orchestration.schema';
+import type { JobRun } from './job-orchestrator.protocol';
+import type {
+  IJobRunService,
+  ListForScopeOptions,
+  CancelForScopeOptions,
+  RescheduleForScopeOptions,
+} from './job-run-service.protocol';
+import type { IJobOrchestrator } from './job-orchestrator.protocol';
+import { JOB_ORCHESTRATOR, JOBS_MULTI_TENANT } from './jobs-domain.tokens';
+import { MissingTenantIdError } from './jobs-errors';
+
+const NON_TERMINAL_STATUSES: JobRunRow['status'][] = [
+  'pending',
+  'running',
+  'waiting',
+];
+
+@Injectable()
+export class DrizzleJobRunService implements IJobRunService {
+  constructor(
+    @Inject(DRIZZLE) private readonly db: DrizzleClient,
+    @Inject(JOB_ORCHESTRATOR) private readonly orchestrator: IJobOrchestrator,
+    @Inject(JOBS_MULTI_TENANT) private readonly multiTenant: boolean,
+  ) {}
+
+  /**
+   * JOB-8 — produce the tenant WHERE fragment (or `null` to opt out).
+   * Returns `null` when multi-tenancy is off (caller skips the predicate).
+   * Throws `MissingTenantIdError` when on + `undefined`.
+   * When on + explicit `null`, filters `tenant_id IS NULL`.
+   */
+  private tenantCondition(
+    method: string,
+    tenantId: string | null | undefined,
+  ) {
+    if (!this.multiTenant) return null;
+    if (tenantId === undefined) throw new MissingTenantIdError(method);
+    return tenantId === null
+      ? isNull(jobRuns.tenantId)
+      : eq(jobRuns.tenantId, tenantId);
+  }
+
+  async listForScope(
+    entityType: string,
+    entityId: string,
+    opts: ListForScopeOptions = {},
+  ): Promise<JobRun[]> {
+    const conditions = [
+      eq(jobRuns.scopeEntityType, entityType),
+      eq(jobRuns.scopeEntityId, entityId),
+    ];
+    const tenantCond = this.tenantCondition('listForScope', opts.tenantId);
+    if (tenantCond) conditions.push(tenantCond);
+    if (opts.status) {
+      if (Array.isArray(opts.status)) {
+        conditions.push(inArray(jobRuns.status, opts.status));
+      } else {
+        conditions.push(eq(jobRuns.status, opts.status));
+      }
+    }
+    if (opts.jobType) {
+      conditions.push(eq(jobRuns.jobType, opts.jobType));
+    }
+
+    const orderCol = (() => {
+      switch (opts.orderBy) {
+        case 'created_at asc':
+          return asc(jobRuns.createdAt);
+        case 'run_at desc':
+          return desc(jobRuns.runAt);
+        case 'run_at asc':
+          return asc(jobRuns.runAt);
+        case 'created_at desc':
+        default:
+          return desc(jobRuns.createdAt);
+      }
+    })();
+
+    let q = this.db
+      .select()
+      .from(jobRuns)
+      .where(and(...conditions))
+      .orderBy(orderCol)
+      .$dynamic();
+
+    if (typeof opts.limit === 'number') {
+      q = q.limit(opts.limit);
+    }
+    if (typeof opts.offset === 'number') {
+      q = q.offset(opts.offset);
+    }
+
+    const rows = await q;
+    return rows as JobRun[];
+  }
+
+  async cancelForScope(
+    entityType: string,
+    entityId: string,
+    opts: CancelForScopeOptions = {},
+  ): Promise<void> {
+    const tenantCond = this.tenantCondition('cancelForScope', opts.tenantId);
+    const conditions = [
+      eq(jobRuns.scopeEntityType, entityType),
+      eq(jobRuns.scopeEntityId, entityId),
+      inArray(jobRuns.status, NON_TERMINAL_STATUSES),
+    ];
+    if (tenantCond) conditions.push(tenantCond);
+
+    const rows = await this.db
+      .select({ id: jobRuns.id })
+      .from(jobRuns)
+      .where(and(...conditions));
+
+    for (const { id } of rows) {
+      // Propagate the tenant gate into cascade-cancel. The scope query has
+      // already narrowed to this tenant; passing `tenantId` through keeps
+      // the orchestrator's per-row guard consistent under multi-tenant mode.
+      await this.orchestrator.cancel(id, {
+        cascade: true,
+        tenantId: opts.tenantId,
+      });
+    }
+  }
+
+  async rescheduleForScope(
+    entityType: string,
+    entityId: string,
+    newRunAt: Date,
+    opts: RescheduleForScopeOptions = {},
+  ): Promise<void> {
+    const tenantCond = this.tenantCondition('rescheduleForScope', opts.tenantId);
+    const conditions = [
+      eq(jobRuns.scopeEntityType, entityType),
+      eq(jobRuns.scopeEntityId, entityId),
+      eq(jobRuns.status, 'pending'),
+    ];
+    if (tenantCond) conditions.push(tenantCond);
+
+    await this.db
+      .update(jobRuns)
+      .set({ runAt: newRunAt, updatedAt: new Date() })
+      .where(and(...conditions));
+  }
+
+  /**
+   * Internal helper used by cascade paths (not on the public protocol).
+   * Exposed as a public method on the concrete class so infrastructure
+   * code (cascade tests, debug tools) can call it without a cast.
+   */
+  async findByRootRunId(rootRunId: string): Promise<JobRun[]> {
+    const rows = await this.db
+      .select()
+      .from(jobRuns)
+      .where(eq(jobRuns.rootRunId, rootRunId));
+    return rows as JobRun[];
+  }
+}

package/runtime/subsystems/jobs/job-run-service.memory-backend.ts

@@ -0,0 +1,165 @@
+/**
+ * MemoryJobRunService — scope-oriented queries and bulk ops over the
+ * in-memory run store (ADR-022, JOB-4).
+ *
+ * Mirrors `DrizzleJobRunService` but scans `MemoryJobStore.runs.values()`.
+ * Cancel delegates back to the orchestrator so cascade semantics stay in
+ * one place.
+ */
+import { Inject, Injectable } from '@nestjs/common';
+import type { JobRunRow } from './job-orchestration.schema';
+import type { JobRun } from './job-orchestrator.protocol';
+import type {
+  IJobRunService,
+  ListForScopeOptions,
+  CancelForScopeOptions,
+  RescheduleForScopeOptions,
+} from './job-run-service.protocol';
+import type { IJobOrchestrator } from './job-orchestrator.protocol';
+import { JOB_ORCHESTRATOR, JOBS_MULTI_TENANT } from './jobs-domain.tokens';
+import { MissingTenantIdError } from './jobs-errors';
+import { MemoryJobStore } from './memory-job-store';
+
+const NON_TERMINAL_STATUSES: JobRunRow['status'][] = [
+  'pending',
+  'running',
+  'waiting',
+];
+
+@Injectable()
+export class MemoryJobRunService implements IJobRunService {
+  constructor(
+    private readonly store: MemoryJobStore,
+    @Inject(JOB_ORCHESTRATOR) private readonly orchestrator: IJobOrchestrator,
+    @Inject(JOBS_MULTI_TENANT) private readonly multiTenant: boolean,
+  ) {}
+
+  /**
+   * JOB-8 — produce a per-row predicate for the tenant gate.
+   * Returns `null` when multi-tenancy is off (caller doesn't check).
+   * Throws when on + `undefined`; matches `tenant_id IS NULL` on explicit
+   * `null` to support cross-tenant background work.
+   */
+  private tenantPredicate(
+    method: string,
+    tenantId: string | null | undefined,
+  ): ((r: JobRunRow) => boolean) | null {
+    if (!this.multiTenant) return null;
+    if (tenantId === undefined) throw new MissingTenantIdError(method);
+    return (r) => r.tenantId === tenantId;
+  }
+
+  async listForScope(
+    entityType: string,
+    entityId: string,
+    opts: ListForScopeOptions = {},
+  ): Promise<JobRun[]> {
+    const statusFilter = opts.status
+      ? Array.isArray(opts.status)
+        ? new Set(opts.status)
+        : new Set([opts.status])
+      : null;
+    const tenantCheck = this.tenantPredicate('listForScope', opts.tenantId);
+
+    const rows: JobRunRow[] = [];
+    for (const r of this.store.runs.values()) {
+      if (r.scopeEntityType !== entityType) continue;
+      if (r.scopeEntityId !== entityId) continue;
+      if (statusFilter && !statusFilter.has(r.status)) continue;
+      if (opts.jobType && r.jobType !== opts.jobType) continue;
+      if (tenantCheck && !tenantCheck(r)) continue;
+      rows.push(r);
+    }
+
+    const orderBy = opts.orderBy ?? 'created_at desc';
+    rows.sort((a, b) => compareBy(a, b, orderBy));
+
+    const offset = opts.offset ?? 0;
+    const limit = opts.limit;
+    const sliced =
+      typeof limit === 'number' ? rows.slice(offset, offset + limit) : rows.slice(offset);
+    return sliced as JobRun[];
+  }
+
+  async cancelForScope(
+    entityType: string,
+    entityId: string,
+    opts: CancelForScopeOptions = {},
+  ): Promise<void> {
+    const tenantCheck = this.tenantPredicate('cancelForScope', opts.tenantId);
+
+    const ids: string[] = [];
+    for (const r of this.store.runs.values()) {
+      if (r.scopeEntityType !== entityType) continue;
+      if (r.scopeEntityId !== entityId) continue;
+      if (!NON_TERMINAL_STATUSES.includes(r.status)) continue;
+      if (tenantCheck && !tenantCheck(r)) continue;
+      ids.push(r.id);
+    }
+    for (const id of ids) {
+      // Propagate the tenant gate through the orchestrator's cancel so the
+      // internal per-row guard passes (no surprise MissingTenantIdError
+      // once the scope query has already narrowed to this tenant).
+      await this.orchestrator.cancel(id, {
+        cascade: true,
+        tenantId: opts.tenantId,
+      });
+    }
+  }
+
+  async rescheduleForScope(
+    entityType: string,
+    entityId: string,
+    newRunAt: Date,
+    opts: RescheduleForScopeOptions = {},
+  ): Promise<void> {
+    const tenantCheck = this.tenantPredicate('rescheduleForScope', opts.tenantId);
+    for (const r of this.store.runs.values()) {
+      if (r.scopeEntityType !== entityType) continue;
+      if (r.scopeEntityId !== entityId) continue;
+      if (r.status !== 'pending') continue;
+      if (tenantCheck && !tenantCheck(r)) continue;
+      this.store.runs.set(r.id, {
+        ...r,
+        runAt: newRunAt,
+        updatedAt: new Date(),
+      });
+    }
+  }
+
+  /**
+   * Direct lookup. Not on the protocol — concrete-class convenience for
+   * tests. Matches `DrizzleJobRunService.findByRootRunId` in spirit; both
+   * are debug / test helpers that sidestep the orchestrator.
+   */
+  findById(runId: string): JobRun | null {
+    return (this.store.runs.get(runId) ?? null) as JobRun | null;
+  }
+
+  /** Public counterpart to the Drizzle backend's `findByRootRunId` helper. */
+  findByRootRunId(rootRunId: string): JobRun[] {
+    const out: JobRunRow[] = [];
+    for (const r of this.store.runs.values()) {
+      if (r.rootRunId === rootRunId) out.push(r);
+    }
+    return out as JobRun[];
+  }
+}
+
+function compareBy(
+  a: JobRunRow,
+  b: JobRunRow,
+  order: Exclude<ListForScopeOptions['orderBy'], undefined>,
+): number {
+  switch (order) {
+    case 'created_at asc':
+      return a.createdAt.getTime() - b.createdAt.getTime();
+    case 'run_at desc':
+      return b.runAt.getTime() - a.runAt.getTime();
+    case 'run_at asc':
+      return a.runAt.getTime() - b.runAt.getTime();
+    case 'created_at desc':
+    default:
+      return b.createdAt.getTime() - a.createdAt.getTime();
+  }
+}

package/runtime/subsystems/jobs/job-run-service.protocol.ts

@@ -0,0 +1,79 @@
+/**
+ * IJobRunService — scope-oriented queries and bulk operations over
+ * `job_run` rows (ADR-022, JOB-2).
+ *
+ * This is a separate port from `IJobOrchestrator` because the access
+ * pattern is different: orchestrator mutates individual runs by id;
+ * run service scans by `(scope_entity_type, scope_entity_id)`.
+ */
+import type { JobRun } from './job-orchestrator.protocol';
+
+export interface ListForScopeOptions {
+  /**
+   * Single status or set. Widens to the full `JobRun['status']` union so
+   * callers can pass values straight from `jobRunStatusEnum`.
+   */
+  status?: JobRun['status'] | JobRun['status'][];
+  jobType?: string;
+  limit?: number;
+  offset?: number;
+  orderBy?:
+    | 'created_at desc'
+    | 'created_at asc'
+    | 'run_at desc'
+    | 'run_at asc';
+
+  /**
+   * Multi-tenancy gate (JOB-8). When `multiTenant: true`, the backend adds
+   * `AND tenant_id = :tenantId` to the scope query. `undefined` throws
+   * `MissingTenantIdError`; explicit `null` matches `tenant_id IS NULL`
+   * rows (cross-tenant background work).
+   */
+  tenantId?: string | null;
+}
+
+/**
+ * JOB-8 — scoped bulk ops take the same tenant gate as `listForScope`.
+ * Added in JOB-8; pre-JOB-8 callers passing nothing continue to compile.
+ */
+export interface CancelForScopeOptions {
+  tenantId?: string | null;
+}
+
+export interface RescheduleForScopeOptions {
+  tenantId?: string | null;
+}
+
+export interface IJobRunService {
+  /**
+   * Return runs attached to `(entityType, entityId)`. Backed by
+   * `idx_job_run_scope` for efficient reads.
+   */
+  listForScope(
+    entityType: string,
+    entityId: string,
+    opts?: ListForScopeOptions,
+  ): Promise<JobRun[]>;
+
+  /**
+   * Cancel every non-terminal run attached to `(entityType, entityId)`,
+   * cascading via `root_run_id`. Used e.g. when an Opportunity is closed
+   * and all its background work should stop.
+   */
+  cancelForScope(
+    entityType: string,
+    entityId: string,
+    opts?: CancelForScopeOptions,
+  ): Promise<void>;
+
+  /**
+   * Push `run_at` forward on every `pending` run attached to the scope.
+   * Useful for "pause this account's background work until tomorrow".
+   */
+  rescheduleForScope(
+    entityType: string,
+    entityId: string,
+    newRunAt: Date,
+    opts?: RescheduleForScopeOptions,
+  ): Promise<void>;
+}

package/runtime/subsystems/jobs/job-step-service.drizzle-backend.ts

@@ -0,0 +1,66 @@
+/**
+ * DrizzleJobStepService — upsert + lookup on `job_step` for replay-safe
+ * memoization (ADR-022, JOB-3).
+ *
+ * `recordStep` upserts on the `(job_run_id, step_id)` unique index — each
+ * step row is written as `running` first, then transitioned to a terminal
+ * state (`completed` / `failed` / `skipped`). `findStep` is the hot path
+ * that `ctx.step()` consults on every invocation; null on miss.
+ */
+import { Inject, Injectable } from '@nestjs/common';
+import { and, eq } from 'drizzle-orm';
+import type { DrizzleClient } from '../../types/drizzle';
+import { DRIZZLE } from '../../constants/tokens';
+import { jobSteps, type JobStepRow } from './job-orchestration.schema';
+import type {
+  IJobStepService,
+  JobStep,
+  RecordStepInput,
+} from './job-step-service.protocol';
+
+@Injectable()
+export class DrizzleJobStepService implements IJobStepService {
+  constructor(@Inject(DRIZZLE) private readonly db: DrizzleClient) {}
+
+  async recordStep(input: RecordStepInput): Promise<JobStep> {
+    const values = {
+      jobRunId: input.jobRunId,
+      stepId: input.stepId,
+      kind: input.kind,
+      seq: input.seq,
+      status: input.status,
+      input: (input.input ?? null) as Record<string, unknown> | null,
+      output: (input.output ?? null) as Record<string, unknown> | null,
+      error: input.error ?? null,
+      attempts: input.attempts ?? 0,
+      startedAt: input.startedAt ?? null,
+      finishedAt: input.finishedAt ?? null,
+    };
+
+    const [row] = await this.db
+      .insert(jobSteps)
+      .values(values)
+      .onConflictDoUpdate({
+        target: [jobSteps.jobRunId, jobSteps.stepId],
+        set: {
+          status: values.status,
+          output: values.output,
+          error: values.error,
+          finishedAt: values.finishedAt,
+          attempts: values.attempts,
+        },
+      })
+      .returning();
+
+    return row as JobStep;
+  }
+
+  async findStep(runId: string, stepId: string): Promise<JobStep | null> {
+    const [row] = await this.db
+      .select()
+      .from(jobSteps)
+      .where(and(eq(jobSteps.jobRunId, runId), eq(jobSteps.stepId, stepId)))
+      .limit(1);
+    return ((row as JobStepRow | undefined) ?? null) as JobStep | null;
+  }
+}