@polycode-projects/the-mechanical-code-talker 1.12.0 → 2.0.1

package/src/{ask.mjs → domain/ask.mjs}

@@ -16,16 +16,19 @@
 // (mgx:touchedByCommit / mgx:changeCoupledWith) — a different, simpler
 // question than temporal.mjs's time-scrubbing Chronograph surface.
 
-import { relationKind, impactClosure, normPath, HISTORY_CAP } from "./codegraph.mjs";
+import { relationKind, impactClosure, moduleCountOf, normPath, HISTORY_CAP } from "./codegraph.mjs";
 import {
+  RELATIONS,
   VERB_TO_KIND, ENTITY_TO_TYPE, MODIFIER_TO_KIND,
   CONTEXT_PRONOUNS, META_MEANING_VERBS,
   WHERE_MARKERS, MENTION_MARKERS,
   RELATIVE_PRONOUNS, PLACEHOLDER_NOUNS, BOOLEAN_CONNECTIVES, QUALIFIERS,
+  PASSIVE_PARTICIPLE_TO_KIND, GENERIC_AGENT_WORDS,
   AGGREGATE_TRIGGERS, LIST_TRIGGERS, SUPERLATIVE_EXTREMES, EDGE_NOUN_TO_METRIC, METRIC_IMPLIES_ENTITY, ANAPHORA_TRIGGERS,
   MEMBERSHIP_KINDS, CASCADE_NOISE, CASCADE_SYNONYMS, HELP_TRIGGERS,
+  stripTrailingScopeFiller,
 } from "./ask-vocab.mjs";
-import { normalizeQuery, applyNegationFrames, applyPhrasingFrames, matchNegationSet, STOPWORDS, splitWords, wordsOf } from "./interpret/normalize.mjs";
+import { expandContractions, normalizeQuery, applyNegationFrames, applyPhrasingFrames, matchNegationSet, STOPWORDS, splitWords, wordsOf } from "./interpret/normalize.mjs";
 import { editDistance, fuzzyBound } from "./interpret/fuzzy.mjs";
 import { parseAnchored } from "./interpret/strategies/grammar.mjs";
 import { parseKeywordSpot, findPhrase } from "./interpret/strategies/keywords.mjs";
@@ -36,7 +39,7 @@ import { pickPhrase } from "./answer-variants.mjs";
 
 // Normalization stays importable from its original site (tests + chat surface).
 export { normalizeQuery, applyNegationFrames };
-import { nlpAdapter } from "./ask-nlp.mjs";
+import { defaultNlp } from "./interpret/nlp-registry.mjs";
 
 // Per-graph, per-kind memo; a local copy of codegraph.mjs's private
 // edgesOfKind. Named differently from codegraph.mjs's own cache: the inlined
@@ -120,12 +123,6 @@ const LEADING_RELATION_VERB_RE = new RegExp(
   "i",
 );
 
-/** The default lemma/POS adapter: wink-nlp when Node has the optional deps
- *  installed, null otherwise. */
-function defaultNlp() {
-  return typeof nlpAdapter === "function" ? nlpAdapter() : null;
-}
-
 /** Compile a free-text question into {shape, kind, entityType, modifier,
  *  object[, subject]}, or null if no strategy fits. When strategies parse and
  *  disagree, returns {ambiguousParse: true, candidates: [...]}. `opts.nlp`
@@ -216,6 +213,7 @@ function parseComposite(text, nlp) {
   return parseExistence(w, lc)
     || parseQualifierCheck(w, lc)
     || parseNegation(text, nlp, 0)
+    || parseNegatedAsk(w, lc)
     || parseForwardNegation(w, lc, nlp)
     || parseTemporal(w, lc, nlp, 0)
     || parseCommitFilter(w, lc)
@@ -600,10 +598,28 @@ function parseExistence(w, lc) {
                // different (relationship) question; leave it for the parsers below.
 }
 
-/** Qualifier-check: "is <term> [a/an] <qualifier> [<kind>]?" — a single-entity
- *  yes/no property check ("is Task.title public"), the missing single-entity
- *  sibling of the qualifier post-filter over a set. Guarded off "is/are
- *  there …" (parseExistence's shape). */
+/** The "in <scope>" tail of a qualifier check ("is Task.title public in Task").
+ *  A tail naming the whole index restricts nothing, so TRAILING_SCOPE_FILLER —
+ *  the table the meta-whatis reader already strips with — takes "in this
+ *  codebase" off first and the check runs unscoped, exactly as it reads.
+ *  Returns {scope}, a miss node, or null when there's no "in" tail at all. */
+function parseQualifierScope(qualifier, tailWords) {
+  if (!tailWords.length) return null;
+  const withQualifier = `${qualifier} ${tailWords.join(" ")}`;
+  const tail = stripTrailingScopeFiller(withQualifier).slice(qualifier.length).trim();
+  const rest = splitWords(tail);
+  const inIdx = rest.findIndex((x) => x.toLowerCase() === "in");
+  if (inIdx < 0) return null;
+  const scope = rest.slice(inIdx + 1).join(" ").trim();
+  return scope ? { scope } : { node: "miss", reason: `"in" needs a scope afterward` };
+}
+
+/** Qualifier-check: "is <term> [a/an] <qualifier> [<kind>] [in <scope>]?" — a
+ *  single-entity yes/no property check ("is Task.title public"), the missing
+ *  single-entity sibling of the qualifier post-filter over a set. Guarded off
+ *  "is/are there …" (parseExistence's shape). An "in <scope>" tail rides the
+ *  parse and eval checks the term is really inside that scope, so
+ *  "is Task.title public in SomeOtherClass" can't answer off the term alone. */
 function parseQualifierCheck(w, lc) {
   if (lc[0] !== "is" && lc[0] !== "are") return null;
   if (lc[1] === "there") return null; // parseExistence's own shape
@@ -613,13 +629,46 @@ function parseQualifierCheck(w, lc) {
     if (QUALIFIERS[lc[i]]) { qualIdx = i; negated = lc[i - 1] === "not"; break; }
   }
   if (qualIdx < 0) return null; // no qualifier word at all → not this shape
+  // "is X tested by logger.mjs" asks about logger.mjs's own edges, not X's
+  // coverage property, so it declines here and reads as a passive instead. Two
+  // guards keep the decline narrow: the qualifier must have a relation
+  // counterpart ("is X public by Y" is not a sentence), and the agent must name
+  // something — "is X covered by tests" is still the plain coverage question.
+  const byIdx = lc.indexOf("by", qualIdx + 1);
+  if (byIdx > 0 && PASSIVE_PARTICIPLE_TO_KIND[lc[qualIdx]]) {
+    let agentIdx = byIdx + 1;
+    while (agentIdx < lc.length && (lc[agentIdx] === "the" || lc[agentIdx] === "a" || lc[agentIdx] === "an")) agentIdx += 1;
+    const agent = lc[agentIdx];
+    if (agent && !GENERIC_AGENT_WORDS.has(agent)) return null;
+  }
+  const tail = parseQualifierScope(lc[qualIdx], w.slice(qualIdx + 1));
+  if (tail?.node === "miss") return tail;
   let termStart = 1;
   if (lc[termStart] === "the") termStart += 1;
   let termEnd = negated ? qualIdx - 1 : qualIdx;
   if (termEnd > termStart && (lc[termEnd - 1] === "a" || lc[termEnd - 1] === "an")) termEnd -= 1;
   const term = termEnd > termStart ? w.slice(termStart, termEnd).join(" ").trim() : "";
   if (!term) return { node: "miss", reason: `"is/are <qualifier>" needs a named thing to check first` };
-  return { node: "qualCheck", term, qualifier: lc[qualIdx], negated };
+  return { node: "qualCheck", term, qualifier: lc[qualIdx], negated, scope: tail?.scope || null };
+}
+
+/** Negated polar: "does X not <verb> Y" — its positive twin's yes/no question
+ *  asked for the edge's ABSENCE. The sentence re-parses through the anchored
+ *  grammar with "not" dropped, and the `negated` flag rides the parse the same
+ *  way parseQualifierCheck's does: eval folds it into the answer and render
+ *  states whichever polarity holds.
+ *
+ *  It lives here rather than in the grammar because the strategy pipeline reads
+ *  the same sentence at positive polarity ("not" is no stopword) and the merge
+ *  would call the two readings an ambiguity. Declining to a composite production
+ *  is what keeps the sentence out of that merge. */
+function parseNegatedAsk(w, lc) {
+  if (lc[0] !== "do" && lc[0] !== "does" && lc[0] !== "did") return null;
+  const notIdx = lc.indexOf("not", 1);
+  if (notIdx < 0) return null;
+  const positive = parseAnchored(w.filter((_, i) => i !== notIdx).join(" "));
+  if (!positive || positive.shape !== "ask") return null;
+  return { ...positive, negated: true };
 }
 
 /** Trailing filler an aggregate/list tail can carry ("how many classes are
@@ -1698,14 +1747,38 @@ function evalExists(graph, ast) {
   return { compositeKind: "exists", entityType, term: null, scopeModule, scopeMatch, matches: pool };
 }
 
+/** Is `ind` inside a resolved qualifier-check scope? Read off the containment
+ *  the graph already carries: a directory or module scope matches the term's
+ *  own defining module, and a container scope (a class over its attributes and
+ *  methods) matches a MEMBERSHIP_KINDS edge. Anything the graph doesn't state
+ *  is not contained. */
+function withinScope(graph, ind, owner) {
+  const moduleId = moduleIdOf(graph, ind);
+  if (owner.kind === "dir") return owner.mods.some((m) => m.id === ind.id || m.id === moduleId);
+  return moduleId === owner.id || membershipOwnSet(graph, owner.id).some((o) => o.id === ind.id);
+}
+
 /** Qualifier-check eval: resolves the term (a context pronoun binds through
  *  contextId), then reads qualHolds(). `holds` means "the statement as asked
- *  is true" (negation already folded in). */
+ *  is true" (negation already folded in). An "in <scope>" tail is resolved and
+ *  checked first: the property is only reported for a term the scope really
+ *  contains, so the tail can never ride along unread. */
 function evalQualCheck(graph, ast, opts) {
-  const { term, qualifier, negated } = ast;
+  const { term, qualifier, negated, scope } = ast;
   const r = resolveTermOrContext(graph, term, opts.contextId);
   if (r.unresolvedPronoun) return { compositeKind: "qualCheck", qualCheckMiss: "pronoun", term, matches: [] };
   if (!r.match) return { compositeKind: "qualCheck", qualCheckMiss: "unresolved", term, matches: [] };
+  if (scope) {
+    const owner = resolveMembershipOwner(graph, scope, opts.contextId);
+    if (owner.kind === "miss") return { compositeKind: "qualCheck", qualCheckMiss: "scope", term, scope, matches: [] };
+    if (!withinScope(graph, r.match, owner)) {
+      return {
+        compositeKind: "qualCheck", qualCheckMiss: "outsideScope",
+        term, scope, subjectLabel: r.match.label,
+        scopeLabel: owner.kind === "dir" ? scope : owner.label, matches: [],
+      };
+    }
+  }
   const rawHolds = qualHolds(graph, r.match, QUALIFIERS[qualifier]);
   const holds = negated ? !rawHolds : rawHolds;
   return { compositeKind: "qualCheck", subject: r.match, qualifier, negated, holds, matches: [r.match] };
@@ -1768,7 +1841,7 @@ function describeFindHit(ind) {
   return mod && mod !== "(unknown module)" ? `${label} in ${mod}` : label;
 }
 
-function renderComposite(parsed, result) {
+function renderComposite(parsed, result, graph) {
   if (result.compositeMiss) {
     if (result.reason === "no-prev") {
       return { content: `"those"/"them" needs a previous answer to refer to — ask a listing question first, then follow up.`, miss: true, ambiguous: false };
@@ -1803,6 +1876,12 @@ function renderComposite(parsed, result) {
     if (result.qualCheckMiss === "unresolved") {
       return { content: `couldn't find "${result.term}" in the index to check.`, miss: true, ambiguous: false };
     }
+    if (result.qualCheckMiss === "scope") {
+      return { content: `couldn't find "${result.scope}" in the index to check inside.`, miss: true, ambiguous: false };
+    }
+    if (result.qualCheckMiss === "outsideScope") {
+      return { content: `No — ${result.subjectLabel} isn't in ${result.scopeLabel}.`, miss: true, ambiguous: false };
+    }
     const label = result.subject.label;
     const truePhrase = result.negated ? `not ${result.qualifier}` : result.qualifier;
     const falsePhrase = result.negated ? result.qualifier : `not ${result.qualifier}`;
@@ -1831,7 +1910,7 @@ function renderComposite(parsed, result) {
   // — inherited from <ancestor>: …"), never silently presented as the owner's own.
   if (result.compositeKind === "membership") {
     if (!result.matches.length) {
-      return { content: `nothing in the index matches that${result.entityType ? ` (${nounFor(result.entityType, 2)})` : ""}. ${touchesRephraseHint()}`, miss: true, ambiguous: false, matches: [] };
+      return { content: `nothing in the index matches that${result.entityType ? ` (${nounFor(result.entityType, 2)})` : ""}. ${touchesRephraseHint(graph)}`, miss: true, ambiguous: false, matches: [] };
     }
     if (result.inheritedNotOwn) {
       const kindPlural = nounFor(result.entityType, 2);
@@ -1923,10 +2002,10 @@ function renderComposite(parsed, result) {
     const setNoun = result.entityType ? nounFor(result.entityType, n || 2) : (n === 1 ? "entity" : "entities");
     const wasWere = n === 1 ? "was" : "were";
     if (!n) {
-      return { content: `nothing in the index matches the inner set, so there is no change history to date. ${touchesRephraseHint()}`, miss: true, ambiguous: false, matches: [] };
+      return { content: `nothing in the index matches the inner set, so there is no change history to date. ${touchesRephraseHint(graph)}`, miss: true, ambiguous: false, matches: [] };
     }
     if (!result.matches.length) {
-      return { content: `no recorded commit touched the ${n} ${setNoun} in that set in this index. ${touchesRephraseHint()}`, miss: true, ambiguous: false, matches: [] };
+      return { content: `no recorded commit touched the ${n} ${setNoun} in that set in this index. ${touchesRephraseHint(graph)}`, miss: true, ambiguous: false, matches: [] };
     }
     const newest = result.matches[0];
     const date = (newest.attributes || []).find((a) => a.key === "date")?.value || "";
@@ -1943,7 +2022,7 @@ function renderComposite(parsed, result) {
   }
   // set-producing
   if (!result.matches.length) {
-    return { content: `nothing in the index matches that${result.entityType ? ` (${nounFor(result.entityType, 2)})` : ""}. ${touchesRephraseHint()}`, miss: true, ambiguous: false, matches: [] };
+    return { content: `nothing in the index matches that${result.entityType ? ` (${nounFor(result.entityType, 2)})` : ""}. ${touchesRephraseHint(graph)}`, miss: true, ambiguous: false, matches: [] };
   }
   return { content: `${compositeList(result.matches)}.`, miss: false, ambiguous: false, matches: result.matches };
 }
@@ -1961,8 +2040,17 @@ export function rephraseHint() {
 /** A short, honest nudge for the touches/history-family of correct-but-
  *  unhelpful misses, pointing at "who touched X" / "/describe X" shapes that
  *  produce a real answer elsewhere. Reused verbatim by every miss template
- *  in this family. */
-export function touchesRephraseHint() {
+ *  in this family.
+ *
+ *  A graph with no modules holds no index to rephrase against, so the shapes
+ *  above would send the reader off to look up entities that cannot be there.
+ *  It gets a line that says what the store actually holds instead. A NULL
+ *  graph is UNKNOWN, not empty (see chat.mjs's noCodeGraph), so it keeps the
+ *  index-shaped advice. */
+export function touchesRephraseHint(graph = null) {
+  if (graph && moduleCountOf(graph) === 0) {
+    return "This store holds no code index, so it records no modules or commits to look through.";
+  }
   return 'Try "who touched <a module that actually has commits>" or "/describe <module>" to see what\'s in the index.';
 }
 
@@ -2057,6 +2145,28 @@ function resolveObjectCore(graph, term, { expectedClass = null } = {}) {
   }
   if (extId && !expectedClass) return { match: { id: extId, label: t, class: null }, candidates: [], tier: 2, ambiguous: false };
 
+  // "store.mjs and logger.mjs" names two operands, and every tier below reads a
+  // term as ONE. Tier 3's slashStem deliberately resolves past trailing junk, so
+  // the second operand is dropped and the first is answered about with full
+  // confidence: "is model.mjs called by store.mjs and logger.mjs" returns a flat
+  // Yes that is only ever about store.mjs. Nothing here reads coordination, so a
+  // miss is the answer.
+  //
+  // Gated on both sides resolving to DIFFERENT individuals on their own, which is
+  // what makes this a coordination rather than a name: a label that merely
+  // contains the word was already claimed by the exact tier above, and a side that
+  // resolves to nothing was never an operand. Neither part carries an " and " of
+  // its own, so the recursion is one level deep.
+  const andParts = t.split(/\s+and\s+/i).map((p) => p.trim()).filter(Boolean);
+  if (andParts.length > 1) {
+    const operandIds = new Set();
+    for (const part of andParts) {
+      const r = resolveObjectCore(graph, part, { expectedClass });
+      if (r.match && !r.ambiguous) operandIds.add(r.match.id);
+    }
+    if (operandIds.size > 1) return { match: null, candidates: [], tier: null, ambiguous: false };
+  }
+
   // Tier 3, two regimes: a dotted term with no slash ("res.json") is
   // symbol-shaped, so it matches only symbol labels or a module by exact
   // basename equality (never a phantom substring-of-path match); undotted/
@@ -2418,7 +2528,7 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
   if (parsed.ambiguousParse) {
     const branches = parsed.candidates.map((c) => {
       const branchResult = traverse(graph, c, { contextId, prev });
-      return { parsed: c, result: branchResult, rendered: render(c, branchResult) };
+      return { parsed: c, result: branchResult, rendered: render(c, branchResult, graph) };
     });
     return { matches: [], objMatch: null, candidates: parsed.candidates, traversal: null, ambiguous: true, branches };
   }
@@ -2502,14 +2612,16 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
     // touches edges are stored commit -> entity; orient by where the commit
     // actually is when it's named on the object side.
     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"];
-    }
+    if (kind === "touches" && to.class === "Commit" && from.class !== "Commit") [from, to] = [to, from];
+    // Both operands are named, so the yes/no wants the symbol-grain sibling
+    // unconditionally: a callsSymbol-only edge is still a real call, and reading
+    // the coarse kind alone answers No to a question the graph can answer Yes.
+    const sibling = SYMBOL_GRAIN_SIBLING[kind];
+    const kinds = [...new Set(sibling ? [...kindsFor(kind), sibling] : kindsFor(kind))];
     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,
+      matches: edges, answer: parsed.negated ? edges.length === 0 : edges.length > 0,
+      objMatch: obj.match, subjMatch: subj.match,
       candidates: [], traversal: `${kinds.join("+")} edge from ${from.label} to ${to.label}`, ambiguous: false,
     };
   }
@@ -2569,7 +2681,7 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
     const pool = uniqueById([objMatch, ...(candidates || [])]).slice(0, OVERFLOW_CAP);
     const branches = pool.map((c) => {
       const branchResult = traverse(graph, parsed, { contextId, prev, pinnedObjMatch: c });
-      return { candidate: c, result: branchResult, rendered: render(parsed, branchResult) };
+      return { candidate: c, result: branchResult, rendered: render(parsed, branchResult, graph) };
     });
     return { matches: [], objMatch, candidates, traversal: null, ambiguous: true, branches };
   }
@@ -2876,11 +2988,46 @@ function describeParse(p) {
   return `${ent}${p.kind} "${obj}"`;
 }
 
+/** The base verb form for a relation ("imports" -> "import"), for the frames
+ *  that need an infinitive. Unknown kinds fall back to the token itself rather
+ *  than being coerced into a guessed base form. */
+function bareVerbFor(kind) {
+  return RELATIONS[kind]?.bare || kind;
+}
+
+/** English gloss of a SET-COMPLEMENT AST — the shape parseNegation compiles
+ *  "which X do not <verb> Y" into (allOfClass DIFFERENCE the positive set).
+ *  Restates the question in the same grammar the positive canonical uses
+ *  ('modules that imports "store.mjs"'), so the negated and positive readings
+ *  of one question are told apart by reading the line, which is the whole point
+ *  of printing it. Returns null for any other boolean shape rather than
+ *  glossing it wrongly. */
+function complementGloss(parsed) {
+  // Exactly two atoms: a third would be silently dropped from the gloss,
+  // restating a narrower question than the one that was asked.
+  if (!Array.isArray(parsed.atoms) || parsed.atoms.length !== 2) return null;
+  const [seed, diff] = parsed.atoms;
+  if (seed.op !== "seed" || seed.ast?.node !== "allOfClass" || diff.op !== "difference") return null;
+  const noun = nounFor(parsed.entityType, 2);
+  if (diff.kind === "qual") return `${noun} that are not ${diff.filters.join(" and not ")}`;
+  if (diff.kind !== "set" || !diff.ast) return null;
+  if (diff.ast.node === "existsEdge") return `${noun} that do not ${bareVerbFor(diff.ast.kind)} anything`;
+  // The positive leg parseNegation differenced off the class: a single clause
+  // ("which modules do not import store.mjs") is the shape this gloss reads.
+  // Anything deeper is a nested composite and gets no gloss rather than a
+  // confidently wrong one.
+  const leaf = diff.ast.node === "clause" ? diff.ast.clause : diff.ast;
+  if (!leaf || leaf.node || !leaf.kind) return null;
+  const obj = leaf.object ?? leaf.subject;
+  if (obj == null) return null;
+  return `${noun} that do not ${bareVerbFor(leaf.kind)} ${JSON.stringify(String(obj))}`;
+}
+
 /** The canonical restatement of what a query was understood to mean: an
  *  English gloss (`english`) and a compact `shape(kind, args...)` notation
  *  (`machine`), both read off `parsed`'s already-compiled fields. A
- *  compositional AST gets a coarse fallback — per-node-type canonicalization
- *  isn't implemented yet. */
+ *  compositional AST with no gloss of its own falls back to naming its node
+ *  type — coarse, but never a wrong restatement. */
 function canonicalOf(parsed) {
   if (!parsed) return null;
   if (parsed.ambiguousParse) {
@@ -2890,11 +3037,16 @@ function canonicalOf(parsed) {
     };
   }
   if (parsed.node) {
-    return { english: `a compositional query (${parsed.node})`, machine: `composite(${parsed.node})` };
+    const gloss = parsed.node === "boolean" ? complementGloss(parsed) : null;
+    return {
+      english: gloss || `a compositional query (${parsed.node})`,
+      machine: `composite(${parsed.node})`,
+    };
   }
   const q = (s) => JSON.stringify(String(s ?? ""));
   const args = [];
   if (parsed.kind) args.push(parsed.kind);
+  if (parsed.negated) args.push("negated");
   if (parsed.entityType) args.push(`entityType=${parsed.entityType}`);
   if (parsed.modifier && parsed.modifier !== "direct") args.push(`modifier=${parsed.modifier}`);
   if (parsed.subject != null) args.push(`subject=${q(parsed.subject)}`);
@@ -2902,7 +3054,7 @@ function canonicalOf(parsed) {
   const machine = `${parsed.shape}(${args.join(", ")})`;
   let english;
   if (parsed.shape === "ask") {
-    english = `does "${parsed.subject}" ${verbFor(parsed.kind)} "${parsed.object}"?`;
+    english = `does "${parsed.subject}" ${parsed.negated ? "not " : ""}${verbFor(parsed.kind)} "${parsed.object}"?`;
   } else if (parsed.shape === "meta") {
     english = `what does "${parsed.object}" mean, in this graph's own vocabulary?`;
   } else if (parsed.shape === "mentions") {
@@ -2921,19 +3073,19 @@ function canonicalOf(parsed) {
 /** Render a compiled query result into {content, miss, ambiguous, matches?,
  *  candidates?}. A tier-5 fuzzy object resolution is announced, not silent:
  *  prefixed "assuming you meant <label>:" so the correction is on the record. */
-export function render(parsed, result) {
-  const r = renderCore(parsed, result);
+export function render(parsed, result, graph = null) {
+  const r = renderCore(parsed, result, graph);
   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) {
+function renderCore(parsed, result, graph) {
   if (!parsed) {
     return { content: `couldn't parse this as a graph question. Try: ${rephraseHint()}`, miss: true, ambiguous: false };
   }
-  if (parsed.node) return renderComposite(parsed, result);
+  if (parsed.node) return renderComposite(parsed, result, graph);
   if (parsed.ambiguousParse) {
     // Each branch was actually resolved in traverse() above (never guessed at) —
     // show every reading's real, effective answer, not just its one-line label, so
@@ -3060,7 +3212,7 @@ function renderCore(parsed, result) {
     const what = /^(?:commit[:\s])?[0-9a-f]{7,40}$/i.test(objText) ? "commit"
       : (!objText.includes("/") && /^[\w$]+(\.[\w$]+)+$/.test(objText) ? "symbol" : fallback);
     return {
-      content: `no ${what} matching "${parsed.object}" found in the index. ${touchesRephraseHint()}`,
+      content: `no ${what} matching "${parsed.object}" found in the index. ${touchesRephraseHint(graph)}`,
       miss: true, ambiguous: false, candidates: [],
     };
   }
@@ -3106,7 +3258,7 @@ function renderCore(parsed, result) {
   if (result.whenShape) {
     const subject = result.objMatch.label;
     if (!result.matches.length) {
-      return { content: `no recorded commit touches ${subject} in this index. ${touchesRephraseHint()}`, miss: true, ambiguous: false };
+      return { content: `no recorded commit touches ${subject} in this index. ${touchesRephraseHint(graph)}`, miss: true, ambiguous: false };
     }
     const newest = result.matches[0];
     const date = (newest.attributes || []).find((a) => a.key === "date")?.value || "";
@@ -3133,7 +3285,7 @@ function renderCore(parsed, result) {
   if (result.whoLastShape) {
     const subject = result.objMatch.label;
     if (!result.matches.length) {
-      return { content: `no recorded commit touches ${subject} in this index. ${touchesRephraseHint()}`, miss: true, ambiguous: false };
+      return { content: `no recorded commit touches ${subject} in this index. ${touchesRephraseHint(graph)}`, miss: true, ambiguous: false };
     }
     const newest = result.matches[0];
     const author = (newest.attributes || []).find((a) => a.key === "author")?.value;
@@ -3174,9 +3326,17 @@ function renderCore(parsed, result) {
     if (!result.objMatch || !result.subjMatch) {
       return { content: `couldn't resolve one of the terms in this question.`, miss: true, ambiguous: false };
     }
+    // The edge sentence and the no-edge sentence each state what the graph
+    // holds; the question's polarity only decides which one carries the Yes.
+    const edgeFound = `${result.traversal}.`;
+    const noEdge = `no ${parsed.kind} edge found from ${result.subjMatch.label} to ${result.objMatch.label}.`;
+    const holds = parsed.negated ? noEdge : edgeFound;
+    const fails = parsed.negated ? edgeFound : noEdge;
     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,
+      content: `${result.answer ? "Yes" : "No"} — ${result.answer ? holds : fails}`,
+      // A miss is the absence of a citation, which the polarity never changes:
+      // "no edge found" cites nothing whether it arrives as a Yes or a No.
+      miss: !result.matches.length, ambiguous: false,
     };
   }
   if (!result.matches.length) {
@@ -3201,7 +3361,7 @@ function renderCore(parsed, result) {
     }
     const entityWord = nounFor(parsed.entityType || "Module", 2);
     return {
-      content: `No ${entityWord} found whose module directly ${verbFor(parsed.kind)} ${parsed.object}. ${touchesRephraseHint()}`,
+      content: `No ${entityWord} found whose module directly ${verbFor(parsed.kind)} ${parsed.object}. ${touchesRephraseHint(graph)}`,
       miss: true, ambiguous: false,
     };
   }
@@ -3399,7 +3559,7 @@ export function relaxParse(graph, query, { nlp = undefined, contextId = null, pr
       if (p.object != null && !hasRealTerm(p.object)) return null;
       if (p.shape === "ask" && p.subject != null && !hasRealTerm(p.subject)) return null;
     }
-    const rendered = render(p, traverse(graph, p, { contextId, prev }));
+    const rendered = render(p, traverse(graph, p, { contextId, prev }), graph);
     return rendered.miss ? null : { parsed: p, text };
   };
   const done = (hit) => ({ parsed: hit.parsed, from, to: hit.text, dropped: [...dropped], steps });
@@ -3604,14 +3764,14 @@ export function ask(graph, query, { contextId = null, nlp = undefined, prev = nu
     if (r) { parsed = r.parsed; relaxed = { from: r.from, to: r.to, dropped: r.dropped, steps: r.steps }; }
   }
   let result = traverse(graph, parsed, { contextId, prev });
-  let rendered = render(parsed, result);
+  let rendered = render(parsed, result, graph);
   // Dynamic memory-graph class count/list fallback, only once everything
   // above already produced an honest miss.
   if (rendered.miss && !rendered.ambiguous) {
     const dyn = dynamicClassQuery(graph, query);
     if (dyn) {
       const dynResult = traverse(graph, dyn, { contextId, prev });
-      const dynRendered = render(dyn, dynResult);
+      const dynRendered = render(dyn, dynResult, graph);
       if (!dynRendered.miss) { parsed = dyn; result = dynResult; rendered = dynRendered; relaxed = null; }
     }
   }
@@ -3620,13 +3780,17 @@ export function ask(graph, query, { contextId = null, nlp = undefined, prev = nu
   // `!envelope.parsed`, so populating it here would steal turns from lanes
   // like moduleOrientLane ("what is X for"). Fires only once nothing else parsed.
   if (parsed === null && rendered.miss && !rendered.ambiguous) {
-    const bareM = String(query || "").trim().match(BARE_META_WHATIS_RE);
+    // The contraction is written out first, or "what's X" reads as a different
+    // question from "what is X" on the apostrophe alone. Only the contraction
+    // pass, never normalizeQuery's fuller one — the filler strip would let
+    // "please describe X"-shaped turns in through a lead they didn't type.
+    const bareM = expandContractions(String(query || "")).trim().match(BARE_META_WHATIS_RE);
     const bareTerm = bareM?.[1]?.trim();
     if (bareTerm && !/\s+(?:for|about)$/i.test(bareTerm)) {
       const bareParsed = parseQuery(`what is a ${bareTerm}`, { nlp });
       if (bareParsed?.shape === "meta") {
         result = traverse(graph, bareParsed, { contextId, prev });
-        rendered = render(bareParsed, result);
+        rendered = render(bareParsed, result, graph);
       }
     }
   }
@@ -3645,7 +3809,7 @@ export function ask(graph, query, { contextId = null, nlp = undefined, prev = nu
       const forParsed = parseQuery(`what is a ${forTerm}`, { nlp });
       if (forParsed?.shape === "meta") {
         const forResult = traverse(graph, forParsed, { contextId, prev });
-        const forRendered = render(forParsed, forResult);
+        const forRendered = render(forParsed, forResult, graph);
         if (!forRendered.miss && !forRendered.ambiguous) {
           result = forResult;
           rendered = forRendered;
@@ -3669,7 +3833,7 @@ export function ask(graph, query, { contextId = null, nlp = undefined, prev = nu
     const answered = directFull.alternates
       .map((a) => {
         const altResult = traverse(graph, a.parsed, { contextId, prev });
-        const altRendered = render(a.parsed, altResult);
+        const altRendered = render(a.parsed, altResult, graph);
         return altRendered.miss ? null : { a, text: altRendered.content };
       })
       .filter(Boolean);