pi-weave 0.1.7 → 0.1.8

package/src/core/frontmatter.ts

@@ -1,4 +1,4 @@
-import type { NoteMeta, NoteSource } from "./types";
+import type { NoteFrontMatter, NoteMeta, NoteSource } from "./types";
 import { NOTE_SOURCES } from "./types";
 
 /**
@@ -7,21 +7,94 @@ import { NOTE_SOURCES } from "./types";
  * Deliberately a *subset*: notes are meant to be human-editable plain text,
  * so we write only `key: value` scalars and `[a, b]` inline arrays, and we
  * parse exactly that. Anything richer belongs in the Markdown body.
+ *
+ * ## Parsing a subset without writing a subset
+ *
+ * "We parse a subset" used to also mean "we write a subset", and those are
+ * not the same promise. `parseNoteFile` read five keys and `serializeNote`
+ * wrote five keys, so every write through core silently deleted whatever
+ * else the file carried — `aliases`, `cssclass`, `publish`, any property an
+ * Obsidian user or another tool had added. Reading a note and appending one
+ * line destroyed the rest of its metadata (weave-workspace §11 P5).
+ *
+ * The fix is *not* a fuller YAML parser. A vault is plain text a human edits,
+ * and a parser that understands more is a parser that **rewrites** more —
+ * every construct it learns to read is a construct it will re-emit in its own
+ * preferred spelling. The fix is to stop conflating "parsed" with
+ * "preserved":
+ *
+ * - The five keys in {@link MANAGED_FRONT_MATTER_KEYS} are **owned**: parsed
+ *   into {@link NoteMeta}, and re-rendered from those values on write.
+ * - Every other line is **carried**: emitted as the exact bytes it was read
+ *   as, in its original position. Unknown keys, blank lines, junk without a
+ *   colon, and syntax this subset cannot represent at all — block lists,
+ *   folded scalars, nested maps — all survive, because none of them is ever
+ *   interpreted.
+ *
+ * The round-trip property is therefore: **owned fields round-trip by value,
+ * every other byte round-trips by byte, and key order is preserved.**
+ *
+ * ## Two rules that keep writes from inventing content
+ *
+ * **An owned key is never added to a file that did not have it, unless it
+ * carries a value the parser would not have defaulted to.** Real vaults are
+ * full of hand-written notes with no `created`/`updated`; `parseNoteFile`
+ * defaults those to `""`, and writing `created: ` back would be the engine
+ * fabricating metadata during an unrelated edit. Since no mutation path ever
+ * *sets* `created`, it stays `""` and stays absent; `updated` is appended
+ * only because a caller explicitly asked for a bump, which is a requested
+ * change rather than a silent one. See {@link isDefaulted}.
+ *
+ * **An owned key whose on-disk syntax this subset cannot represent is
+ * frozen**: carried verbatim, and not re-rendered or duplicated. Obsidian's
+ * property editor writes tags as a YAML block list —
+ *
+ * ```yaml
+ * tags:
+ *   - reading
+ * ```
+ *
+ * — which is exactly the shape a line-oriented serializer would destroy, by
+ * rewriting the parent as `tags: []` and orphaning the two children under it.
+ * So such a construct is left alone entirely and the append pass skips the
+ * key, because emitting a second `tags:` further down would leave the user
+ * with a duplicated property. The cost is that the engine neither reads nor
+ * updates those tags — the same blindness it has today, minus the data loss.
+ * It is observable rather than silent: every mutation API returns the note as
+ * re-parsed from what was actually written, so a caller that sets tags on
+ * such a note gets back a note whose tags did not change.
  */
 
 export interface ParsedNoteFile {
   meta: NoteMeta;
   body: string;
+  /** The front-matter block verbatim, for lossless re-serialization. */
+  frontMatter: NoteFrontMatter;
 }
 
 /** Generic, tolerant front-matter parse (any fields) — for non-note OKF files. */
 export interface ParsedFrontMatter {
   fields: Map<string, string>;
   body: string;
+  /** The raw block lines in file order, `---` fences excluded. */
+  lines: readonly string[];
 }
 
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
 
+/**
+ * The front-matter keys this module owns — parsed into {@link NoteMeta} and
+ * re-rendered on write. Everything else is carried verbatim.
+ *
+ * The array order is also the order in which a missing owned key is appended,
+ * so a note that gains `updated` gains it in a predictable place.
+ */
+export const MANAGED_FRONT_MATTER_KEYS = ["title", "created", "updated", "tags", "source"] as const;
+
+export type ManagedFrontMatterKey = (typeof MANAGED_FRONT_MATTER_KEYS)[number];
+
+const MANAGED: ReadonlySet<string> = new Set<string>(MANAGED_FRONT_MATTER_KEYS);
+
 export function quoteField(value: string): string {
   // Only quote when the value could confuse our subset parser.
   if (/[:#[\]]|^\s|\s$|^$/.test(value)) {
@@ -38,6 +111,48 @@ export function unquoteField(value: string): string {
   return trimmed;
 }
 
+/** One classified line of a front-matter block. */
+export interface FrontMatterLine {
+  /** The line exactly as it appears in the file. */
+  text: string;
+  /** The top-level key it declares, or null for blank/junk/continuation lines. */
+  key: string | null;
+  /**
+   * True when the value is a scalar or inline array this subset can both read
+   * and write. False for a key introducing a block construct — its value
+   * lives in the indented lines below it, which no line-oriented rewrite can
+   * safely touch.
+   */
+  scalar: boolean;
+}
+
+/**
+ * Classify a front-matter block line by line.
+ *
+ * The **single** rule for "which line is which key", shared by the parser and
+ * the serializer. A second copy of this rule is a second way for a write to
+ * disagree with a read about whether a line is owned — and disagreeing in
+ * that direction means either dropping a property or duplicating it.
+ *
+ * Block detection needs one line of lookahead, which is why this classifies
+ * the whole block rather than exposing a per-line predicate: `tags:` is a
+ * scalar with an empty value on its own, and the head of a list when the next
+ * line is indented.
+ */
+export function scanFrontMatter(lines: readonly string[]): FrontMatterLine[] {
+  return lines.map((text, i): FrontMatterLine => {
+    const idx = text.indexOf(":");
+    // Indented lines belong to whatever is above them: treating one as a
+    // top-level key would let the serializer hoist it out of its parent.
+    if (idx <= 0 || /^\s/.test(text)) return { text, key: null, scalar: false };
+    const key = text.slice(0, idx).trim();
+    if (key.length === 0) return { text, key: null, scalar: false };
+    const value = text.slice(idx + 1).trim();
+    const blockHead = value.length === 0 && /^\s+\S/.test(lines[i + 1] ?? "");
+    return { text, key, scalar: !blockHead };
+  });
+}
+
 function parseTags(value: string): string[] {
   const trimmed = value.trim();
   if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) {
@@ -58,21 +173,98 @@ function parseSource(value: string): NoteSource {
     : "human";
 }
 
-/** Serialize note metadata + body to the on-disk Markdown form. */
-export function serializeNote(meta: NoteMeta, body: string): string {
-  const lines = [
-    "---",
-    `title: ${quoteField(meta.title)}`,
-    `created: ${meta.created}`,
-    `updated: ${meta.updated}`,
-    `tags: [${meta.tags.map(quoteField).join(", ")}]`,
-    `source: ${meta.source}`,
-    "---",
-    "",
-    body.replace(/\s+$/, ""),
-    "",
-  ];
-  return lines.join("\n");
+/** Render one owned key from its parsed value. */
+function renderManaged(key: ManagedFrontMatterKey, meta: NoteMeta): string {
+  switch (key) {
+    case "title":
+      return `title: ${quoteField(meta.title)}`;
+    case "created":
+      return `created: ${meta.created}`;
+    case "updated":
+      return `updated: ${meta.updated}`;
+    case "tags":
+      return `tags: [${meta.tags.map(quoteField).join(", ")}]`;
+    default:
+      return `source: ${meta.source}`;
+  }
+}
+
+/**
+ * True when omitting `key` would parse back to the same value — the value is
+ * indistinguishable from the parser's default for an absent key.
+ *
+ * Gates **appending** an owned key that the file did not already declare, so
+ * an edit to a note's body cannot grow its front matter with fields the user
+ * never wrote. A key the file *does* declare is always re-rendered, never
+ * dropped: `tags: []` and `source: human` written by hand are the user's
+ * lines, and deleting them would be the mirror-image mutation.
+ *
+ * `title` is never defaulted: it is the one required field, and a note
+ * without it is malformed rather than empty.
+ */
+function isDefaulted(key: ManagedFrontMatterKey, meta: NoteMeta): boolean {
+  switch (key) {
+    case "title":
+      return false;
+    case "created":
+      return meta.created.length === 0;
+    case "updated":
+      return meta.updated.length === 0;
+    case "tags":
+      return meta.tags.length === 0;
+    default:
+      return meta.source === "human";
+  }
+}
+
+/**
+ * Serialize note metadata + body to the on-disk Markdown form.
+ *
+ * With `frontMatter` supplied — as `parseNoteFile` returns and every vault
+ * write path threads through — the original block is replayed line for line:
+ * owned scalar keys are re-rendered in place from `meta`, everything else is
+ * emitted as the exact bytes it was read as. Owned keys the original did not
+ * declare are appended at the end of the block, and only when they carry a
+ * non-default value.
+ *
+ * Without it, the canonical five-line block is written — the shape `addNote`
+ * creates for a brand-new note, where there is no prior layout to respect.
+ */
+export function serializeNote(meta: NoteMeta, body: string, frontMatter?: NoteFrontMatter): string {
+  const block = frontMatter === undefined ? canonicalBlock(meta) : replayBlock(meta, frontMatter);
+  return ["---", ...block, "---", "", body.replace(/\s+$/, ""), ""].join("\n");
+}
+
+function canonicalBlock(meta: NoteMeta): string[] {
+  return MANAGED_FRONT_MATTER_KEYS.map((key) => renderManaged(key, meta));
+}
+
+function replayBlock(meta: NoteMeta, frontMatter: NoteFrontMatter): string[] {
+  /** Top-level keys the file declares, in any syntax — including frozen ones. */
+  const declared = new Set<string>();
+  /** Owned keys already re-rendered, so a duplicate key collapses to one line. */
+  const rendered = new Set<string>();
+  const out: string[] = [];
+
+  for (const line of scanFrontMatter(frontMatter)) {
+    if (line.key !== null) declared.add(line.key);
+    if (line.key === null || !line.scalar || !MANAGED.has(line.key)) {
+      out.push(line.text); // carried verbatim — never interpreted, never reformatted
+      continue;
+    }
+    // A repeated owned key is a typo, and `parseFrontMatter` keeps the last
+    // occurrence. Re-rendering the parsed value at the *first* position and
+    // dropping the rest preserves that value while collapsing the duplicate.
+    if (rendered.has(line.key)) continue;
+    rendered.add(line.key);
+    out.push(renderManaged(line.key as ManagedFrontMatterKey, meta));
+  }
+
+  for (const key of MANAGED_FRONT_MATTER_KEYS) {
+    if (declared.has(key) || isDefaulted(key, meta)) continue;
+    out.push(renderManaged(key, meta));
+  }
+  return out;
 }
 
 /**
@@ -85,14 +277,16 @@ export function parseFrontMatter(text: string): ParsedFrontMatter | null {
   const match = FRONTMATTER_RE.exec(text);
   if (!match || match[1] === undefined) return null;
   const body = text.slice(match[0].length).replace(/^\n/, "").replace(/\s+$/, "");
+  const lines = match[1].split("\n");
   const fields = new Map<string, string>();
-  for (const line of match[1].split("\n")) {
-    if (line.trim().length === 0) continue;
-    const idx = line.indexOf(":");
-    if (idx <= 0) continue; // tolerate blank/junk lines, front matter is best-effort
-    fields.set(line.slice(0, idx).trim(), line.slice(idx + 1).trim());
+  for (const line of scanFrontMatter(lines)) {
+    // Blank/junk lines and block constructs are skipped: front matter is
+    // best-effort, and a value this subset cannot read is one it must not
+    // pretend to have read as `""`.
+    if (line.key === null || !line.scalar) continue;
+    fields.set(line.key, line.text.slice(line.text.indexOf(":") + 1).trim());
   }
-  return { fields, body };
+  return { fields, body, lines };
 }
 
 /**
@@ -115,5 +309,5 @@ export function parseNoteFile(text: string): ParsedNoteFile {
     tags: parseTags(parsed.fields.get("tags") ?? "[]"),
     source: parseSource(parsed.fields.get("source") ?? "human"),
   };
-  return { meta, body: parsed.body };
+  return { meta, body: parsed.body, frontMatter: parsed.lines };
 }

package/src/core/git.ts

@@ -18,7 +18,26 @@ export interface GitExecOptions {
 
 const DEFAULT_TIMEOUT_MS = 5_000;
 
+/**
+ * Process-wide count of `git` subprocesses spawned by this module.
+ *
+ * Every git call in core funnels through the `git()` helper below, so this
+ * is an exact spawn count rather than a model of one. `src/core/cache/
+ * workspace` samples it around its own work to report `CacheStats.gitCalls`,
+ * which is what makes "a no-change rebuild spawns zero git processes"
+ * (weave-workspace §4.1) an assertion about observed behaviour.
+ *
+ * Monotonic and never reset: callers take deltas.
+ */
+let spawnCount = 0;
+
+/** Number of git subprocesses spawned so far in this process. Monotonic. */
+export function gitSpawnCount(): number {
+  return spawnCount;
+}
+
 async function git(args: string[], cwd: string, timeoutMs: number): Promise<string | null> {
+  spawnCount += 1;
   return new Promise((resolve) => {
     execFile("git", args, { cwd, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 }, (err, stdout) => {
       if (err) resolve(null);

package/src/core/graph/build.ts

@@ -11,6 +11,7 @@
 import type { Note, RepoIndex, StalenessReport, VaultStatus } from "../types";
 import type { SummaryRecord } from "../summaries";
 import type { EdgeKind, GraphEdge, GraphModel, GraphNode } from "./model";
+import { buildPathIndex, resolveMentions, type PathIndex } from "./mentions";
 import { extractWikilinks } from "./wikilinks";
 
 /** Hard cap on note nodes (docs/weave-view.md M3 guard). */
@@ -85,7 +86,14 @@ function parseRemote(raw: string): { label: string; url: string } {
   return { label: tail.replace(/\.git$/, ""), url: s };
 }
 
-function buildVaultSide(input: BuildGraphInput, maxNotes: number, nodes: GraphNode[], edges: GraphEdge[]): string[] {
+function buildVaultSide(
+  input: BuildGraphInput,
+  maxNotes: number,
+  nodes: GraphNode[],
+  edges: GraphEdge[],
+  danglingLinks: Record<string, string[]>,
+  paths: PathIndex,
+): string[] {
   const truncated = input.notes.length > maxNotes;
   const kept = input.notes.slice(0, maxNotes);
 
@@ -108,8 +116,14 @@ function buildVaultSide(input: BuildGraphInput, maxNotes: number, nodes: GraphNo
       updated: note.updated,
     };
     if (note.tags.length > 0) detail.tags = note.tags.join(", ");
-    const dangling = links.length - resolved.length;
-    if (dangling > 0) detail["dangling links"] = String(dangling);
+    // The names, not just the count (§4.2). `detail` keeps carrying the count
+    // because it is what the TUI's side panel prints; the structured targets
+    // go on the model, where a UI can turn them into ghost nodes.
+    const dangling = links.filter((slug) => !keptSlugs.has(slug));
+    if (dangling.length > 0) {
+      detail["dangling links"] = String(dangling.length);
+      danglingLinks[note.slug] = dangling;
+    }
     detail.preview = preview(note.body);
 
     nodes.push({ id: `note:${note.slug}`, kind: "note", label: note.title, provenance: note.source, detail });
@@ -117,6 +131,14 @@ function buildVaultSide(input: BuildGraphInput, maxNotes: number, nodes: GraphNo
     for (const target of resolved) {
       edges.push({ source: `note:${note.slug}`, target: `note:${target}`, kind: "links-to" });
     }
+    // A note body naming a repo path → `mentions` (§4.4). Emitted after the
+    // wiki-links so a note's edges read vault-ward first, then code-ward, and
+    // only for paths that are already nodes — `paths` is built from the repo
+    // index, so a mention of an unindexed file resolves to its enclosing
+    // module or to nothing at all. Never to a phantom node.
+    for (const target of resolveMentions(note.body, paths)) {
+      edges.push({ source: `note:${note.slug}`, target, kind: "mentions" });
+    }
   }
   return [...keptSlugs];
 }
@@ -243,7 +265,16 @@ export function buildGraph(input: BuildGraphInput, options: { maxNotes?: number
   const maxNotes = options.maxNotes ?? DEFAULT_MAX_NOTES;
   const nodes: GraphNode[] = [];
   const edges: GraphEdge[] = [];
-  buildVaultSide(input, maxNotes, nodes, edges);
+  const danglingLinks: Record<string, string[]> = {};
+  // Built before the vault side, because that is where `mentions` edges are
+  // emitted and they need to know which repo paths are real nodes. Derived
+  // from the same `structure` arrays `buildRepositorySide` walks, so the two
+  // cannot disagree about which ids exist. Empty when there is no repository:
+  // a vault-only graph has nothing to mention.
+  const paths = input.repository === null
+    ? (new Map<string, string>() as PathIndex)
+    : buildPathIndex(input.repository.index.structure);
+  buildVaultSide(input, maxNotes, nodes, edges, danglingLinks, paths);
   if (input.repository !== null) {
     buildRepositorySide(input.repository, input.summaries, nodes, edges);
   }
@@ -252,7 +283,9 @@ export function buildGraph(input: BuildGraphInput, options: { maxNotes?: number
     staleness: input.repository?.staleness ?? null,
     nodes,
     edges,
+    danglingLinks,
   };
 }
 
 export type { EdgeKind, GraphEdge, GraphModel, GraphNode, NodeKind } from "./model";
+export { buildPathIndex, extractPathMentions, resolveMentions, type PathIndex } from "./mentions";

package/src/core/graph/current.ts

@@ -11,22 +11,17 @@
 
 import { readFile } from "node:fs/promises";
 import { join, resolve, sep } from "node:path";
-import {
-  assessStaleness,
-  buildGraph,
-  DEFAULT_MAX_NOTES,
-  findGitRoot,
-  getNote,
-  listNotes,
-  noteCount,
-  readRepoIndex,
-  readSummaryMap,
-  resolveNotePath,
-  resolveVaultRoot,
-  type BuildGraphInput,
-  type GraphModel,
-  type Note,
-} from "../index";
+// Imported from the individual modules rather than the `../index` barrel:
+// `src/core/cache/workspace` imports this file, and the barrel re-exports
+// that cache, so going through the barrel would close an import cycle.
+import { findGitRoot } from "../git";
+import { resolveVaultRoot } from "../paths";
+import { assessStaleness, readRepoIndex } from "../repoIndex";
+import { readSummaryMap } from "../summaries";
+import type { Note } from "../types";
+import { getNote, readVault, resolveNotePath } from "../vault";
+import { buildGraph, DEFAULT_MAX_NOTES, type BuildGraphInput } from "./build";
+import type { GraphModel } from "./model";
 
 /** A note read for the viewers (read-only; never cached). Mirrors the vault `Note` shape. */
 export interface ViewNote {
@@ -76,31 +71,49 @@ export async function readOkfFileForView(cwd: string, rel: string): Promise<{ pa
   }
 }
 
+/**
+ * Assemble the repository half of the graph input for `cwd`, or null when
+ * cwd is not inside a git repository with a readable `.okf` index. Shared
+ * with `src/core/cache/workspace` so the cached and uncached paths cannot
+ * drift in what they read.
+ */
+export async function readRepositorySide(
+  cwd: string,
+): Promise<Pick<BuildGraphInput, "repository" | "summaries"> | null> {
+  const repoRoot = await findGitRoot(cwd);
+  if (repoRoot === null) return null;
+  const index = await readRepoIndex(repoRoot);
+  if (index === null) return null;
+  return {
+    repository: { index, staleness: await assessStaleness(repoRoot) },
+    summaries: await readSummaryMap(repoRoot), // deep-scan sidecars, read live
+  };
+}
+
 /**
  * Assemble the fresh graph from disk. Called on every viewer fetch
  * (no caching — docs/weave-view.md §2). Reads the vault (capped at
  * DEFAULT_MAX_NOTES) and, when cwd is an indexed git repository, the repo
  * index + deep-scan summary sidecars. Degrades to a vault-only graph when
  * the repo has no index or the index is corrupt.
+ *
+ * One read per note: `readVault` returns bodies *and* the file count, so the
+ * old `listNotes` → `getNote`-per-slug → `noteCount` sequence (2N reads plus
+ * a third readdir) is now N reads and one readdir (weave-workspace §4.1).
  */
 export async function buildCurrentGraph(cwd: string, vaultRoot: string = resolveVaultRoot()): Promise<GraphModel> {
-  const noteSummaries = (await listNotes(vaultRoot)).slice(0, DEFAULT_MAX_NOTES);
-  const loaded = await Promise.all(noteSummaries.map((s) => getNote(vaultRoot, s.slug)));
-  const notes = loaded.filter((n): n is Note => n !== null);
+  const { notes, fileCount } = await readVault(vaultRoot);
 
   const input: BuildGraphInput = {
-    vault: { root: vaultRoot, exists: true, noteCount: await noteCount(vaultRoot) },
-    notes,
+    vault: { root: vaultRoot, exists: true, noteCount: fileCount },
+    notes: notes.slice(0, DEFAULT_MAX_NOTES),
     repository: null,
   };
 
-  const repoRoot = await findGitRoot(cwd);
-  if (repoRoot !== null) {
-    const index = await readRepoIndex(repoRoot);
-    if (index !== null) {
-      input.repository = { index, staleness: await assessStaleness(repoRoot) };
-      input.summaries = await readSummaryMap(repoRoot); // deep-scan sidecars, read live
-    }
+  const repo = await readRepositorySide(cwd);
+  if (repo !== null) {
+    input.repository = repo.repository;
+    if (repo.summaries !== undefined) input.summaries = repo.summaries;
   }
   return buildGraph(input);
 }

package/src/core/graph/mentions.ts

@@ -0,0 +1,170 @@
+/**
+ * `mentions` edges: a note body that names a repository path → note → node
+ * (weave-workspace §4.4, §15.5).
+ *
+ * `EdgeKind` has declared `"mentions"` since the graph model was written and
+ * `buildGraph` had never emitted one, so every consumer carried a branch that
+ * could not be taken and the legend advertised a relationship the product did
+ * not have. This module is the implementation side of that choice.
+ *
+ * Pure and I/O-free, like its sibling `wikilinks.ts`: a regex over a string
+ * and a lookup in a map built from the repo index. No parsing, no LLM, no
+ * new dependency (§4.4 is explicit about all three).
+ */
+
+import type { RepoStructure } from "../types";
+
+/**
+ * A repo-relative path candidate: two or more `/`-joined segments of word
+ * characters, dots and dashes.
+ *
+ * The lookbehind is the part doing real work. `(?<![\w/.@:-])` refuses to
+ * start a match immediately after a character that would make this the *tail*
+ * of something longer, which is what keeps `https://github.com/org/repo/src`
+ * and `user@host.com/path` from being read as repo paths. Without it every
+ * URL in every note becomes a candidate, and since candidates are only kept
+ * when they hit a real node the damage would be invisible until the day
+ * someone's repo happened to contain `org/repo`.
+ *
+ * At least one slash is required, so prose words are not candidates. Trailing
+ * sentence punctuation is stripped by {@link extractPathMentions} rather than
+ * excluded here, because `src/core.` at the end of a sentence should match
+ * `src/core` and a regex that refuses the dot cannot also accept
+ * `src/core/vault.ts`.
+ */
+const PATH_RE = /(?<![\w/.@:-])([\w.-]+(?:\/[\w.-]+)+)/g;
+
+/** Punctuation that ends a sentence rather than a path. */
+const TRAILING_PUNCT_RE = /[.,;:!?)\]}'"]+$/;
+
+/**
+ * Repo path → graph node id, for every path-addressable node the builder
+ * emits.
+ *
+ * Deliberately built from {@link RepoStructure} rather than by scanning the
+ * finished node list: both are derived from the same arrays, so mirroring the
+ * id construction here keeps the invariant that *every* value in this map is
+ * a node that exists, while reading it back off `GraphNode.detail.path` would
+ * mean re-parsing a display-only field (§4.2) to recover something structured
+ * we already had.
+ */
+export type PathIndex = ReadonlyMap<string, string>;
+
+/**
+ * Index the path-bearing nodes of a repository, exactly mirroring the ids
+ * `buildRepositorySide` emits.
+ *
+ * Insertion order is modules, then entry points, then packages, then `.okf`
+ * files. Later kinds do **not** overwrite earlier ones: a path that is both a
+ * module and an entry point resolves to the module, which is the coarser and
+ * more navigable of the two. The choice only has to be *stable*, and pinning
+ * it here is what makes it so.
+ *
+ * `(root)` is skipped. It is a display label for "files directly in the repo
+ * root", not a path, and no note body can spell it in a way that reaches
+ * here anyway.
+ */
+export function buildPathIndex(structure: RepoStructure): PathIndex {
+  const index = new Map<string, string>();
+  const put = (path: string, id: string): void => {
+    if (path.length > 0 && !index.has(path)) index.set(path, id);
+  };
+  for (const mod of structure.modules) {
+    if (mod.path === "(root)") continue;
+    put(mod.path, `module:${mod.path}`);
+  }
+  for (const entry of structure.entryPoints) put(entry, `entryPoint:${entry}`);
+  for (const pkg of structure.packages) put(pkg.manifestPath, `package:${pkg.manifestPath}`);
+  // `.okf` files are addressed by their repo-relative path (".okf/…"), while
+  // their node ids drop the prefix — the same rename `buildRepositorySide`
+  // performs.
+  for (const file of structure.okFiles ?? []) {
+    put(file, `okf:${file.replace(/^\.okf\//, "")}`);
+  }
+  return index;
+}
+
+/**
+ * Every distinct path-like token in a note body, in order of first
+ * appearance, with trailing sentence punctuation and trailing slashes
+ * removed.
+ *
+ * Exported for its own tests: the regex is the part of this feature most
+ * likely to be wrong, and testing it through `buildGraph` alone would mean
+ * every false-positive case needed a whole repo fixture.
+ */
+export function extractPathMentions(body: string): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const match of body.matchAll(PATH_RE)) {
+    // `?? ""` rather than an `undefined` guard: the group is mandatory, so it
+    // always participates and a guard would be a branch no input can take.
+    // An empty string falls out at the `includes("/")` check just below.
+    const path = (match[1] ?? "").replace(TRAILING_PUNCT_RE, "").replace(/\/+$/, "");
+    if (!path.includes("/") || seen.has(path)) continue;
+    seen.add(path);
+    out.push(path);
+  }
+  return out;
+}
+
+/**
+ * Resolve the repo nodes a note body mentions, as node ids in first-appearance
+ * order, deduplicated.
+ *
+ * ## Granularity: exact match, else the longest **enclosing** module
+ *
+ * This is the decision that keeps the edge count sane, and it runs in exactly
+ * one direction.
+ *
+ * *Never downward.* A note saying "see `src/core`" produces **one** edge, to
+ * `module:src/core`. It does not fan out to the files beneath it. Expanding a
+ * prefix downward is how a three-word sentence turns into forty edges and the
+ * graph column becomes unreadable — the explicit failure mode §4.4 warns
+ * about.
+ *
+ * *Upward, at most one step.* A note saying `src/core/vault.ts` is making a
+ * genuine reference, but most repository files are not graph nodes (only
+ * modules, entry points, packages and `.okf` files are), so an exact-match-only
+ * rule would silently drop the majority of real mentions and leave the feature
+ * looking broken. The fallback walks the path's ancestors longest-first and
+ * takes the first that is a **module**, so the mention lands on the nearest
+ * indexed container: `src/core/graph/build.ts` → `module:src/core`.
+ *
+ * The asymmetry is what makes this safe. Each distinct mentioned path resolves
+ * to **at most one** node, so the edges a note can contribute are bounded by
+ * the number of distinct paths it names, and the collapse only ever reduces
+ * that further — two files in the same module fold into a single edge because
+ * the result is deduplicated by target.
+ *
+ * The ancestor walk is restricted to modules on purpose: an entry point or a
+ * manifest is a *file*, and "this note mentions a path inside `package.json`"
+ * is not a relationship that exists.
+ */
+export function resolveMentions(body: string, paths: PathIndex): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const path of extractPathMentions(body)) {
+    const id = paths.get(path) ?? enclosingModule(path, paths);
+    if (id === null || id === undefined || seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return out;
+}
+
+/**
+ * The nearest ancestor directory of `path` that is an indexed module, or
+ * `null`. Longest first, so `src/core/graph/x.ts` prefers `src/core/graph`
+ * over `src/core` when both are modules.
+ */
+function enclosingModule(path: string, paths: PathIndex): string | null {
+  const segments = path.split("/");
+  for (let cut = segments.length - 1; cut > 0; cut--) {
+    const ancestor = segments.slice(0, cut).join("/");
+    const id = paths.get(ancestor);
+    // Only a module may absorb a mention of something inside it.
+    if (id !== undefined && id.startsWith("module:")) return id;
+  }
+  return null;
+}