@aburi/diff 0.2.0 → 0.3.0

package/dist/index.mjs

@@ -2,10 +2,15 @@ import { RESERVED_LANGUAGE_IDS, computeWeaklyConnectedComponents, reconstructCal
 
 //#region src/components.ts
 /**
-* §6.1 — Component diff. Component identity is `id`; when a Component is present in both
+* `docs/design/diff-algorithm.md` §6.1 — Component diff. Assumes `components[].id` is unique on each side (ir-schema.md §14
+* #2) and does not check it: `buildDiff` establishes that before calling, and a caller
+* reaching this export directly owns the obligation, because the lookup map here is
+* last-write-wins and a repeat is lost rather than reported.
+*
+* Component identity is `id`; when a Component is present in both
 * base and head with the same id, the three delta booleans describe which axes actually
 * moved (roots reshuffle, public API globs, or framework hint list). `modified` deltas
-* are intentionally absent from this diff (§5.2.3): fields are reported as before/after
+* are intentionally absent from this diff (diff-algorithm.md §5.2.3): fields are reported as before/after
 * pairs via the `changed[]` entries so consumers can render them without stringifying
 * arrays.
 */
@@ -47,21 +52,61 @@ function diffComponents(base, head) {
 	};
 }
 /**
-* §6.2 — Dependency diff. Identity is the composite `(from, to, via)` triple; direction
-* and effect changes are surfaced as an added + removed pair so `modified` is not part of
-* the schema (§6.2 tail).
+* Build a side view from a document. The only construction site there is.
+*
+* `buildDiff` reads `lostFiles` for its own Symbol classification too, from this same object,
+* so "a Symbol reported unknown and the edges it took with it cannot disagree about which file
+* went missing" is a property of the wiring rather than a claim in a comment.
+*
+* Exported because `DependencySideView` is public and `diffDependencies` requires one: without
+* a factory a caller would have to reproduce the `symbols[].source.file` keying and the
+* `stats.skippedFiles` read, and the likeliest outcome of that is a caller who gets it wrong.
+*/
+function dependencySideView(ir) {
+	const symbolFiles = /* @__PURE__ */ new Map();
+	for (const symbol of ir.symbols) symbolFiles.set(symbol.id, symbol.source.file);
+	const lostFiles = /* @__PURE__ */ new Map();
+	for (const file of ir.stats.skippedFiles ?? []) lostFiles.set(file.path, file.reason);
+	return {
+		symbolFiles,
+		lostFiles
+	};
+}
+/**
+* `docs/design/diff-algorithm.md` §6.2 — Dependency diff. Identity is the composite
+* `(from, to, via)` triple; direction and effect changes are surfaced as an added + removed
+* pair so `modified` is not part of the schema (§6.2 tail). Uniqueness of that triple is the caller's obligation on the same
+* terms as `diffComponents` above — a repeat here is indistinguishable in the output from
+* the flip it encodes.
+*
+* `sides` is what separates a deletion from a loss (`docs/design/diff-algorithm.md` §6.2.1).
+* It is required rather than optional: omitting it would classify every edge into a lost file
+* as a deletion again — silently, and while still writing `unknown: []`, which this schema
+* defines as "nothing was unknown" rather than "nobody looked". A caller with no skip list to
+* offer says so by passing a side view whose `lostFiles` is empty, which is the honest spelling
+* of an IR written before `stats.skippedFiles` existed.
+*
+* The return type declares `unknown` present, where the schema leaves it optional for documents
+* that predate the field. A reader may find it missing; this function always writes it.
 */
-function diffDependencies(base, head) {
+function diffDependencies(base, head, sides) {
 	const baseKeys = /* @__PURE__ */ new Map();
 	for (const d of base) baseKeys.set(dependencyKey(d), d);
 	const headKeys = /* @__PURE__ */ new Map();
 	for (const d of head) headKeys.set(dependencyKey(d), d);
 	const added = [];
 	const removed = [];
+	const unknown = [];
 	for (const [key, dep] of headKeys) {
 		const b = baseKeys.get(key);
 		if (b === void 0) {
-			added.push(dep);
+			const lostFiles = endpointsLostBy(dep, sides.head, sides.base);
+			if (lostFiles.length > 0) unknown.push({
+				dependency: dep,
+				absentFrom: "base",
+				lostFiles
+			});
+			else added.push(dep);
 			continue;
 		}
 		if (b.direction !== dep.direction || (b.effect ?? null) !== (dep.effect ?? null)) {
@@ -69,16 +114,71 @@ function diffDependencies(base, head) {
 			added.push(dep);
 		}
 	}
-	for (const [key, dep] of baseKeys) if (!headKeys.has(key)) removed.push(dep);
+	for (const [key, dep] of baseKeys) {
+		if (headKeys.has(key)) continue;
+		const lostFiles = endpointsLostBy(dep, sides.base, sides.head);
+		if (lostFiles.length > 0) unknown.push({
+			dependency: dep,
+			absentFrom: "head",
+			lostFiles
+		});
+		else removed.push(dep);
+	}
 	added.sort(compareDependencies);
 	removed.sort(compareDependencies);
+	unknown.sort((a, b) => compareDependencies(a.dependency, b.dependency));
 	return {
 		added,
-		removed
+		removed,
+		unknown
 	};
 }
+/**
+* The endpoint files `absent` never analysed, read through `holder` because that is the
+* document the edge — and therefore the Symbol behind each endpoint — actually comes from.
+*
+* Both endpoints are checked: an edge dies when *either* end's file goes, including one whose
+* other end survived, and that half is the easiest to miss because the surviving Symbol is
+* right there in both documents.
+*
+* Deduped and sorted by path, so an intra-file edge collapses to the one file it lost.
+*/
+function endpointsLostBy(dep, holder, absent) {
+	const byPath = /* @__PURE__ */ new Map();
+	for (const endpoint of [dep.from, dep.to]) {
+		const file = holder.symbolFiles.get(endpoint);
+		if (file === void 0) continue;
+		const reason = absent.lostFiles.get(file);
+		if (reason === void 0) continue;
+		byPath.set(file, reason);
+	}
+	return [...byPath.entries()].map(([path, reason]) => ({
+		path,
+		reason
+	})).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+}
+/**
+* `docs/design/diff-algorithm.md` §6.2 — the fields Dependency identity is made of, in key order, and the join that turns
+* them into one. Both halves are exported so the entry-point uniqueness check keys on
+* exactly what this file keys on — a check with its own notion of identity would let through
+* the duplicates that actually collide here, and a check that shared only the join would
+* still be free to disagree about which fields identity is made of.
+*
+* Core's invariant #13 joins the same triple with a different separator. The two agree for
+* every endpoint that satisfies the id grammars of ir-schema.md §3.1 and §4, which is every
+* Document the integrity checker accepts; they could in principle disagree for one that does
+* not, and `buildDiff` runs no grammar check on the IRs it is handed.
+*/
+const DEPENDENCY_IDENTITY_FIELDS = [
+	"from",
+	"to",
+	"via"
+];
+function dependencyIdentity(parts) {
+	return parts.join("::");
+}
 function dependencyKey(d) {
-	return `${d.from}::${d.to}::${d.via}`;
+	return dependencyIdentity(DEPENDENCY_IDENTITY_FIELDS.map((field) => d[field]));
 }
 function compareDependencies(a, b) {
 	const keyA = dependencyKey(a);
@@ -151,48 +251,112 @@ function validateLineFuzz(value) {
 	return value;
 }
 /**
-* Two-index diff: build key-indexed maps for both sides, then classify each key into
-* `added` / `removed` / `modified`. Line-fuzzed identities are matched within tolerance
-* so cosmetic line shifts do not produce added/removed noise. `modified` only fires when
-* the identity key stays the same but the content differs.
+* §5.2 — pair the two sides by identity key within ±`lineFuzz`, then classify each element
+* into `added` / `removed` / `modified`. `modified` fires only when a pairing holds and the
+* content differs, so a cosmetic line shift produces nothing.
+*
+* Several elements of one Symbol routinely share a key — two `guard` rules, two calls to one
+* target, two `@Get` — so which base element a head element takes is a real choice. Two
+* passes make it: first the elements whose key **and content** agree, then whatever is left.
+* An untouched element is therefore claimed by its own counterpart before an edited or
+* deleted neighbour can take it, and the remainder pairs by proximity — where a genuine edit
+* lands. Taking the first key hit instead reported a deleted `guard@1` by removing its
+* untouched `guard@3` neighbour *and* listing that same neighbour as modified.
+*
+* Each pass is an order-preserving assignment rather than a per-element search, because a
+* greedy pass takes a pairing that leaves a better set unreachable. Two identical guards
+* shifted down two lines are the smallest case: the first head element is nearest to the
+* *second* base element, and claiming it strands the other head outside the window, so a
+* block that moved intact comes back as an `added` and a `removed`.
 */
 function differentiate(base, head, isEqual, lineFuzz) {
-	const added = [];
-	const removed = [];
-	const modified = [];
-	const consumedBase = /* @__PURE__ */ new Set();
-	for (const h of head) {
-		let matchIdx = -1;
-		for (let j = 0; j < base.length; j++) {
-			if (consumedBase.has(j)) continue;
-			const b = base[j];
-			if (b === void 0) continue;
-			if (b.key !== h.key) continue;
-			if (Math.abs(b.line - h.line) > lineFuzz) continue;
-			matchIdx = j;
-			break;
-		}
-		if (matchIdx === -1) {
-			added.push(h.item);
-			continue;
+	const freeBase = new Set(base.map((_, index) => index));
+	const freeHead = new Set(head.map((_, index) => index));
+	const partnerOf = /* @__PURE__ */ new Map();
+	for (const contentMustAgree of [true, false]) {
+		const admits = (b, h) => b.key === h.key && Math.abs(b.line - h.line) <= lineFuzz && (!contentMustAgree || isEqual(b.item, h.item));
+		for (const [baseIndex, headIndex] of assignInOrder(base, head, freeBase, freeHead, admits)) {
+			freeBase.delete(baseIndex);
+			freeHead.delete(headIndex);
+			const counterpart = base[baseIndex];
+			if (counterpart !== void 0) partnerOf.set(headIndex, counterpart);
 		}
-		consumedBase.add(matchIdx);
-		const bmatch = base[matchIdx];
-		if (bmatch === void 0) continue;
-		if (!isEqual(bmatch.item, h.item)) modified.push(h.item);
 	}
-	for (let j = 0; j < base.length; j++) {
-		if (consumedBase.has(j)) continue;
-		const b = base[j];
-		if (b === void 0) continue;
-		removed.push(b.item);
+	const added = [];
+	const modified = [];
+	for (const [index, h] of head.entries()) {
+		const counterpart = partnerOf.get(index);
+		if (counterpart === void 0) added.push(h.item);
+		else if (!isEqual(counterpart.item, h.item)) modified.push(h.item);
 	}
 	return {
 		added,
-		removed,
+		removed: base.filter((_, index) => freeBase.has(index)).map((b) => b.item),
 		modified
 	};
 }
+const NO_PAIRINGS = {
+	pairs: 0,
+	distance: 0
+};
+/** `a` is preferred over `b`: more pairings wins, and among equals the tighter one does. */
+function better(a, b) {
+	return a.pairs !== b.pairs ? a.pairs > b.pairs : a.distance < b.distance;
+}
+/**
+* The best set of non-crossing pairings between the still-free elements of `base` and `head`,
+* as `[baseIndex, headIndex]` in ascending order — most pairings first, then least total line
+* movement.
+*
+* Non-crossing is the whole content of the rule, and ir-schema §14 #11 is what licenses it:
+* these arrays are ordered by line, so `i < j` means element `i` sits above element `j` in the
+* file. Two pairings that cross would have an element move above one it was below, which is
+* not a line shift — it is a different element. Restricting to non-crossing sets also makes
+* the optimum reachable by a suffix recurrence rather than by a general assignment algorithm.
+*
+* Maximising the count before minimising distance is what stops a near pairing from being
+* taken at the cost of a far one that would otherwise have no partner at all.
+*/
+function assignInOrder(base, head, freeBase, freeHead, admits) {
+	const best = Array.from({ length: base.length + 1 }, () => Array.from({ length: head.length + 1 }, () => NO_PAIRINGS));
+	const pairingAt = (i, j) => {
+		const b = base[i];
+		const h = head[j];
+		if (b === void 0 || h === void 0) return null;
+		if (!freeBase.has(i) || !freeHead.has(j) || !admits(b, h)) return null;
+		const rest = best[i + 1]?.[j + 1] ?? NO_PAIRINGS;
+		return {
+			pairs: rest.pairs + 1,
+			distance: rest.distance + Math.abs(b.line - h.line)
+		};
+	};
+	for (let i = base.length - 1; i >= 0; i--) for (let j = head.length - 1; j >= 0; j--) {
+		const skipBase = best[i + 1]?.[j] ?? NO_PAIRINGS;
+		const skipHead = best[i]?.[j + 1] ?? NO_PAIRINGS;
+		let winner = better(skipBase, skipHead) ? skipBase : skipHead;
+		const paired = pairingAt(i, j);
+		if (paired !== null && better(paired, winner)) winner = paired;
+		const row = best[i];
+		if (row !== void 0) row[j] = winner;
+	}
+	const chosen = [];
+	let i = 0;
+	let j = 0;
+	while (i < base.length && j < head.length) {
+		const here = best[i]?.[j] ?? NO_PAIRINGS;
+		const paired = pairingAt(i, j);
+		if (paired !== null && paired.pairs === here.pairs && paired.distance === here.distance) {
+			chosen.push([i, j]);
+			i++;
+			j++;
+			continue;
+		}
+		const skipBase = best[i + 1]?.[j] ?? NO_PAIRINGS;
+		if (skipBase.pairs === here.pairs && skipBase.distance === here.distance) i++;
+		else j++;
+	}
+	return chosen;
+}
 function diffRules(base, head, lineFuzz) {
 	const mapper = (r) => ({
 		item: r,
@@ -303,6 +467,13 @@ function diffSignature(base, head) {
 			typeParametersChanged: !arraysEqual(base?.typeParameters ?? empty.added.map(String), head?.typeParameters ?? empty.added.map(String))
 		};
 	}
+	/**
+	* Parameters are positional, so the index is part of the identity and the fuzz below is 0.
+	* That makes each key unique within its list, so §5.2.0 never has a choice to make here and
+	* both of its passes reduce to the same positional comparison. Dropping the index from the
+	* key would make two same-named parameters ambiguous and hand the choice back to §5.2.0,
+	* which is not what a positional list wants.
+	*/
 	const inputMapper = (input, index) => ({
 		item: input,
 		key: `${index}:${input.name}`,
@@ -417,6 +588,15 @@ function compareUnorderedSet(a, b) {
 * The result is de-duplicated so `InvoiceService.createInvoice` collapses to
 * `["invoice", "service", "create"]` — Jaccard similarity relies on set semantics, so
 * repeated tokens must not double-count.
+*
+* **The camel boundary is ASCII.** `isCamelBoundary` compares code points against `a`–`z`,
+* `A`–`Z` and `0`–`9`, so a name written in a script with no ASCII case boundary and no
+* separator comes back whole: `获取用户信息` and `ユーザー情報を取得する` are one token each,
+* and so is `получитьПользователя` — its camel hump does not register. A separator still
+* splits (`ユーザー.取得` gives two), and a mixed name splits on its ASCII half.
+*
+* That makes the token count a poor measure of how much such a name says, which matters
+* wherever a count is read as a proxy for that — see §3.4.3's admissibility rule.
 */
 function tokenizeName(input) {
 	const seen = /* @__PURE__ */ new Set();
@@ -466,47 +646,280 @@ function isCamelBoundary(prev, curr) {
 * purpose of §3.4.1). Empty on one side only returns 0.0.
 */
 function jaccard(a, b) {
-	if (a.length === 0 && b.length === 0) return 1;
-	if (a.length === 0 || b.length === 0) return 0;
-	const setA = new Set(a);
-	const setB = new Set(b);
+	return jaccardSets(new Set(a), new Set(b));
+}
+function jaccardSets(a, b) {
+	if (a.size === 0 && b.size === 0) return 1;
+	if (a.size === 0 || b.size === 0) return 0;
+	const [small, large] = a.size <= b.size ? [a, b] : [b, a];
 	let intersection = 0;
-	for (const t of setA) if (setB.has(t)) intersection++;
-	const union = setA.size + setB.size - intersection;
-	return intersection / union;
+	for (const token of small) if (large.has(token)) intersection++;
+	return intersection / (a.size + b.size - intersection);
 }
-/** name-token Jaccard shortcut used by nameSimilarity and ownerSimilarity call sites. */
+/**
+* Jaccard over the tokens of two strings. Part of the module's surface rather than an
+* internal shortcut: the two formulas below go through a token table they share for one
+* matching pass, so this has no caller inside this file.
+*/
 function jaccardTokens(a, b) {
 	return jaccard(tokenizeName(a), tokenizeName(b));
 }
+const tokenizeEveryTime = (value) => new Set(tokenizeName(value));
 /**
 * §3.4.1 — Jaccard over the tokens of the full qualified name. The last segment is not
 * given extra weight; the entire path contributes uniformly because the intersection is
 * what the score should reward.
 */
 function nameSimilarity(baseName, headName) {
-	return jaccardTokens(baseName, headName);
+	return nameFormula(tokenizeEveryTime, baseName, headName);
 }
 /**
-* §3.4.6 — owner similarity: same as nameSimilarity but restricted to everything **before**
-* the last segment. Compensates for the R-8 same-name-different-class collision, where
-* `UserRepo.getUser` should not be pair-swapped with `AdminRepo.getUser`.
+* §3.4.1 — Jaccard over the tokens of the **last segment**: the member name with its owner
+* removed. What §3.4's composite reads, because §3.4.6 decides the owner separately and
+* reading it on both axes charges for it twice.
+*/
+function memberSimilarity(baseName, headName) {
+	return memberFormula(tokenizeEveryTime, baseName, headName);
+}
+/**
+* §3.4.6 (R-8) — whether two Symbols are close enough in *scope* to be the same Symbol: the
+* same owner, or one whose owner was renamed. A gate rather than a score, because grading the
+* owner cannot do what R-8 asks. `UserRepo.findById` and `AdminRepo.findById` agree on their
+* member name and their signature, so a shared `Repo` token at weight 0.2 carries them to
+* 0.8667 against a 0.85 threshold — while `UsersRepository.findById`, which *is* the rename,
+* shares no owner token and scores 0.8000. The collision outscores the rename, and raising the
+* weight only moves both: at 0.3 two three-token class names sharing two tokens land on
+* exactly 0.85.
 *
 * Owner extraction:
 * - `Class::method` → `Class`
 * - `A.B.C.method` → `A.B.C`
 * - `topLevel`     → `` (empty)
 *
-* When both owners are empty (top-level functions), returns 1.0 because both live in the
-* same "no-owner" bucket. When one is empty and the other is not, returns 0.0 because the
-* two Symbols live in structurally different scopes.
+* Two empty owners are compatible: top-level Symbols share the one outer scope. One empty and
+* one not are never compatible — the two live at different depths.
+*
+* Otherwise the owners must correspond segment for segment, and within a segment every token
+* on each side must find a distinct partner on the other under `sameWord`. Both sides must be
+* covered, so `UserRepo` and `UserRepoV2` are two classes rather than one renamed — an added
+* token is as much evidence of a sibling as of a rename, and R-8's business is refusing the
+* collision.
 */
-function ownerSimilarity(baseName, headName) {
+function ownersAreCompatible(baseName, headName) {
+	return ownerGate(tokenizeEveryTime, baseName, headName);
+}
+/**
+* §3.4.6 — the tokens `a` and `b` name the same thing.
+*
+* Equal, or the same word inflected: `user`/`users`, `entity`/`entities`. Nothing else, and
+* that is the whole of the rule rather than a first approximation.
+*
+* A bare prefix test is the obvious generalisation and it cannot be made to work. It admits
+* `repo`/`report`, `cache`/`cached`, `con`/`controller` — two distinct classes, which is
+* exactly the collision R-8 exists to refuse. Every measure that might separate those from a
+* real rename fails, because the two populations interleave rather than sitting on opposite
+* sides of anything:
+*
+* ```
+*                              dice    levenshtein
+*   accept  UserRepo/UsersRepository   0.571   7
+*   reject  RepoManager/ReportManager  0.818   2
+*   accept  Repo/Repository            0.500   6
+*   reject  CacheStore/CachedStore     0.842   1
+* ```
+*
+* The renames to accept score *lower* than the collisions to refuse, on both. There is no
+* threshold, and a length-growth rule fares no better: `con`→`controller` grows by 7 and
+* `user`→`users` by 1, so anything admitting the second admits the first.
+*
+* Inflection is not on that spectrum. It is a closed, mechanical relation between two spellings
+* of one word, so it can be recognised rather than estimated — and it covers the case a plain
+* equality test misses most often, a class pluralised in place.
+*
+* What this gives up is the abbreviation family: `UserRepo` → `UsersRepository` no longer
+* clears the gate on `repo`/`repository`. That is a real rename reported as `added` +
+* `removed`, and §3.4.6 records it as the price of refusing `repo`/`report`, which no rule
+* over the two strings alone can tell apart. The evidence that would settle it is not in the
+* strings: the owner is itself a Symbol, and whether *it* paired is the question being
+* guessed at here.
+*/
+function sameWord(a, b) {
+	if (a === b) return true;
+	const [short, long] = a.length <= b.length ? [a, b] : [b, a];
+	return pluralises(short, long);
+}
+/**
+* The longest owner segment the matching will search.
+*
+* `augment` is Kuhn's, so the search is cubic in the token count and recursive with it. A
+* class name is a handful of words; anything past this is not a name the gate has an opinion
+* about, and `buildDiff` takes IR JSON from a caller rather than only from `aburi scan`, so
+* the bound is what turns an adversarial 1600-token identifier from a hang into an answer.
+* Refusing is the safe direction: the pair falls to `added` + `removed`.
+*/
+const MAX_OWNER_SEGMENT_TOKENS = 32;
+/** English noun inflection, which is what a pluralised class name goes through. */
+function pluralises(singular, plural) {
+	if (plural === `${singular}s` || plural === `${singular}es`) return true;
+	return singular.endsWith("y") && plural === `${singular.slice(0, -1)}ies`;
+}
+function nameFormula(setOf, baseName, headName) {
+	return jaccardSets(setOf(baseName), setOf(headName));
+}
+function memberFormula(setOf, baseName, headName) {
+	return jaccardSets(setOf(lastSegment(baseName)), setOf(lastSegment(headName)));
+}
+function ownerGate(setOf, baseName, headName) {
 	const baseOwner = extractOwner(baseName);
 	const headOwner = extractOwner(headName);
-	if (baseOwner === "" && headOwner === "") return 1;
-	if (baseOwner === "" || headOwner === "") return 0;
-	return jaccardTokens(baseOwner, headOwner);
+	if (baseOwner === "" && headOwner === "") return true;
+	if (baseOwner === "" || headOwner === "") return false;
+	if (baseOwner === headOwner) return true;
+	return segmentsCorrespond(baseOwner, headOwner, setOf);
+}
+/**
+* §3.4.6 — the two owners name the same scope: segment for segment, token for token.
+*
+* Compared per segment rather than over the owner as a whole, because `tokenizeName` dedups
+* and an owner is a *path*. `Users.UserRepo` collapses to `{users, user, repo}` while
+* `Users.UsersRepository` collapses to `{users, repository}` — the namespace and the class
+* share a word, so one side loses a token and the two stop being comparable before any
+* spelling is looked at. Segment by segment they line up: `Users`/`Users`, then
+* `UserRepo`/`UsersRepository`.
+*
+* A rename changes what a class is called, not how deeply it is nested, so a differing segment
+* count is a differing scope.
+*/
+function segmentsCorrespond(baseOwner, headOwner, setOf) {
+	const baseSegments = baseOwner.split(".");
+	const headSegments = headOwner.split(".");
+	if (baseSegments.length !== headSegments.length) return false;
+	return baseSegments.every((segment, index) => {
+		const counterpart = headSegments[index];
+		if (counterpart === void 0) return false;
+		if (segment === counterpart) return true;
+		return coversBothWays(setOf(segment), setOf(counterpart));
+	});
+}
+/**
+* Whether the two token sets admit a perfect matching under `sameWord`.
+*
+* Sizes must agree, after which an injection from one side is a bijection — so only one
+* direction is searched. The search is augmenting-path rather than greedy, because a greedy
+* pass can strand a token a different choice would have matched: over `{user, users}` and
+* `{user, userx}`, taking the identical pair first leaves `users` with nothing, though
+* `user`→`userx` with `users`→`user` covers both. One segment runs to a handful of tokens, so
+* the exact answer costs nothing worth saving.
+*/
+function coversBothWays(a, b) {
+	if (a.size !== b.size) return false;
+	if (a.size > MAX_OWNER_SEGMENT_TOKENS) return false;
+	const right = [...b];
+	const partnerOf = /* @__PURE__ */ new Map();
+	for (const token of a) if (!augment(token, right, partnerOf, /* @__PURE__ */ new Set())) return false;
+	return true;
+}
+/** Kuhn's step: claim a free partner for `token`, or displace one that can move on. */
+function augment(token, right, partnerOf, visited) {
+	for (const candidate of right) {
+		if (visited.has(candidate) || !sameWord(token, candidate)) continue;
+		visited.add(candidate);
+		const holder = partnerOf.get(candidate);
+		if (holder === void 0 || augment(holder, right, partnerOf, visited)) {
+			partnerOf.set(candidate, token);
+			return true;
+		}
+	}
+	return false;
+}
+/**
+* §3.4.6 — a necessary condition on two non-empty owners, cheaper than the full gate: their
+* first segments must correspond, since segments are compared positionally.
+*
+* A filter, not a decision. It relaxes `coversBothWays`' perfect matching to "every token
+* finds some partner", so it can only ever admit more than the gate does; answering `true`
+* says the gate has to be asked. Loosening it further costs correctness nothing and speed a
+* little — refusing something the gate would accept is the direction that would break recall.
+*/
+function firstSegmentsCouldAgree(baseOwner, headOwner, setOf) {
+	const baseFirst = baseOwner.slice(0, dotOrEnd(baseOwner));
+	const headFirst = headOwner.slice(0, dotOrEnd(headOwner));
+	if (baseFirst === headFirst) return true;
+	const baseTokens = setOf(baseFirst);
+	const headTokens = setOf(headFirst);
+	if (baseTokens.size !== headTokens.size) return false;
+	if (baseTokens.size > MAX_OWNER_SEGMENT_TOKENS) return false;
+	for (const token of baseTokens) {
+		let partnered = false;
+		for (const candidate of headTokens) if (sameWord(token, candidate)) {
+			partnered = true;
+			break;
+		}
+		if (!partnered) return false;
+	}
+	return true;
+}
+function dotOrEnd(owner) {
+	const dot = owner.indexOf(".");
+	return dot < 0 ? owner.length : dot;
+}
+/**
+* A scorer that tokenises each distinct name once.
+*
+* Stage 4 scores every (base, head) pair in a bucket, so a bucket of K on each side asks for
+* K² similarities over 2K distinct names — tokenising on every call splits the same strings
+* into the same tokens hundreds of thousands of times. The table lives for one call rather
+* than for the process, because the names it holds are only the ones that pass is comparing.
+*/
+function createNameScorer() {
+	const sets = /* @__PURE__ */ new Map();
+	const setOf = (value) => {
+		const cached = sets.get(value);
+		if (cached !== void 0) return cached;
+		const built = new Set(tokenizeName(value));
+		sets.set(value, built);
+		return built;
+	};
+	const owners = /* @__PURE__ */ new Map();
+	const ownerOf = (qname) => {
+		const cached = owners.get(qname);
+		if (cached !== void 0) return cached;
+		const built = extractOwner(qname);
+		owners.set(qname, built);
+		return built;
+	};
+	/**
+	* §3.4.6's gate, with the segment split and the matching skipped where they can be.
+	*
+	* The gate is the costliest thing stage 4 asks per candidate — it splits both owners into
+	* segments, tokenises each and runs an augmenting-path matching. Two shortcuts, in order of
+	* how much they save:
+	*
+	* - **Identical owners.** A bucket of methods on one class asks about the same owner over
+	*   and over, and `ownerGate` already answers those on a string compare; doing it here skips
+	*   the two `extractOwner` calls as well, which are substrings on every candidate.
+	* - **A different first segment.** Segments correspond positionally, so owners whose first
+	*   segments cannot be the same word are incompatible whatever the rest says. The check is
+	*   one `sameWord` over two token sets the table already holds, against a full matching over
+	*   every segment.
+	*
+	* Not memoised on the pair. A bulk rename produces as many distinct owner pairs as
+	* candidates, so a table keyed on them grows with the cross-product — enough to exceed
+	* V8's Map limit on the very input this is meant to make fast.
+	*/
+	const compatible = (baseName, headName) => {
+		const baseOwner = ownerOf(baseName);
+		const headOwner = ownerOf(headName);
+		if (baseOwner === headOwner) return true;
+		if (baseOwner === "" || headOwner === "") return false;
+		if (!firstSegmentsCouldAgree(baseOwner, headOwner, setOf)) return false;
+		return segmentsCorrespond(baseOwner, headOwner, setOf);
+	};
+	return {
+		name: (baseName, headName) => nameFormula(setOf, baseName, headName),
+		member: (baseName, headName) => memberFormula(setOf, baseName, headName),
+		ownersCompatible: compatible
+	};
 }
 function extractOwner(qname) {
 	const staticIdx = qname.indexOf("::");
@@ -528,9 +941,75 @@ function lastSegment(qname) {
 //#region src/match.ts
 /** Fingerprint for the 12-hex-char "everything zero" (i.e. dropped) canonical hash. */
 const ZERO_LOGIC_FP = "000000000000";
+/** §3.3 — the similarity a multi-candidate logic-fingerprint group must reach to pair. */
+const NAME_DISAMBIGUATION_THRESHOLD = .85;
+/**
+* §3.8 — accept candidate pairings highest score first, taking each base and each head at
+* most once. Stages 3, 4 and 4.5 all choose from a set of possible pairings, and all three
+* used to decide one head at a time — which let an earlier head consume a base that was a
+* later head's exact match, and reported the loser as `added` beside the pair it lost.
+*
+* The two id sets come back with the pairings because every caller needs them to work out
+* what is left over, and deriving them again at the call site is a chance to derive the
+* wrong one: reading the head ids out as the base ids typechecks, and reproduces the very
+* symptom this exists to prevent.
+*
+* Not free, and §8.2 carries the bound: `candidates` is every pairing that clears its
+* threshold, so this holds O(base × head) records for stages 3 and 4 in the worst case where
+* the per-head loop it replaced held one, and sorting them is O(C log C). Stage 4 buys that
+* back and more with `createNameScorer`.
+*
+* It is not an optimal assignment — a greedy sweep can still strand a pair whose partners
+* were both taken by higher-scoring ones — but it never passes over the best available
+* pairing, which is the case that shows up in a review as one symbol appearing twice.
+*
+* Stage 4.5 does not call this, because that licence is what it cannot borrow: §3.4.5's
+* candidates are all worth the same, so no pairing is the best available and stranding one
+* buys nothing. See `bestPairing`.
+*/
+function acceptInScoreOrder(candidates) {
+	candidates.sort(compareCandidates);
+	const baseIds = /* @__PURE__ */ new Set();
+	const headIds = /* @__PURE__ */ new Set();
+	const pairs = [];
+	for (const candidate of candidates) {
+		if (baseIds.has(candidate.base.id) || headIds.has(candidate.head.id)) continue;
+		baseIds.add(candidate.base.id);
+		headIds.add(candidate.head.id);
+		pairs.push(candidate);
+	}
+	return {
+		pairs,
+		baseIds,
+		headIds
+	};
+}
+/**
+* Highest score first, then `(base.id, head.id)` ascending. The two id keys are what make
+* the order total, and they are a total order only because ids are unique within a Document
+* (ir-schema.md §14 #1), which `buildDiff` establishes before the first stage runs. Without
+* them equal scores resolve to enumeration order, and the diff stops being a function of the
+* two Documents.
+*/
+function compareCandidates(a, b) {
+	if (a.score !== b.score) return b.score - a.score;
+	if (a.base.id !== b.base.id) return a.base.id < b.base.id ? -1 : 1;
+	return a.head.id < b.head.id ? -1 : a.head.id > b.head.id ? 1 : 0;
+}
+/** The entries of `symbols` that no accepted pairing claimed, in their original order. */
+function unclaimed(symbols, claimed) {
+	return symbols.filter((symbol) => !claimed.has(symbol.id));
+}
 /**
 * §3.1 — segments Symbols with identical `id` into paired matches. Runs first because it
 * is the highest-confidence signal (no heuristics, just hash lookup).
+*
+* Assumes `id` is unique on each side (ir-schema.md §14 #1) and does not check it:
+* `buildDiff` establishes that before calling, and a caller reaching this export directly
+* owns the obligation. A repeat on the head side loses all but the last entry to the lookup
+* map and then removes every one of them from `remainingHead`; a repeat on the base side
+* pairs the same head Symbol more than once. The later stages track consumed base Symbols
+* by id and lose a repeat the same way.
 */
 function matchStageId(base, head) {
 	const headById = /* @__PURE__ */ new Map();
@@ -557,7 +1036,9 @@ function matchStageId(base, head) {
 }
 /**
 * §3.2 — git rename detection. When a rename map is available (typical of ref-driven
-* scans), rewrite the base id with the head-side file path and look for a hit.
+* scans), rewrite the base id with the head-side file path and look for a hit. Two base
+* files renamed onto one target predict the same head id, so the claimants are collected
+* before one is chosen.
 *
 * The rewriter only touches the `file` portion of the id — the `<language>:` prefix and
 * the trailing `#<qualified-name>` segment stay unchanged so a moved file with the same
@@ -572,34 +1053,46 @@ function matchStageGitRename(remainingBase, remainingHead, renameMap) {
 	};
 	const headById = /* @__PURE__ */ new Map();
 	for (const h of remainingHead) headById.set(h.id, h);
-	const matched = [];
-	const usedHead = /* @__PURE__ */ new Set();
-	const remaining = [];
+	const claimants = /* @__PURE__ */ new Map();
 	for (const b of remainingBase) {
 		const newPath = renameMap.get(b.source.file);
-		if (newPath === void 0) {
-			remaining.push(b);
-			continue;
-		}
+		if (newPath === void 0) continue;
 		const expectedId = rewriteIdFile(b.id, b.source.file, newPath);
-		const h = expectedId === null ? void 0 : headById.get(expectedId);
-		if (h === void 0 || usedHead.has(h.id)) {
-			remaining.push(b);
-			continue;
-		}
+		if (expectedId === null) continue;
+		const head = headById.get(expectedId);
+		if (head === void 0) continue;
+		const claim = claimants.get(expectedId);
+		if (claim === void 0) claimants.set(expectedId, {
+			head,
+			bases: [b]
+		});
+		else claim.bases.push(b);
+	}
+	const matched = [];
+	const usedBase = /* @__PURE__ */ new Set();
+	const usedHead = /* @__PURE__ */ new Set();
+	for (const { head, bases } of claimants.values()) {
+		const base = lowestId(bases);
 		matched.push({
-			base: b,
-			head: h,
+			base,
+			head,
 			rationale: "git-rename"
 		});
-		usedHead.add(h.id);
+		usedBase.add(base.id);
+		usedHead.add(head.id);
 	}
 	return {
 		matched,
-		remainingBase: remaining,
-		remainingHead: remainingHead.filter((h) => !usedHead.has(h.id))
+		remainingBase: unclaimed(remainingBase, usedBase),
+		remainingHead: unclaimed(remainingHead, usedHead)
 	};
 }
+/** Total on the non-empty claim lists above: a claim is created holding its first base. */
+function lowestId(symbols) {
+	let lowest = symbols[0];
+	for (const symbol of symbols) if (symbol.id < lowest.id) lowest = symbol;
+	return lowest;
+}
 /**
 * Predict the id a base Symbol would carry after git moved its file. The second Symbol-id
 * derivation in the codebase after `makeSymbolId` itself, so it goes back through the same
@@ -622,212 +1115,468 @@ function rewriteIdFile(id, oldPath, newPath) {
 	});
 }
 /**
-* §3.3 — group base Symbols by `fingerprint.logic` and match head Symbols whose logic
-* fingerprint is in the map. Two disambiguation branches:
-* - single candidate → paired with `logic-fingerprint`
-* - multiple candidates → best `nameSimilarity` wins if ≥ 0.85; otherwise leave both
-*   sides in remaining for stage 4 to re-evaluate
+* §3.3 — group both sides by `fingerprint.logic` and pair within each group. Two branches:
+* - single base candidate → paired with `logic-fingerprint`, no similarity test
+* - several → `nameSimilarity` disambiguates at ≥ 0.85; a group that cannot reach it is left
+*   whole for stage 4 to re-evaluate
 *
 * Dropped symbols are excluded (§3.3 tail) — their logic fingerprint is the sentinel
 * `"000000000000"` and would collide with every other dropped Symbol in the workspace.
 * They flow to the stage-4.5 weak matcher instead.
 */
 function matchStageLogicFingerprint(remainingBase, remainingHead) {
-	const logicMap = /* @__PURE__ */ new Map();
-	const carryBase = [];
-	for (const b of remainingBase) {
-		if (b.dropped || b.fingerprint.logic === ZERO_LOGIC_FP) {
-			carryBase.push(b);
-			continue;
-		}
-		const bucket = logicMap.get(b.fingerprint.logic) ?? [];
-		bucket.push(b);
-		logicMap.set(b.fingerprint.logic, bucket);
+	const baseGroups = groupByLogic(remainingBase);
+	const headGroups = groupByLogic(remainingHead);
+	const scorer = createNameScorer();
+	const matched = [];
+	for (const [logic, heads] of headGroups) {
+		const bases = baseGroups.get(logic);
+		if (bases === void 0) continue;
+		matched.push(...pairWithinLogicGroup(bases, heads, scorer));
 	}
+	const usedBase = new Set(matched.map((pair) => pair.base.id));
+	const usedHead = new Set(matched.map((pair) => pair.head.id));
+	return {
+		matched,
+		remainingBase: unclaimed(remainingBase, usedBase),
+		remainingHead: unclaimed(remainingHead, usedHead)
+	};
+}
+/**
+* Symbols by logic fingerprint, skipping the ones §3.3 excludes. Both sides are grouped, so
+* a group is a self-contained problem: the Symbols in it can only pair with each other, and
+* no group’s outcome depends on any other’s.
+*/
+function groupByLogic(symbols) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const symbol of symbols) {
+		if (symbol.dropped || symbol.fingerprint.logic === ZERO_LOGIC_FP) continue;
+		const bucket = groups.get(symbol.fingerprint.logic) ?? [];
+		bucket.push(symbol);
+		groups.set(symbol.fingerprint.logic, bucket);
+	}
+	return groups;
+}
+/**
+* §3.3’s two branches, over one logic-fingerprint group.
+*
+* A lone base candidate pairs with no similarity test — identical logic is taken as proof on
+* its own. With more than one, names disambiguate and a group that cannot reach the
+* threshold is left whole for stage 4.
+*
+* The loop is what keeps the second branch feeding the first: a scored round that consumes
+* all but one base leaves that one unconditional, which is how the per-head version behaved
+* when its candidate list shrank to a single entry.
+*/
+function pairWithinLogicGroup(bases, heads, scorer) {
+	let freeBase = [...bases];
+	let freeHead = [...heads];
 	const matched = [];
-	const carryHead = [];
-	const usedBaseIds = /* @__PURE__ */ new Set();
-	for (const h of remainingHead) {
-		if (h.dropped || h.fingerprint.logic === ZERO_LOGIC_FP) {
-			carryHead.push(h);
-			continue;
-		}
-		const candidates = logicMap.get(h.fingerprint.logic);
-		if (candidates === void 0 || candidates.length === 0) {
-			carryHead.push(h);
-			continue;
-		}
-		if (candidates.length === 1) {
-			const only = candidates[0];
-			if (only === void 0) continue;
+	while (freeBase.length > 0 && freeHead.length > 0) {
+		const lone = freeBase.length === 1 ? freeBase[0] : void 0;
+		if (lone !== void 0) {
+			const head = closestNameTo(lone, freeHead, scorer);
+			if (head === void 0) break;
 			matched.push({
-				base: only,
-				head: h,
+				base: lone,
+				head,
 				rationale: "logic-fingerprint"
 			});
-			usedBaseIds.add(only.id);
-			logicMap.delete(h.fingerprint.logic);
-			continue;
+			break;
+		}
+		const candidates = [];
+		for (const base of freeBase) for (const head of freeHead) {
+			const score = scorer.name(base.name, head.name);
+			if (score >= NAME_DISAMBIGUATION_THRESHOLD) candidates.push({
+				base,
+				head,
+				score
+			});
 		}
-		let best = null;
-		for (const c of candidates) {
-			const score = nameSimilarity(c.name, h.name);
-			if (best === null || score > best.score) best = {
-				symbol: c,
+		const accepted = acceptInScoreOrder(candidates);
+		if (accepted.pairs.length === 0) break;
+		for (const { base, head } of accepted.pairs) matched.push({
+			base,
+			head,
+			rationale: "logic-fingerprint+name-disambiguation"
+		});
+		freeBase = unclaimed(freeBase, accepted.baseIds);
+		freeHead = unclaimed(freeHead, accepted.headIds);
+	}
+	return matched;
+}
+/**
+* The head whose name is closest to `base`, ties going to the lower id. The lone-candidate
+* branch pairs whatever it is given, so this only decides *which* head it takes — but that
+* decision was array order, and it is visible in the diff.
+*/
+function closestNameTo(base, heads, scorer) {
+	let best;
+	for (const head of heads) {
+		const score = scorer.name(base.name, head.name);
+		if (best === void 0 || score > best.score) {
+			best = {
+				head,
 				score
 			};
+			continue;
 		}
-		if (best !== null && best.score >= .85) {
-			matched.push({
-				base: best.symbol,
-				head: h,
-				rationale: "logic-fingerprint+name-disambiguation"
-			});
-			usedBaseIds.add(best.symbol.id);
-			const remainingBucket = candidates.filter((c) => c.id !== best?.symbol.id);
-			if (remainingBucket.length === 0) logicMap.delete(h.fingerprint.logic);
-			else logicMap.set(h.fingerprint.logic, remainingBucket);
-		} else carryHead.push(h);
+		if (score === best.score && head.id < best.head.id) best = {
+			head,
+			score
+		};
 	}
-	const finalBase = [...carryBase];
-	for (const bucket of logicMap.values()) for (const b of bucket) if (!usedBaseIds.has(b.id)) finalBase.push(b);
-	return {
-		matched,
-		remainingBase: finalBase,
-		remainingHead: carryHead
-	};
+	return best?.head;
 }
 /**
 * §3.4 — name + signature similarity with `(kind, signatureNullness)` bucket pre-filter.
 * `signatureNullness` distinguishes symbols with no signature (`interface`, `type`,
 * `class`) from callable ones so that a class body is never paired against a function.
 *
-* The composite score:
-*   0.5 * nameSimilarity + 0.3 * signatureSimilarity + 0.2 * ownerSimilarity
+* §3.4.6's owner gate runs before the score: a pair whose owners are not the same class, or
+* one a rename of the other, is not the same Symbol however well the rest agrees, and no
+* weight small enough to leave the name axis meaning something can outvote a matching member
+* name and signature.
+*
+* The composite score, over the pairs that clear it:
+*   0.5 * memberSimilarity + 0.3 * signatureSimilarity + 0.2 * OWNER_AXIS_SATISFIED
+*
+* `memberSimilarity` reads the last segment, not the whole qualified name: the gate has
+* already settled the owner, and reading it again on the name axis charges for it twice —
+* which is what kept a renamed class from ever pairing (§3.4.6).
 *
-* §3.4.3 threshold table:
-* - 1-token name → 1.0 (unreachable → never paired; false-positive shield)
-* - 2-token name → 0.95 (strict, avoids `getUser` vs `getUsers`)
-* - default      → 0.85
+* §3.4.3 threshold table, applied per head by the token count of its last name segment:
+* - 1 token  → 1.0 (an exact match on both remaining axes)
+* - 2 tokens → 0.95 (strict, avoids `getUser` vs `getUsers`)
+* - default  → 0.85
 *
-* §3.4.3 tail — if both sides are signature-less, we skip pairing entirely because
-* signatureSimilarity always returns 1.0 for `null + null` and would flood the bucket with
-* false pairings.
+* §3.4.3 also names two Symbols the stage does not read at all, because for them the score is
+* high on evidence it does not have rather than on a resemblance: one whose signature is
+* null, since `signatureSimilarity(null, null)` is 1.0 and the bucket key restricts it to
+* candidates that are equally signature-less; and one whose qualified name carries a single
+* distinct token, since that is the whole of what its identity amounts to. Neither can be
+* expressed as a threshold — the second wants a bar above the top of the scale.
+*
+* Every pairing in a bucket that clears its head’s threshold becomes a candidate, and the
+* candidates are settled in score order rather than one head at a time — see
+* `acceptInScoreOrder`. That doubles the pairings scored, from a bucket that shrank as heads
+* consumed it to the full bucket every time; `createNameScorer` more than pays for it by
+* tokenising each distinct name once per pass instead of once per comparison.
 */
 function matchStageNameSignature(remainingBase, remainingHead) {
 	const buckets = /* @__PURE__ */ new Map();
 	for (const b of remainingBase) {
 		if (b.dropped) continue;
+		if (!saysEnoughToPair(b.name)) continue;
 		const key = bucketKey(b);
-		const bucket = buckets.get(key) ?? [];
-		bucket.push(b);
+		const bucket = buckets.get(key) ?? {
+			members: [],
+			byToken: /* @__PURE__ */ new Map()
+		};
+		const position = bucket.members.length;
+		bucket.members.push(b);
+		for (const token of memberTokens(b.name)) {
+			const sharing = bucket.byToken.get(token) ?? [];
+			sharing.push(position);
+			bucket.byToken.set(token, sharing);
+		}
 		buckets.set(key, bucket);
 	}
-	const matched = [];
-	const remainingHeadOut = [];
-	const usedBaseIds = /* @__PURE__ */ new Set();
+	const visitsOf = /* @__PURE__ */ new Map();
+	for (const bucket of buckets.values()) visitsOf.set(bucket, new Int32Array(bucket.members.length));
+	const scorer = createNameScorer();
+	const candidates = [];
+	let visitCount = 0;
 	for (const h of remainingHead) {
-		if (h.dropped) {
-			remainingHeadOut.push(h);
-			continue;
-		}
-		const key = bucketKey(h);
-		const bucket = buckets.get(key);
-		if (bucket === void 0 || bucket.length === 0) {
-			remainingHeadOut.push(h);
-			continue;
-		}
-		if ((h.signature === null || h.signature === void 0) && bucket.every((c) => c.signature === null || c.signature === void 0)) {
-			remainingHeadOut.push(h);
-			continue;
-		}
-		let best = null;
-		for (const c of bucket) {
-			const score = .5 * nameSimilarity(c.name, h.name) + .3 * signatureSimilarity(c.signature ?? null, h.signature ?? null) + .2 * ownerSimilarity(c.name, h.name);
-			if (best === null || score > best.score) best = {
-				symbol: c,
-				score
-			};
-		}
+		if (h.dropped) continue;
+		if (h.signature === null || h.signature === void 0) continue;
+		if (!saysEnoughToPair(h.name)) continue;
+		const bucket = buckets.get(bucketKey(h));
+		if (bucket === void 0) continue;
 		const threshold = thresholdFor(h.name);
-		if (best !== null && best.score >= threshold) {
-			matched.push({
-				base: best.symbol,
-				head: h,
-				rationale: "name-signature"
-			});
-			usedBaseIds.add(best.symbol.id);
-			buckets.set(key, bucket.filter((c) => c.id !== best?.symbol.id));
-		} else remainingHeadOut.push(h);
-	}
-	const remainingBaseOut = [];
-	for (const b of remainingBase) {
-		if (b.dropped) {
-			remainingBaseOut.push(b);
+		const memberFloor = lowestUsefulMember(threshold);
+		const tokens = memberTokens(h.name);
+		let reach = 0;
+		for (const token of tokens) reach += bucket.byToken.get(token)?.length ?? 0;
+		if (reach >= bucket.members.length) {
+			for (const b of bucket.members) collectCandidate(b, h, scorer, memberFloor, threshold, candidates);
 			continue;
 		}
-		if (!usedBaseIds.has(b.id)) remainingBaseOut.push(b);
+		const visited = visitsOf.get(bucket);
+		if (visited === void 0) continue;
+		visitCount++;
+		for (const token of tokens) for (const position of bucket.byToken.get(token) ?? []) {
+			if (visited[position] === visitCount) continue;
+			visited[position] = visitCount;
+			const b = bucket.members[position];
+			if (b !== void 0) collectCandidate(b, h, scorer, memberFloor, threshold, candidates);
+		}
 	}
+	const accepted = acceptInScoreOrder(candidates);
 	return {
-		matched,
-		remainingBase: remainingBaseOut,
-		remainingHead: remainingHeadOut
+		matched: accepted.pairs.map(({ base, head }) => ({
+			base,
+			head,
+			rationale: "name-signature"
+		})),
+		remainingBase: unclaimed(remainingBase, accepted.baseIds),
+		remainingHead: unclaimed(remainingHead, accepted.headIds)
 	};
 }
+/**
+* §3.4 — score one candidate pairing and keep it if it clears the head's threshold.
+*
+* A plain function rather than a closure over the head loop: both branches of the walk need
+* it, and a closure built per head is the cross-product moved into the allocator — measurably
+* so, at around 1.6x on a bucket the index cannot narrow.
+*
+* §3.4.3's floor is read before §3.4.6's gate and is the only early exit here. It is one
+* Jaccard over token sets the pass already holds, where the gate splits both owners into
+* segments, tokenises each and runs an augmenting-path matching. The gate short-circuits
+* internally on identical owners and on first segments that cannot correspond, so there is
+* nothing left worth hoisting out of it.
+*/
+function collectCandidate(base, head, scorer, memberFloor, threshold, candidates) {
+	const member = scorer.member(base.name, head.name);
+	if (member < memberFloor) return;
+	if (!scorer.ownersCompatible(base.name, head.name)) return;
+	const score = .5 * member + .3 * signatureSimilarity(base.signature ?? null, head.signature ?? null) + .2 * OWNER_AXIS_SATISFIED;
+	if (score >= threshold) candidates.push({
+		base,
+		head,
+		score
+	});
+}
 function bucketKey(s) {
 	const sig = s.signature === null || s.signature === void 0 ? "no-sig" : "has-sig";
 	return `${s.kind}::${sig}`;
 }
+/**
+* §3.4.0 — the least `memberSimilarity` that leaves `threshold` reachable.
+*
+* `0.5 * member + 0.3 * signature + 0.2 * 1` must reach the threshold, and the signature axis
+* is worth at most 0.3, so `member >= 2 * (threshold - 0.5)`. Refusing below this is exact
+* rather than approximate: nothing the other two axes can do rescues a pair under it.
+*
+* Reading it before §3.4.6's gate is what keeps stage 4 off the cross-product. The gate splits
+* and tokenises two owners; this is one Jaccard over token sets the pass has already built,
+* and it refuses most of what a shared token admits.
+*/
+function lowestUsefulMember(threshold) {
+	return 2 * (threshold - .5);
+}
+/**
+* §3.4.0 — the token that stands in for a member name carrying none.
+*
+* `Foo.Bar.` has an empty last segment and two tokens in its qualified name, so it is
+* admissible, and two such Symbols score 1.0 on an axis comparing two empty sets. They have
+* no token to be indexed under and cannot pair with anything that has one, so they share a
+* key of their own. A real token cannot collide with it: `tokenizeName` never emits a space.
+*/
+const NO_MEMBER_TOKENS = " none";
+function memberTokens(qname) {
+	const tokens = tokenizeName(lastSegment(qname));
+	return tokens.length === 0 ? [NO_MEMBER_TOKENS] : tokens;
+}
+/**
+* §3.4.3 — the composite score a pair must reach, by how many tokens the head's last name
+* segment has. A one-token segment still asks for the whole scale, which a pair reaches on an
+* identical member name and signature past §3.4.6's gate: `0.5 + 0.3 + 0.2`, exactly 1 in
+* IEEE 754. The owner need not be identical, only compatible — `UserRepo.get` and
+* `UserRepos.get` reach it.
+*/
+const EXACT_MATCH_ONLY = 1;
+const TWO_TOKEN_THRESHOLD = .95;
+const DEFAULT_THRESHOLD = .85;
+/**
+* §3.4.6 — what the owner axis is worth to a pair that clears its gate, which is every pair
+* that reaches the score. Written as a value rather than folded into the weights so the
+* composite keeps the 0.5/0.3/0.2 shape §3.4.3's rows are calibrated against: dropping the
+* term and renormalising would move every threshold without changing what any of them means.
+*/
+const OWNER_AXIS_SATISFIED = 1;
 function thresholdFor(qname) {
 	const tokens = tokenizeName(lastSegment(qname)).length;
-	if (tokens <= 1) return 1;
-	if (tokens === 2) return .95;
-	return .85;
+	if (tokens <= 1) return EXACT_MATCH_ONLY;
+	if (tokens === 2) return TWO_TOKEN_THRESHOLD;
+	return DEFAULT_THRESHOLD;
 }
 /**
-* §3.4.5 — dropped-only weak matcher. For dropped Symbols the fingerprint is zeroed and
-* name/signature are the only remaining signals. Score is a coarse "did the last name
-* segment or file basename survive?" — if either half matches we pair (threshold 0.5).
+* §3.4.3 — whether a Symbol's qualified name says enough for stage 4 to read it at all.
+*
+* The score is built from three things the name supplies: its tokens, its owner's tokens,
+* and a signature. A name of one distinct token supplies one word and an owner that either
+* repeats it or is empty, and `main(x: string): void` against another `main(x: string): void`
+* scores the full 1.0 on that — two unrelated CLI entry points reported as one move. The
+* table's first row was written to refuse this and could not: 1.0 is the top of the scale,
+* so no threshold sits above it. Being unpairable is a property of the name, not a score it
+* failed to reach, so it is decided here rather than by the comparison.
+*
+* Counted over the whole qualified name, because that is what the score reads.
+* `UserRepo.get` supplies three tokens and pairs, though its last segment is one — the
+* measure `thresholdFor` uses, and the wrong one for this question. Tokens are deduped, so
+* `Main.main` supplies one and does not.
+*
+* Read off both sides, because the property belongs to a pairing. It was once read off the
+* head alone, on the arithmetic that a short name anywhere capped the score at 0.75 — true
+* while the name axis read the whole qualified name, and false since §3.4.6 became a gate and
+* the axis moved to the last segment. `Main.main` is one deduped token and clears the gate
+* against `Mains.main`, whose member name is identical, so the pair reaches the top of the
+* scale from a name saying one word.
 *
-* This is deliberately lax; diff-algorithm.md §3.4.5 already accepts that dropped Symbols live
-* outside the main IR review surface, so occasional false pairings only affect the
-* "Drop-rule variation" fold-out section in the Markdown projection.
+* The count stands in for how much the name says, and `tokenizeName` splits on ASCII case
+* boundaries, so a name written in a script that has none is one token however long it is:
+* `ユーザー情報を取得する` is refused here on the same footing as `main`. For that name the
+* proxy is wrong — two unrelated Symbols do not carry it by coincidence the way two carry
+* `main` — and the cost is a stage-4 move this stage will not find. Fixing it means measuring
+* the name by something other than a bare token count, which is §3.4.1's to change.
+*/
+function saysEnoughToPair(qname) {
+	return tokenizeName(qname).length > 1;
+}
+/**
+* §3.4.5 — dropped-only weak matcher. For dropped Symbols the fingerprint is zeroed, so the
+* only signals left are the trailing segment of the qualified name and the file basename.
+* Either one alone is enough to pair, which is deliberately lax: §3.4.5 accepts a
+* false-positive risk because dropped Symbols sit outside the IR's main review surface.
+*
+* What it does not accept is a signal that identifies nothing. A basename hit on `index.ts`
+* — the most common filename in a TypeScript monorepo — paired every dropped Symbol of one
+* kind under one with every other, at a score they all tied on, and the results landed in
+* `summary.moved`, which `--fail-on moved` gates on. So a half counts only when exactly one
+* dropped base and one dropped head carry that key: such a key names a pair, where a key
+* several Symbols carry names a group, and a group is not a pairing.
+*
+* That makes the candidates the identifying keys themselves — at most one pairing each,
+* two axes, so at most `2 × min(base, head)` of them rather than the cross-product a shared
+* basename used to produce.
+*
+* "Exactly one" is counted over the Symbols this stage is handed, not over every dropped
+* Symbol in the Document — stages 1 and 2 have already taken theirs, and a key they emptied
+* out identifies again. That is the intended reading, since the question is which leftover a
+* key picks out, but it is also how a shared `index.ts` comes back: three dropped classes
+* under one, two of them matched by id, and the basename identifies the two that are left.
+*
+* It also leaves nothing for §3.4.5's 0.5-per-half scale to rank, so §3.8's sweep is the
+* wrong instrument: it settles conflicts by score, and with none to settle by it would drop
+* one identified pairing for another over nothing but the id it sorts under. `bestPairing`
+* takes a maximum matching instead.
 */
 function matchStageDroppedWeak(remainingBase, remainingHead) {
-	const droppedBase = remainingBase.filter((s) => s.dropped);
-	const nonDroppedBase = remainingBase.filter((s) => !s.dropped);
-	const droppedHead = remainingHead.filter((s) => s.dropped);
-	const nonDroppedHead = remainingHead.filter((s) => !s.dropped);
-	const matched = [];
-	const usedBaseIds = /* @__PURE__ */ new Set();
-	const carryHead = [];
-	for (const h of droppedHead) {
-		let best = null;
-		for (const b of droppedBase) {
-			if (b.kind !== h.kind) continue;
-			if (usedBaseIds.has(b.id)) continue;
-			const nameHit = lastSegment(b.name) === lastSegment(h.name) ? 1 : 0;
-			const fileHit = basename(b.source.file) === basename(h.source.file) ? 1 : 0;
-			const score = .5 * nameHit + .5 * fileHit;
-			if (best === null || score > best.score) best = {
-				symbol: b,
-				score
-			};
-		}
-		if (best !== null && best.score >= .5) {
-			matched.push({
-				base: best.symbol,
-				head: h,
-				rationale: "dropped-weak-match"
-			});
-			usedBaseIds.add(best.symbol.id);
-		} else carryHead.push(h);
-	}
+	const bases = remainingBase.filter((s) => s.dropped);
+	const heads = remainingHead.filter((s) => s.dropped);
+	const identified = [];
+	for (const keyOf of [nameKey, fileKey]) identified.push(...pairsIdentifiedBy(bases, heads, keyOf));
+	const matched = bestPairing(identified);
 	return {
-		matched,
-		remainingBase: [...nonDroppedBase, ...droppedBase.filter((b) => !usedBaseIds.has(b.id))],
-		remainingHead: [...nonDroppedHead, ...carryHead]
+		matched: matched.map(({ base, head }) => ({
+			base,
+			head,
+			rationale: "dropped-weak-match"
+		})),
+		remainingBase: unclaimed(remainingBase, new Set(matched.map((edge) => edge.base.id))),
+		remainingHead: unclaimed(remainingHead, new Set(matched.map((edge) => edge.head.id)))
+	};
+}
+/**
+* As many of the identified pairings as can hold at once.
+*
+* Each axis identifies a Symbol at most once, so a Symbol carries at most two pairings and
+* the whole set is the union of two matchings — which is a disjoint union of simple paths and
+* even cycles. Alternate pairings along a component are therefore a maximum matching of it,
+* and walking each component from a fixed end makes the choice among the maximum matchings
+* canonical rather than a property of the input order.
+*
+* The alternative would be §3.8's sweep, and it is the wrong instrument once §3.4.5's score
+* is gone: over `Shared.ts#Alpha`, `Other.ts#Beta` against `Other.ts#Alpha`,
+* `Shared.ts#Gamma`, all three pairings are identified and it takes one where two hold.
+*/
+function bestPairing(edges) {
+	const ordered = [...edges].sort(byEndpoints);
+	const atBase = /* @__PURE__ */ new Map();
+	const atHead = /* @__PURE__ */ new Map();
+	for (const [index, edge] of ordered.entries()) {
+		appendTo(atBase, edge.base.id, index);
+		appendTo(atHead, edge.head.id, index);
+	}
+	const adjacent = (index) => {
+		const edge = ordered[index];
+		if (edge === void 0) return [];
+		return [...atBase.get(edge.base.id) ?? [], ...atHead.get(edge.head.id) ?? []].filter((other) => other !== index);
 	};
+	const walked = ordered.map(() => false);
+	const matching = [];
+	/** Follow a component from `start`, taking every other pairing along it. */
+	const walkFrom = (start) => {
+		let step = start;
+		let take = true;
+		while (!walked[step]) {
+			walked[step] = true;
+			const edge = ordered[step];
+			if (take && edge !== void 0) matching.push(edge);
+			take = !take;
+			const next = adjacent(step).find((other) => walked[other] === false);
+			if (next === void 0) return;
+			step = next;
+		}
+	};
+	for (const [index] of ordered.entries()) if (!walked[index] && adjacent(index).length <= 1) walkFrom(index);
+	for (const [index] of ordered.entries()) if (!walked[index]) walkFrom(index);
+	return matching;
+}
+function byEndpoints(a, b) {
+	if (a.base.id !== b.base.id) return a.base.id < b.base.id ? -1 : 1;
+	return a.head.id < b.head.id ? -1 : a.head.id > b.head.id ? 1 : 0;
+}
+function appendTo(table, key, index) {
+	const bucket = table.get(key);
+	if (bucket === void 0) table.set(key, [index]);
+	else bucket.push(index);
+}
+/**
+* The pairings a key picks out on its own: those whose key exactly one dropped base and one
+* dropped head carry. A key held by two Symbols on either side is discarded rather than
+* resolved — with the fingerprint zeroed there is nothing left to tell the members apart, and
+* guessing between them is the false pairing this rule exists to refuse.
+*/
+function pairsIdentifiedBy(bases, heads, keyOf) {
+	const soleBase = soleCarriers(bases, keyOf);
+	const soleHead = soleCarriers(heads, keyOf);
+	const pairs = [];
+	for (const [key, base] of soleBase) {
+		const head = soleHead.get(key);
+		if (head !== void 0) pairs.push({
+			base,
+			head
+		});
+	}
+	return pairs;
+}
+/** Keys carried by exactly one of `symbols`, mapped to it. */
+function soleCarriers(symbols, keyOf) {
+	const sole = /* @__PURE__ */ new Map();
+	const shared = /* @__PURE__ */ new Set();
+	for (const symbol of symbols) {
+		const key = keyOf(symbol);
+		if (shared.has(key)) continue;
+		if (sole.has(key)) {
+			sole.delete(key);
+			shared.add(key);
+			continue;
+		}
+		sole.set(key, symbol);
+	}
+	return sole;
+}
+/**
+* The two halves §3.4.5 scores. `kind` leads because it gates a pair before either half is
+* read, and `/` separates because no kind, qualified-name segment or basename contains one.
+*/
+function nameKey(symbol) {
+	return `${symbol.kind}/${lastSegment(symbol.name)}`;
+}
+function fileKey(symbol) {
+	return `${symbol.kind}/${basename(symbol.source.file)}`;
 }
 function basename(path) {
 	const slash = path.lastIndexOf("/");
@@ -1027,6 +1776,7 @@ function nodeIdOf(change) {
 	switch (change.status) {
 		case "added": return change.symbol.id;
 		case "removed": return change.symbol.id;
+		case "unknown": return change.symbol.id;
 		case "changed":
 		case "moved+changed":
 		case "dropped-toggled": return change.after.id;
@@ -1083,7 +1833,7 @@ function dropDirection(head) {
 
 //#endregion
 //#region src/diff.ts
-const DIFF_SCHEMA = "https://aburi.dev/schema/aburi.diff.v1.json";
+const DIFF_SCHEMA = "https://aburi.kage1020.com/schema/aburi.diff.v1.json";
 const DEFAULT_GENERATOR = {
 	name: "aburi",
 	version: "0.0.0"
@@ -1096,8 +1846,8 @@ const DEFAULT_GENERATOR = {
 * serialisation.
 */
 function buildDiff(input) {
-	assertIRShape(input.baseIR, "baseIR");
-	assertIRShape(input.headIR, "headIR");
+	assertDiffable(input.baseIR, "baseIR");
+	assertDiffable(input.headIR, "headIR");
 	ensureSchemasAgree(input.baseIR, input.headIR);
 	const stage1 = matchStageId(input.baseIR.symbols, input.headIR.symbols);
 	const stage2 = matchStageGitRename(stage1.remainingBase, stage1.remainingHead, input.gitRenames ?? null);
@@ -1112,6 +1862,8 @@ function buildDiff(input) {
 		...stage4_5.matched
 	];
 	const summary = {
+		unknown: 0,
+		depsUnknown: 0,
 		added: 0,
 		removed: 0,
 		moved: 0,
@@ -1127,6 +1879,7 @@ function buildDiff(input) {
 		depsAdded: 0,
 		depsRemoved: 0
 	};
+	let unknown = 0;
 	const symbols = [];
 	for (const pair of pairs) {
 		const status = classifyStatus(pair.base, pair.head);
@@ -1175,16 +1928,48 @@ function buildDiff(input) {
 	}
 	const finalRemainingHead = stage4_5.remainingHead;
 	const finalRemainingBase = stage4_5.remainingBase;
-	for (const h of finalRemainingHead) if (h.dropped) summary.droppedAdded++;
-	else {
+	const baseSide = dependencySideView(input.baseIR);
+	const headSide = dependencySideView(input.headIR);
+	const lostByHead = headSide.lostFiles;
+	const lostByBase = baseSide.lostFiles;
+	for (const h of finalRemainingHead) {
+		if (h.dropped) {
+			summary.droppedAdded++;
+			continue;
+		}
+		const reason = lostByBase.get(h.source.file);
+		if (reason !== void 0) {
+			unknown++;
+			symbols.push({
+				status: "unknown",
+				symbol: h,
+				absentFrom: "base",
+				reason
+			});
+			continue;
+		}
 		summary.added++;
 		symbols.push({
 			status: "added",
 			symbol: h
 		});
 	}
-	for (const b of finalRemainingBase) if (b.dropped) summary.droppedRemoved++;
-	else {
+	for (const b of finalRemainingBase) {
+		if (b.dropped) {
+			summary.droppedRemoved++;
+			continue;
+		}
+		const reason = lostByHead.get(b.source.file);
+		if (reason !== void 0) {
+			unknown++;
+			symbols.push({
+				status: "unknown",
+				symbol: b,
+				absentFrom: "head",
+				reason
+			});
+			continue;
+		}
 		summary.removed++;
 		symbols.push({
 			status: "removed",
@@ -1195,9 +1980,14 @@ function buildDiff(input) {
 	summary.componentsAdded = components.added.length;
 	summary.componentsRemoved = components.removed.length;
 	summary.componentsChanged = components.changed.length;
-	const dependencies = diffDependencies(input.baseIR.dependencies, input.headIR.dependencies);
+	const dependencies = diffDependencies(input.baseIR.dependencies, input.headIR.dependencies, {
+		base: baseSide,
+		head: headSide
+	});
 	summary.depsAdded = dependencies.added.length;
 	summary.depsRemoved = dependencies.removed.length;
+	summary.depsUnknown = dependencies.unknown.length;
+	summary.unknown = unknown;
 	symbols.sort(compareSymbolChange);
 	const slices = computeSlices({
 		changes: symbols,
@@ -1213,9 +2003,41 @@ function buildDiff(input) {
 		symbols,
 		components,
 		dependencies,
-		slices
+		slices,
+		notCompared: filesNeitherSideRead(lostByBase, lostByHead)
 	};
 }
+/**
+* Paths both documents record as never analysed, with each side's own reason.
+*
+* This is the loss `unknown` cannot describe. That status is derived from the matcher's
+* leftovers — a Symbol one document holds and the other lacks — and a file skipped on both
+* sides contributes Symbols to neither, so it leaves no leftover to classify and the whole
+* document falls silent about it. Silence is the one thing it must not do here: a diff with
+* nothing to say about a path is exactly what a diff that compared it and found it unchanged
+* looks like.
+*
+* The intersection, not the union. A one-sided loss has leftovers on the other side and is
+* reported as `unknown` there; listing it here as well would count one loss twice, in two
+* vocabularies that mean different things.
+*
+* Always returns an array, empty included. Optionality in the schema covers documents written
+* before the field existed, and no arithmetic elsewhere in a diff would let a reader tell that
+* case from a run that missed nothing (docs/design/diff-algorithm.md §10.1).
+*/
+function filesNeitherSideRead(lostByBase, lostByHead) {
+	const both = [];
+	for (const [path, baseReason] of lostByBase) {
+		const headReason = lostByHead.get(path);
+		if (headReason === void 0) continue;
+		both.push({
+			path,
+			baseReason,
+			headReason
+		});
+	}
+	return both.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+}
 /** §9.1 — refuse to diff across schema versions. */
 function ensureSchemasAgree(base, head) {
 	if (base.$schema !== head.$schema) throw new DiffError(`Base IR schema "${base.$schema}" does not match head IR schema "${head.$schema}"; a diff across schema versions is not supported.`, {
@@ -1223,31 +2045,100 @@ function ensureSchemasAgree(base, head) {
 		value: base.$schema
 	});
 }
+/** Identity is a single field, so joining the one-member tuple is joining nothing. */
+const soleField = (parts) => parts.join("");
+const IDENTIFIED_COLLECTIONS = [
+	{
+		field: "symbols",
+		identityFields: ["id"],
+		keyOf: soleField,
+		noun: "id",
+		show: soleField,
+		consequence: "stage 1 pairs Symbols by id and every later stage tracks the base Symbols it has consumed by id, so a repeat leaves one entry out of the diff entirely or classifies its counterpart twice (ir-schema.md §14 #1)"
+	},
+	{
+		field: "components",
+		identityFields: ["id"],
+		keyOf: soleField,
+		noun: "id",
+		show: soleField,
+		consequence: "Component identity is the id, so a repeat hides one entry and can report a change the two revisions do not contain (ir-schema.md §14 #2)"
+	},
+	{
+		field: "dependencies",
+		identityFields: DEPENDENCY_IDENTITY_FIELDS,
+		keyOf: dependencyIdentity,
+		noun: "(from, to, via) triple",
+		show: (parts) => `(${parts.join(", ")})`,
+		consequence: "direction and effect are deliberately outside Dependency identity (§6.2), so a repeat surfaces as an added + removed pair no reader can tell from a real flip (ir-schema.md §14 #13)"
+	}
+];
 /**
-* Top-level shape check. Refuses to enter the 5-stage matcher when a caller hands in an
-* IR-shaped object that is missing one of the collections the matcher requires as an
-* array. Without this, a malformed `baseIR = { symbols: undefined, ... }` would crash
-* deep inside `matchStageId` with `TypeError: undefined is not iterable`, leaving the
-* root cause obscured. Not a full schema validation — just an entry-point smoke test.
+* The two things `buildDiff` needs before stage 1 runs: a Document it can walk, and
+* identities it can key on. diff-algorithm.md §3.7 states the second and why it is checked
+* here as well as at extraction time.
+*
+* Neither half is a full schema validation. A Symbol that reaches stage 1 is an object with
+* a string `id`, because the identity scan reads that much; nothing checks it carries a
+* `fingerprint`, which is `checkIRIntegrity` #20's job and runs when the CLI reads an IR off
+* disk. What this does buy is that a malformed collection is named — `symbols: undefined`
+* used to surface as `TypeError: undefined is not iterable` and `symbols: [null]` as
+* `TypeError: Cannot read properties of null (reading 'id')`, both from inside
+* `matchStageId`, with neither the collection nor the index named.
 */
-function assertIRShape(ir, name) {
-	if (ir === null || typeof ir !== "object") throw new DiffError(`${name} must be an IR object; got ${typeof ir}.`, {
-		code: "ir-shape-invalid",
-		value: name
-	});
-	if (typeof ir.$schema !== "string" || ir.$schema.length === 0) throw new DiffError(`${name}.$schema must be a non-empty schema URL.`, {
-		code: "ir-shape-invalid",
-		value: `${name}.$schema`
-	});
-	for (const field of [
-		"symbols",
-		"components",
-		"dependencies"
-	]) if (!Array.isArray(ir[field])) throw new DiffError(`${name}.${field} must be an array.`, {
+function assertDiffable(ir, name) {
+	if (ir === null || typeof ir !== "object") throw shapeError(name, `${name} must be an IR object; got ${describeValue(ir)}.`);
+	if (typeof ir.$schema !== "string" || ir.$schema.length === 0) throw shapeError(`${name}.$schema`, `${name}.$schema must be a non-empty schema URL.`);
+	for (const collection of IDENTIFIED_COLLECTIONS) assertUniqueIdentity(ir[collection.field], `${name}.${collection.field}`, collection);
+}
+function assertUniqueIdentity(entries, subject, collection) {
+	if (!Array.isArray(entries)) throw shapeError(subject, `${subject} must be an array.`);
+	const firstSeen = /* @__PURE__ */ new Map();
+	for (const [index, entry] of entries.entries()) {
+		const entrySubject = `${subject}[${index}]`;
+		const parts = identityFieldsOf(entry, entrySubject, collection);
+		const key = collection.keyOf(parts);
+		const first = firstSeen.get(key);
+		if (first === void 0) {
+			firstSeen.set(key, index);
+			continue;
+		}
+		const shown = collection.show(parts);
+		throw new DiffError(`${entrySubject} repeats the ${collection.noun} "${shown}" first seen at index ${first}; ${collection.consequence}.`, {
+			code: "ir-identity-collision",
+			value: shown
+		});
+	}
+}
+/**
+* The identity fields of one entry, established as strings on the way out. Reading them is
+* what forces the check: without it a Symbol carrying no `id` has nothing to collide with,
+* passes, and derives a Slice anchored on `undefined` several stages later — which
+* `assertSliceRecordInvariant` reports as `slice-invariant-violated`, the one code the CLI
+* presents as a bug in Aburi rather than in the caller's IR.
+*/
+function identityFieldsOf(entry, subject, collection) {
+	if (typeof entry !== "object" || entry === null || Array.isArray(entry)) throw shapeError(subject, `${subject} must be an object; got ${describeValue(entry)}.`);
+	const parts = [];
+	for (const field of collection.identityFields) {
+		const value = entry[field];
+		if (typeof value !== "string") throw shapeError(`${subject}.${field}`, `${subject}.${field} must be a string; got ${describeValue(value)}.`);
+		parts.push(value);
+	}
+	return parts;
+}
+function shapeError(subject, message) {
+	return new DiffError(message, {
 		code: "ir-shape-invalid",
-		value: `${name}.${field}`
+		value: subject
 	});
 }
+function describeValue(value) {
+	if (value === void 0) return "undefined";
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	return `a ${typeof value}`;
+}
 /**
 * Deterministic ordering of the `symbols[]` output:
 * 1. by status (alphabetical) — pins added/changed/moved sections
@@ -1263,10 +2154,19 @@ function compareSymbolChange(a, b) {
 	return idA < idB ? -1 : idA > idB ? 1 : 0;
 }
 function referenceId(change) {
-	if (change.status === "added" || change.status === "removed") return change.symbol.id;
+	if (change.status === "added" || change.status === "removed" || change.status === "unknown") return change.symbol.id;
 	return change.after.id;
 }
 /**
+* The files a document's scan never analysed, by path, with why.
+*
+* `stats.skippedFiles` is Class B: absent means the writer predates the field, not that
+* nothing was lost. An empty map is the honest answer either way — with no enumeration
+* there is no absence this function can explain, and guessing from
+* `totalFiles > parsedFiles` would attach a reason to whichever Symbols happened to be
+* missing. The CLI says so on stderr instead; a diff cannot invent the list.
+*/
+/**
 * Byte-deterministic serialiser for a DiffResult. Delegates to `@aburi/core`
 * `serializeCanonical` so the sort order, NFC normalisation, and codepoint key sort are
 * shared with the IR side.
@@ -1276,5 +2176,5 @@ function writeCanonicalDiff(diff, options = {}) {
 }
 
 //#endregion
-export { DEFAULT_LINE_FUZZ, DiffError, MAX_LINE_FUZZ, MIN_LINE_FUZZ, assertSliceRecordInvariant, buildDiff, classifyStatus, computeSlices, computeSymbolDelta, diffComponents, diffDependencies, dropDirection, jaccard, jaccardTokens, lastSegment, matchStageDroppedWeak, matchStageGitRename, matchStageId, matchStageLogicFingerprint, matchStageNameSignature, nameSimilarity, ownerSimilarity, signatureSimilarity, sliceAnchor, sliceRecordViolation, tokenizeName, writeCanonicalDiff };
+export { DEFAULT_LINE_FUZZ, DiffError, MAX_LINE_FUZZ, MIN_LINE_FUZZ, assertSliceRecordInvariant, buildDiff, classifyStatus, computeSlices, computeSymbolDelta, dependencySideView, diffComponents, diffDependencies, dropDirection, jaccard, jaccardTokens, lastSegment, matchStageDroppedWeak, matchStageGitRename, matchStageId, matchStageLogicFingerprint, matchStageNameSignature, memberSimilarity, nameSimilarity, ownersAreCompatible, signatureSimilarity, sliceAnchor, sliceRecordViolation, tokenizeName, writeCanonicalDiff };
 //# sourceMappingURL=index.mjs.map