@ansonlai/docx-redline-js 0.6.1 → 0.7.0

package/node/cli-help.js

@@ -39,6 +39,14 @@ const APPLY_EXAMPLES = Object.freeze([
             modified: 'Revised clause.'
         }
     },
+    {
+        description: 'Localized tracked replacement in one strong accepted-view paragraph target.',
+        operation: {
+            type: 'redline',
+            target: { paragraphId: '1A2B3C4D' },
+            replacements: [{ find: 'thirty (30) days', replace: 'sixty (60) days' }]
+        }
+    },
     {
         description: 'Comment the complete target paragraph.',
         operation: {
@@ -116,7 +124,7 @@ export const CLI_COMMAND_HELP = Object.freeze({
     },
     apply: {
         summary: 'Apply canonical document operations and write a derived DOCX.',
-        usage: 'docx-redline apply <file.docx> --operations <file.json|-> [options]',
+        usage: 'docx-redline apply <file.docx> (--operations <file.json|->|<inline operation>) [options]',
         options: [
             HELP,
             option('operations', '--operations <file.json|->, --operations-file <file>', 'Read an operation array/envelope from a UTF-8 file or serializer-backed stdin.'),
@@ -124,7 +132,14 @@ export const CLI_COMMAND_HELP = Object.freeze({
             option('noClobber', '--no-clobber', 'Alias of --no-overwrite.'),
             option('expectedRevision', '--expected-revision <token|json>', 'Reject a stale package revision.'),
             option('target', '--target <text>', 'Inline one-operation target text.'),
+            option('targetId', '--target-id <paragraphId>', 'Strong inline target using a paragraphId from fresh inspection.'),
             option('modified', '--modified <text>', 'Complete desired accepted-view target content.'),
+            option('find', '--find <exact text>', 'Exact case-sensitive source span for one localized replacement.'),
+            option('replace', '--replace <text>', 'Replacement text for --find; an empty string deletes the span.'),
+            option('occurrence', '--occurrence <N>', 'Positive 1-based --find occurrence within the uniquely resolved target paragraph.'),
+            option('search', '--search <text>', 'Case-insensitive context anchor for speculative find/replace; all matching anchors are considered.'),
+            option('contextRange', '--context-range <START:END>', 'Signed inclusive paragraph offsets (-20..20) from each --search anchor; 1:3 means strictly the next three paragraphs.'),
+            option('around', '--around <N>', 'With --search, shorthand for symmetric --context-range -N:N (0-20).'),
             option('comment', '--comment <text>', 'Create an inline comment operation.'),
             option('textToComment', '--text-to-comment <text>', 'Anchor an inline comment to an exact subspan.'),
             option('targetRef', '--target-ref <N>', 'Disambiguate an inline target with a 1-based machine index.'),
@@ -138,6 +153,10 @@ export const CLI_COMMAND_HELP = Object.freeze({
         ],
         notes: [
             'modified is complete desired accepted-view content, not only inserted words.',
+            'Use either modified or find/replace. A strong accepted-view target is preferred when already known.',
+            'Without a strong target, find/replace may resolve globally or within --search plus a directional context range; it fails unless exactly one paragraph is eligible.',
+            '--occurrence disambiguates repeated text only within one uniquely selected paragraph, never between paragraphs.',
+            'Inline find/replace accepts one replacement; use operations JSON for multiple simultaneous replacements.',
             'Use a structured JSON file or serializer-backed stdin; never interpolate legal text through raw shell quoting.',
             'The source is never overwritten unless --in-place is explicit.',
             'The agent profile keeps progressive execution unless --atomic is explicit and does not change existing-revision policy.',
@@ -182,6 +201,14 @@ export function commandOptionKeys(command) {
     return (CLI_COMMAND_HELP[command]?.options || []).map(item => item.key);
 }
 
+const DOCS_BASE_URL = 'https://github.com/AnsonLai/docx-redline-js/blob/main/';
+export const CLI_DOCUMENTATION_URLS = Object.freeze([
+    `${DOCS_BASE_URL}AGENTS.md`,
+    `${DOCS_BASE_URL}docs/AGENT_FAST_START.md`,
+    `${DOCS_BASE_URL}docs/SKILL_AUTHORING.md`,
+    `${DOCS_BASE_URL}docs/schemas/document-operations.schema.json`
+]);
+
 export function buildCliHelp(command = null) {
     if (!command) {
         return {
@@ -190,7 +217,7 @@ export function buildCliHelp(command = null) {
             usage: 'docx-redline <command> [file.docx] [options]',
             commands: CLI_COMMANDS.map(name => ({ name, summary: CLI_COMMAND_HELP[name].summary })),
             notes: ['Run docx-redline <command> --help for flags, semantics, and bounded examples.'],
-            documentation: ['AGENTS.md', 'docs/AGENT_FAST_START.md', 'docs/SKILL_AUTHORING.md', 'docs/schemas/document-operations.schema.json']
+            documentation: [...CLI_DOCUMENTATION_URLS]
         };
     }
     const entry = CLI_COMMAND_HELP[command];
@@ -204,6 +231,6 @@ export function buildCliHelp(command = null) {
         options: entry.options.map(({ key: _key, ...publicOption }) => publicOption),
         notes: entry.notes,
         examples: entry.examples,
-        documentation: ['AGENTS.md', 'docs/AGENT_FAST_START.md', 'docs/SKILL_AUTHORING.md', 'docs/schemas/document-operations.schema.json']
+        documentation: [...CLI_DOCUMENTATION_URLS]
     };
 }

package/node/cli.js

@@ -10,7 +10,7 @@ import { normalizeErrorWithRecovery } from '../services/error-recovery.js';
 import { buildCliHelp, CLI_COMMANDS, commandOptionKeys } from './cli-help.js';
 
 const suffixes = { apply: 'redlined', accept: 'accepted', reject: 'rejected', 'delete-comments': 'comments-removed' };
-const CLI_CONTRACT_VERSION = 7;
+const CLI_CONTRACT_VERSION = 8;
 const DEFAULT_INSPECTION_LIMIT = 20;
 const INSPECTION_SOFT_BYTE_LIMIT = 48 * 1024;
 const CLI_CAPABILITIES = [
@@ -28,12 +28,25 @@ const CLI_CAPABILITIES = [
     'inspection-context-v1',
     'bounded-inspection-v1',
     'human-document-references-v1',
+    'localized-replacements-v1',
+    'speculative-search-apply-v1',
+    'localized-change-summary-v1',
     'deduplicated-cli-receipts',
     'compact-cli-json-v1'
 ];
 const commandOptions = Object.fromEntries(CLI_COMMANDS.map(command => [command, new Set(commandOptionKeys(command))]));
 
-function cliError(code, message, exitCode = 2, details) { return { status: 'error', error: normalizeErrorWithRecovery({ code, message, ...(details ? { details } : {}) }), exitCode }; }
+function cliError(code, message, exitCode = 2, details) {
+    return {
+        status: 'error',
+        error: normalizeErrorWithRecovery({
+            ...(details && typeof details === 'object' ? details : {}),
+            code,
+            message
+        }),
+        exitCode
+    };
+}
 const optionAliases = new Map([
     ['operationsFile', 'operations'],
     ['o', 'output'],
@@ -59,7 +72,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] === '-' || !argv[index + 1].startsWith('-') || /^-\d/.test(argv[index + 1]))) flags[key] = argv[++index];
+        else if (argv[index + 1] !== undefined && (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 };
@@ -150,31 +163,232 @@ async function readUtf8Stream(stream) {
     return Buffer.concat(chunks).toString('utf8');
 }
 
-async function readOperations(file, flags = {}, stdin = process.stdin) {
-    if (!file && flags?.target) {
-        let op;
-        if (flags.comment) {
-            op = {
-                type: 'comment',
-                target: String(flags.target),
-                commentContent: String(flags.comment),
-                ...(flags.textToComment ? { textToComment: String(flags.textToComment) } : {}),
-                ...(flags.targetRef ? { targetRef: positiveInteger(flags.targetRef) } : {}),
-                ...(flags.author ? { author: String(flags.author) } : {})
-            };
-        } else {
-            op = {
-                type: 'replace',
-                target: String(flags.target),
-                modified: flags.modified !== undefined ? String(flags.modified) : '',
-                ...(flags.targetRef ? { targetRef: positiveInteger(flags.targetRef) } : {}),
-                ...(flags.author ? { author: String(flags.author) } : {}),
-                ...(flags.existingRevisions ? { existingRevisions: String(flags.existingRevisions) } : {})
-            };
-        }
-        return { operations: [op], expectedRevision: null };
-    }
-    if (!file) throw Object.assign(new Error('Use --operations <file.json> or --target <text>.'), { code: 'OPERATIONS_REQUIRED' });
+function parseContextRange(value) {
+    const match = String(value).match(/^\s*(-?\d+)\s*:\s*(-?\d+)\s*$/);
+    if (!match) throw invalidFilter('--context-range must use START:END with signed integer offsets from -20 through 20.');
+    const start = Number(match[1]);
+    const end = Number(match[2]);
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < -20 || end > 20 || start > end) {
+        throw invalidFilter('--context-range requires START <= END and both offsets from -20 through 20.');
+    }
+    return { start, end, text: `${start}:${end}` };
+}
+
+function speculativeCandidate(paragraph) {
+    return {
+        excerpt: boundedText(paragraph.exactText, 240),
+        index: paragraph.index,
+        ref: paragraph.ref,
+        paragraphId: paragraph.paragraphId,
+        fingerprint: paragraph.fingerprint,
+        revisionView: 'accepted',
+        inTable: paragraph.inTable,
+        humanReference: paragraph.humanReference,
+        provision: paragraph.provision,
+        nearestHeading: paragraph.nearestHeading
+    };
+}
+
+function speculativeError(code, message, details = {}) {
+    return Object.assign(new Error(message), { code, ...details });
+}
+
+function resolveSpeculativePatchTarget(document, flags) {
+    if (!document) throw speculativeError('INVALID_OPERATION', 'Speculative localized replacement requires an open document.');
+    if (flags.contextRange !== undefined && flags.around !== undefined) {
+        throw invalidFilter('Use --context-range or --around, not both.');
+    }
+    const search = flags.search === undefined ? null : String(flags.search).trim();
+    if (flags.search !== undefined && (!search || flags.search === true)) {
+        throw invalidFilter('--search must be non-empty text.');
+    }
+    if ((flags.contextRange !== undefined || flags.around !== undefined) && !search) {
+        throw invalidFilter('--context-range and --around require --search.');
+    }
+    let range = { start: 0, end: 0, text: '0:0' };
+    if (flags.contextRange !== undefined) range = parseContextRange(flags.contextRange);
+    if (flags.around !== undefined) {
+        const text = String(flags.around).trim();
+        if (!/^\d+$/.test(text) || Number(text) > 20) {
+            throw invalidFilter('--around must be an integer from 0 through 20.');
+        }
+        const around = Number(text);
+        range = { start: -around, end: around, text: `${-around}:${around}` };
+    }
+
+    const inspected = document.inspect({ revisionView: 'accepted' });
+    const paragraphs = Array.isArray(inspected.paragraphs) ? inspected.paragraphs : [];
+    let anchors = [];
+    let eligible = paragraphs;
+    if (search) {
+        const folded = search.toLowerCase();
+        anchors = paragraphs.filter(paragraph => paragraph.exactText.toLowerCase().includes(folded));
+        if (anchors.length === 0) {
+            throw speculativeError('TARGET_NOT_FOUND', `No paragraph matched search query: "${search}".`, {
+                context: { search, range: range.text },
+                recovery: { action: 'reinspect', requiresReinspection: true, sameArgumentsSafe: false }
+            });
+        }
+        const eligibleIndexes = new Set();
+        for (const anchor of anchors) {
+            const anchorPosition = anchor.index - 1;
+            for (let offset = range.start; offset <= range.end; offset += 1) {
+                const position = anchorPosition + offset;
+                if (position >= 0 && position < paragraphs.length) eligibleIndexes.add(position);
+            }
+        }
+        eligible = [...eligibleIndexes].sort((a, b) => a - b).map(position => paragraphs[position]);
+    }
+
+    const find = String(flags.find);
+    const matches = eligible.filter(paragraph => paragraph.exactText.includes(find));
+    const context = {
+        ...(search ? { search, range: range.text, anchorMatchCount: anchors.length } : {})
+    };
+    if (matches.length === 0) {
+        throw speculativeError('PATCH_SOURCE_NOT_FOUND', search
+            ? `No paragraph in the contextual range contains the exact patch source: "${find}".`
+            : `No paragraph contains the exact patch source: "${find}".`, {
+            context,
+            ...(anchors.length ? { candidates: anchors.map(speculativeCandidate) } : {}),
+            recovery: { action: 'reinspect', requiresReinspection: true, sameArgumentsSafe: false }
+        });
+    }
+    if (matches.length > 1) {
+        throw speculativeError('AMBIGUOUS_TARGET', `The exact patch source matched ${matches.length} eligible paragraphs.`, {
+            context,
+            candidates: matches.map(speculativeCandidate),
+            recovery: { action: 'choose_candidate', requiresReinspection: false, sameArgumentsSafe: false }
+        });
+    }
+    const selected = matches[0];
+    return {
+        target: {
+            exactText: selected.exactText,
+            ...(selected.paragraphId ? { paragraphId: selected.paragraphId } : {}),
+            fingerprint: selected.fingerprint,
+            revisionView: 'accepted',
+            inTable: selected.inTable
+        },
+        context: {
+            ...context,
+            humanReference: selected.humanReference
+        }
+    };
+}
+
+async function readOperations(file, flags = {}, stdin = process.stdin, document = null) {
+    const hasInlineTarget = flags?.target !== undefined
+        || flags?.targetId !== undefined
+        || flags?.targetRef !== undefined;
+    const hasInlinePatch = flags?.find !== undefined
+        || flags?.replace !== undefined
+        || flags?.occurrence !== undefined;
+    const hasSpeculativeScope = flags?.search !== undefined
+        || flags?.contextRange !== undefined
+        || flags?.around !== undefined;
+    if (file && (hasInlinePatch || hasSpeculativeScope)) {
+        throw Object.assign(new Error('Use --operations or inline speculative find/replace options, not both.'), {
+            code: 'INVALID_OPERATION'
+        });
+    }
+    if (hasInlineTarget && hasSpeculativeScope) {
+        throw Object.assign(new Error('Use a strong inline target or --search/--context-range, not both.'), {
+            code: 'INVALID_OPERATION'
+        });
+    }
+    if (!file && (hasInlineTarget || hasInlinePatch || hasSpeculativeScope)) {
+        if (hasSpeculativeScope && !hasInlinePatch) {
+            throw Object.assign(new Error('--search, --context-range, and --around are only valid with inline --find/--replace.'), {
+                code: 'INVALID_OPERATION'
+            });
+        }
+        const targetRef = flags.targetRef === undefined ? null : positiveInteger(flags.targetRef);
+        if (flags.targetRef !== undefined && targetRef == null) {
+            throw Object.assign(new Error('--target-ref must be a positive 1-based integer.'), {
+                code: 'INVALID_OPERATION'
+            });
+        }
+        const targetId = flags.targetId === undefined ? null : String(flags.targetId).trim();
+        if (flags.targetId !== undefined && (!targetId || flags.targetId === true)) {
+            throw Object.assign(new Error('--target-id must be a non-empty paragraphId.'), {
+                code: 'INVALID_OPERATION'
+            });
+        }
+        const targetText = flags.target === undefined ? null : String(flags.target);
+        let target = targetId
+            ? { ...(targetText == null ? {} : { exactText: targetText }), paragraphId: targetId }
+            : targetText;
+        let speculativeContext = null;
+        let op;
+        if (flags.comment) {
+            if (hasInlinePatch) {
+                throw Object.assign(new Error('Inline comments cannot be combined with --find/--replace.'), {
+                    code: 'INVALID_OPERATION'
+                });
+            }
+            op = {
+                type: 'comment',
+                ...(target == null ? {} : { target }),
+                commentContent: String(flags.comment),
+                ...(flags.textToComment ? { textToComment: String(flags.textToComment) } : {}),
+                ...(targetRef == null ? {} : { targetRef }),
+                ...(flags.author ? { author: String(flags.author) } : {})
+            };
+        } else if (hasInlinePatch) {
+            if (flags.modified !== undefined) {
+                throw Object.assign(new Error('Use --modified or --find/--replace, not both.'), {
+                    code: 'INVALID_OPERATION'
+                });
+            }
+            if (
+                flags.find === undefined
+                || flags.find === true
+                || String(flags.find).length === 0
+                || flags.replace === undefined
+                || flags.replace === true
+            ) {
+                throw Object.assign(new Error('Inline localized replacement requires non-empty --find and string --replace values.'), {
+                    code: 'INVALID_OPERATION'
+                });
+            }
+            const occurrence = flags.occurrence === undefined ? null : positiveInteger(flags.occurrence);
+            if (flags.occurrence !== undefined && occurrence == null) {
+                throw Object.assign(new Error('--occurrence must be a positive 1-based integer.'), {
+                    code: 'INVALID_OPERATION'
+                });
+            }
+            if (!hasInlineTarget) {
+                const resolution = resolveSpeculativePatchTarget(document, flags);
+                target = resolution.target;
+                speculativeContext = resolution.context;
+            }
+            op = {
+                type: 'redline',
+                ...(target == null ? {} : { target }),
+                ...(targetRef == null ? {} : { targetRef }),
+                replacements: [{
+                    find: String(flags.find),
+                    replace: String(flags.replace),
+                    ...(occurrence == null ? {} : { occurrence })
+                }],
+                ...(speculativeContext ? { _speculativeContext: speculativeContext } : {}),
+                ...(flags.author ? { author: String(flags.author) } : {}),
+                ...(flags.existingRevisions ? { existingRevisions: String(flags.existingRevisions) } : {})
+            };
+        } else {
+            op = {
+                type: 'replace',
+                ...(target == null ? {} : { target }),
+                modified: flags.modified !== undefined ? String(flags.modified) : '',
+                ...(targetRef == null ? {} : { targetRef }),
+                ...(flags.author ? { author: String(flags.author) } : {}),
+                ...(flags.existingRevisions ? { existingRevisions: String(flags.existingRevisions) } : {})
+            };
+        }
+        return { operations: [op], expectedRevision: null };
+    }
+    if (!file) throw Object.assign(new Error('Use --operations <file.json> or an inline operation.'), { code: 'OPERATIONS_REQUIRED' });
     let parsed;
     try {
         const source = file === '-' ? await readUtf8Stream(stdin) : await readFile(file, 'utf8');
@@ -470,6 +684,11 @@ function compactMutationResult(value) {
     } = serialized;
     const results = Array.isArray(compact.results) ? compact.results.map(compactOperationResult) : [];
     const status = compact.status || 'ok';
+    const localizedChangesVerified = results.every(result => !result?.change || (
+        result.change.committed === true
+        && result.change.finalDisposition === 'applied'
+        && result.change.verification?.acceptedViewMatchesCompiledText === true
+    ));
     return {
         ...compact,
         ...(Array.isArray(compact.results) ? { results } : {}),
@@ -486,6 +705,7 @@ function compactMutationResult(value) {
             && status !== 'error'
             && status !== 'partial'
             && results.every(result => result?.status !== 'error')
+            && localizedChangesVerified
     };
 }
 
@@ -606,7 +826,7 @@ export async function executeCli(argv, io = process) {
             return { status: hasErrors ? 'error' : 'ok', command, input, valid: !hasErrors, issues };
         }
         const opsData = command === 'preflight' || command === 'apply'
-            ? await readOperations(flags.operations, flags, io.stdin || process.stdin)
+            ? await readOperations(flags.operations, flags, io.stdin || process.stdin, document)
             : null;
         const operations = opsData?.operations || null;
         let expectedRevision = opsData?.expectedRevision || null;
@@ -663,8 +883,13 @@ export async function executeCli(argv, io = process) {
                 generateRedlines,
                 ...(flags.existingRevisions ? { existingRevisions: flags.existingRevisions } : {}),
                 ...(expectedRevision ? { expectedRevision } : {})
-            });
-            const mutationResult = await writeMutation(command, input, flags, result);
+            });
+            const localizedVerificationFailed = (result.results || []).some(item => item?.change && (
+                item.change.committed !== true
+                || item.change.finalDisposition !== 'applied'
+                || item.change.verification?.acceptedViewMatchesCompiledText !== true
+            ));
+            const mutationResult = await writeMutation(command, input, flags, result);
             return compactMutationResult({
                 command,
                 input,
@@ -672,7 +897,7 @@ export async function executeCli(argv, io = process) {
                 ...(profile ? { executionProfile: profile, effectiveOptions } : {}),
                 ...(result.status === 'error'
                     ? { exitCode: 2 }
-                    : (result.status === 'partial' && requireComplete
+                    : ((result.status === 'partial' || localizedVerificationFailed) && requireComplete
                         ? { exitCode: 3 }
                         : {}))
             });
@@ -681,8 +906,8 @@ export async function executeCli(argv, io = process) {
         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 compactMutationResult({ command, input, ...serializable(await writeMutation(command, input, flags, result)) });
-    } catch (error) { return cliError(error.code || 'CLI_FAILED', error.message); }
-}
+    } catch (error) { return cliError(error.code || 'CLI_FAILED', error.message, 2, error); }
+}
 
 export async function runCli(argv = process.argv.slice(2), io = process) {
     configureLogger({}, { level: 'silent' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ansonlai/docx-redline-js",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Host-independent OOXML reconciliation engine for .docx manipulation with track changes",
   "license": "MIT",
   "type": "module",
@@ -46,15 +46,18 @@
     "scripts/",
     "!scripts/benchmark-agent-workflow.mjs",
     "!scripts/benchmark-agent-cli-discovery.mjs",
+    "!scripts/benchmark-localized-turn-reduction.mjs",
     "!scripts/lib/agent-performance-cases.mjs",
     "docs/AGENT_FAST_START.md",
     "docs/AGENT_KNOWLEDGE_BASE.md",
     "docs/SKILL_AUTHORING.md",
     "docs/TESTING.md",
+    "docs/releases/0.7.0.md",
     "docs/schemas/document-operations.schema.json",
     "docs/validation-reports/2026-09-12-agent-protocol-rollout.md",
     "docs/validation-reports/2026-09-12-agent-cli-discovery-baseline.md",
     "docs/validation-reports/2026-09-13-agent-cli-efficiency-rollout.md",
+    "docs/validation-reports/2026-09-14-localized-patching-rollout.md",
     "index.js",
     "index.d.ts",
     "dist/",
@@ -93,6 +96,7 @@
     "benchmark:session": "node scripts/benchmark-operation-session.mjs",
     "benchmark:agent": "node scripts/benchmark-agent-workflow.mjs",
     "benchmark:agent-cli": "node scripts/benchmark-agent-cli-discovery.mjs",
+    "benchmark:localized": "node scripts/benchmark-localized-turn-reduction.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/services/batch-operation-orchestrator.js

@@ -450,8 +450,9 @@ export async function applyOperationsToDocumentXml(documentXml, operations, auth
                 authorUsed: result.authorUsed,
                 ...(result.resolvedBy ? { resolvedBy: result.resolvedBy } : {}),
                 ...(result.resolvedTarget ? { resolvedTarget: result.resolvedTarget } : {}),
-                ...(result.resolvedAnchor ? { resolvedAnchor: result.resolvedAnchor } : {}),
-                ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
+                ...(result.resolvedAnchor ? { resolvedAnchor: result.resolvedAnchor } : {}),
+                ...(result.change ? { change: result.change } : {}),
+                ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
                 ...(result.error ? { error: result.error } : {}),
                 ...(result.receipt ? { receipt: result.receipt } : {})
             });
@@ -531,26 +532,34 @@ export async function applyOperationsToDocumentXml(documentXml, operations, auth
         }
     }
 
-    if (rolledBack) {
-        for (const r of results) {
-            if (r.receipt && r.receipt.attemptedDisposition === 'applied') {
-                r.receipt.finalDisposition = 'rolled_back';
-                r.receipt.committed = false;
-            }
-        }
+    if (rolledBack) {
+        for (const r of results) {
+            if (r.receipt && r.receipt.attemptedDisposition === 'applied') {
+                r.receipt.finalDisposition = 'rolled_back';
+                r.receipt.committed = false;
+            }
+            if (r.change) {
+                r.change.finalDisposition = 'rolled_back';
+                r.change.committed = false;
+            }
+        }
         for (const receipt of allReceipts) {
             if (receipt.attemptedDisposition === 'applied') {
                 receipt.finalDisposition = 'rolled_back';
                 receipt.committed = false;
             }
         }
-    } else {
-        for (const r of results) {
-            if (r.receipt && r.receipt.attemptedDisposition === 'applied') {
-                r.receipt.committed = true;
-                r.receipt.finalDisposition = 'applied';
-            }
-        }
+    } else {
+        for (const r of results) {
+            if (r.receipt && r.receipt.attemptedDisposition === 'applied') {
+                r.receipt.committed = true;
+                r.receipt.finalDisposition = 'applied';
+            }
+            if (r.change) {
+                r.change.finalDisposition = 'applied';
+                r.change.committed = true;
+            }
+        }
         for (const receipt of allReceipts) {
             if (receipt.attemptedDisposition === 'applied') {
                 receipt.committed = true;

package/services/document-inspection.js

@@ -309,6 +309,36 @@ export function inspectDocumentParts(parts, options = {}) {
         comments.set(id, definition);
     }
     const selected = selectInspectionParagraphs(paragraphs, options);
+    if (options.search && selected.selection && selected.selection.totalMatches === 0) {
+        const needle = String(options.search).toLowerCase();
+        const alternateView = revisionView === 'accepted' ? 'rejected' : 'accepted';
+        let rangeStart = 1;
+        let rangeEnd = paragraphNodes.length;
+        if (options.range) {
+            rangeStart = Number(options.range.start ?? options.range[0]);
+            rangeEnd = Number(options.range.end ?? options.range[1]);
+        }
+        let alternateMatches = 0;
+        for (let i = 0; i < paragraphNodes.length; i++) {
+            const index = i + 1;
+            if (options.range && (index < rangeStart || index > rangeEnd)) continue;
+            if (Array.isArray(options.indexes) && !options.indexes.includes(index)) continue;
+            const pNode = paragraphNodes[i];
+            if (options.table && !hasAncestor(pNode, 'tc')) continue;
+            if (options.body && hasAncestor(pNode, 'tc')) continue;
+            if (options.revised && revisionAuthors(pNode).length === 0) continue;
+            const altText = extractCanonicalParagraphText(pNode, { revisionView: alternateView });
+            if (options.skipEmpty && altText.length === 0) continue;
+            if (altText.toLowerCase().includes(needle)) {
+                alternateMatches++;
+            }
+        }
+        if (alternateMatches > 0) {
+            selected.selection.hint = revisionView === 'accepted'
+                ? `0 matches in accepted view, but ${alternateMatches} match${alternateMatches === 1 ? '' : 'es'} found in --view rejected. If searching for deleted text to restore, re-run with --view rejected.`
+                : `0 matches in rejected view, but ${alternateMatches} match${alternateMatches === 1 ? '' : 'es'} found in --view accepted. Re-run with --view accepted.`;
+        }
+    }
     paragraphs = selected.paragraphs;
     const allRevisionAuthors = [...new Set(paragraphs.flatMap(item => item.revisionAuthors))].sort();
     const coveredEntries = extractDocumentPartsEntries(parts);