@pattern-stack/codegen 0.10.1 → 0.12.0

package/runtime/subsystems/integration/entity-change-source-registry.memory.ts

@@ -0,0 +1,40 @@
+/**
+ * Integration subsystem — in-memory entity-change-source registry
+ *
+ * Default `IEntityChangeSourceRegistry` backed by a `Map<entityName, source>`.
+ * Track D's codegen-emitted aggregator folds per-provider adapter
+ * contributions into one of these and binds it under
+ * `ENTITY_CHANGE_SOURCE_REGISTRY` (RFC-0001 §3); tests and simple consumers
+ * construct it directly.
+ *
+ * See {@link ./entity-change-source-registry.protocol} for the contract and
+ * #336 for scope.
+ */
+
+import type { IChangeSource } from './integration-change-source.protocol';
+import {
+  type IEntityChangeSourceRegistry,
+  UnknownEntityError,
+} from './entity-change-source-registry.protocol';
+
+export class MemoryEntityChangeSourceRegistry
+  implements IEntityChangeSourceRegistry
+{
+  constructor(private readonly sources: Map<string, IChangeSource<unknown>>) {}
+
+  get<T = unknown>(name: string): IChangeSource<T> {
+    const source = this.sources.get(name);
+    if (!source) {
+      throw new UnknownEntityError(name, [...this.sources.keys()]);
+    }
+    return source as IChangeSource<T>;
+  }
+
+  has(name: string): boolean {
+    return this.sources.has(name);
+  }
+
+  entities(): readonly string[] {
+    return [...this.sources.keys()];
+  }
+}

package/runtime/subsystems/integration/entity-change-source-registry.protocol.ts

@@ -0,0 +1,59 @@
+/**
+ * Integration subsystem — entity-keyed change-source registry (port)
+ *
+ * `IEntityChangeSourceRegistry` resolves an `IChangeSource<T>` by entity name.
+ * It generalizes today's per-entity DI tokens (`ACCOUNT_POLL_FETCH_REGISTRY`,
+ * `CONTACT_POLL_FETCH_REGISTRY`, …) into one entity-keyed registry, so the L3
+ * composing port (`<Surface>Port`, Track C C6) can be entity-agnostic at the
+ * type level instead of enumerating entities (epic #328 locked decision #5).
+ *
+ * This lives in L1 (the integration subsystem) rather than in a per-surface
+ * package because the same shape applies across surfaces — CRM (`account`,
+ * `contact`, `deal`), Mail (`email`, `thread`, `label`), Transcript
+ * (`transcript`, `speaker`, `utterance`), Meeting (`meeting`, `attendee`).
+ * Cross-surface plumbing belongs at L1 (epic #328 locked decision #6).
+ *
+ * Scope (Track C · C7): this is purely the L1 type + memory impl. Codegen does
+ * NOT yet emit this registry, and the existing per-entity tokens keep emitting
+ * unchanged — the retarget (and the per-entity-token deprecation) is Track D
+ * D3/D4 (RFC-0001 §3/§8).
+ *
+ * See #336 (this issue), #328 (parent epic), RFC-0001 §3 (the registry
+ * contract Track D emits the wiring for).
+ */
+
+import type { IChangeSource } from './integration-change-source.protocol';
+
+/**
+ * Entity-keyed resolver for change sources. The orchestrator (and the L3
+ * surface port) consume this, agnostic to whether a source came from a
+ * hand-written adapter or a configured `PollChangeSource<T>`.
+ */
+export interface IEntityChangeSourceRegistry {
+  /**
+   * Resolve a change source for a given entity name.
+   * Throws {@link UnknownEntityError} if the entity isn't registered.
+   */
+  get<T = unknown>(entityName: string): IChangeSource<T>;
+
+  /** True if the entity is registered. */
+  has(entityName: string): boolean;
+
+  /** List all entity names this registry serves. */
+  entities(): readonly string[];
+}
+
+/**
+ * Thrown by {@link IEntityChangeSourceRegistry.get} when no source is
+ * registered for the requested entity. The message enumerates the available
+ * entities so a misconfiguration (typo'd entity name, missing adapter
+ * contribution) is diagnosable from the error alone.
+ */
+export class UnknownEntityError extends Error {
+  constructor(entity: string, available: readonly string[]) {
+    super(
+      `No change source registered for entity '${entity}'. Available: ${available.join(', ')}`,
+    );
+    this.name = 'UnknownEntityError';
+  }
+}

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,39 @@ 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';
+
+// Entity-keyed change-source registry (C7, #336) — L1 protocol + memory impl.
+// Generalizes per-entity `<ENTITY>_POLL_FETCH_REGISTRY` tokens into one
+// entity-keyed registry so the L3 surface port (C6) is entity-agnostic. Codegen
+// retarget to emit it is Track D D3/D4 (RFC-0001 §3).
+export type { IEntityChangeSourceRegistry } from './entity-change-source-registry.protocol';
+export { UnknownEntityError } from './entity-change-source-registry.protocol';
+export { MemoryEntityChangeSourceRegistry } from './entity-change-source-registry.memory';
 
 // DetectionConfig (#226-1) — Zod schema + inferred types; canonical source
 // of filter/mapping shape consumed by primitives + codegen YAML validator
@@ -68,10 +76,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 +108,43 @@ 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';
+  ENTITY_CHANGE_SOURCE_REGISTRY,
+  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 +152,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';