docvortex 0.5.1__tar.gz → 0.5.2__tar.gz

{docvortex-0.5.1 → docvortex-0.5.2}/Cargo.lock

@@ -2,15 +2,35 @@
 # It is not intended for manual editing.
 version = 4
 
+[[package]]
+name = "bitflags"
+version = "2.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
+
 [[package]]
 name = "docvortex-core"
 version = "0.1.0"
 
+[[package]]
+name = "docvortex-pdfium"
+version = "0.1.0"
+dependencies = [
+ "parking_lot",
+]
+
 [[package]]
 name = "docvortex-python"
 version = "0.1.0"
 dependencies = [
  "docvortex-core",
+ "docvortex-pdfium",
  "pyo3",
 ]
 
@@ -26,12 +46,44 @@ version = "0.2.189"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
 
+[[package]]
+name = "lock_api"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965"
+dependencies = [
+ "scopeguard",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
+[[package]]
+name = "parking_lot"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a"
+dependencies = [
+ "lock_api",
+ "parking_lot_core",
+]
+
+[[package]]
+name = "parking_lot_core"
+version = "0.9.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "redox_syscall",
+ "smallvec",
+ "windows-link",
+]
+
 [[package]]
 name = "portable-atomic"
 version = "1.15.0"
@@ -114,6 +166,27 @@ dependencies = [
  "proc-macro2",
 ]
 
+[[package]]
+name = "redox_syscall"
+version = "0.5.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
+dependencies = [
+ "bitflags",
+]
+
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+
+[[package]]
+name = "smallvec"
+version = "1.16.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f9395f0f0eee849a9b707b2f06bb92a6a422090e2123bb2ef8e87a0e61892a8e"
+
 [[package]]
 name = "syn"
 version = "2.0.119"
@@ -136,3 +209,9 @@ name = "unicode-ident"
 version = "1.0.26"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"

{docvortex-0.5.1 → docvortex-0.5.2}/Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["rust/docvortex-core", "rust/docvortex-python"]
+members = ["rust/docvortex-core", "rust/docvortex-pdfium", "rust/docvortex-python"]
 resolver = "2"
 
 [profile.release]

{docvortex-0.5.1 → docvortex-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docvortex
-Version: 0.5.1
+Version: 0.5.2
 Summary: A fast, multi-format document parsing and conversion engine
 License-Expression: MIT
 Project-URL: Repository, https://github.com/myhloli/DocVortex

{docvortex-0.5.1 → docvortex-0.5.2}/docs/ARCHITECTURE.md

@@ -10,6 +10,7 @@ batch computations and their Python bindings. They are built and released togeth
 | --- | --- |
 | `src/docvortex/` | Importable Python package and runtime resources |
 | `rust/docvortex-core/` | Python-independent numeric kernels and Rust contract tests |
+| `rust/docvortex-pdfium/` | Same-library PDFium ABI, object/path reading and synchronized font callbacks |
 | `rust/docvortex-python/` | PyO3 argument validation, conversion, bindings and PDFium bridge |
 | Root `pyproject.toml`, `setup.py`, `MANIFEST.in` | Python metadata, optional extension build and source distribution |
 | Root `Cargo.toml`, `Cargo.lock`, `rust-toolchain.toml` | Shared Rust workspace, dependencies and compiler |
@@ -58,8 +59,9 @@ Python document/PDF algorithms
         -> Python-owned objects and parsing decisions
 ```
 
-Python retains Unicode/text interpretation, public objects, algorithmic decisions and
-reference implementations. The core crate does not access Python objects or PDFium.
+Python retains the public objects, top-level document pipeline and reference implementations.
+Rust also owns continuous text grouping/visual preparation/typography and prepared table-corridor computations.
+Unicode classifications are prepared using the active Python version before detached Rust computation. The core crate does not access Python objects or PDFium.
 Bindings validate transport records and preserve Python error and object-reuse
 semantics. Numeric work releases the GIL only at the existing explicit boundaries.
 
@@ -69,9 +71,9 @@ It does not load another PDFium library, take ownership of handles or close them
 Subsequent numeric geometry conversion can release the GIL after reading finishes.
 
 `DOCVORTEX_COMPUTE_BACKEND=python|rust|auto` selects the backend once per process.
-`python` never imports the extension; `rust` requires a compatible extension; `auto`
+The default is `auto`, preferring a compatible Rust extension. `python` never imports the extension; `rust` requires a compatible extension; `auto`
 falls back on a missing or incompatible extension. Computation errors propagate.
-The current private protocol is **6**. Rebuild an editable extension after changing
+The current private protocol is **22**. Rebuild an editable extension after changing
 native sources and restart processes that cached the backend. Module-only refactors
 preserve the protocol and all Python-visible registrations.
 

docvortex-0.5.2/docs/pdf-native-kernel-next.md

@@ -0,0 +1,89 @@
+# PDF 原生内核：串行执行任务计划
+
+> 2026-09-27 默认策略更新：用户认可当前性能并明确要求切换。默认计算和渲染配置均为 `auto`：计算优先兼容 Rust，扩展缺失或不兼容时回退 Python；渲染选择 `session`，会话内部沿用计算后端。计算或渲染运行错误直接传播，不自动重试旧实现。显式 `rust` 要求兼容扩展；`python` 及 `legacy` 渲染保留用于回退。下文“不切换默认”的记录属于此前阶段，不再代表当前策略；原 Rust 基线的两倍目标仍未达成，不据此宣称 P0–P5 全部完成。此默认调整不等于合并或发布。
+
+## 当前执行约束
+
+用户已于 2026-09-27 要求恢复执行：不使用子代理，按本计划逐步推进，速度提升优先，进程树峰值 RSS 上限放宽为基线的 130%。此前暂停报告保留为历史证据；未满足质量及性能门槛前，不切换默认后端、不发布或合并。最初暂停批次冻结在 `output/pdf/native-kernel-20260927/candidate-stage4`、`mineru-stage4`；其历史报告保留在 `STAGE4-REPORT.md`。恢复后已推进至协议 22 的 `candidate-stage17b` / `mineru-stage8`，原始输入仍为同目录 `inputs`，每份报告记录实际源码与扩展摘要。
+
+协议 12 已将原始文本读取、坐标处理、去重和组行接入 Rust 自有快照，Flash 和 MinerU 复用文本证据。仍不能将此称为 P0–P5 全部完成，也没有证据支持切换默认实现。
+
+## 已完成的恢复批次
+
+- 阶段 5 已消除四份栅格化退化，32 份输入栅格化中位数总和降低 22.65%；协议 12 双 wheel 本机集成通过，远端 CI 重跑受网络阻断。详见 `rust-pdf-stage5-render.md`。
+- 已建立真实 medium 模型录制/回放，32 份模型输入与完整输出一致，并独立完成分阶段 profiler。高档位真实回放、完整冷启动和更细分账仍待补齐。
+- 阶段 6 协议 13 原生字符归属通过验收：真实 medium 共享入口中位数总和降低 26.78%，最大 RSS 比 93.04%，没有超过 5% 的单样本退化。详见 `rust-pdf-stage6-text.md`。
+- 阶段 7–14 已推进正文组装、样式/上下标和全文几何复用；当前优先事项见下面检查点。历史阶段 4 冻结记录仅用于追溯，不表示当前源码状态。
+
+## 当前检查点与待验证工作
+
+协议 22（`f96a566`）将 Flash 文字样式检测直接接入 Rust 文本快照，整段完成粗体、装饰线、分式排除和样式区间；只传行成员 ID，保留公开可变输入的参考入口。32 份公开和实际 medium 回放一致，5344 项完整测试、实际双 wheel 及三组跨平台 CI 通过。正式累计耗时降幅：公开 29.51%、Flash 文本 33.82%、共享路径 39.30%；无持续退化，RSS 满足 130% 上限，仍未达到 2 倍目标。完整证据及失败/中断记录见 [阶段 17 报告](rust-pdf-stage17-inline-styles.md)。[阶段 16 取图](rust-pdf-stage16-bitmap-crops.md)、[阶段 15 候选](rust-pdf-stage15-table-candidates.md) 和以下协议 16 记录均作为历史证据保留。
+
+协议 16 / DocVortex `34fb8c5` 已完成原始分类统计、上下标字体复用和整页 worker 调度调整；MinerU 检查点 `739ad39f`。最终 32 份公开解析耗时降低 13.77%，31 份 Flash 文本降低 19.76%，32 份真实 medium 共享链路降低 41.41%；对应最大 RSS 比为 108.66%、108.30%、93.08%。全部输出一致，无持续超过 5% 的单样本退化。冷启动降低 21.49%，八样本连续资源检查通过。
+
+实现提交的 DocVortex 39 项 CI、原生 wheel 矩阵及 MinerU 9 个联合安装组合全部通过。此前网络、测试导入和 Windows 编码阻断已解决。详见 [完整本批报告](rust-pdf-stage11-classification-render.md)。未合并、发布或切换默认，三条链路均未达到 50% 目标。
+
+下一批按 [P4 执行计划](pdf-native-kernel-p4-execution.md) 深入自有文本读取、对象可见性/路径读取和视觉证据物化：先区分 PDFium 固定工作、重复属性查询和 Python 对象组装，再推进页面数据的连续 Rust 消费。样式检测已在同源 Flash 路径迁移；公开可变输入、链接、表注、候选发现、X/Y 和最终布局的剩余规则继续保留。分类/正文原始统计复用、矢量快照和 Rust 文档所有权尚未完成，高档位、WebUI、当前协议冷启动和长期资源验收独立进行。
+
+以下恢复清单保留历史任务背景：阶段 5–11 已完成的退化修复、联合 wheel、medium 回放和冷启动不再重复执行；尚未完成项继续按实测热点推进。
+
+## 恢复后的优先顺序
+
+### 1. 先关闭本轮验收缺口
+
+- 依据本轮逐文档正式结果定位持续超过 5% 的耗时退化，保留首次和反序复测；先复现再修改，不用新的汇总掩盖失败样本。
+- 本轮优先复现四份栅格化失败：`2407.00079v4_origi-10.pdf`、`IEBM_A_2667169_O-5.pdf`、`fund_asset_and_transaction_tables.pdf`、`49.-.pdf`。反序复测分别退化 27.52%、23.01%、10.49%、17.35%；从定向会话的打开/关闭、通信及像素传递分账定位，不能用文字提取收益抵消栅格化阶段退化。
+- 修复 Windows 超时测试对 `timeout=1e-9` 的不确定假设：实际建立 worker 后使用可控时钟或确定过期的 deadline，继续验证异常、进程退出和输入资源释放。同步修复 MinerU 同类测试，不修改业务超时以迁就测试。
+- 联合安装 CI 的逐文件来源与 ABI 校验已通过，但 9 个任务均在测试收集时因 `_span_test_utils` 无法导入而停止。保留 `python -I` 与 `--import-mode=importlib`，仅显式开放该测试辅助模块所在目录，避免将仓库源码重新放入导入路径；修复后重跑全部组合，不能将“来源校验通过”称为集成测试通过。
+- 为协议 12 再构建实际 wheel，独立安装 DocVortex 与 MinerU；核对包来源、协议、扩展摘要和全部 wheel 文件，运行三平台安装与正确性矩阵。已有协议 11 wheel/CI 结果不代替协议 12 验收。
+- 将语义不变的最终二进制纳入完整三方字符回放，补充 xhigh 真实共享入口及浏览器/真实模型集成。已有 medium/high 冻结回放不等于全部档位完成。
+
+交付：可审阅提交、完整差异清单、跨平台 CI 与实际双 wheel 组合证据；功能、性能、CI 和发布状态分别报告。
+
+### 2. 补齐 P0 的全链路分账
+
+- 建立第三条完整 MinerU 共享链路的冻结模型输出回放，实际包含栅格化、字符提取、文本证据、原生表格和素材处理；模型推理单列。现有文本/表格原语和输入服务基准仅作为阶段诊断。
+- 为导入、字体初始化、PDFium 读取与渲染、Python 对象物化、Rust 计算、IPC、复制、编码建立可核对的分账，区分独占时间与嵌套累计时间。
+- 独立测量新进程冷启动；预热仅复用正常运行时及进程池，不复用前一文档的分析结果。将 32 PDF／299 页扩充到长文档、扫描、图像密集和复杂裁剪样本。
+- 对三条链路分别计算逐文档中位数之和，并报告 PDFium 固定工作量所限制的加速上限。若实际可优化占比不足以达到 2 倍，明确目标差距，不调整口径。
+
+交付：三链路统一基准及全量输出、时间、同时刻进程树峰值 RSS 报告。
+
+### 3. 完成原生数据所有权和分类复用（P1/P2）
+
+- 将矢量、路径、链接与注释从 Python 兼容存储迁入不可变 Rust 页面模型；算法层保留整数来源 ID，不接触 PDFium 指针。
+- 在同一 PDFium 库与运行时锁下逐步迁移文档、页面、文本页的所有权；用异常退出、重复关闭、回调失败和关闭后访问快照验证生命周期。
+- 分类先新增原始统计批次，保留 generated 字符、Unicode map error、bounded text 和原始字体字节。不要从已经去重的 canonical 快照反推原始统计。
+- 保留分类所需的 pypdf 文档结构探测；字体资源对象、内容流操作符和嵌套 Form 次数不能替换为字体名称推断。明确分类字体名 UTF-8 ignore 与文本提取 replace 的语义差别。
+- 缓存抽样页的去重前原始列或分类摘要，限制驻留；后续窗口消费后释放。消除剩余表格/旋转文本填充的重复物化，并保持显式可变几何输入的优先级。
+
+交付：分类完整统计及最终结果等价；主路径不逐字符往返 Python；快照内存不随文档数量持续增长。
+
+### 4. 完成渲染与取图缓冲（P3）
+
+- 保留定向 open/task/close/ack 协议、文档句柄复用和并发预算；先根据实测分账确定临时像素文件、编码、IPC 与父进程复制的成本。
+- 实现独立像素缓冲及带所有者的 NumPy/PIL 适配，验证消费者仍引用时不能提前回收；共享内存超时、取消和崩溃均可清理。
+- 合并同页裁图并复用整页图，维持原编码器与栅格参数。局部渲染另批验证 CropBox、旋转、透明度、边缘与像素对齐后再启用。
+- 连续处理同时检查实际 OS worker 身份、映射/文件清理、缓冲驻留与完整进程树 RSS，而非仅检查池的内部计数。
+
+交付：像素等价、完整栅格化性能和内存门槛；没有降低清晰度换取速度。
+
+### 5. 整段迁移 Flash 规则（P4）
+
+按照“行与几何 → 表格 → 图形/公式 → 标题段落及阅读顺序 → 跨页判断 → 最终块构造”推进。每次迁移一个能在 Rust 内连续执行的阶段，避免继续增加细碎 Python/Rust 往返。
+
+- 文档级字体、标题、页眉、水印统计仍先于依赖它们的逐页裁决；保留跨页依赖和原始顺序。
+- 优先消除重复扫描、重复排序与重复候选构造，候选覆盖、阈值和结果顺序不变。
+- 纯迁移提交只要求等价；算法改进另交提交，逐项附原文、前后标框和导出结果，拒绝未解释的质量变化。
+
+交付：`PdfModel.predict()` 的 PDF 分析主流程由 Rust 驱动，Python 仅在输出边界物化 model-list；完整语料与 186 个既有表格区域差分通过。
+
+### 6. 双仓发布收敛（P5）
+
+只有三链路各自满足中位数之和降低至少 50%、无持续单样本超过 5% 退化、峰值 RSS 不超过 130%，且质量和兼容性通过后，才切换默认内核。
+
+- 同步提高 MinerU 的 DocVortex 最低版本，以实际安装 wheel 验证组合；保持 Python 3.10–3.14、ABI3 和跨平台矩阵。
+- 保留一个发布周期的显式旧后端选项，计算错误不静默回退；之后退出纯 Python PDF 后端，无扩展时明确报错，其他格式独立运行。
+- 更新架构、私有协议、诊断与中文函数说明。合并、发布和默认切换分别作为独立交付状态，不与本机测试通过混称。
+
+若性能目标仍未达到，则交付真实瓶颈、质量证据与差距，保持候选/回退状态，不宣称 P5 完成。

docvortex-0.5.2/docs/pdf-native-kernel-p4-execution.md

@@ -0,0 +1,67 @@
+# 下一阶段执行顺序：Flash 完整规则内核
+
+> 2026-09-27 默认策略更新：用户认可当前性能并明确要求切换。默认计算和渲染配置均为 `auto`：计算优先兼容 Rust，扩展缺失或不兼容时回退 Python；渲染选择 `session`，会话内部沿用计算后端。计算或渲染运行错误直接传播，不自动重试旧实现。显式 `rust` 要求兼容扩展；`python` 及 `legacy` 渲染保留用于回退。下文“不切换默认”的记录属于此前阶段，不再代表当前策略；原 Rust 基线的两倍目标仍未达成，不据此宣称 P0–P5 全部完成。此默认调整不等于合并或发布。
+
+当前工作继续按单代理串行推进。RSS 上限是原始冻结 Rust 基线的 130%，不能错误地拿每个中间候选的 RSS 作为新的预算基线。保留各轮失败、回放及正式结果；不得通过改变统计口径、删候选或降图像质量宣布达标。
+
+协议 20 已迁移候选成员和动态合并，协议 21 已完成位图直裁，协议 22 已将同源 Flash 页面的整段文字样式检测接入 Rust 快照。下一批细分自有文本读取、对象可见性/路径读取与视觉证据物化，再推进更多消费者共享 Rust 页面数据。新增样式阶段的迁移与验收见 [阶段 17 报告](rust-pdf-stage17-inline-styles.md)。本文的表格剩余规则、X/Y 和最终布局继续保留；编号表示职责分组，实施优先级按全语料成本及可优化比例确定。
+
+## 已具备的检查点
+
+协议 15 的三链路热运行和 medium 冷启动已完成，详见 `rust-pdf-stage9-inline.md`。协议 16 已将分类原始统计迁入 Rust，299 页字段与字典顺序一致，32 份真实共享回放一致，完整测试 5165 passed / 1 skipped。整页渲染已采用较低的 worker 页数门槛，仍最多使用原有 3 进程预算，裁图调度不变；最终全量性能结果以第 11 批报告为准。
+
+协议 17（`a35a6f4`）继续将全文风险筛查与完整 run 统计迁入 Rust，32 份完整几何计划及公开输出一致，5171 项完整测试、实际双 wheel 安装及跨平台 CI 通过。性能与边界详见 [阶段 12 报告](rust-pdf-stage12-geometry.md)。
+
+这些是阶段结果。PDFium 文档/页面的完整 Rust 生命周期、矢量快照、Flash 全流程和旧后端退出尚未全部完成。
+
+协议 18（`7481460`）进一步接通 Rust 自有文档的几何准备、锚点、run、跨页样式和来源恢复，样式路径不构造字符样本，布局路径仅在剩余 Python 规则前物化一次。完整几何计划及 32 份公开/medium 回放一致，5181 项全量测试和实际双 wheel 检查通过。当前正式性能与 CI 证据见 [阶段 13 报告](rust-pdf-stage13-owned-geometry.md)。
+
+协议 19（`6d9bbb2`）接通 canonical 行指标和最终 Y 风险，共享基线聚类，诊断直接从自有 run 导出。无需实际修复时跳过字符物化的能力通过针对性测试；当前 32 份语料的布局文档仍需后续修复，未命中该分支。完整测试 5183 项及实际双 wheel 检查通过，性能与 CI 见 [阶段 14 报告](rust-pdf-stage14-line-metrics.md)。
+
+协议 20（`6fc883d`）将核心成员、网格扩展、动态合并及注释角色冲突处理留在 Rust，内部检测器只物化保留的最终候选。修正版 32 份候选完整字段、注释顺序和公开/medium 回放一致，完整测试 5187 项通过。失败首版及修正版证据见 [阶段 15 报告](rust-pdf-stage15-table-candidates.md)。候选发现和表注文字/几何链还不是完整 Rust 流程。
+
+## 1. 整体迁移全文几何计划
+
+早期独立低干扰阶段计时中，demo1 / 中文论文2 的 `build_document_geometry_plan()` 占公开解析约 27%；协议 19 的当前比例已降至约 16.5% / 15.5%。阶段诊断不代替正式性能收益，详细函数 profiler 放大的累计比例也不能直接当作加速空间。
+
+风险筛查、样本准备、run 统计、跨页样式校准、来源恢复、canonical 行指标和最终 Y 风险已完成阶段迁移；剩余工作是把 `src/docvortex/analyzers/native/pdf/char_geometry.py` 的 X 修复及 Y 行分析/邻行/修复接入同一 Rust 文档数据。延后布局路径最后一次 Python 字符样本物化，不能每个子阶段重新转换字符字典。原始页与行来源 ID、stable tie、字段更新顺序和全文先后依赖必须保留。
+
+需特别验证：线性插值分位数（该模块不是相邻取样分位数）、CPython 版本对应的浮点求和、字体族/Unicode 类别、source 与 loose side-map 的不同来源、稀疏相邻字符修复、跨页样式触发、split shadow、旋转及诊断顺序。配置或自定义输入不支持时明确选择参考路径，计算失败必须抛出。
+
+几何剩余工作：
+
+1. canonical tight 并集、基线及 Y 风险摘要已完成；继续让后续 Y 行分析复用 anchor ID 和聚类。`_record_line_canonical_metrics()` / `_analyze_lines()` 按宽度和成员数选择 dominant，`_has_document_y_risk()` 按成员数选择；只能共享聚类，不能错误地统一三处裁决规则。
+2. 接入 X donor、稀疏修复、行修复汇总；先保留纯数值修复记录，按原插入顺序在绑定边界构造 `CharLayoutGeometry` / `LineGeometryRepair`。
+3. 接入 Y 邻行、侵入判定、trim 与 split shadow；复用已经准备好的行与 run，最终仅导出计划字段和诊断。保留 X 修复先于 Y、跨页样式先于来源恢复的依赖。
+4. 独立测量热点，再跑三链路正式验收。若几何阶段收益已明显受 PDFium 或表格阶段限制，按独占耗时调整下一批优先级，不为减少 Python 代码量而继续细碎迁移。
+
+交付：完整 `DocumentGeometryPlan` 字段及诊断差分、布局/原文/标框对照、32 份公开/Flash/共享入口回放，以及独立正式计时和进程树 RSS。
+
+## 2. 整体迁移表格候选展开与合并
+
+历史分账中，49.- 的页面准备约占公开解析的 83%。协议 20 当前独立分账显示：公开入口约 1.431 s，表格检测约 0.930 s，其中候选发现约 0.358 s、自有展开/合并约 0.504 s；最终 `_TableCandidate` 仅构造 2 个。这些成本主要集中在密集表格；全语料发现/自有合并合计约 8.09%。后续仍要消除 Python draft、表注证据及部分框组装的开销，但不能把此阶段称为完整表格内核迁移完成，也不能把单样本比例套用于全量优先级。
+
+让候选、网格成员、注释归属、展开状态及合并更新留在 Rust 中，最终只物化保留的候选。保持现有候选覆盖、按分数稳定排序、首个重叠目标选择、成员集合更新和注释合并顺序。禁止以少计算候选或缩小区域替代迁移。
+
+当前实现与下一批边界：
+
+- 已接通 Rust 核心成员与页面网格上下文。下一步统一候选发现和表注所需的 row/core/annotation 数据与整数行 ID；caption、Unicode 标记与字体语义先按原规则编码一次。
+- 网格扩展与动态合并已连续执行；下一步让候选区间、分数和来源 ID 留在 Rust，减少逐个 Python draft，并将表注链的几何、成员与标记引用判断接入同一上下文。参与合并之前必须得到与参考相同的最终框和成员，不能拿尚未展开的框提前裁掉候选。
+- `_merge_table_candidates()` 按分数稳定降序依次处理，并与已有目标当前框比较；目标 union 后会改变后续命中，不能用初始框的一次批量匹配代替动态合并。保留 `_SharedLineIndexSet` 的精确成员语义及注释合并顺序。
+- 已在所有候选处理后按位置稳定排序并导出保留对象；仍需消除 Python 注释及 draft 临时对象。继续做候选逐字段、成员、注释和最终表格对照，再独立测量物化次数与各阶段成本，不用最终候选物化减少代替整个阶段完成。
+
+交付：现有 186 个表格区域及全部 demo 的结构/诊断/HTML 等价，另覆盖合并单元格、旋转、脚注和透明路径。算法改进应另提交，不能混进纯迁移验收。
+
+## 3. 迁移最终布局与跨页规则
+
+继续处理 `_finalize_prepared_page()`、阅读顺序/栏布局、标题段落和正文尺度统计。跨页字体、标题、页眉、水印和参考文献判断仍先收集全局证据再逐页裁决，不能改成独立页面判断。
+
+优先批量保留 Rust 行、字符与字体 ID，减少重复扫描和排序。直到 PDF 主分析流程由 Rust 驱动、仅在输出边界物化 model-list，才将 P4 标记完成。
+
+## 4. 收敛所有权与发布门槛
+
+- 分类当前有独立原始统计快照；仍需与正文原始读取进一步复用，不能声称所有 PDFium 字符读取已经只执行一次。
+- 矢量、链接和注释仍需移入不可变 Rust 页面模型；统一文档/页面/文本页/位图/字体回调生命周期与同库运行时锁。
+- 补齐全量 high/xhigh 的真实模型录制回放、长文档和图像密集/复杂裁剪样本、长期资源稳定性及实际 WebUI 验收。已有 demo1 high/xhigh 是代表样本。
+- 保持三链路各自降低至少 50%、无持续单样本超过 5% 退化、RSS 不超过 130% 的门槛；冷启动单列。尚未满足时保留显式候选和参考后端，不切换默认。
+- 最终能力和最低 DocVortex 版本同步进入 MinerU，以实际安装双 wheel 验证 Python 3.10–3.14、ABI3 和跨平台矩阵，再按发布周期退出旧后端。

docvortex-0.5.2/docs/pdf-native-kernel.md

@@ -0,0 +1,98 @@
+# PDF 原生内核迁移
+
+> 2026-09-27 默认策略更新：用户认可当前性能并明确要求切换。默认计算和渲染配置均为 `auto`：计算优先兼容 Rust，扩展缺失或不兼容时回退 Python；渲染选择 `session`，会话内部沿用计算后端。计算或渲染运行错误直接传播，不自动重试旧实现。显式 `rust` 要求兼容扩展；`python` 及 `legacy` 渲染保留用于回退。下文“不切换默认”的记录属于此前阶段，不再代表当前策略；原 Rust 基线的两倍目标仍未达成，不据此宣称 P0–P5 全部完成。此默认调整不等于合并或发布。
+
+## 验收目标与冻结基线
+
+以 DocVortex `3eef2d1`、MinerU `cabe6e34` 为基线，目标为本机 Mac 单文档热运行耗时降低 50%。公开 parse、MinerU Flash 和冻结模型输入的共享 PDF 链路独立验收；进程树同时刻峰值 RSS 不超过基线 130%（2026-09-27 恢复任务时调整，此前冻结报告仍保留原 120% 门槛），单样本持续耗时退化不超过 5%。冷启动单列，模型推理与导出 PDF 排版不计作本项目的优化收益。
+
+本轮证据根目录为 `output/pdf/native-kernel-20260927/`。源码、原生扩展与输入均独立冻结；32 PDF／299 页包括历史 `49.-.pdf`。`candidate-source` 和 `public-comparison` 是第一批实现，`candidate-stage2` 和 `public-stage2` 是第二批实现，不能混用源码或将前者收益归于后者。
+
+## 当前实现
+
+### 同库读取与连续计算
+
+新增 `docvortex-pdfium` crate，承载原始字符读取、对象树/矩阵/裁剪遍历、路径解码和字体提供器。它借用当前 pypdfium2 的函数和页面，不加载第二份 PDFium，不再次初始化运行库。桥接层先检查 ctypes ABI，再调用同库地址；原有 PDFium 锁仍保护读取操作。
+
+字符原始记录直接在 Rust 中转换坐标，每批至多物化 1024 条 Python 记录。对象树也按有界批次输出，路径端点保留原有共享关系。字体数据及常见回调移入 Rust；非 ASCII 名称的少量字符集判定继续使用 Python 编码语义。回调及释放使用可重入锁，等待锁的绑定方法释放 GIL。实际使用情况和 ABI 回退原因由后端诊断公开。第二批冻结实现的私有协议为 10；后续 run 清洗和句尾迁移使用协议 11。
+
+文本管线将字符组片段、组行、上下标和视觉行准备连接在 Rust 内执行，仅在计算前读取所需字符属性、计算后构造 Python 行。非 ASCII 属性以当前 Python 解释器为准，纯计算期间不回调 Python。特殊可执行对象或不满足精确数值约定的输入保留参考语义。
+
+协议 11 进一步在原生 run 上完成控制字符、软断词和空白清洗，以及句尾和小字号引用判断。Unicode 十进制字符单独使用解释器的 `isdecimal` 属性；粗行回退、空 run 过滤后的原编号及后续跨行合并保持原语义。
+
+表格候选的行中心、边界、成员和来源索引保存在原生候选对象内，连续完成区间划分和成员摘要。候选覆盖、排序、阈值和 HTML 输出规则保持原样。
+
+第二批正式测试发现 `49.-.pdf` 持续退化约 18%，因此该批性能门槛失败。剖析显示每候选重新散列成员和多次身份检查引入了额外开销。修复版将来源 ID 在准备时压缩为连续编号，查询采用独立位图；内部不可变行序列共享已验证区间，外部可变序列仍逐次检查。修复前的证据保留，不用于宣称修复后通过。
+
+### 快照兼容接口
+
+`PDFPage.get_snapshot()` 返回 `PDFPageSnapshot`；文档持有弱缓存。快照独立于原生页面句柄，公开字符、矢量和链接返回独立副本。`prepare_text_evidence`、`prepare_table_page` 接受 `snapshot=`，拒绝错误页面来源及显式几何混用。页面尺寸/旋转仅缓存成功读取值。
+
+协议 12 引入 `NativeTextSnapshot`：字符、去重字体和来源索引由 Rust `Arc` 持有，核心数据不含 Python 对象或 PDFium 指针。原始读取、坐标修复、代理对处理、裁剪、去重和组行连续执行；Flash 直接消费原生视觉行。Python 字符及几何对象仅在兼容接口需要时物化，返回值不反向修改快照。Unicode 属性、字体名称解码和少量浮点兼容元数据按解释器语义去重准备。
+
+`PDFPage.get_text_snapshot()` 提供只读文本入口，不提前提取矢量或链接；`get_snapshot()` 在需要完整页面证据时复用其文本所有权。文档弱缓存不延长快照生命周期，关闭文档后仍可访问已有快照。MinerU 窗口缓存先用轻量行摘要判断方向，再按需升级为完整快照，逐页处理及异常退出时释放缓存。显式传入的可变几何仍遵循原接口，不被内部快照覆盖。
+
+这尚不是完整的 Rust 页面模型：矢量和链接仍保留 Python 兼容存储，文档及页面生命周期仍由 Python 管理，部分表格和旋转文本填充还会读取物化几何。分类、跨页语义与最终块构造没有因此整体迁入 Rust。
+
+### 可选渲染会话
+
+`PDFDocument.get_render_session(threads=..., timeout=...)` 惰性创建文档所有的会话。定向 worker 协议包含打开、任务、关闭、退出和确认。输入 PDF 写入一次，由各 worker 的 PDFium 文件读取器复用文档句柄；关闭确认在句柄释放之后返回。worker 可跨文档复用，共享并发预算；超时、取消和崩溃路径清理资源。原始 PDFium 位图及 stride 通过受控临时文件返回，父进程只做一次必要解码并持有独立 PIL 图像。
+
+默认使用 `session` 新路径，通过 `DOCVORTEX_PDF_RENDER_BACKEND=legacy` 可显式回退。旧按 bytes API 保留兼容，新调用可传 `session=`。MinerU 窗口和补图路径复用文档会话，纯文本 Flash 不提前创建输入文件。异步取消等待渲染任务清理完成。此实现尚不是零复制 NumPy/PIL 或 Rust 像素缓冲。
+
+## 已完成的正确性检查
+
+修复版协议 11 的本地全套结果：Rust 5107 passed / 1 skipped；Python 4617 passed / 491 skipped；MinerU 相关集成 128 passed。Cargo workspace 测试、Clippy（拒绝警告）和格式检查通过。
+
+连续文本直接原生入口覆盖 48 PDF／453 页、1,201,195 字符，逐字段及数值类型检查通过。表格迁移的 32 PDF／299 页 ModelJson、MiddleJson 与冻结基线一致，186 个表格区域的结果、样式 HTML 和诊断一致。测试包含回调重入、字体缓冲、快照关闭后访问、worker 超时/取消/崩溃和关闭失败。
+
+Mac arm64 ABI3 wheel 已构建并通过 CPython 3.14 ABI 检查；独立安装环境的 170 项新内核测试通过。实际安装 DocVortex 与 MinerU 两个 wheel 后，含图的 13 页 `demo1.pdf` Flash 自动文本路径与冻结基线完整一致。测试环境复用本机现有第三方依赖，不代表从零依赖解析或跨平台矩阵已通过。
+
+以上是正确性和本机安装证据，不代表 2 倍性能目标达成，也不代表跨平台 wheel、真实模型及 WebUI 全部验收。
+
+## 协议 11 冻结版本性能
+
+`candidate-stage3`（源码基于 `75f7923`）与原始 Rust 基线逐文档交替运行，一次预热、五次正式测量，并独立采样进程树 RSS。`public-stage3/report.json` 的 32 份公开 `parse()` 输出全部一致；热运行中位数之和为 24.8195 s → 22.4035 s，降低 **9.73%**。最大单文档 RSS 比例为 **1.0335**，没有持续超过 5% 的耗时退化。`49.-.pdf` 在完整轮次中降低 3.21%，先前 18% 的退化未重现。
+
+同一冻结引擎配合 `mineru-stage2` 的实际 Flash 自动文本入口，31 份符合文本分类的 PDF 输出全部一致；`small_ocr.pdf` 按自动分类排除，未强制改为文本。热运行中位数之和为 27.4885 s → 24.2485 s，降低 **11.79%**；最大 RSS 比例 **1.0361**，没有持续超过 5% 的退化。证据为 `flash-stage3/report.json`。
+
+两条链路均**未达到 50% 目标**，不能代替输入栅格化和完整共享路径的验收。协议 12 原生文本快照不在上述冻结版本中，其收益必须另测。
+
+## 协议 12 正确性证据
+
+`text-stage4-parity` 对比纯 Python、原 Rust 字符管线和原生快照：48 PDF／453 页、1,812 种可见性与扩展几何组合的字段、数值类型、别名关系、粗行和视觉行一致。实际执行 1,780 次原生读取，另有 32 个空页组合，无隐式回退；32 PDF／299 页 ModelJson、MiddleJson 也与冻结基线一致。此回放对应二进制摘要 `d9fa33fc…`；随后仅新增 API 与兼容适配的 `06831184…` 另有 113 项专项测试，不将旧二进制回放标为新版本全量回放。
+
+新增 API 版本本机全套为 Rust **5137 passed / 1 skipped**，Python **4620 passed / 518 skipped**。MinerU 专项测试分别为 Rust **184 passed**、Python **182 passed / 2 skipped**。`host-stage4-parity` 的 32 PDF × medium/high 共 64 个回放用例与原基线及协议 11 版本业务输出一致；旧字符几何提取调用由 598 次降为 0。调用次数减少是复用证据，不是耗时收益；实际模型、WebUI 和正式性能仍需分别验收。
+
+## 协议 12 正式性能与暂停
+
+等价静态修复后重建的实际扩展为 `5e946ba774853022b44651a329430a55fb0afa95d6e4d68a684902159418cb78`。格式、严格 Clippy、Cargo 测试及重建后的 203 项快照专项通过。该版源码对应本地 DocVortex `dc0f778` 和 MinerU `bf901490`，冻结副本与最终提交的运行代码逐文件一致。
+
+32 份公开 `parse()` 的逐文档中位数之和为 **21.8964 s → 19.3079 s，降低 11.82%**；31 份实际 Flash 文本路径为 **23.7769 s → 20.8848 s，降低 12.16%**。两者完整输出均一致，无持续超过 5% 的耗时退化，最大进程树 RSS 分别增加 **7.28%** 和 **8.09%**。Flash 的 OCR 样本按实际自动分类排除。
+
+输入栅格化阶段总和为 **6.5079 s → 6.0547 s，降低 6.96%**，32 份像素摘要一致，但 **4 份文档持续退化超过 5%，性能门槛失败**。栅格化不是完整第三条共享链路。独立内存及五次连续处理检查覆盖四个代表样本，均在预算内，worker 和输入资源释放通过；不将有限回放当作长期无泄漏证明。
+
+**2 倍目标未达到，默认渲染器保持 legacy。按用户要求，本轮测试完成后暂停。** 详细原始证据及失败样本见 `output/pdf/native-kernel-20260927/STAGE4-REPORT.md`；恢复顺序见 [后续任务计划](pdf-native-kernel-next.md)。协议 12 提交尚未推送，跨平台 CI、完整共享链路、独立冷启动和发布门槛尚未完成。
+
+## 剩余交付门槛
+
+| 阶段 | 尚未完成 |
+| --- | --- |
+| P0 | 三条实际链路的完整交替计时、分账和独立冷启动验收 |
+| P1 | 将矢量、链接和文档生命周期纳入原生模型；现已完成文本快照所有权 |
+| P2 | 分类统计复用、剩余表格与文本填充边界的中间物化；现已接通原生文本连续入口 |
+| P3 | 独立像素缓冲及共享视图；完整性能、内存和连续处理门槛 |
+| P4 | 标题段落、图注脚注、阅读顺序、跨页裁决及最终块构造整体迁移 |
+| P5 | MinerU 全档位验收、最低版本调整、安装 wheel 组合及跨平台 CI，达标后默认切换和旧后端退出 |
+
+迁移期间保留 `DOCVORTEX_COMPUTE_BACKEND=python|rust|auto` 及旧渲染器，不静默掩盖计算错误。达到完整门槛前不移除 Python 后端、不宣称完成全部计划。
+
+## 输入 PDF 基准
+
+`tests/benchmarks/pdf_input.py` 记录分类、字符/矢量读取及真正的输入栅格化，不等同于 `pdf_render.py` 的导出 PDF 排版，也不等同于 MinerU 端到端性能。报告冻结源码/扩展摘要、窗口/进程参数、导入、首次调用及热运行。摘要计算在阶段计时外；`process_wall_seconds` 包含全部运行、检查和退出，不能当作冷启动解析耗时。
+
+`tools/mineru_flash_benchmark.py` 在显式指定的双仓源码上调用实际 `analyze_pdf(effort="flash", parse_mode="auto")`，包括分类、分析、补图、页面几何及关闭。新进程首调用作为唯一预热，再测五次；导入时间单列。另起独立进程预热后采样一次入口 RSS，采样结束才序列化完整结果。自动分类为 OCR 的样本明确排除于 Flash 文本指标，不启动模型或强制改为文本。宿主集成工具放在 `tools`，避免引擎测试引入 MinerU 依赖。
+
+## 恢复执行：第五批渲染修复
+
+用户已要求单代理恢复执行，RSS 门槛为 130%。第五批 32 份输入栅格化耗时降低 **22.65%**，像素一致，原四份持续退化全部消除；八份独立内存样本通过新预算。实际安装双 wheel 联合检查 383 项通过；网络阻塞推送，尚未取得新跨平台 CI 结果。见 [第五批证据](rust-pdf-stage5-render.md)。此前暂停报告及协议 12 端到端数字保留为各自冻结版本的历史证据。

{docvortex-0.5.1 → docvortex-0.5.2}/docs/rust-acceleration.md

@@ -1,8 +1,8 @@
 # Optional Rust PDF kernels
 
 See [Repository architecture](ARCHITECTURE.md) for the Python/Rust ownership boundary
-and binding-module layout. The current private extension protocol is **8**, shared by
-the Python loader and Rust core. Protocol 4, 5, 6 and 7 references below describe historical
+and binding-module layout. The current private extension protocol is **11**, shared by
+the Python loader and Rust core. Protocol 4, 5, 6, 7 and 8 references below describe historical
 interfaces or rollout stages, not the current loader requirement. Rebuild editable
 native installs and restart existing processes after updating native sources.
 
@@ -255,3 +255,21 @@ Existing timing runs can be audited without discarding their original memory rec
 ```sh
 python tests/benchmarks/pdf_memory.py --timing-report output/rust/revisions/report.json --output output/rust/memory-audit
 ```
+
+## Native kernel migration (protocol 11)
+
+The same-library PDFium adapter is now a separate Python-independent crate. Object
+traversal, clipping and path decoding run there; character geometry stays in Rust
+until bounded output batches. The synchronized font provider handles ASCII/CJK
+requests natively and preserves Python normalization for uncommon non-ASCII names.
+The full Flash document pipeline is not yet a standalone Rust engine.
+
+`PDFPage.get_snapshot()` explicitly shares detached page evidence; public mutable
+character access still materializes isolated Python data. `PDFDocument.get_render_session()`
+reuses mapped input and directed workers. `DOCVORTEX_PDF_RENDER_BACKEND=auto` is the default and selects `session` rendering
+in DocVortex and the matching MinerU checkout. Sessions use Rust when the compute
+backend provides it and support Python when it does not. Rendering errors propagate
+without retrying through the legacy renderer.
+Set `DOCVORTEX_PDF_RENDER_BACKEND=legacy` to explicitly use the previous renderer.
+For the Python reference configuration, also set `DOCVORTEX_COMPUTE_BACKEND=python`. See
+[pdf-native-kernel.md](pdf-native-kernel.md) for migration and evidence boundaries.

docvortex-0.5.2/docs/rust-pdf-stage11-classification-render.md

@@ -0,0 +1,46 @@
+# PDF 原生内核第 10–11 批：原始分类与渲染并行度
+
+## 交付内容
+
+DocVortex 实现检查点 `34fb8c5`，私有协议 16；MinerU 生产接入代码维持本轮已验证版本，测试编码修复检查点为 `739ad39f`。按用户要求全程单代理，原始冻结 Rust 基线的进程树峰值 RSS 上限为 130%。
+
+- PDFium 原始 Unicode、generated 标志、Unicode map error 和字体字节读取进入 Rust，统计独立于 canonical 去重字符。字体 UTF-8 ignore、规范化名称碰撞以及每种统计各自的字典键首次出现顺序均保持参考行为。
+- 原始分类快照不持有 PDFium 指针，文本页关闭后仍可读取；每次导出独立字典。原生计算失败明确抛出，不进入通用 OCR 回退。
+- 上下标记录按 canonical 字体 ID 复用等价类，消除逐字符字体名复制/哈希。
+- 整页渲染从原来每 worker 至少 30 页调整为至少 4 页，仍使用既有最多 3 进程的共享预算；裁图保持原策略，DPI、编码器、像素与结果顺序不变。
+
+分类的独立原始统计快照不等于分类与正文已经共享全部原始读取；文档/页面 Rust 所有权、矢量快照和完整 Flash 内核仍需后续迁移。
+
+## 正式热运行验收
+
+冻结候选：`output/pdf/native-kernel-20260927/candidate-stage11` / `mineru-stage8`。基线为 DocVortex `3eef2d1` / MinerU `cabe6e34`，同样启用旧 Rust。逐文档预热一次、正式五次，逐文档交替版本；内存独立测量。候选显式使用 session，基线使用 legacy。Profiler、构建、测试和真实模型录制均在正式计时之外执行。
+
+| 范围 | 样本 | 基线中位数总和 | 候选中位数总和 | 耗时降低 | 最大进程树 RSS 比 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| 公开 parse() | 32 | 21.999844 s | 18.971245 s | 13.77% | 108.66% |
+| MinerU Flash 自动文本 | 31 | 23.925293 s | 19.198173 s | 19.76% | 108.30% |
+| 实际 medium 共享 PDF | 32 | 25.025109 s | 14.663202 s | 41.41% | 93.08% |
+
+完整结果一致，三条链路均通过无持续超过 5% 退化及 RSS 130% 门槛。公开入口的 `manufacturing_facilities_cross_page_table.pdf` 首次为 +5.49%，反序复测为 -4.17%，未构成持续退化；首次值保留在总和中。`small_ocr.pdf` 仍分类为 OCR，因此不计入 Flash 文本速度。
+
+**三条链路均未达到耗时降低至少 50% 的最终目标。** 共享路径尚需在本批基线下再减少约 2.15 秒总和。不同轮次的基线波动不能算作增量收益。
+
+## 冷启动与连续处理
+
+32 份实际 medium/auto 输入，每次观测启动新解释器、每份五次并交替版本：逐文档中位数总和从 44.973797 秒降到 35.309844 秒，降低 **21.49%**，没有首次或持续超过 5% 的退化。计时包含解释器、导入、输入及冻结模型结果加载、字体初始化和 worker 启动直到首次分析返回；不包含真实模型计算、返回后验证和退出清理。没有用热运行替代冷启动，也未从总耗时扣除模型结果加载。
+
+独立的连续栅格化内存检查覆盖 8 份输入，窗口 16 页，每份预热一次再运行五次。所有样本的进程树峰值 RSS 比在 22.32%–74.79%，worker 身份稳定、输入与像素资源释放检查均通过。回收后驻留差值为 16 KiB–8.21 MiB；这是有限次数测试，不能据此证明无限运行没有泄漏。原始证据为 `cold-stage11/report.json`、`cold-stage11-summary.json` 和 `render-memory-stage11-summary.json`。
+
+## 质量与兼容性
+
+- 32 PDF / 299 页的原始分类字段和字典顺序逐页与 Python 参考一致。
+- 32 份实际 medium 模型输入与完整输出严格回放一致；公开 ModelJson、MiddleJson、素材摘要和诊断全等。
+- 协议 16 完整测试 5165 passed / 1 skipped；原 Python 分类路径 21 passed。真实多进程渲染追加 29 项、宿主相关检查 32 项通过。
+- 实际安装 ABI3 wheel 检查通过；最终 wheel 的渲染、分类和快照追加检查 70 项通过，双 wheel 包文件、来源及扩展已逐项校验。
+- [DocVortex CI](https://github.com/myhloli/DocVortex/actions/runs/36284975783) 39 项全部通过；[原生 wheel 矩阵](https://github.com/myhloli/DocVortex/actions/runs/36284975780) 全部通过；[双仓联合安装矩阵](https://github.com/myhloli/Magic-PDF/actions/runs/36285069477) 9 个组合全部通过。
+
+原始报告分别位于 `shared-stage11`、`public-stage11`、`flash-stage11`，摘要为对应 `*-summary.json`，执行顺序和退出状态保存在 `stage11-execution.json`。三样本增量试测仅用于选方案，不代替上述全量验收。
+
+## 后续顺序
+
+优先整体迁移全文几何计划、表格候选展开/合并和最终布局，详见 [P4 执行计划](pdf-native-kernel-p4-execution.md)。默认未切换，未合并、未发布；高档位全量真实回放、实际 WebUI 和最终后端退出仍未完成。

docvortex-0.5.2/docs/rust-pdf-stage12-geometry.md

@@ -0,0 +1,48 @@
+# PDF 原生内核阶段 12：全文风险与 run 统计
+
+## 实现及边界
+
+实现检查点为 DocVortex `a35a6f40d39240a8e6c81b38246a30161aa14fc1`，私有协议 17。MinerU 生产代码未改动，继续验证 `739ad39f` 对应的双仓组合。按用户要求单人执行，速度优先，RSS 门槛继续固定为最初 Rust 基线的 130%。
+
+- 文档风险累积器在 Rust 内完成锚点筛选、相邻对、Y 簇、字体分组和跨页样式统计；逐行输入后仅返回提前命中或最终风险，保持原来的全文先后依赖。
+- 完整 run 统计一次读取内部样本，在 Rust 内稳定排序锚点，计算相邻对、字距、bearing、中位数、强异常和同族传播。最终按原来的 run 键顺序构造统计对象，并保持成员对象身份。
+- 线性插值分位数、首个并列簇/字体、重复来源行的集合与计数语义不变；独立的 Python 参考实现保留。非标准类型、越界或非有限输入明确选择参考路径，原生计算及输出构造异常直接传播。
+- Rust 计算释放 GIL，不访问 PDFium，不新增线程池。中文函数说明、协议注册和 ABI 验证同步更新；wheel 矩阵加入完整字符几何测试。
+
+这仍不是完整 Rust 文档几何内核：样本构造、样式修复、X/Y 修复和最终诊断的部分组织还在 Python；风险与 run 两个阶段仍有独立输入边界。全文布局、表格候选闭包、PDFium 文档所有权和矢量快照也尚未全部迁移。
+
+## 选择依据
+
+仅迁移风险筛查的首个候选保留在 `candidate-stage12`：三份热点的公开解析中位数总和仅下降 0.44%，属于波动级收益，未据此宣称稳定加速。
+
+增加完整 run 统计后的 `candidate-stage12b`，相对上一版 `candidate-stage11` 的相同三样本试测总和下降 5.46%；demo1、中文论文2 分别下降 6.64%、8.59%，49.- 下降 0.55%。两版每份均预热一次、测量五次，完整输出相同。此小范围试测仅用于选方案，不能代替全量正式验收。
+
+## 正式验收
+
+本批以 DocVortex `3eef2d1` / MinerU `cabe6e34` 为基线，双方启用对应 Rust 实现。候选使用冻结的 `candidate-stage12b` / `mineru-stage8`，session 渲染参数不变；基线仍使用 legacy。冻结副本记录前序 HEAD 和 dirty 状态，实际源码摘要及扩展摘要写入每份报告，对应上述实现检查点。
+
+每份文档预热一次、正式五次，逐文档交替版本；超过 5% 的退化反序复测，首次值保留在总和。内存独立采样同时刻进程树 RSS。构建、测试、模型录制和 profiler 不与正式计时混跑。
+
+| 范围 | 文档数 | 基线中位数总和 | 候选中位数总和 | 耗时降低 | 最大进程树 RSS 比 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| 公开 parse() | 32 | 21.904906 s | 17.867750 s | 18.43% | 108.74% |
+| MinerU Flash 自动文本 | 31 | 23.608431 s | 18.263778 s | 22.64% | 108.35% |
+| 实际 medium 共享 PDF | 32 | 24.753747 s | 14.773294 s | 40.32% | 93.19% |
+
+三条链路输出全等，没有首次超过 5% 的单样本耗时退化，均通过 RSS 130% 门槛。`small_ocr.pdf` 仍分类为 OCR，不混入 Flash 文本指标。**三条链路均未达到最终 50% 降幅目标。** 不同批次基线计时的波动不作为新增实现的收益；共享路径本批仅作原始基线验收，不宣称几何规则迁移使其额外加速。
+
+本批未重复完整冷启动与长期稳定性验收；上一批结果保留为协议 16 的历史证据，不能重标为协议 17 成绩。
+
+## 质量、安装及 CI
+
+- 32 PDF / 299 页逐份运行两遍，完整 `DocumentGeometryPlan` 所有字段与参考实现相等，公开 ModelJson、MiddleJson、素材和诊断摘要也一致。
+- 32 份真实 medium 模型输入及完整结果严格回放一致；没有只比较最终文本而跳过模型输入。
+- 最终 Rust 后端全量测试 5171 passed / 1 skipped；针对性测试 104 passed，Python 参考几何测试 25 passed / 2 skipped；Rust workspace 与严格 Clippy 通过。
+- 实际 ABI3 wheel 验证、独立安装后的 123 项 DocVortex 检查及 439 项 MinerU 边界检查通过。双 wheel 包文件、METADATA、安装来源和原生扩展均已核对；安装态、冻结候选、当前构建的扩展 SHA 相同。
+- [源码 CI](https://github.com/myhloli/DocVortex/actions/runs/36290043350) 39 项、[原生 wheel 矩阵](https://github.com/myhloli/DocVortex/actions/runs/36290043369) 和[双仓联合矩阵](https://github.com/myhloli/Magic-PDF/actions/runs/36290399476) 9 个组合全部通过。联合矩阵首次短 SHA 调度停在检出步骤，改用完整 SHA 重启；失败记录保留，不当作测试通过。
+
+原始证据在 `output/pdf/native-kernel-20260927/` 下的 `public-stage12b`、`flash-stage12b`、`shared-stage12b`、对应摘要、`stage12b-quality.json`、`stage12b-execution.json` 及各 audit / wheel 日志。首次本机构建缺少 `wheel` 依赖，补齐后重试成功，原失败记录保留。
+
+## 后续
+
+继续把样本、run 和修复结果保留在统一 Rust 文档数据中，迁移样式与 X/Y 修复，减少剩余跨阶段物化；之后处理表格候选与最终布局。详细顺序见 [P4 执行计划](pdf-native-kernel-p4-execution.md)。本批未合并、未发布、未切换默认后端，P4/P5 尚未完成。