@ansonlai/docx-redline-js 0.4.0 → 0.5.1

package/docs/plans/2026-09-05-structural-revisions-and-fidelity-oracles.md

@@ -0,0 +1,1669 @@
+# Structural Revisions, Stable Addressing, and Fidelity Oracles
+
+**Status:** Proposed — implementation-ready specification  
+**Date:** 2026-09-05  
+**Target releases:** v0.5.0–v1.0.0  
+**Priority:** Correct accepted/rejected results and document fidelity over throughput or review-pane cosmetics
+
+## 1. Purpose
+
+The package already performs surgical text redlining, paragraph-mark revision
+generation, tracked run formatting, structured-content planning, strict
+preflight, atomic live-DOM batches, and package validation. The next releases
+should harden and extend those capabilities without creating a second mutation
+model or weakening existing rollback and targeting guarantees.
+
+This plan focuses on the remaining gaps:
+
+1. Prove what is preserved before expanding mutation behavior.
+2. Give callers precise revision-view addressing without pretending that All
+   Markup is one unambiguous string.
+3. Make replacement metadata and insertion affinity explicit while preserving
+   structural containers.
+4. Complete paragraph-boundary and formatting-revision semantics already
+   partially implemented.
+5. Add package concurrency guards, dependent batch steps, and commit-aware
+   receipts.
+6. Promote strict application targeting only through a documented major-version
+   migration.
+
+The plan does not introduce an editor tree, layout engine, HTML round-trip, or
+second document authority. The OOXML package and the current live DOM remain
+authoritative.
+
+## 2. Current Baseline
+
+Before implementation, tests and documentation must acknowledge what exists.
+Treat these as foundations to extend, not greenfield work:
+
+- `engine/run-builders.js` creates `w:ins`, `w:del`, paragraph-mark revisions,
+  and `w:rPrChange` snapshots.
+- `services/revision-comment-management.js` accepts and rejects text, move,
+  paragraph-mark, and property-change revisions.
+- `core/paragraph-text.js` already extracts accepted and rejected revision
+  views.
+- `services/operation-preflight.js` is strict by default and reports ambiguous
+  targets and anchors.
+- The Node facade and CLI default to strict target application; the lower-level
+  application API remains permissive for compatibility.
+- `DocumentOperationSession` owns one live DOM and one document-scoped
+  `RevisionIdAllocator`, with per-operation DOM and allocator savepoints.
+- Batch execution uses an immutable start-of-batch target-reference snapshot,
+  comment-first scheduling, and one final serialization.
+- `planStructuredReplacement` validates headings, paragraphs, lists, and tables
+  before a large structural insertion is applied.
+- Word differential, visual, package, round-trip, and real-document tests are
+  already part of the verification stack.
+
+### Required baseline audit
+
+Create a short capability matrix before feature work begins. For each proposed
+behavior, label it `implemented`, `partial`, `missing`, or `intentionally
+unsupported`, and link the production code and regression test. At minimum the
+matrix must cover:
+
+- text insertion, deletion, and replacement;
+- paragraph insertion, deletion, split, and boundary removal;
+- run and paragraph property revisions;
+- hyperlinks, bookmarks, comments, fields, SDTs, tabs, breaks, and notes;
+- lists and table structural revisions;
+- accepted/rejected text extraction;
+- target resolution, batch savepoints, and package artifact wiring.
+
+No phase may duplicate an implemented path under a new option without a written
+migration and compatibility reason.
+
+## 3. Non-Negotiable Invariants
+
+### 3.1 Lifecycle correctness
+
+For every generated revision:
+
+- Accept All produces the requested final document.
+- Reject All restores the intended source document.
+- Selective author acceptance/rejection does not consume another author's work.
+- Repeating acceptance or rejection is idempotent.
+- Paragraph count, order, list membership, tables, comments, and section
+  ownership are checked in addition to plain text.
+
+### 3.2 Preservation envelope
+
+“Untouched” has three distinct meanings and must not be conflated:
+
+1. **Untouched package entry:** compare the uncompressed entry payload
+   byte-for-byte. ZIP container bytes are not expected to match after repacking.
+2. **Untouched subtree inside a modified XML part:** compare using a
+   namespace-aware canonical structural digest.
+3. **Intentionally modified region:** validate against an operation-specific
+   mutation envelope and lifecycle oracle.
+
+An operation must declare which XML nodes, ancestor containers, relationships,
+content types, and companion parts it is permitted to change. Unexpected drift
+outside that envelope fails the test.
+
+### 3.3 Structural safety over presentation heuristics
+
+Bookmarks, comment ranges, hyperlinks, fields, SDTs, proofing markers, drawings,
+and revision boundaries must not be moved or deleted merely to influence how
+Word groups a change in the Reviewing Pane.
+
+### 3.4 Refusal over guessing
+
+Ambiguous targets, anchors, capture selections, revision views, or structural
+ownership must produce structured errors. Fuzzy or first-match fallback is a
+legacy compatibility behavior, never an agent recommendation.
+
+### 3.5 One mutation authority
+
+All public package operations continue through the existing session, allocator,
+savepoint, artifact, and validation paths. New functionality must not introduce
+parallel ID allocation, string-only package mutation, or a second batch state.
+
+## 4. Compatibility Matrix
+
+| Initiative | Initial behavior | Classification | Default change |
+|---|---|---|---|
+| Fidelity and mutation-envelope oracles | Test-only | Non-breaking | None |
+| Explicit accepted/rejected addressing | Additive option; omitted means current behavior | Non-breaking | None |
+| Preserving existing revisions during addressed edits | New opt-in policy | Additive, high-risk | No automatic default |
+| Paired replacement metadata | Opt-in serialization policy | Observable semantic change | Consider only after Word evidence |
+| Explicit insertion affinity | Additive; omitted means legacy resolution | Non-breaking | No implicit `left` default |
+| Completed paragraph-boundary handling | New support for previously refused/fallback cases | Internal semantic change | Route only proven cases |
+| Author-aware formatting coalescing | Opt-in policy | Observable semantic change | Preserve current behavior initially |
+| Package revision token | Additive precondition | Non-breaking | No check when omitted |
+| Capture chaining | Additive batch feature | Non-breaking for independent batches | Dependency scheduling only when used |
+| Mutation receipts | Additive result field | Non-breaking | Existing result fields remain authoritative |
+| Strict lower-level application by default | Default behavior change | Breaking | v1.0.0 only |
+
+“Non-breaking” means more than an unchanged TypeScript signature. Changes to
+generated OOXML, formatting inheritance, accepted/rejected structure, revision
+count, author attribution, warnings, or Word presentation are observable and
+must be tested and documented.
+
+## 5. Milestone 0 — Fidelity Oracle Foundation
+
+**Target:** v0.5.0, before new mutation semantics  
+**Classification:** Non-breaking, test and validation infrastructure
+
+### 5.1 Part inventory and mutation envelopes
+
+Add a fixture helper that inventories every package entry and records:
+
+- entry URI and SHA-256 of its uncompressed bytes;
+- content type and relationship ownership;
+- XML root namespace and canonical digest for XML parts;
+- known volatile metadata that a test intentionally ignores.
+
+Each operation family declares allowed effects. Examples:
+
+- Text-only body edit: `word/document.xml` only.
+- List creation: document XML, numbering XML, numbering relationship, and
+  content type when absent.
+- Comment creation: document XML, comments XML, comments relationship, and
+  content type when absent.
+- Header edit: selected header part only, plus artifacts explicitly required by
+  that edit.
+
+The oracle must fail when an undeclared part changes, even if the resulting DOCX
+opens successfully.
+
+### 5.2 Canonical subtree comparison
+
+Do not implement canonicalization by simple prefix replacement. Use a proven XML
+canonicalization implementation where possible. If a local OOXML subset is
+necessary, it must:
+
+- compare expanded names, not literal prefixes;
+- sort attributes by namespace URI and local name;
+- retain child order;
+- preserve text, tabs, breaks, and `xml:space` semantics;
+- preserve or correctly rewrite QName-valued attributes such as
+  `mc:Ignorable`;
+- distinguish absent properties from explicit off-values when Word does;
+- normalize only syntax that is semantically equivalent.
+
+Untouched subtree identity cannot rely solely on `w14:paraId`: IDs may be absent
+or duplicated in real documents. Match nodes using a combination of stable IDs,
+canonical fingerprints, ancestor context, and ordered-neighbor evidence. Exclude
+the mutation target, its structurally affected ancestors, and any explicitly
+declared sibling boundary from the untouched set.
+
+### 5.3 Required oracles
+
+Add tests for:
+
+- accepted and rejected text and structure;
+- revision ID uniqueness across every revision element supported by validation;
+- comment and numbering artifact integrity;
+- untouched entry byte equality;
+- untouched subtree canonical equality;
+- save-and-reopen semantic equality;
+- no-op and atomic rollback returning the exact original XML/package bytes;
+- Word open, Accept All, Reject All, and save/reopen behavior.
+
+Reviewing Pane grouping is a visual compatibility observation, not a schema or
+lifecycle oracle.
+
+### Acceptance gate
+
+No later phase begins until representative paragraph, list, table, comment,
+header/footer, field, hyperlink, bookmark, drawing, and SDT fixtures pass the
+new preservation envelope.
+
+## 6. Milestone 1 — Revision-View Addressing
+
+**Target:** v0.5.0  
+**Classification:** Additive, with mutation support gated separately
+
+### 6.1 Use semantic view names
+
+Expose revision addressing as:
+
+```ts
+export type RevisionView = 'accepted' | 'rejected';
+
+export interface ParagraphTargetDescriptor {
+  exactText?: string;
+  paragraphId?: string;
+  index?: number;
+  occurrence?: number;
+  fingerprint?: string;
+  revisionView?: RevisionView; // Defaults to accepted/current behavior.
+}
+```
+
+Do not call accepted text “No Markup or Original.” Original/rejected and
+accepted/final are different views. Do not expose a single `tracked` string made
+by concatenating deleted and inserted text; a replacement has two overlapping
+histories, not one stable user-facing coordinate line.
+
+For inspection that needs revision history, return segments instead:
+
+```ts
+interface RevisionTextSegment {
+  text: string;
+  kind: 'baseline' | 'insertion' | 'deletion' | 'move_from' | 'move_to';
+  author?: string;
+  revisionId?: string;
+  acceptedStart: number | null;
+  rejectedStart: number | null;
+}
+```
+
+Offsets use JavaScript UTF-16 code units. DOM mapping must cover `w:t`,
+`w:delText`, tabs, breaks, carriage returns, soft/no-break hyphens, entities,
+and revision/move ancestry.
+
+### 6.2 Separate inspection from mutation policy
+
+Reading or locating text in a rejected view does not automatically authorize
+editing historical deletion markup. Initial scope:
+
+- Inspection and preflight support both views.
+- Comments may target a supported revision range only after schema and Word
+  round-trip fixtures prove the anchor representation.
+- Text mutation of another pending deletion or insertion is refused until an
+  explicit author-aware lifecycle policy exists.
+- The existing `reject-input` and `accept-all-first` policies remain unchanged.
+- If a future `preserve-input` policy is added, it must prohibit illegal nested
+  revisions and define same-author coalescing separately.
+
+### Acceptance criteria
+
+- The same descriptor resolves deterministically in accepted and rejected
+  views.
+- Duplicate text remains ambiguous within the selected view.
+- Emoji, entities, tabs, breaks, moves, and mixed insert/delete replacements map
+  to the correct DOM boundaries.
+- Omitting `revisionView` produces byte-for-byte current behavior.
+
+## 7. Milestone 2 — Replacement Pairing and Insertion Affinity
+
+**Target:** v0.5.0 experimental; stabilize in v0.6.0  
+**Classification:** Opt-in observable serialization behavior
+
+### 7.1 Paired replacement metadata
+
+Model a delete-followed-by-insert diff as one internal replacement event when
+both sides share a safe parent and no structural boundary must be crossed. The
+event allocates distinct revision IDs but may share one author and timestamp.
+
+```ts
+interface ReplacementRevisionEvent {
+  deletionId: string;
+  insertionId: string;
+  author: string;
+  date: string;
+}
+```
+
+Rules:
+
+- `w:del` and `w:ins` IDs remain distinct and document-scoped.
+- Shared metadata is allocated once for the event.
+- Empty runs created solely by splitting are removed.
+- `xml:space="preserve"` is based on emitted text boundaries; consecutive
+  interior spaces are also preserved defensively.
+- Pairing never crosses a hyperlink, field, SDT, comment, bookmark, move, or
+  incompatible revision parent.
+- Required structural markers may remain between changes. Fidelity wins over
+  visual grouping.
+- Word may present a paired event as a combined replacement, but the public API
+  does not guarantee a particular balloon shape.
+
+### 7.2 Separate formatting affinity from container affinity
+
+One `left | right` flag is insufficient for every boundary. Define:
+
+```ts
+interface InsertionAffinity {
+  formatting?: 'left' | 'right' | 'none';
+  hyperlink?: 'inside' | 'outside' | 'preserve';
+  revision?: 'coalesce_same_author' | 'separate';
+}
+```
+
+Bookmarks and comments are ranges represented by markers, not formatting
+wrappers. Their membership is determined by the insertion point relative to
+start/end markers and must be tested independently.
+
+When affinity is omitted, retain the existing boundary behavior. Do not claim
+that a universal implicit `left` policy matches Word in every container.
+
+### Acceptance criteria
+
+- Accepted and rejected content is identical with pairing enabled or disabled.
+- Pairing never removes or reorders structural markers.
+- Every formatting/hyperlink/comment/bookmark boundary combination has an
+  explicit expected DOM position.
+- Word-version visual fixtures record presentation differences without making
+  them correctness requirements.
+
+## 8. Milestone 3 — Complete Paragraph-Boundary Semantics
+
+**Target:** v0.6.0  
+**Classification:** Internal semantic change for newly supported cases
+
+The paragraph-mark primitives already exist. This phase completes the operation
+matrix and removes unsafe reconstruction only where native boundary revisions
+are proven.
+
+### 8.1 Boundary removal versus paragraph deletion
+
+These operations must remain distinct:
+
+1. **Remove the boundary between A and B while retaining both texts**
+   - Keep both physical paragraphs in the pending-revision document.
+   - Mark the paragraph mark ending A with `w:pPr/w:rPr/w:del`.
+   - Do not mark B's retained text as deleted.
+   - Accept joins the contents; Reject restores the boundary.
+2. **Delete Paragraph B and its text**
+   - Track B's content deletion.
+   - Track the relevant paragraph mark so Reject does not leave a ghost
+     paragraph, bullet, or number.
+   - Accept removes B; Reject restores B exactly.
+
+For boundary acceptance, do not assume that A's paragraph properties win. The
+remaining paragraph mark normally determines final paragraph formatting. Build
+native Word fixtures for conflicting A/B styles, numbering, spacing, and
+section properties, then encode the observed ownership rule before implementing
+the merge algorithm.
+
+### 8.2 Paragraph split
+
+When splitting A into A and B:
+
+- Split at a structurally safe run boundary.
+- Create B with the correct inherited paragraph properties.
+- Mark the newly inserted boundary—the paragraph mark ending A—with
+  `w:pPr/w:rPr/w:ins`.
+- Move retained trailing runs without incorrectly marking their text inserted.
+- Accept keeps A and B; Reject moves B's retained content back into A and
+  removes the inserted boundary.
+
+### 8.3 Unsafe cases
+
+Refuse or retain the current proven fallback when the boundary owns or crosses:
+
+- `w:sectPr` with uncertain ownership;
+- table-cell terminal paragraphs;
+- incompatible list definitions;
+- overlapping bookmarks/comments;
+- fields, SDTs, drawings, notes, or unsupported revision nesting.
+
+### Acceptance criteria
+
+- A full matrix covers split, join, delete, list-item insertion/deletion, and
+  boundaries adjacent to structural content.
+- Word and internal Accept All/Reject All agree on paragraph order, text,
+  paragraph properties, numbering, and section ownership.
+- Existing paragraph-mark regression tests remain valid and are expanded rather
+  than replaced.
+
+## 9. Milestone 4 — Complete Tracked Formatting Semantics
+
+**Target:** v0.6.0  
+**Classification:** Existing behavior plus opt-in author-aware coalescing
+
+`w:rPrChange` generation and property-change lifecycle handling already exist.
+This phase closes coverage gaps and defines a public formatting operation model.
+
+### 9.1 Operation contracts
+
+Distinguish character and paragraph formatting:
+
+```ts
+interface CharacterFormatOperation {
+  type: 'format';
+  target: ParagraphTargetDescriptor;
+  textToFormat: string;
+  properties: {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+    highlight?: string | null;
+  };
+}
+
+interface ParagraphFormatOperation {
+  type: 'paragraph-format';
+  target: ParagraphTargetDescriptor;
+  properties: {
+    alignment?: 'left' | 'center' | 'right' | 'both';
+    keepNext?: boolean;
+    keepLines?: boolean;
+    pageBreakBefore?: boolean;
+  };
+}
+```
+
+The property set may expand only with prior-state snapshot and lifecycle tests.
+The previous-state child of `w:rPrChange` or `w:pPrChange` contains the complete
+direct property state required to reverse the change, excluding nested change
+records.
+
+### 9.2 Author-aware policy
+
+Preserve current formatting revision behavior by default. Add an experimental
+policy only after selective-author tests:
+
+```ts
+formattingRevisionPolicy?: 'always' | 'coalesce-own-insertion';
+```
+
+- `always`: current behavior; create the appropriate property revision.
+- `coalesce-own-insertion`: formatting inside the active author's pending
+  insertion updates that insertion directly.
+- Formatting baseline text or another author's insertion creates a separate
+  property revision attributed to the active author.
+
+### Acceptance criteria
+
+- Bold/italic/underline/strike/highlight on/off transitions round-trip.
+- Paragraph-property changes round-trip independently of run properties.
+- Same-author and different-author pending insertions are tested separately.
+- Run splitting never duplicates an existing `w:rPrChange` ID.
+- Omitting the new policy retains current serialized behavior.
+
+## 10. Milestone 5 — Versioned Concurrency Tokens
+
+**Target:** v0.7.0  
+**Classification:** Additive precondition
+
+### 10.1 Two token scopes
+
+Do not describe a three-part hash as a complete package revision.
+
+```ts
+interface RevisionToken {
+  algorithm: 'sha256';
+  version: 1;
+  scope: 'document-parts' | 'package';
+  value: string;
+}
+```
+
+- `document-parts`: hash a documented, sorted list of provided part names and
+  exact strings/bytes. Suitable for lower-level APIs.
+- `package`: hash every relevant ZIP entry name plus its uncompressed bytes.
+  Suitable for `openDocx` and CLI workflows.
+
+Use length-prefixed binary framing so part boundaries cannot collide. Include
+the token version and scope in the digest input. A package token necessarily
+requires reading the ZIP directory and selected entries; it can still reject
+before any mutation is staged.
+
+### 10.2 Check location
+
+- Inspection returns the token and the covered part list.
+- Apply recomputes it from the exact incoming state before creating mutation
+  savepoints or package artifacts.
+- Mismatch returns `REVISION_MISMATCH`, `hasChanges: false`, no artifacts, and
+  the original bytes.
+- A token from one scope cannot satisfy another scope.
+
+### Acceptance criteria
+
+- Changes to document text, comments, numbering, relationships, headers,
+  footers, styles, notes, or media are detected by the package token.
+- ZIP recompression without uncompressed entry changes does not invalidate a
+  package token.
+- Omitted preconditions preserve current behavior.
+
+## 11. Milestone 6 — Dependency-Aware Capture Chaining
+
+**Target:** v0.7.0  
+**Classification:** Additive batch behavior when captures are used
+
+### 11.1 Contract
+
+```json
+[
+  {
+    "operationId": "insert-privacy-section",
+    "type": "replace",
+    "target": { "exactText": "11. Term and Termination" },
+    "modified": "11. Term and Termination\n\n12. Data Privacy\nService Provider shall maintain the required controls.",
+    "structuredContent": true,
+    "captureKey": "privacy-section"
+  },
+  {
+    "operationId": "comment-controls",
+    "type": "comment",
+    "target": {
+      "captureRef": "privacy-section",
+      "select": "required controls"
+    },
+    "commentContent": "Confirm the evidence and audit cadence."
+  }
+]
+```
+
+### 11.2 Dependency scheduling
+
+Build a dependency graph before execution:
+
+- A `captureRef` depends on the operation exporting its `captureKey`.
+- Reject duplicate keys, missing references, forward references not resolvable
+  by the graph, and cycles.
+- Preserve source order among independent operations.
+- Retain comment-first scheduling only when it does not violate dependencies.
+- `executionOrder` reports actual topological order.
+
+Static preflight reports capture-dependent targets as `deferred`, not missing.
+An optional mutation preview may execute against an isolated clone to resolve
+all dynamic selections without committing output.
+
+### 11.3 Stable capture representation
+
+Do not store raw DOM nodes as the durable capture value. Savepoint restoration
+replaces the DOM tree and invalidates those references. A capture records a
+serializable session-local identity:
+
+```ts
+interface CapturedEntity {
+  captureKey: string;
+  operationIndex: number;
+  kind: 'paragraph' | 'range' | 'table' | 'list';
+  generatedParagraphIds: string[];
+  fingerprints: string[];
+  expectedText: string[];
+  structuralPathHints: string[];
+}
+```
+
+Resolution reacquires nodes from the current session index and verifies text and
+fingerprint before mutation. The capture table participates in every savepoint:
+failed/no-op steps restore its exact prior state, and atomic rollback discards it.
+If a captured entity is replaced later, the executor must either update the
+capture deterministically or return `CAPTURE_STALE`.
+
+### 11.4 Structured insertion guidance
+
+Large generated content must be analyzed before execution:
+
+1. Run `planStructuredReplacement`.
+2. Refuse malformed tables or ambiguous block boundaries.
+3. Emit separate heading, paragraph, list, and table nodes.
+4. Capture block identities, not a flattened combined string.
+5. Apply dependent comments or formatting only after those nodes exist.
+
+### Acceptance criteria
+
+- Insert-then-comment and insert-then-format work in one atomic batch.
+- Independent comments retain current comment-first safety.
+- Savepoint restoration never leaves stale node references or captures.
+- Failure of a dependent step rolls back the entire atomic batch and all
+  artifacts.
+
+## 12. Milestone 7 — Commit-Aware Mutation Receipts
+
+**Target:** v0.7.0  
+**Classification:** Additive result metadata
+
+Receipts describe both what was attempted and what survived the transaction:
+
+```ts
+interface MutationReceipt {
+  operationIndex: number;
+  operationId?: string;
+  attemptedDisposition: 'applied' | 'no_change' | 'refused' | 'not_attempted';
+  finalDisposition: 'applied' | 'no_change' | 'refused' | 'rolled_back' | 'not_attempted';
+  committed: boolean;
+  authorUsed?: string;
+  revisionItems: Array<{
+    id: string;
+    kind: 'ins' | 'del' | 'move_from' | 'move_to' | 'rPrChange' | 'pPrChange' | 'structural';
+    partName: string;
+  }>;
+  commentIds: string[];
+  numberingIds: string[];
+  relationshipIds: string[];
+  affectedTargets: ResolvedDocumentTarget[];
+  warnings: string[];
+}
+```
+
+Rules:
+
+- Existing result fields and status strings remain unchanged.
+- Collectors are scoped to the operation savepoint.
+- IDs consumed by a failed/no-op step are absent after restore.
+- A later atomic failure changes earlier provisional receipts to
+  `finalDisposition: 'rolled_back'` and `committed: false`.
+- No IDs are presented as durable handles unless the transaction commits.
+- Receipt generation must not add paragraph IDs or otherwise mutate the
+  document solely for telemetry.
+
+### Acceptance criteria
+
+- Receipts enumerate exact committed revision, comment, numbering, and
+  relationship allocations.
+- No-op, refusal, stopped execution, per-step rollback, and whole-batch rollback
+  are distinguishable.
+- Receipt contents agree with a fresh parse of the committed package.
+
+## 13. Milestone 8 — Strict Application Migration
+
+**Target:** warning cycle in v0.7.x; default change in v1.0.0  
+**Classification:** Breaking default change
+
+Preflight is already strict by default, and the Node facade/CLI already prefer
+strict application. The remaining migration concerns callers of permissive
+lower-level application APIs.
+
+### Migration
+
+- v0.7.x: ambiguous permissive resolution succeeds only where legacy behavior
+  currently permits it and emits `AMBIGUOUS_TARGET_HEURISTIC_USED`.
+- Documentation and generated agent examples always use strict application.
+- v1.0.0: lower-level application defaults to strict.
+- An explicit `strictTargets: false` compatibility escape hatch may remain for
+  one major release, with warnings.
+
+Strict descriptors are conjunctive assertions, not a priority list: when both
+`paragraphId` and `exactText` are supplied, both must describe the same current
+target. An index or occurrence alone is not a concurrency guarantee.
+
+### Acceptance criteria
+
+- Zero, duplicate, descriptor-conflict, stale fingerprint, and anchor ambiguity
+  have distinct errors and candidate diagnostics.
+- Preflight and strict application resolve the same target or both refuse.
+- CLI and Node package workflows never silently choose candidate one.
+
+## 14. Verification Matrix
+
+Every milestone runs:
+
+```bash
+npm test
+npm run test:isolation
+npm run check:types
+node scripts/export-validation-fixtures.mjs
+```
+
+Risk-specific gates:
+
+| Change | Required additional verification |
+|---|---|
+| Canonical fidelity | New fidelity-oracle suite plus real package corpus |
+| Revision addressing | Accepted/rejected view, entity, Unicode, move, and mixed-revision fixtures |
+| Pairing/affinity | Hyperlink, field, SDT, bookmark, comment, and multi-author fixtures |
+| Paragraph boundaries | Internal round trip plus desktop Word Accept/Reject and visual review |
+| Formatting revisions | Selective-author Accept/Reject and complete previous-state snapshots |
+| Concurrency tokens | Entry mutation/recompression/token-version matrix |
+| Capture chaining | Dependency graph, savepoint, stale capture, and atomic rollback matrix |
+| Receipts | Fresh-package audit of every reported committed ID |
+
+Desktop Word automation proves open/save and accepted/rejected outcomes. Visual
+inspection remains required for layout, paragraph marks, change bars, and
+Reviewing Pane presentation because those UI details are not fully exposed as a
+stable COM assertion surface.
+
+## 15. Release Sequence
+
+### v0.5.0 — Evidence and addressing
+
+- Current-capability audit.
+- Mutation envelopes and fidelity oracles.
+- Accepted/rejected revision-view inspection and targeting.
+- Experimental paired replacement metadata and explicit insertion affinity.
+
+### v0.6.0 — Structural lifecycle completion
+
+- Proven paragraph boundary join/split/delete cases.
+- Complete character and paragraph formatting revision contracts.
+- Expanded selective-author and native Word lifecycle fixtures.
+
+### v0.7.0 — Transactional agent workflows
+
+- Versioned document/package concurrency tokens.
+- Dependency-aware capture chaining.
+- Commit-aware mutation receipts.
+- Permissive-target deprecation warnings.
+
+### v1.0.0 — Strict defaults
+
+- Strict lower-level application by default.
+- Compatibility flags and deprecated helpers reviewed under normal semver rules.
+- Full fidelity, lifecycle, package, and Word validation gates required for
+  release.
+
+## 16. Exit Criteria
+
+This program is complete when:
+
+1. Every claimed existing and new capability has production-code and regression-
+   test evidence.
+2. Every operation declares and stays within its mutation envelope.
+3. Accepted and rejected results match internal and desktop Word outcomes for
+   text and structure.
+4. Large structured insertions remain headings, paragraphs, lists, and tables
+   rather than flattened text.
+5. Dependent batch steps use stable captures and preserve atomic rollback.
+6. Receipts never report rolled-back IDs as committed.
+7. Stale package mutations fail before document state is changed.
+8. Ambiguous agent operations fail closed under all recommended public workflows.
+
+## 17. Coding-Agent Execution Protocol
+
+This section is normative. An implementation agent should follow it even when a
+work package appears simple.
+
+### 17.1 Unit of work
+
+Implement exactly one work package from Section 18 at a time. Do not combine
+unrelated packages, opportunistically refactor adjacent modules, or change a
+default before the package that explicitly authorizes that change.
+
+For each work package:
+
+1. Read `AGENTS.md`, `ARCHITECTURE.md`, `docs/TESTING.md`, and every production
+   file listed under **Files to inspect**.
+2. Run the listed baseline tests before editing. If they fail, record the
+   pre-existing failure and stop unless the task explicitly includes repairing
+   it.
+3. Add the smallest failing regression test that expresses the requested
+   invariant.
+4. Implement through existing helpers and session state. Do not create a second
+   parser, allocator, target resolver, or package writer.
+5. Run the focused tests, then the shared gates in Section 17.5.
+6. Update public declarations, schemas, README, architecture, testing guidance,
+   and changelog only when the work package changes those contracts.
+7. Report files changed, tests run, compatibility impact, and any deferred
+   unsafe cases.
+
+### 17.2 Mutation rules
+
+- Create Word elements through `createWordElement`.
+- Create revision metadata through the document-scoped allocator path already
+  used by `createRevisionMetadata` and `RevisionIdAllocator`.
+- Never allocate revision IDs with module globals, timestamps, random numbers,
+  or a fresh per-operation allocator inside a batch.
+- Mutate the live session DOM. String serialization is a boundary operation,
+  not a mutation technique.
+- Retain per-operation DOM, allocator, runtime-context, artifact, capture, and
+  receipt savepoints.
+- Never move or delete unknown OOXML merely because the current renderer ignores
+  it.
+- Preserve source whitespace exactly. Replacement text is caller data and must
+  not be trimmed, collapsed, Markdown-normalized, or line-ending-normalized.
+- Keep accepted/rejected text extraction centralized in
+  `core/paragraph-text.js`.
+- Keep target selection centralized in `core/paragraph-targeting.js` and
+  `services/operation-preflight.js`.
+- Keep package mutations in the Node/package layer. Browser-safe root imports
+  must not acquire Node built-ins.
+
+### 17.3 Error behavior
+
+Expected refusal is not an exception. Return the established error shape:
+
+```ts
+{
+  hasChanges: false,
+  status: 'error',
+  error: {
+    code: 'STABLE_MACHINE_CODE',
+    message: 'Actionable human-readable explanation.'
+  }
+}
+```
+
+An atomic batch failure additionally returns the original document, empty
+uncommitted artifacts, `rolledBack: true`, and per-operation attempt results.
+Never convert a structured refusal into `no_change`.
+
+New error codes introduced by this plan:
+
+| Code | Meaning |
+|---|---|
+| `UNSUPPORTED_REVISION_VIEW_MUTATION` | Requested view can be inspected but not safely mutated |
+| `UNSAFE_REVISION_NESTING` | Mutation would create unsupported nested/overlapping revisions |
+| `UNSUPPORTED_INSERTION_AFFINITY` | Requested container placement is not legal or deterministic |
+| `UNSAFE_PARAGRAPH_BOUNDARY` | Split/join crosses unsupported structural ownership |
+| `REVISION_MISMATCH` | Expected package/document token does not match current state |
+| `REVISION_TOKEN_SCOPE_MISMATCH` | Token scope/version cannot guard the selected API |
+| `DUPLICATE_CAPTURE_KEY` | More than one step exports the same capture key |
+| `CAPTURE_NOT_FOUND` | No step exports the requested capture |
+| `CAPTURE_DEPENDENCY_CYCLE` | Capture dependencies cannot be topologically ordered |
+| `AMBIGUOUS_CAPTURE_SELECTION` | `select` matches multiple locations inside a capture |
+| `CAPTURE_STALE` | Captured identity no longer resolves to the verified current entity |
+
+Add codes to runtime validation, TypeScript declarations, JSON schema, README,
+and tests in the same work package that first emits them.
+
+### 17.4 Public-contract propagation checklist
+
+For every public option, operation field, result field, or error payload, inspect
+and update all applicable surfaces:
+
+- `index.js` and `index.d.ts`;
+- `services/document-operation-contract.js`;
+- `services/standalone-operation-runner.d.ts`;
+- `docs/schemas/document-operations.schema.json`;
+- `node/docx-document.js`;
+- CLI parsing/help/examples;
+- `README.md`, `ARCHITECTURE.md`, `docs/AGENT-WORKFLOW.md`,
+  `docs/TESTING.md`, and `CHANGELOG.md`;
+- contract, schema, package facade, CLI, and type-export tests.
+
+Do not update only the JavaScript implementation and leave declarations or the
+operation schema behind.
+
+### 17.5 Shared verification gates
+
+Run these after every work package:
+
+```bash
+npm test
+npm run test:isolation
+npm run check:types
+```
+
+Run these when OOXML generation or package plumbing changes:
+
+```bash
+node scripts/export-validation-fixtures.mjs
+docx-redline validate <representative-output.docx>
+```
+
+Run the relevant Word differential suite before completing any work package that
+changes paragraph marks, revision wrappers, run properties, numbering, tables,
+comments, relationships, or content types. Visual suites require human review of
+the generated evidence; successful rendering alone is not visual approval.
+
+## 18. Ordered Implementation Work Packages
+
+### WP-00 — Capability and Gap Audit [COMPLETED 2026-09-05]
+
+**Depends on:** None  
+**Produces runtime changes:** No  
+**Status:** Completed — audit matrix published at `docs/plans/structural-revision-capability-matrix.md` with all 67 baseline test suites verified passing.
+
+**Files to inspect**
+
+- `engine/run-builders.js`
+- `engine/surgical-run-splitting.js`
+- `engine/surgical-diff-application.js`
+- `engine/reconstruction-mode.js`
+- `pipeline/list-generation.js`
+- `pipeline/structured-content.js`
+- `core/paragraph-text.js`
+- `core/paragraph-targeting.js`
+- `services/document-operation-session.js`
+- `services/batch-operation-orchestrator.js`
+- `services/revision-comment-management.js`
+- `services/operation-preflight.js`
+- `node/docx-document.js`
+
+**Steps**
+
+1. Create `docs/plans/structural-revision-capability-matrix.md`.
+2. Add one row for every behavior named in Section 2.
+3. For each row, record status, production symbol, existing test, missing case,
+   and proposed work package.
+4. Mark a capability `implemented` only when generation, validation, Accept All,
+   and Reject All are covered.
+5. Mark behavior that exists only for lists or only for whole-paragraph deletion
+   as `partial`, not implemented.
+6. Record current serialized output for one canonical fixture per partial area.
+
+**Tests**
+
+No new test is required, but all tests linked from the matrix must be executed.
+
+**Done when**
+
+No later work package describes existing behavior as absent, and every claimed
+gap has a reproducible fixture or test.
+
+### WP-01 — Package Part Inventory Helper [COMPLETED 2026-09-05]
+
+**Depends on:** WP-00  
+**Produces runtime changes:** No; test helper only  
+**Status:** Completed — helper implemented in `tests/helpers/package-fidelity.mjs`, verified by `tests/package_fidelity_inventory_tests.mjs`.
+
+**Files to inspect**
+
+- `node/zip-archive.js`
+- `services/package-builder.js`
+- `services/standalone-docx-plumbing.js`
+- existing ZIP/package transaction tests
+
+**New files**
+
+- `tests/helpers/package-fidelity.mjs`
+- `tests/package_fidelity_inventory_tests.mjs`
+
+**Algorithm**
+
+1. Read every ZIP entry as its uncompressed byte payload.
+2. Normalize entry names to OPC forward-slash form; reject duplicate normalized
+   names.
+3. Sort by entry name for reporting only. Never treat archive order, compression
+   method, CRC field position, or ZIP timestamps as content.
+4. Return `{ entries: Map<name, { size, sha256, bytes }> }`.
+5. Provide `comparePackageEntries(before, after, allowedChangedEntries)`.
+6. Fail with a report containing unexpected changed, added, and removed entries.
+7. Do not silently ignore `docProps`, relationships, media, content types, or
+   custom XML.
+
+**Required tests**
+
+- Recompressing identical entries produces no content differences.
+- One-byte payload changes are detected.
+- Added and removed entries are reported separately.
+- Duplicate normalized paths are refused.
+- Binary media is compared without text decoding.
+
+**Done when**
+
+The helper can prove exact untouched entry payload preservation without claiming
+the entire ZIP byte stream remains identical.
+
+### WP-02 — OOXML Canonical Subtree Helper [COMPLETED 2026-09-05]
+
+**Depends on:** WP-01  
+**Produces runtime changes:** No; test helper only  
+**Status:** Completed — canonical XML helper implemented in `tests/helpers/canonical-ooxml.mjs` supporting QName-valued attribute canonicalization, verified by `tests/canonical_ooxml_tests.mjs`.
+
+**Files to inspect**
+
+- `adapters/xml-adapter.js`
+- `core/word-xml.js`
+- `core/xml-query.js`
+- fixtures containing `mc:Ignorable`, alternate prefixes, drawings, and SDTs
+
+**New files**
+
+- `tests/helpers/canonical-ooxml.mjs`
+- `tests/canonical_ooxml_tests.mjs`
+
+**Steps**
+
+1. Evaluate an existing standards-compliant canonicalization dependency before
+   writing custom logic. Do not add a dependency without documenting bundle and
+   browser impact.
+2. Represent element and attribute names as `{ namespaceURI, localName }`.
+3. Preserve element child order and exact character data.
+4. Canonicalize namespace declarations without breaking QName-valued attribute
+   contents.
+5. Treat comments and processing instructions consistently and document whether
+   they participate in the digest.
+6. Return both canonical bytes and SHA-256 so failures can print a readable
+   canonical diff.
+
+**Required tests**
+
+- Different harmless prefixes compare equal.
+- Different attribute orders compare equal.
+- Different child orders compare unequal.
+- `w:b` absent and `w:b w:val="0"` compare unequal.
+- Leading/trailing spaces and `xml:space` differences compare unequal when they
+  change Word text semantics.
+- `mc:Ignorable` remains bound to the intended namespace prefixes.
+
+**Stop condition**
+
+If QName-valued attributes cannot be canonicalized safely, limit the first
+oracle to exact serialized subtree bytes and document the limitation. Do not
+ship a prefix-replacement approximation as canonical XML.
+
+### WP-03 — Mutation Envelope Registry and Fidelity Suite [COMPLETED 2026-09-05]
+
+**Depends on:** WP-01, WP-02  
+**Produces runtime changes:** No unless a discovered fidelity bug is separately scoped  
+**Status:** Completed — mutation envelopes registry implemented in `tests/helpers/mutation-envelopes.mjs`, verified against the multi-feature fixture matrix in `tests/fidelity_oracle_tests.mjs`.
+
+**New files**
+
+- `tests/helpers/mutation-envelopes.mjs`
+- `tests/fidelity_oracle_tests.mjs`
+
+**Steps**
+
+1. Define envelopes by operation kind and structural route: surgical text,
+   reconstruction, list, structured content, table reconciliation, comment,
+   highlight, accept/reject, and package plumbing.
+2. Each envelope lists allowed part changes and affected subtree classes.
+3. Capture before-state entry hashes and candidate subtree identities.
+4. Apply exactly one operation.
+5. Reopen the output package before measuring after-state.
+6. Compare untouched package entries exactly.
+7. Reacquire untouched subtrees using IDs plus fingerprints and ordered context.
+8. Compare their canonical digests.
+9. Run internal Accept All and Reject All and compare expected structure.
+10. Emit a diagnostic that names the first unexpected entry or subtree.
+
+**Required fixture matrix**
+
+- normal paragraph surrounded by untouched paragraphs;
+- hyperlink and bookmark adjacent to an edit;
+- comment range adjacent to an edit;
+- field-code paragraph;
+- drawing and image relationship;
+- SDT containing text;
+- numbered and bulleted lists;
+- existing table and newly inserted Markdown table;
+- header, footer, footnote, and endnote package parts;
+- documents with and without comments/numbering parts.
+
+**Done when**
+
+The suite passes current behavior or produces separately tracked fidelity bugs.
+Do not weaken an envelope merely to make a failure disappear.
+
+### WP-04 — Revision-View Segment Extraction [COMPLETED 2026-09-05]
+
+**Depends on:** WP-03  
+**Produces runtime changes:** Additive inspection API  
+**Status:** Completed — implemented `extractParagraphRevisionSegments` in `core/paragraph-text.js`, wired `segments` into `inspectDocumentParts` in `services/document-inspection.js`, exported types in `index.d.ts` and `index.js`, and verified by `tests/revision_view_segment_tests.mjs`.
+
+**Files to edit**
+
+- `core/paragraph-text.js`
+- `services/document-inspection.js`
+- public exports and declarations from Section 17.4
+
+**New tests**
+
+- `tests/revision_view_segment_tests.mjs`
+
+**Algorithm**
+
+1. Add one depth-first paragraph walker that emits structural text pieces.
+2. Track ancestors for `ins`, `del`, `moveFrom`, and `moveTo`.
+3. Emit text for `w:t`, `w:delText`, tabs, breaks, carriage returns,
+   soft hyphens, and no-break hyphens.
+4. Compute accepted and rejected visibility using the existing canonical rules.
+5. Maintain accepted and rejected UTF-16 cursors independently.
+6. For a hidden segment, store `null` for that view's start.
+7. Merge adjacent pieces only when kind, author, revision ID, and DOM carrier are
+   compatible.
+8. Reimplement existing accepted/rejected string extraction as a projection of
+   the walker, or prove parity before retaining both implementations.
+
+**Required assertions**
+
+- Concatenating accepted-visible segments equals current accepted extraction.
+- Concatenating rejected-visible segments equals current rejected extraction.
+- Entity decoding does not alter DOM offsets.
+- An emoji counts as two UTF-16 code units.
+- A replacement exposes deletion and insertion as separate segments, never as
+  one concatenated “tracked” word.
+- Move revisions map consistently with existing accept/reject behavior.
+
+**Compatibility gate**
+
+Existing extraction output must be byte-for-byte unchanged for all current
+fixtures.
+
+### WP-05 — Revision-View Target Resolution [COMPLETED 2026-09-05]
+
+**Depends on:** WP-04  
+**Produces runtime changes:** Additive target option for inspection/preflight  
+**Status:** Completed — implemented revisionView-aware caching and conjunctive descriptor resolution in `core/paragraph-targeting.js`, validation in `services/document-operation-contract.js`, preflight multi-view support in `services/operation-preflight.js`, mutation refusal with `UNSUPPORTED_REVISION_VIEW_MUTATION` in `services/document-operation-applier.js`, JSON schema updates, and verified by `tests/revision_view_target_tests.mjs`.
+
+**Files to edit**
+
+- `core/paragraph-targeting.js`
+- `services/operation-preflight.js`
+- `services/document-operation-contract.js`
+- public contract surfaces from Section 17.4
+
+**Steps**
+
+1. Add `revisionView` validation with only `accepted` and `rejected` values.
+2. Build or cache paragraph metadata per revision view; never reuse accepted
+   text for rejected matching.
+3. Resolve all supplied descriptor fields conjunctively.
+4. Calculate `occurrence` within the selected view.
+5. Include the selected view in candidate diagnostics and fingerprints.
+6. Restrict the initial implementation to inspection and preflight.
+7. If apply receives `revisionView: 'rejected'`, return
+   `UNSUPPORTED_REVISION_VIEW_MUTATION` until WP-06 explicitly supports that
+   operation kind.
+
+**Required tests**
+
+- Same phrase at different accepted/rejected locations.
+- Phrase exists only in an insertion.
+- Phrase exists only in a deletion.
+- Duplicate phrase in one view but unique in the other.
+- Descriptor fields disagree despite one individually matching.
+- Invalid view is rejected by runtime contract and JSON schema.
+
+### WP-06 — Existing-Revision Mutation Policy [COMPLETED 2026-09-05]
+
+**Depends on:** WP-05  
+**Produces runtime changes:** Opt-in only  
+**Status:** Completed — implemented policy matrix: allow schema-valid comments inside pending insertions across same and different authors with selective accept/reject preservation; refuse deletion comments, cross-container comment ranges, and deletion/move replacements with `UNSAFE_REVISION_NESTING`; refuse pending insertion replacements with `EXISTING_REVISIONS`; verified by `tests/existing_revision_mutation_policy_tests.mjs`.
+
+**Goal**
+
+Decide which mutations can safely preserve existing revisions. Do not add a
+general `preserve-input` switch until the matrix below is implemented.
+
+**Policy matrix to implement and test**
+
+| Existing content | Same author | Different author | Initial action |
+|---|---:|---:|---|
+| Baseline text | n/a | n/a | Normal tracked mutation |
+| Pending insertion, comment only | Yes | Yes | Allow if comment range is schema-valid |
+| Pending insertion, text replacement | Yes | No | Refuse initially; later consider same-author coalescing |
+| Pending deletion, comment only | Yes | Yes | Refuse until native Word fixture proves representation |
+| Pending deletion, text replacement | Yes | No | Refuse with `UNSAFE_REVISION_NESTING` |
+| Move source/destination | Any | Any | Refuse until move-specific lifecycle is designed |
+
+**Steps**
+
+1. Generate native Word fixtures for every proposed allowed case.
+2. Inspect exact OOXML before copying the pattern.
+3. Add schema, Word open/save, selective-author Accept/Reject, and internal
+   lifecycle tests.
+4. Add only narrowly named policies for proven cases.
+5. Retain current `reject-input` default.
+
+**Stop condition**
+
+If internal and Word selective-author outcomes differ, keep the case refused.
+
+### WP-07 — Replacement Event Metadata [COMPLETED 2026-09-05]
+
+**Depends on:** WP-03  
+**Produces runtime changes:** Opt-in paired metadata  
+**Status:** Completed — implemented opt-in `pairReplacements` with shared author/timestamp metadata, distinct document-allocated revision IDs, structural boundary safety fallback emitting `PAIRING_SKIPPED_STRUCTURAL_BOUNDARY`, lifecycle equivalence, schema and type declarations, and verified by `tests/replacement_event_metadata_tests.mjs`.
+
+**Files to inspect/edit**
+
+- `engine/surgical-diff-application.js`
+- `engine/surgical-run-splitting.js`
+- `engine/run-builders.js`
+- `core/types.js`
+- `core/redline-validation.js`
+
+**Steps**
+
+1. Identify delete/insert token pairs before either wrapper is created.
+2. Confirm both sides can be emitted under the same legal parent.
+3. Allocate one event author/date and two unique revision IDs.
+4. Pass explicit metadata into builders; do not call the clock independently for
+   each half.
+5. Remove only empty runs introduced by the current split operation.
+6. Preserve all pre-existing zero-width structural nodes in their original order.
+7. Fall back to independent revisions when safe adjacency is impossible.
+8. Return a warning such as `PAIRING_SKIPPED_STRUCTURAL_BOUNDARY` only when the
+   caller explicitly requested pairing.
+
+**Tests**
+
+- Plain run replacement receives identical author/date and distinct IDs.
+- Accepted/rejected output matches independent mode.
+- Replacement across two formatting runs retains both formats.
+- Hyperlink, comment, bookmark, field, SDT, and existing-revision boundaries
+  trigger safe fallback without node movement.
+- Multiple replacements in one operation receive separate event pairs.
+- Validation rejects duplicate revision IDs.
+
+**Word evidence**
+
+Record Word version, build, platform, displayed revision count, and screenshots.
+Do not encode “one balloon” as a cross-version API guarantee.
+
+### WP-08 — Insertion Affinity [COMPLETED 2026-09-05]
+
+**Depends on:** WP-07  
+**Produces runtime changes:** Additive explicit option  
+**Status:** Completed — implemented `InsertionAffinity` (`formatting`, `hyperlink`, `revision`, `bookmark`, `comment`), `describeInsertionBoundary` descriptor, strict validation returning `UNSUPPORTED_INSERTION_AFFINITY` for illegal positions, exact legacy fallback when omitted, schema and type declarations, and verified by `tests/insertion_affinity_tests.mjs`.
+
+**Files to inspect/edit**
+
+- `engine/surgical-spans.js`
+- `engine/surgical-run-splitting.js`
+- `engine/surgical-diff-application.js`
+- hyperlink/bookmark/comment targeting helpers
+
+**Steps**
+
+1. Create an internal boundary descriptor containing left/right carrier runs and
+   all open/closing structural boundaries at the insertion point.
+2. Apply formatting affinity independently from hyperlink/revision affinity.
+3. Treat bookmark and comment range markers as ordered boundaries, not wrappers.
+4. Validate requested affinity before mutation.
+5. If the requested placement is illegal or ambiguous, return
+   `UNSUPPORTED_INSERTION_AFFINITY`.
+6. When omitted, call the exact legacy path.
+
+**Minimum test grid**
+
+For insertion at the start and end of each structure, test left/right formatting
+and legal inside/outside placement:
+
+- normal to bold run;
+- paragraph start/end with no carrier on one side;
+- hyperlink;
+- bookmark range;
+- comment range;
+- field begin/separate/end sequence;
+- SDT content;
+- same-author insertion;
+- different-author insertion.
+
+Assert exact parent, sibling order, inherited `w:rPr`, accepted/rejected text,
+and preservation of every range marker.
+
+### WP-09 — Paragraph Boundary Fixture Matrix
+
+**Depends on:** WP-03  
+**Produces runtime changes:** No; fixture/oracle work  
+**Status:** Completed — generated 10 Word-native golden fixture triples (30 DOCX files and 30 extracted XML parts in `tests/fixtures/paragraph-boundaries/`) covering split, boundary deletion, middle paragraph deletion, blank paragraph insertion, style boundaries, list levels, section breaks, table cells, bookmarks/comments, and multi-author revisions using desktop Word COM automation (`scripts/generate-paragraph-boundary-fixtures.ps1`). Validated all 10 fixtures and codified the empirical ownership rules in `tests/paragraph_boundary_matrix_tests.mjs`.
+
+**New files**
+
+- `tests/fixtures/paragraph-boundaries/`
+- `tests/paragraph_boundary_matrix_tests.mjs`
+- `scripts/generate-paragraph-boundary-fixtures.ps1`
+
+**Fixture creation**
+
+Use desktop Word to create golden examples for:
+
+- split one paragraph in the middle;
+- delete only the boundary between two paragraphs;
+- delete an entire middle paragraph;
+- insert a blank paragraph;
+- boundaries between different paragraph styles;
+- boundaries with different list levels/numIds;
+- boundary before a section break;
+- first/last paragraph in a table cell;
+- adjacent bookmark/comment ranges;
+- same-author and multi-author revisions.
+
+For every golden fixture, save pending, accepted, and rejected copies. Extract
+the relevant XML and record which paragraph owns the inserted/deleted mark and
+which `w:pPr` survives acceptance.
+
+**Done when**
+
+The ownership rules are evidence, not assumptions in prose:
+1. **Paragraph Split**: Paragraph A owns the inserted paragraph mark (`w:pPr/w:rPr/w:ins`), Paragraph B contains the moved runs without false insertion wrappers; on rejection, Paragraph B content is folded back into Paragraph A and Paragraph B is removed.
+2. **Boundary Deletion**: Paragraph A owns the deleted paragraph mark (`w:pPr/w:rPr/w:del`), Paragraph B's content is untouched in pending state; on acceptance, Paragraph A's contents are prepended into Paragraph B, Paragraph A is removed, and Paragraph B's properties survive (with any style inheritance tracked via `w:pPrChange`); on rejection, Paragraph A's deleted mark is removed and both paragraphs remain distinct.
+3. **Paragraph Deletion**: The deleted paragraph owns both its paragraph mark deletion (`w:pPr/w:rPr/w:del`) and text deletions (`w:del/w:r/w:delText`). On acceptance, the paragraph is removed; on rejection, the paragraph and its runs are restored intact.
+4. **Section Breaks**: Embedded in `w:pPr/w:sectPr`; deleting the break marks the paragraph mark ending Paragraph A deleted.
+5. **Table Cells**: Cell terminal paragraph constraints must be preserved; internal cell paragraph boundary deletions follow the standard merge.
+6. **Bookmarks and Comments**: Range start and end markers are retained within their respective paragraph nodes across boundary revisions.
+
+### WP-10 — Paragraph Boundary Implementation [COMPLETED 2026-09-05]
+
+**Depends on:** WP-09  
+**Produces runtime changes:** New proven structural routes  
+**Status:** Completed — implemented structural paragraph boundary mutations (split, join, blank and whole-paragraph deletions) with explicit schema safeguards (refusing sole table cell paragraph deletion, cross-cell joins, section break paragraph deletion, field instruction splits, open bookmark splits returning `UNSAFE_PARAGRAPH_BOUNDARY`). Verified across 11 unit tests in `tests/paragraph_boundary_implementation_tests.mjs`, all 10 Word-native golden fixture tests in `tests/paragraph_boundary_matrix_tests.mjs`, and full regression/fuzz suites (77/77 test suites passing).
+
+**Files to inspect/edit**
+
+- `engine/reconstruction-mode.js`
+- `engine/reconstruction-writer.js`
+- `engine/run-builders.js`
+- `services/revision-comment-management.js`
+- `services/document-operation-mutations.js`
+
+**Implementation order**
+
+1. Boundary removal retaining both texts.
+2. Paragraph split retaining all source text.
+3. Entire paragraph deletion.
+4. Blank paragraph insertion/deletion.
+5. List paragraph cases.
+6. Only then consider section/table-cell cases supported by WP-09 evidence.
+
+**Boundary removal algorithm**
+
+1. Resolve adjacent A/B paragraphs under the same legal parent.
+2. Verify no unsupported boundary ownership.
+3. Mark the paragraph mark ending A as deleted.
+4. Leave B text active and in B while the revision is pending.
+5. On acceptance, merge using the golden-fixture property ownership rule.
+6. On rejection, remove only the boundary deletion marker.
+
+**Split algorithm**
+
+1. Resolve a safe UTF-16 split boundary using surgical span mapping.
+2. Clone only the paragraph properties proven to transfer.
+3. Move trailing retained nodes into B without wrapping them as inserted text.
+4. Mark the paragraph mark ending A as inserted.
+5. On rejection, move retained B content back into A in exact order and remove B.
+
+**Required safeguards**
+
+- Never create an empty numbered/bulleted ghost paragraph after Reject All.
+- Never place `w:sectPr` on both paragraphs.
+- Never split a field instruction or move only one bookmark/comment boundary.
+- Preserve tabs, breaks, hyperlinks, drawings, and SDTs as nodes.
+- Return `UNSAFE_PARAGRAPH_BOUNDARY` before mutation for unsupported cases.
+
+### WP-11 — Formatting Contract Completion [COMPLETED 2026-09-05]
+
+**Depends on:** WP-03, WP-06  
+**Produces runtime changes:** Additive operations; current default retained  
+**Status:** Completed — implemented explicit character-format (`format`, `character-format`) and paragraph-format (`paragraph-format`) operations with tracked revisions (`w:rPrChange`, `w:pPrChange`), schema ordering (`RPR_SCHEMA_ORDER`, `PPR_SCHEMA_ORDER`), direct prior state snapshots excluding nested change records, fresh ID preservation on run clones, author-aware coalescing policy (`coalesce-own-insertion`), and no-op handling without ID consumption. Verified in `tests/formatting_contract_tests.mjs` and all 78 test suites.
+
+**Files to inspect/edit**
+
+- `engine/format-application.js`
+- `engine/formatting-removal.js`
+- `engine/run-builders.js`
+- `engine/rpr-helpers.js`
+- `services/document-operation-contract.js`
+- `services/revision-comment-management.js`
+
+**Steps**
+
+1. Inventory current Markdown format hints and highlight behavior.
+2. Define explicit character-format and paragraph-format operations in runtime,
+   declarations, and schema.
+3. Split only the requested character span.
+4. Snapshot complete direct prior properties without nested change records.
+5. Apply explicit on/off properties in schema order.
+6. Generate one property change per resulting changed carrier.
+7. Preserve fresh unique IDs when a run containing history is cloned.
+8. Implement paragraph `w:pPrChange` generation separately from run formatting.
+9. Add author-aware coalescing only after the WP-06 selective-author policy
+   permits it.
+
+**Tests**
+
+- Every supported property: absent→on, on→off, and value→different value.
+- Partial-run and multi-run spans.
+- Character style plus direct formatting.
+- Existing `w:rPrChange` and `w:pPrChange` history.
+- Same/different author pending insertion.
+- Accept/reject one author while retaining another's property change.
+- No requested property change returns `no_change` without consuming an ID.
+
+### WP-12 — Revision Token Core [COMPLETED 2026-09-05]
+
+**Depends on:** WP-01  
+**Produces runtime changes:** Additive inspection utility  
+**Status:** Completed — implemented binary framing revision token generator in `services/revision-token.js` (`buildRevisionTokenFraming`, `computeRevisionToken`, `computeRevisionTokenSync`, `computeDocumentPartsRevisionToken`, `validateRevisionToken`), package-scoped token computation in `node/docx-document.js` (`computePackageRevisionToken`, `DocxDocument.prototype.getRevisionToken`, `DocxDocument.prototype.revisionToken`), integrated into `inspectDocumentParts`, browser-safe with 0 Node imports in root graph, verified in `tests/revision_token_tests.mjs` and all 79 test suites.
+
+**New/edited files**
+
+- `services/revision-token.js` or an equivalently focused leaf module
+- `services/document-inspection.js`
+- `node/docx-document.js`
+- browser/root dependency isolation tests
+
+**Binary framing**
+
+Hash this conceptual sequence using UTF-8 names and raw payload bytes:
+
+```text
+magic = "docx-redline-revision-token\0"
+version = uint32be(1)
+scopeLength + scope
+entryCount
+for each entry sorted by normalized name:
+  nameLength + name
+  payloadLength + payload
+```
+
+Use fixed-width unsigned big-endian lengths or another unambiguous documented
+encoding. Reject duplicate normalized entry names. The browser implementation
+may use Web Crypto asynchronously; the Node package path may use `node:crypto`
+behind a Node-only module. Do not import Node crypto from the browser-safe root
+graph.
+
+**Tests**
+
+- Stable across ZIP compression/order/timestamp changes.
+- Changes when any entry name or payload changes.
+- Stable regardless of Map/object enumeration order.
+- Different scope or version produces a different token.
+- Binary zero bytes and non-ASCII entry names frame correctly.
+
+### WP-13 — Revision Token Enforcement [COMPLETED 2026-09-05]
+
+**Depends on:** WP-12  
+**Produces runtime changes:** Additive apply precondition  
+**Status:** Completed — added `expectedRevision` precondition support across package facade (`DocxDocument.prototype.applyOperations`), batch runner (`applyOperationsToDocumentXml`), single-op runner (`applyOperationToDocumentXml`), CLI (`--expected-revision` and JSON file wrapper), and document-operations schema. Validates token syntax, enforces scope isolation (`REVISION_TOKEN_SCOPE_MISMATCH`), timing-safe token equality comparison with `areRevisionTokensEqual`, structured rejection with `REVISION_MISMATCH` before mutating state or creating artifacts in both atomic and non-atomic modes. Verified in `tests/revision_token_enforcement_tests.mjs` and all 80 test suites.
+
+**Steps**
+
+1. Add `expectedRevision` to package and applicable lower-level options.
+2. Validate token syntax, version, algorithm, and scope before comparison.
+3. Recompute from the exact input supplied to apply.
+4. Perform comparison before creating session mutations or companion artifacts.
+5. Use a timing-safe equality primitive where available; correctness must not
+   depend on it.
+6. Return `REVISION_TOKEN_SCOPE_MISMATCH` for incompatible scopes and
+   `REVISION_MISMATCH` for unequal valid tokens.
+7. Ensure atomic and non-atomic modes both leave input untouched on mismatch.
+
+**Tests**
+
+- Matching token applies.
+- Stale token refuses.
+- Token from another document refuses.
+- Parts token cannot guard package API and vice versa.
+- No operation result or artifact is partially produced.
+- Omitting the option follows the byte-for-byte legacy path.
+
+### WP-14 — Capture Contract and Dependency Graph [COMPLETED 2026-09-05]
+
+**Depends on:** WP-05  
+**Produces runtime changes:** Validation and scheduling for capture batches  
+**Status:** Completed — added `operationId`, `captureKey`, `target.captureRef`, and `target.select` to document operation contract, TypeScript declarations, and JSON schema. Implemented `buildOperationDependencyPlan` performing Kahn topological sort with comment priority among ready nodes, duplicate key detection (`DUPLICATE_CAPTURE_KEY`), missing producer detection (`CAPTURE_NOT_FOUND`), and cycle detection (`CAPTURE_DEPENDENCY_CYCLE`). Integrated dependency graph planning into `applyOperationsToDocumentXml` and `orderOperationsForStableTargets`. Updated `preflightOperations` to validate dependency graph and mark capture consumers as `status: 'deferred'` without searching static DOM. Ensured batch `results` remain sorted by original operation index while `executionOrder` reports actual execution order. Verified in `tests/capture_dependency_graph_tests.mjs` and all 81 test suites.
+
+**Files to inspect/edit**
+
+- `services/document-operation-contract.js`
+- `services/operation-preflight.js`
+- `services/batch-operation-orchestrator.js`
+- public contract surfaces from Section 17.4
+
+**Steps**
+
+1. Validate `operationId`, `captureKey`, and `target.captureRef` as non-empty,
+   bounded strings.
+2. Build `captureKey -> source operation index`.
+3. Reject duplicates and missing producers.
+4. Add dependency edges from consumer to producer.
+5. Perform a stable topological sort using original operation index as the tie
+   breaker.
+6. Apply existing comment-first priority only among currently ready independent
+   nodes.
+7. Detect cycles before constructing `DocumentOperationSession` mutations.
+8. Preflight static targets immediately and mark capture consumers `deferred`.
+
+**Tests**
+
+- Linear dependency, diamond dependency, independent comments, duplicate key,
+  missing producer, self-cycle, multi-node cycle, and stable tie order.
+- `results` remain sorted by original index while `executionOrder` reports actual
+  execution.
+- Batches without capture fields preserve current scheduling exactly.
+
+### WP-15 — Capture Storage, Resolution, and Savepoints [COMPLETED 2026-09-05]
+
+**Depends on:** WP-14  
+**Produces runtime changes:** Capture execution  
+**Status:** Completed — added `captureTable` to `DocumentOperationSession` with savepoint clone/restore and atomic rollback clearing. Implemented `deriveCapturedEntity`, `invalidateAffectedCaptures`, and `resolveTargetFromCapture` in `services/capture-engine.js`. Wired capture resolution and live/removed mutation node tracking into `services/document-operation-mutations.js` and `services/document-operation-applier.js`. Verified all 10 required routes (plain paragraph, structured content, lists, tables, producer no-ops, producer failures, consumer rollback, staleness detection, ambiguous selection, non-atomic isolation) in `tests/capture_resolution_tests.mjs` and all 82 test suites.
+
+**Files to inspect/edit**
+
+- `services/document-operation-session.js`
+- `services/document-operation-applier.js`
+- `services/document-operation-mutations.js`
+- structured/list/table replacement paths
+
+**Steps**
+
+1. Add `captureTable` to the session.
+2. Clone/restore it with every savepoint.
+3. After a successful changed producer, derive captures from the actual imported
+   live-DOM nodes—not from the requested text alone.
+4. Store serializable identity evidence; do not store raw nodes across
+   savepoints.
+5. Reacquire candidates from the current paragraph/table index.
+6. Verify fingerprints and expected text before resolving `select`.
+7. Require a unique `select` match within the capture.
+8. Invalidate or deterministically update captures affected by later structural
+   replacement.
+9. Discard all captures on atomic rollback.
+
+**Required route tests**
+
+- Plain paragraph insertion → comment.
+- Structured heading/paragraph insertion → comment.
+- List insertion → format one item.
+- Table insertion → target one cell only if the capture schema supports cells.
+- Producer no-op, producer failure, consumer failure, stale capture, ambiguous
+  selection, and later replacement of captured content.
+
+### WP-16 — Receipt Collector [COMPLETED 2026-09-05]
+
+**Depends on:** WP-03  
+**Produces runtime changes:** Internal telemetry collector  
+**Status:** Completed — added `ReceiptCollector` in `services/receipt-collector.js` owned by `DocumentOperationSession` with savepoint snapshots and restore. Instrumented `core/types.js` (`createRevisionMetadata`, `createReplacementRevisionEvent`), `engine/run-builders.js` (`createTrackChange`, `markParagraphMark`, `snapshotAndAttachRPrChange`, `snapshotAndAttachPPrChange`), `engine/reconstruction-writer.js`, `engine/table-mode.js`, `pipeline/serialization.js`, `services/comment-engine.js`, `services/document-operation-mutations.js`, `services/batch-operation-orchestrator.js`, and `services/standalone-docx-plumbing.js` to record revisions, comments, numbering, relationships, and targets directly at point of allocation/attachment. Verified via `tests/receipt_collector_tests.mjs` and all 83 test suites.
+
+**Files to inspect/edit**
+
+- `core/types.js`
+- revision builders
+- comment engine
+- numbering helpers
+- package relationship/content-type helpers
+- `services/document-operation-session.js`
+
+**Steps**
+
+1. Add a session-owned collector with `beginOperation(index)`, record methods,
+   `commitOperation()`, and `restore(savepoint)`.
+2. Record IDs at the successful allocation/attachment point, not by reparsing a
+   partially serialized string.
+3. Associate every item with kind and part name.
+4. Snapshot collector state in operation savepoints.
+5. Ensure failed/no-op allocations disappear on restore.
+6. Keep the collector internal until WP-17 proves reconciliation with output.
+
+**Tests**
+
+- Text replacement records distinct deletion/insertion IDs.
+- Formatting records property-change IDs.
+- Comment/list/package plumbing records companion IDs.
+- Failed and no-op operations leave collector state unchanged.
+
+### WP-17 — Public Commit-Aware Receipts
+
+**Depends on:** WP-16  
+**Produces runtime changes:** Additive result field  
+**Status:** Completed — added `MutationReceipt` and `MutationReceiptRevisionItem` interfaces to types/index. Instrumented batch orchestrator and single-operation applier to attach receipts to every item result and top-level batch results (`receipts`). Implemented output reconciliation via `reconcileReceiptsAgainstOutput` verifying all committed IDs are present in serialized XML or failing the transaction. Supported atomic rollback marking prior items `rolled_back` with `committed: false`. Added `tests/mutation_receipt_tests.mjs` verifying all required test cases. All 84 test suites pass.
+
+**Steps**
+
+1. Convert internal collector records to the receipt schema in Section 12.
+2. Attach provisional receipts to item results.
+3. At successful transaction commit, set applied receipts `committed: true`.
+4. On atomic rollback, rewrite every provisionally applied receipt to
+   `finalDisposition: 'rolled_back'` and `committed: false`.
+5. Mark unexecuted steps `not_attempted` when `continueOnError: false`.
+6. Reopen committed output and reconcile every reported durable ID.
+7. If reconciliation fails, treat it as a transaction error rather than return
+   inaccurate telemetry.
+
+**Tests**
+
+- Successful atomic and non-atomic batches.
+- Early stop and continue-on-error.
+- Later failure rolling back earlier success.
+- Mixed text/comment/list/table/format operations.
+- Existing IDs are never incorrectly reported as newly allocated.
+
+### WP-18 — Strict Application Warning Cycle
+
+**Depends on:** WP-05  
+**Produces runtime changes:** Warning only before v1.0.0  
+**Status:** Completed — added `AMBIGUOUS_TARGET_HEURISTIC_USED` warning in `core/paragraph-targeting.js` triggered only when permissive resolution chooses among multiple identical candidate paragraphs. Integrated candidate count and migration guidance into warnings in `document-operation-applier.js`, `batch-operation-orchestrator.js`, and `operation-preflight.js`. Updated `README.md`, `AGENTS.md`, `ARCHITECTURE.md`, and `CHANGELOG.md` with migration guidance and strict descriptor examples. Created `tests/strict_application_warning_tests.mjs` verifying all warning cycle invariants. All 85 test suites pass.
+
+**Steps**
+
+1. Identify every public application entry point and its current strict default.
+2. Add a warning only when permissive resolution actually chooses among multiple
+   candidates—not merely when `strictTargets: false` is present.
+3. Include candidate count and migration guidance without exposing document
+   content beyond existing diagnostics policy.
+4. Ensure preflight and strict application share the same candidate resolver.
+5. Update recommended examples to strict descriptors.
+
+**v1.0.0 task**
+
+Change the remaining permissive defaults only in a dedicated major-version
+work package. Update semver notes, migration examples, and compatibility tests at
+that time; do not silently make the change during v0.x implementation.
+
+## 19. Test Fixture Naming and Assertions
+
+Use names that state the invariant, not the implementation. Examples:
+
+- `paragraph-boundary-join-retains-second-text`
+- `paragraph-split-reject-restores-source-properties`
+- `replacement-pair-preserves-comment-boundary`
+- `rejected-view-target-is-ambiguous`
+- `capture-savepoint-reacquires-current-node`
+- `atomic-receipt-marks-prior-success-rolled-back`
+
+Every structural fixture should assert at least:
+
+1. operation status and error code;
+2. generated revision element location and unique IDs;
+3. exact accepted text;
+4. exact rejected text;
+5. accepted paragraph/table/list structure;
+6. rejected paragraph/table/list structure;
+7. preservation of nearby unknown/structural nodes;
+8. validation result;
+9. package artifact presence/absence;
+10. no unexpected mutation-envelope drift.
+
+Avoid assertions that merely search the serialized XML for a tag. Parse the
+output and assert parent, child, sibling order, namespace, attributes, and
+affected text. Regex assertions may supplement but not replace DOM assertions.
+
+## 20. Implementation Reporting Template
+
+The implementing agent should finish each work package with this report:
+
+```text
+Work package: WP-XX — Name
+Outcome: complete | partial | blocked
+
+Behavior implemented:
+- ...
+
+Compatibility:
+- Public API change: ...
+- Default behavior change: none | ...
+- Serialized OOXML change: none | ...
+
+Files changed:
+- path — purpose
+
+Tests added:
+- test — invariant
+
+Verification run:
+- command — result
+
+Deferred or refused cases:
+- case — reason and error code
+
+Manual Word evidence:
+- not required | artifact path and review status
+```
+
+Do not report a work package complete when focused tests pass but shared gates,
+package validation, required Word evidence, declarations, schemas, or docs remain
+unfinished.