clivly 0.8.0 → 0.9.0

package/{entity-config-va2bkH5o.mjs → projection-C5244vGa.cjs}

@@ -4203,333 +4203,154 @@ function superRefine(fn, params) {
 	return /* @__PURE__ */ _superRefine(fn, params);
 }
 //#endregion
-//#region ../core/src/entity-config.ts
+//#region ../core/src/projection.ts
 /**
-* Entity Config v2 — the declarative contract that turns Clivly's "schema-aware"
-* promise into a real capability.
+* Projection-backed custom mappings — one custom object derived from a base
+* table plus explicit joins.
 *
-* 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`.
+* 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.
 *
-* 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.
+* 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.
 */
-/** 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 = union([
-	strictObject({ eq: union([
-		string(),
-		number(),
-		boolean()
-	]) }),
-	strictObject({ ne: union([
-		string(),
-		number(),
-		boolean()
-	]) }),
-	strictObject({ in: array(union([
-		string(),
-		number(),
-		boolean()
-	])).min(1) }),
-	strictObject({ notIn: array(union([
-		string(),
-		number(),
-		boolean()
-	])).min(1) }),
-	strictObject({ isNull: literal(true) }),
-	strictObject({ isNotNull: literal(true) })
-]);
-const filterValueSchema = union([
-	string(),
-	number(),
-	boolean(),
-	filterOperatorsSchema
-]);
-/** `$raw` is a reserved key; a column literally named `$raw` is not addressable. */
-const filterSchema = union([strictObject({ $raw: string().min(1) }), record(string(), 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.
-*/
-const relationshipViaSchema = union([
+/** The reserved ref name for the projection's base table. */
+const BASE_REF = "base";
+/** Entity keys become view names (`crm_src_<entityKey>`), so keep them slugs. */
+const PROJECTION_KEY_PATTERN = /^[a-z][a-z0-9_]*$/;
+const projectionRefSchema = strictObject({
+	table: string().min(1),
+	column: string().min(1)
+});
+const projectionJoinConditionSchema = strictObject({
+	left: projectionRefSchema,
+	op: literal("eq"),
+	right: projectionRefSchema
+});
+const projectionJoinSchema = strictObject({
+	/** SQL alias and ref target. Unique within the projection. */
+	key: string().regex(PROJECTION_KEY_PATTERN),
+	table: string().min(1),
+	type: _enum(["inner", "left"]),
+	on: array(projectionJoinConditionSchema).min(1)
+});
+const projectionFieldBindingSchema = strictObject({ from: projectionRefSchema });
+const projectionIdentitySchema = union([
 	strictObject({
-		fkOn: _enum(["company", "contact"]),
-		column: string().min(1)
+		kind: literal("base_pk"),
+		/** Defaults to the discovered single-column PK of the base table. */
+		column: string().min(1).optional()
 	}),
 	strictObject({
-		through: string().min(1),
-		localKey: string().min(1),
-		foreignKey: string().min(1)
+		kind: literal("column"),
+		from: projectionRefSchema
 	}),
-	strictObject({ $raw: string().min(1) })
+	strictObject({
+		kind: literal("composite"),
+		parts: array(projectionRefSchema).min(2)
+	})
 ]);
-const relationshipSchema = strictObject({
-	/** Key of the related entity in the `entities` map. */
-	entity: string().min(1),
-	via: relationshipViaSchema
-});
-/** A named map of relationships, as stored on an entity / in the mappings row. */
-const relationshipsSchema = record(string(), relationshipSchema);
-const entitySchema = strictObject({
-	/** Which CRM concept this entity maps onto — a canonical concept or "custom". */
-	concept: union([_enum(CRM_CONCEPTS), literal(CUSTOM_CONCEPT)]),
-	/** Host table (or view) this entity is derived from. */
-	source: 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: 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: record(string(), 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: array(string()).optional(),
-	/** Named relationships to other entities in this config. */
-	relationships: record(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: string().min(1).optional()
-});
-const entitiesConfigSchema = strictObject({ entities: record(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);
-}
+const projectionSchema = strictObject({
+	version: literal(1),
+	kind: literal("projection"),
+	entityKey: string().regex(PROJECTION_KEY_PATTERN),
+	baseTable: string().min(1),
+	joins: array(projectionJoinSchema),
+	fieldBindings: record(string(), projectionFieldBindingSchema).refine((b) => Object.keys(b).length > 0, { message: "at least one field must be bound" }),
+	identity: projectionIdentitySchema
+});
 /**
-* 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`.
+* 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.
 */
-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)
-	};
+function identityRefs(identity, basePkColumn) {
+	if (identity.kind === "base_pk") return [{
+		table: BASE_REF,
+		column: identity.column ?? basePkColumn
+	}];
+	if (identity.kind === "column") return [identity.from];
+	return identity.parts;
 }
-/** 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));
+//#endregion
+Object.defineProperty(exports, "BASE_REF", {
+	enumerable: true,
+	get: function() {
+		return BASE_REF;
 	}
-	tableExists(name) {
-		return this.columnsByTable.has(name);
+});
+Object.defineProperty(exports, "PROJECTION_KEY_PATTERN", {
+	enumerable: true,
+	get: function() {
+		return PROJECTION_KEY_PATTERN;
 	}
-	columnExists(table, column) {
-		return this.columnsByTable.get(table)?.has(column) ?? false;
+});
+Object.defineProperty(exports, "_enum", {
+	enumerable: true,
+	get: function() {
+		return _enum;
 	}
-	report(path, message) {
-		this.errors.push({
-			path,
-			message
-		});
+});
+Object.defineProperty(exports, "array", {
+	enumerable: true,
+	get: function() {
+		return array;
 	}
-	/** 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;
+});
+Object.defineProperty(exports, "boolean", {
+	enumerable: true,
+	get: function() {
+		return boolean;
 	}
-};
-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;
+});
+Object.defineProperty(exports, "identityRefs", {
+	enumerable: true,
+	get: function() {
+		return identityRefs;
 	}
-	if (!v.tableExists(fkTable)) {
-		v.report(path, `table "${fkTable}" is not in the discovered schema`);
-		return;
+});
+Object.defineProperty(exports, "literal", {
+	enumerable: true,
+	get: function() {
+		return literal;
 	}
-	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;
+});
+Object.defineProperty(exports, "number", {
+	enumerable: true,
+	get: function() {
+		return number;
 	}
-	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;
+});
+Object.defineProperty(exports, "projectionSchema", {
+	enumerable: true,
+	get: function() {
+		return projectionSchema;
 	}
-	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
-export { MATERIALIZING_CONCEPTS as a, filterSchema as c, validateEntitiesConfig as d, ClivlyConfigError as i, relationshipSchema as l, CRM_CONCEPTS as n, defineClivlyConfig as o, CUSTOM_CONCEPT as r, entitiesConfigSchema as s, CANONICAL_FIELDS as t, relationshipsSchema as u };
+});
+Object.defineProperty(exports, "record", {
+	enumerable: true,
+	get: function() {
+		return record;
+	}
+});
+Object.defineProperty(exports, "strictObject", {
+	enumerable: true,
+	get: function() {
+		return strictObject;
+	}
+});
+Object.defineProperty(exports, "string", {
+	enumerable: true,
+	get: function() {
+		return string;
+	}
+});
+Object.defineProperty(exports, "union", {
+	enumerable: true,
+	get: function() {
+		return union;
+	}
+});