@ansonlai/docx-redline-js 0.5.4 → 0.6.1

package/services/document-operation-applier.js

@@ -30,21 +30,22 @@ import {
 } from './receipt-collector.js';
 import { validateRedlineOoxml } from '../core/redline-validation.js';
 import { subtractValidationIssueMultiset, validationErrors } from '../core/validation-delta.js';
-
-export function normalizeOperationError(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 { normalizeErrorWithRecovery } from './error-recovery.js';
+
+export function normalizeOperationError(error, context = {}) {
+    return normalizeErrorWithRecovery(error, context);
+}
 
 /**
  * Validates and dispatches one structured operation against full document XML.
  * Result metadata is assembled here so every mutation path exposes the same
  * */
-export async function applyOperationToDocumentXml(documentXml, op, author, runtimeContext = null, options = {}) {
-    const operationIndex = typeof options._operationIndex === 'number' ? options._operationIndex : 1;
+export async function applyOperationToDocumentXml(documentXml, op, author, runtimeContext = null, options = {}) {
+    const operationIndex = typeof options._operationIndex === 'number' ? options._operationIndex : 1;
+    const errorContext = {
+        operationIndex,
+        ...(typeof op?.operationId === 'string' ? { operationId: op.operationId } : {})
+    };
     const validation = validateDocumentOperation(op);
     if (!validation.valid) {
         const authorUsed = resolveDocumentOperationAuthor(op, author, getDefaultAuthor());
@@ -52,7 +53,7 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
             documentXml,
             hasChanges: false,
             status: 'error',
-            error: validation.error,
+            error: normalizeOperationError(validation.error, errorContext),
             operationType: normalizeDocumentOperation(op).operationKind,
             authorUsed,
             receipt: createEmptyReceipt(operationIndex, op?.operationId, authorUsed, 'refused')
@@ -75,10 +76,10 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
             documentXml,
             hasChanges: false,
             status: 'error',
-            error: {
-                code: 'UNSUPPORTED_REVISION_VIEW_MUTATION',
-                message: 'Targeting rejected revision view for mutation is not supported yet.'
-            },
+            error: normalizeOperationError({
+                code: 'UNSUPPORTED_REVISION_VIEW_MUTATION',
+                message: 'Targeting rejected revision view for mutation is not supported yet.'
+            }, errorContext),
             operationType: operation.operationKind,
             authorUsed,
             receipt: createEmptyReceipt(operationIndex, operation.operationId, authorUsed, 'refused')
@@ -92,10 +93,10 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                 documentXml,
                 hasChanges: false,
                 status: 'error',
-                error: {
-                    code: tokenValidation.error?.code || 'INVALID_REVISION_TOKEN',
-                    message: tokenValidation.error?.message || 'Invalid revision token.'
-                },
+                error: normalizeOperationError({
+                    code: tokenValidation.error?.code || 'INVALID_REVISION_TOKEN',
+                    message: tokenValidation.error?.message || 'Invalid revision token.'
+                }, errorContext),
                 operationType: operation.operationKind,
                 authorUsed,
                 receipt: createEmptyReceipt(operationIndex, operation.operationId, authorUsed, 'refused')
@@ -106,10 +107,10 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                 documentXml,
                 hasChanges: false,
                 status: 'error',
-                error: {
-                    code: 'REVISION_TOKEN_SCOPE_MISMATCH',
-                    message: `Revision token scope mismatch: expected 'document-parts', got '${options.expectedRevision.scope}'.`
-                },
+                error: normalizeOperationError({
+                    code: 'REVISION_TOKEN_SCOPE_MISMATCH',
+                    message: `Revision token scope mismatch: expected 'document-parts', got '${options.expectedRevision.scope}'.`
+                }, errorContext),
                 operationType: operation.operationKind,
                 authorUsed,
                 receipt: createEmptyReceipt(operationIndex, operation.operationId, authorUsed, 'refused')
@@ -127,10 +128,12 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                 documentXml,
                 hasChanges: false,
                 status: 'error',
-                error: {
-                    code: 'REVISION_MISMATCH',
-                    message: `Document revision mismatch: expected '${options.expectedRevision.value}', current is '${currentToken.value}'.`
-                },
+                error: normalizeOperationError({
+                    code: 'REVISION_MISMATCH',
+                    message: `Document revision mismatch: expected '${options.expectedRevision.value}', current is '${currentToken.value}'.`,
+                    expectedRevision: options.expectedRevision,
+                    currentRevision: currentToken
+                }, errorContext),
                 operationType: operation.operationKind,
                 authorUsed,
                 receipt: createEmptyReceipt(operationIndex, operation.operationId, authorUsed, 'refused')
@@ -146,7 +149,7 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
             documentXml,
             hasChanges: false,
             status: 'error',
-            error: session.parseResult.error,
+            error: normalizeOperationError(session.parseResult.error, errorContext),
             warnings: session.parseResult.warnings,
             operationType: operation.operationKind,
             authorUsed,
@@ -161,7 +164,9 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
         operation.operationId,
         authorUsed
     );
-    const operationWarnings = [];
+    const operationWarnings = Array.isArray(operation._compiledWarnings)
+        ? [...operation._compiledWarnings]
+        : [];
     const operationOptions = {
         ...options,
         ...(typeof operation.generateRedlines === 'boolean' ? { generateRedlines: operation.generateRedlines } : {}),
@@ -173,6 +178,10 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
         ...(operation.formattingRevisionPolicy ? { formattingRevisionPolicy: operation.formattingRevisionPolicy } : {}),
         targetDescriptor: operation.targetDescriptor,
         targetEndDescriptor: operation.targetEndDescriptor,
+        _compiledSourceId: operation._compiledSourceId || null,
+        _compiledSourceEndId: operation._compiledSourceEndId || null,
+        _compiledResolvedBy: operation._compiledResolvedBy || null,
+        _sourceTargetRegistry: session.sourceTargetRegistry || null,
         _resolutionCapture: resolutionCapture,
         _revisionIdAllocator: session.revisionIdAllocator,
         _documentOperationSession: session,
@@ -345,12 +354,12 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                     documentXml,
                     hasChanges: false,
                     status: 'error',
-                    error: {
+                    error: normalizeOperationError({
                         code: 'GENERATED_OOXML_INVALID',
                         stage: 'validation',
                         message: `Operation introduced invalid OOXML (${codes}).`,
                         generatedIssues: generatedErrors
-                    },
+                    }, errorContext),
                     operationType: operation.operationKind,
                     authorUsed,
                     receipt: operationReceipt,
@@ -358,6 +367,14 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                 };
             }
             session.markMutationCommitted(operation.operationKind !== 'comment_reply');
+            if (operation._compiledSourceId && session.sourceTargetRegistry) {
+                session.sourceTargetRegistry.commitMutation(
+                    operation._compiledSourceId,
+                    operationOptions._mutationRemovedNodes,
+                    operationOptions._mutationLiveNodes,
+                    operationIndex
+                );
+            }
             if (operation.captureKey && session.captureTable) {
                 session.captureTable.set(
                     operation.captureKey,
@@ -394,7 +411,7 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                         documentXml,
                         hasChanges: false,
                         status: 'error',
-                        error: reconciliation.error,
+                        error: normalizeOperationError(reconciliation.error, errorContext),
                         warnings: [reconciliation.error.message],
                         operationType: operation.operationKind,
                         authorUsed,
@@ -404,7 +421,8 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                 }
             }
         }
-        return {
+        if (result?.error) result.error = normalizeOperationError(result.error, errorContext);
+        return {
             ...result,
             operationType: operation.operationKind,
             authorUsed,
@@ -413,7 +431,7 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
         };
     } catch (error) {
         session.restoreSavepoint(savepoint);
-        const normalizedError = normalizeOperationError(error);
+        const normalizedError = normalizeOperationError(error, errorContext);
         const operationReceipt = createEmptyReceipt(
             operationIndex,
             operation.operationId,

package/services/document-operation-contract.js

@@ -51,7 +51,8 @@ export function getCanonicalOperationType(operation) {
     return 'redline';
 }
 
-export function normalizeTargetDescriptor(target, legacyTargetRef = null) {
+export function normalizeTargetDescriptor(target, legacyTargetRef = null, defaultRevisionView = 'accepted') {
+    const fallbackRevisionView = defaultRevisionView === 'rejected' ? 'rejected' : 'accepted';
     if (!isRecord(target)) {
         return {
             text: typeof target === 'string' ? target : '',
@@ -60,7 +61,7 @@ export function normalizeTargetDescriptor(target, legacyTargetRef = null) {
             occurrence: null,
             inTable: null,
             fingerprint: null,
-            revisionView: 'accepted'
+            revisionView: fallbackRevisionView
         };
     }
 
@@ -77,7 +78,9 @@ export function normalizeTargetDescriptor(target, legacyTargetRef = null) {
         fingerprint: nonEmptyString(target.fingerprint)
             ? target.fingerprint.trim()
             : (nonEmptyString(target.sourceFingerprint) ? target.sourceFingerprint.trim() : null),
-        revisionView: target.revisionView === 'rejected' ? 'rejected' : 'accepted',
+        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
     };
@@ -85,11 +88,12 @@ export function normalizeTargetDescriptor(target, legacyTargetRef = null) {
 
 export function normalizeDocumentOperation(operation) {
     const source = isRecord(operation) ? operation : {};
-    const targetDescriptor = normalizeTargetDescriptor(source.target, source.targetRef);
+    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)
+        ? normalizeTargetDescriptor(source.targetEnd, source.targetEndRef, defaultRevisionView)
         : null;
-    const kind = getCanonicalOperationType(source);
 
     return {
         ...source,

package/services/document-operation-mutations.js

@@ -224,11 +224,36 @@ function describeTargetTextMatch(actualText, requestedText) {
     };
 }
 
-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 {
@@ -1106,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,
@@ -1120,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);
@@ -1669,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
                     }
                 };
             }

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;
     }

package/services/error-recovery.js

@@ -0,0 +1,174 @@
+export const ERROR_RECOVERY_VERSION = 1;
+
+const RULES = Object.freeze({
+    INVALID_OPERATION: ['request', 'request_fixable', 'change_request'],
+    INVALID_AGENT_REQUEST: ['request', 'request_fixable', 'change_request'],
+    INVALID_FILTER: ['request', 'request_fixable', 'change_request'],
+    INVALID_OPERATIONS_FILE: ['request', 'request_fixable', 'change_request'],
+    OPERATIONS_REQUIRED: ['request', 'request_fixable', 'change_request'],
+    UNKNOWN_OPTION: ['request', 'request_fixable', 'change_request'],
+    UNEXPECTED_ARGUMENT: ['request', 'request_fixable', 'change_request'],
+    INVALID_ACTION: ['request', 'request_fixable', 'change_request'],
+    INVALID_PROFILE: ['request', 'request_fixable', 'change_request'],
+    INVALID_REVISION_TOKEN: ['revision-check', 'request_fixable', 'change_request'],
+    BATCH_OPERATION_FAILED: ['batch-execution', 'request_fixable', 'inspect_failed_operations'],
+    REVISION_TOKEN_SCOPE_MISMATCH: ['revision-check', 'request_fixable', 'change_request'],
+    REVISION_MISMATCH: ['revision-check', 'target_refresh_required', 'reinspect'],
+    TARGET_NOT_FOUND: ['target-resolution', 'target_refresh_required', 'reinspect'],
+    SOURCE_TARGET_NOT_FOUND: ['target-resolution', 'target_refresh_required', 'reinspect'],
+    TARGET_TEXT_MISMATCH: ['target-resolution', 'target_refresh_required', 'reinspect'],
+    TARGET_FINGERPRINT_MISMATCH: ['target-resolution', 'target_refresh_required', 'reinspect'],
+    TARGET_INDEX_MISMATCH: ['target-resolution', 'target_refresh_required', 'reinspect'],
+    TARGET_OCCURRENCE_MISMATCH: ['target-resolution', 'candidate_selection_required', 'choose_candidate'],
+    STALE_TARGET_HANDLE: ['target-resolution', 'target_refresh_required', 'reinspect'],
+    TARGET_HANDLE_NOT_FOUND: ['target-resolution', 'target_refresh_required', 'reinspect'],
+    AMBIGUOUS_TARGET: ['target-resolution', 'candidate_selection_required', 'choose_candidate'],
+    TARGET_RANGE_INVALID: ['target-resolution', 'request_fixable', 'change_target_range'],
+    ANCHOR_NOT_FOUND: ['anchor-resolution', 'request_fixable', 'change_anchor'],
+    AMBIGUOUS_ANCHOR: ['anchor-resolution', 'candidate_selection_required', 'choose_candidate'],
+    PATCH_SOURCE_NOT_FOUND: ['patch-compilation', 'request_fixable', 'change_patch'],
+    AMBIGUOUS_PATCH_SOURCE: ['patch-compilation', 'candidate_selection_required', 'choose_occurrence'],
+    OVERLAPPING_PATCHES: ['patch-compilation', 'source_conflict', 'combine_patches'],
+    CONFLICTING_PATCHES: ['patch-compilation', 'source_conflict', 'combine_patches'],
+    PATCH_ROUNDTRIP_MISMATCH: ['patch-validation', 'request_fixable', 'reinspect_and_narrow'],
+    DIFF_TOKEN_LIMIT: ['patch-compilation', 'request_fixable', 'narrow_operation'],
+    STRUCTURED_CONTENT_INVALID: ['request', 'request_fixable', 'change_request'],
+    UNSUPPORTED_INSERTION_AFFINITY: ['request', 'request_fixable', 'change_request'],
+    EXISTING_REVISIONS: ['target-safety', 'policy_choice_required', 'set_option'],
+    COMMENTED_CONTENT_MERGE: ['target-safety', 'user_authorization_required', 'resolve_comments'],
+    COMMENTED_CONTENT_DELETE: ['target-safety', 'user_authorization_required', 'resolve_comments'],
+    OVERLAPPING_SOURCE_TARGETS: ['batch-compilation', 'source_conflict', 'consolidate_operations'],
+    OVERLAPPING_TEXT_EDITS: ['batch-compilation', 'source_conflict', 'consolidate_operations'],
+    REVISION_ORDER_CONFLICT: ['batch-compilation', 'source_conflict', 'split_or_consolidate_operations'],
+    TARGET_CONSUMED_BY_OPERATION: ['batch-execution', 'source_conflict', 'use_created_content_dependency'],
+    CAPTURE_FANOUT_CONFLICT: ['batch-compilation', 'source_conflict', 'split_or_chain_capture_consumers'],
+    DUPLICATE_CAPTURE_KEY: ['batch-compilation', 'request_fixable', 'rename_capture'],
+    CAPTURE_NOT_FOUND: ['batch-compilation', 'request_fixable', 'add_or_correct_capture'],
+    CAPTURE_DEPENDENCY_CYCLE: ['batch-compilation', 'source_conflict', 'replan_batch'],
+    AMBIGUOUS_CAPTURE_SELECTION: ['batch-compilation', 'candidate_selection_required', 'choose_candidate'],
+    CAPTURE_STALE: ['batch-execution', 'source_conflict', 'replan_batch'],
+    GENERATED_OOXML_INVALID: ['validation', 'library_or_builder_failure', 'report_library_failure'],
+    DOCUMENT_SERIALIZATION_FAILED: ['serialization', 'library_or_builder_failure', 'report_library_failure'],
+    PACKAGE_OPERATION_FAILED: ['package', 'library_or_builder_failure', 'report_library_failure'],
+    PACKAGE_VALIDATION: ['package-validation', 'library_or_builder_failure', 'report_library_failure'],
+    MUTATION_RECEIPT_MISMATCH: ['receipt-validation', 'library_or_builder_failure', 'report_library_failure'],
+    FOREIGN_PARAGRAPH_MARK_DELETION: ['target-safety', 'policy_choice_required', 'use_restore_or_leave_deleted'],
+    RESTORATION_STATE_REQUIRED: ['target-safety', 'target_refresh_required', 'reinspect'],
+    RESTORATION_COUNT_MISMATCH: ['request', 'request_fixable', 'change_request'],
+    REJECTED_INSERTION_STATE_REQUIRED: ['target-safety', 'target_refresh_required', 'reinspect'],
+    UNSAFE_REVISION_NESTING: ['target-safety', 'manual_document_resolution', 'manual_resolution'],
+    UNSAFE_REVISION_BOUNDARY: ['target-safety', 'manual_document_resolution', 'manual_resolution'],
+    UNSAFE_PARAGRAPH_BOUNDARY: ['target-safety', 'manual_document_resolution', 'manual_resolution'],
+    UNSAFE_DELETED_TABLE_ROW: ['target-safety', 'manual_document_resolution', 'manual_resolution'],
+    UNSUPPORTED_MOVE_REVISION: ['target-safety', 'manual_document_resolution', 'manual_resolution'],
+    SECTION_BREAK_PARAGRAPH: ['target-safety', 'manual_document_resolution', 'manual_resolution'],
+    UNSAFE_PARAGRAPH_PLACEMENT: ['target-safety', 'manual_document_resolution', 'manual_resolution'],
+    UNSUPPORTED_REVISION_VIEW_MUTATION: ['target-safety', 'manual_document_resolution', 'manual_resolution']
+});
+
+function issueSummary(error) {
+    const issues = Array.isArray(error?.generatedIssues)
+        ? error.generatedIssues
+        : (Array.isArray(error?.issues) ? error.issues : null);
+    if (!issues) return null;
+    const byCode = new Map();
+    for (const issue of issues) {
+        const code = issue?.code || 'UNKNOWN';
+        byCode.set(code, (byCode.get(code) || 0) + 1);
+    }
+    return {
+        total: issues.length,
+        byCode: Array.from(byCode, ([code, count]) => ({ code, count }))
+    };
+}
+
+function ruleFor(code) {
+    return RULES[code] || ['operation', 'manual_document_resolution', 'inspect_error'];
+}
+
+/** Add stable machine recovery metadata while preserving code-specific details. */
+export function normalizeErrorWithRecovery(error, context = {}) {
+    const source = error && typeof error === 'object' ? error : {};
+    const code = typeof source.code === 'string' && source.code ? source.code : 'OPERATION_ERROR';
+    const [defaultStage, category, action] = ruleFor(code);
+    const details = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (key === 'name' || key === 'stack' || key === 'message' || key === 'code') continue;
+        details[key] = value;
+    }
+    const requiresAuthorization = category === 'user_authorization_required';
+    const requiresReinspection = category === 'target_refresh_required'
+        || code === 'PATCH_ROUNDTRIP_MISMATCH';
+    const recovery = {
+        action,
+        sameArgumentsSafe: false,
+        requiresReinspection,
+        requiresUserAuthorization: requiresAuthorization,
+        ...(code === 'EXISTING_REVISIONS' ? {
+            field: 'existingRevisions',
+            recommendedValue: 'slice-cross-author'
+        } : {}),
+        ...(source.recovery && typeof source.recovery === 'object' ? source.recovery : {})
+    };
+    const summary = issueSummary(source);
+    const derivedContext = {
+        ...context,
+        ...(Array.isArray(source.revisionAuthors) ? { revisionAuthors: source.revisionAuthors } : {}),
+        ...(source.currentPolicy ? { currentPolicy: source.currentPolicy } : {})
+    };
+    if (
+        ['TARGET_TEXT_MISMATCH', 'TARGET_FINGERPRINT_MISMATCH'].includes(code)
+        && Array.isArray(source.candidates)
+        && source.candidates.length === 1
+    ) {
+        derivedContext.currentTarget = source.candidates[0];
+        derivedContext.requiresRecomposeModified = true;
+    }
+    return {
+        recoveryVersion: ERROR_RECOVERY_VERSION,
+        code,
+        message: source.message || String(error),
+        stage: source.stage || defaultStage,
+        category: source.category || category,
+        ...details,
+        ...(Object.keys(derivedContext).length > 0 || source.context ? {
+            context: { ...(source.context || {}), ...derivedContext }
+        } : {}),
+        ...(summary ? { issueSummary: summary } : {}),
+        recovery
+    };
+}
+
+export function createRetryPlan({
+    atomic = false,
+    rolledBack = false,
+    results = [],
+    receipts = [],
+    operationCount = null
+} = {}) {
+    const count = Number.isInteger(operationCount)
+        ? operationCount
+        : Math.max(results.length, receipts.length);
+    const attempted = new Set(results.map(result => result?.index).filter(Number.isInteger));
+    const failedIndexes = results
+        .filter(result => result?.status === 'error')
+        .map(result => result.index)
+        .filter(Number.isInteger);
+    const committedIndexes = receipts
+        .filter(receipt => receipt?.committed === true)
+        .map(receipt => receipt.operationIndex)
+        .filter(Number.isInteger);
+    const unattemptedIndexes = [];
+    for (let index = 1; index <= count; index += 1) {
+        if (!attempted.has(index)) unattemptedIndexes.push(index);
+    }
+    const base = rolledBack || atomic || committedIndexes.length === 0 ? 'original' : 'output';
+    return {
+        base,
+        committedIndexes,
+        failedIndexes,
+        unattemptedIndexes,
+        replayWholeBatch: base === 'original',
+        sameArgumentsSafe: false
+    };
+}