@clivly/core 0.7.4 → 0.9.0

package/dist/entity-config.mjs

@@ -1,339 +1,2 @@
-import { z } from "zod";
-//#region src/entity-config.ts
-/**
-* Entity Config v2 — the declarative contract that turns Clivly's "schema-aware"
-* promise into a real capability.
-*
-* A CRM entity is no longer a flat table name. It is a *derived entity*: a
-* filtered slice of a host table (`source` + `filter`), a column allowlist
-* (`fields` + `readOnly`), and declared `relationships` to other entities. The
-* same host table can back several entities (e.g. `users` → owners + members)
-* distinguished by `role`.
-*
-* This module is the Phase 1 slice: types, schema, `defineClivlyConfig` (a
-* structural helper) and `validateEntitiesConfig` (semantic validation against
-* the host's discovered schema). It performs NO DB access and generates no SQL —
-* the view compiler (Phase 2) and sync engine (Phase 3) consume this contract.
-*/
-/** Canonical CRM concepts a host entity can map onto. */
-const CRM_CONCEPTS = [
-	"contact",
-	"company",
-	"deal",
-	"activity",
-	"conversation",
-	"note"
-];
-/**
-* The canonical `fields` keys the mirror actually persists, per concept — the
-* crm_* columns the sync store writes. An entity's `fields` map keys must be one
-* of these: a non-canonical key (e.g. `fullName` instead of `name`) validates
-* structurally but has no destination column, so the store silently writes an
-* empty value. `validateEntitiesConfig` flags those.
-*
-* This is the single source of truth — the Drizzle store imports it, so the
-* two can't drift (the drift is what made the silent-data-loss trap possible).
-* Concepts absent here aren't materialized yet, so their field keys are
-* unconstrained.
-*/
-const CANONICAL_FIELDS = {
-	contact: [
-		"name",
-		"email",
-		"title",
-		"status"
-	],
-	company: [
-		"name",
-		"domain",
-		"industry",
-		"size"
-	],
-	deal: [
-		"name",
-		"value",
-		"stage"
-	]
-};
-/**
-* The concepts the mapping→sync pipeline can actually materialize into `crm_*`
-* tables. These are exactly the CANONICAL_FIELDS keys — the Drizzle sync store's
-* `persist()` throws for any other concept, so offering one (in the mapping
-* editor, in suggestions, or via the upsert API) is a broken affordance.
-*
-* The broader CRM_CONCEPTS set still validates structurally, so previously
-* stored rows for not-yet-materialized concepts keep rendering. When a concept
-* gains a sync-store path, add its canonical fields above and it joins this set
-* automatically (guarded by the MATERIALIZING_CONCEPTS drift test).
-*/
-const MATERIALIZING_CONCEPTS = [
-	"contact",
-	"company",
-	"deal"
-];
-/**
-* The org-defined custom-object target. Deliberately NOT a member of
-* CRM_CONCEPTS / CANONICAL_FIELDS / MATERIALIZING_CONCEPTS — a custom object has
-* no fixed canonical columns; its mapping's fieldMap keys ARE its properties.
-* Handled as an explicit branch wherever concepts are switched on, so the
-* canonical-concept invariants (and their drift test) stay intact.
-*/
-const CUSTOM_CONCEPT = "custom";
-/**
-* Operator forms for a single column predicate. All predicates on an entity are
-* AND-ed together. `$raw` (see FilterExpr) is the escape hatch for anything the
-* operators can't express.
-*/
-const filterOperatorsSchema = z.union([
-	z.strictObject({ eq: z.union([
-		z.string(),
-		z.number(),
-		z.boolean()
-	]) }),
-	z.strictObject({ ne: z.union([
-		z.string(),
-		z.number(),
-		z.boolean()
-	]) }),
-	z.strictObject({ in: z.array(z.union([
-		z.string(),
-		z.number(),
-		z.boolean()
-	])).min(1) }),
-	z.strictObject({ notIn: z.array(z.union([
-		z.string(),
-		z.number(),
-		z.boolean()
-	])).min(1) }),
-	z.strictObject({ isNull: z.literal(true) }),
-	z.strictObject({ isNotNull: z.literal(true) })
-]);
-const filterValueSchema = z.union([
-	z.string(),
-	z.number(),
-	z.boolean(),
-	filterOperatorsSchema
-]);
-/**
-* A raw SQL predicate fragment. Kept as a *string* (not a query-builder callback)
-* so the whole config stays JSON-serializable — it can be persisted into
-* `crm_entity_mappings` and shipped to the cloud unchanged. Embedded-only in
-* practice; not validated against the schema.
-*/
-const rawFilterSchema = z.strictObject({ $raw: z.string().min(1) });
-const columnFilterSchema = z.record(z.string(), filterValueSchema);
-/** `$raw` is a reserved key; a column literally named `$raw` is not addressable. */
-const filterSchema = z.union([rawFilterSchema, columnFilterSchema]);
-/**
-* How the link between two entities is expressed in the host schema:
-* - `fkOn: "company"` — FK lives on the company table (e.g. organizations.owner_id)
-* - `fkOn: "contact"` — FK lives on the contact table (e.g. users.organization_id)
-* - `through`         — a join table sits between them (many-to-many, role often here)
-* - `$raw`            — opaque SQL join fragment (escape hatch; not schema-validated)
-*
-* `column` and the join-table keys are `table.column` or bare `column` strings.
-*/
-const relationshipViaSchema = z.union([
-	z.strictObject({
-		fkOn: z.enum(["company", "contact"]),
-		column: z.string().min(1)
-	}),
-	z.strictObject({
-		through: z.string().min(1),
-		localKey: z.string().min(1),
-		foreignKey: z.string().min(1)
-	}),
-	z.strictObject({ $raw: z.string().min(1) })
-]);
-const relationshipSchema = z.strictObject({
-	/** Key of the related entity in the `entities` map. */
-	entity: z.string().min(1),
-	via: relationshipViaSchema
-});
-/** A named map of relationships, as stored on an entity / in the mappings row. */
-const relationshipsSchema = z.record(z.string(), relationshipSchema);
-const entitySchema = z.strictObject({
-	/** Which CRM concept this entity maps onto — a canonical concept or "custom". */
-	concept: z.union([z.enum(CRM_CONCEPTS), z.literal(CUSTOM_CONCEPT)]),
-	/** Host table (or view) this entity is derived from. */
-	source: z.string().min(1),
-	/**
-	* Distinguishes multiple entities backed by the same table (e.g. "primary"
-	* for owners, "secondary" for members). Free text; defaults to "primary".
-	*/
-	role: z.string().min(1).optional(),
-	/** Predicate that narrows `source` into this entity's rows. Omit = whole table. */
-	filter: filterSchema.optional(),
-	/** clivlyField → sourceColumn. At least one field is required. */
-	fields: z.record(z.string(), z.string()).refine((f) => Object.keys(f).length > 0, { message: "at least one field must be mapped" }),
-	/**
-	* Host-owned identity fields. Sync overwrites them; the CRM UI cannot edit
-	* them. Must be a subset of `fields` keys.
-	*/
-	readOnly: z.array(z.string()).optional(),
-	/** Named relationships to other entities in this config. */
-	relationships: z.record(z.string(), relationshipSchema).optional(),
-	/**
-	* For a "custom" entity, the crm_object_types row this materializes into.
-	* Required for custom (enforced at the API layer), unused for standard concepts.
-	*/
-	targetObjectTypeId: z.string().min(1).optional()
-});
-const entitiesConfigSchema = z.strictObject({ entities: z.record(z.string(), entitySchema).refine((e) => Object.keys(e).length > 0, { message: "at least one entity must be defined" }) });
-/** Thrown by `defineClivlyConfig({ strict: true })` on non-canonical field keys. */
-var ClivlyConfigError = class extends Error {
-	issues;
-	constructor(issues) {
-		super(`Clivly config has ${issues.length} non-canonical field mapping(s) that would write empty values at sync time:\n${issues.map((issue) => `  - ${issue.path}: ${issue.message}`).join("\n")}`);
-		this.name = "ClivlyConfigError";
-		this.issues = issues;
-	}
-};
-function nonCanonicalFieldKeys(entity) {
-	const canonical = CANONICAL_FIELDS[entity.concept];
-	if (!canonical) return [];
-	return Object.keys(entity.fields).filter((key) => !canonical.includes(key));
-}
-function nonCanonicalMessage(entity, field) {
-	const canonical = CANONICAL_FIELDS[entity.concept] ?? [];
-	return `"${field}" is not a canonical ${entity.concept} field (expected one of: ${canonical.join(", ")})`;
-}
-function canonicalFieldIssues(config) {
-	const issues = [];
-	for (const [key, entity] of Object.entries(config.entities)) for (const field of nonCanonicalFieldKeys(entity)) issues.push({
-		path: `entities.${key}.fields.${field}`,
-		message: nonCanonicalMessage(entity, field)
-	});
-	return issues;
-}
-function defaultWarn(message) {
-	console.warn(message);
-}
-/**
-* Structural helper for `clivly.config.ts`. Gives full type inference on the
-* literal you pass and eagerly parses it, so shape errors surface at config
-* load rather than at sync time.
-*
-* It also catches the silent-data-loss footgun: a non-canonical field key for a
-* materialised concept (e.g. `fullName` instead of `name` on a `contact`) has no
-* destination column, so the store would write an empty value. By default these
-* are reported via `onWarn` (a `console.warn`); pass `{ strict: true }` to throw
-* a `ClivlyConfigError` instead. Does NOT validate against the host schema — that
-* needs the discovered schema; see `validateEntitiesConfig`.
-*/
-function defineClivlyConfig(config, options) {
-	const parsed = entitiesConfigSchema.parse(config);
-	const issues = canonicalFieldIssues(parsed);
-	if (issues.length > 0) {
-		if (options?.strict) throw new ClivlyConfigError(issues);
-		const warn = options?.onWarn ?? defaultWarn;
-		for (const issue of issues) warn(`⚠ Clivly config: ${issue.message} (${issue.path}) — this field would write an empty value at sync time. Pass { strict: true } to make this throw.`);
-	}
-	return parsed;
-}
-/** Split a `table.column` / bare `column` ref into its parts. */
-function parseColumnRef(ref) {
-	const dot = ref.indexOf(".");
-	if (dot === -1) return { column: ref };
-	return {
-		table: ref.slice(0, dot),
-		column: ref.slice(dot + 1)
-	};
-}
-/** Shared lookup + error-collection state threaded through the validators. */
-var SchemaValidator = class {
-	errors = [];
-	columnsByTable = /* @__PURE__ */ new Map();
-	constructor(schema) {
-		for (const table of schema) this.columnsByTable.set(table.name, new Set(table.columns));
-	}
-	tableExists(name) {
-		return this.columnsByTable.has(name);
-	}
-	columnExists(table, column) {
-		return this.columnsByTable.get(table)?.has(column) ?? false;
-	}
-	report(path, message) {
-		this.errors.push({
-			path,
-			message
-		});
-	}
-	/** Report if `column` is absent from `table`. Returns whether it existed. */
-	requireColumn(path, table, column) {
-		if (this.columnExists(table, column)) return true;
-		this.report(path, `column "${column}" does not exist on "${table}"`);
-		return false;
-	}
-};
-function validateFields(v, base, entity) {
-	for (const [field, column] of Object.entries(entity.fields)) v.requireColumn(`${base}.fields.${field}`, entity.source, column);
-	for (const field of nonCanonicalFieldKeys(entity)) v.report(`${base}.fields.${field}`, nonCanonicalMessage(entity, field));
-}
-function validateReadOnly(v, base, entity) {
-	for (const field of entity.readOnly ?? []) if (!(field in entity.fields)) v.report(`${base}.readOnly`, `"${field}" is not one of this entity's fields`);
-}
-function validateFilter(v, base, entity) {
-	if (!entity.filter || "$raw" in entity.filter) return;
-	for (const column of Object.keys(entity.filter)) v.requireColumn(`${base}.filter.${column}`, entity.source, column);
-}
-function validateFkVia(v, relBase, via, entity, related) {
-	const { table, column } = parseColumnRef(via.column);
-	const fkTable = table ?? (via.fkOn === "contact" ? entity.source : related?.source);
-	const path = `${relBase}.via.column`;
-	if (!fkTable) {
-		v.report(path, `cannot resolve table for FK column "${via.column}"`);
-		return;
-	}
-	if (!v.tableExists(fkTable)) {
-		v.report(path, `table "${fkTable}" is not in the discovered schema`);
-		return;
-	}
-	v.requireColumn(path, fkTable, column);
-}
-function validateThroughVia(v, relBase, via) {
-	if (!v.tableExists(via.through)) {
-		v.report(`${relBase}.via.through`, `join table "${via.through}" is not in the discovered schema`);
-		return;
-	}
-	v.requireColumn(`${relBase}.via.localKey`, via.through, via.localKey);
-	v.requireColumn(`${relBase}.via.foreignKey`, via.through, via.foreignKey);
-}
-function validateRelationship(v, base, config, entity, relName, rel) {
-	const relBase = `${base}.relationships.${relName}`;
-	const related = config.entities[rel.entity];
-	if (!related) v.report(`${relBase}.entity`, `"${rel.entity}" is not a defined entity`);
-	const { via } = rel;
-	if ("fkOn" in via) validateFkVia(v, relBase, via, entity, related);
-	else if ("through" in via) validateThroughVia(v, relBase, via);
-}
-function validateEntity(v, config, key, entity) {
-	const base = `entities.${key}`;
-	if (!v.tableExists(entity.source)) {
-		v.report(`${base}.source`, `table "${entity.source}" is not in the discovered schema`);
-		return;
-	}
-	validateFields(v, base, entity);
-	validateReadOnly(v, base, entity);
-	validateFilter(v, base, entity);
-	for (const [relName, rel] of Object.entries(entity.relationships ?? {})) validateRelationship(v, base, config, entity, relName, rel);
-}
-/**
-* Validate a (structurally valid) config against the host's discovered schema:
-* source tables exist, mapped columns exist, `readOnly` ⊆ `fields`, filter
-* columns exist, and relationships point at real entities/tables/columns.
-*
-* `$raw` filters and `$raw` relationship joins are opaque and skipped. Returns
-* every error found (not just the first) so a mapping UI or CLI can show them
-* all at once.
-*/
-function validateEntitiesConfig(config, schema) {
-	const validator = new SchemaValidator(schema);
-	for (const [key, entity] of Object.entries(config.entities)) validateEntity(validator, config, key, entity);
-	return {
-		valid: validator.errors.length === 0,
-		errors: validator.errors
-	};
-}
-//#endregion
+import { a as MATERIALIZING_CONCEPTS, c as filterSchema, d as validateEntitiesConfig, i as ClivlyConfigError, l as relationshipSchema, n as CRM_CONCEPTS, o as defineClivlyConfig, r as CUSTOM_CONCEPT, s as entitiesConfigSchema, t as CANONICAL_FIELDS, u as relationshipsSchema } from "./entity-config-Tb5bbKLj.mjs";
 export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, MATERIALIZING_CONCEPTS, defineClivlyConfig, entitiesConfigSchema, filterSchema, 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.cjs");
+const require_entity_config = require("./entity-config-PoOGzvpN.cjs");
 const require_mapping_score = require("./mapping-score.cjs");
 //#region src/entity-heuristics.ts
 const TARGET_CONCEPTS = [

package/dist/entity-heuristics.d.cts

@@ -1,3 +1,4 @@
+import { DiscoveredColumnMeta } from "./entity-config.cjs";
 import { Scored } from "./mapping-score.cjs";
 //#region src/entity-heuristics.d.ts
 declare const TARGET_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
@@ -6,17 +7,6 @@ declare function suggestCursorField(columnKeys: string[]): string | null;
 declare function matchesConcept(tableName: string, concept: TargetConcept): {
   exact: boolean;
 } | null;
-interface DiscoveredColumnMeta {
-  isForeignKey?: boolean;
-  isPrimaryKey?: boolean;
-  name: string;
-  nullable?: boolean;
-  references?: {
-    table: string;
-    column: string;
-  };
-  type?: string;
-}
 interface ScoredTable {
   columns: string[];
   columnsMeta?: DiscoveredColumnMeta[];
@@ -64,4 +54,4 @@ interface FieldSuggestion {
 declare function scoreFieldMap(concept: TargetConcept, table: ScoredTable): Scored<FieldSuggestion>[];
 declare function toFieldMap(scored: Scored<FieldSuggestion>[]): Record<string, string>;
 //#endregion
-export { DiscoveredColumnMeta, FieldSuggestion, RelationshipSuggestion, ScoredTable, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };
+export { type DiscoveredColumnMeta, FieldSuggestion, RelationshipSuggestion, ScoredTable, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };

package/dist/entity-heuristics.d.mts

@@ -1,3 +1,4 @@
+import { DiscoveredColumnMeta } from "./entity-config.mjs";
 import { Scored } from "./mapping-score.mjs";
 //#region src/entity-heuristics.d.ts
 declare const TARGET_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
@@ -6,17 +7,6 @@ declare function suggestCursorField(columnKeys: string[]): string | null;
 declare function matchesConcept(tableName: string, concept: TargetConcept): {
   exact: boolean;
 } | null;
-interface DiscoveredColumnMeta {
-  isForeignKey?: boolean;
-  isPrimaryKey?: boolean;
-  name: string;
-  nullable?: boolean;
-  references?: {
-    table: string;
-    column: string;
-  };
-  type?: string;
-}
 interface ScoredTable {
   columns: string[];
   columnsMeta?: DiscoveredColumnMeta[];
@@ -64,4 +54,4 @@ interface FieldSuggestion {
 declare function scoreFieldMap(concept: TargetConcept, table: ScoredTable): Scored<FieldSuggestion>[];
 declare function toFieldMap(scored: Scored<FieldSuggestion>[]): Record<string, string>;
 //#endregion
-export { DiscoveredColumnMeta, FieldSuggestion, RelationshipSuggestion, ScoredTable, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };
+export { type DiscoveredColumnMeta, FieldSuggestion, RelationshipSuggestion, ScoredTable, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };

package/dist/entity-heuristics.mjs

@@ -1,4 +1,4 @@
-import { MATERIALIZING_CONCEPTS } from "./entity-config.mjs";
+import { a as MATERIALIZING_CONCEPTS } from "./entity-config-Tb5bbKLj.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,77 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_auth_adapter = require("./auth-adapter.cjs");
-const require_entity_config = require("./entity-config.cjs");
+const require_projection = require("./projection-BXBkh7qp.cjs");
+const require_entity_config = require("./entity-config-PoOGzvpN.cjs");
 const require_mapping_form = require("./mapping-form.cjs");
 const require_mappings_config = require("./mappings-config.cjs");
-const require_view_compiler = require("./view-compiler.cjs");
+const require_view_compiler = require("./view-compiler-BwZ9UgLp.cjs");
 const require_sync_engine = require("./sync-engine.cjs");
+//#region src/projection-draft.ts
+function emptyProjectionDraft(baseTable) {
+	return {
+		baseTable,
+		entityKey: "",
+		fieldBindings: {},
+		identity: { kind: "base_pk" },
+		joins: []
+	};
+}
+/**
+* The ON conditions implied by a foreign key between the two tables, so the
+* builder can pre-fill a join instead of making the user hand-pick columns.
+* Returns [] when no FK relates them — the user then picks manually.
+*/
+function suggestJoinConditions(baseTable, joinTable, schema, joinKey) {
+	const join = schema.find((t) => t.name === joinTable);
+	const conditions = [];
+	for (const column of join?.columnsMeta ?? []) if (column.references?.table === baseTable) conditions.push({
+		left: {
+			table: joinKey,
+			column: column.name
+		},
+		op: "eq",
+		right: {
+			table: require_projection.BASE_REF,
+			column: column.references.column
+		}
+	});
+	return conditions;
+}
+/** 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;
+	if (Object.keys(draft.fieldBindings).length === 0) return null;
+	return {
+		version: 1,
+		kind: "projection",
+		entityKey: draft.entityKey,
+		baseTable: draft.baseTable,
+		joins: draft.joins,
+		fieldBindings: draft.fieldBindings,
+		identity: draft.identity
+	};
+}
+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");
+}
+/** Per-join fan-out, for the builder's inline cardinality hints. */
+function describeCardinality(draft, schema) {
+	const projection = draftToProjection(draft);
+	if (!projection) return [];
+	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) => ({
+		joinKey: join.key,
+		fansOut: fanning.has(join.key)
+	}));
+}
+//#endregion
+exports.BASE_REF = require_projection.BASE_REF;
 exports.CANONICAL_FIELDS = require_entity_config.CANONICAL_FIELDS;
 exports.CRM_CONCEPTS = require_entity_config.CRM_CONCEPTS;
 exports.ClivlyConfigError = require_entity_config.ClivlyConfigError;
@@ -13,16 +80,30 @@ exports.MATERIALIZING_CONCEPTS = require_entity_config.MATERIALIZING_CONCEPTS;
 exports.authCustom = require_auth_adapter.authCustom;
 exports.buildFilterFromDiscriminator = require_mapping_form.buildFilterFromDiscriminator;
 exports.buildRelationships = require_mapping_form.buildRelationships;
+exports.columnMetaFor = require_entity_config.columnMetaFor;
 exports.compileEntityView = require_view_compiler.compileEntityView;
 exports.compileEntityViews = require_view_compiler.compileEntityViews;
+exports.coversUniqueKey = require_entity_config.coversUniqueKey;
 exports.defineClivlyConfig = require_entity_config.defineClivlyConfig;
+exports.describeCardinality = describeCardinality;
+exports.draftErrors = draftErrors;
+exports.draftToProjection = draftToProjection;
+exports.emptyProjectionDraft = emptyProjectionDraft;
 exports.entitiesConfigSchema = require_entity_config.entitiesConfigSchema;
 exports.explainEntitiesConfig = require_view_compiler.explainEntitiesConfig;
+exports.fanOutJoins = require_entity_config.fanOutJoins;
 exports.filterSchema = require_entity_config.filterSchema;
+exports.hasRichMeta = require_entity_config.hasRichMeta;
+exports.identityRefs = require_projection.identityRefs;
+exports.joinFansOut = require_entity_config.joinFansOut;
 exports.mappingsToEntitiesConfig = require_mappings_config.mappingsToEntitiesConfig;
+exports.primaryKeyColumns = require_entity_config.primaryKeyColumns;
+exports.projectionSchema = require_projection.projectionSchema;
 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.runSync = require_sync_engine.runSync;
+exports.suggestJoinConditions = suggestJoinConditions;
 exports.validateEntitiesConfig = require_entity_config.validateEntitiesConfig;
+exports.validateProjection = require_entity_config.validateProjection;

package/dist/index.d.cts

@@ -1,9 +1,79 @@
 import { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, RecordSource, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateDealInput, UpdateTaskInput } from "./types.cjs";
 import { CRMAdapter } from "./adapter.cjs";
 import { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom } from "./auth-adapter.cjs";
-import { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.cjs";
+import { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredColumnMeta, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.cjs";
 import { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.cjs";
-import { EntityMappingRow, mappingsToEntitiesConfig } from "./mappings-config.cjs";
+import { a as ProjectionIdentity, c as ProjectionRef, i as ProjectionFieldBinding, l as identityRefs, n as mappingsToEntitiesConfig, o as ProjectionJoin, r as BASE_REF, s as ProjectionMapping, t as EntityMappingRow, u as projectionSchema } from "./mappings-config-BWo4cRDF.cjs";
 import { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig } from "./view-compiler.cjs";
 import { EntitySyncResult, MirrorRecord, PersistAction, SourceRow, SyncAction, SyncResult, SyncStore, reconcile, runSync } from "./sync-engine.cjs";
-export { type Activity, type ActivityType, 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 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 DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type Note, type PersistAction, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, 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, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };
+//#region src/projection-cardinality.d.ts
+declare function joinFansOut(join: ProjectionJoin, joinTable: DiscoveredSchemaTable): boolean;
+/** Every join in the projection that can multiply rows. */
+declare function fanOutJoins(projection: ProjectionMapping, tablesByName: Map<string, DiscoveredSchemaTable>): ProjectionJoin[];
+//#endregion
+//#region src/projection-draft.d.ts
+/**
+ * The builder's in-progress shape.
+ *
+ * A draft is deliberately looser than a `ProjectionMapping`: it exists while
+ * the user is still choosing things, so every field can be empty. All of the
+ * builder's rules live here as pure functions, which keeps the React components
+ * presentational and lets the rules be tested without a DOM.
+ */
+interface ProjectionDraft {
+  baseTable: string;
+  entityKey: string;
+  fieldBindings: Record<string, ProjectionFieldBinding>;
+  identity: ProjectionIdentity;
+  joins: ProjectionJoin[];
+}
+declare function emptyProjectionDraft(baseTable: string): ProjectionDraft;
+/**
+ * The ON conditions implied by a foreign key between the two tables, so the
+ * builder can pre-fill a join instead of making the user hand-pick columns.
+ * Returns [] when no FK relates them — the user then picks manually.
+ */
+declare function suggestJoinConditions(baseTable: string, joinTable: string, schema: DiscoveredSchemaTable[], joinKey: string): ProjectionJoin["on"];
+/** A draft becomes a projection once it has a valid key and ≥1 binding. */
+declare function draftToProjection(draft: ProjectionDraft): ProjectionMapping | null;
+declare function draftErrors(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): ConfigValidationError[];
+/** Per-join fan-out, for the builder's inline cardinality hints. */
+declare function describeCardinality(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): Array<{
+  fansOut: boolean;
+  joinKey: string;
+}>;
+//#endregion
+//#region src/projection-validate.d.ts
+/**
+ * Validate a projection against the discovered schema. Returns every error
+ * found (not just the first) so a builder UI can show them all at once.
+ */
+declare function validateProjection(projection: ProjectionMapping, schema: DiscoveredSchemaTable[], base: string): ConfigValidationError[];
+//#endregion
+//#region src/schema-meta.d.ts
+/**
+ * Accessors over a discovered table's schema-v2 metadata.
+ *
+ * Every helper treats *absent* metadata as **unknown**, never as a negative
+ * fact. `coversUniqueKey` returning false on a v1 payload is what makes
+ * projection validation fail closed: we cannot prove a join is many-to-one, so
+ * we refuse to compile it rather than guess.
+ */
+declare function columnMetaFor(table: DiscoveredSchemaTable, column: string): DiscoveredColumnMeta | undefined;
+/**
+ * Every primary-key column. More than one entry means a composite PK, which is
+ * why `base_pk` identity is rejected for such tables.
+ */
+declare function primaryKeyColumns(table: DiscoveredSchemaTable): string[];
+/**
+ * Do `columns` contain every column of at least one unique key on `table`?
+ *
+ * This is the fan-out test. A join whose ON columns cover a unique key of the
+ * joined table matches at most one row per base row; one that does not can
+ * match many.
+ */
+declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]): boolean;
+/** 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 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, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, 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 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, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };