@pattern-stack/codegen 0.17.0 → 0.17.2

package/dist/src/index.js

@@ -46,25 +46,25 @@ import {
   validatePatternProject
 } from "../chunk-IOQMMH6C.js";
 import "../chunk-KVOWSC5S.js";
-import "../chunk-P3AYBRP6.js";
-import "../chunk-PRWIX6UW.js";
-import "../chunk-SR7F3TJY.js";
+import "../chunk-ATVGYF3D.js";
+import "../chunk-YK5JEVLX.js";
 import "../chunk-EO2QPOKH.js";
-import "../chunk-SQDOBLBP.js";
-import "../chunk-OGIZXGPY.js";
-import "../chunk-LG57S2SC.js";
-import "../chunk-DCCZB4UC.js";
-import "../chunk-MZ6GV4YF.js";
-import "../chunk-HNWZFNKP.js";
+import "../chunk-PRWIX6UW.js";
+import "../chunk-XWBK3XJK.js";
 import "../chunk-AHV4GDYM.js";
-import "../chunk-43SBT72G.js";
-import "../chunk-4MF3HKJA.js";
-import "../chunk-TIZXQU26.js";
-import "../chunk-36U5UGIO.js";
+import "../chunk-SQDOBLBP.js";
+import "../chunk-JEINYUJH.js";
 import "../chunk-5TK7MEN4.js";
 import "../chunk-4KNXX6TI.js";
 import "../chunk-3CJFPU6Q.js";
+import "../chunk-TDEHU73T.js";
 import "../chunk-S7C6TIIF.js";
+import "../chunk-MZ6GV4YF.js";
+import "../chunk-LG57S2SC.js";
+import "../chunk-HNWZFNKP.js";
+import "../chunk-I6UXRJ3Q.js";
+import "../chunk-TIZXQU26.js";
+import "../chunk-4MF3HKJA.js";
 import "../chunk-U64T4YZE.js";
 import "../chunk-2E224ZSN.js";
 export {

package/package.json

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

package/runtime/subsystems/integration/deep-equal.differ.ts

@@ -12,7 +12,11 @@
  *      `id`, `createdAt`, `updatedAt`, `deletedAt`, `type`,
  *      `lastModifiedAt`, `fields`, `providerMetadata`
  *    (`fields` is the EAV bag — it's diffed by the sink's EAV dual-write
- *    path, not at the canonical-record layer.)
+ *    path, not at the canonical-record layer.) Consumers augment the list via
+ *    `options.ignore` and — when a default is domain data for their entity —
+ *    REMOVE a default via `options.unignore` (e.g. an entity whose
+ *    `deletedAt` is a vendor-observed retraction tombstone, not row metadata;
+ *    see `DeepEqualDifferOptions.unignore`).
  *
  * 2. **`providerChangedFields` hint (CDC)** — when present, restricts the
  *    comparison to the hinted field set. The hint is advisory; fields in
@@ -75,6 +79,26 @@ export interface DeepEqualDifferOptions {
    * merged (not replaced) with `DEFAULT_IGNORE_FIELDS`.
    */
   readonly ignore?: readonly string[];
+
+  /**
+   * Field names to REMOVE from the default ignore list — the inverse of
+   * `ignore`. Use this to declare that a normally-metadata column is in fact
+   * DOMAIN DATA for this entity and must register as a field change.
+   *
+   * The canonical case (swe-brain ADR-0008 §1, the gap this knob closes):
+   * `deletedAt` is in `DEFAULT_IGNORE_FIELDS` because most sinks stamp it as
+   * row metadata sinks own unconditionally. But an entity with
+   * `softDelete: false` and a domain-owned `deleted_at` carries the
+   * vendor-observed retraction tombstone ON the canonical record (a Slack
+   * `message_deleted` → `deletedAt`). Without un-ignoring it, the tombstone
+   * overlay diffs to `'noop'`, the upsert is skipped, and `deleted_at` never
+   * lands. `unignore: ['deletedAt']` makes the differ treat it as domain data.
+   *
+   * Applied AFTER `ignore` is merged, so `unignore` wins on a field listed in
+   * both. Subtracting a field not in the (merged) ignore set is a harmless
+   * no-op. Does not touch `DEFAULT_IGNORE_FIELDS` for any other instance.
+   */
+  readonly unignore?: readonly string[];
 }
 
 @Injectable()
@@ -84,11 +108,16 @@ export class DeepEqualDiffer<T extends Record<string, unknown>>
   private readonly ignore: ReadonlySet<string>;
 
   constructor(opts: DeepEqualDifferOptions = {}) {
-    if (opts.ignore && opts.ignore.length > 0) {
-      this.ignore = new Set([...DEFAULT_IGNORE_FIELDS, ...opts.ignore]);
-    } else {
-      this.ignore = DEFAULT_IGNORE_FIELDS;
+    const merged = new Set<string>(DEFAULT_IGNORE_FIELDS);
+    if (opts.ignore) {
+      for (const field of opts.ignore) merged.add(field);
+    }
+    // `unignore` is subtracted last so it wins over a field that also appears
+    // in `ignore` or the defaults — "this column is domain data here."
+    if (opts.unignore) {
+      for (const field of opts.unignore) merged.delete(field);
     }
+    this.ignore = merged;
   }
 
   diff(

package/runtime/subsystems/integration/integration.module.ts

@@ -73,7 +73,7 @@ import { MemoryCursorStore } from './integration-cursor-store.memory-backend';
 import { MemoryRunRecorder } from './integration-run-recorder.memory-backend';
 import { PostgresCursorStore } from './integration-cursor-store.drizzle-backend';
 import { DrizzleIntegrationRunRecorder } from './integration-run-recorder.drizzle-backend';
-import { DeepEqualDiffer } from './deep-equal.differ';
+import { DeepEqualDiffer, type DeepEqualDifferOptions } from './deep-equal.differ';
 
 export interface IntegrationModuleOptions {
   /**
@@ -100,6 +100,24 @@ export interface IntegrationModuleOptions {
    * Defaults to `false`.
    */
   multiTenant?: boolean;
+
+  /**
+   * Default-differ configuration (DIFFER-UNIGNORE, 0.17.1). Threaded into the
+   * `DeepEqualDiffer` bound to `INTEGRATION_FIELD_DIFFER`. Omit for the
+   * historical behaviour (the default ignore list, unchanged).
+   *
+   * Mirrors `DeepEqualDifferOptions`:
+   *   - `ignore`   — extra field names to ignore (merged with the defaults).
+   *   - `unignore` — default-ignored field names to RE-include as domain data
+   *     (e.g. `['deletedAt']` for an entity whose `deletedAt` is a
+   *     vendor-observed retraction tombstone, not row metadata — swe-brain
+   *     ADR-0008 §1). Subtracted after the merge, so it wins.
+   *
+   * A feature module that binds its own `IFieldDiffer<T>` to
+   * `INTEGRATION_FIELD_DIFFER` overrides this entirely (per-entity escape hatch
+   * unchanged).
+   */
+  differ?: DeepEqualDifferOptions;
 }
 
 @Module({})
@@ -112,7 +130,13 @@ export class IntegrationModule {
       { provide: INTEGRATION_MULTI_TENANT, useValue: multiTenant },
       // Default differ — consumers can override by binding a different
       // `IFieldDiffer<T>` to `INTEGRATION_FIELD_DIFFER` in their feature module.
-      { provide: INTEGRATION_FIELD_DIFFER, useValue: new DeepEqualDiffer() },
+      // DIFFER-UNIGNORE: `options.differ` (ignore/unignore) is threaded here so
+      // a consumer can declare a default-ignored column (e.g. `deletedAt`) as
+      // domain data for their entities without binding a bespoke differ.
+      {
+        provide: INTEGRATION_FIELD_DIFFER,
+        useValue: new DeepEqualDiffer(options.differ ?? {}),
+      },
     ];
 
     const backendProviders: Provider[] =

package/runtime/subsystems/jobs/job-handler.base.ts

@@ -42,13 +42,33 @@ export interface RetryPolicy {
   nonRetryableErrors?: string[];
 }
 
+/**
+ * Concurrency lane key (JOB-FN-KEY, 0.16.2).
+ *
+ * Two authoring forms, both honored end-to-end (the typed function form was
+ * previously dropped to `null` at registration — see `upsertJobRows` — so
+ * `collisionMode` silently never engaged):
+ *
+ *   - **`string`** — a `{{field}}` template evaluated against the start
+ *     payload by `evaluateKeyTemplate` (single-key substitution, no dotted
+ *     paths). Persisted verbatim to `job.concurrency_key_template`.
+ *   - **`(input) => string`** — an arbitrary function of the input. Persisted
+ *     as the `FN_KEY_SENTINEL` marker so the definition-hash gate stays stable
+ *     and the collision path engages; `start()` re-resolves the live function
+ *     from `JOB_HANDLER_REGISTRY` and evaluates it against the payload.
+ *
+ * Both forms produce a per-lane key; same key + in-flight incumbent ⇒
+ * `collisionMode` ('queue' | 'reject' | 'replace') decides.
+ */
+export type JobKeySelector<TInput> = string | ((input: TInput) => string);
+
 export interface ConcurrencyPolicy<TInput> {
-  key: (input: TInput) => string;
+  key: JobKeySelector<TInput>;
   collisionMode: 'queue' | 'reject' | 'replace';
 }
 
 export interface DedupePolicy<TInput> {
-  key: (input: TInput) => string;
+  key: JobKeySelector<TInput>;
   windowMs: number;
 }
 
@@ -245,3 +265,96 @@ export namespace HandlerRegistry {
     return JOB_HANDLER_REGISTRY.get(type);
   }
 }
+
+// ─── Key resolution (JOB-FN-KEY, 0.16.2) ────────────────────────────────────
+
+/**
+ * Sentinel persisted to `job.concurrency_key_template` / `dedupe_key_template`
+ * when the authored `key` is a function rather than a `{{field}}` template.
+ *
+ * Why a sentinel (not `null`): the collision/dedupe paths in both backends gate
+ * on `definition.concurrencyKeyTemplate != null`. A function key persisted as
+ * `null` (the pre-0.16.2 bug) left those columns empty, so `collisionMode` /
+ * the dedupe window never engaged — the job ran with NO key. A stable sentinel
+ * keeps the column non-null (path engages) AND keeps the definition-hash gate
+ * (`upsertJobRows`' `IS DISTINCT FROM` clause) stable across boots, since the
+ * function identity itself can't be hashed. `start()` detects the sentinel and
+ * re-resolves the live function from `JOB_HANDLER_REGISTRY`.
+ *
+ * Chosen as an angle-bracketed token so it can never collide with a real
+ * `{{field}}` template (which never contains a literal `<`).
+ */
+export const FN_KEY_SENTINEL = '<fn>';
+
+/**
+ * Registration-time projection: collapse an authored `JobKeySelector` to the
+ * string stored in the `job` definition row. A string template is stored
+ * verbatim; a function is stored as `FN_KEY_SENTINEL`; absence stays `null`.
+ */
+export function keySelectorToTemplate(
+  key: JobKeySelector<unknown> | undefined,
+): string | null {
+  if (typeof key === 'string') return key;
+  if (typeof key === 'function') return FN_KEY_SENTINEL;
+  return null;
+}
+
+/** Which meta policy a key belongs to — selects the live fn at `start()`. */
+export type KeyKind = 'concurrency' | 'dedupe';
+
+/**
+ * `start()`-time resolution shared by every backend. Turns the persisted
+ * template column into the concrete per-run key for the given payload.
+ *
+ *   - `template == null` → `null` (no key; caller skips the collision/dedupe path).
+ *   - `template === FN_KEY_SENTINEL` → look the live `@JobHandler` meta up in
+ *     `JOB_HANDLER_REGISTRY`, pull `meta[kind].key`, and invoke it against the
+ *     payload. The registry is the runtime source of truth (the worker already
+ *     resolves handler classes the same way), so the function survives the DB
+ *     round-trip even though it can't be persisted.
+ *   - otherwise → a `{{field}}` template, evaluated via the injected
+ *     `evaluateTemplate` (each backend passes its own copy to avoid a runtime
+ *     import cycle).
+ *
+ * Throws `JobKeyFunctionUnavailableError` if the sentinel is present but no
+ * live function can be found (e.g. the registry was reset, or a function key
+ * was persisted by a newer build and read by an older one). Failing loud beats
+ * silently degrading to no-key — the exact regression this fix exists to kill.
+ */
+export function resolveJobKey(
+  kind: KeyKind,
+  type: string,
+  template: string | null,
+  payload: Record<string, unknown>,
+  evaluateTemplate: (template: string, payload: Record<string, unknown>) => string,
+): string | null {
+  if (template == null) return null;
+  if (template !== FN_KEY_SENTINEL) return evaluateTemplate(template, payload);
+
+  const meta = JOB_HANDLER_REGISTRY.get(type)?.meta;
+  const key = (meta?.[kind] as { key?: unknown } | undefined)?.key;
+  if (typeof key !== 'function') {
+    throw new JobKeyFunctionUnavailableError(type, kind);
+  }
+  return (key as (input: unknown) => string)(payload);
+}
+
+/**
+ * Raised when a `${FN_KEY_SENTINEL}` template is read but the live function
+ * key is missing from `JOB_HANDLER_REGISTRY`. Kept here (not in `jobs-errors`)
+ * so `job-handler.base` stays import-cycle-free.
+ */
+export class JobKeyFunctionUnavailableError extends Error {
+  constructor(
+    readonly jobType: string,
+    readonly kind: KeyKind,
+  ) {
+    super(
+      `[jobs] ${kind} key for job '${jobType}' was persisted as a function ` +
+        `sentinel ('${FN_KEY_SENTINEL}') but no live function is registered ` +
+        `for it. The @JobHandler must be imported before start() so its meta ` +
+        `is in JOB_HANDLER_REGISTRY.`,
+    );
+    this.name = 'JobKeyFunctionUnavailableError';
+  }
+}

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

@@ -36,6 +36,11 @@ import {
 import { jobSteps } from './job-orchestration.schema';
 import { JOBS_MULTI_TENANT, JOBS_LISTEN_NOTIFY } from './jobs-domain.tokens';
 import { JOBS_WAKE_CHANNEL, pgNotify } from './pg-notify';
+import {
+  keySelectorToTemplate,
+  resolveJobKey,
+  type JobKeySelector,
+} from './job-handler.base';
 
 /**
  * Terminal statuses — transitions into these are final. Used by `cancel`
@@ -140,9 +145,17 @@ export class DrizzleJobOrchestrator implements IJobOrchestrator {
     if (!def) throw new JobTypeNotFoundError(type);
     const definition = def as JobDefinitionRow;
 
-    // 1b. Dedupe check.
+    // 1b. Dedupe check. JOB-FN-KEY: `resolveJobKey` honors both the `{{field}}`
+    // template AND a function key persisted as `FN_KEY_SENTINEL` (re-resolved
+    // live from JOB_HANDLER_REGISTRY).
     if (definition.dedupeKeyTemplate && definition.dedupeWindowMs) {
-      const dedupeKey = evaluateKeyTemplate(definition.dedupeKeyTemplate, payload);
+      const dedupeKey = resolveJobKey(
+        'dedupe',
+        type,
+        definition.dedupeKeyTemplate,
+        payload,
+        evaluateKeyTemplate,
+      ) as string;
       const windowStart = new Date(Date.now() - definition.dedupeWindowMs);
       const existing = await client
         .select()
@@ -166,10 +179,15 @@ export class DrizzleJobOrchestrator implements IJobOrchestrator {
     // 1c. Concurrency collision check.
     let concurrencyKey: string | null = null;
     if (definition.concurrencyKeyTemplate) {
-      concurrencyKey = evaluateKeyTemplate(
+      // Non-null cast: the branch guard proves the template is present, so the
+      // resolver never returns null here (it only nulls on a null template).
+      concurrencyKey = resolveJobKey(
+        'concurrency',
+        type,
         definition.concurrencyKeyTemplate,
         payload,
-      );
+        evaluateKeyTemplate,
+      ) as string;
       const inFlight = await client
         .select()
         .from(jobRuns)
@@ -223,10 +241,13 @@ export class DrizzleJobOrchestrator implements IJobOrchestrator {
       rootRunId = parent.rootRunId;
     }
 
-    const dedupeKey =
-      definition.dedupeKeyTemplate
-        ? evaluateKeyTemplate(definition.dedupeKeyTemplate, payload)
-        : null;
+    const dedupeKey = resolveJobKey(
+      'dedupe',
+      type,
+      definition.dedupeKeyTemplate,
+      payload,
+      evaluateKeyTemplate,
+    );
 
     const [inserted] = await client
       .insert(jobRuns)
@@ -460,17 +481,23 @@ export class DrizzleJobOrchestrator implements IJobOrchestrator {
         backoff: 'fixed' as const,
         baseMs: 0,
       };
-      const concurrencyKeyTemplate =
-        (meta.concurrency as { key?: unknown } | undefined)?.key;
-      const concurrencyKeyTemplateStr =
-        typeof concurrencyKeyTemplate === 'string' ? concurrencyKeyTemplate : null;
+      // JOB-FN-KEY (0.16.2): both authored key forms are honored. A `{{field}}`
+      // string is persisted verbatim; a function is persisted as
+      // `FN_KEY_SENTINEL` (non-null so the collision/dedupe path engages, and
+      // hash-stable so the definition-hash gate doesn't churn on every boot —
+      // the function identity can't be hashed). `start()` re-resolves the live
+      // function from `JOB_HANDLER_REGISTRY`. The pre-0.16.2 `typeof === string
+      // ? … : null` dropped function keys to null, so `collisionMode` silently
+      // never engaged.
+      const concurrencyKeyTemplateStr = keySelectorToTemplate(
+        meta.concurrency?.key as JobKeySelector<unknown> | undefined,
+      );
       const collisionMode =
         (meta.concurrency?.collisionMode as JobDefinitionRow['collisionMode']) ??
         'queue';
-      const dedupeKeyTemplate =
-        (meta.dedupe as { key?: unknown } | undefined)?.key;
-      const dedupeKeyTemplateStr =
-        typeof dedupeKeyTemplate === 'string' ? dedupeKeyTemplate : null;
+      const dedupeKeyTemplateStr = keySelectorToTemplate(
+        meta.dedupe?.key as JobKeySelector<unknown> | undefined,
+      );
       const dedupeWindowMs = meta.dedupe?.windowMs ?? null;
       const timeoutMs = meta.timeoutMs ?? null;
       const replayFrom = meta.replayFrom ?? 'last_checkpoint';

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

@@ -32,11 +32,17 @@ import type {
   JobContext,
   JobHandlerBase,
   JobHandlerMeta,
+  JobKeySelector,
   RetryPolicy,
   SpawnChildOptions,
   StepOptions,
 } from './job-handler.base';
-import { ParentClosePolicy } from './job-handler.base';
+import {
+  ParentClosePolicy,
+  keySelectorToTemplate,
+  FN_KEY_SENTINEL,
+  JobKeyFunctionUnavailableError,
+} from './job-handler.base';
 import {
   JobCollisionError,
   JobNotReplayableError,
@@ -176,10 +182,9 @@ export class MemoryJobOrchestrator implements IJobOrchestrator {
     meta: JobHandlerMeta<TInput>,
     handlerClass: new (...args: unknown[]) => JobHandlerBase<TInput>,
   ): void {
-    const concurrencyKeyTemplate =
-      (meta.concurrency as { key?: string } | undefined)?.key ?? null;
-    const dedupeKeyTemplate =
-      (meta.dedupe as { key?: string } | undefined)?.key ?? null;
+    // JOB-FN-KEY (0.16.2): mirror the Drizzle backend — collapse a function
+    // key to `FN_KEY_SENTINEL` so the def row stays non-null (collision/dedupe
+    // path engages); `start()` re-resolves the live fn from `handlerRegistry`.
     const dedupeWindowMs = meta.dedupe?.windowMs ?? null;
     const now = new Date();
 
@@ -194,13 +199,15 @@ export class MemoryJobOrchestrator implements IJobOrchestrator {
         baseMs: 0,
       },
       timeoutMs: meta.timeoutMs ?? null,
-      concurrencyKeyTemplate:
-        typeof concurrencyKeyTemplate === 'string' ? concurrencyKeyTemplate : null,
+      concurrencyKeyTemplate: keySelectorToTemplate(
+        meta.concurrency?.key as JobKeySelector<unknown> | undefined,
+      ),
       collisionMode:
         (meta.concurrency?.collisionMode as JobDefinitionRow['collisionMode']) ??
         'queue',
-      dedupeKeyTemplate:
-        typeof dedupeKeyTemplate === 'string' ? dedupeKeyTemplate : null,
+      dedupeKeyTemplate: keySelectorToTemplate(
+        meta.dedupe?.key as JobKeySelector<unknown> | undefined,
+      ),
       dedupeWindowMs,
       priorityDefault: 0,
       replayFrom: meta.replayFrom ?? 'last_checkpoint',
@@ -223,6 +230,34 @@ export class MemoryJobOrchestrator implements IJobOrchestrator {
     return this.handlerRegistry.get(type);
   }
 
+  /**
+   * JOB-FN-KEY (0.16.2): resolve a persisted key template against the payload.
+   * Delegates to the shared `resolveJobKey`, but binds the FUNCTION-sentinel
+   * lookup to THIS backend's local `handlerRegistry` (the memory backend keeps
+   * its own meta map seeded by `registerHandler`, distinct from the global
+   * `JOB_HANDLER_REGISTRY` that the Drizzle/worker path uses — memory tests
+   * register handlers directly, never via the `@JobHandler` decorator). The
+   * `evaluateTemplate` callback handles the ordinary `{{field}}` path.
+   */
+  private resolveKey(
+    kind: 'concurrency' | 'dedupe',
+    type: string,
+    template: string | null,
+    payload: Record<string, unknown>,
+  ): string | null {
+    if (template == null) return null;
+    if (template !== FN_KEY_SENTINEL) {
+      return evaluateKeyTemplate(template, payload);
+    }
+    const key = (this.handlerRegistry.get(type)?.meta?.[kind] as
+      | { key?: unknown }
+      | undefined)?.key;
+    if (typeof key !== 'function') {
+      throw new JobKeyFunctionUnavailableError(type, kind);
+    }
+    return (key as (input: unknown) => string)(payload);
+  }
+
   /**
    * Boot-time upsert per `IJobOrchestrator.upsertJobRows`. Memory backend
    * just funnels each entry through `registerHandler`. The validator is
@@ -270,11 +305,10 @@ export class MemoryJobOrchestrator implements IJobOrchestrator {
       if (!definition) throw new JobTypeNotFoundError(type);
 
       // 1. Dedupe — return existing non-excluded run within the window.
+      // JOB-FN-KEY: `resolveKey` honors the `{{field}}` template AND a function
+      // key persisted as `FN_KEY_SENTINEL` (re-resolved from `handlerRegistry`).
       if (definition.dedupeKeyTemplate && definition.dedupeWindowMs) {
-        const dedupeKey = evaluateKeyTemplate(
-          definition.dedupeKeyTemplate,
-          payload,
-        );
+        const dedupeKey = this.resolveKey('dedupe', type, definition.dedupeKeyTemplate, payload) as string;
         const windowStart = Date.now() - definition.dedupeWindowMs;
         const existing = this.findDedupeCandidate(type, dedupeKey, windowStart);
         if (existing) return existing;
@@ -284,10 +318,13 @@ export class MemoryJobOrchestrator implements IJobOrchestrator {
       let concurrencyKey: string | null = null;
       let queueBlockedBy: string | null = null;
       if (definition.concurrencyKeyTemplate) {
-        concurrencyKey = evaluateKeyTemplate(
+        // Non-null cast: the branch guard proves the template is present.
+        concurrencyKey = this.resolveKey(
+          'concurrency',
+          type,
           definition.concurrencyKeyTemplate,
           payload,
-        );
+        ) as string;
         const incumbent = this.findInFlightByConcurrencyKey(concurrencyKey);
         if (incumbent) {
           switch (definition.collisionMode) {
@@ -331,9 +368,12 @@ export class MemoryJobOrchestrator implements IJobOrchestrator {
       // 4. Compute dedupe key for the persisted row (separate from dedupe
       //    short-circuit above — we store it even when no prior run matched
       //    so future dedupe checks see it).
-      const dedupeKey = definition.dedupeKeyTemplate
-        ? evaluateKeyTemplate(definition.dedupeKeyTemplate, payload)
-        : null;
+      const dedupeKey = this.resolveKey(
+        'dedupe',
+        type,
+        definition.dedupeKeyTemplate,
+        payload,
+      );
 
       const now = new Date();
       const runAt = queueBlockedBy

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

@@ -317,6 +317,17 @@ export class JobWorker implements OnModuleInit, OnModuleDestroy {
   }
 
   async onModuleDestroy(): Promise<void> {
+    // LISTEN-NOTIFY-2 — release the listener connection on EVERY destroy path,
+    // including the `shuttingDown` early-return below (reached when SIGTERM and
+    // Nest's onModuleDestroy both fire) and a destroy with no prior SIGTERM.
+    // Previously this lived only on the first (non-shuttingDown) branch, so a
+    // double-fire — or a stop() that raced the listener's own in-flight
+    // connect() — left a `LISTEN codegen_jobs_wake` socket open past
+    // `app.close()`, hanging the process. `PgNotifyListener.stop()` is itself
+    // idempotent + connect-race-safe (LISTEN-NOTIFY-2). Best-effort; a failure
+    // here doesn't block the drain.
+    await this.stopNotifyListener();
+
     if (this.shuttingDown) {
       // Still drain, but don't tear intervals down twice.
       await this.drainInFlight();
@@ -333,17 +344,6 @@ 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.
@@ -370,6 +370,24 @@ export class JobWorker implements OnModuleInit, OnModuleDestroy {
     ]);
   }
 
+  /**
+   * LISTEN-NOTIFY-2 — stop + drop the wake listener. Idempotent: a second call
+   * (SIGTERM + Nest destroy) finds `notifyListener` already null and no-ops.
+   * `PgNotifyListener.stop()` is itself race-safe against an in-flight
+   * `connect()`, so even a destroy that arrives microseconds after `start()`
+   * releases the listener socket rather than leaking it.
+   */
+  private async stopNotifyListener(): Promise<void> {
+    const listener = this.notifyListener;
+    if (!listener) return;
+    this.notifyListener = null;
+    try {
+      await listener.stop();
+    } catch (err) {
+      this.logger.error(`notify listener stop failed: ${(err as Error).message}`);
+    }
+  }
+
   // ============================================================================
   // Poll loop
   // ============================================================================