Repository navigation
feat(query): expose field units and interpretation limits on templates - #147
Conversation
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
left a comment
There was a problem hiding this comment.
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_allocationon theallocatedpeak columns contradicts the repo's own counter semantics.trace_entry.allocatedis a live-occupancy counter (attach_blockadds,detach_blocksubtracts; each event stores the current total), soMAX(allocated)is the high-water mark of a point-in-time occupancy — the same class asactive/reserved, which this PR labelsinstantaneous_occupancy. The added limit "not a point-in-time occupancy" is wrong, andallocator_gapitself computes same-eventreserved - allocatedgaps 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_rowstruncation (applied after the window SUM). - LOW: strict
output_schemavalidation is a breaking change for user-authored template YAML; packaged-file failures are downgraded to a warning + whole-file skip. - LOW:
semantics_versionattributed from the global registry rather than the executed template (latent, not reachable today). - LOW: registry singleton's
output_schemaexposed 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.
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.
Follow-up (
|
codeasier
left a comment
There was a problem hiding this comment.
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:
- Stale MCP references. Beyond the
query/AGENTS.mdline annotated below, the PR description itself still claims exposure "through--template-info, the Python API, and MCP", liststests/test_mcp_server.pyandtests/test_contract_cli_mcp.pyin 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-59enforces 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. - Docs wording (en/zh
querying.md) implies that omittingsemantics_versionis what keepsoutput_schemaatcolumn/typeonly, but the parser validates the two independently. - Forward-hardening: the new validators accept multi-line strings and
": "insidecolumnnames, which could corrupt the CLI text protocol the contract tests rely on;_OUTPUT_SCHEMA_DETAIL_KEYSincli.pyduplicates the optional-key set already defined inquery/config.py.
codeasier
left a comment
There was a problem hiding this comment.
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.
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.
Follow-up (
|
output_schema now includes integer sentinels and list interpretation limits, so the str-only annotation was stale.
📝 Description
Add a validated field-semantics contract on query
output_schema(units,metric_semantics,scope, denominator, sentinel, interpretation limits) and expose it through--template-infoand the Python API. Result rows stay raw and cite the contract viatemplate/semantics_versioninstead of repeating long explanations.This reuses the existing YAML → config → registry → core → CLI/API path from #120 rather than introducing a second schema.
semantics_versionis distinct from YAMLversionand SnapshotDB/callstack layout; v1/v2 SQL variants share one contract. Unannotated templates remain valid withcolumn/typeonly; field annotations do not require a template-levelsemantics_version.Annotated first:
leak_detection,memory_peak,allocator_gap, andactive_memory_callstack_at_event. Diagnostic skills keep the decision flow and point at--template-infoinstead of redefining those fields.🔗 Related Issue
Fixes #141
🧪 Testing
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.pyruff check .,black --check src tests✅ Checklist
Snapshot Runtime Provenance
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
--jsonfor--template-infois 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.