JSON 与 C ABI 文档比较

通过 THPDFJobProcessor.ExecuteLoadedOperationWithComparison 比较两个已加载文档，通过 hpdf_document_compare_json_v1 比较两个 C ABI 句柄，或通过 JSON job 处理器比较两个文件

通用模式

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

遍历、流、值、保留差异与 Render 限制会产生 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 需要输出流或 callback

变更种类为 insert、delete、replace 与 move；页面与段落索引从零开始，字符起点是从一开始的 UTF-16 位置，矩形覆盖 PDF 用户空间中的语义行而非精确字形四边形

PDF 选择 side=before 或 side=after，对照每个语义页面快照验证所选文档，添加高亮与 Before/After 注释，保存审阅副本，并总是回滚源对象图事务

审阅 PDF 是完整重写，需要单独的签名验证；比较不改动借用的源文档及其签名

选项与边界

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

Render 接受 dpi、colorSpace（rgb 或 luminance）、colorTolerance、minimumSimilarity、maxChangedPixelRatio、tileSize 与 maxChangedRegions；callback 操作不向文件系统写热力图

契约 options 接受 THPDFContractCompareOptions 的 Boolean、边距、相似度、样板与资源字段，使用 camelCase 名称；granularity 为 word 或 sentence

共享预算为 memoryBytes、outputBytes、resultBytes、timeMilliseconds、pixels、objectCount 与 pageCount；选项被钳制到这些预算内

内存预算为两条解码路径、Render 像素、对齐存储与私有输出分配保守配额；它们是工作负载限制而非操作系统 RSS 上限，已加载的对象图仍归调用方所有

JSON 分配用保守的转义大小估计检查，可能拒绝最终 UTF-8 表示本可容纳的结果；HTML 在输出字节预算内使用保守的字符配额

预算失败返回 ABI 状态 8，取消返回状态 4；取消在页面、对象、流块、Render 对象、像素行与对齐边界处协作检查

C ABI 错误控制包络有独立的 8 KiB 上限，并把细节截断到 1,024 个 UTF-16 码元，当请求的结果预算容不下错误响应时也能报告预算错误

借用 C ABI 句柄

用各自的 hpdf_io_v1 源加载每个句柄，调用 hpdf_document_compare_json_v1(handle_a, handle_b, operation)；ABI v1 记录布局与原始 execute 导出不变

operation.input_io 必须为 NULL，result_io 必须提供写，可选 output_io 提供产物；JSON 文件键 input、otherInput 与 output 会被拒绝

两个独立源都可以返回短随机访问读取，即使已解码对象被缓存，两个取消 callback 也会被轮询；同一句柄可以传入两次做自比较

在句柄生命周期与活跃调用期间保持输入 callback 及其上下文存活，并对每个句柄串行化操作；比较返回之前保留句柄引用

产物在回调发布之前于私有有界缓冲中构建并验证；发布期间失败的 callback 可能保留已被接受的字节，而源文档保持不变

文件 job

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

password 与 otherPassword 分别解锁两个文件；JSON 输出可以省略输出路径并保留在结果包络中