@polycode-projects/the-mechanical-code-talker 3.1.0 → 3.1.3

package/src/services/chat.mjs

@@ -128,6 +128,8 @@ const GOAL_BY_KIND = {
   touchesSymbol: "understand commit/change history",
   cochange: "understand change-coupling between modules",
   reexports: "understand a module's public exports/API surface",
+  serves: "understand which component provides or backs another",
+  denotes: "understand which vocabulary term names a code entity",
 };
 const goalNoun = (entityType) => (entityType ? `${String(entityType).toLowerCase()}(s)` : "entities");
 
@@ -257,7 +259,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 +272,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 +1118,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 +1267,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 +2056,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 +2173,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;
@@ -2190,6 +2242,8 @@ const MISS_EXAMPLES = {
   define: ['"where is <name> defined"', '"where is <name> mentioned"'],
   meaning: ['"what is a <ClassName>"', '"what does <term> mean"'],
   count: ['"how many classes are there"', '"how many modules are there"'],
+  serve: ['"what does <name> serve"', '"what serves <name>"'],
+  denote: ['"what does <name> denote"', '"what denotes <name>"'],
 };
 const MISS_DEFAULT = ['"which modules import <name>"', '"what calls <name>"'];
 
@@ -2201,6 +2255,8 @@ function tailoredExamples(q) {
   const has = (re) => re.test(q);
   if (has(/\bimport/)) return MISS_EXAMPLES.import;
   if (has(/\bexport/)) return MISS_EXAMPLES.export;
+  if (has(/\bserv(?:e|es|ed|ing|ice)\b/)) return MISS_EXAMPLES.serve;
+  if (has(/\bdenot(?:e|es|ed|ing|ation)\b/)) return MISS_EXAMPLES.denote;
   if (has(/\b(?:calls?|caller|callee)\b/)) return MISS_EXAMPLES.call;
   if (has(/\b(?:tests?|cover|covering|tested)\b/)) return MISS_EXAMPLES.test;
   if (has(/\b(?:inherit|subclass|extends?|superclass|hierarchy|base class|parent class)\b/)) return MISS_EXAMPLES.inherit;
@@ -2245,7 +2301,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 +2905,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 +2934,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 +3191,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 +4839,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 +5548,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 +5596,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 +5618,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 +5629,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 +11008,33 @@ 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.
+ *
+ *  The "everything i need ..." branch is the same shape with a purpose clause
+ *  instead of a bare noun: "give me everything i need to change X"/"...for X"
+ *  both reach here as "describe everything i need to change X"/"describe
+ *  everything i need for X". The "to <verb...>" purpose clause is never split
+ *  word-by-word (a multi-word clause like "to work on X" would mis-split into
+ *  a captured verb plus a dangling remainder) — the greedy `.*\s` instead
+ *  always backtracks to the LAST whitespace run in the match, so the whole
+ *  clause strips as one unit and only the trailing symbol/path survives. */
+const DESCRIBE_LEADING_NOISE_RE =
+  /^(?:(?:the\s+)?(?:context|details|detail|info|information|background)\s+(?:for|on|about|of|around)\s+|everything\s+i(?:'d|\s+would)?\s+need\s+(?:to\s+.*\s|for\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 +11064,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.
@@ -13260,6 +13370,15 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     const described = await describeWrapperAnswer(query, { config, source, focus: newFocus, graph, tel });
     if (described) {
       answer = described.text; via = described.miss ? "miss" : "describe"; recordMiss = !!described.miss;
+      // The composed engine's failed parse above (`via` was still "composed"
+      // to reach this lane at all) can have deduced a goal/canonical for a
+      // DIFFERENT reading it never resolved — e.g. "give me everything i need
+      // to change X" bag-of-words-matches "change" as a touches verb and
+      // deduces subject="describe everything i need". This rescue answers a
+      // different question, so that stale interpretation must not survive
+      // into its answer (same staleness the FUZZY-VERB DECLINE lane guards
+      // against, below).
+      canonical = null; deduced = null;
       note(trace, "lane: (4d) DESCRIBE-WRAPPER RESCUE — a polite wrapper around \"describe/tell me about <symbol>\" resolved via /describe, tried last after every other lane declined");
       note(trace, "goal: get a symbol's definition/kind/relations (phrased conversationally)");
       // Carry the resolved entity forward as the new focus, same class-gated
@@ -14785,7 +14904,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 +15035,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 +15326,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/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",
 ]);