@polycode-projects/the-mechanical-code-talker 4.1.0 → 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,
@@ -48,6 +49,8 @@ import { worldProvenanceTag } from "../../domain/worlds-pack.mjs";
 import { resolveSpriteForClass, SPRITE_REGISTRY, classAncestorChain } from "../../domain/sprite-map.mjs";
 import { resolveSpriteAsset } from "../../domain/sprite-templates.mjs";
 import { createTurnSession } from "./turn-session.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
 
 /** A live, shared mud world several characters can each act in. `worldPayload`
  *  is `{ name, facts, rules, opening }` — the same shape adventure-browser-
@@ -60,7 +63,10 @@ import { createTurnSession } from "./turn-session.mjs";
  *  are minted, fewer leaves the ones nobody is playing out of the world
  *  altogether.
  *
- *  Returns `{ memoryDir, 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
@@ -87,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
@@ -99,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;
@@ -124,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;
@@ -156,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;
@@ -270,7 +291,13 @@ export async function createMudSession(worldPayload, { characters = [], epoch =
     return claims.length;
   }
 
-  return { memoryDir, 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
@@ -351,22 +378,47 @@ export function worldFactsForCast(facts, characters) {
   return rows.filter((f) => !uncast.has(f.subject)).concat(mintedCharacterFacts(rows, characters));
 }
 
-// Re-exported so mud-viz.mjs's own inlined script never duplicates sprite
-// resolution or the digest/affordance/knowledge readers its room view and
-// chat pills already need — the same reach-through-the-global posture
-// adventure-browser-entry.mjs's own globalThis.tmctAdventure takes.
-globalThis.tmctMud = {
-  createMudSession, pickMudRoster, expandMudRoster, mintedCharacterFacts, worldFactsForCast,
-  resolveSpriteForClass, SPRITE_REGISTRY, classAncestorChain, resolveSpriteAsset,
-  foldWorldState, worldActionRows, worldDigestRows, roomAffordances,
-  personKnowledgeLines, personKnownFoodLines,
-  diggableDirections, castInRoom, displayNameOf, isOutOfPlay, outOfPlayReasonOf, outOfPlayPhrase,
-  roomKindOf,
-  // The shared-world reach-throughs: which predicates carry live world state,
-  // and the P2P layer's own four. mud.html hands both to `mudSyncableFacts`,
-  // which is written to take the check rather than import the engine itself.
-  isMudStatePredicate, P2P_PREDICATES,
-  // The edit mode's own reach-throughs: the SKOS neighbourhood and the is-a
-  // chain its cursor-suggestion pills read, neither of which is splice-safe.
-  relatedForTerm,
-};
+// Several characters, one world, so a line has to say who is speaking:
+// `tmct.turn(line, { as: "mole-1" })` routes to that character's own window,
+// which owns its private focus/last and its own fog of war. Everything else a
+// window does — a scripted autoplayTick, its visited rooms, whether it is
+// still in play — stays on `tmct.session.windows[id]`, because those are
+// per-character state rather than questions anyone could ask in words.
+//
+// `tmct.page` keeps the sprite resolution and the digest/affordance/knowledge
+// readers the room view and chat pills render from, the roster helpers that
+// decide which animals this visit is played with, the two predicate lists the
+// P2P layer checks against, and the SKOS neighbourhood behind the edit mode's
+// cursor pills — none of which is `.toString()`-splice-safe.
+publishTmctSurface({
+  open: createMudSession,
+  turn: (line, options, session) => {
+    const character = options?.as;
+    const characterWindow = character ? session.windows[character] : null;
+    if (!characterWindow) {
+      return {
+        answer: `say which character is speaking — tmct.turn(line, { as: "${Object.keys(session.windows)[0] || "mole-1"}" })`,
+        end: false, record: null, plan: null, research: null,
+      };
+    }
+    return characterWindow.turn(line);
+  },
+  // 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,
+    resolveSpriteForClass, SPRITE_REGISTRY, classAncestorChain, resolveSpriteAsset,
+    foldWorldState, worldActionRows, worldDigestRows, roomAffordances,
+    personKnowledgeLines, personKnownFoodLines,
+    diggableDirections, castInRoom, displayNameOf, isOutOfPlay, outOfPlayReasonOf, outOfPlayPhrase,
+    roomKindOf,
+    isMudStatePredicate, P2P_PREDICATES,
+    relatedForTerm,
+  },
+});

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,12 +29,13 @@ 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";
 // Re-exported so the page can register a CDN-loaded wink-nlp pair before the
 // first teach, the same seam chat-browser-entry.mjs exposes as
-// tmctChat.registerWinkModel — see wink-model.mjs's own header. The hanoi
+// tmct.page.registerWinkModel — see wink-model.mjs's own header. The hanoi
 // lesson's own "moving a disk onto a target makes the disk rest on the
 // target" sentence needs a REAL lemmatiser (verbLemma reduces "moving" to
 // "move" to match the taught "move onto" action family) — without it, that
@@ -44,10 +45,12 @@ import { createTurnSession } from "./turn-session.mjs";
 // model because their own gameplay never asks a taught rule to reduce a
 // verb; the hanoi lesson is the first live session here that does.
 import { registerWinkModel } from "../../adapters/wink-model.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
 
 /** A live in-memory towers-of-hanoi session this page's live controls AND
- *  chat dock can both drive. Returns `{ memoryDir, sessionId, diskCount,
- *  maxDepth, plan, turn }`. `plan` is the puzzle's freshly solved plan (the
+ *  chat dock can both drive. Returns `{ memoryDir, sessionId, graph,
+ *  diskCount, maxDepth, plan, turn }`. `plan` is the puzzle's freshly solved plan (the
  *  same shape chat.mjs's planLaneAnswer returns, enriched with
  *  `becauseText` — see `turn()` below), or null when `maxDepth` was too low
  *  to find one (an honest miss, not an error: `turn()`'s own answer text
@@ -84,13 +87,48 @@ export async function createPlanSession({ diskCount = 3, maxDepth = DEFAULT_GAME
     if (r.plan) plan = r.plan;
   }
 
-  return { memoryDir, sessionId, 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; },
+  };
 }
 
-// Re-exported so the page's own rendering script (plan-viz.mjs's inlined
-// script) never has to duplicate board layout or PDDL/OWL-RDF formatting —
-// the same posture adventure-browser-entry.mjs/spider-fly-browser-entry.mjs
-// take re-exporting their own engines' pure helpers.
-globalThis.tmctPlan = {
-  createPlanSession, computeBlocksLayout, planToPageData, renderInputsFromPlan, planToPddl, registerWinkModel,
-};
+// `tmct.page` keeps the board layout and the PDDL/OWL-RDF formatting the
+// page's own script draws with, plus the wink seam the hanoi lesson needs
+// registered before its first teach. Note that `tmct.plan(...)` here is the
+// 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: (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

@@ -39,15 +39,10 @@ import { groundTextToFacts } from "./ingest-browser-entry.mjs";
 import { openPersistedStore } from "./idb-persist.mjs";
 import { digestTermFromPayloadBrowser } from "./digest-client.mjs";
 import { createTurnSession } from "./turn-session.mjs";
+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
@@ -100,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"];
@@ -210,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.
@@ -234,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") {
@@ -247,6 +241,7 @@ export function createResearchSession({ seedPayload = null, vocabSeeded = false,
 
   return {
     memoryDir,
+    graph,
     chatSessionId,
     ingestSessionId,
     sessionIds,
@@ -327,8 +322,22 @@ export function createResearchSession({ seedPayload = null, vocabSeeded = false,
   };
 }
 
-globalThis.tmctResearch = {
-  createResearchSession, researchSnapshot, exportFactsJsonl,
-  registerWinkModel, registerReferencePackProvider, registerLiveReferenceProvider, registerResearchProvider,
-  normFactTerm, vocabExampleHint, openPersistedStore,
-};
+// This page's ask is already source-scoped: `tmct.ask(q, { sources })` keeps
+// the checked source keys and runs the same factAnswer/factReadBack cascade
+// the ledger dock runs, so a visitor can see the answer change as they tick
+// sources off. `tmct.page` keeps the provider and wink seams the page
+// registers, the run snapshot its timeline reads, its persisted store and its
+// JSONL export.
+publishTmctSurface({
+  open: createResearchSession,
+  ask: async (request, options, session) => {
+    const { text, miss } = await session.ask(request, options);
+    return { answer: text, data: null, miss };
+  },
+  plan: enginePlan,
+  page: {
+    researchSnapshot, exportFactsJsonl,
+    registerWinkModel, registerReferencePackProvider, registerLiveReferenceProvider, registerResearchProvider,
+    normFactTerm, vocabExampleHint, openPersistedStore,
+  },
+});

package/src/surfaces/web/spider-fly-browser-entry.mjs

@@ -44,6 +44,8 @@
 // them back (hand-written pathfinding over has-exit-* facts, not the taught
 // action-rule DSL), so nothing here depends on them being loaded.
 import { createTurnSession } from "./turn-session.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
 import { registerWinkModel } from "../../adapters/wink-model.mjs";
 import {
   createInMemoryStore, normFactTerm, appendFacts, loadMemory, readFactRows,
@@ -137,6 +139,16 @@ export async function createSpiderFlySession({ flyCount = 1 } = {}) {
     initial: { turn: 0, agents: initialAgents, activeWebs: [] },
     taxonomyRows,
 
+    /** The board as a graph, as of the last refresh. Every tick moves the
+     *  pieces, so a caller putting a question to it calls `refreshGraph()`
+     *  first — which is exactly what `turn()` below already does. */
+    get graph() { return graph; },
+
+    /** Rebuild the board graph from the store's current rows. Exposed so a
+     *  question asked outside the chat dock (tmct.ask) reads this turn's
+     *  positions and not last turn's, the same way a typed one does. */
+    refreshGraph: refreshWorldGraph,
+
     /** Run one real engine turn directly. Returns spider-fly.mjs's own
      *  { turn, agents, ecology } shape unmodified. */
     async tick() {
@@ -189,16 +201,23 @@ export async function createSpiderFlySession({ flyCount = 1 } = {}) {
   };
 }
 
-// cellId/parseCellId/DIRECTION_DELTA/visibleCells/DEFAULT_VISION_RADIUS are
-// re-exported so the page's own rendering script (spider-fly-viz.mjs) never
-// has to duplicate grid geometry or the vision-radius default: reconstructing
-// a spider's remaining silk-thread path from its returned direction list, and
-// computing the POV overlay's visible-cell mask, both need them.
-// pillsForSpiderFly/oneStepDirectionBetween are re-exported so the same page
-// can build its own dynamic deception-pill container without duplicating
-// spider-fly-turn.mjs's own pill logic.
-globalThis.tmctSpiderFly = {
-  createSpiderFlySession, normFactTerm, resolveSpriteForClass, SPRITE_REGISTRY, resolveSpriteAsset,
-  cellId, parseCellId, DIRECTION_DELTA, visibleCells, DEFAULT_VISION_RADIUS,
-  pillsForSpiderFly, oneStepDirectionBetween, DEFAULT_GAME_CONFIG, registerWinkModel,
-};
+// `tmct.page` is grid geometry and sprite resolution — the two things on this
+// page the engine has no plain-English form for. Reconstructing a spider's
+// remaining silk-thread path from its returned direction list and masking the
+// POV overlay's visible cells both need the raw cell math; the deception pills
+// need spider-fly-turn.mjs's own pill logic.
+publishTmctSurface({
+  open: createSpiderFlySession,
+  // The board moves every tick, so a question rebuilds the graph first —
+  // the same refresh a typed turn does before it dispatches.
+  ask: async (request, options, session) => {
+    await session.refreshGraph();
+    return graphAsk(request, options, session);
+  },
+  plan: enginePlan,
+  page: {
+    normFactTerm, resolveSpriteForClass, SPRITE_REGISTRY, resolveSpriteAsset,
+    cellId, parseCellId, DIRECTION_DELTA, visibleCells, DEFAULT_VISION_RADIUS,
+    pillsForSpiderFly, oneStepDirectionBetween, DEFAULT_GAME_CONFIG, registerWinkModel,
+  },
+});

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

@@ -18,38 +18,78 @@
 // 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, 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,
+    get graph() { return graph; },
+    refreshGraph,
     factCount: factRows.length,
-    turn: session.turn,
+    async turn(line) {
+      await refreshGraph();
+      return turnSession.turn(line);
+    },
   };
 }
 
-// registerWinkModel is re-exported so the page's own inline script can hand in
-// the self-hosted wink pair (./vendor/wink.js) exactly the way chat.html/
-// ledger.html/plan.html register theirs — the bundle itself never imports
-// wink-nlp (wink-model.mjs's own header explains why).
-globalThis.tmctSprites = { createSpriteCatalogSession, registerWinkModel, normFactTerm, extractSceneItems };
+// `tmct.page` keeps the wink seam (the page hands in the self-hosted pair from
+// ./vendor/wink.js, exactly the way chat.html/ledger.html/plan.html register
+// theirs — the bundle itself never imports wink-nlp), the term normalizer, and
+// the scene composer's parser, which reads a typed line into drawable items
+// rather than answering anything.
+publishTmctSurface({
+  open: createSpriteCatalogSession,
+  // 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 },
+});