graphmark 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,51 @@
 # CHANGELOG
 
 
+## v0.5.0 (2026-07-25)
+
+### Features
+
+- **graph**: Add calibrated near-miss suggestions (#112)
+  ([#116](https://github.com/cdcoonce/graphmark/pull/116),
+  [`db873b1`](https://github.com/cdcoonce/graphmark/commit/db873b1009bbef599e9eef035720306b62a548b8))
+
+Track E slice 3, and the last thing keeping a consumer's parallel resolver alive. diagnose(graph,
+  display, suggest=k) fills candidates with near-miss notes for a `missing` verdict only — every
+  other reason already carries the rel_paths in play — so the default of 0 leaves the check gate's
+  hot path untouched.
+
+The rule was calibrated, not invented. The prior art (bidirectional substring containment over
+  stems) was frozen over a real 521-note vault's broken links, giving 53 distinct displays, each
+  annotated by a human as useful / useless / missing / correct-none. Only then was an algorithm
+  chosen, and it is justified against that set: 27/27 useful kept — the non-negotiable — 7 of 8
+  useless dropped, 4 of 5 missing found, zero new false suggestions. Method and measured result in
+  tests/fixtures/suggest/README.md; the vault is private, so every shape is reproduced as a named
+  test with invented names rather than committing the rows.
+
+Matching is directional, which is what separates a suggestion from a wrong answer. A display inside
+  a candidate is an abbreviation and always offered ([[Jordan]] -> Jordan Ellis). A candidate inside
+  a display is offered only above SUGGEST_MIN_COVERAGE: dropping a "-reference" suffix is the
+  answer, matching one word out of five is a real note that is NOT the target, and that shape is
+  what made the old hints untrustworthy. Partial overlap in neither direction is rejected — it
+  carried no useful hint anywhere in the baseline, and rejecting it is what holds the
+  false-suggestion rate at zero.
+
+Two annotations were corrected mid-calibration and both changed the design: [[Work Tasks]] and
+  [[Personal Index]] looked useless only because the old rule printed bare stems, rendering four
+  distinct Index.md files as "Index, Index, Index, Index". Both are correct answers. Suggestions
+  therefore return rel_paths, and `index` is deliberately NOT a generic stem.
+
+Also scrubs real colleague names out of the package. They had been used as doc/test examples and one
+  shipped in a docstring in 0.4.0; all replaced with invented placeholders. Published history still
+  carries them.
+
+Both constants are pinned by the baseline: the cap is the lowest value that keeps every useful
+  suggestion, the floor the highest. Teeth-checked by mutation — disabling suppression fails 1,
+  dropping the coverage floor fails 3, dropping folder-keying fails 2, suggesting on every reason
+  fails 3, and dropping the digit filter initially survived until a ranking test was added to cover
+  it.
+
+
 ## v0.4.0 (2026-07-25)
 
 ### Features

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphmark
-Version: 0.4.0
+Version: 0.5.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
@@ -223,6 +223,36 @@ Alias, anchor and `.md` forms all diagnose identically to the bare form.
 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.
 
+### Near-miss suggestions
+
+Pass `suggest=k` to turn a `missing` verdict into an actionable one. Suggestions are computed only
+for `missing` — every other reason already carries the rel_paths in play — so the default of `0`
+costs nothing on the `check` hot path.
+
+```python
+graphmark.diagnose(graph, "Jordan", suggest=5).candidates
+# ('people/Jordan Ellis.md',)
+```
+
+Matching is **directional**, which is what separates a suggestion from a wrong answer:
+
+- a display inside a candidate name is an abbreviation — `[[Jordan]]` → `Jordan Ellis`, or
+  `[[Mood Tracker]]` → `2026-04-11-mood-tracker` (pure-digit tokens are filing metadata, not
+  content);
+- a candidate inside a display is offered only when it covers at least `SUGGEST_MIN_COVERAGE` of it
+  — `[[fable-prompt-technique-reference]]` → `fable-prompt-technique` is the answer, while
+  `[[Dagster PJM InSchedules]]` → `Dagster` is a real note that is _not_ the target;
+- partial overlap in neither direction is rejected;
+- a display matching more than `SUGGEST_MAX_MATCHES` notes names a topic, not a typo, and gets
+  nothing at all.
+
+Notes whose stem is generic (`SKILL.md`, `README.md`) are matched on their **parent folder**, where
+their name actually lives.
+
+Both constants were calibrated against a human-annotated baseline of a real vault's broken links
+rather than chosen by taste — see [`tests/fixtures/suggest/README.md`](tests/fixtures/suggest/README.md)
+for the method and the measured result.
+
 ## Configuration
 
 ```toml

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

@@ -196,6 +196,36 @@ Alias, anchor and `.md` forms all diagnose identically to the bare form.
 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.
 
+### Near-miss suggestions
+
+Pass `suggest=k` to turn a `missing` verdict into an actionable one. Suggestions are computed only
+for `missing` — every other reason already carries the rel_paths in play — so the default of `0`
+costs nothing on the `check` hot path.
+
+```python
+graphmark.diagnose(graph, "Jordan", suggest=5).candidates
+# ('people/Jordan Ellis.md',)
+```
+
+Matching is **directional**, which is what separates a suggestion from a wrong answer:
+
+- a display inside a candidate name is an abbreviation — `[[Jordan]]` → `Jordan Ellis`, or
+  `[[Mood Tracker]]` → `2026-04-11-mood-tracker` (pure-digit tokens are filing metadata, not
+  content);
+- a candidate inside a display is offered only when it covers at least `SUGGEST_MIN_COVERAGE` of it
+  — `[[fable-prompt-technique-reference]]` → `fable-prompt-technique` is the answer, while
+  `[[Dagster PJM InSchedules]]` → `Dagster` is a real note that is _not_ the target;
+- partial overlap in neither direction is rejected;
+- a display matching more than `SUGGEST_MAX_MATCHES` notes names a topic, not a typo, and gets
+  nothing at all.
+
+Notes whose stem is generic (`SKILL.md`, `README.md`) are matched on their **parent folder**, where
+their name actually lives.
+
+Both constants were calibrated against a human-annotated baseline of a real vault's broken links
+rather than chosen by taste — see [`tests/fixtures/suggest/README.md`](tests/fixtures/suggest/README.md)
+for the method and the measured result.
+
 ## Configuration
 
 ```toml

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

@@ -82,7 +82,7 @@ already learned were fine. #107 is the fourth fix that had to be applied in two
 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]]`).
+the note a display resolves to (so `[[jordan ellis]]` can be repaired to `[[Jordan Ellis]]`).
 
 _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

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

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

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

@@ -28,12 +28,15 @@ from graphmark.dismiss import (
 from graphmark.export import to_dot, to_json
 from graphmark.graph import (
     DIAGNOSIS_REASONS,
+    SUGGEST_MAX_MATCHES,
+    SUGGEST_MIN_COVERAGE,
     LinkDiagnosis,
     NormalizeResolver,
     VaultGraph,
     build_catalog,
     candidates_for,
     diagnose,
+    suggest_notes,
 )
 from graphmark.interfaces import LinkExtractor, Resolver, Similarity
 from graphmark.metrics import (
@@ -96,6 +99,8 @@ __all__ = [
     "Document",
     "LinkExtractor",
     "DIAGNOSIS_REASONS",
+    "SUGGEST_MAX_MATCHES",
+    "SUGGEST_MIN_COVERAGE",
     "LinkDiagnosis",
     "NormalizeResolver",
     "Resolver",
@@ -110,6 +115,7 @@ __all__ = [
     "build_catalog",
     "candidates_for",
     "diagnose",
+    "suggest_notes",
     "clusters",
     "gaps",
     "hubs",

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

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import re
 import string
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from pathlib import Path
 
 from graphmark.config import VaultConfig
@@ -144,6 +144,90 @@ class NormalizeResolver:
         return paths[0]
 
 
+#: A display matching more than this many notes names a *topic*, not a mistyped note, and gets no
+#: suggestions at all. Calibrated, not chosen: on the reference vault ``[[AMRT]]`` matched 47 notes
+#: while ``[[Priya Raghavan]]`` needs a cap of at least 12 to survive (that token appears in 9 note
+#: stems), so 12 is the lowest value that keeps every human-confirmed useful suggestion.
+SUGGEST_MAX_MATCHES = 12
+
+#: When a candidate's name sits *inside* a longer display, the fraction of the display it must
+#: account for. ``[[fable-prompt-technique-reference]]`` → ``fable-prompt-technique`` covers 3 of 4
+#: tokens and is the answer; ``[[Dagster PJM InSchedules]]`` → ``Dagster`` covers 1 of 3 and is a
+#: real note that is not the target — the shape that made the old suggestions untrustworthy. 0.4 is
+#: the highest floor that keeps every useful suggestion in the annotated baseline.
+SUGGEST_MIN_COVERAGE = 0.4
+
+#: Note stems that name nothing — the note's identity lives in its parent folder instead. Kept
+#: deliberately short: ``index`` is NOT here, because a vault's ``personal/Index.md`` is a real,
+#: linkable note and re-keying it onto its folder would lose the actual answer.
+GENERIC_STEMS = frozenset({"skill", "readme"})
+
+
+def _content_tokens(text: str) -> frozenset[str]:
+    """Normalized tokens with pure-digit runs dropped.
+
+    Date prefixes are filing metadata, not content: ``2026-04-11-mood-tracker`` and
+    ``Mood Tracker`` are the same note to a human, and the dated twin is the single most common
+    near-miss shape in a journal-style vault.
+    """
+    return frozenset(t for t in _normalize(text).split() if not t.isdigit())
+
+
+def _suggestion_keys(catalog: dict[str, list[str]]) -> list[tuple[str, frozenset[str]]]:
+    """(rel_path, name tokens) for every note, keyed by folder where the stem is generic."""
+    keys: list[tuple[str, frozenset[str]]] = []
+    for paths in catalog.values():
+        for rel in paths:
+            path = Path(rel)
+            name = path.parent.name if path.stem.lower() in GENERIC_STEMS else path.stem
+            tokens = _content_tokens(name)
+            if tokens:
+                keys.append((rel, tokens))
+    return keys
+
+
+def suggest_notes(display: str, catalog: dict[str, list[str]], k: int) -> tuple[str, ...]:
+    """Up to ``k`` notes whose names are near-misses for ``display``, best first.
+
+    Matching is **directional**, which is what separates a suggestion from noise:
+
+    * the display's tokens inside a candidate's — the display abbreviates a longer title
+      (``[[Jordan]]`` → ``Jordan Ellis``). Always offered; a short display naturally names a
+      longer note.
+    * a candidate's tokens inside the display's — offered only when the candidate accounts for at
+      least ``SUGGEST_MIN_COVERAGE`` of the display. Dropping a suffix is a real answer; matching
+      one word out of five is a wrong answer that invites a wrong repair.
+    * neither — rejected. Partial overlap produced no useful suggestion anywhere in the annotated
+      baseline, and rejecting it is what holds the false-suggestion rate at zero.
+
+    Ranked by how much of the longer name the match accounts for, ties broken by rel_path so the
+    output is byte-stable.
+    """
+    display_tokens = _content_tokens(display)
+    if not display_tokens or k <= 0:
+        return ()
+
+    scored: list[tuple[float, str]] = []
+    for rel, name_tokens in _suggestion_keys(catalog):
+        if display_tokens <= name_tokens:
+            score = len(display_tokens) / len(name_tokens)
+        elif name_tokens <= display_tokens:
+            score = len(name_tokens) / len(display_tokens)
+            if score < SUGGEST_MIN_COVERAGE:
+                continue
+        else:
+            continue
+        scored.append((score, rel))
+
+    # A display that matches half the vault is a topic. Offering its "best" dozen would be
+    # confident nonsense, so it gets nothing.
+    if len(scored) > SUGGEST_MAX_MATCHES:
+        return ()
+
+    scored.sort(key=lambda pair: (-pair[0], pair[1]))
+    return tuple(rel for _, rel in scored[:k])
+
+
 #: 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 = (
@@ -167,10 +251,11 @@ class LinkDiagnosis:
 
     ``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.
+    ``[[jordan ellis]]`` → ``[[Jordan Ellis]]`` 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.
+    unindexed markdown for ``out-of-scope-note``, and — only when ``diagnose`` is asked for them —
+    the near-miss suggestions for ``missing``. Empty for every other reason.
     """
 
     display: str
@@ -219,14 +304,24 @@ def _diagnose(
     return LinkDiagnosis(display=display, reason="missing")
 
 
-def diagnose(graph: VaultGraph, display: str) -> LinkDiagnosis:
+def diagnose(graph: VaultGraph, display: str, *, suggest: int = 0) -> 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``.
+
+    ``suggest=k`` fills ``candidates`` with up to k near-miss notes — but only for a ``missing``
+    verdict, since every other reason either already carries the rel_paths in play or has nothing
+    to look for. The default of 0 does no extra work at all, keeping the vault-health gate's hot
+    path free of it.
     """
-    return _diagnose(display, graph.catalog, graph.out_of_scope, graph.resolver)
+    if suggest < 0:
+        raise ValueError(f"suggest must be >= 0, got {suggest}")
+    diagnosis = _diagnose(display, graph.catalog, graph.out_of_scope, graph.resolver)
+    if suggest and diagnosis.reason == "missing":
+        return replace(diagnosis, candidates=suggest_notes(display, graph.catalog, suggest))
+    return diagnosis
 
 
 class VaultGraph:

graphmark-0.5.0/tests/fixtures/suggest/README.md

@@ -0,0 +1,62 @@
+# Suggestion calibration — provenance
+
+`suggest_notes()` is the one part of graphmark whose expected output is **human judgment, not
+oracle-derived**. There is no reference engine to diff against: the question "is this a useful
+suggestion?" has no mechanical answer. So the rule was calibrated rather than invented, and this
+file records how, because the numbers in `SUGGEST_MAX_MATCHES` / `SUGGEST_MIN_COVERAGE` are
+meaningless without it.
+
+## Method
+
+1. **Freeze the baseline.** The prior art was a consumer's hint rule — bidirectional substring
+   containment over normalized note stems, capped at 5 for display. It was run over a real
+   521-note vault's actual broken links, yielding **53 distinct displays** that reached the hint
+   search.
+2. **Annotate it.** A human marked every row:
+   - `useful` (25 → 27 after correction) — the hint is the answer; a new rule **must** keep it
+   - `useless` (8) — a wrong or unactionable suggestion; a new rule should drop it
+   - `missing` (5) — no hint today, but an obvious answer exists
+   - `correct-none` (13) — no hint, and nothing to find
+3. **Then** choose an algorithm, and justify it against the annotation.
+
+The vault is private, so the annotated rows are not committed here — every distinct shape they
+cover is reproduced as a named test case in `tests/test_suggestions.py`, with invented names.
+
+## What the annotation established
+
+Two rows were reclassified during calibration, and both changed the design:
+
+- `[[Work Tasks]] → Tasks` and `[[Personal Index]] → Index` were first marked useless, because the
+  hint rendered as a bare repeated stem (`Index, Index, Index, Index`). Both are in fact **correct**
+  — `work/Tasks.md` and `personal/Index.md`. The defect was the _display format_, not the matching:
+  showing stems threw away the path that disambiguates them. Suggestions therefore return
+  **rel_paths**. This is also why `index` is not in `GENERIC_STEMS`.
+
+## Result
+
+|                       | old rule | calibrated rule |
+| --------------------- | -------- | --------------- |
+| useful kept           | 27/27    | **27/27**       |
+| useless dropped       | 0/8      | **7/8**         |
+| missing found         | 0/5      | **4/5**         |
+| new false suggestions | —        | **0**           |
+
+The two knowingly-accepted gaps:
+
+- **`[[My Brain]]`** still suggests two real notes sharing that prefix. Defensible, so not worth
+  distorting the rule to remove.
+- **`[[graphify-knowledge-graph-tool]] → graphify-memory-layer-eval`** is still missed. They share
+  one token of four in neither direction, so only edit distance would find it — and every
+  edit-distance variant tried scored worse overall, losing useful rows to keep this one. Rejecting
+  partial overlap is what holds the false-suggestion rate at zero.
+
+## Why the constants are what they are
+
+- `SUGGEST_MAX_MATCHES = 12` — the **lowest** cap that keeps every useful suggestion. One display
+  (a two-token personal name whose first token appears in 9 note stems) needs 12; at 8 it is lost.
+  The pathological case it exists for matched 47 notes.
+- `SUGGEST_MIN_COVERAGE = 0.4` — the **highest** floor that keeps every useful suggestion. At 0.5
+  two rows are lost; at 0.67 six are.
+
+Re-running the calibration after any change to the rule is the check that matters. A green unit
+suite proves the shapes still behave; only the annotated set proves the rule is still _useful_.

{graphmark-0.4.0 → graphmark-0.5.0}/tests/test_diagnose.py

@@ -41,12 +41,12 @@ class TestResolved:
         assert d == LinkDiagnosis(display="b", target="b.md", reason="resolved", candidates=())
 
     def test_the_target_carries_the_canonical_title(self, tmp_path):
-        # The repair the gardener needs: [[ethan courtman]] → [[Ethan Courtman]]. The caller
+        # The repair the gardener needs: [[jordan ellis]] → [[Jordan Ellis]]. The caller
         # recovers the title from the target's stem, so no separate title field is needed.
-        _write(tmp_path, "people/Ethan Courtman.md")
-        d = diagnose(_build(tmp_path), "ethan courtman")
+        _write(tmp_path, "people/Jordan Ellis.md")
+        d = diagnose(_build(tmp_path), "jordan ellis")
         assert d.reason == "resolved"
-        assert Path(d.target).stem == "Ethan Courtman"
+        assert Path(d.target).stem == "Jordan Ellis"
 
     def test_path_qualified_link_resolves(self, tmp_path):
         _write(tmp_path, "docs/deep/note.md")

{graphmark-0.4.0 → graphmark-0.5.0}/tests/test_graph_catalogs.py

@@ -34,8 +34,8 @@ def _build(root: Path, **config_kwargs) -> VaultGraph:
 
 class TestCatalog:
     def test_maps_normalized_stem_to_rel_path(self, tmp_path):
-        _write(tmp_path, "Ethan Courtman.md")
-        assert _build(tmp_path).catalog == {"ethan courtman": ["Ethan Courtman.md"]}
+        _write(tmp_path, "Jordan Ellis.md")
+        assert _build(tmp_path).catalog == {"jordan ellis": ["Jordan Ellis.md"]}
 
     def test_punctuation_normalizes_to_the_same_key_as_spaces(self, tmp_path):
         # The vault's real repair case: [[oura pipeline]] should be able to find oura-pipeline.md.

{graphmark-0.4.0 → graphmark-0.5.0}/tests/test_public_api.py

@@ -118,6 +118,9 @@ class TestPublicSurface:
         "LinkDiagnosis",
         "DIAGNOSIS_REASONS",
         "candidates_for",
+        "suggest_notes",
+        "SUGGEST_MAX_MATCHES",
+        "SUGGEST_MIN_COVERAGE",
         # dismissal store
         "weaklink_sig",
         "record_dismissal",

graphmark-0.5.0/tests/test_suggestions.py

@@ -0,0 +1,279 @@
+"""diagnose(..., suggest=k) — near-miss candidates for a link that names nothing.
+
+The last thing keeping a consumer's parallel resolver alive: when a link resolves to nothing, a
+useful tool offers near-miss note titles, and the repair proposal is only actionable because of
+them.
+
+The rule here was not invented — it was calibrated against a frozen baseline of a real 521-note
+vault's broken links, annotated by a human as useful / useless / missing-the-obvious-answer (see
+tests/fixtures/suggest/README.md). Three policy decisions came from that annotation:
+
+  1. A display matching more than SUGGEST_MAX_MATCHES notes gets nothing: it names a topic, not a
+     typo. ([[AMRT]] matched 47 notes under the old rule.)
+  2. A note whose stem is generic (SKILL.md, README.md) is indexed by its PARENT FOLDER, because
+     that is where its name lives.
+  3. Matching is directional. A display inside a candidate is an abbreviation and always useful
+     ([[Jordan]] -> Jordan Ellis). A candidate inside a display is useful only when it covers
+     most of it ([[fable-prompt-technique-reference]] -> fable-prompt-technique) and is noise when
+     it is one word out of many ([[Dagster PJM InSchedules]] -> Dagster).
+
+Partial overlap in neither direction is rejected: it produced no useful hint anywhere in the
+baseline.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from graphmark.config import VaultConfig
+from graphmark.graph import (
+    SUGGEST_MAX_MATCHES,
+    SUGGEST_MIN_COVERAGE,
+    NormalizeResolver,
+    VaultGraph,
+    diagnose,
+)
+from graphmark.parse import WikilinkExtractor
+
+
+def _write(root: Path, rel: str, text: str = "") -> None:
+    path = root / rel
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+def _build(root: Path, **config_kwargs) -> VaultGraph:
+    return VaultGraph.build(
+        VaultConfig(root=root, **config_kwargs), WikilinkExtractor(), NormalizeResolver()
+    )
+
+
+class TestDefaultIsUnchanged:
+    """suggest=0 must cost nothing — the check gate's hot path never wants suggestions."""
+
+    def test_no_suggestions_without_the_flag(self, tmp_path):
+        _write(tmp_path, "Jordan Ellis.md")
+        _write(tmp_path, "a.md", "See [[Jordan]].\n")
+        d = diagnose(_build(tmp_path), "Jordan")
+        assert (d.reason, d.candidates) == ("missing", ())
+
+    def test_explicit_zero_is_the_same(self, tmp_path):
+        _write(tmp_path, "Jordan Ellis.md")
+        assert diagnose(_build(tmp_path), "Jordan", suggest=0).candidates == ()
+
+
+class TestAbbreviations:
+    """display ⊆ candidate — the display names part of a longer real title."""
+
+    def test_a_first_name_finds_the_full_name(self, tmp_path):
+        _write(tmp_path, "people/Jordan Ellis.md")
+        d = diagnose(_build(tmp_path), "Jordan", suggest=5)
+        assert d.reason == "missing"
+        assert d.candidates == ("people/Jordan Ellis.md",)
+
+    def test_a_title_finds_a_prefixed_slug(self, tmp_path):
+        _write(tmp_path, "ref/anthropic-containing-claude.md")
+        d = diagnose(_build(tmp_path), "Containing Claude", suggest=5)
+        assert d.candidates == ("ref/anthropic-containing-claude.md",)
+
+    def test_date_prefixes_are_not_content(self, tmp_path):
+        # A dated twin of the same note is the single most common shape in the baseline.
+        _write(tmp_path, "notes/2026-04-11-mood-tracker.md")
+        d = diagnose(_build(tmp_path), "Mood Tracker", suggest=5)
+        assert d.candidates == ("notes/2026-04-11-mood-tracker.md",)
+
+    def test_a_dated_twin_outranks_a_longer_untitled_match(self, tmp_path):
+        # Where dropping digits actually bites: both notes contain the display's tokens, so both
+        # match either way, but only ignoring the date makes the dated twin score a perfect 1.0
+        # and sort first. Counting "2026", "04" and "11" as content buries the right answer.
+        _write(tmp_path, "notes/2026-04-11-mood-tracker.md")
+        _write(tmp_path, "notes/mood tracker notes.md")
+        d = diagnose(_build(tmp_path), "Mood Tracker", suggest=5)
+        assert d.candidates[0] == "notes/2026-04-11-mood-tracker.md"
+
+    def test_punctuation_differences_do_not_matter(self, tmp_path):
+        _write(tmp_path, "trips/2026-mike-brenna-wedding-trip.md")
+        d = diagnose(_build(tmp_path), "Mike & Brenna Wedding Trip", suggest=5)
+        assert d.candidates == ("trips/2026-mike-brenna-wedding-trip.md",)
+
+    def test_several_expansions_all_surface(self, tmp_path):
+        # [[Robin]] is genuinely ambiguous between two people — both must show, or the human
+        # cannot pick.
+        _write(tmp_path, "people/Robin Vance.md")
+        _write(tmp_path, "people/Robin Weaver.md")
+        d = diagnose(_build(tmp_path), "Robin", suggest=5)
+        assert d.candidates == ("people/Robin Vance.md", "people/Robin Weaver.md")
+
+
+class TestSuffixDrops:
+    """candidate ⊆ display — useful only when the candidate covers most of the display."""
+
+    def test_dropping_a_suffix_finds_the_base_note(self, tmp_path):
+        _write(tmp_path, "ref/fable-prompt-technique.md")
+        d = diagnose(_build(tmp_path), "fable-prompt-technique-reference", suggest=5)
+        assert d.candidates == ("ref/fable-prompt-technique.md",)
+
+    def test_a_two_word_display_finds_its_one_word_note(self, tmp_path):
+        # [[Work Tasks]] -> work/Tasks.md: coverage 1/2 clears the floor.
+        _write(tmp_path, "work/Tasks.md")
+        d = diagnose(_build(tmp_path), "Work Tasks", suggest=5)
+        assert d.candidates == ("work/Tasks.md",)
+
+    def test_one_word_out_of_many_is_rejected(self, tmp_path):
+        # [[Dagster PJM InSchedules]] -> Dagster was the archetypal noise hint: a real note, but
+        # not the target, and it invites a wrong repair.
+        _write(tmp_path, "ref/Dagster.md")
+        d = diagnose(_build(tmp_path), "Dagster PJM InSchedules", suggest=5)
+        assert d.candidates == ()
+
+    def test_the_coverage_floor_is_the_boundary(self, tmp_path):
+        # 2 of 5 tokens = 0.4, exactly the floor, which is inclusive.
+        _write(tmp_path, "ref/rec dashboard.md")
+        d = diagnose(_build(tmp_path), "reference rec dashboard env delivery", suggest=5)
+        assert d.candidates == ("ref/rec dashboard.md",)
+        # 1 of 5 = 0.2, below it.
+        _write(tmp_path, "ref/delivery.md")
+        assert (
+            "ref/delivery.md"
+            not in diagnose(
+                _build(tmp_path), "reference rec dashboard env delivery", suggest=5
+            ).candidates
+        )
+
+
+class TestPartialOverlapRejected:
+    def test_sharing_one_token_in_neither_direction_suggests_nothing(self, tmp_path):
+        # {graphify, memory, layer, eval} vs {graphify, knowledge, graph, tool}: neither is a
+        # subset, so this is rejected. A known miss, accepted to keep the noise floor at zero.
+        _write(tmp_path, "ideas/graphify-memory-layer-eval.md")
+        d = diagnose(_build(tmp_path), "graphify-knowledge-graph-tool", suggest=5)
+        assert d.candidates == ()
+
+
+class TestBroadMatchSuppression:
+    def test_a_display_matching_more_than_the_cap_suggests_nothing(self, tmp_path):
+        for i in range(SUGGEST_MAX_MATCHES + 1):
+            _write(tmp_path, f"notes/amrt topic {i}.md")
+        d = diagnose(_build(tmp_path), "AMRT", suggest=5)
+        assert d.candidates == ()
+
+    def test_exactly_at_the_cap_still_suggests(self, tmp_path):
+        for i in range(SUGGEST_MAX_MATCHES):
+            _write(tmp_path, f"notes/amrt topic {i}.md")
+        d = diagnose(_build(tmp_path), "AMRT", suggest=SUGGEST_MAX_MATCHES)
+        assert len(d.candidates) == SUGGEST_MAX_MATCHES
+
+
+class TestFolderNamedNotes:
+    def test_a_generic_stem_is_indexed_by_its_folder(self, tmp_path):
+        _write(tmp_path, "skills/mr-review-packet/SKILL.md")
+        d = diagnose(_build(tmp_path), "mr-review-packet", suggest=5)
+        assert d.candidates == ("skills/mr-review-packet/SKILL.md",)
+
+    def test_readme_counts_as_generic_too(self, tmp_path):
+        _write(tmp_path, "tools/link-checker/README.md")
+        d = diagnose(_build(tmp_path), "link checker", suggest=5)
+        assert d.candidates == ("tools/link-checker/README.md",)
+
+    def test_a_normal_stem_is_still_indexed_by_its_stem(self, tmp_path):
+        _write(tmp_path, "skills/mr-review-packet/notes.md")
+        assert diagnose(_build(tmp_path), "mr-review-packet", suggest=5).candidates == ()
+
+    def test_index_is_not_generic(self, tmp_path):
+        # personal/Index.md is a real, linkable vault index — treating "Index" as generic would
+        # re-key four different indexes onto their folder names and lose the actual answer.
+        _write(tmp_path, "personal/Index.md")
+        d = diagnose(_build(tmp_path), "Personal Index", suggest=5)
+        assert d.candidates == ("personal/Index.md",)
+
+
+class TestOrderingAndLimits:
+    def test_k_limits_the_result(self, tmp_path):
+        for name in ("Robin Vance", "Robin Weaver", "Robin Zhang"):
+            _write(tmp_path, f"people/{name}.md")
+        assert len(diagnose(_build(tmp_path), "Robin", suggest=2).candidates) == 2
+
+    def test_best_coverage_ranks_first(self, tmp_path):
+        _write(tmp_path, "a/afk-cockpit-ui.md")
+        _write(tmp_path, "a/afk-cockpit-metrics-audit-and-review.md")
+        d = diagnose(_build(tmp_path), "afk-cockpit", suggest=5)
+        assert d.candidates[0] == "a/afk-cockpit-ui.md"
+
+    def test_ties_break_on_rel_path(self, tmp_path):
+        _write(tmp_path, "zeta/Robin Vance.md")
+        _write(tmp_path, "alpha/Robin Ford.md")
+        d = diagnose(_build(tmp_path), "Robin", suggest=5)
+        assert d.candidates == ("alpha/Robin Ford.md", "zeta/Robin Vance.md")
+
+
+class TestOnlyForMissing:
+    """Every other verdict already carries the right candidates, or needs none."""
+
+    def test_a_resolved_link_gets_no_suggestions(self, tmp_path):
+        _write(tmp_path, "b.md")
+        _write(tmp_path, "b extended.md")
+        d = diagnose(_build(tmp_path), "b", suggest=5)
+        assert (d.reason, d.candidates) == ("resolved", ())
+
+    def test_an_ambiguous_link_keeps_its_real_candidates(self, tmp_path):
+        _write(tmp_path, "one/note.md")
+        _write(tmp_path, "two/note.md")
+        _write(tmp_path, "three/note extended.md")
+        d = diagnose(_build(tmp_path), "note", suggest=5)
+        assert d.reason == "ambiguous"
+        assert d.candidates == ("one/note.md", "two/note.md")
+
+    def test_an_out_of_scope_link_keeps_its_real_candidates(self, tmp_path):
+        _write(tmp_path, "docs/a.md")
+        _write(tmp_path, "templates/guide.md")
+        _write(tmp_path, "docs/guide extended.md")
+        d = diagnose(_build(tmp_path, scoped_folders=["docs"]), "guide", suggest=5)
+        assert d.reason == "out-of-scope-note"
+        assert d.candidates == ("templates/guide.md",)
+
+    def test_an_intra_note_link_gets_no_suggestions(self, tmp_path):
+        _write(tmp_path, "a.md")
+        assert diagnose(_build(tmp_path), "#Heading", suggest=5).candidates == ()
+
+    def test_a_non_note_file_gets_no_suggestions(self, tmp_path):
+        _write(tmp_path, "a.md")
+        _write(tmp_path, "Board extended.md")
+        assert diagnose(_build(tmp_path), "Board.canvas", suggest=5).candidates == ()
+
+
+class TestConstants:
+    def test_the_calibrated_band_is_published(self):
+        # Both values were fixed by the annotated baseline, not chosen by taste: the cap at 12
+        # because [[Priya Raghavan]] needs it (that token appears in 9 stems), the floor at 0.4
+        # because it is the highest value that keeps every useful hint.
+        assert SUGGEST_MAX_MATCHES == 12
+        assert SUGGEST_MIN_COVERAGE == 0.4
+
+    def test_exported_from_the_top_level(self):
+        import graphmark
+
+        assert graphmark.SUGGEST_MAX_MATCHES == SUGGEST_MAX_MATCHES
+        assert graphmark.SUGGEST_MIN_COVERAGE == SUGGEST_MIN_COVERAGE
+
+
+class TestBuildIsUnaffected:
+    def test_suggestions_never_change_the_graph(self, tmp_path):
+        _write(tmp_path, "hub.md", "[[Jordan]] and [[b]]\n")
+        _write(tmp_path, "Jordan Ellis.md")
+        _write(tmp_path, "b.md")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {"hub.md": ["Jordan"]}
+        assert graph.out_links["hub.md"] == {"b.md"}
+        # asking for suggestions is a read, not a mutation
+        diagnose(graph, "Jordan", suggest=5)
+        assert graph.unresolved == {"hub.md": ["Jordan"]}
+        assert graph.out_links["hub.md"] == {"b.md"}
+
+
+@pytest.mark.parametrize("bad", [-1, -5])
+def test_negative_suggest_is_a_usage_error(tmp_path, bad):
+    _write(tmp_path, "a.md")
+    with pytest.raises(ValueError, match="suggest"):
+        diagnose(_build(tmp_path), "Nowhere", suggest=bad)