@clivly/core 0.8.0 → 0.9.1

package/dist/integration-state.mjs

@@ -0,0 +1,232 @@
+//#region src/integration-state.ts
+const INTEGRATION_STEPS = [
+	"credential",
+	"application",
+	"schema",
+	"mapping",
+	"trigger",
+	"sync",
+	"widget"
+];
+const INTEGRATION_STEP_LABELS = {
+	credential: "Secure credential",
+	application: "Application connected",
+	schema: "Schema discovered",
+	mapping: "Entities mapped",
+	trigger: "Clivly can start a sync",
+	sync: "First sync observed",
+	widget: "Chat widget installed"
+};
+/** Each step's prerequisites. Ordering is enforced by a test, not convention. */
+const STEP_PREREQUISITES = {
+	credential: [],
+	application: ["credential"],
+	schema: ["application"],
+	mapping: ["schema"],
+	trigger: ["application"],
+	sync: ["mapping", "trigger"],
+	widget: ["application"]
+};
+function stepIndex(id) {
+	return INTEGRATION_STEPS.indexOf(id);
+}
+/** A heartbeat older than this means the app stopped checking in. */
+const HEARTBEAT_STALE_MS = 600 * 1e3;
+function formatAge(ms) {
+	if (ms < 6e4) return `${Math.max(1, Math.round(ms / 1e3))}s ago`;
+	if (ms < 36e5) return `${Math.round(ms / 6e4)}m ago`;
+	return `${Math.round(ms / 36e5)}h ago`;
+}
+function heartbeatAge(facts) {
+	return facts.lastHeartbeatAt === null ? null : facts.now - facts.lastHeartbeatAt;
+}
+/** Is the raw condition behind each step met, ignoring prerequisites? */
+function isSatisfied(id, facts) {
+	const age = heartbeatAge(facts);
+	switch (id) {
+		case "credential": return facts.hasCredential;
+		case "application": return age !== null && age < HEARTBEAT_STALE_MS;
+		case "schema": return facts.discoveredTableCount > 0;
+		case "mapping": return facts.mappedEntityCount > 0;
+		case "trigger": return facts.triggerConfigured;
+		case "sync": return facts.lastRun?.ok === true;
+		default: return facts.widgetInstalled;
+	}
+}
+function evidenceFor(id, facts) {
+	const age = heartbeatAge(facts);
+	if (id === "application" && age !== null) return `heartbeat ${formatAge(age)}`;
+	if (id === "schema" && facts.discoveredTableCount > 0) return `found ${facts.discoveredTableCount} tables`;
+	if (id === "mapping" && facts.mappedEntityCount > 0) return `${facts.mappedEntityCount} entity mapped`;
+	if (id === "trigger" && facts.triggerConfigured) return "trigger URL and secret set";
+	if (id === "sync" && facts.lastRun) return `last run ${formatAge(facts.now - facts.lastRun.at)}`;
+	return null;
+}
+function problemFor(id, facts) {
+	if (id === "sync" && facts.lastRun && !facts.lastRun.ok) return {
+		code: "sync_failed",
+		message: facts.lastRun.message ?? "The last sync run failed.",
+		fix: "Open the run log to see the host response."
+	};
+	if (id === "application") {
+		const age = heartbeatAge(facts);
+		if (age !== null && age >= HEARTBEAT_STALE_MS) return {
+			code: "heartbeat_stale",
+			message: `Your app stopped checking in ${formatAge(age)}.`,
+			fix: "Start your app, then run `npx clivly status`."
+		};
+		if (age === null && facts.everConnected) return {
+			code: "heartbeat_stale",
+			message: "Your application stopped checking in.",
+			fix: "Start your app, then run `npx clivly status`."
+		};
+	}
+	return null;
+}
+/**
+* Walk the ladder once. A step is `blocked` when an earlier step it needs has
+* not been satisfied — a prerequisite statement, not a verdict about this step
+* — and only the first unsatisfied step is `active`, so exactly one root cause
+* ever surfaces.
+*/
+function resolveSteps(facts) {
+	const satisfied = /* @__PURE__ */ new Set();
+	const steps = [];
+	let activeTaken = false;
+	for (const id of INTEGRATION_STEPS) {
+		const unmet = STEP_PREREQUISITES[id].find((need) => !satisfied.has(need));
+		const label = INTEGRATION_STEP_LABELS[id];
+		if (isSatisfied(id, facts)) {
+			satisfied.add(id);
+			steps.push({
+				id,
+				label,
+				state: "done",
+				blockedBy: null,
+				evidence: evidenceFor(id, facts),
+				problem: null
+			});
+			continue;
+		}
+		if (unmet !== void 0) {
+			steps.push({
+				id,
+				label,
+				state: "blocked",
+				blockedBy: unmet,
+				evidence: null,
+				problem: null
+			});
+			continue;
+		}
+		const problem = problemFor(id, facts);
+		let state = "active";
+		if (problem) state = "failed";
+		else if (id === "widget") state = "skipped";
+		const claimsAttention = state === "active" || state === "failed";
+		steps.push({
+			id,
+			label,
+			state: activeTaken && state === "active" ? "blocked" : state,
+			blockedBy: null,
+			evidence: evidenceFor(id, facts),
+			problem: activeTaken ? null : problem
+		});
+		if (claimsAttention) activeTaken = true;
+	}
+	return steps;
+}
+const STEP_STATUS_WHEN_ACTIVE = {
+	credential: "not_configured",
+	application: "awaiting_connection",
+	schema: "connected",
+	mapping: "mapping_required",
+	trigger: "trigger_required",
+	sync: "ready_to_sync",
+	widget: "healthy"
+};
+/**
+* Collapse the ladder to the single status the surfaces switch on. Live
+* conditions — a run in flight, a failure, a heartbeat gone quiet — win over
+* ladder position, because they describe the integration as it is now rather
+* than how far setup once got.
+*/
+function deriveStatus(steps, facts) {
+	if (facts.syncInFlight) return "syncing";
+	if (steps.find((step) => step.id === "application")?.problem?.code === "heartbeat_stale") return "disconnected";
+	if (steps.some((step) => step.state === "failed")) return "error";
+	const blocking = steps.find((step) => step.state === "active" || step.state === "blocked");
+	if (blocking) return STEP_STATUS_WHEN_ACTIVE[blocking.id];
+	return facts.warnings.length > 0 ? "warning" : "healthy";
+}
+/**
+* The command that installs Clivly into a host app. Exported because the connect
+* dialog prints it too, and it must be the same string as the one the ladder
+* recommends — that pairing is what C-05 broke.
+*/
+const INSTALL_COMMAND = "npx clivly init";
+const NEXT_BY_STEP = {
+	credential: {
+		label: "Create a credential",
+		command: null,
+		envFile: null
+	},
+	application: {
+		label: "Install Clivly in your app",
+		command: INSTALL_COMMAND,
+		envFile: ".env.local"
+	},
+	schema: {
+		label: "Check what the SDK reported",
+		command: "npx clivly status",
+		envFile: null
+	},
+	mapping: {
+		label: "Choose the table holding your people",
+		command: null,
+		envFile: null
+	},
+	trigger: {
+		label: "Let Clivly start a sync",
+		command: null,
+		envFile: null
+	},
+	sync: {
+		label: "Run the first sync",
+		command: "npx clivly sync",
+		envFile: null
+	},
+	widget: {
+		label: "Install the chat widget",
+		command: null,
+		envFile: null
+	}
+};
+/**
+* THE one producer of `next.command`. Six surfaces previously each invented
+* their own "run this next" string, and one of them named a read-only command
+* as the fix for a write problem (C-05). If you need a command for the
+* next-action slot, call this — do not write another one.
+*/
+function nextAction(steps, status) {
+	if (status === "healthy" || status === "syncing") return null;
+	const blocking = steps.find((step) => step.state === "failed") ?? steps.find((step) => step.state === "active");
+	if (!blocking) return null;
+	if (blocking.problem?.code === "heartbeat_stale") return {
+		label: "Reconnect your app",
+		command: "npx clivly status",
+		envFile: null
+	};
+	return NEXT_BY_STEP[blocking.id];
+}
+function computeIntegrationState(facts) {
+	const steps = resolveSteps(facts);
+	const status = deriveStatus(steps, facts);
+	return {
+		status,
+		steps,
+		next: nextAction(steps, status)
+	};
+}
+//#endregion
+export { INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, STEP_PREREQUISITES, computeIntegrationState, deriveStatus, formatAge, nextAction, resolveSteps, stepIndex };

package/dist/mapping-form.d.cts

@@ -1,4 +1,4 @@
-import { FilterExpr, RelationshipVia, RelationshipsMap } from "./entity-config.cjs";
+import { b as RelationshipsMap, m as FilterExpr, y as RelationshipVia } from "./entity-config-CLxI8dVb.cjs";
 //#region src/mapping-form.d.ts
 /**
  * A relationship the mapping UI can offer or has configured, in the shape the

package/dist/mapping-form.d.mts

@@ -1,4 +1,4 @@
-import { FilterExpr, RelationshipVia, RelationshipsMap } from "./entity-config.mjs";
+import { b as RelationshipsMap, m as FilterExpr, y as RelationshipVia } from "./entity-config-CLxI8dVb.mjs";
 //#region src/mapping-form.d.ts
 /**
  * A relationship the mapping UI can offer or has configured, in the shape the

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-Dh8aEcgj.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,4 +1,4 @@
-import { ClivlyEntitiesConfig } from "./entity-config.cjs";
+import { M as ProjectionMapping, a as ClivlyEntitiesConfig } from "./entity-config-CLxI8dVb.cjs";
 //#region src/mappings-config.d.ts
 /**
  * Mappings → Entity Config bridge.
@@ -23,6 +23,12 @@ import { ClivlyEntitiesConfig } from "./entity-config.cjs";
 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;

package/dist/mappings-config.d.mts

@@ -1,4 +1,4 @@
-import { ClivlyEntitiesConfig } from "./entity-config.mjs";
+import { M as ProjectionMapping, a as ClivlyEntitiesConfig } from "./entity-config-CLxI8dVb.mjs";
 //#region src/mappings-config.d.ts
 /**
  * Mappings → Entity Config bridge.
@@ -23,6 +23,12 @@ import { ClivlyEntitiesConfig } from "./entity-config.mjs";
 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;

package/dist/mappings-config.mjs

@@ -1,4 +1,4 @@
-import { CANONICAL_FIELDS } from "./entity-config.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-8Fgr6IOH.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-BpNI8Ttw.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.d.cts

@@ -1,4 +1,4 @@
-import { ClivlyEntitiesConfig } from "./entity-config.cjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-CLxI8dVb.cjs";
 import { CompileOptions, CompiledView } from "./view-compiler.cjs";
 //#region src/sync-engine.d.ts
 /**

package/dist/sync-engine.d.mts

@@ -1,4 +1,4 @@
-import { ClivlyEntitiesConfig } from "./entity-config.mjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-CLxI8dVb.mjs";
 import { CompileOptions, CompiledView } from "./view-compiler.mjs";
 //#region src/sync-engine.d.ts
 /**

package/dist/sync-engine.mjs

@@ -1,4 +1,4 @@
-import { compileEntityViews } from "./view-compiler.mjs";
+import { r as compileEntityViews } from "./view-compiler-CcqsGxv4.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)) {