Native Linux contract comparison

hpdf_document_compare_json_v1 借用两个已加载文档句柄，运行原生语义合同比较或 general document comparison，并通过回调输出准备好的结果

{"schemaVersion":1,"type":"compare.contract","format":"html",
 "title":"Contract review","options":{"granularity":"word",
 "ignoreRepeatedHeadersFooters":true,"maxAlignmentCells":2000000},
 "limits":{"memoryBytes":268435456,"resultBytes":4194304,"outputBytes":8388608}}

语义合同报告

原生适配器使用与 Windows contract API 相同的可移植段落对齐与差异算法，包括单词或句子级变更、跨页移动、重复页边排除、样板过滤和页面续接

合同报告包含 comparisonComplete、identical、differenceCount、页面与段落计数、排除项、工作与对齐计数器，以及每处变更的文本、上下文和位置

每个位置包含从零计的页面与段落、从一计的字符偏移、字符数，以及覆盖相交语义行的 PDF 用户空间矩形；矩形表示行几何

原生 glyph 提取保留嵌套 Form 资源与矩阵、继承的页面边界，并对明文和已认证 AES R5/R6 输入遵守提取权限；没有可提取文本的页报告提取失败，需要 OCR 或显式删除空白页

选项与限制

options 接受 granularity（word 或 sentence）、ignoreCase、ignoreRepeatedHeadersFooters、normalizeMarginDigits、joinPageContinuations、headerMarginPoints、footerMarginPoints、paragraphGapFactor、minimumParagraphSimilarity、minimumRepeatedPages 和 excludedLineTexts

显式正整数限制包括 maxPages、maxParagraphs、maxSemanticLines、maxCharacters、maxTokens、maxDifferences、maxAlignmentCells 和 maxWorkUnits；操作内存与结果预算在执行前封顶这些限制

compare 接受页数、页文本、对象数、渲染图像、结构和完整模式，并输出 JSON；可用模式通过 comparisonModes 发现，合同格式通过 contractFormats 发现

format:json 把结果 JSON 写到可选的 binary 回调和必需的 result 回调；format:html 要求 binary 回调，输出独立 UTF-8 审阅文件，标题与合同措辞已转义

format:pdf 要求 binary 输出回调，创建 side:before 或 side:after 的真实 annotated review copy，默认 after；options.maxHighlights 限制高亮的语义行数

生命周期与发布

调用期间两个句柄须保持存活；同句柄比较受支持，反序并发比较按稳定顺序获取锁

所有回调在调用线程上同步运行；资源限制临时应用于每个已加载文档并在事后恢复，失败与取消路径同样如此

该调用不接受输入回调或文件路径成员，并保留两个源文档及其修订；binary 与 JSON 输出在发布开始前完成准备并施加边界

Pascal 接口

HPDFCompareHeadlessContracts 接受两个 THPDFHeadlessDocument 对象和既有的 THPDFContractCompareOptions，返回 THPDFContractCompareReport

HPDFHeadlessContractSource 暴露原生适配器；HPDFContractCompareCore 中的 HPDFCompareContractSources 为可移植核心接受自定义的有界页数、语义页和可见框回调

HPDFContractCompareCore 持有共享算法、报告类型和 HTML 渲染器，不依赖 VCL 或 LCL；既有的 HPDFContractCompare Windows 接口通过别名和适配器保留其类型、常量和已加载文档入口

THPDFHeadlessDocument.ExtractPageGlyphs 与 AnalyzePageSemanticText 通过与 ExtractPageText 相同的嵌套内容遍历器暴露定位 glyph 和语义布局

原生 ABI 验收覆盖真实的明文、AES R5/R6 和嵌套 Form 比较、回滚、预算和锁顺序；独立 pypdf 与 MuPDF 阅读器验证完整差异、精确上下文、偏移和源 glyph 几何

Native Linux C ABI · Contract comparison · Remaining delivery plan