@pattern-stack/codegen 0.4.0 → 0.4.2

package/runtime/subsystems/bridge/bridge-delivery.drizzle-backend.ts

@@ -0,0 +1,149 @@
+/**
+ * DrizzleBridgeDeliveryRepo — Postgres implementation of `IJobBridge`
+ * (BRIDGE-4, ADR-023 Phase 2).
+ *
+ * Behavioral twin of `MemoryBridgeDeliveryRepo` (BRIDGE-3). The key
+ * difference is `insertDelivery`: where the memory backend throws
+ * `UniqueConstraintError` on a duplicate `(event_id, trigger_id)`, the
+ * Drizzle backend uses `INSERT … ON CONFLICT (event_id, trigger_id) DO
+ * NOTHING` and surfaces the dedup as a silent no-op. This matches the
+ * BRIDGE-4 spec recommendation — a thrown error inside the per-event tx
+ * would abort sibling triggers, which is exactly the failure mode the
+ * facade's Case B pre-write was designed to prevent.
+ *
+ * Tests that need to assert "the constraint fired" use `findDelivery` to
+ * confirm the existing row is the facade-eager pre-write (or the prior
+ * drain attempt's row), not the one this call tried to insert. The
+ * `UniqueConstraintError` branch from BRIDGE-3 is the memory-backend
+ * fidelity path; the Drizzle backend models the same idempotency through
+ * SQL semantics rather than a thrown error.
+ *
+ * The other four methods (`findDelivery`, `findDeliveryById`,
+ * `mark{Delivered,Skipped,Failed}`) are straightforward
+ * `SELECT … LIMIT 1` / `UPDATE … WHERE id = ?` queries.
+ */
+import { Inject, Injectable, Optional } from '@nestjs/common';
+import { eq, and } from 'drizzle-orm';
+
+import { DRIZZLE } from '../../constants/tokens';
+import type { DrizzleClient } from '../../types/drizzle';
+import type { DrizzleTransaction } from '../events/event-bus.protocol';
+
+import { bridgeDelivery } from './bridge-delivery.schema';
+import type { BridgeDeliveryRecord } from './bridge-delivery.schema';
+import type {
+  BridgeDeliveryInsert,
+  IJobBridge,
+} from './bridge.protocol';
+import { assertTenantId } from './assert-tenant-id';
+import { BRIDGE_MULTI_TENANT } from './bridge.tokens';
+
+@Injectable()
+export class DrizzleBridgeDeliveryRepo implements IJobBridge {
+  constructor(
+    @Inject(DRIZZLE) private readonly db: DrizzleClient,
+    /**
+     * Site (c) of the three ADR-023 §Multi-tenancy enforcement sites.
+     * `@Optional()` so unit tests / non-bridge mounts that don't provide
+     * the token still construct the repo cleanly; defaults to `false`,
+     * which makes `assertTenantId` a no-op.
+     */
+    @Optional()
+    @Inject(BRIDGE_MULTI_TENANT)
+    private readonly multiTenant: boolean = false,
+  ) {}
+
+  async insertDelivery(
+    row: BridgeDeliveryInsert,
+    tx?: DrizzleTransaction,
+  ): Promise<void> {
+    // Multi-tenancy gate — last-line defense. Even if callers skipped
+    // sites (a) `EventFlowService.publishAndStart` and (b)
+    // `BridgeDeliveryHandler.run`, a direct repo call still fails fast
+    // BEFORE any SQL is issued.
+    assertTenantId(
+      'DrizzleBridgeDeliveryRepo.insertDelivery',
+      this.multiTenant,
+      row.tenantId,
+    );
+    const client = (tx ?? this.db) as DrizzleClient;
+    // ON CONFLICT DO NOTHING — surfaces dedup as silent no-op so the
+    // per-event tx stays atomic across sibling triggers. RETURNING is
+    // omitted here: the public IJobBridge contract is `Promise<void>`,
+    // and the drain hook (BRIDGE-4) uses its own
+    // `tx.insert(...).onConflictDoNothing().returning({id})` pattern
+    // when it needs the rowcount discriminator. See class-level JSDoc.
+    await client
+      .insert(bridgeDelivery)
+      .values(row)
+      .onConflictDoNothing({
+        target: [bridgeDelivery.eventId, bridgeDelivery.triggerId],
+      });
+  }
+
+  async findDelivery(
+    eventId: string,
+    triggerId: string,
+  ): Promise<BridgeDeliveryRecord | null> {
+    const rows = await this.db
+      .select()
+      .from(bridgeDelivery)
+      .where(
+        and(
+          eq(bridgeDelivery.eventId, eventId),
+          eq(bridgeDelivery.triggerId, triggerId),
+        ),
+      )
+      .limit(1);
+    return (rows[0] as BridgeDeliveryRecord | undefined) ?? null;
+  }
+
+  async findDeliveryById(id: string): Promise<BridgeDeliveryRecord | null> {
+    const rows = await this.db
+      .select()
+      .from(bridgeDelivery)
+      .where(eq(bridgeDelivery.id, id))
+      .limit(1);
+    return (rows[0] as BridgeDeliveryRecord | undefined) ?? null;
+  }
+
+  async markDelivered(
+    id: string,
+    userRunId: string,
+    tx?: DrizzleTransaction,
+  ): Promise<void> {
+    const client = (tx ?? this.db) as DrizzleClient;
+    await client
+      .update(bridgeDelivery)
+      .set({
+        status: 'delivered',
+        userRunId,
+        deliveredAt: new Date(),
+      })
+      .where(eq(bridgeDelivery.id, id));
+  }
+
+  async markSkipped(
+    id: string,
+    reason: string,
+    tx?: DrizzleTransaction,
+  ): Promise<void> {
+    const client = (tx ?? this.db) as DrizzleClient;
+    await client
+      .update(bridgeDelivery)
+      .set({ status: 'skipped', skipReason: reason })
+      .where(eq(bridgeDelivery.id, id));
+  }
+
+  async markFailed(
+    id: string,
+    error: Record<string, unknown>,
+    tx?: DrizzleTransaction,
+  ): Promise<void> {
+    const client = (tx ?? this.db) as DrizzleClient;
+    await client
+      .update(bridgeDelivery)
+      .set({ status: 'failed', error })
+      .where(eq(bridgeDelivery.id, id));
+  }
+}

package/runtime/subsystems/bridge/bridge-delivery.memory-backend.ts

@@ -0,0 +1,140 @@
+/**
+ * MemoryBridgeDeliveryRepo — in-memory `IJobBridge` (BRIDGE-3, ADR-023 Phase 2).
+ *
+ * Behavioral twin of the Drizzle backend (BRIDGE-4) for use in
+ * `just test-unit`. No Docker, no Postgres, fully synchronous. Backs a
+ * `Map<"${eventId}::${triggerId}", BridgeDeliveryRecord>` so the UNIQUE
+ * `(event_id, trigger_id)` constraint can be simulated cheaply.
+ *
+ * Precedent: `MemoryEventBus` (EVT-5), `MemoryJobOrchestrator`
+ * (jobs subsystem). Same shape — a class implementing the protocol plus
+ * test-only helpers (`getDeliveriesForEvent`, `getByStatus`, `clear`) that
+ * BRIDGE-5's framework-handler tests and BRIDGE-7's facade tests will
+ * exercise.
+ *
+ * The synthetic `UniqueConstraintError` carries a `constraint` field equal
+ * to the Drizzle constraint name (`uq_bridge_delivery_event_trigger`, set
+ * in BRIDGE-1's schema) so consumers — including BRIDGE-4's
+ * `INSERT … ON CONFLICT (event_id, trigger_id) DO NOTHING` path and
+ * BRIDGE-7's Case B dedup tests — can branch on the same discriminator
+ * regardless of which backend is wired up. ADR-023 explicitly relies on
+ * this constraint as the dedup mechanism in two places (replay; facade-
+ * vs-drain Case B); a typed error makes both call sites checkable.
+ */
+import { randomUUID } from 'node:crypto';
+
+import type {
+  BridgeDeliveryInsert,
+  IJobBridge,
+} from './bridge.protocol';
+import type { BridgeDeliveryRecord } from './bridge-delivery.schema';
+import { UniqueConstraintError } from './bridge-errors';
+
+const BRIDGE_DELIVERY_UNIQUE_CONSTRAINT =
+  'uq_bridge_delivery_event_trigger' as const;
+
+function key(eventId: string, triggerId: string): string {
+  return `${eventId}::${triggerId}`;
+}
+
+export class MemoryBridgeDeliveryRepo implements IJobBridge {
+  private readonly deliveries = new Map<string, BridgeDeliveryRecord>();
+
+  async insertDelivery(row: BridgeDeliveryInsert): Promise<void> {
+    const k = key(row.eventId, row.triggerId);
+    if (this.deliveries.has(k)) {
+      throw new UniqueConstraintError(
+        BRIDGE_DELIVERY_UNIQUE_CONSTRAINT,
+        row.eventId,
+        row.triggerId,
+      );
+    }
+    // Materialize a full BridgeDeliveryRecord — fill in DB defaults that
+    // the insert payload allowed to be omitted.
+    const record: BridgeDeliveryRecord = {
+      id: row.id ?? randomUUID(),
+      eventId: row.eventId,
+      triggerId: row.triggerId,
+      wrapperRunId: row.wrapperRunId ?? null,
+      userRunId: row.userRunId ?? null,
+      status: row.status ?? 'pending',
+      skipReason: row.skipReason ?? null,
+      error: (row.error as Record<string, unknown> | null | undefined) ?? null,
+      tenantId: row.tenantId ?? null,
+      attemptedAt:
+        row.attemptedAt instanceof Date ? row.attemptedAt : new Date(),
+      deliveredAt:
+        row.deliveredAt instanceof Date ? row.deliveredAt : null,
+    };
+    this.deliveries.set(k, record);
+  }
+
+  async findDelivery(
+    eventId: string,
+    triggerId: string,
+  ): Promise<BridgeDeliveryRecord | null> {
+    return this.deliveries.get(key(eventId, triggerId)) ?? null;
+  }
+
+  async findDeliveryById(id: string): Promise<BridgeDeliveryRecord | null> {
+    for (const record of this.deliveries.values()) {
+      if (record.id === id) return record;
+    }
+    return null;
+  }
+
+  async markDelivered(id: string, userRunId: string): Promise<void> {
+    const record = this.findById(id);
+    record.status = 'delivered';
+    record.userRunId = userRunId;
+    record.deliveredAt = new Date();
+  }
+
+  async markSkipped(id: string, reason: string): Promise<void> {
+    const record = this.findById(id);
+    record.status = 'skipped';
+    record.skipReason = reason;
+  }
+
+  async markFailed(
+    id: string,
+    error: Record<string, unknown>,
+  ): Promise<void> {
+    const record = this.findById(id);
+    record.status = 'failed';
+    record.error = error;
+  }
+
+  // ─── Test helpers ────────────────────────────────────────────────────────
+
+  /** All deliveries for a given event (any status, declaration order). */
+  getDeliveriesForEvent(eventId: string): BridgeDeliveryRecord[] {
+    return [...this.deliveries.values()].filter((r) => r.eventId === eventId);
+  }
+
+  /** All deliveries currently in the given status. */
+  getByStatus(
+    status: BridgeDeliveryRecord['status'],
+  ): BridgeDeliveryRecord[] {
+    return [...this.deliveries.values()].filter((r) => r.status === status);
+  }
+
+  /** Reset the store. Tests use this in `beforeEach`. */
+  clear(): void {
+    this.deliveries.clear();
+  }
+
+  // ─── Internals ───────────────────────────────────────────────────────────
+
+  private findById(id: string): BridgeDeliveryRecord {
+    for (const record of this.deliveries.values()) {
+      if (record.id === id) return record;
+    }
+    throw new Error(
+      `MemoryBridgeDeliveryRepo: no delivery with id '${id}' (transition ` +
+        `methods may not be called for unknown rows; the framework handler ` +
+        `should always findDelivery first or operate on a row it just ` +
+        `inserted).`,
+    );
+  }
+}

package/runtime/subsystems/bridge/bridge-delivery.schema.ts

@@ -0,0 +1,142 @@
+/**
+ * Drizzle schema for the `bridge_delivery` ledger (ADR-023 Phase 2, BRIDGE-1).
+ *
+ * The `bridge_delivery` table is the idempotency ledger for the event-to-job
+ * bridge. Every (event, trigger) pair the bridge is asked to spawn produces
+ * exactly one row; the `UNIQUE (event_id, trigger_id)` constraint guarantees
+ * that:
+ *
+ *   1. Outbox replays of an event do not double-spawn user job runs — the
+ *      drain attempts to insert the duplicate, the constraint trips, and the
+ *      drain skips that trigger.
+ *   2. The `IEventFlow.publishAndStart` facade can pre-write a
+ *      `(status='delivered')` row before the drain runs (Case B from ADR-023
+ *      §`publishAndStart` + existing `triggers:` collision); the drain then
+ *      hits UNIQUE on that trigger and skips it while still spawning any
+ *      other triggers for the same event normally.
+ *
+ * Status values:
+ *   - `pending`   — wrapper run exists; user job not yet started.
+ *   - `delivered` — user job started; `user_run_id` populated.
+ *   - `skipped`   — intentional no-op (`when:` returned false, or
+ *                   facade-eager path pre-empted the bridge spawn).
+ *   - `failed`    — wrapper exhausted retry policy; no auto-retry past that
+ *                   (mirrors events outbox stance — ops eyes only).
+ *
+ * `wrapper_run_id` is **nullable**: the facade-eager path (Case B) pre-writes
+ * `bridge_delivery` with no wrapper. The bridge-drain path always populates
+ * it.
+ *
+ * `tenant_id` is emitted **unconditionally and nullable** (per JOB-8
+ * 2026-04-20 reversal); enforcement is service-layer (BRIDGE-8) gated on the
+ * `BRIDGE_MULTI_TENANT` DI token, not a DB constraint.
+ *
+ * Indexes:
+ *   - `bridge_delivery_event_idx` — lookup all deliveries for an event.
+ *   - `bridge_delivery_status_idx` — partial; ops dashboards filter by
+ *     `pending | failed`.
+ *   - `bridge_delivery_user_run_idx` — partial; reverse lookup from a
+ *     spawned user run back to its delivery row.
+ *
+ * No service logic, no DI wiring — this is the schema foundation. Backends
+ * (memory + drizzle) and the framework handler land in BRIDGE-3 / BRIDGE-4 /
+ * BRIDGE-5.
+ */
+import {
+  index,
+  jsonb,
+  pgEnum,
+  pgTable,
+  text,
+  timestamp,
+  unique,
+  uuid,
+} from 'drizzle-orm/pg-core';
+import { sql } from 'drizzle-orm';
+import type { InferSelectModel } from 'drizzle-orm';
+
+import { domainEvents } from '../events/domain-events.schema';
+import { jobRuns } from '../jobs/job-orchestration.schema';
+
+// ─── Enum ───────────────────────────────────────────────────────────────────
+
+export const bridgeDeliveryStatusEnum = pgEnum('bridge_delivery_status', [
+  'pending',
+  'delivered',
+  'skipped',
+  'failed',
+]);
+
+// ─── Table ──────────────────────────────────────────────────────────────────
+
+export const bridgeDelivery = pgTable(
+  'bridge_delivery',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    /** FK to the source event in the outbox. */
+    eventId: uuid('event_id')
+      .notNull()
+      .references(() => domainEvents.id),
+    /**
+     * Stable codegen-emitted identifier for the (job, trigger) pair, of the
+     * form `<job_type>#<triggerIndex>` (BRIDGE-6). Forms the second half of
+     * the UNIQUE idempotency key.
+     */
+    triggerId: text('trigger_id').notNull(),
+    /**
+     * Wrapper `job_run.id` (the framework `@framework/bridge_delivery` run
+     * that drove this delivery). Nullable: the facade-eager path
+     * (`publishAndStart` Case B) pre-writes a delivered row with no wrapper.
+     */
+    wrapperRunId: uuid('wrapper_run_id').references(() => jobRuns.id),
+    /**
+     * Spawned user `job_run.id`. Null until status is `delivered`; remains
+     * null for `skipped` and `failed` deliveries.
+     */
+    userRunId: uuid('user_run_id').references(() => jobRuns.id),
+    status: bridgeDeliveryStatusEnum('status').notNull().default('pending'),
+    /** Populated when status=`skipped` (e.g. `'when_returned_false'`, `'trigger_unregistered'`). */
+    skipReason: text('skip_reason'),
+    /** Populated when status=`failed`. Mirrors `job_run.error` shape. */
+    error: jsonb('error').$type<Record<string, unknown>>(),
+    /**
+     * Emitted unconditionally and nullable (JOB-8 / SYNC-6 precedent).
+     * Enforcement gated on `BRIDGE_MULTI_TENANT` at the service layer
+     * (BRIDGE-8); no DB constraint.
+     */
+    tenantId: text('tenant_id'),
+    attemptedAt: timestamp('attempted_at', { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+    deliveredAt: timestamp('delivered_at', { withTimezone: true }),
+  },
+  (t) => ({
+    /**
+     * Idempotency ledger. Outbox replays and facade-vs-drain collisions both
+     * dedup through this constraint.
+     */
+    uqBridgeDeliveryEventTrigger: unique('uq_bridge_delivery_event_trigger').on(
+      t.eventId,
+      t.triggerId,
+    ),
+    /** Lookup all deliveries for an event (fanout report, debugging). */
+    idxBridgeDeliveryEvent: index('idx_bridge_delivery_event').on(t.eventId),
+    /**
+     * Ops dashboard filter — only the actionable states. Partial index keeps
+     * it small at scale (the bulk of rows will be `delivered`).
+     */
+    idxBridgeDeliveryStatus: index('idx_bridge_delivery_status')
+      .on(t.status)
+      .where(sql`${t.status} IN ('pending','failed')`),
+    /**
+     * Reverse lookup from a spawned user run back to its delivery row.
+     * Partial — most rows in the bridge ledger but only successful
+     * deliveries have a `user_run_id`.
+     */
+    idxBridgeDeliveryUserRun: index('idx_bridge_delivery_user_run')
+      .on(t.userRunId)
+      .where(sql`${t.userRunId} IS NOT NULL`),
+  }),
+);
+
+export type BridgeDeliveryRecord = InferSelectModel<typeof bridgeDelivery>;

package/runtime/subsystems/bridge/bridge-errors.ts

@@ -0,0 +1,112 @@
+/**
+ * Typed errors for the bridge subsystem (ADR-023 Phase 2, BRIDGE-2).
+ *
+ * All thrown by the three enforcement sites named in ADR-023 §Multi-tenancy:
+ *   - `EventFlowService.publishAndStart` entry (BRIDGE-7)
+ *   - `BridgeDeliveryHandler.handle` entry (BRIDGE-5)
+ *   - `DrizzleBridgeDeliveryRepo.insertDelivery` pre-write (BRIDGE-4)
+ *
+ * Same shape as `runtime/subsystems/jobs/jobs-errors.ts` and
+ * `runtime/subsystems/events/events-errors.ts` so consumers can catch them
+ * with the same exception-filter pattern across all three subsystems.
+ */
+
+/**
+ * Thrown when `BridgeModule` was configured with `multiTenant: true` but
+ * the caller did not pass a `tenantId` at one of the three enforcement
+ * sites listed above.
+ *
+ * **Strict enforcement rationale (mirrors JOB-8 / SYNC-6 stance, locked
+ * 2026-04-18 for jobs; same rationale applies here).** Cross-tenant data
+ * leakage is the worst class of bug a multi-tenant system can ship;
+ * surfacing the misuse loudly at the call site (rather than silently
+ * defaulting to `null` or to "the last tenant seen") prevents both
+ * accidental global writes and sneaky reads that return a union of tenants.
+ *
+ * - `undefined` `tenantId` → throw this error.
+ * - Explicit `null` `tenantId` → passes; opts the call into cross-tenant
+ *   work (e.g. a system housekeeping event with no owning tenant). The
+ *   `bridge_delivery` row is persisted with `tenant_id = NULL`.
+ *
+ * The `callSite` constructor argument names which of the three enforcement
+ * sites threw — review reports and ops dashboards rely on a stable site
+ * name, so use the canonical strings: `'EventFlowService.publishAndStart'`,
+ * `'BridgeDeliveryHandler.handle'`,
+ * `'DrizzleBridgeDeliveryRepo.insertDelivery'`.
+ */
+export class MissingTenantIdError extends Error {
+  override readonly name = 'MissingTenantIdError';
+  constructor(public readonly callSite: string) {
+    super(
+      `MissingTenantIdError: BridgeModule was configured with ` +
+        `multiTenant=true but ${callSite} was called without tenantId ` +
+        `(undefined). Pass an explicit tenantId, or pass null for ` +
+        `cross-tenant work.`,
+    );
+  }
+}
+
+/**
+ * Synthetic error thrown by `MemoryBridgeDeliveryRepo.insertDelivery` when
+ * a duplicate `(event_id, trigger_id)` insert hits the simulated UNIQUE
+ * constraint (BRIDGE-3).
+ *
+ * Carries a `constraint` field equal to the Drizzle constraint name
+ * declared in BRIDGE-1's schema (`uq_bridge_delivery_event_trigger`) so
+ * call sites can branch on the same discriminator regardless of which
+ * backend is wired up. This matters because ADR-023 explicitly leans on
+ * the constraint as the dedup mechanism in two places — outbox replay
+ * and `publishAndStart` Case B — and BRIDGE-4 / BRIDGE-7 will share a
+ * type-check path with BRIDGE-3-driven tests.
+ *
+ * The Drizzle backend (BRIDGE-4) does NOT throw this error: it uses
+ * `INSERT … ON CONFLICT (event_id, trigger_id) DO NOTHING RETURNING id`
+ * per the BRIDGE-4 spec recommendation, so collisions surface as an empty
+ * result set rather than an exception. The error exists so the memory
+ * backend can faithfully model the "duplicate raises" behaviour for tests
+ * that want to assert the constraint actually fires.
+ */
+/**
+ * Thrown by `BridgeModule.onModuleInit` when `JobWorkerModule` is wired
+ * alongside the bridge but its active `pools` list does not include one
+ * or more of the three reserved bridge pools (`events_inbound`,
+ * `events_change`, `events_outbound`).
+ *
+ * Without a worker polling those pools, the wrapper `job_run` rows the
+ * outbox drain inserts (BRIDGE-4) sit `pending` forever — a silent
+ * footgun where `eventFlow.publish(...)` returns success but no user
+ * job ever spawns. The boot-time check converts that into a fail-fast.
+ *
+ * Operators can either (a) add `...BRIDGE_RESERVED_POOLS` to their
+ * `JobWorkerModule.forRoot({ pools })` configuration so the same
+ * process polls the reserved pools, or (b) run a separate worker
+ * process per reserved pool for lane isolation (ADR-022 §Pool
+ * isolation).
+ */
+export class BridgeReservedPoolsNotPolledError extends Error {
+  override readonly name = 'BridgeReservedPoolsNotPolledError';
+  constructor(public readonly missingPools: readonly string[]) {
+    super(
+      `BridgeModule loaded but JobWorkerModule is not polling reserved ` +
+        `pool '${missingPools[0]}'. Add ...BRIDGE_RESERVED_POOLS to your ` +
+        `JobWorkerModule.forRoot({ pools }) configuration. Missing pools: ` +
+        `${missingPools.join(', ')}. (Bridge-fanout wrappers will sit ` +
+        `pending forever without these pollers.)`,
+    );
+  }
+}
+
+export class UniqueConstraintError extends Error {
+  override readonly name = 'UniqueConstraintError';
+  constructor(
+    public readonly constraint: string,
+    public readonly eventId: string,
+    public readonly triggerId: string,
+  ) {
+    super(
+      `UniqueConstraintError: duplicate insert into bridge_delivery for ` +
+        `(event_id='${eventId}', trigger_id='${triggerId}') — violates ` +
+        `constraint '${constraint}'.`,
+    );
+  }
+}