@polycode-projects/seonix 0.1.0 → 0.2.0

package/src/ask.mjs

@@ -0,0 +1,762 @@
+// ask.mjs — a mechanical (zero-model-call) natural-language query engine over the
+// seonix graph. PLAN_MECHANICAL_CHAT.md (P0): a small, closed English grammar
+// compiles a free-text question into a graph traversal over the SAME classified
+// relation groups codegraph.mjs's other render functions read, then renders a
+// templated, citation-faithful answer. No embeddings, no fuzzy matching beyond
+// plain substring/component matching, no model calls — a miss is a stated blank,
+// never a guess (the extraction pipeline's "no wrong edge" ethos, held at the
+// query layer too).
+//
+// Four pure, independently-testable stages, orchestrated by ask():
+//   parseQuery (grammar)  ->  resolveObject (mechanical term resolution)  ->
+//   traverse (graph lookup)  ->  render (templates).
+//
+// §3.5/3.6 (2026-07-02, ELIZA/PARRY-style breadth): parseQuery normalizes the
+// raw text (contractions, g-drop, filler-strip), rewrites recognized negative-
+// rhetorical constructions to their affirmative form, then runs TWO INDEPENDENT
+// parsing STRATEGIES against the same normalized text — the original anchored-
+// template matcher (precise, fast, unweakened) and a keyword-spotting/
+// decomposition matcher (ELIZA's own mechanism: find the keyword, decompose
+// around it, tolerate reordering/casual phrasing) — and MERGES their results:
+// one strategy hit -> use it; both hit and agree -> use it (high confidence);
+// both hit and DISAGREE -> a genuine parse-level ambiguity, surfaced honestly;
+// neither hits -> the honest grammar miss. STRATEGIES is a plain array so a
+// third strategy could join the same way, not a hardcoded two-branch special
+// case.
+//
+// Where a parsed intent is temporal/churn-shaped (touched/since/cochange as a
+// FILTER over commits, not a structural edge), this engine does NOT re-implement
+// that — see PLAN_MECHANICAL_CHAT.md §2: matchQuery/nlToQuery (temporal.mjs) already
+// own that surface for the Chronograph browser; ask.mjs's own `touches`/`cochange`
+// verbs here answer "which modules touch/co-change with X" as ONE-HOP structural
+// edges (mgx:touchedByCommit / mgx:changeCoupledWith), which is a different (and
+// simpler) question than the browser's time-scrubbing view.
+
+import { relationKind, impactClosure } from "./codegraph.mjs";
+import {
+  VERB_TO_KIND, ENTITY_TO_TYPE, MODIFIER_TO_KIND,
+  CONTRACTIONS, G_DROP, FILLER_WORDS, CONTEXT_PRONOUNS, NEGATION_FRAMES,
+  META_MEANING_VERBS,
+} from "./ask-vocab.mjs";
+import { lookupByProseTokens } from "./prose.mjs";
+
+/** All edges of a classified relation kind, flattened across relation groups —
+ *  a local copy of codegraph.mjs's private edgesOfKind (kept local rather than
+ *  exported+imported to avoid coupling this file's commit boundary to concurrent
+ *  in-flight edits elsewhere in codegraph.mjs; both read the same relationKind
+ *  classification, so they cannot drift in meaning). */
+function edgesOfKind(graph, kind) {
+  const out = [];
+  for (const g of graph.relations) if (relationKind(g) === kind) out.push(...g.edges);
+  return out;
+}
+
+// ---- §3 vocabulary — single-sourced in ./ask-vocab.mjs; the grammar, the
+// rephrase-hint text, and the renderer's noun forms all derive from those
+// three tables, so they cannot drift. ----
+
+// Predicate kinds carrying a finer, symbol-grain sibling (module-coarse -> fn/method-precise).
+// "which functions call X" should read off callsSymbol (fn->fn), not the module-coarse "calls".
+const SYMBOL_GRAIN_SIBLING = { calls: "callsSymbol", touches: "touchesSymbol" };
+const FINE_ENTITY_TYPES = new Set(["Function", "Method", "Class", "Attribute", "GlobalVariable"]);
+
+const OVERFLOW_CAP = 12;
+
+const PLURAL_FORMS = {
+  Function: ["function", "functions"], Method: ["method", "methods"],
+  Class: ["class", "classes"], Module: ["module", "modules"],
+  Attribute: ["attribute", "attributes"], GlobalVariable: ["variable", "variables"],
+  Commit: ["commit", "commits"],
+};
+function nounFor(entityType, n) {
+  const [s, p] = PLURAL_FORMS[entityType] || ["result", "results"];
+  return n === 1 ? s : p;
+}
+
+// Every relation KIND token is already the correct 3rd-person-singular verb form
+// ("X imports Y", "X calls Y", "X touches Y") EXCEPT "cochange", the one kind whose
+// name is a bare noun/verb stem ("X cochange Y" is wrong; "X cochanges Y" is right) —
+// so the reverse-shape zero-hit template below reads off this table instead of
+// unconditionally appending "s" (which used to double-pluralize every other kind:
+// "callss", "importss", "touchess").
+const REVERSE_MISS_VERB = { cochange: "cochanges" };
+function verbFor(kind) {
+  return REVERSE_MISS_VERB[kind] || kind;
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// ---- §3.5 normalization — runs before EITHER parsing strategy sees the text ----
+
+/** contraction/informal-spelling table -> word-boundary regex, longest phrase
+ *  first (so "there's" doesn't get shadowed by a shorter overlapping entry). */
+const CONTRACTION_RE = new RegExp(
+  "\\b(" + Object.keys(CONTRACTIONS).sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b",
+  "gi",
+);
+
+/** Free-text -> normalized free-text: contractions expanded, g-dropped words
+ *  restored, filler/politeness words stripped. Idempotent and pure — the same
+ *  input always normalizes the same way, so both parsing strategies see
+ *  identical text and their outputs are directly comparable. Deliberately
+ *  does NOT force lowercase: object/subject terms (module names like
+ *  "myFile", class names like "Base") are meaningfully cased, and every
+ *  substitution below already matches case-insensitively (`i`/`gi` flags) —
+ *  forcing the whole string to lowercase would silently corrupt every parsed
+ *  term's case instead. */
+export function normalizeQuery(text) {
+  let q = String(text || "");
+  q = q.replace(CONTRACTION_RE, (m) => CONTRACTIONS[m.toLowerCase()]);
+  q = q.replace(G_DROP, "$1ing");
+  if (FILLER_WORDS.length) {
+    const fillerRe = new RegExp(
+      "\\b(" + [...FILLER_WORDS].sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b",
+      "gi",
+    );
+    q = q.replace(fillerRe, " ");
+  }
+  return q.replace(/\s+/g, " ").trim();
+}
+
+/** Recognized negative-rhetorical constructions, rewritten to the affirmative
+ *  form of the SAME question (§3.6) — a small pattern set, not a general
+ *  negation-scope parser. First matching frame wins; unmatched text passes
+ *  through unchanged. */
+export function applyNegationFrames(text) {
+  for (const frame of NEGATION_FRAMES) {
+    const m = text.match(frame.re);
+    if (m) return frame.to(m).replace(/\s+/g, " ").trim();
+  }
+  return text;
+}
+
+// ---- strategy 1: anchored templates — fixed precedence order; first fit wins,
+// never ambiguous at the template level (a question matching two shapes is a
+// design smell we test against). Unweakened from the original P0 grammar. ----
+
+const VERB_ALT = Object.keys(VERB_TO_KIND).sort((a, b) => b.length - a.length).map(escapeRegex).join("|");
+const ENTITY_ALT = Object.keys(ENTITY_TO_TYPE).sort((a, b) => b.length - a.length).map(escapeRegex).join("|");
+const MODIFIER_ALT = Object.keys(MODIFIER_TO_KIND).sort((a, b) => b.length - a.length).map(escapeRegex).join("|");
+const META_ALT = META_MEANING_VERBS.slice().sort((a, b) => b.length - a.length).map(escapeRegex).join("|");
+
+const TEMPLATES = [
+  // T1 ASK: "does X import Y" / "is X a subclass of Y" -> Yes/No. Tried FIRST: it starts with
+  // does/is/do, which the reverse/forward templates below never match (those start with
+  // which/what), so precedence between T1 and the rest is structural, not a tie-break guess.
+  {
+    name: "ask",
+    re: new RegExp(`^(?:does|do)\\s+(.+?)\\s+(${VERB_ALT})\\s+(.+?)\\??$`, "i"),
+    build: (m) => ({
+      shape: "ask", entityType: null, modifier: "direct",
+      kind: VERB_TO_KIND[m[2].toLowerCase()], subject: m[1].trim(), object: m[3].trim(),
+    }),
+  },
+  // T2 reverse: "which <entity> [<modifier>] <verb> <object>" — the operator's own example shape.
+  {
+    name: "reverse",
+    re: new RegExp(`^which\\s+(${ENTITY_ALT})\\s+(?:(${MODIFIER_ALT})\\s+)?(${VERB_ALT})\\s+(.+?)\\??$`, "i"),
+    build: (m) => ({
+      shape: "reverse",
+      entityType: ENTITY_TO_TYPE[m[1].toLowerCase()],
+      modifier: m[2] ? MODIFIER_TO_KIND[m[2].toLowerCase()] : "direct",
+      kind: VERB_TO_KIND[m[3].toLowerCase()],
+      object: m[4].trim(),
+    }),
+  },
+  // T3 forward: "what does <object> <verb>" — X is given, list its R-related things.
+  {
+    name: "forward",
+    re: new RegExp(`^what\\s+(?:does|do)\\s+(.+?)\\s+(${VERB_ALT})\\??$`, "i"),
+    build: (m) => ({
+      shape: "forward", entityType: null, modifier: "direct",
+      kind: VERB_TO_KIND[m[2].toLowerCase()], object: m[1].trim(),
+    }),
+  },
+  // T4 meta: "what does <term> mean" — a question about the GRAPH'S OWN VOCABULARY
+  // (a SchemaClass/SchemaPredicate label, e.g. "cochange", or a raw prop token, e.g.
+  // "mgx:callsSymbol"), not a graph traversal over code edges. Tried after T3: T3 also
+  // starts "what does/do", but T3 only fires when the tail is a relation VERB_ALT
+  // phrase ("import"/"calls"/…), which "mean"/"means"/etc never are (disjoint tables —
+  // ask-vocab.mjs's file comment explains why they're kept separate), so the two never
+  // actually compete for the same input.
+  {
+    name: "meta-mean",
+    re: new RegExp(`^what\\s+(?:does|do|is|are)\\s+(.+?)\\s+(?:${META_ALT})\\??$`, "i"),
+    build: (m) => ({ shape: "meta", entityType: null, modifier: "direct", kind: "meta", object: m[1].trim() }),
+  },
+  // T5 meta: "what is a/an <term>" — the OTHER worked phrasing ("what is a Commit").
+  // The indefinite article is REQUIRED (not optional): a bare "what is <anything>"
+  // would also swallow "what is the meaning of this codebase" (an existing, deliberately
+  // honest grammar-miss regression case — ask.test.mjs/ask-dual-strategy.test.mjs both
+  // assert it stays null), which never mentions "a"/"an" before its tail. Requiring the
+  // article keeps this template's reach to the one worked shape without reopening that.
+  {
+    name: "meta-whatis",
+    re: new RegExp(`^what\\s+(?:is|are)\\s+(?:an?)\\s+(.+?)\\??$`, "i"),
+    build: (m) => ({ shape: "meta", entityType: null, modifier: "direct", kind: "meta", object: m[1].trim() }),
+  },
+];
+
+/** Strategy 1: the original P0 anchored grammar, unmodified in behavior — the
+ *  whole (normalized) string must match one of TEMPLATES start-to-end. Pure. */
+function parseAnchored(text) {
+  for (const t of TEMPLATES) {
+    const m = text.match(t.re);
+    if (m) return t.build(m);
+  }
+  return null;
+}
+
+// ---- strategy 2: keyword-spotting/decomposition — ELIZA's own mechanism: find
+// the keyword(s) anywhere in the text, decompose around them, tolerate reordering
+// and casual phrasing. Position-independent (no `^...$` anchor), so it tolerates
+// "what calls this" / "who invokes this" / "something executes this, where from"
+// — real phrasings the anchored grammar's fixed shapes don't cover. ----
+
+const STOPWORDS = new Set([
+  "what", "who", "which", "where", "when", "why", "how",
+  "does", "do", "is", "are", "the", "a", "an", "of", "to", "from", "at", "in", "on",
+  "there", "something", "anything", "nothing", "one", "any",
+]);
+
+/** Find the longest phrase from `table`'s keys that appears as a contiguous
+ *  run of `words` (case already lowercased by the caller). Longest-match-first
+ *  (multi-word phrases before single words) so "co-changes with" isn't
+ *  shadowed by a shorter unrelated word. Returns {kind, start, end} (end
+ *  exclusive) or null. */
+function findPhrase(lcWords, table) {
+  const phrases = Object.keys(table).sort((a, b) => b.split(" ").length - a.split(" ").length);
+  for (const p of phrases) {
+    const pWords = p.split(" ");
+    for (let i = 0; i <= lcWords.length - pWords.length; i += 1) {
+      if (pWords.every((w, j) => lcWords[i + j] === w)) return { kind: table[p], start: i, end: i + pWords.length };
+    }
+  }
+  return null;
+}
+
+/** Strategy 2: scan (already-normalized) text for a verb keyword anywhere,
+ *  plus optional entity/modifier keywords anywhere, then split whatever's
+ *  left (after removing the matched spans + stopwords) into the words BEFORE
+ *  and AFTER the verb. Which side(s) are non-empty decides the shape —
+ *  mirrors the three anchored shapes but by decomposition instead of a fixed
+ *  template, so it tolerates reordering/casual phrasing the anchored regexes
+ *  don't: text on BOTH sides ("does X import Y") -> ask{subject:before,
+ *  object:after}; only AFTER the verb ("what calls this") -> reverse{object:
+ *  after}; only BEFORE it ("what does X import") -> forward{object:before}.
+ *  A lone context pronoun ("this"/"it"/"that"/"here") ending up as a resolved
+ *  term is left as plain text — resolveTermOrContext (traverse-time)
+ *  recognizes it against an optional contextId, so no separate flag is
+ *  needed here. A misparse here costs nothing beyond an honest object-miss
+ *  downstream (resolveObject never guesses). Pure. */
+function parseKeywordSpot(text) {
+  // Strip a trailing "?" (mirrors the anchored templates' own `\??$`) and turn commas into
+  // pauses/spaces — but NEVER strip a mid-word ".": object terms are routinely dotted file/module
+  // names ("a.py", "utils.mjs"), and the anchored strategy captures those raw, so keyword-spot
+  // must too or the two strategies would "disagree" over a period that was never part of the intent.
+  const words = text.replace(/\?+\s*$/, "").replace(/,/g, " ").split(/\s+/).filter(Boolean);
+  const lcWords = words.map((w) => w.toLowerCase());
+  const verbHit = findPhrase(lcWords, VERB_TO_KIND);
+  if (!verbHit) return null;
+  const entityHit = findPhrase(lcWords, ENTITY_TO_TYPE);
+  const modifierHit = findPhrase(lcWords, MODIFIER_TO_KIND);
+  const consumed = new Set();
+  const mark = (hit) => { if (hit) for (let i = hit.start; i < hit.end; i += 1) consumed.add(i); };
+  mark(verbHit); mark(entityHit); mark(modifierHit);
+  const sideText = (from, to) => words
+    .slice(from, to)
+    .filter((_, j) => !consumed.has(from + j) && !STOPWORDS.has(lcWords[from + j]))
+    .join(" ")
+    .trim();
+  const beforeText = sideText(0, verbHit.start);
+  const afterText = sideText(verbHit.end, words.length);
+  const kind = verbHit.kind;
+  const entityType = entityHit ? ENTITY_TO_TYPE[lcWords.slice(entityHit.start, entityHit.end).join(" ")] : null;
+  const modifier = modifierHit ? MODIFIER_TO_KIND[lcWords.slice(modifierHit.start, modifierHit.end).join(" ")] : "direct";
+
+  if (beforeText && afterText) return { shape: "ask", entityType: null, modifier: "direct", kind, subject: beforeText, object: afterText };
+  if (afterText) return { shape: "reverse", entityType, modifier, kind, object: afterText };
+  if (beforeText) return { shape: "forward", entityType: null, modifier: "direct", kind, object: beforeText };
+  return null;
+}
+
+// ---- strategy merge — run both, agree/disagree/single/neither (§ above). A
+// plain array + a merge step, so a third strategy plugs in the same way. ----
+
+const STRATEGIES = [
+  { name: "anchored", parse: parseAnchored },
+  { name: "keyword-spot", parse: parseKeywordSpot },
+];
+
+const cmpTerm = (s) => String(s || "").trim().toLowerCase().replace(/\s+/g, " ");
+
+/** Do two independently-produced parses mean the same graph query? Same
+ *  shape, same relation kind, and matching term(s) (both subject and object
+ *  for "ask"; just object otherwise) — anything less is a genuine
+ *  disagreement, not a near-miss to paper over. */
+function sameParse(p, q) {
+  if (p.shape !== q.shape || p.kind !== q.kind) return false;
+  if (p.shape === "ask") return cmpTerm(p.subject) === cmpTerm(q.subject) && cmpTerm(p.object) === cmpTerm(q.object);
+  return cmpTerm(p.object) === cmpTerm(q.object);
+}
+
+/** Compile a free-text question into {shape, kind, entityType, modifier,
+ *  object[, subject]}, or null if NEITHER strategy fits — an honest grammar
+ *  miss (§6.3), never a best-effort guess. When both strategies parse and
+ *  AGREE, returns that parse unchanged (no fallback ordering — either
+ *  strategy's own result is equally valid once they agree, per §above: "use
+ *  either"). When both parse but DISAGREE (different shape/kind/term),
+ *  returns {ambiguousParse: true, candidates: [...]} — a genuine "this could
+ *  mean more than one thing" case, distinct from resolveObject's later
+ *  object-resolution ambiguity. Pure. */
+export function parseQuery(query) {
+  const raw = String(query || "").trim().replace(/\s+/g, " ");
+  if (!raw) return null;
+  const text = applyNegationFrames(normalizeQuery(raw));
+  if (!text) return null;
+  const hits = STRATEGIES.map((s) => ({ name: s.name, parsed: s.parse(text) })).filter((r) => r.parsed);
+  if (hits.length === 0) return null;
+  if (hits.length === 1) return hits[0].parsed;
+  const [a, b] = hits;
+  if (sameParse(a.parsed, b.parsed)) return a.parsed;
+  return { ambiguousParse: true, candidates: hits.map((h) => h.parsed) };
+}
+
+/** The rephrase hint shown on a grammar miss — generated from the SAME tables the parser
+ *  uses, so it can never suggest a phrasing the grammar doesn't actually support (§6.3). */
+export function rephraseHint() {
+  return '"which <functions|classes|modules> <imports|calls|inherits from|tests|touched> <name>" or "what does <name> <import|call|inherit from>" or plainly "what calls this" (about a selected node) or "what does <term> mean"/"what is a <ClassName>" (about the graph\'s own vocabulary)';
+}
+
+// ---- §4 object-term resolution — mechanical, no embeddings, tiered, stop at first hit ----
+
+function componentSet(s) {
+  return new Set(String(s).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
+}
+
+/** Resolve a free-text object/subject term against the graph's individuals, in priority
+ *  order (§4, generalized beyond the module-coupling worked example to cover every verb
+ *  family's object grain — `inherits`/`calls` resolve against Class/Function names, not
+ *  just modules): (1) exact label/id match, (2) an `ext:` unresolved-target match (today
+ *  ext: targets are edge-endpoint STRINGS with no individual of their own — e.g. an
+ *  unimported inherits base, or any import target — so this tier returns a synthetic
+ *  {id:"ext:<name>", label:<name>, class:null} match rather than an `individuals` lookup;
+ *  see PLAN_MECHANICAL_CHAT.md §10 on why external `imports` targets land here rather
+ *  than tier 1/3 today), (3) boundary-aware substring/component match, (4) a prose-index
+ *  fallback (PLAN_PROSE_INDEX.md §6): the term, tokenized the same way as a docstring, is
+ *  looked up against `graph.proseIndex` via `lookupByProseTokens` — an exact WORD-level
+ *  overlap match against a symbol's decomposed-identifier or doc-comment tokens, never a
+ *  substring/fuzzy guess (the same "no wrong edge" standard as tiers 1-3, just over a
+ *  different token source: prose rather than the literal identifier). Only ever consulted
+ *  once every literal-identifier tier above has failed, and the result is tagged
+ *  `matchedVia: "prose"` so a caller can tell the match came from prose content rather
+ *  than the symbol's own name — the render layer does not currently read this (it treats
+ *  a resolved match as a resolved match, same "honest miss vs genuine hit" binary tiers
+ *  1-3 already use), but the field is there for any caller that wants to surface it. (5)
+ *  no match at all — an honest miss. Returns {match, candidates, tier, ambiguous
+ *  [, matchedVia]} — ambiguous on a true tier-3 score tie OR a true tier-4 overlap-count
+ *  tie. */
+export function resolveObject(graph, term) {
+  const t = String(term || "").trim();
+  if (!t) return { match: null, candidates: [], tier: null, ambiguous: false };
+  const tLc = t.toLowerCase();
+  const pool = graph.individuals;
+
+  const exact = pool.find((i) => String(i.label).toLowerCase() === tLc || String(i.id).toLowerCase() === tLc);
+  if (exact) return { match: exact, candidates: [], tier: 1, ambiguous: false };
+
+  // ext: targets never have their own individual (they're a raw edge-endpoint id) — find
+  // the actual (case-preserved) id off a real edge rather than reconstructing it, so a
+  // typo'd term can't silently "resolve" to an ext: id nothing in the graph references.
+  const extLc = `ext:${tLc}`;
+  let extId = null;
+  outer: for (const g of graph.relations) {
+    for (const e of g.edges) {
+      if (String(e.object).toLowerCase() === extLc) { extId = e.object; break outer; }
+    }
+  }
+  if (extId) return { match: { id: extId, label: t, class: null }, candidates: [], tier: 2, ambiguous: false };
+
+  const termComps = componentSet(t);
+  const scored = [];
+  for (const m of pool) {
+    const label = String(m.label || "").toLowerCase();
+    if (label.includes(tLc)) {
+      scored.push({ ind: m, score: 1000 - Math.abs(label.length - tLc.length) });
+      continue;
+    }
+    const overlap = [...termComps].filter((c) => componentSet(m.label).has(c)).length;
+    if (overlap > 0) scored.push({ ind: m, score: overlap * 10 });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  if (scored.length) {
+    const [best, ...rest] = scored;
+    const tied = rest.filter((x) => x.score === best.score);
+    return {
+      match: best.ind,
+      candidates: rest.slice(0, 4).map((x) => x.ind),
+      tier: 3,
+      ambiguous: tied.length > 0,
+    };
+  }
+
+  // tier 4: prose-index fallback (PLAN_PROSE_INDEX.md §6) — see the function doc above.
+  const proseHits = lookupByProseTokens(graph.proseIndex, t);
+  if (proseHits.length) {
+    const [best, ...rest] = proseHits;
+    const bestInd = graph.byId.get(best.id);
+    if (bestInd) {
+      const tied = rest.filter((h) => h.score === best.score);
+      return {
+        match: bestInd,
+        candidates: rest.slice(0, 4).map((h) => graph.byId.get(h.id)).filter(Boolean),
+        tier: 4,
+        ambiguous: tied.length > 0,
+        matchedVia: "prose",
+      };
+    }
+  }
+  return { match: null, candidates: [], tier: null, ambiguous: false };
+}
+
+/** Resolve a term that may be a context pronoun ("this"/"it"/"that"/"here") —
+ *  when `contextId` is given, resolve straight to that graph entity (a real
+ *  click/focus in the caller's UI, not a guess); with no contextId, an honest
+ *  miss explaining exactly what's missing, distinct from "no such name in the
+ *  index". A non-pronoun term always falls through to the ordinary
+ *  resolveObject tiers. */
+function resolveTermOrContext(graph, term, contextId) {
+  if (CONTEXT_PRONOUNS.includes(String(term || "").trim().toLowerCase())) {
+    if (!contextId) return { match: null, candidates: [], tier: null, ambiguous: false, unresolvedPronoun: true };
+    const ind = graph.byId.get(contextId);
+    return ind
+      ? { match: ind, candidates: [], tier: 1, ambiguous: false }
+      : { match: null, candidates: [], tier: null, ambiguous: false, unresolvedPronoun: true };
+  }
+  return resolveObject(graph, term);
+}
+
+// ---- traversal — orchestrates codegraph.mjs's edgesOfKind; grain-refines a module-coarse
+// edge (e.g. imports: Module->Module) down to a finer requested entityType via `defines`
+// (Module -> top-level Function/Class/Method/Attribute), never re-implementing edge scans. ----
+
+function refineToEntities(graph, moduleIds, entityType) {
+  const out = [];
+  for (const e of edgesOfKind(graph, "defines")) {
+    if (!moduleIds.has(e.subject)) continue;
+    const ind = graph.byId.get(e.object);
+    if (ind && ind.class === entityType) out.push(ind);
+  }
+  return out;
+}
+
+/** Safety net (paired with the render-branch fix earlier in this file's history): a
+ *  {shape, kind, entityType} combination must be explicitly listed here to receive
+ *  real non-"direct" modifier behavior. Anything parsing to a non-"direct" modifier
+ *  that ISN'T listed gets an honest "not supported yet" response from render() —
+ *  never a silent fallback to direct-only behavior. This means a future
+ *  MODIFIER_TO_KIND addition that forgets to wire traverse()/render() for it fails
+ *  loud here, by construction, rather than quietly behaving as if the modifier had
+ *  never been given (the exact bug class this file's own render-routing fix, above,
+ *  just caught). Today's only non-"direct" value is "transitive" (PLAN_MECHANICAL_
+ *  CHAT.md P1), wired below for reverse-shape imports/calls closures over
+ *  impactClosure (codegraph.mjs) — module-coarse only; the fine-grained
+ *  callsSymbol/touchesSymbol siblings and every other predicate kind have no
+ *  closure primitive yet, and forward-shape currently never parses a non-"direct"
+ *  modifier at all (both parsing strategies hardcode modifier:"direct" for it). */
+function modifierIsWired(shape, kind, entityType) {
+  return shape === "reverse" && (kind === "imports" || kind === "calls") && (!entityType || entityType === "Module");
+}
+// Matches renderImpact's own default (codegraph.mjs) — impactClosure is reused as-is,
+// not reimplemented, so its own depth convention is the honest one to inherit.
+const TRANSITIVE_MAX_DEPTH = 8;
+
+/** Compile a parsed query into a graph lookup. Pure given (graph, parsed, opts).
+ *  `opts.contextId` resolves a context pronoun ("this"/"it"/…) when the parse
+ *  needed one. Returns {matches, objMatch, candidates, traversal, ambiguous,
+ *  answer?, unresolvedPronoun?} — `answer` only set for the "ask" shape.
+ *  `matches` is always an array of individuals (or edge records for "ask"). */
+export function traverse(graph, parsed, { contextId = null } = {}) {
+  if (!parsed || parsed.ambiguousParse) return { matches: [], objMatch: null, candidates: [], traversal: null, ambiguous: false };
+  const { shape, kind, entityType } = parsed;
+
+  // meta: a question about the graph's OWN vocabulary ("what does cochange mean", "what
+  // is a Commit") — looked up against the SchemaClass/SchemaPredicate individuals
+  // schema-docs.mjs's ingestSchemaDocs merged into the graph, not a code-edge traversal.
+  // Matched by exact (case-insensitive) label ("cochange", "Commit") OR the raw `token`
+  // attribute a SchemaPredicate also carries ("mgx:callsSymbol") — never substring/fuzzy,
+  // same discipline as resolveObject's own tiers: a real term match or an honest miss.
+  if (shape === "meta") {
+    const term = String(parsed.object || "").trim();
+    const termLc = term.toLowerCase();
+    const match = (graph.individuals || []).find((i) => {
+      if (i.class !== "SchemaClass" && i.class !== "SchemaPredicate") return false;
+      if (String(i.label).toLowerCase() === termLc) return true;
+      const token = (i.attributes || []).find((a) => a.key === "token")?.value;
+      return token && String(token).toLowerCase() === termLc;
+    });
+    if (!match) return { matches: [], objMatch: null, candidates: [], traversal: `schema lookup for "${term}"`, ambiguous: false };
+    return {
+      matches: [match], objMatch: match, candidates: [],
+      traversal: `schema lookup for "${term}"`, ambiguous: false,
+    };
+  }
+
+  // §modifier support gate (safety net, see modifierIsWired's own doc above) — checked
+  // BEFORE object resolution, so an unsupported modifier+kind combination gets its own
+  // honest capability-gap message rather than masquerading as an object-miss, or worse,
+  // silently behaving as if "transitively"/"indirectly" had never been said.
+  if (parsed.modifier && parsed.modifier !== "direct" && !modifierIsWired(shape, kind, entityType)) {
+    return {
+      matches: [], objMatch: null, candidates: [], ambiguous: false,
+      unsupportedModifier: true,
+      traversal: `modifier "${parsed.modifier}" requested for a "${kind}" query — no closure traversal exists for this combination yet`,
+    };
+  }
+
+  if (shape === "ask") {
+    const subj = resolveTermOrContext(graph, parsed.subject, contextId);
+    const obj = resolveTermOrContext(graph, parsed.object, contextId);
+    if (!subj.match || !obj.match) {
+      return {
+        matches: [], objMatch: obj.match, candidates: obj.candidates, traversal: null, ambiguous: false, answer: null,
+        unresolvedPronoun: !!(subj.unresolvedPronoun || obj.unresolvedPronoun),
+      };
+    }
+    const edges = edgesOfKind(graph, kind).filter((e) => e.subject === subj.match.id && e.object === obj.match.id);
+    return {
+      matches: edges, answer: edges.length > 0, objMatch: obj.match, subjMatch: subj.match,
+      candidates: [], traversal: `${kind} edge from ${subj.match.label} to ${obj.match.label}`, ambiguous: false,
+    };
+  }
+
+  // reverse and forward both resolve one named term ("object" in the parsed shape — for
+  // forward it is the query's grammatical subject, e.g. "what does X import" -> parsed.object = X).
+  const { match: objMatch, candidates, ambiguous, unresolvedPronoun, matchedVia } = resolveTermOrContext(graph, parsed.object, contextId);
+  if (!objMatch) return { matches: [], objMatch: null, candidates, traversal: null, ambiguous: false, unresolvedPronoun };
+
+  if (shape === "forward") {
+    const edges = edgesOfKind(graph, kind).filter((e) => e.subject === objMatch.id);
+    const matches = edges.map((e) => graph.byId.get(e.object)).filter(Boolean);
+    return { matches, objMatch, candidates, traversal: `${kind} edges where subject = ${objMatch.label}`, ambiguous, matchedVia };
+  }
+
+  // reverse + transitive (PLAN_MECHANICAL_CHAT.md P1): the gate above guarantees kind is
+  // "imports" or "calls" and entityType is null/"Module" here. Reuses impactClosure
+  // (codegraph.mjs) AS-IS rather than reimplementing a closure — impactClosure's own
+  // dependents map is a REVERSE closure over imports+calls edges TOGETHER (renderImpact's
+  // "what would break" framing), not a strict single-predicate chain, so a query for
+  // "transitively imports" and one for "transitively calls" both resolve to the SAME
+  // mixed reverse-dependency closure. That's a real, deliberate scope decision (matching
+  // the plan's own instruction to wire onto "renderImpact's existing closure traversal"
+  // rather than build a new predicate-pure one) — the traversal receipt below says so
+  // honestly rather than implying a narrower single-predicate result than what was
+  // actually computed.
+  if (parsed.modifier === "transitive") {
+    const levels = impactClosure(graph, objMatch, { maxDepth: TRANSITIVE_MAX_DEPTH });
+    const matches = levels.flat().map((d) => graph.byId.get(d.id)).filter(Boolean);
+    return {
+      matches, objMatch, candidates, ambiguous, matchedVia,
+      traversal: `reverse dependency closure over imports+calls edges from ${objMatch.label} (impactClosure, maxDepth=${TRANSITIVE_MAX_DEPTH})`,
+    };
+  }
+
+  // reverse: "which <entityType> R <objMatch>"
+  const symbolKind = SYMBOL_GRAIN_SIBLING[kind];
+  if (symbolKind && FINE_ENTITY_TYPES.has(entityType)) {
+    const edges = edgesOfKind(graph, symbolKind).filter((e) => e.object === objMatch.id);
+    const matches = edges.map((e) => graph.byId.get(e.subject)).filter((i) => i && i.class === entityType);
+    return { matches, objMatch, candidates, traversal: `${symbolKind} edges where object = ${objMatch.label}`, ambiguous, matchedVia };
+  }
+
+  // General case: some predicates are already fine-grained (inherits: Class->Class, contains:
+  // Class->Member) and some are module-coarse (imports/calls/tests/cochange: Module->Module).
+  // Rather than assume one or the other, check what the edge's actual subjects ARE: if they
+  // already match the requested entityType, use them directly (inherits); only when they're
+  // Module individuals and a FINER entityType was asked for do we refine via `defines`
+  // (imports) — never blindly treat an edge's subject id as if it were always a module id.
+  const edges = edgesOfKind(graph, kind).filter((e) => e.object === objMatch.id);
+  const subjects = edges.map((e) => graph.byId.get(e.subject)).filter(Boolean);
+  let matches, grainNote = "";
+  if (!entityType) {
+    matches = subjects;
+  } else {
+    const direct = subjects.filter((s) => s.class === entityType);
+    if (direct.length) {
+      matches = direct;
+    } else if (entityType !== "Module" && subjects.some((s) => s.class === "Module")) {
+      const moduleIds = new Set(subjects.filter((s) => s.class === "Module").map((s) => s.id));
+      matches = refineToEntities(graph, moduleIds, entityType);
+      grainNote = `, then ${entityType} defined in the matched module(s)`;
+    } else {
+      matches = [];
+    }
+  }
+  return { matches, objMatch, candidates, traversal: `${kind} edges where object = ${objMatch.label}${grainNote}`, ambiguous, matchedVia };
+}
+
+// ---- §5 templated renderer — string interpolation + grouping/pluralization/overflow rules,
+// never generation; every sentence is read off a matched edge/individual. ----
+
+function moduleLabelOf(ind) {
+  if (ind.class === "Module") return ind.label;
+  const site = (ind.attributes || []).find((a) => a.key === "site")?.value;
+  if (site) return String(site).split(":")[0];
+  const m = String(ind.id || "").match(/^fn:(.+)#/);
+  return m ? m[1] : "(unknown module)";
+}
+
+function symbolLabelOf(ind) {
+  const label = String(ind.label || ind.id || "");
+  return ["Function", "Method"].includes(ind.class) ? `function ${label}()` : label;
+}
+
+/** One-line, honest rephrasing of a candidate parse — used to describe a
+ *  parse-level disagreement between strategies without pretending to pick
+ *  a winner. Template only, reads straight off the parsed fields. */
+function describeParse(p) {
+  const obj = p.object ?? p.subject ?? "?";
+  const ent = p.entityType ? nounFor(p.entityType, 2) + " that " : "";
+  return `${ent}${p.kind} "${obj}"`;
+}
+
+/** Render a compiled query result into {content, miss, ambiguous, matches?, candidates?}.
+ *  Every branch is a template, not generation — §5's grouping/pluralization/overflow rules. */
+export function render(parsed, result) {
+  if (!parsed) {
+    return { content: `couldn't parse this as a graph question. Try: ${rephraseHint()}`, miss: true, ambiguous: false };
+  }
+  if (parsed.ambiguousParse) {
+    const options = parsed.candidates.map((p, i) => `${i + 1}) ${describeParse(p)}`).join(" or ");
+    return {
+      content: `this could mean more than one thing: ${options} — try rephrasing more specifically.`,
+      miss: false, ambiguous: true, candidates: parsed.candidates.map(describeParse),
+    };
+  }
+  if (result.unresolvedPronoun) {
+    return {
+      content: `"${parsed.object ?? parsed.subject}" needs a selected node to refer to — click a node first, or name it directly.`,
+      miss: true, ambiguous: false,
+    };
+  }
+  if (result.unsupportedModifier) {
+    return {
+      content: `the "${parsed.modifier}" modifier isn't supported for "${parsed.kind}" queries yet — only imports/calls (module-level) have a transitive closure today.`,
+      miss: true, ambiguous: false,
+    };
+  }
+  if (parsed.shape === "meta") {
+    if (!result.objMatch) {
+      return {
+        content: `"${parsed.object}" isn't a term in this graph's own vocabulary (no matching class or predicate).`,
+        miss: true, ambiguous: false,
+      };
+    }
+    const doc = (result.objMatch.attributes || []).find((a) => a.key === "doc")?.value || "";
+    const kindWord = result.objMatch.class === "SchemaClass" ? "a class in the graph's schema" : "a predicate (relation) in the graph's schema";
+    return { content: `${result.objMatch.label} is ${kindWord}: ${doc}`, miss: false, ambiguous: false, matches: result.matches };
+  }
+  if (!result.objMatch && (!result.candidates || result.candidates.length === 0) && parsed.shape !== "ask") {
+    return {
+      content: `no module matching "${parsed.object}" found in the index.`,
+      miss: true, ambiguous: false, candidates: [],
+    };
+  }
+  if (result.ambiguous) {
+    return {
+      content: `"${parsed.object}" matches more than one module ambiguously — please narrow the term.`,
+      miss: false, ambiguous: true, candidates: [result.objMatch, ...(result.candidates || [])].map((i) => i.label),
+    };
+  }
+  if (parsed.shape === "ask") {
+    if (!result.objMatch || !result.subjMatch) {
+      return { content: `couldn't resolve one of the terms in this question.`, miss: true, ambiguous: false };
+    }
+    return {
+      content: result.answer ? `Yes. (${result.traversal})` : `No — no ${parsed.kind} edge found from ${result.subjMatch.label} to ${result.objMatch.label}.`,
+      miss: !result.answer, ambiguous: false,
+    };
+  }
+  if (!result.matches.length) {
+    // forward: parsed.object is the GIVEN subject ("what does X import" -> X), not a
+    // search target — "No modules found that X." reads as broken grammar (and X's own
+    // relation edges are simply absent, not "not found"), so this shape gets its own,
+    // subject-first phrasing rather than reusing reverse's "found ... that OBJECT" template.
+    if (parsed.shape === "forward") {
+      return {
+        content: `${result.objMatch.label} has no ${parsed.kind} edges in the index. (traversal: ${result.traversal || "no traversal resolved"})`,
+        miss: true, ambiguous: false,
+      };
+    }
+    const entityWord = nounFor(parsed.entityType || "Module", 2);
+    return {
+      content: `No ${entityWord} found whose module directly ${verbFor(parsed.kind)} ${parsed.object}. (traversal: ${result.traversal || "no traversal resolved"})`,
+      miss: true, ambiguous: false,
+    };
+  }
+  // Route by the MATCHED entities' actual class, not just the parsed hint — a reverse
+  // query phrased without an explicit entity keyword ("what imports X", entityType null)
+  // still resolves to Module individuals for a module-level relation like "imports", and
+  // grouping those by-module (module label as its own "symbol" label) reads as nonsense
+  // ("in a.mjs there is a.mjs"). The fine-grained per-symbol grouping below is only
+  // meaningful when the matches are sub-module entities (functions/classes/etc).
+  if (parsed.shape === "forward" || parsed.entityType === "Module" || result.matches.every((m) => m.class === "Module")) {
+    const shown = result.matches.slice(0, OVERFLOW_CAP).map((m) => m.label);
+    const extra = result.matches.length > OVERFLOW_CAP ? `, …and ${result.matches.length - OVERFLOW_CAP} more` : "";
+    return { content: shown.join(" and ") + extra + ".", miss: false, ambiguous: false, matches: result.matches };
+  }
+  // reverse, fine-grained entity: group by module, one clause per module (§5 grouping rule) —
+  // the FIRST module states "in {module} there is …"; each SUBSEQUENT module states
+  // "there is … in {module}" (module trails, not leads), matching the plan's worked example.
+  const byModule = new Map();
+  for (const m of result.matches.slice(0, OVERFLOW_CAP)) {
+    const mod = moduleLabelOf(m);
+    if (!byModule.has(mod)) byModule.set(mod, []);
+    byModule.get(mod).push(symbolLabelOf(m));
+  }
+  const listJoin = (syms) =>
+    syms.length > 1 ? `${syms.slice(0, -1).join(", ")} and ${syms[syms.length - 1]}` : syms[0];
+  const clauses = [...byModule.entries()].map(([mod, syms], i) => {
+    const list = listJoin(syms);
+    return i === 0 ? `in ${mod} there is ${list}` : `there is ${list} in ${mod}`;
+  });
+  const extra = result.matches.length > OVERFLOW_CAP ? ` …and ${result.matches.length - OVERFLOW_CAP} more` : "";
+  return { content: clauses.join(" and ") + extra + ".", miss: false, ambiguous: false, matches: result.matches };
+}
+
+// ---- orchestration — the seonix_ask entry point (§6.3: parse -> resolve -> traverse -> render) ----
+
+/** Answer a free-text question over the graph, mechanically. `opts.contextId`
+ *  resolves a context pronoun ("this"/"it"/…) — wired from a UI's currently-
+ *  selected node when one exists; omit it in the bare CLI/MCP surface, where
+ *  a pronoun then produces an honest miss rather than a guess. Returns the
+ *  full {content, seonix_ask:{mechanical,parsed,matches,traversal,miss,
+ *  ambiguous,candidates?}} envelope §6.2 specifies. Zero model calls. */
+export function ask(graph, query, { contextId = null } = {}) {
+  const parsed = parseQuery(query);
+  const result = traverse(graph, parsed, { contextId });
+  const rendered = render(parsed, result);
+  return {
+    content: rendered.content,
+    seonix_ask: {
+      mechanical: true,
+      parsed: (parsed && !parsed.ambiguousParse) ? parsed : null,
+      matches: (result.matches || []).map((m) => ({
+        id: m.id, label: m.label, type: m.class, module: m.class ? moduleLabelOf(m) : undefined,
+      })),
+      traversal: result.traversal || null,
+      miss: !!rendered.miss,
+      ambiguous: !!rendered.ambiguous,
+      // Confidence provenance (PLAN_PROSE_INDEX.md §6): set only when resolveObject's
+      // object-term resolution fell all the way through to the tier-4 prose-index
+      // fallback (a word-level match against a decomposed identifier/doc-comment, not
+      // the symbol's own literal name) — null for every other (literal-identifier) tier,
+      // so a caller can distinguish "matched the thing's own name" from "matched
+      // something it merely talks about" without the rendered content wording changing.
+      matchedVia: result.matchedVia || null,
+      ...(rendered.ambiguous ? { candidates: rendered.candidates } : {}),
+    },
+  };
+}