@ansonlai/docx-redline-js 0.5.3 → 0.5.4

package/AGENTS.md

@@ -158,7 +158,7 @@ use explicit restoration intent. A normal `redline` remains fail-closed with
 ```js
 const restoration = {
   type: 'restore',
-  target: { paragraphId: '1A2B3C4D' },
+  target: { paragraphId: '1A2B3C4D', revisionView: 'rejected' },
   modified: 'Restored or adjusted paragraph text.',
   author: 'Editor'
 };
@@ -166,8 +166,29 @@ const restoration = {
 
 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.
+preserves the deleted source paragraph, and inserts the counterproposal after
+the complete deleted source block with a fresh paragraph ID. Unchanged
+pre-existing validation defects remain baseline diagnostics; a restore fails
+with `GENERATED_OOXML_INVALID` only when it introduces a new validation error.
+
+To insert run-level text inside content visible only in the rejected view, use
+an explicit rejected-view `insert` operation:
+
+```js
+const insertion = {
+  type: 'insert',
+  target: { paragraphId: '1A2B3C4D', revisionView: 'rejected' },
+  anchor: { exactText: 'must pay', occurrence: 1, offset: 5 },
+  modified: '[clarification] ',
+  author: 'Editor',
+  existingRevisions: 'slice-cross-author'
+};
+```
+
+The anchor offset is relative to `anchor.exactText`. Repeated anchors require an
+explicit `occurrence`. The engine preserves the foreign deletion as sibling
+`w:del` carriers around a top-level `w:ins`; unsupported comments, bookmarks,
+fields, hyperlinks, moves, or non-text split boundaries fail closed.
 
 `targetRef` is an optional 1-based paragraph reference used to disambiguate
 duplicate text. An operation-level `author` overrides the batch author; batch
@@ -293,8 +314,9 @@ Key CLI defaults and behaviors:
 - **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`.
-- Check `written: true` on stdout. If an error occurs, inspect `error.code` or `results[i].error.code` (e.g. `TARGET_NOT_FOUND`, `ANCHOR_NOT_FOUND`) to correct the target text and re-apply.
+- **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`.
+- **Compact mutation JSON**: `apply`, `accept`, `reject`, and `delete-comments` omit document/package XML and full validation arrays. `validation.originalIssues` and `validation.generatedIssues` are code/count summaries; run `validate` for full issue records.
+- Check `completion: true`, `written: true`, and a non-null `outputPath` on stdout. `completion` is derived from the write result, top-level status, and every operation status, so failed, partial, and unwritten work cannot appear complete. If an error occurs, inspect `error.code` or `results[i].error.code` (e.g. `TARGET_NOT_FOUND`, `ANCHOR_NOT_FOUND`) before correcting the cause and re-applying.
 
 For multi-clause or multi-page reviews, apply edits **section-by-section** or clause-by-clause (e.g., using `--in-place` on a working copy) rather than bundling dozens of edits into one massive batch. This keeps context compact, simplifies error diagnosis, and prevents cascading anchor drift.
 
@@ -412,12 +434,14 @@ When the CLI or runner returns an error code, follow these specific recovery act
 |---|---|---|
 | `TARGET_NOT_FOUND` | Target text did not match any paragraph. | **Do NOT retry with paraphrased text.** Re-run `extract`/`inspect`, copy `exactText` verbatim (including exact whitespace/punctuation), and add a discriminator (`paragraphId`, `fingerprint`, or `occurrence`). |
 | `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. |
+| `ANCHOR_NOT_FOUND` / `AMBIGUOUS_ANCHOR` | A comment or rejected-view insertion anchor was not uniquely matched. | For comments, narrow `textToComment` or omit it to anchor the whole paragraph. For rejected-view insertion, copy exact rejected text and provide `anchor.occurrence`. |
 | `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. 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. |
+| `REJECTED_INSERTION_STATE_REQUIRED` / `UNSAFE_REVISION_BOUNDARY` | An explicit rejected-view insertion did not resolve to supported plain run text inside a wholly foreign-deleted paragraph. | Do not fall back to a generic edit. Narrow the exact anchor/offset, or handle comments, bookmarks, fields, hyperlinks, moves, or other structural boundaries manually. |
+| `GENERATED_OOXML_INVALID` | The operation introduced a new validation error relative to its baseline. | Treat the operation as unapplied and inspect `generatedIssues`; correct the generating operation or builder rather than repairing or accepting the source document's unrelated baseline defects. |
 | `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. |
@@ -601,12 +625,22 @@ retain their string-only return type and return `''` for parse failures.
 
 ### Target text versus replacement text
 
-Target resolution may normalize surrounding or repeated whitespace while
-matching a paragraph. Replacement text is not normalized: tabs, line breaks,
-non-breaking spaces, repeated spaces, and leading/trailing whitespace become
-part of the requested edit. When editing extracted document text, copy the
-exact paragraph text and modify it in place rather than round-tripping it
-through a formatter that may change whitespace.
+Target resolution may normalize surrounding or repeated whitespace while
+matching a paragraph. Replacement text is not normalized: tabs, line breaks,
+non-breaking spaces, repeated spaces, and leading/trailing whitespace become
+part of the requested edit. When editing extracted document text, copy the
+exact paragraph text and modify it in place rather than round-tripping it
+through a formatter that may change whitespace.
+
+The normalized caller target is never used for mutation offsets in a text-bearing
+edit. After target selection, the engine uses the resolved paragraph's byte-exact
+JavaScript string as the source coordinate system. The legacy format-only
+fallback for field-code paragraphs with no extractable accepted-view spans is
+not a text-replacement path. If an ASCII-space target selected an NBSP
+source, `resolvedTarget.targetTextMatch` reports `space_equivalent`, escaped
+source/request excerpts, and differing code points. An NBSP-to-space request is
+tracked as a replacement; it must not retain the NBSP and append another space.
+The CLI keeps these bounded diagnostics but removes resolved clause text.
 
 For ordinary insertions and deletions, target the visible accepted view:
 inserted `w:t` text is visible and deleted `w:delText` is not. Move revisions

package/ARCHITECTURE.md

@@ -94,6 +94,12 @@ No Word add-in entrypoints or host-specific integration layers are part of this
     fingerprints, document order, and table context for deterministic reuse.
 - `core/redline-validation.js`
   - Runtime structural validation (`validateRedlineOoxml`) mirroring the test-suite invariants: no nested revisions, `w:delText` inside `w:del`, complete revision metadata, unique revision ids, preserved boundary whitespace.
+- `core/validation-delta.js`
+  - Stable issue signatures and multiset subtraction for classifying baseline
+    versus generated validation issues without hiding added duplicate errors.
+- `core/revision-cloning.js`
+  - Shared effective-property cloning strips historical revision descendants;
+    intentional revision-bearing splits refresh cloned property-change IDs.
 - `engine/oxml-engine.js`
   - Main reconciliation router, mode selection, existing-revision policy gate, and status/error result handling.
 - `engine/route-selection.js`
@@ -102,7 +108,10 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 - `engine/run-builders.js`
   - Shared builders for insertion/deletion wrappers, paragraph-mark revisions, visible run content, and run-property changes.
 - `engine/surgical-*.js`
-  - Surgical run splitting, diff application, and span helpers for localized edits that preserve surrounding markup.
+  - Surgical run splitting, diff application, and span helpers for localized edits that preserve surrounding markup. Plain-text edit groups execute from right to left with a fresh live span index, while space/NBSP-only replacement hunks are refined to character-local changes so unchanged hyperlink containers survive.
+    The shared carrier splitter also handles explicit rejected-view deletion
+    splits, retaining `w:delText`, tabs, breaks, soft/non-breaking hyphens,
+    formatting, foreign metadata, and fresh trailing/property-change IDs.
 - `engine/formatting-removal.js`
   - Shared formatting removal and highlight helpers.
 - `pipeline/list-markers.js`
@@ -130,10 +139,21 @@ No Word add-in entrypoints or host-specific integration layers are part of this
     preflight, single-operation application, batch application, and scheduling.
 - `services/document-operation-applier.js`
   - Canonical single-operation validation, author resolution, dispatch, and
-    result metadata assembly.
+    result metadata assembly. Before commit it validates the entire live
+    document against the operation savepoint and refuses newly generated
+    structural errors, including duplicate revision IDs.
 - `services/document-operation-mutations.js`
   - Coupled OOXML mutation implementations for redline, highlight, and comment
-    operations. These use leaf-module imports and never import the root entry.
+    operations. For text-bearing edits, the resolved paragraph's exact
+    accepted-view text is the source coordinate system even when target
+    selection used normalized whitespace;
+    bounded match-mode/code-point diagnostics are attached to resolved target
+    metadata. Explicit rejected-view insertion splits a supported direct
+    foreign `w:del` at an anchor-relative offset into sibling deletion,
+    insertion, and deletion carriers. Paragraph restoration emits its inserted
+    block after the untouched source range and verifies baseline-delta,
+    mutation-envelope, and lifecycle postconditions. These use leaf-module
+    imports and never import the root entry.
 - `services/batch-operation-orchestrator.js`
   - Comment-first stable scheduling, atomic policy, artifact aggregation,
     per-operation results, one final document serialization, and deferred
@@ -157,11 +177,16 @@ No Word add-in entrypoints or host-specific integration layers are part of this
     revision authors, table context, and advisory visible numbering.
 - `node/docx-document.js`
   - Transactional whole-DOCX editing, artifact wiring, validation, and rollback.
+    OOXML and package issues are classified as baseline/generated multisets, so
+    unchanged source defects remain diagnostics while new defects block writes.
     This surface is excluded from the browser/root dependency graph.
 - `node/cli.js` and `bin/docx-redline.js`
   - Cross-platform, JSON-only agent command boundary. Read commands never
     mutate; write commands require attribution, use package transactions, and
     only overwrite source files under explicit `--in-place` authorization.
+    Mutation commands expose a compact contract: package/XML payloads and full
+    validation arrays remain internal, while stdout contains durability fields,
+    per-operation evidence, validation counts, and a derived completion flag.
 - `orchestration/*`
   - Route planning and list fallback orchestration utilities.
 
@@ -309,6 +334,16 @@ still be re-exported from `index.js`.
 - Operation-level authors override the batch author. Runtime results expose
   `authorUsed`, `authorsUsed`, `operationType`, `resolvedBy`, and resolved target
   metadata so integrations can audit what the engine actually selected.
+- A normalized target match does not become an edit coordinate system for a
+  text-bearing mutation. Mutation uses canonical accepted-view source text, and `resolvedTarget.targetTextMatch`
+  records `exact`, `space_equivalent`, or `normalized` selection plus bounded
+  invisible-character diagnostics.
+- CLI contract version 3 is deliberately narrower than library result objects.
+  `apply`, `accept`, `reject`, and `delete-comments` omit `documentXml`, package
+  parts, inspection text, and full issue arrays. `completion` is true only when
+  `written === true`, top-level status is neither error nor partial, and every
+  operation result is non-error. The `validate` command remains the full issue
+  reporting surface.
 - `preflightOperations` is the read-only safety boundary for agent-generated
   batches. It uses strict targeting by default; mutation APIs retain permissive
   legacy targeting unless `strictTargets: true` is requested. In v1.0.0,

package/CHANGELOG.md

@@ -5,10 +5,16 @@
 ### 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.
+- **Source-truth whitespace replacement alignment (WP09a)**: Strict target resolution may equate ordinary spaces with NBSPs, but mutation offsets now always come from the resolved paragraph's exact accepted view. Space-equivalent word replacement hunks are refined to character-local edits, and multiple plain-text edits are applied right-to-left against refreshed live spans. This tracks NBSP-to-space substitutions exactly while preserving unchanged hyperlinks and prevents earlier run splits from invalidating later anchors.
+- **Exact mismatch diagnostics**: `PATCH_ROUNDTRIP_MISMATCH` now includes the expected and actual code points at the first mismatch. Document-operation results also report bounded `targetTextMatch` diagnostics when target selection used equivalent whitespace.
+- **Baseline-delta validation (WP09c)**: Restoration, operation, and package validation now compare issue multisets against the source. Unchanged legacy defects remain visible without blocking safe work, while any added occurrence or mutation-envelope error fails closed with `GENERATED_OOXML_INVALID` before an operation is reported as applied.
+- **Revision identity sanitation (WP09d)**: New paragraph/list builders inherit effective `pPr`/`rPr` formatting without cloning historical revision descendants. Operation-level whole-document validation catches duplicate revision IDs and rolls back the operation savepoint before committing its receipt.
 
 ### 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.
+- **Compact mutation CLI contract (WP09b)**: CLI contract version 3 removes `documentXml`, OOXML/package artifacts, full inspection data, and full validation issue arrays from normal `apply`, `accept`, `reject`, and `delete-comments` stdout. Mutation responses retain actionable errors, per-operation receipts, output durability fields, code/count validation summaries, and a derived `completion` flag that cannot report success for failed, partial, or unwritten work.
+- **Word-native deleted-section editing (WP09e)**: An explicit rejected-view `insert` operation can split a foreign deletion at an exact anchor-relative offset into sibling `del(A) / ins(B) / del(A)` carriers. Contiguous paragraph restorations now follow their untouched deleted source block, matching Microsoft Word's ordering. Ambiguous anchors and unsupported structural split boundaries remain fail-closed.
 
 ## 0.5.1
 

package/README.md

@@ -159,13 +159,14 @@ docx-redline apply contract.docx --target "Another author's clause" --modified "
 docx-redline apply contract.docx --operations operations.json --atomic --output reviewed.docx
 ```
 
-All commands emit JSON on stdout. `apply` defaults:
+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.
+- **Inline edits**: Use `--target <text>` with `--modified <text>` or `--comment <text>` for quick one-liners without creating a JSON file.
+- **Compact mutation results**: `apply`, `accept`, `reject`, and `delete-comments` omit full OOXML/package payloads and inspection text from stdout. They report `written`, `outputPath`, per-operation results and receipts, compact validation counts, and a derived `completion` boolean. Use `validate` when full issue arrays are needed.
 
 See [the agent workflow in AGENTS.md](./AGENTS.md#agent-document-workflow-cli) and the
 [operation JSON Schema](docs/schemas/document-operations.schema.json).
@@ -203,8 +204,9 @@ Common result fields:
 |-------|---------|
 | `status` | Operation status: `'ok'`, `'partial'`, `'no-op'`, or `'error'`. |
 | `error` | Present on failure; includes a stable `code` such as `PARSE_ERROR`, `TARGET_NOT_FOUND`, `PARTIAL_TARGET`, `EXISTING_REVISIONS`, `DIFF_TOKEN_LIMIT`, or `BATCH_OPERATION_FAILED`. |
-| `written` | CLI/facade boolean indicating whether the output file was successfully written to disk. |
-| `rolledBack` | Present and `true` when an atomic batch encountered an error and rolled back all changes. |
+| `written` | CLI/facade boolean indicating whether the output file was successfully written to disk. |
+| `completion` | CLI-only boolean that is `true` only when a destination was written, top-level status is neither error nor partial, and no operation result failed. |
+| `rolledBack` | Present and `true` when an atomic batch encountered an error and rolled back all changes. |
 
 Word diffs are deterministic by default (no wall-clock timeout). Inputs above
 the safe ceiling of 262,144 unique diff tokens return `DIFF_TOKEN_LIMIT` with
@@ -216,11 +218,11 @@ silent text loss.
 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'
-});
+const result = await applyRedlineToOxml(paragraphOoxml, originalText, modifiedText, {
+  generateRedlines: true,
+  author: 'Reviewer B',
+  existingRevisions: 'slice-cross-author'
+});
 ```
 
 The engine applies Microsoft Word Desktop-native tracked change structures:
@@ -346,6 +348,12 @@ If a structural boundary prevents exact reconstruction, the transform returns
 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.
+For text-bearing replacements, the exact accepted-view text of the resolved
+paragraph—not a space-normalized caller target—defines mutation offsets. Word-level replacement
+hunks that differ only by ordinary spaces and NBSPs are refined to character
+edits so unchanged hyperlinks and their relationship attributes stay in place.
+Runner results expose bounded `resolvedTarget.targetTextMatch` code-point
+diagnostics when equivalent whitespace was used to identify the target.
 
 ### Deep Imports
 
@@ -533,11 +541,30 @@ const restoration = await applyOperationToDocumentXml(
   documentXml,
   {
     type: 'restore',
-    target: { paragraphId: '1A2B3C4D' },
+    target: { paragraphId: '1A2B3C4D', revisionView: 'rejected' },
     modified: 'Restored or adjusted paragraph text.'
   },
   'Editor'
 );
+
+// A single restoration follows its deleted source paragraph. A range
+// restoration follows the complete deleted source block. Unchanged legacy
+// validation defects are retained as baseline issues; newly generated errors
+// fail closed before commit.
+
+// To insert run-level text at a location visible only in the rejected view,
+// provide explicit rejected-view intent and an exact anchor-relative offset.
+const deletedTextInsertion = await applyOperationToDocumentXml(
+  documentXml,
+  {
+    type: 'insert',
+    target: { paragraphId: '1A2B3C4D', revisionView: 'rejected' },
+    anchor: { exactText: 'must pay', occurrence: 1, offset: 5 },
+    modified: '[clarification] ',
+    existingRevisions: 'slice-cross-author'
+  },
+  'Editor'
+);
 
 // applyOperationToDocumentXml(...) returns a full w:document payload.
 zip.file('word/document.xml', opResult.documentXml);

package/core/paragraph-revision-safety.js

@@ -128,7 +128,7 @@ export function inspectForeignDeletedParagraphTarget(paragraph, mutationAuthor)
     };
 }
 
-export function getParagraphRestorationRefusal(paragraph) {
+export function getParagraphRestorationRefusal(paragraph, options = {}) {
     const pPr = directChild(paragraph, 'pPr');
     if (directChild(pPr, 'sectPr')) {
         return {
@@ -169,13 +169,15 @@ export function getParagraphRestorationRefusal(paragraph) {
         };
     }
 
-    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.'
-        };
+    if (options.requireFollowingParagraph !== false) {
+        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;

package/core/redline-validation.js

@@ -65,19 +65,22 @@ function parseOoxmlForValidation(oxml) {
  * Issue severities: 'error' issues indicate output Word may repair or
  * mis-resolve; 'warning' issues are suspicious but tolerated by Word.
  *
- * @param {string} oxml - OOXML string (fragment, document, or package scope)
+ * @param {string|Document|Element} oxml - OOXML string or an already-parsed DOM
  * @returns {{ valid: boolean, issues: Array<{ code: string, severity: 'error'|'warning', message: string }> }}
  */
 export function validateRedlineOoxml(oxml) {
     const issues = [];
     const addIssue = (code, severity, message) => issues.push({ code, severity, message });
 
-    if (typeof oxml !== 'string' || oxml.trim() === '') {
-        addIssue('PARSE_ERROR', 'error', 'Input is not a non-empty OOXML string.');
+    const isDomNode = oxml && typeof oxml === 'object' && (oxml.nodeType === 9 || oxml.nodeType === 1);
+    if (!isDomNode && (typeof oxml !== 'string' || oxml.trim() === '')) {
+        addIssue('PARSE_ERROR', 'error', 'Input is not non-empty OOXML or a parsed XML DOM.');
         return { valid: false, issues };
     }
 
-    const { doc, error } = parseOoxmlForValidation(oxml);
+    const { doc, error } = isDomNode
+        ? { doc: oxml.nodeType === 9 ? oxml : oxml.ownerDocument }
+        : parseOoxmlForValidation(oxml);
     if (!doc) {
         addIssue('PARSE_ERROR', 'error', `OOXML does not parse as XML: ${error}`);
         return { valid: false, issues };

package/core/revision-cloning.js

@@ -6,6 +6,26 @@ import {
 } from './types.js';
 import { isWordElement } from './word-xml.js';
 
+const REVISION_HISTORY_ELEMENTS = new Set([
+    'ins', 'del', 'moveFrom', 'moveTo', 'pPrChange', 'rPrChange',
+    'tblPrChange', 'trPrChange', 'tcPrChange', 'sectPrChange'
+]);
+
+/**
+ * Clones effective paragraph/run properties without copying tracked history
+ * into a newly created paragraph or run.
+ */
+export function clonePropertiesWithoutRevisionHistory(root) {
+    if (!root) return null;
+    const clone = root.cloneNode(true);
+    const candidates = [clone, ...Array.from(clone.getElementsByTagName?.('*') || [])];
+    for (const node of candidates.reverse()) {
+        if (!REVISION_HISTORY_ELEMENTS.has(String(node.localName || node.nodeName || '').replace(/^.*:/, ''))) continue;
+        node.parentNode?.removeChild(node);
+    }
+    return clone;
+}
+
 /**
  * Assigns fresh document-scoped IDs to w:rPrChange elements in a cloned
  * run-properties subtree. This preserves formatting-revision metadata while
@@ -32,6 +52,7 @@ export function refreshRunPropertyChangeIds(root, allocator = null) {
         } else {
             node.setAttribute('w:id', nextId);
         }
+        resolvedAllocator._receiptCollector?.recordRevision(Number(nextId), 'rPrChange');
     }
 
     return root;

package/core/validation-delta.js

@@ -0,0 +1,23 @@
+function issueKey(issue) {
+    return `${issue?.source || ''}\u001f${issue?.severity || ''}\u001f${issue?.code || ''}\u001f${issue?.message || ''}`;
+}
+
+/** Subtracts baseline validation issues as a multiset, preserving duplicates. */
+export function subtractValidationIssueMultiset(outputIssues = [], baselineIssues = []) {
+    const remaining = new Map();
+    for (const issue of baselineIssues || []) {
+        const key = issueKey(issue);
+        remaining.set(key, (remaining.get(key) || 0) + 1);
+    }
+    return (outputIssues || []).filter(issue => {
+        const key = issueKey(issue);
+        const count = remaining.get(key) || 0;
+        if (count === 0) return true;
+        remaining.set(key, count - 1);
+        return false;
+    });
+}
+
+export function validationErrors(issues = []) {
+    return (issues || []).filter(issue => issue?.severity === 'error');
+}