@polycode-projects/seonix 0.2.1 → 0.4.0

package/src/ask-nlp.mjs

@@ -0,0 +1,73 @@
+// ask-nlp.mjs — the OPTIONAL wink-nlp adapter behind ask.mjs's lemma/POS tier.
+//
+// BOUNDARY (hard, do not move): this file is Node-only and is NEVER inlined into
+// the viewer bundle. viz.mjs's askSource() inlines codegraph.mjs + ask-vocab.mjs +
+// ask.mjs ONLY and strips their import lines, so the portable single-file HTML has
+// no wink, no model, and no `nlpAdapter` binding at all — ask.mjs reaches this
+// module exclusively through a `typeof nlpAdapter === "function"` guard and
+// degrades to adapter-less parsing (lemma/POS tiers off; the curated tables and
+// the bounded edit-distance tier still work, browser and Node alike). Keeping the
+// ~1MB CJS model out of the page is the point of the split.
+//
+// wink-nlp and wink-eng-lite-web-model are CJS — loaded via createRequire, the
+// same Node-module-resolution approach viz.mjs uses to locate cytoscape (resolve
+// through the module system, never a guessed path). The require happens lazily on
+// first use and failure is cached as null: a checkout without the optional deps
+// installed answers exactly like the browser bundle, it never throws.
+
+import { createRequire } from "node:module";
+
+let cached; // undefined = not tried yet; null = unavailable (tried once, honestly off)
+
+/** Lazily build the {lemma, posTags} adapter, or null when wink isn't loadable.
+ *  Deterministic: wink-nlp's tagger/lemmatiser is a fixed model with no sampling,
+ *  so the same input always yields the same tags/lemmas across processes. */
+export function nlpAdapter() {
+  if (cached !== undefined) return cached;
+  try {
+    const require = createRequire(import.meta.url);
+    const winkNLP = require("wink-nlp");
+    const model = require("wink-eng-lite-web-model");
+    const nlp = winkNLP(model);
+    const its = nlp.its;
+    cached = {
+      /** Lowercase lemma of a single token ("imported" -> "import"); the word
+       *  itself when wink has nothing better (unknown words come back as-is). */
+      lemma(word) {
+        const w = String(word || "");
+        try {
+          const out = nlp.readDoc(w).tokens().out(its.lemma);
+          return String(out[0] || w).toLowerCase();
+        } catch {
+          return w.toLowerCase();
+        }
+      },
+      /** UPOS tags aligned to the CALLER's word array. wink re-tokenizes (it
+       *  splits "walk.mjs" into three tokens), so each input word is greedily
+       *  matched to the run of wink tokens that spell it and takes its FIRST
+       *  sub-token's tag; null per word on any surprise, never a throw. */
+      posTags(words) {
+        try {
+          const toks = nlp.readDoc(words.join(" ")).tokens();
+          const texts = toks.out();
+          const tags = toks.out(its.pos);
+          const out = [];
+          let k = 0;
+          for (const w of words) {
+            if (k >= texts.length) { out.push(null); continue; }
+            out.push(tags[k]);
+            let acc = texts[k];
+            k += 1;
+            while (acc.length < w.length && k < texts.length) { acc += texts[k]; k += 1; }
+          }
+          return out;
+        } catch {
+          return words.map(() => null);
+        }
+      },
+    };
+  } catch {
+    cached = null;
+  }
+  return cached;
+}

package/src/ask-vocab.mjs

@@ -35,8 +35,9 @@ export const RELATIONS = {
   imports: {
     comment: "Module -> Module: subject's import graph references object (usesComplexType).",
     verbs: [
-      // formal/neutral
-      "couples to", "couple to", "uses", "use", "depends on", "imports", "import",
+      // formal/neutral ("uses"/"use" moved to the `uses` union family, 2026-07-02 —
+      // "uses code from" stays here: its phrasing is specifically import-flavored)
+      "couples to", "couple to", "depends on", "imports", "import",
       "relies on", "rely on", "requires", "require", "references", "reference",
       "pulls in", "pull in", "built on", "builds on", "build on", "uses code from",
       // casual/colloquial
@@ -46,6 +47,21 @@ export const RELATIONS = {
       "importing",
     ],
   },
+  // "uses" is a QUERY-side union family, not a stored predicate (2026-07-02 query
+  // families): "what uses X" honestly means BOTH the import graph and the call
+  // graph, so ask.mjs traverses it as imports + calls + callsSymbol together
+  // (KIND_UNIONS there). The verbs moved here FROM imports — "which modules use X"
+  // still answers with the importing modules (the asked Module grain filters the
+  // union down to module-grain subjects), and "what uses <function>" now also
+  // reaches the symbol-grain callers instead of silently ignoring them.
+  uses: {
+    comment: "query-side union: imports (Module->Module) + calls (Module->Module) + callsSymbol (fn->fn).",
+    verbs: [
+      "uses", "use", "used by", "makes use of", "make use of",
+      // gerund (g-drop normalization — §3.5)
+      "using",
+    ],
+  },
   calls: {
     comment: "Function/Method -> Function/Class (symbol-grain) or Module -> Module (coarse): subject invokes object.",
     verbs: [
@@ -93,8 +109,13 @@ export const RELATIONS = {
       "derives from", "derive from", "is a subclass of", "are a subclass of",
       "is a kind of", "are a kind of", "is built off", "are built off",
       "is built on top of", "are built on top of",
-      // gerund (g-drop normalization — §3.5)
-      "extending",
+      // gerund (g-drop normalization — §3.5, and the compositional grammar's
+      // gerund-led boolean gate: "classes inheriting from Base but not tested").
+      // Both the two-word "inheriting from" (so "from" is consumed into the verb
+      // phrase, not the object term) and the bare "inheriting" (the single token
+      // the gerund-lead check reads) are listed; longest-match-first prefers the
+      // two-word form when "from" follows.
+      "extending", "inheriting from", "inheriting", "subclassing", "extends from",
     ],
   },
   touches: {
@@ -104,6 +125,27 @@ export const RELATIONS = {
       "was changed in", "were changed in", "was edited in", "were edited in",
       "was modified by", "were modified by", "was tweaked in", "were tweaked in",
       "got changed in", "got edited in",
+      // commit-question forms (2026-07-02, viewer commit-chat fix): the same touch
+      // relation asked from the commit's side — "which changes touch commit <sha>",
+      // "what did commit <sha> touch", "which functions changed in <sha>", "which
+      // changes landed in commit <sha>", "what was touched by commit <sha>". Bare
+      // "touch" completes the touched/touches pair for the "did … touch" auxiliary
+      // form; the "by"/"in" phrases are the passive/locative counterparts of forms
+      // already above (curated per register spread, not a thesaurus dump).
+      "touch", "touched by", "modified by", "changed by", "changed in",
+      "landed in", "land in",
+      // contents-of-a-commit forms (2026-07-02, operator screenshot: "what was in
+      // commit <sha>" missed on the live site). "was in"/"went into" only read as
+      // touch questions when the object is a commit — the sha-shaped object keeps
+      // them from firing on structural questions ("is X in the graph" has no verb
+      // match anyway). Judgment call: "is in" omitted — too generic without the
+      // past-tense anchor and risks matching containment phrasings.
+      "was in", "were in", "went into", "included in",
+      // when-question forms (2026-07-02 query families): "when was X last
+      // updated/edited" — bare past participles that only read naturally in the
+      // temporal shape; the when template routes them, but they are ordinary
+      // touches verbs so "which modules were updated ..." keeps working too.
+      "updated", "edited",
       // gerund (g-drop normalization — §3.5)
       "touching",
     ],
@@ -118,15 +160,31 @@ export const RELATIONS = {
     ],
   },
   reexports: {
-    comment: "Module -> Module: subject re-exports a name it imported from object.",
+    comment: "Module -> exported symbol: subject's public API surface (__all__/export list).",
     verbs: [
       "exports", "export", "re-exports", "re-export", "passes through", "pass through",
+      // API-surface phrasing (2026-07-02 query families): "what does <module>
+      // expose". Bare "exposed" is NOT listed — the lemma tier maps it here when
+      // an adapter is present, and "how does the API get exposed" has no
+      // traversal either way (pinned as an honest miss in the tests).
+      "exposes", "expose",
       // gerund (g-drop normalization — §3.5)
       "exporting",
     ],
   },
 };
 
+// ---- where/when/mentions markers (2026-07-02 query families) — the location and
+// prose-mention questions carry NO relation verb ("where is X defined", "where is
+// X mentioned"), so ask.mjs routes them by these marker words instead of
+// VERB_TO_KIND. Closed lists, same curation discipline as everything above. ----
+
+/** Definition-location markers: "where is X <marker>" (or bare "where is X"). */
+export const WHERE_MARKERS = Object.freeze(["defined", "declared", "located", "implemented"]);
+
+/** Prose-mention markers: "where is X <marker>" -> the prose/mentions surface. */
+export const MENTION_MARKERS = Object.freeze(["mentioned", "referenced"]);
+
 /** relation token -> flat verb-phrase list, the shape ask.mjs's VERB_TO_KIND
  *  table needs (phrase -> kind), derived once from RELATIONS. */
 export const VERB_TO_KIND = Object.freeze(
@@ -142,6 +200,18 @@ export const ENTITY_TO_TYPE = Object.freeze({
   module: "Module", modules: "Module", file: "Module", files: "Module",
   attribute: "Attribute", attributes: "Attribute", field: "Attribute", fields: "Attribute",
   variable: "GlobalVariable", variables: "GlobalVariable", global: "GlobalVariable", globals: "GlobalVariable",
+  // "changes" in a touch question ("which changes touch commit <sha>") means the
+  // code entities on the other end of the touch edges, at WHATEVER grain the graph
+  // recorded — module (touches) and symbol (touchesSymbol) together when the commit
+  // is the given side, and the touching commits themselves when a module/symbol is
+  // the given side. Mapped to the pseudo-type "Change" (not a node class): ask.mjs's
+  // traverse() reads it as a wildcard over the touch traversal's results rather than
+  // aliasing it to ONE real class and silently dropping the other grain of the
+  // answer. Listed BEFORE commit/commits: findPhrase (ask.mjs) takes the first
+  // same-length phrase in table order, so in "which changes touch commit <sha>" the
+  // entity slot must consume "changes" and leave "commit <sha>" intact as the
+  // object term.
+  change: "Change", changes: "Change",
   commit: "Commit", commits: "Commit",
 });
 
@@ -173,6 +243,83 @@ export const CONTRACTIONS = Object.freeze({
   "gimme": "give me",
 });
 
+// ---- misspellings and wrong words (2026-07-02, two-level fuzzy work) — these are
+// CORRECTIONS, not synonyms: the asker typed a broken or incorrect surface form of
+// a word this grammar already owns, and we restore the canonical form BEFORE
+// parsing (normalizeQuery applies both tables like CONTRACTIONS: word-boundary,
+// longest key first, case-insensitive). Synonyms belong in RELATIONS/ENTITY_TO_TYPE;
+// these tables exist so a typo'd or misused word maps to canonical language
+// deterministically, ahead of (and more precisely than) ask.mjs's bounded
+// edit-distance fallback. ask.mjs's correction regex refuses to rewrite a word
+// glued to a dotted extension ("revision.mjs" stays a module name), since
+// WRONG_WORDS entries are real English words that plausibly name modules; a
+// bare standalone token that happens to be a real identifier remains the
+// accepted residual exposure, same as CONTRACTIONS. ----
+
+/** Curated common typos of THIS vocabulary's own keywords — entity nouns, relation
+ *  verbs, and the grammar's anchor words (which/what/does/the): a typo'd anchor
+ *  kills the anchored templates outright, so anchors earn entries too. Values are
+ *  always the canonical word. Judgment calls logged: "calss" maps to "class" (the
+ *  doubled-s slip of "class"), NOT "calls", though both are edit-distance 1 — the
+ *  exact tie the generic fuzzy tier must refuse to break; a curated table is where
+ *  that call is made deliberately. "dose" is a real English word, but at a word
+ *  boundary in this closed question grammar ("dose X import Y") the intent is
+ *  unambiguous. */
+export const MISSPELLINGS = Object.freeze({
+  // entity nouns
+  "funtion": "function", "funtions": "functions",
+  "fucntion": "function", "fucntions": "functions",
+  "functoin": "function", "functoins": "functions",
+  "calss": "class", "calsses": "classes", "classs": "class", "clases": "classes",
+  "modul": "module", "moduls": "modules",
+  "moduel": "module", "moduels": "modules",
+  "moudle": "module", "moudles": "modules",
+  "methdo": "method", "methdos": "methods",
+  "mehtod": "method", "mehtods": "methods",
+  "comit": "commit", "comits": "commits",
+  "commmit": "commit", "commmits": "commits",
+  "varaible": "variable", "varaibles": "variables",
+  "varibale": "variable", "varibales": "variables",
+  "atribute": "attribute", "atributes": "attributes",
+  // relation verbs
+  "improt": "import", "improts": "imports",
+  "imoprt": "import", "imoprts": "imports",
+  "inherts": "inherits", "inheirts": "inherits",
+  "extands": "extends", "extneds": "extends",
+  "depnds": "depends",
+  "touchs": "touches", "tuoches": "touches", "touhced": "touched",
+  "chagned": "changed", "chnaged": "changed",
+  "chagnes": "changes", "chnages": "changes",
+  "calles": "calls",
+  "exprot": "export", "exprots": "exports",
+  "tets": "tests",
+  // grammar anchor words
+  "whcih": "which", "wich": "which", "whihc": "which",
+  "waht": "what",
+  "dose": "does", "doess": "does",
+  "teh": "the",
+});
+
+/** Words used INCORRECTLY but with clear intent, mapped to the canonical schema
+ *  term — used like synonyms by the asker, but they are corrections of usage, not
+ *  alternative names (which is why they live here and not in ENTITY_TO_TYPE).
+ *  Only mapped where intent is unambiguous in a code-graph question; words
+ *  deliberately NOT mapped are logged in the omitted-on-purpose block at the end
+ *  of this file. */
+export const WRONG_WORDS = Object.freeze({
+  // neither a folder nor a directory grain exists in this graph — in "which
+  // folders import X" the only honest referent is the module/file grain.
+  "folder": "module", "folders": "modules",
+  "directory": "module", "directories": "modules",
+  // unambiguous abbreviation of an entity noun this grammar owns
+  "func": "function", "funcs": "functions",
+  // VCS terms whose canonical schema class here is Commit
+  "changeset": "commit", "changesets": "commits",
+  "revision": "commit", "revisions": "commits",
+  // code-graph "property" is the Attribute grain in this schema
+  "property": "attribute", "properties": "attributes",
+});
+
 /** Trailing g-drop ("callin'", "hittin'") — a plain suffix restore, not a
  *  lemmatiser: -in' -> -ing, applied per-word during normalization. The
  *  apostrophe is REQUIRED (not optional): bare "-in" endings with no
@@ -223,6 +370,27 @@ export const NEGATION_FRAMES = Object.freeze([
   { re: /\b(?:nobody|nothing|no one)\s+(\S.*?)(?:,?\s+does\s+it\??|,?\s+do\s+they\??)?$/i, to: (m) => `what ${m[1]}` },
 ]);
 
+// ---- commit-content frames (2026-07-02, operator screenshot: "what was in commit
+// ef74e44e25c8" missed on the live site) — "what was/is in commit <sha>", "what's
+// in <sha>" (the contraction table has already expanded "what's" by the time
+// frames run), "what went into <sha>", "what made it into commit <sha>" all mean
+// the canonical commit-subject question "what did <sha> touch", so they are
+// REWRITTEN to it before either parse strategy runs: the same mechanism and scope
+// discipline as NEGATION_FRAMES (a small closed pattern set, first match wins),
+// which also makes both strategies parse the family for free. The sha-shaped tail
+// is REQUIRED so these frames only ever fire on an actual commit reference: over a
+// non-sha object ("what was in walk.mjs") the frame does not match and the text is
+// left for the ordinary grammar to handle as it already does, rather than being
+// bent into a commit-subject touches query that would then blank. ----
+export const COMMIT_CONTENT_FRAMES = Object.freeze([
+  // "what was in commit ef74e44e25c8" / "what is in ef74e44e" / "what's in commit <sha>"
+  { re: /^what\s+(?:is|was|were|are)\s+in\s+((?:commit\s+)?[0-9a-f]{7,40})\??$/i, to: (m) => `what did ${m[1]} touch` },
+  // "what went into commit ef74e44e25c8" / casual "what got into <sha>"
+  { re: /^what\s+(?:went|got)\s+into\s+((?:commit\s+)?[0-9a-f]{7,40})\??$/i, to: (m) => `what did ${m[1]} touch` },
+  // "what made it into commit ef74e44e25c8"
+  { re: /^what\s+made\s+it\s+into\s+((?:commit\s+)?[0-9a-f]{7,40})\??$/i, to: (m) => `what did ${m[1]} touch` },
+]);
+
 // ---- §7 meta-vocabulary — trigger phrases for the "meta" query shape (asking what a
 // graph vocabulary term itself means: "what does cochange mean", "what does mgx:
 // callsSymbol mean"). Deliberately NOT folded into RELATIONS/VERB_TO_KIND: these
@@ -238,6 +406,197 @@ export const META_MEANING_VERBS = Object.freeze([
   "represent", "represents", "refer to", "refers to",
 ]);
 
+// ---- §compositional grammar vocabulary (PLAN §5.16 P3 — the ask engine's step up
+// from ELIZA keyword-spotting to a real recursive-descent grammar over CLAUSES).
+// ask.mjs's parseComposite reads these tables to recognize the compositional
+// MARKERS — relative clauses, boolean connectives, subject qualifiers, aggregates,
+// superlatives, and anaphora — that compose the SAME closed clause vocabulary
+// (RELATIONS/ENTITY_TO_TYPE above) into multi-hop / set-algebra queries. The
+// grammar COMPOSES the closed vocabulary; it never opens it. Every table here is
+// curated + closed, same discipline as everything above: a marker the tables don't
+// carry is an honest miss, never a guess. ----
+
+/** Relative-clause introducers: "<noun> that/which/who <predicate>". Only ever
+ *  read as a relative pronoun when it sits AFTER a noun and BEFORE a predicate
+ *  (ask.mjs enforces both) — "that" is also a CONTEXT_PRONOUN ("what calls that"),
+ *  so position, not mere presence, decides. This gates the nested/relative and
+ *  same-subject boolean shapes: their absence is exactly what keeps the bare
+ *  reverse-template query "which classes extends Base and couples to logging" out
+ *  of the compositional path (it stays the existing two-strategy ambiguous parse). */
+export const RELATIVE_PRONOUNS = Object.freeze(["that", "which", "who"]);
+
+/** Placeholder object nouns — the indefinite "something" in "what calls something
+ *  that imports X": they name NO entity, they stand in for the inner clause's
+ *  result set. Mapped to entityType null (any grain); a real entity noun in the
+ *  same slot ("what calls modules that import X") narrows the grain instead. */
+export const PLACEHOLDER_NOUNS = Object.freeze([
+  "something", "anything", "everything", "somethings", "things", "thing",
+  "entities", "entity", "nodes", "node", "stuff", "code",
+  // "symbol(s)" is a grain-agnostic stand-in for any code entity — "exported
+  // symbols of X" means whatever X defines, at any grain, filtered by the qualifier.
+  "symbol", "symbols",
+]);
+
+/** Boolean connectives over same-subject clauses -> a set operation on result ids.
+ *  "and" = intersection, "or" = union, "but not"/"and not"/"without"/"except" =
+ *  difference. Multi-word keys are matched longest-first by ask.mjs so "but not"
+ *  wins over a bare "not". Left-associative in ask.mjs's fold. */
+export const BOOLEAN_CONNECTIVES = Object.freeze({
+  "but not": "difference", "and not": "difference", "except": "difference",
+  "without": "difference",
+  "and": "intersection", "plus": "intersection",
+  "or": "union",
+});
+
+/** Subject QUALIFIERS (adjectives) -> a post-filter over the result set, read off
+ *  attributes/edges the graph already carries (codegraph.mjs): `visibility`
+ *  (private/protected present; public is the default/absent), `isStatic`/
+ *  `isConstant`/`isAbstract` boolean attrs, the reexports edge set (exported), and
+ *  the tests edge set (tested/untested). `isAbstract` is never populated by any
+ *  extractor today (codegraph.mjs says so) — "abstract methods" therefore honestly
+ *  returns an empty set, not an error, exactly like any other zero-hit answer. An
+ *  UNKNOWN qualifier is an honest miss naming these supported ones (ask.mjs). */
+export const QUALIFIERS = Object.freeze({
+  public: { via: "visibility", value: "public" },
+  private: { via: "visibility", value: "private" },
+  protected: { via: "visibility", value: "protected" },
+  static: { via: "attr", attr: "isStatic" },
+  abstract: { via: "attr", attr: "isAbstract" },
+  constant: { via: "attr", attr: "isConstant" },
+  exported: { via: "exported" },
+  "re-exported": { via: "exported" },
+  tested: { via: "tested", value: true },
+  covered: { via: "tested", value: true },
+  untested: { via: "tested", value: false },
+  uncovered: { via: "tested", value: false },
+});
+
+/** 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"]);
+
+/** Superlative extremes -> ranking direction. "most/greatest/highest/biggest/
+ *  largest/most-connected" rank descending; "fewest/least/smallest/lowest" rank
+ *  ascending. Read by ask.mjs's parseSuperlative alongside EDGE_NOUN_TO_METRIC. */
+export const SUPERLATIVE_EXTREMES = Object.freeze({
+  most: "most", greatest: "most", highest: "most", biggest: "most",
+  largest: "most", "most-connected": "most", "most connected": "most",
+  fewest: "fewest", least: "fewest", smallest: "fewest", lowest: "fewest",
+});
+
+/** Degree-metric nouns for superlatives ("which module has the most <noun>") ->
+ *  {kind, dir} over the SAME classified edge groups. dir "out" counts edges where
+ *  the ranked entity is the subject (its own imports/calls); "in" counts edges
+ *  where it is the object (its importers/callers/tests). "connections"/"edges"/
+ *  "connected" is the total (both directions, all structural kinds). A `sibling`
+ *  fine-grained kind is added to the tally when present (callers include the
+ *  symbol-grain callsSymbol edges, not just module-coarse calls); a `filter`
+ *  restricts the counted objects to one class ("methods"). */
+export const EDGE_NOUN_TO_METRIC = Object.freeze({
+  imports: { kind: "imports", dir: "out" },
+  dependencies: { kind: "imports", dir: "out" },
+  importers: { kind: "imports", dir: "in" },
+  dependents: { kind: "imports", dir: "in" },
+  callers: { kind: "calls", dir: "in", sibling: "callsSymbol" },
+  callees: { kind: "calls", dir: "out", sibling: "callsSymbol" },
+  calls: { kind: "calls", dir: "out", sibling: "callsSymbol" },
+  methods: { kind: "contains", dir: "out", filter: "Method" },
+  members: { kind: "contains", dir: "out" },
+  tests: { kind: "tests", dir: "in" },
+  subclasses: { kind: "inherits", dir: "in" },
+  connections: { kind: "*", dir: "both" },
+  edges: { kind: "*", dir: "both" },
+  connected: { kind: "*", dir: "both" },
+});
+
+/** Anaphora triggers over the PREVIOUS result set (ask()'s `prev` id array):
+ *  "which of those/them/these …", "how many of those …". The pronoun refers to the
+ *  last answer's ids, not a graph term — with no prev supplied it is an honest miss
+ *  (ask.mjs), never a guess, exactly like an unresolved context pronoun. */
+export const ANAPHORA_TRIGGERS = Object.freeze(["those", "them", "these"]);
+
+/** Membership relations for "<entity> of/in <term>" (qualifier/relative inner
+ *  clauses like "public methods of Widget", "untested functions in walk.mjs") ->
+ *  the forward edge kinds whose subject is <term> and whose objects are the
+ *  members. contains (Class->member) and defines (Module->symbol) are both tried;
+ *  the asked entity type narrows the result. */
+export const MEMBERSHIP_KINDS = Object.freeze(["contains", "defines"]);
+
+// ---- §progressive-relaxation cascade vocabulary (SHRDLU-in-a-code-graph, with a
+// Zork parser's forgiveness) — the three closed, curated tables ask.mjs's relaxParse
+// reads when the DIRECT parse of a query would MISS. The cascade only ever DROPS
+// noise/unmatched words or NORMALISES a near-canonical word to the closed vocabulary;
+// it never invents a term or guesses an entity, and it bottoms out in the same honest
+// rephrase hint. Every entry is hand-curated with inline provenance, same "closed is
+// deliberate" ethos as everything above: a word these tables don't carry is left for
+// the honest miss, never a general-English stoplist that would silently eat a real
+// code term. ----
+
+/** Politeness / filler / vocative / presentation-frame tokens the cascade may strip
+ *  ONE AT A TIME (leftmost first) when a query misses — but only ever a token that is
+ *  NOT itself a content vocabulary word (a relation verb, entity noun, modifier,
+ *  qualifier, aggregate/superlative trigger, …) and does NOT resolve to a graph entity
+ *  (ask.mjs guards both), so a module literally named "show" or "the" is never eaten.
+ *  This is a SUPERSET of the multi-word politeness FILLER_WORDS strips up-front during
+ *  normalization: those handle "could you"/"tell me"/"please" before either parse runs;
+ *  these single tokens catch what a spoken-style question keeps AFTER that pass — the
+ *  bare vocative ("matey"), the article ("the"/"a"), and the presentation frame words
+ *  ("show"/"me"/"list") that the compositional grammar already skips as FRAME_WORDS but
+ *  the keyword-spotting strategy does not, so an un-stripped "show me" otherwise
+ *  decomposes to a bogus ask{subject:"show me"}. Curated, not a general stoplist:
+ *  question words (what/which/…), connectives (and/or), and pronouns (this/it/that)
+ *  are deliberately ABSENT — they carry grammatical weight and must survive. */
+export const CASCADE_NOISE = Object.freeze([
+  // articles / vague determiners (kept OUT of content vocab so they're strippable;
+  // the aggregate/where parsers already tolerate a stray "the"/"a", so stripping is
+  // belt-and-braces, not load-bearing)
+  "the", "a", "an", "some",
+  // 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",
+  "thanks", "thank", "ta", "cheers",
+  // greetings a question sometimes opens with (chat.mjs owns standalone greetings;
+  // here they're only stripped when embedded in an otherwise-real question)
+  "hi", "hello", "hey", "yo", "hiya", "howdy", "ok", "okay",
+  // vocatives / terms of address (the "matey" of the worked example, and its kin)
+  "matey", "mate", "buddy", "pal", "dude", "man", "bro", "bru", "fam",
+  "friend", "sir", "maam", "folks", "guys", "everyone", "dear",
+  // presentation frames — the keyword-spotting strategy's blind spot: the
+  // compositional grammar skips these as FRAME_WORDS, but "show me what imports X"
+  // otherwise decomposes (via keyword-spot) to ask{subject:"show me"}. Stripping
+  // them on a miss recovers the underlying reverse/forward question. ("count" is NOT
+  // here — it is an aggregate trigger; "find"/"search" are here as presentation
+  // verbs, not the seonix_search tool, which ask.mjs never dispatches.)
+  "show", "tell", "give", "list", "find", "me", "us", "lemme",
+]);
+
+/** Near-canonical words the cascade REWRITES to the closed vocabulary once noise and
+ *  unmatched tokens are gone (SYNONYM-NORMALISE, the cascade's third layer). Kept
+ *  deliberately TINY and aggregate-flavoured: the relation/entity synonyms a developer
+ *  actually types already live in RELATIONS/ENTITY_TO_TYPE (and "uses"/"depends on" are
+ *  mapped there); this table only closes the gap for the count family, whose triggers
+ *  (AGGREGATE_TRIGGERS) don't include the "tally the classes"/"total number of classes"
+ *  register. Each key is also kept OUT of the drop pass (ask.mjs treats a synonym key as
+ *  meaningful) so it survives to be normalised rather than dropped as unmatched. The
+ *  rewrite is guarded by ask.mjs (never applied to a token that resolves to a graph
+ *  entity), so a symbol named "total" is never bent into "count". */
+export const CASCADE_SYNONYMS = Object.freeze({
+  tally: "count", tallies: "count", sum: "count", total: "count", totals: "count",
+});
+
+/** Explicit help / orientation requests — when the WHOLE query is one of these, ask.mjs
+ *  shows the rephrase hint DIRECTLY (the honest bottom of the cascade, reached on
+ *  demand) rather than pretending to answer or running the relaxation loop. A closed
+ *  set matched against the whole normalized query only, so "which functions call help"
+ *  (a real question about a symbol named "help") is untouched. Standalone greetings and
+ *  the chat "/help" command are chat.mjs's own surface; this is the bare CLI/MCP ask()
+ *  entry point's equivalent. */
+export const HELP_TRIGGERS = Object.freeze([
+  "help", "help me", "how do i ask", "how do i use this", "what can i ask",
+  "what can you ask", "usage", "commands", "examples", "syntax", "options",
+]);
+
 // ---- omitted-on-purpose (judgment calls, not oversights) -------------------
 // "runs"/"executes" (calls) are common English words with many non-code
 // senses — accepted anyway, formal-template AND keyword-spotting alike,
@@ -256,3 +615,9 @@ export const META_MEANING_VERBS = Object.freeze([
 // alongside"), so g-drop normalization has no bare stem to dialectally
 // contract in the first place; only relations with a genuinely bare-verb
 // casual form ("call", "touch") needed one.
+// WRONG_WORDS not mapped (judgment calls): "script(s)" (routinely names a real
+// module/identifier — rewriting it could corrupt an object term, and file/files
+// already covers the honest synonym); "package(s)" (a genuinely coarser grain
+// this graph doesn't model — mapping it to module would silently answer a
+// different question than the one asked); "fn" (too short and too often a real
+// identifier fragment to rewrite at a word boundary).