@ansonlai/docx-redline-js 0.5.3 → 0.6.0

package/services/document-operation-mutations.js

@@ -27,6 +27,13 @@ import {
 } from '../core/paragraph-revision-safety.js';
 import { extractCanonicalParagraphText } from '../core/paragraph-text.js';
 import { validateRedlineOoxml } from '../core/redline-validation.js';
+import { subtractValidationIssueMultiset, validationErrors } from '../core/validation-delta.js';
+import { clonePropertiesWithoutRevisionHistory } from '../core/revision-cloning.js';
+import {
+    getRunContentPieces,
+    getRunTextLength,
+    splitTrackChangeCarrier
+} from '../engine/surgical-run-splitting.js';
 import { applyHighlightToOoxml } from '../engine/formatting-removal.js';
 import { parseTable as parseMarkdownTable } from '../pipeline/pipeline.js';
 import { injectCommentsIntoOoxml } from './comment-engine.js';
@@ -162,15 +169,91 @@ async function reconcileMarkdownTableOoxml(oxml, originalText, markdownTable, op
     };
 }
 
-function getParagraphText(paragraph) {
-    return getParagraphTextFromOxml(paragraph);
-}
+function getParagraphText(paragraph) {
+    return getParagraphTextFromOxml(paragraph);
+}
+
+function escapeInvisibleText(value, maxLength = 96) {
+    const text = String(value ?? '');
+    const bounded = text.length > maxLength ? `${text.slice(0, maxLength)}…` : text;
+    return bounded
+        .replace(/\\/g, '\\\\')
+        .replace(/\r/g, '\\r')
+        .replace(/\n/g, '\\n')
+        .replace(/\t/g, '\\t')
+        .replace(/\u00a0/g, '\\u00A0')
+        .replace(/\u202f/g, '\\u202F')
+        .replace(/\u2060/g, '\\u2060');
+}
+
+function codePointLabel(value, offset) {
+    if (offset >= value.length) return 'END';
+    return `U+${value.codePointAt(offset).toString(16).toUpperCase().padStart(4, '0')}`;
+}
+
+function describeTargetTextMatch(actualText, requestedText) {
+    const actual = String(actualText ?? '');
+    const requested = String(requestedText ?? '');
+    if (actual === requested) return { mode: 'exact' };
+
+    const differences = [];
+    const limit = Math.min(actual.length, requested.length);
+    for (let offset = 0; offset < limit && differences.length < 8; offset++) {
+        if (actual[offset] === requested[offset]) continue;
+        differences.push({
+            offset,
+            sourceCodePoint: codePointLabel(actual, offset),
+            requestedCodePoint: codePointLabel(requested, offset)
+        });
+    }
+    if (actual.length !== requested.length && differences.length < 8) {
+        differences.push({
+            offset: limit,
+            sourceCodePoint: codePointLabel(actual, limit),
+            requestedCodePoint: codePointLabel(requested, limit)
+        });
+    }
+
+    const spaceEquivalent = actual.length === requested.length
+        && actual.replace(/\u00a0/g, ' ') === requested.replace(/\u00a0/g, ' ');
+    return {
+        mode: spaceEquivalent ? 'space_equivalent' : 'normalized',
+        differences,
+        sourceExcerpt: escapeInvisibleText(actual),
+        requestedExcerpt: escapeInvisibleText(requested)
+    };
+}
 
-function resolveTargetParagraph(xmlDoc, targetText, targetRef, opType, runtimeContext = null, options = {}) {
+function resolveTargetParagraph(xmlDoc, targetText, targetRef, opType, runtimeContext = null, options = {}) {
     const onInfo = typeof options?.onInfo === 'function' ? options.onInfo : () => { };
     const onWarn = typeof options?.onWarn === 'function' ? options.onWarn : () => { };
     const session = options?._documentOperationSession || null;
-    const paragraphMetadataIndex = session?.getParagraphMetadataIndex?.() || null;
+    const paragraphMetadataIndex = session?.getParagraphMetadataIndex?.() || null;
+
+    if (options?._compiledSourceId && options?._sourceTargetRegistry) {
+        const resolved = options._sourceTargetRegistry.resolve(options._compiledSourceId, xmlDoc);
+        if (resolved?.error || !resolved?.paragraph) return resolved;
+        resolved.resolvedBy = options._compiledResolvedBy || resolved.resolvedBy;
+        if (options?._resolutionCapture) {
+            const paragraph = resolved.paragraph;
+            const metadata = paragraphMetadataIndex?.byParagraph?.get(paragraph) || null;
+            Object.assign(options._resolutionCapture, {
+                resolvedBy: resolved.resolvedBy,
+                resolvedTarget: {
+                    index: metadata?.index ?? getDocumentParagraphNodes(xmlDoc).indexOf(paragraph) + 1,
+                    paragraphId: metadata?.paragraphId ?? getParagraphId(paragraph),
+                    text: metadata?.text ?? getParagraphText(paragraph),
+                    fingerprint: metadata?.fingerprint ?? createParagraphFingerprint(paragraph),
+                    inTable: metadata?.inTable ?? !!findContainingWordElement(paragraph, 'tbl'),
+                    targetTextMatch: describeTargetTextMatch(
+                        metadata?.text ?? getParagraphText(paragraph),
+                        options?.targetDescriptor?.exactText ?? targetText
+                    )
+                }
+            });
+        }
+        return resolved;
+    }
 
     if (options?.targetDescriptor?.captureRef) {
         try {
@@ -178,16 +261,20 @@ function resolveTargetParagraph(xmlDoc, targetText, targetRef, opType, runtimeCo
             if (options?._resolutionCapture && resolved?.paragraph) {
                 const paragraph = resolved.paragraph;
                 const metadata = paragraphMetadataIndex?.byParagraph?.get(paragraph) || null;
-                Object.assign(options._resolutionCapture, {
-                    resolvedBy: resolved.resolvedBy,
-                    resolvedTarget: {
+                Object.assign(options._resolutionCapture, {
+                    resolvedBy: resolved.resolvedBy,
+                    resolvedTarget: {
                         index: metadata?.index ?? Array.from(xmlDoc.getElementsByTagNameNS(NS_W, 'p')).indexOf(paragraph) + 1,
                         paragraphId: metadata?.paragraphId ?? getParagraphId(paragraph),
                         text: metadata?.text ?? getParagraphText(paragraph),
                         fingerprint: metadata?.fingerprint ?? createParagraphFingerprint(paragraph),
-                        inTable: metadata?.inTable ?? !!findContainingWordElement(paragraph, 'tbl')
-                    }
-                });
+                        inTable: metadata?.inTable ?? !!findContainingWordElement(paragraph, 'tbl'),
+                        targetTextMatch: describeTargetTextMatch(
+                            metadata?.text ?? getParagraphText(paragraph),
+                            options?.targetDescriptor?.exactText ?? targetText
+                        )
+                    }
+                });
             }
             return resolved;
         } catch (error) {
@@ -216,14 +303,18 @@ function resolveTargetParagraph(xmlDoc, targetText, targetRef, opType, runtimeCo
         const metadata = paragraphMetadataIndex?.byParagraph?.get(paragraph) || null;
         Object.assign(options._resolutionCapture, {
             resolvedBy: resolved.resolvedBy,
-            resolvedTarget: {
+            resolvedTarget: {
                 index: metadata?.index ?? Array.from(xmlDoc.getElementsByTagNameNS(NS_W, 'p')).indexOf(paragraph) + 1,
                 paragraphId: metadata?.paragraphId ?? getParagraphId(paragraph),
                 text: metadata?.text ?? getParagraphText(paragraph),
                 fingerprint: metadata?.fingerprint ?? createParagraphFingerprint(paragraph),
-                inTable: metadata?.inTable ?? !!findContainingWordElement(paragraph, 'tbl')
-            }
-        });
+                inTable: metadata?.inTable ?? !!findContainingWordElement(paragraph, 'tbl'),
+                targetTextMatch: describeTargetTextMatch(
+                    metadata?.text ?? getParagraphText(paragraph),
+                    options?.targetDescriptor?.exactText ?? targetText
+                )
+            }
+        });
     }
     return resolved;
 }
@@ -260,7 +351,7 @@ function preprocessRedlineTargetParagraph(targetParagraph) {
     removeProofErrNodes(targetParagraph);
 }
 
-function getDirectWordChild(element, localName) {
+function getDirectWordChild(element, localName) {
     if (!element) return null;
     return Array.from(element.childNodes || []).find(
         node => node && node.nodeType === 1 && node.namespaceURI === NS_W && node.localName === localName
@@ -325,7 +416,7 @@ function buildInsertedListParagraph(xmlDoc, anchorParagraph, entry, revisionMeta
 
     const anchorPPr = getDirectWordChild(anchorParagraph, 'pPr');
     if (anchorPPr) {
-        paragraph.appendChild(anchorPPr.cloneNode(true));
+        paragraph.appendChild(clonePropertiesWithoutRevisionHistory(anchorPPr));
     }
     ensureListProperties(xmlDoc, paragraph, entry.ilvl, entry.numId);
 
@@ -341,7 +432,7 @@ function buildInsertedListParagraph(xmlDoc, anchorParagraph, entry, revisionMeta
     const anchorFirstRun = Array.from(anchorParagraph.getElementsByTagNameNS(NS_W, 'r'))[0] || null;
     const anchorRunPr = anchorFirstRun ? getDirectWordChild(anchorFirstRun, 'rPr') : null;
     if (anchorRunPr) {
-        run.appendChild(anchorRunPr.cloneNode(true));
+        run.appendChild(clonePropertiesWithoutRevisionHistory(anchorRunPr));
     }
 
     const textNode = createWordElement(xmlDoc, 'w:t');
@@ -445,12 +536,12 @@ function buildFallbackInsertedPlainParagraph(xmlDoc, text, revisionMetadata, aut
 function buildEmptyParagraphTemplateFromAnchor(xmlDoc, anchorParagraph) {
     const paragraph = createWordElement(xmlDoc, 'w:p');
     const anchorPPr = getDirectWordChild(anchorParagraph, 'pPr');
-    if (anchorPPr) paragraph.appendChild(anchorPPr.cloneNode(true));
+    if (anchorPPr) paragraph.appendChild(clonePropertiesWithoutRevisionHistory(anchorPPr));
 
     const run = createWordElement(xmlDoc, 'w:r');
     const anchorFirstRun = Array.from(anchorParagraph.getElementsByTagNameNS(NS_W, 'r'))[0] || null;
     const anchorRunPr = anchorFirstRun ? getDirectWordChild(anchorFirstRun, 'rPr') : null;
-    if (anchorRunPr) run.appendChild(anchorRunPr.cloneNode(true));
+    if (anchorRunPr) run.appendChild(clonePropertiesWithoutRevisionHistory(anchorRunPr));
 
     const textNode = createWordElement(xmlDoc, 'w:t');
     textNode.textContent = '';
@@ -463,7 +554,7 @@ function wrapParagraphContentInInsertion(xmlDoc, paragraph, revisionMetadata, au
     const wrappedParagraph = createWordElement(xmlDoc, 'w:p');
     const pPr = options.sanitizeParagraphProperties === true
         ? createSanitizedRestorationPPr(xmlDoc, paragraph)
-        : getDirectWordChild(paragraph, 'pPr')?.cloneNode(true);
+        : clonePropertiesWithoutRevisionHistory(getDirectWordChild(paragraph, 'pPr'));
     if (pPr) wrappedParagraph.appendChild(pPr);
     if (options.paragraphId) wrappedParagraph.setAttributeNS(NS_W14, 'w14:paraId', options.paragraphId);
     if (options.trackParagraphMark === true) {
@@ -539,6 +630,71 @@ function collectNumberingIdsFromNodes(nodes) {
     return Array.from(ids);
 }
 
+function directDeletionCarrierText(carrier) {
+    return Array.from(carrier?.childNodes || []).reduce((text, child) => {
+        return text + (child?.nodeType === 1 && child.namespaceURI === NS_W && child.localName === 'r'
+            ? getRunContentPieces(child).map(piece => piece.text).join('')
+            : '');
+    }, '');
+}
+
+function findOccurrenceOffset(text, needle, occurrence) {
+    let from = 0;
+    let found = -1;
+    for (let index = 0; index < occurrence; index++) {
+        found = text.indexOf(needle, from);
+        if (found < 0) return -1;
+        from = found + Math.max(needle.length, 1);
+    }
+    return found;
+}
+
+function countNonOverlappingOccurrences(text, needle) {
+    if (!needle) return 0;
+    let count = 0;
+    let from = 0;
+    while (from <= text.length) {
+        const found = text.indexOf(needle, from);
+        if (found < 0) break;
+        count += 1;
+        from = found + needle.length;
+    }
+    return count;
+}
+
+function hasUnsupportedDeletionSplitMarkup(paragraph, carrier) {
+    const unsafeParagraphNames = new Set([
+        'commentRangeStart', 'commentRangeEnd', 'commentReference',
+        'bookmarkStart', 'bookmarkEnd', 'moveFromRangeStart', 'moveFromRangeEnd',
+        'moveToRangeStart', 'moveToRangeEnd'
+    ]);
+    if (Array.from(paragraph.getElementsByTagName?.('*') || []).some(node => unsafeParagraphNames.has(node.localName))) {
+        return true;
+    }
+    for (const child of Array.from(carrier?.childNodes || [])) {
+        if (child.nodeType !== 1) continue;
+        if (!(child.namespaceURI === NS_W && child.localName === 'r')) return true;
+        for (const runChild of Array.from(child.childNodes || [])) {
+            if (runChild.nodeType !== 1 || runChild.namespaceURI !== NS_W) continue;
+            if (!['rPr', 'delText', 't', 'tab', 'br', 'cr', 'noBreakHyphen', 'softHyphen'].includes(runChild.localName)) return true;
+        }
+    }
+    return false;
+}
+
+function insertedRunPropertiesAtDeletionOffset(carrier, localOffset) {
+    let offset = 0;
+    for (const child of Array.from(carrier?.childNodes || [])) {
+        if (!(child?.nodeType === 1 && child.namespaceURI === NS_W && child.localName === 'r')) continue;
+        const length = getRunTextLength(getRunContentPieces(child));
+        if (localOffset <= offset + length) {
+            return clonePropertiesWithoutRevisionHistory(getDirectWordChild(child, 'rPr'));
+        }
+        offset += length;
+    }
+    return null;
+}
+
 const RESTORATION_PPR_ALLOWLIST = new Set([
     'pStyle', 'numPr', 'ind', 'jc', 'spacing', 'tabs',
     'keepNext', 'keepLines', 'outlineLvl', 'contextualSpacing'
@@ -678,13 +834,13 @@ function isInsertedParagraphByAuthor(paragraph, author) {
     return !!marker && normalizedAuthor(wordAttribute(marker, 'author')) === normalizedAuthor(author);
 }
 
-function precedingParagraphBlock(firstSource, count) {
+function followingParagraphBlock(lastSource, count) {
     const paragraphs = [];
-    let cursor = firstSource;
+    let cursor = lastSource;
     for (let i = 0; i < count; i++) {
-        cursor = directWordParagraphSibling(cursor, 'previousSibling');
+        cursor = directWordParagraphSibling(cursor, 'nextSibling');
         if (!cursor) return [];
-        paragraphs.unshift(cursor);
+        paragraphs.push(cursor);
     }
     return paragraphs;
 }
@@ -713,26 +869,37 @@ function buildExpectedRestorationDocument(beforeXml, sourceStartIndex, existingI
     if (parsed.error || !parsed.doc) return null;
     const expectedDoc = parsed.doc;
     const originalParagraphs = getDocumentParagraphNodes(expectedDoc);
-    const source = originalParagraphs[sourceStartIndex] || null;
-    if (!source?.parentNode) return null;
+    const lastSource = originalParagraphs[sourceStartIndex + templates.length - 1] || null;
+    if (!lastSource?.parentNode) return null;
 
     for (const index of [...existingIndexes].sort((a, b) => b - a)) {
         const paragraph = originalParagraphs[index];
         paragraph?.parentNode?.removeChild(paragraph);
     }
+    const insertionPoint = lastSource.nextSibling;
     for (const template of templates) {
-        source.parentNode.insertBefore(expectedDoc.importNode(template, true), source);
+        lastSource.parentNode.insertBefore(expectedDoc.importNode(template, true), insertionPoint);
     }
     return createSerializer().serializeToString(expectedDoc);
 }
 
-function verifyParagraphRestorationLifecycle(beforeXml, outputXml, sourceStartIndex, existingIndexes, templates) {
-    const validation = validateRedlineOoxml(outputXml);
-    if (!validation.valid) {
+function verifyParagraphRestorationLifecycle(beforeXml, outputXml, sourceStartIndex, existingIndexes, templates, insertedParagraphs = []) {
+    const baselineValidation = validateRedlineOoxml(beforeXml);
+    const outputValidation = validateRedlineOoxml(outputXml);
+    const generatedIssues = subtractValidationIssueMultiset(outputValidation.issues, baselineValidation.issues);
+    const envelopeIssues = insertedParagraphs.flatMap(paragraph => (
+        validateRedlineOoxml(createSerializer().serializeToString(paragraph)).issues
+            .filter(issue => issue.severity === 'error')
+    ));
+    const generatedErrors = validationErrors(generatedIssues);
+    if (generatedErrors.length > 0 || envelopeIssues.length > 0) {
         return {
             valid: false,
             stage: 'validation',
-            message: validation.issues.filter(issue => issue.severity === 'error').map(issue => issue.message).join(' ')
+            code: 'GENERATED_OOXML_INVALID',
+            generatedIssues,
+            envelopeIssues,
+            message: [...generatedErrors, ...envelopeIssues].map(issue => issue.message).join(' ')
         };
     }
 
@@ -758,6 +925,176 @@ function verifyParagraphRestorationLifecycle(beforeXml, outputXml, sourceStartIn
     return { valid: true };
 }
 
+/**
+ * Inserts a new tracked run at an exact offset inside text visible only in the
+ * rejected view of a wholly deleted paragraph. The foreign deletion is split,
+ * never rewritten or re-authored.
+ */
+export async function insertIntoRejectedDeletedText(
+    documentXml,
+    targetText,
+    anchor,
+    modified,
+    author,
+    targetRef = null,
+    runtimeContext = null,
+    options = {}
+) {
+    const { serializer, xmlDoc, operationSession } = resolveMutationDocument(documentXml, options);
+    if (!xmlDoc) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: { code: 'PARSE_ERROR', message: 'Could not parse document OOXML.' }
+        };
+    }
+
+    const resolved = resolveTargetParagraph(xmlDoc, targetText, targetRef, 'insert', runtimeContext, options);
+    if (resolved?.error || !resolved?.paragraph) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: resolved?.error || { code: 'TARGET_NOT_FOUND', message: 'Rejected-view insertion target was not found.' }
+        };
+    }
+
+    const paragraph = resolved.paragraph;
+    const state = inspectForeignDeletedParagraphTarget(paragraph, author);
+    if (!state.matches) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'REJECTED_INSERTION_STATE_REQUIRED',
+                message: 'Rejected-view insertion requires a wholly deleted paragraph owned by another author.'
+            }
+        };
+    }
+    const structuralRefusal = getParagraphRestorationRefusal(paragraph, { requireFollowingParagraph: false });
+    if (structuralRefusal) {
+        return { documentXml, hasChanges: false, status: 'error', error: structuralRefusal };
+    }
+    if (/\r|\n/.test(modified)) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'UNSAFE_PARAGRAPH_BOUNDARY',
+                message: 'Rejected-view insertion supports run-level text only; use restore for paragraph boundaries.'
+            }
+        };
+    }
+
+    const rejectedText = extractCanonicalParagraphText(paragraph, { revisionView: 'rejected' });
+    if (!anchor.occurrenceExplicit && countNonOverlappingOccurrences(rejectedText, anchor.exactText) > 1) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'AMBIGUOUS_ANCHOR',
+                message: 'The rejected-view insertion anchor is repeated; provide anchor.occurrence explicitly.'
+            }
+        };
+    }
+    const anchorStart = findOccurrenceOffset(rejectedText, anchor.exactText, anchor.occurrence);
+    if (anchorStart < 0) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: { code: 'ANCHOR_NOT_FOUND', message: 'The rejected-view insertion anchor was not found at the requested occurrence.' }
+        };
+    }
+    const insertionOffset = anchorStart + anchor.offset;
+    const carriers = Array.from(paragraph.childNodes || []).filter(
+        node => node?.nodeType === 1 && node.namespaceURI === NS_W && node.localName === 'del'
+    );
+    if (carriers.some(carrier => hasUnsupportedDeletionSplitMarkup(paragraph, carrier))) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'UNSAFE_REVISION_BOUNDARY',
+                message: 'The rejected-view insertion boundary contains comments, bookmarks, fields, hyperlinks, moves, or non-text run markup that cannot be split safely.'
+            }
+        };
+    }
+    let carrierStart = 0;
+    let targetCarrier = null;
+    let carrierOffset = 0;
+    for (const carrier of carriers) {
+        const length = directDeletionCarrierText(carrier).length;
+        if (insertionOffset >= carrierStart && insertionOffset <= carrierStart + length) {
+            targetCarrier = carrier;
+            carrierOffset = insertionOffset - carrierStart;
+            break;
+        }
+        carrierStart += length;
+    }
+    if (!targetCarrier || carriers.map(directDeletionCarrierText).join('') !== rejectedText) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'UNSAFE_REVISION_NESTING',
+                message: 'The rejected-view anchor is not contained in a supported direct deletion carrier.'
+            }
+        };
+    }
+
+    const runProperties = insertedRunPropertiesAtDeletionOffset(targetCarrier, carrierOffset);
+    const { leftCarrier, rightCarrier } = splitTrackChangeCarrier(
+        xmlDoc,
+        targetCarrier,
+        carrierOffset,
+        options._revisionIdAllocator || null
+    );
+    const insertion = createWordElement(xmlDoc, 'w:ins');
+    const metadata = createRevisionMetadata(author, options._revisionIdAllocator || xmlDoc, 'ins');
+    insertion.setAttribute('w:id', String(metadata.id));
+    insertion.setAttribute('w:author', metadata.author);
+    insertion.setAttribute('w:date', metadata.date);
+    const run = createWordElement(xmlDoc, 'w:r');
+    if (runProperties) run.appendChild(runProperties);
+    const textNode = createWordElement(xmlDoc, 'w:t');
+    if (/^\s|\s$/.test(modified)) textNode.setAttribute('xml:space', 'preserve');
+    textNode.textContent = modified;
+    run.appendChild(textNode);
+    insertion.appendChild(run);
+
+    const parent = targetCarrier.parentNode;
+    if (leftCarrier) parent.insertBefore(leftCarrier, targetCarrier);
+    parent.insertBefore(insertion, targetCarrier);
+    if (rightCarrier) parent.insertBefore(rightCarrier, targetCarrier);
+    options?._mutationRemovedNodes?.push(targetCarrier);
+    parent.removeChild(targetCarrier);
+    options?._mutationLiveNodes?.push(paragraph, insertion);
+    operationSession?.invalidateParagraphMetadata?.();
+
+    const outputXml = serializer.serializeToString(xmlDoc);
+    const outputRejected = extractCanonicalParagraphText(paragraph, { revisionView: 'rejected' });
+    const outputAccepted = extractCanonicalParagraphText(paragraph, { revisionView: 'accepted' });
+    if (outputRejected !== rejectedText || !outputAccepted.includes(modified)) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'PATCH_ROUNDTRIP_MISMATCH',
+                message: 'Rejected-view insertion did not preserve the deleted source and expose the requested inserted text.'
+            }
+        };
+    }
+    return { documentXml: outputXml, hasChanges: true, status: 'ok' };
+}
+
 /**
  * Materializes an explicit counterproposal for one or more paragraphs wholly
  * deleted (content and paragraph mark) by another author.
@@ -794,7 +1131,22 @@ export async function restoreDeletedParagraphByExactText(
 
     const firstSource = resolved.paragraph;
     let sourceParagraphs = [firstSource];
-    if (targetEndRef) {
+    if (options._compiledSourceEndId) {
+        const endResolved = resolveTargetParagraph(
+            xmlDoc,
+            options.targetEndDescriptor?.text || '',
+            targetEndRef,
+            'restore',
+            runtimeContext,
+            { ...options, _compiledSourceId: options._compiledSourceEndId }
+        );
+        const allParagraphs = endResolved?.paragraph ? getDocumentParagraphNodes(xmlDoc) : [];
+        const startIndex = allParagraphs.indexOf(firstSource);
+        const endIndex = allParagraphs.indexOf(endResolved?.paragraph);
+        sourceParagraphs = startIndex >= 0 && endIndex >= startIndex
+            ? allParagraphs.slice(startIndex, endIndex + 1)
+            : null;
+    } else if (targetEndRef) {
         sourceParagraphs = resolveParagraphRangeByRefs(xmlDoc, targetRef, targetEndRef, {
             opType: 'restore',
             targetRefSnapshot: runtimeContext?.targetRefSnapshot || null,
@@ -808,7 +1160,11 @@ export async function restoreDeletedParagraphByExactText(
             options.targetEndDescriptor.index,
             'restore',
             runtimeContext,
-            { ...options, targetDescriptor: options.targetEndDescriptor }
+            {
+                ...options,
+                targetDescriptor: options.targetEndDescriptor,
+                _compiledSourceId: options._compiledSourceEndId || null
+            }
         );
         const allParagraphs = endResolved?.paragraph ? getDocumentParagraphNodes(xmlDoc) : [];
         const startIndex = allParagraphs.indexOf(firstSource);
@@ -891,7 +1247,8 @@ export async function restoreDeletedParagraphByExactText(
         }
     }
 
-    const existingBlock = precedingParagraphBlock(firstSource, sourceParagraphs.length);
+    const lastSource = sourceParagraphs[sourceParagraphs.length - 1];
+    const existingBlock = followingParagraphBlock(lastSource, sourceParagraphs.length);
     const hasExistingRestoration = existingBlock.length === sourceParagraphs.length
         && existingBlock.every(paragraph => isInsertedParagraphByAuthor(paragraph, author));
     if (
@@ -939,7 +1296,8 @@ export async function restoreDeletedParagraphByExactText(
         const paragraph = xmlDoc.importNode(template, true);
         return trackRestoredParagraph(xmlDoc, paragraph, author, operationSession);
     });
-    for (const paragraph of insertedParagraphs) parent.insertBefore(paragraph, firstSource);
+    const insertionPoint = lastSource.nextSibling;
+    for (const paragraph of insertedParagraphs) parent.insertBefore(paragraph, insertionPoint);
     if (hasExistingRestoration) {
         for (const paragraph of existingBlock) {
             options?._mutationRemovedNodes?.push(paragraph);
@@ -955,7 +1313,8 @@ export async function restoreDeletedParagraphByExactText(
         outputXml,
         sourceStartIndex,
         existingIndexes,
-        templates
+        templates,
+        insertedParagraphs
     );
     if (!oracle.valid) {
         return {
@@ -963,9 +1322,11 @@ export async function restoreDeletedParagraphByExactText(
             hasChanges: false,
             status: 'error',
             error: {
-                code: 'PATCH_ROUNDTRIP_MISMATCH',
+                code: oracle.code || 'PATCH_ROUNDTRIP_MISMATCH',
                 message: oracle.message,
                 stage: oracle.stage,
+                ...(oracle.generatedIssues ? { generatedIssues: oracle.generatedIssues } : {}),
+                ...(oracle.envelopeIssues ? { envelopeIssues: oracle.envelopeIssues } : {}),
                 ...(oracle.expected ? { expected: oracle.expected } : {}),
                 ...(oracle.actual ? { actual: oracle.actual } : {})
             }
@@ -1352,7 +1713,9 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
                     status: 'error',
                     error: {
                         code: 'EXISTING_REVISIONS',
-                        message: `Target paragraph contains tracked changes from another author (${authors.length ? authors.join(', ') : 'unattributed'}). Pass existingRevisions: "accept-all-first" or resolve revisions first.`
+                        message: `Target paragraph contains tracked changes from another author (${authors.length ? authors.join(', ') : 'unattributed'}). Use existingRevisions: "slice-cross-author" for a surgical edit that preserves reviewer history; accepting or rejecting revisions requires separate authorization.`,
+                        revisionAuthors: authors,
+                        currentPolicy: existingPolicy
                     }
                 };
             }
@@ -1715,8 +2078,8 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
                 ? explicitRangeParagraphs.map(paragraph => getParagraphText(paragraph)).join('\n')
                 : (inferredTableRangeParagraphs
                     ? inferredTableRangeParagraphs.map(paragraph => getParagraphText(paragraph)).join('\n')
-                    : (currentParagraphText || targetText))
-        );
+                    : (currentParagraphText || targetText))
+        );
     const scopedXml = useTableScope
         ? serializer.serializeToString(containingTable)
         : (

package/services/document-operation-session.js

@@ -42,6 +42,7 @@ export class DocumentOperationSession {
         this.executionOrder = [];
         this.authorsUsed = new Set();
         this.captureTable = new Map();
+        this.sourceTargetRegistry = null;
         this.nextCaptureParaId = 1;
         this.receiptCollector = new ReceiptCollector();
 
@@ -111,6 +112,7 @@ export class DocumentOperationSession {
             commentsXmlMode: this.commentsXmlMode,
             commentsExtendedXmlMode: this.commentsExtendedXmlMode,
             captureTable: cloneCaptureTable(this.captureTable),
+            sourceTargetRegistry: this.sourceTargetRegistry?.createSavepoint?.(this.document) || null,
             nextCaptureParaId: this.nextCaptureParaId,
             receiptCollector: this.receiptCollector ? this.receiptCollector.createSavepoint() : null
         };
@@ -127,6 +129,7 @@ export class DocumentOperationSession {
         this.commentsXmlMode = savepoint.commentsXmlMode || 'merge';
         this.commentsExtendedXmlMode = savepoint.commentsExtendedXmlMode || 'merge';
         this.captureTable = savepoint.captureTable ? cloneCaptureTable(savepoint.captureTable) : new Map();
+        this.sourceTargetRegistry?.restoreSavepoint?.(this.document, savepoint.sourceTargetRegistry);
         if (typeof savepoint.nextCaptureParaId === 'number') {
             this.nextCaptureParaId = savepoint.nextCaptureParaId;
         }
@@ -160,6 +163,7 @@ export class DocumentOperationSession {
         this.hasChanges = false;
         this.documentHasChanges = false;
         this.captureTable.clear();
+        this.sourceTargetRegistry = null;
         this.receiptCollector?.clear();
         return this.originalDocumentXml;
     }