@clivly/core 0.7.4 → 0.9.0

package/dist/index.d.mts

@@ -1,9 +1,79 @@
 import { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, RecordSource, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateDealInput, UpdateTaskInput } from "./types.mjs";
 import { CRMAdapter } from "./adapter.mjs";
 import { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom } from "./auth-adapter.mjs";
-import { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.mjs";
+import { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredColumnMeta, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.mjs";
 import { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
-import { EntityMappingRow, mappingsToEntitiesConfig } from "./mappings-config.mjs";
+import { a as ProjectionIdentity, c as ProjectionRef, i as ProjectionFieldBinding, l as identityRefs, n as mappingsToEntitiesConfig, o as ProjectionJoin, r as BASE_REF, s as ProjectionMapping, t as EntityMappingRow, u as projectionSchema } from "./mappings-config-B0W5bVZj.mjs";
 import { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig } from "./view-compiler.mjs";
 import { EntitySyncResult, MirrorRecord, PersistAction, SourceRow, SyncAction, SyncResult, SyncStore, reconcile, runSync } from "./sync-engine.mjs";
-export { type Activity, type ActivityType, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type Note, type PersistAction, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };
+//#region src/projection-cardinality.d.ts
+declare function joinFansOut(join: ProjectionJoin, joinTable: DiscoveredSchemaTable): boolean;
+/** Every join in the projection that can multiply rows. */
+declare function fanOutJoins(projection: ProjectionMapping, tablesByName: Map<string, DiscoveredSchemaTable>): ProjectionJoin[];
+//#endregion
+//#region src/projection-draft.d.ts
+/**
+ * The builder's in-progress shape.
+ *
+ * A draft is deliberately looser than a `ProjectionMapping`: it exists while
+ * the user is still choosing things, so every field can be empty. All of the
+ * builder's rules live here as pure functions, which keeps the React components
+ * presentational and lets the rules be tested without a DOM.
+ */
+interface ProjectionDraft {
+  baseTable: string;
+  entityKey: string;
+  fieldBindings: Record<string, ProjectionFieldBinding>;
+  identity: ProjectionIdentity;
+  joins: ProjectionJoin[];
+}
+declare function emptyProjectionDraft(baseTable: string): ProjectionDraft;
+/**
+ * The ON conditions implied by a foreign key between the two tables, so the
+ * builder can pre-fill a join instead of making the user hand-pick columns.
+ * Returns [] when no FK relates them — the user then picks manually.
+ */
+declare function suggestJoinConditions(baseTable: string, joinTable: string, schema: DiscoveredSchemaTable[], joinKey: string): ProjectionJoin["on"];
+/** A draft becomes a projection once it has a valid key and ≥1 binding. */
+declare function draftToProjection(draft: ProjectionDraft): ProjectionMapping | null;
+declare function draftErrors(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): ConfigValidationError[];
+/** Per-join fan-out, for the builder's inline cardinality hints. */
+declare function describeCardinality(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): Array<{
+  fansOut: boolean;
+  joinKey: string;
+}>;
+//#endregion
+//#region src/projection-validate.d.ts
+/**
+ * Validate a projection against the discovered schema. Returns every error
+ * found (not just the first) so a builder UI can show them all at once.
+ */
+declare function validateProjection(projection: ProjectionMapping, schema: DiscoveredSchemaTable[], base: string): ConfigValidationError[];
+//#endregion
+//#region src/schema-meta.d.ts
+/**
+ * Accessors over a discovered table's schema-v2 metadata.
+ *
+ * Every helper treats *absent* metadata as **unknown**, never as a negative
+ * fact. `coversUniqueKey` returning false on a v1 payload is what makes
+ * projection validation fail closed: we cannot prove a join is many-to-one, so
+ * we refuse to compile it rather than guess.
+ */
+declare function columnMetaFor(table: DiscoveredSchemaTable, column: string): DiscoveredColumnMeta | undefined;
+/**
+ * Every primary-key column. More than one entry means a composite PK, which is
+ * why `base_pk` identity is rejected for such tables.
+ */
+declare function primaryKeyColumns(table: DiscoveredSchemaTable): string[];
+/**
+ * Do `columns` contain every column of at least one unique key on `table`?
+ *
+ * This is the fan-out test. A join whose ON columns cover a unique key of the
+ * joined table matches at most one row per base row; one that does not can
+ * match many.
+ */
+declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]): boolean;
+/** Is this table's payload rich enough to validate a projection against? */
+declare function hasRichMeta(table: DiscoveredSchemaTable): boolean;
+//#endregion
+export { type Activity, type ActivityType, BASE_REF, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredColumnMeta, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type Note, type PersistAction, type ProjectionDraft, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };

package/dist/index.mjs

@@ -1,7 +1,73 @@
 import { authCustom } from "./auth-adapter.mjs";
-import { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, MATERIALIZING_CONCEPTS, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.mjs";
+import { i as projectionSchema, n as PROJECTION_KEY_PATTERN, r as identityRefs, t as BASE_REF } from "./projection-C_EMRmZ8.mjs";
+import { _ as hasRichMeta, a as MATERIALIZING_CONCEPTS, c as filterSchema, d as validateEntitiesConfig, f as validateProjection, g as coversUniqueKey, h as columnMetaFor, i as ClivlyConfigError, l as relationshipSchema, m as joinFansOut, n as CRM_CONCEPTS, o as defineClivlyConfig, p as fanOutJoins, s as entitiesConfigSchema, t as CANONICAL_FIELDS, u as relationshipsSchema, v as primaryKeyColumns } from "./entity-config-Tb5bbKLj.mjs";
 import { buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
 import { mappingsToEntitiesConfig } from "./mappings-config.mjs";
-import { DEFAULT_VIEW_PREFIX, compileEntityView, compileEntityViews, explainEntitiesConfig } from "./view-compiler.mjs";
+import { i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-BKrBA_II.mjs";
 import { reconcile, runSync } from "./sync-engine.mjs";
-export { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };
+//#region src/projection-draft.ts
+function emptyProjectionDraft(baseTable) {
+	return {
+		baseTable,
+		entityKey: "",
+		fieldBindings: {},
+		identity: { kind: "base_pk" },
+		joins: []
+	};
+}
+/**
+* The ON conditions implied by a foreign key between the two tables, so the
+* builder can pre-fill a join instead of making the user hand-pick columns.
+* Returns [] when no FK relates them — the user then picks manually.
+*/
+function suggestJoinConditions(baseTable, joinTable, schema, joinKey) {
+	const join = schema.find((t) => t.name === joinTable);
+	const conditions = [];
+	for (const column of join?.columnsMeta ?? []) if (column.references?.table === baseTable) conditions.push({
+		left: {
+			table: joinKey,
+			column: column.name
+		},
+		op: "eq",
+		right: {
+			table: BASE_REF,
+			column: column.references.column
+		}
+	});
+	return conditions;
+}
+/** A draft becomes a projection once it has a valid key and ≥1 binding. */
+function draftToProjection(draft) {
+	if (!PROJECTION_KEY_PATTERN.test(draft.entityKey)) return null;
+	if (Object.keys(draft.fieldBindings).length === 0) return null;
+	return {
+		version: 1,
+		kind: "projection",
+		entityKey: draft.entityKey,
+		baseTable: draft.baseTable,
+		joins: draft.joins,
+		fieldBindings: draft.fieldBindings,
+		identity: draft.identity
+	};
+}
+function draftErrors(draft, schema) {
+	const projection = draftToProjection(draft);
+	if (!projection) return [{
+		path: "projection",
+		message: "Name the object and map a field."
+	}];
+	return validateProjection(projection, schema, "projection");
+}
+/** Per-join fan-out, for the builder's inline cardinality hints. */
+function describeCardinality(draft, schema) {
+	const projection = draftToProjection(draft);
+	if (!projection) return [];
+	const tablesByName = new Map(schema.map((t) => [t.name, t]));
+	const fanning = new Set(fanOutJoins(projection, tablesByName).map((j) => j.key));
+	return projection.joins.map((join) => ({
+		joinKey: join.key,
+		fansOut: fanning.has(join.key)
+	}));
+}
+//#endregion
+export { BASE_REF, CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };

package/dist/mappings-config-B0W5bVZj.d.mts

@@ -0,0 +1,168 @@
+import { ClivlyEntitiesConfig } from "./entity-config.mjs";
+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/mappings-config.d.ts
+/**
+ * Mappings → Entity Config bridge.
+ *
+ * `crm_entity_mappings` rows are the single source of truth for how a host
+ * schema maps onto Clivly's CRM concepts. This module compiles those rows into
+ * a `ClivlyEntitiesConfig` — the contract the view compiler and sync engine
+ * consume — so the persisted mapping and the runtime pipeline never diverge.
+ *
+ * The row model has no explicit entity-key column (it's keyed by
+ * `sourceTable + targetConcept + role`), but the config's `relationships`
+ * reference other entities *by key*. This builder therefore derives a stable
+ * key per row and resolves each relationship's `entity` reference through the
+ * same derivation — so a relationship stored as `entity: "<relatedTable>"`
+ * (the shape `mappings.suggest` produces) resolves to the right entity.
+ */
+/**
+ * A persisted `crm_entity_mappings` row, narrowed to the columns the builder
+ * reads. Structurally compatible with the Drizzle row (jsonb columns typed
+ * loosely) so the API layer can pass `db.select()` results straight in.
+ */
+interface EntityMappingRow {
+  fieldMap: Record<string, string>;
+  filter?: Record<string, unknown> | null;
+  /**
+   * Advanced mapping: a base table plus explicit joins. When set, this — not
+   * `fieldMap` — is the authored source of truth, and `sourceTable` merely
+   * mirrors `projection.baseTable`.
+   */
+  projection?: ProjectionMapping | null;
+  relationships?: Record<string, unknown> | null;
+  role?: string | null;
+  sourceTable: string;
+  status?: string | null;
+  targetConcept: string;
+  targetObjectTypeId?: string | null;
+}
+/**
+ * Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`
+ * rows with at least one mapped field are included; disabled/suggested rows and
+ * unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
+ * eligible — a no-op the view compiler and sync engine both tolerate.
+ */
+declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
+//#endregion
+export { ProjectionIdentity as a, ProjectionRef as c, ProjectionFieldBinding as i, identityRefs as l, mappingsToEntitiesConfig as n, ProjectionJoin as o, BASE_REF as r, ProjectionMapping as s, EntityMappingRow as t, projectionSchema as u };

package/dist/mappings-config-BWo4cRDF.d.cts

@@ -0,0 +1,168 @@
+import { ClivlyEntitiesConfig } from "./entity-config.cjs";
+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/mappings-config.d.ts
+/**
+ * Mappings → Entity Config bridge.
+ *
+ * `crm_entity_mappings` rows are the single source of truth for how a host
+ * schema maps onto Clivly's CRM concepts. This module compiles those rows into
+ * a `ClivlyEntitiesConfig` — the contract the view compiler and sync engine
+ * consume — so the persisted mapping and the runtime pipeline never diverge.
+ *
+ * The row model has no explicit entity-key column (it's keyed by
+ * `sourceTable + targetConcept + role`), but the config's `relationships`
+ * reference other entities *by key*. This builder therefore derives a stable
+ * key per row and resolves each relationship's `entity` reference through the
+ * same derivation — so a relationship stored as `entity: "<relatedTable>"`
+ * (the shape `mappings.suggest` produces) resolves to the right entity.
+ */
+/**
+ * A persisted `crm_entity_mappings` row, narrowed to the columns the builder
+ * reads. Structurally compatible with the Drizzle row (jsonb columns typed
+ * loosely) so the API layer can pass `db.select()` results straight in.
+ */
+interface EntityMappingRow {
+  fieldMap: Record<string, string>;
+  filter?: Record<string, unknown> | null;
+  /**
+   * Advanced mapping: a base table plus explicit joins. When set, this — not
+   * `fieldMap` — is the authored source of truth, and `sourceTable` merely
+   * mirrors `projection.baseTable`.
+   */
+  projection?: ProjectionMapping | null;
+  relationships?: Record<string, unknown> | null;
+  role?: string | null;
+  sourceTable: string;
+  status?: string | null;
+  targetConcept: string;
+  targetObjectTypeId?: string | null;
+}
+/**
+ * Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`
+ * rows with at least one mapped field are included; disabled/suggested rows and
+ * unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
+ * eligible — a no-op the view compiler and sync engine both tolerate.
+ */
+declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
+//#endregion
+export { ProjectionIdentity as a, ProjectionRef as c, ProjectionFieldBinding as i, identityRefs as l, mappingsToEntitiesConfig as n, ProjectionJoin as o, BASE_REF as r, ProjectionMapping as s, EntityMappingRow as t, projectionSchema as u };

package/dist/mappings-config.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config.cjs");
+const require_entity_config = require("./entity-config-PoOGzvpN.cjs");
 //#region src/mappings-config.ts
 const RESERVED_FIELD = "id";
 /**
@@ -22,7 +22,9 @@ function canonicalFields(concept, fieldMap) {
 const DEFAULT_ROLE = "primary";
 const ACTIVE_STATUS = "active";
 function isEligible(row) {
-	return (row.status ?? ACTIVE_STATUS) === ACTIVE_STATUS && Object.keys(row.fieldMap ?? {}).length > 0;
+	if ((row.status ?? ACTIVE_STATUS) !== ACTIVE_STATUS) return false;
+	if (row.projection) return Object.keys(row.projection.fieldBindings ?? {}).length > 0;
+	return Object.keys(row.fieldMap ?? {}).length > 0;
 }
 /**
 * Preferred key for a row: the bare source table when it backs a single entity,
@@ -46,13 +48,28 @@ function uniquify(base, used) {
 	used.add(key);
 	return key;
 }
+/**
+* A projection's `fields` map, derived mechanically from its bindings.
+*
+* `ClivlyEntityConfig.fields` is required and read by existing consumers, so a
+* projection entity must populate it. The values are ref *tokens*
+* (`"base.full_name"`), never host column names — the compiler reads
+* `projection.fieldBindings`, and `validateEntitiesConfig` skips the legacy
+* column check for projection entities precisely because of this.
+*/
+function projectionFields(projection) {
+	const fields = {};
+	for (const [field, binding] of Object.entries(projection.fieldBindings)) fields[field] = `${binding.from.table}.${binding.from.column}`;
+	return fields;
+}
 function buildEntity(row, refIndex) {
 	const entity = {
 		concept: row.targetConcept,
-		source: row.sourceTable,
+		source: row.projection?.baseTable ?? row.sourceTable,
 		role: row.role ?? DEFAULT_ROLE,
-		fields: canonicalFields(row.targetConcept, row.fieldMap)
+		fields: row.projection ? projectionFields(row.projection) : canonicalFields(row.targetConcept, row.fieldMap)
 	};
+	if (row.projection) entity.projection = row.projection;
 	if (row.targetConcept === "custom" && row.targetObjectTypeId) entity.targetObjectTypeId = row.targetObjectTypeId;
 	if (row.filter && Object.keys(row.filter).length > 0) entity.filter = row.filter;
 	if (row.relationships && Object.keys(row.relationships).length > 0) {
@@ -77,11 +94,16 @@ function buildEntity(row, refIndex) {
 function mappingsToEntitiesConfig(rows) {
 	const eligible = rows.filter(isEligible);
 	const tableCounts = /* @__PURE__ */ new Map();
-	for (const row of eligible) tableCounts.set(row.sourceTable, (tableCounts.get(row.sourceTable) ?? 0) + 1);
+	for (const row of eligible) {
+		if (row.projection) continue;
+		tableCounts.set(row.sourceTable, (tableCounts.get(row.sourceTable) ?? 0) + 1);
+	}
 	const used = /* @__PURE__ */ new Set();
 	const tableAnchor = /* @__PURE__ */ new Map();
 	const assigned = [];
-	for (const row of eligible) {
+	const legacyRows = eligible.filter((row) => !row.projection);
+	const projectionRows = eligible.filter((row) => row.projection);
+	for (const row of legacyRows) {
 		const key = uniquify(preferredKey(row, tableCounts), used);
 		assigned.push({
 			row,
@@ -89,6 +111,10 @@ function mappingsToEntitiesConfig(rows) {
 		});
 		if ((row.role ?? DEFAULT_ROLE) === DEFAULT_ROLE || !tableAnchor.has(row.sourceTable)) tableAnchor.set(row.sourceTable, key);
 	}
+	for (const row of projectionRows) assigned.push({
+		row,
+		key: uniquify(row.projection?.entityKey ?? row.sourceTable, used)
+	});
 	const refIndex = /* @__PURE__ */ new Map();
 	for (const { key } of assigned) refIndex.set(key, key);
 	for (const [table, key] of tableAnchor) if (!refIndex.has(table)) refIndex.set(table, key);

package/dist/mappings-config.d.cts

@@ -1,41 +1,2 @@
-import { ClivlyEntitiesConfig } from "./entity-config.cjs";
-//#region src/mappings-config.d.ts
-/**
- * Mappings → Entity Config bridge.
- *
- * `crm_entity_mappings` rows are the single source of truth for how a host
- * schema maps onto Clivly's CRM concepts. This module compiles those rows into
- * a `ClivlyEntitiesConfig` — the contract the view compiler and sync engine
- * consume — so the persisted mapping and the runtime pipeline never diverge.
- *
- * The row model has no explicit entity-key column (it's keyed by
- * `sourceTable + targetConcept + role`), but the config's `relationships`
- * reference other entities *by key*. This builder therefore derives a stable
- * key per row and resolves each relationship's `entity` reference through the
- * same derivation — so a relationship stored as `entity: "<relatedTable>"`
- * (the shape `mappings.suggest` produces) resolves to the right entity.
- */
-/**
- * A persisted `crm_entity_mappings` row, narrowed to the columns the builder
- * reads. Structurally compatible with the Drizzle row (jsonb columns typed
- * loosely) so the API layer can pass `db.select()` results straight in.
- */
-interface EntityMappingRow {
-  fieldMap: Record<string, string>;
-  filter?: Record<string, unknown> | null;
-  relationships?: Record<string, unknown> | null;
-  role?: string | null;
-  sourceTable: string;
-  status?: string | null;
-  targetConcept: string;
-  targetObjectTypeId?: string | null;
-}
-/**
- * Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`
- * rows with at least one mapped field are included; disabled/suggested rows and
- * unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
- * eligible — a no-op the view compiler and sync engine both tolerate.
- */
-declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
-//#endregion
+import { n as mappingsToEntitiesConfig, t as EntityMappingRow } from "./mappings-config-BWo4cRDF.cjs";
 export { EntityMappingRow, mappingsToEntitiesConfig };

package/dist/mappings-config.d.mts

@@ -1,41 +1,2 @@
-import { ClivlyEntitiesConfig } from "./entity-config.mjs";
-//#region src/mappings-config.d.ts
-/**
- * Mappings → Entity Config bridge.
- *
- * `crm_entity_mappings` rows are the single source of truth for how a host
- * schema maps onto Clivly's CRM concepts. This module compiles those rows into
- * a `ClivlyEntitiesConfig` — the contract the view compiler and sync engine
- * consume — so the persisted mapping and the runtime pipeline never diverge.
- *
- * The row model has no explicit entity-key column (it's keyed by
- * `sourceTable + targetConcept + role`), but the config's `relationships`
- * reference other entities *by key*. This builder therefore derives a stable
- * key per row and resolves each relationship's `entity` reference through the
- * same derivation — so a relationship stored as `entity: "<relatedTable>"`
- * (the shape `mappings.suggest` produces) resolves to the right entity.
- */
-/**
- * A persisted `crm_entity_mappings` row, narrowed to the columns the builder
- * reads. Structurally compatible with the Drizzle row (jsonb columns typed
- * loosely) so the API layer can pass `db.select()` results straight in.
- */
-interface EntityMappingRow {
-  fieldMap: Record<string, string>;
-  filter?: Record<string, unknown> | null;
-  relationships?: Record<string, unknown> | null;
-  role?: string | null;
-  sourceTable: string;
-  status?: string | null;
-  targetConcept: string;
-  targetObjectTypeId?: string | null;
-}
-/**
- * Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`
- * rows with at least one mapped field are included; disabled/suggested rows and
- * unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
- * eligible — a no-op the view compiler and sync engine both tolerate.
- */
-declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
-//#endregion
+import { n as mappingsToEntitiesConfig, t as EntityMappingRow } from "./mappings-config-B0W5bVZj.mjs";
 export { EntityMappingRow, mappingsToEntitiesConfig };