@polycode-projects/the-mechanical-code-talker 5.0.6 → 5.0.8

package/README.md

@@ -1,5 +1,15 @@
 # tmct — The Mechanical Code Talker
 
+[![npm version](https://img.shields.io/npm/v/@polycode-projects/the-mechanical-code-talker)](https://www.npmjs.com/package/@polycode-projects/the-mechanical-code-talker)
+[![npm downloads](https://img.shields.io/npm/dm/@polycode-projects/the-mechanical-code-talker)](https://www.npmjs.com/package/@polycode-projects/the-mechanical-code-talker)
+[![licence](https://img.shields.io/npm/l/@polycode-projects/the-mechanical-code-talker)](https://gitlab.com/polycode-projects/the-mechanical-code-talker/-/blob/main/LICENSE)
+[![live demos](https://img.shields.io/badge/demos-tmct.polycode.co.uk-blue)](https://tmct.polycode.co.uk)
+
+> Canonical home: [GitLab](https://gitlab.com/polycode-projects/the-mechanical-code-talker).
+> Installs come from [npm](https://www.npmjs.com/package/@polycode-projects/the-mechanical-code-talker).
+> The [GitHub repo](https://github.com/polycode-public/the-mechanical-code-talker) is a
+> read-only mirror, synced hourly. Issues and merge requests go to GitLab.
+
 `@polycode-projects/the-mechanical-code-talker`
 
 A pure-JS, **no-LLM**, offline, **$0** chatbot in the ELIZA/PARRY lineage.
@@ -85,11 +95,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)
@@ -97,21 +109,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>)
@@ -1493,6 +1509,11 @@ hardened:
 - A nightly **`npm audit` + OSV-Scanner** job watches dependencies.
 - Releases are published with **npm provenance** (`--provenance`).
 
+The npm tarball carries Sigstore-signed provenance naming the GitLab pipeline
+that built it. Every published version also gets a GitLab release tag pinned to
+the exact commit that pipeline ran against. Follow both and an install traces
+back to the source it was built from.
+
 The content-address hash is single-sourced in `src/domain/hash.mjs`, so the
 cross-version-stable fact-id contract has exactly one definition.
 

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.6",
+  "version": "5.0.8",
   "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.",
@@ -96,6 +96,7 @@
     "check:readme": "TMCT_CHECK_README=1 node --disable-warning=ExperimentalWarning --test test-e2e/readme-examples.test.mjs",
     "e2e:browsers": "playwright install chromium",
     "gen:screenshots": "node scripts/gen-screenshots.mjs",
+    "gen:og-images": "node scripts/gen-og-images.mjs",
     "check:links": "node scripts/check-links.mjs",
     "check:pii": "node scripts/pii-lint.mjs",
     "check:pack": "node scripts/check-pack-manifest.mjs",
@@ -153,7 +154,7 @@
     "template:coverage": "node scripts/template-coverage.mjs",
     "audit": "npm audit --audit-level=high",
     "audit:fix": "npm audit fix",
-    "demo:build": "node scripts/build-demo-site.mjs",
+    "demo:build": "node scripts/build-demo-site.mjs && node scripts/gen-og-images.mjs",
     "roll": "node scripts/roll.mjs",
     "build:ask-bundle": "node scripts/build-ask-bundle.mjs",
     "build:chat-bundle": "node scripts/build-chat-bundle.mjs",

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

@@ -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";
@@ -4125,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/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

package/src/domain/memory/capability.mjs

@@ -18,7 +18,7 @@
 //
 // Pure and import-free of core.mjs, exactly like trust.mjs beside it.
 
-import { findIsaChain, SUBCLASS_PREDICATE, TYPE_PREDICATE } from "../syllogise.mjs";
+import { findIsaChain, buildSubClassSuccessors, SUBCLASS_PREDICATE, TYPE_PREDICATE } from "../syllogise.mjs";
 
 /** The negative-polarity CURIE prefix. A separate prefix, never an
  *  "mgx:not-<lemma>" mint: chat.mjs's predicatePhrase reads "mgx:not-fly" as
@@ -78,10 +78,14 @@ const byTrustThenName = (a, b) => (b.trust || 0) - (a.trust || 0) || String(a.su
 
 const asSet = (v) => (v instanceof Set ? v : new Set(Array.isArray(v) ? v : [v]));
 
-const isaEdgesOf = (facts) => ({
-  typeEdges: facts.filter((f) => f.predicate === TYPE_PREDICATE).map((f) => [f.subject, f.object]),
-  subClassEdges: facts.filter((f) => f.predicate === SUBCLASS_PREDICATE).map((f) => [f.subject, f.object]),
-});
+// The ⊑ adjacency is built here, once per call, rather than inside each chase:
+// every caller below chases many subjects over the same edges, and rebuilding
+// the index per chase makes one small search cost the whole edge set.
+const isaEdgesOf = (facts) => {
+  const typeEdges = facts.filter((f) => f.predicate === TYPE_PREDICATE).map((f) => [f.subject, f.object]);
+  const subClassEdges = facts.filter((f) => f.predicate === SUBCLASS_PREDICATE).map((f) => [f.subject, f.object]);
+  return { typeEdges, subClassSucc: buildSubClassSuccessors(subClassEdges) };
+};
 
 /** The shortest isa chain from any spelling of `subjects` up to `target`, or
  *  null. The chase is corpus-INCLUSIVE on purpose, and that is a considered
@@ -90,11 +94,11 @@ const isaEdgesOf = (facts) => ({
  *  would be fabrication. Here the premise being chased to — "bird can fly" — is
  *  itself corpus data on a fresh install, so a taught-only chase would find
  *  nothing to inherit and the whole feature would never fire. */
-function shortestChainTo(subjects, target, typeEdges, subClassEdges, maxHops) {
+function shortestChainTo(subjects, target, typeEdges, subClassSucc, maxHops) {
   let best = null;
   for (const s of subjects) {
     if (s === target) return [];
-    const chain = findIsaChain(s, new Set([target]), typeEdges, subClassEdges, { maxHops });
+    const chain = findIsaChain(s, new Set([target]), typeEdges, subClassSucc, { maxHops });
     if (chain && (!best || chain.length < best.length)) best = chain;
   }
   return best;
@@ -126,7 +130,7 @@ export function resolveCapabilityPolarity(subject, object, facts, { maxHops = 3
   const subjects = asSet(subject);
   const objects = asSet(object);
   const rows = Array.isArray(facts) ? facts : [];
-  const { typeEdges, subClassEdges } = isaEdgesOf(rows);
+  const { typeEdges, subClassSucc } = isaEdgesOf(rows);
 
   const carriers = rows.filter(
     (f) => (f.predicate === CAPABLE_OF_PREDICATE || f.predicate === NEG_CAPABLE_OF_PREDICATE) && objects.has(f.object),
@@ -139,7 +143,7 @@ export function resolveCapabilityPolarity(subject, object, facts, { maxHops = 3
       candidates.push({ fact, polarity, hops: 0, chain: null });
       continue;
     }
-    const chain = shortestChainTo(subjects, fact.subject, typeEdges, subClassEdges, maxHops);
+    const chain = shortestChainTo(subjects, fact.subject, typeEdges, subClassSucc, maxHops);
     if (chain && chain.length) candidates.push({ fact, polarity, hops: chain.length, chain });
   }
 
@@ -212,14 +216,14 @@ export function capabilityBaseRate(subject, object, facts, { maxHops = 3 } = {})
   };
 
   const split = siblings.map(capabilityOf);
-  const { typeEdges, subClassEdges } = isaEdgesOf(rows);
+  const { typeEdges, subClassSucc } = isaEdgesOf(rows);
   return {
     klass,
     kinds: siblings.length,
     positive: split.filter((s) => s.polarity === "positive"),
     negative: split.filter((s) => s.polarity === "negative"),
     unknown: split.filter((s) => s.polarity === "unknown"),
-    chain: shortestChainTo(subjects, klass, typeEdges, subClassEdges, maxHops),
+    chain: shortestChainTo(subjects, klass, typeEdges, subClassSucc, maxHops),
   };
 }
 

package/src/domain/router/drive.mjs

@@ -56,11 +56,14 @@ const refuse = (why, driver) => ({ calls: [], refused: true, terminated: true, p
 
 /** Execute the MEMBER-FILTER HTN method ("which methods of X end up calling Y")
  *  — the per-member hop the single-shot resolver cannot emit on its own. Step 1
- *  grounds members(X) via resolveOne; then, per CALLABLE member (sorted, bounded
- *  by the planner's MAX_STEPS budget), one tmct_callees hop. The fold is
- *  membersReaching (the bounded transitive callsSymbol closure), computed over
- *  the graph, never parsed from text. Honest refuses: no tmct_callees in the
- *  declared toolset, an unbindable filter target, an over-budget member list. */
+ *  grounds members(X) via resolveOne; then, per CALLABLE member (sorted), one
+ *  tmct_callees hop, so long as the whole list fits the planner's MAX_STEPS
+ *  budget. The fold is membersReaching (the bounded transitive callsSymbol
+ *  closure), computed over the graph, never parsed from text — it covers every
+ *  member whether or not the hops were emitted, so a class with more members
+ *  than the plan budget allows gets the same answer with a fold step in the
+ *  proof in place of the hop chain. Honest refuses: no tmct_callees in the
+ *  declared toolset, an unbindable filter target, an ungrounded member list. */
 async function memberFilterDrive(request, tools, ctx, segments) {
   const [setSeg, filterSeg] = segments;
   if (!tools.includes("tmct_callees")) {
@@ -81,29 +84,45 @@ async function memberFilterDrive(request, tools, ctx, segments) {
   const proof = [{ step: "causal-link", producer: "graph", condition: classInd.label, consumer: `step-1:${r1.selected.name}`, role: "action", ok: true }];
   for (const s of r1.proof) proof.push({ ...s, ofStep: 1 });
   const why = [
-    `HTN method: member-filter — enumerate members(${classInd.label}), hop tmct_callees per callable member, fold by bounded transitive reach of ${target.label}`,
+    `HTN method: member-filter — enumerate members(${classInd.label}), fold by bounded transitive reach of ${target.label} over every callable member, and hop tmct_callees per member while that hop chain fits the plan budget`,
     ...(r1.why || []).map((w) => `[1] ${w}`),
   ];
 
   const members = memberIndividuals(ctx.graph, classInd)
     .filter((m) => CALLABLE_MEMBER_CLASSES.has(m.class))
     .sort((a, b) => String(a.label).localeCompare(String(b.label)));
-  if (1 + members.length > MAX_STEPS) {
-    return refuse(`member-filter needs ${1 + members.length} steps (> budget ${MAX_STEPS}) — escalate`, ROUTER_DRIVER);
-  }
-  for (let i = 0; i < members.length; i += 1) {
-    const m = members[i];
-    const res = await ctx.dispatch("tmct_callees", { symbol: m.label });
-    if (!res.ok) return refuse(`the callees hop for ${m.label} did not ground: ${res.error}`, ROUTER_DRIVER);
-    calls.push({ name: "tmct_callees", input: { symbol: m.label } });
-    proof.push({ step: "causal-link", producer: "step-1", condition: m.label, consumer: `step-${i + 2}:tmct_callees`, role: "member-filter", ok: true });
-    why.push(`[${i + 2}] callees hop over ${m.label} (a member step 1 produced)`);
+  // MAX_STEPS bounds the emitted PLAN, not the answer. The fold below reads the
+  // graph's own callsSymbol edges in one pass over every member at any member
+  // count, so a member list too long to walk hop by hop still gets folded — it
+  // just gets no per-member hops. All of them or none: emitting the first seven
+  // of ninety-nine would read as "these are the members I checked", which is a
+  // trace of work nobody did.
+  const hopsFitTheBudget = 1 + members.length <= MAX_STEPS;
+  if (hopsFitTheBudget) {
+    for (let i = 0; i < members.length; i += 1) {
+      const m = members[i];
+      const res = await ctx.dispatch("tmct_callees", { symbol: m.label });
+      if (!res.ok) return refuse(`the callees hop for ${m.label} did not ground: ${res.error}`, ROUTER_DRIVER);
+      calls.push({ name: "tmct_callees", input: { symbol: m.label } });
+      proof.push({ step: "causal-link", producer: "step-1", condition: m.label, consumer: `step-${i + 2}:tmct_callees`, role: "member-filter", ok: true });
+      why.push(`[${i + 2}] callees hop over ${m.label} (a member step 1 produced)`);
+    }
+  } else {
+    proof.push({
+      step: "graph-fold", producer: "step-1", condition: target.label,
+      consumer: `fold:membersReaching(${classInd.label})`, role: "member-filter",
+      members: members.length, hops: 0, ok: true,
+    });
+    why.push(`[2] ${members.length} callable members needs a ${1 + members.length}-step plan against a budget of ${MAX_STEPS}, so no per-member callees hop was dispatched — the fold reads the same callsSymbol edges those hops would have reported, over every one of the ${members.length}`);
   }
 
   const composed = membersReaching(ctx.graph, classInd, target.label);
+  const trace = hopsFitTheBudget
+    ? calls.map((c) => c.name).join(" -> ")
+    : `${calls.map((c) => c.name).join(" -> ")} + graph fold over ${members.length} members`;
   return {
     calls, refused: false, terminated: true, proof, driver: ROUTER_DRIVER, why, composed,
-    observed: `plan(member-filter): ${calls.map((c) => c.name).join(" -> ")} => {${composed.join(", ")}}`,
+    observed: `plan(member-filter): ${trace} => {${composed.join(", ")}}`,
   };
 }
 

package/src/domain/router/resolver.mjs

@@ -36,6 +36,17 @@ const SUPERLATIVE_RE = new RegExp(
   "i",
 );
 
+// A PAST-TENSE report of an action already taken ("I ran the impact of X",
+// "someone called tmct_impact then tmct_untested"). The frames below key on topic
+// words with no tense test, so `\bimpacts?\b` fires on a narration exactly as it
+// does on an instruction and the router re-runs what the speaker said they had
+// already done. Closed and past-tense only, in both the subject and the verb: a
+// present-tense request ("run the impact of X", "I need the impact of X", "if I
+// run impact then the untested scan") must keep binding, so no bare
+// run/check/list here and no subjectless verb.
+const NARRATED_ACTION_RE =
+  /\b(?:i|we|you|they|someone|somebody)\s+(?:just\s+|already\s+|first\s+|then\s+|earlier\s+|previously\s+)?(?:ran|looked|listed|checked|called|did|used|inspected|described|viewed|examined|dumped|traced|printed|queried|opened|walked|pulled)\b/i;
+
 // ---- the ask-kind -> epistemic-topic MAPPING (the Stage-1 core) --------------
 // Keyed `${shape}:${kind}` off parseQuery's output. Every topic must be achievable by
 // exactly one registered capability (the bidirectional conformance test proves it).
@@ -218,6 +229,10 @@ export function mapParse(parse) {
 /** Match an imperative FRAME. Returns { name, arg|noArg, term, topic, source:"frame", why }
  *  or null. Backward-chains the frame's topic to a capability. */
 export function mapFrame(request) {
+  // A narrated trace is a report of work already done. Claiming it here dispatches
+  // that work a second time and calls the data an answer to "what am I trying to
+  // do", so the frames decline and the request goes on to the goal-reasoner.
+  if (NARRATED_ACTION_RE.test(request)) return null;
   for (const f of FRAMES) {
     if (!f.re.test(request)) continue;
     if (f.skipIfSuperlative && SUPERLATIVE_RE.test(request)) continue;
@@ -345,6 +360,40 @@ function testModuleTie(graph, matchInd, candidateInd) {
     || (e.subject === candidateInd.id && e.object === matchInd.id));
 }
 
+/** The tied-read check EVERY binding path runs, so one term cannot mean two
+ *  things down one route and one thing down another. A tie is either
+ *  resolveObject's own score tie (r.ambiguous) or a same-tier candidate the
+ *  graph's `tests` edge ties to the match. Returns the enumerate-or-refuse
+ *  answer — a refusal carrying one dispatched read per tied reading — or null
+ *  when the term names exactly one entity. `siblingTie` is off for a memory-graph
+ *  resolution, which has no code-graph tests-edge notion to check. */
+async function tiedReadRefusal(r, { term, capName, arg, ctx, execute, siblingTie = true }) {
+  const sibling = (siblingTie && !r.ambiguous)
+    ? (r.candidates || []).find((c) => testModuleTie(ctx.graph, r.match, c))
+    : null;
+  if (!r.ambiguous && !sibling) return null;
+  const pool = r.ambiguous ? [r.match, ...(r.candidates || [])].slice(0, 4) : [r.match, sibling];
+  const candidateResults = await dispatchEachCandidate(pool, capName, arg, ctx, execute);
+  const extra = candidateResults
+    ? { candidateResults, candidateCalls: pool.map((c) => ({ name: capName, input: { [arg]: c.label } })) }
+    : undefined;
+  return REFUSE(`"${term}" is ambiguous (${pool.map((m) => m.label).join(", ")}) — narrow it`, extra);
+}
+
+/** The arg key of a bound call's code-graph ENTITY slot, read off the registry's
+ *  own `resolves` precondition rather than a list kept here. A free-text slot
+ *  (tmct_search's query — declared with no resolves precondition) and a
+ *  memory-graph slot both return null, so neither is checked against the code
+ *  graph. Null when the call names no code-graph entity at all. */
+function codeGraphEntityArg(capName, input) {
+  for (const pre of preconditionsOf(capName)) {
+    if (pre.pred !== PRECOND.resolves || MEMORY_KINDS.includes(pre.as)) continue;
+    const arg = parametersOf(capName).find((p) => p.name === pre.param)?.arg ?? pre.param;
+    if (input[arg] != null) return arg;
+  }
+  return null;
+}
+
 /** Select a capability for a request and BIND its arguments — the full resolver.
  *  Order: command register -> NL parse -> imperative frame. Delegates entity binding to
  *  ctx.resolve and, unless `execute:false`, grounds it via ctx.dispatch. Returns
@@ -388,7 +437,18 @@ export async function resolveOne(request, declaredNames, ctx, { execute = true }
   // the two binding oracles never mix on one pick.
   let input = pick.input ? { ...pick.input } : {};
   let resolved = null;
-  if (!pick.input && !pick.noArg) {
+  if (pick.input) {
+    // A command pick arrives already bound, so it skips the binding step below.
+    // The tie check is not part of binding: a term naming two graph entities has
+    // to refuse on this route too, or the terse command form answers what the NL
+    // and frame routes both decline.
+    const entityArg = ctx.resolve ? codeGraphEntityArg(pick.name, input) : null;
+    if (entityArg) {
+      const term = String(input[entityArg]);
+      const tied = await tiedReadRefusal(ctx.resolve(term), { term, capName: pick.name, arg: entityArg, ctx, execute });
+      if (tied) return tied;
+    }
+  } else if (!pick.noArg) {
     const term = String(pick.term || "").trim();
     if (!term) return REFUSE(`the ${pick.topic} intent named no entity to bind`);
     const memoryBound = isMemoryTermSlot(pick.name, pick.arg);
@@ -400,22 +460,8 @@ export async function resolveOne(request, declaredNames, ctx, { execute = true }
         ? `the memory graph holds no facts mentioning "${term}" (honest miss)`
         : `"${term}" does not resolve to any graph entity (honest miss)`);
     }
-    // A tied read: either resolveObject's own score-tie (r.ambiguous), or a same-tier
-    // candidate the graph's own `tests` edge ties to the match (a source module and
-    // its test module — a grain neither side's raw score alone reveals as tied).
-    // resolveMemoryTerm's exact-match tiers have no code-graph tests-edge notion, so
-    // the sibling tie-check only applies on the code-graph resolution path.
-    const sibling = (!memoryBound && !r.ambiguous)
-      ? (r.candidates || []).find((c) => testModuleTie(ctx.graph, r.match, c))
-      : null;
-    if (r.ambiguous || sibling) {
-      const pool = r.ambiguous ? [r.match, ...(r.candidates || [])].slice(0, 4) : [r.match, sibling];
-      const candidateResults = await dispatchEachCandidate(pool, pick.name, pick.arg, ctx, execute);
-      const extra = candidateResults
-        ? { candidateResults, candidateCalls: pool.map((c) => ({ name: pick.name, input: { [pick.arg]: c.label } })) }
-        : undefined;
-      return REFUSE(`"${term}" is ambiguous (${pool.map((m) => m.label).join(", ")}) — narrow it`, extra);
-    }
+    const tied = await tiedReadRefusal(r, { term, capName: pick.name, arg: pick.arg, ctx, execute, siblingTie: !memoryBound });
+    if (tied) return tied;
     resolved = r.match;
     // The frame's own optional slots ride alongside the bound entity — declared
     // params of the same capability, so hallucinationsIn still validates them.

package/src/domain/spider-fly-world.mjs

@@ -37,8 +37,8 @@ export const SPIDER_MASS_DECREMENT_PER_TURN = 0.5;
  *  the town square's own roles object, minus the food entry: nothing inert
  *  lies on a spider-and-fly board, and a null food role is what says so. */
 export const SPIDER_FLY_ROLES = Object.freeze({
-  predator: Object.freeze({ role: "predator", kind: "spider", idPrefix: "spider" }),
-  prey: Object.freeze({ role: "prey", kind: "fly", idPrefix: "fly" }),
+  predator: Object.freeze({ role: "predator", kind: "spider", idPrefix: "spider", hunts: "prey" }),
+  prey: Object.freeze({ role: "prey", kind: "fly", idPrefix: "fly", hunts: null }),
   food: null,
 });