Skip to content

[H2] 每次查询(含 tab 补全)都完整校验并哈希整个数据集,且不可被超时中断 #219

Closed

Description

@codeasier

最终验收状态(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 校验,也不证明数据完整性。
  • fix: make dataset validation cancellable and cache reuse explicit (#219) #226 / perf: reuse content-verified dataset validation in process #230 的实现及 test: close bounded-query and integrity-mode acceptance gaps (#218, #219) #233 的 36 项 compatibility-v1/native-v2 × default-strong/explicit-immutable 回归覆盖实际 hash-read bytes、validator 次数、cold/warm、manifest/成员替换、隐藏 change-token 边界、取消/失效、连接所有权及新进程 cold。证据以真实读取量和调用次数为主,不仅是 wall-clock。
  • test: close bounded-query and integrity-mode acceptance gaps (#218, #219) #233 共新增 41 项回归(本项 36 + [H1] 全局查询全量取行到 Python,被硬编码工作预算卡死 #218 5),已合入 main 39fefd1dad820f3262604f0dc9fb9bf9811a248a(tree fdd05481d3e467f2546d52bda2dc2b61dabe1d61)。合并前 CI 38104812415 七项通过。合并后精确 main 提交的 CI 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

  1. codeasier commented on Oct 10, 2026

    @codeasier
    OwnerAuthor

    在固定提交 7c33464906aced190698452ebb3a8de8e8e9ab05 上完成了实际运行复现。结论:本 issue 的核心问题成立,且 native-v2 的分片 SHA256 实际为 每次 inspect 3 遍,不是原文推测的 2 遍。

    环境与测量口径

    • 2026-10-10,Linux x86_64,Python 3.12.14,SQLite 3.53.1,安装版本 0.4.0.post1.dev31。
    • 从上述提交 pip install 到独立 venv(非 editable);测量进程的 pt_snap_cli.__file__ 确认位于 venv 的 site-packages,不从源码目录导入。
    • 纯 SQL 生成 compatibility-v1 / native-v2 合成数据;1 个设备,分别 1 千 / 10 万 / 100 万条 event,并有相同数量的 block。没有加载 pickle,没有改产品代码。
    • 每个规模/操作启动新 Python 进程,同一进程内重复 3 次,服务对象复用。下面 inspect 表中耗时取 3 次中位数,RSS 为该进程 3 次运行的最高 ru_maxrss / 1024,单位 MiB,包含解释器与导入基线约 21.5 MiB;不是净增量或保留内存。
    • 数据刚生成,未清理 OS 页缓存;共享云环境绝对耗时会波动,重点是重复全量工作、行数增长关系及超时不能及时中断。

    实测

    1. inspect 及重复查询仍随行数增长

    格式 event / block 数 inspect 中位耗时 进程峰值 RSS
    compatibility-v1 1,000 / 1,000 0.0050 s 22.39 MiB
    compatibility-v1 100,000 / 100,000 0.4335 s 57.00 MiB
    compatibility-v1 1,000,000 / 1,000,000 4.1557 s 333.75 MiB
    native-v2 1,000 / 1,000 0.0047 s 23.27 MiB
    native-v2 100,000 / 100,000 0.3637 s 101.05 MiB
    native-v2 1,000,000 / 1,000,000 3.7056 s 728.99 MiB

    百万级 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 三次调用:

    • v1:4.156 / 4.104 / 3.999 s
    • native:3.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:

    操作(百万级 fixture) v1 耗时 / 峰值 RSS native 耗时 / 峰值 RSS
    event --params '{"id":0}' -n 1 --json 4.781 s / 296.45 MiB 4.039 s / 730.14 MiB
    相同查询加 --timeout 2 4.606 s / 296.45 MiB 3.979 s / 730.14 MiB
    Bash query --device <Tab> 4.491 s / 296.43 MiB 3.874 s / 730.12 MiB

    补全正常输出 0。准确范围是dataset 的设备 ID 补全;模板名等静态补全不走这里。

    超时查询退出码为 1,stderr JSON 是 error.code=QUERY_TIMEOUT、Query timed out after 2.0 seconds。也就是说,预算确实计入 inspect 的耗时,但只在完整 inspect 返回后才报错,无法在 2 秒时终止该阶段。核心服务三次 timeout_s=2 分别用了 v1 4.214 / 4.590 / 3.870 s、native 3.953 / 4.064 / 3.791 s;每次均完成了全部校验及哈希。

    3. 运行期计数:native 三遍哈希,report 三次 inspect

    instrumentation 只包装原函数进行计时/计数,不跳过其工作;SQLite trace 记录原始验证 SQL:

    • v1 单分片每次 inspect:manifest 哈希 2 次、分片哈希 1 次。
    • native 单分片每次 inspect:manifest 哈希 2 次、分片哈希 3 次,并执行 1 次 PRAGMA quick_check。
    • native 百万级分片为 85,946,368 bytes;仅该分片一轮 inspect 就累计哈希 257,839,104 bytes,不含 manifest。v1 百万级分片为 74,919,936 bytes。
    • 额外的 10 万事件 / 4 分片实验(这是 validator 接受的简化合成布局;各片仅写本片新分配 block,没有补齐仍存活 block 的 carry-in,因此不是 exporter-faithful 成员布局,只用于观察 inspect/哈希调用,不用于生命周期查询正确性结论):仍仅查询 id=0,v1 会哈希全部 4 个分片;native 会哈希全部分片共 12 次,执行 4 次 quick_check,尽管目标 event 只在第一片。
    • 在1000 行的成功报告上,ReportService.peak_memory_report 两种格式都调用 inspect 3 次;v1 总共 3 次分片哈希,native 共 9 次。本项计数不是对百万级报告能够成功跑完的声明。

    对应代码

    修复与验收建议

    1. 明确“完整验证”和“已验证 generation 的轻量解析”边界。在 finalized/不可变发布约束与安全的失效策略下复用验证结果;同一个 report 的 3 个子查询复用同一 generation。完整验证移到 import 发布边界或显式 validate 时,需要说明外部/未验证数据的准入流程;不能为性能跳过必需的完整性校验,缓存 miss 的强验证也必须可取消。仅缓存 Context 不能消除当前开销。
    2. 缓存键至少考虑规范路径、文件身份/元数据与 manifest generation;不能把 (inode,size,mtime) 当作无条件的内容完整性证明。保留替换、manifest 改变、sidecar/symlink、内容改变等拒绝和失效契约。固定分片数时 warm path 应不再随 event/block 行数增加;分片数增长时仍可能有 O(分片数) 的 stat 检查,验收需区分。
    3. 设备补全只需受限地解析设备列表,不应执行全行生命周期/quick_check/分片 SHA256;无需先完整证明整个数据集才能给出补全候选。
    4. 将共用 deadline 传入解析、校验、哈希:Python 循环按批检查,哈希按 chunk 检查,SQLite 校验 SQL/quick_check 使用并清理 progress handler。不能只在 inspect 返回后检查。
    5. native 可复用已验证哈希来形成 fingerprint,避免冗余的第三遍;校验前后哈希目前承担内容变化检测,不能直接盲删。仅省哈希也不能解决 IDs、blocks、references 等 O(N) 内存,需要调整完整校验的执行位置及算法。
    6. 自动化回归优先断言工作量:第二次查询/补全不触发全表验证或完整哈希;单个报告只解析一次 generation;在校验循环、哈希和 quick_check 内分别触发 deadline;失败后资源关闭、下次查询可用;manifest/成员替换、mtime 变化和内容篡改不能错误命中;缓存 miss 验证期间同样遵守预算。另保留百万级 opt-in 性能/RSS 测试,避免把本机的秒数作为通用 CI 阈值。

    可直接复现(自包含)

    以下两个脚本均为复现工具,不修改产品。生成器创建新目录,目录已存在时会拒绝覆盖。测试使用合成 SQLite 合约数据,不代表真实 import/replay 的性能;没有运行完整测试套件,也没有验证修复。

    git clone https://github.com/codeasier/pt-snap-cli.git ptsnap-219
    git -C ptsnap-219 checkout 7c33464906aced190698452ebb3a8de8e8e9ab05
    python3.12 -m venv venv
    venv/bin/python -m pip install ./ptsnap-219
    mkdir -p h2/logs

    将下列代码分别保存为 h2/generate.py、h2/measure.py,然后执行:

    for n in 1000 100000 1000000; do
      venv/bin/python h2/generate.py h2/v1-$n --rows "$n"
      venv/bin/python h2/generate.py h2/native-$n --rows "$n" --native
      for kind in v1 native; do
        venv/bin/python h2/measure.py h2/$kind-$n --operation inspect --repeat 3 > h2/logs/inspect-$kind-$n.jsonl
      done
    done
    for kind in v1 native; do
      for op in query completion timeout; do
        venv/bin/python h2/measure.py h2/$kind-1000000 --operation "$op" --repeat 3 --timeout 2 > h2/logs/$op-$kind.jsonl
      done
      venv/bin/python h2/measure.py h2/$kind-1000 --operation report
      venv/bin/pt-snap query h2/$kind-1000000 --template-use event --params '{"id":0}' -n 1 --timeout 2 --json
      PT_SNAP_DB_PATH="$PWD/h2/$kind-1000000" COMP_WORDS='pt-snap query --device ' COMP_CWORD=3 _PT_SNAP_COMPLETE=complete_bash venv/bin/pt-snap
    done
    # 4 分片选择性查询(native 加 --native):
    venv/bin/python h2/generate.py h2/v1-4shards --rows 100000 --shards 4
    venv/bin/python h2/measure.py h2/v1-4shards --operation query

    其中 --operation query/timeout 固定只请求 event(id=0) 和 max_rows=1;JSONL 包含安装路径、重复次数、墙钟/CPU、RSS、高层 inspect 次数、每次真实 hash 的文件/字节/耗时、验证 SQL 计数。

    generate.py
    """Synthetic trusted SQL-only fixtures, separate from product and executable pickles."""
    import argparse, hashlib, json, sqlite3, time
    from pathlib import Path
    from pt_snap_cli.core.dataset_contract import ACTION_NAMES, BLOCK_STATES
    from pt_snap_cli.core.native_dataset_contract import cache_identity
    
    def make(root, n, native=False, shards=1):
        root = Path(root).absolute()
        root.mkdir(parents=True, exist_ok=False)
        (root/'device_0').mkdir()
        metadata = dict(metadata_schema_version=1, import_format_version=2,
            source_sha256=hashlib.sha256(b'synthetic sql fixture').hexdigest(),
            source_size=0, source_name='synthetic-sql-no-pickle', requested_device=None,
            importer_name='pt-snap-cli', importer_version='repro-fixture', completed_at='2026-10-10T00:00:00+00:00')
        capacity = (n + shards - 1) // shards
        slices = []
        for index, start in enumerate(range(0,n,capacity)):
            end = min(n,start+capacity)-1
            relative = f'device_0/slice_{index:05d}.db'
            path = root/relative
            with sqlite3.connect(path) as conn:
                conn.execute('PRAGMA journal_mode=OFF')
                conn.execute('PRAGMA synchronous=OFF')
                conn.execute('PRAGMA cache_size=-8192')
                stack_column = 'callstackId INTEGER' if native else 'callstack TEXT'
                conn.executescript('CREATE TABLE dictionary ("table" TEXT, "column" TEXT, "key" TEXT, "value" TEXT);'
                  f'CREATE TABLE trace_entry_0 (id INTEGER PRIMARY KEY, action INTEGER,address INTEGER,size INTEGER,stream INTEGER,allocated INTEGER,active INTEGER,reserved INTEGER,{stack_column});'
                  'CREATE TABLE block_0 (id INTEGER PRIMARY KEY,address INTEGER,size INTEGER,requestedSize INTEGER,state INTEGER,allocEventId INTEGER,freeEventId INTEGER);')
                actions = (*ACTION_NAMES,'oom') if native else ACTION_NAMES
                conn.executemany('INSERT INTO dictionary VALUES (?,?,?,?)',
                    [('trace_entry_0','action',str(i),v) for i,v in enumerate(actions)] +
                    [('block_0','state',str(i),v) for i,v in BLOCK_STATES])
                conn.executemany('INSERT INTO trace_entry_0 VALUES (?,?,?,?,?,?,?,?,?)',
                    ((i,4,4096+i*64,64,0,(i+1)*64,(i+1)*64,n*64,0 if native else 'fixture.py:1:test') for i in range(start,end+1)))
                conn.executemany('INSERT INTO block_0 VALUES (?,?,?,?,?,?,?)',
                    ((i,4096+i*64,64,64,1,i,-1) for i in range(start,end+1)))
                if native:
                    conn.executescript('CREATE TABLE callstack (id INTEGER PRIMARY KEY, callstack TEXT);'
                       "INSERT INTO callstack VALUES (0, 'fixture.py:1:test');"
                       'CREATE TABLE pt_snap_block_reference (blockId INTEGER PRIMARY KEY,stream INTEGER,allocCallstack TEXT,freeCallstack TEXT);')
                    conn.executemany('INSERT INTO pt_snap_block_reference VALUES (?,?,?,?)',
                       ((i,0,'fixture.py:1:test',None) for i in range(start,end+1)))
                    coltypes = [f'"{k}" '+('INTEGER' if isinstance(v,int) or v is None else 'TEXT') for k,v in metadata.items()]
                    conn.execute('CREATE TABLE pt_snap_metadata (id INTEGER PRIMARY KEY,'+','.join(coltypes)+')')
                    conn.execute('INSERT INTO pt_snap_metadata VALUES ('+','.join('?' for _ in range(len(metadata)+1))+')',[1,*metadata.values()])
                conn.commit()
            conn.close()
            item = dict(index=index,startEventId=start,endEventId=end,file=relative,ready=True)
            if native:
                with path.open('rb') as source:
                    digest = hashlib.file_digest(source,'sha256').hexdigest()
                item.update(startPosition=start,endPosition=end,sha256=digest)
            slices.append(item)
        manifest = dict(schemaVersion=1,status='complete',sourceFile=metadata['source_name'],
           devices={'0':dict(eventCount=n,sliceCount=len(slices),readySlices=list(range(len(slices))),slices=slices)})
        if native:
            manifest.update(format='pt-snap-native-v2',identity=cache_identity(metadata['source_sha256'],None,capacity),metadata=metadata,omittedDevices=[])
        else:
            manifest.update(cacheHash='',eventsPerSlice=capacity)
        (root/'manifest.json').write_text(json.dumps(manifest,indent=2)+'\n')
        return {'path':str(root),'events':n,'blocks':n,'native':native,'shards':len(slices),'db_bytes':sum((root/s['file']).stat().st_size for s in slices)}
    
    if __name__=='__main__':
        p=argparse.ArgumentParser(); p.add_argument('path'); p.add_argument('--rows',type=int,required=True); p.add_argument('--native',action='store_true'); p.add_argument('--shards',type=int,default=1); a=p.parse_args()
        t=time.perf_counter(); result=make(a.path,a.rows,a.native,a.shards); result['generation_s']=time.perf_counter()-t; print(json.dumps(result))
    measure.py
    """Measure installed pt_snap_cli. Instrumentation counts real calls, never stubs work."""
    import argparse, collections, json, os, platform, resource, sqlite3, sys, time
    from pathlib import Path
    import pt_snap_cli
    from pt_snap_cli.core import dataset_resolver as dr, native_dataset_contract as nc
    from pt_snap_cli.core.query_service import QueryService
    from pt_snap_cli.core.report_service import ReportService
    from pt_snap_cli.completion import complete_device_ids
    
    p=argparse.ArgumentParser(); p.add_argument('path'); p.add_argument('--operation',choices=['inspect','query','timeout','completion','report'],default='inspect'); p.add_argument('--repeat',type=int,default=1); p.add_argument('--timeout',type=float,default=2); a=p.parse_args()
    path=Path(a.path).absolute(); counters=collections.Counter(); hash_calls=[]; inspect_calls=[]; sql=collections.Counter()
    original_connect=sqlite3.connect
    
    def connect(*args,**kwargs):
        conn=original_connect(*args,**kwargs); conn.set_trace_callback(lambda statement: sql.update([statement])); return conn
    sqlite3.connect=connect
    
    def hash_wrapper(owner, original):
        def wrapper(path):
            t=time.perf_counter(); value=original(path)
            hash_calls.append({'owner':owner,'name':str(Path(path).relative_to(path_root)),'bytes':Path(path).stat().st_size,'wall_s':time.perf_counter()-t})
            return value
        return wrapper
    path_root=path
    for module in (dr,nc):
        module._hash_file=hash_wrapper(module.__name__,module._hash_file)
    original_inspect=dr.DatasetResolver.inspect
    
    def inspect(self,*args,**kwargs):
        t=time.perf_counter()
        try: return original_inspect(self,*args,**kwargs)
        finally: inspect_calls.append(time.perf_counter()-t)
    dr.DatasetResolver.inspect=inspect
    resolver=dr.DatasetResolver(); service=QueryService(); report=ReportService()
    os.environ['PT_SNAP_DB_PATH']=str(path)
    print(json.dumps({'environment':{'python':sys.version,'package':pt_snap_cli.__file__,'version':pt_snap_cli.__version__,'sqlite':sqlite3.sqlite_version,'platform':platform.platform(),'pid':os.getpid(),'ru_maxrss_unit':'KiB Linux','baseline_rss_peak_kib':resource.getrusage(resource.RUSAGE_SELF).ru_maxrss},'path':str(path),'operation':a.operation}),flush=True)
    try:
        for run in range(a.repeat):
            hash_calls.clear(); inspect_calls.clear(); sql.clear()
            t=time.perf_counter(); c=time.process_time(); before=resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
            result={}
            try:
                if a.operation=='inspect':
                    value=resolver.inspect(path); result={'fingerprint':value.fingerprint,'events':value.validation.real_event_count,'devices':value.device_ids}
                elif a.operation=='completion': result={'device_ids':complete_device_ids()}
                elif a.operation=='report':
                    value=report.peak_memory_report(path,limit=1); result={'event_id':value.event_id,'groups':len(value.callstack_groups)}
                else:
                    value=service.execute_query('event',{'id':0},db_path=path,max_rows=1,timeout_s=a.timeout if a.operation=='timeout' else None)
                    result={'row_count':len(value.rows),'first_id':value.rows[0]['id'] if value.rows else None}
                result['status']='ok'
            except Exception as exc:
                result={'status':'error','error_type':type(exc).__name__,'error':str(exc)}
            result.update(run=run+1,wall_s=time.perf_counter()-t,cpu_s=time.process_time()-c,rss_peak_kib=resource.getrusage(resource.RUSAGE_SELF).ru_maxrss,rss_peak_increment_kib=resource.getrusage(resource.RUSAGE_SELF).ru_maxrss-before,inspect_calls=inspect_calls,hash_calls=hash_calls,sql=dict(sql))
            print(json.dumps(result),flush=True)
    finally:
        service.close(); report.close()
  2. codeasier commented on Oct 11, 2026

    @codeasier
    OwnerAuthor

    2026-10-11 最终验收:#233 已合入,精确合并提交的 main CI 全部通过。按正文顶部的已确认双模式契约关闭为 completed:默认 strong warm 完整 hash、不重复 validator,为 O(bytes + shards);immutable 为显式信任快路径。新 CLI 可 cold、无持久缓存,两模式均不保证原子 snapshot。历史“命中与数据量无关”不再作为默认 strong 验收要求,原文保留以便追溯。

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions