@clivly/core 0.1.0 → 0.2.0

package/dist/entity-heuristics.mjs

@@ -0,0 +1,335 @@
+//#region src/entity-heuristics.ts
+const TARGET_CONCEPTS = [
+	"contact",
+	"company",
+	"deal",
+	"activity",
+	"conversation",
+	"note"
+];
+const TABLE_PATTERNS = [
+	{
+		concept: "contact",
+		names: [
+			"users",
+			"customers",
+			"clients",
+			"accounts",
+			"participants",
+			"attendees",
+			"people",
+			"members",
+			"contacts"
+		]
+	},
+	{
+		concept: "company",
+		names: [
+			"companies",
+			"organizations",
+			"organisations",
+			"orgs",
+			"teams",
+			"businesses",
+			"accounts"
+		]
+	},
+	{
+		concept: "deal",
+		names: [
+			"deals",
+			"opportunities",
+			"subscriptions",
+			"orders",
+			"invoices",
+			"sales"
+		]
+	},
+	{
+		concept: "conversation",
+		names: [
+			"conversations",
+			"messages",
+			"tickets",
+			"threads",
+			"chats",
+			"inbox"
+		]
+	},
+	{
+		concept: "activity",
+		names: [
+			"events",
+			"activities",
+			"jobs",
+			"logs",
+			"audit",
+			"shifts",
+			"scans",
+			"sessions"
+		]
+	},
+	{
+		concept: "note",
+		names: [
+			"notes",
+			"comments",
+			"annotations"
+		]
+	}
+];
+const CONCEPT_FIELDS = {
+	contact: [{
+		field: "name",
+		candidates: [
+			"name",
+			"full_name",
+			"fullname",
+			"display_name"
+		],
+		required: false
+	}, {
+		field: "email",
+		candidates: ["email", "email_address"],
+		required: true
+	}],
+	company: [{
+		field: "name",
+		candidates: [
+			"name",
+			"company_name",
+			"legal_name",
+			"title"
+		],
+		required: true
+	}, {
+		field: "domain",
+		candidates: [
+			"domain",
+			"website",
+			"url"
+		],
+		required: false
+	}],
+	deal: [
+		{
+			field: "name",
+			candidates: ["name", "title"],
+			required: false
+		},
+		{
+			field: "value",
+			candidates: [
+				"value",
+				"amount",
+				"total",
+				"price"
+			],
+			required: false
+		},
+		{
+			field: "stage",
+			candidates: [
+				"stage",
+				"status",
+				"state"
+			],
+			required: false
+		}
+	],
+	activity: [
+		{
+			field: "type",
+			candidates: [
+				"type",
+				"kind",
+				"event_type"
+			],
+			required: false
+		},
+		{
+			field: "summary",
+			candidates: [
+				"summary",
+				"description",
+				"message",
+				"title"
+			],
+			required: false
+		},
+		{
+			field: "createdAt",
+			candidates: [
+				"created_at",
+				"createdat",
+				"timestamp"
+			],
+			required: false
+		}
+	],
+	conversation: [{
+		field: "status",
+		candidates: ["status", "state"],
+		required: false
+	}, {
+		field: "subject",
+		candidates: [
+			"subject",
+			"title",
+			"preview"
+		],
+		required: false
+	}],
+	note: [{
+		field: "body",
+		candidates: [
+			"body",
+			"content",
+			"text",
+			"note"
+		],
+		required: true
+	}]
+};
+const CURSOR_CANDIDATES = [
+	"updatedat",
+	"updated_at",
+	"modifiedat",
+	"modified_at",
+	"createdat",
+	"created_at"
+];
+function suggestCursorField(columnKeys) {
+	const lowerToActual = new Map(columnKeys.map((c) => [c.toLowerCase(), c]));
+	for (const candidate of CURSOR_CANDIDATES) {
+		const match = lowerToActual.get(candidate);
+		if (match) return match;
+	}
+	return null;
+}
+function suggestConcept(tableName) {
+	const normalized = tableName.toLowerCase();
+	for (const { concept, names } of TABLE_PATTERNS) if (names.includes(normalized)) return concept;
+	for (const { concept, names } of TABLE_PATTERNS) if (names.some((name) => normalized.includes(name))) return concept;
+	return null;
+}
+function matchesConcept(tableName, concept) {
+	const normalized = tableName.toLowerCase();
+	const entry = TABLE_PATTERNS.find((p) => p.concept === concept);
+	if (!entry) return null;
+	if (entry.names.includes(normalized)) return { exact: true };
+	if (entry.names.some((name) => normalized.includes(name))) return { exact: false };
+	return null;
+}
+function suggestFieldMap(concept, columns) {
+	const lowerToActual = new Map(columns.map((c) => [c.toLowerCase(), c]));
+	const map = {};
+	for (const { field, candidates } of CONCEPT_FIELDS[concept]) for (const candidate of candidates) {
+		const match = lowerToActual.get(candidate);
+		if (match) {
+			map[field] = match;
+			break;
+		}
+	}
+	return map;
+}
+function requiredFieldsFor(concept) {
+	return CONCEPT_FIELDS[concept].filter((f) => f.required).map((f) => f.field);
+}
+function validateMapping(requiredFields, fieldMap) {
+	const missing = requiredFields.filter((field) => !fieldMap[field]);
+	return {
+		valid: missing.length === 0,
+		missing
+	};
+}
+const DISCRIMINATOR_COLUMNS = [
+	"role",
+	"type",
+	"kind",
+	"status",
+	"state",
+	"category",
+	"tier"
+];
+function suggestDiscriminatorColumns(columns) {
+	const lowerToActual = new Map(columns.map((c) => [c.toLowerCase(), c]));
+	const out = [];
+	for (const name of DISCRIMINATOR_COLUMNS) {
+		const match = lowerToActual.get(name);
+		if (match) out.push(match);
+	}
+	return out;
+}
+const CONTACT_FK_HINTS = [
+	"user_id",
+	"owner_id",
+	"contact_id",
+	"member_id",
+	"person_id",
+	"created_by"
+];
+const COMPANY_FK_HINTS = [
+	"organization_id",
+	"organisation_id",
+	"org_id",
+	"company_id",
+	"account_id",
+	"team_id"
+];
+function firstMatchingColumn(columns, hints) {
+	const lowerToActual = new Map(columns.map((c) => [c.toLowerCase(), c]));
+	for (const hint of hints) {
+		const match = lowerToActual.get(hint);
+		if (match) return match;
+	}
+	return null;
+}
+/**
+* Suggest contact→company relationships for a contact-concept source table by
+* inspecting FK column names across the discovered schema. Detects all three
+* DSL shapes: FK-on-contact, FK-on-company, and a join table. Suggestions are
+* candidates only — the developer confirms.
+*/
+function suggestRelationships(source, allTables) {
+	const companyTables = allTables.filter((t) => t.name !== source.name && suggestConcept(t.name) === "company");
+	if (companyTables.length === 0) return [];
+	const suggestions = [];
+	const contactFk = firstMatchingColumn(source.columns, COMPANY_FK_HINTS);
+	if (contactFk) suggestions.push({
+		name: "company",
+		entityTable: companyTables[0]?.name ?? "",
+		via: {
+			fkOn: "contact",
+			column: `${source.name}.${contactFk}`
+		}
+	});
+	for (const company of companyTables) {
+		const companyFk = firstMatchingColumn(company.columns, CONTACT_FK_HINTS);
+		if (companyFk) suggestions.push({
+			name: "company",
+			entityTable: company.name,
+			via: {
+				fkOn: "company",
+				column: `${company.name}.${companyFk}`
+			}
+		});
+	}
+	for (const table of allTables) {
+		if (table.name === source.name) continue;
+		const localKey = firstMatchingColumn(table.columns, CONTACT_FK_HINTS);
+		const foreignKey = firstMatchingColumn(table.columns, COMPANY_FK_HINTS);
+		if (localKey && foreignKey) suggestions.push({
+			name: "company",
+			entityTable: companyTables.find((c) => c.name !== table.name)?.name ?? companyTables[0]?.name ?? "",
+			via: {
+				through: table.name,
+				localKey,
+				foreignKey
+			}
+		});
+	}
+	return suggestions;
+}
+//#endregion
+export { TARGET_CONCEPTS, matchesConcept, requiredFieldsFor, suggestConcept, suggestCursorField, suggestDiscriminatorColumns, suggestFieldMap, suggestRelationships, validateMapping };

package/dist/index.cjs

@@ -0,0 +1,26 @@
+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_mapping_form = require("./mapping-form.cjs");
+const require_mappings_config = require("./mappings-config.cjs");
+const require_view_compiler = require("./view-compiler.cjs");
+const require_sync_engine = require("./sync-engine.cjs");
+exports.CANONICAL_FIELDS = require_entity_config.CANONICAL_FIELDS;
+exports.CRM_CONCEPTS = require_entity_config.CRM_CONCEPTS;
+exports.ClivlyConfigError = require_entity_config.ClivlyConfigError;
+exports.authCustom = require_auth_adapter.authCustom;
+exports.buildFilterFromDiscriminator = require_mapping_form.buildFilterFromDiscriminator;
+exports.buildRelationships = require_mapping_form.buildRelationships;
+exports.compileEntityView = require_view_compiler.compileEntityView;
+exports.compileEntityViews = require_view_compiler.compileEntityViews;
+exports.defineClivlyConfig = require_entity_config.defineClivlyConfig;
+exports.entitiesConfigSchema = require_entity_config.entitiesConfigSchema;
+exports.explainEntitiesConfig = require_view_compiler.explainEntitiesConfig;
+exports.filterSchema = require_entity_config.filterSchema;
+exports.mappingsToEntitiesConfig = require_mappings_config.mappingsToEntitiesConfig;
+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.validateEntitiesConfig = require_entity_config.validateEntitiesConfig;

package/dist/index.d.cts

@@ -0,0 +1,9 @@
+import { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, 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, 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 { CompileOptions, CompiledView, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig } from "./view-compiler.cjs";
+import { EntitySyncResult, MirrorRecord, PersistAction, SourceRow, SyncAction, SyncResult, SyncStore, reconcile, runSync } from "./sync-engine.cjs";
+export { Activity, ActivityType, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, type CrmConcept, type CrmMembership, CrmRole, Deal, DealStage, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, type MembershipResolver, type MirrorRecord, Note, type PersistAction, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SyncAction, type SyncResult, type SyncStore, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateDealInput, UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };

package/dist/index.d.mts

@@ -1,9 +1,9 @@
-import { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateTaskInput } from "./types.mjs";
+import { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateDealInput, UpdateTaskInput } from "./types.mjs";
 import { CRMAdapter } from "./adapter.mjs";
 import { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom } from "./auth-adapter.mjs";
-import { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.mjs";
+import { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.mjs";
 import { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
 import { EntityMappingRow, mappingsToEntitiesConfig } from "./mappings-config.mjs";
-import { CompileOptions, CompiledView, compileEntityView, compileEntityViews } from "./view-compiler.mjs";
+import { CompileOptions, CompiledView, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig } from "./view-compiler.mjs";
 import { EntitySyncResult, MirrorRecord, PersistAction, SourceRow, SyncAction, SyncResult, SyncStore, reconcile, runSync } from "./sync-engine.mjs";
-export { Activity, ActivityType, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, type CrmConcept, type CrmMembership, CrmRole, Deal, DealStage, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type FilterExpr, type FilterValue, type MembershipResolver, type MirrorRecord, Note, type PersistAction, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SyncAction, type SyncResult, type SyncStore, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };
+export { Activity, ActivityType, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, type CrmConcept, type CrmMembership, CrmRole, Deal, DealStage, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, type MembershipResolver, type MirrorRecord, Note, type PersistAction, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SyncAction, type SyncResult, type SyncStore, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateDealInput, UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { authCustom } from "./auth-adapter.mjs";
-import { CANONICAL_FIELDS, CRM_CONCEPTS, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.mjs";
+import { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.mjs";
 import { buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
 import { mappingsToEntitiesConfig } from "./mappings-config.mjs";
-import { compileEntityView, compileEntityViews } from "./view-compiler.mjs";
+import { compileEntityView, compileEntityViews, explainEntitiesConfig } from "./view-compiler.mjs";
 import { reconcile, runSync } from "./sync-engine.mjs";
-export { CANONICAL_FIELDS, CRM_CONCEPTS, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };
+export { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };

package/dist/mapping-form.cjs

@@ -0,0 +1,50 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/mapping-form.ts
+/**
+* Build the filter for a discriminated entity: rows where `column` equals
+* `value` belong to this entity (e.g. `role = "owner"`). Returns `undefined`
+* when either side is blank so the caller can omit the filter entirely.
+*/
+function buildFilterFromDiscriminator(column, value) {
+	const col = column?.trim();
+	const val = value.trim();
+	if (!col || val === "") return;
+	return { [col]: { eq: val } };
+}
+/**
+* A stable identity string for a relationship's `via`. Two candidates on the
+* same source table always differ in their join (`fkOn`+column, join-table
+* keys, or raw SQL), so this disambiguates candidates the heuristic gives the
+* same `name` (every contact→company candidate is named "company").
+*/
+function relationshipViaSignature(via) {
+	if ("fkOn" in via) return `fk:${via.fkOn}:${via.column}`;
+	if ("through" in via) return `through:${via.through}:${via.localKey}:${via.foreignKey}`;
+	return `raw:${via.$raw}`;
+}
+/**
+* Compile the selected relationship candidates into the persisted
+* `RelationshipsMap`. Returns `undefined` for an empty selection so the caller
+* omits the field.
+*/
+function buildRelationships(candidates) {
+	if (candidates.length === 0) return;
+	const map = {};
+	for (const candidate of candidates) {
+		let key = candidate.name;
+		let suffix = 2;
+		while (key in map) {
+			key = `${candidate.name}_${suffix}`;
+			suffix++;
+		}
+		map[key] = {
+			entity: candidate.entityTable,
+			via: candidate.via
+		};
+	}
+	return map;
+}
+//#endregion
+exports.buildFilterFromDiscriminator = buildFilterFromDiscriminator;
+exports.buildRelationships = buildRelationships;
+exports.relationshipViaSignature = relationshipViaSignature;

package/dist/mapping-form.d.cts

@@ -0,0 +1,35 @@
+import { FilterExpr, RelationshipVia, RelationshipsMap } from "./entity-config.cjs";
+
+//#region src/mapping-form.d.ts
+/**
+ * A relationship the mapping UI can offer or has configured, in the shape the
+ * heuristic suggester produces. `entityTable` is the *host table name*; the
+ * mappings→config compiler resolves it to the canonical entity key, so it is
+ * persisted verbatim as the relationship's `entity` reference.
+ */
+interface RelationshipCandidate {
+  entityTable: string;
+  name: string;
+  via: RelationshipVia;
+}
+/**
+ * Build the filter for a discriminated entity: rows where `column` equals
+ * `value` belong to this entity (e.g. `role = "owner"`). Returns `undefined`
+ * when either side is blank so the caller can omit the filter entirely.
+ */
+declare function buildFilterFromDiscriminator(column: string | null | undefined, value: string): FilterExpr | undefined;
+/**
+ * A stable identity string for a relationship's `via`. Two candidates on the
+ * same source table always differ in their join (`fkOn`+column, join-table
+ * keys, or raw SQL), so this disambiguates candidates the heuristic gives the
+ * same `name` (every contact→company candidate is named "company").
+ */
+declare function relationshipViaSignature(via: RelationshipVia): string;
+/**
+ * Compile the selected relationship candidates into the persisted
+ * `RelationshipsMap`. Returns `undefined` for an empty selection so the caller
+ * omits the field.
+ */
+declare function buildRelationships(candidates: RelationshipCandidate[]): RelationshipsMap | undefined;
+//#endregion
+export { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature };

package/dist/mappings-config.cjs

@@ -0,0 +1,99 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_entity_config = require("./entity-config.cjs");
+//#region src/mappings-config.ts
+const RESERVED_FIELD = "id";
+/**
+* Restrict a persisted field map to what the mirror can actually store: drop
+* the reserved `id` key (for every concept) and, for materialized concepts
+* (contact/company), any key that isn't canonical. This makes the pipeline
+* resilient to legacy or mis-suggested field maps — a stray `id` no longer
+* blocks the whole sync.
+*/
+function canonicalFields(concept, fieldMap) {
+	const allowed = require_entity_config.CANONICAL_FIELDS[concept];
+	const result = {};
+	for (const [field, column] of Object.entries(fieldMap)) {
+		if (field === RESERVED_FIELD) continue;
+		if (allowed && !allowed.includes(field)) continue;
+		result[field] = column;
+	}
+	return result;
+}
+const DEFAULT_ROLE = "primary";
+const ACTIVE_STATUS = "active";
+function isEligible(row) {
+	return (row.status ?? ACTIVE_STATUS) === ACTIVE_STATUS && Object.keys(row.fieldMap ?? {}).length > 0;
+}
+/**
+* Preferred key for a row: the bare source table when it backs a single entity,
+* else role-suffixed so multiple roles on one table stay distinct and stable
+* (the primary role keeps the bare name). Uniqueness is still enforced by the
+* caller in case two rows land on the same preferred key.
+*/
+function preferredKey(row, tableCounts) {
+	const role = row.role ?? DEFAULT_ROLE;
+	if ((tableCounts.get(row.sourceTable) ?? 0) <= 1) return row.sourceTable;
+	return role === DEFAULT_ROLE ? row.sourceTable : `${row.sourceTable}__${role}`;
+}
+function uniquify(base, used) {
+	if (!used.has(base)) {
+		used.add(base);
+		return base;
+	}
+	let suffix = 2;
+	while (used.has(`${base}__${suffix}`)) suffix++;
+	const key = `${base}__${suffix}`;
+	used.add(key);
+	return key;
+}
+function buildEntity(row, refIndex) {
+	const entity = {
+		concept: row.targetConcept,
+		source: row.sourceTable,
+		role: row.role ?? DEFAULT_ROLE,
+		fields: canonicalFields(row.targetConcept, row.fieldMap)
+	};
+	if (row.filter && Object.keys(row.filter).length > 0) entity.filter = row.filter;
+	if (row.relationships && Object.keys(row.relationships).length > 0) {
+		const relationships = {};
+		for (const [name, spec] of Object.entries(row.relationships)) {
+			const rel = spec;
+			relationships[name] = {
+				entity: refIndex.get(rel.entity) ?? rel.entity,
+				via: rel.via
+			};
+		}
+		entity.relationships = relationships;
+	}
+	return entity;
+}
+/**
+* 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.
+*/
+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);
+	const used = /* @__PURE__ */ new Set();
+	const tableAnchor = /* @__PURE__ */ new Map();
+	const assigned = [];
+	for (const row of eligible) {
+		const key = uniquify(preferredKey(row, tableCounts), used);
+		assigned.push({
+			row,
+			key
+		});
+		if ((row.role ?? DEFAULT_ROLE) === DEFAULT_ROLE || !tableAnchor.has(row.sourceTable)) tableAnchor.set(row.sourceTable, key);
+	}
+	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);
+	const entities = {};
+	for (const { row, key } of assigned) entities[key] = buildEntity(row, refIndex);
+	return { entities };
+}
+//#endregion
+exports.mappingsToEntitiesConfig = mappingsToEntitiesConfig;

package/dist/mappings-config.d.cts

@@ -0,0 +1,41 @@
+import { ClivlyEntitiesConfig } from "./entity-config.cjs";
+
+//#region 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;
+  relationships?: Record<string, unknown> | null;
+  role?: string | null;
+  sourceTable: string;
+  status?: string | null;
+  targetConcept: string;
+}
+/**
+ * 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 { EntityMappingRow, mappingsToEntitiesConfig };

package/dist/mappings-config.mjs

@@ -1,4 +1,23 @@
+import { CANONICAL_FIELDS } from "./entity-config.mjs";
 //#region src/mappings-config.ts
+const RESERVED_FIELD = "id";
+/**
+* Restrict a persisted field map to what the mirror can actually store: drop
+* the reserved `id` key (for every concept) and, for materialized concepts
+* (contact/company), any key that isn't canonical. This makes the pipeline
+* resilient to legacy or mis-suggested field maps — a stray `id` no longer
+* blocks the whole sync.
+*/
+function canonicalFields(concept, fieldMap) {
+	const allowed = CANONICAL_FIELDS[concept];
+	const result = {};
+	for (const [field, column] of Object.entries(fieldMap)) {
+		if (field === RESERVED_FIELD) continue;
+		if (allowed && !allowed.includes(field)) continue;
+		result[field] = column;
+	}
+	return result;
+}
 const DEFAULT_ROLE = "primary";
 const ACTIVE_STATUS = "active";
 function isEligible(row) {
@@ -31,7 +50,7 @@ function buildEntity(row, refIndex) {
 		concept: row.targetConcept,
 		source: row.sourceTable,
 		role: row.role ?? DEFAULT_ROLE,
-		fields: { ...row.fieldMap }
+		fields: canonicalFields(row.targetConcept, row.fieldMap)
 	};
 	if (row.filter && Object.keys(row.filter).length > 0) entity.filter = row.filter;
 	if (row.relationships && Object.keys(row.relationships).length > 0) {