原生 headless 文档对比
HPDFHeadlessCompare 通过 HPDFCompareHeadlessDocuments 对比两个已加载的原生文档；Linux Callback ABI 用 hpdf_document_compare_json_v1（type:compare）暴露同一实现
| Pascal 模式 | JSON 模式 | 对比内容 |
|---|---|---|
| hcmPageCount | pagecount | 页树叶节点数量 |
| hcmPageText | pagetext | 页数与提取的 Unicode 文本 |
| hcmObjectCount | objectcount | 页数与物理在用的交叉引用对象数量 |
| hcmRenderedImage | renderedimage | 页数、Render 尺寸与原生 Cairo 像素 |
| hcmStructural | structural | 页数与归一化的 catalog、information 及不可达对象图 |
| hcmFull | full | 页数与对象数量、归一化对象图、Unicode 文本及 Render 像素 |
结构等价
结构对比会解析间接引用并对字典条目排序、归一化 PDF 名称与字面/十六进制字符串表示，并在用 SHA-256 哈希内容之前解码普通流过滤器
对象编号、序列化顺序与普通流压缩不改变结构等价性；末端图像编码保留其过滤与解码策略，不可达对象则按多重集合比较
加密字典与交叉引用/对象流存储容器不参与语义结构；已认证的 AES R5/R6 内容在解密后比较，并强制执行提取权限
结构差异会报告文档级路径 $Document；物理对象数量仍是独立模式，等价内容使用不同存储布局时可能不同
Render 对比
每个页面都会用原生 Cairo 设备按选定 DPI 实际 Render；解码后的图像像素合成到白底上，再按 RGB 或亮度比较
报告包含尺寸、变化像素数量、最大通道差、平均绝对误差、变化像素比例与相似度；相似度为 1 - meanAbsoluteError / 255
像素的最大通道差超过 ColorTolerance 即视为变化；页面只有在尺寸一致且相似度与变化像素比例都达到配置阈值时才通过
Render 依赖与原生页面 Render 相同的受支持字体、图像编解码器和图形语义；不支持的页面会使对比失败，而不是产出一份相同的报告
有界执行
对比选项约束遍历、深度、对象、解码流、文本准备、结果存储与 Render 像素；取消会传导到遍历、文本提取与 Render
Pascal 对比期间两个文档实例都要保持存活且被独占持有；无论成功、失败还是取消，它们的内容与资源选项都原样保留
Linux ABI 接受上面六个小写模式名，以及与 Pascal 上限严格对应的 options 成员，另有 dpi、colorTolerance、minimumSimilarity、maxChangedPixelRatio 与 colorSpace:rgb 或 luminance
ABI 结果在同步 Callback 发布前已完整就绪并受预算约束；同句柄调用与反序并发调用沿用既有的稳定加锁顺序