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

package/src/router/registry.mjs

@@ -0,0 +1,271 @@
+// src/router/registry.mjs — Stage 0 of the capability router (PLAN_CAPABILITY_ROUTER.md).
+//
+// Each tmct tool is modelled as a STRIPS/PDDL operator declared as DATA:
+// a `Capability` with typed `Parameter`s, `Precondition`s, and `Effect`s
+// (an add-list / delete-list). This is the direct mapping the reference note
+// docs/references/planning/STRIPS_PDDL.md calls "the most direct in the whole
+// set": a capability IS a STRIPS operator expressed in tmct's OWL vocabulary.
+//
+//   - Preconditions are the SAFETY GATE — a capability will not fire unless its
+//     preconditions are provably satisfied (Stage 4, the guardrail, reads these).
+//     This is why the router REFUSES rather than emitting an unsafe call, the
+//     same discipline as tmct's honest miss.
+//   - Effects are the PROOF CHAIN — for a read-only query tool the effect is
+//     EPISTEMIC (it makes a fact KNOWN to the agent), never a world mutation, so
+//     every graph-query capability has an EMPTY delete-list (the STRIPS closed-
+//     world assumption: what is not deleted is unchanged, and a query changes
+//     nothing in the world). Stage 1 (the resolver) backward-chains from a goal
+//     `(knows <topic> ?x)` to the capability whose add-list achieves it.
+//
+// This module is PURE: plain frozen data + pure accessor functions, NO I/O. The
+// tool NAMES + parameter ARG KEYS are the exact ones src/server.mjs `dispatchTool`
+// reads (verified against its switch), so a bound call this registry validates is
+// directly dispatchable. Stage 1 (resolver) and Stage 4 (guardrail) consume this
+// substrate; nothing here imports the graph or the network.
+
+// ---- OWL-labelled vocabulary (tmct's style: urn:tmct:… prefixes) ------------
+// The registry declares its OWN vocabulary the way every tmct graph artifact
+// does (see the fixture's `prefixes` block + the schema-doc individuals). A
+// capability is a `cap:Capability` individual; its parts are `cap:Parameter`,
+// `cap:Precondition`, `cap:Effect`. Parameter TYPES range over the same seon/mgx
+// entity classes the code graph already speaks (Module, Class, Function, …).
+
+export const PREFIXES = Object.freeze({
+  cap: "urn:tmct:cap#", // the capability/operator vocabulary (this module)
+  mgx: "urn:tmct:mgx#", // tmct's code-graph predicates (imports/calls/tests/…)
+  seon: "http://se-on.org/ontologies/seon.owl#", // software-evolution ontology classes
+});
+
+// The OWL classes this registry mints individuals of.
+export const VOCAB = Object.freeze({
+  Capability: "cap:Capability", // rdf:type of a declared tool/operator
+  Parameter: "cap:Parameter",
+  Precondition: "cap:Precondition",
+  Effect: "cap:Effect",
+});
+
+// Parameter entity-KINDS — the seon/mgx classes a slot ranges over. `Query` and
+// `Kind`/`Package` are free-text / enum slots (no graph resolution); the rest
+// name a graph entity the guardrail must prove RESOLVES before the call fires.
+export const KINDS = Object.freeze({
+  Symbol: "seon:CodeEntity", // any code symbol: function/method/class/module/attribute
+  Module: "seon:Module",
+  Class: "seon:ClassDefinition",
+  Query: "cap:FreeText", // lexical search string — no resolution precondition
+  Kind: "cap:KindFilter", // enum: function|class|method|… (search filter)
+  Package: "cap:PackageName", // optional architecture-scope filter
+});
+
+// Precondition PREDICATE tags (the small closed vocabulary a precondition uses).
+export const PRECOND = Object.freeze({
+  graphLoaded: "cap:graph-loaded", // a graph artifact is present + parseable
+  resolves: "cap:resolves", // { param, as } — the slot binds to an entity of kind `as`
+  anyPresent: "cap:any-present", // { params } — at least one of these slots is provided
+});
+
+// ---- capability builder (returns PLAIN FROZEN data) -------------------------
+
+/** A parameter slot. `arg` is the EXACT dispatchTool key (never invented). */
+const param = (name, kind, { arg = name, required = true, note = "" } = {}) =>
+  Object.freeze({ type: VOCAB.Parameter, name, kind, arg, required, note });
+
+/** graph-loaded precondition — every graph-query capability carries it. */
+const graphLoaded = () => Object.freeze({ type: VOCAB.Precondition, pred: PRECOND.graphLoaded });
+/** resolves(param, as) — the named slot must bind to a graph entity of kind `as`. */
+const resolves = (paramName, as) =>
+  Object.freeze({ type: VOCAB.Precondition, pred: PRECOND.resolves, param: paramName, as });
+/** any-present(params) — search-style disjunction (query OR kind must be given). */
+const anyPresent = (params) =>
+  Object.freeze({ type: VOCAB.Precondition, pred: PRECOND.anyPresent, params: Object.freeze([...params]) });
+
+/** An epistemic add-effect: after the call the agent KNOWS `topic` about `?of`. */
+const knows = (topic, ofParam = null) =>
+  Object.freeze({ type: VOCAB.Effect, pred: "cap:knows", topic, of: ofParam ? `?${ofParam}` : null });
+
+/** Declare one capability as frozen STRIPS data. Read-only query tools pass an
+ *  empty delete-list (`del: []`) — the closed-world "queries mutate nothing". */
+function capability({ name, label, question, params = [], preconditions = [], add = [], del = [] }) {
+  return Object.freeze({
+    type: VOCAB.Capability,
+    name, // the dispatchTool tool name — directly callable
+    label, // human label (the slash-command verb)
+    question, // one-line "what question does this answer"
+    readOnly: true, // every capability here is query-only
+    parameters: Object.freeze(params),
+    preconditions: Object.freeze(preconditions),
+    effects: Object.freeze({ add: Object.freeze(add), del: Object.freeze(del) }),
+  });
+}
+
+// ---- the registry — the read-only graph-query tools as operators ------------
+// Enumerated from src/server.mjs `dispatchTool` (the query-only, bounded-output
+// slice). Arg keys verified against the switch: describe/callers/callees/tests/
+// history/… take `symbol`; impact/exports take `module`; members/subclasses take
+// `class`; search takes `query` (+ optional kind/name/decorator); architecture
+// takes an optional `package`; untested takes nothing.
+
+const CAPABILITIES = Object.freeze([
+  capability({
+    name: "tmct_search", label: "search", question: "lexical search across the graph",
+    params: [
+      param("query", KINDS.Query, { required: false, note: "required unless a kind filter is given" }),
+      param("kind", KINDS.Kind, { required: false }),
+      param("name", KINDS.Query, { required: false }),
+      param("decorator", KINDS.Query, { required: false }),
+    ],
+    preconditions: [graphLoaded(), anyPresent(["query", "kind"])],
+    add: [knows("matches", "query")],
+  }),
+  capability({
+    name: "tmct_describe", label: "describe", question: "a symbol's definition, kind and relations",
+    params: [param("symbol", KINDS.Symbol)],
+    preconditions: [graphLoaded(), resolves("symbol", KINDS.Symbol)],
+    add: [knows("description", "symbol")],
+  }),
+  capability({
+    name: "tmct_signature", label: "signature", question: "a symbol's signature only",
+    params: [param("symbol", KINDS.Symbol)],
+    preconditions: [graphLoaded(), resolves("symbol", KINDS.Symbol)],
+    add: [knows("signature", "symbol")],
+  }),
+  capability({
+    name: "tmct_impact", label: "impact", question: "what a change to this module reaches (impact closure)",
+    params: [param("module", KINDS.Module)],
+    preconditions: [graphLoaded(), resolves("module", KINDS.Module)],
+    add: [knows("impact", "module")],
+  }),
+  capability({
+    name: "tmct_members", label: "members", question: "the methods/attributes of a class",
+    params: [param("class", KINDS.Class, { arg: "class" })],
+    preconditions: [graphLoaded(), resolves("class", KINDS.Class)],
+    add: [knows("members", "class")],
+  }),
+  capability({
+    name: "tmct_subclasses", label: "subclasses", question: "the subclasses of a class",
+    params: [param("class", KINDS.Class, { arg: "class" })],
+    preconditions: [graphLoaded(), resolves("class", KINDS.Class)],
+    add: [knows("subclasses", "class")],
+  }),
+  capability({
+    name: "tmct_exports", label: "exports", question: "a module's public exports",
+    params: [param("module", KINDS.Module)],
+    preconditions: [graphLoaded(), resolves("module", KINDS.Module)],
+    add: [knows("exports", "module")],
+  }),
+  capability({
+    name: "tmct_callers", label: "callers", question: "functions that call this symbol",
+    params: [param("symbol", KINDS.Symbol)],
+    preconditions: [graphLoaded(), resolves("symbol", KINDS.Symbol)],
+    add: [knows("callers", "symbol")],
+  }),
+  capability({
+    name: "tmct_callees", label: "callees", question: "functions this symbol calls",
+    params: [param("symbol", KINDS.Symbol)],
+    preconditions: [graphLoaded(), resolves("symbol", KINDS.Symbol)],
+    add: [knows("callees", "symbol")],
+  }),
+  capability({
+    name: "tmct_calls", label: "calls", question: "the call edges out of this symbol/module",
+    params: [param("symbol", KINDS.Symbol)],
+    preconditions: [graphLoaded(), resolves("symbol", KINDS.Symbol)],
+    add: [knows("calls", "symbol")],
+  }),
+  capability({
+    name: "tmct_tests_for", label: "tests", question: "the tests covering this symbol",
+    params: [param("symbol", KINDS.Symbol)],
+    preconditions: [graphLoaded(), resolves("symbol", KINDS.Symbol)],
+    add: [knows("tests", "symbol")],
+  }),
+  capability({
+    name: "tmct_untested", label: "untested", question: "symbols with no covering test",
+    params: [],
+    preconditions: [graphLoaded()],
+    add: [knows("untested", null)],
+  }),
+  capability({
+    name: "tmct_history", label: "history", question: "the commit history of this symbol",
+    params: [param("symbol", KINDS.Symbol)],
+    preconditions: [graphLoaded(), resolves("symbol", KINDS.Symbol)],
+    add: [knows("history", "symbol")],
+  }),
+  capability({
+    name: "tmct_cochanges", label: "cochanges", question: "symbols that change together with this one",
+    params: [param("symbol", KINDS.Symbol)],
+    preconditions: [graphLoaded(), resolves("symbol", KINDS.Symbol)],
+    add: [knows("cochanges", "symbol")],
+  }),
+  capability({
+    name: "tmct_architecture", label: "arch", question: "the architecture overview (optional package filter)",
+    params: [param("package", KINDS.Package, { required: false })],
+    preconditions: [graphLoaded()],
+    add: [knows("architecture", "package")],
+  }),
+]);
+
+// A frozen name→capability index (built once).
+const BY_NAME = Object.freeze(
+  CAPABILITIES.reduce((m, c) => { m[c.name] = c; return m; }, Object.create(null)),
+);
+
+// ---- closed-world / DEFAULT-DENY --------------------------------------------
+// The registry is a deliberate, DOCUMENTED STRICT SUBSET of the src/server.mjs
+// `dispatchTool` switch. The model is CLOSED-WORLD default-deny: a tool name
+// that is NOT a registered capability is treated as UNKNOWN — the guardrail /
+// AGENTBENCH grader rejects it as a hallucination (`hallucinationsIn` →
+// "unknown-tool"), so a planner/shim that emits an UNREGISTERED tool is an
+// AUTOMATIC FAIL, exactly as if it invented a tool that does not exist. This is
+// the safety posture: only what is declared (with real preconditions) may fire.
+//
+// The following dispatch tools are INTENTIONALLY UNREGISTERED — they emit
+// UNBOUNDED raw output (a source snippet / a whole edit-context bundle), which
+// is the most hallucination-prone surface and NOT a clean STRIPS query with a
+// bounded epistemic effect. Registering them would require modelling
+// output-size + file-read preconditions we have not committed to; until then,
+// default-deny keeps them OUT of the router's provable envelope by design (not
+// by omission). Recorded here so the exclusion is a decision, not an accident:
+export const EXCLUDED_FROM_REGISTRY = Object.freeze({
+  tmct_context: "unbounded edit-context bundle (multi-file); needs a size/budget precondition",
+  tmct_context_more: "unbounded context continuation; same as tmct_context",
+  tmct_snippet: "raw source-file read (reads the filesystem); needs a file-read + span precondition",
+});
+
+/** The full registry as a plain frozen object (facts + index), for callers that
+ *  want the whole substrate. Prefer the accessors below for lookups. */
+export const REGISTRY = Object.freeze({
+  prefixes: PREFIXES,
+  vocab: VOCAB,
+  kinds: KINDS,
+  precond: PRECOND,
+  capabilities: CAPABILITIES,
+});
+
+// ---- pure accessors ---------------------------------------------------------
+
+/** All declared capabilities (the operator set). */
+export function capabilities() { return CAPABILITIES; }
+
+/** The capability named `n`, or undefined. */
+export function capabilityByName(n) { return BY_NAME[n]; }
+
+/** True iff `n` names a declared capability. */
+export function isCapability(n) { return Boolean(BY_NAME[n]); }
+
+/** The parameter slots of capability `n` (empty array if unknown/no-arg). */
+export function parametersOf(n) { return BY_NAME[n]?.parameters ?? []; }
+
+/** The preconditions of capability `n` (the safety gate the guardrail checks). */
+export function preconditionsOf(n) { return BY_NAME[n]?.preconditions ?? []; }
+
+/** The effects of capability `n` — `{ add, del }` (the proof-chain contribution). */
+export function effectsOf(n) { return BY_NAME[n]?.effects ?? { add: [], del: [] }; }
+
+/** The set of arg keys capability `n` accepts (for the guardrail's unknown-arg
+ *  check). Returns a Set of strings. */
+export function argKeysOf(n) {
+  return new Set(parametersOf(n).map((p) => p.arg));
+}
+
+/** The required arg keys of `n` (params with required:true). */
+export function requiredArgsOf(n) {
+  return parametersOf(n).filter((p) => p.required).map((p) => p.arg);
+}

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;
+}