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

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

@@ -2,17 +2,18 @@
 // (built by scripts/build-chat-bundle.mjs).
 //
 // Unlike memory-ask-browser-entry.mjs (factAnswer/factReadBack only), this
-// exposes the FULL turn engine: createChatSession wraps chat.mjs's runTurn
-// with a session-shaped closure — the focus/last/planState threading
-// src/services/chat-session.mjs's createSession.turn does, minus every
-// filesystem side effect (no transcript log, no sidecar, no graph upsert).
-// Memory is an in-memory Backend-B handle, optionally pre-loaded with a
-// built seed payload (scripts/build-chat-seed.mjs), so teach turns, recall,
-// proof chains and the honest miss all run client-side with zero I/O.
+// exposes the FULL turn engine: createChatSession wraps the shared
+// createTurnSession (turn-session.mjs) around chat.mjs's runTurn — the
+// focus/last/planState/researchState threading src/services/chat-session.mjs's
+// createSession.turn does, minus every filesystem side effect (no transcript
+// log, no sidecar, no graph upsert). Memory is an in-memory Backend-B handle,
+// optionally pre-loaded with a built seed payload (scripts/build-chat-seed.mjs),
+// so teach turns, recall, proof chains and the honest miss all run
+// client-side with zero I/O.
 //
-// Three browser traps this file owns so no caller can fall into them:
-//   - runTurn defaults `env` to process.env, and a browser has no `process`
-//     global — every turn here passes `env: {}` explicitly;
+// Two browser traps this file still owns, beyond what createTurnSession
+// already covers (passing `env: {}` explicitly, since a browser has no
+// `process` global; the crash-resistant catch fallback):
 //   - the uuid adapter needs node:crypto — the session id comes from the
 //     Web Crypto API instead, with a Date.now fallback for contexts
 //     without it;
@@ -25,15 +26,15 @@
 //     adapter — its own setDigestStructures is a documented no-op there
 //     (see that module's header), so the call is harmless either way, never
 //     a load error and never a behavior change on the Node side.
-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 { vocabExampleHint } from "../../services/chat.mjs";
+import { createInMemoryStore, normFactTerm, loadMemory, readFactRows, applySeedPayload } from "../../adapters/memory/core.mjs";
 import { splitSentencesPreservingPaths } from "../../services/sentences.mjs";
-import { provenanceTagToSource } from "../../domain/memory/trust.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import { registerWinkModel } from "../../adapters/wink-model.mjs";
 import { setDigestStructures } from "../../adapters/corpus/digest-bank.mjs";
+import { createTurnSession } from "./turn-session.mjs";
+import { memoryStats, exportFactsJsonl } from "./memory-stats.mjs";
 // The reference-pack provider seam: the page registers a fetch-backed
 // provider over public/reference-pack/ so the engine's pack lookups work
 // where the gzipped fs layout cannot (the module's own fs loader degrades to
@@ -50,6 +51,8 @@ import { registerLiveReferenceProvider, registerResearchProvider } from "../../a
 // decides when to save/load/clear; this entry only carries the wrapper
 // across the bundle boundary.
 import { openPersistedStore } from "./idb-persist.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
 
 /**
  * A browser chat session over the real turn engine.
@@ -69,17 +72,14 @@ import { openPersistedStore } from "./idb-persist.mjs";
  * is module-scope, last write wins, and every session created after this one
  * shares it.
  *
- * Returns { memoryDir, sessionId, turn }. `turn(line)` resolves to
+ * Returns { memoryDir, sessionId, graph, turn }. `turn(line)` resolves to
  * { answer, end, record, plan } and threads focus/last/planState between
  * calls exactly as the CLI session does.
  */
 export function createChatSession({ seedPayload = null, vocabSeeded = false, liveReference = false, onLiveLookup = null, synthesisBudget = 12, digestStructures = null } = {}) {
   setDigestStructures(digestStructures || []);
   const memoryDir = createInMemoryStore();
-  // Spread onto the store's own empty payload so a partial seed (individuals
-  // and objectProperties only) still carries the classes/prefixes scaffolding
-  // the write path recounts — teach turns must work on any seed.
-  if (seedPayload) memoryDir.payload = { ...memoryDir.payload, ...seedPayload };
+  applySeedPayload(memoryDir, seedPayload);
 
   // A known-empty code graph: code-structure questions get the same honest
   // no-code-graph answer an un-pointed CLI session gives, never a crash.
@@ -88,10 +88,6 @@ export function createChatSession({ seedPayload = null, vocabSeeded = false, liv
   const vocabHint = vocabExampleHint(vocabSeeded);
   const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
 
-  let focus = null;
-  let last = null;
-  let planState = null;
-  let researchState = null;
   // Four-state, like the CLI: false (off), true (rescue on a miss),
   // "supplement" (also append a cited read-out under every grounded vocabulary
   // answer), or "always" (widen that to every grounded answer). The two string
@@ -102,9 +98,23 @@ export function createChatSession({ seedPayload = null, vocabSeeded = false, liv
   // page's slider sets it; 0 stores article facts without any entailed rows.
   let synthesisBudgetOn = Number.isFinite(synthesisBudget) ? synthesisBudget : 12;
 
+  const session = createTurnSession({
+    memoryDir, graph, lexicon, sessionId, vocabHint,
+    buildExtraOptions: () => ({
+      liveReference: liveReferenceOn, onLiveLookup,
+      uiContext: "browser", synthesisBudget: synthesisBudgetOn,
+    }),
+    // `result.liveReference` mirrors a `/wiki on|off|supplement|always`
+    // command back into this session's own toggle state.
+    captureExtraState: (result) => {
+      if (typeof result.liveReference === "boolean" || result.liveReference === "supplement" || result.liveReference === "always") liveReferenceOn = result.liveReference;
+    },
+  });
+
   return {
     memoryDir,
     sessionId,
+    graph,
     get liveReference() { return liveReferenceOn; },
     /** The page's toggle seam: set the live Wikipedia mode for every later turn
      *  (the `/wiki on|off|supplement|always` command sets the same state). */
@@ -113,92 +123,10 @@ export function createChatSession({ seedPayload = null, vocabSeeded = false, liv
     /** The page's slider seam: set the auto-synthesis budget for every later
      *  learn-on-miss load. Clamped to a non-negative integer; 0 disables it. */
     setSynthesisBudget(n) { synthesisBudgetOn = Number.isFinite(n) && n > 0 ? Math.floor(n) : 0; },
-
-    /** One dispatched turn. A throwing runTurn must never kill the session —
-     *  the page has no other chance to show this turn's answer. */
-    async turn(line) {
-      let result;
-      try {
-        result = await runTurn(line, {
-          config: null, source: null, graph, focus, last, memoryDir, sessionId,
-          env: {}, lexicon, vocabHint, planState, researchState,
-          liveReference: liveReferenceOn, onLiveLookup,
-          uiContext: "browser", synthesisBudget: synthesisBudgetOn,
-        });
-      } 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, plan: null, research: null };
-      }
-      focus = result.focus;
-      last = result.last;
-      if ("planState" in result) planState = result.planState;
-      if ("researchState" in result) researchState = result.researchState;
-      if (typeof result.liveReference === "boolean" || result.liveReference === "supplement" || result.liveReference === "always") liveReferenceOn = result.liveReference;
-      // `research` distinguishes three cases on purpose: a queue snapshot
-      // (research turn), null (a research turn that ended the run), and
-      // undefined (not a research turn — the page leaves its controls alone).
-      return { answer: result.answer, end: Boolean(result.end), record: result.record ?? null, plan: result.plan ?? null, research: result.research };
-    },
+    turn: session.turn,
   };
 }
 
-/**
- * The memory a running session holds, broken down by where each fact came
- * from: the seed corpus bands it booted with (keyed by the SAME band name
- * build-chat-seed.mjs/extensions.mjs seed under — "human", "seon",
- * "conceptnet" today, whichever bands a future seed adds tomorrow) plus
- * whatever has been taught THIS session over chat. Reuses memory/trust.mjs's
- * own `provenanceTagToSource` against each fact's already-stored provenance
- * tag(s) (readFactRows' `provenance`, the ' | '-joined compat string) rather
- * than inventing a second provenance parse — the same tag chat.mjs's own
- * "(source: ...)" citation already carries, so this panel and a turn's
- * citation always agree on where a fact came from.
- *
- * Returns { total, bandCounts, taught }: `bandCounts` maps a band label to
- * its fact count ("taught this session" for a teach/operator-sourced fact
- * with no corpus band, "other" for anything provenance can't place);
- * `taught` lists every session-taught fact (subject/predicate/object + its
- * own provenance tag), most-recently-taught last — a stats panel's
- * provenance column reads straight off this, no further lookup needed.
- */
-export async function memoryStats(memoryDir) {
-  const memory = await loadMemory(memoryDir);
-  const rows = readFactRows(memory);
-  const bandCounts = {};
-  const taught = [];
-  for (const row of rows) {
-    const tags = String(row.provenance || "").split(" | ").filter(Boolean);
-    let band = null;
-    let isTaught = false;
-    let taughtTag = "";
-    for (const tag of tags) {
-      const src = provenanceTagToSource(tag);
-      if (!src) continue;
-      // corpusWeak (a /r/RelatedTo-strength triple, e.g. ConceptNet's or
-      // SEON's own weaker associations) names the SAME band as corpus (a
-      // /r/IsA-strength one) — both carry `src.name`, and a band count that
-      // dropped the weak tier would undercount a corpus by exactly its
-      // weak-relation facts (SEON: 19 of them, all `corpus-weak:seon`).
-      if ((src.kind === "corpus" || src.kind === "corpusWeak") && src.name) band = src.name;
-      if (src.kind === "teach" || src.kind === "operator") { isTaught = true; taughtTag = tag; }
-    }
-    const label = band || (isTaught ? "taught this session" : "other");
-    bandCounts[label] = (bandCounts[label] || 0) + 1;
-    if (isTaught) taught.push({ subject: row.subject, predicate: row.predicate, object: row.object, tag: taughtTag });
-  }
-  return { total: rows.length, bandCounts, taught };
-}
-
-/**
- * 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));
-}
-
 /**
  * Every fact a "research <topic>" run has stored so far, in storage order —
  * the exposure the "researched this session" panel needs and runTurn's
@@ -219,4 +147,20 @@ export async function researchedFactRows(memoryDir) {
     .map((row) => ({ subject: row.subject, predicate: row.predicate, object: row.object }));
 }
 
-globalThis.tmctChat = { createChatSession, registerWinkModel, registerReferencePackProvider, registerLiveReferenceProvider, registerResearchProvider, normFactTerm, vocabExampleHint, memoryStats, openPersistedStore, exportFactsJsonl, researchedFactRows, splitSentences: splitSentencesPreservingPaths };
+// The page reaches the engine through the one shared surface: `tmct.open()`
+// opens this session, `tmct.turn()` runs the dock, `tmct.ask()` puts a
+// question to the session's own graph. What stays on `tmct.page` is what has
+// no plain-English form — the vendor/provider seams the page registers before
+// the first turn, its IndexedDB wrapper, and the two serializers its export
+// and paste-ingest controls run.
+publishTmctSurface({
+  open: createChatSession,
+  ask: graphAsk,
+  plan: enginePlan,
+  page: {
+    registerWinkModel, registerReferencePackProvider, registerLiveReferenceProvider,
+    registerResearchProvider, normFactTerm, vocabExampleHint, memoryStats,
+    openPersistedStore, exportFactsJsonl, researchedFactRows,
+    splitSentences: splitSentencesPreservingPaths,
+  },
+});

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

@@ -13,14 +13,19 @@
 // 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, vocabExampleHint } from "../../services/chat.mjs";
+import { vocabExampleHint } 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 { computeCodeExplorerData, computeCodeLedger, edgePhrase } from "../../services/code-explorer-viz.mjs";
 import { generateCodeHints } from "../../domain/code-explorer-hints.mjs";
+import { createTurnSession } from "./turn-session.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
+import { tmct_ask } from "../../tools/handlers/tmct-ask.mjs";
+import { RELATIONS } from "../../domain/ask-vocab.mjs";
 
 /**
  * A browser code-explorer session over the real turn engine. Registers the
@@ -34,7 +39,7 @@ import { generateCodeHints } from "../../domain/code-explorer-hints.mjs";
  * payload carries the starter vocabulary. Teaches land in the same in-memory
  * store, so a taught fact never touches disk.
  *
- * Returns { memoryDir, sessionId, turn }, the createChatSession shape the
+ * Returns { memoryDir, sessionId, graph, turn }, the createChatSession shape the
  * page's chat expects.
  */
 export function createCodeExplorerSession({ graphPayload, seedPayload = null, vocabSeeded = false } = {}) {
@@ -54,42 +59,194 @@ export function createCodeExplorerSession({ graphPayload, seedPayload = null, vo
   // 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;
+  const turnSession = createTurnSession({
+    memoryDir, graph, lexicon, sessionId, vocabHint,
+    // The code explorer is the one page whose turns run against a real
+    // provider seam (source.mjs, registered above) and a virtual graph file
+    // path, so both override createTurnSession's config:null/source:null
+    // defaults on every call.
+    buildExtraOptions: () => ({ config, source }),
+  });
 
   return {
     memoryDir,
     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 };
-    },
+    graph,
+    turn: turnSession.turn,
   };
 }
 
-// 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 chat shares with
-// the ledger page.
-globalThis.tmctCodeExplorer = {
-  createCodeExplorerSession,
-  computeCodeExplorerData,
-  computeCodeLedger,
-  generateCodeHints,
-  parseEntities,
-  normFactTerm,
-  registerWinkModel,
-};
+// ---- "what relates to X", asked ------------------------------------------
+
+// A symbol-grain predicate asks as its coarse sibling: ask()'s relation
+// vocabulary carries one question per grain pair, not two.
+const COARSE_RELATION = { callsSymbol: "calls", touchesSymbol: "touches" };
+
+/** The two questions ask() understands about one relation kind, both spelled
+ *  from its own vocabulary: `verbs[0]` reads as the reverse direction ("what
+ *  couples to X"), `bare` as the forward one ("what does X import"). A relation
+ *  taught to ask-vocab is asked here with no second table to keep in step. */
+function relationQuestions(kind, term) {
+  const { bare, verbs } = RELATIONS[kind];
+  return [
+    { shape: "reverse", query: `what ${verbs[0]} ${term}` },
+    { shape: "forward", query: `what does ${term} ${bare}` },
+  ];
+}
+
+/** The kinds worth asking about: the ones this graph actually stores, folded
+ *  onto ask()'s vocabulary keys. A graph carrying only imports asks two
+ *  questions, not twenty. */
+function askableRelationKinds(graph) {
+  const kinds = new Set();
+  for (const relation of graph.relations) {
+    if (!relation.edges.length) continue;
+    const kind = COARSE_RELATION[relation.predicate] || relation.predicate;
+    if (Object.hasOwn(RELATIONS, kind)) kinds.add(kind);
+  }
+  return [...kinds];
+}
+
+/** Every stored edge as `<subjectId> <objectId>`, keyed by the coarse relation
+ *  kind so both grains of a pair land in one set, beside a label-to-ids index.
+ *  An answer names the individuals it found; these two decide whether the row
+ *  built from that answer is an edge the graph actually holds. */
+function indexEdges(graph) {
+  const edgesByKind = new Map();
+  for (const relation of graph.relations) {
+    const kind = COARSE_RELATION[relation.predicate] || relation.predicate;
+    let pairs = edgesByKind.get(kind);
+    if (!pairs) edgesByKind.set(kind, (pairs = new Set()));
+    for (const edge of relation.edges) pairs.add(`${edge.subject} ${edge.object}`);
+  }
+  const idsByLabel = new Map();
+  for (const individual of graph.individuals) {
+    if (!individual?.label || !individual.id) continue;
+    const ids = idsByLabel.get(individual.label);
+    if (ids) ids.push(individual.id);
+    else idsByLabel.set(individual.label, [individual.id]);
+  }
+  return { edgesByKind, idsByLabel };
+}
+
+// parseEntities walks the whole payload, and a focus click re-asks the same
+// graph, so one parse and one edge index per payload serve every question put
+// to it.
+const readGraphs = new WeakMap();
+function readGraph(payload) {
+  let read = readGraphs.get(payload);
+  if (!read) {
+    const graph = parseEntities(payload);
+    read = { graph, ...indexEdges(graph) };
+    readGraphs.set(payload, read);
+  }
+  return read;
+}
+
+const rowKey = (row) => JSON.stringify([row.s, row.kind, row.o]);
+
+/**
+ * "What relates to <term>", asked instead of computed. Every relation kind the
+ * loaded graph carries becomes two real tmct_ask round trips over that graph —
+ * the same ask() every chat turn on this page already reaches — and the
+ * answers' typed `matches` become the explorer sidebar's rows. The page stops
+ * deciding what relates to what, so the panel and the conversation cannot
+ * scope or phrase one question two ways.
+ *
+ * Two things have to hold before an answer becomes a row. ask() must have
+ * parsed the question as the question asked: an identifier that is itself a
+ * relation verb makes it read "what tests run" as a question about testing, and
+ * rows off that answer would describe the wrong term. And the row must be an
+ * edge this graph holds between the term and what the answer named — ask()
+ * resolves a term against the asked relation's own range, so "what contains
+ * Task" legitimately answers about `Task.title`'s container, which is a true
+ * sentence about a different pair than the one the sidebar is drawing. A row
+ * the graph cannot confirm is dropped rather than shown; the engine's own prose
+ * is where an inexact resolution belongs, because there it can say so.
+ *
+ * `grounded` is false when no question was understood as asked, which is the
+ * caller's signal to fall back rather than show an empty neighbourhood for a
+ * term the graph plainly has edges for.
+ *
+ * Returns { term, rows, asked, grounded }: `rows` in computeCodeLedger's own
+ * row shape so one renderer draws both, `asked` every question put to the
+ * engine beside what came back.
+ */
+export function askRelatedFacts(graphPayload, term) {
+  const rows = [];
+  const asked = [];
+  let grounded = false;
+  if (!graphPayload || !term) return { term: term || null, rows, asked, grounded };
+
+  const { graph, edgesByKind, idsByLabel } = readGraph(graphPayload);
+  // An edge group's objectLabel is denormalized and can be shorter than the
+  // individual's own ("assignTo" for `Task.assignTo`), so the row list offers
+  // clickable terms this graph holds no individual for. There is nothing to ask
+  // about one, and saying so leaves the caller its row-list fallback instead of
+  // an answered-and-empty neighbourhood.
+  const termIds = idsByLabel.get(term) || [];
+  if (!termIds.length) return { term, rows, asked, grounded };
+
+  const seen = new Set();
+  for (const kind of askableRelationKinds(graph)) {
+    const storedEdges = edgesByKind.get(kind) || new Set();
+    const holdsEdge = (subjectId, objectId) => storedEdges.has(`${subjectId} ${objectId}`);
+    for (const { shape, query } of relationQuestions(kind, term)) {
+      const envelope = tmct_ask({ query }, { graph }).data;
+      const parsed = envelope?.parsed;
+      const answeredAsAsked = parsed?.shape === shape
+        && parsed?.kind === kind
+        && parsed?.object === term
+        && !envelope.ambiguous;
+      if (!answeredAsAsked) {
+        asked.push({ query, kind, shape, used: false, parsedAs: parsed?.canonical?.machine ?? null });
+        continue;
+      }
+      grounded = true;
+      const matches = Array.isArray(envelope.matches) ? envelope.matches : [];
+      let confirmed = 0;
+      for (const match of matches) {
+        if (!match?.label || !match.id) continue;
+        const aboutTerm = termIds.some((termId) => (shape === "reverse"
+          ? holdsEdge(match.id, termId)
+          : holdsEdge(termId, match.id)));
+        if (!aboutTerm) continue;
+        confirmed += 1;
+        const row = shape === "reverse"
+          ? { s: match.label, kind, phrase: edgePhrase(kind), o: term, sClass: match.type || "", oClass: "" }
+          : { s: term, kind, phrase: edgePhrase(kind), o: match.label, sClass: "", oClass: match.type || "" };
+        const key = rowKey(row);
+        if (seen.has(key)) continue;
+        seen.add(key);
+        rows.push(row);
+      }
+      asked.push({ query, kind, shape, used: true, miss: Boolean(envelope.miss), matched: matches.length, confirmed, traversal: envelope.traversal ?? null });
+    }
+  }
+  return { term, rows, asked, grounded };
+}
+
+// This page holds a REAL code graph, so `tmct.ask` is the engine answering
+// over it — the same round trip askRelatedFacts already makes twice per
+// relation kind to build the sidebar's rows.
+//
+// `tmct.page` keeps the re-derivation helpers a graph swapped through the
+// desktop picker re-renders with, plus the wink and term-normalizing seams the
+// chat shares with the ledger page. `createCodeExplorerSession` sits there
+// too: this page's client script is still one raw-text block, and it reaches
+// its factory through the bag rather than through `tmct.open()`.
+publishTmctSurface({
+  open: createCodeExplorerSession,
+  ask: graphAsk,
+  plan: enginePlan,
+  page: {
+    createCodeExplorerSession,
+    askRelatedFacts,
+    computeCodeExplorerData,
+    computeCodeLedger,
+    generateCodeHints,
+    parseEntities,
+    normFactTerm,
+    registerWinkModel,
+  },
+});

package/src/surfaces/web/engine-surface.mjs

@@ -0,0 +1,82 @@
+// engine-surface.mjs — the standard `ask` and `plan` routes a browser page
+// wires into publishTmctSurface (tmct-surface.mjs).
+//
+// Both run the SAME machinery the CLI runs, over the session's own in-memory
+// state rather than a repo on disk: `graphAsk` dispatches `tmct_ask` through
+// the tool layer and hands back the structured envelope beside the prose
+// (dispatchToolStructured's `{ content, data }`); `enginePlan` builds the
+// capability planner's context from whatever the session holds and runs one
+// request through it.
+//
+// Kept out of tmct-surface.mjs on purpose. That module is pure wiring and
+// imports nothing, so memory-ask-browser-entry.mjs — the one bundle that is
+// committed and published, and is deliberately small — can publish the same
+// `globalThis.tmct` without pulling the tool layer and the router into its
+// bundle.
+import { dispatchToolStructured } from "../../tools/server.mjs";
+import { capabilityPlanDeps, noCodeGraph } from "../../services/chat.mjs";
+
+/**
+ * One plain-English question, answered against the graph this session holds,
+ * through the same `tmct_ask` tool the CLI dispatches. Returns
+ * `{ answer, data, miss }` — `data` is ask()'s own envelope (the parse, the
+ * matches it found, the traversal it walked), which is what a panel renders
+ * rows from and what makes an answer auditable.
+ *
+ * A session whose graph is empty answers with an honest miss. That is the real
+ * state of a memory-only page: its rows are facts in a store, and ask() reads
+ * a graph. spider-fly is the page that closed that gap for its own world, by
+ * projecting its live board into a graph (worldRelationGraphPayload) before
+ * every turn — the same route is open to any page whose rows have a shape
+ * worth asking over.
+ */
+export async function graphAsk(request, options, session) {
+  const { content, data } = await dispatchToolStructured("tmct_ask", { query: request }, {
+    graph: session.graph,
+    memoryBackend: session.memoryDir,
+  });
+  return { answer: content, data, miss: Boolean(data?.miss) };
+}
+
+/**
+ * One compound or maintenance-goal request, planned and executed over whatever
+ * this session holds — the same capability router `/plan` reaches, with the
+ * same memory-only mode a page with no code graph needs (a code-graph
+ * capability there refuses by naming the graph it hasn't got).
+ *
+ * Returns the planner's own result: `{ refused, why, driver, calls, composed,
+ * observed }`. No prose is composed here — a page that wants the written
+ * answer asks for it in words through `tmct.turn("/plan …")`, which is the
+ * same split `dispatchTool` and `dispatchToolStructured` already draw.
+ */
+export async function enginePlan(request, options, session) {
+  const graph = session.graph && !noCodeGraph(session.graph) ? session.graph : null;
+  const memoryDir = session.memoryDir ?? null;
+  if (!graph && !memoryDir) {
+    return {
+      refused: true,
+      why: "nothing to plan over — this session holds neither a code graph nor a memory store",
+      driver: null, calls: [], composed: null, observed: null,
+    };
+  }
+  const { buildCapabilityPlanCtx, runCapabilityPlan, declaredCapabilityNames } =
+    await import("../../domain/router/drive.mjs");
+  const ctx = await buildCapabilityPlanCtx({
+    ...capabilityPlanDeps(), config: null, source: null, graph, memoryDir,
+  });
+  try {
+    const result = await runCapabilityPlan(request, declaredCapabilityNames(), ctx);
+    return {
+      refused: Boolean(result.refused),
+      why: Array.isArray(result.why) ? result.why.join("; ") : (result.why ?? null),
+      driver: result.driver ?? null,
+      calls: result.calls ?? [],
+      composed: result.composed ?? null,
+      observed: result.observed ?? null,
+    };
+  } finally {
+    // The taught registrations are per-ctx: dispose them so the next call
+    // re-reads the store instead of meeting a stale name collision.
+    for (const dispose of ctx.disposers || []) dispose();
+  }
+}

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

@@ -24,15 +24,15 @@
 // runTurn engine, the same weight class as the chat/ledger bundles, and is
 // never published.
 import { runTurn, vocabExampleHint } from "../../services/chat.mjs";
-import { createInMemoryStore, normFactTerm, loadMemory, readFactRows, appendFact } from "../../adapters/memory/core.mjs";
-import { serializeFactsJsonl } from "../../adapters/memory/export-jsonl.mjs";
+import { createInMemoryStore, normFactTerm, loadMemory, readFactRows, appendFact, applySeedPayload } from "../../adapters/memory/core.mjs";
 import { splitSentencesPreservingPaths, stripCitationResidue } from "../../services/sentences.mjs";
 import { clauseCandidates, optimisticTriples } from "../../services/extract-facts.mjs";
 import { touchedFactRows } from "../../domain/memory/touched-facts.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import { registerWinkModel, winkInstance } from "../../adapters/wink-model.mjs";
-import { memoryStats } from "./memory-stats.mjs";
+import { memoryStats, exportFactsJsonl } from "./memory-stats.mjs";
 import { openPersistedStore } from "./idb-persist.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
 
 // The pronoun subjects a bounded carry substitutes with the last unique
 // grounded subject in the SAME paragraph. Reset at every blank line, so a
@@ -178,7 +178,7 @@ export async function groundTextToFacts(text, { memoryDir, sessionId, lexicon, v
  */
 export function createIngestSession({ seedPayload = null, vocabSeeded = false } = {}) {
   const memoryDir = createInMemoryStore();
-  if (seedPayload) memoryDir.payload = { ...memoryDir.payload, ...seedPayload };
+  applySeedPayload(memoryDir, seedPayload);
 
   const lexicon = loadLexicon();
   const vocabHint = vocabExampleHint(vocabSeeded);
@@ -193,16 +193,15 @@ export function createIngestSession({ seedPayload = null, vocabSeeded = false }
   };
 }
 
-/**
- * The session's whole triple store as JSONL — the same
- * { subject, predicate, object, provenance } shape `tmct extract` and
- * `tmct memory --export` emit, offered to the page as the canonical download.
- */
-export async function exportFactsJsonl(memoryDir) {
-  return serializeFactsJsonl(await loadMemory(memoryDir));
-}
-
-globalThis.tmctIngest = {
-  createIngestSession, groundTextToFacts, exportFactsJsonl, registerWinkModel, normFactTerm,
-  memoryStats, openPersistedStore,
-};
+// This page grounds pasted prose into facts; it holds no conversation, so
+// `tmct.turn` is unwired and says so, and the one call the page makes is
+// `tmct.session.ingest(text)`. `tmct.page` keeps the recognizer entry point
+// the page also drives directly, the wink seam, the stats fold behind its
+// counters, its IndexedDB wrapper and its JSONL export.
+publishTmctSurface({
+  open: createIngestSession,
+  page: {
+    groundTextToFacts, exportFactsJsonl, registerWinkModel, normFactTerm,
+    memoryStats, openPersistedStore,
+  },
+});