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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "5.0.4",
+  "version": "5.0.5",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; indexes a repo on request (tmct index) or reads any producer's graph.",

package/src/adapters/memory/core.mjs

@@ -50,6 +50,7 @@ import {
   planRetraction, mergeRetractions, retractionFromWire, retractionWireFact,
   isRetractedRecord, RETRACTION_CLASS,
 } from "../../domain/memory/retraction.mjs";
+import { admittedNodes, stableRecordIds } from "../../domain/memory/causal-stability.mjs";
 import { assertIndividualValid } from "./shacl.mjs";
 
 // The rollup vocabulary and its tuning constants live with the compaction
@@ -70,6 +71,8 @@ export {
   retractedRecordIds, retractedAtOf, retractionWireFact, retractionFromWire,
 } from "../../domain/memory/retraction.mjs";
 
+export { admittedNodes, peersToConvince, stableRecordIds } from "../../domain/memory/causal-stability.mjs";
+
 export const MEMORY_DIR_REL = join(".tmct", "memory");
 export const MEMORY_GRAPH_REL = join(MEMORY_DIR_REL, "graph.json");
 
@@ -3189,6 +3192,56 @@ export async function appendRetractions(dir, wireFacts) {
   return { merged: incoming.length, removed };
 }
 
+/** What this store could retire, and the roster it has to convince first.
+ *
+ *  `roster` is the world's admission graph, folded to a set of node ids —
+ *  replicated, grow-only, and the same on every peer holding the same facts.
+ *  `retirable` is the tombstones every peer on that roster is known to hold.
+ *  `acknowledgedBy(nodeId)` is what supplies that evidence; nothing produces it
+ *  yet, so `retirable` reads empty and this is a report rather than a sweep.
+ *  Retiring nothing is the current behaviour, and it is the safe one: a
+ *  tombstone dropped one peer early lets that peer's copy resurrect a retracted
+ *  fact. See docs/references/papers/crdt.md. */
+export function retirableRetractions(memory, { self = "", acknowledgedBy = null } = {}) {
+  const roster = admittedNodes(readFactRows(memory));
+  const recordIds = [];
+  for (const ind of memory?.individuals || []) {
+    if (ind?.class === RETRACTION_CLASS && ind.id) recordIds.push(ind.id);
+  }
+  return { roster, retirable: stableRecordIds({ recordIds, roster, self, acknowledgedBy }) };
+}
+
+/** Drop named retraction records. Takes the ids rather than choosing them, so a
+ *  caller has to have run the stability rule and passed its answer; ids that are
+ *  not retraction records are skipped. Returns the ids that went. */
+export async function retireRetractions(dir, ids) {
+  const asked = new Set((ids || []).filter(Boolean));
+  const retired = [];
+  if (!asked.size) return { retired };
+  await mutateMemory(dir, (payload) => {
+    const drop = new Set();
+    payload.individuals = (payload.individuals || []).filter((ind) => {
+      if (ind?.class !== RETRACTION_CLASS || !asked.has(ind.id)) return true;
+      drop.add(ind.id);
+      return false;
+    });
+    if (!drop.size) return;
+    for (const id of drop) retired.push(id);
+    const idx = memoryIndexOf(payload);
+    if (idx) {
+      for (const id of drop) {
+        idx.individualsById.delete(id);
+        const groupId = factGroupId(id);
+        const held = (idx.retractionsByGroup.get(groupId) || []).filter((r) => !drop.has(r.id));
+        if (held.length) idx.retractionsByGroup.set(groupId, held);
+        else idx.retractionsByGroup.delete(groupId);
+      }
+    }
+    recountClasses(payload);
+  });
+  return { retired };
+}
+
 /** The trust floor a fact must clear before a differing object counts as a real
  *  contradiction (below it the fact is too weak to contradict anything). */
 const CONTRADICTION_TRUST_FLOOR = 0.5;

package/src/domain/game-config.mjs

@@ -90,6 +90,11 @@ export const DEFAULT_GAME_CONFIG = Object.freeze({
     // this is the one switch that turns that off (visionRadius: Infinity for
     // the food-only belief call) without any new belief machinery.
     foodVisionGated: true,
+    // Whether the town-square lane accepts teaching. Its own knob rather than
+    // a share of the adventure one below: the board's sentence table is a
+    // different vocabulary, and a page checkbox on the town square should not
+    // have to set a key named after another surface.
+    teach: false,
   }),
   guessNumber: Object.freeze({
     defaultLo: 1,
@@ -161,6 +166,7 @@ const MUDIII_KEY_MAP = Object.freeze({
   max_prey_population: "maxPreyPopulation",
   max_food_items: "maxFoodItems",
   food_vision_gated: "foodVisionGated",
+  teach: "teach",
 });
 
 const ADVENTURE_KEY_MAP = Object.freeze({

package/src/domain/memory/causal-stability.mjs

@@ -0,0 +1,82 @@
+// memory/causal-stability.mjs — deciding when a replicated tombstone has been
+// held by enough peers to retire.
+//
+// A retraction record and a compaction summary both work by staying put: they
+// carry the ids they suppressed, and any peer that re-delivers one of those ids
+// gets refused. That is what makes a delete survive a sync over a grow-only
+// set. It also means the records accumulate, because nothing yet says when one
+// has done its job.
+//
+// The literature calls the missing rule CAUSAL STABILITY: a record is safe to
+// drop once every replica that could still send a conflicting copy has it. Two
+// inputs, and the mesh has one of them.
+//
+//   - The ROSTER. `node:<joiner> mgx:invitedBy node:<inviter>` is an ordinary
+//     replicated fact, so the set of node ids ever admitted to a world is a
+//     grow-only union every peer computes the same way. `admittedNodes` reads
+//     it. Grow-only is exactly right here: a roster that could shrink would let
+//     a forgotten node's stale copy back in.
+//   - The ACKNOWLEDGEMENT. Nothing yet records that a named node holds a named
+//     record. `stableRecordIds` takes it as an argument rather than inventing
+//     it, and answers "nothing is stable" when it is absent — which is the
+//     current answer, and the safe one.
+//
+// Every rule here errs the same way. Dropping a tombstone one peer short lets
+// that peer's copy resurrect a retracted fact, and that failure is silent,
+// late, and reads as the memory inventing something. Retiring nothing is
+// merely unbounded. So: an empty roster retires nothing, a member with no
+// acknowledgement retires nothing, and an unparseable input retires nothing.
+//
+// Pure: no clock, no counter, no arrival order. The answer is a function of the
+// fact set and the acknowledgement evidence handed in, which is the same
+// invariant every read-time resolver over the store has to meet.
+// docs/references/papers/crdt.md carries the full design and the options it
+// rejected.
+import { INVITED_BY_PREDICATE } from "../p2p/facts.mjs";
+
+/** The node ids a world has ever admitted, from its admission edges. Both ends
+ *  of each edge count: the joiner wrote the edge about itself, and it names the
+ *  node that let it in. Sorted, so two peers holding the same facts hand the
+ *  same roster to the rule below. */
+export function admittedNodes(rows) {
+  const nodes = new Set();
+  for (const row of rows || []) {
+    if (row?.predicate !== INVITED_BY_PREDICATE) continue;
+    if (row.subject) nodes.add(String(row.subject));
+    if (row.object) nodes.add(String(row.object));
+  }
+  return [...nodes].sort();
+}
+
+/** The roster this node has to convince before retiring anything: every
+ *  admitted node except itself. A node holding its own record proves nothing
+ *  about who else still has a copy. */
+export function peersToConvince(roster, self = "") {
+  const me = String(self || "");
+  return (roster || []).map(String).filter((id) => id && id !== me);
+}
+
+/**
+ * Which of `recordIds` every peer on the roster is known to hold.
+ *
+ * `acknowledgedBy(nodeId)` returns the record ids that node is known to hold.
+ * Nothing supplies it in the product yet, so it defaults to knowing nothing and
+ * the answer defaults to the empty set. That default is the gate: this rule
+ * cannot retire anything until something can show a peer holds a record.
+ *
+ * An empty roster answers with nothing too. A store with no admission edges has
+ * not shown it is alone; it has shown it does not know who else is out there,
+ * and a copy of it can be sitting in a closed browser tab.
+ */
+export function stableRecordIds({ recordIds = [], roster = [], self = "", acknowledgedBy = null } = {}) {
+  const peers = peersToConvince(roster, self);
+  if (!peers.length) return [];
+  if (typeof acknowledgedBy !== "function") return [];
+  const held = new Map();
+  for (const peer of peers) {
+    const ids = acknowledgedBy(peer);
+    held.set(peer, new Set([...(ids || [])].map(String)));
+  }
+  const candidates = [...new Set((recordIds || []).map(String).filter(Boolean))].sort();
+  return candidates.filter((id) => peers.every((peer) => held.get(peer).has(id)));
+}

package/src/domain/town-square-world.mjs

@@ -82,6 +82,42 @@ export function oneStepDirectionBetween(fromCell, toCell) {
   return null;
 }
 
+/** The eight points a facing may take, clockwise from north. The four
+ *  cardinals are DIRECTION_DELTA's own keys, and they are the only ones a STEP
+ *  can use — the grid has no diagonal exits. The four intercardinals are
+ *  turn-only, which is what a forty-five degree turn on the spot writes. */
+export const COMPASS_POINTS = Object.freeze([
+  "north", "northeast", "east", "southeast", "south", "southwest", "west", "northwest",
+]);
+
+/** `facing` turned `degrees` clockwise (a negative angle turns the other way),
+ *  landing on one of COMPASS_POINTS. Null when `facing` isn't a compass point
+ *  or the angle isn't a whole multiple of 45, so a caller refuses rather than
+ *  rounding a nonsense turn into a real one. Pure. */
+export function turnedFacing(facing, degrees) {
+  const at = COMPASS_POINTS.indexOf(String(facing ?? ""));
+  if (at < 0) return null;
+  if (!Number.isInteger(degrees) || degrees % 45 !== 0) return null;
+  const steps = degrees / 45;
+  return COMPASS_POINTS[(((at + steps) % 8) + 8) % 8];
+}
+
+/** The compass point directly behind `facing`, or null. Pure. */
+export function reverseFacing(facing) {
+  return turnedFacing(facing, 180);
+}
+
+/** The cell one step `direction` from `cell`, or null when `direction` names
+ *  no cardinal step or `cell` doesn't parse. Bounds and props are NOT checked
+ *  here: whether that cell can actually be entered is the exit table's answer,
+ *  and there is only one of those. Pure. */
+export function stepCellFrom(cell, direction) {
+  const at = parseCellId(cell);
+  const delta = DIRECTION_DELTA[String(direction ?? "")];
+  if (!at || !delta) return null;
+  return cellId(at.x + delta.dx, at.y + delta.dy);
+}
+
 // ---- the prop vocabulary ------------------------------------------------------
 
 /** The closed set of noun stems a prop id may use ("house-1" -> "house"). A

package/src/services/mudiii-turn.mjs

@@ -14,13 +14,15 @@
 
 import {
   TOWN_SQUARE_LAYOUTS, DEFAULT_GRID_SIZE, DIRECTION_DELTA,
-  cellId, parseCellId, inBounds, chebyshevDistance, oneStepDirectionBetween,
+  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";
@@ -553,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
@@ -708,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.',