@pattern-stack/codegen 0.8.1 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",

package/runtime/subsystems/bridge/bridge.module.ts

@@ -149,6 +149,11 @@ export class BridgeModule implements OnModuleInit {
 
   async onModuleInit(): Promise<void> {
     if (!this.workerOpts) return;
+    // BULLMQ-1 Phase 1 — `allPools: true` activates every pool (reserved
+    // `events_*` included), so the reserved-pool guarantee holds by
+    // construction. Short-circuit pass without inspecting the (typically
+    // omitted) explicit `pools` list.
+    if (this.workerOpts.allPools) return;
     const activePools = this.workerOpts.pools ?? [];
     const missing = BRIDGE_RESERVED_POOLS.filter(
       (p) => !activePools.includes(p),

package/runtime/subsystems/events/event-bus.drizzle-backend.ts

@@ -29,10 +29,20 @@
  * via EventsModule.forRoot({ backend: '...' }) without touching use cases.
  */
 import { Injectable, OnModuleDestroy, OnModuleInit, Inject, Logger, Optional } from '@nestjs/common';
-import { eq, and, inArray, asc, type SQL } from 'drizzle-orm';
+import { eq, and, inArray, asc, desc, gte, lt, or, sql, type SQL } from 'drizzle-orm';
 import type { DomainEvent, DrizzleTransaction, IEventBus } from './event-bus.protocol';
+import type {
+  EventPage,
+  IEventReadPort,
+  ListEventsQuery,
+} from './event-read.protocol';
+import {
+  clampEventLimit,
+  decodeEventCursor,
+  encodeEventCursor,
+} from './event-keyset-cursor';
 import type { DrizzleClient } from '../../types/drizzle';
-import { domainEvents } from './domain-events.schema';
+import { domainEvents, type DomainEventRecord } from './domain-events.schema';
 import { DRIZZLE } from '../../constants/tokens';
 import { EVENTS_MODULE_OPTIONS } from './events.tokens';
 import type { EventsModuleOptions } from './events.module';
@@ -76,8 +86,43 @@ function toInsertValues(event: DomainEvent) {
   };
 }
 
+/**
+ * Project a raw `domain_events` row into the narrow `EventSummary` shape.
+ * Shared with the memory backend via this helper kept module-local to each
+ * backend (the events subsystem has no cross-backend projection file yet;
+ * the two are byte-identical and small).
+ */
+function toEventSummary(r: DomainEventRecord) {
+  const metadata = (r.metadata ?? undefined) as
+    | Record<string, unknown>
+    | undefined;
+  const rootRunId = metadata?.['rootRunId'];
+  return {
+    id: r.id,
+    type: r.type,
+    aggregateId: r.aggregateId,
+    aggregateType: r.aggregateType,
+    status: r.status,
+    pool: r.pool,
+    direction: r.direction,
+    tier: r.tier,
+    rootRunId: typeof rootRunId === 'string' ? rootRunId : null,
+    tenantId: r.tenantId,
+    occurredAt:
+      r.occurredAt instanceof Date
+        ? r.occurredAt
+        : new Date(r.occurredAt as unknown as string),
+    processedAt:
+      r.processedAt == null
+        ? null
+        : r.processedAt instanceof Date
+          ? r.processedAt
+          : new Date(r.processedAt as unknown as string),
+  };
+}
+
 @Injectable()
-export class DrizzleEventBus implements IEventBus, OnModuleInit, OnModuleDestroy {
+export class DrizzleEventBus implements IEventBus, IEventReadPort, OnModuleInit, OnModuleDestroy {
   private readonly logger = new Logger(DrizzleEventBus.name);
   private polling = false;
   private pollTimer: ReturnType<typeof setTimeout> | null = null;
@@ -178,6 +223,67 @@ export class DrizzleEventBus implements IEventBus, OnModuleInit, OnModuleDestroy
     };
   }
 
+  // ============================================================================
+  // IEventReadPort (OBS-LIST-1)
+  // ============================================================================
+
+  async listEvents(query: ListEventsQuery = {}): Promise<EventPage> {
+    const limit = clampEventLimit(query.limit);
+    const conditions: SQL<unknown>[] = [];
+
+    if (query.poolId) conditions.push(eq(domainEvents.pool, query.poolId));
+    if (query.direction)
+      conditions.push(eq(domainEvents.direction, query.direction));
+    if (query.since) conditions.push(gte(domainEvents.occurredAt, query.since));
+    if (query.rootRunId) {
+      // Filter on the JSON correlation id: metadata->>'rootRunId'.
+      conditions.push(
+        sql`${domainEvents.metadata}->>'rootRunId' = ${query.rootRunId}`,
+      );
+    }
+    if (query.tenantId !== undefined) {
+      conditions.push(
+        query.tenantId === null
+          ? (sql`${domainEvents.tenantId} is null` as SQL<unknown>)
+          : eq(domainEvents.tenantId, query.tenantId),
+      );
+    }
+
+    // Keyset seek: WHERE (occurred_at, id) < (cursorOccurredAt, cursorId).
+    if (query.cursor) {
+      const keyset = decodeEventCursor(query.cursor);
+      if (keyset) {
+        conditions.push(
+          or(
+            lt(domainEvents.occurredAt, keyset.occurredAt),
+            and(
+              eq(domainEvents.occurredAt, keyset.occurredAt),
+              lt(domainEvents.id, keyset.id),
+            ),
+          )!,
+        );
+      }
+    }
+
+    const rows = (await this.db
+      .select()
+      .from(domainEvents)
+      .where(conditions.length > 0 ? and(...conditions) : undefined)
+      .orderBy(desc(domainEvents.occurredAt), desc(domainEvents.id))
+      .limit(limit + 1)) as DomainEventRecord[];
+
+    const hasMore = rows.length > limit;
+    const page = hasMore ? rows.slice(0, limit) : rows;
+    const items = page.map(toEventSummary);
+    const last = page[page.length - 1];
+    const nextCursor =
+      hasMore && last
+        ? encodeEventCursor({ occurredAt: last.occurredAt, id: last.id })
+        : null;
+
+    return { items, nextCursor };
+  }
+
   // ============================================================================
   // Polling
   // ============================================================================

package/runtime/subsystems/events/event-bus.memory-backend.ts

@@ -21,11 +21,52 @@
  */
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
 import type { DomainEvent, IEventBus } from './event-bus.protocol';
+import type {
+  EventPage,
+  EventSummary,
+  IEventReadPort,
+  ListEventsQuery,
+} from './event-read.protocol';
+import {
+  clampEventLimit,
+  decodeEventCursor,
+  encodeEventCursor,
+} from './event-keyset-cursor';
 import { EVENTS_MODULE_OPTIONS } from './events.tokens';
 import type { EventsModuleOptions } from './events.module';
 
+/**
+ * Project an in-memory `DomainEvent` into the narrow `EventSummary` shape.
+ * The memory backend has no first-class columns, so `pool` / `direction` /
+ * `tier` / `tenantId` / `rootRunId` are read from `metadata` (mirroring how
+ * the Drizzle backend stamps them onto columns at publish time). `status`
+ * is reported as `'processed'` — the memory bus dispatches synchronously,
+ * so once an event is in `publishedEvents` it has been handled.
+ */
+function toEventSummary(event: DomainEvent): EventSummary {
+  const metadata = event.metadata;
+  const str = (key: string): string | null => {
+    const v = metadata?.[key];
+    return typeof v === 'string' ? v : null;
+  };
+  return {
+    id: event.id,
+    type: event.type,
+    aggregateId: event.aggregateId,
+    aggregateType: event.aggregateType,
+    status: 'processed',
+    pool: str('pool'),
+    direction: str('direction'),
+    tier: str('tier') ?? 'domain',
+    rootRunId: str('rootRunId'),
+    tenantId: str('tenantId'),
+    occurredAt: event.occurredAt,
+    processedAt: event.occurredAt,
+  };
+}
+
 @Injectable()
-export class MemoryEventBus implements IEventBus {
+export class MemoryEventBus implements IEventBus, IEventReadPort {
   private readonly logger = new Logger(MemoryEventBus.name);
 
   /** All events published since construction (or last clear). */
@@ -86,6 +127,67 @@ export class MemoryEventBus implements IEventBus {
     };
   }
 
+  // ============================================================================
+  // IEventReadPort (OBS-LIST-1)
+  // ============================================================================
+
+  async listEvents(query: ListEventsQuery = {}): Promise<EventPage> {
+    const limit = clampEventLimit(query.limit);
+    const keyset = query.cursor ? decodeEventCursor(query.cursor) : null;
+
+    const str = (e: DomainEvent, key: string): string | null => {
+      const v = e.metadata?.[key];
+      return typeof v === 'string' ? v : null;
+    };
+
+    const matched = this.publishedEvents.filter((e) => {
+      if (query.poolId && str(e, 'pool') !== query.poolId) return false;
+      if (query.direction && str(e, 'direction') !== query.direction)
+        return false;
+      if (query.rootRunId && str(e, 'rootRunId') !== query.rootRunId)
+        return false;
+      if (query.since && e.occurredAt.getTime() < query.since.getTime())
+        return false;
+      if (query.tenantId !== undefined) {
+        const t = str(e, 'tenantId');
+        if (query.tenantId === null) {
+          if (t !== null) return false;
+        } else if (t !== query.tenantId) {
+          return false;
+        }
+      }
+      return true;
+    });
+
+    // Order occurred_at DESC, id DESC to match the Drizzle backend keyset.
+    matched.sort((a, b) => {
+      const dt = b.occurredAt.getTime() - a.occurredAt.getTime();
+      if (dt !== 0) return dt;
+      return a.id < b.id ? 1 : a.id > b.id ? -1 : 0;
+    });
+
+    const seeked = keyset
+      ? matched.filter((e) => {
+          const ct = e.occurredAt.getTime();
+          const kt = keyset.occurredAt.getTime();
+          if (ct < kt) return true;
+          if (ct > kt) return false;
+          return e.id < keyset.id;
+        })
+      : matched;
+
+    const hasMore = seeked.length > limit;
+    const page = hasMore ? seeked.slice(0, limit) : seeked;
+    const items = page.map(toEventSummary);
+    const last = page[page.length - 1];
+    const nextCursor =
+      hasMore && last
+        ? encodeEventCursor({ occurredAt: last.occurredAt, id: last.id })
+        : null;
+
+    return { items, nextCursor };
+  }
+
   /** Remove all published events and subscriptions. Useful in beforeEach. */
   clear(): void {
     this.publishedEvents.length = 0;

package/runtime/subsystems/events/event-keyset-cursor.ts

@@ -0,0 +1,59 @@
+/**
+ * Keyset (seek) cursor codec for `IEventReadPort.listEvents` (OBS-LIST-1).
+ *
+ * The list is ordered `occurred_at DESC, id DESC`. The cursor encodes the
+ * `(occurredAt, id)` of the last row on the previous page so the next page
+ * seeks with `WHERE (occurred_at, id) < (cursorOccurredAt, cursorId)`.
+ *
+ * The cursor is opaque to consumers: a base64url-encoded JSON tuple. Shape
+ * is an implementation detail — never parse it outside this module.
+ *
+ * Mirrors the jobs keyset codec; kept separate because the events subsystem
+ * must not depend on `runtime/subsystems/jobs/`.
+ */
+
+export interface EventKeyset {
+  occurredAt: Date;
+  id: string;
+}
+
+/** Default page size when `limit` is omitted. */
+export const DEFAULT_EVENT_LIST_LIMIT = 50;
+/** Hard upper bound on page size. */
+export const MAX_EVENT_LIST_LIMIT = 200;
+
+/** Clamp a caller-supplied `limit` into `[1, MAX_EVENT_LIST_LIMIT]`. */
+export function clampEventLimit(limit: number | undefined): number {
+  if (typeof limit !== 'number' || !Number.isFinite(limit)) {
+    return DEFAULT_EVENT_LIST_LIMIT;
+  }
+  const floored = Math.floor(limit);
+  if (floored < 1) return 1;
+  if (floored > MAX_EVENT_LIST_LIMIT) return MAX_EVENT_LIST_LIMIT;
+  return floored;
+}
+
+export function encodeEventCursor(keyset: EventKeyset): string {
+  const tuple = [keyset.occurredAt.toISOString(), keyset.id];
+  return Buffer.from(JSON.stringify(tuple), 'utf8').toString('base64url');
+}
+
+/**
+ * Decode an opaque cursor back into its `(occurredAt, id)` keyset. Returns
+ * `null` for malformed input so user-supplied garbage is treated as "start
+ * from the beginning" rather than throwing.
+ */
+export function decodeEventCursor(cursor: string): EventKeyset | 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 occurredAt = new Date(iso);
+    if (Number.isNaN(occurredAt.getTime())) return null;
+    return { occurredAt, id };
+  } catch {
+    return null;
+  }
+}

package/runtime/subsystems/events/event-read.protocol.ts

@@ -0,0 +1,97 @@
+/**
+ * IEventReadPort — read-side port over `domain_events` (OBS-LIST-1).
+ *
+ * The publish/subscribe `IEventBus` (EVENT_BUS) is a *write + dispatch*
+ * port; it deliberately does not expose tabular reads beyond `findById`.
+ * The observability combiner needs a paginated, filterable list of
+ * `domain_events` for its events viewer, so we add a dedicated read port
+ * rather than overloading `IEventBus`.
+ *
+ * Keeping reads on a separate port means:
+ *   - the combiner can compose it `@Optional()` independently of EVENT_BUS;
+ *   - the Redis backend (which retains no history) simply does not provide
+ *     it — there is no "list" semantics to fake;
+ *   - the write/dispatch surface stays minimal.
+ *
+ * Both `DrizzleEventBus` and `MemoryEventBus` implement this port (they
+ * already hold the rows / in-memory log); `EventsModule.forRoot` binds the
+ * `EVENT_READ_PORT` token to the same instance for drizzle/memory backends.
+ */
+
+import type { DomainEvent } from './event-bus.protocol';
+
+/**
+ * Filter + keyset-pagination input for `IEventReadPort.listEvents`.
+ *
+ * Ordered `occurred_at DESC, id DESC`. `rootRunId` filters on the JSON
+ * `metadata->>'rootRunId'` — the correlation id stamped by the jobs/bridge
+ * machinery so an event can be traced back to the run tree that emitted it.
+ */
+export interface ListEventsQuery {
+  /** Filter on `metadata->>'rootRunId'` (correlation id). */
+  rootRunId?: string;
+  /** Filter on the first-class `pool` column. */
+  poolId?: string;
+  /** Filter on the first-class `direction` column (inbound|change|outbound). */
+  direction?: string;
+  /** Lower bound on `occurred_at` (inclusive). */
+  since?: Date;
+  /** Opaque keyset cursor from a previous page's `nextCursor`. */
+  cursor?: string;
+  /** Page size. Backend clamps to a sane default + max. */
+  limit?: number;
+  /**
+   * Multi-tenancy filter on the first-class `tenant_id` column. Only
+   * meaningful when the consumer publishes tenant-scoped events
+   * (`events.multi_tenant: true`); otherwise leave undefined.
+   *   - `string` — filter `tenant_id = :tenantId`.
+   *   - `null`   — filter `tenant_id IS NULL`.
+   *   - `undefined` — no tenant filter.
+   */
+  tenantId?: string | null;
+}
+
+/**
+ * Summary row for the events list. A narrow projection over `domain_events`
+ * carrying what the viewer + correlation timeline need. `rootRunId` is
+ * surfaced (lifted out of `metadata`) so the timeline can stitch without a
+ * second metadata dig.
+ */
+export interface EventSummary {
+  id: string;
+  type: string;
+  aggregateId: string;
+  aggregateType: string;
+  status: string;
+  pool: string | null;
+  direction: string | null;
+  tier: string;
+  rootRunId: string | null;
+  tenantId: string | null;
+  occurredAt: Date;
+  processedAt: Date | null;
+}
+
+/**
+ * One page of `listEvents` results. `nextCursor` is `null` when there are
+ * no more rows.
+ */
+export interface EventPage {
+  items: EventSummary[];
+  nextCursor: string | null;
+}
+
+export interface IEventReadPort {
+  /**
+   * Paginated, filterable list of `domain_events` (OBS-LIST-1). Newest
+   * first (`occurred_at` desc, `id` desc keyset tie-break). Returns an
+   * `EventPage` with an opaque `nextCursor` for keyset pagination.
+   */
+  listEvents(query?: ListEventsQuery): Promise<EventPage>;
+}
+
+/** A `DomainEvent` whose metadata may carry a `rootRunId` correlation id. */
+export function rootRunIdOf(event: DomainEvent): string | null {
+  const v = event.metadata?.['rootRunId'];
+  return typeof v === 'string' ? v : null;
+}

package/runtime/subsystems/events/events.module.ts

@@ -47,6 +47,7 @@
 import { Module, type DynamicModule, type Provider } from '@nestjs/common';
 import {
   EVENT_BUS,
+  EVENT_READ_PORT,
   EVENTS_MODULE_OPTIONS,
   EVENTS_MULTI_TENANT,
   REDIS_URL,
@@ -180,10 +181,21 @@ export class EventsModule {
             REDIS_URL,
           ],
         },
+        {
+          // Read port (OBS-LIST-1). Drizzle + memory backends implement
+          // IEventReadPort on the EVENT_BUS instance; the redis backend
+          // retains no history, so EVENT_READ_PORT resolves to `null` and
+          // optional consumers (the observability combiner) degrade to
+          // empty results.
+          provide: EVENT_READ_PORT,
+          useFactory: (options: EventsModuleOptions, bus: unknown) =>
+            options.backend === 'redis' ? null : bus,
+          inject: [EVENTS_MODULE_OPTIONS, EVENT_BUS],
+        },
         TypedEventBus,
         { provide: TYPED_EVENT_BUS, useExisting: TypedEventBus },
       ],
-      exports: [EVENT_BUS, TYPED_EVENT_BUS, EVENTS_MULTI_TENANT],
+      exports: [EVENT_BUS, EVENT_READ_PORT, TYPED_EVENT_BUS, EVENTS_MULTI_TENANT],
     };
   }
 
@@ -222,9 +234,13 @@ export class EventsModule {
       providers: [
         { provide: EVENTS_MODULE_OPTIONS, useValue: options },
         provider,
+        // Read port (OBS-LIST-1): drizzle + memory backends implement
+        // IEventReadPort on the same instance as EVENT_BUS. The redis
+        // backend retains no history and does not provide this token.
+        { provide: EVENT_READ_PORT, useExisting: EVENT_BUS },
         ...buildTypedBusProviders(multiTenant),
       ],
-      exports: [EVENT_BUS, TYPED_EVENT_BUS, EVENTS_MULTI_TENANT],
+      exports: [EVENT_BUS, EVENT_READ_PORT, TYPED_EVENT_BUS, EVENTS_MULTI_TENANT],
     };
   }
 }

package/runtime/subsystems/events/events.tokens.ts

@@ -11,6 +11,22 @@
  */
 export const EVENT_BUS = 'EVENT_BUS' as const;
 
+/**
+ * Injection token for the read-side `IEventReadPort` over `domain_events`
+ * (OBS-LIST-1).
+ *
+ * Bound by `EventsModule.forRoot` to the same backend instance as
+ * `EVENT_BUS` for the `drizzle` and `memory` backends (both implement
+ * `IEventReadPort`). The `redis` backend retains no history and therefore
+ * does NOT provide this token — consumers composing it (e.g. the
+ * observability combiner) inject it `@Optional()` and degrade to empty
+ * results.
+ *
+ * String constant (not Symbol) so it matches by value across import
+ * boundaries — same convention as `EVENT_BUS`.
+ */
+export const EVENT_READ_PORT = 'EVENT_READ_PORT' as const;
+
 /**
  * Injection token for the generated `TypedEventBus` facade.
  *

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,