clivly 0.7.4 → 0.9.0

package/internal.d.cts

@@ -1,9 +1,10 @@
 import { C as UpdateDealInput, S as UpdateContactInput, _ as Task, a as ContactFilters, b as TaskPriority, c as CreateCompanyInput, d as CreateTaskInput, f as CrmRole, g as RecordSource, h as Note, i as Contact, l as CreateContactInput, m as DealStage, n as ActivityType, o as ContactStatus, p as Deal, r as Company, s as CreateActivityInput, t as Activity, u as CreateDealInput, v as TaskEntityType, w as UpdateTaskInput, x as TaskStatus, y as TaskFilters } from "./types-B1oRXdNP.cjs";
 import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-DWzgl5Yq.cjs";
 import { t as CRMAdapter } from "./adapter-C2eRbBfo.cjs";
-import { C as validateEntitiesConfig, S as relationshipsSchema, _ as RelationshipsMap, a as ClivlyEntitiesConfig, b as filterSchema, c as ConfigValidationResult, d as FilterExpr, f as FilterValue, g as RelationshipVia, h as RelationshipSpec, i as ClivlyConfigError, l as CrmConcept, m as MaterializingConcept, n as CRM_CONCEPTS, o as ClivlyEntityConfig, p as MATERIALIZING_CONCEPTS, s as ConfigValidationError, t as CANONICAL_FIELDS, u as DiscoveredSchemaTable, v as defineClivlyConfig, x as relationshipSchema, y as entitiesConfigSchema } from "./entity-config-DoUCXtq5.cjs";
-import { i as relationshipViaSignature, n as buildFilterFromDiscriminator, r as buildRelationships, t as RelationshipCandidate } from "./mapping-form-lfyEE7EJ.cjs";
-import { n as mappingsToEntitiesConfig, t as EntityMappingRow } from "./mappings-config-XmzB4dag.cjs";
-import { a as compileEntityView, i as ExplainResult, n as CompiledView, o as compileEntityViews, r as DEFAULT_VIEW_PREFIX, s as explainEntitiesConfig, t as CompileOptions } from "./view-compiler-BWz0sGdm.cjs";
-import { c as SyncResult, f as reconcile, l as SyncStore, n as MirrorRecord, o as SourceRow, p as runSync, r as PersistAction, s as SyncAction, t as EntitySyncResult } from "./sync-engine-B7QIbXro.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 };
+import { C as relationshipsSchema, S as relationshipSchema, _ as RelationshipVia, a as ClivlyEntitiesConfig, b as entitiesConfigSchema, c as ConfigValidationResult, d as DiscoveredSchemaTable, f as FilterExpr, g as RelationshipSpec, h as MaterializingConcept, i as ClivlyConfigError, l as CrmConcept, m as MATERIALIZING_CONCEPTS, n as CRM_CONCEPTS, o as ClivlyEntityConfig, p as FilterValue, s as ConfigValidationError, t as CANONICAL_FIELDS, u as DiscoveredColumnMeta, v as RelationshipsMap, w as validateEntitiesConfig, x as filterSchema, y as defineClivlyConfig } from "./entity-config-C4Yf_fPj.cjs";
+import { i as relationshipViaSignature, n as buildFilterFromDiscriminator, r as buildRelationships, t as RelationshipCandidate } from "./mapping-form-43bwOTat.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-xsLMn3I-.cjs";
+import { a as compileEntityView, i as ExplainResult, n as CompiledView, o as compileEntityViews, r as DEFAULT_VIEW_PREFIX, s as explainEntitiesConfig, t as CompileOptions } from "./view-compiler-Ll9cbIJz.cjs";
+import { c as SyncResult, f as reconcile, l as SyncStore, n as MirrorRecord, o as SourceRow, p as runSync, r as PersistAction, s as SyncAction, t as EntitySyncResult } from "./sync-engine-GNqRB8eS.cjs";
+import { a as validateProjection, c as draftErrors, d as suggestJoinConditions, f as fanOutJoins, i as primaryKeyColumns, l as draftToProjection, n as coversUniqueKey, o as ProjectionDraft, p as joinFansOut, r as hasRichMeta, s as describeCardinality, t as columnMetaFor, u as emptyProjectionDraft } from "./internal-B8ydhsKd.cjs";
+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 };

package/internal.d.mts

@@ -1,9 +1,10 @@
 import { C as UpdateDealInput, S as UpdateContactInput, _ as Task, a as ContactFilters, b as TaskPriority, c as CreateCompanyInput, d as CreateTaskInput, f as CrmRole, g as RecordSource, h as Note, i as Contact, l as CreateContactInput, m as DealStage, n as ActivityType, o as ContactStatus, p as Deal, r as Company, s as CreateActivityInput, t as Activity, u as CreateDealInput, v as TaskEntityType, w as UpdateTaskInput, x as TaskStatus, y as TaskFilters } from "./types-B1oRXdNP.mjs";
 import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-Bjgo8LhN.mjs";
 import { t as CRMAdapter } from "./adapter-D5LRa-NA.mjs";
-import { C as validateEntitiesConfig, S as relationshipsSchema, _ as RelationshipsMap, a as ClivlyEntitiesConfig, b as filterSchema, c as ConfigValidationResult, d as FilterExpr, f as FilterValue, g as RelationshipVia, h as RelationshipSpec, i as ClivlyConfigError, l as CrmConcept, m as MaterializingConcept, n as CRM_CONCEPTS, o as ClivlyEntityConfig, p as MATERIALIZING_CONCEPTS, s as ConfigValidationError, t as CANONICAL_FIELDS, u as DiscoveredSchemaTable, v as defineClivlyConfig, x as relationshipSchema, y as entitiesConfigSchema } from "./entity-config-DoUCXtq5.mjs";
-import { i as relationshipViaSignature, n as buildFilterFromDiscriminator, r as buildRelationships, t as RelationshipCandidate } from "./mapping-form-D93lhHEc.mjs";
-import { n as mappingsToEntitiesConfig, t as EntityMappingRow } from "./mappings-config-DsUa7-1w.mjs";
-import { a as compileEntityView, i as ExplainResult, n as CompiledView, o as compileEntityViews, r as DEFAULT_VIEW_PREFIX, s as explainEntitiesConfig, t as CompileOptions } from "./view-compiler-Bn_EJJMO.mjs";
-import { c as SyncResult, f as reconcile, l as SyncStore, n as MirrorRecord, o as SourceRow, p as runSync, r as PersistAction, s as SyncAction, t as EntitySyncResult } from "./sync-engine-DGk_AeHJ.mjs";
-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 };
+import { C as relationshipsSchema, S as relationshipSchema, _ as RelationshipVia, a as ClivlyEntitiesConfig, b as entitiesConfigSchema, c as ConfigValidationResult, d as DiscoveredSchemaTable, f as FilterExpr, g as RelationshipSpec, h as MaterializingConcept, i as ClivlyConfigError, l as CrmConcept, m as MATERIALIZING_CONCEPTS, n as CRM_CONCEPTS, o as ClivlyEntityConfig, p as FilterValue, s as ConfigValidationError, t as CANONICAL_FIELDS, u as DiscoveredColumnMeta, v as RelationshipsMap, w as validateEntitiesConfig, x as filterSchema, y as defineClivlyConfig } from "./entity-config-C4Yf_fPj.mjs";
+import { i as relationshipViaSignature, n as buildFilterFromDiscriminator, r as buildRelationships, t as RelationshipCandidate } from "./mapping-form-DUvWUYCo.mjs";
+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-BpcR8bBo.mjs";
+import { a as compileEntityView, i as ExplainResult, n as CompiledView, o as compileEntityViews, r as DEFAULT_VIEW_PREFIX, s as explainEntitiesConfig, t as CompileOptions } from "./view-compiler-Cin0neDO.mjs";
+import { c as SyncResult, f as reconcile, l as SyncStore, n as MirrorRecord, o as SourceRow, p as runSync, r as PersistAction, s as SyncAction, t as EntitySyncResult } from "./sync-engine-ZsusW-q_.mjs";
+import { a as validateProjection, c as draftErrors, d as suggestJoinConditions, f as fanOutJoins, i as primaryKeyColumns, l as draftToProjection, n as coversUniqueKey, o as ProjectionDraft, p as joinFansOut, r as hasRichMeta, s as describeCardinality, t as columnMetaFor, u as emptyProjectionDraft } from "./internal-MBkNo3bw.mjs";
+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 };

package/internal.mjs

@@ -1,7 +1,9 @@
-import { a as MATERIALIZING_CONCEPTS, c as filterSchema, d as validateEntitiesConfig, i as ClivlyConfigError, l as relationshipSchema, n as CRM_CONCEPTS, o as defineClivlyConfig, s as entitiesConfigSchema, t as CANONICAL_FIELDS, u as relationshipsSchema } from "./entity-config-va2bkH5o.mjs";
+import { i as projectionSchema, r as identityRefs, t as BASE_REF } from "./projection-D7xmQP4S.mjs";
+import { _ as hasRichMeta, a as MATERIALIZING_CONCEPTS, c as filterSchema, d as validateEntitiesConfig, f as validateProjection, g as coversUniqueKey, h as columnMetaFor, i as ClivlyConfigError, l as relationshipSchema, m as joinFansOut, n as CRM_CONCEPTS, o as defineClivlyConfig, p as fanOutJoins, s as entitiesConfigSchema, t as CANONICAL_FIELDS, u as relationshipsSchema, v as primaryKeyColumns } from "./entity-config-D3LmzgLb.mjs";
 import { t as authCustom } from "./auth-adapter-gfVDxf3d.mjs";
 import { n as buildRelationships, r as relationshipViaSignature, t as buildFilterFromDiscriminator } from "./mapping-form-DigkuvFc.mjs";
-import { t as mappingsToEntitiesConfig } from "./mappings-config-Dbgxx3Nv.mjs";
-import { i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-ChWr_Lml.mjs";
-import { i as runSync, r as reconcile } from "./sync-engine-Do5ru3WF.mjs";
-export { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };
+import { t as mappingsToEntitiesConfig } from "./mappings-config-bJQT_gSa.mjs";
+import { a as suggestJoinConditions, i as emptyProjectionDraft, n as draftErrors, r as draftToProjection, t as describeCardinality } from "./internal-DMySVbM0.mjs";
+import { i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-DlTpOfZi.mjs";
+import { i as runSync, r as reconcile } from "./sync-engine-Bg6-SznL.mjs";
+export { BASE_REF, CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, 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 };

package/{mapping-form-D93lhHEc.d.mts → mapping-form-43bwOTat.d.cts}

@@ -1,4 +1,4 @@
-import { _ as RelationshipsMap, d as FilterExpr, g as RelationshipVia } from "./entity-config-DoUCXtq5.mjs";
+import { _ as RelationshipVia, f as FilterExpr, v as RelationshipsMap } from "./entity-config-C4Yf_fPj.cjs";
 //#region ../core/src/mapping-form.d.ts
 /**
  * A relationship the mapping UI can offer or has configured, in the shape the

package/{mapping-form-lfyEE7EJ.d.cts → mapping-form-DUvWUYCo.d.mts}

@@ -1,4 +1,4 @@
-import { _ as RelationshipsMap, d as FilterExpr, g as RelationshipVia } from "./entity-config-DoUCXtq5.cjs";
+import { _ as RelationshipVia, f as FilterExpr, v as RelationshipsMap } from "./entity-config-C4Yf_fPj.mjs";
 //#region ../core/src/mapping-form.d.ts
 /**
  * A relationship the mapping UI can offer or has configured, in the shape the

package/{mappings-config-BsRADNRv.cjs → mappings-config-BSSwdHiq.cjs}

@@ -1,4 +1,4 @@
-const require_entity_config = require("./entity-config-D87rV-tE.cjs");
+const require_entity_config = require("./entity-config-CsLl-ftC.cjs");
 //#region ../core/src/mappings-config.ts
 const RESERVED_FIELD = "id";
 /**
@@ -21,7 +21,9 @@ function canonicalFields(concept, fieldMap) {
 const DEFAULT_ROLE = "primary";
 const ACTIVE_STATUS = "active";
 function isEligible(row) {
-	return (row.status ?? ACTIVE_STATUS) === ACTIVE_STATUS && Object.keys(row.fieldMap ?? {}).length > 0;
+	if ((row.status ?? ACTIVE_STATUS) !== ACTIVE_STATUS) return false;
+	if (row.projection) return Object.keys(row.projection.fieldBindings ?? {}).length > 0;
+	return Object.keys(row.fieldMap ?? {}).length > 0;
 }
 /**
 * Preferred key for a row: the bare source table when it backs a single entity,
@@ -45,13 +47,28 @@ function uniquify(base, used) {
 	used.add(key);
 	return key;
 }
+/**
+* A projection's `fields` map, derived mechanically from its bindings.
+*
+* `ClivlyEntityConfig.fields` is required and read by existing consumers, so a
+* projection entity must populate it. The values are ref *tokens*
+* (`"base.full_name"`), never host column names — the compiler reads
+* `projection.fieldBindings`, and `validateEntitiesConfig` skips the legacy
+* column check for projection entities precisely because of this.
+*/
+function projectionFields(projection) {
+	const fields = {};
+	for (const [field, binding] of Object.entries(projection.fieldBindings)) fields[field] = `${binding.from.table}.${binding.from.column}`;
+	return fields;
+}
 function buildEntity(row, refIndex) {
 	const entity = {
 		concept: row.targetConcept,
-		source: row.sourceTable,
+		source: row.projection?.baseTable ?? row.sourceTable,
 		role: row.role ?? DEFAULT_ROLE,
-		fields: canonicalFields(row.targetConcept, row.fieldMap)
+		fields: row.projection ? projectionFields(row.projection) : canonicalFields(row.targetConcept, row.fieldMap)
 	};
+	if (row.projection) entity.projection = row.projection;
 	if (row.targetConcept === "custom" && row.targetObjectTypeId) entity.targetObjectTypeId = row.targetObjectTypeId;
 	if (row.filter && Object.keys(row.filter).length > 0) entity.filter = row.filter;
 	if (row.relationships && Object.keys(row.relationships).length > 0) {
@@ -76,11 +93,16 @@ function buildEntity(row, refIndex) {
 function mappingsToEntitiesConfig(rows) {
 	const eligible = rows.filter(isEligible);
 	const tableCounts = /* @__PURE__ */ new Map();
-	for (const row of eligible) tableCounts.set(row.sourceTable, (tableCounts.get(row.sourceTable) ?? 0) + 1);
+	for (const row of eligible) {
+		if (row.projection) continue;
+		tableCounts.set(row.sourceTable, (tableCounts.get(row.sourceTable) ?? 0) + 1);
+	}
 	const used = /* @__PURE__ */ new Set();
 	const tableAnchor = /* @__PURE__ */ new Map();
 	const assigned = [];
-	for (const row of eligible) {
+	const legacyRows = eligible.filter((row) => !row.projection);
+	const projectionRows = eligible.filter((row) => row.projection);
+	for (const row of legacyRows) {
 		const key = uniquify(preferredKey(row, tableCounts), used);
 		assigned.push({
 			row,
@@ -88,6 +110,10 @@ function mappingsToEntitiesConfig(rows) {
 		});
 		if ((row.role ?? DEFAULT_ROLE) === DEFAULT_ROLE || !tableAnchor.has(row.sourceTable)) tableAnchor.set(row.sourceTable, key);
 	}
+	for (const row of projectionRows) assigned.push({
+		row,
+		key: uniquify(row.projection?.entityKey ?? row.sourceTable, used)
+	});
 	const refIndex = /* @__PURE__ */ new Map();
 	for (const { key } of assigned) refIndex.set(key, key);
 	for (const [table, key] of tableAnchor) if (!refIndex.has(table)) refIndex.set(table, key);

package/mappings-config-BpcR8bBo.d.mts

@@ -0,0 +1,167 @@
+import { A as ZodRecord, D as ZodLiteral, E as ZodEnum, M as ZodUnion, N as output, O as ZodObject, P as $strict, T as ZodArray, a as ClivlyEntitiesConfig, j as ZodString, k as ZodOptional } from "./entity-config-C4Yf_fPj.mjs";
+//#region ../core/src/projection.d.ts
+/**
+ * Projection-backed custom mappings — one custom object derived from a base
+ * table plus explicit joins.
+ *
+ * A projection is deliberately narrow: equality joins only, direct column
+ * bindings only, no expressions and no aggregation. Everything a user can
+ * express here compiles to a single read-only view whose `id` column is
+ * provably unique per row, which is what lets the sync engine consume it
+ * unchanged.
+ *
+ * Refs address tables symbolically: `"base"` for the base table, or a join's
+ * `key`. Raw table names are never accepted in a ref, so a projection can
+ * never reach a table it did not declare.
+ */
+/** The reserved ref name for the projection's base table. */
+declare const BASE_REF = "base";
+declare const projectionRefSchema: ZodObject<{
+  table: ZodString;
+  column: ZodString;
+}, $strict>;
+type ProjectionRef = output<typeof projectionRefSchema>;
+declare const projectionJoinSchema: ZodObject<{
+  key: ZodString;
+  table: ZodString;
+  type: ZodEnum<{
+    inner: "inner";
+    left: "left";
+  }>;
+  on: ZodArray<ZodObject<{
+    left: ZodObject<{
+      table: ZodString;
+      column: ZodString;
+    }, $strict>;
+    op: ZodLiteral<"eq">;
+    right: ZodObject<{
+      table: ZodString;
+      column: ZodString;
+    }, $strict>;
+  }, $strict>>;
+}, $strict>;
+type ProjectionJoin = output<typeof projectionJoinSchema>;
+declare const projectionFieldBindingSchema: ZodObject<{
+  from: ZodObject<{
+    table: ZodString;
+    column: ZodString;
+  }, $strict>;
+}, $strict>;
+type ProjectionFieldBinding = output<typeof projectionFieldBindingSchema>;
+declare const projectionIdentitySchema: ZodUnion<readonly [ZodObject<{
+  kind: ZodLiteral<"base_pk">;
+  column: ZodOptional<ZodString>;
+}, $strict>, ZodObject<{
+  kind: ZodLiteral<"column">;
+  from: ZodObject<{
+    table: ZodString;
+    column: ZodString;
+  }, $strict>;
+}, $strict>, ZodObject<{
+  kind: ZodLiteral<"composite">;
+  parts: ZodArray<ZodObject<{
+    table: ZodString;
+    column: ZodString;
+  }, $strict>>;
+}, $strict>]>;
+type ProjectionIdentity = output<typeof projectionIdentitySchema>;
+declare const projectionSchema: ZodObject<{
+  version: ZodLiteral<1>;
+  kind: ZodLiteral<"projection">;
+  entityKey: ZodString;
+  baseTable: ZodString;
+  joins: ZodArray<ZodObject<{
+    key: ZodString;
+    table: ZodString;
+    type: ZodEnum<{
+      inner: "inner";
+      left: "left";
+    }>;
+    on: ZodArray<ZodObject<{
+      left: ZodObject<{
+        table: ZodString;
+        column: ZodString;
+      }, $strict>;
+      op: ZodLiteral<"eq">;
+      right: ZodObject<{
+        table: ZodString;
+        column: ZodString;
+      }, $strict>;
+    }, $strict>>;
+  }, $strict>>;
+  fieldBindings: ZodRecord<ZodString, ZodObject<{
+    from: ZodObject<{
+      table: ZodString;
+      column: ZodString;
+    }, $strict>;
+  }, $strict>>;
+  identity: ZodUnion<readonly [ZodObject<{
+    kind: ZodLiteral<"base_pk">;
+    column: ZodOptional<ZodString>;
+  }, $strict>, ZodObject<{
+    kind: ZodLiteral<"column">;
+    from: ZodObject<{
+      table: ZodString;
+      column: ZodString;
+    }, $strict>;
+  }, $strict>, ZodObject<{
+    kind: ZodLiteral<"composite">;
+    parts: ZodArray<ZodObject<{
+      table: ZodString;
+      column: ZodString;
+    }, $strict>>;
+  }, $strict>]>;
+}, $strict>;
+type ProjectionMapping = output<typeof projectionSchema>;
+/**
+ * Every column ref an identity depends on. `basePkColumn` is the base table's
+ * discovered PK, used only when a `base_pk` identity omits an explicit column.
+ */
+declare function identityRefs(identity: ProjectionIdentity, basePkColumn: string): ProjectionRef[];
+//#endregion
+//#region ../core/src/mappings-config.d.ts
+/**
+ * Mappings → Entity Config bridge.
+ *
+ * `crm_entity_mappings` rows are the single source of truth for how a host
+ * schema maps onto Clivly's CRM concepts. This module compiles those rows into
+ * a `ClivlyEntitiesConfig` — the contract the view compiler and sync engine
+ * consume — so the persisted mapping and the runtime pipeline never diverge.
+ *
+ * The row model has no explicit entity-key column (it's keyed by
+ * `sourceTable + targetConcept + role`), but the config's `relationships`
+ * reference other entities *by key*. This builder therefore derives a stable
+ * key per row and resolves each relationship's `entity` reference through the
+ * same derivation — so a relationship stored as `entity: "<relatedTable>"`
+ * (the shape `mappings.suggest` produces) resolves to the right entity.
+ */
+/**
+ * A persisted `crm_entity_mappings` row, narrowed to the columns the builder
+ * reads. Structurally compatible with the Drizzle row (jsonb columns typed
+ * loosely) so the API layer can pass `db.select()` results straight in.
+ */
+interface EntityMappingRow {
+  fieldMap: Record<string, string>;
+  filter?: Record<string, unknown> | null;
+  /**
+   * Advanced mapping: a base table plus explicit joins. When set, this — not
+   * `fieldMap` — is the authored source of truth, and `sourceTable` merely
+   * mirrors `projection.baseTable`.
+   */
+  projection?: ProjectionMapping | null;
+  relationships?: Record<string, unknown> | null;
+  role?: string | null;
+  sourceTable: string;
+  status?: string | null;
+  targetConcept: string;
+  targetObjectTypeId?: string | null;
+}
+/**
+ * Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`
+ * rows with at least one mapped field are included; disabled/suggested rows and
+ * unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
+ * eligible — a no-op the view compiler and sync engine both tolerate.
+ */
+declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
+//#endregion
+export { ProjectionIdentity as a, ProjectionRef as c, ProjectionFieldBinding as i, identityRefs as l, mappingsToEntitiesConfig as n, ProjectionJoin as o, BASE_REF as r, ProjectionMapping as s, EntityMappingRow as t, projectionSchema as u };

package/{mappings-config-Dbgxx3Nv.mjs → mappings-config-bJQT_gSa.mjs}

@@ -1,4 +1,4 @@
-import { t as CANONICAL_FIELDS } from "./entity-config-va2bkH5o.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-D3LmzgLb.mjs";
 //#region ../core/src/mappings-config.ts
 const RESERVED_FIELD = "id";
 /**
@@ -21,7 +21,9 @@ function canonicalFields(concept, fieldMap) {
 const DEFAULT_ROLE = "primary";
 const ACTIVE_STATUS = "active";
 function isEligible(row) {
-	return (row.status ?? ACTIVE_STATUS) === ACTIVE_STATUS && Object.keys(row.fieldMap ?? {}).length > 0;
+	if ((row.status ?? ACTIVE_STATUS) !== ACTIVE_STATUS) return false;
+	if (row.projection) return Object.keys(row.projection.fieldBindings ?? {}).length > 0;
+	return Object.keys(row.fieldMap ?? {}).length > 0;
 }
 /**
 * Preferred key for a row: the bare source table when it backs a single entity,
@@ -45,13 +47,28 @@ function uniquify(base, used) {
 	used.add(key);
 	return key;
 }
+/**
+* A projection's `fields` map, derived mechanically from its bindings.
+*
+* `ClivlyEntityConfig.fields` is required and read by existing consumers, so a
+* projection entity must populate it. The values are ref *tokens*
+* (`"base.full_name"`), never host column names — the compiler reads
+* `projection.fieldBindings`, and `validateEntitiesConfig` skips the legacy
+* column check for projection entities precisely because of this.
+*/
+function projectionFields(projection) {
+	const fields = {};
+	for (const [field, binding] of Object.entries(projection.fieldBindings)) fields[field] = `${binding.from.table}.${binding.from.column}`;
+	return fields;
+}
 function buildEntity(row, refIndex) {
 	const entity = {
 		concept: row.targetConcept,
-		source: row.sourceTable,
+		source: row.projection?.baseTable ?? row.sourceTable,
 		role: row.role ?? DEFAULT_ROLE,
-		fields: canonicalFields(row.targetConcept, row.fieldMap)
+		fields: row.projection ? projectionFields(row.projection) : canonicalFields(row.targetConcept, row.fieldMap)
 	};
+	if (row.projection) entity.projection = row.projection;
 	if (row.targetConcept === "custom" && row.targetObjectTypeId) entity.targetObjectTypeId = row.targetObjectTypeId;
 	if (row.filter && Object.keys(row.filter).length > 0) entity.filter = row.filter;
 	if (row.relationships && Object.keys(row.relationships).length > 0) {
@@ -76,11 +93,16 @@ function buildEntity(row, refIndex) {
 function mappingsToEntitiesConfig(rows) {
 	const eligible = rows.filter(isEligible);
 	const tableCounts = /* @__PURE__ */ new Map();
-	for (const row of eligible) tableCounts.set(row.sourceTable, (tableCounts.get(row.sourceTable) ?? 0) + 1);
+	for (const row of eligible) {
+		if (row.projection) continue;
+		tableCounts.set(row.sourceTable, (tableCounts.get(row.sourceTable) ?? 0) + 1);
+	}
 	const used = /* @__PURE__ */ new Set();
 	const tableAnchor = /* @__PURE__ */ new Map();
 	const assigned = [];
-	for (const row of eligible) {
+	const legacyRows = eligible.filter((row) => !row.projection);
+	const projectionRows = eligible.filter((row) => row.projection);
+	for (const row of legacyRows) {
 		const key = uniquify(preferredKey(row, tableCounts), used);
 		assigned.push({
 			row,
@@ -88,6 +110,10 @@ function mappingsToEntitiesConfig(rows) {
 		});
 		if ((row.role ?? DEFAULT_ROLE) === DEFAULT_ROLE || !tableAnchor.has(row.sourceTable)) tableAnchor.set(row.sourceTable, key);
 	}
+	for (const row of projectionRows) assigned.push({
+		row,
+		key: uniquify(row.projection?.entityKey ?? row.sourceTable, used)
+	});
 	const refIndex = /* @__PURE__ */ new Map();
 	for (const { key } of assigned) refIndex.set(key, key);
 	for (const [table, key] of tableAnchor) if (!refIndex.has(table)) refIndex.set(table, key);

package/mappings-config-xsLMn3I-.d.cts

@@ -0,0 +1,167 @@
+import { A as ZodRecord, D as ZodLiteral, E as ZodEnum, M as ZodUnion, N as output, O as ZodObject, P as $strict, T as ZodArray, a as ClivlyEntitiesConfig, j as ZodString, k as ZodOptional } from "./entity-config-C4Yf_fPj.cjs";
+//#region ../core/src/projection.d.ts
+/**
+ * Projection-backed custom mappings — one custom object derived from a base
+ * table plus explicit joins.
+ *
+ * A projection is deliberately narrow: equality joins only, direct column
+ * bindings only, no expressions and no aggregation. Everything a user can
+ * express here compiles to a single read-only view whose `id` column is
+ * provably unique per row, which is what lets the sync engine consume it
+ * unchanged.
+ *
+ * Refs address tables symbolically: `"base"` for the base table, or a join's
+ * `key`. Raw table names are never accepted in a ref, so a projection can
+ * never reach a table it did not declare.
+ */
+/** The reserved ref name for the projection's base table. */
+declare const BASE_REF = "base";
+declare const projectionRefSchema: ZodObject<{
+  table: ZodString;
+  column: ZodString;
+}, $strict>;
+type ProjectionRef = output<typeof projectionRefSchema>;
+declare const projectionJoinSchema: ZodObject<{
+  key: ZodString;
+  table: ZodString;
+  type: ZodEnum<{
+    inner: "inner";
+    left: "left";
+  }>;
+  on: ZodArray<ZodObject<{
+    left: ZodObject<{
+      table: ZodString;
+      column: ZodString;
+    }, $strict>;
+    op: ZodLiteral<"eq">;
+    right: ZodObject<{
+      table: ZodString;
+      column: ZodString;
+    }, $strict>;
+  }, $strict>>;
+}, $strict>;
+type ProjectionJoin = output<typeof projectionJoinSchema>;
+declare const projectionFieldBindingSchema: ZodObject<{
+  from: ZodObject<{
+    table: ZodString;
+    column: ZodString;
+  }, $strict>;
+}, $strict>;
+type ProjectionFieldBinding = output<typeof projectionFieldBindingSchema>;
+declare const projectionIdentitySchema: ZodUnion<readonly [ZodObject<{
+  kind: ZodLiteral<"base_pk">;
+  column: ZodOptional<ZodString>;
+}, $strict>, ZodObject<{
+  kind: ZodLiteral<"column">;
+  from: ZodObject<{
+    table: ZodString;
+    column: ZodString;
+  }, $strict>;
+}, $strict>, ZodObject<{
+  kind: ZodLiteral<"composite">;
+  parts: ZodArray<ZodObject<{
+    table: ZodString;
+    column: ZodString;
+  }, $strict>>;
+}, $strict>]>;
+type ProjectionIdentity = output<typeof projectionIdentitySchema>;
+declare const projectionSchema: ZodObject<{
+  version: ZodLiteral<1>;
+  kind: ZodLiteral<"projection">;
+  entityKey: ZodString;
+  baseTable: ZodString;
+  joins: ZodArray<ZodObject<{
+    key: ZodString;
+    table: ZodString;
+    type: ZodEnum<{
+      inner: "inner";
+      left: "left";
+    }>;
+    on: ZodArray<ZodObject<{
+      left: ZodObject<{
+        table: ZodString;
+        column: ZodString;
+      }, $strict>;
+      op: ZodLiteral<"eq">;
+      right: ZodObject<{
+        table: ZodString;
+        column: ZodString;
+      }, $strict>;
+    }, $strict>>;
+  }, $strict>>;
+  fieldBindings: ZodRecord<ZodString, ZodObject<{
+    from: ZodObject<{
+      table: ZodString;
+      column: ZodString;
+    }, $strict>;
+  }, $strict>>;
+  identity: ZodUnion<readonly [ZodObject<{
+    kind: ZodLiteral<"base_pk">;
+    column: ZodOptional<ZodString>;
+  }, $strict>, ZodObject<{
+    kind: ZodLiteral<"column">;
+    from: ZodObject<{
+      table: ZodString;
+      column: ZodString;
+    }, $strict>;
+  }, $strict>, ZodObject<{
+    kind: ZodLiteral<"composite">;
+    parts: ZodArray<ZodObject<{
+      table: ZodString;
+      column: ZodString;
+    }, $strict>>;
+  }, $strict>]>;
+}, $strict>;
+type ProjectionMapping = output<typeof projectionSchema>;
+/**
+ * Every column ref an identity depends on. `basePkColumn` is the base table's
+ * discovered PK, used only when a `base_pk` identity omits an explicit column.
+ */
+declare function identityRefs(identity: ProjectionIdentity, basePkColumn: string): ProjectionRef[];
+//#endregion
+//#region ../core/src/mappings-config.d.ts
+/**
+ * Mappings → Entity Config bridge.
+ *
+ * `crm_entity_mappings` rows are the single source of truth for how a host
+ * schema maps onto Clivly's CRM concepts. This module compiles those rows into
+ * a `ClivlyEntitiesConfig` — the contract the view compiler and sync engine
+ * consume — so the persisted mapping and the runtime pipeline never diverge.
+ *
+ * The row model has no explicit entity-key column (it's keyed by
+ * `sourceTable + targetConcept + role`), but the config's `relationships`
+ * reference other entities *by key*. This builder therefore derives a stable
+ * key per row and resolves each relationship's `entity` reference through the
+ * same derivation — so a relationship stored as `entity: "<relatedTable>"`
+ * (the shape `mappings.suggest` produces) resolves to the right entity.
+ */
+/**
+ * A persisted `crm_entity_mappings` row, narrowed to the columns the builder
+ * reads. Structurally compatible with the Drizzle row (jsonb columns typed
+ * loosely) so the API layer can pass `db.select()` results straight in.
+ */
+interface EntityMappingRow {
+  fieldMap: Record<string, string>;
+  filter?: Record<string, unknown> | null;
+  /**
+   * Advanced mapping: a base table plus explicit joins. When set, this — not
+   * `fieldMap` — is the authored source of truth, and `sourceTable` merely
+   * mirrors `projection.baseTable`.
+   */
+  projection?: ProjectionMapping | null;
+  relationships?: Record<string, unknown> | null;
+  role?: string | null;
+  sourceTable: string;
+  status?: string | null;
+  targetConcept: string;
+  targetObjectTypeId?: string | null;
+}
+/**
+ * Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`
+ * rows with at least one mapped field are included; disabled/suggested rows and
+ * unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
+ * eligible — a no-op the view compiler and sync engine both tolerate.
+ */
+declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
+//#endregion
+export { ProjectionIdentity as a, ProjectionRef as c, ProjectionFieldBinding as i, identityRefs as l, mappingsToEntitiesConfig as n, ProjectionJoin as o, BASE_REF as r, ProjectionMapping as s, EntityMappingRow as t, projectionSchema as u };

package/{namespace-probe-B4WE45TH.d.mts → namespace-probe-BSH_p9TK.d.cts}

@@ -1,4 +1,4 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-DoUCXtq5.mjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-C4Yf_fPj.cjs";
 //#region ../sdk/src/drizzle-meta.d.ts
 declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
 interface DrizzleSourceMeta {
@@ -10,6 +10,8 @@ interface DrizzleSourceMeta {
   idField: string;
   /** The backing table's real name, so discovery can key metadata by table. */
   tableName?: string;
+  /** Every unique key on the table, each as its DB column names. */
+  uniqueConstraints?: string[][];
 }
 //#endregion
 //#region ../sdk/src/types.d.ts
@@ -33,6 +35,13 @@ interface DiscoveredTable {
   name: string;
   /** Approximate source row count, when cheaply derivable. */
   rowCount?: number;
+  /**
+   * Every unique key on the table, each as its DB column names. Primary keys
+   * are included (a PK is a unique key). Absent on v1 hosts and for
+   * hand-declared tables — consumers must treat absence as "unknown", never
+   * as "no unique keys".
+   */
+  uniqueConstraints?: string[][];
 }
 interface ClivlySDKConfig {
   /** Org-scoped API token (sk_live_…) from Settings → API keys. */

package/{namespace-probe-DRzOtaRT.d.cts → namespace-probe-Dsp5uNkS.d.mts}

@@ -1,4 +1,4 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-DoUCXtq5.cjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-C4Yf_fPj.mjs";
 //#region ../sdk/src/drizzle-meta.d.ts
 declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
 interface DrizzleSourceMeta {
@@ -10,6 +10,8 @@ interface DrizzleSourceMeta {
   idField: string;
   /** The backing table's real name, so discovery can key metadata by table. */
   tableName?: string;
+  /** Every unique key on the table, each as its DB column names. */
+  uniqueConstraints?: string[][];
 }
 //#endregion
 //#region ../sdk/src/types.d.ts
@@ -33,6 +35,13 @@ interface DiscoveredTable {
   name: string;
   /** Approximate source row count, when cheaply derivable. */
   rowCount?: number;
+  /**
+   * Every unique key on the table, each as its DB column names. Primary keys
+   * are included (a PK is a unique key). Absent on v1 hosts and for
+   * hand-declared tables — consumers must treat absence as "unknown", never
+   * as "no unique keys".
+   */
+  uniqueConstraints?: string[][];
 }
 interface ClivlySDKConfig {
   /** Org-scoped API token (sk_live_…) from Settings → API keys. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clivly",
-  "version": "0.7.4",
+  "version": "0.9.0",
   "private": false,
   "type": "module",
   "description": "Clivly CLI — scaffold a CRM into your app (clivly init).",