@pattern-stack/codegen 0.15.1 → 0.15.3

package/package.json

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

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

@@ -32,6 +32,7 @@
  */
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
 import { randomUUID } from 'node:crypto';
+import { eq } from 'drizzle-orm';
 
 import type { DomainEvent, DrizzleTransaction } from '../events/event-bus.protocol';
 import { bridgeDelivery } from './bridge-delivery.schema';
@@ -143,7 +144,38 @@ export class BridgeOutboxDrainHook implements IBridgeOutboxDrainHook {
       const deliveryId = randomUUID();
       const wrapperRunId = randomUUID();
 
-      // 1. bridge_delivery insert with ON CONFLICT DO NOTHING + RETURNING.
+      // FK ORDER (BRIDGE / 0.15.2): `bridge_delivery.wrapper_run_id` REFERENCES
+      // `job_run(id)` is a plain (non-deferrable) FK, so the referenced
+      // wrapper `job_run` MUST exist before the delivery row that points at it
+      // is inserted — otherwise Postgres rejects the delivery insert
+      // immediately. (The codegen unit tests mock `tx`, so they never
+      // exercised this ordering against a real FK; package-mode bridge
+      // deliveries are the first to do so.) We therefore insert the wrapper
+      // run FIRST, then the delivery. Idempotency is unchanged: the delivery
+      // keeps its `ON CONFLICT (event_id, trigger_id) DO NOTHING RETURNING`,
+      // and when the delivery conflicts (outbox replay or facade-eager Case B)
+      // we DELETE the just-inserted orphan wrapper run in the same tx, so a
+      // skipped delivery leaves no stray `job_run` for a worker to claim.
+
+      // 1. Wrapper job_run insert. We carry the deliveryId into the wrapper
+      //    input so BridgeDeliveryHandler.run(ctx) can locate the row via
+      //    repo.findDeliveryById(ctx.input.deliveryId).
+      await (tx as unknown as { insert: typeof client.insert })
+        .insert(jobRuns)
+        .values({
+          id: wrapperRunId,
+          jobType: BRIDGE_DELIVERY_JOB_TYPE,
+          jobVersion: 1,
+          rootRunId: wrapperRunId,
+          pool: wrapperPool,
+          status: 'pending',
+          input: { deliveryId },
+          triggerSource: 'event',
+          triggerRef: event.id,
+          tenantId,
+        });
+
+      // 2. bridge_delivery insert with ON CONFLICT DO NOTHING + RETURNING.
       const inserted = await (tx as unknown as {
         insert: typeof client.insert;
       })
@@ -162,30 +194,21 @@ export class BridgeOutboxDrainHook implements IBridgeOutboxDrainHook {
         .returning({ id: bridgeDelivery.id });
 
       if (inserted.length === 0) {
-        // Case B (facade pre-wrote `delivered`) or drain replay — skip
-        // wrapper insert for this trigger. Sibling triggers still fire.
+        // Case B (facade pre-wrote `delivered`) or drain replay — the delivery
+        // already exists, so this trigger is a no-op. Remove the orphan wrapper
+        // run we speculatively inserted above so no worker claims it. Sibling
+        // triggers still fire.
+        await (tx as unknown as {
+          delete: (table: unknown) => {
+            where: (cond: unknown) => Promise<unknown>;
+          };
+        })
+          .delete(jobRuns)
+          .where(eq(jobRuns.id, wrapperRunId));
         dedupSkips++;
         continue;
       }
 
-      // 2. Wrapper job_run insert. We carry the deliveryId into the
-      //    wrapper input so BridgeDeliveryHandler.run(ctx) can locate
-      //    the row via repo.findDeliveryById(ctx.input.deliveryId).
-      await (tx as unknown as { insert: typeof client.insert })
-        .insert(jobRuns)
-        .values({
-          id: wrapperRunId,
-          jobType: BRIDGE_DELIVERY_JOB_TYPE,
-          jobVersion: 1,
-          rootRunId: wrapperRunId,
-          pool: wrapperPool,
-          status: 'pending',
-          input: { deliveryId },
-          triggerSource: 'event',
-          triggerRef: event.id,
-          tenantId,
-        });
-
       delivered++;
     }
 

package/runtime/subsystems/index.ts

@@ -92,6 +92,33 @@ export type {
   SourcedRecord,
 } from './integration';
 
+// Integration — change-source primitives + DetectionConfig (#226-3/4, ADR-033).
+// Re-exported here so consumers authoring a webhook/poll drain across the
+// package boundary import them from `@pattern-stack/codegen/subsystems` instead
+// of reaching into the deep `.../integration/index` path. Surfaced by the
+// swe-brain dogfood (gap #6 — the first real consumer of `WebhookChangeSource`,
+// whose Slack inbound drain otherwise had to deep-import the primitive +
+// `DetectionConfigSchema`). Selective re-export (mirrors the curated
+// `IncrementalReadBase` / `ExecuteIntegrationUseCase` forwards above) — not
+// `export *`, to keep the `IntegrationRunSummary` name clash contained.
+export {
+  WebhookChangeSource,
+  PollChangeSource,
+  buildChangeSource,
+  DetectionConfigSchema,
+} from './integration';
+export type {
+  WebhookChangeSourceOptions,
+  WebhookFetchCallback,
+  WebhookFetchContext,
+  WebhookCursor,
+  PollChangeSourceOptions,
+  PollFetchCallback,
+  PollFetchContext,
+  PollCursor,
+  DetectionConfig,
+} from './integration';
+
 // Integration — assembly emission (RFC-0002). The generated per-entity sink
 // imports `IIntegrationSink`; the generated per-entity assembly module imports
 // `ExecuteIntegrationUseCase` + `INTEGRATION_CHANGE_SOURCE` + `INTEGRATION_SINK`

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

@@ -133,11 +133,14 @@ export class PollChangeSource<T> implements IChangeSource<T> {
     }
     const config = opts.config;
 
-    // Field mapping: locate the canonical `external_id` target. Adapters
-    // emit T already-mapped, but the primitive needs to know which key on
-    // T carries the external id so it can stamp `Change.externalId`. Source
-    // of truth is the mapping table — codegen emits it from YAML, the
-    // primitive reads it here.
+    // Field mapping: locate the entry whose canonical `target` is `external_id`.
+    // Adapters emit T already-mapped, but the primitive needs to know which key
+    // on T carries the external id so it can stamp `Change.externalId`. That key
+    // is the mapping's `source` (the field on the emitted record), NOT its
+    // `target` (the canonical column) — they differ whenever the canonical
+    // record is vendor-neutral camelCase (e.g. `source: 'externalId'` →
+    // `target: 'external_id'`). Source of truth is the mapping table — codegen
+    // emits it from YAML, the primitive reads it here.
     const externalIdMapping = config.mapping.find(
       (m) => m.target === 'external_id',
     );
@@ -146,7 +149,7 @@ export class PollChangeSource<T> implements IChangeSource<T> {
         "PollChangeSource: DetectionConfig.mapping must include an entry with target 'external_id' so emitted Change<T>.externalId can be populated",
       );
     }
-    this.externalIdSourceField = externalIdMapping.target;
+    this.externalIdSourceField = externalIdMapping.source;
 
     this.adapter = opts.adapter;
     this.filters = config.filters;
@@ -196,7 +199,7 @@ export class PollChangeSource<T> implements IChangeSource<T> {
       ];
       if (typeof externalIdRaw !== 'string' || externalIdRaw.length === 0) {
         throw new Error(
-          `PollChangeSource: record missing string '${this.externalIdSourceField}' — emitted records MUST carry the canonical external id keyed by the mapping target`,
+          `PollChangeSource: record missing string '${this.externalIdSourceField}' — emitted records MUST carry the canonical external id keyed by the mapping source`,
         );
       }
       let dedupKey: string | undefined;

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

@@ -9,8 +9,9 @@
  *   - canonical `Change<T>.source = 'webhook'` stamping;
  *   - `dedupKey` derivation from the configured `webhook.eventIdField` on
  *     the emitted record;
- *   - `externalId` derivation from the mapping table's `external_id` target
- *     (mirrors `PollChangeSource`);
+ *   - `externalId` derivation: the mapping entry whose `target === 'external_id'`
+ *     names — via its `source` — the field on the emitted record that carries
+ *     the canonical external id (mirrors `PollChangeSource`);
  *   - middleware-chain composition via the locked `ChangeMiddleware<T>` shape
  *     (#226-1) — same composition seam as the poll primitive.
  *
@@ -132,10 +133,13 @@ export class WebhookChangeSource<T> implements IChangeSource<T> {
     }
     const config = opts.config;
 
-    // Field mapping: locate the canonical `external_id` target — mirrors the
-    // poll primitive's contract. Adapters emit records already-mapped; the
-    // primitive needs to know which key on T carries the external id so it
-    // can stamp `Change.externalId`.
+    // Field mapping: locate the entry whose canonical `target` is `external_id`
+    // — mirrors the poll primitive's contract. Adapters emit records
+    // already-mapped; the primitive needs to know which key on T carries the
+    // external id so it can stamp `Change.externalId`. That key is the
+    // mapping's `source` (the field on the emitted record), NOT its `target`
+    // (the canonical column) — they differ whenever the canonical record is
+    // vendor-neutral camelCase (e.g. `source: 'externalId'` → `target: 'external_id'`).
     const externalIdMapping = config.mapping.find(
       (m) => m.target === 'external_id',
     );
@@ -144,7 +148,7 @@ export class WebhookChangeSource<T> implements IChangeSource<T> {
         "WebhookChangeSource: DetectionConfig.mapping must include an entry with target 'external_id' so emitted Change<T>.externalId can be populated",
       );
     }
-    this.externalIdSourceField = externalIdMapping.target;
+    this.externalIdSourceField = externalIdMapping.source;
     this.eventIdSourceField = config.webhook.eventIdField;
 
     this.queue = opts.queue;
@@ -183,7 +187,7 @@ export class WebhookChangeSource<T> implements IChangeSource<T> {
       ];
       if (typeof externalIdRaw !== 'string' || externalIdRaw.length === 0) {
         throw new Error(
-          `WebhookChangeSource: record missing string '${this.externalIdSourceField}' — emitted records MUST carry the canonical external id keyed by the mapping target`,
+          `WebhookChangeSource: record missing string '${this.externalIdSourceField}' — emitted records MUST carry the canonical external id keyed by the mapping source`,
         );
       }
       const eventIdRaw = (record as Record<string, unknown>)[

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

@@ -609,19 +609,25 @@ export class JobWorker implements OnModuleInit, OnModuleDestroy {
    * worker resumes via stale-claim sweep).
    */
   private async nextStepSeq(runId: string): Promise<number> {
-    const [row] = await this.db.execute(
+    const result = await this.db.execute(
       sql`SELECT COALESCE(MAX(seq), 0) + 1 AS next FROM job_step WHERE job_run_id = ${runId}`,
-    ) as unknown as Array<{ next: number }>;
-    // pg driver returns { rows: [...] } for raw execute; tolerate both shapes.
+    );
+    // Driver shape varies and is NOT uniformly array-iterable, so we must
+    // never array-destructure the raw result (that throws `{} is not iterable`
+    // on the node-postgres `Result` object, which exposes `.rows` instead of
+    // being an array — first hit by package-mode bridge deliveries on
+    // `drizzle-orm/node-postgres`). Normalise to a row array first, then read.
+    //   - node-postgres `db.execute(sql)` → `{ rows: [{ next }], ... }`
+    //   - some drivers / future shapes → a plain `[{ next }]` array
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const maybeRows = (row as any)?.rows;
-    if (Array.isArray(maybeRows) && maybeRows.length > 0) {
-      return Number(maybeRows[0].next ?? 1);
-    }
-    if (row && typeof (row as { next?: unknown }).next !== 'undefined') {
-      return Number((row as { next: unknown }).next);
-    }
-    return 1;
+    const raw = result as any;
+    const rows: Array<{ next?: unknown }> = Array.isArray(raw)
+      ? raw
+      : Array.isArray(raw?.rows)
+        ? raw.rows
+        : [];
+    const next = rows[0]?.next;
+    return typeof next === 'undefined' ? 1 : Number(next);
   }
 
   // ============================================================================