@polycode-projects/the-mechanical-code-talker 3.0.0 → 3.0.2

package/src/services/chat.mjs

@@ -22,6 +22,7 @@ import { dispatchTool, loadGraph, TOOLS } from "../tools/server.mjs";
 import { ToolError } from "../adapters/config.mjs";
 import { parseEntities, edgesOfKind, moduleCountOf, renderAuthorCard, renderAuthorTouches, renderCommitAuthor, resolveSymbol, renderCompare } from "../domain/codegraph.mjs";
 import { classDisplayName, DYNAMIC_TAIL_OK_RE } from "../domain/ask.mjs";
+import { emptyRecord as emptyDiscourseRecord, advanceTurn as advanceDiscourseTurn, register as registerReferent, bind as bindDiscourseForm } from "../domain/discourse.mjs";
 import { uuidv7 } from "../adapters/uuid.mjs";
 import * as defaultSource from "../adapters/source.mjs";
 import { loadTemplates, render as renderTemplate } from "../adapters/corpus/templates.mjs";
@@ -1074,6 +1075,15 @@ const CAPABILITY_PHRASES = [
   /^(?:can you\s+)?walk me through (?:this|the)\s+(?:app|codebase|repo|repository|project|code)\??$/i,
   /^(?:what(?:'s|s|\s+is)|give me|show me|gimme) the big picture(?:\s+(?:here|(?:on|of|for|about)\s+(?:this|the)\s+(?:app|codebase|repo|repository|project|code)))?\??$/i,
   /^(?:give me|what's) the lay of the land\??$/i,
+  // "give me an overview" / "an overview" — the plain-word sibling of "the
+  // big picture" just above, same optional here/of-this-repo tail. Without a
+  // closed entry the word "overview" prose-matches real symbols in an
+  // indexed graph (moduleOverviewText) and the describe rescue dumps that
+  // symbol's card. The detailed forms ("give me a detailed overview of X")
+  // carry a mandatory "detailed"+of-term and stay with the completions
+  // rescue, untouched by this anchor.
+  /^(?:(?:can|could|would) you\s+)?(?:give me|show me|gimme)\s+an overview(?:\s+(?:here|(?:on|of|for|about)\s+(?:this|the)\s+(?:app|codebase|repo|repository|project|code)))?\??$/i,
+  /^an overview(?:\s+please)?\??$/i,
   // "what have we got here"/"what've we got here" — a casual, self-answering
   // opener (matches after a leading "so" strips via LEADING_CONNECTIVE_RE,
   // leaving this as the bare remainder).
@@ -5545,9 +5555,24 @@ async function moduleOrientLane(query, { graph }) {
   // to end in a module path would be claimed here.
   const tailLooksLikePath = !!(m || identityMatch) && phraseWords.length > 1 && MODULE_PATH_RE.test(pathTail);
   // The identity phrasing ("what is <term>") only ever claims a path-shaped
-  // term — bare, or with modifier words ahead of a path-shaped tail; the
-  // orient/purpose phrasings carry their own anchors.
-  if (!m && !MODULE_PATH_RE.test(bare) && !tailLooksLikePath) return null;
+  // term — bare, or with modifier words ahead of a path-shaped tail — or,
+  // below, a bare extensionless module basename.
+  //
+  // "what is codegraph": both siblings of that question already resolve the
+  // module ("what is codegraph.mjs" via MODULE_PATH_RE, "describe codegraph"
+  // via resolveSymbol's basename tier), so the extensionless identity form
+  // resolves by the same evidence — exact basename-stem equality against
+  // exactly ONE module. The gate stays strict: a single bare word with no
+  // article (an articled "what is a dog" keeps its vocabulary reading), and
+  // any tie or non-module term declines unchanged.
+  if (!m && !MODULE_PATH_RE.test(bare) && !tailLooksLikePath) {
+    if (!identityMatch || !/^[\w$][\w$.-]*$/.test(identityMatch)) return null;
+    const stemLc = bare.toLowerCase();
+    const stemHits = graph.individuals.filter((i) => i.class === "Module"
+      && String(i.label).toLowerCase().split("/").pop().replace(/\.[a-z0-9]+$/, "") === stemLc);
+    if (stemHits.length !== 1) return null;
+    return { text: moduleOverviewText(graph, stemHits[0]), via: "meta" };
+  }
   const ent = await resolveEntity(graph, m ? phrase : bare);
   if (ent) {
     const ind = graph.byId?.get?.(ent.id);
@@ -6411,6 +6436,37 @@ function senseSplitFactList(hits, rows, subjectVariants, { indent = "" } = {}) {
   return { lines, grouped };
 }
 
+// A subject-scan term answer longer than this many flat fact lines leads with a
+// deterministic digest paragraph (src/domain/digest) and holds the full list
+// behind the escape; a shorter answer is already readable as a list.
+const DIGEST_READBACK_THRESHOLD = 8;
+
+/** The digest lead for a subject-scan term answer: a bounded narrative first
+ *  (selection, sentence structures, composition — all deterministic, no model),
+ *  the full fact list held behind the "show the facts"/"more" escape. `termRows`
+ *  are the term's own fact rows, `allRows` the whole store the statistics scan
+ *  over, `lines` the already-rendered flat fact list the escape reveals.
+ *
+ *  Returns { text, pending } or null. Null when the structure bank is
+ *  unavailable (the in-browser dock stubs the filesystem loader out) or the
+ *  selector kept nothing renderable, so the caller falls back to the flat list —
+ *  the same graceful degradation the construction banks take in a browser
+ *  bundle. Deterministic; the digest reads only stored facts. */
+async function termDigestReadBack(term, termRows, allRows, lines) {
+  let digestTermFromRows;
+  try { ({ digestTermFromRows } = await import("../adapters/corpus/digest-bank.mjs")); }
+  catch { return null; }
+  let article;
+  try { article = digestTermFromRows(term, termRows, allRows); }
+  catch { return null; }
+  if (!article || !article.paragraphs.length) return null;
+  const sources = [...new Set((article.sources || []).map((s) => s.provenance).filter(Boolean))];
+  const sourceLine = sources.length ? `(sources: ${sources.join("; ")})\n` : "";
+  const escape = `Say 'show the facts' for all ${lines.length} stored facts.`;
+  const text = `${article.paragraphs.join("\n\n")}\n\n${sourceLine}${escape}`;
+  return { text, pending: { items: lines, noun: "facts" } };
+}
+
 /** "a"/"an" for a term, through the SAME grammar-rules.toml "article" rule and
  *  finish.mjs's beginsWithVowelSound every other agreement site in this file
  *  uses — never a hardcoded "a", which is ungrammatical for a vowel-initial
@@ -7538,7 +7594,17 @@ async function factAnswerReaders(memoryDir, query, envelope, miss, biasByBundle
     // "disclosed, never dropped" contract). Unconfigured/tied bias degrades to
     // trust-desc, byte-identical to before this feature existed.
     hits = rankByBiasThenTrust(hits, biasByBundle);
-    const { lines, grouped } = senseSplitFactList(hits, await factRows(memoryDir, cache), variants);
+    const allRows = await factRows(memoryDir, cache);
+    const { lines, grouped } = senseSplitFactList(hits, allRows, variants);
+    // A long undifferentiated "what is X" leads with the digest — a bounded
+    // narrative over the same facts — and holds the full list behind the escape.
+    // It wins over the sense-split grouping here: the digest's own selector
+    // filters the mis-sensed branch that grouping would otherwise surface as its
+    // own block. Falls back to grouping/flat when the digest is unavailable.
+    const digested = (!predicate && lines.length > DIGEST_READBACK_THRESHOLD)
+      ? await termDigestReadBack(subject, hits, allRows, lines)
+      : null;
+    if (digested) return { ...digested, replace: miss };
     if (grouped) return { ...grouped, replace: miss };
     const shown = lines.slice(0, FACT_ANSWER_CAP);
     const rest = lines.slice(FACT_ANSWER_CAP);
@@ -11813,7 +11879,31 @@ const DECISION_RECALL_RE = /^(?:remind\s+me\s+)?what\s+(?:did\s+)?(?:we|i|you)\s
  *  than silently accepted alongside the current location. */
 const MOVE_HISTORY_RE = /^where\s+did\s+(.+?)\s+(?:move|get\s+moved|go)(?:\s+to)?[?.!\s]*$/i;
 
-async function runAsk(query, { config, source, graph, focus, last, templates, memoryDir, sessionId = "", lexicon = null, env, trace, vocabHint = null, tel = null, biasByBundle = {}, cache = null, vocabAntecedent = null, planHolder = null, gameConfig = DEFAULT_GAME_CONFIG, liveReference = false, onLiveLookup = null, uiContext = "cli", synthesisBudget = AUTO_SYNTHESIS_BUDGET }) {
+/** "was that before logger.mjs was touched" — a singular bindable form, a
+ *  comparison word, and an embedded passive clause. The closed participle set
+ *  is the touch family the when-question path answers; anything else keeps
+ *  the honest miss. */
+const TEMPORAL_COMPARISON_RE = /^(?:was|is)\s+(this one|that one|it|this|that)\s+(before|after)\s+(.+?)\s+(?:was|were)\s+(touched|changed|modified|edited|updated)[?.!\s]*$/i;
+
+/** ARCHITECTURE-OVERVIEW intent — "show me the architecture", "what is the
+ *  architecture of this repo": the whole-repo map the /arch command renders.
+ *  A closed phrase set, because the literal word "architecture" is also a
+ *  plausible SYMBOL substring in many graphs (renderArchitecture,
+ *  tmct_architecture) — the symbol-describe rescues would otherwise resolve
+ *  the word to one such symbol and dump its definition card instead of the
+ *  map. Every phrasing here names the architecture as a TOPIC (an article,
+ *  an of-this-repo tail, or an overview/map noun); a query that NAMES a
+ *  symbol ("describe renderArchitecture") never matches. */
+const ARCH_OVERVIEW_LEAD = "(?:(?:can|could|would)\\s+you\\s+(?:please\\s+)?)?(?:(?:show|give)\\s+(?:me|us)\\s+|describe\\s+|explain\\s+|what(?:'s|s|\\s+is)\\s+)?";
+const ARCH_OVERVIEW_TAIL = "(?:\\s+(?:of|for)\\s+(?:this|the)\\s+(?:app|codebase|repo|repository|project|code))?";
+const ARCH_OVERVIEW_PHRASES = [
+  // Article-carried: "the architecture" alone, or wrapped/tailed.
+  new RegExp(`^${ARCH_OVERVIEW_LEAD}the\\s+architecture(?:\\s+(?:overview|map|diagram))?${ARCH_OVERVIEW_TAIL}(?:\\s+here)?\\??$`, "i"),
+  // Article-less: anchored by the of-this-repo tail or the overview/map noun instead.
+  new RegExp(`^${ARCH_OVERVIEW_LEAD}architecture\\s+(?:(?:of|for)\\s+(?:this|the)\\s+(?:app|codebase|repo|repository|project|code)|overview|map|diagram)\\??$`, "i"),
+];
+
+async function runAsk(query, { config, source, graph, focus, last, templates, memoryDir, sessionId = "", lexicon = null, env, trace, vocabHint = null, tel = null, biasByBundle = {}, cache = null, vocabAntecedent = null, planHolder = null, discourseHolder = null, gameConfig = DEFAULT_GAME_CONFIG, liveReference = false, onLiveLookup = null, uiContext = "cli", synthesisBudget = AUTO_SYNTHESIS_BUDGET }) {
   const ts = new Date().toISOString();
   // The surface this turn runs on ("cli" default; "browser" from a web entry) —
   // the honest-miss tail below points a browser/adventure miss at the teach
@@ -11842,6 +11932,45 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       .replace(/^(?:and|so|then|also)\s+/i, "")
       .replace(/how many\s+/i, "how many of those ");
   }
+  // TEMPORAL COMPARISON ACROSS TURNS — "was that before logger.mjs was
+  // touched": a singular bindable form, a comparison word, and an embedded
+  // passive clause. The form binds against the session's discourse record (a
+  // dated referent a previous answer established), the embedded clause runs
+  // fresh through the same when-question path a standalone turn takes, and
+  // the two ISO dates compare with both sides cited. Checked BEFORE the ask
+  // engine (the same precedence RENAME_HISTORY_RE takes, below) so the
+  // sentence never reaches the keyword-spot strategy's multi-token patient
+  // guard; an unbound form, an undated referent, or an unanswerable clause
+  // all fall through, and that guard's honest miss stands unchanged.
+  {
+    const cmp = graph && discourseHolder ? String(query).trim().match(TEMPORAL_COMPARISON_RE) : null;
+    if (cmp) {
+      const [, form, cmpOp, clauseSubject, participle] = cmp;
+      const bound = bindDiscourseForm(discourseHolder.record, form);
+      const refDay = String(bound?.referent?.attrs?.date || "").slice(0, 10);
+      if (bound?.referent && refDay) {
+        const { ask } = await import("../domain/ask.mjs");
+        const fresh = ask(graph, `when was ${clauseSubject} ${participle}`);
+        const freshHit = (!fresh?.tmct_ask?.miss && !fresh?.tmct_ask?.ambiguous) ? fresh?.tmct_ask?.matches?.[0] : null;
+        const freshCommit = freshHit?.id ? graph.byId?.get?.(freshHit.id) : null;
+        const clauseDay = freshCommit?.class === "Commit"
+          ? String((freshCommit.attributes || []).find((a) => a.key === "date")?.value || "").slice(0, 10)
+          : "";
+        if (clauseDay) {
+          const holds = cmpOp.toLowerCase() === "before" ? refDay < clauseDay : refDay > clauseDay;
+          const relation = refDay < clauseDay ? "came before" : refDay > clauseDay ? "came after" : "landed on the same day as";
+          const verb = participle.toLowerCase();
+          const text = `${holds ? "Yes" : "No"} — ${bound.referent.label} (${refDay}) ${relation} ${clauseSubject} was last ${verb} (${freshCommit.label}, ${clauseDay}).`;
+          note(trace, "goal: compare a prior answer's dated referent against a freshly read event (cross-turn temporal composition)");
+          note(trace, `lane: TEMPORAL_COMPARISON_RE — "${form}" bound ${bound.referent.label} (${refDay}) through the discourse record; the embedded clause re-ran as its own when-question`);
+          const turn = plainTurn(query, text, { via: "composed", miss: false, focus });
+          const cited = [graph.byId?.get?.(bound.referent.ids[0]), freshCommit].filter(Boolean);
+          turn.detail = { traversal: `discourse ${bound.referent.ref} (${refDay}) vs last-${verb} of ${clauseSubject} (${clauseDay})`, matches: cited };
+          return turn;
+        }
+      }
+    }
+  }
   // RENAME HISTORY — "what was X called before" and its siblings. The index
   // records current names only, and without this gate "called" fuzzes onto
   // the calls relation ("before" simply drops), so the reply read as fluent
@@ -12020,6 +12149,17 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       "isn't resolved to anything yet — name the term directly, or ask a question that resolves one first.",
     );
     if (envJson) { try { envelope = JSON.parse(envJson); } catch { envelope = null; } }
+    // Typed discourse referents the answer established (the ask envelope's
+    // additive `discourse` field, emitted beside the eval where the answer's
+    // content is still typed) register into the session's record here — the
+    // one point both ask paths (direct call and dispatchTool) converge.
+    if (discourseHolder && Array.isArray(envelope?.discourse)) {
+      for (const { lane, ...spec } of envelope.discourse) {
+        discourseHolder.record = registerReferent(discourseHolder.record, {
+          ...spec, from: { turn: discourseHolder.record.turn, lane, query: askQuery },
+        });
+      }
+    }
   } catch (e) {
     const thrown = String(e?.message || e);
     // A graph-less session's ask dispatch fails reading the never-configured
@@ -12198,10 +12338,32 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       note(trace, `goal: ${deduced} (revised — the raw \"what else\" phrasing was recognized directly, not the relaxed/reparsed envelope)`);
     }
   }
+  // (0a) ARCHITECTURE OVERVIEW — see ARCH_OVERVIEW_PHRASES. Answered here,
+  // before the meta/orientation lanes and long before the symbol-resolve
+  // rescues (4d), so the closed architecture phrasings reach the map instead
+  // of a literal-token symbol card or the vocabulary-touch teach offer.
+  if (!handled && miss && graph && !noCodeGraph(graph)) {
+    // The RAW text is tried alongside the peeled one: applyPreambleFrames'
+    // show/give-me bridge rewrites "show me the architecture" into "describe
+    // architecture", which drops the article this closed set anchors on.
+    const archRaw = correctMisspellings(String(query).trim());
+    const archPeeled = applyPreambleFrames(archRaw);
+    if (ARCH_OVERVIEW_PHRASES.some((re) => re.test(archRaw) || re.test(archPeeled))) {
+      try {
+        const archText = await dispatchTool("tmct_architecture", {}, { config, source, tel });
+        if (archText) {
+          answer = archText; via = "meta"; recordMiss = false; handled = true;
+          deduced = "understand the overall architecture (package/module boundaries)";
+          note(trace, `goal: ${deduced} (revised — a closed architecture-overview phrasing was recognized directly)`);
+          note(trace, "lane: (0a) ARCHITECTURE OVERVIEW — routed to the whole-repo architecture map (/arch), never a literal symbol lookup on the word \"architecture\"");
+        }
+      } catch { /* the tool couldn't load a graph — the ordinary lanes decide */ }
+    }
+  }
   // (1) #2 META/SELF: bare self/session questions ("what do you know", "what is this
   // codebase", "how do i start") → a summary / orientation, answered before the
   // fact-dump readers so "what do you know" gets a summary, not raw facts.
-  if (miss) {
+  if (!handled && miss) {
     const meta = await metaLane(query, { graph, memoryDir, last, templates, vocabHint, focus });
     if (meta) {
       // A lane may answer with a better-worded decline (the module-orient
@@ -13751,7 +13913,11 @@ async function assertTurn(line, { memoryDir, sessionId, focus, lexicon = null, c
 // the same pending state. Any other (real) query produces a fresh `last` without
 // `pending`, so the remainder is naturally cleared — no stale continuation. ----
 const PAGE = 32;
-const MORE_RE = /^(?:more|show more|see more|the rest|next|continue|go on)\b[.!?]*$/i;
+// "show the facts"/"show the chains" are the digest read-back's own escape
+// (the digest holds the full fact list — chains included, since the flat lines
+// carry their is-a ancestry — on the same pending remainder), folded in here so
+// they page the held list exactly as "more" does.
+const MORE_RE = /^(?:more|show more|see more|the rest|next|continue|go on|show(?: me)? the facts|show the chains)\b[.!?]*$/i;
 
 /** The impact-intent gate — "what would break if I change X" and its natural
  *  neighbours, routed to the same /impact closure. Sibling of normalize.mjs's
@@ -14337,7 +14503,7 @@ function vocabAntecedentFrom(last) {
   return m[1];
 }
 
-export async function runTurn(input, { config, source = defaultSource, graph = null, focus = null, last = null, memoryDir = null, sessionId = "", env = process.env, lexicon = null, narrate = false, liveReference = false, onLiveLookup = null, vocabHint = null, tel = null, biasByBundle = {}, factRowsCache: injectedFactRowsCache = null, planState = null, gameConfig = null, uiContext = "cli", synthesisBudget = AUTO_SYNTHESIS_BUDGET, researchState = null, researchConfig = null, _noSplit = false } = {}) {
+export async function runTurn(input, { config, source = defaultSource, graph = null, focus = null, last = null, memoryDir = null, sessionId = "", env = process.env, lexicon = null, narrate = false, liveReference = false, onLiveLookup = null, vocabHint = null, tel = null, biasByBundle = {}, factRowsCache: injectedFactRowsCache = null, planState = null, gameConfig = null, uiContext = "cli", synthesisBudget = AUTO_SYNTHESIS_BUDGET, researchState = null, researchConfig = null, discourse = null, _noSplit = false } = {}) {
   // Every game's tuning knobs (spider-fly's mass economy, guess-the-number's
   // bounds, the shared plan lane's search-depth cap) — a caller's own
   // gameConfig (chat-session.mjs resolves one per session from tmct.toml)
@@ -14402,7 +14568,12 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
   // the PLAN NEXT block below write planHolder.state; every other path leaves
   // it untouched, and the caller re-threads whatever comes back.
   const planHolder = { state: planState };
-  const ctx = { config, source, graph, focus, last, memoryDir, sessionId, templates, env, lexicon, trace, narrate, liveReference, onLiveLookup, vocabHint: resolvedVocabHint, tel, biasByBundle, cache: factRowsCache, vocabAntecedent, planHolder, gameConfig: resolvedGameConfig, uiContext, synthesisBudget };
+  // The session's typed discourse record rides the same holder pattern,
+  // threaded turn-to-turn beside focus and last. Registration happens where
+  // an answer's typed content is in hand (runAsk, off the ask envelope's
+  // `discourse` referents); the caller re-threads whatever comes back.
+  const discourseHolder = { record: discourse ?? emptyDiscourseRecord() };
+  const ctx = { config, source, graph, focus, last, memoryDir, sessionId, templates, env, lexicon, trace, narrate, liveReference, onLiveLookup, vocabHint: resolvedVocabHint, tel, biasByBundle, cache: factRowsCache, vocabAntecedent, planHolder, discourseHolder, gameConfig: resolvedGameConfig, uiContext, synthesisBudget };
   // A DISPATCHED turn (count / slash-command / ask) becomes the new "last
   // answer" that why/say-more re-renders; a conversational turn does not.
   // Every dispatched turn's result passes through finish() here — the LAST
@@ -14446,10 +14617,16 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
       detail: finished.detail ?? null,
       grounded: finished.record?.miss ? (last?.grounded ?? null) : finished.answer,
     };
+    // Every dispatched turn advances the discourse record's turn counter —
+    // the counter is the registration ordinal that makes a same-turn tie
+    // detectable, so it moves once, here, on the one path every dispatched
+    // turn shares. Conversational turns bypass withLast and leave the record
+    // untouched, exactly as they leave `last`.
+    discourseHolder.record = advanceDiscourseTurn(discourseHolder.record);
     // Goal/canonical lines append onto the PRE-narration `finished` result
     // `nextLast` was captured from, so a narrated turn still gets both short
     // lines up top plus the full trace block after.
-    return { ...withNarration(withCanonicalLine(withGoalLine(finished)), trace, fallbackGoal), last: nextLast };
+    return { ...withNarration(withCanonicalLine(withGoalLine(finished)), trace, fallbackGoal), last: nextLast, discourse: discourseHolder.record };
   };
 
   // Slash-optional system commands: a bare leading command word ("stats",
@@ -14692,17 +14869,18 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
         && await everySentenceTeaches(sentences.slice(0, -1), lexicon);
       const finalIsPayload = endsInPlanTrigger || teachesThenAsks;
       if (finalIsPayload || await everySentenceTeaches(sentences, lexicon)) {
-        let f = focus; let l = last; let ps = planHolder.state;
+        let f = focus; let l = last; let ps = planHolder.state; let d = discourseHolder.record;
         const receipts = [];
         let finalRec = null;
         for (const sentence of sentences) {
           const r = await runTurn(sentence, {
             config, source, graph, focus: f, last: l, memoryDir, sessionId, env, lexicon,
-            narrate: false, vocabHint, tel, biasByBundle, planState: ps, _noSplit: true,
+            narrate: false, vocabHint, tel, biasByBundle, planState: ps, discourse: d, _noSplit: true,
           });
           f = r.focus ?? f;
           l = r.last ?? l;
           if ("planState" in r) ps = r.planState;
+          if ("discourse" in r) d = r.discourse;
           finalRec = r;
           receipts.push(String(r.answer ?? "").split("\n")[0]);
         }
@@ -14725,6 +14903,7 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
         combined.planState = ps;
         combined.focus = f;
         combined.last = l;
+        combined.discourse = d;
         // Each per-sentence turn recorded only its OWN sentence; the transcript
         // echo and the turn record must quote the whole multi-sentence line the
         // user actually typed, not just its last sentence.

package/src/services/ledger-viz.mjs

@@ -504,8 +504,8 @@ function sparkCaptionHtml(stats) {
  *  different questions (did this render even offer the reference; did the
  *  browser actually manage to load it), and both must hold for the live
  *  path to run. */
-export function renderLedgerHtml({ rows, terms, edges, focus, contradictions, worthALook, payload, meta, memoryAskBundle, stats, ledgerBundleAvailable = false } = {}) {
-  const ledgerJson = embedJson({ rows: rows || [], terms: terms || [], edges: edges || [], focus: focus || null, contradictions: contradictions || [], worthALook: worthALook || null, meta: meta || { shown: 0, total: 0, truncated: false } });
+export function renderLedgerHtml({ rows, terms, edges, focus, contradictions, worthALook, payload, meta, memoryAskBundle, stats, ledgerBundleAvailable = false, focusDigest = null } = {}) {
+  const ledgerJson = embedJson({ rows: rows || [], terms: terms || [], edges: edges || [], focus: focus || null, contradictions: contradictions || [], worthALook: worthALook || null, meta: meta || { shown: 0, total: 0, truncated: false }, focusDigest: focusDigest || null });
   const payloadJson = embedJson(payload || { individuals: [], objectProperties: [] });
   const shown = meta?.shown ?? (rows || []).length;
   const title = `tmct ledger — ${shown} fact${shown === 1 ? "" : "s"}${focus ? ` (focus: ${escapeHtml(focus)})` : ""}`;
@@ -641,6 +641,9 @@ ${THEME_TOKENS_CSS}
   .focuscard { background: var(--card); border: 1px solid var(--line); border-radius: 10px; padding: .8rem 1rem; margin-bottom: 1rem; }
   .focuscard .term { font-size: 1.35rem; font-weight: 700; }
   .focuscard .klass, .focuscard .stats { font-family: ${MONO_STACK}; font-size: .72rem; color: var(--muted); margin-top: .3rem; font-variant-numeric: tabular-nums; }
+  .focuscard .focusdigest { margin-top: .7rem; font-size: .92rem; line-height: 1.5; }
+  .focuscard .focusdigest p { margin: 0 0 .4rem; }
+  .focuscard .focusdigest .dgsrc { font-family: ${MONO_STACK}; font-size: .7rem; color: var(--muted); margin-top: .2rem; }
   .group { margin: 1.1rem 0; }
   .group h3 { font-family: ${MONO_STACK}; font-size: .68rem; letter-spacing: .08em; text-transform: uppercase; color: var(--muted); font-weight: 400; margin: 0 0 .35rem; display: flex; align-items: baseline; gap: .5rem; }
   .group h3::after { content: ""; flex: 1; border-top: 1px solid var(--line); transform: translateY(-.2em); }
@@ -860,10 +863,18 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
     const srcs = new Set(all.map((r) => r.src.split(" | ")[0]));
     const dates = all.map((r) => r.createdAt).filter(Boolean).sort();
     const klass = all.find((r) => r.s === focus && r.family === "is-a");
+    // The digest paragraph is computed server-side for the page's initial focus
+    // (renderLedgerHtml has the payload and reads the sentence-structure bank);
+    // a client refocus to another term shows the fact groups without it.
+    const dg = (focus === LEDGER.focus && LEDGER.focusDigest && LEDGER.focusDigest.paragraphs && LEDGER.focusDigest.paragraphs.length) ? LEDGER.focusDigest : null;
+    const digestHtml = dg
+      ? '<div class="focusdigest">' + dg.paragraphs.map((p) => "<p>" + esc(p) + "</p>").join("") +
+        (dg.sources && dg.sources.length ? '<p class="dgsrc">sources: ' + esc(dg.sources.join("; ")) + "</p>" : "") + "</div>"
+      : "";
     let html = '<div class="focuscard"><div class="term">' + esc(focus) + "</div>" +
       '<div class="klass">' + (klass ? esc(klass.phrase + " " + klass.o) : "no class recorded") + "</div>" +
       '<div class="stats">' + all.length + " facts &middot; " + srcs.size + " source" + (srcs.size === 1 ? "" : "s") +
-      (dates.length ? " &middot; first " + esc(dates[0].slice(0, 10)) + " &middot; last " + esc(dates[dates.length - 1].slice(0, 10)) : "") + "</div></div>";
+      (dates.length ? " &middot; first " + esc(dates[0].slice(0, 10)) + " &middot; last " + esc(dates[dates.length - 1].slice(0, 10)) : "") + "</div>" + digestHtml + "</div>";
     const bracketed = new Set();
     for (const fam of FAMS) {
       const rows = mine.filter((r) => r.family === fam && !bracketed.has(r.id));

package/src/services/sessions.mjs

@@ -48,7 +48,9 @@ function labelFromId(id) {
  *  reader never sees a torn graph.json and a crash never destroys the old one. */
 async function atomicWriteJson(file, obj) {
   const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
-  await writeFile(tmp, JSON.stringify(obj));
+  // 2-space indent: a legitimate session upsert into a hand-formatted graph
+  // reflows to the same pretty shape a producer wrote, not one compact line.
+  await writeFile(tmp, JSON.stringify(obj, null, 2));
   await rename(tmp, file);
 }