@pattern-stack/codegen 0.8.0 → 0.9.0

package/runtime/subsystems/events/index.ts

@@ -4,8 +4,15 @@
  * Import the module in AppModule, inject the bus via EVENT_BUS token.
  */
 export type { DomainEvent, IEventBus, DrizzleTransaction } from './event-bus.protocol';
+export type {
+  IEventReadPort,
+  ListEventsQuery,
+  EventSummary,
+  EventPage,
+} from './event-read.protocol';
 export {
   EVENT_BUS,
+  EVENT_READ_PORT,
   EVENTS_MODULE_OPTIONS,
   EVENTS_MULTI_TENANT,
   TYPED_EVENT_BUS,

package/runtime/subsystems/jobs/bullmq.config.ts

@@ -0,0 +1,125 @@
+/**
+ * BullMQ backend configuration surface (BULLMQ-1, ADR-022 extension slot).
+ *
+ * The core `IJobOrchestrator` contract is backend-agnostic; everything in
+ * this file is BullMQ-specific and lives behind the
+ * `jobs.extensions.bullmq.*` config namespace (CLAUDE.md core/extension
+ * protocol). The Drizzle backend never reads any of it.
+ */
+import type { ConnectionOptions } from 'bullmq';
+import { loadPoolConfig, type PoolConfig } from './pool-config.loader';
+
+/**
+ * Typed shape of `codegen.config.yaml: jobs.extensions.bullmq`. Snake_case
+ * because it mirrors the YAML the consumer authors.
+ *
+ * ```yaml
+ * jobs:
+ *   backend: bullmq
+ *   extensions:
+ *     bullmq:
+ *       redis_url: redis://localhost:6379   # or env REDIS_URL
+ *       queue_prefix: myapp                  # optional namespace (ADR-022 OQ)
+ *       bull_board:
+ *         enabled: true
+ *         mount_path: /api/admin/queues
+ * ```
+ */
+export interface BullMqExtensionsConfig {
+  /**
+   * Redis/Valkey connection URL. When omitted, the runtime resolves
+   * `process.env.REDIS_URL`, then falls back to `redis://localhost:6379`.
+   */
+  redis_url?: string;
+  /**
+   * Optional queue-name prefix to avoid collisions when several codegen apps
+   * share one Redis (ADR-022 §"BullMQ queue naming collisions"). Applied to
+   * every pool queue alias.
+   */
+  queue_prefix?: string;
+  /**
+   * Bull Board dashboard — opt-in extension (not core). Mounting is the
+   * consumer's responsibility (it needs the consumer's Express/Nest adapter +
+   * admin auth); we only carry the config. See README + spec §Extensions.
+   */
+  bull_board?: {
+    enabled: boolean;
+    mount_path?: string;
+  };
+}
+
+/**
+ * The runtime form after `redis_url`/env resolution. This is what the
+ * orchestrator + worker actually consume.
+ */
+export interface BullMqResolvedConfig {
+  connection: ConnectionOptions;
+  queuePrefix?: string;
+  bullBoard?: { enabled: boolean; mountPath: string };
+}
+
+/** DI token for the resolved BullMQ `ConnectionOptions` (ioredis-compatible). */
+export const BULLMQ_CONNECTION = Symbol('BULLMQ_CONNECTION');
+
+/** DI token for the full resolved BullMQ config (prefix + bull board). */
+export const BULLMQ_RESOLVED_CONFIG = Symbol('BULLMQ_RESOLVED_CONFIG');
+
+const DEFAULT_REDIS_URL = 'redis://localhost:6379';
+const DEFAULT_BULL_BOARD_MOUNT = '/admin/queues';
+
+/**
+ * Resolve the BullMQ runtime config from the extension block.
+ *
+ * Precedence for the connection URL:
+ *   1. explicit `extensions.bullmq.redis_url`
+ *   2. `process.env.REDIS_URL`
+ *   3. `redis://localhost:6379`
+ *
+ * Returns a `{ url }` connection shape — BullMQ/ioredis accept a URL string
+ * via the `{ url }` ConnectionOptions form.
+ */
+export function resolveBullMqConfig(
+  ext: BullMqExtensionsConfig | undefined,
+): BullMqResolvedConfig {
+  const url =
+    ext?.redis_url ?? process.env.REDIS_URL ?? DEFAULT_REDIS_URL;
+
+  const resolved: BullMqResolvedConfig = {
+    connection: { url } as ConnectionOptions,
+    queuePrefix: ext?.queue_prefix,
+  };
+  if (ext?.bull_board?.enabled) {
+    resolved.bullBoard = {
+      enabled: true,
+      mountPath: ext.bull_board.mount_path ?? DEFAULT_BULL_BOARD_MOUNT,
+    };
+  }
+  return resolved;
+}
+
+/**
+ * Resolve the BullMQ queue name for a *logical pool name*. The orchestrator
+ * and worker MUST agree on this mapping or jobs are enqueued onto a queue
+ * nobody consumes. Both derive it identically:
+ *
+ *   1. Look up the pool's `queue` alias (e.g. `jobs-batch`) in the resolved
+ *      pool config — the same alias `JobWorkerModule.onModuleInit` logs and
+ *      that the BullMQ `Worker` binds to.
+ *   2. Fall back to the logical pool name when the pool is unknown (defensive;
+ *      still a stable, colon-free identifier).
+ *   3. Apply the optional `queue_prefix` namespace for multi-app Redis
+ *      sharing — `:` is fine in the *queue name* (it is only forbidden in the
+ *      `jobId`, hence the sha1 there).
+ *
+ * `poolConfig` defaults to the cached `loadPoolConfig()` so callers that only
+ * hold the logical pool name (the orchestrator) don't need to thread the map.
+ */
+export function resolvePoolQueueName(
+  pool: string,
+  config: BullMqResolvedConfig | null | undefined,
+  poolConfig: PoolConfig = loadPoolConfig(),
+): string {
+  const alias = poolConfig.get(pool)?.queue ?? pool;
+  const prefix = config?.queuePrefix;
+  return prefix ? `${prefix}:${alias}` : alias;
+}

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-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,
+  };
+}