@pattern-stack/codegen 0.15.3 → 0.16.1

package/dist/chunk-DLG62MQY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../runtime/subsystems/bridge/bridge-outbox-drain-hook.ts"],"sourcesContent":["/**\n * BridgeOutboxDrainHook — drains-time bridge fanout writer (BRIDGE-4,\n * ADR-023 Phase 2).\n *\n * Implements `IBridgeOutboxDrainHook`. Called by `DrizzleEventBus`'s\n * modified `processBatch` once per drained event, INSIDE the per-event\n * transaction. For every trigger registered against the event's type in\n * the codegen-emitted `bridgeRegistry`, writes:\n *\n *   1. `bridge_delivery` ledger row — `INSERT … ON CONFLICT (event_id,\n *      trigger_id) DO NOTHING RETURNING id`. Empty result ⇒ Case B\n *      facade-eager pre-write OR drain-replay collision; skip wrapper\n *      insert for that trigger; sibling triggers still fire.\n *   2. `job_run` wrapper row — `type='@framework/bridge_delivery'`,\n *      `pool='events_<direction>'`, `input={ deliveryId }`,\n *      `trigger_source='event'`, `trigger_ref=event.id`. The wrapper is\n *      what the framework `BridgeDeliveryHandler` (BRIDGE-5) eventually\n *      claims via the worker that polls the corresponding reserved pool.\n *\n * Null `event.metadata.direction` is tolerated: the hook logs a one-line\n * warning per event and returns zeros without writing rows. The drain's\n * `processed_at` stamp + subscriber dispatch still fire normally.\n * Direction is null only for events published via the legacy\n * `IEventBus.publish(...)` path (`TypedEventBus.publish` always sets it);\n * such events are out of scope for bridge fanout.\n *\n * The wrapper insert generates its own `id` via Drizzle's `defaultRandom`\n * — we don't `RETURNING id` because nobody needs it at drain time;\n * `BridgeDeliveryHandler` later looks up the wrapper via the\n * `bridge_delivery.wrapper_run_id` link if needed. This keeps the drain\n * one-round-trip-per-trigger.\n */\nimport { Inject, Injectable, Logger, Optional } from '@nestjs/common';\nimport { randomUUID } from 'node:crypto';\nimport { eq } from 'drizzle-orm';\n\nimport type { DomainEvent, DrizzleTransaction } from '../events/event-bus.protocol';\nimport { bridgeDelivery } from './bridge-delivery.schema';\nimport { jobRuns } from '../jobs/job-orchestration.schema';\n\nimport { BRIDGE_REGISTRY } from './bridge.tokens';\nimport type {\n  BridgeOutboxDrainResult,\n  BridgeRegistry,\n  BridgeTriggerEntry,\n  IBridgeOutboxDrainHook,\n} from './bridge.protocol';\nimport { BRIDGE_DELIVERY_JOB_TYPE } from './bridge-delivery-handler';\nimport type { EventTypeName } from '../events/event-registry';\nimport { JOBS_LISTEN_NOTIFY } from '../jobs/jobs-domain.tokens';\nimport { JOBS_WAKE_CHANNEL, pgNotify } from '../jobs/pg-notify';\n\n/** Reserved pools the wrapper rows route into; ADR-022 / ADR-024. */\nconst POOL_BY_DIRECTION: Record<string, string> = {\n  inbound: 'events_inbound',\n  change: 'events_change',\n  outbound: 'events_outbound',\n};\n\n@Injectable()\nexport class BridgeOutboxDrainHook implements IBridgeOutboxDrainHook {\n  private readonly logger = new Logger(BridgeOutboxDrainHook.name);\n  private warnedNullDirection = false;\n  private readonly warnedAuditTypes = new Set<string>();\n\n  constructor(\n    @Optional()\n    @Inject(BRIDGE_REGISTRY)\n    private readonly registry: BridgeRegistry = {},\n    // LISTEN-NOTIFY-1 — when true, the wrapper `job_run` insert below emits an\n    // in-tx `pg_notify(codegen_jobs_wake, <wrapperPool>)` so the reserved-pool\n    // worker wakes the instant the per-event drain tx commits — otherwise the\n    // bridge hop alone would still cost a full poll interval. `@Optional()`\n    // defaulting false so the hook keeps working when jobs isn't installed\n    // (bridge can drive non-jobs consumers) or in vendored/test wiring.\n    @Optional()\n    @Inject(JOBS_LISTEN_NOTIFY)\n    private readonly listenNotify: boolean = false,\n  ) {}\n\n  async processEvent(\n    event: DomainEvent,\n    tx: DrizzleTransaction,\n  ): Promise<BridgeOutboxDrainResult> {\n    // Audit-tier guard (defense-in-depth — AUDIT-4). Audit events are not\n    // bridge-eligible: the codegen-side validator (AUDIT-2) blocks the\n    // registry from listing them as triggers. Reaching this branch means\n    // registry/runtime drift — an out-of-band `bridge_trigger` insert, or\n    // version skew during deploy. Refuse fanout, surface drift via WARN.\n    if (event.metadata?.['tier'] === 'audit') {\n      this.warnAuditBlockedOnce(event);\n      return {\n        delivered: 0,\n        dedupSkips: 0,\n        triggerCount: 0,\n        auditBlocked: 1,\n      };\n    }\n\n    const triggers = this.lookupTriggers(event.type);\n    if (triggers.length === 0) {\n      return {\n        delivered: 0,\n        dedupSkips: 0,\n        triggerCount: 0,\n        auditBlocked: 0,\n      };\n    }\n\n    const direction =\n      (event.metadata?.['direction'] as string | undefined) ?? null;\n    const tenantId =\n      (event.metadata?.['tenantId'] as string | null | undefined) ?? null;\n    const wrapperPool = direction ? POOL_BY_DIRECTION[direction] : undefined;\n\n    if (!wrapperPool) {\n      // Null direction (or an unrecognised one — defensive). Bridge\n      // fanout requires a routed wrapper pool; without one we can't\n      // spawn. Log once per process so misconfiguration surfaces.\n      if (!this.warnedNullDirection) {\n        this.warnedNullDirection = true;\n        this.logger.warn(\n          `Skipping bridge fanout for events with null/unknown direction. ` +\n            `event.id=${event.id} event.type=${event.type} ` +\n            `direction=${String(direction)}. The wrapper pool is derived ` +\n            `from direction (events_<direction>); publishers must use ` +\n            `TypedEventBus.publish() so direction is stamped on the ` +\n            `outbox row.`,\n        );\n      }\n      return {\n        delivered: 0,\n        dedupSkips: 0,\n        triggerCount: triggers.length,\n        auditBlocked: 0,\n      };\n    }\n\n    let delivered = 0;\n    let dedupSkips = 0;\n    const client = tx as unknown as {\n      insert: (table: unknown) => {\n        values: (v: unknown) => {\n          onConflictDoNothing: (opts: unknown) => {\n            returning: (cols: unknown) => Promise<{ id: string }[]>;\n          };\n        } & {\n          // wrapper insert path — no ON CONFLICT\n          // (typed loosely via the same helper return shape)\n        };\n      };\n    };\n\n    for (const trigger of triggers) {\n      const deliveryId = randomUUID();\n      const wrapperRunId = randomUUID();\n\n      // FK ORDER (BRIDGE / 0.15.2): `bridge_delivery.wrapper_run_id` REFERENCES\n      // `job_run(id)` is a plain (non-deferrable) FK, so the referenced\n      // wrapper `job_run` MUST exist before the delivery row that points at it\n      // is inserted — otherwise Postgres rejects the delivery insert\n      // immediately. (The codegen unit tests mock `tx`, so they never\n      // exercised this ordering against a real FK; package-mode bridge\n      // deliveries are the first to do so.) We therefore insert the wrapper\n      // run FIRST, then the delivery. Idempotency is unchanged: the delivery\n      // keeps its `ON CONFLICT (event_id, trigger_id) DO NOTHING RETURNING`,\n      // and when the delivery conflicts (outbox replay or facade-eager Case B)\n      // we DELETE the just-inserted orphan wrapper run in the same tx, so a\n      // skipped delivery leaves no stray `job_run` for a worker to claim.\n\n      // 1. Wrapper job_run insert. We carry the deliveryId into the wrapper\n      //    input so BridgeDeliveryHandler.run(ctx) can locate the row via\n      //    repo.findDeliveryById(ctx.input.deliveryId).\n      await (tx as unknown as { insert: typeof client.insert })\n        .insert(jobRuns)\n        .values({\n          id: wrapperRunId,\n          jobType: BRIDGE_DELIVERY_JOB_TYPE,\n          jobVersion: 1,\n          rootRunId: wrapperRunId,\n          pool: wrapperPool,\n          status: 'pending',\n          input: { deliveryId },\n          triggerSource: 'event',\n          triggerRef: event.id,\n          tenantId,\n        });\n\n      // 2. bridge_delivery insert with ON CONFLICT DO NOTHING + RETURNING.\n      const inserted = await (tx as unknown as {\n        insert: typeof client.insert;\n      })\n        .insert(bridgeDelivery)\n        .values({\n          id: deliveryId,\n          eventId: event.id,\n          triggerId: trigger.triggerId,\n          wrapperRunId,\n          status: 'pending',\n          tenantId,\n        })\n        .onConflictDoNothing({\n          target: [bridgeDelivery.eventId, bridgeDelivery.triggerId],\n        })\n        .returning({ id: bridgeDelivery.id });\n\n      if (inserted.length === 0) {\n        // Case B (facade pre-wrote `delivered`) or drain replay — the delivery\n        // already exists, so this trigger is a no-op. Remove the orphan wrapper\n        // run we speculatively inserted above so no worker claims it. Sibling\n        // triggers still fire.\n        await (tx as unknown as {\n          delete: (table: unknown) => {\n            where: (cond: unknown) => Promise<unknown>;\n          };\n        })\n          .delete(jobRuns)\n          .where(eq(jobRuns.id, wrapperRunId));\n        dedupSkips++;\n        continue;\n      }\n\n      // LISTEN-NOTIFY-1 — the wrapper run is real and claimable; wake its\n      // reserved-pool worker on commit (D7). Same `tx` as the inserts above, so\n      // delivery is gated on the per-event drain tx committing. Best-effort: a\n      // notify failure is non-fatal (the reserved-pool worker still polls).\n      if (this.listenNotify) {\n        try {\n          await pgNotify(tx, JOBS_WAKE_CHANNEL, wrapperPool);\n        } catch (err) {\n          this.logger.warn(\n            `pg_notify(${JOBS_WAKE_CHANNEL}, ${wrapperPool}) failed for ` +\n              `wrapper run ${wrapperRunId}: ${(err as Error).message} ` +\n              `(non-fatal — the reserved-pool worker still polls).`,\n          );\n        }\n      }\n\n      delivered++;\n    }\n\n    return {\n      delivered,\n      dedupSkips,\n      triggerCount: triggers.length,\n      auditBlocked: 0,\n    };\n  }\n\n  private warnAuditBlockedOnce(event: DomainEvent): void {\n    if (this.warnedAuditTypes.has(event.type)) return;\n    this.warnedAuditTypes.add(event.type);\n    this.logger.warn(\n      `Bridge guard blocked audit-tier event '${event.type}' (event.id=${event.id}). ` +\n        `Registry says this event is not bridge-eligible; a bridge_trigger row exists ` +\n        `out-of-band. Investigate registry/runtime drift.`,\n    );\n  }\n\n  private lookupTriggers(\n    eventType: string,\n  ): BridgeTriggerEntry[] {\n    const candidates = this.registry[eventType as EventTypeName];\n    return (candidates ?? []) as BridgeTriggerEntry[];\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-TNXH7BJS.js → chunk-E45CSC33.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-AQFQ4BYM.js";
 import {
   ObservabilityService
-} from "./chunk-YPWODKD5.js";
+} from "./chunk-W2UIDI3R.js";
 import {
   OBSERVABILITY,
   OBSERVABILITY_MODULE_OPTIONS
@@ -45,4 +45,4 @@ ObservabilityModule = __decorateClass([
 export {
   ObservabilityModule
 };
-//# sourceMappingURL=chunk-TNXH7BJS.js.map
+//# sourceMappingURL=chunk-E45CSC33.js.map

package/dist/{chunk-4JLJYWJC.js → chunk-H6FO2ZDJ.js}

@@ -1,17 +1,22 @@
-import {
-  clampEventLimit,
-  decodeEventCursor,
-  encodeEventCursor
-} from "./chunk-UQ5EHOH2.js";
-import {
-  EVENTS_MODULE_OPTIONS
-} from "./chunk-H5NH7KPE.js";
 import {
   BRIDGE_OUTBOX_DRAIN_HOOK
 } from "./chunk-4LH67P4U.js";
+import {
+  EVENTS_WAKE_CHANNEL,
+  PgNotifyListener,
+  pgNotify
+} from "./chunk-MYQIQ27N.js";
 import {
   domainEvents
 } from "./chunk-OFRRBC7M.js";
+import {
+  EVENTS_MODULE_OPTIONS
+} from "./chunk-H5NH7KPE.js";
+import {
+  clampEventLimit,
+  decodeEventCursor,
+  encodeEventCursor
+} from "./chunk-UQ5EHOH2.js";
 import {
   DRIZZLE
 } from "./chunk-U64T4YZE.js";
@@ -83,12 +88,35 @@ var DrizzleEventBus = class {
   pollTimer = null;
   handlers = /* @__PURE__ */ new Map();
   opts;
+  // LISTEN-NOTIFY-1 — dedicated wake listener + debounce state. `null` when
+  // `listenNotify` is off (the common case); polling is the only driver then.
+  notifyListener = null;
+  /** True while a wake-driven drain is in flight (debounce gate). */
+  wakeDraining = false;
+  /** A notify arrived mid-drain → re-drain once when the current drain ends. */
+  wakeRecheckPending = false;
   // ============================================================================
   // Lifecycle
   // ============================================================================
   async onModuleInit() {
     this.polling = true;
     this.schedulePoll();
+    if (this.opts.listenNotify) {
+      const pool = this.db.$client;
+      if (!pool || typeof pool.connect !== "function") {
+        this.logger.warn(
+          `listen_notify enabled but the Drizzle client exposes no pg Pool ($client.connect missing) \u2014 falling back to interval polling only.`
+        );
+      } else {
+        this.notifyListener = new PgNotifyListener({
+          channel: EVENTS_WAKE_CHANNEL,
+          pool,
+          label: "events",
+          onNotify: (payload) => this.onWake(payload)
+        });
+        await this.notifyListener.start();
+      }
+    }
   }
   async onModuleDestroy() {
     this.polling = false;
@@ -96,6 +124,43 @@ var DrizzleEventBus = class {
       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).
+   */
+  onWake(payload) {
+    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();
+  }
+  async drainOnWake() {
+    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;
+    }
   }
   // ============================================================================
   // IEventBus
@@ -103,13 +168,36 @@ var DrizzleEventBus = class {
   async publish(event, tx) {
     const client = tx ?? this.db;
     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);
+    await this.emitWakeNotify(client, [values.pool]);
   }
   async publishMany(events, tx) {
     if (events.length === 0) return;
     const client = tx ?? this.db;
     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);
+    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.
+   */
+  async emitWakeNotify(client, pools) {
+    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 \u2014 interval polling still drains the outbox).`
+        );
+      }
+    }
   }
   async findById(eventId) {
     const rows = await this.db.select().from(domainEvents).where(eq(domainEvents.id, eventId)).limit(1);
@@ -305,4 +393,4 @@ DrizzleEventBus = __decorateClass([
 export {
   DrizzleEventBus
 };
-//# sourceMappingURL=chunk-4JLJYWJC.js.map
+//# sourceMappingURL=chunk-H6FO2ZDJ.js.map

package/dist/chunk-H6FO2ZDJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../runtime/subsystems/events/event-bus.drizzle-backend.ts"],"sourcesContent":["/**\n * DrizzleEventBus — Postgres-backed event bus using the transactional outbox pattern.\n *\n * Events are inserted into the `domain_events` table within the caller's\n * Drizzle transaction. A background polling loop (started on module init)\n * reads unprocessed events and dispatches them to registered subscribers.\n *\n * When the transaction rolls back, the event is never persisted — no\n * phantom events.\n *\n * Pool awareness (EVT-4):\n * - On `publish`/`publishMany` the backend writes `metadata.pool`,\n *   `metadata.direction`, and `metadata.tenantId` into the first-class\n *   `pool` / `direction` / `tenant_id` columns (metadata JSON is still\n *   written unchanged for protocol stability).\n * - The drain loop filters by `opts.pools` when provided, so separate\n *   processes (e.g. one per `events_inbound` / `events_change` /\n *   `events_outbound`) can claim only their own lane. `pools: undefined`\n *   drains all pending rows (backwards-compatible behaviour).\n *\n * EVT-Q7: No stale-event sweeper. `FOR UPDATE SKIP LOCKED` is\n * self-healing — the row is only locked for the duration of the\n * enclosing polling transaction; the `status='processed'` update happens\n * within that same transaction. There is no `claimed_at` semantic (unlike\n * jobs), so no stale rows can exist.\n *\n * This backend is suitable until you need real-time fan-out or very high\n * throughput. At that point, swap the backend for Redis Streams or similar\n * via EventsModule.forRoot({ backend: '...' }) without touching use cases.\n */\nimport { Injectable, OnModuleDestroy, OnModuleInit, Inject, Logger, Optional } from '@nestjs/common';\nimport { eq, and, inArray, asc, desc, gte, lt, or, sql, type SQL } from 'drizzle-orm';\nimport type { DomainEvent, DrizzleTransaction, IEventBus } from './event-bus.protocol';\nimport type {\n  EventPage,\n  IEventReadPort,\n  ListEventsQuery,\n} from './event-read.protocol';\nimport {\n  clampEventLimit,\n  decodeEventCursor,\n  encodeEventCursor,\n} from './event-keyset-cursor';\nimport type { DrizzleClient } from '../../types/drizzle';\nimport { domainEvents, type DomainEventRecord } from './domain-events.schema';\nimport { DRIZZLE } from '../../constants/tokens';\nimport { EVENTS_MODULE_OPTIONS } from './events.tokens';\nimport type { EventsModuleOptions } from './events.module';\nimport { BRIDGE_OUTBOX_DRAIN_HOOK } from '../bridge/bridge.tokens';\nimport type { IBridgeOutboxDrainHook } from '../bridge/bridge.protocol';\nimport {\n  EVENTS_WAKE_CHANNEL,\n  PgNotifyListener,\n  pgNotify,\n} from '../jobs/pg-notify';\n\n/** How long to wait between polling cycles (ms). */\nconst POLL_INTERVAL_MS = 1_000;\n/** Max events claimed per polling cycle to bound memory usage. */\nconst POLL_BATCH_SIZE = 50;\n\n/**\n * Row shape built from `metadata` for writing into `domain_events`. Keeps\n * the per-event extraction logic in one place so publish/publishMany stay\n * in sync.\n */\nfunction toInsertValues(event: DomainEvent, multiTenant: boolean) {\n  const metadata = event.metadata ?? undefined;\n  const pool = (metadata?.['pool'] as string | undefined) ?? null;\n  const direction = (metadata?.['direction'] as string | undefined) ?? null;\n  // AUDIT-1: tier defaults to 'domain' when absent. The DB CHECK\n  // constraint (`domain_events_tier_routing_check`) enforces the\n  // tier ⇔ routing-fields invariant at the storage boundary; no\n  // JS-side assertion is needed here.\n  const tier = (metadata?.['tier'] as string | undefined) ?? 'domain';\n  const base = {\n    id: event.id,\n    type: event.type,\n    aggregateId: event.aggregateId,\n    aggregateType: event.aggregateType,\n    payload: event.payload,\n    occurredAt: event.occurredAt,\n    processedAt: null,\n    status: 'pending' as const,\n    metadata: event.metadata,\n    pool,\n    direction,\n    tier,\n  };\n  // EVT-8: `tenant_id` is a scaffold-time conditional column, emitted only\n  // when `events.multi_tenant: true`. Only write it when multi-tenancy is\n  // on — under single-tenant scaffolds the column does not exist, so the\n  // key must be omitted from the insert.\n  if (!multiTenant) return base;\n  const tenantId = (metadata?.['tenantId'] as string | undefined) ?? null;\n  return { ...base, tenantId };\n}\n\n/**\n * Project a raw `domain_events` row into the narrow `EventSummary` shape.\n * Shared with the memory backend via this helper kept module-local to each\n * backend (the events subsystem has no cross-backend projection file yet;\n * the two are byte-identical and small).\n */\nfunction toEventSummary(r: DomainEventRecord) {\n  const metadata = (r.metadata ?? undefined) as\n    | Record<string, unknown>\n    | undefined;\n  const rootRunId = metadata?.['rootRunId'];\n  return {\n    id: r.id,\n    type: r.type,\n    aggregateId: r.aggregateId,\n    aggregateType: r.aggregateType,\n    status: r.status,\n    pool: r.pool,\n    direction: r.direction,\n    tier: r.tier,\n    rootRunId: typeof rootRunId === 'string' ? rootRunId : null,\n    // EVT-8: `tenant_id` is a scaffold-time conditional column. Read it\n    // structurally so this projection typechecks against both the\n    // multi-tenant schema (column present) and the single-tenant schema\n    // (column absent → undefined → null).\n    tenantId: (r as { tenantId?: string | null }).tenantId ?? null,\n    occurredAt:\n      r.occurredAt instanceof Date\n        ? r.occurredAt\n        : new Date(r.occurredAt as unknown as string),\n    processedAt:\n      r.processedAt == null\n        ? null\n        : r.processedAt instanceof Date\n          ? r.processedAt\n          : new Date(r.processedAt as unknown as string),\n  };\n}\n\n@Injectable()\nexport class DrizzleEventBus implements IEventBus, IEventReadPort, OnModuleInit, OnModuleDestroy {\n  private readonly logger = new Logger(DrizzleEventBus.name);\n  private polling = false;\n  private pollTimer: ReturnType<typeof setTimeout> | null = null;\n  private readonly handlers = new Map<string, Set<(event: DomainEvent) => Promise<void>>>();\n  private readonly opts: EventsModuleOptions;\n\n  // LISTEN-NOTIFY-1 — dedicated wake listener + debounce state. `null` when\n  // `listenNotify` is off (the common case); polling is the only driver then.\n  private notifyListener: PgNotifyListener | null = null;\n  /** True while a wake-driven drain is in flight (debounce gate). */\n  private wakeDraining = false;\n  /** A notify arrived mid-drain → re-drain once when the current drain ends. */\n  private wakeRecheckPending = false;\n\n  constructor(\n    @Inject(DRIZZLE) private readonly db: DrizzleClient,\n    @Optional() @Inject(EVENTS_MODULE_OPTIONS) opts?: EventsModuleOptions,\n    /**\n     * Bridge subsystem hook (BRIDGE-4). Optional — when the bridge\n     * subsystem is not installed in the consuming app, this token is\n     * undefined and the drain skips the bridge block entirely (preserves\n     * EVT-4 baseline behaviour).\n     *\n     * When provided, `processEvent` is invoked once per drained event\n     * INSIDE the per-event tx, before `processed_at` is stamped. The\n     * hook owns all knowledge of `bridge_delivery + wrapper job_run`\n     * shapes; the events subsystem stays unaware of bridge schemas.\n     */\n    @Optional()\n    @Inject(BRIDGE_OUTBOX_DRAIN_HOOK)\n    private readonly bridgeHook: IBridgeOutboxDrainHook | null = null,\n  ) {\n    // Default so direct construction (e.g. integration tests not going\n    // through Nest DI) keeps working without an explicit options object.\n    this.opts = opts ?? { backend: 'drizzle' };\n  }\n\n  // ============================================================================\n  // Lifecycle\n  // ============================================================================\n\n  async onModuleInit(): Promise<void> {\n    this.polling = true;\n    this.schedulePoll();\n\n    // LISTEN-NOTIFY-1 — start the wake listener ALONGSIDE the poll timer. A\n    // notify for one of this drainer's pools triggers an immediate drain; the\n    // interval timer above stays the durability heartbeat. Startup is\n    // fire-and-forget — a connect failure self-heals via the listener's backoff.\n    if (this.opts.listenNotify) {\n      const pool = (this.db as unknown as { $client?: unknown }).$client;\n      if (!pool || typeof (pool as { connect?: unknown }).connect !== 'function') {\n        this.logger.warn(\n          `listen_notify enabled but the Drizzle client exposes no pg Pool ` +\n            `($client.connect missing) — falling back to interval polling only.`,\n        );\n      } else {\n        this.notifyListener = new PgNotifyListener({\n          channel: EVENTS_WAKE_CHANNEL,\n          pool: pool as { connect(): Promise<never> },\n          label: 'events',\n          onNotify: (payload) => this.onWake(payload),\n        });\n        await this.notifyListener.start();\n      }\n    }\n  }\n\n  async onModuleDestroy(): Promise<void> {\n    this.polling = false;\n    if (this.pollTimer) {\n      clearTimeout(this.pollTimer);\n      this.pollTimer = null;\n    }\n    if (this.notifyListener) {\n      try {\n        await this.notifyListener.stop();\n      } catch (err) {\n        this.logger.error(`notify listener stop failed: ${err}`);\n      }\n      this.notifyListener = null;\n    }\n  }\n\n  /**\n   * Wake handler — a `codegen_events_wake` notification arrived. A pool-filtered\n   * drainer (`opts.pools` set) ignores payloads naming a pool it doesn't own; an\n   * all-pools drainer wakes for any. Debounced: a notify mid-drain just flags a\n   * re-check so a burst collapses to at most one extra drain (D3).\n   */\n  private onWake(payload: string): void {\n    if (!this.polling) return;\n    const pools = this.opts.pools;\n    if (pools && pools.length > 0 && !pools.includes(payload)) return;\n    if (this.wakeDraining) {\n      this.wakeRecheckPending = true;\n      return;\n    }\n    void this.drainOnWake();\n  }\n\n  private async drainOnWake(): Promise<void> {\n    this.wakeDraining = true;\n    try {\n      do {\n        this.wakeRecheckPending = false;\n        await this.processBatch();\n      } while (this.wakeRecheckPending && this.polling);\n    } catch (err) {\n      this.logger.error(`wake drain error: ${err}`);\n    } finally {\n      this.wakeDraining = false;\n    }\n  }\n\n  // ============================================================================\n  // IEventBus\n  // ============================================================================\n\n  async publish(event: DomainEvent, tx?: DrizzleTransaction): Promise<void> {\n    const client = (tx ?? this.db) as DrizzleClient;\n    const multiTenant = this.opts.multiTenant ?? false;\n    const values = toInsertValues(event, multiTenant);\n    await client.insert(domainEvents).values(values);\n    // LISTEN-NOTIFY-1 — wake the drainer on commit (D2: emitted through the same\n    // `client`, so a rolled-back publish emits no phantom wake). The pool is the\n    // payload; the drainer re-runs its own pool-filtered claim on wake.\n    await this.emitWakeNotify(client, [values.pool]);\n  }\n\n  async publishMany(events: DomainEvent[], tx?: DrizzleTransaction): Promise<void> {\n    if (events.length === 0) return;\n    const client = (tx ?? this.db) as DrizzleClient;\n    const multiTenant = this.opts.multiTenant ?? false;\n    const valuesList = events.map((e) => toInsertValues(e, multiTenant));\n    await client.insert(domainEvents).values(valuesList);\n    // De-dup pools so a batch into one lane emits a single wake.\n    await this.emitWakeNotify(client, valuesList.map((v) => v.pool));\n  }\n\n  /**\n   * Emit one in-tx `pg_notify(codegen_events_wake, <pool>)` per distinct pool in\n   * the just-inserted batch. No-op unless `listenNotify` is on. Best-effort: a\n   * notify failure is non-fatal (interval polling still drains the rows), so we\n   * log + swallow rather than failing the publish.\n   */\n  private async emitWakeNotify(\n    client: DrizzleClient,\n    pools: Array<string | null>,\n  ): Promise<void> {\n    if (!this.opts.listenNotify) return;\n    const distinct = new Set(pools.map((p) => p ?? ''));\n    for (const pool of distinct) {\n      try {\n        await pgNotify(client, EVENTS_WAKE_CHANNEL, pool);\n      } catch (err) {\n        this.logger.warn(\n          `pg_notify(${EVENTS_WAKE_CHANNEL}, '${pool}') failed: ${err} ` +\n            `(non-fatal — interval polling still drains the outbox).`,\n        );\n      }\n    }\n  }\n\n  async findById(eventId: string): Promise<DomainEvent | null> {\n    const rows = await this.db\n      .select()\n      .from(domainEvents)\n      .where(eq(domainEvents.id, eventId))\n      .limit(1);\n    const row = rows[0];\n    if (!row) return null;\n    return {\n      id: row.id,\n      type: row.type,\n      aggregateId: row.aggregateId,\n      aggregateType: row.aggregateType,\n      payload: row.payload as Record<string, unknown>,\n      occurredAt:\n        row.occurredAt instanceof Date\n          ? row.occurredAt\n          : new Date(row.occurredAt as unknown as string),\n      metadata: (row.metadata ?? undefined) as\n        | Record<string, unknown>\n        | undefined,\n    };\n  }\n\n  subscribe<T extends DomainEvent = DomainEvent>(\n    eventType: string,\n    handler: (event: T) => Promise<void>,\n  ): () => void {\n    if (!this.handlers.has(eventType)) {\n      this.handlers.set(eventType, new Set());\n    }\n    const set = this.handlers.get(eventType)!;\n    const h = handler as (event: DomainEvent) => Promise<void>;\n    set.add(h);\n    return () => {\n      set.delete(h);\n    };\n  }\n\n  // ============================================================================\n  // IEventReadPort (OBS-LIST-1)\n  // ============================================================================\n\n  async listEvents(query: ListEventsQuery = {}): Promise<EventPage> {\n    const limit = clampEventLimit(query.limit);\n    const conditions: SQL<unknown>[] = [];\n\n    if (query.poolId) conditions.push(eq(domainEvents.pool, query.poolId));\n    if (query.direction)\n      conditions.push(eq(domainEvents.direction, query.direction));\n    if (query.since) conditions.push(gte(domainEvents.occurredAt, query.since));\n    if (query.rootRunId) {\n      // Filter on the JSON correlation id: metadata->>'rootRunId'.\n      conditions.push(\n        sql`${domainEvents.metadata}->>'rootRunId' = ${query.rootRunId}`,\n      );\n    }\n    // EVT-8: `tenant_id` is a scaffold-time conditional column (emitted only\n    // under `events.multi_tenant: true`). Guard the filter behind the same\n    // `multiTenant` flag, and read the column structurally so this backend\n    // typechecks against both the multi-tenant schema (column present) and\n    // the single-tenant schema (column absent). When multi-tenancy is off\n    // there is no `tenant_id` column to filter on.\n    if (this.opts.multiTenant && query.tenantId !== undefined) {\n      const tenantIdColumn = (\n        domainEvents as unknown as { tenantId: typeof domainEvents.pool }\n      ).tenantId;\n      conditions.push(\n        query.tenantId === null\n          ? (sql`${tenantIdColumn} is null` as SQL<unknown>)\n          : eq(tenantIdColumn, query.tenantId),\n      );\n    }\n\n    // Keyset seek: WHERE (occurred_at, id) < (cursorOccurredAt, cursorId).\n    if (query.cursor) {\n      const keyset = decodeEventCursor(query.cursor);\n      if (keyset) {\n        conditions.push(\n          or(\n            lt(domainEvents.occurredAt, keyset.occurredAt),\n            and(\n              eq(domainEvents.occurredAt, keyset.occurredAt),\n              lt(domainEvents.id, keyset.id),\n            ),\n          )!,\n        );\n      }\n    }\n\n    const rows = (await this.db\n      .select()\n      .from(domainEvents)\n      .where(conditions.length > 0 ? and(...conditions) : undefined)\n      .orderBy(desc(domainEvents.occurredAt), desc(domainEvents.id))\n      .limit(limit + 1)) as DomainEventRecord[];\n\n    const hasMore = rows.length > limit;\n    const page = hasMore ? rows.slice(0, limit) : rows;\n    const items = page.map(toEventSummary);\n    const last = page[page.length - 1];\n    const nextCursor =\n      hasMore && last\n        ? encodeEventCursor({ occurredAt: last.occurredAt, id: last.id })\n        : null;\n\n    return { items, nextCursor };\n  }\n\n  // ============================================================================\n  // Polling\n  // ============================================================================\n\n  /**\n   * Test-only hook. Runs exactly one drain cycle and returns. Production\n   * code goes through `onModuleInit` → `schedulePoll`, which calls the\n   * same `processBatch` under a timer.\n   */\n  async drainOnce(): Promise<void> {\n    await this.processBatch();\n  }\n\n  private schedulePoll(): void {\n    if (!this.polling) return;\n    this.pollTimer = setTimeout(async () => {\n      try {\n        await this.processBatch();\n      } catch (err) {\n        this.logger.error(`Poll cycle error: ${err}`);\n      } finally {\n        this.schedulePoll();\n      }\n    }, POLL_INTERVAL_MS);\n  }\n\n  /**\n   * Drain one batch (BRIDGE-4 restructure of EVT-4).\n   *\n   * Two-phase per drained event:\n   *\n   *   1. **Per-event transaction** — bridge fanout (`bridgeHook.processEvent`)\n   *      + `processed_at` stamp. Both write through the same `tx`. A throw\n   *      inside the tx (only infra-level failures should reach here, since\n   *      the hook tolerates null direction and registry misses inline)\n   *      rolls back the bridge inserts AND the `processed_at` stamp; the\n   *      event re-claims on the next drain cycle. Bridge `UNIQUE\n   *      (event_id, trigger_id)` makes the retry idempotent.\n   *\n   *   2. **After commit** — dispatch in-process subscribers (`IEventBus.subscribe`\n   *      handlers). This deliberately runs OUTSIDE the per-event tx (lead\n   *      decision 2026-04-22): subscribers are best-effort and must not\n   *      gate forward progress or roll back bridge fanout. Subscriber\n   *      errors are caught + logged; `processed_at` is already committed.\n   *      The old `MAX_RETRIES=3` in-process retry loop and the\n   *      `failed`-stamping path were removed in BRIDGE-4 along with their\n   *      coupling.\n   *\n   * The `processed_at` UPDATE carries `AND status='pending'` (BRIDGE-4\n   * tightening — without it, a hypothetical double-claim could double-stamp\n   * the timestamp). The per-event tx + `FOR UPDATE SKIP LOCKED` claim\n   * make this defensive belt-and-suspenders.\n   */\n  private async processBatch(): Promise<void> {\n    const pools = this.opts.pools;\n\n    // Build WHERE: status='pending' [AND pool IN (...)]\n    const whereClause: SQL<unknown> = pools && pools.length > 0\n      ? (and(eq(domainEvents.status, 'pending'), inArray(domainEvents.pool, pools)) as SQL<unknown>)\n      : eq(domainEvents.status, 'pending');\n\n    // Claim a batch with FOR UPDATE SKIP LOCKED so multiple pollers don't\n    // double-dispatch. The lock is released when the outer transaction\n    // commits — which is fine because the immediately-following per-event\n    // tx flips status='processed' under its own `AND status='pending'`\n    // guard, so a re-claim of the same row in a subsequent batch is a\n    // no-op UPDATE.\n    const rows = await this.db.transaction(async (tx) => {\n      return tx\n        .select()\n        .from(domainEvents)\n        .where(whereClause)\n        .orderBy(asc(domainEvents.occurredAt))\n        .limit(POLL_BATCH_SIZE)\n        .for('update', { skipLocked: true });\n    }) as Array<typeof domainEvents.$inferSelect>;\n\n    for (const row of rows) {\n      const event: DomainEvent = {\n        id: row.id,\n        type: row.type,\n        aggregateId: row.aggregateId,\n        aggregateType: row.aggregateType,\n        payload: row.payload as Record<string, unknown>,\n        occurredAt: row.occurredAt instanceof Date ? row.occurredAt : new Date(row.occurredAt as unknown as string),\n        metadata: (row.metadata ?? undefined) as Record<string, unknown> | undefined,\n      };\n\n      // Phase 1 — per-event tx: bridge fanout + processed_at stamp.\n      try {\n        await this.db.transaction(async (tx) => {\n          if (this.bridgeHook) {\n            await this.bridgeHook.processEvent(event, tx);\n          }\n          await tx\n            .update(domainEvents)\n            .set({ status: 'processed', processedAt: new Date() })\n            .where(\n              and(\n                eq(domainEvents.id, event.id),\n                eq(domainEvents.status, 'pending'),\n              ),\n            );\n        });\n      } catch (err) {\n        // Infra-level failure inside the per-event tx — bridge inserts\n        // and processed_at both rolled back. Log and move on; the next\n        // drain cycle re-claims the row. UNIQUE on bridge_delivery makes\n        // the retry idempotent.\n        this.logger.error(\n          `Per-event tx failed for event id=${event.id} type=${event.type}: ${err}`,\n        );\n        continue;\n      }\n\n      // Phase 2 — best-effort subscriber dispatch. Errors are logged\n      // and discarded; processed_at is already committed. Subscribers\n      // are observability + cache-busts + small ancillary work; they\n      // must not gate forward progress.\n      try {\n        await this.dispatch(event);\n      } catch (err) {\n        this.logger.error(\n          `Subscriber dispatch failed for event id=${event.id} type=${event.type} ` +\n            `(processed_at already committed; failure does not retry): ${err}`,\n        );\n      }\n    }\n  }\n\n  private async dispatch(event: DomainEvent): Promise<void> {\n    const set = this.handlers.get(event.type);\n    if (!set) return;\n\n    let firstError: unknown;\n    for (const handler of set) {\n      try {\n        await handler(event);\n      } catch (err) {\n        this.logger.error(\n          `Handler error for event type \"${event.type}\" (id: ${event.id}): ${err}`,\n        );\n        if (firstError === undefined) {\n          firstError = err;\n        }\n      }\n    }\n\n    if (firstError !== undefined) {\n      throw firstError;\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-5Y7W3XR6.js → chunk-IT6FRTEW.js}

@@ -1,3 +1,12 @@
+import {
+  jobRuns,
+  jobSteps,
+  jobs
+} from "./chunk-OKXZ63IA.js";
+import {
+  JOBS_LISTEN_NOTIFY,
+  JOBS_MULTI_TENANT
+} from "./chunk-ZPL74UQN.js";
 import {
   JobCollisionError,
   JobNotReplayableError,
@@ -6,13 +15,9 @@ import {
   MissingTenantIdError
 } from "./chunk-T4BIIU5E.js";
 import {
-  JOBS_MULTI_TENANT
-} from "./chunk-BIO6F7YI.js";
-import {
-  jobRuns,
-  jobSteps,
-  jobs
-} from "./chunk-OKXZ63IA.js";
+  JOBS_WAKE_CHANNEL,
+  pgNotify
+} from "./chunk-MYQIQ27N.js";
 import {
   DRIZZLE
 } from "./chunk-U64T4YZE.js";
@@ -23,7 +28,7 @@ import {
 
 // runtime/subsystems/jobs/job-orchestrator.drizzle-backend.ts
 import { randomUUID } from "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";
 var TERMINAL_STATUSES = [
   "completed",
@@ -43,12 +48,14 @@ function evaluateKeyTemplate(template, input) {
   });
 }
 var DrizzleJobOrchestrator = class {
-  constructor(db, multiTenant) {
+  constructor(db, multiTenant, listenNotify = false) {
     this.db = db;
     this.multiTenant = multiTenant;
+    this.listenNotify = listenNotify;
   }
   db;
   multiTenant;
+  listenNotify;
   // TODO(logging-subsystem): swap to ILogger once ADR-028 lands
   logger = new Logger(DrizzleJobOrchestrator.name);
   /**
@@ -157,6 +164,16 @@ var DrizzleJobOrchestrator = class {
       claimedAt: null,
       attempts: 0
     }).returning();
+    if (this.listenNotify) {
+      const wakePool = inserted.pool;
+      try {
+        await pgNotify(client, JOBS_WAKE_CHANNEL, wakePool);
+      } catch (err) {
+        this.logger.warn(
+          `pg_notify(${JOBS_WAKE_CHANNEL}, ${wakePool}) failed for run ${inserted.id}: ${err.message} (non-fatal \u2014 interval polling still claims the run).`
+        );
+      }
+    }
     return inserted;
   }
   // ==========================================================================
@@ -341,7 +358,9 @@ var DrizzleJobOrchestrator = class {
 DrizzleJobOrchestrator = __decorateClass([
   Injectable(),
   __decorateParam(0, Inject(DRIZZLE)),
-  __decorateParam(1, Inject(JOBS_MULTI_TENANT))
+  __decorateParam(1, Inject(JOBS_MULTI_TENANT)),
+  __decorateParam(2, Optional()),
+  __decorateParam(2, Inject(JOBS_LISTEN_NOTIFY))
 ], DrizzleJobOrchestrator);
 function notInStatus(statuses) {
   const negated = statuses.map((s) => ne(jobRuns.status, s));
@@ -353,4 +372,4 @@ export {
   evaluateKeyTemplate,
   DrizzleJobOrchestrator
 };
-//# sourceMappingURL=chunk-5Y7W3XR6.js.map
+//# sourceMappingURL=chunk-IT6FRTEW.js.map

package/dist/chunk-IT6FRTEW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../runtime/subsystems/jobs/job-orchestrator.drizzle-backend.ts"],"sourcesContent":["/**\n * DrizzleJobOrchestrator — Postgres-backed implementation of\n * `IJobOrchestrator` (ADR-022, JOB-3).\n *\n * Single-layer architecture: `start` writes a single `job_run` row; the\n * `JobWorker` polling loop claims it directly via `FOR UPDATE SKIP LOCKED`.\n * No `job_queue` table, no executor port. See `docs/specs/JOB-3.md`.\n */\nimport { randomUUID } from 'node:crypto';\nimport { Inject, Injectable, Logger, Optional } from '@nestjs/common';\nimport { and, desc, eq, gt, inArray, isNotNull, ne, notInArray, sql } from 'drizzle-orm';\nimport type { DrizzleClient } from '../../types/drizzle';\nimport type { DrizzleTransaction } from '../events/event-bus.protocol';\nimport { DRIZZLE } from '../../constants/tokens';\nimport {\n  jobRuns,\n  jobs,\n  type JobDefinitionRow,\n  type JobRunRow,\n} from './job-orchestration.schema';\nimport type {\n  CancelOptions,\n  IJobOrchestrator,\n  JobPoolDef,\n  JobRun,\n  JobUpsertEntry,\n  StartOptions,\n} from './job-orchestrator.protocol';\nimport {\n  JobCollisionError,\n  JobNotReplayableError,\n  JobTemplateFieldMissingError,\n  JobTypeNotFoundError,\n  MissingTenantIdError,\n} from './jobs-errors';\nimport { jobSteps } from './job-orchestration.schema';\nimport { JOBS_MULTI_TENANT, JOBS_LISTEN_NOTIFY } from './jobs-domain.tokens';\nimport { JOBS_WAKE_CHANNEL, pgNotify } from './pg-notify';\n\n/**\n * Terminal statuses — transitions into these are final. Used by `cancel`\n * (to short-circuit idempotently) and by `replay` (as the guard gate).\n */\nexport const TERMINAL_STATUSES = [\n  'completed',\n  'failed',\n  'timed_out',\n  'canceled',\n] as const;\ntype TerminalStatus = (typeof TERMINAL_STATUSES)[number];\ntype JobRunStatus = JobRunRow['status'];\n\n/** Statuses excluded from dedupe window matches per ADR-022. */\nconst DEDUPE_EXCLUDED_STATUSES: JobRunStatus[] = ['canceled', 'failed'];\n/** Statuses that count as in-flight for concurrency collision checks. */\nconst IN_FLIGHT_STATUSES: JobRunStatus[] = ['pending', 'running'];\n\n/**\n * Substitute `{{field}}` placeholders against the input payload.\n *\n * Implementation decision (JOB-3, 2026-04-19): simple `{{field}}` single-key\n * substitution, no dotted paths, no Mustache/Handlebars dependency. A missing\n * field throws `JobTemplateFieldMissingError` synchronously — cheaper than\n * discovering the misconfiguration at claim time.\n */\nexport function evaluateKeyTemplate(\n  template: string,\n  input: Record<string, unknown>,\n): string {\n  return template.replace(/\\{\\{\\s*([a-zA-Z0-9_]+)\\s*\\}\\}/g, (_match, field: string) => {\n    const value = input[field];\n    if (value === undefined || value === null) {\n      throw new JobTemplateFieldMissingError(template, field);\n    }\n    return String(value);\n  });\n}\n\n@Injectable()\nexport class DrizzleJobOrchestrator implements IJobOrchestrator {\n  // TODO(logging-subsystem): swap to ILogger once ADR-028 lands\n  private readonly logger = new Logger(DrizzleJobOrchestrator.name);\n\n  constructor(\n    @Inject(DRIZZLE) private readonly db: DrizzleClient,\n    @Inject(JOBS_MULTI_TENANT) private readonly multiTenant: boolean,\n    // LISTEN-NOTIFY-1 — when true, `start()` emits an in-tx\n    // `pg_notify(codegen_jobs_wake, <pool>)` so a `listen_notify` worker wakes\n    // on enqueue-commit. `@Optional()` defaulting to false so direct\n    // construction (integration tests not going through DI) keeps working.\n    @Optional()\n    @Inject(JOBS_LISTEN_NOTIFY)\n    private readonly listenNotify: boolean = false,\n  ) {}\n\n  /**\n   * JOB-8 — resolve `tenantId` for a mutating / targeted-read call.\n   * Returns the tenant value that should be written to the row (or compared\n   * against in a WHERE clause). When `multiTenant` is off, the column is\n   * forced to `null` regardless of what callers pass. When on, `undefined`\n   * throws; `null` and strings pass through untouched.\n   */\n  private resolveTenantId(\n    method: string,\n    tenantId: string | null | undefined,\n  ): string | null {\n    if (!this.multiTenant) return null;\n    if (tenantId === undefined) throw new MissingTenantIdError(method);\n    return tenantId;\n  }\n\n  // ==========================================================================\n  // start\n  // ==========================================================================\n\n  async start(\n    type: string,\n    input: unknown,\n    opts: StartOptions = {},\n    tx?: DrizzleTransaction,\n  ): Promise<JobRun> {\n    const payload = (input ?? {}) as Record<string, unknown>;\n\n    // JOB-8 — resolve tenant gate up front so `multi_tenant=true` +\n    // undefined surfaces before any row is touched.\n    const tenantId = this.resolveTenantId('start', opts.tenantId);\n\n    // BRIDGE-7: thread the optional caller tx through every read/write\n    // in this method so EventFlowService.publishAndStart can bundle the\n    // outbox insert, the eager job_run insert, and (for Case B) the\n    // bridge_delivery pre-write into a single transaction.\n    const client = (tx ?? this.db) as DrizzleClient;\n\n    // 1a. Load job definition.\n    const [def] = await client\n      .select()\n      .from(jobs)\n      .where(eq(jobs.type, type))\n      .limit(1);\n    if (!def) throw new JobTypeNotFoundError(type);\n    const definition = def as JobDefinitionRow;\n\n    // 1b. Dedupe check.\n    if (definition.dedupeKeyTemplate && definition.dedupeWindowMs) {\n      const dedupeKey = evaluateKeyTemplate(definition.dedupeKeyTemplate, payload);\n      const windowStart = new Date(Date.now() - definition.dedupeWindowMs);\n      const existing = await client\n        .select()\n        .from(jobRuns)\n        .where(\n          and(\n            eq(jobRuns.jobType, type),\n            eq(jobRuns.dedupeKey, dedupeKey),\n            gt(jobRuns.createdAt, windowStart),\n            // status NOT IN ('canceled', 'failed')\n            notInStatus(DEDUPE_EXCLUDED_STATUSES),\n          ),\n        )\n        .orderBy(desc(jobRuns.createdAt))\n        .limit(1);\n      if (existing.length > 0) {\n        return existing[0] as JobRun;\n      }\n    }\n\n    // 1c. Concurrency collision check.\n    let concurrencyKey: string | null = null;\n    if (definition.concurrencyKeyTemplate) {\n      concurrencyKey = evaluateKeyTemplate(\n        definition.concurrencyKeyTemplate,\n        payload,\n      );\n      const inFlight = await client\n        .select()\n        .from(jobRuns)\n        .where(\n          and(\n            eq(jobRuns.concurrencyKey, concurrencyKey),\n            inArray(jobRuns.status, IN_FLIGHT_STATUSES),\n          ),\n        )\n        .limit(1);\n      if (inFlight.length > 0) {\n        const incumbent = inFlight[0] as JobRun;\n        switch (definition.collisionMode) {\n          case 'reject':\n            throw new JobCollisionError(type, concurrencyKey, incumbent);\n          case 'replace':\n            // JOB-8 — thread the incumbent's own tenantId through the\n            // internal cascade. Without this, every `replace`-collision\n            // start() under multiTenant=true throws MissingTenantIdError\n            // from the inner cancel() call instead of cancelling the\n            // incumbent. Mirrors the memory backend's `cancelLocked(\n            // incumbent.id, ..., incumbent.tenantId)` pattern.\n            await this.cancel(incumbent.id, {\n              cascade: true,\n              reason: 'replaced',\n              tenantId: incumbent.tenantId,\n            });\n            break;\n          case 'queue':\n            // Fall through — row is inserted; claim query gates it until\n            // the incumbent transitions (see JobWorker.processRun queue gate).\n            break;\n        }\n      }\n    }\n\n    // 1d. Resolve id + rootRunId, INSERT.\n    const newId = randomUUID();\n    let rootRunId: string = newId;\n    if (opts.parentRunId) {\n      const [parent] = await client\n        .select({ rootRunId: jobRuns.rootRunId })\n        .from(jobRuns)\n        .where(eq(jobRuns.id, opts.parentRunId))\n        .limit(1);\n      if (!parent) {\n        throw new Error(\n          `parentRunId ${opts.parentRunId} does not reference an existing job_run`,\n        );\n      }\n      rootRunId = parent.rootRunId;\n    }\n\n    const dedupeKey =\n      definition.dedupeKeyTemplate\n        ? evaluateKeyTemplate(definition.dedupeKeyTemplate, payload)\n        : null;\n\n    const [inserted] = await client\n      .insert(jobRuns)\n      .values({\n        id: newId,\n        jobType: type,\n        jobVersion: definition.version,\n        parentRunId: opts.parentRunId ?? null,\n        rootRunId,\n        parentClosePolicy: opts.parentClosePolicy ?? 'terminate',\n        scopeEntityType: opts.scope?.entityType ?? null,\n        scopeEntityId: opts.scope?.entityId ?? null,\n        tenantId,\n        tags: opts.tags ?? {},\n        pool: opts.pool ?? definition.pool,\n        priority: opts.priority ?? definition.priorityDefault,\n        concurrencyKey,\n        dedupeKey,\n        status: 'pending',\n        input: payload,\n        output: null,\n        error: null,\n        triggerSource: opts.triggerSource ?? 'manual',\n        triggerRef: opts.triggerRef ?? null,\n        runAt: opts.runAt ?? new Date(),\n        startedAt: null,\n        finishedAt: null,\n        claimedAt: null,\n        attempts: 0,\n      })\n      .returning();\n\n    // LISTEN-NOTIFY-1 — wake a listening worker the instant this enqueue\n    // commits. Emitted through the SAME `client` (the caller's tx when one was\n    // passed, else the pool) so delivery is gated on commit — a rolled-back\n    // enqueue emits no phantom wake (D2). The pool name is the payload; the\n    // worker re-runs its own pool-filtered claim query on wake. Polling is the\n    // fallback, so a failed notify is non-fatal: log + continue.\n    if (this.listenNotify) {\n      const wakePool = (inserted as JobRunRow).pool;\n      try {\n        await pgNotify(client, JOBS_WAKE_CHANNEL, wakePool);\n      } catch (err) {\n        this.logger.warn(\n          `pg_notify(${JOBS_WAKE_CHANNEL}, ${wakePool}) failed for run ` +\n            `${(inserted as JobRunRow).id}: ${(err as Error).message} ` +\n            `(non-fatal — interval polling still claims the run).`,\n        );\n      }\n    }\n\n    return inserted as JobRun;\n  }\n\n  // ==========================================================================\n  // cancel\n  // ==========================================================================\n\n  async cancel(runId: string, opts: CancelOptions = {}): Promise<void> {\n    // JOB-8 — resolve tenant gate up front (strict undefined-throws).\n    const tenantId = this.resolveTenantId('cancel', opts.tenantId);\n\n    // Load target.\n    const [target] = await this.db\n      .select()\n      .from(jobRuns)\n      .where(eq(jobRuns.id, runId))\n      .limit(1);\n    if (!target) return;\n    // JOB-8 — cross-tenant cancel is a silent no-op (no existence leak).\n    if (this.multiTenant && target.tenantId !== tenantId) return;\n    if (TERMINAL_STATUSES.includes(target.status as TerminalStatus)) {\n      return; // idempotent\n    }\n\n    // Atomic transition, guarded against concurrent terminal moves.\n    const [cancelled] = await this.db\n      .update(jobRuns)\n      .set({\n        status: 'canceled',\n        finishedAt: new Date(),\n        updatedAt: new Date(),\n      })\n      .where(\n        and(eq(jobRuns.id, runId), notInStatus([...TERMINAL_STATUSES])),\n      )\n      .returning();\n\n    if (!cancelled) return; // lost the race; already terminal\n\n    if (opts.cascade === false) return;\n\n    // Fetch descendants and branch on parent_close_policy.\n    const descendants = await this.db\n      .select()\n      .from(jobRuns)\n      .where(\n        and(\n          eq(jobRuns.rootRunId, target.rootRunId),\n          ne(jobRuns.id, runId),\n          notInStatus([...TERMINAL_STATUSES]),\n        ),\n      );\n\n    for (const child of descendants) {\n      const policy = (child as JobRunRow).parentClosePolicy;\n      if (policy === 'abandon') continue;\n      // 'terminate' | 'cancel' — both transition the child to canceled.\n      await this.db\n        .update(jobRuns)\n        .set({\n          status: 'canceled',\n          finishedAt: new Date(),\n          updatedAt: new Date(),\n        })\n        .where(\n          and(\n            eq(jobRuns.id, (child as JobRunRow).id),\n            notInStatus([...TERMINAL_STATUSES]),\n          ),\n        );\n    }\n\n    void opts.reason; // reserved for future audit logging\n  }\n\n  // ==========================================================================\n  // replay\n  // ==========================================================================\n\n  async replay(runId: string): Promise<JobRun> {\n    // Load target + its job definition (we need replay_from).\n    const [target] = await this.db\n      .select()\n      .from(jobRuns)\n      .where(eq(jobRuns.id, runId))\n      .limit(1);\n    if (!target) {\n      throw new Error(`replay: run ${runId} not found`);\n    }\n    const run = target as JobRunRow;\n    if (!TERMINAL_STATUSES.includes(run.status as TerminalStatus)) {\n      throw new JobNotReplayableError(runId, run.status);\n    }\n\n    const [def] = await this.db\n      .select()\n      .from(jobs)\n      .where(eq(jobs.type, run.jobType))\n      .limit(1);\n    if (!def) throw new JobTypeNotFoundError(run.jobType);\n    const mode = (def as JobDefinitionRow).replayFrom;\n\n    // Atomic: step reset + run reset must commit together.\n    const result = await this.db.transaction(async (tx) => {\n      if (mode === 'scratch') {\n        await tx.delete(jobSteps).where(eq(jobSteps.jobRunId, runId));\n      } else if (mode === 'last_step') {\n        // Delete only non-completed step rows — completed steps stay memoised.\n        await tx\n          .delete(jobSteps)\n          .where(\n            and(eq(jobSteps.jobRunId, runId), ne(jobSteps.status, 'completed')),\n          );\n      } else {\n        // 'last_checkpoint' — Phase 1 has no explicit checkpoint markers, so\n        // behaviour collapses to `last_step`. See docs/specs/JOB-3.md\n        // \"Implementation Decisions\" — planned divergence in a later phase.\n        await tx\n          .delete(jobSteps)\n          .where(\n            and(eq(jobSteps.jobRunId, runId), ne(jobSteps.status, 'completed')),\n          );\n      }\n\n      const [updated] = await tx\n        .update(jobRuns)\n        .set({\n          status: 'pending',\n          attempts: 0,\n          runAt: new Date(),\n          startedAt: null,\n          finishedAt: null,\n          claimedAt: null,\n          error: null,\n          output: null,\n          updatedAt: new Date(),\n        })\n        .where(eq(jobRuns.id, runId))\n        .returning();\n      return updated as JobRunRow;\n    });\n\n    return result as JobRun;\n  }\n\n  // ==========================================================================\n  // upsertJobRows — boot-time materialisation of `job` definitions\n  // ==========================================================================\n\n  /**\n   * Hash-gated `INSERT … ON CONFLICT (type) DO UPDATE … WHERE` per Q3\n   * resolution (2026-04-19): the `UPDATE` branch executes only when one\n   * of the persisted metadata fields differs from the incoming payload;\n   * `version` bumps only on real change; concurrent boots with identical\n   * content are idempotent no-ops.\n   *\n   * Why this shape (not `DO NOTHING`, not advisory locks):\n   *   - `DO NOTHING` would let an old-version instance leave a stale row\n   *     that a new-version instance can't overwrite during a rolling deploy.\n   *   - Advisory locks add latency and leak risk under crashes.\n   *   - The `WHERE … IS DISTINCT FROM …` clause makes the conditional\n   *     atomic — no read-modify-write race on `version` between concurrent\n   *     boots.\n   *\n   * Orphan detection: a single `SELECT type FROM job WHERE type NOT IN (...)`\n   * returns the types present in DB but absent from `entries`. Caller (boot\n   * validator) decides whether to throw `BootValidationError`.\n   */\n  async upsertJobRows(\n    entries: JobUpsertEntry[],\n    poolConfig: ReadonlyMap<string, JobPoolDef>,\n  ): Promise<{ orphaned: string[] }> {\n    void poolConfig; // pool validation is the module's responsibility; orchestrator just persists\n\n    for (const entry of entries) {\n      const meta = entry.meta;\n      const pool = meta.pool ?? 'batch';\n      const retryPolicy = meta.retry ?? {\n        attempts: 1,\n        backoff: 'fixed' as const,\n        baseMs: 0,\n      };\n      const concurrencyKeyTemplate =\n        (meta.concurrency as { key?: unknown } | undefined)?.key;\n      const concurrencyKeyTemplateStr =\n        typeof concurrencyKeyTemplate === 'string' ? concurrencyKeyTemplate : null;\n      const collisionMode =\n        (meta.concurrency?.collisionMode as JobDefinitionRow['collisionMode']) ??\n        'queue';\n      const dedupeKeyTemplate =\n        (meta.dedupe as { key?: unknown } | undefined)?.key;\n      const dedupeKeyTemplateStr =\n        typeof dedupeKeyTemplate === 'string' ? dedupeKeyTemplate : null;\n      const dedupeWindowMs = meta.dedupe?.windowMs ?? null;\n      const timeoutMs = meta.timeoutMs ?? null;\n      const replayFrom = meta.replayFrom ?? 'last_checkpoint';\n      const scopeEntityType = meta.scope?.entity ?? null;\n      // Q3 resolution: priority_default and replay_from are part of the\n      // hashed metadata even though they aren't currently set via decorator\n      // metadata above (priority_default has no `@JobHandler` field yet).\n      // Default to 0 to keep UPDATE branch quiet across deploys.\n      const priorityDefault = 0;\n\n      // Hash-gated upsert: every metadata column appears in the WHERE clause\n      // so the UPDATE branch only fires on a real change. `version` bumps\n      // exactly when the WHERE matches.\n      await this.db\n        .insert(jobs)\n        .values({\n          type: entry.type,\n          version: 1,\n          pool,\n          scopeEntityType,\n          retryPolicy,\n          timeoutMs,\n          concurrencyKeyTemplate: concurrencyKeyTemplateStr,\n          collisionMode,\n          dedupeKeyTemplate: dedupeKeyTemplateStr,\n          dedupeWindowMs,\n          priorityDefault,\n          replayFrom,\n        })\n        .onConflictDoUpdate({\n          target: jobs.type,\n          set: {\n            pool: sql`EXCLUDED.pool`,\n            scopeEntityType: sql`EXCLUDED.scope_entity_type`,\n            retryPolicy: sql`EXCLUDED.retry_policy`,\n            timeoutMs: sql`EXCLUDED.timeout_ms`,\n            concurrencyKeyTemplate: sql`EXCLUDED.concurrency_key_template`,\n            collisionMode: sql`EXCLUDED.collision_mode`,\n            dedupeKeyTemplate: sql`EXCLUDED.dedupe_key_template`,\n            dedupeWindowMs: sql`EXCLUDED.dedupe_window_ms`,\n            priorityDefault: sql`EXCLUDED.priority_default`,\n            replayFrom: sql`EXCLUDED.replay_from`,\n            version: sql`${jobs.version} + 1`,\n            updatedAt: sql`now()`,\n          },\n          // The hash gate: every field listed in the Q3 resolution appears\n          // here. `IS DISTINCT FROM` is the null-safe inequality operator;\n          // jsonb cast to text gives stable comparison without invoking a\n          // dedicated hash column (avoids a JOB-1 schema migration).\n          setWhere: sql`\n            ${jobs.pool} IS DISTINCT FROM EXCLUDED.pool OR\n            ${jobs.retryPolicy}::text IS DISTINCT FROM EXCLUDED.retry_policy::text OR\n            ${jobs.timeoutMs} IS DISTINCT FROM EXCLUDED.timeout_ms OR\n            ${jobs.concurrencyKeyTemplate} IS DISTINCT FROM EXCLUDED.concurrency_key_template OR\n            ${jobs.collisionMode} IS DISTINCT FROM EXCLUDED.collision_mode OR\n            ${jobs.dedupeKeyTemplate} IS DISTINCT FROM EXCLUDED.dedupe_key_template OR\n            ${jobs.dedupeWindowMs} IS DISTINCT FROM EXCLUDED.dedupe_window_ms OR\n            ${jobs.priorityDefault} IS DISTINCT FROM EXCLUDED.priority_default OR\n            ${jobs.replayFrom} IS DISTINCT FROM EXCLUDED.replay_from OR\n            ${jobs.scopeEntityType} IS DISTINCT FROM EXCLUDED.scope_entity_type\n          `,\n        });\n    }\n\n    // Orphan detection: any `job` row whose type is not in the registry.\n    const types = entries.map((e) => e.type);\n    const orphans =\n      types.length === 0\n        ? await this.db.select({ type: jobs.type }).from(jobs)\n        : await this.db\n            .select({ type: jobs.type })\n            .from(jobs)\n            .where(notInArray(jobs.type, types));\n\n    return { orphaned: orphans.map((o) => o.type) };\n  }\n}\n\n// ─── Helpers ────────────────────────────────────────────────────────────────\n\nfunction notInStatus(statuses: JobRunStatus[]) {\n  // Drizzle's inArray composes with `not` via negation helper; use raw sql\n  // to stay readable. `inArray` + `.not()` isn't idiomatic in 0.45.\n  const negated = statuses.map((s) => ne(jobRuns.status, s));\n  return and(...negated);\n}\n\n// `isNotNull` + `gt` imports are retained for potential future use; silence\n// unused-import lint by re-exporting via `void`.\nvoid isNotNull;\n"],"mappings":"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","names":["dedupeKey"]}

package/dist/{chunk-RC23QROE.js → chunk-JM3T27ZW.js}

@@ -1,3 +1,6 @@
+import {
+  jobRuns
+} from "./chunk-OKXZ63IA.js";
 import {
   JOB_HANDLER_REGISTRY
 } from "./chunk-CO6LUM72.js";
@@ -5,10 +8,11 @@ import {
   JOB_ORCHESTRATOR,
   JOB_RUN_SERVICE,
   JOB_STEP_SERVICE
-} from "./chunk-BIO6F7YI.js";
+} from "./chunk-ZPL74UQN.js";
 import {
-  jobRuns
-} from "./chunk-OKXZ63IA.js";
+  JOBS_WAKE_CHANNEL,
+  PgNotifyListener
+} from "./chunk-MYQIQ27N.js";
 import {
   tokenKey
 } from "./chunk-GYGNEQSC.js";
@@ -96,6 +100,7 @@ var JobWorker = class {
     this.staleSweeperIntervalMs = options.staleSweeperIntervalMs ?? DEFAULT_STALE_SWEEPER_INTERVAL_MS;
     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;
       this.sigtermHandled = true;
@@ -120,6 +125,14 @@ var JobWorker = class {
   staleSweeperIntervalMs;
   staleThresholdMs;
   shutdownTimeoutMs;
+  // LISTEN-NOTIFY-1 — dedicated listener + debounce state. `null` when
+  // `listenNotify` is off (the common case); polling is the only driver then.
+  listenNotifyEnabled;
+  notifyListener = null;
+  /** True while a wake-driven claim cycle is in flight (debounce gate). */
+  wakeDraining = false;
+  /** A notify arrived mid-cycle → re-check once when the cycle ends. */
+  wakeRecheckPending = false;
   // ============================================================================
   // Lifecycle
   // ============================================================================
@@ -131,6 +144,59 @@ var JobWorker = class {
       void this.sweepStaleClaims();
     }, this.staleSweeperIntervalMs);
     process.on("SIGTERM", this.sigtermHandler);
+    if (this.listenNotifyEnabled) {
+      const pool = this.db.$client;
+      if (!pool || typeof pool.connect !== "function") {
+        this.logger.warn(
+          `listen_notify enabled but the Drizzle client exposes no pg Pool ($client.connect missing) \u2014 falling back to interval polling only.`
+        );
+      } else {
+        this.notifyListener = new PgNotifyListener({
+          channel: JOBS_WAKE_CHANNEL,
+          pool,
+          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).
+   */
+  onWake(payload) {
+    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.
+   */
+  async drainOnWake() {
+    this.wakeDraining = true;
+    try {
+      do {
+        this.wakeRecheckPending = false;
+        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() {
     if (this.shuttingDown) {
@@ -147,6 +213,14 @@ var JobWorker = class {
       this.sweeperTimer = null;
     }
     process.removeListener("SIGTERM", this.sigtermHandler);
+    if (this.notifyListener) {
+      try {
+        await this.notifyListener.stop();
+      } catch (err) {
+        this.logger.error(`notify listener stop failed: ${err.message}`);
+      }
+      this.notifyListener = null;
+    }
     await this.drainInFlight();
     try {
       await this.db.update(jobRuns).set({ status: "pending", claimedAt: null, startedAt: null }).where(
@@ -444,4 +518,4 @@ export {
   buildStaleSweepQuery,
   JobWorker
 };
-//# sourceMappingURL=chunk-RC23QROE.js.map
+//# sourceMappingURL=chunk-JM3T27ZW.js.map