Check that a document diff accounts for every difference in its compare models.
A compare model is OneDiff’s in-memory form of a document, made from a real file by an adapter; follow the PDF-loading example, exporting Word documents to PDF first.
dotnet add package RecursiveAI.OneDiff.DocumentsRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using OneDiff.Documents; using OneDiff.Documents.Model; var oldDoc = Doc("Pay in 30 days."); var newDoc = Doc("Pay in 60 days."); var result = Comparison.Of( oldDoc, newDoc, CompareSettings.Strict); Console.WriteLine( result.Verification.Passed); static CompareDocument Doc(string text) { var builder = new CompareDocumentBuilder(); builder.Add(NodeKind.Paragraph, new NodeContent { Text = text }); return builder.Build(); }
TrueUnzip the example, then dotnet run.
Full program
using OneDiff.Documents; using OneDiff.Documents.Model; var oldBuilder = new CompareDocumentBuilder(); var newBuilder = new CompareDocumentBuilder(); oldBuilder.Add(NodeKind.Paragraph, new NodeContent { Text = "Payment within 30 days.", Anchor = Anchor.ForNode("paragraph-0") }); newBuilder.Add(NodeKind.Paragraph, new NodeContent { Text = "Payment within 60 days.", Anchor = Anchor.ForNode("paragraph-0") }); var settings = CompareSettings.Strict; var alignment = Stages.Align(oldBuilder.Build(), newBuilder.Build(), settings: settings); var pairDiffs = Stages.DiffPairs(alignment); var changes = Stages.Classify(Stages.Group(pairDiffs)); var result = Stages.Verify(changes); Console.WriteLine($"Changes: {result.Changes.Length}"); Console.WriteLine($"Passed: {result.Verification.Passed}"); Console.WriteLine($"Verified here: {result.Verification.VerifiedHere}"); Console.WriteLine($"Fallback level: {result.Verification.FallbackLevel}"); Console.WriteLine($"Earlier failures: {result.Verification.FailureCount}"); Console.WriteLine($"Recheck failures: {result.Check().Length}");
dotnet run prints:
Changes: 1 Passed: True Verified here: True Fallback level: 0 Earlier failures: 0 Recheck failures: 0
Strict hides no categories and enables ThrowOnFailure: a failed verification throws ComparisonVerificationException instead of falling back.
Variations
After the full program, allow fallback and inspect its level and diagnostics:
var checkedAgain = Comparison.Of(result.Old, result.New, new CompareSettings { ThrowOnFailure = false }); Console.WriteLine($"Fallback: {checkedAgain.Verification.FallbackLevel}"); foreach (var diagnostic in checkedAgain.Diagnostics) Console.WriteLine(diagnostic.Code);
Fallback: 0Related recipes
Audit hidden whitespace differences
The short answer
Use Comparison.Of for the complete pipeline, or call Stages.Verify after alignment, pair diffing, grouping and classification when working with individual stages. Read Verification.Passed, VerifiedHere, FallbackLevel and FailureCount. Set ThrowOnFailure when a failed verification must stop the comparison instead of producing a coarser fallback.
The check is over the compare models under the selected settings. It checks that the edits replay in both directions, that changes have the expected text and anchors, that groups account for changes, and that the ledger accounts for hidden differences. It is not a statement that an extraction adapter captured everything in an original file.
How do I verify document diff completeness in C#?
The full program builds two paragraphs with explicit anchors and changes a payment term from 30 to 60 days. Stages.Verify runs after Stages.Classify; it does not replace alignment or generate a diff from two strings on its own. The printed result has one change, passes in this process, and has no fallback or earlier failures.
Replay is checked old to new and new to old across the compared text and formatting. Attribute edits are checked in both directions too. Verification also checks node coverage: visible nodes must be linked or accounted for as inserts and deletes. A successful word-level edit is not enough if another paragraph was omitted.
Anchors are checked against what the compare model resolves for each change side. In this example each paragraph uses the synthetic reference paragraph-0. A real source adapter supplies meaningful source locations. The comparison engine copies those anchors; it does not interpret an adapter’s opaque reference as a physical file location.
How do I check a document diff again?
Call result.Check() as the full program does. It returns the failures found by rerunning the completeness checks and leaves the immutable result’s original Verification record unchanged. Zero failures means the recheck passed; print or handle the failures if the array is nonempty.
The distinction matters for stored comparisons. VerifiedHere says whether verification ran in the current process on this value. A comparison read from JSON with verification disabled has not earned that claim merely because serialized metadata says an earlier run passed. The JSON reader verifies by default; if verification is deliberately skipped, rerun Check before treating the result as checked content.
Groups are presentation, not the underlying edit data. Verification checks that group IDs are valid and that every change belongs to exactly one group. It also checks the hidden-difference ledger independently. A result is not complete merely because its visible edits look plausible.
What happens if document diff verification fails?
With ThrowOnFailure = true, the engine throws ComparisonVerificationException. CompareSettings.Strict selects that behavior and hides no categories. It is appropriate when a verification defect should stop downstream processing rather than change the granularity of the output.
Without strict failure handling, the engine retries increasingly coarse representations. It first regroups using the fallback stages on the same alignment, then replaces changed blocks as wholes, then uses unaligned block deletions and insertions. Each fallback is checked again. FallbackLevel identifies the representation retained, while diagnostics record failures and the fallback warning.
A passing fallback is complete but may be less useful to a reviewer who expected small edits. Decide separately whether your application accepts that presentation. Passed alone does not tell you whether fallback occurred. The variation prints the level and any diagnostic codes; the sample takes no fallback path.