fix: track changes docs

Author: harbournick

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

@@ -1016,5 +1016,5 @@
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "9f517507db3d5a45d0f2e6a22ec14f11de4b6d2f0a94c9b5ecef151ee64b795a"
+  "sourceHash": "ea6e458d5c1476621d84f5bde9f85df9c3d620d0e226f206c57456f5ed6d20b3"
 }

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

@@ -20,7 +20,7 @@ Retrieve a single tracked change by ID.
 
 ## Expected result
 
-Returns a TrackChangeInfo object with the change type, author, date, affected content, and source Word revision IDs when available.
+Returns a TrackChangeInfo object with the change type, author, date, affected content, and raw imported Word OOXML revision IDs (`w:id`) when available.
 
 ## Input fields
 
@@ -137,14 +137,18 @@ Returns a TrackChangeInfo object with the change type, author, date, affected co
     },
     "wordRevisionIds": {
       "additionalProperties": false,
+      "description": "Raw imported Word OOXML revision IDs (`w:id`) from the source document when available. This is provenance metadata, not the canonical SuperDoc tracked-change ID. Replacements may include both `insert` and `delete` IDs.",
       "properties": {
         "delete": {
+          "description": "Raw imported Word OOXML revision ID (`w:id`) from a `<w:del>` element when this logical change includes a deletion.",
           "type": "string"
         },
         "format": {
+          "description": "Raw imported Word OOXML revision ID (`w:id`) from a `<w:rPrChange>` element when this logical change includes a formatting revision.",
           "type": "string"
         },
         "insert": {
+          "description": "Raw imported Word OOXML revision ID (`w:id`) from a `<w:ins>` element when this logical change includes an insertion.",
           "type": "string"
         }
       },

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

@@ -20,7 +20,7 @@ List all tracked changes in the document.
 
 ## Expected result
 
-Returns a TrackChangesListResult with tracked change entries, total count, and source Word revision IDs when available.
+Returns a TrackChangesListResult with tracked change entries, total count, and raw imported Word OOXML revision IDs (`w:id`) when available.
 
 ## Input fields
 
@@ -168,14 +168,18 @@ Returns a TrackChangesListResult with tracked change entries, total count, and s
           },
           "wordRevisionIds": {
             "additionalProperties": false,
+            "description": "Raw imported Word OOXML revision IDs (`w:id`) from the source document when available. This is provenance metadata, not the canonical SuperDoc tracked-change ID. Replacements may include both `insert` and `delete` IDs.",
             "properties": {
               "delete": {
+                "description": "Raw imported Word OOXML revision ID (`w:id`) from a `<w:del>` element when this logical change includes a deletion.",
                 "type": "string"
               },
               "format": {
+                "description": "Raw imported Word OOXML revision ID (`w:id`) from a `<w:rPrChange>` element when this logical change includes a formatting revision.",
                 "type": "string"
               },
               "insert": {
+                "description": "Raw imported Word OOXML revision ID (`w:id`) from a `<w:ins>` element when this logical change includes an insertion.",
                 "type": "string"
               }
             },

packages/document-api/src/README.md

@@ -711,7 +711,7 @@ List tracked changes in the document. Supports filtering by `type` and paginatio
 Retrieve full information for a single tracked change by its canonical ID. Throws `TARGET_NOT_FOUND` when the ID is invalid.
 
 - **Input**: `TrackChangesGetInput` (`{ id }`)
-- **Output**: `TrackChangeInfo` (includes `wordRevisionIds` when imported source OOXML revision IDs are available)
+- **Output**: `TrackChangeInfo` (includes `wordRevisionIds` with raw imported Word OOXML `w:id` values when available)
 - **Mutates**: No
 - **Idempotency**: idempotent
 

packages/document-api/src/contract/operation-definitions.ts

@@ -2215,7 +2215,7 @@ export const OPERATION_DEFINITIONS = {
     memberPath: 'trackChanges.list',
     description: 'List all tracked changes in the document.',
     expectedResult:
-      'Returns a TrackChangesListResult with tracked change entries, total count, and source Word revision IDs when available.',
+      'Returns a TrackChangesListResult with tracked change entries, total count, and raw imported Word OOXML revision IDs (`w:id`) when available.',
     requiresDocumentContext: true,
     metadata: readOperation({
       idempotency: 'idempotent',
@@ -2230,7 +2230,7 @@ export const OPERATION_DEFINITIONS = {
     memberPath: 'trackChanges.get',
     description: 'Retrieve a single tracked change by ID.',
     expectedResult:
-      'Returns a TrackChangeInfo object with the change type, author, date, affected content, and source Word revision IDs when available.',
+      'Returns a TrackChangeInfo object with the change type, author, date, affected content, and raw imported Word OOXML revision IDs (`w:id`) when available.',
     requiresDocumentContext: true,
     metadata: readOperation({
       idempotency: 'idempotent',

packages/document-api/src/contract/schemas.ts

@@ -1478,11 +1478,27 @@ const commentDomainItemSchema = discoveryItemSchema(
 
 const commentsListResultSchema = discoveryResultSchema(commentDomainItemSchema);
 
-const trackChangeWordRevisionIdsSchema = objectSchema({
-  insert: { type: 'string' },
-  delete: { type: 'string' },
-  format: { type: 'string' },
-});
+const trackChangeWordRevisionIdsSchema: JsonSchema = {
+  ...objectSchema({
+    insert: {
+      type: 'string',
+      description:
+        'Raw imported Word OOXML revision ID (`w:id`) from a `<w:ins>` element when this logical change includes an insertion.',
+    },
+    delete: {
+      type: 'string',
+      description:
+        'Raw imported Word OOXML revision ID (`w:id`) from a `<w:del>` element when this logical change includes a deletion.',
+    },
+    format: {
+      type: 'string',
+      description:
+        'Raw imported Word OOXML revision ID (`w:id`) from a `<w:rPrChange>` element when this logical change includes a formatting revision.',
+    },
+  }),
+  description:
+    'Raw imported Word OOXML revision IDs (`w:id`) from the source document when available. This is provenance metadata, not the canonical SuperDoc tracked-change ID. Replacements may include both `insert` and `delete` IDs.',
+};
 
 const trackChangeInfoSchema = objectSchema(
   {

packages/document-api/src/types/track-changes.types.ts

@@ -3,9 +3,18 @@ import type { DiscoveryOutput } from './discovery.js';
 
 export type TrackChangeType = 'insert' | 'delete' | 'format';
 
+/**
+ * Raw imported Word OOXML revision IDs (`w:id`) from the source document when available.
+ *
+ * This is provenance metadata, not the canonical SuperDoc tracked-change ID.
+ * Replacements may include both `insert` and `delete` IDs.
+ */
 export interface TrackChangeWordRevisionIds {
+  /** Raw imported Word OOXML revision ID (`w:id`) from a `<w:ins>` element when present. */
   insert?: string;
+  /** Raw imported Word OOXML revision ID (`w:id`) from a `<w:del>` element when present. */
   delete?: string;
+  /** Raw imported Word OOXML revision ID (`w:id`) from a `<w:rPrChange>` element when present. */
   format?: string;
 }
 
@@ -14,6 +23,7 @@ export interface TrackChangeInfo {
   /** Convenience alias for `address.entityId`. */
   id: string;
   type: TrackChangeType;
+  /** Raw imported Word OOXML revision IDs (`w:id`) from the source document when available. */
   wordRevisionIds?: TrackChangeWordRevisionIds;
   author?: string;
   authorEmail?: string;
@@ -34,6 +44,7 @@ export interface TrackChangesListQuery {
 export interface TrackChangeDomain {
   address: TrackedChangeAddress;
   type: TrackChangeType;
+  /** Raw imported Word OOXML revision IDs (`w:id`) from the source document when available. */
   wordRevisionIds?: TrackChangeWordRevisionIds;
   author?: string;
   authorEmail?: string;