@clivly/core 0.9.6 → 0.10.0

package/dist/{entity-config-BAaZOIID.cjs → entity-config-C5jBmG2C.cjs}

@@ -1,40 +1,6 @@
-const require_projection = require("./projection-OJYCYmS_.cjs");
+const require_projection = require("./projection-DFgCoyZl.cjs");
+const require_schema_meta = require("./schema-meta-Cgi0MnHh.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.
@@ -55,7 +21,7 @@ function joinSideColumns(join) {
 	return columns;
 }
 function joinFansOut(join, joinTable) {
-	return !coversUniqueKey(joinTable, joinSideColumns(join));
+	return !require_schema_meta.coversUniqueKey(joinTable, joinSideColumns(join));
 }
 /** Every join in the projection that can multiply rows. */
 function fanOutJoins(projection, tablesByName) {
@@ -135,10 +101,10 @@ function checkTablesExist(errors, projection, resolver, base) {
 			ok = false;
 			continue;
 		}
-		if (!hasRichMeta(table)) {
+		if (!require_schema_meta.hasRichMeta(table)) {
 			errors.push({
 				path,
-				message: `table "${name}" has no key/column metadata — upgrade @clivly/sdk and re-run discovery before using a projection`
+				message: `table "${name}" was discovered without column types or unique keys, which a projection needs to prove its id is unique. Redeploy or restart the app so it re-reports its schema (or run \`clivly push-schema\`); if the table is declared by hand as \`{ name, columns }\`, use \`discoverFromDrizzle\` so keys and types come with it.`
 			});
 			ok = false;
 		}
@@ -183,10 +149,27 @@ function checkRefs(errors, projection, resolver, base, basePk) {
 	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);
 }
+/**
+* Prove that a single-column identity (`column`, or `base_pk` with an
+* explicit column) is actually unique.
+*
+* `coversUniqueKey` fails closed on absent metadata, same as every other
+* check in this file: a column not provably covered by a unique key is
+* rejected, never assumed safe.
+*/
+function checkSingleColumnIdentity(errors, resolver, path, ref) {
+	const table = resolver.tableFor(ref.table);
+	if (!table) return;
+	if (!require_schema_meta.coversUniqueKey(table, [ref.column])) errors.push({
+		path,
+		message: `identity column "${ref.table}.${ref.column}" is not covered by a unique key of "${table.name}" — pick a column with a unique constraint, or use a composite identity that is`
+	});
+}
 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) {
+	const pk = require_schema_meta.primaryKeyColumns(baseTable);
+	const { identity } = projection;
+	if (identity.kind === "base_pk" && !identity.column) {
 		if (pk.length === 0) {
 			errors.push({
 				path,
@@ -201,11 +184,23 @@ function checkIdentitySafety(errors, projection, resolver, base, baseTable) {
 			});
 			return;
 		}
+		return;
+	}
+	if (identity.kind === "base_pk" && identity.column) {
+		checkSingleColumnIdentity(errors, resolver, path, {
+			table: require_projection.BASE_REF,
+			column: identity.column
+		});
+		return;
 	}
-	if (projection.identity.kind !== "composite") return;
-	for (const part of projection.identity.parts) {
+	if (identity.kind === "column") {
+		checkSingleColumnIdentity(errors, resolver, path, identity.from);
+		return;
+	}
+	if (identity.kind !== "composite") return;
+	for (const part of identity.parts) {
 		const table = resolver.tableFor(part.table);
-		const meta = table && columnMetaFor(table, part.column);
+		const meta = table && require_schema_meta.columnMetaFor(table, part.column);
 		if (!meta) continue;
 		if (meta.nullable !== false) errors.push({
 			path,
@@ -239,12 +234,70 @@ function checkFanOut(errors, projection, resolver, base, basePk) {
 		});
 		return;
 	}
-	if (!coversUniqueKey(joinTable, require_projection.identityRefs(projection.identity, basePk).filter((ref) => ref.table === join.key).map((ref) => ref.column))) errors.push({
+	if (!require_schema_meta.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`
 	});
 }
 /**
+* One error naming a filter column that is not on the projection's base table,
+* and the base table it would have to be on.
+*/
+function columnOnBase(column, baseTable, path) {
+	if (baseTable?.columns.includes(column)) return [];
+	return [{
+		path,
+		message: `filter column "${column}" does not exist on "${baseTable?.name ?? "the base table"}" — a derived object is filtered by its base table's columns only, so name one of those, or move the condition into a join's \`on\``
+	}];
+}
+/**
+* A derived object's filter is evaluated in the cloud against pushed rows, so
+* it can only name columns of the base table.
+*
+* Every rejected shape here fails *silently* today, which is the whole reason
+* the check exists — a filter that cannot be honoured must error, never quietly
+* return the wrong rows. The three shapes fail in different directions:
+*
+* - `$raw` is opaque SQL meant for the embedded model. The cloud path cannot
+*   evaluate it and passes every row, so the filter is ignored and the object
+*   syncs UNFILTERED.
+* - A joined-table column resolves to nothing on a pushed row, so under a
+*   positive operator (`eq`, `in`) no row matches and the object syncs EMPTY.
+* - The same unresolvable column under a NEGATIVE operator (`ne`, `isNull`,
+*   `notIn`) is the dangerous one: the missing cell reads as null, so the
+*   predicate is true for every row and a filter meant to narrow the sync
+*   ADMITS EVERYTHING. Nobody notices extra rows arriving.
+*
+* Rejecting an unresolvable column closes the last two together.
+*/
+function validateProjectionFilter(filter, projection, schema, base) {
+	if (!filter) return [];
+	const path = `${base}.filter`;
+	if ("$raw" in filter) return [{
+		path,
+		message: "a $raw filter cannot be evaluated against a derived object's rows — it is opaque SQL, so the cloud passes every row through unfiltered. Express it as column conditions on the base table instead"
+	}];
+	const baseTable = schema.find((t) => t.name === projection.baseTable);
+	const errors = [];
+	for (const column of Object.keys(filter)) {
+		if (column.includes(".")) {
+			const [ref, ...rest] = column.split(".");
+			const bare = rest.join(".");
+			if (ref !== "base") {
+				errors.push({
+					path,
+					message: `filter column "${column}" names the join "${ref}", but a derived object is filtered by its base table ("${projection.baseTable}") only — filter on a base column, or move the condition into that join's \`on\``
+				});
+				continue;
+			}
+			errors.push(...columnOnBase(bare, baseTable, path));
+			continue;
+		}
+		errors.push(...columnOnBase(column, baseTable, path));
+	}
+	return errors;
+}
+/**
 * 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.
 */
@@ -255,7 +308,7 @@ function validateProjection(projection, schema, 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";
+	const basePk = require_schema_meta.primaryKeyColumns(baseTable)[0] ?? "id";
 	checkRefs(errors, projection, resolver, base, basePk);
 	checkIdentitySafety(errors, projection, resolver, base, baseTable);
 	checkFanOut(errors, projection, resolver, base, basePk);
@@ -517,6 +570,15 @@ function customObjectDeclarations(config) {
 * 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.
+*
+* This is the single derivation of that map, and both consumers depend on it
+* emitting ref tokens. `mappingsToEntitiesConfig` populates a projection
+* entity's required `fields`; the cloud ingest path needs the same map because
+* a projection's persisted `crm_entity_mappings.field_map` is empty by design,
+* so `rowToSourceRow` derives the effective field map from the projection
+* instead. The tokens emitted here are exactly how `fromDrizzleProjection` keys
+* the rows it pushes (`drizzle-projection.ts` `refToken`), so the two line up.
+* Deriving this a second time anywhere would let the copies drift.
 */
 function projectionFields(projection) {
 	const fields = {};
@@ -655,7 +717,7 @@ function validateEntity(v, config, key, entity, schema) {
 		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);
+		for (const error of validateProjectionFilter(entity.filter, entity.projection, schema, base)) v.report(error.path, error.message);
 		return;
 	}
 	validateFields(v, base, entity);
@@ -711,18 +773,6 @@ Object.defineProperty(exports, "MATERIALIZING_CONCEPTS", {
 		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, "customObjectDeclarations", {
 	enumerable: true,
 	get: function() {
@@ -753,24 +803,12 @@ Object.defineProperty(exports, "filterSchema", {
 		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() {
@@ -801,3 +839,9 @@ Object.defineProperty(exports, "validateProjection", {
 		return validateProjection;
 	}
 });
+Object.defineProperty(exports, "validateProjectionFilter", {
+	enumerable: true,
+	get: function() {
+		return validateProjectionFilter;
+	}
+});

package/dist/{entity-config-buOIVtMM.d.cts → entity-config-DCa785OE.d.cts}

@@ -16,6 +16,23 @@ import { z } from "zod";
  */
 /** The reserved ref name for the projection's base table. */
 declare const BASE_REF = "base";
+/**
+ * Entity keys become view names (`crm_src_<entityKey>`), so keep them slugs.
+ *
+ * Accepts hyphens as well as underscores, matching `OBJECT_TYPE_SLUG_PATTERN`
+ * on the server. Those two were widened apart: the server learned hyphens
+ * because the SDK's own `slugify` collapses non-alphanumerics to them and
+ * `clivly status` reports that form as canonical — but this pattern was missed,
+ * so `clivly status` would tell you to key an entity `client-accounts` and then
+ * `defineClivlyConfig` would reject the config it had just asked for. Same bug,
+ * opposite half of the product.
+ *
+ * Widening is the safe direction: every key that was valid before still is, so
+ * nothing existing is renamed. Safe at all because neither use is ever a bare
+ * SQL identifier — the view name is quoted (`view-compiler.ts`, `quoteIdent`),
+ * and so is a join's `key` when it is emitted as an alias.
+ */
+declare const PROJECTION_KEY_PATTERN: RegExp;
 declare const projectionRefSchema: z.ZodObject<{
   table: z.ZodString;
   column: z.ZodString;
@@ -517,6 +534,15 @@ declare function customObjectDeclarations(config: ClivlyEntitiesConfig): CustomO
  * 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.
+ *
+ * This is the single derivation of that map, and both consumers depend on it
+ * emitting ref tokens. `mappingsToEntitiesConfig` populates a projection
+ * entity's required `fields`; the cloud ingest path needs the same map because
+ * a projection's persisted `crm_entity_mappings.field_map` is empty by design,
+ * so `rowToSourceRow` derives the effective field map from the projection
+ * instead. The tokens emitted here are exactly how `fromDrizzleProjection` keys
+ * the rows it pushes (`drizzle-projection.ts` `refToken`), so the two line up.
+ * Deriving this a second time anywhere would let the copies drift.
  */
 declare function projectionFields(projection: ProjectionMapping): Record<string, string>;
 declare function defineClivlyConfig(config: ClivlyEntitiesConfigInput, options?: {
@@ -577,4 +603,4 @@ interface ConfigValidationResult {
  */
 declare function validateEntitiesConfig(config: ClivlyEntitiesConfig, schema: DiscoveredSchemaTable[]): ConfigValidationResult;
 //#endregion
-export { BASE_REF as A, defineClivlyConfig as C, relationshipSchema as D, projectionFields as E, ProjectionRef as F, identityRefs as I, projectionSchema as L, ProjectionIdentity as M, ProjectionJoin as N, relationshipsSchema as O, ProjectionMapping as P, customObjectDeclarations as S, filterSchema as T, MATERIALIZING_CONCEPTS as _, ClivlyEntitiesConfig as a, RelationshipVia as b, ClivlyEntityConfigInput as c, CrmConcept as d, CustomObjectDeclaration as f, FilterValue as g, FilterExpr as h, ClivlyConfigError as i, ProjectionFieldBinding as j, validateEntitiesConfig as k, ConfigValidationError as l, DiscoveredSchemaTable as m, CRM_CONCEPTS as n, ClivlyEntitiesConfigInput as o, DiscoveredColumnMeta as p, CUSTOM_CONCEPT as r, ClivlyEntityConfig as s, CANONICAL_FIELDS as t, ConfigValidationResult as u, MaterializingConcept as v, entitiesConfigSchema as w, RelationshipsMap as x, RelationshipSpec as y };
+export { BASE_REF as A, defineClivlyConfig as C, relationshipSchema as D, projectionFields as E, ProjectionMapping as F, ProjectionRef as I, identityRefs as L, ProjectionFieldBinding as M, ProjectionIdentity as N, relationshipsSchema as O, ProjectionJoin as P, projectionSchema as R, customObjectDeclarations as S, filterSchema as T, MATERIALIZING_CONCEPTS as _, ClivlyEntitiesConfig as a, RelationshipVia as b, ClivlyEntityConfigInput as c, CrmConcept as d, CustomObjectDeclaration as f, FilterValue as g, FilterExpr as h, ClivlyConfigError as i, PROJECTION_KEY_PATTERN as j, validateEntitiesConfig as k, ConfigValidationError as l, DiscoveredSchemaTable as m, CRM_CONCEPTS as n, ClivlyEntitiesConfigInput as o, DiscoveredColumnMeta as p, CUSTOM_CONCEPT as r, ClivlyEntityConfig as s, CANONICAL_FIELDS as t, ConfigValidationResult as u, MaterializingConcept as v, entitiesConfigSchema as w, RelationshipsMap as x, RelationshipSpec as y };

package/dist/{entity-config-buOIVtMM.d.mts → entity-config-DCa785OE.d.mts}

@@ -16,6 +16,23 @@ import { z } from "zod";
  */
 /** The reserved ref name for the projection's base table. */
 declare const BASE_REF = "base";
+/**
+ * Entity keys become view names (`crm_src_<entityKey>`), so keep them slugs.
+ *
+ * Accepts hyphens as well as underscores, matching `OBJECT_TYPE_SLUG_PATTERN`
+ * on the server. Those two were widened apart: the server learned hyphens
+ * because the SDK's own `slugify` collapses non-alphanumerics to them and
+ * `clivly status` reports that form as canonical — but this pattern was missed,
+ * so `clivly status` would tell you to key an entity `client-accounts` and then
+ * `defineClivlyConfig` would reject the config it had just asked for. Same bug,
+ * opposite half of the product.
+ *
+ * Widening is the safe direction: every key that was valid before still is, so
+ * nothing existing is renamed. Safe at all because neither use is ever a bare
+ * SQL identifier — the view name is quoted (`view-compiler.ts`, `quoteIdent`),
+ * and so is a join's `key` when it is emitted as an alias.
+ */
+declare const PROJECTION_KEY_PATTERN: RegExp;
 declare const projectionRefSchema: z.ZodObject<{
   table: z.ZodString;
   column: z.ZodString;
@@ -517,6 +534,15 @@ declare function customObjectDeclarations(config: ClivlyEntitiesConfig): CustomO
  * 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.
+ *
+ * This is the single derivation of that map, and both consumers depend on it
+ * emitting ref tokens. `mappingsToEntitiesConfig` populates a projection
+ * entity's required `fields`; the cloud ingest path needs the same map because
+ * a projection's persisted `crm_entity_mappings.field_map` is empty by design,
+ * so `rowToSourceRow` derives the effective field map from the projection
+ * instead. The tokens emitted here are exactly how `fromDrizzleProjection` keys
+ * the rows it pushes (`drizzle-projection.ts` `refToken`), so the two line up.
+ * Deriving this a second time anywhere would let the copies drift.
  */
 declare function projectionFields(projection: ProjectionMapping): Record<string, string>;
 declare function defineClivlyConfig(config: ClivlyEntitiesConfigInput, options?: {
@@ -577,4 +603,4 @@ interface ConfigValidationResult {
  */
 declare function validateEntitiesConfig(config: ClivlyEntitiesConfig, schema: DiscoveredSchemaTable[]): ConfigValidationResult;
 //#endregion
-export { BASE_REF as A, defineClivlyConfig as C, relationshipSchema as D, projectionFields as E, ProjectionRef as F, identityRefs as I, projectionSchema as L, ProjectionIdentity as M, ProjectionJoin as N, relationshipsSchema as O, ProjectionMapping as P, customObjectDeclarations as S, filterSchema as T, MATERIALIZING_CONCEPTS as _, ClivlyEntitiesConfig as a, RelationshipVia as b, ClivlyEntityConfigInput as c, CrmConcept as d, CustomObjectDeclaration as f, FilterValue as g, FilterExpr as h, ClivlyConfigError as i, ProjectionFieldBinding as j, validateEntitiesConfig as k, ConfigValidationError as l, DiscoveredSchemaTable as m, CRM_CONCEPTS as n, ClivlyEntitiesConfigInput as o, DiscoveredColumnMeta as p, CUSTOM_CONCEPT as r, ClivlyEntityConfig as s, CANONICAL_FIELDS as t, ConfigValidationResult as u, MaterializingConcept as v, entitiesConfigSchema as w, RelationshipsMap as x, RelationshipSpec as y };
+export { BASE_REF as A, defineClivlyConfig as C, relationshipSchema as D, projectionFields as E, ProjectionMapping as F, ProjectionRef as I, identityRefs as L, ProjectionFieldBinding as M, ProjectionIdentity as N, relationshipsSchema as O, ProjectionJoin as P, projectionSchema as R, customObjectDeclarations as S, filterSchema as T, MATERIALIZING_CONCEPTS as _, ClivlyEntitiesConfig as a, RelationshipVia as b, ClivlyEntityConfigInput as c, CrmConcept as d, CustomObjectDeclaration as f, FilterValue as g, FilterExpr as h, ClivlyConfigError as i, PROJECTION_KEY_PATTERN as j, validateEntitiesConfig as k, ConfigValidationError as l, DiscoveredSchemaTable as m, CRM_CONCEPTS as n, ClivlyEntitiesConfigInput as o, DiscoveredColumnMeta as p, CUSTOM_CONCEPT as r, ClivlyEntityConfig as s, CANONICAL_FIELDS as t, ConfigValidationResult as u, MaterializingConcept as v, entitiesConfigSchema as w, RelationshipsMap as x, RelationshipSpec as y };

package/dist/{entity-config-kusaRiDs.mjs → entity-config-DpHPMFIS.mjs}

@@ -1,40 +1,6 @@
-import { a as projectionSchema, i as identityRefs, t as BASE_REF } from "./projection-BXw_iiw5.mjs";
+import { i as projectionSchema, r as identityRefs, t as BASE_REF } from "./projection-SCNrLJMV.mjs";
+import { i as primaryKeyColumns, n as coversUniqueKey, r as hasRichMeta, t as columnMetaFor } from "./schema-meta-Ac7938mT.mjs";
 import { z } from "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.
@@ -138,7 +104,7 @@ function checkTablesExist(errors, projection, resolver, base) {
 		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`
+				message: `table "${name}" was discovered without column types or unique keys, which a projection needs to prove its id is unique. Redeploy or restart the app so it re-reports its schema (or run \`clivly push-schema\`); if the table is declared by hand as \`{ name, columns }\`, use \`discoverFromDrizzle\` so keys and types come with it.`
 			});
 			ok = false;
 		}
@@ -183,10 +149,27 @@ function checkRefs(errors, projection, resolver, base, basePk) {
 	for (const [field, binding] of Object.entries(projection.fieldBindings)) checkRef(errors, resolver, `${base}.projection.fieldBindings.${field}`, binding.from);
 	for (const ref of identityRefs(projection.identity, basePk)) checkRef(errors, resolver, `${base}.projection.identity`, ref);
 }
+/**
+* Prove that a single-column identity (`column`, or `base_pk` with an
+* explicit column) is actually unique.
+*
+* `coversUniqueKey` fails closed on absent metadata, same as every other
+* check in this file: a column not provably covered by a unique key is
+* rejected, never assumed safe.
+*/
+function checkSingleColumnIdentity(errors, resolver, path, ref) {
+	const table = resolver.tableFor(ref.table);
+	if (!table) return;
+	if (!coversUniqueKey(table, [ref.column])) errors.push({
+		path,
+		message: `identity column "${ref.table}.${ref.column}" is not covered by a unique key of "${table.name}" — pick a column with a unique constraint, or use a composite identity that is`
+	});
+}
 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) {
+	const { identity } = projection;
+	if (identity.kind === "base_pk" && !identity.column) {
 		if (pk.length === 0) {
 			errors.push({
 				path,
@@ -201,9 +184,21 @@ function checkIdentitySafety(errors, projection, resolver, base, baseTable) {
 			});
 			return;
 		}
+		return;
 	}
-	if (projection.identity.kind !== "composite") return;
-	for (const part of projection.identity.parts) {
+	if (identity.kind === "base_pk" && identity.column) {
+		checkSingleColumnIdentity(errors, resolver, path, {
+			table: BASE_REF,
+			column: identity.column
+		});
+		return;
+	}
+	if (identity.kind === "column") {
+		checkSingleColumnIdentity(errors, resolver, path, identity.from);
+		return;
+	}
+	if (identity.kind !== "composite") return;
+	for (const part of identity.parts) {
 		const table = resolver.tableFor(part.table);
 		const meta = table && columnMetaFor(table, part.column);
 		if (!meta) continue;
@@ -245,6 +240,64 @@ function checkFanOut(errors, projection, resolver, base, basePk) {
 	});
 }
 /**
+* One error naming a filter column that is not on the projection's base table,
+* and the base table it would have to be on.
+*/
+function columnOnBase(column, baseTable, path) {
+	if (baseTable?.columns.includes(column)) return [];
+	return [{
+		path,
+		message: `filter column "${column}" does not exist on "${baseTable?.name ?? "the base table"}" — a derived object is filtered by its base table's columns only, so name one of those, or move the condition into a join's \`on\``
+	}];
+}
+/**
+* A derived object's filter is evaluated in the cloud against pushed rows, so
+* it can only name columns of the base table.
+*
+* Every rejected shape here fails *silently* today, which is the whole reason
+* the check exists — a filter that cannot be honoured must error, never quietly
+* return the wrong rows. The three shapes fail in different directions:
+*
+* - `$raw` is opaque SQL meant for the embedded model. The cloud path cannot
+*   evaluate it and passes every row, so the filter is ignored and the object
+*   syncs UNFILTERED.
+* - A joined-table column resolves to nothing on a pushed row, so under a
+*   positive operator (`eq`, `in`) no row matches and the object syncs EMPTY.
+* - The same unresolvable column under a NEGATIVE operator (`ne`, `isNull`,
+*   `notIn`) is the dangerous one: the missing cell reads as null, so the
+*   predicate is true for every row and a filter meant to narrow the sync
+*   ADMITS EVERYTHING. Nobody notices extra rows arriving.
+*
+* Rejecting an unresolvable column closes the last two together.
+*/
+function validateProjectionFilter(filter, projection, schema, base) {
+	if (!filter) return [];
+	const path = `${base}.filter`;
+	if ("$raw" in filter) return [{
+		path,
+		message: "a $raw filter cannot be evaluated against a derived object's rows — it is opaque SQL, so the cloud passes every row through unfiltered. Express it as column conditions on the base table instead"
+	}];
+	const baseTable = schema.find((t) => t.name === projection.baseTable);
+	const errors = [];
+	for (const column of Object.keys(filter)) {
+		if (column.includes(".")) {
+			const [ref, ...rest] = column.split(".");
+			const bare = rest.join(".");
+			if (ref !== "base") {
+				errors.push({
+					path,
+					message: `filter column "${column}" names the join "${ref}", but a derived object is filtered by its base table ("${projection.baseTable}") only — filter on a base column, or move the condition into that join's \`on\``
+				});
+				continue;
+			}
+			errors.push(...columnOnBase(bare, baseTable, path));
+			continue;
+		}
+		errors.push(...columnOnBase(column, baseTable, path));
+	}
+	return errors;
+}
+/**
 * 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.
 */
@@ -517,6 +570,15 @@ function customObjectDeclarations(config) {
 * 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.
+*
+* This is the single derivation of that map, and both consumers depend on it
+* emitting ref tokens. `mappingsToEntitiesConfig` populates a projection
+* entity's required `fields`; the cloud ingest path needs the same map because
+* a projection's persisted `crm_entity_mappings.field_map` is empty by design,
+* so `rowToSourceRow` derives the effective field map from the projection
+* instead. The tokens emitted here are exactly how `fromDrizzleProjection` keys
+* the rows it pushes (`drizzle-projection.ts` `refToken`), so the two line up.
+* Deriving this a second time anywhere would let the copies drift.
 */
 function projectionFields(projection) {
 	const fields = {};
@@ -655,7 +717,7 @@ function validateEntity(v, config, key, entity, schema) {
 		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);
+		for (const error of validateProjectionFilter(entity.filter, entity.projection, schema, base)) v.report(error.path, error.message);
 		return;
 	}
 	validateFields(v, base, entity);
@@ -681,4 +743,4 @@ function validateEntitiesConfig(config, schema) {
 	};
 }
 //#endregion
-export { columnMetaFor as _, MATERIALIZING_CONCEPTS as a, primaryKeyColumns as b, entitiesConfigSchema as c, relationshipSchema as d, relationshipsSchema as f, joinFansOut as g, fanOutJoins as h, ClivlyConfigError as i, filterSchema as l, validateProjection as m, CRM_CONCEPTS as n, customObjectDeclarations as o, validateEntitiesConfig as p, CUSTOM_CONCEPT as r, defineClivlyConfig as s, CANONICAL_FIELDS as t, projectionFields as u, coversUniqueKey as v, hasRichMeta as y };
+export { joinFansOut as _, MATERIALIZING_CONCEPTS as a, entitiesConfigSchema as c, relationshipSchema as d, relationshipsSchema as f, fanOutJoins as g, validateProjectionFilter as h, ClivlyConfigError as i, filterSchema as l, validateProjection as m, CRM_CONCEPTS as n, customObjectDeclarations as o, validateEntitiesConfig as p, CUSTOM_CONCEPT as r, defineClivlyConfig as s, CANONICAL_FIELDS as t, projectionFields as u };

package/dist/entity-config.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-BAaZOIID.cjs");
+const require_entity_config = require("./entity-config-C5jBmG2C.cjs");
 exports.CANONICAL_FIELDS = require_entity_config.CANONICAL_FIELDS;
 exports.CRM_CONCEPTS = require_entity_config.CRM_CONCEPTS;
 exports.CUSTOM_CONCEPT = require_entity_config.CUSTOM_CONCEPT;

package/dist/entity-config.d.cts

@@ -1,2 +1,2 @@
-import { C as defineClivlyConfig, D as relationshipSchema, E as projectionFields, O as relationshipsSchema, S as customObjectDeclarations, T as filterSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipVia, c as ClivlyEntityConfigInput, d as CrmConcept, f as CustomObjectDeclaration, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, k as validateEntitiesConfig, l as ConfigValidationError, m as DiscoveredSchemaTable, n as CRM_CONCEPTS, o as ClivlyEntitiesConfigInput, p as DiscoveredColumnMeta, r as CUSTOM_CONCEPT, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as MaterializingConcept, w as entitiesConfigSchema, x as RelationshipsMap, y as RelationshipSpec } from "./entity-config-buOIVtMM.cjs";
+import { C as defineClivlyConfig, D as relationshipSchema, E as projectionFields, O as relationshipsSchema, S as customObjectDeclarations, T as filterSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipVia, c as ClivlyEntityConfigInput, d as CrmConcept, f as CustomObjectDeclaration, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, k as validateEntitiesConfig, l as ConfigValidationError, m as DiscoveredSchemaTable, n as CRM_CONCEPTS, o as ClivlyEntitiesConfigInput, p as DiscoveredColumnMeta, r as CUSTOM_CONCEPT, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as MaterializingConcept, w as entitiesConfigSchema, x as RelationshipsMap, y as RelationshipSpec } from "./entity-config-DCa785OE.cjs";
 export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntitiesConfigInput, ClivlyEntityConfig, ClivlyEntityConfigInput, ConfigValidationError, ConfigValidationResult, CrmConcept, CustomObjectDeclaration, DiscoveredColumnMeta, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, customObjectDeclarations, defineClivlyConfig, entitiesConfigSchema, filterSchema, projectionFields, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/dist/entity-config.d.mts

@@ -1,2 +1,2 @@
-import { C as defineClivlyConfig, D as relationshipSchema, E as projectionFields, O as relationshipsSchema, S as customObjectDeclarations, T as filterSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipVia, c as ClivlyEntityConfigInput, d as CrmConcept, f as CustomObjectDeclaration, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, k as validateEntitiesConfig, l as ConfigValidationError, m as DiscoveredSchemaTable, n as CRM_CONCEPTS, o as ClivlyEntitiesConfigInput, p as DiscoveredColumnMeta, r as CUSTOM_CONCEPT, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as MaterializingConcept, w as entitiesConfigSchema, x as RelationshipsMap, y as RelationshipSpec } from "./entity-config-buOIVtMM.mjs";
+import { C as defineClivlyConfig, D as relationshipSchema, E as projectionFields, O as relationshipsSchema, S as customObjectDeclarations, T as filterSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipVia, c as ClivlyEntityConfigInput, d as CrmConcept, f as CustomObjectDeclaration, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, k as validateEntitiesConfig, l as ConfigValidationError, m as DiscoveredSchemaTable, n as CRM_CONCEPTS, o as ClivlyEntitiesConfigInput, p as DiscoveredColumnMeta, r as CUSTOM_CONCEPT, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as MaterializingConcept, w as entitiesConfigSchema, x as RelationshipsMap, y as RelationshipSpec } from "./entity-config-DCa785OE.mjs";
 export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntitiesConfigInput, ClivlyEntityConfig, ClivlyEntityConfigInput, ConfigValidationError, ConfigValidationResult, CrmConcept, CustomObjectDeclaration, DiscoveredColumnMeta, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, customObjectDeclarations, defineClivlyConfig, entitiesConfigSchema, filterSchema, projectionFields, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/dist/entity-config.mjs

@@ -1,2 +1,2 @@
-import { a as MATERIALIZING_CONCEPTS, c as entitiesConfigSchema, d as relationshipSchema, f as relationshipsSchema, i as ClivlyConfigError, l as filterSchema, n as CRM_CONCEPTS, o as customObjectDeclarations, p as validateEntitiesConfig, r as CUSTOM_CONCEPT, s as defineClivlyConfig, t as CANONICAL_FIELDS, u as projectionFields } from "./entity-config-kusaRiDs.mjs";
+import { a as MATERIALIZING_CONCEPTS, c as entitiesConfigSchema, d as relationshipSchema, f as relationshipsSchema, i as ClivlyConfigError, l as filterSchema, n as CRM_CONCEPTS, o as customObjectDeclarations, p as validateEntitiesConfig, r as CUSTOM_CONCEPT, s as defineClivlyConfig, t as CANONICAL_FIELDS, u as projectionFields } from "./entity-config-DpHPMFIS.mjs";
 export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, MATERIALIZING_CONCEPTS, customObjectDeclarations, defineClivlyConfig, entitiesConfigSchema, filterSchema, projectionFields, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/dist/entity-heuristics.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-BAaZOIID.cjs");
+const require_entity_config = require("./entity-config-C5jBmG2C.cjs");
 const require_mapping_score = require("./mapping-score.cjs");
 //#region src/entity-heuristics.ts
 const TARGET_CONCEPTS = [
@@ -251,6 +251,38 @@ function matchesConcept(tableName, concept) {
 	if (entry.names.some((name) => candidates.some((candidate) => candidate.includes(name)))) return { exact: false };
 	return null;
 }
+const SENSITIVE_COLUMNS = /* @__PURE__ */ new Set([
+	"password",
+	"password_hash",
+	"passwordhash",
+	"access_token",
+	"accesstoken",
+	"api_key",
+	"apikey",
+	"client_secret",
+	"clientsecret",
+	"encrypted_password",
+	"encryptedpassword",
+	"refresh_token",
+	"refreshtoken",
+	"id_token",
+	"idtoken",
+	"password_digest",
+	"passworddigest",
+	"private_key",
+	"privatekey",
+	"secret",
+	"session_token",
+	"sessiontoken"
+]);
+/**
+* Does this table carry credentials? Such tables are withheld from suggestions
+* and from bulk apply, so one click can never map an auth table into the CRM.
+* They stay manually selectable — an explicit, informed choice is legitimate.
+*/
+function hasSensitiveColumns(columns) {
+	return columns.some((column) => SENSITIVE_COLUMNS.has(column.toLowerCase().replaceAll("-", "_")));
+}
 function metaFor(table, column) {
 	return table.columnsMeta?.find((c) => c.name === column);
 }
@@ -463,6 +495,7 @@ function toFieldMap(scored) {
 }
 //#endregion
 exports.TARGET_CONCEPTS = TARGET_CONCEPTS;
+exports.hasSensitiveColumns = hasSensitiveColumns;
 exports.matchesConcept = matchesConcept;
 exports.requiredFieldsFor = requiredFieldsFor;
 exports.scoreConcepts = scoreConcepts;