> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# trackChanges.decide

> Accept or reject tracked changes by logical id, by selected text range, by logical anchor range ({ anchor, relativeStart, relativeEnd }), or every active change in the document. Range targets may include overlap / side selectors and may partially resolve a change, splitting surviving content into new fragments with stable ids. Legacy `{ id, range: { kind: "partial", ... } }` targets are promoted only when the active adapter supports `decide()`; legacy fallback adapters fail closed with `INVALID_INPUT`. `input.expectedRevision` is accepted as a compatibility alias for mutation options.

## Summary

Accept or reject tracked changes by logical id, by selected text range, by logical anchor range (\{ anchor, relativeStart, relativeEnd }), or every active change in the document. Range targets may include overlap / side selectors and may partially resolve a change, splitting surviving content into new fragments with stable ids. Legacy `\{ id, range: \{ kind: "partial", ... \} \}` targets are promoted only when the active adapter supports `decide()`; legacy fallback adapters fail closed with `INVALID_INPUT`. `input.expectedRevision` is accepted as a compatibility alias for mutation options.

* Operation ID: `trackChanges.decide`
* API member path: `editor.doc.trackChanges.decide(...)`
* Mutates document: `yes`
* Idempotency: `conditional`
* Supports tracked mode: `no`
* Supports dry run: `no`
* Deterministic target resolution: `yes`

## Expected result

Returns a Receipt. `removed` lists retired tracked-change ids; `inserted` lists successor fragment ids produced by partial range splits; `invalidatedRefs` lists every retired tracked-change ref plus cascade-deleted comment ids; `remappedRefs` carries surviving comment anchors moved by the decision; `affectedStories` lists touched stories; `textRangeShifts` reports per-story visible-text deltas; `txId` correlates with history. Failures: SPAN\_FRAGMENTED when a range crosses an indivisible boundary, CAPABILITY\_UNAVAILABLE for formatting / structural / move targets (not yet supported), TARGET\_NOT\_FOUND for retired ids or zero overlap, STALE\_REVISION for stale expectedRevision, REVISION\_MISMATCH for stale range coverage, NO\_OP when \{ kind: 'all' } resolves an empty target set.

## Input fields

| Field | Type | Required | Description |
| - | - | - | - |
| `decision` | enum | yes | `"accept"`, `"reject"` |
| `expectedRevision` | string | no | |
| `target` | object(kind="id") \| object(kind="range") \| object(kind="range") \| object(kind="range") \| object(kind="all") \| object \| object \| object | yes | One of: object(kind="id"), object(kind="range"), object(kind="range"), object(kind="range"), object(kind="all"), object, object, object |

### Example request

```json theme={null}
{
  "decision": "accept",
  "target": {
    "id": "id-001",
    "story": {
      "kind": "story",
      "storyType": "body"
    }
  }
}
```

## Output fields

### Variant 1 (success=true)

| Field | Type | Required | Description |
| - | - | - | - |
| `affectedStories` | StoryLocator\[] | no | |
| `id` | string | no | |
| `inserted` | EntityAddress\[] | no | |
| `invalidatedRefs` | AffectedRef\[] | no | |
| `remappedRefs` | AffectedRefRemapping\[] | no | |
| `removed` | EntityAddress\[] | no | |
| `success` | `true` | yes | Constant: `true` |
| `textRangeShifts` | TextRangeShift\[] | no | |
| `txId` | string | no | |
| `updated` | EntityAddress\[] | no | |

### Variant 2 (success=false)

| Field | Type | Required | Description |
| - | - | - | - |
| `failure` | object | yes | |
| `failure.code` | enum | yes | `"NO_OP"`, `"INVALID_INPUT"`, `"INVALID_TARGET"`, `"TARGET_NOT_FOUND"`, `"CAPABILITY_UNAVAILABLE"`, `"PERMISSION_DENIED"`, `"PRECONDITION_FAILED"`, `"COMMENT_CASCADE_PARTIAL"`, `"SPAN_FRAGMENTED"`, `"STALE_REVISION"`, `"REVISION_MISMATCH"` |
| `failure.details` | any | no | |
| `failure.message` | string | yes | |
| `success` | `false` | yes | Constant: `false` |

### Example response

```json theme={null}
{
  "id": "id-001",
  "inserted": [
    {
      "entityId": "entity-789",
      "entityType": "comment",
      "kind": "entity"
    }
  ],
  "success": true
}
```

## Pre-apply throws

* `TARGET_NOT_FOUND`
* `CAPABILITY_UNAVAILABLE`
* `INVALID_INPUT`
* `INVALID_TARGET`

## Non-applied failure codes

* `NO_OP`
* `INVALID_INPUT`
* `INVALID_TARGET`
* `TARGET_NOT_FOUND`
* `CAPABILITY_UNAVAILABLE`
* `PERMISSION_DENIED`
* `PRECONDITION_FAILED`
* `COMMENT_CASCADE_PARTIAL`
* `SPAN_FRAGMENTED`
* `STALE_REVISION`
* `REVISION_MISMATCH`

## Raw schemas

> [accordion] Raw input schema
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "decision": {
>       "enum": [
>         "accept",
>         "reject"
>       ]
>     },
>     "expectedRevision": {
>       "description": "Backward-compatible alias for options.expectedRevision. Explicit mutation options take precedence when both are supplied.",
>       "type": "string"
>     },
>     "target": {
>       "description": "Decision target. Canonical shapes: { kind: 'id', id, story? } (whole logical tracked change), { kind: 'range', range: TextTarget, overlap?, side?, story?, part? } or { kind: 'range', range: { anchor, relativeStart, relativeEnd }, overlap?, side?, story?, part? } (resolves only the selected overlap; may split fragments), { kind: 'all' } (every active tracked change). Legacy { id, story? } / { id, range: { kind: 'partial', start, end } } / { scope: 'all' } shapes are accepted and transparently promoted to canonical targets.",
>       "oneOf": [
>         {
>           "additionalProperties": false,
>           "properties": {
>             "id": {
>               "type": "string"
>             },
>             "kind": {
>               "const": "id"
>             },
>             "moveRole": {
>               "description": "Optional move pairing assertion. 'pair' requires the resolved tracked change to be a paired move; 'source' / 'destination' further narrow to a specific half. When the assertion does not hold the decide adapter fails closed.",
>               "enum": [
>                 "pair",
>                 "source",
>                 "destination"
>               ]
>             },
>             "side": {
>               "description": "Optional replacement side. When the id resolves to a paired replacement, decides only the 'inserted' or 'deleted' half, leaving the other half as a standalone pending change.",
>               "enum": [
>                 "inserted",
>                 "deleted"
>               ]
>             },
>             "story": {
>               "$ref": "#/$defs/StoryLocator"
>             }
>           },
>           "required": [
>             "kind",
>             "id"
>           ],
>           "type": "object"
>         },
>         {
>           "additionalProperties": false,
>           "properties": {
>             "kind": {
>               "const": "range"
>             },
>             "overlap": {
>               "description": "Optional logical overlap selector for callers that already resolved an ambiguous overlap surface. Adapter-owned interpretation.",
>               "type": "string"
>             },
>             "part": {
>               "description": "Compatibility alias used by older range callers; interpretation is adapter-owned.",
>               "type": "string"
>             },
>             "range": {
>               "$ref": "#/$defs/TextTarget"
>             },
>             "side": {
>               "description": "Optional revision side for paired replacement or move targets.",
>               "enum": [
>                 "insert",
>                 "inserted",
>                 "delete",
>                 "deleted",
>                 "source",
>                 "destination"
>               ]
>             },
>             "story": {
>               "$ref": "#/$defs/StoryLocator",
>               "description": "Optional story containing the range target."
>             }
>           },
>           "required": [
>             "kind",
>             "range"
>           ],
>           "type": "object"
>         },
>         {
>           "additionalProperties": false,
>           "properties": {
>             "kind": {
>               "const": "range"
>             },
>             "overlap": {
>               "description": "Optional logical overlap selector for callers that already resolved an ambiguous overlap surface. Adapter-owned interpretation.",
>               "type": "string"
>             },
>             "part": {
>               "description": "Compatibility alias used by older range callers; interpretation is adapter-owned.",
>               "type": "string"
>             },
>             "range": {
>               "additionalProperties": false,
>               "properties": {
>                 "anchor": {
>                   "type": "string"
>                 },
>                 "relativeEnd": {
>                   "minimum": 0,
>                   "type": "integer"
>                 },
>                 "relativeStart": {
>                   "minimum": 0,
>                   "type": "integer"
>                 }
>               },
>               "required": [
>                 "anchor",
>                 "relativeStart",
>                 "relativeEnd"
>               ],
>               "type": "object"
>             },
>             "side": {
>               "description": "Optional revision side for paired replacement or move targets.",
>               "enum": [
>                 "insert",
>                 "inserted",
>                 "delete",
>                 "deleted",
>                 "source",
>                 "destination"
>               ]
>             },
>             "story": {
>               "$ref": "#/$defs/StoryLocator",
>               "description": "Optional story containing the range target."
>             }
>           },
>           "required": [
>             "kind",
>             "range"
>           ],
>           "type": "object"
>         },
>         {
>           "additionalProperties": false,
>           "properties": {
>             "anchor": {
>               "type": "string"
>             },
>             "kind": {
>               "const": "range"
>             },
>             "overlap": {
>               "description": "Optional logical overlap selector for callers that already resolved an ambiguous overlap surface. Adapter-owned interpretation.",
>               "type": "string"
>             },
>             "part": {
>               "description": "Compatibility alias used by older range callers; interpretation is adapter-owned.",
>               "type": "string"
>             },
>             "relativeEnd": {
>               "minimum": 0,
>               "type": "integer"
>             },
>             "relativeStart": {
>               "minimum": 0,
>               "type": "integer"
>             },
>             "side": {
>               "description": "Optional revision side for paired replacement or move targets.",
>               "enum": [
>                 "insert",
>                 "inserted",
>                 "delete",
>                 "deleted",
>                 "source",
>                 "destination"
>               ]
>             },
>             "story": {
>               "$ref": "#/$defs/StoryLocator",
>               "description": "Optional story containing the range target."
>             }
>           },
>           "required": [
>             "kind",
>             "anchor",
>             "relativeStart",
>             "relativeEnd"
>           ],
>           "type": "object"
>         },
>         {
>           "additionalProperties": false,
>           "properties": {
>             "kind": {
>               "const": "all"
>             },
>             "story": {
>               "description": "Optional explicit bulk filter. Omit or pass 'all' to target every revision-capable story, or pass a StoryLocator to scope the decision to one story.",
>               "oneOf": [
>                 {
>                   "$ref": "#/$defs/StoryLocator"
>                 },
>                 {
>                   "const": "all"
>                 }
>               ]
>             }
>           },
>           "required": [
>             "kind"
>           ],
>           "type": "object"
>         },
>         {
>           "additionalProperties": false,
>           "properties": {
>             "id": {
>               "type": "string"
>             },
>             "moveRole": {
>               "description": "Optional move pairing assertion. 'pair' requires the resolved tracked change to be a paired move; 'source' / 'destination' further narrow to a specific half. When the assertion does not hold the decide adapter fails closed.",
>               "enum": [
>                 "pair",
>                 "source",
>                 "destination"
>               ]
>             },
>             "side": {
>               "description": "Optional replacement side. When the id resolves to a paired replacement, decides only the 'inserted' or 'deleted' half.",
>               "enum": [
>                 "inserted",
>                 "deleted"
>               ]
>             },
>             "story": {
>               "$ref": "#/$defs/StoryLocator"
>             }
>           },
>           "required": [
>             "id"
>           ],
>           "type": "object"
>         },
>         {
>           "additionalProperties": false,
>           "properties": {
>             "id": {
>               "type": "string"
>             },
>             "range": {
>               "additionalProperties": false,
>               "properties": {
>                 "end": {
>                   "minimum": 0,
>                   "type": "integer"
>                 },
>                 "kind": {
>                   "const": "partial"
>                 },
>                 "start": {
>                   "minimum": 0,
>                   "type": "integer"
>                 }
>               },
>               "required": [
>                 "kind",
>                 "start",
>                 "end"
>               ],
>               "type": "object"
>             },
>             "story": {
>               "$ref": "#/$defs/StoryLocator"
>             }
>           },
>           "required": [
>             "id",
>             "range"
>           ],
>           "type": "object"
>         },
>         {
>           "additionalProperties": false,
>           "properties": {
>             "scope": {
>               "enum": [
>                 "all"
>               ]
>             },
>             "story": {
>               "description": "Optional explicit bulk filter. Omit or pass 'all' to target every revision-capable story, or pass a StoryLocator to scope the decision to one story.",
>               "oneOf": [
>                 {
>                   "$ref": "#/$defs/StoryLocator"
>                 },
>                 {
>                   "const": "all"
>                 }
>               ]
>             }
>           },
>           "required": [
>             "scope"
>           ],
>           "type": "object"
>         }
>       ]
>     }
>   },
>   "required": [
>     "decision",
>     "target"
>   ],
>   "type": "object"
> }
> ```

> [accordion] Raw output schema
>
> ```json theme={null}
> {
>   "oneOf": [
>     {
>       "$ref": "#/$defs/ReceiptSuccess"
>     },
>     {
>       "additionalProperties": false,
>       "properties": {
>         "failure": {
>           "additionalProperties": false,
>           "properties": {
>             "code": {
>               "enum": [
>                 "NO_OP",
>                 "INVALID_INPUT",
>                 "INVALID_TARGET",
>                 "TARGET_NOT_FOUND",
>                 "CAPABILITY_UNAVAILABLE",
>                 "PERMISSION_DENIED",
>                 "PRECONDITION_FAILED",
>                 "COMMENT_CASCADE_PARTIAL",
>                 "SPAN_FRAGMENTED",
>                 "STALE_REVISION",
>                 "REVISION_MISMATCH"
>               ]
>             },
>             "details": {},
>             "message": {
>               "type": "string"
>             }
>           },
>           "required": [
>             "code",
>             "message"
>           ],
>           "type": "object"
>         },
>         "success": {
>           "const": false
>         }
>       },
>       "required": [
>         "success",
>         "failure"
>       ],
>       "type": "object"
>     }
>   ]
> }
> ```

> [accordion] Raw success schema
>
> ```json theme={null}
> {
>   "$ref": "#/$defs/ReceiptSuccess"
> }
> ```

> [accordion] Raw failure schema
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "failure": {
>       "additionalProperties": false,
>       "properties": {
>         "code": {
>           "enum": [
>             "NO_OP",
>             "INVALID_INPUT",
>             "INVALID_TARGET",
>             "TARGET_NOT_FOUND",
>             "CAPABILITY_UNAVAILABLE",
>             "PERMISSION_DENIED",
>             "PRECONDITION_FAILED",
>             "COMMENT_CASCADE_PARTIAL",
>             "SPAN_FRAGMENTED",
>             "STALE_REVISION",
>             "REVISION_MISMATCH"
>           ]
>         },
>         "details": {},
>         "message": {
>           "type": "string"
>         }
>       },
>       "required": [
>         "code",
>         "message"
>       ],
>       "type": "object"
>     },
>     "success": {
>       "const": false
>     }
>   },
>   "required": [
>     "success",
>     "failure"
>   ],
>   "type": "object"
> }
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.