@ansonlai/docx-redline-js 0.4.0 → 0.5.1

package/ARCHITECTURE.md

@@ -12,6 +12,7 @@ This repository contains only the publishable package surface:
 - `pipeline/`
 - `services/`
 - `orchestration/`
+- `node/` (separate Node-only package facade)
 - `index.js`
 - `index.d.ts`
 - `dist/`
@@ -35,6 +36,7 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 │   ├── logger.js
 │   └── xml-adapter.js
 ├── core/
+│   ├── paragraph-text.js
 │   └── word-xml.js
 ├── engine/
 │   ├── oxml-engine.js
@@ -48,8 +50,19 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 │   ├── comment-engine.js
 │   ├── numbering-helpers.js
 │   ├── revision-comment-management.js
+│   ├── document-inspection.js
+│   ├── document-operation-session.js
+│   ├── document-operation-applier.js
+│   ├── document-operation-mutations.js
+│   ├── batch-operation-orchestrator.js
+│   ├── operation-heuristics.js
 │   ├── standalone-docx-plumbing.js
 │   └── standalone-operation-runner.js
+├── node/
+│   ├── docx-document.js
+│   ├── cli.js
+│   ├── zip-archive.js
+│   └── index.js
 ├── index.js
 └── index.d.ts
 ```
@@ -72,16 +85,36 @@ No Word add-in entrypoints or host-specific integration layers are part of this
   - Namespace-safe Word element creation, tracked-change detection, and OOXML payload source-shape helpers.
 - `core/types.js`
   - Shared model enums/types plus revision metadata generation and document-aware revision ID seeding.
+- `core/paragraph-text.js`
+  - Canonical accepted/rejected/current-view text shared by targeting,
+    ingestion, and inspection.
+- `core/paragraph-targeting.js`
+  - Target descriptors and session-scoped paragraph metadata indexes. The
+    index groups IDs and normalized text while retaining canonical text,
+    fingerprints, document order, and table context for deterministic reuse.
 - `core/redline-validation.js`
   - Runtime structural validation (`validateRedlineOoxml`) mirroring the test-suite invariants: no nested revisions, `w:delText` inside `w:del`, complete revision metadata, unique revision ids, preserved boundary whitespace.
 - `engine/oxml-engine.js`
   - Main reconciliation router, mode selection, existing-revision policy gate, and status/error result handling.
+- `engine/route-selection.js`
+  - Internal reconciliation capability matrix and opt-in diagnostic route
+    instrumentation. It observes policy; it does not expose a route override.
 - `engine/run-builders.js`
   - Shared builders for insertion/deletion wrappers, paragraph-mark revisions, visible run content, and run-property changes.
 - `engine/surgical-*.js`
   - Surgical run splitting, diff application, and span helpers for localized edits that preserve surrounding markup.
 - `engine/formatting-removal.js`
   - Shared formatting removal and highlight helpers.
+- `pipeline/list-markers.js`
+  - Dependency-light canonical list-marker grammar, classification, numbering
+    vocabulary, and parsed list-item representation.
+- `pipeline/list-generation.js`
+  - Structural paragraph-to-list generation, paragraph-mark revisions, and
+    selective inheritance of source typography for inserted list runs.
+- `pipeline/structured-content.js`
+  - Strict decomposition and planning for atomic mixed heading/paragraph/list/
+    table replacements. It rejects ambiguous table-like pipe text rather than
+    allowing a fallback to literal paragraphs.
 - `pipeline/*`
   - Ingestion, markdown preprocessing, diffing, patching, and serialization stages. Ingestion treats deleted and moved-from content as non-visible text and inserted/moved-to content as visible text.
 - `services/comment-engine.js`
@@ -93,7 +126,42 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 - `services/revision-comment-management.js`
   - OOXML transforms for accepting/rejecting insertion, deletion, move, paragraph-mark, and property-change revisions by author/all-authors, plus deleting comments by author/all-authors.
 - `services/standalone-operation-runner.js`
-  - Host-agnostic operation bridge for full-document `redline`, `highlight`, and `comment` workflows.
+  - Stable compatibility facade for full-document operations. It only re-exports
+    preflight, single-operation application, batch application, and scheduling.
+- `services/document-operation-applier.js`
+  - Canonical single-operation validation, author resolution, dispatch, and
+    result metadata assembly.
+- `services/document-operation-mutations.js`
+  - Coupled OOXML mutation implementations for redline, highlight, and comment
+    operations. These use leaf-module imports and never import the root entry.
+- `services/batch-operation-orchestrator.js`
+  - Comment-first stable scheduling, atomic policy, artifact aggregation,
+    per-operation results, one final document serialization, and deferred
+    runtime-context commit.
+- `services/document-operation-session.js`
+  - One live document DOM and revision allocator per invocation, immutable
+    start-of-batch target snapshot, lazy paragraph metadata, per-operation DOM
+    and allocator savepoints, exact original XML rollback, index invalidation,
+    artifact/result accumulation, and isolated runtime-context helpers.
+- `services/operation-heuristics.js`
+  - DOM-light decisions for list/plain adjacency insertion and explicit-range
+    list insertion. Canonical list/table targeting remains in `core/*`.
+- `services/document-operation-contract.js`
+  - Compatibility normalization, canonical operation kinds, author precedence,
+    and stable runtime validation for document operations.
+- `services/operation-preflight.js`
+  - Read-only strict target and anchor resolution, revision-policy diagnostics,
+    artifact prediction, and same-paragraph conflict reporting.
+- `services/document-inspection.js`
+  - Read-only paragraphs/comments inventory with target identity, headings,
+    revision authors, table context, and advisory visible numbering.
+- `node/docx-document.js`
+  - Transactional whole-DOCX editing, artifact wiring, validation, and rollback.
+    This surface is excluded from the browser/root dependency graph.
+- `node/cli.js` and `bin/docx-redline.js`
+  - Cross-platform, JSON-only agent command boundary. Read commands never
+    mutate; write commands require attribution, use package transactions, and
+    only overwrite source files under explicit `--in-place` authorization.
 - `orchestration/*`
   - Route planning and list fallback orchestration utilities.
 
@@ -102,15 +170,24 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 1. Caller imports from `index.js`.
 2. Caller configures XML provider/logger/defaults when needed via `adapters/*`.
 3. Caller invokes reconciliation APIs (`applyRedlineToOxml`, operation runner, ingestion/export helpers).
-4. `engine/oxml-engine.js` routes to format, table, list, surgical, or reconstruction flows.
-5. Pipeline/services return OOXML, optional package artifacts (`numberingXml`, comments payloads), and non-breaking `status`/`error` fields where applicable.
-6. Optional revision/comment management transforms can accept/reject revisions, including move revisions, or delete comments by author.
-7. Caller writes resulting XML back to package/document boundaries.
+4. A full-document batch parses once, captures its initial target snapshot, and
+   creates an operation savepoint before each mutation.
+5. `engine/oxml-engine.js` routes each selected scope to format, table, list,
+   surgical, or reconstruction flows; successful scoped output is imported
+   into the live document.
+6. Failed and no-op operations restore their savepoint. A successful changed
+   batch serializes the full document once; atomic failures and all-no-op
+   batches return the exact input string without serialization.
+7. Pipeline/services return OOXML, optional package artifacts (`numberingXml`, comments payloads), and non-breaking `status`/`error` fields where applicable.
+8. Optional revision/comment management transforms can accept/reject revisions, including move revisions, or delete comments by author.
+9. Caller writes resulting XML back to package/document boundaries.
 
 ## Public Surfaces
 
 - Primary: `index.js`
 - Types: `index.d.ts`
+- Stable XML operation runner: `@ansonlai/docx-redline-js/standalone-runner`
+- Node-only DOCX facade: `@ansonlai/docx-redline-js/node`
 
 Keep public exports centralized through `index.js`; deep imports are supported by
 the package `exports` map for advanced consumers, but new public APIs should
@@ -125,14 +202,138 @@ still be re-exported from `index.js`.
   `w:id`, `w:author`, and `w:date` stay consistent and document-unique.
 - Seed revision IDs from parsed input with `seedRevisionIdsFromDocument(xmlDoc)`
   before emitting new tracked changes.
-- Use `containsTrackedChanges(xmlDoc)` before redlining existing revisions unless
-  the caller explicitly chooses the `existingRevisions: 'accept-all-first'` policy.
+- Treat revision metadata inside cloned content as identity-bearing state, not
+  ordinary formatting. When a run containing `w:rPrChange` is split or cloned,
+  preserve an existing revision ID on at most one output run and allocate a
+  fresh document-scoped ID for every additional copy.
+- Use `containsTrackedChanges(xmlDoc)` and `getTrackedChangeAuthors(xmlDoc)`
+  to inspect existing revisions. By default (`existingRevisions: 'merge-same-author'`),
+  subsequent edits from the same author are merged against the pre-revision baseline
+  while revisions from different authors fail closed with `EXISTING_REVISIONS`.
+  Revised paragraphs containing comment anchors fail closed with
+  `COMMENTED_CONTENT_MERGE`; never discard anchors as a side effect of restoring
+  the pre-revision baseline.
+  Pass `existingRevisions: 'accept-all-first'` to normalize prior revisions explicitly.
 - Do not write unknown `result.oxml` payloads directly into `word/document.xml`;
   normalize with `extractReplacementNodesFromOoxml(...)` or use
   `applyOperationToDocumentXml(...).documentXml` for full-document replacement.
 - Run `validateRedlineOoxml(oxml)` on generated output before packaging it;
   it reports structural invariant violations as `{ valid, issues }`.
 
+## Integration Contracts
+
+### Targeting and text fidelity
+
+- Paragraph targeting and replacement have different contracts. Targeting may
+  use normalized text and fallback heuristics; replacement content is literal
+  and must preserve tabs, line breaks, non-breaking spaces, repeated spaces,
+  and boundary whitespace.
+- Text extraction used for targeting represents the visible accepted view of
+  tracked content: insertions are visible and deletions are excluded.
+- Paragraph indexes are transient integration references, not user-facing
+  document identifiers. Prefer paragraph IDs plus exact text where available.
+- Ambiguous matches are unsafe for document mutation. New targeting surfaces
+  should report candidate matches or `AMBIGUOUS_TARGET` rather than silently
+  choosing the first paragraph.
+- Do not remove operation-session savepoints merely to improve throughput.
+  Any replacement must prove that a thrown error or false no-op cannot leak a
+  partial DOM mutation or revision-ID allocation into later operations.
+
+### Structural paragraph-to-list replacement
+
+- In WordprocessingML, `w:numId w:val="0"` suppresses numbering. It represents
+  no reusable list context and must never be returned by numbering allocation
+  or assigned to a generated list item. Generated lists use a positive `numId`
+  bound to a compatible `w:abstractNum` definition.
+- Expanding one non-list paragraph into multiple list paragraphs is a block
+  replacement, not an inline replacement. The original content remains in its
+  own paragraph with a deleted paragraph mark; every replacement item occupies
+  its own paragraph with an inserted paragraph mark and inserted text. This is
+  required so Word can accept the edit as the new paragraphs or reject it as
+  the exact original paragraph without joining the old heading to item one.
+- Inserted list runs selectively inherit source typography (`w:rFonts`, size,
+  language, and related script properties). Semantic emphasis such as bold,
+  underline, italic, or strike is emitted only when requested by the replacement
+  markup; heading emphasis must not leak into ordinary list body text.
+- Low-level list output can carry a package-fragment sentinel needed by its
+  standalone payload shape. Full-document mutation removes that sentinel while
+  importing replacement nodes, so it cannot become an empty document paragraph.
+- Tests for this route must verify positive numbering IDs, separate physical
+  paragraphs, formatting inheritance/non-inheritance, valid revision markup,
+  and exact accepted and rejected paragraph sequences.
+
+### Atomic mixed-content replacement
+
+- `planStructuredReplacement(...)` converts agent-authored Markdown into one
+  replacement operation carrying `structuredContent: true`. The block plan is
+  diagnostic metadata; execution remains one mutation so replacing the anchor
+  cannot invalidate later blocks.
+- Mixed-content parsing recognizes explicit Markdown headings, blank-line
+  paragraph boundaries, adjacent list items, and contiguous table rows. Tables
+  require a header separator and consistent column counts. Invalid input fails
+  with `STRUCTURED_CONTENT_INVALID`; silently degrading table pipes into visible
+  paragraph text is forbidden on this route.
+- Newly inserted tables inside a mixed replacement are tracked once at block
+  scope. Cell runs are not nested in additional `w:ins` wrappers, preserving the
+  no-nested-revisions invariant while allowing Reject All to remove the table.
+- Agents must use explicit heading markers and valid table grammar rather than
+  relying on capitalization or layout inference. The engine preserves the
+  declared block types and does not guess legal-document semantics.
+
+### Package artifacts and transactions
+
+- A real `.docx` stores document markup, comments, numbering, relationships,
+  and content types in separate parts. APIs operating on one XML string cannot
+  claim to update artifacts held in another part.
+- Comment IDs must be allocated against both document anchors and the existing
+  `word/comments.xml` part. Revision IDs must be allocated against the complete
+  document revision scope.
+- Numbering payloads must be merged with `mergeNumberingXmlBySchemaOrder` when
+  a package already contains numbering definitions; replacement is not a merge.
+- Safe package mutation is transactional: retain the original package, apply
+  operations, merge all artifacts, validate redline markup and package wiring,
+  and commit only if every required check succeeds.
+- `openDocx(buffer)` implements this transaction for Node without adding a ZIP
+  dependency to browser or XML-only consumers. Unmodified part contents remain
+  byte-identical after extraction, although the ZIP container is reserialized.
+
+### Operation results
+
+- `hasChanges: false` does not imply success. Callers must check `status`,
+  `error`, and warnings to distinguish errors, missing anchors, and true no-ops.
+- Batch results must preserve the caller's original operation indexes even when
+  execution is reordered for stable anchors.
+- Author attribution is externally visible document data. Agent-facing APIs
+  should require an explicit author and report the author used for every
+  operation rather than relying silently on a configured fallback.
+- 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.
+- `preflightOperations` is the read-only safety boundary for agent-generated
+  batches. It uses strict targeting by default; mutation APIs retain permissive
+  legacy targeting unless `strictTargets: true` is requested. In v1.0.0,
+  application will default to strict targeting; in the current warning cycle,
+  permissive resolution that chooses among multiple identical paragraphs emits
+  `AMBIGUOUS_TARGET_HEURISTIC_USED` with candidate count and migration guidance.
+  Both preflight and mutation runners share the same candidate resolver
+  (`resolveTargetParagraph`).
+
+### Mutation receipts and output reconciliation oracle
+
+- `ReceiptCollector` tracks exact allocations (revision IDs with kind and target part,
+  comment IDs, numbering IDs, relationship IDs, affected targets, and warnings)
+  directly at the point of allocation/attachment during operation execution.
+- Collector state is snapshotted within operation savepoints. Failed or rolled-back
+  operations cleanly restore prior collector state without leaking orphaned allocations.
+- Single operations expose `result.receipt`; batches expose per-item `results[i].receipt`
+  and top-level `result.receipts`, with dispositions (`applied`, `refused`, `no_change`,
+  `rolled_back`, `not_attempted`) and `committed: true/false`.
+- The output reconciliation oracle (`reconcileReceiptsAgainstOutput`) performs an
+  independent, non-negotiable verification: every durable ID reported as committed
+  is parsed from the serialized output XML parts (`word/document.xml`, `word/comments.xml`,
+  `word/numbering.xml`). Any discrepancy immediately fails the transaction and triggers
+  atomic rollback.
+
 
 ## Build Output
 
@@ -148,7 +349,12 @@ The bundle inlines `diff-match-patch` and keeps `@xmldom/xmldom` external.
 ## Testing
 
 - `npm test`
-  - Runs the package test runner (`scripts/run-tests.mjs`) against all `tests/*.mjs` except setup helpers.
+  - Runs all `tests/*.mjs` except setup helpers in separate Node processes with
+    a conservative four-worker cap. Use `DOCX_TEST_CONCURRENCY=1` to reproduce
+    the same sorted suite serially.
+- `npm run benchmark:tests`
+  - Compares paired serial and bounded-parallel suite runs and records JSON
+    under ignored `tmp/benchmarks/`.
 - `npm run test:isolation`
   - Runs boundary checks for Word API markers and dependency-graph isolation.
 - `npm run check:types`
@@ -170,7 +376,7 @@ The bundle inlines `diff-match-patch` and keeps `@xmldom/xmldom` external.
   - Nightly independent-oracle validation: XSD schema check, LibreOffice
     conversion, and an extended 20k-case fuzz sweep with a fresh seed.
 
-Use these checks before publishing or tagging. See `docs/VALIDATION.md`.
+Use these checks before publishing or tagging. See [docs/TESTING.md](./docs/TESTING.md#release-validation-and-independent-oracles).
 
 ## Fast Orientation For Contributors
 

package/CHANGELOG.md

@@ -0,0 +1,319 @@
+# Changelog
+
+## 0.5.0
+
+### ⚠️ Breaking changes
+
+The following changes can require caller or contributor updates. No public
+export or valid existing function signature was removed.
+
+#### Runtime and result-contract changes
+
+- **Canonical paragraph text:** `getParagraphText(...)` now returns the
+  accepted/current view instead of the earlier simplified `w:t`/`w:tab`
+  concatenation. It excludes deleted and `w:moveFrom` content and includes
+  structural breaks, soft hyphens, and non-breaking hyphens.
+  **Migration:** regenerate compared/cached text with the upgraded library. Use
+  `extractCanonicalParagraphText(...)` when accepted/rejected-view semantics
+  are intended; integrations that require the former raw traversal must retain
+  their own legacy extractor before upgrading.
+- **Paragraph fingerprints:** fingerprints now incorporate canonical paragraph
+  text. Stored fingerprints can become stale for paragraphs containing
+  revisions, moves, breaks, soft hyphens, or non-breaking hyphens.
+  **Migration:** do not carry fingerprints across this upgrade; re-extract the
+  document and regenerate target descriptors.
+- **Invalid operations:** malformed or field-incompatible document-operation
+  objects now return a structured `INVALID_OPERATION` error at the runner
+  boundary instead of reaching later failure/no-op paths.
+  **Migration:** validate operation files against the published schema and
+  handle `status === 'error'` plus `error.code === 'INVALID_OPERATION'`.
+- **Commented paragraph deletion:** deleting a complete paragraph that contains
+  an existing comment now fails with `COMMENTED_CONTENT_DELETE` instead of
+  producing OOXML with dangling comment references.
+  **Migration:** preserve or deliberately remove/relocate the comment before
+  deleting the paragraph, and handle the structured error. Atomic callers keep
+  the original document unchanged.
+- **Comment anchor failures:** missing or ambiguous comment anchors now return
+  `ANCHOR_NOT_FOUND` or `AMBIGUOUS_ANCHOR` and fail/roll back an atomic batch;
+  they are no longer reported as successful `no_change` operations.
+  **Migration:** treat these codes as failed operations and use a unique exact
+  anchor or stricter target descriptor before retrying.
+- **Stricter package validation:** DOCX package validation now rejects
+  unbalanced comment ranges, dangling references/usages, orphan definitions,
+  and duplicate comment-definition IDs that earlier validation could allow.
+  **Migration:** repair the comment anchors and `word/comments.xml` definitions
+  before applying or validating further changes.
+
+#### Development workflow change
+
+- **Parallel tests by default:** `npm test` now runs up to four isolated child
+  processes concurrently. This does not change the published runtime API, but
+  contributor automation that depends on test execution order or shared files
+  must be updated. **Migration:** make tests independent or set
+  `DOCX_TEST_CONCURRENCY=1` for the previous serial scheduling behavior.
+
+Strict targeting remains opt-in on existing low-level mutation APIs; it is the
+default only on the newly added Node facade and CLI.
+
+### Deprecations and future breaking changes
+
+- Replacing an existing numbering part without a merge callback now emits a
+  deprecation warning. The Node facade and CLI already merge safely by default.
+  **This remains supported in this release but will become an error in the next
+  major version.** Migrate low-level callers to
+  `mergeNumberingXmlBySchemaOrder` before that release.
+- **Permissive target resolution deprecation (`AMBIGUOUS_TARGET_HEURISTIC_USED`):**
+  Lower-level document operation runners currently default to permissive targeting.
+  In v1.0.0, application will default to `strictTargets: true`. In this release,
+  when permissive resolution encounters multiple identical candidate paragraphs and
+  heuristically chooses the first candidate, it emits an `AMBIGUOUS_TARGET_HEURISTIC_USED`
+  warning with candidate count and migration guidance.
+  **Migration:** Disambiguate operations using `paragraphId`, `index`, `occurrence`,
+  or `fingerprint` and pass `{ strictTargets: true }`.
+
+### ℹ️ Noteworthy Default & Usability Changes (Non-breaking)
+
+The following improvements update default behaviors to maximize agent speed, reduce friction, and eliminate unnecessary errors during iterative editing. These changes are **not technically breaking changes** (no public APIs or exports were removed, and all existing options remain configurable), but represent important behavioral refinements that callers should note:
+
+- **Fallback Author Default (`'AI Redliner'`):** `setDefaultAuthor`, `node/cli.js`, and `openDocx` now default to `'AI Redliner'` (configurable via the `DOCX_REDLINE_AUTHOR` environment variable or `--author`). The CLI `apply` command and core APIs no longer error with `AUTHOR_REQUIRED` when operations omit an author.
+- **Output Overwrite by Default:** Destination files provided via `--output` now overwrite by default instead of failing with `OUTPUT_EXISTS`. Callers wanting protection against accidental overwrites can pass `--no-overwrite` or `--no-clobber`. The source document remains protected and is never overwritten unless `--in-place` is explicitly passed.
+- **Replacement Event Pairing (`pairReplacements: true` by default):** Adjacent `<w:del>` and `<w:ins>` revisions now default to sharing linked revision metadata and identical timestamps so Microsoft Word groups them as a single replacement in the Reviewing Pane. Pass `pairReplacements: false` for independent revision timestamps.
+- **Structured Content Auto-Detection (`structuredContent: true` by default):** Markdown tables, headings (`#`), and lists in replacement text automatically render as native Word elements (`w:tbl`, `w:pStyle`, `w:numPr`). Single outline-numbered legal clauses (e.g. `13.2.1.1`) continue to be treated as ordinary paragraphs without spurious list conversion. Pass `structuredContent: false` to treat replacement text strictly as plain text.
+- **Progressive Batch Mode (`atomic: false` default, `atomic: true` opt-in):** Batch operations and CLI `apply` now apply edits progressively by default (`atomic: false`): valid edits commit directly, while failing edits report structured errors in `results` for faster debugging. Pass `{ atomic: true }` (or `--atomic` on the CLI) for all-or-nothing rollback when any operation fails.
+- **Clean Direct Edits (`generateRedlines: false` / `--no-redlines`):** Prominently documented that tracked redlines are not always the preferred method. Callers can pass `generateRedlines: false` (or `--no-redlines` on the CLI) for clean execution drafts, document restructuring, or minor typo fixes without tracked changes markup.
+- **Existing Revisions Policy (`existingRevisions: 'merge-same-author'` by default):** When editing a paragraph that already contains tracked changes from the same author, prior revisions by that author are merged against the pre-revision baseline (prior changes by that author are reverted and re-diffed to the new modified text), avoiding revision accumulation and nested markup. If a paragraph contains tracked changes from another reviewer, the operation fails closed with `EXISTING_REVISIONS` to protect third-party review marks. Commented revision content fails closed with `COMMENTED_CONTENT_MERGE` so comment anchors cannot be removed or orphaned. Callers can explicitly pass `'accept-all-first'` to normalize prior revisions or `'reject-input'` to refuse editing any revised paragraph.
+- **Inline One-Liner CLI Edits:** Added `--target <text>` with `--modified <text>` or `--comment <text>` on `docx-redline apply` for fast 1–2 edit workflows without creating a JSON operations file.
+
+### Added
+
+- Added **Mutation Receipts** (`receipt` on `DocumentOperationResult` and `receipts`
+  on `BatchOperationResult`). Every operation execution returns structured,
+  commit-aware telemetry capturing durable revision IDs (with kind and target part),
+  comment IDs, numbering IDs, relationship IDs, affected targets, and warnings.
+  Supports `not_attempted`, `applied`, `refused`, `no_change`, and `rolled_back`
+  dispositions.
+- Added **Commit-Aware Output Reconciliation Oracle** (`reconcileReceiptsAgainstOutput`).
+  Before completing any transaction, reported durable IDs are checked against a
+  fresh parse of the generated output OOXML parts. Any reconciliation discrepancy
+  immediately fails the transaction and triggers atomic rollback.
+- Exported receipt primitives: `ReceiptCollector`, `createEmptyReceipt`, and
+  `reconcileReceiptsAgainstOutput` along with `MutationReceipt` and
+  `MutationReceiptRevisionItem` TypeScript declarations.
+- Added **Paragraph Mark Revisions** (`w:pPrChange`, `markParagraphMarkInserted`,
+  `markParagraphMarkDeleted`) ensuring whole-paragraph deletions and insertions
+  cleanly track paragraph mark lifecycles for full Accept All / Reject All symmetry.
+- Added **Paragraph Boundary Mutation Validation** (`validateParagraphBoundaryMutation`)
+  guarding against invalid cross-paragraph boundary merges.
+
+- Added `analyzeStructuredContent(...)` and `planStructuredReplacement(...)`
+  for agent-authored attachments and schedules containing mixed headings,
+  paragraphs, lists, and tables. The planner returns typed blocks and produces
+  one atomic `structuredContent` operation only when the Markdown is valid.
+
+- Added session-scoped paragraph metadata indexing for canonical text,
+  normalized text, paragraph IDs, fingerprints, table context, and document
+  indexes, plus deterministic targeting and route-profiling benchmarks.
+- Added a shared list-marker grammar and parsed list-item vocabulary used by
+  pipeline analysis, orchestration, normalization, and list targeting.
+- Added an internal reconciliation capability matrix and opt-in route
+  instrumentation. Public reconciliation result shapes and route selection
+  policy remain unchanged.
+
+- Added `scripts/extract_text.mjs` and `scripts/apply_changes.mjs` as thin
+  compatibility entrypoints for legacy skill installations. They delegate to
+  the supported CLI, retain strict atomic validated writes, and accept legacy
+  operation files with a top-level `changes` array.
+- Added typed operations, per-operation authors, strict target descriptors,
+  deterministic preflight diagnostics, and auditable resolution metadata.
+- Added `inspectDocumentParts(...)`, a structured document inventory using the
+  same canonical text extractor as targeting and ingestion.
+- Added `@ansonlai/docx-redline-js/node`. `openDocx(...)` applies batches to
+  complete DOCX buffers transactionally and validates before commit.
+- Added the cross-platform `docx-redline` CLI with JSON `inspect`, `extract`,
+  `preflight`, `apply`, `accept`, `reject`, `delete-comments`, and `validate`
+  commands, plus a published operation-file JSON Schema.
+
+### Behavior and reliability
+
+- Explicit structured replacements now reject missing Markdown table separator
+- Generated Markdown tables repeat their header row and prevent logical data rows from splitting across pages.
+  rows, missing data rows, and inconsistent column counts with
+  `STRUCTURED_CONTENT_INVALID` instead of inserting literal pipe-delimited text.
+- Tables created inside mixed replacements are tracked once at block scope,
+  avoiding nested revisions while keeping Accept All and Reject All symmetric.
+
+- Target preflight and live mutation reuse one document-scoped paragraph index;
+  strict duplicate detection and resolution metadata retain their prior
+  semantics while avoiding repeated whole-document text traversal.
+- Revision-ID seeding now walks the DOM with child/sibling pointers instead of
+  allocating an array containing every element.
+- Single-source-paragraph list expansion uses the focused list generator
+  directly. Multi-paragraph marked-list edits deliberately retain the legacy
+  run-aware reconciliation pipeline for structural parity.
+- Fixed paragraph-to-list expansion when a manually numbered heading carries
+  `w:numId w:val="0"`. Numbering suppression is no longer reused as a generated
+  list ID, so inserted bullet and numbered items receive valid positive IDs.
+- Tracked heading-to-list replacements now keep the deleted source heading in
+  its own paragraph and track the paragraph marks of every inserted list item.
+  This prevents deleted heading text from joining the first item and preserves
+  exact Accept/Reject structure without adding a full-document sentinel
+  paragraph.
+- Inserted list items now inherit source font family, size, language, and
+  related script typography without inheriting heading-only bold, underline,
+  italic, or strike formatting unless requested by the replacement markdown.
+- Canonical-only table-cell targeting now consumes the shared paragraph-text
+  extractor, while offset- and sentinel-producing walkers remain specialized.
+  Their accepted visible projections now agree on soft hyphens as well as tabs,
+  breaks, hyperlinks, and non-breaking hyphens.
+
+- Comment preflight and application now share one anchor resolver. Exact
+  matches take priority, unique ordinary-space/NBSP differences preserve raw
+  offsets, and missing or repeated anchors return structured
+  `ANCHOR_NOT_FOUND` or `AMBIGUOUS_ANCHOR` errors.
+- Full-document operation batches now share one live DOM and revision-ID
+  allocator, reducing complete-document parsing and serialization from once per
+  operation to once per changed batch. Scoped reconciliation engines and their
+  targeting decisions are unchanged.
+- Each live-session operation uses a DOM and allocator savepoint. Errors and
+  reported no-ops restore the savepoint; atomic failures and all-no-op batches
+  still return the exact original XML without serializing it.
+- Decomposed the standalone document-operation runner into a stable 13-line
+  compatibility facade plus focused session, applier, batch-orchestrator,
+  heuristic, and OOXML-mutation modules. Runtime exports and declarations are
+  unchanged, and operation internals now use leaf imports instead of importing
+  the root entry point.
+- Package comment IDs are seeded from existing anchors and definitions, and
+  the Node facade merges numbering without discarding prior definitions.
+- Canonical paragraph text consistently handles revisions, moves, tabs,
+  breaks, soft hyphens, and non-breaking hyphens; see the breaking-change note
+  above for `getParagraphText(...)` and fingerprint compatibility.
+- Structured inspection now explicitly supports the `current` view as the
+  accepted/current document view and resolves comment ranges spanning multiple
+  paragraphs as one exact anchor string.
+- Transactional no-op results preserve the original DOCX bytes exactly,
+  including when the same facade instance has already committed an edit.
+
+### Testing and development
+
+- Added focused and semantic visual-failure regressions for suppressed
+  numbering, paragraph separation, paragraph-mark revisions, selective
+  typography inheritance, and exact accepted/rejected paragraph sequences,
+  plus seeded fuzz variants across list length, marker, font, and size.
+  Added the independently specified
+  `legal-suppressed-heading-to-bullet-list` and
+  `legal-structured-attachment-mixed-blocks` Microsoft Word differential
+  fixtures; the synthetic catalogue now contains 49 cases and 49 task types.
+
+- The JavaScript test runner now uses bounded asynchronous subprocess workers,
+  capped at four by default, while retaining one fresh Node process per file,
+  sorted reporting, timeouts, captured diagnostics, and failure-marker checks.
+  Set `DOCX_TEST_CONCURRENCY=1` for serial reproduction.
+- Added `npm run benchmark:tests` and a Phase 6 runner regression. The checked
+  benchmark reduced median suite time from 18.02 seconds to 7.96 seconds
+  (55.80%); 20 consecutive parallel runs and a separate serial run passed all
+  63 files. Parallel c8 collection remains valid at 89.90% statements/lines,
+  77.40% branches, and 93.10% functions.
+
+- Added Phase 3 targeting/traversal, Phase 4 list/text parity, and Phase 5 route
+  compatibility regressions. Together with the Phase 6 runner regression, the
+  suite now contains 63 passing test files.
+- Added `npm run benchmark:targeting` and `npm run profile:routes`. The checked
+  10,000-paragraph benchmark showed no single-operation regression and a 47.16x
+  Node median improvement for 100 cached resolutions. The equivalent native
+  Chrome benchmark showed no single-operation regression and a 36.45x batch
+  improvement. All 47 Microsoft Word differential fixtures and all 60 real-
+  document Word corpus scenarios passed after the routing changes.
+
+- Added subprocess coverage for legacy wrapper selection, operation-file
+  compatibility, successful output, atomic anchor failure, source-byte
+  preservation, and protection of pre-existing output files.
+- Added a live-session accuracy and instrumentation suite covering accepted and
+  rejected text, structural validity, sequential equivalence, comments, lists,
+  tables, highlights, one-parse/one-serialize execution, exact no-ops, and
+  atomic rollback. Added `npm run benchmark:session`; the checked accuracy-first
+  benchmark reduced parse/serialize counts from 10/10 to 1/1 and measured a
+  1.58x median speedup with per-operation savepoints retained.
+- Added a Phase 2 architecture regression covering facade export identity,
+  direct leaf imports, exact session rollback, isolated context commit, and
+  stable comment-first scheduling.
+- Added five edge-case suites for canonical text views, cross-paragraph comment
+  inspection, table/list/reference context, sequential package transactions,
+  selective multi-author cleanup, ZIP rejection behavior, CLI filters, JSON
+  exit contracts, and destructive-output safeguards. Together with the Phase 2
+  Phase 1 and Phase 2 regressions, these established the earlier 57-file
+  baseline expanded by the subsequent performance phases.
+
+## 0.3.0
+
+### Breaking changes
+
+- Malformed OOXML no longer escapes public transform APIs as a raw parser
+  exception. In particular, revision accept/reject and comment-deletion callers
+  that previously used `try`/`catch` must now inspect `status === 'error'` and
+  `error.code === 'PARSE_ERROR'` on the returned result.
+- Caller content is no longer sanitized by default. Pass `sanitizeInput: true`
+  to remove a standalone leading assistant-preface line. Dollar-delimited text
+  and literal `\\n` / `\\r\\n` sequences are never removed implicitly.
+- The exported `sanitizeAiResponse` helper no longer removes dollar-delimited
+  spans or converts literal `\\n` / `\\r\\n` sequences. Direct callers that
+  relied on those transformations must perform them explicitly.
+- `applyOperationsToDocumentXml` is atomic by default. Failed batches return
+  the original document with `rolledBack: true`; pass `atomic: false` to retain
+  partial-result behavior.
+- Missing multi-line targets now return `TARGET_NOT_FOUND` instead of being
+  indistinguishable from a no-op. Stale batch anchors also return
+  `TARGET_NOT_FOUND` instead of falling back to a visibly different paragraph.
+
+### Behavior changes and fixes
+
+- Revision IDs are now allocated per document. Near-limit prior IDs restart in
+  a safe low range, and unrelated bookmark/relationship IDs no longer seed the
+  revision counter.
+- Concurrent calls with explicit authors keep their revision attribution
+  isolated from process-global defaults.
+- `existingRevisions: 'accept-all-first'` now preserves the original OOXML when
+  the requested edit is a no-op.
+- Added `existingRevisions: 'accept-all-first-keep-normalized'` for callers that
+  explicitly want accepted existing revisions returned even when no redline is
+  added.
+- Diff output is deterministic by default. Inputs exceeding 262,144 unique
+  tokens return `DIFF_TOKEN_LIMIT` with the original OOXML unchanged instead of
+  risking truncated text; leading whitespace is preserved exactly.
+- Reconstruction preserves structural line breaks and body section-property
+  placement. A target that names only part of a reconstruction range now
+  returns `PARTIAL_TARGET` instead of risking deletion of untargeted content.
+- Paragraph targeting and reconstruction now preserve leading, middle, and
+  trailing `w:tab` elements as literal tab characters instead of omitting or
+  trimming them.
+- Adjacent redline edits now preserve complex-field instructions, begin/
+  separate/end markers, and unchanged cached display results in their original
+  field boundary. Field instructions remain inert and are not evaluated.
+- Added structured XML parse results and result-returning ingestion helpers.
+- Hardened deterministic diff token handling and leading-whitespace fidelity.
+
+### Testing and development
+
+- Expanded the desktop Word differential from 20 to 25 cases, adding structural
+  checks for bookmarks, internal hyperlinks, mixed formatting, content
+  controls, and tables.
+- Expanded the desktop Word differential from 25 to 28 cases with structural
+  tabs and a locked PAGE field, and added tab/field shapes to focused and fuzz
+  regression testing.
+- Expanded the desktop Word differential from 28 to 33 cases with comments,
+  footnotes, endnotes, headers/footers, and an external hyperlink.
+- Extended the deterministic script-only DOCX packager with opt-in related
+  parts, relationship/content-type validation, reusable fixture constructors,
+  and SHA-256 verification that supplied parts remain byte-identical. Runtime
+  library code and dependencies are unchanged.
+- Added validated task, structure, oracle, and manual-review metadata across the
+  33 synthetic and 20 SuperDoc Word cases. `npm run report:word:coverage`
+  produces a deterministic coverage matrix with explicit high-priority gap
+  dispositions, while `npm run review:word:prepare` creates a pending rotating
+  human-review manifest without self-certifying visual results.
+- Added detailed production-function coverage reporting and a checked per-file
+  regression baseline. Five behavior-focused Phase 3 suites exercise numbering
+  collisions/remapping, every reconciliation route, list construction and
+  fallback, patch/format boundaries, table decisions, pipeline modes, and
+  standalone rollback/highlight paths. Production function coverage moved from
+  437/540 to 496/542 and all reachable P0 functions are covered; no runtime
+  behavior or compatibility contract changed.