@polycode-projects/the-mechanical-code-talker 4.1.1 → 4.1.2

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

@@ -32,6 +32,7 @@ import {
   createInMemoryStore, appendFacts, appendRule, loadMemory, readFactRows, removeFacts,
 } from "../../adapters/memory/core.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
+import { memoryFactGraphPayload } from "../../domain/memory-facts.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import {
   foldWorldState, worldActionRows, worldDigestRows, roomAffordances,
@@ -62,7 +63,10 @@ import { graphAsk, enginePlan } from "./engine-surface.mjs";
  *  are minted, fewer leaves the ones nobody is playing out of the world
  *  altogether.
  *
- *  Returns `{ memoryDir, graph, windows, snapshot }`. `windows` is a plain object
+ *  Returns `{ memoryDir, codeGraph, graph, refreshGraph, windows, snapshot }`.
+ *  `codeGraph` is the known-empty index the turn engine and a scripted
+ *  autoplayTick read; `graph` is this world's own memory store projected for
+ *  `ask()` (refreshGraph rebuilds it on demand). `windows` is a plain object
  *  keyed by character id, each value `{ character, turn, autoplayTick,
  *  visitedRoomIds, turnsTaken, isOutOfPlay, outOfPlayReason }`. `snapshot()` is
  *  the one OMNISCIENT read this module exposes — the central world map's own
@@ -89,7 +93,11 @@ export async function createMudSession(worldPayload, { characters = [], epoch =
   // way rather than through the "play <world>" opener (which needs a
   // shipped "player" individual mud-garden deliberately has none of).
   const planHolder = { state: { adventure: { world: worldPayload.name } } };
-  const graph = parseEntities({ individuals: [], objectProperties: [] });
+  // A known-empty code graph: code-structure questions get the same honest
+  // no-code-graph answer an un-pointed CLI session gives, never a crash — the
+  // turn engine (and a scripted autoplayTick) keep reading THIS one for their
+  // own in-turn code lane.
+  const codeGraph = parseEntities({ individuals: [], objectProperties: [] });
   // The world's own minted ids ("groundhog-1", "carrot-2") are declared as
   // vocabulary inside the adventure lane itself, for the length of one world
   // command — see adventure.mjs's own worldLexicon. This page hands over the
@@ -101,6 +109,17 @@ export async function createMudSession(worldPayload, { characters = [], epoch =
     return { rows, state: foldWorldState(worldActionRows(rows)) };
   }
 
+  // What `tmct.ask()` traverses is a different graph: this shared world's own
+  // memory store, projected through memoryFactGraphPayload. Rebuilt on demand
+  // rather than once at open, because every character's turn grows the store.
+  // Built off readWorld()'s own rows rather than a second readFactRows call.
+  let memoryGraph = parseEntities({ individuals: [], objectProperties: [] });
+  async function refreshGraph() {
+    const { rows } = await readWorld();
+    memoryGraph = parseEntities(memoryFactGraphPayload(rows));
+    return memoryGraph;
+  }
+
   async function roomOf(character) {
     const { state } = await readWorld();
     return state.placements.get(character)?.object ?? null;
@@ -126,10 +145,10 @@ export async function createMudSession(worldPayload, { characters = [], epoch =
     if (startRoom) visitedRoomIds.add(startRoom);
 
     const turnSession = createTurnSession({
-      memoryDir, graph, lexicon, sessionId: character,
+      memoryDir, graph: codeGraph, lexicon, sessionId: character,
       vocabHint: 'Try a world command ("dig north", "eat the carrot-1"), or ask "what food do you know about".',
       buildExtraOptions: () => ({
-        uiContext: "browser", actingSubject: character, planState: planHolder.state,
+        actingSubject: character, planState: planHolder.state,
       }),
       captureExtraState: async (result, state) => {
         if ("planState" in result) planHolder.state = state.planState;
@@ -158,7 +177,7 @@ export async function createMudSession(worldPayload, { characters = [], epoch =
        *  note }` unmodified, so the caller can render the speech-bubble/
        *  dig-flourish triggers straight off `actions`. */
       async autoplayTick(k) {
-        const result = await runMudTurn(character, { world: worldPayload.name, memoryDir, env: {}, graph, k });
+        const result = await runMudTurn(character, { world: worldPayload.name, memoryDir, env: {}, graph: codeGraph, k });
         // A turn that ended in starvation still happened, and still counts —
         // only a DECLINED turn (no room to act in) leaves the tally alone.
         if (result.room) turnsTaken += 1;
@@ -272,7 +291,13 @@ export async function createMudSession(worldPayload, { characters = [], epoch =
     return claims.length;
   }
 
-  return { memoryDir, graph, windows, snapshot, applyEdit, wave, claimCharacters };
+  return {
+    memoryDir,
+    codeGraph,
+    get graph() { return memoryGraph; },
+    refreshGraph,
+    windows, snapshot, applyEdit, wave, claimCharacters,
+  };
 }
 
 /** `count` entries drawn at random from `roster`, in random order, without
@@ -378,7 +403,13 @@ publishTmctSurface({
     }
     return characterWindow.turn(line);
   },
-  ask: graphAsk,
+  // The memory projection is rebuilt first, so a direct tmct.ask() sees every
+  // fact any character's turn has written into this shared world since the
+  // last one.
+  ask: async (request, options, session) => {
+    await session.refreshGraph();
+    return graphAsk(request, options, session);
+  },
   plan: enginePlan,
   page: {
     pickMudRoster, expandMudRoster, mintedCharacterFacts, worldFactsForCast,

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

@@ -26,7 +26,7 @@ export {
   ROOM_FAILED,
 } from "../../services/p2p-room.mjs";
 export { createTransport } from "../../adapters/p2p/webrtc-transport.mjs";
-export { generatePeerId, generateWorldId, generateDisplayName } from "../../domain/p2p/peer-id.mjs";
+export { generatePeerId, generateWorldId, generateDisplayName, generateNodeId } from "../../domain/p2p/peer-id.mjs";
 export { chatSyncableFacts, mudSyncableFacts } from "../../domain/p2p/sync-filter.mjs";
 export { decodeInviteBlob, encodeInviteBlob } from "../../domain/p2p/wire.mjs";
 export {

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

@@ -29,6 +29,7 @@ import { parseEntities } from "../../domain/codegraph.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import { DEFAULT_GAME_CONFIG } from "../../domain/game-config.mjs";
 import { hanoiLessonSentences } from "../../domain/hanoi-lesson.mjs";
+import { hanoiBoardRows, hanoiBoardGraphPayload } from "../../domain/hanoi-board.mjs";
 import { computeBlocksLayout, planToPageData, renderInputsFromPlan } from "../../services/plan-viz.mjs";
 import { planToPddl } from "../../services/plan-pddl.mjs";
 import { createTurnSession } from "./turn-session.mjs";
@@ -86,7 +87,29 @@ export async function createPlanSession({ diskCount = 3, maxDepth = DEFAULT_GAME
     if (r.plan) plan = r.plan;
   }
 
-  return { memoryDir, sessionId, graph, diskCount, maxDepth, plan, turn: session.turn };
+  // The board `tmct.ask()` traverses. The plan lane's own states are rows, not
+  // a graph, so an ask over this session used to meet an empty one and miss
+  // every question about the puzzle in front of the visitor. hanoi-board.mjs
+  // projects one position into `{individuals, objectProperties}`; the page
+  // calls `showBoard` whenever it mounts a fresh plan or the transport moves
+  // the step, so what ask() reads is what the board shows.
+  let boardPlan = plan;
+  let boardStep = 0;
+  let boardGraph = null;
+  function showBoard({ plan: nextPlan = boardPlan, step = boardStep } = {}) {
+    boardPlan = nextPlan;
+    boardStep = Math.max(0, Math.floor(Number(step) || 0));
+    boardGraph = parseEntities(hanoiBoardGraphPayload(hanoiBoardRows({ plan: boardPlan, step: boardStep })));
+    return boardGraph;
+  }
+  showBoard();
+
+  return {
+    memoryDir, sessionId, graph, diskCount, maxDepth, plan, turn: session.turn,
+    showBoard,
+    get boardGraph() { return boardGraph; },
+    get boardStep() { return boardStep; },
+  };
 }
 
 // `tmct.page` keeps the board layout and the PDDL/OWL-RDF formatting the
@@ -95,9 +118,17 @@ export async function createPlanSession({ diskCount = 3, maxDepth = DEFAULT_GAME
 // CAPABILITY planner, not the puzzle solver: a typed "solve it" is a
 // conversational turn like any other, so the page reaches the hanoi plan
 // through `tmct.turn("solve it", { maxDepth })` and reads `.plan` off it.
+//
+// `tmct.ask(q, { step })` answers over the projected BOARD rather than the
+// session's own (empty) code graph, so a question about the puzzle is grounded
+// in the position on screen. Passing `step` moves the board first, which is
+// how the page keeps the two in step while the transport scrubs.
 publishTmctSurface({
   open: createPlanSession,
-  ask: graphAsk,
+  ask: (request, options, session) => {
+    if (options?.step != null) session.showBoard({ step: options.step });
+    return graphAsk(request, options, { graph: session.boardGraph, memoryDir: session.memoryDir });
+  },
   plan: enginePlan,
   page: { computeBlocksLayout, planToPageData, renderInputsFromPlan, planToPddl, registerWinkModel },
 });

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

@@ -43,13 +43,6 @@ import { publishTmctSurface } from "./tmct-surface.mjs";
 import { enginePlan } from "./engine-surface.mjs";
 import { exportFactsJsonl } from "./memory-stats.mjs";
 
-// The Fact individual's first-write-wins timestamp, read straight off the
-// stored attribute (mgx:createdAt) so a "recently learned" ordering never
-// has to re-parse a provenance tag — the research lane's own tags carry a
-// depth, not a timestamp, so the attribute is the one field every source
-// shares.
-const CREATED_AT_ATTR = "mgx:createdAt";
-
 /**
  * The source key ONE provenance tag folds to, for the page's per-source
  * checkboxes/history. `sessionIds` tells a teach tag apart: a teach:chat tag
@@ -102,18 +95,17 @@ const clonePayload = (payload) => {
   try { return structuredClone(payload); } catch { return JSON.parse(JSON.stringify(payload)); }
 };
 
-/** Fact rows plus the createdAt attribute readFactRows drops, in one pass over
- *  the loaded memory — the "recently learned" panels want the timestamp, the
- *  ask filter wants the id, both want the provenance. */
+/** Fact rows plus the createdAt readFactRows keeps per assertion rather than per
+ *  row — the "recently learned" panels want the timestamp, the ask filter wants
+ *  the id, both want the provenance. A triple asserted by several sources was
+ *  first learned when the EARLIEST of them said it, which is the moment those
+ *  panels are ordering by. */
 async function factRowsWithCreatedAt(memoryDir) {
   const memory = await loadMemory(memoryDir);
-  const createdById = new Map();
-  for (const ind of memory?.individuals || []) {
-    if (ind?.class !== "Fact") continue;
-    const at = (ind.attributes || []).find((a) => a?.prop === CREATED_AT_ATTR || a?.key === CREATED_AT_ATTR)?.value || "";
-    createdById.set(ind.id, at);
-  }
-  return readFactRows(memory).map((row) => ({ ...row, createdAt: createdById.get(row.id) || "" }));
+  return readFactRows(memory).map((row) => {
+    const stamps = (row.assertions || []).map((a) => a.createdAt).filter(Boolean).sort();
+    return { ...row, createdAt: stamps[0] || "" };
+  });
 }
 
 const SOURCE_ORDER = ["taught", "ingest", "research"];
@@ -212,7 +204,7 @@ export function createResearchSession({ seedPayload = null, vocabSeeded = false,
 
   const graph = parseEntities({ individuals: [], objectProperties: [] });
   const lexicon = loadLexicon();
-  const vocabHint = vocabExampleHint(vocabSeeded);
+  const vocabHint = vocabExampleHint(vocabSeeded, "browser");
   // A DISTINCT id so an ingested fact's teach tag is told apart from a typed
   // teach turn's by session id alone — the whole reason the two growth paths
   // stay separable in the source panel.
@@ -236,7 +228,7 @@ export function createResearchSession({ seedPayload = null, vocabSeeded = false,
     sessionId: globalThis.crypto?.randomUUID?.() ?? String(Date.now()),
     buildExtraOptions: () => ({
       researchConfig, liveReference: liveReferenceOn, onLiveLookup,
-      uiContext: "browser", synthesisBudget: synthesisBudgetOn,
+      synthesisBudget: synthesisBudgetOn,
     }),
     captureExtraState: (result) => {
       if (typeof result.liveReference === "boolean" || result.liveReference === "supplement" || result.liveReference === "always") {

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

@@ -18,36 +18,62 @@
 // a typed class name through ask.mjs's resolveObject, so it needs the real
 // resolver in the page rather than a self-contained function the page could
 // splice in as text.
-import { createInMemoryStore, appendFacts, normFactTerm } from "../../adapters/memory/core.mjs";
+//
+// `tmct.ask()` needs a real graph to traverse (engine-surface.mjs's graphAsk
+// dispatches tmct_ask over `session.graph`), so this session projects its own
+// store into one via spriteFactGraphPayload — sprite-facts.mjs's own
+// counterpart to spider-fly-browser-entry.mjs's worldRelationGraphPayload
+// use. `refreshGraph()` rebuilds it from the store's CURRENT rows (not just
+// the embedded factRows), so a fact taught mid-session is visible to a later
+// ask() the same way spider-fly's board rebuild is; `turn()` and the
+// published `ask` route both call it first, mirroring spider-fly's exact
+// wiring points.
+import { createInMemoryStore, appendFacts, normFactTerm, loadMemory, readFactRows } from "../../adapters/memory/core.mjs";
 import { extractSceneItems } from "../../domain/scene-compose.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
-import { SPRITE_FACTS_PROVENANCE } from "../../domain/sprite-facts.mjs";
+import { SPRITE_FACTS_PROVENANCE, spriteFactGraphPayload } from "../../domain/sprite-facts.mjs";
 import { registerWinkModel } from "../../adapters/wink-model.mjs";
 import { createTurnSession } from "./turn-session.mjs";
 import { publishTmctSurface } from "./tmct-surface.mjs";
 import { graphAsk, enginePlan } from "./engine-surface.mjs";
 
 /** A live in-memory chat session seeded with the embedded sprite-facts rows.
- *  Returns { memoryDir, sessionId, graph, factCount, turn }. */
+ *  Returns { memoryDir, sessionId, graph, refreshGraph, factCount, turn }. */
 export async function createSpriteCatalogSession({ factRows = [] } = {}) {
   const memoryDir = createInMemoryStore();
   await appendFacts(memoryDir, factRows.map((f) => ({
     subject: f.subject, predicate: f.predicate, object: f.object, provenance: SPRITE_FACTS_PROVENANCE,
   })));
 
-  const graph = parseEntities({ individuals: [], objectProperties: [] });
+  let graph = parseEntities({ individuals: [], objectProperties: [] });
+  async function refreshGraph() {
+    const rows = readFactRows(await loadMemory(memoryDir));
+    graph = parseEntities(spriteFactGraphPayload(rows));
+  }
+  await refreshGraph();
+
   const lexicon = loadLexicon();
   const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
 
-  const session = createTurnSession({ memoryDir, graph, lexicon, sessionId, vocabHint: "" });
+  // `graph` is re-read here, not captured once: createTurnSession binds its
+  // own copy at creation, and refreshGraph() reassigns this closure's own
+  // variable on every call.
+  const turnSession = createTurnSession({
+    memoryDir, graph, lexicon, sessionId, vocabHint: "",
+    buildExtraOptions: () => ({ graph }),
+  });
 
   return {
     memoryDir,
     sessionId,
-    graph,
+    get graph() { return graph; },
+    refreshGraph,
     factCount: factRows.length,
-    turn: session.turn,
+    async turn(line) {
+      await refreshGraph();
+      return turnSession.turn(line);
+    },
   };
 }
 
@@ -58,7 +84,12 @@ export async function createSpriteCatalogSession({ factRows = [] } = {}) {
 // rather than answering anything.
 publishTmctSurface({
   open: createSpriteCatalogSession,
-  ask: graphAsk,
+  // The graph is rebuilt first, so a direct tmct.ask() call (not just a
+  // typed chat turn) sees any fact taught since the last one.
+  ask: async (request, options, session) => {
+    await session.refreshGraph();
+    return graphAsk(request, options, session);
+  },
   plan: enginePlan,
   page: { registerWinkModel, normFactTerm, extractSceneItems },
 });

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

@@ -25,6 +25,18 @@
 // 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
+// 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).
+// 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
+// `tmct.*` name everything else on this page already uses.
+//
 // `ask` and `plan` are supplied per page rather than fixed here, because what
 // a page can ground a question against genuinely differs: code-explorer holds
 // a code graph, spider-fly holds a live board projected into one, the ledger

package/src/surfaces/web/turn-session.mjs

@@ -9,8 +9,15 @@
 // capture, and a return shape covering every field one caller or another
 // reads back.
 //
+// Every caller of this wrapper is a page by construction, so `uiContext:
+// "browser"` is a DEFAULT here rather than something each entry remembers to
+// pass. It is what makes the engine's dead-ends name an exit a page can take
+// ("teach me a fact") instead of the CLI's `tmct index`/`--repo`/`tmct init`.
+// Five of the nine already passed it and four had never got round to it, which
+// is exactly the drift a shared default removes.
+//
 // The nine differ in what they hand `runTurn` beyond the common core
-// (`uiContext`, `synthesisBudget`, `gameConfig`, `researchConfig`,
+// (`synthesisBudget`, `gameConfig`, `researchConfig`,
 // `actingSubject`, a per-character `sessionId`...) and in what they do with a
 // turn's result besides the standard focus/last/planState/researchState fold
 // (sync an externally-held plan holder, grow a visited-rooms set, bump a
@@ -41,7 +48,7 @@ function turnErrorFallback(message) {
  *
  * `buildExtraOptions(state, callArgs)` (optional) returns extra `runTurn`
  * options to merge OVER the defaults below — anything a specific page needs
- * (`uiContext: "browser"`, `synthesisBudget`, `gameConfig`, `researchConfig`,
+ * (`synthesisBudget`, `gameConfig`, `researchConfig`,
  * a per-character `actingSubject`/`sessionId`, or a `planState` read from an
  * external holder instead of this closure's own). `state` is
  * `{ focus, last, planState, researchState }` as this turn is about to run;
@@ -88,7 +95,7 @@ export function createTurnSession({
     try {
       result = await runTurn(line, {
         config: null, source: null, graph, focus, last, memoryDir, sessionId,
-        env: {}, lexicon, vocabHint, planState, researchState,
+        env: {}, lexicon, vocabHint, planState, researchState, uiContext: "browser",
         ...extra,
       });
     } catch (e) {