@polycode-projects/the-mechanical-code-talker 1.12.0 → 2.0.1

package/src/tools/handlers/tmct-context.mjs

@@ -0,0 +1,163 @@
+// tmct_context — the sized "edit bundle" for one symbol: exemplar source, sibling
+// signatures, the registration anchor and the insertion region, in one call.
+
+import { readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { ToolError } from "../../adapters/config.mjs";
+import { sliceSpan, readSpanSafe } from "../../adapters/source-slice.mjs";
+import * as defaultSource from "../../adapters/source.mjs";
+import { contextPlan, sizeBundle, bundleMask, trimBundleMask } from "../../domain/codegraph.mjs";
+import { ask } from "../../domain/ask.mjs";
+import { createGraphService } from "../../adapters/providers/graph-service.mjs";
+import { loadGraph } from "../graph-load.mjs";
+import { resolveOrThrow, SNIPPET_MAX_LINES } from "./kit.mjs";
+
+/**
+ * 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 (bin/tmct.mjs). `trim:true` renders
+ * a SECONDARY, signatures-only bundle (no bodies/tails) for related-but-not-primary
+ * digest modules.
+ *
+ * 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();
+  if (!symbol) throw new ToolError("symbol is required");
+  const depth = String(args?.depth || "auto").trim().toLowerCase();
+  // Tuning-flag contract: `min` forces the LEANEST bundle (TINY mask, no top-up) regardless of
+  // exemplar length; `untuned` reproduces the earlier escalation (tuning #1 bypassed). Neither
+  // → the tuned default (sizeBundle's anchor-gated escalation).
+  const min = Boolean(args?.min);
+  const untuned = Boolean(args?.untuned);
+  // `max` forces the injection CEILING — FULL tier (every section + inlined depth-1 callee
+  // bodies) with top-up, and it OVERRIDES trim so even secondary modules get the full bundle. Used
+  // by the tmct-max arm to test whether more injection re-bloats.
+  const max = Boolean(args?.max);
+  const graph = await loadGraph(config, source);
+  // repo root = the dir containing .tmct/ (graphFile = <repo>/.tmct/graph.json) — computed
+  // before createGraphService so the RI service can be constructed source-capable: this
+  // module still does its OWN safe reads below (readSpanSafe/sliceSpan) rather than
+  // delegating to svc.context(). 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) 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, ask });
+  const { match } = resolveOrThrow(svc, symbol, "symbol");
+  const plan = contextPlan(graph, match);
+  // Pick the section mask by depth — min forces TINY, full/max forces everything, auto runs
+  // the size classifier (lean TINY default + one-tier top-up when the edit needs it).
+  let tier;
+  let mask;
+  let topup = false;
+  if (min || depth === "min") { tier = "TINY"; mask = bundleMask("TINY"); }
+  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);
+  let lines = null;
+  if (plan.moduleLabel) {
+    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) => 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.",
+  ];
+  // ---- 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}`);
+    out.push(sliceBody(start, end));
+    if (plan.callHint) out.push(plan.callHint);
+  }
+  if (mask.registration && plan.globals.length) {
+    out.push(`\n## registration / module globals (replicate this pattern):`);
+    for (const g of plan.globals) out.push(`  ${g.label} = ${g.value}${g.site ? `  [:${g.site.start}]` : ""}`);
+  }
+  if (mask.exemplar && plan.exemplar?.site && lines) {
+    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(sliceBody(start, end));
+    if (plan.callHint) out.push(plan.callHint);
+  }
+  if (mask.inlinedCallees && plan.calleeBodies.length && lines) {
+    let budget = 120; // 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;
+      const bodyLines = fromThisFile && lines
+        ? lines
+        : await readSpanSafe({ readFile, repoRoot, path: cb.site.path }).then((r) => r.lines).catch(() => 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);
+    }
+  }
+  if (mask.classMembers && plan.classMembers && plan.classMembers.members.length) {
+    out.push(`\n## members of ${plan.classMembers.className} (the edit likely lives INSIDE this class — copy a member's shape, do not read the class body):`);
+    for (const m of plan.classMembers.members) {
+      const short = String(m.label).split(".").pop();
+      const sig = m.params != null && m.params !== "" ? `(${m.params})${m.returns ? ` -> ${m.returns}` : ""}` : "";
+      const dec = m.decorators ? `@${m.decorators} ` : "";
+      const r = m.raises ? `  raises=${m.raises}` : "";
+      out.push(`  ${m.class} ${short}${m.site ? ` :${m.site.start}` : ""}  ${dec}${short}${sig}${r}`);
+    }
+  }
+  if (mask.siblings && plan.siblings.length) {
+    out.push(`\n## sibling symbols to copy the style of (most relevant first; ${plan.siblings.length} total):`);
+    for (const s of plan.siblings.slice(0, plan.siblingCap)) {
+      const sig = s.site ? lineAt(s.site.start) : "";
+      const dec = s.decorators ? `@${s.decorators} ` : "";
+      const r = s.raises ? `  raises=${s.raises}` : "";
+      out.push(`  ${s.class} ${s.label}${s.site ? ` :${s.site.start}` : ""}  ${dec}${sig}${r}`);
+    }
+    if (plan.siblings.length > plan.siblingCap) {
+      out.push(`  …+${plan.siblings.length - plan.siblingCap} more (use tmct_search kind=function or tmct_snippet <name> for any of them)`);
+    }
+  }
+  if (mask.allExports && plan.allExports) {
+    out.push(`\n## module __all__ — this module curates its public API; ADD your new public symbol to this list so it is importable:\n  ${plan.allExports}`);
+  }
+  if (mask.reexports && plan.exports && plan.exports.length) out.push(`\n## re-exported symbols (resolved __all__ → defining module): ${plan.exports.join(", ")}`);
+  // The contiguous insertion region is part of the STABLE prefix — always present (even at
+  // TINY) so the agent never needs to Read the file to place the edit.
+  if (mask.insertionRegion && plan.insertionRegion && lines) {
+    const start = plan.insertionRegion.start;
+    const end = Math.min(lines.length, start + 40 - 1); // INSERTION_REGION_CAP
+    out.push(`\n## insertion region (write your new sibling here) — ${plan.moduleLabel}:${start}-${end}`);
+    out.push(lines.slice(start - 1, end).map((l, i) => `${start + i}\t${l}`).join("\n"));
+  } else if (plan.insertion) {
+    out.push(`\n## insert the new sibling after line ~${plan.insertion} (end of the last top-level definition).`);
+  }
+  // ---- 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(", ")}`);
+  }
+  out.push(`\nYou now have the snippet, the sibling style, the registration anchor and the tests. ` +
+    `Write the new code with Edit/Write — do NOT Read ${plan.moduleLabel}.`);
+  if (tier !== "FULL") {
+    out.push(`(bundle tier ${tier}; for any omitted sections run tmct_context_more {"symbol":"${symbol}"}, or tmct_context with depth="full".)`);
+  }
+  return { text: out.join("\n"), tier, topup };
+}
+
+export async function tmct_context(args, { config, source, tel }) {
+  return (await buildContextBundle(args, { config, source, tel })).text;
+}
+
+// buildContextBundle validates `symbol` before it loads anything and then loads the graph
+// itself, so dispatch hands this handler the raw config and skips its own load rather than
+// loading the graph twice.
+tmct_context.ownsGraphLoad = true;

package/src/tools/handlers/tmct-describe.mjs

@@ -0,0 +1,15 @@
+// tmct_describe — locate one symbol and list its typed edges, falling through to the
+// memory/corpus facts when the concept is known there but absent from the code-map.
+
+import { renderDescribe, resolveSymbol } from "../../domain/codegraph.mjs";
+import { memoryFactRows, renderMemoryDefinition } from "../memory-fallthrough.mjs";
+import { requiredArg, resolveOrThrow } from "./kit.mjs";
+
+export async function tmct_describe(args, { graph, svc, config }) {
+  const symbol = requiredArg(args, "symbol");
+  const { match, candidates } = resolveSymbol(svc.graph, symbol);
+  if (match) return renderDescribe(graph, match, { candidates }); // code-map wins when present
+  const fallback = renderMemoryDefinition(await memoryFactRows(config), symbol);
+  if (fallback) return fallback;
+  resolveOrThrow(svc, symbol, "symbol"); // no code-map + no memory fact → the honest miss
+}

package/src/tools/handlers/tmct-exports.mjs

@@ -0,0 +1,9 @@
+// tmct_exports — a module's public __all__ surface, each name resolved to its definer.
+
+import { renderExports } from "../../domain/codegraph.mjs";
+import { requiredArg, resolveOrThrow } from "./kit.mjs";
+
+export function tmct_exports(args, { graph, svc }) {
+  const { match } = resolveOrThrow(svc, requiredArg(args, "module"), "module");
+  return renderExports(graph, match);
+}

package/src/tools/handlers/tmct-file-history.mjs

@@ -0,0 +1,6 @@
+// tmct_file_history — commits that touched a symbol's module, with author / date / subject.
+
+import { renderFileHistory } from "../../domain/codegraph.mjs";
+import { symbolHandler } from "./kit.mjs";
+
+export const tmct_file_history = symbolHandler(renderFileHistory);

package/src/tools/handlers/tmct-history.mjs

@@ -0,0 +1,6 @@
+// tmct_history — recent commits that touched a symbol's module, newest first.
+
+import { renderHistory } from "../../domain/codegraph.mjs";
+import { symbolHandler } from "./kit.mjs";
+
+export const tmct_history = symbolHandler(renderHistory);

package/src/tools/handlers/tmct-impact.mjs

@@ -0,0 +1,9 @@
+// tmct_impact — transitive reverse closure over imports/calls: what breaks if a module changes.
+
+import { renderImpact } from "../../domain/codegraph.mjs";
+import { requiredArg, resolveOrThrow } from "./kit.mjs";
+
+export function tmct_impact(args, { graph, svc }) {
+  const { match } = resolveOrThrow(svc, requiredArg(args, "module"), "module");
+  return renderImpact(graph, match);
+}

package/src/tools/handlers/tmct-members.mjs

@@ -0,0 +1,16 @@
+// tmct_members — a class's methods and attributes. A concept's "members" in the corpus
+// sense are its subclasses (its instances), which is the fall-through when the code-map
+// has no such class.
+
+import { renderMembers, resolveSymbol } from "../../domain/codegraph.mjs";
+import { memoryFactRows, renderMemorySubclasses } from "../memory-fallthrough.mjs";
+import { requiredArg, resolveOrThrow } from "./kit.mjs";
+
+export async function tmct_members(args, { graph, svc, config }) {
+  const symbol = requiredArg(args, "class");
+  const { match } = resolveSymbol(svc.graph, symbol);
+  if (match) return renderMembers(graph, match); // code-map wins when present
+  const fallback = renderMemorySubclasses(await memoryFactRows(config), symbol);
+  if (fallback) return fallback;
+  resolveOrThrow(svc, symbol, "class"); // the honest miss
+}

package/src/tools/handlers/tmct-method-history.mjs

@@ -0,0 +1,6 @@
+// tmct_method_history — commits that touched one method symbol.
+
+import { renderMethodHistory } from "../../domain/codegraph.mjs";
+import { symbolHandler } from "./kit.mjs";
+
+export const tmct_method_history = symbolHandler(renderMethodHistory);

package/src/tools/handlers/tmct-search.mjs

@@ -0,0 +1,22 @@
+// tmct_search — free-text/ranked lookup over the code-map, falling through to the
+// memory/corpus facts when a plain concept query misses the code-map entirely.
+
+import { ToolError } from "../../adapters/config.mjs";
+import { renderSearch } from "../../domain/codegraph.mjs";
+import { memoryFactRows, renderMemoryDefinition } from "../memory-fallthrough.mjs";
+
+export async function tmct_search(args, { graph, config }) {
+  const query = String(args?.query || "").trim();
+  const kind = String(args?.kind || "").trim();
+  if (!query && !kind) throw new ToolError("query is required");
+  const out = renderSearch(graph, query, {
+    kind,
+    decorator: String(args?.decorator || "").trim(),
+    name: String(args?.name || "").trim(),
+  });
+  if (!kind && /^no module matches/.test(out)) {
+    const fallback = renderMemoryDefinition(await memoryFactRows(config), query);
+    if (fallback) return fallback;
+  }
+  return out;
+}

package/src/tools/handlers/tmct-signature.mjs

@@ -0,0 +1,6 @@
+// tmct_signature — one symbol's API surface without the body.
+
+import { renderSignature } from "../../domain/codegraph.mjs";
+import { symbolHandler } from "./kit.mjs";
+
+export const tmct_signature = symbolHandler(renderSignature);

package/src/tools/handlers/tmct-snippet.mjs

@@ -0,0 +1,37 @@
+// tmct_snippet — the exact source of one symbol's line span, plus a one-line in-repo
+// call hint. Does its own safe span read rather than delegating to svc.snippet(), which
+// would drop the candidates / call hint / truncation notice this presentation carries.
+
+import { readFile } from "node:fs/promises";
+import { ToolError } from "../../adapters/config.mjs";
+import { readSpanSafe } from "../../adapters/source-slice.mjs";
+import { siteOf, callHint } from "../../domain/codegraph.mjs";
+import { requiredArg, resolveOrThrow, SNIPPET_MAX_LINES } from "./kit.mjs";
+
+export async function tmct_snippet(args, { graph, svc, repoRoot }) {
+  const symbol = requiredArg(args, "symbol");
+  const { match, candidates } = resolveOrThrow(svc, symbol, "symbol");
+  const site = siteOf(match);
+  if (!site) {
+    throw new ToolError(
+      `"${match.label}" (${match.class || "Entity"}) has no source span in the graph — ` +
+        "it is likely a module. Use tmct_describe for its contents, then tmct_snippet one of the functions/classes it defines.",
+    );
+  }
+  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})` : "";
+  const cand = candidates.length ? `\n(other matches: ${candidates.map((c) => c.label).join(", ")})` : "";
+  const hint = callHint(graph, match);
+  return `${header}\n${body}${note}${hint ? `\n${hint}` : ""}${cand}`;
+}

package/src/tools/handlers/tmct-subclasses.mjs

@@ -0,0 +1,16 @@
+// tmct_subclasses — a class's bases plus the transitive set of classes that extend it,
+// falling through to the memory/corpus isa-family facts for a concept the code-map
+// doesn't hold.
+
+import { renderSubclasses, resolveSymbol } from "../../domain/codegraph.mjs";
+import { memoryFactRows, renderMemorySubclasses } from "../memory-fallthrough.mjs";
+import { requiredArg, resolveOrThrow } from "./kit.mjs";
+
+export async function tmct_subclasses(args, { graph, svc, config }) {
+  const symbol = requiredArg(args, "class");
+  const { match } = resolveSymbol(svc.graph, symbol);
+  if (match) return renderSubclasses(graph, match); // code-map wins when present
+  const fallback = renderMemorySubclasses(await memoryFactRows(config), symbol);
+  if (fallback) return fallback;
+  resolveOrThrow(svc, symbol, "class"); // no code-map subclass + no memory fact → honest miss
+}

package/src/tools/handlers/tmct-tests-for.mjs

@@ -0,0 +1,6 @@
+// tmct_tests_for — the test modules covering a symbol or module.
+
+import { renderTestsFor } from "../../domain/codegraph.mjs";
+import { symbolHandler } from "./kit.mjs";
+
+export const tmct_tests_for = symbolHandler(renderTestsFor);

package/src/tools/handlers/tmct-untested.mjs

@@ -0,0 +1,7 @@
+// tmct_untested — source modules with no covering test module.
+
+import { renderUntested } from "../../domain/codegraph.mjs";
+
+export function tmct_untested(_args, { graph }) {
+  return renderUntested(graph);
+}

package/src/tools/memory-fallthrough.mjs

@@ -0,0 +1,65 @@
+// Read-only consumers of the conversational-memory graph (corpus facts, separate from
+// the code-map graph.json). The fall-through the concept-shaped tools use: when the
+// code-map resolves nothing for a concept query, answer from the reified isa-family
+// facts instead, always citing provenance.
+
+import { dirname } from "node:path";
+import { loadMemory, readFactRows, normFactTerm } from "../adapters/memory/core.mjs";
+
+// The reified isa-family predicates a memory Fact carries ("<subject> rdfs:subClassOf
+// <object>" / "rdf:type"): subject IS-A object. Subclasses of X = facts whose OBJECT is X;
+// superclasses of X = facts whose SUBJECT is X. (Matches chat.mjs's ISA_PREDICATES.)
+const ISA_PREDICATES = new Set(["rdfs:subClassOf", "rdf:type"]);
+const MEMORY_LIST_CAP = 40;
+
+/** Load the conversational-memory Facts as trust-bearing rows, failure-tolerant (no memory
+ *  store / unreadable → [], so the tool still returns its honest code-map miss). repoRoot is
+ *  the dir that CONTAINS .tmct/ (graphFile = <repo>/.tmct/graph.json), which is exactly the
+ *  `dir` loadMemory joins MEMORY_GRAPH_REL onto. */
+export async function memoryFactRows(config) {
+  try {
+    return readFactRows(await loadMemory(dirname(dirname(config.graphFile))));
+  } catch {
+    return [];
+  }
+}
+
+/** A short provenance receipt for a set of memory rows — distinct source strings, capped. */
+function memoryProvenance(rows) {
+  const provs = [...new Set(rows.map((r) => r.provenance).filter(Boolean))];
+  if (!provs.length) return "provenance: memory/corpus facts";
+  const shown = provs.slice(0, 2).join("; ");
+  return `provenance: ${shown}${provs.length > 2 ? `, +${provs.length - 2} more source(s)` : ""}`;
+}
+
+/** Subclasses of a concept from the reified isa-family facts (subjects of
+ *  "<subj> subClassOf <term>"). Null when the term names no such facts, so the caller can
+ *  keep the honest code-map miss. Provenance is always cited. */
+export function renderMemorySubclasses(rows, term) {
+  const t = normFactTerm(term);
+  const hits = rows.filter((r) => ISA_PREDICATES.has(r.predicate) && r.object === t);
+  if (!hits.length) return null;
+  const labels = [...new Set(hits.map((r) => r.subject))].sort();
+  const shown = labels.slice(0, MEMORY_LIST_CAP);
+  const tail = labels.length > MEMORY_LIST_CAP ? `\n  …+${labels.length - MEMORY_LIST_CAP} more` : "";
+  return `"${term}" is not a code-map entity — answering from memory/corpus facts. ` +
+    `${labels.length} known subclass(es):\n  ${shown.join("\n  ")}${tail}\n(${memoryProvenance(hits)})`;
+}
+
+/** A concept's DEFINITION from the isa-family facts — its superclasses ("is a …") plus a
+ *  count/sample of its known subclasses. Null when the term names no facts. */
+export function renderMemoryDefinition(rows, term) {
+  const t = normFactTerm(term);
+  const isa = rows.filter((r) => ISA_PREDICATES.has(r.predicate) && (r.subject === t || r.object === t));
+  if (!isa.length) return null;
+  const supers = [...new Set(isa.filter((r) => r.subject === t).map((r) => r.object))];
+  const subs = [...new Set(isa.filter((r) => r.object === t).map((r) => r.subject))].sort();
+  const lines = [`"${term}" is not a code-map entity — answering from memory/corpus facts.`];
+  if (supers.length) lines.push(`is a: ${supers.slice(0, MEMORY_LIST_CAP).join(", ")}`);
+  if (subs.length) {
+    const tail = subs.length > MEMORY_LIST_CAP ? `, +${subs.length - MEMORY_LIST_CAP} more` : "";
+    lines.push(`known subclasses (${subs.length}): ${subs.slice(0, MEMORY_LIST_CAP).join(", ")}${tail}`);
+  }
+  lines.push(`(${memoryProvenance(isa)})`);
+  return lines.join("\n");
+}

package/src/{schema-docs.mjs → tools/schema-docs.mjs}

@@ -1,5 +1,5 @@
 // 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
+// every entity class and predicate tmct's typed graph (src/adapters/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.

package/src/tools/server.mjs

@@ -0,0 +1,61 @@
+// tmct tool layer — query-only tools over the deterministic typed code-graph
+// artifact (<repo>/.tmct/graph.json). The graph source is a LOCAL file
+// (src/adapters/source.mjs) and tmct_search is a LOCAL lexical lookup (no remote API,
+// no LLM, no model calls anywhere). dispatchTool is the single internal entry
+// the chat surface and the `cli <tool>` route call into.
+//
+// This module is the dispatch entry only: it maps a tool name to the handler module
+// that owns it (handlers/, one module per tool), loads the graph once, builds the
+// typed service object (the Repository Interface) and hands both to the handler.
+// Each tool 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.
+
+import { readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { HOT_TOOLS } from "./definitions.mjs";
+import { ToolError } from "../adapters/config.mjs";
+import * as defaultSource from "../adapters/source.mjs";
+import { ask } from "../domain/ask.mjs";
+import { createGraphService } from "../adapters/providers/graph-service.mjs";
+import { loadGraph } from "./graph-load.mjs";
+import { HANDLERS } from "./handlers/index.mjs";
+import { setDefaultNlpAdapter } from "../domain/interpret/nlp-registry.mjs";
+import { setConstructionBanks } from "../domain/interpret/strategies/constructions.mjs";
+import { nlpAdapter } from "../adapters/ask-nlp.mjs";
+import { readConstructionFiles } from "../adapters/corpus/construction-banks.mjs";
+
+// Composition: the tool layer supplies the domain parser's default lemma/POS
+// adapter and the construction-grammar banks (lazy loader), so dispatchTool-
+// only consumers get the same NL tiers chat wires.
+setDefaultNlpAdapter(nlpAdapter);
+setConstructionBanks(readConstructionFiles);
+
+export { loadGraph } from "./graph-load.mjs";
+export { buildContextBundle } from "./handlers/tmct-context.mjs";
+
+// Tiered tool surface: the hot tools carry full descriptions/schemas in this
+// catalog; every COLD tool (describe/members/impact/history/…) is still served
+// by dispatchTool below and is reachable via the CLI `cli <tool>` route +
+// the <repo>/.tmct/TOOLS.md catalog `tmct init` writes (renderToolsCatalog). Both
+// tiers, and the schemas themselves, come from the tool definitions.
+export const TOOLS = HOT_TOOLS.map(({ name, agentDescription, inputSchema }) => ({
+  name,
+  description: agentDescription,
+  inputSchema,
+}));
+
+export async function dispatchTool(name, args, { config, source = defaultSource, tel = null } = {}) {
+  // Reject an unknown tool BEFORE touching the graph — an unknown name never
+  // triggers a load. hasOwn, so an inherited name ("constructor", "toString")
+  // is unknown rather than a callable found on the prototype chain.
+  if (!Object.hasOwn(HANDLERS, name)) throw new ToolError(`unknown tool: ${name}`);
+  const handle = HANDLERS[name];
+  if (handle.ownsGraphLoad) return handle(args, { config, source, tel });
+  const graph = await loadGraph(config, source);
+  // repo root = the dir containing .tmct/ (graphFile = <repo>/.tmct/graph.json). Passed to
+  // createGraphService so svc.snippet()/svc.context() are usable directly, and on to the
+  // handlers that do their own safe source reads.
+  const repoRoot = dirname(dirname(config.graphFile));
+  const svc = createGraphService(graph, { sourceAccess: true, repoRoot, readFile, tel, ask });
+  return handle(args, { graph, svc, config, repoRoot });
+}

package/src/answer-variants.mjs

@@ -1,39 +0,0 @@
-// answer-variants.mjs — deterministic, committed answer-phrasing variety for
-// a curated set of answer templates (answer-variants.json).
-//
-// Selection is a pure hash of (poolId, key), never Math.random/Date.now, so
-// output is byte-identical across runs (pinnable in tests). Load is lazy and
-// failure-tolerant (missing file, or a stubbed node:fs in the browser bundle,
-// both degrade to returning `base`) rather than throwing.
-
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-import { createHash } from "node:crypto";
-
-const DATA_FILE = join(dirname(fileURLToPath(import.meta.url)), "answer-variants.json");
-
-let dataCache; // undefined = not yet attempted; null = load failed/unavailable
-function loadData() {
-  if (dataCache !== undefined) return dataCache;
-  try {
-    dataCache = JSON.parse(readFileSync(DATA_FILE, "utf8"));
-  } catch {
-    dataCache = null;
-  }
-  return dataCache;
-}
-
-/** Deterministically choose `base` or one of `poolId`'s committed variants,
- *  keyed on `key`. Any failure (unknown pool, unreadable data, falsy `key`)
- *  falls back to `base`. */
-export function pickPhrase(poolId, key, base) {
-  if (!key) return base;
-  const data = loadData();
-  const variants = data?.pools?.[poolId]?.variants;
-  if (!Array.isArray(variants) || !variants.length) return base;
-  const forms = [base, ...variants];
-  const digest = createHash("sha256").update(`${poolId}:${String(key)}`).digest();
-  const idx = digest[0] % forms.length;
-  return forms[idx];
-}

package/src/hash.mjs

@@ -1,24 +0,0 @@
-// hash.mjs — the single home for tmct's content-address hash.
-//
-// FNV-1a 32-bit is deliberately home-grown: it must be synchronous, browser-safe,
-// dependency-free, and — critically — CROSS-VERSION STABLE, because fact ids are
-// content-addressed by it and a fact's id is its identity across the whole memory
-// graph. Every library candidate fails at least one of those; this eight-line
-// function fails none. It lives here, once, so the fact-id contract has exactly
-// one definition.
-
-/** FNV-1a 32-bit. Returns the unsigned 32-bit integer (0 … 2^32−1). */
-export function fnv1a32(str) {
-  let h = 0x811c9dc5;
-  for (let i = 0; i < str.length; i += 1) {
-    h ^= str.charCodeAt(i);
-    h = Math.imul(h, 0x01000193);
-  }
-  return h >>> 0;
-}
-
-/** FNV-1a 32-bit as a zero-padded 8-char hex string — the stable content-address
- *  used for fact ids (`fact:<hex>`). Same (s,p,o) → same id → upsert, never a dup. */
-export function fnv1aHex(str) {
-  return fnv1a32(str).toString(16).padStart(8, "0");
-}