clivly 0.8.0 → 0.9.1

package/{sdk-C6WANW8M.mjs → sdk-BvRD2jAp.mjs}

@@ -276,6 +276,46 @@ function errorMessage(error) {
 }
 //#endregion
 //#region ../sdk/src/doctor.ts
+const TEMPORAL_CURSOR_TYPES = [
+	"timestamp",
+	"timestamptz",
+	"datetime",
+	"date",
+	"time"
+];
+/**
+* Warn when the sync cursor cannot observe an update.
+*
+* `clivly init` falls back to the primary key when a table has no
+* `updated_at`-like column, and emits a TODO saying "confirm it is monotonic".
+* A serial `id` *is* monotonic, so the note reads as satisfied — but monotonic
+* is only half the requirement. An `id` never changes, so every insert mirrors
+* and **no edit ever does**: a contact who changes their email keeps the old one
+* in the CRM forever, with nothing anywhere reporting a problem.
+*
+* A code comment could not enforce this; a real integrator shipped exactly this
+* configuration to production. This is the check that says so out loud.
+*/
+function cursorMonotonicityCheck(source) {
+	const meta = source[DRIZZLE_META];
+	if (!meta?.columnsMeta) return null;
+	const index = meta.columnKeys.indexOf(meta.cursorField);
+	const type = meta.columnsMeta[index]?.type?.toLowerCase();
+	if (!type) return null;
+	const temporal = TEMPORAL_CURSOR_TYPES.some((t) => type.startsWith(t));
+	const name = `Cursor tracks updates (${source.entity})`;
+	if (temporal) return {
+		name,
+		ok: true,
+		detail: `"${source.entity}" pages on ${meta.cursorField} (${type}) — edits re-sync.`
+	};
+	return {
+		name,
+		ok: true,
+		warn: true,
+		detail: `"${source.entity}" pages on ${meta.cursorField} (${type}), which does not change when a row is edited — inserts will sync, edits will not. Add an updated_at column to "${meta.tableName ?? source.entity}" and set it as the cursor, or accept insert-only mirroring.`
+	};
+}
 function configuredSources(config) {
 	const sources = [];
 	if (config.source?.contacts) sources.push(config.source.contacts);
@@ -304,32 +344,12 @@ async function mappingDryRunChecks(config) {
 	return checks;
 }
 /**
-* Run the read-only setup checks and return a structured report. Every check
-* captures its own error into `detail` rather than throwing, so one failure never
-* hides the rest. `ok` is the AND of all non-skipped checks.
+* Confirm each drizzle source actually has the cursor and id columns the sync
+* pages on. Hand-written sources have no column metadata, so they are skipped
+* rather than failed.
 */
-async function runDoctor(args) {
-	const { config, connect } = args;
+function cursorColumnChecks(sources) {
 	const checks = [];
-	const sources = configuredSources(config);
-	const hasKey = Boolean(config.apiKey);
-	checks.push({
-		name: "API key present",
-		ok: hasKey,
-		detail: hasKey ? "CLIVLY_API_KEY is set." : "apiKey is empty — set CLIVLY_API_KEY."
-	});
-	const entityCount = config.entities ? Object.keys(config.entities.entities).length : 0;
-	checks.push({
-		name: "Entities configured",
-		ok: entityCount > 0,
-		detail: entityCount > 0 ? `${entityCount} entit${entityCount === 1 ? "y" : "ies"} configured.` : "No `entities` config — pass defineClivlyConfig(...) as `entities`."
-	});
-	checks.push({
-		name: "Sources configured",
-		ok: sources.length > 0,
-		detail: sources.length > 0 ? `${sources.length} source(s) to mirror.` : "No `source.contacts` — nothing to sync."
-	});
-	checks.push(checkConceptCoverage(config));
 	for (const source of sources) {
 		const meta = source[DRIZZLE_META];
 		if (!meta) {
@@ -341,7 +361,7 @@ async function runDoctor(args) {
 			});
 			continue;
 		}
-		const idField = source.idField ?? "id";
+		const idField = meta.idField ?? source.idField ?? "id";
 		const missing = [meta.cursorField, idField].filter((field) => !meta.columnKeys.includes(field));
 		checks.push({
 			name: `Cursor/id columns exist (${source.entity})`,
@@ -349,6 +369,14 @@ async function runDoctor(args) {
 			detail: missing.length === 0 ? `"${source.entity}": ${meta.cursorField} + ${idField} present.` : `"${source.entity}" missing column(s): ${missing.join(", ")}.`
 		});
 	}
+	return checks;
+}
+/**
+* Read one row from each source to prove the query works and that rows actually
+* carry the cursor key. Fetch errors are captured as failures, never thrown.
+*/
+async function sampleFetchChecks(sources) {
+	const checks = [];
 	for (const source of sources) try {
 		const rows = await source.fetchPage({
 			since: null,
@@ -368,10 +396,45 @@ async function runDoctor(args) {
 			detail: describeFetchError(source.entity, error)
 		});
 	}
+	return checks;
+}
+/**
+* Run the read-only setup checks and return a structured report. Every check
+* captures its own error into `detail` rather than throwing, so one failure never
+* hides the rest. `ok` is the AND of all non-skipped checks.
+*/
+async function runDoctor(args) {
+	const { config, probe } = args;
+	const checks = [];
+	const sources = configuredSources(config);
+	const hasKey = Boolean(config.apiKey);
+	checks.push({
+		name: "API key present",
+		ok: hasKey,
+		detail: hasKey ? "CLIVLY_API_KEY is set." : "apiKey is empty — set CLIVLY_API_KEY."
+	});
+	const entityCount = config.entities ? Object.keys(config.entities.entities).length : 0;
+	checks.push({
+		name: "Entities configured",
+		ok: entityCount > 0,
+		detail: entityCount > 0 ? `${entityCount} entit${entityCount === 1 ? "y" : "ies"} configured.` : "No `entities` config — pass defineClivlyConfig(...) as `entities`."
+	});
+	checks.push({
+		name: "Sources configured",
+		ok: sources.length > 0,
+		detail: sources.length > 0 ? `${sources.length} source(s) to mirror.` : "No `source.contacts` — nothing to sync."
+	});
+	checks.push(checkConceptCoverage(config));
+	checks.push(...cursorColumnChecks(sources));
+	for (const source of sources) {
+		const check = cursorMonotonicityCheck(source);
+		if (check) checks.push(check);
+	}
+	checks.push(...await sampleFetchChecks(sources));
 	checks.push(...await mappingDryRunChecks(config));
-	const result = await connect();
+	const result = await probe();
 	checks.push({
-		name: "Heartbeat",
+		name: "Clivly reachable",
 		ok: result.ok,
 		detail: result.ok ? `Reached Clivly — org "${result.org?.name ?? "(unnamed)"}".` : `Could not connect (${result.reason}).`
 	});
@@ -810,6 +873,7 @@ const UNAUTHORIZED_STATUS = 401;
 const FORBIDDEN_STATUS = 403;
 const CLIENT_ERROR_FLOOR = 400;
 const SERVICE_UNAVAILABLE_STATUS = 503;
+const NOT_FOUND_STATUS = 404;
 function connectReason(status) {
 	if (status === UNAUTHORIZED_STATUS) return "invalid_api_key";
 	if (status === FORBIDDEN_STATUS) return "forbidden";
@@ -818,6 +882,10 @@ function connectReason(status) {
 	if (status >= CLIENT_ERROR_FLOOR) return "client_error";
 	return "server_error";
 }
+function pingReason(status) {
+	if (status === NOT_FOUND_STATUS) return "server_too_old";
+	return connectReason(status);
+}
 async function resolveOrg(response) {
 	try {
 		return (await response.json())?.org;
@@ -1049,9 +1117,38 @@ function createClivlySDK(config) {
 			retryable: isRetryableStatus(response.status)
 		};
 	};
+	const ping = async () => {
+		const response = await fetcher(`${apiUrl}/clivly/sdk/ping`, {
+			method: "GET",
+			headers: { authorization: `Bearer ${config.apiKey}` }
+		});
+		if (response === null) return {
+			ok: false,
+			status: null,
+			reason: "network_error",
+			retryable: true
+		};
+		if (response.ok) {
+			const body = await response.json().catch(() => ({}));
+			return {
+				ok: true,
+				status: response.status,
+				reason: "ok",
+				retryable: false,
+				org: body?.org,
+				..."appLastSeenAt" in body ? { appLastSeenAt: body.appLastSeenAt ?? null } : {}
+			};
+		}
+		return {
+			ok: false,
+			status: response.status,
+			reason: pingReason(response.status),
+			retryable: isRetryableStatus(response.status)
+		};
+	};
 	const doctor = () => runDoctor({
 		config,
-		connect
+		probe: ping
 	});
 	const runScheduled = async (options) => {
 		await heartbeat();
@@ -1144,6 +1241,7 @@ function createClivlySDK(config) {
 		stop,
 		heartbeat,
 		connect,
+		ping,
 		doctor,
 		runScheduled,
 		createClivlyHandler,

package/sdk.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-D87rV-tE.cjs");
-const require_sdk = require("./sdk-iqOXeWIp.cjs");
+const require_entity_config = require("./entity-config-nuXge6rY.cjs");
+const require_sdk = require("./sdk-Bj-ZDf4u.cjs");
 exports.ClivlyAuthError = require_sdk.ClivlyAuthError;
 exports.ClivlyError = require_sdk.ClivlyError;
 exports.ClivlyNetworkError = require_sdk.ClivlyNetworkError;

package/sdk.d.cts

@@ -1 +1,36 @@
-export {}
+import { a as ClivlyEntitiesConfig, x as defineClivlyConfig } from "./entity-config-fKQhimtD.cjs";
+import { a as ClivlyConnectResult, c as ClivlyUser, d as DiscoveredTable, f as DoctorCheck, i as ClivlyConnectReason, l as CreateChatSessionHandlerOptions, n as ChatSessionRequestBody, o as ClivlySDK, p as DoctorReport, r as ChatWidgetVisitor, s as ClivlySDKConfig, u as CursorStore } from "./namespace-probe-aRFmpU85.cjs";
+//#region ../sdk/src/chat-session.d.ts
+declare function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl, fetchImpl, resolveUser }: CreateChatSessionHandlerOptions): (request: Request) => Promise<Response>;
+//#endregion
+//#region ../sdk/src/errors.d.ts
+declare class ClivlyError extends Error {
+  /** HTTP status, or null when the request never completed (network error). */
+  readonly status: number | null;
+  readonly reason: ClivlyConnectResult["reason"];
+  /** Whether a retry could plausibly succeed (network, 429, 5xx). */
+  readonly retryable: boolean;
+  constructor(result: ClivlyConnectResult, message?: string);
+  /**
+   * Build the error subclass matching a failed result's reason, or `null` when
+   * the result is `ok`.
+   */
+  static from(result: ClivlyConnectResult): ClivlyError | null;
+}
+/** The API key was rejected (401) or lacks access (403). Not retryable. */
+declare class ClivlyAuthError extends ClivlyError {}
+/** Rate limited (429). Retryable after backoff / `Retry-After`. */
+declare class ClivlyRateLimitError extends ClivlyError {}
+/** The request never reached the server (network/DNS/TLS). Retryable. */
+declare class ClivlyNetworkError extends ClivlyError {}
+//#endregion
+//#region ../sdk/src/index.d.ts
+/**
+ * Create the Clivly SDK. The implemented surface — heartbeat/discovery reporting
+ * and the auth-verify handler — connects a developer's app to a running Clivly
+ * backend today. Tunnel management and CRM write-back are scaffolded (see the
+ * clearly-marked TODOs) and land with the Cloudflare infrastructure.
+ */
+declare function createClivlySDK(config: ClivlySDKConfig): ClivlySDK;
+//#endregion
+export { type ChatSessionRequestBody, type ChatWidgetVisitor, ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, type ClivlyEntitiesConfig, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type CreateChatSessionHandlerOptions, type CursorStore, type DiscoveredTable, type DoctorCheck, type DoctorReport, createChatSessionHandler, createClivlySDK, defineClivlyConfig };

package/sdk.d.mts

@@ -1 +1,36 @@
-export {}
+import { a as ClivlyEntitiesConfig, x as defineClivlyConfig } from "./entity-config-fKQhimtD.mjs";
+import { a as ClivlyConnectResult, c as ClivlyUser, d as DiscoveredTable, f as DoctorCheck, i as ClivlyConnectReason, l as CreateChatSessionHandlerOptions, n as ChatSessionRequestBody, o as ClivlySDK, p as DoctorReport, r as ChatWidgetVisitor, s as ClivlySDKConfig, u as CursorStore } from "./namespace-probe-BkUs8raG.mjs";
+//#region ../sdk/src/chat-session.d.ts
+declare function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl, fetchImpl, resolveUser }: CreateChatSessionHandlerOptions): (request: Request) => Promise<Response>;
+//#endregion
+//#region ../sdk/src/errors.d.ts
+declare class ClivlyError extends Error {
+  /** HTTP status, or null when the request never completed (network error). */
+  readonly status: number | null;
+  readonly reason: ClivlyConnectResult["reason"];
+  /** Whether a retry could plausibly succeed (network, 429, 5xx). */
+  readonly retryable: boolean;
+  constructor(result: ClivlyConnectResult, message?: string);
+  /**
+   * Build the error subclass matching a failed result's reason, or `null` when
+   * the result is `ok`.
+   */
+  static from(result: ClivlyConnectResult): ClivlyError | null;
+}
+/** The API key was rejected (401) or lacks access (403). Not retryable. */
+declare class ClivlyAuthError extends ClivlyError {}
+/** Rate limited (429). Retryable after backoff / `Retry-After`. */
+declare class ClivlyRateLimitError extends ClivlyError {}
+/** The request never reached the server (network/DNS/TLS). Retryable. */
+declare class ClivlyNetworkError extends ClivlyError {}
+//#endregion
+//#region ../sdk/src/index.d.ts
+/**
+ * Create the Clivly SDK. The implemented surface — heartbeat/discovery reporting
+ * and the auth-verify handler — connects a developer's app to a running Clivly
+ * backend today. Tunnel management and CRM write-back are scaffolded (see the
+ * clearly-marked TODOs) and land with the Cloudflare infrastructure.
+ */
+declare function createClivlySDK(config: ClivlySDKConfig): ClivlySDK;
+//#endregion
+export { type ChatSessionRequestBody, type ChatWidgetVisitor, ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, type ClivlyEntitiesConfig, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type CreateChatSessionHandlerOptions, type CursorStore, type DiscoveredTable, type DoctorCheck, type DoctorReport, createChatSessionHandler, createClivlySDK, defineClivlyConfig };

package/sdk.mjs

@@ -1,3 +1,3 @@
-import { o as defineClivlyConfig } from "./entity-config-va2bkH5o.mjs";
-import { a as ClivlyRateLimitError, i as ClivlyNetworkError, n as ClivlyAuthError, o as createChatSessionHandler, r as ClivlyError, t as createClivlySDK } from "./sdk-C6WANW8M.mjs";
+import { o as defineClivlyConfig } from "./entity-config-D08zAeFY.mjs";
+import { a as ClivlyRateLimitError, i as ClivlyNetworkError, n as ClivlyAuthError, o as createChatSessionHandler, r as ClivlyError, t as createClivlySDK } from "./sdk-BvRD2jAp.mjs";
 export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createChatSessionHandler, createClivlySDK, defineClivlyConfig };

package/{sync-engine-DGk_AeHJ.d.mts → sync-engine-DHQ7rXZe.d.mts}

@@ -1,5 +1,5 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-DoUCXtq5.mjs";
-import { n as CompiledView, t as CompileOptions } from "./view-compiler-Bn_EJJMO.mjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-fKQhimtD.mjs";
+import { n as CompiledView, t as CompileOptions } from "./view-compiler-CcUwzZut.mjs";
 //#region ../core/src/sync-engine.d.ts
 /**
  * Sync engine (Phase 3) — materializes the read-only entity views into Clivly's

package/{sync-engine-B7QIbXro.d.cts → sync-engine-DiPjH53O.d.cts}

@@ -1,5 +1,5 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-DoUCXtq5.cjs";
-import { n as CompiledView, t as CompileOptions } from "./view-compiler-BWz0sGdm.cjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-fKQhimtD.cjs";
+import { n as CompiledView, t as CompileOptions } from "./view-compiler-DqAdVxLq.cjs";
 //#region ../core/src/sync-engine.d.ts
 /**
  * Sync engine (Phase 3) — materializes the read-only entity views into Clivly's

package/{sync-engine-Do5ru3WF.mjs → sync-engine-SuxSzbZ4.mjs}

@@ -1,4 +1,4 @@
-import { r as compileEntityViews } from "./view-compiler-ChWr_Lml.mjs";
+import { r as compileEntityViews } from "./view-compiler-CQx8TRrW.mjs";
 //#region ../core/src/sync-engine.ts
 /**
 * Diff a view's rows against the current mirror population for one entity.
@@ -170,10 +170,17 @@ function isEmptyValue(value) {
 */
 function computeSampleWarnings(rows, requiredFields, sourceTable) {
 	if (rows.length === 0) return [{ message: `no rows found in ${sourceTable}` }];
+	const seenRefs = /* @__PURE__ */ new Set();
+	const duplicateRefs = /* @__PURE__ */ new Set();
+	for (const row of rows) {
+		if (seenRefs.has(row.sourceRef)) duplicateRefs.add(row.sourceRef);
+		seenRefs.add(row.sourceRef);
+	}
+	const identityWarnings = duplicateRefs.size > 0 ? [{ message: `duplicate id in ${duplicateRefs.size} of ${rows.length} sampled rows — identity is not unique, so sync would collapse these into one record` }] : [];
 	const required = new Set(requiredFields);
 	const fields = new Set(requiredFields);
 	for (const row of rows) for (const key of Object.keys(row.fields)) fields.add(key);
-	const warnings = [];
+	const warnings = [...identityWarnings];
 	for (const field of [...fields].sort()) {
 		const emptyCount = rows.filter((row) => isEmptyValue(row.fields[field])).length;
 		if (required.has(field)) {

package/{sync-engine-CzEbpQGv.cjs → sync-engine-abE94g6X.cjs}

@@ -1,4 +1,4 @@
-const require_view_compiler = require("./view-compiler-BIwvm-o2.cjs");
+const require_view_compiler = require("./view-compiler-Blu4OXJ7.cjs");
 //#region ../core/src/sync-engine.ts
 /**
 * Diff a view's rows against the current mirror population for one entity.
@@ -170,10 +170,17 @@ function isEmptyValue(value) {
 */
 function computeSampleWarnings(rows, requiredFields, sourceTable) {
 	if (rows.length === 0) return [{ message: `no rows found in ${sourceTable}` }];
+	const seenRefs = /* @__PURE__ */ new Set();
+	const duplicateRefs = /* @__PURE__ */ new Set();
+	for (const row of rows) {
+		if (seenRefs.has(row.sourceRef)) duplicateRefs.add(row.sourceRef);
+		seenRefs.add(row.sourceRef);
+	}
+	const identityWarnings = duplicateRefs.size > 0 ? [{ message: `duplicate id in ${duplicateRefs.size} of ${rows.length} sampled rows — identity is not unique, so sync would collapse these into one record` }] : [];
 	const required = new Set(requiredFields);
 	const fields = new Set(requiredFields);
 	for (const row of rows) for (const key of Object.keys(row.fields)) fields.add(key);
-	const warnings = [];
+	const warnings = [...identityWarnings];
 	for (const field of [...fields].sort()) {
 		const emptyCount = rows.filter((row) => isEmptyValue(row.fields[field])).length;
 		if (required.has(field)) {

package/{view-compiler-BIwvm-o2.cjs → view-compiler-Blu4OXJ7.cjs}

@@ -1,3 +1,58 @@
+const require_projection = require("./projection-C5244vGa.cjs");
+//#region ../core/src/projection-sql.ts
+/**
+* SQL generation for projection-backed entities.
+*
+* Base and joins are aliased by their ref key (`base`, then each join's `key`),
+* which is what allows the same table to be joined twice and keeps generated
+* SQL independent of host table names.
+*
+* Pure string generation — no DB access. Identifiers are escaped so output is
+* deterministic and injection-safe.
+*/
+/** Quote a single identifier part, escaping embedded double-quotes. */
+function quoteIdent(name) {
+	return `"${name.replace(/"/g, "\"\"")}"`;
+}
+function refSql(ref) {
+	return `${quoteIdent(ref.table)}.${quoteIdent(ref.column)}`;
+}
+/**
+* The identity expression, aliased as `id`. Composite identities concatenate
+* their parts with `::`; validation guarantees every part is NOT NULL and
+* non-text, which is what makes the concatenation collision-free.
+*/
+function identitySql(projection, basePkColumn) {
+	const refs = require_projection.identityRefs(projection.identity, basePkColumn);
+	if (projection.identity.kind === "composite") return `CONCAT_WS('::', ${refs.map((ref) => `${refSql(ref)}::text`).join(", ")}) AS ${quoteIdent("id")}`;
+	const [ref] = refs;
+	if (!ref) throw new Error("projection identity resolved to no column");
+	return `${refSql(ref)} AS ${quoteIdent("id")}`;
+}
+function compileProjectionSelect(projection, basePkColumn) {
+	const selectItems = [identitySql(projection, basePkColumn)];
+	const columns = ["id"];
+	for (const [field, binding] of Object.entries(projection.fieldBindings)) {
+		selectItems.push(`${refSql(binding.from)} AS ${quoteIdent(field)}`);
+		columns.push(field);
+	}
+	return {
+		columns,
+		selectItems
+	};
+}
+function compileProjectionJoins(projection) {
+	return projection.joins.map((join) => {
+		const keyword = join.type === "inner" ? "INNER JOIN" : "LEFT JOIN";
+		const on = join.on.map((c) => `${refSql(c.left)} = ${refSql(c.right)}`).join(" AND ");
+		return `${keyword} ${quoteIdent(join.table)} AS ${quoteIdent(join.key)} ON ${on}`;
+	});
+}
+/** `FROM <baseTable> AS "base"` — the alias every ref resolves against. */
+function compileProjectionFrom(projection) {
+	return `FROM ${quoteIdent(projection.baseTable)} AS ${quoteIdent(require_projection.BASE_REF)}`;
+}
+//#endregion
 //#region ../core/src/view-compiler.ts
 /**
 * View compiler (Phase 2) — turns a validated entity config into read-only
@@ -22,10 +77,6 @@
 const SOURCE_KEY = "id";
 const DEFAULT_VIEW_PREFIX = "crm_src_";
 const DEFAULT_ROLE = "primary";
-/** Quote a single identifier part, escaping embedded double-quotes. */
-function quoteIdent(name) {
-	return `"${name.replace(/"/g, "\"\"")}"`;
-}
 /** Emit a SQL literal for a scalar filter value. */
 function quoteLiteral(value) {
 	if (typeof value === "number") return String(value);
@@ -106,17 +157,24 @@ function compileRelationship(relName, rel, source, related) {
 		refColumn: refCol
 	};
 }
-function compileEntityView(config, entityKey, options = {}) {
-	const entity = config.entities[entityKey];
-	if (!entity) throw new Error(`entity "${entityKey}" is not defined`);
-	const viewName = `${options.viewPrefix ?? "crm_src_"}${entityKey}`;
-	const src = entity.source;
+/** SELECT items for a legacy single-table entity: source key, then fields. */
+function legacySelect(entity, src) {
 	const selectItems = [`${quoteIdent(src)}.${quoteIdent(SOURCE_KEY)} AS ${quoteIdent("id")}`];
 	const columns = ["id"];
 	for (const [field, column] of Object.entries(entity.fields)) {
 		selectItems.push(`${quoteIdent(src)}.${quoteIdent(column)} AS ${quoteIdent(field)}`);
 		columns.push(field);
 	}
+	return {
+		columns,
+		selectItems
+	};
+}
+/**
+* Relationship JOINs for a legacy entity. Appends each relationship's ref
+* column to `columns`/`selectItems` in place, preserving the existing order.
+*/
+function legacyJoins(config, entity, columns, selectItems) {
 	const joins = [];
 	for (const [relName, rel] of Object.entries(entity.relationships ?? {})) {
 		const compiled = compileRelationship(relName, rel, entity, config.entities[rel.entity]);
@@ -126,12 +184,39 @@ function compileEntityView(config, entityKey, options = {}) {
 			columns.push(compiled.refColumn);
 		}
 	}
-	const conditions = compileFilterConditions(src, entity.filter);
-	if (options.orgScope) conditions.push(`${quoteIdent(src)}.${quoteIdent(options.orgScope.column)} = ${quoteLiteral(options.orgScope.value)}`);
+	return joins;
+}
+/**
+* Translate a driver error from executing a compiled view into something
+* actionable, or `undefined` when it is not one we recognise (caller rethrows).
+*
+* The case that matters: `WITH (security_invoker = true)` needs Postgres 15,
+* and PG 14 rejects it with sqlstate 22023 naming a Postgres internal
+* (`reloptions.c`) — no mention of Clivly, the option, or the version. The
+* compiler cannot catch this itself because the host executes the SQL.
+*/
+function explainViewExecutionError(error) {
+	if (typeof error !== "object" || error === null) return;
+	const { code, routine } = error;
+	const message = error instanceof Error ? error.message : "";
+	if (!(code === "22023" && (routine === "parseRelOptionsInternal" || message.includes("security_invoker")))) return;
+	return "CREATE VIEW … WITH (security_invoker = true) requires Postgres 15+. Pass `securityInvoker: false` to compile without it — but note the view then runs with its owner's privileges instead of the querying role's, which bypasses row-level security (RLS) on the underlying tables. Prefer upgrading Postgres if you rely on RLS to separate tenants.";
+}
+function compileEntityView(config, entityKey, options = {}) {
+	const entity = config.entities[entityKey];
+	if (!entity) throw new Error(`entity "${entityKey}" is not defined`);
+	const viewName = `${options.viewPrefix ?? "crm_src_"}${entityKey}`;
+	const src = entity.source;
+	const projection = entity.projection;
+	const filterTable = projection ? require_projection.BASE_REF : src;
+	const { selectItems, columns } = projection ? compileProjectionSelect(projection, SOURCE_KEY) : legacySelect(entity, src);
+	const joins = projection ? compileProjectionJoins(projection) : legacyJoins(config, entity, columns, selectItems);
+	const conditions = compileFilterConditions(filterTable, entity.filter);
+	if (options.orgScope) conditions.push(`${quoteIdent(filterTable)}.${quoteIdent(options.orgScope.column)} = ${quoteLiteral(options.orgScope.value)}`);
 	const lines = [
 		options.securityInvoker ?? true ? `CREATE OR REPLACE VIEW ${quoteIdent(viewName)} WITH (security_invoker = true) AS` : `CREATE OR REPLACE VIEW ${quoteIdent(viewName)} AS`,
 		`SELECT ${selectItems.join(", ")}`,
-		`FROM ${quoteIdent(src)}`,
+		projection ? compileProjectionFrom(projection) : `FROM ${quoteIdent(src)}`,
 		...joins
 	];
 	if (conditions.length > 0) lines.push(`WHERE ${conditions.join(" AND ")}`);
@@ -206,3 +291,9 @@ Object.defineProperty(exports, "explainEntitiesConfig", {
 		return explainEntitiesConfig;
 	}
 });
+Object.defineProperty(exports, "explainViewExecutionError", {
+	enumerable: true,
+	get: function() {
+		return explainViewExecutionError;
+	}
+});