Skip to content

feat(query): distinguish truncated pages without a default COUNT - #153

Merged
codeasier merged 2 commits into
mainfrom
feat/issue-140-query-completeness
Sep 19, 2026
Merged

codeasier merged 2 commits into
mainfrom
feat/issue-140-query-completeness

Conversation

@codeasier

@codeasier codeasier commented Sep 19, 2026 •

Copy link
Copy Markdown
Owner

📝 Description

Query JSON/API results now say whether a page is complete. Default total is this page's returned count; exact matching-set COUNT is opt-in via --exact-total / exact_total=True. A finite trailing LIMIT fetches one extra row to set has_more, then drops it. event / block / allocation add id as a sort tie-break. --timeout / PT_SNAP_QUERY_TIMEOUT uses a SQLite progress handler and is independent of -n; timeout exits as QUERY_TIMEOUT. Diagnostic skills keep bounded listings and honor has_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 added/updated
  • Focused pytest: 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 check and black --check on touched Python paths
  • basedpyright on touched src (0 errors)
  • Full pytest suite
  • Manual testing completed

✅ Checklist

  • Code follows project guidelines
  • Documentation updated (if applicable)
  • No new warnings introduced
  • Changes tested locally

Snapshot Runtime Provenance

  • Snapshot provenance evaluation completed when snapshot runtime files change
    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

  • Default total no longer becomes a COUNT when -n is hit. Callers that treated a capped total as the matching-set size must pass --exact-total.
  • Changelog is under [0.5.0] - Unreleased only.

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 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.

交叉评审结论(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-total COUNT 的测试;
    • 新增的 allocation id 平局排序未测试。
  • [低] 变更备注(请确认是否有意):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 上由父会话独立复核。

Comment thread src/pt_snap_cli/core/query_service.py Resolved
Comment thread src/pt_snap_cli/core/query_service.py Resolved
Comment thread src/pt_snap_cli/core/query_service.py Resolved
Comment thread src/pt_snap_cli/core/query_service.py Resolved
Comment thread CHANGELOG.md Resolved
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

Copy link
Copy Markdown
Owner Author

交叉评审里未落在行内的两点:

  • 残余测试:已补 top_n 完整性 / --exact-total、PT_SNAP_QUERY_TIMEOUT CLI、COUNT 共享超时、allocation 与 leak_detection 的 id 平局排序(4506c4f)。
  • 未知设备短路:有意保留。这是 main 上 execute_template / count_template 的既有行为,只是随 execute_template_page 搬家。CLI/API 仍先走 _resolve_device_id。

@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.

跟进复核(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 类型签名已保证数值输入,可留待后续。

评审视角结论:所有发现已解决,无新增阻塞项。

@codeasier
codeasier merged commit 792672f into main Sep 19, 2026
6 checks passed
@codeasier
codeasier deleted the feat/issue-140-query-completeness branch October 3, 2026 19:18
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.

[FEATURE] 查询结果完整性与分页协议:has_more/total 语义/超时保护

1 participant