@ansonlai/docx-redline-js 0.5.4 → 0.6.0

package/services/operation-batch-compiler.js

@@ -0,0 +1,394 @@
+import {
+    buildParagraphMetadataIndex,
+    getDocumentParagraphNodes,
+    getParagraphId,
+    resolveTargetParagraph
+} from '../core/paragraph-targeting.js';
+import {
+    normalizeDocumentOperation,
+    normalizeTargetDescriptor,
+    validateDocumentOperation
+} from './document-operation-contract.js';
+
+const TEXT_WRITE_KINDS = new Set(['redline', 'restore', 'rejected-insert']);
+const FORMAT_WRITE_KINDS = new Set(['highlight', 'format', 'paragraph-format']);
+
+function normalizedError(error) {
+    return {
+        code: typeof error?.code === 'string' && error.code ? error.code : 'OPERATION_ERROR',
+        message: error?.message || String(error),
+        ...(Array.isArray(error?.candidates) ? { candidates: error.candidates } : {})
+    };
+}
+
+function isParagraphAttached(document, paragraph) {
+    return !!paragraph && getDocumentParagraphNodes(document).includes(paragraph);
+}
+
+function paragraphNodesFromMutation(nodes = []) {
+    const paragraphs = [];
+    for (const node of nodes) {
+        if (!node || node.nodeType !== 1) continue;
+        if (node.localName === 'p') paragraphs.push(node);
+        for (const paragraph of Array.from(node.getElementsByTagNameNS?.('*', 'p') || [])) {
+            if (!paragraphs.includes(paragraph)) paragraphs.push(paragraph);
+        }
+    }
+    return paragraphs;
+}
+
+/** Session-local source identities over live paragraph nodes. */
+export class SourceTargetRegistry {
+    constructor(document) {
+        this.document = document;
+        this.nextId = 1;
+        this.entries = new Map();
+        this.idsByNode = new WeakMap();
+    }
+
+    register(paragraph, metadata = {}) {
+        const existing = this.idsByNode.get(paragraph);
+        if (existing) return existing;
+        const sourceId = `S${this.nextId++}`;
+        this.entries.set(sourceId, {
+            sourceId,
+            paragraph,
+            sourceIndex: metadata.index || null,
+            paragraphId: metadata.paragraphId || null,
+            fingerprint: metadata.fingerprint || null,
+            text: metadata.text || '',
+            revisionView: metadata.revisionView === 'rejected' ? 'rejected' : 'accepted',
+            consumed: false,
+            consumedByOperation: null
+        });
+        this.idsByNode.set(paragraph, sourceId);
+        return sourceId;
+    }
+
+    describe(sourceId) {
+        const entry = this.entries.get(sourceId);
+        if (!entry) return null;
+        return {
+            sourceId,
+            index: entry.sourceIndex,
+            paragraphId: entry.paragraphId,
+            fingerprint: entry.fingerprint,
+            text: entry.text,
+            revisionView: entry.revisionView
+        };
+    }
+
+    resolve(sourceId, document = this.document) {
+        const entry = this.entries.get(sourceId);
+        if (!entry) {
+            return {
+                error: {
+                    code: 'SOURCE_TARGET_NOT_FOUND',
+                    message: `Compiled source target ${String(sourceId)} was not found.`
+                }
+            };
+        }
+        if (entry.consumed) {
+            return {
+                error: {
+                    code: 'TARGET_CONSUMED_BY_OPERATION',
+                    message: `Compiled source target ${sourceId} was consumed by operation ${entry.consumedByOperation}.`,
+                    sourceTarget: this.describe(sourceId),
+                    consumedByOperation: entry.consumedByOperation
+                }
+            };
+        }
+        if (isParagraphAttached(document, entry.paragraph)) {
+            return { paragraph: entry.paragraph, resolvedBy: 'batch_source' };
+        }
+        return {
+            error: {
+                code: 'TARGET_CONSUMED_BY_OPERATION',
+                message: `Compiled source target ${sourceId} is no longer present in the live document.`,
+                sourceTarget: this.describe(sourceId),
+                consumedByOperation: entry.consumedByOperation
+            }
+        };
+    }
+
+    createSavepoint(document = this.document) {
+        const paragraphs = getDocumentParagraphNodes(document);
+        return new Map(Array.from(this.entries, ([sourceId, entry]) => [sourceId, {
+            paragraphIndex: paragraphs.indexOf(entry.paragraph),
+            consumed: entry.consumed,
+            consumedByOperation: entry.consumedByOperation
+        }]));
+    }
+
+    restoreSavepoint(document, snapshot) {
+        this.document = document;
+        this.idsByNode = new WeakMap();
+        const paragraphs = getDocumentParagraphNodes(document);
+        for (const [sourceId, entry] of this.entries) {
+            const saved = snapshot instanceof Map ? snapshot.get(sourceId) : null;
+            entry.consumed = saved?.consumed === true;
+            entry.consumedByOperation = saved?.consumedByOperation || null;
+            entry.paragraph = Number.isInteger(saved?.paragraphIndex) && saved.paragraphIndex >= 0
+                ? (paragraphs[saved.paragraphIndex] || null)
+                : null;
+            if (entry.paragraph) this.idsByNode.set(entry.paragraph, sourceId);
+        }
+    }
+
+    commitMutation(sourceId, removedNodes, liveNodes, operationIndex) {
+        const entry = this.entries.get(sourceId);
+        if (!entry || !Array.isArray(removedNodes) || !removedNodes.includes(entry.paragraph)) return;
+        const candidates = paragraphNodesFromMutation(liveNodes);
+        const sameId = entry.paragraphId
+            ? candidates.filter(paragraph => getParagraphId(paragraph) === entry.paragraphId)
+            : [];
+        const successor = sameId.length === 1
+            ? sameId[0]
+            : (candidates.length === 1 ? candidates[0] : null);
+        if (successor) {
+            entry.paragraph = successor;
+            this.idsByNode.set(successor, sourceId);
+            return;
+        }
+        entry.paragraph = null;
+        entry.consumed = true;
+        entry.consumedByOperation = operationIndex;
+    }
+}
+
+function resolvedTarget(metadata, revisionView) {
+    return {
+        index: metadata.index,
+        paragraphId: metadata.paragraphId,
+        fingerprint: metadata.fingerprint,
+        text: metadata.text,
+        inTable: metadata.inTable,
+        revisionView
+    };
+}
+
+function resolveDescriptor(xmlDoc, descriptor, kind, strictTargets, metadataIndices, callbacks = {}) {
+    const revisionView = descriptor?.revisionView === 'rejected' ? 'rejected' : 'accepted';
+    if (!metadataIndices[revisionView]) {
+        metadataIndices[revisionView] = buildParagraphMetadataIndex(xmlDoc, { revisionView });
+    }
+    const index = metadataIndices[revisionView];
+    const resolution = resolveTargetParagraph(xmlDoc, {
+        targetText: descriptor.text,
+        targetRef: descriptor.index,
+        targetDescriptor: descriptor,
+        opType: kind,
+        strictAmbiguity: strictTargets,
+        paragraphMetadataIndex: index,
+        metadataIndices,
+        onInfo: callbacks.onInfo,
+        onWarn: callbacks.onWarn
+    });
+    const metadata = index.byParagraph.get(resolution.paragraph);
+    return {
+        paragraph: resolution.paragraph,
+        resolvedBy: resolution.resolvedBy,
+        metadata: resolvedTarget(metadata, revisionView)
+    };
+}
+
+function buildConflict(code, message, bindings, target, action) {
+    return {
+        code,
+        message,
+        operationIndexes: bindings.map(binding => binding.index).sort((a, b) => a - b),
+        target,
+        recovery: {
+            action,
+            sameArgumentsSafe: false,
+            requiresReinspection: false,
+            requiresUserAuthorization: false
+        }
+    };
+}
+
+/** Resolve source targets once and derive source-level conflicts before mutation. */
+export function compileOperationBatch(xmlDoc, operations = [], options = {}) {
+    const sourceOperations = Array.isArray(operations) ? operations : [];
+    const strictTargets = options.strictTargets !== false;
+    const registry = new SourceTargetRegistry(xmlDoc);
+    const metadataIndices = {
+        accepted: buildParagraphMetadataIndex(xmlDoc, { revisionView: 'accepted' }),
+        rejected: null
+    };
+    const bindings = [];
+    const compiledOperations = [];
+
+    for (let index = 0; index < sourceOperations.length; index += 1) {
+        const sourceOperation = sourceOperations[index];
+        const validation = validateDocumentOperation(sourceOperation);
+        const operation = validation.operation || normalizeDocumentOperation(sourceOperation);
+        const binding = {
+            index: index + 1,
+            operationKind: operation.operationKind,
+            operationId: operation.operationId,
+            sourceIds: [],
+            warnings: []
+        };
+        const compiled = { ...sourceOperation };
+
+        const dynamicOccurrence = operation.targetDescriptor?.occurrence != null
+            && !operation.targetDescriptor?.paragraphId
+            && !operation.targetDescriptor?.fingerprint;
+        const compositeTextTarget = typeof operation.targetDescriptor?.text === 'string'
+            && /\r|\n/.test(operation.targetDescriptor.text)
+            && !operation.targetEndDescriptor;
+        if (dynamicOccurrence || compositeTextTarget) binding.dynamic = true;
+
+        if (
+            validation.valid
+            && operation.operationKind !== 'comment_reply'
+            && !operation.targetDescriptor?.captureRef
+            && !binding.dynamic
+        ) {
+            try {
+                const start = resolveDescriptor(
+                    xmlDoc,
+                    operation.targetDescriptor,
+                    operation.operationKind,
+                    strictTargets,
+                    metadataIndices,
+                    {
+                        onInfo: options.onInfo,
+                        onWarn: warning => binding.warnings.push(String(warning))
+                    }
+                );
+                const startId = registry.register(start.paragraph, start.metadata);
+                binding.sourceIds.push(startId);
+                binding.resolvedBy = start.resolvedBy;
+                binding.resolvedTarget = start.metadata;
+                compiled._compiledSourceId = startId;
+                compiled._compiledResolvedBy = start.resolvedBy;
+                if (binding.warnings.length > 0) compiled._compiledWarnings = binding.warnings;
+
+                const targetEndDescriptor = operation.targetEndDescriptor
+                    || (operation.targetEndRef != null
+                        ? normalizeTargetDescriptor(null, operation.targetEndRef, operation.targetDescriptor.revisionView)
+                        : null);
+                if (targetEndDescriptor) {
+                    const end = resolveDescriptor(
+                        xmlDoc,
+                        targetEndDescriptor,
+                        operation.operationKind,
+                        strictTargets,
+                        metadataIndices,
+                        {
+                            onInfo: options.onInfo,
+                            onWarn: warning => binding.warnings.push(String(warning))
+                        }
+                    );
+                    const endId = registry.register(end.paragraph, end.metadata);
+                    compiled._compiledSourceEndId = endId;
+                    const paragraphs = getDocumentParagraphNodes(xmlDoc);
+                    const startIndex = paragraphs.indexOf(start.paragraph);
+                    const endIndex = paragraphs.indexOf(end.paragraph);
+                    if (startIndex < 0 || endIndex < startIndex) {
+                        throw Object.assign(new Error('Target range is not a forward contiguous paragraph range.'), {
+                            code: 'TARGET_RANGE_INVALID'
+                        });
+                    }
+                    for (const paragraph of paragraphs.slice(startIndex, endIndex + 1)) {
+                        const viewIndex = metadataIndices[operation.targetDescriptor.revisionView] || metadataIndices.accepted;
+                        const metadata = viewIndex.byParagraph.get(paragraph);
+                        binding.sourceIds.push(registry.register(paragraph, metadata || {}));
+                    }
+                    binding.sourceIds = [...new Set(binding.sourceIds)];
+                    binding.resolvedTargetEnd = end.metadata;
+                }
+            } catch (error) {
+                binding.error = normalizedError(error);
+            }
+        }
+        bindings.push(binding);
+        compiledOperations.push(compiled);
+    }
+
+    const existingCaptureKeys = new Set(compiledOperations.map(operation => operation?.captureKey).filter(Boolean));
+    let nextImplicitCapture = 1;
+    for (const binding of bindings) {
+        if (binding.error?.code !== 'TARGET_NOT_FOUND') continue;
+        const consumerIndex = binding.index - 1;
+        const consumer = normalizeDocumentOperation(sourceOperations[consumerIndex]);
+        const targetText = consumer.targetDescriptor?.text;
+        if (!targetText) continue;
+        const producers = sourceOperations.flatMap((candidate, producerIndex) => {
+            if (producerIndex === consumerIndex || typeof candidate?.modified !== 'string') return [];
+            const createdParagraphs = candidate.modified.split(/\r?\n/).map(text => text.trim()).filter(Boolean);
+            return createdParagraphs.includes(targetText.trim()) ? [{ candidate, producerIndex }] : [];
+        });
+        if (producers.length !== 1) continue;
+        const [{ candidate: producer, producerIndex }] = producers;
+        let captureKey = producer.captureKey || compiledOperations[producerIndex].captureKey;
+        if (!captureKey) {
+            do {
+                captureKey = `__batch_created_${nextImplicitCapture++}`;
+            } while (existingCaptureKeys.has(captureKey));
+            existingCaptureKeys.add(captureKey);
+            compiledOperations[producerIndex].captureKey = captureKey;
+        }
+        compiledOperations[consumerIndex].target = { captureRef: captureKey, select: targetText };
+        delete compiledOperations[consumerIndex]._compiledSourceId;
+        delete compiledOperations[consumerIndex]._compiledResolvedBy;
+        delete binding.error;
+        binding.sourceIds = [];
+        binding.resolvedBy = 'created_content_dependency';
+        binding.createdByOperation = producerIndex + 1;
+        binding.captureRef = captureKey;
+    }
+
+    const bySource = new Map();
+    for (const binding of bindings) {
+        if (binding.error || binding.dynamic) continue;
+        for (const sourceId of binding.sourceIds) {
+            if (!bySource.has(sourceId)) bySource.set(sourceId, []);
+            bySource.get(sourceId).push(binding);
+        }
+    }
+
+    const conflicts = [];
+    const conflictKeys = new Set();
+    for (const [sourceId, sourceBindings] of bySource) {
+        const textWrites = sourceBindings.filter(binding => TEXT_WRITE_KINDS.has(binding.operationKind));
+        const formatWrites = sourceBindings.filter(binding => FORMAT_WRITE_KINDS.has(binding.operationKind));
+        if (textWrites.length > 1) {
+            const key = `text:${textWrites.map(binding => binding.index).sort().join(',')}`;
+            if (!conflictKeys.has(key)) {
+                conflictKeys.add(key);
+                conflicts.push(buildConflict(
+                    'OVERLAPPING_SOURCE_TARGETS',
+                    `Operations ${textWrites.map(binding => binding.index).join(', ')} contain incompatible text writes to the same batch-start source target.`,
+                    textWrites,
+                    registry.describe(sourceId),
+                    'consolidate_operations'
+                ));
+            }
+        }
+        if (textWrites.length > 0 && formatWrites.length > 0) {
+            const affected = [...textWrites, ...formatWrites];
+            const key = `format:${affected.map(binding => binding.index).sort().join(',')}`;
+            if (!conflictKeys.has(key)) {
+                conflictKeys.add(key);
+                conflicts.push(buildConflict(
+                    'REVISION_ORDER_CONFLICT',
+                    `Operations ${affected.map(binding => binding.index).join(', ')} combine text and formatting writes on the same batch-start source target.`,
+                    affected,
+                    registry.describe(sourceId),
+                    'split_or_consolidate_operations'
+                ));
+            }
+        }
+    }
+
+    return {
+        valid: conflicts.length === 0 && bindings.every(binding => !binding.error),
+        compiledOperations,
+        bindings,
+        conflicts,
+        registry
+    };
+}

package/services/operation-preflight.js

@@ -29,14 +29,12 @@ import {
     resolveDocumentOperationAuthor,
     validateDocumentOperation
 } from './document-operation-contract.js';
-import { buildOperationDependencyPlan } from './batch-operation-orchestrator.js';
-
-function normalizedError(error) {
-    return {
-        code: typeof error?.code === 'string' && error.code ? error.code : 'OPERATION_ERROR',
-        message: error?.message || String(error),
-        ...(Array.isArray(error?.candidates) ? { candidates: error.candidates } : {})
-    };
+import { buildOperationDependencyPlan } from './batch-operation-orchestrator.js';
+import { compileOperationBatch } from './operation-batch-compiler.js';
+import { normalizeErrorWithRecovery } from './error-recovery.js';
+
+function normalizedError(error, context = {}) {
+    return normalizeErrorWithRecovery(error, context);
 }
 
 function operationNeedsNumbering(operation) {
@@ -70,10 +68,6 @@ function targetMetadata(xmlDoc, paragraph, resolvedBy, suppliedText, paragraphMe
     };
 }
 
-function buildConflict(code, message, operationIndexes, target) {
-    return { code, message, operationIndexes, target };
-}
-
 function getCommentIdsInParagraph(paragraph) {
     const ids = new Set();
     for (const localName of ['commentRangeStart', 'commentRangeEnd', 'commentReference']) {
@@ -90,10 +84,10 @@ export function preflightOperations(documentXml, operations, author, options = {
         return {
             valid: false,
             status: 'error',
-            error: {
+            error: normalizedError({
                 code: 'INVALID_OPERATION',
                 message: `Unsupported existingRevisions policy: "${String(options.existingRevisions)}".`
-            },
+            }),
             results: [],
             conflicts: [],
             authorsUsed: [],
@@ -105,7 +99,7 @@ export function preflightOperations(documentXml, operations, author, options = {
         return {
             valid: false,
             status: 'error',
-            error: parsed.error,
+            error: normalizedError(parsed.error),
             results: [],
             conflicts: [],
             authorsUsed: [],
@@ -119,19 +113,23 @@ export function preflightOperations(documentXml, operations, author, options = {
         rejected: null
     };
     const sourceOperations = Array.isArray(operations) ? operations : [];
-    const dependencyPlan = buildOperationDependencyPlan(sourceOperations);
-    if (!dependencyPlan.valid) {
+    const batchCompilation = compileOperationBatch(xmlDoc, sourceOperations, {
+        strictTargets: options.strictTargets !== false,
+        onInfo: options.onInfo,
+        onWarn: options.onWarn
+    });
+    const dependencyPlan = buildOperationDependencyPlan(batchCompilation.compiledOperations);
+    if (!dependencyPlan.valid) {
         return {
             valid: false,
             status: 'error',
-            error: dependencyPlan.error,
+            error: normalizedError(dependencyPlan.error),
             results: [],
             conflicts: [],
             authorsUsed: [],
             requiredArtifacts: { comments: false, numbering: false }
         };
-    }
-
+    }
     const strictTargets = options.strictTargets !== false;
     const results = [];
     const authorsUsed = new Set();
@@ -175,7 +173,7 @@ export function preflightOperations(documentXml, operations, author, options = {
             continue;
         }
 
-        if (operation.targetDescriptor?.captureRef) {
+        if (operation.targetDescriptor?.captureRef) {
             results.push({
                 index: index + 1,
                 type: sourceOperation?.type || 'redline',
@@ -186,8 +184,35 @@ export function preflightOperations(documentXml, operations, author, options = {
                 captureRef: operation.targetDescriptor.captureRef,
                 ...(operation.targetDescriptor.select ? { select: operation.targetDescriptor.select } : {})
             });
-            continue;
-        }
+            continue;
+        }
+
+        const compiledBinding = batchCompilation.bindings[index];
+        if (compiledBinding?.error) {
+            results.push({
+                index: index + 1,
+                type: sourceOperation?.type || 'redline',
+                operationType: operation.operationKind,
+                status: 'error',
+                authorUsed,
+                error: compiledBinding.error
+            });
+            continue;
+        }
+        if (compiledBinding?.createdByOperation) {
+            results.push({
+                index: index + 1,
+                type: sourceOperation?.type || 'redline',
+                operationType: operation.operationKind,
+                status: 'deferred',
+                authorUsed,
+                resolvedBy: 'created_content_dependency',
+                captureRef: compiledBinding.captureRef,
+                select: operation.targetDescriptor.text,
+                createdByOperation: compiledBinding.createdByOperation
+            });
+            continue;
+        }
 
         const targetView = operation.targetDescriptor?.revisionView === 'rejected' ? 'rejected' : 'accepted';
         let currentMetadataIndex = targetView === 'rejected'
@@ -195,17 +220,28 @@ export function preflightOperations(documentXml, operations, author, options = {
             : metadataIndices.accepted;
 
         try {
-            const resolved = resolveTargetParagraph(xmlDoc, {
-                targetText: operation.target,
-                targetRef: operation.targetRef,
-                targetDescriptor: operation.targetDescriptor,
-                opType: operation.operationKind,
-                strictAmbiguity: strictTargets,
-                paragraphMetadataIndex: currentMetadataIndex,
-                metadataIndices,
-                onInfo: options.onInfo,
-                onWarn: options.onWarn
-            });
+            let resolved;
+            if (compiledBinding.dynamic) {
+                resolved = resolveTargetParagraph(xmlDoc, {
+                    targetText: operation.target,
+                    targetRef: operation.targetRef,
+                    targetDescriptor: operation.targetDescriptor,
+                    opType: operation.operationKind,
+                    strictAmbiguity: strictTargets,
+                    paragraphMetadataIndex: currentMetadataIndex,
+                    metadataIndices,
+                    onInfo: options.onInfo,
+                    onWarn: options.onWarn
+                });
+            } else {
+                const bound = batchCompilation.registry.resolve(compiledBinding.sourceIds[0], xmlDoc);
+                if (bound.error) throw Object.assign(new Error(bound.error.message), bound.error);
+                resolved = {
+                    paragraph: bound.paragraph,
+                    resolvedBy: compiledBinding.resolvedBy,
+                    warnings: compiledBinding.warnings
+                };
+            }
             const paragraph = resolved.paragraph;
             const metadata = targetMetadata(xmlDoc, paragraph, resolved.resolvedBy, operation.target, currentMetadataIndex, targetView);
             const paragraphText = metadata.resolvedTarget.text;
@@ -313,8 +349,10 @@ export function preflightOperations(documentXml, operations, author, options = {
                     const allSame = authors.length > 0 && authors.every(a => a.trim().toLowerCase() === opAuthor);
                     if (!allSame && existingPolicy === 'merge-same-author') {
                         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.`
+                            code: 'EXISTING_REVISIONS',
+                            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
                         };
                     } else if (allSame) {
                         const mergeCommentIds = getCommentIdsInParagraph(paragraph);
@@ -408,43 +446,24 @@ export function preflightOperations(documentXml, operations, author, options = {
         }
     }
 
-    const conflicts = [];
-    const byTarget = new Map();
-    for (const result of results) {
-        const targetIndex = result.resolvedTarget?.index;
-        if (!targetIndex) continue;
-        if (!byTarget.has(targetIndex)) byTarget.set(targetIndex, []);
-        byTarget.get(targetIndex).push(result);
-    }
-
-    for (const [targetIndex, targetResults] of byTarget) {
-        const redlines = targetResults.filter(result => ['redline', 'restore', 'rejected-insert'].includes(result.operationType));
-        const highlights = targetResults.filter(result => result.operationType === 'highlight');
-        const target = targetResults[0].resolvedTarget;
-        if (redlines.length > 1) {
-            conflicts.push(buildConflict(
-                'OVERLAPPING_TEXT_EDITS',
-                `Multiple text edits target paragraph ${targetIndex}; later operations may use a stale anchor.`,
-                redlines.map(result => result.index),
-                target
-            ));
-        }
-        if (redlines.length > 0 && highlights.length > 0) {
-            conflicts.push(buildConflict(
-                'REVISION_ORDER_CONFLICT',
-                `A text edit and highlight target paragraph ${targetIndex}; operation order can invalidate the target or existing-revision policy.`,
-                [...redlines, ...highlights].map(result => result.index).sort((a, b) => a - b),
-                target
-            ));
-        }
-    }
+    const conflicts = batchCompilation.conflicts;
 
-    const hasErrors = results.some(result => result.status === 'error');
-    return {
-        valid: !hasErrors && conflicts.length === 0,
-        status: !hasErrors && conflicts.length === 0 ? 'ok' : 'error',
-        results,
-        conflicts,
+    const enrichedResults = results.map(result => result.error ? {
+        ...result,
+        error: normalizedError(result.error, {
+            operationIndex: result.index,
+            ...(sourceOperations[result.index - 1]?.operationId
+                ? { operationId: sourceOperations[result.index - 1].operationId }
+                : {})
+        })
+    } : result);
+    const enrichedConflicts = conflicts.map(conflict => normalizedError(conflict));
+    const hasErrors = enrichedResults.some(result => result.status === 'error');
+    return {
+        valid: !hasErrors && enrichedConflicts.length === 0,
+        status: !hasErrors && enrichedConflicts.length === 0 ? 'ok' : 'error',
+        results: enrichedResults,
+        conflicts: enrichedConflicts,
         authorsUsed: Array.from(authorsUsed),
         requiredArtifacts: {
             comments: commentsRequired,

package/services/standalone-operation-runner.d.ts

@@ -10,9 +10,11 @@ export interface ParagraphTargetDescriptor {
   inTable?: boolean;
   fingerprint?: string;
   sourceFingerprint?: string;
+  /** Defaults to rejected for restore operations and accepted for all other operations. */
   revisionView?: 'accepted' | 'rejected';
   captureRef?: string;
   select?: string;
+  createdByOperation?: number;
 }
 
 export interface InsertionAffinity {
@@ -238,6 +240,17 @@ export interface DocumentOperationBatchResult {
   status?: RedlineStatus;
   error?: RedlineError;
   warnings?: string[];
+  conflicts?: OperationConflict[];
+  retryPlan?: MutationRetryPlan;
+}
+
+export interface MutationRetryPlan {
+  base: 'original' | 'output';
+  committedIndexes: number[];
+  failedIndexes: number[];
+  unattemptedIndexes: number[];
+  replayWholeBatch: boolean;
+  sameArgumentsSafe: false;
 }
 
 export interface OperationPreflightItemResult {
@@ -271,10 +284,13 @@ export interface OperationPreflightItemResult {
 }
 
 export interface OperationConflict {
-  code: 'OVERLAPPING_TEXT_EDITS' | 'REVISION_ORDER_CONFLICT' | string;
+  code: 'OVERLAPPING_SOURCE_TARGETS' | 'OVERLAPPING_TEXT_EDITS' | 'REVISION_ORDER_CONFLICT' | 'CAPTURE_FANOUT_CONFLICT' | string;
   message: string;
   operationIndexes: number[];
   target: ResolvedDocumentTarget;
+  recoveryVersion?: number;
+  category?: string;
+  recovery?: RedlineError['recovery'];
 }
 
 export interface OperationPreflightResult {