docs(document-api): soften metadata.remove atomicity wording + add story (SD-3104)

The metadata.remove contract claimed 'both succeed or neither does,' but
the adapter writes to two separate state systems (ProseMirror doc + OOXML
package) with no shared commit primitive. The adapter resolves the target
up-front so the common failure mode lands before any state change, but a
crash strictly between the two writes can leave a dangling payload.
Wording now reflects that.

Also adds tests/doc-api-stories/tests/metadata/all-commands.ts: a real
Editor + DOCX round-trip story covering attach / list / get / resolve /
update / remove. Goes through the SDK + CLI like the rest of the doc-api
stories. Catches the gap that smoke unit tests cannot: that the adapter
actually wraps a text range, writes the payload, and resolves the anchor
back to a SelectionTarget on a live editor.

Author: caio-pizzol

apps/docs/document-api/reference/_generated-manifest.json

@@ -1077,5 +1077,5 @@
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "c071807d15c2622572bb4828f566d9480d3a62698ad30f08341aeb9b4f15df1e"
+  "sourceHash": "97cf1fa7f05b40382d9839c0b60c7b97ccb7fddec642bc62383946ca76a75ee8"
 }

apps/docs/document-api/reference/index.mdx

@@ -641,5 +641,5 @@ The tables below are grouped by namespace.
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/metadata/list"><code>metadata.list</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.metadata.list(...)</code></span> | List anchored-metadata entries in the document, optionally filtered by consumer namespace and/or a `within` selection (returns only entries whose anchor overlaps `within`). |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/metadata/get"><code>metadata.get</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.metadata.get(...)</code></span> | Get a single anchored-metadata entry by id, including its JSON payload. |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/metadata/update"><code>metadata.update</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.metadata.update(...)</code></span> | Replace the JSON payload of an existing anchored-metadata entry. Replace semantics; no merge. The anchor is left untouched. |
-| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/metadata/remove"><code>metadata.remove</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.metadata.remove(...)</code></span> | Atomically remove an anchored-metadata entry. Strips the anchor SDT wrapper (its content stays in the document) and deletes the payload entry from the Storage Part; both succeed or neither does. When the backing part has no remaining entries, the part itself is removed. |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/metadata/remove"><code>metadata.remove</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.metadata.remove(...)</code></span> | Remove an anchored-metadata entry. Strips the anchor content-control wrapper (its content stays in the document) and deletes the payload entry from the Storage Part. In v1 these writes are sequenced, not transactional: the adapter resolves the target up-front so missing-target failures land before any state change, but a crash strictly between the two writes can leave a dangling payload. When the backing part has no remaining entries, the part itself is removed. |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/metadata/resolve"><code>metadata.resolve</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.metadata.resolve(...)</code></span> | Find where an anchored-metadata entry is anchored in the document. Returns the SelectionTarget covering the anchor content. |

apps/docs/document-api/reference/metadata/remove.mdx

@@ -1,14 +1,14 @@
 ---
 title: metadata.remove
 sidebarTitle: metadata.remove
-description: Atomically remove an anchored-metadata entry. Strips the anchor SDT wrapper (its content stays in the document) and deletes the payload entry from the Storage Part; both succeed or neither does. When the backing part has no remaining entries, the part itself is removed.
+description: "Remove an anchored-metadata entry. Strips the anchor content-control wrapper (its content stays in the document) and deletes the payload entry from the Storage Part. In v1 these writes are sequenced, not transactional: the adapter resolves the target up-front so missing-target failures land before any state change, but a crash strictly between the two writes can leave a dangling payload. When the backing part has no remaining entries, the part itself is removed."
 ---
 
 {/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}
 
 ## Summary
 
-Atomically remove an anchored-metadata entry. Strips the anchor SDT wrapper (its content stays in the document) and deletes the payload entry from the Storage Part; both succeed or neither does. When the backing part has no remaining entries, the part itself is removed.
+Remove an anchored-metadata entry. Strips the anchor content-control wrapper (its content stays in the document) and deletes the payload entry from the Storage Part. In v1 these writes are sequenced, not transactional: the adapter resolves the target up-front so missing-target failures land before any state change, but a crash strictly between the two writes can leave a dangling payload. When the backing part has no remaining entries, the part itself is removed.
 
 - Operation ID: `metadata.remove`
 - API member path: `editor.doc.metadata.remove(...)`

apps/docs/document-engine/sdks.mdx

@@ -737,7 +737,7 @@ The SDKs expose all operations from the [Document API](/document-api/overview) p
 | `doc.metadata.list` | `metadata list` | List anchored-metadata entries in the document, optionally filtered by consumer namespace and/or a `within` selection (returns only entries whose anchor overlaps `within`). |
 | `doc.metadata.get` | `metadata get` | Get a single anchored-metadata entry by id, including its JSON payload. |
 | `doc.metadata.update` | `metadata update` | Replace the JSON payload of an existing anchored-metadata entry. Replace semantics; no merge. The anchor is left untouched. |
-| `doc.metadata.remove` | `metadata remove` | Atomically remove an anchored-metadata entry. Strips the anchor SDT wrapper (its content stays in the document) and deletes the payload entry from the Storage Part; both succeed or neither does. When the backing part has no remaining entries, the part itself is removed. |
+| `doc.metadata.remove` | `metadata remove` | Remove an anchored-metadata entry. Strips the anchor content-control wrapper (its content stays in the document) and deletes the payload entry from the Storage Part. In v1 these writes are sequenced, not transactional: the adapter resolves the target up-front so missing-target failures land before any state change, but a crash strictly between the two writes can leave a dangling payload. When the backing part has no remaining entries, the part itself is removed. |
 | `doc.metadata.resolve` | `metadata resolve` | Find where an anchored-metadata entry is anchored in the document. Returns the SelectionTarget covering the anchor content. |
 | `doc.insertTab` | `insert tab` | Insert a real Word tab node at a collapsed text insertion point. Accepts the same target/ref shortcuts as insert, but only for point inserts. |
 | `doc.insertLineBreak` | `insert line-break` | Insert a real Word line-break node at a collapsed text insertion point. Accepts the same target/ref shortcuts as insert, but only for point inserts. |
@@ -1215,7 +1215,7 @@ The SDKs expose all operations from the [Document API](/document-api/overview) p
 | `doc.metadata.list` | `metadata list` | List anchored-metadata entries in the document, optionally filtered by consumer namespace and/or a `within` selection (returns only entries whose anchor overlaps `within`). |
 | `doc.metadata.get` | `metadata get` | Get a single anchored-metadata entry by id, including its JSON payload. |
 | `doc.metadata.update` | `metadata update` | Replace the JSON payload of an existing anchored-metadata entry. Replace semantics; no merge. The anchor is left untouched. |
-| `doc.metadata.remove` | `metadata remove` | Atomically remove an anchored-metadata entry. Strips the anchor SDT wrapper (its content stays in the document) and deletes the payload entry from the Storage Part; both succeed or neither does. When the backing part has no remaining entries, the part itself is removed. |
+| `doc.metadata.remove` | `metadata remove` | Remove an anchored-metadata entry. Strips the anchor content-control wrapper (its content stays in the document) and deletes the payload entry from the Storage Part. In v1 these writes are sequenced, not transactional: the adapter resolves the target up-front so missing-target failures land before any state change, but a crash strictly between the two writes can leave a dangling payload. When the backing part has no remaining entries, the part itself is removed. |
 | `doc.metadata.resolve` | `metadata resolve` | Find where an anchored-metadata entry is anchored in the document. Returns the SelectionTarget covering the anchor content. |
 | `doc.insert_tab` | `insert tab` | Insert a real Word tab node at a collapsed text insertion point. Accepts the same target/ref shortcuts as insert, but only for point inserts. |
 | `doc.insert_line_break` | `insert line-break` | Insert a real Word line-break node at a collapsed text insertion point. Accepts the same target/ref shortcuts as insert, but only for point inserts. |

packages/document-api/src/contract/operation-definitions.ts

@@ -6411,7 +6411,7 @@ export const OPERATION_DEFINITIONS = {
   'metadata.remove': {
     memberPath: 'metadata.remove',
     description:
-      'Atomically remove an anchored-metadata entry. Strips the anchor SDT wrapper (its content stays in the document) and deletes the payload entry from the Storage Part; both succeed or neither does. When the backing part has no remaining entries, the part itself is removed.',
+      'Remove an anchored-metadata entry. Strips the anchor content-control wrapper (its content stays in the document) and deletes the payload entry from the Storage Part. In v1 these writes are sequenced, not transactional: the adapter resolves the target up-front so missing-target failures land before any state change, but a crash strictly between the two writes can leave a dangling payload. When the backing part has no remaining entries, the part itself is removed.',
     expectedResult: 'Returns an AnchoredMetadataMutationResult with the removed entry id on success or a failure.',
     requiresDocumentContext: true,
     metadata: mutationOperation({

packages/document-api/src/metadata/anchored-metadata.types.ts

@@ -203,11 +203,21 @@ export interface AnchoredMetadataAttachSuccess {
 export type AnchoredMetadataAttachResult = AnchoredMetadataAttachSuccess | AdapterMutationFailure;
 
 /**
- * Successful mutation outcome for update / remove. `remove` is atomic:
- * both the anchor SDT (wrapper only — content stays in the document) and
- * the payload entry are removed in a single mutation; no dangling state.
- * When the backing Storage Part has no remaining entries, the part itself
- * is removed.
+ * Successful mutation outcome for update / remove.
+ *
+ * `remove` strips both the anchor content control (wrapper only, content
+ * stays in the document) and the payload entry, in that order. When the
+ * backing Storage Part has no remaining entries, the part itself is
+ * removed.
+ *
+ * In v1 these writes are sequenced, not transactional. The anchor lives
+ * in ProseMirror doc state and the payload lives in the OOXML package:
+ * two different state systems with no shared commit primitive. The
+ * adapter resolves the target up-front so the common failure mode
+ * (`TARGET_NOT_FOUND`) fails before any state change, but a crash
+ * strictly between the PM dispatch and the customXml write can leave a
+ * dangling payload entry. A future revision may add cross-state
+ * compensation.
  */
 export interface AnchoredMetadataMutationSuccess {
   success: true;