@polycode-projects/the-mechanical-code-talker 1.9.0 → 1.9.2

package/README.md

@@ -392,21 +392,6 @@ once automatically after seeding and on demand; the entailed facts are
 **low-trust and retractable** (never outranking a stated fact) and this never runs
 on the chat's hot path.
 
-## What tmct deliberately is NOT
-
-- **It is not an indexer.** tmct keeps no codebase index of its own. It
-  consumes a graph via a provider seam (`fetchEntities` and friends) — building
-  that graph is a different tool's job. tmct's job is the *conversation*.
-- **It is not a reasoning model.** Where it "reasons", it does so by
-  *calculation* surfaced as prose ("there are a lot of tests for a codebase of
-  that size"). It is deterministic, explainable, and cheap. Even its forward-chaining
-  entailment (`tmct syllogise`) is mechanical OWL rule materialization applied
-  offline, rule-by-rule and retractable, not an LLM. There is **no LLM anywhere
-  in the product**. (An LLM-as-judge exists only in the offline eval harness
-  that tunes tmct, see `SKILL_BENCHMARK_CEFR_ENGLISH.md`, never in the product path.)
-- **It never guesses silently.** When it cannot resolve your question it says
-  so and nudges you toward a query it *can* answer.
-
 ## Install & use
 
 ```bash

package/corpus/seon/README.md

@@ -111,8 +111,7 @@ This directory is **data only**; wiring it into seeding is the coordinator's
    the seon tier the ordering only affects the ConceptNet tail.
 3. **Provenance caveat:** `toFacts` currently hard-codes the provenance string
    `corpus:conceptnet <rel>`. If the coordinator wants seon facts tagged as their own
-   source (`corpus:seon`), that is a one-line parametrisation of `toFacts` /
-   `seedMemory` — out of scope for this data-only directory.
+   source (`corpus:seon`), that is a one-line parametrisation of `toFacts`
 
 ## Regenerating / extending
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",
@@ -88,6 +88,8 @@
     "init:persona:human": "node bin/tmct.mjs init --with-persona human",
     "init:persona:empty": "node bin/tmct.mjs init --with-persona empty",
     "init:large": "node bin/tmct.mjs init && node bin/tmct.mjs import --corpus seon && node bin/tmct.mjs import --corpus conceptnet && node bin/tmct.mjs import --corpus aws && node bin/tmct.mjs import --corpus python && node bin/tmct.mjs import --corpus java",
+    "init:xl": "node bin/tmct.mjs init --persona-size large && node bin/tmct.mjs import --corpus seon && node bin/tmct.mjs import --corpus conceptnet && node bin/tmct.mjs import --corpus aws && node bin/tmct.mjs import --corpus python && node bin/tmct.mjs import --corpus java && node bin/tmct.mjs import --corpus wordnet-xl",
+    "init:xxl": "node bin/tmct.mjs init --persona-size large && node bin/tmct.mjs import --corpus seon && node bin/tmct.mjs import --corpus conceptnet && node bin/tmct.mjs import --corpus aws && node bin/tmct.mjs import --corpus python && node bin/tmct.mjs import --corpus java && node bin/tmct.mjs import --corpus wordnet-full && node bin/tmct.mjs import --corpus namenet",
     "memory": "node bin/tmct.mjs memory",
     "syllogise": "node bin/tmct.mjs syllogise",
     "viz": "node bin/tmct.mjs viz",

package/src/chat.mjs

@@ -677,7 +677,7 @@ async function answerEdgeCount(graph, query) {
  *  Consulted only when answerCount can't map the noun to a graph class (an unknown
  *  kind) AND a session's memory is in hand. Returns the count string or null (no
  *  such fact → the honest "I can't count …" from answerCount stands). */
-async function countFromFacts(graph, memoryDir, query, biasByBundle = {}) {
+async function countFromFacts(graph, memoryDir, query, biasByBundle = {}, cache = null) {
   if (!graph || !memoryDir) return null;
   const m = String(query).match(/\b(?:how many|number of|count(?:\s+the)?)\s+([a-z]+)\b/i);
   if (!m) return null;
@@ -686,7 +686,7 @@ async function countFromFacts(graph, memoryDir, query, biasByBundle = {}) {
   let normFactTerm;
   try { ({ normFactTerm } = await import("./memory/core.mjs")); } catch { return null; }
   const objVariants = factTermVariants(normFactTerm, asked);
-  const isa = (await factRows(memoryDir))
+  const isa = (await factRows(memoryDir, cache))
     .filter((f) => ISA_PREDICATES.has(f.predicate) && objVariants.has(f.object));
   // pick the highest-bias, then highest-trust asserted subject that maps to a
   // countable graph class (rankByBiasThenTrust: bias-tied/unconfigured degrades
@@ -721,7 +721,7 @@ async function countFromFacts(graph, memoryDir, query, biasByBundle = {}) {
 // graph-cardinality count untouched — same honest-decline discipline as
 // every other lane here).
 const HOW_MANY_ARE_RE = /^how\s+many\s+([\w-]+)\s+(?:are|is)\s+(.+?)[?.!\s]*$/i;
-async function answerQuantifierRecall(memoryDir, query, biasByBundle = {}) {
+async function answerQuantifierRecall(memoryDir, query, biasByBundle = {}, cache = null) {
   if (!memoryDir) return null;
   const m = String(query).trim().match(HOW_MANY_ARE_RE);
   if (!m) return null;
@@ -730,7 +730,7 @@ async function answerQuantifierRecall(memoryDir, query, biasByBundle = {}) {
   let normFactTerm;
   try { ({ normFactTerm } = await import("./memory/core.mjs")); } catch { return null; }
   const subjVariants = factTermVariants(normFactTerm, asked);
-  const rows = (await factRows(memoryDir)).filter((f) => ISA_PREDICATES.has(f.predicate) && subjVariants.has(f.subject));
+  const rows = (await factRows(memoryDir, cache)).filter((f) => ISA_PREDICATES.has(f.predicate) && subjVariants.has(f.subject));
   if (!rows.length) return null; // never heard of this subject at all — let answerCount own the shape
   const objVariants = factTermVariants(normFactTerm, m[2]);
   const hit = rankByBiasThenTrust(rows.filter((f) => objVariants.has(f.object)), biasByBundle)[0];
@@ -2067,7 +2067,7 @@ const GENERIC_ANCHOR_NOUNS = new Set(["thing", "concept", "object", "entity"]);
  *  fact-grounded term matches under the EXACT spelling teachFact itself stored
  *  it under. Failure-tolerated: no memory dir / no match → false, never a
  *  guessed "yes". */
-async function isGroundedByFact(term, memoryDir) {
+async function isGroundedByFact(term, memoryDir, cache = null) {
   if (!memoryDir) return false;
   const raw = String(term ?? "").trim();
   if (!raw) return false;
@@ -2083,7 +2083,7 @@ async function isGroundedByFact(term, memoryDir) {
   // OPERATOR actually taught (or a prior `tmct syllogise` entailment) anchors
   // a term here. factRows (not memoryFacts) is used specifically because it's
   // the one read path that carries sourceTypes for this filter.
-  const rows = await factRows(memoryDir);
+  const rows = await factRows(memoryDir, cache);
   const isTaught = (f) => !f.sourceTypes?.includes("corpus") && !f.sourceTypes?.includes("web");
   return rows.some((f) => MINT_ISA_PREDICATES.has(f.predicate) && isTaught(f) && (f.subject === t || f.object === t));
 }
@@ -2098,13 +2098,13 @@ async function isGroundedByFact(term, memoryDir) {
  *  narrower and NOUN-specific — see its own comment — so an object that's
  *  merely a known ADJECTIVE doesn't get misrouted into the class/subClassOf
  *  branch instead of the property branch.) */
-async function isGroundedTerm(term, lex, memoryDir) {
+async function isGroundedTerm(term, lex, memoryDir, cache = null) {
   const raw = String(term ?? "").trim();
   if (!raw) return false;
   if (GENERIC_ANCHOR_NOUNS.has(raw.toLowerCase())) return true;
   const { classify } = await import("./grammar/lexicon.mjs");
   if (classify(raw, lex)) return true;
-  return isGroundedByFact(raw, memoryDir);
+  return isGroundedByFact(raw, memoryDir, cache);
 }
 
 /** The "both sides ungrounded" grounding NUDGE (operator refinement,
@@ -2127,15 +2127,15 @@ async function isGroundedTerm(term, lex, memoryDir) {
  *  unchanged) whenever the payload doesn't fit the shape, or at least one
  *  side IS already grounded — a DIFFERENT, more specific reason it declined,
  *  where this nudge would be actively unhelpful noise. */
-async function ungroundedPairHint(payload, lexicon, memoryDir) {
+async function ungroundedPairHint(payload, lexicon, memoryDir, cache = null) {
   if (!memoryDir) return "";
   const m = String(payload).trim().match(UNKNOWN_SUBJECT_RE);
   if (!m) return "";
   const [, , subjectRaw, , objectRaw] = m;
   const { loadLexicon } = await import("./grammar/lexicon.mjs");
   const lex = lexicon || loadLexicon();
-  if (await isGroundedTerm(subjectRaw, lex, memoryDir)) return "";
-  if (await isGroundedTerm(objectRaw, lex, memoryDir)) return "";
+  if (await isGroundedTerm(subjectRaw, lex, memoryDir, cache)) return "";
+  if (await isGroundedTerm(objectRaw, lex, memoryDir, cache)) return "";
   // 2026-07-10 (found live via SKILL_BENCHMARK_CONVERSATION.md playtest, a
   // classic first-thing-a-user-tries example: "john is a man"): the original
   // suggestion chained the second term UNDER the first's now-grounded proper
@@ -2179,7 +2179,7 @@ async function ungroundedPairHint(payload, lexicon, memoryDir) {
  *  the SUBJECT, not about the "remember that" wrapper). Only the "every"
  *  determiner records a quantifier (point 3: "a"/bare/"your" read as one
  *  specific entity, not a class-level generalization). */
-async function unknownSubjectFallback(payload, { memoryDir, sessionId, lexicon }) {
+async function unknownSubjectFallback(payload, { memoryDir, sessionId, lexicon }, cache = null) {
   if (!memoryDir) return null;
   const m = String(payload).trim().match(UNKNOWN_SUBJECT_RE);
   if (!m) return null;
@@ -2211,7 +2211,7 @@ async function unknownSubjectFallback(payload, { memoryDir, sessionId, lexicon }
   // lexicon noun — both are always treated as class-level (never property),
   // consistent with unknownObjectFallback (below) always minting a CLASS.
   if (lookupNoun(lex, objectRaw) || GENERIC_ANCHOR_NOUNS.has(String(objectRaw).toLowerCase())
-    || (await isGroundedByFact(objectRaw, memoryDir))) {
+    || (await isGroundedByFact(objectRaw, memoryDir, cache))) {
     return teachFact(memoryDir, sessionId, {
       subject, predicate: SUBCLASS_PREDICATE, object: objectRaw, quantifier,
     });
@@ -2297,7 +2297,7 @@ async function objectReadsAsNonNoun(word) {
     return false;
   }
 }
-async function unknownObjectFallback(payload, { memoryDir, sessionId, lexicon }) {
+async function unknownObjectFallback(payload, { memoryDir, sessionId, lexicon }, cache = null) {
   if (!memoryDir) return null;
   const m = String(payload).trim().match(UNKNOWN_SUBJECT_RE);
   if (!m) return null;
@@ -2305,9 +2305,9 @@ async function unknownObjectFallback(payload, { memoryDir, sessionId, lexicon })
   if (!/^(?:every|each|all)$/i.test((det || "").trim())) return null; // class-level mint needs a real universal quantifier
   const { loadLexicon, lookupNoun } = await import("./grammar/lexicon.mjs");
   const lex = lexicon || loadLexicon();
-  const subjectGrounded = await isGroundedTerm(subjectRaw, lex, memoryDir);
+  const subjectGrounded = await isGroundedTerm(subjectRaw, lex, memoryDir, cache);
   if (!subjectGrounded) return null; // ungrounded subject isn't this fallback's asymmetry — never a guessed mint
-  const objectGrounded = await isGroundedTerm(objectRaw, lex, memoryDir);
+  const objectGrounded = await isGroundedTerm(objectRaw, lex, memoryDir, cache);
   if (objectGrounded) return null; // object already known — nothing to mint
   if (await objectReadsAsNonNoun(objectRaw)) return null; // reads like an adjective/verb, not a class noun — defer to unknownAdjectiveFallback
   const quantifier = /^every$/i.test((det || "").trim()) ? "every" : "";
@@ -2377,9 +2377,7 @@ async function unknownObjectFallback(payload, { memoryDir, sessionId, lexicon })
  *  Sits strictly UPSTREAM of the pre-existing TEACH_PROPERTY_RE gap (the
  *  wrapped-only surface that mints ANY bare complement word with zero
  *  grounding check at all, e.g. "remember that zorp is florpy" —
- *  Verification finding 3, PLAN_TAUGHT_RELATIONS.md): this fallback does not
- *  close that gap (out of scope, a deliberate separate operator decision),
- *  only adds a properly-grounded alternative ahead of it.
+ *  Verification finding 3, PLAN_TAUGHT_RELATIONS.md): .
  *
  *  IMPLEMENTATION ADJUSTMENT found live (not in the original plan text): a
  *  bare "module is banana" (a KNOWN lexicon-noun subject, NO article, NO
@@ -2399,7 +2397,7 @@ async function unknownObjectFallback(payload, { memoryDir, sessionId, lexicon })
  *  otherwise provide. "the cache is bespoke" and "Mary is female" both carry
  *  one of those signals (the leading "the", and capitalization,
  *  respectively); "module is banana" carries none. */
-async function unknownAdjectiveFallback(payload, { memoryDir, sessionId, lexicon }) {
+async function unknownAdjectiveFallback(payload, { memoryDir, sessionId, lexicon }, cache = null) {
   if (!memoryDir) return null;
   const m = String(payload).trim().match(UNKNOWN_SUBJECT_RE);
   if (!m) return null;
@@ -2410,7 +2408,7 @@ async function unknownAdjectiveFallback(payload, { memoryDir, sessionId, lexicon
   // membership sentence, unknownSubjectFallback/unknownObjectFallback's own
   // territory (already had first refusal on it) — never misread as a property.
   if (lookupNoun(lex, objectRaw) || GENERIC_ANCHOR_NOUNS.has(String(objectRaw).toLowerCase())
-    || (await isGroundedByFact(objectRaw, memoryDir))) return null;
+    || (await isGroundedByFact(objectRaw, memoryDir, cache))) return null;
   // Subject-side groundedness — strip a leading "the"/"a"/"an" first
   // (normFactTerm's own article-strip, mirrored here) so "the cache" checks
   // groundedness under its real head noun "cache", the same spelling
@@ -2418,7 +2416,7 @@ async function unknownAdjectiveFallback(payload, { memoryDir, sessionId, lexicon
   const bareSubject = subjectRaw.replace(/^(?:the|an?)\s+/i, "").trim() || subjectRaw;
   const hadArticle = bareSubject !== subjectRaw;
   const capitalized = /^[A-Z]/.test(bareSubject);
-  const factGrounded = await isGroundedByFact(bareSubject, memoryDir);
+  const factGrounded = await isGroundedByFact(bareSubject, memoryDir, cache);
   const genericAnchor = GENERIC_ANCHOR_NOUNS.has(bareSubject.toLowerCase());
   // A bare (no article, no capitalization) subject grounded ONLY via the
   // static lexicon is exactly the pinned "module is banana" shape — see this
@@ -2745,7 +2743,7 @@ const RETRACT_NOT_A_RE = /^(?:a\s+|an\s+)?([\w-]+(?:\s+[\w-]+)?)\s+(?:(?:is|are)
  *  is tried against the remember-wrapped surface too. */
 const RETRACT_FORGET_RE = /^forget\s+(?:that\s+)?(?:a\s+|an\s+)?([\w-]+(?:\s+[\w-]+)?)\s+(?:is|are)\s+(?:an?\s+)?(?:(?:kind|type)\s+of\s+)?([\w-]+)$/i;
 
-async function teachLane(query, { memoryDir, sessionId = "", lexicon = null }) {
+async function teachLane(query, { memoryDir, sessionId = "", lexicon = null, cache = null }) {
   // Tier 6 playtest: this lane read the raw, un-normalized query, so a closed
   // discourse-marker preamble ahead of a teach sentence ("howdy pardner,
   // remember that TaskController is fragile") corrupted TEACH_RE's own match —
@@ -3174,7 +3172,7 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null }) {
       // assertTurn ITSELF records the "every" quantifier (point 3) on a plain
       // universal success, so every caller (this loop AND the top-level
       // declarative-sentence dispatch in runTurn) gets it uniformly.
-      const stored = await assertTurn(cand, { memoryDir, sessionId, focus: null, lexicon });
+      const stored = await assertTurn(cand, { memoryDir, sessionId, focus: null, lexicon, cache });
       if (stored) return { text: stored.answer, via: "assert", miss: false };
     }
     // BUG "redis" fix (Feature A point 1): the real ACE grammar just declined
@@ -3183,7 +3181,7 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null }) {
     // Covers BOTH the bare and the wrapped surface (payload is already
     // unwrapped either way) — see unknownSubjectFallback's own docblock for
     // the exact narrowing rules (object must still be known, etc.).
-    const fallback = await unknownSubjectFallback(payload, { memoryDir, sessionId, lexicon });
+    const fallback = await unknownSubjectFallback(payload, { memoryDir, sessionId, lexicon }, cache);
     if (fallback) return fallback;
     // MIRROR mint fallback (Feature A, 2026-07-09 operator-authorized vocabulary-
     // growth extension): the known-subject/unknown-object asymmetry — tried
@@ -3191,7 +3189,7 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null }) {
     // lexicon (or a prior taught fact) already grounds can mint a brand-new
     // object term. See unknownObjectFallback's own docblock for the exact
     // narrowing rules (the "both sides ungrounded" safety guard, etc.).
-    const objectFallback = await unknownObjectFallback(payload, { memoryDir, sessionId, lexicon });
+    const objectFallback = await unknownObjectFallback(payload, { memoryDir, sessionId, lexicon }, cache);
     if (objectFallback) return objectFallback;
     // ADJECTIVE-MINT fallback (PLAN_TAUGHT_RELATIONS.md Item 5, Phase 1): tried
     // right after unknownObjectFallback declines, so a grounded subject (static
@@ -3200,7 +3198,7 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null }) {
     // docblock for the exact narrowing rules (the "both sides ungrounded"
     // safety guard, and why this must be a standalone function rather than
     // nested inside unknownSubjectFallback).
-    const adjectiveFallback = await unknownAdjectiveFallback(payload, { memoryDir, sessionId, lexicon });
+    const adjectiveFallback = await unknownAdjectiveFallback(payload, { memoryDir, sessionId, lexicon }, cache);
     if (adjectiveFallback) return adjectiveFallback;
     // PROPERTY teach — "remember/note that <X> is <adjective>": wrapper-REQUIRED
     // (a bare "X is deprecated" is never silently reified), and only after the
@@ -3271,7 +3269,7 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null }) {
   // replacement, exactly like "did" above — see ungroundedPairHint's own
   // docblock for why this is scoped to the "both sides ungrounded, fits the
   // X is/are Y shape" case only.
-  const groundingHint = await ungroundedPairHint(payload, lexicon, memoryDir);
+  const groundingHint = await ungroundedPairHint(payload, lexicon, memoryDir, cache);
   return {
     text: `I couldn't store that —${why} I remember facts in the shape "every X is a Y", where X and Y are `
       + `words I know.${did}${groundingHint} Type /memory to see what I already remember.`,
@@ -4205,11 +4203,27 @@ async function memoryFacts(memoryDir) {
 /** Load memory once and resolve every reified Fact into a TRUST-BEARING row
  *  ({subject,predicate,object,provenance,trust,sourceTypes,…}) via core's
  *  readFactRows — the seam the answer layer ranks + cites without re-walking the
- *  graph shape (Wave-A memory/core.mjs). Lazy + failure-tolerated: no memory → []. */
-async function factRows(memoryDir) {
+ *  graph shape (Wave-A memory/core.mjs). Lazy + failure-tolerated: no memory → [].
+ *
+ *  `cache` (PLAN_GRAPH_SCAN.md "Query side: memoize the per-turn reload"): an
+ *  optional, caller-owned plain object (`{ rows: null }`, e.g. one runTurn call's
+ *  own `factRowsCache`) — when `cache.rows` is already populated, it's returned
+ *  directly, skipping loadMemory/readFactRows entirely; otherwise the result is
+ *  computed as before and stashed onto `cache.rows` for the next caller sharing
+ *  the same cache this turn. Absent/null (the default) reproduces today's
+ *  behavior exactly — a fresh, uncached reload every call — so every caller that
+ *  doesn't pass one is byte-for-byte unaffected. Never shared across turns or
+ *  with mutateMemory (see the plan doc for why a global cache was rejected).
+ *  `cache.reloads` is bumped once per REAL loadMemory/readFactRows call (never on
+ *  a cache hit) purely so a test can assert "computed once per turn" by call
+ *  count instead of wall-clock — see test/chat-factrows-cache.test.mjs. */
+async function factRows(memoryDir, cache = null) {
+  if (cache?.rows) return cache.rows;
   try {
     const { loadMemory, readFactRows } = await import("./memory/core.mjs");
-    return readFactRows(await loadMemory(memoryDir));
+    const rows = readFactRows(await loadMemory(memoryDir));
+    if (cache) { cache.rows = rows; cache.reloads = (cache.reloads || 0) + 1; }
+    return rows;
   } catch {
     return [];
   }
@@ -4612,7 +4626,7 @@ function uniqueFacts(rows) {
  *  returns the handle's `payload` directly with ZERO fs calls — so a caller
  *  that hands this a handle already carrying the embedded page's full graph
  *  gets a pure, disk-free traversal, no bundle-time module shimming needed. */
-export async function factAnswer(memoryDir, query, envelope, miss, biasByBundle = {}) {
+export async function factAnswer(memoryDir, query, envelope, miss, biasByBundle = {}, cache = null) {
   let normFactTerm;
   try { ({ normFactTerm } = await import("./memory/core.mjs")); } catch { return null; }
   const q = String(query).trim();
@@ -4632,7 +4646,7 @@ export async function factAnswer(memoryDir, query, envelope, miss, biasByBundle
   const usedForQ = q.match(WHAT_USED_FOR_RE);
   if (usedForQ) {
     const variants = factTermVariants(normFactTerm, usedForQ[1]);
-    const hits = (await factRows(memoryDir)).filter((f) => f.predicate === "mgx:usedFor" && variants.has(f.object));
+    const hits = (await factRows(memoryDir, cache)).filter((f) => f.predicate === "mgx:usedFor" && variants.has(f.object));
     if (hits.length) {
       const ranked = rankByBiasThenTrust(uniqueFacts(hits), biasByBundle);
       const lines = ranked.map(renderFactLine);
@@ -4653,7 +4667,7 @@ export async function factAnswer(memoryDir, query, envelope, miss, biasByBundle
     const m = q.match(re);
     if (!m) continue;
     const variants = factTermVariants(normFactTerm, m[1]);
-    const hits = (await factRows(memoryDir)).filter((f) => f.predicate === predicate && variants.has(f.object));
+    const hits = (await factRows(memoryDir, cache)).filter((f) => f.predicate === predicate && variants.has(f.object));
     if (!hits.length) continue; // try the next candidate marker, don't give up yet
     const ranked = rankByBiasThenTrust(uniqueFacts(hits), biasByBundle);
     const lines = ranked.map(renderFactLine);
@@ -4703,7 +4717,7 @@ export async function factAnswer(memoryDir, query, envelope, miss, biasByBundle
     // factRows (trust+sourceIds-bearing), not the plain memoryFacts shape — the
     // bias-weighted ranking below needs each hit's sourceIds to resolve which
     // bundle it came from (memory/bias.mjs's biasForRow).
-    const subjectHits = (await factRows(memoryDir)).filter((f) => variants.has(f.subject));
+    const subjectHits = (await factRows(memoryDir, cache)).filter((f) => variants.has(f.subject));
     let hits = predicate ? subjectHits.filter((f) => f.predicate === predicate) : subjectHits;
     if (!hits.length) {
       // The subject itself is known, but not under this specific relation —
@@ -4763,7 +4777,7 @@ export async function factAnswer(memoryDir, query, envelope, miss, biasByBundle
   const canDo = q.match(WHAT_CAN_DO_RE);
   if (canDo) {
     const variants = factTermVariants(normFactTerm, canDo[1]);
-    const hits = (await factRows(memoryDir)).filter((f) => f.predicate === "mgx:capableOf" && variants.has(f.subject));
+    const hits = (await factRows(memoryDir, cache)).filter((f) => f.predicate === "mgx:capableOf" && variants.has(f.subject));
     if (!hits.length) return null;
     const ranked = rankByBiasThenTrust(uniqueFacts(hits), biasByBundle);
     const lines = ranked.map(renderFactLine);
@@ -4782,7 +4796,7 @@ export async function factAnswer(memoryDir, query, envelope, miss, biasByBundle
   const hasQ = q.match(WHAT_HAS_RE);
   if (hasQ && !HAS_TEMPORAL_TAIL.has(hasQ[1].trim().split(/\s+/)[0]?.toLowerCase())) {
     const variants = factTermVariants(normFactTerm, hasQ[1]);
-    const hits = (await factRows(memoryDir)).filter((f) => f.predicate === "mgx:hasA" && variants.has(f.object));
+    const hits = (await factRows(memoryDir, cache)).filter((f) => f.predicate === "mgx:hasA" && variants.has(f.object));
     if (!hits.length) return null;
     const ranked = rankByBiasThenTrust(uniqueFacts(hits), biasByBundle);
     const lines = ranked.map(renderFactLine);
@@ -4819,7 +4833,7 @@ export async function factAnswer(memoryDir, query, envelope, miss, biasByBundle
     : inheritsQ?.[1];
   if (inheritsObj) {
     const variants = factTermVariants(normFactTerm, inheritsObj);
-    const hits = (await factRows(memoryDir)).filter((f) => ISA_PREDICATES.has(f.predicate) && variants.has(f.object));
+    const hits = (await factRows(memoryDir, cache)).filter((f) => ISA_PREDICATES.has(f.predicate) && variants.has(f.object));
     // Only diverts on a REAL hit — same discipline every other reader in this
     // cascade follows (CAN_ASK_RE/WHAT_CAN_DO_RE/WHAT_HAS_RE above all `return
     // null` on zero hits too). A zero-hit case here must NOT invent its own
@@ -4847,7 +4861,7 @@ export async function factAnswer(memoryDir, query, envelope, miss, biasByBundle
   const know = q.match(KNOW_ABOUT_RE);
   if (know) {
     const variants = factTermVariants(normFactTerm, know[1]);
-    const rows = await factRows(memoryDir);
+    const rows = await factRows(memoryDir, cache);
     // Bug E subtype walk (operator follow-up request, this session): a
     // cycle-safe BFS DOWNWARD over isa-family facts from the term's own
     // variants — every fact whose OBJECT is in the current frontier
@@ -5283,7 +5297,7 @@ function inheritsChain(graph, startId) {
  *        "what kind of thing is an X" reports X's own type (subject-side first).
  *  Miss-only and run AFTER factAnswer returns null, so it never shadows the
  *  subject-side answer or a schema hit. Returns { text, replace:true } or null. */
-async function factReadBack(memoryDir, query, envelope, miss, graph = null, focusLabel = null, biasByBundle = {}) {
+async function factReadBack(memoryDir, query, envelope, miss, graph = null, focusLabel = null, biasByBundle = {}, cache = null) {
   if (!miss) return null;
   let normFactTerm;
   try { ({ normFactTerm } = await import("./memory/core.mjs")); } catch { return null; }
@@ -5330,7 +5344,7 @@ async function factReadBack(memoryDir, query, envelope, miss, graph = null, focu
   // fragile" is the SAME one-word-out-of-alignment problem the hedge adverbs
   // above were fixed for, just a dialect opener instead of a hedge adverb.
   const qHedge = q.replace(/^(?:actually|really|honestly|yeah\s+nah)\s*,?\s+/i, "");
-  const rows = await factRows(memoryDir);
+  const rows = await factRows(memoryDir, cache);
   if (!rows.length) {
     // Tier-5 playtest fix (cycle 2), found live: with TRULY zero facts
     // remembered yet (a fresh session, nothing taught at all), the early
@@ -6411,10 +6425,10 @@ async function factReadBack(memoryDir, query, envelope, miss, graph = null, focu
  *  only (a `/describe` names ONE code entity as the subject of its own facts,
  *  not every fact that merely mentions it in passing) — null when memory holds
  *  nothing about this subject. */
-async function describedFacts(memoryDir, label, biasByBundle = {}) {
+async function describedFacts(memoryDir, label, biasByBundle = {}, cache = null) {
   let normFactTerm;
   try { ({ normFactTerm } = await import("./memory/core.mjs")); } catch { return null; }
-  const rows = await factRows(memoryDir);
+  const rows = await factRows(memoryDir, cache);
   if (!rows.length) return null;
   const variants = factTermVariants(normFactTerm, label);
   const hits = rankByBiasThenTrust(rows.filter((f) => variants.has(f.subject)), biasByBundle);
@@ -7349,7 +7363,7 @@ async function relationForceAnswer(query, envelope, { graph, config, source, tem
  *  shipped corpus/seon file (seonDefinitions), so it works without per-repo memory
  *  seeding; the memory fact rows only ADD remembered "A is a X" examples when present.
  *  Lazy + failure-tolerated throughout (chat.mjs ethos). Returns { text, instances }. */
-async function conceptForceAnswer(query, envelope, { graph, config, source, memoryDir, templates }) {
+async function conceptForceAnswer(query, envelope, { graph, config, source, memoryDir, templates, cache = null }) {
   const rawTerm = conceptTermOf(query, envelope);
   if (!rawTerm) return null;
   let normFactTerm; let composeConcept; let CONCEPT_CLASS;
@@ -7369,7 +7383,7 @@ async function conceptForceAnswer(query, envelope, { graph, config, source, memo
     try { g = parseEntities(await source.fetchEntities(config)); } catch { g = null; }
   }
   if (!g) return null;
-  const rows = memoryDir ? await factRows(memoryDir) : [];
+  const rows = memoryDir ? await factRows(memoryDir, cache) : [];
   let composed;
   try { composed = composeConcept(g, term, { definition, factRows: rows }); }
   catch { return null; }
@@ -7425,7 +7439,7 @@ async function entityOfKindInText(graph, expectedClass, answerText) {
  *  otherwise the unchanged dispatchTool path (which also yields the no-graph error).
  *  A hit updates the focus to the resolved object. Grammar miss / ToolError → a
  *  normal answer, never a crash. */
-async function runAsk(query, { config, source, graph, focus, last, templates, memoryDir, sessionId = "", lexicon = null, env, trace, vocabHint = null, tel = null, biasByBundle = {} }) {
+async function runAsk(query, { config, source, graph, focus, last, templates, memoryDir, sessionId = "", lexicon = null, env, trace, vocabHint = null, tel = null, biasByBundle = {}, cache = null }) {
   const ts = new Date().toISOString();
   // DISCOURSE ANAPHORA (CHATBENCH_006 levers 1+2): a follow-up like "which of those
   // are tested" / "how many of those" / "count them" filters or counts the PREVIOUS
@@ -7949,8 +7963,8 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
   let bareMetaHit = null;
   if ((isConversationalCandidate || isBareCamelCaseWhatisCandidate) && (bareWhatisShape || isAdjectiveShape || reversePredicateShape)) {
     if (memoryDir) {
-      bareMetaHit = (await factAnswer(memoryDir, gateQuery, envelope, miss, biasByBundle))
-        ?? (await factReadBack(memoryDir, gateQuery, envelope, miss, graph, newFocus?.label, biasByBundle));
+      bareMetaHit = (await factAnswer(memoryDir, gateQuery, envelope, miss, biasByBundle, cache))
+        ?? (await factReadBack(memoryDir, gateQuery, envelope, miss, graph, newFocus?.label, biasByBundle, cache));
       // HANDOVER.md 2026-07-10 item 10 (dropped-article gap): a bare "what is X"
       // with NO taught fact but a KNOWN curated corpus term ("what is cache", no
       // article) used to lose this exact same isConversationalCandidate race —
@@ -8042,8 +8056,8 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     // reified fact is stronger evidence than a transcript echo. Subject-side facts
     // first (factAnswer), then the reverse-membership read-back (factReadBack) so an
     // asserted "every X is a Y" answers "what is a Y" too.
-    const fact = (await factAnswer(memoryDir, query, envelope, miss, biasByBundle))
-      ?? (await factReadBack(memoryDir, query, envelope, miss, graph, newFocus?.label, biasByBundle));
+    const fact = (await factAnswer(memoryDir, query, envelope, miss, biasByBundle, cache))
+      ?? (await factReadBack(memoryDir, query, envelope, miss, graph, newFocus?.label, biasByBundle, cache));
     if (fact) {
       answer = fact.replace ? fact.text : `${answer}\n${fact.text}`;
       via = "fact";
@@ -8117,7 +8131,7 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
   let conceptAllIds = null;
   let conceptPending = null;
   if (via === "composed" || via === "corpus/seon") {
-    const concept = await conceptForceAnswer(query, envelope, { graph, config, source, memoryDir, templates });
+    const concept = await conceptForceAnswer(query, envelope, { graph, config, source, memoryDir, templates, cache });
     if (concept) {
       answer = concept.text; via = "corpus/seon"; recordMiss = false;
       conceptInstances = concept.instances;
@@ -8174,7 +8188,7 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
   // (4) #2 TEACH lane — a teach-shaped would-miss nothing above answered: route to
   // memory, or say what CAN be remembered (LOUD), never the wall / a silent drop.
   if (miss && recordMiss && via === "composed") {
-    const taught = await teachLane(query, { memoryDir, sessionId, lexicon });
+    const taught = await teachLane(query, { memoryDir, sessionId, lexicon, cache });
     if (taught) {
       answer = taught.text; via = taught.via; recordMiss = taught.miss;
       note(trace, `lane: (4) TEACH — TEACH_RE/OWNS_TEACH_RE/BARE_DECLARATIVE_RE matched, ${taught.miss ? "but the payload could not be stored" : "reified into .tmct/memory"}`);
@@ -8540,7 +8554,7 @@ const GOAL_BY_COMMAND = {
  *  field now (Bug F point 5) — mirrors runAsk's own `goal` field so
  *  withGoalLine's short "Goal (inferred): …" line fires for command
  *  dispatches too, not just ask()-parsed queries. */
-async function runCommand(line, { config, source, graph, focus, memoryDir, trace, narrate = false, tel = null, biasByBundle = {} }) {
+async function runCommand(line, { config, source, graph, focus, memoryDir, trace, narrate = false, tel = null, biasByBundle = {}, cache = null }) {
   const ts = new Date().toISOString();
   const sp = line.indexOf(" ");
   const name = (sp === -1 ? line.slice(1) : line.slice(1, sp)).toLowerCase();
@@ -8651,7 +8665,7 @@ async function runCommand(line, { config, source, graph, focus, memoryDir, trace
       // matching taught facts (subject === the resolved entity, trust-ranked)
       // under the code-map answer, mirroring the ask-path's fact-append pattern.
       if (name === "describe" && memoryDir) {
-        const facts = await describedFacts(memoryDir, ent.label, biasByBundle);
+        const facts = await describedFacts(memoryDir, ent.label, biasByBundle, cache);
         if (facts) { answer = `${answer}\n${facts}`; note(trace, "source: memory facts (describedFacts) appended to the code-map answer"); }
       }
       return mk(answer, { resolvedIds: [ent.id], newFocus: nextFocus(graph, focus, ent) });
@@ -8699,7 +8713,7 @@ function renderAmbiguousAssert(line, ambiguous, normFactTerm) {
  *  relation-shaped with 0-1 surviving readings), so this adds exactly one
  *  cheap check ahead of the EXISTING, unchanged parseAce path below — every
  *  single-reading sentence renders byte-identically to before. */
-async function assertTurn(line, { memoryDir, sessionId, focus, lexicon = null }) {
+async function assertTurn(line, { memoryDir, sessionId, focus, lexicon = null, cache = null }) {
   try {
     const { parseAce, parseAceAmbiguous } = await import("./grammar/ace.mjs");
     // A session handle carries its own loaded lexicon (createSession loads it once);
@@ -8778,7 +8792,7 @@ async function assertTurn(line, { memoryDir, sessionId, focus, lexicon = null })
         const newSubj = normFactTerm(res.triples[0].subject);
         const newObj = normFactTerm(res.triples[0].object);
         const isTaughtRow = (f) => !f.sourceTypes?.includes("corpus") && !f.sourceTypes?.includes("web");
-        const priorEdges = (await factRows(memoryDir))
+        const priorEdges = (await factRows(memoryDir, cache))
           .filter((f) => f.predicate === SUBCLASS_PREDICATE && isTaughtRow(f)
             && !(normFactTerm(f.subject) === newSubj && normFactTerm(f.object) === newObj))
           .map((f) => [normFactTerm(f.subject), normFactTerm(f.object)]);
@@ -8930,8 +8944,22 @@ function rewriteUsesAsBaseFrame(text) {
   return null;
 }
 
-export async function runTurn(input, { config, source = defaultSource, graph = null, focus = null, last = null, memoryDir = null, sessionId = "", env = process.env, lexicon = null, narrate = false, vocabHint = null, tel = null, biasByBundle = {} } = {}) {
+export async function runTurn(input, { config, source = defaultSource, graph = null, focus = null, last = null, memoryDir = null, sessionId = "", env = process.env, lexicon = null, narrate = false, vocabHint = null, tel = null, biasByBundle = {}, factRowsCache: injectedFactRowsCache = null } = {}) {
   const line = String(input ?? "").trim();
+  // PLAN_GRAPH_SCAN.md "Query side: memoize the per-turn reload": ONE fresh,
+  // empty cache for this turn only — every factRows() reader reached from this
+  // call (factAnswer, factReadBack, describedFacts, countFromFacts,
+  // answerQuantifierRecall, assertTurn, teachLane's grounding fallbacks,
+  // conceptForceAnswer, …) shares it via `ctx`/an explicit trailing arg, so the
+  // first reader to run computes loadMemory+readFactRows once and every later
+  // reader THIS TURN reuses that same result instead of reloading from disk.
+  // Never persisted, never shared across turns or with mutateMemory (a global
+  // cache was explicitly rejected — see the plan doc's own reasoning: a reader
+  // could observe a mutator's half-written object). `injectedFactRowsCache` is a
+  // TEST-ONLY escape hatch (default null, so every real caller gets a fresh one
+  // exactly as before) — passing one in lets a test observe `.reloads` after the
+  // call to assert the real load path ran exactly once this turn.
+  const factRowsCache = injectedFactRowsCache ?? { rows: null };
   // The captured residue is used for RECOGNITION at every dispatch site below
   // (asBareCommand, conversationalTurn, assertTurn, the count lanes, runAsk);
   // the ORIGINAL `line` survives untouched for record.query/logLines fidelity
@@ -8959,7 +8987,7 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
   // pass one gets it computed here instead, so "try this vocabulary example" is
   // never wrong regardless of caller.
   const resolvedVocabHint = vocabHint ?? vocabExampleHint(await hasSeededVocabulary(memoryDir));
-  const ctx = { config, source, graph, focus, last, memoryDir, sessionId, templates, env, lexicon, trace, narrate, vocabHint: resolvedVocabHint, tel, biasByBundle };
+  const ctx = { config, source, graph, focus, last, memoryDir, sessionId, templates, env, lexicon, trace, narrate, vocabHint: resolvedVocabHint, tel, biasByBundle, cache: factRowsCache };
   // A DISPATCHED turn (count / slash-command / ask) becomes the new "last answer"
   // that why/say-more re-renders; a conversational turn does not (it preserves it).
   // FINISH SEAM (PLAN_RESPONSE_FINISHING §"Where it lives"): every dispatched turn's
@@ -9051,7 +9079,7 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
   // authority gate declines (returns null) for anything answerCount should own,
   // so ordinary structural counts fall through completely unaffected.
   if (memoryDir) {
-    const quantifierRecall = await answerQuantifierRecall(memoryDir, workingLine, biasByBundle);
+    const quantifierRecall = await answerQuantifierRecall(memoryDir, workingLine, biasByBundle, factRowsCache);
     if (quantifierRecall != null) {
       note(trace, 'goal: recall a taught quantifier for a class-membership pair ("how many Xs are Ys")');
       note(trace, "lane: answerQuantifierRecall — matched HOW_MANY_ARE_RE with a subject tmct has facts about; literal recall, never real counting");
@@ -9079,7 +9107,7 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
     // ASSERTED vocabulary fact ("every class is a type" → "how many types" = the
     // class count). countFromFacts declines on a real graph kind, so ordinary
     // counts are unaffected; it only speaks for a remembered object noun.
-    const viaFact = memoryDir ? await countFromFacts(graph, memoryDir, workingLine, biasByBundle) : null;
+    const viaFact = memoryDir ? await countFromFacts(graph, memoryDir, workingLine, biasByBundle, factRowsCache) : null;
     if (viaFact != null) {
       note(trace, 'goal: get a count of an asserted-vocabulary kind ("every X is a Y" inherited cardinality)');
       note(trace, "lane: countFromFacts — the counted noun matched a remembered isa-fact's SUBJECT, whose class IS countable");

package/src/memory/core.mjs

@@ -762,8 +762,56 @@ async function persistMemory(dir, payload) {
  *  reached). `await fn(payload)` is a documented no-op for every existing
  *  SYNC caller (appendUtterance(s), appendFacts) — awaiting a non-Promise
  *  value just resolves to it, byte-identical behaviour to calling it plain. */
+// ---- mutateMemory-scoped lookup index (PLAN_GRAPH_SCAN.md Phase 1) ----------
+// syncFactSources's per-fact bookkeeping (upsertSource, upsertIndividual,
+// upsertEdge's statedBy path, statedByObjectsFor, sourcesByIdMap) used to each
+// re-scan payload.individuals or the statedBy edge list from scratch, turning
+// one appendFacts batch of n facts into O(n^2) work. mutateMemory now builds
+// three lookup Maps once per call (one O(n) pass) and attaches them to payload
+// under a Symbol key — JSON.stringify skips Symbol-keyed properties
+// automatically, so persistMemory's graph.json write is byte-identical to
+// before. Every helper below checks for the Symbol slot: present → O(1) Map
+// lookup; absent (a bare payload object built outside mutateMemory, e.g. a
+// test fixture) → today's exact linear-scan fallback, so nothing outside
+// mutateMemory's own call chain can observe a behaviour change. The index is
+// discarded when mutateMemory returns — it never survives across calls, so
+// there is no invalidation logic to get wrong.
+const MEMORY_INDEX = Symbol("mutateMemory lookup index");
+
+/** Build the three lookup Maps from the just-loaded payload and attach them
+ *  under MEMORY_INDEX. Any code that pushes a new individual into
+ *  payload.individuals, or a new statedBy edge, must also write the matching
+ *  index entry in that same statement (see upsertIndividual/upsertSource/
+ *  upsertEdge/appendFacts below) — the same discipline appendFacts's own
+ *  local `byId` Map already used for the Fact upsert, generalised here. */
+function buildMemoryIndex(payload) {
+  const individualsById = new Map();
+  const sourcesById = new Map();
+  const statedByBySubject = new Map();
+  for (const ind of payload.individuals || []) {
+    if (!ind?.id) continue;
+    individualsById.set(ind.id, ind);
+    if (ind.class === SOURCE_CLASS) sourcesById.set(ind.id, ind);
+  }
+  const statedGroup = (payload.objectProperties || []).find((g) => g?.prop === STATED_BY_PROP);
+  for (const e of statedGroup?.examples || []) {
+    if (!e?.subject) continue;
+    const list = statedByBySubject.get(e.subject);
+    if (list) list.push(e.object);
+    else statedByBySubject.set(e.subject, [e.object]);
+  }
+  payload[MEMORY_INDEX] = { individualsById, sourcesById, statedByBySubject };
+  return payload[MEMORY_INDEX];
+}
+
+/** The active lookup index for this payload, or null when this payload wasn't
+ *  built by mutateMemory (a bare test fixture) — callers fall back to a
+ *  linear scan in that case. */
+const memoryIndexOf = (payload) => payload?.[MEMORY_INDEX] || null;
+
 async function mutateMemory(dir, fn) {
   const payload = await loadMemory(dir);
+  buildMemoryIndex(payload);
   const out = (await fn(payload)) ?? payload;
   migrateLegacyProvenance(out);
   recomputeSourceReliability(out);
@@ -827,9 +875,10 @@ const sourceLabel = (id) => String(id).replace(/^src:/, "");
 function upsertSource(payload, desc, createdAtCandidate) {
   const info = sourceIdFor(desc);
   if (!info) return null;
-  const prior = payload.individuals.find((i) => i?.id === info.id);
+  const idx = memoryIndexOf(payload);
+  const prior = idx ? idx.individualsById.get(info.id) : payload.individuals.find((i) => i?.id === info.id);
   const created = firstWriteCreatedAt(prior, desc?.createdAt || createdAtCandidate);
-  upsertIndividual(payload, {
+  const ind = {
     id: info.id, label: sourceLabel(info.id), class: SOURCE_CLASS,
     derived_from: [], mentions: [],
     attributes: [
@@ -839,7 +888,9 @@ function upsertSource(payload, desc, createdAtCandidate) {
       ...(info.url ? [{ prop: "mgx:sourceUrl", key: "sourceUrl", value: info.url }] : []),
       ...(info.rule ? [{ prop: "mgx:sourceRule", key: "sourceRule", value: info.rule }] : []),
     ],
-  });
+  };
+  const stored = upsertIndividual(payload, ind);
+  if (idx) idx.sourcesById.set(info.id, stored);
   return info.id;
 }
 
@@ -906,13 +957,23 @@ export function provenanceTagToSource(tag) {
 /** Map a payload's Source individuals into the { id: Source } shape computeTrust
  *  resolves against. */
 function sourcesByIdMap(payload) {
+  const idx = memoryIndexOf(payload);
   const m = {};
+  if (idx) {
+    // idx.sourcesById is kept incrementally correct by upsertSource, so this
+    // is O(distinct Sources) — a handful, roughly one per corpus/provider —
+    // never O(all individuals), unlike the fallback rebuild below.
+    for (const [id, ind] of idx.sourcesById) m[id] = ind;
+    return m;
+  }
   for (const i of payload.individuals) if (i?.class === SOURCE_CLASS) m[i.id] = i;
   return m;
 }
 
 /** The Source ids a Fact is statedBy, read off the edge group. */
 function statedByObjectsFor(payload, factId) {
+  const idx = memoryIndexOf(payload);
+  if (idx) return (idx.statedByBySubject.get(factId) || []).slice();
   const g = payload.objectProperties.find((x) => x?.prop === STATED_BY_PROP);
   return (g?.examples || []).filter((e) => e?.subject === factId).map((e) => e.object);
 }
@@ -1039,8 +1100,9 @@ function recomputeSourceReliability(payload) {
   }
   if (!bySource.size) return;
 
+  const idx = memoryIndexOf(payload);
   for (const [sid, counts] of bySource) {
-    const source = payload.individuals.find((i) => i?.id === sid);
+    const source = idx ? idx.individualsById.get(sid) : payload.individuals.find((i) => i?.id === sid);
     if (!source) continue;
     setAttr(source, SOURCE_RELIABILITY_PROP, "sourceReliability", String(sessionReliabilityFrom(counts)));
     // Own-attribute mutation in place (PLAN_VIZ.md §2) — same reasoning as recomputeFactTrust.
@@ -1053,16 +1115,38 @@ function recomputeSourceReliability(payload) {
   const affected = new Set();
   for (const e of statedGroup?.examples || []) if (bySource.has(e?.object)) affected.add(e.subject);
   for (const id of affected) {
-    const ind = payload.individuals.find((i) => i?.id === id);
+    const ind = idx ? idx.individualsById.get(id) : payload.individuals.find((i) => i?.id === id);
     if (ind) recomputeFactTrust(payload, ind);
   }
 }
 
-/** Upsert an individual by id (replace-in-place keeps ordering stable). */
+/** Upsert an individual by id (replace-in-place keeps ordering stable).
+ *  Returns the individual object actually stored in payload.individuals — the
+ *  caller (e.g. upsertSource) should index THAT reference, not `ind` itself,
+ *  since the indexed path below merges into the prior object in place rather
+ *  than replacing the array slot. When a lookup index is present (built by
+ *  mutateMemory), an existing individual is updated via Object.assign — same
+ *  array position AND same object identity as before, so it stays trivially
+ *  in sync with individualsById without a second Map write, and a brand-new
+ *  individual is pushed + indexed in the same statement. Absent an index
+ *  (a bare payload built outside mutateMemory), this is EXACTLY the original
+ *  findIndex + replace-or-push code. */
 function upsertIndividual(payload, ind) {
+  const idx = memoryIndexOf(payload);
+  if (idx) {
+    const prior = idx.individualsById.get(ind.id);
+    if (prior) {
+      Object.assign(prior, ind);
+      return prior;
+    }
+    payload.individuals.push(ind);
+    idx.individualsById.set(ind.id, ind);
+    return ind;
+  }
   const i = payload.individuals.findIndex((x) => x?.id === ind.id);
-  if (i >= 0) payload.individuals[i] = ind;
-  else payload.individuals.push(ind);
+  if (i >= 0) { payload.individuals[i] = ind; return ind; }
+  payload.individuals.push(ind);
+  return ind;
 }
 
 /** Upsert one edge into the named relation group (dedupe by subject>object). Stamps `createdAt`
@@ -1076,6 +1160,27 @@ function upsertEdge(payload, { predicate, prop }, edge) {
     group = { predicate, prop, count: 0, examples: [] };
     payload.objectProperties.push(group);
   }
+  // statedBy-only fast path (PLAN_GRAPH_SCAN.md Phase 1): statedByBySubject
+  // tracks, per fact, the small list of Source ids already stated it (almost
+  // always 0-1 during a seed), so the overwhelmingly common case — a brand
+  // new (subject,object) statedBy pair — can append directly without the
+  // find+filter scan of the WHOLE statedBy edge list below. Every other
+  // predicate (saidInSession, inReplyTo, ...) is untouched and always takes
+  // the original path.
+  const idx = prop === STATED_BY_PROP ? memoryIndexOf(payload) : null;
+  if (idx) {
+    const existing = idx.statedByBySubject.get(edge.subject);
+    if (!existing || !existing.includes(edge.object)) {
+      group.examples.push({ ...edge, createdAt: edge.createdAt || nowIso() });
+      group.count = group.examples.length;
+      if (existing) existing.push(edge.object);
+      else idx.statedByBySubject.set(edge.subject, [edge.object]);
+      return;
+    }
+    // Rare re-assert of the exact same (subject,object) pair — fall through
+    // to the exact original find+filter dance so first-write-wins createdAt
+    // is preserved; the index is kept accurate below too.
+  }
   // Edges are flat ({subject, object, ...}), not attribute-bearing individuals, so this can't
   // reuse firstWriteCreatedAt (which reads `.attributes`) directly — same discipline, edge shape:
   // the prior edge's OWN createdAt wins if it has one, else the incoming candidate, else now.
@@ -1086,6 +1191,11 @@ function upsertEdge(payload, { predicate, prop }, edge) {
   );
   group.examples.push({ ...edge, createdAt });
   group.count = group.examples.length;
+  if (idx) {
+    const list = idx.statedByBySubject.get(edge.subject) || [];
+    if (!list.includes(edge.object)) list.push(edge.object);
+    idx.statedByBySubject.set(edge.subject, list);
+  }
 }
 
 /** Recount `classes[]` from the individuals — every memory class stays counted
@@ -1341,7 +1451,13 @@ export async function appendFacts(dir, facts) {
   if (!prepared.length) return { ids, appended: 0, skipped };
   await mutateMemory(dir, (payload) => {
     // id → individual index for O(1) upsert (the array grows to thousands).
-    const byId = new Map(payload.individuals.map((i) => [i?.id, i]));
+    // When mutateMemory already built the Symbol-keyed lookup index, reuse
+    // THAT Map directly (same object) instead of rescanning payload.individuals
+    // a second time — every `byId.set` below then also keeps
+    // idx.individualsById correct for upsertSource/recomputeSourceReliability's
+    // later lookups in this same mutation, with no extra write.
+    const idx = memoryIndexOf(payload);
+    const byId = idx ? idx.individualsById : new Map(payload.individuals.map((i) => [i?.id, i]));
     const touched = [];
     const seen = new Set();
     const trustOptsById = new Map();
@@ -1370,10 +1486,15 @@ export async function appendFacts(dir, facts) {
           ...(f.justification && f.justification.length ? [{ prop: "mgx:factJustification", key: "justification", value: f.justification.join(" ") }] : []),
         ],
       };
-      // Upsert into BOTH the array (replace-in-place keeps order) and the index.
-      if (prior) payload.individuals[payload.individuals.indexOf(prior)] = ind;
-      else payload.individuals.push(ind);
-      byId.set(f.id, ind);
+      // Upsert via the shared helper — O(1) via the index (Object.assign in
+      // place when `prior` exists, push+index when it's new), same as every
+      // other upsert path now. Previously this did its own inline
+      // `payload.individuals.indexOf(prior)` array scan on a re-assert within
+      // the same batch — an O(n) fallback that could still blow up a batch
+      // heavy with within-file duplicate triples; upsertIndividual has no
+      // such case left.
+      const stored = upsertIndividual(payload, ind);
+      byId.set(f.id, stored);
       ids.push(f.id);
       if (!seen.has(f.id)) { seen.add(f.id); touched.push(f.id); }
       // Last-prepared-row-wins per id for the trust hook opts (mirrors the

package/src/viz.mjs

@@ -207,9 +207,11 @@ export function renderVizHtml({ nodes, edges, focus, payload, askBundle, memoryA
   #wrap { position: relative; width: 100vw; height: 100vh; overflow: hidden; }
   canvas { display: block; width: 100%; height: 100%; cursor: grab; touch-action: none; }
   canvas.grabbing { cursor: grabbing; }
-  #hud { position: absolute; top: 12px; left: 12px; max-width: 42ch; background: rgba(20,22,30,0.82); border: 1px solid rgba(255,255,255,0.12); border-radius: 8px; padding: 10px 12px; font-size: 12.5px; line-height: 1.45; pointer-events: none; }
+  #hud { position: absolute; top: 12px; left: 12px; max-width: 34ch; background: rgba(20,22,30,0.82); border: 1px solid rgba(255,255,255,0.12); border-radius: 8px; padding: 10px 12px; font-size: 12.5px; line-height: 1.45; pointer-events: none; }
   #hud b { color: #fff; }
-  #hud .muted { color: #9aa1b0; }
+  #hud .muted { color: #9aa1b0; display: block; margin: 4px 0 8px; }
+  #hud button { pointer-events: auto; background: rgba(255,255,255,0.08); border: 1px solid rgba(255,255,255,0.2); color: #e7e9ee; border-radius: 5px; padding: 3px 9px; font-size: 12px; cursor: pointer; }
+  #hud button:hover { background: rgba(255,255,255,0.18); }
   #controls { position: absolute; top: 12px; left: 50%; transform: translateX(-50%); display: flex; gap: 10px; align-items: center; background: rgba(20,22,30,0.88); border: 1px solid rgba(255,255,255,0.14); border-radius: 8px; padding: 7px 12px; font-size: 12.5px; flex-wrap: wrap; max-width: min(86vw, 900px); }
   #controls .grp { display: flex; align-items: center; gap: 5px; }
   #controls button { background: rgba(255,255,255,0.08); border: 1px solid rgba(255,255,255,0.2); color: #e7e9ee; border-radius: 5px; width: 22px; height: 22px; line-height: 1; cursor: pointer; font-size: 13px; }
@@ -223,14 +225,14 @@ export function renderVizHtml({ nodes, edges, focus, payload, askBundle, memoryA
   #controls input[type="number"] { width: 3.6em; }
   #controls input[type="text"].search { width: 9em; }
   #controls .sep { width: 1px; align-self: stretch; background: rgba(255,255,255,0.14); margin: 0 2px; }
-  #legend { position: absolute; top: 58px; left: 50%; transform: translateX(-50%); display: none; flex-wrap: wrap; gap: 6px; align-items: center; background: rgba(20,22,30,0.88); border: 1px solid rgba(255,255,255,0.14); border-radius: 8px; padding: 6px 10px; font-size: 11.5px; max-width: min(86vw, 900px); }
+  #legend { position: absolute; bottom: 12px; left: 12px; display: none; flex-wrap: wrap; gap: 6px; align-items: center; background: rgba(20,22,30,0.88); border: 1px solid rgba(255,255,255,0.14); border-radius: 8px; padding: 6px 10px; font-size: 11.5px; max-width: min(60vw, 640px); }
   #legend.show { display: flex; }
   #legend select { background: #14161e; color: #e7e9ee; border: 1px solid #2a2e42; border-radius: 5px; padding: 1px 4px; font: inherit; font-size: 11px; }
   #legend .chip { display: flex; align-items: center; gap: 4px; cursor: pointer; padding: 2px 6px; border-radius: 10px; border: 1px solid rgba(255,255,255,0.16); }
   #legend .chip.off { opacity: 0.4; }
   #legend .chip .swatch { width: 7px; height: 7px; border-radius: 50%; display: inline-block; }
   #legend .chip .n { color: #9aa1b0; }
-  #panel { position: absolute; top: 12px; right: 12px; width: 280px; max-width: calc(100vw - 24px); background: rgba(20,22,30,0.92); border: 1px solid rgba(255,255,255,0.14); border-radius: 8px; padding: 12px 14px; font-size: 13px; line-height: 1.5; display: none; }
+  #panel { position: absolute; top: 12px; right: 404px; width: 280px; max-width: calc(100vw - 428px); background: rgba(20,22,30,0.92); border: 1px solid rgba(255,255,255,0.14); border-radius: 8px; padding: 12px 14px; font-size: 13px; line-height: 1.5; display: none; }
   #panel.show { display: block; }
   #panel h2 { margin: 0 0 6px; font-size: 14px; word-break: break-word; }
   #panel dl { margin: 8px 0 0; }
@@ -245,26 +247,26 @@ export function renderVizHtml({ nodes, edges, focus, payload, askBundle, memoryA
   #empty.show { display: flex; }
   #empty div { max-width: 46ch; color: #9aa1b0; }
   #empty b { color: #e7e9ee; }
-  #ask { position: absolute; bottom: 12px; right: 12px; width: 340px; max-width: calc(100vw - 24px); background: rgba(20,22,30,0.92); border: 1px solid rgba(255,255,255,0.14); border-radius: 8px; padding: 10px 12px; font-size: 12.5px; }
-  #ask h3 { margin: 0 0 6px; font-size: 12.5px; color: #9aa1b0; font-weight: 600; text-transform: uppercase; letter-spacing: 0.04em; }
-  #ask .row { display: flex; gap: 6px; }
+  #ask { position: absolute; top: 12px; bottom: 12px; right: 12px; width: 380px; max-width: calc(100vw - 24px); background: rgba(20,22,30,0.92); border: 1px solid rgba(255,255,255,0.14); border-radius: 8px; padding: 10px 12px; font-size: 12.5px; display: flex; flex-direction: column; }
+  #ask h3 { margin: 0 0 6px; font-size: 12.5px; color: #9aa1b0; font-weight: 600; text-transform: uppercase; letter-spacing: 0.04em; flex: 0 0 auto; }
+  #ask .row { display: flex; gap: 6px; flex: 0 0 auto; }
   #askq { flex: 1; min-width: 0; background: #14161e; color: #e7e9ee; border: 1px solid #2a2e42; border-radius: 5px; padding: 6px 9px; font: inherit; font-size: 12.5px; }
   #askq:focus { outline: none; border-color: #7aa2f7; }
   #askq:disabled { opacity: 0.6; }
   #asksubmit { background: rgba(122,162,247,0.18); border: 1px solid #7aa2f7; color: #cfe0ff; border-radius: 5px; padding: 6px 12px; font-size: 12.5px; cursor: pointer; }
   #asksubmit:hover { background: rgba(122,162,247,0.3); }
-  #askresult { margin-top: 8px; max-height: 32vh; overflow: auto; line-height: 1.55; color: #c0caf5; white-space: pre-wrap; }
+  #askresult { margin-top: 8px; flex: 1 1 auto; min-height: 0; overflow: auto; line-height: 1.55; color: #c0caf5; white-space: pre-wrap; }
   #askresult .q { color: #565f89; font-style: normal; margin-bottom: 3px; }
   #askresult.miss { color: #a9b1d6; font-style: italic; }
   #askresult .canon { margin-top: 6px; color: #6b7189; font-size: 11px; font-style: normal; border-top: 1px dashed rgba(255,255,255,0.1); padding-top: 5px; }
   #askresult .src { margin-top: 4px; color: #565f89; font-size: 10.5px; }
-  #ask .hint { color: #6b7189; font-size: 11px; }
+  #ask .hint { color: #6b7189; font-size: 11px; flex: 0 0 auto; }
 </style>
 </head>
 <body>
 <div id="wrap">
   <canvas id="c"></canvas>
-  <div id="hud"><b>tmct viz</b><br><span class="muted">drag to pan &middot; scroll to zoom &middot; click a node for details &middot; double-click to re-centre</span></div>
+  <div id="hud"><b>tmct viz</b><span class="muted">drag to pan &middot; scroll to zoom &middot; click a node for details &middot; double-click to re-centre</span><button id="resetview" title="reset pan/zoom to fit the current view">reset view</button></div>
   <div id="controls">
     <span class="grp"><span class="muted">depth</span><button id="depthdown" title="shallower">&minus;</button><b class="depthval" id="depthval"></b><button id="depthup" title="deeper">+</button></span>
     <span class="grp" id="typefilters"></span>
@@ -579,6 +581,10 @@ ${hasMemChat ? `<script>\n${memoryAskBundle}\n</script>` : ""}
   var dpr = window.devicePixelRatio || 1;
   var view = { scale: 1, x: 0, y: 0 };
   var selectedId = null;
+  // The full set of node ids a query answer actually resolved to (not just
+  // the single "primary" selectedId) — draw() rings every one of them so a
+  // multi-fact answer shows ALL the nodes it came from, not just one.
+  var highlightIds = new Set();
 
   function resize() {
     canvas.width = Math.floor(canvas.clientWidth * dpr);
@@ -667,6 +673,14 @@ ${hasMemChat ? `<script>\n${memoryAskBundle}\n</script>` : ""}
         ctx.lineWidth = Math.max(1.5, 2 * dpr); ctx.strokeStyle = "#e0af68";
         ctx.beginPath(); ctx.arc(sp.x, sp.y, Math.max(1.5, r) + 5 * dpr, 0, Math.PI * 2); ctx.stroke();
       }
+      // Every node the last "ask the graph" answer actually resolved to
+      // (frameQueryResult below) — a distinct green ring so a multi-fact
+      // answer's whole result set reads as one highlighted group, not just
+      // the single primary node selectedId/focus already mark.
+      if (highlightIds.has(n.id) && n.id !== selectedId) {
+        ctx.lineWidth = Math.max(1.5, 2 * dpr); ctx.strokeStyle = "#9ece6a";
+        ctx.beginPath(); ctx.arc(sp.x, sp.y, Math.max(1.5, r) + 4 * dpr, 0, Math.PI * 2); ctx.stroke();
+      }
       var showLabel = view.scale > 0.55 && labelMode !== "none" && (
         labelMode !== "smart"
         || n.id === selectedId || n.id === GRAPH.focus || n.id === hoverId
@@ -710,15 +724,28 @@ ${hasMemChat ? `<script>\n${memoryAskBundle}\n</script>` : ""}
     draw();
   }, { passive: false });
 
-  function fitToVisible() {
-    var vis = Array.from(visibleNodeIds()).map(function (id) { return pos.get(id); }).filter(Boolean);
-    if (!vis.length) return;
-    var minX = Math.min.apply(null, vis.map(function (p) { return p.x; })), maxX = Math.max.apply(null, vis.map(function (p) { return p.x; }));
-    var minY = Math.min.apply(null, vis.map(function (p) { return p.y; })), maxY = Math.max.apply(null, vis.map(function (p) { return p.y; }));
+  // Shared bounding-box fit — pan/zoom so every position in "points" is framed
+  // with padding. fitToVisible/fitToIds are both thin wrappers naming WHICH
+  // positions to fit; the math itself lives here once.
+  function fitToPositions(points) {
+    if (!points.length) return;
+    var minX = Math.min.apply(null, points.map(function (p) { return p.x; })), maxX = Math.max.apply(null, points.map(function (p) { return p.x; }));
+    var minY = Math.min.apply(null, points.map(function (p) { return p.y; })), maxY = Math.max.apply(null, points.map(function (p) { return p.y; }));
     var w = Math.max(1, maxX - minX), h = Math.max(1, maxY - minY);
     view.scale = Math.min(4, Math.max(0.1, Math.min(canvas.width / dpr / (w + 160), canvas.height / dpr / (h + 160))));
     view.x = -(minX + maxX) / 2 * view.scale; view.y = -(minY + maxY) / 2 * view.scale;
   }
+  function fitToVisible() {
+    fitToPositions(Array.from(visibleNodeIds()).map(function (id) { return pos.get(id); }).filter(Boolean));
+  }
+  // Fit specifically to a query answer's own result set (not just "whatever
+  // recentre's re-walk happened to make visible") — a multi-fact answer's
+  // nodes can be spread wider than the default depth/nodeLimit view, so this
+  // is the precision framing step frameQueryResult calls after recentre.
+  function fitToIds(ids) {
+    fitToPositions(ids.map(function (id) { return pos.get(id); }).filter(Boolean));
+  }
+  document.getElementById("resetview").addEventListener("click", function () { fitToVisible(); draw(); });
 
   // ---- recentre: RE-WALK the FULL graph (via TERM_GRAPH — Bug 2's augmented
   // view, so a recentre reaches real concept-relation edges the same way
@@ -750,6 +777,24 @@ ${hasMemChat ? `<script>\n${memoryAskBundle}\n</script>` : ""}
     fitToVisible();
     return true;
   }
+
+  // Focus the graph on a QUERY ANSWER's own result set — every node it
+  // actually resolved to, not just one. Re-walks from the first valid id
+  // (recentre's existing mechanism, which already reaches most/all closely
+  // related result nodes), then fitToIds() precisely frames the full
+  // requested set — any id recentre's walk didn't reach simply has no
+  // position and drops out of the fit, an honest degrade, never a guess.
+  // Sets highlightIds so draw() rings every result node, not just the
+  // primary one selectedId/GRAPH.focus already mark.
+  function frameQueryResult(ids) {
+    var real = (ids || []).filter(function (id) { return walkGraph().byId.has(id); });
+    if (!real.length) return false;
+    if (!recentre(real[0])) return false;
+    fitToIds(real);
+    highlightIds = new Set(real);
+    selectedId = real[0];
+    return true;
+  }
   document.getElementById("edgekind").addEventListener("change", function (ev) {
     edgeKindMode = ev.target.value;
     var seed = GRAPH.focus;
@@ -866,22 +911,53 @@ ${hasMemChat ? `<script>\n${memoryAskBundle}\n</script>` : ""}
   var memHandle = hasMemEngine ? tmctMemoryAsk.createInMemoryStore() : null;
   if (memHandle) memHandle.payload = PAYLOAD;
 
-  // Light, best-effort focus-follow for a memory-engine hit: factAnswer
-  // returns rendered TEXT, not a resolved entity id (unlike ask.mjs's
-  // envelope/matches) — strip a leading question-word crust and try the
-  // remainder as a term id. An honest "don't recentre" on no match, never a
-  // wrong guess.
-  function guessTermIdFromQuery(query) {
-    if (!hasEngine || !hasMemEngine) return null;
+  // Placeholder is a real term from THIS graph, picked once per page load, so
+  // the hint stays honest ("what is X" where X actually resolves here) instead
+  // of a static example that may not exist in a given repo's graph. Native
+  // <input placeholder> behaviour (disappears on focus/typing, reappears when
+  // blank) is untouched — this only changes what text it starts with.
+  if (hasEngine && FULL_GRAPH) {
+    var termLabels = [];
+    walkGraph().byId.forEach(function (ind, id) {
+      if (id.indexOf("term:") === 0 && ind.label) termLabels.push(ind.label);
+    });
+    if (termLabels.length) {
+      askInput.placeholder = 'what is ' + termLabels[Math.floor(Math.random() * termLabels.length)];
+    }
+  }
+
+  // Best-effort focus-follow for a memory-engine hit: factAnswer returns
+  // rendered TEXT, not a list of resolved entity ids (unlike ask.mjs's
+  // envelope/matches). Two passes, both real-graph-checked, never a guessed
+  // id that doesn't exist:
+  //  1. every term node whose label appears in the ANSWER text — this is
+  //     "the nodes that come back," e.g. "dog is a kind of animal" surfaces
+  //     BOTH term:dog and term:animal, not just the one the question asked
+  //     about, so a multi-fact answer highlights its whole result set.
+  //  2. if that finds nothing (e.g. a phrasing that doesn't echo a bare term
+  //     label), fall back to stripping the QUESTION's own crust and trying
+  //     the remainder as a single term id — the previous behaviour, kept as
+  //     a fallback rather than replaced.
+  function findAnsweredTermIds(query, answerText) {
+    if (!hasEngine || !hasMemEngine) return [];
+    var hay = " " + String(answerText).toLowerCase() + " ";
+    var found = [];
+    walkGraph().byId.forEach(function (ind, id) {
+      if (id.indexOf("term:") !== 0) return;
+      var label = String(ind.label || "").toLowerCase();
+      if (label.length < 3) return; // skip too-short/noisy labels (dedupe/precision, not a real cap)
+      if (hay.indexOf(" " + label) !== -1 || hay.indexOf(label + " ") !== -1) found.push(id);
+    });
+    if (found.length) return found;
     var stripped = String(query).toLowerCase()
       .replace(/^(what|where|who|which|does|do|is|are)\b/, "")
       .replace(/\b(is|are|used for|do|does|mean|means|a|an|the)\b/g, " ")
       .replace(/[?.!]+$/, "")
       .replace(/\s+/g, " ")
       .trim();
-    if (!stripped) return null;
+    if (!stripped) return [];
     var id = "term:" + tmctMemoryAsk.normFactTerm(stripped);
-    return walkGraph().byId.has(id) ? id : null;
+    return walkGraph().byId.has(id) ? [id] : [];
   }
 
   function runAsk(query) {
@@ -893,8 +969,7 @@ ${hasMemChat ? `<script>\n${memoryAskBundle}\n</script>` : ""}
         if (fact && fact.text) {
           askOut.innerHTML = '<div class="q">&quot;' + esc(query) + '&quot;</div>' + esc(fact.text)
             + '<div class="src">answered from the full embedded memory graph (not just what\\'s currently drawn)</div>';
-          var termId = guessTermIdFromQuery(query);
-          if (termId && recentre(termId)) selectedId = termId;
+          frameQueryResult(findAnsweredTermIds(query, fact.text));
           draw();
           return;
         }
@@ -911,13 +986,13 @@ ${hasMemChat ? `<script>\n${memoryAskBundle}\n</script>` : ""}
         ? '<div class="canon">read as: ' + esc(envelope.canonical.english) + "</div>"
         : "";
       askOut.innerHTML = '<div class="q">&quot;' + esc(query) + '&quot;</div>' + esc(t.content) + canon;
-      // Focus-follows-answer: prefer the resolved objMatch (the term the
-      // question was actually ABOUT), else the first real match — either way,
-      // only if it's a genuine individual in the graph, never a guess.
-      var targetId = (envelope.parsed && envelope.parsed.object && (envelope.matches || [])[0] && envelope.matches[0].id)
-        || (envelope.matches && envelope.matches[0] && envelope.matches[0].id)
-        || null;
-      if (targetId && recentre(targetId)) { selectedId = targetId; }
+      // Focus-follows-answer: frame EVERY real match this answer resolved to
+      // (envelope.matches is already the full candidate list ask.mjs itself
+      // ranked — previously only matches[0] recentred, silently dropping the
+      // rest of a multi-match answer's own result set), never a guess beyond
+      // what the engine itself actually returned.
+      var targetIds = (envelope.matches || []).map(function (m) { return m.id; }).filter(Boolean);
+      frameQueryResult(targetIds);
       draw();
     })();
   }