@polycode-projects/the-mechanical-code-talker 1.3.2 → 1.4.0

package/src/providers/graph-service.mjs

@@ -19,7 +19,15 @@ import {
   edgesOfKind,
   relationKind,
   impactClosure,
+  scoreSymbolsRanked,
+  searchModulesRanked,
+  SEARCH_LIMIT,
+  contextPlan,
+  sizeBundle,
+  bundleMask,
+  renderGraphOnlyBundle,
 } from "../codegraph.mjs";
+import { readSpanSafe, sliceSpan } from "../source-slice.mjs";
 import { ask } from "../ask.mjs";
 import {
   hit,
@@ -56,14 +64,86 @@ function groupMetaForKind(graph, kind) {
   return { predicate: kind, prop: null };
 }
 
+const CONTEXT_BODY_MAX_LINES = 200; // mirrors server.mjs's SNIPPET_MAX_LINES for the source-capable body sections
+const CONTEXT_INLINE_CALLEE_LOC = 120; // mirrors server.mjs's INLINE_CALLEE_LOC budget
+
+/** The fs-dependent half of context()'s bundle — anchor / exemplar / inlined-callee body
+ *  TEXT — layered on top of renderGraphOnlyBundle's pure sections when the provider is
+ *  source-capable. Mirrors server.mjs's buildContextBundle body sections (same shape, same
+ *  safe readSpanSafe/sliceSpan primitives from Item 1) but lives here because it needs fs,
+ *  which codegraph.mjs deliberately never touches. Read failures degrade silently (an
+ *  omitted section), matching buildContextBundle's own graceful-degradation behavior —
+ *  this is a best-effort enrichment on top of an already-real graph-only hit, not a new
+ *  failure mode. Returns "" when nothing could be rendered. */
+async function renderSourceBodies(plan, mask, { readFile, repoRoot }) {
+  if (!plan.moduleLabel) return "";
+  let lines = null;
+  try {
+    ({ lines } = await readSpanSafe({ readFile, repoRoot, path: plan.moduleLabel }));
+  } catch {
+    lines = null;
+  }
+  if (!lines) return "";
+  const out = [];
+  if (mask.anchor && plan.anchor?.site) {
+    const { start, end } = plan.anchor.site;
+    out.push(`\n## anchor: ${plan.anchor.label} (${plan.anchor.class}) @ ${plan.moduleLabel}:${start}-${end}`);
+    out.push(sliceSpan(lines, start, end, CONTEXT_BODY_MAX_LINES).text);
+    if (plan.callHint) out.push(plan.callHint);
+  }
+  if (mask.exemplar && plan.exemplar?.site) {
+    const { start, end } = plan.exemplar.site;
+    const dec = plan.exemplar.decorators ? ` @${plan.exemplar.decorators}` : "";
+    out.push(`\n## closest example (full body) — copy this style: ${plan.exemplar.label} (${plan.exemplar.class})${dec} @ ${plan.moduleLabel}:${start}-${end}`);
+    out.push(sliceSpan(lines, start, end, CONTEXT_BODY_MAX_LINES).text);
+    if (plan.callHint) out.push(plan.callHint);
+  }
+  if (mask.inlinedCallees && plan.calleeBodies.length) {
+    let budget = CONTEXT_INLINE_CALLEE_LOC;
+    for (const cb of plan.calleeBodies) {
+      if (budget <= 0) break;
+      const start = cb.site.start;
+      const fromThisFile = cb.site.path === plan.moduleLabel;
+      let bodyLines = fromThisFile ? lines : null;
+      if (!bodyLines) {
+        try { ({ lines: bodyLines } = await readSpanSafe({ readFile, repoRoot, path: cb.site.path })); }
+        catch { bodyLines = null; }
+      }
+      if (!bodyLines) continue;
+      const sliced = sliceSpan(bodyLines, start, cb.site.end, budget);
+      out.push(`\n## inlined callee body (depth-1 in-repo call): ${cb.label} @ ${cb.site.path}:${start}-${cb.site.end}`);
+      out.push(sliced.text);
+      budget -= (sliced.end - start + 1);
+    }
+  }
+  return out.join("\n");
+}
+
 /**
  * @param {object} graph  a parseEntities() result
  * @param {object} [opts]
- * @param {boolean} [opts.sourceAccess=false]  whether source services can read bodies
+ * @param {boolean} [opts.sourceAccess=false]  whether source services (snippet, context) read
+ *   real fs bodies. When true, `repoRoot` + `readFile` are REQUIRED (a programmer error to
+ *   omit either — this module stays fs-free otherwise, "pure graph queries, no fs" by default;
+ *   fs is an explicit INJECTED capability, never an ambient import).
+ * @param {string} [opts.repoRoot]  absolute repo root; required when sourceAccess is true.
+ * @param {Function} [opts.readFile]  async (path, encoding) => string, e.g. node:fs/promises'
+ *   readFile; required when sourceAccess is true.
+ * @param {object|null} [opts.tel]  an optional telemetry sink ({ record(fields) }, e.g. from
+ *   telemetry.mjs's createTelemetry). When present, every service is wrapped ONCE here to time
+ *   it and record `{ tool: "ri.<name>", perf: { ms_total }, response: { ok, count } }` — counts
+ *   only, never raw text/body. Null (the default) skips the wrapping loop entirely — zero
+ *   overhead, and fixtureProvider()/bootstrapProvider() (which pass no tel) are unaffected.
  * @returns the typed service object
  */
-export function createGraphService(graph, { sourceAccess = false } = {}) {
+export function createGraphService(graph, { sourceAccess = false, repoRoot = null, readFile = null, tel = null } = {}) {
   const byId = graph.byId;
+  if (sourceAccess && (!repoRoot || typeof readFile !== "function")) {
+    throw new TypeError(
+      "createGraphService({ sourceAccess: true }) requires both repoRoot and readFile — " +
+        "fs access is an injected capability, not an ambient import.",
+    );
+  }
 
   const resolveId = (id) => byId.get(id) || null;
 
@@ -169,28 +249,37 @@ export function createGraphService(graph, { sourceAccess = false } = {}) {
       });
     },
 
-    edges(id, kind) {
+    edges(id, kind, { limit, offset = 0 } = {}) {
       if (!EDGE_KINDS.includes(kind)) {
         throw new TypeError(`edges(): unknown kind "${kind}" (not in EDGE_KINDS)`);
       }
       const ind = resolveId(id);
       if (!ind) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: id });
       const meta = groupMetaForKind(graph, kind);
-      const edges = edgesOfKind(graph, kind)
+      // edge order is stable/memoized (edgesOfKind's own docblock in codegraph.mjs) — a plain
+      // slice after filter/map is a safe, backward-compatible pagination: an omitted `limit`
+      // leaves the full list untouched (limit=undefined → slice(offset) → everything from offset).
+      let edges = edgesOfKind(graph, kind)
         .filter((e) => e.subject === id)
         .map((e) => toEdge(e, meta));
+      edges = limit == null ? edges.slice(offset) : edges.slice(offset, offset + limit);
       return hit({ kind, edges });
     },
 
-    impact(moduleId) {
+    impact(moduleId, { maxDepth } = {}) {
       const ind = resolveId(moduleId);
       if (!ind) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: moduleId });
-      const levels = impactClosure(graph, ind);
+      const levels = maxDepth == null ? impactClosure(graph, ind) : impactClosure(graph, ind, { maxDepth });
       const total = levels.reduce((n, l) => n + l.length, 0);
       return hit({ total, levels });
     },
 
-    snippet(id) {
+    // NOTE: async (returns Promise<Result>) — real source reads (node:fs/promises) are
+    // inherently async, and unlike the pure graph services above, a caller of a
+    // source-reaching service should always `await` it regardless of whether THIS
+    // particular provider happens to be source-capable (awaiting a non-Promise value is a
+    // safe no-op, so this is backward-compatible for a caller that already awaits).
+    async snippet(id) {
       const ind = resolveId(id);
       if (!ind) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: id });
       const site = siteOf(ind);
@@ -201,18 +290,37 @@ export function createGraphService(graph, { sourceAccess = false } = {}) {
         });
       }
       if (!site) return miss(MISS_REASONS.NO_SOURCE, { term: id, detail: "no source span in the graph (likely a module)" });
-      // A source-capable subclass overrides snippet to read the body; the graph-only
-      // base returns the span with a null body.
-      return hit({ path: site.path, span: { start: site.start, end: site.end }, body: null });
+      try {
+        const sliced = await readSpanSafe({
+          readFile, repoRoot, path: site.path, start: site.start, end: site.end, maxLines: CONTEXT_BODY_MAX_LINES,
+        });
+        return hit({ path: site.path, span: { start: site.start, end: site.end }, body: sliced.text });
+      } catch (e) {
+        // A path-traversal ToolError or any other read failure both land here — honestly,
+        // never a throw (the interface's error contract: a clean miss is a value).
+        return miss(MISS_REASONS.NO_SOURCE, { term: id, detail: `could not read ${site.path}: ${e?.message || e}` });
+      }
     },
 
-    context(symbol) {
+    // INTERFACE_VERSION 1.1.0 (2d): context() is now a graph-only HIT for any resolvable
+    // symbol — contextPlan/sizeBundle/renderGraphOnlyBundle are pure graph queries, so a
+    // graph-only provider (no working tree) can genuinely answer with siblings/registration/
+    // globals/tests/exports/insertion-region, everything EXCEPT anchor/exemplar/inlined-callee
+    // body TEXT. Only an unresolvable symbol still misses (UNRESOLVED_TERM). A source-capable
+    // provider layers the body sections on top via renderSourceBodies (below).
+    async context(symbol, { depth = "auto" } = {}) {
       const { match } = resolveSymbol(graph, String(symbol ?? ""));
       if (!match) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: String(symbol ?? "") });
-      return miss(MISS_REASONS.NO_SOURCE, {
-        term: String(symbol ?? ""),
-        detail: "the edit bundle reaches into the working tree; this provider exposes no source",
-      });
+      const plan = contextPlan(graph, match);
+      const d = String(depth || "auto").trim().toLowerCase();
+      let tier, mask;
+      if (d === "min") { tier = "TINY"; mask = bundleMask("TINY"); }
+      else if (d === "full") { tier = "FULL"; mask = bundleMask("FULL"); }
+      else ({ tier, mask } = sizeBundle(plan, graph, {}));
+      const graphText = renderGraphOnlyBundle(plan, mask);
+      if (!svc.sourceAccess) return hit({ text: graphText, tier });
+      const bodyText = await renderSourceBodies(plan, mask, { readFile, repoRoot });
+      return hit({ text: bodyText ? `${graphText}\n${bodyText}` : graphText, tier });
     },
 
     architecture({ package: pkg = "" } = {}) {
@@ -281,21 +389,37 @@ export function createGraphService(graph, { sourceAccess = false } = {}) {
       return hit({ commits });
     },
 
-    search(query, { kind = "", name = "", decorator = "" } = {}) {
-      const q = String(query || "").trim().toLowerCase();
+    // Ranked lexical search, mirroring codegraph.mjs's renderSearch/searchSymbols semantics
+    // instead of the old flat substring filter: module-mode (no kind, or kind="module") ranks
+    // via searchModulesRanked/scoreModules (path + defined-symbol + import-proximity scoring),
+    // symbol-mode (kind names a symbol kind) ranks via scoreSymbolsRanked. name/decorator
+    // filters apply in SYMBOL mode only — module mode never supported them in codegraph.mjs
+    // either (renderSearch's module branch ignores both beyond the "was anything specified"
+    // check), so this does not invent a new filter semantic. Results are capped at
+    // `limit` (default SEARCH_LIMIT), sliced after the full ranked array is computed.
+    search(query, { kind = "", name = "", decorator = "", limit = SEARCH_LIMIT, offset = 0 } = {}) {
+      const rawQuery = String(query || "");
       const k = String(kind || "").trim().toLowerCase();
-      const nm = String(name || "").trim().toLowerCase();
+      const nm = String(name || "").trim();
       const dec = String(decorator || "").trim().toLowerCase();
-      const results = graph.individuals
-        .filter((i) => {
-          const label = String(i.label || "").toLowerCase();
-          if (k && (i.class || "").toLowerCase() !== k) return false;
-          if (nm && !label.includes(nm)) return false;
-          if (dec && !String(attrOf(i, "decorators") || "").toLowerCase().includes(dec)) return false;
-          if (q && !label.includes(q)) return false;
-          return true;
-        })
-        .map(toIndividual);
+      let nameRe = null;
+      if (nm) {
+        try { nameRe = new RegExp(nm, "i"); } catch { nameRe = null; }
+      }
+      let rankedInds; // Individual[], highest-ranked first
+      if (k && k !== "module") {
+        const tokens = rawQuery.toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean);
+        rankedInds = scoreSymbolsRanked(graph, tokens, { kind: k, decFilter: dec, nameRe }).map((s) => s.ind);
+      } else {
+        // label→individual, scoped to this call (no persistent cache) — maps searchModulesRanked's
+        // `path` labels (a copy of the label, not the live individual) back to real Individuals.
+        const byLabel = new Map();
+        for (const i of graph.individuals) if ((i.class || "") === "Module") byLabel.set(i.label, i);
+        rankedInds = searchModulesRanked(graph, rawQuery)
+          .map(({ path }) => byLabel.get(path))
+          .filter(Boolean);
+      }
+      const results = rankedInds.slice(offset, offset + limit).map(toIndividual);
       return hit({ results });
     },
 
@@ -305,8 +429,61 @@ export function createGraphService(graph, { sourceAccess = false } = {}) {
     },
   };
 
+  // Optional telemetry (Item 3.2): when `tel` is supplied, wrap every RI service ONCE here at
+  // construction — never per-method by hand — to time it and record COUNTS only (never raw
+  // text/body; see responseCounts below and telemetry.mjs's redact() as a second net). When
+  // `tel` is null (the default), this loop does not run at all: zero overhead, and
+  // fixtureProvider()/bootstrapProvider() (which pass no `tel`) are completely unaffected.
+  if (tel) {
+    for (const name of SERVICES) {
+      const orig = svc[name];
+      if (typeof orig !== "function") continue;
+      svc[name] = (...args) => {
+        const t0 = performance.now();
+        const result = orig.apply(svc, args);
+        // snippet/context are ASYNC (Promise<Result>) — record after settling, still return a
+        // promise; every other service is synchronous — record immediately, return the value
+        // as-is. Detected at the ACTUAL call (not a static per-service list) so this is correct
+        // even if a future service's sync/async-ness varies by branch.
+        if (result && typeof result.then === "function") {
+          return result.then((r) => {
+            recordTelemetry(tel, name, performance.now() - t0, r);
+            return r;
+          });
+        }
+        recordTelemetry(tel, name, performance.now() - t0, result);
+        return result;
+      };
+    }
+  }
+
   return svc;
 }
 
+/** tel.record({ tool: `ri.${name}`, perf: { ms_total }, response }) for one wrapped service
+ *  call — swallows any error (telemetry must never break the call it's observing). */
+function recordTelemetry(tel, name, ms, result) {
+  try {
+    tel.record({ tool: `ri.${name}`, perf: { ms_total: ms }, response: responseCounts(result) });
+  } catch { /* telemetry must never break the caller's turn */ }
+}
+
+/** Counts only, never raw text/body: { ok, count } — count is the sum of every array-valued
+ *  field's length under result.value (edges.length, results.length, candidates.length, …), a
+ *  single generic aggregate rather than guessing each service's own field names. A miss
+ *  records its reason (a closed-set token, not free text) instead of a count. */
+function responseCounts(result) {
+  if (!result || typeof result !== "object" || result.ok !== true) {
+    return { ok: false, reason: result?.miss?.reason || null };
+  }
+  let count = 0;
+  const value = result.value;
+  if (Array.isArray(value)) count = value.length;
+  else if (value && typeof value === "object") {
+    for (const v of Object.values(value)) if (Array.isArray(v)) count += v.length;
+  }
+  return { ok: true, count };
+}
+
 /** The source-reaching services a graph-only provider satisfies with NO_SOURCE. */
 export { SOURCE_SERVICES };

package/src/repository-interface.mjs

@@ -18,7 +18,7 @@
 /** SemVer of the interface. Additive-by-default: new services / optional args are
  *  minor bumps; the suite for version N stays green under N+1. A breaking change
  *  is a new MAJOR with its own suite (see the versioning policy in the plan). */
-export const INTERFACE_VERSION = "1.0.0";
+export const INTERFACE_VERSION = "1.1.0";
 
 /** The OWL vocabulary the types are grounded in. */
 export const ONTOLOGY_IRI = "urn:tmct:core";
@@ -211,7 +211,10 @@ export const REPOSITORY_INTERFACE = Object.freeze({
   capabilitiesModel:
     "A provider advertises `capabilities: string[]` (service names it implements). " +
     "A service outside the set is negotiated away to miss(CAPABILITY_ABSENT) — never an error. " +
-    "Source services (snippet, context) may be advertised yet answer miss(NO_SOURCE) when no working tree exists.",
+    "snippet may be advertised yet answer miss(NO_SOURCE) when no working tree exists (it has " +
+    "nothing useful without fs); context is graph-only-capable since INTERFACE_VERSION 1.1.0 — " +
+    "it returns a real hit (graph-only bundle) for any resolvable symbol even with no working " +
+    "tree, only escalating NO_SOURCE-style behavior to richer body text when source-capable.",
   services: {
     resolve: {
       group: "resolution", args: { term: "string" },
@@ -264,15 +267,26 @@ export const REPOSITORY_INTERFACE = Object.freeze({
     },
     snippet: {
       group: "source", args: { id: "string" },
-      result: "{ path: string, span: { start, end }, body: string|null }",
+      result: "{ path: string, span: { start, end }, body: string|null } — Promise<Result>",
       misses: ["UNRESOLVED_TERM", "NO_SOURCE"], concurrency: CONCURRENT_SAFE,
-      purpose: "The exact source span of a symbol. A provider with no working tree returns miss(NO_SOURCE) honestly.",
+      purpose: "The exact source span of a symbol. A provider with no working tree returns miss(NO_SOURCE) honestly — snippet has nothing useful without fs.",
+      note: "ASYNC (returns Promise<Result>) — a real body read is inherently fs I/O; callers should always await it. A graph-only provider still resolves synchronously-in-spirit (the promise settles on the same tick) but the return type is uniformly a Promise regardless of sourceAccess.",
     },
     context: {
       group: "source", args: { symbol: "string", depth: "min|auto|full?" },
-      result: "{ text: string, tier: string } (a sized edit bundle)",
-      misses: ["UNRESOLVED_TERM", "NO_SOURCE"], concurrency: CONCURRENT_SAFE,
-      purpose: "The composed edit bundle (exemplar, siblings, registration, insertion region). Source-reaching.",
+      result: "{ text: string, tier: string } (a sized edit bundle) — Promise<Result>",
+      // INTERFACE_VERSION 1.1.0 (2026-07): NARROWED miss contract — context() used to
+      // unconditionally miss(NO_SOURCE) (its whole edit bundle was implemented as fs-only).
+      // contextPlan/sizeBundle/renderGraphOnlyBundle are pure graph queries, so a graph-only
+      // provider (sourceAccess:false) now returns a REAL HIT for any resolvable symbol —
+      // siblings, registration, class members, __all__/re-exports, insertion region, covering
+      // tests, co-change — everything except anchor/exemplar/inlined-callee BODY TEXT, which
+      // still needs a source-capable provider. NO_SOURCE is consequently no longer a miss
+      // reason context() can return (dropped from the list below) — the only remaining miss is
+      // an unresolvable symbol.
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "The composed edit bundle (exemplar, siblings, registration, insertion region). A graph-only provider returns the graph-only sections as a real hit; a source-capable provider (sourceAccess:true, repoRoot, readFile) additionally includes the anchor/exemplar/inlined-callee body text.",
+      note: "ASYNC (returns Promise<Result>) — see snippet's note; source-capable rendering is fs I/O.",
     },
     architecture: {
       group: "aggregate", args: { package: "string?" },

package/src/server.mjs

@@ -15,8 +15,9 @@
 // otherwise hand-compose into one deterministic round-trip. See ask.mjs.
 
 import { readFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { dirname } from "node:path";
 import { ToolError } from "./config.mjs";
+import { sliceSpan, readSpanSafe } from "./source-slice.mjs";
 import * as defaultSource from "./source.mjs";
 import {
   parseEntities,
@@ -202,7 +203,7 @@ function resolveOrThrow(svc, symbol, what) {
  * 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 } = {}) {
+export async function buildContextBundle(args, { config, source = defaultSource, trim = false, tel = null } = {}) {
   const symbol = String(args?.symbol || "").trim();
   if (!symbol) throw new ToolError("symbol is required");
   const depth = String(args?.depth || "auto").trim().toLowerCase();
@@ -216,7 +217,17 @@ export async function buildContextBundle(args, { config, source = defaultSource,
   // by the tmct-max arm to test whether more injection re-bloats.
   const max = Boolean(args?.max);
   const graph = await loadGraph(config, source);
-  const svc = createGraphService(graph);
+  // repo root = the dir containing .tmct/ (graphFile = <repo>/.tmct/graph.json) — computed
+  // before createGraphService so the RI service can be constructed source-capable (2e): this
+  // module still does its OWN safe reads below (readSpanSafe/sliceSpan, Item 1) rather than
+  // delegating to svc.context() — see the module docblock's note on why. Passing sourceAccess
+  // through anyway keeps svc.snippet()/svc.context() usable by any future/external caller of
+  // this same service object without a second, divergent construction path. `tel` (optional,
+  // Item 3.3) is an already-constructed telemetry sink threaded down from the caller (e.g.
+  // chat.mjs's session-level createTelemetry) — never minted here, so a caller that never
+  // passes one costs nothing extra (createGraphService's own wrapping loop no-ops on tel:null).
+  const repoRoot = dirname(dirname(config.graphFile));
+  const svc = createGraphService(graph, { sourceAccess: true, repoRoot, readFile, tel });
   const { match } = resolveOrThrow(svc, symbol, "symbol");
   const plan = contextPlan(graph, match);
   // #6/B1/B6: pick the section mask by depth — min forces TINY, full/max forces everything, auto
@@ -228,17 +239,13 @@ export async function buildContextBundle(args, { config, source = defaultSource,
   else if (max || depth === "full") { tier = "FULL"; mask = bundleMask("FULL"); topup = true; }
   else ({ tier, mask, topup } = sizeBundle(plan, graph, { untuned }));
   if (trim && !max) mask = trimBundleMask(mask); // B2: secondary digest module → signatures + region only (max keeps the full bundle)
-  const repoRoot = dirname(dirname(config.graphFile));
   let lines = null;
   if (plan.moduleLabel) {
-    try { lines = (await readFile(join(repoRoot, plan.moduleLabel), "utf8")).split("\n"); }
+    try { ({ lines } = await readSpanSafe({ readFile, repoRoot, path: plan.moduleLabel })); }
     catch { lines = null; }
   }
   const lineAt = (n) => (lines && lines[n - 1] != null ? lines[n - 1].trim() : "");
-  const sliceBody = (start, end) => {
-    const e = Math.min(lines.length, Math.min(end, start + SNIPPET_MAX_LINES - 1));
-    return lines.slice(start - 1, e).map((l, i) => `${start + i}\t${l}`).join("\n");
-  };
+  const sliceBody = (start, end) => sliceSpan(lines, start, end, SNIPPET_MAX_LINES).text;
   const out = [
     `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.",
@@ -266,16 +273,15 @@ export async function buildContextBundle(args, { config, source = defaultSource,
     for (const cb of plan.calleeBodies) {
       if (budget <= 0) break;
       const start = cb.site.start;
-      const end = Math.min(cb.site.end, start + budget - 1);
       const fromThisFile = cb.site.path === plan.moduleLabel;
       const bodyLines = fromThisFile && lines
         ? lines
-        : await readFile(join(repoRoot, cb.site.path), "utf8").then((t) => t.split("\n")).catch(() => null);
+        : await readSpanSafe({ readFile, repoRoot, path: cb.site.path }).then((r) => r.lines).catch(() => null);
       if (!bodyLines) continue;
-      const e = Math.min(bodyLines.length, end);
+      const sliced = sliceSpan(bodyLines, start, cb.site.end, budget);
       out.push(`\n## inlined callee body (depth-1 in-repo call): ${cb.label} @ ${cb.site.path}:${start}-${cb.site.end}`);
-      out.push(bodyLines.slice(start - 1, e).map((l, i) => `${start + i}\t${l}`).join("\n"));
-      budget -= (e - start + 1);
+      out.push(sliced.text);
+      budget -= (sliced.end - start + 1);
     }
   }
   if (mask.classMembers && plan.classMembers && plan.classMembers.members.length) {
@@ -337,11 +343,11 @@ const DISPATCH_TOOLS = new Set([
   "tmct_file_history", "tmct_method_history", "tmct_class_history",
 ]);
 
-export async function dispatchTool(name, args, { config, source = defaultSource } = {}) {
+export async function dispatchTool(name, args, { config, source = defaultSource, tel = null } = {}) {
   // tmct_context builds (and loads) its own edit bundle — return early so we don't
   // double-load the graph for it.
   if (name === "tmct_context") {
-    return (await buildContextBundle(args, { config, source })).text;
+    return (await buildContextBundle(args, { config, source, tel })).text;
   }
   // Reject an unknown tool BEFORE touching the graph — preserves the original
   // ordering (an unknown name never triggers a load).
@@ -352,7 +358,13 @@ export async function dispatchTool(name, args, { config, source = defaultSource
   // the result with tmct's own render* layer (which reads svc.graph). This is the
   // switch's operations extracted into a named, typed seam without changing bytes.
   const graph = await loadGraph(config, source);
-  const svc = createGraphService(graph);
+  // repo root = the dir containing .tmct/ (graphFile = <repo>/.tmct/graph.json). Passed through
+  // to createGraphService (2e) so svc.snippet()/svc.context() are usable directly; this
+  // dispatcher still does its OWN safe read for tmct_snippet below (readSpanSafe/sliceSpan,
+  // Item 1) rather than delegating, to keep its richer presentation (candidates, call hints,
+  // truncation notices) — see the tmct_snippet branch below.
+  const repoRoot = dirname(dirname(config.graphFile));
+  const svc = createGraphService(graph, { sourceAccess: true, repoRoot, readFile, tel });
   if (name === "tmct_context_more") {
     const symbol = String(args?.symbol || "").trim();
     if (!symbol) throw new ToolError("symbol is required");
@@ -379,18 +391,16 @@ export async function dispatchTool(name, args, { config, source = defaultSource
           "it is likely a module. Use tmct_describe for its contents, then tmct_snippet one of the functions/classes it defines.",
       );
     }
-    // repo root = the dir containing .tmct/ (graphFile = <repo>/.tmct/graph.json)
-    const repoRoot = dirname(dirname(config.graphFile));
-    const abs = join(repoRoot, site.path);
-    let text;
-    try { text = await readFile(abs, "utf8"); }
-    catch (e) { throw new ToolError(`could not read ${site.path} (${e?.code || e?.message || e})`); }
-    const lines = text.split("\n");
-    const start = Math.max(1, site.start);
-    let end = Math.min(lines.length, site.end);
-    let truncated = false;
-    if (end - start + 1 > SNIPPET_MAX_LINES) { end = start + SNIPPET_MAX_LINES - 1; truncated = true; }
-    const body = lines.slice(start - 1, end).map((l, i) => `${start + i}\t${l}`).join("\n");
+    let sliced;
+    try {
+      sliced = await readSpanSafe({
+        readFile, repoRoot, path: site.path, start: site.start, end: site.end, maxLines: SNIPPET_MAX_LINES,
+      });
+    } catch (e) {
+      if (e instanceof ToolError) throw e; // path-traversal guard: message already names the offending path
+      throw new ToolError(`could not read ${site.path} (${e?.code || e?.message || e})`);
+    }
+    const { text: body, truncated } = sliced;
     const span = site.end > site.start ? `${site.start}-${site.end}` : `${site.start}`;
     const header = `${match.label} — ${match.class || "Entity"} @ ${site.path}:${span}`;
     const note = truncated ? `\n… (truncated to ${SNIPPET_MAX_LINES} lines; full span ${span})` : "";

package/src/source-slice.mjs

@@ -0,0 +1,68 @@
+// Shared, safe source-span slicing for the tool layer (src/server.mjs) and the
+// source-capable Repository Interface provider (src/providers/graph-service.mjs).
+//
+// 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).
+//   - 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
+//                   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.
+
+import { resolve, sep } from "node:path";
+import { ToolError } from "./config.mjs";
+
+/**
+ * Extract and line-number one span from an in-memory `lines` array (already split on "\n").
+ * Pure — no fs. `start`/`end` are 1-based, inclusive, graph-derived (may be out of range).
+ * `maxLines` (optional) caps the span length, truncating from `start`; omit for no cap.
+ * Returns { start, end, text, truncated } where start/end are the CLAMPED bounds actually
+ * sliced (not the raw input) and text is "<lineNo>\t<content>" per line, joined with "\n".
+ */
+export function sliceSpan(lines, start, end, maxLines) {
+  const s = Math.max(1, start);
+  let e = Math.min(lines.length, end);
+  let truncated = false;
+  if (maxLines != null && e - s + 1 > maxLines) {
+    e = s + maxLines - 1;
+    truncated = true;
+  }
+  const text = lines.slice(s - 1, e).map((l, i) => `${s + i}\t${l}`).join("\n");
+  return { start: s, end: e, text, truncated };
+}
+
+/**
+ * Safely read `path` (relative, from the graph) rooted at `repoRoot`, then optionally slice
+ * one span out of it. `readFile` is injected (e.g. node:fs/promises' readFile) — this module
+ * never imports fs itself, so callers control the fs capability.
+ *
+ * SECURITY: resolves the joined path and verifies it is `repoRoot` itself or a descendant of
+ * it (`resolved === repoRoot || resolved.startsWith(repoRoot + sep)`) BEFORE calling `readFile`.
+ * A path that escapes repoRoot (e.g. via `../../etc/passwd`-shaped graph data) throws a
+ * ToolError naming the offending path — never reaches fs.
+ *
+ * When `start`/`end` are omitted, returns the whole file as `{ lines }` (for callers that need
+ * to slice multiple spans out of the same file without re-reading it — see buildContextBundle).
+ * When both are given, also slices via sliceSpan and spreads its result in.
+ */
+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, but this
+  // function is the real security boundary and must not depend on that).
+  const root = resolve(repoRoot);
+  const resolved = resolve(root, path);
+  if (resolved !== root && !resolved.startsWith(root + sep)) {
+    throw new ToolError(`refusing to read outside the repository root: ${path}`);
+  }
+  const text = await readFile(resolved, "utf8");
+  const lines = text.split("\n");
+  if (start == null || end == null) return { lines };
+  return { lines, ...sliceSpan(lines, start, end, maxLines) };
+}

package/src/telemetry.mjs

@@ -14,8 +14,11 @@ import { appendFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { uuidv7 } from "./uuid.mjs";
 
-/** Field names whose VALUES are (or embed) raw source and must never be logged. */
-const DROP_KEYS = new Set(["text", "content", "snippet"]);
+/** Field names whose VALUES are (or embed) raw source and must never be logged. `body` is
+ *  the Repository Interface's own field name for real source text (snippet()/context()'s
+ *  source-capable body sections, PLAN item 2/3) — without it, raw source read via the
+ *  now-source-capable createGraphService could leak straight into a telemetry log. */
+const DROP_KEYS = new Set(["text", "content", "snippet", "body"]);
 /** String fields longer than this are truncated — except query.raw (the user's own
  *  question, which is the correlation key and is not file content). */
 const MAX_STR = 500;

package/src/toml-config.mjs

@@ -101,6 +101,13 @@ export async function normalizeConfig(raw, { configDir } = {}) {
   if (seed.limit !== undefined) seedCfg.limit = seed.limit;
   if (Object.keys(seedCfg).length) cfg.seed = seedCfg;
 
+  // Extension-pack seam (src/extensions.mjs): sparse PASS-THROUGH only — the
+  // raw `[extensions]`/`[bias]` tables ride through unmodified so a caller can
+  // see they're present; validation happens one layer up, in
+  // resolveExtensions() (never here — this module stays a plain raw reader).
+  if (src.extensions !== undefined) cfg.extensions = src.extensions;
+  if (src.bias !== undefined) cfg.bias = src.bias;
+
   const idx = src.index || {};
   const index = {};
   if (idx.languages !== undefined) index.languages = idx.languages;
@@ -137,6 +144,16 @@ export async function normalizeConfig(raw, { configDir } = {}) {
   const tel = src.telemetry || {};
   if (tel.enabled !== undefined) cfg.telemetry = { enabled: tel.enabled };
 
+  // [memory] retention_versions — read by memory/core.mjs's snapshotMemory as
+  // the manifest-bootstrap default (only when no manifest.json exists yet; a
+  // persisted manifest's own retentionVersions wins after that). Sparse like
+  // every other table here: absent when unset, so "unset" stays distinguishable
+  // from "set to the default" — the shipped default (5, memory/core.mjs's
+  // DEFAULT_RETENTION) is applied where the value is actually CONSUMED
+  // (snapshotMemory), not injected here.
+  const mem = src.memory || {};
+  if (mem.retention_versions !== undefined) cfg.memory = { retentionVersions: mem.retention_versions };
+
   const unwired = [];
   for (const [a, b] of UNWIRED_KEYS) {
     if (src[a] && src[a][b] !== undefined) unwired.push(`${a}.${b}`);