@ansonlai/docx-redline-js 0.8.3 → 0.9.0

package/services/document-operation-contract.js

@@ -1,537 +1,628 @@
-/**
- * Public document-operation normalization and validation.
- *
- * Keep compatibility aliases at this boundary so the runner and preflight
- * logic can operate on one internal shape.
- */
-
-import { validateExactReplacementRequests } from './localized-replacement-compiler.js';
-
-const SUPPORTED_OPERATION_TYPES = new Set([
-    'redline',
-    'replace',
-    'format',
-    'character-format',
-    'paragraph-format',
-    'list-change',
-    'table-reconciliation',
-    'insert',
-    'restore',
-    'delete',
-    'comment',
-    'comment_reply',
-    'comment_resolve',
-    'highlight'
-]);
-
-export const EXISTING_REVISIONS_POLICIES = Object.freeze([
-    'merge-same-author',
-    'slice-cross-author',
-    'reject-input',
-    'accept-all-first',
-    'accept-all-first-keep-normalized'
-]);
-
-export function isExistingRevisionsPolicy(value) {
-    return EXISTING_REVISIONS_POLICIES.includes(value);
-}
-
-function isRecord(value) {
-    return !!value && typeof value === 'object' && !Array.isArray(value);
-}
-
-function nonEmptyString(value) {
-    return typeof value === 'string' && value.trim().length > 0;
-}
-
-/** Operations that address an existing comment thread by id instead of targeting a paragraph. */
-export function isCommentThreadOperationKind(kind) {
-    return kind === 'comment_reply' || kind === 'comment_resolve';
-}
-
-export function getCanonicalOperationType(operation) {
-    const type = operation?.type;
-    if (type === 'insert' && operation?.target?.revisionView === 'rejected') return 'rejected-insert';
-    if (type === 'restore') return 'restore';
-    if (type === 'comment' || type === 'comment_reply' || type === 'comment_resolve' || type === 'highlight') return type;
-    if (type === 'paragraph-format') return 'paragraph-format';
-    if (type === 'character-format' || (type === 'format' && (operation?.textToFormat != null || operation?.properties != null))) return 'format';
-    return 'redline';
-}
-
-export function normalizeTargetDescriptor(target, legacyTargetRef = null, defaultRevisionView = 'accepted') {
-    const fallbackRevisionView = defaultRevisionView === 'rejected' ? 'rejected' : 'accepted';
-    if (!isRecord(target)) {
-        return {
-            text: typeof target === 'string' ? target : '',
-            index: legacyTargetRef ?? null,
-            paragraphId: null,
-            occurrence: null,
-            inTable: null,
-            fingerprint: null,
-            revisionView: fallbackRevisionView
-        };
-    }
-
-    return {
-        text: typeof target.exactText === 'string'
-            ? target.exactText
-            : (typeof target.text === 'string' ? target.text : ''),
-        index: target.index ?? target.paragraphIndex ?? legacyTargetRef ?? null,
-        paragraphId: nonEmptyString(target.paragraphId) ? target.paragraphId.trim() : null,
-        occurrence: Number.isInteger(target.occurrence) && target.occurrence > 0
-            ? target.occurrence
-            : null,
-        inTable: typeof target.inTable === 'boolean' ? target.inTable : null,
-        fingerprint: nonEmptyString(target.fingerprint)
-            ? target.fingerprint.trim()
-            : (nonEmptyString(target.sourceFingerprint) ? target.sourceFingerprint.trim() : null),
-        revisionView: target.revisionView === 'rejected'
-            ? 'rejected'
-            : (target.revisionView === 'accepted' ? 'accepted' : fallbackRevisionView),
-        captureRef: nonEmptyString(target.captureRef) ? target.captureRef.trim() : null,
-        select: typeof target.select === 'string' ? target.select : null
-    };
-}
-
-export function normalizeDocumentOperation(operation) {
-    const source = isRecord(operation) ? operation : {};
-    const kind = getCanonicalOperationType(source);
-    const defaultRevisionView = kind === 'restore' ? 'rejected' : 'accepted';
-    const targetDescriptor = normalizeTargetDescriptor(source.target, source.targetRef, defaultRevisionView);
-    const targetEndDescriptor = source.targetEnd != null
-        ? normalizeTargetDescriptor(source.targetEnd, source.targetEndRef, defaultRevisionView)
-        : null;
-
-    return {
-        ...source,
-        operationId: nonEmptyString(source.operationId) ? source.operationId.trim() : null,
-        captureKey: nonEmptyString(source.captureKey) ? source.captureKey.trim() : null,
-        operationKind: kind,
-        anchor: isRecord(source.anchor) ? {
-            exactText: typeof source.anchor.exactText === 'string' ? source.anchor.exactText : '',
-            occurrence: Number.isInteger(source.anchor.occurrence) && source.anchor.occurrence > 0 ? source.anchor.occurrence : 1,
-            occurrenceExplicit: Number.isInteger(source.anchor.occurrence) && source.anchor.occurrence > 0,
-            offset: Number.isInteger(source.anchor.offset) ? source.anchor.offset : null
-        } : null,
-        targetDescriptor,
-        targetEndDescriptor,
-        target: targetDescriptor.text,
-        targetRef: targetDescriptor.index,
-        targetEndRef: targetEndDescriptor?.index ?? source.targetEndRef ?? null,
-        ...(source.type === 'delete' && source.modified == null ? { modified: '' } : {})
-    };
-}
-
-export function validateDocumentOperation(operation) {
-    if (!isRecord(operation)) {
-        return {
-            valid: false,
-            error: { code: 'INVALID_OPERATION', message: 'Operation must be an object.' }
-        };
-    }
-
-    const rawType = operation.type;
-    if (rawType != null && rawType !== '' && !SUPPORTED_OPERATION_TYPES.has(rawType)) {
-        return {
-            valid: false,
-            error: {
-                code: 'INVALID_OPERATION',
-                message: `Unsupported operation type: "${String(rawType)}".`
-            }
-        };
-    }
-
-    const normalized = normalizeDocumentOperation(operation);
-    if (isRecord(operation.target) && operation.target.revisionView != null) {
-        if (operation.target.revisionView !== 'accepted' && operation.target.revisionView !== 'rejected') {
-            return {
-                valid: false,
-                error: {
-                    code: 'INVALID_OPERATION',
-                    message: 'Target revisionView must be "accepted" or "rejected" when provided.'
-                }
-            };
-        }
-    }
-
-    if (isRecord(operation.targetEnd) && operation.targetEnd.revisionView != null) {
-        if (operation.targetEnd.revisionView !== 'accepted' && operation.targetEnd.revisionView !== 'rejected') {
-            return {
-                valid: false,
-                error: {
-                    code: 'INVALID_OPERATION',
-                    message: 'Target revisionView must be "accepted" or "rejected" when provided.'
-                }
-            };
-        }
-    }
-
-    if (operation.operationId != null && (!nonEmptyString(operation.operationId) || operation.operationId.trim().length > 256)) {
-        return {
-            valid: false,
-            error: { code: 'INVALID_OPERATION', message: 'operationId must be a non-empty string under 256 characters when provided.' }
-        };
-    }
-
-    if (operation.captureKey != null && (!nonEmptyString(operation.captureKey) || operation.captureKey.trim().length > 256)) {
-        return {
-            valid: false,
-            error: { code: 'INVALID_OPERATION', message: 'captureKey must be a non-empty string under 256 characters when provided.' }
-        };
-    }
-
-    if (isRecord(operation.target) && operation.target.captureRef != null && (!nonEmptyString(operation.target.captureRef) || operation.target.captureRef.trim().length > 256)) {
-        return {
-            valid: false,
-            error: { code: 'INVALID_OPERATION', message: 'target.captureRef must be a non-empty string under 256 characters when provided.' }
-        };
-    }
-
-    if (isRecord(operation.target) && operation.target.select != null && typeof operation.target.select !== 'string') {
-        return {
-            valid: false,
-            error: { code: 'INVALID_OPERATION', message: 'target.select must be a string when provided.' }
-        };
-    }
-
-    const target = normalized.targetDescriptor;
-    if (
-        !isCommentThreadOperationKind(normalized.operationKind)
-        && !nonEmptyString(target.text)
-        && target.index == null
-        && !target.paragraphId
-        && !target.fingerprint
-        && !target.captureRef
-    ) {
-        return {
-            valid: false,
-            error: {
-                code: 'INVALID_OPERATION',
-                message: 'Operation target must provide text, a paragraph index, a paragraphId, or a captureRef.'
-            }
-        };
-    }
-
-    if (target.occurrence != null && !nonEmptyString(target.text)) {
-        return {
-            valid: false,
-            error: {
-                code: 'INVALID_OPERATION',
-                message: 'Target occurrence requires target text.'
-            }
-        };
-    }
-
-    if (normalized.operationKind === 'redline') {
-        const hasModified = typeof normalized.modified === 'string';
-        const hasReplacements = normalized.replacements !== undefined;
-        if (hasModified === hasReplacements) {
-            return {
-                valid: false,
-                error: {
-                    code: 'INVALID_OPERATION',
-                    message: 'Redline operations require exactly one of string "modified" or non-empty "replacements".'
-                }
-            };
-        }
-        if (hasReplacements) {
-            if (rawType != null && rawType !== '' && !['redline', 'replace'].includes(rawType)) {
-                return {
-                    valid: false,
-                    error: {
-                        code: 'INVALID_OPERATION',
-                        message: 'Localized replacements are supported only for redline or replace operations.'
-                    }
-                };
-            }
-            if (
-                target.revisionView !== 'accepted'
-                || target.captureRef
-                || target.occurrence != null
-                || normalized.captureKey
-                || normalized.targetEndDescriptor
-                || normalized.targetEndRef != null
-                || /\r|\n/.test(target.text || '')
-            ) {
-                return {
-                    valid: false,
-                    error: {
-                        code: 'INVALID_OPERATION',
-                        message: 'Localized replacements v1 require one batch-start accepted-view paragraph target without captures, target occurrence, or a target range.'
-                    }
-                };
-            }
-            const replacementValidation = validateExactReplacementRequests(normalized.replacements);
-            if (!replacementValidation.ok) {
-                return { valid: false, error: replacementValidation.error };
-            }
-            if (replacementValidation.replacements.some(replacement => /\r|\n/.test(replacement.replace))) {
-                return {
-                    valid: false,
-                    error: {
-                        code: 'INVALID_OPERATION',
-                        message: 'Localized replacements v1 cannot insert paragraph breaks.'
-                    }
-                };
-            }
-            normalized.replacements = replacementValidation.replacements;
-        }
-    }
-
-    if (normalized.operationKind === 'rejected-insert') {
-        if (!nonEmptyString(normalized.modified)) {
-            return {
-                valid: false,
-                error: { code: 'INVALID_OPERATION', message: 'Rejected-view insert operations require non-empty string "modified" text.' }
-            };
-        }
-        if (
-            !normalized.anchor
-            || !nonEmptyString(normalized.anchor.exactText)
-            || !Number.isInteger(normalized.anchor.offset)
-            || normalized.anchor.offset < 0
-            || normalized.anchor.offset > normalized.anchor.exactText.length
-        ) {
-            return {
-                valid: false,
-                error: {
-                    code: 'INVALID_OPERATION',
-                    message: 'Rejected-view insert operations require anchor.exactText, a positive occurrence, and an offset within the anchor text.'
-                }
-            };
-        }
-        if (normalized.existingRevisions !== 'slice-cross-author') {
-            return {
-                valid: false,
-                error: {
-                    code: 'INVALID_OPERATION',
-                    message: 'Rejected-view insert operations require existingRevisions: "slice-cross-author".'
-                }
-            };
-        }
-    }
-
-    if (normalized.operationKind === 'restore') {
-        const hasModified = operation.modified !== undefined;
-        const hasReplacements = operation.replacements !== undefined;
-        const validSingle = nonEmptyString(normalized.modified);
-        const validRange = Array.isArray(normalized.modified)
-            && normalized.modified.length > 0
-            && normalized.modified.every(nonEmptyString);
-        if (hasModified && hasReplacements) {
-            return {
-                valid: false,
-                error: {
-                    code: 'INVALID_OPERATION',
-                    message: 'Restore operations accept modified or replacements, not both.'
-                }
-            };
-        }
-        if (hasModified && !validSingle && !validRange) {
-            return {
-                valid: false,
-                error: {
-                    code: 'INVALID_OPERATION',
-                    message: 'Restore modified must be a non-empty string or non-empty string array.'
-                }
-            };
-        }
-        if (!hasModified) {
-            if (
-                target.revisionView !== 'rejected'
-                || (!target.paragraphId && !target.fingerprint)
-                || target.captureRef
-                || target.occurrence != null
-                || normalized.captureKey
-                || normalized.targetEndDescriptor
-                || normalized.targetEndRef != null
-                || /\r|\n/.test(target.text || '')
-            ) {
-                return {
-                    valid: false,
-                    error: {
-                        code: 'INVALID_OPERATION',
-                        message: 'Verbatim and localized restore require one strong batch-start rejected-view paragraph target without captures, target occurrence, or a target range.'
-                    }
-                };
-            }
-        }
-        if (hasReplacements) {
-            const replacementValidation = validateExactReplacementRequests(normalized.replacements);
-            if (!replacementValidation.ok) {
-                return { valid: false, error: replacementValidation.error };
-            }
-            if (replacementValidation.replacements.some(replacement => /\r|\n/.test(replacement.replace))) {
-                return {
-                    valid: false,
-                    error: {
-                        code: 'INVALID_OPERATION',
-                        message: 'Localized restore cannot insert paragraph breaks.'
-                    }
-                };
-            }
-            normalized.replacements = replacementValidation.replacements;
-        }
-        if (normalized.generateRedlines === false) {
-            return {
-                valid: false,
-                error: {
-                    code: 'INVALID_OPERATION',
-                    message: 'Restore operations require tracked changes and cannot set generateRedlines to false.'
-                }
-            };
-        }
-    }
-
-    if (normalized.structuredContent != null && typeof normalized.structuredContent !== 'boolean') {
-        return {
-            valid: false,
-            error: { code: 'INVALID_OPERATION', message: 'structuredContent must be a boolean when provided.' }
-        };
-    }
-
-    if (normalized.pairReplacements != null && typeof normalized.pairReplacements !== 'boolean') {
-        return {
-            valid: false,
-            error: { code: 'INVALID_OPERATION', message: 'pairReplacements must be a boolean when provided.' }
-        };
-    }
-
-    if (normalized.existingRevisions != null && !isExistingRevisionsPolicy(normalized.existingRevisions)) {
-        return {
-            valid: false,
-            error: {
-                code: 'INVALID_OPERATION',
-                message: `existingRevisions must be one of: ${EXISTING_REVISIONS_POLICIES.join(', ')}.`
-            }
-        };
-    }
-
-    if (normalized.insertionAffinity != null) {
-        if (!isRecord(normalized.insertionAffinity)) {
-            return {
-                valid: false,
-                error: { code: 'INVALID_OPERATION', message: 'insertionAffinity must be an object when provided.' }
-            };
-        }
-        const { formatting, hyperlink, revision, bookmark, comment } = normalized.insertionAffinity;
-        if (formatting != null && !['left', 'right', 'none'].includes(formatting)) {
-            return {
-                valid: false,
-                error: { code: 'INVALID_OPERATION', message: 'insertionAffinity.formatting must be "left", "right", or "none".' }
-            };
-        }
-        if (hyperlink != null && !['inside', 'outside', 'preserve'].includes(hyperlink)) {
-            return {
-                valid: false,
-                error: { code: 'INVALID_OPERATION', message: 'insertionAffinity.hyperlink must be "inside", "outside", or "preserve".' }
-            };
-        }
-        if (revision != null && !['coalesce_same_author', 'separate'].includes(revision)) {
-            return {
-                valid: false,
-                error: { code: 'INVALID_OPERATION', message: 'insertionAffinity.revision must be "coalesce_same_author" or "separate".' }
-            };
-        }
-        if (bookmark != null && !['inside', 'outside'].includes(bookmark)) {
-            return {
-                valid: false,
-                error: { code: 'INVALID_OPERATION', message: 'insertionAffinity.bookmark must be "inside" or "outside".' }
-            };
-        }
-        if (comment != null && !['inside', 'outside'].includes(comment)) {
-            return {
-                valid: false,
-                error: { code: 'INVALID_OPERATION', message: 'insertionAffinity.comment must be "inside" or "outside".' }
-            };
-        }
-    }
-
-    if (normalized.operationKind === 'comment') {
-        if (!nonEmptyString(normalized.commentContent)) {
-            return {
-                valid: false,
-                error: { code: 'INVALID_OPERATION', message: 'Comment operations require a non-empty "commentContent" field.' }
-            };
-        }
-    }
-
-    if (normalized.operationKind === 'comment_reply') {
-        if (!nonEmptyString(String(normalized.parentCommentId ?? ''))) {
-            return { valid: false, error: { code: 'INVALID_OPERATION', message: 'Comment reply operations require a "parentCommentId".' } };
-        }
-        if (!nonEmptyString(normalized.commentContent)) {
-            return { valid: false, error: { code: 'INVALID_OPERATION', message: 'Comment reply operations require a non-empty "commentContent" field.' } };
-        }
-    }
-
-    if (normalized.operationKind === 'comment_resolve') {
-        if (!nonEmptyString(String(normalized.commentId ?? ''))) {
-            return { valid: false, error: { code: 'INVALID_OPERATION', message: 'Comment resolve operations require a "commentId".' } };
-        }
-        if (normalized.resolved != null && typeof normalized.resolved !== 'boolean') {
-            return { valid: false, error: { code: 'INVALID_OPERATION', message: 'Comment resolve "resolved" must be a boolean when provided.' } };
-        }
-    }
-
-    if (normalized.operationKind === 'highlight') {
-        if (!nonEmptyString(normalized.textToHighlight)) {
-            return {
-                valid: false,
-                error: { code: 'INVALID_OPERATION', message: 'Highlight operations require a non-empty "textToHighlight" field.' }
-            };
-        }
-        if (normalized.color != null && !nonEmptyString(normalized.color)) {
-            return {
-                valid: false,
-                error: { code: 'INVALID_OPERATION', message: 'Highlight color must be a non-empty string when provided.' }
-            };
-        }
-    }
-
-    if (normalized.operationKind === 'format') {
-        if (!nonEmptyString(normalized.textToFormat)) {
-            return {
-                valid: false,
-                error: { code: 'INVALID_OPERATION', message: 'Format operations require a non-empty "textToFormat" field.' }
-            };
-        }
-        if (!isRecord(normalized.properties)) {
-            return {
-                valid: false,
-                error: { code: 'INVALID_OPERATION', message: 'Format operations require a "properties" object.' }
-            };
-        }
-        if (normalized.formattingRevisionPolicy != null && !['always', 'coalesce-own-insertion'].includes(normalized.formattingRevisionPolicy)) {
-            return {
-                valid: false,
-                error: { code: 'INVALID_OPERATION', message: 'formattingRevisionPolicy must be "always" or "coalesce-own-insertion".' }
-            };
-        }
-    }
-
-    if (normalized.operationKind === 'paragraph-format') {
-        if (!isRecord(normalized.properties)) {
-            return {
-                valid: false,
-                error: { code: 'INVALID_OPERATION', message: 'Paragraph-format operations require a "properties" object.' }
-            };
-        }
-    }
-
-    if (normalized.author != null && !nonEmptyString(normalized.author)) {
-        return {
-            valid: false,
-            error: { code: 'INVALID_OPERATION', message: 'Operation author must be a non-empty string when provided.' }
-        };
-    }
-
-    return { valid: true, operation: normalized };
-}
-
-export function resolveDocumentOperationAuthor(operation, batchAuthor, fallbackAuthor) {
-    if (nonEmptyString(operation?.author)) return operation.author.trim();
-    if (nonEmptyString(batchAuthor)) return batchAuthor.trim();
-    return nonEmptyString(fallbackAuthor) ? fallbackAuthor.trim() : 'Author';
-}
+/**
+ * Public document-operation normalization and validation.
+ *
+ * Keep compatibility aliases at this boundary so the runner and preflight
+ * logic can operate on one internal shape.
+ */
+
+import { validateExactReplacementRequests } from './localized-replacement-compiler.js';
+import { validateParagraphNumberingShape, findUnknownParagraphFormatKeys, PARAGRAPH_FORMAT_PROPERTY_KEYS } from './list-conversion-diagnostics.js';
+import { validateListFormatShape } from './list-format.js';
+
+const SUPPORTED_OPERATION_TYPES = new Set([
+    'redline',
+    'replace',
+    'format',
+    'character-format',
+    'paragraph-format',
+    'list-format',
+    'list-change',
+    'table-reconciliation',
+    'insert',
+    'restore',
+    'delete',
+    'comment',
+    'comment_reply',
+    'comment_resolve',
+    'highlight'
+]);
+
+export const EXISTING_REVISIONS_POLICIES = Object.freeze([
+    'merge-same-author',
+    'slice-cross-author',
+    'reject-input',
+    'accept-all-first',
+    'accept-all-first-keep-normalized'
+]);
+
+export function isExistingRevisionsPolicy(value) {
+    return EXISTING_REVISIONS_POLICIES.includes(value);
+}
+
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+
+/** Operations that address an existing comment thread by id instead of targeting a paragraph. */
+export function isCommentThreadOperationKind(kind) {
+    return kind === 'comment_reply' || kind === 'comment_resolve';
+}
+
+export function getCanonicalOperationType(operation) {
+    const type = operation?.type;
+    if (type === 'insert' && operation?.target?.revisionView === 'rejected') return 'rejected-insert';
+    if (type === 'restore') return 'restore';
+    if (type === 'comment' || type === 'comment_reply' || type === 'comment_resolve' || type === 'highlight') return type;
+    if (type === 'paragraph-format') return 'paragraph-format';
+    if (type === 'list-format') return 'list-format';
+    if (type === 'character-format' || (type === 'format' && (operation?.textToFormat != null || operation?.properties != null))) return 'format';
+    return 'redline';
+}
+
+export function normalizeTargetDescriptor(target, legacyTargetRef = null, defaultRevisionView = 'accepted') {
+    const fallbackRevisionView = defaultRevisionView === 'rejected' ? 'rejected' : 'accepted';
+    if (!isRecord(target)) {
+        return {
+            text: typeof target === 'string' ? target : '',
+            index: legacyTargetRef ?? null,
+            paragraphId: null,
+            occurrence: null,
+            inTable: null,
+            fingerprint: null,
+            revisionView: fallbackRevisionView
+        };
+    }
+
+    return {
+        text: typeof target.exactText === 'string'
+            ? target.exactText
+            : (typeof target.text === 'string' ? target.text : ''),
+        index: target.index ?? target.paragraphIndex ?? legacyTargetRef ?? null,
+        paragraphId: nonEmptyString(target.paragraphId) ? target.paragraphId.trim() : null,
+        occurrence: Number.isInteger(target.occurrence) && target.occurrence > 0
+            ? target.occurrence
+            : null,
+        inTable: typeof target.inTable === 'boolean' ? target.inTable : null,
+        fingerprint: nonEmptyString(target.fingerprint)
+            ? target.fingerprint.trim()
+            : (nonEmptyString(target.sourceFingerprint) ? target.sourceFingerprint.trim() : null),
+        revisionView: target.revisionView === 'rejected'
+            ? 'rejected'
+            : (target.revisionView === 'accepted' ? 'accepted' : fallbackRevisionView),
+        captureRef: nonEmptyString(target.captureRef) ? target.captureRef.trim() : null,
+        select: typeof target.select === 'string' ? target.select : null
+    };
+}
+
+export function normalizeDocumentOperation(operation) {
+    const source = isRecord(operation) ? operation : {};
+    const kind = getCanonicalOperationType(source);
+    const defaultRevisionView = kind === 'restore' ? 'rejected' : 'accepted';
+    const targetDescriptor = normalizeTargetDescriptor(source.target, source.targetRef, defaultRevisionView);
+    const targetEndDescriptor = source.targetEnd != null
+        ? normalizeTargetDescriptor(source.targetEnd, source.targetEndRef, defaultRevisionView)
+        : null;
+
+    return {
+        ...source,
+        operationId: nonEmptyString(source.operationId) ? source.operationId.trim() : null,
+        captureKey: nonEmptyString(source.captureKey) ? source.captureKey.trim() : null,
+        operationKind: kind,
+        anchor: isRecord(source.anchor) ? {
+            exactText: typeof source.anchor.exactText === 'string' ? source.anchor.exactText : '',
+            occurrence: Number.isInteger(source.anchor.occurrence) && source.anchor.occurrence > 0 ? source.anchor.occurrence : 1,
+            occurrenceExplicit: Number.isInteger(source.anchor.occurrence) && source.anchor.occurrence > 0,
+            offset: Number.isInteger(source.anchor.offset) ? source.anchor.offset : null
+        } : null,
+        targetDescriptor,
+        targetEndDescriptor,
+        target: targetDescriptor.text,
+        targetRef: targetDescriptor.index,
+        targetEndRef: targetEndDescriptor?.index ?? source.targetEndRef ?? null,
+        ...(source.type === 'delete' && source.modified == null ? { modified: '' } : {})
+    };
+}
+
+export function validateDocumentOperation(operation) {
+    if (!isRecord(operation)) {
+        return {
+            valid: false,
+            error: { code: 'INVALID_OPERATION', message: 'Operation must be an object.' }
+        };
+    }
+
+    const rawType = operation.type;
+    if (rawType != null && rawType !== '' && !SUPPORTED_OPERATION_TYPES.has(rawType)) {
+        return {
+            valid: false,
+            error: {
+                code: 'INVALID_OPERATION',
+                message: `Unsupported operation type: "${String(rawType)}".`
+            }
+        };
+    }
+
+    const normalized = normalizeDocumentOperation(operation);
+    if (isRecord(operation.target) && operation.target.revisionView != null) {
+        if (operation.target.revisionView !== 'accepted' && operation.target.revisionView !== 'rejected') {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'Target revisionView must be "accepted" or "rejected" when provided.'
+                }
+            };
+        }
+    }
+
+    if (isRecord(operation.targetEnd) && operation.targetEnd.revisionView != null) {
+        if (operation.targetEnd.revisionView !== 'accepted' && operation.targetEnd.revisionView !== 'rejected') {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'Target revisionView must be "accepted" or "rejected" when provided.'
+                }
+            };
+        }
+    }
+
+    if (operation.operationId != null && (!nonEmptyString(operation.operationId) || operation.operationId.trim().length > 256)) {
+        return {
+            valid: false,
+            error: { code: 'INVALID_OPERATION', message: 'operationId must be a non-empty string under 256 characters when provided.' }
+        };
+    }
+
+    if (operation.captureKey != null && (!nonEmptyString(operation.captureKey) || operation.captureKey.trim().length > 256)) {
+        return {
+            valid: false,
+            error: { code: 'INVALID_OPERATION', message: 'captureKey must be a non-empty string under 256 characters when provided.' }
+        };
+    }
+
+    if (isRecord(operation.target) && operation.target.captureRef != null && (!nonEmptyString(operation.target.captureRef) || operation.target.captureRef.trim().length > 256)) {
+        return {
+            valid: false,
+            error: { code: 'INVALID_OPERATION', message: 'target.captureRef must be a non-empty string under 256 characters when provided.' }
+        };
+    }
+
+    if (isRecord(operation.target) && operation.target.select != null && typeof operation.target.select !== 'string') {
+        return {
+            valid: false,
+            error: { code: 'INVALID_OPERATION', message: 'target.select must be a string when provided.' }
+        };
+    }
+
+    const target = normalized.targetDescriptor;
+    if (
+        !isCommentThreadOperationKind(normalized.operationKind)
+        && !nonEmptyString(target.text)
+        && target.index == null
+        && !target.paragraphId
+        && !target.fingerprint
+        && !target.captureRef
+    ) {
+        return {
+            valid: false,
+            error: {
+                code: 'INVALID_OPERATION',
+                message: 'Operation target must provide text, a paragraph index, a paragraphId, or a captureRef.'
+            }
+        };
+    }
+
+    if (target.occurrence != null && !nonEmptyString(target.text)) {
+        return {
+            valid: false,
+            error: {
+                code: 'INVALID_OPERATION',
+                message: 'Target occurrence requires target text.'
+            }
+        };
+    }
+
+    if (normalized.operationKind === 'redline') {
+        const hasModified = typeof normalized.modified === 'string';
+        const hasReplacements = normalized.replacements !== undefined;
+        if (hasModified === hasReplacements) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'Redline operations require exactly one of string "modified" or non-empty "replacements".'
+                }
+            };
+        }
+        if (hasReplacements) {
+            if (rawType != null && rawType !== '' && !['redline', 'replace'].includes(rawType)) {
+                return {
+                    valid: false,
+                    error: {
+                        code: 'INVALID_OPERATION',
+                        message: 'Localized replacements are supported only for redline or replace operations.'
+                    }
+                };
+            }
+            if (
+                target.revisionView !== 'accepted'
+                || target.captureRef
+                || target.occurrence != null
+                || normalized.captureKey
+                || normalized.targetEndDescriptor
+                || normalized.targetEndRef != null
+            ) {
+                return {
+                    valid: false,
+                    error: {
+                        code: 'INVALID_OPERATION',
+                        message: 'Localized replacements v1 require one batch-start accepted-view paragraph target without captures, target occurrence, or a target range.'
+                    }
+                };
+            }
+            const replacementValidation = validateExactReplacementRequests(normalized.replacements);
+            if (!replacementValidation.ok) {
+                return { valid: false, error: replacementValidation.error };
+            }
+            if (replacementValidation.replacements.some(replacement => /\r|\n/.test(replacement.replace))) {
+                return {
+                    valid: false,
+                    error: {
+                        code: 'INVALID_OPERATION',
+                        message: 'Localized replacements v1 cannot insert paragraph breaks.'
+                    }
+                };
+            }
+            // A soft line break (w:br reads as "\n") is not text the localized
+            // diff can delete, so a find spanning one would keep the break.
+            if (replacementValidation.replacements.some(replacement => /\r|\n/.test(replacement.find))) {
+                return {
+                    valid: false,
+                    error: {
+                        code: 'INVALID_OPERATION',
+                        message: 'Localized replacements v1 cannot span a line break; use one replacement per line or a full "modified" paragraph.'
+                    }
+                };
+            }
+            normalized.replacements = replacementValidation.replacements;
+        }
+    }
+
+    if (normalized.operationKind === 'rejected-insert') {
+        if (!nonEmptyString(normalized.modified)) {
+            return {
+                valid: false,
+                error: { code: 'INVALID_OPERATION', message: 'Rejected-view insert operations require non-empty string "modified" text.' }
+            };
+        }
+        if (
+            !normalized.anchor
+            || !nonEmptyString(normalized.anchor.exactText)
+            || !Number.isInteger(normalized.anchor.offset)
+            || normalized.anchor.offset < 0
+            || normalized.anchor.offset > normalized.anchor.exactText.length
+        ) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'Rejected-view insert operations require anchor.exactText, a positive occurrence, and an offset within the anchor text.'
+                }
+            };
+        }
+        if (normalized.existingRevisions !== 'slice-cross-author') {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'Rejected-view insert operations require existingRevisions: "slice-cross-author".'
+                }
+            };
+        }
+    }
+
+    if (normalized.operationKind === 'restore') {
+        const hasModified = operation.modified !== undefined;
+        const hasReplacements = operation.replacements !== undefined;
+        const validSingle = nonEmptyString(normalized.modified);
+        const validRange = Array.isArray(normalized.modified)
+            && normalized.modified.length > 0
+            && normalized.modified.every(nonEmptyString);
+        if (hasModified && hasReplacements) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'Restore operations accept modified or replacements, not both.'
+                }
+            };
+        }
+        if (hasModified && !validSingle && !validRange) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'Restore modified must be a non-empty string or non-empty string array.'
+                }
+            };
+        }
+        if (!hasModified) {
+            if (
+                target.revisionView !== 'rejected'
+                || (!target.paragraphId && !target.fingerprint)
+                || target.captureRef
+                || target.occurrence != null
+                || normalized.captureKey
+                || normalized.targetEndDescriptor
+                || normalized.targetEndRef != null
+                || /\r|\n/.test(target.text || '')
+            ) {
+                return {
+                    valid: false,
+                    error: {
+                        code: 'INVALID_OPERATION',
+                        message: 'Verbatim and localized restore require one strong batch-start rejected-view paragraph target without captures, target occurrence, or a target range.'
+                    }
+                };
+            }
+        }
+        if (hasReplacements) {
+            const replacementValidation = validateExactReplacementRequests(normalized.replacements);
+            if (!replacementValidation.ok) {
+                return { valid: false, error: replacementValidation.error };
+            }
+            if (replacementValidation.replacements.some(replacement => /\r|\n/.test(replacement.replace))) {
+                return {
+                    valid: false,
+                    error: {
+                        code: 'INVALID_OPERATION',
+                        message: 'Localized restore cannot insert paragraph breaks.'
+                    }
+                };
+            }
+            normalized.replacements = replacementValidation.replacements;
+        }
+        if (normalized.generateRedlines === false) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'Restore operations require tracked changes and cannot set generateRedlines to false.'
+                }
+            };
+        }
+    }
+
+    if (normalized.structuredContent != null && typeof normalized.structuredContent !== 'boolean') {
+        return {
+            valid: false,
+            error: { code: 'INVALID_OPERATION', message: 'structuredContent must be a boolean when provided.' }
+        };
+    }
+
+    if (normalized.pairReplacements != null && typeof normalized.pairReplacements !== 'boolean') {
+        return {
+            valid: false,
+            error: { code: 'INVALID_OPERATION', message: 'pairReplacements must be a boolean when provided.' }
+        };
+    }
+
+    if (normalized.listMarkers != null && normalized.listMarkers !== 'literal') {
+        return {
+            valid: false,
+            error: { code: 'INVALID_OPERATION', message: 'listMarkers must be "literal" when provided.' }
+        };
+    }
+
+    if (normalized.existingRevisions != null && !isExistingRevisionsPolicy(normalized.existingRevisions)) {
+        return {
+            valid: false,
+            error: {
+                code: 'INVALID_OPERATION',
+                message: `existingRevisions must be one of: ${EXISTING_REVISIONS_POLICIES.join(', ')}.`
+            }
+        };
+    }
+
+    if (normalized.insertionAffinity != null) {
+        if (!isRecord(normalized.insertionAffinity)) {
+            return {
+                valid: false,
+                error: { code: 'INVALID_OPERATION', message: 'insertionAffinity must be an object when provided.' }
+            };
+        }
+        const { formatting, hyperlink, revision, bookmark, comment } = normalized.insertionAffinity;
+        if (formatting != null && !['left', 'right', 'none'].includes(formatting)) {
+            return {
+                valid: false,
+                error: { code: 'INVALID_OPERATION', message: 'insertionAffinity.formatting must be "left", "right", or "none".' }
+            };
+        }
+        if (hyperlink != null && !['inside', 'outside', 'preserve'].includes(hyperlink)) {
+            return {
+                valid: false,
+                error: { code: 'INVALID_OPERATION', message: 'insertionAffinity.hyperlink must be "inside", "outside", or "preserve".' }
+            };
+        }
+        if (revision != null && !['coalesce_same_author', 'separate'].includes(revision)) {
+            return {
+                valid: false,
+                error: { code: 'INVALID_OPERATION', message: 'insertionAffinity.revision must be "coalesce_same_author" or "separate".' }
+            };
+        }
+        if (bookmark != null && !['inside', 'outside'].includes(bookmark)) {
+            return {
+                valid: false,
+                error: { code: 'INVALID_OPERATION', message: 'insertionAffinity.bookmark must be "inside" or "outside".' }
+            };
+        }
+        if (comment != null && !['inside', 'outside'].includes(comment)) {
+            return {
+                valid: false,
+                error: { code: 'INVALID_OPERATION', message: 'insertionAffinity.comment must be "inside" or "outside".' }
+            };
+        }
+    }
+
+    if (normalized.operationKind === 'comment') {
+        if (!nonEmptyString(normalized.commentContent)) {
+            return {
+                valid: false,
+                error: { code: 'INVALID_OPERATION', message: 'Comment operations require a non-empty "commentContent" field.' }
+            };
+        }
+    }
+
+    if (normalized.operationKind === 'comment_reply') {
+        if (!nonEmptyString(String(normalized.parentCommentId ?? ''))) {
+            return { valid: false, error: { code: 'INVALID_OPERATION', message: 'Comment reply operations require a "parentCommentId".' } };
+        }
+        if (!nonEmptyString(normalized.commentContent)) {
+            return { valid: false, error: { code: 'INVALID_OPERATION', message: 'Comment reply operations require a non-empty "commentContent" field.' } };
+        }
+    }
+
+    if (normalized.operationKind === 'comment_resolve') {
+        if (!nonEmptyString(String(normalized.commentId ?? ''))) {
+            return { valid: false, error: { code: 'INVALID_OPERATION', message: 'Comment resolve operations require a "commentId".' } };
+        }
+        if (normalized.resolved != null && typeof normalized.resolved !== 'boolean') {
+            return { valid: false, error: { code: 'INVALID_OPERATION', message: 'Comment resolve "resolved" must be a boolean when provided.' } };
+        }
+    }
+
+    if (normalized.operationKind === 'highlight') {
+        if (!nonEmptyString(normalized.textToHighlight)) {
+            return {
+                valid: false,
+                error: { code: 'INVALID_OPERATION', message: 'Highlight operations require a non-empty "textToHighlight" field.' }
+            };
+        }
+        if (normalized.color != null && !nonEmptyString(normalized.color)) {
+            return {
+                valid: false,
+                error: { code: 'INVALID_OPERATION', message: 'Highlight color must be a non-empty string when provided.' }
+            };
+        }
+    }
+
+    if (normalized.operationKind === 'format') {
+        if (!nonEmptyString(normalized.textToFormat)) {
+            return {
+                valid: false,
+                error: { code: 'INVALID_OPERATION', message: 'Format operations require a non-empty "textToFormat" field.' }
+            };
+        }
+        if (normalized.textOccurrence != null && (!Number.isInteger(normalized.textOccurrence) || normalized.textOccurrence < 1)) {
+            return {
+                valid: false,
+                error: { code: 'INVALID_OPERATION', message: 'textOccurrence must be a positive integer when provided.' }
+            };
+        }
+        if (!isRecord(normalized.properties)) {
+            return {
+                valid: false,
+                error: { code: 'INVALID_OPERATION', message: 'Format operations require a "properties" object.' }
+            };
+        }
+        if (normalized.formattingRevisionPolicy != null && !['always', 'coalesce-own-insertion'].includes(normalized.formattingRevisionPolicy)) {
+            return {
+                valid: false,
+                error: { code: 'INVALID_OPERATION', message: 'formattingRevisionPolicy must be "always" or "coalesce-own-insertion".' }
+            };
+        }
+    }
+
+    if (normalized.operationKind === 'paragraph-format') {
+        if (!isRecord(normalized.properties)) {
+            return {
+                valid: false,
+                error: { code: 'INVALID_OPERATION', message: 'Paragraph-format operations require a "properties" object.' }
+            };
+        }
+        const unknownKeys = findUnknownParagraphFormatKeys(normalized.properties);
+        if (unknownKeys.length > 0) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: `paragraph-format does not support ${unknownKeys.length === 1 ? 'property' : 'properties'} ${unknownKeys.map(key => `"${key}"`).join(', ')}. Supported: ${PARAGRAPH_FORMAT_PROPERTY_KEYS.join(', ')}.`,
+                    field: `properties.${unknownKeys[0]}`,
+                    properties: unknownKeys,
+                    recovery: { action: 'change_request', hint: `Use only: ${PARAGRAPH_FORMAT_PROPERTY_KEYS.join(', ')}.` }
+                }
+            };
+        }
+        if (normalized.properties.numbering !== undefined) {
+            const shapeError = validateParagraphNumberingShape(normalized.properties.numbering);
+            if (shapeError) {
+                return {
+                    valid: false,
+                    error: {
+                        code: 'INVALID_OPERATION',
+                        message: shapeError,
+                        field: 'properties.numbering',
+                        recovery: { action: 'change_request', hint: 'Pass numbering as { "numId": <existing numId from inspect>, "level": 0 } or null.' }
+                    }
+                };
+            }
+        }
+    }
+
+    if (normalized.operationKind === 'list-format') {
+        const shapeError = validateListFormatShape(normalized.list);
+        if (shapeError) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: shapeError.message,
+                    field: shapeError.field,
+                    recovery: {
+                        action: 'change_request',
+                        hint: 'Pass list as { "mode": "convert-plain" } (optional format, kind, level, strip "marker" | "none", start with strip "none"), { "mode": "change-format", "format": ... } (optional kind, lvlText, start, level, scope "list" | "range") or { "mode": "join", "continueFrom": { "paragraphId": ... } } (optional scope).'
+                    }
+                }
+            };
+        }
+        if (operation.modified !== undefined || operation.replacements !== undefined) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'list-format changes list structure only; express text changes as a separate redline operation.',
+                    field: operation.modified !== undefined ? 'modified' : 'replacements'
+                }
+            };
+        }
+        if (target.captureRef || target.occurrence != null || target.revisionView !== 'accepted') {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'list-format v1 targets batch-start accepted-view paragraphs without captures or target occurrence.'
+                }
+            };
+        }
+    }
+
+    if (normalized.author != null && !nonEmptyString(normalized.author)) {
+        return {
+            valid: false,
+            error: { code: 'INVALID_OPERATION', message: 'Operation author must be a non-empty string when provided.' }
+        };
+    }
+
+    return { valid: true, operation: normalized };
+}
+
+export function resolveDocumentOperationAuthor(operation, batchAuthor, fallbackAuthor) {
+    if (nonEmptyString(operation?.author)) return operation.author.trim();
+    if (nonEmptyString(batchAuthor)) return batchAuthor.trim();
+    return nonEmptyString(fallbackAuthor) ? fallbackAuthor.trim() : 'Author';
+}