Remove the WmlComparer engine in favour of DocxDiff

[JSv4]

Removes WmlComparer, the legacy comparison engine, and carries that through every surface that touched it. Breaking, for v11.0.0.

DocxDiff has been the default since v8.0.0. This deletes the alternative rather than keeping a second, feature-frozen engine alive behind a selector.

What this actually cost, before the diff

The four parity scoreboards checked DocxDiff by running it head-to-head against WmlComparer over the WC corpus. They could not outlive their own oracle, so the first commit freezes what they prove while both engines still exist. That is deliberately a separate commit, so the evidence lands before anything is deleted.

Two artifacts, doing different jobs:

• docs/architecture/wmlcomparer_parity_baseline/ — the four reports verbatim from their final run against a live WmlComparer. A historical record; nothing can re-derive it now. It answers "was the IR engine ever actually checked against the thing it replaced, and on what": 179 runnable cases at 177 pass / 2 documented deviations, 39 markup cases all pass, 84 Consolidate cases all reproduce, and 184 differential comparisons at 117 MATCH / 18 GRANULARITY / 47 catalogued DIVERGENT / 2 pairs the legacy engine threw on and DocxDiff handled.
• DocxDiffCorpusBaselineTests + DocxDiffCorpusBaseline.tsv — the live replacement. Same 92 pairs, both directions, both granularities (368 rows), pinning DocxDiff's own per-kind multiset of normalized revision text. Verified 368/368 reproduce. It pins the multiset rather than a count, so a regression that swaps which text is inserted while keeping the tally still fails. Four whole-document-rewrite rows collapse to a SHA-256 over the same encoding (they were 728 KB each; the median row is 93 bytes), which took the file from 1.65 MB to 48 KB without weakening it.

What was kept

The cross-package merge helpers — CopyMissingStylesFromOneDocToAnother, CopyMissingNumberingFromOneDocToAnother, MoveRelatedPartsToDestination and their private helpers — move verbatim to Docxodus/PackageMerge.cs. They copy styles, numbering definitions and related package parts between two packages; none of it is comparison logic, and DocxDiff's markup renderers have always called them. The move is byte-for-byte with the #nullable disable header intact, so a regression there can only come from a later edit rather than from the extraction.

This corrects a claim in CLAUDE.md: it said DocxDiff depends on WmlComparer's types, so the engine was not removable. DocxDiff referenced those types only in doc comments. The real dependency was these three helpers, which the compiler found immediately.

The one thing most likely to break a caller silently

DocxCompare.Compare always applies PreAcceptInputRevisions; the raw DocxDiff API leaves it opt-in. That is the difference between Word-like behaviour and whole-document churn on revision-bearing inputs, and it used to be buried in a settings mapping that no longer has a reason to exist. It is now ApplyFrontDoorRevisionPolicy, applied to a clone so a caller's settings object is never mutated, and pinned by tests. Anyone moving a call from DocxCompare.Compare to DocxDiff.Compare must set that flag to keep their current output.

This branch originally applied PreAccept and PreserveInputRevisions, faithfully reproducing the pre-v11 mapping. #644 landed on main while this was open and established that preserving is wrong on this surface — Word's Compare dialog says it treats existing revisions as accepted, and the preserve behaviour had been decoded from oracle documents that turned out to be Combine-shaped. That is a correctness fix and this branch was only carrying old behaviour forward, so the merge takes main's policy and keeps this branch's structure. Preservation remains an explicit opt-in on the raw API.

getRevisions: the one genuine capability gap

The legacy call read ONE already-redlined document; DocxDiff.GetRevisions needs both sides, so it was not a drop-in. It now reads the document's own markup through DocxSession.ListRevisions, which was already wired through every transport. Consequences, all intended:

• The move knobs (detectMoves, moveSimilarityThreshold, moveMinimumWordCount, caseInsensitive) are gone. They existed because the old call re-derived moves with a Jaccard threshold over a document that already carried w:moveFrom/w:moveTo markup. The moves in the document are now simply the moves.
• A move is ONE entry, not a source/destination pair, and is only emitted when both halves are present with paired range-marker ids — a strictly stronger statement about the markup than two halves were. moveGroupId, isMoveSource, and the isMoveSource/isMoveDestination/findMovePair helpers go with them.
• npm's getRevisions returns RevisionListEntry — the shape the session's own listRevisions already returned — and the WASM export returns DocxSessionJson.SerializeRevisionList verbatim. A dedicated DTO was written first and then deleted: it would have forked one concept into two wire shapes (PascalCase families on one path, snake_case on the other), which is what the single-owner rule exists to prevent.
• Because the reported type is now the markup-level name (ins/del/moveFrom), isInsertion/isDeletion/isMove/isFormatChange would have silently matched nothing. They test family instead.

A capability that is genuinely lost

Some older Word documents put tracked-revision wrappers inside an Office Math run — schema-invalid markup that WmlComparer's preprocessing repaired as a side effect. DocxDiff does not repair it. Measured on WC012-Math-After.docx: source has one validation error, DocxDiff's output has the same one error, and the bytes do not change.

So the guard in CanReturnExactNoOp that refused the byte-identical shortcut for such documents was buying nothing but a full comparison returning the same bytes. It is removed, CanReturnExactNoOp is now plain byte equality, and a test pins the honest behaviour: invalid input passes through unrepaired rather than being silently rewritten. Tracked as #642 rather than left implicit. (The strict-OOXML normalization #644 added to that same shortcut is independent and is kept — a strict left is still normalized to transitional on the way out.)

Tests

The 73 WmlComparer-specific tests go. Tests that used the engine only to synthesize a redline fixture now use DocxCompare. Two needed real thought:

• RP001 compared an accepted baseline against processed output by counting revisions between them. Routed through the front door it saw the inputs' own preserved markup as a difference, and the engine additionally reports a paragraph-mark change as an empty-text revision, which the legacy reader dropped by its own normalize-and-drop-if-empty rule. It now asks the engine directly with pre-accept on and applies that same empty-text rule. (My first attempt at this turned one failure into eight; the fix came from dumping what was actually reported rather than guessing.)
• The move-markup test asserted the reader saw two Moved revisions. One grouped entry is the correct equivalent, so it now also asserts the entry is Supported and carries no diagnostic — otherwise weakening the count would have been indistinguishable from hiding a regression.

The fuzz test keeps its own-oracle half and replaces the differential half with the same signal that half existed to catch — a comparable case producing zero revisions — pinned as a constant, since every case is a pure function of its seed. Corpus data outliving its tests (the WC003 row list, the expected-schema-error list) moves to files of its own. The four WmlComparer design docs are banner-marked historical rather than deleted; they record Word-behaviour findings DocxDiff inherited or deliberately diverged from.

Two problems surfaced only by actually running things, not by the compiler:

• worker.spec.ts asserted firstRevision.revisionType, a field that no longer exists on RevisionListEntry (the kind is type). TypeScript could not catch it because the assertion runs inside page.evaluate on an any. Fixed by asserting the fields the entry really carries — id / author / type / family / resolutionStatus — rather than narrowing the test until it passed.
• Merging main brought in DocxDiffStrictConformanceTests.cs cleanly — git reported no conflict, because this branch never touched that file — but Render-fidelity round: package tolerance, section defaults, style provenance, and Word-Compare input-revision policy #644's new selector test calls the removed ComparisonEngine and WmlComparerSettings. Two compile errors inside a file git considered resolved. Rewritten against the front door rather than dropped, since the strict-identity assertion is worth keeping.

Verification

Measured on the current head, 3caeecc (the merge of main @ e605d62). "Before" is main.

	before	after
Library warnings	135	133
Test warnings	782	716
.NET suite	—	3,918 passed, 0 failed, 3 skipped
Browser suite (Playwright, CI)	—	669 passed, 0 failed, 10 skipped
Suppressed nullable sites (all 21 files stripped)	3,443	2,907
NoWarn sites (CS8073/CA2200/CS8632)	35	32

536 nullable warnings retired — 16% of the total; PackageMerge.cs carries 31 of the engine's forward, and the opt-out file count stays at 21 because that file inherited the header. The NoWarn list barely moves: of the 4 sites WmlComparer held, 1 came back with PackageMerge.cs, so all three codes stay suppressed. The remaining nullable debt is now tracked in #645 and its sub-issues (#646–#651).

Also verified: redline CLI builds; WASM builds and publishes at 3656 KB wire size against a 4096 KB budget; npm run build and tsc --noEmit clean.

Closes nothing on its own; #642 tracks the math-run repair.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XvfkMu2yXDS41AQ7256YxT

[JSv4]

Browser suite result, as promised in the description.

659 passed, 10 skipped, 10 failed. One of those failures was real and is fixed in 299378b; the other nine are this sandbox, not the diff.

The real one

worker.spec.ts › getRevisions extracts revisions from compared document asserted firstRevision.revisionType was defined. It wasn't. getRevisions now returns RevisionListEntry, whose markup-level kind field is type — revisionType belonged to the shape this PR removes. The test was asserting a field that no longer exists, so it failed for exactly the right reason, and the typechecker couldn't catch it because the assertion runs inside page.evaluate on an any.

Fixed by asserting what the entry actually carries — id, author, type, family, resolutionStatus — rather than narrowing the test until it passed. Also corrected the RevisionType enum's doc comment, which still described it as matching WmlComparerRevisionType; it matches DocxDiffRevisionType and belongs to the docxDiff* APIs, which is precisely the distinction this failure was about.

The 8 affected chromium specs pass after the fix, and tsc --noEmit is clean.

The nine that aren't this PR's

Failures	Cause
6 × demo-arcade-doom.spec.ts, 1 × demo-arcade-mobile.spec.ts	The page's dynamic import() of cdn.jsdelivr.net/gh/grubbyplaya/doomgenericjs@… fails inside the browser sandbox. The shell in this container reaches that URL (HTTP 200); the page context does not.
2 × firefox-cross-block-selection	browserType.launch: Executable doesn't exist at /opt/pw-browsers/firefox-1497/firefox/firefox — only Chromium is installed here.

Neither spec file is touched by this PR (git diff --name-only origin/main...HEAD lists neither), and both failure modes are environmental rather than behavioural. CI runs these on its own runners, where both the CDN fetch and the Firefox binary are available — so treat CI's verdict on them as authoritative over mine, not the other way round.

---

Generated by Claude Code