@pattern-stack/codegen 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,128 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.12.0] — 2026-05-31
+
+Integration codegen retarget (RFC-0001): a **provider/adapter/surface** model
+for integration codegen, plus a **surface-package framework**. Additive over
+0.11.0 — new declarative inputs and emitted artifacts; existing entity codegen
+is unchanged. The one breaking item (the ADR-033.2 per-entity provider tuples)
+has no consumers. Consumers adopt by adding `definitions/providers/*.yaml` and
+regenerating. Ships alongside four independently-versioned **surface packages**
+(`@pattern-stack/codegen-{crm,calendar,mail,transcript}`) publishing fresh at
+`0.1.0`.
+
+### ⚠ BREAKING CHANGES
+
+- **ADR-033.2 per-entity provider tuples removed.** The
+  `<entity>-integration-source.providers.ts` emission (`<ENTITY>_PROVIDERS`
+  const + `<Entity>Provider` type) is deleted. Its replacement is the
+  surface-scoped, codegen-owned typed view at
+  `src/integrations/<surface>/types.generated.ts` (`<Surface>Provider` /
+  `<Surface>Entity` unions + a `(provider, entity)` validity map) — a single
+  source of provider truth. ADR-033.2 is superseded by RFC-0001. No published
+  consumers depend on the tuples.
+
+### Added
+
+- **Track C — surface-package framework (ADR-036).** First-class L2 *surface
+  packages* shipping type-shaped ports + DI tokens + an L3 composing port per
+  integration surface:
+  - **L1** — `IEntityChangeSourceRegistry` (entity-keyed change-source
+    resolver) + `MemoryEntityChangeSourceRegistry` + the
+    `ENTITY_CHANGE_SOURCE_REGISTRY` token, in the integration subsystem;
+    exported across the package boundary via `@pattern-stack/codegen/subsystems`.
+  - **`@pattern-stack/codegen-crm`** — L2 CRM ports (`IFieldDefinitionReader`,
+    `IPicklistReader`, `IAssociationReader`), the `CrmCapabilities` descriptor,
+    and the L3 entity-agnostic **`CrmPort`** composing port + `assertCrmAdapter`
+    conformance helper (on the `/testing` subpath).
+  - **`@pattern-stack/codegen-{calendar,mail,transcript}`** — incremental-read
+    interaction surfaces (`CalendarPort` / `MailPort` / `TranscriptPort`,
+    canonical types, capability descriptors). Independently versioned (`0.1.0`).
+- **Track D — provider/adapter integration codegen (RFC-0001).**
+  - `definitions/providers/<provider>.yaml` — providers as first-class
+    declarative artifacts (slug, auth strategy, client, surfaces); Zod schema +
+    validator with a **pre-flight import-path check** (a missing
+    strategy/client export fails `cdp gen`, not NestJS boot), surface
+    cross-check, and slug-uniqueness.
+  - Emits, per provider × surface: a `<provider>.provider.module.ts`, an
+    **emit-once** `<provider>-<surface>.adapter.ts` scaffold (sentinel-guarded,
+    author-owned after first emit), fully codegen-owned adapter modules +
+    barrels, a per-surface registry (`<SURFACE>_ADAPTER_CONTRIBUTIONS` →
+    `<SURFACE>_ENTITY_SOURCES`, folding into the L1 registry), and the
+    `types.generated.ts` typed view.
+  - Optional entity-YAML **`surface:`** field — the declarative input the
+    provider/adapter emission groups entities by.
+- **`context:` output-folder grouping (#403).** An optional top-level entity
+  `context:` nests its generated module folder under that segment
+  (`<modules>/<context>/<plural>/`); no context → flat (byte-identical to
+  before).
+- **Multi-package release.** `just publish` publishes the root plus every
+  opted-in `packages/*` (those declaring `publishConfig.access: public`) at its
+  own independent version, skipping versions already on npm.
+
+## [0.11.0] — 2026-05-30
+
+Vocabulary rename per **ADR-0005 (swe-brain `.ai-docs/decisions/ADR-0005-rename-sync-to-integration.md`)**:
+the data-movement domain `sync` → `integration` (reserving "sync" for
+ElectricSQL-style replication), the `Synced` entity family → `Integrated`, and
+the authenticated vendor-link `IntegrationStore` → `ConnectionStore`. This is a
+clean break — there are no compat shims or deprecated aliases; consumers
+migrate by **regenerating** off the renamed substrate (codegen owns the
+physical/structural names).
+
+### ⚠ BREAKING CHANGES
+
+- **Integration engine (`sync` → `integration`).**
+  - `SyncModule` → `IntegrationModule` (`.forRoot({ backend, multiTenant? })`);
+    `ExecuteSyncUseCase` → `ExecuteIntegrationUseCase`.
+  - Tokens `SYNC_*` → `INTEGRATION_*` (cursor store, run recorder, field
+    differ, change source, sink, multi-tenant flag, module options).
+  - Protocols/ports/recorders/cursor-stores/errors `sync-*` → `integration-*`;
+    `runtime/subsystems/sync/**` → `runtime/subsystems/integration/**`.
+  - Tables `sync_runs` / `sync_run_items` / `sync_subscriptions` →
+    `integration_runs` / `integration_run_items` / `integration_subscriptions`;
+    cursor column `last_sync_at` → `last_integration_at`.
+  - Entity-YAML config block `sync:` → `integration:` (incl. `sync.inbound` →
+    `integration.inbound`); the per-entity `*-sync-source.module.ts` codegen
+    output → `*-integration-source.module.ts`.
+  - CLI: `codegen subsystem install sync` → `… install integration`; the
+    `/sync` skill → `/integration`.
+- **`Synced` entity family → `Integrated`.**
+  - `SyncedEntityRepository` / `SyncedEntityService` → `IntegratedEntityRepository`
+    / `IntegratedEntityService`; `SyncUpsertConfig` → `IntegrationUpsertConfig`;
+    `syncUpsertOne`/`syncUpsert`/`syncConfig`/`SyncFkResolver` →
+    `integrationUpsertOne`/`integrationUpsert`/`integrationConfig`/`IntegrationFkResolver`;
+    `junction-sync-repository.ts` → `junction-integration-repository.ts`.
+  - YAML `pattern: Synced` → `pattern: Integrated`.
+- **Auth vendor-link `integration` → `connection`.**
+  - `IntegrationStore` ports → `ConnectionStore`:
+    `IIntegrationReader`/`IIntegrationTokenWriter`/`IIntegrationGrantSink` →
+    `IConnection*`; `DecryptedIntegration` → `DecryptedConnection`;
+    `IntegrationGrantInput`/`IntegrationTokenUpdate` → `Connection*`;
+    `IntegrationBrokenError` → `ConnectionBrokenError`; DI tokens
+    `AUTH_INTEGRATION_*` → `AUTH_CONNECTION_*`.
+  - Engine FK `integration_subscriptions.integration_id` → `connection_id`
+    (the column references the connected account/instance — a *connection*;
+    the table name stays `integration_subscriptions`).
+  - The `examples/auth-integrations` starter is fully renamed to the connection
+    vocabulary: `connection.yaml` entity (table `connections`),
+    `ConnectionsService`, `ConnectionsAuthModule`, `Connection*Adapter`,
+    vendored under `<modules>/connections/`. The `auth-integrations` subsystem
+    **install command** keeps its name.
+
+### Preserved (NOT renamed)
+
+- The CLI imperative **verb** `sync` in app-level event names
+  (`crm_sync_started`, `webhook_outbound_contact_sync`).
+- ElectricSQL `frontend.sync` collection config (replication sense).
+
+### Migration
+
+No shims. Re-vendor the runtime (`codegen update`) and **regenerate** entities/
+subsystems off the renamed names; update app code that references the renamed
+symbols/tokens/tables/config keys. See ADR-0005 (swe-brain `.ai-docs/decisions/ADR-0005-rename-sync-to-integration.md`).
+
 ## [0.10.1] — 2026-05-28
 
 Dogfood fixes found wiring `@pattern-stack/codegen@0.10.0` into a second

package/README.md

@@ -23,7 +23,7 @@ entity:
   name: contact
   plural: contacts
   table: contacts
-  pattern: Synced                   # Synced | Activity | Metadata | Knowledge | Base (or app-defined)
+  pattern: Integrated               # Integrated | Activity | Metadata | Knowledge | Base (or app-defined)
 
 fields:
   email:
@@ -94,7 +94,7 @@ codegen subsystem install events     # domain event bus (transactional outbox)
 codegen subsystem install jobs       # background job queue (pg-boss pattern)
 codegen subsystem install cache      # key-value cache with TTL
 codegen subsystem install storage    # file storage (local filesystem)
-codegen subsystem install sync       # external-system sync engine (IChangeSource + orchestrator + audit log)
+codegen subsystem install integration # external-system integration engine (IChangeSource + orchestrator + audit log)
 codegen subsystem install bridge     # event-to-job bridge (durable async fanout via @JobHandler.triggers)
 codegen subsystem install openapi-config  # OpenAPI/Swagger — Zod DTOs as /docs-json + Swagger UI. See docs/CONSUMER-SETUP.md §OpenAPI
 codegen subsystem install auth       # OAuth integration auth (AuthModule + ports + state store + AuthController)
@@ -144,7 +144,7 @@ Families provide pre-built base classes with domain-specific query patterns:
 
 | Family | When to Use | Key Methods |
 |--------|-------------|-------------|
-| `synced` | CRM-synced entities (contacts, accounts) | `findByExternalId`, `syncUpsert`, `findAllByUserId` |
+| `integrated` | externally-integrated entities (contacts, accounts) | `findByExternalId`, `integrationUpsert`, `findAllByUserId` |
 | `activity` | Time-based events (emails, calls, meetings) | `findByDateRange`, `findRecentByOpportunityId` |
 | `metadata` | Key-value data (tags, custom fields) | `findByEntityIdAndType`, `upsertMany` |
 | `knowledge` | Vector-searchable content | Stub (needs pgvector) |
@@ -163,9 +163,9 @@ queries:
   - by: [user_id, status]    # → FindContactByUserIdAndStatusUseCase (compound)
 ```
 
-## Sync Detection (`detection:` block)
+## Integration Detection (`detection:` block)
 
-Entities that participate in the sync subsystem may declare a `detection:` block describing how upstream changes are detected. The block is parsed by the canonical `DetectionConfigSchema` shipped from `runtime/subsystems/sync` — primitives (`PollChangeSource<T>`, `WebhookChangeSource<T>`) and the per-entity factory module emitted by codegen consume the same parsed shape, so YAML and runtime stay in lockstep (ADR-033, epic #226).
+Entities that participate in the integration subsystem may declare a `detection:` block describing how upstream changes are detected. The block is parsed by the canonical `DetectionConfigSchema` shipped from `runtime/subsystems/integration` — primitives (`PollChangeSource<T>`, `WebhookChangeSource<T>`) and the per-entity factory module emitted by codegen consume the same parsed shape, so YAML and runtime stay in lockstep (ADR-033, epic #226).
 
 ```yaml
 detection:

package/consumer-skills/codegen/SKILL.md

@@ -7,7 +7,7 @@ description: >-
   the `codegen` (aka `cdp`) CLI, install or wire an infrastructure subsystem, or
   refresh the project after a package upgrade. This is the entry-point router;
   it points at the focused `entities`, `subsystems`, `jobs`, `events`, `bridge`,
-  and `sync` skills for deep work.
+  and `integration` skills for deep work.
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 user-invocable: false
 ---
@@ -53,7 +53,7 @@ generation run the two barrels are rewritten and you wire them into
 | Write a background `@JobHandler`, configure pools, set concurrency/ordering | the `jobs` skill |
 | Author a domain event, publish via the outbox, use the typed event bus | the `events` skill |
 | React to an event with a durable async job (the event-to-job bridge) | the `bridge` skill |
-| Pull/push data from an external system (`IChangeSource` / `ISyncSink`) | the `sync` skill |
+| Pull/push data from an external system (`IChangeSource` / `IIntegrationSink`) | the `integration` skill |
 
 ## CLI quick reference
 

package/consumer-skills/{sync → integration}/SKILL.md

@@ -1,25 +1,25 @@
 ---
-name: sync
-description: Load when integrating an external system (CRM, billing, etc.) in a project that ran `codegen subsystem install sync`. Triggers include implementing `IChangeSource<T>` for a provider; writing an `ISyncSink<T>`; registering `SyncModule.forRoot(...)` in `app.module.ts`; building a per-entity feature module that binds the change source, sink, and `ExecuteSyncUseCase`; declaring a `detection:` block in entity YAML; querying the `sync_runs` / `sync_run_items` audit log or the structured `changed_fields` jsonb; or wiring cursor persistence, diffing, and multi-tenancy.
+name: integration
+description: Load when integrating an external system (CRM, billing, etc.) in a project that ran `codegen subsystem install integration`. Triggers include implementing `IChangeSource<T>` for a provider; writing an `IIntegrationSink<T>`; registering `IntegrationModule.forRoot(...)` in `app.module.ts`; building a per-entity feature module that binds the change source, sink, and `ExecuteIntegrationUseCase`; declaring a `detection:` block in entity YAML; querying the `integration_runs` / `integration_run_items` audit log or the structured `changed_fields` jsonb; or wiring cursor persistence, diffing, and multi-tenancy.
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 user-invocable: false
 ---
 
 <!-- managed by @pattern-stack/codegen — re-run `codegen skills install` to refresh. Edit the package source, not this vendored copy. -->
 
-# Sync Subsystem
+# Integration Subsystem
 
-The sync subsystem is a generic external-system integration engine for your
-app. One orchestrator — `ExecuteSyncUseCase<T>` — runs *every* integration in
+The integration subsystem is a generic external-system integration engine for your
+app. One orchestrator — `ExecuteIntegrationUseCase<T>` — runs *every* integration in
 your codebase. You write per-provider detection code against a single port
 (`IChangeSource<T>`) and per-entity write code against a single sink
-(`ISyncSink<T>`). Everything else — cursor persistence, field diffing,
+(`IIntegrationSink<T>`). Everything else — cursor persistence, field diffing,
 per-record audit, run lifecycle — is provided by the subsystem.
 
-You opt in with `codegen subsystem install sync`, which vendors the runtime
-into `<paths.subsystems>/sync/` (imported as `@shared/subsystems/sync`), adds a
-`sync:` block to `codegen.config.yaml`, and emits the audit schema
-(`sync-audit.schema.ts`). Unlike some subsystems, sync ships **no `generated/`
+You opt in with `codegen subsystem install integration`, which vendors the runtime
+into `<paths.subsystems>/integration/` (imported as `@shared/subsystems/integration`), adds a
+`integration:` block to `codegen.config.yaml`, and emits the audit schema
+(`integration-audit.schema.ts`). Unlike some subsystems, integration ships **no `generated/`
 directory** — there are no codegen-emitted runtime artifacts from the base
 install. (Per-entity change-source modules are emitted only if you declare a
 `detection:` block in an entity YAML — see the change-sources L1 file.)
@@ -32,41 +32,41 @@ subsystem owns; step 1 is the only thing you write per provider:
 1. **detect** upstream change *(you — `IChangeSource<T>`)*
 2. **diff** against local state *(subsystem — `IFieldDiffer<T>`, default `DeepEqualDiffer`)*
 3. **apply** the upsert or soft-delete *(your sink, called by the orchestrator)*
-4. **record** the structured delta into `sync_run_items` *(subsystem)*
+4. **record** the structured delta into `integration_run_items` *(subsystem)*
 5. **emit** an event on success *(you — wired in your sink, optional)*
 
 Three detection modes (poll / CDC / webhook) converge on the single
 `IChangeSource<T>` port; per-mode differences live in `Change<T>` metadata, not
 in separate ports.
 
-**Sync is not events and not jobs.** Sync detects upstream change → diffs →
-applies → records (`sync_runs` + `sync_run_items` pairs). It can be *triggered
+**Integration is not events and not jobs.** Integration detects upstream change → diffs →
+applies → records (`integration_runs` + `integration_run_items` pairs). It can be *triggered
 by* a scheduled job (polling) or a webhook, and it can *emit* events on a
 successful upsert — but the three subsystems have distinct lifecycles. See the
 `jobs` and `events` skills for those.
 
-**The audit is structured, not freeform.** `sync_run_items.changed_fields` is
+**The audit is structured, not freeform.** `integration_run_items.changed_fields` is
 `{ fieldName: { from, to } }` jsonb, validated at write time. That makes drift
 queries ("when did this opportunity first become Closed Won?") one-shot SQL
 filters instead of JSON scrapes.
 
 ## Wiring at a glance
 
-`SyncModule.forRoot(...)` in `app.module.ts` wires the substrate — the cursor
+`IntegrationModule.forRoot(...)` in `app.module.ts` wires the substrate — the cursor
 store, run recorder, field differ, and multi-tenant flag. It is `global: true`
-and **does NOT provide `ExecuteSyncUseCase`**. The orchestrator depends on
-`SYNC_CHANGE_SOURCE` + `SYNC_SINK`, which are per-entity and consumer-owned, so
-you register `ExecuteSyncUseCase` in your *feature module* alongside those
-bindings. Putting it in `SyncModule` would force Nest to resolve those tokens
+and **does NOT provide `ExecuteIntegrationUseCase`**. The orchestrator depends on
+`INTEGRATION_CHANGE_SOURCE` + `INTEGRATION_SINK`, which are per-entity and consumer-owned, so
+you register `ExecuteIntegrationUseCase` in your *feature module* alongside those
+bindings. Putting it in `IntegrationModule` would force Nest to resolve those tokens
 at module compile time, before your feature module is imported.
 
 ```ts
-import { SyncModule } from '@shared/subsystems/sync';
+import { IntegrationModule } from '@shared/subsystems/integration';
 
 @Module({
   imports: [
     DatabaseModule,
-    SyncModule.forRoot({ backend: 'drizzle' }),  // 'memory' in tests
+    IntegrationModule.forRoot({ backend: 'drizzle' }),  // 'memory' in tests
     // ... per-entity feature modules, other subsystems
   ],
 })
@@ -77,13 +77,13 @@ export class AppModule {}
 
 | When the task involves… | Read |
 |---|---|
-| Implementing `IChangeSource<T>` or `ISyncSink<T>`; the per-entity feature module; the `detection:` block + provider-keyed factory; triggering a run; multi-tenancy; loopback; testing | `change-sources-and-sinks.md` |
-| The `sync_runs` / `sync_run_items` / `sync_subscriptions` shape; the structured `changed_fields` contract; worked drift / staleness / stuck-run queries; orchestrator run lifecycle and failure semantics | `audit-and-detection.md` |
+| Implementing `IChangeSource<T>` or `IIntegrationSink<T>`; the per-entity feature module; the `detection:` block + provider-keyed factory; triggering a run; multi-tenancy; loopback; testing | `change-sources-and-sinks.md` |
+| The `integration_runs` / `integration_run_items` / `integration_subscriptions` shape; the structured `changed_fields` contract; worked drift / staleness / stuck-run queries; orchestrator run lifecycle and failure semantics | `audit-and-detection.md` |
 
 ## Non-obvious rules
 
 1. **One port for three modes.** Poll, CDC, and webhook adapters all implement
-   `IChangeSource<T>` with `listChanges(subscription, cursor): AsyncIterable<Change<T>>`.
+   `IChangeSource<T>` with `listChanges(subscription, cursor): AintegrationIterable<Change<T>>`.
    Per-mode concerns ride in `Change<T>` metadata (`source`, `dedupKey`,
    `providerChangedFields`). Do not introduce `IPollSource` / `ICdcSource` /
    `IWebhookSource` — the union is deliberate.
@@ -93,7 +93,7 @@ export class AppModule {}
    The orchestrator is the only reader/writer of cursor storage — never inject
    the cursor store inside a source or sink.
 
-3. **`SyncModule` does NOT provide `ExecuteSyncUseCase`.** Register the
+3. **`IntegrationModule` does NOT provide `ExecuteIntegrationUseCase`.** Register the
    orchestrator in your feature module's `providers` array next to your source
    and sink bindings.
 
@@ -102,8 +102,8 @@ export class AppModule {}
    insert (in both Drizzle and Memory backends). Do not treat it as freeform —
    arbitrary keys break drift queries and get rejected.
 
-5. **The sync audit tables are subsystem-owned.** Query `sync_subscriptions`,
-   `sync_runs`, and `sync_run_items` freely for dashboards, but do not write to
+5. **The integration audit tables are subsystem-owned.** Query `integration_subscriptions`,
+   `integration_runs`, and `integration_run_items` freely for dashboards, but do not write to
    them directly (bypassing the recorder's validation lands malformed data),
    and do not author entity YAMLs for them (that produces redundant
    repositories/services shadowing the subsystem).
@@ -124,9 +124,9 @@ export class AppModule {}
   `IWebhookSource`). One `IChangeSource<T>` for all modes.
 - Do not treat `changed_fields` as freeform jsonb — the `{ from, to }` shape is
   load-bearing for drift queries and enforced at write.
-- Do not provide `ExecuteSyncUseCase` in `SyncModule` — it forces eager
+- Do not provide `ExecuteIntegrationUseCase` in `IntegrationModule` — it forces eager
   resolution of consumer-owned tokens.
-- Do not write directly to the sync audit tables, and do not ship entity YAMLs
+- Do not write directly to the integration audit tables, and do not ship entity YAMLs
   for them.
 - Do not inject the cursor store inside a source or sink — the orchestrator
   owns the get/put lifecycle.

package/consumer-skills/{sync → integration}/audit-and-detection.md

@@ -2,7 +2,7 @@
 
 # Audit model, orchestrator flow, and diffing
 
-The sync subsystem records every run into three tables and runs every
+The integration subsystem records every run into three tables and runs every
 integration through one orchestrator loop. This file covers the table shapes,
 the structured `changed_fields` contract, the queries you'll write against the
 audit log, the orchestrator's run lifecycle and failure semantics, and how the
@@ -15,15 +15,15 @@ UIs, but never write to them directly (you'd bypass the recorder's validation),
 and never author entity YAMLs for them (that produces redundant
 repositories/services that shadow the subsystem).
 
-### `sync_subscriptions`
+### `integration_subscriptions`
 
-Cursor owner per `(integration_id, adapter, domain, external_ref)` tuple. The
+Cursor owner per `(connection_id, adapter, domain, external_ref)` tuple. The
 cursor store reads/writes it.
 
 | Column | Type | Notes |
 |---|---|---|
 | `id` | uuid PK | `defaultRandom()` |
-| `integration_id` | text | Opaque id of the connected account/instance (SFDC org id, GH installation id, …) |
+| `connection_id` | text | Opaque id of the connected account/instance (SFDC org id, GH installation id, …) |
 | `adapter` | text | Short adapter label: `'salesforce'`, `'hubspot'` |
 | `domain` | text | Canonical entity: `'opportunity'`, `'contact'` |
 | `external_ref` | text NULL | Upstream scope (filter id, webhook subscription id); NULL = full domain |
@@ -31,21 +31,21 @@ cursor store reads/writes it.
 | `config` | jsonb, default `{}` | Per-subscription config (`batchSize`, `highWatermark`, …) |
 | `cursor` | jsonb NULL | Opaque; written by the cursor store; NULL until first successful run |
 | `last_sync_at` | ts NULL | Stamped alongside `cursor` |
-| `tenant_id` | text NULL | Present only when `sync.multi_tenant: true` |
+| `tenant_id` | text NULL | Present only when `integration.multi_tenant: true` |
 | `created_at` / `updated_at` | ts | |
 
-Indexes: a unique `(integration_id, adapter, domain, external_ref)` tuple
+Indexes: a unique `(connection_id, adapter, domain, external_ref)` tuple
 (Postgres treats NULL `external_ref` as distinct — that's a consumer modeling
 concern), and an `(enabled, last_sync_at)` scheduling index.
 
-### `sync_runs`
+### `integration_runs`
 
-One row per `ExecuteSyncUseCase.execute()` invocation.
+One row per `ExecuteIntegrationUseCase.execute()` invocation.
 
 | Column | Type | Notes |
 |---|---|---|
 | `id` | uuid PK | |
-| `subscription_id` | uuid FK → `sync_subscriptions.id` (cascade) | |
+| `subscription_id` | uuid FK → `integration_subscriptions.id` (cascade) | |
 | `direction` | enum `inbound \| outbound` | Almost always `inbound`; `outbound` reserved for writeback |
 | `action` | enum `poll \| cdc \| webhook \| manual \| writeback` | Provenance for self-identification |
 | `status` | enum `running \| success \| no_changes \| failed` | `running` is in-flight only |
@@ -60,14 +60,14 @@ One row per `ExecuteSyncUseCase.execute()` invocation.
 Indexes: `(subscription_id, started_at)` for timelines, `(status, started_at)`
 for the stale-run sweeper.
 
-### `sync_run_items`
+### `integration_run_items`
 
 One row per upstream change processed within a run.
 
 | Column | Type | Notes |
 |---|---|---|
 | `id` | uuid PK | |
-| `sync_run_id` | uuid FK → `sync_runs.id` (cascade) | |
+| `integration_run_id` | uuid FK → `integration_runs.id` (cascade) | |
 | `entity_type` | text | Canonical domain (`'opportunity'`) |
 | `external_id` | text | Upstream id |
 | `local_id` | text NULL | Set on `created \| updated \| deleted`; null on `noop` |
@@ -79,7 +79,7 @@ One row per upstream change processed within a run.
 | `created_at` | ts, default now | |
 | `tenant_id` | text NULL | Present only when multi-tenant |
 
-Indexes: `(sync_run_id, created_at)` for within-run timelines,
+Indexes: `(integration_run_id, created_at)` for within-run timelines,
 `(entity_type, external_id)` for per-record history.
 
 ## The `changed_fields` contract
@@ -119,12 +119,12 @@ taste, augment the differ's ignore list in your feature module (see Diffing).
 
 ## Common queries
 
-**"What changed in the last 24 hours across all sync?"**
+**"What changed in the last 24 hours across all integration?"**
 
 ```sql
 SELECT sr.action, sri.entity_type, sri.external_id, sri.operation, sri.changed_fields
-FROM sync_run_items sri
-JOIN sync_runs sr ON sri.sync_run_id = sr.id
+FROM integration_run_items sri
+JOIN integration_runs sr ON sri.integration_run_id = sr.id
 WHERE sri.created_at > now() - interval '1 day'
   AND sri.status = 'success'
   AND sri.operation != 'noop'
@@ -135,7 +135,7 @@ ORDER BY sri.created_at DESC;
 
 ```sql
 SELECT id, adapter, domain, external_ref, last_sync_at
-FROM sync_subscriptions
+FROM integration_subscriptions
 WHERE enabled = true
   AND (last_sync_at IS NULL OR last_sync_at < now() - interval '1 hour')
 ORDER BY last_sync_at ASC NULLS FIRST;
@@ -147,7 +147,7 @@ mid-run without reaching the completion path)
 
 ```sql
 SELECT sr.id, sr.subscription_id, sr.started_at, sr.action
-FROM sync_runs sr
+FROM integration_runs sr
 WHERE sr.status = 'running'
   AND sr.started_at < now() - interval '10 minutes';
 ```
@@ -156,7 +156,7 @@ WHERE sr.status = 'running'
 
 ```sql
 SELECT sri.created_at
-FROM sync_run_items sri
+FROM integration_run_items sri
 WHERE sri.entity_type = 'opportunity'
   AND sri.external_id = '006Ab00000ABC'
   AND sri.changed_fields -> 'stage_name' ->> 'to' = 'Closed Won'
@@ -173,7 +173,7 @@ SELECT sri.external_id,
        sri.changed_fields -> 'amount' ->> 'from' AS old_amount,
        sri.changed_fields -> 'amount' ->> 'to'   AS new_amount,
        sri.created_at
-FROM sync_run_items sri
+FROM integration_run_items sri
 WHERE sri.entity_type = 'opportunity'
   AND sri.created_at > now() - interval '7 days'
   AND sri.changed_fields ? 'amount'
@@ -215,7 +215,7 @@ execute(input)
 ### Failure semantics worth memorizing
 
 1. **`assertTenantId` fires before `startRun`.** Rejected multi-tenant inputs
-   never open a `sync_runs` row — no dangling `status=running`. Backends
+   never open a `integration_runs` row — no dangling `status=running`. Backends
    re-validate at their write boundary (defense in depth).
 
 2. **Cursor advances per-yield, not per-success.** `latestCursor` updates on
@@ -289,7 +289,7 @@ as changes), but the diff output preserves the *raw* values:
 cannot remove defaults):
 
 ```ts
-{ provide: SYNC_FIELD_DIFFER, useValue: new DeepEqualDiffer({ ignore: ['sync_version'] }) }
+{ provide: INTEGRATION_FIELD_DIFFER, useValue: new DeepEqualDiffer({ ignore: ['integration_version'] }) }
 ```
 
 Bind it as `useValue: new DeepEqualDiffer(...)`, not `useClass` — the
@@ -299,4 +299,4 @@ constructor's optional options object confuses Nest's metadata reflection.
 columns changed, set it on the `Change<T>` and the differ skips deep-equal over
 untouched fields — but it still applies the ignore list. To write a fully
 custom differ (type-aware enum normalization, hint-only inspection), implement
-`IFieldDiffer<T>` and bind it to `SYNC_FIELD_DIFFER`.
+`IFieldDiffer<T>` and bind it to `INTEGRATION_FIELD_DIFFER`.