Skip to content

feat(query): expose field units and interpretation limits on templates - #147

Merged
codeasier merged 4 commits into
mainfrom
issue-141-query-semantics
Sep 18, 2026
Merged

codeasier merged 4 commits into
mainfrom
issue-141-query-semantics

Conversation

@codeasier

@codeasier codeasier commented Sep 18, 2026 •

Copy link
Copy Markdown
Owner

📝 Description

Add a validated field-semantics contract on query output_schema (units, metric_semantics, scope, denominator, sentinel, interpretation limits) and expose it through --template-info and the Python API. Result rows stay raw and cite the contract via template / semantics_version instead of repeating long explanations.

This reuses the existing YAML → config → registry → core → CLI/API path from #120 rather than introducing a second schema. semantics_version is distinct from YAML version and SnapshotDB/callstack layout; v1/v2 SQL variants share one contract. Unannotated templates remain valid with column/type only; field annotations do not require a template-level semantics_version.

Annotated first: leak_detection, memory_peak, allocator_gap, and active_memory_callstack_at_event. Diagnostic skills keep the decision flow and point at --template-info instead of redefining those fields.

🔗 Related Issue

Fixes #141

🧪 Testing

  • Tests added/updated
  • Manual testing completed
  • pytest tests/query/test_config.py tests/query/test_template_semantics.py tests/query/test_registry.py tests/query/test_peak_memory_templates.py tests/core/test_query_service.py tests/test_api.py tests/test_contract_cli_api.py tests/test_cli.py tests/test_bundled_skills.py tests/skills/test_memory_leak_contract.py tests/skills/test_memory_peak_breakdown_contract.py
  • ruff check ., black --check src tests

✅ 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: Query template metadata, CLI/API presentation, docs, and skills only; snapshot runtime is unchanged.

📋 Additional Notes

--json for --template-info is still owned by #138; this PR makes the same metadata available as structured API dicts and CLI text that the CLI/API contract parser round-trips.

Agents were inferring statistical meaning from column names and skill
docs, which drift and cause misreads such as treating
percent_of_active_blocks as a block-count share. Put a validated
semantics contract on output_schema and surface it through
--template-info, the API, and MCP.

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

Reviewed by 3 independent reviewer models on an isolated snapshot at head f0df4f0, then independently verified finding-by-finding against the source (allocator replay semantics, snapshot2db event emission, executor limit push-down, registry caching).

1 verified HIGH + 6 LOW findings — details in the inline comments:

Note: this review would normally be submitted as Request changes; GitHub does not allow requesting changes on one's own PR, so it is submitted as a comment review instead. The HIGH finding should be addressed before merge.

  • HIGH: metric_semantics: cumulative_allocation on the allocated peak columns contradicts the repo's own counter semantics. trace_entry.allocated is a live-occupancy counter (attach_block adds, detach_block subtracts; each event stores the current total), so MAX(allocated) is the high-water mark of a point-in-time occupancy — the same class as active/reserved, which this PR labels instantaneous_occupancy. The added limit "not a point-in-time occupancy" is wrong, and allocator_gap itself computes same-event reserved - allocated gaps that are only coherent under the point-in-time reading. Since this PR's deliverable is the agent-facing interpretation contract, this should be fixed before merge.
  • LOW: percent denominator text omits caller-side max_rows truncation (applied after the window SUM).
  • LOW: strict output_schema validation is a breaking change for user-authored template YAML; packaged-file failures are downgraded to a warning + whole-file skip.
  • LOW: semantics_version attributed from the global registry rather than the executed template (latent, not reachable today).
  • LOW: registry singleton's output_schema exposed by reference through the Python API.
  • LOW: tautological test assertion.

Everything else verified clean: pipeline consistency (YAML → config → registry → service → CLI/API/MCP), validation vocabularies, CLI↔MCP round-trip contract tests, en/zh doc symmetry, bundled-skills byte-identity, no snapshot/ or PROVENANCE.md surface touched.

Comment thread src/pt_snap_cli/query/config.py Resolved
Comment thread src/pt_snap_cli/core/query_service.py Resolved
Comment thread src/pt_snap_cli/query/registry.py Resolved
Comment thread tests/query/test_template_semantics.py Resolved
Correct allocated peak columns to instantaneous occupancy, document
max_rows after callstack percentages, and deep-copy output_schema at
the service boundary after MCP removal on main.
@codeasier

Copy link
Copy Markdown
Owner Author

Follow-up (d571dc9)

Merged origin/main (MCP removal) into this branch and addressed the review:

  • HIGH: Relabeled allocated peak columns as instantaneous_occupancy on memory_peak and allocator_gap; dropped the incorrect “not a point-in-time occupancy” limit.
  • LOW (done): Documented caller-side max_rows after callstack percentages; deep-copied output_schema at the service boundary; removed the tautological variant assertion.
  • LOW (wontfix / defer): Strict output_schema validation stays; registry vs runtime semantics_version is not reachable on CLI/API today.

CLI/API contract tests now live in tests/test_contract_cli_api.py. Focused suite: 253 passed.

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

Follow-up cross-review (round 2, head d571dc9)

Re-reviewed by 3 independent reviewer models with parent-session verification. The previous round's HIGH finding (cumulative_allocation on the allocated peak columns) and the follow-up LOW items (denominator max_rows note, output_schema deep copy in QueryService.get_template_info, tautological test assertion) are all verified fixed. No code-level blocking defects this round.

Remaining low-severity items, published inline below:

  1. Stale MCP references. Beyond the query/AGENTS.md line annotated below, the PR description itself still claims exposure "through --template-info, the Python API, and MCP", lists tests/test_mcp_server.py and tests/test_contract_cli_mcp.py in the test command, and mentions "CLI/MCP contract parser round-trips" — none of which exist at this head, since the merge from main removed the MCP surface (tests/test_package.py:48-59 enforces removal). The recorded test command would error on nonexistent paths, so the stated validation is not reproducible as written. Recommend updating the PR description (feature story + test checklist) along with the AGENTS.md wording.
  2. Docs wording (en/zh querying.md) implies that omitting semantics_version is what keeps output_schema at column/type only, but the parser validates the two independently.
  3. Forward-hardening: the new validators accept multi-line strings and ": " inside column names, which could corrupt the CLI text protocol the contract tests rely on; _OUTPUT_SCHEMA_DETAIL_KEYS in cli.py duplicates the optional-key set already defined in query/config.py.

Comment thread src/pt_snap_cli/query/AGENTS.md Resolved
Comment thread docs/en/querying.md Resolved
Comment thread docs/zh/querying.md Resolved
Comment thread src/pt_snap_cli/query/config.py Resolved
Comment thread src/pt_snap_cli/cli.py Resolved

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

One further item from the round-2 cross-review that was held back pending a decision: the dead peak vocabulary value. Since semantics_version: 1 freezes the contract at release, this is the last cheap moment to resolve it either way.

Comment thread src/pt_snap_cli/query/config.py Resolved
Remove unused peak and cumulative_allocation labels before v1 freeze,
share output_schema optional keys with the CLI, and separate
semantics_version from field annotations in the docs.
@codeasier

Copy link
Copy Markdown
Owner Author

Follow-up (bcb0dfc)

Second review pass:

Previous HIGH allocated-occupancy fix remains in d571dc9.

output_schema now includes integer sentinels and list interpretation
limits, so the str-only annotation was stale.
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] 查询模板语义元数据:字段单位、统计口径与解释限制

1 participant