@clivly/core 0.8.0 → 0.9.0

package/dist/mappings-config-BWo4cRDF.d.cts

@@ -0,0 +1,168 @@
+import { ClivlyEntitiesConfig } from "./entity-config.cjs";
+import { z } from "zod";
+//#region src/projection.d.ts
+/**
+ * Projection-backed custom mappings — one custom object derived from a base
+ * table plus explicit joins.
+ *
+ * A projection is deliberately narrow: equality joins only, direct column
+ * bindings only, no expressions and no aggregation. Everything a user can
+ * express here compiles to a single read-only view whose `id` column is
+ * provably unique per row, which is what lets the sync engine consume it
+ * unchanged.
+ *
+ * Refs address tables symbolically: `"base"` for the base table, or a join's
+ * `key`. Raw table names are never accepted in a ref, so a projection can
+ * never reach a table it did not declare.
+ */
+/** The reserved ref name for the projection's base table. */
+declare const BASE_REF = "base";
+declare const projectionRefSchema: z.ZodObject<{
+  table: z.ZodString;
+  column: z.ZodString;
+}, z.core.$strict>;
+type ProjectionRef = z.infer<typeof projectionRefSchema>;
+declare const projectionJoinSchema: z.ZodObject<{
+  key: z.ZodString;
+  table: z.ZodString;
+  type: z.ZodEnum<{
+    inner: "inner";
+    left: "left";
+  }>;
+  on: z.ZodArray<z.ZodObject<{
+    left: z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>;
+    op: z.ZodLiteral<"eq">;
+    right: z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+type ProjectionJoin = z.infer<typeof projectionJoinSchema>;
+declare const projectionFieldBindingSchema: z.ZodObject<{
+  from: z.ZodObject<{
+    table: z.ZodString;
+    column: z.ZodString;
+  }, z.core.$strict>;
+}, z.core.$strict>;
+type ProjectionFieldBinding = z.infer<typeof projectionFieldBindingSchema>;
+declare const projectionIdentitySchema: z.ZodUnion<readonly [z.ZodObject<{
+  kind: z.ZodLiteral<"base_pk">;
+  column: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+  kind: z.ZodLiteral<"column">;
+  from: z.ZodObject<{
+    table: z.ZodString;
+    column: z.ZodString;
+  }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+  kind: z.ZodLiteral<"composite">;
+  parts: z.ZodArray<z.ZodObject<{
+    table: z.ZodString;
+    column: z.ZodString;
+  }, z.core.$strict>>;
+}, z.core.$strict>]>;
+type ProjectionIdentity = z.infer<typeof projectionIdentitySchema>;
+declare const projectionSchema: z.ZodObject<{
+  version: z.ZodLiteral<1>;
+  kind: z.ZodLiteral<"projection">;
+  entityKey: z.ZodString;
+  baseTable: z.ZodString;
+  joins: z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    table: z.ZodString;
+    type: z.ZodEnum<{
+      inner: "inner";
+      left: "left";
+    }>;
+    on: z.ZodArray<z.ZodObject<{
+      left: z.ZodObject<{
+        table: z.ZodString;
+        column: z.ZodString;
+      }, z.core.$strict>;
+      op: z.ZodLiteral<"eq">;
+      right: z.ZodObject<{
+        table: z.ZodString;
+        column: z.ZodString;
+      }, z.core.$strict>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>>;
+  fieldBindings: z.ZodRecord<z.ZodString, z.ZodObject<{
+    from: z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>;
+  }, z.core.$strict>>;
+  identity: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"base_pk">;
+    column: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"column">;
+    from: z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>;
+  }, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"composite">;
+    parts: z.ZodArray<z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>>;
+  }, z.core.$strict>]>;
+}, z.core.$strict>;
+type ProjectionMapping = z.infer<typeof projectionSchema>;
+/**
+ * Every column ref an identity depends on. `basePkColumn` is the base table's
+ * discovered PK, used only when a `base_pk` identity omits an explicit column.
+ */
+declare function identityRefs(identity: ProjectionIdentity, basePkColumn: string): ProjectionRef[];
+//#endregion
+//#region src/mappings-config.d.ts
+/**
+ * Mappings → Entity Config bridge.
+ *
+ * `crm_entity_mappings` rows are the single source of truth for how a host
+ * schema maps onto Clivly's CRM concepts. This module compiles those rows into
+ * a `ClivlyEntitiesConfig` — the contract the view compiler and sync engine
+ * consume — so the persisted mapping and the runtime pipeline never diverge.
+ *
+ * The row model has no explicit entity-key column (it's keyed by
+ * `sourceTable + targetConcept + role`), but the config's `relationships`
+ * reference other entities *by key*. This builder therefore derives a stable
+ * key per row and resolves each relationship's `entity` reference through the
+ * same derivation — so a relationship stored as `entity: "<relatedTable>"`
+ * (the shape `mappings.suggest` produces) resolves to the right entity.
+ */
+/**
+ * A persisted `crm_entity_mappings` row, narrowed to the columns the builder
+ * reads. Structurally compatible with the Drizzle row (jsonb columns typed
+ * loosely) so the API layer can pass `db.select()` results straight in.
+ */
+interface EntityMappingRow {
+  fieldMap: Record<string, string>;
+  filter?: Record<string, unknown> | null;
+  /**
+   * Advanced mapping: a base table plus explicit joins. When set, this — not
+   * `fieldMap` — is the authored source of truth, and `sourceTable` merely
+   * mirrors `projection.baseTable`.
+   */
+  projection?: ProjectionMapping | null;
+  relationships?: Record<string, unknown> | null;
+  role?: string | null;
+  sourceTable: string;
+  status?: string | null;
+  targetConcept: string;
+  targetObjectTypeId?: string | null;
+}
+/**
+ * Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`
+ * rows with at least one mapped field are included; disabled/suggested rows and
+ * unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
+ * eligible — a no-op the view compiler and sync engine both tolerate.
+ */
+declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
+//#endregion
+export { ProjectionIdentity as a, ProjectionRef as c, ProjectionFieldBinding as i, identityRefs as l, mappingsToEntitiesConfig as n, ProjectionJoin as o, BASE_REF as r, ProjectionMapping as s, EntityMappingRow as t, projectionSchema as u };

package/dist/mappings-config.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config.cjs");
+const require_entity_config = require("./entity-config-PoOGzvpN.cjs");
 //#region src/mappings-config.ts
 const RESERVED_FIELD = "id";
 /**
@@ -22,7 +22,9 @@ function canonicalFields(concept, fieldMap) {
 const DEFAULT_ROLE = "primary";
 const ACTIVE_STATUS = "active";
 function isEligible(row) {
-	return (row.status ?? ACTIVE_STATUS) === ACTIVE_STATUS && Object.keys(row.fieldMap ?? {}).length > 0;
+	if ((row.status ?? ACTIVE_STATUS) !== ACTIVE_STATUS) return false;
+	if (row.projection) return Object.keys(row.projection.fieldBindings ?? {}).length > 0;
+	return Object.keys(row.fieldMap ?? {}).length > 0;
 }
 /**
 * Preferred key for a row: the bare source table when it backs a single entity,
@@ -46,13 +48,28 @@ function uniquify(base, used) {
 	used.add(key);
 	return key;
 }
+/**
+* A projection's `fields` map, derived mechanically from its bindings.
+*
+* `ClivlyEntityConfig.fields` is required and read by existing consumers, so a
+* projection entity must populate it. The values are ref *tokens*
+* (`"base.full_name"`), never host column names — the compiler reads
+* `projection.fieldBindings`, and `validateEntitiesConfig` skips the legacy
+* column check for projection entities precisely because of this.
+*/
+function projectionFields(projection) {
+	const fields = {};
+	for (const [field, binding] of Object.entries(projection.fieldBindings)) fields[field] = `${binding.from.table}.${binding.from.column}`;
+	return fields;
+}
 function buildEntity(row, refIndex) {
 	const entity = {
 		concept: row.targetConcept,
-		source: row.sourceTable,
+		source: row.projection?.baseTable ?? row.sourceTable,
 		role: row.role ?? DEFAULT_ROLE,
-		fields: canonicalFields(row.targetConcept, row.fieldMap)
+		fields: row.projection ? projectionFields(row.projection) : canonicalFields(row.targetConcept, row.fieldMap)
 	};
+	if (row.projection) entity.projection = row.projection;
 	if (row.targetConcept === "custom" && row.targetObjectTypeId) entity.targetObjectTypeId = row.targetObjectTypeId;
 	if (row.filter && Object.keys(row.filter).length > 0) entity.filter = row.filter;
 	if (row.relationships && Object.keys(row.relationships).length > 0) {
@@ -77,11 +94,16 @@ function buildEntity(row, refIndex) {
 function mappingsToEntitiesConfig(rows) {
 	const eligible = rows.filter(isEligible);
 	const tableCounts = /* @__PURE__ */ new Map();
-	for (const row of eligible) tableCounts.set(row.sourceTable, (tableCounts.get(row.sourceTable) ?? 0) + 1);
+	for (const row of eligible) {
+		if (row.projection) continue;
+		tableCounts.set(row.sourceTable, (tableCounts.get(row.sourceTable) ?? 0) + 1);
+	}
 	const used = /* @__PURE__ */ new Set();
 	const tableAnchor = /* @__PURE__ */ new Map();
 	const assigned = [];
-	for (const row of eligible) {
+	const legacyRows = eligible.filter((row) => !row.projection);
+	const projectionRows = eligible.filter((row) => row.projection);
+	for (const row of legacyRows) {
 		const key = uniquify(preferredKey(row, tableCounts), used);
 		assigned.push({
 			row,
@@ -89,6 +111,10 @@ function mappingsToEntitiesConfig(rows) {
 		});
 		if ((row.role ?? DEFAULT_ROLE) === DEFAULT_ROLE || !tableAnchor.has(row.sourceTable)) tableAnchor.set(row.sourceTable, key);
 	}
+	for (const row of projectionRows) assigned.push({
+		row,
+		key: uniquify(row.projection?.entityKey ?? row.sourceTable, used)
+	});
 	const refIndex = /* @__PURE__ */ new Map();
 	for (const { key } of assigned) refIndex.set(key, key);
 	for (const [table, key] of tableAnchor) if (!refIndex.has(table)) refIndex.set(table, key);

package/dist/mappings-config.d.cts

@@ -1,41 +1,2 @@
-import { ClivlyEntitiesConfig } from "./entity-config.cjs";
-//#region src/mappings-config.d.ts
-/**
- * Mappings → Entity Config bridge.
- *
- * `crm_entity_mappings` rows are the single source of truth for how a host
- * schema maps onto Clivly's CRM concepts. This module compiles those rows into
- * a `ClivlyEntitiesConfig` — the contract the view compiler and sync engine
- * consume — so the persisted mapping and the runtime pipeline never diverge.
- *
- * The row model has no explicit entity-key column (it's keyed by
- * `sourceTable + targetConcept + role`), but the config's `relationships`
- * reference other entities *by key*. This builder therefore derives a stable
- * key per row and resolves each relationship's `entity` reference through the
- * same derivation — so a relationship stored as `entity: "<relatedTable>"`
- * (the shape `mappings.suggest` produces) resolves to the right entity.
- */
-/**
- * A persisted `crm_entity_mappings` row, narrowed to the columns the builder
- * reads. Structurally compatible with the Drizzle row (jsonb columns typed
- * loosely) so the API layer can pass `db.select()` results straight in.
- */
-interface EntityMappingRow {
-  fieldMap: Record<string, string>;
-  filter?: Record<string, unknown> | null;
-  relationships?: Record<string, unknown> | null;
-  role?: string | null;
-  sourceTable: string;
-  status?: string | null;
-  targetConcept: string;
-  targetObjectTypeId?: string | null;
-}
-/**
- * Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`
- * rows with at least one mapped field are included; disabled/suggested rows and
- * unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
- * eligible — a no-op the view compiler and sync engine both tolerate.
- */
-declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
-//#endregion
+import { n as mappingsToEntitiesConfig, t as EntityMappingRow } from "./mappings-config-BWo4cRDF.cjs";
 export { EntityMappingRow, mappingsToEntitiesConfig };

package/dist/mappings-config.d.mts

@@ -1,41 +1,2 @@
-import { ClivlyEntitiesConfig } from "./entity-config.mjs";
-//#region src/mappings-config.d.ts
-/**
- * Mappings → Entity Config bridge.
- *
- * `crm_entity_mappings` rows are the single source of truth for how a host
- * schema maps onto Clivly's CRM concepts. This module compiles those rows into
- * a `ClivlyEntitiesConfig` — the contract the view compiler and sync engine
- * consume — so the persisted mapping and the runtime pipeline never diverge.
- *
- * The row model has no explicit entity-key column (it's keyed by
- * `sourceTable + targetConcept + role`), but the config's `relationships`
- * reference other entities *by key*. This builder therefore derives a stable
- * key per row and resolves each relationship's `entity` reference through the
- * same derivation — so a relationship stored as `entity: "<relatedTable>"`
- * (the shape `mappings.suggest` produces) resolves to the right entity.
- */
-/**
- * A persisted `crm_entity_mappings` row, narrowed to the columns the builder
- * reads. Structurally compatible with the Drizzle row (jsonb columns typed
- * loosely) so the API layer can pass `db.select()` results straight in.
- */
-interface EntityMappingRow {
-  fieldMap: Record<string, string>;
-  filter?: Record<string, unknown> | null;
-  relationships?: Record<string, unknown> | null;
-  role?: string | null;
-  sourceTable: string;
-  status?: string | null;
-  targetConcept: string;
-  targetObjectTypeId?: string | null;
-}
-/**
- * Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`
- * rows with at least one mapped field are included; disabled/suggested rows and
- * unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
- * eligible — a no-op the view compiler and sync engine both tolerate.
- */
-declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
-//#endregion
+import { n as mappingsToEntitiesConfig, t as EntityMappingRow } from "./mappings-config-B0W5bVZj.mjs";
 export { EntityMappingRow, mappingsToEntitiesConfig };

package/dist/mappings-config.mjs

@@ -1,4 +1,4 @@
-import { CANONICAL_FIELDS } from "./entity-config.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-Tb5bbKLj.mjs";
 //#region src/mappings-config.ts
 const RESERVED_FIELD = "id";
 /**
@@ -21,7 +21,9 @@ function canonicalFields(concept, fieldMap) {
 const DEFAULT_ROLE = "primary";
 const ACTIVE_STATUS = "active";
 function isEligible(row) {
-	return (row.status ?? ACTIVE_STATUS) === ACTIVE_STATUS && Object.keys(row.fieldMap ?? {}).length > 0;
+	if ((row.status ?? ACTIVE_STATUS) !== ACTIVE_STATUS) return false;
+	if (row.projection) return Object.keys(row.projection.fieldBindings ?? {}).length > 0;
+	return Object.keys(row.fieldMap ?? {}).length > 0;
 }
 /**
 * Preferred key for a row: the bare source table when it backs a single entity,
@@ -45,13 +47,28 @@ function uniquify(base, used) {
 	used.add(key);
 	return key;
 }
+/**
+* A projection's `fields` map, derived mechanically from its bindings.
+*
+* `ClivlyEntityConfig.fields` is required and read by existing consumers, so a
+* projection entity must populate it. The values are ref *tokens*
+* (`"base.full_name"`), never host column names — the compiler reads
+* `projection.fieldBindings`, and `validateEntitiesConfig` skips the legacy
+* column check for projection entities precisely because of this.
+*/
+function projectionFields(projection) {
+	const fields = {};
+	for (const [field, binding] of Object.entries(projection.fieldBindings)) fields[field] = `${binding.from.table}.${binding.from.column}`;
+	return fields;
+}
 function buildEntity(row, refIndex) {
 	const entity = {
 		concept: row.targetConcept,
-		source: row.sourceTable,
+		source: row.projection?.baseTable ?? row.sourceTable,
 		role: row.role ?? DEFAULT_ROLE,
-		fields: canonicalFields(row.targetConcept, row.fieldMap)
+		fields: row.projection ? projectionFields(row.projection) : canonicalFields(row.targetConcept, row.fieldMap)
 	};
+	if (row.projection) entity.projection = row.projection;
 	if (row.targetConcept === "custom" && row.targetObjectTypeId) entity.targetObjectTypeId = row.targetObjectTypeId;
 	if (row.filter && Object.keys(row.filter).length > 0) entity.filter = row.filter;
 	if (row.relationships && Object.keys(row.relationships).length > 0) {
@@ -76,11 +93,16 @@ function buildEntity(row, refIndex) {
 function mappingsToEntitiesConfig(rows) {
 	const eligible = rows.filter(isEligible);
 	const tableCounts = /* @__PURE__ */ new Map();
-	for (const row of eligible) tableCounts.set(row.sourceTable, (tableCounts.get(row.sourceTable) ?? 0) + 1);
+	for (const row of eligible) {
+		if (row.projection) continue;
+		tableCounts.set(row.sourceTable, (tableCounts.get(row.sourceTable) ?? 0) + 1);
+	}
 	const used = /* @__PURE__ */ new Set();
 	const tableAnchor = /* @__PURE__ */ new Map();
 	const assigned = [];
-	for (const row of eligible) {
+	const legacyRows = eligible.filter((row) => !row.projection);
+	const projectionRows = eligible.filter((row) => row.projection);
+	for (const row of legacyRows) {
 		const key = uniquify(preferredKey(row, tableCounts), used);
 		assigned.push({
 			row,
@@ -88,6 +110,10 @@ function mappingsToEntitiesConfig(rows) {
 		});
 		if ((row.role ?? DEFAULT_ROLE) === DEFAULT_ROLE || !tableAnchor.has(row.sourceTable)) tableAnchor.set(row.sourceTable, key);
 	}
+	for (const row of projectionRows) assigned.push({
+		row,
+		key: uniquify(row.projection?.entityKey ?? row.sourceTable, used)
+	});
 	const refIndex = /* @__PURE__ */ new Map();
 	for (const { key } of assigned) refIndex.set(key, key);
 	for (const [table, key] of tableAnchor) if (!refIndex.has(table)) refIndex.set(table, key);

package/dist/projection-BXBkh7qp.cjs

@@ -0,0 +1,98 @@
+let zod = require("zod");
+//#region src/projection.ts
+/**
+* Projection-backed custom mappings — one custom object derived from a base
+* table plus explicit joins.
+*
+* A projection is deliberately narrow: equality joins only, direct column
+* bindings only, no expressions and no aggregation. Everything a user can
+* express here compiles to a single read-only view whose `id` column is
+* provably unique per row, which is what lets the sync engine consume it
+* unchanged.
+*
+* Refs address tables symbolically: `"base"` for the base table, or a join's
+* `key`. Raw table names are never accepted in a ref, so a projection can
+* never reach a table it did not declare.
+*/
+/** The reserved ref name for the projection's base table. */
+const BASE_REF = "base";
+/** Entity keys become view names (`crm_src_<entityKey>`), so keep them slugs. */
+const PROJECTION_KEY_PATTERN = /^[a-z][a-z0-9_]*$/;
+const projectionRefSchema = zod.z.strictObject({
+	table: zod.z.string().min(1),
+	column: zod.z.string().min(1)
+});
+const projectionJoinConditionSchema = zod.z.strictObject({
+	left: projectionRefSchema,
+	op: zod.z.literal("eq"),
+	right: projectionRefSchema
+});
+const projectionJoinSchema = zod.z.strictObject({
+	/** SQL alias and ref target. Unique within the projection. */
+	key: zod.z.string().regex(PROJECTION_KEY_PATTERN),
+	table: zod.z.string().min(1),
+	type: zod.z.enum(["inner", "left"]),
+	on: zod.z.array(projectionJoinConditionSchema).min(1)
+});
+const projectionFieldBindingSchema = zod.z.strictObject({ from: projectionRefSchema });
+const projectionIdentitySchema = zod.z.union([
+	zod.z.strictObject({
+		kind: zod.z.literal("base_pk"),
+		/** Defaults to the discovered single-column PK of the base table. */
+		column: zod.z.string().min(1).optional()
+	}),
+	zod.z.strictObject({
+		kind: zod.z.literal("column"),
+		from: projectionRefSchema
+	}),
+	zod.z.strictObject({
+		kind: zod.z.literal("composite"),
+		parts: zod.z.array(projectionRefSchema).min(2)
+	})
+]);
+const projectionSchema = zod.z.strictObject({
+	version: zod.z.literal(1),
+	kind: zod.z.literal("projection"),
+	entityKey: zod.z.string().regex(PROJECTION_KEY_PATTERN),
+	baseTable: zod.z.string().min(1),
+	joins: zod.z.array(projectionJoinSchema),
+	fieldBindings: zod.z.record(zod.z.string(), projectionFieldBindingSchema).refine((b) => Object.keys(b).length > 0, { message: "at least one field must be bound" }),
+	identity: projectionIdentitySchema
+});
+/**
+* Every column ref an identity depends on. `basePkColumn` is the base table's
+* discovered PK, used only when a `base_pk` identity omits an explicit column.
+*/
+function identityRefs(identity, basePkColumn) {
+	if (identity.kind === "base_pk") return [{
+		table: BASE_REF,
+		column: identity.column ?? basePkColumn
+	}];
+	if (identity.kind === "column") return [identity.from];
+	return identity.parts;
+}
+//#endregion
+Object.defineProperty(exports, "BASE_REF", {
+	enumerable: true,
+	get: function() {
+		return BASE_REF;
+	}
+});
+Object.defineProperty(exports, "PROJECTION_KEY_PATTERN", {
+	enumerable: true,
+	get: function() {
+		return PROJECTION_KEY_PATTERN;
+	}
+});
+Object.defineProperty(exports, "identityRefs", {
+	enumerable: true,
+	get: function() {
+		return identityRefs;
+	}
+});
+Object.defineProperty(exports, "projectionSchema", {
+	enumerable: true,
+	get: function() {
+		return projectionSchema;
+	}
+});

package/dist/projection-C_EMRmZ8.mjs

@@ -0,0 +1,75 @@
+import { z } from "zod";
+//#region src/projection.ts
+/**
+* Projection-backed custom mappings — one custom object derived from a base
+* table plus explicit joins.
+*
+* A projection is deliberately narrow: equality joins only, direct column
+* bindings only, no expressions and no aggregation. Everything a user can
+* express here compiles to a single read-only view whose `id` column is
+* provably unique per row, which is what lets the sync engine consume it
+* unchanged.
+*
+* Refs address tables symbolically: `"base"` for the base table, or a join's
+* `key`. Raw table names are never accepted in a ref, so a projection can
+* never reach a table it did not declare.
+*/
+/** The reserved ref name for the projection's base table. */
+const BASE_REF = "base";
+/** Entity keys become view names (`crm_src_<entityKey>`), so keep them slugs. */
+const PROJECTION_KEY_PATTERN = /^[a-z][a-z0-9_]*$/;
+const projectionRefSchema = z.strictObject({
+	table: z.string().min(1),
+	column: z.string().min(1)
+});
+const projectionJoinConditionSchema = z.strictObject({
+	left: projectionRefSchema,
+	op: z.literal("eq"),
+	right: projectionRefSchema
+});
+const projectionJoinSchema = z.strictObject({
+	/** SQL alias and ref target. Unique within the projection. */
+	key: z.string().regex(PROJECTION_KEY_PATTERN),
+	table: z.string().min(1),
+	type: z.enum(["inner", "left"]),
+	on: z.array(projectionJoinConditionSchema).min(1)
+});
+const projectionFieldBindingSchema = z.strictObject({ from: projectionRefSchema });
+const projectionIdentitySchema = z.union([
+	z.strictObject({
+		kind: z.literal("base_pk"),
+		/** Defaults to the discovered single-column PK of the base table. */
+		column: z.string().min(1).optional()
+	}),
+	z.strictObject({
+		kind: z.literal("column"),
+		from: projectionRefSchema
+	}),
+	z.strictObject({
+		kind: z.literal("composite"),
+		parts: z.array(projectionRefSchema).min(2)
+	})
+]);
+const projectionSchema = z.strictObject({
+	version: z.literal(1),
+	kind: z.literal("projection"),
+	entityKey: z.string().regex(PROJECTION_KEY_PATTERN),
+	baseTable: z.string().min(1),
+	joins: z.array(projectionJoinSchema),
+	fieldBindings: z.record(z.string(), projectionFieldBindingSchema).refine((b) => Object.keys(b).length > 0, { message: "at least one field must be bound" }),
+	identity: projectionIdentitySchema
+});
+/**
+* Every column ref an identity depends on. `basePkColumn` is the base table's
+* discovered PK, used only when a `base_pk` identity omits an explicit column.
+*/
+function identityRefs(identity, basePkColumn) {
+	if (identity.kind === "base_pk") return [{
+		table: BASE_REF,
+		column: identity.column ?? basePkColumn
+	}];
+	if (identity.kind === "column") return [identity.from];
+	return identity.parts;
+}
+//#endregion
+export { projectionSchema as i, PROJECTION_KEY_PATTERN as n, identityRefs as r, BASE_REF as t };

package/dist/sync-engine.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_view_compiler = require("./view-compiler.cjs");
+const require_view_compiler = require("./view-compiler-BwZ9UgLp.cjs");
 //#region src/sync-engine.ts
 /**
 * Diff a view's rows against the current mirror population for one entity.
@@ -171,10 +171,17 @@ function isEmptyValue(value) {
 */
 function computeSampleWarnings(rows, requiredFields, sourceTable) {
 	if (rows.length === 0) return [{ message: `no rows found in ${sourceTable}` }];
+	const seenRefs = /* @__PURE__ */ new Set();
+	const duplicateRefs = /* @__PURE__ */ new Set();
+	for (const row of rows) {
+		if (seenRefs.has(row.sourceRef)) duplicateRefs.add(row.sourceRef);
+		seenRefs.add(row.sourceRef);
+	}
+	const identityWarnings = duplicateRefs.size > 0 ? [{ message: `duplicate id in ${duplicateRefs.size} of ${rows.length} sampled rows — identity is not unique, so sync would collapse these into one record` }] : [];
 	const required = new Set(requiredFields);
 	const fields = new Set(requiredFields);
 	for (const row of rows) for (const key of Object.keys(row.fields)) fields.add(key);
-	const warnings = [];
+	const warnings = [...identityWarnings];
 	for (const field of [...fields].sort()) {
 		const emptyCount = rows.filter((row) => isEmptyValue(row.fields[field])).length;
 		if (required.has(field)) {

package/dist/sync-engine.mjs

@@ -1,4 +1,4 @@
-import { compileEntityViews } from "./view-compiler.mjs";
+import { r as compileEntityViews } from "./view-compiler-BKrBA_II.mjs";
 //#region src/sync-engine.ts
 /**
 * Diff a view's rows against the current mirror population for one entity.
@@ -170,10 +170,17 @@ function isEmptyValue(value) {
 */
 function computeSampleWarnings(rows, requiredFields, sourceTable) {
 	if (rows.length === 0) return [{ message: `no rows found in ${sourceTable}` }];
+	const seenRefs = /* @__PURE__ */ new Set();
+	const duplicateRefs = /* @__PURE__ */ new Set();
+	for (const row of rows) {
+		if (seenRefs.has(row.sourceRef)) duplicateRefs.add(row.sourceRef);
+		seenRefs.add(row.sourceRef);
+	}
+	const identityWarnings = duplicateRefs.size > 0 ? [{ message: `duplicate id in ${duplicateRefs.size} of ${rows.length} sampled rows — identity is not unique, so sync would collapse these into one record` }] : [];
 	const required = new Set(requiredFields);
 	const fields = new Set(requiredFields);
 	for (const row of rows) for (const key of Object.keys(row.fields)) fields.add(key);
-	const warnings = [];
+	const warnings = [...identityWarnings];
 	for (const field of [...fields].sort()) {
 		const emptyCount = rows.filter((row) => isEmptyValue(row.fields[field])).length;
 		if (required.has(field)) {