@clivly/core 0.2.0 → 0.3.0-next.2

package/dist/entity-heuristics.d.cts

@@ -1,13 +1,35 @@
+import { Scored } from "./mapping-score.cjs";
+
 //#region src/entity-heuristics.d.ts
 declare const TARGET_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
 type TargetConcept = (typeof TARGET_CONCEPTS)[number];
 declare function suggestCursorField(columnKeys: string[]): string | null;
-declare function suggestConcept(tableName: string): TargetConcept | null;
 declare function matchesConcept(tableName: string, concept: TargetConcept): {
   exact: boolean;
 } | null;
-declare function suggestFieldMap(concept: TargetConcept, columns: string[]): Record<string, string>;
-declare function requiredFieldsFor(concept: TargetConcept): string[];
+interface DiscoveredColumnMeta {
+  isForeignKey?: boolean;
+  isPrimaryKey?: boolean;
+  name: string;
+  nullable?: boolean;
+  references?: {
+    table: string;
+    column: string;
+  };
+  type?: string;
+}
+interface ScoredTable {
+  columns: string[];
+  columnsMeta?: DiscoveredColumnMeta[];
+  name: string;
+  rowCount?: number;
+}
+declare function scoreConcepts(table: ScoredTable): Scored<TargetConcept>[];
+declare function topConcept(table: ScoredTable): {
+  best: Scored<TargetConcept>;
+  ambiguous: boolean;
+} | null;
+declare function requiredFieldsFor(concept: TargetConcept | "custom"): string[];
 declare function validateMapping(requiredFields: string[], fieldMap: Record<string, string>): {
   valid: boolean;
   missing: string[];
@@ -28,16 +50,19 @@ interface RelationshipSuggestion {
   name: string;
   via: SuggestedVia;
 }
-interface HeuristicTable {
-  columns: string[];
-  name: string;
-}
 /**
- * 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.
+ * Suggest contact→company relationships. When the source table carries FK
+ * metadata (`references`), the target table is a *fact*, not a name guess —
+ * that scores highest. Without metadata (v1 hosts) we fall back to the legacy
+ * FK-name hints at a lower tier.
  */
-declare function suggestRelationships(source: HeuristicTable, allTables: HeuristicTable[]): RelationshipSuggestion[];
+declare function scoreRelationships(source: ScoredTable, allTables: ScoredTable[]): Scored<RelationshipSuggestion>[];
+interface FieldSuggestion {
+  column: string;
+  field: string;
+  required: boolean;
+}
+declare function scoreFieldMap(concept: TargetConcept, table: ScoredTable): Scored<FieldSuggestion>[];
+declare function toFieldMap(scored: Scored<FieldSuggestion>[]): Record<string, string>;
 //#endregion
-export { RelationshipSuggestion, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, suggestConcept, suggestCursorField, suggestDiscriminatorColumns, suggestFieldMap, suggestRelationships, validateMapping };
+export { 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,13 +1,35 @@
+import { Scored } from "./mapping-score.mjs";
+
 //#region src/entity-heuristics.d.ts
 declare const TARGET_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
 type TargetConcept = (typeof TARGET_CONCEPTS)[number];
 declare function suggestCursorField(columnKeys: string[]): string | null;
-declare function suggestConcept(tableName: string): TargetConcept | null;
 declare function matchesConcept(tableName: string, concept: TargetConcept): {
   exact: boolean;
 } | null;
-declare function suggestFieldMap(concept: TargetConcept, columns: string[]): Record<string, string>;
-declare function requiredFieldsFor(concept: TargetConcept): string[];
+interface DiscoveredColumnMeta {
+  isForeignKey?: boolean;
+  isPrimaryKey?: boolean;
+  name: string;
+  nullable?: boolean;
+  references?: {
+    table: string;
+    column: string;
+  };
+  type?: string;
+}
+interface ScoredTable {
+  columns: string[];
+  columnsMeta?: DiscoveredColumnMeta[];
+  name: string;
+  rowCount?: number;
+}
+declare function scoreConcepts(table: ScoredTable): Scored<TargetConcept>[];
+declare function topConcept(table: ScoredTable): {
+  best: Scored<TargetConcept>;
+  ambiguous: boolean;
+} | null;
+declare function requiredFieldsFor(concept: TargetConcept | "custom"): string[];
 declare function validateMapping(requiredFields: string[], fieldMap: Record<string, string>): {
   valid: boolean;
   missing: string[];
@@ -28,16 +50,19 @@ interface RelationshipSuggestion {
   name: string;
   via: SuggestedVia;
 }
-interface HeuristicTable {
-  columns: string[];
-  name: string;
-}
 /**
- * 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.
+ * Suggest contact→company relationships. When the source table carries FK
+ * metadata (`references`), the target table is a *fact*, not a name guess —
+ * that scores highest. Without metadata (v1 hosts) we fall back to the legacy
+ * FK-name hints at a lower tier.
  */
-declare function suggestRelationships(source: HeuristicTable, allTables: HeuristicTable[]): RelationshipSuggestion[];
+declare function scoreRelationships(source: ScoredTable, allTables: ScoredTable[]): Scored<RelationshipSuggestion>[];
+interface FieldSuggestion {
+  column: string;
+  field: string;
+  required: boolean;
+}
+declare function scoreFieldMap(concept: TargetConcept, table: ScoredTable): Scored<FieldSuggestion>[];
+declare function toFieldMap(scored: Scored<FieldSuggestion>[]): Record<string, string>;
 //#endregion
-export { RelationshipSuggestion, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, suggestConcept, suggestCursorField, suggestDiscriminatorColumns, suggestFieldMap, suggestRelationships, validateMapping };
+export { DiscoveredColumnMeta, FieldSuggestion, RelationshipSuggestion, ScoredTable, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };

package/dist/entity-heuristics.mjs

@@ -1,3 +1,5 @@
+import { MATERIALIZING_CONCEPTS } from "./entity-config.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 = [
 	"contact",
@@ -115,7 +117,7 @@ const CONCEPT_FIELDS = {
 		{
 			field: "name",
 			candidates: ["name", "title"],
-			required: false
+			required: true
 		},
 		{
 			field: "value",
@@ -207,12 +209,7 @@ function suggestCursorField(columnKeys) {
 	}
 	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;
-}
+const MATERIALIZING = new Set(MATERIALIZING_CONCEPTS);
 function matchesConcept(tableName, concept) {
 	const normalized = tableName.toLowerCase();
 	const entry = TABLE_PATTERNS.find((p) => p.concept === concept);
@@ -221,19 +218,64 @@ function matchesConcept(tableName, concept) {
 	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;
+function metaFor(table, column) {
+	return table.columnsMeta?.find((c) => c.name === column);
+}
+function hasDefiningColumn(concept, columns) {
+	const lower = new Set(columns.map((c) => c.toLowerCase()));
+	const required = CONCEPT_FIELDS[concept].filter((f) => f.required);
+	return required.length > 0 && required.every((f) => f.candidates.some((c) => lower.has(c)));
+}
+function scoreConcepts(table) {
+	const out = [];
+	for (const concept of TARGET_CONCEPTS) {
+		if (!MATERIALIZING.has(concept)) continue;
+		const nameMatch = matchesConcept(table.name, concept);
+		if (!nameMatch) continue;
+		let score = 0;
+		const reasons = [];
+		if (nameMatch.exact) {
+			score += W.nameExact;
+			reasons.push(`name matches "${table.name}"`);
+		} else {
+			score += W.nameSubstring;
+			reasons.push(`name looks like ${concept}`);
 		}
+		if (hasDefiningColumn(concept, table.columns)) {
+			score += W.definingColumn;
+			reasons.push(`has the columns a ${concept} needs`);
+		}
+		if (table.columnsMeta?.some((c) => c.isPrimaryKey)) {
+			score += W.hasPrimaryKey;
+			reasons.push("has primary key");
+		}
+		if (table.rowCount !== void 0) if (table.rowCount === 0) {
+			score += W.emptyTable;
+			reasons.push("table is empty");
+		} else {
+			score += W.hasRows;
+			reasons.push(`${table.rowCount.toLocaleString("en-US")} rows`);
+		}
+		out.push({
+			value: concept,
+			score,
+			tier: tierFor(score, CONCEPT_TIERS),
+			reasons
+		});
 	}
-	return map;
+	return out.sort((a, b) => b.score - a.score);
+}
+function topConcept(table) {
+	const ranked = scoreConcepts(table);
+	const best = ranked[0];
+	if (!best) return null;
+	return {
+		best,
+		ambiguous: isAmbiguous(ranked)
+	};
 }
 function requiredFieldsFor(concept) {
+	if (concept === "custom") return [];
 	return CONCEPT_FIELDS[concept].filter((f) => f.required).map((f) => f.field);
 }
 function validateMapping(requiredFields, fieldMap) {
@@ -261,14 +303,6 @@ function suggestDiscriminatorColumns(columns) {
 	}
 	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",
@@ -286,50 +320,112 @@ function firstMatchingColumn(columns, hints) {
 	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.
+* Suggest contact→company relationships. When the source table carries FK
+* metadata (`references`), the target table is a *fact*, not a name guess —
+* that scores highest. Without metadata (v1 hosts) we fall back to the legacy
+* FK-name hints at a lower tier.
 */
-function suggestRelationships(source, allTables) {
-	const companyTables = allTables.filter((t) => t.name !== source.name && suggestConcept(t.name) === "company");
+function scoreRelationships(source, allTables) {
+	const companyTables = allTables.filter((t) => t.name !== source.name && topConcept(t)?.best.value === "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}`
-			}
+	const companyNames = new Set(companyTables.map((t) => t.name.toLowerCase()));
+	const out = [];
+	const seenTargets = /* @__PURE__ */ new Set();
+	for (const col of source.columnsMeta ?? []) {
+		const ref = col.references;
+		if (!(ref && companyNames.has(ref.table.toLowerCase()))) continue;
+		if (seenTargets.has(ref.table.toLowerCase())) continue;
+		seenTargets.add(ref.table.toLowerCase());
+		out.push({
+			value: {
+				name: "company",
+				entityTable: ref.table,
+				via: {
+					fkOn: "contact",
+					column: `${source.name}.${col.name}`
+				}
+			},
+			score: W.fkResolved,
+			tier: tierFor(W.fkResolved, RELATIONSHIP_TIERS),
+			reasons: [`foreign key → ${ref.table}.${ref.column}`]
 		});
 	}
-	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({
+	if (source.columnsMeta?.length) return out.sort((a, b) => b.score - a.score);
+	const contactFk = firstMatchingColumn(source.columns, COMPANY_FK_HINTS);
+	if (contactFk) out.push({
+		value: {
 			name: "company",
-			entityTable: companyTables.find((c) => c.name !== table.name)?.name ?? companyTables[0]?.name ?? "",
+			entityTable: companyTables[0]?.name ?? "",
 			via: {
-				through: table.name,
-				localKey,
-				foreignKey
+				fkOn: "contact",
+				column: `${source.name}.${contactFk}`
 			}
+		},
+		score: W.fkNameHint,
+		tier: tierFor(W.fkNameHint, RELATIONSHIP_TIERS),
+		reasons: [`column "${contactFk}" looks like a company link`]
+	});
+	return out.sort((a, b) => b.score - a.score);
+}
+const FIELD_TYPE_EXPECTATION = {
+	name: "text",
+	email: "text",
+	domain: "text",
+	stage: "text",
+	status: "text",
+	subject: "text",
+	body: "text",
+	summary: "text",
+	type: "text",
+	value: "numeric",
+	createdAt: "timestamp"
+};
+function typeFits(field, type) {
+	const expectation = FIELD_TYPE_EXPECTATION[field];
+	if (!(expectation && type)) return null;
+	if (expectation === "text") return isTextLike(type);
+	if (expectation === "numeric") return isNumericLike(type);
+	return isTimestampLike(type);
+}
+function scoreFieldMap(concept, table) {
+	const lowerToActual = new Map(table.columns.map((c) => [c.toLowerCase(), c]));
+	const out = [];
+	for (const { field, candidates, required } of CONCEPT_FIELDS[concept]) for (const candidate of candidates) {
+		const column = lowerToActual.get(candidate);
+		if (!column) continue;
+		let score = W.fieldNameMatch;
+		const reasons = [`name matches "${column}"`];
+		const meta = metaFor(table, column);
+		const fits = typeFits(field, meta?.type);
+		if (fits === true) {
+			score += W.typeCompatible;
+			reasons.push(`type ${meta?.type}`);
+		} else if (fits === false) {
+			score += W.typeMismatch;
+			reasons.push(`type ${meta?.type} does not fit ${field}`);
+		}
+		if (required && meta?.nullable === false) {
+			score += W.requiredNotNull;
+			reasons.push("not null");
+		}
+		out.push({
+			value: {
+				field,
+				column,
+				required
+			},
+			score,
+			tier: tierFor(score, FIELD_TIERS),
+			reasons
 		});
+		break;
 	}
-	return suggestions;
+	return out;
+}
+function toFieldMap(scored) {
+	const map = {};
+	for (const { value } of scored) map[value.field] = value.column;
+	return map;
 }
 //#endregion
-export { TARGET_CONCEPTS, matchesConcept, requiredFieldsFor, suggestConcept, suggestCursorField, suggestDiscriminatorColumns, suggestFieldMap, suggestRelationships, validateMapping };
+export { TARGET_CONCEPTS, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };

package/dist/index.cjs

@@ -8,6 +8,7 @@ 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.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;

package/dist/index.d.cts

@@ -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, UpdateDealInput, UpdateTaskInput } from "./types.cjs";
+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, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.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 { 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 };
+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, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, Note, type PersistAction, RecordSource, 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, UpdateDealInput, UpdateTaskInput } from "./types.mjs";
+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.mjs";
 import { CRMAdapter } from "./adapter.mjs";
 import { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom } from "./auth-adapter.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 { 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.mjs";
 import { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
 import { EntityMappingRow, mappingsToEntitiesConfig } from "./mappings-config.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, 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 };
+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, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, Note, type PersistAction, RecordSource, 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, ClivlyConfigError, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.mjs";
+import { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, MATERIALIZING_CONCEPTS, 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, explainEntitiesConfig } from "./view-compiler.mjs";
 import { reconcile, runSync } from "./sync-engine.mjs";
-export { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };
+export { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, MATERIALIZING_CONCEPTS, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };

package/dist/mapping-score.cjs

@@ -0,0 +1,97 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/mapping-score.ts
+const CONCEPT_TIERS = {
+	high: 70,
+	medium: 40
+};
+const FIELD_TIERS = {
+	high: 70,
+	medium: 40
+};
+const RELATIONSHIP_TIERS = {
+	high: 60,
+	medium: 30
+};
+/** Two concept candidates closer than this are treated as ambiguous. */
+const AMBIGUITY_MARGIN = 15;
+/** Signal weights. Tuned against fixtures; adjust here, not at call sites. */
+const W = {
+	nameExact: 50,
+	nameSubstring: 25,
+	definingColumn: 20,
+	hasPrimaryKey: 10,
+	hasRows: 10,
+	emptyTable: -20,
+	fieldNameMatch: 50,
+	typeCompatible: 30,
+	typeMismatch: -30,
+	requiredNotNull: 10,
+	fkResolved: 60,
+	fkNameHint: 30,
+	joinTable: 20
+};
+function tierFor(score, t) {
+	if (score >= t.high) return "High";
+	if (score >= t.medium) return "Medium";
+	return "Low";
+}
+const TEXT_TYPES = [
+	"text",
+	"varchar",
+	"char",
+	"citext",
+	"uuid",
+	"string"
+];
+const NUMERIC_TYPES = [
+	"numeric",
+	"decimal",
+	"int",
+	"integer",
+	"bigint",
+	"smallint",
+	"float",
+	"double",
+	"real",
+	"money"
+];
+const TIMESTAMP_TYPES = [
+	"timestamp",
+	"timestamptz",
+	"date",
+	"datetime"
+];
+function matchesType(type, list) {
+	if (!type) return false;
+	const normalized = type.toLowerCase();
+	return list.some((t) => normalized.startsWith(t));
+}
+function isTextLike(type) {
+	return matchesType(type, TEXT_TYPES);
+}
+function isNumericLike(type) {
+	return matchesType(type, NUMERIC_TYPES);
+}
+function isTimestampLike(type) {
+	return matchesType(type, TIMESTAMP_TYPES);
+}
+/**
+* True when the top two candidates are too close to call. Callers must never
+* one-click apply an ambiguous result — the user picks.
+*/
+function isAmbiguous(ranked) {
+	const [first, second] = ranked;
+	if (!(first && second)) return false;
+	return first.score - second.score < 15;
+}
+//#endregion
+exports.AMBIGUITY_MARGIN = AMBIGUITY_MARGIN;
+exports.CONCEPT_TIERS = CONCEPT_TIERS;
+exports.FIELD_TIERS = FIELD_TIERS;
+exports.RELATIONSHIP_TIERS = RELATIONSHIP_TIERS;
+exports.W = W;
+exports.isAmbiguous = isAmbiguous;
+exports.isNumericLike = isNumericLike;
+exports.isTextLike = isTextLike;
+exports.isTimestampLike = isTimestampLike;
+exports.tierFor = tierFor;

package/dist/mapping-score.d.cts

@@ -0,0 +1,49 @@
+//#region src/mapping-score.d.ts
+type Tier = "High" | "Medium" | "Low";
+interface Scored<T> {
+  /** Human-readable chips, e.g. `type text`, `name matches "contacts"`. */
+  reasons: string[];
+  /** Internal — used for ranking and the apply threshold. Never rendered. */
+  score: number;
+  tier: Tier;
+  value: T;
+}
+/** Tier cut-offs: score >= high → High; >= medium → Medium; else Low. */
+interface Thresholds {
+  high: number;
+  medium: number;
+}
+declare const CONCEPT_TIERS: Thresholds;
+declare const FIELD_TIERS: Thresholds;
+declare const RELATIONSHIP_TIERS: Thresholds;
+/** Two concept candidates closer than this are treated as ambiguous. */
+declare const AMBIGUITY_MARGIN = 15;
+/** Signal weights. Tuned against fixtures; adjust here, not at call sites. */
+declare const W: {
+  readonly nameExact: 50;
+  readonly nameSubstring: 25;
+  readonly definingColumn: 20;
+  readonly hasPrimaryKey: 10;
+  readonly hasRows: 10;
+  readonly emptyTable: -20;
+  readonly fieldNameMatch: 50;
+  readonly typeCompatible: 30;
+  readonly typeMismatch: -30;
+  readonly requiredNotNull: 10;
+  readonly fkResolved: 60;
+  readonly fkNameHint: 30;
+  readonly joinTable: 20;
+};
+declare function tierFor(score: number, t: Thresholds): Tier;
+declare function isTextLike(type: string | undefined): boolean;
+declare function isNumericLike(type: string | undefined): boolean;
+declare function isTimestampLike(type: string | undefined): boolean;
+/**
+ * True when the top two candidates are too close to call. Callers must never
+ * one-click apply an ambiguous result — the user picks.
+ */
+declare function isAmbiguous(ranked: Array<{
+  score: number;
+}>): boolean;
+//#endregion
+export { AMBIGUITY_MARGIN, CONCEPT_TIERS, FIELD_TIERS, RELATIONSHIP_TIERS, Scored, Thresholds, Tier, W, isAmbiguous, isNumericLike, isTextLike, isTimestampLike, tierFor };

package/dist/mapping-score.d.mts

@@ -0,0 +1,49 @@
+//#region src/mapping-score.d.ts
+type Tier = "High" | "Medium" | "Low";
+interface Scored<T> {
+  /** Human-readable chips, e.g. `type text`, `name matches "contacts"`. */
+  reasons: string[];
+  /** Internal — used for ranking and the apply threshold. Never rendered. */
+  score: number;
+  tier: Tier;
+  value: T;
+}
+/** Tier cut-offs: score >= high → High; >= medium → Medium; else Low. */
+interface Thresholds {
+  high: number;
+  medium: number;
+}
+declare const CONCEPT_TIERS: Thresholds;
+declare const FIELD_TIERS: Thresholds;
+declare const RELATIONSHIP_TIERS: Thresholds;
+/** Two concept candidates closer than this are treated as ambiguous. */
+declare const AMBIGUITY_MARGIN = 15;
+/** Signal weights. Tuned against fixtures; adjust here, not at call sites. */
+declare const W: {
+  readonly nameExact: 50;
+  readonly nameSubstring: 25;
+  readonly definingColumn: 20;
+  readonly hasPrimaryKey: 10;
+  readonly hasRows: 10;
+  readonly emptyTable: -20;
+  readonly fieldNameMatch: 50;
+  readonly typeCompatible: 30;
+  readonly typeMismatch: -30;
+  readonly requiredNotNull: 10;
+  readonly fkResolved: 60;
+  readonly fkNameHint: 30;
+  readonly joinTable: 20;
+};
+declare function tierFor(score: number, t: Thresholds): Tier;
+declare function isTextLike(type: string | undefined): boolean;
+declare function isNumericLike(type: string | undefined): boolean;
+declare function isTimestampLike(type: string | undefined): boolean;
+/**
+ * True when the top two candidates are too close to call. Callers must never
+ * one-click apply an ambiguous result — the user picks.
+ */
+declare function isAmbiguous(ranked: Array<{
+  score: number;
+}>): boolean;
+//#endregion
+export { AMBIGUITY_MARGIN, CONCEPT_TIERS, FIELD_TIERS, RELATIONSHIP_TIERS, Scored, Thresholds, Tier, W, isAmbiguous, isNumericLike, isTextLike, isTimestampLike, tierFor };