drupal-mcp-connector 2.7.3 → 2.8.0

package/src/lib/patch-preflight.js

@@ -1,5 +1,5 @@
 /**
- * JSON:API PATCH preflight for Drupal core's working-copy guard (#201).
+ * JSON:API PATCH preflight and working-copy targeting (#201 / #166).
  *
  * `EntityResource::patchIndividual()` rejects a canonical PATCH when the
  * stored entity is not both the latest and the default revision. That check
@@ -8,23 +8,33 @@
  * 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.
+ * payload" with no row written.
  *
- * `workingCopy: null` and "latest-version vid === default vid" are not proof
- * the node is writable. That is the #201 lie.
+ * Two distinct cases share that core 400:
  *
- * Distinct from #166: there a working copy is visible and the fix is PATCH
- * `?resourceVersion=rel:working-copy`. This module does not implement that.
+ * - **#166** — `rel:working-copy` resolves. PATCH (and the dryRun probe)
+ *   target `?resourceVersion=rel:working-copy`. Do not discard, do not
+ *   retry the canonical URL, and do not tell the caller to publish first.
+ * - **#201** — the working-copy alias does not resolve, but core still
+ *   blocks. That is a stray revision row. Refuse with revision-surgery
+ *   language. `workingCopy: null` is not proof the node is writable.
+ *
+ * A working-copy 400 *after* targeting the working copy is a stale or
+ * concurrent write — refuse, do not fall back to discard.
  */
 
 import { entityLooksModerated, hasExplicitModerationState } from "./moderation-default.js";
+import { entityRevisionId } from "./write-revision.js";
 
 /** Stable error code for a core working-copy / not-latest-revision block. */
 export const PATCH_BLOCKED_CODE = "PATCH_BLOCKED";
 
+/** Stable error code when a working-copy PATCH itself is rejected. */
+export const PATCH_WORKING_COPY_STALE_CODE = "PATCH_WORKING_COPY_STALE";
+
+/** Stable error code when the working-copy resource does not match the target. */
+export const PATCH_TARGET_AMBIGUOUS_CODE = "PATCH_TARGET_AMBIGUOUS";
+
 const WORKING_COPY_PATCH_RE = /has a working copy is not yet supported/i;
 
 /**
@@ -39,61 +49,75 @@ export const PATCH_BLOCKED_MESSAGE =
   "See connector #201. Do not retry the same canonical PATCH.";
 
 /**
- * Read a revision id off a working-copy body (canonical or raw-ish).
- * @param {?object} workingCopy
- * @returns {?number|string}
- */
-function workingCopyVid(workingCopy) {
-  if (!workingCopy || typeof workingCopy !== "object") return null;
-  const fields = workingCopy.fields && typeof workingCopy.fields === "object"
-    ? workingCopy.fields
-    : {};
-  const attrs = workingCopy.attributes && typeof workingCopy.attributes === "object"
-    ? workingCopy.attributes
-    : {};
-  const raw = workingCopy.vid
-    ?? fields.drupal_internal__vid
-    ?? attrs.drupal_internal__vid
-    ?? workingCopy.drupal_internal__vid;
-  if (raw === undefined || raw === null || raw === "") return null;
-  const n = Number(raw);
-  return Number.isFinite(n) ? n : raw;
-}
+ * A working-copy-targeted PATCH (or its probe) hit core's working-copy guard.
+ * That is a stale or concurrent conflict, not an invitation to discard.
+ */
+export const PATCH_WORKING_COPY_STALE_MESSAGE =
+  "This entity's working-copy revision could not be updated (stale or concurrent write). " +
+  "The connector will not retry the canonical URL or discard the draft. " +
+  "Re-read rel:working-copy and retry, or resolve the conflict in Drupal. See connector #166.";
 
 /**
  * Operator message for a core working-copy 400.
- * A resolvable working copy is an ordinary pending draft — do not prescribe
- * revision surgery. Surgery is only for the invisible-row case (#201 follow-up).
- * @param {?object} [workingCopy]
+ * A resolvable working copy is edited in place (#166) — this message is only
+ * for the invisible-row case (#201).
  * @returns {string}
  */
-export function patchBlockedMessage(workingCopy) {
-  if (workingCopy) {
-    const vid = workingCopyVid(workingCopy);
-    const which = vid !== null && vid !== undefined ? ` (vid ${vid})` : "";
-    return `This node has a pending draft${which}. Publish or discard it `
-      + "before a canonical PATCH.";
-  }
+export function patchBlockedMessage() {
   return PATCH_BLOCKED_MESSAGE;
 }
 
 /**
- * Thrown when the core working-copy PATCH guard rejects a write (or its probe).
+ * Thrown when the core working-copy PATCH guard rejects a canonical write
+ * (or its probe) and no working copy is addressable (#201).
  */
 export class PatchBlockedError extends Error {
   /**
    * @param {?Error} [cause] The original Drupal 400.
-   * @param {{workingCopy?: ?object}} [options]
    */
-  constructor(cause, { workingCopy } = {}) {
-    super(patchBlockedMessage(workingCopy ?? null));
+  constructor(cause) {
+    super(PATCH_BLOCKED_MESSAGE);
     this.name = "PatchBlockedError";
     this.code = PATCH_BLOCKED_CODE;
-    if (workingCopy) this.workingCopyVid = workingCopyVid(workingCopy);
     if (cause) this.cause = cause;
   }
 }
 
+/**
+ * Thrown when a working-copy-targeted PATCH or probe is rejected (#166).
+ */
+export class WorkingCopyStaleError extends Error {
+  /**
+   * @param {?Error} [cause] The original Drupal 400.
+   */
+  constructor(cause) {
+    super(PATCH_WORKING_COPY_STALE_MESSAGE);
+    this.name = "WorkingCopyStaleError";
+    this.code = PATCH_WORKING_COPY_STALE_CODE;
+    if (cause) this.cause = cause;
+  }
+}
+
+/**
+ * Thrown when `rel:working-copy` resolves to a different UUID than the
+ * entity being updated.
+ */
+export class PatchTargetAmbiguousError extends Error {
+  /**
+   * @param {string} expectedId Requested entity UUID.
+   * @param {string} actualId Working-copy resource UUID.
+   */
+  constructor(expectedId, actualId) {
+    super(
+      `The working-copy resource id (${actualId}) does not match the entity ` +
+      `being updated (${expectedId}). Refusing an ambiguous PATCH target. ` +
+      "See connector #166."
+    );
+    this.name = "PatchTargetAmbiguousError";
+    this.code = PATCH_TARGET_AMBIGUOUS_CODE;
+  }
+}
+
 /**
  * Whether an error is Drupal core's working-copy PATCH guard (core #2795279).
  * @param {unknown} err
@@ -105,27 +129,22 @@ export function isWorkingCopyPatchError(err) {
 
 /**
  * Rewrite a core working-copy 400 into {@link PatchBlockedError}; otherwise
- * return the original value. Pass `workingCopy` when the pending draft is
- * addressable so the message does not prescribe revision surgery.
+ * return the original value. Used only for the stray-revision (#201) case.
  * @param {unknown} err
- * @param {{workingCopy?: ?object}} [options]
  * @returns {unknown}
  */
-export function rewriteWorkingCopyPatchError(err, { workingCopy } = {}) {
+export function rewriteWorkingCopyPatchError(err) {
   if (!isWorkingCopyPatchError(err)) return err;
-  return new PatchBlockedError(
-    err instanceof Error ? err : new Error(String(err)),
-    { workingCopy },
-  );
+  return new PatchBlockedError(err instanceof Error ? err : new Error(String(err)));
 }
 
 /**
- * Load `rel:working-copy` so a blocked PATCH can name a pending draft.
+ * Load `rel:working-copy` so a write can target the pending draft (#166).
  * @param {object} backend
  * @param {{entityType: string, bundle: string, id: string}} ref
  * @returns {Promise<?object>}
  */
-async function loadWorkingCopy(backend, { entityType, bundle, id }) {
+export async function loadWorkingCopy(backend, { entityType, bundle, id }) {
   if (typeof backend?.getEntity !== "function") return null;
   try {
     const wc = await backend.getEntity({
@@ -137,6 +156,38 @@ async function loadWorkingCopy(backend, { entityType, bundle, id }) {
   }
 }
 
+/**
+ * Decide whether this PATCH should target `rel:working-copy`.
+ *
+ * A 200 from the working-copy alias is treated as an addressable draft unless
+ * both live and working vids are known and equal (the alias echoed the
+ * default revision). An id mismatch is refused rather than guessed.
+ *
+ * @param {object} backend
+ * @param {{entityType: string, bundle: string, id: string, existing?: ?object}} ref
+ * @returns {Promise<{resourceVersion: ?string, workingCopy: ?object, liveVid: ?number|string, workingVid: ?number|string}>}
+ * @throws {PatchTargetAmbiguousError}
+ */
+export async function resolveWorkingCopyPatchTarget(backend, { entityType, bundle, id, existing }) {
+  const workingCopy = await loadWorkingCopy(backend, { entityType, bundle, id });
+  let liveVid = entityRevisionId(existing);
+  if (workingCopy && (liveVid === null || liveVid === undefined) && typeof backend?.getEntity === "function") {
+    const live = await backend.getEntity({ entityType, bundle, id }).catch(() => null);
+    liveVid = entityRevisionId(live);
+  }
+  if (!workingCopy) {
+    return { resourceVersion: undefined, workingCopy: null, liveVid, workingVid: null };
+  }
+  if (workingCopy.id && workingCopy.id !== id) {
+    throw new PatchTargetAmbiguousError(id, workingCopy.id);
+  }
+  const workingVid = entityRevisionId(workingCopy);
+  if (workingVid !== null && liveVid !== null && String(workingVid) === String(liveVid)) {
+    return { resourceVersion: undefined, workingCopy, liveVid, workingVid };
+  }
+  return { resourceVersion: "rel:working-copy", workingCopy, liveVid, workingVid };
+}
+
 /**
  * Whether this update should run the PATCH probe.
  * Skip unmoderated / non-revisionable bundles — the guard is about
@@ -170,14 +221,16 @@ export function isProbePassedWithoutSave(err) {
 }
 
 /**
- * Probe the same guard core uses on the canonical PATCH URL.
+ * Probe the same guard core uses on the PATCH about to be sent.
  *
  * 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.
+ * treated as a probe failure.
+ *
+ * When `resourceVersion` is `rel:working-copy`, the probe hits that same
+ * URL so dryRun cannot succeed when the real write would 400 (#166).
  *
  * @param {object} args
  * @param {object} args.backend Backend with `rawQuery` + `resourcePath`.
@@ -186,11 +239,12 @@ export function isProbePassedWithoutSave(err) {
  * @param {string} args.id
  * @param {?object} [args.existing]
  * @param {object} [args.attributes]
+ * @param {?string} [args.resourceVersion]
  * @returns {Promise<{probed: boolean, writable?: boolean|string, skipped?: string}>}
- * @throws {PatchBlockedError} When the guard rejects the probe.
+ * @throws {PatchBlockedError|WorkingCopyStaleError} When the guard rejects the probe.
  */
 export async function preflightPatchWritable({
-  backend, entityType, bundle, id, existing, attributes,
+  backend, entityType, bundle, id, existing, attributes, resourceVersion,
 }) {
   if (!shouldPreflightPatch({ existing, attributes })) {
     return { probed: false };
@@ -198,7 +252,10 @@ export async function preflightPatchWritable({
   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)}`;
+  let path = `${backend.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`;
+  if (resourceVersion) {
+    path += `?resourceVersion=${encodeURIComponent(resourceVersion)}`;
+  }
   const type = `${entityType}--${bundle}`;
   const probeId = id === PATCH_PROBE_MISMATCH_ID
     ? "00000000-0000-4000-a000-000000000002"
@@ -217,11 +274,15 @@ export async function preflightPatchWritable({
     );
   } catch (err) {
     if (isWorkingCopyPatchError(err)) {
+      const cause = err instanceof Error ? err : new Error(String(err));
+      if (resourceVersion === "rel:working-copy") {
+        throw new WorkingCopyStaleError(cause);
+      }
       const workingCopy = await loadWorkingCopy(backend, { entityType, bundle, id });
-      throw new PatchBlockedError(
-        err instanceof Error ? err : new Error(String(err)),
-        { workingCopy },
-      );
+      if (workingCopy) {
+        throw new WorkingCopyStaleError(cause);
+      }
+      throw new PatchBlockedError(cause);
     }
     if (isProbePassedWithoutSave(err)) {
       return { probed: true, writable: true };
@@ -230,19 +291,49 @@ export async function preflightPatchWritable({
   }
 }
 
+/**
+ * Resolve the PATCH target, then run the same probe the real write will use.
+ * Callers inherit #166 targeting by going through this before dryRun or write.
+ *
+ * @param {object} backend
+ * @param {{entityType: string, bundle: string, id: string, existing?: ?object, attributes?: object}} args
+ * @returns {Promise<{resourceVersion: ?string, workingCopy: ?object, liveVid: ?number|string, workingVid: ?number|string}>}
+ */
+export async function prepareGuardedPatch(backend, {
+  entityType, bundle, id, existing, attributes,
+}) {
+  const target = shouldPreflightPatch({ existing, attributes })
+    ? await resolveWorkingCopyPatchTarget(backend, { entityType, bundle, id, existing })
+    : { resourceVersion: undefined, workingCopy: null, liveVid: null, workingVid: null };
+  await preflightPatchWritable({
+    backend, entityType, bundle, id, existing, attributes,
+    resourceVersion: target.resourceVersion,
+  });
+  return target;
+}
+
 /**
  * `backend.updateEntity` with the core working-copy 400 rewritten.
+ * A working-copy-targeted 400 is stale/concurrent (#166). A canonical 400
+ * with no addressable working copy is the #201 stray-revision case.
  * @param {object} backend
  * @param {object} input updateEntity argument.
  * @returns {Promise<*>}
- * @throws {PatchBlockedError|*}
+ * @throws {PatchBlockedError|WorkingCopyStaleError|*}
  */
 export async function updateEntityGuarded(backend, input) {
   try {
     return await backend.updateEntity(input);
   } catch (err) {
     if (!isWorkingCopyPatchError(err)) throw err;
+    const cause = err instanceof Error ? err : new Error(String(err));
+    if (input?.resourceVersion === "rel:working-copy") {
+      throw new WorkingCopyStaleError(cause);
+    }
     const workingCopy = await loadWorkingCopy(backend, input);
-    throw rewriteWorkingCopyPatchError(err, { workingCopy });
+    if (workingCopy) {
+      throw new WorkingCopyStaleError(cause);
+    }
+    throw new PatchBlockedError(cause);
   }
 }

package/src/lib/security.js

@@ -53,6 +53,17 @@ import { parse } from "graphql";
  *
  *  globalRedactedFields string[]         stripped from every response, every type
  *
+ *  declaredCeiling     string            narrow-only X-MCP-Declared-Ceiling
+ *                                        (public|internal|restricted). Invalid
+ *                                        values are dropped, never widened.
+ *  readBudgets         object            finite northbound budgets bound to
+ *                                        principal+target (#179). Same classes
+ *                                        as mcp_sentinel: results, bytes,
+ *                                        requests, requestWindowSec, pages,
+ *                                        pageWindowSec, chainedActions,
+ *                                        chainedActionWindowSec. Omitted keys
+ *                                        use the module defaults.
+ *
  * ─── Field redaction ──────────────────────────────────────────────────────
  *
  *  Redacted fields are replaced with "[REDACTED]" in response attributes.
@@ -259,6 +270,8 @@ export function resolveSecurityConfig(site) {
       ...(preset.globalRedactedFields ?? []),
       ...(raw.globalRedactedFields    ?? []),
     ],
+    declaredCeiling:       raw.declaredCeiling ?? preset.declaredCeiling,
+    readBudgets:           raw.readBudgets ?? preset.readBudgets ?? null,
   };
 }
 
@@ -470,7 +483,7 @@ export function assertPublishAllowed(secConfig, attributes = {}) {
  * @param {string} query GraphQL document text.
  * @returns {boolean} True if any operation is a mutation.
  */
-function graphqlHasMutation(query) {
+export function graphqlHasMutation(query) {
   try {
     const doc = parse(query);
     return doc.definitions.some(
@@ -754,5 +767,6 @@ export function getSecuritySummary(site) {
     deniedEntityTypes:     cfg.deniedEntityTypes,
     entityRules:           cfg.entityRules,
     globalRedactedFields:  cfg.globalRedactedFields,
+    declaredCeiling:       cfg.declaredCeiling ?? null,
   };
 }

package/src/lib/server-tools.js

@@ -24,6 +24,7 @@
 
 import fetch from "node-fetch";
 import { authHeadersAsync, clientHeaders, CLIENT_VERSION } from "./config.js";
+import { consumeBudgetIfEnforced, northboundHeaders, sourceBudgetDenial } from "./data-flow.js";
 import { clearToken } from "./oauth.js";
 
 /**
@@ -90,6 +91,7 @@ async function baseHeaders(site, sessionId) {
     Accept: "application/json, text/event-stream",
     "MCP-Protocol-Version": MCP_PROTOCOL_VERSION,
     ...clientHeaders(),
+    ...northboundHeaders(),
     ...(await authHeadersAsync(site)),
   };
   if (sessionId) headers["Mcp-Session-Id"] = sessionId;
@@ -263,9 +265,12 @@ export async function callServerTool(site, toolName, args = {}) {
   let sessionId = await ensureSession(site, endpoint);
   let refreshedAuth = false;
   let reinitedSession = false;
+  let paid = false;
 
   // Retry loop: at most one auth refresh and one session re-init, each replayed once.
   while (true) {
+    consumeBudgetIfEnforced("request", 1, { retry: paid });
+    paid = true;
     const res = await fetch(endpoint, {
       method: "POST",
       headers: await baseHeaders(site, sessionId),
@@ -289,6 +294,8 @@ export async function callServerTool(site, toolName, args = {}) {
     }
 
     if (!res.ok) {
+      const mapped = sourceBudgetDenial(rawText);
+      if (mapped) throw mapped;
       throw new Error(`Server-tool call ${toolName} failed ${res.status}: ${rawText}`);
     }
 
@@ -303,6 +310,8 @@ export async function callServerTool(site, toolName, args = {}) {
     const result = body?.result;
     if (result?.isError) {
       const detail = extractTextContent(result) || "tool reported an error";
+      const mapped = sourceBudgetDenial(detail);
+      if (mapped) throw mapped;
       throw new Error(`Server-tool ${toolName} reported an error: ${detail}`);
     }
     return result;

package/src/lib/site-target.js

@@ -0,0 +1,78 @@
+/**
+ * Resolved-target disclosure and the multi-site write guard (#167).
+ *
+ * A silent default that returns plausible content from the wrong environment
+ * is the failure class: the response looks like success and every field a
+ * caller would sanity-check (id, title, url) is correct. `_target` uses the
+ * same `{ name, baseUrl, source }` block as `drupal_mcp_whoami` so there is
+ * one vocabulary. `source` is load-bearing — `hint` when the caller named a
+ * target, `default` when `defaultSite` was used, `grant` when a principal
+ * had exactly one entitled site.
+ *
+ * Reads may still default. Writes (and GraphQL mutations) may not when more
+ * than one site is configured: a write on the wrong site is not recoverable.
+ */
+
+import { describeTarget } from "./principal.js";
+import { isWriteLikeCall } from "./operations.js";
+import { SecurityError } from "./security.js";
+
+/** Shared `site` argument schema. Injected onto every tool that accepts `site`. */
+export const SITE_PARAM = {
+  type: "string",
+  description:
+    "Named site from connector config. Omit only on reads: multi-site configs " +
+    "fall back to defaultSite (often local/dev, not production). Writes require " +
+    "an explicit site when more than one site is configured. Every response " +
+    "includes `_target` { name, baseUrl, source } (`hint` when you passed site, " +
+    "`default` when you did not).",
+};
+
+/**
+ * Attach the resolved target to a tool payload so JSON.stringify keeps it.
+ *
+ * Object results get `_target` as a sibling. Arrays are wrapped as
+ * `{ items, _target }` because extra properties on an array are dropped by
+ * JSON.stringify. Tools that do not address a single site pass `resolved` as
+ * null and are returned unchanged.
+ *
+ * @param {*} result Handler return value.
+ * @param {?{site: object, source: string}} resolved
+ * @returns {*}
+ */
+export function withResolvedTarget(result, resolved) {
+  if (!resolved?.site) return result;
+  const _target = describeTarget(resolved.site, resolved.source);
+  if (result && typeof result === "object" && !Array.isArray(result)) {
+    return { ...result, _target };
+  }
+  if (Array.isArray(result)) {
+    return { items: result, _target };
+  }
+  if (result === undefined || result === null) {
+    return { _target };
+  }
+  return { result, _target };
+}
+
+/**
+ * Refuse a write that would silently land on defaultSite when more than one
+ * site is configured. Resolution behaviour for reads is unchanged.
+ *
+ * @param {string} toolName
+ * @param {object} args Raw caller arguments (before any default rewrite).
+ * @param {?{site: object, source: string, name: string}} resolved
+ * @param {string[]} siteNames Configured site names.
+ * @returns {void}
+ * @throws {SecurityError}
+ */
+export function assertExplicitSiteForWrite(toolName, args, resolved, siteNames) {
+  if (!resolved || resolved.source !== "default") return;
+  if (!Array.isArray(siteNames) || siteNames.length < 2) return;
+  if (!isWriteLikeCall(toolName, args)) return;
+  throw new SecurityError(
+    "Write tools require an explicit site when more than one site is configured. " +
+    "Omitted site would default to \"" + resolved.name + "\" (" + resolved.site.baseUrl + "). " +
+    "Pass site explicitly. Configured sites: " + siteNames.join(", ") + ".",
+  );
+}

package/src/lib/tool-prompts.js

@@ -15,6 +15,7 @@
  */
 
 import { isDestructiveTool } from "./operations.js";
+import { SITE_PARAM } from "./site-target.js";
 
 /** Convert a tool name to its prompt/command name: `drupal_create_node` → `drupal-create-node`. */
 export const toolNameToPromptName = (name) => name.replace(/_/g, "-");
@@ -54,7 +55,7 @@ export function paramList(inputSchema) {
     name,
     required: required.has(name),
     hint: typeHint(spec),
-    description: spec?.description || (name === "site" ? "omit for the default site" : ""),
+    description: spec?.description || (name === "site" ? SITE_PARAM.description : ""),
   }));
 }
 

package/src/lib/write-revision.js

@@ -5,7 +5,79 @@
  * 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`.
+ *
+ * After a write, {@link attachWrittenRevisionPair} may add `_revisions`
+ * `{ live, working }` when both vids can be read honestly (#166).
+ */
+
+/**
+ * Read a revision id off a canonical (or raw-ish) entity body.
+ * @param {?object} entity
+ * @returns {?number|string}
+ */
+export function entityRevisionId(entity) {
+  if (!entity || typeof entity !== "object") return null;
+  const fields = entity.fields && typeof entity.fields === "object"
+    ? entity.fields
+    : {};
+  const attrs = entity.attributes && typeof entity.attributes === "object"
+    ? entity.attributes
+    : {};
+  const raw = entity.vid
+    ?? fields.drupal_internal__vid
+    ?? attrs.drupal_internal__vid
+    ?? entity.drupal_internal__vid;
+  if (raw === undefined || raw === null || raw === "") return null;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : raw;
+}
+
+/**
+ * Attach distinct live vs working revision ids when both are known.
+ * Does not invent vids.
+ * @param {object} entity
+ * @param {{live: ?number|string, working: ?number|string}} pair
+ * @returns {object}
  */
+export function attachRevisionPair(entity, { live, working }) {
+  if (!entity || live === null || live === undefined || working === null || working === undefined) {
+    return entity;
+  }
+  if (String(live) === String(working)) return entity;
+  return { ...entity, _revisions: { live, working } };
+}
+
+/**
+ * After a write, attach `_revisions` when a working copy is addressable
+ * and the live vid is already known. Omits the block when either side
+ * cannot be read — never invents a vid.
+ *
+ * @param {object} args
+ * @param {object} args.backend
+ * @param {string} args.entityType
+ * @param {string} args.bundle
+ * @param {string} args.id
+ * @param {object} args.entity Write result to annotate.
+ * @param {?number|string} [args.liveVid]
+ * @returns {Promise<object>}
+ */
+export async function attachWrittenRevisionPair({
+  backend, entityType, bundle, id, entity, liveVid,
+}) {
+  if (liveVid === null || liveVid === undefined || !entity) return entity;
+  let workingVid = null;
+  if (typeof backend?.getEntity === "function") {
+    try {
+      const wc = await backend.getEntity({
+        entityType, bundle, id, resourceVersion: "rel:working-copy",
+      });
+      workingVid = entityRevisionId(wc);
+    } catch {
+      workingVid = null;
+    }
+  }
+  return attachRevisionPair(entity, { live: liveVid, working: workingVid });
+}
 
 /**
  * @param {object} args
@@ -16,15 +88,23 @@
  * @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).
+ *   re-GET the written resource (nodes do this for the persisted alias).
+ * @param {?string} [args.resourceVersion] JSON:API revision selector used
+ *   for the write (e.g. `rel:working-copy`). PreferCanonical re-reads this
+ *   resource instead of the default revision so a draft PATCH is not
+ *   replaced by the live body.
  * @returns {Promise<object>} Entity to return, with `_revision` when relevant.
  */
 export async function readWrittenRevision({
   backend, entityType, bundle, id, relationshipsSent, patchResult = null, preferCanonical = false,
+  resourceVersion,
 }) {
   if (!relationshipsSent) {
     if (preferCanonical && typeof backend.getEntity === "function") {
-      const fresh = await backend.getEntity({ entityType, bundle, id }).catch(() => null);
+      const fresh = await backend.getEntity({
+        entityType, bundle, id,
+        ...(resourceVersion ? { resourceVersion } : {}),
+      }).catch(() => null);
       return fresh ?? patchResult ?? { id };
     }
     return patchResult ?? { id };

package/src/tools/bulk.js

@@ -19,7 +19,7 @@ import {
   resolveErrRelationships, embedParagraphRef,
   resolveParagraphRevisionId, missingParagraphRevisionError,
 } from "../lib/err-relationships.js";
-import { preflightPatchWritable, updateEntityGuarded } from "../lib/patch-preflight.js";
+import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
 
 /**
  * Normalize an unknown thrown value into a human-readable message.
@@ -118,13 +118,14 @@ async function bulkUpdate({ site: siteName, entityType, bundle, items = [] }) {
       });
       assertPublishAllowed(sec, attributes);
       const resolvedRelationships = await resolveErrRelationships(backend, item.relationships ?? {});
-      await preflightPatchWritable({
-        backend, entityType, bundle, id: item.id, existing, attributes,
+      const patchTarget = await prepareGuardedPatch(backend, {
+        entityType, bundle, id: item.id, existing, attributes,
       });
       const entity = await updateEntityGuarded(backend, {
         entityType, bundle, id: item.id,
         attributes,
         relationships: resolvedRelationships,
+        ...(patchTarget.resourceVersion ? { resourceVersion: patchTarget.resourceVersion } : {}),
       });
       updated += 1;
       results.push({ index, success: true, id: entity?.id ?? item.id });