@pattern-stack/codegen 0.15.3 → 0.16.0

package/dist/runtime/subsystems/jobs/index.js

@@ -1,8 +1,8 @@
-import "../../../chunk-UTN4GBPQ.js";
+import "../../../chunk-W4HOHZVF.js";
 import {
   JobWorkerModule,
   JobWorkerOrchestrator
-} from "../../../chunk-4H3PETLM.js";
+} from "../../../chunk-RUYLXR5F.js";
 import {
   JOB_WORKER_OPTIONS,
   JobWorker,
@@ -10,42 +10,28 @@ import {
   buildStaleSweepQuery,
   classifyError,
   computeBackoff
-} from "../../../chunk-RC23QROE.js";
+} from "../../../chunk-XDIIVIIK.js";
 import {
   JobsDomainModule
-} from "../../../chunk-O37C3YE6.js";
-import {
-  DrizzleJobRunService
-} from "../../../chunk-FBGHYQIZ.js";
-import {
-  MemoryJobRunService
-} from "../../../chunk-RDVTWIYY.js";
-import "../../../chunk-L3LZWWSX.js";
+} from "../../../chunk-3RWMQC3K.js";
 import {
   DrizzleJobStepService
 } from "../../../chunk-DV4RV2DC.js";
-import {
-  BULLMQ_CONNECTION,
-  BULLMQ_RESOLVED_CONFIG,
-  resolveBullMqConfig,
-  resolvePoolQueueName
-} from "../../../chunk-I6MVCB5A.js";
-import {
-  FRAMEWORK_POOLS,
-  RESERVED_POOL_NAMES,
-  allNonReservedPoolNames,
-  allPoolNames,
-  loadPoolConfig
-} from "../../../chunk-RHVN6NA7.js";
 import {
   DrizzleJobOrchestrator
-} from "../../../chunk-5Y7W3XR6.js";
+} from "../../../chunk-OTR44OH6.js";
 import {
   MemoryJobOrchestrator
-} from "../../../chunk-4RFHUZXU.js";
+} from "../../../chunk-BULPAAD3.js";
 import {
   MemoryJobStepService
 } from "../../../chunk-PNZSGAB2.js";
+import {
+  DrizzleJobRunService
+} from "../../../chunk-VNBC3VXM.js";
+import {
+  MemoryJobRunService
+} from "../../../chunk-BHZP6LOV.js";
 import {
   MemoryJobStore
 } from "../../../chunk-SNQ3TOWP.js";
@@ -58,6 +44,27 @@ import {
   MissingTenantIdError,
   ReservedPoolViolationError
 } from "../../../chunk-T4BIIU5E.js";
+import "../../../chunk-L3LZWWSX.js";
+import {
+  BULLMQ_CONNECTION,
+  BULLMQ_RESOLVED_CONFIG,
+  resolveBullMqConfig,
+  resolvePoolQueueName
+} from "../../../chunk-I6MVCB5A.js";
+import {
+  FRAMEWORK_POOLS,
+  RESERVED_POOL_NAMES,
+  allNonReservedPoolNames,
+  allPoolNames,
+  loadPoolConfig
+} from "../../../chunk-RHVN6NA7.js";
+import {
+  JOBS_LISTEN_NOTIFY,
+  JOBS_MULTI_TENANT,
+  JOB_ORCHESTRATOR,
+  JOB_RUN_SERVICE,
+  JOB_STEP_SERVICE
+} from "../../../chunk-ZPL74UQN.js";
 import {
   HandlerRegistry,
   JOB_HANDLER_METADATA_KEY,
@@ -66,12 +73,6 @@ import {
   JobHandlerBase,
   ParentClosePolicy
 } from "../../../chunk-CO6LUM72.js";
-import {
-  JOBS_MULTI_TENANT,
-  JOB_ORCHESTRATOR,
-  JOB_RUN_SERVICE,
-  JOB_STEP_SERVICE
-} from "../../../chunk-BIO6F7YI.js";
 import {
   collisionModeEnum,
   jobRunStatusEnum,
@@ -85,6 +86,12 @@ import {
   triggerSourceEnum,
   waitKindEnum
 } from "../../../chunk-OKXZ63IA.js";
+import {
+  EVENTS_WAKE_CHANNEL,
+  JOBS_WAKE_CHANNEL,
+  PgNotifyListener,
+  pgNotify
+} from "../../../chunk-MYQIQ27N.js";
 import "../../../chunk-GYGNEQSC.js";
 import "../../../chunk-U64T4YZE.js";
 import "../../../chunk-2E224ZSN.js";
@@ -95,9 +102,12 @@ export {
   DrizzleJobOrchestrator,
   DrizzleJobRunService,
   DrizzleJobStepService,
+  EVENTS_WAKE_CHANNEL,
   FRAMEWORK_POOLS,
   HandlerRegistry,
+  JOBS_LISTEN_NOTIFY,
   JOBS_MULTI_TENANT,
+  JOBS_WAKE_CHANNEL,
   JOB_HANDLER_METADATA_KEY,
   JOB_HANDLER_REGISTRY,
   JOB_ORCHESTRATOR,
@@ -120,6 +130,7 @@ export {
   MemoryJobStore,
   MissingTenantIdError,
   ParentClosePolicy,
+  PgNotifyListener,
   RESERVED_POOL_NAMES,
   ReservedPoolViolationError,
   allNonReservedPoolNames,
@@ -137,6 +148,7 @@ export {
   jobs,
   loadPoolConfig,
   parentClosePolicyEnum,
+  pgNotify,
   replayFromEnum,
   resolveBullMqConfig,
   resolvePoolQueueName,

package/dist/runtime/subsystems/jobs/job-orchestrator.bullmq-backend.js

@@ -1,20 +1,21 @@
+import {
+  DrizzleJobOrchestrator
+} from "../../../chunk-OTR44OH6.js";
+import "../../../chunk-T4BIIU5E.js";
 import {
   BULLMQ_CONNECTION,
   BULLMQ_RESOLVED_CONFIG,
   resolvePoolQueueName
 } from "../../../chunk-I6MVCB5A.js";
 import "../../../chunk-RHVN6NA7.js";
-import {
-  DrizzleJobOrchestrator
-} from "../../../chunk-5Y7W3XR6.js";
-import "../../../chunk-T4BIIU5E.js";
 import {
   JOBS_MULTI_TENANT
-} from "../../../chunk-BIO6F7YI.js";
+} from "../../../chunk-ZPL74UQN.js";
 import {
   jobRuns,
   jobs
 } from "../../../chunk-OKXZ63IA.js";
+import "../../../chunk-MYQIQ27N.js";
 import "../../../chunk-GYGNEQSC.js";
 import {
   DRIZZLE

package/dist/runtime/subsystems/jobs/job-orchestrator.bullmq-backend.js.map

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

package/dist/runtime/subsystems/jobs/job-orchestrator.drizzle-backend.d.ts

@@ -25,8 +25,9 @@ declare function evaluateKeyTemplate(template: string, input: Record<string, unk
 declare class DrizzleJobOrchestrator implements IJobOrchestrator {
     private readonly db;
     private readonly multiTenant;
+    private readonly listenNotify;
     private readonly logger;
-    constructor(db: DrizzleClient, multiTenant: boolean);
+    constructor(db: DrizzleClient, multiTenant: boolean, listenNotify?: boolean);
     /**
      * JOB-8 — resolve `tenantId` for a mutating / targeted-read call.
      * Returns the tenant value that should be written to the row (or compared

package/dist/runtime/subsystems/jobs/job-orchestrator.drizzle-backend.js

@@ -2,10 +2,11 @@ import {
   DrizzleJobOrchestrator,
   TERMINAL_STATUSES,
   evaluateKeyTemplate
-} from "../../../chunk-5Y7W3XR6.js";
+} from "../../../chunk-OTR44OH6.js";
 import "../../../chunk-T4BIIU5E.js";
-import "../../../chunk-BIO6F7YI.js";
+import "../../../chunk-ZPL74UQN.js";
 import "../../../chunk-OKXZ63IA.js";
+import "../../../chunk-MYQIQ27N.js";
 import "../../../chunk-GYGNEQSC.js";
 import "../../../chunk-U64T4YZE.js";
 import "../../../chunk-2E224ZSN.js";

package/dist/runtime/subsystems/jobs/job-orchestrator.memory-backend.js

@@ -1,11 +1,11 @@
 import {
   MemoryJobOrchestrator
-} from "../../../chunk-4RFHUZXU.js";
+} from "../../../chunk-BULPAAD3.js";
 import "../../../chunk-PNZSGAB2.js";
 import "../../../chunk-SNQ3TOWP.js";
 import "../../../chunk-T4BIIU5E.js";
+import "../../../chunk-ZPL74UQN.js";
 import "../../../chunk-CO6LUM72.js";
-import "../../../chunk-BIO6F7YI.js";
 import "../../../chunk-GYGNEQSC.js";
 import "../../../chunk-2E224ZSN.js";
 export {

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

@@ -1,9 +1,9 @@
 import {
   DrizzleJobRunService
-} from "../../../chunk-FBGHYQIZ.js";
-import "../../../chunk-L3LZWWSX.js";
+} from "../../../chunk-VNBC3VXM.js";
 import "../../../chunk-T4BIIU5E.js";
-import "../../../chunk-BIO6F7YI.js";
+import "../../../chunk-L3LZWWSX.js";
+import "../../../chunk-ZPL74UQN.js";
 import "../../../chunk-OKXZ63IA.js";
 import "../../../chunk-GYGNEQSC.js";
 import "../../../chunk-U64T4YZE.js";

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

@@ -1,10 +1,10 @@
 import {
   MemoryJobRunService
-} from "../../../chunk-RDVTWIYY.js";
-import "../../../chunk-L3LZWWSX.js";
+} from "../../../chunk-BHZP6LOV.js";
 import "../../../chunk-SNQ3TOWP.js";
 import "../../../chunk-T4BIIU5E.js";
-import "../../../chunk-BIO6F7YI.js";
+import "../../../chunk-L3LZWWSX.js";
+import "../../../chunk-ZPL74UQN.js";
 import "../../../chunk-GYGNEQSC.js";
 import "../../../chunk-2E224ZSN.js";
 export {

package/dist/runtime/subsystems/jobs/job-worker.d.ts

@@ -32,6 +32,14 @@ interface JobWorkerOptions {
     staleThresholdMs?: number;
     /** Max ms to wait for in-flight drain on SIGTERM. Default 30_000. */
     shutdownTimeoutMs?: number;
+    /**
+     * LISTEN-NOTIFY-1 — when true, hold a dedicated listener connection and
+     * LISTEN on `codegen_jobs_wake`. A notification naming this worker's `pool`
+     * triggers an immediate (debounced) claim cycle, so an enqueue is claimed in
+     * milliseconds instead of waiting for the next `pollIntervalMs` tick. Polling
+     * continues unchanged as the fallback heartbeat. Default false.
+     */
+    listenNotify?: boolean;
 }
 declare const JOB_WORKER_OPTIONS: unique symbol;
 declare const TERMINAL_STATUSES: JobRunRow['status'][];
@@ -154,8 +162,28 @@ declare class JobWorker implements OnModuleInit, OnModuleDestroy {
     private readonly staleSweeperIntervalMs;
     private readonly staleThresholdMs;
     private readonly shutdownTimeoutMs;
+    private readonly listenNotifyEnabled;
+    private notifyListener;
+    /** True while a wake-driven claim cycle is in flight (debounce gate). */
+    private wakeDraining;
+    /** A notify arrived mid-cycle → re-check once when the cycle ends. */
+    private wakeRecheckPending;
     constructor(db: DrizzleClient, orchestrator: IJobOrchestrator, runService: IJobRunService, stepService: IJobStepService, options: JobWorkerOptions, moduleRef: ModuleRef);
     onModuleInit(): void;
+    /**
+     * Wake handler — a `codegen_jobs_wake` notification arrived. Only payloads
+     * naming THIS worker's pool are relevant (other pools have their own workers).
+     * Debounced: if a claim cycle is already running we just flag a re-check so a
+     * burst of N enqueues collapses to at most one extra cycle (D3).
+     */
+    private onWake;
+    /**
+     * Claim-until-empty on a wake. Unlike the interval `pollAndProcess` (one
+     * claim per tick), a wake drains greedily up to the concurrency ceiling so a
+     * burst that arrived together is dispatched without waiting for N ticks. The
+     * `wakeRecheckPending` flag coalesces notifies that land mid-drain.
+     */
+    private drainOnWake;
     onModuleDestroy(): Promise<void>;
     private drainInFlight;
     pollAndProcess(): Promise<void>;

package/dist/runtime/subsystems/jobs/job-worker.js

@@ -6,10 +6,11 @@ import {
   buildStaleSweepQuery,
   classifyError,
   computeBackoff
-} from "../../../chunk-RC23QROE.js";
+} from "../../../chunk-XDIIVIIK.js";
+import "../../../chunk-ZPL74UQN.js";
 import "../../../chunk-CO6LUM72.js";
-import "../../../chunk-BIO6F7YI.js";
 import "../../../chunk-OKXZ63IA.js";
+import "../../../chunk-MYQIQ27N.js";
 import "../../../chunk-GYGNEQSC.js";
 import "../../../chunk-U64T4YZE.js";
 import "../../../chunk-2E224ZSN.js";

package/dist/runtime/subsystems/jobs/job-worker.module.js

@@ -2,23 +2,24 @@ import {
   JOB_WORKER_MODULE_OPTIONS,
   JobWorkerModule,
   JobWorkerOrchestrator
-} from "../../../chunk-4H3PETLM.js";
-import "../../../chunk-RC23QROE.js";
-import "../../../chunk-O37C3YE6.js";
-import "../../../chunk-FBGHYQIZ.js";
-import "../../../chunk-RDVTWIYY.js";
-import "../../../chunk-L3LZWWSX.js";
+} from "../../../chunk-RUYLXR5F.js";
+import "../../../chunk-XDIIVIIK.js";
+import "../../../chunk-3RWMQC3K.js";
 import "../../../chunk-DV4RV2DC.js";
-import "../../../chunk-I6MVCB5A.js";
-import "../../../chunk-RHVN6NA7.js";
-import "../../../chunk-5Y7W3XR6.js";
-import "../../../chunk-4RFHUZXU.js";
+import "../../../chunk-OTR44OH6.js";
+import "../../../chunk-BULPAAD3.js";
 import "../../../chunk-PNZSGAB2.js";
+import "../../../chunk-VNBC3VXM.js";
+import "../../../chunk-BHZP6LOV.js";
 import "../../../chunk-SNQ3TOWP.js";
 import "../../../chunk-T4BIIU5E.js";
+import "../../../chunk-L3LZWWSX.js";
+import "../../../chunk-I6MVCB5A.js";
+import "../../../chunk-RHVN6NA7.js";
+import "../../../chunk-ZPL74UQN.js";
 import "../../../chunk-CO6LUM72.js";
-import "../../../chunk-BIO6F7YI.js";
 import "../../../chunk-OKXZ63IA.js";
+import "../../../chunk-MYQIQ27N.js";
 import "../../../chunk-GYGNEQSC.js";
 import "../../../chunk-U64T4YZE.js";
 import "../../../chunk-2E224ZSN.js";

package/dist/runtime/subsystems/jobs/jobs-domain.module.d.ts

@@ -20,17 +20,22 @@ import './pool-config.loader.js';
  */
 
 /**
- * Drizzle backend extensions surface. None are wired into the Drizzle
- * orchestrator yet — this is the **typed reservation** for the LISTEN/NOTIFY
- * + tunable poll-interval extensions called out in ADR-022. App code
- * passing these today is parsed but not yet dispatched; when the
- * Drizzle orchestrator grows the consumer hooks, opt-in code paths will
- * read directly from these fields.
+ * Drizzle backend extensions surface (LISTEN-NOTIFY-1 wires both fields).
+ *
+ * - `listenNotify` → provided as `JOBS_LISTEN_NOTIFY` so the orchestrator emits
+ *   in-tx `pg_notify` on enqueue, and threaded into each spawned `JobWorker`
+ *   (which holds the listener connection). Off by default.
+ * - `pollIntervalMs` → threaded into the spawned `JobWorker`'s
+ *   `JobWorkerOptions.pollIntervalMs` (the worker already honored this; it just
+ *   never received a config value). Default 1000.
+ *
+ * Both run ALONGSIDE interval polling — `listenNotify` only adds an early wake;
+ * polling remains the durability heartbeat.
  */
 interface DrizzleBackendExtensions {
     /** Use Postgres LISTEN/NOTIFY to wake the polling loop. Default false. */
     listenNotify?: boolean;
-    /** Polling interval when LISTEN/NOTIFY is off (ms). Default 1000. */
+    /** Polling interval (ms). Default 1000. */
     pollIntervalMs?: number;
 }
 interface JobsDomainModuleOptions {

package/dist/runtime/subsystems/jobs/jobs-domain.module.js

@@ -1,20 +1,21 @@
 import {
   JobsDomainModule
-} from "../../../chunk-O37C3YE6.js";
-import "../../../chunk-FBGHYQIZ.js";
-import "../../../chunk-RDVTWIYY.js";
-import "../../../chunk-L3LZWWSX.js";
+} from "../../../chunk-3RWMQC3K.js";
 import "../../../chunk-DV4RV2DC.js";
-import "../../../chunk-I6MVCB5A.js";
-import "../../../chunk-RHVN6NA7.js";
-import "../../../chunk-5Y7W3XR6.js";
-import "../../../chunk-4RFHUZXU.js";
+import "../../../chunk-OTR44OH6.js";
+import "../../../chunk-BULPAAD3.js";
 import "../../../chunk-PNZSGAB2.js";
+import "../../../chunk-VNBC3VXM.js";
+import "../../../chunk-BHZP6LOV.js";
 import "../../../chunk-SNQ3TOWP.js";
 import "../../../chunk-T4BIIU5E.js";
+import "../../../chunk-L3LZWWSX.js";
+import "../../../chunk-I6MVCB5A.js";
+import "../../../chunk-RHVN6NA7.js";
+import "../../../chunk-ZPL74UQN.js";
 import "../../../chunk-CO6LUM72.js";
-import "../../../chunk-BIO6F7YI.js";
 import "../../../chunk-OKXZ63IA.js";
+import "../../../chunk-MYQIQ27N.js";
 import "../../../chunk-GYGNEQSC.js";
 import "../../../chunk-U64T4YZE.js";
 import "../../../chunk-2E224ZSN.js";

package/dist/runtime/subsystems/jobs/jobs-domain.tokens.d.ts

@@ -16,5 +16,17 @@ declare const JOB_STEP_SERVICE: unique symbol;
  * targeted reads. See docs/specs/JOB-8.md.
  */
 declare const JOBS_MULTI_TENANT: unique symbol;
+/**
+ * LISTEN/NOTIFY wakeup opt-in flag (LISTEN-NOTIFY-1). Bound to
+ * `JobsDomainModule.forRoot({ extensions: { drizzle: { listenNotify } } })`,
+ * defaulting to `false`.
+ *
+ * When `true`, the Drizzle orchestrator emits an in-transaction
+ * `pg_notify(codegen_jobs_wake, <pool>)` on every `start()` INSERT so a worker
+ * with `listen_notify` enabled wakes the moment the enqueue commits. Off by
+ * default; polling is unchanged. The flag is read by `DrizzleJobOrchestrator`
+ * and by the bridge outbox drain hook (its wrapper `job_run` inserts notify too).
+ */
+declare const JOBS_LISTEN_NOTIFY: unique symbol;
 
-export { JOBS_MULTI_TENANT, JOB_ORCHESTRATOR, JOB_RUN_SERVICE, JOB_STEP_SERVICE };
+export { JOBS_LISTEN_NOTIFY, JOBS_MULTI_TENANT, JOB_ORCHESTRATOR, JOB_RUN_SERVICE, JOB_STEP_SERVICE };

package/dist/runtime/subsystems/jobs/jobs-domain.tokens.js

@@ -1,12 +1,14 @@
 import {
+  JOBS_LISTEN_NOTIFY,
   JOBS_MULTI_TENANT,
   JOB_ORCHESTRATOR,
   JOB_RUN_SERVICE,
   JOB_STEP_SERVICE
-} from "../../../chunk-BIO6F7YI.js";
+} from "../../../chunk-ZPL74UQN.js";
 import "../../../chunk-GYGNEQSC.js";
 import "../../../chunk-2E224ZSN.js";
 export {
+  JOBS_LISTEN_NOTIFY,
   JOBS_MULTI_TENANT,
   JOB_ORCHESTRATOR,
   JOB_RUN_SERVICE,

package/dist/runtime/subsystems/jobs/pg-notify.d.ts

@@ -0,0 +1,85 @@
+import { DrizzleClient } from '../../types/drizzle.js';
+import { DrizzleTransaction } from '../events/event-bus.protocol.js';
+import 'drizzle-orm/node-postgres';
+
+/** Channel the jobs worker LISTENs on; payload = pool name. */
+declare const JOBS_WAKE_CHANNEL = "codegen_jobs_wake";
+/** Channel the events drainer LISTENs on; payload = event pool (or ''). */
+declare const EVENTS_WAKE_CHANNEL = "codegen_events_wake";
+/**
+ * Emit an in-transaction `pg_notify`. Call with the SAME `tx`/client handle as
+ * the row write being announced so delivery is gated on commit. `payload` is a
+ * short plain string (a pool name); it is NOT JSON — the wake is a hint and the
+ * subsequent claim/drain query is authoritative. Channel names are framework
+ * constants (never user input), so the `set_config`-free literal-channel form is
+ * safe; the payload is bound as a parameter.
+ */
+declare function pgNotify(tx: DrizzleClient | DrizzleTransaction, channel: string, payload: string): Promise<void>;
+/** Minimal structural view of the `pg` Client/PoolClient surface we touch. */
+interface PgListenClient {
+    query(text: string): Promise<unknown>;
+    on(event: 'notification', cb: (msg: {
+        channel: string;
+        payload?: string;
+    }) => void): void;
+    on(event: 'error', cb: (err: Error) => void): void;
+    removeAllListeners?: (event?: string) => void;
+    release?: (err?: boolean) => void;
+    end?: () => Promise<void>;
+}
+/** Minimal structural view of the `pg` Pool's `connect()`. */
+interface PgPoolish {
+    connect(): Promise<PgListenClient>;
+}
+interface PgNotifyListenerOptions {
+    /** Channel to LISTEN on. */
+    channel: string;
+    /**
+     * The underlying `pg.Pool` — obtained from `drizzleClient.$client`. A
+     * dedicated `PoolClient` is checked out and held for the listener's lifetime
+     * (separate from the query pool so a slow query never delays a wake).
+     */
+    pool: PgPoolish;
+    /**
+     * Called for every notification on `channel`, with the raw payload string
+     * (`''` when Postgres delivers an empty payload). The owner decides whether
+     * the payload is relevant (e.g. "is this one of my pools?") and debounces its
+     * own claim cycle.
+     */
+    onNotify: (payload: string) => void;
+    /** Label used in log lines (e.g. 'jobs:interactive', 'events'). */
+    label: string;
+    backoffMinMs?: number;
+    backoffMaxMs?: number;
+}
+/**
+ * Holds a dedicated listener connection and forwards notifications to `onNotify`.
+ * Reconnects with capped exponential backoff on drop; logs the first failure +
+ * the recovery exactly once each so a flapping connection doesn't flood logs.
+ */
+declare class PgNotifyListener {
+    private readonly opts;
+    private readonly logger;
+    private client;
+    private stopped;
+    private reconnectTimer;
+    private backoffMs;
+    private readonly backoffMinMs;
+    private readonly backoffMaxMs;
+    /** WARN-once gate so a flapping listener doesn't spam the log. */
+    private warnedDown;
+    constructor(opts: PgNotifyListenerOptions);
+    /** Begin listening. Idempotent-ish: a second call while connected is a no-op. */
+    start(): Promise<void>;
+    /** Stop listening + release the connection. Safe to call repeatedly. */
+    stop(): Promise<void>;
+    private connect;
+    /** Connection dropped after being established → reconnect. */
+    private handleDrop;
+    /** Initial / reconnect `connect()` threw. */
+    private handleConnectFailure;
+    private scheduleReconnect;
+    private releaseClient;
+}
+
+export { EVENTS_WAKE_CHANNEL, JOBS_WAKE_CHANNEL, PgNotifyListener, type PgNotifyListenerOptions, pgNotify };

package/dist/runtime/subsystems/jobs/pg-notify.js

@@ -0,0 +1,14 @@
+import {
+  EVENTS_WAKE_CHANNEL,
+  JOBS_WAKE_CHANNEL,
+  PgNotifyListener,
+  pgNotify
+} from "../../../chunk-MYQIQ27N.js";
+import "../../../chunk-2E224ZSN.js";
+export {
+  EVENTS_WAKE_CHANNEL,
+  JOBS_WAKE_CHANNEL,
+  PgNotifyListener,
+  pgNotify
+};
+//# sourceMappingURL=pg-notify.js.map

package/dist/runtime/subsystems/jobs/pg-notify.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}