@polycode-projects/seonix 0.2.1 → 0.3.0

package/src/ask.mjs

@@ -2,10 +2,13 @@
 // 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).
+// templated, citation-faithful answer. No embeddings, no generative 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). Term/keyword matching is TIERED
+// (2026-07-02, two-level fuzzy): exact curated match always wins; a Node-only
+// wink-nlp LEMMA/POS tier and a bounded Damerau-Levenshtein FUZZY tier fire only
+// on a miss, a unique fuzzy hit is announced in the answer ("assuming you
+// meant …"), and any tie surfaces as ambiguity — never a silently-broken guess.
 //
 // Four pure, independently-testable stages, orchestrated by ask():
 //   parseQuery (grammar)  ->  resolveObject (mechanical term resolution)  ->
@@ -35,10 +38,19 @@
 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,
+  CONTRACTIONS, MISSPELLINGS, WRONG_WORDS, G_DROP, FILLER_WORDS,
+  CONTEXT_PRONOUNS, NEGATION_FRAMES, COMMIT_CONTENT_FRAMES, META_MEANING_VERBS,
+  WHERE_MARKERS, MENTION_MARKERS,
 } from "./ask-vocab.mjs";
 import { lookupByProseTokens } from "./prose.mjs";
+// The OPTIONAL Node-only wink-nlp adapter (lemma/POS tier). BOUNDARY: the inlined
+// viewer bundle (viz.mjs askSource) strips this import line and never inlines
+// ask-nlp.mjs, so in the browser `nlpAdapter` is simply an undeclared identifier —
+// defaultNlp() below reads it through `typeof`, the one operator that touches an
+// undeclared name without throwing, and the portable single-file HTML degrades to
+// adapter-less parsing (curated tables + bounded fuzzy still on) instead of
+// shipping a ~1MB language model inside the page.
+import { nlpAdapter } from "./ask-nlp.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
@@ -60,6 +72,14 @@ function edgesOfKind(graph, kind) {
 const SYMBOL_GRAIN_SIBLING = { calls: "callsSymbol", touches: "touchesSymbol" };
 const FINE_ENTITY_TYPES = new Set(["Function", "Method", "Class", "Attribute", "GlobalVariable"]);
 
+// Query-side UNION families (2026-07-02 query families): a parsed kind that is not
+// itself a stored predicate but a curated union of stored kinds — "what uses X"
+// honestly means the import graph AND the call graph together. Everything else
+// maps to itself; grain selection (asked entity type) then narrows the union's
+// subjects the same way it narrows a single kind's.
+const KIND_UNIONS = { uses: ["imports", "calls", "callsSymbol"] };
+const kindsFor = (kind) => KIND_UNIONS[kind] || [kind];
+
 const OVERFLOW_CAP = 12;
 
 const PLURAL_FORMS = {
@@ -67,6 +87,9 @@ const PLURAL_FORMS = {
   Class: ["class", "classes"], Module: ["module", "modules"],
   Attribute: ["attribute", "attributes"], GlobalVariable: ["variable", "variables"],
   Commit: ["commit", "commits"],
+  // "Change" is ask-vocab.mjs's pseudo-type (a wildcard over the touch traversal's
+  // results, never a node class) — it still needs noun forms for zero-hit templates.
+  Change: ["change", "changes"],
 };
 function nounFor(entityType, n) {
   const [s, p] = PLURAL_FORMS[entityType] || ["result", "results"];
@@ -92,10 +115,25 @@ function escapeRegex(s) {
 
 /** 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",
+const tableRe = (table) => new RegExp(
+  "\\b(" + Object.keys(table).sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b",
+  "gi",
+);
+const CONTRACTION_RE = tableRe(CONTRACTIONS);
+// misspelling/wrong-word CORRECTIONS (ask-vocab.mjs) — same mechanism, applied
+// after contractions: restore the intended spelling first, then map misused
+// words to their canonical schema term. Deterministic and curated, so they run
+// BEFORE either parse strategy and ahead of the bounded edit-distance fallback.
+// The trailing lookahead refuses to rewrite a word glued to a dotted extension:
+// WRONG_WORDS entries are real English words that plausibly NAME modules
+// ("revision.mjs", "property.py"), and a correction that corrupts an object
+// term would be a guess — the exact thing these tables exist to avoid.
+const correctionRe = (table) => new RegExp(
+  "\\b(" + Object.keys(table).sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b(?!\\.[a-z0-9])",
   "gi",
 );
+const MISSPELLING_RE = correctionRe(MISSPELLINGS);
+const WRONG_WORD_RE = correctionRe(WRONG_WORDS);
 
 /** Free-text -> normalized free-text: contractions expanded, g-dropped words
  *  restored, filler/politeness words stripped. Idempotent and pure — the same
@@ -109,6 +147,8 @@ const CONTRACTION_RE = new RegExp(
 export function normalizeQuery(text) {
   let q = String(text || "");
   q = q.replace(CONTRACTION_RE, (m) => CONTRACTIONS[m.toLowerCase()]);
+  q = q.replace(MISSPELLING_RE, (m) => MISSPELLINGS[m.toLowerCase()]);
+  q = q.replace(WRONG_WORD_RE, (m) => WRONG_WORDS[m.toLowerCase()]);
   q = q.replace(G_DROP, "$1ing");
   if (FILLER_WORDS.length) {
     const fillerRe = new RegExp(
@@ -120,12 +160,15 @@ export function normalizeQuery(text) {
   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. */
+/** Recognized rhetorical/idiomatic constructions rewritten to the canonical form
+ *  of the SAME question before either parse strategy sees the text — a small
+ *  closed pattern set, not a general rewriter. Two families, tried in order:
+ *  COMMIT_CONTENT_FRAMES first ("what was in commit <sha>" -> "what did <sha>
+ *  touch"; sha-anchored, so it can't swallow a containment question), then the
+ *  §3.6 negative-rhetorical NEGATION_FRAMES. First matching frame across both wins
+ *  and rewriting stops; unmatched text passes through unchanged. */
 export function applyNegationFrames(text) {
-  for (const frame of NEGATION_FRAMES) {
+  for (const frame of [...COMMIT_CONTENT_FRAMES, ...NEGATION_FRAMES]) {
     const m = text.match(frame.re);
     if (m) return frame.to(m).replace(/\s+/g, " ").trim();
   }
@@ -143,11 +186,12 @@ const META_ALT = META_MEANING_VERBS.slice().sort((a, b) => b.length - a.length).
 
 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
+  // does/is/do/did, 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.
+  // "did" joins does/do for the past-tense commit forms ("did commit <sha> touch X").
   {
     name: "ask",
-    re: new RegExp(`^(?:does|do)\\s+(.+?)\\s+(${VERB_ALT})\\s+(.+?)\\??$`, "i"),
+    re: new RegExp(`^(?:does|do|did)\\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(),
@@ -166,9 +210,10 @@ const TEMPLATES = [
     }),
   },
   // T3 forward: "what does <object> <verb>" — X is given, list its R-related things.
+  // "did" joins does/do for the past-tense commit forms ("what did commit <sha> touch").
   {
     name: "forward",
-    re: new RegExp(`^what\\s+(?:does|do)\\s+(.+?)\\s+(${VERB_ALT})\\??$`, "i"),
+    re: new RegExp(`^what\\s+(?:does|do|did)\\s+(.+?)\\s+(${VERB_ALT})\\??$`, "i"),
     build: (m) => ({
       shape: "forward", entityType: null, modifier: "direct",
       kind: VERB_TO_KIND[m[2].toLowerCase()], object: m[1].trim(),
@@ -197,14 +242,48 @@ const TEMPLATES = [
     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() }),
   },
+  // T6 mention: "where is <term> mentioned/referenced" — the prose/mentions surface
+  // (2026-07-02 query families). Tried BEFORE T7: T7's trailing marker is optional,
+  // so without this ordering it would swallow the mention question and lose the
+  // marker that distinguishes "locate the definition" from "list the prose mentions".
+  {
+    name: "mention",
+    re: new RegExp(`^where\\s+(?:is|are|was|were)\\s+(.+?)\\s+(?:${MENTION_MARKERS.map(escapeRegex).join("|")})\\??$`, "i"),
+    build: (m) => ({ shape: "mentions", entityType: null, modifier: "direct", kind: "mentions", object: m[1].trim() }),
+  },
+  // T7 where: "where is <term> [defined|declared|located|implemented]" — definition
+  // location off the site attribute / defining module. "where" starts no other
+  // template, so precedence against T1-T5 is structural.
+  {
+    name: "where",
+    re: new RegExp(`^where\\s+(?:is|are|was|were)\\s+(.+?)(?:\\s+(?:${WHERE_MARKERS.map(escapeRegex).join("|")}))?\\??$`, "i"),
+    build: (m) => ({ shape: "where", entityType: null, modifier: "direct", kind: "where", object: m[1].trim() }),
+  },
+  // T8 when: "when did <term> [last] change/touched/updated…" — temporal shape over
+  // the touches edges + commit date attributes. The verb slot reuses VERB_ALT, but
+  // only the touches family carries dates to answer with, so build() rejects any
+  // other kind (returning null falls through — parseAnchored tolerates it) rather
+  // than pretending "when did X import Y" has a temporal answer.
+  {
+    name: "when",
+    re: new RegExp(`^when\\s+(?:did|does|do|was|were|is)\\s+(.+?)\\s+(?:last\\s+)?(${VERB_ALT})\\??$`, "i"),
+    build: (m) => (VERB_TO_KIND[m[2].toLowerCase()] === "touches"
+      ? { shape: "when", entityType: null, modifier: "direct", kind: "touches", object: m[1].trim() }
+      : null),
+  },
 ];
 
-/** Strategy 1: the original P0 anchored grammar, unmodified in behavior — the
- *  whole (normalized) string must match one of TEMPLATES start-to-end. Pure. */
+/** Strategy 1: the original P0 anchored grammar — the whole (normalized) string
+ *  must match one of TEMPLATES start-to-end. A build() may return null to reject
+ *  a structural match on curated grounds (T8's non-temporal verbs); the scan then
+ *  simply continues, exactly as if the regex had not matched. Pure. */
 function parseAnchored(text) {
   for (const t of TEMPLATES) {
     const m = text.match(t.re);
-    if (m) return t.build(m);
+    if (m) {
+      const parsed = t.build(m);
+      if (parsed) return parsed;
+    }
   }
   return null;
 }
@@ -217,26 +296,112 @@ function parseAnchored(text) {
 
 const STOPWORDS = new Set([
   "what", "who", "which", "where", "when", "why", "how",
-  "does", "do", "is", "are", "the", "a", "an", "of", "to", "from", "at", "in", "on",
+  "does", "do", "did", "is", "are", "was", "were", "the", "a", "an", "of", "to", "from", "at", "in", "on",
   "there", "something", "anything", "nothing", "one", "any",
+  // temporal filler in when-questions ("when was X last touched") — a symbol
+  // literally named "last" would be the accepted residual cost, same trade as
+  // every other stopword.
+  "last",
 ]);
 
 /** 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) {
+ *  shadowed by a shorter unrelated word. A span overlapping `consumed` indices
+ *  is skipped: the verb and entity tables now share a surface form ("change"
+ *  is both a touches verb and the Change entity noun), and a word already
+ *  claimed by the verb pass must not double as the entity keyword. Returns
+ *  {kind, start, end} (end exclusive) or null. */
+function findPhrase(lcWords, table, consumed = null) {
   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 (consumed && pWords.some((_, j) => consumed.has(i + j))) continue;
       if (pWords.every((w, j) => lcWords[i + j] === w)) return { kind: table[p], start: i, end: i + pWords.length };
     }
   }
   return null;
 }
 
+// ---- bounded edit distance (two-level fuzzy, 2026-07-02) — hand-rolled
+// Damerau-Levenshtein (optimal string alignment: substitution/insertion/deletion
+// + adjacent transposition), bounded with an early row-minimum exit. Used by the
+// keyword-spot FUZZY tier below and resolveObject's tier 5 — both fire only after
+// every exact/curated tier missed, and a distance TIE is refused (keyword) or
+// surfaced as ambiguity (object), never broken by a guess. Pure JS, no deps, so
+// the inlined viewer bundle gets fuzzy matching for free. ----
+
+/** Distance between a and b, or max+1 as soon as it provably exceeds `max`. */
+function editDistance(a, b, max) {
+  if (a === b) return 0;
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  let prev2 = null;
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i += 1) {
+    const cur = [i];
+    let rowMin = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let v = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) v = Math.min(v, prev2[j - 2] + cost);
+      cur[j] = v;
+      if (v < rowMin) rowMin = v;
+    }
+    if (rowMin > max) return max + 1;
+    prev2 = prev;
+    prev = cur;
+  }
+  return prev[b.length];
+}
+
+/** The curated distance budget: 1 edit for short tokens, 2 for longer ones. */
+const fuzzyBound = (s) => (s.length <= 5 ? 1 : 2);
+
+/** Every single word appearing in the three parse tables — the "is this word
+ *  already vocabulary?" gate for the lemma/fuzzy canonicalization passes (an
+ *  exact vocab word is NEVER rewritten: exact curated match always wins). */
+const VOCAB_WORDS = new Set(
+  [...Object.keys(VERB_TO_KIND), ...Object.keys(ENTITY_TO_TYPE), ...Object.keys(MODIFIER_TO_KIND)]
+    .flatMap((p) => p.split(" ")),
+);
+
+/** Fuzzy-correction TARGETS: verb-phrase and modifier constituents only, length ≥4.
+ *  Entity nouns are deliberately excluded — real identifiers collide with them at
+ *  distance ≤2 far too easily ("myfile" is 2 edits from "file", "caller" 2 from
+ *  "calls"-family words), and entity-noun typos are already owned by the curated
+ *  MISSPELLINGS table where such calls are made deliberately. Short constituents
+ *  ("of", "to", "in", "on") are excluded for the same reason: at bound 1 half of
+ *  English is adjacent to them. */
+const FUZZY_TARGET_WORDS = [...new Set(
+  [...Object.keys(VERB_TO_KIND), ...Object.keys(MODIFIER_TO_KIND)]
+    .flatMap((p) => p.split(" "))
+    .filter((w) => w.length >= 4),
+)];
+
+/** A query word may be canonicalized only if it is plain alphabetic, not a
+ *  stopword, and not already vocabulary. Dotted/digit terms (file names, shas)
+ *  are never touched. */
+function eligibleForCanon(w) {
+  return /^[a-z]+$/.test(w) && !STOPWORDS.has(w) && !VOCAB_WORDS.has(w);
+}
+
+/** UNIQUE within-bound fuzzy vocab keyword for `w`, or null — a tie between two
+ *  distinct target words at the same distance is refused outright (the honest-miss
+ *  discipline at the vocabulary level; cf. MISSPELLINGS' curated "calss" decision). */
+function fuzzyVocabWord(w) {
+  const bound = fuzzyBound(w);
+  let best = bound + 1;
+  let hit = null;
+  let tied = false;
+  for (const target of FUZZY_TARGET_WORDS) {
+    const d = editDistance(w, target, Math.min(best, bound));
+    if (d < best) { best = d; hit = target; tied = false; }
+    else if (d === best && d <= bound && target !== hit) tied = true;
+  }
+  return best <= bound && !tied ? hit : 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
@@ -250,21 +415,95 @@ function findPhrase(lcWords, table) {
  *  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) {
+ *  downstream (resolveObject never guesses).
+ *
+ *  Keyword matching is TIERED (two-level fuzzy work, 2026-07-02) — each lower
+ *  tier fires ONLY when every tier above found no verb phrase at all, so an
+ *  exact curated match can never be displaced:
+ *    1. exact — the words as typed (post-normalization, which already applied
+ *       the curated CONTRACTIONS/MISSPELLINGS/WRONG_WORDS corrections);
+ *    2. lemma (only with the optional Node-side `nlp` adapter) — each eligible
+ *       word is replaced by its wink lemma IF that lemma is itself a vocab word
+ *       ("imported"/"importing" -> "import"), so inflections hit the curated
+ *       phrases without enumerating them. Every verb family already stores its
+ *       lemma form ("import", "call", "touch", "use", …), so a direct
+ *       lemma-in-vocab check is the whole lookup — no reverse index needed;
+ *    3. fuzzy (adapter-free; works in the inlined viewer too) — a word ≥4 chars
+ *       matching nothing exactly may rewrite to a UNIQUE verb/modifier
+ *       constituent within the bounded edit distance (see fuzzyVocabWord; ties
+ *       are refused, entity nouns are never fuzzy targets).
+ *  The canonicalized words drive PHRASE FINDING only — sideText always reads the
+ *  ORIGINAL words, so a correction can never corrupt an object/subject term. */
+function parseKeywordSpot(text, nlp = null) {
   // 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);
+  // where/mentions shapes (2026-07-02 query families): "where is X [defined]" and
+  // "where is X mentioned" carry NO relation verb, so the verb-driven decomposition
+  // below can never reach them. Routed here by the "where" question word + marker —
+  // but ONLY when no relation verb exists anywhere in the sentence: "something
+  // executes this, where from" (an existing worked phrasing) has a verb, and its
+  // "where" is decorative, not a location question.
+  if (lcWords.includes("where") && !findPhrase(lcWords, VERB_TO_KIND)) {
+    const mention = lcWords.some((w) => MENTION_MARKERS.includes(w));
+    const markers = new Set([...WHERE_MARKERS, ...MENTION_MARKERS]);
+    const objText = words.filter((w, i) => !STOPWORDS.has(lcWords[i]) && !markers.has(lcWords[i])).join(" ").trim();
+    if (objText) {
+      const kind = mention ? "mentions" : "where";
+      return { shape: kind, entityType: null, modifier: "direct", kind, object: objText };
+    }
+  }
+  let canonWords = lcWords;
+  let verbHit = findPhrase(lcWords, VERB_TO_KIND);
+  if (!verbHit && nlp) {
+    // tier 2: lemma (see the tier doc above) — replace only when the lemma is
+    // itself vocabulary, so unknown words ("myfile") pass through untouched.
+    const lemmaWords = lcWords.map((w) => {
+      if (!eligibleForCanon(w)) return w;
+      const l = nlp.lemma(w);
+      return VOCAB_WORDS.has(l) ? l : w;
+    });
+    verbHit = findPhrase(lemmaWords, VERB_TO_KIND);
+    if (verbHit) canonWords = lemmaWords;
+  }
+  if (!verbHit) {
+    // tier 3: bounded-edit-distance rewrite toward verb/modifier keywords only
+    // ("impotr" -> "import"); ≥4-char words only — below that the bound covers
+    // half of English (and "and" is 1 edit from the "land in" constituent).
+    const fuzzyWords = lcWords.map((w) => (w.length >= 4 && eligibleForCanon(w) ? fuzzyVocabWord(w) || w : w));
+    verbHit = findPhrase(fuzzyWords, VERB_TO_KIND);
+    if (verbHit) canonWords = fuzzyWords;
+  }
   if (!verbHit) return null;
-  const entityHit = findPhrase(lcWords, ENTITY_TO_TYPE);
-  const modifierHit = findPhrase(lcWords, MODIFIER_TO_KIND);
+  // POS consumer (wink adapter, Node-side only): rescue the ONE decomposition this
+  // strategy provably mis-parses — a relation word used as a NOUN in a "the
+  // <imports> of <term>" nominal ("show the imports of walk.mjs" otherwise
+  // decomposes to ask{subject:"show"}; bare "the imports of walk.mjs" to the
+  // reverse shape, both wrong). The wink probe showed "import" is tagged NOUN even
+  // in genuine verb use ("which modules import walk.mjs"), so the POS signal is
+  // deliberately NOT a general verb veto — it only fires inside this exact
+  // det+NOUN+"of" frame, where the nominal reading is grammatically forced.
+  if (nlp && verbHit.end - verbHit.start === 1) {
+    const i = verbHit.start;
+    const det = lcWords[i - 1];
+    if ((det === "the" || det === "these" || det === "those") && lcWords[i + 1] === "of") {
+      const tags = nlp.posTags(words);
+      if (tags[i] === "NOUN") {
+        const objText = words.slice(i + 2).filter((w, j) => !STOPWORDS.has(lcWords[i + 2 + j])).join(" ").trim();
+        if (objText) return { shape: "forward", entityType: null, modifier: "direct", kind: verbHit.kind, object: objText };
+      }
+    }
+  }
   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);
+  mark(verbHit);
+  const entityHit = findPhrase(canonWords, ENTITY_TO_TYPE, consumed);
+  mark(entityHit);
+  const modifierHit = findPhrase(canonWords, MODIFIER_TO_KIND, consumed);
+  mark(modifierHit);
   const sideText = (from, to) => words
     .slice(from, to)
     .filter((_, j) => !consumed.has(from + j) && !STOPWORDS.has(lcWords[from + j]))
@@ -273,12 +512,28 @@ function parseKeywordSpot(text) {
   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";
+  // slices read canonWords, not lcWords: the entity/modifier spans were matched
+  // against the canonicalized array, whose word IS the table key.
+  const entityType = entityHit ? ENTITY_TO_TYPE[canonWords.slice(entityHit.start, entityHit.end).join(" ")] : null;
+  const modifier = modifierHit ? MODIFIER_TO_KIND[canonWords.slice(modifierHit.start, modifierHit.end).join(" ")] : "direct";
+
+  // when shape (2026-07-02 query families): "when did X change" / "when was X last
+  // touched" — the "when" question word turns a touches decomposition temporal.
+  // Only touches carries commit dates to answer with; a "when" next to any other
+  // relation verb falls through to the ordinary shapes (and their honest answers).
+  if (kind === "touches" && lcWords.includes("when")) {
+    const objText = beforeText || afterText;
+    if (objText) return { shape: "when", entityType: null, modifier: "direct", kind: "touches", object: objText };
+  }
 
   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 };
+  // forward keeps the spotted entityType ("which modules did commit <sha> touch" is a
+  // forward decomposition — subject before the verb — whose asked grain would otherwise
+  // be lost); traverse() only consults it for the commit-as-subject grain selection,
+  // so plain forwards behave exactly as before. Modifier stays hardcoded: no forward
+  // closure traversal exists (see modifierIsWired).
+  if (beforeText) return { shape: "forward", entityType, modifier: "direct", kind, object: beforeText };
   return null;
 }
 
@@ -290,7 +545,20 @@ const STRATEGIES = [
   { name: "keyword-spot", parse: parseKeywordSpot },
 ];
 
-const cmpTerm = (s) => String(s || "").trim().toLowerCase().replace(/\s+/g, " ");
+/** The default lemma/POS adapter: wink-nlp when this is a Node process with the
+ *  optional deps installed, null otherwise. BOUNDARY (see the import comment):
+ *  the inlined viewer bundle strips the ask-nlp.mjs import, so `nlpAdapter` is
+ *  an UNDECLARED identifier there — `typeof` reads it without throwing and the
+ *  browser path degrades to no adapter, same parse pipeline otherwise. */
+function defaultNlp() {
+  return typeof nlpAdapter === "function" ? nlpAdapter() : null;
+}
+
+// "commit abc1234" and bare "abc1234" are the SAME term once resolveObject's
+// commit-sha tier strips the noun — the anchored strategy captures the noun inside
+// its object span while keyword-spot consumes it as the entity keyword, so without
+// this the two strategies would "disagree" over a word that names no different thing.
+const cmpTerm = (s) => String(s || "").trim().toLowerCase().replace(/\s+/g, " ").replace(/^commit\s+(?=[0-9a-f]{7,40}$)/, "");
 
 /** Do two independently-produced parses mean the same graph query? Same
  *  shape, same relation kind, and matching term(s) (both subject and object
@@ -310,13 +578,17 @@ function sameParse(p, q) {
  *  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) {
+ *  object-resolution ambiguity. `opts.nlp` overrides the lemma/POS adapter
+ *  (pass null to force the adapter-less browser behavior in a Node test);
+ *  leaving it undefined picks the deterministic default (defaultNlp). Pure
+ *  given (query, adapter) — the adapter itself is a fixed model, no sampling. */
+export function parseQuery(query, { nlp = undefined } = {}) {
+  const adapter = nlp === undefined ? defaultNlp() : nlp;
   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);
+  const hits = STRATEGIES.map((s) => ({ name: s.name, parsed: s.parse(text, adapter) })).filter((r) => r.parsed);
   if (hits.length === 0) return null;
   if (hits.length === 1) return hits[0].parsed;
   const [a, b] = hits;
@@ -327,7 +599,7 @@ export function parseQuery(query) {
 /** 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)';
+  return '"which <functions|classes|modules> <imports|calls|uses|inherits from|tests|touched> <name>" or "what does <name> <import|call|export>" or "what uses <name>" or "where is <name> defined" / "where is <name> mentioned" or "when did <name> change" or "which changes touch commit <sha>"/"what did commit <sha> touch" (a commit\'s own changes) 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 ----
@@ -339,7 +611,9 @@ function componentSet(s) {
 /** 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
+ *  just modules): a sha-shaped term ("[commit ]<hex≥7>") first resolves against Commit
+ *  individuals by unique id/label prefix (see the inline comment), then (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;
@@ -355,15 +629,43 @@ function componentSet(s) {
  *  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. */
+ *  a bounded Damerau-Levenshtein pass against labels AND label components (two-level
+ *  fuzzy, 2026-07-02): a UNIQUE within-bound match resolves, tagged `matchedVia:
+ *  "fuzzy"` so render() can say "assuming you meant <label>" out loud; multiple
+ *  matches at the same best distance are an honest ambiguity listing the candidates.
+ *  Never applied to sha-shaped terms (the commit namespace is exact-or-ambiguous
+ *  only) nor to terms under 4 chars (the bound would cover half of everything).
+ *  (6) no match at all — an honest miss. Returns {match, candidates, tier, ambiguous
+ *  [, matchedVia]} — ambiguous on a true tier-3 score tie, a tier-4 overlap-count
+ *  tie, or a tier-5 distance 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;
 
+  // commit-sha tier (checked first, only for sha-shaped terms): "ef74e44e25c8",
+  // "commit ef74e44e25c8", "commit:ef74e44", or a full 40-char sha resolve against
+  // Commit individuals by id/label prefix (ids are commit:<full-sha>, labels the
+  // 12-char short sha), case-insensitive. A UNIQUE prefix is exact-grade over the
+  // closed commit namespace (tier 1); a prefix shared by more than one commit is an
+  // honest ambiguity listing the candidates — never "the first one"; a hex-looking
+  // word matching NO commit falls through to the ordinary tiers unchanged (it may
+  // be a real code identifier).
+  const shaTerm = tLc.match(/^(commit[:\s])?([0-9a-f]{7,40})$/);
+  if (shaTerm) {
+    const sha = shaTerm[2];
+    const hits = pool.filter((i) => i.class === "Commit"
+      && (String(i.id).toLowerCase().startsWith(`commit:${sha}`) || String(i.label).toLowerCase().startsWith(sha)));
+    if (hits.length === 1) return { match: hits[0], candidates: [], tier: 1, ambiguous: false };
+    if (hits.length > 1) return { match: hits[0], candidates: hits.slice(1, 5), tier: 1, ambiguous: true };
+    // the explicit "commit" noun declares intent — with no matching commit, falling
+    // through would let the WORD "commit" component-match the Commit schema node (or
+    // any identifier containing it): a guess, not a resolution. Bare hex still falls
+    // through (it may be a real code identifier).
+    if (shaTerm[1]) return { match: null, candidates: [], tier: null, ambiguous: false };
+  }
+
   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 };
 
@@ -379,16 +681,42 @@ export function resolveObject(graph, term) {
   }
   if (extId) return { match: { id: extId, label: t, class: null }, candidates: [], tier: 2, ambiguous: false };
 
-  const termComps = componentSet(t);
+  // tier 3 — two disjoint regimes (dotted-symbol fix, 2026-07-02, advisor-verified
+  // bug): a DOTTED term with no slash ("res.json", "Widget.render", "walk.mjs") is
+  // symbol-shaped (object.member / Class.method / a bare file name), and the old
+  // any-substring-of-any-label pass let it land on a module whose PATH merely
+  // contains the text ("res.json" -> test/res.json.js — the wrong grain presented
+  // as if the term were that file). Such terms now match only (a) symbol labels
+  // (whole-term containment, or the ".member" suffix when the owner alias differs:
+  // "res.json" -> Response.json), and (b) module labels by EXACT basename equality
+  // ("walk.mjs" -> src/walk.mjs — extension-stripped basename equality is
+  // deliberately NOT used; that is precisely the phantom-path vector). Symbol
+  // matches outrank module matches. Undotted/slashed terms keep the original pass.
   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 dotted = !tLc.includes("/") && /^[\w$]+(\.[\w$]+)+$/.test(tLc);
+  if (dotted) {
+    const lastSeg = tLc.split(".").pop();
+    for (const m of pool) {
+      const label = String(m.label || "").toLowerCase();
+      if (m.class === "Module") {
+        if (label.split("/").pop() === tLc) scored.push({ ind: m, score: 1000 - Math.abs(label.length - tLc.length) });
+      } else if (label.includes(tLc)) {
+        scored.push({ ind: m, score: 2000 - Math.abs(label.length - tLc.length) });
+      } else if (label.endsWith(`.${lastSeg}`)) {
+        scored.push({ ind: m, score: 1500 - Math.abs(label.length - tLc.length) });
+      }
+    }
+  } else {
+    const termComps = componentSet(t);
+    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 });
     }
-    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) {
@@ -403,22 +731,75 @@ export function resolveObject(graph, term) {
   }
 
   // tier 4: prose-index fallback (PLAN_PROSE_INDEX.md §6) — see the function doc above.
-  const proseHits = lookupByProseTokens(graph.proseIndex, t);
+  // The typeof guard is the same viewer-bundle boundary as defaultNlp(): viz.mjs's
+  // askSource strips the prose.mjs import but does not inline prose.mjs, so in the
+  // browser `lookupByProseTokens` is an undeclared identifier — without the guard,
+  // ANY term reaching this tier threw a ReferenceError in the page instead of
+  // rendering the honest miss (a real, previously-untested viewer bug).
+  // DOTTED terms never consult prose: "res.json" word-matches test/res.json.js's
+  // own path tokens, which is the tier-3 phantom-path bug reappearing through a
+  // side door — a dotted term names an identifier, and identifiers resolve by
+  // label (tiers above) or the bounded fuzzy pass below, or they honestly miss.
+  let proseResult = null;
+  const proseHits = !dotted && typeof lookupByProseTokens === "function" ? 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 {
+      proseResult = {
         match: bestInd,
         candidates: rest.slice(0, 4).map((h) => graph.byId.get(h.id)).filter(Boolean),
         tier: 4,
         ambiguous: tied.length > 0,
         matchedVia: "prose",
       };
+      // A UNIQUE SEMANTIC prose hit stands — fuzzy is never consulted (lower
+      // tiers fire only on a miss). Two prose outcomes yield to tier 5 instead:
+      // (a) an AMBIGUOUS tie — a typo'd identifier ("bulidContextBundle") often
+      // word-overlaps several symbols' prose tokens at the same score while its
+      // 1-edit NAME match is unique; (b) a hit that only exists because the
+      // prose SPELL layer corrected the query token (via:"spell") — the same
+      // typo tier 5 resolves with stronger (name) evidence and announces out
+      // loud, exactly the division of labour prose.mjs's own spell-layer
+      // comment specifies. If tier 5 cannot resolve uniquely either, the
+      // stashed prose result is surfaced as-is.
+      if (!proseResult.ambiguous && best.via !== "spell") return proseResult;
     }
   }
-  return { match: null, candidates: [], tier: null, ambiguous: false };
+
+  // tier 5: bounded fuzzy (see the function doc) — every exact tier above missed
+  // (or tier 4 tied), so a typo'd identifier gets one honest chance against labels
+  // and their components. sha-shaped terms never reach here (guard above);
+  // sub-4-char terms are excluded because a 1-edit budget on 3 chars matches far
+  // too much to ever be a unique intent.
+  if (!shaTerm && tLc.length >= 4) {
+    const bound = fuzzyBound(tLc);
+    let best = bound + 1;
+    let hits = [];
+    for (const m of pool) {
+      let d = editDistance(String(m.label || "").toLowerCase(), tLc, bound);
+      if (d > 0) {
+        for (const comp of componentSet(m.label)) {
+          if (d <= 0) break;
+          d = Math.min(d, editDistance(comp, tLc, bound));
+        }
+      }
+      if (d < best) { best = d; hits = [m]; }
+      else if (d === best && d <= bound) hits.push(m);
+    }
+    if (best <= bound && hits.length === 1) {
+      return { match: hits[0], candidates: [], tier: 5, ambiguous: false, matchedVia: "fuzzy" };
+    }
+    if (best <= bound && hits.length > 1 && !proseResult) {
+      // equidistant fuzzy tie with no prose evidence either — honest ambiguity.
+      const [bestInd, ...rest] = hits;
+      return { match: bestInd, candidates: rest.slice(0, 4), tier: 5, ambiguous: true, matchedVia: "fuzzy" };
+    }
+  }
+  // fuzzy couldn't resolve uniquely: surface the prose tie (when there was one)
+  // exactly as before, else the honest miss.
+  return proseResult || { match: null, candidates: [], tier: null, ambiguous: false };
 }
 
 /** Resolve a term that may be a context pronoun ("this"/"it"/"that"/"here") —
@@ -452,6 +833,35 @@ function refineToEntities(graph, moduleIds, entityType) {
   return out;
 }
 
+/** Everything a commit touched, across BOTH stored grains — touches (Commit->Module)
+ *  and touchesSymbol (Commit->fn/method/class) — narrowed by the asked entity type:
+ *  "modules"/"files" keeps the coarse grain only, a fine type keeps its own symbol
+ *  class only, and null/"Change" ("which changes touch commit X") keeps the union.
+ *  The result carries `commitSubject` so render() cites the commit and groups the
+ *  touched entities by class instead of pretending the commit was a search target. */
+function commitTouches(graph, commit, entityType, extra = {}) {
+  // "Commit" counts as wildcard here too: in "what was touched by commit X" the
+  // keyword-spotter consumes "commit" as the entity keyword though it belongs to
+  // the object noun phrase — and no commit ever touches another commit (no
+  // Commit->Commit edges exist), so honoring it as a class filter could only
+  // ever manufacture a false blank.
+  const wildcard = !entityType || entityType === "Change" || entityType === "Commit";
+  const wantCoarse = wildcard || entityType === "Module";
+  const wantFine = wildcard || FINE_ENTITY_TYPES.has(entityType);
+  const kinds = [...(wantCoarse ? ["touches"] : []), ...(wantFine ? ["touchesSymbol"] : [])];
+  let matches = kinds
+    .flatMap((k) => edgesOfKind(graph, k))
+    .filter((e) => e.subject === commit.id)
+    .map((e) => graph.byId.get(e.object))
+    .filter(Boolean);
+  if (entityType && FINE_ENTITY_TYPES.has(entityType)) matches = matches.filter((m) => m.class === entityType);
+  return {
+    matches, objMatch: commit, commitSubject: true, ambiguous: false, candidates: [],
+    traversal: `${kinds.join("+")} edges where subject = commit ${commit.label}`,
+    ...extra,
+  };
+}
+
 /** 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
@@ -504,6 +914,23 @@ export function traverse(graph, parsed, { contextId = null } = {}) {
     };
   }
 
+  // mentions: "where is X mentioned" (2026-07-02 query families) — the prose
+  // surface, not an edge traversal: list the individuals whose decomposed
+  // identifier / doc-comment tokens contain the term's words (the same index
+  // resolveObject's tier 4 consults, surfaced directly). The term itself is NOT
+  // resolved to an entity first — the question is about mentions of the words,
+  // which is exactly what the prose index stores. typeof guard: same viewer-
+  // bundle boundary as tier 4 (prose.mjs is never inlined).
+  if (shape === "mentions") {
+    const term = String(parsed.object || "").trim();
+    const hits = typeof lookupByProseTokens === "function" ? lookupByProseTokens(graph.proseIndex, term) : [];
+    const matches = hits.map((h) => graph.byId.get(h.id)).filter(Boolean);
+    return {
+      matches, objMatch: null, candidates: [], ambiguous: false, mentionsShape: true,
+      traversal: `proseIndex word lookup for "${term}"`,
+    };
+  }
+
   // §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,
@@ -525,10 +952,21 @@ export function traverse(graph, parsed, { contextId = null } = {}) {
         unresolvedPronoun: !!(subj.unresolvedPronoun || obj.unresolvedPronoun),
       };
     }
-    const edges = edgesOfKind(graph, kind).filter((e) => e.subject === subj.match.id && e.object === obj.match.id);
+    // touches edges are stored commit -> entity, so when the question names the
+    // commit on the OBJECT side ("was walk.mjs touched by commit X"), orient the
+    // edge test by where the commit actually is instead of failing on direction;
+    // a commit subject is also checked at the symbol grain ("does commit X touch
+    // <function>" lives on touchesSymbol, not the module-coarse kind).
+    let [from, to] = [subj.match, obj.match];
+    let kinds = kindsFor(kind); // "uses" checks the whole union ("does X use Y")
+    if (kind === "touches") {
+      if (to.class === "Commit" && from.class !== "Commit") [from, to] = [to, from];
+      if (from.class === "Commit") kinds = ["touches", "touchesSymbol"];
+    }
+    const edges = kinds.flatMap((k) => edgesOfKind(graph, k)).filter((e) => e.subject === from.id && e.object === to.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,
+      candidates: [], traversal: `${kinds.join("+")} edge from ${from.label} to ${to.label}`, ambiguous: false,
     };
   }
 
@@ -537,10 +975,61 @@ export function traverse(graph, parsed, { contextId = null } = {}) {
   const { match: objMatch, candidates, ambiguous, unresolvedPronoun, matchedVia } = resolveTermOrContext(graph, parsed.object, contextId);
   if (!objMatch) return { matches: [], objMatch: null, candidates, traversal: null, ambiguous: false, unresolvedPronoun };
 
+  // where: "where is X [defined]" (2026-07-02 query families) — the resolved
+  // entity IS the answer; render() reads its class + site attribute ("path:
+  // start[-end]", seon:startsAt) for the module/line citation.
+  if (shape === "where") {
+    const site = (objMatch.attributes || []).find((a) => a.key === "site")?.value || null;
+    return {
+      matches: [objMatch], objMatch, candidates, ambiguous, matchedVia, whereShape: true, site,
+      traversal: site ? `site attribute of ${objMatch.label}` : `class + defining module of ${objMatch.label}`,
+    };
+  }
+
+  // when: "when did X change" / "when was X last touched" (2026-07-02 query
+  // families) — the commits whose touch edges reach X, newest commit date first
+  // (mgx:commitDate, ISO-8601, so a lexical sort IS the date sort; undated
+  // commits sort last and render() says so honestly). Checked BEFORE the
+  // commit-as-subject flip: "when did <sha> change" asks for the commit's own
+  // date, not its touched files, so a Commit object answers with itself.
+  if (shape === "when") {
+    const dateOf = (c) => String((c.attributes || []).find((a) => a.key === "date")?.value || "");
+    let commits;
+    if (objMatch.class === "Commit") {
+      commits = [objMatch];
+    } else {
+      const edges = ["touches", "touchesSymbol"].flatMap((k) => edgesOfKind(graph, k)).filter((e) => e.object === objMatch.id);
+      const seen = new Set();
+      commits = [];
+      for (const e of edges) {
+        if (seen.has(e.subject)) continue;
+        seen.add(e.subject);
+        const c = graph.byId.get(e.subject);
+        if (c && c.class === "Commit") commits.push(c);
+      }
+      commits.sort((a, b) => dateOf(b).localeCompare(dateOf(a)));
+    }
+    return {
+      matches: commits, objMatch, candidates, ambiguous, matchedVia, whenShape: true,
+      traversal: `touches+touchesSymbol edges where object = ${objMatch.label}, newest commit date first`,
+    };
+  }
+
+  // commit-as-subject flip: touches edges are stored commit -> entity, so when the
+  // RESOLVED term of a touches question is itself a Commit — "which changes touch
+  // commit ef74e44e25c8" (reverse), "what did commit abc1234 touch" (forward),
+  // "what changed in abc1234" (casual reverse) — the honest reading is "what did
+  // that commit touch": read the edges FROM the commit, grain-selected by the asked
+  // entity type, instead of scanning for edges INTO it (a commit is never a touch
+  // target, so the un-flipped scan would render a misleading blank).
+  if (kind === "touches" && objMatch.class === "Commit") {
+    return commitTouches(graph, objMatch, entityType, { candidates, ambiguous, matchedVia });
+  }
+
   if (shape === "forward") {
-    const edges = edgesOfKind(graph, kind).filter((e) => e.subject === objMatch.id);
+    const edges = kindsFor(kind).flatMap((k) => edgesOfKind(graph, k)).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 };
+    return { matches, objMatch, candidates, traversal: `${kindsFor(kind).join("+")} edges where subject = ${objMatch.label}`, ambiguous, matchedVia };
   }
 
   // reverse + transitive (PLAN_MECHANICAL_CHAT.md P1): the gate above guarantees kind is
@@ -577,10 +1066,33 @@ export function traverse(graph, parsed, { contextId = null } = {}) {
   // 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 edges = kindsFor(kind).flatMap((k) => edgesOfKind(graph, k)).filter((e) => e.object === objMatch.id);
+  let extNote = "";
+  if (!edges.length && objMatch.class) {
+    // Unresolved ext:<Name> endpoints with the SAME name as the resolved entity:
+    // the extractor declined to assert identity (e.g. commander's every "class X
+    // extends Command" edge points at ext:Command, never the Class node), so a
+    // strict id match renders a FALSE blank. Count them by NAME instead and say
+    // so in the receipt — name-grade evidence, labeled as such, same standard as
+    // resolveObject's own ext: tier.
+    const extId = `ext:${String(objMatch.label).toLowerCase()}`;
+    edges = kindsFor(kind).flatMap((k) => edgesOfKind(graph, k)).filter((e) => String(e.object).toLowerCase() === extId);
+    if (edges.length) extNote = ` (by name, via unresolved ${extId} references)`;
+  }
+  // dedupe by id: a union kind ("uses") can reach the same subject through two
+  // legs (a module that both imports AND calls X), and one answer must list it once.
+  const subjects = [];
+  const seenSubjects = new Set();
+  for (const e of edges) {
+    const s = graph.byId.get(e.subject);
+    if (s && !seenSubjects.has(s.id)) { seenSubjects.add(s.id); subjects.push(s); }
+  }
   let matches, grainNote = "";
-  if (!entityType) {
+  // "Change" (ask-vocab.mjs's pseudo-type) is a wildcard here: "which changes touch
+  // walk.mjs" means the touch edges' own subjects — the commits — not a node class
+  // to filter by (no individual is ever class "Change", so filtering would always
+  // produce a false blank).
+  if (!entityType || entityType === "Change") {
     matches = subjects;
   } else {
     const direct = subjects.filter((s) => s.class === entityType);
@@ -594,7 +1106,7 @@ export function traverse(graph, parsed, { contextId = null } = {}) {
       matches = [];
     }
   }
-  return { matches, objMatch, candidates, traversal: `${kind} edges where object = ${objMatch.label}${grainNote}`, ambiguous, matchedVia };
+  return { matches, objMatch, candidates, traversal: `${kindsFor(kind).join("+")} edges where object = ${objMatch.label}${extNote}${grainNote}`, ambiguous, matchedVia };
 }
 
 // ---- §5 templated renderer — string interpolation + grouping/pluralization/overflow rules,
@@ -613,6 +1125,10 @@ function symbolLabelOf(ind) {
   return ["Function", "Method"].includes(ind.class) ? `function ${label}()` : label;
 }
 
+function listJoin(syms) {
+  return syms.length > 1 ? `${syms.slice(0, -1).join(", ")} and ${syms[syms.length - 1]}` : syms[0];
+}
+
 /** 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. */
@@ -623,8 +1139,19 @@ function describeParse(p) {
 }
 
 /** Render a compiled query result into {content, miss, ambiguous, matches?, candidates?}.
- *  Every branch is a template, not generation — §5's grouping/pluralization/overflow rules. */
+ *  Every branch is a template, not generation — §5's grouping/pluralization/overflow rules.
+ *  A tier-5 fuzzy object resolution is ANNOUNCED, not silent: the answer is prefixed
+ *  "assuming you meant <label>:" so the correction is on the record next to the result
+ *  (an unannounced fuzzy hit would be indistinguishable from an exact one — a guess). */
 export function render(parsed, result) {
+  const r = renderCore(parsed, result);
+  if (result && result.matchedVia === "fuzzy" && result.objMatch && !r.ambiguous) {
+    r.content = `assuming you meant ${result.objMatch.label}: ${r.content}`;
+  }
+  return r;
+}
+
+function renderCore(parsed, result) {
   if (!parsed) {
     return { content: `couldn't parse this as a graph question. Try: ${rephraseHint()}`, miss: true, ambiguous: false };
   }
@@ -658,18 +1185,113 @@ export function render(parsed, result) {
     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 };
   }
+  // mentions: the prose surface — checked before the generic objMatch-null miss
+  // below, because a mentions result deliberately carries no resolved object
+  // (the question is about the term's words, not a graph entity).
+  if (result.mentionsShape) {
+    if (!result.matches.length) {
+      return {
+        content: `"${parsed.object}" is not mentioned in any indexed identifier or doc-comment prose. (traversal: ${result.traversal})`,
+        miss: true, ambiguous: false,
+      };
+    }
+    const shown = result.matches.slice(0, OVERFLOW_CAP).map((m) => `${m.label} (${nounFor(m.class, 1)})`);
+    const extra = result.matches.length > OVERFLOW_CAP ? `, …and ${result.matches.length - OVERFLOW_CAP} more` : "";
+    return {
+      content: `"${parsed.object}" is mentioned in the prose tokens of ${listJoin(shown)}${extra}.`,
+      miss: false, ambiguous: false, matches: result.matches,
+    };
+  }
   if (!result.objMatch && (!result.candidates || result.candidates.length === 0) && parsed.shape !== "ask") {
+    // name what kind of thing was looked for: a sha-shaped term was checked against
+    // the commit namespace, a dotted slash-free term against symbol labels — a
+    // generic "no module matching" would misreport both.
+    const objText = String(parsed.object || "").trim();
+    const what = /^(?:commit[:\s])?[0-9a-f]{7,40}$/i.test(objText) ? "commit"
+      : (!objText.includes("/") && /^[\w$]+(\.[\w$]+)+$/.test(objText) ? "symbol" : "module");
     return {
-      content: `no module matching "${parsed.object}" found in the index.`,
+      content: `no ${what} matching "${parsed.object}" found in the index.`,
       miss: true, ambiguous: false, candidates: [],
     };
   }
   if (result.ambiguous) {
+    // the candidates say what KIND of thing is ambiguous — a shared commit-sha
+    // prefix must read "more than one commit", not "module".
+    const pool = [result.objMatch, ...(result.candidates || [])].filter(Boolean);
+    const noun = pool.length && pool.every((i) => i.class === "Commit") ? "commit" : "module";
     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),
+      content: `"${parsed.object}" matches more than one ${noun} ambiguously — please narrow the term.`,
+      miss: false, ambiguous: true, candidates: pool.map((i) => i.label),
     };
   }
+  // where: the resolved entity's own location, cited off the site attribute.
+  if (result.whereShape) {
+    const ind = result.objMatch;
+    if (ind.class === "Module") {
+      return { content: `${ind.label} is a module — the label is its repo path.`, miss: false, ambiguous: false, matches: result.matches };
+    }
+    if (ind.class === "Commit") {
+      return { content: `${ind.label} is a commit, not a code location — try "what did commit ${ind.label} touch".`, miss: true, ambiguous: false };
+    }
+    const m = String(result.site || "").match(/^(.*):(\d+)(?:-(\d+))?$/);
+    if (m) {
+      const lines = m[3] && m[3] !== m[2] ? `lines ${m[2]}-${m[3]}` : `line ${m[2]}`;
+      return { content: `${symbolLabelOf(ind)} is defined in ${m[1]} at ${lines}.`, miss: false, ambiguous: false, matches: result.matches };
+    }
+    return {
+      content: `${symbolLabelOf(ind)} is defined in ${moduleLabelOf(ind)} (no line span recorded in this index).`,
+      miss: false, ambiguous: false, matches: result.matches,
+    };
+  }
+  // when: newest touching commit + its date; undated commits are said out loud
+  // (honest miss with the precise re-index hint), never silently skipped.
+  if (result.whenShape) {
+    const subject = result.objMatch.label;
+    if (!result.matches.length) {
+      return { content: `no recorded commit touches ${subject} in this index. (traversal: ${result.traversal})`, miss: true, ambiguous: false };
+    }
+    const newest = result.matches[0];
+    const date = (newest.attributes || []).find((a) => a.key === "date")?.value || "";
+    if (!date) {
+      return {
+        content: `commit ${newest.label} touched ${subject}, but this index records no commit dates — re-index with a current seonix to attach mgx:commitDate.`,
+        miss: true, ambiguous: false,
+      };
+    }
+    const msg = (newest.attributes || []).find((a) => a.key === "message")?.value || "";
+    const day = String(date).slice(0, 10);
+    if (newest.id === result.objMatch.id) {
+      return { content: `commit ${newest.label} is dated ${day}${msg ? ` ("${msg}")` : ""}.`, miss: false, ambiguous: false, matches: result.matches };
+    }
+    const more = result.matches.length - 1;
+    return {
+      content: `${subject} was last touched by commit ${newest.label} on ${day}${msg ? ` ("${msg}")` : ""}${more ? `; ${more} earlier commit${more === 1 ? "" : "s"} recorded` : ""}.`,
+      miss: false, ambiguous: false, matches: result.matches,
+    };
+  }
+  // commit-as-subject answers ("which changes touch commit X", "what did commit X
+  // touch"): cite the commit, group the touched entities by CLASS — modules and
+  // symbols are different grains of the same answer, and flattening them into one
+  // undifferentiated list would hide which is which. Same OVERFLOW_CAP as the
+  // other list templates; zero hits is the standard honest blank, commit cited.
+  if (result.commitSubject) {
+    const cite = `commit ${result.objMatch.label}`;
+    if (!result.matches.length) {
+      return {
+        content: `${cite} touched nothing recorded in the index. (traversal: ${result.traversal})`,
+        miss: true, ambiguous: false,
+      };
+    }
+    const byClass = new Map();
+    for (const m of result.matches.slice(0, OVERFLOW_CAP)) {
+      const cls = m.class || "Module";
+      if (!byClass.has(cls)) byClass.set(cls, []);
+      byClass.get(cls).push(["Function", "Method"].includes(cls) ? `${m.label}()` : m.label);
+    }
+    const clauses = [...byClass.entries()].map(([cls, labels]) => `${nounFor(cls, labels.length)} ${listJoin(labels)}`);
+    const extra = result.matches.length > OVERFLOW_CAP ? `; …and ${result.matches.length - OVERFLOW_CAP} more` : "";
+    return { content: `${cite} touched ${clauses.join("; ")}${extra}.`, miss: false, ambiguous: false, matches: result.matches };
+  }
   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 };
@@ -701,8 +1323,10 @@ export function render(parsed, result) {
   // 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")) {
+  // meaningful when the matches are sub-module entities (functions/classes/etc) — a
+  // Commit list ("which commits touched X") has no containing module to group by, so
+  // anything that is not a fine entity takes the flat join.
+  if (parsed.shape === "forward" || parsed.entityType === "Module" || result.matches.every((m) => !FINE_ENTITY_TYPES.has(m.class))) {
     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 };
@@ -716,8 +1340,6 @@ export function render(parsed, result) {
     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}`;
@@ -731,11 +1353,14 @@ export function render(parsed, result) {
 /** 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);
+ *  a pronoun then produces an honest miss rather than a guess. `opts.nlp`
+ *  overrides the lemma/POS adapter (see parseQuery) — leave it undefined and
+ *  a Node process picks up wink automatically while the inlined viewer stays
+ *  adapter-less by construction. Returns the full {content, seonix_ask:
+ *  {mechanical,parsed,matches,traversal,miss,ambiguous,candidates?}} envelope
+ *  §6.2 specifies. Zero generative model calls. */
+export function ask(graph, query, { contextId = null, nlp = undefined } = {}) {
+  const parsed = parseQuery(query, { nlp });
   const result = traverse(graph, parsed, { contextId });
   const rendered = render(parsed, result);
   return {
@@ -749,12 +1374,11 @@ export function ask(graph, query, { contextId = null } = {}) {
       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.
+      // Confidence provenance: "prose" when resolveObject fell through to the tier-4
+      // prose-index fallback (PLAN_PROSE_INDEX.md §6 — matched what the symbol talks
+      // about, not its name); "fuzzy" when the tier-5 bounded-edit-distance pass
+      // resolved a typo'd term (the rendered content also announces it: "assuming you
+      // meant <label>"); null for every literal-identifier tier.
       matchedVia: result.matchedVia || null,
       ...(rendered.ambiguous ? { candidates: rendered.candidates } : {}),
     },