@ansonlai/docx-redline-js 0.5.4 → 0.6.0

package/node/docx-document.js

@@ -11,11 +11,42 @@ import { acceptTrackedChangesInOoxml, rejectTrackedChangesInOoxml, deleteComment
 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.
@@ -84,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
+                });
             }
         }
 
@@ -163,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 });
@@ -197,23 +233,26 @@ export class DocxDocument {
             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)
@@ -301,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>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ansonlai/docx-redline-js",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Host-independent OOXML reconciliation engine for .docx manipulation with track changes",
   "license": "MIT",
   "type": "module",
@@ -44,7 +44,13 @@
     "bin/",
     "orchestration/",
     "scripts/",
-    "docs/",
+    "!scripts/benchmark-agent-workflow.mjs",
+    "!scripts/lib/agent-performance-cases.mjs",
+    "docs/AGENT_FAST_START.md",
+    "docs/AGENT_KNOWLEDGE_BASE.md",
+    "docs/TESTING.md",
+    "docs/schemas/document-operations.schema.json",
+    "docs/validation-reports/2026-09-12-agent-protocol-rollout.md",
     "index.js",
     "index.d.ts",
     "dist/",
@@ -77,10 +83,11 @@
   "scripts": {
     "build": "node scripts/build.mjs",
     "check:types": "tsc -p tsconfig.types.json && node scripts/check-types.mjs",
-    "lint": "eslint index.js adapters core engine pipeline services orchestration scripts tests",
+    "lint": "eslint index.js adapters core engine pipeline services orchestration scripts examples tests",
     "test:coverage": "c8 --reporter=text --reporter=json --reporter=json-summary --reports-dir=coverage node scripts/run-tests.mjs",
     "coverage:gaps": "node scripts/report-coverage-gaps.mjs",
     "benchmark:session": "node scripts/benchmark-operation-session.mjs",
+    "benchmark:agent": "node scripts/benchmark-agent-workflow.mjs",
     "benchmark:targeting": "node scripts/benchmark-targeting-hot-paths.mjs",
     "benchmark:tests": "node scripts/benchmark-test-runner.mjs",
     "profile:routes": "node scripts/profile-route-selection.mjs",

package/scripts/generate-cross-author-slicing-fixtures.ps1

@@ -76,7 +76,7 @@ try {
 
     # -------------------------------------------------------------------------
     # Scenario 1: insert-interior
-    # Author A (Barry) inserts: "amended by this Agreement."
+    # Author A (John) inserts: "amended by this Agreement."
     # Author B (Anson) inserts "MASTER " before "Agreement"
     # -------------------------------------------------------------------------
     Write-Host "1. insert-interior"
@@ -85,8 +85,8 @@ try {
     $doc.Range(0, 0).Text = "Contract terms "
     
     # Author A insertion
-    $global:word.UserName = "Barry Plasteras"
-    $global:word.UserInitials = "BP"
+    $global:word.UserName = "John Doe"
+    $global:word.UserInitials = "JD"
     $doc.TrackRevisions = $true
     $endR = $doc.Range($doc.Content.End - 1, $doc.Content.End - 1)
     $endR.Text = "amended by this Agreement."
@@ -103,7 +103,7 @@ try {
 
     # -------------------------------------------------------------------------
     # Scenario 2: delete-interior
-    # Author A (Barry) inserts: "The Services will process the Input to generate outputs for Customer."
+    # Author A (John) inserts: "The Platform will process the Data to generate deliverables for Client."
     # Author B (Anson) deletes: "generate "
     # -------------------------------------------------------------------------
     Write-Host "2. delete-interior"
@@ -112,11 +112,11 @@ try {
     $doc.Range(0, 0).Text = "Background. "
     
     # Author A insertion
-    $global:word.UserName = "Barry Plasteras"
-    $global:word.UserInitials = "BP"
+    $global:word.UserName = "John Doe"
+    $global:word.UserInitials = "JD"
     $doc.TrackRevisions = $true
     $endR = $doc.Range($doc.Content.End - 1, $doc.Content.End - 1)
-    $endR.Text = "The Services will process the Input to generate outputs for Customer."
+    $endR.Text = "The Platform will process the Data to generate deliverables for Client."
     
     # Author B deletion inside Author A's insertion
     $global:word.UserName = "Anson Lai"
@@ -129,8 +129,8 @@ try {
 
     # -------------------------------------------------------------------------
     # Scenario 3: delete-boundary-start
-    # Author A (Barry) inserts: "Notwithstanding the foregoing, the NDA remains in effect."
-    # Author B (Anson) deletes: "Notwithstanding the foregoing, "
+    # Author A (John) inserts: "Notwithstanding anything to the contrary, the confidentiality terms remain in effect."
+    # Author B (Anson) deletes: "Notwithstanding anything to the contrary, "
     # -------------------------------------------------------------------------
     Write-Host "3. delete-boundary-start"
     $doc = $global:word.Documents.Add()
@@ -138,16 +138,16 @@ try {
     $doc.Range(0, 0).Text = "Section 1. "
     
     # Author A insertion
-    $global:word.UserName = "Barry Plasteras"
-    $global:word.UserInitials = "BP"
+    $global:word.UserName = "John Doe"
+    $global:word.UserInitials = "JD"
     $doc.TrackRevisions = $true
     $endR = $doc.Range($doc.Content.End - 1, $doc.Content.End - 1)
-    $endR.Text = "Notwithstanding the foregoing, the NDA remains in effect."
+    $endR.Text = "Notwithstanding anything to the contrary, the confidentiality terms remain in effect."
     
     # Author B deletion at start of insertion
     $global:word.UserName = "Anson Lai"
     $global:word.UserInitials = "AL"
-    $delWord = "Notwithstanding the foregoing, "
+    $delWord = "Notwithstanding anything to the contrary, "
     $foundPos = Find-RequiredText $doc $delWord "delete-boundary-start"
     $delRange = $doc.Range($foundPos, $foundPos + $delWord.Length)
     $delRange.Delete() | Out-Null
@@ -155,8 +155,8 @@ try {
 
     # -------------------------------------------------------------------------
     # Scenario 4: delete-boundary-end
-    # Author A (Barry) inserts: "subject to Section 2.8 and applicable law."
-    # Author B (Anson) deletes: " and applicable law."
+    # Author A (John) inserts: "subject to Section 4.2 and applicable standards."
+    # Author B (Anson) deletes: " and applicable standards."
     # -------------------------------------------------------------------------
     Write-Host "4. delete-boundary-end"
     $doc = $global:word.Documents.Add()
@@ -164,16 +164,16 @@ try {
     $doc.Range(0, 0).Text = "Compliance: "
     
     # Author A insertion
-    $global:word.UserName = "Barry Plasteras"
-    $global:word.UserInitials = "BP"
+    $global:word.UserName = "John Doe"
+    $global:word.UserInitials = "JD"
     $doc.TrackRevisions = $true
     $endR = $doc.Range($doc.Content.End - 1, $doc.Content.End - 1)
-    $endR.Text = "subject to Section 2.8 and applicable law."
+    $endR.Text = "subject to Section 4.2 and applicable standards."
     
     # Author B deletion at end of insertion
     $global:word.UserName = "Anson Lai"
     $global:word.UserInitials = "AL"
-    $delWord = " and applicable law."
+    $delWord = " and applicable standards."
     $foundPos = Find-RequiredText $doc $delWord "delete-boundary-end"
     $delRange = $doc.Range($foundPos, $foundPos + $delWord.Length)
     $delRange.Delete() | Out-Null
@@ -182,7 +182,7 @@ try {
     # -------------------------------------------------------------------------
     # Scenario 5: delete-straddle-baseline-insertion
     # Baseline: "Baseline start "
-    # Author A (Barry) inserts: "inserted finish."
+    # Author A (John) inserts: "inserted finish."
     # Author B (Anson) deletes: "start inserted" (straddling baseline and insertion)
     # -------------------------------------------------------------------------
     Write-Host "5. delete-straddle-baseline-insertion"
@@ -191,8 +191,8 @@ try {
     $doc.Range(0, 0).Text = "Baseline start "
     
     # Author A insertion
-    $global:word.UserName = "Barry Plasteras"
-    $global:word.UserInitials = "BP"
+    $global:word.UserName = "John Doe"
+    $global:word.UserInitials = "JD"
     $doc.TrackRevisions = $true
     $endR = $doc.Range($doc.Content.End - 1, $doc.Content.End - 1)
     $endR.Text = "inserted finish."
@@ -209,7 +209,7 @@ try {
     # -------------------------------------------------------------------------
     # Scenario 6: multi-author-stacked
     # Baseline: "Provision "
-    # Author A (Barry) inserts: "first draft of the proposal with initial metrics."
+    # Author A (John) inserts: "first draft of the proposal with initial metrics."
     # Author B (Anson) deletes: "of the proposal "
     # Author C (Chris) deletes: "initial " from the remaining text
     # -------------------------------------------------------------------------
@@ -219,8 +219,8 @@ try {
     $doc.Range(0, 0).Text = "Provision "
     
     # Author A insertion
-    $global:word.UserName = "Barry Plasteras"
-    $global:word.UserInitials = "BP"
+    $global:word.UserName = "John Doe"
+    $global:word.UserInitials = "JD"
     $doc.TrackRevisions = $true
     $endR = $doc.Range($doc.Content.End - 1, $doc.Content.End - 1)
     $endR.Text = "first draft of the proposal with initial metrics."