@pattern-stack/codegen 0.15.1 → 0.15.3

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

@@ -1,242 +1,9 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __decorateClass = (decorators, target, key, kind) => {
-  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
-  for (var i = decorators.length - 1, decorator; i >= 0; i--)
-    if (decorator = decorators[i])
-      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-  if (kind && result) __defProp(target, key, result);
-  return result;
-};
-var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
-
-// runtime/subsystems/integration/execute-integration.use-case.ts
-import { Inject, Injectable, Logger, Optional } from "@nestjs/common";
-
-// runtime/subsystems/integration/integration-errors.ts
-var MissingTenantIdError = 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 MissingTenantIdError(options.operation);
-  }
-}
-
-// 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/integration/execute-integration.use-case.ts
-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 Logger(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([
-  Injectable(),
-  __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(INTEGRATION_MULTI_TENANT))
-], ExecuteIntegrationUseCase);
+import {
+  ExecuteIntegrationUseCase
+} from "../../../chunk-OGIZXGPY.js";
+import "../../../chunk-MZ6GV4YF.js";
+import "../../../chunk-S7C6TIIF.js";
+import "../../../chunk-2E224ZSN.js";
 export {
   ExecuteIntegrationUseCase
 };

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

@@ -1 +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\n/**\n * Injection token for the entity-keyed `IEntityChangeSourceRegistry` (C7,\n * #336). Bound to the codegen-emitted aggregator that folds per-provider\n * adapter contributions into one registry (RFC-0001 §3, emitted by Track D\n * D3/D4).\n *\n * A string constant, not `Symbol.for(...)`, to match this subsystem's token\n * convention (see file header). The originating issue's code block proposed a\n * `Symbol.for('@pattern-stack/codegen.entity-change-source-registry')` key,\n * predating the sync→integration consolidation onto string tokens; kept as a\n * string here for internal consistency with the other INTEGRATION_* tokens.\n */\nexport const ENTITY_CHANGE_SOURCE_REGISTRY = 'ENTITY_CHANGE_SOURCE_REGISTRY' as const;\n"],"mappings":"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","names":[]}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/runtime/subsystems/integration/incremental-read.js

@@ -1,147 +1,8 @@
-// runtime/subsystems/integration/incremental-read.ts
-async function mapConcurrent(ids, fn, limit) {
-  const out = /* @__PURE__ */ new Map();
-  if (ids.length === 0) return out;
-  const width = Math.max(1, Math.min(limit, ids.length));
-  let next = 0;
-  const worker = async () => {
-    while (next < ids.length) {
-      const idx = next++;
-      const id = ids[idx];
-      out.set(id, await fn(id));
-    }
-  };
-  await Promise.all(Array.from({ length: width }, worker));
-  return out;
-}
-var IncrementalReadBase = class {
-  /**
-   * Whether the vendor takes the request predicate server-side. Declared, not
-   * enforced here — surfaced into the emission manifest (R3) so the falsifier
-   * suite (R4) can record which adapters filter post-hydrate. `false` is the
-   * honest floor (e.g. Gmail without `q=`), handled via `matchesRecord`.
-   */
-  filterPushdown = false;
-  /** Max concurrent in-flight calls for a `mapConcurrent`-built `hydrate`. */
-  hydrateConcurrency = 10;
-  /** `Change<T>.source` provenance stamped by `listChanges`. */
-  changeSource = "poll";
-  /**
-   * Whether this source's cursor strategy is divisible (RFC-0003 §3). When
-   * `true` (default — sortable watermarks like `systemModstamp`/`timestamp`/
-   * `replayId`), `listChanges` emits each record's per-ref cursor, so the
-   * orchestrator may checkpoint mid-walk and a crash resumes from the last
-   * delivered ref.
-   *
-   * When `false` (atomic opaque tokens — Gmail `historyId`, Calendar
-   * `syncToken`), `listChanges` WITHHOLDS per-ref cursors and emits the
-   * end-of-walk token only on the final record, so the orchestrator's
-   * persist-last-yielded lifecycle can never persist an unresumable mid-walk
-   * token. The cost is blast-radius: an interrupted atomic run resumes
-   * all-or-nothing from the prior persisted token. For atomic *backfills* that
-   * radius is the whole enumerate walk — bound it with `ReadRequest.pageSize`
-   * (smaller pages ⇒ shorter walks per run). Per-page atomic checkpointing is a
-   * future refinement; R2 gates at end-of-walk.
-   *
-   * Codegen (R3) sets this from the strategy kind via `isDivisibleCursor`.
-   */
-  cursorDivisible = true;
-  // ---- Optional filter hooks — exactly one is live per `filterPushdown` ----
-  /** Pre-hydrate predicate over the cheap ref (preferred — avoids hydration). */
-  matchesRef(_ref, _filter) {
-    return true;
-  }
-  /** Post-hydrate predicate over the canonical record (the no-pushdown floor). */
-  matchesRecord(_record, _filter) {
-    return true;
-  }
-  /**
-   * Resolve the filter for a subscription when adapting to `listChanges`
-   * (which has no filter argument). Defaults to none; codegen wiring (R3)
-   * overrides this to thread `DetectionConfig.filters`.
-   */
-  filterFor(_subscription) {
-    return void 0;
-  }
-  // ---- PROVIDED by the base ----
-  /**
-   * Stream canonical records for a request. Filter is applied BEFORE hydrate
-   * (structural: a kept ref is hydrated, a rejected one never is), so an
-   * adapter cannot hydrate-then-discard. A hydrate miss (deleted mid-run) is
-   * skipped, never fabricated.
-   */
-  async *read(req, ctx) {
-    for await (const refPage of this.enumerate(req.mode, req.filter, req.pageSize, ctx)) {
-      const kept = refPage.filter((ref) => this.matchesRef(ref, req.filter));
-      if (kept.length === 0) continue;
-      const raws = await this.hydrate(
-        kept.map((ref) => ref.externalId),
-        ctx
-      );
-      for (const ref of kept) {
-        const raw = raws.get(ref.externalId);
-        if (raw === void 0 || raw === null) continue;
-        const record = this.toCanonical(raw);
-        if (record !== null && this.matchesRecord(record, req.filter)) {
-          yield { externalId: ref.externalId, record, raw, cursor: ref.cursor };
-        }
-      }
-    }
-  }
-  /**
-   * `RandomRead<T>` — single-record read, provided for free as
-   * `toCanonical ∘ hydrate([id])`. Reuses the adapter's batched fetch + miss
-   * tolerance; returns `null` for a missing or undecodable record.
-   */
-  async get(id, ctx) {
-    const raws = await this.hydrate([id], ctx);
-    const raw = raws.get(id);
-    if (raw === void 0 || raw === null) return null;
-    return this.toCanonical(raw);
-  }
-  /**
-   * `IChangeSource<T>` adaptation. Maps the orchestrator's by-value cursor to a
-   * `ReadMode` (`null` → `full` backfill, else `delta`), streams `read()`, and
-   * stamps each `SourcedRecord` into a `Change<T>`. All records surface as
-   * `'updated'`; the orchestrator's diff stage classifies create-vs-update and
-   * deletes arrive as tombstone refs (`toCanonical` may flag them).
-   *
-   * Cursor emission honors `cursorDivisible` (RFC-0003 §3). Divisible: each
-   * record carries its own per-ref cursor. Atomic: per-ref cursors are withheld
-   * (`undefined`, which the orchestrator skips persisting) and the end-of-walk
-   * token rides only on the final record — so a mid-walk crash never persists
-   * an unresumable token. If an atomic run yields no surviving records, no
-   * cursor is persisted and the next run re-reads the same (empty) delta — a
-   * bounded inefficiency, never data loss.
-   */
-  async *listChanges(subscription, cursor) {
-    const mode = cursor === null || cursor === void 0 ? { kind: "full" } : { kind: "delta", cursor };
-    const filter = this.filterFor(subscription);
-    const stream = this.read({ mode, filter }, { subscription });
-    if (this.cursorDivisible) {
-      for await (const sourced of stream) {
-        yield this.toChange(sourced, sourced.cursor);
-      }
-      return;
-    }
-    let prev = null;
-    for await (const sourced of stream) {
-      if (prev !== null) yield this.toChange(prev, void 0);
-      prev = sourced;
-    }
-    if (prev !== null) yield this.toChange(prev, prev.cursor);
-  }
-  /** Stamp a `SourcedRecord` into a `Change<T>` with an explicit emitted cursor. */
-  toChange(sourced, cursor) {
-    return {
-      externalId: sourced.externalId,
-      operation: "updated",
-      record: sourced.record,
-      cursor,
-      source: this.changeSource
-    };
-  }
-};
+import {
+  IncrementalReadBase,
+  mapConcurrent
+} from "../../../chunk-LG57S2SC.js";
+import "../../../chunk-2E224ZSN.js";
 export {
   IncrementalReadBase,
   mapConcurrent

package/dist/runtime/subsystems/integration/incremental-read.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../runtime/subsystems/integration/incremental-read.ts"],"sourcesContent":["/**\n * Integration subsystem — `IncrementalRead<T, F>` + `RandomRead<T>` capability\n * and the providing `IncrementalReadBase<T, F, M>` (RFC-0003 R1).\n *\n * The universal read primitive. Where `IChangeSource.listChanges` is the\n * *transport* contract (stream `Change<T>`, orchestrator owns cursor lifecycle),\n * this base owns *how the body that produces those changes is written* — the\n * level the bare `changeSources = {}` author-seam left unstructured.\n *\n * The read decomposes into two composable verbs the adapter supplies:\n *\n *   - `enumerate(mode, filter) → AsyncIterable<Ref<M>[]>` — the cheap delta /\n *     backfill walk; streams pages of lightweight refs (id + per-ref cursor +\n *     filterable metadata). LAZY: pull-driven so hydrate backpressures it.\n *   - `hydrate(ids) → Map<id, raw>` — the expensive fetch-by-id, batched; where\n *     bounded concurrency / a vendor `/batch` endpoint lives. Keyed and\n *     miss-tolerant (a mid-run 404 cannot shift alignment).\n *   - `toCanonical(raw) → T | null` — provider payload → canonical record.\n *\n * The base PROVIDES the orchestration: drain enumerate, **filter before\n * hydrate** (structural — an adapter physically cannot hydrate-then-discard),\n * keyed pairing, per-ref cursor emission, and the `IChangeSource.listChanges`\n * adaptation. It also provides `RandomRead.get()` for free as\n * `toCanonical ∘ hydrate([id])` — so every incremental adapter is a\n * single-record reader (the \"list cheaply, fill on click\" query-surface need)\n * without extra code.\n *\n * The shape generalizes dealbrain's proven HubSpot `listSince` (streams, pushes\n * the filter server-side, carries a per-record cursor) to vendors whose list\n * returns id-stubs (Gmail) or nested resources (Meet). Calendar-style\n * full-object lists override `hydrate` as a passthrough.\n *\n * See RFC-0003 (Track D round-3), ADR-033 (`detection:` config), and\n * `poll-change-source.ts` (the sibling primitive this composes beside).\n */\n\nimport type {\n  Change,\n  ChangeSource,\n  IChangeSource,\n  IntegrationSubscriptionView,\n} from './integration-change-source.protocol';\n\n// ============================================================================\n// Capability shapes\n// ============================================================================\n\n/**\n * How a read walks the upstream. Modes are values, not verbs (swe-brain\n * ADR-0003: mode ≠ capability) — one `read()` verb dispatches on these.\n *\n *   - `delta`     — incremental walk from a persisted cursor.\n *   - `full`      — cursorless backfill (optionally bounded by `since`).\n *   - `reconcile` — gap-repair: re-fetch a known id set the cursor skipped\n *                   (the repair pass for the silent-tail-skip + #414-style\n *                   multi-provider divergence).\n */\nexport type ReadMode =\n  | { readonly kind: 'delta'; readonly cursor: unknown }\n  | { readonly kind: 'full'; readonly since?: Date }\n  | { readonly kind: 'reconcile'; readonly knownIds: readonly string[] };\n\n/**\n * A cheap ref from the enumerate pass: identity + per-ref cursor + metadata to\n * filter or display on. `cursor` is the position AS OF this ref — see\n * `IncrementalReadBase.cursorDivisible` (R2) for when it may be checkpointed\n * mid-walk versus withheld until a safe boundary.\n */\nexport interface Ref<M = Record<string, unknown>> {\n  readonly externalId: string;\n  readonly cursor: unknown;\n  readonly meta: M;\n}\n\n/** A read request: the mode, an optional adapter-typed filter, and page size. */\nexport interface ReadRequest<F = unknown> {\n  readonly mode: ReadMode;\n  readonly filter?: F;\n  readonly pageSize?: number;\n}\n\n/**\n * Per-run context threaded from `listChanges` into the vendor read body (R5).\n *\n * Carries the `subscription` framing the run so `enumerate`/`hydrate` can resolve\n * **per-connection credentials** (and raw-landing keys) from\n * `subscription.externalRef` — the gap a multi-account consumer surfaced: a\n * singleton change source cannot hold connection-scoped auth, and before R5 the\n * base forwarded the subscription only into `filterFor`, never into the fetch.\n *\n * Optional throughout (the core contract): a direct `read()` / `get()` call — the\n * query surface's \"fill one record on click\" — may omit it. An adapter that needs\n * per-connection auth reads `ctx?.subscription?.externalRef` and asserts its\n * presence; a provider-level-auth adapter ignores it.\n */\nexport interface ReadContext {\n  /** The subscription framing this run; `externalRef` is the upstream scope /\n   *  connection id the adapter resolves credentials + raw-landing keys from. */\n  readonly subscription?: IntegrationSubscriptionView;\n}\n\n/**\n * The `read()`-side envelope: canonical record + the raw vendor payload it came\n * from + the originating external id + the per-ref cursor.\n *\n * Distinct from the runtime's transport envelope `Change<T>`\n * (operation/externalId/cursor/source). The relationship is one-directional:\n * `listChanges()` adapts `read()` → `Change<T>` (dropping `raw`, stamping\n * `operation`). `read()` keeps `raw` and `externalId` so a query surface can\n * re-project without a second fetch.\n */\nexport interface SourcedRecord<T> {\n  readonly externalId: string;\n  readonly record: T;\n  readonly raw: unknown;\n  readonly cursor: unknown;\n}\n\n/**\n * The universal read capability — one public verb that streams. Filtering,\n * hydration, and cursor emission are the providing base's concern.\n */\nexport interface IncrementalRead<T, F = unknown> {\n  read(req: ReadRequest<F>, ctx?: ReadContext): AsyncIterable<SourcedRecord<T>>;\n}\n\n/**\n * Single-record read by external id — the \"fill on click\" atom. Provided for\n * free by `IncrementalReadBase` (composes `hydrate` + `toCanonical`); declared\n * as its own capability so consumers can depend on it without the streaming\n * surface.\n */\nexport interface RandomRead<T> {\n  get(id: string, ctx?: ReadContext): Promise<T | null>;\n}\n\n// ============================================================================\n// Bounded-parallel map helper\n// ============================================================================\n\n/**\n * Map `ids` through `fn` with at most `limit` concurrent in-flight calls,\n * collecting results keyed by id. The workhorse for writing a batched\n * `hydrate` over a single-id fetch without serial N+1 latency.\n */\nexport async function mapConcurrent<R>(\n  ids: readonly string[],\n  fn: (id: string) => Promise<R>,\n  limit: number,\n): Promise<Map<string, R>> {\n  const out = new Map<string, R>();\n  if (ids.length === 0) return out;\n  const width = Math.max(1, Math.min(limit, ids.length));\n  let next = 0;\n  const worker = async (): Promise<void> => {\n    while (next < ids.length) {\n      const idx = next++;\n      const id = ids[idx]!;\n      out.set(id, await fn(id));\n    }\n  };\n  await Promise.all(Array.from({ length: width }, worker));\n  return out;\n}\n\n// ============================================================================\n// IncrementalReadBase\n// ============================================================================\n\n/**\n * Providing base for the read capability. A subclass fills exactly three vendor\n * methods — `enumerate`, `hydrate`, `toCanonical` — and gets a streaming,\n * filter-before-hydrate, miss-tolerant `IncrementalRead<T, F>` +\n * `IChangeSource<T>` + `RandomRead<T>`.\n *\n * Type params: `T` canonical record, `F` adapter-typed filter, `M` per-ref\n * metadata (defaults to an untyped bag — surface packages supply a domain `M`).\n */\nexport abstract class IncrementalReadBase<T, F = unknown, M = Record<string, unknown>>\n  implements IncrementalRead<T, F>, IChangeSource<T>, RandomRead<T>\n{\n  /** Human label for run logs — e.g. `'google-mail-email'`. */\n  abstract readonly label: string;\n\n  /**\n   * Whether the vendor takes the request predicate server-side. Declared, not\n   * enforced here — surfaced into the emission manifest (R3) so the falsifier\n   * suite (R4) can record which adapters filter post-hydrate. `false` is the\n   * honest floor (e.g. Gmail without `q=`), handled via `matchesRecord`.\n   */\n  protected readonly filterPushdown: boolean = false;\n\n  /** Max concurrent in-flight calls for a `mapConcurrent`-built `hydrate`. */\n  protected readonly hydrateConcurrency: number = 10;\n\n  /** `Change<T>.source` provenance stamped by `listChanges`. */\n  protected readonly changeSource: ChangeSource = 'poll';\n\n  /**\n   * Whether this source's cursor strategy is divisible (RFC-0003 §3). When\n   * `true` (default — sortable watermarks like `systemModstamp`/`timestamp`/\n   * `replayId`), `listChanges` emits each record's per-ref cursor, so the\n   * orchestrator may checkpoint mid-walk and a crash resumes from the last\n   * delivered ref.\n   *\n   * When `false` (atomic opaque tokens — Gmail `historyId`, Calendar\n   * `syncToken`), `listChanges` WITHHOLDS per-ref cursors and emits the\n   * end-of-walk token only on the final record, so the orchestrator's\n   * persist-last-yielded lifecycle can never persist an unresumable mid-walk\n   * token. The cost is blast-radius: an interrupted atomic run resumes\n   * all-or-nothing from the prior persisted token. For atomic *backfills* that\n   * radius is the whole enumerate walk — bound it with `ReadRequest.pageSize`\n   * (smaller pages ⇒ shorter walks per run). Per-page atomic checkpointing is a\n   * future refinement; R2 gates at end-of-walk.\n   *\n   * Codegen (R3) sets this from the strategy kind via `isDivisibleCursor`.\n   */\n  protected readonly cursorDivisible: boolean = true;\n\n  // ---- SUPPLIED by the adapter (the irreducible vendor seam) ----\n\n  /**\n   * The cheap walk. Streams pages of refs; LAZY so `hydrate` backpressures it\n   * (one page hydrated before the next is pulled). Mode-dispatch lives here:\n   * `delta` resumes from `mode.cursor`, `full` walks from the top, `reconcile`\n   * re-fetches `mode.knownIds`.\n   *\n   * `pageSize` (from `ReadRequest`) is the adapter's requested vendor page size\n   * — also the atomic-cursor backfill blast-radius bound (§ `cursorDivisible`).\n   * Honor it as a hint; vendors that cap page size clamp it.\n   *\n   * `ctx?.subscription` (R5) carries the run's subscription, so a per-connection\n   * adapter resolves credentials / upstream scope from `externalRef` here; absent\n   * on a direct `read()` with no run subscription.\n   */\n  protected abstract enumerate(\n    mode: ReadMode,\n    filter?: F,\n    pageSize?: number,\n    ctx?: ReadContext,\n  ): AsyncIterable<Ref<M>[]>;\n\n  /**\n   * Fetch raw payloads for `ids`, keyed by id. MUST be miss-tolerant: omit (or\n   * map to `null`) any id that 404s mid-run rather than throwing or shifting\n   * alignment. Write it over `mapConcurrent(ids, (id) => this.fetchOne(id),\n   * this.hydrateConcurrency)`; override with a real `/batch` call or a\n   * passthrough (full-object list) where the vendor allows.\n   *\n   * `ctx?.subscription` (R5) carries the run's subscription for per-connection\n   * credential resolution (the fetch is where the vendor call happens) and is the\n   * natural place to land raw payloads keyed by `subscription.id`.\n   */\n  protected abstract hydrate(ids: string[], ctx?: ReadContext): Promise<Map<string, unknown>>;\n\n  /** Provider payload → canonical record. Return `null` to drop a record. */\n  protected abstract toCanonical(raw: unknown): T | null;\n\n  // ---- Optional filter hooks — exactly one is live per `filterPushdown` ----\n\n  /** Pre-hydrate predicate over the cheap ref (preferred — avoids hydration). */\n  protected matchesRef(_ref: Ref<M>, _filter?: F): boolean {\n    return true;\n  }\n\n  /** Post-hydrate predicate over the canonical record (the no-pushdown floor). */\n  protected matchesRecord(_record: T, _filter?: F): boolean {\n    return true;\n  }\n\n  /**\n   * Resolve the filter for a subscription when adapting to `listChanges`\n   * (which has no filter argument). Defaults to none; codegen wiring (R3)\n   * overrides this to thread `DetectionConfig.filters`.\n   */\n  protected filterFor(_subscription: IntegrationSubscriptionView): F | undefined {\n    return undefined;\n  }\n\n  // ---- PROVIDED by the base ----\n\n  /**\n   * Stream canonical records for a request. Filter is applied BEFORE hydrate\n   * (structural: a kept ref is hydrated, a rejected one never is), so an\n   * adapter cannot hydrate-then-discard. A hydrate miss (deleted mid-run) is\n   * skipped, never fabricated.\n   */\n  async *read(req: ReadRequest<F>, ctx?: ReadContext): AsyncIterable<SourcedRecord<T>> {\n    for await (const refPage of this.enumerate(req.mode, req.filter, req.pageSize, ctx)) {\n      const kept = refPage.filter((ref) => this.matchesRef(ref, req.filter));\n      if (kept.length === 0) continue;\n      const raws = await this.hydrate(\n        kept.map((ref) => ref.externalId),\n        ctx,\n      );\n      for (const ref of kept) {\n        const raw = raws.get(ref.externalId);\n        if (raw === undefined || raw === null) continue; // deleted mid-run → skip\n        const record = this.toCanonical(raw);\n        if (record !== null && this.matchesRecord(record, req.filter)) {\n          yield { externalId: ref.externalId, record, raw, cursor: ref.cursor };\n        }\n      }\n    }\n  }\n\n  /**\n   * `RandomRead<T>` — single-record read, provided for free as\n   * `toCanonical ∘ hydrate([id])`. Reuses the adapter's batched fetch + miss\n   * tolerance; returns `null` for a missing or undecodable record.\n   */\n  async get(id: string, ctx?: ReadContext): Promise<T | null> {\n    const raws = await this.hydrate([id], ctx);\n    const raw = raws.get(id);\n    if (raw === undefined || raw === null) return null;\n    return this.toCanonical(raw);\n  }\n\n  /**\n   * `IChangeSource<T>` adaptation. Maps the orchestrator's by-value cursor to a\n   * `ReadMode` (`null` → `full` backfill, else `delta`), streams `read()`, and\n   * stamps each `SourcedRecord` into a `Change<T>`. All records surface as\n   * `'updated'`; the orchestrator's diff stage classifies create-vs-update and\n   * deletes arrive as tombstone refs (`toCanonical` may flag them).\n   *\n   * Cursor emission honors `cursorDivisible` (RFC-0003 §3). Divisible: each\n   * record carries its own per-ref cursor. Atomic: per-ref cursors are withheld\n   * (`undefined`, which the orchestrator skips persisting) and the end-of-walk\n   * token rides only on the final record — so a mid-walk crash never persists\n   * an unresumable token. If an atomic run yields no surviving records, no\n   * cursor is persisted and the next run re-reads the same (empty) delta — a\n   * bounded inefficiency, never data loss.\n   */\n  async *listChanges(\n    subscription: IntegrationSubscriptionView,\n    cursor: unknown | null,\n  ): AsyncIterable<Change<T>> {\n    const mode: ReadMode =\n      cursor === null || cursor === undefined\n        ? { kind: 'full' }\n        : { kind: 'delta', cursor };\n    const filter = this.filterFor(subscription);\n    // R5: thread the run's subscription into the read body so `enumerate`/`hydrate`\n    // can resolve per-connection credentials (and raw-landing keys) from it.\n    const stream = this.read({ mode, filter }, { subscription });\n\n    if (this.cursorDivisible) {\n      for await (const sourced of stream) {\n        yield this.toChange(sourced, sourced.cursor);\n      }\n      return;\n    }\n\n    // Atomic: one-record lookahead. Emit every record but the last with a\n    // withheld (`undefined`) cursor; the last record carries the end-of-walk\n    // token. Contract: an atomic adapter stamps the (single, shared) end-of-walk\n    // token onto its refs' `cursor` — so whichever record survives last carries\n    // it. The base emits a real cursor exactly once, on that final record, so the\n    // orchestrator can never persist a mid-walk value. If zero records survive,\n    // nothing is persisted (next run re-reads the delta — bounded, never lossy).\n    let prev: SourcedRecord<T> | null = null;\n    for await (const sourced of stream) {\n      if (prev !== null) yield this.toChange(prev, undefined);\n      prev = sourced;\n    }\n    if (prev !== null) yield this.toChange(prev, prev.cursor);\n  }\n\n  /** Stamp a `SourcedRecord` into a `Change<T>` with an explicit emitted cursor. */\n  private toChange(sourced: SourcedRecord<T>, cursor: unknown): Change<T> {\n    return {\n      externalId: sourced.externalId,\n      operation: 'updated',\n      record: sourced.record,\n      cursor,\n      source: this.changeSource,\n    };\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}