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

package/src/services/p2p-room.mjs

@@ -164,6 +164,19 @@ export function createP2pRoom({
   const seenProvenanceById = new Map();
   let cachedRows = [];
 
+  // Store-touching work runs one job at a time, in arrival order. Every path
+  // that reads or writes memoryDir/seenProvenanceById/cachedRows crosses at
+  // least one await, so without this a rebind could swap the store while a
+  // merge is half-written into the old one — the merged rows would then
+  // baseline against the wrong store, or vanish. Jobs queued behind a rebind
+  // land on the store the rebind installed.
+  let storeChain = Promise.resolve();
+  function withStore(job) {
+    const run = storeChain.then(job);
+    storeChain = run.then(() => {}, () => {});
+    return run;
+  }
+
   const factsListeners = new Set();
   const stateListeners = new Set();
   const peersListeners = new Set();
@@ -246,8 +259,8 @@ export function createP2pRoom({
 
   /** Diff the store against what this room last saw, relabel each changed
    *  fact's provenance for the wire, and broadcast the batch. The page calls
-   *  this once after every local turn or action. */
-  async function afterLocalChange() {
+   *  this (as `afterLocalChange`) once after every local turn or action. */
+  async function flushLocalChange() {
     await ensureStarted();
     await refreshRows();
     const changed = [];
@@ -270,7 +283,7 @@ export function createP2pRoom({
     if (!accepted.length) return { merged: 0 };
     // Flush first: a local fact still waiting to be diffed would otherwise be
     // recorded as merged below and never leave this browser.
-    await afterLocalChange();
+    await flushLocalChange();
     const { ids } = await appendFacts(memoryDir, accepted.map((f) => ({
       subject: f.subject,
       predicate: f.predicate,
@@ -357,9 +370,11 @@ export function createP2pRoom({
         return;
       }
       case "sync-request": {
-        await refreshRows();
-        const timestamp = now();
-        const facts = syncableFacts(cachedRows).flatMap((row) => toWireFacts(row, displayName, timestamp));
+        const facts = await withStore(async () => {
+          await refreshRows();
+          const timestamp = now();
+          return syncableFacts(cachedRows).flatMap((row) => toWireFacts(row, displayName, timestamp));
+        });
         send(transport, syncResponseMessage({ facts }));
         return;
       }
@@ -368,7 +383,7 @@ export function createP2pRoom({
       // between them needs no sequencing.
       case "sync-response":
       case "op":
-        await mergeIncomingFacts(message.facts);
+        await withStore(() => mergeIncomingFacts(message.facts));
     }
   }
 
@@ -413,7 +428,7 @@ export function createP2pRoom({
   /** Mint a fresh invite blob. One blob completes exactly one connection, so
    *  each call replaces whatever earlier invite was still waiting for a reply. */
   async function startSharing() {
-    await ensureStarted();
+    await withStore(ensureStarted);
     const transport = attachTransport(transportFactory());
     pendingShare = transport;
     lastError = null;
@@ -425,7 +440,7 @@ export function createP2pRoom({
   /** Decode someone's invite and answer it. Returns the reply blob to send
    *  back, or a named problem the page can show beside the box it came from. */
   async function acceptInvite(blobString) {
-    await ensureStarted();
+    await withStore(ensureStarted);
     const decoded = decodeInviteBlob(blobString);
     if (decoded.error) {
       lastError = problem("invite", decoded.error);
@@ -453,7 +468,7 @@ export function createP2pRoom({
   /** Feed the joiner's reply back into the invite it answers, completing the
    *  connection. */
   async function completeInvite(replyBlob) {
-    await ensureStarted();
+    await withStore(ensureStarted);
     if (!pendingShare) {
       lastError = problem("reply", "no-pending-invite");
       return lastError;
@@ -482,20 +497,24 @@ export function createP2pRoom({
   }
 
   async function setMyDisplayName(name) {
-    await ensureStarted();
-    displayName = name;
-    await appendFacts(memoryDir, [nodeNameFact(myPeerId, name, now())]);
-    await sortFactIndividualsById();
-    return afterLocalChange();
+    return withStore(async () => {
+      await ensureStarted();
+      displayName = name;
+      await appendFacts(memoryDir, [nodeNameFact(myPeerId, name, now())]);
+      await sortFactIndividualsById();
+      return flushLocalChange();
+    });
   }
 
   /** Wave as `subjectId`, in `roomId` when there is one. chat.html's presence
    *  wave passes null and lands on PRESENCE_SCOPE instead. */
   async function wave(subjectId, roomId = null) {
-    await ensureStarted();
-    await appendFacts(memoryDir, [waveFact(subjectId, roomId || PRESENCE_SCOPE, now())]);
-    await sortFactIndividualsById();
-    return afterLocalChange();
+    return withStore(async () => {
+      await ensureStarted();
+      await appendFacts(memoryDir, [waveFact(subjectId, roomId || PRESENCE_SCOPE, now())]);
+      await sortFactIndividualsById();
+      return flushLocalChange();
+    });
   }
 
   /** Whether `subjectId` is waving right now, read from the cached rows so a
@@ -517,6 +536,53 @@ export function createP2pRoom({
     return peers.get(peerId)?.displayName || String(peerId).slice(0, 8);
   }
 
+  /** Re-bind this room to a fresh store — the recast path. The peer
+   *  connections are the point of keeping the room alive, so nothing about
+   *  the transports or the peer map is touched. In order: flush whatever the
+   *  OLD store still had undiffed (a turn landed just before the recast must
+   *  not vanish silently), swap the store reference, rebuild the diff
+   *  baseline against the new store, write the identity facts into it, then
+   *  push the new store's syncable facts to every open channel as an
+   *  ordinary op and ask each peer for its own view with an ordinary
+   *  sync-request — the exact machinery a freshly opened channel uses, no
+   *  new message type. Runs on the store chain, so a merge in flight when
+   *  the recast happens finishes against the store it started on, and
+   *  everything behind it lands on the new one. */
+  async function rebind({ memoryDir: nextMemoryDir, worldName: nextWorldName, myDisplayName: nextDisplayName } = {}) {
+    if (!nextMemoryDir) throw new Error("rebind needs the store to bind to");
+    return withStore(async () => {
+      if (closed) throw new Error("this room is closed");
+      if (started) await flushLocalChange();
+      memoryDir = nextMemoryDir;
+      if (nextWorldName) worldName = nextWorldName;
+      if (nextDisplayName) displayName = nextDisplayName;
+      started = true;
+      seenProvenanceById.clear();
+      cachedRows = [];
+      const timestamp = now();
+      const identity = [];
+      if (worldId && worldName) identity.push(worldNameFact(worldId, worldName, timestamp));
+      if (myPeerId && displayName) identity.push(nodeNameFact(myPeerId, displayName, timestamp));
+      if (identity.length) {
+        await appendFacts(memoryDir, identity);
+        await sortFactIndividualsById();
+      }
+      await refreshRows();
+      for (const row of cachedRows) seenProvenanceById.set(row.id, row.provenance);
+      const targets = connectedPeers();
+      let pushed = 0;
+      if (targets.length) {
+        const wireTimestamp = now();
+        const facts = syncableFacts(cachedRows).flatMap((row) => toWireFacts(row, displayName, wireTimestamp));
+        pushed = facts.length;
+        if (facts.length) broadcast(opMessage({ from: myPeerId, facts }));
+        broadcast(syncRequestMessage());
+      }
+      emit(factsListeners, { merged: 0, rows: cachedRows });
+      return { pushed, peers: targets.length };
+    });
+  }
+
   function close() {
     closed = true;
     for (const peer of peers.values()) peer.transport.close();
@@ -534,23 +600,24 @@ export function createP2pRoom({
   return {
     peerId: myPeerId,
     worldId,
-    worldName,
+    get worldName() { return worldName; },
     get displayName() { return displayName; },
     get state() { return state; },
     get lastError() { return lastError; },
     get droppedMessages() { return droppedMessages; },
     peers: peerList,
     displayNameFor,
-    start: ensureStarted,
+    start: () => withStore(ensureStarted),
     startSharing,
     acceptInvite,
     completeInvite,
-    afterLocalChange,
+    afterLocalChange: () => withStore(flushLocalChange),
     setMyDisplayName,
     wave,
     isWaving,
+    rebind,
     factRows: () => cachedRows,
-    refresh: refreshRows,
+    refresh: () => withStore(refreshRows),
     onFactsChanged: subscribe(factsListeners),
     onStateChanged: subscribe(stateListeners),
     onPeersChanged: subscribe(peersListeners),

package/src/services/plan-pddl.mjs

@@ -25,6 +25,8 @@
 // is itself a declared class name is a class-to-class edge; anything else is
 // an individual-to-class edge), not a guess.
 
+import { countLabel } from "./viz-theme.mjs";
+
 const attachPrefix = (predicate) => {
   const p = String(predicate ?? "").trim();
   return p.includes(":") ? p : `mgx:${p}`;
@@ -208,7 +210,7 @@ export function planToPddl(plan, { problemName = "tmct-plan", domainName = "tmct
 
   if (actions.length) {
     lines.push("");
-    lines.push(`;; action sequence — findActionPath's own shortest path (${actions.length} move${actions.length === 1 ? "" : "s"})`);
+    lines.push(`;; action sequence — findActionPath's own shortest path (${countLabel(actions.length, "move")})`);
     actions.forEach((action, i) => {
       const before = states[i] || [];
       const after = states[i + 1] || [];

package/src/services/plan-viz.mjs

@@ -18,7 +18,7 @@
 // inline script degrades honestly when that sibling script is absent or
 // fails to load — the live controls disable themselves rather than pretend
 // to work.
-import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson } from "./viz-theme.mjs";
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, countLabel } from "./viz-theme.mjs";
 import { planToPddl } from "./plan-pddl.mjs";
 
 const BOARD_W = 640;
@@ -285,7 +285,7 @@ export function renderPlanHtml({ plan, rendersAs = {}, sizeOrder = [], title } =
   const pageData = planToPageData({ plan, rendersAs, sizeOrder });
   const embedded = embedJson(pageData);
   const pddlText = planToPddl(plan);
-  const pageTitle = title || `tmct plan — ${actions.length} move${actions.length === 1 ? "" : "s"}`;
+  const pageTitle = title || `tmct plan — ${countLabel(actions.length, "move")}`;
 
   return `<!doctype html>
 <!-- data-theme is pinned to dark on purpose: this page reads as a track/
@@ -483,6 +483,7 @@ const PLAN = ${embedded};
 (function () {
   "use strict";
   const escapeHtml = ${escapeHtml.toString()};
+  const countLabel = ${countLabel.toString()};
   // Best-effort: a copy of this page opened without the sibling worker file
   // (a tmct --render plan --output file, a file:// open) just swallows the
   // registration failure and works exactly as before.
@@ -664,7 +665,7 @@ const PLAN = ${embedded};
   mountPlan(PLAN);
 
   // ---- live re-solve: disk-count/max-depth controls + the chat-assert dock
-  // over the sibling plan-browser.bundle.js (window.tmctPlan). Degrades
+  // over the sibling plan-browser.bundle.js (window.tmct). Degrades
   // honestly when the bundle failed to load or wasn't built alongside this
   // page (e.g. a plain renderPlanHtml() call with no bundle nearby) — the
   // baked-in replay above already stands on its own either way.
@@ -677,7 +678,7 @@ const PLAN = ${embedded};
   const chatqEl = document.getElementById("chatq");
   const chatpillsEl = document.getElementById("chatpills");
 
-  const liveAvailable = typeof tmctPlan !== "undefined" && typeof tmctPlan.createPlanSession === "function";
+  const liveAvailable = typeof tmct !== "undefined" && typeof tmct.open === "function";
   if (!liveAvailable) {
     liveStatusEl.textContent = "live re-solve unavailable here — showing the baked-in replay only.";
     liveStatusEl.classList.add("isError");
@@ -711,7 +712,7 @@ const PLAN = ${embedded};
             import("./vendor/wink.js"),
             winkTimeout(WINK_LOAD_TIMEOUT_MS, "wink vendor asset load timed out"),
           ]);
-          tmctPlan.registerWinkModel(() => ({ winkNLP: mod.winkNLP, model: mod.model }));
+          tmct.page.registerWinkModel(() => ({ winkNLP: mod.winkNLP, model: mod.model }));
         } catch (err) {
           // eslint-disable-next-line no-console
           console.warn("tmct plan: the wink vendor asset failed to load, continuing without the lemma/POS tier", err);
@@ -728,9 +729,9 @@ const PLAN = ${embedded};
     }
     function applyPlan(freshPlan) {
       if (!freshPlan) return;
-      const { rendersAs, sizeOrder } = tmctPlan.renderInputsFromPlan(freshPlan);
-      mountPlan(tmctPlan.planToPageData({ plan: freshPlan, rendersAs, sizeOrder }));
-      if (pddlEl) pddlEl.textContent = tmctPlan.planToPddl(freshPlan);
+      const { rendersAs, sizeOrder } = tmct.page.renderInputsFromPlan(freshPlan);
+      mountPlan(tmct.page.planToPageData({ plan: freshPlan, rendersAs, sizeOrder }));
+      if (pddlEl) pddlEl.textContent = tmct.page.planToPddl(freshPlan);
       // The <title>/<h1> were baked from the INITIAL plan's own goal text —
       // a live re-solve toward a different goal (a fresh puzzle, or a
       // taught goal revision) must not leave them stating the old one.
@@ -741,7 +742,7 @@ const PLAN = ${embedded};
     async function ensureSession() {
       if (session) return session;
       await tryLoadWink();
-      session = await tmctPlan.createPlanSession({
+      session = await tmct.open({
         diskCount: Math.max(1, Math.min(7, parseInt(diskCountEl.value, 10) || 3)),
         maxDepth: Math.max(1, parseInt(maxDepthEl.value, 10) || 300),
       });
@@ -756,10 +757,10 @@ const PLAN = ${embedded};
       liveStatusEl.textContent = "solving a " + n + "-disk puzzle…";
       liveStatusEl.classList.remove("isError");
       await tryLoadWink();
-      session = await tmctPlan.createPlanSession({ diskCount: n, maxDepth: d });
+      session = await tmct.open({ diskCount: n, maxDepth: d });
       if (session.plan) {
         applyPlan(session.plan);
-        liveStatusEl.textContent = "live — " + n + " disk" + (n === 1 ? "" : "s") + ", max depth " + d + ".";
+        liveStatusEl.textContent = "live — " + countLabel(n, "disk", "disks") + ", max depth " + d + ".";
       } else {
         liveStatusEl.textContent = "no plan found within " + d + " moves — raise max search depth and try again.";
         liveStatusEl.classList.add("isError");
@@ -776,7 +777,7 @@ const PLAN = ${embedded};
       withLock(async () => {
         const s = await ensureSession();
         const maxDepth = Math.max(1, parseInt(maxDepthEl.value, 10) || 300);
-        const result = await s.turn(q, { maxDepth });
+        const result = await tmct.turn(q, { maxDepth });
         addChatLine("a", result.answer);
         if (result.plan) applyPlan(result.plan);
       });

package/src/services/research-viz.mjs

@@ -2,7 +2,7 @@
 // document shaped exactly like ingest-viz.mjs/chat-page-viz.mjs's own
 // page-builders — one inlined <style> importing viz-theme.mjs's shared tokens,
 // behaviour as an inlined IIFE — running the research engine
-// (research-browser.bundle.js's globalThis.tmctResearch) by same-origin
+// (research-browser.bundle.js's globalThis.tmct) by same-origin
 // relative paths.
 //
 // One in-memory graph grows three ways, each visible on the page:
@@ -20,8 +20,10 @@
 // input. scripts/build-demo-site.mjs calls it directly and writes the result to
 // public/research.html, after research-browser.bundle.js already exists.
 import { THEME_TOKENS_CSS, MONO_STACK, escapeHtml } from "./viz-theme.mjs";
-import { fetchWithProgress } from "./memory-panel-viz.mjs";
+import { fetchWithProgress, loadProgressLine, factTripleParts } from "./memory-panel-viz.mjs";
 import { createTicker, prefersReducedMotion } from "./viz-ticker.mjs";
+import { loadWinkVendor } from "./viz-boot.mjs";
+import { cloneMemoryPayload } from "../adapters/memory/core.mjs";
 
 const DEFAULT_TITLE = "the-mechanical-code-talker — research";
 
@@ -63,35 +65,6 @@ export function sourceLabelFor(source) {
   return { label: (BANDS[band] || band || "seed") + " (seed corpus)", tone: "seed" };
 }
 
-/** One learned fact as its three canonical cells plus a source tone, for the
- *  highlights and history lists. Pure, `.toString()`-splice safe. */
-export function factTripleParts(fact) {
-  return {
-    subject: String((fact && fact.subject) || ""),
-    predicate: String((fact && fact.predicate) || ""),
-    object: String((fact && fact.object) || ""),
-    source: String((fact && fact.source) || ""),
-  };
-}
-
-/** The boot statusline while the big assets stream in — the same aggregator
- *  ingest-viz.mjs's own loadProgressLine is. `parts` is an array of
- *  { loaded, total } byte counts. Self-contained, `.toString()`-splice safe. */
-export function loadProgressLine(parts) {
-  const mb = (n) => (n / 1048576).toFixed(1);
-  let loaded = 0;
-  let total = 0;
-  let totalKnown = true;
-  for (const p of parts || []) {
-    loaded += (p && p.loaded) || 0;
-    if (p && p.total > 0) total += p.total;
-    else totalKnown = false;
-  }
-  return totalKnown && total > 0
-    ? "loading the engine… " + mb(loaded) + " MB / " + mb(total) + " MB"
-    : "loading the engine… " + mb(loaded) + " MB";
-}
-
 /** The self-contained research page. Pure — the same output for the same
  *  input every time; every piece of state is computed live in the browser once
  *  the sibling research bundle loads. `digestStructures` are the pre-parsed
@@ -136,7 +109,7 @@ ${DASH_DARK_CHROME_CSS}
   .brand { display: flex; flex-direction: column; gap: .3rem; max-width: 640px; }
   .eyebrow { font-family: ${MONO_STACK}; font-size: .72rem; letter-spacing: .08em; text-transform: uppercase; color: var(--muted); }
   .subtitle { font-size: .92rem; color: var(--ink); opacity: .82; max-width: 58ch; }
-  .statuspanel { display: flex; gap: 1.1rem; background: var(--card); border: 1px solid var(--line); border-radius: 6px; padding: .5rem .9rem; }
+  .statuspanel { display: flex; flex-wrap: wrap; gap: .5rem 1.1rem; background: var(--card); border: 1px solid var(--line); border-radius: 6px; padding: .5rem .9rem; }
   .statuspanel .stat { display: flex; flex-direction: column; gap: .14rem; min-width: 7rem; }
   .statuspanel .stat-label { font-family: ${MONO_STACK}; font-size: .6rem; letter-spacing: .08em; text-transform: uppercase; color: var(--muted); }
   .statuspanel .stat-value { font-family: ${MONO_STACK}; font-size: .82rem; font-variant-numeric: tabular-nums; color: var(--ink); }
@@ -255,6 +228,7 @@ ${DASH_DARK_CHROME_CSS}
     .cols { grid-template-columns: 1fr; }
     .chip.tapchip { grid-template-columns: 1.5rem minmax(0,1fr) 3.2rem; }
     .chip.tapchip .track { display: none; }
+    .statuspanel .stat { min-width: 0; }
   }
   @media (prefers-reduced-motion: reduce) { * { scroll-behavior: auto !important; } }
   @media (prefers-reduced-motion: no-preference) {
@@ -381,6 +355,8 @@ ${DASH_DARK_CHROME_CSS}
   const fetchWithProgress = ${fetchWithProgress.toString()};
   const createTicker = ${createTicker.toString()};
   const prefersReducedMotion = ${prefersReducedMotion.toString()};
+  const loadWinkVendor = ${loadWinkVendor.toString()};
+  const cloneMemoryPayload = ${cloneMemoryPayload.toString()};
   const el = (id) => document.getElementById(id);
   // The digest sentence-structure bank, pre-parsed at build time — the browser
   // has no TOML parser, so the page carries the table the client-side digest
@@ -409,7 +385,6 @@ ${DASH_DARK_CHROME_CSS}
   const checkedSources = new Set(); // source keys currently checked for the ask
 
   // ---- boot --------------------------------------------------------------
-  const WINK_LOAD_TIMEOUT_MS = 8000;
   const progressParts = {};
   let progressActive = true;
   function noteProgress(key, loaded, total) {
@@ -417,20 +392,7 @@ ${DASH_DARK_CHROME_CSS}
     if (progressActive) statEngineEl.textContent = loadProgressLine(Object.values(progressParts));
   }
 
-  async function tryLoadWink() {
-    let settled = false;
-    const timeout = new Promise((_, reject) => setTimeout(() => { if (!settled) reject(new Error("wink load stalled")); }, WINK_LOAD_TIMEOUT_MS));
-    try {
-      const mod = await Promise.race([import("./vendor/wink.js"), timeout]);
-      settled = true;
-      window.tmctResearch.registerWinkModel(() => ({ winkNLP: mod.winkNLP, model: mod.model }));
-      return "loaded";
-    } catch (err) {
-      settled = true;
-      console.warn("tmct research: the wink vendor asset failed to load", err);
-      return "unavailable";
-    }
-  }
+  const loadWink = loadWinkVendor({ register: (factory) => window.tmct.page.registerWinkModel(factory) });
 
   let seedPayload = null;
   let seedFacts = 0;
@@ -444,12 +406,8 @@ ${DASH_DARK_CHROME_CSS}
       console.warn("tmct research: chat-seed.json unavailable — starting unseeded", err);
     }
   }
-  const cloneSeed = () => {
-    if (!seedPayload) return null;
-    try { return structuredClone(seedPayload); } catch { return JSON.parse(JSON.stringify(seedPayload)); }
-  };
-  function newSession() {
-    return window.tmctResearch.createResearchSession({ seedPayload: cloneSeed(), vocabSeeded: Boolean(seedPayload), digestStructures: DIGEST_STRUCTURES });
+  async function newSession() {
+    return window.tmct.open({ seedPayload: cloneMemoryPayload(seedPayload), vocabSeeded: Boolean(seedPayload), digestStructures: DIGEST_STRUCTURES });
   }
 
   // The curated reference pack provider, same fetch seam chat.html registers,
@@ -474,17 +432,17 @@ ${DASH_DARK_CHROME_CSS}
   };
 
   async function boot() {
-    if (!window.tmctResearch) {
+    if (!window.tmct) {
       engineNoteEl.hidden = false;
       engineNoteEl.textContent = "The research engine did not load. Run npm run demo:build, then reload this page.";
       statSeedEl.textContent = "—";
       statEngineEl.textContent = "unavailable";
       return;
     }
-    const [winkStatus] = await Promise.all([tryLoadWink(), fetchSeed()]);
+    const [winkStatus] = await Promise.all([loadWink(), fetchSeed()]);
     progressActive = false;
-    window.tmctResearch.registerReferencePackProvider(fetchPackProvider);
-    session = newSession();
+    window.tmct.page.registerReferencePackProvider(fetchPackProvider);
+    session = await newSession();
     const winkPart = winkStatus === "loaded" ? "wink-nlp loaded" : "wink-nlp unavailable, curated tiers only";
     statSeedEl.textContent = seedPayload ? seedFacts.toLocaleString() + " facts" : "no seed";
     statEngineEl.textContent = winkPart + " · ready";
@@ -507,7 +465,7 @@ ${DASH_DARK_CHROME_CSS}
   async function refresh() {
     if (!session) return;
     let snap;
-    try { snap = await window.tmctResearch.researchSnapshot(session.memoryDir, session.sessionIds); }
+    try { snap = await window.tmct.page.researchSnapshot(session.memoryDir, session.sessionIds); }
     catch (err) { console.warn("tmct research: snapshot failed", err); return; }
     const total = (snap.sources || []).reduce((sum, source) => sum + (Number(source.count) || 0), 0);
     statFactsEl.textContent = total.toLocaleString();
@@ -668,15 +626,15 @@ ${DASH_DARK_CHROME_CSS}
     answerEl.className = "";
     answerEl.textContent = "thinking…";
     let res;
-    try { res = await session.ask(q, { sources: allChecked ? null : checked }); }
-    catch (err) { res = { text: "", miss: true }; }
-    if (res.miss || !res.text) {
+    try { res = await tmct.ask(q, { sources: allChecked ? null : checked }); }
+    catch (err) { res = { answer: "", miss: true }; }
+    if (res.miss || !res.answer) {
       answerEl.className = "miss";
       const scope = allChecked ? "any checked source" : "the " + checked.length + " checked source" + (checked.length === 1 ? "" : "s");
       answerEl.textContent = "No grounded answer from " + scope + ". It abstains rather than guess.";
     } else {
       answerEl.className = "";
-      answerEl.textContent = res.text;
+      answerEl.textContent = res.answer;
     }
   }
   el("askGo").addEventListener("click", ask);
@@ -747,7 +705,7 @@ ${DASH_DARK_CHROME_CSS}
     const note = el("teachNote");
     note.textContent = "…";
     let res;
-    try { res = await session.turn(q); } catch { res = null; }
+    try { res = await tmct.turn(q); } catch { res = null; }
     if (res && res.record && res.record.via === "assert" && !res.record.miss) {
       note.textContent = "stored: " + (res.answer || "remembered.");
       el("teachInput").value = "";
@@ -828,7 +786,7 @@ ${DASH_DARK_CHROME_CSS}
   async function researchStep(line) {
     if (!session) return;
     let res;
-    try { res = await session.turn(line); } catch { res = null; }
+    try { res = await tmct.turn(line); } catch { res = null; }
     if (res && res.research !== undefined) {
       researchQueue = res.research;
       renderResearchControls();
@@ -859,9 +817,9 @@ ${DASH_DARK_CHROME_CSS}
 
   // ---- tools --------------------------------------------------------------
   el("exportFacts").addEventListener("click", async () => {
-    if (!session || !window.tmctResearch.exportFactsJsonl) return;
+    if (!session || !window.tmct.page.exportFactsJsonl) return;
     let jsonl;
-    try { jsonl = await window.tmctResearch.exportFactsJsonl(session.memoryDir); }
+    try { jsonl = await window.tmct.page.exportFactsJsonl(session.memoryDir); }
     catch { return; }
     const blob = new Blob([jsonl], { type: "application/x-ndjson" });
     const url = URL.createObjectURL(blob);
@@ -874,7 +832,7 @@ ${DASH_DARK_CHROME_CSS}
     researchTicker.pause();
     researchQueue = null;
     checkedSources.clear();
-    session = newSession();
+    session = await newSession();
     el("teachNote").textContent = "";
     el("ingestNote").textContent = "";
     el("researchNote").textContent = "";

package/src/services/spider-fly-turn.mjs

@@ -17,6 +17,7 @@
 
 import {
   DIRECTION_DELTA, WORLD_NAME, cellId, parseCellId, inBounds, chebyshevDistance, oneStepDirectionBetween,
+  agentKindOf, liveIdsOfKind,
 } from "../domain/spider-fly-world.mjs";
 import { foldSpiderFlyState, runSpiderFlyTick, startSpiderFlyGame, beliefSnapshotFor } from "./spider-fly.mjs";
 import { worldProvenanceTag } from "../domain/worlds-pack.mjs";
@@ -121,11 +122,6 @@ async function openSpiderFlyGame({ planHolder, memoryDir, env, cache, gameConfig
 
 // ---- resolving an addressed agent / belief target ----------------------------
 
-const liveIdsOfKind = (kind, state) => {
-  const re = new RegExp(`^${kind}-\\d+$`);
-  return [...state.placements.keys()].filter((id) => re.test(id) && !state.removed.has(id)).sort();
-};
-
 /** An exact "kind-num" reference, or (no number given) the first live
  *  individual of that kind — null when nothing live matches. */
 function resolveAgentId(kind, num, state) {
@@ -133,7 +129,7 @@ function resolveAgentId(kind, num, state) {
     const id = `${kind}-${num}`;
     return state.placements.has(id) && !state.removed.has(id) ? id : null;
   }
-  const live = liveIdsOfKind(kind, state);
+  const live = liveIdsOfKind(state.placements, kind, state.removed);
   return live[0] ?? null;
 }
 
@@ -143,7 +139,7 @@ function resolveAgentId(kind, num, state) {
  *  than one spider or fly. */
 function resolveNearestAgentId(kind, num, state, nearCell) {
   if (num) return resolveAgentId(kind, num, state);
-  const live = liveIdsOfKind(kind, state);
+  const live = liveIdsOfKind(state.placements, kind, state.removed);
   if (!live.length || !nearCell) return live[0] ?? null;
   let best = live[0];
   let bestDist = Infinity;
@@ -193,11 +189,6 @@ export { oneStepDirectionBetween };
 // claim, true or false alike. A pill's `truth` tag is for the human eye
 // only — it never rides along in the submitted text itself.
 
-const liveIdsOfKindFromAgents = (kind, agents) => {
-  const re = new RegExp(`^${kind}-\\d+$`);
-  return Object.keys(agents || {}).filter((id) => re.test(id)).sort();
-};
-
 /** "spider"/"fly" bare when exactly one individual of that kind is live
  *  (nothing to disambiguate), else the individual's own numbered id — a
  *  pill-set legibility choice, not a grammar restriction (the addressed
@@ -246,8 +237,8 @@ function reflectedCell(cell) {
  */
 export function pillsForSpiderFly(agents, explicitAddresseeId, opts = {}) {
   const { defaultKind = "spider" } = opts;
-  const liveSpiders = liveIdsOfKindFromAgents("spider", agents);
-  const liveFlies = liveIdsOfKindFromAgents("fly", agents);
+  const liveSpiders = liveIdsOfKind(agents, "spider");
+  const liveFlies = liveIdsOfKind(agents, "fly");
 
   const addressPills = [
     ...liveSpiders.map((id) => ({ id, kind: "spider", label: `@${agentPillLabel("spider", id, liveSpiders)}` })),
@@ -258,7 +249,7 @@ export function pillsForSpiderFly(agents, explicitAddresseeId, opts = {}) {
   const addresseeId = (explicitAddresseeId && agents[explicitAddresseeId]) ? explicitAddresseeId : fallbackAddresseeId;
   if (!addresseeId) return { addressPills, claimPills: [], addresseeId: null };
 
-  const addresseeKind = /^spider-\d+$/.test(addresseeId) ? "spider" : "fly";
+  const addresseeKind = agentKindOf(addresseeId);
   const addresseeLabel = agentPillLabel(addresseeKind, addresseeId, addresseeKind === "spider" ? liveSpiders : liveFlies);
   const addresseeCell = parseCellId(agents[addresseeId].cell);
 
@@ -352,10 +343,11 @@ async function runTickAndRender({ planHolder, memoryDir, cache, toldFacts = [],
 
 /** One `[id, cellId | null]` belief entry as a sentence: `"spider-1 is at
  *  cell-3-4."` when observed/told, `"fly-2 has not been observed."`
- *  otherwise — the same wording spider-fly-viz.mjs's own click-expand panel
- *  (observedFactsHtml) renders, so the chat phrasing and the browser panel
- *  never disagree about what an agent can see. */
-function observedFactSentence(id, believedCell) {
+ *  otherwise — exported so spider-fly-viz.mjs's own click-expand panel
+ *  (observedFactsHtml) renders from the SAME function instead of a
+ *  hand-typed copy, so the chat phrasing and the browser panel can never
+ *  drift apart. Pure, self-contained, `.toString()`-splice safe. */
+export function believedFactSentence(id, believedCell) {
   return believedCell ? `${id} is at ${believedCell}.` : `${id} has not been observed.`;
 }
 
@@ -374,14 +366,14 @@ async function spiderFlyBeliefAnswer(match, { memoryDir, gameConfig = DEFAULT_GA
   const observerId = resolveAgentId(kind, num, state);
   if (!observerId) return noSuchAgentAnswer(kind, "addressee");
   const observerCell = parseCellId(state.placements.get(observerId).cell);
-  const candidateIds = [...liveIdsOfKind("spider", state), ...liveIdsOfKind("fly", state)];
+  const candidateIds = [...liveIdsOfKind(state.placements, "spider", state.removed), ...liveIdsOfKind(state.placements, "fly", state.removed)];
   const visionRadius = kind === "spider"
     ? gameConfig?.spiderFly?.spiderVisionRadius
     : gameConfig?.spiderFly?.flyVisionRadius;
   const belief = beliefSnapshotFor(observerId, observerCell, candidateIds, state, { visionRadius });
   const entries = Object.entries(belief);
   const text = entries.length
-    ? `${observerId} sees: ${entries.map(([id, cell]) => observedFactSentence(id, cell)).join(" ")}`
+    ? `${observerId} sees: ${entries.map(([id, cell]) => believedFactSentence(id, cell)).join(" ")}`
     : `${observerId} is alone on the board — nothing else to see.`;
   return {
     text,
@@ -446,7 +438,7 @@ const SF_GOAL_RE = /^(?:what(?:'s|\s+is)\s+(?:the\s+|my\s+)?(?:goal|objective|po
 const WATCHER_STANCE = 'you have no piece here — both agents move on their own. Watch, say "tick" to advance, or address one, e.g. "@spider the fly is east".';
 
 const positionsOfKind = (kind, state) =>
-  liveIdsOfKind(kind, state).map((id) => `${id} at ${state.placements.get(id).cell}`);
+  liveIdsOfKind(state.placements, kind, state.removed).map((id) => `${id} at ${state.placements.get(id).cell}`);
 
 async function spiderFlyContextAnswer(line, { memoryDir }) {
   const l = String(line).trim();