# trackChanges.decide > Accept or reject tracked changes by logical id, by several logical ids atomically, 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. - Member path: `doc.trackChanges.decide(…)` - Mutates document: yes - Idempotency: `conditional` - Supports tracked mode: no - Supports dry run: no ## 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 schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$defs": { "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "body" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "headerFooterSlot" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "headerFooterPart" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "footnote" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "endnote" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "textbox" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] }, "TextTarget": { "type": "object", "properties": { "kind": { "const": "text" }, "segments": { "type": "array", "items": { "$ref": "#/$defs/TextSegment" }, "minItems": 1 }, "story": { "$ref": "#/$defs/StoryLocator" }, "coordinateSpace": { "$ref": "#/$defs/TextCoordinateSpace" } }, "additionalProperties": false, "required": [ "kind", "segments" ] }, "TextSegment": { "type": "object", "properties": { "blockId": { "type": "string" }, "range": { "$ref": "#/$defs/Range" } }, "additionalProperties": false, "required": [ "blockId", "range" ] }, "Range": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } }, "additionalProperties": false, "required": [ "start", "end" ] }, "TextCoordinateSpace": { "enum": [ "visible", "tracked" ] } }, "type": "object", "properties": { "decision": { "enum": [ "accept", "reject" ] }, "expectedRevision": { "type": "string", "description": "Backward-compatible alias for options.expectedRevision. Explicit mutation options take precedence when both are supplied." }, "target": { "description": "Decision target. Canonical shapes: { kind: 'id', id, story? } (one whole logical tracked change), { kind: 'ids', ids } (several whole logical tracked changes in one atomic history unit), { kind: 'range', range: TextTarget, coordinateSpace?, 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": [ { "type": "object", "properties": { "kind": { "const": "id" }, "id": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" }, "side": { "enum": [ "insert", "inserted", "delete", "deleted" ] }, "moveRole": { "enum": [ "pair", "source", "destination" ], "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." } }, "additionalProperties": false, "required": [ "kind", "id" ] }, { "type": "object", "properties": { "kind": { "const": "ids" }, "ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Logical tracked-change ids resolved atomically in one decision and history unit." } }, "additionalProperties": false, "required": [ "kind", "ids" ] }, { "type": "object", "properties": { "kind": { "const": "range" }, "range": { "$ref": "#/$defs/TextTarget" }, "coordinateSpace": { "enum": [ "visible", "tracked" ], "description": "Coordinate space of the TextTarget offsets. Omitted preserves legacy tracked-space behavior." }, "overlap": { "type": "string", "description": "Optional logical overlap selector for callers that already resolved an ambiguous overlap surface. Adapter-owned interpretation." }, "side": { "enum": [ "insert", "inserted", "delete", "deleted", "source", "destination" ], "description": "Optional revision side for paired replacement or move targets." }, "story": { "$ref": "#/$defs/StoryLocator", "description": "Optional story containing the range target." }, "part": { "type": "string", "description": "Compatibility alias used by older range callers; interpretation is adapter-owned." } }, "additionalProperties": false, "required": [ "kind", "range" ] }, { "type": "object", "properties": { "kind": { "const": "range" }, "range": { "type": "object", "properties": { "anchor": { "type": "string" }, "relativeStart": { "type": "integer", "minimum": 0 }, "relativeEnd": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "anchor", "relativeStart", "relativeEnd" ] }, "overlap": { "type": "string", "description": "Optional logical overlap selector for callers that already resolved an ambiguous overlap surface. Adapter-owned interpretation." }, "side": { "enum": [ "insert", "inserted", "delete", "deleted", "source", "destination" ], "description": "Optional revision side for paired replacement or move targets." }, "story": { "$ref": "#/$defs/StoryLocator", "description": "Optional story containing the range target." }, "part": { "type": "string", "description": "Compatibility alias used by older range callers; interpretation is adapter-owned." } }, "additionalProperties": false, "required": [ "kind", "range" ] }, { "type": "object", "properties": { "kind": { "const": "range" }, "anchor": { "type": "string" }, "relativeStart": { "type": "integer", "minimum": 0 }, "relativeEnd": { "type": "integer", "minimum": 0 }, "overlap": { "type": "string", "description": "Optional logical overlap selector for callers that already resolved an ambiguous overlap surface. Adapter-owned interpretation." }, "side": { "enum": [ "insert", "inserted", "delete", "deleted", "source", "destination" ], "description": "Optional revision side for paired replacement or move targets." }, "story": { "$ref": "#/$defs/StoryLocator", "description": "Optional story containing the range target." }, "part": { "type": "string", "description": "Compatibility alias used by older range callers; interpretation is adapter-owned." } }, "additionalProperties": false, "required": [ "kind", "anchor", "relativeStart", "relativeEnd" ] }, { "type": "object", "properties": { "kind": { "const": "all" }, "story": { "oneOf": [ { "$ref": "#/$defs/StoryLocator" }, { "const": "all" } ], "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." } }, "additionalProperties": false, "required": [ "kind" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" }, "moveRole": { "enum": [ "pair", "source", "destination" ], "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." } }, "additionalProperties": false, "required": [ "id" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "range": { "type": "object", "properties": { "kind": { "const": "partial" }, "start": { "type": "integer", "minimum": 0 }, "end": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "kind", "start", "end" ] }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "id", "range" ] }, { "type": "object", "properties": { "scope": { "enum": [ "all" ] }, "story": { "oneOf": [ { "$ref": "#/$defs/StoryLocator" }, { "const": "all" } ], "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." } }, "additionalProperties": false, "required": [ "scope" ] } ] } }, "required": [ "decision", "target" ], "additionalProperties": false } ``` ## Output schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$defs": { "ReceiptSuccess": { "type": "object", "properties": { "success": { "const": true }, "id": { "type": "string" }, "inserted": { "type": "array", "items": { "$ref": "#/$defs/EntityAddress" } }, "updated": { "type": "array", "items": { "$ref": "#/$defs/EntityAddress" } }, "removed": { "type": "array", "items": { "$ref": "#/$defs/EntityAddress" } }, "invalidatedRefs": { "type": "array", "items": { "$ref": "#/$defs/AffectedRef" } }, "remappedRefs": { "type": "array", "items": { "$ref": "#/$defs/AffectedRefRemapping" } }, "affectedStories": { "type": "array", "items": { "$ref": "#/$defs/StoryLocator" } }, "textRangeShifts": { "type": "array", "items": { "$ref": "#/$defs/TextRangeShift" } }, "txId": { "type": "string" }, "warnings": { "type": "array", "items": { "$ref": "#/$defs/ReviewWarning" } }, "effects": { "$ref": "#/$defs/ReceiptEffects" } }, "additionalProperties": false, "required": [ "success" ] }, "EntityAddress": { "oneOf": [ { "$ref": "#/$defs/CommentAddress" }, { "$ref": "#/$defs/TrackedChangeAddress" } ] }, "CommentAddress": { "type": "object", "properties": { "kind": { "const": "entity" }, "entityType": { "const": "comment" }, "entityId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "entityType", "entityId" ] }, "TrackedChangeAddress": { "type": "object", "properties": { "kind": { "const": "entity" }, "entityType": { "const": "trackedChange" }, "entityId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "entityType", "entityId" ] }, "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "body" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "headerFooterSlot" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "headerFooterPart" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "footnote" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "endnote" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "textbox" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] }, "AffectedRef": { "oneOf": [ { "$ref": "#/$defs/TextAddress" }, { "$ref": "#/$defs/BookmarkAddress" }, { "$ref": "#/$defs/CommentAddress" }, { "$ref": "#/$defs/TrackedChangeAddress" }, { "$ref": "#/$defs/BlockNavigationAddress" } ] }, "TextAddress": { "type": "object", "properties": { "kind": { "const": "text" }, "blockId": { "type": "string" }, "range": { "$ref": "#/$defs/Range" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "blockId", "range" ] }, "Range": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } }, "additionalProperties": false, "required": [ "start", "end" ] }, "BookmarkAddress": { "type": "object", "properties": { "kind": { "const": "entity" }, "entityType": { "const": "bookmark" }, "name": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "entityType", "name" ] }, "BlockNavigationAddress": { "type": "object", "properties": { "kind": { "const": "block" }, "nodeId": { "type": "string" }, "nodeType": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "nodeId" ] }, "AffectedRefRemapping": { "type": "object", "properties": { "from": { "$ref": "#/$defs/AffectedRef" }, "to": { "$ref": "#/$defs/AffectedRef" } }, "additionalProperties": false, "required": [ "from", "to" ] }, "TextRangeShift": { "type": "object", "properties": { "story": { "$ref": "#/$defs/StoryLocator" }, "atChar": { "type": "integer" }, "blockId": { "type": "string" }, "atCharInBlock": { "type": "integer" }, "delta": { "type": "integer" } }, "additionalProperties": false, "required": [ "story", "atChar", "delta" ] }, "ReviewWarning": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "feature": { "enum": [ "comments", "trackedChanges" ] }, "severity": { "const": "warning" }, "affectedObjectId": { "type": "string" }, "affectedPartUri": { "type": "string" }, "canProceed": { "type": "boolean" } }, "additionalProperties": false, "required": [ "code", "message", "feature", "severity", "canProceed" ] }, "ReceiptEffects": { "type": "object", "properties": { "insertedText": { "type": "array", "items": { "$ref": "#/$defs/TextMutationEffect" } }, "insertedBlocks": { "type": "array", "items": { "$ref": "#/$defs/BlockMutationEffect" } } }, "additionalProperties": false }, "TextMutationEffect": { "type": "object", "properties": { "kind": { "const": "insertedText" }, "sourcePath": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] } }, "target": { "$ref": "#/$defs/TextAddress" }, "selectionTarget": { "$ref": "#/$defs/SelectionTarget" }, "text": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "target", "selectionTarget", "text" ] }, "SelectionTarget": { "type": "object", "properties": { "kind": { "const": "selection" }, "start": { "$ref": "#/$defs/SelectionPoint" }, "end": { "$ref": "#/$defs/SelectionPoint" }, "story": { "$ref": "#/$defs/StoryLocator" }, "coordinateSpace": { "$ref": "#/$defs/TextCoordinateSpace" } }, "additionalProperties": false, "required": [ "kind", "start", "end" ] }, "SelectionPoint": { "description": "A point in the document. Use {kind:'text', blockId, offset} for character positions or {kind:'nodeEdge', node:{kind:'block', nodeType, nodeId}, edge:'before'|'after'} for block boundaries.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "text" }, "blockId": { "type": "string" }, "offset": { "type": "integer", "minimum": 0 }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "blockId", "offset" ] }, { "type": "object", "properties": { "kind": { "const": "nodeEdge" }, "node": { "$ref": "#/$defs/SelectionEdgeNodeAddress" }, "edge": { "enum": [ "before", "after" ] } }, "additionalProperties": false, "required": [ "kind", "node", "edge" ] } ] }, "SelectionEdgeNodeAddress": { "type": "object", "properties": { "kind": { "const": "block" }, "nodeType": { "enum": [ "paragraph", "heading", "table", "tableOfContents", "sdt", "image" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "TextCoordinateSpace": { "enum": [ "visible", "tracked" ] }, "BlockMutationEffect": { "type": "object", "properties": { "kind": { "const": "insertedBlock" }, "sourcePath": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] } }, "target": { "$ref": "#/$defs/BlockNodeAddress" }, "insertedText": { "$ref": "#/$defs/TextMutationEffect" } }, "additionalProperties": false, "required": [ "kind", "target" ] }, "BlockNodeAddress": { "type": "object", "properties": { "kind": { "const": "block" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] } }, "oneOf": [ { "$ref": "#/$defs/ReceiptSuccess" }, { "type": "object", "properties": { "success": { "const": false }, "failure": { "type": "object", "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" ] }, "message": { "type": "string" }, "details": {} }, "additionalProperties": false, "required": [ "code", "message" ] } }, "additionalProperties": false, "required": [ "success", "failure" ] } ] } ``` ## Pre-apply throws - `TARGET_NOT_FOUND` - `CAPABILITY_UNAVAILABLE` - `INVALID_INPUT` - `INVALID_TARGET` ## Non-applied receipt 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`