@pattern-stack/codegen 0.15.3 → 0.16.1

package/dist/src/index.d.ts

@@ -1681,11 +1681,11 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     }>, z.ZodObject<{
         mode: z.ZodLiteral<"webhook">;
         webhook: z.ZodObject<{
-            eventIdField: z.ZodString;
+            eventIdField: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         }, {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         }>;
         mapping: z.ZodArray<z.ZodObject<{
             source: z.ZodString;
@@ -1715,7 +1715,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         }>, "many">>;
     }, "strip", z.ZodTypeAny, {
         webhook: {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         };
         mode: "webhook";
         mapping: {
@@ -1730,7 +1730,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         }[];
     }, {
         webhook: {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         };
         mode: "webhook";
         mapping: {
@@ -2156,7 +2156,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         }[];
     } | {
         webhook: {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         };
         mode: "webhook";
         mapping: {
@@ -2366,7 +2366,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         }[] | undefined;
     } | {
         webhook: {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         };
         mode: "webhook";
         mapping: {
@@ -2576,7 +2576,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         }[];
     } | {
         webhook: {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         };
         mode: "webhook";
         mapping: {
@@ -2786,7 +2786,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         }[] | undefined;
     } | {
         webhook: {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         };
         mode: "webhook";
         mapping: {
@@ -2996,7 +2996,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         }[];
     } | {
         webhook: {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         };
         mode: "webhook";
         mapping: {
@@ -3206,7 +3206,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         }[] | undefined;
     } | {
         webhook: {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         };
         mode: "webhook";
         mapping: {

package/dist/src/index.js

@@ -44,27 +44,27 @@ import {
   validateOrchestrationProject,
   validatePatternComposition,
   validatePatternProject
-} from "../chunk-32DOFN3T.js";
+} from "../chunk-2WDX6I7T.js";
 import "../chunk-KVOWSC5S.js";
-import "../chunk-GCYKMF22.js";
+import "../chunk-24WXSC3C.js";
 import "../chunk-EO2QPOKH.js";
 import "../chunk-PRWIX6UW.js";
-import "../chunk-DCCZB4UC.js";
+import "../chunk-XWBK3XJK.js";
 import "../chunk-AHV4GDYM.js";
-import "../chunk-SR7F3TJY.js";
+import "../chunk-YK5JEVLX.js";
 import "../chunk-SQDOBLBP.js";
-import "../chunk-3NMCDN7L.js";
+import "../chunk-5TK7MEN4.js";
 import "../chunk-4KNXX6TI.js";
 import "../chunk-3CJFPU6Q.js";
-import "../chunk-OGIZXGPY.js";
+import "../chunk-TDEHU73T.js";
+import "../chunk-S7C6TIIF.js";
 import "../chunk-MZ6GV4YF.js";
 import "../chunk-LG57S2SC.js";
 import "../chunk-HNWZFNKP.js";
-import "../chunk-WWGYCIJX.js";
+import "../chunk-43SBT72G.js";
 import "../chunk-4MF3HKJA.js";
-import "../chunk-YLPAPPLW.js";
+import "../chunk-TIZXQU26.js";
 import "../chunk-36U5UGIO.js";
-import "../chunk-S7C6TIIF.js";
 import "../chunk-U64T4YZE.js";
 import "../chunk-2E224ZSN.js";
 export {

package/package.json

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

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

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

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

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

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

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

package/runtime/subsystems/integration/detection-config.schema.ts

@@ -22,10 +22,12 @@
  *     primitive while emitting `Change<T>.source = 'cdc'`. Long-lived
  *     streaming CDC (SFDC Pub-Sub, Debezium) is a separate primitive
  *     deferred to #226-8.
- *   - `webhook` mode requires `eventIdField` so `WebhookChangeSource<T>`
- *     can populate `Change<T>.dedupKey` from the inbound staging row.
+ *   - `webhook` mode's `eventIdField` is optional: `WebhookChangeSource<T>`
+ *     prefers an `eventId` yielded by the queue iterator and falls back to the
+ *     `eventIdField` record extraction (precedence: yielded eventId >
+ *     eventIdField extraction > undefined dedupKey).
  */
-import { z } from 'zod';
+import { z } from "zod";
 
 // ============================================================================
 // Field mapping — provider field → canonical target
@@ -37,9 +39,9 @@ import { z } from 'zod';
  * etc.); the schema does not enumerate transforms — adapters interpret them.
  */
 export const FieldMappingSchema = z.object({
-  source: z.string().min(1),
-  target: z.string().min(1),
-  transform: z.string().min(1).optional(),
+	source: z.string().min(1),
+	target: z.string().min(1),
+	transform: z.string().min(1).optional(),
 });
 
 export type FieldMapping = z.infer<typeof FieldMappingSchema>;
@@ -54,9 +56,9 @@ export type FieldMapping = z.infer<typeof FieldMappingSchema>;
  * adapters interpret per provider.
  */
 export const ResolvedFilterSchema = z.object({
-  field: z.string().min(1),
-  op: z.enum(['eq', 'neq', 'in', 'nin', 'gt', 'gte', 'lt', 'lte']),
-  value: z.unknown(),
+	field: z.string().min(1),
+	op: z.enum(["eq", "neq", "in", "nin", "gt", "gte", "lt", "lte"]),
+	value: z.unknown(),
 });
 
 export type ResolvedFilter = z.infer<typeof ResolvedFilterSchema>;
@@ -66,23 +68,23 @@ export type ResolvedFilter = z.infer<typeof ResolvedFilterSchema>;
 // ============================================================================
 
 const SystemModstampCursorSchema = z.object({
-  kind: z.literal('systemModstamp'),
-  field: z.string().min(1),
+	kind: z.literal("systemModstamp"),
+	field: z.string().min(1),
 });
 
 const ReplayIdCursorSchema = z.object({
-  kind: z.literal('replayId'),
-  field: z.string().min(1),
+	kind: z.literal("replayId"),
+	field: z.string().min(1),
 });
 
 const TimestampCursorSchema = z.object({
-  kind: z.literal('timestamp'),
-  field: z.string().min(1),
+	kind: z.literal("timestamp"),
+	field: z.string().min(1),
 });
 
 const EventIdCursorSchema = z.object({
-  kind: z.literal('eventId'),
-  field: z.string().min(1),
+	kind: z.literal("eventId"),
+	field: z.string().min(1),
 });
 
 /**
@@ -91,8 +93,8 @@ const EventIdCursorSchema = z.object({
  * `field` is metadata for codegen/adapters (the response key the token lives on).
  */
 const HistoryIdCursorSchema = z.object({
-  kind: z.literal('historyId'),
-  field: z.string().min(1),
+	kind: z.literal("historyId"),
+	field: z.string().min(1),
 });
 
 /**
@@ -100,17 +102,17 @@ const HistoryIdCursorSchema = z.object({
  * same divisibility profile as `historyId`.
  */
 const SyncTokenCursorSchema = z.object({
-  kind: z.literal('syncToken'),
-  field: z.string().min(1),
+	kind: z.literal("syncToken"),
+	field: z.string().min(1),
 });
 
-export const CursorStrategySchema = z.discriminatedUnion('kind', [
-  SystemModstampCursorSchema,
-  ReplayIdCursorSchema,
-  TimestampCursorSchema,
-  EventIdCursorSchema,
-  HistoryIdCursorSchema,
-  SyncTokenCursorSchema,
+export const CursorStrategySchema = z.discriminatedUnion("kind", [
+	SystemModstampCursorSchema,
+	ReplayIdCursorSchema,
+	TimestampCursorSchema,
+	EventIdCursorSchema,
+	HistoryIdCursorSchema,
+	SyncTokenCursorSchema,
 ]);
 
 export type CursorStrategy = z.infer<typeof CursorStrategySchema>;
@@ -135,18 +137,20 @@ export type CursorStrategy = z.infer<typeof CursorStrategySchema>;
  * `eventId` is classified atomic conservatively: a generic opaque id is treated
  * all-or-nothing unless a concrete strategy proves it monotonically resumable.
  */
-export const CURSOR_DIVISIBILITY: Readonly<Record<CursorStrategy['kind'], boolean>> = {
-  systemModstamp: true,
-  timestamp: true,
-  replayId: true,
-  eventId: false,
-  historyId: false,
-  syncToken: false,
+export const CURSOR_DIVISIBILITY: Readonly<
+	Record<CursorStrategy["kind"], boolean>
+> = {
+	systemModstamp: true,
+	timestamp: true,
+	replayId: true,
+	eventId: false,
+	historyId: false,
+	syncToken: false,
 };
 
 /** Predicate form of {@link CURSOR_DIVISIBILITY}. */
-export function isDivisibleCursor(kind: CursorStrategy['kind']): boolean {
-  return CURSOR_DIVISIBILITY[kind];
+export function isDivisibleCursor(kind: CursorStrategy["kind"]): boolean {
+	return CURSOR_DIVISIBILITY[kind];
 }
 
 // ============================================================================
@@ -159,19 +163,25 @@ export function isDivisibleCursor(kind: CursorStrategy['kind']): boolean {
  * `field` — used for Stripe-style event endpoints. Defaults to `'poll'`.
  */
 export const PollDetectionSchema = z.object({
-  cursor: CursorStrategySchema,
-  provenance: z.enum(['poll', 'cdc']).optional(),
+	cursor: CursorStrategySchema,
+	provenance: z.enum(["poll", "cdc"]).optional(),
 });
 
 export type PollDetection = z.infer<typeof PollDetectionSchema>;
 
 /**
- * Webhook-mode block. `eventIdField` names the column in the consumer-owned
- * inbound staging row that `WebhookChangeSource<T>` reads to set
- * `Change<T>.dedupKey`.
+ * Webhook-mode block. `eventIdField`, when present, names the field on the
+ * emitted canonical record that `WebhookChangeSource<T>` reads to set
+ * `Change<T>.dedupKey` — used only as the fallback when the queue iterator
+ * does NOT yield an `eventId` alongside the record.
+ *
+ * `eventIdField` is **optional**: a queue iterator that always yields an
+ * `eventId` (vendor delivery metadata, the preferred channel) need not declare
+ * a record field for it. dedupKey precedence is: yielded `eventId` >
+ * `eventIdField` record extraction > undefined.
  */
 export const WebhookDetectionSchema = z.object({
-  eventIdField: z.string().min(1),
+	eventIdField: z.string().min(1).optional(),
 });
 
 export type WebhookDetection = z.infer<typeof WebhookDetectionSchema>;
@@ -181,17 +191,17 @@ export type WebhookDetection = z.infer<typeof WebhookDetectionSchema>;
 // ============================================================================
 
 const PollModeSchema = z.object({
-  mode: z.literal('poll'),
-  poll: PollDetectionSchema,
-  mapping: z.array(FieldMappingSchema).min(1),
-  filters: z.array(ResolvedFilterSchema).default([]),
+	mode: z.literal("poll"),
+	poll: PollDetectionSchema,
+	mapping: z.array(FieldMappingSchema).min(1),
+	filters: z.array(ResolvedFilterSchema).default([]),
 });
 
 const WebhookModeSchema = z.object({
-  mode: z.literal('webhook'),
-  webhook: WebhookDetectionSchema,
-  mapping: z.array(FieldMappingSchema).min(1),
-  filters: z.array(ResolvedFilterSchema).default([]),
+	mode: z.literal("webhook"),
+	webhook: WebhookDetectionSchema,
+	mapping: z.array(FieldMappingSchema).min(1),
+	filters: z.array(ResolvedFilterSchema).default([]),
 });
 
 /**
@@ -201,9 +211,9 @@ const WebhookModeSchema = z.object({
  * (Stripe-style event endpoints) is expressed via `mode: 'poll'` with
  * `poll.provenance: 'cdc'`.
  */
-export const DetectionConfigSchema = z.discriminatedUnion('mode', [
-  PollModeSchema,
-  WebhookModeSchema,
+export const DetectionConfigSchema = z.discriminatedUnion("mode", [
+	PollModeSchema,
+	WebhookModeSchema,
 ]);
 
 export type DetectionConfig = z.infer<typeof DetectionConfigSchema>;