@pattern-stack/codegen 0.4.0 → 0.4.2

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

@@ -0,0 +1,175 @@
+/**
+ * BridgeOutboxDrainHook — drains-time bridge fanout writer (BRIDGE-4,
+ * ADR-023 Phase 2).
+ *
+ * Implements `IBridgeOutboxDrainHook`. Called by `DrizzleEventBus`'s
+ * modified `processBatch` once per drained event, INSIDE the per-event
+ * transaction. For every trigger registered against the event's type in
+ * the codegen-emitted `bridgeRegistry`, writes:
+ *
+ *   1. `bridge_delivery` ledger row — `INSERT … ON CONFLICT (event_id,
+ *      trigger_id) DO NOTHING RETURNING id`. Empty result ⇒ Case B
+ *      facade-eager pre-write OR drain-replay collision; skip wrapper
+ *      insert for that trigger; sibling triggers still fire.
+ *   2. `job_run` wrapper row — `type='@framework/bridge_delivery'`,
+ *      `pool='events_<direction>'`, `input={ deliveryId }`,
+ *      `trigger_source='event'`, `trigger_ref=event.id`. The wrapper is
+ *      what the framework `BridgeDeliveryHandler` (BRIDGE-5) eventually
+ *      claims via the worker that polls the corresponding reserved pool.
+ *
+ * Null `event.metadata.direction` is tolerated: the hook logs a one-line
+ * warning per event and returns zeros without writing rows. The drain's
+ * `processed_at` stamp + subscriber dispatch still fire normally.
+ * Direction is null only for events published via the legacy
+ * `IEventBus.publish(...)` path (`TypedEventBus.publish` always sets it);
+ * such events are out of scope for bridge fanout.
+ *
+ * The wrapper insert generates its own `id` via Drizzle's `defaultRandom`
+ * — we don't `RETURNING id` because nobody needs it at drain time;
+ * `BridgeDeliveryHandler` later looks up the wrapper via the
+ * `bridge_delivery.wrapper_run_id` link if needed. This keeps the drain
+ * one-round-trip-per-trigger.
+ */
+import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
+import { randomUUID } from 'node:crypto';
+
+import type { DomainEvent, DrizzleTransaction } from '../events/event-bus.protocol';
+import { bridgeDelivery } from './bridge-delivery.schema';
+import { jobRuns } from '../jobs/job-orchestration.schema';
+
+import { BRIDGE_REGISTRY } from './bridge.tokens';
+import type {
+  BridgeOutboxDrainResult,
+  BridgeRegistry,
+  BridgeTriggerEntry,
+  IBridgeOutboxDrainHook,
+} from './bridge.protocol';
+import { BRIDGE_DELIVERY_JOB_TYPE } from './bridge-delivery-handler';
+import type { EventTypeName } from '../events/generated/types';
+
+/** Reserved pools the wrapper rows route into; ADR-022 / ADR-024. */
+const POOL_BY_DIRECTION: Record<string, string> = {
+  inbound: 'events_inbound',
+  change: 'events_change',
+  outbound: 'events_outbound',
+};
+
+@Injectable()
+export class BridgeOutboxDrainHook implements IBridgeOutboxDrainHook {
+  private readonly logger = new Logger(BridgeOutboxDrainHook.name);
+  private warnedNullDirection = false;
+
+  constructor(
+    @Optional()
+    @Inject(BRIDGE_REGISTRY)
+    private readonly registry: BridgeRegistry = {},
+  ) {}
+
+  async processEvent(
+    event: DomainEvent,
+    tx: DrizzleTransaction,
+  ): Promise<BridgeOutboxDrainResult> {
+    const triggers = this.lookupTriggers(event.type);
+    if (triggers.length === 0) {
+      return { delivered: 0, dedupSkips: 0, triggerCount: 0 };
+    }
+
+    const direction =
+      (event.metadata?.['direction'] as string | undefined) ?? null;
+    const tenantId =
+      (event.metadata?.['tenantId'] as string | null | undefined) ?? null;
+    const wrapperPool = direction ? POOL_BY_DIRECTION[direction] : undefined;
+
+    if (!wrapperPool) {
+      // Null direction (or an unrecognised one — defensive). Bridge
+      // fanout requires a routed wrapper pool; without one we can't
+      // spawn. Log once per process so misconfiguration surfaces.
+      if (!this.warnedNullDirection) {
+        this.warnedNullDirection = true;
+        this.logger.warn(
+          `Skipping bridge fanout for events with null/unknown direction. ` +
+            `event.id=${event.id} event.type=${event.type} ` +
+            `direction=${String(direction)}. The wrapper pool is derived ` +
+            `from direction (events_<direction>); publishers must use ` +
+            `TypedEventBus.publish() so direction is stamped on the ` +
+            `outbox row.`,
+        );
+      }
+      return { delivered: 0, dedupSkips: 0, triggerCount: triggers.length };
+    }
+
+    let delivered = 0;
+    let dedupSkips = 0;
+    const client = tx as unknown as {
+      insert: (table: unknown) => {
+        values: (v: unknown) => {
+          onConflictDoNothing: (opts: unknown) => {
+            returning: (cols: unknown) => Promise<{ id: string }[]>;
+          };
+        } & {
+          // wrapper insert path — no ON CONFLICT
+          // (typed loosely via the same helper return shape)
+        };
+      };
+    };
+
+    for (const trigger of triggers) {
+      const deliveryId = randomUUID();
+      const wrapperRunId = randomUUID();
+
+      // 1. bridge_delivery insert with ON CONFLICT DO NOTHING + RETURNING.
+      const inserted = await (tx as unknown as {
+        insert: typeof client.insert;
+      })
+        .insert(bridgeDelivery)
+        .values({
+          id: deliveryId,
+          eventId: event.id,
+          triggerId: trigger.triggerId,
+          wrapperRunId,
+          status: 'pending',
+          tenantId,
+        })
+        .onConflictDoNothing({
+          target: [bridgeDelivery.eventId, bridgeDelivery.triggerId],
+        })
+        .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.
+        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++;
+    }
+
+    return { delivered, dedupSkips, triggerCount: triggers.length };
+  }
+
+  private lookupTriggers(
+    eventType: string,
+  ): BridgeTriggerEntry[] {
+    const candidates = this.registry[eventType as EventTypeName];
+    return (candidates ?? []) as BridgeTriggerEntry[];
+  }
+}

package/runtime/subsystems/bridge/bridge.module.ts

@@ -0,0 +1,160 @@
+/**
+ * BridgeModule — `DynamicModule.forRoot({ backend, multiTenant })`
+ * factory that wires the entire bridge subsystem (BRIDGE-8, ADR-023
+ * Phase 2).
+ *
+ * The bridge is the formalized seam between events (ADR-024) and jobs
+ * (ADR-022). It is owned by neither subsystem and consumes their tokens
+ * via DI. `BridgeModule` is the *combiner* — neither `EventsModule` nor
+ * `JobsDomainModule` know about it.
+ *
+ * Consumer wiring (must be imported AFTER `EventsModule`,
+ * `JobsDomainModule`, and `JobWorkerModule`):
+ * ```ts
+ * @Module({
+ *   imports: [
+ *     EventsModule.forRoot({ backend: 'drizzle' }),
+ *     JobWorkerModule.forRoot({
+ *       mode: 'embedded',
+ *       backend: 'drizzle',
+ *       pools: ['interactive', 'batch', ...BRIDGE_RESERVED_POOLS],
+ *     }),
+ *     BridgeModule.forRoot({ backend: 'drizzle', multiTenant: false }),
+ *   ],
+ * })
+ * class AppModule {}
+ * ```
+ *
+ * Boot-time check: `onModuleInit` inspects `JobWorkerModule`'s active
+ * pools and throws `BridgeReservedPoolsNotPolledError` when any of the
+ * three reserved bridge pools isn't being polled. Converts the
+ * "wrappers sit pending forever" footgun into a fail-fast.
+ *
+ * Handler registration: ONE `@JobHandler('@framework/bridge_delivery',
+ * ...)` decorator on `BridgeDeliveryHandler` auto-registers it in
+ * `JOB_HANDLER_REGISTRY` at module-load time. We declare the class as a
+ * Nest provider here so DI resolves its constructor deps; per-direction
+ * routing happens via `job_run.pool='events_<direction>'` set by
+ * `BridgeOutboxDrainHook` (BRIDGE-4) — workers polling each reserved
+ * pool independently claim wrappers from their own pool and dispatch to
+ * the same handler class. The reserved-pool validator exemption
+ * (BRIDGE-5) lets the framework handler legitimately target a reserved
+ * pool.
+ */
+import {
+  Inject,
+  Module,
+  Optional,
+  type DynamicModule,
+  type OnModuleInit,
+  type Provider,
+} from '@nestjs/common';
+
+import {
+  JOB_WORKER_MODULE_OPTIONS,
+  type JobWorkerModuleOptions,
+} from '../jobs/job-worker.module';
+
+import {
+  BRIDGE_DELIVERY_REPO,
+  BRIDGE_MODULE_OPTIONS,
+  BRIDGE_MULTI_TENANT,
+  BRIDGE_OUTBOX_DRAIN_HOOK,
+  BRIDGE_REGISTRY,
+  EVENT_FLOW,
+} from './bridge.tokens';
+import { BridgeReservedPoolsNotPolledError } from './bridge-errors';
+import { MemoryBridgeDeliveryRepo } from './bridge-delivery.memory-backend';
+import { DrizzleBridgeDeliveryRepo } from './bridge-delivery.drizzle-backend';
+import { BridgeOutboxDrainHook } from './bridge-outbox-drain-hook';
+import { EventFlowService } from './event-flow.service';
+import { BridgeDeliveryHandler } from './bridge-delivery-handler';
+import { bridgeRegistry } from './generated/registry';
+import { BRIDGE_RESERVED_POOLS } from './reserved-pools';
+
+export interface BridgeModuleOptions {
+  /**
+   * `'memory'` for unit tests (no Postgres), `'drizzle'` for production.
+   * Switches `BRIDGE_DELIVERY_REPO` between
+   * `MemoryBridgeDeliveryRepo` and `DrizzleBridgeDeliveryRepo`.
+   */
+  backend: 'memory' | 'drizzle';
+  /**
+   * Multi-tenancy opt-in. When `true`, the three enforcement sites
+   * (`EventFlowService.publishAndStart`, `BridgeDeliveryHandler.run`,
+   * `DrizzleBridgeDeliveryRepo.insertDelivery`) throw
+   * `MissingTenantIdError` when `tenantId === undefined`. Explicit
+   * `null` always passes (cross-tenant work). Defaults to `false`.
+   */
+  multiTenant?: boolean;
+}
+
+@Module({})
+export class BridgeModule implements OnModuleInit {
+  static forRoot(opts: BridgeModuleOptions): DynamicModule {
+    const repoProvider: Provider =
+      opts.backend === 'memory'
+        ? { provide: BRIDGE_DELIVERY_REPO, useClass: MemoryBridgeDeliveryRepo }
+        : { provide: BRIDGE_DELIVERY_REPO, useClass: DrizzleBridgeDeliveryRepo };
+
+    return {
+      module: BridgeModule,
+      global: true,
+      // BridgeModule consumes EVENT_BUS / JOB_ORCHESTRATOR / DRIZZLE
+      // from sibling subsystems via DI; no `imports` needed here. The
+      // consumer is responsible for wiring EventsModule + JobsDomainModule
+      // (or JobWorkerModule, which transitively imports the latter)
+      // BEFORE BridgeModule.
+      providers: [
+        { provide: BRIDGE_MODULE_OPTIONS, useValue: opts },
+        { provide: BRIDGE_MULTI_TENANT, useValue: opts.multiTenant ?? false },
+        { provide: BRIDGE_REGISTRY, useValue: bridgeRegistry },
+        repoProvider,
+        // Drain hook — always wired; `DrizzleEventBus` consumes it via
+        // `@Optional()`, so non-bridge mounts simply see `undefined`.
+        { provide: BRIDGE_OUTBOX_DRAIN_HOOK, useClass: BridgeOutboxDrainHook },
+        // Facade — class provider + token alias.
+        EventFlowService,
+        { provide: EVENT_FLOW, useExisting: EventFlowService },
+        // Framework handler — provider so DI can construct it. The
+        // `@JobHandler` decorator already auto-registers it in
+        // `JOB_HANDLER_REGISTRY` at module-load time, and its `jobs`
+        // row is upserted at `JobWorkerModule.onModuleInit`. We just
+        // need the class instantiated as a Nest provider so its DI
+        // deps (BRIDGE_DELIVERY_REPO, JOB_ORCHESTRATOR, EVENT_BUS,
+        // BRIDGE_REGISTRY, BRIDGE_MULTI_TENANT) resolve.
+        BridgeDeliveryHandler,
+      ],
+      exports: [
+        EVENT_FLOW,
+        BRIDGE_DELIVERY_REPO,
+        BRIDGE_REGISTRY,
+        BRIDGE_MULTI_TENANT,
+        BRIDGE_MODULE_OPTIONS,
+        BRIDGE_OUTBOX_DRAIN_HOOK,
+      ],
+    };
+  }
+
+  /**
+   * `JOB_WORKER_MODULE_OPTIONS` is declared `@Optional()` so unit tests
+   * that mount `BridgeModule` alone (no `JobWorkerModule`) boot
+   * cleanly — the boot-time check skips when the token is undefined.
+   */
+  constructor(
+    @Optional()
+    @Inject(JOB_WORKER_MODULE_OPTIONS)
+    private readonly workerOpts?: JobWorkerModuleOptions,
+  ) {}
+
+  async onModuleInit(): Promise<void> {
+    if (!this.workerOpts) return;
+    const activePools = this.workerOpts.pools ?? [];
+    const missing = BRIDGE_RESERVED_POOLS.filter(
+      (p) => !activePools.includes(p),
+    );
+    if (missing.length > 0) {
+      throw new BridgeReservedPoolsNotPolledError(missing);
+    }
+  }
+}

package/runtime/subsystems/bridge/bridge.protocol.ts

@@ -0,0 +1,351 @@
+/**
+ * Bridge subsystem — protocols (ports) — ADR-023 Phase 2, BRIDGE-2.
+ *
+ * Two interfaces:
+ *
+ *   - `IJobBridge`  — repo-shaped contract over the `bridge_delivery`
+ *                     ledger. Backends: memory (BRIDGE-3), Drizzle
+ *                     (BRIDGE-4). Consumed by the framework
+ *                     `BridgeDeliveryHandler` (BRIDGE-5), the modified
+ *                     outbox drain (BRIDGE-4), and the `EventFlowService`
+ *                     facade for Case B pre-writes (BRIDGE-7).
+ *
+ *   - `IEventFlow`  — the developer-facing facade from ADR-023 §Decision 7.
+ *                     Two verbs: `publish` and `publishAndStart`. All
+ *                     request-path and fanout publishing should go through
+ *                     this token rather than `IEventBus` / `TYPED_EVENT_BUS`
+ *                     directly so reviewers can grep call sites and the
+ *                     `codegen events consumers <type>` CLI (BRIDGE-9) can
+ *                     index Tier 2 alongside Tier 3 triggers and Tier 1
+ *                     subscribers.
+ *
+ * Both interfaces accept an optional last-arg `DrizzleTransaction` so
+ * callers operating inside an existing transaction can thread it through
+ * (the outbox drain's per-event tx, the facade's Case B pre-write).
+ */
+import type { InferInsertModel } from 'drizzle-orm';
+
+import type { DrizzleTransaction, DomainEvent } from '../events/event-bus.protocol';
+import type {
+  EventOfType,
+  EventTypeName,
+} from '../events/generated/types';
+
+import type {
+  BridgeDeliveryRecord,
+  bridgeDelivery,
+} from './bridge-delivery.schema';
+
+// ============================================================================
+// IJobBridge — bridge_delivery ledger repo
+// ============================================================================
+
+/**
+ * Insert payload for `IJobBridge.insertDelivery`. Derived from the
+ * Drizzle schema so the contract stays in sync with the table — adding a
+ * column to `bridge_delivery` propagates to every backend without manual
+ * sync. `id`, `attemptedAt` carry DB defaults; `wrapperRunId`, `userRunId`,
+ * `skipReason`, `error`, `tenantId`, `deliveredAt` are nullable per BRIDGE-1.
+ */
+export type BridgeDeliveryInsert = InferInsertModel<typeof bridgeDelivery>;
+
+export interface IJobBridge {
+  /**
+   * Insert a `bridge_delivery` row.
+   *
+   * **Throws on `UNIQUE (event_id, trigger_id)` conflict.** Callers that
+   * expect collisions (the outbox drain hitting a facade-eager pre-write,
+   * the drain re-claiming after a crash) should catch the conflict and
+   * skip — see ADR-023 §`publishAndStart` + existing `triggers:` collision
+   * and the BRIDGE-4 spec for the recommended `INSERT … ON CONFLICT … DO
+   * NOTHING RETURNING id` shape that turns the throw into an empty result.
+   */
+  insertDelivery(
+    row: BridgeDeliveryInsert,
+    tx?: DrizzleTransaction,
+  ): Promise<void>;
+
+  /**
+   * Lookup a delivery by its idempotency key. Returns `null` when no row
+   * matches. Used in tests / dashboards for the canonical (event, trigger)
+   * lookup — distinct from `findDeliveryById`, which is what the
+   * `BridgeDeliveryHandler` (BRIDGE-5) uses given that the wrapper input
+   * only carries the delivery id.
+   */
+  findDelivery(
+    eventId: string,
+    triggerId: string,
+  ): Promise<BridgeDeliveryRecord | null>;
+
+  /**
+   * Lookup a delivery by primary key. Drizzle backend (BRIDGE-4):
+   * `SELECT … WHERE id = ? LIMIT 1`. Memory backend (BRIDGE-3): linear
+   * scan (small N). Returns `null` when no row matches — handler treats
+   * that as `delivery_row_missing` and the wrapper completes cleanly.
+   */
+  findDeliveryById(id: string): Promise<BridgeDeliveryRecord | null>;
+
+  /**
+   * Transition `pending` → `delivered`, populating `user_run_id` and
+   * `delivered_at`. Called by `BridgeDeliveryHandler` after
+   * `orchestrator.start(userJob)` returns.
+   */
+  markDelivered(
+    id: string,
+    userRunId: string,
+    tx?: DrizzleTransaction,
+  ): Promise<void>;
+
+  /**
+   * Transition `pending` → `skipped`, populating `skip_reason`. Called by
+   * `BridgeDeliveryHandler` when the trigger's `when:` predicate returns
+   * `false` or when the trigger no longer exists in the registry (rename
+   * scenario from ADR-023 §Consequences).
+   */
+  markSkipped(
+    id: string,
+    reason: string,
+    tx?: DrizzleTransaction,
+  ): Promise<void>;
+
+  /**
+   * Transition `pending` → `failed`, populating `error`. Called by the
+   * wrapper after its retry policy is exhausted; surfaces in ops
+   * dashboards via the `idx_bridge_delivery_status` partial index.
+   */
+  markFailed(
+    id: string,
+    error: Record<string, unknown>,
+    tx?: DrizzleTransaction,
+  ): Promise<void>;
+}
+
+// ============================================================================
+// IEventFlow — developer-facing facade (ADR-023 §Decision 7)
+// ============================================================================
+
+/**
+ * Caller-supplied options for `IEventFlow.publishAndStart`.
+ *
+ * `tenantId` semantics match `IJobOrchestrator.StartOptions.tenantId`
+ * (JOB-8): explicit `null` opts into cross-tenant work; `undefined` throws
+ * `MissingTenantIdError` when `BridgeModule` is configured with
+ * `multiTenant: true`.
+ *
+ * `parentRunId` lets request-path callers attach the eagerly-started run
+ * to an existing run hierarchy (e.g. a higher-level orchestration that
+ * publishes events as side effects of its own steps).
+ */
+export interface PublishAndStartOptions {
+  parentRunId?: string;
+  tenantId?: string | null;
+}
+
+/**
+ * Result of `IEventFlow.publishAndStart`. The facade returns the
+ * eagerly-started user run's id so the caller can subscribe to its
+ * completion or correlate with its own request id.
+ */
+export interface PublishAndStartResult {
+  runId: string;
+}
+
+export interface IEventFlow {
+  /**
+   * Tier 1 + Tier 3 — plain publish.
+   *
+   * Writes the event to the outbox (or in-memory bus, depending on the
+   * backend). Bridge triggers fire asynchronously (via
+   * `@JobHandler.triggers`); in-process `IEventBus.subscribe` handlers
+   * fire in-call. Returns when the outbox row is committed.
+   *
+   * Delegates to `IEventBus.publish` under the hood.
+   *
+   * **Note on signature:** ADR-023 §Decision 7 sketches the verb as
+   * `publish<T extends EventType>(event: TypedEvent<T>)`. The actual
+   * generated types are `EventTypeName` and `EventOfType<T>` (see
+   * `runtime/subsystems/events/generated/types.ts`); we use those here so
+   * the contract typechecks against the real codegen output. The verb
+   * shape and behaviour are unchanged.
+   */
+  publish<T extends EventTypeName>(
+    event: EventOfType<T>,
+    tx?: DrizzleTransaction,
+  ): Promise<void>;
+
+  /**
+   * Tier 2 + Tier 3 + Tier 1 — publish + eagerly start a specific named
+   * job.
+   *
+   * Behaviour:
+   *   1. Writes the event to the outbox (so bridge triggers and Tier 1
+   *      subscribers fire as normal).
+   *   2. Synchronously calls `IJobOrchestrator.start(jobType, input,
+   *      opts)` to enqueue the user job before returning to the caller.
+   *   3. **Case B dedup** — if the (event, jobType) pair has a declared
+   *      `@JobHandler.triggers` entry, the facade pre-writes a
+   *      `bridge_delivery(status='delivered', user_run_id=<eagerRunId>)`
+   *      row in the same transaction as `orchestrator.start(...)`. The
+   *      drain's later `INSERT … ON CONFLICT (event_id, trigger_id) DO
+   *      NOTHING` then sees the existing row and skips that trigger while
+   *      still spawning any other triggers for the same event.
+   *
+   * Use when the caller needs the job enqueued before returning to the
+   * user (request-path, within-transaction durability). For pure async
+   * fanout where Tier 3 alone suffices, use `publish` instead.
+   *
+   * **Same-tx invariant** (BRIDGE-7): the outbox insert, the
+   * `orchestrator.start` insert, and the Case B `bridge_delivery`
+   * pre-write must all share a transaction. A crash between any two
+   * leaves the system inconsistent (e.g. event published but no eager
+   * run, or eager run with no Case B dedup row → drain double-spawns).
+   *
+   * **Note on signature:** ADR-023 §Decision 7 sketches `JobType` /
+   * `JobInputOf<J>` parameters; the jobs subsystem currently models the
+   * orchestrator's `start` as `start(type: string, input: unknown, …)`
+   * with no generated `JobType` union analogous to events' `EventTypeName`.
+   * The facade matches that shape today; tightening the surface is a
+   * post-Phase-2 follow-up that requires generated job typing first.
+   */
+  publishAndStart<T extends EventTypeName>(
+    event: EventOfType<T>,
+    jobType: string,
+    input: unknown,
+    opts?: PublishAndStartOptions,
+  ): Promise<PublishAndStartResult>;
+}
+
+// ============================================================================
+// bridgeRegistry — emitted by codegen (BRIDGE-6), consumed by drain (BRIDGE-4),
+// the framework handler (BRIDGE-5), and the EventFlow facade (BRIDGE-7).
+// ============================================================================
+
+/**
+ * One entry in the `bridgeRegistry`. Generated from a user job's
+ * `@JobHandler({ triggers: [...] })` decorator metadata in BRIDGE-6.
+ *
+ * The `T extends EventTypeName` parameter is what gives `map`/`when`
+ * callbacks compile-time access to the typed payload via `EventOfType<T>`.
+ * Codegen emits one entry per (job, trigger-index) pair, so `triggerId` is
+ * stable across re-runs.
+ *
+ * `triggerId` shape: `<jobType>#<triggerIndex>`. Forms the second half of
+ * the `bridge_delivery (event_id, trigger_id)` UNIQUE idempotency key.
+ *
+ * `map` is required and returns the input payload to pass to
+ * `IJobOrchestrator.start(jobType, input, ...)` — typed as `unknown` here
+ * because the registry is event-keyed, not job-keyed (one event can fan
+ * out to N jobs with N input shapes).
+ *
+ * `when` is optional. When provided and the predicate returns `false` at
+ * handler time, `BridgeDeliveryHandler` records the delivery as
+ * `skipped` with `skip_reason='predicate_false'` rather than spawning the
+ * user job (ADR-023 §Decision 6).
+ */
+export interface BridgeTriggerEntry<
+  T extends EventTypeName = EventTypeName,
+> {
+  triggerId: string;
+  jobType: string;
+  map: (event: EventOfType<T>) => unknown;
+  when?: (event: EventOfType<T>) => boolean;
+}
+
+/**
+ * Codegen-emitted registry — `Record<EventTypeName, BridgeTriggerEntry[]>`.
+ * Per-event-type ordered array of triggers (declaration order across
+ * handler files, deterministic across codegens so `triggerId` indices stay
+ * stable).
+ *
+ * The mapped-type form (`{ [T in EventTypeName]?: BridgeTriggerEntry<T>[] }`)
+ * gives each entry's `map`/`when` callbacks the right `EventOfType<T>`
+ * narrowing under indexed access.
+ */
+export type BridgeRegistry = {
+  [T in EventTypeName]?: BridgeTriggerEntry<T>[];
+};
+
+
+// ============================================================================
+// IBridgeOutboxDrainHook — port the events outbox drain calls per event
+// ============================================================================
+
+/**
+ * Result of one drain-hook invocation, returned for observability + tests.
+ *
+ * `delivered`: number of `bridge_delivery + wrapper job_run` row pairs the
+ * hook actually inserted for this event (post-`ON CONFLICT DO NOTHING`).
+ *
+ * `dedupSkips`: number of triggers whose `bridge_delivery` insert tripped
+ * `UNIQUE (event_id, trigger_id)` and was skipped (Case B from ADR-023's
+ * facade-eager pre-write, or replay of a previous drain attempt). These
+ * are not failures — they're the dedup mechanism doing its job.
+ *
+ * `triggerCount`: total triggers matched in the registry for this event;
+ * `triggerCount === delivered + dedupSkips`.
+ */
+export interface BridgeOutboxDrainResult {
+  delivered: number;
+  dedupSkips: number;
+  triggerCount: number;
+}
+
+/**
+ * Port the events outbox drain (EVT-4 / `DrizzleEventBus.processBatch`)
+ * calls once per drained event, INSIDE the per-event transaction
+ * (BRIDGE-4). Implemented by `BridgeOutboxDrainHook` in the bridge
+ * subsystem; injected as `@Optional()` into `DrizzleEventBus` so projects
+ * that haven't installed the bridge subsystem keep the EVT-4 baseline.
+ *
+ * Why a port and not direct schema imports inside the events subsystem:
+ *   - Keeps the events subsystem free of any knowledge of bridge_delivery
+ *     and wrapper job_run shape; the layering inversion that ADR-023
+ *     names ("the drain must know about bridge") is captured in this one
+ *     port, not strewn across every bridge column the drain touches.
+ *   - Tests can mock the port and assert call-shape without spinning up
+ *     the full bridge module.
+ *   - `BridgeModule.forRoot()` (BRIDGE-8) wires the implementation; in
+ *     non-bridge consumers the token is undefined and the drain skips
+ *     the bridge block entirely. ADR-023 §Outbox drain atomicity is
+ *     preserved either way (the per-event tx still wraps `processed_at`).
+ */
+export interface IBridgeOutboxDrainHook {
+  /**
+   * Process one drained event's bridge fanout. Called inside the drain's
+   * per-event transaction; the hook writes `bridge_delivery + wrapper
+   * job_run` row pairs for every matched trigger via the supplied `tx`.
+   *
+   * Behaviour:
+   *   1. Looks up `bridgeRegistry[event.type]`. No matches → returns
+   *      `{ delivered: 0, dedupSkips: 0, triggerCount: 0 }`; the drain
+   *      proceeds to dispatch user subscribers + stamp `processed_at`.
+   *   2. For each matched trigger:
+   *      - `INSERT INTO bridge_delivery (event_id, trigger_id, status,
+   *        wrapper_run_id, tenant_id, ...) VALUES (...) ON CONFLICT
+   *        (event_id, trigger_id) DO NOTHING RETURNING id`. Empty
+   *        result ⇒ Case B / replay collision; skip wrapper insert for
+   *        this trigger; sibling triggers still fire normally.
+   *      - On insert success: `INSERT INTO job_run (type=
+   *        '@framework/bridge_delivery', pool='events_<direction>',
+   *        input={ deliveryId }, trigger_source='event', trigger_ref=
+   *        event.id, tenant_id)`. The wrapper row is what the framework
+   *        `BridgeDeliveryHandler` (BRIDGE-5) will eventually claim.
+   *   3. Returns the counts for observability.
+   *
+   * Throwing aborts the per-event tx — bridge inserts roll back, the
+   * `processed_at` stamp is not made, and the event re-claims on the next
+   * drain cycle. Callers should let infra exceptions propagate; recoverable
+   * conditions (null direction, missing registry entry) are handled
+   * inline and do not throw.
+   *
+   * Null `event.metadata.direction` MUST be tolerated: the wrapper pool
+   * is derived from direction; absent direction means the publisher
+   * predates ADR-024 (manual `eventBus.publish(...)` rather than
+   * `TypedEventBus.publish(...)`). Hook should log + return zeros so the
+   * drain still stamps `processed_at` and dispatches subscribers.
+   */
+  processEvent(
+    event: DomainEvent,
+    tx: DrizzleTransaction,
+  ): Promise<BridgeOutboxDrainResult>;
+}