JSON and C ABI document comparison

Compare two loaded documents through THPDFJobProcessor.ExecuteLoadedOperationWithComparison, two C ABI handles through hpdf_document_compare_json_v1, or two files through the JSON job processor

Generic modes

type=compare accepts mode values pageCount, pageText, objectCount, renderedImage, full, and structural; the default is structural

The modes retain the native THPDFDocComparison behavior, including page alignment and structural object signatures; objectCount also compares page and object structure

{
  "schemaVersion": 1,
  "type": "compare",
  "mode": "full",
  "render": {"dpi": 72, "colorSpace": "rgb", "colorTolerance": 8},
  "options": {"maxDifferences": 1000, "maxStreamBytes": 1048576},
  "budget": {"memoryBytes": 268435456, "resultBytes": 16777216,
             "outputBytes": 67108864, "timeMilliseconds": 60000, "pixels": 10000000}
}

The result envelope includes comparison, comparisonComplete, identical, documentUpdated=false, elapsed time, and output size; optional binary output contains the comparison JSON without its envelope

Traversal, stream, value, retained-difference, and rendering limits produce status=incomplete, comparisonComplete=false, and identical=false, even when the inspected subset is equal

Contract review

type=compare.contract aligns paragraphs, detects movement, and reports word or sentence insertions, deletions, and replacements with both contexts and locations

{
  "schemaVersion": 1,
  "type": "compare.contract",
  "format": "pdf",
  "side": "after",
  "options": {"granularity": "word", "ignoreRepeatedHeadersFooters": true,
              "excludedLineTexts": ["CONFIDENTIAL COPY"], "maxWorkUnits": 50000000}
}

format accepts json, html, or pdf; JSON is the default, and HTML or PDF requires an output stream or callback

Change kinds are insert, delete, replace, and move; page and paragraph indices are zero-based, character starts are one-based UTF-16 positions, and rectangles cover semantic lines in PDF user space rather than exact glyph quadrilaterals

PDF selects side=before or side=after, verifies the selected document against every semantic page snapshot, adds highlights and Before/After comments, saves a review copy, and always rolls back the source graph transaction

A review PDF is a full rewrite and requires separate signature verification; comparison leaves the borrowed source documents and their signatures unchanged

Options and bounds

Generic options accepts maxObjects, maxEdges, maxPages, maxDepth, maxDifferences, maxStreamBytes, maxTotalStreamBytes, maxValueBytes, and maxPathBytes

Rendering accepts dpi, colorSpace (rgb or luminance), colorTolerance, minimumSimilarity, maxChangedPixelRatio, tileSize, and maxChangedRegions; callback operations do not write heatmaps to the filesystem

Contract options accepts the boolean, margin, similarity, boilerplate, and resource fields from THPDFContractCompareOptions, using camelCase names; granularity is word or sentence

Shared budgets are memoryBytes, outputBytes, resultBytes, timeMilliseconds, pixels, objectCount, and pageCount; options are clamped to these budgets

Memory budgets allocate conservative allowances for both decode paths, rendering pixels, alignment storage, and private output; they are workload limits rather than an operating-system RSS cap, and already-loaded object graphs remain owned by the caller

JSON allocation is checked with a conservative escaped-size estimate, which can reject a result whose eventual UTF-8 representation would fit; HTML uses a conservative character allowance within the output-byte budget

Budget failures return ABI status 8 and cancellation returns status 4; cancellation is cooperative at page, object, stream-block, rendering-object, pixel-row, and alignment boundaries

The C ABI error control envelope has an independent 8 KiB maximum and truncates detail to 1,024 UTF-16 code units, allowing a budget error to be reported when the requested result budget is too small for an error response

Borrowed C ABI handles

Load each handle with its own hpdf_io_v1 source and call hpdf_document_compare_json_v1(handle_a, handle_b, operation); the ABI v1 record layouts and original execute export remain unchanged

operation.input_io must be NULL, result_io must provide write, and optional output_io supplies the artifact; JSON file keys input, otherInput, and output are rejected

Both independent sources may return short random-access reads, and both cancellation callbacks are polled even when their decoded objects are cached; the same handle may be supplied twice for self comparison

Keep input callbacks and their contexts alive for the handle lifetime and active calls, and serialize operations on each handle; handle references are retained until comparison returns

Artifacts are built and validated in private bounded buffers before callback publication; callbacks that fail during publication can retain bytes already accepted, while the source documents remain unchanged

File jobs

{"operations":[{"type":"compare.contract","input":"before.pdf",
  "otherInput":"after.pdf","format":"html","output":"review.html"}]}

password and otherPassword independently unlock the two files; JSON output may omit an output path and remain in the result envelope