@polycode-projects/the-mechanical-code-talker 5.0.5 → 5.0.7

package/README.md

@@ -27,6 +27,7 @@ derive by rule from both. Every answer is either grounded or an honest miss.
 | `data/` | seed data assets: sprites, phrasebook, games, response templates |
 | `ontology/` | the software ontology (`tmct-core.ttl`) and memory shapes, in Turtle |
 | `scripts/` | build, check, and maintenance scripts (`npm run` targets live here) |
+| `infra/` | the AWS CDK app that provisions the deployed site and its OIDC/deploy roles |
 | `examples/` | runnable example scripts and fixture repos used by the README's own examples and the test suite |
 | `demo/` | standalone demo scripts (e.g. the agentic-loop demo) |
 | `electron/` | the Electron desktop app wrapper |
@@ -37,7 +38,7 @@ derive by rule from both. Every answer is either grounded or an honest miss.
 | `reports/` | benchmark write-ups (`BENCHMARK_*.md`) and `PAGE_WEIGHTS.md` — see the root `STATUS.md` for the one-page summary these feed |
 | `playtests/` | numbered playtest session logs, one edge found and fixed per entry |
 | `archive/` | delivered `PLAN_*.md`/`BENCHMARK_*.md` docs, kept for history |
-| `public/` | the built demo site — a gitignored output of `npm run demo:build`, never hand-edited |
+| `public/` | the demo site: the hand-written home page, the eleven about pages, the shared stylesheet and the model/screenshot assets. The demo pages and browser bundles beside them are gitignored build outputs of `npm run demo:build` |
 
 `node_modules/` (dependencies) and dotfiles/hidden tooling directories are omitted above.
 
@@ -84,11 +85,13 @@ tmct> ahab is the father of john
 noted — remembered: ahab fathers john
 
 Goal (inferred): Teach/remember a new fact.
+(this session keeps nothing — the fact is gone when it ends. Run without --ephemeral, or on a stored backend, to keep it.)
 
 tmct> john is the father of ishmael
 noted — remembered: john fathers ishmael
 
 Goal (inferred): Teach/remember a new fact.
+(this session keeps nothing — the fact is gone when it ends. Run without --ephemeral, or on a stored backend, to keep it.)
 
 tmct> a father is a kind of parent
 noted — remembered 1 fact: father rdfs:subClassOf parent (father is a type of parent)
@@ -96,21 +99,25 @@ noted — remembered 1 fact: father rdfs:subClassOf parent (father is a type of
 Goal (inferred): Teach/remember a new fact.
 
 Canonical: does "father" inherits "parent"? — ask(inherits, subject="father", "parent")
+(this session keeps nothing — the fact is gone when it ends. Run without --ephemeral, or on a stored backend, to keep it.)
 
 tmct> remember that ahab is male
 noted — remembered: ahab is male
 
 Goal (inferred): Teach/remember a new fact.
+(this session keeps nothing — the fact is gone when it ends. Run without --ephemeral, or on a stored backend, to keep it.)
 
 tmct> a grandparent is a parent of a parent
 noted — remembered: a grandparent is a parent of a parent
 
 Goal (inferred): Teach/remember a new fact.
+(this session keeps nothing — the fact is gone when it ends. Run without --ephemeral, or on a stored backend, to keep it.)
 
 tmct> a grandfather is a grandparent who is male
 noted — remembered: a grandfather is a grandparent who is male
 
 Goal (inferred): Teach/remember a new fact.
+(this session keeps nothing — the fact is gone when it ends. Run without --ephemeral, or on a stored backend, to keep it.)
 
 tmct> is ahab the grandfather of ishmael
 yes — you told me: ahab fathers john (source: teach:chat:<session-id>@<timestamp>); father is a kind of parent (source: ace:chat:<session-id>@<timestamp>); you told me: john fathers ishmael (source: teach:chat:<session-id>@<timestamp>); you told me: ahab is male (source: teach:chat:<session-id>@<timestamp>)
@@ -319,16 +326,19 @@ tmct> /exit
 
 **[Try it live in your browser →](https://tmct.polycode.co.uk/)**
 runs the actual query engine client-side. No server, no install. The landing
-page answers codebase questions live, and eight more pages each ground their
+page answers codebase questions live, and eleven more pages each ground their
 own domain: a full chat seeded with 63,470 facts (the same nine bands as
 `npm run init:xl`), the
 **memory ledger** (every fact as a readable sentence; drill by clicking the
 terms inside), and the **code explorer** (the same ledger UI refocused on a
 code graph, with a hint rail of suggested next questions). An **ingest
 page** turns pasted or dropped text into grounded facts and downloads them
-as canonical JSONL. The rest are a Towers-of-Hanoi plan replayed move by
-move, the spider-and-fly and text-adventure games, and a sprite gallery
-whose chat dock answers from 1,033 generated sprite facts. The chat page and
+as canonical JSONL, and a **research page** walks a stub wiki graph link by
+link. The rest are a Towers-of-Hanoi plan replayed move by move, the
+spider-and-fly and text-adventure games, a sprite gallery whose chat dock
+answers from 1,480 generated sprite facts, and two multi-agent worlds: a
+burrow that shares one world across browsers over WebRTC, and a Three.js
+town square where a wolf hunts goblins. The chat page and
 the ledger take the same paste-or-drop text in place; every page that holds
 a fact store exports it as JSONL.
 The site hosts its own copy of wink-nlp, ships its assets precompressed,
@@ -373,8 +383,8 @@ functions". Every suggestion resolves to a real answer.
 The identical page also runs as a plain hosted page over the demo code
 graph, with nothing to install:
 **[try it live →](https://tmct.polycode.co.uk/code.html)**.
-The desktop build below is for exploring your own repo or graph, which the
-hosted page cannot reach.
+The desktop build below is for exploring your own repo or graph: a browser page
+gets no filesystem access, so the hosted page reads the demo graph it ships with.
 
 Electron is a dev-only dependency and never ships in the npm package. Because
 `.npmrc` sets `ignore-scripts=true`, installing it does not fetch the runtime
@@ -659,7 +669,7 @@ now consults two shipped, lazily-loaded packs before giving up:
   triples into memory (provenance `child:conceptnet:kettle`, ranked below
   anything you teach) and answers from them; the next ask answers from
   memory directly.
-- `corpus/reference/`: 3,887 Simple English Wikipedia summaries. When the
+- `corpus/reference/`: 3,888 Simple English Wikipedia summaries. When the
   triples cannot answer, a matching article answers as a cited read-out
   (`source: reference article "Otter"…, CC BY-SA 4.0`).
 
@@ -712,7 +722,7 @@ the shipped `npm run example:*` demos) reads a graph but writes nothing back.
 
 The default persona also comes in three sizes: Small (~664 facts, the
 default), Medium (~1,608, `tmct init --persona-size medium`) and Large
-(~13,609, `--persona-size large`, deep enough to chain real multi-hop
+(~13,600, `--persona-size large`, deep enough to chain real multi-hop
 reasoning).
 
 ### Memory backends
@@ -935,6 +945,17 @@ provenance record. Most of its flags choose what gets seeded and where config is
                                in this repo picks it up with no flag needed
 ```
 
+`tmct index` is the producer side of the graph seam. It walks a repo's own source
+and writes the `.tmct/graph.json` that chat, serve and the CLI then read.
+
+```output:help:index
+  tmct index [--repo <abs>]    produce a code graph from a repo's OWN source (default: cwd):
+       [--no-history]          walk the tree, parse JS/TS with the TypeScript compiler
+                               API, read git history, and write <repo>/.tmct/graph.json —
+                               the artifact chat/serve/cli then read. --no-history skips
+                               the git passes (no commit/touches/cochange edges)
+```
+
 `tmct import` does the same activation as `tmct init`, but against a repo that is
 already set up. Its `--graph` flag works differently from the others: it appends to
 `tmct.toml`'s `graph_files` array instead of activating a bundle.
@@ -1055,6 +1076,15 @@ kill $SERVE_PID
        [--graph <path>]        the same thing. --graph names the graph file outright
        [--config <path>]       (repeatable), --config an alternate tmct.toml
   tmct cli digest '{…}'        architecture map + per-module context bundles
+  tmct --help                  show this help
+```
+
+The help closes with two notes on where a chat session runs and what it leaves
+behind:
+
+```output:help:notes
+On a terminal, chat opens the full-screen TUI; piped input gets the plain shell.
+In chat: /help lists slash-commands; /exit leaves. Session log → <repo>/.tmct/session-<id>.md.
 ```
 
 Two precedence chains apply across every command above, in this order:
@@ -1116,6 +1146,12 @@ graph_file = ".tmct/graph.json"
 # Extra graphs, merged alongside graph_file (ids that collide are auto-prefixed).
 graph_files = [".tmct/graph.json", ".tmct/legacy-graph.json"]
 
+[graph]
+# A chat session reads this repo's graph and writes nothing back into its
+# .tmct/: no session upsert, no transcript, no memory. The committed example
+# fixtures set it so `tmct chat --repo examples/<x>` can't rewrite them.
+read_only = false
+
 [corpus]
 # "tier1" (committed slice only, $0/offline, the default), "tier2" (also fetch
 # growable corpora at seed time), or "tier3" (also consult live sources per query).
@@ -1124,6 +1160,8 @@ tier = "tier1"
 [seed]
 enabled = true      # seed the committed corpus into .tmct/memory during init
 limit = 500         # cap the seeded fact count (definitional band first); unset = no cap
+capture_unknown_context = true   # keep the sentence around an unrecognized term
+unknown_context_limit = 200      # cap how many of those contexts are kept
 
 # One [extensions.<name>] table per bundle. A recognized name (human, seon,
 # conceptnet, human-medium, human-large, tier2-aws, tier2-python, tier2-java,
@@ -1177,7 +1215,6 @@ call_adjacency = true       # boost callers/callees of a matched symbol
 impl_of_interface = true    # boost an interface's implementations
 beam_search = true          # use beam search over the graph walk
 beam_width = 8
-embed_rank = false          # rerank by embedding similarity (off by default)
 prose_layers = 2            # how many prose-generation passes to run
 
 [tune.expansion]
@@ -1186,6 +1223,17 @@ nodes = 50                  # node budget for the walk
 q = 0.5                     # expansion breadth parameter
 depth = 3                   # max hops
 
+# Research-lane knobs (src/services/research.mjs).
+[research]
+fanout_limit = 8            # links followed per page
+max_depth = 3               # hops from the starting topic
+max_topics = 40             # topics visited in one crawl
+min_interval_ms = 1000      # politeness delay between fetches
+
+# Discourse record (src/domain/discourse.mjs).
+[discourse]
+max_referents = 12          # how many referents stay resolvable across turns
+
 [telemetry]
 enabled = false             # local-only counters; never phones home
 
@@ -1202,10 +1250,13 @@ spider_initial_mass = 15
 spider_mass_decrement_per_turn = 0.5   # lower = slower to starve
 fly_initial_mass = 10
 fly_mass_decrement_per_turn = 1
-vision_radius = 4                      # Chebyshev radius an agent can see other agents within
+spider_vision_radius = 4               # Chebyshev radius a spider sees other agents within
+fly_vision_radius = 4                  # the same radius for a fly
 egg_hatch_delay_turns = 3              # turns between a lay and its hatch
 fly_spawn_interval_turns = 3           # a new fly arrives every Nth turn
-eggs_eaten_threshold = 2               # flies eaten since the last egg before the next one lays
+egg_lay_mass_threshold = 25            # mass a spider must reach before it lays
+egg_hatch_count = 2                    # hatchlings per egg
+min_hatchling_mass = 3                 # mass a hatchling starts with
 web_duration_turns = 10                # turns a spider-built web stays active
 
 [games.guess-number]
@@ -1219,8 +1270,9 @@ max_depth = 300  # the "solve it" plan lane's search-depth cap (hanoi, river-cro
 
 ### Try it on an example graph
 
-tmct *consumes* a code graph at `<repo>/.tmct/graph.json`. It does not build
-one. Two ready-made example graphs live in `examples/` in this repo (clone the
+tmct reads a code graph at `<repo>/.tmct/graph.json`. `tmct index` builds one
+from a repo's own source, and any other producer can write the same file. Two
+ready-made example graphs live in `examples/` in this repo (clone the
 repo to use them; they are not in the published npm package), so you can see
 it answer real questions with no setup:
 
@@ -1402,7 +1454,7 @@ and transcripts are in the linked write-ups.
 | Determinism | Byte-identical on rerun: a 379-case `--replay` clean across 2 runs, no LLM, no network, $0 per turn | A property of the no-model pipeline. | `archive/BENCHMARK_INFERENCE_2.7.12.md` |
 | Dialogue robustness (persona sweep) | A 6-persona sweep (textbook logician, casual newcomer, new developer, adversarial sceptic, returning user, planning user) fixed 25 of the prior cycle's 29 routed findings (21 clean, 4 with a residual noted); 4 remain broken, 2 in a shape distinct from the original complaint | Free exploration across all six personas surfaced roughly 60 fresh findings beyond the ratchet check. The single highest-signal pattern: tmct's own suggested repair text was itself frequently broken when followed verbatim (since fixed, see `NEXT.md`). | `archive/BENCHMARK_CONVERSATION_2.7.11.md` |
 
-Three offline benchmark rigs live in a clone (they are not in the npm
+Seven offline benchmark rigs live in a clone (they are not in the npm
 package). Each replays a committed case set through the real product and
 writes graded rows you can diff between runs:
 
@@ -1412,7 +1464,14 @@ writes graded rows you can diff between runs:
 - `npm run infbench` generates inference cases, then runs each through both
   drive points, the reasoning kernel and the chat surface;
 - `npm run agentbench:run` measures the tool-loop behaviour, and every
-  verdict carries a hallucination axis.
+  verdict carries a hallucination axis;
+- `npm run idxbench:run` grades how faithfully the code-index producer
+  restates source as a graph;
+- `npm run ingestbench:run` (with `ingestbench:judge`) grades text-to-facts
+  extraction;
+- `npm run researchbench:run` grades the research lane's link traversal
+  against a frozen stub wiki graph;
+- `npm run synthbench:code` grades deterministic code synthesis.
 
 The smallest real slice of each, the same invocations the test suite's
 bench-smoke lane replays:
@@ -1457,7 +1516,7 @@ tmct's vocabulary is grounded in published standards where they exist, and says
 Each alignment below is a triple in `ontology/tmct-core.ttl` and a test in
 `test/adapters/grammar-ontology.test.mjs`. `docs/references/` holds an entry per source: the
 edition, the retrieval date, the terms tmct uses, and what could not be verified.
-`PLAN_NORMATIVE.md` holds the reconciliation, one verdict per term.
+`archive/PLAN_NORMATIVE.md` holds the reconciliation, one verdict per term.
 
 ### The data model
 
@@ -1476,7 +1535,7 @@ edition, the retrieval date, the terms tmct uses, and what could not be verified
 | [Attempto Controlled English](http://attempto.ifi.uzh.ch/site/docs/) | ACE 6.7, 2013 | The controlled-English fragment. tmct implements 9 of ACE's declarative sentence patterns. |
 | Kuhn, "A Survey and Classification of Controlled Natural Languages" | *Computational Linguistics* 40(1), 2014 | Where ACE sits among controlled languages. |
 | [ConceptNet](https://github.com/commonsense/conceptnet5/wiki/Relations) | slice pins 5.7.0 | The commonsense corpus. 25 relations are mirrored into `mgx:` and each cites its `/r/` origin. |
-| Damerau, *CACM* 7(3), 1964 · Levenshtein, *Soviet Physics Doklady* 10(8), 1966 | — | Fuzzy matching. `fuzzy.mjs` implements **Optimal String Alignment** — restricted Damerau-Levenshtein, which allows adjacent transposition but edits no substring twice. |
+| Damerau, *CACM* 7(3), 1964 · Levenshtein, *Soviet Physics Doklady* 10(8), 1966 | — | Fuzzy matching. `src/domain/interpret/fuzzy.mjs` implements **Optimal String Alignment** — restricted Damerau-Levenshtein, which allows adjacent transposition but edits no substring twice. |
 
 ### Reasoning and planning
 
@@ -1492,7 +1551,7 @@ edition, the retrieval date, the terms tmct uses, and what could not be verified
 
 | source | edition | what tmct uses it for |
 |---|---|---|
-| Jensen et al., "A Consensus Glossary of Temporal Database Concepts" | *SIGMOD Record* 23(1), 1994 | The time vocabulary. `mgx:utteranceTs` is valid time; `mgx:createdAt` is a transaction-time start. tmct is **not** bitemporal: `mgx:updatedAt` is an audit stamp, so tmct cannot answer what it believed last Tuesday. |
+| Jensen et al., "A Consensus Glossary of Temporal Database Concepts" | *SIGMOD Record* 23(1), 1994 | The time vocabulary. `mgx:utteranceTs` is valid time; `mgx:createdAt` is a transaction-time start. tmct is **not** bitemporal: `mgx:updatedAt` is an audit stamp, so "what did it believe last Tuesday" lands on the honest miss wall. |
 | RFC 9923, "The FNV Non-Cryptographic Hash Algorithm" | Informational, 2026 | FNV hashes the narrow non-fact-id pools (paraphrase keys, per-URL source ids, corpus dedupe). Fact ids are content-addressed with a **64-bit truncation of SHA-256**, so a fact id is collision-resistant at tmct's corpus sizes; tmct is still **not** a Merkle tree and offers no tamper-evidence. |
 | Green, Karvounarakis, Tannen, "Provenance Semirings" | PODS 2007 | The distinction tmct's docs keep: it records source annotation and PROV-style attribution, not how-provenance. |
 

package/bin/tmct.mjs

@@ -183,6 +183,34 @@ async function runDigest(args, { dispatchTool, buildContextBundle, source, confi
   process.stdout.write([header, ...body].join("\n") + "\n");
 }
 
+/** The conversational memory store's vocabulary reader, bound to whatever store
+ *  the target repo already has. `cli tmct_ask` and chat answer over the same
+ *  `--repo`, so a term chat knows used to come back from the cold route as a
+ *  miss purely because the cold route reads the code graph and nothing else.
+ *
+ *  Read-only by construction: the reader is handed a throwaway in-memory copy
+ *  of the store, so a repo with no memory yet stays that way (opening a backend
+ *  would create one) and nothing a reader writes reaches disk. `{ factLookup:
+ *  null }` when the repo has no store, which leaves the graph-only answer. */
+async function openColdMemoryReader(config) {
+  const empty = { factLookup: null, close: async () => {} };
+  if (!config?.graphFile) return empty;
+  const { dirname: dirnameOf } = await import("node:path");
+  const repoRoot = dirnameOf(dirnameOf(config.graphFile));
+  const { openExistingMemoryBackend, readOnlyMemorySnapshot } = await import("../src/adapters/memory/core.mjs");
+  const store = await openExistingMemoryBackend(repoRoot);
+  if (!store) return empty;
+  let snapshot = null;
+  try { snapshot = await readOnlyMemorySnapshot(store.dir); }
+  finally { await store.close(); }
+  if (!snapshot) return empty;
+  const { factAnswer } = await import("../src/services/chat.mjs");
+  return {
+    factLookup: (query, envelope) => factAnswer(snapshot, query, envelope, true),
+    close: async () => {},
+  };
+}
+
 /** The carried `cli` dispatcher (digest / tmct_locate / any-tool fallback).
  *  Imports are lazy so `tmct --help` and chat startup never pay for the tool
  *  stack. */
@@ -266,15 +294,18 @@ async function runCliMode() {
       process.exit(2);
     }
     const config = await configFor(args.repo_path);
+    const memory = await openColdMemoryReader(config);
     try {
       // The recognizer seam a tool like tmct_ingest needs: injected here (bin
       // sits above the service layer) rather than imported by the tool layer.
       const { ingestText } = await import("../src/services/extract-facts.mjs");
-      const text = await dispatchTool(sub, args, { config, ingest: ingestText });
+      const text = await dispatchTool(sub, args, { config, ingest: ingestText, factLookup: memory.factLookup });
       process.stdout.write(text + "\n");
     } catch (e) {
       process.stderr.write(`tmct: ${e?.message || e}\n`);
       process.exit(1);
+    } finally {
+      await memory.close();
     }
     return;
   }
@@ -540,7 +571,12 @@ async function buildEngineBundleJs(builderFile) {
   }
   const dir = await mkdtemp(join(tmpdir(), "tmct-render-"));
   try {
-    const { outPath } = await build(dir);
+    // Quiet: this build is an implementation detail of writing one page. Its
+    // esbuild log is eleven "import.meta is not available with the iife output
+    // format" warnings about Node-only paths the browser entry never reaches,
+    // and they arrived ahead of the single line the user asked for. A build
+    // script still prints them — its reader is a developer.
+    const { outPath } = await build(dir, { quiet: true });
     return await readFile(outPath, "utf8");
   } finally {
     await rm(dir, { recursive: true, force: true });
@@ -603,8 +639,33 @@ async function writeStandaloneViewPage(archetype, rest) {
   process.stdout.write(`wrote ${outPath} (${(Buffer.byteLength(html, "utf8") / 1024).toFixed(0)} KB, self-contained)\n`);
 }
 
+/** Refuse a `--repo` that names nothing on disk, before any verb gets to create
+ *  it. Eight verbs open a memory store under the path they are handed, and the
+ *  store's own mkdir is recursive, so a mistyped path used to be scaffolded in
+ *  silence — a fresh tmct.toml, a .tmct/ tree, 688 seeded facts — and the
+ *  answer came back as if the repo were the one meant. `init` is the one verb
+ *  whose whole job is to create a repo from nothing, so it never reaches here. */
+async function refuseMissingRepoPath(argv) {
+  const i = argv.indexOf("--repo");
+  const given = i !== -1 ? argv[i + 1] : null;
+  if (!given || given.startsWith("--")) return;
+  const { resolve } = await import("node:path");
+  const { stat } = await import("node:fs/promises");
+  const abs = resolve(process.cwd(), given);
+  let entry = null;
+  try { entry = await stat(abs); } catch { entry = null; }
+  if (entry?.isDirectory()) return;
+  const where = abs === given ? given : `${given} (${abs})`;
+  process.stderr.write(entry
+    ? `tmct: --repo ${where} is not a directory.\n`
+    : `tmct: --repo ${where} does not exist. Nothing was created. `
+      + `Check the path, or run \`tmct init --repo ${given}\` to make a repo there.\n`);
+  process.exit(2);
+}
+
 async function main() {
   const mode = process.argv[2];
+  if (mode !== "init") await refuseMissingRepoPath(process.argv.slice(3));
 
   if (mode === "chat") {
     const rest = process.argv.slice(3);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "5.0.5",
+  "version": "5.0.7",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; indexes a repo on request (tmct index) or reads any producer's graph.",

package/src/adapters/memory/core.mjs

@@ -698,6 +698,29 @@ export async function openMemoryBackend(repoRoot, backendChoice) {
   return { dir: handle, close: async () => closeSqliteMemoryStore(handle) };
 }
 
+/** openMemoryBackend for a caller that only wants to READ what a repo already
+ *  holds: null when the repo has no store yet, because opening one creates it.
+ *  The cold surfaces (the `cli` tool route) answer over a repo they were merely
+ *  pointed at, and must leave a repo with no memory exactly as they found it. */
+export async function openExistingMemoryBackend(repoRoot, backendChoice = "") {
+  if (!repoRoot || typeof repoRoot !== "string") return null;
+  const dbPath = join(repoRoot, ".tmct", "memory", "graph.sqlite");
+  try { await access(dbPath); } catch { return null; }
+  return openMemoryBackend(repoRoot, backendChoice);
+}
+
+/** A throwaway in-memory COPY of a store's facts: readers answer from the real
+ *  data, and anything a reader writes lands in the copy rather than on disk.
+ *  What a surface with no session behind it (the `cli` tool route, the HTTP
+ *  messages endpoint) hands a reader that expects a memory handle, so a cold
+ *  answer matches a chat answer without the cold call gaining a write. */
+export async function readOnlyMemorySnapshot(memoryDir) {
+  if (!memoryDir) return null;
+  const snapshot = createInMemoryStore();
+  applySeedPayload(snapshot, cloneMemoryPayload(await loadMemory(memoryDir)));
+  return snapshot;
+}
+
 /** openMemoryBackend for an entry point that holds only a repo path and has no
  *  CLI-flag tier (the fold's idle pass, `tmct import --file`): resolve the
  *  backend token the way the chat path does minus the flag —

package/src/domain/ask-vocab.mjs

@@ -396,6 +396,25 @@ export const VERB_TO_KIND = Object.freeze(
  *  builds never collide on the same top-level identifier. */
 export const HAS_FAMILY_VERBS = Object.freeze(new Set(["has", "have", "holds", "hold"]));
 
+/** Every action-flavored word in RELATIONS.calls.verbs ("run(s)", "execute(s)",
+ *  "invoke(s)", "trigger(s)", "fire(s)", "hit(s)", "kick(s) off") also opens an
+ *  imperative request for a NAMED REPORT ("run the impact of X", "trigger the
+ *  untested scan") — the router's own capability labels (registry.mjs), not a
+ *  code-graph relation. "run"/"execute" earn the calls kind because "which
+ *  functions run X" is a genuine reverse-calls question, so the collision can't
+ *  be fixed by dropping them from RELATIONS.calls; instead grammar.mjs and
+ *  keywords.mjs check this set before reading the calls kind's object, so
+ *  "impact"/"untested"/… stay the report the sentence names rather than
+ *  becoming the leading word of a term nothing will ever resolve. Curated
+ *  against registry.mjs's own capability labels — a new capability's label
+ *  needs adding here too, the same discipline CASCADE_FUZZY_REAL_WORDS
+ *  (ask.mjs) already uses for "impact" on the fuzzy-correction side. */
+export const CALLS_VERB_REPORT_NOUNS = Object.freeze(new Set([
+  "search", "describe", "signature", "impact", "members", "subclasses",
+  "exports", "callers", "callees", "calls", "tests", "untested", "history",
+  "cochanges", "architecture", "arch", "related", "sprite",
+]));
+
 /** "what is a kind of X" / "what is a subclass of X" collision fix: some
  *  inherits verbs are themselves phrased "is a <continuation>", which would
  *  otherwise collide with grammar.mjs's literal meta-whatis reading and

package/src/domain/ask.mjs

@@ -15,7 +15,7 @@
 // ask.mjs's own `touches`/`cochange` verbs answer one-hop structural edges
 // (mgx:touchedByCommit / mgx:changeCoupledWith).
 
-import { relationKind, impactClosure, moduleCountOf, normPath, packageCounts, modulesOf, HISTORY_CAP } from "./codegraph.mjs";
+import { relationKind, impactClosure, moduleCountOf, normPath, packageCounts, modulesOf, HISTORY_CAP, NO_CODE_INDEX_NOTE } from "./codegraph.mjs";
 import { isTestPath } from "./module-paths.mjs";
 import {
   RELATIONS,
@@ -27,7 +27,7 @@ import {
   AGGREGATE_TRIGGERS, LIST_TRIGGERS, SUPERLATIVE_EXTREMES, EDGE_NOUN_TO_METRIC, METRIC_IMPLIES_ENTITY, ANAPHORA_TRIGGERS,
   MEMBERSHIP_KINDS, CASCADE_NOISE, CASCADE_SYNONYMS, HELP_TRIGGERS,
   WORLD_RELATIONS, WORLD_NOUN_TO_RELATION, WORLD_PREDICATES, locativePreposition,
-  stripTrailingScopeFiller, stripTrailingTemporalAdverb,
+  stripTrailingScopeFiller, stripTrailingTemporalAdverb, CALLS_VERB_REPORT_NOUNS,
 } from "./ask-vocab.mjs";
 import { expandContractions, normalizeQuery, applyNegationFrames, applyPhrasingFrames, matchNegationSet, STOPWORDS, splitWords, wordsOf, escapeRegex } from "./interpret/normalize.mjs";
 import { editDistance, fuzzyBound } from "./interpret/fuzzy.mjs";
@@ -2491,9 +2491,7 @@ export function rephraseHint() {
  *  graph is UNKNOWN, not empty (see chat.mjs's noCodeGraph), so it keeps the
  *  index-shaped advice. */
 function touchesRephraseHint(graph = null) {
-  if (graph && moduleCountOf(graph) === 0) {
-    return "This store holds no code index, so it records no modules or commits to look through.";
-  }
+  if (graph && moduleCountOf(graph) === 0) return NO_CODE_INDEX_NOTE;
   return 'Try "who touched <a module that actually has commits>" or "/describe <module>" to see what\'s in the index.';
 }
 
@@ -4127,6 +4125,13 @@ const CONTENT_VOCAB = new Set([
   ...wordsOf(PLACEHOLDER_NOUNS), ...wordsOf(ANAPHORA_TRIGGERS), ...wordsOf(META_MEANING_VERBS),
   ...wordsOf(WHERE_MARKERS), ...wordsOf(MENTION_MARKERS), ...wordsOf(RELATIVE_PRONOUNS),
   ...wordsOf(Object.keys(CASCADE_SYNONYMS)),
+  // "impact"/"untested"/… (CALLS_VERB_REPORT_NOUNS) name the report an imperative
+  // "run"/"execute"/"trigger" sentence is asking for. Without this, the drop-
+  // unmatched pass below reads a report noun as packaging around a "calls"
+  // reverse-question object it never was, drops it, and turns "run the impact
+  // of X" into the confidently WRONG answer "what calls X" instead of the
+  // honest miss keywords.mjs's own guard already declines the direct parse to.
+  ...wordsOf([...CALLS_VERB_REPORT_NOUNS]),
 ]);
 
 /** Structural scaffolding words — question words, frame verbs, context

package/src/domain/codegraph.mjs

@@ -57,6 +57,10 @@ export function moduleCountOf(graph) {
   return graph.individuals.filter((i) => (i.class || "") === "Module").length;
 }
 
+/** What a store with zero modules actually holds, said once so every lane that
+ *  has to decline for that reason declines in the same words. */
+export const NO_CODE_INDEX_NOTE = "This store holds no code index, so it records no modules or commits to look through.";
+
 // ---- relation-kind classifier (for impact + tests-coverage) -------------------
 
 const KINDS = ["imports", "calls", "defines", "tests", "touches", "contains", "inherits", "callsSymbol", "touchesSymbol"];
@@ -1360,7 +1364,13 @@ export function renderTestsFor(graph, ind) {
 }
 
 /** Source modules with no covering test module — a coverage gap view. Test
- *  modules (subjects of test edges, or test-named paths) are excluded. */
+ *  modules (subjects of test edges, or test-named paths) are excluded.
+ *
+ *  "Nothing is uncovered" and "I hold nothing to look at" are opposite
+ *  statements, so the empty survey has to say which one it means: with no
+ *  source module recorded there is no coverage claim to make at all, and the
+ *  full-coverage sentence would be an assertion about a repo this store has
+ *  never seen. */
 export function renderUntested(graph) {
   const covered = new Set();
   const testModules = new Set();
@@ -1368,14 +1378,18 @@ export function renderUntested(graph) {
     covered.add(e.object);
     testModules.add(e.subject);
   }
-  const untested = graph.individuals
-    .filter(
-      (i) =>
-        (i.class || "") === "Module" &&
-        !testModules.has(i.id) &&
-        !isTestPath(String(i.label).toLowerCase()) &&
-        !covered.has(i.id),
-    )
+  const sourceModules = graph.individuals.filter(
+    (i) => (i.class || "") === "Module"
+      && !testModules.has(i.id)
+      && !isTestPath(String(i.label).toLowerCase()),
+  );
+  if (!sourceModules.length) {
+    return moduleCountOf(graph) === 0
+      ? `no modules to check for test coverage in this index. ${NO_CODE_INDEX_NOTE}`
+      : "no source modules to check for test coverage in this index — only test modules are recorded.";
+  }
+  const untested = sourceModules
+    .filter((i) => !covered.has(i.id))
     .map((i) => i.label)
     .sort();
   if (!untested.length) return "every source module has at least one covering test module.";

package/src/domain/game-config.mjs

@@ -90,6 +90,16 @@ export const DEFAULT_GAME_CONFIG = Object.freeze({
     // this is the one switch that turns that off (visionRadius: Infinity for
     // the food-only belief call) without any new belief machinery.
     foodVisionGated: true,
+    // Whether prey weigh the predator and the crumb in one score instead of
+    // running the evade rung ahead of the forage one. Off by default: strict
+    // priority is what ships, and the blend is the alternative a comparison
+    // run measures against it (scripts/compare-prey-decision.mjs).
+    blendPreyDecision: false,
+    // How much of that score belongs to keeping away from the predator, with
+    // the rest going to closing on food. 1 evades exactly as the priority
+    // chain does, 0 ignores the predator, and the middle takes a crumb that
+    // costs little distance. Read only when blendPreyDecision is on.
+    preyThreatWeight: 0.5,
     // Whether the town-square lane accepts teaching. Its own knob rather than
     // a share of the adventure one below: the board's sentence table is a
     // different vocabulary, and a page checkbox on the town square should not
@@ -166,6 +176,8 @@ const MUDIII_KEY_MAP = Object.freeze({
   max_prey_population: "maxPreyPopulation",
   max_food_items: "maxFoodItems",
   food_vision_gated: "foodVisionGated",
+  blend_prey_decision: "blendPreyDecision",
+  prey_threat_weight: "preyThreatWeight",
   teach: "teach",
 });
 

package/src/domain/interpret/strategies/keywords.mjs

@@ -8,7 +8,7 @@
 import {
   VERB_TO_KIND, ENTITY_TO_TYPE, MODIFIER_TO_KIND,
   WHERE_MARKERS, MENTION_MARKERS, PLACEHOLDER_NOUNS, PASSIVE_PARTICIPLE_TO_KIND,
-  INHERITS_REVERSE_VERBS, HAS_FAMILY_VERBS,
+  INHERITS_REVERSE_VERBS, HAS_FAMILY_VERBS, CALLS_VERB_REPORT_NOUNS,
 } from "../../ask-vocab.mjs";
 import { STOPWORDS } from "../normalize.mjs";
 import { VOCAB_WORDS, eligibleForCanon, fuzzyVocabWord } from "../fuzzy.mjs";
@@ -29,6 +29,33 @@ const TEMPORAL_TRAILING_ADVERBS = new Set(["recently", "lately", "yet", "already
 // below (the forward/reverse branches keep their own tested grain-check
 // decline, per that constant's own docblock).
 
+/** "run the impact of X" / "if I run impact on X": a calls-kind object phrase
+ *  led by one of ask-vocab.mjs's CALLS_VERB_REPORT_NOUNS, with a further word
+ *  after it, is the report the sentence is naming, not the start of a code-graph
+ *  term — reading "impact app/lib/a.mjs" as one term answers a question nobody
+ *  asked and can never resolve. A BARE single-word object ("what calls impact")
+ *  is left alone: that's the genuine, structurally identical question about a
+ *  symbol that happens to be named "impact", and there's no local signal to
+ *  tell the two apart, so this only declines the shape a real report request
+ *  actually takes. */
+function leadsWithCallsReportNoun(objectText) {
+  const words = objectText.trim().split(/\s+/);
+  return words.length > 1 && CALLS_VERB_REPORT_NOUNS.has(words[0].toLowerCase());
+}
+
+/** "run the calls of X": CALLS_VERB_REPORT_NOUNS includes "calls" itself (the
+ *  tmct_calls edge-dump label), and findPhrase (above) matches phrases in
+ *  table-order rather than leftmost-in-sentence — for kind "calls" that order
+ *  puts the literal word "calls" ahead of "run", so verbHit lands on "calls"
+ *  (mid-sentence) instead of "run" (sentence-initial), and "run" survives as
+ *  the ask-shape's SUBJECT instead of being read as the imperative lead. A
+ *  subject that is itself nothing but one of the calls kind's own verb words
+ *  is that same misread, one hop further along — decline it here rather than
+ *  reordering findPhrase's table, which every other kind's lookup shares. */
+function isBareCallsVerbWord(text) {
+  return VERB_TO_KIND[text.trim().toLowerCase()] === "calls";
+}
+
 /** Find the longest phrase from `table`'s keys that appears as a contiguous
  *  run of `words` (case already lowercased by the caller). Longest-match-first
  *  (multi-word phrases before single words) so "co-changes with" isn't
@@ -289,6 +316,7 @@ export function parseKeywordSpot(text, nlp = null) {
     // the entityType-driven forward/reverse branches below, which keep their
     // own tested grain-check decline.
     if (kind === "defines" && HAS_FAMILY_VERBS.has(verbPhrase)) return null;
+    if (kind === "calls" && (leadsWithCallsReportNoun(afterText) || isBareCallsVerbWord(beforeText))) return null;
     // A semantically-reverse verb ("superclass of") swaps subject/object, same as
     // grammar.mjs's T1.
     let subject = beforeText;
@@ -297,6 +325,7 @@ export function parseKeywordSpot(text, nlp = null) {
     return stamp({ shape: "ask", entityType: null, modifier: "direct", kind, subject, object });
   }
   if (afterText) {
+    if (kind === "calls" && leadsWithCallsReportNoun(afterText)) return null;
     // A type word riding beside the named object ("what uses the Store
     // CLASS") describes the OBJECT's grain — it says which "Store" is meant,
     // not what class of thing may answer. Reading it as the result filter