@polycode-projects/the-mechanical-code-talker 5.0.3 → 5.0.5

package/src/services/mudiii-scene.mjs

@@ -186,12 +186,14 @@ export function currentActionFor(agentId, agentsById, moving) {
  *  so acting on the ecology row too would double it). `kind` is one of
  *  "death" (the rig's own Death clip, then scale to zero) or "consume" (an
  *  eaten item scales to zero, no clip — items are primitive geometry).
- *  Pure. */
+ *  `eat-agent` alone also carries `actorId`, the predator that gets a
+ *  one-shot attack clip while its prey plays death — the one event where a
+ *  second, surviving agent has its own flourish to play. Pure. */
 export function flourishForEcologyEvent(event) {
   if (!event || !event.type) return null;
   switch (event.type) {
     case "eat-agent":
-      return { kind: "death", targetId: event.prey, cell: event.cell };
+      return { kind: "death", targetId: event.prey, cell: event.cell, actorId: event.predator };
     case "starve":
       return { kind: "death", targetId: event.agent, cell: event.cell };
     case "eat-item":
@@ -359,6 +361,11 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
   var manifestByKind = {};
   var lastAgentsById = {};
   var lastItemsById = {};
+  // Every removeAgent/removeItem call, kept small and reset on boot — an
+  // e2e assertion's read, so it can tell an eaten agent/item's flourish
+  // removal (source "ecology") apart from applyTick's own diff no-op
+  // (source "diff") without guessing from a vanished mesh alone.
+  var removalLog = [];
   var cameraState = { mode: "overhead", selectedId: null };
   var cameraTween = null, lookAtTween = null;
   var lastFrameTs = null;
@@ -385,9 +392,6 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
       });
     });
   }
-  var glbCache = null;
-  function loadGlb(url) { return glbCache.load(url); }
-
   async function ensureThree() {
     if (THREE) return true;
     var result = await loadThreeVendor();
@@ -396,7 +400,6 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     OrbitControlsCtor = result.OrbitControls; MeshoptDecoderRef = result.MeshoptDecoder;
     gltfLoader = new GLTFLoaderCtor();
     gltfLoader.setMeshoptDecoder(MeshoptDecoderRef);
-    glbCache = createCachedLoader(loadGlbRaw);
     setUpScene();
     return true;
   }
@@ -513,13 +516,23 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     object3D.userData.tmctNormalized = true;
   }
 
-  async function loadPropTemplate(asset) {
-    var url = modelUrlFor(asset.destPath);
-    if (propTemplates[url]) return propTemplates[url];
-    var gltf = await loadGlb(url);
-    normalizeToHeight(gltf.scene, asset.targetHeight);
-    propTemplates[url] = gltf.scene;
-    return gltf.scene;
+  // Keyed on the manifest row's own key field, not its destPath: food-crumb
+  // and food-morsel share one GLB at two different targetHeights, and
+  // normalizeToHeight refuses a second call on the same object, so a
+  // destPath-keyed cache would hand the second row the first row's
+  // already-normalized graph and throw.
+  function loadPropTemplate(asset) {
+    var key = asset.key;
+    if (!propTemplates[key]) {
+      var url = modelUrlFor(asset.destPath);
+      var promise = loadGlbRaw(url).then(function (gltf) {
+        normalizeToHeight(gltf.scene, asset.targetHeight);
+        return gltf.scene;
+      });
+      promise.catch(function () { delete propTemplates[key]; });
+      propTemplates[key] = promise;
+    }
+    return propTemplates[key];
   }
 
   async function placeProps(propPlacements) {
@@ -544,13 +557,11 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     }
   }
 
-  // ---- items: crumbs and morsels, primitive geometry ------------------------
-  // Doubled from 0.08/0.18: against the fox's own 1m targetHeight and a 1-unit
-  // cell, the old radii read as barely-visible dots on the board.
-  var CRUMB_RADIUS = 0.16, MORSEL_RADIUS = 0.36;
-  function itemGeometryFor(kind) { return new THREE.SphereGeometry(kind === "morsel" ? MORSEL_RADIUS : CRUMB_RADIUS, 10, 8); }
-  function itemMaterialFor(kind) { return new THREE.MeshStandardMaterial({ color: kind === "morsel" ? 0xd98a2b : 0x8c6a3f }); }
-  function itemHeightFor(kind) { return kind === "morsel" ? MORSEL_RADIUS : CRUMB_RADIUS; }
+  // ---- items: crumbs and morsels, the committed hay bale at two target
+  // heights (food-crumb 0.16, food-morsel 0.36 in data/mudiii-assets.json),
+  // matching the on-ground footprint the primitive spheres they replace were
+  // already tuned to. ---------------------------------------------------------
+  function itemAssetKeyFor(kind) { return kind === "morsel" ? "food-morsel" : "food-crumb"; }
 
   function animateScaleTo(object3D, target, now) {
     var duration = tweenDurationMs;
@@ -566,29 +577,55 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     requestAnimationFrame(step);
   }
 
+  // A Group per live item, the same shape ensureAgent uses for agents: the
+  // group is in the scene (and in itemMeshes) synchronously so a second tick
+  // arriving before the GLB resolves finds an existing entry rather than
+  // starting a second load, but stays invisible until the model is in it.
   function applyItemTick(id, item, now) {
     var world = cellToWorld(item.cell, GRID_SIZE, CELL_SIZE);
     if (!world) return;
     var entry = itemMeshes[id];
-    if (!entry) {
-      var mesh = new THREE.Mesh(itemGeometryFor(item.kind), itemMaterialFor(item.kind));
-      mesh.name = "item-" + id;
-      mesh.position.set(world.x, itemHeightFor(item.kind), world.z);
-      mesh.scale.setScalar(0);
-      scene.add(mesh);
-      entry = { mesh: mesh, cell: item.cell, kind: item.kind };
-      itemMeshes[id] = entry;
-      animateScaleTo(mesh, 1, now);
+    if (entry) {
+      entry.cell = item.cell;
+      entry.mesh.position.set(world.x, 0, world.z);
       return;
     }
-    entry.cell = item.cell;
-    entry.mesh.position.set(world.x, itemHeightFor(item.kind), world.z);
+    var group = new THREE.Group();
+    group.name = "item-" + id;
+    group.position.set(world.x, 0, world.z);
+    group.visible = false;
+    scene.add(group);
+    entry = { mesh: group, cell: item.cell, kind: item.kind };
+    itemMeshes[id] = entry;
+    var asset = manifestByKind[itemAssetKeyFor(item.kind)];
+    if (!asset) return;
+    loadPropTemplate(asset).then(function (template) {
+      if (itemMeshes[id] !== entry) return; // removed while the model was still loading
+      var instance = template.clone();
+      instance.position.y = template.position.y;
+      group.add(instance);
+      group.visible = true;
+      group.scale.setScalar(0);
+      animateScaleTo(group, 1, performance.now());
+    }).catch(function (err) {
+      // eslint-disable-next-line no-console
+      console.warn("tmct: an item model failed to load", id, err);
+    });
+  }
+
+  function recordRemoval(kind, id, source) {
+    removalLog.push({ kind: kind, id: id, source: source });
   }
 
-  function removeItem(id, withFlourish) {
+  // source ("ecology" | "diff") is recorded, never branched on — it exists
+  // so an e2e assertion can tell an eaten item's flourish removal apart from
+  // a plain diff no-op, since a vanished mesh alone does not say which path
+  // did the removing.
+  function removeItem(id, withFlourish, source) {
     var entry = itemMeshes[id];
     if (!entry) return;
     delete itemMeshes[id];
+    recordRemoval("item", id, source);
     if (withFlourish) animateScaleTo(entry.mesh, 0, performance.now());
     else if (entry.mesh.parent) entry.mesh.parent.remove(entry.mesh);
   }
@@ -603,7 +640,7 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     var kind = roleOfAgentId(id);
     var entry = {
       group: new THREE.Group(), tween: null, cell: null, facing: agent.facing, role: agent.role,
-      kind: kind, mixer: null, actions: {}, currentClip: null, clipMap: null,
+      kind: kind, mixer: null, actions: {}, currentClip: null, clipMap: null, oneShotAction: null,
     };
     entry.group.visible = false;
     scene.add(entry.group);
@@ -628,6 +665,15 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
   }
 
   function playClip(entry, clipName) {
+    // A one-shot flourish left its own action running at full weight (see
+    // playClipOnce below — fadeIn ramps the NEW action in but never ramps
+    // the old one out on its own, so without this the flourish pose would
+    // keep blending into every clip after it, forever). Fade it out before
+    // any of the guards below can skip the rest of this call.
+    if (entry.oneShotAction) {
+      entry.oneShotAction.fadeOut(0.15);
+      entry.oneShotAction = null;
+    }
     if (!entry.mixer || !clipName || entry.currentClip === clipName) return;
     var next = entry.actions[clipName];
     if (!next) return;
@@ -637,6 +683,28 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     entry.currentClip = clipName;
   }
 
+  // A one-shot version of playClip for a flourish (the predator's own bite
+  // on eat-agent): LoopOnce + clampWhenFinished so the clip plays through and
+  // holds its last pose rather than looping. Never skips a repeat of
+  // entry.currentClip the way playClip does — a flourish must always play,
+  // even if the actor happened to already be on this same clip. Clears
+  // entry.currentClip to null so the next applyAgentTick's own playClip call
+  // is never refused as "already on this clip", and records the action on
+  // entry.oneShotAction so that same next call fades it back out.
+  function playClipOnce(entry, clipName) {
+    if (!entry.mixer || !clipName) return;
+    var action = entry.actions[clipName];
+    if (!action) return;
+    var prev = entry.currentClip && entry.currentClip !== clipName ? entry.actions[entry.currentClip] : null;
+    action.reset();
+    action.setLoop(THREE.LoopOnce, 1);
+    action.clampWhenFinished = true;
+    action.fadeIn(0.15).play();
+    if (prev) prev.fadeOut(0.15);
+    entry.oneShotAction = action;
+    entry.currentClip = null;
+  }
+
   function playSpawnFlourish(group, now) {
     group.scale.setScalar(0);
     animateScaleTo(group, 1, now);
@@ -667,10 +735,11 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     }
   }
 
-  function removeAgent(id) {
+  function removeAgent(id, source) {
     var entry = agentGroups[id];
     if (!entry) return;
     delete agentGroups[id];
+    recordRemoval("agent", id, source);
     var deathClip = entry.clipMap && entry.clipMap.death;
     var deathClipName = Array.isArray(deathClip) ? deathClip[0] : deathClip;
     if (deathClipName) {
@@ -683,10 +752,17 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
 
   function applyEcology(ecology) {
     for (var i = 0; i < (ecology || []).length; i += 1) {
-      var flourish = flourishForEcologyEvent(ecology[i]);
+      var event = ecology[i];
+      var flourish = flourishForEcologyEvent(event);
       if (!flourish) continue;
-      if (flourish.kind === "death") removeAgent(flourish.targetId);
-      else if (flourish.kind === "consume") removeItem(flourish.targetId, true);
+      if (flourish.kind === "death") removeAgent(flourish.targetId, "ecology");
+      else if (flourish.kind === "consume") removeItem(flourish.targetId, true, "ecology");
+      if (flourish.actorId) {
+        var actorEntry = agentGroups[flourish.actorId];
+        if (actorEntry && actorEntry.clipMap) {
+          playClipOnce(actorEntry, clipForAction(actorEntry.role, event.type, actorEntry.clipMap));
+        }
+      }
     }
   }
 
@@ -741,6 +817,7 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     itemMeshes = {};
     lastAgentsById = {};
     lastItemsById = {};
+    removalLog = [];
     manifestByKind = buildManifestByKind(input && input.assetManifest);
     await placeProps((input && input.propPlacements) || []);
     setCamera({ mode: "overhead", selectedId: null });
@@ -754,9 +831,15 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     var items = (tick && tick.items) || {};
     for (var id in agents) if (Object.prototype.hasOwnProperty.call(agents, id)) applyAgentTick(id, agents[id], now);
     for (var itemId in items) if (Object.prototype.hasOwnProperty.call(items, itemId)) applyItemTick(itemId, items[itemId], now);
-    for (var goneAgent in lastAgentsById) if (!(goneAgent in agents)) removeAgent(goneAgent);
-    for (var goneItem in lastItemsById) if (!(goneItem in items)) removeItem(goneItem, false);
+    // Ecology first: an eaten agent/item is already gone from this tick's own
+    // agents/items map, so applyEcology's own removeAgent/removeItem call is
+    // what actually removes it (with its flourish). The two diff loops below
+    // then find that id already deleted and no-op — removeAgent/removeItem
+    // both delete their map entry before anything else, so a second call for
+    // the same id returns immediately.
     applyEcology(tick && tick.ecology);
+    for (var goneAgent in lastAgentsById) if (!(goneAgent in agents)) removeAgent(goneAgent, "diff");
+    for (var goneItem in lastItemsById) if (!(goneItem in items)) removeItem(goneItem, false, "diff");
     lastAgentsById = agents;
     lastItemsById = items;
     refreshCameraTween(now);
@@ -812,6 +895,15 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
       var asset = manifestByKind[entry.kind];
       return { height: size.y, minY: box.min.y, targetHeight: asset ? asset.targetHeight : null };
     },
+    // Every removal recorded for id, oldest first — each entry's own
+    // source is "ecology" (an eat/starve flourish removed it) or "diff"
+    // (applyTick found it missing from a tick's own agents/items map with no
+    // ecology event driving that). An e2e assertion's read.
+    removalsFor: function (id) {
+      var out = [];
+      for (var i = 0; i < removalLog.length; i += 1) if (removalLog[i].id === id) out.push(removalLog[i]);
+      return out;
+    },
     ready: function () { return booted; },
   };
 })();`;

package/src/services/mudiii-turn.mjs

@@ -14,13 +14,15 @@
 
 import {
   TOWN_SQUARE_LAYOUTS, DEFAULT_GRID_SIZE, DIRECTION_DELTA,
-  cellId, parseCellId, inBounds, chebyshevDistance, oneStepDirectionBetween,
-  agentKindOf, liveIdsOfKind, layoutNamed,
+  cellId, parseCellId, inBounds, isSolid, chebyshevDistance, oneStepDirectionBetween,
+  agentKindOf, liveIdsOfKind, layoutNamed, isFoodId,
 } from "../domain/town-square-world.mjs";
 import {
   MUDIII_ROLES, foldTownSquareState, startTownSquareGame, runTownSquareTick,
   placeFood, roleOfId, beliefSnapshotFor,
 } from "./predator-prey.mjs";
+import { snapshotSubject } from "./adventure.mjs";
+import { correctMisspellings, QUESTION_LEAD_RE } from "../domain/interpret/normalize.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";
@@ -88,6 +90,25 @@ const MUDIII_TOLD_RE = new RegExp(
 // never ground truth.
 const MUDIII_SEE_RE = /^what (?:does|can) the (fox|goblin)(?:-(\d+))?\s+see[.!?\s]*$/i;
 
+// "who put/placed that there?" — provenance, ground truth (not belief), read
+// from placeFood's own mgx:placed-by row. The subject must be named, either
+// an item id ("who put morsel-1 there?") or a cell ("who put food at
+// cell-3-4?") — a bare "who put that there?" with no referent at all names
+// nothing to look up and is left to the ordinary lanes. Requires the leading
+// "who put/placed/dropped" verb, so it never collides with an unrelated "who"
+// question (the fox's own catches, the goblins' names, anything not about a
+// placement) — those never start with this verb at all.
+const MUDIII_WHO_PLACED_RE = new RegExp(
+  "^who\\s+(?:put|placed|dropped)\\s+"
+  + "(?:"
+  + "(?:the\\s+)?(morsel|crumb)(?:-(\\d+))?"
+  + "|"
+  + "(?:(?:the\\s+)?(?:food|morsel|crumb|that|it)\\s+)?(?:at|on)\\s+(cell-\\d+-\\d+)"
+  + ")"
+  + "(?:\\s+there)?[?.!\\s]*$",
+  "i",
+);
+
 // The player's own verb: "put food at cell-3-4" (primary, never shadowed —
 // the adventure imperative grammar's own "put" arm hard-requires a literal
 // "in", so "at" never parses there) and "drop a morsel at cell-3-4"
@@ -441,6 +462,63 @@ async function mudiiiBeliefAnswer(match, { memoryDir, gameConfig = DEFAULT_GAME_
   };
 }
 
+function noLivePlacedSubjectAnswer(kind) {
+  return {
+    text: `there's no live ${kind} on the board for that to be about.`,
+    lane: "game-inform",
+    note: `MUDIII — who-placed declined: no live ${kind} resolves`,
+    miss: true,
+  };
+}
+
+/** "who put/placed <item|cell> there?": ground truth read off the folded
+ *  state's own placedBy Map (predator-prey.mjs's fold of every mgx:placed-by
+ *  row), never belief. Resolves the subject the same way the told-fact and
+ *  see recognizers already do — resolveAgentId for a named item, a direct
+ *  placements scan for a cell — then declines, naming the reason, when the
+ *  item isn't on the board at all or is on the board but carries no placedBy
+ *  row (spawned food never does; placeFood is the only writer of that row). */
+async function mudiiiWhoPlacedAnswer(match, { memoryDir }) {
+  const [, kindRaw, num, cellLiteral] = match;
+  const rows = readFactRows(await loadMemory(memoryDir));
+  const state = foldTownSquareState(rows);
+
+  let itemId = null;
+  if (kindRaw) {
+    itemId = resolveAgentId(kindRaw.toLowerCase(), num, state);
+  } else {
+    const entry = [...state.placements.entries()].find(([id, place]) =>
+      isFoodId(id) && !state.removed.has(id) && place.cell === cellLiteral);
+    itemId = entry ? entry[0] : null;
+  }
+
+  if (!itemId) {
+    if (kindRaw) return noLivePlacedSubjectAnswer(kindRaw.toLowerCase());
+    return {
+      text: `there's no food at ${cellLiteral} to ask about.`,
+      lane: "game-inform",
+      note: `MUDIII — who-placed declined: no live food item sits at ${cellLiteral}`,
+      miss: true,
+    };
+  }
+
+  const placed = state.placedBy.get(itemId);
+  if (!placed) {
+    return {
+      text: `${itemId} was never placed — it spawned on its own.`,
+      lane: "game-inform",
+      note: `MUDIII — who-placed declined: ${itemId} carries no mgx:placed-by row (spawned food)`,
+      miss: true,
+    };
+  }
+
+  return {
+    text: `${placed.by} put ${itemId} at ${state.placements.get(itemId).cell}.`,
+    lane: "game-inform",
+    note: `MUDIII — who-placed answered from state.placedBy for ${itemId}`,
+  };
+}
+
 /** The addressed teach-frame turn: resolve the addressee and the belief
  *  subject (an agent OR a food item), resolve the told cell, and run ONE tick
  *  with that told-fact fed in. Told-facts are not persisted across turns —
@@ -477,6 +555,242 @@ async function runToldFactTurn(match, { planHolder, memoryDir, cache, gameConfig
   });
 }
 
+// ---- the teach lane: a declarative sentence read as a board fact -------------
+//
+// The town square's own half of the world-teach act world-teach.mjs performs
+// for a manor and a burrow, and shaped the same way: a small closed sentence
+// table, one additive planner over the live fold, and a "noted — … now."
+// confirmation carrying the same `world:<name>:taught:turnK` provenance.
+//
+// It stays here rather than routing through world-teach.mjs because that
+// module's gates are written for a ROOM world. It declines by naming rooms,
+// mints a fresh portable when the subject is one the world has never heard
+// of, and plans against foldWorldState. A board has cells instead of rooms
+// and one fold of its own, and nothing here ever mints: every subject must
+// already resolve to a live individual foldTownSquareState folds, or the
+// write would put a fact on the board that the board cannot draw.
+
+const PLACEMENT_PREDICATE = "mgx:currently-in";
+const MASS_PREDICATE = "mgx:hasMass";
+const MOOD_PREDICATE = "mgx:feels";
+const FACING_PREDICATE = "mgx:facing";
+const PLACED_BY_PREDICATE = "mgx:placed-by";
+
+// The families foldTownSquareState ranks by (epoch, turn). A row in one of
+// them needs a snapshot subject or it ranks as turn 0 and loses to anything
+// already played about the same thing. mgx:placed-by is read raw and keeps
+// its bare subject, exactly as placeFood writes it.
+const TAUGHT_SNAPSHOT_PREDICATES = new Set([
+  PLACEMENT_PREDICATE, MASS_PREDICATE, MOOD_PREDICATE, FACING_PREDICATE,
+]);
+
+// The closed cast vocabulary a taught sentence may name, matching the lane's
+// own recognizers above. Mood and facing take an agent alone — a crumb has
+// neither — while a cell and a weight are true of an inert item too.
+const CAST_SUBJECT = "(fox|goblin|crumb|morsel)(?:-(\\d+))?";
+const AGENT_SUBJECT = "(fox|goblin)(?:-(\\d+))?";
+const ITEM_SUBJECT = "(crumb|morsel)(?:-(\\d+))?";
+
+/**
+ * The town square's sentence table: every fact about this board a person can
+ * state, one row per predicate the fold reads. Checked in order, first match
+ * wins.
+ *
+ *   Fox-1 is at cell-3-4.            mgx:currently-in
+ *   The goblin weighs 4.             mgx:hasMass
+ *   The fox feels angry.             mgx:feels
+ *   Goblin-2 faces north.            mgx:facing
+ *   The baker put morsel-1 there.    mgx:placed-by
+ *
+ * A bare kind ("the fox") names whichever individual of that kind is live and
+ * lowest-numbered; a numbered id names exactly one. Closed on both sides: a
+ * mood or a direction outside the engine's own words does not parse at all,
+ * so nothing here can write a value a renderer has no drawing for.
+ */
+const TOWN_SQUARE_TEACH_PATTERNS = [
+  { kind: "placement", predicate: PLACEMENT_PREDICATE,
+    re: new RegExp(`^(?:the\\s+)?${CAST_SUBJECT}\\s+is\\s+at\\s+(cell-\\d+-\\d+)[.!\\s]*$`, "i") },
+  { kind: "mass", predicate: MASS_PREDICATE,
+    re: new RegExp(`^(?:the\\s+)?${CAST_SUBJECT}\\s+weighs\\s+(\\d+(?:\\.\\d+)?)[.!\\s]*$`, "i") },
+  { kind: "mood", predicate: MOOD_PREDICATE,
+    re: new RegExp(`^(?:the\\s+)?${AGENT_SUBJECT}\\s+feels\\s+(calm|angry|scared|happy)[.!\\s]*$`, "i") },
+  { kind: "facing", predicate: FACING_PREDICATE,
+    re: new RegExp(`^(?:the\\s+)?${AGENT_SUBJECT}\\s+faces\\s+(north|south|east|west)[.!\\s]*$`, "i") },
+];
+
+// The one sentence whose subject is not its leading noun: the item is the
+// subject and the placer is the object, which is the direction "who put that
+// there?" reads the row back in.
+const TOWN_SQUARE_PLACED_BY_RE = new RegExp(
+  `^(?:the\\s+)?([a-z][a-z-]*)\\s+(?:put|placed|dropped)\\s+(?:the\\s+)?${ITEM_SUBJECT}\\s+there[.!\\s]*$`,
+  "i",
+);
+
+/** One line -> `{ kind, predicate, kindWord, num, object }`, or null when the
+ *  table recognizes nothing — an honest miss, never a guessed shape.
+ *  `kindWord`/`num` name the individual the sentence is about; the caller
+ *  resolves that pair against the live board. Pure. */
+export function parseTownSquareTeachLine(line) {
+  const trimmed = String(line || "").trim();
+  if (!trimmed) return null;
+  for (const { kind, predicate, re } of TOWN_SQUARE_TEACH_PATTERNS) {
+    const m = trimmed.match(re);
+    if (!m) continue;
+    return { kind, predicate, kindWord: m[1].toLowerCase(), num: m[2] ?? null, object: m[3].toLowerCase() };
+  }
+  const placed = trimmed.match(TOWN_SQUARE_PLACED_BY_RE);
+  if (!placed) return null;
+  return {
+    kind: "placed-by", predicate: PLACED_BY_PREDICATE,
+    kindWord: placed[2].toLowerCase(), num: placed[3] ?? null, object: placed[1].toLowerCase(),
+  };
+}
+
+/**
+ * The rows one already-resolved taught triple implies against the board's
+ * current fold — the town square's counterpart to mud-editor.mjs's
+ * planTaughtMudTriple, and additive for the same reason: one sentence only
+ * ever says what it says, so nothing it leaves out is evidence of anything.
+ * Re-asserting a fact the board already holds appends nothing, and `reason`
+ * says which of the two happened.
+ *
+ * Takes the fold alone rather than the raw rows its burrow counterpart also
+ * needs: every family this table can say is one foldTownSquareState folds, so
+ * there is no raw-row family left to diff against. Pure.
+ */
+export function planTaughtTownSquareTriple(state, triple) {
+  if (!triple?.subject || !triple?.object) return { toAppend: [], reason: "nothing parsed" };
+  const { subject, object } = triple;
+  switch (triple.kind) {
+    case "placement": {
+      const current = state?.placements?.get(subject);
+      if (current?.cell === object) return { toAppend: [], reason: `${subject} already stands at ${object}` };
+      return {
+        toAppend: [triple],
+        reason: current ? `${subject} moves from ${current.cell} to ${object}` : `${subject} is placed at ${object}`,
+      };
+    }
+    case "mass": {
+      const current = state?.mass?.get(subject);
+      if (current && Number(current.value) === Number(object)) return { toAppend: [], reason: `${subject} already weighs ${object}` };
+      return { toAppend: [triple], reason: `${subject} weighs ${object}` };
+    }
+    case "mood": {
+      const current = state?.mood?.get(subject);
+      if (current?.value === object) return { toAppend: [], reason: `${subject} already feels ${object}` };
+      return { toAppend: [triple], reason: `${subject} feels ${object}` };
+    }
+    case "facing": {
+      const current = state?.facing?.get(subject);
+      if (current?.value === object) return { toAppend: [], reason: `${subject} already faces ${object}` };
+      return { toAppend: [triple], reason: `${subject} faces ${object}` };
+    }
+    case "placed-by": {
+      const current = state?.placedBy?.get(subject);
+      if (current?.by === object) return { toAppend: [], reason: `${object} already put ${subject} there` };
+      return { toAppend: [triple], reason: `${object} put ${subject} there` };
+    }
+    default:
+      return { toAppend: [], reason: `the board folds nothing for ${triple.predicate}` };
+  }
+}
+
+/** One taught triple as the sentence the board says back, in world-teach.mjs's
+ *  own `noted — … now.` shape. Pure. */
+export function townSquareTeachConfirmation(triple) {
+  switch (triple.kind) {
+    case "placement": return `noted — ${triple.subject} is at ${triple.object} now.`;
+    case "mass": return `noted — ${triple.subject} weighs ${triple.object} now.`;
+    case "mood": return `noted — ${triple.subject} feels ${triple.object} now.`;
+    case "facing": return `noted — ${triple.subject} faces ${triple.object} now.`;
+    case "placed-by": return `noted — the ${triple.object} put ${triple.subject} there now.`;
+    default: return "noted — the board says that now.";
+  }
+}
+
+const teachDecline = (text, note) => ({ text, lane: "game-answer", note: `MUDIII — world-teach: ${note}`, miss: true });
+
+/**
+ * One line read as a fact about the LIVE board, or null when it is not a
+ * teach sentence at all and the ordinary lane should have it. Writes the
+ * fold-versioned families under a snapshot subject stamped at the next tick's
+ * own turn number, the same convention placeFood uses so a teach and the tick
+ * that resolves it share one turn rather than the teach quietly spending one.
+ *
+ * Nobody moves in response: a taught fact never runs the ecology pass, which
+ * is the same trade world-teach.mjs makes for a manor.
+ */
+async function mudiiiTeachTurn(line, { memoryDir, cache, world, layout }) {
+  const trimmed = String(line || "").trim();
+  if (!trimmed || !memoryDir) return null;
+  // A trailing "?" is an unambiguous question, and a leading interrogative is
+  // the same signal one word earlier — a question must never reach a write
+  // boundary. Both mirror world-teach.mjs, which stands down on either.
+  if (/\?\s*$/.test(trimmed)) return null;
+  if (QUESTION_LEAD_RE.test(correctMisspellings(trimmed))) return null;
+
+  const parsed = parseTownSquareTeachLine(trimmed);
+  if (!parsed) return null;
+
+  const rows = readFactRows(await loadMemory(memoryDir));
+  const state = foldTownSquareState(rows);
+  const subject = resolveAgentId(parsed.kindWord, parsed.num, state);
+  if (!subject) {
+    return teachDecline(
+      `there's no live ${parsed.kindWord} on the board for that to be about.`,
+      `"${trimmed}" is about a ${parsed.kindWord} nothing live answers to; declined rather than minting one the board cannot draw`,
+    );
+  }
+
+  if (parsed.kind === "placement") {
+    const cell = parseCellId(parsed.object);
+    if (!cell || !inBounds(layout.gridSize, cell.x, cell.y)) {
+      return teachDecline(
+        `${parsed.object} is off the board — this square runs cell-1-1 to cell-${layout.gridSize}-${layout.gridSize}.`,
+        `"${trimmed}" names a cell outside the ${layout.gridSize}x${layout.gridSize} board`,
+      );
+    }
+    if (isSolid(layout, parsed.object)) {
+      return teachDecline(
+        `${parsed.object} is blocked — nothing stands inside a building.`,
+        `"${trimmed}" would stand ${subject} on a prop cell, which no path ever reaches`,
+      );
+    }
+  }
+
+  const triple = { subject, predicate: parsed.predicate, object: parsed.object, kind: parsed.kind };
+  const { toAppend, reason } = planTaughtTownSquareTriple(state, triple);
+  if (!toAppend.length) {
+    return {
+      text: "the board already says that.",
+      lane: "game-answer",
+      miss: false,
+      note: `MUDIII — world-teach: "${trimmed}" asserts a fact the board already holds (${reason}); nothing written`,
+      taught: [],
+    };
+  }
+
+  const k = state.tickCount + 1;
+  const epoch = state.epoch;
+  const facts = toAppend.map((t) => ({
+    subject: TAUGHT_SNAPSHOT_PREDICATES.has(t.predicate) ? snapshotSubject(t.subject, k, epoch) : t.subject,
+    predicate: t.predicate,
+    object: t.object,
+  }));
+  const provenance = `${worldProvenanceTag(world)}:taught:turn${k}`;
+  await appendFacts(memoryDir, facts.map((f) => ({ ...f, provenance })));
+  if (cache) cache.rows = null;
+
+  return {
+    text: townSquareTeachConfirmation(triple),
+    lane: "game-answer",
+    miss: false,
+    goal: `change what the board says about ${subject}`,
+    note: `MUDIII — world-teach: ${reason}; wrote ${facts.length} row(s) at turn ${k} with provenance ${provenance}; no tick rides a taught fact`,
+    taught: facts,
+  };
+}
+
 // ---- in-game orientation asides ---------------------------------------------
 //
 // "where is the fox", "where am I", "what can I do", "what is the fox's
@@ -632,6 +946,17 @@ export async function mudiiiTurn(line, { planHolder, memoryDir, env, cache = nul
     return runPlaceFoodTurn(putMatch[1], { memoryDir, gameConfig, world: mudiii.world, layout });
   }
 
+  // The teach switch runs before the plan-frame guard for the same reason the
+  // food verb does: "the fox is at cell-3-4" reads as a planning frame on its
+  // leading noun, and answering a sentence this lane's own table accepts with
+  // "stop watching, then set your goal" refuses the one thing the switch is
+  // for. With the switch off nothing here runs and the lane behaves exactly
+  // as it always has.
+  if (gameConfig?.mudiii?.teach) {
+    const taught = await mudiiiTeachTurn(trimmed, { memoryDir, cache, world: mudiii.world, layout });
+    if (taught) return taught;
+  }
+
   if (isPlanFrameLine(line)) {
     return {
       text: 'the town square game is running — say "stop watching" to end it, then set your goal.',
@@ -659,6 +984,11 @@ export async function mudiiiTurn(line, { planHolder, memoryDir, env, cache = nul
     return mudiiiBeliefAnswer(seeMatch, { memoryDir, gameConfig });
   }
 
+  const whoPlacedMatch = trimmed.match(MUDIII_WHO_PLACED_RE);
+  if (whoPlacedMatch) {
+    return mudiiiWhoPlacedAnswer(whoPlacedMatch, { memoryDir });
+  }
+
   if (MUDIII_TICK_RE.test(line)) {
     return runTickAndRender({ planHolder, memoryDir, cache, world: mudiii.world, toldFacts: [], gameConfig });
   }