@clivly/core 0.9.7 → 0.10.0

package/README.md

@@ -195,19 +195,26 @@ collide).
 
 ### Building one interactively
 
-`ProjectionDraft` and its helpers exist so a builder UI stays presentational —
-every rule is a pure function of draft + schema:
+The builder engine lives on the **`@clivly/core/builder`** subpath, deliberately
+kept off the root barrel so the published `clivly` package does not pull it into
+the CLI's declaration emit.
+
+It exists so a builder UI stays *presentational*: the UI renders and collects,
+and every structural judgement — what can start a list, what is reachable from
+there, what a change costs — is a pure function of schema + picks answered here.
+A component that walks the graph or classifies cardinality itself is a bug.
 
 | Helper | Purpose |
 | --- | --- |
-| `emptyProjectionDraft(baseTable)` | A blank draft |
-| `addDraftJoin(draft, joinTable, schema)` | Add a join, keyed uniquely and pre-filled from foreign-key metadata |
-| `removeDraftJoin(draft, joinKey)` | Remove a join **and** every binding and identity that addressed it — left behind they fail validation as "unknown ref table", blaming the field for the join's removal |
-| `draftRefOptions(draft, schema)` | The tables and columns a field or identity may currently read from, in ref order |
-| `suggestJoinConditions(base, joinTable, schema, key)` | Pre-fill a join's `ON` from foreign-key metadata |
-| `draftToProjection(draft)` | `ProjectionMapping`, or `null` while incomplete |
-| `draftErrors(draft, schema)` | Validation errors, one per cause, each anchored to the section that owns it (`projection.entityKey`, `projection.joins`, …) |
-| `describeCardinality(draft, schema)` | Per-join `{ joinKey, fansOut }` for inline hints. Answered from the joins alone, so the warning arrives while the identity is still being chosen |
+| `listStartingRecordOptions(schema)` | What can be the "one row per…" of a list, each offerable or not with a machine-readable reason (no primary key, composite key, thin discovery metadata) |
+| `buildRelationshipGraph(schema)` / `edgesFrom(graph, table)` | A **bidirectional** graph: a table's own foreign keys (child → parent) *and* every other table's keys pointing at it (parent → child) |
+| `enumeratePaths(graph, startTable, options?)` | Ranked routes outward from a starting record, each flagged `isCollection` when it crosses a to-many edge. Budgeted by `MAX_HOPS` / `MAX_CANDIDATES` / `MAX_RESULTS`, and it reports *why* it truncated |
+| `compilePaths({schema, startTable, pickedFields, entityKey})` | Picked fields → a validated `ProjectionMapping`, allocating join keys and bindings. Throws `PathCompileError` for a shape it cannot express |
+| `classifyStartingRecordChange({schema, from, to, picks})` | Which picks survive changing the starting record, which are lost, and how many connections fall away. Survivors come back **repointed** to routes from the new starting record |
+
+Reachability is *directional*, which is why that last one cannot be approximated
+by intersecting path keys: a field reachable as a single value from one starting
+record can be a collection from another, and a collection is not pickable at all.
 
 `compileProjectionPreview(projection, limit)` compiles the same object to a
 capped, read-only `SELECT` — used by both sides of the dashboard's preview, so

package/dist/builder.cjs

@@ -0,0 +1,599 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_projection = require("./projection-DFgCoyZl.cjs");
+const require_schema_meta = require("./schema-meta-Cgi0MnHh.cjs");
+//#region src/path-compiler.ts
+/**
+* Compiles picked paths into a `ProjectionMapping` whose joins are in
+* dependency order.
+*
+* This is the last step of the derived-object builder: the user has browsed
+* outward from a starting list and picked fields, and this turns those picks
+* into the existing projection contract — unchanged, so validation, view
+* compilation, paging and sync all consume it as they already do.
+*
+* Four properties carry the weight:
+*
+* 1. **Joins dedupe by edge path, not by table.** Ten fields reached through
+*    the same chain of relationships produce one join. Two chains that land on
+*    the same table through *different* foreign keys stay two joins, because
+*    they are two genuinely different relationships. The ordered edge path is
+*    the join's identity.
+*
+* 2. **Dependency order.** Joins are emitted shortest-prefix-first, so a
+*    join's ON condition only ever references the base table or a join already
+*    declared above it. `validateProjection`'s forward-reference check is the
+*    external proof of this, and SQL requires it.
+*
+* 3. **No raw table name is ever an alias.** Every join key is derived from
+*    the full edge path — including which FK column each hop followed — and
+*    uniquified deterministically. A table-derived alias would silently
+*    collapse two different relationships into one.
+*
+* 4. **Collections never compile.** A path that crosses a to-many edge
+*    resolves to many rows, not a value. Emitting one as a join would fan the
+*    output out and quietly duplicate or collapse mirror rows at sync time.
+*    Asked to compile one, this throws rather than emitting something
+*    plausible.
+*
+* No table, column, or relationship is ever named in this file — the only
+* inputs are the schema, the starting table, and the user's picks.
+*/
+/** The reserved binding name; the view always projects identity as `id`. */
+const RESERVED_FIELD = "id";
+/**
+* Thrown when picks cannot compile to a valid projection.
+*
+* A distinct class so a builder UI can tell "this cannot be expressed" apart
+* from a genuine bug, and so callers can catch it narrowly. Failing loudly is
+* the point: the alternative — emitting a plausible-looking mapping — is the
+* defect class this whole body of work exists to close.
+*/
+var PathCompileError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "PathCompileError";
+	}
+};
+/**
+* Reduce an arbitrary identifier to the projection key charset.
+*
+* Table and column names come from the host's schema and are not constrained
+* to `PROJECTION_KEY_PATTERN` — they may carry capitals, spaces, or leading
+* digits. Sanitizing is lossy on purpose (two different names can reduce to
+* the same token), which is exactly why the caller disambiguates afterwards
+* rather than trusting this to be injective.
+*/
+function sanitize(part) {
+	return part.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+/**
+* A key candidate for the join reached by `edges`.
+*
+* Every hop contributes both the FK column it followed and the table it landed
+* on. Carrying the column is what keeps two FKs into the same table apart:
+* without it, both hops would reduce to the destination table's name and the
+* two relationships would collide into one alias.
+*/
+function keyCandidate(edges) {
+	const joined = edges.flatMap((edge) => [sanitize(edge.fromColumn), sanitize(edge.toTable)]).filter(Boolean).join("_");
+	return require_projection.PROJECTION_KEY_PATTERN.test(joined) ? joined : `j_${joined}`;
+}
+/** The ordered prefixes of a path, longest last. Each prefix is one join. */
+function prefixesOf(edges) {
+	return edges.map((_, index) => edges.slice(0, index + 1));
+}
+/**
+* Identity of a join: the full ordered edge path, including direction and both
+* column halves of every hop.
+*
+* This is the deduplication key and it is exact — unlike the *display* key,
+* nothing here is sanitized or lossy, so two distinct relationships can never
+* be conflated into one join.
+*/
+function prefixIdentity(edges) {
+	return edges.map((e) => `${e.direction}:${e.fromTable}.${e.fromColumn}->${e.toTable}.${e.toColumn}`).join("|");
+}
+/** Assigns each distinct edge path a unique, deterministic key. */
+var JoinKeyAllocator = class {
+	byIdentity = /* @__PURE__ */ new Map();
+	taken = /* @__PURE__ */ new Set([require_projection.BASE_REF]);
+	/**
+	* The key for this edge path, allocating one on first sight.
+	*
+	* Collisions are resolved by a counter rather than by anything derived from
+	* call order beyond first-sight order, which is itself deterministic
+	* because joins are visited in a fixed sorted order. The same picks
+	* therefore always produce the same keys.
+	*/
+	keyFor(edges) {
+		const identity = prefixIdentity(edges);
+		const existing = this.byIdentity.get(identity);
+		if (existing) return existing;
+		const candidate = keyCandidate(edges);
+		let key = candidate;
+		let suffix = 2;
+		while (this.taken.has(key)) {
+			key = `${candidate}_${suffix}`;
+			suffix += 1;
+		}
+		this.taken.add(key);
+		this.byIdentity.set(identity, key);
+		return key;
+	}
+};
+/** The ref an edge path resolves to: `base` for the root, else a join key. */
+function refTableFor(edges, allocator) {
+	return edges.length === 0 ? require_projection.BASE_REF : allocator.keyFor(edges);
+}
+function buildJoin(edges, allocator) {
+	const edge = edges.at(-1);
+	if (!edge) throw new PathCompileError("cannot build a join from an empty path");
+	const parentRef = refTableFor(edges.slice(0, -1), allocator);
+	const key = allocator.keyFor(edges);
+	const left = {
+		table: parentRef,
+		column: edge.fromColumn
+	};
+	const right = {
+		table: key,
+		column: edge.toColumn
+	};
+	return {
+		key,
+		table: edge.toTable,
+		type: "left",
+		on: [{
+			left,
+			op: "eq",
+			right
+		}]
+	};
+}
+function assertCompilable(field, startTable) {
+	const path = field.path;
+	if (!path || path.edges.length === 0) return;
+	if (path.isCollection) throw new PathCompileError(`field "${field.name}" is reached through a collection (a to-one relationship is required); a collection is many rows, not a value, so it must be started as its own list rather than compiled into a join`);
+	const first = path.edges[0];
+	if (first && first.fromTable !== startTable) throw new PathCompileError(`field "${field.name}" follows a path starting at "${first.fromTable}", not the starting table "${startTable}"`);
+}
+function validatePicks(options) {
+	const { pickedFields, startTable } = options;
+	if (pickedFields.length === 0) throw new PathCompileError("at least one field must be picked");
+	const seen = /* @__PURE__ */ new Set();
+	for (const field of pickedFields) {
+		if (field.name === RESERVED_FIELD) throw new PathCompileError(`"${RESERVED_FIELD}" is a reserved field name — the view always projects identity as "${RESERVED_FIELD}"`);
+		if (seen.has(field.name)) throw new PathCompileError(`duplicate field name "${field.name}"`);
+		seen.add(field.name);
+		assertCompilable(field, startTable);
+	}
+}
+/**
+* The starting table's single-column primary key.
+*
+* Fails closed on absent or composite keys rather than guessing a column: an
+* identity that is not provably unique per row is the failure mode that
+* silently duplicates or collapses mirror rows at sync time.
+*/
+function basePrimaryKey(schema, startTable) {
+	const table = schema.find((t) => t.name === startTable);
+	if (!table) throw new PathCompileError(`starting table "${startTable}" is not in the discovered schema`);
+	const pk = require_schema_meta.primaryKeyColumns(table);
+	const [column] = pk;
+	if (!column) throw new PathCompileError(`"${startTable}" has no discovered single-column primary key, which a derived object needs to identify its rows`);
+	if (pk.length > 1) throw new PathCompileError(`"${startTable}" has a composite primary key (${pk.join(", ")}), which cannot be used as a derived object's identity`);
+	return column;
+}
+/**
+* Every distinct edge-path prefix used by at least one picked field, ordered
+* shortest first.
+*
+* Ordering by depth is what puts joins in dependency order: a prefix of length
+* n can only reference the base table or its own length n-1 prefix, both of
+* which sort strictly earlier. Ties within a depth break on the exact path
+* identity, so the order is total and stable across runs.
+*/
+function requiredPrefixes(pickedFields) {
+	const byIdentity = /* @__PURE__ */ new Map();
+	for (const field of pickedFields) for (const prefix of prefixesOf(field.path?.edges ?? [])) {
+		const identity = prefixIdentity(prefix);
+		if (!byIdentity.has(identity)) byIdentity.set(identity, prefix);
+	}
+	return [...byIdentity.entries()].sort(([leftId, left], [rightId, right]) => {
+		const byDepth = left.length - right.length;
+		if (byDepth !== 0) return byDepth;
+		if (leftId === rightId) return 0;
+		return leftId < rightId ? -1 : 1;
+	}).map(([, prefix]) => prefix);
+}
+/**
+* Compile picked fields into a projection mapping.
+*
+* Throws `PathCompileError` when the picks cannot be expressed — a collection
+* path, a missing primary key, a reserved or duplicated field name. Every
+* mapping it returns satisfies `projectionSchema` and, given a schema whose
+* tables carry rich metadata, `validateProjection`.
+*/
+function compilePaths(options) {
+	const { entityKey, pickedFields, schema, startTable } = options;
+	validatePicks(options);
+	const identityColumn = basePrimaryKey(schema, startTable);
+	const allocator = new JoinKeyAllocator();
+	const joins = requiredPrefixes(pickedFields).map((prefix) => buildJoin(prefix, allocator));
+	const fieldBindings = {};
+	for (const field of pickedFields) {
+		const table = refTableFor(field.path?.edges ?? [], allocator);
+		fieldBindings[field.name] = { from: {
+			table,
+			column: field.column
+		} };
+	}
+	return {
+		version: 1,
+		kind: "projection",
+		entityKey,
+		baseTable: startTable,
+		joins,
+		fieldBindings,
+		identity: {
+			kind: "base_pk",
+			column: identityColumn
+		}
+	};
+}
+//#endregion
+//#region src/relationship-graph.ts
+const NO_RICH_META_REASON$1 = { code: "no-rich-meta" };
+/** Every edge whose `fromTable` is `table`, in either direction. */
+function edgesFrom(graph, table) {
+	return graph.edges.filter((edge) => edge.fromTable === table);
+}
+function childToParentCardinality(parentTable, parentColumn) {
+	return require_schema_meta.coversUniqueKey(parentTable, [parentColumn]) ? "to-one" : "to-many";
+}
+function parentToChildCardinality(childTable, childFkColumn) {
+	return require_schema_meta.coversUniqueKey(childTable, [childFkColumn]) ? "to-one" : "to-many";
+}
+/**
+* Build the bidirectional relationship graph for a discovered schema.
+*
+* No table, column, or relationship is ever named in this function — the
+* only input is the schema itself.
+*/
+function buildRelationshipGraph(schema) {
+	const tablesByName = new Map(schema.map((table) => [table.name, table]));
+	const nodes = schema.map((table) => require_schema_meta.hasRichMeta(table) ? {
+		table: table.name,
+		offerable: true
+	} : {
+		table: table.name,
+		offerable: false,
+		reason: NO_RICH_META_REASON$1
+	});
+	const edges = [];
+	for (const table of schema) {
+		if (!require_schema_meta.hasRichMeta(table)) continue;
+		for (const column of table.columnsMeta) {
+			const ref = column.references;
+			if (!ref) continue;
+			const parentTable = tablesByName.get(ref.table);
+			if (!(parentTable && require_schema_meta.hasRichMeta(parentTable))) continue;
+			edges.push({
+				fromTable: table.name,
+				fromColumn: column.name,
+				toTable: parentTable.name,
+				toColumn: ref.column,
+				direction: "child-to-parent",
+				cardinality: childToParentCardinality(parentTable, ref.column)
+			});
+			edges.push({
+				fromTable: parentTable.name,
+				fromColumn: ref.column,
+				toTable: table.name,
+				toColumn: column.name,
+				direction: "parent-to-child",
+				cardinality: parentToChildCardinality(table, column.name)
+			});
+		}
+	}
+	return {
+		nodes,
+		edges
+	};
+}
+//#endregion
+//#region src/path-enumeration.ts
+/**
+* Breadth-first enumeration of the paths reachable from a starting table.
+*
+* This is the "browse outward" engine behind the derived-object builder: the
+* user picks a starting list and we show them what else is reachable, without
+* ever naming a join, a base table, or an ON condition.
+*
+* Three properties matter enough to be spelled out:
+*
+* 1. **Cycles terminate.** A table already on a path is not revisited, so a
+*    self-referencing table yields its one-hop neighbours and stops. Parallel
+*    edges are still distinct: edge identity is the FK column pair, not the
+*    table pair, so two FKs into the same table stay two relationships.
+*
+* 2. **To-many is sticky.** Once a path crosses a to-many edge, everything at
+*    or beyond it is a *collection* — a list of rows, not a single value. Those
+*    paths are not pickable columns and must never be compiled into joins; the
+*    UI shows them with a "start a list of X" action instead.
+*
+* 3. **Truncation is reported, never silent.** Hitting a budget is part of the
+*    return value so the UI can say deeper paths are hidden and offer a
+*    narrower search, rather than quietly showing a partial answer as if it
+*    were the whole one.
+*
+* No table, column, or relationship is ever named here — the only inputs are
+* the graph and the starting table.
+*/
+/** Spec-mandated: how many edges deep a path may go. */
+const MAX_HOPS = 3;
+/** Spec-mandated: how many candidate paths may be considered before stopping. */
+const MAX_CANDIDATES = 200;
+/** Spec-mandated: how many ranked results may be displayed. */
+const MAX_RESULTS = 50;
+/**
+* `direction` is part of the key, not decoration. A column that is both a PK
+* and a self-FK (`t.id` referencing `t.id`) emits two genuinely different
+* edges — one child-to-parent, one parent-to-child — whose table/column
+* halves are identical. Without `direction` they collapse to one key, which
+* makes two distinct paths indistinguishable to the comparator and leaves
+* `Array.prototype.sort` free to order them either way.
+*/
+function edgeKey(edge) {
+	return `${edge.direction}:${edge.fromTable}.${edge.fromColumn}->${edge.toTable}.${edge.toColumn}`;
+}
+function pathKey(edges) {
+	return edges.map(edgeKey).join("|");
+}
+/**
+* Does the path's destination carry a column named exactly `field`?
+*
+* Only an exact match counts. A fuzzy match here would reorder results for
+* reasons a user cannot see, and the ordering is load-bearing downstream.
+*/
+function matchesField(path, field, columnsByTable) {
+	if (!field) return false;
+	const columns = columnsByTable?.get(path.toTable);
+	return columns ? columns.includes(field) : false;
+}
+/**
+* Total order over paths: hop count, then exact field match, then the stable
+* key. The key tiebreak is what makes the order total — without it, equal-rank
+* paths would keep their input order, which is stable per run but would drift
+* the moment edge construction changed.
+*
+* Returns 0 on equal keys rather than an arbitrary 1. A comparator that
+* answers 1 for both (a, b) and (b, a) is *inconsistent*, and
+* `Array.prototype.sort` is explicitly allowed to order such elements however
+* it likes — which would make Task 5's ordering invariant flake rather than
+* fail cleanly. Keys are unique in practice now that `edgeKey` carries
+* `direction`, so this is defence against the class, not a live collision.
+*/
+function comparePaths(left, right, field, columnsByTable) {
+	const byHops = left.edges.length - right.edges.length;
+	if (byHops !== 0) return byHops;
+	const leftMatch = matchesField(left, field, columnsByTable);
+	if (leftMatch !== matchesField(right, field, columnsByTable)) return leftMatch ? -1 : 1;
+	if (left.key === right.key) return 0;
+	return left.key < right.key ? -1 : 1;
+}
+/**
+* Should this edge be followed from `path`?
+*
+* A self-referencing FK is a real relationship a user browses to (a row's
+* parent row), so it is offered as a one-hop path even though it lands back
+* on the starting table. It is never extended: the destination is already on
+* the path, so the next level rejects it and the cycle terminates.
+*/
+function canFollow(entry, edge) {
+	const isSelfEdgeFromStart = entry.path.edges.length === 0 && edge.toTable === edge.fromTable;
+	return !entry.visited.has(edge.toTable) || isSelfEdgeFromStart;
+}
+function extend(entry, edge) {
+	const edges = [...entry.path.edges, edge];
+	return {
+		path: {
+			edges,
+			toTable: edge.toTable,
+			isCollection: entry.path.isCollection || edge.cardinality === "to-many",
+			key: pathKey(edges)
+		},
+		visited: /* @__PURE__ */ new Set([...entry.visited, edge.toTable])
+	};
+}
+/**
+* Expand one breadth-first level, appending to `candidates`.
+*
+* Returns the next frontier, or `undefined` when the candidate budget ran out
+* mid-level — the caller treats that as truncation and stops.
+*/
+function expandLevel(graph, frontier, candidates, maxCandidates) {
+	const next = [];
+	for (const entry of frontier) for (const edge of edgesFrom(graph, entry.path.toTable)) {
+		if (!canFollow(entry, edge)) continue;
+		if (candidates.length >= maxCandidates) return;
+		const extended = extend(entry, edge);
+		candidates.push(extended.path);
+		next.push(extended);
+	}
+	return next;
+}
+/**
+* Enumerate every path reachable from `startTable`, ranked and budgeted.
+*
+* Breadth-first, so the candidate budget always cuts the deepest frontier
+* rather than an arbitrary slice of a half-explored level.
+*
+* Note the order of operations: ranking happens *after* the candidate budget
+* has already stopped the walk. A path that would have ranked highly but sits
+* beyond the 200th candidate is therefore never seen, and no amount of
+* ranking recovers it. That is inherent to bounding the search rather than a
+* defect — and it is precisely why truncation is reported, so the UI can
+* offer a narrower search instead of implying the list is complete.
+*/
+function enumeratePaths(graph, startTable, options = {}) {
+	const maxHops = options.maxHops ?? 3;
+	const maxCandidates = options.maxCandidates ?? 200;
+	const maxResults = options.maxResults ?? 50;
+	const candidates = [];
+	let truncatedBy;
+	let frontier = [{
+		path: {
+			edges: [],
+			toTable: startTable,
+			isCollection: false,
+			key: ""
+		},
+		visited: /* @__PURE__ */ new Set([startTable])
+	}];
+	for (let hop = 0; hop < maxHops && frontier.length > 0; hop += 1) {
+		const next = expandLevel(graph, frontier, candidates, maxCandidates);
+		if (!next) {
+			truncatedBy = "candidate-budget";
+			break;
+		}
+		frontier = next;
+	}
+	const columnsByTable = options.columnsByTable;
+	const ranked = [...candidates].sort((left, right) => comparePaths(left, right, options.field, columnsByTable));
+	const paths = ranked.slice(0, maxResults);
+	if (!truncatedBy && ranked.length > maxResults) truncatedBy = "result-limit";
+	return {
+		paths,
+		truncated: Boolean(truncatedBy),
+		truncatedBy,
+		candidatesConsidered: candidates.length
+	};
+}
+//#endregion
+//#region src/starting-record-change.ts
+/** Does this table have a column of exactly this name? */
+function hasColumn(schema, table, column) {
+	const found = schema.find((entry) => entry.name === table);
+	return found ? found.columns.includes(column) : false;
+}
+/**
+* The route a pick would have from the new starting record, or `null` when it
+* has none.
+*
+* Returns `{ path: undefined }` — deliberately distinct from `null` — when the
+* field is a column of the new starting record itself. That is a survivor
+* reached by no route, which is exactly what `PickedField.path` being absent
+* means to `compilePaths`.
+*/
+function repoint(schema, paths, toTable, pick) {
+	if (hasColumn(schema, toTable, pick.column)) return { path: void 0 };
+	const destination = pick.path?.toTable ?? void 0;
+	const candidates = paths.filter((path) => !path.isCollection);
+	if (destination !== void 0) {
+		const match = candidates.find((path) => path.toTable === destination && hasColumn(schema, path.toTable, pick.column));
+		return match ? { path: match } : null;
+	}
+	const match = candidates.find((path) => hasColumn(schema, path.toTable, pick.column));
+	return match ? { path: match } : null;
+}
+/**
+* Identify the connection a pick travelled over, for counting.
+*
+* The path key, not the destination table: two FKs from one table into the
+* same table — a ticket's assignee and its reviewer — are two genuinely
+* different connections that both end at `users`. Counting by destination
+* would collapse them into one and under-report what the user loses.
+*
+* `null` means the pick was a column of the starting record, which is not a
+* connection.
+*/
+function connectionOf(pick) {
+	if (!pick.path || pick.path.edges.length === 0) return null;
+	return pick.path.key;
+}
+/**
+* Classify what changing the starting record does to a set of picked fields.
+*
+* Pure and total: an unknown `to` table simply has no reachable paths, so
+* every pick that is not one of its own columns is reported removed. It never
+* throws, because its caller is a confirmation dialog that must be able to
+* render an answer for any proposed change, including a nonsensical one.
+*/
+function classifyStartingRecordChange(options) {
+	const { from, picks, schema, to } = options;
+	if (from === to) return {
+		keptFields: [...picks],
+		removedConnectionCount: 0,
+		removedFields: []
+	};
+	const { paths } = enumeratePaths(buildRelationshipGraph(schema), to);
+	const keptFields = [];
+	const removedFields = [];
+	const removedConnections = /* @__PURE__ */ new Set();
+	for (const pick of picks) {
+		const repointed = repoint(schema, paths, to, pick);
+		if (repointed) {
+			keptFields.push({
+				column: pick.column,
+				name: pick.name,
+				...repointed.path ? { path: repointed.path } : {}
+			});
+			continue;
+		}
+		removedFields.push(pick);
+		const connection = connectionOf(pick);
+		if (connection !== null) removedConnections.add(connection);
+	}
+	return {
+		keptFields,
+		removedConnectionCount: removedConnections.size,
+		removedFields
+	};
+}
+//#endregion
+//#region src/starting-record-eligibility.ts
+const NO_RICH_META_REASON = { code: "no-rich-meta" };
+const COMPOSITE_PK_REASON = { code: "composite-pk" };
+const NO_PRIMARY_KEY_REASON = { code: "no-primary-key" };
+/**
+* List every table in the discovered schema with its starting-record
+* eligibility, in schema order.
+*
+* No table, column, or relationship is ever named in this function — the
+* only input is the schema itself.
+*/
+function listStartingRecordOptions(schema) {
+	return schema.map((table) => {
+		if (!require_schema_meta.hasRichMeta(table)) return {
+			table: table.name,
+			offerable: false,
+			reason: NO_RICH_META_REASON
+		};
+		const pk = require_schema_meta.primaryKeyColumns(table);
+		if (pk.length > 1) return {
+			table: table.name,
+			offerable: false,
+			reason: COMPOSITE_PK_REASON
+		};
+		if (pk.length === 0) return {
+			table: table.name,
+			offerable: false,
+			reason: NO_PRIMARY_KEY_REASON
+		};
+		return {
+			table: table.name,
+			offerable: true
+		};
+	});
+}
+//#endregion
+exports.MAX_CANDIDATES = MAX_CANDIDATES;
+exports.MAX_HOPS = MAX_HOPS;
+exports.MAX_RESULTS = MAX_RESULTS;
+exports.PathCompileError = PathCompileError;
+exports.buildRelationshipGraph = buildRelationshipGraph;
+exports.classifyStartingRecordChange = classifyStartingRecordChange;
+exports.compilePaths = compilePaths;
+exports.edgesFrom = edgesFrom;
+exports.enumeratePaths = enumeratePaths;
+exports.listStartingRecordOptions = listStartingRecordOptions;