@polycode-projects/the-mechanical-code-talker 0.7.1 → 0.8.0

package/src/router/resolver.mjs

@@ -0,0 +1,293 @@
+// src/router/resolver.mjs — Stage 1 of the capability router (PLAN_CAPABILITY_ROUTER.md):
+// THE RESOLVER. Turn a request into a SELECTED registry capability with bound
+// arguments, by unification + backward chaining over capabilities-as-facts
+// (a mini-Datalog/SLD step, exactly the "open-condition satisfaction" the plan
+// names). Deterministic, no-LLM, glass-box: every choice is provable.
+//
+// THE CORE is the ask-kind -> capability MAPPING. A request becomes an epistemic
+// GOAL `(knows <topic> ?of)`; each capability's add-effect declares which topic
+// it achieves (registry.mjs `knows(topic, of)`); backward chaining finds the
+// capability whose add-list unifies with the goal and binds ?of to the request's
+// object term. Three fact sources feed the SAME backward-chaining step:
+//
+//   1. THE COMMAND REGISTER (server-http.mjs `selectTool`, the terse verbs
+//      "describe X" / "callers X" / "untested") — exact + unambiguous, tried
+//      FIRST because a terse command mis-parses through the NL grammar (e.g.
+//      "callees Widget.render" keyword-spots to shape:reverse/kind:calls, which
+//      would wrongly route to callers). A literal command verb is ground truth.
+//   2. THE NL PARSE (ask.mjs `parseQuery` -> {shape, kind, entityType, object}) —
+//      the relational grammar ("which functions call X", "what does X export").
+//      NL_INTENTS maps a {shape,kind} to the epistemic TOPIC; backwardChain maps
+//      the topic to the capability. This is the Stage-1 deliverable proper.
+//   3. IMPERATIVE INTENT FRAMES (Stage 2, this module's FRAMES table) — curated
+//      phrasings the relational grammar does not carry ("blast radius of X",
+//      "who calls X", "search for X"): a regex -> {topic, arg}. Same backward
+//      chaining (topic -> capability), same resolveObject binding.
+//
+// ENTITY BINDING is DELEGATED to `resolveObject` (ask.mjs — the tiered lemma/
+// fuzzy binding oracle with honest ambiguity). This module NEVER re-implements
+// resolution: the registry's `resolves(param, as)` precondition maps exactly to
+// a resolveObject call, and an ambiguous / no-match term is an HONEST REFUSE,
+// never a guess. On any no-fit -> refuse.
+//
+// Pure-ish: mapParse/mapFrame/backwardChain/commandCapability are pure; resolveOne
+// is async only because it consults ctx.resolve (the graph binding oracle) and
+// ctx.dispatch (executes the grounded call). No network, no Date.now.
+
+import { parseQuery } from "../ask.mjs";
+import { selectTool } from "../server-http.mjs";
+import {
+  capabilities, capabilityByName, preconditionsOf, effectsOf, PRECOND,
+} from "./registry.mjs";
+import { hallucinationsIn } from "../../agentbench/grade.mjs";
+
+// ---- the ask-kind -> epistemic-topic MAPPING (the Stage-1 core) --------------
+// Keyed `${shape}:${kind}` off parseQuery's simple-clause output. The VALUE is
+// the epistemic TOPIC a capability's add-effect must achieve; backwardChain then
+// unifies that topic with the registry (capabilities-as-facts). Every entry's
+// topic MUST be achievable by exactly one registered capability (the bidirectional
+// conformance test proves it). `arg` is the parameter grain the object binds to.
+export const NL_INTENTS = Object.freeze({
+  "reverse:calls": { topic: "callers", arg: "symbol" }, // "which fns call X" -> callers of X
+  "forward:calls": { topic: "callees", arg: "symbol" }, // "what does X call"  -> callees of X
+  "reverse:tests": { topic: "tests", arg: "symbol" }, // "which tests cover X"
+  "forward:tests": { topic: "tests", arg: "symbol" }, // "what tests X"
+  "reverse:inherits": { topic: "subclasses", arg: "class" }, // "which classes extend X"
+  "forward:reexports": { topic: "exports", arg: "module" }, // "what does X export"
+  "forward:contains": { topic: "members", arg: "class" }, // "what does X contain" -> members of X
+  "when:touches": { topic: "history", arg: "symbol" }, // "when did X change" -> commit history
+  "forward:cochange": { topic: "cochanges", arg: "symbol" }, // "what changes with X"
+  "reverse:cochange": { topic: "cochanges", arg: "symbol" },
+});
+
+// ---- ask-vocab RELATION kinds with NO capability — the HONEST ceiling --------
+// Every ask-vocab.mjs RELATIONS key must be either mapped (above) or listed here
+// with a reason (the bidirectional conformance test enforces the partition — no
+// silent gap). These are relations tmct's grammar SPEAKS but the read-only
+// graph-query registry has no operator for: routing them anywhere would be a
+// mis-route, so the resolver REFUSES (never a guess).
+export const UNMAPPED_KINDS = Object.freeze({
+  imports: "no importer/imports query tool in the registry (there is no tmct_imports); refusing beats mis-routing to calls",
+  uses: "a query-side UNION (imports+calls+callsSymbol) with no single capability; a router that must emit ONE call cannot honour it — refuse",
+  defines: "Module->symbol `defines` has no dedicated capability (tmct_members is Class-scoped `contains`); refuse rather than answer a different grain",
+});
+
+// ---- capabilities the NL surface cannot reach today (named, not accidental) ---
+// A declared capability with no NL/command/frame path is a ROUTING GAP. The
+// conformance test FAILS on an untagged gap; a genuinely-unreachable cap must be
+// tagged HERE with the Stage it needs, so the ceiling is honest rather than a
+// silent low-completion refuse. (Coordinator reinforcement 2.)
+export const NOT_NL_REACHABLE = Object.freeze({
+  tmct_calls: "the raw call-edge dump collides with tmct_callees on every NL phrasing (\"what does X call\" -> callees) and has no command verb; distinguishing it needs a Stage-2 intent frame we have not authored",
+});
+
+// ---- imperative intent FRAMES (Stage 2 — fills what the relational grammar and
+// the command register both miss). regex -> { topic, arg | noArg }. `arg` names
+// the parameter grain; the entity is pulled by extractEntity (or, for search, the
+// residual query text). Ordered: first match wins. Every frame's topic is
+// backward-chained to a capability just like an NL intent, so the frame table
+// adds PHRASINGS, never a new routing path. ----
+export const FRAMES = Object.freeze([
+  { re: /\buntested\b|\bwithout\s+(?:a\s+)?tests?\b|\bhas\s+no\s+tests?\b|\bneeds?\s+(?:a\s+)?tests?\b/i, topic: "untested", noArg: true },
+  { re: /\bblast\s*radius\b|\bimpacts?\b|\bimpacted\b|what\s+(?:a\s+)?change.*(?:reach|affect|touch)|what\s+(?:depends?\s+on|dependents?)\b/i, topic: "impact", arg: "module" },
+  { re: /\bcallees?\b|what\s+does\s+\S+\s+call\b/i, topic: "callees", arg: "symbol" },
+  { re: /\bcallers?\b|who\s+calls\b|what\s+calls\b/i, topic: "callers", arg: "symbol" },
+  { re: /\btests?\b.*\b(?:for|cover|covering|of)\b|which\s+tests?\b|covers?\b|covered\b|test\s+coverage\b/i, topic: "tests", arg: "symbol" },
+  { re: /\bcochang|change[- ]coupl/i, topic: "cochanges", arg: "symbol" },
+  { re: /\bexports?\b|\bpublic\s+api\b/i, topic: "exports", arg: "module" },
+  { re: /\bsubclasses?\b|children\s+of\b|\bextends?\b/i, topic: "subclasses", arg: "class" },
+  { re: /\bmembers?\b|\bmethods?\s+of\b|\battributes?\s+of\b/i, topic: "members", arg: "class" },
+  { re: /\bhistory\b|who\s+changed\b|commits?\s+(?:that\s+)?touch/i, topic: "history", arg: "symbol" },
+  { re: /\bsignature\b/i, topic: "signature", arg: "symbol" },
+  { re: /\bdescribe\b|what\s+is\b|tell\s+me\s+about\b|definition\s+of\b/i, topic: "description", arg: "symbol" },
+  { re: /\bsearch\b|\bfind\b|look\s+for\b/i, topic: "matches", arg: "query" },
+]);
+
+// ---- backward chaining (the SLD/Datalog step) --------------------------------
+
+/** Backward-chain a goal `(knows <topic> ?of)` to the registered capability whose
+ *  add-effect ACHIEVES it. Pure over the registry; returns the capability or null.
+ *  This is the whole selection primitive — a capability is chosen ONLY because its
+ *  declared effect unifies with the request's epistemic goal, never by name. */
+export function backwardChain(topic) {
+  for (const cap of capabilities()) {
+    if (effectsOf(cap.name).add.some((e) => e.topic === topic)) return cap;
+  }
+  return null;
+}
+
+// The stopword set for the imperative-frame entity extractor (Stage-2 slot
+// filling). Deliberately generous: a wrong pick is caught by the resolveObject
+// miss -> honest refuse, never emitted.
+const STOP = new Set([
+  "what", "whats", "which", "who", "whom", "does", "do", "did", "is", "are", "the", "a", "an",
+  "of", "for", "to", "in", "on", "by", "me", "us", "tell", "about", "show", "list", "give", "get",
+  "assess", "check", "then", "and", "or", "instead", "if", "end", "up", "its", "it", "this", "that",
+  "call", "calls", "called", "caller", "callers", "callee", "callees", "test", "tests", "tested",
+  "cover", "covers", "covering", "describe", "description", "define", "definition", "impact",
+  "member", "members", "method", "methods", "attribute", "attributes", "subclass", "subclasses",
+  "export", "exports", "history", "commit", "commits", "signature", "search", "find", "look",
+  "module", "modules", "class", "classes", "function", "functions", "symbol", "symbols",
+  "untested", "blast", "radius", "change", "changes", "changing", "reach", "reaches", "affect", "affects",
+]);
+
+/** Pull one entity token from a request (imperative-frame slot-filling). Prefer a
+ *  path/dotted/CamelCase token, else the last non-stopword identifier. "" if none. */
+export function extractEntity(request) {
+  const tokens = String(request).match(/[A-Za-z_][A-Za-z0-9_./-]*/g) || [];
+  const pool = tokens.filter((t) => !STOP.has(t.toLowerCase()));
+  const strong = pool.filter((t) => /[./]/.test(t) || /^[A-Z][a-z]/.test(t) || /\.[a-z]+$/.test(t));
+  const pick = strong.length ? strong : pool;
+  return pick.length ? pick[pick.length - 1] : "";
+}
+
+/** The residual search query: strip the leading search/find verb + a filler "for". */
+function searchQuery(request) {
+  return String(request).replace(/^\s*(?:search|find|look\s+for|look)\s+(?:for\s+)?/i, "").trim();
+}
+
+// ---- request -> capability + raw term (PURE, no binding yet) -----------------
+
+/** Map a parseQuery simple-clause parse to a capability selection, or a refusal,
+ *  or null (not an NL shape this resolver routes). Returns one of:
+ *    { name, arg, term, topic, source:"nl", why:[...] }   — a selection
+ *    { refuse:true, reason }                               — an honest no-fit
+ *    null                                                   — parse absent / not simple
+ *  Backward-chains topic -> capability so selection is provable, never by name. */
+export function mapParse(parse) {
+  if (!parse || parse.node || !parse.shape) return null; // compositional/absent -> not here
+  const { shape, kind } = parse;
+  // yes/no + locational/vocabulary shapes have no read-only query operator
+  if (shape === "ask") return { refuse: true, reason: "a yes/no `does X <verb> Y` question has no capability that emits it (the registry answers WHAT, not WHETHER)" };
+  if (shape === "where" || shape === "meta" || shape === "mentions") {
+    return { refuse: true, reason: `the "${shape}" shape (location/vocabulary/prose) has no read-only graph-query capability` };
+  }
+  const intent = NL_INTENTS[`${shape}:${kind}`];
+  if (!intent) {
+    const reason = UNMAPPED_KINDS[kind] || `no capability maps the ${shape}/${kind} intent`;
+    return { refuse: true, reason };
+  }
+  const cap = backwardChain(intent.topic);
+  if (!cap) return { refuse: true, reason: `backward chaining found no capability achieving (knows ${intent.topic})` };
+  return {
+    name: cap.name, arg: intent.arg, term: String(parse.object || "").trim(), topic: intent.topic, source: "nl",
+    why: [`parse ${shape}/${kind} => goal (knows ${intent.topic} ?${intent.arg})`, `backward-chain => ${cap.name} (its add-effect achieves ${intent.topic})`],
+  };
+}
+
+/** Match an imperative FRAME. Returns { name, arg|noArg, term, topic, source:"frame", why }
+ *  or null. Backward-chains the frame's topic to a capability. */
+export function mapFrame(request) {
+  for (const f of FRAMES) {
+    if (!f.re.test(request)) continue;
+    const cap = backwardChain(f.topic);
+    if (!cap) continue;
+    if (f.noArg) return { name: cap.name, noArg: true, topic: f.topic, source: "frame", why: [`imperative frame => goal (knows ${f.topic})`, `backward-chain => ${cap.name}`] };
+    const term = f.arg === "query" ? searchQuery(request) : extractEntity(request);
+    return { name: cap.name, arg: f.arg, term, topic: f.topic, source: "frame", why: [`imperative frame => goal (knows ${f.topic} ?${f.arg})`, `backward-chain => ${cap.name}`] };
+  }
+  return null;
+}
+
+/** The command register (server-http.mjs selectTool) filtered to the registry.
+ *  Returns { name, input, source:"command", why } or null. selectTool binds the
+ *  arg from the terse command; we re-clean a search query (its raw join keeps a
+ *  stray "for"). Never reaches outside the declared set. */
+export function commandCapability(request, declaredNames) {
+  const sel = selectTool(request, new Set(declaredNames));
+  if (!sel || !capabilityByName(sel.name)) return null;
+  const input = { ...sel.input };
+  if (sel.name === "tmct_search" && input.query != null) input.query = searchQuery(request) || String(input.query);
+  return { name: sel.name, input, source: "command", why: [`command register: "${String(request).trim().split(/\s+/)[0]}" => ${sel.name}`] };
+}
+
+// ---- the full single-call resolver (async — binds + grounds) -----------------
+
+/** Build the glass-box proof chain for a grounded single call: its preconditions
+ *  (graphLoaded + resolves(param) with the BOUND value + any-present) then the
+ *  epistemic add-effect. Dispatch has SUCCEEDED, so `resolves` steps are ok. */
+export function proofFor(name, input) {
+  const steps = [];
+  for (const pre of preconditionsOf(name)) {
+    if (pre.pred === PRECOND.graphLoaded) steps.push({ step: "precondition", pred: pre.pred, ok: true });
+    else if (pre.pred === PRECOND.resolves) steps.push({ step: "precondition", pred: pre.pred, param: pre.param, value: input[pre.param] ?? null, ok: true });
+    else if (pre.pred === PRECOND.anyPresent) steps.push({ step: "precondition", pred: pre.pred, params: pre.params, ok: pre.params.some((k) => input[k]) });
+  }
+  for (const eff of effectsOf(name).add) steps.push({ step: "effect", pred: eff.pred, topic: eff.topic, of: eff.of });
+  return steps;
+}
+
+const REFUSE = (why) => ({ selected: null, refused: true, reason: why });
+
+/** Select a capability for a request and BIND its arguments — the full resolver.
+ *  Order: command register -> NL parse -> imperative frame. On a bound selection
+ *  it delegates entity binding to ctx.resolve (resolveObject) and, unless
+ *  `execute:false`, grounds it via ctx.dispatch. Returns
+ *    { selected:{name,input}, proof, why, resolved, observed? }  — a grounded call
+ *    { selected:null, refused:true, reason }                     — an honest refusal
+ *  NEVER emits an ungrounded / ambiguous / undeclared call. */
+export async function resolveOne(request, declaredNames, ctx, { execute = true } = {}) {
+  const declared = new Set(declaredNames);
+
+  // 1. command register (exact) 2. NL parse 3. imperative frame. An NL-parse
+  //    REFUSAL is NOT terminal: a shape with no relational operator ("what is the
+  //    impact of X", "list what covers X") can still be an imperative FRAME hit,
+  //    so we fall through and only surface the NL reason if the frame misses too.
+  let pick = commandCapability(request, declared);
+  let nlRefuse = null;
+  if (!pick) {
+    const mapped = mapParse(parseQuery(request));
+    if (mapped && !mapped.refuse) pick = mapped;
+    else if (mapped && mapped.refuse) nlRefuse = mapped.reason;
+  }
+  if (!pick) pick = mapFrame(request);
+  if (!pick) return REFUSE(nlRefuse || "no command, NL parse, or imperative frame selects a capability");
+  let why = pick.why ?? [];
+  if (!declared.has(pick.name)) return REFUSE(`selected ${pick.name} but it is not in the declared toolset`);
+
+  // build the bound input. A command pick already carries a bound input; an NL /
+  // frame pick carries a raw term that we BIND via resolveObject (the oracle).
+  let input = pick.input ? { ...pick.input } : {};
+  let resolved = null;
+  if (!pick.input && !pick.noArg) {
+    const term = String(pick.term || "").trim();
+    if (!term) return REFUSE(`the ${pick.topic} intent named no entity to bind`);
+    // DELEGATE binding to resolveObject — the resolves(param,as) precondition.
+    const r = ctx.resolve ? ctx.resolve(term) : { match: { label: term }, ambiguous: false };
+    if (!r || !r.match) return REFUSE(`"${term}" does not resolve to any graph entity (honest miss)`);
+    if (r.ambiguous) return REFUSE(`"${term}" is ambiguous (${[r.match, ...(r.candidates || [])].slice(0, 4).map((m) => m.label).join(", ")}) — narrow it`);
+    resolved = r.match;
+    input = { [pick.arg]: r.match.label };
+    why = [...why, `resolveObject: "${term}" => ${r.match.label} (${r.match.class || "?"}, tier ${r.tier})`];
+  }
+
+  const call = { name: pick.name, input };
+  // the same zero-hallucination gate the grader enforces — self-check before emit.
+  const problems = hallucinationsIn(call, [...declared]);
+  if (problems.length) return REFUSE(`bound call did not validate: ${problems.map((p) => p.reason).join(",")}`);
+
+  // ground it: a ToolError (unresolvable entity) is an honest miss -> refuse.
+  if (execute && ctx.dispatch) {
+    const res = await ctx.dispatch(pick.name, input);
+    if (!res.ok) return REFUSE(`unresolvable at dispatch: ${res.error}`);
+    return { selected: call, proof: proofFor(pick.name, input), why, resolved: res.resolved ?? resolved, observed: String(res.text ?? "").slice(0, 240) };
+  }
+  return { selected: call, proof: proofFor(pick.name, input), why, resolved };
+}
+
+// ---- reachability (used by the bidirectional conformance test + docs) ---------
+
+/** The epistemic topics some NL intent or imperative frame can reach. */
+export function nlReachableTopics() {
+  const topics = new Set();
+  for (const v of Object.values(NL_INTENTS)) topics.add(v.topic);
+  for (const f of FRAMES) topics.add(f.topic);
+  return topics;
+}
+
+/** Every capability an NL intent or frame can reach (by name), via backwardChain. */
+export function reachableCapabilityNames() {
+  const names = new Set();
+  for (const topic of nlReachableTopics()) { const c = backwardChain(topic); if (c) names.add(c.name); }
+  return names;
+}

package/src/server-http.mjs

@@ -0,0 +1,296 @@
+// 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`:
+//
+//   - 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.
+//
+// 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.
+
+import { createServer } from "node:http";
+import { runTurn, COMMANDS, asBareCommand, isConversational } from "./chat.mjs";
+import { TOOLS } from "./server.mjs";
+import { parseEntities } from "./codegraph.mjs";
+import { uuidv7 } from "./uuid.mjs";
+import * as defaultSource from "./source.mjs";
+
+/** The zero usage every response carries — the meter prices tmct as the $0 floor. */
+const ZERO_USAGE = { input_tokens: 0, output_tokens: 0 };
+
+/** The tmct tools dispatchTool can back (the set the shim will emit a tool_use for).
+ *  A declared tool outside this set is ignored for emission (the request falls
+ *  through to a text answer) — the shim never emits a call it cannot ground. The
+ *  COMMANDS map (chat.mjs) names the richer graph tools; TOOLS names the hot
+ *  catalog. Their union is what dispatchTool serves. */
+const BACKED_TOOLS = new Set([
+  ...TOOLS.map((t) => t.name),
+  ...Object.values(COMMANDS).map((s) => s.tool),
+]);
+
+/** Flatten a message's `content` (a string OR a content-block array) into plain
+ *  text — concatenating the `text` blocks. Non-text blocks are ignored here. */
+function textOfContent(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((b) => b && b.type === "text" && typeof b.text === "string")
+    .map((b) => b.text)
+    .join("\n")
+    .trim();
+}
+
+/** The last message with the given role, or null. */
+function lastMessageOfRole(messages, role) {
+  if (!Array.isArray(messages)) return null;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i] && messages[i].role === role) return messages[i];
+  }
+  return null;
+}
+
+/** The first tool_result block in a message's content array, or null. The caller
+ *  returns one of these after executing a tool_use — its presence means the loop
+ *  is closing and we answer with end_turn. */
+function firstToolResult(message) {
+  const content = message && message.content;
+  if (!Array.isArray(content)) return null;
+  return content.find((b) => b && b.type === "tool_result") || null;
+}
+
+/** Render a tool_result block's `content` (string OR block array OR arbitrary
+ *  value) back to text — what the caller reported when it executed the tool. */
+function toolResultText(block) {
+  const c = block && block.content;
+  if (typeof c === "string") return c;
+  if (Array.isArray(c)) return textOfContent(c);
+  if (c == null) return "";
+  try { return JSON.stringify(c); } catch { return String(c); }
+}
+
+/**
+ * Decide whether a user turn maps to a DECLARED, dispatch-backed graph-query
+ * tool, and bind its arguments. Deterministic, in-ethos (no NL guessing beyond
+ * the chat surface's own command routing):
+ *
+ *   1. A slash/bare command that names a tmct tool ("describe X", "/callers X",
+ *      "untested") → that tool with its argument bound from the exact arg key the
+ *      dispatchTool switch reads (COMMANDS in chat.mjs). Only when the tool is
+ *      declared by the caller.
+ *   2. Otherwise, a non-conversational structural question → tmct_ask{query:…},
+ *      when tmct_ask is declared. Small-talk (isConversational) never emits a
+ *      call — it falls through to a text answer.
+ *
+ * Returns { name, input } or null (→ answer as text).
+ */
+export function selectTool(text, declaredNames) {
+  const t = String(text || "").trim();
+  if (!t) return null;
+
+  // 1. explicit command form → a specific tool, argument bound
+  const cmdLine = t.startsWith("/") ? t : asBareCommand(t);
+  if (cmdLine) {
+    const [first, ...restTok] = cmdLine.replace(/^\//, "").split(/\s+/);
+    const spec = COMMANDS[String(first).toLowerCase()];
+    if (spec && declaredNames.has(spec.tool) && BACKED_TOOLS.has(spec.tool)) {
+      const input = {};
+      if (spec.arg) {
+        const val = restTok.join(" ").trim();
+        if (val) input[spec.arg] = val;
+        // an entity command with no argument can't bind a call — fall through
+        else if (!spec.optional) return askFallback(t, declaredNames);
+      }
+      return { name: spec.tool, input };
+    }
+  }
+
+  // 2. structural question → tmct_ask, unless it's small-talk
+  return askFallback(t, declaredNames);
+}
+
+/** The tmct_ask fallback: emit tmct_ask{query} for a non-conversational line when
+ *  the caller declared tmct_ask; otherwise null (→ text answer). */
+function askFallback(text, declaredNames) {
+  if (declaredNames.has("tmct_ask") && BACKED_TOOLS.has("tmct_ask") && !isConversational(text)) {
+    return { name: "tmct_ask", input: { query: text } };
+  }
+  return null;
+}
+
+/** Build the assistant message envelope shared by every branch. */
+function assistantMessage(model, content, stopReason) {
+  return {
+    id: `msg_${uuidv7().replace(/-/g, "")}`,
+    type: "message",
+    role: "assistant",
+    model: model || "tmct",
+    content,
+    stop_reason: stopReason,
+    stop_sequence: null,
+    usage: { ...ZERO_USAGE },
+  };
+}
+
+/**
+ * Produce the Messages-API response for one request body. Pure over its inputs
+ * (the loaded graph + config), so it is unit-testable without a socket.
+ *   - a returned tool_result → end_turn text (relay the tool's output)
+ *   - a mapped, declared graph tool → tool_use
+ *   - otherwise → end_turn text via runTurn
+ */
+export async function respondToMessages(body, { config, graph, source = defaultSource } = {}) {
+  const { model, messages, tools } = body || {};
+  const declaredNames = new Set(
+    (Array.isArray(tools) ? tools : []).map((t) => t && t.name).filter(Boolean),
+  );
+
+  // Closing the loop: the caller executed our tool_use and returned a
+  // tool_result. Relay it as the final, cited answer with end_turn.
+  const lastUser = lastMessageOfRole(messages, "user");
+  const tr = firstToolResult(lastUser);
+  if (tr) {
+    const text = toolResultText(tr) || "(the tool returned no output)";
+    return assistantMessage(model, [{ type: "text", text }], "end_turn");
+  }
+
+  const userText = textOfContent(lastUser && lastUser.content);
+
+  // tool_use emission: a declared, dispatch-backed graph tool the request maps to.
+  if (declaredNames.size) {
+    const sel = selectTool(userText, declaredNames);
+    if (sel) {
+      const block = {
+        type: "tool_use",
+        id: `toolu_${uuidv7().replace(/-/g, "")}`,
+        name: sel.name,
+        input: sel.input,
+      };
+      return assistantMessage(model, [block], "tool_use");
+    }
+  }
+
+  // text answer: the cited, read-only answer the chat surface gives. memoryDir is
+  // null so the endpoint is PURE — no session artifacts, no writes, deterministic.
+  const { answer } = await runTurn(userText, { config, graph, source, memoryDir: null });
+  return assistantMessage(model, [{ type: "text", text: answer }], "end_turn");
+}
+
+/** Self-description payload (GET /) — lets a routing target discover the endpoint
+ *  and the tools tmct can back with just an HTTP GET. */
+function describe(config) {
+  return {
+    service: "tmct",
+    description: "Anthropic Messages API-compatible, deterministic, no-LLM graph router (the $0 floor).",
+    endpoint: { method: "POST", path: "/v1/messages" },
+    graph: config && config.graphFile,
+    tools: TOOLS.map((t) => ({ name: t.name, description: t.description, input_schema: t.inputSchema })),
+    usage_pricing: ZERO_USAGE,
+  };
+}
+
+async function readBody(req, limit = 5 * 1024 * 1024) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on("data", (c) => {
+      size += c.length;
+      if (size > limit) { reject(new Error("request body too large")); req.destroy(); return; }
+      chunks.push(c);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+
+function sendJson(res, status, obj) {
+  const payload = JSON.stringify(obj);
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+  res.end(payload);
+}
+
+/** An Anthropic-style error envelope. */
+function sendError(res, status, type, message) {
+  sendJson(res, status, { type: "error", error: { type, message } });
+}
+
+/**
+ * Start the HTTP server. Loads the graph once (tolerant: a missing artifact is
+ * the empty bootstrap graph, never an error). Returns { server, url, host, port,
+ * config, close } — `close()` shuts the socket cleanly (no hanging handles).
+ *
+ *   config — { graphFile } (build via configFor(repoPath) in bin/tmct.mjs)
+ *   host   — bind address (default 127.0.0.1)
+ *   port   — TCP port; 0 picks an ephemeral port (tests)
+ */
+export async function startServer({ config, host = "127.0.0.1", port = 0, source = defaultSource } = {}) {
+  if (!config || !config.graphFile) throw new Error("startServer requires config.graphFile");
+  // Load the graph once, up front. A missing artifact loads as the empty
+  // bootstrap graph — runTurn tolerates it (an honest empty/orienting answer).
+  const graph = parseEntities(await source.fetchEntities(config));
+
+  const server = createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url, "http://localhost");
+      if (req.method === "GET" && (url.pathname === "/" || url.pathname === "/v1/models")) {
+        sendJson(res, 200, describe(config));
+        return;
+      }
+      if (url.pathname !== "/v1/messages") {
+        sendError(res, 404, "not_found_error", `no route ${req.method} ${url.pathname}`);
+        return;
+      }
+      if (req.method !== "POST") {
+        sendError(res, 405, "invalid_request_error", "POST /v1/messages");
+        return;
+      }
+      let body;
+      try {
+        body = JSON.parse((await readBody(req)) || "{}");
+      } catch {
+        sendError(res, 400, "invalid_request_error", "request body is not valid JSON");
+        return;
+      }
+      if (!body || !Array.isArray(body.messages)) {
+        sendError(res, 400, "invalid_request_error", "`messages` array is required");
+        return;
+      }
+      const out = await respondToMessages(body, { config, graph, source });
+      sendJson(res, 200, out);
+    } catch (e) {
+      sendError(res, 500, "api_error", e && e.message ? e.message : String(e));
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, () => { server.removeListener("error", reject); resolve(); });
+  });
+
+  const addr = server.address();
+  const boundPort = typeof addr === "object" && addr ? addr.port : port;
+  const url = `http://${host}:${boundPort}`;
+
+  return {
+    server,
+    host,
+    port: boundPort,
+    url,
+    config,
+    close: () => new Promise((resolve) => server.close(() => resolve())),
+  };
+}