@polycode-projects/the-mechanical-code-talker 2.10.1 → 2.10.3

package/data/templates/responses.jsonl

@@ -60,6 +60,7 @@
 {"id":"conversational-greeting-good-evening","class":"conversational","register":"friendly","template":"Good evening. Ask me about this codebase, or /help."}
 {"id":"conversational-thanks","class":"conversational","register":"friendly","template":"Any time. Ask another, or /help for what I can do."}
 {"id":"conversational-farewell","class":"conversational","register":"friendly","template":"Bye — flushing the session log. Come back with a question any time."}
+{"id":"conversational-dismissal","class":"conversational","register":"friendly","template":"No worries. Ask another, or /help for what I can do."}
 {"id":"orientation-friendly","class":"orientation","register":"friendly","template":"I'm tmct — a deterministic, offline code-graph assistant (no LLM). I answer questions about THIS codebase's structure — imports, calls, definitions,\nhistory and counts. For example:\n  which modules import {example1}\n  what calls {example2}\n  how many classes are there\n/help for commands, /stats for an overview of the graph."}
 {"id":"miss-no-previous-answer","class":"miss","register":"friendly","template":"No previous answer to expand yet — ask me a question first, then say \"why\" or \"say more\"."}
 {"id":"conversational-greeting-empty","class":"conversational","register":"friendly","template":"Hi. I'm tmct. {vocabHint} Point me at a repo with `--repo <path>` for code-structure questions too (imports, calls, definitions). /help for commands."}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.10.1",
+  "version": "2.10.3",
   "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/domain/ask.mjs

@@ -896,7 +896,12 @@ function parseSuperlative(w, lc, nlp) {
   }
   const connectivity = lc.includes("connected") || lc.slice(extIdx, extIdx + 2).join(" ") === "most connected"
     || ["largest", "biggest", "smallest"].includes(lc[extIdx]);
-  if (!metric && connectivity) { metric = EDGE_NOUN_TO_METRIC.connections; metricNoun = "connections"; }
+  // A bare importance superlative ("the most important file") names no explicit
+  // edge metric, so it ranks by total connectivity — the sum of an entity's
+  // in/out edges, the most defensible deterministic proxy for "important".
+  const IMPORTANCE_WORDS = ["important", "significant", "central", "key", "core", "essential", "critical", "principal"];
+  const importanceRanked = lc.some((x) => IMPORTANCE_WORDS.includes(x));
+  if (!metric && (connectivity || importanceRanked)) { metric = EDGE_NOUN_TO_METRIC.connections; metricNoun = "connections"; }
   // entity noun anywhere (first match, deterministic); else default from a
   // metric that implies exactly one entity class ("test(s)" always ranks
   // Modules, the one declared exception — see METRIC_IMPLIES_ENTITY — so "what
@@ -4205,6 +4210,26 @@ export function ask(graph, query, { contextId = null, nlp = undefined, prev = nu
       content = `${content}\n${lines.join("\n")}`;
     }
   }
+  // NARROWING DISCLOSURE: the resolver picked ONE entity among several distinct
+  // name-matches (a scored win, not a tie — a tie renders as branches above and
+  // is excluded here). Whether the pick then produced an answer or an empty
+  // result, disclose it and the count of the other matches in one line, so a
+  // silent narrowing (a merged graph's src/store.mjs over src/core/store.mjs, a
+  // directory term landing on one module, a wrong-case pick reporting no members)
+  // is never mistaken for the only reading.
+  if (!rendered.ambiguous && result.objMatch && Array.isArray(result.candidates) && result.candidates.length) {
+    // A ranked shape (entry-point, superlative) carries its runners-up in
+    // `matches` and discloses them its own way; a NAME-narrowing carries the
+    // narrowed-away candidates OUTSIDE `matches`. Only the latter is disclosed.
+    const matchIds = new Set((result.matches || []).map((m) => m && m.id));
+    const others = result.candidates.filter((c) => c && c.id && c.id !== result.objMatch.id && !matchIds.has(c.id));
+    if (others.length) {
+      const shown = others.slice(0, 3).map((c) => c.label).filter(Boolean);
+      const more = others.length - shown.length;
+      const list = shown.join(", ") + (more > 0 ? `, +${more} more` : "");
+      content = `${content}\n(answering for ${result.objMatch.label} — ${others.length} other match${others.length === 1 ? "" : "es"}: ${list})`;
+    }
+  }
   return {
     content,
     tmct_ask: {

package/src/domain/domain.mjs

@@ -5,9 +5,18 @@
 // arrives as data from the memory store's fact/Rule rows. Plugs into
 // planning.mjs's findActionPath as its applyActions.
 
+import { provenanceTagToSource } from "./memory/trust.mjs";
+
 const MEMBER_EDGE_PREDICATES = new Set(["rdfs:subClassOf", "rdf:type"]);
 const SNAPSHOT_RE = /^(.+)@step(\d+)$/;
 
+/** The class-member list a grounding step ranges over. The default "all" is
+ *  every typed member; "taught" restricts to instances a person taught, the
+ *  scope the plan lane uses so a merged corpus never widens a quantified goal
+ *  or the movable set. Falls back to nothing for an unknown scope. */
+const membersInScope = (domain, cls, scope) =>
+  (scope === "taught" ? domain.taughtClassMembers : domain.classMembers)?.[cls] || [];
+
 /** Trim a taught term defensively: some teach frames keep a sentence's
  *  trailing punctuation in the captured object. */
 const normTerm = (value) => String(value ?? "").trim().replace(/[.!?]+$/, "");
@@ -110,18 +119,34 @@ export function compileDomain(factRows, ruleRows) {
 
   // Class membership from typing edges. A member is a subject with a typing
   // edge into the class and no typing edge pointing at itself (a leaf).
-  const edges = (factRows || []).map(normRow).filter((r) => MEMBER_EDGE_PREDICATES.has(r.predicate));
-  const hasIncoming = new Set(edges.map((r) => r.object));
-  const classMembers = {};
-  for (const edge of edges) {
-    if (hasIncoming.has(edge.subject)) continue;
-    (classMembers[edge.object] ??= []).push(edge.subject);
-  }
-  for (const members of Object.values(classMembers)) {
-    members.sort();
-    // de-dup while keeping order
-    for (let i = members.length - 1; i > 0; i -= 1) if (members[i] === members[i - 1]) members.splice(i, 1);
-  }
+  const membersFromEdges = (typingEdges) => {
+    const hasIncoming = new Set(typingEdges.map((r) => r.object));
+    const members = {};
+    for (const edge of typingEdges) {
+      if (hasIncoming.has(edge.subject)) continue;
+      (members[edge.object] ??= []).push(edge.subject);
+    }
+    for (const list of Object.values(members)) {
+      list.sort();
+      // de-dup while keeping order
+      for (let i = list.length - 1; i > 0; i -= 1) if (list[i] === list[i - 1]) list.splice(i, 1);
+    }
+    return members;
+  };
+  const typingRows = (factRows || []).filter((r) => MEMBER_EDGE_PREDICATES.has(normTerm(r.predicate)));
+  const edges = typingRows.map(normRow);
+  const classMembers = membersFromEdges(edges);
+  // The same membership, restricted to instances a person taught (an operator
+  // assert or a teach-lane frame). A planner that quantifies over a class —
+  // "every X" — ranges over the taught individuals only: a merged corpus can
+  // type dozens of unrelated things into that class, and sweeping those into
+  // the goal makes it unsatisfiable and the search fruitless. classMembers
+  // keeps every member for the readers that want them all.
+  const taughtEdges = edges.filter((_, i) => {
+    const kind = provenanceTagToSource(typingRows[i].provenance)?.kind;
+    return kind === "operator" || kind === "teach";
+  });
+  const taughtClassMembers = membersFromEdges(taughtEdges);
 
   // A class-bound word (an effect role or constraint term that is neither
   // "subject" nor "target") is substituted by its class's sole member at
@@ -158,7 +183,7 @@ export function compileDomain(factRows, ruleRows) {
     .filter((r) => !dynamicPredicates.has(r.predicate) && !MEMBER_EDGE_PREDICATES.has(r.predicate))
     .sort(rowSort);
 
-  return { actions, classMembers, dynamicPredicates, ordering };
+  return { actions, classMembers, taughtClassMembers, dynamicPredicates, ordering };
 }
 
 const domainIndividuals = (domain) => {
@@ -312,13 +337,16 @@ function constraintViolated(action, nextState, domain) {
 }
 
 /** Every legal grounded action from `state`, with its successor.
- *  Deterministic: actions, signatures, and members are walked sorted. */
-export function movesFromRules(state, domain, { budget = 5000 } = {}) {
+ *  Deterministic: actions, signatures, and members are walked sorted. `scope`
+ *  ("all" | "taught") picks which class members ground the moves — the plan
+ *  lane passes "taught" so corpus members of a taught class never enter the
+ *  movable set. */
+export function movesFromRules(state, domain, { budget = 5000, scope = "all" } = {}) {
   let groundings = 0;
   for (const action of domain.actions) {
     for (const sig of action.signatures) {
-      groundings += (domain.classMembers[sig.subjectClass] || []).length *
-        (domain.classMembers[sig.targetClass] || []).length;
+      groundings += membersInScope(domain, sig.subjectClass, scope).length *
+        membersInScope(domain, sig.targetClass, scope).length;
     }
   }
   if (groundings > budget) throw new PlanBudgetError(groundings, budget);
@@ -327,8 +355,8 @@ export function movesFromRules(state, domain, { budget = 5000 } = {}) {
   for (const action of domain.actions) {
     const [verb, particle] = action.name.split(/\s+/);
     for (const sig of action.signatures) {
-      for (const subject of domain.classMembers[sig.subjectClass] || []) {
-        for (const target of domain.classMembers[sig.targetClass] || []) {
+      for (const subject of membersInScope(domain, sig.subjectClass, scope)) {
+        for (const target of membersInScope(domain, sig.targetClass, scope)) {
           if (subject === target) continue;
           let ok = true;
           for (const precond of action.preconds) {
@@ -360,7 +388,7 @@ export function movesFromRules(state, domain, { budget = 5000 } = {}) {
  *  state predicate. Satisfaction is a transitive walk along the goal
  *  predicate: a stacked member reaches the goal object through its support
  *  chain, which a direct row lookup cannot see. */
-export function compileGoal(goalSpecs, domain) {
+export function compileGoal(goalSpecs, domain, { scope = "all" } = {}) {
   const specs = (goalSpecs || []).map((g) => ({
     universal: Boolean(g.universal),
     term: normTerm(g.term),
@@ -369,7 +397,7 @@ export function compileGoal(goalSpecs, domain) {
   }));
   const checks = [];
   for (const spec of specs) {
-    const members = spec.universal ? domain.classMembers[spec.term] || [] : [spec.term];
+    const members = spec.universal ? membersInScope(domain, spec.term, scope) : [spec.term];
     if (spec.universal && members.length === 0) {
       throw new Error(`the goal names "${spec.term}" as a class, but it has no known members`);
     }

package/src/services/adventure.mjs

@@ -408,9 +408,21 @@ const BACKGROUND_FACT_PHRASES = {
   "mgx:atLocation": "is found in",
 };
 
+/** True when a fact row is provably owned by a NON-world source (a merged
+ *  corpus, a reference pack, a taught assert) rather than the loaded world. A
+ *  row with no provenance is not "non-world" — a hand-built digest view carries
+ *  none, and the room-look filter keeps those. World facts and their @turn
+ *  snapshots tag as `world:<name>[:turnN]`. */
+function isNonWorldSourced(row) {
+  const prov = String(row.provenance || "").trim();
+  return prov !== "" && !prov.startsWith("world:");
+}
+
 /** The digest's fact view: current placements (folded), exits, typing and
  *  every other surviving fact, with phrase predicates and sentence-cased
- *  subjects so the pipeline's sentence splitter sees real sentences. Pure. */
+ *  subjects so the pipeline's sentence splitter sees real sentences. Room text
+ *  is world-sourced only — a merged corpus's overlap on a room's own vocabulary
+ *  never leaks into the description. Pure. */
 export function worldDigestRows(rows, state) {
   const out = [];
   const seen = new Set();
@@ -440,6 +452,12 @@ export function worldDigestRows(rows, state) {
   }
   for (const row of rows || []) {
     if (SNAPSHOT_RE.test(row.subject)) continue;                 // folded above
+    // Room text comes from the world source only. A merged corpus overlaps a
+    // room's own vocabulary ("library rdfs:subClassOf literary study"), and
+    // without this those rows leak into the room description as stray sentences.
+    // A row with no provenance (a hand-built test view) is kept — the filter
+    // only drops rows a non-world source provably owns.
+    if (isNonWorldSourced(row)) continue;
     if (PLACEMENT_PREDICATES.has(row.predicate)) continue;       // folded above
     if (VIEW_EXCLUDED_PREDICATES.has(row.predicate)) continue;
     const exit = EXIT_PREDICATE_RE.exec(row.predicate);
@@ -909,6 +927,58 @@ async function worldOpennessAnswer(line, { memoryDir }) {
   );
 }
 
+// The in-game orientation asides — "where am I", "what can I do", "what is the
+// quest/goal". Without a world-state answer these fall through to the ordinary
+// lanes and misroute: "where am I" reads "I" as a module name, "what can I do"
+// walls, and "what is the goal" answers from corpus vocabulary about the word
+// "goal". A live world answers each from its own fold first.
+const WORLD_WHERE_AM_I_RE = /^where\s+am\s+i(?:\s+now)?[?.!\s]*$/i;
+const WORLD_OPTIONS_RE = /^(?:what\s+can\s+i\s+do(?:\s+(?:here|now))?|what\s+are\s+my\s+options|what\s+(?:should|do)\s+i\s+do(?:\s+(?:here|now))?|what\s+now)[?.!\s]*$/i;
+const WORLD_QUEST_RE = /^(?:what(?:'s|\s+is)\s+(?:the\s+|my\s+)?(?:quest|goal|objective|mission|aim)|what\s+am\s+i\s+(?:trying\s+to\s+do|(?:supposed|meant)\s+to\s+do)|what\s+do\s+i\s+do\s+here)[?.!\s]*$/i;
+
+/** The in-game orientation asides, answered from the world fold: the player's
+ *  room, the room's real affordances, and the world's objective. Null when the
+ *  line is none of them, so an ordinary question keeps its lane. */
+async function worldContextAnswer(line, { memoryDir }) {
+  const l = String(line).trim();
+  const asksWhere = WORLD_WHERE_AM_I_RE.test(l);
+  const asksOptions = WORLD_OPTIONS_RE.test(l);
+  const asksQuest = WORLD_QUEST_RE.test(l);
+  if (!asksWhere && !asksOptions && !asksQuest) return null;
+  let rows;
+  try { rows = readFactRows(await loadMemory(memoryDir)); } catch { return null; }
+  const state = foldWorldState(rows);
+  const here = state.placements.get("player")?.object ?? null;
+
+  if (asksWhere) {
+    return here
+      ? answer(`you are in the ${here}.`, "ADVENTURE — where-am-I aside: the player's own room from the current world fold", { goal: "check where you are" })
+      : answer("the world has no written player position yet.", "ADVENTURE — where-am-I aside: no player placement", { miss: true, goal: "check where you are" });
+  }
+
+  if (asksOptions) {
+    const actions = here ? roomAffordances(rows, state, here) : [];
+    return answer(
+      actions.length ? `you can: ${actions.join(", ")}.` : `nothing obvious here — say "look" to look around${here ? ` the ${here}` : ""}.`,
+      `ADVENTURE — options aside: the ${here}'s roomAffordances, the same list "look" appends`,
+      { goal: "see what you can do here" },
+    );
+  }
+
+  const objectiveId = rows.find((r) => r.predicate === "mgx:is-objective" && r.object === "true")?.subject ?? null;
+  return objectiveId
+    ? answer(
+        `your goal is to find the ${objectiveId} and pick it up.`,
+        `ADVENTURE — quest aside: the world's objective (${objectiveId}), named without spoiling where it is`,
+        { goal: `find the ${objectiveId}` },
+      )
+    : answer(
+        `this world sets no explicit goal — explore it, and say "look" to see your options.`,
+        "ADVENTURE — quest aside: no objective marker in this world",
+        { goal: "explore the world" },
+      );
+}
+
 async function inventoryAnswer({ memoryDir, graph }) {
   const memory = await loadMemory(memoryDir);
   const rows = readFactRows(memory);
@@ -1033,5 +1103,7 @@ export async function adventureTurn(line, { planHolder, memoryDir, sessionId = "
   if (whereAside) return whereAside;
   const opennessAside = await worldOpennessAnswer(line, { memoryDir });
   if (opennessAside) return opennessAside;
+  const contextAside = await worldContextAnswer(line, { memoryDir });
+  if (contextAside) return contextAside;
   return null; // a mid-game aside — the ordinary lanes answer, world untouched
 }