@clivly/core 0.1.0 → 0.2.0

package/README.md

@@ -12,6 +12,21 @@ This package defines the interfaces that ORM and auth adapters implement. It has
 | `@clivly/core/adapter` | `CRMAdapter` — the interface every ORM implementation fulfils (org-scoped; contacts, companies, deals, tasks, activities) |
 | `@clivly/core/auth-adapter` | `ClivlyAuthAdapter`, `authCustom()`, `MembershipResolver` — pluggable host-app identity + the `crm_members` authorization layer |
 | `@clivly/core/types` | Shared domain types (`Contact`, `Company`, `Deal`, `Task`, `Note`, `Activity`, inputs, filters, `CrmRole`) |
+| `@clivly/core/drizzle` | `discoverFromDrizzle(schema)` — derive the discovery shape from a Drizzle schema object. Requires the optional `drizzle-orm` peer dependency |
+
+## Schema discovery (Drizzle)
+
+`discoverFromDrizzle` turns your Drizzle schema into Clivly's discovery shape, so you don't hand-author table/column arrays:
+
+```ts
+import { discoverFromDrizzle } from "@clivly/core/drizzle";
+import * as schema from "./db/schema";
+
+const tables = discoverFromDrizzle(schema);
+// → [{ name: "participants", columns: ["id", "full_name", "email", …] }, …]
+```
+
+Column names are the real DB names (`full_name`), not the Drizzle keys (`fullName`). `drizzle-orm` is an **optional peer dependency** — only needed when you import this subpath.
 
 ## Usage
 
@@ -24,6 +39,48 @@ function useAdapter(crm: CRMAdapter) {
 }
 ```
 
+## The `$raw` escape hatch
+
+Entity `filter`s and relationship `via`s accept a `$raw` form — an opaque SQL fragment for predicates the operators can't express (e.g. a cross-table condition):
+
+```ts
+defineClivlyConfig({
+  entities: {
+    owner: {
+      concept: "contact",
+      source: "users",
+      fields: { name: "full_name", email: "email" },
+      filter: { $raw: "role = 'owner' AND deleted_at IS NULL" },
+    },
+  },
+});
+```
+
+**`$raw` is unchecked.** `validateEntitiesConfig` deliberately **skips** `$raw` filters and joins — it can't know your columns are real or your SQL is valid. Two consequences:
+
+- **Injection safety is on you.** Never interpolate untrusted input into a `$raw` string; treat it like handwritten SQL. Everything else in the config is escaped for you; `$raw` is not.
+- **Mistakes surface at sync time, not config time** — unless you dry-run it.
+
+### Dry-run with `explainEntitiesConfig`
+
+`explainEntitiesConfig(config, run, options?)` compiles each entity's view and executes it via a runner you provide, so a broken `$raw` fragment fails **before** the first sync. It never throws — it returns one `ExplainResult` per entity:
+
+```ts
+import { explainEntitiesConfig } from "@clivly/core";
+
+const results = await explainEntitiesConfig(config, (sql) =>
+  // Run somewhere side-effect-free — e.g. a transaction you roll back.
+  db.transaction(async (tx) => {
+    await tx.execute(sql);
+    throw new Rollback();
+  }).catch(swallowRollback)
+);
+
+for (const r of results) {
+  if (!r.ok) console.error(`${r.entityKey}: ${r.error}`);
+}
+```
+
 ## License
 
 MIT

package/dist/adapter.d.cts

@@ -0,0 +1,36 @@
+import { Activity, Company, Contact, ContactFilters, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, Deal, Task, TaskFilters, UpdateContactInput, UpdateDealInput, UpdateTaskInput } from "./types.cjs";
+
+//#region src/adapter.d.ts
+/**
+ * The contract every ORM implementation fulfils. `packages/drizzle` is the first
+ * implementation; Prisma/Kysely/TypeORM can follow without changes to consumers.
+ *
+ * Every method is scoped to a single organization (`orgId`) — the adapter is the
+ * one place tenant isolation is enforced for CRM data. Implementations only ever
+ * read/write Clivly-owned `crm_*` tables; they never mutate host business tables.
+ */
+interface CRMAdapter {
+  archiveTask(orgId: string, id: string): Promise<Task>;
+  completeTask(orgId: string, id: string): Promise<Task>;
+  createActivity(orgId: string, data: CreateActivityInput): Promise<Activity>;
+  createCompany(orgId: string, data: CreateCompanyInput): Promise<Company>;
+  createContact(orgId: string, data: CreateContactInput): Promise<Contact>;
+  createDeal(orgId: string, data: CreateDealInput): Promise<Deal>;
+  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[]>;
+  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[]>;
+  getTasks(orgId: string, filters?: TaskFilters): Promise<Task[]>;
+  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>;
+  updateDealStage(orgId: string, id: string, stage: Deal["stage"]): Promise<Deal>;
+  updateTask(orgId: string, id: string, data: UpdateTaskInput): Promise<Task>;
+  updateTaskStatus(orgId: string, id: string, status: Task["status"]): Promise<Task>;
+}
+//#endregion
+export { CRMAdapter };

package/dist/adapter.d.mts

@@ -1,4 +1,4 @@
-import { Activity, Company, Contact, ContactFilters, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, Deal, Task, TaskFilters, UpdateContactInput, UpdateTaskInput } from "./types.mjs";
+import { Activity, Company, Contact, ContactFilters, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, Deal, Task, TaskFilters, UpdateContactInput, UpdateDealInput, UpdateTaskInput } from "./types.mjs";
 
 //#region src/adapter.d.ts
 /**
@@ -17,14 +17,17 @@ interface CRMAdapter {
   createContact(orgId: string, data: CreateContactInput): Promise<Contact>;
   createDeal(orgId: string, data: CreateDealInput): Promise<Deal>;
   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[]>;
   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[]>;
   getTasks(orgId: string, filters?: TaskFilters): Promise<Task[]>;
   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>;
   updateDealStage(orgId: string, id: string, stage: Deal["stage"]): Promise<Deal>;
   updateTask(orgId: string, id: string, data: UpdateTaskInput): Promise<Task>;
   updateTaskStatus(orgId: string, id: string, status: Task["status"]): Promise<Task>;

package/dist/auth-adapter.cjs

@@ -0,0 +1,7 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/auth-adapter.ts
+function authCustom(resolver) {
+	return { getUser: async (req) => await resolver(req) };
+}
+//#endregion
+exports.authCustom = authCustom;

package/dist/auth-adapter.d.cts

@@ -0,0 +1,30 @@
+import { CrmRole } from "./types.cjs";
+
+//#region src/auth-adapter.d.ts
+interface ClivlyUser {
+  email: string;
+  id: string;
+  name?: string;
+}
+/**
+ * Bridges any host auth system into Clivly. Ship adapters wrap a concrete SDK
+ * (`@clivly/auth-clerk`, `@clivly/auth-workos`), and `authCustom` wraps an
+ * arbitrary `(req) => user` resolver.
+ *
+ * This answers "who is this person?" only. Authorization ("what can they do in
+ * this org?") is the separate `crm_members` layer — see `MembershipResolver`.
+ */
+interface ClivlyAuthAdapter {
+  getUser(req: Request): Promise<ClivlyUser | null>;
+}
+declare function authCustom(resolver: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null): ClivlyAuthAdapter;
+interface CrmMembership {
+  orgId: string;
+  role: CrmRole;
+  userId: string;
+}
+interface MembershipResolver {
+  getMembership(userId: string, orgId: string): Promise<CrmMembership | null>;
+}
+//#endregion
+export { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom };

package/dist/drizzle.cjs

@@ -0,0 +1,32 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let drizzle_orm = require("drizzle-orm");
+//#region 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/dist/drizzle.d.cts

@@ -0,0 +1,21 @@
+import { DiscoveredSchemaTable } from "./entity-config.cjs";
+
+//#region 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/dist/drizzle.d.mts

@@ -0,0 +1,21 @@
+import { DiscoveredSchemaTable } from "./entity-config.mjs";
+
+//#region 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/dist/drizzle.mjs

@@ -0,0 +1,31 @@
+import { Table, getTableColumns, getTableName, is } from "drizzle-orm";
+//#region 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/dist/entity-config.cjs

@@ -0,0 +1,314 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let zod = require("zod");
+//#region src/entity-config.ts
+/**
+* Entity Config v2 — the declarative contract that turns Clivly's "schema-aware"
+* promise into a real capability.
+*
+* A CRM entity is no longer a flat table name. It is a *derived entity*: a
+* filtered slice of a host table (`source` + `filter`), a column allowlist
+* (`fields` + `readOnly`), and declared `relationships` to other entities. The
+* same host table can back several entities (e.g. `users` → owners + members)
+* distinguished by `role`.
+*
+* This module is the Phase 1 slice: types, schema, `defineClivlyConfig` (a
+* structural helper) and `validateEntitiesConfig` (semantic validation against
+* the host's discovered schema). It performs NO DB access and generates no SQL —
+* the view compiler (Phase 2) and sync engine (Phase 3) consume this contract.
+*/
+/** Canonical CRM concepts a host entity can map onto. */
+const CRM_CONCEPTS = [
+	"contact",
+	"company",
+	"deal",
+	"activity",
+	"conversation",
+	"note"
+];
+/**
+* The canonical `fields` keys the mirror actually persists, per concept — the
+* crm_* columns the sync store writes. An entity's `fields` map keys must be one
+* of these: a non-canonical key (e.g. `fullName` instead of `name`) validates
+* structurally but has no destination column, so the store silently writes an
+* empty value. `validateEntitiesConfig` flags those.
+*
+* This is the single source of truth — the Drizzle store imports it, so the
+* two can't drift (the drift is what made the silent-data-loss trap possible).
+* Concepts absent here aren't materialized yet, so their field keys are
+* unconstrained.
+*/
+const CANONICAL_FIELDS = {
+	contact: [
+		"name",
+		"email",
+		"title",
+		"status"
+	],
+	company: [
+		"name",
+		"domain",
+		"industry",
+		"size"
+	]
+};
+/**
+* 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.
+*/
+const filterOperatorsSchema = zod.z.union([
+	zod.z.strictObject({ eq: zod.z.union([
+		zod.z.string(),
+		zod.z.number(),
+		zod.z.boolean()
+	]) }),
+	zod.z.strictObject({ ne: zod.z.union([
+		zod.z.string(),
+		zod.z.number(),
+		zod.z.boolean()
+	]) }),
+	zod.z.strictObject({ in: zod.z.array(zod.z.union([
+		zod.z.string(),
+		zod.z.number(),
+		zod.z.boolean()
+	])).min(1) }),
+	zod.z.strictObject({ notIn: zod.z.array(zod.z.union([
+		zod.z.string(),
+		zod.z.number(),
+		zod.z.boolean()
+	])).min(1) }),
+	zod.z.strictObject({ isNull: zod.z.literal(true) }),
+	zod.z.strictObject({ isNotNull: zod.z.literal(true) })
+]);
+const filterValueSchema = zod.z.union([
+	zod.z.string(),
+	zod.z.number(),
+	zod.z.boolean(),
+	filterOperatorsSchema
+]);
+/**
+* A raw SQL predicate fragment. Kept as a *string* (not a query-builder callback)
+* so the whole config stays JSON-serializable — it can be persisted into
+* `crm_entity_mappings` and shipped to the cloud unchanged. Embedded-only in
+* practice; not validated against the schema.
+*/
+const rawFilterSchema = zod.z.strictObject({ $raw: zod.z.string().min(1) });
+const columnFilterSchema = zod.z.record(zod.z.string(), filterValueSchema);
+/** `$raw` is a reserved key; a column literally named `$raw` is not addressable. */
+const filterSchema = zod.z.union([rawFilterSchema, columnFilterSchema]);
+/**
+* How the link between two entities is expressed in the host schema:
+* - `fkOn: "company"` — FK lives on the company table (e.g. organizations.owner_id)
+* - `fkOn: "contact"` — FK lives on the contact table (e.g. users.organization_id)
+* - `through`         — a join table sits between them (many-to-many, role often here)
+* - `$raw`            — opaque SQL join fragment (escape hatch; not schema-validated)
+*
+* `column` and the join-table keys are `table.column` or bare `column` strings.
+*/
+const relationshipViaSchema = zod.z.union([
+	zod.z.strictObject({
+		fkOn: zod.z.enum(["company", "contact"]),
+		column: zod.z.string().min(1)
+	}),
+	zod.z.strictObject({
+		through: zod.z.string().min(1),
+		localKey: zod.z.string().min(1),
+		foreignKey: zod.z.string().min(1)
+	}),
+	zod.z.strictObject({ $raw: zod.z.string().min(1) })
+]);
+const relationshipSchema = zod.z.strictObject({
+	/** Key of the related entity in the `entities` map. */
+	entity: zod.z.string().min(1),
+	via: relationshipViaSchema
+});
+/** 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),
+	/** Host table (or view) this entity is derived from. */
+	source: zod.z.string().min(1),
+	/**
+	* Distinguishes multiple entities backed by the same table (e.g. "primary"
+	* for owners, "secondary" for members). Free text; defaults to "primary".
+	*/
+	role: zod.z.string().min(1).optional(),
+	/** Predicate that narrows `source` into this entity's rows. Omit = whole table. */
+	filter: filterSchema.optional(),
+	/** clivlyField → sourceColumn. At least one field is required. */
+	fields: zod.z.record(zod.z.string(), zod.z.string()).refine((f) => Object.keys(f).length > 0, { message: "at least one field must be mapped" }),
+	/**
+	* Host-owned identity fields. Sync overwrites them; the CRM UI cannot edit
+	* them. Must be a subset of `fields` keys.
+	*/
+	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()
+});
+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. */
+var ClivlyConfigError = class extends Error {
+	issues;
+	constructor(issues) {
+		super(`Clivly config has ${issues.length} non-canonical field mapping(s) that would write empty values at sync time:\n${issues.map((issue) => `  - ${issue.path}: ${issue.message}`).join("\n")}`);
+		this.name = "ClivlyConfigError";
+		this.issues = issues;
+	}
+};
+function nonCanonicalFieldKeys(entity) {
+	const canonical = CANONICAL_FIELDS[entity.concept];
+	if (!canonical) return [];
+	return Object.keys(entity.fields).filter((key) => !canonical.includes(key));
+}
+function nonCanonicalMessage(entity, field) {
+	const canonical = CANONICAL_FIELDS[entity.concept] ?? [];
+	return `"${field}" is not a canonical ${entity.concept} field (expected one of: ${canonical.join(", ")})`;
+}
+function canonicalFieldIssues(config) {
+	const issues = [];
+	for (const [key, entity] of Object.entries(config.entities)) for (const field of nonCanonicalFieldKeys(entity)) issues.push({
+		path: `entities.${key}.fields.${field}`,
+		message: nonCanonicalMessage(entity, field)
+	});
+	return issues;
+}
+function defaultWarn(message) {
+	console.warn(message);
+}
+/**
+* Structural helper for `clivly.config.ts`. Gives full type inference on the
+* literal you pass and eagerly parses it, so shape errors surface at config
+* load rather than at sync time.
+*
+* It also catches the silent-data-loss footgun: a non-canonical field key for a
+* materialised concept (e.g. `fullName` instead of `name` on a `contact`) has no
+* destination column, so the store would write an empty value. By default these
+* are reported via `onWarn` (a `console.warn`); pass `{ strict: true }` to throw
+* a `ClivlyConfigError` instead. Does NOT validate against the host schema — that
+* needs the discovered schema; see `validateEntitiesConfig`.
+*/
+function defineClivlyConfig(config, options) {
+	const parsed = entitiesConfigSchema.parse(config);
+	const issues = canonicalFieldIssues(parsed);
+	if (issues.length > 0) {
+		if (options?.strict) throw new ClivlyConfigError(issues);
+		const warn = options?.onWarn ?? defaultWarn;
+		for (const issue of issues) warn(`⚠ Clivly config: ${issue.message} (${issue.path}) — this field would write an empty value at sync time. Pass { strict: true } to make this throw.`);
+	}
+	return parsed;
+}
+/** Split a `table.column` / bare `column` ref into its parts. */
+function parseColumnRef(ref) {
+	const dot = ref.indexOf(".");
+	if (dot === -1) return { column: ref };
+	return {
+		table: ref.slice(0, dot),
+		column: ref.slice(dot + 1)
+	};
+}
+/** Shared lookup + error-collection state threaded through the validators. */
+var SchemaValidator = class {
+	errors = [];
+	columnsByTable = /* @__PURE__ */ new Map();
+	constructor(schema) {
+		for (const table of schema) this.columnsByTable.set(table.name, new Set(table.columns));
+	}
+	tableExists(name) {
+		return this.columnsByTable.has(name);
+	}
+	columnExists(table, column) {
+		return this.columnsByTable.get(table)?.has(column) ?? false;
+	}
+	report(path, message) {
+		this.errors.push({
+			path,
+			message
+		});
+	}
+	/** Report if `column` is absent from `table`. Returns whether it existed. */
+	requireColumn(path, table, column) {
+		if (this.columnExists(table, column)) return true;
+		this.report(path, `column "${column}" does not exist on "${table}"`);
+		return false;
+	}
+};
+function validateFields(v, base, entity) {
+	for (const [field, column] of Object.entries(entity.fields)) v.requireColumn(`${base}.fields.${field}`, entity.source, column);
+	for (const field of nonCanonicalFieldKeys(entity)) v.report(`${base}.fields.${field}`, nonCanonicalMessage(entity, field));
+}
+function validateReadOnly(v, base, entity) {
+	for (const field of entity.readOnly ?? []) if (!(field in entity.fields)) v.report(`${base}.readOnly`, `"${field}" is not one of this entity's fields`);
+}
+function validateFilter(v, base, entity) {
+	if (!entity.filter || "$raw" in entity.filter) return;
+	for (const column of Object.keys(entity.filter)) v.requireColumn(`${base}.filter.${column}`, entity.source, column);
+}
+function validateFkVia(v, relBase, via, entity, related) {
+	const { table, column } = parseColumnRef(via.column);
+	const fkTable = table ?? (via.fkOn === "contact" ? entity.source : related?.source);
+	const path = `${relBase}.via.column`;
+	if (!fkTable) {
+		v.report(path, `cannot resolve table for FK column "${via.column}"`);
+		return;
+	}
+	if (!v.tableExists(fkTable)) {
+		v.report(path, `table "${fkTable}" is not in the discovered schema`);
+		return;
+	}
+	v.requireColumn(path, fkTable, column);
+}
+function validateThroughVia(v, relBase, via) {
+	if (!v.tableExists(via.through)) {
+		v.report(`${relBase}.via.through`, `join table "${via.through}" is not in the discovered schema`);
+		return;
+	}
+	v.requireColumn(`${relBase}.via.localKey`, via.through, via.localKey);
+	v.requireColumn(`${relBase}.via.foreignKey`, via.through, via.foreignKey);
+}
+function validateRelationship(v, base, config, entity, relName, rel) {
+	const relBase = `${base}.relationships.${relName}`;
+	const related = config.entities[rel.entity];
+	if (!related) v.report(`${relBase}.entity`, `"${rel.entity}" is not a defined entity`);
+	const { via } = rel;
+	if ("fkOn" in via) validateFkVia(v, relBase, via, entity, related);
+	else if ("through" in via) validateThroughVia(v, relBase, via);
+}
+function validateEntity(v, config, key, entity) {
+	const base = `entities.${key}`;
+	if (!v.tableExists(entity.source)) {
+		v.report(`${base}.source`, `table "${entity.source}" is not in the discovered schema`);
+		return;
+	}
+	validateFields(v, base, entity);
+	validateReadOnly(v, base, entity);
+	validateFilter(v, base, entity);
+	for (const [relName, rel] of Object.entries(entity.relationships ?? {})) validateRelationship(v, base, config, entity, relName, rel);
+}
+/**
+* Validate a (structurally valid) config against the host's discovered schema:
+* source tables exist, mapped columns exist, `readOnly` ⊆ `fields`, filter
+* columns exist, and relationships point at real entities/tables/columns.
+*
+* `$raw` filters and `$raw` relationship joins are opaque and skipped. Returns
+* every error found (not just the first) so a mapping UI or CLI can show them
+* all at once.
+*/
+function validateEntitiesConfig(config, schema) {
+	const validator = new SchemaValidator(schema);
+	for (const [key, entity] of Object.entries(config.entities)) validateEntity(validator, config, key, entity);
+	return {
+		valid: validator.errors.length === 0,
+		errors: validator.errors
+	};
+}
+//#endregion
+exports.CANONICAL_FIELDS = CANONICAL_FIELDS;
+exports.CRM_CONCEPTS = CRM_CONCEPTS;
+exports.ClivlyConfigError = ClivlyConfigError;
+exports.defineClivlyConfig = defineClivlyConfig;
+exports.entitiesConfigSchema = entitiesConfigSchema;
+exports.filterSchema = filterSchema;
+exports.relationshipSchema = relationshipSchema;
+exports.relationshipsSchema = relationshipsSchema;
+exports.validateEntitiesConfig = validateEntitiesConfig;