@pattern-stack/codegen 0.8.1 → 0.9.1

package/runtime/subsystems/jobs/index.ts

@@ -42,6 +42,9 @@ export type {
   RescheduleForScopeOptions,
   PoolStatusCount,
   JobRunFailure,
+  ListJobRunsQuery,
+  JobRunSummary,
+  JobRunPage,
 } from './job-run-service.protocol';
 
 // ─── JOB-2: step-service protocol ──────────────────────────────────────────
@@ -76,6 +79,24 @@ export type {
 export { DrizzleJobOrchestrator } from './job-orchestrator.drizzle-backend';
 export { DrizzleJobRunService } from './job-run-service.drizzle-backend';
 export { DrizzleJobStepService } from './job-step-service.drizzle-backend';
+
+// ─── BULLMQ-1: BullMQ backend (additive; opt-in via jobs.backend: bullmq) ──
+export {
+  BullMQJobOrchestrator,
+  sha1JobId,
+} from './job-orchestrator.bullmq-backend';
+export {
+  BullMQJobWorker,
+  type BullMQJobWorkerOptions,
+} from './job-worker.bullmq-backend';
+export {
+  BULLMQ_CONNECTION,
+  BULLMQ_RESOLVED_CONFIG,
+  resolveBullMqConfig,
+  resolvePoolQueueName,
+  type BullMqExtensionsConfig,
+  type BullMqResolvedConfig,
+} from './bullmq.config';
 export {
   JobWorker,
   JOB_WORKER_OPTIONS,
@@ -115,6 +136,7 @@ export {
 export {
   loadPoolConfig,
   allNonReservedPoolNames,
+  allPoolNames,
   FRAMEWORK_POOLS,
   RESERVED_POOL_NAMES,
   type PoolConfig,

package/runtime/subsystems/jobs/job-handler.base.ts

@@ -16,6 +16,7 @@
  */
 // TODO(logging-subsystem): swap to ILogger once ADR-028 lands
 import type { Logger } from '@nestjs/common';
+import type { EventOfType, EventTypeName } from '../events/generated/types';
 import type { JobRun } from './job-orchestrator.protocol';
 
 // ─── ParentClosePolicy ──────────────────────────────────────────────────────
@@ -60,6 +61,35 @@ export interface ScopeRef<TInput, TScope extends string = string> {
   from: (input: TInput) => string;
 }
 
+/**
+ * Bridge trigger authoring shape (BRIDGE-6 follow-up — BRIDGE-6 shipped the
+ * generator + runtime for `@JobHandler({ triggers })` but never added the
+ * authoring field to this type; the generator's tests scan source as strings,
+ * so a real decorator was never compiled and the gap went uncaught).
+ *
+ * Declared on `@JobHandler({ triggers })`; the codegen bridge-registry
+ * generator (`src/cli/shared/bridge-registry-generator.ts`) scans these from
+ * source and emits `bridge/generated/registry.ts`, validating each `event`
+ * against the generated `eventRegistry` at `gen-all`. The distributed union
+ * narrows `map`/`when` per `event`, so callbacks are typed against the event
+ * payload (ADR-023, "typed against PayloadOfType<T>").
+ *
+ * Typed against events' generated types — the same `import type` coupling the
+ * bridge already has (erased at runtime). `jobs` must NOT import `bridge`, so
+ * the post-gen `BridgeTriggerEntry` is deliberately not referenced here;
+ * `triggerId`/`jobType` are computed by the generator, not authored.
+ */
+export type JobTrigger<TInput> = {
+  [T in EventTypeName]: {
+    /** Event type that fires this trigger. Validated against `eventRegistry`. */
+    event: T;
+    /** Maps the event to the job input. Inlined verbatim into the registry. */
+    map: (event: EventOfType<T>) => TInput;
+    /** Optional guard; `false` → wrapper records `status='skipped'`. */
+    when?: (event: EventOfType<T>) => boolean;
+  };
+}[EventTypeName];
+
 export interface JobHandlerMeta<TInput> {
   pool?: string;
   scope?: ScopeRef<TInput>;
@@ -68,6 +98,12 @@ export interface JobHandlerMeta<TInput> {
   dedupe?: DedupePolicy<TInput>;
   timeoutMs?: number;
   replayFrom?: 'scratch' | 'last_step' | 'last_checkpoint';
+  /**
+   * Bridge triggers (ADR-023 Tier 3). Codegen scans these into `bridgeRegistry`;
+   * the framework `BridgeDeliveryHandler` starts this job per matched event.
+   * Absent for jobs started directly or via `IEventFlow.publishAndStart`.
+   */
+  triggers?: readonly JobTrigger<TInput>[];
 }
 
 // ─── Runtime option shapes ──────────────────────────────────────────────────

package/runtime/subsystems/jobs/job-orchestrator.bullmq-backend.ts

@@ -0,0 +1,381 @@
+/**
+ * BullMQJobOrchestrator — BullMQ-backed implementation of `IJobOrchestrator`
+ * (BULLMQ-1, ADR-022 §58 — the reserved "Phase 6+" backend, now built).
+ *
+ * Split-of-responsibility (spec §"Postgres + BullMQ coordination"):
+ *   - Postgres `job_run` stays the **domain source of truth** — scoping,
+ *     hierarchy (`parent_run_id`/`root_run_id`), dedupe/concurrency state,
+ *     `listForScope`. All of that is the Drizzle backend's job and is reused
+ *     verbatim by extending `DrizzleJobOrchestrator`.
+ *   - BullMQ owns the **claim/dispatch** half. `start` adds a job to the
+ *     pool's queue (or to a FlowProducer flow when parented); the BullMQ
+ *     `Worker` (see `job-worker.bullmq-backend.ts`) consumes it and runs the
+ *     handler through the existing `JobHandlerBase` path. `cancel` removes
+ *     the queued job; `replay` re-adds it after the shared DB reset.
+ *
+ * This is **additive**: the Drizzle backend, the core protocol, and app code
+ * are untouched. Consumers flip `jobs.backend: bullmq` with no code change —
+ * the same `IJobOrchestrator` surface is satisfied.
+ *
+ * `jobId` (spec §Gotcha 1): BullMQ treats `:` as a Redis key separator and
+ * consumers use `vendor:externalId`-shaped idempotency keys, so we derive the
+ * `jobId` as `sha1(idempotencyKey)` — colon-safe and stable (same logical key
+ * → same id → BullMQ-native dedup). When no dedupe key is configured we fall
+ * back to the `job_run.id` (a fresh UUID), which is already colon-safe.
+ */
+import { createHash } from 'node:crypto';
+import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
+import { eq } from 'drizzle-orm';
+// `bullmq` is an OPTIONAL peer dependency. Only TYPE imports here — types are
+// erased at compile time and never resolve `'bullmq'` at runtime, so a
+// `drizzle`-only consumer who didn't install bullmq can still load this file
+// (it is statically imported by `jobs-domain.module.ts`). The VALUE
+// constructors (`Queue`, `FlowProducer`) are loaded lazily via `await
+// import('bullmq')` in `loadBullMq()` — mirrors
+// `event-bus.redis-backend.ts:createRedisClient`. See BULLMQ-1 §Lazy import.
+import type { ConnectionOptions, FlowProducer, Queue } from 'bullmq';
+import type { DrizzleClient } from '../../types/drizzle';
+import type { DrizzleTransaction } from '../events/event-bus.protocol';
+import { DRIZZLE } from '../../constants/tokens';
+import { jobRuns, jobs, type JobDefinitionRow } from './job-orchestration.schema';
+import { DrizzleJobOrchestrator } from './job-orchestrator.drizzle-backend';
+import type {
+  CancelOptions,
+  JobRun,
+  StartOptions,
+} from './job-orchestrator.protocol';
+import { JOBS_MULTI_TENANT } from './jobs-domain.tokens';
+import {
+  BULLMQ_CONNECTION,
+  resolvePoolQueueName,
+  type BullMqResolvedConfig,
+  BULLMQ_RESOLVED_CONFIG,
+} from './bullmq.config';
+
+/**
+ * Derive a colon-safe, stable BullMQ `jobId` from a logical idempotency key.
+ *
+ * SHA-1 over the raw key. Collision analysis (spec §Gotcha 1, resolved during
+ * implementation): SHA-1's 160-bit space makes an accidental collision between
+ * two *distinct* logical keys astronomically unlikely at any realistic job
+ * volume (the birthday bound is ~2^80 keys before a 50% collision chance —
+ * orders of magnitude beyond any job throughput). SHA-1's cryptographic
+ * weakness is irrelevant here: there is no adversary forging idempotency keys,
+ * and even a forged collision only deduplicates two jobs that the caller chose
+ * to key identically. We therefore accept SHA-1 with no mitigation. The *same*
+ * logical key intentionally maps to the *same* jobId — that is the dedup
+ * mechanism, not a collision.
+ */
+export function sha1JobId(idempotencyKey: string): string {
+  return createHash('sha1').update(idempotencyKey).digest('hex');
+}
+
+// Constructor types for the lazily-loaded `bullmq` value exports. Typed via
+// `typeof` the type-only imports so the cached ctors stay strongly typed
+// without a runtime `import`.
+type QueueCtor = typeof import('bullmq').Queue;
+type FlowProducerCtor = typeof import('bullmq').FlowProducer;
+
+@Injectable()
+export class BullMQJobOrchestrator extends DrizzleJobOrchestrator {
+  // TODO(logging-subsystem): swap to ILogger once ADR-028 lands
+  private readonly bullLogger = new Logger(BullMQJobOrchestrator.name);
+
+  /** Lazily-opened `Queue` handles, one per pool. */
+  private readonly queues = new Map<string, Queue>();
+  /** Single FlowProducer for parent/child hierarchies. Lazily opened. */
+  private _flow: FlowProducer | null = null;
+
+  /**
+   * Cached `bullmq` value constructors, populated by `loadBullMq()` on first
+   * use (the `start`/`cancel`/`replay` entrypoints `await` it before touching
+   * a queue). Kept off the import graph so a `drizzle`-only consumer never
+   * resolves the optional `'bullmq'` package.
+   */
+  private QueueCtor: QueueCtor | null = null;
+  private FlowProducerCtor: FlowProducerCtor | null = null;
+  private bullMqLoad: Promise<void> | null = null;
+
+  /**
+   * Own reference to the Drizzle client. `DrizzleJobOrchestrator.db` is
+   * `private` (can't be redeclared even privately in a subclass), and the
+   * spec forbids touching that file — so the subclass keeps its own handle
+   * under a distinct name (same instance, passed through to `super`) for the
+   * cancel-cascade snapshot + definition/run loads below.
+   */
+  private readonly bullDb: DrizzleClient;
+
+  constructor(
+    @Inject(DRIZZLE) db: DrizzleClient,
+    @Inject(JOBS_MULTI_TENANT) multiTenant: boolean,
+    @Inject(BULLMQ_CONNECTION) private readonly connection: ConnectionOptions,
+    @Optional()
+    @Inject(BULLMQ_RESOLVED_CONFIG)
+    private readonly bullConfig: BullMqResolvedConfig | null = null,
+  ) {
+    super(db, multiTenant);
+    this.bullDb = db;
+  }
+
+  /**
+   * Lazily load the optional `bullmq` package and cache its value
+   * constructors. Idempotent (single in-flight promise). Throws a friendly,
+   * actionable error when the consumer selected `backend: 'bullmq'` but did
+   * not install the package — mirrors `createRedisClient` in the redis event
+   * backend. Must be `await`ed before any `queueFor`/`flow` access.
+   */
+  private async loadBullMq(): Promise<void> {
+    if (this.QueueCtor && this.FlowProducerCtor) return;
+    if (!this.bullMqLoad) {
+      this.bullMqLoad = (async () => {
+        try {
+          const mod = await import('bullmq');
+          this.QueueCtor = mod.Queue;
+          this.FlowProducerCtor = mod.FlowProducer;
+        } catch {
+          throw new Error(
+            'BullMQ backend requires the "bullmq" package. Install it with: npm install bullmq',
+          );
+        }
+      })();
+    }
+    await this.bullMqLoad;
+  }
+
+  /**
+   * Open (or reuse) the `Queue` for a pool. Synchronous — callers `await
+   * loadBullMq()` first so `QueueCtor` is populated.
+   */
+  private queueFor(pool: string): Queue {
+    if (!this.QueueCtor) {
+      throw new Error('BullMQJobOrchestrator: queueFor called before loadBullMq()');
+    }
+    const name = resolvePoolQueueName(pool, this.bullConfig);
+    let q = this.queues.get(name);
+    if (!q) {
+      q = new this.QueueCtor(name, { connection: this.connection });
+      this.queues.set(name, q);
+    }
+    return q;
+  }
+
+  private flow(): FlowProducer {
+    if (!this.FlowProducerCtor) {
+      throw new Error('BullMQJobOrchestrator: flow called before loadBullMq()');
+    }
+    if (!this._flow) {
+      this._flow = new this.FlowProducerCtor({ connection: this.connection });
+    }
+    return this._flow;
+  }
+
+  // ==========================================================================
+  // start — Postgres insert (super) + BullMQ dispatch
+  // ==========================================================================
+
+  override async start(
+    type: string,
+    input: unknown,
+    opts: StartOptions = {},
+    tx?: DrizzleTransaction,
+  ): Promise<JobRun> {
+    // (1) Postgres remains source of truth — the Drizzle backend handles the
+    //     job-definition lookup, dedupe short-circuit, concurrency collision,
+    //     parent/root resolution, and the `job_run` INSERT. If dedupe
+    //     short-circuited it returns the incumbent row whose dispatch already
+    //     happened on the original start; we must not enqueue again.
+    const run = await super.start(type, input, opts, tx);
+
+    // Dedupe returned an existing run (its createdAt predates this call) —
+    // BullMQ-native dedup already covered the dispatch. Skip re-enqueue.
+    // We detect this by checking the run was freshly created in THIS call:
+    // a brand-new run has status 'pending' and zero attempts AND its id is
+    // not yet known to BullMQ. The cheapest reliable signal is the dedupe
+    // path's contract: super.start returns the incumbent unchanged. Since we
+    // cannot distinguish purely from the row, we rely on `jobId` idempotency
+    // — re-adding with the same jobId is a no-op in BullMQ, so the enqueue is
+    // safe to attempt unconditionally.
+
+    await this.dispatch(run, type);
+    return run;
+  }
+
+  /**
+   * Map a `job_run` row onto a BullMQ job via `queue.add`. When the run has a
+   * `parentRunId` we attach it to the parent's existing BullMQ job through the
+   * `parent: { id, queue }` opt — BullMQ then tracks the parent/child link in
+   * its own graph. (The FlowProducer is reserved for whole-tree atomic
+   * submits, exposed as an opt-in extension via `flowProducer()`; runtime
+   * `ctx.spawnChild` is incremental, so `queue.add` with a parent ref is the
+   * correct primitive here.)
+   *
+   * The `jobId` is colon-safe + stable: `sha1(dedupeKey)` when a dedupe key is
+   * present (so the same logical key dedups), else the `job_run.id` UUID
+   * (already colon-free).
+   *
+   * The domain `parentClosePolicy` cascade is still enforced in Postgres by
+   * the shared `cancel` path — BullMQ's parent link is dispatch bookkeeping,
+   * not the authority.
+   */
+  private async dispatch(run: JobRun, type: string): Promise<void> {
+    await this.loadBullMq();
+    const def = await this.loadDefinition(type);
+    const jobId = run.dedupeKey ? sha1JobId(run.dedupeKey) : run.id;
+
+    const jobOpts: Record<string, unknown> = {
+      jobId,
+      ...this.retryOpts(def),
+      ...this.dedupeOpts(run, def),
+    };
+
+    if (run.parentRunId) {
+      const parentRow = await this.loadRun(run.parentRunId);
+      if (parentRow) {
+        const parentJobId = parentRow.dedupeKey
+          ? sha1JobId(parentRow.dedupeKey)
+          : parentRow.id;
+        jobOpts.parent = {
+          id: parentJobId,
+          queue: resolvePoolQueueName(parentRow.pool, this.bullConfig),
+        };
+      }
+    }
+
+    // The processor reads the authoritative input from `job_run`; the payload
+    // carries the runId so it can load the row, plus type/input for logging.
+    const payload = { runId: run.id, type, input: run.input };
+    await this.queueFor(run.pool).add(type, payload, jobOpts);
+  }
+
+  /**
+   * Opt-in extension (spec §Extensions): expose the FlowProducer for
+   * consumers that want to submit a whole parent/child DAG atomically up
+   * front, rather than incrementally via `ctx.spawnChild`. Backend-specific —
+   * code using it is not portable to the Drizzle backend. Async because it
+   * lazily loads the optional `bullmq` package on first use.
+   */
+  async flowProducer(): Promise<FlowProducer> {
+    await this.loadBullMq();
+    return this.flow();
+  }
+
+  private retryOpts(def: JobDefinitionRow): {
+    attempts?: number;
+    backoff?: { type: 'fixed' | 'exponential'; delay: number };
+  } {
+    const policy = def.retryPolicy;
+    if (!policy) return {};
+    return {
+      attempts: policy.attempts,
+      backoff: {
+        type: policy.backoff === 'exponential' ? 'exponential' : 'fixed',
+        delay: policy.baseMs,
+      },
+    };
+  }
+
+  private dedupeOpts(
+    run: JobRun,
+    def: JobDefinitionRow,
+  ): { deduplication?: { id: string; ttl?: number } } {
+    if (!run.dedupeKey || !def.dedupeWindowMs) return {};
+    return {
+      deduplication: {
+        id: sha1JobId(run.dedupeKey),
+        ttl: def.dedupeWindowMs,
+      },
+    };
+  }
+
+  // ==========================================================================
+  // cancel — Postgres cascade (super) + remove from queue
+  // ==========================================================================
+
+  override async cancel(runId: string, opts: CancelOptions = {}): Promise<void> {
+    // Snapshot the subtree BEFORE the DB cascade flips rows to canceled, so we
+    // can remove every affected BullMQ job. We read the target's rootRunId and
+    // the non-terminal descendants the same way the Drizzle cascade does.
+    const target = await this.loadRun(runId);
+
+    await super.cancel(runId, opts);
+
+    if (!target) return;
+    await this.loadBullMq();
+    // Remove the target's own queued job.
+    await this.removeFromQueue(target);
+
+    if (opts.cascade === false) return;
+
+    // Remove descendants' queued jobs (the DB rows were just canceled by
+    // super.cancel; we mirror that into BullMQ so workers don't pick them up).
+    const descendants = await this.bullDb
+      .select()
+      .from(jobRuns)
+      .where(eq(jobRuns.rootRunId, target.rootRunId));
+    for (const child of descendants) {
+      if (child.id === runId) continue;
+      await this.removeFromQueue(child as JobRun);
+    }
+  }
+
+  private async removeFromQueue(run: JobRun): Promise<void> {
+    const jobId = run.dedupeKey ? sha1JobId(run.dedupeKey) : run.id;
+    try {
+      const job = await this.queueFor(run.pool).getJob(jobId);
+      if (job) await job.remove();
+    } catch (err) {
+      // A job already moved to active/completed cannot always be removed;
+      // the Postgres cancel is authoritative either way.
+      this.bullLogger.warn(
+        `cancel: could not remove BullMQ job ${jobId} (pool=${run.pool}): ${(err as Error).message}`,
+      );
+    }
+  }
+
+  // ==========================================================================
+  // replay — Postgres reset (super) + re-enqueue
+  // ==========================================================================
+
+  override async replay(runId: string): Promise<JobRun> {
+    const run = await super.replay(runId);
+    await this.dispatch(run, run.jobType);
+    return run;
+  }
+
+  // ==========================================================================
+  // Internals
+  // ==========================================================================
+
+  private async loadDefinition(type: string): Promise<JobDefinitionRow> {
+    const [def] = await this.bullDb
+      .select()
+      .from(jobs)
+      .where(eq(jobs.type, type))
+      .limit(1);
+    if (!def) {
+      throw new Error(`BullMQJobOrchestrator: no job definition for '${type}'`);
+    }
+    return def as JobDefinitionRow;
+  }
+
+  private async loadRun(id: string): Promise<JobRun | null> {
+    const [row] = await this.bullDb
+      .select()
+      .from(jobRuns)
+      .where(eq(jobRuns.id, id))
+      .limit(1);
+    return (row as JobRun) ?? null;
+  }
+
+  /** Close all open queue + flow connections. Called on module destroy. */
+  async closeConnections(): Promise<void> {
+    for (const q of this.queues.values()) {
+      await q.close().catch(() => undefined);
+    }
+    this.queues.clear();
+    if (this._flow) {
+      await this._flow.close().catch(() => undefined);
+      this._flow = null;
+    }
+  }
+}

package/runtime/subsystems/jobs/job-run-keyset-cursor.ts

@@ -0,0 +1,88 @@
+/**
+ * Keyset (seek) cursor codec for `IJobRunService.listJobRuns` (OBS-LIST-1).
+ *
+ * The list is ordered `created_at DESC, id DESC`. The cursor encodes the
+ * `(createdAt, id)` of the last row on the previous page so the next page
+ * can seek with `WHERE (created_at, id) < (cursorCreatedAt, cursorId)`
+ * rather than an `OFFSET`. Keyset pagination stays O(log n) on deep pages
+ * and is stable as new rows arrive at the head.
+ *
+ * The cursor is opaque to consumers: a base64url-encoded JSON tuple. Shape
+ * is an implementation detail — never parse it outside this module.
+ *
+ * Also hosts `toJobRunSummary`, the single `JobRunRow → JobRunSummary`
+ * projection shared by both backends so the narrow shape stays in sync.
+ */
+import type { JobRunRow } from './job-orchestration.schema';
+import type { JobRunSummary } from './job-run-service.protocol';
+
+export interface JobRunKeyset {
+  /** `created_at` of the last row on the previous page. */
+  createdAt: Date;
+  /** `id` (UUID) tie-break of the last row on the previous page. */
+  id: string;
+}
+
+/** Default page size when `limit` is omitted. */
+export const DEFAULT_LIST_LIMIT = 50;
+/** Hard upper bound on page size to keep a single read bounded. */
+export const MAX_LIST_LIMIT = 200;
+
+/** Clamp a caller-supplied `limit` into `[1, MAX_LIST_LIMIT]`. */
+export function clampLimit(limit: number | undefined): number {
+  if (typeof limit !== 'number' || !Number.isFinite(limit)) {
+    return DEFAULT_LIST_LIMIT;
+  }
+  const floored = Math.floor(limit);
+  if (floored < 1) return 1;
+  if (floored > MAX_LIST_LIMIT) return MAX_LIST_LIMIT;
+  return floored;
+}
+
+export function encodeKeysetCursor(keyset: JobRunKeyset): string {
+  const tuple = [keyset.createdAt.toISOString(), keyset.id];
+  return Buffer.from(JSON.stringify(tuple), 'utf8').toString('base64url');
+}
+
+/**
+ * Decode an opaque cursor back into its `(createdAt, id)` keyset. Returns
+ * `null` for a malformed cursor so callers can treat garbage input as
+ * "start from the beginning" rather than throwing on user-supplied data.
+ */
+export function decodeKeysetCursor(cursor: string): JobRunKeyset | null {
+  try {
+    const json = Buffer.from(cursor, 'base64url').toString('utf8');
+    const parsed = JSON.parse(json) as unknown;
+    if (!Array.isArray(parsed) || parsed.length !== 2) return null;
+    const [iso, id] = parsed;
+    if (typeof iso !== 'string' || typeof id !== 'string') return null;
+    const createdAt = new Date(iso);
+    if (Number.isNaN(createdAt.getTime())) return null;
+    return { createdAt, id };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Project a raw `job_run` row into the narrow `JobRunSummary` shape exposed
+ * by `listJobRuns`. `errorMessage` is pulled from the jsonb `error.message`.
+ */
+export function toJobRunSummary(r: JobRunRow): JobRunSummary {
+  return {
+    runId: r.id,
+    rootRunId: r.rootRunId,
+    jobType: r.jobType,
+    pool: r.pool,
+    status: r.status,
+    scopeEntityType: r.scopeEntityType,
+    scopeEntityId: r.scopeEntityId,
+    tenantId: r.tenantId,
+    attempts: r.attempts,
+    errorMessage: r.error?.message ?? null,
+    runAt: r.runAt,
+    startedAt: r.startedAt,
+    finishedAt: r.finishedAt,
+    createdAt: r.createdAt,
+  };
+}

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

@@ -7,7 +7,7 @@
  * `idx_job_run_scope`, whereas orchestrator mutates individual runs by id.
  */
 import { Inject, Injectable } from '@nestjs/common';
-import { and, asc, desc, eq, inArray, isNull, sql } from 'drizzle-orm';
+import { and, asc, desc, eq, gte, inArray, isNull, lt, or, sql } from 'drizzle-orm';
 import type { DrizzleClient } from '../../types/drizzle';
 import { DRIZZLE } from '../../constants/tokens';
 import { jobRuns, type JobRunRow } from './job-orchestration.schema';
@@ -19,7 +19,16 @@ import type {
   RescheduleForScopeOptions,
   PoolStatusCount,
   JobRunFailure,
+  ListJobRunsQuery,
+  JobRunPage,
+  JobRunSummary,
 } from './job-run-service.protocol';
+import {
+  clampLimit,
+  decodeKeysetCursor,
+  encodeKeysetCursor,
+  toJobRunSummary,
+} from './job-run-keyset-cursor';
 import type { IJobOrchestrator } from './job-orchestrator.protocol';
 import { JOB_ORCHESTRATOR, JOBS_MULTI_TENANT } from './jobs-domain.tokens';
 import { MissingTenantIdError } from './jobs-errors';
@@ -208,6 +217,55 @@ export class DrizzleJobRunService implements IJobRunService {
     }));
   }
 
+  async listJobRuns(query: ListJobRunsQuery = {}): Promise<JobRunPage> {
+    const limit = clampLimit(query.limit);
+    const conditions = [];
+
+    const tenantCond = this.tenantCondition('listJobRuns', query.tenantId);
+    if (tenantCond) conditions.push(tenantCond);
+    if (query.poolId) conditions.push(eq(jobRuns.pool, query.poolId));
+    if (query.rootRunId) conditions.push(eq(jobRuns.rootRunId, query.rootRunId));
+    if (query.status) conditions.push(eq(jobRuns.status, query.status));
+    if (query.since) conditions.push(gte(jobRuns.createdAt, query.since));
+
+    // Keyset seek: WHERE (created_at, id) < (cursorCreatedAt, cursorId),
+    // expanded into a SARGable OR so the same `created_at` index is used.
+    if (query.cursor) {
+      const keyset = decodeKeysetCursor(query.cursor);
+      if (keyset) {
+        conditions.push(
+          or(
+            lt(jobRuns.createdAt, keyset.createdAt),
+            and(
+              eq(jobRuns.createdAt, keyset.createdAt),
+              lt(jobRuns.id, keyset.id),
+            ),
+          )!,
+        );
+      }
+    }
+
+    // Fetch one extra row to determine whether a next page exists without a
+    // separate COUNT.
+    const rows = await this.db
+      .select()
+      .from(jobRuns)
+      .where(conditions.length > 0 ? and(...conditions) : undefined)
+      .orderBy(desc(jobRuns.createdAt), desc(jobRuns.id))
+      .limit(limit + 1);
+
+    const hasMore = rows.length > limit;
+    const page = hasMore ? rows.slice(0, limit) : rows;
+    const items = page.map(toJobRunSummary);
+    const last = page[page.length - 1];
+    const nextCursor =
+      hasMore && last
+        ? encodeKeysetCursor({ createdAt: last.createdAt, id: last.id })
+        : null;
+
+    return { items, nextCursor };
+  }
+
   /**
    * Internal helper used by cascade paths (not on the public protocol).
    * Exposed as a public method on the concrete class so infrastructure