drupal-mcp-connector 2.6.1 → 2.7.1

package/src/lib/verify.js

@@ -19,6 +19,7 @@
 
 import { createHash } from "node:crypto";
 import { CLIENT_VERSION } from "./config.js";
+import { resolveInboundAuthConfig, resolveInboundAuthMode } from "./http-auth.js";
 
 /** Check outcome vocabulary.
  *
@@ -44,6 +45,7 @@ export const STATIC_CHECKS = [
   "entitlement",
   "target_resolution",
   "tenant_neutrality",
+  "inbound_auth",
 ];
 
 /**
@@ -222,13 +224,14 @@ export function configDigest(config) {
  * credentials, no side effects.
  *
  * @param {object} config Parsed connector configuration.
- * @param {{source?: string, now?: () => Date}} [options]
+ * @param {{source?: string, now?: () => Date, env?: NodeJS.ProcessEnv}} [options]
  *   `source` names what was verified (a path, or a label) for the evidence;
- *   `now` is injectable so a run is reproducible in tests.
+ *   `now` is injectable so a run is reproducible in tests;
+ *   `env` is the process environment under verification (defaults to `process.env`).
  * @returns {object} Evidence document: tool, version, subject, checks,
  *   residuals and a summary. Never contains secret values.
  */
-export function verifyStatic(config, { source = "config", now = () => new Date() } = {}) {
+export function verifyStatic(config, { source = "config", now = () => new Date(), env = process.env } = {}) {
   const sites = Object.entries(config?.sites ?? {});
   const named = (name, message) => `${name}: ${message}`;
   const nothingToCheck = sites.length === 0;
@@ -364,12 +367,44 @@ export function verifyStatic(config, { source = "config", now = () => new Date()
   const tenantNeutrality = check(
     "tenant_neutrality",
     "The configuration names no real tenant hosts or identifiers",
-    mentionedHosts(config?.sites ?? {})
+    mentionedHosts({ sites: config?.sites ?? {}, auth: config?.auth ?? {} })
       .filter(({ host }) => !isNeutralHost(host))
       .map(({ path, host }) => `${path}: "${host}" is not a documentation-reserved host; a shipped example must not name a real deployment.`),
     { skipped: nothingToCheck },
   );
 
+  const inbound = resolveInboundAuthConfig(config, env);
+  const inboundFindings = [];
+  if (inbound.issuer || inbound.audience || inbound.resource) {
+    if (!inbound.issuer) inboundFindings.push("auth.issuer is missing.");
+    else if (!String(inbound.issuer).startsWith("https://")) {
+      inboundFindings.push("auth.issuer is not HTTPS.");
+    }
+    if (!inbound.audience) inboundFindings.push("auth.audience is missing.");
+    if (inbound.resource && !String(inbound.resource).startsWith("https://")) {
+      inboundFindings.push("auth.resource is not HTTPS.");
+    }
+    if (inbound.introspectionUrl && !String(inbound.introspectionUrl).startsWith("https://")) {
+      inboundFindings.push("auth.introspectionUrl is not HTTPS.");
+    }
+  }
+  const transportName = env.MCP_TRANSPORT || "stdio";
+  if (transportName === "https" || transportName === "http") {
+    const decision = resolveInboundAuthMode({
+      bindHost: env.MCP_BIND_HOST || "0.0.0.0",
+      allowUnauth: env.MCP_ALLOW_UNAUTHENTICATED === "1",
+      sharedToken: env.MCP_AUTH_TOKEN || "",
+      resourceServer: inbound,
+    });
+    if (decision.mode === "fatal") inboundFindings.push(decision.reason);
+  }
+
+  const inboundAuth = check(
+    "inbound_auth",
+    "Network-facing HTTPS authenticates as an OAuth protected resource",
+    inboundFindings,
+  );
+
   const checks = [
     transport,
     principalAuth,
@@ -379,6 +414,7 @@ export function verifyStatic(config, { source = "config", now = () => new Date()
     entitlement,
     targetResolution,
     tenantNeutrality,
+    inboundAuth,
   ];
 
   const counts = checks.reduce(

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/config.js

@@ -12,6 +12,7 @@
  */
 
 import { getSiteConfig } from "../lib/config.js";
+import { describeTarget, getRequestIdentity } from "../lib/principal.js";
 import {
   resolveSecurityConfig,
   getSecuritySummary,
@@ -117,8 +118,13 @@ async function whoami({ site: siteName }) {
   // When no OAuth scopes are configured, hasScope() is a no-op (preset-only).
   const canWrite  = !sec.readOnly && hasScope(site, "mcp_write");
   const canConfig = hasScope(site, "mcp_config");
+  const identity = getRequestIdentity();
   return {
     site: site._name,
+    target: describeTarget(site, siteName ? "hint" : "default"),
+    principal: identity
+      ? { sub: identity.sub, clientId: identity.clientId, scopes: [...(identity.scopes ?? [])] }
+      : null,
     tier: inferTier(site, sec),
     preset: summary.preset,
     scopes: site.oauth?.scopes ?? [],

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,
       },
     },

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: {