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

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/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