@polycode-projects/seonix 0.4.0 → 0.5.0

package/bin/cli.mjs

@@ -81,7 +81,12 @@ async function runDigest(args) {
   let autoSelected = null; // for the header, when `query` drove selection
   if (!modules.length && args.query) {
     const graph = parseEntities(await source.fetchEntities(configFor(repoPath)));
-    const ranked = searchModulesRanked(graph, args.query);
+    // SHIPPED DEFAULT (0.5.0): the no-MCP digest's query-mode auto-locate resolves literal-mention ON
+    // (a fresh invocation with no seonix.toml), disable-able via `literal_mention:false`. Kept in
+    // lockstep with the `seonix_locate` handler so `cli digest '{query}'` ≡ `cli seonix_locate` for the
+    // same query. A strict no-op unless the query carries a ≥3-component dotted path / repo-relative
+    // path; searchModulesRanked derives rawQuery from the query when literalMention is on.
+    const ranked = searchModulesRanked(graph, args.query, { literalMention: args.literal_mention !== false });
     const scoreGapK = args.score_gap === false ? null : (Number.isFinite(args.score_gap) ? args.score_gap : DEFAULT_SCORE_GAP);
     modules = selectRankedModules(ranked, { top_k: Number.isFinite(args.top_k) ? args.top_k : 2, scoreGapK }).slice(0, DIGEST_MODULE_CAP);
     autoSelected = modules;
@@ -277,6 +282,18 @@ async function main() {
           implOfInterface: !!args.impl_of_interface, // E1b: C# impl-of-interface boost
           beamSearch: !!args.beam_search, // §5.15: multi-ply discriminative expansion
           ...(Number.isFinite(Number(args.beam_width)) ? { beamWidth: Number(args.beam_width) } : {}),
+          // B018 §8.1.3 literal-mention lever: match verbatim dotted-name/path mentions in the RAW
+          // query (which the locate tokenizer destroys). searchModulesRanked derives rawQuery from the
+          // query arg when literalMention is on; the rig passes the raw problem as the query, so literal
+          // matching keys off the untokenized text. raw_query is forwarded too for callers that normalize
+          // the query arg separately from the raw problem text.
+          // SHIPPED DEFAULT (0.5.0): literal-mention is ON for a fresh invocation (no arg, no
+          // seonix.toml) — pass `literal_mention:false` to disable. It is a strict no-op on queries
+          // with no ≥3-component dotted path / repo-relative path, so it never perturbs the cells the
+          // headline B018 numbers were measured on. The low-level scoreModules default (codegraph.mjs)
+          // stays literalMention=false; the product surface opts in explicitly, right here.
+          literalMention: args.literal_mention !== false,
+          ...(args.raw_query != null ? { rawQuery: String(args.raw_query) } : {}),
         });
         process.stdout.write(ranked.map((r) => `${r.path}\t${r.score}`).join("\n") + "\n");
       } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/seonix",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "type": "module",
   "description": "SEONIX — a deterministic, offline, $0 code-graph tool that makes a cheap coding agent edit like an expensive one. Indexes a repo with Python ast + git (zero model calls) and renders a bounded edit-digest.",

package/src/ask-vocab.mjs

@@ -298,6 +298,18 @@ export const MISSPELLINGS = Object.freeze({
   "waht": "what",
   "dose": "does", "doess": "does",
   "teh": "the",
+  // aggregate/list TRIGGER words (2026-07-02, trigger-typo work) — a typo of a count
+  // or list trigger used to be DROPPED as unmatched by the relaxation cascade, losing
+  // the aggregate/list INTENT entirely ("how manyn classes" → the count was lost);
+  // curated here so the intended trigger is restored BEFORE parsing (the general
+  // bounded fuzzy path in ask.mjs's cascade is the backstop for uncurated typos).
+  "manyn": "many", "mnay": "many", "amny": "many", "mnany": "many",
+  "coutn": "count", "conut": "count", "cuont": "count", "ocunt": "count",
+  "numer": "number", "nubmer": "number", "numbr": "number", "nmuber": "number",
+  "lst": "list", "lsit": "list", "ilst": "list",
+  "shwo": "show", "hsow": "show",
+  "dispaly": "display", "dsiplay": "display",
+  "funtcions": "functions", "funciton": "function", "funcitons": "functions",
 });
 
 /** Words used INCORRECTLY but with clear intent, mapped to the canonical schema
@@ -473,8 +485,53 @@ export const QUALIFIERS = Object.freeze({
 
 /** Aggregate/count triggers: "how many <kind> …", "count <kind>s", "number of
  *  <kind>". Answered by counting a class of individuals or a clause's result set —
- *  no header magic, a straight count over the graph (ask.mjs). */
-export const AGGREGATE_TRIGGERS = Object.freeze(["how many", "how much", "count", "number of", "count of"]);
+ *  no header magic, a straight count over the graph (ask.mjs). Register-spread the
+ *  same way RELATIONS' verbs are (2026-07-02): the count question has a formal
+ *  ("how many"/"number of"), a neutral/imperative ("count"/"count up"), and a
+ *  quantity ("quantity of"/"total number of") register a developer actually types.
+ *  Judgement calls, kept OUT deliberately: bare "tally"/"sum"/"total" — those are
+ *  already mapped to "count" by CASCADE_SYNONYMS (ask.mjs's relaxation layer), and a
+ *  cascade test asserts "tally the classes" reaches the count via that synonym path,
+ *  so promoting them to direct triggers here would both duplicate the mapping and
+ *  break that test; and single-word "total"/"sum" would false-match identifier
+ *  fragments ("total price", "sum of squares") the count intent never meant. */
+export const AGGREGATE_TRIGGERS = Object.freeze([
+  // formal ("the number of classes" reaches "number of" once the cascade strips the
+  // leading article — keeping the trigger list clear of "the" so it never enters
+  // CONTENT_VOCAB and blocks the article's own noise-strip)
+  "how many", "how much", "how many of", "number of",
+  "total number of", "quantity of",
+  // neutral / imperative
+  "count", "count up", "count of", "tot up",
+]);
+
+/** LIST triggers (2026-07-02, list shape) — the many ways a developer asks to SEE the
+ *  individuals of a kind ("list functions", "show me the classes", "what are the
+ *  modules"). Read by ask.mjs's parseList (a sibling of the count node): a trigger
+ *  followed by an entity kind noun lists that class (capped at OVERFLOW_CAP), a
+ *  trailing scope/predicate narrows it, and an unknown kind after a clear list trigger
+ *  is an honest miss naming the kinds. Two registers, wide-but-deliberate (the operator's
+ *  "err toward inclusion", bounded by the file-header discipline: a phrase earns its
+ *  place only if it genuinely means "enumerate these" and won't false-match an unrelated
+ *  identifier — parseList further requires a real entity kind to follow, so a stray
+ *  "show"/"name" in another question is never seized):
+ *   · IMPERATIVE — "<verb> [me/us] [the] <kind>". Bare determiners/objects (the/a/all/
+ *     me/us) after the verb are skipped by parseList's LIST_SKIP, so only the verb stem
+ *     is listed here (not every "... the"/"... all" inflection).
+ *   · INTERROGATIVE — "what/which are [the] <kind>"; the bare "what <kind>"/"which
+ *     <kind>" (+ optional "are there") form is handled directly in parseList, not here.
+ *  Kept OUT on purpose: "tell me" / "give me" collide only where normalizeQuery already
+ *  strips them as FILLER_WORDS ("tell me the classes" → "the classes"), so "tell me" is
+ *  omitted (it never survives to parseList); "gimme" is omitted because CONTRACTIONS
+ *  rewrites it to "give me" before parseList runs. */
+export const LIST_TRIGGERS = Object.freeze([
+  // imperative — "<verb> [me/us] [the] <kind>"
+  "list", "show", "show me", "show us", "display", "print", "print out",
+  "dump", "enumerate", "name", "give me", "get me", "spit out", "rattle off",
+  "run down", "run through", "ls",
+  // interrogative — "what/which are [the] <kind>"
+  "what are", "which are",
+]);
 
 /** Superlative extremes -> ranking direction. "most/greatest/highest/biggest/
  *  largest/most-connected" rank descending; "fewest/least/smallest/lowest" rank
@@ -552,6 +609,13 @@ export const CASCADE_NOISE = Object.freeze([
   // the aggregate/where parsers already tolerate a stray "the"/"a", so stripping is
   // belt-and-braces, not load-bearing)
   "the", "a", "an", "some",
+  // topic lead-in filler — "what about the modules", "how about classes": "about"
+  // carries no graph meaning here, so stripping it lets the bare kind noun surface for
+  // the cascade's bare-kind-noun terminal rule (ask.mjs). ("what"/"how" are structural
+  // question words the drop-pass keeps; only the "about" between them and the kind is
+  // noise.) A module literally named "about" is safe-listed by relaxParse's resolvesExact
+  // guard, same as every other noise token.
+  "about",
   // politeness / hedges (single-token; multi-word "could you"/"please" etc. are
   // FILLER_WORDS, stripped earlier during normalization)
   "please", "pls", "plz", "kindly", "just", "simply", "maybe", "perhaps",

package/src/ask.mjs

@@ -42,7 +42,7 @@ import {
   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,
+  AGGREGATE_TRIGGERS, LIST_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";
@@ -625,6 +625,9 @@ export function parseQuery(query, { nlp = undefined } = {}) {
 //   {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:"list", entityType, base, scoped}      — list the individuals of eval(base),
+//        capped at OVERFLOW_CAP; `scoped` suppresses the "narrow with …" hint when the
+//        list was already restricted (a module scope or predicate tail)
 //   {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
@@ -672,6 +675,7 @@ function parseComposite(text, nlp) {
   return parseAnaphora(w, lc, nlp)
     || parseAggregate(w, lc, nlp)
     || parseSuperlative(w, lc, nlp)
+    || parseList(w, lc, nlp, 0)
     || parseNested(w, lc, nlp, 0)
     || parseRelationalOrQualified(w, lc, nlp, 0);
 }
@@ -755,9 +759,22 @@ function parsePredicateFilter(words, nlp) {
   return undefined;
 }
 
+/** Trailing "and that's the whole question" filler an aggregate/list tail can carry
+ *  ("how many classes are there", "list functions in total", "which classes exist in
+ *  the index") — a count/list over a bare kind is frequently phrased with such a tail,
+ *  and it must NOT be mistaken for a restrictor (that's the exact bug behind "how many
+ *  classes are there" → the count-restrictor miss). Combined with STOPWORDS (which
+ *  already carries are/there/is/in/the/…) at the call site, so only the non-stopword
+ *  extras live here. A tail with ANY word outside this ∪ STOPWORDS is a real restrictor. */
+const AGG_TAIL_FILLER = new Set([
+  "total", "altogether", "overall", "exist", "exists", "existing", "present",
+  "here", "now", "currently", "graph", "index", "codebase", "repo", "repository",
+]);
+
 /** 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. */
+ *  individuals; a restrictor tail counts a clause's result set; a purely-filler tail
+ *  ("… are there", "… in total") is treated as no restrictor (a bare count). */
 function parseAggregate(w, lc, nlp) {
   const trig = AGGREGATE_TRIGGERS.find((t) => lc.slice(0, t.split(" ").length).join(" ") === t);
   if (!trig) return null;
@@ -770,8 +787,9 @@ function parseAggregate(w, lc, nlp) {
   const entWord = lc[i];
   i += 1;
   const tail = w.slice(i);
+  const tailMeaningful = lc.slice(i).some((t) => !STOPWORDS.has(t) && !AGG_TAIL_FILLER.has(t));
   let base;
-  if (tail.length) {
+  if (tailMeaningful) {
     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;
@@ -782,6 +800,79 @@ function parseAggregate(w, lc, nlp) {
   return { node: "count", entityType: noun.entityType, base };
 }
 
+// Determiners/objects skipped after a LIST trigger verb ("show me THE classes") — a
+// superset of the aggregate skip so "give me all the modules" reaches the kind noun.
+const LIST_SKIP = new Set(["the", "a", "an", "all", "me", "us"]);
+const LIST_TRIGGERS_SORTED = [...LIST_TRIGGERS].sort((a, b) => b.split(" ").length - a.split(" ").length);
+// The listable node classes, named in the honest miss and the empty-index message.
+const LISTABLE_KINDS = "functions, classes, methods, modules, attributes, variables, or commits";
+
+/** LIST: "list <kind>", "show me the <kind>s", "what are the <kind>", "list <kind> in
+ *  <module>". A sibling of the count node — it enumerates the individuals of a class
+ *  (rendered under OVERFLOW_CAP) instead of counting them. Fires on a LIST_TRIGGERS
+ *  verb, OR the bare interrogative "what/which <kind>" — but the interrogative form is
+ *  gated to a filler-only tail so an ordinary reverse query ("which functions call X")
+ *  is NOT hijacked into a list (it must stay a simple clause; the compat tests pin it).
+ *  A scope/predicate tail ("in walk.mjs", "that call X") is delegated to parseSetPhrase
+ *  (reusing membership/relational/boolean), and its `scoped` flag suppresses the
+ *  "narrow with …" hint. An unknown kind after a clear imperative trigger ("list
+ *  bananas") is an honest miss naming the listable kinds; anything less certain falls
+ *  through (null) to the existing parser/cascade rather than guessing. */
+function parseList(w, lc, nlp, depth) {
+  let i = 0;
+  let interrogative = false;
+  let matched = null;
+  for (const t of LIST_TRIGGERS_SORTED) {
+    const tw = t.split(" ");
+    if (lc.slice(0, tw.length).join(" ") === t) { matched = t; i = tw.length; break; }
+  }
+  if (!matched) {
+    if (lc[0] === "what" || lc[0] === "which") { interrogative = true; i = 1; }
+    else return null;
+  }
+  while (i < lc.length && LIST_SKIP.has(lc[i])) 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;
+  // "Change" is ask-vocab.mjs's pseudo-type (no node is ever class "Change"), so it is
+  // not a listable class — fall through rather than render a false empty.
+  if (!noun || noun.placeholder || noun.entityType === "Change") {
+    // A clear imperative "list <one unknown plain word>" is an honest miss that NAMES
+    // the kinds; a verb-led or multi-word tail, or the interrogative form, is too
+    // uncertain to claim as a list — fall through to the existing parser/cascade.
+    if (!interrogative && i < lc.length && i === lc.length - 1
+      && /^[a-z]+$/.test(lc[i]) && !VERB_TO_KIND[lc[i]] && !PLACEHOLDER_NOUNS.includes(lc[i])) {
+      return { node: "miss", reason: `"${lc[i]}" isn't a listable kind — try ${LISTABLE_KINDS}` };
+    }
+    return null;
+  }
+  const entityType = noun.entityType;
+  const entWord = lc[i];
+  i += 1;
+  const tail = w.slice(i);
+  const tailMeaningful = lc.slice(i).some((t) => !STOPWORDS.has(t) && !AGG_TAIL_FILLER.has(t));
+  // The bare interrogative "what/which <kind>" is a list ONLY with an explicit
+  // list-confirming filler tail ("… are there", "… that exist"): a real predicate
+  // ("which functions call X") is a reverse query, and a *bare* "which methods" is left
+  // alone deliberately — otherwise the relaxation cascade could drop an unknown
+  // qualifier ("which shiny methods" → "which methods") and silently list everything,
+  // erasing the honest "unknown qualifier" miss. Imperative triggers ("list methods")
+  // carry their own list intent, so they need no such tail.
+  if (interrogative && (tailMeaningful || tail.length === 0)) return null;
+  let base;
+  let scoped = false;
+  if (tailMeaningful) {
+    const setAst = parseSetPhrase(`which ${[...quals, entWord, ...tail].join(" ")}`, nlp, (depth || 0) + 1);
+    if (!setAst || setAst.node === "miss") return { node: "miss", reason: (setAst && setAst.reason) || "the list filter didn't parse" };
+    base = setAst;
+    scoped = true;
+  } else {
+    base = { node: "allOfClass", entityType };
+    if (quals.length) base = { node: "qualifier", filters: quals, inner: base };
+  }
+  return { node: "list", entityType, base, scoped };
+}
+
 /** 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
@@ -1139,6 +1230,7 @@ function evalSuperlative(graph, ast) {
 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 === "list") return { compositeKind: "list", matches: evalSet(graph, ast.base, opts), entityType: ast.entityType, scoped: ast.scoped };
   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 };
@@ -1154,7 +1246,7 @@ const compositeList = (matches) => listJoin(matches.slice(0, OVERFLOW_CAP)
 /** 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"';
+  return 'compositional queries also work: "which functions call X and call Y", "what calls something that imports X", "public methods of X", "list functions" / "show me the classes", "how many classes", "which module has the most imports", or (after a listing) "which of those are tested"';
 }
 
 function renderComposite(parsed, result) {
@@ -1168,6 +1260,19 @@ function renderComposite(parsed, result) {
     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 === "list") {
+    if (!result.matches.length) {
+      return { content: `no ${nounFor(result.entityType, 2)} in this index.`, miss: true, ambiguous: false, matches: [] };
+    }
+    // an unscoped list that overflowed the cap gets a light hint to narrow by module —
+    // but only for kinds that live IN a module (a "modules in <module>" or "commits in
+    // <module>" scope is meaningless); the scoped forms are already narrow, no hint.
+    const scopeable = !["Module", "Commit"].includes(result.entityType);
+    const hint = (!result.scoped && scopeable && result.matches.length > OVERFLOW_CAP)
+      ? ` — narrow with "${nounFor(result.entityType, 2)} in <module>"`
+      : "";
+    return { content: `${compositeList(result.matches)}${hint}.`, miss: false, ambiguous: false, matches: result.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";
@@ -1981,6 +2086,49 @@ const CONTENT_VOCAB = new Set([
  *  ("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));
+/** Every token that carries NO graph meaning of its own — curated noise (articles,
+ *  politeness, vocatives, presentation frames) PLUS the structural scaffolding
+ *  (question words, context pronouns). The bare-kind-noun terminal rule (relaxParse's
+ *  Layer 4) treats a query as "just a kind noun wrapped in packaging" only when every
+ *  non-kind token is one of these — so an unknown qualifier ("shiny") or a relation
+ *  verb, being neither, still blocks the default and preserves the honest miss. */
+const NOISE_OR_SCAFFOLD = new Set([...CASCADE_NOISE_SET, ...STRUCTURAL_WORDS]);
+
+/** The aggregate/list TRIGGER words the cascade's drop-unmatched pass will fuzzy-correct
+ *  a typo toward (Gap 2, trigger-typo work). Curated (not derived from LIST_TRIGGERS'
+ *  multi-word phrases) so the target set stays clean single verbs — "many", "count",
+ *  "list", "show", … — and never drags in a stray "down"/"off"/"out" from a phrasal
+ *  trigger that would mis-correct an unrelated token. */
+const TRIGGER_FUZZY_WORDS = [
+  "many", "count", "number", "quantity", "total", "tally",
+  "list", "show", "display", "print", "dump", "enumerate", "name",
+];
+/** Closed-vocab words a plain unknown may be fuzzy-corrected TOWARD before the cascade
+ *  discards it: relation verbs, entity kind nouns, and the aggregate/list triggers. A
+ *  correction fires only on a token already bound for the drop pile (grammar doesn't own
+ *  it, no entity resolves) and only for a UNIQUE within-bound target, so it strictly
+ *  beats dropping — a typo of a trigger keeps its intent instead of being lost. Excludes
+ *  STOPWORDS/structural words (a random unknown must never bend into "what"/"the") and
+ *  <4-char words (at the small bound they match half of English). */
+const CASCADE_FUZZY_TARGETS = [...new Set([
+  ...wordsOf(Object.keys(VERB_TO_KIND)),
+  ...Object.keys(ENTITY_TO_TYPE),
+  ...TRIGGER_FUZZY_WORDS,
+])].filter((wd) => /^[a-z]+$/.test(wd) && wd.length >= 4 && !STOPWORDS.has(wd));
+
+/** UNIQUE within-bound fuzzy correction of `w` toward CASCADE_FUZZY_TARGETS, or null —
+ *  a distance tie between two distinct targets is refused (honest-miss discipline at the
+ *  vocabulary level, cf. fuzzyVocabWord). */
+function fuzzyCascadeWord(w) {
+  const bound = fuzzyBound(w);
+  let best = bound + 1; let hit = null; let tied = false;
+  for (const target of CASCADE_FUZZY_TARGETS) {
+    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;
+}
 
 /** 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,
@@ -2099,16 +2247,28 @@ export function relaxParse(graph, query, { nlp = undefined, contextId = null, pr
   // Layer 2 — DROP-UNMATCHED (plain-lowercase unknowns beside the real terms)
   const survivors = [];
   const nowDropped = [];
+  const corrected = [];
   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) {
+    if (!plain || CONTENT_VOCAB.has(lc) || STRUCTURAL_WORDS.has(lc) || resolvesLiteral(t)) {
+      survivors.push(t);
+      continue;
+    }
+    // Gap 2 — before dropping an unmatched plain token, try a bounded fuzzy-correct to a
+    // UNIQUE closed-vocab word (verbs, entity kinds, aggregate/list triggers): a typo of
+    // a TRIGGER ("manyn"→"many", "coutn"→"count", "liist"→"list") is restored, not
+    // discarded, so the count/list intent survives. Only a unique within-bound hit; else
+    // the token is genuinely unrecoverable and drops exactly as before.
+    const fix = fuzzyCascadeWord(lc);
+    if (fix && fix !== lc) { survivors.push(fix); corrected.push(`${t}→${fix}`); continue; }
+    nowDropped.push(t);
+  }
+  if ((corrected.length || nowDropped.length) && survivors.length) {
     tokens = survivors;
     dropped.push(...nowDropped);
-    steps.push(`drop unmatched ${JSON.stringify(nowDropped)} → "${tokens.join(" ")}"`);
+    if (corrected.length) steps.push(`fuzzy-correct ${JSON.stringify(corrected)} → "${tokens.join(" ")}"`);
+    if (nowDropped.length) steps.push(`drop unmatched ${JSON.stringify(nowDropped)} → "${tokens.join(" ")}"`);
     const hit = attempt(tokens);
     if (hit) return done(hit);
   }
@@ -2126,6 +2286,47 @@ export function relaxParse(graph, query, { nlp = undefined, contextId = null, pr
     if (hit) return done(hit);
   }
 
+  // Layer 4 (terminal) — BARE KIND NOUN → a bounded DEFAULT ACTION. When noise-strip,
+  // drop-unmatched and synonym-normalise have all failed to yield an answerable parse,
+  // give the operator's "vague enough to land" case a sensible answer instead of an
+  // honest miss: a query that is ONLY a kind noun (class/classes, function/functions,
+  // module, method, attribute, variable, commit, …) wrapped in articles/noise/question
+  // words DEFAULTS TO A COUNT of that kind ("the classes" / "classes" / "tell me the
+  // classes" → "20 classes."). Count, not list: a bare unscoped list of 647 functions is
+  // noise, whereas the count is the cheap useful answer the asker can then drill into
+  // ("list them"). Deterministic — count for every kind, no cardinality cap.
+  //
+  // We classify the ORIGINAL normalized tokens (`from`), NOT the layer-mutated `tokens`:
+  // drop-unmatched has by now EATEN any unknown qualifier, so "the shiny classes" would
+  // otherwise look identical to a bare "classes". Reading the whole phrase keeps the
+  // discipline exact — the rule fires ONLY when every non-kind token is pure packaging
+  // (NOISE_OR_SCAFFOLD). A dangling unknown qualifier ("the shiny classes"), a relation
+  // verb, a marker, or a real term is neither noise nor a kind noun, so it lands in
+  // `others`, blocks the default, and the honest miss (or the real compositional query,
+  // if a lower layer already rescued it) stands.
+  const bareLc = splitWords(from).map((t) => t.toLowerCase());
+  const kindWords = [];
+  const others = [];
+  for (const t of bareLc) {
+    if (NOISE_OR_SCAFFOLD.has(t)) continue;
+    // real entity kinds only — "change"/"changes" is ask-vocab's pseudo-type (never a
+    // node class), so it is not a countable kind; it falls into `others`.
+    const et = ENTITY_TO_TYPE[t];
+    if (et && et !== "Change") kindWords.push(t);
+    else others.push(t);
+  }
+  if (kindWords.length === 1 && others.length === 0) {
+    // reuse the whole aggregate pipeline (parseAggregate → count node → renderer): a
+    // synthesized "count <kind>" is the exact query the cascade's other count paths land.
+    const hit = attempt(["count", kindWords[0]]);
+    if (hit) { steps.push(`bare kind "${kindWords[0]}" → count`); return done(hit); }
+  }
+  // A LONE unknown noun wrapped only in packaging ("the bananas") is left to the generic
+  // honest miss (the rephrase hint already NAMES the kinds): a crisper "isn't a listable
+  // kind" miss here would fire on every one-word non-query the same way ("tell me a joke"),
+  // which chat.mjs's own surface deliberately answers with the general hint — so the
+  // bare-noun default is a COUNT of a KNOWN kind only, never a re-worded miss.
+
   return null; // exhausted — the honest bottom of the cascade (caller keeps the original miss)
 }
 

package/src/codegraph.mjs

@@ -563,6 +563,27 @@ const BEAM_OVERFLOW_CAP = 4;     // near-miss safety valve size
 const BEAM_PLIES = 2;            // hops of expansion
 const BEAM_EDGE_GROUPS = [["imports"], ["calls", "callsSymbol"], ["inherits"], ["cochange"]];
 
+// ---- SPIRAL expansion (opt-in, default off; BEAM_RESEARCH.md's "fix #2/#3" made concrete) ------
+// Deterministic bounded-radius ego walk from the lexical seeds, ordered fewest-arcs-first, with a
+// degree-quantile hub gate. UNLIKE beamExpand it MAY introduce modules that had no lexical match
+// (it walks the graph from the seeds), so it can in principle lift a lexically-invisible truth into
+// top-k — the whole point. cochange is dropped (temporal-coupling noise; see the research synthesis).
+//   • spiralDepth          — max hop radius from the seeds (bounded ego expansion). Default 3.
+//   • mostDistinctiveBeams — degree-quantile gate q∈(0,1]: at each expansion step keep only the
+//                            lowest-degree ⌊q·n⌋ candidates (drop the top (1−q) hubs); q=1.0 keeps
+//                            all. Never empties the frontier (keeps ≥1 — the least-connected).
+//   • spiralNodeLimit      — emit budget: how many newly-reached nodes the spiral surfaces. Held at
+//                            12 (MID-tier digest breadth, a KNOWN-DOABLE token budget) — a fixed
+//                            budget, NOT a recall dial.
+const SPIRAL_DEPTH_DEFAULT = 3;
+const SPIRAL_NODE_LIMIT_DEFAULT = 12;
+const SPIRAL_Q_DEFAULT = 0.9;                 // mild hub pruning (drop only the densest 10%) — the centre point
+const SPIRAL_EXPAND_KINDS = ["imports", "calls", "callsSymbol", "inherits"]; // cochange dropped
+const SPIRAL_EMIT_FRAC = 0.5;                 // a newly-surfaced node's base score = maxSeed × this …
+const SPIRAL_HOP_DECAY = 0.6;                 //  … decayed by this per hop from the seeds (bounded < maxSeed, so a walked-in node never dominates rank 1)
+const SPIRAL_PROX_FRAC = 0.2;                 // an ALREADY-matched module the spiral re-reaches gets a bounded nudge …
+const SPIRAL_PROX_CAP_FRAC = 0.35;            //  … capped at this × its own score (same shape as every other proximity family)
+
 /** embedRank: per-module embeddable text — path components + defined symbol names + doc
  *  first-lines, ALL already in the graph (never re-reads source), bounded by the EMB_TEXT_*
  *  caps. Built once per graph and cached alongside the vectors in EMB_CACHE. */
@@ -685,13 +706,106 @@ function beamExpand(graph, scored, beamWidth) {
   }
 }
 
+/** SPIRAL expansion (opt-in; see the SPIRAL_* constants' comment above for the full design).
+ *  A deterministic bounded-radius ego walk from the lexical seeds (`scored`), popped
+ *  fewest-arcs-first via a min-heap keyed (hop ASC, in-graph degree ASC, id ASC), with a
+ *  degree-quantile hub gate at each expansion step. Emits up to `nodeLimit` newly-reached nodes
+ *  in pop order, scoring each seed-relative and bounded so a hub can't dominate rank 1.
+ *  CRITICAL vs beamExpand: it deliberately OMITS the `if (!baseScore.has) continue` guard, so it
+ *  MAY push modules that had NO lexical match into `scored` — the one path to breaking the lexical
+ *  ceiling. Mutates `scored` (nudges re-reached matches in place; APPENDS newly-surfaced modules).
+ *  Pure otherwise (no fs/network); deterministic total ordering throughout. */
+function spiralExpand(graph, scored, { depth = SPIRAL_DEPTH_DEFAULT, q = SPIRAL_Q_DEFAULT, nodeLimit = SPIRAL_NODE_LIMIT_DEFAULT } = {}) {
+  if (!scored.length) return;
+  const byId = new Map(scored.map((s) => [s.ind.id, s]));
+  const seeds = new Set(byId.keys());
+  let maxSeed = 0;
+  for (const s of scored) maxSeed = Math.max(maxSeed, s.score);
+  if (!(maxSeed > 0)) return;
+  // Combined undirected adjacency over the expansion kinds (cochange dropped). In-graph degree =
+  // neighbour count over these kinds — the "arcs" the frontier orders and the quantile gate reads.
+  const adj = adjacencyForKinds(graph, SPIRAL_EXPAND_KINDS);
+  const degree = (id) => (adj.get(id)?.size || 0);
+  // Binary min-heap over the frontier, keyed (hop ASC, degree ASC, id ASC) — pop the closest,
+  // least-connected node first, so expansion fans through the sparse surroundings and fizzles at
+  // hubs. The id tiebreak makes the order a deterministic total order (no RNG, no insertion bias).
+  const heap = [];
+  const less = (a, b) => a.hop !== b.hop ? a.hop < b.hop
+    : a.deg !== b.deg ? a.deg < b.deg
+    : a.id < b.id;
+  const swap = (i, j) => { const t = heap[i]; heap[i] = heap[j]; heap[j] = t; };
+  const push = (node) => {
+    heap.push(node);
+    let i = heap.length - 1;
+    while (i > 0) { const p = (i - 1) >> 1; if (less(heap[i], heap[p])) { swap(i, p); i = p; } else break; }
+  };
+  const pop = () => {
+    const top = heap[0];
+    const last = heap.pop();
+    if (heap.length) {
+      heap[0] = last;
+      let i = 0;
+      for (;;) {
+        const l = 2 * i + 1, r = 2 * i + 2; let m = i;
+        if (l < heap.length && less(heap[l], heap[m])) m = l;
+        if (r < heap.length && less(heap[r], heap[m])) m = r;
+        if (m === i) break;
+        swap(i, m); i = m;
+      }
+    }
+    return top;
+  };
+  const visited = new Set(seeds);
+  for (const id of seeds) push({ id, hop: 0, deg: degree(id) });
+  const defIdx = definesIndex(graph);
+  let emitted = 0;
+  while (heap.length && emitted < nodeLimit) {
+    const node = pop();
+    if (!seeds.has(node.id)) {
+      // Slot this newly-reached node: seed-relative base, hop-decayed and bounded below maxSeed.
+      const emitScore = maxSeed * SPIRAL_EMIT_FRAC * Math.pow(SPIRAL_HOP_DECAY, node.hop - 1);
+      const existing = byId.get(node.id);
+      if (existing) { // already lexically matched (below-k) → bounded nudge, never a replacement
+        existing.score += Math.min(emitScore * SPIRAL_PROX_FRAC, existing.score * SPIRAL_PROX_CAP_FRAC);
+      } else { // lexically INVISIBLE → introduce it (the beam structurally cannot)
+        const ind = graph.byId?.get?.(node.id);
+        if (ind && (ind.class || "") === "Module") {
+          const defines = defIdx.get(ind.id) || [];
+          const entry = { ind, score: emitScore, defineCount: defines.length, matching: [], density: 0 };
+          scored.push(entry);
+          byId.set(node.id, entry);
+        }
+      }
+      emitted++;
+    }
+    if (node.hop >= depth) continue;
+    // This step's candidate set = the popped node's unvisited MODULE neighbours; quantile-gate by
+    // degree, keeping the lowest-degree ⌊q·n⌋ (drop the densest hubs), never fewer than one.
+    const cands = [];
+    for (const nid of adj.get(node.id) || []) {
+      if (visited.has(nid)) continue;
+      const ind = graph.byId?.get?.(nid);
+      if (!ind || (ind.class || "") !== "Module") continue; // no phantom (fn-fallback) module ids
+      cands.push({ id: nid, deg: degree(nid) });
+    }
+    if (!cands.length) continue;
+    cands.sort((a, b) => a.deg - b.deg || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const keep = Math.max(1, Math.floor(q * cands.length)); // lowest-degree q-fraction; never empty
+    for (let i = 0; i < keep; i++) {
+      const c = cands[i];
+      visited.add(c.id);
+      push({ id: c.id, hop: node.hop + 1, deg: c.deg });
+    }
+  }
+}
+
 /** The shared module-ranking core behind renderSearch (text) and searchModulesRanked (path+score).
  *  IDF-weights each query token by rarity across modules (so a whole-problem-statement query is not
  *  swamped by ubiquitous words like template/filter/value), scores path-component + symbol-component
  *  + EXACT-symbol matches, re-ranks with a bounded import-proximity bonus, and breaks ties by
  *  matched-symbol DENSITY (a concrete signal — never ground truth). Pure; deterministic. */
 function scoreModules(graph, tokens, opts = {}) {
-  const { demoteNonProd = false, callAdjacency = false, implOfInterface = false, beamSearch = false, proseBoost = false, proseLayers = false, literalMention = false, embedRank = false, rawQuery = "" } = opts;
+  const { demoteNonProd = false, callAdjacency = false, implOfInterface = false, beamSearch = false, spiral = false, proseBoost = false, proseLayers = false, literalMention = false, embedRank = false, rawQuery = "" } = opts;
   const beamWidth = Number.isFinite(opts.beamWidth) && opts.beamWidth > 0 ? opts.beamWidth : 8;
   const defIdx = definesIndex(graph);
   // Precompute each module's path components + defined-symbol exact/component sets, once.
@@ -956,6 +1070,14 @@ function scoreModules(graph, tokens, opts = {}) {
   }
   // §5.15 beam search (opt-in): multi-ply generalization of the single-hop families above.
   if (beamSearch && scored.length > 1) beamExpand(graph, scored, beamWidth);
+  // SPIRAL (opt-in): bounded-radius ego walk that MAY introduce lexically-invisible modules — runs
+  // last (after every family has finalised the seed scores) so its seed-relative emit scores and
+  // hub gate read the settled ranking, and before the sort so surfaced nodes slot into it.
+  if (spiral && scored.length) spiralExpand(graph, scored, {
+    depth: Number.isFinite(opts.spiralDepth) && opts.spiralDepth > 0 ? opts.spiralDepth : SPIRAL_DEPTH_DEFAULT,
+    q: Number.isFinite(opts.mostDistinctiveBeams) && opts.mostDistinctiveBeams > 0 ? opts.mostDistinctiveBeams : SPIRAL_Q_DEFAULT,
+    nodeLimit: Number.isFinite(opts.spiralNodeLimit) && opts.spiralNodeLimit > 0 ? opts.spiralNodeLimit : SPIRAL_NODE_LIMIT_DEFAULT,
+  });
   // Tie-break: score → matched-symbol DENSITY (concrete, not ground truth) → fewer defines → shorter label.
   scored.sort((a, b) => b.score - a.score || b.density - a.density || a.defineCount - b.defineCount || String(a.ind.label).length - String(b.ind.label).length);
   return scored;