@clivly/core 0.9.0 → 0.9.1

package/dist/entity-config-CLxI8dVb.d.cts

@@ -0,0 +1,556 @@
+import { z } from "zod";
+//#region src/projection.d.ts
+/**
+ * Projection-backed custom mappings — one custom object derived from a base
+ * table plus explicit joins.
+ *
+ * A projection is deliberately narrow: equality joins only, direct column
+ * bindings only, no expressions and no aggregation. Everything a user can
+ * express here compiles to a single read-only view whose `id` column is
+ * provably unique per row, which is what lets the sync engine consume it
+ * unchanged.
+ *
+ * Refs address tables symbolically: `"base"` for the base table, or a join's
+ * `key`. Raw table names are never accepted in a ref, so a projection can
+ * never reach a table it did not declare.
+ */
+/** The reserved ref name for the projection's base table. */
+declare const BASE_REF = "base";
+declare const projectionRefSchema: z.ZodObject<{
+  table: z.ZodString;
+  column: z.ZodString;
+}, z.core.$strict>;
+type ProjectionRef = z.infer<typeof projectionRefSchema>;
+declare const projectionJoinSchema: z.ZodObject<{
+  key: z.ZodString;
+  table: z.ZodString;
+  type: z.ZodEnum<{
+    inner: "inner";
+    left: "left";
+  }>;
+  on: z.ZodArray<z.ZodObject<{
+    left: z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>;
+    op: z.ZodLiteral<"eq">;
+    right: z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+type ProjectionJoin = z.infer<typeof projectionJoinSchema>;
+declare const projectionFieldBindingSchema: z.ZodObject<{
+  from: z.ZodObject<{
+    table: z.ZodString;
+    column: z.ZodString;
+  }, z.core.$strict>;
+}, z.core.$strict>;
+type ProjectionFieldBinding = z.infer<typeof projectionFieldBindingSchema>;
+declare const projectionIdentitySchema: z.ZodUnion<readonly [z.ZodObject<{
+  kind: z.ZodLiteral<"base_pk">;
+  column: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+  kind: z.ZodLiteral<"column">;
+  from: z.ZodObject<{
+    table: z.ZodString;
+    column: z.ZodString;
+  }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+  kind: z.ZodLiteral<"composite">;
+  parts: z.ZodArray<z.ZodObject<{
+    table: z.ZodString;
+    column: z.ZodString;
+  }, z.core.$strict>>;
+}, z.core.$strict>]>;
+type ProjectionIdentity = z.infer<typeof projectionIdentitySchema>;
+declare const projectionSchema: z.ZodObject<{
+  version: z.ZodLiteral<1>;
+  kind: z.ZodLiteral<"projection">;
+  entityKey: z.ZodString;
+  baseTable: z.ZodString;
+  joins: z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    table: z.ZodString;
+    type: z.ZodEnum<{
+      inner: "inner";
+      left: "left";
+    }>;
+    on: z.ZodArray<z.ZodObject<{
+      left: z.ZodObject<{
+        table: z.ZodString;
+        column: z.ZodString;
+      }, z.core.$strict>;
+      op: z.ZodLiteral<"eq">;
+      right: z.ZodObject<{
+        table: z.ZodString;
+        column: z.ZodString;
+      }, z.core.$strict>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>>;
+  fieldBindings: z.ZodRecord<z.ZodString, z.ZodObject<{
+    from: z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>;
+  }, z.core.$strict>>;
+  identity: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"base_pk">;
+    column: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"column">;
+    from: z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>;
+  }, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"composite">;
+    parts: z.ZodArray<z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>>;
+  }, z.core.$strict>]>;
+}, z.core.$strict>;
+type ProjectionMapping = z.infer<typeof projectionSchema>;
+/**
+ * Every column ref an identity depends on. `basePkColumn` is the base table's
+ * discovered PK, used only when a `base_pk` identity omits an explicit column.
+ */
+declare function identityRefs(identity: ProjectionIdentity, basePkColumn: string): ProjectionRef[];
+//#endregion
+//#region src/entity-config.d.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. */
+declare const CRM_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
+type CrmConcept = (typeof CRM_CONCEPTS)[number];
+/**
+ * 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.
+ */
+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<{
+  ne: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+}, z.core.$strict>, z.ZodObject<{
+  in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+}, z.core.$strict>, z.ZodObject<{
+  notIn: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+}, z.core.$strict>, z.ZodObject<{
+  isNull: z.ZodLiteral<true>;
+}, z.core.$strict>, z.ZodObject<{
+  isNotNull: z.ZodLiteral<true>;
+}, z.core.$strict>]>]>;
+/** `$raw` is a reserved key; a column literally named `$raw` is not addressable. */
+declare const filterSchema: z.ZodUnion<readonly [z.ZodObject<{
+  $raw: z.ZodString;
+}, z.core.$strict>, z.ZodRecord<z.ZodString, 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<{
+  ne: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+}, z.core.$strict>, z.ZodObject<{
+  in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+}, z.core.$strict>, z.ZodObject<{
+  notIn: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+}, z.core.$strict>, z.ZodObject<{
+  isNull: z.ZodLiteral<true>;
+}, z.core.$strict>, z.ZodObject<{
+  isNotNull: z.ZodLiteral<true>;
+}, z.core.$strict>]>]>>]>;
+type FilterExpr = z.infer<typeof filterSchema>;
+/** A single column predicate value (scalar shorthand or operator object). */
+type FilterValue = z.infer<typeof filterValueSchema>;
+/**
+ * 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.
+ */
+declare const relationshipViaSchema: z.ZodUnion<readonly [z.ZodObject<{
+  fkOn: z.ZodEnum<{
+    contact: "contact";
+    company: "company";
+  }>;
+  column: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  through: z.ZodString;
+  localKey: z.ZodString;
+  foreignKey: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  $raw: z.ZodString;
+}, z.core.$strict>]>;
+type RelationshipVia = z.infer<typeof relationshipViaSchema>;
+declare const relationshipSchema: z.ZodObject<{
+  entity: z.ZodString;
+  via: z.ZodUnion<readonly [z.ZodObject<{
+    fkOn: z.ZodEnum<{
+      contact: "contact";
+      company: "company";
+    }>;
+    column: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    through: z.ZodString;
+    localKey: z.ZodString;
+    foreignKey: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    $raw: z.ZodString;
+  }, z.core.$strict>]>;
+}, z.core.$strict>;
+type RelationshipSpec = z.infer<typeof relationshipSchema>;
+/** A named map of relationships, as stored on an entity / in the mappings row. */
+declare const relationshipsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+  entity: z.ZodString;
+  via: z.ZodUnion<readonly [z.ZodObject<{
+    fkOn: z.ZodEnum<{
+      contact: "contact";
+      company: "company";
+    }>;
+    column: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    through: z.ZodString;
+    localKey: z.ZodString;
+    foreignKey: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    $raw: z.ZodString;
+  }, z.core.$strict>]>;
+}, z.core.$strict>>;
+type RelationshipsMap = z.infer<typeof relationshipsSchema>;
+declare const entitySchema: z.ZodObject<{
+  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<{
+    $raw: z.ZodString;
+  }, z.core.$strict>, z.ZodRecord<z.ZodString, 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<{
+    ne: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+  }, z.core.$strict>, z.ZodObject<{
+    in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+  }, z.core.$strict>, z.ZodObject<{
+    notIn: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+  }, z.core.$strict>, z.ZodObject<{
+    isNull: z.ZodLiteral<true>;
+  }, z.core.$strict>, z.ZodObject<{
+    isNotNull: z.ZodLiteral<true>;
+  }, z.core.$strict>]>]>>]>>;
+  fields: z.ZodRecord<z.ZodString, z.ZodString>;
+  readOnly: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  relationships: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+    entity: z.ZodString;
+    via: z.ZodUnion<readonly [z.ZodObject<{
+      fkOn: z.ZodEnum<{
+        contact: "contact";
+        company: "company";
+      }>;
+      column: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      through: z.ZodString;
+      localKey: z.ZodString;
+      foreignKey: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      $raw: z.ZodString;
+    }, z.core.$strict>]>;
+  }, z.core.$strict>>>;
+  targetObjectTypeId: z.ZodOptional<z.ZodString>;
+  projection: z.ZodOptional<z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"projection">;
+    entityKey: z.ZodString;
+    baseTable: z.ZodString;
+    joins: z.ZodArray<z.ZodObject<{
+      key: z.ZodString;
+      table: z.ZodString;
+      type: z.ZodEnum<{
+        inner: "inner";
+        left: "left";
+      }>;
+      on: z.ZodArray<z.ZodObject<{
+        left: z.ZodObject<{
+          table: z.ZodString;
+          column: z.ZodString;
+        }, z.core.$strict>;
+        op: z.ZodLiteral<"eq">;
+        right: z.ZodObject<{
+          table: z.ZodString;
+          column: z.ZodString;
+        }, z.core.$strict>;
+      }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    fieldBindings: z.ZodRecord<z.ZodString, z.ZodObject<{
+      from: z.ZodObject<{
+        table: z.ZodString;
+        column: z.ZodString;
+      }, z.core.$strict>;
+    }, z.core.$strict>>;
+    identity: z.ZodUnion<readonly [z.ZodObject<{
+      kind: z.ZodLiteral<"base_pk">;
+      column: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+      kind: z.ZodLiteral<"column">;
+      from: z.ZodObject<{
+        table: z.ZodString;
+        column: z.ZodString;
+      }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+      kind: z.ZodLiteral<"composite">;
+      parts: z.ZodArray<z.ZodObject<{
+        table: z.ZodString;
+        column: z.ZodString;
+      }, z.core.$strict>>;
+    }, z.core.$strict>]>;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+type ClivlyEntityConfig = z.infer<typeof entitySchema>;
+declare const entitiesConfigSchema: z.ZodObject<{
+  entities: z.ZodRecord<z.ZodString, z.ZodObject<{
+    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<{
+      $raw: z.ZodString;
+    }, z.core.$strict>, z.ZodRecord<z.ZodString, 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<{
+      ne: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, z.core.$strict>, z.ZodObject<{
+      in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    }, z.core.$strict>, z.ZodObject<{
+      notIn: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    }, z.core.$strict>, z.ZodObject<{
+      isNull: z.ZodLiteral<true>;
+    }, z.core.$strict>, z.ZodObject<{
+      isNotNull: z.ZodLiteral<true>;
+    }, z.core.$strict>]>]>>]>>;
+    fields: z.ZodRecord<z.ZodString, z.ZodString>;
+    readOnly: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relationships: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+      entity: z.ZodString;
+      via: z.ZodUnion<readonly [z.ZodObject<{
+        fkOn: z.ZodEnum<{
+          contact: "contact";
+          company: "company";
+        }>;
+        column: z.ZodString;
+      }, z.core.$strict>, z.ZodObject<{
+        through: z.ZodString;
+        localKey: z.ZodString;
+        foreignKey: z.ZodString;
+      }, z.core.$strict>, z.ZodObject<{
+        $raw: z.ZodString;
+      }, z.core.$strict>]>;
+    }, z.core.$strict>>>;
+    targetObjectTypeId: z.ZodOptional<z.ZodString>;
+    projection: z.ZodOptional<z.ZodObject<{
+      version: z.ZodLiteral<1>;
+      kind: z.ZodLiteral<"projection">;
+      entityKey: z.ZodString;
+      baseTable: z.ZodString;
+      joins: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        table: z.ZodString;
+        type: z.ZodEnum<{
+          inner: "inner";
+          left: "left";
+        }>;
+        on: z.ZodArray<z.ZodObject<{
+          left: z.ZodObject<{
+            table: z.ZodString;
+            column: z.ZodString;
+          }, z.core.$strict>;
+          op: z.ZodLiteral<"eq">;
+          right: z.ZodObject<{
+            table: z.ZodString;
+            column: z.ZodString;
+          }, z.core.$strict>;
+        }, z.core.$strict>>;
+      }, z.core.$strict>>;
+      fieldBindings: z.ZodRecord<z.ZodString, z.ZodObject<{
+        from: z.ZodObject<{
+          table: z.ZodString;
+          column: z.ZodString;
+        }, z.core.$strict>;
+      }, z.core.$strict>>;
+      identity: z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"base_pk">;
+        column: z.ZodOptional<z.ZodString>;
+      }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"column">;
+        from: z.ZodObject<{
+          table: z.ZodString;
+          column: z.ZodString;
+        }, z.core.$strict>;
+      }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"composite">;
+        parts: z.ZodArray<z.ZodObject<{
+          table: z.ZodString;
+          column: z.ZodString;
+        }, z.core.$strict>>;
+      }, z.core.$strict>]>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+type ClivlyEntitiesConfig = z.infer<typeof entitiesConfigSchema>;
+/**
+ * What an author may hand to `defineClivlyConfig`. Identical to
+ * `ClivlyEntityConfig` except that a projection entity may omit `fields` —
+ * it is derived from `projection.fieldBindings`. Without a projection `fields`
+ * stays required, so the looser input never weakens the ordinary case.
+ */
+type ClivlyEntityConfigInput = (ClivlyEntityConfig & {
+  projection?: undefined;
+}) | (Omit<ClivlyEntityConfig, "fields"> & {
+  fields?: Record<string, string>;
+  projection: ProjectionMapping;
+});
+type ClivlyEntitiesConfigInput = Omit<ClivlyEntitiesConfig, "entities"> & {
+  entities: Record<string, ClivlyEntityConfigInput>;
+};
+/** Thrown by `defineClivlyConfig({ strict: true })` on non-canonical field keys. */
+declare class ClivlyConfigError extends Error {
+  readonly issues: ConfigValidationError[];
+  constructor(issues: ConfigValidationError[]);
+}
+/**
+ * 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`.
+ */
+/**
+ * The `fields` entry a projection binding implies, qualified as `ref.column`.
+ * Qualified rather than bare: two bindings can pull the same column name from
+ * different tables (`cl.full_name` and `adv.full_name`), which a bare column
+ * name cannot tell apart.
+ */
+declare function projectionFields(projection: ProjectionMapping): Record<string, string>;
+declare function defineClivlyConfig(config: ClivlyEntitiesConfigInput, options?: {
+  strict?: boolean;
+  onWarn?: (message: string) => void;
+}): ClivlyEntitiesConfig;
+/**
+ * Per-column metadata a host reports for a discovered table. Structurally
+ * identical to the SDK's `DiscoveredColumn` and to `entity-heuristics.ts`'s
+ * (currently separate) `DiscoveredColumnMeta` — a later task converges that
+ * module onto this one. Every field is optional: a v1 host reports column
+ * names only.
+ */
+interface DiscoveredColumnMeta {
+  isForeignKey?: boolean;
+  isPrimaryKey?: boolean;
+  name: string;
+  nullable?: boolean;
+  references?: {
+    table: string;
+    column: string;
+  };
+  type?: string;
+}
+/**
+ * A host table the SDK reported for discovery. Structurally identical to the
+ * SDK's `DiscoveredTable`; duplicated here to keep `@clivly/core` free of an
+ * SDK dependency (core is the base contract SDK builds on).
+ *
+ * `columns` is the stable v1 contract. `columnsMeta` and `uniqueConstraints`
+ * are the enrichment projection mappings require — absent on v1 hosts, which
+ * is why projection validation fails closed rather than assuming "no keys".
+ */
+interface DiscoveredSchemaTable {
+  columns: string[];
+  columnsMeta?: DiscoveredColumnMeta[];
+  name: string;
+  /** Every unique key as DB column names; PKs included. Absent = unknown. */
+  uniqueConstraints?: string[][];
+}
+interface ConfigValidationError {
+  message: string;
+  /** Dotted path into the config, e.g. `entities.owner.fields.email`. */
+  path: string;
+}
+interface ConfigValidationResult {
+  errors: ConfigValidationError[];
+  valid: boolean;
+}
+/**
+ * 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.
+ */
+declare function validateEntitiesConfig(config: ClivlyEntitiesConfig, schema: DiscoveredSchemaTable[]): ConfigValidationResult;
+//#endregion
+export { ProjectionIdentity as A, filterSchema as C, validateEntitiesConfig as D, relationshipsSchema as E, projectionSchema as F, ProjectionMapping as M, ProjectionRef as N, BASE_REF as O, identityRefs as P, entitiesConfigSchema as S, relationshipSchema as T, MaterializingConcept as _, ClivlyEntitiesConfig as a, RelationshipsMap as b, ClivlyEntityConfigInput as c, CrmConcept as d, DiscoveredColumnMeta as f, MATERIALIZING_CONCEPTS as g, FilterValue as h, ClivlyConfigError as i, ProjectionJoin as j, ProjectionFieldBinding as k, ConfigValidationError as l, FilterExpr as m, CRM_CONCEPTS as n, ClivlyEntitiesConfigInput as o, DiscoveredSchemaTable as p, CUSTOM_CONCEPT as r, ClivlyEntityConfig as s, CANONICAL_FIELDS as t, ConfigValidationResult as u, RelationshipSpec as v, projectionFields as w, defineClivlyConfig as x, RelationshipVia as y };