Skip to content

Diff Algorithm ​

Definition of the aburi diff algorithm, which compares two IRs (base / head) and produces a semantic diff.

References:


1. Purpose ​

The core feature of Aburi's primary use case: "reviewing PRs at semantic granularity". Instead of a line-based code diff, it reports what was added / removed / moved / changed at the Symbol level.

The reviewer's workflow becomes:

  • Scrolling through huge line diffs → eliminated
  • Symbols that are "move only" or "implementation refactor only" are collapsed → out of sight
  • Focus only on places where the "public contract / business logic / side effects" changed

2. Inputs and outputs ​

2.1 Inputs ​

Two IRs (aburi.ir.v1):

  • baseIR: comparison source
  • headIR: comparison target

Both must have matching schema versions (a mismatch is a fatal error).

2.2 Input supply methods ​

bash
aburi diff <base>..<head>             # specify git refs (both regenerated)
aburi diff --base ir-base.json --head ir-head.json  # supply existing IRs directly

For git refs, Aburi internally:

  1. Checks out the base ref and runs aburi scan (IR generation)
  2. Returns to the head ref (or uses a worktree in the first place)
  3. Compares the two IRs

Using a git worktree allows generating the base IR while keeping head intact, so this is the default approach.

2.3 Outputs ​

bash
<output-dir>/diff.json     # diff result (aburi.diff.v1.json schema)
<output-dir>/diff.md       # Markdown projection for pasting into PR comments
<output-dir>/diff.full.md  # diff.md without its size cap, only when --max-bytes shortened it

<output-dir> is --output-dir, then config.output.dir, then .aburi — resolved against the working directory in every case. The filenames are the contract; the rest of this document writes them as .aburi/diff.json / .aburi/diff.md, which is the default run. diff.full.md exists only beside a diff.md whose size cap changed it, and every other run removes it (cli-spec.md §6.3).

A one-line summary goes to stdout; details are referred to the Markdown file.

3. Matching algorithm (5 stages) ​

Pairs up base/head Symbols.

input:  baseIR.symbols, headIR.symbols
output: matchedPairs[], remainingBase[], remainingHead[]

3.1 Stage 1: exact ID match ​

baseById = {s.id: s for s in baseIR.symbols}
headById = {s.id: s for s in headIR.symbols}

for id in keys(baseById) ∩ keys(headById):
  pair = (baseById[id], headById[id])
  matched.push({base: pair[0], head: pair[1], rationale: 'id-match'})
  remove from remainingBase / remainingHead

The most common case. Symbols with no file move and no rename are settled here.

3.2 Stage 2: git rename detection (only when git is available) ​

if git available and ref-based diff:
  renameMap = git diff --find-renames --name-status -z base..head
              → {oldpath: newpath}
  
  claimants = {}
  for sym in remainingBase:
    if sym.source.file not in renameMap: continue
    expectedId = sym.id with old path replaced by renameMap[sym.source.file]
    if expectedId in remainingHead:
      claimants[expectedId].append(sym)

  for (headId, bases) in claimants:
    pair the lowest base.id with headId, rationale: 'git-rename'
    remove from remaining

git's rename detection returns a physical-level mapping, making it the most reliable move-detection mechanism.

-z is part of the contract, not a detail of the invocation. Without it git separates the fields with a tab and renders a path outside printable ASCII the way core.quotePath asks — double-quoted and octal-escaped — so src/a b.ts and src/日本語.ts reach the reader in a shape that matches no sym.source.file, and the move they belong to degrades into the removed + added pair this stage exists to prevent. Under -z each field is NUL-terminated and git's path quoting is bypassed entirely; the record length is decided by the status, since R (rename) and C (copy) carry a second path and every other status carries one. Only R enters the map: a copy's source file is still there, so it is not a move.

The reader has two obligations beyond splitting. It normalizes each path to NFC, because sym.source.file is normalized (toRelativePosix) and the lookup here is a bare Map.get — a repository holding a path decomposed would otherwise build a map that cannot match anything. And it refuses a stream whose records it cannot delimit rather than returning the part it read: a desynced reader produces plausible pairs, and a wrong rename settles a move between two unrelated Symbols, which is worse for this stage than having no hint at all.

git can also succeed while declining to detect renames: over diff.renameLimit it exits 0, warns on stderr, and reports every move as a delete plus an add. That degradation is invisible in the records — they parse, the map is just empty — so the caller warns on any stderr from this invocation.

Two base files renamed onto one target predict the same head id, so the claimants are collected before one is chosen and the lowest base.id is the move source. §3.8 does not apply — there is no score to order by — but the reason for fixing the choice is the one it gives.

3.3 Stage 3: logic fingerprint match ​

For cases git rename could not catch, or when git is unavailable.

group both sides by (sym.kind, sym.fingerprint.logic) (excluding dropped)
  → a group is {bases, heads} that can only pair with each other

for each group:
  if the group's logic names nothing:
    # a value unrelated bodies share (fingerprint.md §4.8): no evidence of identity
    drop every base and head with nameEvidence(name) <= 1      # §3.4.3, inadmissible
  while bases and heads remain:
    if len(bases) == 1 and the group's logic names something:
      # identical logic is proof enough on its own; no similarity test
      pair with the head of highest nameSimilarity, ties to the lower head id
      rationale: 'logic-fingerprint'
      break
    candidates = [(b, h, nameSimilarity(b.name, h.name))
                  for b in bases for h in heads
                  if nameSimilarity >= 0.85]
    accepted = acceptInScoreOrder(candidates)     # §3.8
    if accepted is empty:
      break   # fall through to stage 4 with the group intact
    pair each, rationale: 'logic-fingerprint+name-disambiguation'
    remove them and repeat — a round that leaves one base makes it the lone candidate above

Matching logic fingerprint = same meaning. This catches a good share of "file move without rename" and "file move with a minor refactor".

Except where the logic names nothing. A rule's type and loopKind say what shape a body has, not what it does (fingerprint.md §4.8), so a Symbol with no effect and no rule carrying more — a class, an enum, a constructor, a body that only calls something or returns a literal, a body that is one for loop over calls, one try, a route whose handler is named and whose only logic is the middleware in front of it — shares its logic value with every unrelated body of that shape. That two Symbols share the hash is still true, and the group is keyed on it, but agreement on an axis that says nothing is no evidence that they are one Symbol, as sharing the dropped sentinel is none. Such a group therefore has no lone-candidate branch: every pair in it must reach the 0.85 name bar, and both names must say more than one word. That is the name half of what §3.4.3 skips in stage 4, for the same reason — the name is all there is to go on. The other half, h.signature === null, is not taken: every class carries a null signature, so it would refuse every class this group exists to pair. Without this, a deleted function paired with whatever head of its group was closest by name — an unrelated function, or, before the kind joined the key, an unrelated class added anywhere in the workspace — and --fail-on removed never saw the deletion.

A pair below the bar is now refused whether or not its base was the last one left in the group, where the lone branch used to take it. Which of several bases above the bar takes a shared head is still §3.8's call, so group membership still decides that much.

What this gives up. In such a group a move is settled by its name alone. A class that moved file without git rename information pairs when its name barely changed (similarity ≥ 0.85) and says two words or more: InvoiceRenderer that moved is a move, while Invoice that moved and InvoiceRenderer renamed to InvoicePrinter (similarity 1/3) leave this stage unpaired. An owner gets a second reading, on its members: stage 4 pairs a class whose members all paired into one class, under a name §3.4.6's gate accepts (§3.4.8). So Invoice that moved with a method is a move after all, and InvoiceRenderer → InvoicePrinter is added + removed whatever its methods did, because renderer has no partner. Nothing else takes these back. Stage 4 skips a head with a null signature (§3.4.3), and every class, interface, type alias and enum carries one, as does a const that does not hold a function. DEFAULT_TIMEOUT → REQUEST_TIMEOUT goes the same way as the class rename, and so does a class with no member Symbol to read, or an interface, a type alias or an enum, whose members have none. Stage 4.5 takes only dropped Symbols. A function or method has a signature and gets stage 4 under its own rules, which refuse Cls.getUser → Cls.fetchUser too (member similarity 1/3, under the 0.95 row): with a body that only calls something, that rename was one moved+changed through the lone branch and is added + removed now.

This stage pairs an owner and its members independently. class Invoice { render() } moved file leaves it with Invoice.render paired, since that name says two words, and Invoice unpaired. Stage 4 reconciles the two (§3.4.8).

The kind is part of the group key for the reason it is part of stage 4's bucket key (§3.4.0): a function and a class are never one Symbol, whatever their bodies hash to. It also stops a Symbol whose kind changes while it moves file, on any logic fingerprint, non-empty included: a method extracted into a top-level function, or an enum rewritten as an as const object in another file, is added + removed, because stage 4's bucket carries the kind as well. Within one file the id survives the kind change and stage 1 pairs the two.

Every Symbol stage 3 does not pair is handed to stage 4, a group that missed the bar included. What stage 4 can do with it is stage 4's rule: it skips a Symbol on either side whose name says one word or that has a null signature (§3.4.3), so for those Symbols stage 3 was the last stage to read them by name. An owner among them can still be paired on its members (§3.4.8).

Dropped symbols all share the fingerprint "000000000000", so they would collide massively under the same hash. Dropped-to-dropped matching is excluded from stages 3/4 and handled by a dedicated weak matcher (§3.4.5).

3.4 Stage 4: name + signature similarity (last resort) ​

# Bucket pre-filter (O(N) hash bucketing) suppresses K^2
buckets = group remainingBase by kind
        → { kind: [base symbols] }
        skipping any base with nameEvidence(b.name) <= 1        # §3.4.3, inadmissible
        and then any base with b.signature === null             # §3.4.3, inadmissible

candidates = []
for h in remainingHead:
  if nameEvidence(h.name) <= 1: continue                  # §3.4.3, inadmissible
  if h.signature === null: continue                       # §3.4.3, inadmissible
  bucket = buckets.get(h.kind)
  if !bucket: continue
  threshold = thresholdFor(h.name)                        # §3.4.3
  for b in bucket:
    if not ownersAreCompatible(b.name, h.name): continue  # §3.4.6, the owner gate
    score = (5 * memberSimilarity(b.name, h.name)         # §3.4.1, the last segment
           + 3 * signatureSimilarity(b.signature, h.signature)
           + 2) / 10                                      # §3.4.6, satisfied by the gate
    if score >= threshold:                                # §3.4.3, in exact fractions
      candidates.append((b, h, score))

for (b, h, score) in acceptInScoreOrder(candidates):      # §3.8
  pair, rationale: 'name-signature'

pairOwnersThroughMembers(every pair so far)               # §3.4.8, rationale: 'name-signature'

3.4.0 Bucket pre-filter (mandatory) ​

Stage 4 implemented as O(K^2) drops below practical speed at K=500 (heavy use of the Repository pattern / Zod schemas). As a bucket pre-filter, hash-partition by kind and evaluate each head only within its kind's bucket. A Symbol with no signature never reaches a bucket (§3.4.3).

That key alone is not a partition of anything. A directory rename with no git rename information — the §9.4 plugin-difference and §11.5 shallow-clone situations — leaves every method of the codebase in one bucket, so "a few dozen per bucket" describes the easy case rather than the hard one. Measured at 4000 symbols in one bucket, stage 4 took 64 s against §8.3's 2 s target when that was reported. Two later changes to the per-comparison cost — a per-pass token memo, and settling candidates in one sweep rather than per head — brought it to 14 s, which is what the table below measures against.

So within a bucket the bases are indexed by the tokens of their member names, and a head is offered only the bases sharing one:

for each base in the bucket:
  for each token of tokenize(lastSegment(base.name)):
    index[token].append(base)

for each head:
  candidates = the union of index[token] for the head's member tokens

This costs no recall. The composite is 0.5 * member + 0.3 * signature + 0.2, the lowest row of §3.4.3's table is 0.85, and the signature axis is worth at most 0.3 — so member >= 0.7 for any pairing that survives, whichever row applies. A Jaccard that high is a Jaccard above zero, and a Jaccard above zero is a shared token. Nothing outside the union could have paired.

The same bound, row by row, is the member floor below: (10 × threshold − 5) / 5, which is 7/10 at the 0.85 row, 9/10 at 0.95 and 1 at 1.0. It is a fraction compared as exactly as the score (§3.4.3), so a pairing at the floor with an identical signature, 7/10 and 1, reaches the score and pairs; summed in floating point it passed the floor and then fell a rounding error short of 0.85.

Two details the rule needs:

  • A member name with no tokens is indexed under a key of its own. Foo.Bar. has an empty last segment and two tokens in its qualified name, so §3.4.3 admits it, and two such Symbols score 1.0 on an axis comparing two empty sets. Without a key they would be unreachable — a pairing lost to the index rather than to the score.
  • A head whose postings cover the bucket is walked over the bucket directly. 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 — only charged for the overlap: every Symbol named handleRequest puts the entire bucket under both of its tokens. This is a bound, not a promise of the cheaper branch, since the sum double-counts and a head can trip it while covering far less than the bucket. What it guarantees is that the index never costs more than not having one.

The member floor is read before §3.4.6's gate, and on a corpus of varied names that is worth as much as the index. The floor is one Jaccard over token sets the pass already holds; the gate splits both owners into segments, tokenises each and runs an augmenting-path matching. It is the only early exit — the gate short-circuits internally on identical owners and on first segments that cannot correspond, and hoisting either into the loop buys nothing, because the gate reaches them on the same two lookups.

The reverse order suits the opposite corpus, where the member names are identical and the owners differ: there the gate is the selective test and the floor refuses nothing. Neither order dominates, and this one favours the case the index cannot already help with.

Measured on a directory rename with an edited body, no git rename information, everything in one bucket:

beforeafter
4000 symbols, varied names14.0 s1.3 s
4000 symbols, every member name identical13.4 s13.5 s

The second row is the shape the index cannot help with — one token, shared by everything — and the point of the fallback is that it does not make it worse.

3.4.3 Thresholds by name token count ​

To avoid false positives on short names (1–2 token names like getUser vs getUsers), the threshold is adjusted by the token count of the head's last name segment.

The symbol kind does not enter into it. This section was headed "per-symbol-kind thresholds" and its pseudocode took a kind parameter that neither it nor the implementation ever read; §3.4.6 then quoted "for kind=method the threshold is 0.85" for a two-token name the table gives 0.95. Kind already does the work it can do in §3.4.0's bucket key, which stops a class body from being compared against a function at all.

thresholdFor(headName):
  tokenCount = tokenize(lastSegment(headName)).length
  if tokenCount <= 1:
    return 1.0                  # an exact match on both remaining axes
  if tokenCount == 2:
    return 0.95                 # strict (e.g. 'getUser' vs 'getUsers' scores 1/3 → does not pass)
  return 0.85                   # default

The comparison is exact. Every axis is a ratio of two counts — shared tokens over all tokens on the member axis (§3.4.1), agreeing positions over positions and shared throws over all throws on the signature axis (§3.4.2) — and every row is a fraction: 1, 19/20, 17/20. So the composite is kept as one fraction, (5 × member + 3 × signature + 2 × 1) / 10 over those counts, and score >= threshold is decided by cross-multiplying integers. A score equal to its row therefore pairs, however it is made up.

Summed in floating point, such a score could land a rounding error to either side of its row, so the nominal >= behaved as > for some of them. 0.5 * 3/4 + 0.3 * 11/12 + 0.2 and 0.5 * 7/10 + 0.3 + 0.2 are both 0.8499999999999999: a member that gained a fourth token with one of four inputs retyped was added + removed, as was a pair at the member floor with an identical signature, while 0.5 + 0.3 * 1/2 + 0.2 came out 0.8500000000000001 and paired.

The integers are products of at most four counts — the member names' token union, the input count, the output count and the throws union — and a few small constants, so a double holds them exactly while those four multiply to under 1.5 × 10^13: nearly two thousand of each at once. Stage 3's 0.85 bar (§3.3) needs none of this. Its score is a single quotient of two counts, and a double rounds such a quotient to the same value as 17/20 only when it is 17/20. Nor does the admissibility gate below, though nameEvidence(name) > 1 is a sum of fractions: every term is a multiple of 1/6, so no sum falls between 1 and 7/6, and each combination that makes exactly 1 sums to exactly 1.0.

1.0 is the top of the scale and a reachable score: an identical member name and signature, past §3.4.6's gate, give (5 + 3 + 2) / 10, which is 1. The comparison is score >= threshold, so the first row pairs an unchanged UserRepo.get that moved file with an edited body — which stage 3 does not catch. The owner need not be identical, only compatible, so UserRepo.get → UserRepos.get reaches it too. Making it > would empty the row rather than tighten it.

Symbols stage 4 does not read ​

Two kinds of Symbol are skipped before any threshold applies, because for them a high score means the evidence is missing rather than that the two names resemble each other. Neither is expressible as a threshold, and one of them wants a bar above the top of the scale:

if nameEvidence(s.name) <= 1:       skip the Symbol, either side, leave for added/removed
if s.signature === null:            skip the Symbol, either side, leave for added/removed

The name is read first, so a Symbol that fails both is skipped for its name, which is what §3.4.7 traces.

A null signature makes signatureSimilarity(null, null) return 1.0, so two signature-less Symbols would pair on their names alone. A head with no signature is the case the rule exists for. A base with none could only meet a head with a signature, where the axis is 0 and the composite at most 0.7, under every row of the table — so the rule reads both sides at no cost to recall, and a signature-less base stays out of the buckets. An owner skipped here is read again by §3.4.8, on its members rather than its name.

A one-token qualified name is the whole of what §3.4 has to read about that Symbol's identity. main supplies one word and an empty owner, so a top-level main(x: string): void scores 1.0 against any other top-level main(x: string): void and two unrelated CLI entry points are reported as one moved+changed — which --fail-on moved gates on. The first threshold row was written to prevent exactly this and could not, because 1.0 is the top of the scale.

The measure is over the whole qualified name — the member and its owner together, which is everything §3.4 knows a Symbol by — and not over the last segment alone, which is what thresholdFor reads. UserRepo.get supplies three and goes on pairing though its last segment supplies one; the threshold row that still governs it is the one above. Tokens are deduped (§3.4.1), so Main.main supplies one and is skipped: the formula cannot tell it from a bare main.

It is nameEvidence (§3.4.1) and not the distinct-token count. The two agree on a name whose words the tokeniser can find, and part company on a run it cannot segment, where the measure reads the run and not the token: ユーザー.取得 is two tokens and 1 1/6 words. The two rules in this section therefore read the same name differently on purpose: thresholdFor asks how coarse the Jaccard will be, which really is the token count, and this rule asks how much the name says, which is not.

The rule reads both sides, because the property belongs to a pairing rather than to one end of it.

It once read the head alone, on an arithmetic licence: a one-token name on either side capped the score at 0.5 * 0.5 + 0.3 + 0.2 = 0.75, under the table's lowest row, so a one-token base was unreachable without a check of its own. That held while the name axis was a Jaccard over the whole qualified name. §3.4.6's gate moved the axis to the last segment, and the ceiling went with it: Main.main is one deduped token, it clears the gate against Mains.main by inflection, and their member names are identical, so the pair scores 1.0. Reading both sides costs one test per Symbol and needs no licence.

What this gives up. A one-token name that moved file and changed body is now added + removed where it was one moved+changed. That band is narrow: stage 1 takes it if the id survives, stage 2 if git recorded the rename, stage 3 if the logic fingerprint is unchanged and names something (§3.3). What is left is a cross-file move git did not record, with an edited body — and for a name of one word, that pairing was never better than a guess.

The band was once much wider on codebases with non-Latin identifiers, because the rule read the distinct-token count and §3.4.1's tokeniser reads ユーザー情報を取得する as one token however much it says. That refused it on the same footing as main, where the proxy is simply wrong: two unrelated Symbols do not carry that name by coincidence. nameEvidence is what closed that, and it closes it for the reason rather than for the script — a name of one word is still refused whatever wrote it. главная and مستخدم alongside main; and, since the measure is a floor on words rather than a count of characters, メイン and 초기화 and ハンドラー alongside the same three.

What a morphemic name gets back is narrower than the rule's own band, and the reason is the threshold table rather than this rule. Such a name is one token, so thresholdFor hands it EXACT_MATCH_ONLY and only an identical signature past a compatible owner reaches 1.0: ユーザー情報を取得する moved file with an edited body is a pair, and the same move with one added input is not, where getUserInformation — two tokens in its last segment — has the 0.95 row to fall back on. Admissibility opens the door; the row still decides who comes through.

Stage 3 asks the same of a name only where the logic names nothing (§3.3). An identical logic fingerprint that names something — a guard, a returned expression, an effect — is proof on its own and does not ask the name to carry anything, so a main with such a body that moved file unchanged is still a move. A main whose body only calls something is added + removed: its fingerprint is shared with every other such body, and its name says one word.

3.4.4 Tuning via configuration ​

config.diff.nameSignatureThreshold (default: null = automatic, by the token count of §3.4.3's table) overriding the global threshold is planned — see the roadmap. Currently the threshold is automatic only.

3.4.5 Stage 4.5: dedicated weak matcher for dropped ​

Dropped symbols have zero fingerprints and cannot use stages 3/4. To catch dropped symbols that moved in environments without git rename, a lightweight dropped-only matcher runs after stage 4. Two signals remain: the trailing segment of the qualified name, and the file basename. Either one alone is enough to pair.

A signal counts only when it identifies a Symbol — when exactly one dropped base and one dropped head of that kind carry the key:

for keyOf in [ (kind, lastSegment(name)), (kind, basename(source.file)) ]:
  for key carried by exactly one dropped base AND exactly one dropped head:
    candidates.append((that base, that head))  # both keys may name the same pairing

for (b, h) in the largest subset of candidates that pairs each Symbol at most once:
  pair, rationale: 'dropped-weak-match'

As a result, a change such as "only renamed the directory of DTO files" is recorded as moved:10 rather than droppedAdded:10 / droppedRemoved:10.

Why identifying, and not just matching. A key several Symbols carry names a group, and a group is not a pairing. index.ts is the most common filename in a TypeScript monorepo, so a bare basename match paired every dropped Symbol of one kind under one with every other — at a score they all tied on, which left the choice among unrelated classes to the tie-break. Those pairings land in summary.moved, which --fail-on moved gates on, so the false-positive budget this section grants itself was being spent on the default case rather than an unusual one. Requiring the key to identify costs the pairings where the surviving signal was ambiguous, which are the ones with nothing to distinguish the candidates by — the fingerprint is zeroed, so there is no second opinion to consult.

The candidates carry no weight, so §3.8 does not apply. Every candidate here is worth the same: a pairing both halves identify cannot be contested — both keys are sole on both sides and point at each other, so neither Symbol appears in any other candidate — and the case that remains, one base offered different heads by the two halves, is one the 0.5-per-half scale scored equally anyway. §3.8's sweep settles conflicts by score, and its licence to be greedy is that it never passes over the best available pairing; with no score there is no best, and it would drop one identified pairing for another over nothing but the id it sorts under. Three identified pairings over four Symbols where two can hold is not a hypothetical.

So this stage takes a maximum matching. Each axis identifies a Symbol at most once, so a Symbol carries at most two candidates and the set is the union of two matchings — a disjoint union of simple paths and even cycles, where alternate candidates along each component are a maximum matching and walking from a fixed end makes the choice among them canonical. That is also what bounds the work: at most one pairing per identifying key, two axes, against the cross-product a shared basename used to produce.

"Exactly one" is counted over what reaches this stage, not over every dropped symbol in the Document. Stages 1 and 2 have already taken theirs, so a key they emptied out identifies again. That is the intended reading — the question is which leftover a key picks out, and the stage is handed the leftovers — but it is also the ordinary way a shared index.ts still pairs unrelated symbols: three dropped classes under one, two of them unchanged and matched by id, and the basename identifies the two that remain.

So there is still a false-positive risk — that case, and two unrelated classes that are genuinely the sole carriers of one basename — but dropped symbols are outside the IR's primary field of view, so the impact is small.

3.4.1 nameSimilarity ​

Token split (camelCase / snake_case / . / ::) → Jaccard similarity. Levenshtein is too sensitive and was rejected.

tokenize("InvoiceService.createInvoice") = ["invoice", "service", "create", "invoice"] (lowercase, dedupe)
jaccard(A, B) = |A ∩ B| / |A ∪ B|

The camel boundary is Unicode case. The split tests \p{Ll}, \p{Lu}/\p{Lt} and \p{Nd} rather than the ASCII ranges, so a hump is a hump in every cased script. What no case rule can find is a boundary in a script that has no case, so such a name comes back whole:

tokenize("получитьПользователя")  = ["получить", "пользователя"]   (2 — the hump registers)
tokenize("ユーザー情報を取得する") = ["ユーザー情報を取得する"]     (1)
tokenize("获取用户信息")           = ["获取用户信息"]               (1)
tokenize("مستخدم")                = ["مستخدم"]                     (1 — caseless, and one word)
tokenize("ユーザー.取得")          = ["ユーザー", "取得"]           (2 — a separator still splits)
tokenize("UserRepo.取得")          = ["user", "repo", "取得"]       (3 — the Latin half splits)

Jaccard is unharmed by this: two names that tokenise whole still score 1.0 against each other and 0 against anything else, which is the right answer for identical and for unrelated names alike. The count is likewise the right measure of the Jaccard's granularity, which is what §3.4.3's threshold table reads: one token against a name of n scores 0 or 1/n, so nothing but an identical single token reaches 1.0, and the composite tops out at 0.5 × 0.5 + 0.3 + 0.2 = 0.75 below that — under every row of the table. A one-token name is therefore all-or-nothing on its name axis whatever script wrote it, which is what the first row is calibrated to.

What the count is not is a measure of how much a name says. 获取用户信息 is one token and a phrase. §3.4.3's admissibility rule is the one place that asks that question, and it reads nameEvidence instead:

nameEvidence(qname) = (number of distinct tokens holding anything else)
                    + (distinct Han characters)      / 3
                    + (distinct kana and Hangul)     / 6

over the NFC form of the name; combining marks are not counted

A token of a script that writes its word boundaries is one word however long it runs, because length is not what makes a name coincidental: initialize is ten characters and one word, exactly as main is four and one. A run of a script that writes no boundary cannot be segmented, so it is counted instead, and the divisor is the longest a single word of that script runs. Han writes a morpheme per character and spells its longest single words in three — 初期化, 数据库, 处理器. Kana and Hangul write a syllable per character and take more: ハンドラー is one word in five, コンピュータ and 데이터베이스 one in six.

The quotient is therefore a floor on the number of words in the run, which is what the rule needs — it admits only when the run cannot be a single word. It is fractional where a run is: 取得 is two thirds of a word and getUser is exactly 2.

Script_Extensions rather than Script so that a character belonging to a run comes with it. U+30FC, the prolonged sound mark in ユーザー, is a modifier letter of script Common; read as foreign it would count as a word of its own, and ユーザー — three kana and two marks — would be admitted on the strength of them. Characters are counted once each, as tokens are, so 取得取得 says what 取得 says. NFC first, so a decomposed ガ is the one character it spells and Hangul jamo are the syllable they compose.

An alphabetic script with no case is deliberately not in either bucket. Its characters are letters rather than morphemes or syllables, so a run of them is one word and the token count was already right; a multi-word identifier in such a script writes a separator, and the tokeniser splits on it (مستخدم.احصل → 2).

nameEvidence("main")                = 1       nameEvidence("获取用户信息")           = 2
nameEvidence("initialize")          = 1       nameEvidence("ユーザー情報を取得する") = 2 1/3
nameEvidence("مستخدم")              = 1       nameEvidence("사용자정보조회")         = 1 1/6
nameEvidence("Main.main")           = 1       nameEvidence("получитьПользователя") = 2
nameEvidence("初期化")              = 1       nameEvidence("UserRepo.取得")          = 2 2/3
nameEvidence("ハンドラー")          = 5/6     nameEvidence("ユーザー.取得")          = 1 1/6

Six is the longest word the measure assumes, not the longest there is: アプリケーション is one word in eight and is admitted as though it were more. The constants sit where they do because a name of seven syllables is more often a phrase (사용자정보조회) than a loanword, and a wrong pairing costs less than the band of real moves a higher divisor would refuse.

3.4.6 The owner gate (R-8: avoiding same-name method collisions) ​

Two things must hold at once. A method whose class was renamed (UserRepo.getUser → UsersRepository.getUser) must pair, and a same-named method of a different class (AdminRepo.getUser) must not.

The owner is therefore a gate, not a term in the score: a pair whose owners are incompatible is never scored for pairing. §3.4.7's trace scores one only to decide whether to name it.

ownerOf(qname):
  if '::' in qname: return qname[:first index of '::']    # the Class:: portion of a static method
  if '.'  in qname: return qname[:last index of '.']      # the nested.namespace.Class portion
  return ''
  # 'Class::method' → 'Class'
  # 'A.B.C.method'  → 'A.B.C'
  # 'topLevel'      → ''   (empty)

ownersAreCompatible(baseName, headName):
  baseOwner = ownerOf(baseName)
  headOwner = ownerOf(headName)
  if baseOwner === '' && headOwner === '': return true    # both top-level: one shared scope
  if baseOwner === '' || headOwner === '': return false   # different depths
  if baseOwner === headOwner: return true                 # the common case

  # an owner is a path, so it corresponds segment by segment; within a segment every token on
  # each side needs a distinct partner on the other, under sameWord
  baseSegments = baseOwner.split('.')
  headSegments = headOwner.split('.')
  if len(baseSegments) != len(headSegments): return false
  return all(seg == cnt or perfectMatching(tokenize(seg), tokenize(cnt), sameWord)
             for seg, cnt in zip(baseSegments, headSegments))

sameWord(a, b):
  return a == b or inflectionOf(a, b)     # user/users, entity/entities. Nothing else.

As a result:

pairownersverdict
UserRepo.getUser vs UserRepos.getUserrepo -> reposcompatible, scored 1.0, pairs
EntityStore.findById vs EntitiesStore.findByIdentity -> entitiescompatible, pairs
Users.UserRepo.getUser vs Users.UserRepos.getUsersegment by segmentcompatible, pairs
UserRepo.getUser vs AdminRepo.getUseruser has no partnerrefused
RepoManager.load vs ReportManager.loadrepo is not report inflectedrefused

Why a gate and not a weight. The previous design added 0.2 * jaccardTokens(baseOwner, headOwner) to the score, and could satisfy neither requirement.

It could not pair the rename, because the owner was counted twice. §3.4.1's name axis is a Jaccard over the whole qualified name, so a renamed owner already depressed the name term, and the owner term then charged for the same difference again: UserRepo.getUser vs UsersRepository.getUser scored 0.5*0.4 + 0.3 + 0.2*0 = 0.5, not the 0.9 this section claimed. End to end, renaming a class and keeping three methods with edited bodies reported added: 3 / removed: 3.

And it could not refuse the collision, because a weight cannot outvote a perfect member name and signature. Reading the name axis on the last segment fixes the double count but inverts the ordering — AdminRepo shares the repo token where UsersRepository shares none:

pair, both .findByIdowner Jaccardw=0.2w=0.3threshold
UserRepo vs AdminRepo — must refuse0.3330.86670.80000.85
UserRepo to UsersRepository — must pair00.80000.70000.85
UserRepoService vs AdminRepoService — must refuse0.50.90000.85000.85

The collision outscores the rename at either weight, and the three-token collision passes at both. There is no weight at which "different class" reliably loses, because the quantity being weighed is not evidence of degree.

Past the gate there is no owner left to grade, so the owner axis is satisfied in full and 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.

Why inflection and nothing looser. A prefix test is the obvious way to admit repo -> repository, and it cannot be made to work: it admits repo/report, cache/cached, con/controller — distinct classes, which is the collision this section exists to refuse. Nor is there a threshold to find, because the two populations interleave:

dicelevenshtein
accept UserRepo/UsersRepository0.5717
refuse RepoManager/ReportManager0.8182
accept Repo/Repository0.5006
refuse CacheStore/CachedStore0.8421

The renames to accept score lower than the collisions to refuse, on both measures. 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 rename a plain equality test misses most often — a class pluralised in place.

What the gate costs. Three things, all falling through to added + removed, which is R-8's preferred direction of error:

  • The abbreviation family. UserRepo -> UsersRepository, this section's original headline example, no longer clears the gate. That is the price of refusing repo/report, which no rule over the two strings alone can tell apart.
  • An added or dropped token. UserRepo and UserRepoV2 are two classes rather than one renamed; an added token is as much evidence of a sibling as of a rename.
  • A changed nesting depth. A rename changes what a class is called, not where it lives, so Services.UserRepo and UserRepo are different scopes.

The evidence that would settle the first is not in the strings. The owner is itself a Symbol in the IR, so "was this class paired as a rename" is a question the stage could ask rather than guess at. §3.4.8 asks the converse, which owner a class's members paired into, and still puts the two owner names through this gate, so the abbreviation family stays added + removed: what the members say does not overrule what the names refuse. Admitting a method because its class was paired would mean stage 4 consuming its own output in the other direction, and that, not a looser string rule, is the direction a future revision should take.

3.4.2 signatureSimilarity ​

null + null → 1.0 null + non-null or the reverse → 0.0 Both non-null →

  • match ratio of input types (order-sensitive)
  • match ratio of output types
  • set match ratio of throws (order-insensitive) averaged.

3.4.7 What stage 4 says about a refusal ​

Three of the rules stage 4 refuses on are traced: a Symbol whose name says too little and a Symbol with no signature (both §3.4.3), and a pair whose owners do not correspond (§3.4.6). So are three of the reasons §3.4.8 leaves an owner unpaired although its members paired. The report says nothing about why a Symbol was left unpaired — the gate refuses UserRepo → UsersRepository deliberately, but a reviewer looking at the churn has nothing pointing them here. So each refusal is written to the run's Logger at debug, when DiffInput.logger is given, as one line naming the Symbol, or both Symbols of the refused pair, and the rule:

diff/stage4: ts:src/a.ts#render is not compared by name: its name says too little to pair on
diff/stage4: ts:src/a.ts#buildConfig is not compared by name: it has no signature, and a name alone does not pair
diff/stage4: ts:src/a.ts#UserRepo.findUser and ts:src/b.ts#UsersRepository.findUser are not paired: their owners do not correspond
diff/stage4: ts:src/old.ts#Invoice is not paired through its members: they did not all pair into one owner
diff/stage4: ts:src/old.ts#Invoice and ts:src/new.ts#Receipt are not paired through their members: their names do not correspond
diff/stage4: ts:src/a.ts#Invoice and ts:src/c.ts#Invoice are not paired through their members: the head also holds members paired from elsewhere
  • A Symbol line is written for every non-dropped Symbol either rule turns away and §3.4.8 does not pair, including one with nothing to pair with, and stands for one entry of the report: added or removed, or unknown where the other side skipped its file (§3.5.1). A Symbol that fails both rules is traced once, for its name, which §3.4.3 reads first. The lines are written once §3.4.8 has settled the owners, because an owner it pairs is an entry of neither kind.
  • A gate line is written after the pairings are chosen (§3.8), for a pair whose base and head both reach stage 5 unpaired and which cleared its row's threshold. So each line names two Symbols the report lists separately, which only the gate kept from being a candidate. A pair either of whose Symbols paired elsewhere is not traced, nor one that scored below its row, which is a judgement on the evidence rather than a rule. The line is per pair, so N such bases and M such heads write up to N × M lines.
  • An owner line is written for a base owner whose members paired and which §3.4.8 refused, for one of three of its rules: the members did not all pair into one head owner; the two owners' names do not correspond, because the gate refuses them or one sits a scope deeper than the other; or the head owner also holds members paired from another owner, or from none. Every Symbol such a line names reaches stage 5 unpaired, and each keeps its Symbol line too, since stage 4 did not read its name either. The other refusals are not traced: a head owner that paired elsewhere, as for the gate line, or that §3.4.8 does not read; and one of another kind, as for the bucket key below.

The kind in §3.4.0's bucket key is a rule too and is not traced: a function and a class are never one Symbol (§3.3), so there is no near miss for a line to explain.

The channel is a diagnostic one: nothing it writes reaches the diff result or aburi.diff.v1.json, and buildDiff's answer is the same with and without a logger. Tracing the gate walks the buckets again for the Symbols left unpaired, so it runs only when a logger is given, and aburi diff gives the matcher one only at --log-level debug or ABURI_LOG_LEVEL=debug, where the lines show on stderr.

3.4.8 Owners paired through their members ​

Stage 3 reads a class by its name alone, and stage 4 does not read it at all (§3.4.3). So class Invoice { render() } that moved file, with no git rename information and a body that names nothing, reached stage 5 as added Invoice and removed Invoice beside moved Invoice.render: --fail-on removed and --fail-on moved both fired on one unchanged class. A class whose name was pluralised in place went the same way while §3.4.6's gate paired each of its methods. The pair the names cannot settle is settled by the members. An owner is itself a Symbol, and where its members went is already decided by the stages before, so the question can be asked rather than guessed:

after stage 4's pairs are accepted (§3.8):
  pairs = every pair of stages 1 to 4
  ownerOf(s) = the nearest Symbol of s's own document whose qualified name s's extends,
               in s's file    # `api.v1.get` belongs to `api`: the object between has no Symbol
  depth(s) = the segments of s's qualified name, split at each '.' and '::'

  for b in the unpaired bases with a null signature, not dropped,
           deepest qualified name first, then by id:
    members = the pairs p with ownerOf(p.base) == b
    if members is empty: continue                       # nothing to go on
    if some ownerOf(p.head) differs, or is none: refuse # its members went more than one way
    h = that head owner
    if h is paired, dropped or has a signature: refuse
    if h.kind != b.kind: refuse                         # §3.3: a class is never a namespace
    if depth(h) != depth(b): refuse                     # §3.4.6: a scope deeper is another scope
    if not ownersCorrespond(b.name, h.name): refuse     # §3.4.6's gate, on the owners' own names
    if some pair p with ownerOf(p.head) == h has ownerOf(p.base) != b: refuse
                                                        # h also took members from elsewhere
    pair (b, h), rationale: 'name-signature', throughMembers: len(members)
    pairs.append((b, h))                                # evidence for ownerOf(b) in its turn

The Symbols it reads are the ones stage 4 skips for a null signature, which is every owner a TypeScript document has: a class, a namespace, an object literal a binding holds. One with a signature is stage 4's to score, whatever it made of the name, and a dropped one is stage 4.5's. An interface, a type alias or an enum has no member Symbols (ir-schema.md §3.2), so there is nothing for it to be paired on. A one-word name is no bar: it is what stage 3 could not read, and the members are the evidence here, not the name.

Every member, both ways. The members of b must all have gone into h, and every member h received must have come from b. A class split into two (one method into Printer), a namespace function that moved to the top level, two classes merged into one, and a namespace that took in a top-level function beside its own each have no single counterpart, and pairing one of them would hide the other half of the change. A member that is added or removed says nothing about where its owner went and does not count either way, so a class that moved, losing one method and gaining another, still pairs on the method that came with it. A method that became a top-level function is one of those: it changed kind, which no stage pairs across (§3.3).

The gate still applies. A member's pair can rest on its body alone: stage 3's lone branch pairs a method whose logic names something without reading its owner. Without the gate, Invoice.render moving unchanged into Receipt would make Invoice and Receipt one class. The gate is asked of the owners' own qualified names, as stage 4 asks it of a member's owner, so every pair it admits is one stage 4 would have admitted for their members: UserRepo → UsersRepo pairs, UserRepo → UsersRepository does not.

Nested owners, in one pass. An owner is settled after every owner nested in it, so a pair this loop makes is evidence for the next owner out: namespace Billing → Billing pairs on Billing.Invoice → Billing.Invoices, which paired on its method. An owner always has a lower depth than its members, so its evidence is complete by its turn. Two owners pair only at one depth, so the head side's is complete too: an owner this loop pairs into a member of h is deeper than h, and so than b, and had its turn first. The depth is not the gate's to judge. The gate splits an owner's path at . alone, so a static nested Billing::Invoice is one segment whose tokens correspond to a top-level BillingInvoices; counted at :: too, it is a scope deeper, which §3.4.6 makes another scope. Without the check, the pair (BillingInvoices, Billing::Invoice) could come up beside (Billing, Billing) and give the head Billing a member from outside its partner, and refusing one of the two would follow which file's id sorts first. With it, the outcome is the same in any layout. There is no choice to make among candidates otherwise: b has one target, and two bases that target one head both fail the reverse check, so no score is needed.

What the entry says. The rationale is name-signature, because stage 4 made the pair, and the entry carries throughMembers, the number of member pairs it rests on. A rationale of its own would say this more directly, but adding a MatchRationale value is breaking (§10.1) and --fail-on readers key on the values there are. The count is an optional scalar written only on such a pair, and a writer that predates it never paired an owner this way, so its absence is unambiguous (§10.1). The members are listed as entries of their own, so a count is enough to send a reader to them; a list would be an array, which §10.1 would have every moved entry carry.

What it does not do. It never pairs a member because its owner was paired; that is the direction §3.4.6 leaves to a future revision. A member's pair is as strong as the stage that made it, so an owner paired on one method stage 3 paired by name carries that pairing's risk, and the count says how much the pairing stands on. And it reads only what stages 1 to 4 decided: stage 4.5's weak matches of dropped Symbols are not evidence, because that stage's false-positive budget (§3.4.5) is granted on the premise that its pairs stay outside the IR's primary field of view.

What it costs is one map per side from id to Symbol, a walk up a qualified name for each member pair, and a sort of the unpaired owners.

3.5 Stage 5: the remainder is added / removed / unknown ​

Symbols not paired by this point are finalized:

  • remainingHead → status: added
  • remainingBase → status: removed
  • …unless the other document never analysed the file the Symbol lives in, in which case the status is unknown (§3.5.1)

A removed entry also names the head Symbol it duplicated, when one holds its body (§3.5.2).

3.5.1 unknown: the other document could not look ​

A leftover Symbol whose source.file appears in the other document's stats.skippedFiles[] is not evidence of an addition or a deletion. That document did not read the file, so it cannot say whether the Symbol is there. The entry carries absentFrom (base or head — the document that lost the file, so head reads as "this may still exist" and base as "this may not be new") and the skip reason, which is what decides the reader's next move: parse-timeout depends on how loaded the machine was and usually clears on a re-run, while parse-failed, extraction-failed, over-size and unroutable describe the file and clear only when something is fixed.

Four properties this rests on:

  • Read after all five stages, never before. A Symbol that moved out of a lost file into a file the other document has is matched by stage 3 or 4, and that document holds real evidence for it — it is moved. Filtering the base list up front would throw that answer away.
  • Both directions. A file fine at head and withdrawn at base makes phantom added entries exactly as a file withdrawn at head makes phantom removed ones.
  • Across a git rename. A leftover names its file the way its own document does, and when git renamed that file between the revisions the other document recorded it under the other name. So the lookup is the leftover's own path first, then the path the rename map gives it on the other side: src/big.ts → src/billing.ts with src/billing.ts skipped at head leaves the base Symbols of src/big.ts unknown, not removed, and the mirror case is unknown with absentFrom: "base", not added. Such an entry carries lostPath, the name the absent document skipped the file under: that is where its skip record is, and symbol.source.file is a path that document does not have, so naming it would send the reader to raise a size cap or fix a parse for the wrong file. lostPath is left out whenever the two names agree, on the terms §10.1 gives an optional scalar. Without the map (--base/--head IR files) only the first lookup is possible. A map that renames two base paths onto one head path — git writes none, but buildDiff accepts any — is read in path order, so which record answers does not depend on the order the map lists them in.
  • dropped leftovers keep their counters. They produce no symbols[] entry on either side today and nothing gates on them, so they stay in droppedAdded / droppedRemoved rather than becoming unknown entries where there were none.

When the other document omits stats.skippedFiles entirely — written before the field existed — nothing changes: the leftovers keep added / removed. The list cannot be inferred from totalFiles > parsedFiles without attaching the doubt to whichever Symbols happened to be missing, so aburi diff reports what it can see and warns on stderr that the check was unavailable (cli-spec.md §6.6).

dependencies[] gets the same treatment on its own terms — see §6.2.1. What stays outside both is a file both revisions skipped: neither document holds a Symbol or an edge from it, so there is no leftover to classify and the diff is silent about a file it never compared. That is a statement about the run rather than about any entry, and aburi diff makes it on stderr (cli-spec.md §6.6) and in the artifact, in notCompared[] (§6.3).

3.5.2 duplicateOf: a removal whose body a head Symbol holds ​

Matching is one-to-one, so deduplicating N identical helpers into one — two byte-identical emptyIR builders in two test files becoming one in a shared fixture — pairs one of them with the survivor (§3.3) and leaves N−1 removed. No care on the author's side changes that, and a bare removal reads like deleted behaviour, so --fail-on removed blocked a deduplication every reviewer would approve. The evidence that the behaviour survived is already in the documents: the survivor holds the removed Symbol's body.

It is still a removal, so removed stays its status and duplicateOf names the survivor beside it. The Symbol is gone, and what the same body proves stops at its behaviour (below), so a reader that does not know the field reads the entry as a deletion, which is true, and errs toward caution. That is the shape §4.2 turns down for a Symbol whose file one side never read, and for the opposite reason: there removed would claim a deletion nothing showed. --fail-on removed reads the field and counts the removals that duplicate nothing, and removed:duplicate counts the others (cli-spec.md §6.7).

for each removed Symbol r with no extKind whose logic names something (fingerprint.md §4.8):
  candidates = head Symbols, paired or not, not dropped, with r's kind, r's logic fingerprint
               and r's syntax fingerprint
  r.duplicateOf = the candidate of highest nameSimilarity to r, ties to the lower id   # as §3.3's lone branch
                | null when there is none
every other removed Symbol: r.duplicateOf = null

The kind and the refusal of logic that names nothing are stage 3's, read from the removed side. A function is never the duplicate of a class, and a body whose logic names nothing — one that only calls something, one that returns a literal — is never a duplicate, even of a head Symbol that holds it byte for byte, because its logic fingerprint is one every body of that shape shares.

The syntax fingerprint is what stage 3 does not ask for. A shared logic fingerprint is enough for stage 3 to pair a lone base, because a wrong pairing there is still reported, as a change. Here it would take a deletion out of the gate, and unrelated bodies share a logic fingerprint often: one if (tree === null) throw new Error(…) guard is the whole logic of many helpers. On a change of this repository that moved its test helpers into a shared package, logic alone named a survivor for 22 removals, seven of them a function that only shares its guard with the removed one; with the syntax as well it names nine, each a helper that moved unchanged. The other six were deduplicated into a survivor generalized on the way, whose body differs, and those removals stay bare: a gate that passes on less evidence than an unchanged body would pass on a coincidence.

The extKind is the other thing stage 3 need not ask about. A plugin gives a Symbol one when it reads the Symbol's role from outside its body: a Next.js route handler serves a route because of the file it is in, and a NestJS route method because of the path in its decorator. Two GET handlers in app/api/v1/users/route.ts and app/api/v2/users/route.ts can share a body byte for byte, and deleting the first retires an endpoint whatever the second holds. The syntax fingerprint covers the body alone (fingerprint.md §5), so nothing the comparison reads tells the two routes apart, and such a removal is reported bare. The rule is read off the extKind rather than asked of each plugin, so a React hook or component deleted beside an identical one is bare too. The helper this section exists for has no extKind.

The candidates are every head Symbol, not only the unpaired ones. The survivor is usually paired, with the duplicate it kept (moved) or with itself when a twin beside it was deleted (unchanged), and it can be added when it took a name none of the duplicates had and stage 3 could not choose among them.

summary.removed still counts every removed entry, and summary.removedDuplicates counts the ones with a duplicateOf within it. A current writer emits both on the terms §10.1 gives an optional field whose absence an older writer could have meant differently: duplicateOf: null on every other entry, and removedDuplicates: 0. duplicateOf is a property of the entry rather than a status of its own because adding a status is breaking (§10.1).

What this does not prove. The same body says the survivor computes what the removed Symbol computed. It does not say every caller moved to the survivor: a removed exported helper still breaks an importer the change did not update, as a moved one does. The entry stays in removed and in the report's Removed section, naming the survivor, so a reviewer sees both.

3.6 Handling dropped symbols ​

Symbols with dropped: true are excluded from matching in stages 3/4:

  • Their fingerprints are all zero, so they collide 100% in stage 3
  • Judging identity by name+signature alone carries too little information

Instead, the dropped-only weak matcher of stage 4.5 (§3.4.5) runs:

  1. If caught by stage 1 (exact ID match), settled
  2. Otherwise stage 4.5 attempts the lastSegment(name) + basename(file) weak match, on whichever of the two identifies a symbol (§3.4.5)
  3. If still unmatched, counted independently as "dropped disappeared/appeared" (aggregated in the "dropped + changes" section of the diff report)

Dropped symbols are outside the IR's primary field of view, so the false-positive risk of stage 4.5 is accepted.

3.7 Identity collisions (fail-fast) ​

The diff keys three collections by identity. Stage 1 pairs Symbols by id (§3.1) and stages 2 to 4.5 track the base Symbols they have consumed by id; §6.1 maps Components by id; §6.2 maps Dependencies by the (from, to, via) triple. Repeat any of them and the diff still produces an answer — with an entry left out, an entry classified twice, or a change the two revisions do not contain — and nothing downstream can tell that answer from the real one. ir-schema §14 #1, #2 and #13 forbid all three for that reason, and this section is where that reason lives: the code and its tests refer here rather than restating it.

At extraction time, the Aburi core stops with a fatal error on:

  • Multiple Symbols generated with the same ID (e.g., multiple export default function in the same file, or CJS module.exports.default coexisting with ESM export default)
  • Two or more <default> symbols detected within the same file
  • A dropped and a non-dropped symbol colliding on the same ID

The error message is Symbol ID collision at <file>: <id>, prompting the user to fix the offending location.

At the diff entry point, buildDiff checks the same three identities again before the first stage runs, because it is public API: an IR read off disk has been through the integrity checker, but one a caller assembled in memory has been through nothing. A collision raises DiffError with code ir-identity-collision, naming the side, the collection, the repeated value, and both positions.

The identity pass runs behind a shape gate, and both exist for the same reason. buildDiff calls checkDocumentShape — invariant #20, and only #20 — on each side first, raising ir-shape-invalid named by the record the breach sits in and the field inside it. Without it, every field the diff dereferences crashed with a TypeError naming neither: fingerprint and source during classification (§4), calls, decorators, effects and rules during the delta (§5), components[].roots in §6.1, and stats in the side view §6.2 builds, which reads stats.skippedFiles unconditionally. That enumeration is the shape of the class rather than the whole of it, and it is one change to the matcher away from being out of date — which is the argument for a gate that is not scoped to the fields the matcher happens to read. What the gate establishes is what the IR brand asserts, so a scope that moved with the matcher would leave a caller's Document conditionally valid. With it in place, the identity pass's own type guards have no live path, and DiffError carries the full violation array beside the message so a caller repairing a Document is not made to run the diff once per field.

The entry-point check stops at shape and identity rather than delegating to the whole integrity checker. Most of the remaining rules would make buildDiff refuse a Document over something that does not change its answer — #3 (a component reference that resolves), #7 (the effect vocabulary) and #15 (the callResolution census) are all read by no part of the diff. Note that this argument does not extend to every rule. #4 and #12 (a Symbol-shaped dependency endpoint names a declared Symbol) reach the answer through §6.2, which keys a base edge under the head ids of its paired endpoints: a stray endpoint can spell the id another base edge is translated to. The translation refuses that collision itself, with ir-identity-collision, so the gate does not need the rule. #19 (Unicode normalisation) changes the answer, because matching compares raw strings and an NFD id on one side misses the NFC spelling of the same name on the other. #11 (array ordering) changes it too, through §5.2: an array delta pairs elements in array order, so when a body moves twenty lines, two same-typed rules written in the other order on one side report one of them as added and removed, where the canonical order reports nothing. Neither is enforced here because the diff has no standing to rewrite its inputs, not because they are harmless — and note that #11 no longer reaches matching, which §3.8 makes independent of array order.

3.8 Choosing among candidate pairings ​

Stages 3, 4 and 4.5 each produce a set of possible pairings and have to settle them. acceptInScoreOrder sorts the candidates and sweeps once, taking a pairing when neither side has been taken already:

sort by (score descending, base.id ascending, head.id ascending)
for each candidate:
  if base and head are both still free:
    accept it

Two properties follow, and neither held when each head chose its own best in turn.

The diff is a function of the two Documents, not of their array order. (base.id, head.id) is a total order on candidates of equal score, because ids are unique within a Document (ir-schema §14 #1) — which §3.7 has buildDiff establish before the first stage runs. Without it, equal scores resolve to whichever candidate was enumerated first, and permuting symbols[] changes the bytes of diff.json.

Equal means equal as fractions. Stage 4 sorts on its exact composite (§3.4.3) divided out once, so two composites that are the same fraction are the same number, whichever axes they are made of, and go to the ids. A base that renamed its member, at 3/4 with a signature of 11/12, and one that kept it, at 1 with a signature of 1/2, both score 0.85 for one head, and the lower base id takes it. Summed in floating point they came out 0.8499999999999999 and 0.8500000000000001, and rounding chose. Stage 3's score is a single quotient of two counts, which already divides out to one number per fraction.

A better pairing is never passed over for a worse one. Choosing per head consumed a base the moment some head wanted it, so an earlier head could take the base that was a later head’s exact match — putting one name in the output as an addition and as the source of a move at the same time.

The sweep is greedy, not an optimal assignment: a pairing can still be stranded because both of its partners were taken by higher-scoring ones. That is a deliberate stop — the case that misleads a reader is the best available pairing being skipped, and a greedy sweep in score order never does that.

4. Status determination ​

For each matched pair:

droppedToggled = base.dropped != head.dropped     // §4.1
pathChanged    = base.source.file != head.source.file || base.id != head.id
apiChanged     = base.fingerprint.api    != head.fingerprint.api
logicChanged   = base.fingerprint.logic  != head.fingerprint.logic
syntaxChanged  = base.fingerprint.syntax != head.fingerprint.syntax

confidenceChanged = !head.dropped && base.confidence != head.confidence

contentChanged = apiChanged || logicChanged || syntaxChanged || confidenceChanged

if droppedToggled:
  status = "dropped-toggled"                       // takes precedence over all others
elif pathChanged && contentChanged:
  status = "moved+changed"
elif pathChanged:
  status = "moved"
elif contentChanged:
  status = "changed"
else:
  status = "unchanged"

unchanged is not included in the default output (only counted in the summary).

pathChanged covers an in-file rename as well as a relocation: any id mismatch in a matched pair means the identifier moved, which DF9 ("method rename (same file, same logic) → moved") relies on. Stage 1 pairs by exact id, so only a pair a later stage matched can take the id branch; a changed id no stage pairs is a removal and an addition.

confidence is compared on its own because no fingerprint reads it. The same code classified less surely — a framework role matched on the identifier alone where an import used to prove it — is something a reviewer has to see, and an unchanged pair is never reported, so a confidence change that moved no fingerprint would otherwise vanish. It counts like any other change of its status: toward summary.changed and --fail-on changed when the Symbol stayed put, toward summary.movedChanged and --fail-on moved+changed when it also moved. The blast radius can be wide. A plugin may decide confidence from a file-level signal (the Express plugin asks whether the file imports express), so deleting one import moves every Symbol that plugin classified in that file at once; and when the two IRs were read off disk rather than scanned in one run, they may come from different plugin versions, whose confidence rules differ for code nobody touched. --fail-on confidence-changed gates on this axis alone and takes a threshold (confidence-changed:>20); a gate that should ignore it writes the fingerprint axes (api-changed,logic-changed) instead of changed (cli-spec.md §6.7). A pair dropped on both sides is exempt and stays unchanged (DF13): a dropped Symbol is outside what the diff asks a reviewer to read. component is the contrast: it comes from Component.roots[] rather than from the code, so a re-rooted package changes it under every Symbol without anyone editing them, and it is recorded on the delta only.

4.1 Why the dropped-toggled status exists ​

The transition dropped: false → true (kept → dropped) or dropped: true → false (dropped → kept) is caused by changes to drop rules or plugin configuration:

  • Adding a stronger DTO-detection rule → many classes become dropped: true at once
  • Adding a framework plugin turns previously dropped symbols (no decorators) into boundaries → dropped: false

In this case the fingerprints inevitably all change (a..b → 0..0 or the reverse). Treating this as changed produces the classic false report: "a DTO rule change alone lists every DTO as api-changed in the API changes section (the highest-severity section)".

Treating dropped-toggled as an independent status means:

  • delta (apiChanged, etc.) is not computed (always treated as false)
  • The Markdown projection stores these in a dedicated collapsed section, "Drop rule changes"
  • --fail-on dropped-toggled can make it an explicit CI gate

4.2 Why the unknown status exists ​

The alternatives were both silence of a kind. Suppressing the entry hides a Symbol that may genuinely have been deleted; keeping removed and adding a flag beside it shows an API deletion to every reader that does not know to look for the flag — including --fail-on removed, which is the reason the phantom mattered. A status of its own makes --fail-on removed mean what it says and gives a strict pipeline --fail-on unknown to catch the case where the answer is missing on one side.

A removed duplicate (§3.5.2) does keep removed and add a field beside it. There the status is true: the Symbol is gone, and a reader that misses the field reads a deletion that happened. Here the status would be false, and a reader that missed the flag would read a deletion nobody saw.

It does not catch the case where both sides lost the same file, and no status could. unknown is derived from the matcher's leftovers, and a file skipped in both revisions contributes Symbols to neither document, so there is no leftover to carry a status at all. That loss is reported at document level instead — see §6.3.

5. Delta computation (changed / moved+changed only) ​

Compute per-field "what" changed:

5.1 Fingerprint axes ​

delta.apiChanged    = base.fp.api    != head.fp.api
delta.logicChanged  = base.fp.logic  != head.fp.logic
delta.syntaxChanged = base.fp.syntax != head.fp.syntax

If all three axes changed: "implementation, contract, and meaning all changed".

5.2 Array diff (rules / effects / calls / decorators) ​

For each array, three kinds of delta are computed:

  • added[]: elements in head but not in base
  • removed[]: elements in base but not in head
  • modified[]: elements present in both but with differing content (e.g., a rule where only condition changed)

Element identity criteria — the key that makes two elements candidates; choosing among several candidates is §5.2.0:

  • Rule: (type); an edited one is paired within ±2 lines of where it sat in its Symbol (§5.2.1)
  • Effect: (id, target), with no line window at all
  • Call: (target); an edited one is paired within the line window
  • Decorator: (name); an edited one is paired within the line window (§5.2.2)

An element whose content is unchanged has no line window in any array: it pairs with its counterpart however far the body moved (§5.2.0).

Every line this section compares is an offset: the element's line less its own Symbol's source.startLine, so a base element and a head element are measured from the first line of the base and the head Symbol respectively. A propagated effect, which has no line, sits at offset 0 on both sides.

5.2.0 Choosing among elements that share a key ​

A key does not identify one element. A Symbol routinely holds two guard rules, two calls to one target, two @Get — so which base element a head element takes is a choice.

It is made in two passes, and each pass chooses a set of pairings rather than one at a time:

for admissible in [exact, near]:
  exact(b, h) = same key and content equal
  near(b, h)  = same key and |b.offset - h.offset| <= lineFuzz
  for each key, take the best set of admissible pairings over its elements still free, where
    - the pairings do not cross: i1 < i2 implies j1 < j2
    - more pairings beats fewer
    - among sets of equal size, less total |b.offset - h.offset| wins

unpaired head -> added
unpaired base -> removed
paired, contents differ -> modified   (the head element is the one emitted)

The first pass is what makes the answer readable. An element nothing touched has an exact counterpart, so the pass that only considers exact counterparts claims it before an edited or deleted neighbour can; whatever is left over is then paired by proximity, which is where a genuine edit lands.

Why the exact pass has no line window. Non-crossing, below, is what stops an element from pairing with one it was never beside. A window on the exact pass would add a refusal of exactly the case that pass exists for. A function that moved 14 lines down its file with nothing edited — one guard inserted above it is enough — would otherwise lose every pairing it had, and each call and rule would come back as one added and one removed, listed under both headings with only the line suffix to tell them apart. Distance stays in the pass as the tie-breaker of the score, which is where it ranks two otherwise equal sets. The window belongs to the second pass: once the contents disagree, proximity is the only evidence that two elements are one edited element rather than a deletion and an unrelated insertion that share a key.

The window did one other thing, and dropping it gives that up: it stopped a distant exact counterpart from outranking a near edit. With base guard@10 "!x" and head guard@11 "!y", guard@60 "!x", the exact pass pairs !x with its copy fifty lines down, so !y has nothing left to be an edit of and reads as added, where the window used to report !y modified and !x added. Likewise base !a@10, !b@20 against head !b@10, !c@20 reads as !a removed and !c added rather than two edits. Both readings are defensible, and this one is what the first pass promises: an element nothing touched is claimed by its own counterpart before an edited neighbour can take it. The trade is lopsided in its favour — a body that moved is the ordinary case, and a near edit beside a far identical copy the unusual one.

Why non-crossing, and only within a key. ir-schema §14 #11 orders these arrays by line, so i < j means element i sits above element j in the file. Two pairings of one key that crossed would have an element move above another of its key that it was below — not a line shift but a different element. Elements of different keys are never candidates for each other, so their relative order identifies nothing: a call to scan that moved below a call to mkdir is still the call to scan, and holding it to the order of every other call would report it as added and removed. The constraint is also what makes the best set reachable by a suffix recurrence rather than by a general assignment algorithm, and what settles ties: between two otherwise indistinguishable candidates the one that keeps the pairings in order is the one taken.

Why a set and not one element at a time. A greedy pass takes the pairing in front of it, and a nearer pairing can cost a farther one its only partner:

baseheadfirst key hitnearest line, greedythis rule
guard@1 "!user", guard@3 "!invoice"guard@3 "!invoice"removed and modified !invoiceremoved !userremoved !user
guard@1 "!a", guard@2 "!b"guard@2 "!a", guard@3 "!b"nothingmodified !a, modified !bnothing
guard@1 "!a", guard@2 "!b"guard@3 "!c", guard@4 "!d"modified !c, modified !dmodified !c, added !d, removed !amodified !c, modified !d

Row 1 is a deleted guard: taking the first key hit inside the window let the surviving guard claim the deleted one's slot, so an untouched element was reported as removed and modified at once, under contradictory buckets, and the element actually deleted appeared nowhere.

Row 2 is two guards shifted down a line together with nothing edited — the noise the exact pass exists to suppress, which pairing by proximity alone reintroduces.

Row 3 is the same shift where both guards were also edited, so the exact pass has nothing to claim and the whole block is the second pass's. Greedily, the first head element is nearest the second base element; claiming it strands the other head outside the window, and two edits come back as an edit, an add and a remove. Choosing the pair of pairings together costs more total movement and reports two edits, which is the right answer.

What is not promised. The result depends on the order of the arrays, and cannot not: it pairs by line, and #11 is what fixes that order. Reversing an array produces a different answer — and a non-canonical Document. §3.8 achieves order-independence for Symbol pairing because ids give it a total order that comes from content; §5.2 has no counterpart, and §3.7 records the distinction.

Why offsets and not file lines. A Symbol whose file gained a function above it moves down the file whole, and every element in it moves with it. Measured in file lines, the near pass then saw an edited guard thirty lines from its predecessor and reported a deletion and an unrelated insertion; over 45 of Aburi's own pull requests, 595 of the 699 changed Symbols had shifted in their file, and 298 removed and added pairs in them were edits the window refused only for that reason. Measured from the Symbol's first line, the edit sits beside its predecessor, as it does in the code. Lines inserted inside the body, above the element, still move its offset, and that is the movement the window is for.

5.2.1 Rationale for line fuzz ​

Line fuzz decides one question: whether an edited element is the same element as the one it replaced. A guard whose condition changed from !user to !admin one line lower is an edit and reads as modified; the same pair forty lines apart is more likely a deletion and an unrelated insertion, and reads as removed and added. By default a difference of up to ±2 lines between the two offsets (§5.2) is tolerated for this; beyond that the two are treated as distinct elements.

It does not decide whether an unchanged element survived. That one is paired by the exact pass (§5.2.0), which has no window, so a body that moved any distance reports nothing for the rules, calls and decorators it kept.

The window defaults to 2 and is not an aburi.json setting, because it changes only how an edit reads, never which Symbols changed. A caller of @aburi/diff can pass another value through DeltaOptions.lineFuzz, whose docblock states what it accepts. 0 pairs an edit only with an element on the same line; it does not stop an unchanged element from pairing.

However, fingerprints themselves contain no line information (D4 §4), so line fuzz is for delta display only. It does not affect fingerprint equality checks.

5.2.2 Handling of arguments and receivers in Decorator deltas ​

Decorators are identified by (name), but differences in arguments and qualifier are shown in the delta, each side as written (markdown-projection.md §6.2):

- decorator modified: `@Post('/invoices')` → `@Post('/invoices/v2')`
- decorator modified: `@UseGuards(AuthGuard)` → `@UseGuards(AuthGuard, RoleGuard)`

arguments is combined with line fuzz for the modified determination:

  • Same name + within line fuzz + differing arguments → modified
  • Same name + within line fuzz + differing qualifier (the receiver: @nest.Post → @tsed.Post, or a receiver gained or lost) → modified. The api fingerprint hashes the normalized raw, which quotes the receiver, so a receiver edit moves that fingerprint, and a delta that ignored it would leave the move unexplained
  • An absent qualifier compares as absent. Two Documents written before the field existed report nothing, but a base stored by such a producer and diffed through --base against a head that carries the field reports each qualified decorator as modified, once. aburi diff <base>..<head> re-scans the base with the head's producer, so it never meets this case
  • raw itself is never compared: (name, qualifier, arguments) is its structured decomposition, and comparing the quoted text would report a reformat as an edit
  • boundary is not compared either: plugins derive it rather than the source writing it, so a flip would show as a modified decorator that reads the same on both sides. A boundary flip still moves the api fingerprint with nothing in the decorator delta to explain it; how to show it is a display question of its own
  • A same-name pair further apart than the line fuzz is not paired by the near pass, so a receiver edit that also moved that far reports as added + removed, as a changed argument list does
  • Same name + same arguments + same qualifier + only line differs, by any distance → implicitly the same (not shown in the delta)
5.2.3 modified determination for Component diffs ​

Components have no modified (only the three states added / removed / changed). Inside changed, delta fields indicate the differences via the booleans rootsChanged / publicApiChanged / frameworksChanged. For each field that actually changed, the full before/after arrays are emitted (no per-element modified diff — output is field-granular):

Component changed: billing
  roots: ['apps/billing'] → ['apps/billing', 'packages/billing-domain']
  frameworks: [] → ['nestjs']

5.3 signature delta ​

delta.signature = {
  inputs: { added: [...], removed: [...], modified: [...] },
  outputs: { added: [...], removed: [...] },
  throws:  { added: [...], removed: [...] },
  asyncChanged: bool,
  generatorChanged: bool,
  typeParametersChanged: bool
}

If both signatures are null → delta.signature = null.

Inputs pair by position and name, with no fuzz. A paired input is modified when its type, optional or rest differs — everything the api fingerprint reads about it (fingerprint.md §3.1) — so a parameter that turns optional or rest is named in the delta that explains the api change. An absent optional or rest compares as false.

5.4 component / visibility / confidence delta ​

delta.componentChanged = base.component != head.component
delta.visibilityChanged = base.visibility != head.visibility
delta.confidenceChanged = base.confidence != head.confidence

confidenceChanged is optional in the schema only so a diff written before it existed stays valid. A current writer always emits it, false included, so a reader can tell "unchanged" from "this writer could not say" (§10.1). The values themselves are on before and after.

A Component change means "responsibility relocation", so the diff report emphasizes it.

5.5 export name delta ​

delta.exportedAs = { added: [...], removed: [...], modified: [] }

The names the module exports each side under (fingerprint.md §3.8), compared as a set: export { handler as GET } becoming export { handler as GET, handler as DELETE } gives added: ["DELETE"], and export default function Page becoming export function Page gives added: ["Page"], removed: ["default"]. A name is a string with nothing else to differ in, so modified stays empty. The api fingerprint leaves the names out when they are the declaration's own name alone; the delta compares them whole, the own name included, so it says which name an export gained or lost wherever the fingerprint moved for it, and a declaration that stops being exported names the export it lost beside its visibility change. A renamed declaration exported under its own name records both, removed: ["isAdminUser"], added: ["canAdministerSite"]; the Markdown leaves that pair to its name row (markdown-projection.md MP17d). The key is emitted unconditionally, empty included (§10.1).

5.6 middleware delta ​

delta.middleware = {
  added:     [...],   // names the head holds more often than the base, in head order
  removed:   [...],   // names the base holds more often than the head, in base order
  reordered: bool     // the names both sides hold run in a different order
}

Present when either side's Symbol carries middleware (ir-schema.md §5.8), the two lists being equal included, and absent when neither does, so a reader can tell "unchanged" from "nothing to compare". A side without the key compares as an empty list, so a route that loses its last middleware reports it removed.

The lists are compared as multisets of names, not by position: removing the first of three middleware is one removal, not three changes. Where a name repeats, its earlier occurrences are the ones paired. reordered is true when the longest common subsequence of the two lists is shorter than the names they share. The lists themselves are on before and after, which is where the report reads the order from.

A changed middleware is a removal and an addition: requireRole("admin") → requireRole("user") removes one name and adds the other. A name is the whole of what the IR records about an entry, so there is nothing for a modified bucket to say that the two rows do not.

6. Component / Dependency diff ​

Not only Symbols but also Components / Dependencies are diffed, in separate arrays.

6.1 Component diff ​

componentDiff = {
  added:   [Component],         // head only
  removed: [Component],         // base only
  changed: [{
    before: Component,
    after:  Component,
    delta: { rootsChanged, publicApiChanged, frameworksChanged }
  }]
}

Component identity is id. Which fields make a Component changed and which fields the delta summarises are two different questions, and answering them with one list is a bug this document once invited: a Component is changed when any field differs, while delta names only the three axes a reviewer scans for architectural movement.

Reading the three booleans as the definition of change means a renamed component, an added language, or a new description produces componentsChanged: 0 and an empty changed[] — and with no entry there is not even a before/after pair for the Markdown layer to render. The delta needs no fourth boolean to fix that: changed[] already carries before and after, so a consumer renders a name change by comparing them, and an entry whose three booleans are all false is well-formed and means "something outside those axes moved".

Comparison is over the whole record, so a field added to v1 later counts without this section being revisited, and two spellings of "no value" are reduced to one before it: a description that is null compares equal to an absent key, and a publicApi / frameworks that is [] compares equal to an absent key.

Those two rules are scoped to the fields that license them, not to a class. description is Class A (ir-schema.md §1.1), where a reader MUST treat an absent key as null. publicApi and frameworks are Class B, whose own writer rule is "omitted when empty" — which is what makes [] a non-conforming spelling of absence. Class B does not say that in general: §1.1 is explicit that there "absent" and "empty" are different facts, with stats.lspEnrichment.hintsRejected as its own counterexample. So the one future shape that forces a revisit here is a Class B Component field whose presence is the information — dropping that by shape would swallow a real difference. Every other new field compares as written, which is the case that needs nothing.

6.2 Dependency diff ​

dependencyDiff = {
  added:   [Dependency],
  removed: [Dependency],
  unknown: [{ dependency, absentFrom, lostFiles }]   // §6.2.1
}

Dependency identity is judged by (from, to, via). Changes to direction / effect are treated as an added+removed pair (no modified needed).

A base edge is keyed under the ids the Symbol pairing gave its endpoints: an endpoint the base wrote as the before of a moved, moved+changed, changed or dropped-toggled entry is read as that entry's after id — the translation φ that slice-view.md §5.1 applies to base call edges. A Symbol's id carries its file and its name, so without it a call whose caller or callee was paired under a new id — moved, renamed, or either with its body changed — reads as the old edge removed and a new one added, though it is the same call between the same two Symbols. A removed edge is still reported as the base wrote it, and a Component endpoint is never in the mapping.

No two base edges of a valid Document fold onto one key. That takes three things: the pairing is one-to-one; stage 1 pairs every id both documents hold, so no later pair's after id is an endpoint some other base edge wrote untranslated; and every Symbol-shaped endpoint names a declared Symbol (ir-schema §14 #4, #12). buildDiff does not check the last (§3.7), so an in-memory base whose stray endpoint spells a translated id would lose one of the two edges without a trace. The translation refuses that instead: two base edges that read as one key raise DiffError with code ir-identity-collision, naming both edges and the key.

6.2.1 unknown: the other document could not have held this edge ​

dependencies[] is projected from the resolved call graph, so a Symbol that never reached a document takes every edge it participated in with it. Comparing the two arrays by identity alone therefore reports those edges as deletions — the same confident-but-wrong report §3.5.1 exists to prevent, one array over, and the half that is easiest to miss is an edge whose other end survived: both revisions hold that Symbol, so the edge reads as a call the author removed.

An edge one document holds is unknown when the other document never analysed the file an endpoint of it lives in. absentFrom names that document, on the same reading as §3.5.1 (head means "this may still exist", base means "this may not be new"), and lostFiles[] names the files with the reason each was skipped.

Four properties, two of them differing from the Symbol side:

  • The endpoint's file comes from the document that holds the edge. An endpoint is matched against symbols[].source.file in that document, which is written in the form stats.skippedFiles[].path is and is the space §3.5.1 classifies Symbols by — the same form, though after a git rename not the same name, which the third property deals with. Reading the file out of the id's path segment instead would be a second answer to the same question, and nothing in the schema forces the two to agree — a re-export or a generated file is where they come apart. Both sides read one DependencySideView per document, built once, so the agreement is a property of the wiring rather than a convention to be maintained.
  • lostFiles is a list, where SymbolUnknown carries one reason. An edge has two endpoints: they can sit in two files skipped for two different reasons, one of which says re-run and the other says fix something. An intra-file edge collapses to the single file it lost.
  • A renamed endpoint file is looked up under both names, as §3.5.1 does for a leftover Symbol, and lostFiles[].path is the path the absent document recorded — the one its stats.skippedFiles[] holds — not the holder's. A reader joining lostFiles[].path against the holder's symbols[].source.file therefore misses a renamed file; the list joins against the absent document's skip list, which is what it was copied from. It is deduplicated and sorted on those names, so an intra-file edge in a renamed file still collapses to one entry.
  • A Component-level edge is looked up by the Component it leaves. The scan draws one where a file of from imports a module of to (ir-schema.md §11.3), and the edge does not say which file, so it is unknown when the absent document skipped any file its own components[] attribute to from, and lostFiles[] lists all of them. A lost file of to changes no import of from, so it is not looked up, and neither is a file that lies in no Component.

A direction or effect flip stays an added + removed pair, and no loss check runs on it. The reason is not that neither document lost an endpoint file — nothing forbids a path from being both a symbols[].source.file and a skipped one, so that inference has no invariant behind it. It is that both documents hold the edge, so neither is silent about it, and unknown exists only to explain a silence.

An edge touching a Symbol that moved can be unknown while the Symbol itself is confidently moved. If S goes src/a.ts → src/b.ts and head skipped src/a.ts, stage 2/3/4 pairs the Symbol from real evidence on both sides. A base edge naming ts:src/a.ts#S is compared against the head under ts:src/b.ts#S (§6.2), and when the head holds no such edge, the loss check reads the endpoint's file from the base side, where it is src/a.ts. Erring toward unknown there is correct — head skipped src/a.ts, which may still hold the original S and its call — and it is the one case where the Symbol and dependency sides report different confidence about the same entity. "Cannot disagree about which file went missing" is a claim about file identity, not about the two classifications matching.

dependencies.unknown[] and summary.depsUnknown are optional in the schema only so a diff written before they existed stays valid. A current writer always emits both, empty array and zero included — unlike the IR's stats.skippedFiles, there is no arithmetic elsewhere in the document that would let a reader tell "nothing was unknown" from "this writer could not say".

6.3 Files neither revision analysed ​

notCompared[] names every file both stats.skippedFiles lists hold, with the reason each scan gave. Usually both lists hold it under one path; a file git renamed between the revisions is one file under two names, and it is one entry, under the head path, with the base path in basePath — written on the terms §10.1 gives an optional scalar. Sorted by path, then by the base's name for the file (basePath, else path).

The second key only decides anything for a rename map buildDiff is handed directly, since git renames no two files onto one path and never renames onto a path the base has. Such a map can lead two base records to one head path, and each is its own entry: keeping only one would drop a skip record on the strength of whichever the map or the skip list happened to list first.

It exists because the Symbol level cannot express the loss. A file skipped on one side leaves Symbols on the other, and those become unknown (§3.5.1); a file skipped on both leaves nothing anywhere, so the document said nothing about it — and a diff that says nothing about a path is exactly what a diff that compared it and found it unchanged looks like. Most skip reasons are properties of the file rather than of the revision (a generated bundle over the size cap, a language no plugin claims, a file unparseable since before the branch was cut), so this is the ordinary case: a workspace with a standing blind spot got a clean-looking diff on every pull request while a whole directory sat outside the comparison.

Lost by both, not by either. A one-sided loss is already reported as unknown, and listing it here as well would count one loss twice in two vocabularies that mean different things.

Both reasons, never one. They can differ — parse-timeout at the base and over-size at the head is one file that timed out once and is permanently too large — and the pair is what tells a reader whether a re-run is enough.

No summary counter. unknown and depsUnknown complete a census: they correct the counters beside them, which are undercounts by exactly that much. These files contributed no entry to any array on either side, so there is nothing to correct — the field scopes the document rather than qualifying a count. A gate written to mean "fail if this diff is incomplete" therefore sees neither this nor dependencies.unknown; --fail-on has no token for either (cli-spec.md §6.7).

A document that predates stats.skippedFiles produces nothing here. It reports totalFiles > parsedFiles and no list, so no path can be named; aburi diff warns about that state per side (cli-spec.md §6.6) and the artifact does not invent it.

7. Output formats ​

7.1 Diff result JSON (.aburi/diff.json) ​

jsonc
{
  "$schema": "https://aburi.dev/schema/aburi.diff.v1.json",
  "generator": { "name": "aburi", "version": "1.0.0" },
  "base": {
    "ref": "main",                                   // git ref or "ir-base.json"
    "irSchema": "aburi.ir.v1.json"
  },
  "head": {
    "ref": "HEAD",
    "irSchema": "aburi.ir.v1.json"
  },
  "summary": {
    "added":           5,
    "removed":         3,
    "moved":           2,
    "movedChanged":    1,
    "changed":         12,
    "droppedToggled":  4,
    "unchanged":       142,
    "droppedAdded":    4,
    "droppedRemoved":  1,
    "componentsAdded":   1,
    "componentsRemoved": 0,
    "componentsChanged": 2,
    "depsAdded":     3,
    "depsRemoved":   1,
    "unknown":       2,
    "depsUnknown":   1,
    "removedDuplicates": 1
  },
  "symbols": [
    { "status": "added",   "symbol": { /* Symbol */ } },
    { "status": "removed", "symbol": { /* Symbol */ }, "duplicateOf": "ts:src/fixtures.ts#emptyIR" | null /* §3.5.2 */ },
    { "status": "moved",   "before": {...}, "after": {...}, "rationale": "git-rename" },
    { "status": "changed", "before": {...}, "after": {...}, "delta": { /* see §5 */ } },
    { "status": "moved+changed", "before": {...}, "after": {...}, "rationale": "...", "delta": {...} },
    { "status": "moved", "before": {...}, "after": {...}, "rationale": "name-signature", "throughMembers": 2 /* only on an owner paired through its members — see §3.4.8 */ },
    { "status": "dropped-toggled", "before": {...}, "after": {...}, "direction": "to-dropped" | "to-kept" },
    { "status": "unknown", "symbol": {...}, "absentFrom": "head", "reason": "over-size", "lostPath": "..." /* only after a git rename — see §3.5.1 */ }
  ],
  "components": {
    "added":   [ /* Component[] */ ],
    "removed": [ /* Component[] */ ],
    "changed": [ /* {before, after, delta} */ ]
  },
  "dependencies": {
    "added":   [ /* Dependency[] */ ],
    "removed": [ /* Dependency[] */ ],
    "unknown": [ /* {dependency, absentFrom, lostFiles} — see §6.2.1 */ ]
  },
  "notCompared": [ /* {path, basePath?, baseReason, headReason} — see §6.3 */ ]
}

status: "unchanged" is not included in the output (counted in the summary only).

7.2 Markdown projection (.aburi/diff.md) ​

A format intended for pasting into PR comments. markdown-projection.md §6 specifies it, with an example of each section.

Section order is high importance → low. markdown-projection.md §6.1 is the list the renderer and the size cap follow; this copy must match it:

  1. API changes (warning)
  2. Logic changes
  3. Slice View
  4. Added (new)
  5. Removed (deleted)
  6. Unknown
  7. Not compared
  8. Moved+Changed (moved and changed)
  9. Moved (no semantic change — collapsed)
  10. Component changes
  11. Dependency changes
  12. Dropped changes (collapsed)
  13. Confidence changes
  14. Syntax-only changes (collapsed)

Collapsed sections are visible at zero review cost.

8. Performance characteristics ​

8.1 Complexity ​

StageComplexity
Stage 1 (ID match)O(N) hash map lookup
Stage 2 (git rename)O(R) where R = renamed files
Stage 3 (logic fingerprint)O(N) grouping, then per group of B bases and H heads O(H) for the lone branch and O(B x H) per scored round; a group whose logic names nothing always scores (§3.3)
Stage 4 (name+signature)O(K x C) where K = remaining unmatched and C = bases sharing a member token (§3.4.0); O(K^2) when one token is shared by everything. Pairing owners through their members (§3.4.8) adds O(P x D) for P pairs and a qualified-name depth D, and a sort of the unpaired owners

K is usually < 100 (most symbols are settled in stage 1). Effectively O(N), i.e. linear.

8.2 Memory ​

Both base and head Symbols are held in memory. Under 100MB for a medium monorepo (10k Symbols). Large repositories (>100k) would require streaming, which is not yet supported.

Stage 4 additionally holds one record per candidate pairing (§3.8) — every (base, head) pair in a bucket that clears the head's threshold. That is O(1) in the ordinary case, where a threshold of 0.85 or above admits few pairs, and O(base × head) for a bucket whose members are near-identically named. The per-head loop it replaced held one record; the trade buys the guarantee that the best available pairing is never skipped, and §3.4.0's bucket pre-filter is what keeps the bound to a bucket rather than to the Document.

Stage 4.5 does not pay this. Its candidates are the keys that identify a pairing (§3.4.5), at most one each over two axes, so the list is bounded by the dropped Symbols themselves rather than by their pairs. The rule that bounds it is the same one that stops a shared index.ts from pairing unrelated Symbols: a key several Symbols carry identifies none of them.

8.3 Targets ​

For a medium monorepo (~1000 files, ~5000 Symbols): diff computation <2 seconds (excluding IR generation). Including IR generation: <30 seconds (including a full Workspace scan).

9. Edge cases ​

9.1 Schema version mismatch ​

base.$schema != head.$schema → fatal error, unless both are URLs of IR v1: the two hosts of ir-schema.md §15.1 name one version. When a future v2 ships, an upgrader will be provided.

9.2 Empty base / empty head ​

  • Empty base → every head Symbol is added
  • Empty head → every base Symbol is removed
  • Both empty → empty diff

9.3 Component id collision ​

If base/head share the same Component id but with different roots:

  • Recorded as componentDiff.changed with delta.rootsChanged = true
  • If a Symbol moved to the new component, it is recorded with componentChanged = true

9.4 Differing plugin configurations ​

If base has the effects-prisma plugin enabled and head does not:

  • What was db.write in base remains as calls in head
  • The Symbol's logic fingerprint changes, so it appears as "changed"
  • Nothing in the Diff says the cause is a plugin configuration difference. aburi diff --base --head compares the generator.plugins[] both IRs record and names every difference on stderr (cli-spec.md §6.6, CL62), which is where a reviewer reading the run learns it. In ref mode the case does not arise: both scans load the head's plugins (cli-spec.md §6.4 step 3)

9.5 Massive moved counts ​

When a directory rename turns every symbol into moved:

  • Aggregated in the summary (moved: 1234)
  • The Markdown displays them grouped as "inferred directory rename" (future feature; individual listing is acceptable today)

9.6 Failed dropped-to-dropped matches ​

Dropped symbols are tried in the order stage 1 (exact ID match) → stage 4.5 (weak matcher, §3.4.5). If they survive with the same ID they are treated as unchanged; if caught by stage 4.5 they become moved (rationale: dropped-weak-match); otherwise they are counted independently as droppedRemoved.

10. Verifiable properties ​

IDInputExpected
DF1Feed the same IR as base/head, with nothing in stats.skippedFilessummary all 0, changes/components/dependencies/notCompared all empty
DF1bFeed the same IR as base/head, with a file in stats.skippedFilessummary still all 0, but 1 entry in notCompared — the comparison covered less than the counts suggest
DF21 new Symbol in headadded: 1, 1 entry in the Markdown Added section
DF31 Symbol deleted from baseremoved: 1
DF4Only a rule's condition changedchanged: 1, delta.logicChanged: true, delta.apiChanged: false
DF5signature outputs changedchanged: 1, delta.apiChanged: true
DF6File rename (git rename detectable)moved: 1, rationale: "git-rename"
DF7File rename + rule addedmoved+changed: 1, rationale: "git-rename"
DF8File rename (no git) with a matching logic fp that names somethingmoved: 1, rationale: "logic-fingerprint"
DF9Method rename (same file, same logic)moved: 1, rationale: "name-signature" (same logic fp but different ID)
DF10Multiple Symbols in base/head share the same logic fpDisambiguated by name similarity, paired correctly
DF11Component added1 entry in components.added
DF12Dependency added1 entry in dependencies.added
DF12aA call edge whose caller, callee or both are moved or moved+changed, renamed in their file included, the head holding the same call (same via, direction and effect) under the new idsno dependency change (§6.2); a direction or effect flip is still a removed + added pair
DF12bDF12a without the call on the head side, neither endpoint's file skippedthe base edge, under the ids the base wrote, in dependencies.removed
DF12cDF12a and DF12b with the moved endpoint's old file skipped by the headno dependency change when the head holds the call; otherwise the base edge, as the base wrote it, in dependencies.unknown (§6.2.1)
DF12dTwo base edges that read as one key under the head ids (a stray endpoint spelling a translated id)DiffError ir-identity-collision
DF13Dropped Symbol paired (same ID)Treated as unchanged
DF14Dropped Symbol disappeared (basename also changed)Counted in droppedRemoved
DF14bDropped Symbol moved to another directory (same basename)moved: 1, rationale: "dropped-weak-match"
DF15Schema version mismatchfatal error
DF16Same rule differing only in its offset from the Symbol's first line (within ±2)no delta.rules.modified — the exact pass pairs it, at any lineFuzz including 0; DF17a is the same at any distance
DF17Rule of one type whose condition changed, with a large difference in offset (>2)delta as added + removed
DF17aSame-condition rule with a large difference in offset (>2) — lines inserted in the body above itno delta.rules entry; the exact pass has no window (§5.2.0)
DF17bTwo same-type rules where one moved past the other by more than the windowthe one that crossed as added + removed; the other unchanged — non-crossing takes the nearer exact pairing, and the window then refuses the one it displaced. A crossing within the window is repaired by the second pass and reports nothing
DF17cA Symbol that moved 30 lines down its file, one guard's condition edited, a call's resolution changed and a decorator's arguments edited, each at the same offset from the Symbol's first lineeach in modified; the window compares offsets, not file lines (§5.2). A guard edited on the same file line as its predecessor but at an offset 14 lines away reads as added + removed. Of two effects with one key, the one at the same offset is the one kept: base db.write at offsets 2 and 10, head one at offset 2, reports the second removed
DF18Only syntax changed (logic/api unchanged)changed, only delta.syntaxChanged true → in Markdown: "syntax-only, collapsed"
DF18aOnly confidence changed (high → medium), fingerprints equalchanged: 1, only delta.confidenceChanged true → in Markdown: the Confidence changes section
DF18bDF18a on a Symbol that also moved filemoved+changed: 1
DF18cDF18a on a pair dropped on both sidesunchanged, as DF13
DF18dOnly the names a declaration is exported under changed: export { handler as GET } → export { handler as GET, handler as DELETE }changed: 1, delta.apiChanged true, delta.exportedAs.added: ["DELETE"] (§5.5). Writing export function f as function f with export { f } is unchanged (fingerprint.md A25)
DF18erouter.get("/users", requireAdmin, h) → router.get("/users", h)changed: 1, delta.logicChanged true, delta.middleware { added: [], removed: ["requireAdmin"], reordered: false } → in Markdown: a Logic changes entry with - middleware removed: `requireAdmin` ; swapping two middleware gives reordered: true, and a route that names none on either side has no delta.middleware (§5.6)
DF18frouter.get("/a", requireAdmin, listA) → router.post("/b", requireAdmin, createB), in one file or with the two routes in different files, with or without a third route behind requireAdmin left as it wasadded: 1, removed: 1 — middleware alone names nothing (§3.3), and neither route name passes the 0.85 bar
DF19Two unrelated top-level main(x: string) in different filesadded: 1, removed: 1 — §3.4.3 does not read a name of one word, and §3.3 applies the same rule where the logic names nothing
DF19aA name of one word in any script — главная, مستخدم, initializeas DF19; the rule is about how much the name says, not which script says it
DF19bユーザー情報を取得する moved file with an edited bodymoved+changed: 1, rationale: "name-signature" — nameEvidence floors an unsegmentable run to the words it must hold (§3.4.1)
DF19cполучитьПользователя moved file with an edited bodyas DF19b, on its token count alone: the camel boundary is Unicode case, so the hump splits
DF19dA name of one word written without word boundaries — メイン, 초기화, ハンドラー, 取得as DF19; the floor puts each under a word, as main and handler are
DF19eユーザー情報を取得する moved file with an edited body and an added inputadded: 1, removed: 1 — one token in its last segment, so §3.4.3's first threshold row asks the full 1.0
DF19fA function whose body only calls something is deleted, and an unrelated class with one method is added elsewhereremoved: 1, added: 2 (the class and its method) — §3.3 never pairs across kinds
DF19gA class with one method moved file, without git rename information, and neither body names anything on the logic axismoved: 2 whatever the class name says. When it says two words or more, §3.3 pairs the class; when it says one, §3.4.8 pairs it through its method, rationale: "name-signature", throughMembers: 1
DF19oA class whose members paired into two classes; a namespace whose function moved to the top level; a class whose method moved into a class of a name §3.4.6's gate refuses (Invoice → Receipt), or into one a scope deeper (BillingInvoices → Billing::Invoice); two classes merged into one; a namespace that took in a top-level function beside its own; an owner whose kind changed (let api = { get } → const api = { get } in another file); one whose counterpart stage 1 already pairedevery owner added or removed, or removed: 1 beside the paired counterpart, and no throughMembers anywhere (§3.4.8); with a logger, one owner line per base owner refused for a split, for its name, or for a head that also holds members from elsewhere (§3.4.7)
DF19pA class pluralised in place (UserRepo → UsersRepo) with three methods; namespace Billing holding class Billing.Invoice → Billing.Invoices and its method; const api = { v1: { get } } moved filethe class moved, throughMembers: 3; both owners paired, the namespace through the class's pair, throughMembers: 1 each, in either order of symbols[]; api paired through api.v1.get, the object between having no Symbol (§3.4.8)
DF19qA class that moved file losing one method and gaining another; a static nested Billing::Invoice whose method came from a top-level BillingInvoices beside Billing, whose method moved with it, in whichever file BillingInvoices sitsthe class paired on the one method that came along, throughMembers: 1; Billing paired, BillingInvoices removed and Billing::Invoice added in every layout: two owners a scope apart never pair, so no owner this pass pairs gains a member from outside its partner (§3.4.8)
DF19hA function whose body only calls something, or is one for loop over calls, is deleted, and an unrelated function of the same shape is added elsewhere; both names say two words or moreremoved: 1, added: 1 — §3.3 has no lone-candidate branch where the logic names nothing
DF19iA function whose body returns a non-trivial expression moved file and was renamed, without git rename information — written as a concise arrow (export const isAdminUser = (u) => u.role === "admin") or with a block bodymoved+changed: 1, rationale: "logic-fingerprint", for both spellings — the arrow's expression is its return rule (lang-plugin.md LP19a), so its logic names something and §3.3's lone-candidate branch applies
DF19jgit renames src/big.ts → src/billing.ts; the head skips src/billing.ts (or the base skips src/big.ts, or both do)the base Symbols are unknown with absentFrom: "head" and lostPath: "src/billing.ts" (or the head Symbols unknown with absentFrom: "base" and lostPath: "src/big.ts"), never removed / added; skipped on both sides, one notCompared[] entry with path: "src/billing.ts" and basePath: "src/big.ts" (§3.5.1, §6.3)
DF19kDF19j with the head skipping src/billing.ts, and the base holding an edge ts:src/big.ts#Billing → ts:src/kept.ts#keptthe edge is in dependencies.unknown with absentFrom: "head" and lostFiles: [{ path: "src/billing.ts", … }] — the head's name for the file, not the holder's src/big.ts — never in removed (§6.2.1)
DF19lA rename map handed to buildDiff sends two base paths onto one head path, or onto a path the base also skipped — git writes neitherthe same symbols[] and notCompared[], byte for byte, whatever order the map and the skip lists are in; a notCompared[] entry for each base record that reaches a head one (§3.5.1, §6.3)
DF19mTwo Symbols of one kind with no extKind, one logic fingerprint that names something and one syntax fingerprint, in two files, become one in a third filethe one the survivor pairs with is moved (§3.3); the other is removed with duplicateOf naming the survivor, and summary.removedDuplicates is 1. With the logic naming nothing, the survivor of another kind, its body written otherwise (same logic, other syntax), or an extKind on the removed Symbol (a Next.js GET in app/api/v1/users/route.ts deleted beside an identical one in app/api/v2/users/route.ts), the removal carries duplicateOf: null. A deleted twin of an unchanged Symbol names that Symbol; of several head Symbols with its body, the closest name, and the lower id of two equally close, whatever order the head lists them in (§3.5.2)
DF19nThe base holds a Component edge billing → pricing; the head skips a file under billing's root, or only one under pricing's (or the base skips one under billing's and the head holds the edge)dependencies.unknown with absentFrom: "head" and every skipped file of billing in lostFiles[], never removed; a file of pricing alone leaves the edge removed; the base skipping is unknown with absentFrom: "base" (§6.2.1)
DF20A pair whose stage-4 composite equals its row exactly: member 3/4 with signature 11/12, and member 7/10 with an identical signature, at 0.85; an identical member with signature 5/6 at 0.95; an identical member and signature at 1.0. End to end, AccountService.createUserAccount(a: string, b: number, c: Date, d: boolean) moved file and renamed createUserAccountRecord with d: Optionspaired, rationale: "name-signature" — the composite is a fraction compared exactly (§3.4.3); one step below (two of four inputs retyped, a member of 7/11, its only input retyped at 0.95 or 1.0) added: 1, removed: 1
DF20aTwo bases score the same composite for one head, made of different axes — one renamed its member (3/4, signature 11/12), the other kept it (1, signature 1/2)the lower base id pairs, whichever of the two it is (§3.8)
DF20bA Symbol whose name says too little, a Symbol with no signature, and a pair the owner gate refuses after clearing its row, each with a loggerthe same result as without one, byte for byte, and one debug line per Symbol or refused pair naming the rule (§3.4.7); none for a pair stage 4 made, one that scored below its row, one whose Symbols pair elsewhere, or an owner §3.4.8 paired through its members

10.1 Diff schema compatibility policy ​

The compatibility policy of aburi.diff.v1.json matches the IR schema (ir-schema.md §15). In particular, because the CI gate (aburi diff --fail-on) depends on it:

  • Adding a MatchRationale enum value is breaking (consumers' --fail-on settings depend on fixed values)
  • Adding a status enum value (added / removed / changed / moved / moved+changed / dropped-toggled / unknown) is breaking
  • Adding a summary field is non-breaking
  • Adding an optional SymbolDelta boolean is non-breaking, and the producer emits it unconditionally, false included, for the reason the next row gives
  • Adding an optional array is non-breaking on the same terms — to componentDiff / dependencyDiff or to the document itself — and carries one extra obligation: a reader must be able to tell "the writer had nothing to report" from "the writer predates the field". Where no arithmetic elsewhere in the document supplies that — which is everywhere in a diff — the producer emits the key unconditionally, empty included, and optionality in the schema covers only documents written before it existed. This is where the diff parts company with the IR, whose Class B fields (ir-schema.md §1.1) are omitted when empty: an IR reader can fall back on totalFiles - parsedFiles, and a diff reader has nothing to fall back on.
  • Adding an optional scalar to an entry is non-breaking, and unlike an array it may be left out when it has nothing to say, provided its absence is unambiguous by construction. NotComparedFile.basePath and SymbolUnknown.lostPath are the cases: each is written only when git renamed the file between the revisions, and a writer that predates them did not look across a rename at all, so it never produced an entry that needed one. In a document of either age, absence means "the other name is the same", and nothing has to be emitted to say so. throughMembers on a moved or moved+changed entry is another: a writer that predates it never paired an owner through its members (§3.4.8), so in a document of either age, absence means the pairing rests on its rationale alone. A scalar whose absence an older writer could have meant differently is emitted unconditionally, as the SymbolDelta booleans are, and as SymbolRemoved.duplicateOf is, null included: a writer that predates it reported every removal bare, duplicate or not (§3.5.2).

11. Design decisions ​

11.1 Why a 5-stage matching pipeline ​

A single mechanism (ID match only) produces massive false add/remove on file renames, method renames, and refactors. Applying multiple mechanisms sequentially, settling from the most trustworthy stage down, raises precision:

  1. ID match (definitive information)
  2. git rename (physically definitive)
  3. logic fingerprint match (semantic identity)
  4. name + signature similarity (heuristic)

The stage-4 threshold of 0.85 is provisional; it will be tuned on real projects.

11.2 Why dropped is excluded from stage 3 ​

Dropped symbols with fingerprint.logic = "000000000000" would "match" each other in bulk, producing meaningless pairs. Dropped symbols are settled first by stage 1 (exact ID match); the remainder is picked up cheaply by the dedicated weak matcher of stage 4.5 (lastSegment + basename, §3.4.5). Stage 4.5 runs with the false-positive risk priced in, under the premise that "dropped is outside the IR's primary field of view, so the impact is small" — but only on a key that identifies one symbol on each side, because a basename every symbol shares prices in no risk, it pairs at random.

11.3 Why line fuzz (±2) is used only for delta display ​

Including line numbers in fingerprint computation would change every logic FP the moment a single blank line is inserted. Fingerprints are kept line-free (fingerprint.md §4). However, listing rules that differ only in line as distinct items hurts delta readability. Lines therefore enter the delta only as offsets from the Symbol's first line, to pair an edited element with its predecessor (±2) and to rank equal sets of pairings (§5.2.0); both happen at display time only.

11.4 Why unchanged is excluded from the output ​

Emitting every unchanged Symbol would make the diff as large as the IR itself and impractical. Only a count is provided in the summary; for details, refer to the IR itself.

11.5 Why git is not required ​

In CI environments, git history can be shallow (shallow clone), so git rename detection is not always available. Making the fingerprint-based fallback (stage 3) mandatory keeps the diff working without git.

11.6 Purpose of collapsed Markdown sections ​

Symbols that are "move only" or "syntax only" need not be seen by reviewers. Collapsing them keeps PR comments readable while preserving all information. GitHub's <details> element is collapsed by default.

11.7 Why component / dependency diffs are separated from the Symbol diff ​

Component / Dependency changes are architecture-level changes. Mixing them with Symbol additions/removals hurts clarity. They are managed in separate top-level fields and given separate sections in the Markdown as well.

11.8 Why a plugin-set difference is a warning, not a field of the Diff ​

If base and head have different plugin sets, the same source yields different IRs. This is a difference in "observation", not "meaning". The diff works under the premise of "trusting the IR", so it does not discount a change it can trace to a plugin: it reports what the two documents say. The CLI compares the generator.plugins[] each IR records and warns on stderr when they differ (cli-spec.md §6.6), which needs no schema change and reaches the reviewer reading the run. A field in diff.json would be an additive change to aburi.diff.v1, and is left until a consumer of the artefact needs it.

Released under the Apache License 2.0.