drupal-mcp-connector 2.16.0 → 2.18.0

package/src/lib/server-tools.js

@@ -23,10 +23,19 @@
  */
 
 import fetch from "node-fetch";
+import { createHmac, randomBytes } from "node:crypto";
 import { authHeadersAsync, clientHeaders, CLIENT_NAME, CLIENT_VERSION } from "./config.js";
-import { consumeBudgetIfEnforced, northboundHeaders, sourceBudgetDenial } from "./data-flow.js";
+import { consumeBudgetIfEnforced, northboundHeaders, sourceBudgetDenial, getDataFlowContext } from "./data-flow.js";
 import { clearToken } from "./oauth.js";
 
+/** Calls a configured module binding through the registry, without fallback. */
+export async function callBoundModuleTool(site, binding, args, required) {
+  // Load at invocation: built-in tool definitions are also consumed by the
+  // registry's dispatch middleware, so a static import would create a cycle.
+  const { createModuleToolRegistry } = await import("./module-tools.js");
+  return createModuleToolRegistry().callBinding(site, binding, args, required);
+}
+
 /**
  * Canonical server-side tool names for governed config operations.
  *
@@ -50,11 +59,14 @@ const MCP_PROTOCOL_VERSION = "2025-06-18";
 let rpcId = 0;
 
 /**
- * Per-site MCP session cache, keyed by site._name. Holds the `Mcp-Session-Id`
+ * MCP session cache, keyed by site, endpoint, credentials and principal. Holds the `Mcp-Session-Id`
  * issued by the server's `initialize` response; cleared and re-acquired when the
  * server reports the session is gone (expiry).
  */
 const sessions = new Map();
+// Ephemeral cache identity only, never a persisted password verifier. A keyed
+// digest also prevents offline guessing if a diagnostic exposes a cache key.
+const sessionIdentityKey = randomBytes(32);
 
 /**
  * Resolve a site's server-tools endpoint, or throw a clear, actionable error
@@ -156,7 +168,7 @@ function parseSse(text) {
  * @returns {Promise<string>} The issued MCP session id.
  * @throws {Error} on transport failure, a JSON-RPC error, or a missing session id.
  */
-async function initializeSession(site, endpoint) {
+async function initializeSession(site, endpoint, key) {
   const payload = {
     jsonrpc: "2.0",
     id: ++rpcId,
@@ -173,6 +185,8 @@ async function initializeSession(site, endpoint) {
       method: "POST",
       headers: await baseHeaders(site, null),
       body: JSON.stringify(payload),
+      size: 262144,
+      signal: AbortSignal.timeout(15000),
     });
 
   let res = await post();
@@ -205,12 +219,15 @@ async function initializeSession(site, endpoint) {
       method: "POST",
       headers: await baseHeaders(site, sessionId),
       body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
+      size: 262144,
+      signal: AbortSignal.timeout(15000),
     });
   } catch {
     // Notification is advisory; proceed with the established session.
   }
 
-  sessions.set(site._name, sessionId);
+  if (sessions.size >= 128) sessions.delete(sessions.keys().next().value);
+  sessions.set(key, sessionId);
   return sessionId;
 }
 
@@ -220,9 +237,9 @@ async function initializeSession(site, endpoint) {
  * @param {string} endpoint Fully-qualified endpoint URL.
  * @returns {Promise<string>} The active MCP session id.
  */
-async function ensureSession(site, endpoint) {
-  const cached = sessions.get(site._name);
-  return cached || initializeSession(site, endpoint);
+async function ensureSession(site, endpoint, key) {
+  const cached = sessions.get(key);
+  return cached || initializeSession(site, endpoint, key);
 }
 
 /**
@@ -253,16 +270,32 @@ function isSessionError(res, body) {
  * @returns {Promise<*>} The tool's structured result.
  * @throws {Error} on transport failure, JSON-RPC error, or tool error.
  */
-export async function callServerTool(site, toolName, args = {}) {
+export async function callServerTool(site, toolName, args = {}, options = {}) {
+  return requestServerTool(site, "tools/call", { name: toolName, arguments: args }, options);
+}
+
+/** Fetch one page of the authenticated module tool catalog. */
+export async function listServerTools(site, cursor) {
+  return requestServerTool(site, "tools/list", cursor === undefined ? {} : { cursor }, {
+    maxBytes: 262144, preserveErrors: true,
+  });
+}
+
+/** Shared bounded MCP request transport; retries only explicit auth/session rejection. */
+async function requestServerTool(site, method, params, options) {
+  const toolName = params.name ?? method;
   const endpoint = resolveEndpoint(site);
   const payload = {
     jsonrpc: "2.0",
     id: ++rpcId,
-    method: "tools/call",
-    params: { name: toolName, arguments: args },
+    method,
+    params,
   };
 
-  let sessionId = await ensureSession(site, endpoint);
+  const sessionKey = createHmac("sha256", sessionIdentityKey).update(JSON.stringify([
+    site._name, endpoint, await authHeadersAsync(site), getDataFlowContext()?.principalKey ?? null,
+  ])).digest("hex");
+  let sessionId = await ensureSession(site, endpoint, sessionKey);
   let refreshedAuth = false;
   let reinitedSession = false;
   let paid = false;
@@ -275,21 +308,22 @@ export async function callServerTool(site, toolName, args = {}) {
       method: "POST",
       headers: await baseHeaders(site, sessionId),
       body: JSON.stringify(payload),
+      ...(options.maxBytes ? { size: options.maxBytes, signal: AbortSignal.timeout(15000) } : {}),
     });
     const { body, rawText } = await readBody(res);
 
     // OAuth sites: a 401 may mean the token expired server-side. Refresh once.
-    if (res.status === 401 && site.oauth && !refreshedAuth) {
+    if (res.status === 401 && site.oauth && !refreshedAuth && options.retryRejected !== false) {
       refreshedAuth = true;
       clearToken(site);
       continue;
     }
 
     // Session expired/unknown: re-initialise once and replay.
-    if (isSessionError(res, body) && !reinitedSession) {
+    if (isSessionError(res, body) && !reinitedSession && options.retryRejected !== false) {
       reinitedSession = true;
-      sessions.delete(site._name);
-      sessionId = await ensureSession(site, endpoint);
+      sessions.delete(sessionKey);
+      sessionId = await ensureSession(site, endpoint, sessionKey);
       continue;
     }
 
@@ -308,7 +342,7 @@ export async function callServerTool(site, toolName, args = {}) {
 
     // MCP tools/call result: { content: [...], isError?: boolean }.
     const result = body?.result;
-    if (result?.isError) {
+    if (result?.isError && !options.preserveErrors) {
       const detail = extractTextContent(result) || "tool reported an error";
       const mapped = sourceBudgetDenial(detail);
       if (mapped) throw mapped;

package/src/lib/verify.js

@@ -738,7 +738,13 @@ export async function verifyLive(site, { transport, callTool = null, contentTarg
    */
   const attemptConfigWrite = async () => {
     try {
-      await callTool(site, CONFIG_SET_TOOL, { name: "system.site", data: { name: "verification probe" } });
+      // The negative probe must reach source authorization, not merely prove
+      // that the connector hides out-of-tier tools from discovery.
+      const tool = site.serverTools?.bindings === undefined ? CONFIG_SET_TOOL
+        : (await import("./module-tools.js")).resolveModuleBinding(site, "configSet", {
+          operation: "write", scope: "mcp_config", capabilities: ["configWrite"],
+        }).policy.name;
+      await callTool(site, tool, { name: "system.site", data: { name: "verification probe" } });
       return { served: true, outcome: "served", detail: "accepted" };
     } catch (err) {
       // Not every throw is a refusal — see classifyBridgeError.

package/src/tools/config.js

@@ -22,7 +22,17 @@ import {
   assertConfigScope,
   hasScope,
 } from "../lib/security.js";
-import { callServerTool, SERVER_TOOLS } from "../lib/server-tools.js";
+import { callServerTool, callBoundModuleTool, SERVER_TOOLS } from "../lib/server-tools.js";
+
+/** Compatibility names use an approved module binding when configured. */
+async function configTool(site, binding, args, operation, capability) {
+  if (site.serverTools?.bindings !== undefined) {
+    return callBoundModuleTool(site, binding, args, {
+      operation, scope: "mcp_config", capabilities: [capability],
+    });
+  }
+  return callServerTool(site, new Map(Object.entries(SERVER_TOOLS)).get(binding), args);
+}
 
 // ---------------------------------------------------------------------------
 // Config tools (governed via the server-tool bridge)
@@ -38,7 +48,7 @@ async function configGet({ site: siteName, name }) {
   const site = getSiteConfig(siteName);
   assertConfigScope(site, `config:get ${name}`);
   assertConfigReadAllowed(resolveSecurityConfig(site));
-  return callServerTool(site, SERVER_TOOLS.configGet, { name });
+  return configTool(site, "configGet", { name }, "read", "configRead");
 }
 
 /**
@@ -52,7 +62,7 @@ async function configList({ site: siteName, prefix }) {
   assertConfigScope(site, "config:list");
   assertConfigReadAllowed(resolveSecurityConfig(site));
   const args = prefix ? { prefix } : {};
-  return callServerTool(site, SERVER_TOOLS.configList, args);
+  return configTool(site, "configList", args, "read", "configRead");
 }
 
 /**
@@ -73,7 +83,7 @@ async function configSet({ site: siteName, name, value }) {
   assertConfigScope(site, `config:set ${name}`);
   assertNotReadOnly(sec, `config:set ${name}`);
   assertConfigWriteAllowed(sec);
-  return callServerTool(site, SERVER_TOOLS.configSet, { name, data: value });
+  return configTool(site, "configSet", { name, data: value }, "write", "configWrite");
 }
 
 // ---------------------------------------------------------------------------

package/src/tools/media.js

@@ -14,6 +14,11 @@ import {
   resolveSecurityConfig, redactCanonicalEntity,
   assertReadAllowed, assertWriteAllowed, assertDeleteAllowed, assertPublishAllowed,
 } from "../lib/security.js";
+import {
+  assertDraftLangcode, readDraftTranslation, readTranslationInventory,
+} from "../lib/sentinel-draft.js";
+import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
+import { entityRevisionId } from "../lib/write-revision.js";
 
 /**
  * List all media types (bundles of the media entity type).
@@ -51,14 +56,39 @@ async function listMedia({ site: siteName, type, status, name, limit = 20, offse
 
 /**
  * Fetch a single media entity by UUID, redacted per policy.
- * @param {object} args - { site?, type, id }.
+ * Pass langcode to read an unpublished working translation via Sentinel.
+ * @param {object} args - { site?, type, id, langcode? }.
  * @returns {Promise<object|null>} The redacted media entity, or null.
  */
-async function getMedia({ site: siteName, type, id }) {
+async function getMedia({ site: siteName, type, id, langcode }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "media", type);
   const backend = await resolveBackend(site);
+  if (langcode) {
+    const targetLang = assertDraftLangcode(langcode);
+    const inventory = await readTranslationInventory(backend, { entityType: "media", bundle: type, id });
+    const workingRow = (inventory.working?.translations ?? []).find((row) => row.langcode === targetLang);
+    if (workingRow && workingRow.status === false && inventory.live?.vid && inventory.working?.vid) {
+      const entity = await readDraftTranslation(backend, {
+        entityType: "media", bundle: type, id, langcode: targetLang,
+        draftRevision: { liveVid: inventory.live.vid, workingVid: inventory.working.vid },
+      });
+      return redactCanonicalEntity(entity, sec, "media");
+    }
+    const liveHas = (inventory.live?.translations ?? []).some((row) => row.langcode === targetLang);
+    if (!liveHas) return null;
+    if (targetLang !== inventory.defaultLangcode) {
+      const liveRow = (inventory.live.translations ?? []).find((row) => row.langcode === targetLang);
+      return {
+        id, entityType: "media", bundle: type, langcode: targetLang,
+        status: liveRow?.status ?? null,
+        fields: { name: liveRow?.name ?? null },
+        _revisions: { live: inventory.live.vid, working: inventory.working?.vid ?? null },
+        note: "Published non-default translations are listed on the live revision; full field reads of an unpublished working translation use langcode against the working draft.",
+      };
+    }
+  }
   const entity = await backend.getEntity({ entityType: "media", bundle: type, id });
   return entity ? redactCanonicalEntity(entity, sec, "media") : null;
 }
@@ -91,12 +121,13 @@ async function createMedia({ site: siteName, type, name, status = false, fields
 /**
  * Update a media entity (partial — omitted fields are left untouched; `status`
  * is strictly opt-in, #171). Reference-shaped `fields` values are routed to
- * relationships — see splitReferenceFields.
+ * relationships — see splitReferenceFields. Pass langcode to continue an
+ * unpublished working translation via Sentinel (not a canonical live PATCH).
  *
- * @param {object} args - { site?, type, id, name?, status?, fields? }.
+ * @param {object} args - { site?, type, id, name?, status?, fields?, langcode? }.
  * @returns {Promise<object>} The updated media descriptor.
  */
-async function updateMedia({ site: siteName, type, id, name, status, fields = {} }) {
+async function updateMedia({ site: siteName, type, id, name, status, fields = {}, langcode }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", "media", type);
@@ -105,6 +136,26 @@ async function updateMedia({ site: siteName, type, id, name, status, fields = {}
   if (status !== undefined) attributes.status = status;
   assertPublishAllowed(sec, attributes);
   const backend = await resolveBackend(site);
+  if (langcode) {
+    const targetLang = assertDraftLangcode(langcode);
+    const patchTarget = await prepareGuardedPatch(backend, {
+      entityType: "media", bundle: type, id, attributes,
+      ...(relationships ? { relationships } : {}),
+      langcode: targetLang,
+    });
+    const result = await updateEntityGuarded(backend, {
+      entityType: "media", bundle: type, id, attributes,
+      ...(relationships ? { relationships } : {}),
+      langcode: targetLang,
+      ...(patchTarget.draftRevision ? { draftRevision: patchTarget.draftRevision } : {}),
+    });
+    const redacted = redactCanonicalEntity(result, sec, "media");
+    const working = entityRevisionId(result) ?? patchTarget.workingVid;
+    return {
+      ...redacted,
+      _revisions: { live: patchTarget.liveVid, working },
+    };
+  }
   // #171: pre-read so an unrequested published-state flip is reported, not silent.
   let existing = null;
   if (status === undefined) {
@@ -241,13 +292,14 @@ export const definitions = [
   },
   {
     name: "drupal_get_media",
-    description: "Fetch a single media entity by UUID and media type.",
+    description: "Fetch a single media entity by UUID and media type. Image alt/title are on the file relationship (meta.alt / meta.title). Pass langcode to read an unpublished working translation via Sentinel.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
         site: { type: "string" },
         type: { type: "string" },
         id:   { type: "string", description: "Media entity UUID" },
+        langcode: { type: "string", description: "Target language (e.g. 'es') to read the unpublished working translation instead of the default language." },
       },
     },
   },
@@ -267,7 +319,7 @@ export const definitions = [
   },
   {
     name: "drupal_update_media",
-    description: "Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched.",
+    description: "Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched. Pass langcode to continue an unpublished working translation via Sentinel; this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
@@ -276,7 +328,8 @@ export const definitions = [
         id:     { type: "string" },
         name:   { type: "string" },
         status: { type: "boolean", description: "Published flag. Only sent when provided; requires allowPublish when true." },
-        fields: { type: "object", description: "Field values. Entity-reference values in JSON:API linkage shape ({ data: { type, id } }) are sent as relationships automatically." },
+        fields: { type: "object", description: "Field values. Entity-reference values in JSON:API linkage shape ({ data: { type, id } }) are sent as relationships automatically. Image alt is meta.alt on field_media_image with the existing file UUID." },
+        langcode: { type: "string", description: "Target language for an unpublished working translation (e.g. 'es'). Continues that translation via Sentinel; does not create a missing translation and does not PATCH canonical langcode." },
       },
     },
   },

package/src/tools/moderation.js

@@ -22,7 +22,9 @@ import {
 } from "../lib/security.js";
 import { collectEntities } from "../lib/reports-support.js";
 import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
-import { assertDraftLangcode, readTranslationInventory } from "../lib/draft-write.js";
+import {
+  assertDraftLangcode, isMissingTranslationEndpoint, readTranslationInventory, supportsSentinelDraft,
+} from "../lib/sentinel-draft.js";
 import { inventoryRowMatching } from "../lib/translation-rows.js";
 
 /** Cap for the client-side scan when JSON:API cannot filter the field. */
@@ -65,25 +67,23 @@ async function setModerationState({ site: siteName, type, id, state, langcode })
   const attributes = { moderation_state: state };
   assertPublishAllowed(sec, attributes);
   const backend = await resolveBackend(site);
-  if (langcode) {
-    const targetLang = assertDraftLangcode(langcode);
-    let existing = null;
-    try {
-      existing = (await backend.getEntity({ entityType: "node", bundle: type, id })) ?? null;
-    } catch {
-      existing = null;
-    }
-    const patchTarget = await prepareGuardedPatch(backend, {
-      entityType: "node", bundle: type, id, existing, attributes, langcode: targetLang,
-    });
-    const patched = await updateEntityGuarded(backend, {
-      entityType: "node", bundle: type, id, attributes, langcode: targetLang,
-      ...(patchTarget.draftRevision ? { draftRevision: patchTarget.draftRevision } : {}),
-    });
-    return redactCanonicalEntity(patched, sec, "node");
+  const targetLang = langcode ? assertDraftLangcode(langcode) : undefined;
+  let existing = null;
+  try {
+    existing = (await backend.getEntity({ entityType: "node", bundle: type, id })) ?? null;
+  } catch {
+    existing = null;
   }
-  const entity = await backend.updateEntity({ entityType: "node", bundle: type, id, attributes });
-  return redactCanonicalEntity(entity, sec, "node");
+  const patchTarget = await prepareGuardedPatch(backend, {
+    entityType: "node", bundle: type, id, existing, attributes,
+    ...(targetLang ? { langcode: targetLang } : {}),
+  });
+  const patched = await updateEntityGuarded(backend, {
+    entityType: "node", bundle: type, id, attributes,
+    ...(targetLang ? { langcode: targetLang } : {}),
+    ...(patchTarget.draftRevision ? { draftRevision: patchTarget.draftRevision } : {}),
+  });
+  return redactCanonicalEntity(patched, sec, "node");
 }
 
 /**
@@ -104,7 +104,7 @@ async function contentByModerationState({ site: siteName, type, state, limit = 2
   const sort = [{ field: "changed", dir: "desc" }];
   const targetLang = langcode ? assertDraftLangcode(langcode) : null;
   if (targetLang) {
-    if (typeof backend.rawQuery !== "function" || typeof backend.resourcePath !== "function") {
+    if (!supportsSentinelDraft(backend)) {
       return {
         type, state, langcode: targetLang, unavailable: true,
         reason: "A langcode filter requires Sentinel's translation inventory.",
@@ -130,7 +130,7 @@ async function contentByModerationState({ site: siteName, type, state, limit = 2
           });
         }
       } catch (error) {
-        if (/does not provide Sentinel's governed draft-translation endpoint/.test(String(error?.message))) {
+        if (isMissingTranslationEndpoint(error)) {
           return {
             type, state, langcode: targetLang, unavailable: true,
             reason: "A langcode filter requires Sentinel's translation inventory.",

package/src/tools/nodes.js

@@ -18,7 +18,7 @@ import { shapeWriteResponse, flagUnrequestedStatusChange, RETURNING_SCHEMA, omit
 import { resolveErrRelationships, relationshipsWereSent, paragraphPinsFromEntity } from "../lib/err-relationships.js";
 import { attachWrittenRevisionPair, readWrittenRevision } from "../lib/write-revision.js";
 import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
-import { assertDraftLangcode, readDraftTranslation, readTranslationInventory } from "../lib/draft-write.js";
+import { assertDraftLangcode, readDraftTranslation, readTranslationInventory } from "../lib/sentinel-draft.js";
 import { paragraphResourceVersion } from "./paragraphs.js";
 import { assertBodySummaryWritable, attachSummaryDeprecation } from "../lib/body-summary.js";
 import { buildRedirectAttributes, REDIRECT_ENTITY_TYPE } from "./redirects.js";

package/src/tools/paragraphs.js

@@ -46,7 +46,7 @@ import {
   assertDraftLangcode,
   readDraftTranslation,
   writeDraft,
-} from "../lib/draft-write.js";
+} from "../lib/sentinel-draft.js";
 
 /**
  * Build the resource-identifier ref used to embed a paragraph in a host ERR /

package/src/tools/reports-config.js

@@ -20,7 +20,7 @@
 import { getSiteConfig } from "../lib/config.js";
 import { resolveSecurityConfig, assertConfigReadAllowed } from "../lib/security.js";
 import { gatedReport } from "../lib/reports-support.js";
-import { callServerTool, SERVER_TOOLS, toolResultData } from "../lib/server-tools.js";
+import { callServerTool, callBoundModuleTool, SERVER_TOOLS, toolResultData } from "../lib/server-tools.js";
 import { runPrivileged, serverToolsConfigured, drushConfigured } from "../lib/audit-sources.js";
 import { sshDrush, parseDrush } from "./drush.js";
 
@@ -65,6 +65,11 @@ function configSourceAvailable(site) {
  * @returns {Promise<*>} Parsed config object (or null/text).
  */
 async function readConfig(site, name) {
+  if (site.serverTools?.bindings !== undefined) {
+    return toolResultData(await callBoundModuleTool(site, "configGet", { name }, {
+      operation: "read", scope: "mcp_config", capabilities: ["configRead"],
+    }));
+  }
   if (serverToolsConfigured(site)) {
     try { return toolResultData(await callServerTool(site, SERVER_TOOLS.configGet, { name })); }
     catch (err) { if (!drushConfigured(site)) throw err; }
@@ -82,6 +87,11 @@ async function readConfig(site, name) {
  * @returns {Promise<string[]>} Config object names.
  */
 async function listConfigNames(site, prefix) {
+  if (site.serverTools?.bindings !== undefined) {
+    return pickConfigNames(toolResultData(await callBoundModuleTool(site, "configList", { prefix }, {
+      operation: "read", scope: "mcp_config", capabilities: ["configRead"],
+    })));
+  }
   if (serverToolsConfigured(site)) {
     try { return pickConfigNames(toolResultData(await callServerTool(site, SERVER_TOOLS.configList, { prefix }))); }
     catch (err) { if (!drushConfigured(site)) throw err; }

package/src/tools/reports-content.js

@@ -17,7 +17,9 @@ import { resolveBackend } from "../lib/backends/index.js";
 import { resolveSecurityConfig, assertReadAllowed } from "../lib/security.js";
 import { collectEntities, fieldValue, daysSince } from "../lib/reports-support.js";
 import { bodyHtml, extractAnchors, classifyLink, normalizePath } from "../lib/audit-support.js";
-import { assertDraftLangcode, readTranslationInventory } from "../lib/draft-write.js";
+import {
+  assertDraftLangcode, isMissingTranslationEndpoint, readTranslationInventory, supportsSentinelDraft,
+} from "../lib/sentinel-draft.js";
 import { inventoryRowMatching, inventoryTranslationRows, mapTranslationRow } from "../lib/translation-rows.js";
 
 // ---------------------------------------------------------------------------
@@ -116,7 +118,7 @@ async function workflowBottlenecks({ site: siteName, type, days = 30, states, sa
     sampleSize
   );
 
-  if (targetLang && (typeof backend.rawQuery !== "function" || typeof backend.resourcePath !== "function")) {
+  if (targetLang && !supportsSentinelDraft(backend)) {
     return {
       contentType,
       unavailable: true,
@@ -139,7 +141,7 @@ async function workflowBottlenecks({ site: siteName, type, days = 30, states, sa
         if (!row) continue;
         state = row.moderation_state;
       } catch (error) {
-        if (/does not provide Sentinel's governed draft-translation endpoint/.test(String(error?.message))) {
+        if (isMissingTranslationEndpoint(error)) {
           return {
             contentType,
             unavailable: true,
@@ -207,8 +209,7 @@ async function translationCoverage({ site: siteName, type, sampleSize = 100 }) {
     sampleSize
   );
 
-  const missingEndpoint = /does not provide Sentinel's governed draft-translation endpoint/;
-  if (typeof backend.rawQuery !== "function" || typeof backend.resourcePath !== "function") {
+  if (!supportsSentinelDraft(backend)) {
     return {
       contentType,
       scanned: nodes.length,
@@ -239,7 +240,7 @@ async function translationCoverage({ site: siteName, type, sampleSize = 100 }) {
         outdated: rows.some((row) => row.outdated === true),
       });
     } catch (error) {
-      if (!missingEndpoint.test(String(error?.message))) throw error;
+      if (!isMissingTranslationEndpoint(error)) throw error;
     }
   }
 

package/src/tools/revisions.js

@@ -11,8 +11,8 @@
  *     full chronological history enumeration requires the Drush bridge.
  *   - drupal_get_revision fetches one specific version (by vid or alias).
  *   - drupal_revert_revision is a GOVERNED WRITE: it reads the target revision
- *     and replays its editable attributes through updateEntity to make them the
- *     new current revision (assertWriteAllowed gates it; internal/immutable
+ *     and replays its editable attributes through prepareGuardedPatch /
+ *     updateEntityGuarded (assertWriteAllowed gates it; internal/immutable
  *     bookkeeping fields are never written back).
  *
  * Reads are redacted per the site's security policy.
@@ -23,9 +23,11 @@ import { resolveBackend } from "../lib/backends/index.js";
 import {
   resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, redactCanonicalEntity,
 } from "../lib/security.js";
-import { readNodeDraftInventory } from "../lib/node-draft-inventory.js";
-import { assertDraftLangcode, readDraftTranslation, readTranslationInventory } from "../lib/draft-write.js";
+import {
+  assertDraftLangcode, readDraftTranslation, readNodeDraftInventory, readTranslationInventory,
+} from "../lib/sentinel-draft.js";
 import { omitLiveComputedMetatag } from "../lib/entity-response.js";
+import { changedAheadOfRevision, prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
 
 // Attributes that describe the entity's identity / revision bookkeeping / paths.
 // These are read-only or server-managed and must NOT be replayed on a revert.
@@ -123,20 +125,6 @@ function summarizeRevision(resource) {
   };
 }
 
-/**
- * Whether the default revision's `changed` is later than its own
- * `revision_timestamp` — the readable fingerprint of a #201 node.
- * @param {?object} summary
- * @returns {boolean}
- */
-function changedAheadOfRevision(summary) {
-  if (!summary?.changed || !summary?.revisionTimestamp) return false;
-  const changed = Date.parse(summary.changed);
-  const rev = Date.parse(summary.revisionTimestamp);
-  if (!Number.isFinite(changed) || !Number.isFinite(rev)) return false;
-  return changed > rev;
-}
-
 const LIST_REVISIONS_BASE_NOTE =
   "JSON:API only addresses revisions by id (id:<vid>) or the rel:latest-version / " +
   "rel:working-copy aliases; it cannot enumerate the full chronological history. " +
@@ -286,10 +274,11 @@ async function getRevision({ site: siteName, type, id, version, langcode }) {
 
 /**
  * Revert an entity to a prior revision (GOVERNED WRITE). Reads the target
- * revision, then replays its editable attributes through updateEntity so they
- * become the new current revision. Internal/immutable bookkeeping fields
- * (drupal_internal__*, revision metadata, computed path, timestamps) are
- * stripped before the write so only restorable content is sent.
+ * revision, then replays its editable attributes through prepareGuardedPatch
+ * / updateEntityGuarded so they become the new current revision. Internal /
+ * immutable bookkeeping fields (drupal_internal__*, revision metadata,
+ * computed path, timestamps) are stripped before the write so only
+ * restorable content is sent.
  *
  * This does not delete any history — the revert produces a NEW revision whose
  * content matches the target, preserving the audit trail.
@@ -328,7 +317,19 @@ async function revertRevision({ site: siteName, type, id, version }) {
     )
   );
 
-  await backend.updateEntity({ entityType: "node", bundle: type, id, attributes });
+  let existing = null;
+  try {
+    existing = (await backend.getEntity({ entityType: "node", bundle: type, id })) ?? null;
+  } catch {
+    existing = null;
+  }
+  const patchTarget = await prepareGuardedPatch(backend, {
+    entityType: "node", bundle: type, id, existing, attributes,
+  });
+  await updateEntityGuarded(backend, {
+    entityType: "node", bundle: type, id, attributes,
+    ...(patchTarget.draftRevision ? { draftRevision: patchTarget.draftRevision } : {}),
+  });
 
   return {
     success: true,

package/src/tools/structure.js

@@ -19,7 +19,7 @@ import { resolveBackend } from "../lib/backends/index.js";
 import {
   resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, redactCanonicalEntity,
 } from "../lib/security.js";
-import { assertDraftLangcode } from "../lib/draft-write.js";
+import { assertDraftLangcode } from "../lib/sentinel-draft.js";
 
 const MENU_LINK_TYPE = "menu_link_content";
 const BLOCK_TYPE = "block_content";

package/src/tools/taxonomy.js

@@ -12,7 +12,7 @@ import {
   resolveSecurityConfig, redactCanonicalEntity,
   assertReadAllowed, assertWriteAllowed, assertDeleteAllowed,
 } from "../lib/security.js";
-import { assertDraftLangcode } from "../lib/draft-write.js";
+import { assertDraftLangcode } from "../lib/sentinel-draft.js";
 
 // ---------------------------------------------------------------------------
 // Implementations