@ansonlai/docx-redline-js 0.7.0 → 0.7.1

package/docs/AGENT_FAST_START.md

@@ -21,8 +21,8 @@ It is a development sample, not a package API.
    docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
    ```
 
-   The source must occur in one eligible paragraph. For text after a heading, add `--search "Section 4.1" --context-range 1:3`.
-   `--around 3` is symmetric; use it only when either side is eligible.
+   The source must occur in one eligible paragraph. To narrow it, use a longer, fairly unique phrase: `--search "distinctive nearby heading or phrase" --context-range 1:3`.
+   Generic/repeated anchors can cause `AMBIGUOUS_TARGET` and waste a recovery turn. If `anchorMatchCount > 1`, confirm the returned location and excerpts. `--around 3` is symmetric.
 
 2. For semantic drafting such as “make this provision mutual,” extract enough
    context, then copy `exactText` with `paragraphId` or `fingerprint`:
@@ -31,7 +31,7 @@ It is a development sample, not a package API.
    docx-redline extract contract.docx --search "termination" --around 3
    ```
 
-   Search is case-insensitive; follow `selection.hint` and `selection.nextAfter`, and report `humanReference`. Apply once with a UTF-8 operations file or serializer-backed stdin:
+   Search is case-insensitive; follow `selection.hint` and `selection.nextAfter`, and report `humanReference`. With `--revised`, use `hasRevisions`, `revisionAuthors`, and `deleted` or `inserted` to interpret paragraphs whose active-view `exactText` is empty. Restore one rejected-view paragraph verbatim with `apply --restore --target-id ID`; add one `--find`/`--replace` pair for an exact correction. The shortcut never expands to adjacent paragraphs. Otherwise, apply once with a UTF-8 operations file or serializer-backed stdin:
 
    ```bash
    node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
@@ -46,8 +46,9 @@ The `agent` profile preserves progressive execution and the ordinary revision po
 - Strong inspected targets bind to the batch start; independent edits need no bottom-up sorting.
 - Consolidate writes to one source; use captures for created-content dependencies.
 - Require `completion: true`, `written: true`, a non-null `outputPath`, and no
-  per-operation error. For localized edits also require `change.committed: true`
-  and `change.verification.acceptedViewMatchesCompiledText: true`. The source is
+  per-operation error. For localized edits also require
+  `results[i].change.committed: true`, `finalDisposition: "applied"`, and
+  `verification.acceptedViewMatchesCompiledText: true`. The source is
   not overwritten unless `--in-place` is explicit.
 - On failure, follow `error.recovery.action`. Never retry unchanged arguments.
 - `retryPlan.base: "original"` means replay the batch; `"output"` means retain committed work and retry reported indexes.

package/docs/AGENT_KNOWLEDGE_BASE.md

@@ -484,9 +484,10 @@ The short route for a document-editing request is:
 
 1. For an exact mechanical change with known old and new literals, use localized
    `--find`/`--replace`. Omit the target for global fail-closed resolution, or
-   scope a visible heading with `--search` and a directional range such as
-   `--context-range 1:3`. Repeated anchor matches are unioned; one eligible patch
-   paragraph is still required. `--occurrence` selects only within that paragraph.
+   scope it with a longer, fairly unique nearby `--search` phrase and a
+   directional range such as `--context-range 1:3`. Generic or repeated anchors
+   widen the unioned scope and may fail with `AMBIGUOUS_TARGET`, costing another
+   turn. `--occurrence` selects only within one uniquely resolved paragraph.
 2. For semantic drafting, run one focused `extract`. Add `--around 3` when
    surrounding context on either side is needed, then copy `exactText` plus
    `paragraphId` or `fingerprint`.
@@ -499,8 +500,10 @@ The short route for a document-editing request is:
    text created elsewhere in the batch is scheduled automatically; use explicit
    captures/selectors for non-unique or advanced created-content dependencies.
 5. Walk every result and require `completion: true`, `written: true`, and no
-   per-operation error. For localized patches also require committed `change`
-   evidence and positive accepted-view verification.
+   per-operation error. For localized patches also require
+   `results[i].change.committed: true`, `finalDisposition: "applied"`, and
+   positive accepted-view verification. If `anchorMatchCount > 1`, confirm the
+   returned location and excerpts because the anchor was repeated.
 6. Run a focused `extract` on changed clauses only when placement or list/table
    structure needs confirmation.
 
@@ -512,8 +515,8 @@ below and make one cause-specific correction.
 # 1. Globally unique mechanical edit in one call
 docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
 
-# 2. Mechanical edit strictly within three paragraphs after a visible heading
-docx-redline apply contract.docx --search "Section 4.1" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+# 2. Directional edit using a longer phrase with a higher chance of uniqueness
+docx-redline apply contract.docx --search "distinctive nearby heading or phrase" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
 
 # 3. Focused contextual discovery for semantic drafting
 docx-redline extract contract.docx --search "termination" --around 3
@@ -590,6 +593,13 @@ Paragraph indexes are 1-based. Inspection filters are `--index 12`,
 case-insensitive. When a search returns 0 matches in the active view but matches
 exist in the alternate view (such as searching for a deleted clause to restore),
 `selection.hint` provides immediate guidance to re-run with `--view rejected`.
+Compact `extract --revised` results retain `hasRevisions`, `revisionAuthors`,
+and `deleted`/`inserted` cues, so an empty `exactText` is identifiable as content
+hidden by the selected revision view rather than a failed filter.
+For one strongly identified rejected-view paragraph, `apply --restore
+--target-id ID` restores the rejected text verbatim. One exact
+`--find`/`--replace` pair may adjust it without restating the paragraph. The
+shortcut refuses ranges, captures, weak targets, and inferred adjacent content.
 Add `--around N` (`--context N` or `-C N`) to a search;
 context records are labeled separately and do not consume the direct-hit
 `--limit`. Continue a bounded result with `--after <paragraph-index>`. Ordinary

package/docs/SKILL_AUTHORING.md

@@ -101,12 +101,13 @@ the first executable example should use the one-turn fast path:
 docx-redline apply input.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
 ```
 
-If the literal is not globally unique, scope it with a meaningful visible
-anchor. A heading followed by a multi-paragraph provision should use a
-directional window such as `--search "Section 4.1" --context-range 1:3`;
-`--around 3` is symmetric and should be used only when either side is eligible.
-Require the returned localized `change` evidence, including `committed: true`
-and `verification.acceptedViewMatchesCompiledText: true`.
+If the literal is not globally unique, use a longer, fairly unique nearby phrase
+as `--search` context. Generic or repeated anchors widen the unioned scope and
+may cause `AMBIGUOUS_TARGET`, wasting a recovery turn. Use a directional window
+such as `1:3`; use symmetric `--around 3` only when either side is eligible. On
+success, `anchorMatchCount > 1` signals a repeated anchor: confirm the returned
+location and excerpts. Require `results[i].change` with `committed: true`,
+`finalDisposition: "applied"`, and positive accepted-view verification.
 
 Semantic requests such as “make this provision mutual” still begin with focused
 contextual extraction because the agent must identify and draft the complete

package/docs/releases/0.7.0.md

@@ -70,11 +70,12 @@ Globally unique literal edits no longer require preliminary extraction:
 docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
 ```
 
-For a heading followed by a multi-paragraph provision, use a visible text anchor
-and directional paragraph scope:
+When global matching is too broad, use a longer, fairly unique nearby phrase and
+a directional paragraph scope. Longer anchors generally have a higher chance of
+being unique:
 
 ```bash
-docx-redline apply contract.docx --search "Section 4.1" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+docx-redline apply contract.docx --search "distinctive nearby heading or phrase" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
 ```
 
 `1:3` means strictly the next three physical paragraphs, excluding the heading
@@ -84,10 +85,13 @@ document boundaries. `--around 3` is shorthand for `-3:3`.
 
 Every matching search anchor contributes a window. The library unions and
 deduplicates those windows, then requires exactly one eligible paragraph to
-contain the exact `find` literal. Thus a visible section number may appear both
-as a heading and in cross-references without the anchor itself deciding what is
-edited. `--occurrence` may disambiguate only inside the uniquely selected
-paragraph; it never chooses between paragraphs.
+contain the exact `find` literal. A generic or repeated anchor can therefore
+widen the scope until multiple paragraphs contain `find`, producing a safe
+`AMBIGUOUS_TARGET` failure and an extra recovery turn. On success,
+`results[i].change.context.anchorMatchCount > 1` means the anchor was repeated;
+confirm the returned location and excerpts. It is a specificity signal, not an
+automatic failure. `--occurrence` may disambiguate only inside the uniquely
+selected paragraph; it never chooses between paragraphs.
 
 ### 3. Refusal Without Output Damage
 
@@ -106,43 +110,59 @@ overwritten. The source remains immutable unless `--in-place` is explicit.
 
 ### 4. Explicit Post-Mutation Change Evidence
 
-Successful localized operations return a compact evidence object:
+Successful localized operations return a compact evidence object inside the
+corresponding operation result:
 
 ```json
 {
-  "change": {
-    "kind": "localized_replacement",
-    "committed": true,
-    "finalDisposition": "applied",
-    "target": {
-      "paragraphId": "1A2B3C4D",
-      "humanReference": "Section 4.1 — Termination"
-    },
-    "context": {
-      "search": "Section 4.1",
-      "range": "1:3",
-      "anchorMatchCount": 2
-    },
-    "replacements": [
-      {
-        "find": "thirty (30) days",
-        "replace": "sixty (60) days",
-        "beforeExcerpt": "...thirty (30) days...",
-        "afterExcerpt": "...sixty (60) days..."
+  "status": "ok",
+  "written": true,
+  "completion": true,
+  "results": [
+    {
+      "index": 1,
+      "status": "applied",
+      "change": {
+        "kind": "localized_replacement",
+        "committed": true,
+        "finalDisposition": "applied",
+        "target": {
+          "paragraphId": "1A2B3C4D",
+          "humanReference": "Relevant heading or text lead"
+        },
+        "context": {
+          "search": "distinctive nearby heading or phrase",
+          "range": "1:3",
+          "anchorMatchCount": 1
+        },
+        "replacements": [
+          {
+            "find": "thirty (30) days",
+            "replace": "sixty (60) days",
+            "beforeExcerpt": "...thirty (30) days...",
+            "afterExcerpt": "...sixty (60) days..."
+          }
+        ],
+        "verification": {
+          "acceptedViewMatchesCompiledText": true
+        }
       }
-    ],
-    "verification": {
-      "acceptedViewMatchesCompiledText": true
     }
-  }
+  ]
 }
 ```
 
-Evidence is derived from the resolved source and actual post-mutation accepted
-view rather than simply echoing the request. Excerpts are deterministically
-bounded to 120 characters. Agent completion additionally requires committed,
-applied evidence and positive accepted-view verification. Atomic rollback marks
-previously attempted evidence `committed: false` and `rolled_back`.
+The excerpts come from the resolved batch-start source and compiled desired
+text; the complete actual post-mutation accepted view is then compared with that
+desired text. Positive verification therefore authenticates the reported after
+state without returning the full paragraph. Excerpts are deterministically
+bounded to 120 characters.
+
+Report success only when `completion: true`, `written: true`, the output path is
+non-null, every operation succeeded, and every localized result has
+`change.committed: true`, `change.finalDisposition: "applied"`, and
+`change.verification.acceptedViewMatchesCompiledText: true`. Atomic rollback
+marks previously attempted evidence `committed: false` and `rolled_back`.
 
 ### 5. Agent Guidance and Development Wrapper
 

package/docs/schemas/document-operations.schema.json

@@ -116,7 +116,7 @@
           "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["modified"], "properties": { "type": { "enum": ["redline", "replace", "format", "list-change", "table-reconciliation", "insert"] }, "modified": { "type": "string" }, "structuredContent": { "type": "boolean" }, "targetEnd": { "$ref": "#/$defs/target" }, "targetEndRef": { "type": ["integer", "string", "null"] }, "anchor": { "$ref": "#/$defs/rejectedTextInsertionAnchor" } } } ]
         },
         {
-          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["modified"], "properties": { "type": { "const": "restore" }, "modified": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } } ] }, "targetEnd": { "$ref": "#/$defs/target" }, "targetEndRef": { "type": ["integer", "string", "null"] } } } ]
+          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "properties": { "type": { "const": "restore" }, "modified": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } } ] }, "replacements": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/localizedReplacement" } }, "targetEnd": { "$ref": "#/$defs/target" }, "targetEndRef": { "type": ["integer", "string", "null"] } }, "oneOf": [ { "required": ["modified"], "not": { "required": ["replacements"] } }, { "required": ["replacements"], "not": { "required": ["modified"] } }, { "not": { "anyOf": [ { "required": ["modified"] }, { "required": ["replacements"] } ] } } ] } ]
         },
         {
           "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "properties": { "type": { "const": "delete" }, "modified": { "const": "" } } } ]

package/node/cli-help.js

@@ -12,7 +12,7 @@ const COMPACT = option('compact', '--compact', 'Emit one-line JSON to reduce pro
 const INSPECTION_OPTIONS = Object.freeze([
     HELP,
     option('search', '--search <text>', 'Case-insensitive substring search.'),
-    option('revised', '--revised', 'Select paragraphs containing tracked revisions.'),
+    option('revised', '--revised', 'Select paragraphs containing tracked revisions; extract identifies authors and fully hidden deleted/inserted paragraphs.'),
     option('table', '--table', 'Select paragraphs inside tables.'),
     option('body', '--body', 'Select paragraphs outside tables.'),
     option('nonEmpty', '--non-empty', 'Exclude empty paragraphs; this is not a narrow document scope.'),
@@ -56,15 +56,14 @@ const APPLY_EXAMPLES = Object.freeze([
         }
     },
     {
-        description: 'Counterpropose a wholly foreign-deleted paragraph found through --view rejected.',
+        description: 'Restore one wholly foreign-deleted paragraph verbatim from a strong rejected-view target.',
         operation: {
             type: 'restore',
             target: {
                 exactText: 'Deleted source paragraph.',
                 paragraphId: '3A2B3C4D',
                 revisionView: 'rejected'
-            },
-            modified: 'Restored and revised paragraph.'
+            }
         }
     }
 ]);
@@ -133,11 +132,12 @@ export const CLI_COMMAND_HELP = Object.freeze({
             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('restore', '--restore', 'Restore one rejected-view paragraph identified by --target-id; omit --modified for verbatim restoration.'),
             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('search', '--search <text>', 'Case-insensitive context anchor for speculative find/replace; prefer a longer, fairly unique phrase because all matches contribute scope.'),
             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.'),
@@ -154,7 +154,9 @@ 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.',
+            '--restore requires --target-id from rejected-view extraction; omit modified for verbatim restore or use one inline find/replace.',
             '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.',
+            'Generic or repeated search anchors widen the unioned scope and may cause AMBIGUOUS_TARGET; on success, anchorMatchCount greater than 1 signals that the returned location and excerpts should be confirmed.',
             '--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.',

package/node/cli.js

@@ -31,6 +31,7 @@ const CLI_CAPABILITIES = [
     'localized-replacements-v1',
     'speculative-search-apply-v1',
     'localized-change-summary-v1',
+    'restore-shortcuts-v1',
     'deduplicated-cli-receipts',
     'compact-cli-json-v1'
 ];
@@ -278,6 +279,7 @@ function resolveSpeculativePatchTarget(document, flags) {
 }
 
 async function readOperations(file, flags = {}, stdin = process.stdin, document = null) {
+    const inlineRestore = flags?.restore !== undefined;
     const hasInlineTarget = flags?.target !== undefined
         || flags?.targetId !== undefined
         || flags?.targetRef !== undefined;
@@ -287,8 +289,8 @@ async function readOperations(file, flags = {}, stdin = process.stdin, document
     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.'), {
+    if (file && (hasInlinePatch || hasSpeculativeScope || inlineRestore)) {
+        throw Object.assign(new Error('Use --operations or inline restore/find/replace options, not both.'), {
             code: 'INVALID_OPERATION'
         });
     }
@@ -297,7 +299,12 @@ async function readOperations(file, flags = {}, stdin = process.stdin, document
             code: 'INVALID_OPERATION'
         });
     }
-    if (!file && (hasInlineTarget || hasInlinePatch || hasSpeculativeScope)) {
+    if (!file && (hasInlineTarget || hasInlinePatch || hasSpeculativeScope || inlineRestore)) {
+        if (inlineRestore && flags.restore !== true) {
+            throw Object.assign(new Error('--restore is a boolean flag and does not take a value.'), {
+                code: 'INVALID_OPERATION'
+            });
+        }
         if (hasSpeculativeScope && !hasInlinePatch) {
             throw Object.assign(new Error('--search, --context-range, and --around are only valid with inline --find/--replace.'), {
                 code: 'INVALID_OPERATION'
@@ -319,9 +326,22 @@ async function readOperations(file, flags = {}, stdin = process.stdin, document
         let target = targetId
             ? { ...(targetText == null ? {} : { exactText: targetText }), paragraphId: targetId }
             : targetText;
+        if (inlineRestore) {
+            if (!targetId) {
+                throw Object.assign(new Error('Inline --restore requires --target-id from rejected-view extraction.'), {
+                    code: 'INVALID_OPERATION'
+                });
+            }
+            target = { ...target, revisionView: 'rejected' };
+        }
         let speculativeContext = null;
         let op;
         if (flags.comment) {
+            if (inlineRestore) {
+                throw Object.assign(new Error('Use --restore or --comment, not both.'), {
+                    code: 'INVALID_OPERATION'
+                });
+            }
             if (hasInlinePatch) {
                 throw Object.assign(new Error('Inline comments cannot be combined with --find/--replace.'), {
                     code: 'INVALID_OPERATION'
@@ -364,7 +384,7 @@ async function readOperations(file, flags = {}, stdin = process.stdin, document
                 speculativeContext = resolution.context;
             }
             op = {
-                type: 'redline',
+                type: inlineRestore ? 'restore' : 'redline',
                 ...(target == null ? {} : { target }),
                 ...(targetRef == null ? {} : { targetRef }),
                 replacements: [{
@@ -376,6 +396,14 @@ async function readOperations(file, flags = {}, stdin = process.stdin, document
                 ...(flags.author ? { author: String(flags.author) } : {}),
                 ...(flags.existingRevisions ? { existingRevisions: String(flags.existingRevisions) } : {})
             };
+        } else if (inlineRestore) {
+            op = {
+                type: 'restore',
+                target,
+                ...(flags.modified === undefined ? {} : { modified: String(flags.modified) }),
+                ...(flags.author ? { author: String(flags.author) } : {}),
+                ...(flags.existingRevisions ? { existingRevisions: String(flags.existingRevisions) } : {})
+            };
         } else {
             op = {
                 type: 'replace',
@@ -430,8 +458,14 @@ function compactExtractParagraph(paragraph) {
     const {
         humanReference, provision, nearestHeading, index, ref, paragraphId,
         fingerprint, revisionView, exactText, inTable, list, selectionRole,
-        contextFor
+        contextFor, hasRevisions, revisionAuthors, segments
     } = paragraph;
+    const hiddenRevisionContent = exactText.length === 0 && Array.isArray(segments)
+        && segments.some(segment => segment.text.length > 0 && (
+            revisionView === 'rejected'
+                ? segment.acceptedStart !== null
+                : segment.rejectedStart !== null
+        ));
     return {
         humanReference,
         provision,
@@ -444,6 +478,12 @@ function compactExtractParagraph(paragraph) {
         exactText,
         inTable,
         list,
+        ...(hasRevisions ? {
+            hasRevisions: true,
+            revisionAuthors,
+            ...(hiddenRevisionContent && revisionView === 'accepted' ? { deleted: true } : {}),
+            ...(hiddenRevisionContent && revisionView === 'rejected' ? { inserted: true } : {})
+        } : {}),
         ...(selectionRole ? { selectionRole } : {}),
         ...(Array.isArray(contextFor) ? { contextFor } : {})
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ansonlai/docx-redline-js",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Host-independent OOXML reconciliation engine for .docx manipulation with track changes",
   "license": "MIT",
   "type": "module",

package/services/document-inspection.js

@@ -324,9 +324,8 @@ export function inspectDocumentParts(parts, options = {}) {
             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;
+            if (options.inTable != null && hasAncestor(pNode, 'tc') !== !!options.inTable) continue;
+            if (options.revisedOnly && revisionAuthors(pNode).length === 0) continue;
             const altText = extractCanonicalParagraphText(pNode, { revisionView: alternateView });
             if (options.skipEmpty && altText.length === 0) continue;
             if (altText.toLowerCase().includes(needle)) {

package/services/document-operation-applier.js

@@ -160,7 +160,10 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
         };
     }
 
-    if (Array.isArray(operation.replacements)) {
+    if (
+        Array.isArray(operation.replacements)
+        || (operation.operationKind === 'restore' && op?.modified === undefined)
+    ) {
         const compilation = compileOperationBatch(session.document, [op], {
             strictTargets: options.strictTargets !== false,
             onInfo: options.onInfo,
@@ -415,7 +418,14 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
             }
             if (operation._localizedReplacementCompilation) {
                 let outputText = null;
-                if (operation._compiledSourceId && session.sourceTargetRegistry) {
+                if (operation.operationKind === 'restore') {
+                    const restoredParagraph = operationOptions._mutationLiveNodes.find(node => node?.localName === 'p');
+                    if (restoredParagraph) {
+                        outputText = extractCanonicalParagraphText(restoredParagraph, {
+                            revisionView: 'accepted'
+                        });
+                    }
+                } else if (operation._compiledSourceId && session.sourceTargetRegistry) {
                     const bound = session.sourceTargetRegistry.resolve(
                         operation._compiledSourceId,
                         session.document

package/services/document-operation-contract.js

@@ -307,19 +307,66 @@ export function validateDocumentOperation(operation) {
     }
 
     if (normalized.operationKind === 'restore') {
+        const hasModified = operation.modified !== undefined;
+        const hasReplacements = operation.replacements !== undefined;
         const validSingle = nonEmptyString(normalized.modified);
         const validRange = Array.isArray(normalized.modified)
             && normalized.modified.length > 0
             && normalized.modified.every(nonEmptyString);
-        if (!validSingle && !validRange) {
+        if (hasModified && hasReplacements) {
             return {
                 valid: false,
                 error: {
                     code: 'INVALID_OPERATION',
-                    message: 'Restore operations require a non-empty string or non-empty string array in "modified".'
+                    message: 'Restore operations accept modified or replacements, not both.'
                 }
             };
         }
+        if (hasModified && !validSingle && !validRange) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'Restore modified must be a non-empty string or non-empty string array.'
+                }
+            };
+        }
+        if (!hasModified) {
+            if (
+                target.revisionView !== 'rejected'
+                || (!target.paragraphId && !target.fingerprint)
+                || target.captureRef
+                || target.occurrence != null
+                || normalized.captureKey
+                || normalized.targetEndDescriptor
+                || normalized.targetEndRef != null
+                || /\r|\n/.test(target.text || '')
+            ) {
+                return {
+                    valid: false,
+                    error: {
+                        code: 'INVALID_OPERATION',
+                        message: 'Verbatim and localized restore require one strong batch-start rejected-view paragraph target without captures, target occurrence, or a target range.'
+                    }
+                };
+            }
+        }
+        if (hasReplacements) {
+            const replacementValidation = validateExactReplacementRequests(normalized.replacements);
+            if (!replacementValidation.ok) {
+                return { valid: false, error: replacementValidation.error };
+            }
+            if (replacementValidation.replacements.some(replacement => /\r|\n/.test(replacement.replace))) {
+                return {
+                    valid: false,
+                    error: {
+                        code: 'INVALID_OPERATION',
+                        message: 'Localized restore cannot insert paragraph breaks.'
+                    }
+                };
+            }
+            normalized.replacements = replacementValidation.replacements;
+        }
         if (normalized.generateRedlines === false) {
             return {
                 valid: false,

package/services/document-operation-mutations.js

@@ -223,7 +223,37 @@ function describeTargetTextMatch(actualText, requestedText) {
         requestedExcerpt: escapeInvisibleText(requested)
     };
 }
-
+
+function resolvedTargetDiagnostics(xmlDoc, paragraph, metadata, targetText, options) {
+    const revisionView = options?.targetDescriptor?.revisionView === 'rejected'
+        ? 'rejected'
+        : 'accepted';
+    const viewMetadata = metadata?.revisionView === revisionView ? metadata : null;
+    const index = viewMetadata?.index ?? getDocumentParagraphNodes(xmlDoc).indexOf(paragraph) + 1;
+    const paragraphId = viewMetadata?.paragraphId ?? getParagraphId(paragraph);
+    const inTable = viewMetadata?.inTable ?? !!findContainingWordElement(paragraph, 'tbl');
+    const text = viewMetadata?.text ?? extractCanonicalParagraphText(paragraph, { revisionView });
+    const fingerprint = viewMetadata?.fingerprint ?? createParagraphFingerprint(paragraph, {
+        text,
+        index,
+        paragraphId,
+        inTable,
+        revisionView
+    });
+    return {
+        index,
+        paragraphId,
+        text,
+        fingerprint,
+        revisionView,
+        inTable,
+        targetTextMatch: describeTargetTextMatch(
+            text,
+            options?.targetDescriptor?.text ?? options?.targetDescriptor?.exactText ?? targetText
+        )
+    };
+}
+
 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 : () => { };
@@ -239,17 +269,7 @@ function resolveTargetParagraph(xmlDoc, targetText, targetRef, opType, runtimeCo
             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
-                    )
-                }
+                resolvedTarget: resolvedTargetDiagnostics(xmlDoc, paragraph, metadata, targetText, options)
             });
         }
         return resolved;
@@ -263,17 +283,7 @@ function resolveTargetParagraph(xmlDoc, targetText, targetRef, opType, runtimeCo
                 const metadata = paragraphMetadataIndex?.byParagraph?.get(paragraph) || null;
                 Object.assign(options._resolutionCapture, {
                     resolvedBy: resolved.resolvedBy,
-                    resolvedTarget: {
-                        index: metadata?.index ?? Array.from(xmlDoc.getElementsByTagNameNS(NS_W, 'p')).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
-                        )
-                    }
+                    resolvedTarget: resolvedTargetDiagnostics(xmlDoc, paragraph, metadata, targetText, options)
                 });
             }
             return resolved;
@@ -301,19 +311,9 @@ function resolveTargetParagraph(xmlDoc, targetText, targetRef, opType, runtimeCo
     if (options?._resolutionCapture && resolved?.paragraph) {
         const paragraph = resolved.paragraph;
         const metadata = paragraphMetadataIndex?.byParagraph?.get(paragraph) || null;
-        Object.assign(options._resolutionCapture, {
-            resolvedBy: resolved.resolvedBy,
-            resolvedTarget: {
-                index: metadata?.index ?? Array.from(xmlDoc.getElementsByTagNameNS(NS_W, 'p')).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
-                )
-            }
+        Object.assign(options._resolutionCapture, {
+            resolvedBy: resolved.resolvedBy,
+            resolvedTarget: resolvedTargetDiagnostics(xmlDoc, paragraph, metadata, targetText, options)
         });
     }
     return resolved;