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

package/src/router/guardrail.mjs

@@ -0,0 +1,120 @@
+// src/router/guardrail.mjs — Stage 4 of the capability router
+// (PLAN_CAPABILITY_ROUTER.md): THE GUARDRAIL. Validate an EXTERNALLY-proposed
+// `tool_use` (e.g. an LLM's chosen call in the hybrid fast-path) against the
+// registry's declared preconditions, and DEFAULT-DENY anything outside the
+// declared, registered envelope. This is the precondition-checking half of the
+// STRIPS model: a call fires only when its preconditions are provably satisfied.
+//
+// WHAT IT PROVES — and what it deliberately does NOT.
+//   The guardrail proves RESOLVABILITY: the tool exists in the registry, it was
+//   declared, every arg-key is one the operator accepts, every required arg is
+//   present, and every `resolves(param, as)` precondition binds to a real graph
+//   entity (delegated to resolveObject — the same oracle Stage 1 uses).
+//
+//   It does NOT prove ANTECEDENT-CORRECTNESS. A cross-turn mis-binding — "it" ->
+//   the wrong Commit, say — produces a call whose symbol STILL resolves to a real
+//   entity, so it PASSES the guardrail. That is by design: binding-confidence
+//   across turns is the CHAT LEVER's job (pronoun/focus binding), not the
+//   guardrail's. A gate that leaned on Stage 4 for antecedent correctness would be
+//   trusting the wrong layer. The guardrail's contract is narrow and honest:
+//   "this symbol denotes SOMETHING real and the call is well-formed", never "this
+//   is the RIGHT something".
+//
+// DEFAULT-DENY: a tool name that is not a registered capability is denied outright
+// (identical to a hallucinated/invented tool). The intentionally-unregistered
+// unbounded tools (tmct_snippet/tmct_context*) are therefore denied here too — the
+// registry is the whole trust boundary.
+//
+// Pure over its inputs + ctx.resolve (the binding oracle). No network, no Date.now.
+
+import { capabilityByName, preconditionsOf, PRECOND } from "./registry.mjs";
+import { hallucinationsIn } from "../../agentbench/grade.mjs";
+
+/** Validate a proposed tool_use. Returns a glass-box verdict:
+ *    { ok, tool, denied:[{reason,detail}], steps:[{pred,ok,...}], provenance }
+ *  - ok=false with a `default-deny`/`undeclared`/`unknown-arg`/`missing-arg`
+ *    denial is a STRUCTURAL rejection (no graph needed).
+ *  - ok=false with an `unresolved` step is a BINDING rejection (a `resolves`
+ *    precondition whose term matched no entity, or matched ambiguously).
+ *  - ok=true means the call is RESOLVABLE + well-formed (NOT proven antecedent-
+ *    correct — see the file header).
+ *  `declaredNames` may be null to skip the declared-set check (validate against
+ *  the registry alone); pass it to also enforce the case/session toolset.
+ *  `ctx.resolve(term)` is the resolveObject oracle; omit it to skip binding proof
+ *  (structural-only validation). */
+export function guard(toolUse, declaredNames = null, ctx = {}) {
+  const name = toolUse?.name;
+  const input = toolUse && typeof toolUse.input === "object" && toolUse.input ? toolUse.input : {};
+  const denied = [];
+  const steps = [];
+
+  // 1. DEFAULT-DENY — unknown/unregistered tool is an automatic reject. Reuse the
+  //    grader's hallucination check as the single source of truth for structural
+  //    well-formedness (unknown-tool / undeclared / unknown-arg / missing-arg).
+  const declaredList = declaredNames ? [...declaredNames] : null;
+  const cap = capabilityByName(name);
+  if (!cap) {
+    denied.push({ reason: "default-deny", detail: `"${name ?? "(none)"}" is not a registered capability` });
+    return { ok: false, tool: name ?? null, denied, steps, provenance: "registry default-deny" };
+  }
+  // structural well-formedness against the registry (and the declared set when
+  // given — an undeclared-but-registered tool is still a policy denial).
+  const structural = hallucinationsIn({ name, input }, declaredList ?? [name]);
+  for (const p of structural) {
+    // when no declared set is supplied, an "undeclared" finding is not a real
+    // denial (we synthesised [name] as the set) — filter it out.
+    if (!declaredList && p.reason === "undeclared") continue;
+    denied.push(p);
+  }
+
+  // 2. PRECONDITION CHECK — the STRIPS safety gate, step by step (the proof).
+  for (const pre of preconditionsOf(name)) {
+    if (pre.pred === PRECOND.graphLoaded) {
+      // graph presence is the harness's responsibility; if a resolver is wired we
+      // treat graph-loaded as satisfied (resolveObject would throw without one).
+      steps.push({ step: "precondition", pred: pre.pred, ok: true });
+    } else if (pre.pred === PRECOND.anyPresent) {
+      const ok = pre.params.some((k) => input[k] !== undefined && input[k] !== null && String(input[k]).trim() !== "");
+      steps.push({ step: "precondition", pred: pre.pred, params: pre.params, ok });
+      if (!ok) denied.push({ reason: "missing-arg", detail: `${name} needs one of ${pre.params.join("|")}` });
+    } else if (pre.pred === PRECOND.resolves) {
+      const term = input[pre.param];
+      const present = term !== undefined && term !== null && String(term).trim() !== "";
+      if (!present) {
+        // a missing required arg is already flagged structurally; record the step.
+        steps.push({ step: "precondition", pred: pre.pred, param: pre.param, value: null, ok: false });
+        continue;
+      }
+      // DELEGATE to resolveObject (the binding oracle). No oracle wired → we can
+      // only assert the arg is PRESENT, not that it binds (structural mode).
+      if (!ctx.resolve) {
+        steps.push({ step: "precondition", pred: pre.pred, param: pre.param, value: term, ok: true, note: "structural-only (no resolver wired)" });
+        continue;
+      }
+      const r = ctx.resolve(String(term));
+      const resolvedOk = Boolean(r && r.match && !r.ambiguous);
+      steps.push({
+        step: "precondition", pred: pre.pred, param: pre.param, value: term,
+        ok: resolvedOk,
+        ...(r && r.match ? { boundTo: r.match.label, boundClass: r.match.class ?? null, tier: r.tier ?? null } : {}),
+        ...(r && r.ambiguous ? { ambiguous: true } : {}),
+      });
+      if (!resolvedOk) {
+        denied.push({
+          reason: "unresolved",
+          detail: r && r.ambiguous
+            ? `${name}.${pre.param}="${term}" is ambiguous (narrow it)`
+            : `${name}.${pre.param}="${term}" resolves to no graph entity`,
+        });
+      }
+    }
+  }
+
+  const ok = denied.length === 0;
+  return { ok, tool: name, denied, steps, provenance: ok ? "resolvable (NOT proven antecedent-correct)" : "denied" };
+}
+
+/** Convenience boolean: does a proposed tool_use PASS the guardrail? */
+export function admits(toolUse, declaredNames = null, ctx = {}) {
+  return guard(toolUse, declaredNames, ctx).ok;
+}

package/src/router/planner.mjs

@@ -0,0 +1,168 @@
+// src/router/planner.mjs — Stage 3 of the capability router
+// (PLAN_CAPABILITY_ROUTER.md): THE PLANNER. Compose a bounded, ordered plan of
+// tool calls for a multi-step request, over the SAME operators Stage 1 resolves
+// single-shot. Pure-JS POP/HTN + a Steel & Ho monitor-and-replan loop under a
+// HARD budget — sound/complete INSIDE the declared operator model, honest-refuse
+// (escalate) for novelty outside it. Deterministic, no-LLM, glass-box.
+//
+// THE MODEL, mapped to the literature:
+//   - HTN decomposition (NONLIN/SHOP2): a compound request is decomposed into an
+//     ORDERED list of sub-goals by declared METHODS — the sequencing connectives
+//     ("... then ...", "... and then ...") and the two closed recipes we author:
+//     the CONDITIONAL method ("if <check>, <action> [instead]") and the
+//     RELATIVE-FILTER method ("of the <set> <rel> X, which are <Y>"). Each leaf
+//     sub-goal is resolved by Stage 1 (resolveOne) — the primitive operator.
+//   - POP causal links (partial-order planning): each step's proof records the
+//     PRODUCER -> CONDITION -> CONSUMER link. An independent step's producer is
+//     the grounded graph (graph-loaded); a THREADED step (one whose entity came
+//     from a prior step via anaphora — "its subclasses", "describe it") records
+//     the prior STEP as its producer. That link IS the proof chain (grade.mjs's
+//     connectedness check reads it), never a flat ok-list. Least commitment: we
+//     only order what the connectives actually order.
+//   - Steel & Ho monitor-and-replan: after each call we read the tool_result;
+//     a failed sub-goal (an unresolvable entity / an operator that errors) forces
+//     an honest STOP (refuse/escalate) rather than pressing on with a broken
+//     chain. Bounded depth + a hard step counter GUARANTEE termination — no
+//     unbounded search can ever wedge the caller (the harness also caps us).
+//
+// THE OPEN-WORLD BOUNDARY, named honestly: novelty the declared methods + operators
+// do not cover (a sub-goal that resolves to nothing, a connective we do not model)
+// is REFUSED/ESCALATED, not guessed. Sound/complete is claimed only INSIDE the
+// declared world.
+
+import { resolveOne, extractEntity } from "./resolver.mjs";
+
+// Hard budget — the planner may emit at most this many steps; a request that
+// decomposes to more is REFUSED (escalate) rather than searched. Guarantees
+// termination independent of the harness backstop.
+export const MAX_STEPS = 8;
+
+const PRONOUN_RE = /\b(?:it|its|them|those|these|that|their)\b/i;
+
+/** HTN decomposition — turn a request into an ORDERED list of leaf sub-goals.
+ *  Returns { method, segments:[{ text, role, thread }] }:
+ *    - role "check"  — a conditional antecedent (a test whose call still emits)
+ *    - role "action" — a plain sub-goal
+ *    - thread:true   — the segment carries an anaphor to bind from a prior step
+ *  A single segment (no connective) means "not multi-step" (the driver hands
+ *  those to resolveOne directly). Pure. */
+export function decompose(request) {
+  const raw = String(request || "").trim();
+
+  // METHOD 1 — the CONDITIONAL recipe: "if <check>, <action> [instead]".
+  const cond = raw.match(/^if\s+(.+?),\s*(.+?)(?:\s+instead)?$/i);
+  if (cond) {
+    return {
+      method: "conditional",
+      segments: [
+        { text: cond[1].trim(), role: "check", thread: PRONOUN_RE.test(cond[1]) },
+        { text: cond[2].trim(), role: "action", thread: PRONOUN_RE.test(cond[2]) },
+      ],
+    };
+  }
+
+  // METHOD 2 — the RELATIVE-FILTER recipe: "of the <set> <rel> X, which are <Y>".
+  // Decomposes to [produce the <set> (the <rel> over X), filter it by <Y>].
+  const rel = raw.match(/^of\s+the\s+(.+?),\s*which\s+(?:are\s+)?(.+?)$/i);
+  if (rel) {
+    return {
+      method: "relative-filter",
+      segments: [
+        { text: rel[1].trim(), role: "action", thread: false },
+        { text: `which are ${rel[2].trim()}`, role: "action", thread: true },
+      ],
+    };
+  }
+
+  // METHOD 3 — SEQUENCING: split on the ordered connectives. Least commitment:
+  // we only split where a connective actually is.
+  const parts = raw.split(/\s*(?:,\s*then\s+|,\s+and\s+then\s+|\s+and\s+then\s+|\s+then\s+|,\s+|\s+and\s+)\s*/i)
+    .map((s) => s.replace(/^(?:then\s+|and\s+then\s+|and\s+|also\s+|check\s+|next\s+)/i, "").trim())
+    .filter(Boolean);
+  const segments = parts.map((text) => ({ text, role: "action", thread: PRONOUN_RE.test(text) }));
+  return { method: segments.length > 1 ? "sequence" : "single", segments };
+}
+
+/** True iff the request is multi-step (the planner owns it); else the driver
+ *  routes it to the single-shot resolver. */
+export function isMultiStep(request) {
+  return decompose(request).segments.length > 1;
+}
+
+/** Substitute a bound anaphor: replace a bare pronoun with the prior step's
+ *  entity label so the leaf resolver can bind it ("its subclasses" + Widget ->
+ *  "Widget subclasses"; "describe it" + fnAlpha -> "describe fnAlpha"). */
+function bindAnaphor(text, lastEntity) {
+  if (!lastEntity) return text;
+  return text.replace(PRONOUN_RE, lastEntity);
+}
+
+/** A conditional ANTECEDENT that tests a SPECIFIC entity's coverage ("X has no
+ *  tests", "fnAlpha is untested") is the CHECK operator tmct_tests_for over that
+ *  entity — NOT the no-arg tmct_untested (which lists the whole codebase). Rewrite
+ *  it to the terse "tests <entity>" command form so the leaf resolver binds the
+ *  entity. A check with no coverage predicate is left untouched. */
+function rewriteCheck(text, lastEntity) {
+  if (!/\b(?:untested|tested|no\s+tests?|has\s+no\s+tests?|tests?|coverage|covered)\b/i.test(text)) return text;
+  const entity = extractEntity(text) || lastEntity;
+  return entity ? `tests ${entity}` : text;
+}
+
+const refuse = (why, driver) => ({ calls: [], refused: true, terminated: true, proof: [], driver, why });
+
+/** Plan + execute a multi-step request. Returns a loopResult
+ *    { calls, refused, terminated, proof, why, driver, observed }
+ *  with a POP causal-link proof chain. Steel & Ho: each step is monitored; a
+ *  failed sub-goal STOPS the plan honestly (refuse/escalate). Bounded by
+ *  MAX_STEPS + a hard step counter. `driver` labels the row.
+ *
+ *  ctx: { dispatch(name,input)->{ok,text,resolved?}, resolve(term)->resolveObject } */
+export async function plan(request, declaredNames, ctx, { driver = "resolver-0.8.0" } = {}) {
+  const { method, segments } = decompose(request);
+  if (segments.length > MAX_STEPS) {
+    return refuse(`plan would need ${segments.length} steps (> budget ${MAX_STEPS}) — escalate`, driver);
+  }
+
+  const calls = [];
+  const proof = [];
+  const why = [`HTN method: ${method} — ${segments.length} sub-goal(s)`];
+  let lastEntity = null; // the most-recent bound entity label (for anaphora threading)
+  let steps = 0;
+
+  for (let i = 0; i < segments.length; i += 1) {
+    if (steps >= MAX_STEPS) return refuse("step budget exhausted mid-plan — escalate", driver);
+    steps += 1;
+    const seg = segments[i];
+    let text = seg.thread ? bindAnaphor(seg.text, lastEntity) : seg.text;
+    if (seg.role === "check") text = rewriteCheck(text, lastEntity);
+
+    const r = await resolveOne(text, declaredNames, ctx, { execute: true });
+    if (r.refused) {
+      // Steel & Ho: an unresolvable sub-goal breaks the causal chain — STOP
+      // honestly (escalate), never emit a partial/guessed plan.
+      return refuse(`sub-goal ${i + 1} ("${text}") did not resolve: ${r.reason}`, driver);
+    }
+
+    calls.push(r.selected);
+    // POP causal link: the producer is the prior step when this step THREADED an
+    // anaphor from it; otherwise the grounded graph. Its condition is the arg the
+    // step needed. This is the "why step i" edge, not a flat ok.
+    const producer = seg.thread && i > 0 ? `step-${i}` : "graph";
+    const boundLabel = r.resolved?.label ?? Object.values(r.selected.input || {})[0] ?? null;
+    proof.push({ step: "causal-link", producer, condition: boundLabel, consumer: `step-${i + 1}:${r.selected.name}`, role: seg.role, ok: true });
+    for (const s of r.proof) proof.push({ ...s, ofStep: i + 1 });
+
+    if (r.resolved?.label) lastEntity = r.resolved.label;
+    why.push(...(r.why || []).map((w) => `[${i + 1}] ${w}`));
+  }
+
+  return {
+    calls,
+    refused: false,
+    terminated: true,
+    proof,
+    driver,
+    why,
+    observed: `plan(${method}): ${calls.map((c) => c.name).join(" -> ")}`,
+  };
+}

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