@polycode-projects/the-mechanical-code-talker 6.0.21 → 6.0.22

package/README.md

@@ -131,8 +131,8 @@ table. Choose the architecture that fits your use case.
 | `docs/` | reference docs: the adapter/repository-interface contracts, bibliography |
 | `test/` | the unit, corpus, and estate-guard test suite (`npm test`) |
 | `test-e2e/` | the end-to-end suite: real CLI/TUI spawns and Playwright browser journeys (`npm run test:e2e`) |
-| `test-benchmarks/` | the benchmark harnesses (agentbench, chatbench, idxbench, infbench, ingestbench, researchbench, synthbench) and their shared `benchlib/` |
-| `reports/` | benchmark write-ups (`BENCHMARK_*.md`) and `PAGE_WEIGHTS.md` — see the root `STATUS.md` for the one-page summary these feed |
+| `test-benchmarks/` | the benchmark harnesses (agentbench, idxbench, infbench, ingestbench, researchbench, synthbench) and their shared `benchlib/` |
+| `reports/` | benchmark write-ups (`BENCHMARK_*.md`) — see the root `STATUS.md` for the one-page summary these feed |
 | `playtests/` | numbered playtest session logs, one edge found and fixed per entry |
 | `archive/` | delivered `PLAN_*.md`/`BENCHMARK_*.md` docs, kept for history |
 | `public/` | the demo site: the hand-written home page, `help.html`, the six about pages, `receipts.html`, `claims.html`, the shared stylesheet and the model/screenshot assets. The demo pages and browser bundles beside them are gitignored build outputs of `npm run demo:build` |
@@ -443,11 +443,7 @@ every class's `rdfs:subClassOf` parent drawn as a connector line rather than
 listed. The chat page and the ledger take the same paste-or-drop text in
 place; every page that holds a fact store exports it as JSONL.
 
-Two browsers can also link directly, no server in between: chat's share
-overlay walks a five-step WebRTC handshake (mint an invite, send it, create
-the reply, send that back, paste it to connect), and the mesh grows past a pair — three peers converge
-on the same fact store through a deterministic merge, real browsers driving
-real WebRTC in CI, not a mock. `help.html` walks asking, teaching, sharing,
+`help.html` walks asking, teaching,
 and what to do when something goes wrong. `receipts.html` and `claims.html`
 carry the site's own numbers and claims, each figure naming the committed
 file it was measured or rendered from, including the ones that don't flatter
@@ -1619,19 +1615,15 @@ and transcripts are in the linked write-ups.
 |---|---|---|---|
 | Multi-hop entailment | 379/379 chat cases and 100/100 kernel cases, 0% fabrication, all bands pass | The case set is unchanged from 2.6.0 (same templates, same counts). The one real move this cycle is INF-4's ceiling-graded count dropping 35→30: five cases that now pass as genuine capability instead of against the declared honest-miss floor. | `archive/BENCHMARK_INFERENCE_2.7.12.md` |
 | Tool-call planning | 68/68 cases, 100% plan-completion, 100% result-completion, 0% hallucination, every rung A0→C2 | Goal driver. 2.6.0 gated at TOOL-7 (62/66, 94%). This cycle's router uplift (a guarded RECOVER step, a tied-candidate composer) cleared it: a real capability move, not a ruler change. | `archive/BENCHMARK_AGENT_2.7.12.md` |
-| Groundedness | Every answer carries a source, and an empty graph reports itself empty. Judge-scored mean 1.809/2 over 138 cases, 5 hard fails, 136/138 tier-1. | Judged (`claude-haiku-4-5-20251001`, `judge-prompt-v2`) at N=1. The judge prompt moved v1→v2 since 2.6.0, so this is a measurement, not a clean lever comparison against the prior cycle. The judge runs in the offline eval harness, never in the product. | `archive/BENCHMARK_CEFR_ENGLISH_2.7.12.md` |
 | Abstention (the honest miss) | 0% fabrication across 479 inference rows (379 chat + 100 kernel) and 0% hallucination across 272 agent rows | Structural, not a tuned threshold. tmct abstains because nothing matched, so the rows test a property of a no-model design rather than a score. | `archive/BENCHMARK_INFERENCE_2.7.12.md`, `archive/BENCHMARK_AGENT_2.7.12.md` |
 | Determinism | Byte-identical on rerun: a 379-case `--replay` clean across 2 runs, no LLM, no network, $0 per turn | A property of the no-model pipeline. | `archive/BENCHMARK_INFERENCE_2.7.12.md` |
 | Dialogue robustness (persona sweep) | A 6-persona sweep (textbook logician, casual newcomer, new developer, adversarial sceptic, returning user, planning user) fixed 25 of the prior cycle's 29 routed findings (21 clean, 4 with a residual noted); 4 remain broken, 2 in a shape distinct from the original complaint | Free exploration across all six personas surfaced roughly 60 fresh findings beyond the ratchet check. The single highest-signal pattern: tmct's own suggested repair text was itself frequently broken when followed verbatim (since fixed, see `NEXT.md`). | `archive/BENCHMARK_CONVERSATION_2.7.11.md` |
 
-Seven offline benchmark rigs live in a clone (the harnesses themselves are
+Six offline benchmark rigs live in a clone (the harnesses themselves are
 not in the npm package; AGENTBENCH's capability envelope is, see "As a
 library" above). Each replays a committed case set through the real product
 and writes graded rows you can diff between runs:
 
-- `npm run chatbench:run` measures chat quality against CEFR-graded English
-  cases with deterministic tier-1 checks (the full tuning loop is in
-  `.claude/skills/benchmark-cefr-english/SKILL.md`);
 - `npm run infbench` generates inference cases, then runs each through both
   drive points, the reasoning kernel and the chat surface;
 - `npm run agentbench:run` measures the tool-loop behaviour, and every
@@ -1648,7 +1640,6 @@ The smallest real slice of each, the same invocations the test suite's
 bench-smoke lane replays:
 
 ```bash cwd=repo
-node test-benchmarks/chatbench/run.mjs --stamp smoke --only g-a1-naming-1 --out /tmp/chatbench-smoke
 node test-benchmarks/infbench/generate-cases.mjs --out /tmp/infbench-cases.jsonl
 node test-benchmarks/infbench/run.mjs --cases /tmp/infbench-cases.jsonl --only inf-1-lookup-subClassOf-001 --stamp smoke --out /tmp/infbench-smoke
 node test-benchmarks/agentbench/run.mjs --stamp smoke --driver stub --only ab-a0-describe-widget --out /tmp/agentbench-smoke
@@ -1658,7 +1649,7 @@ Grading beyond tier 1 uses an LLM as judge. The offline eval harness is the
 one place an LLM is allowed, never the product:
 
 ```bash skip=offline-eval-only
-npm run chatbench:judge -- --product /tmp/chatbench-smoke/product.jsonl
+npm run ingestbench:judge -- --product /tmp/ingestbench-smoke/product.jsonl
 ```
 
 ## Security and supply chain
@@ -1735,7 +1726,6 @@ edition, the retrieval date, the terms tmct uses, and what could not be verified
 
 | source | edition | what tmct uses it for |
 |---|---|---|
-| Council of Europe, CEFR — Companion volume | 2020, ISBN 978-92-871-8621-8 | The band labels A1–C2 the chat benchmark grades against. CEFR measures what a *person* can do communicatively; grading the difficulty of *prompts* by band is tmct's adaptation, not a CEFR-validated use. The band descriptions in `test-benchmarks/chatbench/GRADED.md` are tmct's own prose. |
 | Reiter, "On Closed World Data Bases" | *Logic and Data Bases*, Plenum, 1978, pp. 55–76 | Both halves of the honest miss. The planner's operator model is **closed-world**, which is what makes a plan checkable. The chat layer is **open-world**: it will not read "no matching rule" as "the answer is no". |
 | Chow, "On optimum recognition error and reject tradeoff" | *IEEE Trans. Information Theory* 16(1), 1970 | Prior art for the goal. The literature calls a refusal **abstention**, or selective prediction, and Chow's reject option is its root. Those methods threshold a confidence score; tmct has none, and abstains because nothing matched — which is why the row above names the mechanism. |
 | Ji et al., "Survey of Hallucination in Natural Language Generation" | *ACM Computing Surveys* 55(12), 2023 | Groundedness, and what tmct is avoiding by having no model to hallucinate with. |

package/bin/tmct.mjs

@@ -710,6 +710,11 @@ async function main() {
     // supplement on. Default OFF; `/wiki on`/`/wiki off` toggles it
     // mid-session.
     const liveReference = rest.includes("--live-wikipedia");
+    // `--code-graph` (or TMCT_CODE_GRAPH=1, read inside createSession): start
+    // the session reading every line as a question about the code graph.
+    // Default OFF; `/code-graph on`/`/code-graph off` toggles it mid-session.
+    // Nothing infers this from the graph or from what you type.
+    const codeGraphMode = rest.includes("--code-graph");
     // `--graph <path>` (repeatable) / `--config <path>` (src/services/cli-args.mjs): threaded
     // through as the new top tier of createSession's graph-resolution order (above
     // TMCT_GRAPH_FILE — see chat.mjs's own docblock at createSession). Omitted from
@@ -770,7 +775,7 @@ async function main() {
     if (prompt) {
       const { createSession } = await import("../src/services/chat.mjs");
       const { splitSentences } = await import("../src/services/sentences.mjs");
-      const session = await createSession({ repoPath, ephemeral, narrate, liveReference, ...extra });
+      const session = await createSession({ repoPath, ephemeral, narrate, liveReference, codeGraphMode, ...extra });
       let finalAnswer = "";
       let finalPlan = null;
       let parts;
@@ -812,10 +817,10 @@ async function main() {
     const plain = rest.includes("--plain") || !process.stdin.isTTY || !process.stdout.isTTY;
     if (plain) {
       const { runChat } = await import("../src/services/chat.mjs");
-      await runChat({ repoPath, ephemeral, narrate, liveReference, ...extra });
+      await runChat({ repoPath, ephemeral, narrate, liveReference, codeGraphMode, ...extra });
     } else {
       const { runTui } = await import("../src/surfaces/tui/app.mjs");
-      await runTui({ repoPath, ephemeral, narrate, liveReference, ...extra });
+      await runTui({ repoPath, ephemeral, narrate, liveReference, codeGraphMode, ...extra });
     }
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "6.0.21",
+  "version": "6.0.22",
   "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; indexes a repo on request (tmct index) or reads any producer's graph.",
@@ -165,10 +165,6 @@
     "serve:public": "node --disable-warning=ExperimentalWarning bin/tmct.mjs serve --host 0.0.0.0 --port 8787",
     "example:mini": "node --disable-warning=ExperimentalWarning bin/tmct.mjs chat --repo examples/mini-webapp --ephemeral",
     "example:polyglot": "node --disable-warning=ExperimentalWarning bin/tmct.mjs chat --repo examples/polyglot --ephemeral",
-    "chatbench:run": "node test-benchmarks/chatbench/run.mjs",
-    "chatbench:judge": "node test-benchmarks/chatbench/judge.mjs",
-    "chatbench:judge:cached": "node test-benchmarks/chatbench/judge.mjs --cache test-benchmarks/chatbench/verdict-cache.json --promoted test-benchmarks/chatbench/promoted.json",
-    "chatbench:distill": "node test-benchmarks/chatbench/distill.mjs",
     "agentbench:run": "node test-benchmarks/agentbench/run.mjs",
     "infbench": "node test-benchmarks/infbench/generate-cases.mjs && node test-benchmarks/infbench/run.mjs",
     "idxbench:run": "node test-benchmarks/idxbench/run.mjs",

package/src/adapters/memory/core.mjs

@@ -122,7 +122,7 @@ export const SOURCE_RELIABILITY_PROP = "mgx:sourceReliability"; // actor-level (
 // per-session Source instead (`${ID}:<sessionId>`, sourceIdFor below).
 export const OPERATOR_SOURCE_ID = "src:operator-chat";
 const TEACH_SOURCE_ID = "src:teach-chat";
-// One Source per peer NODE, keyed by the stable id its relabeled tag carries.
+// One Source per authoring NODE, keyed by the stable id its tag carries.
 const TEACH_NODE_SOURCE_ID = "src:teach-node";
 
 const ROLES = new Set(["visitor", "tmct"]);
@@ -384,11 +384,11 @@ export function factGroupId(recordId) {
 }
 
 /** The record id one provenance tag keys for a triple. A store files an
- *  assertion under the Source its OWN tag derives, and a broadcast relabel
- *  changes that Source — locally a chat session, at the peer the node that
- *  sent it. So two stores hold one assertion under two ids, and anything that
- *  has to name a record ACROSS the wire (a retraction does) resolves the id
- *  through the tag rather than assuming both ends agree. */
+ *  assertion under the Source its OWN tag derives, and a relabelled tag names a
+ *  different Source — locally a chat session, elsewhere the node that authored
+ *  it. So two stores hold one assertion under two ids, and anything that has to
+ *  name a record ACROSS stores (a retraction does) resolves the id through the
+ *  tag rather than assuming both ends agree. */
 export function factRecordIdForTag(groupId, tag) {
   return `${groupId}@${assertionSourceFor(tag).id}`;
 }
@@ -449,7 +449,7 @@ function assertionTimestampFor(tags, fallback = "", pick = Math.max) {
 
 /** Does an incoming assertion replace this source's own current record?
  *  A genuinely newer embedded timestamp does; an exact re-delivery never does,
- *  which is what keeps a re-seed and a duplicate mesh delivery no-ops. Both
+ *  which is what keeps a re-seed and a duplicate delivery no-ops. Both
  *  sides must carry a real embedded timestamp — an unstamped corpus row
  *  asserted a second time is the same hop saying the same thing, not a new
  *  version. The one tie-break: at equal instants a record carrying an
@@ -784,7 +784,6 @@ export async function openSqliteSeedStore(dbPath) {
 const ROW_META_MEMORY_KEY = "memory";
 const ROW_META_PREFIXES_KEY = "prefixes";
 const ROW_SYLLOGISE_STATE_KEY = "syllogiseState";
-const ROW_NODE_ID_KEY = "nodeId";
 
 /** Bind a row backend as a `memoryDir` token: `{ backend: "row", impl,
  *  cachedPayload, basePayload }`. `basePayload` is the read-only seed overlay;
@@ -1398,15 +1397,41 @@ function buildSqlitePayloadFromRows(handle) {
 // ---- handle.cachedPayload mirrors: applied in lockstep with each SQL write
 // so the cache always matches a fresh SQL reconstruction. ----------------
 
+const cacheArrayPositions = new WeakMap();
+
+/** Key -> first position in one of the cache's own arrays, so a mirror finds
+ *  the entry it is about to replace without scanning for it. Every mirror that
+ *  REMOVES entries replaces the array rather than editing it, and the identity
+ *  check here is what stops an index outliving the rows it named. */
+function cachePositionsOf(owner, array, keyOf) {
+  const held = cacheArrayPositions.get(owner);
+  if (held && held.array === array) return held.byKey;
+  const byKey = new Map();
+  for (let i = 0; i < array.length; i += 1) {
+    const key = keyOf(array[i]);
+    if (!byKey.has(key)) byKey.set(key, i);
+  }
+  cacheArrayPositions.set(owner, { array, byKey });
+  return byKey;
+}
+
+const individualIdOf = (ind) => ind?.id;
+
+/** An edge's (subject,object) identity in the cache. NUL-delimited, matching
+ *  the SQL diff beside it — collision-proof, unlike a space. */
+const edgeCacheKey = (e) => `${e?.subject}\u0000${e?.object}`;
+
 /** Mirrors `INSERT OR REPLACE INTO individuals(...)`: an existing id is
  *  replaced IN PLACE (same array position, matching how SQL keeps that row's
  *  `ord` — and so its sort position — unchanged on an update); a new id is
  *  appended (matching a fresh row getting the next `ord`). */
 function cacheUpsertIndividual(cache, ind) {
   const clone = cloneJson(ind);
-  const i = cache.individuals.findIndex((x) => x?.id === ind.id);
-  if (i >= 0) cache.individuals[i] = clone;
-  else cache.individuals.push(clone);
+  const positions = cachePositionsOf(cache, cache.individuals, individualIdOf);
+  const at = positions.get(ind.id);
+  if (at !== undefined) { cache.individuals[at] = clone; return; }
+  positions.set(ind.id, cache.individuals.length);
+  cache.individuals.push(clone);
 }
 
 /** Mirrors `DELETE FROM individuals`: drop every cached individual the write
@@ -1428,23 +1453,31 @@ function cacheGroupFor(cache, prop) {
 
 /** Mirrors `INSERT OR REPLACE INTO edges(...)`: a changed/new row sorts LAST
  *  under `ORDER BY rowid`, so this moves the entry to the end of `examples`
- *  rather than replacing it in place. NUL-delimited (subject,object) key,
- *  matching the SQL diff beside it — collision-proof, unlike a space. */
+ *  rather than replacing it in place. */
 function cacheUpsertEdge(group, edge, extraKeys) {
-  const key = `${edge.subject}\u0000${edge.object}`;
-  group.examples = group.examples.filter((e) => `${e.subject}\u0000${e.object}` !== key);
+  const key = edgeCacheKey(edge);
+  const positions = cachePositionsOf(group, group.examples, edgeCacheKey);
   const cached = {
     subject: edge.subject, object: edge.object,
     subjectLabel: edge.subjectLabel ?? null, objectLabel: edge.objectLabel ?? null,
   };
   if (extraKeys.length) Object.assign(cached, cloneJson(Object.fromEntries(extraKeys.map((k) => [k, edge[k]]))));
+  if (positions.has(key)) {
+    // Rewriting an edge the group already holds moves every position after the
+    // one it vacates, so the array is replaced and the index built again on the
+    // next call rather than patched here.
+    group.examples = group.examples.filter((e) => edgeCacheKey(e) !== key);
+    group.examples.push(cached);
+    return;
+  }
+  positions.set(key, group.examples.length);
   group.examples.push(cached);
 }
 
 /** Mirrors the per-group edge delete loop: drop any cached edge in this group
  *  whose (subject,object) key isn't in the just-persisted group's key set. */
 function cacheDropEdgesExcept(group, newKeys) {
-  group.examples = group.examples.filter((e) => newKeys.has(`${e.subject}\u0000${e.object}`));
+  group.examples = group.examples.filter((e) => newKeys.has(edgeCacheKey(e)));
 }
 
 /** Mirrors `DELETE FROM relations`: drop every cached edge group the write just
@@ -1805,10 +1838,23 @@ function recomputeDerivedTables(ctx, foldSource, headIndex) {
   recordObjectSupersessions(ctx.db, foldCtx, ctx.touchedPairs);
 }
 
+/** How many rows one write may change and still be mirrored into
+ *  `handle.cachedPayload` row by row. Above this the write drops the cache and
+ *  lets the next read rebuild from the tables instead: mirroring clones every
+ *  row it writes into a payload that already holds a copy of the whole store,
+ *  and a corpus import writes tens of thousands of rows in a single call, so
+ *  the mirror costs more than the one rebuild it saves — and holds two copies
+ *  of the seed in memory while it does it. The bar sits well above any
+ *  interactive write (a chat turn, a teach, a world load move rows in the tens
+ *  to low hundreds) so an ordinary session keeps its warm cache. */
+const CACHE_MIRROR_ROW_LIMIT = 2000;
+
 /** Persist a mutated payload into a Backend C handle: the payload projected to
  *  rows, diffed against the rows already stored, and only the difference
- *  written, in one transaction. Patches `handle.cachedPayload` in lockstep; a
- *  rolled-back write invalidates the cache instead of leaving a partial patch.
+ *  written, in one transaction. Patches `handle.cachedPayload` in lockstep,
+ *  unless the write moves more rows than `CACHE_MIRROR_ROW_LIMIT`, where it
+ *  drops the cache instead; a rolled-back write invalidates the cache rather
+ *  than leaving a partial patch.
  *
  *  The 4 KB wire cap the row contract enforces is not applied here: it protects
  *  a network hop, and a local file store holds a seed's whole statedBy group in
@@ -1816,9 +1862,14 @@ function recomputeDerivedTables(ctx, foldSource, headIndex) {
 function persistSqlitePayload(handle, payload) {
   const db = handle.db;
   const empty = emptyMemory();
-  const cache = handle.cachedPayload || null;
   db.exec("BEGIN IMMEDIATE");
   try {
+    const before = sqlitePayloadStoreRows(handle);
+    const { rows: after, partsByKey } = sqlitePayloadRows(payload, before);
+    const { puts, deletes } = diffRows(before, after);
+    const mirrorsIntoCache = puts.length + deletes.length <= CACHE_MIRROR_ROW_LIMIT;
+    const cache = mirrorsIntoCache ? handle.cachedPayload || null : null;
+
     const setMeta = db.prepare("INSERT OR REPLACE INTO meta(k, v) VALUES (?, ?)");
     setMeta.run("generated_at", JSON.stringify(payload.generated_at ?? empty.generated_at));
     setMeta.run("memory", JSON.stringify(payload.memory ?? empty.memory));
@@ -1836,14 +1887,15 @@ function persistSqlitePayload(handle, payload) {
     }
 
     const ctx = sqliteWriteContext(handle, { cache });
-    const before = sqlitePayloadStoreRows(handle);
-    const { rows: after, partsByKey } = sqlitePayloadRows(payload, before);
-    const { puts, deletes } = diffRows(before, after);
     writeSqliteRows(ctx, puts, partsByKey);
     deleteSqliteRows(ctx, deletes);
     recomputeDerivedTables(ctx, payload, handle.cachedFactHeads);
 
     db.exec("COMMIT");
+    if (!mirrorsIntoCache) {
+      handle.cachedPayload = null;
+      handle.cachedFactHeads = null;
+    }
   } catch (e) {
     db.exec("ROLLBACK");
     // The cache may hold a partially-applied patch at this point (some of the
@@ -2361,47 +2413,6 @@ export async function saveSyllogiseState(dir, state) {
   await atomicWriteJson(file, state);
 }
 
-// ---- Node id: the stable per-store P2P identity, a second sidecar ----------
-// 16 hex, minted the first time a store joins a room and never regenerated.
-// Persisted beside the store rather than inside the graph so it survives a
-// store that gets re-seeded, and so nothing about it ever replicates: a node
-// id is this store's own name for itself, not a fact about the world.
-
-export const NODE_ID_REL = join(MEMORY_DIR_REL, "node-id.json");
-const SQLITE_NODE_ID_KEY = "nodeId";
-
-/** This store's node id, or null when it has never joined a room. */
-export async function loadNodeId(dir) {
-  if (isMemoryHandle(dir)) return dir.nodeId || null;
-  if (isSqliteHandle(dir)) {
-    const row = dir.db.prepare("SELECT v FROM meta WHERE k = ?").get(SQLITE_NODE_ID_KEY);
-    return row?.v ? JSON.parse(row.v).nodeId || null : null;
-  }
-  if (isRowHandle(dir)) return (await readRowMeta(dir, ROW_NODE_ID_KEY, null))?.nodeId || null;
-  try {
-    return JSON.parse(await readFile(join(dir, NODE_ID_REL), "utf8")).nodeId || null;
-  } catch (e) {
-    if (e?.code === "ENOENT") return null;
-    throw e;
-  }
-}
-
-/** Record this store's node id — atomic file write (Backend A), a handle field
- *  (Backend B), a meta-table row (Backend C), or a meta value in the injected
- *  store (Backend D). Callers mint through resolveStoreNodeId, which never
- *  overwrites an id a store already holds, so this value is written once. */
-export async function saveNodeId(dir, nodeId) {
-  if (isMemoryHandle(dir)) { dir.nodeId = nodeId; return; }
-  if (isSqliteHandle(dir)) {
-    dir.db.prepare("INSERT OR REPLACE INTO meta(k, v) VALUES (?, ?)").run(SQLITE_NODE_ID_KEY, JSON.stringify({ nodeId }));
-    return;
-  }
-  if (isRowHandle(dir)) { await dir.impl.putMeta(ROW_NODE_ID_KEY, JSON.stringify({ nodeId })); return; }
-  const file = join(dir, NODE_ID_REL);
-  await mkdir(dirname(file), { recursive: true });
-  await atomicWriteJson(file, { nodeId });
-}
-
 /** Fresh read -> mutate -> atomic write. Serialized per call; every public
  *  append goes through here, including the lazy legacy-provenance migration
  *  and actor-level Source reliability recompute. `fn` may be async (the
@@ -2685,11 +2696,11 @@ function sourceIdFor(desc) {
   switch (desc?.kind) {
     case "operator": return { id: desc.sessionId ? `${OPERATOR_SOURCE_ID}:${desc.sessionId}` : OPERATOR_SOURCE_ID, type: "operator" };
     case "teach": return { id: desc.sessionId ? `${TEACH_SOURCE_ID}:${desc.sessionId}` : TEACH_SOURCE_ID, type: "teach" };
-    // One Source per peer NODE, keyed on the stable id the tag carries rather
-    // than the display name beside it: names are user-chosen and collidable, so
-    // two peers who picked the same one would otherwise collapse into a single
-    // Source and corroborate each other for free. Scores at the teach tier —
-    // a peer teaching is still a person telling us something.
+    // One Source per authoring NODE, keyed on the stable id the tag carries
+    // rather than the display name beside it: names are user-chosen and
+    // collidable, so two nodes that picked the same one would otherwise collapse
+    // into a single Source and corroborate each other for free. Scores at the
+    // teach tier — a node teaching is still a person telling us something.
     case "teachNode": return { id: `${TEACH_NODE_SOURCE_ID}:${desc.nodeId}`, type: "teach" };
     case "provider": return { id: `src:provider:${desc.name}`, type: "provider" };
     case "corpus": return { id: `src:corpus:${desc.name}`, type: "corpus" };
@@ -2861,11 +2872,11 @@ function migrateLegacyProvenance(payload) {
 }
 
 /** A Source id that names one actor and can therefore hold a track record —
- *  the `${SINGLETON}:<id>` shape, for a local operator/teach session or for a
- *  peer NODE across the mesh. A corpus/web/provider/entailed Source names a
- *  document or a derivation, so there is no actor to score.
+ *  the `${SINGLETON}:<id>` shape, for a local operator/teach session or for
+ *  another NODE that authored the tag. A corpus/web/provider/entailed Source
+ *  names a document or a derivation, so there is no actor to score.
  *
- *  A peer node counts for the same reason a local session does, and it is the
+ *  Another node counts for the same reason a local session does, and it is the
  *  reason this matters most: a node that asserts junk drags its own every-fact
  *  prior toward half, so minting fresh identities to corroborate yourself stops
  *  being free the moment any of those claims is contradicted. */
@@ -2978,7 +2989,7 @@ function recomputeSourceReliability(payload) {
 /**
  * Two rollup summaries at one id JOIN instead of overwriting: union the ids
  * they absorbed, then re-derive count, bounds and prior from that union. This
- * is what lets two peers that compacted the same group at different moments
+ * is what lets two stores that compacted the same group at different moments
  * converge — union, min and max are all joins, so the result is the same in
  * either order and applying it twice changes nothing. Re-writing a summary that
  * already holds everything the incoming one does is therefore a no-op, which is
@@ -3210,12 +3221,12 @@ function assertionGroupsFor(payload, groupId, provenance, createdAt = "") {
   if (groups.length === 1 && groups[0].sourceId === NO_SOURCE_ID) {
     if (factRecordIdsFor(payload, groupId).length) return [];
   }
-  // A source whose assertion was retracted here does not come back on the next
-  // sync. This is the ingest half of the enforcement: every delivery path for a
-  // fact lands in this function, so a re-sent copy of a retracted assertion is
-  // recognized and dropped rather than re-materialized. The comparison is
-  // against the assertion's OWN embedded instant, so the same source saying the
-  // thing again — a fresh tag, a later moment — still lands.
+  // A source whose assertion was retracted here does not come back the next
+  // time those rows land. This is the ingest half of the enforcement: every
+  // delivery path for a fact lands here, so a re-sent copy of a retracted
+  // assertion is recognized and dropped rather than re-materialized. The
+  // comparison is against the assertion's OWN embedded instant, so the same
+  // source saying the thing again — a fresh tag, a later moment — still lands.
   const retractions = retractionsFor(payload, groupId);
   if (retractions.length) {
     groups = groups.filter((group) => !isRetractedRecord(
@@ -3327,7 +3338,7 @@ function normalizeExtractionFindings(extraction) {
  *     record it replaces kept whole under `#v<n>` and linked both ways;
  *   - the same source saying the same thing again: its tags union onto the head
  *     and its first write's stamps stand. An exact re-delivery changes nothing,
- *     which is what keeps a re-seed and a duplicate mesh path idempotent.
+ *     which is what keeps a re-seed and a duplicate delivery path idempotent.
  */
 function planFactAssertion(payload, spec) {
   const { groupId, s, p, o, label, tokens, group, createdAt, observedAt, quantifier, environments, extraction = [] } = spec;
@@ -4163,10 +4174,10 @@ export async function foldedFactRows(dir) {
  *
  *  The rows come out in content order, not in the order the payload happened to
  *  hold them. A reader that takes the first of several equally-ranked rows, or
- *  sorts by a key that ties, otherwise answers by arrival order — and two peers
+ *  sorts by a key that ties, otherwise answers by arrival order — and two stores
  *  holding one fact set arrive at it differently. Sorting here is what lets a
  *  reader inherit the guarantee instead of re-earning it: the fold is the one
- *  place every fact read passes through. p2p-room.mjs's sortFactIndividualsById
+ *  place every fact read passes through. rows.mjs's sortFactIndividualsById
  *  does the same job one level down, over the stored records. */
 function foldFactRows(memory, ctx, opts = {}) {
   // A materialised head, when the backend keeps one, replaces the group's own
@@ -4218,7 +4229,7 @@ const FACT_ID_PREFIX = "fact:";
  *  Pure: the speakers come back sorted, so a claim two outlets attributed reads
  *  the same whichever order the attributions arrived in, and an attribution
  *  whose claim the fold never saw simply hangs on nothing — which is the case
- *  every time rows arrive over p2p out of order. */
+ *  every time rows arrive out of order. */
 function attachSpeakers(rows) {
   // An attribution names its claim as its SUBJECT, and a claim's own subject is
   // a term, so the prefix rules nearly every row out on one comparison. The
@@ -4304,11 +4315,11 @@ function factFoldContext(memory, { pairs = null, scopedGroups = new Set() } = {}
     else groups.set(groupId, [ind]);
   }
 
-  // The read half of retraction enforcement. A record a peer re-delivered before
-  // its retraction arrived is still sitting in the payload, and this is what
-  // keeps it out of the answer: the fold is a pure function of the fact set, so
-  // both peers read the same row whichever order the two arrived in. Only a
-  // group that actually carries a retraction pays anything for the check.
+  // The read half of retraction enforcement. A record re-delivered before its
+  // retraction arrived is still sitting in the payload, and this is what keeps
+  // it out of the answer: the fold is a pure function of the fact set, so both
+  // stores read the same row whichever order the two arrived in. Only a group
+  // that actually carries a retraction pays anything for the check.
   for (const [groupId, retractions] of retractionsByGroup) {
     const members = groups.get(groupId);
     if (!members) continue;
@@ -4323,7 +4334,7 @@ function factFoldContext(memory, { pairs = null, scopedGroups = new Set() } = {}
   }
 
   // Codepoint order on the record id, which sorts by source key — the same
-  // locale-free determinism the P2P layer's own sort insists on, so two peers
+  // locale-free determinism rows.mjs's own sort insists on, so two stores
   // holding the same records read the same row.
   for (const members of groups.values()) members.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 
@@ -4566,8 +4577,8 @@ function factGroupsReferencing(payload, goneGroupIds) {
  *
  *  The delete leaves a RETRACTION RECORD behind, one per (triple, source),
  *  carrying the record ids it suppressed and the moment it did. That record is
- *  what makes the retraction survive a sync: a plain delete against a grow-only
- *  set comes straight back from any peer that still holds the fact. It also
+ *  what makes the retraction survive a merge: a plain delete against a grow-only
+ *  set comes straight back from any store that still holds the fact. It also
  *  keeps the retraction on record rather than erasing the fact that something
  *  was asserted at all. A retraction record is never itself removed here.
  *
@@ -4673,8 +4684,9 @@ export async function removeFacts(dir, ids, { provenance = "", retractedAt = ""
 }
 
 /** Every retraction record the store holds, as the wire facts that carry them.
- *  The P2P layer's own diff and sync response read this: a retraction is not a
- *  fact row, so nothing that walks readFactRows would ever find one. */
+ *  Anything that ships one store's retractions to another reads this: a
+ *  retraction is not a fact row, so nothing that walks readFactRows would ever
+ *  find one. */
 export function readRetractions(memory) {
   const out = [];
   for (const ind of memory?.individuals || []) {
@@ -4734,12 +4746,12 @@ export async function appendRetractions(dir, wireFacts) {
 /** What this store could retire, and the roster it has to convince first.
  *
  *  `roster` is the world's admission graph, folded to a set of node ids —
- *  replicated, grow-only, and the same on every peer holding the same facts.
- *  `retirable` is the tombstones every peer on that roster is known to hold.
+ *  replicated, grow-only, and the same on every replica holding the same facts.
+ *  `retirable` is the tombstones every node on that roster is known to hold.
  *  `acknowledgedBy(nodeId)` is what supplies that evidence; nothing produces it
  *  yet, so `retirable` reads empty and this is a report rather than a sweep.
  *  Retiring nothing is the current behaviour, and it is the safe one: a
- *  tombstone dropped one peer early lets that peer's copy resurrect a retracted
+ *  tombstone dropped one node early lets that node's copy resurrect a retracted
  *  fact. See docs/references/papers/crdt.md. */
 export function retirableRetractions(memory, { self = "", acknowledgedBy = null } = {}) {
   const roster = admittedNodes(readFactRows(memory));

package/src/domain/agent-traits.mjs

@@ -15,7 +15,7 @@
 //
 // Every list this module returns is sorted in codepoint order before it is
 // returned, and every resolver here is a pure function of the row SET, never
-// of the order the rows arrived in — the same rule p2p-room.mjs's
+// of the order the rows arrived in — the same rule rows.mjs's
 // sortFactIndividualsById holds for a merged fact store, so two callers who
 // built the same rows in different orders never read a different answer.
 

package/src/domain/answer-variants.json

@@ -10,7 +10,7 @@
         "ask.mjs metaFallbackEntityAnswer (\"X is a Y in this codebase, defined in Z ...\")"
       ],
       "deliberatelyNotUsedBy": [
-        "ask.mjs renderCore whereShape (\"X is defined in Y at line(s) Z\" / \"X is defined in Y (no line span...)\") -- test-benchmarks/chatbench/graded-pool-max.jsonl pins this exact substring as ground truth for 11 'where is X defined' cases (2 in the always-run promoted subset), and that pool is append-only/never-edited-mid-arc per .claude/skills/benchmark-cefr-english/SKILL.md."
+        "ask.mjs renderCore whereShape (\"X is defined in Y at line(s) Z\" / \"X is defined in Y (no line span...)\") -- the grammar, messy-user, compositional and drilldowns corpus lanes pin this exact substring as ground truth for 'where is X defined', so varying it there breaks those rows."
       ]
     },
     "is-dated": {

package/src/domain/cli-verbs.mjs

@@ -38,6 +38,7 @@ export const CLI_VERBS = [
       { flag: "[--plain]", prose: ["force the plain readline shell (the default when", "stdin/stdout is not a terminal)"] },
       { flag: "[--memory-backend <default|memory|sqlite>]", prose: ["storage backend for taught facts this", "session (CLI flag > TMCT_MEMORY_BACKEND env > tmct.toml's", "[memory] backend > sqlite, .tmct/memory/graph.sqlite)"] },
       { flag: "[--research-source <wikipedia|wikidata|simple-wikipedia-pack>]", prose: ["where \"research <topic>\" fetches from this session", "(/wikipedia|/wikidata in chat > this flag > tmct.toml's", "[research] source > wikipedia)"] },
+      { flag: "[--code-graph]", prose: ["read every line as a question about the code graph", "(default off, and never inferred; also TMCT_CODE_GRAPH=1;", "toggle mid-session with /code-graph on|off)"] },
     ],
   },
   {

package/src/domain/memory/causal-stability.mjs

@@ -9,13 +9,13 @@
 //
 // The literature calls the missing rule CAUSAL STABILITY: a record is safe to
 // drop once every replica that could still send a conflicting copy has it. Two
-// inputs, and the mesh has one of them.
+// inputs.
 //
 //   - The ROSTER. `node:<joiner> mgx:invitedBy node:<inviter>` is an ordinary
 //     replicated fact, so the set of node ids ever admitted to a world is a
-//     grow-only union every peer computes the same way. `admittedNodes` reads
-//     it. Grow-only is exactly right here: a roster that could shrink would let
-//     a forgotten node's stale copy back in.
+//     grow-only union every replica computes the same way. `admittedNodes`
+//     reads it. Grow-only is exactly right here: a roster that could shrink
+//     would let a forgotten node's stale copy back in.
 //   - The ACKNOWLEDGEMENT. Nothing yet records that a named node holds a named
 //     record. `stableRecordIds` takes it as an argument rather than inventing
 //     it, and answers "nothing is stable" when it is absent — which is the
@@ -32,7 +32,24 @@
 // invariant every read-time resolver over the store has to meet.
 // docs/references/papers/crdt.md carries the full design and the options it
 // rejected.
-import { INVITED_BY_PREDICATE } from "../p2p/facts.mjs";
+
+export const INVITED_BY_PREDICATE = "mgx:invitedBy";
+
+/** The term a node id takes as a fact subject or object. */
+export const nodeTerm = (nodeId) => `node:${nodeId}`;
+
+/** One admission edge: who let a node in. There is no open discovery here, so
+ *  this records a social admission graph that an identity cannot mint for
+ *  itself. The joiner writes it, because the joiner is the only side that
+ *  knows both node ids at the moment it decides to join. */
+export function invitedByFact(joinerNodeId, inviterNodeId, timestamp) {
+  return {
+    subject: nodeTerm(joinerNodeId),
+    predicate: INVITED_BY_PREDICATE,
+    object: nodeTerm(inviterNodeId),
+    provenance: `ace:p2p:${joinerNodeId}@${timestamp}`,
+  };
+}
 
 /** The node ids a world has ever admitted, from its admission edges. Both ends
  *  of each edge count: the joiner wrote the edge about itself, and it names the

package/src/domain/memory/fact-order.mjs

@@ -12,9 +12,9 @@
 // key. Codepoint order throughout, never localeCompare — two locales have to
 // land on the same order.
 //
-// The store's own precedent is p2p-room.mjs's sortFactIndividualsById, which
-// sorts Fact individuals by content-addressed id after every merge for exactly
-// this reason. This is that discipline carried through to the read side.
+// The store's own precedent is rows.mjs's sortFactIndividualsById, which sorts
+// Fact individuals by content-addressed id after every merge for exactly this
+// reason. This is that discipline carried through to the read side.
 
 /** A fact row's content-derived sort key. */
 export const factOrderKey = (f) => [