@polycode-projects/the-mechanical-code-talker 1.9.1 → 1.10.0

package/src/router/results.mjs

@@ -0,0 +1,231 @@
+// src/router/results.mjs — the RESULT-EXECUTION layer for the capability router.
+//
+// Grading (and the live `tmct plan` surface) needs more than a call PLAN — it
+// needs the executed, COMPOSED answer: an "of the modules impacted by X, which
+// are untested" request passes by emitting tmct_impact then tmct_untested IN
+// ORDER, but the actual set-intersection still has to be computed and checked.
+// This module supplies that, in two halves, both PURE over the parsed graph
+// (no I/O, no Date.now, no LLM):
+//
+//   1. resultSetOf(graph, name, input, resolvedInd) — the STRUCTURED RESULT of a
+//      single grounded call: the SET of entity LABELS the query produces (the
+//      impacted modules, the untested modules, the callers, the members, …),
+//      computed from the SAME codegraph primitives dispatchTool renders as text.
+//      A driver threads this onto ctx.dispatch's return (`result`) — the
+//      structured payload a composer reads. It is the machine-checkable twin of
+//      the human text a tool_result carries.
+//
+//   2. the COMPOSITION OPERATORS — intersect / fallback-if-empty / guard-if-empty
+//      (set-algebra.mjs) — the small set-algebra a multi-step plan needs to fold
+//      its threaded step results into ONE composed answer. A driver picks the
+//      operator from the router's OWN HTN method (relative-filter -> intersect;
+//      conditional -> fallback/guard).
+//
+// Why recompute here rather than parse the rendered text: the text is capped and
+// human-formatted (renderImpact caps lists "for brevity"); the label SET is the
+// honest, uncapped truth the composition needs. These extractors mirror the
+// dispatchTool render* functions edge-for-edge.
+
+import { impactClosure, edgesOfKind, siteOf } from "../codegraph.mjs";
+import { uniqSort } from "./set-algebra.mjs";
+
+// A test-path label, mirroring codegraph.mjs's private isTestLabel (untested view).
+const isTestLabel = (s) =>
+  /(^|\/)tests?\//.test(s) || /(^|\/)test_[^/]*\.py$/.test(s) || /\.tests(\.|$)/.test(s);
+
+/** The module id an individual belongs to — a Module is itself; a fine symbol maps
+ *  through its site span (`mod:<path>`), else an `fn:<path>#name` id. Mirrors the
+ *  private codegraph.moduleIdOf so tests_for/history resolve to the same key
+ *  dispatchTool uses. Null if unmappable. */
+function moduleIdOf(graph, ind) {
+  if ((ind?.class || "") === "Module") return ind.id;
+  const site = siteOf(ind);
+  if (site) return `mod:${site.path}`;
+  const m = String(ind?.id || "").match(/^fn:(.+)#/);
+  return m ? `mod:${m[1]}` : null;
+}
+
+// ---- per-tool structured result sets (label sets), mirroring render* ----------
+
+/** Source modules with no covering test module (mirrors renderUntested). */
+export function untestedModules(graph) {
+  const covered = new Set();
+  const testModules = new Set();
+  for (const e of edgesOfKind(graph, "tests")) { covered.add(e.object); testModules.add(e.subject); }
+  return uniqSort(
+    graph.individuals
+      .filter((i) => (i.class || "") === "Module"
+        && !testModules.has(i.id)
+        && !isTestLabel(String(i.label).toLowerCase())
+        && !covered.has(i.id))
+      .map((i) => i.label),
+  );
+}
+
+/** The reverse impact closure of a module — every transitive dependent's label
+ *  (mirrors renderImpact/impactClosure, uncapped). */
+export function impactLabels(graph, ind) {
+  const labels = [];
+  for (const level of impactClosure(graph, ind)) for (const dep of level) labels.push(dep.label);
+  return uniqSort(labels);
+}
+
+/** The test modules covering a symbol's module (mirrors renderTestsFor). [] = untested. */
+export function testsForLabels(graph, ind) {
+  const modId = moduleIdOf(graph, ind);
+  if (!modId) return [];
+  return uniqSort(edgesOfKind(graph, "tests").filter((e) => e.object === modId).map((e) => e.subjectLabel || e.subject));
+}
+
+/** The methods/attributes of a class (mirrors renderMembers — the `contains` edge). */
+export function membersLabels(graph, ind) {
+  return uniqSort(edgesOfKind(graph, "contains").filter((e) => e.subject === ind.id).map((e) => e.objectLabel || e.object));
+}
+
+const CALL_SYMBOL_CLASSES = new Set(["Function", "Method"]);
+
+/** The member INDIVIDUALS of a class — the contains-edge object IDS mapped
+ *  through a by-id index of graph.individuals to the FULL individuals (dotted
+ *  labels like Widget.render, real classes like Method/Attribute). This is the
+ *  GRAIN FIX the member-filter hop needs: the contains edge's objectLabel is the
+ *  short member name ("render"), but the call graph (callsSymbol) and the
+ *  tmct_callees arg both speak the individual's own dotted label — so we index
+ *  to the individual and read ITS label, never string-concatenate one. */
+export function memberIndividuals(graph, classInd) {
+  const byId = new Map(graph.individuals.map((i) => [i.id, i]));
+  return edgesOfKind(graph, "contains")
+    .filter((e) => e.subject === classInd.id)
+    .map((e) => byId.get(e.object))
+    .filter(Boolean);
+}
+
+/** Members of a class (Method|Function grain only) whose BOUNDED transitive
+ *  callsSymbol closure reaches the target label — the member-filter fold
+ *  ("which methods of X end up calling Y"). Depth-bounded BFS over the fine
+ *  call graph (maxDepth mirrors the planner/subclasses bound); an unknown
+ *  target composes ∅ (an honest empty answer, never a guess). */
+export function membersReaching(graph, classInd, targetLabel, maxDepth = 8) {
+  const target = graph.individuals.find((i) => String(i.label) === String(targetLabel));
+  if (!target) return [];
+  const out = new Map();
+  for (const e of edgesOfKind(graph, "callsSymbol")) {
+    if (!out.has(e.subject)) out.set(e.subject, []);
+    out.get(e.subject).push(e.object);
+  }
+  const reaches = (startId) => {
+    const visited = new Set([startId]);
+    let frontier = [startId];
+    for (let depth = 1; depth <= maxDepth && frontier.length; depth += 1) {
+      const next = [];
+      for (const id of frontier) {
+        for (const o of out.get(id) || []) {
+          if (o === target.id) return true;
+          if (!visited.has(o)) { visited.add(o); next.push(o); }
+        }
+      }
+      frontier = next;
+    }
+    return false;
+  };
+  return uniqSort(
+    memberIndividuals(graph, classInd)
+      .filter((m) => CALL_SYMBOL_CLASSES.has(m.class))
+      .filter((m) => reaches(m.id))
+      .map((m) => m.label),
+  );
+}
+
+/** Callers of a symbol (mirrors renderCallers — callsSymbol for fine symbols,
+ *  else module-coarse calls). */
+export function callersLabels(graph, ind) {
+  if (CALL_SYMBOL_CLASSES.has(ind.class)) {
+    return uniqSort(edgesOfKind(graph, "callsSymbol").filter((e) => e.object === ind.id).map((e) => e.subjectLabel || e.subject));
+  }
+  const modId = moduleIdOf(graph, ind);
+  if (!modId) return [];
+  return uniqSort(edgesOfKind(graph, "calls").filter((e) => e.object === modId).map((e) => e.subjectLabel || e.subject));
+}
+
+/** Callees of a symbol (mirrors renderCallees). */
+export function calleesLabels(graph, ind) {
+  if (CALL_SYMBOL_CLASSES.has(ind.class)) {
+    return uniqSort(edgesOfKind(graph, "callsSymbol").filter((e) => e.subject === ind.id).map((e) => e.objectLabel || e.object));
+  }
+  const modId = moduleIdOf(graph, ind);
+  if (!modId) return [];
+  return uniqSort(edgesOfKind(graph, "calls").filter((e) => e.subject === modId).map((e) => e.objectLabel || e.object));
+}
+
+/** Subclasses (transitive) of a class (mirrors renderSubclasses closure). */
+export function subclassesLabels(graph, ind) {
+  const inherits = edgesOfKind(graph, "inherits");
+  const childrenOf = new Map();
+  for (const e of inherits) {
+    if (!childrenOf.has(e.object)) childrenOf.set(e.object, []);
+    childrenOf.get(e.object).push({ id: e.subject, label: e.subjectLabel || e.subject });
+  }
+  const labels = [];
+  const visited = new Set([ind.id]);
+  let frontier = [ind.id];
+  for (let depth = 1; depth <= 8 && frontier.length; depth += 1) {
+    const next = [];
+    for (const id of frontier) {
+      for (const c of childrenOf.get(id) || []) {
+        if (visited.has(c.id)) continue;
+        visited.add(c.id);
+        labels.push(c.label);
+        next.push(c.id);
+      }
+    }
+    frontier = next;
+  }
+  return uniqSort(labels);
+}
+
+/** Modules change-coupled with a symbol's module (mirrors renderCochanges /
+ *  cochangeNeighbours EDGE-FOR-EDGE: the `cochange` edge is read SYMMETRICALLY —
+ *  a hit whether the module is the edge's subject OR its object). The render
+ *  caps at 20 for brevity; this is the uncapped honest label SET). */
+export function cochangesLabels(graph, ind) {
+  const modId = moduleIdOf(graph, ind);
+  if (!modId) return [];
+  const labels = [];
+  for (const e of edgesOfKind(graph, "cochange")) {
+    if (e.subject === modId) labels.push(e.objectLabel || e.object);
+    else if (e.object === modId) labels.push(e.subjectLabel || e.subject);
+  }
+  return uniqSort(labels);
+}
+
+/** A module's public exports (mirrors renderExports — the `reexports` edge). */
+export function exportsLabels(graph, ind) {
+  const modId = moduleIdOf(graph, ind);
+  if (!modId) return [];
+  return uniqSort(edgesOfKind(graph, "reexports").filter((e) => e.subject === modId).map((e) => e.objectLabel || e.object));
+}
+
+/** The STRUCTURED RESULT SET of one grounded call — the label set the query
+ *  produces, for the composer to thread. `resolvedInd` is the bound entity
+ *  (ctx.dispatch's `resolved`); a no-arg tool (untested) ignores it. A tool with
+ *  no set semantics returns the bound entity itself as a singleton (describe /
+ *  signature — "the thing looked up"). Never throws: an unbindable call already
+ *  refused upstream, so this is only reached on a grounded call. */
+export function resultSetOf(graph, name, _input, resolvedInd) {
+  switch (name) {
+    case "tmct_untested": return untestedModules(graph);
+    case "tmct_impact": return resolvedInd ? impactLabels(graph, resolvedInd) : [];
+    case "tmct_tests_for": return resolvedInd ? testsForLabels(graph, resolvedInd) : [];
+    case "tmct_members": return resolvedInd ? membersLabels(graph, resolvedInd) : [];
+    case "tmct_callers": return resolvedInd ? callersLabels(graph, resolvedInd) : [];
+    case "tmct_callees": return resolvedInd ? calleesLabels(graph, resolvedInd) : [];
+    case "tmct_subclasses": return resolvedInd ? subclassesLabels(graph, resolvedInd) : [];
+    case "tmct_cochanges": return resolvedInd ? cochangesLabels(graph, resolvedInd) : [];
+    case "tmct_exports": return resolvedInd ? exportsLabels(graph, resolvedInd) : [];
+    default: return resolvedInd ? [resolvedInd.label] : [];
+  }
+}
+
+// ---- the composition operators (the multi-step fold) -------------------------
+// Re-exported here (uniqSort included) so a caller can get both halves from one
+// module; they LIVE in set-algebra.mjs.
+export { uniqSort, intersect, fallbackIfEmpty, guardIfEmpty } from "./set-algebra.mjs";

package/src/schema-docs.mjs

@@ -1,25 +1,11 @@
-// schema-docs.mjs — the single source of truth for tmct's own ontology documentation.
+// schema-docs.mjs — the single source of truth for tmct's own ontology documentation:
+// every entity class and predicate tmct's typed graph (src/graph-build.mjs's
+// buildEntities) actually emits, verified against real `prop:`/`class:` literals.
+// `ingestSchemaDocs()` merges it into a graph build so "what does cochange mean" or
+// "what is a Commit" is answerable by querying the graph like any other question.
 //
-// tmct's typed graph (src/graph-build.mjs's buildEntities, queried by codegraph.mjs)
-// has had its schema documented since day one, but only in scattered code comments
-// (graph-build.mjs's header, the `note` fields on some — not all — of the `vocabulary`
-// array entries it emits) — readable by a human editing the source, invisible to anything
-// that only sees graph.json. This file completes that documentation (every entity class,
-// every predicate actually emitted — verified against real `prop:`/`class:` literals in
-// graph-build.mjs, not just what the existing vocabulary array already claimed) and
-// `ingestSchemaDocs()` (called by a graph writer after buildEntities) merges it
-// into a graph build so a question like "what does cochange mean" or "what is a
-// Commit" is answerable by querying the SAME graph the same way any other question is —
-// not via separate hardcoded documentation logic.
-//
-// GLOBAL, NOT PER-REPO: this documentation does not vary by repository — "Module" means
-// the same thing indexing Django or a JS library — so it is static, committed data
-// (this file), never recomputed at index time. Ingesting it is a fixed-size merge, not a
-// computation (see the ~0ms measured delta in schema-docs.test.mjs).
-//
-// Mirrors the pattern in marginalia's app/lib/vocab.mjs (a `comment`/description per
-// schema term, single-sourced) minus the RDF/OWL external-alignment machinery, which
-// doesn't apply here — tmct's schema is code-relationship-specific, not general-domain.
+// GLOBAL, NOT PER-REPO: this documentation doesn't vary by repository, so it's static,
+// committed data, never recomputed at index time.
 
 // ---- entity classes (7 — verified against every `class: "X"` individual literal in
 // graph-build.mjs) -----------------------------------------------------------------------
@@ -58,9 +44,7 @@ export const CLASS_DOCS = Object.freeze([
 ]);
 
 // ---- predicates / attributes (every `prop:` token actually emitted by buildEntities,
-// verified by grep against graph-build.mjs — not just what the pre-existing `vocabulary`
-// array already documented; three real gaps found this way: seon:startsAt, mgx:value,
-// mgx:dotted, plus the prose second-pass's mgx:hasProseTokens) ------------------------
+// verified against graph-build.mjs) ----------------------------------------------------
 export const PREDICATE_DOCS = Object.freeze([
   // ---- object properties (edges between individuals) ----
   { prop: "mgx:importsNamespace", kind: "imports", description:
@@ -110,9 +94,8 @@ export const PREDICATE_DOCS = Object.freeze([
   { prop: "mgx:hasProseTokens", kind: "prose", description:
     "Individual → word tokens (an attribute, not a between-individuals edge). The " +
     "decomposed word sequence extracted from an identifier's name (camelCase/snake_case " +
-    "split) and any doc-comment prose, used by the second-pass prose-to-symbol " +
-    "cross-reference index (PLAN_PROSE_INDEX.md) to resolve free-text object terms that " +
-    "don't exact-match an identifier." },
+    "split) and any doc-comment prose, used by the prose-to-symbol cross-reference index " +
+    "to resolve free-text object terms that don't exact-match an identifier." },
 
   // ---- attributes (individual-scoped facts, not edges) ----
   { prop: "seon:startsAt", kind: "attribute", description:

package/src/server-http.mjs

@@ -1,27 +1,18 @@
 // server-http.mjs — `tmct serve`: an Anthropic Messages API-compatible HTTP
 // endpoint (POST /v1/messages) over tmct's existing zero-model engine.
 //
-// This is Phase A of the capability-router plan (PLAN_CAPABILITY_ROUTER.md): the
-// COMMON INTERFACE a tool-loop client (Claude Code) already speaks. It is a
-// deterministic serialization/HTTP shim — NO model, ever. A request carries
-// { model, messages[], tools[], max_tokens, system? }; a response is a message
-// with `content` blocks (text and/or tool_use) and a `stop_reason`:
+// A deterministic serialization/HTTP shim — no model, ever. A request carries
+// { model, messages[], tools[], max_tokens, system? }; a response is a message with
+// `content` blocks and a `stop_reason`: "end_turn" runs the latest user text through
+// runTurn (chat.mjs) for a cited read-only answer; "tool_use" emits a
+// { type:"tool_use", id, name, input } block backed by dispatchTool (server.mjs) when
+// the request maps to a declared graph-query tool.
 //
-//   - TEXT ANSWER (stop_reason "end_turn"): the latest user text is run through
-//     runTurn (src/chat.mjs) over the configured graph — the same cited,
-//     read-only answer the chat surface gives. Emitted when no tools are
-//     declared, or when nothing maps to a declared graph-query tool.
-//   - TOOL_USE (stop_reason "tool_use"): when tools[] are declared and the
-//     request maps to a declared graph-query tool, a { type:"tool_use", id,
-//     name, input } block is emitted — `name`+`input` are backed by dispatchTool
-//     (src/server.mjs). The caller executes it and returns a tool_result block;
-//     the next request closes the loop with an end_turn text answer.
+// Every response's `usage` is { input_tokens: 0, output_tokens: 0 } — tmct is the $0
+// floor, priced as free by the meter.
 //
-// bedrock-meter-pluggable: every response's `usage` is { input_tokens: 0,
-// output_tokens: 0 } — tmct is the $0 floor, priced as free by the meter.
-//
-// NOTE: src/server.mjs is the TOOL-DISPATCH layer (dispatchTool), NOT an HTTP
-// server; this module is the HTTP surface and imports that layer's exports.
+// src/server.mjs is the tool-dispatch layer, not an HTTP server; this module is the
+// HTTP surface.
 
 import { createServer } from "node:http";
 import { runTurn, COMMANDS, asBareCommand, isConversational } from "./chat.mjs";

package/src/server.mjs

@@ -5,7 +5,7 @@
 // the chat surface and the `cli <tool>` route call into.
 //
 // Tools (all query-only, bounded output): tmct_search, tmct_describe, tmct_snippet,
-// tmct_impact, plus the §9 read-replacing tools tmct_members, tmct_subclasses,
+// tmct_impact, plus the read-replacing tools tmct_members, tmct_subclasses,
 // tmct_architecture, tmct_tests_for, tmct_untested, tmct_history, tmct_callers,
 // tmct_callees. Each answers one question in ONE compact call so the caller need not
 // Read/Grep. Errors reach the caller as clean tool errors — message only, never a stack.
@@ -50,11 +50,9 @@ import {
 } from "./codegraph.mjs";
 import { ask } from "./ask.mjs";
 import { createGraphService } from "./providers/graph-service.mjs";
-// Read-ONLY consumers of the conversational-memory graph (src/memory/core.mjs) — the 500
-// corpus facts live there, NOT in the code-map graph.json every tool below loads. Used by
-// the FALL-THROUGH bridge (below): when the code-map resolves NOTHING for a concept query
-// (/subclasses /describe /members /find), answer from the reified isa-family facts instead
-// of a flat "no entity". Never written here; memory writes stay owned by memory/*.
+// Read-only consumers of the conversational-memory graph (corpus facts, separate from
+// the code-map graph.json). Used by the fall-through bridge below: when the code-map
+// resolves nothing for a concept query, answer from the reified isa-family facts instead.
 import { loadMemory, readFactRows, normFactTerm } from "./memory/core.mjs";
 
 const SNIPPET_MAX_LINES = 200;
@@ -162,13 +160,12 @@ export const TOOLS = [
   },
 ];
 
-// Exported (was module-private) so chat.mjs's compare lane can load the SAME
-// graph dispatchTool's own tools load — no new loading path, just direct reuse
-// of the existing config -> source.fetchEntities -> parseEntities chain, for
-// the case where runAsk's own `graph` param is null (the common case; it's
-// only preloaded when a caller already has one in hand — see runAsk's own
-// `if (graph && ...)` / dispatchTool("tmct_ask", …) split just above the
-// compare lane's call site for the existing precedent).
+// Exported so chat.mjs's compare lane can load the SAME graph dispatchTool's
+// own tools load — no new loading path, just direct reuse of the existing
+// config -> source.fetchEntities -> parseEntities chain, for the case where
+// runAsk's own `graph` param is null (the common case; it's only preloaded
+// when a caller already has one in hand — see runAsk's own `if (graph && ...)`
+// / dispatchTool("tmct_ask", …) split just above).
 export async function loadGraph(config, source) {
   const payload = await source.fetchEntities(config);
   const graph = parseEntities(payload);
@@ -183,11 +180,8 @@ export async function loadGraph(config, source) {
   return graph;
 }
 
-// Resolution + the miss→ToolError bridge, threaded through the typed service
-// object (createGraphService). The service is the named seam; tmct's own
-// presentation (render*) reads its raw graph (svc.graph) and formats. A clean
-// miss on the interface becomes the instructive ToolError the CLI/chat expect —
-// message-only, never a stack, no fabricated entity names (generic placeholder).
+// A clean miss on the interface becomes the instructive ToolError the CLI/chat expect —
+// message-only, never a stack, no fabricated entity names.
 function resolveOrThrow(svc, symbol, what) {
   const { match, candidates } = resolveSymbol(svc.graph, symbol);
   if (!match) {
@@ -201,14 +195,14 @@ function resolveOrThrow(svc, symbol, what) {
 
 /**
  * Build the tmct_context "edit bundle" for a symbol and return { text, tier, topup }.
- * Shared by the tmct_context tool AND the `cli digest` arm (cli.mjs), so both
- * benefit from the size-adaptive sizing for free. `trim:true` (B2) renders a SECONDARY,
- * signatures-only bundle (no bodies/tails) for related-but-not-primary digest modules.
+ * Shared by the tmct_context tool AND the `cli digest` arm (cli.mjs). `trim:true` renders
+ * a SECONDARY, signatures-only bundle (no bodies/tails) for related-but-not-primary
+ * digest modules.
  *
- * Section ORDER is cache-stable (B7): the content that is identical across runs (anchor /
- * registration / exemplar / siblings / __all__ / insertion region) comes FIRST; the more
- * variable, history-derived tails (covering tests, co-change) come LAST, so a stable prefix
- * maximises prompt-cache reuse.
+ * Section order is cache-stable: content identical across runs (anchor/registration/
+ * exemplar/siblings/__all__/insertion region) comes first; more variable, history-derived
+ * tails (covering tests, co-change) come last, so a stable prefix maximises prompt-cache
+ * reuse.
  */
 export async function buildContextBundle(args, { config, source = defaultSource, trim = false, tel = null } = {}) {
   const symbol = String(args?.symbol || "").trim();
@@ -257,7 +251,7 @@ export async function buildContextBundle(args, { config, source = defaultSource,
     `Edit context for ${plan.moduleLabel} [${tier}${trim ? " secondary" : ""}] — assembled from the typed graph + that file. ` +
       "You do NOT need to Read it; write the new code directly after reviewing this.",
   ];
-  // ---- cache-stable prefix (B7): identical across runs ----
+  // ---- cache-stable prefix: identical across runs ----
   if (mask.anchor && plan.anchor?.site && lines) {
     const { start, end } = plan.anchor.site;
     out.push(`\n## anchor: ${plan.anchor.label} (${plan.anchor.class}) @ ${plan.moduleLabel}:${start}-${end}`);
@@ -327,7 +321,7 @@ export async function buildContextBundle(args, { config, source = defaultSource,
   } else if (plan.insertion) {
     out.push(`\n## insert the new sibling after line ~${plan.insertion} (end of the last top-level definition).`);
   }
-  // ---- variable tail (B7): history-derived, kept LAST so the prefix stays cache-stable ----
+  // ---- variable tail: history-derived, kept LAST so the prefix stays cache-stable ----
   if (mask.tests && plan.tests.length) out.push(`\n## covering tests: ${plan.tests.join(", ")}`);
   if (mask.cochange && plan.cochange && plan.cochange.length) {
     out.push(`\n## usually changed together (consider editing these too): ${plan.cochange.map((c) => `${c.label} (×${c.weight})`).join(", ")}`);
@@ -481,7 +475,7 @@ export async function dispatchTool(name, args, { config, source = defaultSource,
     const { content, tmct_ask } = ask(graph, query);
     // Every dispatchTool caller (the chat surface, the CLI fallback) expects a plain string —
     // append the structured envelope as a delimited, machine-parseable block rather than
-    // changing that shared contract for one tool. PLAN_MECHANICAL_CHAT.md §6.2.
+    // changing that shared contract for one tool.
     return `${content}\n\n---tmct_ask---\n${JSON.stringify(tmct_ask, null, 2)}`;
   }
   if (

package/src/sessions.mjs

@@ -7,21 +7,14 @@
 //     {"type":"turn", ts, query, via, resolvedIds, answeredIds, miss}  (one per turn, flushed)
 //     {"type":"end", ts}                                          (clean close marker)
 //
-// From the sidecar the session enters the typed graph twice:
-//   - READ TIME (chat.mjs, per turn): appendSessionToGraph() upserts one `Session`
-//     individual (`session:<uuidv7>`) + `mgx:asksAbout` edges into graph.json —
-//     atomically (temp + rename), re-reading the file first so a re-index that
-//     happened mid-session is tolerated: edges whose targets vanished are dropped,
-//     never left dangling (honest degradation).
-//   - REBUILD (any future graph writer): readSessionRecords() + foldInSessions()
-//     re-attach every recorded session to a FRESH graph, re-resolving each recorded
-//     entity id (by id first, then by unique label derived from the id shape);
-//     unresolvable references are dropped and counted on the session node
-//     (mgx:sessionDroppedEdges) — never a guessed edge.
+// From the sidecar the session enters the typed graph twice: at READ TIME (chat.mjs, per
+// turn) appendSessionToGraph() upserts one `Session` individual + `mgx:asksAbout` edges,
+// atomically, dropping edges whose targets vanished; at REBUILD, readSessionRecords() +
+// foldInSessions() re-attach every recorded session to a fresh graph, re-resolving each
+// entity id and dropping unresolvable references rather than guessing.
 //
-// Sessions are runtime observations, not source derivations: they record what a human
-// asked the graph about and which entities answered, so re-indexing re-attaches them
-// rather than re-deriving them from source.
+// Sessions are runtime observations, not source derivations, so re-indexing re-attaches
+// them rather than re-deriving them from source.
 
 import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
@@ -177,10 +170,6 @@ export async function appendSessionToGraph(graphFile, record, { memory = true, r
   }
   const res = upsertSession(entities, record);
   await atomicWriteJson(graphFile, entities);
-  // ALSO record the turn(s) into tmct's OWN memory graph (.tmct/memory/ — item 9),
-  // and fold the transcript into the text-block corpus once the session has ended.
-  // Best-effort by design: memory must never degrade the graph append that already
-  // succeeded, so every failure here is swallowed (mirrors chat.mjs's own stance).
   if (memory) {
     try { await recordSessionMemory(graphFile, record, repoDir); } catch { /* best-effort */ }
   }
@@ -197,15 +186,13 @@ function repoDirFromGraphFile(graphFile) {
   return basename(tmctDir) === ".tmct" ? dirname(tmctDir) : null;
 }
 
-/** The memory side-write for one session append (item 9's chat wiring, placed
- *  HERE so chat.mjs needs no change — it already calls appendSessionToGraph
- *  every turn). Each recorded turn becomes an a-visitor-said Utterance; the
- *  response prose is recovered from the human transcript (the only artifact
- *  that carries answer TEXT — the sidecar records ids) and recorded alongside
- *  as a tmct Utterance replying to it. Deterministic utterance ids make the
- *  per-turn replay idempotent. Once the sidecar carries its end marker (chat
- *  writes it before the final graph upsert), the session is folded into the
- *  text-block corpus (memory/fold.mjs). */
+/** The memory side-write for one session append, placed here so chat.mjs needs no
+ *  change — it already calls appendSessionToGraph every turn. Each recorded turn becomes
+ *  an a-visitor-said Utterance; the response prose is recovered from the human transcript
+ *  (the sidecar only records ids) and recorded alongside as a tmct Utterance replying to
+ *  it. Deterministic utterance ids make the per-turn replay idempotent. Once the sidecar
+ *  carries its end marker, the session is folded into the text-block corpus
+ *  (memory/fold.mjs). */
 async function recordSessionMemory(graphFile, record, repoDirOverride = null) {
   const repoDir = repoDirOverride ?? repoDirFromGraphFile(graphFile);
   if (!repoDir || !record?.id) return;
@@ -298,9 +285,7 @@ export const turnKey = (ts, query) => `${ts}${query}`;
  * Parse a human-readable session transcript (.tmct/session-<id>.log) into a
  * Map of turnKey(ts, query) → answer text. The transcript is the ONLY session
  * artifact that carries the answer PROSE (the structured sidecar records ids,
- * not text), so the memory write-path recovers response text from here.
- * Tolerant by design: a block is `ts` line + "> query" line + answer lines
- * until the next block; header/footer and torn tails just don't match.
+ * not text),
  */
 export function parseSessionLog(text) {
   const lines = String(text ?? "").split("\n");

package/src/source-slice.mjs

@@ -3,13 +3,11 @@
 //
 // Two halves, deliberately split:
 //   - sliceSpan   — PURE. Given an in-memory `lines` array, extracts + line-numbers
-//                   one span. No fs, no path logic. Lifted byte-identical from the
-//                   slicing logic that used to live inline in server.mjs (buildContextBundle's
-//                   `sliceBody` closure and the tmct_snippet dispatch branch).
+//                   one span. No fs, no path logic.
 //   - readSpanSafe — the fs-touching half. Resolves `join(repoRoot, path)` with Node's
 //                   `resolve()` and REFUSES to read anything that resolves outside
-//                   `repoRoot` before ever calling the injected `readFile`. This is the
-//                   fix for a real path-traversal gap: graph.json's `site.path` values are
+//                   `repoRoot` before ever calling the injected `readFile`. Guards against
+//                   a real path-traversal gap: graph.json's `site.path` values are
 //                   data (parsed from a JSON artifact on disk), not trusted input — a
 //                   crafted or corrupted graph with a `../../etc/passwd`-shaped path must
 //                   never reach an unguarded readFile.
@@ -53,8 +51,8 @@ export function sliceSpan(lines, start, end, maxLines) {
 export async function readSpanSafe({ readFile, repoRoot, path, start, end, maxLines }) {
   // Normalize repoRoot to absolute here too (defense in depth) — resolve(repoRoot, path)
   // is always absolute, so comparing it against a RELATIVE repoRoot would make this guard
-  // reject every read, not just traversal attempts (the actual bug this normalization
-  // fixes; callers should already pass an absolute repoRoot via src/config.mjs.
+  // reject every read, not just traversal attempts. Callers should already pass an
+  // absolute repoRoot via src/config.mjs.
   const root = resolve(repoRoot);
   const resolved = resolve(root, path);
   if (resolved !== root && !resolved.startsWith(root + sep)) {

package/src/source.mjs

@@ -3,7 +3,7 @@
 // stub it); in production it reads the JSON artifact the deterministic indexer
 // wrote to config.graphFile. No network, no model calls.
 //
-// This module is the PROVIDER SEAM (ROADMAP item 14, docs/adapter-contract.md):
+// This module is the PROVIDER SEAM (docs/adapter-contract.md):
 // any graph producer can feed tmct either by writing the entities-payload JSON
 // where config.graphFile points, or by registering a custom loader with
 // registerProvider() — no indexer is ever imported here. tmct only READS
@@ -53,10 +53,9 @@ export function emptyEntities() {
   };
 }
 
-/** Read + parse ONE graph artifact file — the same per-file tolerance the
- *  single-graph path below has always had: a MISSING file (ENOENT) is not an
- *  error, it's the bootstrap payload; any other read/parse failure is a clean
- *  ToolError naming the file. Shared by the single- and multi-graph paths. */
+/** Read + parse ONE graph artifact file: a MISSING file (ENOENT) is not an error, it's
+ *  the bootstrap payload; any other read/parse failure is a clean ToolError naming the
+ *  file. Shared by the single- and multi-graph paths. */
 async function readOneGraphFile(file) {
   let text;
   try {
@@ -93,21 +92,12 @@ async function fetchMergedEntities(config) {
   return merged;
 }
 
-/** Fetch the entities payload through the provider seam. With a registered
- *  provider, its result is returned as-is (uncached — a live provider owns its
- *  own caching/refresh policy); a non-object result is a clean ToolError.
- *  Default: read + parse the local graph artifact, cached per file for the
- *  process. A MISSING artifact (ENOENT) is not an error: the chat surface
- *  starts from an empty graph and the first session fold-in creates the file —
- *  so we return the bootstrap payload (uncached, so the freshly written file is
- *  picked up next fetch). Every other failure still throws a clean ToolError.
- *
- *  MULTI-GRAPH: when `config.graphFiles` names more than one file, this
- *  delegates to fetchMergedEntities (src/graph-merge.mjs) instead — a
- *  SEPARATE code path from the block below. The single-graph case (one
- *  `config.graphFile`, or a one-element `config.graphFiles`) always falls
- *  through to the unchanged block below — byte-identical to before multi-graph
- *  support existed. */
+/** Fetch the entities payload through the provider seam. With a registered provider, its
+ *  result is returned as-is (uncached); a non-object result is a clean ToolError. Default:
+ *  read + parse the local graph artifact, cached per file. A missing artifact (ENOENT)
+ *  returns the bootstrap payload, uncached, so a freshly written file is picked up next
+ *  fetch. When `config.graphFiles` names more than one file, delegates to
+ *  fetchMergedEntities instead. */
 export async function fetchEntities(config) {
   if (provider) {
     let payload;