agent-doc-system 1.2.0 → 1.3.0

package/core/discover.mjs

@@ -7,6 +7,7 @@
 import path from "node:path";
 import { AgentDocError, CODES } from "./codes.mjs";
 import { expandGlob, globToRegExp, assertGlob } from "../core/fsx.mjs";
+import { joinPath, ownsPath } from "./paths.mjs";
 
 // Roots excluded from inference and scaffolding. Authored descriptors strictly
 // below them can still claim units; descriptors at these exact roots cannot.
@@ -20,7 +21,7 @@ function notUnitRoots(cfg) {
 // mode shares this policy even for units with an existing authored descriptor.
 export function isNotUnitRoot(root, cfg) {
   return notUnitRoots(cfg)
-    .some((excluded) => root === excluded || root.startsWith(excluded + "/"));
+    .some((excluded) => ownsPath(excluded, root));
 }
 
 export function discoverUnits(repo, cfg, adapters) {
@@ -54,7 +55,7 @@ export function discoverUnits(repo, cfg, adapters) {
   for (const r of cfg.discovery.supplementalRoots || []) {
     candidates.add(r);
     // The descriptor loader also reads these fixed paths outside the globs.
-    if (repo.exists(r + "/" + cfg.discovery.componentDescriptorName)) descriptorRoots.add(r);
+    if (repo.exists(joinPath(r, cfg.discovery.componentDescriptorName))) descriptorRoots.add(r);
   }
 
   // Adapters may contribute roots the descriptor globs cannot know about: a

package/core/fsx.mjs

@@ -5,11 +5,21 @@
 // is what the graph's inputHash is computed over, so freshness detection can
 // never miss an input. This is the single most important property of the
 // original system and is preserved verbatim.
+//
+// The input set is the checkout as git sees it: paths git ignores are not part
+// of the repository (issue #45). A local build writing into an ignored
+// directory — `astro build` filling `.astro/`, a `build/` tree, a `*.log` —
+// must not move the inputHash, or a graph compiled after that build can never
+// be reproduced by a clean checkout or by CI. Git itself is the oracle (see
+// `ignoredPaths`); nothing here re-implements gitignore matching. Every read,
+// probe and listing below consults the same oracle, and `check` recomputes the
+// hash by running the same compile, so compile and check cannot disagree.
 import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { AgentDocError, CODES } from "./codes.mjs";
+import { canonicalPath, ownsPath, REPO_ROOT } from "./paths.mjs";
 
 export function sha256Hex(buf) {
   return createHash("sha256").update(buf).digest("hex");
@@ -39,6 +49,9 @@ export function assertRepoPath(p, ctx) {
 
 // Build/tooling output is never repository authority. Configurable per install
 // so a project with e.g. "target" or "vendor" trees keeps them out too.
+// This list applies everywhere, and is the *only* exclusion when there is no
+// git oracle (no repository, no git binary, or `noGit`). Inside a git
+// checkout, git-ignored paths are excluded in addition — see `ignoredPaths`.
 // Build and tooling output. Tooling caches and dependency directories only: a
 // name like `build`, `out` or `tmp` is far more likely to be a real unit in some
 // repository than a generated directory, and a repository with a deployable
@@ -62,6 +75,11 @@ export class Repo {
     this.nestedUnitRoots = new Map();
     this.generatedDirs = new Set(opts.generatedDirs || DEFAULT_GENERATED_DIRS);
     this.noGit = Boolean(opts.noGit);
+    // Per-Repo git caches. undefined = not asked yet; null = no answer.
+    this._hasGit = undefined;
+    this._prefix = undefined;
+    this._status = undefined;
+    this._ignored = undefined;
   }
   abs(rel) {
     const a = path.resolve(this.root, rel);
@@ -70,14 +88,71 @@ export class Repo {
     }
     return a;
   }
+  // The paths git ignores under this.root, asked once per Repo and cached, so
+  // every read, probe and listing in a run sees the same snapshot.
+  //
+  // `git status --ignored=matching` is the oracle (git-status(1)): it reports
+  // exactly the untracked paths that match an ignore pattern, and an ignored
+  // directory as one `dir/` entry without its contents. That gives git's own
+  // semantics for free:
+  //   - tracked files are never reported, so a tracked file that matches a
+  //     pattern stays an input ("tracked always wins", gitignore(5));
+  //   - nested .gitignore files, $GIT_DIR/info/exclude and core.excludesFile
+  //     apply with gitignore(5) precedence, negations included, and a file
+  //     whose parent directory is excluded cannot be re-included;
+  //   - a directory that is not itself ignored is never collapsed, only its
+  //     ignored contents are listed. (`git ls-files -o -i --directory` gets
+  //     this wrong: it also prints a non-ignored parent whose only content is
+  //     ignored, and aborts when run from inside an ignored directory.)
+  //
+  // The user's global core.excludesFile deliberately counts. An ignored
+  // untracked file is, by definition, absent from every clean checkout, so
+  // whichever ignore source matched it, dropping it moves this machine's input
+  // set *towards* what CI sees, never away from it — no ignore rule can hide a
+  // tracked file. Ignoring core.excludesFile would bring back issue #45 for
+  // anything a developer ignores globally (editor swap files, `.envrc`): the
+  // file would enter the hash while `git status`, and therefore the graph's
+  // `dirty` flag, stays silent about it.
+  //
+  // The snapshot comes from `statusRecords`, the same single `git status`
+  // call the compile's dirty check reads, so the input set and the `dirty`
+  // flag describe the same moment. Paths come back relative to the git
+  // toplevel and are re-keyed by `toRepoPaths`; an ignored *ancestor* of
+  // this.root is dropped there, so a project the user pointed the compiler at
+  // is never blanked out by an outer .gitignore.
+  //
+  // null when there is no oracle — `noGit`, not a git checkout, git missing
+  // or failing. The input set is then the filesystem minus generatedDirs,
+  // exactly as before #45.
+  ignoredPaths() {
+    if (this._ignored !== undefined) return this._ignored;
+    const recs = this.statusRecords();
+    const prefix = recs ? this.gitPrefix() : null;
+    this._ignored = recs && prefix !== null
+      ? new Set(this.toRepoPaths(recs.filter((r) => r.xy === "!!").map((r) => r.path), prefix))
+      : null;
+    return this._ignored;
+  }
+  // True when git ignores `rel` or one of its parent directories. Directory
+  // entries carry a trailing "/" in git's output.
+  isIgnored(rel) {
+    const set = this.ignoredPaths();
+    if (!set || set.size === 0 || !rel || rel === ".") return false;
+    if (set.has(rel) || set.has(rel + "/")) return true;
+    for (let i = rel.indexOf("/"); i >= 0; i = rel.indexOf("/", i + 1)) {
+      if (set.has(rel.slice(0, i + 1))) return true;
+    }
+    return false;
+  }
+  // An ignored path is probed as absent: that is what a clean checkout sees.
   exists(rel) {
-    const r = fs.existsSync(this.abs(rel));
+    const r = !this.isIgnored(rel) && fs.existsSync(this.abs(rel));
     this.probes.set(rel, r);
     return r;
   }
   isDir(rel) {
     try {
-      const r = fs.statSync(this.abs(rel)).isDirectory();
+      const r = !this.isIgnored(rel) && fs.statSync(this.abs(rel)).isDirectory();
       this.probes.set(rel, r);
       return r;
     } catch {
@@ -87,6 +162,16 @@ export class Repo {
   }
   readBytes(rel, { track = true } = {}) {
     const a = this.abs(rel);
+    // A tracked (input) read of an ignored path fails exactly as a read of a
+    // missing file does, so a descriptor that points into build output breaks
+    // locally the same way it breaks in CI. Untracked reads are not inputs.
+    if (track && this.isIgnored(rel)) {
+      throw new AgentDocError(
+        CODES.PATH_UNRESOLVED,
+        "path is ignored by git, so it is not a repository input: " + rel,
+        { path: rel }
+      );
+    }
     let buf;
     try {
       buf = fs.readFileSync(a);
@@ -114,10 +199,13 @@ export class Repo {
     return JSON.parse(this.readText(rel, { track: false }));
   }
   // Recursive listing, byte-sorted, never following symlinks out of the repo.
+  // Ignored directories are pruned, not descended: an ignored `node_modules`
+  // or `.astro` costs one Set lookup.
   walk(relDir, { exclude = () => false } = {}) {
     const base = relDir ? this.abs(relDir) : this.root;
     const out = [];
-    const stack = [base];
+    const ignored = this.ignoredPaths();
+    const stack = relDir && this.isIgnored(relDir) ? [] : [base];
     while (stack.length) {
       const dir = stack.pop();
       let entries;
@@ -132,6 +220,9 @@ export class Repo {
         const full = path.join(dir, ent.name);
         const rel = path.relative(this.root, full).split(path.sep).join("/");
         if (ent.isSymbolicLink()) continue;
+        // Parents are already known not to be ignored, so the entry itself is
+        // the only lookup needed.
+        if (ignored && ignored.has(ent.isDirectory() ? rel + "/" : rel)) continue;
         if (exclude(rel, ent)) continue;
         if (ent.isDirectory()) stack.push(full);
         else if (ent.isFile()) out.push(rel);
@@ -144,12 +235,11 @@ export class Repo {
   // Per-unit scans use the discovery result, never filesystem heuristics.
   // Keep walk() repository-wide for discovery, contracts and authored inputs.
   ownsUnitPath(unitRoot, rel) {
-    const normalize = (p) => path.posix.normalize(p || ".").replace(/^\.$/, "");
-    const root = normalize(unitRoot);
-    const target = normalize(rel);
-    if (root && target !== root && !target.startsWith(root + "/")) return false;
-    for (const child of this.nestedUnitRoots.get(root) || []) {
-      if (target === child || target.startsWith(child + "/")) return false;
+    if (!ownsPath(unitRoot, rel)) return false;
+    // nestedUnitRoots is keyed with the root spelled "" (see discoverUnits).
+    const root = canonicalPath(unitRoot);
+    for (const child of this.nestedUnitRoots.get(root === REPO_ROOT ? "" : root) || []) {
+      if (ownsPath(child, rel)) return false;
     }
     return true;
   }
@@ -179,12 +269,17 @@ export class Repo {
   // A directory listing is a compiler input like any other, and is recorded so
   // the input hash covers it. An untracked listing would let a change to a
   // directory's contents escape freshness detection.
+  // Ignored entries are left out, as if absent.
   listDir(relDir) {
     let names;
     try {
-      names = fs.readdirSync(this.abs(relDir), { withFileTypes: true })
-        .map((e) => (e.isDirectory() ? e.name + "/" : e.name))
-        .sort();
+      const prefix = relDir && relDir !== "." ? relDir + "/" : "";
+      names = this.isIgnored(relDir)
+        ? []
+        : fs.readdirSync(this.abs(relDir), { withFileTypes: true })
+          .map((e) => (e.isDirectory() ? e.name + "/" : e.name))
+          .filter((n) => !this.isIgnored(prefix + n.replace(/\/$/, "")))
+          .sort();
     } catch {
       names = [];
     }
@@ -204,17 +299,21 @@ export class Repo {
     });
     return trim ? out.trim() : out;
   }
+  // Cached per Repo, like gitPrefix: whether this.root is a git checkout does
+  // not change during a run, and each probe is a process spawn.
   hasGit() {
     if (this.noGit) return false;
+    if (this._hasGit !== undefined) return this._hasGit;
     try {
       const probe = execFileSync("git", ["rev-parse", "--git-dir"], {
         cwd: this.root,
         stdio: ["ignore", "pipe", "ignore"],
       });
-      return probe.toString().trim().length > 0;
+      this._hasGit = probe.toString().trim().length > 0;
     } catch {
-      return false;
+      this._hasGit = false;
     }
+    return this._hasGit;
   }
   // A checkout without git — a source tarball, a vendored copy, a CI runner with
   // no VCS — still compiles. Freshness then rests on the input hash alone, and
@@ -236,14 +335,15 @@ export class Repo {
   // tracker uses.
   gitPrefix() {
     if (this.noGit || !this.hasGit()) return null;
+    if (this._prefix !== undefined) return this._prefix;
     try {
-      return this.git(["rev-parse", "--show-prefix"]);
+      this._prefix = this.git(["rev-parse", "--show-prefix"]);
     } catch {
-      return null;
+      this._prefix = null;
     }
+    return this._prefix;
   }
-  toRepoPaths(gitPaths) {
-    const prefix = this.gitPrefix();
+  toRepoPaths(gitPaths, prefix = this.gitPrefix()) {
     if (prefix === null) return [];
     const out = [];
     for (const p of gitPaths) {
@@ -253,31 +353,46 @@ export class Repo {
     }
     return out;
   }
-  dirtyPaths() {
-    if (this.noGit || !this.hasGit()) return [];
-    let raw;
-    try {
-      // Untrimmed: a porcelain record is `XY <path>` with fixed columns, and an
-      // unstaged change has X = " ". Trimming would eat that space from the
-      // first record, so `.slice(3)` would drop the path's first character —
-      // ` M .agentdoc/graph.json` became `agentdoc/graph.json`, slipped past
-      // the output exclusion and counted as a dirty input (issue #11).
-      raw = this.git(["status", "--porcelain", "-z", "--untracked-files=all"], { trim: false });
-    } catch {
-      return [];
-    }
-    const paths = [];
-    let skipNext = false;
-    for (const rec of raw.split("\0")) {
-      if (!rec) continue;
-      // In -z format a rename/copy is two records: `XY <to>` then a bare
-      // `<from>` with no status. The bare record must be consumed, not parsed
-      // as a status line.
-      if (skipNext) { skipNext = false; continue; }
-      if (rec[0] === "R" || rec[0] === "C" || rec[1] === "R" || rec[1] === "C") skipNext = true;
-      paths.push(rec.slice(3));
+  // One `git status` for both questions a compile asks git about the
+  // working tree: what is dirty (`XY` records) and what is ignored (`!!`).
+  // `--untracked-files=all` lists untracked files individually, so they can
+  // be matched against the read tracker; `--ignored=matching` adds the
+  // ignored paths without descending into ignored directories.
+  // `--no-optional-locks` keeps it read-only: no refreshed index is written
+  // back, so it never contends with a git command the user is running.
+  // `-- .` scopes the scan to this.root, which may sit inside a larger
+  // checkout. Cached unless `fresh`: the ignore oracle must answer from one
+  // snapshot for the whole run.
+  statusRecords({ fresh = false } = {}) {
+    if (!fresh && this._status !== undefined) return this._status;
+    let recs = null;
+    if (!this.noGit && this.hasGit()) {
+      try {
+        // Untrimmed: a porcelain record is `XY <path>` with fixed columns, and
+        // an unstaged change has X = " ". Trimming would eat that space from
+        // the first record, so `.slice(3)` would drop the path's first
+        // character — ` M .agentdoc/graph.json` became `agentdoc/graph.json`,
+        // slipped past the output exclusion and counted as a dirty input
+        // (issue #11).
+        recs = parseStatusZ(this.git(
+          ["--no-optional-locks", "status", "--porcelain", "-z",
+            "--untracked-files=all", "--ignored=matching", "--", "."],
+          { trim: false }
+        ));
+      } catch {
+        recs = null;
+      }
     }
-    return this.toRepoPaths(paths);
+    if (!fresh) this._status = recs;
+    return recs;
+  }
+  // Fresh by default, so a caller holding a Repo sees the current tree. The
+  // compile passes `snapshot: true` to read the same status the ignore oracle
+  // used — one git call, and a dirty flag consistent with the input set.
+  dirtyPaths({ snapshot = false } = {}) {
+    const recs = this.statusRecords({ fresh: !snapshot });
+    if (!recs) return [];
+    return this.toRepoPaths(recs.filter((r) => r.xy !== "!!").map((r) => r.path));
   }
   // null on failure (bad ref, missing object store) so callers can tell
   // "the diff failed" apart from "the diff is empty".
@@ -291,6 +406,23 @@ export class Repo {
   }
 }
 
+// `git status --porcelain -z` records (git-status(1), "Porcelain Format
+// Version 1"): `XY <path>`, NUL-terminated, never quoted.
+function parseStatusZ(raw) {
+  const out = [];
+  let skipNext = false;
+  for (const rec of raw.split("\0")) {
+    if (!rec) continue;
+    // In -z format a rename/copy is two records: `XY <to>` then a bare
+    // `<from>` with no status. The bare record must be consumed, not parsed
+    // as a status line.
+    if (skipNext) { skipNext = false; continue; }
+    if (rec[0] === "R" || rec[0] === "C" || rec[1] === "R" || rec[1] === "C") skipNext = true;
+    out.push({ xy: rec.slice(0, 2), path: rec.slice(3) });
+  }
+  return out;
+}
+
 // Minimal glob: '*' matches within one segment, '**' matches any depth.
 export function globToRegExp(glob) {
   const segs = glob.split("/");

package/core/graph.mjs

@@ -9,7 +9,7 @@ import { assertDeterministic, structuralProjection } from "./determinism.mjs";
 import { sha256Hex } from "./fsx.mjs";
 
 export const COMPILER_NAME = "agentdoc-compiler";
-export const COMPILER_VERSION = "1.2.0";
+export const COMPILER_VERSION = "1.3.0";
 export const GRAPH_SCHEMA_VERSION = "agentdoc.dev/graph/v1";
 
 // Resolve symbolic provenance subjects to RFC 6901 pointers into the graph.

package/core/impact.mjs

@@ -5,6 +5,12 @@
 // from the graph alone, so the answer is available before any exploration.
 import { ContextIndex } from "./query.mjs";
 import { dependentScope, verificationForChange } from "./dependents.mjs";
+import { canonicalPath, ownsPath } from "./paths.mjs";
+
+// Changed paths are compared in the graph's canonical form (git's: no "./").
+// A path that is not repository-relative is kept verbatim so it is reported
+// as unmatched rather than silently rewritten.
+const canonical = (p) => canonicalPath(p) ?? p;
 
 // The affected-file classification is derived from the compiled graph, not from
 // a hand-written list of technology filenames. A list would go stale for every
@@ -59,7 +65,7 @@ export function impact(graph, changedPaths) {
   const matchedVerification = new Set();
 
   for (const raw of changedPaths) {
-    const p = raw.replace(/^\.\//, "");
+    const p = canonical(raw);
     const entity = idx.resolve(p);
     // A Resource is not a component. Adding it to `affectedComponents` put a
     // `resource:` ref in a list an agent reads as "components you must check",
@@ -83,7 +89,7 @@ export function impact(graph, changedPaths) {
     }
     if (kind === "verification") verificationPaths.add(p);
     if (kind === "input") dependencyPaths.add(p);
-    if (p.startsWith("agentdoc/")) catalogPaths.add(p);
+    if (ownsPath("agentdoc", p)) catalogPaths.add(p);
   }
 
   // A check's configuration is evidence of the components it covers, even
@@ -180,7 +186,8 @@ export function impact(graph, changedPaths) {
 
 function graphAffected(graph, changedPaths) {
   const inputs = new Set(graph.provenance.map((p) => p.path));
-  for (const p of changedPaths) if (inputs.has(p)) return true;
+  const paths = changedPaths.map(canonical);
+  for (const p of paths) if (inputs.has(p)) return true;
   const idx = new ContextIndex(graph);
-  return changedPaths.some((p) => idx.resolve(p));
+  return paths.some((p) => idx.resolve(p));
 }

package/core/paths.mjs

@@ -0,0 +1,71 @@
+// Repository-relative path semantics, in one place.
+//
+// Every path the catalog stores or matches is in one canonical form, the one
+// git uses for pathspecs and `ls-files` output: relative to the repository
+// root, '/'-separated, with no "./", no empty or "." segments and no trailing
+// slash. The repository root itself is the single value REPO_ROOT (".", which
+// is what a root unit's `sourcePath` has always recorded).
+//
+// Ownership is decided on whole path segments, never on raw string prefixes:
+// `src` owns `src` and `src/x.ts`, never `src2/x.ts`. The root owns every
+// repository path, which makes it the lowest-precedence owner: when several
+// owners match, the longest one wins, as in a routing table or CODEOWNERS.
+
+export const REPO_ROOT = ".";
+
+// Canonical form of a repository-relative path, or null for a path that is
+// not one: absolute, drive-qualified, backslash-separated or escaping the
+// repository through "..". Those are rejected here rather than resolved, the
+// same rule `isRepoPath` applies to authored paths.
+export function canonicalPath(p) {
+  if (typeof p !== "string") return null;
+  if (p.startsWith("/") || /^[A-Za-z]:/.test(p) || p.includes("\\")) return null;
+  const segs = [];
+  for (const seg of p.split("/")) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === "..") return null;
+    segs.push(seg);
+  }
+  return segs.length ? segs.join("/") : REPO_ROOT;
+}
+
+export function isRepoRoot(p) {
+  return canonicalPath(p) === REPO_ROOT;
+}
+
+// True when `owner` (a directory such as a unit root or a component's
+// sourcePath) contains `file`, segment by segment.
+export function ownsPath(owner, file) {
+  const o = canonicalPath(owner);
+  const f = canonicalPath(file);
+  if (o === null || f === null) return false;
+  if (o === REPO_ROOT) return true;
+  return f === o || f.startsWith(o + "/");
+}
+
+// The most specific owner of `file` among `owners`, or null. Specificity is
+// segment depth, so the root (depth 0) only wins when nothing else matches —
+// a one-character sibling such as `a` must not tie with ".".
+export function longestOwner(owners, file) {
+  let best = null;
+  let bestDepth = -1;
+  for (const o of owners) {
+    if (!ownsPath(o, file)) continue;
+    const c = canonicalPath(o);
+    const depth = c === REPO_ROOT ? 0 : c.split("/").length;
+    if (depth > bestDepth) {
+      best = o;
+      bestDepth = depth;
+    }
+  }
+  return best;
+}
+
+// Join a unit root and a path below it without ever producing "./x": a root
+// unit's manifest is `package.json`, exactly as git and every other path in
+// the graph spell it.
+export function joinPath(root, rel) {
+  const r = canonicalPath(root);
+  const base = r === null ? String(root).replace(/\/+$/, "") : r;
+  return base === REPO_ROOT || base === "" ? rel : base + "/" + rel;
+}

package/core/query.mjs

@@ -10,6 +10,7 @@
 import { AgentDocError, CODES } from "./codes.mjs";
 import { assertNoSecretsInText } from "./secrets.mjs";
 import { verificationForChange } from "./dependents.mjs";
+import { canonicalPath, longestOwner, ownsPath, REPO_ROOT } from "./paths.mjs";
 
 const DEFAULT_BUDGET = {
   relations: 40,
@@ -28,13 +29,13 @@ export class ContextIndex {
   constructor(graph) {
     this.graph = graph;
     this.byRef = new Map(graph.entities.map((e) => [e.ref, e]));
+    // Keyed by canonical source path, so a root unit's "." and any other
+    // spelling of the same directory land on one key.
     this.byPath = new Map();
     for (const e of graph.entities) {
-      const sp = e.derived && e.derived.sourcePath;
-      if (!sp) continue;
+      const sp = e.derived && canonicalPath(e.derived.sourcePath);
+      if (sp === null || sp === undefined) continue;
       this.byPath.set(sp, e);
-      // Longest path first so a nested path resolves to its own component
-      // rather than to a parent.
     }
     // Documentation and constraint files a descriptor links resolve to their
     // component, even when they live outside the source root. Following a
@@ -49,9 +50,12 @@ export class ContextIndex {
         ...(e.derived || {}).constraints || [],
         ...(e.derived || {}).runbooks || [],
       ];
-      for (const p of ctxPaths) if (!this.byDoc.has(p)) this.byDoc.set(p, e);
+      for (const raw of ctxPaths) {
+        const p = canonicalPath(raw) ?? raw;
+        if (!this.byDoc.has(p)) this.byDoc.set(p, e);
+      }
     }
-    this.paths = [...this.byPath.keys()].sort((a, b) => b.length - a.length);
+    this.paths = [...this.byPath.keys()];
     this.relationsByRef = new Map();
     for (const r of graph.relations) {
       if (!this.relationsByRef.has(r.sourceRef)) this.relationsByRef.set(r.sourceRef, []);
@@ -62,34 +66,64 @@ export class ContextIndex {
   }
 
   // A contract file resolves to the API entity that claims it, so "change this
-  // endpoint" routes to the boundary rather than to nothing.
+  // endpoint" routes to the boundary rather than to nothing. A contract ref
+  // names a file, a directory or a module prefix (`events` covering
+  // `events.go`, `events.proto`), the same coverage `Repo.filesWithPrefix`
+  // gives it — never a raw string prefix such as `events2/x`.
   contractFor(needle) {
-    const norm = needle.replace(/^\.\//, "").replace(/\/+$/, "");
+    const norm = canonicalPath(needle);
+    if (norm === null) return null;
     let best = null;
     for (const c of (this.graph.contracts || [])) {
-      if (norm === c.ref || norm.startsWith(c.ref)) {
+      if (contractCovers(c.ref, norm)) {
         if (!best || c.ref.length > best.ref.length) best = c;
       }
     }
     return best;
   }
+  // The component whose source root most specifically owns a repository path:
+  // the longest owning sourcePath, with a root component (".") as the
+  // lowest-precedence fallback. Null when no component owns the path.
+  ownerOf(file) {
+    const p = longestOwner(this.paths, file);
+    return p === null ? null : this.byPath.get(p);
+  }
   resolve(needle) {
     if (this.byRef.has(needle)) return this.byRef.get(needle);
-    const norm = needle.replace(/^\.\//, "").replace(/\/+$/, "");
+    if (looksLikeRef(needle)) return null;
+    // One canonical spelling for every path: `./a/b`, `a//b` and `a/b/` are
+    // all `a/b`. A path escaping the repository resolves to nothing.
+    const norm = canonicalPath(needle);
+    if (norm === null) return null;
     if (this.byDoc.has(norm)) return this.byDoc.get(norm);
-    if (this.byPath.has(norm)) return this.byPath.get(norm);
-    for (const p of this.paths) {
-      if (norm === p || norm.startsWith(p + "/")) return this.byPath.get(p);
-    }
-    for (const p of this.paths) {
-      if (needle.startsWith(p + "/")) return this.byPath.get(p);
-    }
-    if (this.byDoc.has(needle)) return this.byDoc.get(needle);
-    const c = this.contractFor(needle);
-    return c ? this.byRef.get(c.apiRef) || null : null;
+    // Precedence, most specific first: a linked document, a component source
+    // root, a contract's API, and only then a root component. The root owns
+    // every path, so it is the fallback for files nothing else claims; it
+    // must not take a contract file away from the API that declares it.
+    const owner = this.ownerOf(norm);
+    if (owner && canonicalPath(owner.derived.sourcePath) !== REPO_ROOT) return owner;
+    const c = this.contractFor(norm);
+    const api = c ? this.byRef.get(c.apiRef) || null : null;
+    return api || owner || null;
   }
 }
 
+export function contractCovers(ref, file) {
+  const r = canonicalPath(ref);
+  const f = canonicalPath(file);
+  if (r === null || f === null) return false;
+  if (ownsPath(r, f)) return true;
+  const cut = r.lastIndexOf("/");
+  const dir = r.slice(0, cut + 1);
+  return f.startsWith(dir) && f.slice(dir.length).startsWith(r.slice(cut + 1) + ".");
+}
+
+// An entity ref is `kind:namespace/name`. A needle shaped like one that names
+// no entity is an unresolved ref, not a repository path a root component owns.
+function looksLikeRef(needle) {
+  return /^[A-Za-z][\w-]*:/.test(needle);
+}
+
 function contractsOf(graph) {
   return graph.contracts || [];
 }
@@ -136,14 +170,15 @@ export function queryContext(graph, needle, opts = {}) {
   const apiProvider = entity.kind === "API" ? providerOf(ref) : null;
 
   const apiRefs = new Set([...providedApis, ...consumedApis]);
-  const srcPath = (entity.derived && entity.derived.sourcePath) || null;
   const events = g.interfaces.events.filter(
     (e) =>
       e.producers.includes(ref) ||
       e.consumers.includes(ref) ||
       // A contract library that ships the subject catalog owns those subjects,
-      // even when another component is the one that subscribes to them.
-      (srcPath && e.contract && e.contract.ref.startsWith(srcPath + "/"))
+      // even when another component is the one that subscribes to them. The
+      // owner is the component that most specifically owns the contract file,
+      // so a root component does not claim a nested library's catalog.
+      (e.contract && e.contract.ref && idx.ownerOf(e.contract.ref) === entity)
   );
   const externals = g.externalDependencies.filter((e) => e.componentRef === ref);
   const capabilities = g.capabilities.filter((e) => e.componentRef === ref);