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

package/src/domain/game-config.mjs

@@ -78,10 +78,18 @@ export const DEFAULT_GAME_CONFIG = Object.freeze({
     preyVisionRadius: 3,
     preySpawnIntervalTurns: 5,
     foodSpawnIntervalTurns: 3,
-    spawnedFoodMass: 1,
+    // Spawned and placed food are one thing: the same hay bale, worth the
+    // same. The two knobs stay separate so a world can still tell them apart.
+    spawnedFoodMass: 2,
     placedFoodMass: 2,
     maxPreyPopulation: 6,
     maxFoodItems: 8,
+    // Whether food only enters an agent's belief once it is within vision
+    // radius, the same as every other candidate. True by default — a crumb
+    // known to everyone the instant it spawns changes the foraging feel, and
+    // this is the one switch that turns that off (visionRadius: Infinity for
+    // the food-only belief call) without any new belief machinery.
+    foodVisionGated: true,
   }),
   guessNumber: Object.freeze({
     defaultLo: 1,
@@ -152,6 +160,7 @@ const MUDIII_KEY_MAP = Object.freeze({
   placed_food_mass: "placedFoodMass",
   max_prey_population: "maxPreyPopulation",
   max_food_items: "maxFoodItems",
+  food_vision_gated: "foodVisionGated",
 });
 
 const ADVENTURE_KEY_MAP = Object.freeze({

package/src/domain/interpret/normalize.mjs

@@ -123,6 +123,10 @@ export function correctMisspellings(text) {
   return String(text || "").replace(MISSPELLING_RE, (m) => MISSPELLINGS[m.toLowerCase()]);
 }
 
+/** Interrogative / auxiliary leads that make an "X is a Y"-shaped line a QUESTION
+ *  ("what is a cache", "is a module a component"), never a teach declarative. */
+export 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;
+
 const FILLER_RE = FILLER_WORDS.length
   ? new RegExp(
       "\\b(" + [...FILLER_WORDS].sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b\\s*,?",

package/src/domain/memory/retraction.mjs

@@ -0,0 +1,232 @@
+// memory/retraction.mjs — making a retraction survive the next sync.
+//
+// removeFacts is a real delete, and deleting from a replicated grow-only set is
+// not a G-Set operation: a peer that still holds the fact re-sends it and the
+// retraction is undone. What closes that hole is the move compaction's chain
+// summary already makes. The retraction leaves a RECORD behind, the record
+// carries the record ids it suppressed, and two records at one id merge by
+// UNION of those ids. Union is a join, so two peers that retracted at different
+// moments converge, and merging twice changes nothing.
+//
+// A retraction suppresses ONE SOURCE'S assertion, not the whole triple group.
+// Two peers who independently taught the same fact hold two records; one of
+// them retracting leaves the fact standing and cited to the other, and the
+// retraction stays on record rather than erasing what was asserted. That falls
+// out of absorbing concrete record ids: a record another peer holds and this
+// one never did is not in the set.
+//
+// The instant matters as much as the ids. One source asserting the same triple
+// again lands on the SAME content address, so an id on its own cannot tell a
+// suppressed assertion from a later, deliberate one. The record therefore
+// carries the moment of the retraction, and both enforcement points compare an
+// assertion's own time against it: at or before, suppressed; after, it stands.
+// Max is a join too, so that field merges in either order and agrees.
+//
+// Pure: this module plans, merges and encodes retraction RECORDS. core.mjs owns
+// the store, p2p-room.mjs owns the wire. Its own class, its own id suffix and
+// its own predicate keep it clear of compaction — a compacted record and a
+// retracted one mean opposite things, and one namespace would let a summary
+// read as a tombstone. The CRDT vocabulary above is pinned in
+// docs/references/papers/crdt.md.
+
+export const RETRACTION_CLASS = "Retraction";
+
+/** The predicate a retraction travels under. The sync filters admit it on its
+ *  own, because a retraction has to cross a wire that a chat room gates on
+ *  provenance kind and a mud room gates on world predicates. */
+export const RETRACTION_PREDICATE = "mgx:retracted";
+
+export const RETRACTED_RECORD_IDS_PROP = "mgx:retractedRecordIds";
+export const RETRACTED_AT_PROP = "mgx:retractedAt";
+export const RETRACTED_COUNT_PROP = "mgx:retractedCount";
+
+const RETRACTION_SUFFIX = "#retracted";
+const PROVENANCE_PROP = "mgx:factProvenance";
+const NO_INSTANT = "-";
+
+/** One retraction record per (triple, source), the same per-source shape
+ *  compaction's chain summary keys on. */
+export const retractionIdFor = (groupId, sourceId) => `${groupId}@${sourceId}${RETRACTION_SUFFIX}`;
+export const isRetractionId = (id) => String(id || "").endsWith(RETRACTION_SUFFIX);
+
+/** The record id a retraction suppresses, read back off its own id. */
+export function retractionScopeOf(retractionId) {
+  const id = String(retractionId || "");
+  return isRetractionId(id) ? id.slice(0, -RETRACTION_SUFFIX.length) : "";
+}
+
+const attrValue = (ind, prop) => (ind?.attributes || []).find((a) => a?.prop === prop)?.value || "";
+const idList = (value) => String(value || "").split(" ").filter(Boolean);
+const tagList = (value) => String(value || "").split(" | ").filter(Boolean);
+
+export const retractedRecordIds = (ind) => idList(attrValue(ind, RETRACTED_RECORD_IDS_PROP));
+export const retractedAtOf = (ind) => attrValue(ind, RETRACTED_AT_PROP);
+
+/** The later of two instants, tolerating "" and unparseable input on either
+ *  side. Max is a join, which is what lets two records merge in either order. */
+function laterOf(a, b) {
+  const at = Date.parse(a);
+  const bt = Date.parse(b);
+  if (!Number.isFinite(at)) return Number.isFinite(bt) ? String(b) : "";
+  if (!Number.isFinite(bt)) return String(a);
+  return bt > at ? String(b) : String(a);
+}
+
+const templateOf = (record) => ({
+  label: record?.label || "",
+  subject: attrValue(record, "rdf:subject"),
+  predicate: attrValue(record, "rdf:predicate"),
+  object: attrValue(record, "rdf:object"),
+});
+
+/**
+ * Build a retraction record from the only things that define one: which record
+ * ids it suppressed, when, and who said so. Planning and merging both come
+ * through here, so a record built by retracting and the same record reached by
+ * merging two halves come out identical — the property the whole design rests
+ * on. The triple it names is carried for a reader; nothing enforces on it.
+ */
+function buildRetraction({ id, sourceId, template, ids, retractedAt, tags }) {
+  const sorted = [...new Set(ids)].filter(Boolean).sort();
+  const provenance = [...new Set(tags)].filter(Boolean).sort();
+  return {
+    id,
+    label: template?.label || "",
+    class: RETRACTION_CLASS,
+    derived_from: [],
+    mentions: [],
+    attributes: [
+      { prop: "rdf:subject", key: "subject", value: template?.subject || "" },
+      { prop: "rdf:predicate", key: "predicate", value: template?.predicate || "" },
+      { prop: "rdf:object", key: "object", value: template?.object || "" },
+      { prop: "mgx:sourceId", key: "sourceId", value: sourceId || "" },
+      { prop: RETRACTED_RECORD_IDS_PROP, key: "retractedRecordIds", value: sorted.join(" ") },
+      { prop: RETRACTED_COUNT_PROP, key: "retractedCount", value: String(sorted.length) },
+      { prop: RETRACTED_AT_PROP, key: "retractedAt", value: retractedAt || "" },
+      ...(provenance.length ? [{ prop: PROVENANCE_PROP, key: "provenance", value: provenance.join(" | ") }] : []),
+    ],
+  };
+}
+
+/**
+ * Plan the record one source's retraction leaves behind. `recordIds` are the
+ * ids actually removed for that source — its head, its demoted leaves, and any
+ * summary standing for them. `existing` is the record this source already has
+ * here, if the triple has been retracted before; its ids come along, so
+ * retracting twice keeps one record rather than growing a chain of them.
+ *
+ * Null when there is nothing to suppress, which keeps a no-op removal from
+ * writing a tombstone for a fact nobody ever asserted.
+ */
+export function planRetraction({ groupId, sourceId, recordIds = [], retractedAt = "", existing = null, template = null, provenance = "" }) {
+  if (!groupId || !sourceId) return null;
+  const ids = [...retractedRecordIds(existing), ...recordIds].filter(Boolean);
+  if (!ids.length) return null;
+  return buildRetraction({
+    id: retractionIdFor(groupId, sourceId),
+    sourceId,
+    template: template || templateOf(existing),
+    ids,
+    retractedAt: laterOf(retractedAtOf(existing), retractedAt),
+    tags: [...tagList(attrValue(existing, PROVENANCE_PROP)), ...tagList(provenance)],
+  });
+}
+
+/**
+ * Join two retraction records that share an id: union the suppressed ids and
+ * the tags, take the later instant, then re-derive everything else from that.
+ * Commutative, associative and idempotent, because union and max both are and
+ * because the count is a function of the union rather than a separate running
+ * total.
+ */
+export function mergeRetractions(existing, incoming) {
+  const template = templateOf(attrValue(existing, "rdf:subject") ? existing : incoming);
+  return buildRetraction({
+    id: existing?.id || incoming?.id,
+    sourceId: attrValue(existing, "mgx:sourceId") || attrValue(incoming, "mgx:sourceId"),
+    template,
+    ids: [...retractedRecordIds(existing), ...retractedRecordIds(incoming)],
+    retractedAt: laterOf(retractedAtOf(existing), retractedAtOf(incoming)),
+    tags: [...tagList(attrValue(existing, PROVENANCE_PROP)), ...tagList(attrValue(incoming, PROVENANCE_PROP))],
+  });
+}
+
+/** Whether an assertion made at `assertedAt` is old enough for the retraction
+ *  to bite. An assertion with no readable time cannot show it is newer, so it
+ *  is suppressed; the same goes for a record whose own instant will not parse.
+ *  Erring this way keeps a resurrected copy out, and a source that means to say
+ *  the thing again says it with a fresh tag. */
+function notLaterThan(assertedAt, retractedAt) {
+  const asserted = Date.parse(assertedAt);
+  const retracted = Date.parse(retractedAt);
+  if (!Number.isFinite(retracted) || !Number.isFinite(asserted)) return true;
+  return asserted <= retracted;
+}
+
+/** Does this record suppress `recordId` as asserted at `assertedAt`? */
+export function suppressesRecord(retraction, recordId, assertedAt = "") {
+  if (!retraction || !recordId) return false;
+  if (!retractedRecordIds(retraction).includes(recordId)) return false;
+  return notLaterThan(assertedAt, retractedAtOf(retraction));
+}
+
+/** The same check across a group's records. Both enforcement halves — the strip
+ *  on read and the refusal on ingest — ask exactly this question. */
+export function isRetractedRecord(retractions, recordId, assertedAt = "") {
+  for (const retraction of retractions || []) {
+    if (suppressesRecord(retraction, recordId, assertedAt)) return true;
+  }
+  return false;
+}
+
+/** The instant and the ids packed into one triple slot. The instant leads, ids
+ *  follow, space separated — neither an ISO instant nor a record id carries a
+ *  space, so the split is unambiguous. */
+export function encodeRetractionValue(retractedAt, ids) {
+  const sorted = [...new Set(ids || [])].filter(Boolean).sort();
+  return [retractedAt || NO_INSTANT, ...sorted].join(" ");
+}
+
+export function decodeRetractionValue(value) {
+  const parts = String(value || "").split(" ").filter(Boolean);
+  const head = parts[0] || "";
+  const retractedAt = head === NO_INSTANT || !Number.isFinite(Date.parse(head)) ? "" : head;
+  const ids = retractedAt || head === NO_INSTANT ? parts.slice(1) : parts;
+  return { retractedAt, ids };
+}
+
+/** A stored record as the one wire fact that carries it: the record id it
+ *  suppresses as the subject, the retraction predicate, and the instant plus
+ *  the suppressed ids as the object. Everything else on the record is derived
+ *  from those, so the round trip loses nothing a peer enforces on. */
+export function retractionWireFact(record) {
+  const scope = retractionScopeOf(record?.id);
+  if (!scope) return null;
+  return {
+    id: record.id,
+    subject: scope,
+    predicate: RETRACTION_PREDICATE,
+    object: encodeRetractionValue(retractedAtOf(record), retractedRecordIds(record)),
+    provenance: attrValue(record, PROVENANCE_PROP),
+  };
+}
+
+/** The other direction: a received wire fact as the record it stands for.
+ *  Null for anything that is not a well-formed retraction, so a malformed
+ *  message is dropped rather than merged. */
+export function retractionFromWire(fact) {
+  if (!fact || fact.predicate !== RETRACTION_PREDICATE) return null;
+  const scope = String(fact.subject || "");
+  const at = scope.indexOf("@");
+  if (at <= 0 || at === scope.length - 1) return null;
+  const { retractedAt, ids } = decodeRetractionValue(fact.object);
+  if (!ids.length) return null;
+  return buildRetraction({
+    id: `${scope}${RETRACTION_SUFFIX}`,
+    sourceId: scope.slice(at + 1),
+    template: null,
+    ids,
+    retractedAt,
+    tags: tagList(fact.provenance),
+  });
+}

package/src/domain/p2p/sync-filter.mjs

@@ -5,6 +5,13 @@
 // What actually needs syncing is the delta: whatever a person or a peer
 // actually added since boot.
 import { provenanceTagToSource } from "../memory/trust.mjs";
+import { RETRACTION_PREDICATE } from "../memory/retraction.mjs";
+
+// A retraction crosses on both surfaces, whatever else they disagree about.
+// It carries no teach tag of its own to key on and no world predicate, so
+// leaving it to either filter's own rule would strand it and the deleted fact
+// would come straight back from the next peer that still holds it.
+const alwaysSyncable = (row) => row?.predicate === RETRACTION_PREDICATE;
 
 // "teachNode" is the same human teaching, seen from one hop further out: a
 // peer's own relabeled tag, keyed on the node id it carries. It syncs for
@@ -16,6 +23,7 @@ const CHAT_SYNCABLE_KINDS = new Set(["teach", "operator", "teachNode"]);
  *  asserted — never a row from the shipped corpus. */
 export function chatSyncableFacts(rows) {
   return rows.filter((row) => {
+    if (alwaysSyncable(row)) return true;
     const source = provenanceTagToSource(row.provenance);
     return source ? CHAT_SYNCABLE_KINDS.has(source.kind) : false;
   });
@@ -31,5 +39,5 @@ export function chatSyncableFacts(rows) {
  *  this module's own P2P predicates via `extraPredicates`. */
 export function mudSyncableFacts(rows, isMudStatePredicate, extraPredicates = []) {
   const extra = new Set(extraPredicates);
-  return rows.filter((row) => extra.has(row.predicate) || isMudStatePredicate(row.predicate));
+  return rows.filter((row) => alwaysSyncable(row) || extra.has(row.predicate) || isMudStatePredicate(row.predicate));
 }

package/src/domain/spider-fly-world.mjs

@@ -5,7 +5,7 @@
 // structural self-description facts below quote the same shipped defaults
 // the engine actually runs. Both
 // scripts/gen-spider-fly-world.mjs (writes corpus/worlds/src/spider-fly.jsonl)
-// and src/services/spider-fly.mjs (the runtime) read the SAME grid/web
+// and src/services/spider-fly-turn.mjs (the runtime) read the SAME grid/web
 // constants from here, so the shipped world and the engine that plays it can
 // never drift apart.
 
@@ -14,28 +14,34 @@ import { DEFAULT_GAME_CONFIG } from "./game-config.mjs";
 export const WORLD_NAME = "spider-fly";
 export const GRID_SIZE = 10;
 
-// The spider's home cell, and the web's Chebyshev radius around it (radius 1
-// = a 3x3 block, PLAN_SPIDER_FLY.md §3). Corner-ish on purpose (§4): a spider
-// that starts here sees close to half the board just from edge-clipping.
+// The spider's home cell, and the web's Chebyshev radius around it (radius 1 =
+// a 3x3 block). Corner-ish on purpose: a spider that starts here sees close to
+// half the board just from edge-clipping.
 export const WEB_HOME = Object.freeze({ x: 2, y: 2 });
 export const WEB_RADIUS = 1;
 
-// A spider-built dynamic web (src/services/spider-fly.mjs's hasActiveWebAt)
-// stays active for this many turns past the turn it was built, mirroring the
-// static home zone's own always-on web without needing separate code paths.
+// A spider-built web stays active for this many turns past the turn it was
+// spun, mirroring the home zone's own always-on web without a second code path.
 export const WEB_DURATION_TURNS = 10;
 
-// Spider mass mirrors a fly's own (src/services/spider-fly.mjs's
-// FLY_INITIAL_MASS/FLY_MASS_DECREMENT_PER_TURN): a spider starves like a fly
-// does, and gains exactly a fly's remaining mass on an eat. Heavier starting
-// mass than a single fly's worth on purpose — a spider that eats nothing for
-// a while has some runway before starving. The decrement is half a fly's own
-// (spiders live longer between meals than flies do), and — like every other
-// tunable here — overridable per session via tmct.toml's [games.spider-fly]
-// (src/domain/game-config.mjs).
+// A spider starves like a fly does, and gains exactly a fly's remaining mass on
+// an eat. Heavier starting mass than a single fly's worth on purpose — a spider
+// that eats nothing for a while has some runway before starving. The decrement
+// is half a fly's own (spiders live longer between meals than flies do), and —
+// like every other tunable here — overridable per session via tmct.toml's
+// [games.spider-fly] (src/domain/game-config.mjs).
 export const SPIDER_INITIAL_MASS = 15;
 export const SPIDER_MASS_DECREMENT_PER_TURN = 0.5;
 
+/** The cast the shared predator/prey engine runs this board with. Same shape as
+ *  the town square's own roles object, minus the food entry: nothing inert
+ *  lies on a spider-and-fly board, and a null food role is what says so. */
+export const SPIDER_FLY_ROLES = Object.freeze({
+  predator: Object.freeze({ role: "predator", kind: "spider", idPrefix: "spider" }),
+  prey: Object.freeze({ role: "prey", kind: "fly", idPrefix: "fly" }),
+  food: null,
+});
+
 export const cellId = (x, y) => `cell-${x}-${y}`;
 
 const CELL_ID_RE = /^cell-(\d+)-(\d+)$/;
@@ -51,9 +57,9 @@ export const chebyshevDistance = (ax, ay, bx, by) => Math.max(Math.abs(ax - bx),
 export const inBounds = (x, y) => x >= 1 && x <= GRID_SIZE && y >= 1 && y <= GRID_SIZE;
 
 /** Every cell within Chebyshev `radius` of (cx, cy), clipped to the board, in
- *  raster order — the one visibility primitive PLAN_SPIDER_FLY.md §4 names
- *  ("visibleCells(cx, cy, radius=4)"), shared by both agents' belief and this
- *  module's own web-block derivation below. */
+ *  raster order — the one visibility primitive ("visibleCells(cx, cy, radius=4)")
+ *  shared by both agents' belief and this module's own web-block derivation
+ *  below. */
 export function visibleCells(cx, cy, radius) {
   const out = [];
   for (let y = Math.max(1, cy - radius); y <= Math.min(GRID_SIZE, cy + radius); y += 1) {
@@ -66,8 +72,7 @@ export function visibleCells(cx, cy, radius) {
 
 export const isInWebBlock = (x, y) => chebyshevDistance(x, y, WEB_HOME.x, WEB_HOME.y) <= WEB_RADIUS;
 
-/** Every board-edge (perimeter) cell, raster order — where a spawned fly
- *  arrives (PLAN_SPIDER_FLY.md §10). */
+/** Every board-edge (perimeter) cell, raster order. */
 export function perimeterCells() {
   const out = [];
   for (let y = 1; y <= GRID_SIZE; y += 1) {
@@ -94,11 +99,9 @@ export const DIRECTION_DELTA = Object.freeze({
  *  sits EXACTLY one cardinal step away (DIRECTION_DELTA) — null for the same
  *  cell, a diagonal, or any multi-step gap, so a caller never overstates
  *  "adjacent". The one shared primitive both the engine's own plan-driven
- *  facing (spider-fly.mjs) and the chat dock's deception pills
- *  (spider-fly-turn.mjs's pillsForSpiderFly) need — defined once here so
- *  neither has to re-derive it, and so the engine layer never has to import
- *  the chat-turn layer to get it (spider-fly-turn.mjs already imports
- *  spider-fly.mjs; the reverse would cycle). */
+ *  facing and the chat dock's deception pills (spider-fly-turn.mjs's
+ *  pillsForSpiderFly) need — defined once here so neither has to re-derive
+ *  it. */
 export function oneStepDirectionBetween(fromCell, toCell) {
   for (const [direction, { dx, dy }] of Object.entries(DIRECTION_DELTA)) {
     if (fromCell.x + dx === toCell.x && fromCell.y + dy === toCell.y) return direction;
@@ -106,11 +109,10 @@ export function oneStepDirectionBetween(fromCell, toCell) {
   return null;
 }
 
-/** The world's seed taxonomy (PLAN_SPIDER_FLY.md §7): enough for the
- *  ontology-to-sprite worked example (a poodle sprite, a sheepdog falling
- *  back to the generic dog sprite) to run on the default persona, no
- *  --persona-size large flag required. [subject, superclass] pairs, written
- *  as rdfs:subClassOf facts. */
+/** The world's seed taxonomy — enough for the ontology-to-sprite worked example
+ *  (a poodle sprite, a sheepdog falling back to the generic dog sprite) to run
+ *  on the default persona without the --persona-size large flag. [subject,
+ *  superclass] pairs, written as rdfs:subClassOf facts. */
 export const SEED_TAXONOMY = Object.freeze([
   Object.freeze(["poodle", "dog"]),
   Object.freeze(["sheepdog", "dog"]),
@@ -124,13 +126,56 @@ export const SEED_TAXONOMY = Object.freeze([
 export const WORLD_OPENING =
   "a spider waits in its web; a fly drifts in from the edge of the board. Neither is yours to move. Watch, or address one by name in chat.";
 
+/** This board as the shared predator/prey engine's own layout: a bare 10x10
+ *  grid, the always-on web block, and the cast a fresh session mints. `props`
+ *  is empty and stays empty — nothing here blocks movement, so every cell is
+ *  open and the whole perimeter takes an arrival. */
+export const SPIDER_FLY_LAYOUT = Object.freeze({
+  name: WORLD_NAME,
+  gridSize: GRID_SIZE,
+  opening: WORLD_OPENING,
+  boardNoun: "board",
+  boardSubject: "board",
+  cast: Object.freeze({ predators: 1, prey: 1 }),
+  props: Object.freeze([]),
+  staticWebAt: isInWebBlock,
+  webHomeCell: cellId(WEB_HOME.x, WEB_HOME.y),
+});
+
+/** The spider-and-fly knobs restated in the engine's role-keyed shape, with the
+ *  three mechanics this cast wants switched on. The public [games.spider-fly]
+ *  table stays species-keyed on purpose: a tmct.toml key and a page slider keep
+ *  the names a player of THIS game would use, and the translation lives here.
+ *  Unset keys fall back to the shipped defaults, so a partial slider payload is
+ *  always a complete engine config. Pure. */
+export function spiderFlyEngineConfig(knobs) {
+  const k = { ...DEFAULT_GAME_CONFIG.spiderFly, ...(knobs || {}) };
+  return {
+    predatorInitialMass: k.spiderInitialMass,
+    predatorMassDecrementPerTurn: k.spiderMassDecrementPerTurn,
+    predatorVisionRadius: k.spiderVisionRadius,
+    preyInitialMass: k.flyInitialMass,
+    preyMassDecrementPerTurn: k.flyMassDecrementPerTurn,
+    preyVisionRadius: k.flyVisionRadius,
+    preySpawnIntervalTurns: k.flySpawnIntervalTurns,
+    webDurationTurns: k.webDurationTurns,
+    eggLayMassThreshold: k.eggLayMassThreshold,
+    eggHatchDelayTurns: k.eggHatchDelayTurns,
+    eggHatchCount: k.eggHatchCount,
+    minHatchlingMass: k.minHatchlingMass,
+    carryPreyToWeb: true,
+    buildWebs: true,
+    layEggs: true,
+  };
+}
+
 /** Every fact row the shipped world source carries: cell typing, grid
  *  adjacency (mgx:has-exit-<direction>), the web block (mgx:in-web) and the
  *  seed taxonomy — plain { world, kind:"fact", subject, predicate, object }
  *  objects, the exact shape src/domain/worlds-pack.mjs's isWorldFactRow
  *  reads. Deliberately NOT spider-1/fly-1: the board is reusable static
  *  content, minted game entities are a fresh session's own state
- *  (src/services/spider-fly.mjs's startSpiderFlyGame). */
+ *  (src/services/spider-fly-turn.mjs's startSpiderFlyGame). */
 export function* worldFactRows() {
   for (let y = 1; y <= GRID_SIZE; y += 1) {
     for (let x = 1; x <= GRID_SIZE; x += 1) {
@@ -245,10 +290,10 @@ export function isLiveRenderableAgent(id, state) {
 
 /** A minimal, inert rule-row family, so scripts/build-worlds-pack.mjs's
  *  shared validator ("every world needs at least one rule row") passes.
- *  src/services/spider-fly.mjs never reads these back: grid movement is
- *  hand-written pathfinding over findActionPath/findReachableSet
- *  (PLAN_SPIDER_FLY.md §5), not the taught action-Rule DSL, so this rides in
- *  the shard unused, same as an unrelated fact would. */
+ *  src/services/spider-fly-turn.mjs never reads these back: grid movement is
+ *  hand-written pathfinding over findActionPath/findReachableSet, not the
+ *  taught action-Rule DSL, so this rides in the shard unused, same as an
+ *  unrelated fact would. */
 export function* worldRuleRows() {
   yield {
     world: WORLD_NAME, kind: "rule", name: "go", ruleKind: "action-signature",