@polycode-projects/the-mechanical-code-talker 1.8.17 → 1.8.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "1.8.17",
+  "version": "1.8.20",
   "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; no codebase index of its own.",

package/src/ask.mjs

@@ -3514,22 +3514,44 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
         widenNote = `, widened to ${siblingClass} subjects (no ${entityType} recorded)`;
       }
     }
-    // "touches" up-refine composability (HANDOVER 2026-07-12, Class-to-module
-    // up-refinement): an EMPTY touchesSymbol lookup on a resolved CLASS is not
-    // decisive the way it is for a Function/Method — a Class reads naturally as
-    // "the file/unit that holds it", so "who touched <Class>" with no recorded
-    // symbol-precise touch should still answer from the class's containing
-    // module's real touches, rather than a confident-looking-but-possibly-wrong
-    // "nothing touched it". Fall through to the grain-aware up-refine below
-    // ONLY for that Class case. Deliberately NOT widened to every
-    // FINE_ENTITY_TYPES member: "how many commits touched fnAlpha" (a Function)
-    // is pinned elsewhere (ask-combo.test.mjs's grain-aware COUNT lever) to stay
-    // an honest 0 rather than a module-grain false hit — symbol-level counting
-    // precision for functions/methods is a deliberate, separate guarantee this
-    // change must not erode. `calls` is untouched either way: an empty
-    // callsSymbol result stays decisive (call parsing isn't a best-effort
-    // heuristic the way commit-diff symbol attribution is).
-    if (matches.length || !(kind === "touches" && objMatch.class === "Class")) {
+    // "touches"/"calls" up-refine composability (HANDOVER 2026-07-12, Class-to-
+    // module up-refinement; extended to `calls` in the 2026-07-12 follow-up —
+    // "who calls Router" wrongly returned empty for a Class whose calls are only
+    // recorded at module-coarse grain): an EMPTY touchesSymbol/callsSymbol lookup
+    // on a resolved CLASS is not decisive the way it is for a Function/Method — a
+    // Class reads naturally as "the file/unit that holds it", so "who touched
+    // <Class>"/"who calls <Class>" with no recorded symbol-precise edge should
+    // still answer from the class's containing module's real touches/calls,
+    // rather than a confident-looking-but-possibly-wrong "nothing touched/calls
+    // it". Deliberately NOT widened to every FINE_ENTITY_TYPES member: "how many
+    // commits touched fnAlpha" (a Function) is pinned elsewhere (ask-combo.test.mjs's
+    // grain-aware COUNT lever) to stay an honest 0 rather than a module-grain
+    // false hit — symbol-level counting precision for functions/methods is a
+    // deliberate, separate guarantee this change must not erode.
+    //
+    // Up-refine eligibility is gated on the Class having NO recorded `contains`
+    // members: a class the extractor actually populated (Widget, Logger — both
+    // carry real `contains` edges) reads as a fully-modeled unit whose own empty
+    // symbol-grain scan IS the honest answer; a class with zero recorded members
+    // (Router, Button — the extractor only ever saw its declaration, never a
+    // body) is exactly the shape where the coarser module-level edge is the only
+    // real signal recorded at all.
+    //
+    // Even when eligible, only actually fall through to the shared grain-aware
+    // up-refine block below when a containing module can be resolved RIGHT NOW.
+    // That block's own "no containing module found" case renders a DIFFERENT,
+    // wrongGrainMiss-shaped honest miss ("'Button' resolved to the class Button,
+    // but this question needs a module…") than the plain zero-match miss this
+    // symbol-grain scan already renders ("No modules found whose module directly
+    // calls Button…"). A Class with no `contains` members AND no `defines` edge
+    // naming its module (the synthetic chatflow-tier2 fixture's Button, which the
+    // extractor recorded a bare declaration for but never wired into `defines`)
+    // must keep the latter, plain-miss wording — eligibility alone doesn't
+    // guarantee the up-refine can actually complete.
+    const upRefineEligible = (kind === "touches" || kind === "calls") && objMatch.class === "Class"
+      && !edgesOfKind(graph, "contains").some((e) => e.subject === objMatch.id);
+    const upRefineModule = upRefineEligible ? graph.byId.get(moduleIdOf(graph, objMatch) || "") : null;
+    if (matches.length || !(upRefineEligible && upRefineModule)) {
       return { matches, objMatch, candidates, traversal: `${symbolKind} edges where object = ${objMatch.label}${widenNote}`, ambiguous, matchedVia };
     }
   }

package/src/chat.mjs

@@ -4501,6 +4501,13 @@ const FACT_ANSWER_CAP = 32;
 const CAN_ASK_RE = /^(?:can|could)\s+(?:an?\s+)?([\w'-]+(?:\s+[\w'-]+)*?)\s+([a-z]+)[?.!\s]*$/i;
 const WHAT_CAN_DO_RE = /^what\s+can\s+(?:an?\s+)?(.+?)\s+do[?.!\s]*$/i;
 const WHAT_HAS_RE = /^what\s+has\s+(?:an?\s+)?(.+?)[?.!\s]*$/i;
+// "what is used for riding" / "what can be used for riding" / "what is for
+// riding" — the reverse-by-object mirror of BUG 1's forward reader ("what is
+// a tree used for"), missing until now: BUG 1 only ever filtered a KNOWN
+// subject's facts down to mgx:usedFor; nothing answered the reverse question
+// (object known, subject unknown), so it fell all the way through to the
+// code-graph miss cascade — actively misleading for a pure vocabulary query.
+const WHAT_USED_FOR_RE = /^what\s+(?:(?:can\s+be|is)\s+used\s+for|is\s+for)\s+(.+?)[?.!\s]*$/i;
 // Widened 2026-07-11 (live-caught follow-up to the ambiguousParse fix, commit
 // 5c858bf): on the FIRST turn of a graph-less session, dispatchTool's
 // loadGraph() throws its own documented "the graph is empty... this repo
@@ -4548,6 +4555,32 @@ async function factAnswer(memoryDir, query, envelope, miss, biasByBundle = {}) {
   try { ({ normFactTerm } = await import("./memory/core.mjs")); } catch { return null; }
   const q = String(query).trim();
 
+  // (a-pre) "what is used for riding" / "what can be used for riding" / "what
+  // is for riding" — the reverse-by-OBJECT mirror of BUG 1's forward reader
+  // ("what is a tree used for", the (a) block just below). Checked BEFORE (a)
+  // deliberately: this phrasing's leading "what is …" ALSO matches (a)'s own
+  // BARE_WHATIS_RE, which would otherwise greedily treat "used for riding" as
+  // one literal term to define — a guaranteed miss, since no vocabulary term
+  // is ever named "used for riding" — and (a) always returns (hit, honest
+  // per-relation "no", or null), never falling through to a later reader. Only
+  // takes over when it finds a REAL hit; a non-match or zero-hit case falls
+  // through unchanged to (a) and beyond, so ordinary miss messaging is
+  // untouched. mgx:usedFor instead of mgx:hasA; same filter/rank/render/
+  // paginate recipe as (b4)'s WHAT_HAS_RE below.
+  const usedForQ = q.match(WHAT_USED_FOR_RE);
+  if (usedForQ) {
+    const variants = factTermVariants(normFactTerm, usedForQ[1]);
+    const hits = (await factRows(memoryDir)).filter((f) => f.predicate === "mgx:usedFor" && variants.has(f.object));
+    if (hits.length) {
+      const ranked = rankByBiasThenTrust(uniqueFacts(hits), biasByBundle);
+      const lines = ranked.map(renderFactLine);
+      const shown = lines.slice(0, FACT_ANSWER_CAP);
+      const rest = lines.slice(FACT_ANSWER_CAP);
+      const extra = rest.length ? `\n…and ${rest.length} more — say 'more' to see them.` : "";
+      return { text: shown.join("\n") + extra, replace: true, ...(rest.length ? { pending: { items: rest, noun: "facts" } } : {}) };
+    }
+  }
+
   // (a) meta-shaped questions ("what is a module", "what does cache mean") — the
   // parsed object term, matched against fact SUBJECTS; consulted for hits (append
   // alongside the schema-docs answer) and misses (facts answer alone) alike.