@pattern-stack/codegen 0.10.0 → 0.11.0

package/runtime/subsystems/{sync/sync.module.ts → integration/integration.module.ts}

@@ -1,31 +1,31 @@
 /**
- * SyncModule — `DynamicModule.forRoot({ backend, multiTenant? })` factory
- * wiring the sync subsystem's substrate (SYNC-6, ADR-008 subsystem pattern).
+ * IntegrationModule — `DynamicModule.forRoot({ backend, multiTenant? })` factory
+ * wiring the integration subsystem's substrate (SYNC-6, ADR-008 subsystem pattern).
  *
  * ## What this module provides
  *
- *   - `SYNC_CURSOR_STORE`    — Drizzle or Memory cursor store
- *   - `SYNC_RUN_RECORDER`    — Drizzle or Memory run recorder
- *   - `SYNC_FIELD_DIFFER`    — default `DeepEqualDiffer`
- *   - `SYNC_MULTI_TENANT`    — resolved boolean flag (defaults to false)
- *   - `SYNC_MODULE_OPTIONS`  — the options object itself, for backends
+ *   - `INTEGRATION_CURSOR_STORE`    — Drizzle or Memory cursor store
+ *   - `INTEGRATION_RUN_RECORDER`    — Drizzle or Memory run recorder
+ *   - `INTEGRATION_FIELD_DIFFER`    — default `DeepEqualDiffer`
+ *   - `INTEGRATION_MULTI_TENANT`    — resolved boolean flag (defaults to false)
+ *   - `INTEGRATION_MODULE_OPTIONS`  — the options object itself, for backends
  *     that need to inspect config at construction time
  *
  * ## What this module does NOT provide
  *
- *   - `SYNC_CHANGE_SOURCE` — per-provider per-entity; consumer binds in
- *     their feature module (e.g. `OpportunitySyncModule` provides a
+ *   - `INTEGRATION_CHANGE_SOURCE` — per-provider per-entity; consumer binds in
+ *     their feature module (e.g. `OpportunityIntegrationModule` provides a
  *     `SalesforceOpportunityChangeSource`). Loopback suppression — when
  *     needed — is composed into the primitive's middleware chain via
  *     `createLoopbackMiddleware(store)` (#226-5 / ADR-033); the
  *     orchestrator no longer accepts a fingerprint store directly.
- *   - `SYNC_SINK` — per canonical entity; consumer binds in their feature
+ *   - `INTEGRATION_SINK` — per canonical entity; consumer binds in their feature
  *     module.
- *   - `ExecuteSyncUseCase` — registered by the feature module alongside
+ *   - `ExecuteIntegrationUseCase` — registered by the feature module alongside
  *     its source + sink bindings. Providing the orchestrator here would
- *     force Nest to resolve SYNC_CHANGE_SOURCE + SYNC_SINK at module
+ *     force Nest to resolve INTEGRATION_CHANGE_SOURCE + INTEGRATION_SINK at module
  *     compile time, which fails when the feature module hasn't been
- *     imported yet. Consumers register `ExecuteSyncUseCase` in the same
+ *     imported yet. Consumers register `ExecuteIntegrationUseCase` in the same
  *     `providers` array as their source + sink so resolution is local
  *     to where all three are bound.
  *
@@ -38,7 +38,7 @@
  * ```ts
  * // AppModule — single source of truth for backend + multi-tenancy.
  * @Module({
- *   imports: [SyncModule.forRoot({ backend: 'drizzle' })],
+ *   imports: [IntegrationModule.forRoot({ backend: 'drizzle' })],
  * })
  * export class AppModule {}
  *
@@ -46,36 +46,36 @@
  * // orchestrator for free.
  * @Module({
  *   providers: [
- *     { provide: SYNC_CHANGE_SOURCE, useClass: SalesforceOpportunitySource },
- *     { provide: SYNC_SINK,          useClass: OpportunitySyncSink },
- *     ExecuteSyncUseCase,
+ *     { provide: INTEGRATION_CHANGE_SOURCE, useClass: SalesforceOpportunitySource },
+ *     { provide: INTEGRATION_SINK,          useClass: OpportunityIntegrationSink },
+ *     ExecuteIntegrationUseCase,
  *   ],
  * })
- * export class OpportunitySyncModule {
+ * export class OpportunityIntegrationModule {
  *   constructor(
- *     private readonly execute: ExecuteSyncUseCase<CanonicalOpportunity>,
+ *     private readonly execute: ExecuteIntegrationUseCase<CanonicalOpportunity>,
  *   ) {}
  * }
  * ```
  *
  * `global: true` means feature modules do not need to re-import
- * `SyncModule` — the substrate tokens are available project-wide.
+ * `IntegrationModule` — the substrate tokens are available project-wide.
  */
 import { Module, type DynamicModule, type Provider } from '@nestjs/common';
 import {
-  SYNC_CURSOR_STORE,
-  SYNC_FIELD_DIFFER,
-  SYNC_MODULE_OPTIONS,
-  SYNC_MULTI_TENANT,
-  SYNC_RUN_RECORDER,
-} from './sync.tokens';
-import { MemoryCursorStore } from './sync-cursor-store.memory-backend';
-import { MemoryRunRecorder } from './sync-run-recorder.memory-backend';
-import { PostgresCursorStore } from './sync-cursor-store.drizzle-backend';
-import { DrizzleSyncRunRecorder } from './sync-run-recorder.drizzle-backend';
+  INTEGRATION_CURSOR_STORE,
+  INTEGRATION_FIELD_DIFFER,
+  INTEGRATION_MODULE_OPTIONS,
+  INTEGRATION_MULTI_TENANT,
+  INTEGRATION_RUN_RECORDER,
+} from './integration.tokens';
+import { MemoryCursorStore } from './integration-cursor-store.memory-backend';
+import { MemoryRunRecorder } from './integration-run-recorder.memory-backend';
+import { PostgresCursorStore } from './integration-cursor-store.drizzle-backend';
+import { DrizzleIntegrationRunRecorder } from './integration-run-recorder.drizzle-backend';
 import { DeepEqualDiffer } from './deep-equal.differ';
 
-export interface SyncModuleOptions {
+export interface IntegrationModuleOptions {
   /**
    * Backend selection. `drizzle` wires the Postgres cursor store +
    * run-log recorder; `memory` wires in-memory doubles suitable for
@@ -103,16 +103,16 @@ export interface SyncModuleOptions {
 }
 
 @Module({})
-export class SyncModule {
-  static forRoot(options: SyncModuleOptions): DynamicModule {
+export class IntegrationModule {
+  static forRoot(options: IntegrationModuleOptions): DynamicModule {
     const multiTenant = options.multiTenant ?? false;
 
     const sharedProviders: Provider[] = [
-      { provide: SYNC_MODULE_OPTIONS, useValue: options },
-      { provide: SYNC_MULTI_TENANT, useValue: multiTenant },
+      { provide: INTEGRATION_MODULE_OPTIONS, useValue: options },
+      { provide: INTEGRATION_MULTI_TENANT, useValue: multiTenant },
       // Default differ — consumers can override by binding a different
-      // `IFieldDiffer<T>` to `SYNC_FIELD_DIFFER` in their feature module.
-      { provide: SYNC_FIELD_DIFFER, useValue: new DeepEqualDiffer() },
+      // `IFieldDiffer<T>` to `INTEGRATION_FIELD_DIFFER` in their feature module.
+      { provide: INTEGRATION_FIELD_DIFFER, useValue: new DeepEqualDiffer() },
     ];
 
     const backendProviders: Provider[] =
@@ -123,33 +123,33 @@ export class SyncModule {
             // direct assertions. Matches JOB-4 / MemoryJobStore shape.
             { provide: MemoryCursorStore, useValue: new MemoryCursorStore() },
             {
-              provide: SYNC_CURSOR_STORE,
+              provide: INTEGRATION_CURSOR_STORE,
               useExisting: MemoryCursorStore,
             },
             { provide: MemoryRunRecorder, useValue: new MemoryRunRecorder() },
             {
-              provide: SYNC_RUN_RECORDER,
+              provide: INTEGRATION_RUN_RECORDER,
               useExisting: MemoryRunRecorder,
             },
           ]
         : [
             // Drizzle backends — injected with DRIZZLE (provided by the
-            // consumer's DrizzleModule) + the SYNC_MULTI_TENANT flag
+            // consumer's DrizzleModule) + the INTEGRATION_MULTI_TENANT flag
             // we bound above.
-            { provide: SYNC_CURSOR_STORE, useClass: PostgresCursorStore },
-            { provide: SYNC_RUN_RECORDER, useClass: DrizzleSyncRunRecorder },
+            { provide: INTEGRATION_CURSOR_STORE, useClass: PostgresCursorStore },
+            { provide: INTEGRATION_RUN_RECORDER, useClass: DrizzleIntegrationRunRecorder },
           ];
 
     return {
-      module: SyncModule,
+      module: IntegrationModule,
       global: true,
       providers: [...sharedProviders, ...backendProviders],
       exports: [
-        SYNC_MODULE_OPTIONS,
-        SYNC_MULTI_TENANT,
-        SYNC_FIELD_DIFFER,
-        SYNC_CURSOR_STORE,
-        SYNC_RUN_RECORDER,
+        INTEGRATION_MODULE_OPTIONS,
+        INTEGRATION_MULTI_TENANT,
+        INTEGRATION_FIELD_DIFFER,
+        INTEGRATION_CURSOR_STORE,
+        INTEGRATION_RUN_RECORDER,
       ],
     };
   }

package/runtime/subsystems/integration/integration.tokens.ts

@@ -0,0 +1,49 @@
+/**
+ * Integration subsystem — DI tokens
+ *
+ * String constants (not Symbols) so they match by value across import
+ * boundaries — same convention as the events subsystem (`EVENT_BUS`). The
+ * jobs subsystem uses Symbols for its analogous tokens; events and integration
+ * stay internally consistent with strings.
+ *
+ * Usage in use cases:
+ * ```ts
+ * constructor(
+ *   @Inject(INTEGRATION_CHANGE_SOURCE) private readonly source: IChangeSource<CanonicalOpportunity>,
+ *   @Inject(INTEGRATION_CURSOR_STORE)  private readonly cursors: ICursorStore,
+ *   @Inject(INTEGRATION_FIELD_DIFFER)  private readonly differ: IFieldDiffer<CanonicalOpportunity>,
+ *   @Inject(INTEGRATION_SINK)          private readonly sink: IIntegrationSink<CanonicalOpportunity>,
+ *   @Inject(INTEGRATION_RUN_RECORDER)  private readonly recorder: IIntegrationRunRecorder,
+ * ) {}
+ * ```
+ *
+ * Concrete bindings are registered by `IntegrationModule.forRoot(...)` (SYNC-6).
+ */
+
+export const INTEGRATION_CHANGE_SOURCE = 'INTEGRATION_CHANGE_SOURCE' as const;
+export const INTEGRATION_CURSOR_STORE = 'INTEGRATION_CURSOR_STORE' as const;
+export const INTEGRATION_FIELD_DIFFER = 'INTEGRATION_FIELD_DIFFER' as const;
+export const INTEGRATION_SINK = 'INTEGRATION_SINK' as const;
+
+/**
+ * Run-recorder token (SYNC-5). Backed by `IIntegrationRunRecorder`. Drizzle impl
+ * lands in SYNC-4; tests provide inline fakes.
+ */
+export const INTEGRATION_RUN_RECORDER = 'INTEGRATION_RUN_RECORDER' as const;
+
+/**
+ * Injection token for the resolved `IntegrationModuleOptions` object (SYNC-6).
+ *
+ * Backends that need to observe module configuration (e.g. `multiTenant`
+ * flag, pool filters) inject via this token. Provided automatically by
+ * `IntegrationModule.forRoot(...)` / `IntegrationModule.forRootAsync(...)`.
+ */
+export const INTEGRATION_MODULE_OPTIONS = 'INTEGRATION_MODULE_OPTIONS' as const;
+
+/**
+ * Injection token for the resolved multi-tenancy flag (SYNC-6).
+ *
+ * Provided by `IntegrationModule.forRoot(...)` as `options.multiTenant ?? false`.
+ * Consumed by `ExecuteIntegrationUseCase` to enforce the tenantId-is-required rule.
+ */
+export const INTEGRATION_MULTI_TENANT = 'INTEGRATION_MULTI_TENANT' as const;

package/runtime/subsystems/{sync → integration}/loopback.middleware.ts

@@ -1,7 +1,7 @@
 /**
- * Sync subsystem — loopback `ChangeMiddleware` factory (#226-5, ADR-033).
+ * Integration subsystem — loopback `ChangeMiddleware` factory (#226-5, ADR-033).
  *
- * Replaces the prior orchestrator-side `@Optional() SYNC_LOOPBACK_FINGERPRINT_STORE`
+ * Replaces the prior orchestrator-side `@Optional() INTEGRATION_LOOPBACK_FINGERPRINT_STORE`
  * branch. Consumers that need to suppress echoes of their own outbound
  * writes compose `createLoopbackMiddleware(store)` into a primitive's
  * middleware chain — typically alongside `PollChangeSource<T>` — instead
@@ -28,12 +28,12 @@
  * their store or layer a counting middleware alongside this one.
  */
 
-import type { Change } from './sync-change-source.protocol';
+import type { Change } from './integration-change-source.protocol';
 import type {
   ChangeIterator,
   ChangeMiddleware,
-} from './sync-middleware.protocol';
-import type { ILoopbackFingerprintStore } from './sync-loopback.protocol';
+} from './integration-middleware.protocol';
+import type { ILoopbackFingerprintStore } from './integration-loopback.protocol';
 
 /**
  * Build a `ChangeMiddleware<T>` that suppresses changes whose fingerprint

package/runtime/subsystems/{sync → integration}/poll-change-source.ts

@@ -1,5 +1,5 @@
 /**
- * Sync subsystem — `PollChangeSource<T>` primitive (#226-3, ADR-033).
+ * Integration subsystem — `PollChangeSource<T>` primitive (#226-3, ADR-033).
  *
  * Generic poll-mode `IChangeSource<T>` implementation parameterized by a
  * parsed `DetectionConfig` (poll mode) and a consumer-supplied
@@ -36,12 +36,12 @@ import type {
   Change,
   ChangeSource,
   IChangeSource,
-  SyncSubscriptionView,
-} from './sync-change-source.protocol';
+  IntegrationSubscriptionView,
+} from './integration-change-source.protocol';
 import type {
   ChangeIterator,
   ChangeMiddleware,
-} from './sync-middleware.protocol';
+} from './integration-middleware.protocol';
 
 // ============================================================================
 // Cursor + adapter callback shapes
@@ -60,7 +60,7 @@ export type PollCursor = unknown;
  * NOT here on purpose.
  */
 export interface PollFetchContext {
-  readonly subscription: SyncSubscriptionView;
+  readonly subscription: IntegrationSubscriptionView;
   readonly cursor: PollCursor | null;
   readonly filters: readonly ResolvedFilter[];
 }
@@ -174,14 +174,14 @@ export class PollChangeSource<T> implements IChangeSource<T> {
   }
 
   listChanges(
-    subscription: SyncSubscriptionView,
+    subscription: IntegrationSubscriptionView,
     cursor: unknown | null,
   ): AsyncIterable<Change<T>> {
     return this.composed(subscription, cursor);
   }
 
   private async *fetch(
-    subscription: SyncSubscriptionView,
+    subscription: IntegrationSubscriptionView,
     cursor: unknown | null,
   ): AsyncIterable<Change<T>> {
     const ctx: PollFetchContext = {

package/runtime/subsystems/{sync → integration}/webhook-change-source.ts

@@ -1,5 +1,5 @@
 /**
- * Sync subsystem — `WebhookChangeSource<T>` primitive (#226-4, ADR-033).
+ * Integration subsystem — `WebhookChangeSource<T>` primitive (#226-4, ADR-033).
  *
  * Generic webhook-mode `IChangeSource<T>` implementation parameterized by a
  * parsed `DetectionConfig` (webhook mode) and a consumer-supplied
@@ -40,12 +40,12 @@ import type { DetectionConfig } from './detection-config.schema';
 import type {
   Change,
   IChangeSource,
-  SyncSubscriptionView,
-} from './sync-change-source.protocol';
+  IntegrationSubscriptionView,
+} from './integration-change-source.protocol';
 import type {
   ChangeIterator,
   ChangeMiddleware,
-} from './sync-middleware.protocol';
+} from './integration-middleware.protocol';
 
 // ============================================================================
 // Cursor + queue callback shapes
@@ -65,7 +65,7 @@ export type WebhookCursor = unknown;
  * `userId` / `tenantId`.
  */
 export interface WebhookFetchContext {
-  readonly subscription: SyncSubscriptionView;
+  readonly subscription: IntegrationSubscriptionView;
   readonly cursor: WebhookCursor | null;
 }
 
@@ -162,14 +162,14 @@ export class WebhookChangeSource<T> implements IChangeSource<T> {
   }
 
   listChanges(
-    subscription: SyncSubscriptionView,
+    subscription: IntegrationSubscriptionView,
     cursor: unknown | null,
   ): AsyncIterable<Change<T>> {
     return this.composed(subscription, cursor);
   }
 
   private async *fetch(
-    subscription: SyncSubscriptionView,
+    subscription: IntegrationSubscriptionView,
     cursor: unknown | null,
   ): AsyncIterable<Change<T>> {
     const ctx: WebhookFetchContext = {

package/runtime/subsystems/jobs/bullmq.config.ts

@@ -6,9 +6,29 @@
  * `jobs.extensions.bullmq.*` config namespace (CLAUDE.md core/extension
  * protocol). The Drizzle backend never reads any of it.
  */
-import type { ConnectionOptions } from 'bullmq';
 import { loadPoolConfig, type PoolConfig } from './pool-config.loader';
 
+/**
+ * #6 — Structural mirror of BullMQ's `ConnectionOptions`. Declared locally
+ * so this config file (which ships into EVERY jobs install, drizzle or
+ * bullmq) does NOT need the `bullmq` peer dep resolved by the consumer's
+ * tsc. The bullmq backend internally casts to the real `ConnectionOptions`
+ * — that file is only vendored when `--backend bullmq` is selected
+ * (see `backendFileFilter`).
+ *
+ * Accepts the `{ url }` shape this resolver emits, plus the host/port/
+ * password/db form BullMQ also accepts, with an open index for any extra
+ * ioredis options consumers may flow through.
+ */
+export type BullMqConnectionOptions = {
+  url?: string;
+  host?: string;
+  port?: number;
+  password?: string;
+  db?: number;
+  [key: string]: unknown;
+};
+
 /**
  * Typed shape of `codegen.config.yaml: jobs.extensions.bullmq`. Snake_case
  * because it mirrors the YAML the consumer authors.
@@ -53,7 +73,7 @@ export interface BullMqExtensionsConfig {
  * orchestrator + worker actually consume.
  */
 export interface BullMqResolvedConfig {
-  connection: ConnectionOptions;
+  connection: BullMqConnectionOptions;
   queuePrefix?: string;
   bullBoard?: { enabled: boolean; mountPath: string };
 }
@@ -85,7 +105,7 @@ export function resolveBullMqConfig(
     ext?.redis_url ?? process.env.REDIS_URL ?? DEFAULT_REDIS_URL;
 
   const resolved: BullMqResolvedConfig = {
-    connection: { url } as ConnectionOptions,
+    connection: { url },
     queuePrefix: ext?.queue_prefix,
   };
   if (ext?.bull_board?.enabled) {

package/runtime/subsystems/jobs/index.ts

@@ -81,19 +81,24 @@ export { DrizzleJobRunService } from './job-run-service.drizzle-backend';
 export { DrizzleJobStepService } from './job-step-service.drizzle-backend';
 
 // ─── BULLMQ-1: BullMQ backend (additive; opt-in via jobs.backend: bullmq) ──
-export {
-  BullMQJobOrchestrator,
-  sha1JobId,
-} from './job-orchestrator.bullmq-backend';
-export {
-  BullMQJobWorker,
-  type BullMQJobWorkerOptions,
-} from './job-worker.bullmq-backend';
+// #6 — backend-specific implementation classes are NOT re-exported from this
+// public barrel. `BullMQJobOrchestrator` + `BullMQJobWorker` are only vendored
+// when the consumer installs with `--backend bullmq`; surfacing them here
+// would force every consumer's tsc to resolve those files even on a drizzle
+// install (filtered out → TS2307). Consumers who select bullmq import them
+// directly from their backend file; `JobsDomainModule.forRoot({ backend:
+// 'bullmq' })` + `JobWorkerModule` lazy-load them internally.
+//
+// `bullmq.config.ts` (tokens + helpers) IS still re-exported — it always
+// ships (its only type surface is a local `BullMqConnectionOptions`, no
+// `bullmq` peer-dep resolution required). The module files static-import
+// from it.
 export {
   BULLMQ_CONNECTION,
   BULLMQ_RESOLVED_CONFIG,
   resolveBullMqConfig,
   resolvePoolQueueName,
+  type BullMqConnectionOptions,
   type BullMqExtensionsConfig,
   type BullMqResolvedConfig,
 } from './bullmq.config';

package/runtime/subsystems/jobs/job-worker.bullmq-backend.ts

@@ -94,13 +94,16 @@ export class BullMQJobWorker {
     }
     this.worker = new WorkerCtor(
       this.options.queueName,
-      (job) => this.process(job as Job<BullJobPayload>),
+      // #6 / noImplicitAny — explicit annotations so the file stays
+      // strict-clean even when consumers compile under a stricter tsconfig
+      // than the one used to type-check the runtime tree.
+      (job: Job<BullJobPayload>) => this.process(job),
       {
         connection: this.options.connection,
         concurrency: this.options.concurrency,
       },
     );
-    this.worker.on('failed', (job, err) => {
+    this.worker.on('failed', (job: Job<BullJobPayload> | undefined, err: Error) => {
       // BullMQ fires `failed` after EACH attempt; only mirror to job_run when
       // attempts are exhausted (BullMQ will not retry further).
       if (!job) return;

package/runtime/subsystems/jobs/job-worker.module.ts

@@ -52,12 +52,17 @@ import {
   type PoolConfig,
 } from './pool-config.loader';
 import { JobWorker, type JobWorkerOptions } from './job-worker';
-import { BullMQJobWorker } from './job-worker.bullmq-backend';
-import type { ConnectionOptions } from 'bullmq';
+// #6 — `BullMQJobWorker` is lazy-loaded only when `backend: 'bullmq'` is
+// selected (`spawnBullMQWorker` below). The file is filtered out of drizzle/
+// memory installs (see `backendFileFilter`). The `ConnectionOptions` type
+// previously imported from `'bullmq'` is replaced by `BullMqConnectionOptions`
+// from `./bullmq.config` (a self-contained structural mirror that does NOT
+// require the `bullmq` peer dep to type-check).
 import {
   BULLMQ_CONNECTION,
   BULLMQ_RESOLVED_CONFIG,
   resolvePoolQueueName,
+  type BullMqConnectionOptions,
   type BullMqResolvedConfig,
 } from './bullmq.config';
 import {
@@ -157,7 +162,7 @@ export class JobWorkerOrchestrator implements OnModuleInit, OnModuleDestroy {
      */
     @Optional()
     @Inject(BULLMQ_CONNECTION)
-    private readonly bullConnection: ConnectionOptions | null = null,
+    private readonly bullConnection: BullMqConnectionOptions | null = null,
     @Optional()
     @Inject(BULLMQ_RESOLVED_CONFIG)
     private readonly bullConfig: BullMqResolvedConfig | null = null,
@@ -233,7 +238,7 @@ export class JobWorkerOrchestrator implements OnModuleInit, OnModuleDestroy {
       const worker = this.options.workerFactory
         ? this.options.workerFactory(workerOptions)
         : backend === 'bullmq'
-          ? this.spawnBullMQWorker(poolName, def.queue, def.concurrency, poolConfig)
+          ? await this.spawnBullMQWorker(poolName, def.queue, def.concurrency, poolConfig)
           : this.spawnWorker(workerOptions);
       // `JobWorker` extends Nest's lifecycle hooks but the worker isn't
       // a Nest provider here (we manage the array ourselves). Call
@@ -364,12 +369,20 @@ export class JobWorkerOrchestrator implements OnModuleInit, OnModuleDestroy {
    * orchestrator's `dispatch` via `resolvePoolQueueName(pool, …)` so producer
    * and consumer agree.
    */
-  private spawnBullMQWorker(
+  /**
+   * #6 — async + dynamic-import. The `job-worker.bullmq-backend.ts` file is
+   * filtered out of the vendor set for drizzle/memory installs (no `bullmq`
+   * peer dep needed). The non-literal import specifier makes TS treat the
+   * module as `any` so the consumer's tsc never tries to resolve an absent
+   * file. This method is only entered when `backend === 'bullmq'` — at which
+   * point the file IS vendored.
+   */
+  private async spawnBullMQWorker(
     pool: string,
     _queueAlias: string,
     concurrency: number,
     poolConfig: PoolConfig,
-  ): BullMQJobWorker {
+  ): Promise<Pick<JobWorker, 'onModuleInit' | 'onModuleDestroy'>> {
     if (!this.db) {
       throw new Error(
         `JobWorkerModule: BullMQ worker spawning requires the Drizzle client ` +
@@ -390,7 +403,14 @@ export class JobWorkerOrchestrator implements OnModuleInit, OnModuleDestroy {
       );
     }
     const queueName = resolvePoolQueueName(pool, this.bullConfig, poolConfig);
-    return new BullMQJobWorker(
+    const specifier = './job-worker.bullmq-backend';
+    const mod = (await import(specifier)) as {
+      BullMQJobWorker: new (...args: unknown[]) => Pick<
+        JobWorker,
+        'onModuleInit' | 'onModuleDestroy'
+      >;
+    };
+    return new mod.BullMQJobWorker(
       this.db,
       this.orchestrator,
       this.stepService,

package/runtime/subsystems/jobs/jobs-domain.module.ts

@@ -15,6 +15,7 @@
  * and the type system reserves the slot.
  */
 import { Module, type DynamicModule, type Provider } from '@nestjs/common';
+import { DRIZZLE } from '../../constants/tokens';
 import {
   JOB_ORCHESTRATOR,
   JOB_RUN_SERVICE,
@@ -24,7 +25,10 @@ import {
 import { DrizzleJobOrchestrator } from './job-orchestrator.drizzle-backend';
 import { DrizzleJobRunService } from './job-run-service.drizzle-backend';
 import { DrizzleJobStepService } from './job-step-service.drizzle-backend';
-import { BullMQJobOrchestrator } from './job-orchestrator.bullmq-backend';
+// #6 — `BullMQJobOrchestrator` is lazy-loaded only when `backend: 'bullmq'`
+// is selected. The backend file is filtered out of drizzle/memory installs
+// (see `backendFileFilter`); a non-literal dynamic import below sidesteps
+// consumer-side tsc resolution of an absent file.
 import { MemoryJobOrchestrator } from './job-orchestrator.memory-backend';
 import { MemoryJobRunService } from './job-run-service.memory-backend';
 import { MemoryJobStepService } from './job-step-service.memory-backend';
@@ -102,10 +106,31 @@ export class JobsDomainModule {
       // run/step services stay Drizzle (domain reads + `listForScope` are
       // Postgres queries, unchanged per spec). Only the orchestrator's
       // claim/dispatch half swaps to BullMQ.
+      //
+      // #6 — the bullmq backend module is filtered out of drizzle/memory
+      // installs (no `bullmq` peer dep, no consumer-side tsc compile of an
+      // unused file). The factory below dynamic-imports it via a non-literal
+      // specifier so TS treats the module type as `any` and never tries to
+      // resolve the absent file on a drizzle/memory consumer.
       const resolved = resolveBullMqConfig(opts.extensions?.bullmq);
       providers.push({ provide: BULLMQ_CONNECTION, useValue: resolved.connection });
       providers.push({ provide: BULLMQ_RESOLVED_CONFIG, useValue: resolved });
-      providers.push({ provide: JOB_ORCHESTRATOR, useClass: BullMQJobOrchestrator });
+      providers.push({
+        provide: JOB_ORCHESTRATOR,
+        useFactory: async (...args: unknown[]): Promise<object> => {
+          const specifier = './job-orchestrator.bullmq-backend';
+          const mod = (await import(specifier)) as {
+            BullMQJobOrchestrator: new (...args: unknown[]) => object;
+          };
+          return new mod.BullMQJobOrchestrator(...args);
+        },
+        // The bullmq orchestrator constructor mirrors DrizzleJobOrchestrator's
+        // injection list: DRIZZLE + JOBS_MULTI_TENANT + the resolved BullMQ
+        // tokens. Importing token references would force a static dep on the
+        // tokens file in this module's import graph; using the existing
+        // symbols already in scope is sufficient.
+        inject: [DRIZZLE, JOBS_MULTI_TENANT, BULLMQ_CONNECTION, BULLMQ_RESOLVED_CONFIG],
+      });
       providers.push({ provide: JOB_RUN_SERVICE, useClass: DrizzleJobRunService });
       providers.push({ provide: JOB_STEP_SERVICE, useClass: DrizzleJobStepService });
     } else {

package/runtime/subsystems/observability/index.ts

@@ -39,7 +39,7 @@ export type {
   CorrelationTimeline,
   CorrelationTimelineEntry,
   StatusHistogram,
-  SyncRunSummary,
+  IntegrationRunSummary,
   CursorSnapshot,
 } from './observability.protocol';
 

package/runtime/subsystems/observability/observability.module.ts

@@ -1,7 +1,7 @@
 /**
  * ObservabilityModule — combiner subsystem (ADR-025, OBS-5, OBS-6).
  *
- * Composes the jobs, bridge, and sync read ports into a single
+ * Composes the jobs, bridge, and integration read ports into a single
  * `IObservability` facade. Owned by no sibling subsystem; it consumes
  * their tokens via DI, which the consumer app wires by registering the
  * sibling modules in the right order (like BridgeModule — the named
@@ -14,7 +14,7 @@
  *     EventsModule.forRoot({ backend: 'drizzle' }),
  *     JobsDomainModule.forRoot({ backend: 'drizzle' }),
  *     BridgeModule.forRoot({ backend: 'drizzle' }),
- *     SyncModule.forRoot({ backend: 'drizzle' }),
+ *     IntegrationModule.forRoot({ backend: 'drizzle' }),
  *     ObservabilityModule.forRoot({
  *       reporters: {
  *         bridgeMetrics: {