@pattern-stack/codegen 0.4.1 → 0.4.3

package/runtime/subsystems/sync/sync-field-diff.protocol.ts

@@ -0,0 +1,61 @@
+/**
+ * Sync subsystem — field-diff protocol (port)
+ *
+ * `IFieldDiffer<T>` is the pluggable differ seam. The default implementation
+ * (`DeepEqualDiffer`, ships in SYNC-5) walks every field except an ignore
+ * list; CDC-aware differs can skip comparison for fields the provider didn't
+ * flag as changed.
+ *
+ * `FieldDiffSchema` is the structural enforcement of the `changed_fields`
+ * column per ADR-0003 — enforced at write time by the recorder service so
+ * consumers can rely on the shape in downstream queries.
+ */
+import { z } from 'zod';
+
+// ============================================================================
+// FieldDiff shape — the ADR-0003 contract
+// ============================================================================
+
+/**
+ * Structured per-field change. Enforced shape for `sync_run_items.changed_fields`.
+ *
+ * `created` items set `from: null, to: <value>` for every non-null field.
+ * `deleted` items set `from: <value>, to: null`.
+ * `noop` items carry `{}`.
+ */
+export const FieldDiffValueSchema = z.object({
+  from: z.unknown(),
+  to: z.unknown(),
+});
+
+export const FieldDiffSchema = z.record(z.string(), FieldDiffValueSchema);
+
+export type FieldDiffValue = z.infer<typeof FieldDiffValueSchema>;
+export type FieldDiff = z.infer<typeof FieldDiffSchema>;
+
+/** Result of comparing a new record against its existing local state. */
+export type DiffResult = FieldDiff | 'noop';
+
+// ============================================================================
+// IFieldDiffer
+// ============================================================================
+
+/**
+ * Pluggable differ. Default ships in SYNC-5 as `DeepEqualDiffer<T>` —
+ * deep-equal over every field except an ignore list (`updated_at` and other
+ * row metadata). CDC-aware differs restrict comparison to
+ * `providerChangedFields` when supplied.
+ */
+export interface IFieldDiffer<T> {
+  /**
+   * @param existing — current local state, or `null` when the record is new
+   * @param incoming — the canonical record coming from the adapter
+   * @param providerChangedFields — optional hint from CDC-capable sources;
+   *   when present, differ may restrict the comparison to these fields
+   */
+  diff(
+    existing: T | null,
+    incoming: T,
+    providerChangedFields?: string[],
+  ): DiffResult;
+}

package/runtime/subsystems/sync/sync-loopback.protocol.ts

@@ -0,0 +1,33 @@
+/**
+ * Sync subsystem — loopback-fingerprint protocol (port)
+ *
+ * Optional port. When the local system writes to an upstream provider via an
+ * outbound path, the same change typically echoes back on the next inbound
+ * poll/CDC/webhook. A fingerprint store lets `ExecuteSyncUseCase` skip
+ * records it already wrote, avoiding a diff-noop round trip and a spurious
+ * audit row.
+ *
+ * The contract is deliberately narrow: one method, one decision
+ * ("is this change an echo of our own recent write?"). Provider-specific
+ * fingerprinting (hash a canonical payload, TTL shorter than the poll
+ * interval, etc.) lives in the concrete backend. The subsystem does not ship
+ * a backend in Phase 1; consumers that need loopback suppression provide
+ * their own (redis-hashed, memory TTL, etc.).
+ *
+ * `entityType` is `string` (not a union) — per dealbrain-v2's HS-9 findings
+ * the CRM-specific narrowing `'opportunity' | 'account' | 'contact'` bled
+ * into the port and had to be removed. Consumers narrow internally if they
+ * want.
+ */
+
+export interface ILoopbackFingerprintStore<T = unknown> {
+  /**
+   * @returns `true` when the record matches a recent local write (skip it)
+   *          `false` when the record is external-originated (process it)
+   */
+  isEchoOfOwnWrite(
+    entityType: string,
+    externalId: string,
+    record: T,
+  ): Promise<boolean>;
+}

package/runtime/subsystems/sync/sync-run-recorder.drizzle-backend.ts

@@ -0,0 +1,123 @@
+/**
+ * DrizzleSyncRunRecorder — Drizzle-backed `ISyncRunRecorder` (SYNC-4).
+ *
+ * Generic write path only — extracted from dealbrain-v2's
+ * `SyncRunRecorderService`, minus CRM-specific convenience methods. Those
+ * stay consumer-owned; the subsystem ships the substrate.
+ *
+ * ## Responsibilities
+ *
+ *   - `startRun`     — INSERT sync_runs row in status='running', returns id.
+ *   - `recordItem`   — validates `changedFields` via `FieldDiffSchema.parse`
+ *                      BEFORE the INSERT; a malformed shape throws before
+ *                      any DB call fires. Enforces the ADR-0003 contract at
+ *                      the write boundary.
+ *   - `completeRun`  — UPDATE sync_runs with terminal status, counts,
+ *                      cursor_after, duration_ms, completed_at.
+ *
+ * ## Multi-tenancy
+ *
+ * When `SYNC_MULTI_TENANT` is true (SYNC-6):
+ *   - `startRun` and `recordItem` require non-null `tenantId` on input.
+ *     Enforcement goes through the shared `assertTenantId` helper so the
+ *     error message shape matches the orchestrator entry point + the
+ *     cursor-store backends.
+ *   - `completeRun` does NOT re-check tenancy — the run id was returned
+ *     by `startRun` which already enforced it, and run ids are uuids that
+ *     aren't guessable cross-tenant. Matches JOB-3's pattern of trusting
+ *     the run-id for downstream mutations.
+ */
+import { Inject, Injectable, Optional } from '@nestjs/common';
+import { eq } from 'drizzle-orm';
+import type { DrizzleClient } from '../../types/drizzle';
+import { DRIZZLE } from '../../constants/tokens';
+import type {
+  CompleteRunInput,
+  ISyncRunRecorder,
+  RecordItemInput,
+  StartRunInput,
+} from './sync-run-recorder.protocol';
+import { syncRuns, syncRunItems } from './sync-audit.schema';
+import { FieldDiffSchema } from './sync-field-diff.protocol';
+import { SYNC_MULTI_TENANT } from './sync.tokens';
+import { assertTenantId } from './sync-errors';
+
+@Injectable()
+export class DrizzleSyncRunRecorder implements ISyncRunRecorder {
+  private readonly multiTenant: boolean;
+
+  constructor(
+    @Inject(DRIZZLE) private readonly db: DrizzleClient,
+    @Optional() @Inject(SYNC_MULTI_TENANT) multiTenant?: boolean,
+  ) {
+    this.multiTenant = multiTenant ?? false;
+  }
+
+  async startRun(input: StartRunInput): Promise<{ id: string }> {
+    assertTenantId(input.tenantId, {
+      multiTenant: this.multiTenant,
+      operation: 'startRun',
+    });
+
+    const rows = await this.db
+      .insert(syncRuns)
+      .values({
+        subscriptionId: input.subscriptionId,
+        direction: input.direction,
+        action: input.action,
+        status: 'running',
+        cursorBefore: input.cursorBefore ?? null,
+        tenantId: input.tenantId ?? null,
+      })
+      .returning({ id: syncRuns.id });
+
+    const id = rows[0]?.id;
+    if (!id) {
+      // Drizzle's insert().returning() contract: at least one row is
+      // returned for every successful INSERT. A missing id would indicate
+      // a driver misbehavior; throw loudly rather than return bogus data.
+      throw new Error('DrizzleSyncRunRecorder: INSERT RETURNING produced no id');
+    }
+    return { id };
+  }
+
+  async recordItem(input: RecordItemInput): Promise<void> {
+    assertTenantId(input.tenantId, {
+      multiTenant: this.multiTenant,
+      operation: 'recordItem',
+    });
+
+    // ADR-0003 contract enforcement — reject malformed changedFields
+    // before the DB call fires. `parse` throws a ZodError; callers see
+    // the validation failure, not a DB constraint error.
+    FieldDiffSchema.parse(input.changedFields);
+
+    await this.db.insert(syncRunItems).values({
+      syncRunId: input.syncRunId,
+      entityType: input.entityType,
+      externalId: input.externalId,
+      localId: input.localId ?? null,
+      operation: input.operation,
+      status: input.status,
+      changedFields: input.changedFields,
+      title: input.title ?? null,
+      error: input.error ?? null,
+      tenantId: input.tenantId ?? null,
+    });
+  }
+
+  async completeRun(runId: string, input: CompleteRunInput): Promise<void> {
+    await this.db
+      .update(syncRuns)
+      .set({
+        status: input.status,
+        recordsFound: input.recordsFound,
+        recordsProcessed: input.recordsProcessed,
+        cursorAfter: input.cursorAfter ?? null,
+        durationMs: input.durationMs,
+        error: input.error ?? null,
+        completedAt: new Date(),
+      })
+      .where(eq(syncRuns.id, runId));
+  }
+}

package/runtime/subsystems/sync/sync-run-recorder.memory-backend.ts

@@ -0,0 +1,143 @@
+/**
+ * MemoryRunRecorder — in-memory backend for `ISyncRunRecorder` (SYNC-6).
+ *
+ * Test double so `SyncModule.forRoot({ backend: 'memory' })` is genuinely
+ * end-to-end runnable without Postgres. Mirrors the role of
+ * `MemoryCursorStore`: plain keyed state, `clear()` helper for
+ * `beforeEach` resets, public inspection surface so tests can assert on
+ * the recorded run + item timeline without scraping logs.
+ *
+ * Validates `changedFields` through `FieldDiffSchema.parse` on every
+ * `recordItem` call — same ADR-0003 contract as the Drizzle backend. An
+ * in-memory recorder that skipped the validation would be a silently
+ * weaker contract than production.
+ *
+ * `startRun` generates a uuid via `crypto.randomUUID()` (Node 19+ / Bun).
+ * We don't import `uuid` because the subsystem has no other use for it.
+ *
+ * ## Multi-tenancy
+ *
+ * `tenantId` is accepted (and recorded on the in-memory row so tests can
+ * assert it) but enforcement lives at the module boundary. The memory
+ * backend intentionally does not throw on missing `tenantId` — that's
+ * the orchestrator's job when `multiTenant=true` (SYNC-6). A permissive
+ * memory recorder lets tests exercise error paths where the orchestrator
+ * short-circuits before ever reaching the recorder.
+ */
+import { Injectable } from '@nestjs/common';
+import type {
+  CompleteRunInput,
+  ISyncRunRecorder,
+  RecordItemInput,
+  StartRunInput,
+} from './sync-run-recorder.protocol';
+import { FieldDiffSchema } from './sync-field-diff.protocol';
+
+/**
+ * Concrete run row as held in memory. Shape mirrors the interesting
+ * columns on `sync_runs` so assertions read like DB queries.
+ */
+export interface MemoryRunRecord {
+  id: string;
+  subscriptionId: string;
+  direction: 'inbound' | 'outbound';
+  action: 'poll' | 'cdc' | 'webhook' | 'manual' | 'writeback';
+  status: 'running' | 'success' | 'no_changes' | 'failed';
+  cursorBefore: unknown | null;
+  cursorAfter: unknown | null;
+  recordsFound: number;
+  recordsProcessed: number;
+  durationMs: number | null;
+  error: string | null;
+  tenantId: string | null;
+  startedAt: Date;
+  completedAt: Date | null;
+}
+
+@Injectable()
+export class MemoryRunRecorder implements ISyncRunRecorder {
+  /**
+   * All started runs keyed by id. Public so tests can inspect lifecycle
+   * transitions without poking through recording methods.
+   */
+  readonly runs: Map<string, MemoryRunRecord> = new Map();
+
+  /**
+   * Items keyed by `sync_run_id`, array order matches insertion order —
+   * mirrors the timeline the `(sync_run_id, created_at)` index produces
+   * in Postgres.
+   */
+  readonly items: Map<string, RecordItemInput[]> = new Map();
+
+  async startRun(input: StartRunInput): Promise<{ id: string }> {
+    const id = crypto.randomUUID();
+    this.runs.set(id, {
+      id,
+      subscriptionId: input.subscriptionId,
+      direction: input.direction,
+      action: input.action,
+      status: 'running',
+      cursorBefore: input.cursorBefore ?? null,
+      cursorAfter: null,
+      recordsFound: 0,
+      recordsProcessed: 0,
+      durationMs: null,
+      error: null,
+      tenantId: input.tenantId ?? null,
+      startedAt: new Date(),
+      completedAt: null,
+    });
+    this.items.set(id, []);
+    return { id };
+  }
+
+  async recordItem(input: RecordItemInput): Promise<void> {
+    // Same ADR-0003 contract as the Drizzle backend.
+    FieldDiffSchema.parse(input.changedFields);
+
+    const bucket = this.items.get(input.syncRunId);
+    if (!bucket) {
+      throw new Error(
+        `MemoryRunRecorder.recordItem: no run started for id '${input.syncRunId}'. ` +
+          `Call startRun(...) first.`,
+      );
+    }
+    bucket.push(input);
+  }
+
+  async completeRun(runId: string, input: CompleteRunInput): Promise<void> {
+    const run = this.runs.get(runId);
+    if (!run) {
+      throw new Error(
+        `MemoryRunRecorder.completeRun: no run started for id '${runId}'.`,
+      );
+    }
+    run.status = input.status;
+    run.recordsFound = input.recordsFound;
+    run.recordsProcessed = input.recordsProcessed;
+    run.cursorAfter = input.cursorAfter ?? null;
+    run.durationMs = input.durationMs;
+    run.error = input.error ?? null;
+    run.completedAt = new Date();
+  }
+
+  /** Reset state. Tests call this in `beforeEach`. */
+  clear(): void {
+    this.runs.clear();
+    this.items.clear();
+  }
+
+  // ─── test ergonomics ─────────────────────────────────────────────────
+
+  /** All runs for a subscription, newest first. Timeline reads. */
+  getRunsForSubscription(subscriptionId: string): MemoryRunRecord[] {
+    return Array.from(this.runs.values())
+      .filter((r) => r.subscriptionId === subscriptionId)
+      .sort((a, b) => b.startedAt.getTime() - a.startedAt.getTime());
+  }
+
+  /** All item rows for a run, insertion-ordered. */
+  getItemsForRun(runId: string): RecordItemInput[] {
+    return this.items.get(runId) ?? [];
+  }
+}

package/runtime/subsystems/sync/sync-run-recorder.protocol.ts

@@ -0,0 +1,86 @@
+/**
+ * Sync subsystem — run-recorder protocol (port)
+ *
+ * `ISyncRunRecorder` is the write side of the audit log. `ExecuteSyncUseCase`
+ * (SYNC-5) calls `startRun` at the top of the loop, `recordItem` for each
+ * processed change, and `completeRun` in a `finally` block so a run always
+ * reaches a terminal status.
+ *
+ * The Drizzle backend (SYNC-4) persists against `sync_runs` / `sync_run_items`
+ * from the SYNC-1 schema. Tests use lightweight in-memory fakes — no
+ * dedicated memory backend ships; the surface is small enough that inline
+ * fakes keep the intent local to each spec.
+ *
+ * `changed_fields` on `recordItem` is validated by the implementation via
+ * `FieldDiffSchema.parse` (ADR-0003 contract). Orchestrator callers pass the
+ * `DiffResult` the differ returned — `'noop'` is translated to `{}` by the
+ * orchestrator before reaching the recorder, so the recorder's input is
+ * always a `FieldDiff`.
+ */
+import type { FieldDiff } from './sync-field-diff.protocol';
+
+// ============================================================================
+// Lifecycle — inputs
+// ============================================================================
+
+/** Args for `startRun`. Mirrors the non-nullable columns on `sync_runs`. */
+export interface StartRunInput {
+  readonly subscriptionId: string;
+  readonly direction: 'inbound' | 'outbound';
+  readonly action: 'poll' | 'cdc' | 'webhook' | 'manual' | 'writeback';
+  /** Cursor snapshot at run start, or `null` if this is the first run. */
+  readonly cursorBefore: unknown | null;
+  /**
+   * Tenant id when `SYNC_MULTI_TENANT` is enabled. The recorder's own
+   * boundary rule (SYNC-6) enforces non-null when the flag is on;
+   * orchestrator passes it through from `ExecuteSyncInput.tenantId`.
+   */
+  readonly tenantId?: string | null;
+}
+
+/** Args for `recordItem`. Mirrors the non-nullable columns on `sync_run_items`. */
+export interface RecordItemInput {
+  readonly syncRunId: string;
+  readonly entityType: string;
+  readonly externalId: string;
+  readonly localId?: string | null;
+  readonly operation: 'created' | 'updated' | 'deleted' | 'noop';
+  readonly status: 'success' | 'failed' | 'skipped';
+  /**
+   * Structured per-field diff — ADR-0003. `{}` for noop / skipped items.
+   * The recorder validates this against `FieldDiffSchema` on every write.
+   */
+  readonly changedFields: FieldDiff;
+  readonly title?: string | null;
+  readonly error?: string | null;
+  readonly tenantId?: string | null;
+}
+
+/** Args for `completeRun`. */
+export interface CompleteRunInput {
+  readonly status: 'success' | 'no_changes' | 'failed';
+  readonly recordsFound: number;
+  readonly recordsProcessed: number;
+  readonly cursorAfter: unknown | null;
+  readonly durationMs: number;
+  readonly error?: string | null;
+}
+
+// ============================================================================
+// ISyncRunRecorder
+// ============================================================================
+
+export interface ISyncRunRecorder {
+  /** Opens a new `sync_runs` row in `status = 'running'`. Returns the run id. */
+  startRun(input: StartRunInput): Promise<{ id: string }>;
+
+  /** Appends one `sync_run_items` row. Throws if `changedFields` is malformed. */
+  recordItem(input: RecordItemInput): Promise<void>;
+
+  /**
+   * Finalizes the run. Must be called from a `finally` block so an in-flight
+   * run never gets stuck in `'running'` state; the orchestrator passes
+   * `'failed'` when the iteration body threw.
+   */
+  completeRun(runId: string, input: CompleteRunInput): Promise<void>;
+}

package/runtime/subsystems/sync/sync-sink.protocol.ts

@@ -0,0 +1,55 @@
+/**
+ * Sync subsystem — sync-sink protocol (port)
+ *
+ * Write surface for the generic orchestrator. One per canonical entity type.
+ *
+ * **Shape contract:** the sink speaks the *canonical* `TCanonical` externally
+ * — `findByExternalId` returns a canonical-shaped view of local state
+ * (columns projected to canonical field names) so the differ compares
+ * like-for-like against `Change.record` from the adapter. Internal DB
+ * mapping (canonical → local write, EAV dual-write, FK resolution) stays
+ * inside the sink implementation.
+ *
+ * Implementations compose the entity's service + (when the entity has EAV)
+ * `FieldValueService` inside a single transaction. ADR-13-revised.
+ */
+export interface ISyncSink<TCanonical> {
+  /**
+   * Canonical-shaped view of local state, or `null` when no local row exists.
+   * Called once per change to source the diff's "before" side.
+   */
+  findByExternalId(
+    userId: string,
+    externalId: string,
+  ): Promise<TCanonical | null>;
+
+  /**
+   * Insert-or-update by `external_id`. Must:
+   *   - run EAV dual-write in a single transaction when the entity has `fields`
+   *   - resolve FK references (e.g. `account_id` from `accountExternalId`)
+   *     via a repository lookup
+   *   - stamp `user_id` and `provider` from caller / context
+   *   - tolerate re-entry (same record twice in a window = no-op)
+   *
+   * Returns the local row id and the canonical projection of the saved row
+   * (so the orchestrator can record it on `sync_run_items.local_id`).
+   *
+   * `provider` is the adapter domain string (e.g. `'salesforce-crm'`,
+   * `'hubspot-crm'`) persisted on the DB row. Passed from
+   * `ExecuteSyncInput.provider`.
+   */
+  upsertByExternalId(
+    userId: string,
+    record: TCanonical,
+    provider: string,
+  ): Promise<{ id: string; saved: TCanonical }>;
+
+  /**
+   * Soft-delete by `external_id`. Called when `Change.operation === 'deleted'`.
+   * Returns `null` when no local row exists (orchestrator records a no-op).
+   */
+  softDeleteByExternalId(
+    userId: string,
+    externalId: string,
+  ): Promise<{ id: string } | null>;
+}

package/runtime/subsystems/sync/sync.module.ts

@@ -0,0 +1,156 @@
+/**
+ * SyncModule — `DynamicModule.forRoot({ backend, multiTenant? })` factory
+ * wiring the sync 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
+ *     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
+ *     `SalesforceOpportunityChangeSource`).
+ *   - `SYNC_SINK` — per canonical entity; consumer binds in their feature
+ *     module.
+ *   - `SYNC_LOOPBACK_FINGERPRINT_STORE` — optional; consumer provides
+ *     only when they have outbound writeback paths. `@Optional()` at the
+ *     orchestrator seam means absence is fine.
+ *   - `ExecuteSyncUseCase` — 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
+ *     compile time, which fails when the feature module hasn't been
+ *     imported yet. Consumers register `ExecuteSyncUseCase` in the same
+ *     `providers` array as their source + sink so resolution is local
+ *     to where all three are bound.
+ *
+ * Same shape as `EventsModule.forRoot` — the module wires the bus; you
+ * bring your own handlers. Here: the module wires the substrate; you
+ * bring your own source + sink.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * // AppModule — single source of truth for backend + multi-tenancy.
+ * @Module({
+ *   imports: [SyncModule.forRoot({ backend: 'drizzle' })],
+ * })
+ * export class AppModule {}
+ *
+ * // Per-entity feature module — binds source + sink, gets the
+ * // orchestrator for free.
+ * @Module({
+ *   providers: [
+ *     { provide: SYNC_CHANGE_SOURCE, useClass: SalesforceOpportunitySource },
+ *     { provide: SYNC_SINK,          useClass: OpportunitySyncSink },
+ *     ExecuteSyncUseCase,
+ *   ],
+ * })
+ * export class OpportunitySyncModule {
+ *   constructor(
+ *     private readonly execute: ExecuteSyncUseCase<CanonicalOpportunity>,
+ *   ) {}
+ * }
+ * ```
+ *
+ * `global: true` means feature modules do not need to re-import
+ * `SyncModule` — 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';
+import { DeepEqualDiffer } from './deep-equal.differ';
+
+export interface SyncModuleOptions {
+  /**
+   * Backend selection. `drizzle` wires the Postgres cursor store +
+   * run-log recorder; `memory` wires in-memory doubles suitable for
+   * tests + local dev.
+   */
+  backend: 'drizzle' | 'memory';
+
+  /**
+   * Multi-tenancy opt-in (SYNC-6).
+   *
+   * When `true`, every call to the orchestrator + both Drizzle backends
+   * must supply a non-null `tenantId`; missing values throw
+   * `MissingTenantIdError`. Defense-in-depth: the orchestrator rejects
+   * at entry (no dangling `status=running` rows) AND the Drizzle
+   * backends reject at their write boundary (belt-and-braces for any
+   * path that bypasses the orchestrator). Both sites use the shared
+   * `assertTenantId` helper so error messages match.
+   *
+   * Memory backends accept `tenantId` unconditionally — their state is
+   * process-local; cross-tenant isolation there is not meaningful.
+   *
+   * Defaults to `false`.
+   */
+  multiTenant?: boolean;
+}
+
+@Module({})
+export class SyncModule {
+  static forRoot(options: SyncModuleOptions): DynamicModule {
+    const multiTenant = options.multiTenant ?? false;
+
+    const sharedProviders: Provider[] = [
+      { provide: SYNC_MODULE_OPTIONS, useValue: options },
+      { provide: SYNC_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() },
+    ];
+
+    const backendProviders: Provider[] =
+      options.backend === 'memory'
+        ? [
+            // Wired as singletons via `useValue` so tests can pull
+            // them out via `moduleRef.get(MemoryCursorStore)` for
+            // direct assertions. Matches JOB-4 / MemoryJobStore shape.
+            { provide: MemoryCursorStore, useValue: new MemoryCursorStore() },
+            {
+              provide: SYNC_CURSOR_STORE,
+              useExisting: MemoryCursorStore,
+            },
+            { provide: MemoryRunRecorder, useValue: new MemoryRunRecorder() },
+            {
+              provide: SYNC_RUN_RECORDER,
+              useExisting: MemoryRunRecorder,
+            },
+          ]
+        : [
+            // Drizzle backends — injected with DRIZZLE (provided by the
+            // consumer's DrizzleModule) + the SYNC_MULTI_TENANT flag
+            // we bound above.
+            { provide: SYNC_CURSOR_STORE, useClass: PostgresCursorStore },
+            { provide: SYNC_RUN_RECORDER, useClass: DrizzleSyncRunRecorder },
+          ];
+
+    return {
+      module: SyncModule,
+      global: true,
+      providers: [...sharedProviders, ...backendProviders],
+      exports: [
+        SYNC_MODULE_OPTIONS,
+        SYNC_MULTI_TENANT,
+        SYNC_FIELD_DIFFER,
+        SYNC_CURSOR_STORE,
+        SYNC_RUN_RECORDER,
+      ],
+    };
+  }
+}