@polycode-projects/the-mechanical-code-talker 2.9.6 → 2.10.1

package/src/services/import-file.mjs

@@ -1,10 +1,14 @@
-// import-file.mjs — `tmct import --file <definition.txt>`: teach a plain-text
-// definition file, one sentence at a time, through the SAME recognizers the
-// live chat uses (runTurn) — no separate parser, no guessing.
+// import-file.mjs — `tmct import --file <definition.txt|facts.jsonl>`: teach a
+// definition file into a repo's memory. A plain-text file is taught one
+// sentence at a time through the SAME recognizers the live chat uses (runTurn)
+// — no separate parser, no guessing. A JSONL file (the shape `tmct extract` and
+// `tmct memory --export` emit — one {subject, predicate, object, provenance}
+// object per line) loads each fact straight into the store, so an exported
+// triple-store round-trips back in with its provenance intact.
 //
 // The report is loud on purpose: a definition file that half-teaches produces
 // a planner that finds wrong plans or no plans with no visible cause, so every
-// sentence's outcome is printed and any decline makes the caller exit non-zero.
+// line's outcome is printed and any decline makes the caller exit non-zero.
 //
 // `#` lines are comments (skipped, counted, never "declined") — a definition
 // file carries its own example prompts this way.
@@ -13,10 +17,34 @@ import { readFile } from "node:fs/promises";
 import { basename, resolve } from "node:path";
 
 import { runTurn, uuidv7 } from "./chat.mjs";
-import { loadMemory, readFactRows, appendFact, openConfiguredMemoryBackend } from "../adapters/memory/core.mjs";
+import { loadMemory, readFactRows, appendFact, appendFacts, openConfiguredMemoryBackend } from "../adapters/memory/core.mjs";
 import { loadConfig } from "../adapters/config.mjs";
 import { splitSentencesPreservingPaths } from "./sentences.mjs";
 
+/** A body line as a stored fact, or null when it is not a JSONL fact object.
+ *  A fact line JSON-parses to an object carrying string subject/predicate/
+ *  object; anything else (a plain sentence, malformed JSON, a JSON array) is
+ *  not one. */
+function parseFactLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("{")) return null;
+  let record;
+  try {
+    record = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+  if (!record || typeof record !== "object") return null;
+  const { subject, predicate, object } = record;
+  if (typeof subject !== "string" || typeof predicate !== "string" || typeof object !== "string") return null;
+  if (!subject || !predicate || !object) return null;
+  return {
+    subject, predicate, object,
+    provenance: typeof record.provenance === "string" ? record.provenance : "",
+    quantifier: typeof record.quantifier === "string" ? record.quantifier : "",
+  };
+}
+
 /**
  * Teach every sentence of `filePath` into `repoRoot`'s memory store.
  *
@@ -33,14 +61,48 @@ export async function importDefinitionFile(repoRoot, filePath, { env = process.e
 
   const lines = text.split("\n");
   const commentLines = lines.filter((l) => l.trim().startsWith("#"));
-  const body = lines.filter((l) => !l.trim().startsWith("#")).join("\n");
-  const sentences = splitSentencesPreservingPaths(body);
+  const bodyLines = lines.filter((l) => !l.trim().startsWith("#"));
+  const body = bodyLines.join("\n");
+
+  // A file whose every non-blank body line is a JSONL fact object is a
+  // triple-store dump, not prose — import each fact directly, keeping its own
+  // provenance, rather than pushing "{...}" through the sentence recognizer
+  // (which would decline it). This is the return leg for `tmct memory --export`
+  // and the browser pages' fact download.
+  const nonBlankBody = bodyLines.filter((l) => l.trim());
+  const factLines = nonBlankBody.map(parseFactLine);
+  const isFactFile = nonBlankBody.length > 0 && factLines.every(Boolean);
 
   // An injected handle (a caller mid-session, or a build script pinned to the
   // in-memory backend) is used as-is and left open — the caller owns it.
   const opened = injectedMemoryDir ? null : await openConfiguredMemoryBackend(root, env);
   const memoryDir = injectedMemoryDir ?? opened.dir;
   const close = opened ? opened.close : async () => {};
+
+  if (isFactFile) {
+    const importReport = [`${basename(abs)} — ${factLines.length} fact(s), ${commentLines.length} comment line(s) skipped`, ""];
+    // One batched write for the whole dump — a triple export can carry every
+    // seed fact, so a per-fact loop (load+write each) would be quadratic.
+    try {
+      await appendFacts(memoryDir, factLines.map((fact) => ({
+        subject: fact.subject, predicate: fact.predicate, object: fact.object,
+        provenance: fact.provenance || sourceTag, quantifier: fact.quantifier,
+      })));
+    } finally {
+      await close();
+    }
+    const imported = factLines.map((fact) => `${fact.subject} ${fact.predicate} ${fact.object}`);
+    // A triple dump can carry tens of thousands of facts, so the per-line echo
+    // is capped — enough to show the shape, not a wall that overflows a caller's
+    // output buffer.
+    const LIST_CAP = 20;
+    for (const rendered of imported.slice(0, LIST_CAP)) importReport.push(`  imported — ${rendered}`);
+    if (imported.length > LIST_CAP) importReport.push(`  … and ${imported.length - LIST_CAP} more fact(s)`);
+    importReport.push("", `${imported.length} fact(s) imported, 0 declined, ${commentLines.length} comment line(s) skipped`);
+    return { sentences: factLines.length, taught: imported, declined: [], comments: commentLines.length, report: importReport.join("\n") };
+  }
+
+  const sentences = splitSentencesPreservingPaths(body);
   const config = loadConfig(env, root);
 
   const taught = [];

package/src/services/ledger-viz.mjs

@@ -515,10 +515,15 @@ export function renderLedgerHtml({ rows, terms, edges, focus, contradictions, wo
   // the query-only wording even when the live bundle is offered — the dock's
   // own script swaps it for a teach-aware placeholder the moment it confirms
   // tmctLedger actually loaded (never claimed ahead of that confirmation).
+  // The example term skips anything under 3 characters — the SAME floor the
+  // dock's own miss-tips apply below — so a graph whose highest-degree term
+  // is a short stopword-shaped fragment (init:large corpora carry plenty:
+  // "os", "ip", "s3") never becomes the one example a visitor sees.
   const termSet = new Set((terms || []).map((t) => t.term));
+  const exampleTerm = (terms || []).find((t) => t && t.term && t.term.length >= 3);
   const placeholder = termSet.has("ishmael")
     ? "who is the grandfather of ishmael"
-    : (terms && terms.length ? `ask the graph… e.g. what is ${terms[0].term}` : "ask the graph…");
+    : (exampleTerm ? `ask the graph… e.g. what is ${exampleTerm.term}` : "ask the graph…");
   const dockHtml = hasMemChat
     ? `<div class="chat">
         <div class="chatlog" id="chatlog" aria-live="polite"></div>

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

@@ -346,6 +346,10 @@ ${THEME_TOKENS_CSS}
      negative margin equal to this padding, so it reads as one welded unit,
      not a label floating inside a box. */
   .hud, .chat, .tuning { background: var(--chrome-face); border: 1px solid var(--chrome-edge-lo); box-shadow: var(--chrome-shadow-raised); border-radius: 2px; padding: .6rem .75rem; }
+  /* the tuning strip matches the board's own width (not the wider stage-left
+     column it sits in) so the two line up as one visual stack, the same way
+     the board-frame below it is already centered at a fixed width. */
+  .tuning { width: ${BOARD_PX}px; max-width: 100%; margin: 0 auto; box-sizing: border-box; }
   .hud h2, .chat h2, .tuning h2 {
     font-family: ${MONO_STACK}; font-size: .68rem; letter-spacing: .1em; text-transform: uppercase; font-weight: 600;
     margin: -.6rem -.75rem .5rem; padding: .42rem .75rem;
@@ -357,12 +361,22 @@ ${THEME_TOKENS_CSS}
      at once now, so the agent count (and a naive card list's own height)
      can jump sharply; the panel must never grow the page underneath it. */
   .hud-list { max-height: 420px; overflow-y: auto; }
-  .hud-row { display: flex; flex-direction: column; gap: .1rem; padding: .4rem 0; border-top: 1px solid var(--chrome-edge-lo); box-shadow: inset 0 1px 0 var(--chrome-edge-hi); }
+  .hud-row { display: flex; align-items: flex-start; gap: .6rem; padding: .4rem 0; border-top: 1px solid var(--chrome-edge-lo); box-shadow: inset 0 1px 0 var(--chrome-edge-hi); }
   .hud-row:first-of-type { border-top: none; box-shadow: none; }
+  .hud-row.clickable { cursor: pointer; }
+  .hud-row.clickable:hover, .hud-row.clickable:focus-visible { background: var(--chrome-brass-soft); }
+  .hud-main { display: flex; flex-direction: column; gap: .1rem; flex: 1 1 auto; min-width: 0; }
   .hud-id { font-family: ${MONO_STACK}; font-size: .74rem; font-weight: 600; }
   .hud-id.spider { color: var(--taught); } .hud-id.fly { color: var(--fly); } .hud-id.egg { color: var(--muted); }
   .hud-goal { font-size: .85rem; }
   .hud-plan, .hud-belief { font-family: ${MONO_STACK}; font-size: .66rem; color: var(--muted); margin-top: .25rem; line-height: 1.4; padding-left: .5rem; border-left: 2px solid var(--chrome-brass); }
+  /* the click-expand facts panel (§28): beside the clicked spider/fly's own
+     row, never a separate popover or a second panel elsewhere on the page —
+     the same believedCellOf/beliefSnapshotFor read path spider-fly.mjs
+     already computes every tick for planning, rendered here as full
+     sentences instead of the compact believes:-line above. */
+  .hud-detail { flex: 1 1 auto; min-width: 0; font-family: ${MONO_STACK}; font-size: .64rem; line-height: 1.5; color: var(--chrome-well-ink); background: var(--chrome-well); border: 1px solid var(--chrome-edge-lo); box-shadow: var(--chrome-shadow-inset); border-radius: 2px; padding: .35rem .5rem; }
+  .hud-detail-title { text-transform: uppercase; letter-spacing: .06em; opacity: .75; margin-bottom: .2rem; }
   /* A stat-readout track: an inset "LCD" well, filled with a segmented pip
      texture (repeating-linear-gradient) instead of a smooth gradient bar —
      discrete resource units, the same reading-at-a-glance language a 90s
@@ -457,7 +471,7 @@ ${THEME_TOKENS_CSS}
 <body>
 <main>
   <div class="eyebrow">tmct &middot; spider and fly</div>
-  <h1>A spider in its web, a fly on the board — each planning against the other</h1>
+  <h1>Multiple competing planning agents</h1>
   <div class="stage">
     <div class="stage-left">
     <div class="tuning" id="tuning">
@@ -543,6 +557,10 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   const spriteLayer = el("spriteLayer");
   const threadTip = el("threadTip");
   const hudEl = el("hud");
+  // Which agent ids currently show their expanded observed-facts panel —
+  // survives renderHud() rebuilding the list's innerHTML every tick, since
+  // that's the only way this state can persist across a full re-render.
+  const expandedAgents = new Set();
   const chatlogEl = el("chatlog");
   const chatformEl = el("chatform");
   const chatqEl = el("chatq");
@@ -783,21 +801,59 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
     return '<div class="hud-belief">believes: ' + text + "</div>";
   }
 
+  // The full text rendering behind the click-expand panel: one sentence per
+  // other candidate the observer currently has a belief about, or "has not
+  // been observed" for a candidate it doesn't — the same belief map
+  // beliefLineHtml already compresses into a single line, spelled out in
+  // full beside the clicked agent instead of abbreviated above it.
+  function observedFactsHtml(observerId, belief) {
+    const entries = Object.entries(belief || {});
+    const lines = entries.length
+      ? entries.map(([id, cell]) => '<div class="hud-detail-line">'
+          + (cell ? esc(id) + " is at " + esc(cell) + "." : esc(id) + " has not been observed.")
+          + "</div>").join("")
+      : '<div class="hud-detail-line">nothing else is on the board yet.</div>';
+    return '<div class="hud-detail"><div class="hud-detail-title">' + esc(observerId) + " observes</div>" + lines + "</div>";
+  }
+
   function renderHud() {
     const ids = Object.keys(lastAgents).sort();
     if (!ids.length) { hudEl.innerHTML = '<div class="hud-empty">no agents on the board.</div>'; return; }
     hudEl.innerHTML = ids.map((id) => {
       const cls = classOfAgentId(id);
       const a = lastAgents[id];
-      return '<div class="hud-row"><span class="hud-id ' + esc(cls) + '">' + esc(id) + '</span>'
+      const clickable = cls === "spider" || cls === "fly";
+      const expanded = clickable && expandedAgents.has(id);
+      const main = '<div class="hud-main"><span class="hud-id ' + esc(cls) + '">' + esc(id) + '</span>'
         + '<span class="hud-goal">' + esc(goalById[id] || "watching\\u2026") + "</span>"
         + massBarHtml(cls, a.mass)
         + planLineHtml(a.plan)
         + beliefLineHtml(a.belief)
         + "</div>";
+      const attrs = clickable ? ' role="button" tabindex="0" aria-expanded="' + (expanded ? "true" : "false") + '"' : "";
+      return '<div class="hud-row' + (clickable ? " clickable" : "") + '" data-agent-id="' + esc(id) + '"' + attrs + '>'
+        + main + (expanded ? observedFactsHtml(id, a.belief) : "")
+        + "</div>";
     }).join("");
   }
 
+  function toggleAgentExpansion(id) {
+    if (!id) return;
+    if (expandedAgents.has(id)) expandedAgents.delete(id); else expandedAgents.add(id);
+    renderHud();
+  }
+  hudEl.addEventListener("click", (event) => {
+    const row = event.target.closest(".hud-row.clickable");
+    if (row) toggleAgentExpansion(row.dataset.agentId);
+  });
+  hudEl.addEventListener("keydown", (event) => {
+    if (event.key !== "Enter" && event.key !== " ") return;
+    const row = event.target.closest(".hud-row.clickable");
+    if (!row) return;
+    event.preventDefault();
+    toggleAgentExpansion(row.dataset.agentId);
+  });
+
   const threadGeometry = {
     parseCellId: (id) => tmctSpiderFly.parseCellId(id),
     cellId: (x, y) => tmctSpiderFly.cellId(x, y),

package/src/services/spider-fly.mjs

@@ -636,8 +636,11 @@ function stepPlan(fromCell, toCell) {
  *  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. */
-function beliefSnapshotFor(observerSubject, observerCell, candidateIds, state, opts) {
+ *  `{ [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;

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

@@ -18,6 +18,7 @@
 //     without it.
 import { runTurn, vocabExampleHint } from "../../services/chat.mjs";
 import { createInMemoryStore, normFactTerm, loadMemory, readFactRows } from "../../adapters/memory/core.mjs";
+import { serializeFactsJsonl } from "../../adapters/memory/export-jsonl.mjs";
 import { provenanceTagToSource } from "../../domain/memory/trust.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
@@ -147,4 +148,14 @@ export async function memoryStats(memoryDir) {
   return { total: rows.length, bandCounts, taught };
 }
 
-globalThis.tmctChat = { createChatSession, registerWinkModel, registerReferencePackProvider, registerLiveReferenceProvider, normFactTerm, vocabExampleHint, memoryStats, openPersistedStore };
+/**
+ * The session's whole triple store as JSONL — one
+ * { subject, predicate, object, provenance } object per line, the same shape
+ * `tmct extract` and `tmct memory --export` emit. Reads the live memory the
+ * same way memoryStats does; the page offers it as a download.
+ */
+export async function exportFactsJsonl(memoryDir) {
+  return serializeFactsJsonl(await loadMemory(memoryDir));
+}
+
+globalThis.tmctChat = { createChatSession, registerWinkModel, registerReferencePackProvider, registerLiveReferenceProvider, normFactTerm, vocabExampleHint, memoryStats, openPersistedStore, exportFactsJsonl };

package/src/surfaces/web/code-explorer-browser-entry.mjs

@@ -0,0 +1,79 @@
+// code-explorer-browser-entry.mjs — the esbuild entry for the code explorer's
+// LIVE chat dock (public/code-explorer.bundle.js / electron/renderer/
+// code-explorer.bundle.js). It mirrors ledger-browser-entry.mjs, but seeds the
+// full runTurn engine from a CODE graph instead of a memory payload: the dock
+// answers "what does X import" / "which functions call Y" over the loaded
+// graph, the same compositional shapes the hint rail suggests.
+//
+// The graph enters through source.mjs's provider seam — the same seam the CLI
+// and HTTP surfaces read — so runTurn's symbol-grain lanes see the whole
+// payload, while parseEntities builds the coarse graph the flat lanes read.
+// Gitignored, built fresh by scripts/build-code-explorer-bundle.mjs; the page
+// degrades to a static view when it is absent (renderCodeExplorerHtml's own
+// contract), so nothing here is ever published.
+import { runTurn } from "../../services/chat.mjs";
+import { createInMemoryStore, normFactTerm } from "../../adapters/memory/core.mjs";
+import { parseEntities } from "../../domain/codegraph.mjs";
+import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
+import { registerWinkModel } from "../../adapters/wink-model.mjs";
+import * as source from "../../adapters/source.mjs";
+import { computeCodeExplorerData, computeCodeLedger } from "../../services/code-explorer-viz.mjs";
+import { generateCodeHints } from "../../domain/code-explorer-hints.mjs";
+
+/**
+ * A browser code-explorer session over the real turn engine. Registers the
+ * loaded payload with source.mjs's provider seam, parses the coarse graph, and
+ * dispatches every turn through the same runTurn the CLI runs. Teaches land in
+ * an in-memory store so a taught fact never touches disk. Returns
+ * { sessionId, turn }, the createChatSession shape the page's dock expects.
+ */
+export function createCodeExplorerSession({ graphPayload } = {}) {
+  const payload = graphPayload || { individuals: [], objectProperties: [] };
+  source.registerProvider(() => payload);
+
+  const graph = parseEntities(payload);
+  const memoryDir = createInMemoryStore();
+  const lexicon = loadLexicon();
+  const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
+  // A stable virtual path: the provider answers every fetch, so no file is
+  // ever read, but the code lanes still do path math (join/dirname) on it.
+  const config = { graphFile: "graph.json" };
+
+  let focus = null;
+  let last = null;
+  let planState = null;
+
+  return {
+    sessionId,
+    async turn(line) {
+      let result;
+      try {
+        result = await runTurn(line, {
+          config, source, graph, focus, last, memoryDir, sessionId,
+          env: {}, lexicon, vocabHint: "", planState,
+        });
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return { answer: `Something went wrong answering that (${message}). Try rephrasing, or /help.`, end: false, record: null };
+      }
+      focus = result.focus;
+      last = result.last;
+      if ("planState" in result) planState = result.planState;
+      return { answer: result.answer, end: Boolean(result.end), record: result.record ?? null };
+    },
+  };
+}
+
+// Exposed for the page's inline client: the re-derivation helpers so a graph
+// swapped through the desktop picker re-renders without duplicating logic, plus
+// the wink loader hook registerWinkModel and normFactTerm the dock shares with
+// the ledger page.
+globalThis.tmctCodeExplorer = {
+  createCodeExplorerSession,
+  computeCodeExplorerData,
+  computeCodeLedger,
+  generateCodeHints,
+  parseEntities,
+  normFactTerm,
+  registerWinkModel,
+};