@pattern-stack/codegen 0.4.0 → 0.4.2

package/runtime/subsystems/auth/protocols/integration-store.ts

@@ -0,0 +1,66 @@
+/**
+ * Auth subsystem — integration storage ports.
+ *
+ * `OAuth2RefreshStrategy` reads decrypted integration rows and persists
+ * refreshed tokens. The subsystem doesn't care what entity framework stores
+ * those rows — consumers implement these narrow ports against whatever
+ * `integrations` table their app uses.
+ *
+ * In dealbrain-v2 (the extraction source) both ports are satisfied by a
+ * pair of thin adapters over `IntegrationService` + `RefreshIntegrationUseCase`.
+ * The codegen-patterns `examples/auth-integrations/` starter (separate PR)
+ * ships a canonical `integration.yaml` whose generated service + use case
+ * satisfy the shape out of the box.
+ */
+
+/**
+ * An integration row with its secrets decrypted and ready to use.
+ *
+ * Consumers produce this shape from their own storage by passing stored
+ * ciphertexts through `IEncryptionKey.decrypt`. The subsystem never sees
+ * the ciphertext form.
+ */
+export interface DecryptedIntegration {
+  id: string;
+  /** Provider slug — must match the strategy's `provider`. */
+  provider: string;
+  /** Plaintext access token, or empty string if never granted. */
+  accessToken: string;
+  /** Plaintext refresh token, or null if not yet granted / revoked. */
+  refreshToken: string | null;
+  /** Access-token expiry wall time, or null if unknown. */
+  expiresAt: Date | null;
+  /** Opaque provider-specific metadata bag (instance URL, scopes, …). */
+  providerMetadata?: Record<string, unknown> | null;
+}
+
+/**
+ * Read port — fetches a decrypted integration by id.
+ *
+ * Adapters typically wrap a service/repo call that does the decryption
+ * internally. `OAuth2RefreshStrategy.resolve()` calls this on every invocation.
+ */
+export interface IIntegrationReader {
+  findByIdDecrypted(integrationId: string): Promise<DecryptedIntegration | null>;
+}
+
+/**
+ * Write port — persists a refreshed access token (and optionally rotated
+ * refresh token) with the new expiry.
+ *
+ * The subsystem calls this after a successful refresh. Implementations are
+ * responsible for re-encrypting the tokens before they hit storage.
+ *
+ * `refreshToken` semantics: `undefined` means "provider did not rotate; keep
+ * existing ciphertext". A rotated token comes through as a string.
+ */
+export interface IntegrationTokenUpdate {
+  integrationId: string;
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt: Date;
+}
+
+export interface IIntegrationTokenWriter {
+  persistRefresh(update: IntegrationTokenUpdate): Promise<void>;
+}

package/runtime/subsystems/auth/protocols/oauth-state-store.ts

@@ -0,0 +1,16 @@
+/**
+ * Auth subsystem — `IOAuthStateStore` port.
+ *
+ * CSRF protection for the OAuth2 authorize-code callback. Generic across
+ * providers. Concrete backends live under `../backends/oauth-state-store/`.
+ */
+export interface OAuthStateEntry {
+  userId: string;
+  createdAt: Date;
+}
+
+export interface IOAuthStateStore {
+  put(state: string, entry: OAuthStateEntry): Promise<void>;
+  /** Single-use consume: returns entry if present + valid, deletes it. */
+  consume(state: string): Promise<OAuthStateEntry | null>;
+}

package/runtime/subsystems/auth/runtime/integration-broken.error.ts

@@ -0,0 +1,21 @@
+/**
+ * Thrown when an OAuth2 provider returns `400 invalid_grant`/`invalid_token`
+ * on refresh — the refresh token itself is dead (user revoked, org
+ * deactivated, token expired beyond the provider's rotation window). The
+ * integration should be marked broken so background sync stops picking it
+ * up; the user re-initiates OAuth.
+ *
+ * Shared across every OAuth2 strategy.
+ */
+export class IntegrationBrokenError extends Error {
+  constructor(
+    readonly integrationId: string,
+    readonly errorCode: string,
+    readonly errorDescription: string,
+  ) {
+    super(
+      `Integration ${integrationId} broken: ${errorCode} - ${errorDescription}`,
+    );
+    this.name = 'IntegrationBrokenError';
+  }
+}

package/runtime/subsystems/auth/runtime/oauth2-refresh.strategy.ts

@@ -0,0 +1,189 @@
+/**
+ * Abstract base class for OAuth2 refresh-token strategies.
+ *
+ * Template-method pattern: `resolve()` is concrete; four small hooks inject
+ * provider specifics. Validated across two providers in dealbrain-v2
+ * (SalesforceAuthStrategy, HubSpotAuthStrategy) before extraction here — see
+ * `docs/gate-1-auth-extraction-findings.md` for the "build first, extract
+ * later" evidence.
+ *
+ * Subclass contract:
+ *   - `provider`                — slug matched against `integrations.provider`
+ *   - `defaultExpiresInSec`     — fallback when refresh response omits `expires_in`
+ *   - `tokenEndpoint()`         — URL to POST the refresh grant
+ *   - `refreshBodyExtras()`     — provider-specific body params
+ *   - `parseRefreshResponse()`  — raw JSON → ParsedRefreshResponse
+ *   - `buildCredentials()`      — stored or freshly-refreshed access token +
+ *                                 integration + optional raw refresh response
+ *                                 → provider credentials
+ *
+ * Base handles: expiry check w/ 5-min safety window, `forceRefresh` escape
+ * hatch, POST form-urlencoded body, OAuth2 error mapping to
+ * `IntegrationBrokenError`, refresh-token rotation persistence, fetch +
+ * clock injection for tests.
+ */
+import type {
+  AuthCredentials,
+  AuthResolveOptions,
+  IAuthStrategy,
+} from '../protocols/auth-strategy';
+import type {
+  DecryptedIntegration,
+  IIntegrationReader,
+  IIntegrationTokenWriter,
+} from '../protocols/integration-store';
+import { IntegrationBrokenError } from './integration-broken.error';
+
+export type FetchLike = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+/** Safety window before expiry that triggers a refresh. */
+const REFRESH_SAFETY_MS = 5 * 60 * 1000;
+
+export interface OAuth2RefreshStrategyOptions {
+  integrationReader: IIntegrationReader;
+  tokenWriter: IIntegrationTokenWriter;
+  /** Injectable fetch for tests. Defaults to the global `fetch`. */
+  fetch?: FetchLike;
+  /** Injectable clock for tests. Defaults to `Date.now`. */
+  now?: () => number;
+}
+
+export interface ParsedRefreshResponse {
+  accessToken: string;
+  /**
+   * New refresh token if the provider rotated it (HubSpot: always, Salesforce:
+   * sometimes). Omit when the provider reused the old refresh token.
+   */
+  refreshToken?: string;
+  /** Seconds from now. If omitted, subclass `defaultExpiresInSec` applies. */
+  expiresInSec?: number;
+}
+
+export abstract class OAuth2RefreshStrategy implements IAuthStrategy {
+  protected abstract readonly provider: string;
+  protected abstract readonly defaultExpiresInSec: number;
+
+  protected readonly integrationReader: IIntegrationReader;
+  protected readonly tokenWriter: IIntegrationTokenWriter;
+  protected readonly fetchImpl: FetchLike;
+  protected readonly now: () => number;
+
+  constructor(opts: OAuth2RefreshStrategyOptions) {
+    this.integrationReader = opts.integrationReader;
+    this.tokenWriter = opts.tokenWriter;
+    this.fetchImpl = opts.fetch ?? fetch;
+    this.now = opts.now ?? Date.now;
+  }
+
+  async resolve(
+    integrationId: string,
+    opts: AuthResolveOptions = {},
+  ): Promise<AuthCredentials> {
+    const integration =
+      await this.integrationReader.findByIdDecrypted(integrationId);
+    if (!integration) {
+      throw new Error(`Integration ${integrationId} not found`);
+    }
+    if (integration.provider !== this.provider) {
+      throw new Error(
+        `${this.constructor.name} called for non-${this.provider} integration ${integrationId} (provider=${integration.provider})`,
+      );
+    }
+
+    const needsRefresh =
+      opts.forceRefresh ||
+      this.isExpiring(integration.expiresAt) ||
+      !integration.accessToken;
+
+    if (!needsRefresh) {
+      return this.buildCredentials(integration.accessToken, integration);
+    }
+
+    if (!integration.refreshToken) {
+      throw new IntegrationBrokenError(
+        integrationId,
+        'no_refresh_token',
+        'Integration has no refresh token; user must reconnect',
+      );
+    }
+
+    const { parsed, raw } = await this.executeRefresh(
+      integrationId,
+      integration.refreshToken,
+    );
+    const newExpiresAt = new Date(
+      this.now() + (parsed.expiresInSec ?? this.defaultExpiresInSec) * 1000,
+    );
+    await this.tokenWriter.persistRefresh({
+      integrationId,
+      accessToken: parsed.accessToken,
+      refreshToken: parsed.refreshToken ?? undefined,
+      expiresAt: newExpiresAt,
+    });
+
+    return this.buildCredentials(parsed.accessToken, integration, raw);
+  }
+
+  protected abstract tokenEndpoint(): string;
+  protected abstract refreshBodyExtras(): Record<string, string>;
+  protected abstract parseRefreshResponse(raw: unknown): ParsedRefreshResponse;
+  protected abstract buildCredentials(
+    accessToken: string,
+    integration: DecryptedIntegration,
+    refreshRaw?: unknown,
+  ): AuthCredentials;
+
+  private async executeRefresh(
+    integrationId: string,
+    refreshToken: string,
+  ): Promise<{ parsed: ParsedRefreshResponse; raw: unknown }> {
+    const body = new URLSearchParams({
+      grant_type: 'refresh_token',
+      refresh_token: refreshToken,
+      ...this.refreshBodyExtras(),
+    });
+    const response = await this.fetchImpl(this.tokenEndpoint(), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+    });
+    if (!response.ok) {
+      const err = (await safeJson(response)) as Partial<{
+        error: string;
+        error_description: string;
+        message: string;
+      }>;
+      if (
+        response.status === 400 &&
+        (err.error === 'invalid_grant' || err.error === 'invalid_token')
+      ) {
+        throw new IntegrationBrokenError(
+          integrationId,
+          err.error ?? 'invalid_grant',
+          err.error_description ?? err.message ?? 'refresh token rejected',
+        );
+      }
+      throw new Error(
+        `${this.provider} token refresh failed: ${response.status} ${err.error ?? ''} ${err.error_description ?? err.message ?? ''}`.trim(),
+      );
+    }
+    const raw = await response.json();
+    return { parsed: this.parseRefreshResponse(raw), raw };
+  }
+
+  private isExpiring(expiresAt: Date | null): boolean {
+    if (!expiresAt) return true;
+    return expiresAt.getTime() - this.now() < REFRESH_SAFETY_MS;
+  }
+}
+
+async function safeJson(response: Response): Promise<unknown> {
+  try {
+    return await response.clone().json();
+  } catch {
+    return {};
+  }
+}

package/runtime/subsystems/auth/runtime/session-expired.error.ts

@@ -0,0 +1,39 @@
+/**
+ * Provider-agnostic marker for "the access token was rejected; a forced
+ * refresh may recover."
+ *
+ * Concrete provider error classes (e.g. SalesforceSessionExpiredError,
+ * HubSpotUnauthorizedError) either extend `SessionExpiredError` directly or
+ * set `isSessionExpired === true` on their instances. `withAuthRetry` uses
+ * the `isSessionExpiredError` predicate to decide whether to force-refresh
+ * and retry once.
+ *
+ * This discriminator replaces the SFDC-only `instanceof` check from
+ * dealbrain-v2's original `withAuthRetry`. See
+ * `docs/gate-1-auth-extraction-findings.md` (recommendation 4).
+ */
+export class SessionExpiredError extends Error {
+  /** Duck-type marker — works across package boundaries where `instanceof` fails. */
+  readonly isSessionExpired = true as const;
+
+  constructor(message = 'Access token rejected by provider') {
+    super(message);
+    this.name = 'SessionExpiredError';
+  }
+}
+
+/**
+ * Predicate used by `withAuthRetry` by default.
+ *
+ * Matches any error that either `instanceof SessionExpiredError` or carries
+ * the `isSessionExpired === true` marker property. Provider adapters that
+ * want their existing error classes to participate can simply add the
+ * marker property without touching the class hierarchy.
+ */
+export function isSessionExpiredError(err: unknown): boolean {
+  if (err instanceof SessionExpiredError) return true;
+  if (err !== null && typeof err === 'object' && 'isSessionExpired' in err) {
+    return (err as { isSessionExpired?: unknown }).isSessionExpired === true;
+  }
+  return false;
+}

package/runtime/subsystems/auth/runtime/with-auth-retry.ts

@@ -0,0 +1,50 @@
+/**
+ * Run `op` with auth-aware retry-once on session-expired errors.
+ *
+ * Pattern: resolve creds → run op → if `isSessionExpired(e)` → resolve with
+ * `forceRefresh: true` → retry → propagate. A second session-expired error
+ * on the refreshed token propagates rather than looping, so transient
+ * adapter bugs can't hang the caller.
+ *
+ * Generalisation over dealbrain's original SFDC-specific version: the
+ * session-expired classifier is injected. Providers mark their session-
+ * expired errors (via `instanceof` of a marker class, or by setting a known
+ * property) and pass a classifier matching that shape.
+ *
+ * Default classifier recognises the marker interface `SessionExpiredError`
+ * shipped in `session-expired.error.ts` — concrete provider errors that
+ * extend it (or set `isSessionExpired === true`) get retried without any
+ * further wiring.
+ */
+import type {
+  AuthCredentials,
+  IAuthStrategy,
+} from '../protocols/auth-strategy';
+import { isSessionExpiredError } from './session-expired.error';
+
+export interface WithAuthRetryOptions {
+  /**
+   * Classifier that decides whether a thrown error is a session-expired
+   * signal worth retrying once with a fresh token. Defaults to the marker-
+   * interface check in `session-expired.error.ts`.
+   */
+  isSessionExpired?: (err: unknown) => boolean;
+}
+
+export async function withAuthRetry<T>(
+  authStrategy: IAuthStrategy,
+  integrationId: string,
+  op: (credentials: AuthCredentials) => Promise<T>,
+  options: WithAuthRetryOptions = {},
+): Promise<T> {
+  const classify = options.isSessionExpired ?? isSessionExpiredError;
+
+  let creds = await authStrategy.resolve(integrationId);
+  try {
+    return await op(creds);
+  } catch (e) {
+    if (!classify(e)) throw e;
+    creds = await authStrategy.resolve(integrationId, { forceRefresh: true });
+    return op(creds);
+  }
+}

package/runtime/subsystems/bridge/assert-tenant-id.ts

@@ -0,0 +1,57 @@
+/**
+ * `assertTenantId` — shared multi-tenancy enforcement helper for the
+ * bridge subsystem (BRIDGE-8, ADR-023 §Multi-tenancy null-tenantId).
+ *
+ * Single source of truth for the three enforcement sites named in
+ * ADR-023 §Multi-tenancy and the BRIDGE-2 spec:
+ *
+ *   (a) `EventFlowService.publishAndStart`           — request-path entry
+ *   (b) `BridgeDeliveryHandler.run`                  — wrapper handler entry
+ *   (c) `DrizzleBridgeDeliveryRepo.insertDelivery`   — last-line repo defense
+ *
+ * Contract (mirrors JOB-8 / SYNC-6 — locked 2026-04-18 for jobs and
+ * carried into the bridge here):
+ *
+ *   - `multiTenant === false`           → no-op (always passes).
+ *   - `multiTenant === true`,
+ *      `tenantId === undefined`         → throw `MissingTenantIdError(site)`.
+ *   - `multiTenant === true`,
+ *      `tenantId === null`              → passes; opts the call into
+ *                                          cross-tenant work (system
+ *                                          housekeeping, framework events
+ *                                          with no owning tenant). Persists
+ *                                          to the DB as `tenant_id = NULL`.
+ *   - `multiTenant === true`,
+ *      `tenantId` is a string           → passes.
+ *
+ * The strict `undefined`-vs-`null` discrimination is the entire point —
+ * silent defaulting is exactly the failure mode that lets cross-tenant
+ * leaks ship.
+ */
+import { MissingTenantIdError } from './bridge-errors';
+
+/**
+ * Throws `MissingTenantIdError(site)` if `multiTenant === true` and
+ * `tenantId === undefined`. Explicit `null` always passes.
+ *
+ * @param site         Canonical site name — one of:
+ *                     `'EventFlowService.publishAndStart'`,
+ *                     `'BridgeDeliveryHandler.run'`,
+ *                     `'DrizzleBridgeDeliveryRepo.insertDelivery'`.
+ *                     Stable strings; ops dashboards / review reports key
+ *                     on these. Use the same string the existing tests
+ *                     and `MissingTenantIdError` JSDoc enumerate.
+ * @param multiTenant  Resolved `BRIDGE_MULTI_TENANT` flag (from
+ *                     `BridgeModule.forRoot({ multiTenant })`).
+ * @param tenantId     The tenantId the caller supplied (or didn't).
+ */
+export function assertTenantId(
+  site: string,
+  multiTenant: boolean,
+  tenantId: string | null | undefined,
+): void {
+  if (multiTenant && tenantId === undefined) {
+    throw new MissingTenantIdError(site);
+  }
+  // explicit null passes — opts into cross-tenant work
+}

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

@@ -0,0 +1,220 @@
+/**
+ * BridgeDeliveryHandler — the framework `@JobHandler` that runs every
+ * bridge-fanout wrapper on the reserved `events_*` pools (BRIDGE-5,
+ * ADR-023 §Decision 2 flow diagram).
+ *
+ * Role: when the outbox drain (BRIDGE-4) inserts a `bridge_delivery + wrapper
+ * job_run` pair, the worker that polls the wrapper's pool claims that
+ * wrapper and dispatches it to this handler. The handler:
+ *
+ *   1. Loads the `bridge_delivery` row by `ctx.input.deliveryId`.
+ *   2. Looks up the trigger entry in the codegen-emitted `bridgeRegistry`
+ *      (`runtime/subsystems/bridge/generated/registry.ts`, BRIDGE-6).
+ *      A missing entry means the trigger was renamed or removed since the
+ *      delivery row was written; mark `skipped` with
+ *      `skip_reason='trigger_unregistered'` per ADR-023 §Trigger rename
+ *      or removal.
+ *   3. Re-fetches the authoritative `domain_events` row (`IEventBus.findById`)
+ *      so `when:` / `map:` callbacks see the committed payload — never a
+ *      copy that drifted between drain and claim time.
+ *   4. Evaluates `entry.when?.(event)`. False ⇒ mark `skipped` with
+ *      `skip_reason='predicate_false'`.
+ *   5. Calls `IJobOrchestrator.start(entry.jobType, entry.map(event), …)`
+ *      INSIDE `ctx.step('spawn_user_run', …)`. The step memoization is
+ *      what makes wrapper retries (BRIDGE-1 ledger says no auto-retry past
+ *      the wrapper's own retry policy, but Phase 1 wrappers DO retry per
+ *      JOB-3) idempotent — a successful spawn followed by a transient
+ *      ledger-update failure would otherwise re-spawn on the next attempt.
+ *   6. Marks `delivered` with the spawned `runId`.
+ *
+ * Pool registration: BRIDGE-5 ships ONE `@JobHandler` registration with
+ * `pool: 'events_change'` (the default). The wrapper rows the drain
+ * inserts carry `pool: events_<direction>` per row, so workers polling
+ * `events_inbound` / `events_outbound` claim and dispatch to this same
+ * handler class regardless of the metadata pool — the worker filter is on
+ * `job_run.pool`, not on `@JobHandler.meta.pool`. BRIDGE-8 confirms the
+ * three pools are active and registered at module init. The
+ * `@framework/*` job-type prefix exempts this registration from the
+ * reserved-pool validator (BRIDGE-5 added that exemption to
+ * `job-worker.module.ts`).
+ *
+ * Tenant threading: when `BRIDGE_MULTI_TENANT=true`, the handler asserts
+ * `delivery.tenantId !== undefined` before the spawn (the column is
+ * nullable, so explicit `null` is allowed for cross-tenant work — same
+ * contract as JOB-8). BRIDGE-8 wires the assertion via the
+ * `BRIDGE_MULTI_TENANT` token.
+ *
+ * Failure path: any throw inside the handler propagates up; the worker's
+ * normal retry policy (declared on the `@JobHandler` here as `attempts:
+ * 3, backoff: exponential, baseMs: 250`) absorbs transient infra blips.
+ * After exhaustion, the wrapper transitions to `failed`; the outer error
+ * handler catches and calls `repo.markFailed(...)` so the delivery row
+ * reflects the final state. Operators see `bridge_delivery.status='failed'`
+ * surface via the `idx_bridge_delivery_status` partial index (BRIDGE-1).
+ */
+import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
+
+import { JOB_ORCHESTRATOR } from '../jobs/jobs-domain.tokens';
+import type { IJobOrchestrator } from '../jobs/job-orchestrator.protocol';
+import {
+  JobHandler,
+  JobHandlerBase,
+  type JobContext,
+} from '../jobs/job-handler.base';
+
+import { EVENT_BUS } from '../events/events.tokens';
+import type { IEventBus, DomainEvent } from '../events/event-bus.protocol';
+import type { EventTypeName } from '../events/generated/types';
+
+import {
+  BRIDGE_DELIVERY_REPO,
+  BRIDGE_MULTI_TENANT,
+  BRIDGE_REGISTRY,
+} from './bridge.tokens';
+import type {
+  BridgeRegistry,
+  BridgeTriggerEntry,
+  IJobBridge,
+} from './bridge.protocol';
+import { assertTenantId } from './assert-tenant-id';
+
+/** Stable canonical job type — referenced by BRIDGE-4 wrapper inserts. */
+export const BRIDGE_DELIVERY_JOB_TYPE = '@framework/bridge_delivery' as const;
+
+/** Stable canonical step id — referenced for memoization across attempts. */
+const SPAWN_USER_RUN_STEP = 'spawn_user_run' as const;
+
+export interface BridgeDeliveryInput {
+  /** PK of the `bridge_delivery` row this wrapper services. */
+  deliveryId: string;
+}
+
+@Injectable()
+@JobHandler<BridgeDeliveryInput>(BRIDGE_DELIVERY_JOB_TYPE, {
+  pool: 'events_change',
+  retry: { attempts: 3, backoff: 'exponential', baseMs: 250 },
+  replayFrom: 'last_step',
+})
+export class BridgeDeliveryHandler extends JobHandlerBase<
+  BridgeDeliveryInput,
+  { runId: string } | { skipped: true; reason: string }
+> {
+  private readonly classLogger = new Logger(BridgeDeliveryHandler.name);
+
+  constructor(
+    @Inject(BRIDGE_DELIVERY_REPO) private readonly repo: IJobBridge,
+    @Inject(JOB_ORCHESTRATOR) private readonly orchestrator: IJobOrchestrator,
+    @Inject(EVENT_BUS) private readonly events: IEventBus,
+    @Inject(BRIDGE_REGISTRY) private readonly registry: BridgeRegistry,
+    @Optional()
+    @Inject(BRIDGE_MULTI_TENANT)
+    private readonly multiTenant: boolean = false,
+  ) {
+    super();
+  }
+
+  async run(
+    ctx: JobContext<BridgeDeliveryInput>,
+  ): Promise<{ runId: string } | { skipped: true; reason: string }> {
+    const { deliveryId } = ctx.input;
+
+    // Step 1 — locate the delivery row by primary key.
+    const delivery = await this.repo.findDeliveryById(deliveryId);
+    if (!delivery) {
+      // The drain wrote a wrapper job_run but the delivery row is gone
+      // (manual ops cleanup, or delete-cascade from the parent event).
+      // No row → no work; return without throwing so the wrapper marks
+      // completed cleanly.
+      this.classLogger.warn(
+        `bridge_delivery row '${deliveryId}' not found; wrapper completes ` +
+          `without spawning a user job.`,
+      );
+      return { skipped: true, reason: 'delivery_row_missing' };
+    }
+
+    // Step 2 — multi-tenancy gate. Site (b) of the three ADR-023
+    // §Multi-tenancy enforcement sites; shared helper from BRIDGE-8.
+    // The DB always returns string|null, never undefined; this branch
+    // exists for the in-memory backend's older test fixtures and to
+    // pin the contract in shape-typed tests.
+    assertTenantId(
+      'BridgeDeliveryHandler.run',
+      this.multiTenant,
+      delivery.tenantId,
+    );
+
+    // Step 3 — load the typed event row.
+    const event = await this.events.findById(delivery.eventId);
+    if (!event) {
+      // FK from bridge_delivery.event_id → domain_events.id should make
+      // this impossible at the DB layer, but defensive: if the row is
+      // missing we mark skipped, not failed (no work the bridge can do).
+      this.classLogger.warn(
+        `domain_events row '${delivery.eventId}' missing for delivery ` +
+          `'${deliveryId}'; marking skipped.`,
+      );
+      await this.repo.markSkipped(delivery.id, 'event_row_missing');
+      return { skipped: true, reason: 'event_row_missing' };
+    }
+
+    // Step 4 — registry lookup. Handles trigger rename/removal cleanly.
+    const entry = this.findRegistryEntry(event.type, delivery.triggerId);
+    if (!entry) {
+      await this.repo.markSkipped(delivery.id, 'trigger_unregistered');
+      return { skipped: true, reason: 'trigger_unregistered' };
+    }
+
+    // Step 5 — `when:` predicate.
+    if (entry.when && !entry.when(event as never)) {
+      await this.repo.markSkipped(delivery.id, 'predicate_false');
+      return { skipped: true, reason: 'predicate_false' };
+    }
+
+    // Step 6 — memoized spawn. `ctx.step` records the result in
+    // `job_step` and on retry returns the cached `{ runId }` so a
+    // transient failure between `orchestrator.start` and `markDelivered`
+    // doesn't double-spawn the user job.
+    const input = entry.map(event as never);
+    const { runId } = await ctx.step<{ runId: string }>(
+      SPAWN_USER_RUN_STEP,
+      async () => {
+        const run = await this.orchestrator.start(entry.jobType, input, {
+          parentRunId: ctx.run.id,
+          triggerSource: 'event',
+          triggerRef: delivery.eventId,
+          tenantId: delivery.tenantId,
+        });
+        return { runId: run.id };
+      },
+    );
+
+    // Step 7 — ledger transition.
+    await this.repo.markDelivered(delivery.id, runId);
+    return { runId };
+  }
+
+  /**
+   * Locate the registry entry for `(eventType, triggerId)`. Linear scan
+   * over the per-event-type array — N is the number of triggers declared
+   * for one event, typically 1–5; the table is not big enough to warrant
+   * a secondary index.
+   */
+  private findRegistryEntry(
+    eventType: string,
+    triggerId: string,
+  ): BridgeTriggerEntry | undefined {
+    const candidates =
+      this.registry[eventType as EventTypeName] ?? undefined;
+    if (!candidates) return undefined;
+    return candidates.find((c) => c.triggerId === triggerId) as
+      | BridgeTriggerEntry
+      | undefined;
+  }
+}
+
+/**
+ * Re-export for BRIDGE-7 facade Case B and BRIDGE-4 wrapper insert.
+ * Single source of truth for the canonical type string keeps refactors
+ * in one place.
+ */
+export { BRIDGE_DELIVERY_JOB_TYPE as BridgeDeliveryJobType };