graphmark 0.1.1__tar.gz → 0.2.0__tar.gz

graphmark-0.2.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: graphmark
+Version: 0.2.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, siloed notes, neighborhoods, PageRank, and link-gap suggestions over your notes,
+driven by a small config so it works on any Obsidian-family vault.
+
+> Status: **v0.1.1 on PyPI.** The engine is complete and pinned by a frozen differential oracle —
+> structural outputs reproduce a proven reference implementation exactly (shape, ordering,
+> tie-breaking). See `CLAUDE.md` for the architecture and the reference-parity contract.
+
+## Install
+
+```bash
+pip install graphmark        # or: uv pip install graphmark
+```
+
+Dev setup:
+
+```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
+```
+
+## CLI
+
+Every command takes `--config PATH` (TOML) and/or `--root PATH` (vault root; overrides the config's
+root). Output is deterministic JSON (DOT for `export dot`).
+
+```bash
+graphmark stats                          --root /path/to/vault
+graphmark orphans                        --config configs/my-brain.toml
+graphmark hubs --n 10                    --root /path/to/vault
+graphmark clusters                       --root /path/to/vault
+graphmark bridges                        --root /path/to/vault
+graphmark siloed                         --root /path/to/vault
+graphmark neighborhood --note a/b.md --depth 2  --root /path/to/vault
+graphmark pagerank --n 10 --alpha 0.85   --root /path/to/vault
+graphmark export dot                     --root /path/to/vault > graph.dot
+graphmark gaps                           --root /path/to/vault
+```
+
+Note: `gaps` is a **library-first** metric — it ranks and filters link-gap candidates over a
+similarity function you inject (`metrics.gaps(graph, similar_fn, ...)`); the package itself ships no
+embeddings. The CLI subcommand has no similarity source to inject, so `graphmark gaps` prints
+guidance to stderr and exits 2 rather than silently returning `[]`; use the library API (below).
+
+## Library
+
+```python
+from pathlib import Path
+
+from graphmark.config import VaultConfig
+from graphmark.graph import NormalizeResolver, VaultGraph
+from graphmark.metrics import gaps, hubs, stats
+from graphmark.parse import WikilinkExtractor
+
+config = VaultConfig(root=Path("/path/to/vault"))
+graph = VaultGraph.build(config, WikilinkExtractor(), NormalizeResolver())
+
+print(stats(graph))
+print(hubs(graph, n=10))
+
+# gaps: you supply similarity — graphmark owns the deterministic ranking/filtering.
+print(gaps(graph, similar_fn=my_similarity, threshold=0.6, k=8))
+```
+
+`dismiss.py` provides a content-hash dismissal store for gap suggestions: a dismissed pair stays
+suppressed only while both notes exist with unchanged content.
+
+## Development & releases
+
+Two long-lived branches: **`dev`** is the integration branch (open PRs against it); **`main`** is
+the release branch. Both are gated by CI (`ruff check` + `ruff format --check` + `pytest -q` on
+Ubuntu and macOS).
+
+Releases are automated by conventional commits. When `dev` is promoted to `main`,
+`.github/workflows/release.yml` runs [python-semantic-release](https://python-semantic-release.readthedocs.io):
+it reads the commit history since the last tag, bumps the version, updates `CHANGELOG.md`, tags
+`v<version>`, cuts a GitHub release, and publishes to PyPI via OIDC Trusted Publishing. So the
+version is a function of your commit messages — `feat:` bumps the minor, `fix:`/`perf:` the patch
+(pre-1.0, breaking changes bump the minor, not the major). No manual version edits, no tokens.

graphmark-0.2.0/README.md

@@ -0,0 +1,86 @@
+# graphmark
+
+Deterministic knowledge-graph analysis for markdown / `[[wikilink]]` vaults — orphans, hubs,
+clusters, bridges, siloed notes, neighborhoods, PageRank, and link-gap suggestions over your notes,
+driven by a small config so it works on any Obsidian-family vault.
+
+> Status: **v0.1.1 on PyPI.** The engine is complete and pinned by a frozen differential oracle —
+> structural outputs reproduce a proven reference implementation exactly (shape, ordering,
+> tie-breaking). See `CLAUDE.md` for the architecture and the reference-parity contract.
+
+## Install
+
+```bash
+pip install graphmark        # or: uv pip install graphmark
+```
+
+Dev setup:
+
+```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
+```
+
+## CLI
+
+Every command takes `--config PATH` (TOML) and/or `--root PATH` (vault root; overrides the config's
+root). Output is deterministic JSON (DOT for `export dot`).
+
+```bash
+graphmark stats                          --root /path/to/vault
+graphmark orphans                        --config configs/my-brain.toml
+graphmark hubs --n 10                    --root /path/to/vault
+graphmark clusters                       --root /path/to/vault
+graphmark bridges                        --root /path/to/vault
+graphmark siloed                         --root /path/to/vault
+graphmark neighborhood --note a/b.md --depth 2  --root /path/to/vault
+graphmark pagerank --n 10 --alpha 0.85   --root /path/to/vault
+graphmark export dot                     --root /path/to/vault > graph.dot
+graphmark gaps                           --root /path/to/vault
+```
+
+Note: `gaps` is a **library-first** metric — it ranks and filters link-gap candidates over a
+similarity function you inject (`metrics.gaps(graph, similar_fn, ...)`); the package itself ships no
+embeddings. The CLI subcommand has no similarity source to inject, so `graphmark gaps` prints
+guidance to stderr and exits 2 rather than silently returning `[]`; use the library API (below).
+
+## Library
+
+```python
+from pathlib import Path
+
+from graphmark.config import VaultConfig
+from graphmark.graph import NormalizeResolver, VaultGraph
+from graphmark.metrics import gaps, hubs, stats
+from graphmark.parse import WikilinkExtractor
+
+config = VaultConfig(root=Path("/path/to/vault"))
+graph = VaultGraph.build(config, WikilinkExtractor(), NormalizeResolver())
+
+print(stats(graph))
+print(hubs(graph, n=10))
+
+# gaps: you supply similarity — graphmark owns the deterministic ranking/filtering.
+print(gaps(graph, similar_fn=my_similarity, threshold=0.6, k=8))
+```
+
+`dismiss.py` provides a content-hash dismissal store for gap suggestions: a dismissed pair stays
+suppressed only while both notes exist with unchanged content.
+
+## Development & releases
+
+Two long-lived branches: **`dev`** is the integration branch (open PRs against it); **`main`** is
+the release branch. Both are gated by CI (`ruff check` + `ruff format --check` + `pytest -q` on
+Ubuntu and macOS).
+
+Releases are automated by conventional commits. When `dev` is promoted to `main`,
+`.github/workflows/release.yml` runs [python-semantic-release](https://python-semantic-release.readthedocs.io):
+it reads the commit history since the last tag, bumps the version, updates `CHANGELOG.md`, tags
+`v<version>`, cuts a GitHub release, and publishes to PyPI via OIDC Trusted Publishing. So the
+version is a function of your commit messages — `feat:` bumps the minor, `fix:`/`perf:` the patch
+(pre-1.0, breaking changes bump the minor, not the major). No manual version edits, no tokens.

graphmark-0.2.0/docs/ROADMAP.md

@@ -0,0 +1,111 @@
+# 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, siloed notes, neighborhoods, PageRank, and link-gap
+suggestions — driven by a small config so it works on **any** Obsidian-family vault. Published on
+PyPI; generalized from a proven vault-specific engine (`brain_map.py`).
+
+The central fact of this repo: **correctness is pinned by a frozen differential oracle.** Structural
+outputs are the verbatim results of the reference engine, PageRank is checked against networkx, and
+live-vault parity diffing backs the fixtures. The executor cannot regenerate the oracle — so a
+**green gate proves correctness**, and Track A/C work is autonomous-safe.
+
+Identity (settled 2026-07-19): graphmark is **personal infrastructure with a public correctness
+story** — the priority consumer is the owner's vault seam (`graph_cli.py`), not external adoption.
+
+## 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).
+- **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
+  (already-linked / self / threshold / max-score / prefix / dismissed filters; reciprocal dedup;
+  novelty-first ordering); the embedding source is injected by the caller. The gate stays
+  fastembed-free.
+- **Packaging** — PyPI Trusted Publishing on `v*` tags; networkx-only runtime dependency.
+- **Reintegration** — the-vault's `graph_cli.py` consumes the package and injects the vault's
+  similarity function; /connect and /garden run on it.
+
+## Direction
+
+### Track A — Engine parity (CLOSED at v0.1.1 — do not re-propose engine work)
+
+### Track C — Hardening & honest surface (gate-verifiable; autonomous-safe)
+
+_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.**
+
+- 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)
+
+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.
+
+### Track B — Judgment the oracle can't cover (human-validated)
+
+- New fixtures on a **different schema** than my-brain have hand-authored expected values → 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.
+- **Pre-frozen asserting tests.** New modules/behaviors ship only when the conductor has committed
+  the failing test before the slice runs — a green gate must prove the new code, not just tolerate it.
+- **The gaps contract:** graphmark owns deterministic ranking/filtering; similarity is **injected**;
+  the package and its gate stay embedding-free (no fastembed/numpy/scipy in deps).
+- **Implement within the seeded interfaces.** Do not redesign `model`/`interfaces`/`config`
+  boundaries.
+- **Dependency-light.** Shipped runtime dep is `networkx` only.
+- **Keep the layers separate** — engine (vault-agnostic) / config (the domain seam) / surface
+  (JSON, DOT, CLI) / dismissal store. See `CLAUDE.md`.
+- **TDD, tracer-bullet slices.** `afk-sized` = single-purpose, independently testable; larger is
+  `needs-decomposition`.
+
+## Non-goals (CLOSED as dropped 2026-07-19 — do not propose)
+
+Evaluated against the ecosystem and dropped for zero consumer pull; do not re-litigate:
+
+- Embeddings / semantic search / any similarity backend **inside** the package.
+- Betweenness centrality, Louvain/Leiden community detection.
+- CSV/GML/Cypher export; incremental/cached builds; any LLM "propose" pass.
+- MCP server or retrieval/search surface.
+- Alternate link-syntax adapters (Logseq, `[](.)` markdown) — the pluggable interfaces exist so
+  these _can_ be added on demand; do not build them speculatively.
+- Re-platforming (no swapping networkx; no async/parallel rewrites).
+- Performance work without a benchmark showing pain (the live consumer is a ~340-note vault). The
+  known ceilings — O(L·N) path-suffix resolution, O(A·(V+E)) `siloed_notes`, per-metric graph
+  rebuilds — are documented, accepted, and not to be optimized speculatively.

{graphmark-0.1.1 → graphmark-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphmark"
-version = "0.1.1"
+version = "0.2.0"
 description = "Deterministic knowledge-graph analysis for markdown / [[wikilink]] vaults."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -50,3 +50,26 @@ select = ["E", "F", "I", "UP", "B", "SIM"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[tool.semantic_release]
+# Deployment is driven by conventional-commit history: when dev is promoted to main, the
+# release workflow (.github/workflows/release.yml) runs python-semantic-release, which reads the
+# commits since the last tag, decides the bump, updates the version below, writes CHANGELOG.md,
+# commits, tags v<version>, and cuts a GitHub release. The same workflow then publishes to PyPI.
+version_toml = ["pyproject.toml:project.version"]
+# The semantic-release action runs in its own container without uv; leave the build to the
+# workflow's own uv-based publish step (release.yml), so this is intentionally empty.
+build_command = ""
+tag_format = "v{version}"
+commit_message = "chore(release): {version} [skip ci]"
+# Pre-1.0: a breaking change bumps the minor, not the major, until the API is declared stable.
+major_on_zero = false
+allow_zero_version = true
+
+[tool.semantic_release.branches.main]
+match = "main"
+
+[tool.semantic_release.commit_parser_options]
+# feat -> minor, fix/perf -> patch; these types appear in the changelog.
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]

graphmark-0.2.0/src/graphmark/__init__.py

@@ -0,0 +1,8 @@
+"""graphmark — deterministic knowledge-graph analysis for markdown/wikilink vaults."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("graphmark")
+except PackageNotFoundError:  # un-installed source checkout
+    __version__ = "0.0.0+unknown"

{graphmark-0.1.1 → graphmark-0.2.0}/src/graphmark/cli.py

@@ -12,7 +12,6 @@ from graphmark.graph import NormalizeResolver, VaultGraph
 from graphmark.metrics import (
     bridges,
     clusters,
-    gaps,
     hubs,
     neighborhood,
     orphans,
@@ -73,6 +72,16 @@ def main() -> None:
         parser.print_help()
         sys.exit(1)
 
+    if args.command == "gaps":
+        # gaps needs a caller-injected similarity source the CLI can't supply; it is
+        # library-only. Signpost the library API rather than silently printing [].
+        print(
+            "gaps requires an injected similarity source; use the library API "
+            "(graphmark.metrics.gaps) — see README",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
     graph, config = _load(args)
 
     if args.command == "stats":
@@ -88,13 +97,16 @@ def main() -> None:
     elif args.command == "siloed":
         print(to_json(siloed_notes(graph)))
     elif args.command == "neighborhood":
-        print(to_json(neighborhood(graph, args.note, depth=args.depth)))
+        try:
+            result = neighborhood(graph, args.note, depth=args.depth)
+        except ValueError as e:
+            print(f"error: {e}", file=sys.stderr)
+            sys.exit(2)
+        print(to_json(result))
     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__":

{graphmark-0.1.1 → graphmark-0.2.0}/src/graphmark/config.py

@@ -1,8 +1,8 @@
 """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.
+``VaultConfig`` holds every vault-specific policy the engine consults. ``load_config`` reads a
+TOML file into a ``VaultConfig`` (paths resolved relative to the TOML's directory). Fixture tests
+may construct ``VaultConfig`` directly.
 """
 
 from __future__ import annotations
@@ -20,16 +20,23 @@ class VaultConfig:
     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."""
+    """Load a VaultConfig from a TOML file.
+
+    ``root`` is the only required key (resolved relative to the TOML's directory). Every other
+    key that maps to a ``VaultConfig`` field is optional and falls back to the dataclass default;
+    any other key in the TOML is silently ignored. A TOML missing ``root`` raises ``ValueError``
+    naming the file and the missing key.
+    """
     with open(path, "rb") as f:
         data = tomllib.load(f)
 
+    if "root" not in data:
+        raise ValueError(f"config {path}: missing required key 'root'")
+
     toml_dir = path.parent
     root = toml_dir / data["root"]
 
@@ -38,7 +45,5 @@ def load_config(path: Path) -> VaultConfig:
         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.1 → graphmark-0.2.0}/src/graphmark/dismiss.py

@@ -37,10 +37,19 @@ def record_dismissal(root: Path, a: str, b: str, *, path: str = _DEFAULT_PATH) -
 
 
 def load_dismissed(root: Path, *, path: str = _DEFAULT_PATH) -> dict:
+    """Load the dismissal store, treating a corrupt or unreadable store as empty.
+
+    Mirrors ``record_dismissal``'s guard: invalid JSON, an unreadable file, or a non-dict
+    payload all mean "no active dismissals", never a crash.
+    """
     dismissed_file = root / path
     if not dismissed_file.exists():
         return {}
-    return json.loads(dismissed_file.read_text())
+    try:
+        data = json.loads(dismissed_file.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+    return data if isinstance(data, dict) else {}
 
 
 def active_dismissed_sigs(root: Path, *, path: str = _DEFAULT_PATH) -> set[str]:

{graphmark-0.1.1 → graphmark-0.2.0}/src/graphmark/export.py

@@ -12,13 +12,22 @@ def to_json(obj) -> str:
     return json.dumps(obj)
 
 
+def _dot_quote(s: str) -> str:
+    """Escape a string for use inside a double-quoted DOT identifier.
+
+    Backslash must be escaped before the quote so an already-present ``\\`` is not
+    double-counted. Paths without special characters are returned unchanged.
+    """
+    return s.replace("\\", "\\\\").replace('"', '\\"')
+
+
 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}";')
+        lines.append(f'    "{_dot_quote(node)}";')
     for src in sorted(graph.out_links):
         for dst in sorted(graph.out_links[src]):
-            lines.append(f'    "{src}" -> "{dst}";')
+            lines.append(f'    "{_dot_quote(src)}" -> "{_dot_quote(dst)}";')
     lines.append("}")
     return "\n".join(lines)

{graphmark-0.1.1 → graphmark-0.2.0}/src/graphmark/graph.py

@@ -30,6 +30,23 @@ def build_catalog(docs: list[Document]) -> dict[str, list[str]]:
 class NormalizeResolver:
     """Resolves wikilink displays via normalized basename, with path-suffix fallback."""
 
+    def __init__(self) -> None:
+        # Cache the flattened path list per catalog identity. catalog is invariant for a whole
+        # VaultGraph.build(), so folder-style links reuse one flatten instead of rebuilding it
+        # on every call. Keyed by id() and single-slot: a new catalog evicts the previous.
+        self._flat_cache_id: int | None = None
+        self._flat_cache: list[str] | None = None
+
+    @staticmethod
+    def _compute_flat(catalog: dict[str, list[str]]) -> list[str]:
+        return [p for paths in catalog.values() for p in paths]
+
+    def _flatten_paths(self, catalog: dict[str, list[str]]) -> list[str]:
+        if self._flat_cache_id != id(catalog) or self._flat_cache is None:
+            self._flat_cache = self._compute_flat(catalog)
+            self._flat_cache_id = id(catalog)
+        return self._flat_cache
+
     def resolve(self, display: str, catalog: dict[str, list[str]]) -> str | None:
         # Strip alias: "Note|alias" → "Note"
         display = display.split("|")[0]
@@ -39,7 +56,7 @@ class NormalizeResolver:
         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]
+            all_paths = self._flatten_paths(catalog)
             matches = [p for p in all_paths if p.lower().endswith(suffix)]
             return matches[0] if len(matches) == 1 else None
 

{graphmark-0.1.1 → graphmark-0.2.0}/src/graphmark/interfaces.py

@@ -21,6 +21,17 @@ class LinkExtractor(Protocol):
         ...
 
 
+class Similarity(Protocol):
+    """Injected similarity source for ``gaps()`` — the package's similarity seam.
+
+    graphmark owns the deterministic ranking/filtering; the similarity *source* is supplied by
+    the caller. An implementation returns up to ``k`` ``(rel_path, score)`` pairs most similar to
+    the note at ``rel_path`` (higher score = more similar). No embeddings ship in this package.
+    """
+
+    def __call__(self, rel_path: str, k: int) -> list[tuple[str, float]]: ...
+
+
 class Resolver(Protocol):
     """Resolves a link display to a target note."""
 

{graphmark-0.1.1 → graphmark-0.2.0}/src/graphmark/metrics.py

@@ -10,6 +10,16 @@ import networkx as nx
 
 from graphmark.config import VaultConfig
 from graphmark.graph import VaultGraph
+from graphmark.interfaces import Similarity
+
+# Validated gaps banding policy — the band proven in daily /connect + /garden use on the owner's
+# live vault (~340 notes). Ships in-package so any consumer gets the tuned band instead of
+# re-deriving policy; consumers opt in by passing these to gaps(). gaps()'s own signature defaults
+# are intentionally left unchanged (non-breaking).
+GAPS_DEFAULT_THRESHOLD = 0.6
+GAPS_DEFAULT_MAX_SCORE = 0.92
+GAPS_DEFAULT_K = 8
+GAPS_DEFAULT_HUB_DEGREE = 40
 
 
 def _undirected(graph: VaultGraph) -> nx.Graph:
@@ -85,7 +95,13 @@ def siloed_notes(graph: VaultGraph) -> list[str]:
     for bridge in nx.articulation_points(G):
         H = G.copy()
         H.remove_node(bridge)
-        components = sorted(nx.connected_components(H), key=lambda c: -len(c))
+        # Largest component is the mainland; the rest are islands. When components tie for
+        # largest, break the tie deterministically by member order (the component whose sorted
+        # members are lexicographically smallest is the mainland) rather than relying on
+        # nx.connected_components' incidental traversal order. NOTE: this tie-break is
+        # graphmark's own defined convention — it is unverified against the reference engine,
+        # which no frozen fixture exercises; a future divergence is caught by this rule + test.
+        components = sorted(nx.connected_components(H), key=lambda c: (-len(c), sorted(c)))
         for component in components[1:]:
             island_nodes.update(component)
     return sorted(island_nodes)
@@ -133,7 +149,7 @@ def pagerank(graph: VaultGraph, n: int = 10, alpha: float = 0.85) -> list[list]:
 
 def gaps(
     graph: VaultGraph,
-    similar_fn,
+    similar_fn: Similarity,
     threshold: float = 0.0,
     k: int = 5,
     note: str | None = None,
@@ -143,7 +159,12 @@ def gaps(
     hub_degree: int | None = None,
     targets: list | None = None,
 ) -> list[dict]:
-    """Return link-gap suggestions ranked by novelty (non-hub, cross-folder, score-desc)."""
+    """Return link-gap suggestions ranked by novelty (non-hub, cross-folder, score-desc).
+
+    ``similar_fn`` is the injected similarity source (see ``interfaces.Similarity``): given a
+    ``rel_path`` and ``k`` it returns up to ``k`` ``(other_rel_path, score)`` pairs. graphmark
+    owns all deterministic ranking/filtering; the similarity source is the caller's.
+    """
     if note is not None:
         target_list = [note]
     elif targets is not None:
@@ -195,7 +216,13 @@ def gaps(
 
 
 def neighborhood(graph: VaultGraph, note: str, depth: int = 1) -> dict:
-    """Return out/back neighbors (and two_hop when depth>=2) for a note."""
+    """Return out/back neighbors (and two_hop when depth>=2) for a note.
+
+    Raises ``ValueError`` if ``note`` is not a node in the graph, so a typo is distinguishable
+    from a genuinely isolated note.
+    """
+    if note not in graph.nodes:
+        raise ValueError(f"unknown note: {note}")
     out = sorted(graph.out_links.get(note, set()))
     back = sorted(graph.back_links.get(note, set()))
     result: dict = {"note": note, "out": out, "back": back}

graphmark-0.2.0/src/graphmark/model.py

@@ -0,0 +1,20 @@
+"""Core data model for graphmark.
+
+``Document`` is the only model type the engine consumes; the resolved graph is
+``graph.VaultGraph``. Do not rename ``Document``'s type or fields.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["Document"]
+
+
+@dataclass(frozen=True)
+class Document:
+    """A single note in the vault."""
+
+    rel_path: str  # posix rel-path from vault root, e.g. "brain/North Star.md"
+    text: str
+    frontmatter: dict