@pattern-stack/codegen 0.7.4 → 0.7.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",

package/runtime/base-classes/index.ts

@@ -19,8 +19,17 @@ export type { EventCategory } from './lifecycle-events';
 export { BaseFindByIdUseCase, BaseListUseCase } from './base-read-use-cases';
 export type { IFindByIdService, IListService } from './base-read-use-cases';
 
+// Sync upsert config (consumed by SyncedEntityRepository + JunctionSyncRepository)
+export type { SyncUpsertConfig, SyncFkResolver } from './sync-upsert-config';
+
 // Family-specific repository base classes
 export { SyncedEntityRepository } from './synced-entity-repository';
+export {
+  JunctionSyncRepository,
+  buildCompositeExternalId,
+  parseCompositeExternalId,
+} from './junction-sync-repository';
+export type { JunctionSyncConfig } from './junction-sync-repository';
 export { ActivityEntityRepository } from './activity-entity-repository';
 export { MetadataEntityRepository } from './metadata-entity-repository';
 export { KnowledgeEntityRepository } from './knowledge-entity-repository';

package/runtime/base-classes/junction-sync-repository.ts

@@ -0,0 +1,284 @@
+/**
+ * JunctionSyncRepository<TEntity, TSyncWrite, TSyncProjection>
+ *
+ * Base for junction repos that participate in inbound sync (#374). A junction's
+ * sync identity is the tuple `(leftId, rightId[, role])` — there is no native
+ * `external_id`/`provider` column, so the sync seam's externalId is a COMPOSITE
+ * string `<leftExternalId>::<rightExternalId>[::<role>]` (see the static
+ * build/parse helpers below).
+ *
+ * Both parent FKs are resolved STRICTLY in the write path (a missing parent
+ * throws → the orchestrator records a failed item and continues). As of #372
+ * role-bearing junctions carry a unique constraint over `(left, right, role)`,
+ * so the upsert uses `onConflictDoUpdate` (not the legacy select-then-write).
+ * Role-less junctions conflict on `(left, right)`.
+ */
+import { and, eq } from 'drizzle-orm';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+import type { PgTableWithColumns } from 'drizzle-orm/pg-core';
+import type { DrizzleTx } from '../types/drizzle';
+import { BaseRepository } from './base-repository';
+
+export interface JunctionSyncConfig {
+  /** Left endpoint: local FK column (camel) + strict parent table. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  left: { column: string; refTable: PgTableWithColumns<any> };
+  /** Right endpoint: local FK column (camel) + strict parent table. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  right: { column: string; refTable: PgTableWithColumns<any> };
+  /** Role column (camel), or null for a role-less (2-part composite) junction. */
+  roleColumn: string | null;
+}
+
+export abstract class JunctionSyncRepository<
+  TEntity,
+  TSyncWrite,
+  TSyncProjection,
+> extends BaseRepository<TEntity> {
+  /**
+   * Declarative junction sync surface. Concrete repos declare this — the
+   * template emits it with live parent-table handles.
+   */
+  protected abstract readonly syncConfig: JunctionSyncConfig;
+
+  /**
+   * Upsert ONE junction row by its composite identity, in a single transaction:
+   *   1. resolve the REQUIRED left FK (provider-scoped) — STRICT: missing → throws;
+   *   2. resolve the REQUIRED right FK (provider-scoped) — STRICT: missing → throws;
+   *   3. insert-or-update on the `(left, right[, role])` conflict target.
+   *
+   * Idempotent. Returns the composite externalId as the projection `id`.
+   *
+   * @param write     parent external ids (`<left>ExternalId`/`<right>ExternalId`)
+   *                  + optional `role` + `userId`
+   * @param provider  adapter/provider label used to scope the parent lookups
+   * @param tx        optional outer transaction; when omitted we open our own
+   */
+  async syncUpsertOne(
+    write: TSyncWrite,
+    provider: string,
+    tx?: DrizzleTx,
+  ): Promise<TSyncProjection> {
+    const cfg = this.syncConfig;
+    const w = write as Record<string, unknown>;
+    const leftWriteKey = `${cfg.left.column.replace(/Id$/, '')}ExternalId`;
+    const rightWriteKey = `${cfg.right.column.replace(/Id$/, '')}ExternalId`;
+
+    const run = async (db: DrizzleTx): Promise<TSyncProjection> => {
+      const leftId = await this.resolveStrict(
+        db, cfg.left.refTable, w[leftWriteKey] as string, provider, cfg.left.column,
+      );
+      const rightId = await this.resolveStrict(
+        db, cfg.right.refTable, w[rightWriteKey] as string, provider, cfg.right.column,
+      );
+
+      const now = new Date();
+      const role = cfg.roleColumn ? (w['role'] as unknown) : undefined;
+      const values: Record<string, unknown> = {
+        [cfg.left.column]: leftId,
+        [cfg.right.column]: rightId,
+        ...(cfg.roleColumn ? { [cfg.roleColumn]: role } : {}),
+        ...(this.behaviors.timestamps ? { updatedAt: now } : {}),
+      };
+      const target = cfg.roleColumn
+        ? [this.table[cfg.left.column], this.table[cfg.right.column], this.table[cfg.roleColumn]]
+        : [this.table[cfg.left.column], this.table[cfg.right.column]];
+
+      const rows = await db
+        .insert(this.table)
+        .values(values as never)
+        .onConflictDoUpdate({
+          target,
+          set: { ...(this.behaviors.timestamps ? { updatedAt: now } : {}) } as never,
+        })
+        .returning();
+
+      const saved = rows[0] as Record<string, unknown>;
+      return this.toProjection(saved as TEntity, w, provider);
+    };
+
+    return tx ? run(tx) : this.db.transaction((t) => run(t));
+  }
+
+  /**
+   * Canonical-projected lookup by the COMPOSITE externalId, differ-ready. Parses
+   * the composite, resolves BOTH parents NON-throwing (→ null), then selects by
+   * the identity tuple. Returns `null` on malformed composite / unresolved
+   * parent / no row (a missing "before" side is a create from the differ's view).
+   */
+  async findByExternalIdProjected(
+    externalId: string,
+    provider: string,
+  ): Promise<TSyncProjection | null> {
+    const cfg = this.syncConfig;
+    const parsed = parseCompositeExternalId(externalId, cfg.roleColumn !== null);
+    if (!parsed) return null;
+
+    const leftId = await this.resolveLoose(this.db, cfg.left.refTable, parsed.left, provider);
+    if (leftId === null) return null;
+    const rightId = await this.resolveLoose(this.db, cfg.right.refTable, parsed.right, provider);
+    if (rightId === null) return null;
+
+    const rows = await this.db
+      .select()
+      .from(this.table)
+      .where(this.identityWhere(leftId, rightId, parsed.role))
+      .limit(1);
+    const row = rows[0] as TEntity | undefined;
+    if (!row) return null;
+
+    const w: Record<string, unknown> = {
+      [`${cfg.left.column.replace(/Id$/, '')}ExternalId`]: parsed.left,
+      [`${cfg.right.column.replace(/Id$/, '')}ExternalId`]: parsed.right,
+      ...(cfg.roleColumn ? { role: parsed.role } : {}),
+      userId: '',
+    };
+    return this.toProjection(row, w, provider);
+  }
+
+  /**
+   * Hard-delete the junction by composite externalId. Junctions have no
+   * `deleted_at` and no external-linkage columns to clear, so a sync "delete"
+   * removes the row. Resolves both parents NON-throwing, then deletes by the
+   * identity tuple. Returns the composite id, or `null` when nothing matched.
+   */
+  async softDeleteByExternalId(
+    externalId: string,
+    provider: string,
+    tx?: DrizzleTx,
+  ): Promise<{ id: string } | null> {
+    const cfg = this.syncConfig;
+    const parsed = parseCompositeExternalId(externalId, cfg.roleColumn !== null);
+    if (!parsed) return null;
+    const db = this.runner(tx);
+
+    const leftId = await this.resolveLoose(db, cfg.left.refTable, parsed.left, provider);
+    if (leftId === null) return null;
+    const rightId = await this.resolveLoose(db, cfg.right.refTable, parsed.right, provider);
+    if (rightId === null) return null;
+
+    const rows = await db
+      .delete(this.table)
+      .where(this.identityWhere(leftId, rightId, parsed.role))
+      .returning({ id: this.table[cfg.left.column] });
+    return rows[0] ? { id: externalId } : null;
+  }
+
+  /**
+   * Project a raw junction row to the differ shape. `id` is the COMPOSITE
+   * externalId (the junction has no surrogate id). Override to widen the
+   * projection beyond the identity tuple (the template emits a concrete
+   * `toProjection` carrying the role + local FKs + timestamps).
+   */
+  protected toProjection(
+    _row: TEntity,
+    write: Record<string, unknown>,
+    _provider: string,
+  ): TSyncProjection {
+    const cfg = this.syncConfig;
+    const leftExt = write[`${cfg.left.column.replace(/Id$/, '')}ExternalId`] as string;
+    const rightExt = write[`${cfg.right.column.replace(/Id$/, '')}ExternalId`] as string;
+    const role = cfg.roleColumn ? (write['role'] as string) : undefined;
+    return { id: buildCompositeExternalId(leftExt, rightExt, role) } as TSyncProjection;
+  }
+
+  /** Build the identity WHERE clause `(left, right[, role])`. */
+  private identityWhere(leftId: string, rightId: string, role: string | undefined) {
+    const cfg = this.syncConfig;
+    const conds = [
+      eq(this.table[cfg.left.column], leftId),
+      eq(this.table[cfg.right.column], rightId),
+    ];
+    if (cfg.roleColumn && role !== undefined) {
+      conds.push(eq(this.table[cfg.roleColumn], role));
+    }
+    return and(...conds);
+  }
+
+  /** Resolve a parent id (provider-scoped), throwing when unresolved. */
+  private async resolveStrict(
+    db: DrizzleTx,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    refTable: PgTableWithColumns<any>,
+    parentExternalId: string,
+    provider: string,
+    column: string,
+  ): Promise<string> {
+    const id = await this.resolveLoose(db, refTable, parentExternalId, provider);
+    if (!id) {
+      throw new Error(
+        `${this.constructor.name}.syncUpsertOne: unresolved parent ` +
+          `'${parentExternalId}' (provider '${provider}') for '${column}' — ` +
+          `parent not synced yet`,
+      );
+    }
+    return id;
+  }
+
+  /** Resolve a parent id (provider-scoped), returning null when unresolved. */
+  private async resolveLoose(
+    db: DrizzleTx,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    refTable: PgTableWithColumns<any>,
+    parentExternalId: string | null | undefined,
+    provider: string,
+  ): Promise<string | null> {
+    if (!parentExternalId) return null;
+    const rows = await db
+      .select({ id: refTable['id'] })
+      .from(refTable)
+      .where(
+        and(
+          eq(refTable['provider'], provider),
+          eq(refTable['externalId'], parentExternalId),
+        ),
+      )
+      .limit(1);
+    return (rows[0]?.id as string | undefined) ?? null;
+  }
+}
+
+// ============================================================================
+// Composite externalId — the junction sync seam's deterministic identity.
+//
+// Format: `<leftExternalId>::<rightExternalId>[::<role>]`
+//   e.g. `hubspot:42::hubspot:99::employee`  (role-bearing)
+//        `hubspot:42::hubspot:99`            (role-less)
+//
+// Vendor-prefixed ids use a SINGLE colon, so `::` is an unambiguous delimiter.
+// Kept static in the base (replacing the per-repo free functions) so every
+// junction's lookups + its ChangeSource share one definition.
+// ============================================================================
+
+/**
+ * Build the composite externalId from the two parent external ids (+ role when
+ * the junction is role-bearing).
+ */
+export function buildCompositeExternalId(
+  leftExternalId: string,
+  rightExternalId: string,
+  role?: string,
+): string {
+  return role !== undefined
+    ? `${leftExternalId}::${rightExternalId}::${role}`
+    : `${leftExternalId}::${rightExternalId}`;
+}
+
+/**
+ * Parse a composite externalId. `withRole` selects the expected part count
+ * (3 when role-bearing, else 2). Returns `null` when the shape doesn't match
+ * or any part is empty.
+ */
+export function parseCompositeExternalId(
+  externalId: string,
+  withRole: boolean,
+): { left: string; right: string; role: string | undefined } | null {
+  const parts = externalId.split('::');
+  const expected = withRole ? 3 : 2;
+  if (parts.length !== expected || parts.some((p) => p.length === 0)) return null;
+  return {
+    left: parts[0] as string,
+    right: parts[1] as string,
+    role: withRole ? (parts[2] as string) : undefined,
+  };
+}

package/runtime/base-classes/sync-upsert-config.ts

@@ -0,0 +1,58 @@
+/**
+ * SyncUpsertConfig + SyncFkResolver
+ *
+ * Declarative description of an entity's inbound-sync write surface, consumed
+ * by `SyncedEntityRepository.syncUpsertOne` / `findByExternalIdProjected` /
+ * `softDeleteByExternalId` / `toProjection`. Each `pattern: Synced` repository
+ * declares a concrete `syncConfig: SyncUpsertConfig` (emitted by the template),
+ * the same idiom as `behaviors: BehaviorConfig`.
+ *
+ * Named `SyncUpsertConfig` (not `SyncConfig`) to avoid colliding with the sync
+ * subsystem's `DetectionConfig`/`SyncConfig` surface.
+ *
+ * The generic upsert separates three column roles:
+ *   - identity      (`conflictTarget`) — only in `values`, never in `set`
+ *   - copy-through  (`writeColumns`)   — in both `values` and `set`
+ *   - resolved FK   (`fkResolvers`)    — conditional in `set` (no-clobber)
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+import type { PgTableWithColumns } from 'drizzle-orm/pg-core';
+
+/**
+ * Resolves a local FK column from a parent's external id, provider-scoped.
+ *
+ * The base does `SELECT id FROM <refTable> WHERE (provider, externalId) =
+ * (provider, write[writeKey])`. `refTable === 'self'` resolves to `this.table`
+ * (self-FK). `strict: true` throws when the parent is unresolved (junction
+ * posture); falsy leaves the column null this run (opportunistic, entity
+ * posture).
+ */
+export interface SyncFkResolver {
+  /** Local FK column — camel key into `this.table`, e.g. `'parentAccountId'`. */
+  column: string;
+  /** Key on `TSyncWrite` carrying the parent external id (see Decision 4). */
+  writeKey: string;
+  /** Parent table to resolve against; `'self'` → `this.table`. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  refTable: PgTableWithColumns<any> | 'self';
+  /** true = throw on unresolved (junction); falsy = opportunistic null (entity). */
+  strict?: boolean;
+}
+
+export interface SyncUpsertConfig {
+  /** Camel keys into `this.table` forming the conflict target, e.g. `['provider', 'externalId']`. */
+  conflictTarget: string[];
+  /**
+   * Canonical columns copied verbatim write→values/set (camel). EXCLUDES
+   * `externalId`, `provider`, FK columns, and behavior-managed timestamps.
+   */
+  writeColumns: string[];
+  /** Conditional, provider-scoped FK resolvers. */
+  fkResolvers: SyncFkResolver[];
+  /** Columns picked into the projection (camel), incl. id/externalId/timestamps. */
+  projectionColumns: string[];
+  /** When true, `syncUpsertOne` calls `writeCustomFields` for a non-empty `fields` bag. */
+  eav: boolean;
+  /** When true, deletes set `deletedAt`; when false, tombstone-by-clearing external_id/provider. */
+  softDelete: boolean;
+}

package/runtime/base-classes/synced-entity-repository.ts

@@ -1,15 +1,32 @@
 /**
- * SyncedEntityRepository<TEntity>
+ * SyncedEntityRepository<TEntity, TSyncWrite, TSyncProjection>
  *
  * Family-specific base for Synced entities (contacts, accounts, opportunities).
- * Adds external ID lookups, user-scoped queries, and sync stubs.
+ * Adds external ID lookups, user-scoped queries, and the generic inbound-sync
+ * write surface (canonical→Drizzle upsert + provider-scoped FK resolution +
+ * EAV dual-write seam), driven by the concrete repo's `syncConfig`.
  *
- * Concrete repos extend this and declare their table + behaviors.
+ * The type params default so pre-existing single-param subclasses keep
+ * compiling; `pattern: Synced` repos declare all three plus `syncConfig`.
  */
-import { eq, inArray } from 'drizzle-orm';
+import { and, eq, inArray } from 'drizzle-orm';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+import type { PgTableWithColumns } from 'drizzle-orm/pg-core';
+import type { DrizzleTx } from '../types/drizzle';
 import { BaseRepository } from './base-repository';
+import type { SyncUpsertConfig, SyncFkResolver } from './sync-upsert-config';
+
+export abstract class SyncedEntityRepository<
+  TEntity,
+  TSyncWrite = Partial<TEntity>,
+  TSyncProjection = TEntity,
+> extends BaseRepository<TEntity> {
+  /**
+   * Declarative sync write surface. Concrete (`pattern: Synced`) repositories
+   * declare this — the template emits it from the entity's fields + FKs.
+   */
+  protected abstract readonly syncConfig: SyncUpsertConfig;
 
-export abstract class SyncedEntityRepository<TEntity> extends BaseRepository<TEntity> {
   /**
    * Find a single entity by its external CRM identifier.
    */
@@ -39,12 +56,249 @@ export abstract class SyncedEntityRepository<TEntity> extends BaseRepository<TEn
     return rows as TEntity[];
   }
 
+  // ==========================================================================
+  // Inbound sync (#374) — canonical→Drizzle write + provider-scoped FK
+  // resolution + EAV dual-write seam, all inside a SINGLE transaction.
+  // Driven entirely by `this.syncConfig`; the per-entity shape lives there.
+  // ==========================================================================
+
+  /**
+   * Upsert ONE entity by its `(provider, externalId)` identity, in a single
+   * transaction:
+   *   1. resolve each `syncConfig.fkResolvers` FK (provider-scoped). Strict
+   *      resolvers throw on unresolved; non-strict leave the column null.
+   *   2. insert-or-update the canonical columns via `onConflictDoUpdate` on the
+   *      `conflictTarget`. Resolved FKs are only written into `set` when
+   *      non-null this run (no-clobber).
+   *   3. EAV dual-write of `write.fields` via `writeCustomFields` when
+   *      `syncConfig.eav` and the bag is non-empty (same tx).
+   *
+   * Idempotent: a second call with the same identity updates in place. Returns
+   * the canonical projection (so the orchestrator records `local_id`).
+   *
+   * @param write     canonical fields + parent external ids + custom-field bag
+   * @param provider  adapter/provider label persisted + used to scope lookups
+   * @param tx        optional outer transaction; when omitted we open our own
+   */
+  async syncUpsertOne(
+    write: TSyncWrite,
+    provider: string,
+    tx?: DrizzleTx,
+  ): Promise<TSyncProjection> {
+    const cfg = this.syncConfig;
+    const w = write as Record<string, unknown>;
+
+    const run = async (db: DrizzleTx): Promise<TSyncProjection> => {
+      // 1. FK resolution (provider-scoped). Strict → throw; else opportunistic null.
+      const resolvedFks: Record<string, string | null> = {};
+      for (const fk of cfg.fkResolvers) {
+        resolvedFks[fk.column] = await this.resolveFk(db, fk, w[fk.writeKey], provider);
+      }
+
+      // 2. Canonical → Drizzle insert-or-update by the conflict target.
+      const now = new Date();
+      const copyThrough: Record<string, unknown> = {};
+      for (const col of cfg.writeColumns) copyThrough[col] = w[col];
+
+      const values: Record<string, unknown> = {
+        externalId: w['externalId'],
+        provider,
+        ...copyThrough,
+        ...resolvedFks,
+        ...(this.behaviors.timestamps ? { updatedAt: now } : {}),
+      };
+
+      // `set` excludes the identity (externalId/provider). Resolved FKs are
+      // only written when non-null this run — never clobber a previously
+      // resolved parent with null on a later run that dropped the ref.
+      const set: Record<string, unknown> = {
+        ...copyThrough,
+        ...(this.behaviors.timestamps ? { updatedAt: now } : {}),
+      };
+      for (const fk of cfg.fkResolvers) {
+        if (resolvedFks[fk.column] !== null) set[fk.column] = resolvedFks[fk.column];
+      }
+
+      const rows = await db
+        .insert(this.table)
+        .values(values as never)
+        .onConflictDoUpdate({
+          target: cfg.conflictTarget.map((c: string) => this.table[c]),
+          set: set as never,
+        })
+        .returning();
+
+      const saved = rows[0] as Record<string, unknown>;
+
+      // 3. EAV dual-write seam — same tx. No-op unless the entity opts in.
+      const fields = w['fields'] as Record<string, unknown> | undefined;
+      if (cfg.eav && fields && Object.keys(fields).length > 0) {
+        await this.writeCustomFields(
+          db,
+          saved['id'] as string,
+          w['userId'] as string,
+          fields,
+        );
+      }
+
+      return this.toProjection(saved as TEntity);
+    };
+
+    return tx ? run(tx) : this.db.transaction((t) => run(t));
+  }
+
   /**
-   * Sync upsert — bulk insert-or-update from external CRM data.
-   * Concrete repositories must implement with the appropriate conflict target.
+   * Canonical-projected lookup by external id (differ-ready). Returns `null`
+   * when no local row exists. Provider-scoped so a HubSpot id can't match a
+   * Salesforce row.
    */
-  async syncUpsert(_inputs: Array<Partial<TEntity>>): Promise<TEntity[]> {
-    throw new Error('syncUpsert not implemented — override in concrete repository');
+  async findByExternalIdProjected(
+    externalId: string,
+    provider: string,
+  ): Promise<TSyncProjection | null> {
+    const rows = await this.db
+      .select()
+      .from(this.table)
+      .where(
+        and(
+          eq(this.table['provider'], provider),
+          eq(this.table['externalId'], externalId),
+        ),
+      )
+      .limit(1);
+    const row = rows[0] as TEntity | undefined;
+    return row ? this.toProjection(row) : null;
+  }
+
+  /**
+   * Sync "delete" by external id, provider-scoped. When `softDelete: true`,
+   * sets `deletedAt`. When `softDelete: false`, tombstone-by-clearing: null out
+   * `external_id`/`provider` so the row no longer matches future inbound
+   * changes while preserving local-id references. Returns `{ id }` or `null`.
+   */
+  async softDeleteByExternalId(
+    externalId: string,
+    provider: string,
+    tx?: DrizzleTx,
+  ): Promise<{ id: string } | null> {
+    const db = this.runner(tx);
+    const set = this.syncConfig.softDelete
+      ? { deletedAt: new Date(), updatedAt: new Date() }
+      : { externalId: null, provider: null, updatedAt: new Date() };
+    const rows = await db
+      .update(this.table)
+      .set(set as never)
+      .where(
+        and(
+          eq(this.table['provider'], provider),
+          eq(this.table['externalId'], externalId),
+        ),
+      )
+      .returning({ id: this.table['id'] });
+    return rows[0] ? { id: rows[0].id as string } : null;
+  }
+
+  /**
+   * Batch sync upsert — concretizes the former abstract stub. Delegates to
+   * `syncUpsertOne` per input inside one transaction. Inputs are raw partial
+   * rows: provider is read from each input's own `provider` column; rows
+   * missing `externalId`/`provider` are skipped.
+   */
+  async syncUpsert(inputs: Array<Partial<TEntity>>): Promise<TEntity[]> {
+    if (inputs.length === 0) return [];
+    return this.db.transaction(async (tx) => {
+      const out: TEntity[] = [];
+      for (const input of inputs) {
+        const rec = input as Record<string, unknown>;
+        if (!rec['externalId'] || !rec['provider']) continue;
+        const proj = await this.syncUpsertOne(
+          input as unknown as TSyncWrite,
+          rec['provider'] as string,
+          tx,
+        );
+        const id = (proj as Record<string, unknown>)['id'] as string;
+        const row = await tx
+          .select()
+          .from(this.table)
+          .where(eq(this.table['id'], id))
+          .limit(1);
+        out.push(row[0] as TEntity);
+      }
+      return out;
+    });
+  }
+
+  /**
+   * Project a raw row to the canonical differ shape — a generic pick over
+   * `syncConfig.projectionColumns`. Override only for synthesized projections
+   * (e.g. junctions); entities use this verbatim.
+   */
+  protected toProjection(row: TEntity): TSyncProjection {
+    const r = row as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const col of this.syncConfig.projectionColumns) out[col] = r[col];
+    return out as TSyncProjection;
+  }
+
+  /**
+   * EAV dual-write seam (#374, live path lands in #124). No-op by default;
+   * `eav: true` entities emit a concrete override that injects
+   * `FieldValueService` and delegates to `upsertFieldsTransactional` so the
+   * dual-write joins the same tx (`db`). Kept as an explicit hook so the base
+   * stays portable (the FieldValueService dependency is eav-only).
+   */
+  protected async writeCustomFields(
+    _db: DrizzleTx,
+    _entityId: string,
+    _userId: string,
+    _fields: Record<string, unknown>,
+  ): Promise<void> {
+    // Intentionally empty until the entity opts into EAV.
+  }
+
+  /**
+   * Resolve one FK from a parent external id (provider-scoped). `self` resolves
+   * against `this.table`. Strict resolvers throw when unresolved; non-strict
+   * return null. A null/absent write value short-circuits to null.
+   */
+  private async resolveFk(
+    db: DrizzleTx,
+    fk: SyncFkResolver,
+    rawExternalId: unknown,
+    provider: string,
+  ): Promise<string | null> {
+    const parentExternalId = rawExternalId as string | null | undefined;
+    if (!parentExternalId) {
+      if (fk.strict) {
+        throw new Error(
+          `${this.constructor.name}.syncUpsertOne: missing required parent ` +
+            `external id for '${fk.column}' (writeKey '${fk.writeKey}')`,
+        );
+      }
+      return null;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const refTable: PgTableWithColumns<any> =
+      fk.refTable === 'self' ? this.table : fk.refTable;
+    const rows = await db
+      .select({ id: refTable['id'] })
+      .from(refTable)
+      .where(
+        and(
+          eq(refTable['provider'], provider),
+          eq(refTable['externalId'], parentExternalId),
+        ),
+      )
+      .limit(1);
+    const id = (rows[0]?.id as string | undefined) ?? null;
+    if (id === null && fk.strict) {
+      throw new Error(
+        `${this.constructor.name}.syncUpsertOne: unresolved parent ` +
+          `'${parentExternalId}' (provider '${provider}') for '${fk.column}' — ` +
+          `parent not synced yet`,
+      );
+    }
+    return id;
   }
 
   /**