clivly 0.9.4 → 0.9.6

package/index.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { t as CANONICAL_FIELDS } from "./entity-config-B74SPOUZ.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-CusbTOJ1.mjs";
 import "./mapping-score-C68uAqGB.mjs";
 import { matchesConcept, requiredFieldsFor, scoreFieldMap, scoreRelationships, suggestCursorField, toFieldMap } from "./internal-entity-heuristics.mjs";
-import { s as isPlaceholderUrl, t as createClivlySDK } from "./sdk-DYBDR939.mjs";
+import { s as isPlaceholderUrl, t as createClivlySDK } from "./sdk-Dkq6ELkf.mjs";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, watch, writeFileSync } from "node:fs";
@@ -973,7 +973,7 @@ function isKeySet(contents, key) {
 function appendEnvKeys(existing, entries) {
 	const missing = entries.filter((e) => !hasKey$1(existing, e.key));
 	if (missing.length === 0) return existing;
-	const block = missing.map((e) => `${e.comment ? `# ${e.comment}\n` : ""}${e.key}=`).join("\n");
+	const block = missing.map((e) => `${e.comment ? `# ${e.comment}\n` : ""}${e.key}=${e.value ?? ""}`).join("\n");
 	return `${existing}${existing.length > 0 && !existing.endsWith("\n") ? "\n" : ""}${existing.length > 0 ? "\n" : ""}# Clivly\n${block}\n`;
 }
 /**
@@ -1595,7 +1595,7 @@ function planInit(schema, overrides = {}) {
 			todos.push(...candidateTodos);
 			company = candidate;
 			if (matchesConcept(companyTable.tableName, "contact")) todos.push(`"${companyTable.tableName}" matches both contact and company naming — assigned to company. Swap it to your contact entity if that's wrong.`);
-		} else todos.push(`"${companyTable.tableName}" looked like a company but no fields could be mapped — left it out. Add it to \`entities\` once you know which columns map to name/domain.`);
+		} else todos.push(`"${companyTable.tableName}" looked like a company but no fields could be mapped — left it out. Add it to \`entities\` once you know which columns map to name/domain, or build a derived object from it in Clivly (Integrations → Map as custom object) if the fields live in a joined table.`);
 	}
 	if (contactTable && contact) {
 		const scored = scoreRelationships(toScoredTable(contactTable), schema.tables.map(toScoredTable));
@@ -1809,7 +1809,8 @@ const CLIVLY_ENV_KEYS = [
 	},
 	{
 		key: "CLIVLY_SYNC_TRIGGER_URL",
-		comment: "Public URL of your mounted tick route (e.g. https://app.example.com/api/clivly/tick)"
+		value: TRIGGER_URL_PLACEHOLDER,
+		comment: "Public URL of your tick route — replace <yourDomain.com> once deployed. Local dev: run `clivly dev` instead."
 	},
 	{
 		key: "CLIVLY_SYNC_TRIGGER_SECRET",
@@ -2740,6 +2741,103 @@ function ladderExitCode(results) {
 	return results.every((result) => result.state !== "fail" && result.state !== "pending") ? 0 : 1;
 }
 //#endregion
+//#region src/boot-hook-check.ts
+const REMIX_ENTRY_CANDIDATES = [
+	"app/entry.server.tsx",
+	"app/entry.server.ts",
+	"app/entry.server.jsx",
+	"app/entry.server.js"
+];
+const NEXT_CONFIG_CANDIDATES = [
+	"next.config.ts",
+	"next.config.mjs",
+	"next.config.js",
+	"next.config.cjs",
+	"next.config.mts"
+];
+const CLIVLY_MENTION = /clivly/i;
+const INSTRUMENTATION_HOOK_ENABLED = /instrumentationHook\s*:\s*true/;
+/**
+* Where this framework's boot hook lives, most likely location first.
+*
+* The file-owning frameworks are asked of `boot-hook.ts` rather than restated,
+* so a path change there cannot leave this check hunting for a file `init` no
+* longer writes. The other two are patched into a file the app already owns.
+*/
+function bootSiteCandidates(framework) {
+	const owned = [bootHookPath(framework, "app"), bootHookPath(framework, "src/app")].filter((path) => path !== null);
+	if (owned.length > 0) return [...new Set(owned)];
+	if (framework === "tanstack-start") return [...VITE_CONFIG_CANDIDATES];
+	if (framework === "remix") return REMIX_ENTRY_CANDIDATES;
+	return [];
+}
+function declaredDeps(readFile) {
+	const raw = readFile("package.json");
+	if (raw === null) return null;
+	try {
+		const pkg = JSON.parse(raw);
+		return {
+			...pkg.dependencies,
+			...pkg.devDependencies
+		};
+	} catch {
+		return null;
+	}
+}
+function findBootSite(readFile, framework) {
+	for (const candidate of bootSiteCandidates(framework)) {
+		const source = readFile(candidate);
+		if (source !== null && CLIVLY_MENTION.test(source)) return candidate;
+	}
+	return null;
+}
+/**
+* On Next.js below 15 the hook file is ignored unless the flag is on, so a
+* present-and-correct instrumentation.ts is not evidence of anything. A missing
+* next.config is the same failure as one without the flag: either way nothing
+* switches the hook on.
+*/
+function nextFlagVerdict(readFile, version, site) {
+	if (!nextNeedsInstrumentationFlag(version)) return null;
+	for (const candidate of NEXT_CONFIG_CANDIDATES) {
+		const source = readFile(candidate);
+		if (source !== null && INSTRUMENTATION_HOOK_ENABLED.test(source)) return null;
+	}
+	return {
+		state: "broken",
+		detail: `${site} exists, but Next.js ${version} ignores it — experimental.instrumentationHook is not enabled in next.config.`,
+		hint: NEXT_INSTRUMENTATION_FLAG_STEP
+	};
+}
+function checkBootHook(readFile) {
+	const deps = declaredDeps(readFile);
+	if (deps === null) return {
+		state: "unknown",
+		detail: "package.json not readable — cannot tell how this app boots."
+	};
+	const framework = detectFramework(deps);
+	if (framework === "unknown") return {
+		state: "unknown",
+		detail: "No supported framework detected, so there is no known place to check."
+	};
+	const label = FRAMEWORK_LABELS[framework];
+	const site = findBootSite(readFile, framework);
+	if (site === null) return {
+		state: "broken",
+		detail: `No Clivly boot hook found in this ${label} app.`,
+		hint: `Nothing starts the SDK, so your app never tells Clivly it is running — the dashboard stays silent with no error anywhere. Run \`clivly init\` to scaffold it, or call \`clivly.start()\` where your server boots (${bootSiteCandidates(framework)[0]}).`
+	};
+	const nextVersion = deps.next;
+	if (framework === "nextjs" && nextVersion) {
+		const broken = nextFlagVerdict(readFile, nextVersion, site);
+		if (broken) return broken;
+	}
+	return {
+		state: "ok",
+		detail: site
+	};
+}
+//#endregion
 //#region src/edge-safety.ts
 const NODE_BUILTINS = /* @__PURE__ */ new Set([
 	"assert",
@@ -2926,7 +3024,7 @@ function pingOnce(ctx) {
 }
 const REASON_HINT = {
 	ok: "",
-	invalid_api_key: "The key was rejected (401). Check CLIVLY_SECRET_KEY (or legacy CLIVLY_API_KEY).",
+	invalid_api_key: "The key was rejected (401). Run `clivly login` to re-pair and rewrite the credentials, and check CLIVLY_SECRET_KEY (or legacy CLIVLY_API_KEY) belongs to the org whose dashboard you are watching.",
 	forbidden: "The key is valid but lacks access to this org (403).",
 	rate_limited: "Rate limited (429). Wait a moment and retry.",
 	server_error: "Clivly returned a server error (5xx). Retry shortly.",
@@ -3025,15 +3123,16 @@ const triggerUrlStage = {
 	label: "Sync trigger URL",
 	needs: [configStage.id],
 	run(ctx) {
-		const url = ctx.sdk?.syncTrigger?.url;
-		if (url && !isPlaceholderUrl(url)) return Promise.resolve({
+		const trigger = ctx.sdk?.describeSyncTrigger?.();
+		if (trigger?.resolved) return Promise.resolve({
 			state: "pass",
-			detail: url
+			detail: trigger.resolved
 		});
-		const isPlaceholder = url !== void 0;
+		const configured = trigger?.configured;
+		const isPlaceholder = configured !== void 0 && isPlaceholderUrl(configured);
 		return Promise.resolve({
 			state: "warn",
-			detail: isPlaceholder ? `Still the placeholder (${url}) — remote sync cannot call back into this app.` : "Not set — remote sync cannot call back into this app.",
+			detail: isPlaceholder ? `Still the scaffolded placeholder (${configured}) — remote sync cannot call back into this app.` : "Not set — remote sync cannot call back into this app.",
 			hint: "Replace <yourDomain.com> with your deployed origin, or delete the line — on Vercel, Cloudflare Pages, Railway, Render and Fly the SDK derives the URL from the platform. For local development run `clivly dev`: it opens a tunnel and registers the URL for you, outranking whatever is in .env. Push-only setups can ignore this."
 		});
 	}
@@ -3082,6 +3181,24 @@ const STATUS_STAGES = [
 			});
 		}
 	},
+	{
+		id: "boot-hook",
+		label: "Boot hook wired",
+		run(ctx) {
+			const read = ctx.readConfigSource ?? defaultReadConfigSource;
+			const root = dirname(ctx.configPath);
+			const verdict = checkBootHook((relative) => read(resolve(root, relative)));
+			if (verdict.state === "ok") return Promise.resolve({
+				state: "pass",
+				detail: `starts Clivly from ${verdict.detail}`
+			});
+			return Promise.resolve({
+				state: verdict.state === "unknown" ? "skip" : "fail",
+				detail: verdict.detail,
+				hint: verdict.hint
+			});
+		}
+	},
 	sdkChecksStage,
 	triggerUrlStage
 ];
@@ -3135,6 +3252,7 @@ const ALIAS_STAGE_IDS = {
 	doctor: [
 		"config",
 		"runtime",
+		"boot-hook",
 		"setup-checks"
 	],
 	connect: [

package/internal-BQ47iN6f.cjs

@@ -0,0 +1,259 @@
+const require_projection = require("./projection-DEwL-D8R.cjs");
+const require_entity_config = require("./entity-config-DE30_RpU.cjs");
+//#region ../core/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: require_projection.BASE_REF,
+			column: column.references.column
+		}
+	});
+	return conditions;
+}
+/**
+* Add a join on `joinTable`, keyed and pre-filled.
+*
+* The key is the table's own name where that is free, because it is what the
+* user already calls the table; a collision falls back to `_2`, `_3` and so on.
+* Uniqueness is not cosmetic — the key is the SQL alias and the name every ref
+* addresses the table by, so two joins sharing one would make every ref
+* ambiguous. `base` is reserved for the base table and can never be taken.
+*/
+function addDraftJoin(draft, joinTable, schema) {
+	const taken = /* @__PURE__ */ new Set([require_projection.BASE_REF, ...draft.joins.map((j) => j.key)]);
+	let key = joinTable;
+	let suffix = 2;
+	while (taken.has(key)) {
+		key = `${joinTable}_${suffix}`;
+		suffix += 1;
+	}
+	return {
+		...draft,
+		joins: [...draft.joins, {
+			key,
+			table: joinTable,
+			type: "left",
+			on: suggestJoinConditions(draft.baseTable, joinTable, schema, key)
+		}]
+	};
+}
+/**
+* Remove a join, and everything that addressed it.
+*
+* Refs to a removed join are refs to a table the projection no longer declares.
+* Left in place they fail validation as "unknown ref table", which blames the
+* field — or, worse, the identity — for the join's removal. Identity falls back
+* to the base primary key, the same default a new draft starts from.
+*/
+function removeDraftJoin(draft, joinKey) {
+	const fieldBindings = Object.fromEntries(Object.entries(draft.fieldBindings).filter(([, binding]) => binding.from.table !== joinKey));
+	const identityDependsOnJoin = require_projection.identityRefs(draft.identity, "").some((ref) => ref.table === joinKey);
+	return {
+		...draft,
+		joins: draft.joins.filter((join) => join.key !== joinKey),
+		fieldBindings,
+		identity: identityDependsOnJoin ? { kind: "base_pk" } : draft.identity
+	};
+}
+/**
+* Every table a field or identity may currently read from, in ref order: the
+* base table first, then each join.
+*
+* Returns [] when the base table is not in the discovered schema — there is
+* nothing truthful to offer, and inventing columns would let someone build a
+* projection that cannot compile.
+*/
+function draftRefOptions(draft, schema) {
+	const byName = new Map(schema.map((table) => [table.name, table]));
+	const base = byName.get(draft.baseTable);
+	if (!base) return [];
+	const options = [{
+		ref: require_projection.BASE_REF,
+		label: `${base.name} (${require_projection.BASE_REF})`,
+		columns: base.columns
+	}];
+	for (const join of draft.joins) {
+		const table = byName.get(join.table);
+		if (table) options.push({
+			ref: join.key,
+			label: `${table.name} (${join.key})`,
+			columns: table.columns
+		});
+	}
+	return options;
+}
+/** A draft becomes a projection once it has a valid key and ≥1 binding. */
+function draftToProjection(draft) {
+	if (!require_projection.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
+	};
+}
+const PROBE_KEY = "draft";
+/**
+* A draft rendered as a projection so the semantic checks can run against it
+* while it is being written, not only once it is finished.
+*
+* `entityKey` is stood in for rather than taken from the draft: it is the one
+* field `validateProjection` never looks at, and a half-typed key would
+* otherwise have to be valid before any join or identity could be checked. The
+* missing or malformed key is reported separately, by `draftErrors`.
+*/
+function probeProjection(draft) {
+	return {
+		version: 1,
+		kind: "projection",
+		entityKey: PROBE_KEY,
+		baseTable: draft.baseTable,
+		joins: draft.joins,
+		fieldBindings: draft.fieldBindings,
+		identity: draft.identity
+	};
+}
+/**
+* `validateProjection` appends its own `projection.` segment to the base path it
+* is given, because in a config the base is the entity that owns the projection
+* (`entities.accounts` → `entities.accounts.projection.identity`). A draft has
+* no owning entity, so passing "projection" as the base produced
+* `projection.projection.identity` — a path no caller could match against, and
+* the reason `draftErrors` was only ever consumed as a flat list of messages.
+*
+* Passing an empty base and dropping the leading separator leaves one
+* convention: every path here starts `projection.` exactly once, whether it came
+* from this module or from the validator.
+*/
+function semanticErrors(draft, schema) {
+	return require_entity_config.validateProjection(probeProjection(draft), schema, "").map((error) => ({
+		...error,
+		path: error.path.startsWith(".") ? error.path.slice(1) : error.path
+	}));
+}
+/**
+* Every reason this draft cannot be saved, one per cause and each anchored to
+* the section that owns it.
+*
+* One lumped "Name the object and map a field." was all this used to return for
+* an incomplete draft, at the bare path "projection". Two consequences, both
+* bad: a builder had nowhere to attach the message, and — because it returned
+* before validating — a fanning join under a `base_pk` identity stayed silent
+* until the draft was otherwise complete, which is well after the point where
+* the user chose the join.
+*/
+function draftErrors(draft, schema) {
+	const errors = [];
+	if (draft.entityKey === "") errors.push({
+		path: "projection.entityKey",
+		message: "Key is required."
+	});
+	else if (!require_projection.PROJECTION_KEY_PATTERN.test(draft.entityKey)) errors.push({
+		path: "projection.entityKey",
+		message: `Key ${require_projection.PROJECTION_KEY_MESSAGE}.`
+	});
+	if (Object.keys(draft.fieldBindings).length === 0) errors.push({
+		path: "projection.fieldBindings",
+		message: "Map at least one field."
+	});
+	if (draft.baseTable === "") {
+		errors.push({
+			path: "projection.baseTable",
+			message: "Pick a base table."
+		});
+		return errors;
+	}
+	errors.push(...semanticErrors(draft, schema));
+	return errors;
+}
+/**
+* Per-join fan-out, for the builder's inline cardinality hints.
+*
+* Answered from the joins alone. Joins are chosen before the key and the fields
+* are filled in, and a fan-out warning is precisely what should steer the
+* identity choice while it is being made — requiring a complete draft put the
+* hint after the decision it exists to inform.
+*/
+function describeCardinality(draft, schema) {
+	const projection = probeProjection(draft);
+	const tablesByName = new Map(schema.map((t) => [t.name, t]));
+	const fanning = new Set(require_entity_config.fanOutJoins(projection, tablesByName).map((j) => j.key));
+	return projection.joins.map((join) => ({
+		joinKey: join.key,
+		fansOut: fanning.has(join.key)
+	}));
+}
+//#endregion
+Object.defineProperty(exports, "addDraftJoin", {
+	enumerable: true,
+	get: function() {
+		return addDraftJoin;
+	}
+});
+Object.defineProperty(exports, "describeCardinality", {
+	enumerable: true,
+	get: function() {
+		return describeCardinality;
+	}
+});
+Object.defineProperty(exports, "draftErrors", {
+	enumerable: true,
+	get: function() {
+		return draftErrors;
+	}
+});
+Object.defineProperty(exports, "draftRefOptions", {
+	enumerable: true,
+	get: function() {
+		return draftRefOptions;
+	}
+});
+Object.defineProperty(exports, "draftToProjection", {
+	enumerable: true,
+	get: function() {
+		return draftToProjection;
+	}
+});
+Object.defineProperty(exports, "emptyProjectionDraft", {
+	enumerable: true,
+	get: function() {
+		return emptyProjectionDraft;
+	}
+});
+Object.defineProperty(exports, "removeDraftJoin", {
+	enumerable: true,
+	get: function() {
+		return removeDraftJoin;
+	}
+});
+Object.defineProperty(exports, "suggestJoinConditions", {
+	enumerable: true,
+	get: function() {
+		return suggestJoinConditions;
+	}
+});

package/internal-ChufvXE6.mjs

@@ -0,0 +1,212 @@
+import { i as identityRefs, n as PROJECTION_KEY_MESSAGE, r as PROJECTION_KEY_PATTERN, t as BASE_REF } from "./projection-hnPSgH6G.mjs";
+import { h as fanOutJoins, m as validateProjection } from "./entity-config-CusbTOJ1.mjs";
+//#region ../core/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;
+}
+/**
+* Add a join on `joinTable`, keyed and pre-filled.
+*
+* The key is the table's own name where that is free, because it is what the
+* user already calls the table; a collision falls back to `_2`, `_3` and so on.
+* Uniqueness is not cosmetic — the key is the SQL alias and the name every ref
+* addresses the table by, so two joins sharing one would make every ref
+* ambiguous. `base` is reserved for the base table and can never be taken.
+*/
+function addDraftJoin(draft, joinTable, schema) {
+	const taken = /* @__PURE__ */ new Set([BASE_REF, ...draft.joins.map((j) => j.key)]);
+	let key = joinTable;
+	let suffix = 2;
+	while (taken.has(key)) {
+		key = `${joinTable}_${suffix}`;
+		suffix += 1;
+	}
+	return {
+		...draft,
+		joins: [...draft.joins, {
+			key,
+			table: joinTable,
+			type: "left",
+			on: suggestJoinConditions(draft.baseTable, joinTable, schema, key)
+		}]
+	};
+}
+/**
+* Remove a join, and everything that addressed it.
+*
+* Refs to a removed join are refs to a table the projection no longer declares.
+* Left in place they fail validation as "unknown ref table", which blames the
+* field — or, worse, the identity — for the join's removal. Identity falls back
+* to the base primary key, the same default a new draft starts from.
+*/
+function removeDraftJoin(draft, joinKey) {
+	const fieldBindings = Object.fromEntries(Object.entries(draft.fieldBindings).filter(([, binding]) => binding.from.table !== joinKey));
+	const identityDependsOnJoin = identityRefs(draft.identity, "").some((ref) => ref.table === joinKey);
+	return {
+		...draft,
+		joins: draft.joins.filter((join) => join.key !== joinKey),
+		fieldBindings,
+		identity: identityDependsOnJoin ? { kind: "base_pk" } : draft.identity
+	};
+}
+/**
+* Every table a field or identity may currently read from, in ref order: the
+* base table first, then each join.
+*
+* Returns [] when the base table is not in the discovered schema — there is
+* nothing truthful to offer, and inventing columns would let someone build a
+* projection that cannot compile.
+*/
+function draftRefOptions(draft, schema) {
+	const byName = new Map(schema.map((table) => [table.name, table]));
+	const base = byName.get(draft.baseTable);
+	if (!base) return [];
+	const options = [{
+		ref: BASE_REF,
+		label: `${base.name} (${BASE_REF})`,
+		columns: base.columns
+	}];
+	for (const join of draft.joins) {
+		const table = byName.get(join.table);
+		if (table) options.push({
+			ref: join.key,
+			label: `${table.name} (${join.key})`,
+			columns: table.columns
+		});
+	}
+	return options;
+}
+/** 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
+	};
+}
+const PROBE_KEY = "draft";
+/**
+* A draft rendered as a projection so the semantic checks can run against it
+* while it is being written, not only once it is finished.
+*
+* `entityKey` is stood in for rather than taken from the draft: it is the one
+* field `validateProjection` never looks at, and a half-typed key would
+* otherwise have to be valid before any join or identity could be checked. The
+* missing or malformed key is reported separately, by `draftErrors`.
+*/
+function probeProjection(draft) {
+	return {
+		version: 1,
+		kind: "projection",
+		entityKey: PROBE_KEY,
+		baseTable: draft.baseTable,
+		joins: draft.joins,
+		fieldBindings: draft.fieldBindings,
+		identity: draft.identity
+	};
+}
+/**
+* `validateProjection` appends its own `projection.` segment to the base path it
+* is given, because in a config the base is the entity that owns the projection
+* (`entities.accounts` → `entities.accounts.projection.identity`). A draft has
+* no owning entity, so passing "projection" as the base produced
+* `projection.projection.identity` — a path no caller could match against, and
+* the reason `draftErrors` was only ever consumed as a flat list of messages.
+*
+* Passing an empty base and dropping the leading separator leaves one
+* convention: every path here starts `projection.` exactly once, whether it came
+* from this module or from the validator.
+*/
+function semanticErrors(draft, schema) {
+	return validateProjection(probeProjection(draft), schema, "").map((error) => ({
+		...error,
+		path: error.path.startsWith(".") ? error.path.slice(1) : error.path
+	}));
+}
+/**
+* Every reason this draft cannot be saved, one per cause and each anchored to
+* the section that owns it.
+*
+* One lumped "Name the object and map a field." was all this used to return for
+* an incomplete draft, at the bare path "projection". Two consequences, both
+* bad: a builder had nowhere to attach the message, and — because it returned
+* before validating — a fanning join under a `base_pk` identity stayed silent
+* until the draft was otherwise complete, which is well after the point where
+* the user chose the join.
+*/
+function draftErrors(draft, schema) {
+	const errors = [];
+	if (draft.entityKey === "") errors.push({
+		path: "projection.entityKey",
+		message: "Key is required."
+	});
+	else if (!PROJECTION_KEY_PATTERN.test(draft.entityKey)) errors.push({
+		path: "projection.entityKey",
+		message: `Key ${PROJECTION_KEY_MESSAGE}.`
+	});
+	if (Object.keys(draft.fieldBindings).length === 0) errors.push({
+		path: "projection.fieldBindings",
+		message: "Map at least one field."
+	});
+	if (draft.baseTable === "") {
+		errors.push({
+			path: "projection.baseTable",
+			message: "Pick a base table."
+		});
+		return errors;
+	}
+	errors.push(...semanticErrors(draft, schema));
+	return errors;
+}
+/**
+* Per-join fan-out, for the builder's inline cardinality hints.
+*
+* Answered from the joins alone. Joins are chosen before the key and the fields
+* are filled in, and a fan-out warning is precisely what should steer the
+* identity choice while it is being made — requiring a complete draft put the
+* hint after the decision it exists to inform.
+*/
+function describeCardinality(draft, schema) {
+	const projection = probeProjection(draft);
+	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 { draftToProjection as a, suggestJoinConditions as c, draftRefOptions as i, describeCardinality as n, emptyProjectionDraft as o, draftErrors as r, removeDraftJoin as s, addDraftJoin as t };