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

package/src/surfaces/web/mud-browser-entry.mjs

@@ -36,7 +36,7 @@ import { memoryFactGraphPayload } from "../../domain/memory-facts.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import {
   foldWorldState, worldActionRows, worldDigestRows, roomAffordances,
-  personKnowledgeLines, personKnownFoodLines,
+  personKnowledgeLines, personKnownFoodLines, objectClassChain, recordExamined,
   diggableDirections, castInRoom, displayNameOf, isOutOfPlay, outOfPlayReasonOf, outOfPlayPhrase,
   roomKindOf, isMudStatePredicate, worldEpochFact, snapshotSubject,
 } from "../../services/adventure.mjs";
@@ -52,6 +52,12 @@ import { createTurnSession } from "./turn-session.mjs";
 import { publishTmctSurface } from "./tmct-surface.mjs";
 import { graphAsk, enginePlan } from "./engine-surface.mjs";
 
+// The class chain a room-mate object needs to reach for a starting character
+// to be seeded as already knowing about it — mirrors mud-turn.mjs's own
+// private FOOD_CLASS, kept as this file's own copy for the same reason that
+// file gives: nothing here reaches into another module's private constant.
+const MUD_STARTING_FOOD_CLASS = "food";
+
 /** A live, shared mud world several characters can each act in. `worldPayload`
  *  is `{ name, facts, rules, opening }` — the same shape adventure-browser-
  *  entry.mjs's own worldPayload takes, read once at build time through the
@@ -131,6 +137,32 @@ export async function createMudSession(worldPayload, { characters = [], epoch =
     return state.placements.get(character)?.object ?? null;
   }
 
+  // Every character already stands somewhere in the world this store was
+  // just seeded with, and food sitting loose in ITS OWN starting room is
+  // something it would see just by being there — the room's own "You can:"
+  // affordances and the pouch already read straight off this same seeded
+  // state, no play button required. Without this, personKnownFoodLines
+  // reads pure testimony (the mgx:knows-about facts recordTold/recordExamined
+  // write from the scripted tick loop), so "what food do you know about"
+  // stayed empty until the sim had ticked at least once, even with a carrot
+  // sitting in plain view. One recordExamined per character per food item
+  // already in its own room, written once here at open, closes that gap —
+  // a character standing three rooms away from every carrot on the board
+  // still starts knowing nothing, the honest answer for it.
+  {
+    const { rows, state } = await readWorld();
+    for (const character of characters) {
+      const room = state.placements.get(character)?.object ?? null;
+      if (!room) continue;
+      for (const [thing, place] of state.placements) {
+        if (thing === character) continue;
+        if (place.predicate !== "mgx:located-in" || place.object !== room) continue;
+        if (!objectClassChain(rows, thing).includes(MUD_STARTING_FOOD_CLASS)) continue;
+        await recordExamined(memoryDir, { observer: character, thing, k: 0, epoch });
+      }
+    }
+  }
+
   const windows = {};
   for (const character of characters) {
     // Deliberately per-closure, never on a shared object: a window's own

package/src/surfaces/web/mudiii-browser-entry.mjs

@@ -6,14 +6,6 @@
 // on `{ as: character }` — the addressee is in the sentence, "@fox-1 look"),
 // and the simulation itself advances as ONE whole-world tick
 // (`runTownSquareTick`) rather than mud's per-character `autoplayTick`.
-//
-// `src/services/predator-prey.mjs` — the engine this file drives — does not
-// exist in every worktree yet; a concurrent track owns it. The import below
-// is guarded (dynamic, try/catch) so this module still loads, and every
-// test that imports mudiii-viz.mjs (which never imports this file) is
-// unaffected either way. `createMudiiiSession` throws a clear "the engine
-// isn't built yet" error if actually called before that track lands, rather
-// than a bare ERR_MODULE_NOT_FOUND with no context.
 import {
   createInMemoryStore, appendFacts, appendRule, loadMemory, readFactRows, removeFacts,
 } from "../../adapters/memory/core.mjs";
@@ -22,26 +14,21 @@ import { memoryFactGraphPayload } from "../../domain/memory-facts.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import { worldProvenanceTag } from "../../domain/worlds-pack.mjs";
 import {
-  COMPASS_POINTS, DEFAULT_FACING, layoutNamed, reverseFacing, stepCellFrom, turnedFacing,
+  COMPASS_POINTS, DEFAULT_FACING, cellId, layoutNamed, parseCellId, reverseFacing, stepCellFrom, turnedFacing,
 } from "../../domain/town-square-world.mjs";
+import { findActionPath } from "../../domain/planning.mjs";
+import { DEFAULT_GAME_CONFIG } from "../../domain/game-config.mjs";
 import { parseMudEditorText, planMudEditorSync, gridWorldEditorState } from "../../services/mud-editor.mjs";
+import { pillsForMudiii } from "../../services/mudiii-turn.mjs";
+import { relatedForTerm } from "../../domain/skos-view.mjs";
+import { classAncestorChain } from "../../domain/sprite-map.mjs";
 import { createTurnSession } from "./turn-session.mjs";
 import { publishTmctSurface } from "./tmct-surface.mjs";
 import { graphAsk, enginePlan } from "./engine-surface.mjs";
-
-let engine = null;
-async function loadEngine() {
-  if (engine) return engine;
-  try {
-    engine = await import("../../services/predator-prey.mjs");
-  } catch (err) {
-    throw new Error(
-      "mudiii's engine (src/services/predator-prey.mjs) is not built in this worktree yet "
-      + `(${err && err.message ? err.message : err})`,
-    );
-  }
-  return engine;
-}
+import {
+  foldTownSquareState, gridApplyActions, pathStateKey, placeFood as engPlaceFood, recastTownSquare,
+  roleOfId, runTownSquareTick, startTownSquareGame, townSquareBoard,
+} from "../../services/predator-prey.mjs";
 
 /** `count` entries drawn at random from `roster`, in random order, without
  *  repeats — mirrors mud-browser-entry.mjs's own `pickMudRoster`. `random` is
@@ -127,6 +114,29 @@ export function driveRequest(direction, { cell, facing = DEFAULT_FACING } = {})
   return COMPASS_POINTS.includes(press) ? { facing: press } : null;
 }
 
+/** The shortest route from `fromCell` to `toCell` over `factRows`' own exit
+ *  facts, as `{ cells, directions }` — `cells` runs from one end to the other
+ *  inclusive, `directions` names one hop each. Null when nothing connects
+ *  them, so a caller declines visibly rather than drawing a line through a
+ *  building the board would never let anyone walk through.
+ *
+ *  The exit table is the one legality answer, the same rows the engine's own
+ *  chase and forage searches read, so a route drawn here is a route the world
+ *  agrees with. */
+export function routeBetweenCells(factRows, fromCell, toCell) {
+  const from = parseCellId(fromCell);
+  const to = parseCellId(toCell);
+  if (!from || !to) return null;
+  const found = findActionPath(
+    from,
+    (searchState) => searchState.x === to.x && searchState.y === to.y,
+    gridApplyActions(factRows),
+    { stateKey: pathStateKey },
+  );
+  if (!found) return null;
+  return { cells: found.states.map((s) => cellId(s.x, s.y)), directions: found.actions };
+}
+
 /** A live, shared town-square world one visitor watches and talks over.
  *  `worldPayload` is `{ name, facts, rules, opening }`, read once at build
  *  time the same way every other viz page's world payload is. `agents` is
@@ -137,15 +147,14 @@ export function driveRequest(direction, { cell, facing = DEFAULT_FACING } = {})
  *  (`runTownSquareTick`) and its conversation is a single shared dock.
  *
  *  Returns `{ memoryDir, codeGraph, graph, refreshGraph, turn, tick, board,
- *  snapshot, applyEdit, placeFood, driveAgent }`. A reset is not a method here: the
- *  page re-opens a whole session for it, which is what a reset means when the
- *  store is in memory and belongs to one visitor. */
-export async function createMudiiiSession(worldPayload, { agents = [], epoch = 0 } = {}) {
-  const {
-    startTownSquareGame, runTownSquareTick, townSquareBoard, foldTownSquareState,
-    placeFood: engPlaceFood, roleOfId,
-  } = await loadEngine();
-
+ *  snapshot, applyEdit, placeFood, driveAgent, recast }`.
+ *
+ *  `getTeachEnabled` is read fresh on every turn, so a visitor can tick the
+ *  page's teach box mid-session and have the very next line read as a fact to
+ *  store rather than a command to run. */
+export async function createMudiiiSession(
+  worldPayload, { agents = [], epoch = 0, getTeachEnabled = () => false } = {},
+) {
   // Every engine call is layout-scoped: the world pack ships the BOARD, and
   // the layout carries the geometry plus the cast counts the engine mints the
   // animals from. Resolved once here so no call site has to remember it.
@@ -184,8 +193,11 @@ export async function createMudiiiSession(worldPayload, { agents = [], epoch = 0
 
   const turnSession = createTurnSession({
     memoryDir, graph: codeGraph, lexicon, sessionId: "town-square",
-    vocabHint: 'Try "@fox-1 look", or "what does fox-1 believe".',
-    buildExtraOptions: () => ({ planState: planHolder.state }),
+    vocabHint: 'Try "@fox the goblin is east", or "what does the fox see".',
+    buildExtraOptions: () => ({
+      planState: planHolder.state,
+      gameConfig: { ...DEFAULT_GAME_CONFIG, mudiii: { ...DEFAULT_GAME_CONFIG.mudiii, teach: getTeachEnabled() } },
+    }),
     captureExtraState: async (result, state) => {
       if ("planState" in result) planHolder.state = state.planState;
     },
@@ -233,6 +245,22 @@ export async function createMudiiiSession(worldPayload, { agents = [], epoch = 0
     };
   }
 
+  /** Re-cast this same store onto a fresh epoch and hand back the opening
+   *  board. This is what a Reset means once a store is live: the world's own
+   *  facts, everything taught into it and everything the editor changed all
+   *  stand, and only the animals are minted again. Re-opening a whole session
+   *  instead would throw away the taught facts along with the cast, which is
+   *  not what "reset the board" says.
+   *
+   *  `agents` sizes the new cast the same way `createMudiiiSession`'s own
+   *  roster does; `epoch` defaults to one past whatever the store is on. */
+  async function recast({ agents: nextAgents = [], epoch: nextEpoch = null } = {}) {
+    await recastTownSquare(memoryDir, {
+      layout, epoch: nextEpoch, ...townSquareRosterArgs(nextAgents, (id) => roleOfId(id)),
+    });
+    return townSquareBoard(memoryDir, { layout });
+  }
+
   /** The board as it stands, in the same payload shape `tick` returns, with no
    *  turn spent. A page opens a session and then draws THIS — otherwise its
    *  first sight of where anything stands is the first tick, and every mesh
@@ -285,6 +313,7 @@ export async function createMudiiiSession(worldPayload, { agents = [], epoch = 0
     turn: turnSession.turn,
     tick,
     driveAgent,
+    recast,
     board,
     snapshot,
     applyEdit,
@@ -304,5 +333,12 @@ publishTmctSurface({
   plan: enginePlan,
   page: {
     pickMudiiiRoster,
+    // pillsForMudiii closes over two other modules' bindings, so the page
+    // reaches it through this bag rather than a `.toString()` splice.
+    pillsForMudiii,
+    // What the editor's own suggestion rail reads for the word under the
+    // cursor: the lateral SKOS neighbourhood and the vertical is-a chain.
+    relatedForTerm, classAncestorChain,
+    routeBetweenCells,
   },
 });

package/src/surfaces/web/tmct-surface.mjs

@@ -25,13 +25,25 @@
 // them apart at a glance, which is exactly what eleven flat bags made
 // impossible.
 //
-// Two more members show up on some pages, by convention rather than by
+// Three more members show up on some pages, by convention rather than by
 // anything this function returns: `tmct.ready` is the page's own boot
-// promise (chat, ingest), and `tmct.lastSave` is its last background-save
-// record, `{at, ms}` (chat, adventure). Neither can be threaded through
-// `publishTmctSurface(...)` itself — boot is still running when this
-// function returns, so the page's own script sets each once it reaches
-// that point (see chat-page-viz.mjs, ingest-viz.mjs, adventure-viz.mjs).
+// promise (chat, ingest), `tmct.lastSave` is its last background-save
+// record, `{at, ms}` (chat, adventure), and `tmct.seed` is what the starter
+// memory is doing — `{state, facts}` through "loading", "indexing", "ready",
+// "failed" (with `error`) and "skipped" (chat, ingest, research).
+//
+// `tmct.seed` is deliberately not the same question as `tmct.ready`. Boot
+// finishing and the memory arriving are separate events, and a page whose
+// seed failed still boots, still opens, and still answers — from a smaller
+// store, which is the open-world assumption behaving correctly rather than a
+// degraded mode. What the seed record adds is the ability to SAY so: a pill
+// that reports real load progress, and a test that can tell a failed download
+// apart from a store that is empty on purpose. Both look like zero facts.
+//
+// None can be threaded through `publishTmctSurface(...)` itself — boot is
+// still running when this function returns, so the page's own script sets
+// each once it reaches that point (see chat-page-viz.mjs, ingest-viz.mjs,
+// adventure-viz.mjs).
 // Each page's older bare global — window.tmctChatReady, tmctIngestReady,
 // tmctChatLastSave, tmctAdventureLastSave — keeps working unchanged;
 // `tmct.ready` / `tmct.lastSave` just reach the same value under the one

package/src/tools/handlers/tmct-ask.mjs

@@ -1,5 +1,11 @@
 // tmct_ask — a plain-English structural question answered from the graph in one
 // mechanical, zero-model-call round-trip. See src/domain/ask.mjs.
+//
+// SYNCHRONOUS, and callers rely on it: the browser's code explorer imports this
+// function directly and reads the envelope off the return, twice per relation
+// kind, to build its sidebar. Anything that has to await — the memory fallback a
+// cold surface supplies — composes AROUND this at dispatch, never inside it.
+// See askWithMemoryFallback in ../server.mjs.
 
 import { ask } from "../../domain/ask.mjs";
 import { requiredArg, toolResult } from "./kit.mjs";
@@ -9,11 +15,18 @@ import { requiredArg, toolResult } from "./kit.mjs";
  *  that still read that string split it on the one constant rather than their own copy. */
 export const ASK_ENVELOPE_DELIM = "\n\n---tmct_ask---\n";
 
-export function tmct_ask(args, { graph }) {
-  const { content, tmct_ask: envelope } = ask(graph, requiredArg(args, "query"));
+/** One answer + envelope as a tool result. Shared with the memory fallback, so
+ *  both spellings of an answered ask carry the envelope in the same three
+ *  places (prose, structured data, and the in-band string). */
+export function askToolResult(content, envelope) {
   return toolResult({
     content,
     data: envelope,
     text: `${content}${ASK_ENVELOPE_DELIM}${JSON.stringify(envelope, null, 2)}`,
   });
 }
+
+export function tmct_ask(args, { graph }) {
+  const { content, tmct_ask: envelope } = ask(graph, requiredArg(args, "query"));
+  return askToolResult(content, envelope);
+}

package/src/tools/server.mjs

@@ -23,6 +23,7 @@ import { ask } from "../domain/ask.mjs";
 import { createGraphService } from "../adapters/providers/graph-service.mjs";
 import { loadGraph } from "./graph-load.mjs";
 import { HANDLERS } from "./handlers/index.mjs";
+import { askToolResult } from "./handlers/tmct-ask.mjs";
 import { isToolResult } from "./handlers/kit.mjs";
 import { setDefaultNlpAdapter } from "../domain/interpret/nlp-registry.mjs";
 import { setConstructionBanks } from "../domain/interpret/strategies/constructions.mjs";
@@ -50,7 +51,7 @@ export const TOOLS = HOT_TOOLS.map(({ name, agentDescription, inputSchema }) =>
   inputSchema,
 }));
 
-async function runHandler(name, args, { config, source = defaultSource, tel = null, ingest = null, memoryBackend = null, graph: suppliedGraph = null } = {}) {
+async function runHandler(name, args, { config, source = defaultSource, tel = null, ingest = null, memoryBackend = null, factLookup = null, graph: suppliedGraph = null } = {}) {
   // Reject an unknown tool BEFORE touching the graph — an unknown name never
   // triggers a load. hasOwn, so an inherited name ("constructor", "toString")
   // is unknown rather than a callable found on the prototype chain.
@@ -78,7 +79,35 @@ async function runHandler(name, args, { config, source = defaultSource, tel = nu
   // isn't there.
   const repoRoot = config?.graphFile ? dirname(dirname(config.graphFile)) : null;
   const svc = createGraphService(graph, { sourceAccess: Boolean(repoRoot), repoRoot, readFile, tel, ask });
-  return handle(args, { graph, svc, config, repoRoot, memoryBackend });
+  const out = handle(args, { graph, svc, config, repoRoot, memoryBackend });
+  return name === "tmct_ask" ? askWithMemoryFallback(out, args, factLookup) : out;
+}
+
+/** Offer a graph miss to the caller's own memory reader before the miss stands.
+ *  `factLookup` is a seam of the same kind as `ingest`: the conversational
+ *  store's vocabulary reader lives in the SERVICE layer, which this layer sits
+ *  under and must not import, so a cold caller holding a repo's memory hands it
+ *  in. A caller that supplies none keeps the graph-only answer, byte for byte.
+ *
+ *  Composed HERE rather than inside the handler because the handler is a
+ *  synchronous entry the browser's code explorer calls directly — an `async`
+ *  handler hands that caller a promise whose `.data` is undefined, and its
+ *  sidebar silently draws nothing. Dispatch already awaits, so the awaiting
+ *  belongs here. */
+async function askWithMemoryFallback(out, args, factLookup) {
+  const envelope = out?.data;
+  if (!envelope?.miss || typeof factLookup !== "function") return out;
+  let fromMemory = null;
+  try { fromMemory = await factLookup(String(args?.query ?? ""), envelope); } catch { fromMemory = null; }
+  if (!fromMemory?.text) return out;
+  // A reader hit flagged `miss` is the same refusal in better words, so the
+  // envelope keeps its miss and only the prose improves.
+  const content = fromMemory.replace ? fromMemory.text : `${out.content}\n${fromMemory.text}`;
+  return askToolResult(content, {
+    ...envelope,
+    miss: Boolean(fromMemory.miss),
+    matchedVia: fromMemory.miss ? envelope.matchedVia : "memory",
+  });
 }
 
 /** The caller-facing string for one tool call. A handler that returns a structured