@pattern-stack/codegen 0.10.1 → 0.11.0

package/examples/auth-integrations/runtime/connections/oauth/use-cases/list-user-connections.use-case.ts

@@ -0,0 +1,21 @@
+import { Injectable } from '@nestjs/common';
+import { ConnectionService } from '../../connection.service';
+import type { Connection } from '../../connection.entity';
+
+/**
+ * Lists a user's connections newest-first. Used by the settings page
+ * (`GET /connections`) and any "which providers are connected?" UI.
+ *
+ * Returns rows with ciphertexts intact — callers should NOT pass these
+ * to the frontend. Use `ConnectionsService.listByUser` if you need
+ * the consumer-facing facade behavior (which strips ciphertexts before
+ * returning).
+ */
+@Injectable()
+export class ListUserConnectionsUseCase {
+  constructor(private readonly connections: ConnectionService) {}
+
+  async execute(userId: string): Promise<Connection[]> {
+    return this.connections.findByUserId(userId);
+  }
+}

package/examples/auth-integrations/runtime/connections/oauth/use-cases/mark-connection-requires-reauth.use-case.ts

@@ -0,0 +1,21 @@
+import { Injectable } from '@nestjs/common';
+import { ConnectionService } from '../../connection.service';
+import type { Connection } from '../../connection.entity';
+
+/**
+ * Flips an connection's status to `requires_reauth`. Called when the
+ * refresh path raises `ConnectionBrokenError` (refresh token rejected,
+ * scopes revoked, etc.) — see `OAuth2RefreshStrategy` + `withAuthRetry`.
+ *
+ * Idempotent: calling on an already-broken row is a no-op write.
+ */
+@Injectable()
+export class MarkConnectionRequiresReauthUseCase {
+  constructor(private readonly connections: ConnectionService) {}
+
+  async execute(connectionId: string): Promise<Connection> {
+    return this.connections.update(connectionId, {
+      status: 'requires_reauth',
+    });
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",

package/runtime/base-classes/index.ts

@@ -32,24 +32,24 @@ export type { EventCategory } from './lifecycle-events';
 export { BaseFindByIdUseCase, BaseListUseCase } from './base-read-use-cases';
 export type { IFindByIdService, IListService } from './base-read-use-cases';
 
-// Sync upsert config (consumed by SyncedEntityRepository + JunctionSyncRepository)
-export type { SyncUpsertConfig, SyncFkResolver } from './sync-upsert-config';
+// Integration upsert config (consumed by IntegratedEntityRepository + JunctionIntegrationRepository)
+export type { IntegrationUpsertConfig, IntegrationFkResolver } from './integration-upsert-config';
 
 // Family-specific repository base classes
-export { SyncedEntityRepository } from './synced-entity-repository';
+export { IntegratedEntityRepository } from './integrated-entity-repository';
 export {
-  JunctionSyncRepository,
+  JunctionIntegrationRepository,
   buildCompositeExternalId,
   parseCompositeExternalId,
-} from './junction-sync-repository';
-export type { JunctionSyncConfig } from './junction-sync-repository';
+} from './junction-integration-repository';
+export type { JunctionIntegrationConfig } from './junction-integration-repository';
 export { ActivityEntityRepository } from './activity-entity-repository';
 export { MetadataEntityRepository } from './metadata-entity-repository';
 export { KnowledgeEntityRepository } from './knowledge-entity-repository';
 
 // Family-specific service base classes
-export { SyncedEntityService } from './synced-entity-service';
-export type { ISyncedEntityRepository } from './synced-entity-service';
+export { IntegratedEntityService } from './integrated-entity-service';
+export type { IIntegratedEntityRepository } from './integrated-entity-service';
 export { ActivityEntityService } from './activity-entity-service';
 export type { IActivityEntityRepository } from './activity-entity-service';
 export { MetadataEntityService } from './metadata-entity-service';

package/runtime/base-classes/{synced-entity-repository.ts → integrated-entity-repository.ts}

@@ -1,31 +1,31 @@
 /**
- * SyncedEntityRepository<TEntity, TSyncWrite, TSyncProjection>
+ * IntegratedEntityRepository<TEntity, TIntegrationWrite, TIntegrationProjection>
  *
- * Family-specific base for Synced entities (contacts, accounts, opportunities).
- * Adds external ID lookups, user-scoped queries, and the generic inbound-sync
+ * Family-specific base for Integrated entities (contacts, accounts, opportunities).
+ * Adds external ID lookups, user-scoped queries, and the generic inbound-integration
  * write surface (canonical→Drizzle upsert + provider-scoped FK resolution +
- * EAV dual-write seam), driven by the concrete repo's `syncConfig`.
+ * EAV dual-write seam), driven by the concrete repo's `integrationConfig`.
  *
  * The type params default so pre-existing single-param subclasses keep
- * compiling; `pattern: Synced` repos declare all three plus `syncConfig`.
+ * compiling; `pattern: Integrated` repos declare all three plus `integrationConfig`.
  */
 import { and, eq, inArray } from 'drizzle-orm';
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 import type { PgTableWithColumns } from 'drizzle-orm/pg-core';
 import type { DrizzleTx } from '../types/drizzle';
 import { BaseRepository } from './base-repository';
-import type { SyncUpsertConfig, SyncFkResolver } from './sync-upsert-config';
+import type { IntegrationUpsertConfig, IntegrationFkResolver } from './integration-upsert-config';
 
-export abstract class SyncedEntityRepository<
+export abstract class IntegratedEntityRepository<
   TEntity,
-  TSyncWrite = Partial<TEntity>,
-  TSyncProjection = TEntity,
+  TIntegrationWrite = Partial<TEntity>,
+  TIntegrationProjection = TEntity,
 > extends BaseRepository<TEntity> {
   /**
-   * Declarative sync write surface. Concrete (`pattern: Synced`) repositories
+   * Declarative integration write surface. Concrete (`pattern: Integrated`) repositories
    * declare this — the template emits it from the entity's fields + FKs.
    */
-  protected abstract readonly syncConfig: SyncUpsertConfig;
+  protected abstract readonly integrationConfig: IntegrationUpsertConfig;
 
   /**
    * Find a single entity by its external CRM identifier.
@@ -57,21 +57,21 @@ export abstract class SyncedEntityRepository<
   }
 
   // ==========================================================================
-  // Inbound sync (#374) — canonical→Drizzle write + provider-scoped FK
+  // Inbound integration (#374) — canonical→Drizzle write + provider-scoped FK
   // resolution + EAV dual-write seam, all inside a SINGLE transaction.
-  // Driven entirely by `this.syncConfig`; the per-entity shape lives there.
+  // Driven entirely by `this.integrationConfig`; the per-entity shape lives there.
   // ==========================================================================
 
   /**
    * Upsert ONE entity by its `(provider, externalId)` identity, in a single
    * transaction:
-   *   1. resolve each `syncConfig.fkResolvers` FK (provider-scoped). Strict
+   *   1. resolve each `integrationConfig.fkResolvers` FK (provider-scoped). Strict
    *      resolvers throw on unresolved; non-strict leave the column null.
    *   2. insert-or-update the canonical columns via `onConflictDoUpdate` on the
    *      `conflictTarget`. Resolved FKs are only written into `set` when
    *      non-null this run (no-clobber).
    *   3. EAV dual-write of `write.fields` via `writeCustomFields` when
-   *      `syncConfig.eav` and the bag is non-empty (same tx).
+   *      `integrationConfig.eav` and the bag is non-empty (same tx).
    *
    * Idempotent: a second call with the same identity updates in place. Returns
    * the canonical projection (so the orchestrator records `local_id`).
@@ -80,15 +80,15 @@ export abstract class SyncedEntityRepository<
    * @param provider  adapter/provider label persisted + used to scope lookups
    * @param tx        optional outer transaction; when omitted we open our own
    */
-  async syncUpsertOne(
-    write: TSyncWrite,
+  async integrationUpsertOne(
+    write: TIntegrationWrite,
     provider: string,
     tx?: DrizzleTx,
-  ): Promise<TSyncProjection> {
-    const cfg = this.syncConfig;
+  ): Promise<TIntegrationProjection> {
+    const cfg = this.integrationConfig;
     const w = write as Record<string, unknown>;
 
-    const run = async (db: DrizzleTx): Promise<TSyncProjection> => {
+    const run = async (db: DrizzleTx): Promise<TIntegrationProjection> => {
       // 1. FK resolution (provider-scoped). Strict → throw; else opportunistic null.
       const resolvedFks: Record<string, string | null> = {};
       for (const fk of cfg.fkResolvers) {
@@ -155,7 +155,7 @@ export abstract class SyncedEntityRepository<
   async findByExternalIdProjected(
     externalId: string,
     provider: string,
-  ): Promise<TSyncProjection | null> {
+  ): Promise<TIntegrationProjection | null> {
     const rows = await this.db
       .select()
       .from(this.table)
@@ -171,7 +171,7 @@ export abstract class SyncedEntityRepository<
   }
 
   /**
-   * Sync "delete" by external id, provider-scoped. When `softDelete: true`,
+   * Integration "delete" by external id, provider-scoped. When `softDelete: true`,
    * sets `deletedAt`. When `softDelete: false`, tombstone-by-clearing: null out
    * `external_id`/`provider` so the row no longer matches future inbound
    * changes while preserving local-id references. Returns `{ id }` or `null`.
@@ -182,7 +182,7 @@ export abstract class SyncedEntityRepository<
     tx?: DrizzleTx,
   ): Promise<{ id: string } | null> {
     const db = this.runner(tx);
-    const set = this.syncConfig.softDelete
+    const set = this.integrationConfig.softDelete
       ? { deletedAt: new Date(), updatedAt: new Date() }
       : { externalId: null, provider: null, updatedAt: new Date() };
     const rows = await db
@@ -199,20 +199,20 @@ export abstract class SyncedEntityRepository<
   }
 
   /**
-   * Batch sync upsert — concretizes the former abstract stub. Delegates to
-   * `syncUpsertOne` per input inside one transaction. Inputs are raw partial
+   * Batch integration upsert — concretizes the former abstract stub. Delegates to
+   * `integrationUpsertOne` per input inside one transaction. Inputs are raw partial
    * rows: provider is read from each input's own `provider` column; rows
    * missing `externalId`/`provider` are skipped.
    */
-  async syncUpsert(inputs: Array<Partial<TEntity>>): Promise<TEntity[]> {
+  async integrationUpsert(inputs: Array<Partial<TEntity>>): Promise<TEntity[]> {
     if (inputs.length === 0) return [];
     return this.db.transaction(async (tx) => {
       const out: TEntity[] = [];
       for (const input of inputs) {
         const rec = input as Record<string, unknown>;
         if (!rec['externalId'] || !rec['provider']) continue;
-        const proj = await this.syncUpsertOne(
-          input as unknown as TSyncWrite,
+        const proj = await this.integrationUpsertOne(
+          input as unknown as TIntegrationWrite,
           rec['provider'] as string,
           tx,
         );
@@ -230,14 +230,14 @@ export abstract class SyncedEntityRepository<
 
   /**
    * Project a raw row to the canonical differ shape — a generic pick over
-   * `syncConfig.projectionColumns`. Override only for synthesized projections
+   * `integrationConfig.projectionColumns`. Override only for synthesized projections
    * (e.g. junctions); entities use this verbatim.
    */
-  protected toProjection(row: TEntity): TSyncProjection {
+  protected toProjection(row: TEntity): TIntegrationProjection {
     const r = row as Record<string, unknown>;
     const out: Record<string, unknown> = {};
-    for (const col of this.syncConfig.projectionColumns) out[col] = r[col];
-    return out as TSyncProjection;
+    for (const col of this.integrationConfig.projectionColumns) out[col] = r[col];
+    return out as TIntegrationProjection;
   }
 
   /**
@@ -263,7 +263,7 @@ export abstract class SyncedEntityRepository<
    */
   private async resolveFk(
     db: DrizzleTx,
-    fk: SyncFkResolver,
+    fk: IntegrationFkResolver,
     rawExternalId: unknown,
     provider: string,
   ): Promise<string | null> {
@@ -271,7 +271,7 @@ export abstract class SyncedEntityRepository<
     if (!parentExternalId) {
       if (fk.strict) {
         throw new Error(
-          `${this.constructor.name}.syncUpsertOne: missing required parent ` +
+          `${this.constructor.name}.integrationUpsertOne: missing required parent ` +
             `external id for '${fk.column}' (writeKey '${fk.writeKey}')`,
         );
       }
@@ -293,9 +293,9 @@ export abstract class SyncedEntityRepository<
     const id = (rows[0]?.id as string | undefined) ?? null;
     if (id === null && fk.strict) {
       throw new Error(
-        `${this.constructor.name}.syncUpsertOne: unresolved parent ` +
+        `${this.constructor.name}.integrationUpsertOne: unresolved parent ` +
           `'${parentExternalId}' (provider '${provider}') for '${fk.column}' — ` +
-          `parent not synced yet`,
+          `parent not integrated yet`,
       );
     }
     return id;

package/runtime/base-classes/{synced-entity-service.ts → integrated-entity-service.ts}

@@ -1,22 +1,22 @@
 /**
- * SyncedEntityService<TRepo, TEntity>
+ * IntegratedEntityService<TRepo, TEntity>
  *
- * Family-specific base service for Synced entities.
+ * Family-specific base service for Integrated entities.
  * Delegates to a CRM repository that provides external ID lookups
  * and user-scoped queries.
  */
 import { BaseService, type IBaseRepository } from './base-service';
 
-export interface ISyncedEntityRepository<TEntity> extends IBaseRepository<TEntity> {
+export interface IIntegratedEntityRepository<TEntity> extends IBaseRepository<TEntity> {
   findByExternalId(externalId: string): Promise<TEntity | null>;
   findManyByExternalIds(externalIds: string[]): Promise<TEntity[]>;
   findAllByUserId(userId: string): Promise<TEntity[]>;
   findVisibleByUserId(userId: string): Promise<TEntity[]>;
-  syncUpsert(inputs: Array<Partial<TEntity>>): Promise<TEntity[]>;
+  integrationUpsert(inputs: Array<Partial<TEntity>>): Promise<TEntity[]>;
 }
 
-export abstract class SyncedEntityService<
-  TRepo extends ISyncedEntityRepository<TEntity>,
+export abstract class IntegratedEntityService<
+  TRepo extends IIntegratedEntityRepository<TEntity>,
   TEntity,
 > extends BaseService<TRepo, TEntity> {
   /**

package/runtime/base-classes/{sync-upsert-config.ts → integration-upsert-config.ts}

@@ -1,14 +1,14 @@
 /**
- * SyncUpsertConfig + SyncFkResolver
+ * IntegrationUpsertConfig + IntegrationFkResolver
  *
- * Declarative description of an entity's inbound-sync write surface, consumed
- * by `SyncedEntityRepository.syncUpsertOne` / `findByExternalIdProjected` /
- * `softDeleteByExternalId` / `toProjection`. Each `pattern: Synced` repository
- * declares a concrete `syncConfig: SyncUpsertConfig` (emitted by the template),
+ * Declarative description of an entity's inbound-integration write surface, consumed
+ * by `IntegratedEntityRepository.integrationUpsertOne` / `findByExternalIdProjected` /
+ * `softDeleteByExternalId` / `toProjection`. Each `pattern: Integrated` repository
+ * declares a concrete `integrationConfig: IntegrationUpsertConfig` (emitted by the template),
  * the same idiom as `behaviors: BehaviorConfig`.
  *
- * Named `SyncUpsertConfig` (not `SyncConfig`) to avoid colliding with the sync
- * subsystem's `DetectionConfig`/`SyncConfig` surface.
+ * Named `IntegrationUpsertConfig` (not `IntegrationConfig`) to avoid colliding with the integration
+ * subsystem's `DetectionConfig`/`IntegrationConfig` surface.
  *
  * The generic upsert separates three column roles:
  *   - identity      (`conflictTarget`) — only in `values`, never in `set`
@@ -27,10 +27,10 @@ import type { PgTableWithColumns } from 'drizzle-orm/pg-core';
  * posture); falsy leaves the column null this run (opportunistic, entity
  * posture).
  */
-export interface SyncFkResolver {
+export interface IntegrationFkResolver {
   /** Local FK column — camel key into `this.table`, e.g. `'parentAccountId'`. */
   column: string;
-  /** Key on `TSyncWrite` carrying the parent external id (see Decision 4). */
+  /** Key on `TIntegrationWrite` carrying the parent external id (see Decision 4). */
   writeKey: string;
   /** Parent table to resolve against; `'self'` → `this.table`. */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -39,7 +39,7 @@ export interface SyncFkResolver {
   strict?: boolean;
 }
 
-export interface SyncUpsertConfig {
+export interface IntegrationUpsertConfig {
   /** Camel keys into `this.table` forming the conflict target, e.g. `['provider', 'externalId']`. */
   conflictTarget: string[];
   /**
@@ -48,10 +48,10 @@ export interface SyncUpsertConfig {
    */
   writeColumns: string[];
   /** Conditional, provider-scoped FK resolvers. */
-  fkResolvers: SyncFkResolver[];
+  fkResolvers: IntegrationFkResolver[];
   /** Columns picked into the projection (camel), incl. id/externalId/timestamps. */
   projectionColumns: string[];
-  /** When true, `syncUpsertOne` calls `writeCustomFields` for a non-empty `fields` bag. */
+  /** When true, `integrationUpsertOne` calls `writeCustomFields` for a non-empty `fields` bag. */
   eav: boolean;
   /** When true, deletes set `deletedAt`; when false, tombstone-by-clearing external_id/provider. */
   softDelete: boolean;

package/runtime/base-classes/{junction-sync-repository.ts → junction-integration-repository.ts}

@@ -1,9 +1,9 @@
 /**
- * JunctionSyncRepository<TEntity, TSyncWrite, TSyncProjection>
+ * JunctionIntegrationRepository<TEntity, TIntegrationWrite, TIntegrationProjection>
  *
- * Base for junction repos that participate in inbound sync (#374). A junction's
- * sync identity is the tuple `(leftId, rightId[, role])` — there is no native
- * `external_id`/`provider` column, so the sync seam's externalId is a COMPOSITE
+ * Base for junction repos that participate in inbound integration (#374). A junction's
+ * integration identity is the tuple `(leftId, rightId[, role])` — there is no native
+ * `external_id`/`provider` column, so the integration seam's externalId is a COMPOSITE
  * string `<leftExternalId>::<rightExternalId>[::<role>]` (see the static
  * build/parse helpers below).
  *
@@ -19,7 +19,7 @@ import type { PgTableWithColumns } from 'drizzle-orm/pg-core';
 import type { DrizzleTx } from '../types/drizzle';
 import { BaseRepository } from './base-repository';
 
-export interface JunctionSyncConfig {
+export interface JunctionIntegrationConfig {
   /** Left endpoint: local FK column (camel) + strict parent table. */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   left: { column: string; refTable: PgTableWithColumns<any> };
@@ -30,16 +30,16 @@ export interface JunctionSyncConfig {
   roleColumn: string | null;
 }
 
-export abstract class JunctionSyncRepository<
+export abstract class JunctionIntegrationRepository<
   TEntity,
-  TSyncWrite,
-  TSyncProjection,
+  TIntegrationWrite,
+  TIntegrationProjection,
 > extends BaseRepository<TEntity> {
   /**
-   * Declarative junction sync surface. Concrete repos declare this — the
+   * Declarative junction integration surface. Concrete repos declare this — the
    * template emits it with live parent-table handles.
    */
-  protected abstract readonly syncConfig: JunctionSyncConfig;
+  protected abstract readonly integrationConfig: JunctionIntegrationConfig;
 
   /**
    * Upsert ONE junction row by its composite identity, in a single transaction:
@@ -54,17 +54,17 @@ export abstract class JunctionSyncRepository<
    * @param provider  adapter/provider label used to scope the parent lookups
    * @param tx        optional outer transaction; when omitted we open our own
    */
-  async syncUpsertOne(
-    write: TSyncWrite,
+  async integrationUpsertOne(
+    write: TIntegrationWrite,
     provider: string,
     tx?: DrizzleTx,
-  ): Promise<TSyncProjection> {
-    const cfg = this.syncConfig;
+  ): Promise<TIntegrationProjection> {
+    const cfg = this.integrationConfig;
     const w = write as Record<string, unknown>;
     const leftWriteKey = `${cfg.left.column.replace(/Id$/, '')}ExternalId`;
     const rightWriteKey = `${cfg.right.column.replace(/Id$/, '')}ExternalId`;
 
-    const run = async (db: DrizzleTx): Promise<TSyncProjection> => {
+    const run = async (db: DrizzleTx): Promise<TIntegrationProjection> => {
       const leftId = await this.resolveStrict(
         db, cfg.left.refTable, w[leftWriteKey] as string, provider, cfg.left.column,
       );
@@ -109,8 +109,8 @@ export abstract class JunctionSyncRepository<
   async findByExternalIdProjected(
     externalId: string,
     provider: string,
-  ): Promise<TSyncProjection | null> {
-    const cfg = this.syncConfig;
+  ): Promise<TIntegrationProjection | null> {
+    const cfg = this.integrationConfig;
     const parsed = parseCompositeExternalId(externalId, cfg.roleColumn !== null);
     if (!parsed) return null;
 
@@ -138,7 +138,7 @@ export abstract class JunctionSyncRepository<
 
   /**
    * Hard-delete the junction by composite externalId. Junctions have no
-   * `deleted_at` and no external-linkage columns to clear, so a sync "delete"
+   * `deleted_at` and no external-linkage columns to clear, so a integration "delete"
    * removes the row. Resolves both parents NON-throwing, then deletes by the
    * identity tuple. Returns the composite id, or `null` when nothing matched.
    */
@@ -147,7 +147,7 @@ export abstract class JunctionSyncRepository<
     provider: string,
     tx?: DrizzleTx,
   ): Promise<{ id: string } | null> {
-    const cfg = this.syncConfig;
+    const cfg = this.integrationConfig;
     const parsed = parseCompositeExternalId(externalId, cfg.roleColumn !== null);
     if (!parsed) return null;
     const db = this.runner(tx);
@@ -168,16 +168,16 @@ export abstract class JunctionSyncRepository<
    * Project a raw junction row to the differ shape: the COMPOSITE externalId
    * `id` (junctions have no surrogate id) plus the local FK columns, role (when
    * role-bearing) and timestamps — matching the emitted
-   * `<Junction>SyncProjection` interface (id + leftId + rightId + role? +
+   * `<Junction>IntegrationProjection` interface (id + leftId + rightId + role? +
    * createdAt + updatedAt). Junction projections are purely structural, so this
-   * is fully generic over `syncConfig` — no per-junction override is emitted.
+   * is fully generic over `integrationConfig` — no per-junction override is emitted.
    */
   protected toProjection(
     row: TEntity,
     write: Record<string, unknown>,
     _provider: string,
-  ): TSyncProjection {
-    const cfg = this.syncConfig;
+  ): TIntegrationProjection {
+    const cfg = this.integrationConfig;
     const r = row as Record<string, unknown>;
     const leftExt = write[`${cfg.left.column.replace(/Id$/, '')}ExternalId`] as string;
     const rightExt = write[`${cfg.right.column.replace(/Id$/, '')}ExternalId`] as string;
@@ -190,12 +190,12 @@ export abstract class JunctionSyncRepository<
     if (cfg.roleColumn) out[cfg.roleColumn] = r[cfg.roleColumn];
     out['createdAt'] = r['createdAt'];
     out['updatedAt'] = r['updatedAt'];
-    return out as TSyncProjection;
+    return out as TIntegrationProjection;
   }
 
   /** Build the identity WHERE clause `(left, right[, role])`. */
   private identityWhere(leftId: string, rightId: string, role: string | undefined) {
-    const cfg = this.syncConfig;
+    const cfg = this.integrationConfig;
     const conds = [
       eq(this.table[cfg.left.column], leftId),
       eq(this.table[cfg.right.column], rightId),
@@ -218,9 +218,9 @@ export abstract class JunctionSyncRepository<
     const id = await this.resolveLoose(db, refTable, parentExternalId, provider);
     if (!id) {
       throw new Error(
-        `${this.constructor.name}.syncUpsertOne: unresolved parent ` +
+        `${this.constructor.name}.integrationUpsertOne: unresolved parent ` +
           `'${parentExternalId}' (provider '${provider}') for '${column}' — ` +
-          `parent not synced yet`,
+          `parent not integrated yet`,
       );
     }
     return id;
@@ -250,7 +250,7 @@ export abstract class JunctionSyncRepository<
 }
 
 // ============================================================================
-// Composite externalId — the junction sync seam's deterministic identity.
+// Composite externalId — the junction integration seam's deterministic identity.
 //
 // Format: `<leftExternalId>::<rightExternalId>[::<role>]`
 //   e.g. `hubspot:42::hubspot:99::employee`  (role-bearing)

package/runtime/subsystems/auth/auth-oauth-state.schema.ts

@@ -15,7 +15,7 @@
  *   - `expires_at`  — TTL boundary; entries past this are treated as absent.
  *
  * Convention: schema files live at the root of the subsystem dir
- * (mirrors `cache.schema.ts`, `sync-audit.schema.ts`, `domain-events.schema.ts`).
+ * (mirrors `cache.schema.ts`, `integration-audit.schema.ts`, `domain-events.schema.ts`).
  */
 import { pgTable, text, timestamp } from 'drizzle-orm/pg-core';
 import type { InferSelectModel } from 'drizzle-orm';

package/runtime/subsystems/auth/auth.module.ts

@@ -9,17 +9,17 @@
  *   - `AUTH_OPTIONS`        → resolved options bag (used by AuthController
  *                             for `redirectUriBase`).
  *
- * The integration-store ports (`AUTH_INTEGRATION_READER`,
- * `AUTH_INTEGRATION_TOKEN_WRITER`, `AUTH_INTEGRATION_GRANT_SINK`),
+ * The connection-store ports (`AUTH_CONNECTION_READER`,
+ * `AUTH_CONNECTION_TOKEN_WRITER`, `AUTH_CONNECTION_GRANT_SINK`),
  * `AUTH_USER_CONTEXT`, and `STRATEGY_REGISTRY` are deliberately **not**
  * wired here — they are always consumer-specific:
- *   - integration-store ports adapt the consumer's `integrations` storage;
+ *   - connection-store ports adapt the consumer's `connections` storage;
  *   - `IUserContext` adapts the app's session/JWT scheme;
  *   - `STRATEGY_REGISTRY` is populated from the per-provider strategy
  *     classes the consumer maintains.
  *
  * Consumers provide them in their app module (or by importing the
- * `auth-integrations` starter, which binds the three integration-store
+ * `auth-integrations` starter, which binds the three connection-store
  * ports off a single canonical entity).
  *
  * Usage in AppModule:

package/runtime/subsystems/auth/auth.tokens.ts

@@ -10,9 +10,9 @@
  * constructor(
  *   @Inject(ENCRYPTION_KEY) private readonly key: IEncryptionKey,
  *   @Inject(OAUTH_STATE_STORE) private readonly states: IOAuthStateStore,
- *   @Inject(AUTH_INTEGRATION_READER) private readonly reader: IIntegrationReader,
- *   @Inject(AUTH_INTEGRATION_TOKEN_WRITER) private readonly writer: IIntegrationTokenWriter,
- *   @Inject(AUTH_INTEGRATION_GRANT_SINK) private readonly grants: IIntegrationGrantSink,
+ *   @Inject(AUTH_CONNECTION_READER) private readonly reader: IConnectionReader,
+ *   @Inject(AUTH_CONNECTION_TOKEN_WRITER) private readonly writer: IConnectionTokenWriter,
+ *   @Inject(AUTH_CONNECTION_GRANT_SINK) private readonly grants: IConnectionGrantSink,
  *   @Inject(AUTH_USER_CONTEXT) private readonly userCtx: IUserContext,
  *   @Inject(STRATEGY_REGISTRY) private readonly registry: ProviderStrategyRegistry,
  * ) {}
@@ -20,7 +20,7 @@
  *
  * `IAuthStrategy` implementations are provider-specific and registered under
  * provider-specific tokens (e.g. `SALESFORCE_AUTH_STRATEGY`,
- * `HUBSPOT_AUTH_STRATEGY`) by each integration module — this subsystem does
+ * `HUBSPOT_AUTH_STRATEGY`) by each connection module — this subsystem does
  * not mandate a single `AUTH_STRATEGY` token because an app typically has
  * many concurrent strategies, one per provider. They are dispatched through
  * `STRATEGY_REGISTRY` (a `ReadonlyMap<slug, IProviderStrategy>`), populated
@@ -28,9 +28,9 @@
  */
 export const ENCRYPTION_KEY = Symbol('ENCRYPTION_KEY');
 export const OAUTH_STATE_STORE = Symbol('OAUTH_STATE_STORE');
-export const AUTH_INTEGRATION_READER = Symbol('AUTH_INTEGRATION_READER');
-export const AUTH_INTEGRATION_TOKEN_WRITER = Symbol('AUTH_INTEGRATION_TOKEN_WRITER');
-export const AUTH_INTEGRATION_GRANT_SINK = Symbol('AUTH_INTEGRATION_GRANT_SINK');
+export const AUTH_CONNECTION_READER = Symbol('AUTH_CONNECTION_READER');
+export const AUTH_CONNECTION_TOKEN_WRITER = Symbol('AUTH_CONNECTION_TOKEN_WRITER');
+export const AUTH_CONNECTION_GRANT_SINK = Symbol('AUTH_CONNECTION_GRANT_SINK');
 export const AUTH_USER_CONTEXT = Symbol('AUTH_USER_CONTEXT');
 export const STRATEGY_REGISTRY = Symbol('STRATEGY_REGISTRY');
 /**

package/runtime/subsystems/auth/controllers/auth.controller.ts

@@ -15,11 +15,11 @@
  *   - `AUTH_USER_CONTEXT` (IUserContext) — resolves "who is this request"
  *     from the consumer's session/JWT/etc.
  *   - `OAUTH_STATE_STORE` (IOAuthStateStore) — CSRF state minting/consume.
- *   - `AUTH_INTEGRATION_GRANT_SINK` (IIntegrationGrantSink) — persists the
+ *   - `AUTH_CONNECTION_GRANT_SINK` (IConnectionGrantSink) — persists the
  *     freshly-minted grant. Adapter lives consumer-side (e.g. the
  *     auth-integrations starter from #285).
  *
- * The controller never imports `IntegrationsService` or any other concrete
+ * The controller never imports `ConnectionsService` or any other concrete
  * consumer type — it goes through ports only.
  */
 import {
@@ -34,7 +34,7 @@ import {
   HttpStatus,
 } from '@nestjs/common';
 import {
-  AUTH_INTEGRATION_GRANT_SINK,
+  AUTH_CONNECTION_GRANT_SINK,
   AUTH_OPTIONS,
   AUTH_USER_CONTEXT,
   OAUTH_STATE_STORE,
@@ -47,7 +47,7 @@ import type {
   IProviderStrategy,
   ProviderStrategyRegistry,
 } from '../protocols/provider-strategy';
-import type { IIntegrationGrantSink } from '../protocols/integration-store';
+import type { IConnectionGrantSink } from '../protocols/connection-store';
 
 /**
  * Minimal response surface used by the controller — typed loosely so we
@@ -67,8 +67,8 @@ export class AuthController {
     private readonly userContext: IUserContext,
     @Inject(OAUTH_STATE_STORE)
     private readonly stateStore: IOAuthStateStore,
-    @Inject(AUTH_INTEGRATION_GRANT_SINK)
-    private readonly grantSink: IIntegrationGrantSink,
+    @Inject(AUTH_CONNECTION_GRANT_SINK)
+    private readonly grantSink: IConnectionGrantSink,
     @Inject(AUTH_OPTIONS)
     private readonly options: AuthModuleOptions,
   ) {}
@@ -127,7 +127,7 @@ export class AuthController {
     });
     return res.redirect(
       HttpStatus.FOUND,
-      redirect ?? `/settings/integrations?connected=${encodeURIComponent(slug)}`,
+      redirect ?? `/settings/connections?connected=${encodeURIComponent(slug)}`,
     );
   }