Document apiReferenceTrack changes

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.

mutates documentconditional
doc.trackChanges.decide(…)

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.

Inputs

decision"accept" | "reject"required
targetobject | object | object | object | object | object | object | object | objectrequired

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.

id
kind"id"required
idstringrequired
storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
side"insert" | "inserted" | "delete" | "deleted"
moveRole"pair" | "source" | "destination"

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.

ids
kind"ids"required
idsstring[]required

Logical tracked-change ids resolved atomically in one decision and history unit.

range
kind"range"required
rangeTextTargetrequired
Fields
kind"text"required
segmentsTextSegment[]required
storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
coordinateSpace"visible" | "tracked"

Coordinate space of the TextTarget offsets. Omitted preserves legacy tracked-space behavior.

overlapstring

Optional logical overlap selector for callers that already resolved an ambiguous overlap surface. Adapter-owned interpretation.

side"insert" | "inserted" | "delete" | "deleted" | "source" | "destination"

Optional revision side for paired replacement or move targets.

storyStoryLocator

Optional story containing the range target.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
partstring

Compatibility alias used by older range callers; interpretation is adapter-owned.

range
kind"range"required
rangeobjectrequired
Fields
anchorstringrequired
relativeStartintegerrequired
relativeEndintegerrequired
overlapstring

Optional logical overlap selector for callers that already resolved an ambiguous overlap surface. Adapter-owned interpretation.

side"insert" | "inserted" | "delete" | "deleted" | "source" | "destination"

Optional revision side for paired replacement or move targets.

storyStoryLocator

Optional story containing the range target.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
partstring

Compatibility alias used by older range callers; interpretation is adapter-owned.

range
kind"range"required
anchorstringrequired
relativeStartintegerrequired
relativeEndintegerrequired
overlapstring

Optional logical overlap selector for callers that already resolved an ambiguous overlap surface. Adapter-owned interpretation.

side"insert" | "inserted" | "delete" | "deleted" | "source" | "destination"

Optional revision side for paired replacement or move targets.

storyStoryLocator

Optional story containing the range target.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
partstring

Compatibility alias used by older range callers; interpretation is adapter-owned.

all
kind"all"required
storyStoryLocator | "all"

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.

body / headerFooterSlot / headerFooterPart / footnote / endnote / textbox
body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
Variant 2

No fields.

Variant 7
idstringrequired
storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
moveRole"pair" | "source" | "destination"

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.

Variant 8
idstringrequired
rangeobjectrequired
Fields
kind"partial"required
startintegerrequired
endintegerrequired
storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
Variant 9
scope"all"required
storyStoryLocator | "all"

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.

body / headerFooterSlot / headerFooterPart / footnote / endnote / textbox
body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
Variant 2

No fields.

1 additional input field
expectedRevisionstring

Backward-compatible alias for options.expectedRevision. Explicit mutation options take precedence when both are supplied.

Result

Output fields
true
successtruerequired
idstring
insertedEntityAddress[]
updatedEntityAddress[]
removedEntityAddress[]
invalidatedRefsAffectedRef[]
remappedRefsAffectedRefRemapping[]
affectedStoriesStoryLocator[]
textRangeShiftsTextRangeShift[]
txIdstring
false
successfalserequired
failureobjectrequired
Fields
code"NO_OP" | "INVALID_INPUT" | "INVALID_TARGET" | "TARGET_NOT_FOUND" | "CAPABILITY_UNAVAILABLE" | "PERMISSION_DENIED" | "PRECONDITION_FAILED" | "COMMENT_CASCADE_PARTIAL" | "SPAN_FRAGMENTED" | "STALE_REVISION" | "REVISION_MISMATCH"required
messagestringrequired
detailsunknown

Failures

Pre-apply throws

  • TARGET_NOT_FOUND
  • CAPABILITY_UNAVAILABLE
  • INVALID_INPUT
1 more codes
  • INVALID_TARGET

Non-applied receipt codes

  • NO_OP
  • INVALID_INPUT
  • INVALID_TARGET
8 more codes
  • TARGET_NOT_FOUND
  • CAPABILITY_UNAVAILABLE
  • PERMISSION_DENIED
  • PRECONDITION_FAILED
  • COMMENT_CASCADE_PARTIAL
  • SPAN_FRAGMENTED
  • STALE_REVISION
  • REVISION_MISMATCH

Raw schemas

Open the generated JSON artifact for the exact input, output, success, and failure schemas represented by this contract version.

View raw JSON schemas