fix: normalize review namespace into trackChanges, harden input validation

Author: harbournick

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

@@ -119,5 +119,5 @@
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "a8eef0a5f30ba4a353cc0124d1274eaa79550ad9ea63c8815fb1eb915356f085"
+  "sourceHash": "71719d809aa97aaaf7d9200dedd1edf47dc16486b208b473cc009257667bed77"
 }

apps/docs/document-api/reference/comments/patch.mdx

@@ -77,6 +77,7 @@ _No fields._
 - `COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 - `INVALID_TARGET`
+- `INVALID_INPUT`
 
 ## Non-applied failure codes
 

apps/docs/document-api/reference/track-changes/decide.mdx

@@ -67,6 +67,8 @@ _No fields._
 - `TARGET_NOT_FOUND`
 - `COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
+- `INVALID_INPUT`
+- `INVALID_TARGET`
 
 ## Non-applied failure codes
 

apps/docs/document-engine/cli.mdx

@@ -42,6 +42,32 @@ superdoc save
 superdoc close
 ```
 
+## Tracked mode for mutations
+
+Use `--tracked` on mutating commands to apply edits as tracked changes instead of direct edits.
+
+```bash
+# Replace text as a tracked change
+superdoc replace \
+  --target-json '{"kind":"text","blockId":"...","range":{"start":0,"end":9}}' \
+  --text "NewCo Inc." \
+  --tracked
+
+# Insert text as a tracked change
+superdoc insert --text "Added clause" --tracked
+```
+
+`--tracked` is shorthand for `--change-mode tracked`:
+
+```bash
+superdoc replace \
+  --target-json '{"kind":"text","blockId":"...","range":{"start":0,"end":9}}' \
+  --text "NewCo Inc." \
+  --change-mode tracked
+```
+
+For commands that do not support tracked mode, the CLI returns `TRACK_CHANGE_COMMAND_UNAVAILABLE`.
+
 ## Commands
 
 ### Lifecycle
@@ -70,11 +96,10 @@ The CLI exposes all [Document API operations](/document-api/overview) as command
 | `superdoc format underline` | `format.underline` | Toggle underline on a range |
 | `superdoc format strikethrough` | `format.strikethrough` | Toggle strikethrough on a range |
 | `superdoc create paragraph` | `create.paragraph` | Insert a new paragraph |
-| `superdoc comments add` | `comments.add` | Add a comment thread |
+| `superdoc comments create` | `comments.create` | Create a comment thread |
 | `superdoc comments list` | `comments.list` | List all comments |
 | `superdoc track-changes list` | `trackChanges.list` | List tracked changes |
-| `superdoc track-changes accept` | `trackChanges.accept` | Accept a tracked change |
-| `superdoc track-changes reject` | `trackChanges.reject` | Reject a tracked change |
+| `superdoc track-changes decide` | `trackChanges.decide` | Accept or reject a tracked change |
 
 Run `superdoc --help` for the full list, or `superdoc describe` for machine-readable metadata.
 

apps/docs/document-engine/sdks.mdx

@@ -35,7 +35,9 @@ The CLI is bundled with the SDK — no separate install needed.
     ```typescript
     import { SuperDocClient } from '@superdoc-dev/sdk';
 
-    const client = new SuperDocClient();
+    const client = new SuperDocClient({
+      defaultChangeMode: 'tracked',
+    });
 
     // Open a document
     await client.doc.open({ doc: './contract.docx' });
@@ -51,7 +53,6 @@ The CLI is bundled with the SDK — no separate install needed.
       await client.doc.mutations.apply({
         expectedRevision: match.evaluatedRevision,
         atomic: true,
-        changeMode: 'direct',
         steps: [
           {
             id: 'replace-acme',
@@ -76,7 +77,7 @@ The CLI is bundled with the SDK — no separate install needed.
 
 
     async def main():
-        client = AsyncSuperDocClient()
+        client = AsyncSuperDocClient(default_change_mode="tracked")
 
         # Open a document
         await client.doc.open({"doc": "./contract.docx"})
@@ -95,7 +96,6 @@ The CLI is bundled with the SDK — no separate install needed.
                 {
                     "expectedRevision": match["evaluatedRevision"],
                     "atomic": True,
-                    "changeMode": "direct",
                     "steps": [
                         {
                             "id": "replace-acme",
@@ -117,6 +117,8 @@ The CLI is bundled with the SDK — no separate install needed.
   </Tab>
 </Tabs>
 
+Set `defaultChangeMode: 'tracked'` (Node) or `default_change_mode='tracked'` (Python) to make mutations use tracked changes by default. If you pass `changeMode` on a specific call, that explicit value overrides the default.
+
 {/* SDK_OPERATIONS_START */}
 ## Available operations
 

apps/mcp/src/tools/comments.ts

@@ -25,7 +25,7 @@ export function registerCommentTools(server: McpServer, sessions: SessionManager
         const { api } = sessions.get(session_id);
         const parsed = JSON.parse(target);
         const result = api.invoke({
-          operationId: 'comments.add',
+          operationId: 'comments.create',
           input: { text, target: parsed },
         });
         return {
@@ -87,7 +87,7 @@ export function registerCommentTools(server: McpServer, sessions: SessionManager
       try {
         const { api } = sessions.get(session_id);
         const result = api.invoke({
-          operationId: 'comments.reply',
+          operationId: 'comments.create',
           input: { parentCommentId: comment_id, text },
         });
         return {
@@ -117,8 +117,8 @@ export function registerCommentTools(server: McpServer, sessions: SessionManager
       try {
         const { api } = sessions.get(session_id);
         const result = api.invoke({
-          operationId: 'comments.resolve',
-          input: { commentId: comment_id },
+          operationId: 'comments.patch',
+          input: { commentId: comment_id, status: 'resolved' },
         });
         return {
           content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],

apps/mcp/src/tools/track-changes.ts

@@ -57,7 +57,10 @@ export function registerTrackChangesTools(server: McpServer, sessions: SessionMa
     async ({ session_id, id }) => {
       try {
         const { api } = sessions.get(session_id);
-        const result = api.invoke({ operationId: 'review.decide', input: { decision: 'accept', target: { id } } });
+        const result = api.invoke({
+          operationId: 'trackChanges.decide',
+          input: { decision: 'accept', target: { id } },
+        });
         return {
           content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
         };
@@ -85,7 +88,10 @@ export function registerTrackChangesTools(server: McpServer, sessions: SessionMa
     async ({ session_id, id }) => {
       try {
         const { api } = sessions.get(session_id);
-        const result = api.invoke({ operationId: 'review.decide', input: { decision: 'reject', target: { id } } });
+        const result = api.invoke({
+          operationId: 'trackChanges.decide',
+          input: { decision: 'reject', target: { id } },
+        });
         return {
           content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
         };
@@ -112,7 +118,7 @@ export function registerTrackChangesTools(server: McpServer, sessions: SessionMa
       try {
         const { api } = sessions.get(session_id);
         const result = api.invoke({
-          operationId: 'review.decide',
+          operationId: 'trackChanges.decide',
           input: { decision: 'accept', target: { scope: 'all' } },
         });
         return {
@@ -141,7 +147,7 @@ export function registerTrackChangesTools(server: McpServer, sessions: SessionMa
       try {
         const { api } = sessions.get(session_id);
         const result = api.invoke({
-          operationId: 'review.decide',
+          operationId: 'trackChanges.decide',
           input: { decision: 'reject', target: { scope: 'all' } },
         });
         return {

packages/document-api/scripts/lib/contract-output-artifacts.ts

@@ -182,7 +182,7 @@ export function buildAgentArtifacts(): GeneratedFile[] {
       {
         id: 'comment-thread-lifecycle',
         title: 'Comment lifecycle workflow',
-        operations: ['comments.add', 'comments.reply', 'comments.resolve'],
+        operations: ['comments.create', 'comments.patch', 'comments.delete'],
       },
       {
         id: 'list-manipulation',

packages/document-api/src/README.md

@@ -90,7 +90,7 @@ Locate text in the document and replace it:
 
 ```ts
 const result = editor.doc.find({ type: 'text', text: 'foo' });
-const target = result.context?.[0]?.textRanges?.[0];
+const target = result.items?.[0]?.context?.textRanges?.[0];
 if (target) {
   editor.doc.replace({ target, text: 'bar' });
 }
@@ -126,13 +126,13 @@ const receipt = editor.doc.insert(
 Add a comment, reply, then resolve the thread:
 
 ```ts
-const target = result.context?.[0]?.textRanges?.[0];
-const addReceipt = editor.doc.comments.add({ target, text: 'Review this section.' });
+const target = result.items?.[0]?.context?.textRanges?.[0];
+const createReceipt = editor.doc.comments.create({ target, text: 'Review this section.' });
 // Use the comment ID from the receipt to reply
 const comments = editor.doc.comments.list();
-const thread = comments.matches[0];
-editor.doc.comments.reply({ parentCommentId: thread.commentId, text: 'Looks good.' });
-editor.doc.comments.resolve({ commentId: thread.commentId });
+const thread = comments.items[0];
+editor.doc.comments.create({ parentCommentId: thread.id, text: 'Looks good.' });
+editor.doc.comments.patch({ commentId: thread.id, status: 'resolved' });
 ```
 
 ### Workflow: List Manipulation
@@ -141,8 +141,8 @@ Insert a list item, change its type, then indent it:
 
 ```ts
 const lists = editor.doc.lists.list();
-const firstItem = lists.matches[0];
-const insertResult = editor.doc.lists.insert({ target: firstItem, position: 'after', text: 'New item' });
+const firstItem = lists.items[0];
+const insertResult = editor.doc.lists.insert({ target: firstItem.address, position: 'after', text: 'New item' });
 if (insertResult.success) {
   editor.doc.lists.setType({ target: insertResult.item, kind: 'ordered' });
   editor.doc.lists.indent({ target: insertResult.item });
@@ -430,95 +430,36 @@ Convert a list item back into a plain paragraph, exiting the list. Supports dry-
 
 ### Comments
 
-### `comments.add`
+### `comments.create`
 
-Attach a new comment to a text range.
+Create a new comment thread or reply. When `parentCommentId` is provided, creates a reply. Otherwise creates a root comment anchored to the given text range.
 
-- **Input**: `AddCommentInput` (`{ target, text }`)
-- **Output**: `Receipt`
-- **Mutates**: Yes
-- **Idempotency**: non-idempotent
-- **Failure codes**: `INVALID_TARGET`, `NO_OP`
-
-### `comments.edit`
-
-Update the body text of an existing comment.
-
-- **Input**: `EditCommentInput` (`{ commentId, text }`)
-- **Output**: `Receipt`
-- **Mutates**: Yes
-- **Idempotency**: conditional
-- **Failure codes**: `NO_OP`
-
-### `comments.reply`
-
-Add a reply to an existing comment thread.
-
-- **Input**: `ReplyToCommentInput` (`{ parentCommentId, text }`)
+- **Input**: `CommentsCreateInput` (`{ text, target?, parentCommentId? }`)
 - **Output**: `Receipt`
 - **Mutates**: Yes
 - **Idempotency**: non-idempotent
 - **Failure codes**: `INVALID_TARGET`
 
-### `comments.move`
-
-Move a comment to a different text range.
-
-- **Input**: `MoveCommentInput` (`{ commentId, target }`)
-- **Output**: `Receipt`
-- **Mutates**: Yes
-- **Idempotency**: conditional
-- **Failure codes**: `INVALID_TARGET`, `NO_OP`
+### `comments.patch`
 
-### `comments.resolve`
+Field-level patch on an existing comment. Exactly one mutation field must be provided per call.
 
-Resolve an open comment, marking it as addressed.
-
-- **Input**: `ResolveCommentInput` (`{ commentId }`)
+- **Input**: `CommentsPatchInput` (`{ commentId, text?, target?, status?, isInternal? }`)
 - **Output**: `Receipt`
 - **Mutates**: Yes
 - **Idempotency**: conditional
-- **Failure codes**: `NO_OP`
+- **Failure codes**: `INVALID_INPUT`, `INVALID_TARGET`, `NO_OP`
 
-### `comments.remove`
+### `comments.delete`
 
 Remove a comment from the document.
 
-- **Input**: `RemoveCommentInput` (`{ commentId }`)
+- **Input**: `CommentsDeleteInput` (`{ commentId }`)
 - **Output**: `Receipt`
 - **Mutates**: Yes
 - **Idempotency**: conditional
 - **Failure codes**: `NO_OP`
 
-### `comments.setInternal`
-
-Set or clear the internal/private flag on a comment.
-
-- **Input**: `SetCommentInternalInput` (`{ commentId, isInternal }`)
-- **Output**: `Receipt`
-- **Mutates**: Yes
-- **Idempotency**: conditional
-- **Failure codes**: `NO_OP`, `INVALID_TARGET`
-
-### `comments.setActive`
-
-Set which comment is currently active/focused. Pass `null` to clear.
-
-- **Input**: `SetCommentActiveInput` (`{ commentId }`)
-- **Output**: `Receipt`
-- **Mutates**: Yes
-- **Idempotency**: conditional
-- **Failure codes**: `INVALID_TARGET`
-
-### `comments.goTo`
-
-Scroll to and focus a comment in the document.
-
-- **Input**: `GoToCommentInput` (`{ commentId }`)
-- **Output**: `Receipt`
-- **Mutates**: No
-- **Idempotency**: conditional
-
 ### `comments.get`
 
 Retrieve full information for a single comment by ID. Throws `TARGET_NOT_FOUND` when the comment is not found.
@@ -557,42 +498,12 @@ Retrieve full information for a single tracked change by its canonical ID. Throw
 - **Mutates**: No
 - **Idempotency**: idempotent
 
-### `trackChanges.accept`
-
-Accept a tracked change, applying it permanently to the document. Returns `NO_OP` when the change has already been accepted.
-
-- **Input**: `TrackChangesAcceptInput` (`{ id }`)
-- **Output**: `Receipt`
-- **Mutates**: Yes
-- **Idempotency**: conditional
-- **Failure codes**: `NO_OP`
-
-### `trackChanges.reject`
-
-Reject a tracked change, reverting it from the document. Returns `NO_OP` when the change has already been rejected.
-
-- **Input**: `TrackChangesRejectInput` (`{ id }`)
-- **Output**: `Receipt`
-- **Mutates**: Yes
-- **Idempotency**: conditional
-- **Failure codes**: `NO_OP`
-
-### `trackChanges.acceptAll`
+### `trackChanges.decide`
 
-Accept all tracked changes in the document. Returns `NO_OP` when there are no pending changes.
+Accept or reject a tracked change by ID, or accept/reject all changes with `{ scope: 'all' }`.
 
-- **Input**: `TrackChangesAcceptAllInput` (empty object)
+- **Input**: `ReviewDecideInput` (`{ decision: 'accept' | 'reject', target: { id } | { scope: 'all' } }`)
 - **Output**: `Receipt`
 - **Mutates**: Yes
 - **Idempotency**: conditional
-- **Failure codes**: `NO_OP`
-
-### `trackChanges.rejectAll`
-
-Reject all tracked changes in the document. Returns `NO_OP` when there are no pending changes.
-
-- **Input**: `TrackChangesRejectAllInput` (empty object)
-- **Output**: `Receipt`
-- **Mutates**: Yes
-- **Idempotency**: conditional
-- **Failure codes**: `NO_OP`
+- **Failure codes**: `NO_OP`, `TARGET_NOT_FOUND`, `COMMAND_UNAVAILABLE`