## 最终验收状态(2026-10-11 UTC):双模式契约完成 本 issue 按已确认的双模式验收范围关闭为 completed。下方原文与复现保留为历史证据,其中“缓存命中时 inspect 耗时与数据量无关”不再是默认强验证模式的验收要求,以本节为准。 - 默认强验证保留完整内容 SHA256。有界进程内缓存只在 generation 与内容 fingerprint 一致时复用结构/生命周期校验,warm 为 **O(bytes + shards)**:完整 hash,但不重复 validator。新 CLI 进程允许 cold,不新增跨进程持久缓存。 - 仅显式 `PT_SNAP_DATASET_CACHE=immutable` 选择可信、最终化、不可变发布的快路径。warm 不做完整 hash / validator,但逐成员检查路径、成员集合、sidecar 和 change token,为 **O(shards)**。隐藏全部 change token 的原地修改可能漏检,属于违反 opt-in 信任合同;默认强验证仍检查内容变化。元数据签名不是无条件内容完整性证明。 - 两种模式均不提供并发 writer 锁定或原子 snapshot 保证。不得以 warm 性能或元数据复用推导这些保证。 - 共享 timeout 覆盖准入、分块 hash、Python/SQLite 校验;取消或失败不缓存半成品,连接与文件按生命周期关闭,后续请求可恢复。tab 补全仅做有界 manifest 提示,不做成员 hash / SQLite 校验,也不证明数据完整性。 - #226 / #230 的实现及 #233 的 36 项 compatibility-v1/native-v2 × default-strong/explicit-immutable 回归覆盖实际 hash-read bytes、validator 次数、cold/warm、manifest/成员替换、隐藏 change-token 边界、取消/失效、连接所有权及新进程 cold。证据以真实读取量和调用次数为主,不仅是 wall-clock。 - #233 共新增 41 项回归(本项 36 + #218 5),已合入 main `39fefd1dad820f3262604f0dc9fb9bf9811a248a`(tree `fdd05481d3e467f2546d52bda2dc2b61dabe1d61`)。合并前 [CI 38104812415](https://github.com/codeasier/pt-snap-cli/actions/runs/38104812415) 七项通过。合并后精确 main 提交的 [CI 38105436746](https://github.com/codeasier/pt-snap-cli/actions/runs/38105436746) 也已成功,七项检查通过;新增回归在四个 Python 版本均通过,浏览器与打包来源验收通过。 持久缓存、独立 validate 工作流或新的性能承诺如需推进,另立范围,不作为此次收尾条件。 --- ## 原始问题记录(保留历史描述) 父 issue:#217 ## 问题 每次查询都调用 `DatasetResolver.inspect()`:解析 manifest、对每个分片做完整 schema 和逐行生命周期校验、对所有分片文件算 SHA256。耗时和内存随数据集线性增长,且该阶段无法被超时打断。 - 位置:`query_service.py:236`、`dataset_resolver.py:153-167`、`dataset_contract.py:418-454`(逐行 Python 循环 + 全量 `identities` 字典)、`completion.py:78-82` - 读代码推测(未实测):native 每分片哈希两次(`native_dataset_contract.py:313` 与 resolver),另有 `PRAGMA quick_check` 和全事件 ID `set`(`:316`) ## 复现 - 100 万事件 / 100 万 block:`inspect` 约 5.0s、RSS 约 300 MB - `timeout_s=2` 的查询实际 5.4s 才报超时 - `report peak-memory` 调用 3 次 `inspect` ## 建议 - 按 (inode, size, mtime_ns, manifest hash) 缓存校验结果和 fingerprint - 查询时只做轻量校验(schema + `COUNT/MIN/MAX` SQL) - 逐行生命周期一致性检查移到 import 时或独立 `validate` 命令 - 补全路径不做完整校验 - 校验阶段尊重 `timeout_s` ## 验收 - 缓存命中时百万级数据集的 `inspect` 耗时与数据量无关 - `timeout_s` 在校验阶段生效
Activity
codeasier commentedon Oct 10, 2026
在固定提交
7c33464906aced190698452ebb3a8de8e8e9ab05上完成了实际运行复现。结论:本 issue 的核心问题成立,且 native-v2 的分片 SHA256 实际为 每次 inspect 3 遍,不是原文推测的 2 遍。环境与测量口径
0.4.0.post1.dev31。pip install到独立 venv(非 editable);测量进程的pt_snap_cli.__file__确认位于 venv 的site-packages,不从源码目录导入。ru_maxrss / 1024,单位 MiB,包含解释器与导入基线约 21.5 MiB;不是净增量或保留内存。实测
1. inspect 及重复查询仍随行数增长
百万级 fixture 上,v1 的三次 inspect 是
4.156 / 4.184 / 4.025 s,native 是3.803 / 3.658 / 3.706 s,没有出现校验缓存命中后的快速路径。即使只取
event(id=0, max_rows=1),同一QueryService三次调用:4.156 / 4.104 / 3.999 s3.857 / 3.782 / 4.661 s同样的百万级 SQLite 文件,显式当 standalone member 查询,首次约
5.52 ms(v1)/3.45 ms(native),后续0.13–0.19 ms,均返回 id=0 一行。这个对照只说明全数据集验证开销,不主张 standalone member 可以替代任意 dataset-global 语义。2. 真正的 CLI / Bash 设备补全也复现
另用未加任何 instrumentation 的已安装
venv/bin/pt-snap独立进程测试,墙钟包含进程启动;用wait4记录每个子进程自己的 RSS:event --params '{"id":0}' -n 1 --json--timeout 2query --device <Tab>补全正常输出
0。准确范围是dataset 的设备 ID 补全;模板名等静态补全不走这里。超时查询退出码为 1,stderr JSON 是
error.code=QUERY_TIMEOUT、Query timed out after 2.0 seconds。也就是说,预算确实计入 inspect 的耗时,但只在完整 inspect 返回后才报错,无法在 2 秒时终止该阶段。核心服务三次timeout_s=2分别用了 v14.214 / 4.590 / 3.870 s、native3.953 / 4.064 / 3.791 s;每次均完成了全部校验及哈希。3. 运行期计数:native 三遍哈希,report 三次 inspect
instrumentation 只包装原函数进行计时/计数,不跳过其工作;SQLite trace 记录原始验证 SQL:
PRAGMA quick_check。85,946,368 bytes;仅该分片一轮 inspect 就累计哈希257,839,104 bytes,不含 manifest。v1 百万级分片为74,919,936 bytes。id=0,v1 会哈希全部 4 个分片;native 会哈希全部分片共 12 次,执行 4 次 quick_check,尽管目标 event 只在第一片。ReportService.peak_memory_report两种格式都调用 inspect 3 次;v1 总共 3 次分片哈希,native 共 9 次。本项计数不是对百万级报告能够成功跑完的声明。对应代码
修复与验收建议
(inode,size,mtime)当作无条件的内容完整性证明。保留替换、manifest 改变、sidecar/symlink、内容改变等拒绝和失效契约。固定分片数时 warm path 应不再随 event/block 行数增加;分片数增长时仍可能有 O(分片数) 的 stat 检查,验收需区分。可直接复现(自包含)
以下两个脚本均为复现工具,不修改产品。生成器创建新目录,目录已存在时会拒绝覆盖。测试使用合成 SQLite 合约数据,不代表真实 import/replay 的性能;没有运行完整测试套件,也没有验证修复。
将下列代码分别保存为
h2/generate.py、h2/measure.py,然后执行:其中
--operation query/timeout固定只请求event(id=0)和max_rows=1;JSONL 包含安装路径、重复次数、墙钟/CPU、RSS、高层 inspect 次数、每次真实 hash 的文件/字节/耗时、验证 SQL 计数。generate.py
measure.py
fix: make dataset validation cancellable and cache reuse explicit (#219…
fix: reuse a pinned query operation for peak reports (#221) (#227)
test: validate realistic and default-scale dataset queries (#223) (#229)
codeasier commentedon Oct 11, 2026
2026-10-11 最终验收:#233 已合入,精确合并提交的 main CI 全部通过。按正文顶部的已确认双模式契约关闭为 completed:默认 strong warm 完整 hash、不重复 validator,为 O(bytes + shards);immutable 为显式信任快路径。新 CLI 可 cold、无持久缓存,两模式均不保证原子 snapshot。历史“命中与数据量无关”不再作为默认 strong 验收要求,原文保留以便追溯。