@pattern-stack/codegen 0.4.0 → 0.4.2

package/runtime/subsystems/sync/sync-audit.schema.ts

@@ -0,0 +1,300 @@
+/**
+ * Drizzle schema for the sync subsystem audit/observability tables (SYNC-1).
+ *
+ * Three tables model end-to-end sync observability, keyed by the single port
+ * every sync adapter implements (`IChangeSource<T>` from SYNC-2):
+ *
+ *   - `sync_subscriptions` — owns the cursor per
+ *       `(integration_id, adapter, domain, external_ref)` tuple. Addressed
+ *       by id by `ICursorStore` (SYNC-3/SYNC-4).
+ *   - `sync_runs`          — per-run audit log: start/complete, status,
+ *       cursor before/after, counts, direction (inbound|outbound),
+ *       action (poll|cdc|webhook|manual|writeback).
+ *   - `sync_run_items`     — per-record change log with structured
+ *       `changed_fields` jsonb enforced by the Zod `FieldDiffSchema`
+ *       contract (ADR-0003; protocol lives in SYNC-2's
+ *       sync-field-diff.protocol.ts).
+ *
+ * Design calls (vs. issue #126 open questions):
+ *
+ *   - `sync_subscriptions` ships in the subsystem (not consumer-owned).
+ *     Rationale: SYNC-4's `PostgresCursorStore` needs to read/write this
+ *     table directly; making it consumer-owned would require consumers to
+ *     hand-wire a shape the backend already knows. The row is addressable
+ *     by id and scoped by the uniqueness tuple; consumers can still
+ *     query/list it freely. Same stance as `job_run` being subsystem-
+ *     owned while remaining consumer-queryable.
+ *
+ *   - `tenant_id` is always emitted on the three tables as nullable text.
+ *     The `SYNC_MULTI_TENANT` DI flag (SYNC-6) is what enforces the
+ *     non-null + cross-tenant-isolation contract at the service/orchestrator
+ *     boundary. This mirrors JOB-1/JOB-8's final shape — runtime guard, not
+ *     a scaffold-time conditional column. Keeps the schema file uniform
+ *     across single-tenant and multi-tenant deployments.
+ *
+ *   - `changed_fields` on `sync_run_items` is typed via the Zod-inferred
+ *     `FieldDiff` shape from SYNC-2 (`{ [fieldName]: { from, to } }`). The
+ *     recorder service (SYNC-5) validates every write against
+ *     `FieldDiffSchema.parse` so consumers can rely on the shape.
+ */
+import {
+  pgEnum,
+  pgTable,
+  uuid,
+  text,
+  jsonb,
+  integer,
+  boolean,
+  timestamp,
+  index,
+  uniqueIndex,
+} from 'drizzle-orm/pg-core';
+import type { InferSelectModel } from 'drizzle-orm';
+
+import type { FieldDiff } from './sync-field-diff.protocol';
+
+// ─── Enums ──────────────────────────────────────────────────────────────────
+
+/**
+ * Direction of a sync run relative to local state.
+ *
+ *   - `inbound`  — external → local (the common case: SFDC poll → local DB).
+ *   - `outbound` — local → external (writeback; deferred per epic but the
+ *     column shape is reserved so future writeback runs share the audit log).
+ */
+export const syncRunDirectionEnum = pgEnum('sync_run_direction', [
+  'inbound',
+  'outbound',
+]);
+
+/**
+ * How the run detected upstream changes. Maps 1:1 to the `Change.source`
+ * provenance on inbound runs; `manual` captures operator-triggered re-syncs
+ * and `writeback` captures outbound runs.
+ */
+export const syncRunActionEnum = pgEnum('sync_run_action', [
+  'poll',
+  'cdc',
+  'webhook',
+  'manual',
+  'writeback',
+]);
+
+/**
+ * Lifecycle status of a sync run.
+ *
+ *   - `running`     — in-flight; recorder has started but not completed.
+ *   - `success`     — completed with at least one change processed.
+ *   - `no_changes`  — completed cleanly, no upstream changes found.
+ *   - `failed`      — errored before completion; `error` column carries the
+ *     message. `records_processed` may be non-zero (partial progress).
+ */
+export const syncRunStatusEnum = pgEnum('sync_run_status', [
+  'running',
+  'success',
+  'no_changes',
+  'failed',
+]);
+
+/**
+ * Operation applied per record. Mirrors `Change<T>.operation` from SYNC-2,
+ * plus the recorder's own `'noop'` for changes that matched existing state.
+ */
+export const syncRunItemOperationEnum = pgEnum('sync_run_item_operation', [
+  'created',
+  'updated',
+  'deleted',
+  'noop',
+]);
+
+/**
+ * Per-record status within a run. `skipped` captures loopback-detected echoes
+ * of the local system's own writes (see `ILoopbackFingerprintStore` in the
+ * epic), which record the external_id but intentionally do not touch local
+ * state.
+ */
+export const syncRunItemStatusEnum = pgEnum('sync_run_item_status', [
+  'success',
+  'failed',
+  'skipped',
+]);
+
+// ─── sync_subscriptions ─────────────────────────────────────────────────────
+
+/**
+ * One cursor owner per (integration, adapter, domain, external_ref).
+ *
+ *   - `integration_id` — opaque id of the connected account/instance. E.g.
+ *     the SFDC org id for polling strategies, the GitHub installation id
+ *     for webhook strategies.
+ *   - `adapter`        — short adapter label, e.g. `'salesforce'`, `'hubspot'`.
+ *   - `domain`         — canonical entity domain this subscription tracks,
+ *     e.g. `'opportunity'`, `'contact'`.
+ *   - `external_ref`   — optional upstream scope (e.g. a filter id, a
+ *     webhook subscription id). NULL when the subscription covers the
+ *     entire domain.
+ *
+ * The cursor shape is opaque jsonb — strategies type it internally (poll:
+ * `{ systemModstamp }`, cdc: `{ replayId }`, webhook: `{ ts }`). Overwritten
+ * by `ICursorStore.put(id, cursor)`.
+ */
+export const syncSubscriptions = pgTable(
+  'sync_subscriptions',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    integrationId: text('integration_id').notNull(),
+    adapter: text('adapter').notNull(),
+    domain: text('domain').notNull(),
+    externalRef: text('external_ref'),
+    enabled: boolean('enabled').notNull().default(true),
+    /**
+     * Per-subscription configuration bag. Strategies type it internally;
+     * e.g. polling strategies stash `{ batchSize, highWatermark }` here.
+     */
+    config: jsonb('config').notNull().default({}).$type<Record<string, unknown>>(),
+    /**
+     * Opaque cursor persisted by `ICursorStore.put()`. NULL until the first
+     * successful run advances it.
+     */
+    cursor: jsonb('cursor').$type<unknown>(),
+    lastSyncAt: timestamp('last_sync_at', { withTimezone: true }),
+    /** Runtime-enforced when `SYNC_MULTI_TENANT` is true; see SYNC-6. */
+    tenantId: text('tenant_id'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    /**
+     * Composite uniqueness per the epic shape. `external_ref` is nullable;
+     * Postgres treats NULLs as distinct in a UNIQUE constraint, which means
+     * two rows with the same `(integration_id, adapter, domain)` and NULL
+     * external_ref are allowed. That's intentional — a subscription with
+     * NULL external_ref covers the full domain, and duplicates there would
+     * be a consumer-layer modeling issue, not a schema concern.
+     */
+    uqSyncSubscriptionTuple: uniqueIndex('uq_sync_subscriptions_tuple').on(
+      t.integrationId,
+      t.adapter,
+      t.domain,
+      t.externalRef,
+    ),
+    /** Scheduling query: list enabled subscriptions ordered by staleness. */
+    idxSyncSubscriptionsEnabledLastSync: index(
+      'idx_sync_subscriptions_enabled_last_sync',
+    ).on(t.enabled, t.lastSyncAt),
+  }),
+);
+
+export type SyncSubscriptionRow = InferSelectModel<typeof syncSubscriptions>;
+
+// ─── sync_runs ──────────────────────────────────────────────────────────────
+
+/**
+ * One row per invocation of `ExecuteSyncUseCase`. `started_at` is set when
+ * the recorder opens the run; `completed_at`, `status`, `records_*`,
+ * `cursor_after`, and `duration_ms` are filled on completion.
+ *
+ * `cursor_before` / `cursor_after` carry the opaque cursor snapshots so the
+ * run log is fully self-describing — given a run id, an operator can reason
+ * about exactly what window was scanned without cross-referencing another
+ * table.
+ */
+export const syncRuns = pgTable(
+  'sync_runs',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    subscriptionId: uuid('subscription_id')
+      .notNull()
+      .references(() => syncSubscriptions.id, { onDelete: 'cascade' }),
+    direction: syncRunDirectionEnum('direction').notNull(),
+    action: syncRunActionEnum('action').notNull(),
+    status: syncRunStatusEnum('status').notNull().default('running'),
+    recordsFound: integer('records_found').notNull().default(0),
+    recordsProcessed: integer('records_processed').notNull().default(0),
+    cursorBefore: jsonb('cursor_before').$type<unknown>(),
+    cursorAfter: jsonb('cursor_after').$type<unknown>(),
+    durationMs: integer('duration_ms'),
+    error: text('error'),
+    startedAt: timestamp('started_at', { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+    completedAt: timestamp('completed_at', { withTimezone: true }),
+    /** Runtime-enforced when `SYNC_MULTI_TENANT` is true; see SYNC-6. */
+    tenantId: text('tenant_id'),
+  },
+  (t) => ({
+    /** Timeline read: "most recent runs for this subscription". */
+    idxSyncRunsSubscriptionStartedAt: index(
+      'idx_sync_runs_subscription_started_at',
+    ).on(t.subscriptionId, t.startedAt),
+    /** Stale-run sweeper: "runs that started > N minutes ago and are still running". */
+    idxSyncRunsStatusStartedAt: index('idx_sync_runs_status_started_at').on(
+      t.status,
+      t.startedAt,
+    ),
+  }),
+);
+
+export type SyncRunRow = InferSelectModel<typeof syncRuns>;
+
+// ─── sync_run_items ─────────────────────────────────────────────────────────
+
+/**
+ * One row per upstream change processed within a run. Captures the canonical
+ * decision the orchestrator made (`operation` + `status`), the structured
+ * per-field diff (`changed_fields`, ADR-0003), and the local row id
+ * (`local_id`) for drill-down joins.
+ *
+ * `changed_fields` is validated at the recorder layer via `FieldDiffSchema`
+ * (SYNC-2) — the $type<FieldDiff> annotation here only documents the shape
+ * for Drizzle consumers. The runtime enforcement is non-negotiable: downstream
+ * drift-detection queries rely on the `{from, to}` shape per field.
+ *
+ * `title` is an optional human-readable label captured at write time (e.g.
+ * `"Pinnacle opportunity"`) so run-log UIs don't need to re-hydrate the
+ * canonical record.
+ */
+export const syncRunItems = pgTable(
+  'sync_run_items',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    syncRunId: uuid('sync_run_id')
+      .notNull()
+      .references(() => syncRuns.id, { onDelete: 'cascade' }),
+    entityType: text('entity_type').notNull(),
+    externalId: text('external_id').notNull(),
+    localId: text('local_id'),
+    operation: syncRunItemOperationEnum('operation').notNull(),
+    status: syncRunItemStatusEnum('status').notNull(),
+    /**
+     * Structured per-field diff — ADR-0003 shape enforced by
+     * `FieldDiffSchema.parse` at the recorder service layer.
+     *
+     * Shape: `{ [fieldName]: { from: unknown, to: unknown } }`.
+     * Empty `{}` for `noop` items; `{ [field]: { from: null, to: <value> } }`
+     * for created items; `{ [field]: { from: <value>, to: null } }` for
+     * deleted items.
+     */
+    changedFields: jsonb('changed_fields').notNull().default({}).$type<FieldDiff>(),
+    title: text('title'),
+    error: text('error'),
+    createdAt: timestamp('created_at', { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+    /** Runtime-enforced when `SYNC_MULTI_TENANT` is true; see SYNC-6. */
+    tenantId: text('tenant_id'),
+  },
+  (t) => ({
+    /** Ordered timeline within a run. */
+    idxSyncRunItemsRunCreatedAt: index('idx_sync_run_items_run_created_at').on(
+      t.syncRunId,
+      t.createdAt,
+    ),
+    /** Per-record history: "every sync that touched opportunity/$extId". */
+    idxSyncRunItemsEntityExternal: index(
+      'idx_sync_run_items_entity_external',
+    ).on(t.entityType, t.externalId),
+  }),
+);
+
+export type SyncRunItemRow = InferSelectModel<typeof syncRunItems>;

package/runtime/subsystems/sync/sync-change-source.protocol.ts

@@ -0,0 +1,99 @@
+/**
+ * Sync subsystem — change-source protocol (port)
+ *
+ * `IChangeSource<T>` is the hexagonal port every sync adapter implements.
+ * Use cases inject this interface via `SYNC_CHANGE_SOURCE` token. They never
+ * depend on a specific backend implementation.
+ *
+ * Three detection modes (poll / cdc / webhook) converge on this single port
+ * per ADR-0002 (dealbrain-v2). Per-mode differences live in the
+ * `Change.source` / `dedupKey` / `providerChangedFields` metadata fields,
+ * not in separate ports.
+ *
+ * See epic #60 (parent) and upstream ADR-008 subsystem architecture.
+ */
+
+// ============================================================================
+// Change provenance + shape
+// ============================================================================
+
+/**
+ * Provenance of a change record. Maps 1:1 to `sync_runs.action` so run logs
+ * self-identify.
+ */
+export type ChangeSource = 'poll' | 'cdc' | 'webhook';
+
+/**
+ * One upstream change, normalized.
+ *
+ * The adapter has already translated provider-specific record shape into a
+ * canonical T. Custom fields flow through the `fields` bag on `record` when
+ * T supports it (adapters attach it; the sink splits and routes).
+ *
+ * `dedupKey` — set by CDC (replay_id) and webhook (event_id) paths; absent
+ * for polling. Orchestrator uses it for idempotent re-delivery when present,
+ * falls back to fingerprint-comparison otherwise.
+ *
+ * `providerChangedFields` — CDC-only. Lets the differ skip deep-equals when
+ * the provider already told us which fields moved; falls back to computed
+ * diff when absent.
+ *
+ * `cursor` — opaque at this seam. Each strategy types it internally (poll:
+ * `{ systemModstamp }`, CDC: `{ replayId }`, webhook: `{ ts }`) and the
+ * orchestrator persists whatever the strategy last yielded.
+ */
+export interface Change<T> {
+  readonly externalId: string;
+  readonly operation: 'created' | 'updated' | 'deleted';
+  readonly record: T;
+  readonly cursor: unknown;
+  readonly source: ChangeSource;
+  readonly dedupKey?: string;
+  readonly providerChangedFields?: string[];
+}
+
+// ============================================================================
+// Subscription shape (structural — consumer owns the row)
+// ============================================================================
+
+/**
+ * Minimal structural view of a sync-subscription row the port needs.
+ *
+ * The consumer owns the concrete `sync_subscriptions` table (schema lands in
+ * SYNC-1). This interface captures only the fields the port itself reads, so
+ * adapters can be typed without depending on the consumer's ORM row type.
+ */
+export interface SyncSubscriptionView {
+  /** Primary key — addresses the cursor in `ICursorStore`. */
+  readonly id: string;
+  /** Canonical entity domain, e.g. `'opportunity'`, `'contact'`. */
+  readonly domain: string;
+  /** Optional external reference — the upstream "scope" for this subscription. */
+  readonly externalRef?: string | null;
+}
+
+// ============================================================================
+// IChangeSource
+// ============================================================================
+
+/**
+ * The one port every sync adapter implements. Mode-specific concerns
+ * (scheduling, rate-limiting, ack contracts, credential refresh) stay in the
+ * strategy class that implements this interface — this seam is deliberately
+ * minimal.
+ *
+ * Strategies are per-provider per-mode per-entity — one concrete class per
+ * `(provider, detection-mode, canonical-entity)` tuple.
+ */
+export interface IChangeSource<T> {
+  /** Human label for run logs — e.g. `'salesforce-poll-opportunity'`. */
+  readonly label: string;
+
+  /**
+   * Async-iterate upstream changes, newest cursor last. The orchestrator
+   * persists `change.cursor` as it advances; strategies MUST yield at least
+   * one change before the async iterable completes if anything changed
+   * upstream, otherwise cursor advance is a no-op.
+   */
+  listChanges(subscription: SyncSubscriptionView): AsyncIterable<Change<T>>;
+}

package/runtime/subsystems/sync/sync-cursor-store.drizzle-backend.ts

@@ -0,0 +1,104 @@
+/**
+ * PostgresCursorStore — Drizzle-backed `ICursorStore` (SYNC-4).
+ *
+ * Reads/writes `sync_subscriptions.cursor` directly — no service
+ * composition. Consumers that want a service layer around subscriptions
+ * wire it themselves; the port's contract is just cursor persistence.
+ *
+ * ## What `put` stamps
+ *
+ * `put` writes three columns in one statement: `cursor`, `last_sync_at`,
+ * and `updated_at`. Rationale: SYNC-1's scheduling index
+ * `(enabled, last_sync_at)` is useless if `last_sync_at` doesn't advance
+ * with every cursor put. Every real consumer needs this stamped, so
+ * bundling it here avoids every consumer wrapping the port in a service
+ * layer just to stamp a timestamp.
+ *
+ * ## Multi-tenancy
+ *
+ * When `SYNC_MULTI_TENANT` is true (SYNC-6):
+ *   - every read/write is scoped by `AND tenant_id = $tenantId`
+ *   - a null/missing `tenantId` throws `MissingTenantIdError` via the
+ *     shared `assertTenantId` helper (one message shape across the
+ *     orchestrator + both backends, SYNC-6)
+ *   - explicit `null` also throws — matches JOB-8 / EVT-6 strict-enforcement
+ *
+ * When the flag is off, `tenantId` is ignored. Cross-tenant isolation is
+ * the caller's problem in single-tenant deployments.
+ */
+import { Inject, Injectable, Optional } from '@nestjs/common';
+import { and, eq, type SQL } from 'drizzle-orm';
+import type { DrizzleClient } from '../../types/drizzle';
+import { DRIZZLE } from '../../constants/tokens';
+import type { ICursorStore } from './sync-cursor-store.protocol';
+import { syncSubscriptions } from './sync-audit.schema';
+import { SYNC_MULTI_TENANT } from './sync.tokens';
+import { assertTenantId } from './sync-errors';
+
+@Injectable()
+export class PostgresCursorStore implements ICursorStore {
+  private readonly multiTenant: boolean;
+
+  constructor(
+    @Inject(DRIZZLE) private readonly db: DrizzleClient,
+    @Optional() @Inject(SYNC_MULTI_TENANT) multiTenant?: boolean,
+  ) {
+    this.multiTenant = multiTenant ?? false;
+  }
+
+  async get(
+    subscriptionId: string,
+    tenantId?: string | null,
+  ): Promise<unknown | null> {
+    const where = this.buildWhere(subscriptionId, tenantId, 'cursor.get');
+
+    const rows = await this.db
+      .select({ cursor: syncSubscriptions.cursor })
+      .from(syncSubscriptions)
+      .where(where)
+      .limit(1);
+
+    if (rows.length === 0) return null;
+    return rows[0]?.cursor ?? null;
+  }
+
+  async put(
+    subscriptionId: string,
+    cursor: unknown,
+    tenantId?: string | null,
+  ): Promise<void> {
+    const where = this.buildWhere(subscriptionId, tenantId, 'cursor.put');
+
+    await this.db
+      .update(syncSubscriptions)
+      .set({
+        cursor,
+        lastSyncAt: new Date(),
+        updatedAt: new Date(),
+      })
+      .where(where);
+  }
+
+  /**
+   * Centralized WHERE clause — `get` and `put` share identical semantics.
+   * Drift here would let a caller read under one tenancy rule and write
+   * under another.
+   */
+  private buildWhere(
+    subscriptionId: string,
+    tenantId: string | null | undefined,
+    operation: string,
+  ): SQL | undefined {
+    assertTenantId(tenantId, {
+      multiTenant: this.multiTenant,
+      operation,
+    });
+    if (this.multiTenant) {
+      return and(
+        eq(syncSubscriptions.id, subscriptionId),
+        eq(syncSubscriptions.tenantId, tenantId as string),
+      );
+    }
+    return eq(syncSubscriptions.id, subscriptionId);
+  }
+}

package/runtime/subsystems/sync/sync-cursor-store.memory-backend.ts

@@ -0,0 +1,64 @@
+/**
+ * MemoryCursorStore — in-memory backend for `ICursorStore` (SYNC-3).
+ *
+ * Test double that lets consumers exercise `ExecuteSyncUseCase` (SYNC-5) and
+ * other cursor-consuming code paths without Postgres. Mirrors the role of
+ * `MemoryEventBus` and `MemoryJobStore`: plain keyed state, tests take a
+ * direct reference for `beforeEach` resets.
+ *
+ * Cursor values are stored by reference — the port's `get`/`put` contract
+ * treats them as opaque `unknown`. Callers that want durable value-equality
+ * semantics should snapshot via JSON before `put` and reparse after `get`;
+ * this is what the Drizzle backend (SYNC-4) does implicitly via jsonb
+ * round-trip. The memory backend intentionally does not simulate the
+ * serialize/deserialize cycle — consumers who care should test against
+ * Postgres.
+ *
+ * ## Multi-tenancy
+ *
+ * `tenantId` is accepted but ignored. The memory backend's state is
+ * process-local — there's no durable storage where a cross-tenant leak
+ * could occur. Tests that want to assert per-tenant isolation should
+ * target the Drizzle backend.
+ *
+ * Not shipped in dealbrain-v2; this is a subsystem-first addition for the
+ * test surface. Consumed by:
+ *   - SYNC-5 unit tests (`ExecuteSyncUseCase` against synthetic sources)
+ *   - SYNC-6 module tests (`SyncModule.forRoot({ backend: 'memory' })`)
+ */
+import { Injectable } from '@nestjs/common';
+import type { ICursorStore } from './sync-cursor-store.protocol';
+
+@Injectable()
+export class MemoryCursorStore implements ICursorStore {
+  /**
+   * Subscription-id → last persisted cursor. Public so tests can inspect
+   * or pre-seed state; production callers MUST go through `get`/`put`.
+   */
+  readonly cursors: Map<string, unknown> = new Map();
+
+  async get(
+    subscriptionId: string,
+    _tenantId?: string | null,
+  ): Promise<unknown | null> {
+    // `Map.get` returns `undefined` for missing keys; the port contract
+    // returns `null`. Normalize here so callers can `=== null`-check.
+    const value = this.cursors.get(subscriptionId);
+    return value === undefined ? null : value;
+  }
+
+  async put(
+    subscriptionId: string,
+    cursor: unknown,
+    _tenantId?: string | null,
+  ): Promise<void> {
+    // Overwrite semantics — matches the port contract and the Drizzle
+    // backend's `ON CONFLICT DO UPDATE` behavior.
+    this.cursors.set(subscriptionId, cursor);
+  }
+
+  /** Reset state. Tests call this in `beforeEach`. */
+  clear(): void {
+    this.cursors.clear();
+  }
+}

package/runtime/subsystems/sync/sync-cursor-store.protocol.ts

@@ -0,0 +1,53 @@
+/**
+ * Sync subsystem — cursor-store protocol (port)
+ *
+ * Subscription-addressed cursor persistence. The subscription row IS the
+ * cursor owner — addressable by id, scoped by
+ * `(integration, adapter, domain, external_ref)` at the subscription level.
+ *
+ * Cursor shape is opaque at this seam; strategies type it internally
+ * (polling: `{ systemModstamp }`, CDC: `{ replayId }`, webhook: `{ ts }`).
+ * The Drizzle backend stores this as `sync_subscriptions.cursor` jsonb.
+ *
+ * ## Multi-tenancy (SYNC-4)
+ *
+ * Both methods accept an optional `tenantId`. When `SYNC_MULTI_TENANT` is
+ * enabled (SYNC-6), the Drizzle backend MUST scope every read/write by
+ * `tenant_id`, and a `null`/missing value throws `MissingTenantIdError` at
+ * the module boundary. When the flag is off, `tenantId` is ignored.
+ *
+ * The in-memory backend ignores `tenantId` unconditionally — its state is
+ * process-local; cross-tenant isolation there is not meaningful.
+ *
+ * Why a signature change instead of a tenant-proxy wrapper: multi-tenant
+ * correctness bugs are silent and dangerous (cross-tenant cursor tampering).
+ * An explicit signature catches omissions at the type boundary; proxies
+ * hide who's enforcing. Matches JOB-8 / EVT-6 precedent — tenant ids flow
+ * through input shapes, not through wrapper layers.
+ */
+export interface ICursorStore {
+  /**
+   * Return the last persisted cursor for `subscriptionId`, or `null`.
+   *
+   * @param tenantId  required when `SYNC_MULTI_TENANT` is on (backend
+   *                  scopes the SELECT by tenant); ignored otherwise.
+   */
+  get(subscriptionId: string, tenantId?: string | null): Promise<unknown | null>;
+
+  /**
+   * Persist `cursor` for `subscriptionId`. Overwrites.
+   *
+   * The Drizzle backend also stamps `last_sync_at` + `updated_at` on the
+   * same row so the scheduling index `(enabled, last_sync_at)` stays
+   * accurate without consumers wrapping the port. The memory backend
+   * ignores timestamps.
+   *
+   * @param tenantId  required when `SYNC_MULTI_TENANT` is on (backend
+   *                  scopes the UPDATE by tenant); ignored otherwise.
+   */
+  put(
+    subscriptionId: string,
+    cursor: unknown,
+    tenantId?: string | null,
+  ): Promise<void>;
+}

package/runtime/subsystems/sync/sync-errors.ts

@@ -0,0 +1,54 @@
+/**
+ * Typed errors + shared boundary helpers for the sync subsystem.
+ *
+ * Classes (not bare Error) so consumers can `instanceof` them in catch
+ * blocks and exception filters can map them to HTTP codes.
+ *
+ * Mirrors the shape of `events-errors.ts` and `jobs-errors.ts`.
+ */
+
+/**
+ * Thrown by the Drizzle cursor-store / run-recorder backends AND by the
+ * orchestrator entry point when `SYNC_MULTI_TENANT` is enabled but the
+ * caller did not supply a non-null `tenantId`. Strict enforcement at the
+ * boundary — explicit `null` still throws.
+ *
+ * Disable multi-tenancy on the module (`multiTenant: false`, the default)
+ * to opt out of the requirement entirely.
+ *
+ * `operation` identifies the call site (e.g. `'cursor.put'`,
+ * `'startRun'`, `'execute'`) so the stack-trace message points at the
+ * specific boundary that rejected the input.
+ */
+export class MissingTenantIdError extends Error {
+  override readonly name = 'MissingTenantIdError';
+  constructor(operation: string) {
+    super(
+      `Missing tenantId for sync operation '${operation}'. SyncModule is ` +
+        `configured with multiTenant: true — every call must include a ` +
+        `non-null tenantId. Either pass the tenantId or disable multi-` +
+        `tenancy on the module.`,
+    );
+  }
+}
+
+/**
+ * Shared boundary guard — used at the orchestrator entry AND inside the
+ * Drizzle backends. Keeping the check in one function guarantees every
+ * `MissingTenantIdError` carries the same message shape regardless of the
+ * site that raised it, which makes it easier for consumers to pattern-
+ * match on the error in logs/metrics.
+ *
+ * When `multiTenant` is false, the function is a no-op — `tenantId` may
+ * be anything (including `undefined`). When true, `undefined` or `null`
+ * throws.
+ */
+export function assertTenantId(
+  tenantId: string | null | undefined,
+  options: { multiTenant: boolean; operation: string },
+): asserts tenantId is string {
+  if (!options.multiTenant) return;
+  if (tenantId === undefined || tenantId === null) {
+    throw new MissingTenantIdError(options.operation);
+  }
+}