@mrciphersmith/keryx 0.2.80 → 0.2.81

package/src/gdgraph/query.ts

@@ -9,6 +9,7 @@ import type {
   SymbolNode,
   WikiPageNode,
 } from "./types";
+import { TYPE_ONLY_IMPORT_KIND } from "./types";
 import { resolveGraphTarget } from "./target";
 
 export async function loadGraph(projectRoot: string): Promise<GraphData> {
@@ -116,7 +117,19 @@ export function getCycles(graph: GraphData): string[][] {
     // load-order cycle this query answers (P1, flow 140). Excluding it here
     // — rather than reclassifying `edge.kind` — leaves orphans/affected
     // untouched (AC5): both still treat the edge as a normal import.
-    if (edge.kind !== "imports" || edge.importKind === "dynamic-import") {
+    //
+    // A `type-only` edge (AFC-11, flow 234) is excluded for the same reason:
+    // `import type`/`export type … from`/an all-`type`-specifier import is
+    // erased by the compiler, so it never runs at module-load time and a
+    // cycle closed only through such edges is not a real runtime deadlock.
+    // Same non-reclassification rule applies — `edge.kind` stays "imports"
+    // so getOrphans/getAffected/computeAffected still see it as a real
+    // dependency for impact analysis; only this load-order adjacency drops it.
+    if (
+      edge.kind !== "imports" ||
+      edge.importKind === "dynamic-import" ||
+      edge.importKind === TYPE_ONLY_IMPORT_KIND
+    ) {
       continue;
     }
     adjacency.get(edge.from)?.push(edge.to);

package/src/gdgraph/service.test.ts

@@ -2,7 +2,7 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { expect, test } from "bun:test";
-import { createGdgraphService } from "./service";
+import { createGdgraphService, UnknownGraphTargetError } from "./service";
 
 async function makeProject(): Promise<string> {
   const root = await mkdtemp(path.join(tmpdir(), "keryx-svc-"));
@@ -44,6 +44,36 @@ test("AC5.3/T-1 — service.repomap writes artifacts/repomap.md deterministicall
   }
 });
 
+// AFC-10 (flow 234, phase 2): before this task, `service.affected` for a
+// target the graph never indexed and a target the graph indexed but found no
+// edges for returned byte-identical shapes — `{dependencies: [], dependents:
+// [], ranked: []}` — differing only in the echoed-back `target` string.
+// Measured directly against this exact fixture: an unknown path
+// ("src/does-not-exist.ts") and a real, indexed, edge-less leaf file
+// produced the same `{dependencies, dependents, ranked}`. That is the same
+// defect class phase 1 closed at eight other sites — a failure rendered as a
+// legitimate empty success — so an unknown target must now be reported
+// distinguishably instead of silently resolving to an empty result.
+test("AFC-10 — service.affected on a target the graph never indexed throws UnknownGraphTargetError, distinct from an indexed-but-edgeless target", async () => {
+  const root = await makeProject();
+  try {
+    await writeFile(path.join(root, "src", "isolated.ts"), "export const iso = 1;\n");
+    const service = createGdgraphService();
+    await service.build(root);
+
+    // Indexed, legitimately no edges at all: a real success, not an error.
+    const indexedNoEdges = await service.affected(root, "src/isolated.ts");
+    expect(indexedNoEdges.dependencies).toEqual([]);
+    expect(indexedNoEdges.dependents).toEqual([]);
+
+    // Never indexed: must be distinguishable from the above, not the same
+    // `{dependencies: [], dependents: []}` shape under a different `target`.
+    await expect(service.affected(root, "src/does-not-exist.ts")).rejects.toThrow(UnknownGraphTargetError);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test("service.query returns cycles + orphans over the built graph", async () => {
   const root = await makeProject();
   try {

package/src/gdgraph/service.ts

@@ -20,6 +20,29 @@ export interface GdgraphService {
   query(cwd: string, q: "cycles" | "orphans"): Promise<string[] | string[][]>;
 }
 
+// AFC-10 (flow 234, phase 2, frozen AC3): "an unknown target differs from
+// indexed/no edges." Before this, `affected()` for a target the graph never
+// heard of resolved (via `target.ts`'s `resolveGraphTarget`, by contract:
+// "Returns the normalized target unchanged when nothing matches") to the
+// exact same `{dependencies: [], dependents: [], ranked: []}` shape as a
+// target the graph DID index but legitimately has no edges for — a failure
+// rendered as an empty success, the same defect class phase 1 closed at
+// eight other sites. `target.ts`/`affected.ts` are owned by a concurrent
+// agent this task must not edit, so the distinguishing check lives here: the
+// facade already loads the graph, so it can cheaply confirm the RESOLVED
+// target is a real node before handing back a result callers would
+// otherwise read as a legitimate (if boring) answer.
+export class UnknownGraphTargetError extends Error {
+  constructor(public readonly target: string) {
+    super(
+      `gdgraph: "${target}" is not a node in the built graph (never indexed, or the ` +
+        `path/symbol does not exist) — this is not the same as an indexed target with ` +
+        `zero edges. Run \`keryx gdgraph build\` if the file is new, or double-check the path.`,
+    );
+    this.name = "UnknownGraphTargetError";
+  }
+}
+
 export function createGdgraphService(): GdgraphService {
   return {
     async build(cwd) {
@@ -34,7 +57,16 @@ export function createGdgraphService(): GdgraphService {
       const config = await loadGdgraphConfig(cwd);
       const graph = await loadGraph(cwd);
       const depth = options.depth ?? config.affected.defaultDepth;
-      return computeAffected(graph, target, { ...options, depth });
+      const result = computeAffected(graph, target, { ...options, depth });
+      // `result.target` is the RESOLVED target (exact/suffix match), or —
+      // per target.ts's own contract — the normalized input unchanged when
+      // nothing matched. Membership in the loaded node set is exactly the
+      // signal that distinguishes the two.
+      const isKnownNode = graph.nodes.some((node) => node.path === result.target);
+      if (!isKnownNode) {
+        throw new UnknownGraphTargetError(target);
+      }
+      return result;
     },
 
     async repomap(cwd, options = {}) {

package/src/gdgraph/staleness.test.ts

@@ -0,0 +1,208 @@
+// AFC-10 (flow 234, phase 2): the graph "staleness" signal must actually track
+// the five triggers the frozen AC3 names — new commit, untracked, delete,
+// rename, config change — and a git failure must never collapse into "fresh".
+//
+// Before this task, `graphMaybeStale` compared `.git/HEAD`'s own mtime to
+// `nodes.jsonl`'s. That misses every trigger here: `.git/HEAD` is a symbolic
+// ref ("ref: refs/heads/<branch>") whose CONTENT (and often mtime) does not
+// change on an ordinary commit to the current branch, and it never reflects
+// untracked/deleted/renamed working-tree state or a config-file edit at all.
+// These tests build a real git fixture per trigger (never the project repo
+// itself) and assert against `checkGraphStaleness`'s structured result.
+
+import { execFileSync } from "node:child_process";
+import { mkdir, mkdtemp, rm, utimes, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { checkGraphStaleness, graphMaybeStale } from "./staleness";
+import { recordProvenance } from "../sync/provenance";
+
+let root: string;
+
+function git(cwd: string, args: string[]): void {
+  execFileSync("git", args, { cwd, stdio: "ignore" });
+}
+
+/**
+ * A minimal built-graph fixture: a real git repo with one committed source
+ * file, a `nodes.jsonl` "graph storage" file, and recorded build provenance
+ * pointing at the current HEAD — i.e. the state right after a clean
+ * `keryx gdgraph build` with nothing having moved since.
+ */
+async function makeBuiltFixture(): Promise<string> {
+  const dir = await mkdtemp(path.join(tmpdir(), "keryx-staleness-"));
+  git(dir, ["init", "-q"]);
+  git(dir, ["config", "user.email", "test@test.com"]);
+  git(dir, ["config", "user.name", "test"]);
+  await mkdir(path.join(dir, "src"), { recursive: true });
+  await mkdir(path.join(dir, ".metaproject", "data", "gdgraph", "storage"), { recursive: true });
+  await writeFile(path.join(dir, "src", "a.ts"), "export const a = 1;\n");
+  await writeFile(
+    path.join(dir, ".metaproject", "data", "gdgraph", "storage", "nodes.jsonl"),
+    '{"id":"src/a.ts","kind":"file","path":"src/a.ts","language":"typescript"}\n',
+  );
+  git(dir, ["add", "-A"]);
+  git(dir, ["commit", "-q", "-m", "initial build fixture"]);
+  // `recordProvenance` reads `git rev-parse HEAD`, which fails with zero
+  // commits — it must run AFTER the first commit exists, or it silently
+  // no-ops (by design: "no-op outside a git repo", which a HEAD-less repo
+  // with no commits yet also satisfies). It is deliberately left UNCOMMITTED
+  // here, matching the real project's own state (`.provenance.json` sits
+  // modified/untracked in the working tree right after every build) — the
+  // staleness check must treat that as normal build residue, not a trigger.
+  await recordProvenance(dir, "gdgraph", new Date().toISOString());
+  // Ensure nodes.jsonl's mtime is not accidentally newer than a config file
+  // written a moment later in the same test (mtime resolution on some
+  // filesystems is coarse) by nudging it slightly into the past.
+  const past = new Date(Date.now() - 5000);
+  await utimes(path.join(dir, ".metaproject", "data", "gdgraph", "storage", "nodes.jsonl"), past, past);
+  return dir;
+}
+
+beforeEach(async () => {
+  root = await makeBuiltFixture();
+});
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true });
+});
+
+test("AFC-10 control — a clean tree right after build reports fresh", async () => {
+  const result = await checkGraphStaleness(root);
+  expect(result.status).toBe("fresh");
+  expect(await graphMaybeStale(root)).toBe(false);
+});
+
+test("AFC-10 trigger 1/5 — a new commit since the build invalidates the snapshot", async () => {
+  await writeFile(path.join(root, "src", "b.ts"), "export const b = 1;\n");
+  git(root, ["add", "-A"]);
+  git(root, ["commit", "-q", "-m", "a new commit after the graph was built"]);
+
+  const result = await checkGraphStaleness(root);
+  expect(result.status).not.toBe("fresh");
+  expect(await graphMaybeStale(root)).toBe(true);
+});
+
+test("AFC-10 trigger 2/5 — an untracked file invalidates the snapshot", async () => {
+  await writeFile(path.join(root, "src", "untracked.ts"), "export const u = 1;\n");
+
+  const result = await checkGraphStaleness(root);
+  expect(result.status).not.toBe("fresh");
+  expect(await graphMaybeStale(root)).toBe(true);
+});
+
+test("AFC-10 trigger 3/5 — a deleted tracked file invalidates the snapshot", async () => {
+  await rm(path.join(root, "src", "a.ts"));
+
+  const result = await checkGraphStaleness(root);
+  expect(result.status).not.toBe("fresh");
+  expect(await graphMaybeStale(root)).toBe(true);
+});
+
+test("AFC-10 trigger 4/5 — a rename invalidates the snapshot even though file count and content are unchanged", async () => {
+  // The subtle case: `git mv` keeps the file count and byte content identical
+  // to the fixture's committed state — only the path moved.
+  git(root, ["mv", "src/a.ts", "src/a-renamed.ts"]);
+
+  const result = await checkGraphStaleness(root);
+  expect(result.status).not.toBe("fresh");
+  expect(await graphMaybeStale(root)).toBe(true);
+});
+
+test("AFC-10 trigger 5/5 — a gdgraph.config.json change invalidates the snapshot", async () => {
+  await writeFile(
+    path.join(root, ".metaproject", "gdgraph.config.json"),
+    JSON.stringify({ affected: { defaultDepth: 2 } }) + "\n",
+  );
+
+  const result = await checkGraphStaleness(root);
+  expect(result.status).not.toBe("fresh");
+  expect(await graphMaybeStale(root)).toBe(true);
+});
+
+test("AFC-10 group 3 — a git failure is reported as unknown, never as fresh", async () => {
+  // Delete the .git directory entirely so every git invocation the check
+  // makes fails (spawn succeeds, git exits non-zero / "not a git repository").
+  await rm(path.join(root, ".git"), { recursive: true, force: true });
+
+  const result = await checkGraphStaleness(root);
+  expect(result.status).toBe("unknown");
+  expect(result.reasons.length).toBeGreaterThan(0);
+  // The boolean back-compat wrapper must still never read as "fresh" (false)
+  // on a git failure — "unknown" collapses to "treat as maybe-stale", not to
+  // the safe-looking "false" the old mtime-diff check silently returned.
+  expect(await graphMaybeStale(root)).toBe(true);
+});
+
+test("AFC-10 — graph never built at all is reported as stale (not fresh), not a git failure", async () => {
+  await rm(path.join(root, ".metaproject", "data", "gdgraph", "storage", "nodes.jsonl"));
+
+  const result = await checkGraphStaleness(root);
+  expect(result.status).toBe("stale");
+  expect(await graphMaybeStale(root)).toBe(true);
+});
+
+// ---------------------------------------------------------------------------
+// T19 finding 3 (flow 234 review) — `git status --porcelain` prints paths
+// relative to the REPOSITORY ROOT, not to the directory git was invoked in.
+// The `.metaproject/` exclusion in `categorizeStatusLines` compared a bare
+// `.metaproject/` prefix against those repo-root-relative paths, which only
+// ever matches when the project root IS the git root. In a monorepo where the
+// project root sits below the git root, the prefix never matches, so the
+// graph's own build residue (`.provenance.json`, `artifacts/*` — expected to
+// sit modified/untracked right after every build) reads as a real untracked
+// file and the graph reports stale immediately after every clean build.
+// ---------------------------------------------------------------------------
+
+test("AFC-10 / T19 finding 3 — at the git root, the .metaproject exclusion behaves exactly as before", async () => {
+  // `root` (from `makeBuiltFixture`) already IS the git root — this is the
+  // control case the fix must not change. `--show-prefix` there resolves to
+  // "" and the fix must produce the identical "fresh" result as pre-fix.
+  const result = await checkGraphStaleness(root);
+  expect(result.status).toBe("fresh");
+});
+
+test("T19 finding 3 — a project root below the git root still excludes its own .metaproject build residue", async () => {
+  const gitRoot = await mkdtemp(path.join(tmpdir(), "keryx-staleness-monorepo-"));
+  try {
+    git(gitRoot, ["init", "-q"]);
+    git(gitRoot, ["config", "user.email", "test@test.com"]);
+    git(gitRoot, ["config", "user.name", "test"]);
+
+    const projectDir = path.join(gitRoot, "packages", "proj");
+    await mkdir(path.join(projectDir, "src"), { recursive: true });
+    await mkdir(path.join(projectDir, ".metaproject", "data", "gdgraph", "storage"), { recursive: true });
+    await writeFile(path.join(projectDir, "src", "a.ts"), "export const a = 1;\n");
+    await writeFile(
+      path.join(projectDir, ".metaproject", "data", "gdgraph", "storage", "nodes.jsonl"),
+      '{"id":"src/a.ts","kind":"file","path":"src/a.ts","language":"typescript"}\n',
+    );
+    git(gitRoot, ["add", "-A"]);
+    git(gitRoot, ["commit", "-q", "-m", "initial monorepo build fixture"]);
+
+    // Mirrors `makeBuiltFixture`: `recordProvenance` leaves `.provenance.json`
+    // UNCOMMITTED, exactly like a real `keryx gdgraph build` does — this is
+    // the graph's own bookkeeping the exclusion exists to skip, and (per the
+    // reviewer's repro) the ONLY dirty entry in the working tree here.
+    await recordProvenance(projectDir, "gdgraph", new Date().toISOString());
+    const past = new Date(Date.now() - 5000);
+    await utimes(
+      path.join(projectDir, ".metaproject", "data", "gdgraph", "storage", "nodes.jsonl"),
+      past,
+      past,
+    );
+
+    const result = await checkGraphStaleness(projectDir);
+    // Before the fix: `git status --porcelain` (run with cwd=projectDir)
+    // prints "packages/proj/.metaproject/data/gdgraph/.provenance.json",
+    // which does not start with the bare ".metaproject/" prefix the old
+    // check compared against — so it read as a real untracked file and this
+    // was "stale" on a repo with nothing but the graph's own residue dirty.
+    expect(result.status).toBe("fresh");
+    expect(result.reasons).toEqual([]);
+    expect(await graphMaybeStale(projectDir)).toBe(false);
+  } finally {
+    await rm(gitRoot, { recursive: true, force: true });
+  }
+});

package/src/gdgraph/staleness.ts

@@ -1,20 +1,202 @@
 import { stat } from "node:fs/promises";
 import path from "node:path";
+import { gitCmd, gitHead, readProvenance } from "../sync/provenance";
 
-// Cheap, low-noise graph-staleness signal: the graph is "maybe stale" when the
-// repo's `.git/HEAD` (which changes on commit / branch switch) is newer than the
-// built graph storage. Unlike "uncommitted changes", this does NOT fire on every
-// working-tree edit during active development — only after the repo state moved
-// since the last build. Best-effort: any error ⇒ not stale (never warns wrongly).
-export async function graphMaybeStale(cwd: string): Promise<boolean> {
-  const nodes = path.join(cwd, ".metaproject", "data", "gdgraph", "storage", "nodes.jsonl");
-  const head = path.join(cwd, ".git", "HEAD");
-  try {
-    const [nodesStat, headStat] = await Promise.all([stat(nodes), stat(head)]);
-    return headStat.mtimeMs > nodesStat.mtimeMs;
-  } catch {
-    return false;
+// AFC-10 (flow 234, phase 2, frozen AC3): "a new commit, untracked, delete,
+// rename and config change invalidate the snapshot; an unknown target differs
+// from indexed/no-edges; a git error never becomes fresh."
+//
+// The PREVIOUS implementation of this module compared `.git/HEAD`'s mtime to
+// the built graph's `nodes.jsonl` mtime. That is broken for every trigger AC3
+// names: `.git/HEAD` is a symbolic ref ("ref: refs/heads/<branch>") whose
+// CONTENT does not change on an ordinary commit to the current branch (only
+// the ref file it points at does), so its mtime frequently does not advance
+// either — measured directly against a real fixture in `staleness.test.ts`,
+// a fresh commit left the old check reporting "not stale". It also never
+// looked at working-tree status at all, so an untracked file, a deleted
+// file, or a rename (which leaves file COUNT and CONTENT unchanged — the
+// subtle case) were invisible to it. And on any error it returned `false`
+// ("not stale"), i.e. a git failure silently read as fresh.
+//
+// This version checks each trigger against real signals:
+//   - new commit:            recorded build provenance's commit vs current
+//                             `git rev-parse HEAD` (falls back to
+//                             `.git/logs/HEAD`'s mtime — which DOES advance
+//                             on every commit/checkout/branch-switch, unlike
+//                             `.git/HEAD`'s own — when no provenance was
+//                             recorded for this build).
+//   - untracked/delete/rename: `git status --porcelain=v1`, categorized by
+//                             status letter. A plain in-place content edit
+//                             (` M`/`M `) is deliberately NOT a trigger here —
+//                             the module contract (`modules/gdgraph.md`,
+//                             "Freshness & Refresh") only promises the
+//                             file-level graph goes stale when the file SET
+//                             moves; an edit with an unchanged import set
+//                             leaves the file-level graph correct.
+//   - config change:          `.metaproject/gdgraph.config.json`'s mtime vs
+//                             `nodes.jsonl`'s. No separate baseline write is
+//                             needed for this: the config file only *has* a
+//                             newer mtime than the graph when someone touched
+//                             it after the build ran.
+//   - git failure:            ANY git invocation here failing (spawn error,
+//                             non-zero exit, e.g. not a git repo) short-
+//                             circuits the result to `status: "unknown"` —
+//                             it is never allowed to fall through to "fresh".
+export type StalenessStatus = "fresh" | "stale" | "unknown";
+
+export interface StalenessCheck {
+  status: StalenessStatus;
+  // Human-readable reasons, one per trigger/failure that fired. Empty only
+  // when `status === "fresh"`.
+  reasons: string[];
+}
+
+function nodesJsonlPath(cwd: string): string {
+  return path.join(cwd, ".metaproject", "data", "gdgraph", "storage", "nodes.jsonl");
+}
+
+function gdgraphConfigPath(cwd: string): string {
+  return path.join(cwd, ".metaproject", "gdgraph.config.json");
+}
+
+// Categorize `git status --porcelain=v1` lines. Each line is exactly two
+// status characters (index status, worktree status) followed by a space and
+// the path (renames add " -> newPath"). A pure content modify (` M`/`M `/`MM`)
+// intentionally does not set any of these three — see the module doc above.
+//
+// Lines under `.metaproject/` are skipped entirely: that tree holds gdgraph's
+// OWN generated bookkeeping (`.provenance.json`, `artifacts/*`), which the
+// module contract says is expected to sit modified/untracked in the working
+// tree right after every build ("a rebuild leaves those files modified after
+// the commit") — that is normal build residue, not evidence the SOURCE tree
+// moved, and treating it as a trigger would make every build immediately
+// report itself as stale. The config file is checked separately, by mtime.
+//
+// T19 finding 3 (flow 234 review): `git status --porcelain` paths are always
+// relative to the REPOSITORY ROOT, not to the directory git was invoked in
+// (`cwd` here, which is the *project* root and may sit below the git root in
+// a monorepo). A bare ".metaproject/" prefix only ever matches when the
+// project root IS the git root; `rootPrefix` (from `git rev-parse
+// --show-prefix`, empty at the git root) is prepended so the same exclusion
+// matches at both.
+function categorizeStatusLines(
+  porcelain: string,
+  rootPrefix: string,
+): { added: boolean; deleted: boolean; renamed: boolean } {
+  const lines = porcelain.split("\n").filter((line) => line.length >= 2);
+  const metaprojectPrefix = `${rootPrefix}.metaproject/`;
+  let added = false;
+  let deleted = false;
+  let renamed = false;
+  for (const line of lines) {
+    const indexStatus = line[0];
+    const worktreeStatus = line[1];
+    const rawPath = line.slice(3);
+    // For a rename, porcelain prints "old -> new"; check the side(s) that
+    // matter for the metaproject exclusion (either is enough to skip a pure
+    // internal-bookkeeping rename, which does not occur in practice anyway).
+    const isMetaprojectPath = rawPath
+      .split(" -> ")
+      .some((candidate) => candidate.replace(/^"|"$/g, "").startsWith(metaprojectPrefix));
+    if (isMetaprojectPath) {
+      continue;
+    }
+    if (indexStatus === "?" || worktreeStatus === "?" || indexStatus === "A") {
+      added = true;
+    }
+    if (indexStatus === "D" || worktreeStatus === "D") {
+      deleted = true;
+    }
+    if (indexStatus === "R" || worktreeStatus === "R") {
+      renamed = true;
+    }
+  }
+  return { added, deleted, renamed };
+}
+
+/**
+ * The structured staleness check (AFC-10). Never throws — a git failure is
+ * reported as `status: "unknown"` with a reason, not thrown and not "fresh".
+ */
+export async function checkGraphStaleness(cwd: string): Promise<StalenessCheck> {
+  const nodesStat = await stat(nodesJsonlPath(cwd)).catch(() => null);
+  if (!nodesStat) {
+    return { status: "stale", reasons: ["graph has not been built yet (no nodes.jsonl)"] };
   }
+
+  const reasons: string[] = [];
+  let gitFailed = false;
+
+  // --- new commit -----------------------------------------------------------
+  const head = await gitHead(cwd);
+  if (head === null) {
+    gitFailed = true;
+    reasons.push("git rev-parse HEAD failed (not a git repository, or git is unavailable)");
+  } else {
+    const provenance = await readProvenance(cwd, "gdgraph");
+    if (provenance) {
+      if (provenance.commit !== head.commit) {
+        reasons.push(
+          `HEAD moved since the graph was built (built at ${provenance.commit.slice(0, 12)}, now ${head.commit.slice(0, 12)})`,
+        );
+      }
+    } else {
+      // No recorded build provenance for this graph. Fall back to the
+      // reflog's mtime: unlike `.git/HEAD` (a symbolic ref whose content is
+      // usually just "ref: refs/heads/<branch>" and does not change on an
+      // ordinary commit), `.git/logs/HEAD` gets a new entry — and therefore a
+      // fresh mtime — on every commit, checkout, and branch switch.
+      const logsHeadStat = await stat(path.join(cwd, ".git", "logs", "HEAD")).catch(() => null);
+      if (logsHeadStat && logsHeadStat.mtimeMs > nodesStat.mtimeMs) {
+        reasons.push(
+          "repo HEAD moved since the graph was built (no build provenance recorded; inferred from .git/logs/HEAD)",
+        );
+      }
+    }
+  }
+
+  // --- untracked / deleted / renamed ----------------------------------------
+  const porcelain = await gitCmd(cwd, ["status", "--porcelain=v1"]);
+  if (porcelain === null) {
+    gitFailed = true;
+    reasons.push("git status failed");
+  } else {
+    // T19 finding 3: `--show-prefix` is the project root's path relative to
+    // the git root (empty string AT the git root, "packages/proj/" style
+    // below it) — exactly the prefix `git status --porcelain`'s repo-root-
+    // relative paths need for the `.metaproject/` exclusion to match
+    // regardless of where the project root sits. A failed/non-git lookup
+    // (already caught above by the HEAD/status checks) falls back to "",
+    // preserving today's at-the-root behavior rather than under-excluding.
+    const rootPrefix = (await gitCmd(cwd, ["rev-parse", "--show-prefix"])) ?? "";
+    const { added, deleted, renamed } = categorizeStatusLines(porcelain, rootPrefix);
+    if (added) reasons.push("an untracked or newly added file exists in the working tree");
+    if (deleted) reasons.push("a tracked file was deleted in the working tree");
+    if (renamed) reasons.push("a file was renamed (staged) in the working tree");
+  }
+
+  // --- config changed ---------------------------------------------------------
+  const configStat = await stat(gdgraphConfigPath(cwd)).catch(() => null);
+  if (configStat && configStat.mtimeMs > nodesStat.mtimeMs) {
+    reasons.push("gdgraph.config.json changed since the graph was built");
+  }
+
+  if (gitFailed) {
+    // A git failure is reported as its own status — never silently
+    // downgraded to "fresh", and never conflated with a confirmed "stale"
+    // either, since we could not fully verify either way.
+    return { status: "unknown", reasons };
+  }
+  return reasons.length > 0 ? { status: "stale", reasons } : { status: "fresh", reasons: [] };
+}
+
+// Back-compat boolean surface for existing callers (`commands/gdgraph.ts`,
+// `wiki/staleness.ts`): "not demonstrably fresh" -> true. `"stale"` and
+// `"unknown"` both map to `true` so a git failure can never read as `false`
+// ("fresh") the way the old mtime-diff implementation did.
+export async function graphMaybeStale(cwd: string): Promise<boolean> {
+  const result = await checkGraphStaleness(cwd);
+  return result.status !== "fresh";
 }
 
 export const STALE_NOTE = "note: repo moved since the last graph build — `keryx gdgraph build` to refresh.";

package/src/gdgraph/symbols-capability.test.ts

@@ -1,5 +1,13 @@
 import { expect, test } from "bun:test";
-import { isTreesitterEnabled, setTreesitterEnabled, TREESITTER_CAPABILITY } from "./symbols-capability";
+import {
+  isTreesitterEnabled,
+  requireSymbols,
+  setTreesitterEnabled,
+  SymbolsUnavailableError,
+  TREESITTER_CAPABILITY,
+  type SymbolsLayerCarrier,
+} from "./symbols-capability";
+import type { GrammarDiagnosis } from "./treesitter/adapter";
 
 test("enable adds the capability entry to an empty manifest", () => {
   const next = setTreesitterEnabled({}, true);
@@ -39,3 +47,92 @@ test("preserves other gdgraph capabilities and other modules", () => {
   expect(next.modules.security).toEqual({ enabled: true });
   expect(next.schemaVersion).toBe(1);
 });
+
+// --- AFC-13 / AC5 requirement 2: requireSymbols gives a typed, actionable
+// error — never undefined, never an empty result, never a generic Error. ---
+
+test("AC5.req2 — requireSymbols returns graph.symbols when the symbol layer is present (including an empty array — the layer RAN, it just found nothing)", () => {
+  const withSymbols = { symbols: [{ id: "a" }] };
+  expect(requireSymbols(withSymbols)).toEqual(withSymbols.symbols);
+
+  const ranButEmpty = { symbols: [] };
+  expect(requireSymbols(ranButEmpty)).toEqual([]);
+});
+
+test("AC5.req2 — requireSymbols throws SymbolsUnavailableError (not undefined, not an empty result, not a generic Error) when the symbol layer never ran", () => {
+  // A `GraphData`-shaped object with no `symbols` key — exactly what the
+  // graph looks like when the symbol layer never ran. The cast (rather than a
+  // bare literal) is only to satisfy TS's weak-object-literal check, which
+  // otherwise flags "no properties in common" for a fresh literal compared
+  // against a type with a single optional property; a real `GraphData` value
+  // (a named type, not a fresh literal) never triggers this.
+  const graphWithNoLayer = { nodes: [], edges: [] } as unknown as SymbolsLayerCarrier;
+  expect(() => requireSymbols(graphWithNoLayer)).toThrow(SymbolsUnavailableError);
+
+  let caught: unknown;
+  try {
+    requireSymbols(graphWithNoLayer);
+  } catch (err) {
+    caught = err;
+  }
+  expect(caught).toBeInstanceOf(SymbolsUnavailableError);
+  expect(caught).toBeInstanceOf(Error);
+  const typed = caught as SymbolsUnavailableError;
+  // Typed and actionable: a stable `code`, a non-empty `remedy`, a non-empty
+  // `message` — not a bare string thrown, not `err.message === ""`.
+  expect(typed.code).toBe("no-symbol-layer");
+  expect(typeof typed.remedy).toBe("string");
+  expect(typed.remedy.length).toBeGreaterThan(0);
+  expect(typed.message.length).toBeGreaterThan(0);
+});
+
+// --- AFC-13 / AC5 requirement 3: missing vs incompatible must be
+// distinguishable, not collapsed into one outcome. ---
+
+test("AC5.req3 — requireSymbols reports grammar-missing when diagnoses say the grammar never resolved", () => {
+  const diagnoses: GrammarDiagnosis[] = [
+    { language: "typescript", status: "missing", reason: 'grammar asset "tree-sitter-typescript" is not resolved' },
+  ];
+  let caught: SymbolsUnavailableError | undefined;
+  try {
+    requireSymbols({}, diagnoses);
+  } catch (err) {
+    caught = err as SymbolsUnavailableError;
+  }
+  expect(caught?.code).toBe("grammar-missing");
+  expect(caught?.message).toContain("typescript");
+});
+
+test("AC5.req3 — requireSymbols reports grammar-incompatible when diagnoses say the grammar resolved but failed to load (ABI mismatch), and this is a DIFFERENT code/message/remedy than grammar-missing", () => {
+  const incompatible: GrammarDiagnosis[] = [
+    {
+      language: "typescript",
+      status: "incompatible",
+      reason: 'grammar at "/cache/tree-sitter-typescript" failed to load (likely an ABI/version mismatch): Incompatible language version 13. Expected minimum 14',
+    },
+  ];
+  let caught: SymbolsUnavailableError | undefined;
+  try {
+    requireSymbols({}, incompatible);
+  } catch (err) {
+    caught = err as SymbolsUnavailableError;
+  }
+  expect(caught?.code).toBe("grammar-incompatible");
+  expect(caught?.message).toContain("incompatible");
+
+  // Same missing-grammar case as the previous test, compared directly here so
+  // the distinction is asserted in one place: two different real-world
+  // conditions must never collapse into the same code/message/remedy.
+  const missing: GrammarDiagnosis[] = [
+    { language: "typescript", status: "missing", reason: 'grammar asset "tree-sitter-typescript" is not resolved' },
+  ];
+  let missingCaught: SymbolsUnavailableError | undefined;
+  try {
+    requireSymbols({}, missing);
+  } catch (err) {
+    missingCaught = err as SymbolsUnavailableError;
+  }
+  expect(missingCaught?.code).not.toBe(caught?.code);
+  expect(missingCaught?.message).not.toBe(caught?.message);
+  expect(missingCaught?.remedy).not.toBe(caught?.remedy);
+});