drupal-mcp-connector 2.16.0 → 2.18.0

package/src/lib/draft-write.js

@@ -1,430 +1,19 @@
 /**
- * Sentinel's governed draft-continuation contract (d.o #3621022 / GitHub #176).
- * Core JSON:API revision selectors support reads, not PATCH requests.
- * Translation create/update uses the same surface with X-MCP-Draft-Langcode.
- */
-
-import { entityRevisionId } from "./write-revision.js";
-
-const LANGCODE_RE = /^[a-z][a-z0-9_-]{0,11}$/;
-const MISSING_DRAFT_ENDPOINT =
-  "The site does not provide Sentinel's governed draft endpoint (d.o #3621022). " +
-  "Update the server-side module; the draft was not discarded and no canonical fallback was attempted.";
-const MISSING_TRANSLATION_ENDPOINT =
-  "The site does not provide Sentinel's governed draft-translation endpoint. " +
-  "Update MCP Sentinel; no canonical langcode PATCH was attempted.";
-
-/**
- * @param {unknown} error
- * @param {string} message
- * @returns {Error}
- */
-function missingEndpointError(error, message) {
-  if (/Drupal (404|405)\b/.test(String(error?.message))) {
-    return new Error(message, { cause: error });
-  }
-  return error instanceof Error ? error : new Error(String(error));
-}
-
-/**
- * @param {string} langcode
- * @returns {string}
- */
-export function assertDraftLangcode(langcode) {
-  const value = String(langcode || "").trim();
-  if (!LANGCODE_RE.test(value)) {
-    throw new Error("A valid target langcode is required (for example 'es' or 'pt-br').");
-  }
-  return value;
-}
-
-/**
- * @param {object} [draftRevision]
- * @returns {{live: string, working: string}}
- */
-function requireWorkingPair(draftRevision) {
-  const live = String(draftRevision?.liveVid ?? "");
-  const working = String(draftRevision?.workingVid ?? "");
-  if (!/^[1-9]\d*$/.test(live) || !/^[1-9]\d*$/.test(working) || live === working) {
-    throw new Error("Draft continuation requires distinct, verified live and working node revision IDs.");
-  }
-  return { live, working };
-}
-
-/**
- * @param {object} backend
- * @param {string} entityType
- * @param {string} bundle
- * @param {string} id
- * @returns {string}
- */
-function draftResource(backend, entityType, bundle, id) {
-  if (entityType !== "node" && entityType !== "paragraph") {
-    throw new Error("Governed draft translation is implemented for nodes and paragraphs.");
-  }
-  if (typeof backend.rawQuery !== "function" || typeof backend.resourcePath !== "function") {
-    throw new Error("This backend does not support governed draft continuation.");
-  }
-  return `${backend.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`;
-}
-
-/**
- * @param {object} [draftRevision]
- * @returns {string}
- */
-function requireParagraphRevisionId(draftRevision) {
-  const revisionId = String(draftRevision?.revisionId ?? draftRevision?.workingVid ?? "");
-  if (!/^[1-9]\d*$/.test(revisionId)) {
-    throw new Error("Paragraph translation requires a verified paragraph revision ID.");
-  }
-  return revisionId;
-}
-
-/**
- * Validate or continue a draft, using the same payload and revision precondition.
- * No canonical fallback: an absent endpoint or refused precondition stops work.
- * @param {object} backend JSON:API backend.
- * @param {object} input Canonical update input plus draftRevision.
- * @param {boolean} preflight Validate without saving.
- * @returns {Promise<object>} Preflight metadata or the written canonical entity.
- */
-export async function writeDraft(backend, input, preflight = false) {
-  const { entityType, bundle, id, attributes = {}, relationships, draftRevision, langcode } = input;
-  if (entityType === "paragraph") {
-    return writeParagraphDraft(backend, input, preflight);
-  }
-  const { live, working } = requireWorkingPair(draftRevision);
-  const base = draftResource(backend, entityType, bundle, id);
-  const data = { type: `${entityType}--${bundle}`, id, attributes };
-  if (relationships) data.relationships = relationships;
-  const headers = {
-    "If-Match": `"${live}:${working}"`,
-    "X-MCP-Draft-Preflight": preflight ? "1" : "0",
-  };
-  const targetLang = langcode ? assertDraftLangcode(langcode) : null;
-  if (targetLang) headers["X-MCP-Draft-Langcode"] = targetLang;
-  let result;
-  try {
-    result = await backend.rawQuery({
-      path: `${base}/mcp-draft`,
-      options: { method: "PATCH", headers, body: JSON.stringify({ data }) },
-    });
-  } catch (error) {
-    throw missingEndpointError(error, MISSING_DRAFT_ENDPOINT);
-  }
-  if (preflight) {
-    if (result?.meta?.draft_preflight !== true
-      || String(result.meta.live) !== live || String(result.meta.working) !== working) {
-      throw new Error("The site did not confirm a non-saving draft preflight. Refusing to continue.");
-    }
-    if (targetLang && result.meta.langcode && String(result.meta.langcode) !== targetLang) {
-      throw new Error("The site did not confirm the requested translation language. Refusing to continue.");
-    }
-    return result;
-  }
-  if (!result?.data || result.data.id !== id || result.data.type !== data.type) {
-    throw new Error("Draft write response did not identify the requested entity. The write outcome is uncertain; re-read before retrying.");
-  }
-  return backend.toCanonical(result.data);
-}
-
-/**
- * Create a target-language translation as an unpublished forward revision.
- * If-Match is `"live"` when there is no working copy, or `"live:working"` when
- * adding the language onto an existing unpublished English draft.
- * @param {object} backend
- * @param {object} input
- * @param {boolean} [preflight]
- * @returns {Promise<object>}
- */
-export async function createTranslationDraft(backend, input, preflight = false) {
-  const { entityType, bundle, id, attributes = {}, relationships, draftRevision } = input;
-  const langcode = assertDraftLangcode(input.langcode);
-  if (entityType === "paragraph") {
-    return createParagraphTranslationDraft(backend, {
-      entityType, bundle, id, attributes, relationships, draftRevision, langcode,
-    }, preflight);
-  }
-  const live = String(draftRevision?.liveVid ?? "");
-  const workingRaw = draftRevision?.workingVid;
-  const working = workingRaw === undefined || workingRaw === null || workingRaw === ""
-    ? ""
-    : String(workingRaw);
-  if (entityType !== "node" || !/^[1-9]\d*$/.test(live)) {
-    throw new Error("Translation create requires a verified live node revision ID.");
-  }
-  if (working && (!/^[1-9]\d*$/.test(working) || working === live)) {
-    throw new Error("Translation create requires distinct live and working revision IDs when a working copy exists.");
-  }
-  const base = draftResource(backend, entityType, bundle, id);
-  const safeAttributes = { ...attributes };
-  delete safeAttributes.langcode;
-  const data = { type: `${entityType}--${bundle}`, id, attributes: safeAttributes };
-  if (relationships) data.relationships = relationships;
-  const ifMatch = working ? `"${live}:${working}"` : `"${live}"`;
-  let result;
-  try {
-    result = await backend.rawQuery({
-      path: `${base}/mcp-draft/translations`,
-      options: {
-        method: "POST",
-        headers: {
-          "If-Match": ifMatch,
-          "X-MCP-Draft-Preflight": preflight ? "1" : "0",
-          "X-MCP-Draft-Langcode": langcode,
-        },
-        body: JSON.stringify({ data }),
-      },
-    });
-  } catch (error) {
-    throw rewriteTranslationWorkingRevisionError(missingEndpointError(error, MISSING_TRANSLATION_ENDPOINT));
-  }
-  if (preflight) {
-    if (result?.meta?.draft_preflight !== true || String(result.meta.live) !== live) {
-      throw new Error("The site did not confirm a non-saving translation preflight. Refusing to continue.");
-    }
-    return result;
-  }
-  if (!result?.data || result.data.id !== id || result.data.type !== data.type) {
-    throw new Error("Translation create response did not identify the requested entity. The write outcome is uncertain; re-read before retrying.");
-  }
-  return backend.toCanonical(result.data);
-}
-
-/**
- * Live + working revision ids for a node translation create.
- * Prefers Sentinel's mcp-translations inventory over JSON:API
- * `rel:working-copy`, which 403s on some unpublished drafts even when a
- * working revision exists (#282).
- * @param {object} backend
- * @param {{entityType: string, bundle: string, id: string, existing?: ?object}} ref
- * @returns {Promise<{liveVid: ?(number|string), workingVid: ?(number|string)}>}
- */
-export async function resolveNodeTranslationPair(backend, { entityType, bundle, id, existing }) {
-  const fromEntity = existing ? entityRevisionId(existing) : null;
-  try {
-    const meta = await readTranslationInventory(backend, { entityType, bundle, id });
-    const liveVid = meta.live?.vid ?? fromEntity;
-    const workingVid = meta.working?.vid;
-    const distinct = workingVid !== undefined && workingVid !== null && workingVid !== ""
-      && liveVid !== undefined && liveVid !== null
-      && String(workingVid) !== String(liveVid);
-    return { liveVid, workingVid: distinct ? workingVid : undefined };
-  } catch {
-    if (typeof backend.getEntity !== "function") {
-      return { liveVid: fromEntity, workingVid: undefined };
-    }
-    let workingCopy = null;
-    try {
-      workingCopy = await backend.getEntity({
-        entityType, bundle, id, resourceVersion: "rel:working-copy",
-      });
-    } catch {
-      workingCopy = null;
-    }
-    const workingVid = workingCopy ? entityRevisionId(workingCopy) : null;
-    const distinct = workingVid !== null && fromEntity !== null && String(workingVid) !== String(fromEntity);
-    return { liveVid: fromEntity, workingVid: distinct ? workingVid : undefined };
-  }
-}
-
-/**
- * Rewrite Sentinel's live-only 409 into an actionable connector error.
- * @param {unknown} error
- * @returns {Error}
- */
-export function rewriteTranslationWorkingRevisionError(error) {
-  if (/A working revision exists\. Reload and send both revision IDs/i.test(String(error?.message || ""))) {
-    return new Error(
-      "Translation create sent only the live revision, but a working draft exists. " +
-      "The connector should have sent both live and working revision IDs (If-Match). " +
-      "Reload with drupal_list_translations and retry. See connector #282.",
-      { cause: error instanceof Error ? error : undefined },
-    );
-  }
-  return error instanceof Error ? error : new Error(String(error));
-}
-
-/**
- * Read live/working translation inventory from Sentinel.
- * @param {object} backend
- * @param {{entityType: string, bundle: string, id: string, revisionId?: string|number}} ref
- * @returns {Promise<object>}
- */
-export async function readTranslationInventory(backend, { entityType, bundle, id, revisionId }) {
-  const base = draftResource(backend, entityType, bundle, id);
-  const headers = {};
-  if (revisionId !== undefined && revisionId !== null && revisionId !== "") {
-    headers["If-Match"] = `"${requireParagraphRevisionId({ revisionId })}"`;
-  }
-  try {
-    const result = await backend.rawQuery({
-      path: `${base}/mcp-translations`,
-      options: Object.keys(headers).length ? { method: "GET", headers } : undefined,
-    });
-    if (!result?.meta?.live) {
-      throw new Error("The site did not return a translation inventory.");
-    }
-    return result.meta;
-  } catch (error) {
-    throw missingEndpointError(error, MISSING_TRANSLATION_ENDPOINT);
-  }
-}
-
-/**
- * Read one unpublished working translation.
- * @param {object} backend
- * @param {object} input
- * @returns {Promise<object>}
- */
-export async function readDraftTranslation(backend, input) {
-  const { entityType, bundle, id, draftRevision } = input;
-  const langcode = assertDraftLangcode(input.langcode);
-  if (entityType === "paragraph") {
-    return readParagraphDraftTranslation(backend, input);
-  }
-  const { live, working } = requireWorkingPair(draftRevision);
-  const base = draftResource(backend, entityType, bundle, id);
-  let result;
-  try {
-    result = await backend.rawQuery({
-      path: `${base}/mcp-draft`,
-      options: {
-        method: "GET",
-        headers: {
-          "If-Match": `"${live}:${working}"`,
-          "X-MCP-Draft-Langcode": langcode,
-        },
-      },
-    });
-  } catch (error) {
-    throw missingEndpointError(error, MISSING_TRANSLATION_ENDPOINT);
-  }
-  if (!result?.data || result.data.id !== id) {
-    throw new Error("Draft translation read did not identify the requested entity.");
-  }
-  return backend.toCanonical(result.data);
-}
-
-/**
- * Continue an unpublished paragraph translation on a pinned revision.
- * @param {object} backend
- * @param {object} input
- * @param {boolean} [preflight]
- * @returns {Promise<object>}
- */
-async function writeParagraphDraft(backend, input, preflight = false) {
-  const { entityType, bundle, id, attributes = {}, relationships, draftRevision } = input;
-  const langcode = assertDraftLangcode(input.langcode);
-  const revisionId = requireParagraphRevisionId(draftRevision);
-  const draftState = input.draftState;
-  if (typeof draftState !== "string" || !/^[a-f0-9]{64}$/.test(draftState)) {
-    throw new Error("Paragraph translation update requires draftState from the previous draft read. Re-read the draft; do not retry old copy with a refreshed token.");
-  }
-  const base = draftResource(backend, entityType, bundle, id);
-  const data = { type: `${entityType}--${bundle}`, id, attributes };
-  if (relationships) data.relationships = relationships;
-  const headers = {
-    "If-Match": `"${revisionId}"`,
-    "X-MCP-Draft-Preflight": preflight ? "1" : "0",
-    "X-MCP-Draft-Langcode": langcode,
-    "X-MCP-Draft-State": draftState,
-  };
-  let result;
-  try {
-    result = await backend.rawQuery({
-      path: `${base}/mcp-draft`,
-      options: { method: "PATCH", headers, body: JSON.stringify({ data }) },
-    });
-  } catch (error) {
-    throw missingEndpointError(error, MISSING_DRAFT_ENDPOINT);
-  }
-  if (preflight) {
-    if (result?.meta?.draft_preflight !== true
-      || String(result.meta.live) !== revisionId
-      || (result.meta.langcode && String(result.meta.langcode) !== langcode)) {
-      throw new Error("The site did not confirm a non-saving paragraph translation preflight. Refusing to continue.");
-    }
-    return result;
-  }
-  if (!result?.data || result.data.id !== id || result.data.type !== data.type) {
-    throw new Error("Paragraph translation write did not identify the requested entity. The write outcome is uncertain; re-read before retrying.");
-  }
-  return { ...backend.toCanonical(result.data), draftState: result.meta?.draft_state };
-}
-
-/**
- * Create an unpublished paragraph translation on a pinned revision.
- * @param {object} backend
- * @param {object} input
- * @param {boolean} [preflight]
- * @returns {Promise<object>}
- */
-async function createParagraphTranslationDraft(backend, input, preflight = false) {
-  const { entityType, bundle, id, attributes = {}, relationships, draftRevision, langcode } = input;
-  const revisionId = requireParagraphRevisionId(draftRevision);
-  const base = draftResource(backend, entityType, bundle, id);
-  const safeAttributes = { ...attributes };
-  delete safeAttributes.langcode;
-  const data = { type: `${entityType}--${bundle}`, id, attributes: safeAttributes };
-  if (relationships) data.relationships = relationships;
-  let result;
-  try {
-    result = await backend.rawQuery({
-      path: `${base}/mcp-draft/translations`,
-      options: {
-        method: "POST",
-        headers: {
-          "If-Match": `"${revisionId}"`,
-          "X-MCP-Draft-Preflight": preflight ? "1" : "0",
-          "X-MCP-Draft-Langcode": langcode,
-        },
-        body: JSON.stringify({ data }),
-      },
-    });
-  } catch (error) {
-    throw missingEndpointError(error, MISSING_TRANSLATION_ENDPOINT);
-  }
-  if (preflight) {
-    if (result?.meta?.draft_preflight !== true || String(result.meta.live) !== revisionId) {
-      throw new Error("The site did not confirm a non-saving paragraph translation preflight. Refusing to continue.");
-    }
-    return result;
-  }
-  if (!result?.data || result.data.id !== id || result.data.type !== data.type) {
-    throw new Error("Paragraph translation create did not identify the requested entity. The write outcome is uncertain; re-read before retrying.");
-  }
-  return { ...backend.toCanonical(result.data), draftState: result.meta?.draft_state };
-}
-
-/**
- * Read one unpublished paragraph translation of a pinned revision.
- * @param {object} backend
- * @param {object} input
- * @returns {Promise<object>}
- */
-async function readParagraphDraftTranslation(backend, input) {
-  const { entityType, bundle, id, draftRevision } = input;
-  const langcode = assertDraftLangcode(input.langcode);
-  const revisionId = requireParagraphRevisionId(draftRevision);
-  const base = draftResource(backend, entityType, bundle, id);
-  let result;
-  try {
-    result = await backend.rawQuery({
-      path: `${base}/mcp-draft`,
-      options: {
-        method: "GET",
-        headers: {
-          "If-Match": `"${revisionId}"`,
-          "X-MCP-Draft-Langcode": langcode,
-        },
-      },
-    });
-  } catch (error) {
-    throw missingEndpointError(error, MISSING_TRANSLATION_ENDPOINT);
-  }
-  if (!result?.data || result.data.id !== id) {
-    throw new Error("Paragraph draft translation read did not identify the requested entity.");
-  }
-  return { ...backend.toCanonical(result.data), draftState: result.meta?.draft_state };
-}
+ * Compatibility facade for the Sentinel HTTP client.
+ * New call sites should import from `./sentinel-draft.js`.
+ */
+
+export {
+  assertDraftLangcode,
+  assertInventoryDraftLanguage,
+  createTranslationDraft,
+  isMissingDraftEndpoint,
+  isMissingTranslationEndpoint,
+  readDraftTranslation,
+  readNodeDraftInventory,
+  readTranslationInventory,
+  resolveNodeTranslationPair,
+  rewriteTranslationWorkingRevisionError,
+  supportsSentinelDraft,
+  writeDraft,
+} from "./sentinel-draft.js";

package/src/lib/module-tools.js

@@ -0,0 +1,241 @@
+/** Module-owned schemas and behavior, exposed only by explicit local tool policy. */
+import { createHash } from "node:crypto";
+import Ajv from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import { listServerTools, callServerTool, toolResultData } from "./server-tools.js";
+import { listResolvableSiteConfigs, securityMiddleware } from "./dispatch.js";
+import { getRequestIdentity, principalHasScope, resolveGrantedSites } from "./principal.js";
+import { resolveSecurityConfig, SecurityError } from "./security.js";
+import { assertSourceGovernance, GovernanceError } from "./governance.js";
+import { DataFlowBudgetError } from "./data-flow.js";
+import { toolError } from "./errors.js";
+import { withResolvedTarget } from "./site-target.js";
+
+const PREFIX = "drupal_module_";
+const OPERATIONS = new Set(["read", "write", "delete"]);
+const CAPABILITIES = new Map([
+  ["publish", "allowPublish"], ["configRead", "allowConfigRead"],
+  ["configWrite", "allowConfigWrite"], ["graphql", "allowGraphql"],
+]);
+const MAX_BYTES = 262144;
+const MAX_TOOLS = 256;
+
+function bounded(value, limit = MAX_BYTES) {
+  if (Buffer.byteLength(JSON.stringify(value) ?? "") > limit) {
+    throw new SecurityError("Module tool payload exceeds the protocol ceiling.");
+  }
+}
+
+function entries(sites) {
+  const result = new Map();
+  for (const site of sites) {
+    const config = site.serverTools?.modules;
+    if (!config) continue;
+    if (!/^[a-z][a-z0-9_]{0,23}$/.test(config.namespace ?? "")) {
+      throw new SecurityError("Module tools require a stable namespace.");
+    }
+    for (const [alias, policy] of Object.entries(config.tools ?? {})) {
+      if (!/^[a-z][a-z0-9_]{0,47}$/.test(alias) || !policy ||
+          !/^[A-Za-z0-9_.-]{1,128}$/.test(policy.name ?? "") ||
+          !/^[a-z][a-z0-9_:-]{0,63}$/.test(policy.scope ?? "") ||
+          !OPERATIONS.has(policy.operation) || !Array.isArray(policy.capabilities) ||
+          policy.capabilities.some((cap) => !CAPABILITIES.has(cap) && cap !== "rawSql")) {
+        throw new SecurityError("Invalid module tool policy.");
+      }
+      const name = `${PREFIX}${policy.operation}_${config.namespace}__${alias}`;
+      if (result.has(name) || result.size >= MAX_TOOLS) {
+        throw new SecurityError("Duplicate module namespace or excessive tool policy entries.");
+      }
+      result.set(name, { name, alias, site, policy });
+    }
+  }
+  return result;
+}
+
+function allowed(entry, identity, sites, grants) {
+  const { site, policy } = entry;
+  if (identity && (!principalHasScope(identity, policy.scope) ||
+      !resolveGrantedSites(identity, sites, grants).some((s) => s._name === site._name))) return false;
+  const sec = resolveSecurityConfig(site);
+  if (policy.operation !== "read" && sec.readOnly) return false;
+  if (policy.operation === "delete" && !sec.allowDestructive) return false;
+  return policy.capabilities.every((cap) => cap === "rawSql"
+    ? site.drushSsh?.rawSql === "governed"
+    : Boolean(new Map(Object.entries(sec)).get(CAPABILITIES.get(cap))));
+}
+
+function validator(schema) {
+  if (!schema || schema.type !== "object") throw new Error("Object schema required.");
+  bounded(schema, 65536);
+  // Providers may put constraints beside nullable oneOf types. strictTypes
+  // rejects that valid JSON Schema shape; runtime type checks still apply.
+  const ajv = new Ajv({ strict: true, strictTypes: false, allErrors: false, ownProperties: true });
+  addFormats(ajv);
+  const check = ajv.compile(schema);
+  if (check.$async) throw new Error("Async schemas are unavailable.");
+  return check;
+}
+
+async function catalog(site, list) {
+  // Extensions always require source governance, including development sites.
+  await assertSourceGovernance({ ...site, requireGovernance: true });
+  const found = new Map();
+  const seen = new Set();
+  let cursor;
+  let bytes = 0;
+  for (let page = 0; page < 16; page++) {
+    const result = await list(site, cursor);
+    bounded(result);
+    bytes += Buffer.byteLength(JSON.stringify(result));
+    if (bytes > MAX_BYTES || !Array.isArray(result?.tools)) throw new Error("Invalid module catalog.");
+    for (const tool of result.tools) {
+      if (typeof tool?.name !== "string" || found.has(tool.name) || found.size >= MAX_TOOLS) {
+        throw new Error("Invalid or duplicate module tool.");
+      }
+      found.set(tool.name, tool);
+    }
+    if (result.nextCursor === undefined || result.nextCursor === null) return found;
+    if (typeof result.nextCursor !== "string" || seen.has(result.nextCursor)) throw new Error("Invalid catalog cursor.");
+    cursor = result.nextCursor;
+    seen.add(cursor);
+  }
+  throw new Error("Module catalog page limit exceeded.");
+}
+
+function describe(entry, remote) {
+  const input = validator(remote.inputSchema);
+  const output = remote.outputSchema ? validator(remote.outputSchema) : null;
+  const revision = createHash("sha256").update(JSON.stringify({
+    input: remote.inputSchema, output: remote.outputSchema ?? null, policy: entry.policy,
+  })).digest("hex");
+  return { input, output, revision, definition: {
+    name: entry.name,
+    description: `${String(remote.description ?? remote.name).slice(0, 4096)} [${entry.site._name}]`,
+    inputSchema: {
+      type: "object", additionalProperties: false, required: ["catalogRevision", "arguments"],
+      properties: {
+        catalogRevision: { type: "string", const: revision },
+        arguments: { ...remote.inputSchema, $id: remote.inputSchema.$id ?? `urn:module:input:${revision}` },
+      },
+    },
+    annotations: {
+      readOnlyHint: entry.policy.operation === "read",
+      destructiveHint: entry.policy.operation !== "read",
+      idempotentHint: false, openWorldHint: true,
+    },
+    ...(remote.outputSchema ? { outputSchema: {
+      type: "object", required: ["result", "_target"],
+      properties: {
+        result: { ...remote.outputSchema, $id: remote.outputSchema.$id ?? `urn:module:output:${revision}` },
+        _target: { type: "object" },
+      },
+    } } : {}),
+  } };
+}
+
+/** Reserved module names never fall back to built-in handlers. */
+export function isModuleTool(name) {
+  return typeof name === "string" && name.startsWith(PREFIX);
+}
+
+/** Resolves a local binding without granting access or contacting its provider. */
+export function resolveModuleBinding(site, binding, required) {
+  const bindings = new Map(Object.entries(site.serverTools?.bindings ?? {}));
+  const alias = bindings.get(binding);
+  const entry = [...entries([site]).values()].find((item) => item.alias === alias);
+  if (!entry || entry.policy.operation !== required.operation ||
+      entry.policy.scope !== required.scope ||
+      !required.capabilities.every((cap) => entry.policy.capabilities.includes(cap))) {
+    throw new SecurityError("Module binding is missing or does not satisfy the operation contract.");
+  }
+  return entry;
+}
+
+/**
+ * Build a registry without cross-request catalog or authorization caches.
+ * Transport injection lets unrelated fixture providers prove generic dispatch.
+ */
+export function createModuleToolRegistry({ list = listServerTools, call = callServerTool } = {}) {
+  const registry = {
+    /** Invoke a locally bound compatibility operation through normal discovery. */
+    async callBinding(site, binding, args, required, context = {}) {
+      const entry = resolveModuleBinding(site, binding, required);
+      const ctx = { ...context, sites: [site] };
+      const definition = (await registry.list(ctx)).find((item) => item.name === entry.name);
+      if (!definition) throw new SecurityError("Bound module tool is unavailable for this caller.");
+      const result = await registry.call(entry.name, {
+        arguments: args,
+        catalogRevision: definition.inputSchema.properties.catalogRevision.const,
+      }, ctx);
+      if (result.isError) throw new SecurityError("Bound module tool refused the request; no fallback was attempted.");
+      // Compatibility callers consume the original Tool API result, not the
+      // module registry's result/target envelope. Keep the established shape.
+      const data = result.structuredContent.result;
+      return { content: [{ type: "text", text: JSON.stringify(data) }], structuredContent: data };
+    },
+    async list(context = {}) {
+      const sites = context.sites ?? listResolvableSiteConfigs();
+      const identity = context.identity === undefined ? getRequestIdentity() : context.identity;
+      const enabled = [...entries(sites).values()].filter((entry) => allowed(entry, identity, sites, context.grants));
+      const catalogs = new Map();
+      const definitions = [];
+      for (const entry of enabled) {
+        if (!catalogs.has(entry.site._name)) {
+          try {
+            const found = await securityMiddleware(entry.name, { site: entry.site._name },
+              () => catalog(entry.site, list), { ...context, sites, identity, moduleTool: entry.policy });
+            catalogs.set(entry.site._name, found);
+          }
+          catch {
+            // A failed catalog fetch invalidates this provider for the request.
+            catalogs.set(entry.site._name, new Map());
+          }
+        }
+        try {
+          const remote = catalogs.get(entry.site._name).get(entry.policy.name);
+          if (remote) definitions.push(describe(entry, remote).definition);
+        } catch {
+          // A malformed schema disables only that action, not its siblings.
+        }
+      }
+      return definitions.sort((a, b) => a.name.localeCompare(b.name));
+    },
+    async call(name, args, context = {}) {
+      try {
+        const sites = context.sites ?? listResolvableSiteConfigs();
+        const identity = context.identity === undefined ? getRequestIdentity() : context.identity;
+        const entry = entries(sites).get(name);
+        if (!entry || !allowed(entry, identity, sites, context.grants)) throw new SecurityError("Module tool is not enabled for this caller.");
+        bounded(args);
+        if (!args || Object.keys(args).some((key) => !["arguments", "catalogRevision"].includes(key))) {
+          throw new SecurityError("Invalid module tool arguments.");
+        }
+        const invokeContext = { ...context, sites, identity, moduleTool: entry.policy };
+        return await securityMiddleware(name, { site: entry.site._name }, async () => {
+          const remote = (await catalog(entry.site, list)).get(entry.policy.name);
+          if (!remote) throw new SecurityError("Module tool is no longer available.");
+          const spec = describe(entry, remote);
+          if (args.catalogRevision !== spec.revision || !spec.input(args.arguments)) {
+            throw new SecurityError("Module tool schema changed or arguments are invalid. Refresh tools/list.");
+          }
+          const result = await call(entry.site, entry.policy.name, args.arguments, {
+            maxBytes: MAX_BYTES, preserveErrors: true, retryRejected: entry.policy.operation === "read",
+          });
+          bounded(result);
+          if (!Array.isArray(result?.content) || result.content.some((item) => item.type !== "text")) {
+            throw new Error("Unsupported module result content.");
+          }
+          const data = toolResultData(result);
+          const failed = result.isError === true || data?.success === false;
+          if (!failed && spec.output && !spec.output(data)) throw new Error("Invalid module output schema.");
+          const structuredContent = withResolvedTarget({ result: data }, invokeContext.resolvedTarget);
+          return { content: [{ type: "text", text: JSON.stringify(structuredContent) }], structuredContent, isError: failed };
+        }, invokeContext);
+      } catch (error) {
+        const safe = error instanceof SecurityError || error instanceof GovernanceError || error instanceof DataFlowBudgetError;
+        return toolError(safe ? error : new Error("Module tool unavailable or returned an invalid response. No fallback was attempted."));
+      }
+    },
+  };
+  return registry;
+}