@pattern-stack/codegen 0.7.5 → 0.7.7

package/dist/runtime/base-classes/junction-sync-repository.js

@@ -0,0 +1,373 @@
+// runtime/base-classes/junction-sync-repository.ts
+import { and, eq as eq2 } from "drizzle-orm";
+
+// runtime/base-classes/base-repository.ts
+import { eq, inArray, isNull, sql } from "drizzle-orm";
+var BaseRepository = class {
+  // eslint-disable-line @typescript-eslint/no-explicit-any
+  /**
+   * Behavior flags controlling automatic behavior injection.
+   * Override in concrete repositories to enable behaviors.
+   */
+  behaviors = {
+    timestamps: false,
+    softDelete: false,
+    userTracking: false
+  };
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+  /**
+   * Pick the runner for a write: the caller-supplied transaction handle
+   * if present, otherwise the repository's own client. Keeps the `tx`
+   * parameter purely additive — callers without a transaction call as
+   * before. Used by the write methods below + consumer overrides (e.g.
+   * the generated `upsertCurrentValues` on EAV value tables).
+   */
+  runner(tx) {
+    return tx ?? this.db;
+  }
+  // ============================================================================
+  // Read Operations
+  // ============================================================================
+  /**
+   * Find a single entity by its primary key.
+   * Returns null if not found (or soft-deleted when softDelete=true).
+   */
+  async findById(id) {
+    const rows = await this.baseQuery().where(eq(this.table["id"], id)).limit(1);
+    return rows[0] ?? null;
+  }
+  /**
+   * Find multiple entities by their primary keys.
+   * Returns empty array immediately for empty input (avoids DB errors).
+   */
+  async findByIds(ids) {
+    if (ids.length === 0) return [];
+    const rows = await this.baseQuery().where(inArray(this.table["id"], ids));
+    return rows;
+  }
+  /**
+   * List entities with optional filtering, pagination, and ordering.
+   */
+  async list(options) {
+    let query = this.baseQuery();
+    if (options?.where) {
+      query = query.where(options.where);
+    }
+    if (options?.orderBy) {
+      query = query.orderBy(options.orderBy);
+    }
+    if (options?.limit !== void 0) {
+      query = query.limit(options.limit);
+    }
+    if (options?.offset !== void 0) {
+      query = query.offset(options.offset);
+    }
+    const rows = await query;
+    return rows;
+  }
+  /**
+   * Count entities matching an optional WHERE clause.
+   * Soft-deleted rows are always excluded when softDelete=true.
+   */
+  async count(where) {
+    let query = this.db.select({ count: sql`cast(count(*) as integer)` }).from(this.table);
+    const conditions = [];
+    if (this.behaviors.softDelete) {
+      conditions.push(isNull(this.table["deletedAt"]));
+    }
+    if (where) {
+      conditions.push(where);
+    }
+    if (conditions.length === 1) {
+      query = query.where(conditions[0]);
+    } else if (conditions.length > 1) {
+      const { and: and2 } = await import("drizzle-orm");
+      query = query.where(and2(...conditions));
+    }
+    const rows = await query;
+    return rows[0]?.count ?? 0;
+  }
+  /**
+   * Check whether an entity with the given id exists.
+   */
+  async exists(id) {
+    const result = await this.findById(id);
+    return result !== null;
+  }
+  // ============================================================================
+  // Write Operations
+  // ============================================================================
+  /**
+   * Insert a new entity. Timestamps are auto-injected when timestamps=true.
+   */
+  async create(input, tx) {
+    const data = this.withTimestamps(input, "create");
+    const rows = await this.runner(tx).insert(this.table).values(data).returning();
+    return rows[0];
+  }
+  /**
+   * Update an existing entity by id. updatedAt is auto-injected when timestamps=true.
+   * Returns the updated entity.
+   */
+  async update(id, input, tx) {
+    const data = this.withTimestamps(input, "update");
+    const rows = await this.runner(tx).update(this.table).set(data).where(eq(this.table["id"], id)).returning();
+    return rows[0];
+  }
+  /**
+   * Delete an entity by id.
+   * - softDelete=true: sets deletedAt to current timestamp
+   * - softDelete=false: hard-deletes the row
+   */
+  async delete(id, tx) {
+    const runner = this.runner(tx);
+    if (this.behaviors.softDelete) {
+      await runner.update(this.table).set({ deletedAt: /* @__PURE__ */ new Date() }).where(eq(this.table["id"], id));
+    } else {
+      await runner.delete(this.table).where(eq(this.table["id"], id));
+    }
+  }
+  /**
+   * Insert or update multiple entities.
+   * Default naive implementation — family repositories override with
+   * proper conflict-target upsert (e.g., CrmEntityRepository).
+   */
+  async upsertMany(inputs, tx) {
+    return Promise.all(inputs.map((input) => this.create(input, tx)));
+  }
+  // ============================================================================
+  // Protected Helpers
+  // ============================================================================
+  /**
+   * Base SELECT query that automatically excludes soft-deleted rows
+   * when softDelete behavior is enabled.
+   */
+  baseQuery() {
+    const query = this.db.select().from(this.table).$dynamic();
+    if (this.behaviors.softDelete) {
+      return query.where(isNull(this.table["deletedAt"]));
+    }
+    return query;
+  }
+  /**
+   * Merge timestamp fields into an input object.
+   * - mode='create': adds createdAt and updatedAt
+   * - mode='update': adds updatedAt only
+   *
+   * No-op when timestamps behavior is disabled.
+   */
+  withTimestamps(input, mode) {
+    if (!this.behaviors.timestamps) return input;
+    const now = /* @__PURE__ */ new Date();
+    if (mode === "create") {
+      return { ...input, createdAt: now, updatedAt: now };
+    }
+    return { ...input, updatedAt: now };
+  }
+  /**
+   * Build a WHERE clause fragment that restricts results to rows whose
+   * parent (identified by a belongs_to FK) is not soft-deleted.
+   *
+   * Use this in custom repository methods when you need "rows reachable
+   * from an active parent". The default findAll / findById behavior is
+   * NOT changed by this helper — opt in explicitly where needed.
+   *
+   * ADR-021 — Soft-delete cascade: Option A (filter at query time).
+   * `on_delete` FK rules do not fire for soft-deletes; use this helper
+   * instead of expecting cascade semantics on the DB level.
+   *
+   * Example:
+   *   async listActiveMessages(): Promise<Message[]> {
+   *     return this.list({
+   *       where: this.activeParentFilter(conversations, this.table['conversationId']),
+   *     });
+   *   }
+   *
+   * @param parentTable  The Drizzle table object for the parent entity.
+   * @param parentFkColumn  The FK column on this (child) table that references parent.id.
+   */
+  activeParentFilter(parentTable, parentFkColumn) {
+    return sql`EXISTS (
+      SELECT 1 FROM ${parentTable} p
+      WHERE p.id = ${parentFkColumn}
+        AND p.deleted_at IS NULL
+    )`;
+  }
+};
+
+// runtime/base-classes/junction-sync-repository.ts
+var JunctionSyncRepository = class extends BaseRepository {
+  /**
+   * 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, provider, tx) {
+    const cfg = this.syncConfig;
+    const w = write;
+    const leftWriteKey = `${cfg.left.column.replace(/Id$/, "")}ExternalId`;
+    const rightWriteKey = `${cfg.right.column.replace(/Id$/, "")}ExternalId`;
+    const run = async (db) => {
+      const leftId = await this.resolveStrict(
+        db,
+        cfg.left.refTable,
+        w[leftWriteKey],
+        provider,
+        cfg.left.column
+      );
+      const rightId = await this.resolveStrict(
+        db,
+        cfg.right.refTable,
+        w[rightWriteKey],
+        provider,
+        cfg.right.column
+      );
+      const now = /* @__PURE__ */ new Date();
+      const role = cfg.roleColumn ? w["role"] : void 0;
+      const values = {
+        [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).onConflictDoUpdate({
+        target,
+        set: { ...this.behaviors.timestamps ? { updatedAt: now } : {} }
+      }).returning();
+      const saved = rows[0];
+      return this.toProjection(saved, 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, provider) {
+    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];
+    if (!row) return null;
+    const w = {
+      [`${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, provider, tx) {
+    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: the COMPOSITE externalId
+   * `id` (junctions have no surrogate id) plus the local FK columns, role (when
+   * role-bearing) and timestamps — matching the emitted
+   * `<Junction>SyncProjection` interface (id + leftId + rightId + role? +
+   * createdAt + updatedAt). Junction projections are purely structural, so this
+   * is fully generic over `syncConfig` — no per-junction override is emitted.
+   */
+  toProjection(row, write, _provider) {
+    const cfg = this.syncConfig;
+    const r = row;
+    const leftExt = write[`${cfg.left.column.replace(/Id$/, "")}ExternalId`];
+    const rightExt = write[`${cfg.right.column.replace(/Id$/, "")}ExternalId`];
+    const role = cfg.roleColumn ? r[cfg.roleColumn] : void 0;
+    const out = {
+      id: buildCompositeExternalId(leftExt, rightExt, role),
+      [cfg.left.column]: r[cfg.left.column],
+      [cfg.right.column]: r[cfg.right.column]
+    };
+    if (cfg.roleColumn) out[cfg.roleColumn] = r[cfg.roleColumn];
+    out["createdAt"] = r["createdAt"];
+    out["updatedAt"] = r["updatedAt"];
+    return out;
+  }
+  /** Build the identity WHERE clause `(left, right[, role])`. */
+  identityWhere(leftId, rightId, role) {
+    const cfg = this.syncConfig;
+    const conds = [
+      eq2(this.table[cfg.left.column], leftId),
+      eq2(this.table[cfg.right.column], rightId)
+    ];
+    if (cfg.roleColumn && role !== void 0) {
+      conds.push(eq2(this.table[cfg.roleColumn], role));
+    }
+    return and(...conds);
+  }
+  /** Resolve a parent id (provider-scoped), throwing when unresolved. */
+  async resolveStrict(db, refTable, parentExternalId, provider, column) {
+    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}' \u2014 parent not synced yet`
+      );
+    }
+    return id;
+  }
+  /** Resolve a parent id (provider-scoped), returning null when unresolved. */
+  async resolveLoose(db, refTable, parentExternalId, provider) {
+    if (!parentExternalId) return null;
+    const rows = await db.select({ id: refTable["id"] }).from(refTable).where(
+      and(
+        eq2(refTable["provider"], provider),
+        eq2(refTable["externalId"], parentExternalId)
+      )
+    ).limit(1);
+    return rows[0]?.id ?? null;
+  }
+};
+function buildCompositeExternalId(leftExternalId, rightExternalId, role) {
+  return role !== void 0 ? `${leftExternalId}::${rightExternalId}::${role}` : `${leftExternalId}::${rightExternalId}`;
+}
+function parseCompositeExternalId(externalId, withRole) {
+  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],
+    right: parts[1],
+    role: withRole ? parts[2] : void 0
+  };
+}
+export {
+  JunctionSyncRepository,
+  buildCompositeExternalId,
+  parseCompositeExternalId
+};
+//# sourceMappingURL=junction-sync-repository.js.map

package/dist/runtime/base-classes/junction-sync-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../runtime/base-classes/junction-sync-repository.ts","../../../runtime/base-classes/base-repository.ts"],"sourcesContent":["/**\n * JunctionSyncRepository<TEntity, TSyncWrite, TSyncProjection>\n *\n * Base for junction repos that participate in inbound sync (#374). A junction's\n * sync identity is the tuple `(leftId, rightId[, role])` — there is no native\n * `external_id`/`provider` column, so the sync seam's externalId is a COMPOSITE\n * string `<leftExternalId>::<rightExternalId>[::<role>]` (see the static\n * build/parse helpers below).\n *\n * Both parent FKs are resolved STRICTLY in the write path (a missing parent\n * throws → the orchestrator records a failed item and continues). As of #372\n * role-bearing junctions carry a unique constraint over `(left, right, role)`,\n * so the upsert uses `onConflictDoUpdate` (not the legacy select-then-write).\n * Role-less junctions conflict on `(left, right)`.\n */\nimport { and, eq } from 'drizzle-orm';\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nimport type { PgTableWithColumns } from 'drizzle-orm/pg-core';\nimport type { DrizzleTx } from '../types/drizzle';\nimport { BaseRepository } from './base-repository';\n\nexport interface JunctionSyncConfig {\n  /** Left endpoint: local FK column (camel) + strict parent table. */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  left: { column: string; refTable: PgTableWithColumns<any> };\n  /** Right endpoint: local FK column (camel) + strict parent table. */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  right: { column: string; refTable: PgTableWithColumns<any> };\n  /** Role column (camel), or null for a role-less (2-part composite) junction. */\n  roleColumn: string | null;\n}\n\nexport abstract class JunctionSyncRepository<\n  TEntity,\n  TSyncWrite,\n  TSyncProjection,\n> extends BaseRepository<TEntity> {\n  /**\n   * Declarative junction sync surface. Concrete repos declare this — the\n   * template emits it with live parent-table handles.\n   */\n  protected abstract readonly syncConfig: JunctionSyncConfig;\n\n  /**\n   * Upsert ONE junction row by its composite identity, in a single transaction:\n   *   1. resolve the REQUIRED left FK (provider-scoped) — STRICT: missing → throws;\n   *   2. resolve the REQUIRED right FK (provider-scoped) — STRICT: missing → throws;\n   *   3. insert-or-update on the `(left, right[, role])` conflict target.\n   *\n   * Idempotent. Returns the composite externalId as the projection `id`.\n   *\n   * @param write     parent external ids (`<left>ExternalId`/`<right>ExternalId`)\n   *                  + optional `role` + `userId`\n   * @param provider  adapter/provider label used to scope the parent lookups\n   * @param tx        optional outer transaction; when omitted we open our own\n   */\n  async syncUpsertOne(\n    write: TSyncWrite,\n    provider: string,\n    tx?: DrizzleTx,\n  ): Promise<TSyncProjection> {\n    const cfg = this.syncConfig;\n    const w = write as Record<string, unknown>;\n    const leftWriteKey = `${cfg.left.column.replace(/Id$/, '')}ExternalId`;\n    const rightWriteKey = `${cfg.right.column.replace(/Id$/, '')}ExternalId`;\n\n    const run = async (db: DrizzleTx): Promise<TSyncProjection> => {\n      const leftId = await this.resolveStrict(\n        db, cfg.left.refTable, w[leftWriteKey] as string, provider, cfg.left.column,\n      );\n      const rightId = await this.resolveStrict(\n        db, cfg.right.refTable, w[rightWriteKey] as string, provider, cfg.right.column,\n      );\n\n      const now = new Date();\n      const role = cfg.roleColumn ? (w['role'] as unknown) : undefined;\n      const values: Record<string, unknown> = {\n        [cfg.left.column]: leftId,\n        [cfg.right.column]: rightId,\n        ...(cfg.roleColumn ? { [cfg.roleColumn]: role } : {}),\n        ...(this.behaviors.timestamps ? { updatedAt: now } : {}),\n      };\n      const target = cfg.roleColumn\n        ? [this.table[cfg.left.column], this.table[cfg.right.column], this.table[cfg.roleColumn]]\n        : [this.table[cfg.left.column], this.table[cfg.right.column]];\n\n      const rows = await db\n        .insert(this.table)\n        .values(values as never)\n        .onConflictDoUpdate({\n          target,\n          set: { ...(this.behaviors.timestamps ? { updatedAt: now } : {}) } as never,\n        })\n        .returning();\n\n      const saved = rows[0] as Record<string, unknown>;\n      return this.toProjection(saved as TEntity, w, provider);\n    };\n\n    return tx ? run(tx) : this.db.transaction((t) => run(t));\n  }\n\n  /**\n   * Canonical-projected lookup by the COMPOSITE externalId, differ-ready. Parses\n   * the composite, resolves BOTH parents NON-throwing (→ null), then selects by\n   * the identity tuple. Returns `null` on malformed composite / unresolved\n   * parent / no row (a missing \"before\" side is a create from the differ's view).\n   */\n  async findByExternalIdProjected(\n    externalId: string,\n    provider: string,\n  ): Promise<TSyncProjection | null> {\n    const cfg = this.syncConfig;\n    const parsed = parseCompositeExternalId(externalId, cfg.roleColumn !== null);\n    if (!parsed) return null;\n\n    const leftId = await this.resolveLoose(this.db, cfg.left.refTable, parsed.left, provider);\n    if (leftId === null) return null;\n    const rightId = await this.resolveLoose(this.db, cfg.right.refTable, parsed.right, provider);\n    if (rightId === null) return null;\n\n    const rows = await this.db\n      .select()\n      .from(this.table)\n      .where(this.identityWhere(leftId, rightId, parsed.role))\n      .limit(1);\n    const row = rows[0] as TEntity | undefined;\n    if (!row) return null;\n\n    const w: Record<string, unknown> = {\n      [`${cfg.left.column.replace(/Id$/, '')}ExternalId`]: parsed.left,\n      [`${cfg.right.column.replace(/Id$/, '')}ExternalId`]: parsed.right,\n      ...(cfg.roleColumn ? { role: parsed.role } : {}),\n      userId: '',\n    };\n    return this.toProjection(row, w, provider);\n  }\n\n  /**\n   * Hard-delete the junction by composite externalId. Junctions have no\n   * `deleted_at` and no external-linkage columns to clear, so a sync \"delete\"\n   * removes the row. Resolves both parents NON-throwing, then deletes by the\n   * identity tuple. Returns the composite id, or `null` when nothing matched.\n   */\n  async softDeleteByExternalId(\n    externalId: string,\n    provider: string,\n    tx?: DrizzleTx,\n  ): Promise<{ id: string } | null> {\n    const cfg = this.syncConfig;\n    const parsed = parseCompositeExternalId(externalId, cfg.roleColumn !== null);\n    if (!parsed) return null;\n    const db = this.runner(tx);\n\n    const leftId = await this.resolveLoose(db, cfg.left.refTable, parsed.left, provider);\n    if (leftId === null) return null;\n    const rightId = await this.resolveLoose(db, cfg.right.refTable, parsed.right, provider);\n    if (rightId === null) return null;\n\n    const rows = await db\n      .delete(this.table)\n      .where(this.identityWhere(leftId, rightId, parsed.role))\n      .returning({ id: this.table[cfg.left.column] });\n    return rows[0] ? { id: externalId } : null;\n  }\n\n  /**\n   * Project a raw junction row to the differ shape: the COMPOSITE externalId\n   * `id` (junctions have no surrogate id) plus the local FK columns, role (when\n   * role-bearing) and timestamps — matching the emitted\n   * `<Junction>SyncProjection` interface (id + leftId + rightId + role? +\n   * createdAt + updatedAt). Junction projections are purely structural, so this\n   * is fully generic over `syncConfig` — no per-junction override is emitted.\n   */\n  protected toProjection(\n    row: TEntity,\n    write: Record<string, unknown>,\n    _provider: string,\n  ): TSyncProjection {\n    const cfg = this.syncConfig;\n    const r = row as Record<string, unknown>;\n    const leftExt = write[`${cfg.left.column.replace(/Id$/, '')}ExternalId`] as string;\n    const rightExt = write[`${cfg.right.column.replace(/Id$/, '')}ExternalId`] as string;\n    const role = cfg.roleColumn ? (r[cfg.roleColumn] as string | undefined) : undefined;\n    const out: Record<string, unknown> = {\n      id: buildCompositeExternalId(leftExt, rightExt, role),\n      [cfg.left.column]: r[cfg.left.column],\n      [cfg.right.column]: r[cfg.right.column],\n    };\n    if (cfg.roleColumn) out[cfg.roleColumn] = r[cfg.roleColumn];\n    out['createdAt'] = r['createdAt'];\n    out['updatedAt'] = r['updatedAt'];\n    return out as TSyncProjection;\n  }\n\n  /** Build the identity WHERE clause `(left, right[, role])`. */\n  private identityWhere(leftId: string, rightId: string, role: string | undefined) {\n    const cfg = this.syncConfig;\n    const conds = [\n      eq(this.table[cfg.left.column], leftId),\n      eq(this.table[cfg.right.column], rightId),\n    ];\n    if (cfg.roleColumn && role !== undefined) {\n      conds.push(eq(this.table[cfg.roleColumn], role));\n    }\n    return and(...conds);\n  }\n\n  /** Resolve a parent id (provider-scoped), throwing when unresolved. */\n  private async resolveStrict(\n    db: DrizzleTx,\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    refTable: PgTableWithColumns<any>,\n    parentExternalId: string,\n    provider: string,\n    column: string,\n  ): Promise<string> {\n    const id = await this.resolveLoose(db, refTable, parentExternalId, provider);\n    if (!id) {\n      throw new Error(\n        `${this.constructor.name}.syncUpsertOne: unresolved parent ` +\n          `'${parentExternalId}' (provider '${provider}') for '${column}' — ` +\n          `parent not synced yet`,\n      );\n    }\n    return id;\n  }\n\n  /** Resolve a parent id (provider-scoped), returning null when unresolved. */\n  private async resolveLoose(\n    db: DrizzleTx,\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    refTable: PgTableWithColumns<any>,\n    parentExternalId: string | null | undefined,\n    provider: string,\n  ): Promise<string | null> {\n    if (!parentExternalId) return null;\n    const rows = await db\n      .select({ id: refTable['id'] })\n      .from(refTable)\n      .where(\n        and(\n          eq(refTable['provider'], provider),\n          eq(refTable['externalId'], parentExternalId),\n        ),\n      )\n      .limit(1);\n    return (rows[0]?.id as string | undefined) ?? null;\n  }\n}\n\n// ============================================================================\n// Composite externalId — the junction sync seam's deterministic identity.\n//\n// Format: `<leftExternalId>::<rightExternalId>[::<role>]`\n//   e.g. `hubspot:42::hubspot:99::employee`  (role-bearing)\n//        `hubspot:42::hubspot:99`            (role-less)\n//\n// Vendor-prefixed ids use a SINGLE colon, so `::` is an unambiguous delimiter.\n// Kept static in the base (replacing the per-repo free functions) so every\n// junction's lookups + its ChangeSource share one definition.\n// ============================================================================\n\n/**\n * Build the composite externalId from the two parent external ids (+ role when\n * the junction is role-bearing).\n */\nexport function buildCompositeExternalId(\n  leftExternalId: string,\n  rightExternalId: string,\n  role?: string,\n): string {\n  return role !== undefined\n    ? `${leftExternalId}::${rightExternalId}::${role}`\n    : `${leftExternalId}::${rightExternalId}`;\n}\n\n/**\n * Parse a composite externalId. `withRole` selects the expected part count\n * (3 when role-bearing, else 2). Returns `null` when the shape doesn't match\n * or any part is empty.\n */\nexport function parseCompositeExternalId(\n  externalId: string,\n  withRole: boolean,\n): { left: string; right: string; role: string | undefined } | null {\n  const parts = externalId.split('::');\n  const expected = withRole ? 3 : 2;\n  if (parts.length !== expected || parts.some((p) => p.length === 0)) return null;\n  return {\n    left: parts[0] as string,\n    right: parts[1] as string,\n    role: withRole ? (parts[2] as string) : undefined,\n  };\n}\n","/**\n * BaseRepository<TEntity>\n *\n * Abstract base class providing standard CRUD operations via Drizzle ORM.\n * Every generated repository extends this class.\n *\n * Family-specific bases (CrmEntityRepository, etc.) extend this in v0.1\n * without any changes to BaseRepository.\n *\n * NOT @Injectable — concrete repositories are @Injectable and inject DRIZZLE.\n */\nimport { eq, inArray, isNull, sql } from 'drizzle-orm';\nimport type { PgTableWithColumns, PgColumn } from 'drizzle-orm/pg-core';\nimport type { SQL } from 'drizzle-orm';\nimport type { DrizzleClient, DrizzleTx } from '../types/drizzle';\n\n// ============================================================================\n// Interfaces\n// ============================================================================\n\n/**\n * Behavior flags for the repository. Controls automatic timestamp injection\n * and soft-delete filtering.\n */\nexport interface BehaviorConfig {\n  timestamps: boolean;\n  softDelete: boolean;\n  userTracking: boolean;\n}\n\n/**\n * Options for the list() method.\n */\nexport interface ListOptions {\n  where?: SQL;\n  limit?: number;\n  offset?: number;\n  orderBy?: PgColumn | SQL;\n}\n\n// ============================================================================\n// BaseRepository\n// ============================================================================\n\nexport abstract class BaseRepository<TEntity> {\n  /**\n   * The Drizzle table schema for this entity.\n   * Concrete repositories declare this as a class property.\n   */\n  protected abstract readonly table: PgTableWithColumns<any>; // eslint-disable-line @typescript-eslint/no-explicit-any\n\n  /**\n   * Behavior flags controlling automatic behavior injection.\n   * Override in concrete repositories to enable behaviors.\n   */\n  protected readonly behaviors: BehaviorConfig = {\n    timestamps: false,\n    softDelete: false,\n    userTracking: false,\n  };\n\n  protected readonly db: DrizzleClient;\n\n  constructor(db: DrizzleClient) {\n    this.db = db;\n  }\n\n  /**\n   * Pick the runner for a write: the caller-supplied transaction handle\n   * if present, otherwise the repository's own client. Keeps the `tx`\n   * parameter purely additive — callers without a transaction call as\n   * before. Used by the write methods below + consumer overrides (e.g.\n   * the generated `upsertCurrentValues` on EAV value tables).\n   */\n  protected runner(tx?: DrizzleTx): DrizzleClient {\n    return tx ?? this.db;\n  }\n\n  // ============================================================================\n  // Read Operations\n  // ============================================================================\n\n  /**\n   * Find a single entity by its primary key.\n   * Returns null if not found (or soft-deleted when softDelete=true).\n   */\n  async findById(id: string): Promise<TEntity | null> {\n    const rows = await this.baseQuery()\n      .where(eq(this.table['id'], id))\n      .limit(1);\n    return (rows[0] as TEntity) ?? null;\n  }\n\n  /**\n   * Find multiple entities by their primary keys.\n   * Returns empty array immediately for empty input (avoids DB errors).\n   */\n  async findByIds(ids: string[]): Promise<TEntity[]> {\n    if (ids.length === 0) return [];\n    const rows = await this.baseQuery().where(inArray(this.table['id'], ids));\n    return rows as TEntity[];\n  }\n\n  /**\n   * List entities with optional filtering, pagination, and ordering.\n   */\n  async list(options?: ListOptions): Promise<TEntity[]> {\n    let query = this.baseQuery();\n\n    if (options?.where) {\n      query = query.where(options.where) as typeof query;\n    }\n    if (options?.orderBy) {\n      query = query.orderBy(options.orderBy as SQL) as typeof query;\n    }\n    if (options?.limit !== undefined) {\n      query = query.limit(options.limit) as typeof query;\n    }\n    if (options?.offset !== undefined) {\n      query = query.offset(options.offset) as typeof query;\n    }\n\n    const rows = await query;\n    return rows as TEntity[];\n  }\n\n  /**\n   * Count entities matching an optional WHERE clause.\n   * Soft-deleted rows are always excluded when softDelete=true.\n   */\n  async count(where?: SQL): Promise<number> {\n    let query = this.db\n      .select({ count: sql<number>`cast(count(*) as integer)` })\n      .from(this.table);\n\n    const conditions: SQL[] = [];\n    if (this.behaviors.softDelete) {\n      conditions.push(isNull(this.table['deletedAt']));\n    }\n    if (where) {\n      conditions.push(where);\n    }\n\n    if (conditions.length === 1) {\n      query = query.where(conditions[0]) as typeof query;\n    } else if (conditions.length > 1) {\n      // Combine with AND by building the condition inline\n      const { and } = await import('drizzle-orm');\n      query = query.where(and(...conditions)) as typeof query;\n    }\n\n    const rows = await query;\n    return rows[0]?.count ?? 0;\n  }\n\n  /**\n   * Check whether an entity with the given id exists.\n   */\n  async exists(id: string): Promise<boolean> {\n    const result = await this.findById(id);\n    return result !== null;\n  }\n\n  // ============================================================================\n  // Write Operations\n  // ============================================================================\n\n  /**\n   * Insert a new entity. Timestamps are auto-injected when timestamps=true.\n   */\n  async create(input: Partial<TEntity>, tx?: DrizzleTx): Promise<TEntity> {\n    const data = this.withTimestamps(input as Record<string, unknown>, 'create');\n    const rows = await this.runner(tx)\n      .insert(this.table)\n      .values(data as any) // eslint-disable-line @typescript-eslint/no-explicit-any\n      .returning();\n    return rows[0] as TEntity;\n  }\n\n  /**\n   * Update an existing entity by id. updatedAt is auto-injected when timestamps=true.\n   * Returns the updated entity.\n   */\n  async update(id: string, input: Partial<TEntity>, tx?: DrizzleTx): Promise<TEntity> {\n    const data = this.withTimestamps(input as Record<string, unknown>, 'update');\n    const rows = await this.runner(tx)\n      .update(this.table)\n      .set(data as any) // eslint-disable-line @typescript-eslint/no-explicit-any\n      .where(eq(this.table['id'], id))\n      .returning();\n    return rows[0] as TEntity;\n  }\n\n  /**\n   * Delete an entity by id.\n   * - softDelete=true: sets deletedAt to current timestamp\n   * - softDelete=false: hard-deletes the row\n   */\n  async delete(id: string, tx?: DrizzleTx): Promise<void> {\n    const runner = this.runner(tx);\n    if (this.behaviors.softDelete) {\n      await runner\n        .update(this.table)\n        .set({ deletedAt: new Date() } as any) // eslint-disable-line @typescript-eslint/no-explicit-any\n        .where(eq(this.table['id'], id));\n    } else {\n      await runner\n        .delete(this.table)\n        .where(eq(this.table['id'], id));\n    }\n  }\n\n  /**\n   * Insert or update multiple entities.\n   * Default naive implementation — family repositories override with\n   * proper conflict-target upsert (e.g., CrmEntityRepository).\n   */\n  async upsertMany(inputs: Array<Partial<TEntity>>, tx?: DrizzleTx): Promise<TEntity[]> {\n    return Promise.all(inputs.map((input) => this.create(input, tx)));\n  }\n\n  // ============================================================================\n  // Protected Helpers\n  // ============================================================================\n\n  /**\n   * Base SELECT query that automatically excludes soft-deleted rows\n   * when softDelete behavior is enabled.\n   */\n  protected baseQuery() {\n    const query = this.db.select().from(this.table).$dynamic();\n    if (this.behaviors.softDelete) {\n      return query.where(isNull(this.table['deletedAt']));\n    }\n    return query;\n  }\n\n  /**\n   * Merge timestamp fields into an input object.\n   * - mode='create': adds createdAt and updatedAt\n   * - mode='update': adds updatedAt only\n   *\n   * No-op when timestamps behavior is disabled.\n   */\n  protected withTimestamps(\n    input: Record<string, unknown>,\n    mode: 'create' | 'update',\n  ): Record<string, unknown> {\n    if (!this.behaviors.timestamps) return input;\n    const now = new Date();\n    if (mode === 'create') {\n      return { ...input, createdAt: now, updatedAt: now };\n    }\n    return { ...input, updatedAt: now };\n  }\n\n  /**\n   * Build a WHERE clause fragment that restricts results to rows whose\n   * parent (identified by a belongs_to FK) is not soft-deleted.\n   *\n   * Use this in custom repository methods when you need \"rows reachable\n   * from an active parent\". The default findAll / findById behavior is\n   * NOT changed by this helper — opt in explicitly where needed.\n   *\n   * ADR-021 — Soft-delete cascade: Option A (filter at query time).\n   * `on_delete` FK rules do not fire for soft-deletes; use this helper\n   * instead of expecting cascade semantics on the DB level.\n   *\n   * Example:\n   *   async listActiveMessages(): Promise<Message[]> {\n   *     return this.list({\n   *       where: this.activeParentFilter(conversations, this.table['conversationId']),\n   *     });\n   *   }\n   *\n   * @param parentTable  The Drizzle table object for the parent entity.\n   * @param parentFkColumn  The FK column on this (child) table that references parent.id.\n   */\n  protected activeParentFilter(\n    parentTable: PgTableWithColumns<any>, // eslint-disable-line @typescript-eslint/no-explicit-any\n    parentFkColumn: PgColumn,\n  ): SQL {\n    return sql`EXISTS (\n      SELECT 1 FROM ${parentTable} p\n      WHERE p.id = ${parentFkColumn}\n        AND p.deleted_at IS NULL\n    )`;\n  }\n}\n"],"mappings":"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","names":["eq","and","eq"]}

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

@@ -0,0 +1,58 @@
+import { PgTableWithColumns } from 'drizzle-orm/pg-core';
+
+/**
+ * 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)
+ */
+
+/**
+ * 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).
+ */
+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`. */
+    refTable: PgTableWithColumns<any> | 'self';
+    /** true = throw on unresolved (junction); falsy = opportunistic null (entity). */
+    strict?: boolean;
+}
+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;
+}
+
+export type { SyncFkResolver, SyncUpsertConfig };

package/dist/runtime/base-classes/sync-upsert-config.js

@@ -0,0 +1 @@
+//# sourceMappingURL=sync-upsert-config.js.map

package/dist/runtime/base-classes/sync-upsert-config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

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

@@ -1,10 +1,16 @@
+import { DrizzleTx } from '../types/drizzle.js';
 import { BaseRepository } from './base-repository.js';
+import { SyncUpsertConfig } from './sync-upsert-config.js';
+import 'drizzle-orm/node-postgres';
 import 'drizzle-orm/pg-core';
 import 'drizzle-orm';
-import '../types/drizzle.js';
-import 'drizzle-orm/node-postgres';
 
-declare abstract class SyncedEntityRepository<TEntity> extends BaseRepository<TEntity> {
+declare 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;
     /**
      * Find a single entity by its external CRM identifier.
      */
@@ -18,10 +24,66 @@ declare abstract class SyncedEntityRepository<TEntity> extends BaseRepository<TE
      */
     findAllByUserId(userId: string): Promise<TEntity[]>;
     /**
-     * Sync upsert — bulk insert-or-update from external CRM data.
-     * Concrete repositories must implement with the appropriate conflict target.
+     * 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
+     */
+    syncUpsertOne(write: TSyncWrite, provider: string, tx?: DrizzleTx): Promise<TSyncProjection>;
+    /**
+     * 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.
+     */
+    findByExternalIdProjected(externalId: string, provider: string): Promise<TSyncProjection | 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`.
+     */
+    softDeleteByExternalId(externalId: string, provider: string, tx?: DrizzleTx): Promise<{
+        id: 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.
+     */
+    syncUpsert(inputs: Array<Partial<TEntity>>): Promise<TEntity[]>;
+    /**
+     * 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;
+    /**
+     * 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 writeCustomFields(_db: DrizzleTx, _entityId: string, _userId: string, _fields: Record<string, unknown>): Promise<void>;
+    /**
+     * 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.
      */
-    syncUpsert(_inputs: Array<Partial<TEntity>>): Promise<TEntity[]>;
+    private resolveFk;
     /**
      * Find entities visible to a user (ownership + sharing rules).
      * Concrete repositories must implement with visibility logic.