@polycode-projects/the-mechanical-code-talker 4.0.1 → 4.1.0

package/src/services/code-explorer-viz.mjs

@@ -2,11 +2,14 @@
 // a title bar (graph source, Open graph…/Open repo…), an explorer sidebar
 // reading each import/call/contains edge back as a plain sentence, a chat
 // centre over the same graph with a rail of suggested questions, and a status
-// bar carrying the graph's own counts. The chat session seeds BOTH the loaded
-// code graph and chat.html's general-knowledge bands (./chat-seed.json,
-// fetched lazily at runtime), so one conversation answers "what is a queue"
-// and "what imports src/core/model.mjs" alike — and degrades to graph-only
-// when the seed asset is unavailable.
+// bar carrying the graph's own counts. Clicking a term asks the engine what
+// relates to it (askRelatedFacts, over tmct_ask) and renders the answer, so the
+// sidebar and the chat put the same question to the same place.
+//
+// The chat session seeds BOTH the loaded code graph and chat.html's
+// general-knowledge bands (./chat-seed.json, fetched lazily at runtime), so one
+// conversation answers "what is a queue" and "what imports src/core/model.mjs"
+// alike — and degrades to graph-only when the seed asset is unavailable.
 //
 // The derivations are pure so the shell, the packaging scripts, and the unit
 // tests all share one code path; renderCodeExplorerHtml builds one
@@ -18,24 +21,14 @@
 
 import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText } from "./viz-theme.mjs";
 import { generateCodeHints } from "../domain/code-explorer-hints.mjs";
+import { phraseForRelation } from "../domain/ask-vocab.mjs";
+import { fetchWithProgress } from "./memory-panel-viz.mjs";
 
-// Third-person verb for each stored relation kind, symbol grain folded onto its
-// coarse sibling. A kind with no row here reads back as itself, never breaking
-// the sentence.
-const EDGE_PHRASE = new Map([
-  ["imports", "imports"],
-  ["calls", "calls"], ["callsSymbol", "calls"],
-  ["contains", "contains"],
-  ["defines", "defines"],
-  ["inherits", "inherits from"],
-  ["tests", "tests"],
-  ["touches", "touches"], ["touchesSymbol", "touches"],
-  ["cochange", "co-changes with"],
-  ["reexports", "re-exports"],
-]);
-
+// Third-person verb for each stored relation kind, symbol grain folded onto
+// its coarse sibling — derived from ask-vocab.mjs's own RELATIONS table
+// rather than a second hand-curated relation-verb table.
 export function edgePhrase(kind) {
-  return EDGE_PHRASE.get(String(kind || "")) || String(kind || "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+  return phraseForRelation(kind);
 }
 
 // Both packagers (build-electron-app.mjs, build-demo-site.mjs) place
@@ -133,11 +126,7 @@ const CLIENT_JS = String.raw`
   };
   var session = null;
 
-  function esc(s) {
-    return String(s == null ? "" : s).replace(/[&<>"']/g, function (c) {
-      return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c];
-    });
-  }
+  var esc = ${escapeHtml.toString()};
 
   function renderStats(data) {
     var s = data.ledger.stats;
@@ -155,11 +144,37 @@ const CLIENT_JS = String.raw`
     els.factTotal.textContent = (edges + seedState.facts).toLocaleString();
   }
 
-  function renderFocusRows(data) {
+  // "What relates to the focus", put to the engine. askRelatedFacts asks
+  // tmct_ask one question per relation kind the loaded graph carries, in both
+  // directions, and hands back the answers' own typed rows — the same ask()
+  // this page's chat turns reach, so the panel and the conversation answer one
+  // question one way. Null on the static page, which has no engine to ask.
+  function askRelated(focus) {
+    if (!api || !api.askRelatedFacts || !focus) return null;
+    try {
+      return api.askRelatedFacts(DATA.payload, focus);
+    } catch (e) {
+      console.warn("tmct code explorer: the related-facts ask failed, splitting the row list instead", e);
+      return null;
+    }
+  }
+
+  function rowKey(r) { return JSON.stringify([r.s, r.kind, r.o]); }
+
+  function renderFocusRows(data, related) {
     var focus = data.focus;
     var rows = data.ledger.rows;
-    var near = rows.filter(function (r) { return r.s === focus || r.o === focus; });
-    var rest = rows.filter(function (r) { return r.s !== focus && r.o !== focus; });
+    // The engine's answer whenever it grounded one. The row list's own split is
+    // what is left when there is no engine (the static page) or when every
+    // question came back parsed as something else — an identifier that is
+    // itself a relation verb reads as a question about the verb.
+    var grounded = Boolean(related && related.grounded);
+    var near = grounded ? related.rows : rows.filter(function (r) { return r.s === focus || r.o === focus; });
+    var nearKeys = {};
+    near.forEach(function (r) { nearKeys[rowKey(r)] = true; });
+    // Whatever the neighbourhood did not already name, in degree order: a bulk
+    // view of the rest of the graph, which is a fold and not a question.
+    var rest = rows.filter(function (r) { return !nearKeys[rowKey(r)]; });
     var ordered = near.concat(rest);
     els.ledger.innerHTML = ordered.map(function (r) {
       var hot = (r.s === focus || r.o === focus) ? " row-focus" : "";
@@ -168,7 +183,9 @@ const CLIENT_JS = String.raw`
         + '<span class="verb">' + esc(r.phrase) + '</span> '
         + '<button class="term" data-term="' + esc(r.o) + '">' + esc(r.o) + '</button>'
         + '</li>';
-    }).join("") || '<li class="row muted">no edges in this graph.</li>';
+    }).join("") || (grounded
+      ? '<li class="row muted">nothing in this graph relates to ' + esc(focus) + '.</li>'
+      : '<li class="row muted">no edges in this graph.</li>');
     els.focus.textContent = focus || "—";
   }
 
@@ -188,7 +205,7 @@ const CLIENT_JS = String.raw`
 
   function mountView(data) {
     renderStats(data);
-    renderFocusRows(data);
+    renderFocusRows(data, askRelated(data.focus));
     renderHints(data);
   }
 
@@ -233,23 +250,7 @@ const CLIENT_JS = String.raw`
   function seedNote(text) { if (els.seedStatus) els.seedStatus.textContent = text; }
   function mbText(n) { return (n / 1048576).toFixed(1); }
 
-  async function fetchTextWithProgress(url, onProgress) {
-    var res = await fetch(url);
-    if (!res.ok) throw new Error("HTTP " + res.status);
-    var total = Number(res.headers.get("content-length")) || 0;
-    if (!res.body || !res.body.getReader) return res.text();
-    var reader = res.body.getReader();
-    var chunks = [];
-    var loaded = 0;
-    for (;;) {
-      var step = await reader.read();
-      if (step.done) break;
-      chunks.push(step.value);
-      loaded += step.value.byteLength;
-      onProgress(loaded, total);
-    }
-    return new Blob(chunks).text();
-  }
+  var fetchWithProgress = ${fetchWithProgress.toString()};
 
   async function loadSeed() {
     try {
@@ -258,9 +259,10 @@ const CLIENT_JS = String.raw`
         seedNote("loading general knowledge…");
         text = await window.tmctDesktop.readSeed();
       } else {
-        text = await fetchTextWithProgress("./chat-seed.json" + SEED_QUERY, function (loaded, total) {
+        var seedBlob = await fetchWithProgress("./chat-seed.json" + SEED_QUERY, function (loaded, total) {
           seedNote("loading general knowledge… " + mbText(loaded) + (total ? " of " + mbText(total) : "") + " MB");
         });
+        text = await seedBlob.text();
       }
       if (text) {
         seedState.payload = JSON.parse(text);

package/src/services/ingest-viz.mjs

@@ -26,46 +26,20 @@
 // input. scripts/build-demo-site.mjs calls it directly and writes the result
 // to public/ingest.html, after ingest-browser.bundle.js already exists.
 import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml } from "./viz-theme.mjs";
-import { bandLabelFor, statsSummaryLine, clearSiteAssetCaches, fetchWithProgress, renderStatsPanelInto } from "./memory-panel-viz.mjs";
+import {
+  bandLabelFor,
+  statsSummaryLine,
+  clearSiteAssetCaches,
+  fetchWithProgress,
+  renderStatsPanelInto,
+  loadProgressLine,
+  factTripleParts,
+} from "./memory-panel-viz.mjs";
+import { loadWinkVendor } from "./viz-boot.mjs";
+import { cloneMemoryPayload } from "../adapters/memory/core.mjs";
 
 const DEFAULT_TITLE = "the-mechanical-code-talker — ingest";
 
-/** One grounded fact as a canonical triple line — subject, predicate, object,
- *  each in its own cell so the pane can align them. Pure and
- *  `.toString()`-splice safe (no outer refs): the inline script splices this
- *  in and calls it per row. */
-export function factTripleParts(fact) {
-  return {
-    subject: String((fact && fact.subject) || ""),
-    predicate: String((fact && fact.predicate) || ""),
-    object: String((fact && fact.object) || ""),
-    provenance: String((fact && fact.provenance) || ""),
-  };
-}
-
-/** The boot statusline while the big assets stream in — the same aggregator
- *  chat-page-viz.mjs's own loadProgressLine is (kept as this page's own copy
- *  rather than a shared import — the two pages' boot lines diverge slightly
- *  and neither is a collaborator the other calls). `parts` is an array of
- *  { loaded, total } byte counts (total 0 when the response carried no
- *  Content-Length); with no usable total the line shows loaded bytes alone
- *  rather than inventing a denominator. Self-contained, `.toString()`-splice
- *  safe. */
-export function loadProgressLine(parts) {
-  const mb = (n) => (n / 1048576).toFixed(1);
-  let loaded = 0;
-  let total = 0;
-  let totalKnown = true;
-  for (const p of parts || []) {
-    loaded += (p && p.loaded) || 0;
-    if (p && p.total > 0) total += p.total;
-    else totalKnown = false;
-  }
-  return totalKnown && total > 0
-    ? "loading the engine… " + mb(loaded) + " MB / " + mb(total) + " MB"
-    : "loading the engine… " + mb(loaded) + " MB";
-}
-
 /** The self-contained ingest page. Pure — the same output for the same
  *  `title` every time; every piece of state (the session, each grounded fact)
  *  is computed live in the browser once the sibling ingest bundle loads. */
@@ -440,30 +414,14 @@ ${THEME_TOKENS_CSS}
       console.warn("tmct ingest: chat-seed.json unavailable — starting unseeded", err);
     }
   }
-  function cloneSeed() {
-    if (!seedPayload) return null;
-    try { return structuredClone(seedPayload); } catch { return JSON.parse(JSON.stringify(seedPayload)); }
-  }
+  const cloneMemoryPayload = ${cloneMemoryPayload.toString()};
   function newSession() {
-    return window.tmctIngest.createIngestSession({ seedPayload: cloneSeed(), vocabSeeded: Boolean(seedPayload) });
+    return window.tmctIngest.createIngestSession({ seedPayload: cloneMemoryPayload(seedPayload), vocabSeeded: Boolean(seedPayload) });
   }
 
   // ---- engine boot ---------------------------------------------------------
-  const WINK_LOAD_TIMEOUT_MS = 8000;
-  async function tryLoadWink() {
-    let settled = false;
-    const timeout = new Promise((_, reject) => setTimeout(() => { if (!settled) reject(new Error("wink load stalled")); }, WINK_LOAD_TIMEOUT_MS));
-    try {
-      const mod = await Promise.race([import("./vendor/wink.js"), timeout]);
-      settled = true;
-      window.tmctIngest.registerWinkModel(() => ({ winkNLP: mod.winkNLP, model: mod.model }));
-      return "loaded";
-    } catch (err) {
-      settled = true;
-      console.warn("tmct ingest: the wink vendor asset failed to load; the recognizer needs it to split and parse sentences", err);
-      return "unavailable";
-    }
-  }
+  const loadWinkVendor = ${loadWinkVendor.toString()};
+  const tryLoadWink = loadWinkVendor({ register: (factory) => window.tmctIngest.registerWinkModel(factory) });
 
   // The deploy's own version, read off the service worker file the build
   // already stamps — the only same-origin place the number exists at runtime

package/src/services/ledger-viz.mjs

@@ -15,8 +15,10 @@
 // doesn't do: it reads the checked-in chat-dock engine bundle.
 
 import { loadMemory, readFactRows, findContradictions, normFactTerm } from "../adapters/memory/core.mjs";
-import { THEME_TOKENS_CSS, MONO_STACK, escapeHtml, embedJson } from "./viz-theme.mjs";
+import { THEME_TOKENS_CSS, MONO_STACK, escapeHtml, embedJson, countLabel, TOKENS } from "./viz-theme.mjs";
 import { createTicker, prefersReducedMotion } from "./viz-ticker.mjs";
+import { bfsLevels } from "../domain/planning.mjs";
+import { pluralOf } from "../domain/inflect.mjs";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
@@ -33,23 +35,33 @@ const DASH_SANS_STACK = `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
 // themes — a deliberate departure from THEME_TOKENS_CSS's light/dark switch,
 // which every other generated page still follows. --taught/--corpus/--entail/
 // --alert stay the shared semantic provenance tokens; here they're pinned to
-// their dark-theme-friendly values (viz-theme.mjs's own dark token table) so
-// the palette that ships in dark mode elsewhere is what this page always
-// shows. viz-theme.mjs exports only the assembled THEME_TOKENS_CSS string,
-// not its per-mode token table, so the dark set is restated here from that
-// table rather than recomputed.
-const DASH_DARK_CHROME_CSS = `
+// their dark-theme-friendly values, read straight off viz-theme.mjs's own
+// exported TOKENS.dark table so this page's palette can never drift from the
+// one every other generated page's dark mode uses. The tier alphas (.35/.65/1)
+// match TOKENS's own tier scale; the four "soft" tints use higher alphas than
+// THEME_TOKENS_CSS's shared soft tokens on purpose — this dashboard chrome
+// wants a more visible tint against its always-dark background than the
+// light/dark-switching pages need, so those four alphas stay page-specific.
+function hexRgb(hex) {
+  const n = parseInt(hex.slice(1), 16);
+  return `${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}`;
+}
+const DASH_DARK_CHROME_CSS = (() => {
+  const t = TOKENS.dark;
+  const [taught, corpus, entail] = [hexRgb(t.taught), hexRgb(t.corpus), hexRgb(t.entail)];
+  return `
   :root { color-scheme: dark; }
   body {
-    --bg: #15181C; --ink: #E7E5DF; --muted: #9A9E95; --line: #2B3036; --card: #1C2126;
-    --taught: #5FBE8B; --corpus: #6C93BF; --entail: #D9A554; --alert: #D08070;
-    --taught-t1: rgba(95,190,139,.35); --taught-t2: rgba(95,190,139,.65); --taught-t3: rgba(95,190,139,1);
-    --corpus-t1: rgba(108,147,191,.35); --corpus-t2: rgba(108,147,191,.65); --corpus-t3: rgba(108,147,191,1);
-    --entail-t1: rgba(217,165,84,.35); --entail-t2: rgba(217,165,84,.65); --entail-t3: rgba(217,165,84,1);
-    --taught-soft: rgba(95,190,139,.14); --corpus-soft: rgba(108,147,191,.14);
-    --entail-soft: rgba(217,165,84,.16); --alert-soft: rgba(208,128,112,.16);
+    --bg: ${t.bg}; --ink: ${t.ink}; --muted: ${t.muted}; --line: ${t.line}; --card: ${t.card};
+    --taught: ${t.taught}; --corpus: ${t.corpus}; --entail: ${t.entail}; --alert: ${t.alert};
+    --taught-t1: rgba(${taught},.35); --taught-t2: rgba(${taught},.65); --taught-t3: rgba(${taught},1);
+    --corpus-t1: rgba(${corpus},.35); --corpus-t2: rgba(${corpus},.65); --corpus-t3: rgba(${corpus},1);
+    --entail-t1: rgba(${entail},.35); --entail-t2: rgba(${entail},.65); --entail-t3: rgba(${entail},1);
+    --taught-soft: rgba(${taught},.14); --corpus-soft: rgba(${corpus},.14);
+    --entail-soft: rgba(${entail},.16); --alert-soft: rgba(${hexRgb(t.alert)},.16);
   }
 `;
+})();
 
 /** Read the checked-in browser memory-ask-engine bundle
  *  (`src/surfaces/web/memory-ask-browser.bundle.js`) — the real memory-graph answer engine
@@ -453,7 +465,7 @@ function dashboardHtml(stats, { fresh = false } = {}) {
       <div class="tile">
         <span class="tile-label">facts.total</span>
         <span class="tile-value">${total}</span>
-        <span class="tile-sub">${terms} term${terms === 1 ? "" : "s"} tracked</span>
+        <span class="tile-sub">${countLabel(terms, "term")} tracked</span>
       </div>
       <div class="tile tile-tier">
         <span class="tile-label">facts.by-tier</span>
@@ -467,7 +479,7 @@ function dashboardHtml(stats, { fresh = false } = {}) {
       <div class="tile${qualityCls}">
         <span class="tile-label">data.quality</span>
         <span class="tile-value">${s.contradictionCount || 0}</span>
-        <span class="tile-sub">term${s.contradictionCount === 1 ? "" : "s"} with more than one answer</span>
+        <span class="tile-sub">${s.contradictionCount === 1 ? "term" : pluralOf("term")} with more than one answer</span>
       </div>
     </div>
     <div class="barpanels">
@@ -545,7 +557,7 @@ export function renderLedgerHtml({ rows, terms, edges, focus, contradictions, wo
   const ledgerJson = embedJson({ rows: rows || [], terms: terms || [], edges: edges || [], focus: focus || null, contradictions: contradictions || [], worthALook: worthALook || null, meta: meta || { shown: 0, total: 0, truncated: false }, focusDigest: focusDigest || null, digestStructures: Array.isArray(digestStructures) ? digestStructures : [] });
   const payloadJson = embedJson(payload || { individuals: [], objectProperties: [] });
   const shown = meta?.shown ?? (rows || []).length;
-  const title = `tmct ledger — ${shown} fact${shown === 1 ? "" : "s"}${focus ? ` (focus: ${escapeHtml(focus)})` : ""}`;
+  const title = `tmct ledger — ${countLabel(shown, "fact")}${focus ? ` (focus: ${escapeHtml(focus)})` : ""}`;
   const bundleStr = typeof memoryAskBundle === "string" ? memoryAskBundle : "";
   const hasMemChat = bundleStr.length > 0;
   // The placeholder is honest: the canonical exchange only when its terms are
@@ -833,6 +845,11 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
   // escapeHtml/pct by their real names) resolve without a second copy.
   const escapeHtml = esc;
   const pct = ${pct.toString()};
+  // pluralOf underlies countLabel's own default-parameter lookup — spliced
+  // ahead of it so that lookup resolves the same way it does node-side.
+  const pluralOf = ${pluralOf.toString()};
+  const countLabel = ${countLabel.toString()};
+  const bfsLevels = ${bfsLevels.toString()};
   const tierTileHtml = ${tierTileHtml.toString()};
   const microbarsHtml = ${microbarsHtml.toString()};
   const dashboardHtml = ${dashboardHtml.toString()};
@@ -965,7 +982,7 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
       : "";
     let html = '<div class="focuscard"><div class="term">' + esc(focus) + "</div>" +
       '<div class="klass">' + (klass ? esc(klass.phrase + " " + klass.o) : "no class recorded") + "</div>" +
-      '<div class="stats">' + all.length + " facts &middot; " + srcs.size + " source" + (srcs.size === 1 ? "" : "s") +
+      '<div class="stats">' + countLabel(all.length, "fact") + " &middot; " + countLabel(srcs.size, "source") +
       (dates.length ? " &middot; first " + esc(dates[0].slice(0, 10)) + " &middot; last " + esc(dates[dates.length - 1].slice(0, 10)) : "") + "</div>" + digestHtml + "</div>";
     const bracketed = new Set();
     for (const fam of FAMS) {
@@ -1028,13 +1045,16 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
     if (!focus) return;
     const color = { taught: cssVar("--taught"), corpus: cssVar("--corpus"), entailed: cssVar("--entail"), entail: cssVar("--entail") };
     const lineC = cssVar("--line"), inkC = cssVar("--ink");
-    const hop1 = new Set(), hop2 = new Set();
-    for (const e of LEDGER.edges) { if (e.s === focus) hop1.add(e.o); if (e.o === focus) hop1.add(e.s); }
-    hop1.delete(focus);
-    for (const e of LEDGER.edges) {
-      if (hop1.has(e.s) && e.o !== focus && !hop1.has(e.o)) hop2.add(e.o);
-      if (hop1.has(e.o) && e.s !== focus && !hop1.has(e.s)) hop2.add(e.s);
-    }
+    const neighborsOf = (term) => {
+      const out = [];
+      for (const e of LEDGER.edges) {
+        if (e.s === term) out.push(e.o);
+        else if (e.o === term) out.push(e.s);
+      }
+      return out;
+    };
+    const [hop1Level, hop2Level] = bfsLevels(focus, neighborsOf, { maxDepth: 2 });
+    const hop1 = new Set(hop1Level || []), hop2 = new Set(hop2Level || []);
     const cx = w / 2, cy = h / 2, r1 = 42, r2 = 68;
     const pos = { [focus]: { x: cx, y: cy } };
     const place = (set, r) => { const a = [...set].sort(); a.forEach((t, i) => { const ang = (2 * Math.PI * i) / a.length - Math.PI / 2; pos[t] = { x: cx + r * Math.cos(ang), y: cy + r * Math.sin(ang) }; }); };
@@ -1271,7 +1291,7 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
             const fresh = tmctLedger.computeLedgerDataFromPayload(s.memoryDir.payload, {});
             applyLedgerData(fresh);
             const skipped = sentences.length - grounded;
-            statusEl.textContent = sentences.length + " sentence" + (sentences.length === 1 ? "" : "s")
+            statusEl.textContent = countLabel(sentences.length, "sentence")
               + ", " + grounded + " added" + (skipped ? ", " + skipped + " skipped" : "");
           } catch {
             statusEl.textContent = "something went wrong ingesting that";
@@ -1323,7 +1343,7 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
         researchPlayBtn.setAttribute("aria-pressed", String(st.playing));
         researchStatusEl.textContent = !researchQueue ? ""
           : researchQueue.complete
-            ? 'research "' + researchQueue.topic + '" complete \\u2014 ' + researchQueue.done.length + " topic" + (researchQueue.done.length === 1 ? "" : "s")
+            ? 'research "' + researchQueue.topic + '" complete \\u2014 ' + countLabel(researchQueue.done.length, "topic")
             : researchQueue.done.length + " done \\u00b7 " + researchQueue.pending.length + " queued";
       }
 

package/src/services/memory-panel-viz.mjs

@@ -181,3 +181,41 @@ export function renderStatsPanelInto(panelEl, stats, opts) {
     }
   }
 }
+
+/** The boot statusline while the big engine assets stream in — byte-identical
+ *  across research-viz.mjs and ingest-viz.mjs, each commenting that it uses
+ *  "the same aggregator" as the other. `parts` is an array of { loaded, total }
+ *  byte counts (total 0 when a response carried no Content-Length); with no
+ *  usable total the line shows loaded bytes alone rather than inventing a
+ *  denominator. Self-contained, `.toString()`-splice safe. */
+export function loadProgressLine(parts) {
+  const mb = (n) => (n / 1048576).toFixed(1);
+  let loaded = 0;
+  let total = 0;
+  let totalKnown = true;
+  for (const p of parts || []) {
+    loaded += (p && p.loaded) || 0;
+    if (p && p.total > 0) total += p.total;
+    else totalKnown = false;
+  }
+  return totalKnown && total > 0
+    ? "loading the engine… " + mb(loaded) + " MB / " + mb(total) + " MB"
+    : "loading the engine… " + mb(loaded) + " MB";
+}
+
+/** One learned/grounded fact as its three canonical cells, plus whichever of
+ *  the two per-page provenance fields the caller's fact objects carry: `source`
+ *  (research.html's source key, e.g. "taught"/"seed:conceptnet" — used for the
+ *  tone dot) and `provenance` (ingest.html's raw ' | '-joined tag string —
+ *  shown verbatim). Both default to "" when the fact object doesn't carry
+ *  that field, so either page reads back only the one it populated. Pure,
+ *  `.toString()`-splice safe. */
+export function factTripleParts(fact) {
+  return {
+    subject: String((fact && fact.subject) || ""),
+    predicate: String((fact && fact.predicate) || ""),
+    object: String((fact && fact.object) || ""),
+    source: String((fact && fact.source) || ""),
+    provenance: String((fact && fact.provenance) || ""),
+  };
+}

package/src/services/mud-editor.mjs

@@ -12,11 +12,14 @@
 // point is "change what this world is made of" has to speak the vocabulary the
 // world is actually written in, and neither table is a superset of the other.
 //
-// No imports: every export here is `.toString()`-splice-safe, the same discipline
-// adventure-editor.mjs and the *-viz render-glue functions hold — mud-viz.mjs
-// splices these straight into mud.html's inline script, which captures a
-// function's own source text and nothing it closes over. A splice-safe function
-// carries its whole dependency graph inside its own body.
+// Every export here but wordBeforeCursor is written locally, and is
+// `.toString()`-splice-safe, the same discipline adventure-editor.mjs and the
+// *-viz render-glue functions hold — mud-viz.mjs splices these straight into
+// mud.html's inline script, which captures a function's own source text and
+// nothing it closes over. A splice-safe function carries its whole dependency
+// graph inside its own body. wordBeforeCursor is a re-export of viz-theme.mjs's
+// shared implementation, itself self-contained and splice-safe the same way —
+// this module no longer keeps its own copy of it.
 //
 // Two predicate families sync differently, for the reason adventure-editor.mjs's
 // own header sets out:
@@ -34,6 +37,8 @@
 //     that fails to parse this keystroke must never be read as "this fact is
 //     gone".
 
+export { wordBeforeCursor } from "./viz-theme.mjs";
+
 const PLACEMENT_KIND = "placement";
 const OPENNESS_KIND = "openness";
 const MASS_KIND = "mass";
@@ -301,13 +306,3 @@ export function planMudEditorSync(rows, state, triples) {
   }
   return { toAppend, toRemoveIds };
 }
-
-/** The word immediately before `cursorPos` in `text` — a run of letters, digits
- *  and hyphens, the shape this vocabulary's own terms take ("underground-space",
- *  "mole-1"). Empty when the cursor sits after whitespace or punctuation with no
- *  word directly behind it. Pure. */
-export function wordBeforeCursor(text, cursorPos) {
-  const head = String(text || "").slice(0, cursorPos);
-  const m = head.match(/[A-Za-z][A-Za-z0-9-]*$/);
-  return m ? m[0].toLowerCase() : "";
-}

package/src/services/mud-turn.mjs

@@ -50,10 +50,12 @@ import { fnv1a32 } from "../domain/hash.mjs";
 import { bfsLevels } from "../domain/planning.mjs";
 import { loadMemory, readFactRows } from "../adapters/memory/core.mjs";
 import { DEFAULT_GAME_CONFIG, mudMassDrainPerTurn } from "../domain/game-config.mjs";
+import { predatorSubjects } from "../domain/mud-facts.mjs";
 import {
   foldWorldState, worldActionRows, runWorldCommand, recordTold, recordExamined,
   recordMassDrain, personKnowledgeLines, objectClassChain, diggableDirections,
   isOutOfPlay, outOfPlayReasonOf, outOfPlayPhrase, massDrainPerTurnOf,
+  parseSnapshotSubject,
 } from "./adventure.mjs";
 
 const FOOD_CLASS = "food";
@@ -61,7 +63,6 @@ const LATERAL_DIRECTIONS = ["north", "south", "east", "west"];
 // Deep enough to cross a whole burrow without letting one character's
 // pathfinder walk a whole grown world every tick.
 const WALK_SEARCH_DEPTH = 8;
-const SNAPSHOT_RE = /^(.+)@turn(\d+)$/;
 
 const EXIT_TOWARD_FOOD_CHANCE = 0.5;
 const EDGE_FOLLOW_DIG_CHANCE = 0.25;
@@ -208,8 +209,8 @@ function roomsStoodIn(rows, character) {
   const visited = new Set();
   for (const row of worldActionRows(rows)) {
     if (row.predicate !== "mgx:currently-in") continue;
-    const snapshot = SNAPSHOT_RE.exec(row.subject);
-    if ((snapshot ? snapshot[1] : row.subject) !== character) continue;
+    const snapshot = parseSnapshotSubject(row.subject);
+    if ((snapshot ? snapshot.base : row.subject) !== character) continue;
     visited.add(row.object);
   }
   return visited;
@@ -220,9 +221,8 @@ function roomsStoodIn(rows, character) {
  *  funnel straight to the den, since the unvisited room nearest the burrow is
  *  exactly where the fox lives. The den stays reachable by the food gamble
  *  below, which is a gamble and is meant to be. */
-const predatorRooms = (rows, state) => new Set((rows || [])
-  .filter((r) => r.predicate === "mgx:is-predator" && r.object === "true")
-  .map((r) => state.placements.get(r.subject)?.object)
+const predatorRooms = (rows, state) => new Set(predatorSubjects(rows)
+  .map((subject) => state.placements.get(subject)?.object)
   .filter(Boolean));
 
 /**