@pattern-stack/codegen 0.15.3 → 0.16.1

package/runtime/subsystems/integration/webhook-change-source.ts

@@ -7,8 +7,11 @@
  * queue. The primitive owns:
  *
  *   - canonical `Change<T>.source = 'webhook'` stamping;
- *   - `dedupKey` derivation from the configured `webhook.eventIdField` on
- *     the emitted record;
+ *   - `dedupKey` derivation, preferring the `eventId` yielded alongside the
+ *     record by the queue iterator, and falling back to the configured
+ *     `webhook.eventIdField` on the emitted record when no `eventId` is yielded
+ *     (precedence: yielded `eventId` > `eventIdField` record extraction >
+ *     undefined `dedupKey`);
  *   - `externalId` derivation: the mapping entry whose `target === 'external_id'`
  *     names — via its `source` — the field on the emitted record that carries
  *     the canonical external id (mirrors `PollChangeSource`);
@@ -37,16 +40,16 @@
  * into either this primitive or the poll primitive.
  */
 
-import type { DetectionConfig } from './detection-config.schema';
+import type { DetectionConfig } from "./detection-config.schema";
 import type {
-  Change,
-  IChangeSource,
-  IntegrationSubscriptionView,
-} from './integration-change-source.protocol';
+	Change,
+	IChangeSource,
+	IntegrationSubscriptionView,
+} from "./integration-change-source.protocol";
 import type {
-  ChangeIterator,
-  ChangeMiddleware,
-} from './integration-middleware.protocol';
+	ChangeIterator,
+	ChangeMiddleware,
+} from "./integration-middleware.protocol";
 
 // ============================================================================
 // Cursor + queue callback shapes
@@ -66,16 +69,28 @@ export type WebhookCursor = unknown;
  * `userId` / `tenantId`.
  */
 export interface WebhookFetchContext {
-  readonly subscription: IntegrationSubscriptionView;
-  readonly cursor: WebhookCursor | null;
+	readonly subscription: IntegrationSubscriptionView;
+	readonly cursor: WebhookCursor | null;
 }
 
 /**
  * Consumer-supplied queue iterator. Returns an async iterable of
- * `{ record }` pairs — the consumer drains the inbound staging queue and
- * emits already-mapped canonical records `T`. The primitive stamps
- * `source: 'webhook'` and `dedupKey` from the record's configured
- * `webhook.eventIdField`; the consumer is the one who decided when a
+ * `{ record, eventId?, cursor? }` tuples — the consumer drains the inbound
+ * staging queue and emits already-mapped canonical records `T`. The primitive
+ * stamps `source: 'webhook'` and derives `dedupKey` with this precedence:
+ *
+ *   1. the yielded `eventId` (vendor delivery metadata — the queue is the
+ *      right channel for it: a vendor's event id should never need a field
+ *      on the vendor-neutral canonical record);
+ *   2. else the record field named by `webhook.eventIdField`, when configured;
+ *   3. else `undefined`.
+ *
+ * Yielding `eventId` is the safe channel when one canonical record identity
+ * (the `external_id`) can recur across distinct vendor events in a single
+ * drain batch — e.g. a message create and its later edit share an
+ * `external_id` but are different events. Reading dedup identity off the
+ * record (`eventIdField`) collapses those into one `dedupKey`; the yielded
+ * `eventId` keeps them distinct. The consumer is the one who decided when a
  * staging row is "ready" to drain.
  *
  * Webhook mode has no per-record cursor advance — the staging-row drain
@@ -84,33 +99,33 @@ export interface WebhookFetchContext {
  * is whatever the consumer chooses to surface, if anything.
  */
 export type WebhookFetchCallback<T> = (
-  ctx: WebhookFetchContext,
-) => AsyncIterable<{ record: T; cursor?: WebhookCursor }>;
+	ctx: WebhookFetchContext,
+) => AsyncIterable<{ record: T; eventId?: string; cursor?: WebhookCursor }>;
 
 // ============================================================================
 // Constructor options
 // ============================================================================
 
 export interface WebhookChangeSourceOptions<T> {
-  /** Consumer-supplied inbound queue iterator. */
-  readonly queue: WebhookFetchCallback<T>;
-  /**
-   * Parsed detection config. MUST be `mode: 'webhook'`; the constructor
-   * throws if a poll config is supplied. Codegen-emitted factories call
-   * `DetectionConfigSchema.parse(...)` upstream so this is a safety net,
-   * not the primary validation point.
-   */
-  readonly config: DetectionConfig;
-  /**
-   * Optional middleware chain. Same shape and composition rules as
-   * `PollChangeSource` — first element is the outermost layer.
-   */
-  readonly middlewares?: ReadonlyArray<ChangeMiddleware<T>>;
-  /**
-   * Optional human label for run logs (e.g. `'stripe-webhook-charge'`).
-   * Defaults to a derived label based on the mapping at construction.
-   */
-  readonly label?: string;
+	/** Consumer-supplied inbound queue iterator. */
+	readonly queue: WebhookFetchCallback<T>;
+	/**
+	 * Parsed detection config. MUST be `mode: 'webhook'`; the constructor
+	 * throws if a poll config is supplied. Codegen-emitted factories call
+	 * `DetectionConfigSchema.parse(...)` upstream so this is a safety net,
+	 * not the primary validation point.
+	 */
+	readonly config: DetectionConfig;
+	/**
+	 * Optional middleware chain. Same shape and composition rules as
+	 * `PollChangeSource` — first element is the outermost layer.
+	 */
+	readonly middlewares?: ReadonlyArray<ChangeMiddleware<T>>;
+	/**
+	 * Optional human label for run logs (e.g. `'stripe-webhook-charge'`).
+	 * Defaults to a derived label based on the mapping at construction.
+	 */
+	readonly label?: string;
 }
 
 // ============================================================================
@@ -118,100 +133,139 @@ export interface WebhookChangeSourceOptions<T> {
 // ============================================================================
 
 export class WebhookChangeSource<T> implements IChangeSource<T> {
-  public readonly label: string;
-
-  private readonly queue: WebhookFetchCallback<T>;
-  private readonly externalIdSourceField: string;
-  private readonly eventIdSourceField: string;
-  private readonly composed: ChangeIterator<T>;
-
-  constructor(opts: WebhookChangeSourceOptions<T>) {
-    if (opts.config.mode !== 'webhook') {
-      throw new Error(
-        `WebhookChangeSource requires DetectionConfig.mode === 'webhook'; got '${(opts.config as { mode: string }).mode}'`,
-      );
-    }
-    const config = opts.config;
-
-    // Field mapping: locate the entry whose canonical `target` is `external_id`
-    // — mirrors the poll primitive's contract. Adapters emit records
-    // already-mapped; the primitive needs to know which key on T carries the
-    // external id so it can stamp `Change.externalId`. That key is the
-    // mapping's `source` (the field on the emitted record), NOT its `target`
-    // (the canonical column) — they differ whenever the canonical record is
-    // vendor-neutral camelCase (e.g. `source: 'externalId'` → `target: 'external_id'`).
-    const externalIdMapping = config.mapping.find(
-      (m) => m.target === 'external_id',
-    );
-    if (!externalIdMapping) {
-      throw new Error(
-        "WebhookChangeSource: DetectionConfig.mapping must include an entry with target 'external_id' so emitted Change<T>.externalId can be populated",
-      );
-    }
-    this.externalIdSourceField = externalIdMapping.source;
-    this.eventIdSourceField = config.webhook.eventIdField;
-
-    this.queue = opts.queue;
-
-    this.label =
-      opts.label ?? `webhook-change-source:${externalIdMapping.source}`;
-
-    // Compose middleware chain — same shape as PollChangeSource.
-    const inner: ChangeIterator<T> = (sub, cur) => this.fetch(sub, cur);
-    const middlewares = opts.middlewares ?? [];
-    this.composed = middlewares.reduceRight<ChangeIterator<T>>(
-      (next, mw) => mw(next),
-      inner,
-    );
-  }
-
-  listChanges(
-    subscription: IntegrationSubscriptionView,
-    cursor: unknown | null,
-  ): AsyncIterable<Change<T>> {
-    return this.composed(subscription, cursor);
-  }
-
-  private async *fetch(
-    subscription: IntegrationSubscriptionView,
-    cursor: unknown | null,
-  ): AsyncIterable<Change<T>> {
-    const ctx: WebhookFetchContext = {
-      subscription,
-      cursor: cursor as WebhookCursor | null,
-    };
-
-    for await (const { record, cursor: nextCursor } of this.queue(ctx)) {
-      const externalIdRaw = (record as Record<string, unknown>)[
-        this.externalIdSourceField
-      ];
-      if (typeof externalIdRaw !== 'string' || externalIdRaw.length === 0) {
-        throw new Error(
-          `WebhookChangeSource: record missing string '${this.externalIdSourceField}' — emitted records MUST carry the canonical external id keyed by the mapping source`,
-        );
-      }
-      const eventIdRaw = (record as Record<string, unknown>)[
-        this.eventIdSourceField
-      ];
-      if (typeof eventIdRaw !== 'string' || eventIdRaw.length === 0) {
-        throw new Error(
-          `WebhookChangeSource: record missing string '${this.eventIdSourceField}' — webhook records MUST carry the event id (DetectionConfig.webhook.eventIdField) so Change<T>.dedupKey can be populated`,
-        );
-      }
-
-      const change: Change<T> = {
-        externalId: externalIdRaw,
-        // Webhook mode cannot distinguish create vs. update vs. delete on
-        // its own — the orchestrator's diff stage handles classification.
-        // Tombstone / soft-delete detection is consumer-driven (same as
-        // poll mode — see ADR-033).
-        operation: 'updated',
-        record,
-        cursor: nextCursor ?? null,
-        source: 'webhook',
-        dedupKey: eventIdRaw,
-      };
-      yield change;
-    }
-  }
+	public readonly label: string;
+
+	private readonly queue: WebhookFetchCallback<T>;
+	private readonly externalIdSourceField: string;
+	/**
+	 * Record field carrying the event id, when `webhook.eventIdField` is
+	 * configured. Used only as the fallback when the queue iterator does NOT
+	 * yield an `eventId` — see {@link WebhookFetchCallback} for the precedence.
+	 */
+	private readonly eventIdSourceField: string | undefined;
+	private readonly composed: ChangeIterator<T>;
+
+	constructor(opts: WebhookChangeSourceOptions<T>) {
+		if (opts.config.mode !== "webhook") {
+			throw new Error(
+				`WebhookChangeSource requires DetectionConfig.mode === 'webhook'; got '${(opts.config as { mode: string }).mode}'`,
+			);
+		}
+		const config = opts.config;
+
+		// Field mapping: locate the entry whose canonical `target` is `external_id`
+		// — mirrors the poll primitive's contract. Adapters emit records
+		// already-mapped; the primitive needs to know which key on T carries the
+		// external id so it can stamp `Change.externalId`. That key is the
+		// mapping's `source` (the field on the emitted record), NOT its `target`
+		// (the canonical column) — they differ whenever the canonical record is
+		// vendor-neutral camelCase (e.g. `source: 'externalId'` → `target: 'external_id'`).
+		const externalIdMapping = config.mapping.find(
+			(m) => m.target === "external_id",
+		);
+		if (!externalIdMapping) {
+			throw new Error(
+				"WebhookChangeSource: DetectionConfig.mapping must include an entry with target 'external_id' so emitted Change<T>.externalId can be populated",
+			);
+		}
+		this.externalIdSourceField = externalIdMapping.source;
+		this.eventIdSourceField = config.webhook.eventIdField;
+		// `eventIdField` is optional (a callback that always yields `eventId` need
+		// not declare one); `undefined` here just disables the fallback extraction.
+
+		this.queue = opts.queue;
+
+		this.label =
+			opts.label ?? `webhook-change-source:${externalIdMapping.source}`;
+
+		// Compose middleware chain — same shape as PollChangeSource.
+		const inner: ChangeIterator<T> = (sub, cur) => this.fetch(sub, cur);
+		const middlewares = opts.middlewares ?? [];
+		this.composed = middlewares.reduceRight<ChangeIterator<T>>(
+			(next, mw) => mw(next),
+			inner,
+		);
+	}
+
+	listChanges(
+		subscription: IntegrationSubscriptionView,
+		cursor: unknown | null,
+	): AsyncIterable<Change<T>> {
+		return this.composed(subscription, cursor);
+	}
+
+	private async *fetch(
+		subscription: IntegrationSubscriptionView,
+		cursor: unknown | null,
+	): AsyncIterable<Change<T>> {
+		const ctx: WebhookFetchContext = {
+			subscription,
+			cursor: cursor as WebhookCursor | null,
+		};
+
+		for await (const {
+			record,
+			eventId: yieldedEventId,
+			cursor: nextCursor,
+		} of this.queue(ctx)) {
+			const externalIdRaw = (record as Record<string, unknown>)[
+				this.externalIdSourceField
+			];
+			if (typeof externalIdRaw !== "string" || externalIdRaw.length === 0) {
+				throw new Error(
+					`WebhookChangeSource: record missing string '${this.externalIdSourceField}' — emitted records MUST carry the canonical external id keyed by the mapping source`,
+				);
+			}
+
+			// dedupKey precedence: yielded `eventId` > `eventIdField` record
+			// extraction > undefined. The yielded id is vendor delivery metadata
+			// (the right channel for it), and keeps distinct vendor events for the
+			// same `external_id` (e.g. a message and its edit) from collapsing to
+			// one dedupKey — which a record-field extraction would do.
+			const dedupKey = this.deriveDedupKey(yieldedEventId, record);
+
+			const change: Change<T> = {
+				externalId: externalIdRaw,
+				// Webhook mode cannot distinguish create vs. update vs. delete on
+				// its own — the orchestrator's diff stage handles classification.
+				// Tombstone / soft-delete detection is consumer-driven (same as
+				// poll mode — see ADR-033).
+				operation: "updated",
+				record,
+				cursor: nextCursor ?? null,
+				source: "webhook",
+				dedupKey,
+			};
+			yield change;
+		}
+	}
+
+	/**
+	 * Resolve `Change<T>.dedupKey` with the precedence: yielded `eventId` >
+	 * `webhook.eventIdField` record extraction > `undefined`. A non-empty
+	 * yielded `eventId` always wins; otherwise the configured field is read off
+	 * the record (and must be a non-empty string when the field is configured);
+	 * with neither, `dedupKey` is `undefined` (the orchestrator then has no
+	 * delivery-level dedup signal for this change).
+	 */
+	private deriveDedupKey(
+		yieldedEventId: string | undefined,
+		record: T,
+	): string | undefined {
+		if (yieldedEventId !== undefined && yieldedEventId.length > 0) {
+			return yieldedEventId;
+		}
+		if (this.eventIdSourceField === undefined) {
+			return undefined;
+		}
+		const eventIdRaw = (record as Record<string, unknown>)[
+			this.eventIdSourceField
+		];
+		if (typeof eventIdRaw !== "string" || eventIdRaw.length === 0) {
+			throw new Error(
+				`WebhookChangeSource: record missing string '${this.eventIdSourceField}' — a webhook record MUST carry the event id (DetectionConfig.webhook.eventIdField) so Change<T>.dedupKey can be populated, unless the queue iterator yields an 'eventId' alongside the record`,
+			);
+		}
+		return eventIdRaw;
+	}
 }

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.