@ansonlai/docx-redline-js 0.7.0 → 0.7.2

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/docs/validation-reports/2026-09-14-agent-surface-simplification.md

@@ -0,0 +1,75 @@
+# Agent Surface Simplification Replay
+
+**Date:** 2026-09-14  
+**Runtime:** Node.js 24.11.1 on Windows x64  
+**Engine:** Current post-0.7.1 source for every policy  
+**Command:** `npm run benchmark:agent-surface`  
+**Configuration:** 7 measured iterations and 1 warmup per scenario/policy
+
+## Scope
+
+This repository-controlled replay compares three workflow policies without
+changing the underlying engine:
+
+1. `v0.6.2-extract-full`: extraction followed by complete modified text.
+2. `v0.7.1-speculation-led`: speculative literal edits with extraction/apply
+   recovery, and extraction for semantic or batch work.
+3. `simplified-extract-localized`: extraction followed by a compact localized
+   operation against `paragraphId` plus `fingerprint`.
+
+The six wholly synthetic scenarios cover a long literal edit, semantic drafting,
+repeated visible text, rejected-view restoration, an NBSP-bearing target, and an
+independent two-target batch. Every output is re-extracted and compared with its
+predetermined accepted-view text. Benchmark-only verification calls are not
+counted as workflow calls.
+
+## Aggregate Results
+
+| Policy | Correct runs | Total calls | Calls/run | Failed calls | Edit request bytes | Median local ms |
+|---|---:|---:|---:|---:|---:|---:|
+| v0.6.2 extract/full | 42/42 | 84 | 2.00 | 0 | 27,034 | 3.86 |
+| v0.7.1 speculation-led | 42/42 | 77 | 1.83 | 7 | 8,988 | 3.86 |
+| simplified extract/localized | 42/42 | 84 | 2.00 | 0 | 10,661 | 3.77 |
+
+The simplified policy reduced generated edit-request bytes by 60.6% relative to
+the complete-paragraph baseline while preserving a fixed two-call workflow and
+zero failed calls. On the long-paragraph case, its median edit request was 193
+bytes rather than 2,104 bytes, a 90.8% reduction.
+
+The speculation-led policy saved seven total calls because two unique literal
+scenarios completed in one call. The repeated-text scenario cost three calls and
+one failure on every iteration. This demonstrates both the legitimate one-turn
+benefit and the recovery cost that the simplified default is intended to avoid.
+
+The localized form is not always smaller for a short paragraph. In the NBSP
+scenario it used 344 bytes versus 343 bytes for complete modified text. The
+benefit is strongest when the inspected source is long relative to the changed
+span.
+
+## Interpretation
+
+The repository evidence supports the surface decision:
+
+- keep speculative apply as an available expert/harness capability;
+- do not make ordinary agents classify whether to use it;
+- lead with deterministic extraction and one apply;
+- retain localized replacements after inspection to avoid long output payloads;
+- use compact `paragraphId` plus `fingerprint` targets for localized requests,
+  while retaining extracted text locally for drafting; and
+- keep restoration as a request/hint-driven branch.
+
+Local execution time is effectively neutral at this scale and remains far below
+agent deliberation or provider latency. No performance claim should be based on
+the small local timing differences in this report.
+
+## Limitations
+
+This is a deterministic workflow replay, not a model evaluation. It cannot
+measure reasoning tokens, provider tokenization, transport latency, stochastic
+instruction following, or subjective drafting quality. Repeated external agent
+runs using the same model, prompt, document, and engine are still required before
+claiming end-to-end latency improvement.
+
+The machine-readable output is written to
+`tmp/benchmarks/agent-surface-simplification-latest.json` and is intentionally
+not committed.

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('find', '--find <exact text>', 'Case-sensitive source span; exact match first, then ASCII-space/NBSP equivalence.'),
             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

@@ -7,6 +7,7 @@ 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';
+import { localizedReplacementOffsets } from '../services/localized-replacement-compiler.js';
 import { buildCliHelp, CLI_COMMANDS, commandOptionKeys } from './cli-help.js';
 
 const suffixes = { apply: 'redlined', accept: 'accepted', reject: 'rejected', 'delete-comments': 'comments-removed' };
@@ -31,6 +32,8 @@ const CLI_CAPABILITIES = [
     'localized-replacements-v1',
     'speculative-search-apply-v1',
     'localized-change-summary-v1',
+    'localized-space-equivalence-v1',
+    'restore-shortcuts-v1',
     'deduplicated-cli-receipts',
     'compact-cli-json-v1'
 ];
@@ -241,21 +244,27 @@ function resolveSpeculativePatchTarget(document, flags) {
     }
 
     const find = String(flags.find);
-    const matches = eligible.filter(paragraph => paragraph.exactText.includes(find));
+    const patchCandidates = eligible.map(paragraph => ({
+        paragraph,
+        match: localizedReplacementOffsets(paragraph.exactText, find)
+    })).filter(candidate => candidate.match.offsets.length > 0);
+    const exactCandidates = patchCandidates.filter(candidate => candidate.match.matchMode === 'exact');
+    const matches = (exactCandidates.length > 0 ? exactCandidates : patchCandidates)
+        .map(candidate => candidate.paragraph);
     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}".`, {
+            ? `No paragraph in the contextual range contains the patch source: "${find}".`
+            : `No paragraph contains the 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.`, {
+        throw speculativeError('AMBIGUOUS_TARGET', `The patch source matched ${matches.length} eligible paragraphs.`, {
             context,
             candidates: matches.map(speculativeCandidate),
             recovery: { action: 'choose_candidate', requiresReinspection: false, sameArgumentsSafe: false }
@@ -278,6 +287,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 +297,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 +307,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 +334,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 +392,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 +404,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 +466,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 +486,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.2",
   "description": "Host-independent OOXML reconciliation engine for .docx manipulation with track changes",
   "license": "MIT",
   "type": "module",
@@ -47,6 +47,7 @@
     "!scripts/benchmark-agent-workflow.mjs",
     "!scripts/benchmark-agent-cli-discovery.mjs",
     "!scripts/benchmark-localized-turn-reduction.mjs",
+    "!scripts/benchmark-agent-surface-simplification.mjs",
     "!scripts/lib/agent-performance-cases.mjs",
     "docs/AGENT_FAST_START.md",
     "docs/AGENT_KNOWLEDGE_BASE.md",
@@ -58,6 +59,7 @@
     "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",
+    "docs/validation-reports/2026-09-14-agent-surface-simplification.md",
     "index.js",
     "index.d.ts",
     "dist/",
@@ -97,6 +99,7 @@
     "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:agent-surface": "node scripts/benchmark-agent-surface-simplification.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/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,