fix(super-editor): throw REVISION_MISMATCH on metadata dry-run (SD-3104)

Follow-up on the previous dry-run fix. Returning a structured
{ success: false, failure: { code: 'REVISION_MISMATCH' } } on the
attach/remove dry-run paths was shape-inconsistent: the live paths and
the metadata.update dry-run all reach checkRevision via
executeDomainCommand or executeOutOfBandMutation, both of which throw
PlanError. A consumer wrapping these calls in one try/catch couldn't
treat the two failure modes uniformly.

Calls checkRevision directly in the attach + remove dry-run early-return
paths so they throw on stale revisions, matching every other path. Drops
the local REVISION_MISMATCH from the FailureCode union and the
revisionMismatchFailure helper. Updates the two new unit tests to assert
the throw.

Also declares REVISION_MISMATCH on metadata.attach/update/remove throws
arrays in operation-definitions, which the contract was missing.

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": "97cf1fa7f05b40382d9839c0b60c7b97ccb7fddec642bc62383946ca76a75ee8"
+  "sourceHash": "30a98282620ba67a1197b0a2e228c6dd7203c4692c0ca15e56528855f02f38d1"
 }

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

@@ -95,6 +95,7 @@ Returns an AnchoredMetadataAttachResult with the assigned id and the backing Sto
 - `INVALID_TARGET`
 - `INVALID_INPUT`
 - `CAPABILITY_UNAVAILABLE`
+- `REVISION_MISMATCH`
 
 ## Non-applied failure codes
 

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

@@ -69,6 +69,7 @@ Returns an AnchoredMetadataMutationResult with the removed entry id on success o
 - `TARGET_NOT_FOUND`
 - `INVALID_TARGET`
 - `CAPABILITY_UNAVAILABLE`
+- `REVISION_MISMATCH`
 
 ## Non-applied failure codes
 

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

@@ -72,6 +72,7 @@ Returns an AnchoredMetadataMutationResult with the entry id on success or a fail
 - `INVALID_TARGET`
 - `INVALID_INPUT`
 - `CAPABILITY_UNAVAILABLE`
+- `REVISION_MISMATCH`
 
 ## Non-applied failure codes
 

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

@@ -6363,7 +6363,7 @@ export const OPERATION_DEFINITIONS = {
       supportsDryRun: true,
       supportsTrackedMode: false,
       possibleFailureCodes: ['TARGET_NOT_FOUND', 'INVALID_TARGET', 'INVALID_INPUT'],
-      throws: T_REF_INSERT,
+      throws: [...T_REF_INSERT, 'REVISION_MISMATCH'],
     }),
     referenceDocPath: 'metadata/attach.mdx',
     referenceGroup: 'metadata',
@@ -6403,7 +6403,7 @@ export const OPERATION_DEFINITIONS = {
       supportsDryRun: true,
       supportsTrackedMode: false,
       possibleFailureCodes: ['TARGET_NOT_FOUND', 'INVALID_INPUT'],
-      throws: T_REF_MUTATION,
+      throws: [...T_REF_MUTATION, 'REVISION_MISMATCH'],
     }),
     referenceDocPath: 'metadata/update.mdx',
     referenceGroup: 'metadata',
@@ -6419,7 +6419,7 @@ export const OPERATION_DEFINITIONS = {
       supportsDryRun: true,
       supportsTrackedMode: false,
       possibleFailureCodes: ['TARGET_NOT_FOUND'],
-      throws: T_REF_MUTATION_REMOVE,
+      throws: [...T_REF_MUTATION_REMOVE, 'REVISION_MISMATCH'],
     }),
     referenceDocPath: 'metadata/remove.mdx',
     referenceGroup: 'metadata',

packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/anchored-metadata-wrappers.test.ts

@@ -232,23 +232,22 @@ describe('anchored metadata wrappers', () => {
     expect(metadataListWrapper(editor).total).toBe(0);
   });
 
-  it('attach dry-run reports REVISION_MISMATCH when expectedRevision is stale', () => {
+  it('attach dry-run throws REVISION_MISMATCH when expectedRevision is stale', () => {
     const editor = makeEditor();
 
-    const result = metadataAttachWrapper(
-      editor,
-      { id: 'stale-attach', target: TARGET, namespace: 'urn:test:metadata', payload: { label: 'Preview' } },
-      { changeMode: 'direct', dryRun: true, expectedRevision: 'stale-1' },
-    );
-
-    expect(result).toMatchObject({
-      success: false,
-      failure: { code: 'REVISION_MISMATCH' },
-    });
+    // Live attach throws via executeDomainCommand -> checkRevision; dry-run
+    // must match that shape so consumers can use one try/catch path.
+    expect(() =>
+      metadataAttachWrapper(
+        editor,
+        { id: 'stale-attach', target: TARGET, namespace: 'urn:test:metadata', payload: { label: 'Preview' } },
+        { changeMode: 'direct', dryRun: true, expectedRevision: 'stale-1' },
+      ),
+    ).toThrow(/REVISION_MISMATCH/);
     expect(metadataListWrapper(editor).total).toBe(0);
   });
 
-  it('remove dry-run reports REVISION_MISMATCH when expectedRevision is stale', () => {
+  it('remove dry-run throws REVISION_MISMATCH when expectedRevision is stale', () => {
     const editor = makeEditor();
 
     // Seed an entry so remove finds something to act on; without this it
@@ -259,17 +258,14 @@ describe('anchored metadata wrappers', () => {
       { changeMode: 'direct' },
     );
 
-    const result = metadataRemoveWrapper(
-      editor,
-      { id: 'seed' },
-      { changeMode: 'direct', dryRun: true, expectedRevision: 'stale-1' },
-    );
-
-    expect(result).toMatchObject({
-      success: false,
-      failure: { code: 'REVISION_MISMATCH' },
-    });
-    // The seeded entry remains intact — dry-run with stale revision must not mutate.
+    expect(() =>
+      metadataRemoveWrapper(
+        editor,
+        { id: 'seed' },
+        { changeMode: 'direct', dryRun: true, expectedRevision: 'stale-1' },
+      ),
+    ).toThrow(/REVISION_MISMATCH/);
+    // The seeded entry remains intact: dry-run with stale revision must not mutate.
     expect(metadataGetWrapper(editor, { id: 'seed' })?.payload).toEqual({ v: 1 });
   });
 

packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/anchored-metadata-wrappers.ts

@@ -39,7 +39,7 @@ import { paginate } from '../helpers/adapter-utils.js';
 import { findAllSdtNodes, SDT_INLINE_NAME } from '../helpers/content-controls/index.js';
 import { executeOutOfBandMutation } from '../out-of-band-mutation.js';
 import { executeDomainCommand } from './plan-wrappers.js';
-import { getRevision } from './revision-tracker.js';
+import { checkRevision, getRevision } from './revision-tracker.js';
 
 type XmlNode = {
   type?: string;
@@ -69,7 +69,7 @@ type MetadataPart = {
   entries: MetadataEntry[];
 };
 
-type FailureCode = 'INVALID_INPUT' | 'INVALID_TARGET' | 'TARGET_NOT_FOUND' | 'REVISION_MISMATCH';
+type FailureCode = 'INVALID_INPUT' | 'INVALID_TARGET' | 'TARGET_NOT_FOUND';
 
 type FailureResult = {
   success: false;
@@ -80,24 +80,6 @@ function failure(code: FailureCode, message: string): FailureResult {
   return { success: false, failure: { code, message } };
 }
 
-/**
- * Dry-run paths take an early-return shortcut and don't go through
- * `executeOutOfBandMutation` / `executeDomainCommand`, which means they
- * also skip the revision guard those helpers run. Mirror the guard here
- * so optimistic-concurrency previews stay honest: `dryRun: true` with a
- * stale `expectedRevision` must report `REVISION_MISMATCH`, same as the
- * real path would.
- */
-function revisionMismatchFailure(editor: Editor, expectedRevision: string | undefined): FailureResult | null {
-  if (expectedRevision === undefined) return null;
-  const current = getRevision(editor);
-  if (expectedRevision === current) return null;
-  return failure(
-    'REVISION_MISMATCH',
-    `Expected revision "${expectedRevision}" but document is at "${current}". Re-run query.match() to obtain a fresh ref.`,
-  );
-}
-
 function getConverter(editor: Editor): ConverterWithConvertedXml | null {
   return (editor as unknown as { converter?: ConverterWithConvertedXml }).converter ?? null;
 }
@@ -481,8 +463,10 @@ export function metadataAttachWrapper(
 
   const preview = writeEntry(editor, input.namespace, id, input.payload, true);
   if (options?.dryRun) {
-    const stale = revisionMismatchFailure(editor, options.expectedRevision);
-    if (stale) return stale;
+    // Mirror the revision guard that the live path runs inside
+    // executeDomainCommand, so previews against stale revisions throw
+    // REVISION_MISMATCH instead of falsely reporting success.
+    checkRevision(editor, options.expectedRevision);
     return { success: true, id, namespace: input.namespace, partName: preview.partName };
   }
 
@@ -540,8 +524,9 @@ export function metadataRemoveWrapper(
   }
 
   if (options?.dryRun) {
-    const stale = revisionMismatchFailure(editor, options.expectedRevision);
-    if (stale) return stale;
+    // Same revision guard as the live executeOutOfBandMutation /
+    // executeDomainCommand paths. Throws PlanError(REVISION_MISMATCH).
+    checkRevision(editor, options.expectedRevision);
     return { success: true, id: input.id };
   }