@polycode-projects/the-mechanical-code-talker 2.7.12 → 2.7.14

package/corpus/worlds/manifest.json

@@ -3,7 +3,7 @@
   "generated": "by scripts/build-worlds-pack.mjs from corpus/worlds/src/",
   "counts": {
     "worlds": 2,
-    "facts": 527,
+    "facts": 528,
     "rules": 19
   },
   "budgets": {
@@ -14,8 +14,8 @@
   "sources": [
     {
       "file": "src/ashcombe-hall.jsonl",
-      "bytes": 8352,
-      "sha256": "f141da008edb6abfe025ddf4753fc374ccf44bdf23e3a414741f33f7246a3c9a"
+      "bytes": 8458,
+      "sha256": "79332b0700a8c8289ca4d8b5a9cf3dcff4c869fb1b45a72dd291617f61bdd184"
     },
     {
       "file": "src/spider-fly.jsonl",
@@ -31,8 +31,8 @@
     },
     {
       "file": "shards/ashcombe-hall.jsonl.gz",
-      "bytes": 948,
-      "sha256": "49bbdf7bd0008c916145e866cd174d334c97ec449bd8ec850d10985468653c25"
+      "bytes": 963,
+      "sha256": "d44e229d8f30dc43e8801443d426c315b43a6758adb11ad332c84e7108268746"
     },
     {
       "file": "shards/spider-fly.jsonl.gz",

package/corpus/worlds/src/ashcombe-hall.jsonl

@@ -33,6 +33,7 @@
 {"world":"ashcombe-hall","kind":"fact","subject":"portrait","predicate":"mgx:fixed-in","object":"drawing-room"}
 {"world":"ashcombe-hall","kind":"fact","subject":"key","predicate":"mgx:hidden-in","object":"portrait"}
 {"world":"ashcombe-hall","kind":"fact","subject":"letter","predicate":"mgx:hidden-in","object":"cabinet"}
+{"world":"ashcombe-hall","kind":"fact","subject":"letter","predicate":"mgx:is-objective","object":"true"}
 {"world":"ashcombe-hall","kind":"fact","subject":"housekeeper","predicate":"mgx:currently-in","object":"kitchen"}
 {"world":"ashcombe-hall","kind":"fact","subject":"cook","predicate":"mgx:currently-in","object":"kitchen"}
 {"world":"ashcombe-hall","kind":"fact","subject":"butler","predicate":"mgx:currently-in","object":"drawing-room"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.7.12",
+  "version": "2.7.14",
   "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

@@ -28,7 +28,7 @@ import {
   MEMBERSHIP_KINDS, CASCADE_NOISE, CASCADE_SYNONYMS, HELP_TRIGGERS,
   stripTrailingScopeFiller,
 } from "./ask-vocab.mjs";
-import { expandContractions, normalizeQuery, applyNegationFrames, applyPhrasingFrames, matchNegationSet, STOPWORDS, splitWords, wordsOf } from "./interpret/normalize.mjs";
+import { expandContractions, normalizeQuery, applyNegationFrames, applyPhrasingFrames, matchNegationSet, STOPWORDS, splitWords, wordsOf, escapeRegex } from "./interpret/normalize.mjs";
 import { editDistance, fuzzyBound } from "./interpret/fuzzy.mjs";
 import { parseAnchored } from "./interpret/strategies/grammar.mjs";
 import { parseKeywordSpot, findPhrase } from "./interpret/strategies/keywords.mjs";
@@ -3512,14 +3512,38 @@ function renderCore(parsed, result, graph) {
           if (shared > bestShared || d < bestD) { nearest = i; bestShared = shared; bestD = d; }
         }
       }
-      if (nearest) pool = [...pool, nearest];
+      // The nearest neighbour joins `branches` too, traversed and rendered the
+      // SAME way every other candidate's branch already was (traverse()'s own
+      // ambiguous-pool loop, just above in this file) — without this, the
+      // "did you mean" LEAD line named it (via `pool`) but its numbered
+      // preview never appeared at all, silently short one candidate.
+      if (nearest) {
+        pool = [...pool, nearest];
+        if (branches) {
+          const branchResult = traverse(graph, parsed, { pinnedObjMatch: nearest });
+          branches = [...branches, { candidate: nearest, result: branchResult, rendered: render(parsed, branchResult, graph) }];
+        }
+      }
     }
     const noun = pool.length && pool.every((i) => i.class === "Commit") ? "commit" : "module";
     const shown = pool.slice(0, OVERFLOW_CAP).map((i) => i.label);
     const extra = pool.length > OVERFLOW_CAP ? `, …and ${pool.length - OVERFLOW_CAP} more` : "";
     const lead = `"${parsed.object}" matches more than one ${noun} ambiguously — did you mean ${listJoin(shown)}${extra}? Try one of those. If you're not sure, narrow it to one name.`;
+    // A branch's own rendered text can still name the ORIGINAL ambiguous term
+    // instead of the specific candidate it was pinned to — e.g. "what calls
+    // saveTask" resolving 3 ways, where the "Task.assignTo" branch's own
+    // no-results miss text reads "…calls saveTask" (a fallback wording that
+    // is CORRECT for an ordinary single resolution, echoing what the user
+    // actually typed for a pronoun or a shortened path — untouched here) but
+    // wrong under a heading that already says which ONE candidate this
+    // preview is about. Swapped only when the literal ambiguous term still
+    // appears as a whole word in that ONE branch's own text — every other
+    // branch, and every non-branch render, is untouched.
+    const term = String(parsed.object || "");
+    const termRe = term ? new RegExp(`\\b${escapeRegex(term)}\\b`, "gi") : null;
+    const branchText = (b) => (termRe ? b.rendered.content.replace(termRe, b.candidate.label) : b.rendered.content);
     const content = (branches && branches.length)
-      ? `${lead}\n${branches.map((b, i) => `${i + 1}) ${b.candidate.label}: ${b.rendered.content}`).join("\n")}`
+      ? `${lead}\n${branches.map((b, i) => `${i + 1}) ${b.candidate.label}: ${branchText(b)}`).join("\n")}`
       : lead;
     return {
       content, miss: false, ambiguous: true, candidates: pool.map((i) => i.label),

package/src/domain/interpret/normalize.mjs

@@ -600,7 +600,7 @@ export function matchNegationSet(text) {
 export const STOPWORDS = new Set([
   "what", "who", "which", "where", "when", "why", "how",
   "does", "do", "did", "is", "are", "was", "were", "the", "a", "an", "of", "to", "from", "at", "in", "on",
-  "there", "something", "anything", "nothing", "one", "any",
+  "there", "something", "anything", "nothing", "one", "any", "anywhere",
   "last", // temporal filler ("when was X last touched")
   "usually", "typically", "generally", "normally", "often", "commonly", "mostly", // frequency-adverb filler
   "should", "would", "could", "can", "will", "shall", "might", "must", // modal auxiliaries

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

@@ -107,11 +107,24 @@ export function parseKeywordSpot(text, nlp = null) {
       fuzzyVerb = { from: lcWords[at], to: fuzzyWords[at] };
     }
   }
-  if (!verbHit && lcWords.includes("by")) {
+  if (!verbHit) {
     // A participle with no active verb entry still marks a passive when a passive
-    // auxiliary and an agent "by" are both present.
+    // auxiliary precedes it — with or without an agent "by" phrase. "is http.mjs
+    // used anywhere" carries no "by" at all (it's asking whether ANY agent uses
+    // it), so gating this on lcWords.includes("by") left it with no verbHit at
+    // all and no chance to reach the "Bare passive" branch below that already
+    // reads a no-agent participle correctly.
+    //
+    // "used" immediately followed by "for" is carved out even here: "what is a
+    // horse used for" / "what is it used for" is the protected usedFor-purpose
+    // idiom (fuzzy.mjs's own NEVER_CANONICALIZE keeps "used" out of the active
+    // verb table for the identical reason), answered by ask.mjs's dedicated
+    // "used for" reader, never the codegraph uses/imports/calls relation. The
+    // WITH-"by" case ("used by X") is unaffected — "for" only ever follows
+    // "used" directly in the purpose idiom, never in a "by"-agented passive.
     for (let i = 0; i < lcWords.length; i += 1) {
       const k = PASSIVE_PARTICIPLE_TO_KIND[lcWords[i]];
+      if (k && lcWords[i] === "used" && lcWords[i + 1] === "for") continue;
       if (k && lcWords.slice(0, i).some((w) => PASSIVE_AUX.has(w))) { verbHit = { kind: k, start: i, end: i + 1 }; break; }
     }
   }

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

@@ -16,6 +16,19 @@ export const GRID_SIZE = 10;
 export const WEB_HOME = Object.freeze({ x: 2, y: 2 });
 export const WEB_RADIUS = 1;
 
+// A spider-built dynamic web (src/services/spider-fly.mjs's hasActiveWebAt)
+// stays active for this many turns past the turn it was built, mirroring the
+// static home zone's own always-on web without needing separate code paths.
+export const WEB_DURATION_TURNS = 10;
+
+// Spider mass mirrors a fly's own (src/services/spider-fly.mjs's
+// FLY_INITIAL_MASS/FLY_MASS_DECREMENT_PER_TURN): a spider starves like a fly
+// does, and gains exactly a fly's remaining mass on an eat. Heavier starting
+// mass than a single fly's worth on purpose — a spider that eats nothing for
+// a while has some runway before starving.
+export const SPIDER_INITIAL_MASS = 15;
+export const SPIDER_MASS_DECREMENT_PER_TURN = 1;
+
 export const cellId = (x, y) => `cell-${x}-${y}`;
 
 const CELL_ID_RE = /^cell-(\d+)-(\d+)$/;

package/src/domain/sprite-map.mjs

@@ -79,11 +79,53 @@ const ANIMAL_SVG =
   + '<g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="7" y1="17" x2="7" y2="21"/><line x1="17" y1="17" x2="17" y2="21"/></g>'
   + "</svg>";
 
+// ---- the adventure world's own class family (PLAN_GAMES_UPLIFT_V2.md Part B)
+// — a room's floor plan, a piece of furniture, a portable, a person, the
+// player's own adventurer sprite, and a container. Ashcombe Hall's own
+// classes resolve to these directly (no ancestor walk needed, since the
+// shipped world has no rdfs:subClassOf chain at all yet); the walk stays
+// ready for a future world whose taxonomy goes deeper, the same "poodle IsA
+// dog" mechanism spider-fly already exercises.
+
+const ROOM_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3" y="3" width="18" height="18" rx="1" fill="none" stroke="currentColor" stroke-width="1.6"/>'
+  + '<path d="M9 21 L9 13 A3 3 0 0 1 15 13 L15 21" fill="none" stroke="currentColor" stroke-width="1.6"/></svg>';
+
+const FURNITURE_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="4" y="5" width="16" height="3" rx="1" fill="currentColor"/>'
+  + '<rect x="4" y="8" width="3" height="12" fill="currentColor"/>'
+  + '<rect x="17" y="8" width="3" height="12" fill="currentColor"/></svg>';
+
+const PORTABLE_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="5" y="9" width="14" height="11" rx="1.5" fill="currentColor"/>'
+  + '<path d="M9 9 V6.5 A3 3 0 0 1 15 6.5 V9" fill="none" stroke="currentColor" stroke-width="1.6"/></svg>';
+
+const PERSON_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="6.5" r="3.2" fill="currentColor"/>'
+  + '<path d="M6 21 C6 15.5 8.7 13 12 13 C15.3 13 18 15.5 18 21 Z" fill="currentColor"/></svg>';
+
+// The adventurer is the player's own sprite — the same silhouette as `person`
+// plus a small satchel, so the one individual the player controls always
+// reads as visually distinct from the cast of NPCs sharing the room.
+const ADVENTURER_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="6.5" r="3.2" fill="currentColor"/>'
+  + '<path d="M6 21 C6 15.5 8.7 13 12 13 C15.3 13 18 15.5 18 21 Z" fill="currentColor"/>'
+  + '<rect x="15.5" y="13.5" width="4.5" height="5" rx="1" fill="currentColor" opacity="0.6"/></svg>';
+
+const CONTAINER_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3" y="10" width="18" height="10" rx="1.2" fill="currentColor"/>'
+  + '<path d="M3 10 L5 5 H19 L21 10 Z" fill="currentColor" opacity="0.7"/>'
+  + '<rect x="10.6" y="9.4" width="2.8" height="2.2" rx="0.4" fill="currentColor" opacity="0.35"/></svg>';
+
 /** The sprite registry: class name (normFactTerm-normalized) -> inline SVG
  *  markup. `animal` is this world's declared root fallback (PLAN_SPIDER_FLY.md
  *  §7 names "animal"/"object"/"plant" as the family of possible roots — a
  *  spider-and-fly board only ever needs "animal") — resolveSpriteForClass
- *  falls back to it once the ancestor walk exhausts with no closer hit. */
+ *  falls back to it once the ancestor walk exhausts with no closer hit. The
+ *  adventure world's classes (room/furniture/portable/person/adventurer/
+ *  container) are a second, unrelated root family sharing the one flat table —
+ *  a board only ever resolves classes from its own world, so the two never
+ *  collide in practice. */
 export const SPRITE_REGISTRY = Object.freeze({
   spider: SPIDER_SVG,
   fly: FLY_SVG,
@@ -91,6 +133,12 @@ export const SPRITE_REGISTRY = Object.freeze({
   poodle: POODLE_SVG,
   dog: DOG_SVG,
   animal: ANIMAL_SVG,
+  room: ROOM_SVG,
+  furniture: FURNITURE_SVG,
+  portable: PORTABLE_SVG,
+  person: PERSON_SVG,
+  adventurer: ADVENTURER_SVG,
+  container: CONTAINER_SVG,
 });
 
 /** Every direct rdfs:subClassOf superclass of `term`, from a flat fact-row

package/src/services/adventure-autoplay.mjs

@@ -0,0 +1,192 @@
+// adventure-autoplay.mjs — a sibling layer over adventure.mjs (never edited
+// for this: this session's own in-flight rule-shape work owns that file)
+// that plays a loaded world by itself: infer a goal from one generic marker
+// fact, explore toward it, fetch it, and report an honest stall the moment no
+// further move is justified. It is a CALLER of the existing command
+// interpreter (adventureTurn), never a second one — every move it makes is
+// the same plain command string a human types ("go north", "take letter"),
+// executed through the identical turn a real chat session runs.
+//
+// The one hard constraint: auto-play only ever reasons over what it has
+// actually seen. `exposedRoomIds` is the set of rooms this auto-play run has
+// itself moved into (the opening room included from turn 0) — it is the sole
+// caller making every move, so it always knows this, and threads the set
+// forward turn to turn exactly like spider-fly.mjs threads its own agents
+// shape. `exposedFacts` turns that set into the actual filtered view: a fact
+// is exposed when its subject's CURRENT placement resolves into an exposed
+// room, when the subject is the player, or when the fact IS the world's
+// objective marker (told to the player unconditionally at turn 0, the same
+// way the opening line's prose already is). A hidden object's reveal falls
+// out of this automatically — no `mgx:hidden-in` special case is needed, the
+// placement-resolution walk already returns null for anything still hidden.
+//
+// The objective marker is one new, generic world-pack fact,
+// `{"subject":"letter","predicate":"mgx:is-objective","object":"true"}` —
+// deliberately not hard-coded to any one world. A world that ships no such
+// fact simply has nothing for this module to infer a goal toward.
+import { findActionPath } from "../domain/planning.mjs";
+import { loadMemory, readFactRows } from "../adapters/memory/core.mjs";
+import { foldWorldState, adventureTurn } from "./adventure.mjs";
+
+const SNAPSHOT_RE = /^(.+)@turn(\d+)$/;
+const baseSubjectOf = (subject) => SNAPSHOT_RE.exec(subject)?.[1] ?? subject;
+
+const isTypedRow = (rows, subject, type) =>
+  (rows || []).some((r) => r.subject === subject && r.predicate === "rdf:type" && r.object === type);
+
+/** The room a subject's CURRENT placement resolves into — a room resolves to
+ *  itself; an object placed directly in a room resolves to that room; an
+ *  object one containment hop inside an OPEN container resolves to the
+ *  container's own room; anything hidden, carried, or inside a closed
+ *  container resolves to nothing (null). This mirrors adventure.mjs's own
+ *  private `visibleRoomOf` exactly (that helper isn't exported, so the walk
+ *  is re-derived here against the same `foldWorldState` placements map,
+ *  never a second notion of visibility). */
+function roomOfSubject(subject, rows, state) {
+  if (isTypedRow(rows, subject, "room")) return subject;
+  const place = state.placements.get(subject);
+  if (!place || place.predicate === "mgx:hidden-in") return null;
+  if (place.predicate === "mgx:currently-in" || isTypedRow(rows, place.object, "room")) return place.object;
+  const holder = place.object;
+  if (holder === "player") return null; // carried, not resolvable to a room
+  if (!state.openness.get(holder)?.open) return null;
+  const holderPlace = state.placements.get(holder);
+  return holderPlace && holderPlace.predicate !== "mgx:hidden-in" ? holderPlace.object : null;
+}
+
+/**
+ * The subset of `allRows` this auto-play run may reason over, given the
+ * rooms it has actually moved into so far (`exposedRoomIds`). Pure — folds
+ * `allRows` itself rather than taking a precomputed state, so a caller never
+ * has to keep a fold in step with the exposure set by hand.
+ */
+export function exposedFacts(allRows, exposedRoomIds) {
+  const rows = allRows || [];
+  const state = foldWorldState(rows);
+  const exposed = new Set(exposedRoomIds || []);
+  return rows.filter((row) => {
+    if (baseSubjectOf(row.subject) === "player") return true;
+    if (row.predicate === "mgx:is-objective") return true;
+    const room = roomOfSubject(baseSubjectOf(row.subject), rows, state);
+    return room != null && exposed.has(room);
+  });
+}
+
+/** One hop per exposed room's own has-exit-* facts, sorted by direction name
+ *  for deterministic tie-breaking — the applyActions closure findActionPath
+ *  needs, built from the EXPOSED fold only, so a search over this graph can
+ *  never plan through an edge auto-play hasn't itself walked into. */
+function exposedExitApplyActions(exposedState) {
+  return (room) => {
+    const dirs = exposedState.exits.get(room);
+    if (!dirs) return [];
+    return [...dirs.keys()].sort().map((direction) => ({ action: direction, nextState: dirs.get(direction) }));
+  };
+}
+
+const unexposedExitsOf = (room, exposedState, exposed) =>
+  [...(exposedState.exits.get(room)?.entries() ?? [])].filter(([, target]) => !exposed.has(target));
+
+/**
+ * One auto-play tick over a live, loaded adventure: fold the world, infer a
+ * goal from the one generic objective marker under the exposure constraint,
+ * and execute exactly the one move that goal implies through `adventureTurn`
+ * — the same public entry point a real chat turn calls. Returns
+ * `{ turn, goal, plan, done, stalled, exposedRoomIds }`, mirroring
+ * spider-fly.mjs's own tick shape: `plan` is the remaining multi-step route a
+ * `findActionPath` search found this tick (or null when the move was a
+ * single, immediate step — an adjacent unexposed exit, or a take), `goal` is
+ * a short line describing what this tick did, `done` means the objective is
+ * now carried, `stalled` means no move could be justified without guessing.
+ */
+export async function runAdventureAutoplayTick(memoryDir, opts = {}) {
+  const { exposedRoomIds, planHolder, sessionId = "", env = {}, graph = null, cache = null } = opts;
+  const rows = readFactRows(await loadMemory(memoryDir));
+  const state = foldWorldState(rows);
+  const here = state.placements.get("player")?.object ?? null;
+  const exposed = new Set(exposedRoomIds || []);
+
+  if (!here) {
+    return {
+      turn: state.turnCount, goal: "stalled — no player position is written for this world.",
+      plan: null, done: false, stalled: true, exposedRoomIds: exposed,
+    };
+  }
+  exposed.add(here);
+
+  const runCommand = (line) => adventureTurn(line, { planHolder, memoryDir, sessionId, env, graph, cache });
+
+  const exposedRows = exposedFacts(rows, exposed);
+  const exposedState = foldWorldState(exposedRows);
+  const objectiveId = exposedRows.find((r) => r.predicate === "mgx:is-objective" && r.object === "true")?.subject ?? null;
+
+  // Win: the objective is already carried — checked against the FULL fold,
+  // since what the player itself carries is always self-evidently known,
+  // the same unconditional "OR the subject is player" exposure the marker
+  // fact itself gets (worldDigestRows shows carried items regardless of
+  // room visibility too — carrying was never gated on being seen).
+  const carried = objectiveId
+    && state.placements.get(objectiveId)?.predicate === "mgx:located-in"
+    && state.placements.get(objectiveId)?.object === "player";
+  if (objectiveId && carried) {
+    return {
+      turn: state.turnCount, goal: `carrying the ${objectiveId} — the adventure is won.`,
+      plan: [], done: true, stalled: false, exposedRoomIds: exposed,
+    };
+  }
+
+  const objectiveRoom = objectiveId ? roomOfSubject(objectiveId, exposedRows, exposedState) : null;
+
+  if (objectiveId && objectiveRoom) {
+    if (objectiveRoom === here) {
+      await runCommand(`take ${objectiveId}`);
+      return {
+        turn: state.turnCount + 1, goal: `in the ${here} — taking the ${objectiveId}.`,
+        plan: null, done: false, stalled: false, exposedRoomIds: exposed,
+      };
+    }
+    const path = findActionPath(here, (room) => room === objectiveRoom, exposedExitApplyActions(exposedState));
+    if (!path || !path.actions.length) {
+      return {
+        turn: state.turnCount, goal: `stalled — no seen path from the ${here} to the ${objectiveRoom}.`,
+        plan: null, done: false, stalled: true, exposedRoomIds: exposed,
+      };
+    }
+    await runCommand(`go ${path.actions[0]}`);
+    exposed.add(path.states[1]);
+    return {
+      turn: state.turnCount + 1, goal: `heading toward the ${objectiveRoom} for the ${objectiveId}.`,
+      plan: path.actions, done: false, stalled: false, exposedRoomIds: exposed,
+    };
+  }
+
+  // Explore: the objective either doesn't exist in this world, or its room
+  // isn't known yet. Prefer an immediate unexposed exit from here (the
+  // lowest-sorted direction); otherwise path toward the nearest exposed room
+  // that still has one.
+  const unexposedHere = unexposedExitsOf(here, exposedState, exposed).sort(([a], [b]) => a.localeCompare(b));
+  if (unexposedHere.length) {
+    const [direction, target] = unexposedHere[0];
+    await runCommand(`go ${direction}`);
+    exposed.add(target);
+    return {
+      turn: state.turnCount + 1, goal: `exploring — heading ${direction} into unseen ground.`,
+      plan: null, done: false, stalled: false, exposedRoomIds: exposed,
+    };
+  }
+
+  const hasUnexposedExit = (room) => unexposedExitsOf(room, exposedState, exposed).length > 0;
+  const path = findActionPath(here, hasUnexposedExit, exposedExitApplyActions(exposedState));
+  if (!path || !path.actions.length) {
+    return {
+      turn: state.turnCount, goal: "stalled — every reachable room is already explored, and no goal was ever found.",
+      plan: null, done: false, stalled: true, exposedRoomIds: exposed,
+    };
+  }
+  await runCommand(`go ${path.actions[0]}`);
+  exposed.add(path.states[1]);
+  return {
+    turn: state.turnCount + 1, goal: "exploring — backtracking toward unseen ground.",
+    plan: path.actions, done: false, stalled: false, exposedRoomIds: exposed,
+  };
+}