@pattern-stack/codegen 0.11.0 → 0.12.1

package/dist/runtime/subsystems/index.js

@@ -9,7 +9,7 @@ var __decorateClass = (decorators, target, key, kind) => {
   if (kind && result) __defProp(target, key, result);
   return result;
 };
-var __decorateParam = (index3, decorator) => (target, key) => decorator(target, key, index3);
+var __decorateParam = (index4, decorator) => (target, key) => decorator(target, key, index4);
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
 // runtime/subsystems/events/events.tokens.ts
@@ -4017,16 +4017,22 @@ import { Module as Module6 } from "@nestjs/common";
 import { Inject as Inject13, Injectable as Injectable14, Optional as Optional7 } from "@nestjs/common";
 
 // 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_MODULE_OPTIONS = "INTEGRATION_MODULE_OPTIONS";
+var INTEGRATION_MULTI_TENANT = "INTEGRATION_MULTI_TENANT";
+var ENTITY_CHANGE_SOURCE_REGISTRY = "ENTITY_CHANGE_SOURCE_REGISTRY";
 
 // runtime/subsystems/observability/observability.service.ts
 var MAX_TIMELINE_PAGES = 50;
 var ObservabilityService = class {
-  constructor(jobRuns2, bridge, integrationRuns, cursors, events) {
+  constructor(jobRuns2, bridge, integrationRuns2, cursors, events) {
     this.jobRuns = jobRuns2;
     this.bridge = bridge;
-    this.integrationRuns = integrationRuns;
+    this.integrationRuns = integrationRuns2;
     this.cursors = cursors;
     this.events = events;
   }
@@ -4287,6 +4293,971 @@ var ObservabilityError = class extends Error {
   cause;
 };
 
+// runtime/subsystems/integration/integration-field-diff.protocol.ts
+import { z as z2 } from "zod";
+var FieldDiffValueSchema = z2.object({
+  from: z2.unknown(),
+  to: z2.unknown()
+});
+var FieldDiffSchema = z2.record(z2.string(), FieldDiffValueSchema);
+
+// runtime/subsystems/integration/entity-change-source-registry.protocol.ts
+var UnknownEntityError = class extends Error {
+  constructor(entity, available) {
+    super(
+      `No change source registered for entity '${entity}'. Available: ${available.join(", ")}`
+    );
+    this.name = "UnknownEntityError";
+  }
+};
+
+// 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()];
+  }
+};
+
+// runtime/subsystems/integration/detection-config.schema.ts
+import { z as z3 } from "zod";
+var FieldMappingSchema = z3.object({
+  source: z3.string().min(1),
+  target: z3.string().min(1),
+  transform: z3.string().min(1).optional()
+});
+var ResolvedFilterSchema = z3.object({
+  field: z3.string().min(1),
+  op: z3.enum(["eq", "neq", "in", "nin", "gt", "gte", "lt", "lte"]),
+  value: z3.unknown()
+});
+var SystemModstampCursorSchema = z3.object({
+  kind: z3.literal("systemModstamp"),
+  field: z3.string().min(1)
+});
+var ReplayIdCursorSchema = z3.object({
+  kind: z3.literal("replayId"),
+  field: z3.string().min(1)
+});
+var TimestampCursorSchema = z3.object({
+  kind: z3.literal("timestamp"),
+  field: z3.string().min(1)
+});
+var EventIdCursorSchema = z3.object({
+  kind: z3.literal("eventId"),
+  field: z3.string().min(1)
+});
+var CursorStrategySchema = z3.discriminatedUnion("kind", [
+  SystemModstampCursorSchema,
+  ReplayIdCursorSchema,
+  TimestampCursorSchema,
+  EventIdCursorSchema
+]);
+var PollDetectionSchema = z3.object({
+  cursor: CursorStrategySchema,
+  provenance: z3.enum(["poll", "cdc"]).optional()
+});
+var WebhookDetectionSchema = z3.object({
+  eventIdField: z3.string().min(1)
+});
+var PollModeSchema = z3.object({
+  mode: z3.literal("poll"),
+  poll: PollDetectionSchema,
+  mapping: z3.array(FieldMappingSchema).min(1),
+  filters: z3.array(ResolvedFilterSchema).default([])
+});
+var WebhookModeSchema = z3.object({
+  mode: z3.literal("webhook"),
+  webhook: WebhookDetectionSchema,
+  mapping: z3.array(FieldMappingSchema).min(1),
+  filters: z3.array(ResolvedFilterSchema).default([])
+});
+var DetectionConfigSchema = z3.discriminatedUnion("mode", [
+  PollModeSchema,
+  WebhookModeSchema
+]);
+
+// runtime/subsystems/integration/integration-errors.ts
+var MissingTenantIdError3 = class extends Error {
+  name = "MissingTenantIdError";
+  constructor(operation) {
+    super(
+      `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.`
+    );
+  }
+};
+function assertTenantId(tenantId, options) {
+  if (!options.multiTenant) return;
+  if (tenantId === void 0 || tenantId === null) {
+    throw new MissingTenantIdError3(options.operation);
+  }
+}
+
+// runtime/subsystems/integration/integration-audit.schema.ts
+import {
+  pgEnum as pgEnum2,
+  pgTable as pgTable4,
+  uuid as uuid3,
+  text as text4,
+  jsonb as jsonb4,
+  integer as integer2,
+  boolean,
+  timestamp as timestamp4,
+  index as index3,
+  uniqueIndex as uniqueIndex2
+} from "drizzle-orm/pg-core";
+var integrationRunDirectionEnum = pgEnum2("integration_run_direction", [
+  "inbound",
+  "outbound"
+]);
+var integrationRunActionEnum = pgEnum2("integration_run_action", [
+  "poll",
+  "cdc",
+  "webhook",
+  "manual",
+  "writeback"
+]);
+var integrationRunStatusEnum = pgEnum2("integration_run_status", [
+  "running",
+  "success",
+  "no_changes",
+  "failed"
+]);
+var integrationRunItemOperationEnum = pgEnum2("integration_run_item_operation", [
+  "created",
+  "updated",
+  "deleted",
+  "noop"
+]);
+var integrationRunItemStatusEnum = pgEnum2("integration_run_item_status", [
+  "success",
+  "failed",
+  "skipped"
+]);
+var integrationSubscriptions = pgTable4(
+  "integration_subscriptions",
+  {
+    id: uuid3("id").primaryKey().defaultRandom(),
+    connectionId: text4("connection_id").notNull(),
+    adapter: text4("adapter").notNull(),
+    domain: text4("domain").notNull(),
+    externalRef: text4("external_ref"),
+    enabled: boolean("enabled").notNull().default(true),
+    /**
+     * Per-subscription configuration bag. Strategies type it internally;
+     * e.g. polling strategies stash `{ batchSize, highWatermark }` here.
+     */
+    config: jsonb4("config").notNull().default({}).$type(),
+    /**
+     * Opaque cursor persisted by `ICursorStore.put()`. NULL until the first
+     * successful run advances it.
+     */
+    cursor: jsonb4("cursor").$type(),
+    lastIntegrationAt: timestamp4("last_integration_at", { withTimezone: true }),
+    /** Runtime-enforced when `INTEGRATION_MULTI_TENANT` is true; see SYNC-6. */
+    tenantId: text4("tenant_id"),
+    createdAt: timestamp4("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp4("updated_at", { withTimezone: true }).notNull().defaultNow()
+  },
+  (t) => ({
+    /**
+     * Composite uniqueness per the epic shape. `external_ref` is nullable;
+     * Postgres treats NULLs as distinct in a UNIQUE constraint, which means
+     * two rows with the same `(connection_id, adapter, domain)` and NULL
+     * external_ref are allowed. That's intentional — a subscription with
+     * NULL external_ref covers the full domain, and duplicates there would
+     * be a consumer-layer modeling issue, not a schema concern.
+     */
+    uqIntegrationSubscriptionTuple: uniqueIndex2("uq_integration_subscriptions_tuple").on(
+      t.connectionId,
+      t.adapter,
+      t.domain,
+      t.externalRef
+    ),
+    /** Scheduling query: list enabled subscriptions ordered by staleness. */
+    idxIntegrationSubscriptionsEnabledLastIntegration: index3(
+      "idx_integration_subscriptions_enabled_last_integration"
+    ).on(t.enabled, t.lastIntegrationAt)
+  })
+);
+var integrationRuns = pgTable4(
+  "integration_runs",
+  {
+    id: uuid3("id").primaryKey().defaultRandom(),
+    subscriptionId: uuid3("subscription_id").notNull().references(() => integrationSubscriptions.id, { onDelete: "cascade" }),
+    direction: integrationRunDirectionEnum("direction").notNull(),
+    action: integrationRunActionEnum("action").notNull(),
+    status: integrationRunStatusEnum("status").notNull().default("running"),
+    recordsFound: integer2("records_found").notNull().default(0),
+    recordsProcessed: integer2("records_processed").notNull().default(0),
+    cursorBefore: jsonb4("cursor_before").$type(),
+    cursorAfter: jsonb4("cursor_after").$type(),
+    durationMs: integer2("duration_ms"),
+    error: text4("error"),
+    startedAt: timestamp4("started_at", { withTimezone: true }).notNull().defaultNow(),
+    completedAt: timestamp4("completed_at", { withTimezone: true }),
+    /** Runtime-enforced when `INTEGRATION_MULTI_TENANT` is true; see SYNC-6. */
+    tenantId: text4("tenant_id")
+  },
+  (t) => ({
+    /** Timeline read: "most recent runs for this subscription". */
+    idxIntegrationRunsSubscriptionStartedAt: index3(
+      "idx_integration_runs_subscription_started_at"
+    ).on(t.subscriptionId, t.startedAt),
+    /** Stale-run sweeper: "runs that started > N minutes ago and are still running". */
+    idxIntegrationRunsStatusStartedAt: index3("idx_integration_runs_status_started_at").on(
+      t.status,
+      t.startedAt
+    )
+  })
+);
+var integrationRunItems = pgTable4(
+  "integration_run_items",
+  {
+    id: uuid3("id").primaryKey().defaultRandom(),
+    integrationRunId: uuid3("integration_run_id").notNull().references(() => integrationRuns.id, { onDelete: "cascade" }),
+    entityType: text4("entity_type").notNull(),
+    externalId: text4("external_id").notNull(),
+    localId: text4("local_id"),
+    operation: integrationRunItemOperationEnum("operation").notNull(),
+    status: integrationRunItemStatusEnum("status").notNull(),
+    /**
+     * Structured per-field diff — ADR-0003 shape enforced by
+     * `FieldDiffSchema.parse` at the recorder service layer.
+     *
+     * Shape: `{ [fieldName]: { from: unknown, to: unknown } }`.
+     * Empty `{}` for `noop` items; `{ [field]: { from: null, to: <value> } }`
+     * for created items; `{ [field]: { from: <value>, to: null } }` for
+     * deleted items.
+     */
+    changedFields: jsonb4("changed_fields").notNull().default({}).$type(),
+    title: text4("title"),
+    error: text4("error"),
+    createdAt: timestamp4("created_at", { withTimezone: true }).notNull().defaultNow(),
+    /** Runtime-enforced when `INTEGRATION_MULTI_TENANT` is true; see SYNC-6. */
+    tenantId: text4("tenant_id")
+  },
+  (t) => ({
+    /** Ordered timeline within a run. */
+    idxIntegrationRunItemsRunCreatedAt: index3("idx_integration_run_items_run_created_at").on(
+      t.integrationRunId,
+      t.createdAt
+    ),
+    /** Per-record history: "every integration that touched opportunity/$extId". */
+    idxIntegrationRunItemsEntityExternal: index3(
+      "idx_integration_run_items_entity_external"
+    ).on(t.entityType, t.externalId)
+  })
+);
+
+// runtime/subsystems/integration/integration-cursor-store.memory-backend.ts
+import { Injectable as Injectable16 } from "@nestjs/common";
+var MemoryCursorStore = class {
+  /**
+   * Subscription-id → last persisted cursor. Public so tests can inspect
+   * or pre-seed state; production callers MUST go through `get`/`put`.
+   */
+  cursors = /* @__PURE__ */ new Map();
+  /**
+   * Seedable subscription metadata for `listAll` — the memory backend
+   * stores only `subscriptionId → cursor` in its write path, so the
+   * snapshot shape (`connectionId`, `adapter`, `domain`, `externalRef`,
+   * timestamps) has no natural source without test seeding. Tests populate
+   * this map; unseeded entries get empty-string metadata and `new Date(0)`
+   * timestamps so the shape stays stable. Production paths go through the
+   * Drizzle backend.
+   */
+  subscriptions = /* @__PURE__ */ new Map();
+  async get(subscriptionId, _tenantId) {
+    const value = this.cursors.get(subscriptionId);
+    return value === void 0 ? null : value;
+  }
+  async put(subscriptionId, cursor, _tenantId) {
+    this.cursors.set(subscriptionId, cursor);
+  }
+  async listAll(_tenantId) {
+    const snapshots = [];
+    for (const [subscriptionId, cursor] of this.cursors.entries()) {
+      const meta = this.subscriptions.get(subscriptionId);
+      snapshots.push({
+        subscriptionId,
+        connectionId: meta?.connectionId ?? "",
+        adapter: meta?.adapter ?? "",
+        domain: meta?.domain ?? "",
+        externalRef: meta?.externalRef ?? null,
+        cursor: cursor ?? null,
+        lastIntegrationAt: meta?.lastIntegrationAt ?? null,
+        updatedAt: meta?.updatedAt ?? /* @__PURE__ */ new Date(0),
+        tenantId: null
+      });
+    }
+    return snapshots.sort(
+      (a, b) => b.updatedAt.getTime() - a.updatedAt.getTime()
+    );
+  }
+  /** Reset state. Tests call this in `beforeEach`. */
+  clear() {
+    this.cursors.clear();
+    this.subscriptions.clear();
+  }
+};
+MemoryCursorStore = __decorateClass([
+  Injectable16()
+], MemoryCursorStore);
+
+// runtime/subsystems/integration/integration-run-recorder.memory-backend.ts
+import { Injectable as Injectable17 } from "@nestjs/common";
+var MemoryRunRecorder = class {
+  /**
+   * All started runs keyed by id. Public so tests can inspect lifecycle
+   * transitions without poking through recording methods.
+   */
+  runs = /* @__PURE__ */ new Map();
+  /**
+   * Items keyed by `integration_run_id`, array order matches insertion order —
+   * mirrors the timeline the `(integration_run_id, created_at)` index produces
+   * in Postgres.
+   */
+  items = /* @__PURE__ */ new Map();
+  /**
+   * Seedable subscription metadata — tests populate this to make
+   * `listRecent` return meaningful `connectionId` values. The memory
+   * backend doesn't track subscriptions on its own (only runs + items), so
+   * this map is the intentional extension point: tests write entries for
+   * the subscription ids they use, production code never touches it.
+   */
+  subscriptions = /* @__PURE__ */ new Map();
+  async startRun(input) {
+    const id = crypto.randomUUID();
+    this.runs.set(id, {
+      id,
+      subscriptionId: input.subscriptionId,
+      direction: input.direction,
+      action: input.action,
+      status: "running",
+      cursorBefore: input.cursorBefore ?? null,
+      cursorAfter: null,
+      recordsFound: 0,
+      recordsProcessed: 0,
+      durationMs: null,
+      error: null,
+      tenantId: input.tenantId ?? null,
+      startedAt: /* @__PURE__ */ new Date(),
+      completedAt: null
+    });
+    this.items.set(id, []);
+    return { id };
+  }
+  async recordItem(input) {
+    FieldDiffSchema.parse(input.changedFields);
+    const bucket = this.items.get(input.integrationRunId);
+    if (!bucket) {
+      throw new Error(
+        `MemoryRunRecorder.recordItem: no run started for id '${input.integrationRunId}'. Call startRun(...) first.`
+      );
+    }
+    bucket.push(input);
+  }
+  async completeRun(runId, input) {
+    const run = this.runs.get(runId);
+    if (!run) {
+      throw new Error(
+        `MemoryRunRecorder.completeRun: no run started for id '${runId}'.`
+      );
+    }
+    run.status = input.status;
+    run.recordsFound = input.recordsFound;
+    run.recordsProcessed = input.recordsProcessed;
+    run.cursorAfter = input.cursorAfter ?? null;
+    run.durationMs = input.durationMs;
+    run.error = input.error ?? null;
+    run.completedAt = /* @__PURE__ */ new Date();
+  }
+  async listRecent(limit, subscriptionId, _tenantId) {
+    const all = Array.from(this.runs.values());
+    const filtered = subscriptionId === void 0 ? all : all.filter((r) => r.subscriptionId === subscriptionId);
+    return filtered.sort((a, b) => b.startedAt.getTime() - a.startedAt.getTime()).slice(0, limit).map((r) => ({
+      id: r.id,
+      subscriptionId: r.subscriptionId,
+      // connectionId is only knowable if the test seeded subscriptions
+      // metadata; empty string otherwise. The Drizzle backend resolves
+      // it via JOIN, which is the production path.
+      connectionId: this.subscriptions.get(r.subscriptionId)?.connectionId ?? "",
+      status: r.status,
+      startedAt: r.startedAt,
+      completedAt: r.completedAt,
+      recordsProcessed: r.recordsProcessed,
+      tenantId: r.tenantId
+    }));
+  }
+  /** Reset state. Tests call this in `beforeEach`. */
+  clear() {
+    this.runs.clear();
+    this.items.clear();
+    this.subscriptions.clear();
+  }
+  // ─── test ergonomics ─────────────────────────────────────────────────
+  /** All runs for a subscription, newest first. Timeline reads. */
+  getRunsForSubscription(subscriptionId) {
+    return Array.from(this.runs.values()).filter((r) => r.subscriptionId === subscriptionId).sort((a, b) => b.startedAt.getTime() - a.startedAt.getTime());
+  }
+  /** All item rows for a run, insertion-ordered. */
+  getItemsForRun(runId) {
+    return this.items.get(runId) ?? [];
+  }
+};
+MemoryRunRecorder = __decorateClass([
+  Injectable17()
+], MemoryRunRecorder);
+
+// runtime/subsystems/integration/deep-equal.differ.ts
+import { Injectable as Injectable18 } from "@nestjs/common";
+var DEFAULT_IGNORE_FIELDS = /* @__PURE__ */ new Set([
+  "id",
+  "createdAt",
+  "updatedAt",
+  "deletedAt",
+  "type",
+  "lastModifiedAt",
+  "fields",
+  "external_id",
+  "externalId",
+  "provider",
+  "provider_metadata",
+  "providerMetadata"
+]);
+var DeepEqualDiffer = class {
+  ignore;
+  constructor(opts = {}) {
+    if (opts.ignore && opts.ignore.length > 0) {
+      this.ignore = /* @__PURE__ */ new Set([...DEFAULT_IGNORE_FIELDS, ...opts.ignore]);
+    } else {
+      this.ignore = DEFAULT_IGNORE_FIELDS;
+    }
+  }
+  diff(existing, incoming, providerChangedFields) {
+    if (existing === null) {
+      const out2 = {};
+      for (const key of Object.keys(incoming)) {
+        if (this.ignore.has(key)) continue;
+        const value = incoming[key];
+        if (value === null || value === void 0) continue;
+        out2[key] = { from: null, to: value };
+      }
+      return Object.keys(out2).length === 0 ? "noop" : out2;
+    }
+    const candidates = /* @__PURE__ */ new Set();
+    if (providerChangedFields && providerChangedFields.length > 0) {
+      for (const key of providerChangedFields) {
+        if (!this.ignore.has(key)) candidates.add(key);
+      }
+    } else {
+      for (const key of Object.keys(incoming)) {
+        if (!this.ignore.has(key)) candidates.add(key);
+      }
+      for (const key of Object.keys(existing)) {
+        if (this.ignore.has(key)) continue;
+        if (!(key in incoming)) continue;
+        candidates.add(key);
+      }
+    }
+    const out = {};
+    for (const key of candidates) {
+      const before = existing[key];
+      const after = incoming[key];
+      if (!isEqual(before, after)) {
+        out[key] = { from: before ?? null, to: after ?? null };
+      }
+    }
+    return Object.keys(out).length === 0 ? "noop" : out;
+  }
+};
+DeepEqualDiffer = __decorateClass([
+  Injectable18()
+], DeepEqualDiffer);
+function isEqual(a, b) {
+  if (a === b) return true;
+  const na = normalize(a);
+  const nb = normalize(b);
+  if (na === nb) return true;
+  if (typeof na === "object" && typeof nb === "object" && na !== null && nb !== null) {
+    return deepEqualObject(na, nb);
+  }
+  const numericEqual = maybeNumericEqual(na, nb) || maybeNumericEqual(nb, na);
+  return numericEqual;
+}
+function normalize(value) {
+  if (value instanceof Date) return value.toISOString();
+  return value;
+}
+function maybeNumericEqual(a, b) {
+  if (typeof a !== "string" || typeof b !== "number") return false;
+  if (a.trim() === "") return false;
+  const parsed = Number(a);
+  if (!Number.isFinite(parsed)) return false;
+  return parsed === b;
+}
+function deepEqualObject(a, b) {
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!(key in b)) return false;
+    if (!isEqual(a[key], b[key])) return false;
+  }
+  return true;
+}
+
+// runtime/subsystems/integration/execute-integration.use-case.ts
+import { Inject as Inject15, Injectable as Injectable19, Logger as Logger8, Optional as Optional8 } from "@nestjs/common";
+var ExecuteIntegrationUseCase = class {
+  constructor(source, cursors, differ, sink, recorder, multiTenant = false) {
+    this.source = source;
+    this.cursors = cursors;
+    this.differ = differ;
+    this.sink = sink;
+    this.recorder = recorder;
+    this.multiTenant = multiTenant;
+  }
+  source;
+  cursors;
+  differ;
+  sink;
+  recorder;
+  multiTenant;
+  logger = new Logger8(ExecuteIntegrationUseCase.name);
+  async execute(input) {
+    assertTenantId(input.tenantId, {
+      multiTenant: this.multiTenant,
+      operation: "execute"
+    });
+    const source = input.sourceOverride ?? this.source;
+    const startedAt = Date.now();
+    const cursorBefore = await this.cursors.get(input.subscription.id, input.tenantId);
+    const { id: runId } = await this.recorder.startRun({
+      subscriptionId: input.subscription.id,
+      direction: input.direction,
+      action: input.action,
+      cursorBefore,
+      tenantId: input.tenantId
+    });
+    let recordsFound = 0;
+    let recordsProcessed = 0;
+    let recordsFailed = 0;
+    let latestCursor = cursorBefore;
+    let cursorAdvanced = false;
+    let runError = null;
+    let status = "no_changes";
+    try {
+      for await (const change of source.listChanges(input.subscription, cursorBefore)) {
+        recordsFound++;
+        latestCursor = change.cursor;
+        cursorAdvanced = true;
+        try {
+          await this.processChange(runId, input, change);
+          recordsProcessed++;
+        } catch (err) {
+          recordsFailed++;
+          const message = err instanceof Error ? err.message : String(err);
+          this.logger.warn(
+            `integration item failed: subscription=${input.subscription.id} externalId=${change.externalId}: ${message}`
+          );
+          await this.recorder.recordItem({
+            integrationRunId: runId,
+            entityType: input.subscription.domain,
+            externalId: change.externalId,
+            operation: change.operation === "deleted" ? "deleted" : "updated",
+            status: "failed",
+            changedFields: {},
+            error: message,
+            tenantId: input.tenantId
+          });
+        }
+      }
+      if (recordsFailed > 0 && recordsProcessed === 0 && recordsFound > 0) {
+        status = "failed";
+        runError = `all ${recordsFailed} records failed`;
+      } else if (recordsFound === 0) {
+        status = "no_changes";
+      } else {
+        status = "success";
+      }
+    } catch (err) {
+      status = "failed";
+      runError = err instanceof Error ? err.message : String(err);
+      this.logger.error(
+        `integration source failed: subscription=${input.subscription.id}: ${runError}`
+      );
+    }
+    if (cursorAdvanced && latestCursor !== null && latestCursor !== void 0) {
+      try {
+        await this.cursors.put(input.subscription.id, latestCursor, input.tenantId);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        this.logger.error(
+          `cursor put failed: subscription=${input.subscription.id}: ${message}`
+        );
+        if (status !== "failed") {
+          status = "failed";
+          runError = `cursor put failed: ${message}`;
+        }
+      }
+    }
+    const durationMs = Date.now() - startedAt;
+    await this.recorder.completeRun(runId, {
+      status,
+      recordsFound,
+      recordsProcessed,
+      cursorAfter: cursorAdvanced ? latestCursor : cursorBefore,
+      durationMs,
+      error: runError
+    });
+    return {
+      runId,
+      status,
+      recordsFound,
+      recordsProcessed,
+      recordsFailed,
+      cursorBefore,
+      cursorAfter: cursorAdvanced ? latestCursor : cursorBefore,
+      durationMs,
+      error: runError
+    };
+  }
+  async processChange(runId, input, change) {
+    if (change.operation === "deleted") {
+      const result = await this.sink.softDeleteByExternalId(
+        input.userId,
+        change.externalId
+      );
+      await this.recorder.recordItem({
+        integrationRunId: runId,
+        entityType: input.subscription.domain,
+        externalId: change.externalId,
+        localId: result?.id ?? null,
+        operation: result ? "deleted" : "noop",
+        status: "success",
+        changedFields: {},
+        tenantId: input.tenantId
+      });
+      return;
+    }
+    const existing = await this.sink.findByExternalId(
+      input.userId,
+      change.externalId
+    );
+    const diff = this.differ.diff(
+      existing,
+      change.record,
+      change.providerChangedFields
+    );
+    if (diff === "noop") {
+      if (!this.sink.reprojectsOnNoop) {
+        await this.recorder.recordItem({
+          integrationRunId: runId,
+          entityType: input.subscription.domain,
+          externalId: change.externalId,
+          localId: null,
+          operation: "noop",
+          status: "success",
+          changedFields: {},
+          tenantId: input.tenantId
+        });
+        return;
+      }
+      const { id: noopLocalId } = await this.sink.upsertByExternalId(
+        input.userId,
+        change.record,
+        input.provider
+      );
+      await this.recorder.recordItem({
+        integrationRunId: runId,
+        entityType: input.subscription.domain,
+        externalId: change.externalId,
+        localId: noopLocalId,
+        operation: "noop",
+        status: "success",
+        changedFields: {},
+        tenantId: input.tenantId
+      });
+      return;
+    }
+    const { id: localId } = await this.sink.upsertByExternalId(
+      input.userId,
+      change.record,
+      input.provider
+    );
+    await this.recorder.recordItem({
+      integrationRunId: runId,
+      entityType: input.subscription.domain,
+      externalId: change.externalId,
+      localId,
+      operation: existing === null ? "created" : "updated",
+      status: "success",
+      changedFields: diff,
+      tenantId: input.tenantId
+    });
+  }
+};
+ExecuteIntegrationUseCase = __decorateClass([
+  Injectable19(),
+  __decorateParam(0, Inject15(INTEGRATION_CHANGE_SOURCE)),
+  __decorateParam(1, Inject15(INTEGRATION_CURSOR_STORE)),
+  __decorateParam(2, Inject15(INTEGRATION_FIELD_DIFFER)),
+  __decorateParam(3, Inject15(INTEGRATION_SINK)),
+  __decorateParam(4, Inject15(INTEGRATION_RUN_RECORDER)),
+  __decorateParam(5, Optional8()),
+  __decorateParam(5, Inject15(INTEGRATION_MULTI_TENANT))
+], ExecuteIntegrationUseCase);
+
+// runtime/subsystems/integration/integration-cursor-store.drizzle-backend.ts
+import { Inject as Inject16, Injectable as Injectable20, Optional as Optional9 } from "@nestjs/common";
+import { and as and6, desc as desc5, eq as eq7 } from "drizzle-orm";
+var PostgresCursorStore = class {
+  constructor(db, multiTenant) {
+    this.db = db;
+    this.multiTenant = multiTenant ?? false;
+  }
+  db;
+  multiTenant;
+  async get(subscriptionId, tenantId) {
+    const where = this.buildWhere(subscriptionId, tenantId, "cursor.get");
+    const rows = await this.db.select({ cursor: integrationSubscriptions.cursor }).from(integrationSubscriptions).where(where).limit(1);
+    if (rows.length === 0) return null;
+    return rows[0]?.cursor ?? null;
+  }
+  async put(subscriptionId, cursor, tenantId) {
+    const where = this.buildWhere(subscriptionId, tenantId, "cursor.put");
+    await this.db.update(integrationSubscriptions).set({
+      cursor,
+      lastIntegrationAt: /* @__PURE__ */ new Date(),
+      updatedAt: /* @__PURE__ */ new Date()
+    }).where(where);
+  }
+  async listAll(tenantId) {
+    assertTenantId(tenantId, {
+      multiTenant: this.multiTenant,
+      operation: "cursor.listAll"
+    });
+    const where = this.multiTenant ? eq7(integrationSubscriptions.tenantId, tenantId) : void 0;
+    const rows = await this.db.select({
+      id: integrationSubscriptions.id,
+      connectionId: integrationSubscriptions.connectionId,
+      adapter: integrationSubscriptions.adapter,
+      domain: integrationSubscriptions.domain,
+      externalRef: integrationSubscriptions.externalRef,
+      cursor: integrationSubscriptions.cursor,
+      lastIntegrationAt: integrationSubscriptions.lastIntegrationAt,
+      updatedAt: integrationSubscriptions.updatedAt,
+      tenantId: integrationSubscriptions.tenantId
+    }).from(integrationSubscriptions).where(where).orderBy(desc5(integrationSubscriptions.updatedAt));
+    return rows.map((row) => ({
+      subscriptionId: row.id,
+      connectionId: row.connectionId,
+      adapter: row.adapter,
+      domain: row.domain,
+      externalRef: row.externalRef,
+      cursor: row.cursor ?? null,
+      lastIntegrationAt: row.lastIntegrationAt,
+      updatedAt: row.updatedAt,
+      tenantId: row.tenantId
+    }));
+  }
+  /**
+   * Centralized WHERE clause — `get` and `put` share identical semantics.
+   * Drift here would let a caller read under one tenancy rule and write
+   * under another.
+   */
+  buildWhere(subscriptionId, tenantId, operation) {
+    assertTenantId(tenantId, {
+      multiTenant: this.multiTenant,
+      operation
+    });
+    if (this.multiTenant) {
+      return and6(
+        eq7(integrationSubscriptions.id, subscriptionId),
+        eq7(integrationSubscriptions.tenantId, tenantId)
+      );
+    }
+    return eq7(integrationSubscriptions.id, subscriptionId);
+  }
+};
+PostgresCursorStore = __decorateClass([
+  Injectable20(),
+  __decorateParam(0, Inject16(DRIZZLE)),
+  __decorateParam(1, Optional9()),
+  __decorateParam(1, Inject16(INTEGRATION_MULTI_TENANT))
+], PostgresCursorStore);
+
+// runtime/subsystems/integration/integration-run-recorder.drizzle-backend.ts
+import { Inject as Inject17, Injectable as Injectable21, Optional as Optional10 } from "@nestjs/common";
+import { and as and7, desc as desc6, eq as eq8 } from "drizzle-orm";
+var DrizzleIntegrationRunRecorder = class {
+  constructor(db, multiTenant) {
+    this.db = db;
+    this.multiTenant = multiTenant ?? false;
+  }
+  db;
+  multiTenant;
+  async startRun(input) {
+    assertTenantId(input.tenantId, {
+      multiTenant: this.multiTenant,
+      operation: "startRun"
+    });
+    const rows = await this.db.insert(integrationRuns).values({
+      subscriptionId: input.subscriptionId,
+      direction: input.direction,
+      action: input.action,
+      status: "running",
+      cursorBefore: input.cursorBefore ?? null,
+      tenantId: input.tenantId ?? null
+    }).returning({ id: integrationRuns.id });
+    const id = rows[0]?.id;
+    if (!id) {
+      throw new Error("DrizzleIntegrationRunRecorder: INSERT RETURNING produced no id");
+    }
+    return { id };
+  }
+  async recordItem(input) {
+    assertTenantId(input.tenantId, {
+      multiTenant: this.multiTenant,
+      operation: "recordItem"
+    });
+    FieldDiffSchema.parse(input.changedFields);
+    await this.db.insert(integrationRunItems).values({
+      integrationRunId: input.integrationRunId,
+      entityType: input.entityType,
+      externalId: input.externalId,
+      localId: input.localId ?? null,
+      operation: input.operation,
+      status: input.status,
+      changedFields: input.changedFields,
+      title: input.title ?? null,
+      error: input.error ?? null,
+      tenantId: input.tenantId ?? null
+    });
+  }
+  async listRecent(limit, subscriptionId, tenantId) {
+    assertTenantId(tenantId, {
+      multiTenant: this.multiTenant,
+      operation: "listRecent"
+    });
+    const conditions = [];
+    if (subscriptionId !== void 0) {
+      conditions.push(eq8(integrationRuns.subscriptionId, subscriptionId));
+    }
+    if (this.multiTenant) {
+      conditions.push(eq8(integrationRuns.tenantId, tenantId));
+    }
+    const where = conditions.length === 0 ? void 0 : conditions.length === 1 ? conditions[0] : and7(...conditions);
+    const rows = await this.db.select({
+      id: integrationRuns.id,
+      subscriptionId: integrationRuns.subscriptionId,
+      connectionId: integrationSubscriptions.connectionId,
+      status: integrationRuns.status,
+      startedAt: integrationRuns.startedAt,
+      completedAt: integrationRuns.completedAt,
+      recordsProcessed: integrationRuns.recordsProcessed,
+      tenantId: integrationRuns.tenantId
+    }).from(integrationRuns).innerJoin(
+      integrationSubscriptions,
+      eq8(integrationRuns.subscriptionId, integrationSubscriptions.id)
+    ).where(where).orderBy(desc6(integrationRuns.startedAt)).limit(limit);
+    return rows.map((row) => ({
+      id: row.id,
+      subscriptionId: row.subscriptionId,
+      connectionId: row.connectionId,
+      status: row.status,
+      startedAt: row.startedAt,
+      completedAt: row.completedAt,
+      recordsProcessed: row.recordsProcessed,
+      tenantId: row.tenantId
+    }));
+  }
+  async completeRun(runId, input) {
+    await this.db.update(integrationRuns).set({
+      status: input.status,
+      recordsFound: input.recordsFound,
+      recordsProcessed: input.recordsProcessed,
+      cursorAfter: input.cursorAfter ?? null,
+      durationMs: input.durationMs,
+      error: input.error ?? null,
+      completedAt: /* @__PURE__ */ new Date()
+    }).where(eq8(integrationRuns.id, runId));
+  }
+};
+DrizzleIntegrationRunRecorder = __decorateClass([
+  Injectable21(),
+  __decorateParam(0, Inject17(DRIZZLE)),
+  __decorateParam(1, Optional10()),
+  __decorateParam(1, Inject17(INTEGRATION_MULTI_TENANT))
+], DrizzleIntegrationRunRecorder);
+
+// runtime/subsystems/integration/integration.module.ts
+import { Module as Module7 } from "@nestjs/common";
+var IntegrationModule = class {
+  static forRoot(options) {
+    const multiTenant = options.multiTenant ?? false;
+    const sharedProviders = [
+      { provide: INTEGRATION_MODULE_OPTIONS, useValue: options },
+      { provide: INTEGRATION_MULTI_TENANT, useValue: multiTenant },
+      // Default differ — consumers can override by binding a different
+      // `IFieldDiffer<T>` to `INTEGRATION_FIELD_DIFFER` in their feature module.
+      { provide: INTEGRATION_FIELD_DIFFER, useValue: new DeepEqualDiffer() }
+    ];
+    const backendProviders = options.backend === "memory" ? [
+      // Wired as singletons via `useValue` so tests can pull
+      // them out via `moduleRef.get(MemoryCursorStore)` for
+      // direct assertions. Matches JOB-4 / MemoryJobStore shape.
+      { provide: MemoryCursorStore, useValue: new MemoryCursorStore() },
+      {
+        provide: INTEGRATION_CURSOR_STORE,
+        useExisting: MemoryCursorStore
+      },
+      { provide: MemoryRunRecorder, useValue: new MemoryRunRecorder() },
+      {
+        provide: INTEGRATION_RUN_RECORDER,
+        useExisting: MemoryRunRecorder
+      }
+    ] : [
+      // Drizzle backends — injected with DRIZZLE (provided by the
+      // consumer's DrizzleModule) + the INTEGRATION_MULTI_TENANT flag
+      // we bound above.
+      { provide: INTEGRATION_CURSOR_STORE, useClass: PostgresCursorStore },
+      { provide: INTEGRATION_RUN_RECORDER, useClass: DrizzleIntegrationRunRecorder }
+    ];
+    return {
+      module: IntegrationModule,
+      global: true,
+      providers: [...sharedProviders, ...backendProviders],
+      exports: [
+        INTEGRATION_MODULE_OPTIONS,
+        INTEGRATION_MULTI_TENANT,
+        INTEGRATION_FIELD_DIFFER,
+        INTEGRATION_CURSOR_STORE,
+        INTEGRATION_RUN_RECORDER
+      ]
+    };
+  }
+};
+IntegrationModule = __decorateClass([
+  Module7({})
+], IntegrationModule);
+
 // runtime/subsystems/auth/protocols/oauth-state-store.ts
 var OAuthStateError = class extends Error {
   constructor(message, reason) {
@@ -4443,12 +5414,12 @@ async function withAuthRetry(authStrategy, connectionId, op, options = {}) {
 }
 
 // runtime/subsystems/auth/auth-oauth-state.schema.ts
-import { pgTable as pgTable4, text as text4, timestamp as timestamp4 } from "drizzle-orm/pg-core";
-var authOAuthState = pgTable4("auth_oauth_state", {
-  state: text4("state").primaryKey(),
-  userId: text4("user_id").notNull(),
-  redirect: text4("redirect"),
-  expiresAt: timestamp4("expires_at", { withTimezone: true }).notNull()
+import { pgTable as pgTable5, text as text5, timestamp as timestamp5 } from "drizzle-orm/pg-core";
+var authOAuthState = pgTable5("auth_oauth_state", {
+  state: text5("state").primaryKey(),
+  userId: text5("user_id").notNull(),
+  redirect: text5("redirect"),
+  expiresAt: timestamp5("expires_at", { withTimezone: true }).notNull()
 });
 
 // runtime/subsystems/auth/backends/encryption-key/env.ts
@@ -4539,7 +5510,7 @@ var MemoryOAuthStateStore = class {
 
 // runtime/subsystems/auth/backends/state-store.drizzle-backend.ts
 import { randomBytes as randomBytes3 } from "crypto";
-import { eq as eq7 } from "drizzle-orm";
+import { eq as eq9 } from "drizzle-orm";
 var DrizzleOAuthStateStore = class {
   constructor(db, opts = {}) {
     this.db = db;
@@ -4563,7 +5534,7 @@ var DrizzleOAuthStateStore = class {
     return state;
   }
   async consume(state) {
-    const rows = await this.db.delete(authOAuthState).where(eq7(authOAuthState.state, state)).returning();
+    const rows = await this.db.delete(authOAuthState).where(eq9(authOAuthState.state, state)).returning();
     const row = rows[0];
     if (!row) {
       throw new OAuthStateError(
@@ -4585,7 +5556,7 @@ var DrizzleOAuthStateStore = class {
 import {
   Controller,
   Get,
-  Inject as Inject15,
+  Inject as Inject18,
   Param,
   Query,
   Req,
@@ -4687,11 +5658,11 @@ __decorateClass([
 ], AuthController.prototype, "callback", 1);
 AuthController = __decorateClass([
   Controller("auth"),
-  __decorateParam(0, Inject15(STRATEGY_REGISTRY)),
-  __decorateParam(1, Inject15(AUTH_USER_CONTEXT)),
-  __decorateParam(2, Inject15(OAUTH_STATE_STORE)),
-  __decorateParam(3, Inject15(AUTH_CONNECTION_GRANT_SINK)),
-  __decorateParam(4, Inject15(AUTH_OPTIONS))
+  __decorateParam(0, Inject18(STRATEGY_REGISTRY)),
+  __decorateParam(1, Inject18(AUTH_USER_CONTEXT)),
+  __decorateParam(2, Inject18(OAUTH_STATE_STORE)),
+  __decorateParam(3, Inject18(AUTH_CONNECTION_GRANT_SINK)),
+  __decorateParam(4, Inject18(AUTH_OPTIONS))
 ], AuthController);
 
 // runtime/base-classes/tenant-context.ts
@@ -4699,7 +5670,7 @@ import { AsyncLocalStorage } from "async_hooks";
 var als = new AsyncLocalStorage();
 
 // runtime/subsystems/auth/auth.module.ts
-import { Module as Module7 } from "@nestjs/common";
+import { Module as Module8 } from "@nestjs/common";
 function resolveEncryptionKeyProvider(choice) {
   if (choice === "env") {
     return { provide: ENCRYPTION_KEY, useClass: EnvEncryptionKey };
@@ -4759,7 +5730,7 @@ var AuthModule = class {
   }
 };
 AuthModule = __decorateClass([
-  Module7({})
+  Module8({})
 ], AuthModule);
 export {
   AUTH_CONNECTION_GRANT_SINK,
@@ -4776,11 +5747,13 @@ export {
   DrizzleEventBus,
   DrizzleOAuthStateStore,
   ENCRYPTION_KEY,
+  ENTITY_CHANGE_SOURCE_REGISTRY,
   EVENT_BUS,
   EnvEncryptionKey,
   EventsModule,
   LocalStorageBackend,
   MemoryCacheService,
+  MemoryEntityChangeSourceRegistry,
   MemoryEventBus,
   MemoryOAuthStateStore,
   MemoryStorageBackend,
@@ -4795,6 +5768,7 @@ export {
   STRATEGY_REGISTRY,
   SessionExpiredError,
   StorageModule,
+  UnknownEntityError,
   authOAuthState,
   collisionModeEnum,
   isSessionExpiredError,