Read a document once and compare it many times

[JSv4]

Closes #617.

What was left

#594 removed the redundant work inside one comparison and #616 removed the redundant reads inside one comparison. What remains is the redundancy across comparisons — nothing let a caller say "I already read this document":

• one baseline against many counterparties' markups — the baseline is read N times;
• a version chain A→B→C→D — every interior version is read twice;
• GetConflicts before Consolidate on the same inputs — everything read twice.

The IR read is still the single largest stage of a comparison, so this is the biggest remaining lever.

The snapshot

var baseline = DocxDiff.CreateSnapshot(original);          // read once…
foreach (var candidate in candidates)                      // …reused N times
    yield return DocxDiff
        .CreateComparison(baseline, DocxDiff.CreateSnapshot(candidate))
        .GetRevisions();

The issue flagged two things as needing a decision rather than an assumption, so here they are decided:

What it keys on. Only the input-revision policy reaches a read — PreAcceptInputRevisions and PreserveInputRevisions, which together decide whether the document's own tracked changes are flattened away first. Everything else in DocxDiffSettings is a diff-time or render-time policy, so one snapshot serves comparisons that differ in author, granularity, move detection, format comparison and the rest. That collapses the compatibility key to a single boolean, which is why the type exposes exactly one: InputRevisionsAccepted.

A snapshot handed to a comparison asking for the other policy is rejected with an ArgumentException naming both sides, not silently reused or quietly re-read. Serving it would compare a different view of the document than the caller asked for, and that is the kind of thing nobody notices until much later.

Memory. The type's doc comment says it plainly rather than leaving it to be discovered: a materialized snapshot roots the parsed XDocument of every story, not merely the IR values, because the markup renderer clones source elements out of it. That is what makes the reuse possible, and it means a hundred retained snapshots is a hundred parsed documents. Creation itself is free — nothing is read until a comparison needs it.

One more property worth pinning, and it has its own test: the compatibility pre-flight is a property of the comparison, not of the read. A reused snapshot must not make a caller's OnCompatibilityWarning subscription go quiet on the second comparison.

The N-way half, and a bug it turned up

The issue's closing note — the four consolidate statics each read the full reviewer set independently — is fixed by DocxDiffConsolidation, the N-way twin of DocxDiffComparison. The four statics delegate to a single-use instance, so there is one implementation rather than two to keep in step, and a caller can hold the instance to inspect conflicts and then consolidate without a second read of N+1 documents.

Unifying them surfaced something: of the four entry points, only Consolidate ran the compatibility pre-flight. A caller who set ThrowOnCompatibilityWarning and asked for conflicts, consolidated revisions, or the consolidated edit script was silently never told — the same class of gap #622 closed on the pairwise side, and precisely the failure mode #624 describes (the channel is not observed, so no input reveals it). All four now run the same gate. EveryConsolidateEntryPoint_HonorsTheCompatibilitySubscription pins it against a fixture that genuinely warns, asserting both that the callback fires and that the throwing form throws, for each of the four.

The ripple, and why it is a batch rather than a handle

CLAUDE.md's checklist says a public API addition ripples through every transport. A snapshot, though, is an in-process object holding parsed XML. It cannot cross a process or language boundary, and exposing it as a handle would put a memory-pinning lifetime on transports with no good way to bound it — the worst of both.

So the transports get the workload the snapshot exists for, which is also the shape #594 already established here (CompareProducts → CompareProductsJson → each bridge):

Surface
.NET	DocxDiff.CreateSnapshot, CreateComparison(snapshot, snapshot, settings), CreateConsolidation
Facade	DocxDiffOps.CompareBatchJson, DocxDiffOps.ConsolidateProducts
WASM	DocxDiffBridge.CompareBatchJson
npm	docxDiffCompareBatch + DocxDiffBatchResult / DocxDiffBatchCandidate
stdio + python	docx_diff_compare_batch (sequence → named by index, or a name→bytes mapping)
MCP	docxodus_compare with mode: "fan_out" and outputPaths
Docs	ir_diff_engine.md, docx_agent_server.md, CHANGELOG

One baseline, many candidates, baseline read once, per-candidate products identical to comparing that pair alone. A candidate that fails carries its error instead of products — one malformed counterparty markup must not cost the caller the other ninety-nine. That took a fix during review: the candidate's WmlDocument is now constructed inside the per-candidate try, because WmlDocument's byte-array constructor validates the package type and was failing the whole batch.

The MCP path picked up the N-way win directly: docxodus_compare's consolidate branch called Consolidate and then GetConsolidatedRevisionsJson, reading the base and every reviewer twice. It now uses one ConsolidateProducts pass.

Measured

Four comparisons against one baseline, on the heaviest pair in the corpus (WC-BodyBookmarks-Before/After, 2.8 MB and 1.4 MB of document.xml), alternated in one process:

round 0: statics 8219 ms, shared baseline snapshot 4028 ms
round 1: statics 6526 ms, shared baseline snapshot 4159 ms

The saving is exactly what the mechanism predicts: 8 reads become 5, and the win grows with the fan-out.

Output parity

[parity] OK - all 14,916 digests identical across 678 documents

This one mattered more than usual, because making the consolidate statics delegate switches three of them from ReadOpts to RenderReadOpts — provenance retained. #594 established that provenance is equality-neutral by construction; the corpus confirms it across every fixture.

Suite 4203 passed, 0 failed, 3 skipped. npm test -- tests/docx-diff.spec.ts 11 passed (after a full WASM rebuild). pytest tests/test_docx_diff.py 9 passed. Warning baselines move by exactly two each for the two new files, updated in CLAUDE.md in the same commit.

One unrelated fix, carried here

The #614 CHANGELOG entries were sitting in the [10.0.0] section: that PR inserted at the first ### Fixed heading, and [Unreleased] had no ### Fixed at the time, so the first one was inside the released section. Moved to [Unreleased] where they belong.