@polycode-projects/the-mechanical-code-talker 2.10.3 → 2.11.0

package/src/services/research.mjs

@@ -0,0 +1,266 @@
+// research.mjs — the "research <topic>" lane: a Simple English Wikipedia
+// queue that grounds one topic per turn. Depth 0 is the requested topic
+// (opensearch + summary, ingested as graph facts); the topics its lead
+// section links to queue at depth 1, capped by the request's own
+// "limit N" or the configured default. Every completed search reports back
+// as its own chat turn — the queue advances one step per "research next"
+// (or a bare "next" while nothing else owns it), which is exactly what the
+// web pages' auto-play button submits.
+//
+// No node builtins — this module ships in the browser bundles unchanged.
+// The provider (network) and the ingest step (memory writes) are both
+// injected by the caller (chat.mjs), so this file owns only the queue
+// mechanics, the request grammar and the reported prose.
+//
+// Consent posture: an explicit "research <topic>" request IS the network
+// consent for its own fetches. Unlike the clean-miss rescue (which fires on
+// an ordinary question and therefore hides behind /wiki on), nobody types
+// "research owls" without meaning "go and look owls up" — the reply names
+// the source it reached either way. The /wiki toggle keeps governing every
+// other lane unchanged.
+//
+// The abstention invariant holds throughout: a topic whose fetch or
+// grounding fails reports the miss plainly, stores nothing, and the queue
+// moves on. No fact is ever fabricated to keep a research run tidy.
+
+import { normFactTerm } from "../domain/hash.mjs";
+import { loadLexicon, lookupNoun } from "../domain/grammar/lexicon.mjs";
+
+/** The search key a topic folds to: normFactTerm, then the lexicon lemma
+ *  when the noun is known ("owls" → "owl") — the same fold the live
+ *  clean-miss gate applies, and what keeps the provider's topic-drift guard
+ *  happy with an inflected request. An unknown word keys on its own folded
+ *  form (a topic the lexicon has never met is a fine thing to research). */
+export function researchTopicKey(topic, lexicon = null) {
+  const t = normFactTerm(topic);
+  if (!t) return "";
+  try {
+    const lex = lexicon ?? loadLexicon();
+    const entry = lookupNoun(lex, t);
+    if (entry) return normFactTerm(entry.lemma) || t;
+  } catch { /* lexicon unavailable — the folded form still works */ }
+  return t;
+}
+
+/** The most linked topics any request or config may queue at depth 1 —
+ *  the fair-use cap on a research run's total round trips. */
+export const RESEARCH_FANOUT_MAX = 12;
+
+export const RESEARCH_DEFAULTS = Object.freeze({
+  fanoutLimit: 5,
+  depthLimit: 1,
+  minIntervalMs: 2000,
+});
+
+const clampInt = (n, lo, hi) => Math.min(hi, Math.max(lo, Math.floor(n)));
+
+/** tmct.toml's `[research]` table → the lane's effective knobs, shipped
+ *  defaults filling every unset key (the same posture resolveGameConfig
+ *  takes with `[games.*]`). `fanout_limit` caps at RESEARCH_FANOUT_MAX;
+ *  `depth_limit` is 0 (no fan-out) or 1 (the depths engineered today);
+ *  `min_interval_ms` may only RAISE the polite floor between round trips,
+ *  never lower it. */
+export function resolveResearchConfig(toml = null) {
+  const raw = toml?.research || {};
+  const cfg = { ...RESEARCH_DEFAULTS };
+  const fanout = Number(raw.fanout_limit);
+  if (Number.isFinite(fanout)) cfg.fanoutLimit = clampInt(fanout, 0, RESEARCH_FANOUT_MAX);
+  const depth = Number(raw.depth_limit);
+  if (Number.isFinite(depth)) cfg.depthLimit = clampInt(depth, 0, 1);
+  const interval = Number(raw.min_interval_ms);
+  if (Number.isFinite(interval)) cfg.minIntervalMs = Math.max(RESEARCH_DEFAULTS.minIntervalMs, interval);
+  return cfg;
+}
+
+// The verbs that step/inspect/end a run, checked before the start shape so
+// "research next" never parses as a topic called "next".
+const RESEARCH_NEXT_RE = /^research[,:]?\s+(?:next|continue|more)\s*[.!?]*$/i;
+const RESEARCH_STATUS_RE = /^research[,:]?\s+status\s*[.!?]*$/i;
+const RESEARCH_STOP_RE = /^research[,:]?\s+(?:stop|cancel|quit|end)\s*[.!?]*$/i;
+const RESEARCH_START_RE = /^research[,:]?\s+(.+?)(?:[,;]?\s+(?:with\s+)?limit\s+(\d{1,3}))?\s*[.!?]*$/i;
+// A bare continuation word steps the queue too, but only when a run is
+// actually pending and no plan lane owns the word — parseResearchRequest
+// reports it as its own kind so the caller can apply that gate.
+const BARE_NEXT_RE = /^(?:next|continue|carry on|keep going)\s*[.!?]*$/i;
+
+/** The research request a line carries, or null. Kinds: start {topic,
+ *  limit?}, next, bareNext, status, stop. The topic keeps the user's own
+ *  words minus a leading article and any wrapping quotes; limit is only
+ *  present when the request named one. */
+export function parseResearchRequest(line) {
+  const q = String(line || "").trim();
+  if (!q) return null;
+  if (BARE_NEXT_RE.test(q)) return { kind: "bareNext" };
+  if (RESEARCH_NEXT_RE.test(q)) return { kind: "next" };
+  if (RESEARCH_STATUS_RE.test(q)) return { kind: "status" };
+  if (RESEARCH_STOP_RE.test(q)) return { kind: "stop" };
+  const m = q.match(RESEARCH_START_RE);
+  if (!m) return null;
+  const topic = m[1].trim()
+    .replace(/^["'‘’“”]+|["'‘’“”]+$/g, "")
+    .replace(/^(?:an?|the)\s+/i, "")
+    .trim();
+  if (!topic) return null;
+  const out = { kind: "start", topic };
+  if (m[2] !== undefined) out.limit = Number(m[2]);
+  return out;
+}
+
+/** The provenance tag every fact a research run stores carries:
+ *  `research:<topic>@<depth>` — memory/trust.mjs parses it back to the
+ *  referenceLive kind, so live-fetched research content scores exactly like
+ *  any other live Wikipedia load, below the curated packs. */
+export function researchProvenanceTag(topicKey, depth) {
+  return `research:${topicKey}@${depth}`;
+}
+
+/** The cited per-topic report — the same title/licence/revision-pinned-URL
+ *  discipline renderLiveReferenceAnswer holds, naming this lane's source. */
+export function renderResearchAnswer(term, article) {
+  return `${term} — ${article.summary} (source: research article "${article.title}", `
+    + `Simple English Wikipedia, CC BY-SA 4.0 — ${article.url}?oldid=${article.revid})`;
+}
+
+/** The queue as plain data for a UI: pending titles, per-topic fact counts,
+ *  skips, and whether the run is complete. Null for no run. */
+export function researchSnapshot(state) {
+  if (!state) return null;
+  return {
+    topic: state.topic,
+    limit: state.limit,
+    pending: [...state.pending],
+    done: state.done.map((d) => ({ title: d.title, facts: d.facts, depth: d.depth })),
+    skipped: [...state.skipped],
+    complete: state.pending.length === 0,
+  };
+}
+
+const totalFacts = (state) => state.done.reduce((sum, d) => sum + d.facts, 0);
+
+function progressLine(state) {
+  const done = `${state.done.length} topic${state.done.length === 1 ? "" : "s"} grounded, ${totalFacts(state)} fact${totalFacts(state) === 1 ? "" : "s"} stored`;
+  const skipped = state.skipped.length ? `, ${state.skipped.length} skipped` : "";
+  if (!state.pending.length) return `research on "${state.topic}" is complete — ${done}${skipped}.`;
+  return `${done}${skipped}; ${state.pending.length} linked topic${state.pending.length === 1 ? "" : "s"} still queued — "research next" fetches the next one.`;
+}
+
+async function startRun({ topic, limit }, { holder, provider, ingest, config, notify, lexicon }) {
+  const key = researchTopicKey(topic, lexicon);
+  if (!key) {
+    holder.state = null;
+    return { text: `I can't make a search key out of "${topic}".`, miss: true };
+  }
+  try { if (typeof notify === "function") notify(key); } catch { /* notify-only */ }
+  let article = null;
+  try { article = await provider.lookup(key); } catch { article = null; }
+  if (!article) {
+    holder.state = null;
+    return {
+      text: `I couldn't ground "${topic}" from Simple English Wikipedia just now — no matching article, or the network didn't answer. Nothing was stored.`,
+      miss: true,
+    };
+  }
+  let facts = 0;
+  try { facts = await ingest(key, article, researchProvenanceTag(key, 0)); } catch { facts = 0; }
+  const fanout = clampInt(
+    limit !== undefined && Number.isFinite(limit) ? limit : config.fanoutLimit,
+    0,
+    RESEARCH_FANOUT_MAX,
+  );
+  let pending = [];
+  if (fanout > 0 && config.depthLimit > 0 && typeof provider.linkedTitles === "function") {
+    let linked = null;
+    try { linked = await provider.linkedTitles(article.title, { limit: fanout + 2 }); } catch { linked = null; }
+    const seen = new Set([key, normFactTerm(article.title)]);
+    for (const title of linked || []) {
+      const folded = normFactTerm(title);
+      if (!folded || seen.has(folded)) continue;
+      seen.add(folded);
+      pending.push(title);
+      if (pending.length >= fanout) break;
+    }
+  }
+  holder.state = {
+    topic, key, title: article.title, limit: fanout,
+    pending, done: [{ title: article.title, facts, depth: 0 }], skipped: [],
+  };
+  const queueLine = pending.length
+    ? `queued ${pending.length} linked topic${pending.length === 1 ? "" : "s"}: ${pending.join(", ")} — "research next" fetches the next one (the page's play button does this for you).`
+    : `no linked topics queued — research on "${topic}" is complete.`;
+  return {
+    text: `${renderResearchAnswer(key, article)}\nstored ${facts} fact${facts === 1 ? "" : "s"} from "${article.title}". ${queueLine}`,
+    miss: false,
+  };
+}
+
+async function stepRun({ holder, provider, ingest, notify }) {
+  const state = holder.state;
+  const title = state.pending[0];
+  state.pending = state.pending.slice(1);
+  try { if (typeof notify === "function") notify(title); } catch { /* notify-only */ }
+  let article = null;
+  try { article = await (provider.pageByTitle ? provider.pageByTitle(title) : provider.lookup(normFactTerm(title))); } catch { article = null; }
+  if (!article) {
+    state.skipped = [...state.skipped, title];
+    return {
+      text: `I couldn't fetch "${title}" from Simple English Wikipedia — skipped, nothing stored. ${progressLine(state)}`,
+      miss: true,
+    };
+  }
+  const key = normFactTerm(article.title) || normFactTerm(title);
+  let facts = 0;
+  try { facts = await ingest(key, article, researchProvenanceTag(state.key, 1)); } catch { facts = 0; }
+  state.done = [...state.done, { title: article.title, facts, depth: 1 }];
+  return {
+    text: `${renderResearchAnswer(key, article)}\nstored ${facts} fact${facts === 1 ? "" : "s"} from "${article.title}". ${progressLine(state)}`,
+    miss: false,
+  };
+}
+
+/**
+ * The whole lane behind one call — chat.mjs's dispatch stays one thin block.
+ * Returns null when the line carries no research request (or carries a bare
+ * "next" this lane must not claim), else { text, miss, note, goal } with
+ * `holder.state` updated in place; the caller snapshots it for the UI and
+ * threads it to the next turn.
+ *
+ * `ctx`: { holder, provider, ingest(key, article, tag) -> stored count,
+ * config (resolveResearchConfig's shape), memoryDir, planActive,
+ * pagerActive, notify, lexicon }.
+ */
+export async function researchTurn(line, ctx) {
+  const req = parseResearchRequest(line);
+  if (!req) return null;
+  const { holder, memoryDir, planActive, pagerActive } = ctx;
+  const pendingRun = Boolean(holder.state && holder.state.pending.length);
+  // A bare "next" belongs to an active plan first, then to paging — this
+  // lane only claims it when a research queue is the one thing running.
+  if (req.kind === "bareNext" && (!pendingRun || planActive || pagerActive)) return null;
+  const goal = "research a topic on Simple English Wikipedia and remember what it grounds";
+  const wrap = (r, note) => ({ ...r, goal, note });
+  if (req.kind === "status") {
+    if (!holder.state) return wrap({ text: 'no research is running — "research <topic>" starts one.', miss: true }, "RESEARCH — status with no run standing");
+    return wrap({ text: progressLine(holder.state), miss: false }, "RESEARCH — queue status read-out");
+  }
+  if (req.kind === "stop") {
+    if (!holder.state) return wrap({ text: 'no research is running — "research <topic>" starts one.', miss: true }, "RESEARCH — stop with no run standing");
+    const state = holder.state;
+    holder.state = null;
+    const dropped = state.pending.length;
+    return wrap({
+      text: `stopped research on "${state.topic}" — ${state.done.length} topic${state.done.length === 1 ? "" : "s"} grounded, ${totalFacts(state)} fact${totalFacts(state) === 1 ? "" : "s"} stored${dropped ? `, ${dropped} queued topic${dropped === 1 ? "" : "s"} dropped` : ""}.`,
+      miss: false,
+    }, "RESEARCH — run stopped, queue dropped");
+  }
+  if (!memoryDir) {
+    return wrap({ text: "research needs a memory store to write into, and this session has none.", miss: true }, "RESEARCH — declined, no memory store");
+  }
+  if (req.kind === "next" || req.kind === "bareNext") {
+    if (!pendingRun) {
+      if (holder.state) return wrap({ text: progressLine(holder.state), miss: false }, "RESEARCH — next on a completed run reads the summary");
+      return wrap({ text: 'no research is running — "research <topic>" starts one.', miss: true }, "RESEARCH — next with no run standing");
+    }
+    return wrap(await stepRun(ctx), "RESEARCH — one queued topic fetched and grounded");
+  }
+  return wrap(await startRun(req, ctx), "RESEARCH — depth-0 topic fetched, linked topics queued");
+}

package/src/services/sentences.mjs

@@ -43,3 +43,22 @@ export function splitSentencesPreservingPaths(text) {
   }
   return out;
 }
+
+/** Bracketed reference residue an encyclopedia paragraph leaves in prose:
+ *  numeric footnote markers ([3], [12]), single-letter notes ([a]), and the
+ *  named ones ([note 4], [citation needed], [source?], [page 2]). Removed
+ *  case-insensitively so the sentence downstream reads as plain text, with the
+ *  gap tidied so "period.[3] Sales" becomes "period. Sales", not
+ *  "period.  Sales". A file path never carries a bracket, so a dotted module
+ *  identifier ("src/core/store.mjs") is left whole — only bracketed spans are
+ *  touched. Deliberately NOT wired into the shared splitter; a caller that
+ *  wants clean prose applies it before or after splitting. */
+export function stripCitationResidue(text) {
+  return String(text ?? "")
+    .replace(/\[\s*\d+\s*\]/g, "")
+    .replace(/\[\s*[a-z]\s*\]/gi, "")
+    .replace(/\[\s*(?:note|citation|ref|source|page|pp?)\b[^\]]*\]/gi, "")
+    .replace(/ +([.,;:!?])/g, "$1")
+    .replace(/ {2,}/g, " ")
+    .trim();
+}

package/src/services/session-log-format.mjs

@@ -0,0 +1,64 @@
+// session-log-format.mjs — the ONE Markdown shape every session-transcript
+// writer renders turns into: the Node CLI/TUI's own .tmct/session-<id>.md
+// (chat-session.mjs) and the browser chat page's "export .md" button
+// (chat-page-viz.mjs). A `#` title carrying the version and a short session
+// label, one `###` heading per turn at millisecond time-of-day precision,
+// the user's line as a verbatim `>` blockquote, the reply in a fenced
+// block, and a closing session-end line.
+//
+// Every export here is a pure, self-contained function — no imports, and no
+// references outside its own body except calling its siblings in this file
+// by name — so the browser writer can splice each one's own `.toString()`
+// straight into chat.html's inline script, the same discipline
+// provBucketFor/provenanceChipFor already hold in chat-page-viz.mjs.
+
+/** An ISO-8601 string or epoch-ms number, as its own "HH:MM:SS.mmm" time of
+ *  day — read straight off the timestamp's own UTC digits, never converted
+ *  to a local zone, so it always names the wall-clock instant the session
+ *  actually ran the turn on. */
+export function sessionLogTimeOfDay(ts) {
+  const iso = typeof ts === "number" ? new Date(ts).toISOString() : String(ts);
+  return iso.slice(11, 23);
+}
+
+/** The session file's opening block: a `#` title naming the version and a
+ *  short session label (the id's first segment), a byline with the
+ *  calendar date, the started time, and — when given — the repo path, then
+ *  the `---` divider before the first turn. `repo` is optional: a browser
+ *  export has none, so that clause is simply left out rather than shown
+ *  empty. */
+export function sessionLogHeaderMarkdown({ version, sessionId, startedAt, repo }) {
+  const iso = typeof startedAt === "number" ? new Date(startedAt).toISOString() : String(startedAt);
+  const shortId = String(sessionId || "").split("-")[0].slice(0, 8);
+  const date = iso.slice(0, 10);
+  const time = sessionLogTimeOfDay(iso);
+  const bylineParts = [date, "started " + time];
+  if (repo) bylineParts.push("repo " + repo);
+  const byline = "*" + bylineParts.join(" · ") + "*";
+  return "# tmct chat " + version + " — session " + shortId + "\n\n" + byline + "\n\n---\n\n";
+}
+
+/** One turn's own Markdown block: a `###` heading naming the time of day and
+ *  the turn number, the VERBATIM user line as a `>` blockquote (no
+ *  rewriting, no truncation — whatever the recognizer actually saw), and
+ *  the reply in a fenced text block. Ends in a blank line so consecutive
+ *  turn blocks concatenate directly into one document, byte-identical to
+ *  the reference sample. An empty answer (the closing "/exit" marker) opens
+ *  and closes the fence with nothing between, rather than a stray blank
+ *  line inside it. */
+export function sessionLogTurnMarkdown({ startedAt, turnNumber, query, answer }) {
+  const time = sessionLogTimeOfDay(startedAt);
+  const body = answer ? answer + "\n" : "";
+  return "### " + time + " · turn " + turnNumber + "\n\n"
+    + "> " + query + "\n\n"
+    + "```text\n" + body + "```\n\n";
+}
+
+/** The closing block: a `---` divider and the session-end line naming the
+ *  end time and the total turn count (the closing "/exit" marker counts as
+ *  the last turn, so this number is always that marker's own turn number).
+ *  No leading blank line — the preceding turn block already supplied one. */
+export function sessionLogEndMarkdown({ endedAt, turnCount }) {
+  const time = sessionLogTimeOfDay(endedAt);
+  return "---\n\n*session end " + time + " — " + turnCount + " turn" + (turnCount === 1 ? "" : "s") + "*\n";
+}

package/src/services/sessions.mjs

@@ -1,7 +1,7 @@
 // sessions.mjs — chat sessions as first-class temporal graph data, like commits.
 //
 // A `tmct chat` session leaves two artifacts under the target repo:
-//   .tmct/session-<uuidv7>.log            — the human-readable transcript (chat.mjs)
+//   .tmct/session-<uuidv7>.md              — the human-readable transcript (chat-session.mjs, session-log-format.mjs)
 //   .tmct/sessions/session-<uuidv7>.jsonl — the STRUCTURED sidecar this module owns:
 //     {"type":"session", id, started, repo, tmctVersion}        (header line)
 //     {"type":"turn", ts, query, via, resolvedIds, answeredIds, miss}  (one per turn, flushed)
@@ -207,7 +207,7 @@ async function recordSessionMemory(graphFile, record, repoDirOverride = null) {
 
   let answers = new Map();
   try {
-    answers = parseSessionLog(await readFile(join(repoDir, ".tmct", `session-${record.id}.log`), "utf8"));
+    answers = parseSessionLog(await readFile(join(repoDir, ".tmct", `session-${record.id}.md`), "utf8"));
   } catch { /* no transcript (direct API callers) — record the requests alone */ }
 
   const utterances = [];
@@ -294,38 +294,72 @@ export function parseSessionJsonl(text) {
   return { id: String(header.id), started: String(header.started || ""), ended, turns };
 }
 
-// A transcript turn opens with an ISO-8601 ms timestamp line followed by the
-// echoed "> <query>" line (chat.mjs's logLines shape).
-const LOG_TS_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+// A transcript turn heading (session-log-format.mjs's sessionLogTurnMarkdown):
+// "### HH:MM:SS.mmm · turn N" — time of day only, no calendar date (the date
+// lives once, in the header byline). The header byline itself carries that
+// date: "*YYYY-MM-DD · started HH:MM:SS.mmm[ · repo ...]*".
+const MD_TURN_HEADING_RE = /^### (\d{2}:\d{2}:\d{2}\.\d{3}) · turn \d+$/;
+const MD_BYLINE_DATE_RE = /^\*(\d{4}-\d{2}-\d{2}) ·/;
 
 export { turnKey };
 
+/** The calendar date one UTC day after `dateStr` ("YYYY-MM-DD") — used to
+ *  carry the transcript's running date forward across a midnight rollover
+ *  (see parseSessionLog below). */
+function nextUtcDate(dateStr) {
+  const d = new Date(`${dateStr}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + 1);
+  return d.toISOString().slice(0, 10);
+}
+
 /**
- * Parse a human-readable session transcript (.tmct/session-<id>.log) into a
+ * Parse a human-readable session transcript (.tmct/session-<id>.md) into a
  * Map of turnKey(ts, query) → answer text. The transcript is the ONLY session
  * artifact that carries the answer PROSE (the structured sidecar records ids,
- * not text),
+ * not text).
+ *
+ * Each turn heading carries only a TIME of day (see MD_TURN_HEADING_RE above)
+ * — the calendar date is read once from the header byline and carried
+ * forward turn to turn, advancing a day whenever a heading's time reads
+ * EARLIER than the turn before it (a midnight rollover on a long session).
+ * The reconstructed `date + "T" + time + "Z"` is then byte-identical to the
+ * full ISO timestamp session-log-format.mjs's writer sliced the time out of,
+ * so it matches the sidecar's own `record.ts` under turnKey exactly.
  */
 export function parseSessionLog(text) {
   const lines = String(text ?? "").split("\n");
   const answers = new Map();
-  let open = null; // { ts, query, answerLines }
-  const close = () => {
-    if (!open) return;
-    while (open.answerLines.length && !open.answerLines.at(-1).trim()) open.answerLines.pop();
-    answers.set(turnKey(open.ts, open.query), open.answerLines.join("\n"));
-    open = null;
-  };
-  for (let i = 0; i < lines.length; i += 1) {
-    if (LOG_TS_RE.test(lines[i]) && lines[i + 1]?.startsWith("> ")) {
-      close();
-      open = { ts: lines[i], query: lines[i + 1].slice(2), answerLines: [] };
-      i += 1;
-    } else if (open) {
-      open.answerLines.push(lines[i]);
+  let date = null;
+  let lastTime = null;
+  let i = 0;
+  while (i < lines.length) {
+    if (date === null) {
+      const dateMatch = lines[i].match(MD_BYLINE_DATE_RE);
+      if (dateMatch) date = dateMatch[1];
+    }
+    const heading = date && lines[i].match(MD_TURN_HEADING_RE);
+    if (heading) {
+      const time = heading[1];
+      if (lastTime !== null && time < lastTime) date = nextUtcDate(date);
+      lastTime = time;
+      let j = i + 1;
+      if (lines[j] === "") j += 1;
+      const queryLine = lines[j];
+      if (queryLine?.startsWith("> ")) {
+        j += 1;
+        if (lines[j] === "") j += 1;
+        if (lines[j] === "```text") {
+          j += 1;
+          const answerLines = [];
+          while (j < lines.length && lines[j] !== "```") { answerLines.push(lines[j]); j += 1; }
+          answers.set(turnKey(`${date}T${time}Z`, queryLine.slice(2)), answerLines.join("\n"));
+          i = j + 1;
+          continue;
+        }
+      }
     }
+    i += 1;
   }
-  close();
   return answers;
 }
 

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

@@ -18,7 +18,7 @@
 import {
   DIRECTION_DELTA, WORLD_NAME, cellId, parseCellId, inBounds, chebyshevDistance, oneStepDirectionBetween,
 } from "../domain/spider-fly-world.mjs";
-import { foldSpiderFlyState, runSpiderFlyTick, startSpiderFlyGame } from "./spider-fly.mjs";
+import { foldSpiderFlyState, runSpiderFlyTick, startSpiderFlyGame, beliefSnapshotFor } from "./spider-fly.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";
@@ -66,6 +66,12 @@ const SPIDER_FLY_TOLD_RE = new RegExp(
   "i",
 );
 
+// The observable-facts read: "what does the fly see?" / "what can the
+// spider see?" — a closed vocabulary shape, styled after the other
+// game-lane regexes above, with the same optional numbered suffix
+// (SPIDER_FLY_ADDRESS_LEAD_RE's own "-<n>") for a board past one of a kind.
+const SPIDER_FLY_SEE_RE = /^what (?:does|can) the (spider|fly)(?:-(\d+))?\s+see[.!?\s]*$/i;
+
 const WORLD_OPENING_FALLBACK =
   "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.";
 
@@ -342,6 +348,48 @@ async function runTickAndRender({ planHolder, memoryDir, cache, toldFacts = [],
   };
 }
 
+// ---- the observable-facts read: "what does the fly see?" -----------------
+
+/** One `[id, cellId | null]` belief entry as a sentence: `"spider-1 is at
+ *  cell-3-4."` when observed/told, `"fly-2 has not been observed."`
+ *  otherwise — the same wording spider-fly-viz.mjs's own click-expand panel
+ *  (observedFactsHtml) renders, so the chat phrasing and the browser panel
+ *  never disagree about what an agent can see. */
+function observedFactSentence(id, believedCell) {
+  return believedCell ? `${id} is at ${believedCell}.` : `${id} has not been observed.`;
+}
+
+/** "what does the fly see?" / "what does the spider see?" rendered as plain
+ *  text: the same beliefSnapshotFor read spider-fly.mjs's own tick loop and
+ *  the browser panel already use, over the CURRENT board state — read-only,
+ *  no tick runs, nothing is written. Candidates are every OTHER live agent
+ *  of either kind; toldFacts is empty (a told position only ever arrives
+ *  fresh alongside a tick — see runToldFactTurn — so there is none standing
+ *  between ticks to read back here). */
+async function spiderFlyBeliefAnswer(match, { memoryDir, gameConfig = DEFAULT_GAME_CONFIG }) {
+  const kind = match[1].toLowerCase();
+  const num = match[2];
+  const rows = readFactRows(await loadMemory(memoryDir));
+  const state = foldSpiderFlyState(rows);
+  const observerId = resolveAgentId(kind, num, state);
+  if (!observerId) return noSuchAgentAnswer(kind, "addressee");
+  const observerCell = parseCellId(state.placements.get(observerId).cell);
+  const candidateIds = [...liveIdsOfKind("spider", state), ...liveIdsOfKind("fly", state)];
+  const visionRadius = kind === "spider"
+    ? gameConfig?.spiderFly?.spiderVisionRadius
+    : gameConfig?.spiderFly?.flyVisionRadius;
+  const belief = beliefSnapshotFor(observerId, observerCell, candidateIds, state, { visionRadius });
+  const entries = Object.entries(belief);
+  const text = entries.length
+    ? `${observerId} sees: ${entries.map(([id, cell]) => observedFactSentence(id, cell)).join(" ")}`
+    : `${observerId} is alone on the board — nothing else to see.`;
+  return {
+    text,
+    lane: "game-inform",
+    note: `SPIDER-FLY — belief snapshot rendered for ${observerId} via beliefSnapshotFor (read-only, no tick run)`,
+  };
+}
+
 /** The addressed teach-frame turn: resolve the addressee and the belief
  *  subject, resolve the told cell, and run ONE tick with that told-fact fed
  *  in. Told-facts are NOT persisted on the session slot across turns — each
@@ -526,6 +574,11 @@ export async function spiderFlyTurn(line, { planHolder, memoryDir, env, cache =
     return runToldFactTurn(told, { planHolder, memoryDir, cache, gameConfig });
   }
 
+  const seeMatch = String(line).trim().match(SPIDER_FLY_SEE_RE);
+  if (seeMatch) {
+    return spiderFlyBeliefAnswer(seeMatch, { memoryDir, gameConfig });
+  }
+
   if (SPIDER_FLY_TICK_RE.test(line)) {
     return runTickAndRender({ planHolder, memoryDir, cache, toldFacts: [], gameConfig });
   }