@clivly/core 0.9.5 → 0.9.6

package/README.md

@@ -188,10 +188,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/{entity-config-ZSv3XuW_.cjs → entity-config-BAaZOIID.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
 /**

package/dist/{entity-config-Dt_KfgRl.mjs → entity-config-kusaRiDs.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
 /**

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-BAaZOIID.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-kusaRiDs.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-BAaZOIID.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-kusaRiDs.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-BAaZOIID.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-kusaRiDs.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-BAaZOIID.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-kusaRiDs.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.6",
   "private": false,
   "type": "module",
   "description": "ORM/auth-agnostic CRM adapter contracts and shared domain types for Clivly.",