@ansonlai/docx-redline-js 0.5.4 → 0.6.0

package/ARCHITECTURE.md

@@ -69,7 +69,13 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 
 ## Entry Points
 
-- `index.js` (Root exports containing the reconciliation logic)
+- `index.js`: primary host-independent exports for OOXML reconciliation.
+- `services/standalone-operation-runner.js`: stable complete-document XML
+  operations, exported as `@ansonlai/docx-redline-js/standalone-runner`.
+- `node/index.js`: Node-only complete-DOCX buffer facade, exported as
+  `@ansonlai/docx-redline-js/node`.
+- `bin/docx-redline.js`: CLI launcher; command implementation lives in
+  `node/cli.js` and shared operation behavior lives in `services/`.
 
 ## Module Responsibilities
 
@@ -334,6 +340,12 @@ 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.
+- Target fingerprints are revision-view scoped. Inspection returns a
+  `revisionView` beside every paragraph and computes its fingerprint from the
+  same text/view pair. Restore normalization defaults omitted target and range
+  endpoint views to `rejected`; all other operations default to `accepted`.
+  Explicit views remain authoritative, and cross-view text/fingerprint mistakes
+  return an actionable mismatch hint rather than silently weakening targeting.
 - 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

package/CHANGELOG.md

@@ -9,9 +9,14 @@
 - **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.
+- **View-consistent restore targeting**: `restore` targets now default to the rejected view, where a wholly deleted paragraph's source text exists. Rejected-view inspection now computes fingerprints from rejected-view text and reports the view beside each paragraph. Explicit cross-view text or fingerprint mistakes retain strict refusal while returning an actionable view hint.
 
 ### New Features
 
+- **Batch-start source binding (WP-04)**: Strong document-operation targets are compiled once against the immutable source DOM and carried through structural index/fingerprint drift with rollback-aware session identities. Independent edits no longer need manual bottom-up sorting; same-source writes, incompatible revision/format combinations, and unsafe capture fan-out fail before mutation with causal conflict codes. Unique references to paragraph text created elsewhere in the same batch become explicit internal capture dependencies.
+- **Machine-actionable recovery (WP-05)**: Operation, package-facade, example-session, and compact CLI failures now carry recovery envelope version 1 with stable stage/category/action metadata, bounded corrective context, and authorization flags. Failed and partial mutation results include an explicit original-vs-output retry plan and operation indexes. `apply --require-complete` exits with code 3 for partial work while preserving legacy behavior without the flag.
+- **Compact shell-agent protocol (WP-06)**: CLI contract version 5 adds `operations-stdin` and `agent-profile-v1`. `--operations -` accepts UTF-8 operation arrays/envelopes without a temporary operations file, while explicit `--profile agent` combines atomic rollback and complete-success exit behavior and reports its effective settings. `AGENTS.md` is now a 527-word routing card, and the 349-word `docs/AGENT_FAST_START.md` carries the ordinary edit contract. Ambient project configuration was deliberately deferred because it would save only the profile flag while adding hidden state.
+- **Agent rollout audit (WP-07)**: The observational benchmark now compares canonical Node, legacy file-based CLI, compact stdin/profile CLI, and the development session example while verifying accepted/rejected text, comment preservation, independent batch permutations, recovery behavior, and cross-author attribution. The checked run records 82.75% fewer ordinary instruction words, one fewer shell tool turn (33.33%), and 82.22–89.96% smaller localized session requests than canonical Node envelopes without claiming unmeasured provider/model latency.
 - **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.

package/README.md

@@ -20,13 +20,45 @@ Converts AI-generated or programmatic text/markdown edits into valid Office Open
 - Zero host dependencies: works in Node.js, browsers, Deno, and similar JS runtimes with DOM parsing support
 ## Documentation Index
 
-| Document | Description |
-|---|---|
-| **[README.md](./README.md)** | Library overview, installation, quick start, and public API reference |
-| **[AGENTS.md](./AGENTS.md)** | AI coding agent quick reference, targeting rules, and complete CLI workflow |
+| Document | Description |
+|---|---|
+| **[README.md](./README.md)** | Library overview, installation, quick start, and public API reference |
+| **[docs/AGENT_FAST_START.md](./docs/AGENT_FAST_START.md)** | Compact ordinary-edit protocol for structured tools and shell-only agents |
+| **[AGENTS.md](./AGENTS.md)** | Short repository launch card for task routing and contributor verification |
+| **[docs/AGENT_KNOWLEDGE_BASE.md](./docs/AGENT_KNOWLEDGE_BASE.md)** | Full agent reference, CLI workflow, operation examples, error recovery, options, and gotchas |
 | **[ARCHITECTURE.md](./ARCHITECTURE.md)** | Contributor architecture, module responsibilities, end-to-end data flow, and contracts |
 | **[docs/TESTING.md](./docs/TESTING.md)** | Complete testing guide, test lanes, independent oracle validation, and Word visual review checklist |
-| **[CHANGELOG.md](./CHANGELOG.md)** | Release history, breaking changes, and migration notes |
+| **[CHANGELOG.md](./CHANGELOG.md)** | Release history, breaking changes, and migration notes |
+
+## Repository Layout
+
+The package exposes three levels of API:
+
+| Level | Entry point | Use it for |
+|---|---|---|
+| Host-independent OOXML API | `index.js` | Paragraph/range transforms and exported OOXML utilities in browsers, Node.js, or another DOM-capable runtime |
+| Standalone document XML runner | `services/standalone-operation-runner.js` | Applying operations to a complete `word/document.xml` string |
+| Node/DOCX API and CLI | `node/index.js`, `bin/docx-redline.js` | Reading, changing, validating, and writing complete `.docx` ZIP packages |
+
+Implementation folders have distinct roles: `core/` holds shared OOXML and
+targeting primitives; `pipeline/` handles ingestion, diffing, markdown, lists,
+and serialization; `engine/` performs reconciliation; `services/` coordinates
+document operations and package artifacts; `node/` contains Node-only ZIP and
+whole-document code. Tests are directly runnable `tests/*.mjs` files, while
+`tests/helpers/` and `tests/fixtures/` contain support code and data.
+
+Contributors and coding agents should start with the routing table in
+[AGENTS.md](./AGENTS.md#pick-the-route) before exploring the tree. The full
+dependency and ownership map is in [ARCHITECTURE.md](./ARCHITECTURE.md).
+
+For document-operation JSON, choose operations by the desired output structure,
+not by the everyday meaning of the type name. `redline` and `replace` provide
+ordinary text replacement; `list-change` and `table-reconciliation` provide
+structural intent; and ordinary `insert` is a compatibility alias of the
+redline path unless it includes a rejected-view target and anchor. In every
+ordinary text-bearing operation, `modified` is the complete desired content for
+the target. See the [operation model](./docs/AGENT_KNOWLEDGE_BASE.md#operation-model-choose-by-output-shape)
+and the [JSON schema](./docs/schemas/document-operations.schema.json).
 
 ## Install
 
@@ -128,15 +160,56 @@ const result = await document.applyOperations(operations, {
 const outputBuffer = result.toBuffer();
 ```
 
-The Node facade performs edits, artifact merges, package wiring, validation,
-and commit as one transaction. It defaults to strict targets and returns the
-untouched input with `written: false` on atomic failure. It is isolated from
-the root/browser dependency graph.
-
-Install `@xmldom/xmldom` alongside the package when using the Node facade or
-CLI; it remains an optional peer so browser consumers do not install a DOM shim.
-
-### Agent CLI
+The Node facade performs edits, artifact merges, package wiring, validation,
+and commit as one transaction. It defaults to strict targets and returns the
+untouched input with `written: false` on atomic failure. It is isolated from
+the root/browser dependency graph.
+
+Install `@xmldom/xmldom` alongside the package when using the Node facade or
+CLI; it remains an optional peer so browser consumers do not install a DOM shim.
+
+#### Example agent session wrapper (development only)
+
+[`examples/agent-session-wrapper.mjs`](./examples/agent-session-wrapper.mjs)
+demonstrates how a custom agent harness can keep one `DocxDocument` open, return
+short revision-bound target handles, apply safe defaults once, and translate a
+narrow edit request into canonical document operations:
+
+```js
+import { readFile } from 'node:fs/promises';
+import { createExampleAgentSession } from './examples/agent-session-wrapper.mjs';
+
+const session = createExampleAgentSession(await readFile('contract.docx'), {
+  profile: { author: 'Editor' }
+});
+const inspection = session.inspect({ search: 'termination', around: 2 });
+const clause = inspection.targets.find(target => target.role === 'match');
+const result = await session.applyEdits([{
+  target: clause.handle,
+  replacements: [{
+    find: 'The Company may terminate',
+    replace: 'Either party may terminate'
+  }]
+}]);
+```
+
+This file is a testable sample, not a package export or supported alternate
+mutation engine. It delegates to `@ansonlai/docx-redline-js/node`, is excluded
+from the published package files, and is intended to help MCP servers, Claude
+skills, OpenCode tools, and other custom harnesses design thin integrations.
+The sample binds each handle to the inspected package revision and view, returns
+new handles after successful mutations, and expands localized exact replacements
+into complete desired paragraph text before delegating to the canonical redline
+operation. Duplicate matches require an explicit `occurrence`; missing,
+ambiguous, overlapping, and conflicting patches fail before document mutation.
+From a source checkout, run `npm run benchmark:agent` to compare its native
+execution and serialized request size with a canonical stateless Node workflow.
+The example and its benchmark are excluded from the published package. The
+benchmark explicitly does not claim to measure LLM reasoning or provider/tool
+latency. Checked comparative results are in the
+[agent protocol rollout audit](./docs/validation-reports/2026-09-12-agent-protocol-rollout.md).
+
+### Agent CLI
 
 ```bash
 docx-redline extract contract.docx --range 10:30
@@ -155,21 +228,32 @@ docx-redline apply contract.docx --target "Typo fix" --modified "Fixed typo" --n
 # 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
+# High-assurance atomic batch with nonzero exit on any incomplete result
+docx-redline apply contract.docx --operations operations.json --atomic --require-complete --output reviewed.docx
+
+# Agent shell path: JSON is emitted by a serializer, not interpolated by the shell
+node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --output reviewed.docx
 ```
 
 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.
+- **Transactionality**: Defaults to `atomic: false` (applies valid operations and reports any failures). Pass `--atomic` for all-or-nothing rollback on any operation error.
+- **Complete-success exit**: Pass `--require-complete` when a progressive `partial` result must exit with code `3`; errors exit with code `2`. Without the flag, partial results retain the legacy zero exit code, so always inspect `completion`.
+- **Agent profile**: `--profile agent` explicitly enables atomic rollback and complete-success exit behavior while retaining strict targeting, validation, tracked changes, and `merge-same-author`. It reports the resolved `effectiveOptions`; explicit flags take precedence.
+- **Operations from stdin**: `--operations -` reads the same array or `{ operations, expectedRevision }` envelope accepted from a file. Feed it from a JSON serializer or structured process API, not shell-interpolated legal text.
 - **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.
 - **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.
+
+`docx-redline version` reports contract version 5 and the additive
+`batch-start-source-binding`, `recovery-envelope-v1`, and
+`require-complete-exit`, `operations-stdin`, and `agent-profile-v1`
+capabilities. Wrappers should negotiate only the capabilities they use.
 
-See [the agent workflow in AGENTS.md](./AGENTS.md#agent-document-workflow-cli) and the
-[operation JSON Schema](docs/schemas/document-operations.schema.json).
+See the [compact agent fast start](./docs/AGENT_FAST_START.md) and the
+[operation JSON Schema](docs/schemas/document-operations.schema.json).
 
 ### Configuration (call once at startup)
 
@@ -203,7 +287,7 @@ Common result fields:
 | Field | Purpose |
 |-------|---------|
 | `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`. |
+| `error` | Present on failure; retains a stable `code` and adds recovery envelope version, stage, category, bounded context, and a machine-readable recovery action. |
 | `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. |
@@ -369,7 +453,17 @@ import {
 import { getParagraphText } from '@ansonlai/docx-redline-js/core/paragraph-targeting.js';
 ```
 
-Use `applyOperationsToDocumentXml(...)` for mixed batches. It stably runs comments before text-changing operations so replacements cannot invalidate their original anchors. Other operation types retain their relative order. Batch results retain each operation's original 1-based index and expose the actual `executionOrder`.
+Use `applyOperationsToDocumentXml(...)` for mixed batches. It stably runs comments before text-changing operations so replacements cannot invalidate their original anchors. Other operation types retain their relative order. Batch results retain each operation's original 1-based index and expose the actual `executionOrder`.
+
+Before mutation, the runner resolves strong source descriptors against the
+immutable batch-start document and binds them to session-local source
+identities. Independent edits therefore do not need to be manually sorted when
+an earlier structural rewrite changes later paragraph indexes or fingerprints.
+Targets that deliberately refer to uniquely created paragraph text are compiled
+into an internal capture dependency. True overlap is not guessed: incompatible
+writes to one source fail before mutation with `OVERLAPPING_SOURCE_TARGETS` or
+`REVISION_ORDER_CONFLICT`, and mutating capture fan-out without distinct
+selectors fails with `CAPTURE_FANOUT_CONFLICT`.
 
 Threaded replies use a comment operation with no body target:
 
@@ -392,12 +486,23 @@ serialization. Accuracy remains the controlling constraint: each operation has
 an internal savepoint so an error or no-op cannot leak a partial edit or consumed
 revision ID into later operations.
 
-Batches are atomic by default: any operation error returns the original
-`documentXml`, `hasChanges: false`, empty package artifacts, and
-`rolledBack: true`. The default `continueOnError: true` still attempts the full
-batch so `results` describes what would have applied. Callers that intentionally
-consume partial results must pass `{ atomic: false }`; use
-`{ continueOnError: false }` to stop after the first error.
+Batches are progressive by default (`atomic: false`): valid operations commit
+while failed operations remain unapplied and are reported in `results`. Pass
+`{ atomic: true }` when any operation error must return the original
+`documentXml`, `hasChanges: false`, empty package artifacts, and
+`rolledBack: true`. The default `continueOnError: true` still attempts the full
+batch so `results` describes every operation; use `{ continueOnError: false }`
+to stop after the first error.
+
+Every failed or partial mutation includes `retryPlan`. Its `base` is `original`
+after rollback/no commit and `output` after a progressive partial commit;
+`committedIndexes`, `failedIndexes`, and `unattemptedIndexes` identify the safe
+replay scope. Errors use recovery envelope version 1 and always report
+`sameArgumentsSafe: false`. Follow `error.recovery.action`; do not infer a retry
+from prose. Authorization-sensitive actions, such as resolving comments, are
+marked with `requiresUserAuthorization: true`. For `EXISTING_REVISIONS`, the
+non-normalizing surgical recommendation is `slice-cross-author`; accepting or
+rejecting prior revisions still requires explicit authority.
 
 Comment anchors use exact matching first, then a unique ASCII-space/NBSP
 equivalent match that preserves source offsets and text. Missing anchors return
@@ -541,7 +646,8 @@ const restoration = await applyOperationToDocumentXml(
   documentXml,
   {
     type: 'restore',
-    target: { paragraphId: '1A2B3C4D', revisionView: 'rejected' },
+    // restore targets default to the rejected view, where deleted text exists
+    target: { paragraphId: '1A2B3C4D', exactText: 'Original deleted paragraph text.' },
     modified: 'Restored or adjusted paragraph text.'
   },
   'Editor'
@@ -551,6 +657,8 @@ const restoration = await applyOperationToDocumentXml(
 // restoration follows the complete deleted source block. Unchanged legacy
 // validation defects are retained as baseline issues; newly generated errors
 // fail closed before commit.
+// inspect/extract descriptors report their revisionView, and each fingerprint
+// is computed from the same view as exactText. Keep those fields together.
 
 // 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.
@@ -650,8 +758,10 @@ invariant with a fresh seed. See [Release validation in docs/TESTING.md](./docs/
 
 ## Architecture & Contributing
 
-- **[ARCHITECTURE.md](./ARCHITECTURE.md)**: Detailed module layout, end-to-end reconciliation flow, and contributor fast orientation.
-- **[AGENTS.md](./AGENTS.md)**: Concise quick reference for AI coding agents and CLI automation.
+- **[ARCHITECTURE.md](./ARCHITECTURE.md)**: Detailed module layout, end-to-end reconciliation flow, and contributor fast orientation.
+- **[AGENTS.md](./AGENTS.md)**: Fast-start routing and operational guardrails for AI coding agents.
+- **[docs/AGENT_FAST_START.md](./docs/AGENT_FAST_START.md)**: Minimal ordinary-edit contract for agent integrations.
+- **[docs/AGENT_KNOWLEDGE_BASE.md](./docs/AGENT_KNOWLEDGE_BASE.md)**: Full agent reference for APIs, operations, CLI automation, recovery, and gotchas.
 - **[docs/TESTING.md](./docs/TESTING.md)**: Comprehensive testing model, test lanes, independent oracle checks, and visual review checklist.
 - **[CHANGELOG.md](./CHANGELOG.md)**: Version history, migration guides, and deprecation schedules.
 

package/core/paragraph-targeting.js

@@ -424,9 +424,14 @@ export function resolveTargetParagraph(xmlDoc, options = {}) {
             );
         }
         if (descriptor.fingerprint && descriptor.fingerprint !== actualFingerprint) {
+            const alternateView = revisionView === 'rejected' ? 'accepted' : 'rejected';
+            const alternateFingerprint = createParagraphFingerprint(byId, { revisionView: alternateView });
+            const viewHint = descriptor.fingerprint === alternateFingerprint
+                ? ` The supplied fingerprint matches the ${alternateView} view; set target.revisionView to "${alternateView}" or use a fingerprint extracted from the ${revisionView} view.`
+                : '';
             throw createTargetError(
                 'TARGET_FINGERPRINT_MISMATCH',
-                `Target paragraphId "${descriptor.paragraphId}" no longer matches its source fingerprint.`,
+                `Target paragraphId "${descriptor.paragraphId}" no longer matches its source fingerprint.${viewHint}`,
                 cachedEntry ? [serializeTargetCandidate(cachedEntry)] : null
             );
         }
@@ -438,9 +443,16 @@ export function resolveTargetParagraph(xmlDoc, options = {}) {
             );
         }
         if (cleanTargetText && actualText !== normalizeWhitespaceForTargeting(cleanTargetText)) {
+            const alternateView = revisionView === 'rejected' ? 'accepted' : 'rejected';
+            const alternateText = normalizeWhitespaceForTargeting(
+                extractCanonicalParagraphText(byId, { revisionView: alternateView })
+            );
+            const viewHint = alternateText === normalizeWhitespaceForTargeting(cleanTargetText)
+                ? ` The supplied text matches the ${alternateView} view; set target.revisionView to "${alternateView}".`
+                : '';
             throw createTargetError(
                 'TARGET_TEXT_MISMATCH',
-                `Target paragraphId "${descriptor.paragraphId}" no longer matches the supplied text.`,
+                `Target paragraphId "${descriptor.paragraphId}" no longer matches the supplied text.${viewHint}`,
                 cachedEntry ? [serializeTargetCandidate(cachedEntry)] : null
             );
         }

package/dist/docx-redline-js.esm.js

@@ -1,4 +1,4 @@
-// @ansonlai/docx-redline-js v0.5.4 — https://github.com/AnsonLai/docx-redline-js
+// @ansonlai/docx-redline-js v0.6.0 — https://github.com/AnsonLai/docx-redline-js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -4890,6 +4890,47 @@ function extractFormattingFromOoxml(xmlDoc) {
   return { existingFormatHints, textSpans, paragraphs };
 }
 
+// core/revision-cloning.js
+var REVISION_HISTORY_ELEMENTS = /* @__PURE__ */ new Set([
+  "ins",
+  "del",
+  "moveFrom",
+  "moveTo",
+  "pPrChange",
+  "rPrChange",
+  "tblPrChange",
+  "trPrChange",
+  "tcPrChange",
+  "sectPrChange"
+]);
+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;
+}
+function refreshRunPropertyChangeIds(root, allocator = null) {
+  if (!root) return root;
+  const xmlDoc = root.nodeType === 9 ? root : root.ownerDocument;
+  const resolvedAllocator = allocator instanceof RevisionIdAllocator ? allocator : getRevisionIdAllocatorForDocument(xmlDoc) || createRevisionIdAllocator(xmlDoc);
+  const candidates = [root, ...Array.from(root.getElementsByTagName?.("*") || [])];
+  for (const node of candidates) {
+    if (!isWordElement(node, "rPrChange")) continue;
+    const nextId = String(resolvedAllocator.next());
+    if (typeof node.setAttributeNS === "function") {
+      node.setAttributeNS(NS_W, "w:id", nextId);
+    } else {
+      node.setAttribute("w:id", nextId);
+    }
+    resolvedAllocator._receiptCollector?.recordRevision(Number(nextId), "rPrChange");
+  }
+  return root;
+}
+
 // engine/run-builders.js
 function createTrackChange(xmlDoc, type, run, author, revisionMetadata = null) {
   const wrapper = createWordElement(xmlDoc, type === "ins" ? "w:ins" : "w:del");
@@ -5078,13 +5119,8 @@ function snapshotAndAttachRPrChange(xmlDoc, rPr, author, dateStr, sourceNode) {
   rPrChange.setAttribute("w:id", String(metadata.id));
   rPrChange.setAttribute("w:author", metadata.author);
   rPrChange.setAttribute("w:date", dateStr || metadata.date);
-  const previousRPr = createWordElement(xmlDoc, "w:rPr");
   const source = sourceNode || rPr;
-  Array.from(source.childNodes).forEach((child) => {
-    if (child.nodeName !== "w:rPrChange") {
-      previousRPr.appendChild(child.cloneNode(true));
-    }
-  });
+  const previousRPr = clonePropertiesWithoutRevisionHistory(source) || createWordElement(xmlDoc, "w:rPr");
   rPrChange.appendChild(previousRPr);
   const existing = getFirstElementByTag(rPr, "w:rPrChange");
   if (existing) {
@@ -5894,25 +5930,6 @@ function describeInsertionBoundary(spanIndex, pos, fallbackParagraph = null) {
   };
 }
 
-// core/revision-cloning.js
-function refreshRunPropertyChangeIds(root, allocator = null) {
-  if (!root) return root;
-  const xmlDoc = root.nodeType === 9 ? root : root.ownerDocument;
-  const resolvedAllocator = allocator instanceof RevisionIdAllocator ? allocator : getRevisionIdAllocatorForDocument(xmlDoc) || createRevisionIdAllocator(xmlDoc);
-  const candidates = [root, ...Array.from(root.getElementsByTagName?.("*") || [])];
-  for (const node of candidates) {
-    if (!isWordElement(node, "rPrChange")) continue;
-    const nextId = String(resolvedAllocator.next());
-    if (typeof node.setAttributeNS === "function") {
-      node.setAttributeNS(NS_W, "w:id", nextId);
-    } else {
-      node.setAttribute("w:id", nextId);
-    }
-    resolvedAllocator._receiptCollector?.recordRevision(Number(nextId), "rPrChange");
-  }
-  return root;
-}
-
 // engine/surgical-run-splitting.js
 var TRACK_CHANGE_CARRIERS = /* @__PURE__ */ new Set(["ins", "del"]);
 function getRunContentPieces(runElement) {
@@ -8415,6 +8432,51 @@ function getCommentIdsInOoxml(node) {
   }
   return [...ids].sort((a, b) => Number(a) - Number(b) || a.localeCompare(b));
 }
+function directWordChild(node, localName2) {
+  return Array.from(node?.childNodes || []).find((child) => child?.nodeType === 1 && child.namespaceURI === NS_W && child.localName === localName2) || null;
+}
+function insertedParagraphMarkMetadata(paragraph, author) {
+  const marker = directWordChild(directWordChild(directWordChild(paragraph, "pPr"), "rPr"), "ins");
+  if (!marker) return null;
+  const markerAuthor = marker.getAttribute("w:author") || marker.getAttributeNS(NS_W, "author") || "";
+  if (markerAuthor.trim().toLowerCase() !== String(author || "").trim().toLowerCase()) return null;
+  return {
+    id: marker.getAttribute("w:id") || marker.getAttributeNS(NS_W, "id") || "",
+    author: markerAuthor,
+    date: marker.getAttribute("w:date") || marker.getAttributeNS(NS_W, "date") || ""
+  };
+}
+function emptyParagraphBaseline(paragraph, serializer) {
+  const clone = paragraph.cloneNode(false);
+  const pPr = directWordChild(paragraph, "pPr");
+  if (pPr) clone.appendChild(clonePropertiesWithoutRevisionHistory(pPr));
+  return serializer.serializeToString(clone);
+}
+function restoreInsertedParagraphMark(oxml, metadata) {
+  if (!metadata || typeof oxml !== "string" || !oxml.trim()) return oxml;
+  const parsed = parseOoxmlSafe(oxml, "text/xml");
+  if (!parsed.doc || parsed.error) return oxml;
+  const paragraph = parsed.doc.documentElement?.localName === "p" ? parsed.doc.documentElement : getDocumentParagraphs(parsed.doc)[0];
+  if (!paragraph) return oxml;
+  let pPr = directWordChild(paragraph, "pPr");
+  if (!pPr) {
+    pPr = createWordElement(parsed.doc, "w:pPr");
+    paragraph.insertBefore(pPr, paragraph.firstChild);
+  }
+  let rPr = directWordChild(pPr, "rPr");
+  if (!rPr) {
+    rPr = createWordElement(parsed.doc, "w:rPr");
+    pPr.appendChild(rPr);
+  }
+  if (!directWordChild(rPr, "ins")) {
+    const marker = createWordElement(parsed.doc, "w:ins");
+    if (metadata.id) marker.setAttribute("w:id", metadata.id);
+    marker.setAttribute("w:author", metadata.author);
+    if (metadata.date) marker.setAttribute("w:date", metadata.date);
+    rPr.appendChild(marker);
+  }
+  return serializeXml(parsed.doc);
+}
 async function applyRedlineToOxml(oxml, originalText, modifiedText, options = {}) {
   const inputOoxml = oxml;
   let workingOoxml = oxml;
@@ -8426,6 +8488,7 @@ async function applyRedlineToOxml(oxml, originalText, modifiedText, options = {}
   let parseWarnings = [];
   const operationWarnings = [];
   let normalizedExistingRevisions = false;
+  let preservedInsertedParagraphMark = null;
   const existingRevisionsPolicy = options.existingRevisions || "merge-same-author";
   const keepNormalizedNoOp = existingRevisionsPolicy === "accept-all-first-keep-normalized";
   const finalize = (result) => {
@@ -8456,6 +8519,9 @@ async function applyRedlineToOxml(oxml, originalText, modifiedText, options = {}
     if (!withStatus.status) {
       withStatus.status = withStatus.hasChanges ? "ok" : "no-op";
     }
+    if (preservedInsertedParagraphMark && withStatus.hasChanges && typeof withStatus.oxml === "string") {
+      withStatus.oxml = restoreInsertedParagraphMark(withStatus.oxml, preservedInsertedParagraphMark);
+    }
     return withOoxmlSourceType(withStatus);
   };
   const finalizeUnchanged = () => {
@@ -8521,9 +8587,11 @@ async function applyRedlineToOxml(oxml, originalText, modifiedText, options = {}
           });
         }
         log("[OxmlEngine] Existing revisions from same author detected; rejecting previous changes to merge against baseline");
+        const soleParagraph = inputParagraphs.length === 1 ? inputParagraphs[0] : null;
+        preservedInsertedParagraphMark = insertedParagraphMarkMetadata(soleParagraph, author);
         const rejected = rejectTrackedChangesInOoxml(inputOoxml, { author });
         if (rejected.status === "error") return finalize(rejected);
-        workingOoxml = rejected.oxml;
+        workingOoxml = preservedInsertedParagraphMark && !String(rejected.oxml || "").trim() ? emptyParagraphBaseline(soleParagraph, serializer) : rejected.oxml;
         normalizedExistingRevisions = true;
         const rejectedParsed = parseOoxmlSafe(workingOoxml, "text/xml");
         parseWarnings.push(...rejectedParsed.warnings);
@@ -8565,7 +8633,9 @@ async function applyRedlineToOxml(oxml, originalText, modifiedText, options = {}
           status: "error",
           error: {
             code: "EXISTING_REVISIONS",
-            message: `Input OOXML contains tracked changes from another author (${authors.length ? authors.join(", ") : "unattributed"}). Pass existingRevisions: "accept-all-first" or resolve revisions first.`
+            message: `Input OOXML contains tracked changes from another author (${authors.length ? authors.join(", ") : "unattributed"}). Use existingRevisions: "slice-cross-author" for a surgical edit that preserves reviewer history; accepting or rejecting revisions requires separate authorization.`,
+            revisionAuthors: authors,
+            currentPolicy: existingRevisionsPolicy
           }
         });
       } else {
@@ -9173,9 +9243,12 @@ function resolveTargetParagraph(xmlDoc, options = {}) {
       );
     }
     if (descriptor.fingerprint && descriptor.fingerprint !== actualFingerprint) {
+      const alternateView = revisionView === "rejected" ? "accepted" : "rejected";
+      const alternateFingerprint = createParagraphFingerprint(byId, { revisionView: alternateView });
+      const viewHint = descriptor.fingerprint === alternateFingerprint ? ` The supplied fingerprint matches the ${alternateView} view; set target.revisionView to "${alternateView}" or use a fingerprint extracted from the ${revisionView} view.` : "";
       throw createTargetError(
         "TARGET_FINGERPRINT_MISMATCH",
-        `Target paragraphId "${descriptor.paragraphId}" no longer matches its source fingerprint.`,
+        `Target paragraphId "${descriptor.paragraphId}" no longer matches its source fingerprint.${viewHint}`,
         cachedEntry ? [serializeTargetCandidate(cachedEntry)] : null
       );
     }
@@ -9187,9 +9260,14 @@ function resolveTargetParagraph(xmlDoc, options = {}) {
       );
     }
     if (cleanTargetText && actualText !== normalizeWhitespaceForTargeting(cleanTargetText)) {
+      const alternateView = revisionView === "rejected" ? "accepted" : "rejected";
+      const alternateText = normalizeWhitespaceForTargeting(
+        extractCanonicalParagraphText(byId, { revisionView: alternateView })
+      );
+      const viewHint = alternateText === normalizeWhitespaceForTargeting(cleanTargetText) ? ` The supplied text matches the ${alternateView} view; set target.revisionView to "${alternateView}".` : "";
       throw createTargetError(
         "TARGET_TEXT_MISMATCH",
-        `Target paragraphId "${descriptor.paragraphId}" no longer matches the supplied text.`,
+        `Target paragraphId "${descriptor.paragraphId}" no longer matches the supplied text.${viewHint}`,
         cachedEntry ? [serializeTargetCandidate(cachedEntry)] : null
       );
     }
@@ -11403,9 +11481,10 @@ function inspectDocumentParts(parts, options = {}) {
   const resolveNumbering = createNumberingResolver(numberingPart.doc);
   let nearestHeading = null;
   const paragraphNodes = getDocumentParagraphNodes(documentPart.doc);
-  const commentAnchors = collectDocumentCommentAnchors(paragraphNodes, options.revisionView || "accepted");
+  const revisionView = options.revisionView === "rejected" ? "rejected" : "accepted";
+  const commentAnchors = collectDocumentCommentAnchors(paragraphNodes, revisionView);
   let paragraphs = paragraphNodes.map((paragraph, zeroIndex) => {
-    const text = extractCanonicalParagraphText(paragraph, { revisionView: options.revisionView || "accepted" });
+    const text = extractCanonicalParagraphText(paragraph, { revisionView });
     const level = headingLevel(paragraph);
     if (level) nearestHeading = { level, text };
     const ids = [...new Set([...descendants(paragraph, "commentRangeStart"), ...descendants(paragraph, "commentReference")].map((node) => attr2(node, "id")).filter(Boolean))];
@@ -11422,7 +11501,8 @@ function inspectDocumentParts(parts, options = {}) {
       index,
       ref: `P${index}`,
       paragraphId: getParagraphId2(paragraph),
-      fingerprint: createParagraphFingerprint(paragraph),
+      fingerprint: createParagraphFingerprint(paragraph, { text, index, revisionView }),
+      revisionView,
       text,
       exactText: text,
       excerpt: text.slice(0, options.excerptLength || 120),