@ansonlai/docx-redline-js 0.5.1 → 0.5.3

package/AGENTS.md

@@ -55,12 +55,12 @@ const result = await applyRedlineToOxml(oxml, originalText, modifiedText, {
 contains tracked changes from the same author, prior revisions by that author are
 reverted to the pre-revision baseline and re-diffed to the new text, cleanly
 merging the edits without accumulating intermediate revisions or nesting markup.
-If the paragraph contains revisions from a different reviewer, the edit fails
-with `EXISTING_REVISIONS` to safeguard third-party marks. Pass
-`existingRevisions: 'slice-cross-author'` (or `--existing-revisions slice-cross-author`)
-to preserve the other reviewer's attribution while applying Word-native
-insertions and deletions inside their pending insertion. Pass
-`existingRevisions: 'accept-all-first'` (or `--existing-revisions accept-all-first`
+If the paragraph contains revisions from a different reviewer, the edit fails
+with `EXISTING_REVISIONS` to safeguard third-party marks. Pass
+`existingRevisions: 'slice-cross-author'` (or `--existing-revisions slice-cross-author`)
+to preserve the other reviewer's attribution while applying Word-native
+insertions and deletions inside their pending insertion. Pass
+`existingRevisions: 'accept-all-first'` (or `--existing-revisions accept-all-first`
 via CLI) to normalize all prior revisions first, or `'reject-input'` to refuse any
 paragraph with open revisions. Use `'accept-all-first-keep-normalized'` only when
 accepted revisions should be returned as a real change even on a no-op edit.
@@ -144,12 +144,30 @@ const result = await applyOperationsToDocumentXml(documentXml, operations, 'Agen
 The operation runner uses these field names:
 
 ```js
-const operations = [
+const operations = [
   { type: 'redline', target: 'Old paragraph text', modified: 'New paragraph text', targetRef: 12 },
   { type: 'comment', target: 'Paragraph text', textToComment: 'anchor text', commentContent: 'Comment body', targetRef: 18 },
   { type: 'highlight', target: 'Paragraph text', textToHighlight: 'anchor text', color: 'yellow', targetRef: 24 }
-];
-```
+];
+```
+
+To counterpropose text for a paragraph wholly deleted by another reviewer,
+use explicit restoration intent. A normal `redline` remains fail-closed with
+`FOREIGN_PARAGRAPH_MARK_DELETION`:
+
+```js
+const restoration = {
+  type: 'restore',
+  target: { paragraphId: '1A2B3C4D' },
+  modified: 'Restored or adjusted paragraph text.',
+  author: 'Editor'
+};
+```
+
+For a contiguous range, provide `targetEnd`/`targetEndRef` and one string per
+source paragraph in `modified`. Restoration always uses tracked changes,
+preserves the deleted source paragraph, and inserts the counterproposal before
+it with a fresh paragraph ID.
 
 `targetRef` is an optional 1-based paragraph reference used to disambiguate
 duplicate text. An operation-level `author` overrides the batch author; batch
@@ -263,12 +281,16 @@ docx-redline apply contract.docx --target "Original clause" --modified "New clau
 # 2. Direct edit without tracked changes (clean text, no revision clutter)
 docx-redline apply contract.docx --target "Typo fix" --modified "Fixed typo" --no-redlines --output clean.docx
 
-# 3. Batch operations with ops.json
+# 3. Cross-author edit inside another reviewer's pending insertion
+docx-redline apply contract.docx --target "Pending clause text" --modified "Updated clause text" --existing-revisions slice-cross-author --output reviewed.docx
+
+# 4. Batch operations with ops.json
 docx-redline apply contract.docx --operations operations.json --output reviewed.docx
 ```
 
 Key CLI defaults and behaviors:
 - **Author**: Automatically defaults to `'AI Redliner'` (overridable via `--author` or `DOCX_REDLINE_AUTHOR` environment variable).
+- **Existing revisions**: Defaults to `'merge-same-author'`. Pass `--existing-revisions slice-cross-author` to edit inside another reviewer's pending insertions with native carrier slicing.
 - **Overwrite behavior**: Destination files provided via `--output` overwrite by default. To protect existing destination files, pass `--no-overwrite` or `--no-clobber`. The source document is never overwritten unless `--in-place` is specified.
 - **Tracked changes**: Defaults to `generateRedlines: true`. When clean direct text is needed, pass `--no-redlines`.
 - **Atomic rollback (optional)**: Operations apply progressively by default (`atomic: false`). For all-or-nothing transactional rollback where any error halts and reverts all changes, pass `--atomic`.
@@ -392,7 +414,11 @@ When the CLI or runner returns an error code, follow these specific recovery act
 | `AMBIGUOUS_TARGET` | Multiple paragraphs match identical text. | Disambiguate by supplying `paragraphId`, `fingerprint`, `occurrence`, or `index` in the target descriptor. |
 | `ANCHOR_NOT_FOUND` / `AMBIGUOUS_ANCHOR` | Comment anchor text was not uniquely matched in paragraph. | Narrow `textToComment` to a unique exact substring, or omit `textToComment` to anchor the comment to the entire paragraph. |
 | `OVERLAPPING_TEXT_EDITS` | Multiple operations target the same paragraph concurrently. | Consolidate all changes to the same paragraph into a single `redline` or `replace` operation. |
-| `EXISTING_REVISIONS` | Target paragraph contains tracked changes from another author. | Fails closed to protect third-party review marks. Report the other reviewer's name to the user. Do not pass `accept-all-first` without explicit authorization. |
+| `EXISTING_REVISIONS` | Target paragraph contains tracked changes from another author. | Fails closed to protect third-party review marks. If editing inside that reviewer's pending insertion is intended, pass `--existing-revisions slice-cross-author` (or `existingRevisions: 'slice-cross-author'`). Do not pass `accept-all-first` without explicit user authorization. |
+| `PATCH_ROUNDTRIP_MISMATCH` | A cross-author surgical edit did not reconstruct the requested modified text exactly. | Treat the operation as unapplied. Re-extract the exact paragraph text and split the edit into a narrower operation that does not cross the reported structural boundary. |
+| `FOREIGN_PARAGRAPH_MARK_DELETION` | A normal edit attempted to write into a paragraph wholly deleted by another reviewer. | Use an explicit `restore` operation if the user intends to counterpropose that paragraph; otherwise leave the deletion unresolved. |
+| `RESTORATION_STATE_REQUIRED` / `RESTORATION_COUNT_MISMATCH` | A `restore` target is not a wholly foreign-deleted paragraph, or its replacement count does not match the paragraph range. | Re-inspect the document and target the deleted paragraph by stable descriptor; provide exactly one replacement string per source paragraph. |
+| `UNSAFE_DELETED_TABLE_ROW` / `UNSUPPORTED_MOVE_REVISION` / `SECTION_BREAK_PARAGRAPH` / `UNSAFE_PARAGRAPH_PLACEMENT` | Paragraph restoration cannot preserve the source structural boundary safely. | Do not retry as an ordinary redline. Resolve the row/move/section/placement condition manually or narrow the restoration to a safe paragraph. |
 | `COMMENTED_CONTENT_MERGE` / `COMMENTED_CONTENT_DELETE` | Operation would overwrite, revert, or delete content with comments. | Fails closed to prevent orphaned comment threads. Report the comment author and text to the user; resolve the comment before re-editing. |
 | `INVALID_OPERATION` | Operation object violates schema or has incompatible fields. | Validate the JSON structure against [`document-operations.schema.json`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/docs/schemas/document-operations.schema.json) before targeting is attempted. |
 | `STRUCTURED_CONTENT_INVALID` | Malformed Markdown table or structure in replacement text. | Ensure tables include a separator row (`\| --- \| --- \|`) and consistent column counts; do not downgrade to raw text. |
@@ -531,7 +557,7 @@ orchestration/
 | `structuredContent` | `boolean` | `true` | Auto-detects Markdown tables, headings (`#`), and lists in replacement text and renders them as native Word elements (`w:tbl`, `w:pStyle`, `w:numPr`). Pass `false` to treat replacement text strictly as plain text. |
 | `pairReplacements` | `boolean` | `true` | Links adjacent `<w:del>` and `<w:ins>` revisions with matching timestamps so Word groups them as a single replacement in the Reviewing Pane. |
 | `strictTargets` | `boolean` | `true` (CLI/facade) | Requires exact target descriptors (`exactText`, `paragraphId`, `index`, `occurrence`, `fingerprint`) and forbids ambiguous matching. Defaults to `false` in low-level runner for backwards compatibility. |
-| `existingRevisions` | `string` | `'merge-same-author'` | How to handle paragraphs with existing tracked changes. `'merge-same-author'` merges the same author's work and protects other authors with `EXISTING_REVISIONS`. `'slice-cross-author'` retains same-author merging while allowing Word-native edits inside another author's pending insertion. Pass `'accept-all-first'` to normalize prior revisions or `'reject-input'` to refuse editing revised paragraphs. |
+| `existingRevisions` | `string` | `'merge-same-author'` | How to handle paragraphs with existing tracked changes. `'merge-same-author'` merges the same author's work and protects other authors with `EXISTING_REVISIONS`. `'slice-cross-author'` retains same-author merging while allowing Word-native edits inside another author's pending insertion. Pass `'accept-all-first'` to normalize prior revisions or `'reject-input'` to refuse editing revised paragraphs. |
 | `removeFormatting` | `boolean` | `false` | When `true` and the text is unchanged with no Markdown hints, strips existing bold/italic/underline/strikethrough formatting. |
 | `sanitizeInput` | `boolean` | `false` | Opt-in removal of standalone leading assistant-preface lines. Literal dollar signs and `\n` sequences are always preserved. |
 
@@ -617,7 +643,7 @@ directly into `word/document.xml`.
 5. `useNativeApi: true` means standalone mode cannot fully handle that operation path.
 6. `deleteCommentsByAuthorInOoxml` removes definitions and linked anchors only when they are present in the same OOXML payload. In a real `.docx`, `word/comments.xml` and `word/document.xml` are separate parts and must both be updated by the package integration layer.
 7. If output begins with `<pkg:package`, treat it as package-level OOXML and normalize it before writing anything back to `word/document.xml`.
-8. Existing revisions from the same author are merged by default against the pre-revision baseline (`merge-same-author`), while third-party revisions fail closed with `EXISTING_REVISIONS`. Pass `existingRevisions: 'slice-cross-author'` to preserve third-party attribution while editing inside pending insertions, `'accept-all-first'` to normalize all prior revisions first, or `'reject-input'` to refuse any revised paragraph.
+8. Existing revisions from the same author are merged by default against the pre-revision baseline (`merge-same-author`), while third-party revisions fail closed with `EXISTING_REVISIONS`. Pass `existingRevisions: 'slice-cross-author'` to preserve third-party attribution while editing inside pending insertions, `'accept-all-first'` to normalize all prior revisions first, or `'reject-input'` to refuse any revised paragraph.
 9. Caller content is not sanitized by default. Pass `sanitizeInput: true` only for raw assistant output; literal dollar delimiters and `\\n` sequences are never rewritten.
 10. Hyperlinks, bookmarks, comment markers, tabs/breaks, and footnote/endnote references are structural OOXML and should survive adjacent redline edits.
 11. Internally, create Word elements through `createWordElement` and tracked-change metadata through `createRevisionMetadata`.

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## Unreleased
+
+### Safety Fixes
+
+- **Foreign deleted-paragraph resurrection guard**: Refuses non-empty same-paragraph edits when another author owns the paragraph-mark deletion and all existing paragraph content is deleted. The operation now returns `FOREIGN_PARAGRAPH_MARK_DELETION` with the owning author instead of emitting lifecycle-unsafe OOXML; atomic document operations roll back byte-for-byte. `validateRedlineOoxml` reports already-authored instances as warnings.
+
+### New Features
+
+- **Explicit paragraph restoration (`type: 'restore'`)**: Restores or counterproposes another reviewer's pending whole-paragraph deletion as a separately tracked sibling paragraph. The source deletion remains untouched; the restored paragraph receives its own inserted paragraph mark, content insertion, sanitized paragraph properties, and fresh `w14:paraId`. Single paragraphs and contiguous ranges are supported, with full Accept/Reject lifecycle verification and structured refusals at unsafe table-row, move, section-break, and terminal-paragraph boundaries.
+
+## 0.5.1
+
+### Highlights & New Features
+
+- **Cross-Author Revision Slicing (`existingRevisions: 'slice-cross-author'`)**: Adds native support for editing text inside another reviewer's pending tracked insertion without erasing their attribution or requiring prior acceptance.
+  - **Word-Native Insertion Slicing**: When inserting text inside another author's pending `<w:ins>`, the engine splits the outer carrier into sibling `<w:ins>` elements at the paragraph level (`[ins(A), ins(B), ins(A)]`), ensuring strict ECMA-376 schema compliance without illegal `ins/ins` nesting.
+  - **Word-Native Deletion Slicing**: When deleting text inside another author's pending `<w:ins>`, the engine nests `<w:del>` directly inside `<w:ins>` per ECMA-376 Part 1 `CT_RunTrackChange` Section 17.13.5.21 and Microsoft Word Desktop 365 native behavior.
+  - **Boundary & Straddle Deletions**: Deletions straddling baseline text and pending insertions cleanly partition into separate top-level and nested `<w:del>` containers while sharing unified event/author attribution.
+  - **Multi-Author Stacked Revisions**: Multiple reviewers can independently delete or insert content within the same carrier insertion without cross-author interference.
+  - **Cascading & Coalescing Lifecycles**: Full round-trip lifecycle parity with Microsoft Word Desktop:
+    - Rejecting Author A cleanly discards Author A's insertion and any dependent nested deletions by Author B.
+    - Accepting Author A unwraps the insertion into baseline text while leaving Author B's deletions pending against the baseline.
+    - Rejecting Author B restores Author B's deleted text within Author A's insertion, and coalesces adjacent split `<w:ins>` fragments back into a single continuous carrier.
+  - **CLI & Facade Integration**: Fully exposed via the `docx-redline` CLI (`--existing-revisions slice-cross-author`), Node facade (`openDocx`), and batch operation runner.
+
+### Non-breaking Changes & Improvements
+
+- **Validation Update (`validateRedlineOoxml`)**: Refined `NESTED_REVISION` checks to permit direct `<w:ins><w:del>...</w:del></w:ins>` nesting (standard ECMA-376 and Word Desktop behavior), while continuing to strictly reject `ins/ins`, `del/del`, and `del/ins` nesting.
+- **Slicing Round-Trip Guard**: Cross-author surgical edits now preserve whitespace-only insertions (including ordinary-space replacements for NBSP characters beside hyperlinks) and verify the exact accepted-view text before reporting success. A mismatch fails closed with `PATCH_ROUNDTRIP_MISMATCH` and returns the original OOXML unchanged.
+- **Hyperlink-Adjacent Replacement Anchoring**: Paired replacements immediately before or after a hyperlink now retain a stable insertion point after the deletion run is split, preventing qualifiers from being relocated past the hyperlink or following formatted runs.
+- **Multiple Same-Run Insertions**: Insertion-only slicing operations with multiple edit points now apply from right to left against a refreshed live span index, preventing an earlier run split from relocating later insertions.
+- **Insertion Stress Hardening**: Slicing now detects edge whitespace changes exactly, uses a character-local insertion-only diff when the original text is an exact subsequence of the modified text, and coalesces new text into an existing same-author carrier when foreign revisions are also present. This prevents repeated phrases from relocating insertions and prevents invalid `w:ins/w:ins` nesting in mixed-author paragraphs.
+- **Preflight Inspection**: `preflightOperations` now inspects and validates `slice-cross-author` batches, reporting pending foreign-author carrier targets as `ready` instead of `EXISTING_REVISIONS`.
+- **Test Suite Expansion**: Added 7 new test suites covering 36 Word Desktop COM golden fixtures, carrier splitting invariants, the SYN-01..12d synthetic test matrix, PKG-01..06 strict package differential replay, the repeated-text/hyperlink whitespace regression, 76 deterministic insertion stress scenarios, and 12 replacement-anchor lifecycle scenarios (expanding the suite from 88 to 95 passing suites).
+
 ## 0.5.0
 
 ### ⚠️ Breaking changes

package/README.md

@@ -143,6 +143,8 @@ docx-redline extract contract.docx --range 10:30
 docx-redline preflight contract.docx --operations operations.json --author "Editor"
 docx-redline apply contract.docx --operations operations.json --author "Editor" --output reviewed.docx
 docx-redline validate reviewed.docx
+```
+
 ```bash
 # Inline one-liner edit (no operations file needed)
 docx-redline apply contract.docx --target "Original clause text" --modified "New clause text" --output reviewed.docx
@@ -150,6 +152,9 @@ docx-redline apply contract.docx --target "Original clause text" --modified "New
 # Direct edit without tracked changes
 docx-redline apply contract.docx --target "Typo fix" --modified "Fixed typo" --no-redlines --output clean.docx
 
+# Cross-author edit inside another reviewer's pending insertion
+docx-redline apply contract.docx --target "Another author's clause" --modified "Revised clause" --existing-revisions slice-cross-author --output reviewed.docx
+
 # High-assurance atomic batch
 docx-redline apply contract.docx --operations operations.json --atomic --output reviewed.docx
 ```
@@ -157,6 +162,7 @@ docx-redline apply contract.docx --operations operations.json --atomic --output
 All commands emit JSON on stdout. `apply` defaults:
 - **Author**: Defaults to `'AI Redliner'` (or `DOCX_REDLINE_AUTHOR` environment variable).
 - **Output overwrite**: Destination files provided via `--output` overwrite by default. Pass `--no-overwrite` or `--no-clobber` to safeguard existing destination files. The source input is never overwritten unless `--in-place` is specified.
+- **Existing revisions**: Defaults to `'merge-same-author'`. Pass `--existing-revisions slice-cross-author` to edit inside another reviewer's pending insertions with native carrier slicing.
 - **Transactionality**: Defaults to `atomic: false` (applies valid operations and reports any failures). Pass `--atomic` for all-or-nothing rollback on any operation error.
 - **Tracked changes**: Defaults to `generateRedlines: true`. Pass `--no-redlines` when clean direct text edits are desired.
 - **Inline edits**: Use `--target <text>` with `--modified <text>` or `--comment <text>` for quick one-liners without creating a JSON file.
@@ -183,13 +189,13 @@ See [the agent workflow in AGENTS.md](./AGENTS.md#agent-document-workflow-cli) a
 | `structuredContent` | `boolean` | `true` | Auto-detects Markdown tables, headings (`#`), and lists in replacement text and renders them as native Word elements (`w:tbl`, `w:pStyle`, `w:numPr`). Pass `false` to treat replacement text strictly as plain text. |
 | `pairReplacements` | `boolean` | `true` | Links adjacent `<w:del>` and `<w:ins>` revisions with matching timestamps so Word groups them as a single replacement in the Reviewing Pane. |
 | `strictTargets` | `boolean` | `true` (CLI/facade) | Requires exact target descriptors (`exactText`, `paragraphId`, `index`, `occurrence`, `fingerprint`) and forbids ambiguous matching. Defaults to `false` in low-level runner for backwards compatibility. |
-| `existingRevisions` | `string` | `'merge-same-author'` | How to handle paragraphs with existing tracked changes. `'merge-same-author'` merges revisions from the same author and protects other authors with `EXISTING_REVISIONS`. `'slice-cross-author'` keeps that same-author merge behavior while allowing Word-native edits inside another author's pending insertion. Pass `'accept-all-first'` to normalize prior revisions or `'reject-input'` to refuse editing revised paragraphs. |
+| `existingRevisions` | `string` | `'merge-same-author'` | How to handle paragraphs with existing tracked changes. `'merge-same-author'` merges revisions from the same author and protects other authors with `EXISTING_REVISIONS`. `'slice-cross-author'` keeps that same-author merge behavior while allowing Word-native edits inside another author's pending insertion. Pass `'accept-all-first'` to normalize prior revisions or `'reject-input'` to refuse editing revised paragraphs. |
 | `removeFormatting` | `boolean` | `false` | When `true` and the text is unchanged with no Markdown hints, strips existing bold/italic/underline/strikethrough formatting. |
-| `sanitizeInput` | `boolean` | `false` | Opt-in removal of standalone leading assistant-preface lines. Literal dollar signs and `\n` sequences are always preserved. |
-
-Same-author revision merging refuses paragraphs containing comment anchors with
-`COMMENTED_CONTENT_MERGE`; resolve those comments first so the merge cannot
-remove or orphan their anchors.
+| `sanitizeInput` | `boolean` | `false` | Opt-in removal of standalone leading assistant-preface lines. Literal dollar signs and `\n` sequences are always preserved. |
+
+Same-author revision merging refuses paragraphs containing comment anchors with
+`COMMENTED_CONTENT_MERGE`; resolve those comments first so the merge cannot
+remove or orphan their anchors.
 
 Common result fields:
 
@@ -205,6 +211,24 @@ the safe ceiling of 262,144 unique diff tokens return `DIFF_TOKEN_LIMIT` with
 the original OOXML unchanged so callers can split the operation without risking
 silent text loss.
 
+### Editing inside existing revisions (cross-author slicing)
+
+During multi-round legal negotiations, a reviewer often needs to edit text that was previously inserted by another reviewer whose revision is still pending. Pass `existingRevisions: 'slice-cross-author'` (or `--existing-revisions slice-cross-author` via CLI) to edit inside another author's pending insertion without erasing their attribution or requiring prior acceptance:
+
+```js
+const result = await applyRedlineToOxml(paragraphOoxml, originalText, modifiedText, {
+  generateRedlines: true,
+  author: 'Anson Lai',
+  existingRevisions: 'slice-cross-author'
+});
+```
+
+The engine applies Microsoft Word Desktop-native tracked change structures:
+- **Insertions inside pending insertions**: The carrier `<w:ins>` is split into sibling `<w:ins>` containers at the paragraph level (`[ins(Author A), ins(Author B), ins(Author A)]`), maintaining strict schema compliance without illegal `ins/ins` nesting.
+- **Deletions inside pending insertions**: The new `<w:del>` is nested directly inside the carrier `<w:ins>` (valid under ECMA-376 Part 1 `CT_RunTrackChange`), ensuring that if Author A's insertion is rejected, Author B's dependent deletion is cleanly removed with it.
+- **Straddle deletions**: Deletions spanning between baseline text and pending insertions cleanly partition across their respective container contexts without invalid coalescing.
+- **Lifecycle parity**: Accepting or rejecting either reviewer independently produces identical results to Microsoft Word Desktop's native review pane.
+
 ### Replacing a heading with a tracked list
 
 The list route treats a one-paragraph heading expanded into multiple markdown
@@ -309,11 +333,19 @@ an earlier block has already replaced.
 | `ensureCommentsExtendedArtifactsInZip(zip, commentsExtendedXml)` | Add or replace modern Word comment-thread metadata in a `.docx` package. |
 | `validateDocxPackage(zip)` | Validate `.docx` structural consistency. |
 
-Malformed OOXML never escapes these public transform APIs as a raw parser
-exception. Transforms return `status: 'error'` with `error.code === 'PARSE_ERROR'`;
-validators return a `PARSE_ERROR` issue. Recoverable XML parser
-diagnostics are forwarded through the configured logger and included in
-`warnings` where the result shape supports them.
+Malformed OOXML never escapes these public transform APIs as a raw parser
+exception. Transforms return `status: 'error'` with `error.code === 'PARSE_ERROR'`;
+validators return a `PARSE_ERROR` issue. Recoverable XML parser
+diagnostics are forwarded through the configured logger and included in
+`warnings` where the result shape supports them.
+
+Cross-author slicing also verifies its exact accepted-view text before success.
+If a structural boundary prevents exact reconstruction, the transform returns
+`status: 'error'` with `error.code === 'PATCH_ROUNDTRIP_MISMATCH'`,
+`hasChanges: false`, and the original OOXML unchanged.
+Pure insertion-only slicing uses an exact character-local diff so repeated words
+cannot move an insertion to a different occurrence. Leading/trailing spaces,
+tabs, and non-breaking spaces are treated as real changes rather than no-ops.
 
 ### Deep Imports
 
@@ -488,14 +520,27 @@ import { applyOperationToDocumentXml } from '@ansonlai/docx-redline-js/standalon
 const zip = await JSZip.loadAsync(docxBuffer);
 const documentXml = await zip.file('word/document.xml').async('string');
 
-const opResult = await applyOperationToDocumentXml(
+const opResult = await applyOperationToDocumentXml(
   documentXml,
   { type: 'redline', target: 'old text', modified: 'new text' },
   'Editor'
-);
+);
+
+// Restoring another reviewer's pending whole-paragraph deletion requires
+// explicit intent. The restored counterproposal becomes a separately tracked
+// sibling paragraph; a normal redline operation remains fail-closed.
+const restoration = await applyOperationToDocumentXml(
+  documentXml,
+  {
+    type: 'restore',
+    target: { paragraphId: '1A2B3C4D' },
+    modified: 'Restored or adjusted paragraph text.'
+  },
+  'Editor'
+);
 
 // applyOperationToDocumentXml(...) returns a full w:document payload.
-zip.file('word/document.xml', opResult.documentXml);
+zip.file('word/document.xml', opResult.documentXml);
 
 const fragmentResult = await applyRedlineToOxml(
   paragraphOoxml,

package/core/paragraph-revision-safety.js

@@ -0,0 +1,213 @@
+const NON_CONTENT_CHILDREN = new Set([
+    'pPr',
+    'bookmarkStart', 'bookmarkEnd',
+    'commentRangeStart', 'commentRangeEnd', 'commentReference',
+    'customXmlInsRangeStart', 'customXmlInsRangeEnd',
+    'customXmlDelRangeStart', 'customXmlDelRangeEnd',
+    'moveFromRangeStart', 'moveFromRangeEnd',
+    'moveToRangeStart', 'moveToRangeEnd',
+    'permStart', 'permEnd', 'proofErr'
+]);
+
+function localNameOf(node) {
+    return String(node?.localName || node?.nodeName || '').replace(/^.*:/, '');
+}
+
+function directElementChildren(node) {
+    return Array.from(node?.childNodes || []).filter(child => child.nodeType === 1);
+}
+
+function directChild(node, localName) {
+    return directElementChildren(node).find(child => localNameOf(child) === localName) || null;
+}
+
+function wordAttribute(node, localName) {
+    return node?.getAttribute?.(`w:${localName}`)
+        || node?.getAttribute?.(localName)
+        || '';
+}
+
+function normalizedAuthor(author) {
+    return String(author || '').trim().toLowerCase();
+}
+
+function isAnchorOnlyRun(node) {
+    if (localNameOf(node) !== 'r') return false;
+    return directElementChildren(node).every(child => [
+        'rPr', 'commentReference',
+        'bookmarkStart', 'bookmarkEnd',
+        'commentRangeStart', 'commentRangeEnd',
+        'proofErr'
+    ].includes(localNameOf(child)));
+}
+
+function isNonContentChild(node) {
+    return NON_CONTENT_CHILDREN.has(localNameOf(node)) || isAnchorOnlyRun(node);
+}
+
+function isWhollyDeletedContentNode(node) {
+    if (localNameOf(node) === 'del') return true;
+    if (!['customXml', 'smartTag', 'sdt', 'sdtContent'].includes(localNameOf(node))) return false;
+    const contentChildren = directElementChildren(node).filter(child => (
+        !isNonContentChild(child) && localNameOf(child) !== 'sdtPr'
+    ));
+    return contentChildren.every(isWhollyDeletedContentNode);
+}
+
+function paragraphFallsWithinMoveFromRange(paragraph) {
+    const root = paragraph?.ownerDocument?.documentElement || null;
+    if (!root) return false;
+    const openIds = new Set();
+    for (const node of [root, ...Array.from(root.getElementsByTagName?.('*') || [])]) {
+        if (node === paragraph && openIds.size > 0) return true;
+        const name = localNameOf(node);
+        const id = wordAttribute(node, 'id');
+        if (name === 'moveFromRangeStart' && id !== '') openIds.add(id);
+        if (name === 'moveFromRangeEnd' && id !== '') openIds.delete(id);
+    }
+    return false;
+}
+
+function paragraphMarkDeletion(paragraph) {
+    const pPr = directChild(paragraph, 'pPr');
+    const rPr = directChild(pPr, 'rPr');
+    return directChild(rPr, 'del');
+}
+
+function hasVisibleInsertionContent(insertion) {
+    for (const node of Array.from(insertion?.getElementsByTagName?.('*') || [])) {
+        const localName = localNameOf(node);
+        if (!['t', 'tab', 'br', 'cr', 'noBreakHyphen', 'softHyphen'].includes(localName)) continue;
+        let ancestor = node.parentNode;
+        let hidden = false;
+        while (ancestor && ancestor !== insertion) {
+            const ancestorName = localNameOf(ancestor);
+            if (ancestorName === 'del' || ancestorName === 'moveFrom') {
+                hidden = true;
+                break;
+            }
+            ancestor = ancestor.parentNode;
+        }
+        if (hidden) continue;
+        if (localName !== 't' || (node.textContent || '').length > 0) return true;
+    }
+    return false;
+}
+
+/**
+ * Detects the pre-mutation resurrection target defined by WP08: a paragraph
+ * mark deleted by another author with no surviving content in that paragraph.
+ */
+export function inspectForeignDeletedParagraphTarget(paragraph, mutationAuthor) {
+    const markDeletion = paragraphMarkDeletion(paragraph);
+    if (!markDeletion) {
+        return {
+            matches: false,
+            hasParagraphMarkDeletion: false,
+            foreignParagraphMarkDeletion: false,
+            allContentDeleted: false,
+            ownerAuthor: null,
+            markDeletion: null
+        };
+    }
+
+    const ownerAuthor = wordAttribute(markDeletion, 'author') || null;
+    const foreignParagraphMarkDeletion = !ownerAuthor
+        || normalizedAuthor(ownerAuthor) !== normalizedAuthor(mutationAuthor);
+
+    const contentChildren = directElementChildren(paragraph)
+        .filter(child => !isNonContentChild(child));
+    const allContentDeleted = contentChildren.every(isWhollyDeletedContentNode);
+    return {
+        matches: foreignParagraphMarkDeletion && allContentDeleted,
+        hasParagraphMarkDeletion: true,
+        foreignParagraphMarkDeletion,
+        allContentDeleted,
+        ownerAuthor,
+        markDeletion
+    };
+}
+
+export function getParagraphRestorationRefusal(paragraph) {
+    const pPr = directChild(paragraph, 'pPr');
+    if (directChild(pPr, 'sectPr')) {
+        return {
+            code: 'SECTION_BREAK_PARAGRAPH',
+            message: 'Refusing to restore a deleted paragraph whose paragraph properties contain a section break.'
+        };
+    }
+
+    let ancestor = paragraph?.parentNode || null;
+    while (ancestor) {
+        if (localNameOf(ancestor) === 'moveFrom') {
+            return {
+                code: 'UNSUPPORTED_MOVE_REVISION',
+                message: 'Refusing to restore a paragraph that is part of a pending move-from revision.'
+            };
+        }
+        ancestor = ancestor.parentNode;
+    }
+    if (
+        paragraphFallsWithinMoveFromRange(paragraph)
+        ||
+        paragraph?.getElementsByTagName?.('*')
+        && Array.from(paragraph.getElementsByTagName('*')).some(node => ['moveFrom', 'moveFromRangeStart', 'moveFromRangeEnd'].includes(localNameOf(node)))
+    ) {
+        return {
+            code: 'UNSUPPORTED_MOVE_REVISION',
+            message: 'Refusing to restore a paragraph that is part of a pending move-from revision.'
+        };
+    }
+
+    let row = paragraph?.parentNode || null;
+    while (row && localNameOf(row) !== 'tr') row = row.parentNode;
+    const rowProperties = directChild(row, 'trPr');
+    if (rowProperties && directChild(rowProperties, 'del')) {
+        return {
+            code: 'UNSAFE_DELETED_TABLE_ROW',
+            message: 'Refusing to restore a paragraph inside a table row with a pending row deletion.'
+        };
+    }
+
+    let sibling = paragraph?.nextSibling || null;
+    while (sibling && (sibling.nodeType !== 1 || localNameOf(sibling) !== 'p')) sibling = sibling.nextSibling;
+    if (!sibling) {
+        return {
+            code: 'UNSAFE_PARAGRAPH_PLACEMENT',
+            message: 'Refusing to restore a deleted paragraph without a following paragraph in the same structural container.'
+        };
+    }
+
+    return null;
+}
+
+/**
+ * Finds already-authored same-paragraph resurrection shapes. This is a
+ * warning-only validation predicate because standalone validation has no
+ * mutation baseline with which to prove when a foreign insertion was added.
+ */
+export function findForeignDeletedParagraphResurrections(root) {
+    const paragraphs = localNameOf(root) === 'p'
+        ? [root]
+        : Array.from(root?.getElementsByTagName?.('*') || []).filter(node => localNameOf(node) === 'p');
+    const matches = [];
+
+    for (const paragraph of paragraphs) {
+        const markDeletion = paragraphMarkDeletion(paragraph);
+        if (!markDeletion) continue;
+        const ownerAuthor = wordAttribute(markDeletion, 'author') || null;
+        const contentChildren = directElementChildren(paragraph)
+            .filter(child => !isNonContentChild(child));
+        const foreignInsertions = contentChildren.filter(child => {
+            if (localNameOf(child) !== 'ins' || !hasVisibleInsertionContent(child)) return false;
+            return normalizedAuthor(wordAttribute(child, 'author')) !== normalizedAuthor(ownerAuthor);
+        });
+        const onlyDeletedContentAndForeignInsertions = contentChildren.every(child => {
+            return isWhollyDeletedContentNode(child) || foreignInsertions.includes(child);
+        });
+        if (foreignInsertions.length > 0 && onlyDeletedContentAndForeignInsertions) {
+            matches.push({ paragraph, markDeletion, ownerAuthor, foreignInsertions });
+        }
+    }
+    return matches;
+}

package/core/paragraph-targeting.js

@@ -459,6 +459,25 @@ export function resolveTargetParagraph(xmlDoc, options = {}) {
         return { paragraph: byId, resolvedBy: 'paragraph_id' };
     }
 
+    if (descriptor?.fingerprint && !cleanTargetText && !parsedRef) {
+        let fingerprintCandidates = (paragraphMetadataIndex?.entries || [])
+            .filter(candidate => candidate.fingerprint === descriptor.fingerprint);
+        if (typeof descriptor.inTable === 'boolean') {
+            fingerprintCandidates = fingerprintCandidates.filter(candidate => candidate.inTable === descriptor.inTable);
+        }
+        if (fingerprintCandidates.length === 1) {
+            return { paragraph: fingerprintCandidates[0].paragraph, resolvedBy: 'fingerprint' };
+        }
+        if (fingerprintCandidates.length > 1) {
+            throw createTargetError(
+                'AMBIGUOUS_TARGET',
+                'Target fingerprint matched multiple paragraphs; provide paragraphId or index.',
+                fingerprintCandidates.map(serializeTargetCandidate)
+            );
+        }
+        throw createTargetError('TARGET_NOT_FOUND', `Target fingerprint not found: "${descriptor.fingerprint}".`);
+    }
+
     let candidates = [];
     if (cleanTargetText) {
         const unfilteredCandidates = findStrictTargetCandidates(xmlDoc, cleanTargetText, paragraphMetadataIndex);

package/core/redline-validation.js

@@ -10,6 +10,7 @@
 
 import { parseXml } from '../adapters/xml-adapter.js';
 import { NS_W } from './types.js';
+import { findForeignDeletedParagraphResurrections } from './paragraph-revision-safety.js';
 
 const REVISION_ID_ELEMENTS = new Set(['ins', 'del', 'rPrChange', 'pPrChange']);
 const REVISION_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}T/;
@@ -180,5 +181,17 @@ export function validateRedlineOoxml(oxml) {
         }
     }
 
+    // Structurally valid but lifecycle-unsafe: accepting the paragraph-mark
+    // deletion can merge or discard a foreign insertion placed into a
+    // paragraph whose pre-existing content is otherwise wholly deleted.
+    for (const resurrection of findForeignDeletedParagraphResurrections(doc)) {
+        const ownerAuthor = resurrection.ownerAuthor || 'unattributed';
+        addIssue(
+            'FOREIGN_PARAGRAPH_MARK_DELETION',
+            'warning',
+            `Paragraph deleted by ${ownerAuthor} also contains non-empty insertion content from another author; Accept/Reject lifecycle may not preserve the apparent restoration.`
+        );
+    }
+
     return { valid: !issues.some(issue => issue.severity === 'error'), issues };
 }