@konneal/engine 0.2.84 → 0.2.86

package/dist/{ask-GVU5PYC4.js → ask-XM5FO6LR.js}

@@ -1,6 +1,7 @@
 import {
   handleAsk
-} from "./chunk-D24PQPDK.js";
+} from "./chunk-PIEUN5B2.js";
+import "./chunk-GCK6DW7E.js";
 import "./chunk-7HWJOFTQ.js";
 import "./chunk-SPKPH54J.js";
 import "./chunk-A3QHHUN5.js";

package/dist/chunk-GCK6DW7E.js

@@ -0,0 +1,234 @@
+// workers/worker_public/src/refs.ts
+var REF = /\[\[(u:[A-Za-z0-9_-]+)\]\]/g;
+function availableUnitIds(hits) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const h of hits) {
+    const u = h.metadata?.unit_id;
+    if (u) ids.add(u);
+  }
+  return ids;
+}
+function parseRefs(text) {
+  return [...text.matchAll(REF)].map((m) => m[1]);
+}
+function sanitizeRefs(text, available) {
+  const dropped = [];
+  const out = text.replace(REF, (full, id) => {
+    if (available.has(id)) return full;
+    dropped.push(id);
+    return "";
+  });
+  return { text: out, dropped };
+}
+async function resolveBlocks(db, refs) {
+  if (!refs.length) return [];
+  const uniq = [...new Set(refs)].slice(0, 12);
+  const blocks = [];
+  for (let i = 0; i < uniq.length; i += 20) {
+    const batch = uniq.slice(i, i + 20);
+    const placeholders = batch.map((_, n) => `?${n + 1}`).join(",");
+    try {
+      const res = await db.prepare(`SELECT unit_id, type, docidentifier, edition, payload FROM unit_payloads WHERE unit_id IN (${placeholders})`).bind(...batch).all();
+      for (const r of res.results) {
+        let payload = {};
+        try {
+          payload = JSON.parse(String(r.payload));
+        } catch {
+          continue;
+        }
+        blocks.push({
+          unit_id: String(r.unit_id),
+          type: String(r.type),
+          docidentifier: String(r.docidentifier ?? ""),
+          edition: r.edition ? String(r.edition) : void 0,
+          payload
+        });
+      }
+    } catch (e) {
+      console.log("resolveBlocks failed:", String(e).slice(0, 150));
+    }
+  }
+  return blocks;
+}
+async function contractV2(db, answer, usedHits) {
+  const available = availableUnitIds(usedHits);
+  const { text, dropped } = sanitizeRefs(answer, available);
+  if (dropped.length) console.log("refs: dropped", dropped.length, "invalid (not in passages)");
+  const refs = parseRefs(text);
+  const blocks = await resolveBlocks(db, refs);
+  return { text, blocks, dropped };
+}
+function tableRetyped(text, availableTable) {
+  if (!availableTable) return false;
+  return /(^|\n)\s*\|[^\n]+\|\s*(\n\s*\|[-: |]+\|\s*)?(\n|$)/.test(text) && (text.match(/\|/g) ?? []).length >= 6;
+}
+
+// workers/worker_public/src/tools-content.ts
+var slug = (docidentifier) => docidentifier.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+var unitsGet = {
+  name: "units.get",
+  description: "Fetch typed Recommendation content \u2014 a table, formula or figure as structured data (columns, rows, MathML, caption), by its unit id. The machine-consumable form of a Recommendation's content, for computing with rather than reading.",
+  params: [{ key: "unit_id", required: true, description: "the unit id, e.g. u:table-1 or u:form-3 (ids appear in answers' [[u:\u2026]] references)" }],
+  audiences: ["mcp"],
+  handler: async (env, args) => {
+    const unit_id = String(args?.unit_id ?? "").trim().replace(/^\[?\[?u:/, "u:").replace(/]?\]?$/, "");
+    if (!/^u:[\w.-]+$/.test(unit_id)) return null;
+    const blocks = await resolveBlocks(env.DB, [unit_id]);
+    if (!blocks.length) {
+      return { name: "units.get", query: unit_id, output: `No typed unit "${unit_id}" exists in the indexed payloads. State this plainly.` };
+    }
+    return {
+      name: "units.get",
+      query: unit_id,
+      output: JSON.stringify(
+        blocks.map((b) => ({ unit_id: b.unit_id, type: b.type, docidentifier: b.docidentifier, payload: b.payload }))
+      )
+    };
+  }
+};
+var graphCites = {
+  name: "graph.cites",
+  description: "The bibliography edges: what a publication's own bibliography actually cites, extracted from its indexed bibliography sections. Returns the cited works' labels for a document (optionally scoped to an edition).",
+  params: [
+    { key: "doc", required: true, description: "the publication identifier, e.g. R 60-1:2021" },
+    { key: "edition", required: false, description: "an edition year to scope, e.g. 2021" }
+  ],
+  audiences: ["mcp"],
+  handler: async (env, args) => {
+    const doc = String(args?.doc ?? "").trim();
+    if (doc.length < 3) return null;
+    const edition = args?.edition ? String(args.edition).trim() : null;
+    const pat = `%${doc.replace(/[:\s]+/g, "%")}%${edition ? edition : ""}%`;
+    try {
+      const rows = await env.DB.prepare(
+        "SELECT DISTINCT n.label AS label FROM graph_edges e JOIN documents d ON e.src = d.canonical_id JOIN graph_nodes n ON e.dst = n.id WHERE d.docidentifier LIKE ?1 AND e.kind = 'cites' ORDER BY label LIMIT 60"
+      ).bind(pat).all();
+      const labels = (rows.results ?? []).map((r) => r.label).filter(Boolean);
+      return {
+        name: "graph.cites",
+        query: `${doc}${edition ? ` (${edition})` : ""}`,
+        output: labels.length ? `The publication's bibliography cites:
+${labels.map((l) => `- ${l}`).join("\n")}` : `No bibliography citations are indexed for "${doc}"${edition ? ` (${edition})` : ""}. State this plainly.`
+      };
+    } catch {
+      return null;
+    }
+  }
+};
+var docsSection = {
+  name: "docs.section",
+  description: "Fetch one clause of a publication's rendered document \u2014 its text and its permanent deep-link URL \u2014 for agents that need the human-formatted passage with its anchor.",
+  params: [
+    { key: "doc", required: true, description: "the publication identifier, e.g. R 60-1:2021" },
+    { key: "clause", required: true, description: "the clause anchor, e.g. 5.1.1 or annex-b" }
+  ],
+  audiences: ["mcp"],
+  handler: async (env, args) => {
+    const doc = String(args?.doc ?? "").trim();
+    const clause = String(args?.clause ?? "").trim();
+    if (doc.length < 3 || !clause) return null;
+    try {
+      const rows = await env.DB.prepare(
+        "SELECT docidentifier, clause_anchor, clause_title, text FROM chunks WHERE docidentifier LIKE ?1 AND REPLACE(clause_anchor, ' ', '') = ?2 LIMIT 1"
+      ).bind(`%${doc.replace(/[:\s]+/g, "%")}%`, clause).all();
+      const r = (rows.results ?? [])[0];
+      if (!r) {
+        return { name: "docs.section", query: `${doc} \xA7${clause}`, output: `No clause "${clause}" is indexed for "${doc}". State this plainly.` };
+      }
+      const url = `https://www.ommisa.org/docs/${slug(r.docidentifier)}.html#${r.clause_anchor}`;
+      return {
+        name: "docs.section",
+        query: `${r.docidentifier} \xA7${r.clause_anchor}`,
+        output: JSON.stringify({ docidentifier: r.docidentifier, clause: r.clause_anchor, title: r.clause_title, url, text: (r.text ?? "").slice(0, 4e3) })
+      };
+    } catch {
+      return null;
+    }
+  }
+};
+var glossaryLookup = {
+  name: "glossary.lookup",
+  description: "Look up a defined term in the terminology datasets \u2014 the concept's definition and its defining publication. Bind everyday words to the defined term before interpreting a question.",
+  params: [{ key: "term", required: true, description: "the term or everyday phrase to bind, e.g. creep or load cell" }],
+  audiences: ["mcp"],
+  handler: async (env, args) => {
+    const term = String(args?.term ?? "").trim();
+    if (term.length < 2) return null;
+    try {
+      const rows = await env.DB.prepare(
+        "SELECT clause_title AS term, chunk_text AS text, docidentifier FROM chunks WHERE corpus = 'glossary' AND (clause_title = ?1 OR clause_title LIKE ?2) LIMIT 3"
+      ).bind(term, `%${term}%`).all();
+      const hits = (rows.results ?? []).filter((r) => r.term);
+      if (!hits.length) {
+        return { name: "glossary.lookup", query: term, output: `No defined term matches "${term}" in the terminology datasets. State this plainly.` };
+      }
+      return {
+        name: "glossary.lookup",
+        query: term,
+        output: hits.map((r) => `- ${r.term} (${r.docidentifier}): ${String(r.text ?? "").split(" \u2014 ").slice(1).join(" \u2014 ").slice(0, 400)}`).join("\n")
+      };
+    } catch {
+      return null;
+    }
+  }
+};
+
+// workers/worker_public/src/tools.ts
+function parseToolCall(text) {
+  const m = /^TOOL\s+([a-z_.]+)\s*(\{[^\n}]*\})?/m.exec(String(text ?? ""));
+  if (!m) return null;
+  let args = {};
+  if (m[2]) {
+    try {
+      args = JSON.parse(m[2]);
+    } catch {
+      return null;
+    }
+  } else if (/^TOOL\s+[a-z_.]+\s*\{/m.test(String(text ?? ""))) {
+    return null;
+  }
+  return { name: m[1].toLowerCase(), args };
+}
+var certificatesSearch = {
+  name: "certificates.search",
+  description: "Search the certificate register (a snapshot) by holder name, model designation, or a printed certificate number. Returns the matching rows \u2014 number, holder, model, issue year, status, and document links where on file \u2014 or the exact no-match statement for the string asked.",
+  params: [{ key: "query", required: true, description: "the holder, model, or printed certificate number to look up" }],
+  audiences: ["agent", "mcp"],
+  handler: async (env, args) => {
+    const query = String(args?.query ?? "").trim().slice(0, 160);
+    if (!query) return null;
+    const { searchRegister, registerNote, certificateLinks } = await import("./certificates-CO7KX2S2.js");
+    const reg = await searchRegister(env.DB, query, true);
+    const output = reg?.rows?.length ? [registerNote(reg.rows), certificateLinks(reg.rows)].filter(Boolean).join("\n") : `No certificate was found for "${query}" in the certificates database (the register snapshot). State this as the search's result, with the searched string visible.`;
+    return { name: "certificates.search", query, output };
+  }
+};
+var TOOLS_REGISTRY = [certificatesSearch, unitsGet, graphCites, docsSection, glossaryLookup];
+var TOOL_DECLARATION = [
+  "You may use one tool before answering, by writing a single line:",
+  ...TOOLS_REGISTRY.filter((t) => t.audiences.includes("agent")).map((t) => {
+    const shape = `{${t.params.map((p) => `"${p.key}": "<${p.description}>"`).join(", ")}}`;
+    return `TOOL ${t.name} ${shape}`;
+  }),
+  "The worker runs it and returns the result attributed \u2014 phrase the tool's result as what it returned, with the searched string visible in your answer. Use a tool when the question turns on what it answers (including from a photograph). If you do not need it, answer directly without the line."
+].join("\n");
+async function runTool(env, call) {
+  const spec = TOOLS_REGISTRY.find((t) => t.name === call.name && t.audiences.includes("agent"));
+  if (!spec) return null;
+  return spec.handler(env, call.args ?? {});
+}
+function toolNote(r) {
+  return `The ${r.name} tool returned, for the query "${r.query}":
+${r.output}`;
+}
+
+export {
+  resolveBlocks,
+  contractV2,
+  tableRetyped,
+  parseToolCall,
+  TOOLS_REGISTRY,
+  TOOL_DECLARATION,
+  runTool,
+  toolNote
+};

package/dist/{chunk-D24PQPDK.js → chunk-PIEUN5B2.js}

@@ -1,3 +1,12 @@
+import {
+  TOOL_DECLARATION,
+  contractV2,
+  parseToolCall,
+  resolveBlocks,
+  runTool,
+  tableRetyped,
+  toolNote
+} from "./chunk-GCK6DW7E.js";
 import {
   NO_CONTEXT,
   answerQuality,
@@ -363,71 +372,6 @@ function checkQuoteAnchors(answer, passages) {
 }
 var ANCHOR_CORRECTION_NOTE = "Correction notice: your draft quoted text that does not appear verbatim in the provided passages. Rewrite the answer \u2014 every quoted phrase must be an exact copy from a passage, or cite the clause without quoting.";
 
-// workers/worker_public/src/refs.ts
-var REF = /\[\[(u:[A-Za-z0-9_-]+)\]\]/g;
-function availableUnitIds(hits) {
-  const ids = /* @__PURE__ */ new Set();
-  for (const h of hits) {
-    const u = h.metadata?.unit_id;
-    if (u) ids.add(u);
-  }
-  return ids;
-}
-function parseRefs(text) {
-  return [...text.matchAll(REF)].map((m) => m[1]);
-}
-function sanitizeRefs(text, available) {
-  const dropped = [];
-  const out = text.replace(REF, (full, id) => {
-    if (available.has(id)) return full;
-    dropped.push(id);
-    return "";
-  });
-  return { text: out, dropped };
-}
-async function resolveBlocks(db, refs) {
-  if (!refs.length) return [];
-  const uniq = [...new Set(refs)].slice(0, 12);
-  const blocks = [];
-  for (let i = 0; i < uniq.length; i += 20) {
-    const batch = uniq.slice(i, i + 20);
-    const placeholders = batch.map((_, n) => `?${n + 1}`).join(",");
-    try {
-      const res = await db.prepare(`SELECT unit_id, type, docidentifier, edition, payload FROM unit_payloads WHERE unit_id IN (${placeholders})`).bind(...batch).all();
-      for (const r of res.results) {
-        let payload = {};
-        try {
-          payload = JSON.parse(String(r.payload));
-        } catch {
-          continue;
-        }
-        blocks.push({
-          unit_id: String(r.unit_id),
-          type: String(r.type),
-          docidentifier: String(r.docidentifier ?? ""),
-          edition: r.edition ? String(r.edition) : void 0,
-          payload
-        });
-      }
-    } catch (e) {
-      console.log("resolveBlocks failed:", String(e).slice(0, 150));
-    }
-  }
-  return blocks;
-}
-async function contractV2(db, answer, usedHits) {
-  const available = availableUnitIds(usedHits);
-  const { text, dropped } = sanitizeRefs(answer, available);
-  if (dropped.length) console.log("refs: dropped", dropped.length, "invalid (not in passages)");
-  const refs = parseRefs(text);
-  const blocks = await resolveBlocks(db, refs);
-  return { text, blocks, dropped };
-}
-function tableRetyped(text, availableTable) {
-  if (!availableTable) return false;
-  return /(^|\n)\s*\|[^\n]+\|\s*(\n\s*\|[-: |]+\|\s*)?(\n|$)/.test(text) && (text.match(/\|/g) ?? []).length >= 6;
-}
-
 // workers/worker_public/src/completion.ts
 async function completeTables(db, answer, used) {
   const blocks = [];
@@ -1873,39 +1817,6 @@ function exactCacheKey(indexVersion, gen, ns, queryHash) {
   return `a:${indexVersion}:g${gen}:${ns}:${queryHash}`;
 }
 
-// workers/worker_public/src/tools.ts
-function parseToolCall(text) {
-  const m = /^TOOL\s+([a-z_]+)\s*(\{[^\n}]*\})?/m.exec(String(text ?? ""));
-  if (!m) return null;
-  let args = {};
-  if (m[2]) {
-    try {
-      args = JSON.parse(m[2]);
-    } catch {
-      return null;
-    }
-  } else if (/^TOOL\s+[a-z_]+\s*\{/m.test(String(text ?? ""))) {
-    return null;
-  }
-  return { name: m[1].toLowerCase(), args };
-}
-var TOOL_DECLARATION = `You may use one tool before answering, by writing a single line:
-TOOL register_search {"query": "manufacturer and model to look up"}
-The worker runs it against the certificate register (a snapshot) and returns the matching rows, or the exact no-match statement for the string you asked. Use it when the question turns on certification standing and the holder is known \u2014 including from a photograph. Then answer, phrasing the tool's result as what it returned (the searched string stays visible in your answer). If you do not need the tool, answer directly without the line.`;
-async function runTool(db, call) {
-  if (call.name !== "register_search") return null;
-  const query = String(call.args?.query ?? "").trim().slice(0, 160);
-  if (!query) return null;
-  const { searchRegister: searchRegister2, registerNote: registerNote2 } = await import("./certificates-CO7KX2S2.js");
-  const reg = await searchRegister2(db, query, true);
-  const output = reg?.rows?.length ? registerNote2(reg.rows) : `No certificate was found for "${query}" in the certificates database (the register snapshot). State this as the search's result, with the searched string visible.`;
-  return { name: call.name, query, output };
-}
-function toolNote(r) {
-  return `The ${r.name} tool returned, for the query "${r.query}":
-${r.output}`;
-}
-
 // workers/worker_public/src/operations.ts
 function isOperationIntent(query) {
   return /\b(operations?|endpoints?)\b/i.test(query);
@@ -2900,7 +2811,7 @@ ${q.query}`.replace("\n\n\n\n", "\n\n") }];
       const call = parseToolCall(probeText);
       if (call) {
         mark(`Searching the certificate register for \u201C${String(call.args?.query ?? "")}\u201D`);
-        const result = await runTool(env.DB, call);
+        const result = await runTool(env, call);
         if (result) {
           messages.push({ role: "system", content: toolNote(result) });
           pendingTools.push(result);

package/dist/tools-3AMOGBJG.js

@@ -0,0 +1,14 @@
+import {
+  TOOLS_REGISTRY,
+  TOOL_DECLARATION,
+  parseToolCall,
+  runTool,
+  toolNote
+} from "./chunk-GCK6DW7E.js";
+export {
+  TOOLS_REGISTRY,
+  TOOL_DECLARATION,
+  parseToolCall,
+  runTool,
+  toolNote
+};

package/dist/tools-content.d.ts

@@ -0,0 +1,5 @@
+import type { ToolSpec } from "./tools.ts";
+export declare const unitsGet: ToolSpec;
+export declare const graphCites: ToolSpec;
+export declare const docsSection: ToolSpec;
+export declare const glossaryLookup: ToolSpec;

package/dist/tools.d.ts

@@ -7,12 +7,29 @@ export interface ToolResult {
     query: string;
     output: string;
 }
-/** The strict protocol: a line `TOOL register_search {"query": "…"}`.
+/** The strict protocol: a line `TOOL certificates.search {"query": "…"}`.
  *  Plain regex parse — no JSON mode needed, tolerant of surrounding
  *  prose (the model may talk around the call). */
 export declare function parseToolCall(text: string): ToolCall | null;
-export declare const TOOL_DECLARATION = "You may use one tool before answering, by writing a single line:\nTOOL register_search {\"query\": \"manufacturer and model to look up\"}\nThe worker runs it against the certificate register (a snapshot) and returns the matching rows, or the exact no-match statement for the string you asked. Use it when the question turns on certification standing and the holder is known \u2014 including from a photograph. Then answer, phrasing the tool's result as what it returned (the searched string stays visible in your answer). If you do not need the tool, answer directly without the line.";
-export declare function runTool(db: any, call: ToolCall): Promise<ToolResult | null>;
+export interface ToolSpec {
+    /** canonical on every surface */
+    name: string;
+    description: string;
+    params: {
+        key: string;
+        required: boolean;
+        description: string;
+    }[];
+    audiences: ("agent" | "mcp")[];
+    handler: (env: any, args: Record<string, unknown>) => Promise<ToolResult | null>;
+}
+export declare const TOOLS_REGISTRY: ToolSpec[];
+/** The agent loop's protocol declaration, GENERATED from the registry —
+ *  the model's tool vocabulary is always the registry's, never a
+ *  hand-maintained literal. */
+export declare const TOOL_DECLARATION: string;
+/** Dispatch by LOOKUP — a tool name is never hard-coded at a call site. */
+export declare function runTool(env: any, call: ToolCall): Promise<ToolResult | null>;
 /** The attributed injection: the answer model sees what the tool
  *  returned, for the string it asked — never a standing claim. */
 export declare function toolNote(r: ToolResult): string;

package/dist/worker_public/src/index.js

@@ -6,7 +6,10 @@ import {
   modelGroundingBlock,
   scoreFaithfulness,
   scoreJudge
-} from "../../chunk-D24PQPDK.js";
+} from "../../chunk-PIEUN5B2.js";
+import {
+  TOOLS_REGISTRY
+} from "../../chunk-GCK6DW7E.js";
 import {
   handleSearch
 } from "../../chunk-KO6DRI7C.js";
@@ -922,7 +925,16 @@ var TOOLS = [
       },
       required: ["query"]
     }
-  }
+  },
+  ...TOOLS_REGISTRY.filter((t) => t.audiences.includes("mcp")).map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: {
+      type: "object",
+      properties: Object.fromEntries(t.params.map((p) => [p.key, { type: "string", description: p.description }])),
+      required: t.params.filter((p) => p.required).map((p) => p.key)
+    }
+  }))
 ];
 function dispatch(method, params, callTool) {
   switch (method) {
@@ -959,7 +971,12 @@ async function handleMcp(env, ctx, req, tier, key) {
       // stream:false forces the JSON lane (anon defaults to SSE)
       body: JSON.stringify({ ...args, stream: false })
     });
-    const res = name === "ask" ? await (await import("../../ask-GVU5PYC4.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-LVUQLA3C.js")).handleSearch(env, ctx, inner, tier, key);
+    const { runTool, TOOLS_REGISTRY: TOOLS_REGISTRY2 } = await import("../../tools-3AMOGBJG.js");
+    if (TOOLS_REGISTRY2.some((t) => t.name === name && t.audiences.includes("mcp"))) {
+      const r = await runTool({ ...env, DB: env.DB }, { name, args });
+      return r ? { tool: r.name, query: r.query, result: r.output } : { error: { message: `tool ${name} returned nothing for the given arguments` } };
+    }
+    const res = name === "ask" ? await (await import("../../ask-XM5FO6LR.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-LVUQLA3C.js")).handleSearch(env, ctx, inner, tier, key);
     return res.json().catch(() => ({ error: { message: "tool transport failed", status: res.status } }));
   });
   if (out.ok && "accepted" in out) return new Response(null, { status: 202 });

package/package.json

@@ -27,7 +27,7 @@
     "playwright": "^1.62.1",
     "yaml": "^2.9.1"
   },
-  "version": "0.2.84",
+  "version": "0.2.86",
   "description": "The Konneal engine: the publisher-agnostic build pipeline and API plane for standards intelligence (retrieval, answer contract, verdicts, evaluation).",
   "license": "BSD-3-Clause",
   "type": "module",

package/workers/worker_public/src/ask.ts

@@ -1227,7 +1227,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
   await attachFigureImages(env, messages, usedHits, q.query);
   // the agent loop (the owner's 2026-09-28 direction): ONE bounded tool
   // round, armed only where a tool can help. The model may call
-  // register_search through the strict line protocol; the worker
+  // the registry tools through the strict line protocol; the worker
   // executes it deterministically and the ATTRIBUTED result joins the
   // messages — what the tool returned, for the string it asked. The
   // invocations record into pendingTools; the stream emits them as its
@@ -1253,7 +1253,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
       const call = parseToolCall(probeText);
       if (call) {
         mark(`Searching the certificate register for “${String(call.args?.query ?? "")}”`);
-        const result = await runTool(env.DB, call);
+        const result = await runTool(env, call);
         if (result) {
           messages.push({ role: "system", content: toolNote(result) });
           pendingTools.push(result);

package/workers/worker_public/src/mcp-proto.ts

@@ -1,6 +1,7 @@
 // The MCP protocol surface (JSON-RPC 2.0, streamable HTTP 2025-06-18),
 // dependency-free so plain node can load it for unit tests — the
 // route adapter (mcp.ts) owns the handler wiring.
+import { TOOLS_REGISTRY } from "./tools.ts";
 export const PROTOCOL_VERSION = "2025-06-18";
 
 export interface McpTool {
@@ -9,6 +10,8 @@ export interface McpTool {
   inputSchema: { type: "object"; properties: Record<string, unknown>; required: string[] };
 }
 
+// the registry's MCP-audience tools are GENERATED here (OCP: adding a
+// tool registers it; this list is never hand-extended for them)
 export const TOOLS: McpTool[] = [
   {
     name: "ask",
@@ -34,6 +37,17 @@ export const TOOLS: McpTool[] = [
       required: ["query"],
     },
   },
+  ...TOOLS_REGISTRY
+    .filter((t) => t.audiences.includes("mcp"))
+    .map((t): McpTool => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: {
+        type: "object",
+        properties: Object.fromEntries(t.params.map((p) => [p.key, { type: "string", description: p.description }])),
+        required: t.params.filter((p) => p.required).map((p) => p.key),
+      },
+    })),
 ];
 
 export type McpResult =

package/workers/worker_public/src/mcp.ts

@@ -32,6 +32,13 @@ export async function handleMcp(
     });
     // deferred so plain node can load mcp-proto without the handlers'
     // .md prompt imports, which only the bundler resolves
+    // registry tools (certificates.search, units.get, …) dispatch through
+    // the SAME handlers the API would — the no-drift rule, now structural
+    const { runTool, TOOLS_REGISTRY } = await import("./tools.ts");
+    if (TOOLS_REGISTRY.some((t) => t.name === name && t.audiences.includes("mcp"))) {
+      const r = await runTool({ ...env, DB: (env as any).DB }, { name, args });
+      return r ? { tool: r.name, query: r.query, result: r.output } : { error: { message: `tool ${name} returned nothing for the given arguments` } };
+    }
     const res = name === "ask"
       ? await (await import("./ask")).handleAsk(env, ctx as any, inner, tier, key)
       : await (await import("./search")).handleSearch(env, ctx as any, inner, tier, key);

package/workers/worker_public/src/tools-content.ts

@@ -0,0 +1,139 @@
+// The content-plane MCP tools (the owner's 2026-10-04 direction): a
+// content plane earns a tool when its answer is MACHINE-SHAPED —
+// structured data an agent computes with, not prose it re-reads. Every
+// handler wraps the SAME query surface the API serves; entitlement
+// scope rides the metadata the serving path already enforces. These are
+// MCP-audience only: the agent path's declaration stays small because
+// tool-selection quality degrades with menu size.
+import type { ToolSpec } from "./tools.ts";
+import { resolveBlocks } from "./refs.ts";
+
+const slug = (docidentifier: string) =>
+  docidentifier
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+export const unitsGet: ToolSpec = {
+  name: "units.get",
+  description:
+    "Fetch typed Recommendation content — a table, formula or figure as structured data (columns, rows, MathML, caption), by its unit id. The machine-consumable form of a Recommendation's content, for computing with rather than reading.",
+  params: [{ key: "unit_id", required: true, description: "the unit id, e.g. u:table-1 or u:form-3 (ids appear in answers' [[u:…]] references)" }],
+  audiences: ["mcp"],
+  handler: async (env, args) => {
+    const unit_id = String(args?.unit_id ?? "").trim().replace(/^\[?\[?u:/, "u:").replace(/]?\]?$/, "");
+    if (!/^u:[\w.-]+$/.test(unit_id)) return null;
+    const blocks = await resolveBlocks(env.DB, [unit_id]);
+    if (!blocks.length) {
+      return { name: "units.get", query: unit_id, output: `No typed unit "${unit_id}" exists in the indexed payloads. State this plainly.` };
+    }
+    return {
+      name: "units.get",
+      query: unit_id,
+      output: JSON.stringify(
+        blocks.map((b: any) => ({ unit_id: b.unit_id, type: b.type, docidentifier: b.docidentifier, payload: b.payload })),
+      ),
+    };
+  },
+};
+
+export const graphCites: ToolSpec = {
+  name: "graph.cites",
+  description:
+    "The bibliography edges: what a publication's own bibliography actually cites, extracted from its indexed bibliography sections. Returns the cited works' labels for a document (optionally scoped to an edition).",
+  params: [
+    { key: "doc", required: true, description: "the publication identifier, e.g. R 60-1:2021" },
+    { key: "edition", required: false, description: "an edition year to scope, e.g. 2021" },
+  ],
+  audiences: ["mcp"],
+  handler: async (env, args) => {
+    const doc = String(args?.doc ?? "").trim();
+    if (doc.length < 3) return null;
+    const edition = args?.edition ? String(args.edition).trim() : null;
+    const pat = `%${doc.replace(/[:\s]+/g, "%")}%${edition ? edition : ""}%`;
+    try {
+      const rows = await env.DB.prepare(
+        "SELECT DISTINCT n.label AS label FROM graph_edges e JOIN documents d ON e.src = d.canonical_id JOIN graph_nodes n ON e.dst = n.id WHERE d.docidentifier LIKE ?1 AND e.kind = 'cites' ORDER BY label LIMIT 60",
+      )
+        .bind(pat)
+        .all();
+      const labels = ((rows.results ?? []) as { label: string }[]).map((r) => r.label).filter(Boolean);
+      return {
+        name: "graph.cites",
+        query: `${doc}${edition ? ` (${edition})` : ""}`,
+        output: labels.length
+          ? `The publication's bibliography cites:\n${labels.map((l) => `- ${l}`).join("\n")}`
+          : `No bibliography citations are indexed for "${doc}"${edition ? ` (${edition})` : ""}. State this plainly.`,
+      };
+    } catch {
+      return null;
+    }
+  },
+};
+
+export const docsSection: ToolSpec = {
+  name: "docs.section",
+  description:
+    "Fetch one clause of a publication's rendered document — its text and its permanent deep-link URL — for agents that need the human-formatted passage with its anchor.",
+  params: [
+    { key: "doc", required: true, description: "the publication identifier, e.g. R 60-1:2021" },
+    { key: "clause", required: true, description: "the clause anchor, e.g. 5.1.1 or annex-b" },
+  ],
+  audiences: ["mcp"],
+  handler: async (env, args) => {
+    const doc = String(args?.doc ?? "").trim();
+    const clause = String(args?.clause ?? "").trim();
+    if (doc.length < 3 || !clause) return null;
+    try {
+      const rows = await env.DB.prepare(
+        "SELECT docidentifier, clause_anchor, clause_title, text FROM chunks WHERE docidentifier LIKE ?1 AND REPLACE(clause_anchor, ' ', '') = ?2 LIMIT 1",
+      )
+        .bind(`%${doc.replace(/[:\s]+/g, "%")}%`, clause)
+        .all();
+      const r = (rows.results ?? [])[0] as { docidentifier: string; clause_anchor: string; clause_title: string; text: string } | undefined;
+      if (!r) {
+        return { name: "docs.section", query: `${doc} §${clause}`, output: `No clause "${clause}" is indexed for "${doc}". State this plainly.` };
+      }
+      const url = `https://www.ommisa.org/docs/${slug(r.docidentifier)}.html#${r.clause_anchor}`;
+      return {
+        name: "docs.section",
+        query: `${r.docidentifier} §${r.clause_anchor}`,
+        output: JSON.stringify({ docidentifier: r.docidentifier, clause: r.clause_anchor, title: r.clause_title, url, text: (r.text ?? "").slice(0, 4000) }),
+      };
+    } catch {
+      return null;
+    }
+  },
+};
+
+export const glossaryLookup: ToolSpec = {
+  name: "glossary.lookup",
+  description:
+    "Look up a defined term in the terminology datasets — the concept's definition and its defining publication. Bind everyday words to the defined term before interpreting a question.",
+  params: [{ key: "term", required: true, description: "the term or everyday phrase to bind, e.g. creep or load cell" }],
+  audiences: ["mcp"],
+  handler: async (env, args) => {
+    const term = String(args?.term ?? "").trim();
+    if (term.length < 2) return null;
+    try {
+      const rows = await env.DB.prepare(
+        "SELECT clause_title AS term, chunk_text AS text, docidentifier FROM chunks WHERE corpus = 'glossary' AND (clause_title = ?1 OR clause_title LIKE ?2) LIMIT 3",
+      )
+        .bind(term, `%${term}%`)
+        .all();
+      const hits = ((rows.results ?? []) as { term: string; text: string; docidentifier: string }[]).filter((r) => r.term);
+      if (!hits.length) {
+        return { name: "glossary.lookup", query: term, output: `No defined term matches "${term}" in the terminology datasets. State this plainly.` };
+      }
+      return {
+        name: "glossary.lookup",
+        query: term,
+        output: hits
+          .map((r) => `- ${r.term} (${r.docidentifier}): ${String(r.text ?? "").split(" — ").slice(1).join(" — ").slice(0, 400)}`)
+          .join("\n"),
+      };
+    } catch {
+      return null;
+    }
+  },
+};

package/workers/worker_public/src/tools.ts

@@ -17,35 +17,74 @@ export interface ToolResult {
   output: string;
 }
 
-/** The strict protocol: a line `TOOL register_search {"query": "…"}`.
+/** The strict protocol: a line `TOOL certificates.search {"query": "…"}`.
  *  Plain regex parse — no JSON mode needed, tolerant of surrounding
  *  prose (the model may talk around the call). */
 export function parseToolCall(text: string): ToolCall | null {
-  const m = /^TOOL\s+([a-z_]+)\s*(\{[^\n}]*\})?/m.exec(String(text ?? "")); // line-anchored, case-sensitive: prose never trips it
+  const m = /^TOOL\s+([a-z_.]+)\s*(\{[^\n}]*\})?/m.exec(String(text ?? "")); // line-anchored, case-sensitive: prose never trips it
   if (!m) return null;
   let args: Record<string, unknown> = {};
   if (m[2]) {
     try { args = JSON.parse(m[2]); } catch { return null; }
-  } else if (/^TOOL\s+[a-z_]+\s*\{/m.test(String(text ?? ""))) {
+  } else if (/^TOOL\s+[a-z_.]+\s*\{/m.test(String(text ?? ""))) {
     return null; // a malformed call (opened, never closed) is not a call
   }
   return { name: m[1].toLowerCase(), args };
 }
 
-export const TOOL_DECLARATION = `You may use one tool before answering, by writing a single line:
-TOOL register_search {"query": "manufacturer and model to look up"}
-The worker runs it against the certificate register (a snapshot) and returns the matching rows, or the exact no-match statement for the string you asked. Use it when the question turns on certification standing and the holder is known — including from a photograph. Then answer, phrasing the tool's result as what it returned (the searched string stays visible in your answer). If you do not need the tool, answer directly without the line.`;
-
-export async function runTool(db: any, call: ToolCall): Promise<ToolResult | null> {
-  if (call.name !== "register_search") return null;
-  const query = String(call.args?.query ?? "").trim().slice(0, 160);
-  if (!query) return null;
-  const { searchRegister, registerNote } = await import("./certificates");
-  const reg = await searchRegister(db, query, true); // the tool decided — no shaping gate
-  const output = reg?.rows?.length
-    ? registerNote(reg.rows)
-    : `No certificate was found for "${query}" in the certificates database (the register snapshot). State this as the search's result, with the searched string visible.`;
-  return { name: call.name, query, output };
+// ── the tool registry (OCP, the owner's 2026-10-04 direction) ────────
+// ONE declared table is the single source of the tool surface: the agent
+// loop's declaration is GENERATED from it, runTool dispatches by lookup,
+// and the MCP server's tools/list is generated from the same entries.
+// Adding a tool = adding one registration; no call site is edited.
+export interface ToolSpec {
+  /** canonical on every surface */
+  name: string;
+  description: string;
+  params: { key: string; required: boolean; description: string }[];
+  audiences: ("agent" | "mcp")[];
+  handler: (env: any, args: Record<string, unknown>) => Promise<ToolResult | null>;
+}
+
+const certificatesSearch: ToolSpec = {
+  name: "certificates.search",
+  description:
+    "Search the certificate register (a snapshot) by holder name, model designation, or a printed certificate number. Returns the matching rows — number, holder, model, issue year, status, and document links where on file — or the exact no-match statement for the string asked.",
+  params: [{ key: "query", required: true, description: "the holder, model, or printed certificate number to look up" }],
+  audiences: ["agent", "mcp"],
+  handler: async (env, args) => {
+    const query = String(args?.query ?? "").trim().slice(0, 160);
+    if (!query) return null;
+    const { searchRegister, registerNote, certificateLinks } = await import("./certificates");
+    const reg = await searchRegister(env.DB, query, true); // the tool decided — no shaping gate
+    const output = reg?.rows?.length
+      ? [registerNote(reg.rows), certificateLinks(reg.rows)].filter(Boolean).join("\n")
+      : `No certificate was found for "${query}" in the certificates database (the register snapshot). State this as the search's result, with the searched string visible.`;
+    return { name: "certificates.search", query, output };
+  },
+};
+
+import { unitsGet, graphCites, docsSection, glossaryLookup } from "./tools-content.ts";
+
+export const TOOLS_REGISTRY: ToolSpec[] = [certificatesSearch, unitsGet, graphCites, docsSection, glossaryLookup];
+
+/** The agent loop's protocol declaration, GENERATED from the registry —
+ *  the model's tool vocabulary is always the registry's, never a
+ *  hand-maintained literal. */
+export const TOOL_DECLARATION = [
+  "You may use one tool before answering, by writing a single line:",
+  ...TOOLS_REGISTRY.filter((t) => t.audiences.includes("agent")).map((t) => {
+    const shape = `{${t.params.map((p) => `"${p.key}": "<${p.description}>"`).join(", ")}}`;
+    return `TOOL ${t.name} ${shape}`;
+  }),
+  "The worker runs it and returns the result attributed — phrase the tool's result as what it returned, with the searched string visible in your answer. Use a tool when the question turns on what it answers (including from a photograph). If you do not need it, answer directly without the line.",
+].join("\n");
+
+/** Dispatch by LOOKUP — a tool name is never hard-coded at a call site. */
+export async function runTool(env: any, call: ToolCall): Promise<ToolResult | null> {
+  const spec = TOOLS_REGISTRY.find((t) => t.name === call.name && t.audiences.includes("agent"));
+  if (!spec) return null;
+  return spec.handler(env, call.args ?? {});
 }
 
 /** The attributed injection: the answer model sees what the tool