@clivly/core 0.8.0 → 0.9.1

package/dist/entity-config-Dh8aEcgj.cjs

@@ -0,0 +1,779 @@
+const require_projection = require("./projection-BXBkh7qp.cjs");
+let zod = require("zod");
+//#region src/schema-meta.ts
+/**
+* Accessors over a discovered table's schema-v2 metadata.
+*
+* Every helper treats *absent* metadata as **unknown**, never as a negative
+* fact. `coversUniqueKey` returning false on a v1 payload is what makes
+* projection validation fail closed: we cannot prove a join is many-to-one, so
+* we refuse to compile it rather than guess.
+*/
+function columnMetaFor(table, column) {
+	return table.columnsMeta?.find((c) => c.name === column);
+}
+/**
+* Every primary-key column. More than one entry means a composite PK, which is
+* why `base_pk` identity is rejected for such tables.
+*/
+function primaryKeyColumns(table) {
+	return (table.columnsMeta ?? []).filter((c) => c.isPrimaryKey).map((c) => c.name);
+}
+/**
+* Do `columns` contain every column of at least one unique key on `table`?
+*
+* This is the fan-out test. A join whose ON columns cover a unique key of the
+* joined table matches at most one row per base row; one that does not can
+* match many.
+*/
+function coversUniqueKey(table, columns) {
+	const present = new Set(columns);
+	return (table.uniqueConstraints ?? []).some((key) => key.length > 0 && key.every((column) => present.has(column)));
+}
+/** Is this table's payload rich enough to validate a projection against? */
+function hasRichMeta(table) {
+	return Boolean(table.columnsMeta && table.uniqueConstraints);
+}
+//#endregion
+//#region src/projection-cardinality.ts
+/**
+* Cardinality analysis for projection joins.
+*
+* A join matches at most one row per base row exactly when the columns it
+* constrains *on the joined table* cover a whole unique key of that table.
+* Anything else can match many rows — "fan-out" — which multiplies the view's
+* output and is only safe if identity is unique per output row.
+*
+* Unknown metadata is treated as fan-out. That is deliberate: we can never
+* prove safety from an absent constraint list, and guessing wrong silently
+* corrupts the mirror.
+*/
+/** The join's own columns constrained by its ON conditions. */
+function joinSideColumns(join) {
+	const columns = [];
+	for (const condition of join.on) for (const ref of [condition.left, condition.right]) if (ref.table === join.key) columns.push(ref.column);
+	return columns;
+}
+function joinFansOut(join, joinTable) {
+	return !coversUniqueKey(joinTable, joinSideColumns(join));
+}
+/** Every join in the projection that can multiply rows. */
+function fanOutJoins(projection, tablesByName) {
+	return projection.joins.filter((join) => {
+		const table = tablesByName.get(join.table);
+		return table ? joinFansOut(join, table) : true;
+	});
+}
+//#endregion
+//#region src/projection-validate.ts
+/**
+* Semantic validation for a projection mapping, against the host's discovered
+* schema.
+*
+* The organising principle is **fail closed**. Every check that cannot be
+* proven safe from the discovered metadata is an error, not a warning: a
+* projection whose `id` column is not unique per output row silently collapses
+* or duplicates mirror rows at sync time, which is the worst failure mode in
+* the system and is invisible until data is already wrong.
+*/
+const RESERVED_FIELD = "id";
+const TEXT_TYPES = /* @__PURE__ */ new Set([
+	"text",
+	"varchar",
+	"char",
+	"citext",
+	"json",
+	"jsonb"
+]);
+function isTextType(type) {
+	if (!type) return true;
+	const base = type.toLowerCase().split("(")[0]?.trim() ?? "";
+	return TEXT_TYPES.has(base);
+}
+function buildResolver(projection, schema) {
+	const tablesByName = new Map(schema.map((t) => [t.name, t]));
+	const refToTable = /* @__PURE__ */ new Map([[require_projection.BASE_REF, projection.baseTable]]);
+	for (const join of projection.joins) refToTable.set(join.key, join.table);
+	return {
+		tablesByName,
+		tableFor(refTable) {
+			const name = refToTable.get(refTable);
+			return name ? tablesByName.get(name) : void 0;
+		}
+	};
+}
+function checkRef(errors, resolver, path, ref) {
+	const table = resolver.tableFor(ref.table);
+	if (!table) {
+		errors.push({
+			path,
+			message: `unknown ref table "${ref.table}"`
+		});
+		return;
+	}
+	if (!table.columns.includes(ref.column)) errors.push({
+		path,
+		message: `column "${ref.column}" does not exist on "${table.name}"`
+	});
+}
+function checkTablesExist(errors, projection, resolver, base) {
+	let ok = true;
+	const names = [{
+		name: projection.baseTable,
+		path: `${base}.projection.baseTable`
+	}, ...projection.joins.map((j, i) => ({
+		name: j.table,
+		path: `${base}.projection.joins.${i}.table`
+	}))];
+	for (const { name, path } of names) {
+		const table = resolver.tablesByName.get(name);
+		if (!table) {
+			errors.push({
+				path,
+				message: `table "${name}" is not in the discovered schema`
+			});
+			ok = false;
+			continue;
+		}
+		if (!hasRichMeta(table)) {
+			errors.push({
+				path,
+				message: `table "${name}" has no key/column metadata — upgrade @clivly/sdk and re-run discovery before using a projection`
+			});
+			ok = false;
+		}
+	}
+	return ok;
+}
+function checkStructure(errors, projection, base) {
+	const seen = /* @__PURE__ */ new Set();
+	projection.joins.forEach((join, index) => {
+		const path = `${base}.projection.joins.${index}.key`;
+		if (join.key === "base") errors.push({
+			path,
+			message: `join key "${require_projection.BASE_REF}" is reserved`
+		});
+		if (seen.has(join.key)) errors.push({
+			path,
+			message: `duplicate join key "${join.key}"`
+		});
+		seen.add(join.key);
+	});
+	for (const field of Object.keys(projection.fieldBindings)) if (field === RESERVED_FIELD) errors.push({
+		path: `${base}.projection.fieldBindings.${field}`,
+		message: `"${RESERVED_FIELD}" is reserved — the view always projects identity as "id"`
+	});
+	const declared = /* @__PURE__ */ new Set([require_projection.BASE_REF]);
+	for (const [index, join] of projection.joins.entries()) {
+		declared.add(join.key);
+		for (const condition of join.on) for (const ref of [condition.left, condition.right]) if (!declared.has(ref.table)) errors.push({
+			path: `${base}.projection.joins.${index}.on`,
+			message: `join "${join.key}" references "${ref.table}", which is declared later`
+		});
+	}
+}
+function checkRefs(errors, projection, resolver, base, basePk) {
+	projection.joins.forEach((join, index) => {
+		join.on.forEach((condition, conditionIndex) => {
+			const path = `${base}.projection.joins.${index}.on.${conditionIndex}`;
+			checkRef(errors, resolver, path, condition.left);
+			checkRef(errors, resolver, path, condition.right);
+		});
+	});
+	for (const [field, binding] of Object.entries(projection.fieldBindings)) checkRef(errors, resolver, `${base}.projection.fieldBindings.${field}`, binding.from);
+	for (const ref of require_projection.identityRefs(projection.identity, basePk)) checkRef(errors, resolver, `${base}.projection.identity`, ref);
+}
+function checkIdentitySafety(errors, projection, resolver, base, baseTable) {
+	const path = `${base}.projection.identity`;
+	const pk = primaryKeyColumns(baseTable);
+	if (projection.identity.kind === "base_pk" && !projection.identity.column) {
+		if (pk.length === 0) {
+			errors.push({
+				path,
+				message: `"${baseTable.name}" has no discovered primary key — name an identity column explicitly`
+			});
+			return;
+		}
+		if (pk.length > 1) {
+			errors.push({
+				path,
+				message: `"${baseTable.name}" has a composite primary key (${pk.join(", ")}) — use a composite identity instead`
+			});
+			return;
+		}
+	}
+	if (projection.identity.kind !== "composite") return;
+	for (const part of projection.identity.parts) {
+		const table = resolver.tableFor(part.table);
+		const meta = table && columnMetaFor(table, part.column);
+		if (!meta) continue;
+		if (meta.nullable !== false) errors.push({
+			path,
+			message: `composite identity part "${part.table}.${part.column}" must be NOT NULL — CONCAT_WS skips nulls, so distinct rows would share an id`
+		});
+		if (isTextType(meta.type)) errors.push({
+			path,
+			message: `composite identity part "${part.table}.${part.column}" is text-typed — a value containing "::" would make two distinct rows share an id`
+		});
+	}
+}
+function checkFanOut(errors, projection, resolver, base, basePk) {
+	const fanning = fanOutJoins(projection, resolver.tablesByName);
+	if (fanning.length === 0) return;
+	if (fanning.length > 1) {
+		errors.push({
+			path: `${base}.projection.joins`,
+			message: `at most one fan-out join is allowed; ${fanning.map((j) => `"${j.key}"`).join(", ")} all match multiple rows per base row`
+		});
+		return;
+	}
+	const [join] = fanning;
+	if (!join) return;
+	const joinTable = resolver.tablesByName.get(join.table);
+	if (!joinTable) return;
+	const identityPath = `${base}.projection.identity`;
+	if (projection.identity.kind === "base_pk") {
+		errors.push({
+			path: identityPath,
+			message: `join "${join.key}" fans out, so base_pk identity would give every fanned-out row the same id`
+		});
+		return;
+	}
+	if (!coversUniqueKey(joinTable, require_projection.identityRefs(projection.identity, basePk).filter((ref) => ref.table === join.key).map((ref) => ref.column))) errors.push({
+		path: identityPath,
+		message: `identity does not uniquely identify a row of "${joinTable.name}", which fans out — include a unique key of that table`
+	});
+}
+/**
+* Validate a projection against the discovered schema. Returns every error
+* found (not just the first) so a builder UI can show them all at once.
+*/
+function validateProjection(projection, schema, base) {
+	const errors = [];
+	const resolver = buildResolver(projection, schema);
+	checkStructure(errors, projection, base);
+	if (!checkTablesExist(errors, projection, resolver, base)) return errors;
+	const baseTable = resolver.tablesByName.get(projection.baseTable);
+	if (!baseTable) return errors;
+	const basePk = primaryKeyColumns(baseTable)[0] ?? "id";
+	checkRefs(errors, projection, resolver, base, basePk);
+	checkIdentitySafety(errors, projection, resolver, base, baseTable);
+	checkFanOut(errors, projection, resolver, base, basePk);
+	return errors;
+}
+//#endregion
+//#region src/entity-config.ts
+/**
+* Entity Config v2 — the declarative contract that turns Clivly's "schema-aware"
+* promise into a real capability.
+*
+* A CRM entity is no longer a flat table name. It is a *derived entity*: a
+* filtered slice of a host table (`source` + `filter`), a column allowlist
+* (`fields` + `readOnly`), and declared `relationships` to other entities. The
+* same host table can back several entities (e.g. `users` → owners + members)
+* distinguished by `role`.
+*
+* This module is the Phase 1 slice: types, schema, `defineClivlyConfig` (a
+* structural helper) and `validateEntitiesConfig` (semantic validation against
+* the host's discovered schema). It performs NO DB access and generates no SQL —
+* the view compiler (Phase 2) and sync engine (Phase 3) consume this contract.
+*/
+/** Canonical CRM concepts a host entity can map onto. */
+const CRM_CONCEPTS = [
+	"contact",
+	"company",
+	"deal",
+	"activity",
+	"conversation",
+	"note"
+];
+/**
+* The canonical `fields` keys the mirror actually persists, per concept — the
+* crm_* columns the sync store writes. An entity's `fields` map keys must be one
+* of these: a non-canonical key (e.g. `fullName` instead of `name`) validates
+* structurally but has no destination column, so the store silently writes an
+* empty value. `validateEntitiesConfig` flags those.
+*
+* This is the single source of truth — the Drizzle store imports it, so the
+* two can't drift (the drift is what made the silent-data-loss trap possible).
+* Concepts absent here aren't materialized yet, so their field keys are
+* unconstrained.
+*/
+const CANONICAL_FIELDS = {
+	contact: [
+		"name",
+		"email",
+		"title",
+		"status"
+	],
+	company: [
+		"name",
+		"domain",
+		"industry",
+		"size"
+	],
+	deal: [
+		"name",
+		"value",
+		"stage"
+	]
+};
+/**
+* The concepts the mapping→sync pipeline can actually materialize into `crm_*`
+* tables. These are exactly the CANONICAL_FIELDS keys — the Drizzle sync store's
+* `persist()` throws for any other concept, so offering one (in the mapping
+* editor, in suggestions, or via the upsert API) is a broken affordance.
+*
+* The broader CRM_CONCEPTS set still validates structurally, so previously
+* stored rows for not-yet-materialized concepts keep rendering. When a concept
+* gains a sync-store path, add its canonical fields above and it joins this set
+* automatically (guarded by the MATERIALIZING_CONCEPTS drift test).
+*/
+const MATERIALIZING_CONCEPTS = [
+	"contact",
+	"company",
+	"deal"
+];
+/**
+* The org-defined custom-object target. Deliberately NOT a member of
+* CRM_CONCEPTS / CANONICAL_FIELDS / MATERIALIZING_CONCEPTS — a custom object has
+* no fixed canonical columns; its mapping's fieldMap keys ARE its properties.
+* Handled as an explicit branch wherever concepts are switched on, so the
+* canonical-concept invariants (and their drift test) stay intact.
+*/
+const CUSTOM_CONCEPT = "custom";
+/**
+* Operator forms for a single column predicate. All predicates on an entity are
+* AND-ed together. `$raw` (see FilterExpr) is the escape hatch for anything the
+* operators can't express.
+*/
+const filterOperatorsSchema = zod.z.union([
+	zod.z.strictObject({ eq: zod.z.union([
+		zod.z.string(),
+		zod.z.number(),
+		zod.z.boolean()
+	]) }),
+	zod.z.strictObject({ ne: zod.z.union([
+		zod.z.string(),
+		zod.z.number(),
+		zod.z.boolean()
+	]) }),
+	zod.z.strictObject({ in: zod.z.array(zod.z.union([
+		zod.z.string(),
+		zod.z.number(),
+		zod.z.boolean()
+	])).min(1) }),
+	zod.z.strictObject({ notIn: zod.z.array(zod.z.union([
+		zod.z.string(),
+		zod.z.number(),
+		zod.z.boolean()
+	])).min(1) }),
+	zod.z.strictObject({ isNull: zod.z.literal(true) }),
+	zod.z.strictObject({ isNotNull: zod.z.literal(true) })
+]);
+const filterValueSchema = zod.z.union([
+	zod.z.string(),
+	zod.z.number(),
+	zod.z.boolean(),
+	filterOperatorsSchema
+]);
+/**
+* A raw SQL predicate fragment. Kept as a *string* (not a query-builder callback)
+* so the whole config stays JSON-serializable — it can be persisted into
+* `crm_entity_mappings` and shipped to the cloud unchanged. Embedded-only in
+* practice; not validated against the schema.
+*/
+const rawFilterSchema = zod.z.strictObject({ $raw: zod.z.string().min(1) });
+const columnFilterSchema = zod.z.record(zod.z.string(), filterValueSchema);
+/** `$raw` is a reserved key; a column literally named `$raw` is not addressable. */
+const filterSchema = zod.z.union([rawFilterSchema, columnFilterSchema]);
+/**
+* How the link between two entities is expressed in the host schema:
+* - `fkOn: "company"` — FK lives on the company table (e.g. organizations.owner_id)
+* - `fkOn: "contact"` — FK lives on the contact table (e.g. users.organization_id)
+* - `through`         — a join table sits between them (many-to-many, role often here)
+* - `$raw`            — opaque SQL join fragment (escape hatch; not schema-validated)
+*
+* `column` and the join-table keys are `table.column` or bare `column` strings.
+*/
+const relationshipViaSchema = zod.z.union([
+	zod.z.strictObject({
+		fkOn: zod.z.enum(["company", "contact"]),
+		column: zod.z.string().min(1)
+	}),
+	zod.z.strictObject({
+		through: zod.z.string().min(1),
+		localKey: zod.z.string().min(1),
+		foreignKey: zod.z.string().min(1)
+	}),
+	zod.z.strictObject({ $raw: zod.z.string().min(1) })
+]);
+const relationshipSchema = zod.z.strictObject({
+	/** Key of the related entity in the `entities` map. */
+	entity: zod.z.string().min(1),
+	via: relationshipViaSchema
+});
+/** A named map of relationships, as stored on an entity / in the mappings row. */
+const relationshipsSchema = zod.z.record(zod.z.string(), relationshipSchema);
+const entitySchema = zod.z.strictObject({
+	/** Which CRM concept this entity maps onto — a canonical concept or "custom". */
+	concept: zod.z.union([zod.z.enum(CRM_CONCEPTS), zod.z.literal(CUSTOM_CONCEPT)]),
+	/** Host table (or view) this entity is derived from. */
+	source: zod.z.string().min(1),
+	/**
+	* Distinguishes multiple entities backed by the same table (e.g. "primary"
+	* for owners, "secondary" for members). Free text; defaults to "primary".
+	*/
+	role: zod.z.string().min(1).optional(),
+	/** Predicate that narrows `source` into this entity's rows. Omit = whole table. */
+	filter: filterSchema.optional(),
+	/** clivlyField → sourceColumn. At least one field is required. */
+	fields: zod.z.record(zod.z.string(), zod.z.string()).refine((f) => Object.keys(f).length > 0, { message: "at least one field must be mapped" }),
+	/**
+	* Host-owned identity fields. Sync overwrites them; the CRM UI cannot edit
+	* them. Must be a subset of `fields` keys.
+	*/
+	readOnly: zod.z.array(zod.z.string()).optional(),
+	/** Named relationships to other entities in this config. */
+	relationships: zod.z.record(zod.z.string(), relationshipSchema).optional(),
+	/**
+	* For a "custom" entity, the crm_object_types row this materializes into.
+	* Required for custom (enforced at the API layer), unused for standard concepts.
+	*/
+	targetObjectTypeId: zod.z.string().min(1).optional(),
+	/**
+	* Advanced mapping: derive this entity from a base table plus explicit joins
+	* instead of a single source table. Valid only for `concept: "custom"`.
+	*
+	* When present, `source` still holds `projection.baseTable` and `fields`
+	* still holds one entry per binding — both so that every pre-existing reader
+	* of this config keeps working — but `projection` is the authored source of
+	* truth and the only thing the compiler interprets.
+	*/
+	projection: require_projection.projectionSchema.optional()
+});
+const entitiesConfigSchema = zod.z.strictObject({ entities: zod.z.record(zod.z.string(), entitySchema).refine((e) => Object.keys(e).length > 0, { message: "at least one entity must be defined" }) });
+/** Thrown by `defineClivlyConfig({ strict: true })` on non-canonical field keys. */
+var ClivlyConfigError = class extends Error {
+	issues;
+	constructor(issues) {
+		super(`Clivly config has ${issues.length} non-canonical field mapping(s) that would write empty values at sync time:\n${issues.map((issue) => `  - ${issue.path}: ${issue.message}`).join("\n")}`);
+		this.name = "ClivlyConfigError";
+		this.issues = issues;
+	}
+};
+function nonCanonicalFieldKeys(entity) {
+	const canonical = CANONICAL_FIELDS[entity.concept];
+	if (!canonical) return [];
+	return Object.keys(entity.fields).filter((key) => !canonical.includes(key));
+}
+function nonCanonicalMessage(entity, field) {
+	const canonical = CANONICAL_FIELDS[entity.concept] ?? [];
+	return `"${field}" is not a canonical ${entity.concept} field (expected one of: ${canonical.join(", ")})`;
+}
+function canonicalFieldIssues(config) {
+	const issues = [];
+	for (const [key, entity] of Object.entries(config.entities)) for (const field of nonCanonicalFieldKeys(entity)) issues.push({
+		path: `entities.${key}.fields.${field}`,
+		message: nonCanonicalMessage(entity, field)
+	});
+	return issues;
+}
+function defaultWarn(message) {
+	console.warn(message);
+}
+/**
+* Structural helper for `clivly.config.ts`. Gives full type inference on the
+* literal you pass and eagerly parses it, so shape errors surface at config
+* load rather than at sync time.
+*
+* It also catches the silent-data-loss footgun: a non-canonical field key for a
+* materialised concept (e.g. `fullName` instead of `name` on a `contact`) has no
+* destination column, so the store would write an empty value. By default these
+* are reported via `onWarn` (a `console.warn`); pass `{ strict: true }` to throw
+* a `ClivlyConfigError` instead. Does NOT validate against the host schema — that
+* needs the discovered schema; see `validateEntitiesConfig`.
+*/
+/**
+* The `fields` entry a projection binding implies, qualified as `ref.column`.
+* Qualified rather than bare: two bindings can pull the same column name from
+* different tables (`cl.full_name` and `adv.full_name`), which a bare column
+* name cannot tell apart.
+*/
+function projectionFields(projection) {
+	const fields = {};
+	for (const [name, binding] of Object.entries(projection.fieldBindings)) fields[name] = `${binding.from.table}.${binding.from.column}`;
+	return fields;
+}
+/**
+* `fields` duplicates `projection.fieldBindings`, and only the bindings are
+* compiled — so a hand-written `fields` that drifts is both silent and
+* invisible. Derive it when omitted, and reject it when it disagrees.
+*/
+function normalizeProjectionFields(config) {
+	const entities = {};
+	for (const [key, entity] of Object.entries(config.entities ?? {})) {
+		const projection = entity?.projection;
+		if (!projection?.fieldBindings) {
+			entities[key] = entity;
+			continue;
+		}
+		const derived = projectionFields(projection);
+		const declared = entity.fields;
+		if (!declared) {
+			entities[key] = {
+				...entity,
+				fields: derived
+			};
+			continue;
+		}
+		const drifted = [.../* @__PURE__ */ new Set([...Object.keys(derived), ...Object.keys(declared)])].filter((name) => declared[name] !== derived[name]).sort();
+		if (drifted.length > 0) {
+			const detail = drifted.map((name) => `"${name}": fields has ${declared[name] === void 0 ? "no entry" : `"${declared[name]}"`}, bindings imply ${derived[name] === void 0 ? "no entry" : `"${derived[name]}"`}`).join("; ");
+			throw new Error(`Clivly config: entity "${key}" has a \`fields\` map that disagrees with \`projection.fieldBindings\` — ${detail}. Only the bindings are compiled, so the \`fields\` copy would be silently ignored. Omit \`fields\` entirely and it will be derived.`);
+		}
+		entities[key] = entity;
+	}
+	return {
+		...config,
+		entities
+	};
+}
+function defineClivlyConfig(config, options) {
+	const parsed = entitiesConfigSchema.parse(normalizeProjectionFields(config));
+	const issues = canonicalFieldIssues(parsed);
+	if (issues.length > 0) {
+		if (options?.strict) throw new ClivlyConfigError(issues);
+		const warn = options?.onWarn ?? defaultWarn;
+		for (const issue of issues) warn(`⚠ Clivly config: ${issue.message} (${issue.path}) — this field would write an empty value at sync time. Pass { strict: true } to make this throw.`);
+	}
+	return parsed;
+}
+/** Split a `table.column` / bare `column` ref into its parts. */
+function parseColumnRef(ref) {
+	const dot = ref.indexOf(".");
+	if (dot === -1) return { column: ref };
+	return {
+		table: ref.slice(0, dot),
+		column: ref.slice(dot + 1)
+	};
+}
+/** Shared lookup + error-collection state threaded through the validators. */
+var SchemaValidator = class {
+	errors = [];
+	columnsByTable = /* @__PURE__ */ new Map();
+	constructor(schema) {
+		for (const table of schema) this.columnsByTable.set(table.name, new Set(table.columns));
+	}
+	tableExists(name) {
+		return this.columnsByTable.has(name);
+	}
+	columnExists(table, column) {
+		return this.columnsByTable.get(table)?.has(column) ?? false;
+	}
+	report(path, message) {
+		this.errors.push({
+			path,
+			message
+		});
+	}
+	/** Report if `column` is absent from `table`. Returns whether it existed. */
+	requireColumn(path, table, column) {
+		if (this.columnExists(table, column)) return true;
+		this.report(path, `column "${column}" does not exist on "${table}"`);
+		return false;
+	}
+};
+function validateFields(v, base, entity) {
+	for (const [field, column] of Object.entries(entity.fields)) v.requireColumn(`${base}.fields.${field}`, entity.source, column);
+	for (const field of nonCanonicalFieldKeys(entity)) v.report(`${base}.fields.${field}`, nonCanonicalMessage(entity, field));
+}
+function validateReadOnly(v, base, entity) {
+	for (const field of entity.readOnly ?? []) if (!(field in entity.fields)) v.report(`${base}.readOnly`, `"${field}" is not one of this entity's fields`);
+}
+function validateFilter(v, base, entity) {
+	if (!entity.filter || "$raw" in entity.filter) return;
+	for (const column of Object.keys(entity.filter)) v.requireColumn(`${base}.filter.${column}`, entity.source, column);
+}
+function validateFkVia(v, relBase, via, entity, related) {
+	const { table, column } = parseColumnRef(via.column);
+	const fkTable = table ?? (via.fkOn === "contact" ? entity.source : related?.source);
+	const path = `${relBase}.via.column`;
+	if (!fkTable) {
+		v.report(path, `cannot resolve table for FK column "${via.column}"`);
+		return;
+	}
+	if (!v.tableExists(fkTable)) {
+		v.report(path, `table "${fkTable}" is not in the discovered schema`);
+		return;
+	}
+	v.requireColumn(path, fkTable, column);
+}
+function validateThroughVia(v, relBase, via) {
+	if (!v.tableExists(via.through)) {
+		v.report(`${relBase}.via.through`, `join table "${via.through}" is not in the discovered schema`);
+		return;
+	}
+	v.requireColumn(`${relBase}.via.localKey`, via.through, via.localKey);
+	v.requireColumn(`${relBase}.via.foreignKey`, via.through, via.foreignKey);
+}
+function validateRelationship(v, base, config, entity, relName, rel) {
+	const relBase = `${base}.relationships.${relName}`;
+	const related = config.entities[rel.entity];
+	if (!related) v.report(`${relBase}.entity`, `"${rel.entity}" is not a defined entity`);
+	const { via } = rel;
+	if ("fkOn" in via) validateFkVia(v, relBase, via, entity, related);
+	else if ("through" in via) validateThroughVia(v, relBase, via);
+}
+function validateEntity(v, config, key, entity, schema) {
+	const base = `entities.${key}`;
+	if (!v.tableExists(entity.source)) {
+		v.report(`${base}.source`, `table "${entity.source}" is not in the discovered schema`);
+		return;
+	}
+	if (entity.projection) {
+		if (entity.concept !== "custom") v.report(`${base}.projection`, `projection mappings are only supported for concept "${CUSTOM_CONCEPT}"`);
+		if (!entity.targetObjectTypeId) v.report(`${base}.targetObjectTypeId`, "a projection mapping must target a custom object type");
+		if (entity.source !== entity.projection.baseTable) v.report(`${base}.source`, `"source" ("${entity.source}") must match "projection.baseTable" ("${entity.projection.baseTable}") — the view compiler reads baseTable and the sync engine reads source, so a mismatch makes them disagree about which table this entity is`);
+		for (const error of validateProjection(entity.projection, schema, base)) v.report(error.path, error.message);
+		validateReadOnly(v, base, entity);
+		validateFilter(v, base, entity);
+		return;
+	}
+	validateFields(v, base, entity);
+	validateReadOnly(v, base, entity);
+	validateFilter(v, base, entity);
+	for (const [relName, rel] of Object.entries(entity.relationships ?? {})) validateRelationship(v, base, config, entity, relName, rel);
+}
+/**
+* Validate a (structurally valid) config against the host's discovered schema:
+* source tables exist, mapped columns exist, `readOnly` ⊆ `fields`, filter
+* columns exist, and relationships point at real entities/tables/columns.
+*
+* `$raw` filters and `$raw` relationship joins are opaque and skipped. Returns
+* every error found (not just the first) so a mapping UI or CLI can show them
+* all at once.
+*/
+function validateEntitiesConfig(config, schema) {
+	const validator = new SchemaValidator(schema);
+	for (const [key, entity] of Object.entries(config.entities)) validateEntity(validator, config, key, entity, schema);
+	return {
+		valid: validator.errors.length === 0,
+		errors: validator.errors
+	};
+}
+//#endregion
+Object.defineProperty(exports, "CANONICAL_FIELDS", {
+	enumerable: true,
+	get: function() {
+		return CANONICAL_FIELDS;
+	}
+});
+Object.defineProperty(exports, "CRM_CONCEPTS", {
+	enumerable: true,
+	get: function() {
+		return CRM_CONCEPTS;
+	}
+});
+Object.defineProperty(exports, "CUSTOM_CONCEPT", {
+	enumerable: true,
+	get: function() {
+		return CUSTOM_CONCEPT;
+	}
+});
+Object.defineProperty(exports, "ClivlyConfigError", {
+	enumerable: true,
+	get: function() {
+		return ClivlyConfigError;
+	}
+});
+Object.defineProperty(exports, "MATERIALIZING_CONCEPTS", {
+	enumerable: true,
+	get: function() {
+		return MATERIALIZING_CONCEPTS;
+	}
+});
+Object.defineProperty(exports, "columnMetaFor", {
+	enumerable: true,
+	get: function() {
+		return columnMetaFor;
+	}
+});
+Object.defineProperty(exports, "coversUniqueKey", {
+	enumerable: true,
+	get: function() {
+		return coversUniqueKey;
+	}
+});
+Object.defineProperty(exports, "defineClivlyConfig", {
+	enumerable: true,
+	get: function() {
+		return defineClivlyConfig;
+	}
+});
+Object.defineProperty(exports, "entitiesConfigSchema", {
+	enumerable: true,
+	get: function() {
+		return entitiesConfigSchema;
+	}
+});
+Object.defineProperty(exports, "fanOutJoins", {
+	enumerable: true,
+	get: function() {
+		return fanOutJoins;
+	}
+});
+Object.defineProperty(exports, "filterSchema", {
+	enumerable: true,
+	get: function() {
+		return filterSchema;
+	}
+});
+Object.defineProperty(exports, "hasRichMeta", {
+	enumerable: true,
+	get: function() {
+		return hasRichMeta;
+	}
+});
+Object.defineProperty(exports, "joinFansOut", {
+	enumerable: true,
+	get: function() {
+		return joinFansOut;
+	}
+});
+Object.defineProperty(exports, "primaryKeyColumns", {
+	enumerable: true,
+	get: function() {
+		return primaryKeyColumns;
+	}
+});
+Object.defineProperty(exports, "projectionFields", {
+	enumerable: true,
+	get: function() {
+		return projectionFields;
+	}
+});
+Object.defineProperty(exports, "relationshipSchema", {
+	enumerable: true,
+	get: function() {
+		return relationshipSchema;
+	}
+});
+Object.defineProperty(exports, "relationshipsSchema", {
+	enumerable: true,
+	get: function() {
+		return relationshipsSchema;
+	}
+});
+Object.defineProperty(exports, "validateEntitiesConfig", {
+	enumerable: true,
+	get: function() {
+		return validateEntitiesConfig;
+	}
+});
+Object.defineProperty(exports, "validateProjection", {
+	enumerable: true,
+	get: function() {
+		return validateProjection;
+	}
+});