@pattern-stack/codegen 0.10.0 → 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/events/event-bus.drizzle-backend.ts

@@ -59,17 +59,16 @@ const POLL_BATCH_SIZE = 50;
  * the per-event extraction logic in one place so publish/publishMany stay
  * in sync.
  */
-function toInsertValues(event: DomainEvent) {
+function toInsertValues(event: DomainEvent, multiTenant: boolean) {
   const metadata = event.metadata ?? undefined;
   const pool = (metadata?.['pool'] as string | undefined) ?? null;
   const direction = (metadata?.['direction'] as string | undefined) ?? null;
-  const tenantId = (metadata?.['tenantId'] as string | undefined) ?? null;
   // AUDIT-1: tier defaults to 'domain' when absent. The DB CHECK
   // constraint (`domain_events_tier_routing_check`) enforces the
   // tier ⇔ routing-fields invariant at the storage boundary; no
   // JS-side assertion is needed here.
   const tier = (metadata?.['tier'] as string | undefined) ?? 'domain';
-  return {
+  const base = {
     id: event.id,
     type: event.type,
     aggregateId: event.aggregateId,
@@ -82,8 +81,14 @@ function toInsertValues(event: DomainEvent) {
     pool,
     direction,
     tier,
-    tenantId,
   };
+  // EVT-8: `tenant_id` is a scaffold-time conditional column, emitted only
+  // when `events.multi_tenant: true`. Only write it when multi-tenancy is
+  // on — under single-tenant scaffolds the column does not exist, so the
+  // key must be omitted from the insert.
+  if (!multiTenant) return base;
+  const tenantId = (metadata?.['tenantId'] as string | undefined) ?? null;
+  return { ...base, tenantId };
 }
 
 /**
@@ -107,7 +112,11 @@ function toEventSummary(r: DomainEventRecord) {
     direction: r.direction,
     tier: r.tier,
     rootRunId: typeof rootRunId === 'string' ? rootRunId : null,
-    tenantId: r.tenantId,
+    // EVT-8: `tenant_id` is a scaffold-time conditional column. Read it
+    // structurally so this projection typechecks against both the
+    // multi-tenant schema (column present) and the single-tenant schema
+    // (column absent → undefined → null).
+    tenantId: (r as { tenantId?: string | null }).tenantId ?? null,
     occurredAt:
       r.occurredAt instanceof Date
         ? r.occurredAt
@@ -175,13 +184,17 @@ export class DrizzleEventBus implements IEventBus, IEventReadPort, OnModuleInit,
 
   async publish(event: DomainEvent, tx?: DrizzleTransaction): Promise<void> {
     const client = (tx ?? this.db) as DrizzleClient;
-    await client.insert(domainEvents).values(toInsertValues(event));
+    const multiTenant = this.opts.multiTenant ?? false;
+    await client.insert(domainEvents).values(toInsertValues(event, multiTenant));
   }
 
   async publishMany(events: DomainEvent[], tx?: DrizzleTransaction): Promise<void> {
     if (events.length === 0) return;
     const client = (tx ?? this.db) as DrizzleClient;
-    await client.insert(domainEvents).values(events.map(toInsertValues));
+    const multiTenant = this.opts.multiTenant ?? false;
+    await client
+      .insert(domainEvents)
+      .values(events.map((e) => toInsertValues(e, multiTenant)));
   }
 
   async findById(eventId: string): Promise<DomainEvent | null> {
@@ -241,11 +254,20 @@ export class DrizzleEventBus implements IEventBus, IEventReadPort, OnModuleInit,
         sql`${domainEvents.metadata}->>'rootRunId' = ${query.rootRunId}`,
       );
     }
-    if (query.tenantId !== undefined) {
+    // EVT-8: `tenant_id` is a scaffold-time conditional column (emitted only
+    // under `events.multi_tenant: true`). Guard the filter behind the same
+    // `multiTenant` flag, and read the column structurally so this backend
+    // typechecks against both the multi-tenant schema (column present) and
+    // the single-tenant schema (column absent). When multi-tenancy is off
+    // there is no `tenant_id` column to filter on.
+    if (this.opts.multiTenant && query.tenantId !== undefined) {
+      const tenantIdColumn = (
+        domainEvents as unknown as { tenantId: typeof domainEvents.pool }
+      ).tenantId;
       conditions.push(
         query.tenantId === null
-          ? (sql`${domainEvents.tenantId} is null` as SQL<unknown>)
-          : eq(domainEvents.tenantId, query.tenantId),
+          ? (sql`${tenantIdColumn} is null` as SQL<unknown>)
+          : eq(tenantIdColumn, query.tenantId),
       );
     }
 

package/runtime/subsystems/events/events.module.ts

@@ -57,9 +57,27 @@ import { DRIZZLE } from '../../constants/tokens';
 import type { DrizzleClient } from '../../types/drizzle';
 import { DrizzleEventBus } from './event-bus.drizzle-backend';
 import { MemoryEventBus } from './event-bus.memory-backend';
-import { RedisEventBus } from './event-bus.redis-backend';
+// #6 — `RedisEventBus` is lazy-loaded only when `backend: 'redis'` is selected.
+// The file is filtered out of the vendor set for non-redis installs (see
+// `backendFileFilter` in src/cli/commands/subsystem.ts); the dynamic-string
+// import below makes TS treat the specifier as `any` so the consumer's tsc
+// never tries to resolve the absent file.
 import { TypedEventBus } from './generated/bus';
 
+/**
+ * Lazy-load the Redis backend. Routed through a non-literal specifier so
+ * the consumer's `tsc` doesn't resolve `./event-bus.redis-backend` at type
+ * check time — important because that file is filtered out of drizzle/
+ * memory installs (#6).
+ */
+async function loadRedisEventBus(): Promise<new (url: string) => object> {
+  // Non-literal specifier — TS gives this an `any` module type, sidestepping
+  // resolution of a file that may not be vendored.
+  const specifier = './event-bus.redis-backend';
+  const mod = (await import(specifier)) as { RedisEventBus: new (url: string) => object };
+  return mod.RedisEventBus;
+}
+
 export interface EventsModuleOptions {
   backend: 'drizzle' | 'memory' | 'redis';
   /**
@@ -124,11 +142,11 @@ function buildTypedBusProviders(multiTenant: boolean): Provider[] {
  * drizzle backend is selected but no DRIZZLE provider is registered, we
  * throw a clear error instead of silently constructing a broken bus.
  */
-function buildEventBusAsync(
+async function buildEventBusAsync(
   options: EventsModuleOptions,
   db: DrizzleClient | null,
   redisUrl: string,
-): unknown {
+): Promise<unknown> {
   if (options.backend === 'drizzle') {
     if (!db) {
       throw new Error(
@@ -139,6 +157,9 @@ function buildEventBusAsync(
     return new DrizzleEventBus(db, options);
   }
   if (options.backend === 'redis') {
+    // #6: lazy import — the redis backend ships only with `--backend redis`
+    // installs; drizzle/memory consumers never touch the file.
+    const RedisEventBus = await loadRedisEventBus();
     return new RedisEventBus(redisUrl);
   }
   return new MemoryEventBus(options);
@@ -214,9 +235,20 @@ export class EventsModule {
         providers: [
           { provide: EVENTS_MODULE_OPTIONS, useValue: options },
           { provide: REDIS_URL, useValue: resolvedUrl },
-          { provide: EVENT_BUS, useClass: RedisEventBus },
-          // Register concrete class so NestJS can resolve lifecycle hooks
-          RedisEventBus,
+          {
+            // #6: useFactory + dynamic import so the consumer's tsc never
+            // needs to resolve `event-bus.redis-backend.ts` for drizzle/
+            // memory installs (the file is filtered out by
+            // `backendFileFilter`). Nest awaits async factories + manages
+            // lifecycle on the returned instance, so we drop the old bare
+            // `RedisEventBus` provider entry.
+            provide: EVENT_BUS,
+            useFactory: async (url: string): Promise<object> => {
+              const RedisEventBus = await loadRedisEventBus();
+              return new RedisEventBus(url);
+            },
+            inject: [REDIS_URL],
+          },
           ...buildTypedBusProviders(multiTenant),
         ],
         exports: [EVENT_BUS, TYPED_EVENT_BUS, EVENTS_MULTI_TENANT],

package/runtime/subsystems/events/index.ts

@@ -23,6 +23,12 @@ export { EventsModule } from './events.module';
 export type { EventsModuleOptions } from './events.module';
 export { MemoryEventBus } from './event-bus.memory-backend';
 export { DrizzleEventBus } from './event-bus.drizzle-backend';
-export { RedisEventBus } from './event-bus.redis-backend';
+// #6 — backend-specific implementation classes are NOT re-exported here.
+// `RedisEventBus` is only vendored when the consumer installs with
+// `--backend redis`; surfacing it from this barrel would force the consumer's
+// tsc to resolve `./event-bus.redis-backend` even on a drizzle/memory install
+// (the file is filtered out → TS2307). Consumers who select redis import the
+// class directly from `./event-bus.redis-backend` if they need it at all —
+// `EventsModule.forRoot({ backend: 'redis' })` lazy-loads it internally.
 export { domainEvents } from './domain-events.schema';
 export type { DomainEventRecord } from './domain-events.schema';

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';