JSON 與 C ABI 文件比較

透過 THPDFJobProcessor.ExecuteLoadedOperationWithComparison 比較兩份已載入文件、透過 hpdf_document_compare_json_v1 比較兩個 C ABI handle，或透過 JSON job processor 比較兩個檔案

通用模式

type=compare 接受 mode 值 pageCount、pageText、objectCount、renderedImage、full 與 structural；預設為 structural

這些模式保留原生 THPDFDocComparison 的行為，包括頁面對齊與結構物件簽章；objectCount 也會比較頁面與物件結構

{
  "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}
}

結果信封包含 comparison、comparisonComplete、identical、documentUpdated=false、耗時與輸出大小；選填的二進位輸出內容是不含信封的比較 JSON

遍歷、串流、值、保留差異與轉譯上限會產生 status=incomplete、comparisonComplete=false 與 identical=false，即使已檢查的子集完全相等也一樣

契約審閱

type=compare.contract 會對齊段落、偵測移動，並回報文字或句子的插入、刪除與替換，同時附上兩側的上下文與位置

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

format 接受 json、html 或 pdf；預設為 JSON，HTML 或 PDF 則需要輸出串流或回呼

變更種類為 insert、delete、replace 與 move；頁面與段落索引從零起算，字元起始位置是從一起算的 UTF-16 位置，矩形涵蓋 PDF user space 中的語意行，而不是精確的字形四邊形

PDF 會選擇 side=before 或 side=after，對每個語意頁面快照驗證所選文件，加入高亮與 Before/After 註解，儲存審閱副本，並一律回溯來源圖形的交易

審閱 PDF 是完整重寫，需要另外驗證簽章；比較本身不會更動借用的來源文件與其簽章

選項與界限

通用 options 接受 maxObjects、maxEdges、maxPages、maxDepth、maxDifferences、maxStreamBytes、maxTotalStreamBytes、maxValueBytes 與 maxPathBytes

轉譯接受 dpi、colorSpace（rgb 或 luminance）、colorTolerance、minimumSimilarity、maxChangedPixelRatio、tileSize 與 maxChangedRegions；回呼作業不會把熱區圖寫入檔案系統

契約 options 接受 THPDFContractCompareOptions 的布林、邊界、相似度、樣板與資源欄位，採用 camelCase 名稱；granularity 為 word 或 sentence

共用的預算為 memoryBytes、outputBytes、resultBytes、timeMilliseconds、pixels、objectCount 與 pageCount；選項會被限制在這些預算內

記憶體預算為兩條解碼路徑、轉譯像素、對齊儲存與私有輸出配置保守額度；它們是工作負載上限，不是作業系統 RSS 上限，已載入的物件圖仍由呼叫端持有

JSON 配置以保守的跳脫後大小估計檢查，可能因此拒絕一個最終 UTF-8 表示其實放得下的結果；HTML 在輸出位元組預算內使用保守的字元額度

預算失敗回傳 ABI 狀態 8，取消回傳狀態 4；取消是合作式的，發生在頁面、物件、串流區塊、轉譯物件、像素列與對齊等邊界

C ABI 錯誤控制信封有獨立的 8 KiB 上限，並把明細截斷到 1,024 個 UTF-16 code unit，因此當要求的結果預算小到連錯誤回應都放不下時，也能回報預算錯誤

借用的 C ABI handle

為每個 handle 載入各自的 hpdf_io_v1 來源，並呼叫 hpdf_document_compare_json_v1(handle_a, handle_b, operation)；ABI v1 記錄版面與原始 execute 匯出維持不變

operation.input_io 必須為 NULL，result_io 必須提供 write，選填的 output_io 提供成品；JSON 檔案鍵 input、otherInput 與 output 會被拒絕

兩個獨立來源都可以回傳短隨機存取讀取，即使解碼後的物件已被快取，兩個取消回呼仍會被輪詢；同一個 handle 可以傳入兩次做自我比較

輸入回呼與其 context 必須在 handle 生命週期與呼叫進行期間保持存活，並在每個 handle 上序列化執行作業；handle 參照會保留到比較回傳為止

成品會先在私有且有界緩衝區中建構與驗證，再透過回呼發布；發布期間失敗的回呼可能保留已收下的 bytes，來源文件則維持不變

檔案作業

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

password 與 otherPassword 分別解鎖兩個檔案；JSON 輸出可省略輸出路徑，只留在結果信封中