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

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
@@ -76,10 +77,7 @@ import { openPersistedStore } from "./idb-persist.mjs";
 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 +86,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,6 +96,19 @@ 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,
@@ -113,92 +120,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

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

@@ -13,14 +13,17 @@
 // 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 { 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
@@ -54,38 +57,179 @@ 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 };
-    },
+    turn: turnSession.turn,
   };
 }
 
+// ---- "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 };
+}
+
 // 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.
+// swapped through the desktop picker re-renders without duplicating logic, the
+// engine's own answer to "what relates to the focus", plus the wink loader hook
+// registerWinkModel and normFactTerm the chat shares with the ledger page.
 globalThis.tmctCodeExplorer = {
   createCodeExplorerSession,
+  askRelatedFacts,
   computeCodeExplorerData,
   computeCodeLedger,
   generateCodeHints,

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

@@ -24,14 +24,13 @@
 // 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";
 
 // The pronoun subjects a bounded carry substitutes with the last unique
@@ -178,7 +177,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,15 +192,6 @@ 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,

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

@@ -16,9 +16,8 @@
 // class as chat/spider-fly/adventure/plan's own browser bundles) and is
 // never published — only the hosted demo site's public/ledger.html links to
 // it, as an optional sibling script the page degrades honestly without.
-import { runTurn, vocabExampleHint } from "../../services/chat.mjs";
-import { createInMemoryStore, normFactTerm, loadMemory } from "../../adapters/memory/core.mjs";
-import { serializeFactsJsonl } from "../../adapters/memory/export-jsonl.mjs";
+import { vocabExampleHint } from "../../services/chat.mjs";
+import { createInMemoryStore, normFactTerm, applySeedPayload } from "../../adapters/memory/core.mjs";
 import { splitSentencesPreservingPaths } from "../../services/sentences.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
@@ -26,6 +25,8 @@ import { registerWinkModel } from "../../adapters/wink-model.mjs";
 import { registerResearchProvider } from "../../adapters/corpus/wikipedia-live.mjs";
 import { computeLedgerDataFromPayload } from "../../services/ledger-viz.mjs";
 import { digestTermFromPayloadBrowser } from "./digest-client.mjs";
+import { createTurnSession } from "./turn-session.mjs";
+import { exportFactsJsonl } from "./memory-stats.mjs";
 
 /**
  * A browser ledger-dock session over the real turn engine — createChatSession's
@@ -43,56 +44,15 @@ import { digestTermFromPayloadBrowser } from "./digest-client.mjs";
  */
 export function createLedgerSession({ seedPayload = null, vocabSeeded = false } = {}) {
   const memoryDir = createInMemoryStore();
-  // Spread onto the store's own empty payload so a partial seed still
-  // carries the classes/prefixes scaffolding the write path recounts —
-  // teach turns must work regardless of what the seed payload carries.
-  if (seedPayload) memoryDir.payload = { ...memoryDir.payload, ...seedPayload };
+  applySeedPayload(memoryDir, seedPayload);
 
   const graph = parseEntities({ individuals: [], objectProperties: [] });
   const lexicon = loadLexicon();
   const vocabHint = vocabExampleHint(vocabSeeded);
   const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
 
-  let focus = null;
-  let last = null;
-  let planState = null;
-  let researchState = null;
-
-  return {
-    memoryDir,
-    sessionId,
-
-    /** 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,
-        });
-      } 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, research: null };
-      }
-      focus = result.focus;
-      last = result.last;
-      if ("planState" in result) planState = result.planState;
-      if ("researchState" in result) researchState = result.researchState;
-      // `research` distinguishes a queue snapshot (research turn) from null
-      // (a research turn that ended the run) from undefined (not a research
-      // turn) — the dock's controls only react to the first two.
-      return { answer: result.answer, end: Boolean(result.end), record: result.record ?? null, research: result.research };
-    },
-  };
-}
-
-/** The session's whole triple store as JSONL — the same
- *  { subject, predicate, object, provenance } shape `tmct extract` and
- *  `tmct memory --export` emit. The ledger dock's "export facts" control reads
- *  this and offers it as a download. */
-export async function exportFactsJsonl(memoryDir) {
-  return serializeFactsJsonl(await loadMemory(memoryDir));
+  const session = createTurnSession({ memoryDir, graph, lexicon, sessionId, vocabHint });
+  return { memoryDir, sessionId, turn: session.turn };
 }
 
 // Re-exported so ledger-viz.mjs's own inline script never has to duplicate