@pattern-stack/codegen 0.10.1 → 0.11.0

package/dist/runtime/subsystems/{sync → integration}/build-change-source.d.ts

@@ -1,12 +1,12 @@
 import { DetectionConfig } from './detection-config.schema.js';
-import { IChangeSource } from './sync-change-source.protocol.js';
-import { ChangeMiddleware } from './sync-middleware.protocol.js';
+import { IChangeSource } from './integration-change-source.protocol.js';
+import { ChangeMiddleware } from './integration-middleware.protocol.js';
 import { PollFetchCallback } from './poll-change-source.js';
 import { WebhookFetchCallback } from './webhook-change-source.js';
 import 'zod';
 
 /**
- * Sync subsystem — `buildChangeSource()` runtime factory (#250, ADR-033.1 b).
+ * Integration subsystem — `buildChangeSource()` runtime factory (#250, ADR-033.1 b).
  *
  * Mode-dispatching constructor for `IChangeSource<T>`. Codegen-emitted
  * provider modules call this from `useFactory` once they've resolved the

package/dist/runtime/subsystems/{sync → integration}/build-change-source.js

@@ -1,4 +1,4 @@
-// runtime/subsystems/sync/poll-change-source.ts
+// runtime/subsystems/integration/poll-change-source.ts
 var PollChangeSource = class {
   label;
   adapter;
@@ -88,7 +88,7 @@ var PollChangeSource = class {
   }
 };
 
-// runtime/subsystems/sync/webhook-change-source.ts
+// runtime/subsystems/integration/webhook-change-source.ts
 var WebhookChangeSource = class {
   label;
   queue;
@@ -159,7 +159,7 @@ var WebhookChangeSource = class {
   }
 };
 
-// runtime/subsystems/sync/build-change-source.ts
+// runtime/subsystems/integration/build-change-source.ts
 function buildChangeSource(cfg, fetch, middlewares = []) {
   switch (cfg.mode) {
     case "poll":

package/dist/runtime/subsystems/integration/build-change-source.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../runtime/subsystems/integration/poll-change-source.ts","../../../../runtime/subsystems/integration/webhook-change-source.ts","../../../../runtime/subsystems/integration/build-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 canonical `external_id` target. Adapters\n    // emit T already-mapped, but the primitive needs to know which key on\n    // T carries the external id so it can stamp `Change.externalId`. Source\n    // of truth is the mapping table — codegen emits it from YAML, the\n    // 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.target;\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 target`,\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","/**\n * Integration subsystem — `WebhookChangeSource<T>` primitive (#226-4, ADR-033).\n *\n * Generic webhook-mode `IChangeSource<T>` implementation parameterized by a\n * parsed `DetectionConfig` (webhook mode) and a consumer-supplied\n * `WebhookFetchCallback<T>` that iterates a consumer-owned inbound staging\n * queue. The primitive owns:\n *\n *   - canonical `Change<T>.source = 'webhook'` stamping;\n *   - `dedupKey` derivation from the configured `webhook.eventIdField` on\n *     the emitted record;\n *   - `externalId` derivation from the mapping table's `external_id` target\n *     (mirrors `PollChangeSource`);\n *   - middleware-chain composition via the locked `ChangeMiddleware<T>` shape\n *     (#226-1) — same composition seam as the poll primitive.\n *\n * The primitive is **passive**: it iterates whatever the consumer-owned\n * queue yields. It does NOT synchronously drive the orchestrator, does NOT\n * own a transport, and does NOT manage acks. The inbound staging table\n * schema is consumer-owned and deferred per ADR-0002 §Phase 4 — the\n * `WebhookFetchCallback<T>` is the queue contract the consumer injects.\n *\n * Shape locks (decision memo Q5, mirrored from poll primitive):\n *   - `WebhookFetchContext = { subscription, cursor }` — explicitly NO\n *     `userId` / `tenantId`. Run-scope identity is closed over by the\n *     consumer at queue construction or resolved inside the callback via\n *     consumer services. There are no `filters` on the webhook context —\n *     filtering is done at registration / on the staging row, not at the\n *     port seam (the queue is already filtered by the time the primitive\n *     iterates).\n *\n * Long-lived streaming CDC primitives (SFDC Pub-Sub gRPC, Debezium/Kafka,\n * Postgres logical replication) are deferred to `#226-8` — they need a\n * fundamentally different lifecycle (`subscribe(onChange, onError)`,\n * server-paced backpressure, ack-on-yield) and shouldn't be retrofitted\n * into either this primitive or the poll primitive.\n */\n\nimport type { DetectionConfig } from './detection-config.schema';\nimport type {\n  Change,\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 + queue callback shapes\n// ============================================================================\n\n/**\n * Opaque webhook cursor shape. Webhook mode typically has a cursor of\n * `{ ts: ISO-string }` (last drained staging-row timestamp) but the\n * primitive treats it as opaque. Consumer-owned queue iterators interpret\n * it however the staging schema needs.\n */\nexport type WebhookCursor = unknown;\n\n/**\n * Context the primitive forwards to the queue iterator. Locked to exactly\n * two fields per the same Q5 reasoning that locks `PollFetchContext` — no\n * `userId` / `tenantId`.\n */\nexport interface WebhookFetchContext {\n  readonly subscription: IntegrationSubscriptionView;\n  readonly cursor: WebhookCursor | null;\n}\n\n/**\n * Consumer-supplied queue iterator. Returns an async iterable of\n * `{ record }` pairs — the consumer drains the inbound staging queue and\n * emits already-mapped canonical records `T`. The primitive stamps\n * `source: 'webhook'` and `dedupKey` from the record's configured\n * `webhook.eventIdField`; the consumer is the one who decided when a\n * staging row is \"ready\" to drain.\n *\n * Webhook mode has no per-record cursor advance — the staging-row drain\n * order is consumer policy (FIFO by ingestion timestamp, by event id, etc.)\n * and is opaque to the primitive. The orchestrator's last-yielded cursor\n * is whatever the consumer chooses to surface, if anything.\n */\nexport type WebhookFetchCallback<T> = (\n  ctx: WebhookFetchContext,\n) => AsyncIterable<{ record: T; cursor?: WebhookCursor }>;\n\n// ============================================================================\n// Constructor options\n// ============================================================================\n\nexport interface WebhookChangeSourceOptions<T> {\n  /** Consumer-supplied inbound queue iterator. */\n  readonly queue: WebhookFetchCallback<T>;\n  /**\n   * Parsed detection config. MUST be `mode: 'webhook'`; the constructor\n   * throws if a poll config is supplied. Codegen-emitted factories call\n   * `DetectionConfigSchema.parse(...)` upstream so this is a safety net,\n   * not the primary validation point.\n   */\n  readonly config: DetectionConfig;\n  /**\n   * Optional middleware chain. Same shape and composition rules as\n   * `PollChangeSource` — first element is the outermost layer.\n   */\n  readonly middlewares?: ReadonlyArray<ChangeMiddleware<T>>;\n  /**\n   * Optional human label for run logs (e.g. `'stripe-webhook-charge'`).\n   * Defaults to a derived label based on the mapping at construction.\n   */\n  readonly label?: string;\n}\n\n// ============================================================================\n// WebhookChangeSource<T>\n// ============================================================================\n\nexport class WebhookChangeSource<T> implements IChangeSource<T> {\n  public readonly label: string;\n\n  private readonly queue: WebhookFetchCallback<T>;\n  private readonly externalIdSourceField: string;\n  private readonly eventIdSourceField: string;\n  private readonly composed: ChangeIterator<T>;\n\n  constructor(opts: WebhookChangeSourceOptions<T>) {\n    if (opts.config.mode !== 'webhook') {\n      throw new Error(\n        `WebhookChangeSource requires DetectionConfig.mode === 'webhook'; got '${(opts.config as { mode: string }).mode}'`,\n      );\n    }\n    const config = opts.config;\n\n    // Field mapping: locate the canonical `external_id` target — mirrors the\n    // poll primitive's contract. Adapters emit records already-mapped; the\n    // primitive needs to know which key on T carries the external id so it\n    // can stamp `Change.externalId`.\n    const externalIdMapping = config.mapping.find(\n      (m) => m.target === 'external_id',\n    );\n    if (!externalIdMapping) {\n      throw new Error(\n        \"WebhookChangeSource: DetectionConfig.mapping must include an entry with target 'external_id' so emitted Change<T>.externalId can be populated\",\n      );\n    }\n    this.externalIdSourceField = externalIdMapping.target;\n    this.eventIdSourceField = config.webhook.eventIdField;\n\n    this.queue = opts.queue;\n\n    this.label =\n      opts.label ?? `webhook-change-source:${externalIdMapping.source}`;\n\n    // Compose middleware chain — same shape as PollChangeSource.\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: WebhookFetchContext = {\n      subscription,\n      cursor: cursor as WebhookCursor | null,\n    };\n\n    for await (const { record, cursor: nextCursor } of this.queue(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          `WebhookChangeSource: record missing string '${this.externalIdSourceField}' — emitted records MUST carry the canonical external id keyed by the mapping target`,\n        );\n      }\n      const eventIdRaw = (record as Record<string, unknown>)[\n        this.eventIdSourceField\n      ];\n      if (typeof eventIdRaw !== 'string' || eventIdRaw.length === 0) {\n        throw new Error(\n          `WebhookChangeSource: record missing string '${this.eventIdSourceField}' — webhook records MUST carry the event id (DetectionConfig.webhook.eventIdField) so Change<T>.dedupKey can be populated`,\n        );\n      }\n\n      const change: Change<T> = {\n        externalId: externalIdRaw,\n        // Webhook mode cannot distinguish create vs. update vs. delete on\n        // its own — the orchestrator's diff stage handles classification.\n        // Tombstone / soft-delete detection is consumer-driven (same as\n        // poll mode — see ADR-033).\n        operation: 'updated',\n        record,\n        cursor: nextCursor ?? null,\n        source: 'webhook',\n        dedupKey: eventIdRaw,\n      };\n      yield change;\n    }\n  }\n}\n","/**\n * Integration subsystem — `buildChangeSource()` runtime factory (#250, ADR-033.1 b).\n *\n * Mode-dispatching constructor for `IChangeSource<T>`. Codegen-emitted\n * provider modules call this from `useFactory` once they've resolved the\n * provider-keyed `fetches[provider]` callback and parsed the per-entity\n * `DetectionConfig`. Switching is on `cfg.mode` so the option-bag shape\n * difference between primitives (`adapter` vs. `queue`) stays internal —\n * consumers pass one fetch callback regardless of mode.\n */\nimport type { DetectionConfig } from './detection-config.schema';\nimport type { IChangeSource } from './integration-change-source.protocol';\nimport type { ChangeMiddleware } from './integration-middleware.protocol';\nimport {\n  PollChangeSource,\n  type PollFetchCallback,\n} from './poll-change-source';\nimport {\n  WebhookChangeSource,\n  type WebhookFetchCallback,\n} from './webhook-change-source';\n\nexport function buildChangeSource<T>(\n  cfg: DetectionConfig,\n  fetch: PollFetchCallback<T> | WebhookFetchCallback<T>,\n  middlewares: ReadonlyArray<ChangeMiddleware<T>> = [],\n): IChangeSource<T> {\n  switch (cfg.mode) {\n    case 'poll':\n      return new PollChangeSource<T>({\n        adapter: fetch as PollFetchCallback<T>,\n        config: cfg,\n        middlewares,\n      });\n    case 'webhook':\n      return new WebhookChangeSource<T>({\n        queue: fetch as WebhookFetchCallback<T>,\n        config: cfg,\n        middlewares,\n      });\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/runtime/subsystems/{sync → integration}/deep-equal.differ.d.ts

@@ -1,10 +1,10 @@
-import { IFieldDiffer, DiffResult } from './sync-field-diff.protocol.js';
+import { IFieldDiffer, DiffResult } from './integration-field-diff.protocol.js';
 import 'zod';
 
 interface DeepEqualDifferOptions {
     /**
      * Extra field names to ignore in addition to the defaults. Consumers can
-     * pass `['sync_version']` etc. to augment the base list; values here are
+     * pass `['integration_version']` etc. to augment the base list; values here are
      * merged (not replaced) with `DEFAULT_IGNORE_FIELDS`.
      */
     readonly ignore?: readonly string[];

package/dist/runtime/subsystems/{sync → integration}/deep-equal.differ.js

@@ -9,7 +9,7 @@ var __decorateClass = (decorators, target, key, kind) => {
   return result;
 };
 
-// runtime/subsystems/sync/deep-equal.differ.ts
+// runtime/subsystems/integration/deep-equal.differ.ts
 import { Injectable } from "@nestjs/common";
 var DEFAULT_IGNORE_FIELDS = /* @__PURE__ */ new Set([
   "id",

package/dist/runtime/subsystems/integration/deep-equal.differ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../runtime/subsystems/integration/deep-equal.differ.ts"],"sourcesContent":["/**\n * DeepEqualDiffer — default `IFieldDiffer<T>` for the integration subsystem (SYNC-5).\n *\n * Walks every field of `incoming` against `existing`, emitting a structured\n * per-field diff (`{ from, to }`) for every field whose value changed.\n * Returns `'noop'` when the record is unchanged.\n *\n * Design decisions (extracted from the upstream consumer + HS-9 findings):\n *\n * 1. **Ignore list** — row metadata that sinks/services stamp unconditionally\n *    so upstream cannot reasonably disagree:\n *      `id`, `createdAt`, `updatedAt`, `deletedAt`, `type`,\n *      `lastModifiedAt`, `fields`, `providerMetadata`\n *    (`fields` is the EAV bag — it's diffed by the sink's EAV dual-write\n *    path, not at the canonical-record layer.)\n *\n * 2. **`providerChangedFields` hint (CDC)** — when present, restricts the\n *    comparison to the hinted field set. The hint is advisory; fields in\n *    the ignore list are still filtered out even when hinted. Provider\n *    hints are field-NAME-level; they don't override the ignore rules.\n *\n * 3. **Date → ISO string** — `Date` instances are normalized to\n *    `toISOString()` before comparison. Sinks return `Date` from the DB\n *    driver; adapters typically deliver strings. Direct `===` would\n *    always say \"changed.\"\n *\n * 4. **Decimal-string vs number** — Postgres `numeric` columns return as\n *    strings through Drizzle; adapters deliver numbers. When one side is a\n *    number and the other is a numeric string that parses to the same\n *    number, they're equal. The normalizer does NOT coerce non-numeric\n *    strings, and it preserves zero-vs-null distinction.\n *\n * 5. **null-existing path** — `diff(null, incoming)` produces a full\n *    created-shape diff (`{from: null, to: <value>}` for every non-ignored\n *    field). Orchestrator sees this and records `operation: 'created'`.\n */\nimport { Injectable } from '@nestjs/common';\nimport type {\n  DiffResult,\n  FieldDiff,\n  IFieldDiffer,\n} from './integration-field-diff.protocol';\n\n/**\n * Default ignore list. Keep in integration with consumer canonical-record shapes —\n * adding a row-metadata field here means no integration will ever mark it changed.\n *\n * Includes the columns contributed by the `external_id_tracking` behavior\n * (`external_id`/`externalId`, `provider`, `provider_metadata`/`providerMetadata`).\n * These are integration-tracking metadata, not domain attributes: they ride on the\n * canonical record but must never register as a field change (the external id\n * is the record's identity, not a mutable value). Listed in both snake_case\n * and camelCase so the differ ignores them regardless of the consumer's\n * canonical projection casing.\n */\nconst DEFAULT_IGNORE_FIELDS: ReadonlySet<string> = new Set([\n  'id',\n  'createdAt',\n  'updatedAt',\n  'deletedAt',\n  'type',\n  'lastModifiedAt',\n  'fields',\n  'external_id',\n  'externalId',\n  'provider',\n  'provider_metadata',\n  'providerMetadata',\n]);\n\nexport interface DeepEqualDifferOptions {\n  /**\n   * Extra field names to ignore in addition to the defaults. Consumers can\n   * pass `['integration_version']` etc. to augment the base list; values here are\n   * merged (not replaced) with `DEFAULT_IGNORE_FIELDS`.\n   */\n  readonly ignore?: readonly string[];\n}\n\n@Injectable()\nexport class DeepEqualDiffer<T extends Record<string, unknown>>\n  implements IFieldDiffer<T>\n{\n  private readonly ignore: ReadonlySet<string>;\n\n  constructor(opts: DeepEqualDifferOptions = {}) {\n    if (opts.ignore && opts.ignore.length > 0) {\n      this.ignore = new Set([...DEFAULT_IGNORE_FIELDS, ...opts.ignore]);\n    } else {\n      this.ignore = DEFAULT_IGNORE_FIELDS;\n    }\n  }\n\n  diff(\n    existing: T | null,\n    incoming: T,\n    providerChangedFields?: string[],\n  ): DiffResult {\n    // Created-shape: every non-ignored field becomes `{from: null, to}`.\n    if (existing === null) {\n      const out: FieldDiff = {};\n      for (const key of Object.keys(incoming)) {\n        if (this.ignore.has(key)) continue;\n        const value = (incoming as Record<string, unknown>)[key];\n        // Skip fields that are themselves null/undefined — a created record\n        // doesn't need to declare \"this field is null now\" for every\n        // untouched column.\n        if (value === null || value === undefined) continue;\n        out[key] = { from: null, to: value };\n      }\n      return Object.keys(out).length === 0 ? 'noop' : out;\n    }\n\n    // Field set to compare. `providerChangedFields` narrows to a hint set;\n    // ignored fields are filtered out regardless of hint.\n    const candidates = new Set<string>();\n    if (providerChangedFields && providerChangedFields.length > 0) {\n      for (const key of providerChangedFields) {\n        if (!this.ignore.has(key)) candidates.add(key);\n      }\n    } else {\n      for (const key of Object.keys(incoming)) {\n        if (!this.ignore.has(key)) candidates.add(key);\n      }\n      // Also include keys that exist on existing but not on incoming —\n      // e.g. a field that was cleared. This would otherwise be missed when\n      // incoming carries an undefined column we drop from the iteration.\n      for (const key of Object.keys(existing)) {\n        if (this.ignore.has(key)) continue;\n        if (!(key in (incoming as Record<string, unknown>))) continue;\n        candidates.add(key);\n      }\n    }\n\n    const out: FieldDiff = {};\n    for (const key of candidates) {\n      const before = (existing as Record<string, unknown>)[key];\n      const after = (incoming as Record<string, unknown>)[key];\n      if (!isEqual(before, after)) {\n        out[key] = { from: before ?? null, to: after ?? null };\n      }\n    }\n\n    return Object.keys(out).length === 0 ? 'noop' : out;\n  }\n}\n\n// ─── equality helpers ───────────────────────────────────────────────────────\n\n/**\n * Field-level equality with the canonical-integration normalizations:\n *   - Date → toISOString (adapters deliver strings)\n *   - numeric-string vs number → numeric equality when both parse\n *   - deep equality for plain objects/arrays (single-level is enough for\n *     canonical records; nested records travel as jsonb columns where the\n *     sink already owns the comparison)\n */\nfunction isEqual(a: unknown, b: unknown): boolean {\n  if (a === b) return true;\n\n  const na = normalize(a);\n  const nb = normalize(b);\n  if (na === nb) return true;\n\n  // After normalization: both may still be non-primitive objects.\n  if (\n    typeof na === 'object' &&\n    typeof nb === 'object' &&\n    na !== null &&\n    nb !== null\n  ) {\n    return deepEqualObject(na as Record<string, unknown>, nb as Record<string, unknown>);\n  }\n\n  // Numeric string ↔ number: when one side is a number and the other is a\n  // string that parses to the same finite number.\n  const numericEqual = maybeNumericEqual(na, nb) || maybeNumericEqual(nb, na);\n  return numericEqual;\n}\n\nfunction normalize(value: unknown): unknown {\n  if (value instanceof Date) return value.toISOString();\n  return value;\n}\n\nfunction maybeNumericEqual(a: unknown, b: unknown): boolean {\n  // a is string-shape, b is number — parse a and compare. Only when the\n  // string looks numeric AND the parse round-trips (no silent NaN pass-\n  // through on non-numeric strings).\n  if (typeof a !== 'string' || typeof b !== 'number') return false;\n  if (a.trim() === '') return false;\n  const parsed = Number(a);\n  if (!Number.isFinite(parsed)) return false;\n  return parsed === b;\n}\n\nfunction deepEqualObject(\n  a: Record<string, unknown>,\n  b: Record<string, unknown>,\n): boolean {\n  if (Array.isArray(a) !== Array.isArray(b)) return false;\n  const aKeys = Object.keys(a);\n  const bKeys = Object.keys(b);\n  if (aKeys.length !== bKeys.length) return false;\n  for (const key of aKeys) {\n    if (!(key in b)) return false;\n    if (!isEqual(a[key], b[key])) return false;\n  }\n  return true;\n}\n"],"mappings":"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","names":["out"]}

package/dist/runtime/subsystems/{sync → integration}/detection-config.schema.d.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 
 /**
- * Sync subsystem — DetectionConfig schema (#226-1)
+ * Integration subsystem — DetectionConfig schema (#226-1)
  *
- * Canonical Zod schema for per-entity sync detection config. The schema is
+ * Canonical Zod schema for per-entity integration detection config. The schema is
  * the single source of truth for filter/mapping shape and is consumed by:
  *
  *   1. Runtime primitives — `PollChangeSource<T>`, `WebhookChangeSource<T>`
@@ -18,7 +18,7 @@ import { z } from 'zod';
  *   - Cursor strategy is a tagged union over the four shapes the three modes
  *     need (`systemModstamp`, `replayId`, `timestamp`, `eventId`). Each
  *     strategy types its cursor internally; the orchestrator persists what
- *     the iterator last yielded (sync skill rule 2).
+ *     the iterator last yielded (integration skill rule 2).
  *   - `mode: 'poll'` may opt into `provenance: 'cdc'` so Stripe-style event
  *     endpoints (mechanically a poll, semantically CDC) reuse the poll
  *     primitive while emitting `Change<T>.source = 'cdc'`. Long-lived

package/dist/runtime/subsystems/{sync → integration}/detection-config.schema.js

@@ -1,4 +1,4 @@
-// runtime/subsystems/sync/detection-config.schema.ts
+// runtime/subsystems/integration/detection-config.schema.ts
 import { z } from "zod";
 var FieldMappingSchema = z.object({
   source: z.string().min(1),

package/dist/runtime/subsystems/integration/detection-config.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../runtime/subsystems/integration/detection-config.schema.ts"],"sourcesContent":["/**\n * Integration subsystem — DetectionConfig schema (#226-1)\n *\n * Canonical Zod schema for per-entity integration detection config. The schema is\n * the single source of truth for filter/mapping shape and is consumed by:\n *\n *   1. Runtime primitives — `PollChangeSource<T>`, `WebhookChangeSource<T>`\n *      (#226-3, #226-4) accept a parsed `DetectionConfig` at construction.\n *   2. Codegen — `src/schema/entity-definition.schema.ts` (#226-6) imports\n *      this schema so per-entity YAML `detection:` blocks validate against\n *      the same shape the runtime enforces.\n *\n * Locked decisions (see ADR-033 + decision memo Q1–Q6):\n *   - Filter vocabulary is flat AND of `{ field, op, value }` triples; richer\n *     boolean expressions (OR / NOT / nested) are deferred per epic open Q3.\n *   - Cursor strategy is a tagged union over the four shapes the three modes\n *     need (`systemModstamp`, `replayId`, `timestamp`, `eventId`). Each\n *     strategy types its cursor internally; the orchestrator persists what\n *     the iterator last yielded (integration skill rule 2).\n *   - `mode: 'poll'` may opt into `provenance: 'cdc'` so Stripe-style event\n *     endpoints (mechanically a poll, semantically CDC) reuse the poll\n *     primitive while emitting `Change<T>.source = 'cdc'`. Long-lived\n *     streaming CDC (SFDC Pub-Sub, Debezium) is a separate primitive\n *     deferred to #226-8.\n *   - `webhook` mode requires `eventIdField` so `WebhookChangeSource<T>`\n *     can populate `Change<T>.dedupKey` from the inbound staging row.\n */\nimport { z } from 'zod';\n\n// ============================================================================\n// Field mapping — provider field → canonical target\n// ============================================================================\n\n/**\n * Maps a single provider field onto the canonical record. `transform` is an\n * opt-in tag the adapter callback may inspect (`date-iso`, `decimal-string`,\n * etc.); the schema does not enumerate transforms — adapters interpret them.\n */\nexport const FieldMappingSchema = z.object({\n  source: z.string().min(1),\n  target: z.string().min(1),\n  transform: z.string().min(1).optional(),\n});\n\nexport type FieldMapping = z.infer<typeof FieldMappingSchema>;\n\n// ============================================================================\n// Resolved filter — flat-AND triple\n// ============================================================================\n\n/**\n * A single resolved filter clause applied at fetch time. `value` is `unknown`\n * to admit primitives, arrays (for `in` / `nin`), and dates as ISO strings —\n * adapters interpret per provider.\n */\nexport const ResolvedFilterSchema = z.object({\n  field: z.string().min(1),\n  op: z.enum(['eq', 'neq', 'in', 'nin', 'gt', 'gte', 'lt', 'lte']),\n  value: z.unknown(),\n});\n\nexport type ResolvedFilter = z.infer<typeof ResolvedFilterSchema>;\n\n// ============================================================================\n// Cursor strategy — tagged union over the four shapes the modes need\n// ============================================================================\n\nconst SystemModstampCursorSchema = z.object({\n  kind: z.literal('systemModstamp'),\n  field: z.string().min(1),\n});\n\nconst ReplayIdCursorSchema = z.object({\n  kind: z.literal('replayId'),\n  field: z.string().min(1),\n});\n\nconst TimestampCursorSchema = z.object({\n  kind: z.literal('timestamp'),\n  field: z.string().min(1),\n});\n\nconst EventIdCursorSchema = z.object({\n  kind: z.literal('eventId'),\n  field: z.string().min(1),\n});\n\nexport const CursorStrategySchema = z.discriminatedUnion('kind', [\n  SystemModstampCursorSchema,\n  ReplayIdCursorSchema,\n  TimestampCursorSchema,\n  EventIdCursorSchema,\n]);\n\nexport type CursorStrategy = z.infer<typeof CursorStrategySchema>;\n\n// ============================================================================\n// Mode-specific blocks\n// ============================================================================\n\n/**\n * Poll-mode block. `provenance: 'cdc'` opts the poll primitive into stamping\n * `Change<T>.source = 'cdc'` and populating `dedupKey` from the cursor's\n * `field` — used for Stripe-style event endpoints. Defaults to `'poll'`.\n */\nexport const PollDetectionSchema = z.object({\n  cursor: CursorStrategySchema,\n  provenance: z.enum(['poll', 'cdc']).optional(),\n});\n\nexport type PollDetection = z.infer<typeof PollDetectionSchema>;\n\n/**\n * Webhook-mode block. `eventIdField` names the column in the consumer-owned\n * inbound staging row that `WebhookChangeSource<T>` reads to set\n * `Change<T>.dedupKey`.\n */\nexport const WebhookDetectionSchema = z.object({\n  eventIdField: z.string().min(1),\n});\n\nexport type WebhookDetection = z.infer<typeof WebhookDetectionSchema>;\n\n// ============================================================================\n// DetectionConfig — top-level discriminated union over `mode`\n// ============================================================================\n\nconst PollModeSchema = z.object({\n  mode: z.literal('poll'),\n  poll: PollDetectionSchema,\n  mapping: z.array(FieldMappingSchema).min(1),\n  filters: z.array(ResolvedFilterSchema).default([]),\n});\n\nconst WebhookModeSchema = z.object({\n  mode: z.literal('webhook'),\n  webhook: WebhookDetectionSchema,\n  mapping: z.array(FieldMappingSchema).min(1),\n  filters: z.array(ResolvedFilterSchema).default([]),\n});\n\n/**\n * Top-level detection config. Discriminated on `mode` so the relevant\n * mode-block (poll/webhook) is structurally required for that mode. CDC as a\n * long-lived streaming primitive is deferred (#226-8); CDC-as-provenance\n * (Stripe-style event endpoints) is expressed via `mode: 'poll'` with\n * `poll.provenance: 'cdc'`.\n */\nexport const DetectionConfigSchema = z.discriminatedUnion('mode', [\n  PollModeSchema,\n  WebhookModeSchema,\n]);\n\nexport type DetectionConfig = z.infer<typeof DetectionConfigSchema>;\n"],"mappings":";AA2BA,SAAS,SAAS;AAWX,IAAM,qBAAqB,EAAE,OAAO;AAAA,EACzC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACxB,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACxB,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;AACxC,CAAC;AAaM,IAAM,uBAAuB,EAAE,OAAO;AAAA,EAC3C,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACvB,IAAI,EAAE,KAAK,CAAC,MAAM,OAAO,MAAM,OAAO,MAAM,OAAO,MAAM,KAAK,CAAC;AAAA,EAC/D,OAAO,EAAE,QAAQ;AACnB,CAAC;AAQD,IAAM,6BAA6B,EAAE,OAAO;AAAA,EAC1C,MAAM,EAAE,QAAQ,gBAAgB;AAAA,EAChC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;AACzB,CAAC;AAED,IAAM,uBAAuB,EAAE,OAAO;AAAA,EACpC,MAAM,EAAE,QAAQ,UAAU;AAAA,EAC1B,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;AACzB,CAAC;AAED,IAAM,wBAAwB,EAAE,OAAO;AAAA,EACrC,MAAM,EAAE,QAAQ,WAAW;AAAA,EAC3B,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;AACzB,CAAC;AAED,IAAM,sBAAsB,EAAE,OAAO;AAAA,EACnC,MAAM,EAAE,QAAQ,SAAS;AAAA,EACzB,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;AACzB,CAAC;AAEM,IAAM,uBAAuB,EAAE,mBAAmB,QAAQ;AAAA,EAC/D;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAaM,IAAM,sBAAsB,EAAE,OAAO;AAAA,EAC1C,QAAQ;AAAA,EACR,YAAY,EAAE,KAAK,CAAC,QAAQ,KAAK,CAAC,EAAE,SAAS;AAC/C,CAAC;AASM,IAAM,yBAAyB,EAAE,OAAO;AAAA,EAC7C,cAAc,EAAE,OAAO,EAAE,IAAI,CAAC;AAChC,CAAC;AAQD,IAAM,iBAAiB,EAAE,OAAO;AAAA,EAC9B,MAAM,EAAE,QAAQ,MAAM;AAAA,EACtB,MAAM;AAAA,EACN,SAAS,EAAE,MAAM,kBAAkB,EAAE,IAAI,CAAC;AAAA,EAC1C,SAAS,EAAE,MAAM,oBAAoB,EAAE,QAAQ,CAAC,CAAC;AACnD,CAAC;AAED,IAAM,oBAAoB,EAAE,OAAO;AAAA,EACjC,MAAM,EAAE,QAAQ,SAAS;AAAA,EACzB,SAAS;AAAA,EACT,SAAS,EAAE,MAAM,kBAAkB,EAAE,IAAI,CAAC;AAAA,EAC1C,SAAS,EAAE,MAAM,oBAAoB,EAAE,QAAQ,CAAC,CAAC;AACnD,CAAC;AASM,IAAM,wBAAwB,EAAE,mBAAmB,QAAQ;AAAA,EAChE;AAAA,EACA;AACF,CAAC;","names":[]}

package/dist/runtime/subsystems/{sync/execute-sync.use-case.d.ts → integration/execute-integration.use-case.d.ts}

@@ -1,11 +1,11 @@
-import { IChangeSource } from './sync-change-source.protocol.js';
-import { ICursorStore } from './sync-cursor-store.protocol.js';
-import { IFieldDiffer } from './sync-field-diff.protocol.js';
-import { ISyncSink } from './sync-sink.protocol.js';
-import { ISyncRunRecorder } from './sync-run-recorder.protocol.js';
+import { IChangeSource } from './integration-change-source.protocol.js';
+import { ICursorStore } from './integration-cursor-store.protocol.js';
+import { IFieldDiffer } from './integration-field-diff.protocol.js';
+import { IIntegrationSink } from './integration-sink.protocol.js';
+import { IIntegrationRunRecorder } from './integration-run-recorder.protocol.js';
 import 'zod';
 
-interface ExecuteSyncInput<T> {
+interface ExecuteIntegrationInput<T> {
     /** The subscription whose cursor/identity frames this run. */
     readonly subscription: {
         readonly id: string;
@@ -18,18 +18,18 @@ interface ExecuteSyncInput<T> {
     readonly provider: string;
     /** Run direction — almost always `'inbound'`. Reserved for writeback. */
     readonly direction: 'inbound' | 'outbound';
-    /** Detection mode — maps 1:1 to `sync_runs.action`. */
+    /** Detection mode — maps 1:1 to `integration_runs.action`. */
     readonly action: 'poll' | 'cdc' | 'webhook' | 'manual' | 'writeback';
     /** Multi-tenant deployments pass the tenant id through. */
     readonly tenantId?: string | null;
     /**
      * Optional override — inject a specific change source for this run when
      * the DI-bound source is not the one to use (e.g. manual backfill with
-     * a custom cursor). Defaults to the DI-resolved `SYNC_CHANGE_SOURCE`.
+     * a custom cursor). Defaults to the DI-resolved `INTEGRATION_CHANGE_SOURCE`.
      */
     readonly sourceOverride?: IChangeSource<T>;
 }
-interface ExecuteSyncResult {
+interface ExecuteIntegrationResult {
     readonly runId: string;
     readonly status: 'success' | 'no_changes' | 'failed';
     readonly recordsFound: number;
@@ -40,7 +40,7 @@ interface ExecuteSyncResult {
     readonly durationMs: number;
     readonly error?: string | null;
 }
-declare class ExecuteSyncUseCase<T extends Record<string, unknown>> {
+declare class ExecuteIntegrationUseCase<T extends Record<string, unknown>> {
     private readonly source;
     private readonly cursors;
     private readonly differ;
@@ -48,9 +48,9 @@ declare class ExecuteSyncUseCase<T extends Record<string, unknown>> {
     private readonly recorder;
     private readonly multiTenant;
     private readonly logger;
-    constructor(source: IChangeSource<T>, cursors: ICursorStore, differ: IFieldDiffer<T>, sink: ISyncSink<T>, recorder: ISyncRunRecorder, multiTenant?: boolean);
-    execute(input: ExecuteSyncInput<T>): Promise<ExecuteSyncResult>;
+    constructor(source: IChangeSource<T>, cursors: ICursorStore, differ: IFieldDiffer<T>, sink: IIntegrationSink<T>, recorder: IIntegrationRunRecorder, multiTenant?: boolean);
+    execute(input: ExecuteIntegrationInput<T>): Promise<ExecuteIntegrationResult>;
     private processChange;
 }
 
-export { type ExecuteSyncInput, type ExecuteSyncResult, ExecuteSyncUseCase };
+export { type ExecuteIntegrationInput, type ExecuteIntegrationResult, ExecuteIntegrationUseCase };

package/dist/runtime/subsystems/{sync/execute-sync.use-case.js → integration/execute-integration.use-case.js}

@@ -10,15 +10,15 @@ var __decorateClass = (decorators, target, key, kind) => {
 };
 var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
 
-// runtime/subsystems/sync/execute-sync.use-case.ts
+// runtime/subsystems/integration/execute-integration.use-case.ts
 import { Inject, Injectable, Logger, Optional } from "@nestjs/common";
 
-// runtime/subsystems/sync/sync-errors.ts
+// runtime/subsystems/integration/integration-errors.ts
 var MissingTenantIdError = class extends Error {
   name = "MissingTenantIdError";
   constructor(operation) {
     super(
-      `Missing tenantId for sync operation '${operation}'. SyncModule is configured with multiTenant: true \u2014 every call must include a non-null tenantId. Either pass the tenantId or disable multi-tenancy on the module.`
+      `Missing tenantId for integration operation '${operation}'. IntegrationModule is configured with multiTenant: true \u2014 every call must include a non-null tenantId. Either pass the tenantId or disable multi-tenancy on the module.`
     );
   }
 };
@@ -29,16 +29,16 @@ function assertTenantId(tenantId, options) {
   }
 }
 
-// runtime/subsystems/sync/sync.tokens.ts
-var SYNC_CHANGE_SOURCE = "SYNC_CHANGE_SOURCE";
-var SYNC_CURSOR_STORE = "SYNC_CURSOR_STORE";
-var SYNC_FIELD_DIFFER = "SYNC_FIELD_DIFFER";
-var SYNC_SINK = "SYNC_SINK";
-var SYNC_RUN_RECORDER = "SYNC_RUN_RECORDER";
-var SYNC_MULTI_TENANT = "SYNC_MULTI_TENANT";
+// runtime/subsystems/integration/integration.tokens.ts
+var INTEGRATION_CHANGE_SOURCE = "INTEGRATION_CHANGE_SOURCE";
+var INTEGRATION_CURSOR_STORE = "INTEGRATION_CURSOR_STORE";
+var INTEGRATION_FIELD_DIFFER = "INTEGRATION_FIELD_DIFFER";
+var INTEGRATION_SINK = "INTEGRATION_SINK";
+var INTEGRATION_RUN_RECORDER = "INTEGRATION_RUN_RECORDER";
+var INTEGRATION_MULTI_TENANT = "INTEGRATION_MULTI_TENANT";
 
-// runtime/subsystems/sync/execute-sync.use-case.ts
-var ExecuteSyncUseCase = class {
+// runtime/subsystems/integration/execute-integration.use-case.ts
+var ExecuteIntegrationUseCase = class {
   constructor(source, cursors, differ, sink, recorder, multiTenant = false) {
     this.source = source;
     this.cursors = cursors;
@@ -53,7 +53,7 @@ var ExecuteSyncUseCase = class {
   sink;
   recorder;
   multiTenant;
-  logger = new Logger(ExecuteSyncUseCase.name);
+  logger = new Logger(ExecuteIntegrationUseCase.name);
   async execute(input) {
     assertTenantId(input.tenantId, {
       multiTenant: this.multiTenant,
@@ -88,10 +88,10 @@ var ExecuteSyncUseCase = class {
           recordsFailed++;
           const message = err instanceof Error ? err.message : String(err);
           this.logger.warn(
-            `sync item failed: subscription=${input.subscription.id} externalId=${change.externalId}: ${message}`
+            `integration item failed: subscription=${input.subscription.id} externalId=${change.externalId}: ${message}`
           );
           await this.recorder.recordItem({
-            syncRunId: runId,
+            integrationRunId: runId,
             entityType: input.subscription.domain,
             externalId: change.externalId,
             operation: change.operation === "deleted" ? "deleted" : "updated",
@@ -114,7 +114,7 @@ var ExecuteSyncUseCase = class {
       status = "failed";
       runError = err instanceof Error ? err.message : String(err);
       this.logger.error(
-        `sync source failed: subscription=${input.subscription.id}: ${runError}`
+        `integration source failed: subscription=${input.subscription.id}: ${runError}`
       );
     }
     if (cursorAdvanced && latestCursor !== null && latestCursor !== void 0) {
@@ -159,7 +159,7 @@ var ExecuteSyncUseCase = class {
         change.externalId
       );
       await this.recorder.recordItem({
-        syncRunId: runId,
+        integrationRunId: runId,
         entityType: input.subscription.domain,
         externalId: change.externalId,
         localId: result?.id ?? null,
@@ -182,7 +182,7 @@ var ExecuteSyncUseCase = class {
     if (diff === "noop") {
       if (!this.sink.reprojectsOnNoop) {
         await this.recorder.recordItem({
-          syncRunId: runId,
+          integrationRunId: runId,
           entityType: input.subscription.domain,
           externalId: change.externalId,
           localId: null,
@@ -199,7 +199,7 @@ var ExecuteSyncUseCase = class {
         input.provider
       );
       await this.recorder.recordItem({
-        syncRunId: runId,
+        integrationRunId: runId,
         entityType: input.subscription.domain,
         externalId: change.externalId,
         localId: noopLocalId,
@@ -216,7 +216,7 @@ var ExecuteSyncUseCase = class {
       input.provider
     );
     await this.recorder.recordItem({
-      syncRunId: runId,
+      integrationRunId: runId,
       entityType: input.subscription.domain,
       externalId: change.externalId,
       localId,
@@ -227,17 +227,17 @@ var ExecuteSyncUseCase = class {
     });
   }
 };
-ExecuteSyncUseCase = __decorateClass([
+ExecuteIntegrationUseCase = __decorateClass([
   Injectable(),
-  __decorateParam(0, Inject(SYNC_CHANGE_SOURCE)),
-  __decorateParam(1, Inject(SYNC_CURSOR_STORE)),
-  __decorateParam(2, Inject(SYNC_FIELD_DIFFER)),
-  __decorateParam(3, Inject(SYNC_SINK)),
-  __decorateParam(4, Inject(SYNC_RUN_RECORDER)),
+  __decorateParam(0, Inject(INTEGRATION_CHANGE_SOURCE)),
+  __decorateParam(1, Inject(INTEGRATION_CURSOR_STORE)),
+  __decorateParam(2, Inject(INTEGRATION_FIELD_DIFFER)),
+  __decorateParam(3, Inject(INTEGRATION_SINK)),
+  __decorateParam(4, Inject(INTEGRATION_RUN_RECORDER)),
   __decorateParam(5, Optional()),
-  __decorateParam(5, Inject(SYNC_MULTI_TENANT))
-], ExecuteSyncUseCase);
+  __decorateParam(5, Inject(INTEGRATION_MULTI_TENANT))
+], ExecuteIntegrationUseCase);
 export {
-  ExecuteSyncUseCase
+  ExecuteIntegrationUseCase
 };
-//# sourceMappingURL=execute-sync.use-case.js.map
+//# sourceMappingURL=execute-integration.use-case.js.map

package/dist/runtime/subsystems/integration/execute-integration.use-case.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../runtime/subsystems/integration/execute-integration.use-case.ts","../../../../runtime/subsystems/integration/integration-errors.ts","../../../../runtime/subsystems/integration/integration.tokens.ts"],"sourcesContent":["/**\n * ExecuteIntegrationUseCase — the generic integration orchestrator (SYNC-5).\n *\n * One class. Reused across every `(provider, detection-mode, canonical-entity)`\n * tuple. Parameterized over `T` so canonical records stay typed end-to-end.\n *\n * Flow per run:\n *\n *   1. `recorder.startRun(...)` — opens a `integration_runs` row in 'running'.\n *   2. for each change yielded by `source.listChanges(subscription, cursorBefore)`:\n *        a. differ.diff(existing, incoming) → 'noop' short-circuits to\n *           a noop audit row (no sink write).\n *        b. sink.upsertByExternalId / softDeleteByExternalId → records\n *           the local id on the audit row.\n *        c. per-item try/catch — a failed item increments the failed\n *           counter and records `status: 'failed'` with `error`, but\n *           does NOT abort the run.\n *        d. advance `latestCursor = change.cursor` as the iterator moves.\n *   3. `cursors.put(subscription.id, latestCursor)` when the loop completes\n *      AND at least one cursor advance happened. On exceptions from the\n *      source iterator (auth expiry, network error), we persist the\n *      last-good cursor so the next run resumes from the last known\n *      successful position.\n *   4. `finally { recorder.completeRun(...) }` — always terminates the run.\n *\n * Loopback suppression — when a consumer's writes echo back on the next\n * inbound poll/CDC/webhook — is composed into the source's middleware\n * chain via `createLoopbackMiddleware(store)` (#226-5 / ADR-033). The\n * orchestrator no longer special-cases echoes: middleware drops them\n * before they reach this loop. Consumers that don't have outbound\n * writeback paths simply omit the middleware.\n *\n * ## Generics\n *\n * - `T` = canonical record shape from the adapter side. Same `T` flows\n *   through `IChangeSource<T>`, `IFieldDiffer<T>`, `IIntegrationSink<T>`.\n *\n * ## No CRM bleed\n *\n * Per the SYNC-5 issue's extraction notes (HS-9 finding), this orchestrator\n * is strictly provider-agnostic:\n *   - `entityType` is `string` throughout; no `'opportunity' | 'account' | ...`\n *     narrowing leaks into the use case\n *   - the upstream consumer's `IntegrationRunRecorderService` class injection replaced with the\n *     `IIntegrationRunRecorder` protocol (backend lands in SYNC-4)\n */\nimport { Inject, Injectable, Logger, Optional } from '@nestjs/common';\nimport type { IChangeSource, Change } from './integration-change-source.protocol';\nimport type { ICursorStore } from './integration-cursor-store.protocol';\nimport type { IFieldDiffer, FieldDiff } from './integration-field-diff.protocol';\nimport type { IIntegrationSink } from './integration-sink.protocol';\nimport type { IIntegrationRunRecorder } from './integration-run-recorder.protocol';\nimport { assertTenantId } from './integration-errors';\nimport {\n  INTEGRATION_CHANGE_SOURCE,\n  INTEGRATION_CURSOR_STORE,\n  INTEGRATION_FIELD_DIFFER,\n  INTEGRATION_MULTI_TENANT,\n  INTEGRATION_RUN_RECORDER,\n  INTEGRATION_SINK,\n} from './integration.tokens';\n\n// ============================================================================\n// Inputs + result\n// ============================================================================\n\nexport interface ExecuteIntegrationInput<T> {\n  /** The subscription whose cursor/identity frames this run. */\n  readonly subscription: {\n    readonly id: string;\n    readonly domain: string; // entityType — used on audit rows\n    readonly externalRef?: string | null;\n  };\n  /** Per-run user context; threaded through sink writes. */\n  readonly userId: string;\n  /** Provider label persisted on saved rows, e.g. `'salesforce-crm'`. */\n  readonly provider: string;\n  /** Run direction — almost always `'inbound'`. Reserved for writeback. */\n  readonly direction: 'inbound' | 'outbound';\n  /** Detection mode — maps 1:1 to `integration_runs.action`. */\n  readonly action: 'poll' | 'cdc' | 'webhook' | 'manual' | 'writeback';\n  /** Multi-tenant deployments pass the tenant id through. */\n  readonly tenantId?: string | null;\n  /**\n   * Optional override — inject a specific change source for this run when\n   * the DI-bound source is not the one to use (e.g. manual backfill with\n   * a custom cursor). Defaults to the DI-resolved `INTEGRATION_CHANGE_SOURCE`.\n   */\n  readonly sourceOverride?: IChangeSource<T>;\n}\n\nexport interface ExecuteIntegrationResult {\n  readonly runId: string;\n  readonly status: 'success' | 'no_changes' | 'failed';\n  readonly recordsFound: number;\n  readonly recordsProcessed: number;\n  readonly recordsFailed: number;\n  readonly cursorBefore: unknown | null;\n  readonly cursorAfter: unknown | null;\n  readonly durationMs: number;\n  readonly error?: string | null;\n}\n\n// ============================================================================\n// ExecuteIntegrationUseCase\n// ============================================================================\n\n@Injectable()\nexport class ExecuteIntegrationUseCase<T extends Record<string, unknown>> {\n  private readonly logger = new Logger(ExecuteIntegrationUseCase.name);\n\n  constructor(\n    @Inject(INTEGRATION_CHANGE_SOURCE) private readonly source: IChangeSource<T>,\n    @Inject(INTEGRATION_CURSOR_STORE) private readonly cursors: ICursorStore,\n    @Inject(INTEGRATION_FIELD_DIFFER) private readonly differ: IFieldDiffer<T>,\n    @Inject(INTEGRATION_SINK) private readonly sink: IIntegrationSink<T>,\n    @Inject(INTEGRATION_RUN_RECORDER) private readonly recorder: IIntegrationRunRecorder,\n    @Optional()\n    @Inject(INTEGRATION_MULTI_TENANT)\n    private readonly multiTenant: boolean = false,\n  ) {}\n\n  async execute(input: ExecuteIntegrationInput<T>): Promise<ExecuteIntegrationResult> {\n    // Defense-in-depth tenancy guard — fire BEFORE startRun so a rejected\n    // input never leaves a dangling `status=running` row. Backends also\n    // enforce (SYNC-4), but failing fast at the orchestrator boundary is\n    // cheaper for observability, metrics, and manual cleanup.\n    assertTenantId(input.tenantId, {\n      multiTenant: this.multiTenant,\n      operation: 'execute',\n    });\n\n    const source = input.sourceOverride ?? this.source;\n    const startedAt = Date.now();\n    const cursorBefore = await this.cursors.get(input.subscription.id, input.tenantId);\n\n    const { id: runId } = await this.recorder.startRun({\n      subscriptionId: input.subscription.id,\n      direction: input.direction,\n      action: input.action,\n      cursorBefore,\n      tenantId: input.tenantId,\n    });\n\n    let recordsFound = 0;\n    let recordsProcessed = 0;\n    let recordsFailed = 0;\n    let latestCursor: unknown | null = cursorBefore;\n    let cursorAdvanced = false;\n    let runError: string | null = null;\n    let status: 'success' | 'no_changes' | 'failed' = 'no_changes';\n\n    try {\n      for await (const change of source.listChanges(input.subscription, cursorBefore)) {\n        recordsFound++;\n        latestCursor = change.cursor;\n        cursorAdvanced = true;\n\n        try {\n          await this.processChange(runId, input, change);\n          recordsProcessed++;\n        } catch (err) {\n          recordsFailed++;\n          const message = err instanceof Error ? err.message : String(err);\n          this.logger.warn(\n            `integration item failed: subscription=${input.subscription.id} externalId=${change.externalId}: ${message}`,\n          );\n          await this.recorder.recordItem({\n            integrationRunId: runId,\n            entityType: input.subscription.domain,\n            externalId: change.externalId,\n            operation: change.operation === 'deleted' ? 'deleted' : 'updated',\n            status: 'failed',\n            changedFields: {},\n            error: message,\n            tenantId: input.tenantId,\n          });\n        }\n      }\n\n      if (recordsFailed > 0 && recordsProcessed === 0 && recordsFound > 0) {\n        // Every record we saw failed — call the run a failure, not a\n        // success. Partial success (some processed, some failed) still\n        // counts as 'success' so the cursor advances.\n        status = 'failed';\n        runError = `all ${recordsFailed} records failed`;\n      } else if (recordsFound === 0) {\n        status = 'no_changes';\n      } else {\n        status = 'success';\n      }\n    } catch (err) {\n      // Source iterator itself threw — cursor DOES NOT advance past the\n      // last-successful cursor. `latestCursor` still holds the last\n      // `change.cursor` we observed, which is the furthest we know to\n      // have delivered. Persist it (below) so next run resumes there.\n      status = 'failed';\n      runError = err instanceof Error ? err.message : String(err);\n      this.logger.error(\n        `integration source failed: subscription=${input.subscription.id}: ${runError}`,\n      );\n    }\n\n    // Persist cursor advance only when something actually moved. Never\n    // overwrite a valid cursor with `null` on a no-change run.\n    if (cursorAdvanced && latestCursor !== null && latestCursor !== undefined) {\n      try {\n        await this.cursors.put(input.subscription.id, latestCursor, input.tenantId);\n      } catch (err) {\n        const message = err instanceof Error ? err.message : String(err);\n        this.logger.error(\n          `cursor put failed: subscription=${input.subscription.id}: ${message}`,\n        );\n        if (status !== 'failed') {\n          status = 'failed';\n          runError = `cursor put failed: ${message}`;\n        }\n      }\n    }\n\n    const durationMs = Date.now() - startedAt;\n\n    await this.recorder.completeRun(runId, {\n      status,\n      recordsFound,\n      recordsProcessed,\n      cursorAfter: cursorAdvanced ? latestCursor : cursorBefore,\n      durationMs,\n      error: runError,\n    });\n\n    return {\n      runId,\n      status,\n      recordsFound,\n      recordsProcessed,\n      recordsFailed,\n      cursorBefore,\n      cursorAfter: cursorAdvanced ? latestCursor : cursorBefore,\n      durationMs,\n      error: runError,\n    };\n  }\n\n  private async processChange(\n    runId: string,\n    input: ExecuteIntegrationInput<T>,\n    change: Change<T>,\n  ): Promise<void> {\n    // Deletion branch — no diff, no upsert; soft-delete via sink.\n    if (change.operation === 'deleted') {\n      const result = await this.sink.softDeleteByExternalId(\n        input.userId,\n        change.externalId,\n      );\n      await this.recorder.recordItem({\n        integrationRunId: runId,\n        entityType: input.subscription.domain,\n        externalId: change.externalId,\n        localId: result?.id ?? null,\n        operation: result ? 'deleted' : 'noop',\n        status: 'success',\n        changedFields: {},\n        tenantId: input.tenantId,\n      });\n      return;\n    }\n\n    // Create/update path — diff against local state, short-circuit on noop.\n    const existing = await this.sink.findByExternalId(\n      input.userId,\n      change.externalId,\n    );\n    const diff = this.differ.diff(\n      existing,\n      change.record,\n      change.providerChangedFields,\n    );\n\n    if (diff === 'noop') {\n      // Sinks that declare `reprojectsOnNoop` reproject side data the differ\n      // can't see (e.g. EAV field_values) — so fall through to the idempotent\n      // upsert instead of short-circuiting. The canonical state is unchanged,\n      // so the audit `operation` stays `'noop'`, but we capture the local id\n      // returned by the upsert. Sinks without the flag keep today's behavior.\n      if (!this.sink.reprojectsOnNoop) {\n        await this.recorder.recordItem({\n          integrationRunId: runId,\n          entityType: input.subscription.domain,\n          externalId: change.externalId,\n          localId: null,\n          operation: 'noop',\n          status: 'success',\n          changedFields: {},\n          tenantId: input.tenantId,\n        });\n        return;\n      }\n\n      const { id: noopLocalId } = await this.sink.upsertByExternalId(\n        input.userId,\n        change.record,\n        input.provider,\n      );\n      await this.recorder.recordItem({\n        integrationRunId: runId,\n        entityType: input.subscription.domain,\n        externalId: change.externalId,\n        localId: noopLocalId,\n        operation: 'noop',\n        status: 'success',\n        changedFields: {},\n        tenantId: input.tenantId,\n      });\n      return;\n    }\n\n    const { id: localId } = await this.sink.upsertByExternalId(\n      input.userId,\n      change.record,\n      input.provider,\n    );\n\n    await this.recorder.recordItem({\n      integrationRunId: runId,\n      entityType: input.subscription.domain,\n      externalId: change.externalId,\n      localId,\n      operation: existing === null ? 'created' : 'updated',\n      status: 'success',\n      changedFields: diff as FieldDiff,\n      tenantId: input.tenantId,\n    });\n  }\n}\n","/**\n * Typed errors + shared boundary helpers for the integration subsystem.\n *\n * Classes (not bare Error) so consumers can `instanceof` them in catch\n * blocks and exception filters can map them to HTTP codes.\n *\n * Mirrors the shape of `events-errors.ts` and `jobs-errors.ts`.\n */\n\n/**\n * Thrown by the Drizzle cursor-store / run-recorder backends AND by the\n * orchestrator entry point when `INTEGRATION_MULTI_TENANT` is enabled but the\n * caller did not supply a non-null `tenantId`. Strict enforcement at the\n * boundary — explicit `null` still throws.\n *\n * Disable multi-tenancy on the module (`multiTenant: false`, the default)\n * to opt out of the requirement entirely.\n *\n * `operation` identifies the call site (e.g. `'cursor.put'`,\n * `'startRun'`, `'execute'`) so the stack-trace message points at the\n * specific boundary that rejected the input.\n */\nexport class MissingTenantIdError extends Error {\n  override readonly name = 'MissingTenantIdError';\n  constructor(operation: string) {\n    super(\n      `Missing tenantId for integration operation '${operation}'. IntegrationModule is ` +\n        `configured with multiTenant: true — every call must include a ` +\n        `non-null tenantId. Either pass the tenantId or disable multi-` +\n        `tenancy on the module.`,\n    );\n  }\n}\n\n/**\n * Shared boundary guard — used at the orchestrator entry AND inside the\n * Drizzle backends. Keeping the check in one function guarantees every\n * `MissingTenantIdError` carries the same message shape regardless of the\n * site that raised it, which makes it easier for consumers to pattern-\n * match on the error in logs/metrics.\n *\n * When `multiTenant` is false, the function is a no-op — `tenantId` may\n * be anything (including `undefined`). When true, `undefined` or `null`\n * throws.\n */\nexport function assertTenantId(\n  tenantId: string | null | undefined,\n  options: { multiTenant: boolean; operation: string },\n): asserts tenantId is string {\n  if (!options.multiTenant) return;\n  if (tenantId === undefined || tenantId === null) {\n    throw new MissingTenantIdError(options.operation);\n  }\n}\n","/**\n * Integration subsystem — DI tokens\n *\n * String constants (not Symbols) so they match by value across import\n * boundaries — same convention as the events subsystem (`EVENT_BUS`). The\n * jobs subsystem uses Symbols for its analogous tokens; events and integration\n * stay internally consistent with strings.\n *\n * Usage in use cases:\n * ```ts\n * constructor(\n *   @Inject(INTEGRATION_CHANGE_SOURCE) private readonly source: IChangeSource<CanonicalOpportunity>,\n *   @Inject(INTEGRATION_CURSOR_STORE)  private readonly cursors: ICursorStore,\n *   @Inject(INTEGRATION_FIELD_DIFFER)  private readonly differ: IFieldDiffer<CanonicalOpportunity>,\n *   @Inject(INTEGRATION_SINK)          private readonly sink: IIntegrationSink<CanonicalOpportunity>,\n *   @Inject(INTEGRATION_RUN_RECORDER)  private readonly recorder: IIntegrationRunRecorder,\n * ) {}\n * ```\n *\n * Concrete bindings are registered by `IntegrationModule.forRoot(...)` (SYNC-6).\n */\n\nexport const INTEGRATION_CHANGE_SOURCE = 'INTEGRATION_CHANGE_SOURCE' as const;\nexport const INTEGRATION_CURSOR_STORE = 'INTEGRATION_CURSOR_STORE' as const;\nexport const INTEGRATION_FIELD_DIFFER = 'INTEGRATION_FIELD_DIFFER' as const;\nexport const INTEGRATION_SINK = 'INTEGRATION_SINK' as const;\n\n/**\n * Run-recorder token (SYNC-5). Backed by `IIntegrationRunRecorder`. Drizzle impl\n * lands in SYNC-4; tests provide inline fakes.\n */\nexport const INTEGRATION_RUN_RECORDER = 'INTEGRATION_RUN_RECORDER' as const;\n\n/**\n * Injection token for the resolved `IntegrationModuleOptions` object (SYNC-6).\n *\n * Backends that need to observe module configuration (e.g. `multiTenant`\n * flag, pool filters) inject via this token. Provided automatically by\n * `IntegrationModule.forRoot(...)` / `IntegrationModule.forRootAsync(...)`.\n */\nexport const INTEGRATION_MODULE_OPTIONS = 'INTEGRATION_MODULE_OPTIONS' as const;\n\n/**\n * Injection token for the resolved multi-tenancy flag (SYNC-6).\n *\n * Provided by `IntegrationModule.forRoot(...)` as `options.multiTenant ?? false`.\n * Consumed by `ExecuteIntegrationUseCase` to enforce the tenantId-is-required rule.\n */\nexport const INTEGRATION_MULTI_TENANT = 'INTEGRATION_MULTI_TENANT' as const;\n"],"mappings":"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","names":[]}

package/dist/runtime/subsystems/integration/index.d.ts

@@ -0,0 +1,28 @@
+export { Change, ChangeSource, IChangeSource, IntegrationSubscriptionView } from './integration-change-source.protocol.js';
+export { CursorSnapshot, ICursorStore } from './integration-cursor-store.protocol.js';
+export { DiffResult, FieldDiff, FieldDiffSchema, FieldDiffValue, FieldDiffValueSchema, IFieldDiffer } from './integration-field-diff.protocol.js';
+export { IIntegrationSink } from './integration-sink.protocol.js';
+export { CompleteRunInput, IIntegrationRunRecorder, IntegrationRunSummary, RecordItemInput, StartRunInput } from './integration-run-recorder.protocol.js';
+export { ILoopbackFingerprintStore } from './integration-loopback.protocol.js';
+export { CursorStrategy, CursorStrategySchema, DetectionConfig, DetectionConfigSchema, FieldMapping, FieldMappingSchema, PollDetection, PollDetectionSchema, ResolvedFilter, ResolvedFilterSchema, WebhookDetection, WebhookDetectionSchema } from './detection-config.schema.js';
+export { ChangeIterator, ChangeMiddleware, ComposeChangeMiddleware } from './integration-middleware.protocol.js';
+export { createLoopbackMiddleware } from './loopback.middleware.js';
+export { PollChangeSource, PollChangeSourceOptions, PollCursor, PollFetchCallback, PollFetchContext } from './poll-change-source.js';
+export { WebhookChangeSource, WebhookChangeSourceOptions, WebhookCursor, WebhookFetchCallback, WebhookFetchContext } from './webhook-change-source.js';
+export { buildChangeSource } from './build-change-source.js';
+export { INTEGRATION_CHANGE_SOURCE, INTEGRATION_CURSOR_STORE, INTEGRATION_FIELD_DIFFER, INTEGRATION_MODULE_OPTIONS, INTEGRATION_MULTI_TENANT, INTEGRATION_RUN_RECORDER, INTEGRATION_SINK } from './integration.tokens.js';
+export { MissingTenantIdError, assertTenantId } from './integration-errors.js';
+export { IntegrationRunItemRow, IntegrationRunRow, IntegrationSubscriptionRow, integrationRunActionEnum, integrationRunDirectionEnum, integrationRunItemOperationEnum, integrationRunItemStatusEnum, integrationRunItems, integrationRunStatusEnum, integrationRuns, integrationSubscriptions } from './integration-audit.schema.js';
+export { MemoryCursorStore } from './integration-cursor-store.memory-backend.js';
+export { MemoryIntegrationSubscription, MemoryRunRecord, MemoryRunRecorder } from './integration-run-recorder.memory-backend.js';
+export { DeepEqualDiffer, DeepEqualDifferOptions } from './deep-equal.differ.js';
+export { ExecuteIntegrationInput, ExecuteIntegrationResult, ExecuteIntegrationUseCase } from './execute-integration.use-case.js';
+export { PostgresCursorStore } from './integration-cursor-store.drizzle-backend.js';
+export { DrizzleIntegrationRunRecorder } from './integration-run-recorder.drizzle-backend.js';
+export { IntegrationModule, IntegrationModuleOptions } from './integration.module.js';
+import 'zod';
+import 'drizzle-orm/pg-core';
+import 'drizzle-orm';
+import '../../types/drizzle.js';
+import 'drizzle-orm/node-postgres';
+import '@nestjs/common';