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

package/src/surfaces/web/memory-stats.mjs

@@ -4,6 +4,7 @@
 // store shape.
 import { loadMemory, readFactRows } from "../../adapters/memory/core.mjs";
 import { provenanceTagToSource } from "../../domain/memory/trust.mjs";
+import { serializeFactsJsonl } from "../../adapters/memory/export-jsonl.mjs";
 
 /**
  * The memory a running session holds, broken down by where each fact came
@@ -51,3 +52,13 @@ export async function memoryStats(memoryDir) {
   }
   return { total: rows.length, bandCounts, taught };
 }
+
+/**
+ * The session's whole triple store as JSONL — one
+ * { subject, predicate, object, provenance } object per line, the same shape
+ * `tmct extract` and `tmct memory --export` emit. Reads the live memory the
+ * same way memoryStats does; a page offers this as a download.
+ */
+export async function exportFactsJsonl(memoryDir) {
+  return serializeFactsJsonl(await loadMemory(memoryDir));
+}

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

@@ -28,7 +28,6 @@
 // auto-playing at once — this file makes no ordering promise between two
 // concurrent calls into the same memoryDir, the same way two callers writing
 // into any shared store concurrently would need their own queue.
-import { runTurn } from "../../services/chat.mjs";
 import {
   createInMemoryStore, appendFacts, appendRule, loadMemory, readFactRows, removeFacts,
 } from "../../adapters/memory/core.mjs";
@@ -38,7 +37,7 @@ import {
   foldWorldState, worldActionRows, worldDigestRows, roomAffordances,
   personKnowledgeLines, personKnownFoodLines,
   diggableDirections, castInRoom, displayNameOf, isOutOfPlay, outOfPlayReasonOf, outOfPlayPhrase,
-  roomKindOf, isMudStatePredicate,
+  roomKindOf, isMudStatePredicate, worldEpochFact, snapshotSubject,
 } from "../../services/adventure.mjs";
 import { waveFact, playedByFact, P2P_PREDICATES } from "../../domain/p2p/facts.mjs";
 import { relatedForTerm } from "../../domain/skos-view.mjs";
@@ -48,6 +47,9 @@ import { mudSpeciesOf } from "../../domain/game-config.mjs";
 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,18 +62,23 @@ import { resolveSpriteAsset } from "../../domain/sprite-templates.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, graph, windows, snapshot }`. `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
  *  data source, never a per-window one. */
-export async function createMudSession(worldPayload, { characters = [] } = {}) {
+export async function createMudSession(worldPayload, { characters = [], epoch = 0 } = {}) {
   const memoryDir = createInMemoryStore();
   const tag = worldProvenanceTag(worldPayload.name);
   const seedFacts = worldFactsForCast(worldPayload.facts, characters);
   await appendFacts(memoryDir, seedFacts.map((f) => ({
     subject: f.subject, predicate: f.predicate, object: f.object, provenance: tag,
   })));
+  // A recast opens the same deterministic ids over a fresh store while peers
+  // may still hold the old run's snapshots. The epoch marker is what makes
+  // every fold — local and merged — treat this seed as the newer state. An
+  // unrecast boot writes nothing, so a solo session's store is unchanged.
+  if (epoch > 0) await appendFacts(memoryDir, [{ ...worldEpochFact(epoch), provenance: tag }]);
   for (const rule of worldPayload.rules) {
     await appendRule(memoryDir, { name: rule.name, kind: rule.ruleKind, slots: rule.slots, provenance: tag });
   }
@@ -105,9 +112,10 @@ export async function createMudSession(worldPayload, { characters = [] } = {}) {
     // "it"/"there" belongs to that window's own conversation, and its own
     // discovered-room history is the real fog of war this page promises —
     // sharing either across characters would leak one window's state into
-    // another's.
-    let focus = null;
-    let last = null;
+    // another's. createTurnSession owns focus/last for us; planState is the
+    // one piece that is NOT per-character (see planHolder above), so it is
+    // threaded through buildExtraOptions/captureExtraState instead of living
+    // in the session's own internal slot.
     const visitedRoomIds = new Set();
     // This character's OWN turns, not the page's shared tick counter: two
     // windows playing at different speeds, or one paused while the other
@@ -117,6 +125,20 @@ export async function createMudSession(worldPayload, { characters = [] } = {}) {
     const startRoom = await roomOf(character);
     if (startRoom) visitedRoomIds.add(startRoom);
 
+    const turnSession = createTurnSession({
+      memoryDir, graph, 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,
+      }),
+      captureExtraState: async (result, state) => {
+        if ("planState" in result) planHolder.state = state.planState;
+        turnsTaken += 1;
+        const here = await roomOf(character);
+        if (here) visitedRoomIds.add(here);
+      },
+    });
+
     windows[character] = {
       character,
 
@@ -125,27 +147,7 @@ export async function createMudSession(worldPayload, { characters = [] } = {}) {
        *  character via actingSubject. A throwing runTurn must never end the
        *  session; this window has no other chance to show this turn's
        *  answer. */
-      async turn(line) {
-        let result;
-        try {
-          result = await runTurn(line, {
-            config: null, source: null, graph, focus, last, memoryDir,
-            sessionId: character, env: {}, lexicon, uiContext: "browser",
-            actingSubject: character, planState: planHolder.state,
-            vocabHint: 'Try a world command ("dig north", "eat the carrot-1"), or ask "what food do you know about".',
-          });
-        } catch (e) {
-          const message = e instanceof Error ? e.message : String(e);
-          return { answer: `Something went wrong answering that (${message}). Try rephrasing.`, end: false };
-        }
-        focus = result.focus;
-        last = result.last;
-        if ("planState" in result) planHolder.state = result.planState;
-        turnsTaken += 1;
-        const here = await roomOf(character);
-        if (here) visitedRoomIds.add(here);
-        return { answer: result.answer, end: Boolean(result.end) };
-      },
+      turn: turnSession.turn,
 
       /** One whole scripted turn (mud-turn.mjs's runMudTurn): investigate,
        *  walk toward known food, or roll at the edge (dig). `k` is the turn
@@ -221,7 +223,7 @@ export async function createMudSession(worldPayload, { characters = [] } = {}) {
     const editTurn = state.turnCount + 1;
     if (toAppend.length) {
       await appendFacts(memoryDir, toAppend.map((f) => ({
-        subject: f.kind === "other" ? f.subject : `${f.subject}@turn${editTurn}`,
+        subject: f.kind === "other" ? f.subject : snapshotSubject(f.subject, editTurn, state.epoch),
         predicate: f.predicate,
         object: f.object,
         provenance: f.kind === "other" ? tag : `${tag}:turn${editTurn}`,
@@ -270,7 +272,7 @@ export async function createMudSession(worldPayload, { characters = [] } = {}) {
     return claims.length;
   }
 
-  return { memoryDir, windows, snapshot, applyEdit, wave, claimCharacters };
+  return { memoryDir, graph, windows, snapshot, applyEdit, wave, claimCharacters };
 }
 
 /** `count` entries drawn at random from `roster`, in random order, without
@@ -351,22 +353,41 @@ 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);
+  },
+  ask: graphAsk,
+  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/plan-browser-entry.mjs

@@ -24,7 +24,6 @@
 // engine. `maxDepth` is overridable PER CALL (not just at session creation)
 // so the page's own max-search-depth control can re-run "solve it" on the
 // CURRENT board without tearing down and re-teaching the whole puzzle.
-import { runTurn } from "../../services/chat.mjs";
 import { createInMemoryStore } from "../../adapters/memory/core.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
@@ -32,9 +31,10 @@ import { DEFAULT_GAME_CONFIG } from "../../domain/game-config.mjs";
 import { hanoiLessonSentences } from "../../domain/hanoi-lesson.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 +44,12 @@ import { planToPddl } from "../../services/plan-pddl.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
@@ -57,58 +59,45 @@ export async function createPlanSession({ diskCount = 3, maxDepth = DEFAULT_GAME
   const graph = parseEntities({ individuals: [], objectProperties: [] });
   const lexicon = loadLexicon();
   const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
-  const planHolder = { state: null };
-  let focus = null;
-  let last = null;
 
-  /** One dispatched chat turn — the SAME runTurn the CLI and every other
-   *  viz page's own chat dock run, over this session's own memoryDir. A
-   *  throwing runTurn must never kill the session — the page has no other
-   *  chance to show this turn's answer. `maxDepth` overrides the session's
-   *  own default for just this one call (the page's own max-search-depth
-   *  control threads it on every call, including a plain typed "solve
-   *  it"), so raising or lowering it never requires re-teaching the board.
-   *  A returned `plan` carries `becauseText` folded in from the session's
-   *  own plan slot — the plan-lane contract's returned object never carries
-   *  it itself (only planHolder.state does), and the PDDL panel's own
-   *  "because —" line needs it. */
-  async function turn(line, { maxDepth: maxDepthOverride } = {}) {
-    const gameConfig = {
-      ...DEFAULT_GAME_CONFIG,
-      planning: { ...DEFAULT_GAME_CONFIG.planning, maxDepth: maxDepthOverride ?? maxDepth },
-    };
-    let result;
-    try {
-      result = await runTurn(line, {
-        config: null, source: null, graph, focus, last, memoryDir, sessionId,
-        env: {}, lexicon, vocabHint: "", planState: planHolder.state, gameConfig,
-      });
-    } catch (e) {
-      const message = e instanceof Error ? e.message : String(e);
-      return { answer: `Something went wrong answering that (${message}). Try rephrasing, or /help.`, end: false, record: null, plan: null };
-    }
-    focus = result.focus;
-    last = result.last;
-    if ("planState" in result) planHolder.state = result.planState;
-    const plan = result.plan
-      ? { ...result.plan, becauseText: planHolder.state?.becauseText ?? null }
-      : null;
-    return { answer: result.answer, end: Boolean(result.end), record: result.record ?? null, plan };
-  }
+  // `maxDepth` overrides the session's own default for just this one call
+  // (the page's own max-search-depth control threads it on every call,
+  // including a plain typed "solve it"), so raising or lowering it never
+  // requires re-teaching the board. `captureExtraState` folds `becauseText`
+  // onto the returned `plan` from the session's own plan slot — the
+  // plan-lane contract's returned object never carries it itself (only
+  // planState does), and the PDDL panel's own "because —" line needs it.
+  const session = createTurnSession({
+    memoryDir, graph, lexicon, sessionId, vocabHint: "",
+    buildExtraOptions: (state, callArgs) => ({
+      gameConfig: {
+        ...DEFAULT_GAME_CONFIG,
+        planning: { ...DEFAULT_GAME_CONFIG.planning, maxDepth: callArgs?.maxDepth ?? maxDepth },
+      },
+    }),
+    captureExtraState: (result, state) => {
+      if (result.plan) result.plan = { ...result.plan, becauseText: state.planState?.becauseText ?? null };
+    },
+  });
 
   let plan = null;
   for (const sentence of hanoiLessonSentences(diskCount)) {
-    const r = await turn(sentence);
+    const r = await session.turn(sentence);
     if (r.plan) plan = r.plan;
   }
 
-  return { memoryDir, sessionId, diskCount, maxDepth, plan, turn };
+  return { memoryDir, sessionId, graph, diskCount, maxDepth, plan, turn: session.turn };
 }
 
-// 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.
+publishTmctSurface({
+  open: createPlanSession,
+  ask: graphAsk,
+  plan: enginePlan,
+  page: { computeBlocksLayout, planToPageData, renderInputsFromPlan, planToPddl, registerWinkModel },
+});

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

@@ -26,10 +26,9 @@
 // Gitignored, Pages-demo-site-only output — scripts/build-demo-site.mjs builds
 // it fresh on every deploy, never committed, the same posture the chat/ingest
 // bundles document for their own output.
-import { runTurn, vocabExampleHint, factAnswer, factReadBack } from "../../services/chat.mjs";
+import { vocabExampleHint, factAnswer, factReadBack } from "../../services/chat.mjs";
 import { clampResearchConfig } from "../../services/research.mjs";
-import { createInMemoryStore, normFactTerm, loadMemory, readFactRows, removeFacts } from "../../adapters/memory/core.mjs";
-import { serializeFactsJsonl } from "../../adapters/memory/export-jsonl.mjs";
+import { createInMemoryStore, normFactTerm, loadMemory, readFactRows, removeFacts, applySeedPayload } from "../../adapters/memory/core.mjs";
 import { provenanceTagToSource } from "../../domain/memory/trust.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
@@ -39,6 +38,10 @@ import { registerLiveReferenceProvider, registerResearchProvider } from "../../a
 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
@@ -205,22 +208,16 @@ export async function researchSnapshot(memoryDir, sessionIds = {}, { recentCap =
  */
 export function createResearchSession({ seedPayload = null, vocabSeeded = false, liveReference = false, onLiveLookup = null, synthesisBudget = 12, digestStructures = null } = {}) {
   const memoryDir = createInMemoryStore();
-  if (seedPayload) memoryDir.payload = { ...memoryDir.payload, ...seedPayload };
+  applySeedPayload(memoryDir, seedPayload);
 
   const graph = parseEntities({ individuals: [], objectProperties: [] });
   const lexicon = loadLexicon();
   const vocabHint = vocabExampleHint(vocabSeeded);
-  const chatSessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
   // 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.
   const ingestSessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now() + 1);
-  const sessionIds = { chatSessionId, ingestSessionId };
 
-  let focus = null;
-  let last = null;
-  let planState = null;
-  let researchState = null;
   const normLive = (v) => (v === "always" ? "always" : v === "supplement" ? "supplement" : Boolean(v));
   let liveReferenceOn = normLive(liveReference);
   let synthesisBudgetOn = Number.isFinite(synthesisBudget) ? synthesisBudget : 12;
@@ -230,8 +227,29 @@ export function createResearchSession({ seedPayload = null, vocabSeeded = false,
   // (they ride its persisted state), so its queue stays internally consistent.
   let researchConfig = clampResearchConfig();
 
+  // The chat-engine turn (research/teach/ask), threading focus/last/planState/
+  // researchState across calls the way every browser chat dock does. A throw
+  // never kills the session — the page has no other chance to show this
+  // turn's answer.
+  const turnSession = createTurnSession({
+    memoryDir, graph, lexicon, vocabHint,
+    sessionId: globalThis.crypto?.randomUUID?.() ?? String(Date.now()),
+    buildExtraOptions: () => ({
+      researchConfig, liveReference: liveReferenceOn, onLiveLookup,
+      uiContext: "browser", synthesisBudget: synthesisBudgetOn,
+    }),
+    captureExtraState: (result) => {
+      if (typeof result.liveReference === "boolean" || result.liveReference === "supplement" || result.liveReference === "always") {
+        liveReferenceOn = result.liveReference;
+      }
+    },
+  });
+  const chatSessionId = turnSession.sessionId;
+  const sessionIds = { chatSessionId, ingestSessionId };
+
   return {
     memoryDir,
+    graph,
     chatSessionId,
     ingestSessionId,
     sessionIds,
@@ -245,28 +263,7 @@ export function createResearchSession({ seedPayload = null, vocabSeeded = false,
      *  unset keys keep their current value. */
     setResearchConfig(partial) { researchConfig = clampResearchConfig({ ...researchConfig, ...(partial || {}) }); },
 
-    /** One chat-engine turn (research/teach/ask). A throw never kills the
-     *  session — the page has no other chance to show this turn's answer. */
-    async turn(line) {
-      let result;
-      try {
-        result = await runTurn(line, {
-          config: null, source: null, graph, focus, last, memoryDir, sessionId: chatSessionId,
-          env: {}, lexicon, vocabHint, planState, researchState, researchConfig,
-          liveReference: liveReferenceOn, onLiveLookup,
-          uiContext: "browser", synthesisBudget: synthesisBudgetOn,
-        });
-      } catch (e) {
-        const message = e instanceof Error ? e.message : String(e);
-        return { answer: `Something went wrong with that (${message}). Try rephrasing.`, end: false, record: null, plan: null, research: undefined };
-      }
-      focus = result.focus;
-      last = result.last;
-      if ("planState" in result) planState = result.planState;
-      if ("researchState" in result) researchState = result.researchState;
-      if (typeof result.liveReference === "boolean" || result.liveReference === "supplement" || result.liveReference === "always") liveReferenceOn = result.liveReference;
-      return { answer: result.answer, end: Boolean(result.end), record: result.record ?? null, plan: result.plan ?? null, research: result.research };
-    },
+    turn: (line) => turnSession.turn(line),
 
     /** Ingest a document into the SAME store, under the ingest session id so
      *  its facts carry the "ingest" source rather than "taught". */
@@ -333,17 +330,22 @@ export function createResearchSession({ seedPayload = null, vocabSeeded = false,
   };
 }
 
-/**
- * The session's whole triple store as JSONL — the same
- * { subject, predicate, object, provenance } shape `tmct extract` and
- * `tmct memory --export` emit, offered to the page as the canonical download.
- */
-export async function exportFactsJsonl(memoryDir) {
-  return serializeFactsJsonl(await loadMemory(memoryDir));
-}
-
-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,
+  },
+});