feat(document-api): add plan-based mutation engine with query.match and style capture

apps/cli/scripts/export-sdk-contract.ts

@@ -89,6 +89,9 @@ const INTENT_NAMES = {
   'doc.trackChanges.reject': 'reject_tracked_change',
   'doc.trackChanges.acceptAll': 'accept_all_tracked_changes',
   'doc.trackChanges.rejectAll': 'reject_all_tracked_changes',
+  'doc.query.match': 'query_match',
+  'doc.mutations.preview': 'preview_mutations',
+  'doc.mutations.apply': 'apply_mutations',
 } as const satisfies Record<DocBackedCliOpId, string>;
 
 // ---------------------------------------------------------------------------

apps/cli/src/__tests__/conformance/scenarios.ts

@@ -253,6 +253,94 @@ export const SUCCESS_SCENARIOS = {
     const docPath = await harness.copyFixtureDoc('doc-get-text');
     return { stateDir, args: ['get-text', docPath] };
   },
+  'doc.query.match': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-query-match-success');
+    const docPath = await harness.copyFixtureDoc('doc-query-match');
+    return {
+      stateDir,
+      args: [
+        'query',
+        'match',
+        docPath,
+        '--select-json',
+        JSON.stringify({ type: 'node', nodeType: 'paragraph' }),
+        '--require',
+        'any',
+        '--limit',
+        '1',
+      ],
+    };
+  },
+  'doc.mutations.preview': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-mutations-preview-success');
+    const docPath = await harness.copyFixtureDoc('doc-mutations-preview');
+    const steps = [
+      {
+        id: 'preview-insert',
+        op: 'text.insert',
+        where: {
+          by: 'select',
+          select: { type: 'node', nodeType: 'paragraph' },
+          require: 'first',
+        },
+        args: {
+          position: 'before',
+          content: { text: 'PREVIEW_MUTATION_TOKEN' },
+        },
+      },
+    ];
+    return {
+      stateDir,
+      args: [
+        'mutations',
+        'preview',
+        docPath,
+        '--expected-revision',
+        '0',
+        '--atomic-json',
+        'true',
+        '--change-mode',
+        'direct',
+        '--steps-json',
+        JSON.stringify(steps),
+      ],
+    };
+  },
+  'doc.mutations.apply': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-mutations-apply-success');
+    const docPath = await harness.copyFixtureDoc('doc-mutations-apply');
+    const steps = [
+      {
+        id: 'apply-insert',
+        op: 'text.insert',
+        where: {
+          by: 'select',
+          select: { type: 'node', nodeType: 'paragraph' },
+          require: 'first',
+        },
+        args: {
+          position: 'before',
+          content: { text: 'APPLY_MUTATION_TOKEN' },
+        },
+      },
+    ];
+    return {
+      stateDir,
+      args: [
+        'mutations',
+        'apply',
+        docPath,
+        '--atomic-json',
+        'true',
+        '--change-mode',
+        'direct',
+        '--steps-json',
+        JSON.stringify(steps),
+        '--out',
+        harness.createOutputPath('doc-mutations-apply-output'),
+      ],
+    };
+  },
   'doc.capabilities.get': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
     const stateDir = await harness.createStateDir('doc-capabilities-get-success');
     await harness.openSessionFixture(stateDir, 'doc-capabilities-get', 'capabilities-session');

apps/cli/src/cli/operation-params.ts

@@ -267,6 +267,23 @@ const PARAM_FLAG_OVERRIDES: Partial<Record<string, Record<string, { name?: strin
   },
 };
 
+// ---------------------------------------------------------------------------
+// Per-operation param schema overrides
+//
+// Some contract schemas intentionally use broad placeholders (for example,
+// mutation-step arrays represented as { type: 'object' }). Validate these
+// payloads as generic JSON to avoid over-constraining CLI flags.
+// ---------------------------------------------------------------------------
+
+const PARAM_SCHEMA_OVERRIDES: Partial<Record<string, Record<string, CliTypeSpec>>> = {
+  'doc.mutations.preview': {
+    steps: { type: 'json' },
+  },
+  'doc.mutations.apply': {
+    steps: { type: 'json' },
+  },
+};
+
 // ---------------------------------------------------------------------------
 // Schema-derived param exclusions
 //
@@ -453,6 +470,7 @@ function buildDocBackedMetadata(): Record<DocBackedCliOpId, CliOperationMetadata
 
     // Apply flag overrides and exclusions to schema params before merging
     const overrides = PARAM_FLAG_OVERRIDES[cliOpId];
+    const schemaOverrides = PARAM_SCHEMA_OVERRIDES[cliOpId];
     const exclusions = PARAM_EXCLUSIONS[cliOpId];
     for (const param of schemaParams) {
       if (exclusions?.has(param.name)) continue;
@@ -461,6 +479,9 @@ function buildDocBackedMetadata(): Record<DocBackedCliOpId, CliOperationMetadata
         if (override.name) param.name = override.name;
         if (override.flag) param.flag = override.flag;
       }
+      if (schemaOverrides?.[param.name]) {
+        param.schema = schemaOverrides[param.name];
+      }
       if (seenNames.has(param.name)) continue;
       seenNames.add(param.name);
       mergedParams.push(param);

apps/cli/src/cli/operation-set.ts

@@ -90,7 +90,7 @@ function deriveCategoryFromDocApi(docApiId: OperationId): CliCategory {
   const group = REFERENCE_GROUP_BY_OP.get(docApiId);
   if (!group) return 'query';
 
-  if (group === 'core') {
+  if (group === 'core' || group === 'mutations') {
     return COMMAND_CATALOG[docApiId].mutates ? 'mutation' : 'query';
   }
 

apps/docs/document-api/overview.mdx

@@ -36,6 +36,8 @@ Use the tables below to see what operations are available and where each one is
 | Lists | 8 | [Reference](/document-api/reference/lists/index) |
 | Comments | 11 | [Reference](/document-api/reference/comments/index) |
 | Track Changes | 6 | [Reference](/document-api/reference/track-changes/index) |
+| Query | 1 | [Reference](/document-api/reference/query/index) |
+| Mutations | 2 | [Reference](/document-api/reference/mutations/index) |
 
 | Editor method | Operation ID |
 | --- | --- |
@@ -78,6 +80,9 @@ Use the tables below to see what operations are available and where each one is
 | `editor.doc.trackChanges.reject(...)` | [`trackChanges.reject`](/document-api/reference/track-changes/reject) |
 | `editor.doc.trackChanges.acceptAll(...)` | [`trackChanges.acceptAll`](/document-api/reference/track-changes/accept-all) |
 | `editor.doc.trackChanges.rejectAll(...)` | [`trackChanges.rejectAll`](/document-api/reference/track-changes/reject-all) |
+| `editor.doc.query.match(...)` | [`query.match`](/document-api/reference/query/match) |
+| `editor.doc.mutations.preview(...)` | [`mutations.preview`](/document-api/reference/mutations/preview) |
+| `editor.doc.mutations.apply(...)` | [`mutations.apply`](/document-api/reference/mutations/apply) |
 | `editor.doc.capabilities()` | [`capabilities.get`](/document-api/reference/capabilities/get) |
 {/* DOC_API_OPERATIONS_END */}
 

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

@@ -41,6 +41,11 @@
     "apps/docs/document-api/reference/lists/outdent.mdx",
     "apps/docs/document-api/reference/lists/restart.mdx",
     "apps/docs/document-api/reference/lists/set-type.mdx",
+    "apps/docs/document-api/reference/mutations/apply.mdx",
+    "apps/docs/document-api/reference/mutations/index.mdx",
+    "apps/docs/document-api/reference/mutations/preview.mdx",
+    "apps/docs/document-api/reference/query/index.mdx",
+    "apps/docs/document-api/reference/query/match.mdx",
     "apps/docs/document-api/reference/replace.mdx",
     "apps/docs/document-api/reference/track-changes/accept-all.mdx",
     "apps/docs/document-api/reference/track-changes/accept.mdx",
@@ -121,8 +126,20 @@
       ],
       "pagePath": "apps/docs/document-api/reference/track-changes/index.mdx",
       "title": "Track Changes"
+    },
+    {
+      "key": "query",
+      "operationIds": ["query.match"],
+      "pagePath": "apps/docs/document-api/reference/query/index.mdx",
+      "title": "Query"
+    },
+    {
+      "key": "mutations",
+      "operationIds": ["mutations.preview", "mutations.apply"],
+      "pagePath": "apps/docs/document-api/reference/mutations/index.mdx",
+      "title": "Mutations"
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "dd10c0218ba8a9148e8a3412053672bbbe88976f7a779650602aa98dec6efeee"
+  "sourceHash": "def6d3b7f9e73d872b213cde06be8293f5f607501e777f9cb5f76c6d8e3f252a"
 }

apps/docs/document-api/reference/capabilities/get.mdx

@@ -1209,6 +1209,102 @@ description: Generated reference for capabilities.get
           ],
           "type": "object"
         },
+        "mutations.apply": {
+          "additionalProperties": false,
+          "properties": {
+            "available": {
+              "type": "boolean"
+            },
+            "dryRun": {
+              "type": "boolean"
+            },
+            "reasons": {
+              "items": {
+                "enum": [
+                  "COMMAND_UNAVAILABLE",
+                  "OPERATION_UNAVAILABLE",
+                  "TRACKED_MODE_UNAVAILABLE",
+                  "DRY_RUN_UNAVAILABLE",
+                  "NAMESPACE_UNAVAILABLE"
+                ]
+              },
+              "type": "array"
+            },
+            "tracked": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "available",
+            "tracked",
+            "dryRun"
+          ],
+          "type": "object"
+        },
+        "mutations.preview": {
+          "additionalProperties": false,
+          "properties": {
+            "available": {
+              "type": "boolean"
+            },
+            "dryRun": {
+              "type": "boolean"
+            },
+            "reasons": {
+              "items": {
+                "enum": [
+                  "COMMAND_UNAVAILABLE",
+                  "OPERATION_UNAVAILABLE",
+                  "TRACKED_MODE_UNAVAILABLE",
+                  "DRY_RUN_UNAVAILABLE",
+                  "NAMESPACE_UNAVAILABLE"
+                ]
+              },
+              "type": "array"
+            },
+            "tracked": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "available",
+            "tracked",
+            "dryRun"
+          ],
+          "type": "object"
+        },
+        "query.match": {
+          "additionalProperties": false,
+          "properties": {
+            "available": {
+              "type": "boolean"
+            },
+            "dryRun": {
+              "type": "boolean"
+            },
+            "reasons": {
+              "items": {
+                "enum": [
+                  "COMMAND_UNAVAILABLE",
+                  "OPERATION_UNAVAILABLE",
+                  "TRACKED_MODE_UNAVAILABLE",
+                  "DRY_RUN_UNAVAILABLE",
+                  "NAMESPACE_UNAVAILABLE"
+                ]
+              },
+              "type": "array"
+            },
+            "tracked": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "available",
+            "tracked",
+            "dryRun"
+          ],
+          "type": "object"
+        },
         "replace": {
           "additionalProperties": false,
           "properties": {
@@ -1474,6 +1570,9 @@ description: Generated reference for capabilities.get
         "trackChanges.reject",
         "trackChanges.acceptAll",
         "trackChanges.rejectAll",
+        "query.match",
+        "mutations.preview",
+        "mutations.apply",
         "capabilities.get"
       ],
       "type": "object"

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

@@ -20,6 +20,8 @@ Document API is currently alpha and subject to breaking changes.
 | Lists | 8 | [Open](./lists/index) |
 | Comments | 11 | [Open](./comments/index) |
 | Track Changes | 6 | [Open](./track-changes/index) |
+| Query | 1 | [Open](./query/index) |
+| Mutations | 2 | [Open](./mutations/index) |
 
 ## All operations
 
@@ -64,4 +66,7 @@ Document API is currently alpha and subject to breaking changes.
 | [`trackChanges.reject`](./track-changes/reject) | Track Changes | `trackChanges.reject` | Yes | `conditional` | No | No |
 | [`trackChanges.acceptAll`](./track-changes/accept-all) | Track Changes | `trackChanges.acceptAll` | Yes | `conditional` | No | No |
 | [`trackChanges.rejectAll`](./track-changes/reject-all) | Track Changes | `trackChanges.rejectAll` | Yes | `conditional` | No | No |
+| [`query.match`](./query/match) | Query | `query.match` | No | `idempotent` | No | No |
+| [`mutations.preview`](./mutations/preview) | Mutations | `mutations.preview` | No | `idempotent` | No | No |
+| [`mutations.apply`](./mutations/apply) | Mutations | `mutations.apply` | Yes | `non-idempotent` | Yes | No |
 | [`capabilities.get`](./capabilities/get) | Capabilities | `capabilities` | No | `idempotent` | No | No |