@pattern-stack/codegen 0.15.3 → 0.16.0

package/dist/src/index.js

@@ -46,17 +46,18 @@ import {
   validatePatternProject
 } from "../chunk-32DOFN3T.js";
 import "../chunk-KVOWSC5S.js";
-import "../chunk-GCYKMF22.js";
+import "../chunk-24WXSC3C.js";
 import "../chunk-EO2QPOKH.js";
 import "../chunk-PRWIX6UW.js";
-import "../chunk-DCCZB4UC.js";
+import "../chunk-XWBK3XJK.js";
 import "../chunk-AHV4GDYM.js";
-import "../chunk-SR7F3TJY.js";
+import "../chunk-YK5JEVLX.js";
 import "../chunk-SQDOBLBP.js";
 import "../chunk-3NMCDN7L.js";
 import "../chunk-4KNXX6TI.js";
 import "../chunk-3CJFPU6Q.js";
-import "../chunk-OGIZXGPY.js";
+import "../chunk-TDEHU73T.js";
+import "../chunk-S7C6TIIF.js";
 import "../chunk-MZ6GV4YF.js";
 import "../chunk-LG57S2SC.js";
 import "../chunk-HNWZFNKP.js";
@@ -64,7 +65,6 @@ import "../chunk-WWGYCIJX.js";
 import "../chunk-4MF3HKJA.js";
 import "../chunk-YLPAPPLW.js";
 import "../chunk-36U5UGIO.js";
-import "../chunk-S7C6TIIF.js";
 import "../chunk-U64T4YZE.js";
 import "../chunk-2E224ZSN.js";
 export {

package/package.json

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

package/runtime/subsystems/bridge/bridge-outbox-drain-hook.ts

@@ -47,6 +47,8 @@ import type {
 } from './bridge.protocol';
 import { BRIDGE_DELIVERY_JOB_TYPE } from './bridge-delivery-handler';
 import type { EventTypeName } from '../events/event-registry';
+import { JOBS_LISTEN_NOTIFY } from '../jobs/jobs-domain.tokens';
+import { JOBS_WAKE_CHANNEL, pgNotify } from '../jobs/pg-notify';
 
 /** Reserved pools the wrapper rows route into; ADR-022 / ADR-024. */
 const POOL_BY_DIRECTION: Record<string, string> = {
@@ -65,6 +67,15 @@ export class BridgeOutboxDrainHook implements IBridgeOutboxDrainHook {
     @Optional()
     @Inject(BRIDGE_REGISTRY)
     private readonly registry: BridgeRegistry = {},
+    // LISTEN-NOTIFY-1 — when true, the wrapper `job_run` insert below emits an
+    // in-tx `pg_notify(codegen_jobs_wake, <wrapperPool>)` so the reserved-pool
+    // worker wakes the instant the per-event drain tx commits — otherwise the
+    // bridge hop alone would still cost a full poll interval. `@Optional()`
+    // defaulting false so the hook keeps working when jobs isn't installed
+    // (bridge can drive non-jobs consumers) or in vendored/test wiring.
+    @Optional()
+    @Inject(JOBS_LISTEN_NOTIFY)
+    private readonly listenNotify: boolean = false,
   ) {}
 
   async processEvent(
@@ -209,6 +220,22 @@ export class BridgeOutboxDrainHook implements IBridgeOutboxDrainHook {
         continue;
       }
 
+      // LISTEN-NOTIFY-1 — the wrapper run is real and claimable; wake its
+      // reserved-pool worker on commit (D7). Same `tx` as the inserts above, so
+      // delivery is gated on the per-event drain tx committing. Best-effort: a
+      // notify failure is non-fatal (the reserved-pool worker still polls).
+      if (this.listenNotify) {
+        try {
+          await pgNotify(tx, JOBS_WAKE_CHANNEL, wrapperPool);
+        } catch (err) {
+          this.logger.warn(
+            `pg_notify(${JOBS_WAKE_CHANNEL}, ${wrapperPool}) failed for ` +
+              `wrapper run ${wrapperRunId}: ${(err as Error).message} ` +
+              `(non-fatal — the reserved-pool worker still polls).`,
+          );
+        }
+      }
+
       delivered++;
     }
 

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

@@ -48,6 +48,11 @@ import { EVENTS_MODULE_OPTIONS } from './events.tokens';
 import type { EventsModuleOptions } from './events.module';
 import { BRIDGE_OUTBOX_DRAIN_HOOK } from '../bridge/bridge.tokens';
 import type { IBridgeOutboxDrainHook } from '../bridge/bridge.protocol';
+import {
+  EVENTS_WAKE_CHANNEL,
+  PgNotifyListener,
+  pgNotify,
+} from '../jobs/pg-notify';
 
 /** How long to wait between polling cycles (ms). */
 const POLL_INTERVAL_MS = 1_000;
@@ -138,6 +143,14 @@ export class DrizzleEventBus implements IEventBus, IEventReadPort, OnModuleInit,
   private readonly handlers = new Map<string, Set<(event: DomainEvent) => Promise<void>>>();
   private readonly opts: EventsModuleOptions;
 
+  // LISTEN-NOTIFY-1 — dedicated wake listener + debounce state. `null` when
+  // `listenNotify` is off (the common case); polling is the only driver then.
+  private notifyListener: PgNotifyListener | null = null;
+  /** True while a wake-driven drain is in flight (debounce gate). */
+  private wakeDraining = false;
+  /** A notify arrived mid-drain → re-drain once when the current drain ends. */
+  private wakeRecheckPending = false;
+
   constructor(
     @Inject(DRIZZLE) private readonly db: DrizzleClient,
     @Optional() @Inject(EVENTS_MODULE_OPTIONS) opts?: EventsModuleOptions,
@@ -168,6 +181,28 @@ export class DrizzleEventBus implements IEventBus, IEventReadPort, OnModuleInit,
   async onModuleInit(): Promise<void> {
     this.polling = true;
     this.schedulePoll();
+
+    // LISTEN-NOTIFY-1 — start the wake listener ALONGSIDE the poll timer. A
+    // notify for one of this drainer's pools triggers an immediate drain; the
+    // interval timer above stays the durability heartbeat. Startup is
+    // fire-and-forget — a connect failure self-heals via the listener's backoff.
+    if (this.opts.listenNotify) {
+      const pool = (this.db as unknown as { $client?: unknown }).$client;
+      if (!pool || typeof (pool as { connect?: unknown }).connect !== 'function') {
+        this.logger.warn(
+          `listen_notify enabled but the Drizzle client exposes no pg Pool ` +
+            `($client.connect missing) — falling back to interval polling only.`,
+        );
+      } else {
+        this.notifyListener = new PgNotifyListener({
+          channel: EVENTS_WAKE_CHANNEL,
+          pool: pool as { connect(): Promise<never> },
+          label: 'events',
+          onNotify: (payload) => this.onWake(payload),
+        });
+        await this.notifyListener.start();
+      }
+    }
   }
 
   async onModuleDestroy(): Promise<void> {
@@ -176,6 +211,45 @@ export class DrizzleEventBus implements IEventBus, IEventReadPort, OnModuleInit,
       clearTimeout(this.pollTimer);
       this.pollTimer = null;
     }
+    if (this.notifyListener) {
+      try {
+        await this.notifyListener.stop();
+      } catch (err) {
+        this.logger.error(`notify listener stop failed: ${err}`);
+      }
+      this.notifyListener = null;
+    }
+  }
+
+  /**
+   * Wake handler — a `codegen_events_wake` notification arrived. A pool-filtered
+   * drainer (`opts.pools` set) ignores payloads naming a pool it doesn't own; an
+   * all-pools drainer wakes for any. Debounced: a notify mid-drain just flags a
+   * re-check so a burst collapses to at most one extra drain (D3).
+   */
+  private onWake(payload: string): void {
+    if (!this.polling) return;
+    const pools = this.opts.pools;
+    if (pools && pools.length > 0 && !pools.includes(payload)) return;
+    if (this.wakeDraining) {
+      this.wakeRecheckPending = true;
+      return;
+    }
+    void this.drainOnWake();
+  }
+
+  private async drainOnWake(): Promise<void> {
+    this.wakeDraining = true;
+    try {
+      do {
+        this.wakeRecheckPending = false;
+        await this.processBatch();
+      } while (this.wakeRecheckPending && this.polling);
+    } catch (err) {
+      this.logger.error(`wake drain error: ${err}`);
+    } finally {
+      this.wakeDraining = false;
+    }
   }
 
   // ============================================================================
@@ -185,16 +259,46 @@ export class DrizzleEventBus implements IEventBus, IEventReadPort, OnModuleInit,
   async publish(event: DomainEvent, tx?: DrizzleTransaction): Promise<void> {
     const client = (tx ?? this.db) as DrizzleClient;
     const multiTenant = this.opts.multiTenant ?? false;
-    await client.insert(domainEvents).values(toInsertValues(event, multiTenant));
+    const values = toInsertValues(event, multiTenant);
+    await client.insert(domainEvents).values(values);
+    // LISTEN-NOTIFY-1 — wake the drainer on commit (D2: emitted through the same
+    // `client`, so a rolled-back publish emits no phantom wake). The pool is the
+    // payload; the drainer re-runs its own pool-filtered claim on wake.
+    await this.emitWakeNotify(client, [values.pool]);
   }
 
   async publishMany(events: DomainEvent[], tx?: DrizzleTransaction): Promise<void> {
     if (events.length === 0) return;
     const client = (tx ?? this.db) as DrizzleClient;
     const multiTenant = this.opts.multiTenant ?? false;
-    await client
-      .insert(domainEvents)
-      .values(events.map((e) => toInsertValues(e, multiTenant)));
+    const valuesList = events.map((e) => toInsertValues(e, multiTenant));
+    await client.insert(domainEvents).values(valuesList);
+    // De-dup pools so a batch into one lane emits a single wake.
+    await this.emitWakeNotify(client, valuesList.map((v) => v.pool));
+  }
+
+  /**
+   * Emit one in-tx `pg_notify(codegen_events_wake, <pool>)` per distinct pool in
+   * the just-inserted batch. No-op unless `listenNotify` is on. Best-effort: a
+   * notify failure is non-fatal (interval polling still drains the rows), so we
+   * log + swallow rather than failing the publish.
+   */
+  private async emitWakeNotify(
+    client: DrizzleClient,
+    pools: Array<string | null>,
+  ): Promise<void> {
+    if (!this.opts.listenNotify) return;
+    const distinct = new Set(pools.map((p) => p ?? ''));
+    for (const pool of distinct) {
+      try {
+        await pgNotify(client, EVENTS_WAKE_CHANNEL, pool);
+      } catch (err) {
+        this.logger.warn(
+          `pg_notify(${EVENTS_WAKE_CHANNEL}, '${pool}') failed: ${err} ` +
+            `(non-fatal — interval polling still drains the outbox).`,
+        );
+      }
+    }
   }
 
   async findById(eventId: string): Promise<DomainEvent | null> {

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

@@ -96,6 +96,20 @@ export interface EventsModuleOptions {
    * cannot stall change-event propagation (see ADR-022).
    */
   pools?: string[];
+  /**
+   * LISTEN-NOTIFY-1 — when `true` (drizzle backend only), the drainer holds a
+   * dedicated listener connection and LISTENs on `codegen_events_wake`. Each
+   * `publish`/`publishMany` emits an in-tx `pg_notify(codegen_events_wake,
+   * <pool>)` so the drainer wakes the moment the publishing transaction commits,
+   * instead of waiting for the next poll tick. Polling continues unchanged as
+   * the fallback heartbeat; a lost notify degrades to poll latency, never to
+   * lost work. Defaults to `false`.
+   *
+   * Ignored by the memory + redis backends (memory dispatches inline; redis has
+   * its own fan-out). Requires a direct (non-transaction-pooler) connection —
+   * see the events/jobs config block re: PgBouncer.
+   */
+  listenNotify?: boolean;
   /**
    * Multi-tenancy opt-in (EVT-6).
    *

package/runtime/subsystems/jobs/index.ts

@@ -22,6 +22,7 @@ export {
   JOB_RUN_SERVICE,
   JOB_STEP_SERVICE,
   JOBS_MULTI_TENANT,
+  JOBS_LISTEN_NOTIFY,
 } from './jobs-domain.tokens';
 
 // ─── JOB-2: orchestrator protocol ──────────────────────────────────────────
@@ -111,6 +112,15 @@ export {
   buildStaleSweepQuery,
 } from './job-worker';
 export type { JobWorkerOptions } from './job-worker';
+
+// ─── LISTEN-NOTIFY-1: Postgres LISTEN/NOTIFY wakeups ───────────────────────
+export {
+  PgNotifyListener,
+  pgNotify,
+  JOBS_WAKE_CHANNEL,
+  EVENTS_WAKE_CHANNEL,
+} from './pg-notify';
+export type { PgNotifyListenerOptions } from './pg-notify';
 export {
   JobCollisionError,
   JobNotReplayableError,

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

@@ -7,7 +7,7 @@
  * No `job_queue` table, no executor port. See `docs/specs/JOB-3.md`.
  */
 import { randomUUID } from 'node:crypto';
-import { Inject, Injectable, Logger } from '@nestjs/common';
+import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
 import { and, desc, eq, gt, inArray, isNotNull, ne, notInArray, sql } from 'drizzle-orm';
 import type { DrizzleClient } from '../../types/drizzle';
 import type { DrizzleTransaction } from '../events/event-bus.protocol';
@@ -34,7 +34,8 @@ import {
   MissingTenantIdError,
 } from './jobs-errors';
 import { jobSteps } from './job-orchestration.schema';
-import { JOBS_MULTI_TENANT } from './jobs-domain.tokens';
+import { JOBS_MULTI_TENANT, JOBS_LISTEN_NOTIFY } from './jobs-domain.tokens';
+import { JOBS_WAKE_CHANNEL, pgNotify } from './pg-notify';
 
 /**
  * Terminal statuses — transitions into these are final. Used by `cancel`
@@ -83,6 +84,13 @@ export class DrizzleJobOrchestrator implements IJobOrchestrator {
   constructor(
     @Inject(DRIZZLE) private readonly db: DrizzleClient,
     @Inject(JOBS_MULTI_TENANT) private readonly multiTenant: boolean,
+    // LISTEN-NOTIFY-1 — when true, `start()` emits an in-tx
+    // `pg_notify(codegen_jobs_wake, <pool>)` so a `listen_notify` worker wakes
+    // on enqueue-commit. `@Optional()` defaulting to false so direct
+    // construction (integration tests not going through DI) keeps working.
+    @Optional()
+    @Inject(JOBS_LISTEN_NOTIFY)
+    private readonly listenNotify: boolean = false,
   ) {}
 
   /**
@@ -251,6 +259,25 @@ export class DrizzleJobOrchestrator implements IJobOrchestrator {
       })
       .returning();
 
+    // LISTEN-NOTIFY-1 — wake a listening worker the instant this enqueue
+    // commits. Emitted through the SAME `client` (the caller's tx when one was
+    // passed, else the pool) so delivery is gated on commit — a rolled-back
+    // enqueue emits no phantom wake (D2). The pool name is the payload; the
+    // worker re-runs its own pool-filtered claim query on wake. Polling is the
+    // fallback, so a failed notify is non-fatal: log + continue.
+    if (this.listenNotify) {
+      const wakePool = (inserted as JobRunRow).pool;
+      try {
+        await pgNotify(client, JOBS_WAKE_CHANNEL, wakePool);
+      } catch (err) {
+        this.logger.warn(
+          `pg_notify(${JOBS_WAKE_CHANNEL}, ${wakePool}) failed for run ` +
+            `${(inserted as JobRunRow).id}: ${(err as Error).message} ` +
+            `(non-fatal — interval polling still claims the run).`,
+        );
+      }
+    }
+
     return inserted as JobRun;
   }
 

package/runtime/subsystems/jobs/job-worker.module.ts

@@ -245,11 +245,22 @@ export class JobWorkerOrchestrator implements OnModuleInit, OnModuleDestroy {
       // naming; it MUST NOT be passed as the claim-filter pool, or the
       // worker will never match any row and the pool silently never
       // drains. See v0.4.4 fix notes.
+      // LISTEN-NOTIFY-1 — thread the drizzle extension knobs into each spawned
+      // worker. `pollIntervalMs` was always honored by JobWorker but never
+      // received a config value; `listenNotify` is the new wake opt-in. Only
+      // the drizzle backend reads these (bullmq has native wakeups + its own
+      // queue topology), so we ignore them under `backend: 'bullmq'`.
+      const drizzleExt =
+        backend === 'drizzle'
+          ? this.options.domainModuleExtensions?.drizzle
+          : undefined;
       const workerOptions: JobWorkerOptions = {
         pool: poolName,
         concurrency: def.concurrency,
         shutdownTimeoutMs:
           this.options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS,
+        pollIntervalMs: drizzleExt?.pollIntervalMs,
+        listenNotify: drizzleExt?.listenNotify,
       };
       const worker = this.options.workerFactory
         ? this.options.workerFactory(workerOptions)

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

@@ -37,6 +37,7 @@ import {
   type SpawnChildOptions,
   type StepOptions,
 } from './job-handler.base';
+import { JOBS_WAKE_CHANNEL, PgNotifyListener } from './pg-notify';
 
 /**
  * Options accepted by `JobWorker`. JOB-5 threads these through module
@@ -59,6 +60,14 @@ export 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;
 }
 
 // ADR-037: namespaced `Symbol.for(...)` (via `tokenKey()`) — matches by value
@@ -192,6 +201,15 @@ export class JobWorker implements OnModuleInit, OnModuleDestroy {
   private readonly staleThresholdMs: number;
   private readonly shutdownTimeoutMs: number;
 
+  // LISTEN-NOTIFY-1 — dedicated listener + debounce state. `null` when
+  // `listenNotify` is off (the common case); polling is the only driver then.
+  private readonly listenNotifyEnabled: boolean;
+  private notifyListener: PgNotifyListener | null = null;
+  /** True while a wake-driven claim cycle is in flight (debounce gate). */
+  private wakeDraining = false;
+  /** A notify arrived mid-cycle → re-check once when the cycle ends. */
+  private wakeRecheckPending = false;
+
   constructor(
     @Inject(DRIZZLE) private readonly db: DrizzleClient,
     @Inject(JOB_ORCHESTRATOR) private readonly orchestrator: IJobOrchestrator,
@@ -206,6 +224,7 @@ export class JobWorker implements OnModuleInit, OnModuleDestroy {
     this.staleThresholdMs = options.staleThresholdMs ?? DEFAULT_STALE_THRESHOLD_MS;
     this.shutdownTimeoutMs =
       options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
+    this.listenNotifyEnabled = options.listenNotify ?? false;
 
     this.sigtermHandler = () => {
       if (this.sigtermHandled) return;
@@ -227,6 +246,74 @@ export class JobWorker implements OnModuleInit, OnModuleDestroy {
       void this.sweepStaleClaims();
     }, this.staleSweeperIntervalMs);
     process.on('SIGTERM', this.sigtermHandler);
+
+    // LISTEN-NOTIFY-1 — start the wake listener ALONGSIDE the poll timer (never
+    // instead). A notify for this worker's pool drives an immediate claim cycle;
+    // the interval timer above stays the durability heartbeat. Listener startup
+    // is fire-and-forget: a connect failure self-heals via the listener's own
+    // backoff, and until it's up the poll loop is the sole driver.
+    if (this.listenNotifyEnabled) {
+      // The DRIZZLE provider wraps a `pg.Pool`, exposed by drizzle as `$client`.
+      const pool = (this.db as unknown as { $client?: unknown }).$client;
+      if (!pool || typeof (pool as { connect?: unknown }).connect !== 'function') {
+        this.logger.warn(
+          `listen_notify enabled but the Drizzle client exposes no pg Pool ` +
+            `($client.connect missing) — falling back to interval polling only.`,
+        );
+      } else {
+        this.notifyListener = new PgNotifyListener({
+          channel: JOBS_WAKE_CHANNEL,
+          pool: pool as { connect(): Promise<never> },
+          label: `jobs:${this.options.pool}`,
+          onNotify: (payload) => this.onWake(payload),
+        });
+        void this.notifyListener.start();
+      }
+    }
+  }
+
+  /**
+   * 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(payload: string): void {
+    if (this.shuttingDown) return;
+    if (payload !== this.options.pool) return;
+    if (this.wakeDraining) {
+      this.wakeRecheckPending = true;
+      return;
+    }
+    void this.drainOnWake();
+  }
+
+  /**
+   * 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 async drainOnWake(): Promise<void> {
+    this.wakeDraining = true;
+    try {
+      do {
+        this.wakeRecheckPending = false;
+        // Claim while there's capacity; pollAndProcess no-ops at the ceiling.
+        let progressed = true;
+        while (
+          progressed &&
+          !this.shuttingDown &&
+          this.inFlight.size < this.options.concurrency
+        ) {
+          const before = this.inFlight.size;
+          await this.pollAndProcess();
+          progressed = this.inFlight.size > before;
+        }
+      } while (this.wakeRecheckPending && !this.shuttingDown);
+    } finally {
+      this.wakeDraining = false;
+    }
   }
 
   async onModuleDestroy(): Promise<void> {
@@ -246,6 +333,17 @@ export class JobWorker implements OnModuleInit, OnModuleDestroy {
     }
     process.removeListener('SIGTERM', this.sigtermHandler);
 
+    // LISTEN-NOTIFY-1 — release the listener connection so the process can exit
+    // cleanly. Best-effort; a failure here doesn't block the drain.
+    if (this.notifyListener) {
+      try {
+        await this.notifyListener.stop();
+      } catch (err) {
+        this.logger.error(`notify listener stop failed: ${(err as Error).message}`);
+      }
+      this.notifyListener = null;
+    }
+
     await this.drainInFlight();
 
     // Any rows still `running` past timeout → release back to pending.

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

@@ -21,6 +21,7 @@ import {
   JOB_RUN_SERVICE,
   JOB_STEP_SERVICE,
   JOBS_MULTI_TENANT,
+  JOBS_LISTEN_NOTIFY,
 } from './jobs-domain.tokens';
 import { DrizzleJobOrchestrator } from './job-orchestrator.drizzle-backend';
 import { DrizzleJobRunService } from './job-run-service.drizzle-backend';
@@ -41,17 +42,22 @@ import {
 } from './bullmq.config';
 
 /**
- * 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.
  */
 export 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;
 }
 
@@ -79,6 +85,11 @@ export interface JobsDomainModuleOptions {
 export class JobsDomainModule {
   static forRoot(opts: JobsDomainModuleOptions): DynamicModule {
     const multiTenant = opts.multiTenant ?? false;
+    // LISTEN-NOTIFY-1 — drizzle-only extension. `listen_notify` is meaningless
+    // for memory (no DB) and redundant for bullmq (native wakeups); only the
+    // drizzle backend's orchestrator reads it.
+    const listenNotify =
+      opts.backend === 'drizzle' && Boolean(opts.extensions?.drizzle?.listenNotify);
 
     const providers: Provider[] = [
       // JOB-8 — boolean provider consumed by the four service-layer backends.
@@ -87,6 +98,9 @@ export class JobsDomainModule {
       // the value is `false`. See `jobs-domain.tokens.ts` for the claim-loop
       // cross-tenant-by-design decision.
       { provide: JOBS_MULTI_TENANT, useValue: multiTenant },
+      // LISTEN-NOTIFY-1 — always provided so the orchestrator's `@Inject`
+      // resolves; the orchestrator skips the `pg_notify` emit when `false`.
+      { provide: JOBS_LISTEN_NOTIFY, useValue: listenNotify },
     ];
 
     if (opts.backend === 'memory') {
@@ -144,6 +158,7 @@ export class JobsDomainModule {
       JOB_RUN_SERVICE,
       JOB_STEP_SERVICE,
       JOBS_MULTI_TENANT,
+      JOBS_LISTEN_NOTIFY,
     ];
     // BULLMQ-1 — only export the BullMQ tokens when they were actually
     // provided. Nest throws "exported but not provided" otherwise. Exported so

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

@@ -31,3 +31,16 @@ export const JOB_STEP_SERVICE = Symbol.for(tokenKey('jobs', 'step-service'));
  * targeted reads. See docs/specs/JOB-8.md.
  */
 export const JOBS_MULTI_TENANT = Symbol.for(tokenKey('jobs', 'multi-tenant'));
+
+/**
+ * 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).
+ */
+export const JOBS_LISTEN_NOTIFY = Symbol.for(tokenKey('jobs', 'listen-notify'));