@polycode-projects/the-mechanical-code-talker 2.10.3 → 2.11.0

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

@@ -304,7 +304,7 @@ ${THEME_TOKENS_CSS}
      split plus the gap approximates that pair of fractions without them
      needing to sum to a full width. */
   .stage { display: grid; grid-template-columns: minmax(0, 8fr) minmax(280px, 3fr); gap: 1.2rem; align-items: start; }
-  @media (max-width: 760px) { .stage { grid-template-columns: 1fr; } }
+  @media (max-width: 760px) { .stage { grid-template-columns: minmax(0, 1fr); } }
   /* A dusty window corner: a soft light glow near the top-left (WEB_HOME
      already sits near that corner — spider-fly-world.mjs's own header
      comment), and a faint diagonal weave standing in for dust/silk caught
@@ -346,10 +346,21 @@ ${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; }
+  /* Both the controls strip above the board and the tuning strip below it
+     match the board's own width (not the wider stage-left column they sit
+     in), so all three line up as one visual stack. */
+  .tuning, .controls-panel, .head-inner { width: ${BOARD_PX}px; max-width: 100%; margin: 0 auto; box-sizing: border-box; }
+  /* the eyebrow+h1 sit in their own board-width column (.head-inner), inside
+     a .page-head row that mirrors the real board's own 8fr/3fr split below
+     it — the second, empty column just holds that split in place so the
+     first column's own left edge lines up with the board's, instead of the
+     wider page margin. min-width: 0 matches .stage-left's own override:
+     without it, a grid item's default automatic minimum size is its
+     content's own max-content width, and at the phone-width single-column
+     override below the fixed-width child would force the track (and the
+     page) wider than the viewport instead of actually shrinking. */
+  .page-head { margin-bottom: 0; }
+  .head-inner { min-width: 0; }
   .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;
@@ -447,7 +458,7 @@ ${THEME_TOKENS_CSS}
   .tuning-col.spider input[type="range"]::-moz-range-thumb { border-color: var(--taught); }
   .tuning-col.fly input[type="range"]::-moz-range-thumb { border-color: var(--fly); }
   .tuning-col input:disabled { opacity: .45; }
-  .controls-row { display: flex; align-items: center; gap: .6rem; margin-top: 1rem; flex-wrap: wrap; }
+  .controls-row { display: flex; align-items: center; gap: .6rem; flex-wrap: wrap; }
   /* Chunky keycaps: raised by default, pressed-in on :active — the one place
      this redesign uses interaction (not animation) to sell "physical
      control panel", and it costs nothing under reduced-motion since neither
@@ -461,19 +472,39 @@ ${THEME_TOKENS_CSS}
      page is remembered by. */
   .controls-row .turn { margin-left: auto; font-family: ${MONO_STACK}; font-size: .82rem; letter-spacing: .05em; text-transform: uppercase; font-variant-numeric: tabular-nums; color: var(--chrome-well-ink); background: var(--chrome-well); border: 1px solid var(--chrome-brass); box-shadow: var(--chrome-shadow-inset); border-radius: 2px; padding: .3rem .7rem; }
   .status { font-family: ${MONO_STACK}; font-size: .74rem; color: var(--muted); margin-top: .5rem; padding-left: .5rem; border-left: 2px solid var(--chrome-brass); }
-  body.preview .side, body.preview .controls-row, body.preview .status, body.preview .tuning { display: none; }
+  body.preview .side, body.preview .controls-panel, body.preview .tuning { display: none; }
   body.preview main { padding: 0; max-width: none; }
   body.preview .stage, body.preview .stage-left { display: block; }
   body.preview .board-frame { margin: 0; }
-  body.preview .eyebrow, body.preview h1 { display: none; }
+  body.preview .page-head { display: none; }
 </style>
 </head>
 <body>
 <main>
-  <div class="eyebrow">tmct &middot; spider and fly</div>
-  <h1>Multiple competing planning agents</h1>
+  <div class="stage page-head">
+    <div class="head-inner">
+      <div class="eyebrow">tmct &middot; spider and fly</div>
+      <h1>Multiple competing planning agents</h1>
+    </div>
+    <div></div>
+  </div>
   <div class="stage">
     <div class="stage-left">
+    <div class="controls-panel" id="controlsPanel" aria-label="game controls">
+      <div class="controls-row">
+        <button id="resetBtn" type="button" disabled>reset</button>
+        <button id="playBtn" type="button" disabled>&#9654; play</button>
+        <button id="stepBtn" type="button" disabled>step</button>
+        <span class="turn mono" id="turnLabel">turn: 0</span>
+      </div>
+      <div class="status" id="status">loading the engine&hellip;</div>
+    </div>
+    <div class="board-frame" id="boardFrame">
+      <canvas id="board" width="${BOARD_PX}" height="${BOARD_PX}" aria-label="the 10x10 board"></canvas>
+      <canvas id="pov" width="${BOARD_PX}" height="${BOARD_PX}" aria-hidden="true"></canvas>
+      <div class="sprite-layer" id="spriteLayer"></div>
+      <div class="thread-tip" id="threadTip"></div>
+    </div>
     <div class="tuning" id="tuning">
       <h2>live tuning &mdash; mass loss, spawn rate, vision, per class</h2>
       <div class="tuning-grid">
@@ -497,12 +528,6 @@ ${THEME_TOKENS_CSS}
         </div>
       </div>
     </div>
-    <div class="board-frame" id="boardFrame">
-      <canvas id="board" width="${BOARD_PX}" height="${BOARD_PX}" aria-label="the 10x10 board"></canvas>
-      <canvas id="pov" width="${BOARD_PX}" height="${BOARD_PX}" aria-hidden="true"></canvas>
-      <div class="sprite-layer" id="spriteLayer"></div>
-      <div class="thread-tip" id="threadTip"></div>
-    </div>
     </div>
     <aside class="side" aria-label="Chat and agents">
       <div class="chat">
@@ -528,13 +553,6 @@ ${THEME_TOKENS_CSS}
       </div>
     </aside>
   </div>
-  <div class="controls-row">
-    <button id="resetBtn" type="button" disabled>reset</button>
-    <button id="playBtn" type="button" disabled>&#9654; play</button>
-    <button id="stepBtn" type="button" disabled>step</button>
-    <span class="turn mono" id="turnLabel">turn: 0</span>
-  </div>
-  <div class="status" id="status">loading the engine&hellip;</div>
 </main>
 <script>
 const SPIDERFLY = ${gridData};

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

@@ -19,6 +19,7 @@
 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 { 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";
@@ -32,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.
@@ -51,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
@@ -68,15 +71,28 @@ export function createChatSession({ seedPayload = null, vocabSeeded = false, liv
   let focus = null;
   let last = null;
   let planState = null;
-  let liveReferenceOn = Boolean(liveReference);
+  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: flip the live Wikipedia supplement for every
-     *  later turn (the `/wiki on|off` command flips the same state). */
-    setLiveReference(v) { liveReferenceOn = Boolean(v); },
+    /** 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). */
+    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. */
@@ -85,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") 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 };
     },
   };
 }
@@ -158,4 +179,4 @@ export async function exportFactsJsonl(memoryDir) {
   return serializeFactsJsonl(await loadMemory(memoryDir));
 }
 
-globalThis.tmctChat = { createChatSession, registerWinkModel, registerReferencePackProvider, registerLiveReferenceProvider, normFactTerm, vocabExampleHint, memoryStats, openPersistedStore, exportFactsJsonl };
+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

@@ -0,0 +1,208 @@
+// ingest-browser-entry.mjs — the esbuild entry for the ingest page's engine
+// (public/ingest-browser.bundle.js, built by scripts/build-ingest-bundle.mjs),
+// mirroring ledger-browser-entry.mjs's own createLedgerSession shape.
+//
+// The ingest page turns plain pasted/dropped text into stored facts by
+// running each sentence through the SAME deterministic recognizer the chat
+// teach lane already has (runTurn, src/services/chat.mjs) — no new NLU, no
+// LLM, no guessing, exactly as the `tmct extract` CLI does it
+// (src/services/extract-facts.mjs). A sentence the recognizer turns into a
+// stored assertion is kept; every other sentence is honestly skipped.
+//
+// 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.
+// 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
+// ledger-browser-entry.mjs documents for its own bundle. It carries the full
+// 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 { 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 { 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 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.
+ *
+ * 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.
+ */
+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;
+
+  // 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(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 {
+      return null; // a throwing sentence is a skip, never a page-killer
+    }
+    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: sentenceCount, recognized, skipped: sentenceCount - recognized, facts };
+}
+
+/**
+ * A browser ingest session over the real turn engine — a fresh in-memory
+ * Backend-B store, so facts grounded through the page extend one real graph
+ * 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,
+ * 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 lexicon = loadLexicon();
+  const vocabHint = vocabExampleHint(vocabSeeded);
+  const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
+
+  return {
+    memoryDir,
+    sessionId,
+    ingest(text, { onFact = null, optimistic = false } = {}) {
+      return groundTextToFacts(text, { memoryDir, sessionId, lexicon, vocabHint, onFact, optimistic });
+    },
+  };
+}
+
+/**
+ * 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

@@ -17,10 +17,13 @@
 // 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 } from "../../adapters/memory/core.mjs";
+import { createInMemoryStore, normFactTerm, loadMemory } from "../../adapters/memory/core.mjs";
+import { serializeFactsJsonl } from "../../adapters/memory/export-jsonl.mjs";
+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";
 
 /**
@@ -52,6 +55,7 @@ export function createLedgerSession({ seedPayload = null, vocabSeeded = false }
   let focus = null;
   let last = null;
   let planState = null;
+  let researchState = null;
 
   return {
     memoryDir,
@@ -64,22 +68,37 @@ 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 };
     },
   };
 }
 
+/** 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));
+}
+
 // Re-exported so ledger-viz.mjs's own inline script never has to duplicate
 // the derivation logic that builds rows/terms/edges/contradictions/
 // worthALook/stats from a payload — the same posture chat-browser-entry.mjs
 // takes re-exporting registerWinkModel for its own page's CDN wink load.
-globalThis.tmctLedger = { createLedgerSession, computeLedgerDataFromPayload, normFactTerm, registerWinkModel };
+// 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, registerResearchProvider, splitSentences: splitSentencesPreservingPaths, exportFactsJsonl };