@pattern-stack/codegen 0.10.1 → 0.11.0

package/runtime/subsystems/auth/index.ts

@@ -9,25 +9,25 @@
  *   AuthController,
  *   ENCRYPTION_KEY,
  *   OAUTH_STATE_STORE,
- *   AUTH_INTEGRATION_READER,
- *   AUTH_INTEGRATION_TOKEN_WRITER,
- *   AUTH_INTEGRATION_GRANT_SINK,
+ *   AUTH_CONNECTION_READER,
+ *   AUTH_CONNECTION_TOKEN_WRITER,
+ *   AUTH_CONNECTION_GRANT_SINK,
  *   AUTH_USER_CONTEXT,
  *   STRATEGY_REGISTRY,
  *   AUTH_OPTIONS,
  *   OAuth2RefreshStrategy,
  *   withAuthRetry,
- *   IntegrationBrokenError,
+ *   ConnectionBrokenError,
  *   SessionExpiredError,
  *   OAuthStateError,
  *   type IAuthStrategy,
  *   type IEncryptionKey,
  *   type IOAuthStateStore,
  *   type OAuthStateRecord,
- *   type IIntegrationReader,
- *   type IIntegrationTokenWriter,
- *   type IIntegrationGrantSink,
- *   type IntegrationGrantInput,
+ *   type IConnectionReader,
+ *   type IConnectionTokenWriter,
+ *   type IConnectionGrantSink,
+ *   type ConnectionGrantInput,
  *   type IUserContext,
  *   type IProviderStrategy,
  *   type ProviderStrategyRegistry,
@@ -49,13 +49,13 @@ export type {
 } from './protocols/oauth-state-store';
 export { OAuthStateError } from './protocols/oauth-state-store';
 export type {
-  DecryptedIntegration,
-  IIntegrationReader,
-  IIntegrationTokenWriter,
-  IntegrationTokenUpdate,
-  IIntegrationGrantSink,
-  IntegrationGrantInput,
-} from './protocols/integration-store';
+  DecryptedConnection,
+  IConnectionReader,
+  IConnectionTokenWriter,
+  ConnectionTokenUpdate,
+  IConnectionGrantSink,
+  ConnectionGrantInput,
+} from './protocols/connection-store';
 export type { IUserContext } from './protocols/user-context';
 export type {
   IProviderStrategy,
@@ -67,9 +67,9 @@ export type {
 export {
   ENCRYPTION_KEY,
   OAUTH_STATE_STORE,
-  AUTH_INTEGRATION_READER,
-  AUTH_INTEGRATION_TOKEN_WRITER,
-  AUTH_INTEGRATION_GRANT_SINK,
+  AUTH_CONNECTION_READER,
+  AUTH_CONNECTION_TOKEN_WRITER,
+  AUTH_CONNECTION_GRANT_SINK,
   AUTH_USER_CONTEXT,
   STRATEGY_REGISTRY,
   AUTH_OPTIONS,
@@ -83,7 +83,7 @@ export {
   type FetchLike,
 } from './runtime/oauth2-refresh.strategy';
 export { withAuthRetry, type WithAuthRetryOptions } from './runtime/with-auth-retry';
-export { IntegrationBrokenError } from './runtime/integration-broken.error';
+export { ConnectionBrokenError } from './runtime/connection-broken.error';
 export {
   SessionExpiredError,
   isSessionExpiredError,

package/runtime/subsystems/auth/protocols/auth-strategy.ts

@@ -1,7 +1,7 @@
 /**
  * Auth subsystem — `IAuthStrategy` port.
  *
- * The credentials-resolution seam used by every integration adapter. Adapters
+ * The credentials-resolution seam used by every connection adapter. Adapters
  * depend on this interface; concrete strategies (SalesforceAuthStrategy,
  * HubSpotAuthStrategy, future Gmail/Calendar) typically extend the
  * `OAuth2RefreshStrategy` template-method base in `../runtime/`.
@@ -35,12 +35,12 @@ export interface AuthResolveOptions {
 }
 
 /**
- * Auth-strategy contract shared by every integration adapter. Implementations
+ * Auth-strategy contract shared by every connection adapter. Implementations
  * typically extend `OAuth2RefreshStrategy` and override four small hooks.
  */
 export interface IAuthStrategy {
   resolve(
-    integrationId: string,
+    connectionId: string,
     opts?: AuthResolveOptions,
   ): Promise<AuthCredentials>;
 }

package/runtime/subsystems/auth/protocols/{integration-store.ts → connection-store.ts}

@@ -1,26 +1,26 @@
 /**
- * Auth subsystem — integration storage ports.
+ * Auth subsystem — connection storage ports.
  *
- * `OAuth2RefreshStrategy` reads decrypted integration rows and persists
+ * `OAuth2RefreshStrategy` reads decrypted connection rows and persists
  * refreshed tokens. The subsystem doesn't care what entity framework stores
  * those rows — consumers implement these narrow ports against whatever
- * `integrations` table their app uses.
+ * `connections` table their app uses.
  *
  * In the extraction-source app both ports are satisfied by a
- * pair of thin adapters over `IntegrationService` + `RefreshIntegrationUseCase`.
+ * pair of thin adapters over `ConnectionService` + `RefreshConnectionUseCase`.
  * The codegen-patterns `examples/auth-integrations/` starter (separate PR)
- * ships a canonical `integration.yaml` whose generated service + use case
+ * ships a canonical `connection.yaml` whose generated service + use case
  * satisfy the shape out of the box.
  */
 
 /**
- * An integration row with its secrets decrypted and ready to use.
+ * An connection row with its secrets decrypted and ready to use.
  *
  * Consumers produce this shape from their own storage by passing stored
  * ciphertexts through `IEncryptionKey.decrypt`. The subsystem never sees
  * the ciphertext form.
  */
-export interface DecryptedIntegration {
+export interface DecryptedConnection {
   id: string;
   /** Provider slug — must match the strategy's `provider`. */
   provider: string;
@@ -35,13 +35,13 @@ export interface DecryptedIntegration {
 }
 
 /**
- * Read port — fetches a decrypted integration by id.
+ * Read port — fetches a decrypted connection by id.
  *
  * Adapters typically wrap a service/repo call that does the decryption
  * internally. `OAuth2RefreshStrategy.resolve()` calls this on every invocation.
  */
-export interface IIntegrationReader {
-  findByIdDecrypted(integrationId: string): Promise<DecryptedIntegration | null>;
+export interface IConnectionReader {
+  findByIdDecrypted(connectionId: string): Promise<DecryptedConnection | null>;
 }
 
 /**
@@ -54,15 +54,15 @@ export interface IIntegrationReader {
  * `refreshToken` semantics: `undefined` means "provider did not rotate; keep
  * existing ciphertext". A rotated token comes through as a string.
  */
-export interface IntegrationTokenUpdate {
-  integrationId: string;
+export interface ConnectionTokenUpdate {
+  connectionId: string;
   accessToken: string;
   refreshToken?: string;
   expiresAt: Date;
 }
 
-export interface IIntegrationTokenWriter {
-  persistRefresh(update: IntegrationTokenUpdate): Promise<void>;
+export interface IConnectionTokenWriter {
+  persistRefresh(update: ConnectionTokenUpdate): Promise<void>;
 }
 
 /**
@@ -71,10 +71,10 @@ export interface IIntegrationTokenWriter {
  * re-connected an existing one).
  *
  * `AuthController.callback` invokes this after `IProviderStrategy.exchangeCodeForTokens`.
- * The subsystem itself never imports a concrete `IntegrationsService` — the
+ * The subsystem itself never imports a concrete `ConnectionsService` — the
  * consumer's `auth-integrations` starter (or any equivalent) adapts this
  * port. Keeps the auth subsystem standalone: a non-codegen consumer can
- * satisfy the port against its own integrations storage.
+ * satisfy the port against its own connections storage.
  *
  * Semantics:
  *   - Upserts on `(userId, provider)`. Repeated grants for the same pair
@@ -85,7 +85,7 @@ export interface IIntegrationTokenWriter {
  *     them (e.g. some providers omit `expires_in`; not every flow returns
  *     a refresh token on first grant).
  */
-export interface IntegrationGrantInput {
+export interface ConnectionGrantInput {
   userId: string;
   /** Provider slug — must match the strategy's `provider`. */
   provider: string;
@@ -98,6 +98,6 @@ export interface IntegrationGrantInput {
   providerMetadata?: Record<string, unknown>;
 }
 
-export interface IIntegrationGrantSink {
-  createOrUpdateFromOAuthGrant(input: IntegrationGrantInput): Promise<void>;
+export interface IConnectionGrantSink {
+  createOrUpdateFromOAuthGrant(input: ConnectionGrantInput): Promise<void>;
 }

package/runtime/subsystems/auth/protocols/provider-strategy.ts

@@ -18,9 +18,9 @@
  * and dispatches by slug.
  *
  * **Naming convention:** interfaces that describe behavioral ports use the
- * `I` prefix (`IProviderStrategy`, `IIntegrationReader`, `IUserContext`,
+ * `I` prefix (`IProviderStrategy`, `IConnectionReader`, `IUserContext`,
  * `IOAuthStateStore`, `IEncryptionKey`). Plain data types / DTOs (e.g.
- * `ExchangedTokens`, `DecryptedIntegration`, `IntegrationGrantInput`) do
+ * `ExchangedTokens`, `DecryptedConnection`, `ConnectionGrantInput`) do
  * not. Abstract template-method classes (e.g. `OAuth2RefreshStrategy`) also
  * do not — the `I` is for interfaces only.
  */

package/runtime/subsystems/auth/runtime/{integration-broken.error.ts → connection-broken.error.ts}

@@ -2,20 +2,20 @@
  * Thrown when an OAuth2 provider returns `400 invalid_grant`/`invalid_token`
  * on refresh — the refresh token itself is dead (user revoked, org
  * deactivated, token expired beyond the provider's rotation window). The
- * integration should be marked broken so background sync stops picking it
+ * connection should be marked broken so background sync stops picking it
  * up; the user re-initiates OAuth.
  *
  * Shared across every OAuth2 strategy.
  */
-export class IntegrationBrokenError extends Error {
+export class ConnectionBrokenError extends Error {
   constructor(
-    readonly integrationId: string,
+    readonly connectionId: string,
     readonly errorCode: string,
     readonly errorDescription: string,
   ) {
     super(
-      `Integration ${integrationId} broken: ${errorCode} - ${errorDescription}`,
+      `Connection ${connectionId} broken: ${errorCode} - ${errorDescription}`,
     );
-    this.name = 'IntegrationBrokenError';
+    this.name = 'ConnectionBrokenError';
   }
 }

package/runtime/subsystems/auth/runtime/oauth2-refresh.strategy.ts

@@ -8,18 +8,18 @@
  * later" evidence.
  *
  * Subclass contract:
- *   - `provider`                — slug matched against `integrations.provider`
+ *   - `provider`                — slug matched against `connections.provider`
  *   - `defaultExpiresInSec`     — fallback when refresh response omits `expires_in`
  *   - `tokenEndpoint()`         — URL to POST the refresh grant
  *   - `refreshBodyExtras()`     — provider-specific body params
  *   - `parseRefreshResponse()`  — raw JSON → ParsedRefreshResponse
  *   - `buildCredentials()`      — stored or freshly-refreshed access token +
- *                                 integration + optional raw refresh response
+ *                                 connection + optional raw refresh response
  *                                 → provider credentials
  *
  * Base handles: expiry check w/ 5-min safety window, `forceRefresh` escape
  * hatch, POST form-urlencoded body, OAuth2 error mapping to
- * `IntegrationBrokenError`, refresh-token rotation persistence, fetch +
+ * `ConnectionBrokenError`, refresh-token rotation persistence, fetch +
  * clock injection for tests.
  */
 import type {
@@ -28,11 +28,11 @@ import type {
   IAuthStrategy,
 } from '../protocols/auth-strategy';
 import type {
-  DecryptedIntegration,
-  IIntegrationReader,
-  IIntegrationTokenWriter,
-} from '../protocols/integration-store';
-import { IntegrationBrokenError } from './integration-broken.error';
+  DecryptedConnection,
+  IConnectionReader,
+  IConnectionTokenWriter,
+} from '../protocols/connection-store';
+import { ConnectionBrokenError } from './connection-broken.error';
 
 export type FetchLike = (
   input: string | URL | Request,
@@ -43,8 +43,8 @@ export type FetchLike = (
 const REFRESH_SAFETY_MS = 5 * 60 * 1000;
 
 export interface OAuth2RefreshStrategyOptions {
-  integrationReader: IIntegrationReader;
-  tokenWriter: IIntegrationTokenWriter;
+  connectionReader: IConnectionReader;
+  tokenWriter: IConnectionTokenWriter;
   /** Injectable fetch for tests. Defaults to the global `fetch`. */
   fetch?: FetchLike;
   /** Injectable clock for tests. Defaults to `Date.now`. */
@@ -66,65 +66,65 @@ export abstract class OAuth2RefreshStrategy implements IAuthStrategy {
   protected abstract readonly provider: string;
   protected abstract readonly defaultExpiresInSec: number;
 
-  protected readonly integrationReader: IIntegrationReader;
-  protected readonly tokenWriter: IIntegrationTokenWriter;
+  protected readonly connectionReader: IConnectionReader;
+  protected readonly tokenWriter: IConnectionTokenWriter;
   protected readonly fetchImpl: FetchLike;
   protected readonly now: () => number;
 
   constructor(opts: OAuth2RefreshStrategyOptions) {
-    this.integrationReader = opts.integrationReader;
+    this.connectionReader = opts.connectionReader;
     this.tokenWriter = opts.tokenWriter;
     this.fetchImpl = opts.fetch ?? fetch;
     this.now = opts.now ?? Date.now;
   }
 
   async resolve(
-    integrationId: string,
+    connectionId: string,
     opts: AuthResolveOptions = {},
   ): Promise<AuthCredentials> {
-    const integration =
-      await this.integrationReader.findByIdDecrypted(integrationId);
-    if (!integration) {
-      throw new Error(`Integration ${integrationId} not found`);
+    const connection =
+      await this.connectionReader.findByIdDecrypted(connectionId);
+    if (!connection) {
+      throw new Error(`Connection ${connectionId} not found`);
     }
-    if (integration.provider !== this.provider) {
+    if (connection.provider !== this.provider) {
       throw new Error(
-        `${this.constructor.name} called for non-${this.provider} integration ${integrationId} (provider=${integration.provider})`,
+        `${this.constructor.name} called for non-${this.provider} connection ${connectionId} (provider=${connection.provider})`,
       );
     }
 
     const needsRefresh =
       opts.forceRefresh ||
-      this.isExpiring(integration.expiresAt) ||
-      !integration.accessToken;
+      this.isExpiring(connection.expiresAt) ||
+      !connection.accessToken;
 
     if (!needsRefresh) {
-      return this.buildCredentials(integration.accessToken, integration);
+      return this.buildCredentials(connection.accessToken, connection);
     }
 
-    if (!integration.refreshToken) {
-      throw new IntegrationBrokenError(
-        integrationId,
+    if (!connection.refreshToken) {
+      throw new ConnectionBrokenError(
+        connectionId,
         'no_refresh_token',
-        'Integration has no refresh token; user must reconnect',
+        'Connection has no refresh token; user must reconnect',
       );
     }
 
     const { parsed, raw } = await this.executeRefresh(
-      integrationId,
-      integration.refreshToken,
+      connectionId,
+      connection.refreshToken,
     );
     const newExpiresAt = new Date(
       this.now() + (parsed.expiresInSec ?? this.defaultExpiresInSec) * 1000,
     );
     await this.tokenWriter.persistRefresh({
-      integrationId,
+      connectionId,
       accessToken: parsed.accessToken,
       refreshToken: parsed.refreshToken ?? undefined,
       expiresAt: newExpiresAt,
     });
 
-    return this.buildCredentials(parsed.accessToken, integration, raw);
+    return this.buildCredentials(parsed.accessToken, connection, raw);
   }
 
   protected abstract tokenEndpoint(): string;
@@ -132,12 +132,12 @@ export abstract class OAuth2RefreshStrategy implements IAuthStrategy {
   protected abstract parseRefreshResponse(raw: unknown): ParsedRefreshResponse;
   protected abstract buildCredentials(
     accessToken: string,
-    integration: DecryptedIntegration,
+    connection: DecryptedConnection,
     refreshRaw?: unknown,
   ): AuthCredentials;
 
   private async executeRefresh(
-    integrationId: string,
+    connectionId: string,
     refreshToken: string,
   ): Promise<{ parsed: ParsedRefreshResponse; raw: unknown }> {
     const body = new URLSearchParams({
@@ -160,8 +160,8 @@ export abstract class OAuth2RefreshStrategy implements IAuthStrategy {
         response.status === 400 &&
         (err.error === 'invalid_grant' || err.error === 'invalid_token')
       ) {
-        throw new IntegrationBrokenError(
-          integrationId,
+        throw new ConnectionBrokenError(
+          connectionId,
           err.error ?? 'invalid_grant',
           err.error_description ?? err.message ?? 'refresh token rejected',
         );

package/runtime/subsystems/auth/runtime/with-auth-retry.ts

@@ -33,18 +33,18 @@ export interface WithAuthRetryOptions {
 
 export async function withAuthRetry<T>(
   authStrategy: IAuthStrategy,
-  integrationId: string,
+  connectionId: string,
   op: (credentials: AuthCredentials) => Promise<T>,
   options: WithAuthRetryOptions = {},
 ): Promise<T> {
   const classify = options.isSessionExpired ?? isSessionExpiredError;
 
-  let creds = await authStrategy.resolve(integrationId);
+  let creds = await authStrategy.resolve(connectionId);
   try {
     return await op(creds);
   } catch (e) {
     if (!classify(e)) throw e;
-    creds = await authStrategy.resolve(integrationId, { forceRefresh: true });
+    creds = await authStrategy.resolve(connectionId, { forceRefresh: true });
     return op(creds);
   }
 }

package/runtime/subsystems/index.ts

@@ -46,7 +46,7 @@ export type {
   PoolStatusCount,
   JobRunFailure,
   StatusHistogram,
-  SyncRunSummary,
+  IntegrationRunSummary,
   CursorSnapshot,
 } from './observability';
 
@@ -54,9 +54,9 @@ export type {
 export {
   ENCRYPTION_KEY,
   OAUTH_STATE_STORE,
-  AUTH_INTEGRATION_READER,
-  AUTH_INTEGRATION_TOKEN_WRITER,
-  AUTH_INTEGRATION_GRANT_SINK,
+  AUTH_CONNECTION_READER,
+  AUTH_CONNECTION_TOKEN_WRITER,
+  AUTH_CONNECTION_GRANT_SINK,
   AUTH_USER_CONTEXT,
   STRATEGY_REGISTRY,
   AUTH_OPTIONS,
@@ -64,7 +64,7 @@ export {
   AuthController,
   OAuth2RefreshStrategy,
   withAuthRetry,
-  IntegrationBrokenError,
+  ConnectionBrokenError,
   SessionExpiredError,
   isSessionExpiredError,
   OAuthStateError,
@@ -77,19 +77,19 @@ export type {
   IAuthStrategy,
   IEncryptionKey,
   IOAuthStateStore,
-  IIntegrationReader,
-  IIntegrationTokenWriter,
-  IIntegrationGrantSink,
-  IntegrationGrantInput,
+  IConnectionReader,
+  IConnectionTokenWriter,
+  IConnectionGrantSink,
+  ConnectionGrantInput,
   IUserContext,
   IProviderStrategy,
   ProviderStrategyRegistry,
   ExchangedTokens,
   AuthCredentials,
   AuthResolveOptions,
-  DecryptedIntegration,
+  DecryptedConnection,
   OAuthStateRecord,
-  IntegrationTokenUpdate,
+  ConnectionTokenUpdate,
   ParsedRefreshResponse,
   AuthOAuthState,
 } from './auth';

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