@polycode-projects/the-mechanical-code-talker 4.1.8 → 5.0.0

package/src/services/spider-fly.mjs

@@ -4,16 +4,21 @@
 // rows through the shared memory store. No chat, no rendering — a later
 // piece of work wraps runSpiderFlyTick's return shape for a chat turn.
 //
-// Grid geometry (cellId, parseCellId, visibleCells, isInWebBlock,
+// Grid geometry (cellId, parseCellId, chebyshevDistance, isInWebBlock,
 // perimeterCells, DIRECTION_DELTA) is never redefined here — it all comes
 // from spider-fly-world.mjs, the one source of truth both the shipped world
-// pack and this engine read from.
+// pack and this engine read from. Vision-gated belief is the same deal: it
+// lives in the board-size-agnostic domain/agent-belief.mjs and is re-exported
+// below, so this file's public surface is unchanged by where it sits.
 
 import {
   WORLD_NAME, WEB_HOME, WEB_DURATION_TURNS, SPIDER_INITIAL_MASS, SPIDER_MASS_DECREMENT_PER_TURN,
-  cellId, parseCellId, chebyshevDistance, visibleCells, isInWebBlock, perimeterCells,
+  cellId, parseCellId, chebyshevDistance, isInWebBlock, perimeterCells,
   DIRECTION_DELTA, oneStepDirectionBetween,
 } from "../domain/spider-fly-world.mjs";
+import {
+  DEFAULT_VISION_RADIUS, believedCellOf, nearestBelievedTarget, beliefSnapshotFor,
+} from "../domain/agent-belief.mjs";
 import { findActionPath, findReachableSet } from "../domain/planning.mjs";
 import { appendFacts, loadMemory, readFactRows } from "../adapters/memory/core.mjs";
 import { worldProvenanceTag } from "../domain/worlds-pack.mjs";
@@ -24,7 +29,6 @@ import { DEFAULT_GAME_CONFIG } from "../domain/game-config.mjs";
 // ---- tunable constants (starting values, not fixed — the vision radius and
 // mass economy all want checking against a real playable board) -------------
 
-export const DEFAULT_VISION_RADIUS = 4;
 export const FLY_INITIAL_MASS = 10;
 export const FLY_MASS_DECREMENT_PER_TURN = 1;
 export const EGG_HATCH_DELAY_TURNS = 3;
@@ -33,6 +37,7 @@ export const EGG_LAY_MASS_THRESHOLD = 25;
 export const EGG_HATCH_COUNT = 2;
 export const MIN_HATCHLING_MASS = 3;
 export { SPIDER_INITIAL_MASS, SPIDER_MASS_DECREMENT_PER_TURN, WEB_DURATION_TURNS };
+export { DEFAULT_VISION_RADIUS, believedCellOf, nearestBelievedTarget, beliefSnapshotFor };
 
 // ---- seeded "randomness" (never Math.random) ---------------------------------
 // Every "random" decision (fly wander, fly/spawn placement) is a mulberry32
@@ -316,45 +321,11 @@ export function greedySpiderAvoid(spiderCell, believedOtherSpiderCell, applyActi
 }
 
 // ---- visibility and belief (§4): static grid topology is common knowledge
-// to both agents; only dynamic entity positions are gated by vision. A told
-// fact (a later chat-integration piece of work, not built here) is the one
-// extension point this function leaves open via its optional toldFacts
-// parameter — shaped { subject, toAgent, cell, turn }, defaulting to empty
-// so today's belief is exactly "what's currently visible." -------------------
-
-/** Whether `observerSubject` currently believes `targetSubject` to be at a
- *  particular cell: ground truth when the target's real cell is within the
- *  observer's own visibleCells radius, else the newest told fact addressed
- *  to this observer about this target, else null (unknown). A removed
- *  target (eaten/starved/hatched) is never believed present. */
-export function believedCellOf(targetSubject, observerSubject, observerCell, state, opts = {}) {
-  const { visionRadius = DEFAULT_VISION_RADIUS, toldFacts = [] } = opts;
-  const place = state.placements.get(targetSubject);
-  if (place && !state.removed.has(targetSubject)) {
-    const seen = visibleCells(observerCell.x, observerCell.y, visionRadius);
-    if (seen.includes(place.cell)) return parseCellId(place.cell);
-  }
-  const told = toldFacts
-    .filter((f) => f.toAgent === observerSubject && f.subject === targetSubject)
-    .sort((a, b) => (b.turn ?? 0) - (a.turn ?? 0))[0];
-  return told ? parseCellId(told.cell) : null;
-}
-
-/** The nearest candidate (by believed Chebyshev distance) an observer has
- *  any belief about at all — null when the observer believes nothing about
- *  any candidate. `candidates` must already be in a deterministic order
- *  (ties favor the earlier candidate). */
-export function nearestBelievedTarget(observerSubject, observerCell, candidates, state, opts = {}) {
-  let best = null;
-  let bestDist = Infinity;
-  for (const subject of candidates) {
-    const cell = believedCellOf(subject, observerSubject, observerCell, state, opts);
-    if (!cell) continue;
-    const dist = chebyshevDistance(observerCell.x, observerCell.y, cell.x, cell.y);
-    if (dist < bestDist) { bestDist = dist; best = { subject, cell }; }
-  }
-  return best;
-}
+// to both agents; only dynamic entity positions are gated by vision, in
+// domain/agent-belief.mjs (imported and re-exported above). A told fact —
+// shaped { subject, toAgent, cell, turn } — is the chat-integration channel
+// into it, defaulting to empty so belief with no chat is exactly "what's
+// currently visible." --------------------------------------------------------
 
 // ---- the ecology pass (§10): catch, eat, lay, hatch, spawn, starve, all as
 // ordinary turn-gated checks in one fixed-order pass. Order matters and is
@@ -656,27 +627,6 @@ function stepPlan(fromCell, toCell) {
   return direction ? [direction] : [];
 }
 
-/** A full "world knowledge graph" snapshot for one observer this tick: every
- *  OTHER named candidate's believed cell (believedCellOf — ground truth
- *  inside vision, else the newest told fact addressed to this observer,
- *  else null for "unknown") — feeds a per-agent belief panel. Deliberately
- *  never ground truth: showing the observer's own honest gap
- *  between belief and reality (visibly widened by a deceiving pill or a fed
- *  false fact) is the whole point of that panel. Returns a plain
- *  `{ [candidateId]: cellId | null }` map. Exported as the read path for
- *  what one agent can currently observe — every caller (this file's own
- *  tick loop, a viz panel, a future chat lane) reads the same computation,
- *  never a re-derived copy of it. */
-export function beliefSnapshotFor(observerSubject, observerCell, candidateIds, state, opts) {
-  const belief = {};
-  for (const candidateId of candidateIds) {
-    if (candidateId === observerSubject) continue;
-    const cell = believedCellOf(candidateId, observerSubject, observerCell, state, opts);
-    belief[candidateId] = cell ? cellId(cell.x, cell.y) : null;
-  }
-  return belief;
-}
-
 /** Live (unexpired, by `turn`) dynamic webs from a `Map(webId -> {cell,
  *  builtAtTurn})` (either a folded state's own `.webs`, or that widened with
  *  web(s) minted THIS tick before they've been written/read back), as a

package/src/services/world-teach.mjs

@@ -0,0 +1,214 @@
+// world-teach.mjs — a declarative sentence read as a fact against the LIVE
+// world, and written into it on the spot. This is the engine half of the
+// adventure/mud pages' "teach" switch: with it off nothing here runs and the
+// lane behaves exactly as it always has; with it on, a sentence the surface's
+// own editor grammar can express becomes a world fact this turn.
+//
+// It owns the gates, the id minting, the snapshot stamping and the decline
+// wording. It owns NO grammar. The sentence table belongs to the surface —
+// adventure-editor.mjs for a manor, mud-editor.mjs for a burrow, which say
+// placement with different words — so the parser arrives as `parseLine` and
+// this module never learns either vocabulary. Both tables are the inverse of
+// their own page's right-hand "the world's own account" renderer, so every
+// sentence a page has already SHOWN somebody is a sentence they can type back.
+//
+// This is deliberately NOT chat.mjs's teachLane, and does not widen it. A
+// chat teach carries `teach:chat:*` provenance, which worldActionRows filters
+// out of the playable fold on purpose: a locative note somebody made mid-game
+// must never silently move a prop. A world teach is a different act — the
+// player asserting what the world IS — so it carries its own
+// `world:<name>:taught:turnK` provenance, passes that same filter by the
+// `world:` prefix every played turn already uses, and scores on the world's
+// own Source with no change to the trust model. The two stay apart.
+//
+// Semantics are general on purpose. Anything the table can say becomes a
+// fact: a new thing, a world-authored one moved, a locked cabinet opened, the
+// player put somewhere else. The fold has no invariant layer, so a
+// contradicting row does not conflict — the newer write simply wins, exactly
+// as a played turn's does.
+//
+// One consequence worth stating plainly: a teach spends a turn number (every
+// fold-versioned write is stamped `@turnK`, or it would rank as turn 0 and
+// lose to anything already played) but does NOT run the NPC pass. Nobody in
+// the cast moves in response to a sentence. That is the same trade the
+// 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 {
+  classMassFacts, foldWorldState, freshObjectId, snapshotSubject, worldActionRows, worldRelook,
+} from "./adventure.mjs";
+
+// A trailing "?" is an unambiguous "this is a question", and a question must
+// never reach a write boundary. A leading interrogative is the same signal one
+// 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;
+
+// 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
+// the claim that `there` is a `book in the study` — a real fact, about
+// nothing. These decline rather than fall through: the sentence is plainly
+// meant as a teach, and quietly handing it to the ordinary lanes to answer as
+// conversation is the guess this product doesn't make.
+const EMPTY_SUBJECTS = new Set(["it", "they", "them", "there", "this", "that", "these", "those", "he", "she"]);
+
+const PLACEMENT_PREDICATES = new Set([
+  "mgx:currently-in", "mgx:located-in", "mgx:fixed-in", "mgx:stands-locked-in", "mgx:hidden-in",
+]);
+
+const SNAPSHOT_RE = /^(.+?)@(?:epoch(\d+)@)?turn(\d+)$/;
+
+const decline = (text, note) => ({ text, lane: "game-answer", note: `ADVENTURE — world-teach: ${note}`, miss: true });
+
+/** Which subject is which class, for the one genuinely ambiguous placement
+ *  sentence ("X is in the Y." reads as a person standing or a prop resting,
+ *  depending on X). The adventure table takes this as its second argument;
+ *  the burrow table says the two with different words and ignores it. */
+function typesFromRows(rows) {
+  const types = new Map();
+  for (const row of rows || []) {
+    if (row?.predicate === "rdf:type" && row.subject && row.object) {
+      types.set(String(row.subject).trim().toLowerCase(), String(row.object).trim().toLowerCase());
+    }
+  }
+  return types;
+}
+
+const roomsOf = (rows) => [...new Set((rows || [])
+  .filter((r) => r.predicate === "rdf:type" && r.object === "room" && !SNAPSHOT_RE.test(r.subject))
+  .map((r) => r.subject))].sort();
+
+/** Every name the world already resolves — anything typed, anything placed,
+ *  and either end of an exit. A subject already on this list is moved or
+ *  re-described by a teach; one that isn't is minted. */
+function knownNames(rows, state) {
+  const names = new Set();
+  for (const row of rows || []) {
+    if (SNAPSHOT_RE.test(row.subject)) continue;
+    if (row.predicate === "rdf:type" || PLACEMENT_PREDICATES.has(row.predicate)) names.add(row.subject);
+    if (/^mgx:has-exit-[a-z]+$/.test(row.predicate)) { names.add(row.subject); names.add(row.object); }
+  }
+  for (const subject of state?.placements?.keys() ?? []) names.add(subject);
+  return names;
+}
+
+/** An id nothing in the world answers to yet. The plain noun wherever it is
+ *  free, so "Candle is in the study" leaves a thing called `candle` and the
+ *  pill rail offers "take candle" on the very next redraw — the world's own
+ *  class-default minting picks ids the same way. A collision falls back to
+ *  the numbered id every mid-play spawn already uses. */
+function mintedIdFor(rows, noun) {
+  const taken = (rows || []).some((r) => r.subject === noun || r.object === noun);
+  return taken ? freshObjectId(rows, noun) : noun;
+}
+
+function confirmation(triple, { thing, minted, rooms }) {
+  if (triple.predicate === "mgx:is-open") {
+    return `noted — the ${thing} is ${triple.object === "true" ? "open" : "closed"} now.`;
+  }
+  if (PLACEMENT_PREDICATES.has(triple.predicate)) {
+    const where = rooms.includes(triple.object) ? `in the ${triple.object}` : `with the ${triple.object}`;
+    return minted ? `noted — there's a ${thing} ${where} now.` : `noted — the ${thing} is ${where} now.`;
+  }
+  if (triple.predicate === "rdf:type") return `noted — the ${thing} is a ${triple.object} now.`;
+  return `noted — the world says that now.`;
+}
+
+/**
+ * One line read as a fact about the live world, or null when it is not a
+ * teach sentence at all and the ordinary lane should have it. `parseLine` is
+ * the surface's own editor parser (`parseEditorLine` / `parseMudEditorLine`);
+ * `planTriple` is that same editor's additive planner. `rows`/`state` are the
+ * caller's already-loaded fact rows and fold, so this never re-reads the
+ * store to decide.
+ *
+ * Returns the ordinary lane answer shape — `{ text, lane, note }`, plus
+ * `miss: true` on every decline so the transcript styles it like any other
+ * honest refusal, and `taught` (the rows actually written) on a success.
+ */
+export async function worldTeachTurn(line, {
+  parseLine, planTriple, rows, state, memoryDir, world, actingSubject = "player", cache = null, graph = null,
+}) {
+  const trimmed = String(line || "").trim();
+  if (!trimmed || !parseLine || !planTriple || !memoryDir) return null;
+  if (/\?\s*$/.test(trimmed)) return null;
+  if (QUESTION_LEAD_RE.test(correctMisspellings(trimmed))) return null;
+
+  const triple = parseLine(trimmed, typesFromRows(rows));
+  if (!triple) return null;
+
+  const rooms = roomsOf(rows);
+  if (EMPTY_SUBJECTS.has(triple.subject)) {
+    return decline(
+      `"${triple.subject}" doesn't name anything I can write a fact about — name the thing itself, like "candle is in the study".`,
+      `"${trimmed}" parses with "${triple.subject}" as its subject, which refers to nothing this world holds; declined rather than stored against a pronoun`,
+    );
+  }
+  if (triple.kind === "placement" && !rooms.includes(triple.object) && !knownNames(rows, state).has(triple.object)) {
+    return decline(
+      `I don't know a place called "${triple.object}" — this world has: ${rooms.join(", ")}.`,
+      `"${trimmed}" places ${triple.subject} in "${triple.object}", which names no room and nothing else the world holds; declined by name, alternatives listed`,
+    );
+  }
+
+  const { toAppend, reason } = planTriple(rows, state, triple);
+  const known = knownNames(rows, state);
+  const minting = triple.kind === "placement" && !known.has(triple.subject);
+  // Re-asserting something the world already holds is true, so it is not a
+  // miss — but it writes nothing, and saying so is the whole answer.
+  if (!toAppend.length && !minting) {
+    const room = state?.placements?.get(actingSubject)?.object ?? null;
+    return {
+      text: `the world already said that.${room ? ` ${await worldRelook(room, { memoryDir, graph, actingSubject })}` : ""}`,
+      lane: "game-answer",
+      miss: false,
+      note: `ADVENTURE — world-teach: "${trimmed}" asserts a fact the world already holds (${reason}); nothing written`,
+      taught: [],
+    };
+  }
+
+  const k = (state?.turnCount ?? 0) + 1;
+  const epoch = state?.epoch ?? 0;
+  const id = minting ? mintedIdFor(rows, triple.subject) : triple.subject;
+  // Only the fold-versioned families are stamped. foldWorldState ranks an
+  // unstamped row as turn 0, so an unstamped placement would silently lose to
+  // anything already played about the same thing. A type/exit/flag row is read
+  // raw by every reader and must keep its bare subject — a stamped one names a
+  // subject no verb resolves.
+  const stamp = (t) => (t.kind === "other"
+    ? { subject: id, predicate: t.predicate, object: t.object }
+    : { subject: snapshotSubject(id, k, epoch), predicate: t.predicate, object: t.object });
+  const facts = [
+    // A minted thing arrives with the same rows the world's own class-default
+    // and dig spawns write: its own class (which resolves its sprite), the
+    // portable class (which is what makes the take verb accept it), a plain
+    // reading name, and whatever mass its class declares. A class with no
+    // sprite of its own falls back to the parcel icon already drawn for it.
+    ...(minting ? [
+      { subject: id, predicate: "rdf:type", object: triple.subject },
+      { subject: id, predicate: "rdf:type", object: "portable" },
+      { subject: id, predicate: "mgx:display-name", object: triple.subject },
+      ...classMassFacts(rows, id, triple.subject),
+    ] : []),
+    ...toAppend.map(stamp),
+  ];
+  const provenance = `${worldProvenanceTag(world)}:taught:turn${k}`;
+  await appendFacts(memoryDir, facts.map((f) => ({ ...f, provenance })));
+  if (cache) cache.rows = null;
+
+  const freshState = foldWorldState(worldActionRows(readFactRows(await loadMemory(memoryDir))));
+  const here = freshState.placements.get(actingSubject)?.object ?? null;
+  const said = confirmation(triple, { thing: triple.subject, minted: minting, rooms });
+  const relook = here ? ` ${await worldRelook(here, { memoryDir, graph, actingSubject })}` : "";
+  return {
+    text: `${said}${relook}`,
+    lane: "game-answer",
+    miss: false,
+    goal: minting ? `put a ${triple.subject} in the world` : `change what the world says about the ${triple.subject}`,
+    note: `ADVENTURE — world-teach: ${reason}; ${minting ? `minted ${id} and ` : ""}wrote ${facts.length} row(s) at turn ${k} with provenance ${provenance}; no NPC pass rides a taught fact${here ? `; auto-relook appended for the ${here}` : ""}`,
+    taught: facts,
+  };
+}

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

@@ -43,7 +43,7 @@ import {
 import { parseEntities } from "../../domain/codegraph.mjs";
 import { memoryFactGraphPayload } from "../../domain/memory-facts.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
-import { foldWorldState, worldDigestRows, roomAffordances, worldActionRows } from "../../services/adventure.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";
 import { resolveSpriteForClass, SPRITE_REGISTRY, classAncestorChain } from "../../domain/sprite-map.mjs";
@@ -194,15 +194,30 @@ export async function createAdventureSession(worldPayload, { restoredPayload = n
      *  fact as "not in this text" and try to retract it). Retractions
      *  (removeFacts) only ever run when the WHOLE document parsed cleanly —
      *  see adventure-editor.mjs's own header for why a typo must never be
-     *  read as "this fact is gone". Returns `{ unrecognized, added, removed }`. */
+     *  read as "this fact is gone". Returns `{ unrecognized, added, removed }`.
+     *
+     *  A placement or openness edit is written as a TURN SNAPSHOT, the way
+     *  every played turn writes one. foldWorldState ranks an unstamped row as
+     *  turn 0, so an edit to something already played — the lamp taken on
+     *  turn 4, then moved back to the desk in the editor — would be outranked
+     *  by the very move it was meant to correct, and the edit would land in
+     *  the store and change nothing anyone can see. Type/exit/puzzle rows are
+     *  read raw and keep their bare subject: a stamped one names a subject no
+     *  verb resolves. */
     async applyEdit(text) {
       const allRows = readFactRows(await loadMemory(memoryDir));
       const worldRows = allRows.filter((r) => typeof r.provenance === "string" && r.provenance.indexOf(tag) === 0);
       const state = foldWorldState(worldRows);
       const { triples, unrecognized } = parseWorldEditorText(text, worldRows);
       const { toAppend, toRemoveIds } = planWorldEditorSync(worldRows, state, triples);
+      const editTurn = state.turnCount + 1;
       if (toAppend.length) {
-        await appendFacts(memoryDir, toAppend.map((f) => ({ subject: f.subject, predicate: f.predicate, object: f.object, provenance: tag })));
+        await appendFacts(memoryDir, toAppend.map((f) => ({
+          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}`,
+        })));
       }
       const removedCount = unrecognized.length === 0 && toRemoveIds.length ? (await removeFacts(memoryDir, toRemoveIds)).removed.length : 0;
       const here = foldWorldState(readFactRows(await loadMemory(memoryDir))).placements.get("player")?.object ?? null;