@polycode-projects/the-mechanical-code-talker 2.10.5 → 2.11.1

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

@@ -35,7 +35,7 @@ import {
 } from "../../adapters/memory/core.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
-import { foldWorldState, worldDigestRows, roomAffordances } from "../../services/adventure.mjs";
+import { foldWorldState, worldDigestRows, roomAffordances, worldActionRows } from "../../services/adventure.mjs";
 import { runAdventureAutoplayTick, exposedFacts } from "../../services/adventure-autoplay.mjs";
 import { parseWorldEditorText, planWorldEditorSync } from "../../services/adventure-editor.mjs";
 import { resolveSpriteForClass, SPRITE_REGISTRY, classAncestorChain } from "../../domain/sprite-map.mjs";
@@ -92,7 +92,7 @@ export async function createAdventureSession(worldPayload, { restoredPayload = n
   // bookkeeping either way.
   let visitedRoomIds = new Set(Array.isArray(restoredVisitedRoomIds) ? restoredVisitedRoomIds : []);
   const openingRows = readFactRows(await loadMemory(memoryDir));
-  const openingHere = foldWorldState(openingRows).placements.get("player")?.object ?? null;
+  const openingHere = foldWorldState(worldActionRows(openingRows)).placements.get("player")?.object ?? null;
   if (openingHere) visitedRoomIds.add(openingHere);
 
   const graph = parseEntities({ individuals: [], objectProperties: [] });
@@ -126,7 +126,9 @@ export async function createAdventureSession(worldPayload, { restoredPayload = n
       try {
         result = await runTurn(line, {
           config: null, source: null, graph, focus, last, memoryDir, sessionId,
-          env: {}, lexicon, vocabHint: "", planState: planHolder.state,
+          env: {}, lexicon, uiContext: "browser",
+          vocabHint: 'Try a world question ("where is the key"), or teach me: "remember: the moat is a ditch".',
+          planState: planHolder.state,
         });
       } catch (e) {
         const message = e instanceof Error ? e.message : String(e);
@@ -135,7 +137,7 @@ export async function createAdventureSession(worldPayload, { restoredPayload = n
       focus = result.focus;
       last = result.last;
       if ("planState" in result) planHolder.state = result.planState;
-      const here = foldWorldState(readFactRows(await loadMemory(memoryDir))).placements.get("player")?.object ?? null;
+      const here = foldWorldState(worldActionRows(readFactRows(await loadMemory(memoryDir)))).placements.get("player")?.object ?? null;
       if (here) visitedRoomIds.add(here);
       return { answer: result.answer, end: Boolean(result.end), record: result.record ?? null, plan: result.plan ?? null };
     },
@@ -148,7 +150,9 @@ export async function createAdventureSession(worldPayload, { restoredPayload = n
      *  reference into this closure's own Set. */
     async snapshot() {
       const rows = readFactRows(await loadMemory(memoryDir));
-      const state = foldWorldState(rows);
+      // State the page plays and maps from is the game world only; the raw
+      // rows still travel for the digest's background colour.
+      const state = foldWorldState(worldActionRows(rows));
       const here = state.placements.get("player")?.object ?? null;
       return { rows, state, here, turn: state.turnCount, visitedRoomIds: [...visitedRoomIds] };
     },

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

@@ -33,7 +33,9 @@ import { registerReferencePackProvider } from "../../adapters/corpus/reference-p
 // The LIVE Wikipedia seam (opt-in, default off): the page's toggle enables it
 // per session, and e2e tests stub the provider the same way the pack's own
 // provider is stubbed. The adapter is fetch-only, so it bundles as-is.
-import { registerLiveReferenceProvider } from "../../adapters/corpus/wikipedia-live.mjs";
+// registerResearchProvider is the research lane's sibling seam
+// (simple.wikipedia.org) — same stubbing contract for its e2e tests.
+import { registerLiveReferenceProvider, registerResearchProvider } from "../../adapters/corpus/wikipedia-live.mjs";
 // Best-effort IndexedDB persistence for the page's session store — the page
 // decides when to save/load/clear; this entry only carries the wrapper
 // across the bundle boundary.
@@ -52,7 +54,7 @@ import { openPersistedStore } from "./idb-persist.mjs";
  * { 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 } = {}) {
+export function createChatSession({ seedPayload = null, vocabSeeded = false, liveReference = false, onLiveLookup = null, synthesisBudget = 12 } = {}) {
   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
@@ -69,18 +71,28 @@ export function createChatSession({ seedPayload = null, vocabSeeded = false, liv
   let focus = null;
   let last = null;
   let planState = null;
-  // Tri-state, like the TUI: false (off), true (rescue on a miss), or
-  // "supplement" (also append a cited read-out under every grounded answer).
-  const normLive = (v) => (v === "supplement" ? "supplement" : Boolean(v));
+  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
+  // modes stay strings so runTurn reads them as the supplement/always lanes.
+  const normLive = (v) => (v === "always" ? "always" : v === "supplement" ? "supplement" : Boolean(v));
   let liveReferenceOn = normLive(liveReference);
+  // The auto-synthesis budget for this session's learn-on-miss loads — the
+  // page's slider sets it; 0 stores article facts without any entailed rows.
+  let synthesisBudgetOn = Number.isFinite(synthesisBudget) ? synthesisBudget : 12;
 
   return {
     memoryDir,
     sessionId,
     get liveReference() { return liveReferenceOn; },
     /** The page's toggle seam: set the live Wikipedia mode for every later turn
-     *  (the `/wiki on|off|supplement` command sets the same state). */
+     *  (the `/wiki on|off|supplement|always` command sets the same state). */
     setLiveReference(v) { liveReferenceOn = normLive(v); },
+    get synthesisBudget() { return synthesisBudgetOn; },
+    /** 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. */
@@ -89,18 +101,23 @@ export function createChatSession({ seedPayload = null, vocabSeeded = false, liv
       try {
         result = await runTurn(line, {
           config: null, source: null, graph, focus, last, memoryDir, sessionId,
-          env: {}, lexicon, vocabHint, planState,
+          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 };
+        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 (typeof result.liveReference === "boolean" || result.liveReference === "supplement") liveReferenceOn = result.liveReference;
-      return { answer: result.answer, end: Boolean(result.end), record: result.record ?? null, plan: result.plan ?? null };
+      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 };
     },
   };
 }
@@ -162,4 +179,4 @@ export async function exportFactsJsonl(memoryDir) {
   return serializeFactsJsonl(await loadMemory(memoryDir));
 }
 
-globalThis.tmctChat = { createChatSession, registerWinkModel, registerReferencePackProvider, registerLiveReferenceProvider, normFactTerm, vocabExampleHint, memoryStats, openPersistedStore, exportFactsJsonl, splitSentences: splitSentencesPreservingPaths };
+globalThis.tmctChat = { createChatSession, registerWinkModel, registerReferencePackProvider, registerLiveReferenceProvider, registerResearchProvider, normFactTerm, vocabExampleHint, memoryStats, openPersistedStore, exportFactsJsonl, splitSentences: splitSentencesPreservingPaths };

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

@@ -1,17 +1,19 @@
 // code-explorer-browser-entry.mjs — the esbuild entry for the code explorer's
-// LIVE chat dock (public/code-explorer.bundle.js / electron/renderer/
+// LIVE chat (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.
+// full runTurn engine from a CODE graph — and, when the page hands one over,
+// the same general-knowledge seed payload chat.html boots from — so one
+// session answers "which functions call Y" over the loaded graph and "what is
+// a queue" over the seeded memory.
 //
 // 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.
+// The seed enters the in-memory store the same way createChatSession's does.
 // 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 { runTurn, 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";
@@ -23,17 +25,30 @@ 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.
+ * dispatches every turn through the same runTurn the CLI runs.
+ *
+ * `seedPayload` (optional) is a serialized memory graph (loadMemory's shape,
+ * built by scripts/build-chat-seed.mjs) assigned onto the session's fresh
+ * in-memory store, so general-knowledge questions ground alongside the code
+ * graph's own lanes. `vocabSeeded` tells the vocabulary hint whether that
+ * 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
+ * page's chat expects.
  */
-export function createCodeExplorerSession({ graphPayload } = {}) {
+export function createCodeExplorerSession({ graphPayload, seedPayload = null, vocabSeeded = false } = {}) {
   const payload = graphPayload || { individuals: [], objectProperties: [] };
   source.registerProvider(() => payload);
 
   const graph = parseEntities(payload);
   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 };
   const lexicon = loadLexicon();
+  const vocabHint = vocabExampleHint(vocabSeeded);
   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.
@@ -44,13 +59,14 @@ export function createCodeExplorerSession({ graphPayload } = {}) {
   let planState = null;
 
   return {
+    memoryDir,
     sessionId,
     async turn(line) {
       let result;
       try {
         result = await runTurn(line, {
           config, source, graph, focus, last, memoryDir, sessionId,
-          env: {}, lexicon, vocabHint: "", planState,
+          env: {}, lexicon, vocabHint, planState,
         });
       } catch (e) {
         const message = e instanceof Error ? e.message : String(e);
@@ -66,7 +82,7 @@ export function createCodeExplorerSession({ graphPayload } = {}) {
 
 // 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 wink loader hook registerWinkModel and normFactTerm the chat shares with
 // the ledger page.
 globalThis.tmctCodeExplorer = {
   createCodeExplorerSession,

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

@@ -12,7 +12,11 @@
 // The recognizer is reached through ONE seam — `groundTextToFacts` — so a
 // wider ingest tier (an optimistic fuzzy-match pass, a canonical/graph-linked
 // output) slots in behind this single function without the page changing.
-// Today the seam is the strict recognizer alone.
+// Alongside the strict recognizer, groundTextToFacts runs the same
+// citation-stripping, clause-fallback and bounded pronoun-carry passes
+// `ingestText` (extract-facts.mjs) applies for the CLI, and — opt-in, off by
+// default — the same low-trust optimistic tier, so the browser page and the
+// CLI ground the identical class of sentence.
 //
 // Gitignored, Pages-demo-site-only output (scripts/build-demo-site.mjs builds
 // it fresh on every deploy, never committed) — the same posture
@@ -20,21 +24,37 @@
 // 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 } from "../../adapters/memory/core.mjs";
+import { createInMemoryStore, normFactTerm, loadMemory, readFactRows, appendFact } from "../../adapters/memory/core.mjs";
 import { serializeFactsJsonl } from "../../adapters/memory/export-jsonl.mjs";
-import { splitSentencesPreservingPaths } from "../../services/sentences.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 { parseEntities } from "../../domain/codegraph.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
-import { registerWinkModel } from "../../adapters/wink-model.mjs";
+import { registerWinkModel, winkInstance } from "../../adapters/wink-model.mjs";
+import { memoryStats } from "./memory-stats.mjs";
+import { openPersistedStore } from "./idb-persist.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
+// fresh paragraph never resolves against a stale antecedent.
+const PRONOUN_LEAD_RE = /^(?:they|it|these|those|this)\b\s*/i;
 
 /**
- * The single recognizer seam. Splits `text` into sentences (wink's own
- * boundary detection, never a regex), runs each through runTurn against
- * `memoryDir`, and keeps a sentence only when runTurn's own record calls it a
- * stored assertion (`record.via === "assert"`, `record.miss` false) that
- * actually touched a Fact row — the identical keep/skip rule
- * src/services/extract-facts.mjs's own runSentence holds.
+ * The single recognizer seam. Splits `text` into paragraphs (blank-line
+ * separated, so the pronoun carry never bridges a topic break) and each
+ * paragraph into sentences (wink's own boundary detection, never a regex).
+ * Each sentence's citation residue ("[3]", "[citation needed]") is stripped
+ * before grounding; the strict recognizer then tries the whole sentence
+ * first, falling back to its clause fragments only on a miss
+ * (`clauseCandidates`), and — still on a miss, only for a pronoun-led
+ * sentence with a unique adjacent antecedent in this paragraph — one retry
+ * with that antecedent substituted in.
+ *
+ * A sentence still ungrounded after all of that runs the optimistic fuzzy
+ * tier when `optimistic` is set (`optimisticTriples`): a copula or known
+ * relation verb flanked by two resolvable entities, stored under the
+ * low-trust `optimistic-extract:page` tag rather than a teach/assert
+ * provenance, so a fuzzy candidate can never corroborate a curated fact.
  *
  * `onFact(fact)` (optional) is awaited after each grounded row so the page can
  * render the canonical facts LIVE as they land, one at a time.
@@ -42,48 +62,107 @@ import { registerWinkModel } from "../../adapters/wink-model.mjs";
  * Returns { sentences, recognized, skipped, facts } — `facts` an array of
  * { subject, predicate, object, provenance, quantifier, sentence } in the same
  * canonical shape `tmct extract` and the JSONL exporter emit.
- *
- * A wider ingest tier plugs in HERE, behind this one function: the page calls
- * it and nothing else.
  */
-export async function groundTextToFacts(text, { memoryDir, sessionId, graph, lexicon, vocabHint, onFact = null } = {}) {
-  const sentences = splitSentencesPreservingPaths(text);
+export async function groundTextToFacts(text, { memoryDir, sessionId, lexicon, vocabHint, optimistic = false, onFact = null } = {}) {
+  const paragraphs = String(text ?? "").split(/\n[ \t]*\n/);
   const facts = [];
   let focus = null;
   let last = null;
   let planState = null;
+  let sentenceCount = 0;
   let recognized = 0;
+  // Reused, not reloaded: readFactRows(loadMemory(...)) is O(rows), so a
+  // fresh read on every sentence over a large seeded store is exactly the
+  // O(sentences × rows) cost this page must avoid. The snapshot only moves
+  // forward past a sentence that actually asserted something.
+  let beforeRows = readFactRows(await loadMemory(memoryDir));
+  const nlp = optimistic ? winkInstance() : null;
 
-  for (const sentence of sentences) {
-    const before = readFactRows(await loadMemory(memoryDir));
+  // One grounding attempt against `memoryDir`: runs `form` through runTurn,
+  // threading focus/last/planState the same way whether or not it grounds.
+  // No `graph` is passed — this page never offers a code graph to link
+  // against, and a non-null one (even an empty one) makes runTurn read an
+  // ordinary "the number of X" phrase as a graph count query instead of
+  // running the teach cascade, exactly the phrasing the Sales-paragraph
+  // sentence this pipeline is built to ground uses.
+  // Returns the Fact rows this attempt actually touched, or null — a miss, a
+  // non-assert turn, or an assert that touched no Fact row (a Rule teach).
+  async function attempt(form) {
     let record;
     try {
-      const result = await runTurn(sentence, {
-        config: null, source: null, graph, focus, last, memoryDir, sessionId,
-        env: {}, lexicon, vocabHint, planState,
+      const result = await runTurn(form, {
+        config: null, source: null, focus, last, memoryDir, sessionId,
+        env: {}, lexicon, vocabHint, planState, uiContext: "browser",
       });
       focus = result.focus;
       last = result.last;
       if ("planState" in result) planState = result.planState;
       record = result.record;
     } catch {
-      continue; // a throwing sentence is a skip, never a page-killer
+      return null; // a throwing sentence is a skip, never a page-killer
     }
-    if (record?.via !== "assert" || record?.miss) continue;
-    const rows = touchedFactRows(before, readFactRows(await loadMemory(memoryDir)));
-    if (!rows.length) continue; // a Rule teach touches no Fact row — honest skip
-    recognized += 1;
-    for (const row of rows) {
-      const fact = {
-        subject: row.subject, predicate: row.predicate, object: row.object,
-        provenance: row.provenance || "", quantifier: row.quantifier || "", sentence,
-      };
-      facts.push(fact);
-      if (onFact) await onFact(fact);
+    if (record?.via !== "assert" || record?.miss) return null;
+    // The one loadMemory/readFactRows call this attempt pays for, only
+    // because it actually asserted something. Equal lengths mean nothing was
+    // ADDED — a re-assertion's provenance-only change is the one case this
+    // fast path can't see, an accepted trade against paying the full
+    // before/after diff on every recognized sentence in a large store.
+    const afterRows = readFactRows(await loadMemory(memoryDir));
+    const rows = afterRows.length === beforeRows.length ? [] : touchedFactRows(beforeRows, afterRows);
+    beforeRows = afterRows;
+    return rows.length ? rows : null;
+  }
+
+  for (const paragraph of paragraphs) {
+    // The last unique grounded subject in THIS paragraph, carried onto a
+    // later pronoun-led sentence the strict recognizer couldn't ground on its
+    // own. Cleared at the paragraph boundary.
+    let carrySubject = null;
+    for (const rawSentence of splitSentencesPreservingPaths(paragraph)) {
+      sentenceCount += 1;
+      const cleaned = stripCitationResidue(rawSentence);
+
+      let rows = null;
+      for (const candidate of clauseCandidates(cleaned, { nlp })) {
+        rows = await attempt(candidate);
+        if (rows) break;
+      }
+      if (!rows && carrySubject && PRONOUN_LEAD_RE.test(cleaned)) {
+        rows = await attempt(cleaned.replace(PRONOUN_LEAD_RE, `${carrySubject} `));
+      }
+
+      if (rows) {
+        recognized += 1;
+        const subjects = new Set(rows.map((r) => r.subject));
+        if (subjects.size === 1) carrySubject = [...subjects][0];
+        for (const row of rows) {
+          const fact = {
+            subject: row.subject, predicate: row.predicate, object: row.object,
+            provenance: row.provenance || "", quantifier: row.quantifier || "", sentence: rawSentence,
+          };
+          facts.push(fact);
+          if (onFact) await onFact(fact);
+        }
+        continue;
+      }
+
+      if (!optimistic) continue;
+      const candidates = optimisticTriples(cleaned, { lexicon, nlp });
+      if (!candidates.length) continue;
+      recognized += 1;
+      for (const t of candidates) {
+        await appendFact(memoryDir, { subject: t.subject, predicate: t.predicate, object: t.object, provenance: "optimistic-extract:page" });
+        const fact = {
+          subject: t.subject, predicate: t.predicate, object: t.object,
+          provenance: "optimistic-extract:page", quantifier: "", sentence: rawSentence,
+        };
+        facts.push(fact);
+        if (onFact) await onFact(fact);
+      }
     }
   }
 
-  return { sentences: sentences.length, recognized, skipped: sentences.length - recognized, facts };
+  return { sentences: sentenceCount, recognized, skipped: sentenceCount - recognized, facts };
 }
 
 /**
@@ -92,15 +171,15 @@ export async function groundTextToFacts(text, { memoryDir, sessionId, graph, lex
  * the page can then export. `seedPayload` (optional) pre-loads a graph the
  * recognizer can recall and link against.
  *
- * Returns { memoryDir, sessionId, ingest }. `ingest(text, { onFact })` is the
- * one call the page makes; it drives groundTextToFacts against this session's
- * store and returns its { sentences, recognized, skipped, facts } summary.
+ * Returns { memoryDir, sessionId, ingest }. `ingest(text, { onFact,
+ * optimistic })` is the one call the page makes; it drives groundTextToFacts
+ * against this session's store and returns its { sentences, recognized,
+ * skipped, facts } summary.
  */
 export function createIngestSession({ seedPayload = null, vocabSeeded = false } = {}) {
   const memoryDir = createInMemoryStore();
   if (seedPayload) memoryDir.payload = { ...memoryDir.payload, ...seedPayload };
 
-  const graph = parseEntities({ individuals: [], objectProperties: [] });
   const lexicon = loadLexicon();
   const vocabHint = vocabExampleHint(vocabSeeded);
   const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
@@ -108,8 +187,8 @@ export function createIngestSession({ seedPayload = null, vocabSeeded = false }
   return {
     memoryDir,
     sessionId,
-    ingest(text, { onFact = null } = {}) {
-      return groundTextToFacts(text, { memoryDir, sessionId, graph, lexicon, vocabHint, onFact });
+    ingest(text, { onFact = null, optimistic = false } = {}) {
+      return groundTextToFacts(text, { memoryDir, sessionId, lexicon, vocabHint, onFact, optimistic });
     },
   };
 }
@@ -123,4 +202,7 @@ export async function exportFactsJsonl(memoryDir) {
   return serializeFactsJsonl(await loadMemory(memoryDir));
 }
 
-globalThis.tmctIngest = { createIngestSession, groundTextToFacts, exportFactsJsonl, registerWinkModel, normFactTerm };
+globalThis.tmctIngest = {
+  createIngestSession, groundTextToFacts, exportFactsJsonl, registerWinkModel, normFactTerm,
+  memoryStats, openPersistedStore,
+};

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

@@ -23,6 +23,7 @@ import { splitSentencesPreservingPaths } from "../../services/sentences.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import { registerWinkModel } from "../../adapters/wink-model.mjs";
+import { registerResearchProvider } from "../../adapters/corpus/wikipedia-live.mjs";
 import { computeLedgerDataFromPayload } from "../../services/ledger-viz.mjs";
 
 /**
@@ -54,6 +55,7 @@ export function createLedgerSession({ seedPayload = null, vocabSeeded = false }
   let focus = null;
   let last = null;
   let planState = null;
+  let researchState = null;
 
   return {
     memoryDir,
@@ -66,16 +68,20 @@ export function createLedgerSession({ seedPayload = null, vocabSeeded = false }
       try {
         result = await runTurn(line, {
           config: null, source: null, graph, focus, last, memoryDir, sessionId,
-          env: {}, lexicon, vocabHint, planState,
+          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 };
+        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;
-      return { answer: result.answer, end: Boolean(result.end), record: result.record ?? null };
+      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 };
     },
   };
 }
@@ -95,4 +101,4 @@ export async function exportFactsJsonl(memoryDir) {
 // splitSentences + exportFactsJsonl carry the dock's paste-and-drop ingest and
 // its JSONL export across the bundle boundary, the same one-serializer posture
 // chat-browser-entry.mjs holds for its own page.
-globalThis.tmctLedger = { createLedgerSession, computeLedgerDataFromPayload, normFactTerm, registerWinkModel, splitSentences: splitSentencesPreservingPaths, exportFactsJsonl };
+globalThis.tmctLedger = { createLedgerSession, computeLedgerDataFromPayload, normFactTerm, registerWinkModel, registerResearchProvider, splitSentences: splitSentencesPreservingPaths, exportFactsJsonl };