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

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

@@ -35,10 +35,13 @@
 // game-shaped falls through to the ordinary conversational layer, exactly
 // like a real CLI session.
 import { createTurnSession } from "./turn-session.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
 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, worldDigestRows, roomAffordances, worldActionRows } from "../../services/adventure.mjs";
 import { runAdventureAutoplayTick, exposedFacts } from "../../services/adventure-autoplay.mjs";
@@ -101,7 +104,21 @@ export async function createAdventureSession(worldPayload, { restoredPayload = n
   const openingHere = foldWorldState(worldActionRows(openingRows)).placements.get("player")?.object ?? null;
   if (openingHere) visitedRoomIds.add(openingHere);
 
-  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 keeps reading THIS one for its own in-turn code lane.
+  const codeGraph = parseEntities({ individuals: [], objectProperties: [] });
+
+  // What `tmct.ask()` traverses is a different graph: this world's own memory
+  // store, projected through memoryFactGraphPayload. Rebuilt on demand rather
+  // than once at open, because every taught fact and every played turn grows
+  // the store.
+  let memoryGraph = parseEntities({ individuals: [], objectProperties: [] });
+  async function refreshGraph() {
+    memoryGraph = parseEntities(memoryFactGraphPayload(readFactRows(await loadMemory(memoryDir))));
+    return memoryGraph;
+  }
+
   const lexicon = loadLexicon();
 
   // createTurnSession owns focus/last and the catch fallback; planHolder
@@ -115,9 +132,9 @@ export async function createAdventureSession(worldPayload, { restoredPayload = n
   // when the command didn't move anyone) — the manual-play half of the
   // merged exposure set.
   const turnSession = createTurnSession({
-    memoryDir, graph, lexicon, sessionId,
+    memoryDir, graph: codeGraph, lexicon, sessionId,
     vocabHint: 'Try a world question ("where is the key"), or teach me: "remember: the moat is a ditch".',
-    buildExtraOptions: () => ({ uiContext: "browser", planState: planHolder.state }),
+    buildExtraOptions: () => ({ planState: planHolder.state }),
     captureExtraState: async (result) => {
       if ("planState" in result) planHolder.state = result.planState;
       const here = foldWorldState(worldActionRows(readFactRows(await loadMemory(memoryDir)))).placements.get("player")?.object ?? null;
@@ -127,6 +144,9 @@ export async function createAdventureSession(worldPayload, { restoredPayload = n
 
   return {
     memoryDir,
+    codeGraph,
+    get graph() { return memoryGraph; },
+    refreshGraph,
 
     /** One auto-play tick: infer the goal, execute exactly one move through
      *  adventureTurn (adventure-autoplay.mjs's own contract), thread the
@@ -192,25 +212,26 @@ export async function createAdventureSession(worldPayload, { restoredPayload = n
   };
 }
 
-// Re-exported so the page's own rendering script (adventure-viz.mjs) never
-// has to duplicate sprite resolution, the digest reader, the room
-// affordances the chat dock's own pills read from, or (foldWorldState,
-// exposedFacts) the exposure-filtered fold the goal-status panel mirrors —
-// the same posture spider-fly-browser-entry.mjs's own
-// globalThis.tmctSpiderFly re-export takes. `relatedForTerm`/
-// `classAncestorChain` back the edit mode's own cursor-suggestion pills
-// (adventure-viz.mjs's suggestionsForTerm mirrors this same pairing against
-// the global, the same reach-through-the-global pattern captionFor/pillsFor
-// already use for their own adventure.mjs calls). `directedGridLayout`/
-// `roomGraphSvg` (viz-room-graph.mjs's shared BFS-grid room-map layout and
-// SVG renderer) back the manor-map panel, its lightbox and its edit-mode
-// whole-map twin the same way — neither is `.toString()`-splice-safe
-// (roomGraphSvg needs escapeHtml, directedGridLayout needs its own
-// module-level exit-delta table), so the page reaches them here instead of
-// re-implementing the layout a second time.
-globalThis.tmctAdventure = {
-  createAdventureSession, resolveSpriteForClass, SPRITE_REGISTRY, resolveSpriteAsset,
-  worldDigestRows, roomAffordances, foldWorldState, exposedFacts,
-  relatedForTerm, classAncestorChain, openPersistedStore,
-  directedGridLayout, roomGraphSvg,
-};
+// `tmct.page` keeps what the page draws with and the engine has no
+// plain-English form for: sprite resolution, the digest reader, the room
+// affordances the chat pills read from, the exposure-filtered fold the
+// goal-status panel mirrors, the SKOS neighbourhood and is-a chain behind the
+// edit mode's cursor pills, the persisted-store wrapper, and the manor map's
+// own BFS-grid layout and SVG renderer (neither is `.toString()`-splice-safe:
+// roomGraphSvg needs escapeHtml, directedGridLayout its own exit-delta table).
+publishTmctSurface({
+  open: createAdventureSession,
+  // The memory projection is rebuilt first, so a direct tmct.ask() sees every
+  // fact taught or played into this world since the last one.
+  ask: async (request, options, session) => {
+    await session.refreshGraph();
+    return graphAsk(request, options, session);
+  },
+  plan: enginePlan,
+  page: {
+    resolveSpriteForClass, SPRITE_REGISTRY, resolveSpriteAsset,
+    worldDigestRows, roomAffordances, foldWorldState, exposedFacts,
+    relatedForTerm, classAncestorChain, openPersistedStore,
+    directedGridLayout, roomGraphSvg,
+  },
+});

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

@@ -30,6 +30,7 @@ import { vocabExampleHint } from "../../services/chat.mjs";
 import { createInMemoryStore, normFactTerm, loadMemory, readFactRows, applySeedPayload } from "../../adapters/memory/core.mjs";
 import { splitSentencesPreservingPaths } from "../../services/sentences.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
+import { memoryFactGraphPayload } from "../../domain/memory-facts.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import { registerWinkModel } from "../../adapters/wink-model.mjs";
 import { setDigestStructures } from "../../adapters/corpus/digest-bank.mjs";
@@ -51,6 +52,8 @@ import { registerLiveReferenceProvider, registerResearchProvider } from "../../a
 // decides when to save/load/clear; this entry only carries the wrapper
 // across the bundle boundary.
 import { openPersistedStore } from "./idb-persist.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
 
 /**
  * A browser chat session over the real turn engine.
@@ -70,9 +73,14 @@ import { openPersistedStore } from "./idb-persist.mjs";
  * is module-scope, last write wins, and every session created after this one
  * shares it.
  *
- * Returns { memoryDir, sessionId, turn }. `turn(line)` resolves to
- * { answer, end, record, plan } and threads focus/last/planState between
- * calls exactly as the CLI session does.
+ * Returns { memoryDir, sessionId, graph, codeGraph, refreshGraph, turn }.
+ * `turn(line)` resolves to { answer, end, record, plan } and threads
+ * focus/last/planState between calls exactly as the CLI session does.
+ *
+ * The two graphs are separate on purpose. `codeGraph` is the known-empty index
+ * the turn engine reads, and `graph` is this session's memory store projected
+ * for `ask()` — a question about taught facts has a real graph to traverse
+ * while a code-structure question keeps its honest no-code-graph refusal.
  */
 export function createChatSession({ seedPayload = null, vocabSeeded = false, liveReference = false, onLiveLookup = null, synthesisBudget = 12, digestStructures = null } = {}) {
   setDigestStructures(digestStructures || []);
@@ -80,10 +88,24 @@ export function createChatSession({ seedPayload = null, vocabSeeded = false, liv
   applySeedPayload(memoryDir, seedPayload);
 
   // 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.
-  const graph = parseEntities({ individuals: [], objectProperties: [] });
+  // no-code-graph answer an un-pointed CLI session gives, never a crash. The
+  // turn engine keeps reading THIS one, so the identity-led greeting, the teach
+  // pointer and the zero module counts a page earns from an empty index all
+  // stay exactly as they were.
+  const codeGraph = parseEntities({ individuals: [], objectProperties: [] });
+
+  // What `tmct.ask()` traverses is a different graph: this session's own memory
+  // store, projected through memoryFactGraphPayload. Rebuilt on demand rather
+  // than once at open, because every teach, ingest and research turn grows the
+  // store — the same reason spider-fly rebuilds its board before each turn.
+  let memoryGraph = parseEntities({ individuals: [], objectProperties: [] });
+  async function refreshGraph() {
+    memoryGraph = parseEntities(memoryFactGraphPayload(readFactRows(await loadMemory(memoryDir))));
+    return memoryGraph;
+  }
+
   const lexicon = loadLexicon();
-  const vocabHint = vocabExampleHint(vocabSeeded);
+  const vocabHint = vocabExampleHint(vocabSeeded, "browser");
   const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
 
   // Four-state, like the CLI: false (off), true (rescue on a miss),
@@ -97,10 +119,10 @@ export function createChatSession({ seedPayload = null, vocabSeeded = false, liv
   let synthesisBudgetOn = Number.isFinite(synthesisBudget) ? synthesisBudget : 12;
 
   const session = createTurnSession({
-    memoryDir, graph, lexicon, sessionId, vocabHint,
+    memoryDir, graph: codeGraph, lexicon, sessionId, vocabHint,
     buildExtraOptions: () => ({
       liveReference: liveReferenceOn, onLiveLookup,
-      uiContext: "browser", synthesisBudget: synthesisBudgetOn,
+      synthesisBudget: synthesisBudgetOn,
     }),
     // `result.liveReference` mirrors a `/wiki on|off|supplement|always`
     // command back into this session's own toggle state.
@@ -112,6 +134,9 @@ export function createChatSession({ seedPayload = null, vocabSeeded = false, liv
   return {
     memoryDir,
     sessionId,
+    get graph() { return memoryGraph; },
+    codeGraph,
+    refreshGraph,
     get liveReference() { return liveReferenceOn; },
     /** The page's toggle seam: set the live Wikipedia mode for every later turn
      *  (the `/wiki on|off|supplement|always` command sets the same state). */
@@ -144,4 +169,25 @@ export async function researchedFactRows(memoryDir) {
     .map((row) => ({ subject: row.subject, predicate: row.predicate, object: row.object }));
 }
 
-globalThis.tmctChat = { createChatSession, registerWinkModel, registerReferencePackProvider, registerLiveReferenceProvider, registerResearchProvider, normFactTerm, vocabExampleHint, memoryStats, openPersistedStore, exportFactsJsonl, researchedFactRows, splitSentences: splitSentencesPreservingPaths };
+// The page reaches the engine through the one shared surface: `tmct.open()`
+// opens this session, `tmct.turn()` runs the dock, `tmct.ask()` puts a
+// question to the session's own graph. What stays on `tmct.page` is what has
+// no plain-English form — the vendor/provider seams the page registers before
+// the first turn, its IndexedDB wrapper, and the two serializers its export
+// and paste-ingest controls run.
+publishTmctSurface({
+  open: createChatSession,
+  // The memory projection is rebuilt first, so a direct tmct.ask() sees every
+  // fact taught, pasted or researched since the last one.
+  ask: async (request, options, session) => {
+    await session.refreshGraph();
+    return graphAsk(request, options, session);
+  },
+  plan: enginePlan,
+  page: {
+    registerWinkModel, registerReferencePackProvider, registerLiveReferenceProvider,
+    registerResearchProvider, normFactTerm, vocabExampleHint, memoryStats,
+    openPersistedStore, exportFactsJsonl, researchedFactRows,
+    splitSentences: splitSentencesPreservingPaths,
+  },
+});

package/src/surfaces/web/code-explorer-browser-entry.mjs

@@ -22,6 +22,8 @@ import * as source from "../../adapters/source.mjs";
 import { computeCodeExplorerData, computeCodeLedger, edgePhrase } from "../../services/code-explorer-viz.mjs";
 import { generateCodeHints } from "../../domain/code-explorer-hints.mjs";
 import { createTurnSession } from "./turn-session.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
 import { tmct_ask } from "../../tools/handlers/tmct-ask.mjs";
 import { RELATIONS } from "../../domain/ask-vocab.mjs";
 
@@ -37,7 +39,7 @@ import { RELATIONS } from "../../domain/ask-vocab.mjs";
  * payload carries the starter vocabulary. Teaches land in the same in-memory
  * store, so a taught fact never touches disk.
  *
- * Returns { memoryDir, sessionId, turn }, the createChatSession shape the
+ * Returns { memoryDir, sessionId, graph, turn }, the createChatSession shape the
  * page's chat expects.
  */
 export function createCodeExplorerSession({ graphPayload, seedPayload = null, vocabSeeded = false } = {}) {
@@ -51,7 +53,7 @@ export function createCodeExplorerSession({ graphPayload, seedPayload = null, vo
   // the write path recounts — teach turns must work on any seed.
   if (seedPayload) memoryDir.payload = { ...memoryDir.payload, ...seedPayload };
   const lexicon = loadLexicon();
-  const vocabHint = vocabExampleHint(vocabSeeded);
+  const vocabHint = vocabExampleHint(vocabSeeded, "browser");
   const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
   // A stable virtual path: the provider answers every fetch, so no file is
   // ever read, but the code lanes still do path math (join/dirname) on it.
@@ -69,6 +71,7 @@ export function createCodeExplorerSession({ graphPayload, seedPayload = null, vo
   return {
     memoryDir,
     sessionId,
+    graph,
     turn: turnSession.turn,
   };
 }
@@ -223,17 +226,28 @@ export function askRelatedFacts(graphPayload, term) {
   return { term, rows, asked, grounded };
 }
 
-// Exposed for the page's inline client: the re-derivation helpers so a graph
-// swapped through the desktop picker re-renders without duplicating logic, the
-// engine's own answer to "what relates to the focus", plus the wink loader hook
-// registerWinkModel and normFactTerm the chat shares with the ledger page.
-globalThis.tmctCodeExplorer = {
-  createCodeExplorerSession,
-  askRelatedFacts,
-  computeCodeExplorerData,
-  computeCodeLedger,
-  generateCodeHints,
-  parseEntities,
-  normFactTerm,
-  registerWinkModel,
-};
+// This page holds a REAL code graph, so `tmct.ask` is the engine answering
+// over it — the same round trip askRelatedFacts already makes twice per
+// relation kind to build the sidebar's rows.
+//
+// `tmct.page` keeps the re-derivation helpers a graph swapped through the
+// desktop picker re-renders with, plus the wink and term-normalizing seams the
+// chat shares with the ledger page. `createCodeExplorerSession` sits there
+// too: the page keeps its own session slot, created lazily on the first turn
+// once the general-knowledge seed has landed, rather than the one `tmct.open`
+// would install eagerly — so it calls the factory straight from the bag.
+publishTmctSurface({
+  open: createCodeExplorerSession,
+  ask: graphAsk,
+  plan: enginePlan,
+  page: {
+    createCodeExplorerSession,
+    askRelatedFacts,
+    computeCodeExplorerData,
+    computeCodeLedger,
+    generateCodeHints,
+    parseEntities,
+    normFactTerm,
+    registerWinkModel,
+  },
+});

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

@@ -0,0 +1,82 @@
+// engine-surface.mjs — the standard `ask` and `plan` routes a browser page
+// wires into publishTmctSurface (tmct-surface.mjs).
+//
+// Both run the SAME machinery the CLI runs, over the session's own in-memory
+// state rather than a repo on disk: `graphAsk` dispatches `tmct_ask` through
+// the tool layer and hands back the structured envelope beside the prose
+// (dispatchToolStructured's `{ content, data }`); `enginePlan` builds the
+// capability planner's context from whatever the session holds and runs one
+// request through it.
+//
+// Kept out of tmct-surface.mjs on purpose. That module is pure wiring and
+// imports nothing, so memory-ask-browser-entry.mjs — the one bundle that is
+// committed and published, and is deliberately small — can publish the same
+// `globalThis.tmct` without pulling the tool layer and the router into its
+// bundle.
+import { dispatchToolStructured } from "../../tools/server.mjs";
+import { capabilityPlanDeps, noCodeGraph } from "../../services/chat.mjs";
+
+/**
+ * One plain-English question, answered against the graph this session holds,
+ * through the same `tmct_ask` tool the CLI dispatches. Returns
+ * `{ answer, data, miss }` — `data` is ask()'s own envelope (the parse, the
+ * matches it found, the traversal it walked), which is what a panel renders
+ * rows from and what makes an answer auditable.
+ *
+ * A session whose graph is empty answers with an honest miss. That is the real
+ * state of a memory-only page: its rows are facts in a store, and ask() reads
+ * a graph. spider-fly is the page that closed that gap for its own world, by
+ * projecting its live board into a graph (worldRelationGraphPayload) before
+ * every turn — the same route is open to any page whose rows have a shape
+ * worth asking over.
+ */
+export async function graphAsk(request, options, session) {
+  const { content, data } = await dispatchToolStructured("tmct_ask", { query: request }, {
+    graph: session.graph,
+    memoryBackend: session.memoryDir,
+  });
+  return { answer: content, data, miss: Boolean(data?.miss) };
+}
+
+/**
+ * One compound or maintenance-goal request, planned and executed over whatever
+ * this session holds — the same capability router `/plan` reaches, with the
+ * same memory-only mode a page with no code graph needs (a code-graph
+ * capability there refuses by naming the graph it hasn't got).
+ *
+ * Returns the planner's own result: `{ refused, why, driver, calls, composed,
+ * observed }`. No prose is composed here — a page that wants the written
+ * answer asks for it in words through `tmct.turn("/plan …")`, which is the
+ * same split `dispatchTool` and `dispatchToolStructured` already draw.
+ */
+export async function enginePlan(request, options, session) {
+  const graph = session.graph && !noCodeGraph(session.graph) ? session.graph : null;
+  const memoryDir = session.memoryDir ?? null;
+  if (!graph && !memoryDir) {
+    return {
+      refused: true,
+      why: "nothing to plan over — this session holds neither a code graph nor a memory store",
+      driver: null, calls: [], composed: null, observed: null,
+    };
+  }
+  const { buildCapabilityPlanCtx, runCapabilityPlan, declaredCapabilityNames } =
+    await import("../../domain/router/drive.mjs");
+  const ctx = await buildCapabilityPlanCtx({
+    ...capabilityPlanDeps(), config: null, source: null, graph, memoryDir,
+  });
+  try {
+    const result = await runCapabilityPlan(request, declaredCapabilityNames(), ctx);
+    return {
+      refused: Boolean(result.refused),
+      why: Array.isArray(result.why) ? result.why.join("; ") : (result.why ?? null),
+      driver: result.driver ?? null,
+      calls: result.calls ?? [],
+      composed: result.composed ?? null,
+      observed: result.observed ?? null,
+    };
+  } finally {
+    // The taught registrations are per-ctx: dispose them so the next call
+    // re-reads the store instead of meeting a stale name collision.
+    for (const dispose of ctx.disposers || []) dispose();
+  }
+}

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

@@ -29,15 +29,24 @@ import { splitSentencesPreservingPaths, stripCitationResidue } from "../../servi
 import { clauseCandidates, optimisticTriples } from "../../services/extract-facts.mjs";
 import { touchedFactRows } from "../../domain/memory/touched-facts.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
+import { parseEntities } from "../../domain/codegraph.mjs";
+import { ingestFactGraphPayload, ingestedFactRows } from "../../domain/ingest-facts.mjs";
 import { registerWinkModel, winkInstance } from "../../adapters/wink-model.mjs";
 import { memoryStats, exportFactsJsonl } from "./memory-stats.mjs";
 import { openPersistedStore } from "./idb-persist.mjs";
+import { createTurnSession } from "./turn-session.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
 
 // The pronoun subjects a bounded carry substitutes with the last unique
 // grounded subject in the SAME paragraph. Reset at every blank line, so a
 // fresh paragraph never resolves against a stale antecedent.
 const PRONOUN_LEAD_RE = /^(?:they|it|these|those|this)\b\s*/i;
 
+// The turn kinds that move the fact store, so the projected graph a later
+// question traverses has to be rebuilt before it answers.
+const STORE_WRITING_TURNS = new Set(["assert", "retract"]);
+
 /**
  * The single recognizer seam. Splits `text` into paragraphs (blank-line
  * separated, so the pronoun carry never bridges a topic break) and each
@@ -170,29 +179,90 @@ export async function groundTextToFacts(text, { memoryDir, sessionId, lexicon, v
  * the page can then export. `seedPayload` (optional) pre-loads a graph the
  * recognizer can recall and link against.
  *
- * Returns { memoryDir, sessionId, ingest }. `ingest(text, { onFact,
- * optimistic })` is the one call the page makes; it drives groundTextToFacts
- * against this session's store and returns its { sentences, recognized,
- * skipped, facts } summary.
+ * Returns { memoryDir, sessionId, graph, refreshGraph, askableClasses, ingest,
+ * turn }. `ingest(text, { onFact, optimistic })` is the call the ingest panes
+ * make; it drives groundTextToFacts against this session's store and returns
+ * its { sentences, recognized, skipped, facts } summary. `turn(line)` is the
+ * ask dock's own entry point — the FULL chat turn engine (the exact dispatch
+ * the CLI runs) over the same store, so a question it can't ground gets the
+ * same refusal the CLI gives.
+ *
+ * `graph` is what a question actually traverses: the ingested rows projected
+ * through ingest-facts.mjs, rebuilt by `refreshGraph()` whenever the store has
+ * moved since the last one. The rebuild is gated on a dirty flag rather than
+ * run per call because a seeded store holds tens of thousands of rows, and
+ * re-reading all of them to answer a second question about the same two
+ * sentences is the one cost this page has to avoid.
  */
 export function createIngestSession({ seedPayload = null, vocabSeeded = false } = {}) {
   const memoryDir = createInMemoryStore();
   applySeedPayload(memoryDir, seedPayload);
 
   const lexicon = loadLexicon();
-  const vocabHint = vocabExampleHint(vocabSeeded);
+  const vocabHint = vocabExampleHint(vocabSeeded, "browser");
   const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
 
+  let graph = parseEntities({ individuals: [], objectProperties: [] });
+  let storeMovedSinceGraph = true;
+  async function refreshGraph() {
+    if (!storeMovedSinceGraph) return graph;
+    const rows = ingestedFactRows(readFactRows(await loadMemory(memoryDir)));
+    graph = parseEntities(ingestFactGraphPayload(rows));
+    storeMovedSinceGraph = false;
+    return graph;
+  }
+
+  // An empty graph is not the same as no graph to runTurn: a non-null one
+  // makes it read an ordinary "the number of X" phrase as a graph count query
+  // instead of running the teach cascade, so before anything is ingested the
+  // dock keeps the plain conversational reading.
+  const graphForTurn = () => (graph.individuals.length ? graph : null);
+
+  const turnSession = createTurnSession({
+    memoryDir, lexicon, sessionId, vocabHint,
+    buildExtraOptions: () => ({ graph: graphForTurn() }),
+    captureExtraState: (result) => {
+      if (STORE_WRITING_TURNS.has(result?.record?.via) && !result.record.miss) storeMovedSinceGraph = true;
+    },
+  });
+
   return {
     memoryDir,
     sessionId,
-    ingest(text, { onFact = null, optimistic = false } = {}) {
-      return groundTextToFacts(text, { memoryDir, sessionId, lexicon, vocabHint, onFact, optimistic });
+    get graph() { return graph; },
+    refreshGraph,
+    /** The class nouns this graph can actually list, for a page building its
+     *  own "try asking" hint out of real data rather than invented examples. */
+    askableClasses() {
+      return [...new Set(graph.individuals.map((i) => i.class).filter(Boolean))].sort();
+    },
+    async ingest(text, { onFact = null, optimistic = false } = {}) {
+      const summary = await groundTextToFacts(text, { memoryDir, sessionId, lexicon, vocabHint, onFact, optimistic });
+      if (summary.recognized) storeMovedSinceGraph = true;
+      return summary;
+    },
+    async turn(line) {
+      await refreshGraph();
+      return turnSession.turn(line);
     },
   };
 }
 
-globalThis.tmctIngest = {
-  createIngestSession, groundTextToFacts, exportFactsJsonl, registerWinkModel, normFactTerm,
-  memoryStats, openPersistedStore,
-};
+// The page's own two calls are `tmct.session.ingest(text)` and, from the ask
+// dock, `tmct.turn(line)`. `tmct.ask` puts one question straight to the graph
+// this session projects from what it has ingested, rebuilding it first so a
+// fact grounded a moment ago is already visible. `tmct.page` keeps the
+// recognizer entry point the page also drives directly, the wink seam, the
+// stats fold behind its counters, its IndexedDB wrapper and its JSONL export.
+publishTmctSurface({
+  open: createIngestSession,
+  ask: async (request, options, session) => {
+    await session.refreshGraph();
+    return graphAsk(request, options, session);
+  },
+  plan: enginePlan,
+  page: {
+    groundTextToFacts, exportFactsJsonl, registerWinkModel, normFactTerm,
+    memoryStats, openPersistedStore,
+  },
+});

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

@@ -17,9 +17,10 @@
 // never published — only the hosted demo site's public/ledger.html links to
 // it, as an optional sibling script the page degrades honestly without.
 import { vocabExampleHint } from "../../services/chat.mjs";
-import { createInMemoryStore, normFactTerm, applySeedPayload } from "../../adapters/memory/core.mjs";
+import { createInMemoryStore, normFactTerm, applySeedPayload, loadMemory, readFactRows } from "../../adapters/memory/core.mjs";
 import { splitSentencesPreservingPaths } from "../../services/sentences.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
+import { memoryFactGraphPayload } from "../../domain/memory-facts.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import { registerWinkModel } from "../../adapters/wink-model.mjs";
 import { registerResearchProvider } from "../../adapters/corpus/wikipedia-live.mjs";
@@ -27,6 +28,8 @@ import { computeLedgerDataFromPayload } from "../../services/ledger-viz.mjs";
 import { digestTermFromPayloadBrowser } from "./digest-client.mjs";
 import { createTurnSession } from "./turn-session.mjs";
 import { exportFactsJsonl } from "./memory-stats.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
 
 /**
  * A browser ledger-dock session over the real turn engine — createChatSession's
@@ -35,7 +38,12 @@ import { exportFactsJsonl } from "./memory-stats.mjs";
  * a fact taught through the dock extends the SAME graph the page renders
  * from, never a disconnected one.
  *
- * Returns { memoryDir, sessionId, turn }, identical to createChatSession.
+ * Returns { memoryDir, sessionId, graph, codeGraph, refreshGraph, turn },
+ * identical to createChatSession — including the two-graph split: `codeGraph`
+ * is the known-empty index the turn engine reads, and `graph` is the ledger's
+ * own store projected for `ask()`, so a question about the facts on the page
+ * traverses those facts while a code-structure question still refuses honestly.
+ *
  * ledger-viz.mjs's own inline script calls computeLedgerDataFromPayload
  * (re-exported below) on `memoryDir.payload` after a turn whose record shows
  * a successful write (`via: "assert"` or `via: "retract"`, `miss: false`) to
@@ -46,20 +54,45 @@ export function createLedgerSession({ seedPayload = null, vocabSeeded = false }
   const memoryDir = createInMemoryStore();
   applySeedPayload(memoryDir, seedPayload);
 
-  const graph = parseEntities({ individuals: [], objectProperties: [] });
+  const codeGraph = parseEntities({ individuals: [], objectProperties: [] });
+
+  let memoryGraph = parseEntities({ individuals: [], objectProperties: [] });
+  async function refreshGraph() {
+    memoryGraph = parseEntities(memoryFactGraphPayload(readFactRows(await loadMemory(memoryDir))));
+    return memoryGraph;
+  }
+
   const lexicon = loadLexicon();
-  const vocabHint = vocabExampleHint(vocabSeeded);
+  const vocabHint = vocabExampleHint(vocabSeeded, "browser");
   const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
 
-  const session = createTurnSession({ memoryDir, graph, lexicon, sessionId, vocabHint });
-  return { memoryDir, sessionId, turn: session.turn };
+  const session = createTurnSession({ memoryDir, graph: codeGraph, lexicon, sessionId, vocabHint });
+  return {
+    memoryDir,
+    sessionId,
+    get graph() { return memoryGraph; },
+    codeGraph,
+    refreshGraph,
+    turn: session.turn,
+  };
 }
 
-// Re-exported so ledger-viz.mjs's own inline script never has to duplicate
-// the derivation logic that builds rows/terms/edges/contradictions/
-// worthALook/stats from a payload — the same posture chat-browser-entry.mjs
-// takes re-exporting registerWinkModel for its own page's CDN wink load.
-// splitSentences + exportFactsJsonl carry the dock's paste-and-drop ingest and
-// its JSONL export across the bundle boundary, the same one-serializer posture
-// chat-browser-entry.mjs holds for its own page.
-globalThis.tmctLedger = { createLedgerSession, computeLedgerDataFromPayload, normFactTerm, registerWinkModel, registerResearchProvider, splitSentences: splitSentencesPreservingPaths, exportFactsJsonl, digestTermFromPayloadBrowser };
+// `tmct.page` keeps what the page's own script renders with and the engine has
+// no plain-English form for: the payload-to-rows/terms/edges/stats derivation
+// the ledger view re-mounts from after a successful teach, the digest reader,
+// the wink and research seams, and the two serializers behind the dock's
+// paste-ingest and JSONL export.
+publishTmctSurface({
+  open: createLedgerSession,
+  // The memory projection is rebuilt first, so a direct tmct.ask() sees every
+  // fact the dock or the ingest panel has taught since the last one.
+  ask: async (request, options, session) => {
+    await session.refreshGraph();
+    return graphAsk(request, options, session);
+  },
+  plan: enginePlan,
+  page: {
+    computeLedgerDataFromPayload, normFactTerm, registerWinkModel, registerResearchProvider,
+    splitSentences: splitSentencesPreservingPaths, exportFactsJsonl, digestTermFromPayloadBrowser,
+  },
+});