@clivly/core 0.7.4 → 0.9.0

package/dist/entity-config.cjs

@@ -1,350 +1,13 @@
 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"
-	],
-	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.
-*/
-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 — 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),
-	/**
-	* 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(),
-	/**
-	* 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. */
-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.CUSTOM_CONCEPT = CUSTOM_CONCEPT;
-exports.ClivlyConfigError = ClivlyConfigError;
-exports.MATERIALIZING_CONCEPTS = MATERIALIZING_CONCEPTS;
-exports.defineClivlyConfig = defineClivlyConfig;
-exports.entitiesConfigSchema = entitiesConfigSchema;
-exports.filterSchema = filterSchema;
-exports.relationshipSchema = relationshipSchema;
-exports.relationshipsSchema = relationshipsSchema;
-exports.validateEntitiesConfig = validateEntitiesConfig;
+const require_entity_config = require("./entity-config-PoOGzvpN.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/dist/entity-config.d.cts

@@ -191,6 +191,53 @@ declare const entitySchema: z.ZodObject<{
     }, 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<{
@@ -239,6 +286,53 @@ declare const entitiesConfigSchema: z.ZodObject<{
       }, 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>;
@@ -263,14 +357,39 @@ declare function defineClivlyConfig(config: ClivlyEntitiesConfig, 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;
@@ -292,4 +411,4 @@ interface ConfigValidationResult {
  */
 declare function validateEntitiesConfig(config: ClivlyEntitiesConfig, schema: DiscoveredSchemaTable[]): ConfigValidationResult;
 //#endregion
-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 };
+export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredColumnMeta, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/dist/entity-config.d.mts

@@ -191,6 +191,53 @@ declare const entitySchema: z.ZodObject<{
     }, 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<{
@@ -239,6 +286,53 @@ declare const entitiesConfigSchema: z.ZodObject<{
       }, 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>;
@@ -263,14 +357,39 @@ declare function defineClivlyConfig(config: ClivlyEntitiesConfig, 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;
@@ -292,4 +411,4 @@ interface ConfigValidationResult {
  */
 declare function validateEntitiesConfig(config: ClivlyEntitiesConfig, schema: DiscoveredSchemaTable[]): ConfigValidationResult;
 //#endregion
-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 };
+export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredColumnMeta, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };