@pattern-stack/codegen 0.15.1 → 0.15.3

package/dist/chunk-4JLJYWJC.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../runtime/subsystems/events/event-bus.drizzle-backend.ts"],"sourcesContent":["/**\n * DrizzleEventBus — Postgres-backed event bus using the transactional outbox pattern.\n *\n * Events are inserted into the `domain_events` table within the caller's\n * Drizzle transaction. A background polling loop (started on module init)\n * reads unprocessed events and dispatches them to registered subscribers.\n *\n * When the transaction rolls back, the event is never persisted — no\n * phantom events.\n *\n * Pool awareness (EVT-4):\n * - On `publish`/`publishMany` the backend writes `metadata.pool`,\n *   `metadata.direction`, and `metadata.tenantId` into the first-class\n *   `pool` / `direction` / `tenant_id` columns (metadata JSON is still\n *   written unchanged for protocol stability).\n * - The drain loop filters by `opts.pools` when provided, so separate\n *   processes (e.g. one per `events_inbound` / `events_change` /\n *   `events_outbound`) can claim only their own lane. `pools: undefined`\n *   drains all pending rows (backwards-compatible behaviour).\n *\n * EVT-Q7: No stale-event sweeper. `FOR UPDATE SKIP LOCKED` is\n * self-healing — the row is only locked for the duration of the\n * enclosing polling transaction; the `status='processed'` update happens\n * within that same transaction. There is no `claimed_at` semantic (unlike\n * jobs), so no stale rows can exist.\n *\n * This backend is suitable until you need real-time fan-out or very high\n * throughput. At that point, swap the backend for Redis Streams or similar\n * via EventsModule.forRoot({ backend: '...' }) without touching use cases.\n */\nimport { Injectable, OnModuleDestroy, OnModuleInit, Inject, Logger, Optional } from '@nestjs/common';\nimport { eq, and, inArray, asc, desc, gte, lt, or, sql, type SQL } from 'drizzle-orm';\nimport type { DomainEvent, DrizzleTransaction, IEventBus } from './event-bus.protocol';\nimport type {\n  EventPage,\n  IEventReadPort,\n  ListEventsQuery,\n} from './event-read.protocol';\nimport {\n  clampEventLimit,\n  decodeEventCursor,\n  encodeEventCursor,\n} from './event-keyset-cursor';\nimport type { DrizzleClient } from '../../types/drizzle';\nimport { domainEvents, type DomainEventRecord } from './domain-events.schema';\nimport { DRIZZLE } from '../../constants/tokens';\nimport { EVENTS_MODULE_OPTIONS } from './events.tokens';\nimport type { EventsModuleOptions } from './events.module';\nimport { BRIDGE_OUTBOX_DRAIN_HOOK } from '../bridge/bridge.tokens';\nimport type { IBridgeOutboxDrainHook } from '../bridge/bridge.protocol';\n\n/** How long to wait between polling cycles (ms). */\nconst POLL_INTERVAL_MS = 1_000;\n/** Max events claimed per polling cycle to bound memory usage. */\nconst POLL_BATCH_SIZE = 50;\n\n/**\n * Row shape built from `metadata` for writing into `domain_events`. Keeps\n * the per-event extraction logic in one place so publish/publishMany stay\n * in sync.\n */\nfunction toInsertValues(event: DomainEvent, multiTenant: boolean) {\n  const metadata = event.metadata ?? undefined;\n  const pool = (metadata?.['pool'] as string | undefined) ?? null;\n  const direction = (metadata?.['direction'] as string | undefined) ?? null;\n  // AUDIT-1: tier defaults to 'domain' when absent. The DB CHECK\n  // constraint (`domain_events_tier_routing_check`) enforces the\n  // tier ⇔ routing-fields invariant at the storage boundary; no\n  // JS-side assertion is needed here.\n  const tier = (metadata?.['tier'] as string | undefined) ?? 'domain';\n  const base = {\n    id: event.id,\n    type: event.type,\n    aggregateId: event.aggregateId,\n    aggregateType: event.aggregateType,\n    payload: event.payload,\n    occurredAt: event.occurredAt,\n    processedAt: null,\n    status: 'pending' as const,\n    metadata: event.metadata,\n    pool,\n    direction,\n    tier,\n  };\n  // EVT-8: `tenant_id` is a scaffold-time conditional column, emitted only\n  // when `events.multi_tenant: true`. Only write it when multi-tenancy is\n  // on — under single-tenant scaffolds the column does not exist, so the\n  // key must be omitted from the insert.\n  if (!multiTenant) return base;\n  const tenantId = (metadata?.['tenantId'] as string | undefined) ?? null;\n  return { ...base, tenantId };\n}\n\n/**\n * Project a raw `domain_events` row into the narrow `EventSummary` shape.\n * Shared with the memory backend via this helper kept module-local to each\n * backend (the events subsystem has no cross-backend projection file yet;\n * the two are byte-identical and small).\n */\nfunction toEventSummary(r: DomainEventRecord) {\n  const metadata = (r.metadata ?? undefined) as\n    | Record<string, unknown>\n    | undefined;\n  const rootRunId = metadata?.['rootRunId'];\n  return {\n    id: r.id,\n    type: r.type,\n    aggregateId: r.aggregateId,\n    aggregateType: r.aggregateType,\n    status: r.status,\n    pool: r.pool,\n    direction: r.direction,\n    tier: r.tier,\n    rootRunId: typeof rootRunId === 'string' ? rootRunId : null,\n    // EVT-8: `tenant_id` is a scaffold-time conditional column. Read it\n    // structurally so this projection typechecks against both the\n    // multi-tenant schema (column present) and the single-tenant schema\n    // (column absent → undefined → null).\n    tenantId: (r as { tenantId?: string | null }).tenantId ?? null,\n    occurredAt:\n      r.occurredAt instanceof Date\n        ? r.occurredAt\n        : new Date(r.occurredAt as unknown as string),\n    processedAt:\n      r.processedAt == null\n        ? null\n        : r.processedAt instanceof Date\n          ? r.processedAt\n          : new Date(r.processedAt as unknown as string),\n  };\n}\n\n@Injectable()\nexport class DrizzleEventBus implements IEventBus, IEventReadPort, OnModuleInit, OnModuleDestroy {\n  private readonly logger = new Logger(DrizzleEventBus.name);\n  private polling = false;\n  private pollTimer: ReturnType<typeof setTimeout> | null = null;\n  private readonly handlers = new Map<string, Set<(event: DomainEvent) => Promise<void>>>();\n  private readonly opts: EventsModuleOptions;\n\n  constructor(\n    @Inject(DRIZZLE) private readonly db: DrizzleClient,\n    @Optional() @Inject(EVENTS_MODULE_OPTIONS) opts?: EventsModuleOptions,\n    /**\n     * Bridge subsystem hook (BRIDGE-4). Optional — when the bridge\n     * subsystem is not installed in the consuming app, this token is\n     * undefined and the drain skips the bridge block entirely (preserves\n     * EVT-4 baseline behaviour).\n     *\n     * When provided, `processEvent` is invoked once per drained event\n     * INSIDE the per-event tx, before `processed_at` is stamped. The\n     * hook owns all knowledge of `bridge_delivery + wrapper job_run`\n     * shapes; the events subsystem stays unaware of bridge schemas.\n     */\n    @Optional()\n    @Inject(BRIDGE_OUTBOX_DRAIN_HOOK)\n    private readonly bridgeHook: IBridgeOutboxDrainHook | null = null,\n  ) {\n    // Default so direct construction (e.g. integration tests not going\n    // through Nest DI) keeps working without an explicit options object.\n    this.opts = opts ?? { backend: 'drizzle' };\n  }\n\n  // ============================================================================\n  // Lifecycle\n  // ============================================================================\n\n  async onModuleInit(): Promise<void> {\n    this.polling = true;\n    this.schedulePoll();\n  }\n\n  async onModuleDestroy(): Promise<void> {\n    this.polling = false;\n    if (this.pollTimer) {\n      clearTimeout(this.pollTimer);\n      this.pollTimer = null;\n    }\n  }\n\n  // ============================================================================\n  // IEventBus\n  // ============================================================================\n\n  async publish(event: DomainEvent, tx?: DrizzleTransaction): Promise<void> {\n    const client = (tx ?? this.db) as DrizzleClient;\n    const multiTenant = this.opts.multiTenant ?? false;\n    await client.insert(domainEvents).values(toInsertValues(event, multiTenant));\n  }\n\n  async publishMany(events: DomainEvent[], tx?: DrizzleTransaction): Promise<void> {\n    if (events.length === 0) return;\n    const client = (tx ?? this.db) as DrizzleClient;\n    const multiTenant = this.opts.multiTenant ?? false;\n    await client\n      .insert(domainEvents)\n      .values(events.map((e) => toInsertValues(e, multiTenant)));\n  }\n\n  async findById(eventId: string): Promise<DomainEvent | null> {\n    const rows = await this.db\n      .select()\n      .from(domainEvents)\n      .where(eq(domainEvents.id, eventId))\n      .limit(1);\n    const row = rows[0];\n    if (!row) return null;\n    return {\n      id: row.id,\n      type: row.type,\n      aggregateId: row.aggregateId,\n      aggregateType: row.aggregateType,\n      payload: row.payload as Record<string, unknown>,\n      occurredAt:\n        row.occurredAt instanceof Date\n          ? row.occurredAt\n          : new Date(row.occurredAt as unknown as string),\n      metadata: (row.metadata ?? undefined) as\n        | Record<string, unknown>\n        | undefined,\n    };\n  }\n\n  subscribe<T extends DomainEvent = DomainEvent>(\n    eventType: string,\n    handler: (event: T) => Promise<void>,\n  ): () => void {\n    if (!this.handlers.has(eventType)) {\n      this.handlers.set(eventType, new Set());\n    }\n    const set = this.handlers.get(eventType)!;\n    const h = handler as (event: DomainEvent) => Promise<void>;\n    set.add(h);\n    return () => {\n      set.delete(h);\n    };\n  }\n\n  // ============================================================================\n  // IEventReadPort (OBS-LIST-1)\n  // ============================================================================\n\n  async listEvents(query: ListEventsQuery = {}): Promise<EventPage> {\n    const limit = clampEventLimit(query.limit);\n    const conditions: SQL<unknown>[] = [];\n\n    if (query.poolId) conditions.push(eq(domainEvents.pool, query.poolId));\n    if (query.direction)\n      conditions.push(eq(domainEvents.direction, query.direction));\n    if (query.since) conditions.push(gte(domainEvents.occurredAt, query.since));\n    if (query.rootRunId) {\n      // Filter on the JSON correlation id: metadata->>'rootRunId'.\n      conditions.push(\n        sql`${domainEvents.metadata}->>'rootRunId' = ${query.rootRunId}`,\n      );\n    }\n    // EVT-8: `tenant_id` is a scaffold-time conditional column (emitted only\n    // under `events.multi_tenant: true`). Guard the filter behind the same\n    // `multiTenant` flag, and read the column structurally so this backend\n    // typechecks against both the multi-tenant schema (column present) and\n    // the single-tenant schema (column absent). When multi-tenancy is off\n    // there is no `tenant_id` column to filter on.\n    if (this.opts.multiTenant && query.tenantId !== undefined) {\n      const tenantIdColumn = (\n        domainEvents as unknown as { tenantId: typeof domainEvents.pool }\n      ).tenantId;\n      conditions.push(\n        query.tenantId === null\n          ? (sql`${tenantIdColumn} is null` as SQL<unknown>)\n          : eq(tenantIdColumn, query.tenantId),\n      );\n    }\n\n    // Keyset seek: WHERE (occurred_at, id) < (cursorOccurredAt, cursorId).\n    if (query.cursor) {\n      const keyset = decodeEventCursor(query.cursor);\n      if (keyset) {\n        conditions.push(\n          or(\n            lt(domainEvents.occurredAt, keyset.occurredAt),\n            and(\n              eq(domainEvents.occurredAt, keyset.occurredAt),\n              lt(domainEvents.id, keyset.id),\n            ),\n          )!,\n        );\n      }\n    }\n\n    const rows = (await this.db\n      .select()\n      .from(domainEvents)\n      .where(conditions.length > 0 ? and(...conditions) : undefined)\n      .orderBy(desc(domainEvents.occurredAt), desc(domainEvents.id))\n      .limit(limit + 1)) as DomainEventRecord[];\n\n    const hasMore = rows.length > limit;\n    const page = hasMore ? rows.slice(0, limit) : rows;\n    const items = page.map(toEventSummary);\n    const last = page[page.length - 1];\n    const nextCursor =\n      hasMore && last\n        ? encodeEventCursor({ occurredAt: last.occurredAt, id: last.id })\n        : null;\n\n    return { items, nextCursor };\n  }\n\n  // ============================================================================\n  // Polling\n  // ============================================================================\n\n  /**\n   * Test-only hook. Runs exactly one drain cycle and returns. Production\n   * code goes through `onModuleInit` → `schedulePoll`, which calls the\n   * same `processBatch` under a timer.\n   */\n  async drainOnce(): Promise<void> {\n    await this.processBatch();\n  }\n\n  private schedulePoll(): void {\n    if (!this.polling) return;\n    this.pollTimer = setTimeout(async () => {\n      try {\n        await this.processBatch();\n      } catch (err) {\n        this.logger.error(`Poll cycle error: ${err}`);\n      } finally {\n        this.schedulePoll();\n      }\n    }, POLL_INTERVAL_MS);\n  }\n\n  /**\n   * Drain one batch (BRIDGE-4 restructure of EVT-4).\n   *\n   * Two-phase per drained event:\n   *\n   *   1. **Per-event transaction** — bridge fanout (`bridgeHook.processEvent`)\n   *      + `processed_at` stamp. Both write through the same `tx`. A throw\n   *      inside the tx (only infra-level failures should reach here, since\n   *      the hook tolerates null direction and registry misses inline)\n   *      rolls back the bridge inserts AND the `processed_at` stamp; the\n   *      event re-claims on the next drain cycle. Bridge `UNIQUE\n   *      (event_id, trigger_id)` makes the retry idempotent.\n   *\n   *   2. **After commit** — dispatch in-process subscribers (`IEventBus.subscribe`\n   *      handlers). This deliberately runs OUTSIDE the per-event tx (lead\n   *      decision 2026-04-22): subscribers are best-effort and must not\n   *      gate forward progress or roll back bridge fanout. Subscriber\n   *      errors are caught + logged; `processed_at` is already committed.\n   *      The old `MAX_RETRIES=3` in-process retry loop and the\n   *      `failed`-stamping path were removed in BRIDGE-4 along with their\n   *      coupling.\n   *\n   * The `processed_at` UPDATE carries `AND status='pending'` (BRIDGE-4\n   * tightening — without it, a hypothetical double-claim could double-stamp\n   * the timestamp). The per-event tx + `FOR UPDATE SKIP LOCKED` claim\n   * make this defensive belt-and-suspenders.\n   */\n  private async processBatch(): Promise<void> {\n    const pools = this.opts.pools;\n\n    // Build WHERE: status='pending' [AND pool IN (...)]\n    const whereClause: SQL<unknown> = pools && pools.length > 0\n      ? (and(eq(domainEvents.status, 'pending'), inArray(domainEvents.pool, pools)) as SQL<unknown>)\n      : eq(domainEvents.status, 'pending');\n\n    // Claim a batch with FOR UPDATE SKIP LOCKED so multiple pollers don't\n    // double-dispatch. The lock is released when the outer transaction\n    // commits — which is fine because the immediately-following per-event\n    // tx flips status='processed' under its own `AND status='pending'`\n    // guard, so a re-claim of the same row in a subsequent batch is a\n    // no-op UPDATE.\n    const rows = await this.db.transaction(async (tx) => {\n      return tx\n        .select()\n        .from(domainEvents)\n        .where(whereClause)\n        .orderBy(asc(domainEvents.occurredAt))\n        .limit(POLL_BATCH_SIZE)\n        .for('update', { skipLocked: true });\n    }) as Array<typeof domainEvents.$inferSelect>;\n\n    for (const row of rows) {\n      const event: DomainEvent = {\n        id: row.id,\n        type: row.type,\n        aggregateId: row.aggregateId,\n        aggregateType: row.aggregateType,\n        payload: row.payload as Record<string, unknown>,\n        occurredAt: row.occurredAt instanceof Date ? row.occurredAt : new Date(row.occurredAt as unknown as string),\n        metadata: (row.metadata ?? undefined) as Record<string, unknown> | undefined,\n      };\n\n      // Phase 1 — per-event tx: bridge fanout + processed_at stamp.\n      try {\n        await this.db.transaction(async (tx) => {\n          if (this.bridgeHook) {\n            await this.bridgeHook.processEvent(event, tx);\n          }\n          await tx\n            .update(domainEvents)\n            .set({ status: 'processed', processedAt: new Date() })\n            .where(\n              and(\n                eq(domainEvents.id, event.id),\n                eq(domainEvents.status, 'pending'),\n              ),\n            );\n        });\n      } catch (err) {\n        // Infra-level failure inside the per-event tx — bridge inserts\n        // and processed_at both rolled back. Log and move on; the next\n        // drain cycle re-claims the row. UNIQUE on bridge_delivery makes\n        // the retry idempotent.\n        this.logger.error(\n          `Per-event tx failed for event id=${event.id} type=${event.type}: ${err}`,\n        );\n        continue;\n      }\n\n      // Phase 2 — best-effort subscriber dispatch. Errors are logged\n      // and discarded; processed_at is already committed. Subscribers\n      // are observability + cache-busts + small ancillary work; they\n      // must not gate forward progress.\n      try {\n        await this.dispatch(event);\n      } catch (err) {\n        this.logger.error(\n          `Subscriber dispatch failed for event id=${event.id} type=${event.type} ` +\n            `(processed_at already committed; failure does not retry): ${err}`,\n        );\n      }\n    }\n  }\n\n  private async dispatch(event: DomainEvent): Promise<void> {\n    const set = this.handlers.get(event.type);\n    if (!set) return;\n\n    let firstError: unknown;\n    for (const handler of set) {\n      try {\n        await handler(event);\n      } catch (err) {\n        this.logger.error(\n          `Handler error for event type \"${event.type}\" (id: ${event.id}): ${err}`,\n        );\n        if (firstError === undefined) {\n          firstError = err;\n        }\n      }\n    }\n\n    if (firstError !== undefined) {\n      throw firstError;\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-4KNXX6TI.js

@@ -0,0 +1,29 @@
+import {
+  UnknownEntityError
+} from "./chunk-3CJFPU6Q.js";
+
+// runtime/subsystems/integration/entity-change-source-registry.memory.ts
+var MemoryEntityChangeSourceRegistry = class {
+  constructor(sources) {
+    this.sources = sources;
+  }
+  sources;
+  get(name) {
+    const source = this.sources.get(name);
+    if (!source) {
+      throw new UnknownEntityError(name, [...this.sources.keys()]);
+    }
+    return source;
+  }
+  has(name) {
+    return this.sources.has(name);
+  }
+  entities() {
+    return [...this.sources.keys()];
+  }
+};
+
+export {
+  MemoryEntityChangeSourceRegistry
+};
+//# sourceMappingURL=chunk-4KNXX6TI.js.map

package/dist/chunk-4KNXX6TI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../runtime/subsystems/integration/entity-change-source-registry.memory.ts"],"sourcesContent":["/**\n * Integration subsystem — in-memory entity-change-source registry\n *\n * Default `IEntityChangeSourceRegistry` backed by a `Map<entityName, source>`.\n * Track D's codegen-emitted aggregator folds per-provider adapter\n * contributions into one of these and binds it under\n * `ENTITY_CHANGE_SOURCE_REGISTRY` (RFC-0001 §3); tests and simple consumers\n * construct it directly.\n *\n * See {@link ./entity-change-source-registry.protocol} for the contract and\n * #336 for scope.\n */\n\nimport type { IChangeSource } from './integration-change-source.protocol';\nimport {\n  type IEntityChangeSourceRegistry,\n  UnknownEntityError,\n} from './entity-change-source-registry.protocol';\n\nexport class MemoryEntityChangeSourceRegistry\n  implements IEntityChangeSourceRegistry\n{\n  constructor(private readonly sources: Map<string, IChangeSource<unknown>>) {}\n\n  get<T = unknown>(name: string): IChangeSource<T> {\n    const source = this.sources.get(name);\n    if (!source) {\n      throw new UnknownEntityError(name, [...this.sources.keys()]);\n    }\n    return source as IChangeSource<T>;\n  }\n\n  has(name: string): boolean {\n    return this.sources.has(name);\n  }\n\n  entities(): readonly string[] {\n    return [...this.sources.keys()];\n  }\n}\n"],"mappings":";;;;;AAmBO,IAAM,mCAAN,MAEP;AAAA,EACE,YAA6B,SAA8C;AAA9C;AAAA,EAA+C;AAAA,EAA/C;AAAA,EAE7B,IAAiB,MAAgC;AAC/C,UAAM,SAAS,KAAK,QAAQ,IAAI,IAAI;AACpC,QAAI,CAAC,QAAQ;AACX,YAAM,IAAI,mBAAmB,MAAM,CAAC,GAAG,KAAK,QAAQ,KAAK,CAAC,CAAC;AAAA,IAC7D;AACA,WAAO;AAAA,EACT;AAAA,EAEA,IAAI,MAAuB;AACzB,WAAO,KAAK,QAAQ,IAAI,IAAI;AAAA,EAC9B;AAAA,EAEA,WAA8B;AAC5B,WAAO,CAAC,GAAG,KAAK,QAAQ,KAAK,CAAC;AAAA,EAChC;AACF;","names":[]}

package/dist/chunk-4LH67P4U.js

@@ -0,0 +1,17 @@
+// runtime/subsystems/bridge/bridge.tokens.ts
+var BRIDGE_DELIVERY_REPO = "BRIDGE_DELIVERY_REPO";
+var EVENT_FLOW = "EVENT_FLOW";
+var BRIDGE_MULTI_TENANT = "BRIDGE_MULTI_TENANT";
+var BRIDGE_MODULE_OPTIONS = "BRIDGE_MODULE_OPTIONS";
+var BRIDGE_REGISTRY = "BRIDGE_REGISTRY";
+var BRIDGE_OUTBOX_DRAIN_HOOK = "BRIDGE_OUTBOX_DRAIN_HOOK";
+
+export {
+  BRIDGE_DELIVERY_REPO,
+  EVENT_FLOW,
+  BRIDGE_MULTI_TENANT,
+  BRIDGE_MODULE_OPTIONS,
+  BRIDGE_REGISTRY,
+  BRIDGE_OUTBOX_DRAIN_HOOK
+};
+//# sourceMappingURL=chunk-4LH67P4U.js.map

package/dist/chunk-4LH67P4U.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../runtime/subsystems/bridge/bridge.tokens.ts"],"sourcesContent":["/**\n * Injection tokens for the bridge subsystem (ADR-023 Phase 2, BRIDGE-2).\n *\n * String constants (not Symbols) so they match by value across import\n * boundaries — same convention as `EVENT_BUS` / `EVENTS_MULTI_TENANT` in the\n * events subsystem (per EVT-6 §Implementation Notes). The jobs subsystem\n * uses Symbols for its analogous tokens; we keep the bridge file internally\n * consistent with the events convention because the bridge is conceptually\n * downstream of (and imports from) the events module.\n */\n\n/**\n * Token for the `IJobBridge` repo backend (memory in BRIDGE-3, Drizzle in\n * BRIDGE-4). Consumed by `BridgeDeliveryHandler` (BRIDGE-5), the outbox\n * drain (BRIDGE-4 modification), and `EventFlowService` (BRIDGE-7).\n */\nexport const BRIDGE_DELIVERY_REPO = 'BRIDGE_DELIVERY_REPO' as const;\n\n/**\n * Token for the `IEventFlow` facade implementation (BRIDGE-7). Use cases\n * inject this in preference to `EVENT_BUS` / `TYPED_EVENT_BUS` — calling\n * `eventFlow.publish(...)` / `eventFlow.publishAndStart(...)` is the\n * sanctioned authoring surface (ADR-023 §Decision 7).\n */\nexport const EVENT_FLOW = 'EVENT_FLOW' as const;\n\n/**\n * Token for the resolved multi-tenancy flag, provided by\n * `BridgeModule.forRoot({ multiTenant })` in BRIDGE-8. Consumed by\n * `EventFlowService.publishAndStart` (entry), `BridgeDeliveryHandler.handle`\n * (entry), and `DrizzleBridgeDeliveryRepo.insertDelivery` (pre-write) — the\n * three enforcement sites called out in ADR-023 §Multi-tenancy.\n */\nexport const BRIDGE_MULTI_TENANT = 'BRIDGE_MULTI_TENANT' as const;\n\n/**\n * Token for the resolved `BridgeModuleOptions` object. Provided by\n * `BridgeModule.forRoot(...)` / `forRootAsync(...)` in BRIDGE-8.\n * Mirrors `EVENTS_MODULE_OPTIONS` and `JOBS_DOMAIN_OPTIONS` shape — backends\n * inject this when they need to observe additional module configuration\n * (e.g. pool overrides) without each adding a dedicated token.\n */\nexport const BRIDGE_MODULE_OPTIONS = 'BRIDGE_MODULE_OPTIONS' as const;\n\n/**\n * Token for the codegen-emitted `bridgeRegistry` — the\n * `Record<EventTypeName, BridgeTriggerEntry[]>` map that drives\n * outbox-drain trigger lookup (BRIDGE-4) and `EventFlowService` Case B\n * dedup (BRIDGE-7). Provider registration lands in BRIDGE-8; the token is\n * declared here so generated code (BRIDGE-6) can import it without\n * depending on the still-being-formalised module.\n */\nexport const BRIDGE_REGISTRY = 'BRIDGE_REGISTRY' as const;\n\n\n/**\n * Token for the `IBridgeOutboxDrainHook` implementation (BRIDGE-4).\n * Injected `@Optional()` into `DrizzleEventBus` — when the bridge\n * subsystem is not installed the token is undefined and the events\n * outbox drain skips the bridge block entirely (preserves EVT-4\n * baseline behaviour).\n *\n * Resolution order: `BridgeModule.forRoot()` provides this token in\n * BRIDGE-8 alongside the rest of the bridge subsystem. `EventsModule`\n * itself never provides it; the events subsystem stays unaware of the\n * bridge unless the consumer wires it.\n */\nexport const BRIDGE_OUTBOX_DRAIN_HOOK = 'BRIDGE_OUTBOX_DRAIN_HOOK' as const;\n"],"mappings":";AAgBO,IAAM,uBAAuB;AAQ7B,IAAM,aAAa;AASnB,IAAM,sBAAsB;AAS5B,IAAM,wBAAwB;AAU9B,IAAM,kBAAkB;AAexB,IAAM,2BAA2B;","names":[]}

package/dist/chunk-4MF3HKJA.js

@@ -0,0 +1,94 @@
+// runtime/subsystems/integration/poll-change-source.ts
+var PollChangeSource = class {
+  label;
+  adapter;
+  filters;
+  externalIdSourceField;
+  source;
+  /**
+   * When `poll.provenance === 'cdc'`, the field on the emitted record from
+   * which `Change<T>.dedupKey` is read — sourced from `poll.cursor.field`
+   * (Stripe-style event endpoints carry the event id on the record itself
+   * and the cursor advances over the same id). `null` for default poll
+   * provenance, which does NOT populate `dedupKey`.
+   */
+  dedupKeySourceField;
+  composed;
+  constructor(opts) {
+    if (opts.config.mode !== "poll") {
+      throw new Error(
+        `PollChangeSource requires DetectionConfig.mode === 'poll'; got '${opts.config.mode}'`
+      );
+    }
+    const config = opts.config;
+    const externalIdMapping = config.mapping.find(
+      (m) => m.target === "external_id"
+    );
+    if (!externalIdMapping) {
+      throw new Error(
+        "PollChangeSource: DetectionConfig.mapping must include an entry with target 'external_id' so emitted Change<T>.externalId can be populated"
+      );
+    }
+    this.externalIdSourceField = externalIdMapping.source;
+    this.adapter = opts.adapter;
+    this.filters = config.filters;
+    const isCdc = config.poll.provenance === "cdc";
+    this.source = isCdc ? "cdc" : "poll";
+    this.dedupKeySourceField = isCdc ? config.poll.cursor.field : null;
+    this.label = opts.label ?? `poll-change-source:${externalIdMapping.source}`;
+    const inner = (sub, cur) => this.fetch(sub, cur);
+    const middlewares = opts.middlewares ?? [];
+    this.composed = middlewares.reduceRight(
+      (next, mw) => mw(next),
+      inner
+    );
+  }
+  listChanges(subscription, cursor) {
+    return this.composed(subscription, cursor);
+  }
+  async *fetch(subscription, cursor) {
+    const ctx = {
+      subscription,
+      cursor,
+      filters: this.filters
+    };
+    for await (const { record, cursor: nextCursor } of this.adapter(ctx)) {
+      const externalIdRaw = record[this.externalIdSourceField];
+      if (typeof externalIdRaw !== "string" || externalIdRaw.length === 0) {
+        throw new Error(
+          `PollChangeSource: record missing string '${this.externalIdSourceField}' \u2014 emitted records MUST carry the canonical external id keyed by the mapping source`
+        );
+      }
+      let dedupKey;
+      if (this.dedupKeySourceField !== null) {
+        const dedupRaw = record[this.dedupKeySourceField];
+        if (typeof dedupRaw !== "string" || dedupRaw.length === 0) {
+          throw new Error(
+            `PollChangeSource: cdc-provenance record missing string '${this.dedupKeySourceField}' \u2014 when poll.provenance === 'cdc' the cursor.field must be present on each record so dedupKey can be populated`
+          );
+        }
+        dedupKey = dedupRaw;
+      }
+      const change = {
+        externalId: externalIdRaw,
+        // Polling cannot distinguish create vs. update vs. delete on its
+        // own — all yielded records are surfaced as 'updated'. The
+        // orchestrator's diff stage classifies create-vs-update against
+        // local state; soft-delete detection is out of scope for the
+        // primitive (consumer drives via tombstone records or a separate
+        // sweep — see ADR-033).
+        operation: "updated",
+        record,
+        cursor: nextCursor,
+        source: this.source,
+        ...dedupKey !== void 0 ? { dedupKey } : {}
+      };
+      yield change;
+    }
+  }
+};
+
+export {
+  PollChangeSource
+};
+//# sourceMappingURL=chunk-4MF3HKJA.js.map

package/dist/chunk-4MF3HKJA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../runtime/subsystems/integration/poll-change-source.ts"],"sourcesContent":["/**\n * Integration subsystem — `PollChangeSource<T>` primitive (#226-3, ADR-033).\n *\n * Generic poll-mode `IChangeSource<T>` implementation parameterized by a\n * parsed `DetectionConfig` (poll mode) and a consumer-supplied\n * `PollFetchCallback<T>`. The primitive owns:\n *\n *   - filter resolution (flat-AND vocabulary per epic decision Q3 — richer\n *     boolean expressions deferred);\n *   - field mapping → `Change.externalId` derivation;\n *   - cursor strategy passthrough (the orchestrator passes the prior cursor\n *     by-value per ADR-033 / #226-2; the callback yields the next cursor\n *     per record; the primitive simply stamps it onto `Change<T>`);\n *   - `Change<T>.source` provenance (`'poll'` by default);\n *   - middleware-chain composition (the `ChangeMiddleware<T>` shape\n *     locked in #226-1).\n *\n * Shape locks (decision memo Q5):\n *   - `PollFetchContext = { subscription, cursor, filters }` — explicitly\n *     NO `userId` / `tenantId`. Run-scope identity is closed over by the\n *     consumer at adapter construction (or resolved inside the callback\n *     via consumer services). Threading it through the seam would force\n *     port expansion every time run-context grows.\n *\n * The adapter callback returns `{ record: T; cursor: PollCursor }` — the\n * primitive does not reach into the record to extract a cursor itself.\n * `cursor.field` from `DetectionConfig.poll.cursor` is metadata for codegen\n * + adapters; the primitive trusts what the callback yielded.\n */\n\nimport type {\n  DetectionConfig,\n  ResolvedFilter,\n} from './detection-config.schema';\nimport type {\n  Change,\n  ChangeSource,\n  IChangeSource,\n  IntegrationSubscriptionView,\n} from './integration-change-source.protocol';\nimport type {\n  ChangeIterator,\n  ChangeMiddleware,\n} from './integration-middleware.protocol';\n\n// ============================================================================\n// Cursor + adapter callback shapes\n// ============================================================================\n\n/**\n * Opaque poll-cursor shape. Each provider/entity pair binds it concretely\n * via the cursor strategy (`{ systemModstamp }`, `{ replayId }`, etc.); the\n * primitive treats it as an opaque value to pass through.\n */\nexport type PollCursor = unknown;\n\n/**\n * The context the primitive forwards to the adapter callback. Locked to\n * exactly three fields per decision memo Q5 — `userId` / `tenantId` are\n * NOT here on purpose.\n */\nexport interface PollFetchContext {\n  readonly subscription: IntegrationSubscriptionView;\n  readonly cursor: PollCursor | null;\n  readonly filters: readonly ResolvedFilter[];\n}\n\n/**\n * Consumer-supplied fetch callback. Returns an async iterable of\n * `{ record, cursor }` pairs — `record` is already the canonical `T`\n * (the adapter does provider-side translation), `cursor` is the post-record\n * cursor the orchestrator should persist if the run completes successfully.\n */\nexport type PollFetchCallback<T> = (\n  ctx: PollFetchContext,\n) => AsyncIterable<{ record: T; cursor: PollCursor }>;\n\n// ============================================================================\n// Constructor options\n// ============================================================================\n\nexport interface PollChangeSourceOptions<T> {\n  /** Consumer-supplied fetch callback. */\n  readonly adapter: PollFetchCallback<T>;\n  /**\n   * Parsed detection config. MUST be `mode: 'poll'`; the constructor\n   * throws if a webhook config is supplied. Codegen-emitted factories\n   * call `DetectionConfigSchema.parse(...)` upstream so this is a safety\n   * net, not the primary validation point.\n   */\n  readonly config: DetectionConfig;\n  /**\n   * Optional middleware chain. First element is the outermost layer:\n   * sees `(subscription, cursor)` first and yielded `Change<T>` last.\n   * Locked shape (#226-1) — the primitive composes them with its own\n   * `listChanges` implementation as the innermost iterator.\n   */\n  readonly middlewares?: ReadonlyArray<ChangeMiddleware<T>>;\n  /**\n   * Optional human label for run logs (e.g. `'salesforce-poll-opportunity'`).\n   * Defaults to a derived label based on the subscription domain at\n   * construction time fallback — adapters are encouraged to provide one.\n   */\n  readonly label?: string;\n}\n\n// ============================================================================\n// PollChangeSource<T>\n// ============================================================================\n\nexport class PollChangeSource<T> implements IChangeSource<T> {\n  public readonly label: string;\n\n  private readonly adapter: PollFetchCallback<T>;\n  private readonly filters: readonly ResolvedFilter[];\n  private readonly externalIdSourceField: string;\n  private readonly source: ChangeSource;\n  /**\n   * When `poll.provenance === 'cdc'`, the field on the emitted record from\n   * which `Change<T>.dedupKey` is read — sourced from `poll.cursor.field`\n   * (Stripe-style event endpoints carry the event id on the record itself\n   * and the cursor advances over the same id). `null` for default poll\n   * provenance, which does NOT populate `dedupKey`.\n   */\n  private readonly dedupKeySourceField: string | null;\n  private readonly composed: ChangeIterator<T>;\n\n  constructor(opts: PollChangeSourceOptions<T>) {\n    if (opts.config.mode !== 'poll') {\n      throw new Error(\n        `PollChangeSource requires DetectionConfig.mode === 'poll'; got '${(opts.config as { mode: string }).mode}'`,\n      );\n    }\n    const config = opts.config;\n\n    // Field mapping: locate the entry whose canonical `target` is `external_id`.\n    // Adapters emit T already-mapped, but the primitive needs to know which key\n    // on T carries the external id so it can stamp `Change.externalId`. That key\n    // is the mapping's `source` (the field on the emitted record), NOT its\n    // `target` (the canonical column) — they differ whenever the canonical\n    // record is vendor-neutral camelCase (e.g. `source: 'externalId'` →\n    // `target: 'external_id'`). Source of truth is the mapping table — codegen\n    // emits it from YAML, the primitive reads it here.\n    const externalIdMapping = config.mapping.find(\n      (m) => m.target === 'external_id',\n    );\n    if (!externalIdMapping) {\n      throw new Error(\n        \"PollChangeSource: DetectionConfig.mapping must include an entry with target 'external_id' so emitted Change<T>.externalId can be populated\",\n      );\n    }\n    this.externalIdSourceField = externalIdMapping.source;\n\n    this.adapter = opts.adapter;\n    this.filters = config.filters;\n    // Provenance: `mode: 'poll'` defaults to `'poll'`; opt into `'cdc'` via\n    // `poll.provenance` (Stripe-style event endpoints — wired in #226-4).\n    // CDC provenance also stamps `dedupKey` from the cursor's `field`, since\n    // those endpoints surface a per-event id on each record (the same id the\n    // cursor advances over).\n    const isCdc = config.poll.provenance === 'cdc';\n    this.source = isCdc ? 'cdc' : 'poll';\n    this.dedupKeySourceField = isCdc ? config.poll.cursor.field : null;\n\n    this.label =\n      opts.label ?? `poll-change-source:${externalIdMapping.source}`;\n\n    // Compose middleware chain. The terminal iterator is `this.fetch`\n    // bound to `this`. First middleware in the array is the outermost\n    // layer (sees subscription/cursor first, yielded changes last).\n    const inner: ChangeIterator<T> = (sub, cur) => this.fetch(sub, cur);\n    const middlewares = opts.middlewares ?? [];\n    this.composed = middlewares.reduceRight<ChangeIterator<T>>(\n      (next, mw) => mw(next),\n      inner,\n    );\n  }\n\n  listChanges(\n    subscription: IntegrationSubscriptionView,\n    cursor: unknown | null,\n  ): AsyncIterable<Change<T>> {\n    return this.composed(subscription, cursor);\n  }\n\n  private async *fetch(\n    subscription: IntegrationSubscriptionView,\n    cursor: unknown | null,\n  ): AsyncIterable<Change<T>> {\n    const ctx: PollFetchContext = {\n      subscription,\n      cursor: cursor as PollCursor | null,\n      filters: this.filters,\n    };\n\n    for await (const { record, cursor: nextCursor } of this.adapter(ctx)) {\n      const externalIdRaw = (record as Record<string, unknown>)[\n        this.externalIdSourceField\n      ];\n      if (typeof externalIdRaw !== 'string' || externalIdRaw.length === 0) {\n        throw new Error(\n          `PollChangeSource: record missing string '${this.externalIdSourceField}' — emitted records MUST carry the canonical external id keyed by the mapping source`,\n        );\n      }\n      let dedupKey: string | undefined;\n      if (this.dedupKeySourceField !== null) {\n        const dedupRaw = (record as Record<string, unknown>)[\n          this.dedupKeySourceField\n        ];\n        if (typeof dedupRaw !== 'string' || dedupRaw.length === 0) {\n          throw new Error(\n            `PollChangeSource: cdc-provenance record missing string '${this.dedupKeySourceField}' — when poll.provenance === 'cdc' the cursor.field must be present on each record so dedupKey can be populated`,\n          );\n        }\n        dedupKey = dedupRaw;\n      }\n\n      const change: Change<T> = {\n        externalId: externalIdRaw,\n        // Polling cannot distinguish create vs. update vs. delete on its\n        // own — all yielded records are surfaced as 'updated'. The\n        // orchestrator's diff stage classifies create-vs-update against\n        // local state; soft-delete detection is out of scope for the\n        // primitive (consumer drives via tombstone records or a separate\n        // sweep — see ADR-033).\n        operation: 'updated',\n        record,\n        cursor: nextCursor,\n        source: this.source,\n        ...(dedupKey !== undefined ? { dedupKey } : {}),\n      };\n      yield change;\n    }\n  }\n}\n"],"mappings":";AA8GO,IAAM,mBAAN,MAAsD;AAAA,EAC3C;AAAA,EAEC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA;AAAA,EACA;AAAA,EAEjB,YAAY,MAAkC;AAC5C,QAAI,KAAK,OAAO,SAAS,QAAQ;AAC/B,YAAM,IAAI;AAAA,QACR,mEAAoE,KAAK,OAA4B,IAAI;AAAA,MAC3G;AAAA,IACF;AACA,UAAM,SAAS,KAAK;AAUpB,UAAM,oBAAoB,OAAO,QAAQ;AAAA,MACvC,CAAC,MAAM,EAAE,WAAW;AAAA,IACtB;AACA,QAAI,CAAC,mBAAmB;AACtB,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,SAAK,wBAAwB,kBAAkB;AAE/C,SAAK,UAAU,KAAK;AACpB,SAAK,UAAU,OAAO;AAMtB,UAAM,QAAQ,OAAO,KAAK,eAAe;AACzC,SAAK,SAAS,QAAQ,QAAQ;AAC9B,SAAK,sBAAsB,QAAQ,OAAO,KAAK,OAAO,QAAQ;AAE9D,SAAK,QACH,KAAK,SAAS,sBAAsB,kBAAkB,MAAM;AAK9D,UAAM,QAA2B,CAAC,KAAK,QAAQ,KAAK,MAAM,KAAK,GAAG;AAClE,UAAM,cAAc,KAAK,eAAe,CAAC;AACzC,SAAK,WAAW,YAAY;AAAA,MAC1B,CAAC,MAAM,OAAO,GAAG,IAAI;AAAA,MACrB;AAAA,IACF;AAAA,EACF;AAAA,EAEA,YACE,cACA,QAC0B;AAC1B,WAAO,KAAK,SAAS,cAAc,MAAM;AAAA,EAC3C;AAAA,EAEA,OAAe,MACb,cACA,QAC0B;AAC1B,UAAM,MAAwB;AAAA,MAC5B;AAAA,MACA;AAAA,MACA,SAAS,KAAK;AAAA,IAChB;AAEA,qBAAiB,EAAE,QAAQ,QAAQ,WAAW,KAAK,KAAK,QAAQ,GAAG,GAAG;AACpE,YAAM,gBAAiB,OACrB,KAAK,qBACP;AACA,UAAI,OAAO,kBAAkB,YAAY,cAAc,WAAW,GAAG;AACnE,cAAM,IAAI;AAAA,UACR,4CAA4C,KAAK,qBAAqB;AAAA,QACxE;AAAA,MACF;AACA,UAAI;AACJ,UAAI,KAAK,wBAAwB,MAAM;AACrC,cAAM,WAAY,OAChB,KAAK,mBACP;AACA,YAAI,OAAO,aAAa,YAAY,SAAS,WAAW,GAAG;AACzD,gBAAM,IAAI;AAAA,YACR,2DAA2D,KAAK,mBAAmB;AAAA,UACrF;AAAA,QACF;AACA,mBAAW;AAAA,MACb;AAEA,YAAM,SAAoB;AAAA,QACxB,YAAY;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAOZ,WAAW;AAAA,QACX;AAAA,QACA,QAAQ;AAAA,QACR,QAAQ,KAAK;AAAA,QACb,GAAI,aAAa,SAAY,EAAE,SAAS,IAAI,CAAC;AAAA,MAC/C;AACA,YAAM;AAAA,IACR;AAAA,EACF;AACF;","names":[]}

package/dist/chunk-4MVGAMUA.js

@@ -0,0 +1,40 @@
+import {
+  LocalStorageBackend
+} from "./chunk-JWNHNUYL.js";
+import {
+  MemoryStorageBackend
+} from "./chunk-3SZFUTXE.js";
+import {
+  STORAGE
+} from "./chunk-NYBCQZC7.js";
+import {
+  __decorateClass
+} from "./chunk-2E224ZSN.js";
+
+// runtime/subsystems/storage/storage.module.ts
+import { Module } from "@nestjs/common";
+var StorageModule = class {
+  static forRoot(options = { backend: "local" }) {
+    const provider = options.backend === "local" ? {
+      provide: STORAGE,
+      useFactory: () => new LocalStorageBackend(options.basePath ?? "./storage")
+    } : {
+      provide: STORAGE,
+      useClass: MemoryStorageBackend
+    };
+    return {
+      module: StorageModule,
+      global: true,
+      providers: [provider],
+      exports: [STORAGE]
+    };
+  }
+};
+StorageModule = __decorateClass([
+  Module({})
+], StorageModule);
+
+export {
+  StorageModule
+};
+//# sourceMappingURL=chunk-4MVGAMUA.js.map

package/dist/chunk-4MVGAMUA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../runtime/subsystems/storage/storage.module.ts"],"sourcesContent":["/**\n * Storage subsystem — NestJS module factory\n *\n * Register once in AppModule (global: true means all other modules can inject\n * STORAGE without importing StorageModule themselves):\n *\n * ```typescript\n * // app.module.ts\n * @Module({\n *   imports: [\n *     StorageModule.forRoot({ backend: 'local', basePath: './uploads' }),\n *   ],\n * })\n * export class AppModule {}\n * ```\n *\n * Swap to memory backend in tests:\n * ```typescript\n * Test.createTestingModule({\n *   imports: [StorageModule.forRoot({ backend: 'memory' })],\n * });\n * ```\n */\nimport { type DynamicModule, Module } from '@nestjs/common';\nimport { LocalStorageBackend } from './storage.local-backend';\nimport { MemoryStorageBackend } from './storage.memory-backend';\nimport { STORAGE } from './storage.tokens';\n\nexport interface StorageModuleOptions {\n  /** Which backend to activate. */\n  backend: 'local' | 'memory';\n  /**\n   * Base path for the local backend (resolved to an absolute path).\n   * Ignored when backend is 'memory'. Defaults to `./storage`.\n   */\n  basePath?: string;\n}\n\n@Module({})\nexport class StorageModule {\n  static forRoot(options: StorageModuleOptions = { backend: 'local' }): DynamicModule {\n    const provider =\n      options.backend === 'local'\n        ? {\n            provide: STORAGE,\n            useFactory: () => new LocalStorageBackend(options.basePath ?? './storage'),\n          }\n        : {\n            provide: STORAGE,\n            useClass: MemoryStorageBackend,\n          };\n\n    return {\n      module: StorageModule,\n      global: true,\n      providers: [provider],\n      exports: [STORAGE],\n    };\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;AAuBA,SAA6B,cAAc;AAgBpC,IAAM,gBAAN,MAAoB;AAAA,EACzB,OAAO,QAAQ,UAAgC,EAAE,SAAS,QAAQ,GAAkB;AAClF,UAAM,WACJ,QAAQ,YAAY,UAChB;AAAA,MACE,SAAS;AAAA,MACT,YAAY,MAAM,IAAI,oBAAoB,QAAQ,YAAY,WAAW;AAAA,IAC3E,IACA;AAAA,MACE,SAAS;AAAA,MACT,UAAU;AAAA,IACZ;AAEN,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,WAAW,CAAC,QAAQ;AAAA,MACpB,SAAS,CAAC,OAAO;AAAA,IACnB;AAAA,EACF;AACF;AApBa,gBAAN;AAAA,EADN,OAAO,CAAC,CAAC;AAAA,GACG;","names":[]}