@polycode-projects/the-mechanical-code-talker 5.0.2 → 5.0.4

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

@@ -1,30 +1,85 @@
-// spider-fly-turn.mjs — the chat lane for the headless spider-and-fly game
-// (PLAN_SPIDER_FLY.md §6): loading the shipped board into the session's
-// memory store, the stop command, the addressed spatial teach-frame that
-// feeds a told-fact into the next tick, and the bare "tick" command this
-// game's no-player-controlled-entity posture (§1 — both agents move on
-// their own, every turn) needs for CLI use. Mirrors adventure.mjs's own
-// shape exactly: closed-regex openers/stop, a slot-tagged one-at-a-time
-// coexistence check against the other two lanes, a lane function returning
-// { text, goal?, lane, note, miss? } or null when the turn is not this
-// lane's to answer. The fourth of the four lanes sharing planState's slot.
+// spider-fly-turn.mjs — the spider-and-fly cast: its bindings onto the shared
+// predator/prey engine, and its chat lane.
 //
-// This module never plans a path or scores a move itself — every bit of
-// game logic (fold, pathfinding, belief, ecology) lives in spider-fly.mjs;
-// this file only recognizes chat shapes, resolves them to the shapes
-// runSpiderFlyTick's own interface accepts, and renders its return value as
-// chat text.
+// The bindings are the first section below, and they are the whole of what this
+// game adds to predator-prey.mjs. Every piece of game logic — the (epoch, turn)
+// fold, the pathfinding, belief, the decision chains, the ecology pass — is the
+// shared engine's, run with this board's layout, this board's roles and this
+// board's knobs. Carrying a catch to a web, spinning webs and laying eggs are
+// three opt-in engine features spiderFlyEngineConfig switches on; nothing about
+// them is written twice.
+//
+// The lane is everything after that: loading the shipped board into the
+// session's memory store, the stop command, the addressed spatial teach-frame
+// that feeds a told-fact into the next tick, and the bare "tick" command this
+// game's no-player-controlled-entity posture (both agents move on their own,
+// every turn) needs for CLI use. It mirrors adventure.mjs's own shape exactly:
+// closed-regex openers/stop, a slot-tagged one-at-a-time coexistence check
+// against the other lanes, a lane function returning { text, goal?, lane, note,
+// miss? } or null when the turn is not this lane's to answer.
 
 import {
-  DIRECTION_DELTA, WORLD_NAME, cellId, parseCellId, inBounds, chebyshevDistance, oneStepDirectionBetween,
+  DIRECTION_DELTA, WORLD_NAME, SPIDER_FLY_LAYOUT, SPIDER_FLY_ROLES, spiderFlyEngineConfig,
+  cellId, parseCellId, inBounds, chebyshevDistance, oneStepDirectionBetween,
   agentKindOf, liveIdsOfKind,
 } from "../domain/spider-fly-world.mjs";
-import { foldSpiderFlyState, runSpiderFlyTick, startSpiderFlyGame, beliefSnapshotFor } from "./spider-fly.mjs";
+import { perimeterCells } from "../domain/town-square-world.mjs";
+import {
+  beliefSnapshotFor, foldTownSquareState, liveWebs, runTownSquareTick, seededSpawnCell,
+  startTownSquareGame, townSquareBoard,
+} from "./predator-prey.mjs";
 import { worldProvenanceTag } from "../domain/worlds-pack.mjs";
 import { getWorldsPackProvider } from "../adapters/corpus/worlds-pack.mjs";
 import { appendFacts, appendRule, loadMemory, readFactRows } from "../adapters/memory/core.mjs";
 import { DEFAULT_GAME_CONFIG } from "../domain/game-config.mjs";
 
+// ---- the cast's bindings onto the shared engine ------------------------------
+
+/** Fold fact rows into the current board state — the engine's own fold, named
+ *  for the game whose readers ask for it. */
+export const foldSpiderFlyState = foldTownSquareState;
+
+export { beliefSnapshotFor, liveWebs };
+
+const engineOpts = (config) => ({
+  layout: SPIDER_FLY_LAYOUT,
+  roles: SPIDER_FLY_ROLES,
+  config: spiderFlyEngineConfig(config),
+});
+
+/** Mint spider-1 in its web and a spread of flies around the board edge — a
+ *  fresh session's own starting state, never part of the shipped (reusable,
+ *  static) world pack. A no-op once this epoch already holds a roster, so it is
+ *  safe to call from a caller unsure whether the game has started. The flies'
+ *  cells are seeded picks over the same perimeter list, and off the same
+ *  keyspace, a mid-game arrival draws from. */
+export async function startSpiderFlyGame(memoryDir, { flyCount = 1, config = DEFAULT_GAME_CONFIG.spiderFly } = {}) {
+  const homeCell = SPIDER_FLY_LAYOUT.webHomeCell;
+  const agents = { "spider-1": { role: "predator", cell: homeCell } };
+  const edge = perimeterCells(SPIDER_FLY_LAYOUT);
+  const taken = new Set([homeCell]);
+  for (let i = 1; i <= flyCount; i += 1) {
+    const flyId = `fly-${i}`;
+    const free = edge.filter((c) => !taken.has(c));
+    const cell = seededSpawnCell(free.length ? free : edge, { layoutName: SPIDER_FLY_LAYOUT.name, id: flyId });
+    taken.add(cell);
+    agents[flyId] = { role: "prey", cell };
+  }
+  return startTownSquareGame(memoryDir, { ...engineOpts(config), agents });
+}
+
+/** One full turn on this board. `toldFacts` is the belief layer's chat channel:
+ *  `{ subject, toAgent, cell, turn }` rows, empty for an unaddressed tick. */
+export function runSpiderFlyTick(memoryDir, { toldFacts = [], config = DEFAULT_GAME_CONFIG.spiderFly } = {}) {
+  return runTownSquareTick(memoryDir, { ...engineOpts(config), toldFacts });
+}
+
+/** The board as it stands, in a tick's own payload shape, without running one —
+ *  what a renderer draws between opening a session and the first tick. */
+export function spiderFlyBoard(memoryDir, { toldFacts = [], config = DEFAULT_GAME_CONFIG.spiderFly } = {}) {
+  return townSquareBoard(memoryDir, { ...engineOpts(config), toldFacts });
+}
+
 // ---- recognizers: the closed opening/stop/tick/address set -------------------
 
 // The opener names the game without requiring a specific phrasing order —
@@ -42,15 +97,14 @@ const SPIDER_FLY_OPEN_RE =
 // player thinks of the session.
 const SPIDER_FLY_STOP_RE =
   /^(?:stop\s+(?:watching|playing)|quit\s+(?:the\s+)?(?:spider\s+and\s+fly\s+)?game|end\s+the\s+spider(?:\s+and\s+fly)?\s+game|leave\s+the\s+game)[.!?\s]*$/i;
-// The bare tick command — NOT specified by PLAN_SPIDER_FLY.md itself (§11's
-// Play/step button is the page's own answer to "nothing requires the human
-// to act"; this is that same need's CLI/chat equivalent). Styled after the
-// plan lane's own PLAN_NEXT_RE ("next"/"next move"/"go on"/"continue").
+// The chat equivalent of the page's own Play/step button: nothing here
+// requires the human to act, so a watcher needs a word that advances a turn.
+// Styled after the plan lane's own PLAN_NEXT_RE ("next"/"next move"/"go on").
 const SPIDER_FLY_TICK_RE = /^(?:tick|next\s+turn|advance(?:\s+the\s+turn)?)[.!?\s]*$/i;
 
-// The spatial teach-frame (§6.1): "@spider the fly is east" / "@spider the
-// fly is at cell-7-3". Its own closed regex, not a route through
-// parseRelation/parseCopula/parseOfForm — §6.1 found both hit real grammar
+// The spatial teach-frame: "@spider the fly is east" / "@spider the fly is at
+// cell-7-3". Its own closed regex, not a route through
+// parseRelation/parseCopula/parseOfForm — both hit real grammar
 // gaps for this exact shape (the bare copula reading mints a nonsense
 // subclass axiom; the "of" form hits parseAce's own hard-null guard before
 // ever reaching parseRelation/parseCopula). A fixed compass set — north,
@@ -284,6 +338,21 @@ export function pillsForSpiderFly(agents, explicitAddresseeId, opts = {}) {
 
 // ---- rendering one tick's return value as plain chat text --------------------
 
+/** One ecology event as the clause a player reads. Null for an event type this
+ *  board never produces, so a cast that grows one later reads as silence rather
+ *  than as a broken sentence. */
+function ecologyClause(event) {
+  switch (event.type) {
+    case "catch-prey": return `${event.predator} caught ${event.prey} at ${event.cell}`;
+    case "eat-agent": return `${event.prey} was eaten by ${event.predator} at ${event.cell}`;
+    case "starve": return `${event.agent} starved`;
+    case "lay-egg": return `${event.egg} was laid`;
+    case "hatch-egg": return `${event.egg} hatched into ${event.hatchlings.map((h) => h.id).join(" and ")} at ${event.cell}`;
+    case "spawn-prey": return `${event.agent} arrived at the board edge`;
+    default: return null;
+  }
+}
+
 function renderTickText(tick, addressedNote) {
   const parts = [];
   if (addressedNote) parts.push(`${addressedNote}.`);
@@ -291,15 +360,8 @@ function renderTickText(tick, addressedNote) {
   parts.push(ids.length
     ? `Turn ${tick.turn} — ${ids.map((id) => `${id} is now at ${tick.agents[id].cell}`).join("; ")}.`
     : `Turn ${tick.turn} — no agents remain on the board.`);
-  const eco = tick.ecology;
-  const events = [];
-  for (const c of eco.caught) events.push(`${c.spider} caught ${c.fly} at ${c.cell}`);
-  for (const e of eco.eaten) events.push(`${e.fly} was eaten by ${e.spider} at ${e.cell}`);
-  for (const f of eco.starved) events.push(`${f} starved`);
-  if (eco.laid) events.push(`${eco.laid} was laid`);
-  for (const h of eco.hatched) events.push(`${h.egg} hatched into ${h.spiders.map((s) => s.spider).join(" and ")} at ${h.cell}`);
-  if (eco.spawned) events.push(`${eco.spawned} arrived at the board edge`);
-  if (events.length) parts.push(`${events.join("; ")}.`);
+  const clauses = tick.ecology.map(ecologyClause).filter(Boolean);
+  if (clauses.length) parts.push(`${clauses.join("; ")}.`);
   return parts.join(" ");
 }
 
@@ -316,14 +378,26 @@ function combinedGoalLine(agents) {
   return ids.map((id) => `${id} — ${agents[id].goal.replace(/\.\s*$/, "")}`).join("; ");
 }
 
-function describeEcologyNote(eco) {
-  const bits = [];
-  if (eco.caught.length) bits.push(`${eco.caught.length} caught`);
-  if (eco.eaten.length) bits.push(`${eco.eaten.length} eaten`);
-  if (eco.starved.length) bits.push(`${eco.starved.length} starved`);
-  if (eco.laid) bits.push("1 laid");
-  if (eco.hatched.length) bits.push(`${eco.hatched.reduce((n, h) => n + h.spiders.length, 0)} hatched`);
-  if (eco.spawned) bits.push("1 spawned");
+const ECOLOGY_NOTE_WORDS = Object.freeze({
+  "catch-prey": "caught",
+  "eat-agent": "eaten",
+  starve: "starved",
+  "lay-egg": "laid",
+  "hatch-egg": "hatched",
+  "spawn-prey": "spawned",
+});
+
+function describeEcologyNote(events) {
+  const tally = new Map();
+  for (const event of events) {
+    const word = ECOLOGY_NOTE_WORDS[event.type];
+    if (!word) continue;
+    const n = event.type === "hatch-egg" ? event.hatchlings.length : 1;
+    tally.set(word, (tally.get(word) ?? 0) + n);
+  }
+  const bits = Object.values(ECOLOGY_NOTE_WORDS)
+    .filter((word) => tally.has(word))
+    .map((word) => `${tally.get(word)} ${word}`);
   return bits.length ? `; ${bits.join(", ")}` : "";
 }
 
@@ -352,8 +426,8 @@ export function believedFactSentence(id, believedCell) {
 }
 
 /** "what does the fly see?" / "what does the spider see?" rendered as plain
- *  text: the same beliefSnapshotFor read spider-fly.mjs's own tick loop and
- *  the browser panel already use, over the CURRENT board state — read-only,
+ *  text: the same beliefSnapshotFor read the engine's own tick loop and the
+ *  browser panel already use, over the CURRENT board state — read-only,
  *  no tick runs, nothing is written. Candidates are every OTHER live agent
  *  of either kind; toldFacts is empty (a told position only ever arrives
  *  fresh alongside a tick — see runToldFactTurn — so there is none standing
@@ -385,11 +459,10 @@ async function spiderFlyBeliefAnswer(match, { memoryDir, gameConfig = DEFAULT_GA
 /** The addressed teach-frame turn: resolve the addressee and the belief
  *  subject, resolve the told cell, and run ONE tick with that told-fact fed
  *  in. Told-facts are NOT persisted on the session slot across turns — each
- *  addressed line supplies belief for the NEXT tick only, then is gone
- *  (the simplest of the plan doc's own named options, §4's "carry only the
- *  current turn's told-facts"). This also matches how runSpiderFlyTick
- *  itself already works: it holds no standing plan or belief between calls,
- *  recomputing everything fresh from the folded fact rows every tick. */
+ *  addressed line supplies belief for the NEXT tick only, then is gone. That
+ *  matches how the engine itself already works: it holds no standing plan or
+ *  belief between calls, recomputing everything fresh from the folded fact
+ *  rows every tick. */
 async function runToldFactTurn(match, { planHolder, memoryDir, cache, gameConfig = DEFAULT_GAME_CONFIG }) {
   const [, addrKindRaw, addrNum, subjKindRaw, subjNum, direction, cellLiteral] = match;
   const addrKind = addrKindRaw.toLowerCase();
@@ -414,7 +487,7 @@ async function runToldFactTurn(match, { planHolder, memoryDir, cache, gameConfig
   }
 
   const targetCellId = cellId(targetCell.x, targetCell.y);
-  const toldFacts = [{ subject: subjectId, toAgent: addresseeId, cell: targetCellId, turn: state.turnCount + 1 }];
+  const toldFacts = [{ subject: subjectId, toAgent: addresseeId, cell: targetCellId, turn: state.tickCount + 1 }];
   return runTickAndRender({
     planHolder, memoryDir, cache, toldFacts, gameConfig,
     addressedNote: `told the ${addresseeId} the ${subjectId} is at ${targetCellId}`,
@@ -487,13 +560,12 @@ async function spiderFlyContextAnswer(line, { memoryDir }) {
 
 /**
  * The whole spider-and-fly lane for one turn: the opening moves, the stop
- * command, the addressed spatial teach-frame (§6.1), the bare tick command,
- * and the one-at-a-time declines across the shared plan slot both other
- * lanes already implement pairwise. Returns { text, lane, note, goal?,
- * miss? } or null when the turn is not this lane's to answer — an
- * unaddressed aside (e.g. "where is the spider") falls through to the
- * ordinary lanes unchanged, board untouched (§6.2 — no special-cased
- * spider-fly code path for plain questions).
+ * command, the addressed spatial teach-frame, the bare tick command, and the
+ * one-at-a-time declines across the shared plan slot the other lanes already
+ * implement pairwise. Returns { text, lane, note, goal?, miss? } or null when
+ * the turn is not this lane's to answer — an unaddressed aside (e.g. "where is
+ * the spider") falls through to the ordinary lanes unchanged, board untouched,
+ * with no special-cased code path for plain questions.
  */
 export async function spiderFlyTurn(line, { planHolder, memoryDir, env, cache = null, isPlanFrameLine = () => false, gameConfig = DEFAULT_GAME_CONFIG }) {
   const slot = planHolder?.state ?? null;

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

@@ -1,18 +1,17 @@
-// spider-fly-viz.mjs — the spider-and-fly full-screen page (PLAN_SPIDER_FLY.md
-// §8/§9/§11): a self-contained document shaped exactly like ledger-viz.mjs/
-// plan-viz.mjs — one inlined <style> (importing viz-theme.mjs's shared
-// tokens), behaviour as an inlined IIFE — but unlike those two, almost
-// nothing is embedded as build-time data: the whole game is LIVE client-side
-// state (spider-fly-browser-entry.mjs's createSpiderFlySession), so
-// renderSpiderFlyHtml only needs the page's own static grid geometry (which
-// never changes) plus a title. The engine, sprite resolver and chat turn
-// engine all arrive via ./spider-fly-browser.bundle.js, referenced with a
-// plain same-origin <script src> — the same sibling-file arrangement
-// index.html already uses for chat-browser.bundle.js (both are the FULL
-// turn engine, both generated fresh per build, neither meant to be
-// committed), not memory-ask-browser.bundle.js's inlined-text arrangement
-// (that bundle is small and inlined specifically so ledger.html stays
-// portable on its own — that reason doesn't apply here).
+// spider-fly-viz.mjs — the spider-and-fly full-screen page: a self-contained
+// document shaped exactly like ledger-viz.mjs/plan-viz.mjs — one inlined <style>
+// (importing viz-theme.mjs's shared tokens), behaviour as an inlined IIFE — but
+// unlike those two, almost nothing is embedded as build-time data: the whole
+// game is LIVE client-side state (spider-fly-browser-entry.mjs's
+// createSpiderFlySession), so renderSpiderFlyHtml only needs the page's own
+// static grid geometry (which never changes) plus a title. The engine, sprite
+// resolver and chat turn engine all arrive via ./spider-fly-browser.bundle.js,
+// referenced with a plain same-origin <script src> — the same sibling-file
+// arrangement index.html already uses for chat-browser.bundle.js (both are the
+// FULL turn engine, both generated fresh per build, neither meant to be
+// committed), not memory-ask-browser.bundle.js's inlined-text arrangement (that
+// bundle is small and inlined specifically so ledger.html stays portable on its
+// own — that reason doesn't apply here).
 //
 // renderSpiderFlyHtml() is pure: no I/O, deterministic output for identical
 // input. scripts/build-demo-site.mjs calls it directly and writes the result
@@ -37,7 +36,6 @@ import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embed
 import { createTicker } from "./viz-ticker.mjs";
 import { loadWinkVendor } from "./viz-boot.mjs";
 import { GRID_SIZE, WEB_HOME, WEB_RADIUS, isInWebBlock, cellId, agentKindOf } from "../domain/spider-fly-world.mjs";
-import { FLY_INITIAL_MASS, EGG_LAY_MASS_THRESHOLD } from "./spider-fly.mjs";
 import { believedFactSentence } from "./spider-fly-turn.mjs";
 import { DEFAULT_GAME_CONFIG, massScaleFor } from "../domain/game-config.mjs";
 import { resolveSpriteRequest } from "../domain/sprite-request.mjs";
@@ -69,11 +67,11 @@ function webCellIds() {
 /**
  * Reconstruct the spider's remaining silk-thread path — the sequence of
  * cell ids from its CURRENT cell (after this tick's one executed step) to
- * wherever `findActionPath` was aiming — from spider-fly.mjs's own
+ * wherever `findActionPath` was aiming — from spider-fly-turn.mjs's own
  * `agents[spiderId]` shape ({ cell, plan }), where `plan` is the FULL
  * direction list `findActionPath` returned (the step already taken this
  * tick, `plan[0]`, plus every step still to come). Only a spider with a
- * REAL multi-step plan draws a thread at all: spider-fly.mjs's own
+ * REAL multi-step plan draws a thread at all: spider-fly-turn.mjs's own
  * `planSpiderPath` only ever returns one when the believed fly cell sits
  * inside the web block (its `isGoal`'s own requirement) — most ticks the
  * spider is greedily closing distance with no such plan, and this
@@ -104,7 +102,7 @@ export function threadCellsForSpiderPlan(agents, geometry) {
 }
 
 /** The sprite-facing rotation (degrees) for one agent this tick, driven by
- *  its CURRENT plan's first step (spider-fly.mjs's own `agents[id].plan`),
+ *  its CURRENT plan's first step (spider-fly-turn.mjs's own `agents[id].plan`),
  *  never its actual next move — the two usually coincide, but re-planning
  *  fresh every tick means they can visibly diverge as a plan gets clobbered
  *  and replaced, which is the intended, honest demonstration of "plans get
@@ -126,19 +124,17 @@ export function facingDegreesFor(plan, previousDegrees) {
 }
 
 /**
- * The updated corpse set for one redraw (§A.2.5 — visual-only, entirely
- * client-side; the actual starve/eat removal already happened in the
- * engine). Every id present in `prevAgents` but absent from `agents` died
- * THIS tick — eaten or starved are the only two ways an agent ever leaves
- * the engine's own returned roster — and is added at its last-known cell
- * and class; every corpse already older than `lingerTurns` past its own
- * death turn is dropped first, so the set never grows without bound.
- * Returns a plain `{ [id]: { cls, cell, diedAtTurn } }` map. Pure.
- * `lingerTurns` defaults to a literal 4 (not the module-level
- * CORPSE_LINGER_TURNS constant) so this function stays fully
- * `.toString()`-splice safe — every real caller (both the inlined page and
- * CORPSE_LINGER_TURNS's own callers elsewhere in this module) passes it
- * explicitly anyway.
+ * The updated corpse set for one redraw — visual-only, entirely client-side;
+ * the actual starve/eat removal already happened in the engine. Every id
+ * present in `prevAgents` but absent from `agents` died THIS tick — eaten or
+ * starved are the only two ways an agent ever leaves the engine's own returned
+ * roster — and is added at its last-known cell and class; every corpse already
+ * older than `lingerTurns` past its own death turn is dropped first, so the set
+ * never grows without bound. Returns a plain `{ [id]: { cls, cell, diedAtTurn }
+ * }` map. Pure. `lingerTurns` defaults to a literal 4 (not the module-level
+ * CORPSE_LINGER_TURNS constant) so this function stays fully `.toString()`-splice
+ * safe — every real caller (both the inlined page and CORPSE_LINGER_TURNS's own
+ * callers elsewhere in this module) passes it explicitly anyway.
  */
 export function nextCorpses(prevCorpses, prevAgents, agents, turn, lingerTurns = 4) {
   const out = {};
@@ -167,9 +163,9 @@ export function nextCorpses(prevCorpses, prevAgents, agents, turn, lingerTurns =
  *  back to the flat SPRITE_REGISTRY, unchanged from before this module
  *  existed).
  *  `?preview=1` on the page's own URL switches it into the small, auto-
- *  playing, non-interactive mode the home page's hero iframe embeds (§11) —
- *  one file serves both the hero and the "open full-screen" link, matching
- *  how ledger.html/plan.html are each one file embedded two ways.
+ *  playing, non-interactive mode the home page's hero iframe embeds — one file
+ *  serves both the hero and the "open full-screen" link, matching how
+ *  ledger.html/plan.html are each one file embedded two ways.
  *  `engineBundleJs` (the built spider-fly-browser bundle's own text) inlines
  *  the engine into the page instead of the sibling `<script src>`, for the
  *  CLI's standalone export — one downloadable file that runs from file://
@@ -188,13 +184,11 @@ export function renderSpiderFlyHtml({ title = DEFAULT_TITLE, spriteTemplates = [
     previewMaxTurns: PREVIEW_MAX_TURNS,
     tickWaitMs: TICK_WAIT_MS,
     corpseLingerTurns: CORPSE_LINGER_TURNS,
-    maxFlyMass: FLY_INITIAL_MASS,
-    // The spider's mass bar now scales against the EGG-LAY threshold, not
-    // its own starting mass — "how close to laying" is the meaningful cap
-    // to visualize under the new mass-gated lay mechanic (§A.2.2); the old
-    // denominator (a flat starting mass) said nothing about progress toward
-    // the spider's actual goal.
-    maxSpiderMass: EGG_LAY_MASS_THRESHOLD,
+    maxFlyMass: DEFAULT_GAME_CONFIG.spiderFly.flyInitialMass,
+    // The spider's mass bar scales against the egg-lay threshold rather than
+    // its own starting mass: "how close to laying" is what a viewer wants to
+    // read, and a flat starting mass says nothing about progress toward it.
+    maxSpiderMass: DEFAULT_GAME_CONFIG.spiderFly.eggLayMassThreshold,
     defaultConfig: DEFAULT_GAME_CONFIG.spiderFly,
     spriteTemplates,
   });
@@ -347,11 +341,11 @@ ${THEME_TOKENS_CSS}
   .hud-id.spider { color: var(--taught); } .hud-id.fly { color: var(--fly); } .hud-id.egg { color: var(--muted); }
   .hud-goal { font-size: .85rem; }
   .hud-plan, .hud-belief { font-family: ${MONO_STACK}; font-size: .66rem; color: var(--muted); margin-top: .25rem; line-height: 1.4; padding-left: .5rem; border-left: 2px solid var(--chrome-accent); }
-  /* the click-expand facts panel (§28): beside the clicked spider/fly's own
-     row, never a separate popover or a second panel elsewhere on the page —
-     the same believedCellOf/beliefSnapshotFor read path spider-fly.mjs
-     already computes every tick for planning, rendered here as full
-     sentences instead of the compact believes:-line above. */
+  /* the click-expand facts panel: beside the clicked spider/fly's own row,
+     never a separate popover or a second panel elsewhere on the page — the same
+     believedCellOf/beliefSnapshotFor read path spider-fly-turn.mjs already
+     computes every tick for planning, rendered here as full sentences instead of
+     the compact believes:-line above. */
   .hud-detail { flex: 1 1 auto; min-width: 0; font-family: ${MONO_STACK}; font-size: .64rem; line-height: 1.5; color: var(--chrome-well-ink); background: var(--chrome-well); border: 1px solid var(--chrome-edge-lo); box-shadow: var(--chrome-shadow-inset); border-radius: 2px; padding: .35rem .5rem; }
   .hud-detail-title { text-transform: uppercase; letter-spacing: .06em; opacity: .75; margin-bottom: .2rem; }
   /* A stat-readout track: an inset "LCD" well, filled with a segmented pip
@@ -381,11 +375,11 @@ ${THEME_TOKENS_CSS}
   .pill:hover:not(:disabled) { border-color: var(--chrome-accent); }
   .pill:disabled { opacity: .45; cursor: default; }
   .pill[data-role="addr"].active { border-color: var(--taught); color: var(--taught); }
-  /* The dynamic deception-pill rail (§A.2.4): a true/false tag shown ONLY
-     here, via border style/color and a small human-facing glyph — the
-     submitted sentence itself (data-sentence, filled into #chatq on click)
-     never carries the tag, so a clicked pill is indistinguishable from a
-     hand-typed claim once it's in the input. */
+  /* The dynamic deception-pill rail: a true/false tag shown ONLY here, via
+     border style/color and a small human-facing glyph — the submitted sentence
+     itself (data-sentence, filled into #chatq on click) never carries the tag,
+     so a clicked pill is indistinguishable from a hand-typed claim once it's in
+     the input. */
   .dynpills { display: flex; flex-wrap: wrap; gap: .3rem; margin-top: .5rem; padding-top: .5rem; border-top: 1px solid var(--chrome-edge-lo); }
   .dynpills:empty { display: none; padding-top: 0; border-top: none; }
   .pill[data-role="dyn-addr"][data-active="1"] { border-color: var(--taught); color: var(--taught); }
@@ -748,13 +742,13 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
     lastAgents = agents;
   }
 
-  // ---- corpses (§A.2.5): visual-only — the actual starve/eat removal
-  // already happened in the engine before this redraw ever sees "agents".
-  // A corpse sinks to the bottom row of the SAME board column it died in
-  // ("drops to the bottom" — spider-fly-world.mjs's own x/y convention,
-  // y = GRID_SIZE is the bottom row) and fades out once CORPSE_LINGER_TURNS
-  // passes, drawn in the same sprite layer as every live sprite, just
-  // grayscaled and non-interactive (see the .sprite.corpse CSS rule).
+  // ---- corpses: visual-only — the actual starve/eat removal already happened
+  // in the engine before this redraw ever sees "agents". A corpse sinks to the
+  // bottom row of the SAME board column it died in ("drops to the bottom" —
+  // spider-fly-world.mjs's own x/y convention, y = GRID_SIZE is the bottom row)
+  // and fades out once CORPSE_LINGER_TURNS passes, drawn in the same sprite
+  // layer as every live sprite, just grayscaled and non-interactive (see the
+  // .sprite.corpse CSS rule).
   function renderCorpses() {
     for (const id of Object.keys(corpseEls)) {
       if (!corpses[id]) { corpseEls[id].remove(); delete corpseEls[id]; }
@@ -796,12 +790,12 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
     return '<div class="hud-plan">plan: ' + text + ".</div>";
   }
 
-  // The agent's own current world-knowledge-graph snapshot (§A.2.7) — every
-  // OTHER live individual it believes it knows the position of, or
-  // "unseen" when it has no belief at all. Deliberately never ground truth:
-  // this is what the agent would actually ACT on, which a false pill or a
-  // told fact can make visibly wrong compared to where that individual
-  // really is — the gap IS the demonstration.
+  // The agent's own current world-knowledge-graph snapshot — every OTHER live
+  // individual it believes it knows the position of, or "unseen" when it has no
+  // belief at all. Deliberately never ground truth: this is what the agent
+  // would actually ACT on, which a false pill or a told fact can make visibly
+  // wrong compared to where that individual really is — the gap IS the
+  // demonstration.
   function beliefLineHtml(belief) {
     const entries = Object.entries(belief || {});
     if (!entries.length) return "";
@@ -1026,12 +1020,12 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   chatqEl.addEventListener("input", refreshPills);
   refreshPills();
 
-  // ---- deception pills (§A.2.4): a SEPARATE dynamic rail, alongside (never
-  // replacing) the static one above. tmct.page.pillsForSpiderFly is the
-  // exact same pure function spider-fly-turn.mjs exports — this page never
-  // reimplements the true/false claim logic, only renders its output and
-  // fills #chatq on click, same click-to-fill discipline as every other
-  // pill on this page (never auto-submits).
+  // ---- deception pills: a SEPARATE dynamic rail, alongside (never replacing)
+  // the static one above. tmct.page.pillsForSpiderFly is the exact same pure
+  // function spider-fly-turn.mjs exports — this page never reimplements the
+  // true/false claim logic, only renders its output and fills #chatq on click,
+  // same click-to-fill discipline as every other pill on this page (never
+  // auto-submits).
   function renderDynamicPills() {
     if (!session || !Object.keys(lastAgents).length) { dynamicPillsEl.innerHTML = ""; return; }
     const result = tmct.page.pillsForSpiderFly(lastAgents, selectedAddresseeId, {});

package/src/services/world-teach.mjs

@@ -34,7 +34,7 @@
 // page's own edit mode already makes.
 import { appendFacts, loadMemory, readFactRows } from "../adapters/memory/core.mjs";
 import { worldProvenanceTag } from "../domain/worlds-pack.mjs";
-import { correctMisspellings } from "../domain/interpret/normalize.mjs";
+import { correctMisspellings, QUESTION_LEAD_RE } from "../domain/interpret/normalize.mjs";
 import {
   classMassFacts, foldWorldState, freshObjectId, snapshotSubject, worldActionRows, worldRelook,
 } from "./adventure.mjs";
@@ -44,8 +44,8 @@ import {
 // word earlier, run over the closed misspelling repair so a typo'd "wat is the
 // lamp" goes back to the question side rather than reading as a declarative.
 // Both mirror chat.mjs's own teach lane, which stands the whole lane down on
-// either — a world teach has exactly the same reason to.
-const QUESTION_LEAD_RE = /^(?:what|who|which|where|when|why|how|is|are|do|does|did|can|could|should|would|will|has|have)\b/i;
+// either — a world teach has exactly the same reason to (see
+// normalize.mjs's QUESTION_LEAD_RE).
 
 // A subject with no referent of its own. The generic "X is a Y." fallback in
 // both sentence tables would otherwise read "There is a book in the study" as

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

@@ -43,6 +43,7 @@ import {
 import { parseEntities } from "../../domain/codegraph.mjs";
 import { memoryFactGraphPayload } from "../../domain/memory-facts.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
+import { DEFAULT_GAME_CONFIG } from "../../domain/game-config.mjs";
 import { foldWorldState, worldDigestRows, roomAffordances, worldActionRows, snapshotSubject } from "../../services/adventure.mjs";
 import { runAdventureAutoplayTick, exposedFacts } from "../../services/adventure-autoplay.mjs";
 import { parseWorldEditorText, planWorldEditorSync } from "../../services/adventure-editor.mjs";
@@ -66,8 +67,13 @@ import { openPersistedStore } from "./idb-persist.mjs";
  *  already carries them, plus every @turnN state row played since, so the
  *  world resumes exactly where the fold left it. `restoredVisitedRoomIds`
  *  carries the matching exposure set forward; without it, only the player's
- *  current room counts as visited. */
-export async function createAdventureSession(worldPayload, { restoredPayload = null, restoredVisitedRoomIds = null } = {}) {
+ *  current room counts as visited.
+ *
+ *  `getTeachEnabled` (optional) is read fresh on every turn, never once at
+ *  boot — the page's own teach checkbox, so flipping it mid-game changes the
+ *  very next line's reading without a reset. Defaults to always-off, which is
+ *  DEFAULT_GAME_CONFIG.adventure.teach's own default. */
+export async function createAdventureSession(worldPayload, { restoredPayload = null, restoredVisitedRoomIds = null, getTeachEnabled = () => false } = {}) {
   const memoryDir = createInMemoryStore();
   const tag = `world:${worldPayload.name}`;
   if (restoredPayload) {
@@ -134,7 +140,10 @@ export async function createAdventureSession(worldPayload, { restoredPayload = n
   const turnSession = createTurnSession({
     memoryDir, graph: codeGraph, lexicon, sessionId,
     vocabHint: 'Try a world question ("where is the key"), or teach me: "remember: the moat is a ditch".',
-    buildExtraOptions: () => ({ planState: planHolder.state }),
+    buildExtraOptions: () => ({
+      planState: planHolder.state,
+      gameConfig: { ...DEFAULT_GAME_CONFIG, adventure: { ...DEFAULT_GAME_CONFIG.adventure, teach: getTeachEnabled() } },
+    }),
     captureExtraState: async (result) => {
       if ("planState" in result) planHolder.state = result.planState;
       const here = foldWorldState(worldActionRows(readFactRows(await loadMemory(memoryDir)))).placements.get("player")?.object ?? null;