@polycode-projects/seonix 0.3.0 → 0.5.0

package/README.md

@@ -7,13 +7,16 @@ bounded **edit digest** you inject once at session start. Your agent edits from
 turn 1 without fishing through the repo.
 
 > **Headline.** Measured as **mean** input tokens per both-solved task (paired
-> arms, identical model pin): on the Django localisation suite the no-MCP
-> `seonix` digest cut mean input tokens **38% on Haiku 4.5** (`BENCHMARK_016.md`
-> restatement, N=5). Under the score-gap default shipped 2026-07-02 (R1b), the
-> re-tested Django cell on Sonnet 4.6 shows a **41% mean** cut and a C# cell on
-> Sonnet 4.6 shows **57.9% mean**, clearing the ≥50% decision bar. Indexing costs
-> **$0**. The win is model-conditional; full method, numbers and the measurement
-> contract are in the repo.
+> arms, identical model pin). Under the shipped score-gap default (R1b), B017
+> re-tested across three models on a held-out TypeScript corpus and the existing
+> suites: two cells clear the ≥50% decision bar, both on exploration-bound
+> complex tasks — a TypeScript middleware task on **Haiku 4.5 at 59.6%** and a C#
+> service task on **Sonnet 4.6 at 53.5%** — with several more in the 35 to 48%
+> range. Across all measured cells the token cut tracks the turn cut
+> (Pearson 0.91): seonix saves tokens by removing exploration turns, so tasks
+> whose edit site is obvious change little. Indexing costs **$0**. The win is
+> task- and model-conditional; full method, numbers and the measurement contract
+> are in `BENCHMARK_017.md`.
 
 - **Website / live demo:** https://seonix.polycode.co.uk
 - **Source + benchmarks:** https://gitlab.com/polycode-projects/seonix
@@ -49,7 +52,7 @@ removes no turns there is little to save.
 ```bash
 npm i -g @polycode-projects/seonix        # global — gives you the `seonix` bin on PATH
 # or one-shot, no install:
-npx @polycode-projects/seonix index /abs/path/to/repo
+npx @polycode-projects/seonix cli index_repository '{"repo_path":"/abs/path/to/repo"}'
 ```
 
 **Runtime prerequisites:** Node ≥ 24, **Python 3**, and **git** on `PATH` (the
@@ -63,7 +66,7 @@ network calls, **$0**.
 
 ```bash
 # 1. index your repo (deterministic, offline) — writes a machine-local .seonix/
-seonix index /abs/path/to/repo
+seonix cli index_repository '{"repo_path":"/abs/path/to/repo"}'
 
 # 2. self-locate the touched modules from the task text (no human-chosen target)
 seonix cli seonix_search '{"repo_path":"/abs/path/to/repo","query":"<your task>"}'
@@ -118,23 +121,90 @@ in production; pass a known target (`oracle`) only to measure the headroom.
 seonix viz --focus <Symbol> --out graph.html
 ```
 
-Renders a focused, portable Cytoscape sub-graph of the typed code-map as one
-self-contained HTML file, the same view that runs live on the website.
+Renders a focused, portable Cytoscape sub-graph of the typed code-map, the same
+view that runs live on the website. By default it also writes a `code-browser.html`
+and a `timeline.html` beside it with a working header nav; pass `--graph-only`
+for just the single self-contained graph file.
 
 ## Chat
 
 ```bash
-seonix chat [--repo /abs/path]
+seonix chat [--repo /abs/path] [--with-claude | --with-copilot]
 ```
 
-An interactive prompt over the mechanical `seonix_ask` engine (deterministic, no
-model calls): type a question about the indexed codebase — e.g. `which modules
-import walk.mjs` — and the graph answers; `/exit` (or Ctrl+C/Ctrl+D) leaves. Each
-session is appended per turn to `<repo>/.seonix/session-<uuidv7>.log`, and becomes
-first-class graph data like a commit: a structured sidecar
-(`.seonix/sessions/*.jsonl`) records which entities each turn asked about, the
-session enters `graph.json` as a `Session` individual with `mgx:asksAbout` edges
-(re-attached on every re-index), and it appears on the `seonix viz` timeline.
+An interactive client over the typed code-graph (deterministic, no model calls).
+With no `--repo` the target defaults to the **git root** (`git rev-parse
+--show-toplevel`), so running it from a nested package dir still indexes the whole
+repo; pass `--repo <path>` to override. Any **bare line** is a plain-English
+question dispatched through the mechanical `seonix_ask` engine — e.g. `which
+modules import walk.mjs` — and the graph answers. Aggregate questions are answered
+straight off the graph header: `how many classes are there` → `20 classes.`
+(`how many <classes|functions|modules|methods|commits>`, `count the …`, `number of
+…`). A near-miss structural question still gets the precise rephrase hint.
+
+**Conversational manners** (deterministic, zero-model, recognised *before* any graph
+dispatch). A small closed set of everyday expressions gets a templated reply rather
+than a grammar hint:
+
+| you say | you get |
+| --- | --- |
+| `hi` / `hello` / `hey` / `yo` / `g'day` / `good morning` (and `hello there`, with a small nod) | a short greeting + a nudge to ask or `/help` |
+| `thanks` / `ta` / `cheers` / `ty` | an "any time" acknowledgement |
+| `help` / `what can you do` / `who are you` / `?` | the orientation (the friendly help text; see also `/help`, `/stats`) |
+| `bye` / `goodbye` / `quit` / `see ya` | a farewell **and a clean end of session** (flushes the log, closes — the `/exit` path) |
+| `why` / `how` / `explain` / `say more` / `go on` / `elaborate` | **re-renders the last answer verbosely** — repeats it with the ask engine's traversal receipt and the full matched-entity list the terse render trims (no previous answer → it says so plainly) |
+
+These turns resolve no code entity, so — like `/help` — they are recorded as plain
+turns and never add `mgx:asksAbout` edges to the session graph.
+
+**Slash-commands** reach every other query tool in one line each: `/find <query>`
+(or `/search`) for a lexical search; `/context <symbol>` for the sized edit bundle
+(start here to change code) and `/snippet <symbol>` for exact source; `/describe`,
+`/signature`, `/members <class>`, `/subclasses <class>`, `/impact <module>`,
+`/callers`, `/callees`, `/tests <symbol>`, `/untested`, `/history <symbol>`,
+`/exports <module>` and `/arch [package]`, plus `/stats` for a one-screen overview
+(entity counts, relationship counts, package totals). An unknown `/command` just
+nudges you to `/help`; a bad symbol prints the tool's own clean error, never a stack.
+
+The client tracks a **focus** entity for multi-turn context. A command or an answer
+that resolves a primary entity remembers it (the prompt shows it, `seon(walk.mjs)>`);
+a bare `it`/`this`/`that` in a question then binds to it, and a no-argument entity
+command (`/context`, `/impact`, …) reuses it — so `what calls it` works straight
+after `/describe walk.mjs`. Set it explicitly with `/focus <symbol>`. With no focus
+set the client stays single-shot. `/help` lists the commands and the question
+shapes; `/exit` (or Ctrl+C/Ctrl+D) leaves.
+
+Each session is appended per turn to `<repo>/.seonix/session-<uuidv7>.log`, and
+becomes first-class graph data like a commit — **slash-command turns included**: a
+structured sidecar (`.seonix/sessions/*.jsonl`) records each turn's query, the
+command used, and the entities it resolved/answered; the session enters `graph.json`
+as a `Session` individual with `mgx:asksAbout` edges wherever a turn resolved an
+entity (re-attached on every re-index), and it appears on the `seonix viz` timeline.
+
+### Opt-in LLM fallback (`--with-claude` / `--with-copilot`)
+
+**Default OFF. Chat-only. Never in the benchmark, digest, or MCP path.** With a flag
+set, and *only* when the mechanical engine returns a genuine **miss** on a bare
+question (after the conversational layer and slash-commands have had their turn),
+chat consults an external LLM CLI — spawned in the target repo as cwd, with a
+timeout. To keep answers **graph-grounded** it asks the model to *compile one seonix
+command* (given the tool surface), then runs that command mechanically and shows the
+grounded result, **labelled `[LLM-assisted via …]`**. If the model can't produce a
+valid command, its raw text is shown instead, clearly marked `[answer from external
+model … — NOT the deterministic seonix engine]`; the two are never silently blended.
+
+- `--with-claude` → `claude -p "<compile-prompt>" --model haiku` (cheapest model).
+- `--with-copilot` → `gh copilot -- -p "<compile-prompt>" --allow-all-tools --no-color`.
+  **Limitation, honestly:** the GitHub Copilot CLI is an *agentic shell assistant*
+  (its native verbs are running commands and editing files), not a graph Q&A tool —
+  it has no knowledge of the seonix query surface beyond what the prompt hands it, so
+  it's a poorer fit than `claude -p` and is wired best-effort. Prefer `--with-claude`.
+
+Any failure — tool binary absent, non-zero exit, unparseable output, or timeout —
+degrades to the normal honest-miss hint; the flag never crashes or hangs the chat. If
+the flag is set but the binary is missing, chat says so **once at startup** and
+continues mechanical-only. No LLM call is ever made unless the flag is set **and** the
+mechanical engine missed — the hot path (and every benchmark run) stays zero-model.
 
 A real transcript against this repository's own index (verified answers):
 
@@ -170,9 +240,9 @@ a rephrase hint, never a guess.
 
 ## Languages
 
-Python (stdlib `ast`), JS/TS (ts-morph), C# (Roslyn, with a tree-sitter fallback)
-and Java (JavaParser, with a tree-sitter fallback), all merged into the one typed
-graph. The C# Roslyn helper's source ships in the package under `roslyn/`; build
+Python (stdlib `ast`), JS/TS (the TypeScript compiler API, including CommonJS
+`require`/`module.exports`), C# (Roslyn, with a tree-sitter fallback) and Java
+(JavaParser, with a tree-sitter fallback), all merged into the one typed graph. The C# Roslyn helper's source ships in the package under `roslyn/`; build
 it on the consumer side (needs the .NET SDK) if you index C#. The Java JavaParser
 helper is a jar built from the repository's `java/` directory (`mvn package`) and
 is not included in the npm package, so a package install indexes Java with the

package/bin/cli.mjs

@@ -29,7 +29,7 @@
 //   seonix viz [--focus <sym>] [--depth N] [--out f.html] [--data-out f.json] [--repo-url <gitlab url> --ref main] [--site-nav] → render a focused sub-graph to HTML (one shared viewer; data embedded, or split out with --data-out). By default also writes code-browser.html + timeline.html next to --out with a working header nav; --graph-only suppresses the siblings
 //   seonix viz --browser-out f.html [--browser-data-out f.json] [--timeline-out f.html] [--scope product|<prefixes>] → override the sibling artifact paths (Chronograph code browser: temporal scrub + two-cursor diff + narration + ghost-branch merges + keyboard nav; archive/PLAN_CODE_BROWSER.md)
 //   seonix viz --serve [--port N] [--focus <sym>]        → serve the same viewer against THIS repo's index (the local equivalent of the site's #viz; code browser at /code-browser.html, live-reannotating on HEAD change via /code-browser-version)
-//   seonix chat [--repo <abs>]                           → interactive prompt over the mechanical seonix_ask engine; /exit to leave; session log → <repo>/.seonix/session-<uuidv7>.log
+//   seonix chat [--repo <abs>] [--with-claude|--with-copilot] → interactive prompt over the mechanical seonix_ask engine; /exit to leave; session log → <repo>/.seonix/session-<uuidv7>.log. The optional --with-* flags add an opt-in LLM fallback used ONLY when the mechanical engine misses a bare question (chat-only, never in the benchmark path)
 //
 // The index step is offline and model-free (Python ast + git). It writes the
 // graph artifact to <repo_path>/.seonix/graph.json; the server (started with
@@ -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) {
@@ -365,7 +382,13 @@ async function main() {
   if (mode === "chat") {
     const { runChat } = await import("../src/chat.mjs");
     const i = process.argv.indexOf("--repo");
-    await runChat({ repoPath: i !== -1 ? process.argv[i + 1] : undefined });
+    // Opt-in LLM fallback (chat-only, default OFF, miss-gated — never in the benchmark
+    // path): --with-claude shells `claude -p`, --with-copilot shells `gh copilot -- -p`.
+    await runChat({
+      repoPath: i !== -1 ? process.argv[i + 1] : undefined,
+      withClaude: process.argv.includes("--with-claude"),
+      withCopilot: process.argv.includes("--with-copilot"),
+    });
     return;
   }
 
@@ -375,7 +398,7 @@ async function main() {
   }
 
   process.stderr.write(`seonix: unknown invocation "${process.argv.slice(2).join(" ")}". ` +
-    "Use bare (MCP server), `cli index_repository …`, `hook-augment`, or `viz`.\n");
+    "Use bare (MCP server), `cli index_repository …`, `cli <tool> …`, `chat`, `hook-augment`, or `viz`.\n");
   process.exit(2);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/seonix",
-  "version": "0.3.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

@@ -109,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: {
@@ -293,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
@@ -401,6 +418,249 @@ 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). 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
+ *  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",
+  // 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",
+  "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,