@polycode-projects/the-mechanical-code-talker 3.0.10 → 3.1.2

package/src/services/chat.mjs

@@ -257,7 +257,12 @@ function renderNarration(trace, { record, detail, fallbackGoal }) {
  *  renderVerbose) see the exact same text a narrate:false run would have
  *  produced; narrate is purely additive to what's PRINTED, never to what's
  *  REMEMBERED. No-op (returns `result` unchanged, by reference) when `trace`
- *  is null (narrate off) or empty (nothing was traced). */
+ *  is null (narrate off) or empty (nothing was traced).
+ *
+ *  The same trace block also rides the result as its own `narration` field, so
+ *  an embedding caller reads the answer and the trace apart without splitting
+ *  the printed text on NARRATE_MARKER. `answer` keeps the glued form it always
+ *  had — the field is additive, and absent on a turn that traced nothing. */
 function withNarration(result, trace, fallbackGoal) {
   if (!trace || !trace.length) return result;
   const narrative = renderNarration(trace, { record: result.record, detail: result.detail, fallbackGoal });
@@ -265,7 +270,7 @@ function withNarration(result, trace, fallbackGoal) {
   const logLines = Array.isArray(result.logLines)
     ? result.logLines.map((l) => (l === result.answer ? answer : l))
     : result.logLines;
-  return { ...result, answer, logLines };
+  return { ...result, answer, narration: narrative, logLines };
 }
 
 /** A short "Goal (inferred): …" line appended (never prepended) after every
@@ -1111,14 +1116,26 @@ const CAPABILITY_PHRASES = [
   // anything nameable. Answered the same as any other vague opener: sure,
   // here's what I can help with.
   /^can i ask (?:you\s+)?something(?:\s+random)?\??$/i,
+  // The same orientation request with the SUBJECT flipped to "I" — "what can I
+  // ask you" rather than "what can you do". Every entry above reads "you" as
+  // the subject, so the flipped phrasings matched nothing and the bare "I"
+  // token went to the code-graph lane as a module name. The optional
+  // about-tail reuses META_ORIENT_RE's own closed self-referential noun list,
+  // so "what questions can I ask about <a real module>" is untouched.
+  /^what can (?:i|we) ask(?:\s+(?:you|u))?(?:\s+about (?:this|the)\s+(?:app|codebase|repo|repository|project|code))?\??$/i,
+  /^what questions can (?:i|we) ask(?:\s+(?:you|u))?(?:\s+about (?:this|the)\s+(?:app|codebase|repo|repository|project|code))?\??$/i,
+  /^what (?:kind|kinds|sort|sorts|type|types) of questions can (?:i|we) ask(?:\s+(?:you|u))?(?:\s+about (?:this|the)\s+(?:app|codebase|repo|repository|project|code))?\??$/i,
 ];
 /** IDENTITY questions — "who/what are you", by name, in plain or ESL-ish phrasing.
  *  Routed to a self-description (identity-self) that works regardless of graph
  *  state, never the code-graph deflection. */
 const IDENTITY_PHRASES = [
-  /^who are you\??$/i, /^what (is|are|r) (this|you)\??$/i,
+  // The optional adverb ("what EVEN is this thing", "what REALLY is this") is
+  // emphasis on the same question — without it the casual spelling missed the
+  // closed set entirely and the bare "this"/"I" token went to the graph lane.
+  /^who are you\??$/i, /^what (?:even |really |actually )?(is|are|r) (this|you)\??$/i,
   /^what('?s| is) your name\??$/i, /^what exactly are you\??$/i,
-  /^(tell me about|introduce) yourself\??$/i, /^what is this thing\??$/i,
+  /^(tell me about|introduce) yourself\??$/i, /^what (?:even |really |actually )?is this thing\??$/i,
   /^what am i (talking|speaking|chatting) (to|with)\??$/i,
   /^you are what\??$/i, /^what thing (are|is) you\??$/i,
   // "explain [to me|please]* what (you are|this is)" in EITHER word order — a
@@ -1248,6 +1265,34 @@ function aiIdentityMatch(raw) {
   return splitClauses(text).some((clause) => AI_IDENTITY_PHRASES.some((re) => re.test(clause)));
 }
 
+/** The self-referential tail a casual identity question trails after a comma
+ *  ("what even is this thing, like what does it do?"). It names no term at all
+ *  — "it"/"this"/"you" is the thing already asked about in the first clause —
+ *  so it adds nothing to answer and only has to be RECOGNIZED, not routed. */
+const SELF_REFERENTIAL_TAIL_RE = /^(?:like\s+|so\s+|and\s+)?what (?:does|do|can) (?:it|this|you|u) do\??$/i;
+
+/** IDENTITY_PHRASES matched against the raw turn, its preamble-peeled twin, or
+ *  a comma-joined identity clause trailed only by self-referential filler.
+ *
+ *  The peeled check mirrors what CAPABILITY_PHRASES' own dispatch already does
+ *  ("hello there, what am I talking to?" is an exact identity question behind a
+ *  greeting frame, and every entry is anchored, so the frame alone sank it).
+ *
+ *  The clause check is deliberately narrower than aiIdentityMatch's: it splits
+ *  on commas/"and" (conversationalClauses), which a real graph question can sit
+ *  on the far side of, so a match requires the FIRST clause to be an identity
+ *  question AND every later clause to be self-referential filler. "what is
+ *  this, and which modules import walk.mjs" therefore stays a graph query. */
+function identityPhraseMatch(raw) {
+  const text = String(raw);
+  const anchored = (s) => IDENTITY_PHRASES.some((re) => re.test(s));
+  if (anchored(text) || anchored(applyPreambleFrames(text))) return true;
+  const clauses = conversationalClauses(applyPreambleFrames(text).trim());
+  if (clauses.length < 2) return false;
+  return anchored(clauses[0].replace(/[?.!]+$/, ""))
+    && clauses.slice(1).every((c) => SELF_REFERENTIAL_TAIL_RE.test(c));
+}
+
 /** "Do you have feelings/emotions" — with no closed-set match, this would
  *  otherwise misfire into a literal module-name lookup for the bare noun
  *  ("no module matching 'feelings' found in the index") — a wrong-flavor
@@ -2009,7 +2054,7 @@ function conversationalTurn(line, ctx) {
       { lane: "help" },
     );
   }
-  if (IDENTITY_PHRASES.some((re) => re.test(raw))) {
+  if (identityPhraseMatch(raw)) {
     note(ctx.trace, "goal: identity — who/what tmct is, not a capability listing");
     note(ctx.trace, "lane: conversational — identity (IDENTITY_PHRASES closed set)");
     return mk(t(T_IDENTITY_SELF), { lane: "help" });
@@ -2126,7 +2171,12 @@ const ORIENTATION_EMPTY_FALLBACK = "I'm tmct — a deterministic, offline chat a
  *  branch uses, so there is exactly one copy of that wording to keep in sync, not
  *  two hand-duplicated strings. */
 function orientationText(graph, templates, vocabHint) {
-  if (noCodeGraph(graph)) {
+  // A null (never-loaded) graph reads as "unknown, not empty" to noCodeGraph,
+  // which is the right call for the greeting/orientation CARD — but there is no
+  // entity count to render from one either, so the empty wording is the only
+  // truthful thing left to say. Without this the entity tally below threw on a
+  // graph-less runTurn.
+  if (!graph || noCodeGraph(graph)) {
     return tRender(templates, T_ORIENTATION_EMPTY, { vocabHint }) ?? ORIENTATION_EMPTY_FALLBACK;
   }
   const by = (cls) => (graph.individuals || []).filter((i) => (i.class || "") === cls).length;
@@ -2245,7 +2295,14 @@ const TEACH_RE = /^(?:please\s+)?(?:i\s+(?:want|wanted)\s+you\s+to\s+|i(?:'d|\s+
 // stayed null) before ever trying the unknown-subject/object mint fallbacks
 // below — the SAME sentence typed without the period worked. Mirrors
 // UNKNOWN_SUBJECT_RE's own identical tolerance, added for the same reason.
-const BARE_DECLARATIVE_RE = /^(?:every |each |all |a |an )?[\w-]+(?: [\w-]+)? (?:is|are) (?:a |an )?[\w-]+(?: too)?[.!?]*$/i;
+// This is the gate that decides whether a bare declarative becomes a teach
+// payload at all, so a complement narrower than UNKNOWN_SUBJECT_RE's own object
+// capture kept a multi-word class name out of the mint fallbacks downstream no
+// matter how wide their captures were. A multi-word complement is admitted ONLY
+// behind an article — "is A unit of work" names a class, while the article-less
+// "is nice today" / "are fast animals" is ordinary prose that happens to carry a
+// copula, and admitting THAT grounds filler sentences as facts.
+const BARE_DECLARATIVE_RE = /^(?:every |each |all |a |an )?[\w-]+(?: [\w-]+)? (?:is|are) (?:(?:a |an )[\w-]+(?: [\w-]+){0,2}|[\w-]+)(?: too)?[.!?]*$/i;
 /** "X is <comparative> than Y" — the comparative teach/ask surface. The
  *  comparative slot is closed by SHAPE (-er word, better/worse, or a
  *  more/less + adjective pair), never a hand-list of adjectives. */
@@ -2842,7 +2899,11 @@ export { singularizeSurface };
  *  and unknownObjectFallback's own docblocks) — a proper noun that happens to
  *  end in "s" ("redis") naively strips to "redi" if singularized on an "is"
  *  sentence, where no such fold is ever needed.
- *  Y (the object) is a single token, same as parseAce's own copula fragments;
+ *  Y (the object) is ONE TO THREE tokens, so a natural multi-word class name
+ *  ("every Function is a unit of work") reaches the mint instead of failing
+ *  the match outright and falling to the grammar wall; the greedy quantifier
+ *  plus the end anchor keep a longer trailing phrase ("rex is a dog in the
+ *  garden") rejected exactly as before.
  *  X (the subject) is ONE OR TWO tokens, to cover a natural 2-word noun
  *  phrase ("vulcan gizmo is a tool"), the same class of gap OWNS_TEACH_RE's
  *  own object needed widening for, above. The greedy quantifier tries the
@@ -2867,7 +2928,7 @@ export { singularizeSurface };
  *  captures themselves are unaffected (`[\w-]+` never included the period in
  *  the first place), so this only widens WHICH sentences reach the match,
  *  never what gets captured out of one that already did. */
-const UNKNOWN_SUBJECT_RE = /^(every\s+|each\s+|all\s+|any\s+|a\s+|an\s+)?([\w-]+(?:\s+[\w-]+)?)\s+(is|are)\s+(?:an?\s+)?([\w-]+)[.!?]*$/i;
+const UNKNOWN_SUBJECT_RE = /^(every\s+|each\s+|all\s+|any\s+|a\s+|an\s+)?([\w-]+(?:\s+[\w-]+)?)\s+(is|are)\s+(?:an?\s+)?([\w-]+(?:\s+[\w-]+){0,2})[.!?]*$/i;
 
 /** ISA-family predicates (mirrors the private ISA_PREDICATES set defined near
  *  memoryFacts, below, at module scope — both are simple top-level consts
@@ -3124,6 +3185,12 @@ async function unknownSubjectFallback(payload, { memoryDir, sessionId, lexicon }
  *  tagging surprise, degrades to a null tag treated as "no signal" (never a
  *  decline) — matching every other optional-adapter path in this file. */
 async function objectReadsAsNonNoun(word) {
+  // A MULTI-WORD complement only ever reaches here from behind an article, so
+  // it is a noun phrase by construction and the adjective question doesn't
+  // arise. Asking wink anyway tags the joined string as one opaque token and
+  // reads back nonsense ("key value store" → ADJ), which then diverted a plain
+  // class claim into the property lane.
+  if (/\s/.test(String(word || "").trim())) return false;
   try {
     const { nlpAdapter } = await import("../adapters/ask-nlp.mjs");
     const adapter = nlpAdapter();
@@ -4766,12 +4833,18 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null, cac
     if (stored) return stored;
   }
   // PASSIVE ownership — "<X> is owned by <Name>". Same bare-form gate as the
-  // active shape just above: a Capitalized owner
-  // name AND no interrogative lead, so "is TaskController owned by anyone"
-  // (a genuine yes/no QUESTION, handled by factReadBack instead) never lands
-  // a bogus fact here.
+  // active shape just above, reading EITHER side and requiring no
+  // interrogative lead, so "is TaskController owned by anyone" (a genuine
+  // yes/no QUESTION, handled by factReadBack instead) never lands a bogus
+  // fact here. Reading both sides matters as much as it does for the active
+  // shape, and the SUBJECT side gets the path test too: "src/domain/
+  // lexicon.mjs is owned by antony" states ownership just as plainly as a
+  // capitalized owner does, while "the car is owned by john" still declines.
   const ownPassive = ownSrc.match(OWNS_PASSIVE_TEACH_RE);
-  if (ownPassive && memoryDir && !QUESTION_LEAD_RE.test(ownSrc) && !ownSrcMidQuestion && (wrapped || /^[A-Z]/.test(ownPassive[2]))) {
+  const ownPassiveSubject = ownPassive?.[1]?.trim() ?? "";
+  if (ownPassive && memoryDir && !QUESTION_LEAD_RE.test(ownSrc) && !ownSrcMidQuestion
+    && (wrapped || /^[A-Z]/.test(ownPassive[2]) || /^[A-Z]/.test(ownPassiveSubject)
+      || MODULE_PATH_RE.test(ownPassiveSubject))) {
     const stored = await teachFact(memoryDir, sessionId, {
       subject: ownPassive[1], predicate: OWNED_BY_PREDICATE, object: ownPassive[2],
     });
@@ -5469,7 +5542,7 @@ const WHAT_KNOW_RE = /^(?:what\s+(?:do\s+you|d'?you)\s+know(?:\s+so\s+far)?|what
 // do" needs the noun OPTIONAL after "this" (kept REQUIRED after "the") or it
 // falls through to MODULE_ORIENT_RE, which fails to resolve "this" as an
 // entity and hits the raw grammar wall.
-const META_ORIENT_RE = /^(?:what(?:'s| is| are)?\s+this(?:\s+(?:app|codebase|repo|repository|project|code|thing))?|what\s+(?:codebase|repo|repository|project)\s+is\s+this|what\s+does\s+this(?:\s+(?:app|code|codebase|project|repo))?\s+do|what\s+does\s+the\s+(?:app|code|codebase|project|repo)\s+do|what\s+is\s+(?:this|the)\s+app(?:\s+for)?|what\s+am\s+i\s+looking\s+at|what\s+is\s+tmct|how\s+do\s+i\s+(?:start|begin|get\s+started|get\s+going|load\s+(?:my\s+)?code|index\s+(?:my\s+)?(?:code|repo|repository)|use\s+(?:this|you|tmct))|where\s+do\s+i\s+(?:start|begin)(?:\s+reading(?:\s+(?:this\s+)?(?:codebase|code|repo|repository|project))?)?|what\s+should\s+i\s+(?:read|look\s+at)\s+first(?:\s+to\s+understand\s+(?:this\s+)?(?:codebase|code|repo|repository|project))?|where\s+should\s+i\s+start\s+reading(?:\s+(?:this\s+)?(?:codebase|code|repo|repository|project))?|where\s+do\s+i\s+begin\s+reading(?:\s+(?:this\s+)?(?:codebase|code|repo|repository|project))?)$/;
+const META_ORIENT_RE = /^(?:what(?:'s| is| are)?\s+this(?:\s+(?:app|codebase|repo|repository|project|code|thing))?|what\s+(?:codebase|repo|repository|project)\s+is\s+this|what\s+does\s+this(?:\s+(?:app|code|codebase|project|repo))?\s+do|what\s+does\s+the\s+(?:app|code|codebase|project|repo)\s+do|what\s+is\s+(?:this|the)\s+app(?:\s+for)?|what\s+am\s+i\s+looking\s+at|what\s+is\s+tmct|how\s+do\s+i\s+(?:(?:start|begin|get\s+started|get\s+going)(?:\s+(?:with|on)\s+(?:this|it))?|load\s+(?:my\s+)?code|index\s+(?:my\s+)?(?:code|repo|repository)|use\s+(?:this|you|tmct))|where\s+do\s+i\s+(?:start|begin)(?:\s+reading(?:\s+(?:this\s+)?(?:codebase|code|repo|repository|project))?)?|what\s+should\s+i\s+(?:read|look\s+at)\s+first(?:\s+to\s+understand\s+(?:this\s+)?(?:codebase|code|repo|repository|project))?|where\s+should\s+i\s+start\s+reading(?:\s+(?:this\s+)?(?:codebase|code|repo|repository|project))?|where\s+do\s+i\s+begin\s+reading(?:\s+(?:this\s+)?(?:codebase|code|repo|repository|project))?)$/;
 /** A bare "what is in here"/"what's in here"/"whats in here" — the SAME
  *  orientation intent as META_ORIENT_RE's own
  *  "what's in this repo"-shaped members, just phrased with the CONTEXT_WORDS
@@ -5517,17 +5590,19 @@ async function memorySummary(memoryDir, graph) {
 // #2(e) MODULE-GRAIN OVERVIEW. META_ORIENT_RE (above) can't match a module
 // path/symbol name, so "what does app/lib/a.mjs do" needs its own lane.
 // CASE-PRESERVING: reads the ORIGINAL query text, never metaLane's lowercased `q`.
-/** A trailing intensifier/filler adverb tacked onto "do"/"does" ("what does the
- *  store module do exactly?", "...do exactly", "what X does really") — the
- *  closed-form anchor below requires "do"/"does" to be the LAST word before
- *  the optional "?", so this one extra word past it would otherwise hit the
- *  raw grammar wall even though the shared FILLER_WORDS/normalizeQuery pass
- *  (used elsewhere in the file) never sees this lane's case-preserving text
- *  at all. Mirrors MODULE_ORIENT_POLITENESS_RE
- *  just below: closed, optional, single-lane blast radius — a bare "what does
- *  X do" still matches with this suffix empty. */
-const TRAILING_ADVERB_RE = "(?:\\s+(?:exactly|really|actually|anyway))?";
-const MODULE_ORIENT_RE = new RegExp(`^what\\s+does\\s+(.+?)\\s+do${TRAILING_ADVERB_RE}\\??$`, "i");
+/** One intensifier/filler adverb sitting either side of "do"/"does" ("what does
+ *  the store module do exactly?", "what does tasks.mjs actually do
+ *  internally", "what X does really") — the closed-form anchors below pin
+ *  "do"/"does" against the term on one side and the optional "?" on the
+ *  other, so either extra word would hit the raw grammar wall even though the
+ *  shared FILLER_WORDS/normalizeQuery pass (used elsewhere in the file) never
+ *  sees this lane's case-preserving text at all. Mirrors
+ *  MODULE_ORIENT_POLITENESS_RE just below: closed, optional, single-lane blast
+ *  radius — a bare "what does X do" still matches with both slots empty. The
+ *  PRE-verb slot also keeps an adverb out of the term capture, so
+ *  "tasks.mjs actually" never reaches entity resolution as one name. */
+const ORIENT_ADVERB_SLOT_RE = "(?:\\s+(?:exactly|really|actually|truly|anyway|internally|properly))?";
+const MODULE_ORIENT_RE = new RegExp(`^what\\s+does\\s+(.+?)${ORIENT_ADVERB_SLOT_RE}\\s+do${ORIENT_ADVERB_SLOT_RE}\\??$`, "i");
 /** The SUBJECT-FIRST word order of the SAME question ("what saveStore does" vs
  *  "what does saveStore do") — a perfectly natural alternate phrasing of an
  *  ALREADY-recognized intent that would otherwise hit the raw grammar wall
@@ -5537,7 +5612,7 @@ const MODULE_ORIENT_RE = new RegExp(`^what\\s+does\\s+(.+?)\\s+do${TRAILING_ADVE
  *  UNIQUE graph entity or this lane declines) is what keeps this loose an
  *  ending safe — a syntactic match against a term that isn't a real entity
  *  simply falls through unchanged, same as every other lane in this file. */
-const MODULE_ORIENT_SVO_RE = new RegExp(`^what\\s+(.+?)\\s+does${TRAILING_ADVERB_RE}\\??$`, "i");
+const MODULE_ORIENT_SVO_RE = new RegExp(`^what\\s+(.+?)${ORIENT_ADVERB_SLOT_RE}\\s+does${ORIENT_ADVERB_SLOT_RE}\\??$`, "i");
 /** "whats X do" / "what's X do" / "what is X do" — the CONTRACTED phrasing of
  *  "what does X do", where the auxiliary collapses into the "what's"/"whats"
  *  opener and "do" trails the term. MODULE_ORIENT_RE's own "does BEFORE the
@@ -5548,7 +5623,7 @@ const MODULE_ORIENT_SVO_RE = new RegExp(`^what\\s+(.+?)\\s+does${TRAILING_ADVERB
  *  that is not a real unique entity (a pronoun subject "whats it do", a
  *  non-word) simply declines. The "what(?:'s|s|\s+is)" opener mirrors
  *  MODULE_PURPOSE_RE's tolerance for the apostrophe-less "whats" contraction. */
-const MODULE_ORIENT_IS_DO_RE = new RegExp(`^what(?:'s|s|\\s+is)\\s+(.+?)\\s+do${TRAILING_ADVERB_RE}\\??$`, "i");
+const MODULE_ORIENT_IS_DO_RE = new RegExp(`^what(?:'s|s|\\s+is)\\s+(.+?)${ORIENT_ADVERB_SLOT_RE}\\s+do${ORIENT_ADVERB_SLOT_RE}\\??$`, "i");
 // Purpose/identity phrasing: "whats X for"/"what's X
 // about"/"what is X for", the sibling of "what does X do" that asks for the
 // SAME module-grain overview. Deliberately does NOT claim the literal noun
@@ -10927,9 +11002,24 @@ const STACCATO_PRONOUN_RE = /^(?:and|also|so|then|now)\s+(it|that|this|those|the
 const DESCRIBE_GRAIN_WORD_RE = new RegExp(
   `^(?:(?:the|a|an)\\s+)?(.+?)\\s+(${Object.keys(ENTITY_TO_TYPE).join("|")})$`, "i",
 );
+/** A LEADING noise phrase glued onto the captured term by an outer bridge, the
+ *  mirror of the trailing grain word DESCRIBE_GRAIN_WORD_RE strips. "give me
+ *  the context for src/core/store.mjs" reaches this lane as "describe context
+ *  for src/core/store.mjs" (normalize.mjs's show/give-me frame rewrites the
+ *  whole tail into the term), and every resolver downstream then reads
+ *  "context" as part of the name. Closed list, and the term still has to
+ *  resolve afterwards, so a phrase that leaves nothing resolvable simply
+ *  declines to the ordinary miss. */
+const DESCRIBE_LEADING_NOISE_RE =
+  /^(?:the\s+)?(?:context|details|detail|info|information|background)\s+(?:for|on|about|of|around)\s+/i;
+function stripDescribeLeadingNoise(term) {
+  const stripped = String(term || "").replace(DESCRIBE_LEADING_NOISE_RE, "").trim();
+  return stripped || String(term || "").trim();
+}
+
 async function describeGrainRescue(graph, term) {
   if (!graph) return null;
-  const m = String(term || "").trim().match(DESCRIBE_GRAIN_WORD_RE);
+  const m = stripDescribeLeadingNoise(term).match(DESCRIBE_GRAIN_WORD_RE);
   if (!m) return null;
   const [, head, grainWord] = m;
   const expectedClass = ENTITY_TO_TYPE[grainWord.toLowerCase()];
@@ -10959,6 +11049,11 @@ async function describeWrapperAnswer(query, { config, source, focus, graph, tel
   // "describe about X" (a doubled verb) leaves a redundant leading "about "
   // glued to the captured term.
   term = term.replace(/^about\s+/i, "");
+  // "give me the context for X" arrives bridged into "describe context for X".
+  // Cleaned once here so the grain rescue, the /describe dispatch and the
+  // focus-setting resolveEntity below all read the same clean term — the
+  // answer was already right without this, but the focus never updated.
+  term = stripDescribeLeadingNoise(term);
   // A trailing bare discourse tag ("describe Record then") glued onto the
   // captured term, same class of gap stripTrailingDiscourseTag (ask-vocab.mjs)
   // already fixes for the meta-whatis vocab lane.
@@ -14785,7 +14880,60 @@ 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, discourse = null, _noSplit = false } = {}) {
+/** Commands whose answer is SERVED SOURCE TEXT — lines read byte-for-byte off a
+ *  file on disk, which a caller may paste straight into an edit. The prose
+ *  grammar rules rewrite real code into code that no longer parses: a spread
+ *  (`...base`) and an optional chain (`?.`) both read as runs of terminal
+ *  punctuation and collapse to a single character. So the whole answer goes to
+ *  finish() as ONE protected `code` span and comes back untouched. */
+const SOURCE_RENDERING_COMMANDS = new Set(["context", "snippet"]);
+
+/** finish() a dispatched turn, byte-protecting a served-source answer. A
+ *  producer that segmented its own answer keeps its own segments; everything
+ *  else is masked and grammar-corrected exactly as before. */
+function finishTurn(result, ctx) {
+  const preSegmented = Array.isArray(result?.segments) && result.segments.length > 0;
+  if (!preSegmented && typeof result?.answer === "string"
+      && SOURCE_RENDERING_COMMANDS.has(result?.record?.command)) {
+    return finish({ ...result, segments: [{ type: "code", text: result.answer }] }, ctx);
+  }
+  return finish(result, ctx);
+}
+
+/** An uncached readFactRows() snapshot of the memory store — one half of the
+ *  before/after pair a turn's `factsTouched` diff is taken over. Deliberately
+ *  bypasses the turn's factRowsCache: the cache is invalidated by only some
+ *  write paths, and a diff read through it would miss the very writes it exists
+ *  to report. Null (rather than []) when there is no store or it won't load, so
+ *  the caller can tell "nothing to diff" from "diffed, nothing moved". */
+async function factRowSnapshot(memoryDir) {
+  if (!memoryDir) return null;
+  try { return readStoredFactRows(await loadMemoryStore(memoryDir)); } catch { return null; }
+}
+
+/** The Fact rows this turn wrote, diffed against the snapshot taken before it.
+ *  Empty when the turn had no store to write to, or wrote nothing. */
+async function factsTouchedSince(memoryDir, before) {
+  if (!before) return [];
+  const after = await factRowSnapshot(memoryDir);
+  if (!after) return [];
+  const { touchedFactRows } = await import("../domain/memory/touched-facts.mjs");
+  return touchedFactRows(before, after);
+}
+
+/** Run one turn and report which Fact rows it wrote, as `factsTouched` beside
+ *  the answer/record/logLines every caller already reads. The dispatch itself
+ *  is dispatchTurn, below; this wrapper exists so the field lands on EVERY
+ *  return path (dispatched, conversational, multi-sentence) from one place. */
+export async function runTurn(input, options = {}) {
+  const memoryDir = options?.memoryDir ?? null;
+  const before = await factRowSnapshot(memoryDir);
+  const result = await dispatchTurn(input, options);
+  if (!result || typeof result !== "object") return result;
+  return { ...result, factsTouched: await factsTouchedSince(memoryDir, before) };
+}
+
+async function dispatchTurn(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)
@@ -14863,7 +15011,7 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
   // what the shell prints. The narrate block is applied AFTER `last` is
   // captured from the PRE-narration finished result.
   const withLast = (result, fallbackGoal = "unclear — no goal signal for this turn type") => {
-    const finished = attachDialogueAct(finish(result, { graph }), trace);
+    const finished = attachDialogueAct(finishTurn(result, { graph }), trace);
     // The logged transcript echo is ALWAYS the verbatim user line — no dispatch
     // path's internal rewrite (the indirect-request wrapper, the vocab-opener /
     // cleft / ESL rewrites, a discourse substitution) may leak into what the
@@ -15154,8 +15302,11 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
         let f = focus; let l = last; let ps = planHolder.state; let d = discourseHolder.record;
         const receipts = [];
         let finalRec = null;
+        // dispatchTurn, not runTurn: the OUTER wrapper's before/after snapshot
+        // already spans every sentence, so a per-sentence diff would only pay
+        // for a narrower answer to the same question.
         for (const sentence of sentences) {
-          const r = await runTurn(sentence, {
+          const r = await dispatchTurn(sentence, {
             config, source, graph, focus: f, last: l, memoryDir, sessionId, env, lexicon,
             narrate: false, vocabHint, tel, biasByBundle, planState: ps, discourse: d, _noSplit: true,
           });

package/src/services/code-explorer-viz.mjs

@@ -354,6 +354,9 @@ export function renderCodeExplorerHtml(data, { bundleInline = "", bundleAvailabl
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>tmct code explorer</title>
+<link rel="icon" href="./favicon.svg" type="image/svg+xml">
+<link rel="icon" href="./favicon.ico" sizes="any">
+<link rel="apple-touch-icon" href="./apple-touch-icon.png">
 <style>
 ${THEME_TOKENS_CSS}
 * { box-sizing: border-box; }

package/src/services/finish.mjs

@@ -20,7 +20,12 @@ const GRAMMAR_DIR = dirname(fileURLToPath(import.meta.url));
 /** The data-driven grammar-rule table. */
 const GRAMMAR_RULES_FILE = join(GRAMMAR_DIR, "..", "..", "data", "templates", "grammar-rules.toml");
 
-/** The segment type vocabulary. `prose` is the only unprotected type. */
+/** The segment type vocabulary. `prose` is the only unprotected type.
+ *
+ *  `code` is the one type maskSegments never infers: no regex tells source text
+ *  from prose reliably enough to be trusted with a caller's edit. A producer
+ *  that KNOWS it is serving source (chat's /snippet and /context) says so by
+ *  handing finish() its own `code` span, and gets its bytes back exactly. */
 export const SEGMENT_TYPES = Object.freeze([
   "prose", "entity", "path", "number", "code", "provenance", "receipt",
 ]);

package/src/services/ingest-viz.mjs

@@ -76,6 +76,9 @@ export function renderIngestHtml({ title = DEFAULT_TITLE } = {}) {
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${escapeHtml(title)}</title>
+<link rel="icon" href="./favicon.svg" type="image/svg+xml">
+<link rel="icon" href="./favicon.ico" sizes="any">
+<link rel="apple-touch-icon" href="./apple-touch-icon.png">
 <!--
   The wink lemma/POS tier loads from ./vendor/wink.js — the site's own shared
   first-party bundle (built by scripts/build-wink-vendor.mjs), one cached copy

package/src/services/ledger-viz.mjs

@@ -570,6 +570,9 @@ export function renderLedgerHtml({ rows, terms, edges, focus, contradictions, wo
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${escapeHtml(title)}</title>
+<link rel="icon" href="./favicon.svg" type="image/svg+xml">
+<link rel="icon" href="./favicon.ico" sizes="any">
+<link rel="apple-touch-icon" href="./apple-touch-icon.png">
 <!--
   The wink lemma/POS tier loads from ./vendor/wink.js — the site's own shared
   first-party bundle of wink-nlp + wink-eng-lite-web-model (built by

package/src/services/plan-viz.mjs

@@ -293,6 +293,9 @@ export function renderPlanHtml({ plan, rendersAs = {}, sizeOrder = [], title } =
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${escapeHtml(pageTitle)}</title>
+<link rel="icon" href="./favicon.svg" type="image/svg+xml">
+<link rel="icon" href="./favicon.ico" sizes="any">
+<link rel="apple-touch-icon" href="./apple-touch-icon.png">
 <!--
   The wink lemma/POS tier loads from ./vendor/wink.js — the site's own shared
   first-party bundle of wink-nlp + wink-eng-lite-web-model (built by

package/src/services/research-viz.mjs

@@ -87,6 +87,9 @@ export function renderResearchHtml({ title = DEFAULT_TITLE, digestStructures = [
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${escapeHtml(title)}</title>
+<link rel="icon" href="./favicon.svg" type="image/svg+xml">
+<link rel="icon" href="./favicon.ico" sizes="any">
+<link rel="apple-touch-icon" href="./apple-touch-icon.png">
 <!--
   The wink lemma/POS tier loads from ./vendor/wink.js — the site's own shared
   first-party bundle (built by scripts/build-wink-vendor.mjs), one cached copy

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

@@ -225,7 +225,9 @@ export function nextCorpses(prevCorpses, prevAgents, agents, turn, lingerTurns =
  *  the engine into the page instead of the sibling `<script src>`, for the
  *  CLI's standalone export — one downloadable file that runs from file://
  *  with no sibling assets. Default empty keeps the site build's sibling-file
- *  arrangement byte-identical. */
+ *  arrangement byte-identical, favicon links included; the standalone export
+ *  drops them too, since a relative ./favicon.svg would be a dangling
+ *  external reference the "no sibling assets" export can't carry. */
 export function renderSpiderFlyHtml({ title = DEFAULT_TITLE, spriteTemplates = [], engineBundleJs = "" } = {}) {
   const gridData = embedJson({
     gridSize: GRID_SIZE,
@@ -254,6 +256,9 @@ export function renderSpiderFlyHtml({ title = DEFAULT_TITLE, spriteTemplates = [
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${escapeHtml(title)}</title>
+${engineBundleJs ? "" : `<link rel="icon" href="./favicon.svg" type="image/svg+xml">
+<link rel="icon" href="./favicon.ico" sizes="any">
+<link rel="apple-touch-icon" href="./apple-touch-icon.png">`}
 <style>
 ${THEME_TOKENS_CSS}
   :root { --fly: #A6791F; }

package/src/services/sprite-catalog-viz.mjs

@@ -464,7 +464,9 @@ function sectionHtml(group, entries) {
  *  same two template sets) and references the sibling
  *  ./sprites-browser.bundle.js scripts/build-demo-site.mjs builds alongside
  *  it. Left false, the page renders exactly as before — no dock, no bundle
- *  reference, nothing extra to 404. */
+ *  reference, nothing extra to 404 — including the favicon links, since the
+ *  CLI's standalone export (also `spritesBundleAvailable: false`) can't carry
+ *  a dangling relative ./favicon.svg either. */
 export function renderSpriteCatalogHtml({ title = DEFAULT_TITLE, iconTemplates = [], largeTemplates = [], factRows = [], spritesBundleAvailable = false } = {}) {
   const entries = buildSpriteCatalogEntries({ iconTemplates, largeTemplates, factRows });
   const totalSwatches = entries.reduce((n, e) => n + e.iconSwatches.length + e.largeSwatches.length, 0);
@@ -607,6 +609,9 @@ const SPRITE_CHAT = ${embedJson({ rows: dockRows })};
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${escapeHtml(title)}</title>
+${spritesBundleAvailable ? `<link rel="icon" href="./favicon.svg" type="image/svg+xml">
+<link rel="icon" href="./favicon.ico" sizes="any">
+<link rel="apple-touch-icon" href="./apple-touch-icon.png">` : ""}
 <style>
 ${THEME_TOKENS_CSS}
   html { background: var(--bg); }