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

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,8 +37,9 @@ import {
   foldWorldState, worldActionRows, worldDigestRows, roomAffordances,
   personKnowledgeLines, personKnownFoodLines,
   diggableDirections, castInRoom, displayNameOf, isOutOfPlay, outOfPlayReasonOf, outOfPlayPhrase,
-  roomKindOf,
+  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";
 import { runMudTurn } from "../../services/mud-turn.mjs";
 import { parseMudEditorText, planMudEditorSync } from "../../services/mud-editor.mjs";
@@ -47,6 +47,7 @@ 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";
 
 /** A live, shared mud world several characters can each act in. `worldPayload`
  *  is `{ name, facts, rules, opening }` — the same shape adventure-browser-
@@ -64,13 +65,18 @@ import { resolveSpriteAsset } from "../../domain/sprite-templates.mjs";
  *  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 });
   }
@@ -104,9 +110,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
@@ -116,6 +123,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,
 
@@ -124,27 +145,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
@@ -220,7 +221,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}`,
@@ -232,7 +233,44 @@ export async function createMudSession(worldPayload, { characters = [] } = {}) {
     return { unrecognized, added: toAppend.length, removed };
   }
 
-  return { memoryDir, windows, snapshot, applyEdit };
+  // Wall-clock resolution is 1ms, and both writers below are content-addressed
+  // by (subject, predicate, object) — a second wave from the same character in
+  // the same room is the SAME fact id, so it only registers as a change if its
+  // provenance tag differs. Two writes inside one tick would share a timestamp,
+  // share a tag, and the second would silently vanish. p2p-room.mjs nudges its
+  // own clock for exactly this reason; this is the same nudge for the writes
+  // that happen before a room exists.
+  let lastWriteMs = -Infinity;
+  function stampNow() {
+    const nudged = Math.max(Date.now(), lastWriteMs + 1);
+    lastWriteMs = nudged;
+    return new Date(nudged).toISOString();
+  }
+
+  /** `character` waves in whichever room it currently stands in — an ordinary
+   *  add-only fact, so a page with no network renders it exactly like a page
+   *  sharing the world with three others. Returns the room waved in, or null
+   *  when the character stands nowhere (out of play). Nothing is ever
+   *  retracted: "currently waving" is a recency read over this fact's own
+   *  provenance timestamp. */
+  async function wave(character) {
+    const here = await roomOf(character);
+    if (!here) return null;
+    await appendFacts(memoryDir, [waveFact(character, here, stampNow())]);
+    return here;
+  }
+
+  /** Claim `characters` for `peerId` — one add-only `mgx:playedBy` fact each.
+   *  Claims never overwrite: two peers claiming the same animal both write,
+   *  and every reader settles it the same way by taking the oldest claim. */
+  async function claimCharacters(characters, peerId) {
+    const at = stampNow();
+    const claims = (characters || []).map((character) => playedByFact(character, peerId, at));
+    if (claims.length) await appendFacts(memoryDir, claims);
+    return claims.length;
+  }
+
+  return { memoryDir, windows, snapshot, applyEdit, wave, claimCharacters };
 }
 
 /** `count` entries drawn at random from `roster`, in random order, without
@@ -324,6 +362,10 @@ globalThis.tmctMud = {
   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,

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,6 +31,7 @@ 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
@@ -57,52 +57,34 @@ 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, diskCount, maxDepth, plan, turn: session.turn };
 }
 
 // Re-exported so the page's own rendering script (plan-viz.mjs's inlined

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,8 @@ 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 { 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 +206,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,6 +225,26 @@ 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,
     chatSessionId,
@@ -245,28 +260,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,15 +327,6 @@ 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,

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

@@ -43,14 +43,17 @@
 // spider-fly.mjs's own header comment confirms grid movement never reads
 // them back (hand-written pathfinding over has-exit-* facts, not the taught
 // action-rule DSL), so nothing here depends on them being loaded.
-import { runTurn } from "../../services/chat.mjs";
+import { createTurnSession } from "./turn-session.mjs";
+import { registerWinkModel } from "../../adapters/wink-model.mjs";
 import {
   createInMemoryStore, normFactTerm, appendFacts, loadMemory, readFactRows,
 } from "../../adapters/memory/core.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
+import { worldRelationGraphPayload } from "../../domain/ask.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import {
   worldFactRows, WORLD_NAME, WORLD_OPENING, cellId, parseCellId, DIRECTION_DELTA, visibleCells,
+  isLiveRenderableAgent, agentKindOf,
 } from "../../domain/spider-fly-world.mjs";
 import { foldSpiderFlyState, runSpiderFlyTick, startSpiderFlyGame, liveWebs, DEFAULT_VISION_RADIUS } from "../../services/spider-fly.mjs";
 import { pillsForSpiderFly, oneStepDirectionBetween } from "../../services/spider-fly-turn.mjs";
@@ -84,13 +87,27 @@ export async function createSpiderFlySession({ flyCount = 1 } = {}) {
     else if (f.predicate === "mgx:mass") initialAgents[f.subject] = { ...initialAgents[f.subject], mass: Number(f.object) };
   }
 
-  const graph = parseEntities({ individuals: [], objectProperties: [] });
+  // The graph the chat dock's own ask() traverses. There is no code graph
+  // here, so it holds the LIVE BOARD instead: one individual per agent, classed
+  // by its id, carrying its current cell, mass and mood. That is what makes
+  // "list the locations of flies and spiders" a real ask() capability call
+  // rather than another hand-written filter over the same rows. Rebuilt before
+  // every chat turn, since every tick moves the pieces.
+  let graph = parseEntities({ individuals: [], objectProperties: [] });
+  const readBoard = async () => {
+    const rows = readFactRows(await loadMemory(memoryDir));
+    return { rows, state: foldSpiderFlyState(rows) };
+  };
+  async function refreshWorldGraph() {
+    const { rows, state } = await readBoard();
+    graph = parseEntities(worldRelationGraphPayload(rows, {
+      classOf: (id) => (isLiveRenderableAgent(id, state) ? agentKindOf(id) : null),
+    }));
+  }
+  await refreshWorldGraph();
   const lexicon = loadLexicon();
   const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
 
-  let focus = null;
-  let last = null;
-  let planState = { spiderFly: { turn: 0 } };
   // The live, in-page-slider-adjustable knobs (mass-loss-rate/spawn-rate/
   // vision-radius per class, and every other spiderFly tunable) — starts at
   // the shipped defaults, mutated only through setConfig() below, and
@@ -100,6 +117,19 @@ export async function createSpiderFlySession({ flyCount = 1 } = {}) {
   // change only changes what happens FROM HERE ON, same as tmct.toml would.
   let config = { ...DEFAULT_GAME_CONFIG.spiderFly };
 
+  // The chat dock's turn dispatch — createTurnSession owns the focus/last/
+  // planState fold and the throw-safe catch fallback every browser entry
+  // needs; tick() below reaches into the SAME planState (via setPlanState)
+  // so a raw tick and a chat-driven tick can never disagree about the turn
+  // count either lane sees next.
+  const turnSession = createTurnSession({
+    memoryDir, graph, lexicon, sessionId, vocabHint: "",
+    // `graph` is re-read here, not captured above: createTurnSession binds its
+    // own once at creation, and this board is rebuilt every turn.
+    buildExtraOptions: () => ({ graph, gameConfig: { ...DEFAULT_GAME_CONFIG, spiderFly: config } }),
+  });
+  turnSession.setPlanState({ spiderFly: { turn: 0 } });
+
   return {
     memoryDir,
     sessionId,
@@ -111,30 +141,18 @@ export async function createSpiderFlySession({ flyCount = 1 } = {}) {
      *  { turn, agents, ecology } shape unmodified. */
     async tick() {
       const result = await runSpiderFlyTick(memoryDir, { config });
-      planState = { spiderFly: { turn: result.turn } };
+      turnSession.setPlanState({ spiderFly: { turn: result.turn } });
       return result;
     },
 
     /** One dispatched chat turn — the SAME runTurn the CLI and the home
-     *  page's own chat 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. */
+     *  page's own chat run, over this session's own memoryDir, via the
+     *  shared turn-dispatch wrapper (createTurnSession above) every browser
+     *  entry now uses. The board graph is rebuilt first, so a question about
+     *  where the pieces are reads this turn's positions and not last turn's. */
     async turn(line) {
-      let result;
-      try {
-        result = await runTurn(line, {
-          config: null, source: null, graph, focus, last, memoryDir, sessionId,
-          env: {}, lexicon, vocabHint: "", planState,
-          gameConfig: { ...DEFAULT_GAME_CONFIG, spiderFly: config },
-        });
-      } 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) planState = result.planState;
-      return { answer: result.answer, end: Boolean(result.end), record: result.record ?? null, plan: result.plan ?? null };
+      await refreshWorldGraph();
+      return turnSession.turn(line);
     },
 
     /** A read-only fold of the CURRENT board — no engine advance, no goal
@@ -143,11 +161,10 @@ export async function createSpiderFlySession({ flyCount = 1 } = {}) {
      *  chat-driven tick. Web individuals are never listed as agents (that's
      *  spider-1/fly-1/... only) — they surface only through activeWebs. */
     async snapshot() {
-      const rows = readFactRows(await loadMemory(memoryDir));
-      const state = foldSpiderFlyState(rows);
+      const { state } = await readBoard();
       const agents = {};
       for (const [id, place] of state.placements) {
-        if (state.removed.has(id) || /^web-\d+$/.test(id)) continue;
+        if (!isLiveRenderableAgent(id, state)) continue;
         agents[id] = { cell: place.cell, mass: state.mass.get(id)?.value ?? null };
       }
       return { turn: state.turnCount, agents, activeWebs: liveWebs(state.webs, state.turnCount) };
@@ -183,5 +200,5 @@ export async function createSpiderFlySession({ flyCount = 1 } = {}) {
 globalThis.tmctSpiderFly = {
   createSpiderFlySession, normFactTerm, resolveSpriteForClass, SPRITE_REGISTRY, resolveSpriteAsset,
   cellId, parseCellId, DIRECTION_DELTA, visibleCells, DEFAULT_VISION_RADIUS,
-  pillsForSpiderFly, oneStepDirectionBetween, DEFAULT_GAME_CONFIG,
+  pillsForSpiderFly, oneStepDirectionBetween, DEFAULT_GAME_CONFIG, registerWinkModel,
 };

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

@@ -9,16 +9,22 @@
 // (src/domain/sprite-facts.mjs's rows). A question the engine can't ground in
 // those rows gets the same refusal the CLI gives — never a guess.
 //
-// The page's own inline script answers the closed set of catalog-specific
-// question shapes (sprite-catalog-viz.mjs's answerSpriteQuestion) BEFORE
-// handing a line to this session, so this bundle carries no sprite-specific
-// grammar of its own.
-import { runTurn } from "../../services/chat.mjs";
+// Every line the dock takes goes to that session — the page intercepts
+// nothing, so a catalog question is answered by the same membership, count and
+// property lanes chat.mjs runs for any other caller, reading the sprite-facts
+// predicates straight.
+//
+// The scene composer's parser rides along here too: extractSceneItems resolves
+// 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";
+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 { registerWinkModel } from "../../adapters/wink-model.mjs";
+import { createTurnSession } from "./turn-session.mjs";
 
 /** A live in-memory chat session seeded with the embedded sprite-facts rows.
  *  Returns { memoryDir, sessionId, factCount, turn }. */
@@ -32,32 +38,13 @@ export async function createSpriteCatalogSession({ factRows = [] } = {}) {
   const lexicon = loadLexicon();
   const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
 
-  let focus = null;
-  let last = null;
+  const session = createTurnSession({ memoryDir, graph, lexicon, sessionId, vocabHint: "" });
 
   return {
     memoryDir,
     sessionId,
     factCount: factRows.length,
-
-    /** One dispatched chat turn — the SAME runTurn the CLI runs, 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. */
-    async turn(line) {
-      let result;
-      try {
-        result = await runTurn(line, {
-          config: null, source: null, graph, focus, last, memoryDir, sessionId,
-          env: {}, lexicon, vocabHint: "",
-        });
-      } 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 };
-      }
-      focus = result.focus;
-      last = result.last;
-      return { answer: result.answer, end: Boolean(result.end), record: result.record ?? null };
-    },
+    turn: session.turn,
   };
 }
 
@@ -65,4 +52,4 @@ export async function createSpriteCatalogSession({ factRows = [] } = {}) {
 // 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 };
+globalThis.tmctSprites = { createSpriteCatalogSession, registerWinkModel, normFactTerm, extractSceneItems };