drupal-mcp-connector 2.13.0 → 2.13.1

package/.agents/commands/drupal-entity-update.md

@@ -1,11 +1,11 @@
 ---
-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) against the same URL the write will hit. An addressable working copy is PATCHed via ?resourceVersion=rel:working-copy (#166); a stray revision with no addressable working copy still fails with revision-surgery language (#201). Preflight does not un-orphan paragraphs already created — probe the host before creating dependents."
+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 a non-saving PATCH preflight runs first (including dryRun) against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); a stray revision with no addressable working copy still fails with revision-surgery language (#201). Preflight does not un-orphan paragraphs already created — probe the host before creating dependents."
 argument-hint: "<entityType> <bundle> <id> [site] [attributes] [relationships] [dryRun] [returning]"
 ---
 
 Call the MCP tool `drupal_entity_update`.
 
-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) against the same URL the write will hit. An addressable working copy is PATCHed via ?resourceVersion=rel:working-copy (#166); a stray revision with no addressable working copy still fails with revision-surgery language (#201). Preflight does not un-orphan paragraphs already created — probe the host before creating dependents.
+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 a non-saving PATCH preflight runs first (including dryRun) against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); a stray revision with no addressable working copy still fails with revision-surgery language (#201). Preflight does not un-orphan paragraphs already created — probe the host before creating dependents.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -18,7 +18,7 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `site` (string): 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).
 - `attributes` (object (pass as JSON))
 - `relationships` (object (pass as JSON))
-- `dryRun` (boolean (true/false)): 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, and hits the same URL as the real write (canonical, or ?resourceVersion=rel:working-copy when a draft is addressable). A working-copy 400 fails the dryRun.
+- `dryRun` (boolean (true/false)): Validate, resolve ERR identifiers, and (on moderated targets) run the core PATCH-guard probe against Drupal, then return a preview without the real write. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. Any refusal fails the dryRun.
 - `returning` (string): Response verbosity. "full" (default) returns the complete saved entity; "minimal" returns just identity + state (id, type, bundle, title, status, changed, url) — much smaller, recommended for bulk writes where the echoed body would dominate the response.
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.agents/commands/drupal-update-node.md

@@ -1,11 +1,11 @@
 ---
-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 — against the same URL the write will hit. An addressable working copy is PATCHed via ?resourceVersion=rel:working-copy (#166); dryRun uses that same target. 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."
+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 a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); dryRun uses that same target. 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."
 argument-hint: "<type> <id> [site] [title] [body] [summary] [format] [status] [moderationState] [fields] [relationships] [dryRun] [returning]"
 ---
 
 Call the MCP tool `drupal_update_node`.
 
-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 — against the same URL the write will hit. An addressable working copy is PATCHed via ?resourceVersion=rel:working-copy (#166); dryRun uses that same target. 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.
+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 a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); dryRun uses that same target. 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.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -23,7 +23,7 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `moderationState` (string): 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` (object (pass as JSON)): Scalar/attribute field values keyed by machine name. Formatted text: a string or { value, format?, summary? }. format must be in the field's allowed_formats; a single allowed format is used when omitted. Entity-reference fields go in `relationships`, not here.
 - `relationships` (object (pass as JSON)): 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` (boolean (true/false)): 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, and hits the same URL as the real write (canonical, or ?resourceVersion=rel:working-copy when a draft is addressable). A working-copy 400 fails the dryRun.
+- `dryRun` (boolean (true/false)): Validate, resolve ERR identifiers, and (on moderated targets) run the core PATCH-guard probe against Drupal, then return a preview without the real write. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. Any refusal fails the dryRun.
 - `returning` (string): Response verbosity. "full" (default) returns the complete saved entity; "minimal" returns just identity + state (id, type, bundle, title, status, changed, url) — much smaller, recommended for bulk writes where the echoed body would dominate the response.
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.13.1] - 2026-09-05
+
+### Fixed
+- Existing node drafts use Sentinel's governed draft-continuation endpoint
+  instead of a revision-selected core PATCH, which Drupal rejects (#166).
+  Preflight sends the actual fields and revision preconditions without saving.
+  An unavailable server endpoint fails closed without discarding the draft.
+
+### Changed
+- Comments, test names, lab notes, and older changelog entries now reference
+  GitHub issues, release versions, or plain descriptions instead of internal
+  tracker keys (#258). No behaviour change.
+
 ## [2.13.0] - 2026-09-02
 
 ### Security
@@ -124,7 +137,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   credentials never appear in any frame crossing the tunnel. The lab
   README now states plainly that the lab northbound does not authenticate
   the caller (the lab credential authenticates the agent channel) — the
-  product edge's northbound OAuth is DEV-294 work, not this harness.
+  product edge's northbound OAuth is #232 work, not this harness.
 
 ### Added
 - **Deployment documentation for the relay edge and tenant-agent entry
@@ -149,13 +162,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   window. The frame codec lives at `src/lib/relay/frames.js` with hard size,
   teardown, and timeout bounds. These are entry points and libraries only;
   nothing here is a hosted service.
-- **Lab-only outbound-relay harness (DEV-293).** Isolated under
+- **Lab-only outbound-relay harness.** Isolated under
   `lab/outbound-relay/` with tests in `tests/lab/`. A tenant agent dials out
   to a loopback relay; one MCP 2026-07-28 Streamable-HTTP request (stateless,
   no `Mcp-Session-Id`) reaches an in-process stub private Drupal; reconnect
   keeps the same tunnel identity; revocation is checked per request (next
   request denied, no grace window). This is not a public surface, not a
-  hosted-service claim, and not DEV-294. Hosted MCP is unstarted.
+  hosted-service claim, and not the product edge (#232). Hosted MCP is unstarted.
 
 ## [2.9.0] - 2026-08-26
 
@@ -935,7 +948,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.5.1] - 2026-06-29
 
 ### Fixed
-- **Node URL aliases set via the connector now actually persist (DEV-116).** Setting an
+- **Node URL aliases set via the connector now actually persist.** Setting an
   alias with `drupal_update_node` (`fields.path = { alias, pathauto: 0 }`) returned
   success but silently reverted, causing nav 404s. Root cause: JSON:API deserialized the
   `path` field without the existing alias's **`pid`**, so Drupal's `PathItem::postSave`
@@ -943,7 +956,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   in place. The connector now reads the current alias's `pid` (new
   `backend.getPathInfo`) and round-trips it, so the alias is **updated in place** — one
   canonical alias, no duplicate. Verified end-to-end over JSON:API on Drupal 11.
-- **Path-less updates no longer create duplicate aliases.** The DEV-114 "preserve" path
+- **Path-less updates no longer create duplicate aliases.** The 1.5.0 "preserve" path
   re-pinned the current alias *without* its `pid`, hitting the same duplicate bug; it now
   round-trips the `pid` too.
 - **Honest write responses.** `drupal_create_node` / `drupal_update_node` now **re-read**
@@ -973,29 +986,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - **`drupal_update_paragraph`** — update an existing Paragraph entity's field values
   in place (partial JSON:API PATCH) by bundle + UUID, so component / key-capability
-  paragraphs can be maintained end-to-end without re-embedding (DEV-114).
+  paragraphs can be maintained end-to-end without re-embedding.
 - **`drupal_update_menu_link`** — update a menu link by UUID (rename, re-weight,
   re-target, re-parent, enable/disable). `enabled` is preserved across edits unless
-  passed explicitly (DEV-114).
+  passed explicitly.
 - **`drupal_create_menu_link`** now accepts **`parent`** (nest under a parent link
   plugin id) and **`enabled`** on create, and creates links **enabled by default** so
   they render immediately — closing the "menu links created disabled / no parent on
-  create" gap (DEV-114).
+  create" gap.
 
 ### Fixed
 - **Menu links no longer silently regress to disabled.** Every menu-link write now
   asserts `enabled` explicitly (default true on create; the current value re-pinned on
   update), so an unrelated edit can't drop a live link to disabled through the JSON:API
-  write path (DEV-114).
+  write path.
 - **Node updates preserve the existing URL alias.** When `drupal_update_node` is called
   without a `path`, the connector reads the current alias and re-pins it
   (`{ alias, pathauto: 0 }`) so a save can't let Pathauto revert the alias to a stale
-  value. Pass `fields.path` to set the alias explicitly (DEV-114).
+  value. Pass `fields.path` to set the alias explicitly.
 - **Intermittent `drupal_create_menu_link` 422 "path '/…' is inaccessible".** This is a
   transient path-validator/access-cache race in Drupal's `LinkAccessConstraint`; menu-link
   create/update now retries once after a short delay when it hits that specific error.
   Prefer an `entity:node/<id>` target over `internal:/<alias>` to avoid the alias
-  resolution step entirely (DEV-114).
+  resolution step entirely.
 
 ## [1.4.0] - 2026-06-29
 
@@ -1011,7 +1024,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   its status code via a partial update — the path to activate/fix a redirect that
   isn't firing. Both are governed by the per-site security policy (redirect writes /
   `administer redirects`). Resolves the gap where connector-created redirects were
-  inactive and could not be enabled (DEV-111).
+  inactive and could not be enabled.
 
 ## [1.3.2] - 2026-06-27
 
@@ -1418,6 +1431,7 @@ The connector is now **dual-protocol**: every tool runs against an abstract back
 - User tools gained explicit PII-access assertions.
 - Whole tree lint-clean (`npm run lint`) with object-injection sinks rewritten to safe lookups.
 
+[2.13.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.13.1
 [2.13.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.13.0
 [2.12.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.12.0
 [2.11.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.13.0",
+  "version": "2.13.1",
   "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
   "type": "module",
   "main": "src/index.js",

package/src/lib/backends/backend-interface.js

@@ -78,7 +78,7 @@ export class Backend {
    * Read the raw `path` field (alias/pid/langcode) and internal id of an entity,
    * for callers that must round-trip the alias `pid` on an in-place update (the
    * canonical entity only exposes `path.alias` as `url`). Optional capability:
-   * the default returns nulls so read-only/path-less backends are safe. See DEV-116.
+   * the default returns nulls so read-only/path-less backends are safe. See the 1.5.1 alias fix.
    * @param {{entityType: string, bundle: string, id: string}} _ref
    * @returns {Promise<{alias: ?string, pid: ?(number|string), langcode: ?string, drupalId: ?(number|string)}>}
    */

package/src/lib/backends/jsonapi.js

@@ -137,7 +137,7 @@ function applyFilter(params, { field, op = "eq", value }) {
 /**
  * Bind JSON:API `uid` from the grant-stamped identity. Caller uid is overwritten.
  * User entities are left unchanged. No actor claim (auth.actors not in effect
- * for this principal) leaves relationships as-is — the prior, pre-DEV-123 path.
+ * for this principal) leaves relationships as-is — the path before actor mapping (#247).
  * A *present* actor claim that fails UUID validation fails closed (throws)
  * rather than silently keeping a caller-supplied uid: resolveActor()/
  * normalizeActors() already validate the shape before stamping identity.actor,
@@ -309,7 +309,7 @@ export class JsonApiBackend extends Backend {
    * correct in-place alias *update* must round-trip the existing alias's `pid`
    * (Drupal `PathItem::postSave` creates a duplicate alias when `pid` is absent)
    * — so this method exposes it. Returns nulls for entities/backends without a
-   * path field. See DEV-116.
+   * path field. See the 1.5.1 alias fix.
    * @param {{entityType: string, bundle: string, id: string}} ref
    * @returns {Promise<{alias: ?string, pid: ?(number|string), langcode: ?string, drupalId: ?(number|string)}>}
    */

package/src/lib/draft-write.js

@@ -0,0 +1,57 @@
+/**
+ * Sentinel's governed draft-continuation contract (d.o #3621022).
+ * Core JSON:API revision selectors support reads, not PATCH requests.
+ */
+
+/**
+ * Validate or continue a draft, using the same payload and revision precondition.
+ * No canonical fallback: an absent endpoint or refused precondition stops work.
+ * @param {object} backend JSON:API backend.
+ * @param {object} input Canonical update input plus draftRevision.
+ * @param {boolean} preflight Validate without saving.
+ * @returns {Promise<object>} Preflight metadata or the written canonical entity.
+ */
+export async function writeDraft(backend, input, preflight = false) {
+  const { entityType, bundle, id, attributes = {}, relationships, draftRevision } = input;
+  const live = String(draftRevision?.liveVid ?? "");
+  const working = String(draftRevision?.workingVid ?? "");
+  if (entityType !== "node" || !/^[1-9]\d*$/.test(live)
+    || !/^[1-9]\d*$/.test(working) || live === working) {
+    throw new Error("Draft continuation requires distinct, verified live and working node revision IDs.");
+  }
+  if (typeof backend.rawQuery !== "function" || typeof backend.resourcePath !== "function") {
+    throw new Error("This backend does not support governed draft continuation.");
+  }
+  const data = { type: `${entityType}--${bundle}`, id, attributes };
+  if (relationships) data.relationships = relationships;
+  let result;
+  try {
+    result = await backend.rawQuery({
+      path: `${backend.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}/mcp-draft`,
+      options: {
+        method: "PATCH",
+        headers: {
+          "If-Match": `"${live}:${working}"`,
+          "X-MCP-Draft-Preflight": preflight ? "1" : "0",
+        },
+        body: JSON.stringify({ data }),
+      },
+    });
+  } catch (error) {
+    if (/Drupal (404|405)\b/.test(String(error?.message))) {
+      throw new Error("The site does not provide Sentinel's governed draft endpoint (d.o #3621022). Update the server-side module; the draft was not discarded and no canonical fallback was attempted.", { cause: error });
+    }
+    throw error;
+  }
+  if (preflight) {
+    if (result?.meta?.draft_preflight !== true
+      || String(result.meta.live) !== live || String(result.meta.working) !== working) {
+      throw new Error("The site did not confirm a non-saving draft preflight. Refusing to continue.");
+    }
+    return result;
+  }
+  if (!result?.data || result.data.id !== id || result.data.type !== data.type) {
+    throw new Error("Draft write response did not identify the requested entity. The write outcome is uncertain; re-read before retrying.");
+  }
+  return backend.toCanonical(result.data);
+}

package/src/lib/patch-preflight.js

@@ -12,19 +12,19 @@
  *
  * Two distinct cases share that core 400:
  *
- * - **#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.
+ * - **#166** — `rel:working-copy` resolves. Both preflight and write use
+ *   Sentinel's /mcp-draft endpoint with verified live/working revision IDs.
+ *   Core rejects resourceVersion on PATCH. Never retry the canonical URL.
  * - **#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.
+ * Unsupported endpoints and stale revisions fail closed, without discard.
  */
 
 import { entityLooksModerated, hasExplicitModerationState } from "./moderation-default.js";
 import { entityRevisionId } from "./write-revision.js";
+import { writeDraft } from "./draft-write.js";
 
 /** Stable error code for a core working-copy / not-latest-revision block. */
 export const PATCH_BLOCKED_CODE = "PATCH_BLOCKED";
@@ -59,7 +59,7 @@ export const PATCH_WORKING_COPY_STALE_MESSAGE =
 
 /**
  * Operator message for a core working-copy 400.
- * A resolvable working copy is edited in place (#166) — this message is only
+ * A resolvable working copy gets a new draft revision (#166) — this message is only
  * for the invisible-row case (#201).
  * @returns {string}
  */
@@ -300,11 +300,18 @@ export async function preflightPatchWritable({
  * @returns {Promise<{resourceVersion: ?string, workingCopy: ?object, liveVid: ?number|string, workingVid: ?number|string}>}
  */
 export async function prepareGuardedPatch(backend, {
-  entityType, bundle, id, existing, attributes,
+  entityType, bundle, id, existing, attributes, relationships,
 }) {
   const target = shouldPreflightPatch({ existing, attributes })
     ? await resolveWorkingCopyPatchTarget(backend, { entityType, bundle, id, existing })
     : { resourceVersion: undefined, workingCopy: null, liveVid: null, workingVid: null };
+  if (target.resourceVersion) {
+    target.draftRevision = { liveVid: target.liveVid, workingVid: target.workingVid };
+    await writeDraft(backend, {
+      entityType, bundle, id, attributes, relationships, draftRevision: target.draftRevision,
+    }, true);
+    return target;
+  }
   await preflightPatchWritable({
     backend, entityType, bundle, id, existing, attributes,
     resourceVersion: target.resourceVersion,
@@ -323,6 +330,10 @@ export async function prepareGuardedPatch(backend, {
  */
 export async function updateEntityGuarded(backend, input) {
   try {
+    if (input?.draftRevision) return await writeDraft(backend, input);
+    if (input?.resourceVersion) {
+      throw new Error("Core JSON:API does not support revision-selected PATCH. A governed draft preflight is required.");
+    }
     return await backend.updateEntity(input);
   } catch (err) {
     if (!isWorkingCopyPatchError(err)) throw err;

package/src/lib/policy-enforcement.js

@@ -1,5 +1,5 @@
 /**
- * Tenant-side local policy enforcement (#253 / DEV-125).
+ * Tenant-side local policy enforcement (#253).
  *
  * Loopback stand-in for mcp_sentinel `McpPolicyBundleRegistry`: mint / verify
  * / activate / simulate / revoke / rollback / emergency deny. The relay edge

package/src/lib/policy-promotion.js

@@ -1,5 +1,5 @@
 /**
- * W&L-operated dual-control promotion ledger (#253 / DEV-125).
+ * W&L-operated dual-control promotion ledger (#253).
  *
  * The edge never mints a Sentinel HMAC seal. A promotion is an already-sealed
  * portable document plus two distinct operator ids. Eligibility is the gate

package/src/lib/relay/agent.js

@@ -1,5 +1,5 @@
 /**
- * Relay tenant agent (#232) — the DEV-294 AC4 slice, tenant side.
+ * Relay tenant agent (#232) — the hosted-edge slice, tenant side.
  *
  * Dials OUT to the edge's agent channel and serves the real connector server
  * (`createConnectorServerFactory`) over the framed tunnel. The agent never

package/src/lib/relay/edge.js

@@ -1,8 +1,8 @@
 /**
- * Relay northbound edge (#232, #242, #244, #247, #250, #253, #256) — DEV-294
- * AC4, DEV-122 isolation, DEV-124 tenant routing, DEV-123 actor mapping,
- * DEV-125 policy digest and W&L-operated bundle promotion, DEV-126
- * attributable usage, quotas, and abuse signals.
+ * Relay northbound edge (#232, #242, #244, #247, #250, #253, #256) — the
+ * hosted-edge slice (#232), tenant isolation (#242), tenant routing (#244),
+ * actor mapping (#247), policy digest (#250) and W&L-operated bundle
+ * promotion (#253), attributable usage, quotas, and abuse signals (#256).
  *
  * Terminates northbound MCP over the OAuth resource server and fans requests
  * down outbound tenant-agent channels. The edge proposes; the tenant-side
@@ -23,7 +23,7 @@
  *     `agentId`; channel records may bind `sites`. A second unscoped agent
  *     or overlapping site claim is denied at hello. Fan-down selects the
  *     unique bound agent from server-owned grants. Single unscoped agent
- *     remains the DEV-294 compatibility path.
+ *     remains the #232 single-agent compatibility path.
  *   - Stateless MCP 2026-07-28 northbound: sessionful traffic is refused and
  *     no `Mcp-Session-Id` crosses in either direction.
  *   - Revocation is per-request with no grace window, for both credential
@@ -74,7 +74,7 @@ import {
 export const EDGE_MCP_PROTOCOL = "2026-07-28";
 
 /**
- * Revocation bound restated from the DEV-293 lab for both credential kinds.
+ * Revocation bound restated from the outbound-relay lab for both credential kinds.
  * The next request after revoke is denied; an in-flight request may finish.
  */
 export const EDGE_REVOCATION_BOUND = Object.freeze({
@@ -122,7 +122,7 @@ const SHARED_SCOPES = new Set(["tenant", "config"]);
 
 /**
  * Normalize a channel-record `sites` list. Empty / missing means unscoped
- * (legal only as the sole connected agent — the DEV-294 compatibility path).
+ * (legal only as the sole connected agent — the #232 compatibility path).
  *
  * @param {unknown} sites
  * @returns {string[]}
@@ -228,7 +228,7 @@ export function selectTenantSession({
  * Resolve tenant and target from server-owned grants. Caller `tenant` is a
  * confirming hint inside the grant, never authority. When `tenantGrants` is
  * omitted, tenant is derived from the unique agent covering the site grant
- * (DEV-122 / DEV-294 compatibility).
+ * (#242 / #232 compatibility).
  *
  * @param {object} params
  * @param {object|null} params.identity

package/src/lib/relay/frames.js

@@ -2,7 +2,7 @@
  * Relay frame codec (#232).
  *
  * Length-prefixed JSON frames for the edge/agent channel, promoted from the
- * DEV-293 lab harness (`lab/outbound-relay/harness.js`). Mechanism only — no
+ * outbound-relay lab harness (`lab/outbound-relay/harness.js`). Mechanism only — no
  * authentication, entitlement, or header policy lives here.
  *
  * Wire format: 4-byte big-endian payload length, then UTF-8 JSON. A frame

package/src/lib/usage.js

@@ -1,6 +1,5 @@
 /**
- * Attributable usage, quotas, and abuse signals on the relay edge (#256 /
- * DEV-126).
+ * Attributable usage, quotas, and abuse signals on the relay edge (#256).
  *
  * Metering at the seam, lab bounds. Every edge decision (allow or deny) and
  * every fan-down receipt is a record keyed by the grant-resolved tenant and

package/src/tools/bulk.js

@@ -119,13 +119,14 @@ async function bulkUpdate({ site: siteName, entityType, bundle, items = [] }) {
       assertPublishAllowed(sec, attributes);
       const resolvedRelationships = await resolveErrRelationships(backend, item.relationships ?? {});
       const patchTarget = await prepareGuardedPatch(backend, {
-        entityType, bundle, id: item.id, existing, attributes,
+        entityType, bundle, id: item.id, existing, attributes, relationships: resolvedRelationships,
       });
       const entity = await updateEntityGuarded(backend, {
         entityType, bundle, id: item.id,
         attributes,
         relationships: resolvedRelationships,
         ...(patchTarget.resourceVersion ? { resourceVersion: patchTarget.resourceVersion } : {}),
+        ...(patchTarget.draftRevision ? { draftRevision: patchTarget.draftRevision } : {}),
       });
       updated += 1;
       results.push({ index, success: true, id: entity?.id ?? item.id });

package/src/tools/entities.js

@@ -118,7 +118,7 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
   assertPublishAllowed(sec, safeAttributes);
   const resolvedRelationships = await resolveErrRelationships(backend, relationships);
   const patchTarget = await prepareGuardedPatch(backend, {
-    entityType, bundle, id, existing, attributes: safeAttributes,
+    entityType, bundle, id, existing, attributes: safeAttributes, relationships: resolvedRelationships,
   });
   if (dryRun) {
     return {
@@ -129,6 +129,7 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
   const result = await updateEntityGuarded(backend, {
     entityType, bundle, id, attributes: safeAttributes, relationships: resolvedRelationships,
     ...(patchTarget.resourceVersion ? { resourceVersion: patchTarget.resourceVersion } : {}),
+    ...(patchTarget.draftRevision ? { draftRevision: patchTarget.draftRevision } : {}),
   });
   const written = await readWrittenRevision({
     backend, entityType, bundle, id,
@@ -280,7 +281,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). 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) against the same URL the write will hit. An addressable working copy is PATCHed via ?resourceVersion=rel:working-copy (#166); a stray revision with no addressable working copy still fails with revision-surgery language (#201). Preflight does not un-orphan paragraphs already created — probe the host before creating dependents.",
+    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 a non-saving PATCH preflight runs first (including dryRun) against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); a stray revision with no addressable working copy still fails with revision-surgery language (#201). Preflight does not un-orphan paragraphs already created — probe the host before creating dependents.",
     inputSchema: {
       type: "object", required: ["entityType", "bundle", "id"],
       properties: {
@@ -290,7 +291,7 @@ export const definitions = [
         id:            { type: "string" },
         attributes:    { type: "object" },
         relationships: { type: "object" },
-        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, and hits the same URL as the real write (canonical, or ?resourceVersion=rel:working-copy when a draft is addressable). A working-copy 400 fails the dryRun." },
+        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. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. Any refusal fails the dryRun." },
         returning:     RETURNING_SCHEMA,
       },
     },

package/src/tools/nodes.js

@@ -44,11 +44,11 @@ function normalizeAlias(value) {
  * Resolve the `path` attribute to send on an alias-aware node write so the alias
  * actually persists, and decide whether a rename redirect is needed.
  *
- * The bug (DEV-116): JSON:API deserializes `{ alias, pathauto }` onto the node's
+ * The bug (fixed in 1.5.1): JSON:API deserializes `{ alias, pathauto }` onto the node's
  * `path` field, dropping the existing alias's `pid`; Drupal's `PathItem::postSave`
  * then *creates a duplicate* `path_alias` (the older one stays canonical) instead
  * of updating in place. The fix is to round-trip the existing `pid` so the update
- * is in place. DEV-114's path-omitted "preserve" had the same defect (no `pid`),
+ * is in place. The 1.5.0 path-omitted "preserve" had the same defect (no `pid`),
  * so it is fixed here too.
  *
  * @param {object} args - { backend, type, id, providedPath, isCreate }.
@@ -274,7 +274,7 @@ async function createNode({ site: siteName, type, title, body, summary, format,
     return summaryWrite.deprecated && bodyAttr ? attachSummaryDeprecation(preview) : preview;
   }
   // Alias handling: an explicit `path.alias` is set as a manual alias; otherwise
-  // `path` is omitted so pathauto generates the alias (DEV-116).
+  // `path` is omitted so pathauto generates the alias (see the 1.5.1 alias fix).
   const { pathAttr } = await resolvePathWrite({ backend, type, id: null, providedPath: attributes.path, isCreate: true });
   if (pathAttr === undefined) delete attributes.path;
   else attributes.path = pathAttr;
@@ -344,11 +344,10 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
   // #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 / #166: probe the same URL the write will hit. An addressable
-  // working copy is PATCHed via rel:working-copy; a stray revision still
-  // fails the probe with revision-surgery language.
+  // #201 / #166: probe the write endpoint. Addressable drafts use Sentinel's
+  // governed continuation endpoint; stray revisions still fail the probe.
   const patchTarget = await prepareGuardedPatch(backend, {
-    entityType: "node", bundle: type, id, existing, attributes,
+    entityType: "node", bundle: type, id, existing, attributes, relationships: resolvedRelationships,
   });
   if (dryRun) {
     const preview = {
@@ -357,7 +356,7 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
     };
     return summaryWrite.deprecated && bodyAttr ? attachSummaryDeprecation(preview) : preview;
   }
-  // Alias handling (DEV-116): an explicit `path.alias` is set in place by
+  // Alias handling (1.5.1 alias fix): 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
   // it. A rename (alias changed) also gets a 301 redirect from the old path.
@@ -367,6 +366,7 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
   const patched = await updateEntityGuarded(backend, {
     entityType: "node", bundle: type, id, attributes, relationships: resolvedRelationships,
     ...(patchTarget.resourceVersion ? { resourceVersion: patchTarget.resourceVersion } : {}),
+    ...(patchTarget.draftRevision ? { draftRevision: patchTarget.draftRevision } : {}),
   });
   const redirectResult = redirect ? await createRenameRedirect(backend, sec, redirect) : null;
   // #169: when relationships were sent, the canonical re-read is the published
@@ -477,7 +477,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`. 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 — against the same URL the write will hit. An addressable working copy is PATCHed via ?resourceVersion=rel:working-copy (#166); dryRun uses that same target. 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.",
+    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 a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); dryRun uses that same target. 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: {
@@ -492,7 +492,7 @@ export const definitions = [
         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. Formatted text: a string or { value, format?, summary? }. format must be in the field's allowed_formats; a single allowed format is used when omitted. 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 }, …] }. 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, and hits the same URL as the real write (canonical, or ?resourceVersion=rel:working-copy when a draft is addressable). A working-copy 400 fails the dryRun." },
+        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. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. Any refusal fails the dryRun." },
         returning: RETURNING_SCHEMA,
       },
     },