@ansonlai/docx-redline-js 0.5.3 → 0.6.0

package/node/cli.js

@@ -6,28 +6,35 @@ import { validateDocxPackage } from '../services/standalone-docx-plumbing.js';
 import { validateRedlineOoxml } from '../core/redline-validation.js';
 import { configureLogger } from '../adapters/logger.js';
 import { isExistingRevisionsPolicy } from '../services/document-operation-contract.js';
+import { normalizeErrorWithRecovery } from '../services/error-recovery.js';
 
 const suffixes = { apply: 'redlined', accept: 'accepted', reject: 'rejected', 'delete-comments': 'comments-removed' };
-const CLI_CONTRACT_VERSION = 2;
+const CLI_CONTRACT_VERSION = 5;
 const CLI_CAPABILITIES = [
     'atomic-batch-results-on-package-failure',
     'baseline-aware-validation',
+    'compact-mutation-results',
     'cross-author-revision-slicing',
-    'document-scoped-list-revision-ids'
-];
+    'document-scoped-list-revision-ids',
+    'batch-start-source-binding',
+    'recovery-envelope-v1',
+    'require-complete-exit',
+    'operations-stdin',
+    'agent-profile-v1'
+];
 const commandOptions = {
     version: new Set(['help']),
     inspect: new Set(['help', 'search', 'revised', 'table', 'body', 'nonEmpty', 'index', 'indexes', 'range', 'view']),
     extract: new Set(['help', 'search', 'revised', 'table', 'body', 'nonEmpty', 'index', 'indexes', 'range', 'view']),
     preflight: new Set(['help', 'operations', 'author', 'strictTargets', 'target', 'modified', 'comment', 'textToComment', 'targetRef', 'existingRevisions']),
-    apply: new Set(['help', 'operations', 'author', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber', 'expectedRevision', 'target', 'modified', 'comment', 'textToComment', 'targetRef', 'existingRevisions', 'atomic', 'generateRedlines', 'noRedlines']),
+    apply: new Set(['help', 'operations', 'author', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber', 'expectedRevision', 'target', 'modified', 'comment', 'textToComment', 'targetRef', 'existingRevisions', 'atomic', 'generateRedlines', 'noRedlines', 'requireComplete', 'profile']),
     accept: new Set(['help', 'author', 'allAuthors', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber']),
     reject: new Set(['help', 'author', 'allAuthors', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber']),
     'delete-comments': new Set(['help', 'author', 'allAuthors', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber']),
     validate: new Set(['help', 'baseline'])
 };
 
-function cliError(code, message, exitCode = 2, details) { return { status: 'error', error: { code, message, ...(details ? { details } : {}) }, exitCode }; }
+function cliError(code, message, exitCode = 2, details) { return { status: 'error', error: normalizeErrorWithRecovery({ code, message, ...(details ? { details } : {}) }), exitCode }; }
 const optionAliases = new Map([
     ['operationsFile', 'operations'],
     ['o', 'output'],
@@ -38,7 +45,8 @@ const optionAliases = new Map([
     ['no-overwrite', 'noOverwrite'],
     ['no-clobber', 'noClobber'],
     ['no-redlines', 'noRedlines'],
-    ['generate-redlines', 'generateRedlines']
+    ['generate-redlines', 'generateRedlines'],
+    ['require-complete', 'requireComplete']
 ]);
 function parseArgs(argv) {
     const positionals = []; const flags = {};
@@ -50,7 +58,7 @@ function parseArgs(argv) {
         const normalizedKey = rawKey.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
         const key = optionAliases.get(normalizedKey) || normalizedKey;
         if (inline !== undefined) flags[key] = inline;
-        else if (argv[index + 1] && (!argv[index + 1].startsWith('-') || /^-\d/.test(argv[index + 1]))) flags[key] = argv[++index];
+        else if (argv[index + 1] && (argv[index + 1] === '-' || !argv[index + 1].startsWith('-') || /^-\d/.test(argv[index + 1]))) flags[key] = argv[++index];
         else flags[key] = true;
     }
     return { command: positionals[0], input: positionals[1], extraPositionals: positionals.slice(2), flags };
@@ -112,7 +120,16 @@ function inspectionOptions(flags) {
     }
     return options;
 }
-async function readOperations(file, flags = {}) {
+async function readUtf8Stream(stream) {
+    if (!stream || typeof stream[Symbol.asyncIterator] !== 'function') {
+        throw new Error('No readable stdin stream was provided.');
+    }
+    const chunks = [];
+    for await (const chunk of stream) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    return Buffer.concat(chunks).toString('utf8');
+}
+
+async function readOperations(file, flags = {}, stdin = process.stdin) {
     if (!file && flags?.target) {
         let op;
         if (flags.comment) {
@@ -137,7 +154,14 @@ async function readOperations(file, flags = {}) {
         return { operations: [op], expectedRevision: null };
     }
     if (!file) throw Object.assign(new Error('Use --operations <file.json> or --target <text>.'), { code: 'OPERATIONS_REQUIRED' });
-    let parsed; try { parsed = JSON.parse(await readFile(file, 'utf8')); } catch (error) { throw Object.assign(new Error(`Could not read operations JSON: ${error.message}`), { code: 'INVALID_OPERATIONS_FILE' }); }
+    let parsed;
+    try {
+        const source = file === '-' ? await readUtf8Stream(stdin) : await readFile(file, 'utf8');
+        parsed = JSON.parse(source);
+    } catch (error) {
+        const location = file === '-' ? ' from stdin' : '';
+        throw Object.assign(new Error(`Could not read operations JSON${location}: ${error.message}`), { code: 'INVALID_OPERATIONS_FILE' });
+    }
     const operations = Array.isArray(parsed) ? parsed : (parsed?.operations || parsed?.changes);
     if (!Array.isArray(operations)) throw Object.assign(new Error('Operations JSON must be an array or an object with an operations or changes array.'), { code: 'INVALID_OPERATIONS_FILE' });
     return { operations, expectedRevision: parsed?.expectedRevision || null };
@@ -162,10 +186,156 @@ 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',
+        'recoveryVersion', 'category', 'field', 'captureRef', 'operationIndexes',
+        'consumedByOperation', 'expectedScope', 'actualScope'
+    ];
+    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(candidate => {
+            if (!candidate || typeof candidate !== 'object') return candidate;
+            const excerpt = boundedText(candidate.excerpt ?? candidate.exactText ?? candidate.text ?? '', 240);
+            return { ...compactResolvedTarget(candidate), ...(excerpt ? { excerpt } : {}) };
+        });
+    }
+    for (const field of ['recovery', 'issueSummary', 'expectedRevision', 'currentRevision']) {
+        if (error[field] !== undefined) compact[field] = error[field];
+    }
+    if (error.context && typeof error.context === 'object') {
+        compact.context = {
+            ...error.context,
+            ...(error.context.currentTarget ? {
+                currentTarget: {
+                    ...compactResolvedTarget(error.context.currentTarget),
+                    excerpt: boundedText(
+                        error.context.currentTarget.excerpt
+                            ?? error.context.currentTarget.exactText
+                            ?? error.context.currentTarget.text
+                            ?? '',
+                        240
+                    )
+                }
+            } : {})
+        };
+    }
+    if (error.sourceTarget && typeof error.sourceTarget === 'object') {
+        compact.sourceTarget = {
+            ...compactResolvedTarget(error.sourceTarget),
+            excerpt: boundedText(error.sourceTarget.text ?? error.sourceTarget.exactText ?? '', 240)
+        };
+    }
+    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);
@@ -199,7 +369,7 @@ function subtractValidationIssues(issues, baselineIssues) {
     });
 }
 
-export async function executeCli(argv) {
+export async function executeCli(argv, io = process) {
     const { command, input: rawInput, extraPositionals, flags } = parseArgs(argv);
     if (command === 'help' || flags.help) return { status: 'ok', command: 'help', usage: 'docx-redline <version|inspect|extract|preflight|apply|accept|reject|delete-comments|validate> [file.docx] [options]' };
     if (!command) return cliError('COMMAND_REQUIRED', 'A command is required.');
@@ -221,6 +391,10 @@ export async function executeCli(argv) {
     if (flags.existingRevisions != null && !isExistingRevisionsPolicy(flags.existingRevisions)) {
         return cliError('INVALID_OPERATION', `Unsupported existing-revisions policy: "${String(flags.existingRevisions)}".`);
     }
+    const profile = flags.profile == null ? null : String(flags.profile);
+    if (profile && profile !== 'agent') {
+        return cliError('INVALID_PROFILE', `Unknown execution profile: "${profile}". Supported profiles: agent.`);
+    }
     let inspectOptions = null;
     if (command === 'inspect' || command === 'extract') {
         try { inspectOptions = inspectionOptions(flags); }
@@ -259,7 +433,9 @@ export async function executeCli(argv) {
             const hasErrors = issues.some(issue => issue.severity === 'error');
             return { status: hasErrors ? 'error' : 'ok', command, input, valid: !hasErrors, issues };
         }
-        const opsData = command === 'preflight' || command === 'apply' ? await readOperations(flags.operations, flags) : null;
+        const opsData = command === 'preflight' || command === 'apply'
+            ? await readOperations(flags.operations, flags, io.stdin || process.stdin)
+            : null;
         const operations = opsData?.operations || null;
         let expectedRevision = opsData?.expectedRevision || null;
         if (flags.expectedRevision) {
@@ -285,15 +461,31 @@ export async function executeCli(argv) {
             }),
             command,
             input
-        };
-        if (command === 'apply') {
-            const author = flags.author || process.env.DOCX_REDLINE_AUTHOR || 'AI Redliner';
-            const generateRedlines = flags.generateRedlines !== undefined
-                ? (flags.generateRedlines !== 'false' && flags.generateRedlines !== false)
-                : (!flags.noRedlines);
-            const result = await document.applyOperations(operations, {
-                author,
-                atomic: flags.atomic === true || flags.atomic === 'true',
+        };
+        if (command === 'apply') {
+            const agentProfile = profile === 'agent';
+            const author = flags.author || process.env.DOCX_REDLINE_AUTHOR || 'AI Redliner';
+            const generateRedlines = flags.generateRedlines !== undefined
+                ? (flags.generateRedlines !== 'false' && flags.generateRedlines !== false)
+                : (!flags.noRedlines);
+            const atomic = flags.atomic !== undefined
+                ? (flags.atomic === true || flags.atomic === 'true')
+                : agentProfile;
+            const requireComplete = flags.requireComplete !== undefined
+                ? (flags.requireComplete === true || flags.requireComplete === 'true')
+                : agentProfile;
+            const effectiveOptions = {
+                author,
+                atomic,
+                strictTargets: true,
+                validate: true,
+                generateRedlines,
+                existingRevisions: flags.existingRevisions || 'merge-same-author',
+                requireComplete
+            };
+            const result = await document.applyOperations(operations, {
+                author,
+                atomic,
                 validate: true,
                 strictTargets: true,
                 generateRedlines,
@@ -301,22 +493,29 @@ 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),
+                ...(profile ? { executionProfile: profile, effectiveOptions } : {}),
+                ...(result.status === 'error'
+                    ? { exitCode: 2 }
+                    : (result.status === 'partial' && requireComplete
+                        ? { exitCode: 3 }
+                        : {}))
+            });
         }
         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); }
 }
 
-export async function runCli(argv = process.argv.slice(2), io = process) {
-    configureLogger({}, { level: 'silent' });
-    const result = await executeCli(argv); io.stdout.write(`${JSON.stringify(serializable(result), null, 2)}\n`);
-    return result.status === 'error' ? (result.exitCode || 1) : 0;
-}
+export async function runCli(argv = process.argv.slice(2), io = process) {
+    configureLogger({}, { level: 'silent' });
+    const result = await executeCli(argv, io); io.stdout.write(`${JSON.stringify(serializable(result), null, 2)}\n`);
+    return Number.isInteger(result.exitCode) && result.exitCode !== 0
+        ? result.exitCode
+        : (result.status === 'error' ? 1 : 0);
+}

package/node/docx-document.js

@@ -5,16 +5,48 @@ import { inspectDocumentParts } from '../services/document-inspection.js';
 import { applyOperationsToDocumentXml, preflightOperations } from '../services/standalone-operation-runner.js';
 import { createDynamicNumberingIdState, mergeNumberingXmlBySchemaOrder } from '../services/numbering-helpers.js';
 import { ensureCommentsArtifactsInZip, ensureCommentsExtendedArtifactsInZip, ensureNumberingArtifactsInZip, validateDocxPackage } from '../services/standalone-docx-plumbing.js';
-import { validateRedlineOoxml } from '../core/redline-validation.js';
+import { validateRedlineOoxml } from '../core/redline-validation.js';
+import { subtractValidationIssueMultiset, validationErrors } from '../core/validation-delta.js';
 import { acceptTrackedChangesInOoxml, rejectTrackedChangesInOoxml, deleteCommentsByAuthorInOoxml } from '../services/revision-comment-management.js';
 import { createSerializer, parseOoxmlSafe } from '../adapters/xml-adapter.js';
 import { createHash } from 'node:crypto';
 import { MemoryZip, unzipDocx, zipDocx } from './zip-archive.js';
-import { computeRevisionTokenSync, validateRevisionToken, areRevisionTokensEqual } from '../services/revision-token.js';
+import { computeRevisionTokenSync, validateRevisionToken, areRevisionTokensEqual } from '../services/revision-token.js';
+import { createRetryPlan, normalizeErrorWithRecovery } from '../services/error-recovery.js';
 
 configureXmlProvider({ DOMParser, XMLSerializer });
-const text = (entries, path) => entries.get(path)?.toString('utf8') || null;
-const cloneEntries = entries => new Map([...entries].map(([name, data]) => [name, Buffer.from(data)]));
+const text = (entries, path) => entries.get(path)?.toString('utf8') || null;
+const cloneEntries = entries => new Map([...entries].map(([name, data]) => [name, Buffer.from(data)]));
+
+function rolledBackOperationPayload(operationResult, operationCount) {
+    const rollbackReceipt = receipt => {
+        if (!receipt || typeof receipt !== 'object') return receipt;
+        if (receipt.attemptedDisposition !== 'applied' && receipt.committed !== true) return { ...receipt };
+        return { ...receipt, committed: false, finalDisposition: 'rolled_back' };
+    };
+    const receipts = (operationResult?.receipts || []).map(rollbackReceipt);
+    const receiptByIndex = new Map(receipts.map(receipt => [receipt.operationIndex, receipt]));
+    const results = (operationResult?.results || []).map(result => ({
+        ...result,
+        ...(result.receipt ? {
+            receipt: receiptByIndex.get(result.index) || rollbackReceipt(result.receipt)
+        } : {})
+    }));
+    return {
+        results,
+        receipts,
+        executionOrder: operationResult?.executionOrder || [],
+        authorsUsed: [],
+        rolledBack: true,
+        retryPlan: createRetryPlan({
+            atomic: true,
+            rolledBack: true,
+            results,
+            receipts,
+            operationCount
+        })
+    };
+}
 
 /**
  * Computes a package-scoped revision token over all uncompressed entries in a DOCX archive.
@@ -83,60 +115,55 @@ export class DocxDocument {
     get revisionToken() { return this.getRevisionToken(); }
     preflight(operations, author = getDefaultAuthor(), options = {}) { return preflightOperations(text(this.entries, 'word/document.xml'), operations, author || getDefaultAuthor(), { ...options, _existingCommentDetails: existingCommentDetails(this.entries) }); }
     toBuffer() { return zipDocx(this.entries); }
-    async applyOperations(operations, options = {}) {
-        if (options?.expectedRevision) {
+    async applyOperations(operations, options = {}) {
+        const failedApply = error => {
+            const results = [];
+            const receipts = [];
+            return {
+                status: 'error',
+                hasChanges: false,
+                written: false,
+                rolledBack: true,
+                results,
+                receipts,
+                artifactsChanged: [],
+                error: normalizeErrorWithRecovery(error),
+                retryPlan: createRetryPlan({
+                    atomic: true,
+                    rolledBack: true,
+                    results,
+                    receipts,
+                    operationCount: Array.isArray(operations) ? operations.length : 0
+                }),
+                validation: { originalIssues: [], generatedIssues: [] },
+                buffer: Buffer.from(this.originalBuffer),
+                toBuffer: () => Buffer.from(this.originalBuffer)
+            };
+        };
+        if (options?.expectedRevision) {
             const tokenValidation = validateRevisionToken(options.expectedRevision);
             if (!tokenValidation.valid) {
-                return {
-                    status: 'error',
-                    hasChanges: false,
-                    written: false,
-                    rolledBack: true,
-                    results: [],
-                    artifactsChanged: [],
-                    error: {
-                        code: tokenValidation.error?.code || 'INVALID_REVISION_TOKEN',
-                        message: tokenValidation.error?.message || 'Invalid revision token.'
-                    },
-                    validation: { originalIssues: [], generatedIssues: [] },
-                    buffer: Buffer.from(this.originalBuffer),
-                    toBuffer: () => Buffer.from(this.originalBuffer)
-                };
+                return failedApply({
+                    code: tokenValidation.error?.code || 'INVALID_REVISION_TOKEN',
+                    message: tokenValidation.error?.message || 'Invalid revision token.'
+                });
             }
             if (options.expectedRevision.scope !== 'package') {
-                return {
-                    status: 'error',
-                    hasChanges: false,
-                    written: false,
-                    rolledBack: true,
-                    results: [],
-                    artifactsChanged: [],
-                    error: {
-                        code: 'REVISION_TOKEN_SCOPE_MISMATCH',
-                        message: `Revision token scope mismatch: expected 'package', got '${options.expectedRevision.scope}'.`
-                    },
-                    validation: { originalIssues: [], generatedIssues: [] },
-                    buffer: Buffer.from(this.originalBuffer),
-                    toBuffer: () => Buffer.from(this.originalBuffer)
-                };
+                return failedApply({
+                    code: 'REVISION_TOKEN_SCOPE_MISMATCH',
+                    message: `Revision token scope mismatch: expected 'package', got '${options.expectedRevision.scope}'.`,
+                    expectedScope: 'package',
+                    actualScope: options.expectedRevision.scope
+                });
             }
             const currentToken = computePackageRevisionToken(this.entries);
             if (!areRevisionTokensEqual(currentToken.value, options.expectedRevision.value)) {
-                return {
-                    status: 'error',
-                    hasChanges: false,
-                    written: false,
-                    rolledBack: true,
-                    results: [],
-                    artifactsChanged: [],
-                    error: {
-                        code: 'REVISION_MISMATCH',
-                        message: `Document revision mismatch: expected '${options.expectedRevision.value}', current is '${currentToken.value}'.`
-                    },
-                    validation: { originalIssues: [], generatedIssues: [] },
-                    buffer: Buffer.from(this.originalBuffer),
-                    toBuffer: () => Buffer.from(this.originalBuffer)
-                };
+                return failedApply({
+                    code: 'REVISION_MISMATCH',
+                    message: `Document revision mismatch: expected '${options.expectedRevision.value}', current is '${currentToken.value}'.`,
+                    expectedRevision: options.expectedRevision,
+                    currentRevision: currentToken
+                });
             }
         }
 
@@ -162,7 +189,17 @@ export class DocxDocument {
                 _existingCommentDetails: existingCommentDetails(working),
                 commentIdAllocator: nextCommentId(working)
             });
-            if (result.rolledBack || result.status === 'error') return { ...result, written: false, artifactsChanged: [], validation: { originalIssues, generatedIssues: [] }, buffer: this.originalBuffer, toBuffer: () => Buffer.from(this.originalBuffer) };
+            if (result.rolledBack || result.status === 'error') {
+                return {
+                    ...result,
+                    ...rolledBackOperationPayload(result, Array.isArray(operations) ? operations.length : 0),
+                    written: false,
+                    artifactsChanged: [],
+                    validation: { originalIssues, generatedIssues: [] },
+                    buffer: this.originalBuffer,
+                    toBuffer: () => Buffer.from(this.originalBuffer)
+                };
+            }
             if (!result.hasChanges) return { ...result, status: result.status || 'ok', written: false, artifactsChanged: [], validation: { originalIssues, generatedIssues: [] }, buffer: Buffer.from(this.originalBuffer), toBuffer: () => Buffer.from(this.originalBuffer) };
             working.set('word/document.xml', Buffer.from(result.documentXml));
             await ensureNumberingArtifactsInZip(zip, result.numberingXmlParts, { mergeNumberingXml: mergeNumberingXmlBySchemaOrder });
@@ -176,41 +213,46 @@ export class DocxDocument {
             await ensureCommentsExtendedArtifactsInZip(zip, commentsExtendedXmlForPackaging, {
                 replaceExisting: result.commentsExtendedXmlMode === 'replace' || (!result.commentsExtendedXml && !!existingCommentsExtendedXml)
             });
-            if (options.validate !== false) {
-                const generated = validateRedlineOoxml(result.documentXml);
-                const baselineErrors = new Set(baseline.issues.filter(i => i.severity === 'error').map(i => `${i.code}:${i.message}`));
-                const introduced = generated.issues.filter(i => i.severity === 'error' && !baselineErrors.has(`${i.code}:${i.message}`));
-                if (introduced.length) {
-                    const codes = [...new Set(introduced.map(issue => issue.code))].join(', ');
-                    throw Object.assign(
-                        new Error(`Applied operations introduced invalid revision markup (${codes}); these are generated-output issues, not pre-existing input issues.`),
-                        { issues: introduced }
-                    );
-                }
-                await validateDocxPackage(zip);
-            }
+            if (options.validate !== false) {
+                const generated = validateRedlineOoxml(result.documentXml);
+                const outputIssues = generated.issues.map(issue => ({ source: 'word/document.xml', ...issue }));
+                try { await validateDocxPackage(zip); }
+                catch (error) { outputIssues.push({ source: 'package', code: 'PACKAGE_VALIDATION', severity: 'error', message: error.message }); }
+                const introduced = subtractValidationIssueMultiset(outputIssues, originalIssues);
+                const introducedErrors = validationErrors(introduced);
+                if (introducedErrors.length) {
+                    const codes = [...new Set(introducedErrors.map(issue => issue.code))].join(', ');
+                    throw Object.assign(
+                        new Error(`Applied operations introduced invalid revision markup (${codes}); these are generated-output issues, not pre-existing input issues.`),
+                        { issues: introducedErrors }
+                    );
+                }
+            }
             this.entries = working;
             const output = this.toBuffer();
             this.originalBuffer = Buffer.from(output);
             const artifactsChanged = [...working].filter(([name, data]) => !originalEntries.has(name) || !data.equals(originalEntries.get(name))).map(([name]) => name);
             return { ...result, status: result.status || 'ok', written: true, artifactsChanged, validation: { originalIssues, generatedIssues: [] }, buffer: output, inspection: this.inspect(), toBuffer: () => Buffer.from(output) };
-        } catch (error) {
-            this.entries = originalEntries;
-            const generatedIssues = error.issues || [{ source: 'package', code: 'PACKAGE_OPERATION_FAILED', severity: 'error', message: error.message }];
-            return {
-                ...(operationResult ? {
-                    results: operationResult.results || [],
-                    receipts: operationResult.receipts || [],
-                    executionOrder: operationResult.executionOrder || [],
-                    authorsUsed: operationResult.authorsUsed || []
-                } : { results: [] }),
-                status: 'error',
-                hasChanges: false,
-                written: false,
-                rolledBack: true,
-                artifactsChanged: [],
-                error: { code: 'PACKAGE_OPERATION_FAILED', message: error.message },
-                validation: { originalIssues, generatedIssues },
+        } catch (error) {
+            this.entries = originalEntries;
+            const generatedIssues = error.issues || [{ source: 'package', code: 'PACKAGE_OPERATION_FAILED', severity: 'error', message: error.message }];
+            const rollbackPayload = rolledBackOperationPayload(
+                operationResult,
+                Array.isArray(operations) ? operations.length : 0
+            );
+            return {
+                ...rollbackPayload,
+                status: 'error',
+                hasChanges: false,
+                written: false,
+                artifactsChanged: [],
+                error: normalizeErrorWithRecovery({
+                    code: 'PACKAGE_OPERATION_FAILED',
+                    message: error.message,
+                    stage: 'package',
+                    issues: generatedIssues
+                }),
+                validation: { originalIssues, generatedIssues },
                 issues: generatedIssues,
                 buffer: Buffer.from(this.originalBuffer),
                 toBuffer: () => Buffer.from(this.originalBuffer)
@@ -298,5 +340,17 @@ export class DocxDocument {
     }
 }
 
-function packageFailure(source, code, message) { return { status: 'error', hasChanges: false, written: false, rolledBack: true, error: { code, message }, artifactsChanged: [], buffer: Buffer.from(source), toBuffer: () => Buffer.from(source) }; }
+function packageFailure(source, code, message) {
+    return {
+        status: 'error',
+        hasChanges: false,
+        written: false,
+        rolledBack: true,
+        error: normalizeErrorWithRecovery({ code, message }),
+        retryPlan: createRetryPlan({ atomic: true, rolledBack: true }),
+        artifactsChanged: [],
+        buffer: Buffer.from(source),
+        toBuffer: () => Buffer.from(source)
+    };
+}
 export function openDocx(input) { return new DocxDocument(input); }

package/node/index.d.ts

@@ -27,5 +27,9 @@ export class DocxDocument {
 }
 export function computePackageRevisionToken(input: unknown): RevisionToken;
 export function openDocx(input: Uint8Array): DocxDocument;
-export function executeCli(argv: string[]): Promise<Record<string, unknown>>;
-export function runCli(argv?: string[], io?: { stdout: { write(value: string): unknown } }): Promise<number>;
+export interface CliIo {
+  stdin?: AsyncIterable<string | Uint8Array>;
+  stdout: { write(value: string): unknown };
+}
+export function executeCli(argv: string[], io?: Partial<CliIo>): Promise<Record<string, unknown>>;
+export function runCli(argv?: string[], io?: CliIo): Promise<number>;