@ansonlai/docx-redline-js 0.8.4 → 0.9.0

package/ARCHITECTURE.md

@@ -38,8 +38,10 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 │   ├── logger.js
 │   └── xml-adapter.js
 ├── core/
+│   ├── current-properties.js
 │   ├── paragraph-text.js
 │   ├── sha256.js
+│   ├── word-revision-semantics.js
 │   └── word-xml.js
 ├── document/
 │   ├── docx-document.js
@@ -50,18 +52,27 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 │   ├── surgical-mode.js
 │   ├── reconstruction-mode.js
 │   ├── run-builders.js
+│   ├── paragraph-mark-revisions.js
 │   └── formatting-removal.js
 ├── orchestration/
 ├── pipeline/
 ├── services/
 │   ├── comment-engine.js
 │   ├── numbering-helpers.js
+│   ├── numbering-allocation.js
+│   ├── list-conversion-diagnostics.js
+│   ├── list-format.js
+│   ├── list-format-mutation.js
+│   ├── list-format-change.js
+│   ├── operation-batch-compiler.js
+│   ├── localized-replacement-compiler.js
 │   ├── revision-comment-management.js
 │   ├── document-inspection.js
 │   ├── document-operation-session.js
 │   ├── document-operation-applier.js
 │   ├── document-operation-mutations.js
 │   ├── batch-operation-orchestrator.js
+│   ├── revision-fidelity-verifier.js
 │   ├── operation-heuristics.js
 │   ├── standalone-docx-plumbing.js
 │   └── standalone-operation-runner.js
@@ -116,6 +127,24 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 - `core/validation-delta.js`
   - Stable issue signatures and multiset subtraction for classifying baseline
     versus generated validation issues without hiding added duplicate errors.
+- `core/word-revision-semantics.js`
+  - Pure DOM projection of what Word shows after Reject All or Accept All
+    (`projectWordRevisionView`, `wordRevisionParagraphTexts`,
+    `paragraphMarkRevision`). It encodes Word's paragraph-mark rules: a
+    tracked-inserted mark vanishes on Reject and its content merges into the
+    following paragraph of the same container, a tracked-deleted mark does the
+    same on Accept, a table cell keeps its last paragraph, rows marked inserted
+    or deleted vanish, and Reject restores `w:pPrChange` snapshots. It never
+    mutates or serializes. The rules are validated against recorded desktop
+    Word 16 COM results (`tests/fixtures/word-revision-semantics/`).
+- `core/current-properties.js`
+  - Direct-child accessors for the current paragraph/run properties
+    (`getCurrentParagraphProperties`, `getCurrentRunProperties`,
+    `getCurrentChild`, `getCurrentNumIdElements`, ...). Descendant lookups cross
+    `w:pPrChange` / `w:rPrChange`, so a historical `numPr` or `pStyle` would look
+    current; the snapshot is reachable only through the explicit
+    `getHistoricalParagraphProperties` / `getHistoricalRunProperties` and
+    `getAllReferencedNumIdElements`. Depends only on `core/types.js`.
 - `core/revision-cloning.js`
   - Shared effective-property cloning strips historical revision descendants;
     intentional revision-bearing splits refresh cloned property-change IDs.
@@ -125,7 +154,20 @@ No Word add-in entrypoints or host-specific integration layers are part of this
   - 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.
+  - Shared builders for insertion/deletion wrappers, visible run content, and run-property changes. It does not build paragraph-mark revisions.
+- `engine/paragraph-mark-revisions.js`
+  - The single construction site for a tracked paragraph mark (`w:ins` / `w:del`
+    under `w:pPr/w:rPr`). DOM entry points (`markParagraphInserted`,
+    `markParagraphDeleted`, `setParagraphPropertiesMarkRevision`,
+    `clearParagraphMarkRevision`, `restoreParagraphMarkInserted`) and string
+    builders (`paragraphMarkRevisionXml`, `paragraphMarkPPrXml`) share one
+    metadata path, so ids are allocated through the document's allocator and
+    recorded in receipts. `planParagraphMarks` is a pure check that an
+    alignment gives every source paragraph exactly one untracked or deleted
+    mark and every new target paragraph an inserted mark, so Reject All yields
+    the source paragraph count and a deleted paragraph is never collapsed into
+    another. Reconstruction, list and table generation, and document-level
+    shortcuts all call it. Depends only on `core/`.
 - `engine/surgical-*.js`
   - Surgical run splitting, diff application, and span helpers for localized edits that preserve surrounding markup. Plain-text edit groups execute from right to left with a fresh live span index, while space/NBSP-only replacement hunks are refined to character-local changes so unchanged hyperlink containers survive.
     The shared carrier splitter also handles explicit rejected-view deletion
@@ -148,7 +190,36 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 - `services/comment-engine.js`
   - Comment creation and package-level comment XML handling.
 - `services/numbering-helpers.js`
-  - Dynamic numbering ID allocation, numbering payload remapping, and schema-order-safe numbering merges.
+  - Document-scoped numbering ID state (`createDynamicNumberingIdState`,
+    `reserveNextNumberingIdPair`), numbering payload remapping, and shared DOM
+    predicates. It no longer owns a merge.
+- `services/numbering-allocation.js`
+  - The single place that creates, continues, merges and validates numbering
+    definitions. `allocateNumberingDefinition` builds a new `w:abstractNum` +
+    `w:num` (source levels copied, chosen levels redefined, start overrides)
+    from ids reserved through the document state; `allocateNumberingForReplacement`
+    holds the reuse-source-list policy (`continue-source`, `allocate`,
+    `passthrough`) so no call site decides it; `continueBatchListSequence` lets
+    separate operations of one batch that generate items of the same kind,
+    format and level continue one numbering instance (reused only while its
+    `numId` is still bound in the live document). `mergeNumberingParts` /
+    `mergeNumberingXmlBySchemaOrder` are the one numbering merge, used by the
+    runner's consumers and the `openDocx` facade; an incoming `w:abstractNum` /
+    `w:num` id that exists with different content throws `NUMBERING_ID_CONFLICT`.
+    `checkNumberingBinding` validates a direct `{ numId, level }` binding and
+    `validateNumberingIntegrity` reports dangling `numId`, `abstractNumId` and
+    `ilvl` (`NUMBERING_*` issues) for the facade's baseline-delta validation.
+    Old definitions are never deleted or overwritten, and tracked-deleted source
+    paragraphs keep their `numPr`.
+- `services/list-conversion-diagnostics.js`
+  - Safety diagnostics for text edits that retype list markers
+    (`LIST_MARKER_NOT_BOUND` / `UNSUPPORTED_LIST_CONVERSION`,
+    `LIST_FORMAT_NOT_APPLIED` / `UNSUPPORTED_LIST_FORMAT_CHANGE`; warning by
+    default, error under `strictListConversion`, silenced by
+    `listMarkers: 'literal'`), the closed `paragraph-format` key set (unknown
+    keys are `INVALID_OPERATION`) and the `numbering` shape check behind
+    `paragraph-format` numbering binding. Recovery points at `list-format`
+    through `recovery.suggestedOperation`.
 - `services/standalone-docx-plumbing.js`
   - Package-level extraction/wiring/validation for `word/document.xml`, `word/numbering.xml`, and `word/comments.xml`.
 - `services/revision-comment-management.js`
@@ -160,7 +231,13 @@ No Word add-in entrypoints or host-specific integration layers are part of this
   - Canonical single-operation validation, author resolution, dispatch, and
     result metadata assembly. Before commit it validates the entire live
     document against the operation savepoint and refuses newly generated
-    structural errors, including duplicate revision IDs.
+    structural errors, including duplicate revision IDs. For localized
+    `replacements` it also checks, before commit, that the target's accepted text
+    (read from the successor paragraph via `SourceTargetRegistry.previewSuccessor`,
+    or the restored paragraph) equals the compiled desired text; otherwise the
+    savepoint is restored and `PATCH_ROUNDTRIP_MISMATCH` is returned, because a
+    tracked whole-paragraph deletion rejects back to the source and the Reject
+    All verifier alone cannot see it.
 - `services/document-operation-mutations.js`
   - Coupled OOXML mutation implementations for redline, highlight, and comment
     operations. For text-bearing edits, the resolved paragraph's exact
@@ -188,6 +265,50 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 - `services/document-operation-contract.js`
   - Compatibility normalization, canonical operation kinds, author precedence,
     and stable runtime validation for document operations.
+- `services/list-format.js` and `services/list-format-mutation.js`
+  - The `list-format` operation (`convert-plain`, plus the shared request shape
+    for `change-format` and `join`): contract shape, the narrow
+    typed-marker grammar (letter versus roman disambiguation by sequence or an
+    explicit `format`), and the in-place DOM core. Every refusal is decided
+    before mutation; the binding reuses the `paragraph-format.numbering` path
+    (`snapshotAndAttachPPrChange` + `applyParagraphPropertiesToPPr`), the marker
+    becomes one tracked `w:del`, definitions come from
+    `allocateNumberingDefinition`, and batch continuity uses
+    `runtimeContext.listFallbackSequenceState` (an entry is reused only while
+    its `numId` is bound in the live document). Text-equal redline header
+    conversions for letters, roman numerals and bullets call the same core.
+    The `paragraph-format` numbering binding (`properties.numbering`,
+    `{ numId, level }` or `null`) lives in `document-operation-mutations.js`: it
+    snapshots the earliest same-author `w:pPrChange`, refuses another author's
+    pending snapshot (`PARAGRAPH_FORMAT_REVISION_CONFLICT`), and checks the
+    binding with `checkNumberingBinding`. `list-format` is body-only; `openDocx`
+    refuses it with a `part` selector.
+- `services/list-format-change.js`
+  - `list-format` `change-format` and `join` (`scope: 'list'` or `'range'`): rebind existing list items with
+    one tracked `w:pPrChange` each, never editing a shared definition.
+    `change-format` allocates a new definition through
+    `allocateNumberingDefinition` (source levels copied, one redefined, start
+    values on the new abstract); `join` reuses the earlier list's `numId`.
+    Planning models Word's counters (shared abstracts continue each other, a
+    level start re-applies on restart, deeper items start unused levels) and
+    refuses splits, joins and style-linked or instance-overridden definitions
+    it cannot reproduce exactly. Definitions are read from the source part plus
+    the batch's pending numbering parts.
+- `services/operation-batch-compiler.js`
+  - Binds every operation to batch-start source paragraphs
+    (`SourceTargetRegistry`), compiles localized `replacements`, and detects
+    overlap before any mutation. Composition rule for `redline` + `list-format`:
+    exactly one single-paragraph `redline` (no `targetEnd`, anchor, part or
+    structured content) that keeps the typed marker and changes the text after
+    it composes with one `list-format` on the same paragraph; the compiler fixes
+    the order by setting `_compiledRunAfter` on the list-format, which the batch
+    orchestrator honours, so the redline always runs first. Everything else on a
+    list-format target is refused with `LIST_FORMAT_COMPOSITION_CONFLICT`
+    (`reason`: `marker-changed`, `redline-unchanged`, `redline-shape`, or
+    `list-rebind` when a `scope: 'list'` `change-format`/`join` rebinds an item
+    that another operation also writes). `list.continueFrom` is bound at batch
+    start as a read-only target. `previewSuccessor` lets the applier find a
+    target's replacement paragraph before commit.
 - `services/operation-preflight.js`
   - Read-only strict target and anchor resolution, revision-policy diagnostics,
     artifact prediction, and same-paragraph conflict reporting.
@@ -213,6 +334,42 @@ No Word add-in entrypoints or host-specific integration layers are part of this
     Mutation commands expose a compact contract: package/XML payloads and full
     validation arrays remain internal, while stdout contains durability fields,
     per-operation evidence, validation counts, and a derived completion flag.
+- `services/revision-fidelity-verifier.js`
+  - Post-apply invariant check built on `core/word-revision-semantics.js`.
+    `verifyRevisionFidelity` compares Reject All of the output with Reject All
+    of the savepoint (both reject every author's revisions) and reports
+    `REJECT_PARAGRAPH_COUNT`, `REJECT_PARAGRAPH_TEXT`, `REJECT_PARAGRAPH_PROPS`,
+    `REJECT_NUMBERING_REFS` and `REJECT_WRAPPERS`. Under accept-first
+    existing-revision policies the baseline is the accepted view, scoped to the
+    resolved target range when known (otherwise the changed region between the
+    unchanged prefix and suffix). `REJECT_NUMBERING_REFS`
+    (`verifyNumberingReferences`) also refuses a numId that the output binds or
+    Reject All restores when the source did not use it and no `w:num` ->
+    `w:abstractNum` -> `w:lvl` defines it in the numbering available to the
+    operation (numbering existence). `verifyUntrackedLocality` covers
+    `generateRedlines: false` single-target operations with `ACCEPT_NEIGHBORS`:
+    no paragraph outside the target may change in either view.
+    `verifyNoCreatedRevisions` adds `UNTRACKED_CREATED_REVISION`: an untracked
+    operation may not introduce a revision id that was not in the source
+    (fragments of a sliced source revision, same element, author and date, are
+    allowed). `verifyAcceptIntent` adds `ACCEPT_INTENT`: a tracked plain-text
+    `redline` with complete `modified` (single paragraph or `targetEnd` range)
+    must read as `modified` in the Accept All view of its target; accept-first
+    range targets use the exact accepted scope.
+    `buildRevisionFidelityError` produces the `REVISION_FIDELITY_VIOLATION`
+    payload (`violations[].explanation`, `source.sourceParagraphIndex`,
+    `recovery.retryGuidance`). Modes are `enforce` (default, refuse and roll
+    back), `warn` (apply and append a warning) and `off`, resolved by
+    `resolveRevisionFidelityMode`: explicit `verifyRevisionFidelity` option,
+    then the diagnostic `DOCX_REDLINE_REVISION_FIDELITY` environment variable,
+    then `enforce`. The view memo is `createFidelityViews(document)`: lazily
+    filled `accepted` / `rejected` projections, revision-id signatures and
+    numbering references for one DOM. The applier builds a memo for the savepoint
+    (taking over `session._fidelityViews` when it still describes the live
+    document) and one for the result; after a committed tracked or untracked
+    operation the result's memo is stored back in `session._fidelityViews` as
+    the next operation's baseline, and a refused operation restores the prior
+    memo, so each view is computed at most once per DOM.
 - `orchestration/*`
   - Route planning and list fallback orchestration utilities.
 
@@ -221,15 +378,25 @@ 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. A full-document batch parses once, captures its initial target snapshot, and
-   creates an operation savepoint before each mutation.
+4. A full-document batch parses once, captures its initial target snapshot,
+   compiles the operations against it (`operation-batch-compiler.js`: batch-start
+   source binding, localized replacements, overlap and list-format composition
+   checks, all before any mutation), 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
+6. After each mutation the applier (`services/document-operation-applier.js`)
+   validates the generated OOXML against the savepoint, checks the localized
+   replacement intent, then runs the revision fidelity verifier (Reject All,
+   Accept All intent, neighbor, created-revision and numbering-existence
+   invariants); a violation in `enforce` mode restores the savepoint and
+   refuses the operation before anything is committed. 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.
+7. Pipeline/services return OOXML, optional package artifacts (`numberingXml`, comments payloads; numbering parts are merged by `mergeNumberingParts` and
+   checked by `validateNumberingIntegrity`), 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.
 
@@ -265,6 +432,28 @@ still be re-exported from `index.js`.
   `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.
+- Every operation is checked after it is applied
+  (`services/revision-fidelity-verifier.js`, default `enforce`): Word's Reject
+  All of a tracked output must equal Word's Reject All of the source (`REJECT_*`),
+  a plain-text `redline` must read as its `modified` text under Accept All
+  (`ACCEPT_INTENT`), and an untracked edit must neither change other paragraphs
+  (`ACCEPT_NEIGHBORS`) nor create a revision (`UNTRACKED_CREATED_REVISION`). A
+  violation restores the operation savepoint and returns
+  `REVISION_FIDELITY_VIOLATION`; `warn` applies and warns, `off` is for
+  diagnosis only.
+- Allocate, continue, merge and validate numbering only through
+  `services/numbering-allocation.js`. Never edit a shared `w:abstractNum` or
+  `w:num` in place, never delete a definition Reject All may need, and keep
+  `numPr` on tracked-deleted source paragraphs.
+- Construct paragraph-mark `w:ins` / `w:del` only through
+  `engine/paragraph-mark-revisions.js`, and read current paragraph/run
+  properties only through `core/current-properties.js`. Two source-scanning
+  tests enforce this: `tests/paragraph_mark_single_site_tests.mjs` rejects
+  paragraph-mark revision construction (templates opening an `rPr` with
+  `ins`/`del`, DOM creation attached to an `rPr`, retired helper names) outside
+  the helper, and `tests/current_properties_usage_tests.mjs` rejects descendant
+  lookups of property names (`numPr`, `pStyle`, `b`, ...) outside the accessor.
+  Exceptions need an entry with a written reason in each test's allowlist.
 - Do not write unknown `result.oxml` payloads directly into `word/document.xml`;
   normalize with `extractReplacementNodesFromOoxml(...)` or use
   `applyOperationToDocumentXml(...).documentXml` for full-document replacement.
@@ -339,8 +528,10 @@ still be re-exported from `index.js`.
 - 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.
+- Numbering payloads are merged, never replaced, by the single merge in
+  `services/numbering-allocation.js` (`mergeNumberingParts`), which both the
+  runner's consumers and the `openDocx` facade call; conflicting ids fail with
+  `NUMBERING_ID_CONFLICT`.
 - 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.
@@ -370,7 +561,7 @@ still be re-exported from `index.js`.
   text-bearing mutation. Mutation uses canonical accepted-view source text, and `resolvedTarget.targetTextMatch`
   records `exact`, `space_equivalent`, or `normalized` selection plus bounded
   invisible-character diagnostics.
-- CLI contract version 3 is deliberately narrower than library result objects.
+- The CLI contract (version 9; `docx-redline version` lists the capabilities) is deliberately narrower than library result objects.
   `apply`, `accept`, `reject`, and `delete-comments` omit `documentXml`, package
   parts, inspection text, and full issue arrays. `completion` is true only when
   `written === true`, top-level status is neither error nor partial, and every
@@ -400,6 +591,10 @@ still be re-exported from `index.js`.
   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.
+- The oracle checks that durable IDs are committed; the revision fidelity
+  verifier checks what Reject All would restore. A refused operation restores
+  its savepoint and receipt state like any other refusal, so it contributes no
+  committed IDs (`finalDisposition: 'refused'`).
 
 
 ## Build Output
@@ -437,11 +632,21 @@ The bundle inlines `diff-match-patch` and keeps `@xmldom/xmldom` external.
 - `npm run smoke:word:diff`
   - Windows/Word COM differential test: Word itself accepts/rejects the
     generated fixtures and the resulting text is compared to expectations.
+    Structural checks also compare paragraph counts, and list cases compare
+    `ListFormat.ListString` labels after `Revisions.AcceptAll()` /
+    `RejectAll()`.
 - `bash scripts/validate-fixtures-xsd.sh`
   - Validates exported fixtures against the ECMA-376 transitional `wml.xsd`.
+- `tests/reject_roundtrip_matrix_tests.mjs` (part of `npm test`)
+  - Generated operation matrix over fixtures and operation kinds, asserting the
+    revision fidelity invariants and receipt reconciliation (a
+    `RECEIPT_RECONCILIATION_FAILED` fails the case). Replay with `FUZZ_SEED` /
+    `MATRIX_ITERATIONS`.
 - `.github/workflows/validation.yml`
   - Nightly independent-oracle validation: XSD schema check, LibreOffice
-    conversion, and an extended 20k-case fuzz sweep with a fresh seed.
+    conversion, an extended 20k-case fuzz sweep with a fresh seed, and the
+    `matrix-extended` job (1000 reject-roundtrip matrix cases with a
+    date-derived seed; a failure prints its seed and replay command).
 
 Use these checks before publishing or tagging. See [docs/TESTING.md](./docs/TESTING.md#release-validation-and-independent-oracles).
 
@@ -454,7 +659,11 @@ Use this sequence to understand or modify behavior without reading everything:
 3. For targeting bugs, inspect `core/paragraph-targeting.js`, `core/list-targeting.js`, and `core/table-targeting.js`.
 4. For package wiring issues, inspect `services/standalone-docx-plumbing.js`.
 5. For revision/comment cleanup behavior, inspect `services/revision-comment-management.js`.
-6. For numbering/list issues, inspect `services/numbering-helpers.js` and orchestration list-fallback modules.
+6. For numbering/list issues, inspect `services/numbering-allocation.js`,
+   `services/list-format*.js`, `services/list-conversion-diagnostics.js` and
+   orchestration list-fallback modules; for batch composition,
+   `services/operation-batch-compiler.js`; for Reject All refusals,
+   `services/revision-fidelity-verifier.js`.
 7. For reliability regressions, start with `tests/roundtrip_invariant_tests.mjs`,
    `tests/engine_reliability_tests.mjs`, `tests/paragraph_mark_revision_tests.mjs`,
    `tests/move_revision_tests.mjs`, and `tests/hardening_status_tests.mjs`.

package/CHANGELOG.md

@@ -1,5 +1,181 @@
 # Changelog
 
+## 0.9.0
+
+### Changed
+
+- **Unknown `paragraph-format.properties` keys are rejected:** `INVALID_OPERATION` with `field: properties.<key>`, `properties[]`
+  and `recovery.action: change_request`; nothing is applied. The 0.8.x `UNKNOWN_PARAGRAPH_FORMAT_PROPERTY` warning no longer fires.
+- **CLI contract version 9** (`list-format` operation type, capability `list-format-v1`). Integrations that do not send
+  `list-format` can keep requiring version 8.
+- **`UNSUPPORTED_LIST_CONVERSION` / `LIST_MARKER_NOT_BOUND` now point at `list-format`:** `recovery.action` is
+  `use_list_format_convert_plain` (was `apply_plain_text_or_convert_in_host`) and, when the original paragraph has no marker,
+  `recovery.suggestedOperation` carries the `list-format` request to send with the same target (for "Header" -> "C. Header":
+  `{ mode: 'convert-plain', format: 'upperLetter', strip: 'none', start: 3 }`). `listMarkers: 'literal'` is unchanged.
+- **`UNSUPPORTED_LIST_FORMAT_CHANGE` / `LIST_FORMAT_NOT_APPLIED` now point at `list-format` `change-format`:** `recovery.action`
+  is `use_list_format_change_format` (was `change_list_format_in_host`) and `recovery.suggestedOperation` carries
+  `{ type: 'list-format', list: { mode: 'change-format', format, level, scope: 'list' } }`; add a target on one item of the list.
+  `list-change` still never applies a format change itself.
+- **A `list-format` with `scope: 'list'` counts as a write to every item it rebinds:** another write to one of those items in the
+  same batch (`paragraph-format`, `highlight`, `format`, a second `list-format` of the same list) now fails before mutation with
+  `LIST_FORMAT_COMPOSITION_CONFLICT` (`reason: list-rebind`); in WP-5 it ran in batch order. Send it in a separate apply or use
+  `scope: 'range'`. A single-paragraph `redline` of an item still composes (see Added).
+- **Text-equal letter, roman and bullet header conversions are made in place:** a `redline` whose `modified` equals the plain
+  paragraph's typed-marker text (`B. Header` -> `B. Header`) now strips the marker as a tracked deletion and binds the list with a
+  tracked `w:pPrChange` in the same paragraph, like the decimal path. The previous whole-paragraph delete plus insert lost
+  `w14:paraId`, bookmarks and direct formatting and reviewed as a deleted and an inserted line; it remains only for shapes the
+  in-place conversion refuses. (It was reject-exact for plain runs but not for markers inside hyperlinks or smart tags, where the
+  Reject All verifier refuses it.)
+- **Operations that would break Reject All are refused by default:** the revision fidelity verifier now runs in
+  `enforce` mode. A refused operation leaves the document unchanged and returns `REVISION_FIDELITY_VIOLATION` with a
+  one-line message naming the invariant, the source paragraph (extraction index and excerpt), expected vs actual, an
+  explanation and a retry instruction; `violations[]`, `invariants` and `recovery.retryGuidance` carry the same detail for
+  agents, the message is also sent to `onWarn`, and compact CLI output keeps it. Opt out per call with
+  `verifyRevisionFidelity: 'warn'` (apply and warn) or `'off'` (diagnosis). CLI: `--revision-fidelity <enforce|warn|off>`,
+  shown in `effectiveOptions`; the agent profile rejects `off`. Capability `revision-fidelity-v1`. A single-target untracked
+  operation (`generateRedlines: false`) is also refused when it changes a paragraph outside its target in the Accept All or
+  Reject All view (invariant `ACCEPT_NEIGHBORS`).
+- **`ACCEPT_INTENT` and numbering-part existence in the revision fidelity check:** a tracked plain-text `redline` with complete
+  `modified` (no Markdown, list-marker or table syntax; single-paragraph targets and `targetEnd` ranges) is refused when Accept All of
+  its target would not read as `modified`. `REJECT_NUMBERING_REFS` also refuses a numId that the output binds or Reject All restores
+  (including inside `w:pPrChange`) when the source did not already use it and no `w:num` -> `w:abstractNum` -> `w:lvl` defines it in the
+  numbering available to the operation. Accept-first range targets now use the exact accepted scope.
+- **`ensureNumberingArtifactsInZip` always merges numbering, and refuses id conflicts:** the optional `mergeNumberingXml`
+  callback is ignored (the single merge is `mergeNumberingParts` in `services/numbering-allocation.js`), an existing
+  `numbering.xml` is no longer replaced when no callback is given, and an incoming `w:abstractNum` / `w:num` whose id exists with
+  different content throws `NUMBERING_ID_CONFLICT` instead of silently binding new paragraphs to another list. `openDocx` also
+  rejects output that introduces a dangling `numId`, `abstractNumId` or `ilvl` (`NUMBERING_*` issues).
+- **Receipt kinds:** a whole paragraph deleted by an empty `modified` reports its deleted paragraph mark with receipt kind `del`
+  (was `structural`); the explicit `1. Header` list conversion now receipts its `w:pPrChange`.
+- **`paragraph-format` keeps the earliest same-author `w:pPrChange` snapshot** and refuses to overwrite another author's pending
+  snapshot (`PARAGRAPH_FORMAT_REVISION_CONFLICT`); see Added.
+
+### Added
+
+- **`redline` + `list-format` on one paragraph in one batch:** a changed-text header (`1. Old` -> `1. New`) is a `redline` that keeps
+  the typed marker exactly (`modified: '1. New'` or `replacements`) plus a `list-format` `convert-plain` of the same paragraph. The
+  batch compiler allows exactly this pair (both bind at batch start) and fixes the order whatever the batch order: the redline runs
+  first, then the list-format strips the unchanged marker, so Accept All shows label `1.` with `New` and Reject All the literal
+  `1. Old` (verified in Word with `ListFormat.ListString`, including a `3.` start value). A single-paragraph `redline` of a list item
+  also composes with a `change-format`/`join` that rebinds it. Incompatible pairs are refused before mutation with
+  `LIST_FORMAT_COMPOSITION_CONFLICT` (`reason`: `marker-changed` with `sourceMarker`/`modifiedMarker`, `redline-unchanged`,
+  `redline-shape`; `recovery.action: split_text_and_list_changes`); other kinds keep `OVERLAPPING_SOURCE_TARGETS` /
+  `REVISION_ORDER_CONFLICT`. No new capability: it is part of `list-format-v1` behavior.
+- **`list-format` `change-format` and `join` modes (`list-format-change-v1`, contract version stays 9):** `change-format` changes
+  the kind or numbering format of an existing list (`format`, `lvlText`, `start`, `level`, default the target's level). It never
+  edits the shared definition: a NEW `w:abstractNum` + `w:num` is allocated with the source levels, indentation and fonts copied
+  and one level redefined (`w:isLgl`, picture bullets and a bullet's symbol font are dropped on a format change), and each item is
+  rebound with a tracked `w:pPrChange`, so Reject All restores the original labels and Accept All shows the new ones (verified in
+  Word with `ListFormat.ListString` after `Revisions.AcceptAll()`/`RejectAll()`: bullets to `1.`, `1.` to `A.`, a nested level to
+  `(i)`, and two range splits). `scope: 'list'` (default) rebinds every live item of the list (`items[].inTarget` marks those outside
+  the target); `scope: 'range'` rebinds a `target`..`targetEnd` range that runs to the end of the list and continues its count
+  (start values on the new definition, including a split that starts at a nested item). `join` binds the target list (or a range
+  running to its end) to the `numId` of `list.continueFrom`, an item of an earlier list, so it continues that count; `continueFrom` is
+  bound at batch start. Tracked-deleted paragraphs keep their `w:numPr`; a same-author earlier `w:pPrChange` snapshot is kept;
+  later operations in a batch see definitions earlier ones allocated. Refused before any write: `LIST_FORMAT_TARGET_NOT_LIST`,
+  `LIST_FORMAT_MIXED_RANGE` (plain paragraphs, several lists, or several levels without `list.level`), `LIST_FORMAT_STYLE_LINKED`
+  (heading/list-style numbering), `LIST_FORMAT_STYLE_NUMBERED`, `LIST_FORMAT_SPLIT_UNSUPPORTED` (`mid-sequence` range,
+  `nested-restart`, `shared-definition` abstract used by another list, `interleaved` join), `LIST_FORMAT_DEFINITION_UNSUPPORTED`
+  (missing definition, `w:lvlOverride/w:lvl`, `w:lvlRestart` in a split), `LIST_FORMAT_JOIN_INVALID` and
+  `PARAGRAPH_FORMAT_REVISION_CONFLICT`; an untracked rebinding outside the target is refused; a no-op is `ok` with a
+  `LIST_FORMAT_UNCHANGED` warning. Results carry `list` (`sourceNumId`, `numId`, `items[]`, `levelStarts` or `continueFrom`).
+  An older CLI refuses the new modes with `INVALID_OPERATION` (`field: list.mode`), so negotiate the capability.
+- **`list-format` operation, `convert-plain` mode (`list-format-v1`):** binds plain paragraphs (a target, or `target`..`targetEnd`
+  in one container) whose text starts with a typed marker (`1.`/`1)`, `A.`/`a)`, `IV.`/`iv.`, `-`/`•`) to a NEW list definition in
+  place. The marker is removed with a tracked `w:del` of exactly the marker text (`strip: 'marker'`, default) and the `w:numPr`
+  binding is a tracked `w:pPrChange`, so Reject All restores the literal marker and the unnumbered paragraph and Accept All shows
+  the list label (verified in Word: `ListFormat.ListString` after `Revisions.AcceptAll()`/`RejectAll()` for `A.`, `1.`, `I.` and a
+  `C.` start value). Each marker's value is the item's value (`startOverride` on the new `w:num`; the label keeps the typed `.`/`)`);
+  consecutive values share one list, a gap starts a new list at the typed value, body paragraphs in the range stay plain, and a
+  later `list-format` in the same batch whose first value continues the previous list joins it. `strip: 'none'` with `format`
+  (and optional `start`) binds without touching the text. Ambiguous or unsupported shapes are refused with recovery envelopes:
+  `LIST_MARKER_NOT_FOUND`, `LIST_MARKER_AMBIGUOUS` (a lone `I.`/`C.` reads as letter or roman; set `list.format`),
+  `LIST_MARKER_UNSUPPORTED` (mixed markers, `2.1.`, `(a)`, a marker inside a hyperlink/field/revision, format mismatch),
+  `LIST_FORMAT_TARGET_IS_LIST`, `LIST_FORMAT_STYLE_NUMBERED` (style-linked numbering; needs `stylesXml` on the bare runner, read from
+  the package by `openDocx`) and `PARAGRAPH_FORMAT_REVISION_CONFLICT`. Body only. Results carry `list` (`format`, `items[]` with
+  `numId`/`value`, `skipped[]`). Schema `$defs.listFormat`, `ListFormatDocumentOperation` in `index.d.ts`.
+- **`paragraph-format.numbering` binding (`paragraph-numbering-binding-v1`, no contract bump):** `properties.numbering` is
+  `{ numId, level? }` (bind the paragraph to an existing list) or `null` (remove its direct list binding), recorded as a tracked
+  `w:pPrChange` so Reject All restores the previous `w:numPr` exactly and Accept All shows the new one (verified in Word with
+  `Document.Revisions.RejectAll()/AcceptAll()` and `ListFormat.ListString`). `w:numPr` is inserted at its CT_PPr position
+  (after `widowControl`, before `suppressLineNumbers`/`spacing`/`ind`; `ilvl` before `numId`). A binding never allocates: an unknown
+  `numId` or undefined level is refused `PARAGRAPH_NUMBERING_NOT_FOUND`. `paragraph-format` now keeps the earliest `w:pPrChange`
+  snapshot for repeated same-author edits (it used to replace it, so Reject All restored the intermediate state) and refuses to
+  overwrite another author's pending snapshot (`PARAGRAPH_FORMAT_REVISION_CONFLICT`). Letter and roman literal-marker headers
+  (`C.`, `iv.`) now convert with their start value instead of restarting at the first item.
+- **List conversion diagnostics (`list-conversion-diagnostics-v1`, no contract bump):** text edits no longer report a silent `ok`
+  when they cannot create list structure. A plain paragraph whose new text starts a list marker returns the warning
+  `LIST_MARKER_NOT_BOUND` (`diagnostics[]` on the operation result, `CODE: message` in `warnings`), or `UNSUPPORTED_LIST_CONVERSION`
+  under the strict policy (`--profile agent`, `--atomic`, or `strictListConversion: true`). A list item whose retained marker asks for a
+  different kind or format than its numbering definition returns `LIST_FORMAT_NOT_APPLIED` / `UNSUPPORTED_LIST_FORMAT_CHANGE`.
+  `listMarkers: 'literal'` on an operation opts out. `paragraph-format.properties` is now a closed schema; unknown keys (such as
+  `spacingAfter`) first produced an `UNKNOWN_PARAGRAPH_FORMAT_PROPERTY` warning (superseded in 0.9.0, see Changed).
+  Independent of `REVISION_FIDELITY_VIOLATION`; compact CLI output keeps `diagnostics` and the error fields.
+
+- **Numbering allocator:** new `services/numbering-allocation.js` (exported from the package root): `allocateNumberingDefinition`
+  (new abstractNum + num with fresh ids, copied level geometry, per-level `startOverride`), `allocateNumberingForReplacement`
+  (same-kind source-list continuation or fresh allocation; tracked-deleted source paragraphs never change `numPr`),
+  `mergeNumberingParts` / `mergeNumberingXmlBySchemaOrder` (now with an `onConflict` option), `canonicalNumberingDefinition` and
+  `validateNumberingIntegrity`. The standalone runner's consumers and the `openDocx` facade merge through the same function;
+  `reuseSourceListNumbering` is replaced by allocator policy.
+- **Revision fidelity verifier:** every tracked operation now checks, on the live DOM and without extra
+  serialization, that Word's Reject All of its output equals Word's Reject All of the source (paragraph count and order,
+  canonical text including breaks and tabs, paragraph properties, `numPr`, hyperlink/field/content-control membership).
+  A mismatch refuses the operation (see Changed); in `warn` mode it is applied with the message in `warnings` and
+  `revisionFidelityViolations`. The Word-semantics simulator is `core/word-revision-semantics.js`, validated against
+  recorded Word 16 Reject All / Accept All results (`tests/fixtures/word-revision-semantics/expectations.json`).
+
+- **`UNTRACKED_CREATED_REVISION` invariant:** an operation with `generateRedlines: false` is refused (default `enforce`) when its
+  output contains a revision id (`w:ins`, `w:del`, moves, `*PrChange`, paragraph-mark and row revisions) that the source did not
+  have. A foreign revision sliced around the edit keeps its element, author and date and is not counted. It reports as
+  `REVISION_FIDELITY_VIOLATION` with `violations[].invariant: 'UNTRACKED_CREATED_REVISION'`, also for range targets.
+
+### Internal
+
+- **Revision fidelity verifier cost cut from about +39% to about +8% per batch:** each verified operation's projections (accepted and rejected views, revision-id signatures, numbering references) are reused as the next operation's baseline, numbering definitions are parsed once per part, and the revision-view projection no longer builds live node lists. No check was weakened.
+- **One paragraph-mark revision helper:** `engine/paragraph-mark-revisions.js` is now the only module that constructs a tracked paragraph mark (`w:ins`/`w:del` under `w:pPr/w:rPr`): `markParagraphInserted`, `markParagraphDeleted`, `setParagraphPropertiesMarkRevision`, `restoreParagraphMarkInserted`, string builders `paragraphMarkRevisionXml` / `paragraphMarkPPrXml`, and `planParagraphMarks` (asserts the Reject All paragraph-count invariants). Document-level shortcuts, list generation, reconstruction, text-to-table and generated tables use it, and `tests/paragraph_mark_single_site_tests.mjs` fails on any other construction site. Output is unchanged except that a new mark `rPr` is placed before `sectPr`/`pPrChange`, an existing mark is replaced rather than duplicated, and the empty-modified shortcut's deleted-mark receipt kind is `del` (was `structural`).
+
+### Fixed
+
+- **A `targetEnd` given as a compact handle (`paragraphId` + `fingerprint`, no numeric `index`) was silently ignored** for a
+  plain `redline`, so only the first paragraph of the range was replaced and the rest stayed in the accepted text. The range is now
+  resolved from the end handle; a range that crosses a table or other container boundary is refused `TARGET_RANGE_INVALID`.
+- **Range replace over empty paragraphs no longer fails receipt reconciliation:** a replacement whose diff deletes only paragraph
+  breaks recorded a paired deletion revision id in the receipt that was never written, so the operation was refused with
+  `RECEIPT_RECONCILIATION_FAILED`. Paired replacement ids are now recorded only when written. The reject-roundtrip matrix
+  treats that code as a failure, not a skipped refusal.
+- **Plain `redline` keeps `w14:paraId` / `w14:textId`:** reconstruction used to rebuild the paragraph without its identity 
+  attributes; the rebuilt paragraph that survives for a source paragraph (not tracked-deleted) now keeps them, once (an inserted
+  split gives them to the paragraph whose mark Reject All keeps). A composed `redline` + `list-format` pair keeps identity.
+- **Text-changed header conversion with direct `keepNext` / spacing is no longer refused `REJECT_PARAGRAPH_PROPS`:** the list
+  fallback's tracked-deleted source paragraph keeps its original `pPr`; the new list paragraph carries the direct properties and
+  the source `w14:paraId`.
+- **`ReconciliationPipeline.executeTableGeneration` inserts a tracked table block:** the public pipeline method generated
+  tracked cell text in untracked rows (the defect `engine/table-mode.js` had); rows now carry `w:trPr/w:ins` so Reject All
+  removes the table.
+- **Separate list conversions in one batch continue one list:** two `redline` operations that turned non-adjacent headers into continuing markers (`A. Header`, `B. Header`) each allocated their own numbering instance, so Word showed `A.`, `B.` (start values) but as two lists, and a later item inserted between them would not renumber. The structural list fallback now uses the batch sequence state `list-format convert-plain` uses: same kind, format and level with a continuing value reuses the previous operation's live `numId` (a `redline` and a `convert-plain` of the same format join one list too); a gap (`A.` then `C.`) or a different format allocates a new instance. Ids still come from `services/numbering-allocation.js`. (Reported against 0.8.4.)
+- **Weak-target localized replacements no longer delete soft-break paragraphs:** a `replacements` edit targeted only by `index` + `exactText` (no `paragraphId`/`fingerprint`) in a paragraph containing `<w:br/>` returned `ok` but tracked the whole paragraph as deleted and inserted nothing, because the batch compiler treated the line break in `exactText` as a multi-paragraph target and skipped replacement compilation. Localized replacements now always bind at batch start, so weak and strong targets behave identically. Every localized replacement also has its accepted result checked against the compiled text before commit (`PATCH_ROUNDTRIP_MISMATCH`, nothing applied), and uncompiled replacements are refused rather than applied.
+- **Reconstruction keeps wrappers and deleted placeholders:** a text edit in a paragraph with a `w:fldSimple` no longer drops the field (Reject All lost its result text); a deleted manual break, tab or inline object is a tracked deletion instead of disappearing; and converting a paragraph to a list keeps hyperlink and content-control containers around the deleted runs, so Reject All keeps the text inside its link. Found by the reject-roundtrip matrix.
+- **Punctuation edits stay surgical:** leading and trailing punctuation are separate diff tokens and unchanged substantive words anchor the re-diff, so "agents and attorneys" -> "agents, attorneys, accountants and other professional advisors" marks only " and" -> "," and the appended items.
+- **Table reconciliation keeps untouched cell paragraphs:** editing one cell of a Markdown table reconciliation collapsed a multi-paragraph cell (for example `LS` plus a trailing empty paragraph) to one paragraph, untracked, so Reject All lost a paragraph. Cells whose only difference is trailing empty paragraphs are now unchanged, and a modified multi-paragraph cell is reconciled paragraph by paragraph (inserted paragraphs carry tracked marks).
+- **Text-to-table redlines insert tracked table rows:** a paragraph range converted to a Markdown table carried tracked cell text but untracked rows, so Reject All left an empty table behind. Rows now carry `w:trPr/w:ins` and tracked cell paragraph marks like other inserted tables.
+- **Explicit-start list conversion is reversible with Reject All:** converting a `1. Header` paragraph to a list bound `numPr` without recording a `w:pPrChange`, so rejecting the tracked deletion of the marker left a numbered item. The binding now records the original paragraph properties (empty `<w:pPr/>` when none) in a receipted `w:pPrChange`.
+- **Reject/Accept All match Word for table cells and `pPrChange`:** rejecting an inserted paragraph mark keeps the cell's last paragraph (empty) instead of dropping it, accepting a fully deleted sole-paragraph table removes the table, and rejecting a `pPrChange` keeps the paragraph-mark `rPr` and `sectPr` instead of discarding them.
+- **Property readers ignore `pPrChange`/`rPrChange` snapshots:** a new `core/current-properties.js` accessor reads only direct `w:pPr`/`w:rPr` children, so a tracked property change no longer makes its historical `numPr`, `pStyle`, `outlineLvl` or `b`/`i` look current. Markdown export, numbering-context detection, list-numbering reuse/overwrite, list-shape checks and captured-entity kind now use it; a usage test fails on new descendant property lookups.
+- **Explicit `1. Header` list conversion works on a bare `document.xml`:** with no numbering part the batch had no numbering id state, so the conversion aborted after recording tracked deletions in the receipt and failed with `RECEIPT_RECONCILIATION_FAILED`. The bare runner now always seeds numbering ids as `openDocx` does, and an aborted conversion no longer records receipt revisions.
+- **`generateRedlines: false` stays untracked under `slice-cross-author`:** the surgical insert computed its nested-revision flag as
+  `!(generateRedlines && ...)`, which is true whenever `generateRedlines` is false, so an inserted word was wrapped in a new tracked
+  `w:ins` (`applyRedlineToOxml` and `applyOperationsToDocumentXml`; `redline`/`replace`, `modified`/`replacements`). It now writes
+  plain runs, like `merge-same-author`, and leaves other authors' revisions intact (a foreign insertion is sliced around the edit).
+- **Table appended after the final paragraph of a pretty-printed document keeps its tracked trailing paragraph:** a whitespace
+  text node between the last paragraph and `w:sectPr` made the retained-paragraph table append believe the table did not end
+  the body, so the body ended with a table and Word added an untracked empty paragraph that Reject All left behind (plugin
+  report R5; Word differential 5 vs 4 paragraphs). The append now skips non-element nodes when deciding. The Word-semantics
+  simulator (and therefore the post-apply verifier) counts the untracked paragraph Word supplies after a body-final table, so
+  the old output is refused with `REVISION_FIDELITY_VIOLATION`. Documents without whitespace between blocks (the plugin's
+  own) were already correct on `Revisions.RejectAll()` and the ribbon; `Document.RejectAllRevisions()` still leaves the
+  tracked-inserted last mark behind (a Word API quirk, see the fidelity plan).
+
 ## 0.8.4
 
 ### Added