@pattern-stack/codegen 0.10.0 → 0.11.0

package/consumer-skills/{sync → integration}/change-sources-and-sinks.md

@@ -2,71 +2,71 @@
 
 # Change sources, sinks, and feature-module wiring
 
-How you wire a sync integration end to end: the per-entity feature module, the
-`IChangeSource<T>` adapter, the `ISyncSink<T>` write surface, the entity-YAML
+How you wire a integration integration end to end: the per-entity feature module, the
+`IChangeSource<T>` adapter, the `IIntegrationSink<T>` write surface, the entity-YAML
 `detection:` block, triggering runs, multi-tenancy, loopback, and testing.
 
-Everything imports from `@shared/subsystems/sync`.
+Everything imports from `@shared/subsystems/integration`.
 
 ## The per-entity feature module
 
-`SyncModule.forRoot(...)` in `AppModule` wires the substrate (cursor store, run
+`IntegrationModule.forRoot(...)` in `AppModule` wires the substrate (cursor store, run
 recorder, field differ, multi-tenant flag). For **each canonical entity you
-sync**, write a feature module that binds:
+integration**, write a feature module that binds:
 
-- `SYNC_CHANGE_SOURCE` — your adapter (one per `(provider, detection-mode, entity)`)
-- `SYNC_SINK` — your sink (one per canonical entity)
-- `ExecuteSyncUseCase` — the orchestrator class itself
-- optionally `SYNC_FIELD_DIFFER` (custom diff rules) and/or
-  `SYNC_LOOPBACK_FINGERPRINT_STORE`
+- `INTEGRATION_CHANGE_SOURCE` — your adapter (one per `(provider, detection-mode, entity)`)
+- `INTEGRATION_SINK` — your sink (one per canonical entity)
+- `ExecuteIntegrationUseCase` — the orchestrator class itself
+- optionally `INTEGRATION_FIELD_DIFFER` (custom diff rules) and/or
+  `INTEGRATION_LOOPBACK_FINGERPRINT_STORE`
 
 ```ts
 import { Module } from '@nestjs/common';
 import {
-  ExecuteSyncUseCase,
-  SYNC_CHANGE_SOURCE,
-  SYNC_SINK,
-  SYNC_FIELD_DIFFER,
+  ExecuteIntegrationUseCase,
+  INTEGRATION_CHANGE_SOURCE,
+  INTEGRATION_SINK,
+  INTEGRATION_FIELD_DIFFER,
   DeepEqualDiffer,
-} from '@shared/subsystems/sync';
+} from '@shared/subsystems/integration';
 
 @Module({
   providers: [
-    { provide: SYNC_CHANGE_SOURCE, useClass: SalesforceOpportunityChangeSource },
-    { provide: SYNC_SINK,          useClass: OpportunitySyncSink },
+    { provide: INTEGRATION_CHANGE_SOURCE, useClass: SalesforceOpportunityChangeSource },
+    { provide: INTEGRATION_SINK,          useClass: OpportunityIntegrationSink },
     // Override the differ per-entity when you need a wider ignore list:
     {
-      provide: SYNC_FIELD_DIFFER,
-      useValue: new DeepEqualDiffer({ ignore: ['sync_version', 'internal_notes'] }),
+      provide: INTEGRATION_FIELD_DIFFER,
+      useValue: new DeepEqualDiffer({ ignore: ['integration_version', 'internal_notes'] }),
     },
-    ExecuteSyncUseCase,
+    ExecuteIntegrationUseCase,
   ],
-  exports: [ExecuteSyncUseCase],
+  exports: [ExecuteIntegrationUseCase],
 })
-export class OpportunitySyncModule {}
+export class OpportunityIntegrationModule {}
 ```
 
-**Why `ExecuteSyncUseCase` lives here and not in `SyncModule`:** the
-orchestrator depends on `SYNC_CHANGE_SOURCE` + `SYNC_SINK`, which are
+**Why `ExecuteIntegrationUseCase` lives here and not in `IntegrationModule`:** the
+orchestrator depends on `INTEGRATION_CHANGE_SOURCE` + `INTEGRATION_SINK`, which are
 per-feature. Nest resolves providers at module compile time; putting the
-orchestrator in the global `SyncModule` would require those tokens globally,
+orchestrator in the global `IntegrationModule` would require those tokens globally,
 which fails until your feature module is imported.
 
-Inject `ExecuteSyncUseCase<CanonicalOpportunity>` wherever you trigger a run —
+Inject `ExecuteIntegrationUseCase<CanonicalOpportunity>` wherever you trigger a run —
 a scheduled job, a CLI command, a webhook handler, an operator UI button.
 
 ## Writing an `IChangeSource<T>`
 
 The one port every adapter implements. The signature is
-`listChanges(subscription, cursor): AsyncIterable<Change<T>>`:
+`listChanges(subscription, cursor): AintegrationIterable<Change<T>>`:
 
 ```ts
 interface IChangeSource<T> {
   readonly label: string;  // e.g. 'salesforce-poll-opportunity'
   listChanges(
-    subscription: SyncSubscriptionView,
+    subscription: IntegrationSubscriptionView,
     cursor: unknown | null,
-  ): AsyncIterable<Change<T>>;
+  ): AintegrationIterable<Change<T>>;
 }
 
 interface Change<T> {
@@ -84,7 +84,7 @@ A worked poll adapter:
 
 ```ts
 import { Injectable } from '@nestjs/common';
-import type { IChangeSource, Change, SyncSubscriptionView } from '@shared/subsystems/sync';
+import type { IChangeSource, Change, IntegrationSubscriptionView } from '@shared/subsystems/integration';
 
 @Injectable()
 export class SalesforceOpportunityChangeSource
@@ -98,9 +98,9 @@ export class SalesforceOpportunityChangeSource
   ) {}
 
   async *listChanges(
-    sub: SyncSubscriptionView,
+    sub: IntegrationSubscriptionView,
     cursor: unknown | null,
-  ): AsyncIterable<Change<CanonicalOpportunity>> {
+  ): AintegrationIterable<Change<CanonicalOpportunity>> {
     const typed = cursor as { systemModstamp?: string } | null;
     const since = typed?.systemModstamp ?? '1970-01-01T00:00:00Z';
 
@@ -151,14 +151,14 @@ export class SalesforceOpportunityChangeSource
 methods** to `IChangeSource`; if a new mode emerges, add a value to the
 `source` union and a metadata field, not a new port.
 
-## Writing an `ISyncSink<T>`
+## Writing an `IIntegrationSink<T>`
 
 One sink per canonical entity. It speaks the *canonical* shape externally;
 internal mapping (canonical → local columns, EAV dual-write, FK resolution)
 stays inside:
 
 ```ts
-interface ISyncSink<TCanonical> {
+interface IIntegrationSink<TCanonical> {
   findByExternalId(userId: string, externalId: string): Promise<TCanonical | null>;
   upsertByExternalId(userId: string, record: TCanonical, provider: string): Promise<{ id: string; saved: TCanonical }>;
   softDeleteByExternalId(userId: string, externalId: string): Promise<{ id: string } | null>;
@@ -167,7 +167,7 @@ interface ISyncSink<TCanonical> {
 
 ```ts
 @Injectable()
-export class OpportunitySyncSink implements ISyncSink<CanonicalOpportunity> {
+export class OpportunityIntegrationSink implements IIntegrationSink<CanonicalOpportunity> {
   constructor(
     @Inject(DRIZZLE) private readonly db: DrizzleClient,
     private readonly opportunities: OpportunityService,
@@ -208,7 +208,7 @@ export class OpportunitySyncSink implements ISyncSink<CanonicalOpportunity> {
   dual-write (canonical columns + custom-field rows), `user_id` + `provider`
   stamping all happen inside its transaction. The subsystem never reaches around
   the sink to write local tables. **Return the local id** so the orchestrator
-  can record it on `sync_run_items.local_id`.
+  can record it on `integration_run_items.local_id`.
 - **Re-entry tolerance is the sink's job.** A webhook retry or polling overlap
   can deliver the same record twice — make the upsert idempotent (typically
   `ON CONFLICT (external_id) DO UPDATE` with no-op semantics when nothing
@@ -222,7 +222,7 @@ integration provider:
 
 ```yaml
 # entities/opportunity.yaml
-sync:
+integration:
   providers:
     hubspot-crm:    { remote_entity: deal,        direction: inbound }
     salesforce-crm: { remote_entity: Opportunity, direction: inbound }
@@ -240,7 +240,7 @@ detection:
     filters: [ ... ]
 ```
 
-Codegen emits exactly one `<entity>-sync-source.module.ts` per entity,
+Codegen emits exactly one `<entity>-integration-source.module.ts` per entity,
 regardless of provider count. It exports two runtime symbols (plus the module
 class):
 
@@ -260,13 +260,13 @@ Wire your fetch callbacks in a feature module:
 import {
   OPPORTUNITY_POLL_FETCH_REGISTRY,
   OPPORTUNITY_CHANGE_SOURCES,
-  OpportunitySyncSourceModule,
-} from '@modules/opportunity-sync-source.module';
-import type { OpportunityProvider } from '@modules/opportunity-sync-source.providers';
+  OpportunityIntegrationSourceModule,
+} from '@modules/opportunity-integration-source.module';
+import type { OpportunityProvider } from '@modules/opportunity-integration-source.providers';
 import { hubspotFetchOpportunities, salesforceFetchOpportunities } from './my-fetches';
 
 @Module({
-  imports: [OpportunitySyncSourceModule],
+  imports: [OpportunityIntegrationSourceModule],
   providers: [
     {
       provide: OPPORTUNITY_POLL_FETCH_REGISTRY,
@@ -277,10 +277,10 @@ import { hubspotFetchOpportunities, salesforceFetchOpportunities } from './my-fe
     },
   ],
 })
-export class OpportunitySyncWiringModule {}
+export class OpportunityIntegrationWiringModule {}
 ```
 
-The sibling `<entity>-sync-source.providers.ts` artifact exports the
+The sibling `<entity>-integration-source.providers.ts` artifact exports the
 `<EntityName>Provider` literal-union type — using `Record<OpportunityProvider, …>`
 (or the `satisfies` form above) turns a provider-key typo into a compile error.
 
@@ -291,7 +291,7 @@ services.
 
 ## Triggering a run
 
-`ExecuteSyncUseCase` does not schedule itself. Common triggers:
+`ExecuteIntegrationUseCase` does not schedule itself. Common triggers:
 
 **Scheduled job (typical polling)** — wrap the use case in a normal background
 job on one of *your own* pools (never a reserved `events_*` pool — those belong
@@ -299,14 +299,14 @@ to the event/bridge machinery and throw at boot) and give it a cron trigger
 (see the `jobs` skill for the handler shape + scheduling):
 
 ```ts
-@JobHandler<{ subscriptionId: string; tenantId?: string }>('sync_opportunity_poll', {
+@JobHandler<{ subscriptionId: string; tenantId?: string }>('integration_opportunity_poll', {
   pool: 'batch',
 })
-export class SyncOpportunityPollHandler extends JobHandlerBase<{
+export class IntegrationOpportunityPollHandler extends JobHandlerBase<{
   subscriptionId: string;
   tenantId?: string;
 }> {
-  constructor(private readonly execute: ExecuteSyncUseCase<CanonicalOpportunity>) {
+  constructor(private readonly execute: ExecuteIntegrationUseCase<CanonicalOpportunity>) {
     super();
   }
 
@@ -347,7 +347,7 @@ await this.execute.execute({
 });
 ```
 
-## Emitting events on successful sync
+## Emitting events on successful integration
 
 The orchestrator does not emit events — wire `TypedEventBus.publish(...)`
 inside your sink's `upsertByExternalId` transaction, after the row is saved, so
@@ -372,18 +372,18 @@ consumers subscribe via their own handlers. See the `events` skill.
 
 Three things change when `multi_tenant: true`:
 
-1. **`SyncModule.forRoot({ backend: 'drizzle', multiTenant: true })`** in
+1. **`IntegrationModule.forRoot({ backend: 'drizzle', multiTenant: true })`** in
    `AppModule` — binds the multi-tenant flag the orchestrator and Drizzle
    backends inject.
 2. **Every `execute()` call passes `tenantId`.** Missing/null throws
-   `MissingTenantIdError` at entry, *before* a `sync_runs` row is opened (no
+   `MissingTenantIdError` at entry, *before* a `integration_runs` row is opened (no
    dangling `status=running` rows). The Drizzle backends re-validate at their
    write boundary (defense in depth); all sites share one helper so error
    messages match. Explicit `null` is allowed only for deliberate cross-tenant
    work.
-3. **Schema gains `tenant_id` columns** on all three sync tables. Flip
-   `sync.multi_tenant: true` in `codegen.config.yaml`, re-run
-   `subsystem install sync --force --force-config` to re-emit the schema, then
+3. **Schema gains `tenant_id` columns** on all three integration tables. Flip
+   `integration.multi_tenant: true` in `codegen.config.yaml`, re-run
+   `subsystem install integration --force --force-config` to re-emit the schema, then
    apply the migration **before** flipping the module flag — otherwise the
    Drizzle backends throw `column "tenant_id" does not exist` on every write.
 
@@ -402,7 +402,7 @@ interface ILoopbackFingerprintStore<T = unknown> {
   isEchoOfOwnWrite(entityType: string, externalId: string, record: T): Promise<boolean>;
 }
 
-{ provide: SYNC_LOOPBACK_FINGERPRINT_STORE, useClass: RedisLoopbackStore }
+{ provide: INTEGRATION_LOOPBACK_FINGERPRINT_STORE, useClass: RedisLoopbackStore }
 ```
 
 Record a fingerprint (hash of the canonicalized record, TTL **shorter than the
@@ -414,20 +414,20 @@ verify suppression in the audit log; the sink is never called.
 
 ## Testing
 
-`SyncModule.forRoot({ backend: 'memory' })` plus memory feature-module fakes
+`IntegrationModule.forRoot({ backend: 'memory' })` plus memory feature-module fakes
 gives an end-to-end test with no Postgres:
 
 ```ts
-import { SyncModule, MemoryRunRecorder } from '@shared/subsystems/sync';
+import { IntegrationModule, MemoryRunRecorder } from '@shared/subsystems/integration';
 
 const moduleRef = await Test.createTestingModule({
   imports: [
-    SyncModule.forRoot({ backend: 'memory' }),
-    OpportunitySyncTestModule,  // same shape as the real feature module, with fakes
+    IntegrationModule.forRoot({ backend: 'memory' }),
+    OpportunityIntegrationTestModule,  // same shape as the real feature module, with fakes
   ],
 }).compile();
 
-const orch = moduleRef.get(ExecuteSyncUseCase);
+const orch = moduleRef.get(ExecuteIntegrationUseCase);
 const recorder = moduleRef.get(MemoryRunRecorder);
 
 await orch.execute({ /* ... */ });

package/consumer-skills/subsystems/SKILL.md

@@ -2,7 +2,7 @@
 name: subsystems
 description: >-
   Load when installing or wiring an infrastructure subsystem in a project that
-  uses @pattern-stack/codegen — events, jobs, cache, storage, sync, bridge,
+  uses @pattern-stack/codegen — events, jobs, cache, storage, integration, bridge,
   observability, auth, or the OpenAPI config. Covers `codegen subsystem
   install`, the `forRoot` registration ORDER in app.module.ts, which subsystems
   depend on which, and multi-tenancy opt-in. Get the order wrong and the bridge
@@ -17,7 +17,7 @@ user-invocable: false
 # Infrastructure subsystems
 
 Subsystems are the generated infrastructure your use cases call: an event bus,
-a job queue, a cache, file storage, an external-sync engine, the event-to-job
+a job queue, a cache, file storage, an external-integration engine, the event-to-job
 bridge, a read-only observability facade, and OAuth auth. Each follows one
 pattern — **Protocol (port) → Backend (adapter) → Factory (`DynamicModule.
 forRoot`)** — and each is `global: true`, so you register it once in
@@ -33,7 +33,7 @@ forRoot`)** — and each is `global: true`, so you register it once in
   (Postgres) production backend and a memory backend for tests. Swap via the
   `forRoot({ backend })` arg — app code is unchanged.
 - **Order matters.** Some subsystems consume others. The bridge consumes events
-  + jobs; observability composes events/jobs/bridge/sync read ports via
+  + jobs; observability composes events/jobs/bridge/integration read ports via
   optional DI. Registering them in the wrong order means a silently idle bridge
   or an observability facade that reports nothing. See `wiring-and-order.md`.
 
@@ -45,11 +45,11 @@ forRoot`)** — and each is `global: true`, so you register it once in
 | jobs | `JobsDomainModule` + `JobWorkerModule` | `subsystem install jobs` | — |
 | cache | `CacheModule` | `subsystem install cache` | jobs (optional, for cleanup) |
 | storage | `StorageModule` | `subsystem install storage` | — |
-| sync | `SyncModule` | `subsystem install sync` | — |
+| integration | `IntegrationModule` | `subsystem install integration` | — |
 | bridge | `BridgeModule` | `subsystem install bridge` | **events + jobs** |
-| observability | `ObservabilityModule` | `subsystem install observability` | composes events/jobs/bridge/sync (optional) |
+| observability | `ObservabilityModule` | `subsystem install observability` | composes events/jobs/bridge/integration (optional) |
 | auth | `AuthModule` | `subsystem install auth` | — |
-| auth-integrations | `IntegrationsAuthModule` | `subsystem install auth-integrations` | **auth** |
+| auth-integrations | `ConnectionsAuthModule` | `subsystem install auth-integrations` | **auth** |
 | openapi | (config only) | `subsystem install openapi-config` | registry vendored at init |
 
 ## Registration order (authoritative)
@@ -60,13 +60,13 @@ In `app.module.ts`, import in this order (omit what you haven't installed):
 2. `OpenApiModule` — the registry singleton (vendored at init).
 3. `EventsModule.forRoot(...)`
 4. `JobsDomainModule.forRoot(...)` **and** `JobWorkerModule.forRoot(...)`
-5. `CacheModule` / `StorageModule` / `SyncModule.forRoot(...)`
+5. `CacheModule` / `StorageModule` / `IntegrationModule.forRoot(...)`
 6. `BridgeModule.forRoot(...)` — **after** events + jobs.
 7. `ObservabilityModule.forRoot(...)` — **last** of the subsystems (composes the
    ones above via optional DI).
 8. `...GENERATED_MODULES` — your entity modules.
 
-For auth: register `AuthModule.forRoot(...)` before the `IntegrationsAuthModule`
+For auth: register `AuthModule.forRoot(...)` before the `ConnectionsAuthModule`
 that depends on it. Full per-subsystem `forRoot` signatures, the bridge reserved
 pools, and multi-tenancy are in `wiring-and-order.md`.
 
@@ -87,8 +87,42 @@ pools, and multi-tenancy are in `wiring-and-order.md`.
   must be registered after them.
 - **Multi-tenancy is a config flip + a `forRoot` flag + a migration** — never a
   runtime-only toggle. See `wiring-and-order.md`.
+- **`subsystem list` can report `incomplete`, and that's usually fine.**
+  Installing one subsystem may vendor *stub* files of another — e.g. installing
+  `events` drops `bridge/bridge.protocol.ts` + `bridge.tokens.ts` because the
+  events Drizzle backend imports them. That `bridge/` directory has the protocol
+  stubs but no `bridge.module.ts`, so `subsystem list` shows it `incomplete`. It
+  is **not** registered in the generated `subsystems.ts` barrel (the barrel only
+  emits a `forRoot()` for subsystems whose `<name>.module.ts` exists), so it
+  won't break your `tsc`. Run `subsystem install bridge` to promote it to
+  `installed` when you actually want the bridge.
 - **`--backend memory`** is for tests; the scaffolded default is `drizzle`
   (`local` for storage).
+- **Install vendors only the selected backend.** Alternate-backend source
+  files are pruned: a `--backend drizzle` events install does NOT vendor
+  `event-bus.redis-backend.ts`, and a drizzle/memory jobs install does NOT
+  vendor `job-orchestrator.bullmq-backend.ts`, `job-worker.bullmq-backend.ts`,
+  or `bullmq.config.ts`. The module files (`events.module.ts`,
+  `jobs-domain.module.ts`, `job-worker.module.ts`) lazy-load the chosen
+  backend via dynamic `import()` with a non-literal specifier, so the unused
+  backends never drag their peer deps (`ioredis`, `bullmq`) into your `tsc`
+  graph. `bullmq` and `ioredis` are declared as **optional peer
+  dependencies** — install them ONLY if you actually select that backend.
+  **Drizzle installs no longer drag `bullmq` / `ioredis` into your consumer
+  peer-deps**; if your `package.json` carries them only as workarounds for
+  earlier 0.10.x scaffolds, you can drop them.
+- **Bundler caveat.** The dynamic-import specifier is captured in a variable
+  (e.g. `const spec = './event-bus.redis-backend'; await import(spec)`) on
+  purpose — that's what makes `tsc` treat it as `any` and skip resolving the
+  pruned file. A bundler (webpack / esbuild / rollup) won't static-analyse a
+  non-literal specifier either, so it won't include the dynamically-imported
+  file in its output bundle. In practice this is fine: when the file isn't
+  vendored (drizzle install) there's nothing to bundle; when it IS vendored
+  (redis / bullmq install) consumers typically run Node/Bun directly against
+  the source tree. If you bundle a redis/bullmq build for deployment, ensure
+  your bundler is configured to include the vendored
+  `<subsystems-root>/<name>/` tree (e.g. mark it as external + ship alongside)
+  or pin the dynamic-import path to a literal in your own wrapper.
 
 ## Do not
 
@@ -103,3 +137,25 @@ pools, and multi-tenancy are in `wiring-and-order.md`.
   runtime source, not the tenancy-gated Drizzle schema files. If a schema shape
   changed across versions, re-run `subsystem install <name> --force
   --force-config`.
+
+## Removing a subsystem
+
+`codegen subsystem remove <name>` deletes the vendored
+`<subsystems-root>/<name>/` directory and regenerates
+`src/generated/subsystems.ts` so the removed subsystem drops out of the
+`SUBSYSTEM_MODULES` barrel. Git-safety gated like install (warns on
+uncommitted changes; `--force` overrides). `--yes`/`-y` is accepted for flag
+parity with `install`.
+
+What removal does NOT do (intentionally — explicit beats silent rewrites):
+
+- It does **not** strip the `<name>:` block from `codegen.config.yaml`.
+- It does **not** remove the `<Name>Module.forRoot(...)` line from
+  `app.module.ts`.
+- It does **not** strip shared runtime deps (`src/shared/types/drizzle.ts`,
+  `src/shared/constants/tokens.ts`) — other subsystems may still need them.
+
+The CLI prints the two follow-up edits on success. `openapi-config` (a
+config-only pseudo-subsystem) and `auth-integrations` (vendored outside the
+subsystems root, alongside the codegen-emitted entity layer) are not
+auto-removable — the command errors with the right manual next-step.

package/consumer-skills/subsystems/wiring-and-order.md

@@ -17,7 +17,7 @@ import { EventsModule } from '@shared/subsystems/events';
 import { JobsDomainModule, JobWorkerModule } from '@shared/subsystems/jobs';
 import { CacheModule } from '@shared/subsystems/cache';
 import { StorageModule } from '@shared/subsystems/storage';
-import { SyncModule } from '@shared/subsystems/sync';
+import { IntegrationModule } from '@shared/subsystems/integration';
 import { BridgeModule, BRIDGE_RESERVED_POOLS } from '@shared/subsystems/bridge';
 import { ObservabilityModule } from '@shared/subsystems/observability';
 
@@ -44,10 +44,10 @@ class OpenApiModule {}
       // include the bridge's reserved pools so wrappers actually drain:
       pools: ['interactive', 'batch', ...BRIDGE_RESERVED_POOLS],
     }),
-    // 5. cache / storage / sync
+    // 5. cache / storage / integration
     CacheModule.forRoot({ backend: 'drizzle' }),
     StorageModule.forRoot({ backend: 'local' }),
-    SyncModule.forRoot({ backend: 'drizzle' }),
+    IntegrationModule.forRoot({ backend: 'drizzle' }),
     // 6. bridge — AFTER events + jobs
     BridgeModule.forRoot({ backend: 'drizzle', multiTenant: false }),
     // 7. observability — LAST (composes the siblings above)
@@ -68,10 +68,10 @@ export class AppModule {}
 | `JobWorkerModule` | `forRoot({ mode, backend?, pools?, allPools?, shutdownTimeoutMs? })` | `mode: 'embedded' \| 'standalone'`. `pools` = active pool names this process drains (defaults to all non-reserved). `allPools: true` drains every pool incl. reserved. |
 | `CacheModule` | `forRoot({ backend })` | optionally registers a cleanup job when jobs is present. |
 | `StorageModule` | `forRoot({ backend })` | `backend: 'local' \| 'memory'`. Implement S3/GCS by implementing the storage protocol. |
-| `SyncModule` | `forRoot({ backend, multiTenant? })` | wires the cursor store / run recorder / differ ports — NOT the orchestrator (that's per-entity; see the `sync` skill). |
+| `IntegrationModule` | `forRoot({ backend, multiTenant? })` | wires the cursor store / run recorder / differ ports — NOT the orchestrator (that's per-entity; see the `integration` skill). |
 | `BridgeModule` | `forRoot({ backend, multiTenant? })` | must come after events + jobs; fails fast at boot if reserved pools aren't polled. |
 | `ObservabilityModule` | `forRoot({ reporters? })` | read-only facade; `reporters.bridgeMetrics: true` opts into the 60s bridge sampler. Register last. |
-| `AuthModule` | `forRoot({ encryptionKey, oauthStateStore })` | `global: true`; provides `ENCRYPTION_KEY` + `OAUTH_STATE_STORE`. Register before `IntegrationsAuthModule`. |
+| `AuthModule` | `forRoot({ encryptionKey, oauthStateStore })` | `global: true`; provides `ENCRYPTION_KEY` + `OAUTH_STATE_STORE`. Register before `ConnectionsAuthModule`. |
 
 ## Pool configuration (jobs)
 
@@ -90,7 +90,7 @@ jobs:
 `JobWorkerModule.forRoot({ pools })` then names which of those a given worker
 process drains — scale horizontally by running one worker per pool subset.
 
-## Multi-tenancy opt-in (events / jobs / sync / bridge)
+## Multi-tenancy opt-in (events / jobs / integration / bridge)
 
 Three coordinated steps — never a runtime-only toggle:
 
@@ -110,7 +110,7 @@ tenant-less / cross-tenant work).
 - **bridge → events + jobs.** The bridge claims `domain_events` rows and starts
   wrapper job runs in the reserved pools. Without events + jobs registered (and
   the reserved pools polled) it has nothing to consume and nowhere to write.
-- **observability → events/jobs/bridge/sync (optional).** It composes the read
+- **observability → events/jobs/bridge/integration (optional).** It composes the read
   ports of whatever siblings exist, via optional DI. Register it last so those
   ports are already bound; missing siblings are simply omitted from its output.
 - **auth-integrations → auth.** The integration adapters need the encryption key

package/dist/runtime/base-classes/index.d.ts

@@ -3,13 +3,13 @@ export { RequesterContext, RequesterScope, requireRequester, requireRequesterSco
 export { BaseService, IBaseRepository } from './base-service.js';
 export { EventCategory, buildChangeEvents, buildLifecycleEvent, diffSnapshots, emitSafely, entitySnapshot } from './lifecycle-events.js';
 export { BaseFindByIdUseCase, BaseListUseCase, IFindByIdService, IListService } from './base-read-use-cases.js';
-export { SyncFkResolver, SyncUpsertConfig } from './sync-upsert-config.js';
-export { SyncedEntityRepository } from './synced-entity-repository.js';
-export { JunctionSyncConfig, JunctionSyncRepository, buildCompositeExternalId, parseCompositeExternalId } from './junction-sync-repository.js';
+export { IntegrationFkResolver, IntegrationUpsertConfig } from './integration-upsert-config.js';
+export { IntegratedEntityRepository } from './integrated-entity-repository.js';
+export { JunctionIntegrationConfig, JunctionIntegrationRepository, buildCompositeExternalId, parseCompositeExternalId } from './junction-integration-repository.js';
 export { ActivityEntityRepository } from './activity-entity-repository.js';
 export { MetadataEntityRepository } from './metadata-entity-repository.js';
 export { KnowledgeEntityRepository } from './knowledge-entity-repository.js';
-export { ISyncedEntityRepository, SyncedEntityService } from './synced-entity-service.js';
+export { IIntegratedEntityRepository, IntegratedEntityService } from './integrated-entity-service.js';
 export { ActivityEntityService, IActivityEntityRepository } from './activity-entity-service.js';
 export { IMetadataEntityRepository, MetadataEntityService } from './metadata-entity-service.js';
 export { KnowledgeEntityService } from './knowledge-entity-service.js';