@clivly/core 0.9.5 → 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
@@ -188,10 +201,18 @@ every rule is a pure function of draft + schema:
 | Helper | Purpose |
 | --- | --- |
 | `emptyProjectionDraft(baseTable)` | A blank draft |
+| `addDraftJoin(draft, joinTable, schema)` | Add a join, keyed uniquely and pre-filled from foreign-key metadata |
+| `removeDraftJoin(draft, joinKey)` | Remove a join **and** every binding and identity that addressed it — left behind they fail validation as "unknown ref table", blaming the field for the join's removal |
+| `draftRefOptions(draft, schema)` | The tables and columns a field or identity may currently read from, in ref order |
 | `suggestJoinConditions(base, joinTable, schema, key)` | Pre-fill a join's `ON` from foreign-key metadata |
 | `draftToProjection(draft)` | `ProjectionMapping`, or `null` while incomplete |
-| `draftErrors(draft, schema)` | Validation errors for the current draft |
-| `describeCardinality(draft, schema)` | Per-join `{ joinKey, fansOut }` for inline hints |
+| `draftErrors(draft, schema)` | Validation errors, one per cause, each anchored to the section that owns it (`projection.entityKey`, `projection.joins`, …) |
+| `describeCardinality(draft, schema)` | Per-join `{ joinKey, fansOut }` for inline hints. Answered from the joins alone, so the warning arrives while the identity is still being chosen |
+
+`compileProjectionPreview(projection, limit)` compiles the same object to a
+capped, read-only `SELECT` — used by both sides of the dashboard's preview, so
+an embedded org and a cloud org's host app cannot disagree about what the user
+is being shown.
 
 Full guide, including how to choose an identity and the current limits:
 [`docs/guides/derived-objects.md`](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/derived-objects.md).

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-ZSv3XuW_.cjs → entity-config-25v_udeY.cjs}

@@ -1,4 +1,4 @@
-const require_projection = require("./projection-DFgCoyZl.cjs");
+const require_projection = require("./projection-OJYCYmS_.cjs");
 let zod = require("zod");
 //#region src/schema-meta.ts
 /**
@@ -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-Dt_KfgRl.mjs → entity-config-DwGXbUo_.mjs}

@@ -1,4 +1,4 @@
-import { i as projectionSchema, r as identityRefs, t as BASE_REF } from "./projection-SCNrLJMV.mjs";
+import { a as projectionSchema, i as identityRefs, t as BASE_REF } from "./projection-BXw_iiw5.mjs";
 import { z } from "zod";
 //#region src/schema-meta.ts
 /**
@@ -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-ZSv3XuW_.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-Dt_KfgRl.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-ZSv3XuW_.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-Dt_KfgRl.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,10 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_auth_adapter = require("./auth-adapter.cjs");
-const require_projection = require("./projection-DFgCoyZl.cjs");
-const require_entity_config = require("./entity-config-ZSv3XuW_.cjs");
+const require_projection = require("./projection-OJYCYmS_.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-DTGSwTcz.cjs");
+const require_view_compiler = require("./view-compiler-D30HNRnA.cjs");
 const require_sync_engine = require("./sync-engine.cjs");
 //#region src/projection-draft.ts
 function emptyProjectionDraft(baseTable) {
@@ -37,6 +37,78 @@ function suggestJoinConditions(baseTable, joinTable, schema, joinKey) {
 	});
 	return conditions;
 }
+/**
+* Add a join on `joinTable`, keyed and pre-filled.
+*
+* The key is the table's own name where that is free, because it is what the
+* user already calls the table; a collision falls back to `_2`, `_3` and so on.
+* Uniqueness is not cosmetic — the key is the SQL alias and the name every ref
+* addresses the table by, so two joins sharing one would make every ref
+* ambiguous. `base` is reserved for the base table and can never be taken.
+*/
+function addDraftJoin(draft, joinTable, schema) {
+	const taken = /* @__PURE__ */ new Set([require_projection.BASE_REF, ...draft.joins.map((j) => j.key)]);
+	let key = joinTable;
+	let suffix = 2;
+	while (taken.has(key)) {
+		key = `${joinTable}_${suffix}`;
+		suffix += 1;
+	}
+	return {
+		...draft,
+		joins: [...draft.joins, {
+			key,
+			table: joinTable,
+			type: "left",
+			on: suggestJoinConditions(draft.baseTable, joinTable, schema, key)
+		}]
+	};
+}
+/**
+* Remove a join, and everything that addressed it.
+*
+* Refs to a removed join are refs to a table the projection no longer declares.
+* Left in place they fail validation as "unknown ref table", which blames the
+* field — or, worse, the identity — for the join's removal. Identity falls back
+* to the base primary key, the same default a new draft starts from.
+*/
+function removeDraftJoin(draft, joinKey) {
+	const fieldBindings = Object.fromEntries(Object.entries(draft.fieldBindings).filter(([, binding]) => binding.from.table !== joinKey));
+	const identityDependsOnJoin = require_projection.identityRefs(draft.identity, "").some((ref) => ref.table === joinKey);
+	return {
+		...draft,
+		joins: draft.joins.filter((join) => join.key !== joinKey),
+		fieldBindings,
+		identity: identityDependsOnJoin ? { kind: "base_pk" } : draft.identity
+	};
+}
+/**
+* Every table a field or identity may currently read from, in ref order: the
+* base table first, then each join.
+*
+* Returns [] when the base table is not in the discovered schema — there is
+* nothing truthful to offer, and inventing columns would let someone build a
+* projection that cannot compile.
+*/
+function draftRefOptions(draft, schema) {
+	const byName = new Map(schema.map((table) => [table.name, table]));
+	const base = byName.get(draft.baseTable);
+	if (!base) return [];
+	const options = [{
+		ref: require_projection.BASE_REF,
+		label: `${base.name} (${require_projection.BASE_REF})`,
+		columns: base.columns
+	}];
+	for (const join of draft.joins) {
+		const table = byName.get(join.table);
+		if (table) options.push({
+			ref: join.key,
+			label: `${table.name} (${join.key})`,
+			columns: table.columns
+		});
+	}
+	return options;
+}
 /** A draft becomes a projection once it has a valid key and ≥1 binding. */
 function draftToProjection(draft) {
 	if (!require_projection.PROJECTION_KEY_PATTERN.test(draft.entityKey)) return null;
@@ -51,18 +123,90 @@ function draftToProjection(draft) {
 		identity: draft.identity
 	};
 }
+const PROBE_KEY = "draft";
+/**
+* A draft rendered as a projection so the semantic checks can run against it
+* while it is being written, not only once it is finished.
+*
+* `entityKey` is stood in for rather than taken from the draft: it is the one
+* field `validateProjection` never looks at, and a half-typed key would
+* otherwise have to be valid before any join or identity could be checked. The
+* missing or malformed key is reported separately, by `draftErrors`.
+*/
+function probeProjection(draft) {
+	return {
+		version: 1,
+		kind: "projection",
+		entityKey: PROBE_KEY,
+		baseTable: draft.baseTable,
+		joins: draft.joins,
+		fieldBindings: draft.fieldBindings,
+		identity: draft.identity
+	};
+}
+/**
+* `validateProjection` appends its own `projection.` segment to the base path it
+* is given, because in a config the base is the entity that owns the projection
+* (`entities.accounts` → `entities.accounts.projection.identity`). A draft has
+* no owning entity, so passing "projection" as the base produced
+* `projection.projection.identity` — a path no caller could match against, and
+* the reason `draftErrors` was only ever consumed as a flat list of messages.
+*
+* Passing an empty base and dropping the leading separator leaves one
+* convention: every path here starts `projection.` exactly once, whether it came
+* from this module or from the validator.
+*/
+function semanticErrors(draft, schema) {
+	return require_entity_config.validateProjection(probeProjection(draft), schema, "").map((error) => ({
+		...error,
+		path: error.path.startsWith(".") ? error.path.slice(1) : error.path
+	}));
+}
+/**
+* Every reason this draft cannot be saved, one per cause and each anchored to
+* the section that owns it.
+*
+* One lumped "Name the object and map a field." was all this used to return for
+* an incomplete draft, at the bare path "projection". Two consequences, both
+* bad: a builder had nowhere to attach the message, and — because it returned
+* before validating — a fanning join under a `base_pk` identity stayed silent
+* until the draft was otherwise complete, which is well after the point where
+* the user chose the join.
+*/
 function draftErrors(draft, schema) {
-	const projection = draftToProjection(draft);
-	if (!projection) return [{
-		path: "projection",
-		message: "Name the object and map a field."
-	}];
-	return require_entity_config.validateProjection(projection, schema, "projection");
+	const errors = [];
+	if (draft.entityKey === "") errors.push({
+		path: "projection.entityKey",
+		message: "Key is required."
+	});
+	else if (!require_projection.PROJECTION_KEY_PATTERN.test(draft.entityKey)) errors.push({
+		path: "projection.entityKey",
+		message: `Key ${require_projection.PROJECTION_KEY_MESSAGE}.`
+	});
+	if (Object.keys(draft.fieldBindings).length === 0) errors.push({
+		path: "projection.fieldBindings",
+		message: "Map at least one field."
+	});
+	if (draft.baseTable === "") {
+		errors.push({
+			path: "projection.baseTable",
+			message: "Pick a base table."
+		});
+		return errors;
+	}
+	errors.push(...semanticErrors(draft, schema));
+	return errors;
 }
-/** Per-join fan-out, for the builder's inline cardinality hints. */
+/**
+* Per-join fan-out, for the builder's inline cardinality hints.
+*
+* Answered from the joins alone. Joins are chosen before the key and the fields
+* are filled in, and a fan-out warning is precisely what should steer the
+* identity choice while it is being made — requiring a complete draft put the
+* hint after the decision it exists to inform.
+*/
 function describeCardinality(draft, schema) {
-	const projection = draftToProjection(draft);
-	if (!projection) return [];
+	const projection = probeProjection(draft);
 	const tablesByName = new Map(schema.map((t) => [t.name, t]));
 	const fanning = new Set(require_entity_config.fanOutJoins(projection, tablesByName).map((j) => j.key));
 	return projection.joins.map((join) => ({
@@ -77,6 +221,8 @@ exports.CRM_CONCEPTS = require_entity_config.CRM_CONCEPTS;
 exports.ClivlyConfigError = require_entity_config.ClivlyConfigError;
 exports.DEFAULT_VIEW_PREFIX = require_view_compiler.DEFAULT_VIEW_PREFIX;
 exports.MATERIALIZING_CONCEPTS = require_entity_config.MATERIALIZING_CONCEPTS;
+exports.PREVIEW_MAX_ROWS = require_view_compiler.PREVIEW_MAX_ROWS;
+exports.addDraftJoin = addDraftJoin;
 exports.authCustom = require_auth_adapter.authCustom;
 exports.buildFilterFromDiscriminator = require_mapping_form.buildFilterFromDiscriminator;
 exports.buildRelationships = require_mapping_form.buildRelationships;
@@ -86,10 +232,13 @@ exports.compileEntityViews = require_view_compiler.compileEntityViews;
 exports.compileProjectionFrom = require_view_compiler.compileProjectionFrom;
 exports.compileProjectionIdentity = require_view_compiler.compileProjectionIdentity;
 exports.compileProjectionJoins = require_view_compiler.compileProjectionJoins;
+exports.compileProjectionPreview = require_view_compiler.compileProjectionPreview;
+exports.compileProjectionSelect = require_view_compiler.compileProjectionSelect;
 exports.coversUniqueKey = require_entity_config.coversUniqueKey;
 exports.defineClivlyConfig = require_entity_config.defineClivlyConfig;
 exports.describeCardinality = describeCardinality;
 exports.draftErrors = draftErrors;
+exports.draftRefOptions = draftRefOptions;
 exports.draftToProjection = draftToProjection;
 exports.emptyProjectionDraft = emptyProjectionDraft;
 exports.entitiesConfigSchema = require_entity_config.entitiesConfigSchema;
@@ -107,6 +256,7 @@ exports.reconcile = require_sync_engine.reconcile;
 exports.relationshipSchema = require_entity_config.relationshipSchema;
 exports.relationshipViaSignature = require_mapping_form.relationshipViaSignature;
 exports.relationshipsSchema = require_entity_config.relationshipsSchema;
+exports.removeDraftJoin = removeDraftJoin;
 exports.runSync = require_sync_engine.runSync;
 exports.suggestJoinConditions = suggestJoinConditions;
 exports.validateEntitiesConfig = require_entity_config.validateEntitiesConfig;

package/dist/index.d.cts

@@ -35,10 +35,62 @@ declare function emptyProjectionDraft(baseTable: string): ProjectionDraft;
  * Returns [] when no FK relates them — the user then picks manually.
  */
 declare function suggestJoinConditions(baseTable: string, joinTable: string, schema: DiscoveredSchemaTable[], joinKey: string): ProjectionJoin["on"];
+/**
+ * Add a join on `joinTable`, keyed and pre-filled.
+ *
+ * The key is the table's own name where that is free, because it is what the
+ * user already calls the table; a collision falls back to `_2`, `_3` and so on.
+ * Uniqueness is not cosmetic — the key is the SQL alias and the name every ref
+ * addresses the table by, so two joins sharing one would make every ref
+ * ambiguous. `base` is reserved for the base table and can never be taken.
+ */
+declare function addDraftJoin(draft: ProjectionDraft, joinTable: string, schema: DiscoveredSchemaTable[]): ProjectionDraft;
+/**
+ * Remove a join, and everything that addressed it.
+ *
+ * Refs to a removed join are refs to a table the projection no longer declares.
+ * Left in place they fail validation as "unknown ref table", which blames the
+ * field — or, worse, the identity — for the join's removal. Identity falls back
+ * to the base primary key, the same default a new draft starts from.
+ */
+declare function removeDraftJoin(draft: ProjectionDraft, joinKey: string): ProjectionDraft;
+/** One selectable table in the builder's column pickers. */
+interface DraftRefOption {
+  columns: string[];
+  label: string;
+  ref: string;
+}
+/**
+ * Every table a field or identity may currently read from, in ref order: the
+ * base table first, then each join.
+ *
+ * Returns [] when the base table is not in the discovered schema — there is
+ * nothing truthful to offer, and inventing columns would let someone build a
+ * projection that cannot compile.
+ */
+declare function draftRefOptions(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): DraftRefOption[];
 /** A draft becomes a projection once it has a valid key and ≥1 binding. */
 declare function draftToProjection(draft: ProjectionDraft): ProjectionMapping | null;
+/**
+ * Every reason this draft cannot be saved, one per cause and each anchored to
+ * the section that owns it.
+ *
+ * One lumped "Name the object and map a field." was all this used to return for
+ * an incomplete draft, at the bare path "projection". Two consequences, both
+ * bad: a builder had nowhere to attach the message, and — because it returned
+ * before validating — a fanning join under a `base_pk` identity stayed silent
+ * until the draft was otherwise complete, which is well after the point where
+ * the user chose the join.
+ */
 declare function draftErrors(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): ConfigValidationError[];
-/** Per-join fan-out, for the builder's inline cardinality hints. */
+/**
+ * Per-join fan-out, for the builder's inline cardinality hints.
+ *
+ * Answered from the joins alone. Joins are chosen before the key and the fields
+ * are filled in, and a fan-out warning is precisely what should steer the
+ * identity choice while it is being made — requiring a complete draft put the
+ * hint after the decision it exists to inform.
+ */
 declare function describeCardinality(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): Array<{
   fansOut: boolean;
   joinKey: string;
@@ -68,9 +120,37 @@ declare function quoteIdent(name: string): string;
  * a pushed row's `id` identical to the one the view would have produced.
  */
 declare function compileProjectionIdentity(projection: ProjectionMapping, basePkColumn: string): string;
+declare function compileProjectionSelect(projection: ProjectionMapping, basePkColumn: string): {
+  columns: string[];
+  selectItems: string[];
+};
 declare function compileProjectionJoins(projection: ProjectionMapping): string[];
 /** `FROM <baseTable> AS "base"` — the alias every ref resolves against. */
 declare function compileProjectionFrom(projection: ProjectionMapping): string;
+/**
+ * Hard ceiling on preview rows, regardless of what a caller asks for.
+ *
+ * A preview runs against a production database from a button a user can click
+ * as often as they like, so the cap belongs beside the query rather than in
+ * whichever caller happens to be passing a limit today.
+ */
+declare const PREVIEW_MAX_ROWS = 50;
+/**
+ * One SELECT reading a few rows through an UNSAVED projection, for the derived
+ * object builder's preview.
+ *
+ * Lives here, beside the view compiler, because both sides of the round trip
+ * need the identical statement: an embedded org runs it against its own
+ * database from `@clivly.com/api`, and a cloud org's host app runs it from
+ * `@clivly/sdk`. Two copies would be free to disagree about what the user is
+ * being shown, which is the whole value of a preview.
+ *
+ * Columns are aliased by FIELD NAME, not by ref token. That is the deliberate
+ * difference from the push source, which aliases by token because cloud ingest
+ * reads `row[token]`; a preview is read by a person, in a table whose headers
+ * are the field names they just typed.
+ */
+declare function compileProjectionPreview(projection: ProjectionMapping, limit: number): string;
 //#endregion
 //#region src/projection-validate.d.ts
 /**
@@ -105,4 +185,4 @@ declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]
 /** Is this table's payload rich enough to validate a projection against? */
 declare function hasRichMeta(table: DiscoveredSchemaTable): boolean;
 //#endregion
-export { type Activity, type ActivityType, BASE_REF, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, type ConnectionLiveness, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredColumnMeta, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, type IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, type PersistAction, type ProjectionDraft, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type StepId, type StepProblem, type StepState, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };
+export { type Activity, type ActivityType, BASE_REF, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, type ConnectionLiveness, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredColumnMeta, type DiscoveredSchemaTable, type DraftRefOption, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, type IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, PREVIEW_MAX_ROWS, type PersistAction, type ProjectionDraft, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type StepId, type StepProblem, type StepState, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, addDraftJoin, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, compileProjectionSelect, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftRefOptions, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, removeDraftJoin, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };

package/dist/index.d.mts

@@ -35,10 +35,62 @@ declare function emptyProjectionDraft(baseTable: string): ProjectionDraft;
  * Returns [] when no FK relates them — the user then picks manually.
  */
 declare function suggestJoinConditions(baseTable: string, joinTable: string, schema: DiscoveredSchemaTable[], joinKey: string): ProjectionJoin["on"];
+/**
+ * Add a join on `joinTable`, keyed and pre-filled.
+ *
+ * The key is the table's own name where that is free, because it is what the
+ * user already calls the table; a collision falls back to `_2`, `_3` and so on.
+ * Uniqueness is not cosmetic — the key is the SQL alias and the name every ref
+ * addresses the table by, so two joins sharing one would make every ref
+ * ambiguous. `base` is reserved for the base table and can never be taken.
+ */
+declare function addDraftJoin(draft: ProjectionDraft, joinTable: string, schema: DiscoveredSchemaTable[]): ProjectionDraft;
+/**
+ * Remove a join, and everything that addressed it.
+ *
+ * Refs to a removed join are refs to a table the projection no longer declares.
+ * Left in place they fail validation as "unknown ref table", which blames the
+ * field — or, worse, the identity — for the join's removal. Identity falls back
+ * to the base primary key, the same default a new draft starts from.
+ */
+declare function removeDraftJoin(draft: ProjectionDraft, joinKey: string): ProjectionDraft;
+/** One selectable table in the builder's column pickers. */
+interface DraftRefOption {
+  columns: string[];
+  label: string;
+  ref: string;
+}
+/**
+ * Every table a field or identity may currently read from, in ref order: the
+ * base table first, then each join.
+ *
+ * Returns [] when the base table is not in the discovered schema — there is
+ * nothing truthful to offer, and inventing columns would let someone build a
+ * projection that cannot compile.
+ */
+declare function draftRefOptions(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): DraftRefOption[];
 /** A draft becomes a projection once it has a valid key and ≥1 binding. */
 declare function draftToProjection(draft: ProjectionDraft): ProjectionMapping | null;
+/**
+ * Every reason this draft cannot be saved, one per cause and each anchored to
+ * the section that owns it.
+ *
+ * One lumped "Name the object and map a field." was all this used to return for
+ * an incomplete draft, at the bare path "projection". Two consequences, both
+ * bad: a builder had nowhere to attach the message, and — because it returned
+ * before validating — a fanning join under a `base_pk` identity stayed silent
+ * until the draft was otherwise complete, which is well after the point where
+ * the user chose the join.
+ */
 declare function draftErrors(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): ConfigValidationError[];
-/** Per-join fan-out, for the builder's inline cardinality hints. */
+/**
+ * Per-join fan-out, for the builder's inline cardinality hints.
+ *
+ * Answered from the joins alone. Joins are chosen before the key and the fields
+ * are filled in, and a fan-out warning is precisely what should steer the
+ * identity choice while it is being made — requiring a complete draft put the
+ * hint after the decision it exists to inform.
+ */
 declare function describeCardinality(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): Array<{
   fansOut: boolean;
   joinKey: string;
@@ -68,9 +120,37 @@ declare function quoteIdent(name: string): string;
  * a pushed row's `id` identical to the one the view would have produced.
  */
 declare function compileProjectionIdentity(projection: ProjectionMapping, basePkColumn: string): string;
+declare function compileProjectionSelect(projection: ProjectionMapping, basePkColumn: string): {
+  columns: string[];
+  selectItems: string[];
+};
 declare function compileProjectionJoins(projection: ProjectionMapping): string[];
 /** `FROM <baseTable> AS "base"` — the alias every ref resolves against. */
 declare function compileProjectionFrom(projection: ProjectionMapping): string;
+/**
+ * Hard ceiling on preview rows, regardless of what a caller asks for.
+ *
+ * A preview runs against a production database from a button a user can click
+ * as often as they like, so the cap belongs beside the query rather than in
+ * whichever caller happens to be passing a limit today.
+ */
+declare const PREVIEW_MAX_ROWS = 50;
+/**
+ * One SELECT reading a few rows through an UNSAVED projection, for the derived
+ * object builder's preview.
+ *
+ * Lives here, beside the view compiler, because both sides of the round trip
+ * need the identical statement: an embedded org runs it against its own
+ * database from `@clivly.com/api`, and a cloud org's host app runs it from
+ * `@clivly/sdk`. Two copies would be free to disagree about what the user is
+ * being shown, which is the whole value of a preview.
+ *
+ * Columns are aliased by FIELD NAME, not by ref token. That is the deliberate
+ * difference from the push source, which aliases by token because cloud ingest
+ * reads `row[token]`; a preview is read by a person, in a table whose headers
+ * are the field names they just typed.
+ */
+declare function compileProjectionPreview(projection: ProjectionMapping, limit: number): string;
 //#endregion
 //#region src/projection-validate.d.ts
 /**
@@ -105,4 +185,4 @@ declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]
 /** Is this table's payload rich enough to validate a projection against? */
 declare function hasRichMeta(table: DiscoveredSchemaTable): boolean;
 //#endregion
-export { type Activity, type ActivityType, BASE_REF, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, type ConnectionLiveness, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredColumnMeta, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, type IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, type PersistAction, type ProjectionDraft, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type StepId, type StepProblem, type StepState, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };
+export { type Activity, type ActivityType, BASE_REF, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, type ConnectionLiveness, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredColumnMeta, type DiscoveredSchemaTable, type DraftRefOption, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, type IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, PREVIEW_MAX_ROWS, type PersistAction, type ProjectionDraft, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type StepId, type StepProblem, type StepState, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, addDraftJoin, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, compileProjectionSelect, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftRefOptions, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, removeDraftJoin, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };

package/dist/index.mjs

@@ -1,9 +1,9 @@
 import { authCustom } from "./auth-adapter.mjs";
-import { i as projectionSchema, n as PROJECTION_KEY_PATTERN, r as identityRefs, t as BASE_REF } from "./projection-SCNrLJMV.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-Dt_KfgRl.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-DwGXbUo_.mjs";
 import { buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
 import { mappingsToEntitiesConfig } from "./mappings-config.mjs";
-import { c as compileProjectionJoins, i as explainEntitiesConfig, l as quoteIdent, n as compileEntityView, o as compileProjectionFrom, r as compileEntityViews, s as compileProjectionIdentity, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-DjzRXiAJ.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";
 import { reconcile, runSync } from "./sync-engine.mjs";
 //#region src/projection-draft.ts
 function emptyProjectionDraft(baseTable) {
@@ -36,6 +36,78 @@ function suggestJoinConditions(baseTable, joinTable, schema, joinKey) {
 	});
 	return conditions;
 }
+/**
+* Add a join on `joinTable`, keyed and pre-filled.
+*
+* The key is the table's own name where that is free, because it is what the
+* user already calls the table; a collision falls back to `_2`, `_3` and so on.
+* Uniqueness is not cosmetic — the key is the SQL alias and the name every ref
+* addresses the table by, so two joins sharing one would make every ref
+* ambiguous. `base` is reserved for the base table and can never be taken.
+*/
+function addDraftJoin(draft, joinTable, schema) {
+	const taken = /* @__PURE__ */ new Set([BASE_REF, ...draft.joins.map((j) => j.key)]);
+	let key = joinTable;
+	let suffix = 2;
+	while (taken.has(key)) {
+		key = `${joinTable}_${suffix}`;
+		suffix += 1;
+	}
+	return {
+		...draft,
+		joins: [...draft.joins, {
+			key,
+			table: joinTable,
+			type: "left",
+			on: suggestJoinConditions(draft.baseTable, joinTable, schema, key)
+		}]
+	};
+}
+/**
+* Remove a join, and everything that addressed it.
+*
+* Refs to a removed join are refs to a table the projection no longer declares.
+* Left in place they fail validation as "unknown ref table", which blames the
+* field — or, worse, the identity — for the join's removal. Identity falls back
+* to the base primary key, the same default a new draft starts from.
+*/
+function removeDraftJoin(draft, joinKey) {
+	const fieldBindings = Object.fromEntries(Object.entries(draft.fieldBindings).filter(([, binding]) => binding.from.table !== joinKey));
+	const identityDependsOnJoin = identityRefs(draft.identity, "").some((ref) => ref.table === joinKey);
+	return {
+		...draft,
+		joins: draft.joins.filter((join) => join.key !== joinKey),
+		fieldBindings,
+		identity: identityDependsOnJoin ? { kind: "base_pk" } : draft.identity
+	};
+}
+/**
+* Every table a field or identity may currently read from, in ref order: the
+* base table first, then each join.
+*
+* Returns [] when the base table is not in the discovered schema — there is
+* nothing truthful to offer, and inventing columns would let someone build a
+* projection that cannot compile.
+*/
+function draftRefOptions(draft, schema) {
+	const byName = new Map(schema.map((table) => [table.name, table]));
+	const base = byName.get(draft.baseTable);
+	if (!base) return [];
+	const options = [{
+		ref: BASE_REF,
+		label: `${base.name} (${BASE_REF})`,
+		columns: base.columns
+	}];
+	for (const join of draft.joins) {
+		const table = byName.get(join.table);
+		if (table) options.push({
+			ref: join.key,
+			label: `${table.name} (${join.key})`,
+			columns: table.columns
+		});
+	}
+	return options;
+}
 /** A draft becomes a projection once it has a valid key and ≥1 binding. */
 function draftToProjection(draft) {
 	if (!PROJECTION_KEY_PATTERN.test(draft.entityKey)) return null;
@@ -50,18 +122,90 @@ function draftToProjection(draft) {
 		identity: draft.identity
 	};
 }
+const PROBE_KEY = "draft";
+/**
+* A draft rendered as a projection so the semantic checks can run against it
+* while it is being written, not only once it is finished.
+*
+* `entityKey` is stood in for rather than taken from the draft: it is the one
+* field `validateProjection` never looks at, and a half-typed key would
+* otherwise have to be valid before any join or identity could be checked. The
+* missing or malformed key is reported separately, by `draftErrors`.
+*/
+function probeProjection(draft) {
+	return {
+		version: 1,
+		kind: "projection",
+		entityKey: PROBE_KEY,
+		baseTable: draft.baseTable,
+		joins: draft.joins,
+		fieldBindings: draft.fieldBindings,
+		identity: draft.identity
+	};
+}
+/**
+* `validateProjection` appends its own `projection.` segment to the base path it
+* is given, because in a config the base is the entity that owns the projection
+* (`entities.accounts` → `entities.accounts.projection.identity`). A draft has
+* no owning entity, so passing "projection" as the base produced
+* `projection.projection.identity` — a path no caller could match against, and
+* the reason `draftErrors` was only ever consumed as a flat list of messages.
+*
+* Passing an empty base and dropping the leading separator leaves one
+* convention: every path here starts `projection.` exactly once, whether it came
+* from this module or from the validator.
+*/
+function semanticErrors(draft, schema) {
+	return validateProjection(probeProjection(draft), schema, "").map((error) => ({
+		...error,
+		path: error.path.startsWith(".") ? error.path.slice(1) : error.path
+	}));
+}
+/**
+* Every reason this draft cannot be saved, one per cause and each anchored to
+* the section that owns it.
+*
+* One lumped "Name the object and map a field." was all this used to return for
+* an incomplete draft, at the bare path "projection". Two consequences, both
+* bad: a builder had nowhere to attach the message, and — because it returned
+* before validating — a fanning join under a `base_pk` identity stayed silent
+* until the draft was otherwise complete, which is well after the point where
+* the user chose the join.
+*/
 function draftErrors(draft, schema) {
-	const projection = draftToProjection(draft);
-	if (!projection) return [{
-		path: "projection",
-		message: "Name the object and map a field."
-	}];
-	return validateProjection(projection, schema, "projection");
+	const errors = [];
+	if (draft.entityKey === "") errors.push({
+		path: "projection.entityKey",
+		message: "Key is required."
+	});
+	else if (!PROJECTION_KEY_PATTERN.test(draft.entityKey)) errors.push({
+		path: "projection.entityKey",
+		message: `Key ${PROJECTION_KEY_MESSAGE}.`
+	});
+	if (Object.keys(draft.fieldBindings).length === 0) errors.push({
+		path: "projection.fieldBindings",
+		message: "Map at least one field."
+	});
+	if (draft.baseTable === "") {
+		errors.push({
+			path: "projection.baseTable",
+			message: "Pick a base table."
+		});
+		return errors;
+	}
+	errors.push(...semanticErrors(draft, schema));
+	return errors;
 }
-/** Per-join fan-out, for the builder's inline cardinality hints. */
+/**
+* Per-join fan-out, for the builder's inline cardinality hints.
+*
+* Answered from the joins alone. Joins are chosen before the key and the fields
+* are filled in, and a fan-out warning is precisely what should steer the
+* identity choice while it is being made — requiring a complete draft put the
+* hint after the decision it exists to inform.
+*/
 function describeCardinality(draft, schema) {
-	const projection = draftToProjection(draft);
-	if (!projection) return [];
+	const projection = probeProjection(draft);
 	const tablesByName = new Map(schema.map((t) => [t.name, t]));
 	const fanning = new Set(fanOutJoins(projection, tablesByName).map((j) => j.key));
 	return projection.joins.map((join) => ({
@@ -70,4 +214,4 @@ function describeCardinality(draft, schema) {
 	}));
 }
 //#endregion
-export { BASE_REF, CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };
+export { BASE_REF, CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, PREVIEW_MAX_ROWS, addDraftJoin, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, compileProjectionSelect, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftRefOptions, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, removeDraftJoin, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };

package/dist/mappings-config.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-ZSv3XuW_.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-Dt_KfgRl.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-DwGXbUo_.mjs";
 //#region src/mappings-config.ts
 const RESERVED_FIELD = "id";
 /**

package/dist/{projection-SCNrLJMV.mjs → projection-BXw_iiw5.mjs}

@@ -93,4 +93,4 @@ function identityRefs(identity, basePkColumn) {
 	return identity.parts;
 }
 //#endregion
-export { projectionSchema as i, PROJECTION_KEY_PATTERN as n, identityRefs as r, BASE_REF as t };
+export { projectionSchema as a, identityRefs as i, PROJECTION_KEY_MESSAGE as n, PROJECTION_KEY_PATTERN as r, BASE_REF as t };

package/dist/{projection-DFgCoyZl.cjs → projection-OJYCYmS_.cjs}

@@ -99,6 +99,12 @@ Object.defineProperty(exports, "BASE_REF", {
 		return BASE_REF;
 	}
 });
+Object.defineProperty(exports, "PROJECTION_KEY_MESSAGE", {
+	enumerable: true,
+	get: function() {
+		return PROJECTION_KEY_MESSAGE;
+	}
+});
 Object.defineProperty(exports, "PROJECTION_KEY_PATTERN", {
 	enumerable: true,
 	get: function() {

package/dist/sync-engine.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_view_compiler = require("./view-compiler-DTGSwTcz.cjs");
+const require_view_compiler = require("./view-compiler-D30HNRnA.cjs");
 //#region src/sync-engine.ts
 /**
 * Diff a view's rows against the current mirror population for one entity.

package/dist/sync-engine.mjs

@@ -1,4 +1,4 @@
-import { r as compileEntityViews } from "./view-compiler-DjzRXiAJ.mjs";
+import { r as compileEntityViews } from "./view-compiler-u3GGRgnv.mjs";
 //#region src/sync-engine.ts
 /**
 * Diff a view's rows against the current mirror population for one entity.

package/dist/{view-compiler-DTGSwTcz.cjs → view-compiler-D30HNRnA.cjs}

@@ -1,4 +1,4 @@
-const require_projection = require("./projection-DFgCoyZl.cjs");
+const require_projection = require("./projection-OJYCYmS_.cjs");
 //#region src/projection-sql.ts
 /**
 * SQL generation for projection-backed entities.
@@ -61,6 +61,38 @@ function compileProjectionJoins(projection) {
 function compileProjectionFrom(projection) {
 	return `FROM ${quoteIdent(projection.baseTable)} AS ${quoteIdent(require_projection.BASE_REF)}`;
 }
+/**
+* Hard ceiling on preview rows, regardless of what a caller asks for.
+*
+* A preview runs against a production database from a button a user can click
+* as often as they like, so the cap belongs beside the query rather than in
+* whichever caller happens to be passing a limit today.
+*/
+const PREVIEW_MAX_ROWS = 50;
+/**
+* One SELECT reading a few rows through an UNSAVED projection, for the derived
+* object builder's preview.
+*
+* Lives here, beside the view compiler, because both sides of the round trip
+* need the identical statement: an embedded org runs it against its own
+* database from `@clivly.com/api`, and a cloud org's host app runs it from
+* `@clivly/sdk`. Two copies would be free to disagree about what the user is
+* being shown, which is the whole value of a preview.
+*
+* Columns are aliased by FIELD NAME, not by ref token. That is the deliberate
+* difference from the push source, which aliases by token because cloud ingest
+* reads `row[token]`; a preview is read by a person, in a table whose headers
+* are the field names they just typed.
+*/
+function compileProjectionPreview(projection, limit) {
+	const { selectItems } = compileProjectionSelect(projection, projection.identity.kind === "base_pk" ? projection.identity.column ?? "id" : "id");
+	return [
+		`SELECT ${selectItems.join(", ")}`,
+		compileProjectionFrom(projection),
+		...compileProjectionJoins(projection),
+		`LIMIT ${Math.max(1, Math.min(Math.floor(limit), 50))}`
+	].join(" ");
+}
 //#endregion
 //#region src/view-compiler.ts
 /**
@@ -282,6 +314,12 @@ Object.defineProperty(exports, "DEFAULT_VIEW_PREFIX", {
 		return DEFAULT_VIEW_PREFIX;
 	}
 });
+Object.defineProperty(exports, "PREVIEW_MAX_ROWS", {
+	enumerable: true,
+	get: function() {
+		return PREVIEW_MAX_ROWS;
+	}
+});
 Object.defineProperty(exports, "compileEntityView", {
 	enumerable: true,
 	get: function() {
@@ -312,6 +350,18 @@ Object.defineProperty(exports, "compileProjectionJoins", {
 		return compileProjectionJoins;
 	}
 });
+Object.defineProperty(exports, "compileProjectionPreview", {
+	enumerable: true,
+	get: function() {
+		return compileProjectionPreview;
+	}
+});
+Object.defineProperty(exports, "compileProjectionSelect", {
+	enumerable: true,
+	get: function() {
+		return compileProjectionSelect;
+	}
+});
 Object.defineProperty(exports, "explainEntitiesConfig", {
 	enumerable: true,
 	get: function() {

package/dist/{view-compiler-DjzRXiAJ.mjs → view-compiler-u3GGRgnv.mjs}

@@ -1,4 +1,4 @@
-import { r as identityRefs, t as BASE_REF } from "./projection-SCNrLJMV.mjs";
+import { i as identityRefs, t as BASE_REF } from "./projection-BXw_iiw5.mjs";
 //#region src/projection-sql.ts
 /**
 * SQL generation for projection-backed entities.
@@ -61,6 +61,38 @@ function compileProjectionJoins(projection) {
 function compileProjectionFrom(projection) {
 	return `FROM ${quoteIdent(projection.baseTable)} AS ${quoteIdent(BASE_REF)}`;
 }
+/**
+* Hard ceiling on preview rows, regardless of what a caller asks for.
+*
+* A preview runs against a production database from a button a user can click
+* as often as they like, so the cap belongs beside the query rather than in
+* whichever caller happens to be passing a limit today.
+*/
+const PREVIEW_MAX_ROWS = 50;
+/**
+* One SELECT reading a few rows through an UNSAVED projection, for the derived
+* object builder's preview.
+*
+* Lives here, beside the view compiler, because both sides of the round trip
+* need the identical statement: an embedded org runs it against its own
+* database from `@clivly.com/api`, and a cloud org's host app runs it from
+* `@clivly/sdk`. Two copies would be free to disagree about what the user is
+* being shown, which is the whole value of a preview.
+*
+* Columns are aliased by FIELD NAME, not by ref token. That is the deliberate
+* difference from the push source, which aliases by token because cloud ingest
+* reads `row[token]`; a preview is read by a person, in a table whose headers
+* are the field names they just typed.
+*/
+function compileProjectionPreview(projection, limit) {
+	const { selectItems } = compileProjectionSelect(projection, projection.identity.kind === "base_pk" ? projection.identity.column ?? "id" : "id");
+	return [
+		`SELECT ${selectItems.join(", ")}`,
+		compileProjectionFrom(projection),
+		...compileProjectionJoins(projection),
+		`LIMIT ${Math.max(1, Math.min(Math.floor(limit), 50))}`
+	].join(" ");
+}
 //#endregion
 //#region src/view-compiler.ts
 /**
@@ -276,4 +308,4 @@ async function explainEntitiesConfig(config, run, options = {}) {
 	return results;
 }
 //#endregion
-export { explainViewExecutionError as a, compileProjectionJoins as c, explainEntitiesConfig as i, quoteIdent as l, compileEntityView as n, compileProjectionFrom as o, compileEntityViews as r, compileProjectionIdentity as s, DEFAULT_VIEW_PREFIX as t };
+export { explainViewExecutionError as a, compileProjectionIdentity as c, compileProjectionSelect as d, quoteIdent as f, explainEntitiesConfig as i, compileProjectionJoins as l, compileEntityView as n, PREVIEW_MAX_ROWS as o, compileEntityViews as r, compileProjectionFrom as s, DEFAULT_VIEW_PREFIX as t, compileProjectionPreview as u };

package/dist/view-compiler.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_view_compiler = require("./view-compiler-DTGSwTcz.cjs");
+const require_view_compiler = require("./view-compiler-D30HNRnA.cjs");
 exports.DEFAULT_VIEW_PREFIX = require_view_compiler.DEFAULT_VIEW_PREFIX;
 exports.compileEntityView = require_view_compiler.compileEntityView;
 exports.compileEntityViews = require_view_compiler.compileEntityViews;

package/dist/view-compiler.mjs

@@ -1,2 +1,2 @@
-import { a as explainViewExecutionError, i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-DjzRXiAJ.mjs";
+import { a as explainViewExecutionError, i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-u3GGRgnv.mjs";
 export { DEFAULT_VIEW_PREFIX, compileEntityView, compileEntityViews, explainEntitiesConfig, explainViewExecutionError };

package/package.json

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