Repository navigation
feat(query): distinguish truncated pages without a default COUNT - #153
Conversation
Agents cannot tell a complete result from a capped page when total silently becomes a COUNT at the row limit. Probe one extra row for has_more, keep exact totals opt-in, and time-bound execution separately from output limits. Fixes #140
codeasier
left a comment
There was a problem hiding this comment.
交叉评审结论(3/3 评审者成功,父会话裁决)
核心机制验证无误:额外一行探测 has_more、可选 COUNT、progress-handler 超时、event / block / allocation 的 id 平局排序、错误码顺序(ExecutorQueryTimeoutError 先于 ExecutorQueryExecutionError,子类先于基类)均正确。Request changes 仅针对 1 个中等发现(top_n 模板假完整信号,见行内评论),其余 6 个为低严重度。
未落在行内的发现
- [低] 残余测试缺口:
- 无
top_n-only 模板(active_memory_callstack_at_event)的truncated/--exact-total行为测试——正是中等发现所在; - 无
PT_SNAP_QUERY_TIMEOUT的 CLI 端到端测试(现有仅覆盖resolve_query_timeout单元与显式--timeout); - 无超时同样约束
--exact-totalCOUNT 的测试; - 新增的
allocationid平局排序未测试。
- 无
- [低] 变更备注(请确认是否有意):
execute_template_page现在在渲染(即参数校验)之前对未知设备短路返回([], False, None)(executor.py:443-444)。CLI/API 路径不受影响(_resolve_device_id先行校验设备),但直接使用 executor 的库调用者会看到错误优先级变化。
出处
评审模型:volceapi/qwen3.8-flash、opencode-go/deepseek-v4.1-flash、opencode-go/muse-spark-1.3-contributor(后者无发现);所有发现均已在快照 a6627a5 上由父会话独立复核。
Default completeness flags ignored CTE ranking caps, so a ranked callstack page looked finished after dropping groups. Share the timeout budget across page and COUNT, and keep exact totals opt-in.
|
交叉评审里未落在行内的两点:
|
codeasier
left a comment
There was a problem hiding this comment.
跟进复核(cross-review follow-up,针对 4506c4f)
6 条行内评论已逐项复核并在线程内回复关闭,全部确认修复:
| 发现 | 处理 | 验证 |
|---|---|---|
【中】top_n 假完整信号 |
_finite_top_n + _inner_rank_window_full cap-hit 置 has_more/truncated;exact-total 用 total > returned 覆盖 |
新测试 + 本地运行 |
| 【低】超时按语句计 2× | _remaining_timeout 共享一次调用预算 |
新测试 ×2 + 本地运行 |
【低】非法 env 超时归 QUERY_FAILED |
InvalidParameterError → INVALID_PARAMETER |
新 CLI e2e 测试 |
| 【低】env 作用于 report 无覆盖 | 文档化(en/zh docs + CHANGELOG) | 已确认 |
【低】leak_detection 缺平局排序 |
ORDER BY size DESC, id DESC |
新测试 + 本地运行 |
| 【低】CHANGELOG 兼容性提示 | 已补充默认 total 变更条目 |
已确认 |
总评中的测试缺口也已补齐(top_n 模板完整性、CLI env 超时 e2e、COUNT 超时、allocation/leak_detection 平局排序),execute_template_page 的设备短路行为已加注释说明。
本地验证(检出 4506c4f):tests/query、tests/core、tests/skills、test_cli_json.py、test_api.py、test_contract_cli_api.py 共 563 passed;ruff check 与 black --check 通过。
唯一残留(不阻塞):显式传入非 bool 的非数值 timeout(如字符串)仍会在 explicit > 0 处抛未分类 TypeError——CLI/API 类型签名已保证数值输入,可留待后续。
评审视角结论:所有发现已解决,无新增阻塞项。
📝 Description
Query JSON/API results now say whether a page is complete. Default
totalis this page'sreturnedcount; exact matching-setCOUNTis opt-in via--exact-total/exact_total=True. A finite trailingLIMITfetches one extra row to sethas_more, then drops it.event/block/allocationaddidas a sort tie-break.--timeout/PT_SNAP_QUERY_TIMEOUTuses a SQLite progress handler and is independent of-n; timeout exits asQUERY_TIMEOUT. Diagnostic skills keep bounded listings and honorhas_more.New envelope fields on the existing #138 success object:
has_more,truncated,total_is_exact,timeout_s.🔗 Related Issue
Fixes #140
Related to the Agent-friendly parent roadmap (issue 136) only. This slice must not auto-close that parent.
🧪 Testing
tests/query/test_query_completeness.py,tests/core/test_query_service.py,tests/query/,tests/test_cli_json.py,tests/test_contract_cli_api.py,tests/test_api.py, skill contract tests (387 passed)pytest tests/test_cli.py -k query(50 passed)ruff checkandblack --checkon touched Python pathsbasedpyrighton touched src (0 errors)pytestsuite✅ Checklist
Snapshot Runtime Provenance
Snapshot provenance decision: no-update
Snapshot provenance no-update reason: This PR only changes query completeness/pagination/timeout, CLI/API envelope fields, templates, skills, tests, and docs. It does not modify
src/pt_snap_cli/snapshot/**.📋 Additional Notes
totalno longer becomes a COUNT when-nis hit. Callers that treated a cappedtotalas the matching-set size must pass--exact-total.[0.5.0] - Unreleasedonly.