Skip to content

fix: make dataset validation cancellable and cache reuse explicit (#219) - #226

Merged
codeasier merged 2 commits into
mainfrom
fix/219-cancellable-validation
Oct 10, 2026
Merged

codeasier merged 2 commits into
mainfrom
fix/219-cancellable-validation

Conversation

@codeasier

@codeasier codeasier commented Oct 10, 2026 •

Copy link
Copy Markdown
Owner

变更

  • 将同一截止时间传入文件哈希分块、Python 验证循环和 SQLite progress handler,保持 QUERY_TIMEOUT 分类及资源清理。
  • 复用 native 验证已有的哈希,移除第三次重复哈希和重复行物化。
  • 设备补全只读取受限 manifest 元数据,不扫描成员数据库。
  • 新增显式 PT_SNAP_DATASET_CACHE=immutable 进程内缓存,并同步中英文文档。

完整性与剩余限制

默认每次独立 inspect 仍执行完整验证与内容哈希;报告中的每个查询步骤也会重新 inspect,目前不会跨步骤固定同一 ResolvedDataset,也没有额外的报告级内容哈希守卫。只有调用者明确选择 immutable 模式、保证已完成且不可变的数据集发布及可靠文件变化时间语义时,才启用 O(分片数) 的热缓存。每次命中仍检查成员、路径、symlink、sidecar 和文件代际;报告查询步骤的缓存命中同样只检查元数据,不重新哈希内容。此模式不提供并发写入快照保证,不能用于不可靠时间戳或可回滚文件系统。

因此,默认模式下反复独立查询的完整验证成本仍存在。本 PR 不自动关闭 #219。

验证

以下完整测试与性能记录对应原始实现提交 32639e130413e10e7016a024be828c2e0ab9d296;本次检视修正仅更新中英文文档。

  • 云端完整测试 1964 项通过,Ruff/Black/diff 检查通过,basedpyright 0 errors。
  • 独立复核 126 项相关测试通过,包含默认重新哈希、模拟不变 stat 的内容篡改、超时及清理。
  • 单机百万行观察,仅用于 immutable 显式选择模式:v1 冷验证 4.61s,后续热验证 0.29/0.24ms;native 冷验证 3.95s,热验证 0.51/0.39ms。这不是跨设备性能保证。
  • 原始实现提交的 完整 CI 已通过。
  • 本次文档修正:按固定提交核对源文件与 Git blob SHA,核对查询/报告调用路径、中英文含义、相对链接和 diff 空白;通过。当前云端无完整 checkout/测试环境,未重新运行运行时测试、Ruff、Black 或 basedpyright;新提交 CI 待运行。

未修改 snapshot 源码,无需追加 snapshot provenance。
Related to #219, #217

Copy link
Copy Markdown
Owner Author

验证更新:当前提交 32639e130413e10e7016a024be828c2e0ab9d296 的完整 CI 已通过。默认完整验证与显式 immutable 缓存的区别、并发写入不受保证等限制保持不变;#219 保持开放跟踪默认重复 admission 的成本。

@codeasier codeasier left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

检视发现 1 处文档与实现不一致(Medium),行内标注。

Comment thread docs/en/sharded-snapshotdb.md Outdated
Comment on lines +248 to +249
Pinned report-operation guards also rehash content by default, without repeating
row validation.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Medium] 文档所述 "pinned report-operation guard" 在产品代码中从未被调用

本行(及中文文档 docs/zh/sharded-snapshotdb.md:203、:211-213)把 ResolvedDataset.require_unchanged()(src/pt_snap_cli/core/dataset_resolver.py:56)描述为报告操作中会重哈希内容的 guard,但仓库内 src/ 下没有任何调用方,只有 tests/core/test_dataset_validation_cache.py(:48、:74、:378、:383、:409)调用它。

  • 报告流程 ReportService.peak_memory_report(src/pt_snap_cli/core/report_service.py:91-141)在同一次报告内多次进入 QueryService.execute_query(memory_peak、allocator_gap 等步骤),并不会固定(pin)已解析的 dataset;
  • 每次查询都会重新执行 DatasetResolver().inspect(...)(src/pt_snap_cli/core/query_service.py:236)。

因此该 guard 的内容重哈希分支从未实际运行。影响:在 PT_SNAP_DATASET_CACHE=immutable 下,报告/查询复用实际只做元数据检查(规范路径、sidecar、inode/size/mtime/ctime/mode/nlink),"报告操作仍会重哈希内容" 并不成立,启用者可能高估保护强度。

建议二选一:

  1. 在多步报告/查询复用同一 ResolvedDataset 的路径上调用 require_unchanged(budget);或
  2. 修改中英文两处文档,删除或改写为实际存在的逐次 inspect 检查描述。

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

已更新至 3aa912a5f970f1c03cc9a9d68d5c1c35a177d947。

已按建议 2 修正中英文文档,并同步纠正 PR 描述。现在明确说明:报告中每个查询步骤都会再次调用 inspect,目前不会跨步骤固定同一个 ResolvedDataset,也不调用 require_unchanged;immutable 缓存命中仅检查路径、成员、sidecar 和文件代际元数据,报告步骤同样不会在命中时重新哈希。默认完整验证、显式验证器及不可变发布责任边界保持准确描述。本次仅修改两份文档,未引入报告固定代际逻辑。

验证:已按固定提交核对源文件 blob SHA 与实际调用路径,并检查双语一致性、相对链接和 diff 空白。当前云端未恢复完整 checkout/测试环境,未重跑运行时全套测试;新提交 CI 状态另行核实。

补充:#227 后续接入报告固定代际逻辑时,需要一并调整此处“当前报告实现”的说明;本次保持 #226 独立可描述的实际行为,未改动 #227。

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

验证补充:文档修正提交 3aa912a5f970f1c03cc9a9d68d5c1c35a177d947 的完整 CI run 349 已通过。该轮同时覆盖此次提交的测试、覆盖率、lint/format/type 及配置的打包验收;前一轮被更新后的运行替代并取消。检视线程保留,供复核修正文档。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant