drupal-mcp-connector 2.7.0 → 2.7.1

package/src/lib/patch-preflight.js

@@ -0,0 +1,176 @@
+/**
+ * JSON:API PATCH preflight for Drupal core's working-copy guard (#201).
+ *
+ * `EntityResource::patchIndividual()` rejects a canonical PATCH when the
+ * stored entity is not both the latest and the default revision. That check
+ * runs against the revision table *before* the payload is deserialized.
+ * An empty-body PATCH that returns 2xx still calls `$entity->save()` (and
+ * often `setNewRevision`) — so the probe must fail *after* the guard and
+ * *before* save. Core next compares `data.id` to the URL entity UUID; a
+ * well-formed but non-matching id yields 400 "does not match the ID in the
+ * payload" with no row written. Content-moderation's `rel:latest-version` /
+ * `rel:working-copy` aliases can disagree with storage (a revision row with
+ * no `content_moderation_state`), which is how every read tool reports
+ * clean and the write then 400s.
+ *
+ * `workingCopy: null` and "latest-version vid === default vid" are not proof
+ * the node is writable. That is the #201 lie.
+ *
+ * Distinct from #166: there a working copy is visible and the fix is PATCH
+ * `?resourceVersion=rel:working-copy`. This module does not implement that.
+ */
+
+import { entityLooksModerated, hasExplicitModerationState } from "./moderation-default.js";
+
+/** Stable error code for a core working-copy / not-latest-revision block. */
+export const PATCH_BLOCKED_CODE = "PATCH_BLOCKED";
+
+const WORKING_COPY_PATCH_RE = /has a working copy is not yet supported/i;
+
+/**
+ * Actionable replacement for core's "has a working copy" 400.
+ * Clearing the blocking row is revision surgery outside JSON:API.
+ */
+export const PATCH_BLOCKED_MESSAGE =
+  "This entity cannot be updated over JSON:API because the stored entity is not " +
+  "the latest revision (Drupal core #2795279). The JSON:API aliases " +
+  "rel:latest-version and rel:working-copy cannot show the blocking row. " +
+  "Clearing it requires revision surgery outside JSON:API (Drush / the entity API). " +
+  "See connector #201. Do not retry the same canonical PATCH.";
+
+/**
+ * Thrown when the core working-copy PATCH guard rejects a write (or its probe).
+ */
+export class PatchBlockedError extends Error {
+  /** @param {?Error} [cause] The original Drupal 400. */
+  constructor(cause) {
+    super(PATCH_BLOCKED_MESSAGE);
+    this.name = "PatchBlockedError";
+    this.code = PATCH_BLOCKED_CODE;
+    if (cause) this.cause = cause;
+  }
+}
+
+/**
+ * Whether an error is Drupal core's working-copy PATCH guard (core #2795279).
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isWorkingCopyPatchError(err) {
+  return WORKING_COPY_PATCH_RE.test(String(err?.message || ""));
+}
+
+/**
+ * Rewrite a core working-copy 400 into {@link PatchBlockedError}; otherwise
+ * return the original value.
+ * @param {unknown} err
+ * @returns {unknown}
+ */
+export function rewriteWorkingCopyPatchError(err) {
+  if (!isWorkingCopyPatchError(err)) return err;
+  return new PatchBlockedError(err instanceof Error ? err : new Error(String(err)));
+}
+
+/**
+ * Whether this update should run the PATCH probe.
+ * Skip unmoderated / non-revisionable bundles — the guard is about
+ * revisionable entities under content_moderation.
+ * @param {{existing?: ?object, attributes?: object}} input
+ * @returns {boolean}
+ */
+export function shouldPreflightPatch({ existing, attributes } = {}) {
+  if (hasExplicitModerationState(attributes)) return true;
+  return entityLooksModerated(existing);
+}
+
+/**
+ * UUID used as `data.id` on the probe PATCH so it cannot match the URL
+ * entity. Core throws after the working-copy guard and before save.
+ * @see EntityResource::patchIndividual()
+ */
+export const PATCH_PROBE_MISMATCH_ID = "00000000-0000-4000-a000-000000000001";
+
+const ID_MISMATCH_RE = /does not match the ID in the payload/i;
+
+/**
+ * Whether a probe error means the working-copy guard passed and no row
+ * was written (id mismatch, or a 422 during deserialize).
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isProbePassedWithoutSave(err) {
+  const msg = String(err?.message || "");
+  return ID_MISMATCH_RE.test(msg) || /Drupal 422\b/.test(msg);
+}
+
+/**
+ * Probe the same guard core uses on the canonical PATCH URL.
+ *
+ * Sends a PATCH whose `data.id` does not match the URL entity. Core runs
+ * the working-copy check first; a match on that phrase means no row was
+ * written. An id-mismatch 400 (or deserialize 422) means the guard passed
+ * and save was not reached. A 2xx would have saved a revision and is
+ * treated as a probe failure. Do not treat "latest-version vid === default
+ * vid" as writable.
+ *
+ * @param {object} args
+ * @param {object} args.backend Backend with `rawQuery` + `resourcePath`.
+ * @param {string} args.entityType
+ * @param {string} args.bundle
+ * @param {string} args.id
+ * @param {?object} [args.existing]
+ * @param {object} [args.attributes]
+ * @returns {Promise<{probed: boolean, writable?: boolean|string, skipped?: string}>}
+ * @throws {PatchBlockedError} When the guard rejects the probe.
+ */
+export async function preflightPatchWritable({
+  backend, entityType, bundle, id, existing, attributes,
+}) {
+  if (!shouldPreflightPatch({ existing, attributes })) {
+    return { probed: false };
+  }
+  if (typeof backend?.rawQuery !== "function" || typeof backend?.resourcePath !== "function") {
+    return { probed: false, skipped: "backend cannot issue a raw PATCH probe" };
+  }
+  const path = `${backend.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`;
+  const type = `${entityType}--${bundle}`;
+  const probeId = id === PATCH_PROBE_MISMATCH_ID
+    ? "00000000-0000-4000-a000-000000000002"
+    : PATCH_PROBE_MISMATCH_ID;
+  try {
+    await backend.rawQuery({
+      path,
+      options: {
+        method: "PATCH",
+        body: JSON.stringify({ data: { type, id: probeId } }),
+      },
+    });
+    throw new Error(
+      "PATCH probe unexpectedly succeeded (2xx). The probe must fail after " +
+      "core's working-copy guard so no revision is written."
+    );
+  } catch (err) {
+    if (isWorkingCopyPatchError(err)) {
+      throw new PatchBlockedError(err instanceof Error ? err : new Error(String(err)));
+    }
+    if (isProbePassedWithoutSave(err)) {
+      return { probed: true, writable: true };
+    }
+    throw err;
+  }
+}
+
+/**
+ * `backend.updateEntity` with the core working-copy 400 rewritten.
+ * @param {object} backend
+ * @param {object} input updateEntity argument.
+ * @returns {Promise<*>}
+ * @throws {PatchBlockedError|*}
+ */
+export async function updateEntityGuarded(backend, input) {
+  try {
+    return await backend.updateEntity(input);
+  } catch (err) {
+    throw rewriteWorkingCopyPatchError(err);
+  }
+}

package/src/lib/write-revision.js

@@ -0,0 +1,72 @@
+/**
+ * Choose which entity body represents a write (#169).
+ *
+ * When relationships were sent, the canonical/default revision is the
+ * published node — after a draft ERR attach it still shows the *old* refs.
+ * Prefer `rel:working-copy`. If that alias is not addressable, return the
+ * PATCH body (or the canonical re-read) plus `_revision.relationshipsUnverified`.
+ */
+
+/**
+ * @param {object} args
+ * @param {object} args.backend
+ * @param {string} args.entityType
+ * @param {string} args.bundle
+ * @param {string} args.id
+ * @param {boolean} args.relationshipsSent
+ * @param {?object} [args.patchResult] Canonicalised PATCH response body.
+ * @param {boolean} [args.preferCanonical] When no relationships were sent,
+ *   re-GET the canonical resource (nodes do this for the persisted alias).
+ * @returns {Promise<object>} Entity to return, with `_revision` when relevant.
+ */
+export async function readWrittenRevision({
+  backend, entityType, bundle, id, relationshipsSent, patchResult = null, preferCanonical = false,
+}) {
+  if (!relationshipsSent) {
+    if (preferCanonical && typeof backend.getEntity === "function") {
+      const fresh = await backend.getEntity({ entityType, bundle, id }).catch(() => null);
+      return fresh ?? patchResult ?? { id };
+    }
+    return patchResult ?? { id };
+  }
+
+  // Content-moderation working-copy aliases are a node (host) feature. Other
+  // entity types keep the PATCH body and an unverified marker.
+  let workingCopy = null;
+  if (entityType === "node" && typeof backend.getEntity === "function") {
+    try {
+      workingCopy = await backend.getEntity({
+        entityType, bundle, id, resourceVersion: "rel:working-copy",
+      });
+    } catch {
+      workingCopy = null;
+    }
+  }
+  if (workingCopy) {
+    return {
+      ...workingCopy,
+      _revision: {
+        source: "working-copy",
+        note:
+          "Returned from rel:working-copy — the revision that was written, not the " +
+          "published default. Canonical re-reads hide a draft ERR attach (#169).",
+      },
+    };
+  }
+
+  let fallback = patchResult;
+  if (!fallback && preferCanonical && typeof backend.getEntity === "function") {
+    fallback = await backend.getEntity({ entityType, bundle, id }).catch(() => null);
+  }
+  return {
+    ...(fallback ?? { id }),
+    _revision: {
+      source: patchResult ? "patch" : "canonical",
+      relationshipsUnverified: true,
+      note:
+        "Relationships were sent on this write. The body below is not the written " +
+        "revision (no addressable working copy). It is not proof an ERR field landed. " +
+        "Inspect rel:working-copy with drupal_get_revision, or treat the field as unverified (#169).",
+    },
+  };
+}

package/src/tools/bulk.js

@@ -14,7 +14,12 @@
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
 import { resolveSecurityConfig, assertWriteAllowed, assertPublishAllowed } from "../lib/security.js";
-import { applySafeDraftDefault } from "../lib/moderation-default.js";
+import { applySafeDraftDefault, hasExplicitModerationState } from "../lib/moderation-default.js";
+import {
+  resolveErrRelationships, embedParagraphRef,
+  resolveParagraphRevisionId, missingParagraphRevisionError,
+} from "../lib/err-relationships.js";
+import { preflightPatchWritable, updateEntityGuarded } from "../lib/patch-preflight.js";
 
 /**
  * Normalize an unknown thrown value into a human-readable message.
@@ -48,13 +53,20 @@ async function bulkCreate({ site: siteName, entityType, bundle, items = [] }) {
     const item = rawItem || {};
     try {
       assertPublishAllowed(sec, item.attributes ?? {});
+      const resolvedRelationships = await resolveErrRelationships(backend, item.relationships ?? {});
       const entity = await backend.createEntity({
         entityType, bundle,
         attributes: item.attributes ?? {},
-        relationships: item.relationships ?? {},
+        relationships: resolvedRelationships,
       });
       created += 1;
-      results.push({ index, success: true, id: entity?.id });
+      const row = { index, success: true, id: entity?.id };
+      if (entityType === "paragraph" && entity?.id) {
+        const revisionId = await resolveParagraphRevisionId(backend, entity, bundle);
+        if (revisionId === null) throw missingParagraphRevisionError(entity.id);
+        row.relationshipData = embedParagraphRef(entity.bundle || bundle, entity.id, revisionId);
+      }
+      results.push(row);
     } catch (err) {
       failed += 1;
       results.push({ index, success: false, error: errorMessage(err) });
@@ -91,15 +103,28 @@ async function bulkUpdate({ site: siteName, entityType, bundle, items = [] }) {
     const item = rawItem || {};
     try {
       if (!item.id) throw new Error("Missing 'id' for update item");
+      let existing = null;
+      if (!hasExplicitModerationState(item.attributes ?? {})) {
+        try {
+          existing = (await backend.getEntity({ entityType, bundle, id: item.id })) ?? null;
+        } catch {
+          existing = null;
+        }
+      }
       const attributes = await applySafeDraftDefault({
         backend, entityType, bundle, id: item.id,
         attributes: item.attributes ?? {},
+        existingEntity: existing,
       });
       assertPublishAllowed(sec, attributes);
-      const entity = await backend.updateEntity({
+      const resolvedRelationships = await resolveErrRelationships(backend, item.relationships ?? {});
+      await preflightPatchWritable({
+        backend, entityType, bundle, id: item.id, existing, attributes,
+      });
+      const entity = await updateEntityGuarded(backend, {
         entityType, bundle, id: item.id,
         attributes,
-        relationships: item.relationships ?? {},
+        relationships: resolvedRelationships,
       });
       updated += 1;
       results.push({ index, success: true, id: entity?.id ?? item.id });
@@ -123,7 +148,7 @@ const itemAttributesSchema = {
 export const definitions = [
   {
     name: "drupal_bulk_create",
-    description: "Create many entities of a single type + bundle in one call. Permission is checked once; each item is created independently, so the batch continues past individual failures (partial success). Returns per-item { index, success, id | error } and a summary { created, failed }. Writes default to unpublished/draft.",
+    description: "Create many entities of a single type + bundle in one call. Permission is checked once; each item is created independently, so the batch continues past individual failures (partial success). Returns per-item { index, success, id | error } and a summary { created, failed }. Paragraph items also return relationshipData with meta.target_revision_id for a later host attach. Writes default to unpublished/draft.",
     inputSchema: {
       type: "object", required: ["entityType", "bundle", "items"],
       properties: {

package/src/tools/entities.js

@@ -12,6 +12,12 @@ import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
 import { shapeWriteResponse, flagUnrequestedStatusChange, RETURNING_SCHEMA } from "../lib/entity-response.js";
 import { applySafeDraftDefault, hasExplicitModerationState } from "../lib/moderation-default.js";
+import {
+  resolveErrRelationships, relationshipsWereSent, embedParagraphRef,
+  resolveParagraphRevisionId, missingParagraphRevisionError,
+} from "../lib/err-relationships.js";
+import { readWrittenRevision } from "../lib/write-revision.js";
+import { preflightPatchWritable, updateEntityGuarded } from "../lib/patch-preflight.js";
 import {
   resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, assertDeleteAllowed, assertPublishAllowed,
   redactCanonicalEntity, getSecuritySummary,
@@ -63,9 +69,16 @@ async function createEntity({ site: siteName, entityType, bundle, attributes = {
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "create", entityType, bundle);
   assertPublishAllowed(sec, attributes);
-  if (dryRun) return { dryRun: true, operation: "create", entityType, bundle, attributes, relationships };
   const backend = await resolveBackend(site);
-  return shapeWriteResponse(await backend.createEntity({ entityType, bundle, attributes, relationships }), returning);
+  const resolvedRelationships = await resolveErrRelationships(backend, relationships);
+  if (dryRun) return { dryRun: true, operation: "create", entityType, bundle, attributes, relationships: resolvedRelationships };
+  const created = await backend.createEntity({ entityType, bundle, attributes, relationships: resolvedRelationships });
+  if (entityType === "paragraph") {
+    const revisionId = await resolveParagraphRevisionId(backend, created, bundle);
+    if (revisionId === null) throw missingParagraphRevisionError(created.id);
+    created.relationshipData = embedParagraphRef(created.bundle || bundle, created.id, revisionId);
+  }
+  return shapeWriteResponse(created, returning);
 }
 
 /**
@@ -103,9 +116,26 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
     backend, entityType, bundle, id, attributes, existingEntity: existing,
   });
   assertPublishAllowed(sec, safeAttributes);
-  if (dryRun) return { dryRun: true, operation: "update", entityType, bundle, id, attributes: safeAttributes, relationships };
-  const result = await backend.updateEntity({ entityType, bundle, id, attributes: safeAttributes, relationships });
-  return shapeWriteResponse(flagUnrequestedStatusChange(result, existing, safeAttributes), returning);
+  const resolvedRelationships = await resolveErrRelationships(backend, relationships);
+  await preflightPatchWritable({
+    backend, entityType, bundle, id, existing, attributes: safeAttributes,
+  });
+  if (dryRun) {
+    return {
+      dryRun: true, operation: "update", entityType, bundle, id,
+      attributes: safeAttributes, relationships: resolvedRelationships,
+    };
+  }
+  const result = await updateEntityGuarded(backend, {
+    entityType, bundle, id, attributes: safeAttributes, relationships: resolvedRelationships,
+  });
+  const written = await readWrittenRevision({
+    backend, entityType, bundle, id,
+    relationshipsSent: relationshipsWereSent(resolvedRelationships),
+    patchResult: result,
+    preferCanonical: false,
+  });
+  return shapeWriteResponse(flagUnrequestedStatusChange(written, existing, safeAttributes), returning);
 }
 
 /**
@@ -246,7 +276,7 @@ export const definitions = [
   },
   {
     name: "drupal_entity_update",
-    description: "Update an existing entity of any Drupal entity type. Only include attributes/relationships you want to change. Published moderated targets without an explicit attributes.moderation_state default to moderation_state 'draft' (forward revision).",
+    description: "Update an existing entity of any Drupal entity type. Only include attributes/relationships you want to change. Published moderated targets without an explicit attributes.moderation_state default to moderation_state 'draft' (forward revision). Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved. On moderated targets an id-mismatch PATCH preflight runs first (including dryRun) so a core working-copy guard failure is reported before the real write and no revision is saved by the probe (#201). Preflight does not un-orphan paragraphs already created — probe the host before creating dependents.",
     inputSchema: {
       type: "object", required: ["entityType", "bundle", "id"],
       properties: {
@@ -256,7 +286,7 @@ export const definitions = [
         id:            { type: "string" },
         attributes:    { type: "object" },
         relationships: { type: "object" },
-        dryRun:        { type: "boolean", default: false, description: "Validate and return a preview of the update without committing." },
+        dryRun:        { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, and (on moderated targets) run the core PATCH-guard probe against Drupal, then return a preview without the real write. The probe uses a non-matching data.id so Drupal does not save. A working-copy 400 fails the dryRun." },
         returning:     RETURNING_SCHEMA,
       },
     },

package/src/tools/nodes.js

@@ -15,6 +15,9 @@ import {
 } from "../lib/security.js";
 import { applySafeDraftDefault, hasExplicitModerationState } from "../lib/moderation-default.js";
 import { shapeWriteResponse, flagUnrequestedStatusChange, RETURNING_SCHEMA } from "../lib/entity-response.js";
+import { resolveErrRelationships, relationshipsWereSent } from "../lib/err-relationships.js";
+import { readWrittenRevision } from "../lib/write-revision.js";
+import { preflightPatchWritable, updateEntityGuarded } from "../lib/patch-preflight.js";
 import { buildRedirectAttributes, REDIRECT_ENTITY_TYPE } from "./redirects.js";
 
 /** Fallback language for an alias when the node exposes none. */
@@ -269,14 +272,15 @@ async function createNode({ site: siteName, type, title, body, summary, format,
   const bodyAttr = buildBodyAttribute(body, summary, format, site);
   if (bodyAttr) attributes.body = bodyAttr;
   assertPublishAllowed(sec, attributes);
-  if (dryRun) return { dryRun: true, operation: "create", entityType: "node", bundle: type, attributes, relationships };
   const backend = await resolveBackend(site);
+  const resolvedRelationships = await resolveErrRelationships(backend, relationships);
+  if (dryRun) return { dryRun: true, operation: "create", entityType: "node", bundle: type, attributes, relationships: resolvedRelationships };
   // Alias handling: an explicit `path.alias` is set as a manual alias; otherwise
   // `path` is omitted so pathauto generates the alias (DEV-116).
   const { pathAttr } = await resolvePathWrite({ backend, type, id: null, providedPath: attributes.path, isCreate: true });
   if (pathAttr === undefined) delete attributes.path;
   else attributes.path = pathAttr;
-  const created = await backend.createEntity({ entityType: "node", bundle: type, attributes, relationships });
+  const created = await backend.createEntity({ entityType: "node", bundle: type, attributes, relationships: resolvedRelationships });
   // Honest response: re-read so the persisted alias (explicit or pathauto-generated)
   // is reflected rather than the pre-alias write response.
   const fresh = await backend.getEntity({ entityType: "node", bundle: type, id: created.id }).catch(() => null);
@@ -334,7 +338,20 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
     backend, entityType: "node", bundle: type, id, attributes, existingEntity: existing,
   });
   assertPublishAllowed(sec, attributes);
-  if (dryRun) return { dryRun: true, operation: "update", entityType: "node", bundle: type, id, attributes, relationships };
+  // #192: resolve paragraph ERR identifiers before any host PATCH. An unresolved
+  // list would persist empty — fail the whole write instead.
+  const resolvedRelationships = await resolveErrRelationships(backend, relationships);
+  // #201: the core working-copy guard runs before deserialize. A no-op probe
+  // against the same canonical URL is a true preflight, including on dryRun.
+  await preflightPatchWritable({
+    backend, entityType: "node", bundle: type, id, existing, attributes,
+  });
+  if (dryRun) {
+    return {
+      dryRun: true, operation: "update", entityType: "node", bundle: type, id,
+      attributes, relationships: resolvedRelationships,
+    };
+  }
   // Alias handling (DEV-116): an explicit `path.alias` is set in place by
   // round-tripping the existing alias's pid (no duplicate); a path-less update
   // re-pins the current alias *with its pid* so the save can't revert/duplicate
@@ -342,11 +359,18 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
   const { pathAttr, redirect } = await resolvePathWrite({ backend, type, id, providedPath: attributes.path, isCreate: false });
   if (pathAttr === undefined) delete attributes.path;
   else attributes.path = pathAttr;
-  await backend.updateEntity({ entityType: "node", bundle: type, id, attributes, relationships });
+  const patched = await updateEntityGuarded(backend, {
+    entityType: "node", bundle: type, id, attributes, relationships: resolvedRelationships,
+  });
   const redirectResult = redirect ? await createRenameRedirect(backend, sec, redirect) : null;
-  // Honest response: re-read persisted state so the returned `url` is the alias
-  // that actually resolves, never the just-sent value.
-  const fresh = await backend.getEntity({ entityType: "node", bundle: type, id }).catch(() => null);
+  // #169: when relationships were sent, the canonical re-read is the published
+  // revision and is not proof an ERR field landed. Prefer rel:working-copy.
+  const fresh = await readWrittenRevision({
+    backend, entityType: "node", bundle: type, id,
+    relationshipsSent: relationshipsWereSent(resolvedRelationships),
+    patchResult: patched,
+    preferCanonical: true,
+  });
   // #171: an unrequested published-state flip in the persisted node is
   // reported via _statusChanged rather than returned as a clean success.
   const flagged = flagUnrequestedStatusChange(fresh, existing, attributes);
@@ -441,7 +465,7 @@ export const definitions = [
   },
   {
     name: "drupal_update_node",
-    description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Entity-reference fields go in `relationships`, not `fields`.",
+    description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets an id-mismatch PATCH preflight runs first — including on dryRun — so a core working-copy guard failure is reported before the real write and no revision is saved by the probe. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
@@ -455,8 +479,8 @@ export const definitions = [
         status:  { type: "boolean", description: "Published flag for NON-moderated types: true = publish, false = unpublish. Ignored if moderationState is set." },
         moderationState: { type: "string", description: "Moderation state transition for content_moderation types, e.g. 'draft', 'published', 'archived'. Takes precedence over status. Required to keep or re-publish a live node — omitting it on a published moderated node defaults the write to 'draft'." },
         fields:  { type: "object", description: "Scalar/attribute field values keyed by machine name. Entity-reference fields go in `relationships`, not here." },
-        relationships: { type: "object", description: "Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value uses { data: { type, id } }; multi-value uses { data: [{ type, id }, …] }." },
-        dryRun:  { type: "boolean", default: false, description: "Validate and return a preview of the update without committing." },
+        relationships: { type: "object", description: "Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value uses { data: { type, id } }; multi-value uses { data: [{ type, id }, …] }. Paragraph / ERR items must carry meta.target_revision_id — the connector injects it when missing, and fails the write if it cannot." },
+        dryRun:  { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, and (on moderated targets) run the core PATCH-guard probe against Drupal, then return a preview without the real write. The probe uses a non-matching data.id so Drupal does not save. A working-copy 400 fails the dryRun." },
         returning: RETURNING_SCHEMA,
       },
     },