@mrciphersmith/keryx 0.2.83 → 0.2.88

package/src/gdgraph/repomap.ts

@@ -9,6 +9,8 @@
 
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+import type { ContextOverflow } from "../ctx/assembly";
+import { computeAffected } from "./affected";
 import type { GdgraphConfig } from "./config";
 import { personalizedPageRank, type RankEdge } from "./pagerank";
 import type { GraphData, SymbolNode } from "./types";
@@ -17,6 +19,10 @@ export interface RepomapEntry {
   path: string;
   score: number;
   symbols: string[];
+  // AFC-12: true for a matched seed, or a direct (depth-1) consumer/test of a
+  // matched seed. A required entry is protected from budget/rank eviction —
+  // it is not merely another ranked candidate the tie-break can outvote.
+  required: boolean;
 }
 
 export interface RepomapOptions {
@@ -30,6 +36,17 @@ export interface RepomapResult {
   entries: RepomapEntry[];
   tokens: number;
   omitted: number;
+  // AFC-12: paths of OPTIONAL (non-required) entries dropped for budget —
+  // the visible-loss list, named rather than just counted.
+  omittedOptional: string[];
+  // True when omittedOptional is non-empty — an optional-entry loss occurred.
+  partial: boolean;
+  // Present only when the required set (seed + known consumers/tests) does
+  // not fit the budget as a whole. Mirrors `src/ctx/assembly.ts`'s
+  // `ContextOverflow` vocabulary (required-vs-optional, `context_overflow`,
+  // `requiredId`) rather than inventing a second one. When set, `entries` is
+  // empty: a truncated required set is never reported as an ordinary success.
+  overflow?: ContextOverflow;
 }
 
 // Local token estimator — the documented `chars-div-4` default (AC3.2). Kept
@@ -38,11 +55,44 @@ export function estimateTokens(text: string): number {
   return Math.ceil(text.length / 4);
 }
 
-// The stable omission marker (AC3.2). `count` varies; the shape is fixed.
+// The stable omission marker (AC3.2). `count` varies; the shape is fixed —
+// UNCHANGED from before AFC-12, so the hard token budget and the existing
+// pop-until-it-fits loop keep their original, tested convergence behavior
+// regardless of how many optional entries are omitted.
 function omissionMarker(count: number): string {
   return `\n… ${count} entries omitted …\n`;
 }
 
+// AFC-12 visible-loss hint: a SHORT, length-bounded (not proportional to how
+// many paths were dropped) pointer to the full `omittedOptional` list on the
+// result, plus how to continue. Appended best-effort, only if it still fits
+// the budget — it never forces additional entries to be popped. The full,
+// unbounded list of dropped optional paths always lives in the structured
+// `RepomapResult.omittedOptional` field, never only in this rendered text.
+function omissionHint(omittedOptional: readonly string[]): string {
+  const noun = omittedOptional.length === 1 ? "entry" : "entries";
+  return `${omittedOptional.length} optional ${noun} omitted for budget — see \`omittedOptional\`. Increase --budget or narrow --seed to include them.\n`;
+}
+
+// A required entry (seed / known consumer / test) that does not fit the
+// budget as a whole (AFC-12): "budget-exceeded, not success with a truncated
+// required set." No entries are rendered — a partial required set is never
+// presented as legitimate.
+function overflowContent(required: readonly RepomapEntry[], missing: RepomapEntry, budget: number): string {
+  const requiredList = required.map((entry) => `- ${entry.path}`).join("\n");
+  return [
+    HEADER.trimEnd(),
+    "",
+    `context_overflow: required entry "${missing.path}" does not fit within the ${budget}-token budget.`,
+    "",
+    "Required (seed + known consumers/tests):",
+    requiredList,
+    "",
+    "Increase --budget, or narrow --seed, and retry.",
+    "",
+  ].join("\n");
+}
+
 function repomapArtifactPath(cwd: string): string {
   return path.join(cwd, ".metaproject", "data", "gdgraph", "artifacts", "repomap.md");
 }
@@ -117,14 +167,36 @@ export function computeRepomap(
 
   // Rank file nodes (the stable, always-present layer).
   const fileNodes = graph.nodes.filter((node) => node.kind === "file").map((node) => node.path);
+  const fileNodeSet = new Set(fileNodes);
   const rankEdges = buildRankEdges(graph, config);
 
+  // Resolve seeds to real graph nodes. A seed matching no node is silently
+  // dropped from personalization here, unchanged from prior behavior —
+  // resolution diagnostics for an unmatched seed are a separate concern.
+  const matchedSeeds: string[] = [];
   const personalization = new Map<string, number>();
   for (const seed of options.seed ?? []) {
     const normalized = seed.replace(/^\.\//, "");
     const match = fileNodes.find((file) => file === normalized || file.endsWith(normalized));
     if (match) {
       personalization.set(match, (personalization.get(match) ?? 0) + 1);
+      matchedSeeds.push(match);
+    }
+  }
+
+  // AFC-12 required set: a seed is not merely another ranked candidate — the
+  // ranking must not be able to outvote an explicit request. A matched seed,
+  // plus every direct (depth-1) dependent the graph already knows about
+  // (consumers AND tests alike — a test is simply a file that imports the
+  // seed), is protected from budget/rank eviction. Reuses `computeAffected`'s
+  // existing reverse-dependent closure rather than re-deriving one.
+  const requiredSet = new Set<string>(matchedSeeds);
+  for (const seed of matchedSeeds) {
+    const affected = computeAffected(graph, seed, { depth: 1 });
+    for (const dependent of affected.dependents) {
+      if (fileNodeSet.has(dependent)) {
+        requiredSet.add(dependent);
+      }
     }
   }
 
@@ -135,16 +207,51 @@ export function computeRepomap(
     ...(personalization.size > 0 ? { personalization } : {}),
   });
 
-  const allEntries: RepomapEntry[] = ranked.map((node) => ({
-    path: node.id,
-    score: node.score,
-    symbols: topSymbols(graph, node.id, config.repomap.maxSymbolsPerFile),
-  }));
+  // AFC-12 zero-value ballast: an entry the personalized rank never reached
+  // (score exactly 0 — no organic centrality, no path from any seed) carries
+  // no information and must not fill the budget. A required entry is kept
+  // regardless of its score — required-ness, not score, decides survival,
+  // since a genuine consumer/test with no other inbound edges scores 0 too.
+  const allEntries: RepomapEntry[] = ranked
+    .filter((node) => node.score > 0 || requiredSet.has(node.id))
+    .map((node) => ({
+      path: node.id,
+      score: node.score,
+      symbols: topSymbols(graph, node.id, config.repomap.maxSymbolsPerFile),
+      required: requiredSet.has(node.id),
+    }));
+
+  const requiredEntries = allEntries.filter((entry) => entry.required);
+  const optionalEntries = allEntries.filter((entry) => !entry.required);
 
-  // Greedily fill within the budget, always leaving room for the marker.
   let out = HEADER;
   const rendered: RepomapEntry[] = [];
-  for (const entry of allEntries) {
+
+  // Required entries render first, and ALL of them, or none (AFC-12): "if
+  // the seed and its required constraints do not fit as a whole,
+  // budget-exceeded, not success with a truncated required set."
+  for (const entry of requiredEntries) {
+    const trial = out + renderEntryBlock(entry);
+    if (estimateTokens(trial) <= budget) {
+      out = trial;
+      rendered.push(entry);
+    } else {
+      return {
+        path: repomapArtifactPath("."),
+        content: overflowContent(requiredEntries, entry, budget),
+        entries: [],
+        tokens: 0,
+        omitted: allEntries.length,
+        omittedOptional: [],
+        partial: false,
+        overflow: { code: "context_overflow", requiredId: entry.path },
+      };
+    }
+  }
+
+  // Optional entries fill the remaining budget, greedily in rank order
+  // (unchanged semantics for the non-required pool).
+  for (const entry of optionalEntries) {
     const trial = out + renderEntryBlock(entry);
     if (estimateTokens(trial) <= budget) {
       out = trial;
@@ -154,18 +261,37 @@ export function computeRepomap(
     }
   }
 
-  let omitted = allEntries.length - rendered.length;
+  const renderedPaths = new Set(rendered.map((entry) => entry.path));
+  let omittedOptional = optionalEntries
+    .filter((entry) => !renderedPaths.has(entry.path))
+    .map((entry) => entry.path);
+  let omitted = omittedOptional.length;
+
   if (omitted > 0) {
-    // Ensure the final content (incl. marker) stays within budget; pop entries
-    // until the marker fits (AC3.2 hard bound).
-    while (rendered.length > 0 && estimateTokens(out + omissionMarker(omitted)) > budget) {
+    // Ensure the final content (incl. marker) stays within budget; pop only
+    // OPTIONAL entries until the marker fits (AC3.2 hard bound, UNCHANGED) —
+    // a required entry is never sacrificed to make room for the omission
+    // notice.
+    while (
+      rendered.length > 0 &&
+      !rendered[rendered.length - 1]!.required &&
+      estimateTokens(out + omissionMarker(omitted)) > budget
+    ) {
       const popped = rendered.pop();
       if (popped) {
         out = out.slice(0, out.length - renderEntryBlock(popped).length);
+        omittedOptional = [...omittedOptional, popped.path];
         omitted += 1;
       }
     }
     out += omissionMarker(omitted);
+
+    // Best-effort, length-bounded visible-loss hint (AFC-12) — appended only
+    // if it still fits; never forces another entry to be popped.
+    const withHint = out + omissionHint(omittedOptional);
+    if (estimateTokens(withHint) <= budget) {
+      out = withHint;
+    }
   }
 
   return {
@@ -174,6 +300,8 @@ export function computeRepomap(
     entries: rendered,
     tokens: estimateTokens(out),
     omitted,
+    omittedOptional,
+    partial: omittedOptional.length > 0,
   };
 }
 

package/src/gdgraph/staleness.ts

@@ -190,13 +190,26 @@ export async function checkGraphStaleness(cwd: string): Promise<StalenessCheck>
   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";
-}
-
+// Flow 237 T11 (F4): the boolean wrapper `graphMaybeStale` used to live here.
+// It mapped BOTH `"stale"` and `"unknown"` to `true`, which was safe for the
+// callers it had (nothing could read a git failure as "fresh") but lossy: the
+// difference between "the repo moved" and "we could not tell" — the whole
+// point of the tri-state, and the difference between STALE_NOTE and
+// UNKNOWN_NOTE below — did not survive the call. T6 moved the last two
+// production callers (`commands/gdgraph.ts`, `wiki/staleness.ts`) onto
+// `checkGraphStaleness`, leaving the wrapper with no caller but its own test:
+// a collapse sitting in the codebase waiting for the next caller to pick it
+// up by accident. There is no boolean surface any more. Callers that only
+// want a yes/no write `(await checkGraphStaleness(cwd)).status !== "fresh"`
+// at the call site, where the discarded distinction is visible in the diff.
 export const STALE_NOTE = "note: repo moved since the last graph build — `keryx gdgraph build` to refresh.";
+
+// Flow 237 T6 (AFC-28/AC-28, "a check that could not run is unknown rather
+// than passed"): a git failure means staleness genuinely could not be
+// determined — it is not evidence the repo moved. Printing `STALE_NOTE`
+// ("repo moved...") for this case asserted something the check never
+// established. Every live caller must print THIS note (with the tri-state's
+// own reasons) for `status: "unknown"`, and reserve `STALE_NOTE` for a
+// confirmed `status: "stale"`.
+export const UNKNOWN_NOTE =
+  "note: could not determine whether the graph is stale (see reasons below) — run `keryx gdgraph build` if unsure.";

package/src/gdgraph/symbol.ts

@@ -10,27 +10,64 @@ export interface SymbolRef {
   resolved: boolean;
 }
 
+/**
+ * Which of the three resolution tiers produced a candidate (AC6 / AFC-M04,
+ * flow 235: "объяснимые candidates").
+ *
+ * The tiers always existed inside `resolveSymbols` — exact, then
+ * case-insensitive, then substring — but the function returned bare
+ * `SymbolNode`s, so the tier that selected each one was computed and thrown
+ * away. Measured consequence: `keryx gdgraph symbol "wikiAsk"` listed three
+ * definitions with nothing to say which was a real name match and which merely
+ * contains the query as a substring. A caller reading that list cannot tell an
+ * answer from a coincidence.
+ */
+export type SymbolMatchTier = "exact-name" | "case-insensitive-name" | "name-contains-query";
+
+export interface SymbolCandidate {
+  symbol: SymbolNode;
+  tier: SymbolMatchTier;
+}
+
 export interface SymbolQueryResult {
   query: string;
   definitions: SymbolNode[];
+  /** The tier every definition came from, or `undefined` when nothing matched. */
+  matchTier?: SymbolMatchTier;
   callers: SymbolRef[];
   callees: SymbolRef[];
 }
 
 // Resolve a name to matching symbols: exact name, then case-insensitive, then
 // substring — stopping at the first tier that yields hits so precise names win.
-export function resolveSymbols(symbols: SymbolNode[], name: string, limit = 25): SymbolNode[] {
+// Each candidate carries the tier that selected it.
+export function resolveSymbolCandidates(
+  symbols: SymbolNode[],
+  name: string,
+  limit = 25,
+): SymbolCandidate[] {
   const q = name.trim();
   if (!q) return [];
   const lower = q.toLowerCase();
 
+  const tag = (matches: SymbolNode[], tier: SymbolMatchTier): SymbolCandidate[] =>
+    matches.slice(0, limit).map((symbol) => ({ symbol, tier }));
+
   const exact = symbols.filter((s) => s.name === q);
-  if (exact.length > 0) return exact.slice(0, limit);
+  if (exact.length > 0) return tag(exact, "exact-name");
 
   const ci = symbols.filter((s) => s.name.toLowerCase() === lower);
-  if (ci.length > 0) return ci.slice(0, limit);
+  if (ci.length > 0) return tag(ci, "case-insensitive-name");
 
-  return symbols.filter((s) => s.name.toLowerCase().includes(lower)).slice(0, limit);
+  return tag(
+    symbols.filter((s) => s.name.toLowerCase().includes(lower)),
+    "name-contains-query",
+  );
+}
+
+// The bare-node view, unchanged for every existing caller.
+export function resolveSymbols(symbols: SymbolNode[], name: string, limit = 25): SymbolNode[] {
+  return resolveSymbolCandidates(symbols, name, limit).map((candidate) => candidate.symbol);
 }
 
 function labelFor(token: string, byId: Map<string, SymbolNode>): SymbolRef {
@@ -107,7 +144,9 @@ export function transitiveCallers(
 export function querySymbol(graph: GraphData, name: string): SymbolQueryResult {
   const symbols = graph.symbols ?? [];
   const calls = graph.calls ?? [];
-  const definitions = resolveSymbols(symbols, name);
+  const candidates = resolveSymbolCandidates(symbols, name);
+  const definitions = candidates.map((candidate) => candidate.symbol);
+  const matchTier = candidates[0]?.tier;
   const ids = new Set(definitions.map((s) => s.id));
   const byId = new Map(symbols.map((s) => [s.id, s]));
 
@@ -119,5 +158,5 @@ export function querySymbol(graph: GraphData, name: string): SymbolQueryResult {
     callEdges.filter((c) => ids.has(c.from)).map((c) => labelFor(c.to, byId)),
   ).sort((a, b) => a.label.localeCompare(b.label));
 
-  return { query: name, definitions, callers, callees };
+  return { query: name, definitions, ...(matchTier ? { matchTier } : {}), callers, callees };
 }

package/src/gdgraph/treesitter/extract.ts

@@ -68,6 +68,151 @@ interface RawSymbol {
   node: SymbolNode;
 }
 
+// --- Built-in method surface -------------------------------------------------
+//
+// Both resolution passes below match a call to a project symbol BY NAME, using
+// only the last dotted segment of the call expression. That threw the receiver
+// away, so `SEMVER_RE.test(value)` — the RegExp method — was recorded as a call
+// to whichever project symbol happens to be named `test`. Measured on this
+// repository before the fix: 1,567 resolved call edges came from member
+// expressions and 873 of them (56%) named a built-in method, including 272
+// `.test` edges all pointing at `SearchController.test`
+// (src/harness/search/controller.ts:40), 254 `console.log`/`Math.log` edges and
+// 174 `Object.entries` edges. `keryx gdgraph symbol wikiAsk` listed
+// `test (src/harness/search/controller.ts:40)` among its callees for exactly
+// this reason: there is no such call.
+//
+// A member call is NOT noise in general — `service.wikiAsk(...)` is a real edge
+// worth keeping — so the fix is not "drop member calls". What a structural walk
+// cannot do is type the receiver: `x.get(k)` is `Map.prototype.get` or a project
+// `get`, and nothing in the syntax says which. The rule below is therefore about
+// OWNERSHIP of the name, not about the shape of the call:
+//
+//   * bare identifier call (`helper()`)          -> resolve by name (unchanged)
+//   * `this` / `self` / `super` receiver         -> resolve by name; the
+//                                                   receiver is the enclosing
+//                                                   object, so the method is
+//                                                   project-defined by
+//                                                   construction
+//   * any other receiver + a name owned by an
+//     ECMAScript intrinsic or `console`          -> DO NOT resolve
+//   * any other receiver + any other name        -> resolve by name (unchanged)
+//
+// A call we refuse to resolve is NOT dropped: it stays an `unresolved-call`
+// edge carrying the full source expression (`SEMVER_RE.test`), which
+// `querySymbol` renders through `SymbolRef.resolved:false` and
+// `src/commands/gdgraph.ts` prints as `SEMVER_RE.test  (unresolved)`. Silently
+// dropping it would make a real call vanish; resolving it makes a non-call look
+// real. Marking it unresolved is the honest third option, and it reuses the
+// marker the CLI already reads rather than adding a new one.
+//
+// The list is an EXPLICIT frozen set, not `Object.getOwnPropertyNames(...)` of
+// the live intrinsics: the graph is a checked-in artifact and must not shift
+// with the engine (Bun alone adds `console.screenshot`, `console.write`,
+// `Math.sumPrecise`, `Map.prototype.getOrInsert`). Scope is the ECMAScript
+// intrinsic surface plus `console`; host APIs (`stream.write`,
+// `emitter.on`) are deliberately out — see the residuals in the flow report.
+const BUILTIN_METHOD_NAMES: ReadonlySet<string> = new Set([
+  // Object (statics + Object.prototype)
+  "assign", "create", "defineProperties", "defineProperty", "entries", "freeze",
+  "fromEntries", "getOwnPropertyDescriptor", "getOwnPropertyDescriptors",
+  "getOwnPropertyNames", "getOwnPropertySymbols", "getPrototypeOf", "groupBy",
+  "hasOwn", "hasOwnProperty", "is", "isExtensible", "isFrozen", "isPrototypeOf",
+  "isSealed", "keys", "preventExtensions", "propertyIsEnumerable", "seal",
+  "setPrototypeOf", "toLocaleString", "toString", "valueOf", "values",
+  // Array (statics + Array.prototype)
+  "at", "concat", "copyWithin", "every", "fill", "filter", "find", "findIndex",
+  "findLast", "findLastIndex", "flat", "flatMap", "forEach", "from", "includes",
+  "indexOf", "isArray", "join", "lastIndexOf", "map", "of", "pop", "push",
+  "reduce", "reduceRight", "reverse", "shift", "slice", "some", "sort", "splice",
+  "toReversed", "toSorted", "toSpliced", "unshift", "with",
+  // String (statics + String.prototype)
+  "charAt", "charCodeAt", "codePointAt", "endsWith", "fromCharCode",
+  "fromCodePoint", "isWellFormed", "localeCompare", "match", "matchAll",
+  "normalize", "padEnd", "padStart", "raw", "repeat", "replace", "replaceAll",
+  "search", "split", "startsWith", "substr", "substring", "toLocaleLowerCase",
+  "toLocaleUpperCase", "toLowerCase", "toUpperCase", "toWellFormed", "trim",
+  "trimEnd", "trimStart",
+  // Number / Math
+  "abs", "acos", "acosh", "asin", "asinh", "atan", "atan2", "atanh", "cbrt",
+  "ceil", "clz32", "cos", "cosh", "exp", "expm1", "floor", "fround", "hypot",
+  "imul", "isFinite", "isInteger", "isNaN", "isSafeInteger", "log", "log10",
+  "log1p", "log2", "max", "min", "parseFloat", "parseInt", "pow", "random",
+  "round", "sign", "sin", "sinh", "sqrt", "tan", "tanh", "toExponential",
+  "toFixed", "toPrecision", "trunc",
+  // JSON
+  "parse", "stringify",
+  // Map / Set / WeakMap / WeakSet
+  "add", "clear", "delete", "difference", "get", "has", "intersection",
+  "isDisjointFrom", "isSubsetOf", "isSupersetOf", "set", "symmetricDifference",
+  "union",
+  // Promise
+  "all", "allSettled", "any", "catch", "finally", "race", "reject", "resolve",
+  "then", "withResolvers",
+  // RegExp
+  "compile", "exec", "test",
+  // Date (statics + the get*/set*/to* surface)
+  "getDate", "getDay", "getFullYear", "getHours", "getMilliseconds",
+  "getMinutes", "getMonth", "getSeconds", "getTime", "getTimezoneOffset",
+  "getUTCDate", "getUTCDay", "getUTCFullYear", "getUTCHours",
+  "getUTCMilliseconds", "getUTCMinutes", "getUTCMonth", "getUTCSeconds", "now",
+  "setDate", "setFullYear", "setHours", "setMilliseconds", "setMinutes",
+  "setMonth", "setSeconds", "setTime", "setUTCDate", "setUTCFullYear",
+  "setUTCHours", "setUTCMilliseconds", "setUTCMinutes", "setUTCMonth",
+  "setUTCSeconds", "toDateString", "toISOString", "toJSON",
+  "toLocaleDateString", "toLocaleTimeString", "toTimeString", "toUTCString",
+  "UTC",
+  // Function.prototype / Reflect
+  "apply", "bind", "call", "construct", "deleteProperty", "ownKeys",
+  // Symbol
+  "for", "keyFor",
+  // console
+  "assert", "count", "countReset", "debug", "dir", "dirxml", "error", "group",
+  "groupCollapsed", "groupEnd", "info", "table", "time", "timeEnd", "timeLog",
+  "trace", "warn",
+]);
+
+// Receivers that are the enclosing object itself: a method reached through one
+// of these is project-defined by construction, so the built-in guard above must
+// never apply to it (`this.emit(...)` stays a resolved edge).
+const SELF_RECEIVERS: ReadonlySet<string> = new Set(["this", "self", "super"]);
+
+interface CalleeShape {
+  /** Last dotted segment — the method/function name being invoked. */
+  name: string;
+  /** Everything before it, or `null` for a bare identifier call. */
+  receiver: string | null;
+}
+
+// Split a raw callee expression (`SEMVER_RE.test`, `this.emit`, `helper`,
+// `foo.bar(a, b)` from the Java/Python whole-node fallback) into receiver +
+// name, using the same "cut at the first `(`" normalization `lastSegment` has
+// always used.
+function calleeShape(callee: string): CalleeShape {
+  const withoutCall = callee.replace(/\(.*$/s, "").trim();
+  const dot = withoutCall.lastIndexOf(".");
+  if (dot < 0) {
+    return { name: withoutCall, receiver: null };
+  }
+  // `a?.b` / `a!.b` — the optional/non-null marker belongs to the receiver.
+  const receiver = withoutCall.slice(0, dot).trim().replace(/[?!]+$/, "");
+  return { name: withoutCall.slice(dot + 1).trim(), receiver };
+}
+
+// Whether this call expression may be matched to a project symbol by name.
+// See BUILTIN_METHOD_NAMES for the reasoning; `false` leaves the call as an
+// `unresolved-call` edge that still carries the full source expression.
+function isNameResolvableCallee(callee: string): boolean {
+  const { name, receiver } = calleeShape(callee);
+  if (!name) {
+    return false;
+  }
+  if (receiver === null || SELF_RECEIVERS.has(receiver)) {
+    return true;
+  }
+  return !BUILTIN_METHOD_NAMES.has(name);
+}
+
 // Extract the symbol layer from a parsed tree root. `filePath` is the owning
 // file path (matches a file GraphNode.path).
 export function extractSymbolLayer(root: TsNode, filePath: string, language: Language): SymbolLayer {
@@ -131,6 +276,8 @@ export function extractSymbolLayer(root: TsNode, filePath: string, language: Lan
   }));
 
   // Resolve CALL targets to same-file symbols by name; else unresolved-call.
+  // A call on a receiver we cannot type (`SEMVER_RE.test`) is never matched by
+  // name when the name belongs to a built-in — see BUILTIN_METHOD_NAMES.
   const nameToId = new Map<string, string>();
   for (const symbol of symbolNodes) {
     if (!nameToId.has(symbol.name)) {
@@ -139,7 +286,7 @@ export function extractSymbolLayer(root: TsNode, filePath: string, language: Lan
   }
   const resolvedCalls: CallEdge[] = calls.map((call, index) => {
     const calleeName = lastSegment(call.to);
-    const target = nameToId.get(calleeName);
+    const target = isNameResolvableCallee(call.to) ? nameToId.get(calleeName) : undefined;
     if (target) {
       return {
         id: `call:${call.from}->${target}:${index}`,
@@ -204,7 +351,10 @@ export function resolveCrossFileCalls(symbols: SymbolNode[], calls: CallEdge[]):
   const out: CallEdge[] = [];
   for (const call of calls) {
     let edge = call;
-    if (call.kind === "unresolved-call") {
+    // The same built-in guard the per-file pass applies: without it this pass
+    // is strictly WORSE, because a unique project `test` anywhere in the graph
+    // captures every `<regexp>.test(...)` in every file.
+    if (call.kind === "unresolved-call" && isNameResolvableCallee(call.to)) {
       const name = lastSegment(call.to);
       const target = nameCount.get(name) === 1 ? nameToId.get(name) : undefined;
       if (target && target !== call.from) {
@@ -359,9 +509,7 @@ function renderSignature(node: TsNode, kind: SymbolKind, container: string | nul
 }
 
 function lastSegment(callee: string): string {
-  const withoutCall = callee.replace(/\(.*$/s, "");
-  const parts = withoutCall.split(".");
-  return (parts[parts.length - 1] ?? withoutCall).trim();
+  return calleeShape(callee).name;
 }
 
 function firstLine(text: string): string {

package/src/gdgraph/wiki-layer.ts

@@ -18,6 +18,7 @@ import path from "node:path";
 import { collectPages } from "../wiki/collect";
 import { computeModuleKeyFiles } from "../wiki/collect";
 import { resolveDescribeSet } from "../wiki/describes";
+import { resolveWikiPageIdentity, type PageIdentity } from "../wiki/section-index";
 import type { DescribesEdge, FileFingerprint, GraphData, WikiLayer, WikiPageNode } from "./types";
 
 export const WIKI_PAGES_FILE = "wiki-pages.jsonl";
@@ -28,11 +29,41 @@ function storageDir(projectRoot: string): string {
   return path.join(projectRoot, ".metaproject", "data", "gdgraph", "storage");
 }
 
-/** Stable id for a page node. */
+/**
+ * Path-derived page id. **Not stable across a rename**, despite what this
+ * function's doc comment claimed for two phases.
+ *
+ * Measured on a real page of this repository's wiki (flow 235, T5), before any
+ * change: renaming `architecture/os-sandbox.md` to
+ * `architecture/operating-system-sandbox.md` with byte-identical content turned
+ * `wiki:architecture/os-sandbox.md` into
+ * `wiki:architecture/operating-system-sandbox.md`, and a DIFFERENT page written
+ * at the vacated path then answered to the old id — a stale reference resolving
+ * to whatever now occupies the position, with no diagnostic anywhere.
+ *
+ * Kept because it is the correct answer for a page that has never been given an
+ * identity, and because it is the id shape already written into
+ * `storage/wiki-pages.jsonl`. Use {@link wikiPageIdFor} when the page's content
+ * is available: it prefers the authored `keryx:page` marker, which does survive
+ * a rename.
+ */
 export function wikiPageId(relativePath: string): string {
   return `wiki:${relativePath}`;
 }
 
+/**
+ * The page's identity, preferring the authored marker over the path.
+ *
+ * This is the single resolver — `../wiki/section-index.ts`'s
+ * `resolveWikiPageIdentity` — rather than a second copy of the rule living in
+ * the graph layer. A page with a `keryx:page` marker keeps its id through a
+ * file rename; a page without one is still addressed by path, and the returned
+ * `stability` says so out loud instead of letting a caller assume otherwise.
+ */
+export function wikiPageIdFor(relativePath: string, content: string): PageIdentity {
+  return resolveWikiPageIdentity(relativePath, content);
+}
+
 export interface BuildWikiLayerInput {
   projectRoot: string;
   graph: GraphData;

package/src/gdskills/bundled/skills/core/reviewer-skill-creator/SKILL.md

@@ -17,6 +17,8 @@ triggers:
   - "make a reviewer from this profile"
   - "создай ревьюера"
   - "создай нового ревьюера на основании"
+  - "import vantage reviewers"
+  - "import overlay reviewers"
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
@@ -49,6 +51,31 @@ The parallel is the whole convention. A project reviewer is a project-skill whos
 finds it by that alone. Anyone who knows where bundled reviewers live knows where
 these go.
 
+## Bulk import of overlay reviewers
+
+When the overlays already exist as `review-vantage-*` skill packages (for
+example an overlay skill tree with `review-vantage-*` packages), do not recreate them one by one.
+
+```bash
+keryx skills import --from <overlay-home> --module review
+# alias: keryx review import --from <overlay-home>
+```
+
+That copies every `review-vantage-*` package into
+`.metaproject/project-skills/review/`, stamps Origin on each SKILL.md, and is
+the same discovery `review-orchestrator` uses. Generic copies of keryx
+reviewers (`review-logic`, `review-frontend`, …) are skipped on purpose —
+those would shadow the bundled engine.
+
+One overlay package:
+
+```bash
+keryx review import --from <overlay-home>/skills/review-vantage-frontend
+```
+
+Then `keryx review reviewers`. Until that list shows the names, they are not
+wired.
+
 ---
 
 ## Workflow
@@ -212,3 +239,5 @@ undocumented is drift that will be silently "fixed" by whoever refreshes next.
 | Change a reviewer keryx ships | NO | edit `src/gdskills/bundled/skills/review/` and open a PR |
 | Update a skill from review findings | NO | `entity-skill-learner`, `keryx skills learn` |
 | Decide which reviewers a round dispatches | NO | `review-orchestrator` |
+| Import a tree of overlay reviewers | YES — `keryx skills import --from <dir> --module review` (`keryx review import` alias) | — |
+| Import a non-review SKILL.md / GitHub URL | NO | `entity-skill-creator` / `keryx skills import` |

package/src/gdskills/bundled/skills/orchestration/code-verifier/SKILL.codex.md

@@ -68,7 +68,7 @@ Auto-detect the project stack and available verification tools.
 ```bash
 cd <codebase_path>
 
-if   [ -f bun.lockb ];         then PM=bun;    RUNNER="bun run"
+if   [ -f bun.lock ] || [ -f bun.lockb ]; then PM=bun;    RUNNER="bun run"
 elif [ -f pnpm-lock.yaml ];    then PM=pnpm;   RUNNER="pnpm run"
 elif [ -f yarn.lock ];         then PM=yarn;   RUNNER="yarn"
 elif [ -f package-lock.json ]; then PM=npm;    RUNNER="npm run"