@pattern-stack/codegen 0.10.0 → 0.11.0

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

@@ -1,5 +1,5 @@
 /**
- * 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
@@ -9,8 +9,8 @@
  * consumers pass one fetch callback regardless of mode.
  */
 import type { DetectionConfig } from './detection-config.schema';
-import type { IChangeSource } from './sync-change-source.protocol';
-import type { ChangeMiddleware } from './sync-middleware.protocol';
+import type { IChangeSource } from './integration-change-source.protocol';
+import type { ChangeMiddleware } from './integration-middleware.protocol';
 import {
   PollChangeSource,
   type PollFetchCallback,

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

@@ -1,5 +1,5 @@
 /**
- * DeepEqualDiffer — default `IFieldDiffer<T>` for the sync subsystem (SYNC-5).
+ * DeepEqualDiffer — default `IFieldDiffer<T>` for the integration subsystem (SYNC-5).
  *
  * Walks every field of `incoming` against `existing`, emitting a structured
  * per-field diff (`{ from, to }`) for every field whose value changed.
@@ -39,15 +39,15 @@ import type {
   DiffResult,
   FieldDiff,
   IFieldDiffer,
-} from './sync-field-diff.protocol';
+} from './integration-field-diff.protocol';
 
 /**
- * Default ignore list. Keep in sync with consumer canonical-record shapes —
- * adding a row-metadata field here means no sync will ever mark it changed.
+ * Default ignore list. Keep in integration with consumer canonical-record shapes —
+ * adding a row-metadata field here means no integration will ever mark it changed.
  *
  * Includes the columns contributed by the `external_id_tracking` behavior
  * (`external_id`/`externalId`, `provider`, `provider_metadata`/`providerMetadata`).
- * These are sync-tracking metadata, not domain attributes: they ride on the
+ * These are integration-tracking metadata, not domain attributes: they ride on the
  * canonical record but must never register as a field change (the external id
  * is the record's identity, not a mutable value). Listed in both snake_case
  * and camelCase so the differ ignores them regardless of the consumer's
@@ -71,7 +71,7 @@ const DEFAULT_IGNORE_FIELDS: ReadonlySet<string> = new Set([
 export 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[];
@@ -148,7 +148,7 @@ export class DeepEqualDiffer<T extends Record<string, unknown>>
 // ─── equality helpers ───────────────────────────────────────────────────────
 
 /**
- * Field-level equality with the canonical-sync normalizations:
+ * Field-level equality with the canonical-integration normalizations:
  *   - Date → toISOString (adapters deliver strings)
  *   - numeric-string vs number → numeric equality when both parse
  *   - deep equality for plain objects/arrays (single-level is enough for

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

@@ -1,7 +1,7 @@
 /**
- * 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>`
@@ -16,7 +16,7 @@
  *   - 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/runtime/subsystems/{sync/execute-sync.use-case.ts → integration/execute-integration.use-case.ts}

@@ -1,12 +1,12 @@
 /**
- * ExecuteSyncUseCase — the generic sync orchestrator (SYNC-5).
+ * ExecuteIntegrationUseCase — the generic integration orchestrator (SYNC-5).
  *
  * One class. Reused across every `(provider, detection-mode, canonical-entity)`
  * tuple. Parameterized over `T` so canonical records stay typed end-to-end.
  *
  * Flow per run:
  *
- *   1. `recorder.startRun(...)` — opens a `sync_runs` row in 'running'.
+ *   1. `recorder.startRun(...)` — opens a `integration_runs` row in 'running'.
  *   2. for each change yielded by `source.listChanges(subscription, cursorBefore)`:
  *        a. differ.diff(existing, incoming) → 'noop' short-circuits to
  *           a noop audit row (no sink write).
@@ -33,7 +33,7 @@
  * ## Generics
  *
  * - `T` = canonical record shape from the adapter side. Same `T` flows
- *   through `IChangeSource<T>`, `IFieldDiffer<T>`, `ISyncSink<T>`.
+ *   through `IChangeSource<T>`, `IFieldDiffer<T>`, `IIntegrationSink<T>`.
  *
  * ## No CRM bleed
  *
@@ -41,30 +41,30 @@
  * is strictly provider-agnostic:
  *   - `entityType` is `string` throughout; no `'opportunity' | 'account' | ...`
  *     narrowing leaks into the use case
- *   - the upstream consumer's `SyncRunRecorderService` class injection replaced with the
- *     `ISyncRunRecorder` protocol (backend lands in SYNC-4)
+ *   - the upstream consumer's `IntegrationRunRecorderService` class injection replaced with the
+ *     `IIntegrationRunRecorder` protocol (backend lands in SYNC-4)
  */
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
-import type { IChangeSource, Change } from './sync-change-source.protocol';
-import type { ICursorStore } from './sync-cursor-store.protocol';
-import type { IFieldDiffer, FieldDiff } from './sync-field-diff.protocol';
-import type { ISyncSink } from './sync-sink.protocol';
-import type { ISyncRunRecorder } from './sync-run-recorder.protocol';
-import { assertTenantId } from './sync-errors';
+import type { IChangeSource, Change } from './integration-change-source.protocol';
+import type { ICursorStore } from './integration-cursor-store.protocol';
+import type { IFieldDiffer, FieldDiff } from './integration-field-diff.protocol';
+import type { IIntegrationSink } from './integration-sink.protocol';
+import type { IIntegrationRunRecorder } from './integration-run-recorder.protocol';
+import { assertTenantId } from './integration-errors';
 import {
-  SYNC_CHANGE_SOURCE,
-  SYNC_CURSOR_STORE,
-  SYNC_FIELD_DIFFER,
-  SYNC_MULTI_TENANT,
-  SYNC_RUN_RECORDER,
-  SYNC_SINK,
-} from './sync.tokens';
+  INTEGRATION_CHANGE_SOURCE,
+  INTEGRATION_CURSOR_STORE,
+  INTEGRATION_FIELD_DIFFER,
+  INTEGRATION_MULTI_TENANT,
+  INTEGRATION_RUN_RECORDER,
+  INTEGRATION_SINK,
+} from './integration.tokens';
 
 // ============================================================================
 // Inputs + result
 // ============================================================================
 
-export interface ExecuteSyncInput<T> {
+export interface ExecuteIntegrationInput<T> {
   /** The subscription whose cursor/identity frames this run. */
   readonly subscription: {
     readonly id: string;
@@ -77,19 +77,19 @@ export 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>;
 }
 
-export interface ExecuteSyncResult {
+export interface ExecuteIntegrationResult {
   readonly runId: string;
   readonly status: 'success' | 'no_changes' | 'failed';
   readonly recordsFound: number;
@@ -102,25 +102,25 @@ export interface ExecuteSyncResult {
 }
 
 // ============================================================================
-// ExecuteSyncUseCase
+// ExecuteIntegrationUseCase
 // ============================================================================
 
 @Injectable()
-export class ExecuteSyncUseCase<T extends Record<string, unknown>> {
-  private readonly logger = new Logger(ExecuteSyncUseCase.name);
+export class ExecuteIntegrationUseCase<T extends Record<string, unknown>> {
+  private readonly logger = new Logger(ExecuteIntegrationUseCase.name);
 
   constructor(
-    @Inject(SYNC_CHANGE_SOURCE) private readonly source: IChangeSource<T>,
-    @Inject(SYNC_CURSOR_STORE) private readonly cursors: ICursorStore,
-    @Inject(SYNC_FIELD_DIFFER) private readonly differ: IFieldDiffer<T>,
-    @Inject(SYNC_SINK) private readonly sink: ISyncSink<T>,
-    @Inject(SYNC_RUN_RECORDER) private readonly recorder: ISyncRunRecorder,
+    @Inject(INTEGRATION_CHANGE_SOURCE) private readonly source: IChangeSource<T>,
+    @Inject(INTEGRATION_CURSOR_STORE) private readonly cursors: ICursorStore,
+    @Inject(INTEGRATION_FIELD_DIFFER) private readonly differ: IFieldDiffer<T>,
+    @Inject(INTEGRATION_SINK) private readonly sink: IIntegrationSink<T>,
+    @Inject(INTEGRATION_RUN_RECORDER) private readonly recorder: IIntegrationRunRecorder,
     @Optional()
-    @Inject(SYNC_MULTI_TENANT)
+    @Inject(INTEGRATION_MULTI_TENANT)
     private readonly multiTenant: boolean = false,
   ) {}
 
-  async execute(input: ExecuteSyncInput<T>): Promise<ExecuteSyncResult> {
+  async execute(input: ExecuteIntegrationInput<T>): Promise<ExecuteIntegrationResult> {
     // Defense-in-depth tenancy guard — fire BEFORE startRun so a rejected
     // input never leaves a dangling `status=running` row. Backends also
     // enforce (SYNC-4), but failing fast at the orchestrator boundary is
@@ -163,10 +163,10 @@ export class ExecuteSyncUseCase<T extends Record<string, unknown>> {
           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',
@@ -197,7 +197,7 @@ export class ExecuteSyncUseCase<T extends Record<string, unknown>> {
       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}`,
       );
     }
 
@@ -244,7 +244,7 @@ export class ExecuteSyncUseCase<T extends Record<string, unknown>> {
 
   private async processChange(
     runId: string,
-    input: ExecuteSyncInput<T>,
+    input: ExecuteIntegrationInput<T>,
     change: Change<T>,
   ): Promise<void> {
     // Deletion branch — no diff, no upsert; soft-delete via sink.
@@ -254,7 +254,7 @@ export class ExecuteSyncUseCase<T extends Record<string, unknown>> {
         change.externalId,
       );
       await this.recorder.recordItem({
-        syncRunId: runId,
+        integrationRunId: runId,
         entityType: input.subscription.domain,
         externalId: change.externalId,
         localId: result?.id ?? null,
@@ -285,7 +285,7 @@ export class ExecuteSyncUseCase<T extends Record<string, unknown>> {
       // returned by the upsert. Sinks without the flag keep today's behavior.
       if (!this.sink.reprojectsOnNoop) {
         await this.recorder.recordItem({
-          syncRunId: runId,
+          integrationRunId: runId,
           entityType: input.subscription.domain,
           externalId: change.externalId,
           localId: null,
@@ -303,7 +303,7 @@ export class ExecuteSyncUseCase<T extends Record<string, unknown>> {
         input.provider,
       );
       await this.recorder.recordItem({
-        syncRunId: runId,
+        integrationRunId: runId,
         entityType: input.subscription.domain,
         externalId: change.externalId,
         localId: noopLocalId,
@@ -322,7 +322,7 @@ export class ExecuteSyncUseCase<T extends Record<string, unknown>> {
     );
 
     await this.recorder.recordItem({
-      syncRunId: runId,
+      integrationRunId: runId,
       entityType: input.subscription.domain,
       externalId: change.externalId,
       localId,

package/runtime/subsystems/{sync → integration}/index.ts

@@ -1,13 +1,13 @@
 /**
- * Sync subsystem — public API
+ * Integration subsystem — public API
  *
  * Slices landed so far:
  *   - SYNC-2 — protocols + DI tokens (#134)
  *   - SYNC-1 — Drizzle audit-table schemas (#148)
  *   - SYNC-3 — MemoryCursorStore (#149)
- *   - SYNC-5 — ExecuteSyncUseCase + DeepEqualDiffer + recorder/loopback protocols (#150)
+ *   - SYNC-5 — ExecuteIntegrationUseCase + DeepEqualDiffer + recorder/loopback protocols (#150)
  *   - SYNC-4 — Drizzle backends (#151)
- *   - SYNC-6 — SyncModule + MemoryRunRecorder + multi-tenancy opt-in (this slice)
+ *   - SYNC-6 — IntegrationModule + MemoryRunRecorder + multi-tenancy opt-in (this slice)
  *
  * Scaffold templates (SYNC-7) and docs/skills (SYNC-8) land in their own
  * PRs. See epic #60.
@@ -18,31 +18,31 @@ export type {
   Change,
   ChangeSource,
   IChangeSource,
-  SyncSubscriptionView,
-} from './sync-change-source.protocol';
+  IntegrationSubscriptionView,
+} from './integration-change-source.protocol';
 export type {
   CursorSnapshot,
   ICursorStore,
-} from './sync-cursor-store.protocol';
+} from './integration-cursor-store.protocol';
 export type {
   DiffResult,
   FieldDiff,
   FieldDiffValue,
   IFieldDiffer,
-} from './sync-field-diff.protocol';
+} from './integration-field-diff.protocol';
 export {
   FieldDiffSchema,
   FieldDiffValueSchema,
-} from './sync-field-diff.protocol';
-export type { ISyncSink } from './sync-sink.protocol';
+} from './integration-field-diff.protocol';
+export type { IIntegrationSink } from './integration-sink.protocol';
 export type {
   CompleteRunInput,
-  ISyncRunRecorder,
+  IIntegrationRunRecorder,
   RecordItemInput,
   StartRunInput,
-  SyncRunSummary,
-} from './sync-run-recorder.protocol';
-export type { ILoopbackFingerprintStore } from './sync-loopback.protocol';
+  IntegrationRunSummary,
+} from './integration-run-recorder.protocol';
+export type { ILoopbackFingerprintStore } from './integration-loopback.protocol';
 
 // DetectionConfig (#226-1) — Zod schema + inferred types; canonical source
 // of filter/mapping shape consumed by primitives + codegen YAML validator
@@ -68,10 +68,10 @@ export type {
   ChangeIterator,
   ChangeMiddleware,
   ComposeChangeMiddleware,
-} from './sync-middleware.protocol';
+} from './integration-middleware.protocol';
 
 // Loopback middleware factory (#226-5) — replaces the orchestrator's prior
-// `@Optional() SYNC_LOOPBACK_FINGERPRINT_STORE` branch. Consumers compose
+// `@Optional() INTEGRATION_LOOPBACK_FINGERPRINT_STORE` branch. Consumers compose
 // `createLoopbackMiddleware(store)` into their primitive's middleware chain.
 export { createLoopbackMiddleware } from './loopback.middleware';
 
@@ -100,42 +100,42 @@ export { buildChangeSource } from './build-change-source';
 
 // Tokens
 export {
-  SYNC_CHANGE_SOURCE,
-  SYNC_CURSOR_STORE,
-  SYNC_FIELD_DIFFER,
-  SYNC_MODULE_OPTIONS,
-  SYNC_MULTI_TENANT,
-  SYNC_RUN_RECORDER,
-  SYNC_SINK,
-} from './sync.tokens';
+  INTEGRATION_CHANGE_SOURCE,
+  INTEGRATION_CURSOR_STORE,
+  INTEGRATION_FIELD_DIFFER,
+  INTEGRATION_MODULE_OPTIONS,
+  INTEGRATION_MULTI_TENANT,
+  INTEGRATION_RUN_RECORDER,
+  INTEGRATION_SINK,
+} from './integration.tokens';
 
 // Errors + shared guards
-export { MissingTenantIdError, assertTenantId } from './sync-errors';
+export { MissingTenantIdError, assertTenantId } from './integration-errors';
 
 // Audit schemas (SYNC-1) — Drizzle pgTable declarations + row types + enums
 export {
-  syncSubscriptions,
-  syncRuns,
-  syncRunItems,
-  syncRunDirectionEnum,
-  syncRunActionEnum,
-  syncRunStatusEnum,
-  syncRunItemOperationEnum,
-  syncRunItemStatusEnum,
-} from './sync-audit.schema';
+  integrationSubscriptions,
+  integrationRuns,
+  integrationRunItems,
+  integrationRunDirectionEnum,
+  integrationRunActionEnum,
+  integrationRunStatusEnum,
+  integrationRunItemOperationEnum,
+  integrationRunItemStatusEnum,
+} from './integration-audit.schema';
 export type {
-  SyncSubscriptionRow,
-  SyncRunRow,
-  SyncRunItemRow,
-} from './sync-audit.schema';
+  IntegrationSubscriptionRow,
+  IntegrationRunRow,
+  IntegrationRunItemRow,
+} from './integration-audit.schema';
 
 // Memory backends (SYNC-3, SYNC-6) — test doubles
-export { MemoryCursorStore } from './sync-cursor-store.memory-backend';
+export { MemoryCursorStore } from './integration-cursor-store.memory-backend';
 export {
   MemoryRunRecorder,
   type MemoryRunRecord,
-  type MemorySyncSubscription,
-} from './sync-run-recorder.memory-backend';
+  type MemoryIntegrationSubscription,
+} from './integration-run-recorder.memory-backend';
 
 // Runtime (SYNC-5) — orchestrator + default differ
 export {
@@ -143,14 +143,14 @@ export {
   type DeepEqualDifferOptions,
 } from './deep-equal.differ';
 export {
-  ExecuteSyncUseCase,
-  type ExecuteSyncInput,
-  type ExecuteSyncResult,
-} from './execute-sync.use-case';
+  ExecuteIntegrationUseCase,
+  type ExecuteIntegrationInput,
+  type ExecuteIntegrationResult,
+} from './execute-integration.use-case';
 
 // Drizzle backends (SYNC-4)
-export { PostgresCursorStore } from './sync-cursor-store.drizzle-backend';
-export { DrizzleSyncRunRecorder } from './sync-run-recorder.drizzle-backend';
+export { PostgresCursorStore } from './integration-cursor-store.drizzle-backend';
+export { DrizzleIntegrationRunRecorder } from './integration-run-recorder.drizzle-backend';
 
 // Module (SYNC-6)
-export { SyncModule, type SyncModuleOptions } from './sync.module';
+export { IntegrationModule, type IntegrationModuleOptions } from './integration.module';