@polycode-projects/seonix 0.3.0 → 0.4.0

package/src/ask.mjs

@@ -41,6 +41,9 @@ import {
   CONTRACTIONS, MISSPELLINGS, WRONG_WORDS, G_DROP, FILLER_WORDS,
   CONTEXT_PRONOUNS, NEGATION_FRAMES, COMMIT_CONTENT_FRAMES, META_MEANING_VERBS,
   WHERE_MARKERS, MENTION_MARKERS,
+  RELATIVE_PRONOUNS, PLACEHOLDER_NOUNS, BOOLEAN_CONNECTIVES, QUALIFIERS,
+  AGGREGATE_TRIGGERS, SUPERLATIVE_EXTREMES, EDGE_NOUN_TO_METRIC, ANAPHORA_TRIGGERS,
+  MEMBERSHIP_KINDS, CASCADE_NOISE, CASCADE_SYNONYMS, HELP_TRIGGERS,
 } from "./ask-vocab.mjs";
 import { lookupByProseTokens } from "./prose.mjs";
 // The OPTIONAL Node-only wink-nlp adapter (lemma/POS tier). BOUNDARY: the inlined
@@ -588,6 +591,16 @@ export function parseQuery(query, { nlp = undefined } = {}) {
   if (!raw) return null;
   const text = applyNegationFrames(normalizeQuery(raw));
   if (!text) return null;
+  // COMPOSITIONAL PARSE PATH (PLAN §5.16 P3) — the new PRIMARY layer: a recursive
+  // descent over CLAUSES for the compositional shapes (nested/relative, boolean,
+  // qualifiers, aggregates, superlatives, anaphora). It fires ONLY when a
+  // compositional MARKER is present and returns null otherwise, so every plain
+  // clause falls straight through to the unchanged two-strategy merge below — the
+  // whole existing grammar is preserved bit-for-bit. When a marker IS present but
+  // the phrase cannot be compiled, it returns an honest {node:"miss"} rather than
+  // letting keyword-spot guess at a composition it never expressed.
+  const composite = parseComposite(text, adapter);
+  if (composite) return composite;
   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;
@@ -596,10 +609,586 @@ export function parseQuery(query, { nlp = undefined } = {}) {
   return { ambiguousParse: true, candidates: hits.map((h) => h.parsed) };
 }
 
+// ============================================================================
+// §compositional grammar (PLAN §5.16 P3) — the step up from ELIZA keyword-
+// spotting to a real recursive-descent grammar. Tokenize -> recursive-descent
+// parse to an AST of nodes -> compile to graph traversal. The AST node shapes
+// (all carry a `node` tag so traverse()/render() can branch without touching the
+// simple-clause path):
+//   {node:"clause",   clause}                    — a wrapped simple parse (the leaf)
+//   {node:"allOfClass", entityType}              — every individual of a class
+//   {node:"reverseSet"|"forwardSet", kind, entityType, inner}  — nested/relative:
+//        the OBJECT (reverse) / SUBJECT (forward) of the outer edge is the id-set
+//        produced by evaluating `inner` (another AST) — two-stage traversal.
+//   {node:"membership", entityType, term}        — "<entity> of/in <term>"
+//   {node:"qualifier", filters:[word…], inner}   — adjective post-filters on a set
+//   {node:"boolean", entityType, atoms:[{op,kind,ast|filters}…]}  — set algebra
+//        over the SAME subject (and/or/but-not); op ∈ seed/intersection/union/difference
+//   {node:"count", entityType, base}             — aggregate: |eval(base)|
+//   {node:"superlative", entityType, metric, metricNoun, extreme}  — rank by degree
+//   {node:"anaphora", mode, filter}              — over ask()'s `prev` id array
+//   {node:"miss", reason}                        — a compositional marker was seen
+//        but could not compile: an honest stated miss, never a guess.
+// The grammar COMPOSES the closed vocabulary (ask-vocab.mjs); it never opens it —
+// every leaf still resolves through the existing curated clause parser + tiered
+// resolveObject, so a term it can't resolve is still an honest object-miss.
+// ============================================================================
+
+// Depth cap on nesting (PLAN P3: "depth ≥2 nesting; guard against runaway with a
+// sane hop cap and an honest 'too deep to resolve' if exceeded").
+const MAX_COMPOSE_DEPTH = 4;
+// A resolvable-later placeholder object term for the OUTER clause of a nested
+// parse: the outer clause is parsed normally (so its verb/shape/grain classify),
+// then its `object` is discarded and replaced at eval time by the inner set. Chosen
+// to be plainly alphabetic (not a stopword, not vocabulary) so the clause parser
+// treats it as an ordinary object term rather than dropping it.
+const NEST_SENTINEL = "zzinnerset";
+// Filler words dropped at the front of a relative predicate / anaphora filter.
+const PRED_LEAD_SKIP = new Set(["that", "which", "who", "are", "is", "was", "were", "do", "does", "also", "still", "both", "and"]);
+const FRAME_WORDS = new Set(["which", "what", "who", "list", "show", "find", "give", "me", "us", "all"]);
+
+const splitWords = (text) => String(text).replace(/\?+\s*$/, "").replace(/,/g, " ").split(/\s+/).filter(Boolean);
+const entityNoun = (w) => (ENTITY_TO_TYPE[w] ? { entityType: ENTITY_TO_TYPE[w], placeholder: false }
+  : (PLACEHOLDER_NOUNS.includes(w) ? { entityType: null, placeholder: true } : null));
+const isGerundVerb = (w) => !!VERB_TO_KIND[w] && w.endsWith("ing");
+
+/** Run the two existing strategies on a FRAGMENT and return a single simple clause
+ *  (or null). Deterministic tie-break: on strategy disagreement the anchored parse
+ *  wins (STRATEGIES[0]) — a fragment fed from the composer is already shape-
+ *  constrained, so the merge's "surface an ambiguity" behavior isn't wanted here. */
+function parseSimpleClause(text, nlp) {
+  const hits = STRATEGIES.map((s) => s.parse(text, nlp)).filter(Boolean);
+  if (!hits.length) return null;
+  if (hits.length === 1) return hits[0];
+  return sameParse(hits[0], hits[1]) ? hits[0] : hits[0];
+}
+
+/** Top compositional dispatcher — first marker-matching production wins; a
+ *  production returns null (not this shape → fall through) or an AST node (which
+ *  may itself be {node:"miss"} when the marker was present but uncompilable). */
+function parseComposite(text, nlp) {
+  const w = splitWords(text);
+  const lc = w.map((x) => x.toLowerCase());
+  return parseAnaphora(w, lc, nlp)
+    || parseAggregate(w, lc, nlp)
+    || parseSuperlative(w, lc, nlp)
+    || parseNested(w, lc, nlp, 0)
+    || parseRelationalOrQualified(w, lc, nlp, 0);
+}
+
+/** A set-producing sub-expression (used for nested inner clauses, boolean branches,
+ *  and count restrictors): nested first, then the relational/qualifier/boolean
+ *  parser, then a bare simple clause. Carries `depth` for the nesting cap. */
+function parseSetPhrase(text, nlp, depth) {
+  if (depth > MAX_COMPOSE_DEPTH) return { node: "miss", reason: "too deep to resolve" };
+  const w = splitWords(text);
+  const lc = w.map((x) => x.toLowerCase());
+  const nested = parseNested(w, lc, nlp, depth);
+  if (nested) return nested;
+  const rel = parseRelationalOrQualified(w, lc, nlp, depth);
+  if (rel) return rel;
+  const clause = parseSimpleClause(text, nlp);
+  if (clause) return { node: "clause", clause };
+  return null;
+}
+
+/** NESTED / RELATIVE (object-position relative clause): "<outer verb> <placeholder
+ *  |entity> that <inner>" — the noun before "that" is the OBJECT of the outer edge,
+ *  constrained by the inner clause. Distinguished from a subject-relative ("functions
+ *  that call X", handled by parseRelationalOrQualified) by requiring a VERB before the
+ *  relative noun (i.e. the noun is not the leading subject). Returns a reverse/forward
+ *  Set node, an honest miss (marker present, uncompilable), or null (no object-relative
+ *  marker → let another production try). */
+function parseNested(w, lc, nlp, depth) {
+  for (let r = 1; r < lc.length; r += 1) {
+    if (!RELATIVE_PRONOUNS.includes(lc[r])) continue;
+    if (r + 1 >= lc.length) continue;               // nothing after "that"
+    const noun = entityNoun(lc[r - 1]);
+    if (!noun) continue;                            // "that" not preceded by a noun
+    const head = w.slice(0, r - 1);                 // outer clause words, minus the placeholder noun
+    if (!head.length) continue;                     // noun is the leading subject → subject-relative, not this shape
+    const outer = parseSimpleClause([...head, NEST_SENTINEL].join(" "), nlp);
+    if (!outer || (outer.shape !== "reverse" && outer.shape !== "forward")) continue;
+    if (outer.modifier && outer.modifier !== "direct") continue; // no transitive-over-set closure primitive
+    // build the inner sub-query: "which <placeholder-noun> <inner-text>" — recurses,
+    // so the inner may itself be nested/boolean/qualified (depth ≥2).
+    const innerText = `which ${lc[r - 1]} ${w.slice(r + 1).join(" ")}`;
+    const inner = parseSetPhrase(innerText, nlp, depth + 1);
+    if (!inner || inner.node === "miss") return inner ? { node: "miss", reason: inner.reason || "inner clause didn't parse" } : { node: "miss", reason: "inner clause didn't parse" };
+    return { node: outer.shape === "reverse" ? "reverseSet" : "forwardSet", kind: outer.kind, entityType: outer.entityType, inner };
+  }
+  return null;
+}
+
+/** ANAPHORA over the previous result set: "which of those/them <filter>", "how many
+ *  of those <filter>". Requires "of <pronoun>" (so a bare "those" in a term never
+ *  fires). Returns a {node:"anaphora"} (mode count|list), a miss (filter present but
+ *  uncompilable), or null. */
+function parseAnaphora(w, lc, nlp) {
+  let p = -1;
+  for (let i = 1; i < lc.length; i += 1) {
+    if (ANAPHORA_TRIGGERS.includes(lc[i]) && lc[i - 1] === "of") { p = i; break; }
+  }
+  if (p < 0) return null;
+  const head = lc.slice(0, p - 1).join(" ");
+  const mode = /^(how many|how much|count)\b/.test(head) ? "count" : "list";
+  const filter = parsePredicateFilter(w.slice(p + 1), nlp);
+  if (filter === undefined) return { node: "miss", reason: "the follow-up filter didn't parse" };
+  return { node: "anaphora", mode, filter };
+}
+
+/** Parse a trailing filter (for anaphora, and any "of those that …" tail) into
+ *  {type:"all"} | {type:"qual", filters} | {type:"clause", clause}. Returns
+ *  undefined when a non-empty filter cannot be compiled (an honest miss upstream). */
+function parsePredicateFilter(words, nlp) {
+  let i = 0;
+  const lc = words.map((x) => x.toLowerCase());
+  while (i < lc.length && PRED_LEAD_SKIP.has(lc[i])) i += 1;
+  const rest = words.slice(i);
+  const restLc = lc.slice(i);
+  if (!rest.length) return { type: "all" };
+  if (restLc.every((x) => QUALIFIERS[x])) return { type: "qual", filters: restLc };
+  const clause = parseSimpleClause(`what ${rest.join(" ")}`, nlp);
+  if (clause && (clause.shape === "reverse" || clause.shape === "forward") && clause.object) {
+    return { type: "clause", clause };
+  }
+  return undefined;
+}
+
+/** AGGREGATE / COUNT: "how many <entity> [<restrictor>]", "count <entity>",
+ *  "number of <entity> that …". A bare "how many classes" counts the class of
+ *  individuals; a restrictor tail counts a clause's result set. */
+function parseAggregate(w, lc, nlp) {
+  const trig = AGGREGATE_TRIGGERS.find((t) => lc.slice(0, t.split(" ").length).join(" ") === t);
+  if (!trig) return null;
+  let i = trig.split(" ").length;
+  while (i < lc.length && (lc[i] === "the" || lc[i] === "a" || lc[i] === "all")) i += 1;
+  const quals = [];
+  while (i < lc.length && QUALIFIERS[lc[i]]) { quals.push(lc[i]); i += 1; }
+  const noun = i < lc.length ? entityNoun(lc[i]) : null;
+  if (!noun) return { node: "miss", reason: "count needs a known entity kind (functions, classes, modules, …)" };
+  const entWord = lc[i];
+  i += 1;
+  const tail = w.slice(i);
+  let base;
+  if (tail.length) {
+    const setAst = parseSetPhrase(`which ${entWord} ${tail.join(" ")}`, nlp, 1);
+    if (!setAst || setAst.node === "miss") return { node: "miss", reason: "the count restrictor didn't parse" };
+    base = setAst;
+  } else {
+    base = { node: "allOfClass", entityType: noun.entityType };
+  }
+  if (quals.length) base = { node: "qualifier", filters: quals, inner: base };
+  return { node: "count", entityType: noun.entityType, base };
+}
+
+/** SUPERLATIVE: "which <entity> has the most/fewest <edge-noun>", "the most-connected
+ *  <entity>", "the largest <entity>". Ranks individuals of <entity> by a degree
+ *  metric over the classified edge groups. An unrecognized edge noun is an honest
+ *  miss naming the supported ones. */
+function parseSuperlative(w, lc, nlp) {
+  // extreme (single word, or "most connected" two-word)
+  let ext = null; let extIdx = -1;
+  for (let i = 0; i < lc.length; i += 1) {
+    const two = lc.slice(i, i + 2).join(" ");
+    if (SUPERLATIVE_EXTREMES[two]) { ext = SUPERLATIVE_EXTREMES[two]; extIdx = i; break; }
+    if (SUPERLATIVE_EXTREMES[lc[i]]) { ext = SUPERLATIVE_EXTREMES[lc[i]]; extIdx = i; break; }
+  }
+  if (!ext) return null;
+  // entity noun anywhere (first match, deterministic)
+  let entityType; let entWord = null;
+  for (const x of lc) { const n = entityNoun(x); if (n && !n.placeholder) { entityType = n.entityType; entWord = x; break; } }
+  if (!entWord) return { node: "miss", reason: "a superlative needs an entity kind (module, class, function, …)" };
+  // edge noun after the extreme (imports/callers/methods/…)
+  let metric = null; let metricNoun = null;
+  for (let i = extIdx; i < lc.length; i += 1) {
+    if (EDGE_NOUN_TO_METRIC[lc[i]]) { metric = EDGE_NOUN_TO_METRIC[lc[i]]; metricNoun = lc[i]; break; }
+  }
+  const connectivity = lc.includes("connected") || lc.slice(extIdx, extIdx + 2).join(" ") === "most connected"
+    || ["largest", "biggest", "smallest"].includes(lc[extIdx]);
+  if (!metric) {
+    if (connectivity) { metric = EDGE_NOUN_TO_METRIC.connections; metricNoun = "connections"; }
+    else return { node: "miss", reason: "name what to rank by (imports, callers, methods, tests, or connections)" };
+  }
+  return { node: "superlative", entityType, metric, metricNoun, extreme: ext };
+}
+
+/** RELATIONAL / BOOLEAN / QUALIFIER (subject-first): "[which] [<qualifier>…] <entity>
+ *  [that] <predicate>", where <predicate> is one or more relation clauses joined by
+ *  and/or/but-not over the SAME subject, a "<of|in> <term>" membership, or empty (a
+ *  bare qualified class). Fires ONLY on a compositional marker — a leading qualifier,
+ *  a relative pronoun, a gerund-led predicate, or a membership "of/in" — so a plain
+ *  reverse query ("which functions call helper") and the bare-template ambiguous case
+ *  ("which classes extends Base and couples to logging", no marker) both fall through
+ *  to the existing strategies untouched. Returns an AST node, a miss, or null. */
+function parseRelationalOrQualified(w, lc, nlp, depth) {
+  let i = 0;
+  while (i < lc.length && FRAME_WORDS.has(lc[i])) i += 1;
+  const framed = i > 0;
+  const quals = [];
+  while (i < lc.length && QUALIFIERS[lc[i]]) { quals.push(lc[i]); i += 1; }
+  const noun = i < lc.length ? entityNoun(lc[i]) : null;
+  if (!noun) {
+    // an unknown adjective sitting in the qualifier slot, right before a known
+    // entity noun ("which shiny methods", "static frobnicated functions") — an
+    // honest miss that NAMES the supported qualifiers, never a guess (PLAN P3).
+    // STOPWORDS are excluded so a normal question auxiliary in that position ("what
+    // DID commit X touch", "what WAS in <sha>") is left for the existing parser, not
+    // mistaken for an unknown qualifier.
+    if ((framed || quals.length) && i + 1 < lc.length && /^[a-z]+$/.test(lc[i])
+      && !VERB_TO_KIND[lc[i]] && !STOPWORDS.has(lc[i]) && entityNoun(lc[i + 1])) {
+      return { node: "miss", reason: `unknown qualifier "${lc[i]}" — supported: ${Object.keys(QUALIFIERS).join(", ")}` };
+    }
+    return null;                                   // no subject entity → not this shape
+  }
+  const entityType = noun.entityType;
+  const entWord = lc[i];
+  i += 1;
+  let predLc = lc.slice(i);
+  let predWords = w.slice(i);
+  let relFlag = false;
+  if (predLc.length && RELATIVE_PRONOUNS.includes(predLc[0])) { relFlag = true; predLc = predLc.slice(1); predWords = predWords.slice(1); }
+  const membershipLed = predLc[0] === "of" || predLc[0] === "in";
+  const gerundLed = predLc.length > 0 && isGerundVerb(predLc[0]);
+  // marker gate — the crux of backward-compat: without one of these, this is not a
+  // compositional query and we must NOT hijack it from the existing parser.
+  if (!(quals.length || relFlag || membershipLed || gerundLed)) return null;
+
+  // empty predicate → a bare qualified class ("public methods")
+  if (!predWords.length) {
+    let base = { node: "allOfClass", entityType };
+    if (!quals.length) return { node: "miss", reason: "nothing to filter or traverse" };
+    return { node: "qualifier", filters: quals, inner: base };
+  }
+
+  const subjPrefix = noun.placeholder ? "what" : `which ${entWord}`;
+  const { branches, ops } = splitBoolean(predLc, predWords);
+  // build one atom per branch, borrowing a leading verb phrase across bare branches
+  // ("importing X or Y" → the second branch inherits "importing").
+  let prevVerb = null;
+  const atoms = [];
+  for (let b = 0; b < branches.length; b += 1) {
+    const bw = branches[b];
+    const blc = bw.map((x) => x.toLowerCase());
+    const op = b === 0 ? "seed" : ops[b - 1];
+    if (bw.length && blc.every((x) => QUALIFIERS[x])) { atoms.push({ op, kind: "qual", filters: blc }); continue; }
+    if (blc[0] === "of" || blc[0] === "in") {
+      atoms.push({ op, kind: "set", ast: { node: "membership", entityType, term: bw.slice(1).join(" ") } });
+      continue;
+    }
+    let phrase = bw;
+    const vh = findPhrase(blc, VERB_TO_KIND);
+    if (vh) prevVerb = bw.slice(vh.start, vh.end);
+    else if (prevVerb) phrase = [...prevVerb, ...bw];
+    // a branch is a single predicate (top-level booleans are already split out), so
+    // parse it as nested-or-simple — NOT back through parseSetPhrase, which would
+    // re-detect the branch's own gerund/relative lead and recurse on identical text.
+    const ast = parseBranchAst(`${subjPrefix} ${phrase.join(" ")}`, nlp, depth + 1);
+    if (!ast || ast.node === "miss") return { node: "miss", reason: (ast && ast.reason) || "a clause in the combination didn't parse" };
+    atoms.push({ op, kind: "set", ast });
+  }
+  // the first atom must be a base set, not a bare qualifier (a qualifier needs
+  // something to filter). "public methods" already took the empty-predicate path above.
+  if (atoms[0].kind !== "set") return { node: "miss", reason: "start with a clause, then combine with and/or/but-not" };
+
+  let result;
+  if (atoms.length === 1) {
+    result = atoms[0].ast;
+  } else {
+    result = { node: "boolean", entityType, atoms };
+  }
+  if (quals.length) result = { node: "qualifier", filters: quals, inner: result };
+  return result;
+}
+
+/** Parse a single boolean branch (one predicate over the subject) into a set-AST:
+ *  nested (the branch has its own object-relative "that") or a plain simple clause.
+ *  Deliberately does NOT re-enter parseRelationalOrQualified — the branch has no
+ *  top-level boolean of its own (it was just split off one), so descending there
+ *  would only re-detect its gerund/relative lead and recurse on the same text. */
+function parseBranchAst(text, nlp, depth) {
+  if (depth > MAX_COMPOSE_DEPTH) return { node: "miss", reason: "too deep to resolve" };
+  const w = splitWords(text);
+  const lc = w.map((x) => x.toLowerCase());
+  const nested = parseNested(w, lc, nlp, depth);
+  if (nested) return nested;
+  const clause = parseSimpleClause(text, nlp);
+  return clause ? { node: "clause", clause } : null;
+}
+
+/** Split a predicate word array on boolean connectives (longest key first, so
+ *  "but not" beats a bare "not"). Returns {branches:[[word…]…], ops:[op…]} with
+ *  branches.length === ops.length + 1. */
+function splitBoolean(predLc, predWords) {
+  const conns = Object.keys(BOOLEAN_CONNECTIVES).sort((a, z) => z.split(" ").length - a.split(" ").length);
+  const branches = []; const ops = [];
+  let start = 0; let i = 0;
+  while (i < predLc.length) {
+    let hit = null;
+    for (const c of conns) {
+      const cw = c.split(" ");
+      if (predLc.slice(i, i + cw.length).join(" ") === c) { hit = { c, len: cw.length }; break; }
+    }
+    if (hit && i > start) {                        // a connective, and not at a branch start (avoid leading "and")
+      branches.push(predWords.slice(start, i));
+      ops.push(BOOLEAN_CONNECTIVES[hit.c]);
+      i += hit.len; start = i;
+    } else if (hit) { i += hit.len; start = i; }   // connective at branch start — skip it
+    else i += 1;
+  }
+  branches.push(predWords.slice(start));
+  return { branches, ops };
+}
+
+// ---- compositional EVALUATION — compile an AST to a graph traversal, reusing the
+// same primitives (edgesOfKind, resolveObject, refineToEntities, traverse) the
+// simple path uses. Pure given (graph, ast, opts). ----
+
+/** Reverse traversal over a SET of object ids (the nested "callers of {X…}" step) —
+ *  mirrors traverse()'s reverse general case (symbol-grain sibling + defines-refine),
+ *  but membership-tests e.object against a set instead of a single id. */
+function reverseOverSet(graph, kind, entityType, objectIds) {
+  const symbolKind = SYMBOL_GRAIN_SIBLING[kind];
+  if (symbolKind && FINE_ENTITY_TYPES.has(entityType)) {
+    const edges = edgesOfKind(graph, symbolKind).filter((e) => objectIds.has(e.object));
+    return uniqueById(edges.map((e) => graph.byId.get(e.subject)).filter((s) => s && s.class === entityType));
+  }
+  const edges = kindsFor(kind).flatMap((k) => edgesOfKind(graph, k)).filter((e) => objectIds.has(e.object));
+  const subjects = uniqueById(edges.map((e) => graph.byId.get(e.subject)).filter(Boolean));
+  if (!entityType || entityType === "Change") return subjects;
+  const direct = subjects.filter((s) => s.class === entityType);
+  if (direct.length) return direct;
+  if (entityType !== "Module" && subjects.some((s) => s.class === "Module")) {
+    return refineToEntities(graph, new Set(subjects.filter((s) => s.class === "Module").map((s) => s.id)), entityType);
+  }
+  return [];
+}
+
+/** Forward traversal over a SET of subject ids (the "things {X…} call/define" step). */
+function forwardOverSet(graph, kind, subjectIds) {
+  const edges = kindsFor(kind).flatMap((k) => edgesOfKind(graph, k)).filter((e) => subjectIds.has(e.subject));
+  return uniqueById(edges.map((e) => graph.byId.get(e.object)).filter(Boolean));
+}
+
+function uniqueById(inds) {
+  const seen = new Set(); const out = [];
+  for (const x of inds) if (x && !seen.has(x.id)) { seen.add(x.id); out.push(x); }
+  return out;
+}
+
+// Per-graph memo for the qualifier attribute/edge sets (exported symbols, tested
+// modules, symbol→module map) — computed once, so a qualifier filter over a large
+// result set stays cheap and deterministic.
+const qualCache = new WeakMap();
+function qualSets(graph) {
+  let c = qualCache.get(graph);
+  if (c) return c;
+  const exported = new Set();
+  for (const e of edgesOfKind(graph, "reexports")) {
+    exported.add(String(e.object).toLowerCase());
+    const ind = graph.byId.get(e.object);
+    if (ind) exported.add(String(ind.label).toLowerCase());
+  }
+  const testedModules = new Set(edgesOfKind(graph, "tests").map((e) => e.object));
+  const moduleOfSymbol = new Map();
+  for (const e of edgesOfKind(graph, "defines")) moduleOfSymbol.set(e.object, e.subject);
+  c = { exported, testedModules, moduleOfSymbol };
+  qualCache.set(graph, c);
+  return c;
+}
+function moduleIdOf(graph, ind) {
+  if (!ind) return null;
+  if (ind.class === "Module") return ind.id;
+  return qualSets(graph).moduleOfSymbol.get(ind.id) || null;
+}
+
+/** Does an individual satisfy one qualifier (spec from QUALIFIERS)? Reads only
+ *  attributes/edges the graph already carries — an unpopulated attribute (e.g.
+ *  isAbstract) simply yields false, an honest empty rather than an error. */
+function qualHolds(graph, ind, spec) {
+  if (!spec) return false;
+  switch (spec.via) {
+    case "visibility": {
+      const v = String((ind.attributes || []).find((a) => a.key === "visibility")?.value || "public").toLowerCase();
+      return v === spec.value;
+    }
+    case "attr":
+      return !!(ind.attributes || []).find((a) => a.key === spec.attr)?.value;
+    case "exported": {
+      const ex = qualSets(graph).exported;
+      return ex.has(String(ind.label).toLowerCase()) || ex.has(String(ind.id).toLowerCase());
+    }
+    case "tested": {
+      const mid = moduleIdOf(graph, ind);
+      return (!!mid && qualSets(graph).testedModules.has(mid)) === spec.value;
+    }
+    default: return false;
+  }
+}
+
+/** Compile a set-producing AST into an array of individuals. */
+function evalSet(graph, ast, opts) {
+  switch (ast.node) {
+    case "clause": return traverse(graph, ast.clause, opts).matches || [];
+    case "allOfClass": return graph.individuals.filter((i) => i.class === ast.entityType);
+    case "reverseSet": {
+      const ids = new Set(evalSet(graph, ast.inner, opts).map((i) => i.id));
+      return reverseOverSet(graph, ast.kind, ast.entityType, ids);
+    }
+    case "forwardSet": {
+      const ids = new Set(evalSet(graph, ast.inner, opts).map((i) => i.id));
+      return forwardOverSet(graph, ast.kind, ids);
+    }
+    case "membership": {
+      const r = resolveObject(graph, ast.term);
+      if (!r.match) return [];
+      const ids = new Set([r.match.id]);
+      const objs = uniqueById(MEMBERSHIP_KINDS.flatMap((k) => forwardOverSet(graph, k, ids)));
+      return ast.entityType ? objs.filter((o) => o.class === ast.entityType) : objs;
+    }
+    case "qualifier": {
+      const base = evalSet(graph, ast.inner, opts);
+      return base.filter((ind) => ast.filters.every((f) => qualHolds(graph, ind, QUALIFIERS[f])));
+    }
+    case "boolean": return evalBoolean(graph, ast, opts);
+    case "anaphora": return evalAnaphora(graph, ast, opts).matches;
+    default: return [];
+  }
+}
+
+/** Fold a boolean AST left-to-right into a result set. A qualifier atom acts as a
+ *  set filter on the accumulator (intersection keeps satisfiers, difference removes
+ *  them); a set atom contributes its own id-set for the op. */
+function evalBoolean(graph, ast, opts) {
+  let acc = [];
+  for (const atom of ast.atoms) {
+    if (atom.op === "seed") { acc = evalSet(graph, atom.ast, opts); continue; }
+    if (atom.kind === "qual") {
+      const holds = (ind) => atom.filters.every((f) => qualHolds(graph, ind, QUALIFIERS[f]));
+      acc = atom.op === "difference" ? acc.filter((i) => !holds(i)) : acc.filter((i) => holds(i));
+      continue;
+    }
+    const oids = new Set(evalSet(graph, atom.ast, opts).map((i) => i.id));
+    if (atom.op === "intersection") acc = acc.filter((i) => oids.has(i.id));
+    else if (atom.op === "difference") acc = acc.filter((i) => !oids.has(i.id));
+    else if (atom.op === "union") {
+      const seen = new Set(acc.map((i) => i.id));
+      for (const other of evalSet(graph, atom.ast, opts)) if (!seen.has(other.id)) { seen.add(other.id); acc.push(other); }
+    }
+  }
+  return acc;
+}
+
+/** Anaphora over ask()'s `prev` id array — filter/count the previous answer's ids.
+ *  No prev supplied → honest miss (never a guess), like an unresolved pronoun. */
+function evalAnaphora(graph, ast, opts) {
+  const prev = opts && opts.prev;
+  if (!Array.isArray(prev) || !prev.length) return { compositeMiss: true, reason: "no-prev", matches: [] };
+  let items = prev.map((id) => graph.byId.get(id)).filter(Boolean);
+  const f = ast.filter;
+  if (f && f.type === "qual") {
+    items = items.filter((ind) => f.filters.every((q) => qualHolds(graph, ind, QUALIFIERS[q])));
+  } else if (f && f.type === "clause") {
+    const r = resolveObject(graph, f.clause.object);
+    if (!r.match) items = [];
+    else {
+      // include the symbol-grain sibling so a fn->fn "call" filter tests callsSymbol,
+      // not just the module-coarse "calls" edge (mirrors traverse()'s reverse path).
+      const sib = SYMBOL_GRAIN_SIBLING[f.clause.kind];
+      const kinds = [...kindsFor(f.clause.kind), ...(sib ? [sib] : [])];
+      const ok = new Set(kinds.flatMap((k) => edgesOfKind(graph, k)).filter((e) => e.object === r.match.id).map((e) => e.subject));
+      items = items.filter((ind) => ok.has(ind.id));
+    }
+  }
+  // a count over a prior set names the entity kind when the survivors share a class.
+  const common = items.length && items.every((x) => x.class === items[0].class) ? items[0].class : null;
+  if (ast.mode === "count") return { compositeKind: "count", count: items.length, entityType: common, matches: [] };
+  return { compositeKind: "set", matches: items, entityType: common };
+}
+
+// Structural kinds counted for "most-connected" (total degree). Symbol-grain and
+// commit-history kinds are excluded so "connections" reads as the code-structure
+// degree a developer means, not every recorded touch.
+const DEGREE_KINDS = ["imports", "calls", "callsSymbol", "inherits", "contains", "tests"];
+/** Degree of an individual under a superlative metric ({kind, dir, sibling?, filter?}). */
+function degreeMetric(graph, ind, metric) {
+  const kinds = metric.kind === "*" ? DEGREE_KINDS : [metric.kind, ...(metric.sibling ? [metric.sibling] : [])];
+  let n = 0;
+  for (const k of kinds) for (const e of edgesOfKind(graph, k)) {
+    const out = e.subject === ind.id; const inc = e.object === ind.id;
+    if (metric.dir === "out" && out) {
+      if (metric.filter) { const o = graph.byId.get(e.object); if (!o || o.class !== metric.filter) continue; }
+      n += 1;
+    } else if (metric.dir === "in" && inc) n += 1;
+    else if (metric.dir === "both" && (out || inc)) n += 1;
+  }
+  return n;
+}
+function evalSuperlative(graph, ast) {
+  const pool = graph.individuals.filter((i) => i.class === ast.entityType);
+  const scored = pool.map((ind) => ({ ind, score: degreeMetric(graph, ind, ast.metric) }))
+    .sort((a, z) => (ast.extreme === "most" ? z.score - a.score : a.score - z.score));
+  if (!scored.length) return { compositeKind: "superlative", entityType: ast.entityType, matches: [] };
+  const best = scored[0].score;
+  const winners = scored.filter((s) => s.score === best).map((s) => s.ind);
+  return { compositeKind: "superlative", entityType: ast.entityType, metricNoun: ast.metricNoun, extreme: ast.extreme, score: best, matches: winners };
+}
+
+/** Compile any compositional AST to a result object traverse() returns for the
+ *  simple path — {matches, …} plus compositeKind/compositeMiss flags render() reads. */
+export function evalComposite(graph, ast, opts = {}) {
+  if (ast.node === "miss") return { compositeMiss: true, reason: ast.reason || null, matches: [] };
+  if (ast.node === "count") return { compositeKind: "count", count: evalSet(graph, ast.base, opts).length, entityType: ast.entityType, matches: [] };
+  if (ast.node === "superlative") return evalSuperlative(graph, ast);
+  if (ast.node === "anaphora") return evalAnaphora(graph, ast, opts);
+  return { compositeKind: "set", matches: evalSet(graph, ast, opts), entityType: ast.entityType || null };
+}
+
+// ---- compositional RENDER — templated, same "honest miss vs cited hit" discipline
+// as renderCore. ----
+
+const compositeList = (matches) => listJoin(matches.slice(0, OVERFLOW_CAP)
+  .map((m) => (["Function", "Method"].includes(m.class) ? `${m.label}()` : m.label)))
+  + (matches.length > OVERFLOW_CAP ? `, …and ${matches.length - OVERFLOW_CAP} more` : "");
+
+/** A compositional worked example for the rephrase hint (§honest miss now shows a
+ *  compositional phrasing too). */
+export function compositionalHint() {
+  return 'compositional queries also work: "which functions call X and call Y", "what calls something that imports X", "public methods of X", "how many classes", "which module has the most imports", or (after a listing) "which of those are tested"';
+}
+
+function renderComposite(parsed, result) {
+  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 };
+    }
+    return { content: `couldn't compile this compositional question${result.reason ? ` (${result.reason})` : ""}. ${compositionalHint()}.`, miss: true, ambiguous: false };
+  }
+  if (result.compositeKind === "count") {
+    const noun = result.entityType ? nounFor(result.entityType, result.count) : (result.count === 1 ? "result" : "results");
+    return { content: `${result.count} ${noun}.`, miss: false, ambiguous: false, matches: [] };
+  }
+  if (result.compositeKind === "superlative") {
+    if (!result.matches.length) return { content: `no ${nounFor(result.entityType, 2)} to rank in this index.`, miss: true, ambiguous: false };
+    const lead = result.extreme === "most" ? "the most" : "the fewest";
+    const tie = result.matches.length > 1 ? ` (${result.matches.length}-way tie)` : "";
+    return {
+      content: `${compositeList(result.matches)} — ${lead} ${result.metricNoun} (${result.score})${tie}.`,
+      miss: false, ambiguous: false, matches: result.matches,
+    };
+  }
+  // set-producing
+  if (!result.matches.length) {
+    return { content: `nothing in the index matches that${result.entityType ? ` (${nounFor(result.entityType, 2)})` : ""}.`, miss: true, ambiguous: false, matches: [] };
+  }
+  return { content: `${compositeList(result.matches)}.`, miss: false, ambiguous: false, matches: result.matches };
+}
+
 /** 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|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)';
+  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). '
+    + compositionalHint();
 }
 
 // ---- §4 object-term resolution — mechanical, no embeddings, tiered, stop at first hit ----
@@ -888,8 +1477,13 @@ const TRANSITIVE_MAX_DEPTH = 8;
  *  needed one. Returns {matches, objMatch, candidates, traversal, ambiguous,
  *  answer?, unresolvedPronoun?} — `answer` only set for the "ask" shape.
  *  `matches` is always an array of individuals (or edge records for "ask"). */
-export function traverse(graph, parsed, { contextId = null } = {}) {
-  if (!parsed || parsed.ambiguousParse) return { matches: [], objMatch: null, candidates: [], traversal: null, ambiguous: false };
+export function traverse(graph, parsed, { contextId = null, prev = null } = {}) {
+  if (!parsed) return { matches: [], objMatch: null, candidates: [], traversal: null, ambiguous: false };
+  // compositional AST (PLAN §5.16 P3) — the new grammar's nodes carry a `node` tag;
+  // everything else (simple clauses, ambiguousParse) flows through the original path
+  // below completely unchanged.
+  if (parsed.node) return evalComposite(graph, parsed, { contextId, prev });
+  if (parsed.ambiguousParse) return { matches: [], objMatch: null, candidates: [], traversal: null, ambiguous: false };
   const { shape, kind, entityType } = parsed;
 
   // meta: a question about the graph's OWN vocabulary ("what does cochange mean", "what
@@ -1155,6 +1749,7 @@ function renderCore(parsed, result) {
   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.ambiguousParse) {
     const options = parsed.candidates.map((p, i) => `${i + 1}) ${describeParse(p)}`).join(" or ");
     return {
@@ -1348,6 +1943,192 @@ function renderCore(parsed, result) {
   return { content: clauses.join(" and ") + extra + ".", miss: false, ambiguous: false, matches: result.matches };
 }
 
+// ============================================================================
+// §progressive-relaxation cascade (SHRDLU in a code graph, with a Zork parser's
+// forgiveness) — a controlled loop that wraps the WHOLE existing parse and runs
+// ONLY when the direct parse of the normalized query would MISS. A clean direct hit
+// never enters the cascade (it stays instant and exact); the cascade only ever DROPS
+// noise/unmatched words or NORMALISES a near-canonical word to the closed vocabulary,
+// re-attempting the full parse (compositional + templates + keyword-spot) after each
+// transform, and bottoms out in the SAME honest miss + rephrase hint the engine
+// already returned — never inventing a term or guessing an entity. Deterministic:
+// same input → same cascade path. All of it is plain JS over the already-imported
+// tables + resolveObject/parseQuery, so it survives the viewer bundle's import strip.
+// ============================================================================
+
+const wordsOf = (arr) => arr.flatMap((p) => String(p).toLowerCase().split(" "));
+
+/** Every token the CLOSED grammar gives QUERY MEANING to — relation verbs, entity
+ *  nouns, modifiers, qualifiers, aggregate/superlative triggers, edge-degree nouns,
+ *  boolean connectives, placeholder nouns, anaphora/meta/where/mention markers,
+ *  relative pronouns, and the small synonym keys. The noise-strip pass will NEVER
+ *  remove one of these, and the drop-unmatched pass always keeps them: they carry the
+ *  intent, only the packaging around them is negotiable. */
+const CONTENT_VOCAB = new Set([
+  ...wordsOf(Object.keys(VERB_TO_KIND)), ...wordsOf(Object.keys(ENTITY_TO_TYPE)),
+  ...wordsOf(Object.keys(MODIFIER_TO_KIND)), ...wordsOf(Object.keys(QUALIFIERS)),
+  ...wordsOf(AGGREGATE_TRIGGERS), ...wordsOf(Object.keys(SUPERLATIVE_EXTREMES)),
+  ...wordsOf(Object.keys(EDGE_NOUN_TO_METRIC)), ...wordsOf(Object.keys(BOOLEAN_CONNECTIVES)),
+  ...wordsOf(PLACEHOLDER_NOUNS), ...wordsOf(ANAPHORA_TRIGGERS), ...wordsOf(META_MEANING_VERBS),
+  ...wordsOf(WHERE_MARKERS), ...wordsOf(MENTION_MARKERS), ...wordsOf(RELATIVE_PRONOUNS),
+  ...wordsOf(Object.keys(CASCADE_SYNONYMS)),
+]);
+
+/** Structural scaffolding words — question words, articles-in-questions, frame verbs,
+ *  and context pronouns. Not "content", but they hold a sentence together, so the
+ *  drop-unmatched pass keeps them (dropping "what"/"of" would corrupt the grammar);
+ *  the noise-strip pass may still remove the few of these that are ALSO curated noise
+ *  ("the"/"a"/"show"/"me") — the two sets overlap on purpose. */
+const STRUCTURAL_WORDS = new Set([...STOPWORDS, ...FRAME_WORDS, ...CONTEXT_PRONOUNS]);
+const CASCADE_NOISE_SET = new Set(wordsOf(CASCADE_NOISE));
+
+/** Is `parsed` a genuinely ANSWERABLE query — one that both parsed AND (for the simple
+ *  clauses) resolves its named term(s) to a graph entity? A composite non-miss node,
+ *  an ambiguous parse, and a meta/mentions surface all count; an unresolved-context
+ *  pronoun is its OWN specific honest miss (kept, not relaxed). Returns:
+ *    true       — a real, executable answer (even if it later renders an empty set / "No")
+ *    "ambiguous"/"pronoun" — a specific outcome to keep, distinct from relaxable
+ *    false      — no parse at all, a compositional {node:"miss"}, or an unresolved term
+ *  ask() starts the cascade ONLY on `false`, and accepts a relaxed attempt ONLY on the
+ *  strict `true` (so the cascade can never "rescue" a query into another kind of miss). */
+function answerable(graph, parsed, contextId) {
+  if (!parsed) return false;
+  if (parsed.ambiguousParse) return "ambiguous";
+  if (parsed.node) return parsed.node !== "miss";
+  if (parsed.shape === "meta" || parsed.shape === "mentions") return true;
+  const o = resolveTermOrContext(graph, parsed.object, contextId);
+  if (o.unresolvedPronoun) return "pronoun";
+  if (!o.match) return false;
+  if (parsed.shape === "ask") {
+    const s = resolveTermOrContext(graph, parsed.subject, contextId);
+    if (s.unresolvedPronoun) return "pronoun";
+    return s.match ? true : false;
+  }
+  return true;
+}
+
+/** Whole-query help/orientation request → show the hint directly (never the relaxation
+ *  loop, never a pretend answer). Matches only when the ENTIRE normalized query is a
+ *  curated HELP_TRIGGER, so a symbol named "help" in a real question is untouched. */
+function isHelpRequest(query) {
+  const q = String(query || "").trim().toLowerCase().replace(/[?.!\s]+$/, "");
+  return HELP_TRIGGERS.includes(q);
+}
+
+/** The relaxation cascade. Given a query whose direct parse MISSED, walk three
+ *  increasingly-permissive layers, re-attempting the full parse after each transform,
+ *  and return the FIRST attempt that yields an answerable parse (with a trace of what
+ *  it did) — or null if none does (caller then falls back to the original honest miss):
+ *    1. NOISE-STRIP    — remove one curated noise token (leftmost) at a time, never one
+ *                        that is content vocab or resolves to an entity, re-parsing each
+ *                        time, until a parse answers or no noise tokens remain.
+ *    2. DROP-UNMATCHED — drop the plain-lowercase words that are NEITHER grammar NOR a
+ *                        resolvable entity (an unknown "frobnicate"); identifier-shaped
+ *                        tokens (dotted files, shas, CamelCase) are never dropped —
+ *                        they are content that may honestly fail to resolve.
+ *    3. SYNONYM        — rewrite surviving near-canonical words to the closed vocab.
+ *  Bounded (one token removed per noise iteration; hard guard) and deterministic. */
+export function relaxParse(graph, query, { nlp = undefined, contextId = null, prev = null } = {}) {
+  const from = applyNegationFrames(normalizeQuery(String(query || "")));
+  let tokens = splitWords(from);
+  if (!tokens.length) return null;
+  const dropped = [];
+  const steps = [];
+
+  // Two literal-resolution guards (never the fuzzy/prose tiers, whose loose near-
+  // matches would let a noise word masquerade as an entity):
+  //  · resolvesExact  — EXACT label/id or ext: match only (tier ≤ 2). Used to protect a
+  //    curated NOISE word from being stripped: only a token that literally NAMES an
+  //    entity ("a module called `the`") is safe-listed. A mere substring coincidence
+  //    ("me" ⊂ "Method", tier 3) must NOT block stripping a genuine filler word.
+  //  · resolvesLiteral — exact/ext/substring/component (tier ≤ 3). Used to KEEP an
+  //    identifier-shaped content token ("logging" ⊂ "src/logging.mjs") through the
+  //    drop-unmatched pass, and to hold a synonym rewrite off a real entity name.
+  const resolvesExact = (t) => {
+    const r = resolveObject(graph, t);
+    return !!r.match && r.tier != null && r.tier <= 2;
+  };
+  const resolvesLiteral = (t) => {
+    const r = resolveObject(graph, t);
+    return !!r.match && r.tier != null && r.tier <= 3;
+  };
+  // Does a term string carry at least one REAL word — one the grammar doesn't already
+  // own as vocabulary/scaffolding? Guards against a relaxation that drops the actual
+  // asked term and lets a bare marker slide into its place ("where is [X] defined" →
+  // "where is defined", "defined" is a WHERE_MARKER, never the thing being located).
+  const hasRealTerm = (s) => splitWords(String(s || "")).some((w) => {
+    const lc = w.toLowerCase();
+    return !CONTENT_VOCAB.has(lc) && !STRUCTURAL_WORDS.has(lc);
+  });
+  // Accept a relaxed attempt ONLY if it is a genuinely answerable parse (terms resolve)
+  // AND it renders a REAL positive answer — never another empty/miss (relaxation earns a
+  // win only by turning a miss into an answer, never a differently-worded miss) — and
+  // never by promoting a bare marker to the asked term.
+  const TERM_SHAPES = new Set(["reverse", "forward", "where", "when", "ask"]);
+  const attempt = (toks) => {
+    const text = toks.join(" ");
+    const p = parseQuery(text, { nlp });
+    if (answerable(graph, p, contextId) !== true) return null;
+    if (p && !p.node && TERM_SHAPES.has(p.shape)) {
+      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 }));
+    return rendered.miss ? null : { parsed: p, text };
+  };
+  const done = (hit) => ({ parsed: hit.parsed, from, to: hit.text, dropped: [...dropped], steps });
+
+  // Layer 1 — NOISE-STRIP (one lowest-value token at a time)
+  let guard = 0;
+  const hardCap = Math.max(tokens.length, 1) + 12;
+  for (; guard < hardCap; guard += 1) {
+    let idx = -1;
+    for (let i = 0; i < tokens.length; i += 1) {
+      const lc = tokens[i].toLowerCase();
+      if (CASCADE_NOISE_SET.has(lc) && !CONTENT_VOCAB.has(lc) && !resolvesExact(tokens[i])) { idx = i; break; }
+    }
+    if (idx < 0) break;
+    const removed = tokens[idx];
+    tokens = tokens.filter((_, i) => i !== idx);
+    dropped.push(removed);
+    steps.push(`strip noise "${removed}" → "${tokens.join(" ")}"`);
+    const hit = attempt(tokens);
+    if (hit) return done(hit);
+  }
+
+  // Layer 2 — DROP-UNMATCHED (plain-lowercase unknowns beside the real terms)
+  const survivors = [];
+  const nowDropped = [];
+  for (const t of tokens) {
+    const lc = t.toLowerCase();
+    const plain = /^[a-z]+$/.test(lc);
+    const keep = !plain || CONTENT_VOCAB.has(lc) || STRUCTURAL_WORDS.has(lc) || resolvesLiteral(t);
+    if (keep) survivors.push(t); else nowDropped.push(t);
+  }
+  if (nowDropped.length && survivors.length) {
+    tokens = survivors;
+    dropped.push(...nowDropped);
+    steps.push(`drop unmatched ${JSON.stringify(nowDropped)} → "${tokens.join(" ")}"`);
+    const hit = attempt(tokens);
+    if (hit) return done(hit);
+  }
+
+  // Layer 3 — SYNONYM-NORMALISE the survivors onto the canonical vocabulary
+  let changed = false;
+  const normed = tokens.map((t) => {
+    const lc = t.toLowerCase();
+    if (CASCADE_SYNONYMS[lc] && !resolvesLiteral(t)) { changed = true; return CASCADE_SYNONYMS[lc]; }
+    return t;
+  });
+  if (changed) {
+    steps.push(`normalise synonyms → "${normed.join(" ")}"`);
+    const hit = attempt(normed);
+    if (hit) return done(hit);
+  }
+
+  return null; // exhausted — the honest bottom of the cascade (caller keeps the original miss)
+}
+
 // ---- orchestration — the seonix_ask entry point (§6.3: parse -> resolve -> traverse -> render) ----
 
 /** Answer a free-text question over the graph, mechanically. `opts.contextId`
@@ -1356,15 +2137,45 @@ function renderCore(parsed, result) {
  *  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:
+ *  adapter-less by construction. `opts.prev` is the id array of the LAST answer's
+ *  matches — thread it from a chat loop so a follow-up anaphora question ("which of
+ *  those are tested", "how many of them call X") filters/counts the prior result
+ *  set; omit it and anaphora questions produce an honest "needs a previous answer"
+ *  miss. 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 });
+export function ask(graph, query, { contextId = null, nlp = undefined, prev = null } = {}) {
+  // Explicit help/orientation request → the rephrase hint directly (the honest bottom
+  // of the cascade, reached on demand), never a pretend answer or a relaxation attempt.
+  if (isHelpRequest(query)) {
+    return {
+      content: rephraseHint(),
+      seonix_ask: {
+        mechanical: true, parsed: null, matches: [], traversal: null,
+        miss: true, ambiguous: false, matchedVia: null, help: true, relaxed: null,
+      },
+    };
+  }
+  const direct = parseQuery(query, { nlp });
+  // The relaxation cascade fires ONLY when the DIRECT parse would miss (no parse, a
+  // compositional {node:"miss"}, or an unresolved named term) — a clean hit, an
+  // ambiguous parse, an unresolved-pronoun miss, and a real-but-empty answer all keep
+  // the direct parse untouched (a hit stays instant and exact).
+  let parsed = direct;
+  let relaxed = null;
+  if (answerable(graph, direct, contextId) === false) {
+    const r = relaxParse(graph, query, { nlp, contextId, prev });
+    if (r) { parsed = r.parsed; relaxed = { from: r.from, to: r.to, dropped: r.dropped, steps: r.steps }; }
+  }
+  const result = traverse(graph, parsed, { contextId, prev });
   const rendered = render(parsed, result);
+  // If relaxation materially rewrote the query and produced a real answer, note it
+  // lightly (terse, honest) so the reader knows how the question was read.
+  const content = (relaxed && !rendered.miss && relaxed.to !== relaxed.from)
+    ? `read as "${relaxed.to}" — ${rendered.content}`
+    : rendered.content;
   return {
-    content: rendered.content,
+    content,
     seonix_ask: {
       mechanical: true,
       parsed: (parsed && !parsed.ambiguousParse) ? parsed : null,
@@ -1374,6 +2185,11 @@ export function ask(graph, query, { contextId = null, nlp = undefined } = {}) {
       traversal: result.traversal || null,
       miss: !!rendered.miss,
       ambiguous: !!rendered.ambiguous,
+      // The relaxation trace: null when the direct parse was used as-is (a clean hit or
+      // an honest miss the cascade couldn't/shouldn't rescue), else what the cascade
+      // dropped/normalised to reach an answer. A caller can assert relaxed===null to
+      // prove the cascade never touched a direct hit.
+      relaxed,
       // 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