@aburi/diff 0.2.0 → 0.3.0

package/LICENSE

@@ -1,21 +1,202 @@
-MIT License
-
-Copyright (c) 2026 kage1020
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 kage1020
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -43,8 +43,8 @@ import { buildDiff, writeCanonicalDiff } from "@aburi/diff"
 const diff = buildDiff({
   baseIR,
   headIR,
-  base: { ref: "main", irSchema: "https://aburi.dev/schema/aburi.ir.v1.json" },
-  head: { ref: "HEAD", irSchema: "https://aburi.dev/schema/aburi.ir.v1.json" },
+  base: { ref: "main", irSchema: "https://aburi.kage1020.com/schema/aburi.ir.v1.json" },
+  head: { ref: "HEAD", irSchema: "https://aburi.kage1020.com/schema/aburi.ir.v1.json" },
   gitRenames: null,          // optional: { oldPath: newPath } table
 })
 

package/dist/index.d.mts

@@ -1,22 +1,87 @@
 import { CallEdge, SerializeOptions } from "@aburi/core";
-import { Component, ComponentDiff, Dependency, DependencyDiff, DiffResult, IR, IRRef, MatchRationale, Signature, SliceRecord, Symbol, SymbolChange, SymbolDelta, SymbolId } from "@aburi/types";
+import { Component, ComponentDiff, Dependency, DependencyDiff, DependencyEndpoint, DependencyUnknown, DiffResult, IR, IRRef, MatchRationale, NotComparedFile, RelativePath, Signature, SkipReason, SliceRecord, Summary, Symbol, SymbolChange, SymbolDelta, SymbolId } from "@aburi/types";
 
 //#region src/components.d.ts
 /**
- * §6.1 — Component diff. Component identity is `id`; when a Component is present in both
+ * `docs/design/diff-algorithm.md` §6.1 — Component diff. Assumes `components[].id` is unique on each side (ir-schema.md §14
+ * #2) and does not check it: `buildDiff` establishes that before calling, and a caller
+ * reaching this export directly owns the obligation, because the lookup map here is
+ * last-write-wins and a repeat is lost rather than reported.
+ *
+ * Component identity is `id`; when a Component is present in both
  * base and head with the same id, the three delta booleans describe which axes actually
  * moved (roots reshuffle, public API globs, or framework hint list). `modified` deltas
- * are intentionally absent from this diff (§5.2.3): fields are reported as before/after
+ * are intentionally absent from this diff (diff-algorithm.md §5.2.3): fields are reported as before/after
  * pairs via the `changed[]` entries so consumers can render them without stringifying
  * arrays.
  */
 declare function diffComponents(base: readonly Component[], head: readonly Component[]): ComponentDiff;
 /**
- * §6.2 — Dependency diff. Identity is the composite `(from, to, via)` triple; direction
- * and effect changes are surfaced as an added + removed pair so `modified` is not part of
- * the schema (§6.2 tail).
+ * What one document knows about itself, for deciding whether the *other* document's silence
+ * about an edge is evidence.
+ *
+ * `symbolFiles` is keyed on the endpoint id exactly as `dependencies[]` spells it, and its
+ * values come from `symbols[].source.file` — the same space `stats.skippedFiles[].path` is in,
+ * and the same space `buildDiff` classifies Symbols by. Reading the file out of the id's path
+ * segment instead would introduce a second answer to "which file is this endpoint in", and
+ * nothing in the schema forces the two to agree; a Symbol reported `unknown` while its edges
+ * stayed `removed` is precisely the inconsistency this exists to remove.
+ *
+ * A Component endpoint is absent from the map, which is how it stays out of the reclassification
+ * without a special case: a Component is an aggregate over roots and has no file to lose.
  */
-declare function diffDependencies(base: readonly Dependency[], head: readonly Dependency[]): DependencyDiff;
+interface DependencySideView {
+  /**
+   * `source.file` of every Symbol this document holds, by the id an endpoint would name it
+   * with. Keyed by `DependencyEndpoint` rather than `SymbolId` because that is the question
+   * being asked: the lookup happens with an endpoint whose kind is not yet known, and "absent"
+   * is the answer for a Component id. Demanding the kind up front would move that decision to
+   * the caller, where it would need a second Symbol-id silhouette test to make.
+   */
+  symbolFiles: ReadonlyMap<DependencyEndpoint, RelativePath>;
+  /**
+   * Files this document never analysed, by path, with the reason it gave. `RelativePath` on
+   * both sides of the file space is what states the bridge these two maps exist to make — one
+   * map's values are the other's keys — though the alias is unbranded, so it is intent rather
+   * than enforcement.
+   */
+  lostFiles: ReadonlyMap<RelativePath, SkipReason>;
+}
+/**
+ * Build a side view from a document. The only construction site there is.
+ *
+ * `buildDiff` reads `lostFiles` for its own Symbol classification too, from this same object,
+ * so "a Symbol reported unknown and the edges it took with it cannot disagree about which file
+ * went missing" is a property of the wiring rather than a claim in a comment.
+ *
+ * Exported because `DependencySideView` is public and `diffDependencies` requires one: without
+ * a factory a caller would have to reproduce the `symbols[].source.file` keying and the
+ * `stats.skippedFiles` read, and the likeliest outcome of that is a caller who gets it wrong.
+ */
+declare function dependencySideView(ir: IR): DependencySideView;
+/**
+ * `docs/design/diff-algorithm.md` §6.2 — Dependency diff. Identity is the composite
+ * `(from, to, via)` triple; direction and effect changes are surfaced as an added + removed
+ * pair so `modified` is not part of the schema (§6.2 tail). Uniqueness of that triple is the caller's obligation on the same
+ * terms as `diffComponents` above — a repeat here is indistinguishable in the output from
+ * the flip it encodes.
+ *
+ * `sides` is what separates a deletion from a loss (`docs/design/diff-algorithm.md` §6.2.1).
+ * It is required rather than optional: omitting it would classify every edge into a lost file
+ * as a deletion again — silently, and while still writing `unknown: []`, which this schema
+ * defines as "nothing was unknown" rather than "nobody looked". A caller with no skip list to
+ * offer says so by passing a side view whose `lostFiles` is empty, which is the honest spelling
+ * of an IR written before `stats.skippedFiles` existed.
+ *
+ * The return type declares `unknown` present, where the schema leaves it optional for documents
+ * that predate the field. A reader may find it missing; this function always writes it.
+ */
+declare function diffDependencies(base: readonly Dependency[], head: readonly Dependency[], sides: {
+  base: DependencySideView;
+  head: DependencySideView;
+}): DependencyDiff & {
+  unknown: DependencyUnknown[];
+};
 //#endregion
 //#region src/delta.d.ts
 declare const DEFAULT_LINE_FUZZ = 2;
@@ -55,6 +120,13 @@ type GitRenameMap = ReadonlyMap<string, string>;
 /**
  * §3.1 — segments Symbols with identical `id` into paired matches. Runs first because it
  * is the highest-confidence signal (no heuristics, just hash lookup).
+ *
+ * Assumes `id` is unique on each side (ir-schema.md §14 #1) and does not check it:
+ * `buildDiff` establishes that before calling, and a caller reaching this export directly
+ * owns the obligation. A repeat on the head side loses all but the last entry to the lookup
+ * map and then removes every one of them from `remainingHead`; a repeat on the base side
+ * pairs the same head Symbol more than once. The later stages track consumed base Symbols
+ * by id and lose a repeat the same way.
  */
 declare function matchStageId(base: readonly Symbol[], head: readonly Symbol[]): {
   matched: SymbolPair[];
@@ -63,7 +135,9 @@ declare function matchStageId(base: readonly Symbol[], head: readonly Symbol[]):
 };
 /**
  * §3.2 — git rename detection. When a rename map is available (typical of ref-driven
- * scans), rewrite the base id with the head-side file path and look for a hit.
+ * scans), rewrite the base id with the head-side file path and look for a hit. Two base
+ * files renamed onto one target predict the same head id, so the claimants are collected
+ * before one is chosen.
  *
  * The rewriter only touches the `file` portion of the id — the `<language>:` prefix and
  * the trailing `#<qualified-name>` segment stay unchanged so a moved file with the same
@@ -76,11 +150,10 @@ declare function matchStageGitRename(remainingBase: readonly Symbol[], remaining
   remainingHead: Symbol[];
 };
 /**
- * §3.3 — group base Symbols by `fingerprint.logic` and match head Symbols whose logic
- * fingerprint is in the map. Two disambiguation branches:
- * - single candidate → paired with `logic-fingerprint`
- * - multiple candidates → best `nameSimilarity` wins if ≥ 0.85; otherwise leave both
- *   sides in remaining for stage 4 to re-evaluate
+ * §3.3 — group both sides by `fingerprint.logic` and pair within each group. Two branches:
+ * - single base candidate → paired with `logic-fingerprint`, no similarity test
+ * - several → `nameSimilarity` disambiguates at ≥ 0.85; a group that cannot reach it is left
+ *   whole for stage 4 to re-evaluate
  *
  * Dropped symbols are excluded (§3.3 tail) — their logic fingerprint is the sentinel
  * `"000000000000"` and would collide with every other dropped Symbol in the workspace.
@@ -96,17 +169,35 @@ declare function matchStageLogicFingerprint(remainingBase: readonly Symbol[], re
  * `signatureNullness` distinguishes symbols with no signature (`interface`, `type`,
  * `class`) from callable ones so that a class body is never paired against a function.
  *
- * The composite score:
- *   0.5 * nameSimilarity + 0.3 * signatureSimilarity + 0.2 * ownerSimilarity
+ * §3.4.6's owner gate runs before the score: a pair whose owners are not the same class, or
+ * one a rename of the other, is not the same Symbol however well the rest agrees, and no
+ * weight small enough to leave the name axis meaning something can outvote a matching member
+ * name and signature.
+ *
+ * The composite score, over the pairs that clear it:
+ *   0.5 * memberSimilarity + 0.3 * signatureSimilarity + 0.2 * OWNER_AXIS_SATISFIED
+ *
+ * `memberSimilarity` reads the last segment, not the whole qualified name: the gate has
+ * already settled the owner, and reading it again on the name axis charges for it twice —
+ * which is what kept a renamed class from ever pairing (§3.4.6).
+ *
+ * §3.4.3 threshold table, applied per head by the token count of its last name segment:
+ * - 1 token  → 1.0 (an exact match on both remaining axes)
+ * - 2 tokens → 0.95 (strict, avoids `getUser` vs `getUsers`)
+ * - default  → 0.85
  *
- * §3.4.3 threshold table:
- * - 1-token name → 1.0 (unreachable → never paired; false-positive shield)
- * - 2-token name → 0.95 (strict, avoids `getUser` vs `getUsers`)
- * - default      → 0.85
+ * §3.4.3 also names two Symbols the stage does not read at all, because for them the score is
+ * high on evidence it does not have rather than on a resemblance: one whose signature is
+ * null, since `signatureSimilarity(null, null)` is 1.0 and the bucket key restricts it to
+ * candidates that are equally signature-less; and one whose qualified name carries a single
+ * distinct token, since that is the whole of what its identity amounts to. Neither can be
+ * expressed as a threshold — the second wants a bar above the top of the scale.
  *
- * §3.4.3 tail — if both sides are signature-less, we skip pairing entirely because
- * signatureSimilarity always returns 1.0 for `null + null` and would flood the bucket with
- * false pairings.
+ * Every pairing in a bucket that clears its head’s threshold becomes a candidate, and the
+ * candidates are settled in score order rather than one head at a time — see
+ * `acceptInScoreOrder`. That doubles the pairings scored, from a bucket that shrank as heads
+ * consumed it to the full bucket every time; `createNameScorer` more than pays for it by
+ * tokenising each distinct name once per pass instead of once per comparison.
  */
 declare function matchStageNameSignature(remainingBase: readonly Symbol[], remainingHead: readonly Symbol[]): {
   matched: SymbolPair[];
@@ -114,13 +205,32 @@ declare function matchStageNameSignature(remainingBase: readonly Symbol[], remai
   remainingHead: Symbol[];
 };
 /**
- * §3.4.5 — dropped-only weak matcher. For dropped Symbols the fingerprint is zeroed and
- * name/signature are the only remaining signals. Score is a coarse "did the last name
- * segment or file basename survive?" — if either half matches we pair (threshold 0.5).
+ * §3.4.5 — dropped-only weak matcher. For dropped Symbols the fingerprint is zeroed, so the
+ * only signals left are the trailing segment of the qualified name and the file basename.
+ * Either one alone is enough to pair, which is deliberately lax: §3.4.5 accepts a
+ * false-positive risk because dropped Symbols sit outside the IR's main review surface.
  *
- * This is deliberately lax; diff-algorithm.md §3.4.5 already accepts that dropped Symbols live
- * outside the main IR review surface, so occasional false pairings only affect the
- * "Drop-rule variation" fold-out section in the Markdown projection.
+ * What it does not accept is a signal that identifies nothing. A basename hit on `index.ts`
+ * — the most common filename in a TypeScript monorepo — paired every dropped Symbol of one
+ * kind under one with every other, at a score they all tied on, and the results landed in
+ * `summary.moved`, which `--fail-on moved` gates on. So a half counts only when exactly one
+ * dropped base and one dropped head carry that key: such a key names a pair, where a key
+ * several Symbols carry names a group, and a group is not a pairing.
+ *
+ * That makes the candidates the identifying keys themselves — at most one pairing each,
+ * two axes, so at most `2 × min(base, head)` of them rather than the cross-product a shared
+ * basename used to produce.
+ *
+ * "Exactly one" is counted over the Symbols this stage is handed, not over every dropped
+ * Symbol in the Document — stages 1 and 2 have already taken theirs, and a key they emptied
+ * out identifies again. That is the intended reading, since the question is which leftover a
+ * key picks out, but it is also how a shared `index.ts` comes back: three dropped classes
+ * under one, two of them matched by id, and the basename identifies the two that are left.
+ *
+ * It also leaves nothing for §3.4.5's 0.5-per-half scale to rank, so §3.8's sweep is the
+ * wrong instrument: it settles conflicts by score, and with none to settle by it would drop
+ * one identified pairing for another over nothing but the id it sorts under. `bestPairing`
+ * takes a maximum matching instead.
  */
 declare function matchStageDroppedWeak(remainingBase: readonly Symbol[], remainingHead: readonly Symbol[]): {
   matched: SymbolPair[];
@@ -129,6 +239,18 @@ declare function matchStageDroppedWeak(remainingBase: readonly Symbol[], remaini
 };
 //#endregion
 //#region src/diff.d.ts
+/**
+ * The two counters `buildDiff` always writes, narrowed off `Summary`'s optionals.
+ *
+ * They are optional on the wire so a diff written before they existed stays valid, and that
+ * optionality is about *documents*, not about this function — a caller holding a value it just
+ * built should not have to re-decide what "absent" would have meant. Same reason
+ * `diffDependencies` declares its `unknown` array present.
+ */
+interface UnknownCounters {
+  unknown: number;
+  depsUnknown: number;
+}
 interface DiffInput {
   baseIR: IR;
   headIR: IR;
@@ -152,7 +274,19 @@ interface DiffInput {
  * pipe the result through additional steps (Markdown projection, `--fail-on` gate) before
  * serialisation.
  */
-declare function buildDiff(input: DiffInput): DiffResult;
+declare function buildDiff(input: DiffInput): DiffResult & {
+  notCompared: NotComparedFile[];
+  summary: Summary & UnknownCounters;
+};
+/**
+ * The files a document's scan never analysed, by path, with why.
+ *
+ * `stats.skippedFiles` is Class B: absent means the writer predates the field, not that
+ * nothing was lost. An empty map is the honest answer either way — with no enumeration
+ * there is no absence this function can explain, and guessing from
+ * `totalFiles > parsedFiles` would attach a reason to whichever Symbols happened to be
+ * missing. The CLI says so on stderr instead; a diff cannot invent the list.
+ */
 /**
  * Byte-deterministic serialiser for a DiffResult. Delegates to `@aburi/core`
  * `serializeCanonical` so the sort order, NFC normalisation, and codepoint key sort are
@@ -173,6 +307,13 @@ type DiffErrorCode = /** `base.$schema` and `head.$schema` disagree; a diff acro
  * cryptic `TypeError: undefined is not iterable` deep in a matching stage.
  */
 | "ir-shape-invalid"
+/**
+ * `baseIR` or `headIR` repeats an identity the diff keys on: a `symbols[].id`, a
+ * `components[].id`, or a `dependencies[]` `(from, to, via)` triple. Distinct from
+ * `ir-shape-invalid` because the Document is well-formed — the collision changes the
+ * answer rather than preventing one, and ir-schema.md §14 #1 / #2 / #13 already forbid it.
+ */
+| "ir-identity-collision"
 /**
  * A `SliceRecord` broke the derivation invariant of slice-view.md §7.1 / §8.2:
  * `members[]` empty, `members[]` not in strictly ascending order, or `id` not
@@ -229,6 +370,15 @@ declare function signatureSimilarity(base: Signature | null | undefined, head: S
  * The result is de-duplicated so `InvoiceService.createInvoice` collapses to
  * `["invoice", "service", "create"]` — Jaccard similarity relies on set semantics, so
  * repeated tokens must not double-count.
+ *
+ * **The camel boundary is ASCII.** `isCamelBoundary` compares code points against `a`–`z`,
+ * `A`–`Z` and `0`–`9`, so a name written in a script with no ASCII case boundary and no
+ * separator comes back whole: `获取用户信息` and `ユーザー情報を取得する` are one token each,
+ * and so is `получитьПользователя` — its camel hump does not register. A separator still
+ * splits (`ユーザー.取得` gives two), and a mixed name splits on its ASCII half.
+ *
+ * That makes the token count a poor measure of how much such a name says, which matters
+ * wherever a count is read as a proxy for that — see §3.4.3's admissibility rule.
  */
 declare function tokenizeName(input: string): string[];
 /**
@@ -237,7 +387,11 @@ declare function tokenizeName(input: string): string[];
  * purpose of §3.4.1). Empty on one side only returns 0.0.
  */
 declare function jaccard(a: readonly string[], b: readonly string[]): number;
-/** name-token Jaccard shortcut used by nameSimilarity and ownerSimilarity call sites. */
+/**
+ * Jaccard over the tokens of two strings. Part of the module's surface rather than an
+ * internal shortcut: the two formulas below go through a token table they share for one
+ * matching pass, so this has no caller inside this file.
+ */
 declare function jaccardTokens(a: string, b: string): number;
 /**
  * §3.4.1 — Jaccard over the tokens of the full qualified name. The last segment is not
@@ -246,20 +400,36 @@ declare function jaccardTokens(a: string, b: string): number;
  */
 declare function nameSimilarity(baseName: string, headName: string): number;
 /**
- * §3.4.6 — owner similarity: same as nameSimilarity but restricted to everything **before**
- * the last segment. Compensates for the R-8 same-name-different-class collision, where
- * `UserRepo.getUser` should not be pair-swapped with `AdminRepo.getUser`.
+ * §3.4.1 — Jaccard over the tokens of the **last segment**: the member name with its owner
+ * removed. What §3.4's composite reads, because §3.4.6 decides the owner separately and
+ * reading it on both axes charges for it twice.
+ */
+declare function memberSimilarity(baseName: string, headName: string): number;
+/**
+ * §3.4.6 (R-8) — whether two Symbols are close enough in *scope* to be the same Symbol: the
+ * same owner, or one whose owner was renamed. A gate rather than a score, because grading the
+ * owner cannot do what R-8 asks. `UserRepo.findById` and `AdminRepo.findById` agree on their
+ * member name and their signature, so a shared `Repo` token at weight 0.2 carries them to
+ * 0.8667 against a 0.85 threshold — while `UsersRepository.findById`, which *is* the rename,
+ * shares no owner token and scores 0.8000. The collision outscores the rename, and raising the
+ * weight only moves both: at 0.3 two three-token class names sharing two tokens land on
+ * exactly 0.85.
  *
  * Owner extraction:
  * - `Class::method` → `Class`
  * - `A.B.C.method` → `A.B.C`
  * - `topLevel`     → `` (empty)
  *
- * When both owners are empty (top-level functions), returns 1.0 because both live in the
- * same "no-owner" bucket. When one is empty and the other is not, returns 0.0 because the
- * two Symbols live in structurally different scopes.
+ * Two empty owners are compatible: top-level Symbols share the one outer scope. One empty and
+ * one not are never compatible — the two live at different depths.
+ *
+ * Otherwise the owners must correspond segment for segment, and within a segment every token
+ * on each side must find a distinct partner on the other under `sameWord`. Both sides must be
+ * covered, so `UserRepo` and `UserRepoV2` are two classes rather than one renamed — an added
+ * token is as much evidence of a sibling as of a rename, and R-8's business is refusing the
+ * collision.
  */
-declare function ownerSimilarity(baseName: string, headName: string): number;
+declare function ownersAreCompatible(baseName: string, headName: string): boolean;
 /** §3.4.1 tail note — used by drop-4.5 weak matcher and threshold lookup. */
 declare function lastSegment(qname: string): string;
 //#endregion
@@ -355,5 +525,5 @@ declare function classifyStatus(base: Symbol, head: Symbol): SymbolStatus;
 type DropDirection = "to-dropped" | "to-kept";
 declare function dropDirection(head: Symbol): DropDirection;
 //#endregion
-export { DEFAULT_LINE_FUZZ, type DeltaOptions, DiffError, type DiffErrorCode, type DiffErrorDetail, type DiffInput, type DropDirection, type GitRenameMap, MAX_LINE_FUZZ, MIN_LINE_FUZZ, type SliceInput, type SliceRecordViolation, type SliceViolationKind, type SymbolPair, type SymbolStatus, assertSliceRecordInvariant, buildDiff, classifyStatus, computeSlices, computeSymbolDelta, diffComponents, diffDependencies, dropDirection, jaccard, jaccardTokens, lastSegment, matchStageDroppedWeak, matchStageGitRename, matchStageId, matchStageLogicFingerprint, matchStageNameSignature, nameSimilarity, ownerSimilarity, signatureSimilarity, sliceAnchor, sliceRecordViolation, tokenizeName, writeCanonicalDiff };
+export { DEFAULT_LINE_FUZZ, type DeltaOptions, type DependencySideView, DiffError, type DiffErrorCode, type DiffErrorDetail, type DiffInput, type DropDirection, type GitRenameMap, MAX_LINE_FUZZ, MIN_LINE_FUZZ, type SliceInput, type SliceRecordViolation, type SliceViolationKind, type SymbolPair, type SymbolStatus, assertSliceRecordInvariant, buildDiff, classifyStatus, computeSlices, computeSymbolDelta, dependencySideView, diffComponents, diffDependencies, dropDirection, jaccard, jaccardTokens, lastSegment, matchStageDroppedWeak, matchStageGitRename, matchStageId, matchStageLogicFingerprint, matchStageNameSignature, memberSimilarity, nameSimilarity, ownersAreCompatible, signatureSimilarity, sliceAnchor, sliceRecordViolation, tokenizeName, writeCanonicalDiff };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/components.ts","../src/delta.ts","../src/match.ts","../src/diff.ts","../src/errors.ts","../src/signature.ts","../src/similarity.ts","../src/slice.ts","../src/status.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/components.ts","../src/delta.ts","../src/match.ts","../src/diff.ts","../src/errors.ts","../src/signature.ts","../src/similarity.ts","../src/slice.ts","../src/status.ts"],"mappings":"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"}