graphmark 0.1.0__tar.gz

graphmark-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.DS_Store

graphmark-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles Coonce
+
+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.

graphmark-0.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: graphmark
+Version: 0.1.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
+Project-URL: Issues, https://github.com/cdcoonce/graphmark/issues
+Author-email: Charles Coonce <charlescoonce@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: graph,knowledge-graph,markdown,obsidian,pagerank,wikilink
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Requires-Dist: networkx>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# graphmark
+
+Deterministic knowledge-graph analysis for markdown / `[[wikilink]]` vaults — orphans, hubs,
+clusters, bridges, neighborhoods, and PageRank over your notes, driven by a small config so it works
+on any Obsidian-family vault.
+
+> Status: **early**. Engine modules are being built against a differential oracle (a proven
+> reference implementation's frozen outputs). See `CLAUDE.md` for the architecture and the
+> reference-parity contract.
+
+## Install (dev)
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+## Test
+
+```bash
+uv run --extra dev ruff check . && uv run --extra dev ruff format --check . && uv run --extra dev pytest -q
+```
+
+## Usage (once built)
+
+```bash
+graphmark stats     --config configs/my-brain.toml --root /path/to/vault
+graphmark orphans   --config configs/my-brain.toml --root /path/to/vault
+graphmark hubs 10   --config configs/my-brain.toml --root /path/to/vault
+graphmark pagerank  --config configs/my-brain.toml --root /path/to/vault
+graphmark export dot --config configs/my-brain.toml --root /path/to/vault > graph.dot
+```

graphmark-0.1.0/README.md

@@ -0,0 +1,31 @@
+# graphmark
+
+Deterministic knowledge-graph analysis for markdown / `[[wikilink]]` vaults — orphans, hubs,
+clusters, bridges, neighborhoods, and PageRank over your notes, driven by a small config so it works
+on any Obsidian-family vault.
+
+> Status: **early**. Engine modules are being built against a differential oracle (a proven
+> reference implementation's frozen outputs). See `CLAUDE.md` for the architecture and the
+> reference-parity contract.
+
+## Install (dev)
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+## Test
+
+```bash
+uv run --extra dev ruff check . && uv run --extra dev ruff format --check . && uv run --extra dev pytest -q
+```
+
+## Usage (once built)
+
+```bash
+graphmark stats     --config configs/my-brain.toml --root /path/to/vault
+graphmark orphans   --config configs/my-brain.toml --root /path/to/vault
+graphmark hubs 10   --config configs/my-brain.toml --root /path/to/vault
+graphmark pagerank  --config configs/my-brain.toml --root /path/to/vault
+graphmark export dot --config configs/my-brain.toml --root /path/to/vault > graph.dot
+```

graphmark-0.1.0/docs/ROADMAP.md

@@ -0,0 +1,73 @@
+# Roadmap — graphmark (for `afk-driver --expand`)
+
+> Read **verbatim** by `afk-driver --expand` and injected into the feature-proposing agent's prompt
+> alongside the live code. Write at the altitude of **intent** — name directions and gaps; let the
+> expander (and the code it reads) propose specifics. **Every proposal must state which Track it
+> advances** — that is how a human decides whether a green gate is sufficient.
+
+## Vision
+
+A general, deterministic **knowledge-graph analysis library + CLI** for markdown / `[[wikilink]]`
+vaults — orphans, hubs, clusters, bridges, neighborhoods, and PageRank — driven by a small config so
+it works on **any** Obsidian-family vault. It generalizes a proven vault-specific engine
+(`brain_map.py`) into a standalone, pip-installable, publishable package.
+
+The central fact of this repo: **correctness is pinned by a frozen differential oracle.** Structural
+outputs are the verbatim results of the reference engine (`brain_map.py --vault-root`), and PageRank
+is checked against networkx. Both are independent of anything the executor writes, and the executor
+cannot regenerate them — so a **green gate proves correctness**, and nearly all work is Track A.
+
+## What's shipped (baseline — do not re-propose)
+
+- **The seed (Phase 0).** Package scaffold, `.afk` gate, `CLAUDE.md` contract.
+- **Seeded boundaries** — `model.py` (Document/Edge/Graph/Finding), `interfaces.py`
+  (`LinkExtractor`/`Resolver` Protocols), `config.py` (`VaultConfig`; `load_config` is a stub).
+- **`configs/my-brain.toml`** — the reference config instance.
+- **The frozen oracle** — `tests/fixtures/simple/`: a synthetic vault + `expected.json` holding
+  `brain_map`'s verbatim structural output plus networkx PageRank.
+- The engine itself — `parse.py`, `graph.py`, `metrics.py`, `export.py`, `cli.py` — **does not exist
+  yet.** That is the work.
+
+## Direction
+
+### Track A — Engine, correctness & packaging (gate-verifiable; autonomous-safe)
+
+_The frozen oracle can verify these. Safe to promote on a green gate._
+
+- _Where we are:_ boundaries and the oracle exist; no engine. The current bottleneck is
+  **parse + graph + link resolution** (issue #1) — nothing else can be verified until the graph builds.
+- _Where we're going:_ a config-driven engine whose structural metrics reproduce `brain_map` **exactly**
+  (shape, ordering, tie-breaking), a `load_config` that makes every vault-specific behavior parametric,
+  net-new **pure-python PageRank**, DOT export, and a CLI. All checked against frozen fixtures.
+- _The principle:_ every correctness property is pinned by a fixture derived from an independent
+  reference; matching the fixture IS the contract that lets afk build unsupervised.
+
+### Track B — Judgment the oracle can't cover (human-validated)
+
+_The gate confirms "matches the frozen fixture"; it cannot confirm a **new** fixture's expected values
+are right, nor adjudicate API taste._
+
+- New fixtures on the **my-brain schema** derive expected values from `brain_map` → still Track A.
+  New fixtures on a **different schema** (e.g. the generalization fixture in issue #3) have
+  hand-authored expected values → **Track B**: a human confirms them.
+- Public API naming, packaging/release, and documentation voice are Track B.
+
+## Principles every proposal must respect
+
+- **The oracle is the spec.** Never edit an `expected.json` to pass a test. Match it; if it looks
+  wrong, flag it.
+- **Implement within the seeded interfaces.** Do not redesign `model`/`interfaces`/`config` boundaries.
+- **Dependency-light.** Shipped deps are `networkx` only — **no scipy/numpy** in the package;
+  PageRank is pure-python power iteration.
+- **Keep the three layers separate** — engine (vault-agnostic) / config (the domain seam) / surface
+  (JSON, DOT, CLI). See `CLAUDE.md`.
+- **TDD, tracer-bullet slices.** `afk-sized` = single-purpose, independently testable; larger is
+  `needs-decomposition`.
+
+## Non-goals (out of scope — do not propose)
+
+- Semantic "gaps" / embeddings (keep the gate fastembed-free), betweenness centrality, Louvain/Leiden
+  community detection, CSV/GML/Cypher export, incremental/cached builds, any LLM "propose" pass.
+- Alternate link-syntax adapters (Logseq, markdown `[](.)` links) — the pluggable interfaces exist so
+  these *can* be added later; do not build the implementations now.
+- Re-platforming — no swapping networkx for another graph backend; no async/parallel rewrites.

graphmark-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "graphmark"
+version = "0.1.0"
+description = "Deterministic knowledge-graph analysis for markdown / [[wikilink]] vaults."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Charles Coonce", email = "charlescoonce@gmail.com" }]
+keywords = ["knowledge-graph", "markdown", "wikilink", "obsidian", "graph", "pagerank"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Text Processing :: Markup :: Markdown",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = ["networkx>=3.0"]
+
+[project.urls]
+Homepage = "https://github.com/cdcoonce/graphmark"
+Repository = "https://github.com/cdcoonce/graphmark"
+Issues = "https://github.com/cdcoonce/graphmark/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[project.scripts]
+graphmark = "graphmark.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/graphmark"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/graphmark", "tests", "docs/ROADMAP.md", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

graphmark-0.1.0/src/graphmark/__init__.py

@@ -0,0 +1,3 @@
+"""graphmark — deterministic knowledge-graph analysis for markdown/wikilink vaults."""
+
+__version__ = "0.1.0"

graphmark-0.1.0/src/graphmark/cli.py

@@ -0,0 +1,101 @@
+"""Command-line interface for graphmark."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from graphmark.config import VaultConfig, load_config
+from graphmark.export import to_dot, to_json
+from graphmark.graph import NormalizeResolver, VaultGraph
+from graphmark.metrics import (
+    bridges,
+    clusters,
+    gaps,
+    hubs,
+    neighborhood,
+    orphans,
+    pagerank,
+    siloed_notes,
+    stats,
+)
+from graphmark.parse import WikilinkExtractor
+
+
+def _load(args: argparse.Namespace) -> tuple[VaultGraph, VaultConfig]:
+    if args.config is not None:
+        config = load_config(Path(args.config))
+        if args.root is not None:
+            config.root = Path(args.root)
+    elif args.root is not None:
+        config = VaultConfig(root=Path(args.root))
+    else:
+        print("error: --config or --root required", file=sys.stderr)
+        sys.exit(1)
+    graph = VaultGraph.build(config, WikilinkExtractor(), NormalizeResolver())
+    return graph, config
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="graphmark")
+    parser.add_argument("--config", metavar="PATH", help="TOML config file")
+    parser.add_argument("--root", metavar="PATH", help="Vault root (overrides --config root)")
+
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("stats")
+    sub.add_parser("orphans")
+
+    hubs_p = sub.add_parser("hubs")
+    hubs_p.add_argument("--n", type=int, default=10)
+
+    sub.add_parser("clusters")
+    sub.add_parser("bridges")
+    sub.add_parser("siloed")
+
+    nb_p = sub.add_parser("neighborhood")
+    nb_p.add_argument("--note", required=True)
+    nb_p.add_argument("--depth", type=int, default=1)
+
+    pr_p = sub.add_parser("pagerank")
+    pr_p.add_argument("--n", type=int, default=10)
+    pr_p.add_argument("--alpha", type=float, default=0.85)
+
+    exp_p = sub.add_parser("export")
+    exp_p.add_argument("format", choices=["dot"])
+
+    sub.add_parser("gaps")
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(1)
+
+    graph, config = _load(args)
+
+    if args.command == "stats":
+        print(to_json(stats(graph)))
+    elif args.command == "orphans":
+        print(to_json(orphans(graph, config)))
+    elif args.command == "hubs":
+        print(to_json(hubs(graph, n=args.n)))
+    elif args.command == "clusters":
+        print(to_json(clusters(graph)))
+    elif args.command == "bridges":
+        print(to_json(bridges(graph)))
+    elif args.command == "siloed":
+        print(to_json(siloed_notes(graph)))
+    elif args.command == "neighborhood":
+        print(to_json(neighborhood(graph, args.note, depth=args.depth)))
+    elif args.command == "pagerank":
+        print(to_json(pagerank(graph, n=args.n, alpha=args.alpha)))
+    elif args.command == "export" and args.format == "dot":
+        print(to_dot(graph))
+    elif args.command == "gaps":
+        print(to_json(gaps(graph, lambda _rel, _k: [])))
+
+
+if __name__ == "__main__":
+    main()

graphmark-0.1.0/src/graphmark/config.py

@@ -0,0 +1,44 @@
+"""Vault configuration — the domain seam that makes the engine general.
+
+``VaultConfig`` holds every vault-specific policy the engine consults. ``load_config`` (TOML →
+VaultConfig) is intentionally left unimplemented; wiring config through the engine is afk Issue #3.
+Fixture tests may construct ``VaultConfig`` directly.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class VaultConfig:
+    """All vault-specific behavior, parametrized."""
+
+    root: Path
+    scoped_folders: list[str] = field(default_factory=list)
+    excluded_dirs: list[str] = field(default_factory=list)
+    rules_files: list[str] = field(default_factory=lambda: ["CLAUDE.md", "CLAUDE.local.md"])
+    wikilink_pattern: str = r"\[\[(.+?)\]\]"
+    orphan_min_chars: int = 300
+    transient_prefixes: tuple[str, ...] = ()
+
+
+def load_config(path: Path) -> VaultConfig:
+    """Load a VaultConfig from a TOML file."""
+    with open(path, "rb") as f:
+        data = tomllib.load(f)
+
+    toml_dir = path.parent
+    root = toml_dir / data["root"]
+
+    return VaultConfig(
+        root=root,
+        scoped_folders=data.get("scoped_folders", []),
+        excluded_dirs=data.get("excluded_dirs", []),
+        rules_files=data.get("rules_files", ["CLAUDE.md", "CLAUDE.local.md"]),
+        wikilink_pattern=data.get("wikilink_pattern", r"\[\[(.+?)\]\]"),
+        orphan_min_chars=data.get("orphan_min_chars", 300),
+        transient_prefixes=tuple(data.get("transient_prefixes", [])),
+    )

graphmark-0.1.0/src/graphmark/dismiss.py

@@ -0,0 +1,59 @@
+"""Dismissal store with content-hash staleness for weaklink suggestions."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+_DEFAULT_PATH = ".claude/data/connect-dismissed.json"
+
+
+def weaklink_sig(a: str, b: str) -> str:
+    return "weaklink|" + "|".join(sorted([a, b]))
+
+
+def content_hash(path: Path) -> str:
+    return hashlib.sha1(path.read_bytes()).hexdigest()
+
+
+def record_dismissal(root: Path, a: str, b: str, *, path: str = _DEFAULT_PATH) -> None:
+    dismissed_file = root / path
+    dismissed_file.parent.mkdir(parents=True, exist_ok=True)
+    existing = {}
+    if dismissed_file.exists():
+        try:
+            existing = json.loads(dismissed_file.read_text())
+        except (json.JSONDecodeError, OSError):
+            existing = {}
+    sig = weaklink_sig(a, b)
+    existing[sig] = {
+        "a": a,
+        "a_hash": content_hash(root / a),
+        "b": b,
+        "b_hash": content_hash(root / b),
+    }
+    dismissed_file.write_text(json.dumps(existing, indent=2))
+
+
+def load_dismissed(root: Path, *, path: str = _DEFAULT_PATH) -> dict:
+    dismissed_file = root / path
+    if not dismissed_file.exists():
+        return {}
+    return json.loads(dismissed_file.read_text())
+
+
+def active_dismissed_sigs(root: Path, *, path: str = _DEFAULT_PATH) -> set[str]:
+    dismissed = load_dismissed(root, path=path)
+    active: set[str] = set()
+    for sig, record in dismissed.items():
+        a_path = root / record["a"]
+        b_path = root / record["b"]
+        if (
+            a_path.exists()
+            and b_path.exists()
+            and content_hash(a_path) == record["a_hash"]
+            and content_hash(b_path) == record["b_hash"]
+        ):
+            active.add(sig)
+    return active

graphmark-0.1.0/src/graphmark/export.py

@@ -0,0 +1,24 @@
+"""Export helpers: JSON serialisation and Graphviz DOT output."""
+
+from __future__ import annotations
+
+import json
+
+from graphmark.graph import VaultGraph
+
+
+def to_json(obj) -> str:
+    """Serialise any JSON-serialisable object to a string."""
+    return json.dumps(obj)
+
+
+def to_dot(graph: VaultGraph) -> str:
+    """Emit a Graphviz digraph containing every node and directed edge."""
+    lines = ["digraph G {"]
+    for node in sorted(graph.nodes):
+        lines.append(f'    "{node}";')
+    for src in sorted(graph.out_links):
+        for dst in sorted(graph.out_links[src]):
+            lines.append(f'    "{src}" -> "{dst}";')
+    lines.append("}")
+    return "\n".join(lines)

graphmark-0.1.0/src/graphmark/graph.py

@@ -0,0 +1,107 @@
+"""Graph construction: catalog building, link resolution, and VaultGraph."""
+
+from __future__ import annotations
+
+import string
+from pathlib import Path
+
+from graphmark.config import VaultConfig
+from graphmark.interfaces import LinkExtractor, Resolver
+from graphmark.model import Document
+from graphmark.parse import parse_document
+
+_PUNCT_TABLE = str.maketrans(string.punctuation, " " * len(string.punctuation))
+
+
+def _normalize(text: str) -> str:
+    """Lowercase, replace punctuation with spaces, collapse whitespace."""
+    return " ".join(text.lower().translate(_PUNCT_TABLE).split())
+
+
+def build_catalog(docs: list[Document]) -> dict[str, list[str]]:
+    """Map normalized stem → list of rel_paths (len > 1 means ambiguous)."""
+    catalog: dict[str, list[str]] = {}
+    for doc in docs:
+        key = _normalize(Path(doc.rel_path).stem)
+        catalog.setdefault(key, []).append(doc.rel_path)
+    return catalog
+
+
+class NormalizeResolver:
+    """Resolves wikilink displays via normalized basename, with path-suffix fallback."""
+
+    def resolve(self, display: str, catalog: dict[str, list[str]]) -> str | None:
+        # Strip alias: "Note|alias" → "Note"
+        display = display.split("|")[0]
+        # Strip anchor: "Note#Section" → "Note"
+        display = display.split("#")[0]
+
+        if "/" in display:
+            # Path-suffix resolution: find unique rel_path ending with "display.md"
+            suffix = display.lower() + ".md"
+            all_paths = [p for paths in catalog.values() for p in paths]
+            matches = [p for p in all_paths if p.lower().endswith(suffix)]
+            return matches[0] if len(matches) == 1 else None
+
+        # Bare-link resolution: normalize and look up in catalog
+        key = _normalize(display)
+        paths = catalog.get(key)
+        if paths is None or len(paths) != 1:
+            return None
+        return paths[0]
+
+
+class VaultGraph:
+    """Built graph: all nodes plus resolved out/back adjacency."""
+
+    def __init__(
+        self,
+        nodes: dict[str, Document],
+        out_links: dict[str, set[str]],
+        back_links: dict[str, set[str]],
+    ) -> None:
+        self.nodes = nodes
+        self.out_links = out_links
+        self.back_links = back_links
+
+    @classmethod
+    def build(
+        cls,
+        config: VaultConfig,
+        extractor: LinkExtractor,
+        resolver: Resolver,
+    ) -> VaultGraph:
+        root = config.root
+        excluded = set(config.excluded_dirs)
+        rules = set(config.rules_files)
+
+        scoped = set(config.scoped_folders)
+        md_files: list[Path] = []
+        for path in sorted(root.rglob("*.md")):
+            rel_parts = path.relative_to(root).parts
+            if scoped and rel_parts[0] not in scoped:
+                continue
+            if any(p in excluded for p in rel_parts[:-1]):
+                continue
+            if path.name in rules:
+                continue
+            md_files.append(path)
+
+        docs = [parse_document(p, root) for p in md_files]
+        nodes = {doc.rel_path: doc for doc in docs}
+        catalog = build_catalog(docs)
+
+        out_links: dict[str, set[str]] = {rel: set() for rel in nodes}
+        back_links: dict[str, set[str]] = {rel: set() for rel in nodes}
+
+        for doc in docs:
+            for display in extractor.extract(doc.text):
+                target = resolver.resolve(display, catalog)
+                if target is not None and target != doc.rel_path:
+                    out_links[doc.rel_path].add(target)
+
+        for src, targets in out_links.items():
+            for dst in targets:
+                back_links[dst].add(src)
+
+        return cls(nodes, out_links, back_links)

graphmark-0.1.0/src/graphmark/interfaces.py

@@ -0,0 +1,33 @@
+"""Pluggable interfaces — the generality seams.
+
+Only the default wikilink/normalize implementations are required now; these Protocols exist so
+alternate link syntaxes and resolution strategies can be added later without touching the engine.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class LinkExtractor(Protocol):
+    """Extracts raw link displays from note text."""
+
+    def extract(self, text: str) -> list[str]:
+        """Return raw link displays found in ``text``, excluding links inside code spans.
+
+        A "display" is the inner text of a link before resolution, e.g. ``[[Note|alias]]`` yields
+        ``"Note|alias"`` (alias/anchor stripping happens in the Resolver).
+        """
+        ...
+
+
+class Resolver(Protocol):
+    """Resolves a link display to a target note."""
+
+    def resolve(self, display: str, catalog: dict[str, list[str]]) -> str | None:
+        """Resolve ``display`` to a target rel_path, or ``None`` if unresolved/ambiguous.
+
+        ``catalog`` maps a normalized note key to the list of rel_paths sharing that key (length > 1
+        means a collision → a bare link to it is ambiguous and must not resolve).
+        """
+        ...