@aburi/diff 0.1.0 → 0.3.0

package/src/match.ts

@@ -1,6 +1,7 @@
-import type { Symbol as IRSymbol, MatchRationale } from "@aburi/types"
+import { trySymbolId } from "@aburi/core"
+import type { Symbol as IRSymbol, MatchRationale, SymbolId } from "@aburi/types"
 import { signatureSimilarity } from "./signature"
-import { lastSegment, nameSimilarity, ownerSimilarity, tokenizeName } from "./similarity"
+import { createNameScorer, lastSegment, type NameScorer, tokenizeName } from "./similarity"
 
 /**
  * A concluded pairing of one base Symbol with one head Symbol, along with the
@@ -19,9 +20,89 @@ export type GitRenameMap = ReadonlyMap<string, string>
 /** 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 = 0.85
+
+/** One candidate pairing and the score that ranks it against the others. */
+interface ScoredPair {
+  base: IRSymbol
+  head: IRSymbol
+  score: number
+}
+
+/** What one sweep settled: the pairings, and the ids each side spent on them. */
+interface Assignment {
+  pairs: readonly ScoredPair[]
+  baseIds: ReadonlySet<SymbolId>
+  headIds: ReadonlySet<SymbolId>
+}
+
+/**
+ * §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: ScoredPair[]): Assignment {
+  candidates.sort(compareCandidates)
+  const baseIds = new Set<SymbolId>()
+  const headIds = new Set<SymbolId>()
+  const pairs: ScoredPair[] = []
+  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: ScoredPair, b: ScoredPair): number {
+  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: readonly IRSymbol[], claimed: ReadonlySet<SymbolId>): IRSymbol[] {
+  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.
  */
 export function matchStageId(
   base: readonly IRSymbol[],
@@ -31,11 +112,11 @@ export function matchStageId(
   remainingBase: IRSymbol[]
   remainingHead: IRSymbol[]
 } {
-  const headById = new Map<string, IRSymbol>()
+  const headById = new Map<SymbolId, IRSymbol>()
   for (const s of head) headById.set(s.id, s)
   const matched: SymbolPair[] = []
   const remainingBase: IRSymbol[] = []
-  const usedHead = new Set<string>()
+  const usedHead = new Set<SymbolId>()
   for (const b of base) {
     const h = headById.get(b.id)
     if (h !== undefined) {
@@ -51,7 +132,9 @@ export function matchStageId(
 
 /**
  * §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
@@ -70,47 +153,78 @@ export function matchStageGitRename(
   if (renameMap === null || renameMap.size === 0) {
     return { matched: [], remainingBase: [...remainingBase], remainingHead: [...remainingHead] }
   }
-  const headById = new Map<string, IRSymbol>()
+  const headById = new Map<SymbolId, IRSymbol>()
   for (const h of remainingHead) headById.set(h.id, h)
-  const matched: SymbolPair[] = []
-  const usedHead = new Set<string>()
-  const remaining: IRSymbol[] = []
+
+  // Collect every base that predicts a given head before choosing, rather than letting the
+  // first one in the array take it. Two files renamed onto one target both predict the same
+  // id, and which of them is the move source should not be a property of the array order.
+  const claimants = new Map<SymbolId, { head: IRSymbol; bases: [IRSymbol, ...IRSymbol[]] }>()
   for (const b of remainingBase) {
     const newPath = renameMap.get(b.source.file)
-    if (newPath === undefined) {
-      remaining.push(b)
-      continue
-    }
+    if (newPath === undefined) continue
     const expectedId = rewriteIdFile(b.id, b.source.file, newPath)
-    const h = headById.get(expectedId)
-    if (h === undefined || usedHead.has(h.id)) {
-      remaining.push(b)
-      continue
-    }
-    matched.push({ base: b, head: h, rationale: "git-rename" })
-    usedHead.add(h.id)
+    if (expectedId === null) continue
+    const head = headById.get(expectedId)
+    if (head === undefined) continue
+    const claim = claimants.get(expectedId)
+    if (claim === undefined) claimants.set(expectedId, { head, bases: [b] })
+    else claim.bases.push(b)
+  }
+
+  const matched: SymbolPair[] = []
+  const usedBase = new Set<SymbolId>()
+  const usedHead = new Set<SymbolId>()
+  for (const { head, bases } of claimants.values()) {
+    const base = lowestId(bases)
+    matched.push({ base, head, rationale: "git-rename" })
+    usedBase.add(base.id)
+    usedHead.add(head.id)
+  }
+  return {
+    matched,
+    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: readonly [IRSymbol, ...IRSymbol[]]): IRSymbol {
+  let lowest = symbols[0]
+  for (const symbol of symbols) {
+    if (symbol.id < lowest.id) lowest = symbol
   }
-  const remainingHeadOut = remainingHead.filter((h) => !usedHead.has(h.id))
-  return { matched, remainingBase: remaining, remainingHead: remainingHeadOut }
+  return lowest
 }
 
-function rewriteIdFile(id: string, oldPath: string, newPath: string): string {
+/**
+ * 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
+ * constructor rather than re-concatenating the parts: `trySymbolId` rejects a rename target
+ * the id grammar cannot express (a backslash path, say) instead of minting an id no head
+ * Symbol can ever equal.
+ *
+ * Returns `null` for that case, and the unchanged id when no rename applies — the caller
+ * treats a null the same way it treats a lookup miss, leaving the pair for stage 3.
+ */
+function rewriteIdFile(id: SymbolId, oldPath: string, newPath: string): SymbolId | null {
   const colon = id.indexOf(":")
   const hash = id.indexOf("#")
   if (colon < 0 || hash < 0 || hash < colon) return id
-  const language = id.slice(0, colon)
   const filePart = id.slice(colon + 1, hash)
   if (filePart !== oldPath) return id
-  const rest = id.slice(hash)
-  return `${language}:${newPath}${rest}`
+  return trySymbolId({
+    language: id.slice(0, colon),
+    file: newPath,
+    qualifiedName: id.slice(hash + 1),
+  })
 }
 
 /**
- * §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.
@@ -124,64 +238,105 @@ export function matchStageLogicFingerprint(
   remainingBase: IRSymbol[]
   remainingHead: IRSymbol[]
 } {
-  const logicMap = new Map<string, IRSymbol[]>()
-  const carryBase: IRSymbol[] = []
-  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: SymbolPair[] = []
+  for (const [logic, heads] of headGroups) {
+    const bases = baseGroups.get(logic)
+    if (bases === undefined) 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: readonly IRSymbol[]): Map<string, IRSymbol[]> {
+  const groups = new Map<string, IRSymbol[]>()
+  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: readonly IRSymbol[],
+  heads: readonly IRSymbol[],
+  scorer: NameScorer,
+): SymbolPair[] {
+  let freeBase = [...bases]
+  let freeHead = [...heads]
   const matched: SymbolPair[] = []
-  const carryHead: IRSymbol[] = []
-  const usedBaseIds = new Set<string>()
-  for (const h of remainingHead) {
-    if (h.dropped || h.fingerprint.logic === ZERO_LOGIC_FP) {
-      carryHead.push(h)
-      continue
+  while (freeBase.length > 0 && freeHead.length > 0) {
+    const lone = freeBase.length === 1 ? freeBase[0] : undefined
+    if (lone !== undefined) {
+      const head = closestNameTo(lone, freeHead, scorer)
+      if (head === undefined) break
+      matched.push({ base: lone, head, rationale: "logic-fingerprint" })
+      break
     }
-    const candidates = logicMap.get(h.fingerprint.logic)
-    if (candidates === undefined || candidates.length === 0) {
-      carryHead.push(h)
-      continue
-    }
-    if (candidates.length === 1) {
-      const only = candidates[0]
-      if (only === undefined) continue
-      matched.push({ base: only, head: h, rationale: "logic-fingerprint" })
-      usedBaseIds.add(only.id)
-      logicMap.delete(h.fingerprint.logic)
-      continue
+    const candidates: ScoredPair[] = []
+    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: { symbol: IRSymbol; score: number } | null = null
-    for (const c of candidates) {
-      const score = nameSimilarity(c.name, h.name)
-      if (best === null || score > best.score) best = { symbol: c, score }
-    }
-    if (best !== null && best.score >= 0.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)
+    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)
   }
-  const finalBase: IRSymbol[] = [...carryBase]
-  for (const bucket of logicMap.values()) {
-    for (const b of bucket) {
-      if (!usedBaseIds.has(b.id)) finalBase.push(b)
+  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: IRSymbol,
+  heads: readonly IRSymbol[],
+  scorer: NameScorer,
+): IRSymbol | undefined {
+  let best: { head: IRSymbol; score: number } | undefined
+  for (const head of heads) {
+    const score = scorer.name(base.name, head.name)
+    if (best === undefined || score > best.score) {
+      best = { head, score }
+      continue
     }
+    if (score === best.score && head.id < best.head.id) best = { head, score }
   }
-  return { matched, remainingBase: finalBase, remainingHead: carryHead }
+  return best?.head
 }
 
 /**
@@ -189,17 +344,35 @@ export function matchStageLogicFingerprint(
  * `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
  *
- * §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
+ * `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 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 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 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.
  */
 export function matchStageNameSignature(
   remainingBase: readonly IRSymbol[],
@@ -209,63 +382,116 @@ export function matchStageNameSignature(
   remainingBase: IRSymbol[]
   remainingHead: IRSymbol[]
 } {
-  type BucketKey = string
-  const buckets = new Map<BucketKey, IRSymbol[]>()
+  const buckets = new Map<string, Bucket>()
   for (const b of remainingBase) {
     if (b.dropped) continue
+    // §3.4.3 — see `saysEnoughToPair`. Read on the base as well as the head: the property
+    // belongs to a pairing, and either end being short is enough to make the score unearned.
+    if (!saysEnoughToPair(b.name)) continue
     const key = bucketKey(b)
-    const bucket = buckets.get(key) ?? []
-    bucket.push(b)
+    const bucket: Bucket = buckets.get(key) ?? { members: [], byToken: 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: SymbolPair[] = []
-  const remainingHeadOut: IRSymbol[] = []
-  const usedBaseIds = new Set<string>()
+  const visitsOf = new Map<Bucket, Int32Array>()
+  for (const bucket of buckets.values()) visitsOf.set(bucket, new Int32Array(bucket.members.length))
+  const scorer = createNameScorer()
+  const candidates: ScoredPair[] = []
+  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 === undefined || bucket.length === 0) {
-      remainingHeadOut.push(h)
-      continue
-    }
-    const headSigNull = h.signature === null || h.signature === undefined
-    if (headSigNull && bucket.every((c) => c.signature === null || c.signature === undefined)) {
-      remainingHeadOut.push(h)
+    if (h.dropped) continue
+    // §3.4.3 tail — `signatureSimilarity(null, null)` is 1.0, so a signature-less head would
+    // score every candidate high on that axis. The bucket key already partitions by
+    // signature nullness, so a signature-less head only ever sees signature-less candidates:
+    // there is nothing here it could legitimately pair with.
+    if (h.signature === null || h.signature === undefined) continue
+    // §3.4.3 — a name of one distinct token scores 1.0 against any other of the same
+    // signature, which is the top of the scale and so above no threshold. See
+    // `saysEnoughToPair`.
+    if (!saysEnoughToPair(h.name)) continue
+    const bucket = buckets.get(bucketKey(h))
+    if (bucket === undefined) continue
+    const threshold = thresholdFor(h.name)
+    // §3.4.0 — the least a member name can score and still leave the threshold reachable,
+    // granting the other two axes in full.
+    const memberFloor = lowestUsefulMember(threshold)
+    // A base is reached once per token it shares, so a head whose postings add up to at least
+    // the whole bucket is not being narrowed by the index — only charged for the overlap.
+    // Every Symbol named `handleRequest` puts the entire bucket under both of its tokens.
+    // Walking the members straight through covers that without the de-duplication, and keeps
+    // the index from costing more than not having one. A bound rather than a promise of the
+    // cheaper branch: `reach` double-counts, so a head can trip it while covering much less.
+    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
     }
-    let best: { symbol: IRSymbol; score: number } | null = null
-    for (const c of bucket) {
-      const score =
-        0.5 * nameSimilarity(c.name, h.name) +
-        0.3 * signatureSimilarity(c.signature ?? null, h.signature ?? null) +
-        0.2 * ownerSimilarity(c.name, h.name)
-      if (best === null || score > best.score) best = { symbol: c, score }
-    }
-    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 visited = visitsOf.get(bucket)
+    if (visited === undefined) 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 !== undefined) collectCandidate(b, h, scorer, memberFloor, threshold, candidates)
+      }
     }
   }
-  const remainingBaseOut: IRSymbol[] = []
-  for (const b of remainingBase) {
-    if (b.dropped) {
-      remainingBaseOut.push(b)
-      continue
-    }
-    if (!usedBaseIds.has(b.id)) remainingBaseOut.push(b)
+  const accepted = acceptInScoreOrder(candidates)
+  return {
+    matched: accepted.pairs.map(({ base, head }) => ({
+      base,
+      head,
+      rationale: "name-signature" as const,
+    })),
+    remainingBase: unclaimed(remainingBase, accepted.baseIds),
+    remainingHead: unclaimed(remainingHead, accepted.headIds),
   }
-  return { matched, remainingBase: remainingBaseOut, remainingHead: remainingHeadOut }
+}
+
+/**
+ * §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: IRSymbol,
+  head: IRSymbol,
+  scorer: NameScorer,
+  memberFloor: number,
+  threshold: number,
+  candidates: ScoredPair[],
+): void {
+  const member = scorer.member(base.name, head.name)
+  if (member < memberFloor) return
+  if (!scorer.ownersCompatible(base.name, head.name)) return
+  const score =
+    0.5 * member +
+    0.3 * signatureSimilarity(base.signature ?? null, head.signature ?? null) +
+    0.2 * OWNER_AXIS_SATISFIED
+  // Filtering here rather than after the sweep keeps the candidate list to the pairings that
+  // could actually be accepted; the threshold belongs to the head, so a pair below it is never
+  // acceptable however the rest of the group resolves.
+  if (score >= threshold) candidates.push({ base, head, score })
 }
 
 function bucketKey(s: IRSymbol): string {
@@ -273,21 +499,138 @@ function bucketKey(s: IRSymbol): string {
   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: number): number {
+  return 2 * (threshold - 0.5)
+}
+
+/**
+ * One `(kind, signatureNullness)` bucket: its base Symbols, and an index from each token a
+ * member name carries to the positions holding it.
+ *
+ * The de-duplication stamp lives beside the bucket rather than in it, in `visitsOf`, and is
+ * sized once the bucket is complete — a half-built bucket is then not representable, and the
+ * stamp cannot be indexed out of range. It is per bucket rather than per head because a head
+ * reaching every base would otherwise allocate a set the size of the bucket once per head,
+ * which is the cross-product the index exists to avoid moved into the allocator.
+ */
+interface Bucket {
+  members: IRSymbol[]
+  byToken: Map<string, number[]>
+}
+
+/**
+ * §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: string): readonly string[] {
+  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 = 0.95
+const DEFAULT_THRESHOLD = 0.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: string): number {
   const tokens = tokenizeName(lastSegment(qname)).length
-  if (tokens <= 1) return 1
-  if (tokens === 2) return 0.95
-  return 0.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: string): boolean {
+  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.
  */
 export function matchStageDroppedWeak(
   remainingBase: readonly IRSymbol[],
@@ -297,39 +640,155 @@ export function matchStageDroppedWeak(
   remainingBase: IRSymbol[]
   remainingHead: IRSymbol[]
 } {
-  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: SymbolPair[] = []
-  const usedBaseIds = new Set<string>()
-  const carryHead: IRSymbol[] = []
-  for (const h of droppedHead) {
-    let best: { symbol: IRSymbol; score: number } | null = 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 = 0.5 * nameHit + 0.5 * fileHit
-      if (best === null || score > best.score) best = { symbol: b, score }
-    }
-    if (best !== null && best.score >= 0.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)
+
+  // Both halves have the same standing, so the two axes are collected rather than consulted
+  // in an order. Both naming the same pairing needs no special handling: each key is sole on
+  // both sides, so neither Symbol carries another pairing and the repeat is a component of
+  // its own, which `bestPairing` takes once.
+  const identified: WeakEdge[] = []
+  for (const keyOf of [nameKey, fileKey]) {
+    identified.push(...pairsIdentifiedBy(bases, heads, keyOf))
   }
-  const carryBase: IRSymbol[] = [
-    ...nonDroppedBase,
-    ...droppedBase.filter((b) => !usedBaseIds.has(b.id)),
-  ]
+
+  const matched = bestPairing(identified)
   return {
-    matched,
-    remainingBase: carryBase,
-    remainingHead: [...nonDroppedHead, ...carryHead],
+    matched: matched.map(({ base, head }) => ({
+      base,
+      head,
+      rationale: "dropped-weak-match" as const,
+    })),
+    remainingBase: unclaimed(remainingBase, new Set(matched.map((edge) => edge.base.id))),
+    remainingHead: unclaimed(remainingHead, new Set(matched.map((edge) => edge.head.id))),
+  }
+}
+
+/** A pairing that one of §3.4.5's two keys identifies. */
+interface WeakEdge {
+  base: IRSymbol
+  head: IRSymbol
+}
+
+/**
+ * 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: readonly WeakEdge[]): WeakEdge[] {
+  const ordered = [...edges].sort(byEndpoints)
+  const atBase = new Map<SymbolId, number[]>()
+  const atHead = new Map<SymbolId, number[]>()
+  for (const [index, edge] of ordered.entries()) {
+    appendTo(atBase, edge.base.id, index)
+    appendTo(atHead, edge.head.id, index)
+  }
+  const adjacent = (index: number): number[] => {
+    const edge = ordered[index]
+    if (edge === undefined) return []
+    const sharing = [...(atBase.get(edge.base.id) ?? []), ...(atHead.get(edge.head.id) ?? [])]
+    return sharing.filter((other) => other !== index)
+  }
+
+  const walked = ordered.map(() => false)
+  const matching: WeakEdge[] = []
+  /** Follow a component from `start`, taking every other pairing along it. */
+  const walkFrom = (start: number): void => {
+    let step = start
+    let take = true
+    while (!walked[step]) {
+      walked[step] = true
+      const edge = ordered[step]
+      if (take && edge !== undefined) matching.push(edge)
+      take = !take
+      const next = adjacent(step).find((other) => walked[other] === false)
+      if (next === undefined) return
+      step = next
+    }
+  }
+
+  // Paths first, from an end — a component walked from the middle would not alternate to a
+  // maximum. What is unwalked afterwards is on a cycle, where every pairing is an equally
+  // good place to start and the lowest-ordered one is the canonical choice.
+  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: WeakEdge, b: WeakEdge): number {
+  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: Map<SymbolId, number[]>, key: SymbolId, index: number): void {
+  const bucket = table.get(key)
+  if (bucket === undefined) 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: readonly IRSymbol[],
+  heads: readonly IRSymbol[],
+  keyOf: (symbol: IRSymbol) => string,
+): WeakEdge[] {
+  const soleBase = soleCarriers(bases, keyOf)
+  const soleHead = soleCarriers(heads, keyOf)
+  const pairs: WeakEdge[] = []
+  for (const [key, base] of soleBase) {
+    const head = soleHead.get(key)
+    if (head !== undefined) pairs.push({ base, head })
+  }
+  return pairs
+}
+
+/** Keys carried by exactly one of `symbols`, mapped to it. */
+function soleCarriers(
+  symbols: readonly IRSymbol[],
+  keyOf: (symbol: IRSymbol) => string,
+): Map<string, IRSymbol> {
+  const sole = new Map<string, IRSymbol>()
+  const shared = new Set<string>()
+  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: IRSymbol): string {
+  return `${symbol.kind}/${lastSegment(symbol.name)}`
+}
+
+function fileKey(symbol: IRSymbol): string {
+  return `${symbol.kind}/${basename(symbol.source.file)}`
 }
 
 function basename(path: string): string {