drupal-mcp-connector 2.7.0 → 2.7.2

package/src/tools/paragraphs.js

@@ -9,17 +9,24 @@
  * focused way to mint a paragraph and fetch it back, plus the relationship data
  * needed to embed it into a host field.
  *
- * Embedding model — IMPORTANT:
- *   - Over JSON:API (this connector's default backend) a host references a
- *     paragraph from its ERR field by a resource identifier object
- *     `{ type: "paragraph--<bundle>", id: "<paragraph-uuid>" }`. Drupal resolves
- *     the correct target_id + target_revision_id server-side from the UUID. Drop
- *     `relationshipData` (returned by drupal_create_paragraph) into the host's
- *     relationships map and call drupal_entity_update / drupal_update_node.
+ * Embedding model — IMPORTANT (#192):
+ *   - Over JSON:API a host references a paragraph from its ERR field by a
+ *     resource identifier `{ type: "paragraph--<bundle>", id, meta: {
+ *     target_revision_id } }`. Drupal's ERR item is empty unless both
+ *     `target_id` and `target_revision_id` are set; JSON:API only receives the
+ *     revision id from `meta.target_revision_id`. `{ type, id }` alone persists
+ *     an empty field — it is not a no-op, and it is worse than omitting the
+ *     field (which would inherit the previous revision's refs).
+ *   - `relationshipData` from these tools includes that meta key. Host writes
+ *     (`drupal_entity_update` / `drupal_update_node` / bulk update) also resolve
+ *     a missing vid before PATCH and fail the whole write if they cannot.
  *   - The classic entity-API pair `{ target_id, target_revision_id }` (integer
- *     ids) is the REST/Form-API shape, not the JSON:API shape. Those numeric ids
- *     are not surfaced by the canonical entity here; prefer the UUID relationship
- *     form above when writing through this connector.
+ *     ids) is the REST/Form-API shape, not the JSON:API shape.
+ *   - Creating paragraphs and then attaching them is two calls. A content-tier
+ *     agent cannot delete orphans if the host PATCH is then rejected (#201).
+ *     Probe the host first: `drupal_list_revisions` (`possiblyPatchBlocked`)
+ *     and `dryRun` on the host update. Preflight inside `update_node` does not
+ *     un-orphan work that already happened.
  *
  * Both tools are governed: writes assert create permission for the `paragraph`
  * entity type + bundle, reads assert read permission and are redacted per the
@@ -32,33 +39,35 @@ import { resolveBackend } from "../lib/backends/index.js";
 import {
   resolveSecurityConfig, assertWriteAllowed, assertReadAllowed, redactCanonicalEntity,
 } from "../lib/security.js";
-
-/**
- * Build the JSON:API resource type string for a paragraph bundle.
- * @param {string} bundle Paragraph type machine name.
- * @returns {string} e.g. "paragraph--text".
- */
-function resourceType(bundle) {
-  return `paragraph--${bundle}`;
-}
+import {
+  embedParagraphRef, paragraphRevisionId, resolveParagraphRevisionId, missingParagraphRevisionError,
+} from "../lib/err-relationships.js";
 
 /**
  * Build the resource-identifier ref used to embed a paragraph in a host ERR /
- * paragraph reference field over JSON:API.
+ * paragraph reference field over JSON:API. Includes `meta.target_revision_id`
+ * when a vid is known (#192).
  * @param {string} bundle Paragraph type machine name.
  * @param {string} id Paragraph UUID.
- * @returns {{type: string, id: string}}
+ * @param {number|string|null|undefined} [revisionId] Current revision id.
+ * @returns {{type: string, id: string, meta?: {target_revision_id: number}}}
  */
-function embedRef(bundle, id) {
-  return { type: resourceType(bundle), id };
+export function embedRef(bundle, id, revisionId) {
+  return embedParagraphRef(bundle, id, revisionId);
 }
 
 const EMBED_NOTE =
   "Paragraphs are not standalone content: embed this paragraph in a host entity's " +
-  "Entity Reference Revisions (paragraph) field. Over JSON:API, add `relationshipData` " +
-  "to the host field's relationship (e.g. drupal_entity_update / drupal_update_node with " +
-  "relationships: { field_paragraphs: { data: [ relationshipData ] } }). Drupal resolves " +
-  "target_id + target_revision_id from the UUID server-side.";
+  "Entity Reference Revisions (paragraph) field. Over JSON:API the resource identifier " +
+  "MUST include meta.target_revision_id — Drupal's ERR item is empty unless both " +
+  "target_id and target_revision_id are set, and JSON:API only receives the revision " +
+  "id from that meta key. relationshipData from this tool includes it. " +
+  "drupal_entity_update / drupal_update_node also resolve a missing vid before PATCH " +
+  "and fail the write if they cannot. An empty array is an explicit clear. " +
+  "Before creating paragraphs to attach to a published moderated node, call " +
+  "drupal_list_revisions (inspect possiblyPatchBlocked) and dryRun the host update — " +
+  "the host write is rejected after dependents exist, and content-tier cannot delete " +
+  "the orphans (#201).";
 
 /**
  * Create a paragraph entity of the given type and return a ref suitable for
@@ -68,10 +77,11 @@ const EMBED_NOTE =
  *   `attributes` are paragraph field values keyed by Drupal machine name
  *   (e.g. { field_body: { value, format } }). Use drupal_get_entity_schema for
  *   entityType "paragraph" + the bundle to discover available fields.
- * @returns {Promise<{paragraph: object, ref: {id: string, type: string},
- *   relationshipData: {type: string, id: string}, note: string}>}
- *   The created paragraph descriptor plus the embedding ref/relationship data.
+ * @returns {Promise<{paragraph: object, ref: object, relationshipData: object, note: string}>}
+ *   The created paragraph descriptor plus the embedding ref/relationship data
+ *   (including `meta.target_revision_id`).
  * @throws {SecurityError} If creating paragraphs of this bundle is not permitted.
+ * @throws {Error} If the created paragraph has no readable revision id.
  */
 async function createParagraph({ site: siteName, paragraphType, attributes = {} }) {
   const site = getSiteConfig(siteName);
@@ -80,7 +90,9 @@ async function createParagraph({ site: siteName, paragraphType, attributes = {}
   const backend = await resolveBackend(site);
   const paragraph = await backend.createEntity({ entityType: "paragraph", bundle: paragraphType, attributes });
   const bundle = paragraph.bundle || paragraphType;
-  const ref = embedRef(bundle, paragraph.id);
+  const revisionId = await resolveParagraphRevisionId(backend, paragraph, paragraphType);
+  if (revisionId === null) throw missingParagraphRevisionError(paragraph.id);
+  const ref = embedRef(bundle, paragraph.id, revisionId);
   return { paragraph, ref, relationshipData: ref, note: EMBED_NOTE };
 }
 
@@ -94,10 +106,9 @@ async function createParagraph({ site: siteName, paragraphType, attributes = {}
  * @param {object} args - { site?, paragraphType, id, attributes? }.
  *   `attributes` are the paragraph field values to change, keyed by Drupal
  *   machine name (e.g. { field_body: { value, format } }).
- * @returns {Promise<{paragraph: object, ref: {id: string, type: string},
- *   relationshipData: {type: string, id: string}, note: string}>}
- *   The updated paragraph plus the (unchanged) embedding ref.
- * @throws {Error} If id is missing.
+ * @returns {Promise<{paragraph: object, ref: object, relationshipData: object, note: string}>}
+ *   The updated paragraph plus the embedding ref (with current revision id).
+ * @throws {Error} If id is missing or the revision id cannot be read.
  * @throws {SecurityError} If updating paragraphs of this bundle is not permitted.
  */
 async function updateParagraph({ site: siteName, paragraphType, id, attributes = {} }) {
@@ -108,16 +119,18 @@ async function updateParagraph({ site: siteName, paragraphType, id, attributes =
   const backend = await resolveBackend(site);
   const paragraph = await backend.updateEntity({ entityType: "paragraph", bundle: paragraphType, id, attributes });
   const bundle = paragraph.bundle || paragraphType;
-  const ref = embedRef(bundle, paragraph.id);
+  const revisionId = await resolveParagraphRevisionId(backend, paragraph, paragraphType);
+  if (revisionId === null) throw missingParagraphRevisionError(id, "Updated");
+  const ref = embedRef(bundle, paragraph.id, revisionId);
   return { paragraph, ref, relationshipData: ref, note: EMBED_NOTE };
 }
 
 /**
  * Fetch a single paragraph by bundle + UUID, redacted per the site policy, and
- * annotate it with the embedding ref.
+ * annotate it with the embedding ref (including `meta.target_revision_id`).
  *
  * @param {object} args - { site?, paragraphType, id }.
- * @returns {Promise<(object & {ref: {id: string, type: string}})|null>}
+ * @returns {Promise<(object & {ref: object})|null>}
  *   The redacted paragraph with an embedding `ref`, or null if not found.
  * @throws {SecurityError} If reading paragraphs of this bundle is not permitted.
  */
@@ -129,7 +142,8 @@ async function getParagraph({ site: siteName, paragraphType, id }) {
   const entity = await backend.getEntity({ entityType: "paragraph", bundle: paragraphType, id });
   if (!entity) return null;
   const redacted = redactCanonicalEntity(entity, sec, "paragraph");
-  return { ...redacted, ref: embedRef(redacted.bundle || paragraphType, redacted.id) };
+  const revisionId = paragraphRevisionId(entity) ?? paragraphRevisionId(redacted);
+  return { ...redacted, ref: embedRef(redacted.bundle || paragraphType, redacted.id, revisionId) };
 }
 
 // ---------------------------------------------------------------------------
@@ -140,7 +154,7 @@ export const definitions = [
   {
     name: "drupal_create_paragraph",
     description:
-      "Create a Paragraph entity of a given paragraph type (bundle). Paragraphs are content fragments that are NOT standalone — they must be referenced by a host entity's paragraph / Entity Reference Revisions field. Returns the created paragraph plus `relationshipData` ({ type: 'paragraph--<bundle>', id: <uuid> }) to drop into a host field's relationships via drupal_entity_update / drupal_update_node. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) first to discover fields. Governed by the site security policy.",
+      "Create a Paragraph entity of a given paragraph type (bundle). Paragraphs are content fragments that are NOT standalone — they must be referenced by a host entity's paragraph / Entity Reference Revisions field. Returns the created paragraph plus `relationshipData` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) to drop into a host field's relationships via drupal_entity_update / drupal_update_node. Drupal ERR items are empty without that meta key — do not send {type, id} alone. Before creating paragraphs to attach to a published moderated node, call drupal_list_revisions (possiblyPatchBlocked) and dryRun the host update so a doomed PATCH does not orphan them. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) first to discover fields. Governed by the site security policy.",
     inputSchema: {
       type: "object", required: ["paragraphType"],
       properties: {
@@ -153,7 +167,7 @@ export const definitions = [
   {
     name: "drupal_update_paragraph",
     description:
-      "Update an existing Paragraph entity's field values by paragraph type (bundle) and UUID. Only the attributes you pass are changed (partial update); the host entity's reference to this paragraph is unchanged (same UUID), so this maintains a component paragraph in place without re-embedding. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) to discover fields. Governed by the site security policy.",
+      "Update an existing Paragraph entity's field values by paragraph type (bundle) and UUID. Only the attributes you pass are changed (partial update); the host entity's reference to the paragraph is unchanged (same UUID), so this maintains a component paragraph in place without re-embedding. Returns relationshipData including meta.target_revision_id for a later host attach. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) to discover fields. Governed by the site security policy.",
     inputSchema: {
       type: "object", required: ["paragraphType", "id"],
       properties: {
@@ -167,7 +181,7 @@ export const definitions = [
   {
     name: "drupal_get_paragraph",
     description:
-      "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph plus a `ref` ({ type: 'paragraph--<bundle>', id }) you can use to embed it in a host entity's paragraph / ERR field. Note: paragraphs are referenced (by target_id + target_revision_id in the entity API, or by UUID over JSON:API) from a host field rather than queried standalone in production. Governed by the site security policy.",
+      "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy.",
     inputSchema: {
       type: "object", required: ["paragraphType", "id"],
       properties: {

package/src/tools/reports-extra.js

@@ -12,9 +12,49 @@
 
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
-import { resolveSecurityConfig, assertReadAllowed } from "../lib/security.js";
+import { resolveSecurityConfig, assertReadAllowed, assertEntityTypeAllowed } from "../lib/security.js";
 import { collectEntities, fieldValue } from "../lib/reports-support.js";
 
+/** Author base fields that only ever point at `user`. */
+const AUTHOR_BASE_FIELDS = new Set(["uid", "revision_uid"]);
+
+const POLICY_DENIED_REASON = "target entity type denied by policy";
+const ACCESS_DENIED_REASON = "target access denied";
+const UNVERIFIED_REASON = "target could not be verified";
+
+/**
+ * Whether connector policy forbids reading this entity type.
+ * @param {object} sec Resolved security config.
+ * @param {string} entityType Entity type machine name.
+ * @returns {boolean}
+ */
+function isEntityTypeDenied(sec, entityType) {
+  if (!entityType) return false;
+  try {
+    assertEntityTypeAllowed(sec, entityType);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Classify a getEntity failure. Only a 404 (or an unaddressable ref) is an
+ * orphan. Connector policy, Drupal 401/403, and other failures are
+ * unverifiable — and must not share one reason.
+ * @param {unknown} err
+ * @returns {"missing"|"forbidden"|"failed"}
+ */
+function classifyTargetError(err) {
+  const msg = String(err?.message || err || "");
+  const statusMatch = msg.match(/\bDrupal (\d{3})\b/i);
+  const status = statusMatch ? Number(statusMatch[1]) : NaN;
+  if (status === 404) return "missing";
+  if (status === 401 || status === 403) return "forbidden";
+  if (/\b404\b/.test(msg) && !/\b40[13]\b/.test(msg)) return "missing";
+  return "failed";
+}
+
 /**
  * Determine whether a canonical field/relationship value counts as "empty".
  * Handles scalars, JSON:API value-objects ({value}), arrays, and relationship
@@ -161,9 +201,9 @@ async function missingField({ site: siteName, type, field, sampleSize = 100 }) {
 /**
  * Orphaned entity references: sampled entities whose entity-reference fields
  * point at targets that no longer exist. Best-effort — each distinct referenced
- * target is probed once via getEntity; a null result or a fetch error is treated
- * as an unresolved (orphaned) target. Sampling-bounded, so `approximate` is set
- * when the entity scan is capped.
+ * target is probed once via getEntity. Only a 404 / unaddressable ref is an
+ * orphan; 401/403 and connector policy denials are unverifiable (#205).
+ * Sampling-bounded, so `approximate` is set when the entity scan is capped.
  *
  * @param {object} args - { site?, type?, sampleSize? }. `type` defaults to "article".
  * @returns {Promise<object>} Orphaned-reference findings plus scan metadata.
@@ -181,40 +221,56 @@ async function orphanedReferences({ site: siteName, type, sampleSize = 50 }) {
     sampleSize
   );
 
+  const userDenied = isEntityTypeDenied(sec, "user");
+
   // Cache resolution results across all sampled entities so a target is only
   // looked up once (de-dupes both within and across entities).
-  const resolution = new Map(); // id -> boolean (true = exists)
+  const resolution = new Map(); // id -> "ok" | "missing" | "denied" | "forbidden" | "failed"
   /**
-   * Resolve whether a referenced target exists, caching the result.
+   * Resolve a referenced target, caching the classification.
    * @param {{id: string, entityType: ?string, bundle: ?string}} ref Reference to probe.
-   * @returns {Promise<boolean>} True if the target resolves to an entity.
+   * @param {string} fieldName Host field that holds the ref.
+   * @returns {Promise<"ok"|"missing"|"denied"|"forbidden"|"failed">}
    */
-  async function exists(ref) {
+  async function classifyRef(ref, fieldName) {
     if (resolution.has(ref.id)) return resolution.get(ref.id);
-    let ok = false;
+
+    const typeDenied = isEntityTypeDenied(sec, ref.entityType)
+      || (AUTHOR_BASE_FIELDS.has(fieldName) && userDenied);
+    if (typeDenied) {
+      resolution.set(ref.id, "denied");
+      return "denied";
+    }
+
+    if (!ref.entityType || !ref.bundle) {
+      resolution.set(ref.id, "missing");
+      return "missing";
+    }
+
     try {
-      // entityType/bundle are derived from JSON:API "type"; both required to fetch.
-      if (ref.entityType && ref.bundle) {
-        const target = await backend.getEntity({ entityType: ref.entityType, bundle: ref.bundle, id: ref.id });
-        ok = Boolean(target);
-      } else {
-        // Cannot address the target without a concrete type+bundle; treat as
-        // unresolved rather than silently passing.
-        ok = false;
-      }
-    } catch {
-      ok = false;
+      const target = await backend.getEntity({
+        entityType: ref.entityType, bundle: ref.bundle, id: ref.id,
+      });
+      const state = target ? "ok" : "missing";
+      resolution.set(ref.id, state);
+      return state;
+    } catch (err) {
+      const state = classifyTargetError(err);
+      resolution.set(ref.id, state);
+      return state;
     }
-    resolution.set(ref.id, ok);
-    return ok;
   }
 
   const findings = [];
+  let unverifiable = 0;
+  let deniedByPolicy = 0;
+  let accessDenied = 0;
   for (const e of entities) {
     for (const [fieldName, rel] of Object.entries(e.relationships ?? {})) {
       for (const ref of refsOf(rel)) {
-        const ok = await exists(ref);
-        if (!ok) {
+        const state = await classifyRef(ref, fieldName);
+        if (state === "ok") continue;
+        if (state === "missing") {
           findings.push({
             id: e.id,
             title: e.title,
@@ -223,21 +279,34 @@ async function orphanedReferences({ site: siteName, type, sampleSize = 50 }) {
             targetEntityType: ref.entityType,
             targetBundle: ref.bundle,
           });
+          continue;
         }
+        unverifiable += 1;
+        if (state === "denied") deniedByPolicy += 1;
+        if (state === "forbidden") accessDenied += 1;
       }
     }
   }
 
   const approximate = entities.length >= sampleSize;
+  const orphaned = findings.length;
+  let reason;
+  if (deniedByPolicy > 0) reason = POLICY_DENIED_REASON;
+  else if (accessDenied > 0) reason = ACCESS_DENIED_REASON;
+  else if (unverifiable > 0) reason = UNVERIFIED_REASON;
   return {
     contentType,
     scanned: entities.length,
     sampleSize,
     approximate,
-    totalOrphaned: findings.length,
+    orphaned,
+    unverifiable,
+    totalOrphaned: orphaned,
+    reason,
     note: approximate
       ? "Best-effort: reference integrity is checked over a sampling-bounded set of entities."
-      : "Best-effort: each referenced target is probed once via JSON:API.",
+      : "Best-effort: each referenced target is probed once via JSON:API. "
+        + "401/403 and policy-denied types are unverifiable, not orphans.",
     findings,
   };
 }
@@ -274,7 +343,7 @@ export const definitions = [
   },
   {
     name: "drupal_report_orphaned_references",
-    description: "Find entities whose entity-reference fields point at targets that no longer exist (orphaned references). Best-effort: samples entities and probes each distinct referenced target via JSON:API. Flags 'approximate' when sampling-bounded.",
+    description: "Find entities whose entity-reference fields point at targets that no longer exist (orphaned references). Best-effort: samples entities and probes each distinct referenced target via JSON:API. A 404 (or unaddressable ref) is an orphan; 401/403 and connector policy denials are counted as unverifiable, not missing. uid/revision_uid are skipped when the policy denies user. Flags 'approximate' when sampling-bounded.",
     inputSchema: {
       type: "object",
       properties: {

package/src/tools/revisions.js

@@ -112,6 +112,7 @@ function summarizeRevision(resource) {
   return {
     vid: attrs.get("drupal_internal__vid") ?? null,
     revisionTimestamp: attrs.get("revision_timestamp") ?? null,
+    changed: attrs.get("changed") ?? null,
     revisionLog: attrs.get("revision_log") ?? attrs.get("revision_log_message") ?? null,
     status: attrs.get("status") ?? null,
     title: attrs.get("title") ?? null,
@@ -119,6 +120,39 @@ 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. " +
+  "Use drupal_get_revision with a specific vid to inspect a known revision, or the " +
+  "Drush bridge for complete revision-history enumeration. " +
+  "drupal_report_revision_hotspots can surface per-node revision counts.";
+
+const LIST_REVISIONS_NULL_WC_NOTE =
+  " workingCopy: null is not proof the node is PATCH-able. Drupal core rejects " +
+  "PATCH when the stored entity is not the latest revision even when " +
+  "content_moderation exposes no pending revision (connector #201, core #2795279). " +
+  "Inspect possiblyPatchBlocked before creating dependent paragraphs; dryRun on " +
+  "the host update runs the same guard.";
+
+const LIST_REVISIONS_FINGERPRINT_NOTE =
+  " The default revision's changed timestamp is later than its own " +
+  "revision_timestamp — a readable fingerprint that a newer revision row may " +
+  "exist without a content_moderation working copy.";
+
 /**
  * List the addressable revisions of an entity: the latest default revision and
  * the working-copy (forward) revision. Full chronological enumeration is not
@@ -145,19 +179,20 @@ async function listRevisions({ site: siteName, type, id }) {
     .then(summarizeRevision)
     .catch(() => null);
 
+  const possiblyPatchBlocked = Boolean(latestVersion && changedAheadOfRevision(latestVersion));
+  let note = LIST_REVISIONS_BASE_NOTE;
+  if (!workingCopy) note += LIST_REVISIONS_NULL_WC_NOTE;
+  if (possiblyPatchBlocked) note += LIST_REVISIONS_FINGERPRINT_NOTE;
+
   return {
     entityType: "node",
     bundle: type,
     id,
     latestVersion,
     workingCopy,
+    possiblyPatchBlocked,
     fullHistoryAvailable: false,
-    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. " +
-      "Use drupal_get_revision with a specific vid to inspect a known revision, or the " +
-      "Drush bridge for complete revision-history enumeration. " +
-      "drupal_report_revision_hotspots can surface per-node revision counts.",
+    note,
   };
 }
 
@@ -266,7 +301,7 @@ export const definitions = [
   {
     name: "drupal_list_revisions",
     description:
-      "Surface the addressable revisions of a content node: the latest default revision and the working-copy (forward) revision, with their version ids and links. NOTE: JSON:API cannot enumerate full chronological revision history — it only addresses revisions by id or the latest/working-copy aliases. Full history enumeration requires the Drush bridge. Use drupal_report_revision_hotspots for per-node revision counts.",
+      "Surface the addressable revisions of a content node: the latest default revision and the working-copy (forward) revision, with their version ids and links. workingCopy: null is not an all-clear — Drupal core can still reject PATCH when a revision row sits above the default without a content_moderation working copy (#201). The payload includes possiblyPatchBlocked (true when default changed is later than its revision_timestamp) plus changed and revisionTimestamp on latestVersion. Probe the host (this flag, then dryRun on the update) before creating dependent paragraphs. NOTE: JSON:API cannot enumerate full chronological revision history. Full history enumeration requires the Drush bridge.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {

package/src/tools/site.js

@@ -61,14 +61,6 @@ async function listConfiguredSites() {
   return visibleSiteTargets(getRequestIdentity(), resolvable, names);
 }
 
-/**
- * Per-site source-governance condition (#176). The one governed-path
- * diagnostic that stays callable while governance is failing, so an operator
- * can see WHICH required condition failed. Never includes credentials.
- *
- * @param {object} args - { site? } (a named site narrows the report).
- * @returns {Promise<{sites: object[]}>} required/ok/reason per site.
- */
 /**
  * Classify a getSiteConfig failure so the diagnostic reason matches the cause.
  * @param {string} message
@@ -81,6 +73,14 @@ export function classifySiteResolutionFailure(message) {
   return "site_unresolved";
 }
 
+/**
+ * Per-site source-governance condition (#176, #208). Stays callable while
+ * governed paths are denied. Always probes the source readiness endpoint
+ * for resolved sites; never reports ok:true without that check.
+ *
+ * @param {object} [args] - { site? } (a named site narrows the report).
+ * @returns {Promise<{sites: object[]}>} required/checked/ok/reason per site.
+ */
 async function getGovernanceStatus({ site: siteName } = {}) {
   const identity = getRequestIdentity();
   const configured = listSiteNames();
@@ -96,10 +96,10 @@ async function getGovernanceStatus({ site: siteName } = {}) {
       unresolved.push({
         site: name,
         required: null,
+        checked: false,
         ok: false,
         reason: classifySiteResolutionFailure(detail),
         detail,
-        checkedAt: null,
       });
     }
   }
@@ -129,7 +129,7 @@ export const definitions = [
   },
   {
     name: "drupal_governance_status",
-    description: "Report each configured site's source-governance condition: whether governance is required, whether the source contract verifies, and the failed condition when it does not. Callable even while governed paths are denied — this is the diagnostic for that denial.",
+    description: "Report each configured site's source-governance condition. Always probes GET /drupal-mcp/readiness (even when this client does not require governance) and surfaces the server's reason verbatim. Never reports ok:true unless that check ran. Callable even while governed paths are denied — this is the diagnostic for that denial.",
     inputSchema: {
       type: "object",
       properties: { site: { type: "string" } },