clivly 0.2.0 → 0.2.1

package/core-adapter.mjs

@@ -0,0 +1 @@
+export {};

package/core-auth-adapter.cjs

@@ -0,0 +1,3 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_auth_adapter = require("./auth-adapter-CBOKDhlc.cjs");
+exports.authCustom = require_auth_adapter.authCustom;

package/core-auth-adapter.d.cts

@@ -0,0 +1,2 @@
+import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-wvfGKsOJ.cjs";
+export { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom };

package/core-auth-adapter.d.mts

@@ -0,0 +1,2 @@
+import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-FEOR1nx-.mjs";
+export { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom };

package/core-auth-adapter.mjs

@@ -0,0 +1,2 @@
+import { t as authCustom } from "./auth-adapter-wqnnEjo3.mjs";
+export { authCustom };

package/core-drizzle.cjs

@@ -0,0 +1,32 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let drizzle_orm = require("drizzle-orm");
+//#region ../core/src/drizzle.ts
+/**
+* Derive Clivly's discovery shape (table + column names) from a Drizzle schema
+* object — the `* as schema` you pass to `drizzle(client, { schema })`. This
+* delivers the "reads your schema" promise for Drizzle hosts: no hand-authored
+* `DiscoveredTable[]`. Feed the result to the SDK's `schema` option, or diff it
+* against your entity config.
+*
+* Column names are the real database column names (e.g. `full_name`), not the
+* Drizzle property keys (`fullName`). Non-table values in the schema object
+* (relations, enums, helpers) are ignored.
+*
+* `drizzle-orm` is an **optional peer dependency** — you only need it installed
+* when you import this entry (`@clivly/core/drizzle`); the rest of `@clivly/core`
+* stays dependency-free.
+*/
+function discoverFromDrizzle(schema) {
+	const tables = [];
+	for (const value of Object.values(schema)) {
+		if (!(0, drizzle_orm.is)(value, drizzle_orm.Table)) continue;
+		const columns = (0, drizzle_orm.getTableColumns)(value);
+		tables.push({
+			name: (0, drizzle_orm.getTableName)(value),
+			columns: Object.values(columns).map((column) => column.name)
+		});
+	}
+	return tables;
+}
+//#endregion
+exports.discoverFromDrizzle = discoverFromDrizzle;

package/core-drizzle.d.cts

@@ -0,0 +1,21 @@
+import { u as DiscoveredSchemaTable } from "./entity-config-GczjD3y8.cjs";
+
+//#region ../core/src/drizzle.d.ts
+/**
+ * Derive Clivly's discovery shape (table + column names) from a Drizzle schema
+ * object — the `* as schema` you pass to `drizzle(client, { schema })`. This
+ * delivers the "reads your schema" promise for Drizzle hosts: no hand-authored
+ * `DiscoveredTable[]`. Feed the result to the SDK's `schema` option, or diff it
+ * against your entity config.
+ *
+ * Column names are the real database column names (e.g. `full_name`), not the
+ * Drizzle property keys (`fullName`). Non-table values in the schema object
+ * (relations, enums, helpers) are ignored.
+ *
+ * `drizzle-orm` is an **optional peer dependency** — you only need it installed
+ * when you import this entry (`@clivly/core/drizzle`); the rest of `@clivly/core`
+ * stays dependency-free.
+ */
+declare function discoverFromDrizzle(schema: Record<string, unknown>): DiscoveredSchemaTable[];
+//#endregion
+export { discoverFromDrizzle };

package/core-drizzle.d.mts

@@ -0,0 +1,21 @@
+import { u as DiscoveredSchemaTable } from "./entity-config-D1DFyeUp.mjs";
+
+//#region ../core/src/drizzle.d.ts
+/**
+ * Derive Clivly's discovery shape (table + column names) from a Drizzle schema
+ * object — the `* as schema` you pass to `drizzle(client, { schema })`. This
+ * delivers the "reads your schema" promise for Drizzle hosts: no hand-authored
+ * `DiscoveredTable[]`. Feed the result to the SDK's `schema` option, or diff it
+ * against your entity config.
+ *
+ * Column names are the real database column names (e.g. `full_name`), not the
+ * Drizzle property keys (`fullName`). Non-table values in the schema object
+ * (relations, enums, helpers) are ignored.
+ *
+ * `drizzle-orm` is an **optional peer dependency** — you only need it installed
+ * when you import this entry (`@clivly/core/drizzle`); the rest of `@clivly/core`
+ * stays dependency-free.
+ */
+declare function discoverFromDrizzle(schema: Record<string, unknown>): DiscoveredSchemaTable[];
+//#endregion
+export { discoverFromDrizzle };

package/core-drizzle.mjs

@@ -0,0 +1,31 @@
+import { Table, getTableColumns, getTableName, is } from "drizzle-orm";
+//#region ../core/src/drizzle.ts
+/**
+* Derive Clivly's discovery shape (table + column names) from a Drizzle schema
+* object — the `* as schema` you pass to `drizzle(client, { schema })`. This
+* delivers the "reads your schema" promise for Drizzle hosts: no hand-authored
+* `DiscoveredTable[]`. Feed the result to the SDK's `schema` option, or diff it
+* against your entity config.
+*
+* Column names are the real database column names (e.g. `full_name`), not the
+* Drizzle property keys (`fullName`). Non-table values in the schema object
+* (relations, enums, helpers) are ignored.
+*
+* `drizzle-orm` is an **optional peer dependency** — you only need it installed
+* when you import this entry (`@clivly/core/drizzle`); the rest of `@clivly/core`
+* stays dependency-free.
+*/
+function discoverFromDrizzle(schema) {
+	const tables = [];
+	for (const value of Object.values(schema)) {
+		if (!is(value, Table)) continue;
+		const columns = getTableColumns(value);
+		tables.push({
+			name: getTableName(value),
+			columns: Object.values(columns).map((column) => column.name)
+		});
+	}
+	return tables;
+}
+//#endregion
+export { discoverFromDrizzle };

package/core-entity-config.cjs

@@ -0,0 +1,13 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_entity_config = require("./entity-config-Cvjo1cpv.cjs");
+exports.CANONICAL_FIELDS = require_entity_config.CANONICAL_FIELDS;
+exports.CRM_CONCEPTS = require_entity_config.CRM_CONCEPTS;
+exports.CUSTOM_CONCEPT = require_entity_config.CUSTOM_CONCEPT;
+exports.ClivlyConfigError = require_entity_config.ClivlyConfigError;
+exports.MATERIALIZING_CONCEPTS = require_entity_config.MATERIALIZING_CONCEPTS;
+exports.defineClivlyConfig = require_entity_config.defineClivlyConfig;
+exports.entitiesConfigSchema = require_entity_config.entitiesConfigSchema;
+exports.filterSchema = require_entity_config.filterSchema;
+exports.relationshipSchema = require_entity_config.relationshipSchema;
+exports.relationshipsSchema = require_entity_config.relationshipsSchema;
+exports.validateEntitiesConfig = require_entity_config.validateEntitiesConfig;

package/core-entity-config.d.cts

@@ -0,0 +1,2 @@
+import { C as validateEntitiesConfig, S as relationshipsSchema, _ as RelationshipsMap, a as ClivlyEntitiesConfig, b as filterSchema, c as ConfigValidationResult, d as FilterExpr, f as FilterValue, g as RelationshipVia, h as RelationshipSpec, i as ClivlyConfigError, l as CrmConcept, m as MaterializingConcept, n as CRM_CONCEPTS, o as ClivlyEntityConfig, p as MATERIALIZING_CONCEPTS, r as CUSTOM_CONCEPT, s as ConfigValidationError, t as CANONICAL_FIELDS, u as DiscoveredSchemaTable, v as defineClivlyConfig, x as relationshipSchema, y as entitiesConfigSchema } from "./entity-config-GczjD3y8.cjs";
+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/core-entity-config.d.mts

@@ -0,0 +1,2 @@
+import { C as validateEntitiesConfig, S as relationshipsSchema, _ as RelationshipsMap, a as ClivlyEntitiesConfig, b as filterSchema, c as ConfigValidationResult, d as FilterExpr, f as FilterValue, g as RelationshipVia, h as RelationshipSpec, i as ClivlyConfigError, l as CrmConcept, m as MaterializingConcept, n as CRM_CONCEPTS, o as ClivlyEntityConfig, p as MATERIALIZING_CONCEPTS, r as CUSTOM_CONCEPT, s as ConfigValidationError, t as CANONICAL_FIELDS, u as DiscoveredSchemaTable, v as defineClivlyConfig, x as relationshipSchema, y as entitiesConfigSchema } from "./entity-config-D1DFyeUp.mjs";
+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/core-entity-config.mjs

@@ -0,0 +1,2 @@
+import { a as MATERIALIZING_CONCEPTS, c as filterSchema, d as validateEntitiesConfig, i as ClivlyConfigError, l as relationshipSchema, n as CRM_CONCEPTS, o as defineClivlyConfig, r as CUSTOM_CONCEPT, s as entitiesConfigSchema, t as CANONICAL_FIELDS, u as relationshipsSchema } from "./entity-config-DoR0khce.mjs";
+export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, MATERIALIZING_CONCEPTS, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/core-entity-heuristics.cjs

@@ -0,0 +1,442 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_entity_config = require("./entity-config-Cvjo1cpv.cjs");
+const require_mapping_score = require("./mapping-score-D9gfhtRu.cjs");
+//#region ../core/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: true
+		},
+		{
+			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;
+}
+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);
+	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 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 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) {
+	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 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. 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 scoreRelationships(source, allTables) {
+	const companyTables = allTables.filter((t) => t.name !== source.name && topConcept(t)?.best.value === "company");
+	if (companyTables.length === 0) return [];
+	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}`]
+		});
+	}
+	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[0]?.name ?? "",
+			via: {
+				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 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.scoreConcepts = scoreConcepts;
+exports.scoreFieldMap = scoreFieldMap;
+exports.scoreRelationships = scoreRelationships;
+exports.suggestCursorField = suggestCursorField;
+exports.suggestDiscriminatorColumns = suggestDiscriminatorColumns;
+exports.toFieldMap = toFieldMap;
+exports.topConcept = topConcept;
+exports.validateMapping = validateMapping;

package/core-entity-heuristics.d.cts

@@ -0,0 +1,68 @@
+import { a as Scored } from "./mapping-score-BcjC0ZQs.cjs";
+
+//#region ../core/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 matchesConcept(tableName: string, concept: TargetConcept): {
+  exact: boolean;
+} | null;
+interface DiscoveredColumnMeta {
+  isForeignKey?: boolean;
+  isPrimaryKey?: boolean;
+  name: string;
+  nullable?: boolean;
+  references?: {
+    table: string;
+    column: string;
+  };
+  type?: string;
+}
+interface ScoredTable {
+  columns: string[];
+  columnsMeta?: DiscoveredColumnMeta[];
+  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[];
+};
+declare function suggestDiscriminatorColumns(columns: string[]): string[];
+type SuggestedVia = {
+  fkOn: "company" | "contact";
+  column: string;
+} | {
+  through: string;
+  localKey: string;
+  foreignKey: string;
+};
+interface RelationshipSuggestion {
+  /** The related host table. */
+  entityTable: string;
+  /** Suggested relationship name (defaults to the related concept). */
+  name: string;
+  via: SuggestedVia;
+}
+/**
+ * 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 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 { DiscoveredColumnMeta, FieldSuggestion, RelationshipSuggestion, ScoredTable, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };