@clivly/core 0.7.4 → 0.9.0

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)) {

package/dist/view-compiler-BKrBA_II.mjs

@@ -0,0 +1,254 @@
+import { r as identityRefs, t as BASE_REF } from "./projection-C_EMRmZ8.mjs";
+//#region src/projection-sql.ts
+/**
+* SQL generation for projection-backed entities.
+*
+* Base and joins are aliased by their ref key (`base`, then each join's `key`),
+* which is what allows the same table to be joined twice and keeps generated
+* SQL independent of host table names.
+*
+* Pure string generation — no DB access. Identifiers are escaped so output is
+* deterministic and injection-safe.
+*/
+/** Quote a single identifier part, escaping embedded double-quotes. */
+function quoteIdent(name) {
+	return `"${name.replace(/"/g, "\"\"")}"`;
+}
+function refSql(ref) {
+	return `${quoteIdent(ref.table)}.${quoteIdent(ref.column)}`;
+}
+/**
+* The identity expression, aliased as `id`. Composite identities concatenate
+* their parts with `::`; validation guarantees every part is NOT NULL and
+* non-text, which is what makes the concatenation collision-free.
+*/
+function identitySql(projection, basePkColumn) {
+	const refs = identityRefs(projection.identity, basePkColumn);
+	if (projection.identity.kind === "composite") return `CONCAT_WS('::', ${refs.map((ref) => `${refSql(ref)}::text`).join(", ")}) AS ${quoteIdent("id")}`;
+	const [ref] = refs;
+	if (!ref) throw new Error("projection identity resolved to no column");
+	return `${refSql(ref)} AS ${quoteIdent("id")}`;
+}
+function compileProjectionSelect(projection, basePkColumn) {
+	const selectItems = [identitySql(projection, basePkColumn)];
+	const columns = ["id"];
+	for (const [field, binding] of Object.entries(projection.fieldBindings)) {
+		selectItems.push(`${refSql(binding.from)} AS ${quoteIdent(field)}`);
+		columns.push(field);
+	}
+	return {
+		columns,
+		selectItems
+	};
+}
+function compileProjectionJoins(projection) {
+	return projection.joins.map((join) => {
+		const keyword = join.type === "inner" ? "INNER JOIN" : "LEFT JOIN";
+		const on = join.on.map((c) => `${refSql(c.left)} = ${refSql(c.right)}`).join(" AND ");
+		return `${keyword} ${quoteIdent(join.table)} AS ${quoteIdent(join.key)} ON ${on}`;
+	});
+}
+/** `FROM <baseTable> AS "base"` — the alias every ref resolves against. */
+function compileProjectionFrom(projection) {
+	return `FROM ${quoteIdent(projection.baseTable)} AS ${quoteIdent(BASE_REF)}`;
+}
+//#endregion
+//#region src/view-compiler.ts
+/**
+* View compiler (Phase 2) — turns a validated entity config into read-only
+* Postgres view DDL.
+*
+* Each entity compiles to `crm_src_<entity>`: a projection over the host table
+* that (a) selects the source primary key as `id` (the sync engine's
+* `source_ref`), (b) aliases mapped columns to their Clivly field names,
+* (c) resolves each relationship to a `<relationship>_ref` column carrying the
+* host-side key, and (d) applies the entity's filter as a WHERE clause.
+*
+* The view is the security boundary: it exposes only allow-listed columns, and
+* the sync engine (Phase 3) reads exclusively from it — never the raw table.
+* Relationship refs stay host-side keys here; Phase 3 maps `<rel>_ref` onto the
+* corresponding `crm_companies.id` mirror row.
+*
+* Pure string generation — no DB access. Config is developer-authored, but all
+* identifiers and literals are still escaped so output is deterministic and
+* injection-safe.
+*/
+/** The source primary-key column. Assumed `id`; the sync engine reads it as `source_ref`. */
+const SOURCE_KEY = "id";
+const DEFAULT_VIEW_PREFIX = "crm_src_";
+const DEFAULT_ROLE = "primary";
+/** Emit a SQL literal for a scalar filter value. */
+function quoteLiteral(value) {
+	if (typeof value === "number") return String(value);
+	if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
+	return `'${value.replace(/'/g, "''")}'`;
+}
+function quoteList(values) {
+	return `(${values.map((v) => quoteLiteral(v)).join(", ")})`;
+}
+/** Compile one column predicate into a SQL boolean expression. */
+function compilePredicate(table, column, value) {
+	const col = `${quoteIdent(table)}.${quoteIdent(column)}`;
+	if (value === null || typeof value !== "object") return `${col} = ${quoteLiteral(value)}`;
+	if ("eq" in value) return `${col} = ${quoteLiteral(value.eq)}`;
+	if ("ne" in value) return `${col} <> ${quoteLiteral(value.ne)}`;
+	if ("in" in value) return `${col} IN ${quoteList(value.in)}`;
+	if ("notIn" in value) return `${col} NOT IN ${quoteList(value.notIn)}`;
+	if ("isNull" in value) return `${col} IS NULL`;
+	if ("isNotNull" in value) return `${col} IS NOT NULL`;
+	throw new Error(`unsupported filter predicate on ${table}.${column}`);
+}
+/**
+* Build the WHERE conditions for an entity. Returns an array of SQL fragments
+* (ANDed by the caller). `$raw` filters pass through verbatim.
+*/
+function compileFilterConditions(table, filter) {
+	if (!filter) return [];
+	if ("$raw" in filter) return [`(${filter.$raw})`];
+	return Object.entries(filter).map(([column, value]) => compilePredicate(table, column, value));
+}
+/** Split a `table.column` ref, defaulting the table when unqualified. */
+function refParts(ref, defaultTable) {
+	const dot = ref.indexOf(".");
+	if (dot === -1) return {
+		table: defaultTable,
+		column: ref
+	};
+	return {
+		table: ref.slice(0, dot),
+		column: ref.slice(dot + 1)
+	};
+}
+function compileRelationship(relName, rel, source, related) {
+	const refCol = `${relName}_ref`;
+	const refAlias = quoteIdent(refCol);
+	const { via } = rel;
+	if ("fkOn" in via) {
+		const relatedTable = related?.source ?? "";
+		if (via.fkOn === "company") {
+			const { table, column } = refParts(via.column, relatedTable);
+			const relatedFilter = compileFilterConditions(table, related?.filter);
+			const on = [`${quoteIdent(table)}.${quoteIdent(column)} = ${quoteIdent(source.source)}.${quoteIdent(SOURCE_KEY)}`, ...relatedFilter].join(" AND ");
+			return {
+				clause: `LEFT JOIN ${quoteIdent(table)} ON ${on}`,
+				refSelect: `${quoteIdent(table)}.${quoteIdent(SOURCE_KEY)} AS ${refAlias}`,
+				refColumn: refCol
+			};
+		}
+		const { table, column } = refParts(via.column, source.source);
+		const on = [`${quoteIdent(relatedTable)}.${quoteIdent(SOURCE_KEY)} = ${quoteIdent(table)}.${quoteIdent(column)}`, ...compileFilterConditions(relatedTable, related?.filter)].join(" AND ");
+		return {
+			clause: `LEFT JOIN ${quoteIdent(relatedTable)} ON ${on}`,
+			refSelect: `${quoteIdent(relatedTable)}.${quoteIdent(SOURCE_KEY)} AS ${refAlias}`,
+			refColumn: refCol
+		};
+	}
+	if ("through" in via) {
+		const on = `${quoteIdent(via.through)}.${quoteIdent(via.localKey)} = ${quoteIdent(source.source)}.${quoteIdent(SOURCE_KEY)}`;
+		return {
+			clause: `LEFT JOIN ${quoteIdent(via.through)} ON ${on}`,
+			refSelect: `${quoteIdent(via.through)}.${quoteIdent(via.foreignKey)} AS ${refAlias}`,
+			refColumn: refCol
+		};
+	}
+	return {
+		clause: via.$raw,
+		refSelect: null,
+		refColumn: refCol
+	};
+}
+/** SELECT items for a legacy single-table entity: source key, then fields. */
+function legacySelect(entity, src) {
+	const selectItems = [`${quoteIdent(src)}.${quoteIdent(SOURCE_KEY)} AS ${quoteIdent("id")}`];
+	const columns = ["id"];
+	for (const [field, column] of Object.entries(entity.fields)) {
+		selectItems.push(`${quoteIdent(src)}.${quoteIdent(column)} AS ${quoteIdent(field)}`);
+		columns.push(field);
+	}
+	return {
+		columns,
+		selectItems
+	};
+}
+/**
+* Relationship JOINs for a legacy entity. Appends each relationship's ref
+* column to `columns`/`selectItems` in place, preserving the existing order.
+*/
+function legacyJoins(config, entity, columns, selectItems) {
+	const joins = [];
+	for (const [relName, rel] of Object.entries(entity.relationships ?? {})) {
+		const compiled = compileRelationship(relName, rel, entity, config.entities[rel.entity]);
+		joins.push(compiled.clause);
+		if (compiled.refSelect) {
+			selectItems.push(compiled.refSelect);
+			columns.push(compiled.refColumn);
+		}
+	}
+	return joins;
+}
+function compileEntityView(config, entityKey, options = {}) {
+	const entity = config.entities[entityKey];
+	if (!entity) throw new Error(`entity "${entityKey}" is not defined`);
+	const viewName = `${options.viewPrefix ?? "crm_src_"}${entityKey}`;
+	const src = entity.source;
+	const projection = entity.projection;
+	const filterTable = projection ? BASE_REF : src;
+	const { selectItems, columns } = projection ? compileProjectionSelect(projection, SOURCE_KEY) : legacySelect(entity, src);
+	const joins = projection ? compileProjectionJoins(projection) : legacyJoins(config, entity, columns, selectItems);
+	const conditions = compileFilterConditions(filterTable, entity.filter);
+	if (options.orgScope) conditions.push(`${quoteIdent(filterTable)}.${quoteIdent(options.orgScope.column)} = ${quoteLiteral(options.orgScope.value)}`);
+	const lines = [
+		options.securityInvoker ?? true ? `CREATE OR REPLACE VIEW ${quoteIdent(viewName)} WITH (security_invoker = true) AS` : `CREATE OR REPLACE VIEW ${quoteIdent(viewName)} AS`,
+		`SELECT ${selectItems.join(", ")}`,
+		projection ? compileProjectionFrom(projection) : `FROM ${quoteIdent(src)}`,
+		...joins
+	];
+	if (conditions.length > 0) lines.push(`WHERE ${conditions.join(" AND ")}`);
+	const sql = `${lines.join("\n")};`;
+	return {
+		entityKey,
+		viewName,
+		concept: entity.concept,
+		role: entity.role ?? DEFAULT_ROLE,
+		sourceTable: src,
+		columns,
+		sql,
+		dropSql: `DROP VIEW IF EXISTS ${quoteIdent(viewName)};`
+	};
+}
+/** Compile every entity in the config into its view, in declaration order. */
+function compileEntityViews(config, options = {}) {
+	return Object.keys(config.entities).map((key) => compileEntityView(config, key, options));
+}
+/**
+* Dry-run each entity's compiled view against the host DB via a caller-provided
+* `run` function, so `$raw` filter/join fragments — which skip schema validation
+* (see `validateEntitiesConfig`) — fail loudly *before* the first sync instead of
+* at sync time. Never throws: each view's outcome is collected into an
+* `ExplainResult`, so a mapping UI or CLI can show every problem at once.
+*
+* `run` should execute the SQL somewhere side-effect-free — e.g. inside a
+* transaction it rolls back, or by `EXPLAIN`-ing the statement — since the
+* compiled SQL is a `CREATE OR REPLACE VIEW`.
+*/
+async function explainEntitiesConfig(config, run, options = {}) {
+	const results = [];
+	for (const view of compileEntityViews(config, options)) try {
+		await run(view.sql);
+		results.push({
+			entityKey: view.entityKey,
+			ok: true,
+			sql: view.sql
+		});
+	} catch (error) {
+		results.push({
+			entityKey: view.entityKey,
+			ok: false,
+			sql: view.sql,
+			error: error instanceof Error ? error.message : String(error)
+		});
+	}
+	return results;
+}
+//#endregion
+export { explainEntitiesConfig as i, compileEntityView as n, compileEntityViews as r, DEFAULT_VIEW_PREFIX as t };