@ansonlai/docx-redline-js 0.5.2 → 0.5.4

package/docs/schemas/document-operations.schema.json

@@ -28,6 +28,16 @@
       "additionalProperties": false
     },
     "operationArray": { "type": "array", "items": { "$ref": "#/$defs/operation" } },
+    "rejectedTextInsertionAnchor": {
+      "type": "object",
+      "required": ["exactText", "offset"],
+      "properties": {
+        "exactText": { "type": "string", "minLength": 1 },
+        "occurrence": { "type": "integer", "minimum": 1 },
+        "offset": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
     "target": {
       "oneOf": [
         { "type": "string", "minLength": 1 },
@@ -86,7 +96,10 @@
           "additionalProperties": false
         },
         {
-          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["modified"], "properties": { "type": { "enum": ["redline", "replace", "format", "list-change", "table-reconciliation", "insert"] }, "modified": { "type": "string" }, "structuredContent": { "type": "boolean" }, "targetEnd": { "$ref": "#/$defs/target" }, "targetEndRef": { "type": ["integer", "string", "null"] } } } ]
+          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["modified"], "properties": { "type": { "enum": ["redline", "replace", "format", "list-change", "table-reconciliation", "insert"] }, "modified": { "type": "string" }, "structuredContent": { "type": "boolean" }, "targetEnd": { "$ref": "#/$defs/target" }, "targetEndRef": { "type": ["integer", "string", "null"] }, "anchor": { "$ref": "#/$defs/rejectedTextInsertionAnchor" } } } ]
+        },
+        {
+          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["modified"], "properties": { "type": { "const": "restore" }, "modified": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } } ] }, "targetEnd": { "$ref": "#/$defs/target" }, "targetEndRef": { "type": ["integer", "string", "null"] } } } ]
         },
         {
           "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "properties": { "type": { "const": "delete" }, "modified": { "const": "" } } } ]

package/engine/oxml-engine.js

@@ -40,6 +40,7 @@ import { getDocumentParagraphs } from './format-extraction.js';
 import { isDiffTokenLimitError } from '../pipeline/diff-engine.js';
 import { NumberingService } from '../services/numbering-service.js';
 import { recordRouteSelection } from './route-selection.js';
+import { inspectForeignDeletedParagraphTarget } from '../core/paragraph-revision-safety.js';
 
 function getCommentIdsInOoxml(node) {
     const ids = new Set();
@@ -138,9 +139,29 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
     const revisionIdAllocator = options?._revisionIdAllocator instanceof RevisionIdAllocator
         ? options._revisionIdAllocator
         : new RevisionIdAllocator();
-    seedRevisionIdsFromDocument(xmlDoc, revisionIdAllocator);
-
-    if (containsTrackedChanges(xmlDoc)) {
+    seedRevisionIdsFromDocument(xmlDoc, revisionIdAllocator);
+
+    const inputParagraphs = xmlDoc.documentElement && String(xmlDoc.documentElement.localName || '').toLowerCase() === 'p'
+        ? [xmlDoc.documentElement]
+        : getDocumentParagraphs(xmlDoc);
+    if (inputParagraphs.length === 1 && modifiedText.length > 0) {
+        const resurrectionTarget = inspectForeignDeletedParagraphTarget(inputParagraphs[0], author);
+        if (resurrectionTarget.matches) {
+            const ownerAuthor = resurrectionTarget.ownerAuthor || 'unattributed';
+            return finalize({
+                oxml: inputOoxml,
+                hasChanges: false,
+                status: 'error',
+                error: {
+                    code: 'FOREIGN_PARAGRAPH_MARK_DELETION',
+                    message: `Refusing to add visible text to a paragraph whose paragraph mark is deleted by another author (${ownerAuthor}). Use explicit paragraph restoration when supported.`,
+                    ownerAuthor
+                }
+            });
+        }
+    }
+
+    if (containsTrackedChanges(xmlDoc)) {
         if (existingRevisionsPolicy === 'merge-same-author' || existingRevisionsPolicy === 'slice-cross-author') {
             const authors = getTrackedChangeAuthors(xmlDoc);
             const currentAuthor = String(author || '').trim().toLowerCase();

package/engine/surgical-diff-application.js

@@ -161,7 +161,18 @@ export function processDelete(xmlDoc, spanIndex, startPos, endPos, author, gener
             if (delWrapper && record.deletedPieces.length > 0) {
                 delWrapper.appendChild(createRunFromPieces(xmlDoc, record.deletedPieces, record.rPr));
             }
-            insertRunPiecesBefore(xmlDoc, parent, runElement, record.afterPieces, record.rPr);
+            const afterRun = insertRunPiecesBefore(xmlDoc, parent, runElement, record.afterPieces, record.rPr);
+            if (
+                record.globalEnd === endPos
+                && !isWordElement(parent, 'ins')
+            ) {
+                if (!spanIndex.replacementInsertionAnchors) spanIndex.replacementInsertionAnchors = new Map();
+                spanIndex.replacementInsertionAnchors.set(endPos, {
+                    parent,
+                    referenceNode: afterRun || runElement.nextSibling,
+                    rPr: record.rPr
+                });
+            }
             parent.removeChild(runElement);
             changed = true;
         }
@@ -209,6 +220,29 @@ export function processInsert(xmlDoc, spanIndex, pos, text, author, formatHints
         );
     }
 
+    const replacementAnchor = spanIndex.replacementInsertionAnchors?.get(pos) || null;
+    if (
+        replacementAnchor
+        && !affinity
+        && isConnected(replacementAnchor.parent)
+        && (!replacementAnchor.referenceNode || replacementAnchor.referenceNode.parentNode === replacementAnchor.parent)
+    ) {
+        spanIndex.replacementInsertionAnchors.delete(pos);
+        insertTextRuns(
+            xmlDoc,
+            replacementAnchor.parent,
+            replacementAnchor.referenceNode,
+            text,
+            replacementAnchor.rPr,
+            author,
+            formatHints,
+            insertOffset,
+            generateRedlines,
+            revisionMetadata
+        );
+        return true;
+    }
+
     if (!affinity) {
         let targetSpan = findContainingSpan(spanIndex, pos);
 

package/engine/surgical-mode.js

@@ -6,7 +6,7 @@
  */
 
 import { getApplicableFormatHints } from '../pipeline/markdown-processor.js';
-import { computeInsertionOnlyDiffs, computeWordDiffs } from '../pipeline/diff-engine.js';
+import { computeCharacterDiffs, computeInsertionOnlyDiffs, computeWordDiffs } from '../pipeline/diff-engine.js';
 import { getDocumentParagraphs } from './format-extraction.js';
 import { buildSpanIndex, buildSurgicalTextSpans, forEachOverlappingSpan } from './surgical-spans.js';
 import {
@@ -115,7 +115,10 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
     const insertionOnlyDiffs = options.existingRevisions === 'slice-cross-author'
         ? computeInsertionOnlyDiffs(fullText, modifiedText)
         : null;
-    const diffs = insertionOnlyDiffs || computeWordDiffs(fullText, modifiedText, diffOptions);
+    const diffs = insertionOnlyDiffs || refineSpaceEquivalentReplacements(
+        computeWordDiffs(fullText, modifiedText, diffOptions),
+        diffOptions
+    );
     const spanIndex = buildSpanIndex(textSpans);
     const pairReplacements = options.pairReplacements === true;
     const warnings = [];
@@ -124,7 +127,120 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
     let newPos = 0;
     let hasChanges = false;
 
-    for (let i = 0; i < diffs.length; i++) {
+    const insertionOperations = insertionOnlyDiffs
+        ? collectInsertionOperations(insertionOnlyDiffs)
+        : [];
+    if (insertionOperations.length > 1 && formatHints.length === 0) {
+        for (const operation of insertionOperations.slice().reverse()) {
+            const liveSpans = buildSurgicalTextSpans(allParagraphs).textSpans;
+            const liveSpanIndex = buildSpanIndex(liveSpans);
+            const textWithoutNewlines = operation.text.replace(/\n/g, ' ');
+            if (textWithoutNewlines.length === 0) continue;
+            const insertResult = processInsert(
+                xmlDoc,
+                liveSpanIndex,
+                operation.originalPos,
+                textWithoutNewlines,
+                author,
+                formatHints,
+                operation.newPos,
+                generateRedlines,
+                allParagraphs[0] || null,
+                null,
+                options?.insertionAffinity || null,
+                options?.existingRevisions || 'merge-same-author'
+            );
+            if (insertResult && typeof insertResult === 'object' && insertResult.error) {
+                return withOoxmlSourceType({
+                    oxml: serializer.serializeToString(xmlDoc),
+                    hasChanges: false,
+                    status: 'error',
+                    error: insertResult.error
+                });
+            }
+            if (insertResult === true) hasChanges = true;
+        }
+    } else if (formatHints.length === 0) {
+        const editOperations = collectTextEditOperations(diffs);
+        for (const operation of editOperations.reverse()) {
+            const liveSpanIndex = buildSpanIndex(buildSurgicalTextSpans(allParagraphs).textSpans);
+            if (operation.type === 'insert') {
+                const inserted = processInsert(
+                    xmlDoc,
+                    liveSpanIndex,
+                    operation.start,
+                    operation.text.replace(/\n/g, ' '),
+                    author,
+                    formatHints,
+                    operation.newPos,
+                    generateRedlines,
+                    allParagraphs[0] || null,
+                    null,
+                    options?.insertionAffinity || null,
+                    options?.existingRevisions || 'merge-same-author'
+                );
+                if (inserted && typeof inserted === 'object' && inserted.error) {
+                    return withOoxmlSourceType({
+                        oxml: serializer.serializeToString(xmlDoc),
+                        hasChanges: false,
+                        status: 'error',
+                        error: inserted.error
+                    });
+                }
+                if (inserted === true) hasChanges = true;
+                continue;
+            }
+
+            let delMetadata = null;
+            let insMetadata = null;
+            if (operation.type === 'replace' && pairReplacements && generateRedlines && operation.text.replace(/\n/g, ' ')) {
+                const checkResult = checkSafeAdjacencyForPairing(
+                    liveSpanIndex,
+                    operation.start,
+                    operation.end,
+                    options?.existingRevisions === 'slice-cross-author'
+                );
+                if (checkResult.safe) {
+                    const event = createReplacementRevisionEvent(author, xmlDoc);
+                    delMetadata = { id: event.deletionId, author: event.author, date: event.date };
+                    insMetadata = { id: event.insertionId, author: event.author, date: event.date };
+                } else if (checkResult.structuralBoundary) {
+                    warnings.push('PAIRING_SKIPPED_STRUCTURAL_BOUNDARY');
+                }
+            }
+
+            if (processDelete(xmlDoc, liveSpanIndex, operation.start, operation.end, author, generateRedlines, delMetadata)) {
+                hasChanges = true;
+            }
+            if (operation.type === 'replace') {
+                const inserted = processInsert(
+                    xmlDoc,
+                    liveSpanIndex,
+                    operation.end,
+                    operation.text.replace(/\n/g, ' '),
+                    author,
+                    formatHints,
+                    operation.newPos,
+                    generateRedlines,
+                    allParagraphs[0] || null,
+                    insMetadata,
+                    options?.insertionAffinity || null,
+                    options?.existingRevisions || 'merge-same-author'
+                );
+                if (inserted && typeof inserted === 'object' && inserted.error) {
+                    return withOoxmlSourceType({
+                        oxml: serializer.serializeToString(xmlDoc),
+                        hasChanges: false,
+                        status: 'error',
+                        error: inserted.error
+                    });
+                }
+                if (inserted === true) hasChanges = true;
+            }
+        }
+    } else {
+
+      for (let i = 0; i < diffs.length; i++) {
         const [op, text] = diffs[i];
         if (op === 0) {
             const len = text.length;
@@ -216,6 +332,7 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
             }
             newPos += text.length;
         }
+      }
     }
 
     const actualText = allParagraphs.map(paragraph => extractCanonicalParagraphText(paragraph)).join('\n');
@@ -231,7 +348,9 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
                 message: 'Generated OOXML accepted-view text does not match the requested modified text; the mutation was rejected.',
                 mismatchOffset,
                 expectedExcerpt: excerptAt(expectedText, mismatchOffset),
-                actualExcerpt: excerptAt(actualText, mismatchOffset)
+                actualExcerpt: excerptAt(actualText, mismatchOffset),
+                expectedCodePoint: codePointAtOffset(expectedText, mismatchOffset),
+                actualCodePoint: codePointAtOffset(actualText, mismatchOffset)
             },
             ...(warnings.length > 0 ? { warnings: [...new Set(warnings)] } : {})
         });
@@ -257,3 +376,83 @@ function excerptAt(text, offset, radius = 40) {
     const end = Math.min(text.length, offset + radius);
     return text.slice(start, end);
 }
+
+function codePointAtOffset(text, offset) {
+    if (offset >= text.length) return 'END';
+    return `U+${text.codePointAt(offset).toString(16).toUpperCase().padStart(4, '0')}`;
+}
+
+function refineSpaceEquivalentReplacements(diffs, diffOptions) {
+    const refined = [];
+    for (let index = 0; index < diffs.length; index++) {
+        const [op, text] = diffs[index];
+        const next = diffs[index + 1];
+        if (
+            op === -1
+            && next?.[0] === 1
+            && text !== next[1]
+            && text.length === next[1].length
+            && text.replace(/\u00a0/g, ' ') === next[1].replace(/\u00a0/g, ' ')
+        ) {
+            refined.push(...computeCharacterDiffs(text, next[1], diffOptions));
+            index++;
+            continue;
+        }
+        refined.push([op, text]);
+    }
+    return refined;
+}
+
+function collectTextEditOperations(diffs) {
+    const operations = [];
+    let originalPos = 0;
+    let newPos = 0;
+    for (let index = 0; index < diffs.length; index++) {
+        const [op, text] = diffs[index];
+        if (op === 0) {
+            originalPos += text.length;
+            newPos += text.length;
+            continue;
+        }
+        if (op === -1) {
+            const next = diffs[index + 1];
+            if (next?.[0] === 1) {
+                operations.push({
+                    type: 'replace',
+                    start: originalPos,
+                    end: originalPos + text.length,
+                    newPos,
+                    text: next[1]
+                });
+                originalPos += text.length;
+                newPos += next[1].length;
+                index++;
+            } else {
+                operations.push({ type: 'delete', start: originalPos, end: originalPos + text.length, newPos, text: '' });
+                originalPos += text.length;
+            }
+            continue;
+        }
+        operations.push({ type: 'insert', start: originalPos, end: originalPos, newPos, text });
+        newPos += text.length;
+    }
+    return operations;
+}
+
+function collectInsertionOperations(diffs) {
+    const operations = [];
+    let originalPos = 0;
+    let newPos = 0;
+    for (const [op, text] of diffs) {
+        if (op === 0) {
+            originalPos += text.length;
+            newPos += text.length;
+        } else if (op === -1) {
+            originalPos += text.length;
+        } else if (op === 1) {
+            operations.push({ originalPos, newPos, text });
+            newPos += text.length;
+        }
+    }
+    return operations;
+}

package/engine/surgical-run-splitting.js

@@ -8,7 +8,7 @@ import {
 import { refreshRunPropertyChangeIds } from '../core/revision-cloning.js';
 import { getRunChildText, isTextLikeRunChild } from './surgical-spans.js';
 
-const TRACK_CHANGE_CARRIERS = new Set(['ins']);
+const TRACK_CHANGE_CARRIERS = new Set(['ins', 'del']);
 
 export function getRunContentPieces(runElement) {
     const pieces = [];
@@ -72,7 +72,7 @@ export function insertRunPiecesBefore(xmlDoc, parent, referenceNode, pieces, rPr
 }
 
 /**
- * Splits a run-level tracked-change carrier at an accepted-view character
+ * Splits a run-level tracked-change carrier at its visible-view character
  * offset without mutating the source carrier. The original revision ID stays
  * with the leading fragment; an interior trailing fragment receives a fresh,
  * document-scoped ID while all other carrier metadata remains unchanged.
@@ -86,7 +86,7 @@ export function insertRunPiecesBefore(xmlDoc, parent, referenceNode, pieces, rPr
 export function splitTrackChangeCarrier(xmlDoc, carrierElement, splitOffset, allocator = null) {
     const carrierName = getLocalName(carrierElement);
     if (!TRACK_CHANGE_CARRIERS.has(carrierName)) {
-        throw new TypeError('splitTrackChangeCarrier requires a w:ins carrier.');
+        throw new TypeError('splitTrackChangeCarrier requires a w:ins or w:del carrier.');
     }
     if (!Number.isInteger(splitOffset) || splitOffset < 0) {
         throw new RangeError('splitOffset must be a non-negative integer.');
@@ -129,17 +129,18 @@ export function splitTrackChangeCarrier(xmlDoc, carrierElement, splitOffset, all
         } else {
             const localOffset = splitOffset - offset;
             const rPr = Array.from(child.childNodes || []).find(node => isWordElement(node, 'rPr')) || null;
-            const leftPieces = sliceRunPieces(xmlDoc, pieces, 0, localOffset, false);
-            const rightPieces = sliceRunPieces(xmlDoc, pieces, localOffset, runLength, false);
+            const asDeletedText = carrierName === 'del';
+            const leftPieces = sliceRunPieces(xmlDoc, pieces, 0, localOffset, asDeletedText);
+            const rightPieces = sliceRunPieces(xmlDoc, pieces, localOffset, runLength, asDeletedText);
             leftCarrier.appendChild(createRunFromPieces(xmlDoc, leftPieces, rPr));
             const rightRun = createRunFromPieces(xmlDoc, rightPieces, rPr);
-            refreshRunPropertyChangeIds(rightRun, resolveAllocator(xmlDoc, allocator));
             rightCarrier.appendChild(rightRun);
         }
         offset = runEnd;
     }
 
     const resolvedAllocator = resolveAllocator(xmlDoc, allocator);
+    refreshRunPropertyChangeIds(rightCarrier, resolvedAllocator);
     const nextId = resolvedAllocator.next();
     setWordAttribute(rightCarrier, 'id', String(nextId));
     resolvedAllocator._receiptCollector?.recordRevision(nextId, carrierName);
@@ -166,7 +167,7 @@ function getLocalName(element) {
 }
 
 function cloneRunPiece(xmlDoc, sourceNode, text, asDeletedText) {
-    if (asDeletedText) {
+    if (asDeletedText && (isWordElement(sourceNode, 'delText') || isWordElement(sourceNode, 't'))) {
         const delText = createWordElement(xmlDoc, 'w:delText');
         delText.setAttribute('xml:space', 'preserve');
         delText.textContent = text;
@@ -192,6 +193,17 @@ function cloneRunPiece(xmlDoc, sourceNode, text, asDeletedText) {
         return sourceNode.cloneNode(true);
     }
 
+    if (text === '\u00ad' && isWordElement(sourceNode, 'softHyphen')) {
+        return sourceNode.cloneNode(true);
+    }
+
+    if (asDeletedText) {
+        const delText = createWordElement(xmlDoc, 'w:delText');
+        delText.setAttribute('xml:space', 'preserve');
+        delText.textContent = text;
+        return delText;
+    }
+
     const textNode = createWordElement(xmlDoc, 'w:t');
     textNode.setAttribute('xml:space', 'preserve');
     textNode.textContent = text;

package/engine/surgical-spans.js

@@ -3,7 +3,7 @@ import { getFirstElementByTag } from '../core/xml-query.js';
 import { isWordElement } from '../core/word-xml.js';
 
 export function getRunChildText(child) {
-    if (isWordElement(child, 't')) return child.textContent || '';
+    if (isWordElement(child, 't') || isWordElement(child, 'delText')) return child.textContent || '';
     if (isWordElement(child, 'br') || isWordElement(child, 'cr')) return '\n';
     if (isWordElement(child, 'tab')) return '\t';
     if (isWordElement(child, 'noBreakHyphen')) return '\u2011';
@@ -13,6 +13,7 @@ export function getRunChildText(child) {
 
 export function isTextLikeRunChild(child) {
     return isWordElement(child, 't')
+        || isWordElement(child, 'delText')
         || isWordElement(child, 'br')
         || isWordElement(child, 'cr')
         || isWordElement(child, 'tab')

package/index.d.ts

@@ -29,6 +29,7 @@ export type {
   OperationPreflightResult,
   ParagraphTargetDescriptor,
   RedlineDocumentOperation,
+  RestoreDocumentOperation,
   ResolvedCommentAnchor,
   ResolvedDocumentTarget,
   StandaloneRunnerOptions
@@ -43,6 +44,13 @@ export interface RedlineError {
     | 'UNSUPPORTED_REVISION_VIEW_MUTATION'
     | 'UNSUPPORTED_INSERTION_AFFINITY'
     | 'UNSAFE_PARAGRAPH_BOUNDARY'
+    | 'FOREIGN_PARAGRAPH_MARK_DELETION'
+    | 'RESTORATION_STATE_REQUIRED'
+    | 'RESTORATION_COUNT_MISMATCH'
+    | 'UNSAFE_DELETED_TABLE_ROW'
+    | 'UNSUPPORTED_MOVE_REVISION'
+    | 'SECTION_BREAK_PARAGRAPH'
+    | 'UNSAFE_PARAGRAPH_PLACEMENT'
     | 'TARGET_INDEX_MISMATCH'
     | 'REVISION_MISMATCH'
     | 'REVISION_TOKEN_SCOPE_MISMATCH'
@@ -54,6 +62,10 @@ export interface RedlineError {
     | 'CAPTURE_STALE'
     | string;
   message: string;
+  ownerAuthor?: string;
+  stage?: string;
+  expected?: unknown;
+  actual?: unknown;
   commentIds?: string[];
   comments?: Array<{ id: string; author: string; text: string }>;
 }

package/node/cli.js

@@ -8,13 +8,14 @@ import { configureLogger } from '../adapters/logger.js';
 import { isExistingRevisionsPolicy } from '../services/document-operation-contract.js';
 
 const suffixes = { apply: 'redlined', accept: 'accepted', reject: 'rejected', 'delete-comments': 'comments-removed' };
-const CLI_CONTRACT_VERSION = 2;
+const CLI_CONTRACT_VERSION = 3;
 const CLI_CAPABILITIES = [
     'atomic-batch-results-on-package-failure',
     'baseline-aware-validation',
+    'compact-mutation-results',
     'cross-author-revision-slicing',
     'document-scoped-list-revision-ids'
-];
+];
 const commandOptions = {
     version: new Set(['help']),
     inspect: new Set(['help', 'search', 'revised', 'table', 'body', 'nonEmpty', 'index', 'indexes', 'range', 'view']),
@@ -162,10 +163,124 @@ async function writeMutation(command, input, flags, result) {
     await writeFile(destination, result.toBuffer());
     return { status: result.status || 'ok', ...result, outputPath: destination };
 }
-function serializable(value) {
-    const { buffer: _buffer, toBuffer: _toBuffer, ...rest } = value || {};
-    return rest;
-}
+function serializable(value) {
+    const { buffer: _buffer, toBuffer: _toBuffer, ...rest } = value || {};
+    return rest;
+}
+
+function boundedText(value, limit = 512) {
+    const text = String(value ?? '');
+    return text.length > limit ? `${text.slice(0, limit)}…` : text;
+}
+
+function compactError(error) {
+    if (!error || typeof error !== 'object') return error;
+    const fields = [
+        'code', 'stage', 'mismatchOffset', 'expectedExcerpt', 'actualExcerpt',
+        'expectedCodePoint', 'actualCodePoint', 'ownerAuthor', 'commentIds'
+    ];
+    const compact = {};
+    for (const field of fields) {
+        if (error[field] !== undefined) compact[field] = error[field];
+    }
+    if (Array.isArray(error.comments)) {
+        compact.comments = error.comments.map(comment => ({
+            ...(comment?.id !== undefined ? { id: comment.id } : {}),
+            ...(comment?.author !== undefined ? { author: boundedText(comment.author, 160) } : {}),
+            ...(comment?.text !== undefined ? { text: boundedText(comment.text, 512) } : {})
+        }));
+    }
+    if (Array.isArray(error.candidates)) {
+        compact.candidates = error.candidates.map(compactResolvedTarget);
+    }
+    compact.message = boundedText(error.message || String(error));
+    return compact;
+}
+
+function compactResolvedTarget(target) {
+    if (!target || typeof target !== 'object') return target;
+    const { text: _text, exactText: _exactText, ...compact } = target;
+    return compact;
+}
+
+function compactReceipt(receipt) {
+    if (!receipt || typeof receipt !== 'object') return receipt;
+    return {
+        ...receipt,
+        affectedTargets: Array.isArray(receipt.affectedTargets)
+            ? receipt.affectedTargets.map(compactResolvedTarget)
+            : [],
+        warnings: Array.isArray(receipt.warnings) ? receipt.warnings.map(warning => boundedText(warning)) : []
+    };
+}
+
+function compactOperationResult(result) {
+    if (!result || typeof result !== 'object') return result;
+    return {
+        ...result,
+        ...(result.resolvedTarget ? { resolvedTarget: compactResolvedTarget(result.resolvedTarget) } : {}),
+        ...(result.resolvedAnchor ? { resolvedAnchor: compactResolvedTarget(result.resolvedAnchor) } : {}),
+        ...(result.error ? { error: compactError(result.error) } : {}),
+        ...(result.receipt ? { receipt: compactReceipt(result.receipt) } : {}),
+        ...(Array.isArray(result.warnings) ? { warnings: result.warnings.map(warning => boundedText(warning)) } : {})
+    };
+}
+
+function summarizeIssues(issues) {
+    const list = Array.isArray(issues) ? issues : [];
+    const grouped = new Map();
+    for (const issue of list) {
+        const code = issue?.code || 'UNKNOWN';
+        const source = issue?.source || 'unknown';
+        const severity = issue?.severity || 'error';
+        const key = `${source}:${severity}:${code}`;
+        const current = grouped.get(key) || { source, severity, code, count: 0 };
+        current.count++;
+        grouped.set(key, current);
+    }
+    return {
+        total: list.length,
+        errors: list.filter(issue => issue?.severity === 'error').length,
+        warnings: list.filter(issue => issue?.severity === 'warning').length,
+        byCode: Array.from(grouped.values()).sort((a, b) => (
+            a.source.localeCompare(b.source) || a.code.localeCompare(b.code) || a.severity.localeCompare(b.severity)
+        ))
+    };
+}
+
+function compactMutationResult(value) {
+    const serialized = serializable(value);
+    const {
+        documentXml: _documentXml,
+        oxml: _oxml,
+        commentsXml: _commentsXml,
+        commentsExtendedXml: _commentsExtendedXml,
+        numberingXml: _numberingXml,
+        numberingXmlParts: _numberingXmlParts,
+        inspection: _inspection,
+        issues: _issues,
+        ...compact
+    } = serialized;
+    const results = Array.isArray(compact.results) ? compact.results.map(compactOperationResult) : [];
+    const status = compact.status || 'ok';
+    return {
+        ...compact,
+        ...(Array.isArray(compact.results) ? { results } : {}),
+        ...(Array.isArray(compact.receipts) ? { receipts: compact.receipts.map(compactReceipt) } : {}),
+        ...(compact.error ? { error: compactError(compact.error) } : {}),
+        ...(Array.isArray(compact.warnings) ? { warnings: compact.warnings.map(warning => boundedText(warning)) } : {}),
+        ...(compact.validation ? {
+            validation: {
+                originalIssues: summarizeIssues(compact.validation.originalIssues),
+                generatedIssues: summarizeIssues(compact.validation.generatedIssues)
+            }
+        } : {}),
+        completion: compact.written === true
+            && status !== 'error'
+            && status !== 'partial'
+            && results.every(result => result?.status !== 'error')
+    };
+}
 
 async function collectValidationIssues(buffer) {
     const entries = unzipDocx(buffer);
@@ -301,17 +416,17 @@ export async function executeCli(argv) {
                 ...(expectedRevision ? { expectedRevision } : {})
             });
             const mutationResult = await writeMutation(command, input, flags, result);
-            return {
-                command,
-                input,
-                ...serializable(mutationResult),
-                ...(result.status === 'error' || result.error ? { exitCode: 2 } : {})
-            };
+            return compactMutationResult({
+                command,
+                input,
+                ...serializable(mutationResult),
+                ...(result.status === 'error' || result.error ? { exitCode: 2 } : {})
+            });
         }
         const filter = flags.allAuthors ? { allAuthors: true } : flags.author ? { author: String(flags.author) } : null;
         if (!filter) return cliError('AUTHOR_REQUIRED', 'Use --author <name> or --all-authors.');
         const result = command === 'delete-comments' ? await document.deleteComments(filter) : await document.resolveRevisions(command, filter);
-        return { command, input, ...serializable(await writeMutation(command, input, flags, result)) };
+        return compactMutationResult({ command, input, ...serializable(await writeMutation(command, input, flags, result)) });
     } catch (error) { return cliError(error.code || 'CLI_FAILED', error.message); }
 }