@clivly/core 0.9.6 → 0.9.7

package/README.md

@@ -168,6 +168,19 @@ Refer to the base table as `base` and each join by its `key`. Validation is
 `uniqueConstraints` is rejected rather than assumed safe, because identity
 uniqueness cannot be proven without them.
 
+`validateProjection` is also the SDK's guard when it runs an object authored in
+Clivly's dashboard: the definition arrives over the network, and the host
+revalidates it **against the schema the host itself discovered** before any SQL
+is compiled. Because `checkTablesExist` and `checkRefs` bound every table and
+column reference to the schema array you pass in, that call is what limits a
+remote definition to the namespace the developer handed to `discoverFromDrizzle`
+— pass a different schema and you move that boundary.
+
+Since `0.9.7`, **every** identity kind must be provably unique, not just
+composite ones: a single-column identity is rejected unless a unique key covers
+it. The identity is what the sync pages by and what decides which rows survive a
+snapshot, so an unproven one can silently skip and then archive real records.
+
 ### Fan-out
 
 A join that does not cover a unique key of the joined table can match many rows

package/dist/drizzle.cjs

@@ -92,7 +92,7 @@ function buildColumnsMeta(table) {
 * when you import this entry (`@clivly/core/drizzle`); the rest of `@clivly/core`
 * stays dependency-free.
 */
-function discoverFromDrizzle(schema) {
+function discoverFromDrizzle(schema, options = {}) {
 	const tables = [];
 	for (const value of Object.values(schema)) {
 		if (!(0, drizzle_orm.is)(value, drizzle_orm.Table)) continue;
@@ -105,8 +105,16 @@ function discoverFromDrizzle(schema) {
 			...uniqueConstraints === void 0 ? {} : { uniqueConstraints }
 		});
 	}
+	if (tables.length === 0 && !options.allowEmpty) throw new Error(`discoverFromDrizzle: found no Drizzle tables in the object it was given (${describeKeys(schema)}). Import the schema module's tables directly — \`import * as schema from "./db/schema"\` — rather than a barrel or a default export, which can collapse to \`{ default }\` under ESM/CJS interop. Pass { allowEmpty: true } if an empty schema is genuinely intended.`);
 	return tables;
 }
+/** The keys actually present, so the message names what was handed over. */
+function describeKeys(schema) {
+	const keys = Object.keys(schema);
+	if (keys.length === 0) return "it was empty";
+	const shown = keys.slice(0, 5).join(", ");
+	return keys.length > 5 ? `keys: ${shown}, +${keys.length - 5} more` : `keys: ${shown}`;
+}
 //#endregion
 exports.buildColumnsMeta = buildColumnsMeta;
 exports.buildUniqueConstraints = buildUniqueConstraints;

package/dist/drizzle.d.cts

@@ -36,6 +36,8 @@ declare function buildColumnsMeta(table: Table): DiscoveredColumnMeta[];
  * when you import this entry (`@clivly/core/drizzle`); the rest of `@clivly/core`
  * stays dependency-free.
  */
-declare function discoverFromDrizzle(schema: Record<string, unknown>): DiscoveredSchemaTable[];
+declare function discoverFromDrizzle(schema: Record<string, unknown>, options?: {
+  allowEmpty?: boolean;
+}): DiscoveredSchemaTable[];
 //#endregion
 export { buildColumnsMeta, buildUniqueConstraints, discoverFromDrizzle };

package/dist/drizzle.d.mts

@@ -36,6 +36,8 @@ declare function buildColumnsMeta(table: Table): DiscoveredColumnMeta[];
  * when you import this entry (`@clivly/core/drizzle`); the rest of `@clivly/core`
  * stays dependency-free.
  */
-declare function discoverFromDrizzle(schema: Record<string, unknown>): DiscoveredSchemaTable[];
+declare function discoverFromDrizzle(schema: Record<string, unknown>, options?: {
+  allowEmpty?: boolean;
+}): DiscoveredSchemaTable[];
 //#endregion
 export { buildColumnsMeta, buildUniqueConstraints, discoverFromDrizzle };

package/dist/drizzle.mjs

@@ -91,7 +91,7 @@ function buildColumnsMeta(table) {
 * when you import this entry (`@clivly/core/drizzle`); the rest of `@clivly/core`
 * stays dependency-free.
 */
-function discoverFromDrizzle(schema) {
+function discoverFromDrizzle(schema, options = {}) {
 	const tables = [];
 	for (const value of Object.values(schema)) {
 		if (!is(value, Table)) continue;
@@ -104,7 +104,15 @@ function discoverFromDrizzle(schema) {
 			...uniqueConstraints === void 0 ? {} : { uniqueConstraints }
 		});
 	}
+	if (tables.length === 0 && !options.allowEmpty) throw new Error(`discoverFromDrizzle: found no Drizzle tables in the object it was given (${describeKeys(schema)}). Import the schema module's tables directly — \`import * as schema from "./db/schema"\` — rather than a barrel or a default export, which can collapse to \`{ default }\` under ESM/CJS interop. Pass { allowEmpty: true } if an empty schema is genuinely intended.`);
 	return tables;
 }
+/** The keys actually present, so the message names what was handed over. */
+function describeKeys(schema) {
+	const keys = Object.keys(schema);
+	if (keys.length === 0) return "it was empty";
+	const shown = keys.slice(0, 5).join(", ");
+	return keys.length > 5 ? `keys: ${shown}, +${keys.length - 5} more` : `keys: ${shown}`;
+}
 //#endregion
 export { buildColumnsMeta, buildUniqueConstraints, discoverFromDrizzle };

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

@@ -138,7 +138,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 +183,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 (!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 +218,21 @@ 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 (identity.kind === "column") {
+		checkSingleColumnIdentity(errors, resolver, path, identity.from);
+		return;
 	}
-	if (projection.identity.kind !== "composite") return;
-	for (const part of projection.identity.parts) {
+	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;

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

@@ -138,7 +138,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 +183,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 +218,21 @@ function checkIdentitySafety(errors, projection, resolver, base, baseTable) {
 			});
 			return;
 		}
+		return;
+	}
+	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 (projection.identity.kind !== "composite") return;
-	for (const part of projection.identity.parts) {
+	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;

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-25v_udeY.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.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-DwGXbUo_.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-25v_udeY.cjs");
 const require_mapping_score = require("./mapping-score.cjs");
 //#region src/entity-heuristics.ts
 const TARGET_CONCEPTS = [

package/dist/entity-heuristics.mjs

@@ -1,4 +1,4 @@
-import { a as MATERIALIZING_CONCEPTS } from "./entity-config-kusaRiDs.mjs";
+import { a as MATERIALIZING_CONCEPTS } from "./entity-config-DwGXbUo_.mjs";
 import { CONCEPT_TIERS, FIELD_TIERS, RELATIONSHIP_TIERS, W, isAmbiguous, isNumericLike, isTextLike, isTimestampLike, tierFor } from "./mapping-score.mjs";
 //#region src/entity-heuristics.ts
 const TARGET_CONCEPTS = [

package/dist/index.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_auth_adapter = require("./auth-adapter.cjs");
 const require_projection = require("./projection-OJYCYmS_.cjs");
-const require_entity_config = require("./entity-config-BAaZOIID.cjs");
+const require_entity_config = require("./entity-config-25v_udeY.cjs");
 const require_mapping_form = require("./mapping-form.cjs");
 const require_mappings_config = require("./mappings-config.cjs");
 const require_view_compiler = require("./view-compiler-D30HNRnA.cjs");

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { authCustom } from "./auth-adapter.mjs";
 import { a as projectionSchema, i as identityRefs, n as PROJECTION_KEY_MESSAGE, r as PROJECTION_KEY_PATTERN, t as BASE_REF } from "./projection-BXw_iiw5.mjs";
-import { _ as columnMetaFor, a as MATERIALIZING_CONCEPTS, b as primaryKeyColumns, c as entitiesConfigSchema, d as relationshipSchema, f as relationshipsSchema, g as joinFansOut, h as fanOutJoins, i as ClivlyConfigError, l as filterSchema, m as validateProjection, n as CRM_CONCEPTS, p as validateEntitiesConfig, s as defineClivlyConfig, t as CANONICAL_FIELDS, v as coversUniqueKey, y as hasRichMeta } from "./entity-config-kusaRiDs.mjs";
+import { _ as columnMetaFor, a as MATERIALIZING_CONCEPTS, b as primaryKeyColumns, c as entitiesConfigSchema, d as relationshipSchema, f as relationshipsSchema, g as joinFansOut, h as fanOutJoins, i as ClivlyConfigError, l as filterSchema, m as validateProjection, n as CRM_CONCEPTS, p as validateEntitiesConfig, s as defineClivlyConfig, t as CANONICAL_FIELDS, v as coversUniqueKey, y as hasRichMeta } from "./entity-config-DwGXbUo_.mjs";
 import { buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
 import { mappingsToEntitiesConfig } from "./mappings-config.mjs";
 import { c as compileProjectionIdentity, d as compileProjectionSelect, f as quoteIdent, i as explainEntitiesConfig, l as compileProjectionJoins, n as compileEntityView, o as PREVIEW_MAX_ROWS, r as compileEntityViews, s as compileProjectionFrom, t as DEFAULT_VIEW_PREFIX, u as compileProjectionPreview } from "./view-compiler-u3GGRgnv.mjs";

package/dist/mappings-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-25v_udeY.cjs");
 //#region src/mappings-config.ts
 const RESERVED_FIELD = "id";
 /**

package/dist/mappings-config.mjs

@@ -1,4 +1,4 @@
-import { t as CANONICAL_FIELDS } from "./entity-config-kusaRiDs.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-DwGXbUo_.mjs";
 //#region src/mappings-config.ts
 const RESERVED_FIELD = "id";
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/core",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "private": false,
   "type": "module",
   "description": "ORM/auth-agnostic CRM adapter contracts and shared domain types for Clivly.",