@clivly/core 0.2.0 → 0.3.0-next.1

package/dist/adapter.d.cts

@@ -1,4 +1,4 @@
-import { Activity, Company, Contact, ContactFilters, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, Deal, Task, TaskFilters, UpdateContactInput, UpdateDealInput, UpdateTaskInput } from "./types.cjs";
+import { Activity, Company, Contact, ContactFilters, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, Deal, RecordSource, Task, TaskFilters, UpdateContactInput, UpdateDealInput, UpdateTaskInput } from "./types.cjs";
 
 //#region src/adapter.d.ts
 /**
@@ -19,12 +19,22 @@ interface CRMAdapter {
   createTask(orgId: string, data: CreateTaskInput): Promise<Task>;
   deleteDeal(orgId: string, id: string): Promise<Deal | null>;
   getActivities(orgId: string, contactId: string): Promise<Activity[]>;
-  getCompanies(orgId: string): Promise<Company[]>;
+  getCompanies(orgId: string, filters?: {
+    source?: RecordSource;
+  }): Promise<Company[]>;
   getContact(orgId: string, id: string): Promise<Contact | null>;
   getContacts(orgId: string, filters?: ContactFilters): Promise<Contact[]>;
   getDeal(orgId: string, id: string): Promise<Deal | null>;
-  getDeals(orgId: string): Promise<Deal[]>;
+  getDeals(orgId: string, filters?: {
+    source?: RecordSource;
+  }): Promise<Deal[]>;
   getTasks(orgId: string, filters?: TaskFilters): Promise<Task[]>;
+  /**
+   * Move a deal to `stage` and reorder it directly after `afterId` (null = top
+   * of the column). The adapter computes the fractional `position` from the
+   * target column's current order; callers never pass a numeric position.
+   */
+  moveDeal(orgId: string, id: string, stage: Deal["stage"], afterId: string | null): Promise<Deal>;
   reopenTask(orgId: string, id: string): Promise<Task>;
   updateContact(orgId: string, id: string, data: UpdateContactInput): Promise<Contact>;
   updateDeal(orgId: string, id: string, data: UpdateDealInput): Promise<Deal>;

package/dist/adapter.d.mts

@@ -1,4 +1,4 @@
-import { Activity, Company, Contact, ContactFilters, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, Deal, Task, TaskFilters, UpdateContactInput, UpdateDealInput, UpdateTaskInput } from "./types.mjs";
+import { Activity, Company, Contact, ContactFilters, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, Deal, RecordSource, Task, TaskFilters, UpdateContactInput, UpdateDealInput, UpdateTaskInput } from "./types.mjs";
 
 //#region src/adapter.d.ts
 /**
@@ -19,12 +19,22 @@ interface CRMAdapter {
   createTask(orgId: string, data: CreateTaskInput): Promise<Task>;
   deleteDeal(orgId: string, id: string): Promise<Deal | null>;
   getActivities(orgId: string, contactId: string): Promise<Activity[]>;
-  getCompanies(orgId: string): Promise<Company[]>;
+  getCompanies(orgId: string, filters?: {
+    source?: RecordSource;
+  }): Promise<Company[]>;
   getContact(orgId: string, id: string): Promise<Contact | null>;
   getContacts(orgId: string, filters?: ContactFilters): Promise<Contact[]>;
   getDeal(orgId: string, id: string): Promise<Deal | null>;
-  getDeals(orgId: string): Promise<Deal[]>;
+  getDeals(orgId: string, filters?: {
+    source?: RecordSource;
+  }): Promise<Deal[]>;
   getTasks(orgId: string, filters?: TaskFilters): Promise<Task[]>;
+  /**
+   * Move a deal to `stage` and reorder it directly after `afterId` (null = top
+   * of the column). The adapter computes the fractional `position` from the
+   * target column's current order; callers never pass a numeric position.
+   */
+  moveDeal(orgId: string, id: string, stage: Deal["stage"], afterId: string | null): Promise<Deal>;
   reopenTask(orgId: string, id: string): Promise<Task>;
   updateContact(orgId: string, id: string, data: UpdateContactInput): Promise<Contact>;
   updateDeal(orgId: string, id: string, data: UpdateDealInput): Promise<Deal>;

package/dist/entity-config.cjs

@@ -49,9 +49,38 @@ const CANONICAL_FIELDS = {
 		"domain",
 		"industry",
 		"size"
+	],
+	deal: [
+		"name",
+		"value",
+		"stage"
 	]
 };
 /**
+* The concepts the mapping→sync pipeline can actually materialize into `crm_*`
+* tables. These are exactly the CANONICAL_FIELDS keys — the Drizzle sync store's
+* `persist()` throws for any other concept, so offering one (in the mapping
+* editor, in suggestions, or via the upsert API) is a broken affordance.
+*
+* The broader CRM_CONCEPTS set still validates structurally, so previously
+* stored rows for not-yet-materialized concepts keep rendering. When a concept
+* gains a sync-store path, add its canonical fields above and it joins this set
+* automatically (guarded by the MATERIALIZING_CONCEPTS drift test).
+*/
+const MATERIALIZING_CONCEPTS = [
+	"contact",
+	"company",
+	"deal"
+];
+/**
+* The org-defined custom-object target. Deliberately NOT a member of
+* CRM_CONCEPTS / CANONICAL_FIELDS / MATERIALIZING_CONCEPTS — a custom object has
+* no fixed canonical columns; its mapping's fieldMap keys ARE its properties.
+* Handled as an explicit branch wherever concepts are switched on, so the
+* canonical-concept invariants (and their drift test) stay intact.
+*/
+const CUSTOM_CONCEPT = "custom";
+/**
 * Operator forms for a single column predicate. All predicates on an entity are
 * AND-ed together. `$raw` (see FilterExpr) is the escape hatch for anything the
 * operators can't express.
@@ -125,8 +154,8 @@ const relationshipSchema = zod.z.strictObject({
 /** A named map of relationships, as stored on an entity / in the mappings row. */
 const relationshipsSchema = zod.z.record(zod.z.string(), relationshipSchema);
 const entitySchema = zod.z.strictObject({
-	/** Which CRM concept this entity maps onto. */
-	concept: zod.z.enum(CRM_CONCEPTS),
+	/** Which CRM concept this entity maps onto — a canonical concept or "custom". */
+	concept: zod.z.union([zod.z.enum(CRM_CONCEPTS), zod.z.literal(CUSTOM_CONCEPT)]),
 	/** Host table (or view) this entity is derived from. */
 	source: zod.z.string().min(1),
 	/**
@@ -144,7 +173,12 @@ const entitySchema = zod.z.strictObject({
 	*/
 	readOnly: zod.z.array(zod.z.string()).optional(),
 	/** Named relationships to other entities in this config. */
-	relationships: zod.z.record(zod.z.string(), relationshipSchema).optional()
+	relationships: zod.z.record(zod.z.string(), relationshipSchema).optional(),
+	/**
+	* For a "custom" entity, the crm_object_types row this materializes into.
+	* Required for custom (enforced at the API layer), unused for standard concepts.
+	*/
+	targetObjectTypeId: zod.z.string().min(1).optional()
 });
 const entitiesConfigSchema = zod.z.strictObject({ entities: zod.z.record(zod.z.string(), entitySchema).refine((e) => Object.keys(e).length > 0, { message: "at least one entity must be defined" }) });
 /** Thrown by `defineClivlyConfig({ strict: true })` on non-canonical field keys. */
@@ -305,7 +339,9 @@ function validateEntitiesConfig(config, schema) {
 //#endregion
 exports.CANONICAL_FIELDS = CANONICAL_FIELDS;
 exports.CRM_CONCEPTS = CRM_CONCEPTS;
+exports.CUSTOM_CONCEPT = CUSTOM_CONCEPT;
 exports.ClivlyConfigError = ClivlyConfigError;
+exports.MATERIALIZING_CONCEPTS = MATERIALIZING_CONCEPTS;
 exports.defineClivlyConfig = defineClivlyConfig;
 exports.entitiesConfigSchema = entitiesConfigSchema;
 exports.filterSchema = filterSchema;

package/dist/entity-config.d.cts

@@ -34,7 +34,29 @@ type CrmConcept = (typeof CRM_CONCEPTS)[number];
 declare const CANONICAL_FIELDS: {
   readonly contact: readonly ["name", "email", "title", "status"];
   readonly company: readonly ["name", "domain", "industry", "size"];
+  readonly deal: readonly ["name", "value", "stage"];
 };
+/**
+ * The concepts the mapping→sync pipeline can actually materialize into `crm_*`
+ * tables. These are exactly the CANONICAL_FIELDS keys — the Drizzle sync store's
+ * `persist()` throws for any other concept, so offering one (in the mapping
+ * editor, in suggestions, or via the upsert API) is a broken affordance.
+ *
+ * The broader CRM_CONCEPTS set still validates structurally, so previously
+ * stored rows for not-yet-materialized concepts keep rendering. When a concept
+ * gains a sync-store path, add its canonical fields above and it joins this set
+ * automatically (guarded by the MATERIALIZING_CONCEPTS drift test).
+ */
+declare const MATERIALIZING_CONCEPTS: readonly ["contact", "company", "deal"];
+type MaterializingConcept = (typeof MATERIALIZING_CONCEPTS)[number];
+/**
+ * The org-defined custom-object target. Deliberately NOT a member of
+ * CRM_CONCEPTS / CANONICAL_FIELDS / MATERIALIZING_CONCEPTS — a custom object has
+ * no fixed canonical columns; its mapping's fieldMap keys ARE its properties.
+ * Handled as an explicit branch wherever concepts are switched on, so the
+ * canonical-concept invariants (and their drift test) stay intact.
+ */
+declare const CUSTOM_CONCEPT: "custom";
 declare const filterValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodUnion<readonly [z.ZodObject<{
   eq: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
 }, z.core.$strict>, z.ZodObject<{
@@ -126,14 +148,14 @@ declare const relationshipsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
 }, z.core.$strict>>;
 type RelationshipsMap = z.infer<typeof relationshipsSchema>;
 declare const entitySchema: z.ZodObject<{
-  concept: z.ZodEnum<{
+  concept: z.ZodUnion<readonly [z.ZodEnum<{
     contact: "contact";
     company: "company";
     deal: "deal";
     activity: "activity";
     conversation: "conversation";
     note: "note";
-  }>;
+  }>, z.ZodLiteral<"custom">]>;
   source: z.ZodString;
   role: z.ZodOptional<z.ZodString>;
   filter: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
@@ -169,18 +191,19 @@ declare const entitySchema: z.ZodObject<{
       $raw: z.ZodString;
     }, z.core.$strict>]>;
   }, z.core.$strict>>>;
+  targetObjectTypeId: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 type ClivlyEntityConfig = z.infer<typeof entitySchema>;
 declare const entitiesConfigSchema: z.ZodObject<{
   entities: z.ZodRecord<z.ZodString, z.ZodObject<{
-    concept: z.ZodEnum<{
+    concept: z.ZodUnion<readonly [z.ZodEnum<{
       contact: "contact";
       company: "company";
       deal: "deal";
       activity: "activity";
       conversation: "conversation";
       note: "note";
-    }>;
+    }>, z.ZodLiteral<"custom">]>;
     source: z.ZodString;
     role: z.ZodOptional<z.ZodString>;
     filter: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
@@ -216,6 +239,7 @@ declare const entitiesConfigSchema: z.ZodObject<{
         $raw: z.ZodString;
       }, z.core.$strict>]>;
     }, z.core.$strict>>>;
+    targetObjectTypeId: z.ZodOptional<z.ZodString>;
   }, z.core.$strict>>;
 }, z.core.$strict>;
 type ClivlyEntitiesConfig = z.infer<typeof entitiesConfigSchema>;
@@ -269,4 +293,4 @@ interface ConfigValidationResult {
  */
 declare function validateEntitiesConfig(config: ClivlyEntitiesConfig, schema: DiscoveredSchemaTable[]): ConfigValidationResult;
 //#endregion
-export { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };
+export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/dist/entity-config.d.mts

@@ -34,7 +34,29 @@ type CrmConcept = (typeof CRM_CONCEPTS)[number];
 declare const CANONICAL_FIELDS: {
   readonly contact: readonly ["name", "email", "title", "status"];
   readonly company: readonly ["name", "domain", "industry", "size"];
+  readonly deal: readonly ["name", "value", "stage"];
 };
+/**
+ * The concepts the mapping→sync pipeline can actually materialize into `crm_*`
+ * tables. These are exactly the CANONICAL_FIELDS keys — the Drizzle sync store's
+ * `persist()` throws for any other concept, so offering one (in the mapping
+ * editor, in suggestions, or via the upsert API) is a broken affordance.
+ *
+ * The broader CRM_CONCEPTS set still validates structurally, so previously
+ * stored rows for not-yet-materialized concepts keep rendering. When a concept
+ * gains a sync-store path, add its canonical fields above and it joins this set
+ * automatically (guarded by the MATERIALIZING_CONCEPTS drift test).
+ */
+declare const MATERIALIZING_CONCEPTS: readonly ["contact", "company", "deal"];
+type MaterializingConcept = (typeof MATERIALIZING_CONCEPTS)[number];
+/**
+ * The org-defined custom-object target. Deliberately NOT a member of
+ * CRM_CONCEPTS / CANONICAL_FIELDS / MATERIALIZING_CONCEPTS — a custom object has
+ * no fixed canonical columns; its mapping's fieldMap keys ARE its properties.
+ * Handled as an explicit branch wherever concepts are switched on, so the
+ * canonical-concept invariants (and their drift test) stay intact.
+ */
+declare const CUSTOM_CONCEPT: "custom";
 declare const filterValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodUnion<readonly [z.ZodObject<{
   eq: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
 }, z.core.$strict>, z.ZodObject<{
@@ -126,14 +148,14 @@ declare const relationshipsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
 }, z.core.$strict>>;
 type RelationshipsMap = z.infer<typeof relationshipsSchema>;
 declare const entitySchema: z.ZodObject<{
-  concept: z.ZodEnum<{
+  concept: z.ZodUnion<readonly [z.ZodEnum<{
     contact: "contact";
     company: "company";
     deal: "deal";
     activity: "activity";
     conversation: "conversation";
     note: "note";
-  }>;
+  }>, z.ZodLiteral<"custom">]>;
   source: z.ZodString;
   role: z.ZodOptional<z.ZodString>;
   filter: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
@@ -169,18 +191,19 @@ declare const entitySchema: z.ZodObject<{
       $raw: z.ZodString;
     }, z.core.$strict>]>;
   }, z.core.$strict>>>;
+  targetObjectTypeId: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 type ClivlyEntityConfig = z.infer<typeof entitySchema>;
 declare const entitiesConfigSchema: z.ZodObject<{
   entities: z.ZodRecord<z.ZodString, z.ZodObject<{
-    concept: z.ZodEnum<{
+    concept: z.ZodUnion<readonly [z.ZodEnum<{
       contact: "contact";
       company: "company";
       deal: "deal";
       activity: "activity";
       conversation: "conversation";
       note: "note";
-    }>;
+    }>, z.ZodLiteral<"custom">]>;
     source: z.ZodString;
     role: z.ZodOptional<z.ZodString>;
     filter: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
@@ -216,6 +239,7 @@ declare const entitiesConfigSchema: z.ZodObject<{
         $raw: z.ZodString;
       }, z.core.$strict>]>;
     }, z.core.$strict>>>;
+    targetObjectTypeId: z.ZodOptional<z.ZodString>;
   }, z.core.$strict>>;
 }, z.core.$strict>;
 type ClivlyEntitiesConfig = z.infer<typeof entitiesConfigSchema>;
@@ -269,4 +293,4 @@ interface ConfigValidationResult {
  */
 declare function validateEntitiesConfig(config: ClivlyEntitiesConfig, schema: DiscoveredSchemaTable[]): ConfigValidationResult;
 //#endregion
-export { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };
+export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/dist/entity-config.mjs

@@ -48,9 +48,38 @@ const CANONICAL_FIELDS = {
 		"domain",
 		"industry",
 		"size"
+	],
+	deal: [
+		"name",
+		"value",
+		"stage"
 	]
 };
 /**
+* The concepts the mapping→sync pipeline can actually materialize into `crm_*`
+* tables. These are exactly the CANONICAL_FIELDS keys — the Drizzle sync store's
+* `persist()` throws for any other concept, so offering one (in the mapping
+* editor, in suggestions, or via the upsert API) is a broken affordance.
+*
+* The broader CRM_CONCEPTS set still validates structurally, so previously
+* stored rows for not-yet-materialized concepts keep rendering. When a concept
+* gains a sync-store path, add its canonical fields above and it joins this set
+* automatically (guarded by the MATERIALIZING_CONCEPTS drift test).
+*/
+const MATERIALIZING_CONCEPTS = [
+	"contact",
+	"company",
+	"deal"
+];
+/**
+* The org-defined custom-object target. Deliberately NOT a member of
+* CRM_CONCEPTS / CANONICAL_FIELDS / MATERIALIZING_CONCEPTS — a custom object has
+* no fixed canonical columns; its mapping's fieldMap keys ARE its properties.
+* Handled as an explicit branch wherever concepts are switched on, so the
+* canonical-concept invariants (and their drift test) stay intact.
+*/
+const CUSTOM_CONCEPT = "custom";
+/**
 * Operator forms for a single column predicate. All predicates on an entity are
 * AND-ed together. `$raw` (see FilterExpr) is the escape hatch for anything the
 * operators can't express.
@@ -124,8 +153,8 @@ const relationshipSchema = z.strictObject({
 /** A named map of relationships, as stored on an entity / in the mappings row. */
 const relationshipsSchema = z.record(z.string(), relationshipSchema);
 const entitySchema = z.strictObject({
-	/** Which CRM concept this entity maps onto. */
-	concept: z.enum(CRM_CONCEPTS),
+	/** Which CRM concept this entity maps onto — a canonical concept or "custom". */
+	concept: z.union([z.enum(CRM_CONCEPTS), z.literal(CUSTOM_CONCEPT)]),
 	/** Host table (or view) this entity is derived from. */
 	source: z.string().min(1),
 	/**
@@ -143,7 +172,12 @@ const entitySchema = z.strictObject({
 	*/
 	readOnly: z.array(z.string()).optional(),
 	/** Named relationships to other entities in this config. */
-	relationships: z.record(z.string(), relationshipSchema).optional()
+	relationships: z.record(z.string(), relationshipSchema).optional(),
+	/**
+	* For a "custom" entity, the crm_object_types row this materializes into.
+	* Required for custom (enforced at the API layer), unused for standard concepts.
+	*/
+	targetObjectTypeId: z.string().min(1).optional()
 });
 const entitiesConfigSchema = z.strictObject({ entities: z.record(z.string(), entitySchema).refine((e) => Object.keys(e).length > 0, { message: "at least one entity must be defined" }) });
 /** Thrown by `defineClivlyConfig({ strict: true })` on non-canonical field keys. */
@@ -302,4 +336,4 @@ function validateEntitiesConfig(config, schema) {
 	};
 }
 //#endregion
-export { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };
+export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, MATERIALIZING_CONCEPTS, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/dist/entity-heuristics.cjs

@@ -1,4 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_entity_config = require("./entity-config.cjs");
+const require_mapping_score = require("./mapping-score.cjs");
 //#region src/entity-heuristics.ts
 const TARGET_CONCEPTS = [
 	"contact",
@@ -116,7 +118,7 @@ const CONCEPT_FIELDS = {
 		{
 			field: "name",
 			candidates: ["name", "title"],
-			required: false
+			required: true
 		},
 		{
 			field: "value",
@@ -208,12 +210,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(require_entity_config.MATERIALIZING_CONCEPTS);
 function matchesConcept(tableName, concept) {
 	const normalized = tableName.toLowerCase();
 	const entry = TABLE_PATTERNS.find((p) => p.concept === concept);
@@ -222,19 +219,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 += require_mapping_score.W.nameExact;
+			reasons.push(`name matches "${table.name}"`);
+		} else {
+			score += require_mapping_score.W.nameSubstring;
+			reasons.push(`name looks like ${concept}`);
 		}
+		if (hasDefiningColumn(concept, table.columns)) {
+			score += require_mapping_score.W.definingColumn;
+			reasons.push(`has the columns a ${concept} needs`);
+		}
+		if (table.columnsMeta?.some((c) => c.isPrimaryKey)) {
+			score += require_mapping_score.W.hasPrimaryKey;
+			reasons.push("has primary key");
+		}
+		if (table.rowCount !== void 0) if (table.rowCount === 0) {
+			score += require_mapping_score.W.emptyTable;
+			reasons.push("table is empty");
+		} else {
+			score += require_mapping_score.W.hasRows;
+			reasons.push(`${table.rowCount.toLocaleString("en-US")} rows`);
+		}
+		out.push({
+			value: concept,
+			score,
+			tier: require_mapping_score.tierFor(score, require_mapping_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: require_mapping_score.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) {
@@ -262,14 +304,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",
@@ -287,58 +321,122 @@ 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: require_mapping_score.W.fkResolved,
+			tier: require_mapping_score.tierFor(require_mapping_score.W.fkResolved, require_mapping_score.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: require_mapping_score.W.fkNameHint,
+		tier: require_mapping_score.tierFor(require_mapping_score.W.fkNameHint, require_mapping_score.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 require_mapping_score.isTextLike(type);
+	if (expectation === "numeric") return require_mapping_score.isNumericLike(type);
+	return require_mapping_score.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 = require_mapping_score.W.fieldNameMatch;
+		const reasons = [`name matches "${column}"`];
+		const meta = metaFor(table, column);
+		const fits = typeFits(field, meta?.type);
+		if (fits === true) {
+			score += require_mapping_score.W.typeCompatible;
+			reasons.push(`type ${meta?.type}`);
+		} else if (fits === false) {
+			score += require_mapping_score.W.typeMismatch;
+			reasons.push(`type ${meta?.type} does not fit ${field}`);
+		}
+		if (required && meta?.nullable === false) {
+			score += require_mapping_score.W.requiredNotNull;
+			reasons.push("not null");
+		}
+		out.push({
+			value: {
+				field,
+				column,
+				required
+			},
+			score,
+			tier: require_mapping_score.tierFor(score, require_mapping_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
 exports.TARGET_CONCEPTS = TARGET_CONCEPTS;
 exports.matchesConcept = matchesConcept;
 exports.requiredFieldsFor = requiredFieldsFor;
-exports.suggestConcept = suggestConcept;
+exports.scoreConcepts = scoreConcepts;
+exports.scoreFieldMap = scoreFieldMap;
+exports.scoreRelationships = scoreRelationships;
 exports.suggestCursorField = suggestCursorField;
 exports.suggestDiscriminatorColumns = suggestDiscriminatorColumns;
-exports.suggestFieldMap = suggestFieldMap;
-exports.suggestRelationships = suggestRelationships;
+exports.toFieldMap = toFieldMap;
+exports.topConcept = topConcept;
 exports.validateMapping = validateMapping;