drupal-mcp-connector 2.7.4 → 2.8.0

package/src/lib/field-definition.js

@@ -0,0 +1,285 @@
+/**
+ * Authoritative text-format resolution for node writes (#168).
+ *
+ * `backend.getEntitySchema` is sampling-only: it can label a field
+ * `text_formatted` / `text_with_summary` but does NOT expose Field API
+ * `allowed_formats`. Never invent that list from `defaultTextFormat` or
+ * `FALLBACK_TEXT_FORMAT` (`full_html`).
+ *
+ * Resolution chain for a field definition:
+ *   1. `backend.getFieldDefinition` — JSON:API `field_config` via an internal
+ *      adapter fetch (not `drupal_entity_get`; `field_config` is on the agent
+ *      deny list).
+ *   2. Drush `config:get field.field.{entityType}.{bundle}.{field}` when a
+ *      Drush bridge is configured.
+ *   3. If the definition cannot be resolved: return null. Callers keep the
+ *      historical default chain only while the list is unknown. Once the list
+ *      is known, never persist a format outside it.
+ */
+
+import { drushConfigured } from "./audit-sources.js";
+import { validateMachineName } from "./validate.js";
+import { parseDrush, sshDrush } from "../tools/drush.js";
+
+/** Last-resort body format when the Field API list cannot be resolved. */
+export const FALLBACK_TEXT_FORMAT = "full_html";
+
+const FORMATTED_FIELD_TYPES = new Set(["text", "text_long", "text_with_summary"]);
+
+const SKIP_FORMAT_FIELDS = new Set([
+  "title", "status", "moderation_state", "path", "promote", "sticky",
+  "created", "changed", "langcode",
+]);
+
+/**
+ * Normalize a Field API `allowed_formats` value to a string list.
+ * @param {*} raw settings.allowed_formats from field_config / Drush.
+ * @returns {string[]}
+ */
+export function asFormatList(raw) {
+  if (Array.isArray(raw)) return raw.filter((f) => typeof f === "string" && f);
+  if (raw && typeof raw === "object") {
+    return [...new Map(Object.entries(raw)).values()].filter((f) => typeof f === "string" && f);
+  }
+  return [];
+}
+
+/**
+ * Parse a field_config resource or `field.field.*` config object.
+ * @param {object} obj Config / JSON:API attributes.
+ * @param {string} [fallbackName] Field name when the object omits `field_name`.
+ * @returns {?{fieldName: string, fieldType: ?string, allowedFormats: string[]}}
+ */
+export function parseFieldConfigObject(obj, fallbackName) {
+  if (!obj || typeof obj !== "object") return null;
+  const attrs = new Map(Object.entries(obj));
+  const fieldName = attrs.get("field_name") || fallbackName;
+  if (typeof fieldName !== "string" || !fieldName) return null;
+  const settings = attrs.get("settings");
+  const settingsMap = settings && typeof settings === "object" && !Array.isArray(settings)
+    ? new Map(Object.entries(settings))
+    : new Map();
+  const fieldType = attrs.get("field_type");
+  return {
+    fieldName,
+    fieldType: typeof fieldType === "string" ? fieldType : null,
+    allowedFormats: asFormatList(settingsMap.get("allowed_formats")),
+  };
+}
+
+/**
+ * Pick the config object out of a Drush `config:get --format=json` payload.
+ * @param {*} raw Parsed Drush JSON.
+ * @param {string} configName `field.field.{type}.{bundle}.{field}`.
+ * @returns {?object}
+ */
+function unwrapDrushConfig(raw, configName) {
+  if (!raw || typeof raw !== "object") return null;
+  const map = new Map(Object.entries(raw));
+  if (map.has("field_type") || map.has("settings")) return raw;
+  const named = map.get(configName);
+  if (named && typeof named === "object") return named;
+  if (map.size === 1) {
+    const only = [...map.values()][0];
+    if (only && typeof only === "object") return only;
+  }
+  return raw;
+}
+
+/**
+ * Load a field definition via Drush `config:get` (chain step 2).
+ * @param {object} site Site config with `drushSsh`.
+ * @param {string} entityType
+ * @param {string} bundle
+ * @param {string} fieldName
+ * @returns {Promise<?{fieldName: string, fieldType: ?string, allowedFormats: string[]}>}
+ */
+export async function fieldDefinitionFromDrush(site, entityType, bundle, fieldName) {
+  validateMachineName(entityType, "entityType");
+  validateMachineName(bundle, "bundle");
+  validateMachineName(fieldName, "fieldName");
+  const configName = `field.field.${entityType}.${bundle}.${fieldName}`;
+  try {
+    const raw = parseDrush(await sshDrush(site, ["config:get", configName, "--format=json"]));
+    return parseFieldConfigObject(unwrapDrushConfig(raw, configName), fieldName);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve Field API metadata. See the file header for the chain.
+ * @param {object} backend Resolved backend.
+ * @param {object} site Site config.
+ * @param {string} entityType
+ * @param {string} bundle
+ * @param {string} fieldName
+ * @returns {Promise<?{fieldName: string, fieldType: ?string, allowedFormats: string[]}>}
+ */
+export async function resolveFieldDefinition(backend, site, entityType, bundle, fieldName) {
+  if (typeof backend?.getFieldDefinition === "function") {
+    try {
+      const def = await backend.getFieldDefinition({ entityType, bundle, fieldName });
+      if (def) return parseFieldConfigObject({
+        field_name: def.fieldName,
+        field_type: def.fieldType,
+        settings: { allowed_formats: def.allowedFormats },
+      }, fieldName) ?? def;
+    } catch {
+      // JSON:API field_config is optional; try Drush next.
+    }
+  }
+  if (drushConfigured(site)) {
+    const def = await fieldDefinitionFromDrush(site, entityType, bundle, fieldName);
+    if (def) return def;
+  }
+  return null;
+}
+
+/**
+ * Choose the format to persist, or throw before mutation.
+ *
+ * Known list + exactly one entry → that format when the caller omits one.
+ * Known list + caller format outside it → refuse.
+ * Known list + several entries + omitted format → site `defaultTextFormat`
+ * only if it is in the list; otherwise refuse (never `full_html` when it
+ * is not allowed).
+ * Unknown list (`allowedFormats` is null): historical default chain only
+ * when `defaultWhenUnknown` is true (body); otherwise leave format omitted.
+ *
+ * @param {{fieldName: string, requested: ?string, allowedFormats: ?string[],
+ *   site?: object, defaultWhenUnknown?: boolean}} input
+ * @returns {string|undefined}
+ */
+export function resolveTextFormat({
+  fieldName, requested, allowedFormats, site, defaultWhenUnknown = false,
+}) {
+  const asked = requested === undefined || requested === null || requested === ""
+    ? undefined
+    : String(requested);
+
+  if (!Array.isArray(allowedFormats)) {
+    if (asked !== undefined) return asked;
+    if (!defaultWhenUnknown) return undefined;
+    return site?.defaultTextFormat ?? FALLBACK_TEXT_FORMAT;
+  }
+
+  if (allowedFormats.length === 0) {
+    if (asked !== undefined) return asked;
+    if (!defaultWhenUnknown) return undefined;
+    return site?.defaultTextFormat ?? FALLBACK_TEXT_FORMAT;
+  }
+
+  if (asked !== undefined) {
+    if (!allowedFormats.includes(asked)) {
+      throw textFormatError(fieldName, asked, allowedFormats);
+    }
+    return asked;
+  }
+
+  if (allowedFormats.length === 1) {
+    return allowedFormats[0];
+  }
+
+  const siteDefault = site?.defaultTextFormat;
+  if (siteDefault && allowedFormats.includes(siteDefault)) {
+    return siteDefault;
+  }
+
+  throw textFormatError(fieldName, siteDefault ?? FALLBACK_TEXT_FORMAT, allowedFormats);
+}
+
+/**
+ * @param {string} fieldName
+ * @param {string} requested
+ * @param {string[]} allowed
+ * @returns {Error}
+ */
+function textFormatError(fieldName, requested, allowed) {
+  return new Error(
+    `Field "${fieldName}" does not allow format "${requested}" ` +
+    `(allowed: ${allowed.join(", ")}).`
+  );
+}
+
+/**
+ * Whether a payload value is already a formatted-text object.
+ * @param {*} value
+ * @returns {boolean}
+ */
+function isFormattedShape(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  if (!Object.prototype.hasOwnProperty.call(value, "value")) return false;
+  return ["format", "summary", "processed"].some((k) => Object.prototype.hasOwnProperty.call(value, k));
+}
+
+/**
+ * @param {*} value
+ * @returns {string|undefined}
+ */
+function requestedFormatOf(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)
+      && Object.prototype.hasOwnProperty.call(value, "format")) {
+    return value.format;
+  }
+  return undefined;
+}
+
+/**
+ * @param {*} raw
+ * @param {string|undefined} format
+ * @returns {{value: *, format?: string, summary?: *}}
+ */
+function normalizeFormattedValue(raw, format) {
+  if (typeof raw === "string") {
+    const out = { value: raw };
+    if (format !== undefined) out.format = format;
+    return out;
+  }
+  const out = { value: raw.value };
+  if (format !== undefined) out.format = format;
+  if (Object.prototype.hasOwnProperty.call(raw, "summary")) out.summary = raw.summary;
+  return out;
+}
+
+/**
+ * Default and validate text formats on a write attribute map (mutates it).
+ * Same checks run for dry-run and real writes so a disallowed format never
+ * reaches create/update.
+ *
+ * @param {{backend: object, site: object, entityType: string, bundle: string, attributes: object}} input
+ * @returns {Promise<object>} The same attributes object, with formats resolved.
+ */
+export async function applyAllowedFormatsToAttributes({
+  backend, site, entityType, bundle, attributes,
+}) {
+  const names = Object.keys(attributes).filter((name) => !SKIP_FORMAT_FIELDS.has(name));
+  for (const fieldName of names) {
+    const value = new Map(Object.entries(attributes)).get(fieldName);
+    if (value === undefined || value === null) continue;
+    if (typeof value !== "string" && (typeof value !== "object" || Array.isArray(value))) continue;
+
+    const def = await resolveFieldDefinition(backend, site, entityType, bundle, fieldName);
+    const formattedType = Boolean(def?.fieldType && FORMATTED_FIELD_TYPES.has(def.fieldType));
+    const restricted = Boolean(def?.allowedFormats?.length);
+    const isBody = fieldName === "body";
+    const shaped = isFormattedShape(value);
+
+    if (def && !formattedType && !restricted && !isBody) continue;
+    if (!def && !shaped && !isBody) continue;
+
+    const format = resolveTextFormat({
+      fieldName,
+      requested: requestedFormatOf(value),
+      allowedFormats: def ? def.allowedFormats : null,
+      site,
+      defaultWhenUnknown: isBody,
+    });
+
+    if (format === undefined && !formattedType && !isBody && !shaped) continue;
+    Object.assign(attributes, Object.fromEntries([
+      [fieldName, normalizeFormattedValue(value, format)],
+    ]));
+  }
+  return attributes;
+}

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,
   };
 }
 
@@ -754,5 +767,6 @@ export function getSecuritySummary(site) {
     deniedEntityTypes:     cfg.deniedEntityTypes,
     entityRules:           cfg.entityRules,
     globalRedactedFields:  cfg.globalRedactedFields,
+    declaredCeiling:       cfg.declaredCeiling ?? null,
   };
 }