graphmark 0.3.4__tar.gz → 0.4.0__tar.gz

{graphmark-0.3.4 → graphmark-0.4.0}/CHANGELOG.md

@@ -1,6 +1,84 @@
 # CHANGELOG
 
 
+## v0.4.0 (2026-07-25)
+
+### Features
+
+- **graph**: Add diagnose() — why a link failed, not just that it did (#111)
+  ([#114](https://github.com/cdcoonce/graphmark/pull/114),
+  [`1d124a3`](https://github.com/cdcoonce/graphmark/commit/1d124a3423fc5a6f3c8a0a084e8d15927dd1d828))
+
+Track E slice 2. graph.unresolved conflates two problems needing opposite repairs: a link matching
+  NOTHING wants its target created or deleted, a link matching TOO MUCH wants disambiguating against
+  what it collided with. A consumer holding only unresolved cannot tell them apart, so it rebuilds
+  the resolver — the drift this track exists to end.
+
+diagnose(graph, display) returns a frozen LinkDiagnosis: display echoed verbatim, target when
+  resolved, one of the six DIAGNOSIS_REASONS, and the rel_paths in play (the colliding notes for
+  ambiguous, the unindexed markdown for out-of-scope-note). The reason set is exported as a tuple in
+  decision order so a consumer can switch on it exhaustively.
+
+build() now classifies through the same function rather than agreeing with it separately — two
+  classifiers in one package would recreate the drift inside the package. Two property tests pin
+  them together: unresolved is exactly the ambiguous+missing displays, edges are exactly the
+  resolved non-self targets.
+
+candidates_for() consolidates the two-branch matching that _targets_out_of_scope_note had duplicated
+  from the resolver. It reports matches only; deciding uniqueness stays the Resolver's job, so the
+  two cannot disagree about which notes were in play. The graph now also retains the resolver it was
+  built with, so a diagnosis can never contradict its own graph.
+
+Behavior is unchanged: on the live vault, 130 unresolved / 3582 edges both before and after, and all
+  six frozen fixtures byte-identical. What is new is the answer — 8 of those 130 are ambiguous
+  collisions ([[2026-W27-tasks]] existing under both personal/archive and work/archive,
+  [[RESOURCES]] under four learning folders), which the old surface reported as plain breaks.
+
+- **graph**: Retain catalog + out_of_scope on the built graph (#110)
+  ([#113](https://github.com/cdcoonce/graphmark/pull/113),
+  [`7f7a91c`](https://github.com/cdcoonce/graphmark/commit/7f7a91cae961a06155f565384a429c92356868fb))
+
+* docs(roadmap): close Tracks C and D, open Track E (#110-#112)
+
+afk-driver --expand reads this file verbatim, so a stale one makes the fleet propose already-built
+  work and pollutes the telemetry dataset. It still targeted "v0.2.0 — every error path tested"
+  while the package is 0.3.4 with Tracks C and D both fully shipped.
+
+Track C closed (every item landed at 0.2.0). Track D marked shipped at 0.3.0, with its real
+  remaining risk named: the credibility of its flagship number. Four false-positive classes have now
+  been found by triaging a live vault against max_unresolved_links — #98 anchors (19%), #101
+  non-markdown (10%), #104 the .md extension, #107 out-of-scope notes (7%) — so "keep truthing the
+  metric before shipping a GitHub Action that fails someone's build" is the direction, not more
+  surface.
+
+Track E opened: absorb the consumer's second link stack. graphmark says whether a link resolves; the
+  gardener needs to know why it failed and what to do about it, which is why it still carries its
+  own resolver and why #107 had to be fixed in two places. Sliced #110/#111/#112, with #112 flagged
+  not-autonomous-safe past freezing the baseline — its expected values are human judgment, not
+  oracle-derived.
+
+* feat(graph): retain catalog + out_of_scope on the built graph (#110)
+
+Track E slice 1. build() computed both mappings and threw both away, so a consumer that needs to say
+  anything about a link beyond "resolved / didn't" had to rebuild the entire parse/catalog/resolve
+  stack. the-vault's graph_gardener.py does exactly that, and the two stacks drift: #107 was the
+  fourth resolution fix that had to be applied in two places.
+
+graph.catalog is normalized stem → in-scope rel_paths; a key with two or more paths IS an ambiguity
+  set, which is what lets a consumer say WHICH notes a bare link collided with instead of only that
+  it failed. graph.out_of_scope is the same for markdown outside the configured scope, retained from
+  #107. Both are constructor-optional, so three-positional construction keeps working.
+
+Value lists are sorted by rel_path explicitly rather than inheriting the walk's order. Those
+  disagree: sorted(rglob) orders Path objects by parts tuple, yielding a/note.md before a-b/note.md,
+  while rel_path string order is the reverse ('-' < '/'). The first version of the ordering tests
+  used paths where the two agree, so deleting the sorts left the suite green — caught by mutation,
+  and the tests now use the discriminating case.
+
+No behavior change: nothing about what resolves or what an edge is moves, and every frozen fixture
+  is byte-identical.
+
+
 ## v0.3.4 (2026-07-25)
 
 ### Bug Fixes

{graphmark-0.3.4 → graphmark-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphmark
-Version: 0.3.4
+Version: 0.4.0
 Summary: Deterministic knowledge-graph analysis for markdown / [[wikilink]] vaults.
 Project-URL: Homepage, https://github.com/cdcoonce/graphmark
 Project-URL: Repository, https://github.com/cdcoonce/graphmark
@@ -183,8 +183,46 @@ graphmark.siloed_notes(graph)                 # reachable only through a single
 graphmark.neighborhood(graph, "a/b.md", depth=2)
 graphmark.to_dot(graph)                       # Graphviz DOT
 graph.unresolved                              # {rel_path: [broken link displays]}
+graph.catalog                                 # {normalized stem: [rel_paths]} — 2+ means ambiguous
+graph.out_of_scope                            # same, for markdown outside the configured scope
 ```
 
+`catalog` and `out_of_scope` are the resolution state the build consulted. They are what you need to
+explain a link rather than just resolve it — which notes a bare `[[link]]` collided with, or whether
+a link that failed to resolve points at a real file you deliberately excluded. Value lists are
+sorted by rel_path.
+
+## `diagnose` — why a link failed, not just that it did
+
+`graph.unresolved` conflates two different problems. A link that matched _nothing_ needs its target
+created or deleted; a link that matched _too much_ needs disambiguating against the notes it
+collided with. `diagnose` separates them, and names the three cases that are not broken at all.
+
+```python
+d = graphmark.diagnose(graph, "2026-W27-tasks|W27 tasks")
+
+d.reason      # 'ambiguous'
+d.candidates  # ('personal/archive/tasks/2026-W27-tasks.md', 'work/archive/2026/tasks/2026-W27-tasks.md')
+d.target      # None — set only when reason == 'resolved'
+d.display     # echoed verbatim: what a human has to go and fix
+```
+
+| `reason`            | meaning                                                        | `candidates`        |
+| ------------------- | -------------------------------------------------------------- | ------------------- |
+| `resolved`          | names exactly one note; `target` is its rel_path               | —                   |
+| `ambiguous`         | names several notes, so the resolver refused to pick           | the colliding notes |
+| `non-note-file`     | targets a `.canvas` / `.base` / image / PDF — not indexed here | —                   |
+| `out-of-scope-note` | targets real markdown outside the configured scope             | the unindexed paths |
+| `missing`           | names nothing that exists — a genuine broken link              | —                   |
+| `intra-note`        | `[[#Heading]]` / `[[#^block]]` — a same-note reference         | —                   |
+
+`DIAGNOSIS_REASONS` holds that set in decision order, so a consumer can switch on it exhaustively.
+Alias, anchor and `.md` forms all diagnose identically to the bare form.
+
+`VaultGraph.build` classifies its own links through this same function, so a diagnosis can never
+contradict the graph it describes: `unresolved` is exactly the displays diagnosing as `ambiguous` or
+`missing`, and the edges are exactly the `resolved` non-self targets.
+
 ## Configuration
 
 ```toml

{graphmark-0.3.4 → graphmark-0.4.0}/README.md

@@ -156,8 +156,46 @@ graphmark.siloed_notes(graph)                 # reachable only through a single
 graphmark.neighborhood(graph, "a/b.md", depth=2)
 graphmark.to_dot(graph)                       # Graphviz DOT
 graph.unresolved                              # {rel_path: [broken link displays]}
+graph.catalog                                 # {normalized stem: [rel_paths]} — 2+ means ambiguous
+graph.out_of_scope                            # same, for markdown outside the configured scope
 ```
 
+`catalog` and `out_of_scope` are the resolution state the build consulted. They are what you need to
+explain a link rather than just resolve it — which notes a bare `[[link]]` collided with, or whether
+a link that failed to resolve points at a real file you deliberately excluded. Value lists are
+sorted by rel_path.
+
+## `diagnose` — why a link failed, not just that it did
+
+`graph.unresolved` conflates two different problems. A link that matched _nothing_ needs its target
+created or deleted; a link that matched _too much_ needs disambiguating against the notes it
+collided with. `diagnose` separates them, and names the three cases that are not broken at all.
+
+```python
+d = graphmark.diagnose(graph, "2026-W27-tasks|W27 tasks")
+
+d.reason      # 'ambiguous'
+d.candidates  # ('personal/archive/tasks/2026-W27-tasks.md', 'work/archive/2026/tasks/2026-W27-tasks.md')
+d.target      # None — set only when reason == 'resolved'
+d.display     # echoed verbatim: what a human has to go and fix
+```
+
+| `reason`            | meaning                                                        | `candidates`        |
+| ------------------- | -------------------------------------------------------------- | ------------------- |
+| `resolved`          | names exactly one note; `target` is its rel_path               | —                   |
+| `ambiguous`         | names several notes, so the resolver refused to pick           | the colliding notes |
+| `non-note-file`     | targets a `.canvas` / `.base` / image / PDF — not indexed here | —                   |
+| `out-of-scope-note` | targets real markdown outside the configured scope             | the unindexed paths |
+| `missing`           | names nothing that exists — a genuine broken link              | —                   |
+| `intra-note`        | `[[#Heading]]` / `[[#^block]]` — a same-note reference         | —                   |
+
+`DIAGNOSIS_REASONS` holds that set in decision order, so a consumer can switch on it exhaustively.
+Alias, anchor and `.md` forms all diagnose identically to the bare form.
+
+`VaultGraph.build` classifies its own links through this same function, so a diagnosis can never
+contradict the graph it describes: `unresolved` is exactly the displays diagnosing as `ambiguous` or
+`missing`, and the edges are exactly the `resolved` non-self targets.
+
 ## Configuration
 
 ```toml

{graphmark-0.3.4 → graphmark-0.4.0}/docs/ROADMAP.md

@@ -22,11 +22,13 @@ story** — the priority consumer is the owner's vault seam (`graph_cli.py`), no
 
 ## What's shipped (baseline — do not re-propose)
 
-- **The full engine, v0.1.1 on PyPI**: `parse.py` (wikilink extraction, code-span skipping),
-  `graph.py` (catalog + `NormalizeResolver` + `VaultGraph.build`), `metrics.py` (stats, orphans,
-  hubs, clusters, bridges, siloed_notes, neighborhood, pure-python pagerank, gaps),
-  `export.py` (JSON/DOT), `cli.py`, `config.py` (`VaultConfig` + `load_config`), and
-  `dismiss.py` (content-hash weaklink dismissal store).
+- **The full engine, v0.3.4 on PyPI**: `parse.py` (wikilink extraction, code-span skipping),
+  `graph.py` (catalog + `NormalizeResolver` + `VaultGraph.build` + `unresolved`), `metrics.py`
+  (stats, orphans, hubs, clusters, bridges, siloed_notes, neighborhood, pure-python pagerank,
+  gaps), `check.py` (policy evaluation), `export.py` (JSON/DOT), `cli.py`, `config.py`
+  (`VaultConfig` + `CheckPolicy` + `load_config`), and `dismiss.py` (content-hash weaklink
+  dismissal store). Tracks A, C and D are all closed — read their sections before proposing
+  anything in those areas.
 - **Six frozen differential fixtures** — simple, alt, scoped, selflink, gaps (+ out-of-graph),
   dismiss — plus live-vault parity diffs against the reference engine.
 - **`gaps()` with injected similarity** — graphmark owns the deterministic ranking/filtering
@@ -41,38 +43,59 @@ story** — the priority consumer is the owner's vault seam (`graph_cli.py`), no
 
 ### Track A — Engine parity (CLOSED at v0.1.1 — do not re-propose engine work)
 
-### Track C — Hardening & honest surface (gate-verifiable; autonomous-safe)
+### Track C — Hardening & honest surface (CLOSED at v0.2.0 — do not re-propose)
 
-_Where we are:_ v0.1.1 is correct on its parity paths but carries correctness debt and dead
-surface no consumer exercises.
-_Where we're going:_ **v0.2.0 — every error path tested, every public knob real.**
+Every item shipped: version single-sourcing, non-UTF8 notes, dismiss-store JSON guards,
+`load_config` errors, DOT escaping, `neighborhood` on an unknown note, the dead-surface cut
+(`model.Edge/Graph/Finding` gone — `Document` is the only model type; the no-op `wikilink_pattern`
+/ `orphan_min_chars` knobs gone; the CLI `gaps` stub exits 2), the `GAPS_DEFAULT_*` banding
+constants, and the `Similarity` Protocol. `py.typed`, the 3.11–3.13 CI matrix, `--version`, and
+unified exit-code 2 for usage errors came with it.
 
-- Version single-sourcing (pyproject / `__init__.__version__` / smoke-test drift).
-- Robustness: non-UTF8 note handling in `parse_document`; JSON-corruption guards in
-  `dismiss.load_dismissed` / `active_dismissed_sigs`; `load_config` clear error on missing keys;
-  DOT identifier escaping in `to_dot`; defined behavior for `neighborhood` on an unknown note.
-- Cut or wire dead surface: `model.Edge/Graph/Finding` (never consumed — **removed in the 0.2 API
-  cut; `Document` is the only model type**); the CLI `gaps` stub
-  (null `similar_fn` — always `[]`); the silent no-op config knobs `wikilink_pattern` and
-  `orphan_min_chars` (wire them or delete them); make the dismissal-store path injectable instead
-  of hardcoding `.claude/data/connect-dismissed.json`.
-- Move the validated gaps banding policy (threshold / max-score / k / hub-degree defaults) from the
-  consumer's argparse into the package so any consumer gets the proven band.
-- A `Similarity` Protocol in `interfaces.py` typing the injected `similar_fn`.
-
-_The principle:_ each slice is single-purpose with its asserting test **pre-frozen by the
-conductor before dispatch** — the oracle-first discipline that closed the zero-test hole.
-
-### Track D — `graphmark check`: the deterministic CI gate (feature track)
+### Track D — `graphmark check`: the deterministic CI gate (SHIPPED at v0.3.0)
 
 The one unserved niche the ecosystem offers: **headless vault-health gating**. Obsidian's official
 CLI requires the desktop app; the dormant Python incumbent has no CLI; link checkers do no graph
 metrics.
 
-- `graphmark check --config ...` — thresholds (max orphans, max unresolved links, max siloed
-  notes, ...), non-zero exit on breach, byte-stable JSON report for diffing across runs.
-- Config-driven policy block (`[check]` in the TOML) so the gate is declarative.
-- Later: a thin GitHub Action wrapper. The owner's vault dogfoods the gate first.
+Shipped: `graph.unresolved`, the `[check]` policy block (`max_orphans` /
+`max_unresolved_links` / `max_siloed`, strict on unknown keys), `graphmark check` with exit 1
+reserved for breach and a byte-stable JSON report, `graphmark.build()` + curated top-level
+re-exports, and a README rewritten around the real surface.
+
+_Where we are (0.3.4):_ the gate works and the vault dogfoods it. The remaining risk is the
+**credibility of its flagship number**. Four false-positive classes have been found and fixed by
+triaging a real vault against the metric — same-note anchors (#98, 19% of the count),
+non-markdown targets (#101, 10%), the `.md` extension (#104), and links to notes that exist but
+are out of graph scope (#107, 7%). A threshold nobody trusts is not a gate.
+
+_Where we're going:_ keep truthing the metric against live vaults, then the thin GitHub Action
+wrapper — but only once the count is trustworthy enough to fail someone's build.
+
+### Track E — One resolver: absorb the consumer's second link stack (feature track)
+
+_The problem:_ the-vault's `graph_gardener.py` (Lane A) carries its **own** parse / catalog /
+normalize / resolve stack, independent of this package's. The two drift, and drift here is
+user-visible: the gardener spent weeks proposing repairs for working links that graphmark had
+already learned were fine. #107 is the fourth fix that had to be applied in two places.
+
+The gardener's stack survives because it answers questions graphmark cannot yet answer. graphmark
+says _whether_ a link resolves; Lane A needs to know **why it failed and what to do about it** —
+the ambiguity set, the near-miss candidates behind a "did you mean", and the canonical title of
+the note a display resolves to (so `[[ethan courtman]]` can be repaired to `[[Ethan Courtman]]`).
+
+_Where we're going:_ a documented, typed **link-diagnosis** surface that makes the consumer a
+formatter over graphmark's answers instead of a second resolver. The classification is already
+implicit in `build` — resolved / ambiguous / out-of-scope note / non-note file / intra-note
+reference / missing — it is simply thrown away. Candidate suggestion is the one genuinely new
+behavior, and it is the piece a human must confirm: freeze a differential oracle from the current
+gardener's hints on a real vault before changing anything.
+
+Sliced as #110 (retain the catalogs), #111 (`LinkDiagnosis` + `diagnose()`), #112 (near-miss
+suggestions — **not autonomous-safe past freezing the baseline**; the human annotation gate is the
+point of it). The consumer-side deletion is hand-coded in the vault; the package side is afk-able.
+
+_Constraint:_ this is additive. Nothing here may change what resolves or what an edge is.
 
 ### Track B — Judgment the oracle can't cover (human-validated)
 

{graphmark-0.3.4 → graphmark-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphmark"
-version = "0.3.4"
+version = "0.4.0"
 description = "Deterministic knowledge-graph analysis for markdown / [[wikilink]] vaults."
 readme = "README.md"
 requires-python = ">=3.11"

{graphmark-0.3.4 → graphmark-0.4.0}/src/graphmark/__init__.py

@@ -26,7 +26,15 @@ from graphmark.dismiss import (
     weaklink_sig,
 )
 from graphmark.export import to_dot, to_json
-from graphmark.graph import NormalizeResolver, VaultGraph, build_catalog
+from graphmark.graph import (
+    DIAGNOSIS_REASONS,
+    LinkDiagnosis,
+    NormalizeResolver,
+    VaultGraph,
+    build_catalog,
+    candidates_for,
+    diagnose,
+)
 from graphmark.interfaces import LinkExtractor, Resolver, Similarity
 from graphmark.metrics import (
     GAPS_DEFAULT_BAND,
@@ -87,6 +95,8 @@ __all__ = [
     "CheckPolicy",
     "Document",
     "LinkExtractor",
+    "DIAGNOSIS_REASONS",
+    "LinkDiagnosis",
     "NormalizeResolver",
     "Resolver",
     "Similarity",
@@ -98,6 +108,8 @@ __all__ = [
     "bridges",
     "build",
     "build_catalog",
+    "candidates_for",
+    "diagnose",
     "clusters",
     "gaps",
     "hubs",

{graphmark-0.3.4 → graphmark-0.4.0}/src/graphmark/graph.py

@@ -1,9 +1,10 @@
-"""Graph construction: catalog building, link resolution, and VaultGraph."""
+"""Graph construction: catalog building, link resolution, diagnosis, and VaultGraph."""
 
 from __future__ import annotations
 
 import re
 import string
+from dataclasses import dataclass, field
 from pathlib import Path
 
 from graphmark.config import VaultConfig
@@ -53,26 +54,26 @@ def _targets_non_note_file(display: str) -> bool:
     return bool(match) and match.group(0).lower() != ".md"
 
 
-def _targets_out_of_scope_note(display: str, out_of_scope: dict[str, list[str]]) -> bool:
-    """True for a link to a markdown note that exists but is outside the configured scope.
+def candidates_for(display: str, catalog: dict[str, list[str]]) -> list[str]:
+    """Every rel_path in ``catalog`` that ``display`` names, sorted; empty if it names none.
 
-    ``build`` drops unscoped folders, excluded dirs and rules files from the catalog, so links to
-    them fail the resolver — yet the link is correct, Obsidian follows it, and there is nothing for
-    anyone to fix. Reporting it as broken just fills the vault-health count with noise.
+    Answers "what did this display match?" — the question behind both an ambiguity verdict (the
+    resolver saw these and refused to pick) and the out-of-scope check (a link into unindexed
+    markdown). Deciding *uniqueness* remains the ``Resolver``'s job; this only reports matches, so
+    the two never disagree about which notes were in play.
 
-    Only ever consulted after the resolver has already failed, so an in-graph note always wins over
-    an out-of-scope namesake. **Any** candidate suppresses: out-of-scope notes are never link
-    targets, so ambiguity among them says nothing about whether the in-graph link is broken.
+    Matching mirrors ``NormalizeResolver``: bare displays by normalized stem, ``[[folder/note]]``
+    by path suffix. Both branches read the same stripped display.
     """
     target = _strip_display(display)
     if not target:
-        return False
+        return []
     if "/" in target:
         suffix = target.lower() + ".md"
-        return any(
-            path.lower().endswith(suffix) for paths in out_of_scope.values() for path in paths
+        return sorted(
+            path for paths in catalog.values() for path in paths if path.lower().endswith(suffix)
         )
-    return _normalize(target) in out_of_scope
+    return list(catalog.get(_normalize(target), ()))
 
 
 def _is_intra_note_reference(display: str) -> bool:
@@ -86,11 +87,19 @@ def _is_intra_note_reference(display: str) -> bool:
 
 
 def build_catalog(docs: list[Document]) -> dict[str, list[str]]:
-    """Map normalized stem → list of rel_paths (len > 1 means ambiguous)."""
+    """Map normalized stem → list of rel_paths (len > 1 means ambiguous).
+
+    Value lists are sorted by rel_path. ``build`` already walks in path order, but ``Path``
+    ordering and rel_path string ordering disagree where a separator meets punctuation
+    (``a-b/x.md`` vs ``a/b.md``), and this mapping is public state feeding byte-stable reports —
+    so the order is established here rather than inherited.
+    """
     catalog: dict[str, list[str]] = {}
     for doc in docs:
         key = _normalize(Path(doc.rel_path).stem)
         catalog.setdefault(key, []).append(doc.rel_path)
+    for paths in catalog.values():
+        paths.sort()
     return catalog
 
 
@@ -135,12 +144,104 @@ class NormalizeResolver:
         return paths[0]
 
 
+#: Every value ``LinkDiagnosis.reason`` can take, in the order they are decided. A consumer
+#: switches on these strings, so the set is part of the public contract.
+DIAGNOSIS_REASONS = (
+    "resolved",
+    "ambiguous",
+    "non-note-file",
+    "out-of-scope-note",
+    "missing",
+    "intra-note",
+)
+
+
+@dataclass(frozen=True)
+class LinkDiagnosis:
+    """Why a single wikilink display ended up where it did.
+
+    ``build`` sorts every link into one of the ``DIAGNOSIS_REASONS`` and then keeps only whether it
+    resolved, which conflates an *ambiguous* link with a *missing* one. Those need opposite repairs
+    — disambiguate against the colliding notes, versus create or delete the target — so a consumer
+    holding only ``unresolved`` cannot act without rebuilding the resolver itself.
+
+    ``target`` is the resolved rel_path, set only when ``reason == "resolved"``; the caller recovers
+    the note's canonical title from its stem, which is what makes a case repair like
+    ``[[ethan courtman]]`` → ``[[Ethan Courtman]]`` possible.
+
+    ``candidates`` carries the rel_paths in play: the colliding notes for ``ambiguous``, the
+    unindexed markdown for ``out-of-scope-note``. Empty for every other reason.
+    """
+
+    display: str
+    target: str | None = None
+    reason: str = "missing"
+    candidates: tuple[str, ...] = field(default=())
+
+
+def _diagnose(
+    display: str,
+    catalog: dict[str, list[str]],
+    out_of_scope: dict[str, list[str]],
+    resolver: Resolver,
+) -> LinkDiagnosis:
+    """Classify one display against already-built resolution state.
+
+    The single classifier: ``build`` calls this while assembling a graph (before a ``VaultGraph``
+    exists to pass), and the public ``diagnose`` wraps it for callers holding a built graph. Two
+    independent classifiers would drift from each other inside the package, which is the exact
+    failure this surface exists to remove.
+    """
+    if _is_intra_note_reference(display):
+        return LinkDiagnosis(display=display, reason="intra-note")
+
+    target = resolver.resolve(display, catalog)
+    if target is not None:
+        return LinkDiagnosis(display=display, target=target, reason="resolved")
+
+    # The resolver declined. Whether it declined because nothing matched or because too much did
+    # is the distinction consumers need, and only the catalog can answer it.
+    collisions = candidates_for(display, catalog)
+    if collisions:
+        return LinkDiagnosis(display=display, reason="ambiguous", candidates=tuple(collisions))
+
+    # Ordered as build has always ordered it: a "[[Board.canvas]]" is a non-note file even if some
+    # out-of-scope note happens to share the stem.
+    if _targets_non_note_file(display):
+        return LinkDiagnosis(display=display, reason="non-note-file")
+
+    unindexed = candidates_for(display, out_of_scope)
+    if unindexed:
+        return LinkDiagnosis(
+            display=display, reason="out-of-scope-note", candidates=tuple(unindexed)
+        )
+
+    return LinkDiagnosis(display=display, reason="missing")
+
+
+def diagnose(graph: VaultGraph, display: str) -> LinkDiagnosis:
+    """Explain what ``display`` names in ``graph`` — see :class:`LinkDiagnosis`.
+
+    Uses the resolver the graph was built with, so a diagnosis can never contradict the graph it
+    describes. A directly constructed ``VaultGraph`` with no resolver falls back to
+    ``NormalizeResolver``.
+    """
+    return _diagnose(display, graph.catalog, graph.out_of_scope, graph.resolver)
+
+
 class VaultGraph:
     """Built graph: all nodes plus resolved out/back adjacency.
 
     ``unresolved`` maps a rel_path to the raw link displays in it that resolved to nothing, in
     extraction order; notes with no such links are absent. It is the inspectable form of what
     build() would otherwise drop silently, and the source of the broken-link health count.
+
+    ``catalog`` and ``out_of_scope`` are the resolution state build() consulted, retained instead of
+    discarded: normalized stem → rel_paths, in path order, for in-scope notes and for markdown that
+    exists outside the configured scope respectively. A ``catalog`` key with two or more paths *is*
+    an ambiguity set. Consumers need both to say anything about a link beyond whether it resolved —
+    without them, the only way to explain a broken link is to rebuild the whole parse/catalog/
+    resolve stack, and a second stack drifts from this one.
     """
 
     def __init__(
@@ -149,11 +250,19 @@ class VaultGraph:
         out_links: dict[str, set[str]],
         back_links: dict[str, set[str]],
         unresolved: dict[str, list[str]] | None = None,
+        catalog: dict[str, list[str]] | None = None,
+        out_of_scope: dict[str, list[str]] | None = None,
+        resolver: Resolver | None = None,
     ) -> None:
         self.nodes = nodes
         self.out_links = out_links
         self.back_links = back_links
         self.unresolved = unresolved if unresolved is not None else {}
+        self.catalog = catalog if catalog is not None else {}
+        self.out_of_scope = out_of_scope if out_of_scope is not None else {}
+        # Retained so diagnose() answers with the same resolver that built the graph; a
+        # pluggable Resolver that disagreed with the graph it describes would be worse than none.
+        self.resolver: Resolver = resolver if resolver is not None else NormalizeResolver()
 
     @classmethod
     def build(
@@ -188,6 +297,9 @@ class VaultGraph:
                 continue
             md_files.append(path)
 
+        for paths in out_of_scope.values():
+            paths.sort()  # same rel_path ordering guarantee as build_catalog
+
         docs = [parse_document(p, root) for p in md_files]
         nodes = {doc.rel_path: doc for doc in docs}
         catalog = build_catalog(docs)
@@ -197,25 +309,21 @@ class VaultGraph:
 
         unresolved: dict[str, list[str]] = {}
 
+        # Classification lives in _diagnose so build and the public diagnose() can never disagree
+        # about why a link failed. Ambiguous and missing are both broken from a vault-health view;
+        # the raw display is recorded once per occurrence, since that is what a human goes and
+        # fixes.
+        broken = {"ambiguous", "missing"}
         for doc in docs:
             for display in extractor.extract(doc.text):
-                if _is_intra_note_reference(display):
-                    continue
-                target = resolver.resolve(display, catalog)
-                if target is None:
-                    if _targets_non_note_file(display) or _targets_out_of_scope_note(
-                        display, out_of_scope
-                    ):
-                        continue  # out of scope, not a broken note link
-                    # Unresolvable OR ambiguous — the Resolver protocol conflates the two, and
-                    # both are equally broken from a vault-health view. Record the raw display
-                    # (what a human has to go fix) once per occurrence.
+                d = _diagnose(display, catalog, out_of_scope, resolver)
+                if d.reason in broken:
                     unresolved.setdefault(doc.rel_path, []).append(display)
-                elif target != doc.rel_path:
-                    out_links[doc.rel_path].add(target)
+                elif d.target is not None and d.target != doc.rel_path:
+                    out_links[doc.rel_path].add(d.target)
 
         for src, targets in out_links.items():
             for dst in targets:
                 back_links[dst].add(src)
 
-        return cls(nodes, out_links, back_links, unresolved)
+        return cls(nodes, out_links, back_links, unresolved, catalog, out_of_scope, resolver)