From f0df4f027e2badc7436b3861c362af3a804a1062 Mon Sep 17 00:00:00 2001 From: codeasier Date: Fri, 18 Sep 2026 22:08:09 +0800 Subject: [PATCH 1/3] feat(query): expose field units and interpretation limits on templates 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. --- docs/en/mcp.md | 4 +- docs/en/querying.md | 23 ++- docs/en/snapshot-analyzer-api.md | 13 +- docs/zh/mcp.md | 4 +- docs/zh/querying.md | 23 ++- docs/zh/snapshot-analyzer-api.md | 11 +- skills/pt-snap-memory-leak/SKILL.md | 4 +- skills/pt-snap-memory-peak-breakdown/SKILL.md | 5 +- src/pt_snap_cli/api.py | 4 + .../pt-snap-memory-leak/SKILL.md | 4 +- .../pt-snap-memory-peak-breakdown/SKILL.md | 5 +- src/pt_snap_cli/cli.py | 39 ++++- src/pt_snap_cli/core/models.py | 6 +- src/pt_snap_cli/core/query_service.py | 9 ++ src/pt_snap_cli/query/AGENTS.md | 3 +- src/pt_snap_cli/query/config.py | 143 +++++++++++++++++- src/pt_snap_cli/query/mapper.py | 8 +- src/pt_snap_cli/query/registry.py | 2 + src/pt_snap_cli/query/templates/AGENTS.md | 2 + .../active_memory_callstack_at_event.yaml | 37 +++++ .../templates/business/leak_detection.yaml | 20 ++- .../templates/statistical/allocator_gap.yaml | 73 +++++++++ .../templates/statistical/memory_peak.yaml | 31 +++- tests/core/test_query_service.py | 2 + tests/query/AGENTS.md | 1 + tests/query/test_config.py | 91 +++++++++++ tests/query/test_peak_memory_templates.py | 14 ++ tests/query/test_registry.py | 1 + tests/query/test_template_semantics.py | 102 +++++++++++++ tests/skills/test_memory_leak_contract.py | 4 +- .../test_memory_peak_breakdown_contract.py | 8 +- tests/test_api.py | 19 +++ tests/test_cli.py | 11 ++ tests/test_contract_cli_mcp.py | 87 ++++++++++- tests/test_mcp_server.py | 5 + 35 files changed, 768 insertions(+), 50 deletions(-) create mode 100644 tests/query/test_template_semantics.py diff --git a/docs/en/mcp.md b/docs/en/mcp.md index dd2ddb6..8b7cbb6 100644 --- a/docs/en/mcp.md +++ b/docs/en/mcp.md @@ -29,7 +29,7 @@ This starts a FastMCP server that exposes tools for analyzing PyTorch memory sna | `get_focus` | Get the current analysis focus (database path, device ID, source) | | `set_focus` | Set focus to a database and optional device. Use before running queries. | | `list_templates` | List available query templates, optionally filtered by category | -| `get_template_info` | Get detailed information about a template including parameters | +| `get_template_info` | Get detailed information about a template including parameters, output schema, and field semantics | | `execute_query` | Execute a query template against the focused database. Returns at most `max_rows` rows (default **100**; pass `0` for unlimited). See [Query Results and Row Limits](#query-results-and-row-limits). | | `get_database_metadata` | Inspect import provenance for the focused or specified database | @@ -86,6 +86,8 @@ get_database_metadata() | `returned` | Number of rows actually included in `rows`. | | `device_id` | The device the query ran against (explicit `device_id`, else the focused device, else the first device in the database). | | `rows` | The result rows as dictionaries of raw SQLite values. | +| `template` | Template that produced the rows. | +| `semantics_version` | Field-interpretation contract to look up with `get_template_info`, or `null`. | **The MCP default is `max_rows=100`, which differs from the CLI.** `pt-snap query` shows every row unless `-n` is given; the MCP tool caps output so a large result diff --git a/docs/en/querying.md b/docs/en/querying.md index f8b3d10..839e883 100644 --- a/docs/en/querying.md +++ b/docs/en/querying.md @@ -22,7 +22,7 @@ pt-snap query [DB_PATH] [--template-use ] [--params ] \ | `--device` | Device ID | | `--list` | List available query templates | | `--category` | Filter templates by category: `basic`, `statistical`, `business` | -| `--template-info` | Show template details (parameters and output schema) | +| `--template-info` | Show template details (parameters, output schema, and field semantics) | | `-n` | Maximum displayed rows; zero or a negative value means unlimited | ## Query Templates @@ -60,7 +60,7 @@ Domain-specific analysis. | Template | Description | |----------|-------------| -| `leak_detection` | Find allocations without matching free events | +| `leak_detection` | Find captured allocations with no recorded free-completion event (leak candidates) | | `active_memory_callstack_at_event` | Aggregate blocks active at a specific event by allocation callstack, with static and preexisting memory classified separately | ## Leak Detection @@ -71,6 +71,9 @@ pt-snap query --template-use leak_detection --params '{"min_size": 1024}' `min_size` is the minimum candidate size in bytes and defaults to `0`. Select the target device with the command-level `--device` option, not inside `--params`. +`leak_detection` returns candidates that were still live in the captured range, +not confirmed leaks. Read field units and interpretation limits with +`pt-snap query --template-info leak_detection`. ## Parameter Validation @@ -221,14 +224,26 @@ The "Found N" count is exact even when output is capped. Note that the MCP CLI, Python API, and MCP query results contain raw SQLite values. A template's `output_schema` is metadata and is not applied automatically during query execution. Use `ResultMapper` explicitly when converted values such as -hexadecimal address strings are required. +hexadecimal address strings are required. Result rows do not repeat field +explanations; look up `semantics_version` and interpretation limits with +`--template-info` (or `get_template_info`) for the template that produced the +rows. The Python API and MCP `execute_query` results also include `template` +and `semantics_version` so that lookup stays tied to the rows. ## Template Architecture Query templates are defined in YAML format with: -- `version`: Template version +- `version`: YAML file format version, not the field-semantics contract and not the SnapshotDB schema version - `queries`: Query definitions with description, supported devices, parameters, SQL (Jinja2 templated), and output schema - Each parameter declares `type`, `default`, `required`, `description`, and optionally `choices`, a closed list of accepted values that is mandatory for parameters rendered as SQL identifiers or keywords +- Optional `semantics_version` (positive integer) and `interpretation_limits` on the query, plus optional field keys on each `output_schema` entry: `units`, `metric_semantics`, `scope`, `denominator`, `sentinel`, and `interpretation_limits` +- `semantics_version` is the interpretation contract agents should cite. v1/v2 SQL variants of the same template share that contract. Templates that omit it remain valid; their `output_schema` still has `column` and `type` only + +Closed vocabularies: + +- `units`: `bytes`, `gib`, `percent`, `event_id`, `count`, `address`, `flag`, `text` +- `metric_semantics`: `instantaneous_occupancy`, `cumulative_allocation`, `peak`, `same_event_gap`, `share_of_included_rows`, `identifier`, `classification`, `ordering_marker` +- `scope`: `dynamic`, `static`, `preexisting`, `mixed`, `captured_range`, `same_event`. Use `mixed` when a column contains more than one of those per row (see `category` on `active_memory_callstack_at_event`) When passed explicitly to `ResultMapper`, recognized mapping types are `int`, `float`, `str`, `bool`, `hex`, and `datetime`; `datetime` is currently a diff --git a/docs/en/snapshot-analyzer-api.md b/docs/en/snapshot-analyzer-api.md index 5aaa25e..770f895 100644 --- a/docs/en/snapshot-analyzer-api.md +++ b/docs/en/snapshot-analyzer-api.md @@ -82,7 +82,14 @@ if info is not None: `list_templates()` returns dictionaries containing `name`, `description`, and `category`. `get_template_info()` returns full template metadata or `None` only -when the named template does not exist; registry failures are propagated. +when the named template does not exist; registry failures are propagated. The +payload includes `parameters`, `output_schema`, `semantics_version`, and +`interpretation_limits`. `semantics_version` is the field-interpretation +contract and is distinct from YAML `version` and the SnapshotDB schema / +callstack layout. Unannotated templates use `semantics_version: null` and +`column`/`type` only; annotated columns may also declare `units`, +`metric_semantics`, `scope`, `denominator`, `sentinel`, and per-field +`interpretation_limits`. The dict is JSON-serializable. ## Execute Queries @@ -107,7 +114,9 @@ The result contains: | `total` | Number of rows produced before display limiting | | `returned` | Number of rows included in `rows` | | `device_id` | Device selected for execution | -| `rows` | Query rows as dictionaries | +| `rows` | Query rows as dictionaries (raw SQLite values, without long field explanations) | +| `template` | Template that produced the rows | +| `semantics_version` | Interpretation contract to look up via `get_template_info()`, or `None` | Pass `device_id` to `execute_query()` to override the analyzer's device for one call. Otherwise selection uses the analyzer device, then the device from resolved diff --git a/docs/zh/mcp.md b/docs/zh/mcp.md index ea607b0..5326730 100644 --- a/docs/zh/mcp.md +++ b/docs/zh/mcp.md @@ -28,7 +28,7 @@ pt-snap-mcp | `get_focus` | 获取当前分析焦点(数据库路径、设备 ID、来源) | | `set_focus` | 设置焦点到指定数据库和可选设备。运行查询前使用。 | | `list_templates` | 列出可用的查询模板,可按类别筛选 | -| `get_template_info` | 获取模板详情,包括参数信息 | +| `get_template_info` | 获取模板详情,包括参数、输出 schema 和字段语义 | | `execute_query` | 对焦点数据库执行查询模板。最多返回 `max_rows` 行(默认 **100**;传 `0` 表示不限制)。见[查询结果与行数限制](#查询结果与行数限制)。 | | `get_database_metadata` | 查看焦点或指定数据库的导入来源 metadata | @@ -85,6 +85,8 @@ get_database_metadata() | `returned` | `rows` 中实际包含的行数。 | | `device_id` | 查询实际使用的设备(显式 `device_id`,否则为焦点设备,否则为数据库中的第一个设备)。 | | `rows` | 结果行,每行是原始 SQLite 值组成的字典。 | +| `template` | 产生这些行的模板名。 | +| `semantics_version` | 通过 `get_template_info` 查阅的字段解释契约;未声明时为 `null`。 | **MCP 的默认值是 `max_rows=100`,与 CLI 不同。** `pt-snap query` 在没有 `-n` 时 显示全部行;MCP 工具则限制输出,避免大结果集撑爆 agent 的上下文。把 diff --git a/docs/zh/querying.md b/docs/zh/querying.md index 6c85357..dd64dea 100644 --- a/docs/zh/querying.md +++ b/docs/zh/querying.md @@ -22,7 +22,7 @@ pt-snap query [DB_PATH] [--template-use ] [--params ] \ | `--device` | 设备 ID | | `--list` | 列出可用的查询模板 | | `--category` | 按分类过滤模板:`basic`、`statistical`、`business` | -| `--template-info` | 显示模板详情(参数和输出 schema) | +| `--template-info` | 显示模板详情(参数、输出 schema 和字段语义) | | `-n` | 最大显示行数;零或负数表示不限制 | ## 查询模板 @@ -60,7 +60,7 @@ pt-snap query [DB_PATH] [--template-use ] [--params ] \ | 模板 | 说明 | |------|------| -| `leak_detection` | 查找未匹配释放事件的分配 | +| `leak_detection` | 查找已采集分配且没有释放完成记录的候选(不是已确认泄漏) | | `active_memory_callstack_at_event` | 对某个事件时刻的活跃内存块按分配调用栈做聚合,并单独标识静态与 preexisting 内存 | ## 泄漏检测 @@ -70,7 +70,9 @@ pt-snap query --template-use leak_detection --params '{"min_size": 1024}' ``` `min_size` 表示候选泄漏的最小字节数,默认值为 `0`。目标设备应通过命令级 -`--device` 选项指定,而不是放进 `--params`。 +`--device` 选项指定,而不是放进 `--params`。`leak_detection` 返回的是捕获范围内 +仍存活的候选,不是已确认泄漏。用 `pt-snap query --template-info leak_detection` +读取字段单位与解释限制。 ## 参数校验 @@ -212,14 +214,25 @@ Found 150 results, showing 2: CLI、Python API 和 MCP 的查询结果包含原始 SQLite 值。模板的 `output_schema` 只是 metadata,查询执行时不会自动应用。需要十六进制地址字符串等转换值时, -应显式调用 `ResultMapper`。 +应显式调用 `ResultMapper`。结果行不重复字段说明;用 `--template-info` +(或 `get_template_info`)按产生这些行的模板查阅 `semantics_version` 与解释限制。 +Python API 和 MCP 的 `execute_query` 结果还包含 `template` 与 `semantics_version`, +便于把行与契约对应起来。 ## 模板架构 查询模板使用 YAML 格式定义,包含: -- `version`: 模板版本 +- `version`: YAML 文件格式版本,既不是字段语义契约,也不是 SnapshotDB schema 版本 - `queries`: 查询定义,包含描述、支持的设备、参数、SQL(Jinja2 模板语法)和输出 schema - 每个参数声明 `type`、`default`、`required`、`description`,以及可选的 `choices`(允许取值的封闭列表;会被渲染为 SQL 标识符或关键字的参数必须声明它) +- 查询可选声明 `semantics_version`(正整数)和 `interpretation_limits`;`output_schema` 各列还可声明 `units`、`metric_semantics`、`scope`、`denominator`、`sentinel`、`interpretation_limits` +- `semantics_version` 是 Agent 应引用的解释契约。同一模板的 v1/v2 SQL 变体共享该契约。未声明时模板仍有效,`output_schema` 只保留 `column` 与 `type` + +封闭词表: + +- `units`:`bytes`、`gib`、`percent`、`event_id`、`count`、`address`、`flag`、`text` +- `metric_semantics`:`instantaneous_occupancy`、`cumulative_allocation`、`peak`、`same_event_gap`、`share_of_included_rows`、`identifier`、`classification`、`ordering_marker` +- `scope`:`dynamic`、`static`、`preexisting`、`mixed`、`captured_range`、`same_event`。一列按行混合多种范围时用 `mixed`(见 `active_memory_callstack_at_event` 的 `category`) 显式传给 `ResultMapper` 时,可识别的映射类型包括 `int`、`float`、`str`、 `bool`、`hex` 和 `datetime`;当前 `datetime` 只是透传声明,不执行解析。 diff --git a/docs/zh/snapshot-analyzer-api.md b/docs/zh/snapshot-analyzer-api.md index b601f2d..08ced19 100644 --- a/docs/zh/snapshot-analyzer-api.md +++ b/docs/zh/snapshot-analyzer-api.md @@ -76,7 +76,12 @@ if info is not None: `list_templates()` 返回包含 `name`、`description` 和 `category` 的字典。 `get_template_info()` 返回完整模板 metadata;仅当指定模板不存在时返回 `None`,registry -内部错误会继续向调用方抛出。 +内部错误会继续向调用方抛出。返回值包含 `parameters`、`output_schema`、 +`semantics_version` 和 `interpretation_limits`。`semantics_version` 是字段解释契约, +有别于 YAML `version` 以及 SnapshotDB schema / callstack 布局。未标注的模板 +`semantics_version` 为 `null`,列上只有 `column`/`type`;已标注列还可包含 +`units`、`metric_semantics`、`scope`、`denominator`、`sentinel` 以及字段级 +`interpretation_limits`。该字典可直接 JSON 序列化。 ## 执行查询 @@ -101,7 +106,9 @@ for row in result["rows"]: | `total` | 限制显示行数前产生的结果总数 | | `returned` | `rows` 中实际返回的行数 | | `device_id` | 本次执行选择的设备 | -| `rows` | 字典形式的查询行 | +| `rows` | 字典形式的查询行(原始 SQLite 值,不含长说明) | +| `template` | 产生这些行的模板名 | +| `semantics_version` | 通过 `get_template_info()` 查阅的解释契约,未声明时为 `None` | 向 `execute_query()` 传入 `device_id` 可以仅覆盖本次调用的 analyzer 设备。否则依次使用 analyzer 设备;未设置显式 analyzer 数据库时,再使用已解析项目或全局 focus 的设备; diff --git a/skills/pt-snap-memory-leak/SKILL.md b/skills/pt-snap-memory-leak/SKILL.md index 6b439a2..31fe9ef 100644 --- a/skills/pt-snap-memory-leak/SKILL.md +++ b/skills/pt-snap-memory-leak/SKILL.md @@ -96,7 +96,7 @@ Run an initial ranked query, keeping the result bounded while retaining the repo pt-snap query '' --device --template-use leak_detection --params '{"min_size":}' -n 100 ``` -`leak_detection` includes only dynamic blocks with a recorded allocation and no recorded free completion. It intentionally excludes static blocks whose allocation predates tracing. +`leak_detection` includes only dynamic blocks with a recorded allocation and no recorded free completion. It intentionally excludes static blocks whose allocation predates tracing. Interpret its columns from `pt-snap query --template-info leak_detection`; do not treat candidates as confirmed leaks. Record candidate count, largest sizes, addresses, and allocation event IDs. Do not infer simultaneous live bytes by summing cumulative allocation activity from `callstack_analysis`. @@ -108,7 +108,7 @@ Use the final event ID from Step 1: pt-snap query '' --device --template-use active_memory_callstack_at_event --params '{"event_id":,"include_static":true,"min_size":0,"top_n":20}' ``` -Keep static memory separate from dynamic live memory. Rank dynamic groups by `size_bytes`, then compare block count, requested bytes, and each group's share of included active bytes. The `percent_of_active_blocks` column is a byte share (`size_bytes / total size_bytes`) despite its name; it is not the share of block count. A group containing many small blocks can be important even when no individual block appears near the top of `leak_detection`. +Keep static memory separate from dynamic live memory. Rank dynamic groups by `size_bytes`, then compare block count, requested bytes, and each group's share of included active bytes. Read `percent_of_active_blocks` units, denominator, and interpretation limits from `pt-snap query --template-info active_memory_callstack_at_event` rather than inferring them from the column name. A group containing many small blocks can be important even when no individual block appears near the top of `leak_detection`. ### 4. Compare occupancy at the active peak diff --git a/skills/pt-snap-memory-peak-breakdown/SKILL.md b/skills/pt-snap-memory-peak-breakdown/SKILL.md index a43ed61..a62c028 100644 --- a/skills/pt-snap-memory-peak-breakdown/SKILL.md +++ b/skills/pt-snap-memory-peak-breakdown/SKILL.md @@ -192,10 +192,7 @@ their event ID carries the range selection forward. - It does not assign reserved/cache bytes, allocator gaps, or inactive allocated bytes to callstacks. A large gap is evidence of counter separation at one event, not proof of fragmentation, caching policy, or an OOM cause. -- `percent_of_active_blocks` is a byte percentage despite its name. It is based - on `size_bytes`, not block count. -- Excluding static memory changes the percentage denominator. State the - inclusion choice whenever percentages are reported. +- Interpret `percent_of_active_blocks` using `--template-info active_memory_callstack_at_event` (units, denominator, and limits). Do not infer a block-count share from the column name. State the `include_static` choice whenever percentages are reported. ### Static, preexisting, and dynamic memory diff --git a/src/pt_snap_cli/api.py b/src/pt_snap_cli/api.py index 683b142..7490078 100644 --- a/src/pt_snap_cli/api.py +++ b/src/pt_snap_cli/api.py @@ -137,6 +137,8 @@ def get_template_info(self, name: str) -> dict[str, Any] | None: for param_name, param in info.parameters.items() }, "output_schema": info.output_schema, + "semantics_version": info.semantics_version, + "interpretation_limits": info.interpretation_limits, } def execute_query( @@ -161,6 +163,8 @@ def execute_query( "returned": result.returned, "device_id": result.device_id, "rows": result.rows, + "template": result.template, + "semantics_version": result.semantics_version, } def get_database_metadata(self, db_path: str | None = None) -> dict[str, Any]: diff --git a/src/pt_snap_cli/bundled_skills/pt-snap-memory-leak/SKILL.md b/src/pt_snap_cli/bundled_skills/pt-snap-memory-leak/SKILL.md index 6b439a2..31fe9ef 100644 --- a/src/pt_snap_cli/bundled_skills/pt-snap-memory-leak/SKILL.md +++ b/src/pt_snap_cli/bundled_skills/pt-snap-memory-leak/SKILL.md @@ -96,7 +96,7 @@ Run an initial ranked query, keeping the result bounded while retaining the repo pt-snap query '' --device --template-use leak_detection --params '{"min_size":}' -n 100 ``` -`leak_detection` includes only dynamic blocks with a recorded allocation and no recorded free completion. It intentionally excludes static blocks whose allocation predates tracing. +`leak_detection` includes only dynamic blocks with a recorded allocation and no recorded free completion. It intentionally excludes static blocks whose allocation predates tracing. Interpret its columns from `pt-snap query --template-info leak_detection`; do not treat candidates as confirmed leaks. Record candidate count, largest sizes, addresses, and allocation event IDs. Do not infer simultaneous live bytes by summing cumulative allocation activity from `callstack_analysis`. @@ -108,7 +108,7 @@ Use the final event ID from Step 1: pt-snap query '' --device --template-use active_memory_callstack_at_event --params '{"event_id":,"include_static":true,"min_size":0,"top_n":20}' ``` -Keep static memory separate from dynamic live memory. Rank dynamic groups by `size_bytes`, then compare block count, requested bytes, and each group's share of included active bytes. The `percent_of_active_blocks` column is a byte share (`size_bytes / total size_bytes`) despite its name; it is not the share of block count. A group containing many small blocks can be important even when no individual block appears near the top of `leak_detection`. +Keep static memory separate from dynamic live memory. Rank dynamic groups by `size_bytes`, then compare block count, requested bytes, and each group's share of included active bytes. Read `percent_of_active_blocks` units, denominator, and interpretation limits from `pt-snap query --template-info active_memory_callstack_at_event` rather than inferring them from the column name. A group containing many small blocks can be important even when no individual block appears near the top of `leak_detection`. ### 4. Compare occupancy at the active peak diff --git a/src/pt_snap_cli/bundled_skills/pt-snap-memory-peak-breakdown/SKILL.md b/src/pt_snap_cli/bundled_skills/pt-snap-memory-peak-breakdown/SKILL.md index a43ed61..a62c028 100644 --- a/src/pt_snap_cli/bundled_skills/pt-snap-memory-peak-breakdown/SKILL.md +++ b/src/pt_snap_cli/bundled_skills/pt-snap-memory-peak-breakdown/SKILL.md @@ -192,10 +192,7 @@ their event ID carries the range selection forward. - It does not assign reserved/cache bytes, allocator gaps, or inactive allocated bytes to callstacks. A large gap is evidence of counter separation at one event, not proof of fragmentation, caching policy, or an OOM cause. -- `percent_of_active_blocks` is a byte percentage despite its name. It is based - on `size_bytes`, not block count. -- Excluding static memory changes the percentage denominator. State the - inclusion choice whenever percentages are reported. +- Interpret `percent_of_active_blocks` using `--template-info active_memory_callstack_at_event` (units, denominator, and limits). Do not infer a block-count share from the column name. State the `include_static` choice whenever percentages are reported. ### Static, preexisting, and dynamic memory diff --git a/src/pt_snap_cli/cli.py b/src/pt_snap_cli/cli.py index 95a7f7c..31d2e4b 100644 --- a/src/pt_snap_cli/cli.py +++ b/src/pt_snap_cli/cli.py @@ -9,7 +9,7 @@ from collections.abc import Mapping from dataclasses import asdict from pathlib import Path -from typing import Annotated, Literal, NoReturn, cast +from typing import Annotated, Any, Literal, NoReturn, cast import typer @@ -89,6 +89,30 @@ def _query_service() -> QueryService: return QueryService(_focus_service()) +_OUTPUT_SCHEMA_DETAIL_KEYS = ( + "units", + "metric_semantics", + "scope", + "denominator", + "sentinel", + "interpretation_limits", +) + + +def _echo_output_schema_column(column: Mapping[str, Any]) -> None: + typer.echo(f" {column['column']}: {column['type']}") + for key in _OUTPUT_SCHEMA_DETAIL_KEYS: + if key not in column: + continue + value = column[key] + if key == "interpretation_limits": + typer.echo(" interpretation_limits:") + for item in value: + typer.echo(f" - {item}") + else: + typer.echo(f" {key}: {value}") + + def _skill_service() -> SkillService: return SkillService() @@ -371,7 +395,7 @@ def query_database( str | None, typer.Option( "--template-info", - help="Show detailed information about a template (including parameters and output schema)", + help="Show detailed information about a template (including parameters, output schema, and field semantics)", autocompletion=complete_template_names, ), ] = None, @@ -427,6 +451,10 @@ def query_database( typer.echo(f"Description: {info.description}") typer.echo(f"Category: {info.category}") typer.echo(f"Devices: {info.devices}") + typer.echo( + "Semantics Version: " + f"{info.semantics_version if info.semantics_version is not None else 'none'}" + ) typer.echo() typer.echo("Parameters:") if info.parameters: @@ -453,9 +481,14 @@ def query_database( typer.echo("Output Schema:") if info.output_schema: for col in info.output_schema: - typer.echo(f" {col['column']}: {col['type']}") + _echo_output_schema_column(col) else: typer.echo(" Dynamic (depends on query)") + if info.interpretation_limits: + typer.echo() + typer.echo("Interpretation Limits:") + for limit in info.interpretation_limits: + typer.echo(f" - {limit}") typer.echo() typer.echo("Example Usage:") example_params = {} diff --git a/src/pt_snap_cli/core/models.py b/src/pt_snap_cli/core/models.py index 9231bb8..f08c02a 100644 --- a/src/pt_snap_cli/core/models.py +++ b/src/pt_snap_cli/core/models.py @@ -89,7 +89,9 @@ class TemplateInfo: category: str | None devices: str | None parameters: dict[str, TemplateParameter] - output_schema: list[dict[str, str]] | None + output_schema: list[dict[str, Any]] | None + semantics_version: int | None = None + interpretation_limits: list[str] = field(default_factory=list) @dataclass(frozen=True) @@ -98,6 +100,8 @@ class QueryResult: returned: int device_id: int | None rows: list[dict[str, Any]] + template: str | None = None + semantics_version: int | None = None @dataclass(frozen=True) diff --git a/src/pt_snap_cli/core/query_service.py b/src/pt_snap_cli/core/query_service.py index 71a293d..19c1d2f 100644 --- a/src/pt_snap_cli/core/query_service.py +++ b/src/pt_snap_cli/core/query_service.py @@ -113,6 +113,12 @@ def get_template_info(self, name: str) -> TemplateInfo: for param_name, param_details in info["parameters"].items() }, output_schema=info["output_schema"], + semantics_version=info.get("semantics_version"), + interpretation_limits=( + [str(item) for item in info["interpretation_limits"]] + if isinstance(info.get("interpretation_limits"), list) + else [] + ), ) def execute_query( @@ -150,11 +156,14 @@ def execute_query( raise TemplateNotFoundError(f"Template '{template}' not found") from exc raise QueryExecutionError(str(exc)) from exc + template_obj = get_query(template) return QueryResult( total=total, returned=len(rows), device_id=target_device, rows=rows, + template=template, + semantics_version=template_obj.semantics_version if template_obj is not None else None, ) def _get_executor(self, ctx: Context) -> QueryExecutor: diff --git a/src/pt_snap_cli/query/AGENTS.md b/src/pt_snap_cli/query/AGENTS.md index 56d4c39..0d1ef1d 100644 --- a/src/pt_snap_cli/query/AGENTS.md +++ b/src/pt_snap_cli/query/AGENTS.md @@ -25,7 +25,8 @@ ## For AI Agents ### Working In This Directory -- When changing template behavior, check YAML templates, `config.py`, `registry.py`, `executor.py`, and CLI template metadata output together. +- When changing template behavior, check YAML templates, `config.py`, `registry.py`, `executor.py`, and CLI template metadata output together. Field semantics ride the same YAML → config → registry → core → API/MCP/CLI path as `choices`; do not add a second schema. +- `semantics_version` is independent of YAML `version` and SnapshotDB schema / callstack layout. v1/v2 SQL variants share one semantic contract. - Keep SQL value filters parameterized where using builder/condition APIs. - Device-specific template SQL should use injected table names such as `device_trace_table` and `device_block_table`. - Keep direct `QueryParameter` validation errors local; `QueryExecutor` must normalize them to its `TemplateRenderError` before the core boundary. diff --git a/src/pt_snap_cli/query/config.py b/src/pt_snap_cli/query/config.py index 2158f1c..e1edc6c 100644 --- a/src/pt_snap_cli/query/config.py +++ b/src/pt_snap_cli/query/config.py @@ -10,6 +10,42 @@ _CALLSTACK_VARIANTS = ("v1", "v2") +# Field/template interpretation contract, independent of YAML ``version`` and +# SnapshotDB schema / callstack layout. v1/v2 SQL variants share one contract. +_OUTPUT_COLUMN_REQUIRED = ("column", "type") +_OUTPUT_COLUMN_OPTIONAL = ( + "units", + "metric_semantics", + "scope", + "denominator", + "sentinel", + "interpretation_limits", +) +_OUTPUT_COLUMN_KEYS = frozenset(_OUTPUT_COLUMN_REQUIRED + _OUTPUT_COLUMN_OPTIONAL) +OUTPUT_SCHEMA_UNITS = frozenset( + {"bytes", "gib", "percent", "event_id", "count", "address", "flag", "text"} +) +OUTPUT_SCHEMA_METRIC_SEMANTICS = frozenset( + { + "instantaneous_occupancy", + "cumulative_allocation", + "peak", + "same_event_gap", + "share_of_included_rows", + "identifier", + "classification", + "ordering_marker", + } +) +OUTPUT_SCHEMA_SCOPES = frozenset( + {"dynamic", "static", "preexisting", "mixed", "captured_range", "same_event"} +) +_ENUM_FIELDS = { + "units": OUTPUT_SCHEMA_UNITS, + "metric_semantics": OUTPUT_SCHEMA_METRIC_SEMANTICS, + "scope": OUTPUT_SCHEMA_SCOPES, +} + @dataclass class QueryParameter: @@ -105,8 +141,13 @@ class QueryTemplate: parameters: dict[str, QueryParameter] = field(default_factory=dict) query: str = "" query_variants: dict[str, str] = field(default_factory=dict) - output_schema: list[dict[str, str]] = field(default_factory=list) + output_schema: list[dict[str, Any]] = field(default_factory=list) category: str = "basic" + # Interpretation contract for agents. Distinct from YAML ``version`` and + # SnapshotDB schema / callstack layout; omitted on templates that have not + # declared field semantics yet. + semantics_version: int | None = None + interpretation_limits: list[str] = field(default_factory=list) def sql_for_layout(self, layout: str | None) -> str | None: """Return SQL for a detected callstack layout. @@ -195,11 +236,109 @@ def from_dict(cls, data: dict[str, Any], default_category: str | None = None) -> parameters=parameters, query=query, query_variants=query_variants, - output_schema=data.get("output_schema", []), + output_schema=_parse_output_schema(template_name, data.get("output_schema")), category=data.get("category") or default_category or "basic", + semantics_version=_parse_semantics_version( + template_name, data.get("semantics_version") + ), + interpretation_limits=_parse_interpretation_limits( + f"template '{template_name}'", data.get("interpretation_limits") + ), ) +def _parse_semantics_version(template_name: str, raw: Any) -> int | None: + if raw is None: + return None + if isinstance(raw, bool) or not isinstance(raw, int) or raw < 1: + raise ValueError( + f"semantics_version for '{template_name}' must be a positive integer, got {raw!r}" + ) + return raw + + +def _parse_interpretation_limits(label: str, raw: Any) -> list[str]: + if raw is None: + return [] + if not isinstance(raw, list) or not raw: + raise ValueError(f"interpretation_limits for {label} must be a non-empty list of strings") + limits: list[str] = [] + for index, item in enumerate(raw): + if not isinstance(item, str) or not item.strip(): + raise ValueError( + f"interpretation_limits[{index}] for {label} must be a non-empty string" + ) + limits.append(item.strip()) + return limits + + +def _parse_output_schema(template_name: str, raw: Any) -> list[dict[str, Any]]: + if raw is None: + return [] + if not isinstance(raw, list): + raise ValueError(f"output_schema for '{template_name}' must be a list of column mappings") + + columns: list[dict[str, Any]] = [] + for index, item in enumerate(raw): + if not isinstance(item, dict): + raise ValueError( + f"output_schema[{index}] for '{template_name}' must be a mapping with column and type" + ) + unknown = set(item) - _OUTPUT_COLUMN_KEYS + if unknown: + raise ValueError( + f"output_schema[{index}] for '{template_name}' has unsupported keys: " + f"{', '.join(sorted(str(key) for key in unknown))}" + ) + column = item.get("column") + column_type = item.get("type") + if not isinstance(column, str) or not column.strip(): + raise ValueError( + f"output_schema[{index}] for '{template_name}' must declare a non-empty column name" + ) + if not isinstance(column_type, str) or not column_type.strip(): + raise ValueError( + f"output_schema[{index}] column '{column}' for '{template_name}' " + "must declare a non-empty type" + ) + + parsed: dict[str, Any] = {"column": column, "type": column_type} + for key in _OUTPUT_COLUMN_OPTIONAL: + if key not in item: + continue + value = item[key] + if key == "interpretation_limits": + parsed[key] = _parse_interpretation_limits( + f"'{template_name}' column '{column}'", value + ) + continue + if key == "sentinel": + if isinstance(value, bool) or not isinstance(value, int): + raise ValueError( + f"output_schema column '{column}' for '{template_name}' " + f"sentinel must be an integer, got {value!r}" + ) + parsed[key] = value + continue + if key == "denominator": + if not isinstance(value, str) or not value.strip(): + raise ValueError( + f"output_schema column '{column}' for '{template_name}' " + "denominator must be a non-empty string" + ) + parsed[key] = value.strip() + continue + allowed = _ENUM_FIELDS[key] + if not isinstance(value, str) or value not in allowed: + raise ValueError( + f"output_schema column '{column}' for '{template_name}' {key} " + f"must be one of: {', '.join(sorted(allowed))} (got {value!r})" + ) + parsed[key] = value + columns.append(parsed) + return columns + + def _parse_query_variants(template_name: str, raw: Any) -> dict[str, str]: if raw is None: return {} diff --git a/src/pt_snap_cli/query/mapper.py b/src/pt_snap_cli/query/mapper.py index d02c802..4dffaeb 100644 --- a/src/pt_snap_cli/query/mapper.py +++ b/src/pt_snap_cli/query/mapper.py @@ -45,7 +45,7 @@ def register_model_factory( def map( self, row: dict[str, Any], - schema: list[dict[str, str]] | None = None, + schema: list[dict[str, Any]] | None = None, ) -> dict[str, Any]: """Map a single row according to schema. @@ -79,7 +79,7 @@ def map( def map_all( self, rows: list[dict[str, Any]], - schema: list[dict[str, str]] | None = None, + schema: list[dict[str, Any]] | None = None, ) -> list[dict[str, Any]]: """Map all rows according to schema. @@ -136,7 +136,7 @@ def map_all_to_model( def map_result( row: dict[str, Any], - schema: list[dict[str, str]] | None = None, + schema: list[dict[str, Any]] | None = None, ) -> dict[str, Any]: """Map a result row using default mapper. @@ -152,7 +152,7 @@ def map_result( def map_results( rows: list[dict[str, Any]], - schema: list[dict[str, str]] | None = None, + schema: list[dict[str, Any]] | None = None, ) -> list[dict[str, Any]]: """Map all result rows using default mapper. diff --git a/src/pt_snap_cli/query/registry.py b/src/pt_snap_cli/query/registry.py index e1bd61d..4fcbdf3 100644 --- a/src/pt_snap_cli/query/registry.py +++ b/src/pt_snap_cli/query/registry.py @@ -209,6 +209,8 @@ def get_template_info(name: str) -> dict[str, Any] | None: for param_name, param in template.parameters.items() }, "output_schema": template.output_schema, + "semantics_version": template.semantics_version, + "interpretation_limits": template.interpretation_limits, "query": template.query, } diff --git a/src/pt_snap_cli/query/templates/AGENTS.md b/src/pt_snap_cli/query/templates/AGENTS.md index a9be153..949835a 100644 --- a/src/pt_snap_cli/query/templates/AGENTS.md +++ b/src/pt_snap_cli/query/templates/AGENTS.md @@ -23,6 +23,8 @@ ### Working In This Directory - Keep each YAML template's `queries` entry name aligned with the file/topic and documented template name. - Include accurate parameter defaults, required flags, descriptions, and output schema entries. +- Field semantics (`units`, `metric_semantics`, `scope`, `denominator`, `sentinel`, `interpretation_limits`) and template-level `semantics_version` / `interpretation_limits` are optional and validated by `QueryTemplate.from_dict`. Omit them on templates that do not yet declare an interpretation contract. v1/v2 SQL variants must share one `output_schema`. +- `semantics_version` is the field-interpretation contract, distinct from YAML `version` and SnapshotDB schema / callstack layout. - Any parameter rendered as a SQL identifier or keyword (`order_by`, `order_dir`, or similar) must declare `choices`; `order_by` choices must be columns present in `output_schema`. `tests/query/test_registry.py` enforces this for packaged templates. Empty `choices`, a non-list `choices`, or a default outside the list raise at `QueryParameter` construction; `_load_yaml_templates` warns and skips that YAML file, so the template is absent rather than listed. - Callers cannot pass undeclared parameters; `QueryTemplate.validate_params()` rejects unknown names, so declare every input the SQL reads. - Use Jinja variables provided by `QueryExecutor`, especially device-specific table names. diff --git a/src/pt_snap_cli/query/templates/business/active_memory_callstack_at_event.yaml b/src/pt_snap_cli/query/templates/business/active_memory_callstack_at_event.yaml index 723cba8..49ac800 100644 --- a/src/pt_snap_cli/query/templates/business/active_memory_callstack_at_event.yaml +++ b/src/pt_snap_cli/query/templates/business/active_memory_callstack_at_event.yaml @@ -4,6 +4,12 @@ queries: description: Aggregate active memory blocks at an event by allocation callstack, including static memory classification devices: - all + semantics_version: 1 + interpretation_limits: + - "Rows mix dynamic, static, and preexisting groups. Use the category column for per-row scope; do not label the whole result as dynamic." + - "percent_of_active_blocks is a 0-100 byte percentage of the returned rows after min_size, include_static, and top_n truncation of dynamic groups, not of all active memory and not of block counts." + - "Static and preexisting groups have no captured allocation callstack." + - "Event IDs are ordering markers, not elapsed time." parameters: event_id: type: int @@ -196,17 +202,48 @@ queries: output_schema: - column: callstack type: str + units: text + metric_semantics: identifier + scope: mixed + interpretation_limits: + - "Static and preexisting groups use synthetic labels rather than a captured allocation callstack. Dynamic rows may be '[missing callstack]' when the alloc event has no callstack." - column: category type: str + units: text + metric_semantics: classification + scope: mixed + interpretation_limits: + - "Per-row scope: dynamic_live_at_event, static, or preexisting_live_at_event." - column: block_count type: int + units: count + scope: mixed - column: size_bytes type: int + units: bytes + metric_semantics: instantaneous_occupancy + scope: mixed - column: size_gib type: float + units: gib + metric_semantics: instantaneous_occupancy + scope: mixed - column: requested_bytes type: int + units: bytes + metric_semantics: instantaneous_occupancy + scope: mixed - column: requested_gib type: float + units: gib + metric_semantics: instantaneous_occupancy + scope: mixed - column: percent_of_active_blocks type: float + units: percent + metric_semantics: share_of_included_rows + scope: mixed + denominator: "SUM(size_bytes) over the returned rows after min_size filtering, include_static grouping, and top_n truncation of dynamic callstack groups. Static and preexisting groups are always included when include_static is true. This is not all active memory in the snapshot." + interpretation_limits: + - "0-100 byte percentage despite the column name; not a share of block count." + - "Changing include_static, min_size, or top_n changes the denominator." diff --git a/src/pt_snap_cli/query/templates/business/leak_detection.yaml b/src/pt_snap_cli/query/templates/business/leak_detection.yaml index b7fae1d..ecd5a1a 100644 --- a/src/pt_snap_cli/query/templates/business/leak_detection.yaml +++ b/src/pt_snap_cli/query/templates/business/leak_detection.yaml @@ -1,7 +1,7 @@ version: "1.0" queries: leak_detection: - description: Detect memory leaks by finding allocations without free events + description: Find captured allocations with no recorded free-completion event (leak candidates) devices: - all - "0" @@ -17,6 +17,10 @@ queries: default: -1 required: false description: Maximum rows to return (-1 for unlimited). Mirrored from the caller-side ``max_rows`` for SQL pushdown. + semantics_version: 1 + interpretation_limits: + - "Rows are candidates still without a free-completion event in the captured range; end-of-trace survival is not a confirmed leak." + - "Event IDs and ID distances are ordering markers, not elapsed time." query: | SELECT id, address, size, allocEventId FROM {{ device_block_table }} @@ -27,9 +31,23 @@ queries: output_schema: - column: id type: int + metric_semantics: identifier - column: address type: hex + units: address + metric_semantics: identifier + interpretation_limits: + - "The same address can be reused by later allocations; address equality is not allocation identity." - column: size type: int + units: bytes + metric_semantics: instantaneous_occupancy + scope: dynamic - column: allocEventId type: int + units: event_id + metric_semantics: ordering_marker + sentinel: -1 + interpretation_limits: + - "Points to the captured allocation event. This template keeps only allocEventId >= 0, so the uncaptured sentinel -1 is excluded." + - "Event IDs are ordering markers, not timestamps." diff --git a/src/pt_snap_cli/query/templates/statistical/allocator_gap.yaml b/src/pt_snap_cli/query/templates/statistical/allocator_gap.yaml index 26cf20c..bb2b912 100644 --- a/src/pt_snap_cli/query/templates/statistical/allocator_gap.yaml +++ b/src/pt_snap_cli/query/templates/statistical/allocator_gap.yaml @@ -4,6 +4,11 @@ queries: description: Compare allocated, active, and reserved peak events and same-event gaps devices: - all + semantics_version: 1 + interpretation_limits: + - "Gaps are computed from counters at the same peak event. A reserved-active gap is not itself fragmentation." + - "Allocated, active, and reserved may peak at different events; use the same-event flags before comparing across metrics." + - "Event IDs are ordering markers, not elapsed time." parameters: start_id: type: int @@ -65,45 +70,113 @@ queries: output_schema: - column: peak_allocated_event_id type: int + units: event_id + metric_semantics: ordering_marker + scope: captured_range - column: peak_allocated type: int + units: bytes + metric_semantics: cumulative_allocation + scope: captured_range - column: active_at_allocated_peak type: int + units: bytes + metric_semantics: instantaneous_occupancy + scope: same_event - column: reserved_at_allocated_peak type: int + units: bytes + metric_semantics: instantaneous_occupancy + scope: same_event - column: reserved_active_gap_at_allocated_peak type: int + units: bytes + metric_semantics: same_event_gap + scope: same_event + interpretation_limits: + - "Same-event reserved minus active at the allocated peak. Not a direct fragmentation measurement." - column: reserved_allocated_gap_at_allocated_peak type: int + units: bytes + metric_semantics: same_event_gap + scope: same_event - column: peak_active_event_id type: int + units: event_id + metric_semantics: ordering_marker + scope: captured_range - column: peak_active type: int + units: bytes + metric_semantics: instantaneous_occupancy + scope: captured_range - column: allocated_at_active_peak type: int + units: bytes + metric_semantics: cumulative_allocation + scope: same_event - column: reserved_at_active_peak type: int + units: bytes + metric_semantics: instantaneous_occupancy + scope: same_event - column: reserved_active_gap_at_active_peak type: int + units: bytes + metric_semantics: same_event_gap + scope: same_event + interpretation_limits: + - "Same-event reserved minus active at the active peak. Not a direct fragmentation measurement." - column: reserved_allocated_gap_at_active_peak type: int + units: bytes + metric_semantics: same_event_gap + scope: same_event - column: peak_reserved_event_id type: int + units: event_id + metric_semantics: ordering_marker + scope: captured_range - column: peak_reserved type: int + units: bytes + metric_semantics: instantaneous_occupancy + scope: captured_range - column: allocated_at_reserved_peak type: int + units: bytes + metric_semantics: cumulative_allocation + scope: same_event - column: active_at_reserved_peak type: int + units: bytes + metric_semantics: instantaneous_occupancy + scope: same_event - column: reserved_active_gap_at_reserved_peak type: int + units: bytes + metric_semantics: same_event_gap + scope: same_event + interpretation_limits: + - "Same-event reserved minus active at the reserved peak. Not a direct fragmentation measurement." - column: reserved_allocated_gap_at_reserved_peak type: int + units: bytes + metric_semantics: same_event_gap + scope: same_event - column: all_peaks_same_event type: int + units: flag + metric_semantics: classification - column: allocated_active_same_event type: int + units: flag + metric_semantics: classification - column: active_reserved_same_event type: int + units: flag + metric_semantics: classification - column: allocated_reserved_same_event type: int + units: flag + metric_semantics: classification diff --git a/src/pt_snap_cli/query/templates/statistical/memory_peak.yaml b/src/pt_snap_cli/query/templates/statistical/memory_peak.yaml index 764095b..8d9aea0 100644 --- a/src/pt_snap_cli/query/templates/statistical/memory_peak.yaml +++ b/src/pt_snap_cli/query/templates/statistical/memory_peak.yaml @@ -4,6 +4,11 @@ queries: description: Get peak memory metrics from trace events with corresponding event IDs devices: - all + semantics_version: 1 + interpretation_limits: + - "Each peak is the maximum of that counter in the filtered event range; ties resolve to the earliest event ID." + - "Peaks of allocated, active, and reserved may occur at different events; do not subtract them as if they were simultaneous." + - "Event IDs are ordering markers, not elapsed time." parameters: start_id: type: int @@ -54,13 +59,37 @@ queries: output_schema: - column: peak_allocated type: int + units: bytes + metric_semantics: cumulative_allocation + scope: captured_range + interpretation_limits: + - "Maximum of the allocated counter in the filtered range, not a point-in-time occupancy." - column: peak_allocated_event_id type: int + units: event_id + metric_semantics: ordering_marker + scope: captured_range - column: peak_active type: int + units: bytes + metric_semantics: instantaneous_occupancy + scope: captured_range + interpretation_limits: + - "Maximum of the active counter in the filtered range. Do not subtract this from a peak recorded at a different event." - column: peak_active_event_id type: int + units: event_id + metric_semantics: ordering_marker + scope: captured_range - column: peak_reserved type: int + units: bytes + metric_semantics: instantaneous_occupancy + scope: captured_range + interpretation_limits: + - "Maximum of the reserved counter in the filtered range. A large reserved value is not itself fragmentation." - column: peak_reserved_event_id - type: int \ No newline at end of file + type: int + units: event_id + metric_semantics: ordering_marker + scope: captured_range \ No newline at end of file diff --git a/tests/core/test_query_service.py b/tests/core/test_query_service.py index 8d43260..4d0f506 100644 --- a/tests/core/test_query_service.py +++ b/tests/core/test_query_service.py @@ -67,6 +67,8 @@ def test_execute_query_uses_focused_device_zero(self, sample_db: Path) -> None: assert result.device_id == 0 assert result.total == 2 assert result.returned == 2 + assert result.template == "size_query" + assert result.semantics_version is None def test_execute_query_explicit_device_zero_wins(self, sample_db: Path) -> None: config = Config() diff --git a/tests/query/AGENTS.md b/tests/query/AGENTS.md index 2ad49e2..9d53e73 100644 --- a/tests/query/AGENTS.md +++ b/tests/query/AGENTS.md @@ -20,6 +20,7 @@ | `test_callstack_schema_compat.py` | Tests v1/v2 callstack layout detection and dual-schema template results. | | `test_query_max_rows_pushdown.py` | Executes packaged leak/callstack templates against SQLite and tests SQL limit pushdown and stable ordering. | | `test_registry.py` | Tests template registration, lookup, category listing, and registry reset behavior. | +| `test_template_semantics.py` | Tests packaged field-semantics metadata, JSON serializability, and unannotated-template compatibility. | ## Subdirectories | Directory | Purpose | diff --git a/tests/query/test_config.py b/tests/query/test_config.py index e6bf7a0..52f8c9c 100644 --- a/tests/query/test_config.py +++ b/tests/query/test_config.py @@ -321,3 +321,94 @@ def test_get_query_not_found(self): def test_load_yaml_file_not_found(self): with pytest.raises(FileNotFoundError): QueryConfig.load_yaml("/nonexistent/path.yaml") + + +class TestTemplateSemantics: + def test_from_dict_omits_undeclared_semantics(self): + template = QueryTemplate.from_dict( + { + "name": "legacy", + "query": "SELECT 1", + "output_schema": [{"column": "id", "type": "int"}], + } + ) + assert template.semantics_version is None + assert template.interpretation_limits == [] + assert template.output_schema == [{"column": "id", "type": "int"}] + + def test_from_dict_loads_field_and_template_semantics(self): + template = QueryTemplate.from_dict( + { + "name": "annotated", + "query": "SELECT 1", + "semantics_version": 1, + "interpretation_limits": ["Candidates are not confirmed leaks."], + "output_schema": [ + { + "column": "percent_of_active_blocks", + "type": "float", + "units": "percent", + "metric_semantics": "share_of_included_rows", + "scope": "mixed", + "denominator": "SUM(size_bytes) over returned rows", + "interpretation_limits": ["Byte percentage despite the column name."], + }, + { + "column": "allocEventId", + "type": "int", + "units": "event_id", + "metric_semantics": "ordering_marker", + "sentinel": -1, + }, + ], + } + ) + assert template.semantics_version == 1 + assert template.interpretation_limits == ["Candidates are not confirmed leaks."] + percent = template.output_schema[0] + assert percent["units"] == "percent" + assert percent["denominator"] == "SUM(size_bytes) over returned rows" + assert percent["interpretation_limits"] == ["Byte percentage despite the column name."] + assert template.output_schema[1]["sentinel"] == -1 + + def test_from_dict_rejects_unknown_output_schema_key(self): + with pytest.raises(ValueError, match="unsupported keys: mystery"): + QueryTemplate.from_dict( + { + "name": "bad", + "query": "SELECT 1", + "output_schema": [{"column": "id", "type": "int", "mystery": "x"}], + } + ) + + def test_from_dict_rejects_invalid_units(self): + with pytest.raises(ValueError, match="units must be one of"): + QueryTemplate.from_dict( + { + "name": "bad", + "query": "SELECT 1", + "output_schema": [{"column": "id", "type": "int", "units": "milliseconds"}], + } + ) + + def test_from_dict_rejects_non_int_sentinel(self): + with pytest.raises(ValueError, match="sentinel must be an integer"): + QueryTemplate.from_dict( + { + "name": "bad", + "query": "SELECT 1", + "output_schema": [ + {"column": "id", "type": "int", "sentinel": "-1"}, + ], + } + ) + + def test_from_dict_rejects_invalid_semantics_version(self): + with pytest.raises(ValueError, match="positive integer"): + QueryTemplate.from_dict({"name": "bad", "query": "SELECT 1", "semantics_version": 0}) + + def test_from_dict_rejects_empty_interpretation_limits(self): + with pytest.raises(ValueError, match="non-empty list of strings"): + QueryTemplate.from_dict( + {"name": "bad", "query": "SELECT 1", "interpretation_limits": []} + ) diff --git a/tests/query/test_peak_memory_templates.py b/tests/query/test_peak_memory_templates.py index 61101a5..6915680 100644 --- a/tests/query/test_peak_memory_templates.py +++ b/tests/query/test_peak_memory_templates.py @@ -390,3 +390,17 @@ def test_allocator_gap_reports_peak_events_and_same_event_gaps(peak_memory_db: P assert row["active_reserved_same_event"] == 0 assert row["reserved_active_gap_at_active_peak"] == 2560 assert row["reserved_active_gap_at_reserved_peak"] == 7168 + + +def test_callstack_percent_metadata_describes_truncated_denominator() -> None: + """The percent column metadata must match the SQL that top_n already covers.""" + template = get_query("active_memory_callstack_at_event") + assert template is not None + percent = next( + column + for column in template.output_schema + if column["column"] == "percent_of_active_blocks" + ) + assert percent["units"] == "percent" + assert "top_n truncation of dynamic" in percent["denominator"] + assert percent["scope"] == "mixed" diff --git a/tests/query/test_registry.py b/tests/query/test_registry.py index dc796b6..1849673 100644 --- a/tests/query/test_registry.py +++ b/tests/query/test_registry.py @@ -223,6 +223,7 @@ def test_leak_detection_template_exposes_only_min_size(self): assert info is not None assert "min_size" in info["parameters"] assert "device_id" not in info["parameters"] + assert info["semantics_version"] == 1 def test_block_template_schema_includes_every_selected_column(self): info = get_template_info("block") diff --git a/tests/query/test_template_semantics.py b/tests/query/test_template_semantics.py new file mode 100644 index 0000000..2b22927 --- /dev/null +++ b/tests/query/test_template_semantics.py @@ -0,0 +1,102 @@ +"""Packaged query template semantic metadata.""" + +from __future__ import annotations + +import json + +from pt_snap_cli.query.registry import ( + QueryRegistry, + _load_all_templates, + get_query, + get_template_info, +) + + +def setup_function() -> None: + QueryRegistry.reset() + _load_all_templates() + + +_ANNOTATED = ( + "leak_detection", + "memory_peak", + "allocator_gap", + "active_memory_callstack_at_event", +) + + +def _column(template_name: str, column: str) -> dict[str, object]: + template = get_query(template_name) + assert template is not None + match = next(item for item in template.output_schema if item["column"] == column) + return match + + +def test_legacy_templates_remain_loadable_without_semantics() -> None: + info = get_template_info("allocation") + assert info is not None + assert info["semantics_version"] is None + assert info["interpretation_limits"] == [] + assert info["output_schema"][0] == {"column": "id", "type": "int"} + + +def test_annotated_templates_share_a_json_serializable_contract() -> None: + for name in _ANNOTATED: + template = get_query(name) + assert template is not None + assert template.semantics_version == 1 + assert template.interpretation_limits + info = get_template_info(name) + assert info is not None + json.dumps(info) + if template.query_variants: + assert template.sql_for_layout("v1") != template.sql_for_layout("v2") + assert template.output_schema == get_query(name).output_schema + + +def test_leak_detection_metadata_marks_candidates_and_event_ids() -> None: + template = get_query("leak_detection") + assert template is not None + joined = " ".join(template.interpretation_limits) + assert "not a confirmed leak" in joined + alloc = _column("leak_detection", "allocEventId") + assert alloc["units"] == "event_id" + assert alloc["sentinel"] == -1 + assert alloc["metric_semantics"] == "ordering_marker" + address = _column("leak_detection", "address") + assert "not allocation identity" in " ".join(address["interpretation_limits"]) + + +def test_memory_peak_metadata_forbids_cross_event_subtraction() -> None: + template = get_query("memory_peak") + assert template is not None + joined = " ".join(template.interpretation_limits) + assert "do not subtract" in joined.lower() + assert _column("memory_peak", "peak_allocated")["metric_semantics"] == "cumulative_allocation" + assert _column("memory_peak", "peak_active")["metric_semantics"] == "instantaneous_occupancy" + assert _column("memory_peak", "peak_active_event_id")["units"] == "event_id" + + +def test_allocator_gap_metadata_is_same_event_not_fragmentation() -> None: + template = get_query("allocator_gap") + assert template is not None + joined = " ".join(template.interpretation_limits) + assert "not itself fragmentation" in joined + gap = _column("allocator_gap", "reserved_active_gap_at_active_peak") + assert gap["metric_semantics"] == "same_event_gap" + assert gap["units"] == "bytes" + + +def test_callstack_percent_metadata_matches_truncated_byte_denominator() -> None: + percent = _column("active_memory_callstack_at_event", "percent_of_active_blocks") + assert percent["units"] == "percent" + assert percent["metric_semantics"] == "share_of_included_rows" + assert percent["scope"] == "mixed" + denominator = percent["denominator"] + assert "top_n truncation of dynamic" in denominator + assert "not all active memory" in denominator + limits = " ".join(percent["interpretation_limits"]) + assert "not a share of block count" in limits + category = _column("active_memory_callstack_at_event", "category") + assert category["scope"] == "mixed" + assert "Per-row scope" in " ".join(category["interpretation_limits"]) diff --git a/tests/skills/test_memory_leak_contract.py b/tests/skills/test_memory_leak_contract.py index 218d586..827a902 100644 --- a/tests/skills/test_memory_leak_contract.py +++ b/tests/skills/test_memory_leak_contract.py @@ -130,4 +130,6 @@ def test_memory_leak_skill_interprets_percent_column_as_byte_share() -> None: skill = SKILL_PATH.read_text() assert "share of included active bytes" in skill - assert "byte share (`size_bytes / total size_bytes`) despite its name" in skill + assert "--template-info active_memory_callstack_at_event" in skill + assert "rather than inferring them from the column name" in skill + assert "byte share (`size_bytes / total size_bytes`) despite its name" not in skill diff --git a/tests/skills/test_memory_peak_breakdown_contract.py b/tests/skills/test_memory_peak_breakdown_contract.py index c940577..c3c0d2a 100644 --- a/tests/skills/test_memory_peak_breakdown_contract.py +++ b/tests/skills/test_memory_peak_breakdown_contract.py @@ -152,8 +152,12 @@ def test_attribution_caveats_prevent_reserved_and_static_overclaim() -> None: assert "Attribution always describes blocks active at the selected event" in skill assert "when the selected event is the allocated or reserved peak" in normalized assert "It does not assign reserved/cache bytes" in skill - assert "`percent_of_active_blocks` is a byte percentage despite its name" in skill - assert "Excluding static memory changes the percentage denominator" in skill + assert ( + "Interpret `percent_of_active_blocks` using `--template-info active_memory_callstack_at_event`" + in skill + ) + assert "Do not infer a block-count share from the column name" in skill + assert "`percent_of_active_blocks` is a byte percentage despite its name" not in skill assert ( "Keep `static`, `preexisting_live_at_event`, and `dynamic_live_at_event`\n groups separate" in skill diff --git a/tests/test_api.py b/tests/test_api.py index 6140196..4cefee6 100644 --- a/tests/test_api.py +++ b/tests/test_api.py @@ -1,5 +1,6 @@ """Tests for the high-level SnapshotAnalyzer API.""" +import json import sqlite3 import tempfile from pathlib import Path @@ -208,6 +209,22 @@ def test_get_template_info_exists(self) -> None: assert info is not None assert info["name"] == "leak_detection" assert "description" in info + assert info["semantics_version"] == 1 + assert info["interpretation_limits"] + json.dumps(info) + alloc = next( + column for column in info["output_schema"] if column["column"] == "allocEventId" + ) + assert alloc["units"] == "event_id" + assert alloc["sentinel"] == -1 + + def test_get_template_info_legacy_template_omits_semantics(self) -> None: + analyzer = SnapshotAnalyzer() + info = analyzer.get_template_info("allocation") + assert info is not None + assert info["semantics_version"] is None + assert info["interpretation_limits"] == [] + assert info["output_schema"][0] == {"column": "id", "type": "int"} def test_get_template_info_not_found(self) -> None: analyzer = SnapshotAnalyzer() @@ -242,6 +259,8 @@ def test_execute_query_with_focus(self, valid_db: Path) -> None: assert "returned" in result assert "device_id" in result assert "rows" in result + assert result["template"] == "leak_detection" + assert result["semantics_version"] == 1 assert isinstance(result["rows"], list) def test_execute_query_max_rows_zero(self, valid_db: Path) -> None: diff --git a/tests/test_cli.py b/tests/test_cli.py index 76f5251..0ae693f 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -561,6 +561,17 @@ def test_template_info_without_output_schema(self, sample_db: Path) -> None: assert result.exit_code == 0 assert "Output Schema:" in result.stdout assert "Dynamic" in result.stdout + assert "Semantics Version: none" in result.stdout + + def test_template_info_shows_packaged_semantics(self, sample_db: Path) -> None: + result = runner.invoke(app, ["query", str(sample_db), "--template-info", "leak_detection"]) + output = unstyle(result.stdout) + assert result.exit_code == 0 + assert "Semantics Version: 1" in output + assert "units: event_id" in output + assert "sentinel: -1" in output + assert "Interpretation Limits:" in output + assert "not a confirmed leak" in output def test_focus_database_success(self, sample_db: Path) -> None: """Test 'focus' command writes project focus by default.""" diff --git a/tests/test_contract_cli_mcp.py b/tests/test_contract_cli_mcp.py index bb524b4..d77c41f 100644 --- a/tests/test_contract_cli_mcp.py +++ b/tests/test_contract_cli_mcp.py @@ -157,9 +157,15 @@ def _normalize_cli_template_list(output: str) -> list[dict[str, str]]: def _normalize_cli_template_info(output: str) -> dict[str, object]: - info: dict[str, object] = {"parameters": {}, "output_schema": []} + info: dict[str, object] = { + "parameters": {}, + "output_schema": [], + "semantics_version": None, + "interpretation_limits": [], + } section: str | None = None current_param: str | None = None + current_column: dict[str, object] | None = None for raw_line in output.splitlines(): line = raw_line.rstrip() @@ -172,12 +178,21 @@ def _normalize_cli_template_info(output: str) -> dict[str, object]: info["category"] = stripped.removeprefix("Category: ") elif stripped.startswith("Devices: "): info["devices"] = stripped.removeprefix("Devices: ") + elif stripped.startswith("Semantics Version: "): + text = stripped.removeprefix("Semantics Version: ") + info["semantics_version"] = None if text == "none" else int(text) elif stripped == "Parameters:": section = "parameters" + current_column = None elif stripped == "Output Schema:": section = "output_schema" + current_column = None + elif stripped == "Interpretation Limits:": + section = "template_interpretation_limits" + current_column = None elif stripped == "Example Usage:": section = None + current_column = None elif section == "parameters" and line.startswith(" ") and not line.startswith(" "): name, metadata = stripped.split(": ", 1) param_type = metadata.split(" ", 1)[0] @@ -200,13 +215,32 @@ def _normalize_cli_template_info(output: str) -> dict[str, object]: current_param = name elif section == "parameters" and current_param and line.startswith(" "): info["parameters"][current_param]["description"] = stripped + elif section == "output_schema" and stripped == "Dynamic (depends on query)": + continue + elif section == "output_schema" and line.startswith(" - "): + assert current_column is not None + limits = current_column.setdefault("interpretation_limits", []) + assert isinstance(limits, list) + limits.append(stripped[2:]) elif ( - section == "output_schema" - and line.startswith(" ") - and stripped != "Dynamic (depends on query)" + section == "output_schema" and line.startswith(" ") and not line.startswith(" ") ): + assert current_column is not None + if stripped.endswith(":") and ": " not in stripped: + current_column[stripped[:-1]] = [] + else: + key, value = stripped.split(": ", 1) + current_column[key] = _coerce_cli_default(value) if key == "sentinel" else value + elif section == "output_schema" and line.startswith(" ") and not line.startswith(" "): column, column_type = stripped.split(": ", 1) - info["output_schema"].append({"column": column, "type": column_type}) + current_column = {"column": column, "type": column_type} + schema = info["output_schema"] + assert isinstance(schema, list) + schema.append(current_column) + elif section == "template_interpretation_limits" and stripped.startswith("- "): + limits = info["interpretation_limits"] + assert isinstance(limits, list) + limits.append(stripped[2:]) return info @@ -220,6 +254,18 @@ def _normalize_cli_query_result(output: str, device_id: int) -> dict[str, object return {"total": total, "returned": returned, "device_id": device_id, "rows": rows} +def _assert_query_execution_contract( + cli_query: dict[str, object], + mcp_query: dict[str, object], + template: str, + semantics_version: int | None, +) -> None: + shared = {key: mcp_query[key] for key in ("total", "returned", "device_id", "rows")} + assert cli_query == shared + assert mcp_query["template"] == template + assert mcp_query["semantics_version"] == semantics_version + + def _normalize_cli_missing_template(output: str) -> dict[str, str]: return {"error": output.strip().removeprefix("Error: ")} @@ -289,6 +335,9 @@ def test_template_info_contract_matches_cli_and_mcp_semantics( mcp_info = server.get_template_info("allocation") assert cli_info == mcp_info + json.dumps(mcp_info) + assert cli_info["semantics_version"] is None + assert cli_info["interpretation_limits"] == [] assert cli_info["parameters"]["order_by"]["choices"] == [ "id", "allocated", @@ -298,6 +347,30 @@ def test_template_info_contract_matches_cli_and_mcp_semantics( assert cli_info["parameters"]["order_dir"]["choices"] == ["ASC", "DESC"] +def test_template_semantics_contract_matches_cli_and_mcp( + contract_db: Path, mcp_server: ModuleType +) -> None: + """Issue #141: field units and interpretation limits pass through unchanged.""" + server = _set_mcp_focus(mcp_server, contract_db) + for name in ( + "leak_detection", + "memory_peak", + "allocator_gap", + "active_memory_callstack_at_event", + ): + cli_result = runner.invoke( + app, + ["query", str(contract_db), "--template-info", name], + ) + assert cli_result.exit_code == 0, cli_result.stdout + cli_info = _normalize_cli_template_info(cli_result.stdout) + mcp_info = server.get_template_info(name) + assert cli_info == mcp_info + json.dumps(mcp_info) + assert mcp_info["semantics_version"] == 1 + assert mcp_info["interpretation_limits"] + + def test_leak_detection_template_does_not_advertise_device_id( contract_db: Path, mcp_server: ModuleType ) -> None: @@ -352,7 +425,7 @@ def test_query_execution_contract_matches_cli_and_mcp_semantics( "leak_detection", params=params, device_id=device_id, max_rows=0 ) - assert cli_query == mcp_query + _assert_query_execution_contract(cli_query, mcp_query, "leak_detection", 1) def test_event_query_contract_reads_v1_inline_callstack( @@ -391,7 +464,7 @@ def test_event_query_contract_reads_v1_inline_callstack( cli_query = _normalize_cli_query_result(cli_result.stdout, device_id=1) mcp_query = server.execute_query("event", params={"id": 1}, device_id=1, max_rows=0) - assert cli_query == mcp_query + _assert_query_execution_contract(cli_query, mcp_query, "event", None) assert mcp_query["rows"][0]["callstack"] == "train.py:10" diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py index c15077a..90ccdd6 100644 --- a/tests/test_mcp_server.py +++ b/tests/test_mcp_server.py @@ -166,6 +166,9 @@ def test_get_template_info(self) -> None: info = server_mod.get_template_info("leak_detection") assert "name" in info assert "parameters" in info + assert info["semantics_version"] == 1 + assert info["interpretation_limits"] + json.dumps(info) def test_get_template_info_not_found(self) -> None: """Test get_template_info handles missing template.""" @@ -186,6 +189,8 @@ def test_execute_query_returns_dict(self, valid_db: Path) -> None: assert "returned" in result assert "device_id" in result assert "rows" in result + assert result["template"] == "leak_detection" + assert result["semantics_version"] == 1 def test_execute_query_default_max_rows_caps_rows_but_keeps_exact_total( self, valid_db: Path From bcb0dfc8da44bb7acb458fb9c2563b809f73156c Mon Sep 17 00:00:00 2001 From: codeasier Date: Sat, 19 Sep 2026 00:10:55 +0800 Subject: [PATCH 2/3] fix(query): drop unused semantics vocab and stale MCP references 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. --- docs/en/querying.md | 4 +-- docs/zh/querying.md | 4 +-- src/pt_snap_cli/cli.py | 13 ++-------- src/pt_snap_cli/query/AGENTS.md | 2 +- src/pt_snap_cli/query/config.py | 8 +++--- tests/query/test_config.py | 36 ++++++++++++++++++++++++++ tests/query/test_template_semantics.py | 14 ++++++++++ 7 files changed, 60 insertions(+), 21 deletions(-) diff --git a/docs/en/querying.md b/docs/en/querying.md index efc5e16..f534676 100644 --- a/docs/en/querying.md +++ b/docs/en/querying.md @@ -236,12 +236,12 @@ Query templates are defined in YAML format with: - `queries`: Query definitions with description, supported devices, parameters, SQL (Jinja2 templated), and output schema - Each parameter declares `type`, `default`, `required`, `description`, and optionally `choices`, a closed list of accepted values that is mandatory for parameters rendered as SQL identifiers or keywords - Optional `semantics_version` (positive integer) and `interpretation_limits` on the query, plus optional field keys on each `output_schema` entry: `units`, `metric_semantics`, `scope`, `denominator`, `sentinel`, and `interpretation_limits` -- `semantics_version` is the interpretation contract agents should cite. v1/v2 SQL variants of the same template share that contract. Templates that omit it remain valid; their `output_schema` still has `column` and `type` only +- `semantics_version` is the interpretation contract agents should cite. v1/v2 SQL variants of the same template share that contract. Templates that omit both remain valid; unannotated `output_schema` entries carry `column` and `type` only Closed vocabularies: - `units`: `bytes`, `gib`, `percent`, `event_id`, `count`, `address`, `flag`, `text` -- `metric_semantics`: `instantaneous_occupancy`, `cumulative_allocation`, `peak`, `same_event_gap`, `share_of_included_rows`, `identifier`, `classification`, `ordering_marker` +- `metric_semantics`: `instantaneous_occupancy`, `same_event_gap`, `share_of_included_rows`, `identifier`, `classification`, `ordering_marker` - `scope`: `dynamic`, `static`, `preexisting`, `mixed`, `captured_range`, `same_event`. Use `mixed` when a column contains more than one of those per row (see `category` on `active_memory_callstack_at_event`) When passed explicitly to `ResultMapper`, recognized mapping types are `int`, diff --git a/docs/zh/querying.md b/docs/zh/querying.md index a55ea69..41e5fe3 100644 --- a/docs/zh/querying.md +++ b/docs/zh/querying.md @@ -226,12 +226,12 @@ CLI 和 Python API 的查询结果包含原始 SQLite 值。模板的 `output_sc - `queries`: 查询定义,包含描述、支持的设备、参数、SQL(Jinja2 模板语法)和输出 schema - 每个参数声明 `type`、`default`、`required`、`description`,以及可选的 `choices`(允许取值的封闭列表;会被渲染为 SQL 标识符或关键字的参数必须声明它) - 查询可选声明 `semantics_version`(正整数)和 `interpretation_limits`;`output_schema` 各列还可声明 `units`、`metric_semantics`、`scope`、`denominator`、`sentinel`、`interpretation_limits` -- `semantics_version` 是 Agent 应引用的解释契约。同一模板的 v1/v2 SQL 变体共享该契约。未声明时模板仍有效,`output_schema` 只保留 `column` 与 `type` +- `semantics_version` 是 Agent 应引用的解释契约。同一模板的 v1/v2 SQL 变体共享该契约。未同时声明两者时模板仍有效;未注解的 `output_schema` 条目仅含 `column` 与 `type` 封闭词表: - `units`:`bytes`、`gib`、`percent`、`event_id`、`count`、`address`、`flag`、`text` -- `metric_semantics`:`instantaneous_occupancy`、`cumulative_allocation`、`peak`、`same_event_gap`、`share_of_included_rows`、`identifier`、`classification`、`ordering_marker` +- `metric_semantics`:`instantaneous_occupancy`、`same_event_gap`、`share_of_included_rows`、`identifier`、`classification`、`ordering_marker` - `scope`:`dynamic`、`static`、`preexisting`、`mixed`、`captured_range`、`same_event`。一列按行混合多种范围时用 `mixed`(见 `active_memory_callstack_at_event` 的 `category`) 显式传给 `ResultMapper` 时,可识别的映射类型包括 `int`、`float`、`str`、 diff --git a/src/pt_snap_cli/cli.py b/src/pt_snap_cli/cli.py index 31d2e4b..a6d8671 100644 --- a/src/pt_snap_cli/cli.py +++ b/src/pt_snap_cli/cli.py @@ -60,6 +60,7 @@ human_skill_summary, parse_host_option, ) +from pt_snap_cli.query.config import OUTPUT_COLUMN_OPTIONAL from pt_snap_cli.query.registry import discover_categories AGENT_HELP_EPILOG = ( @@ -89,19 +90,9 @@ def _query_service() -> QueryService: return QueryService(_focus_service()) -_OUTPUT_SCHEMA_DETAIL_KEYS = ( - "units", - "metric_semantics", - "scope", - "denominator", - "sentinel", - "interpretation_limits", -) - - def _echo_output_schema_column(column: Mapping[str, Any]) -> None: typer.echo(f" {column['column']}: {column['type']}") - for key in _OUTPUT_SCHEMA_DETAIL_KEYS: + for key in OUTPUT_COLUMN_OPTIONAL: if key not in column: continue value = column[key] diff --git a/src/pt_snap_cli/query/AGENTS.md b/src/pt_snap_cli/query/AGENTS.md index 0d1ef1d..5d24416 100644 --- a/src/pt_snap_cli/query/AGENTS.md +++ b/src/pt_snap_cli/query/AGENTS.md @@ -25,7 +25,7 @@ ## For AI Agents ### Working In This Directory -- When changing template behavior, check YAML templates, `config.py`, `registry.py`, `executor.py`, and CLI template metadata output together. Field semantics ride the same YAML → config → registry → core → API/MCP/CLI path as `choices`; do not add a second schema. +- When changing template behavior, check YAML templates, `config.py`, `registry.py`, `executor.py`, and CLI template metadata output together. Field semantics ride the same YAML → config → registry → core → API/CLI path as `choices`; do not add a second schema. - `semantics_version` is independent of YAML `version` and SnapshotDB schema / callstack layout. v1/v2 SQL variants share one semantic contract. - Keep SQL value filters parameterized where using builder/condition APIs. - Device-specific template SQL should use injected table names such as `device_trace_table` and `device_block_table`. diff --git a/src/pt_snap_cli/query/config.py b/src/pt_snap_cli/query/config.py index e1edc6c..6a343e5 100644 --- a/src/pt_snap_cli/query/config.py +++ b/src/pt_snap_cli/query/config.py @@ -13,7 +13,7 @@ # Field/template interpretation contract, independent of YAML ``version`` and # SnapshotDB schema / callstack layout. v1/v2 SQL variants share one contract. _OUTPUT_COLUMN_REQUIRED = ("column", "type") -_OUTPUT_COLUMN_OPTIONAL = ( +OUTPUT_COLUMN_OPTIONAL = ( "units", "metric_semantics", "scope", @@ -21,15 +21,13 @@ "sentinel", "interpretation_limits", ) -_OUTPUT_COLUMN_KEYS = frozenset(_OUTPUT_COLUMN_REQUIRED + _OUTPUT_COLUMN_OPTIONAL) +_OUTPUT_COLUMN_KEYS = frozenset(_OUTPUT_COLUMN_REQUIRED + OUTPUT_COLUMN_OPTIONAL) OUTPUT_SCHEMA_UNITS = frozenset( {"bytes", "gib", "percent", "event_id", "count", "address", "flag", "text"} ) OUTPUT_SCHEMA_METRIC_SEMANTICS = frozenset( { "instantaneous_occupancy", - "cumulative_allocation", - "peak", "same_event_gap", "share_of_included_rows", "identifier", @@ -303,7 +301,7 @@ def _parse_output_schema(template_name: str, raw: Any) -> list[dict[str, Any]]: ) parsed: dict[str, Any] = {"column": column, "type": column_type} - for key in _OUTPUT_COLUMN_OPTIONAL: + for key in OUTPUT_COLUMN_OPTIONAL: if key not in item: continue value = item[key] diff --git a/tests/query/test_config.py b/tests/query/test_config.py index 52f8c9c..b5707b0 100644 --- a/tests/query/test_config.py +++ b/tests/query/test_config.py @@ -336,6 +336,25 @@ def test_from_dict_omits_undeclared_semantics(self): assert template.interpretation_limits == [] assert template.output_schema == [{"column": "id", "type": "int"}] + def test_from_dict_loads_field_semantics_without_semantics_version(self): + template = QueryTemplate.from_dict( + { + "name": "units_only", + "query": "SELECT 1", + "output_schema": [ + { + "column": "size", + "type": "int", + "units": "bytes", + "metric_semantics": "instantaneous_occupancy", + } + ], + } + ) + assert template.semantics_version is None + assert template.output_schema[0]["units"] == "bytes" + assert template.output_schema[0]["metric_semantics"] == "instantaneous_occupancy" + def test_from_dict_loads_field_and_template_semantics(self): template = QueryTemplate.from_dict( { @@ -391,6 +410,23 @@ def test_from_dict_rejects_invalid_units(self): } ) + def test_from_dict_rejects_unused_metric_semantics(self): + for value in ("peak", "cumulative_allocation"): + with pytest.raises(ValueError, match="metric_semantics must be one of"): + QueryTemplate.from_dict( + { + "name": "bad", + "query": "SELECT 1", + "output_schema": [ + { + "column": "size", + "type": "int", + "metric_semantics": value, + } + ], + } + ) + def test_from_dict_rejects_non_int_sentinel(self): with pytest.raises(ValueError, match="sentinel must be an integer"): QueryTemplate.from_dict( diff --git a/tests/query/test_template_semantics.py b/tests/query/test_template_semantics.py index fe3226c..02a504b 100644 --- a/tests/query/test_template_semantics.py +++ b/tests/query/test_template_semantics.py @@ -4,11 +4,13 @@ import json +from pt_snap_cli.query.config import OUTPUT_SCHEMA_METRIC_SEMANTICS from pt_snap_cli.query.registry import ( QueryRegistry, _load_all_templates, get_query, get_template_info, + list_queries, ) @@ -32,6 +34,18 @@ def _column(template_name: str, column: str) -> dict[str, object]: return match +def test_packaged_metric_semantics_match_published_vocabulary() -> None: + used: set[str] = set() + for name in list_queries(): + template = get_query(name) + assert template is not None + for column in template.output_schema: + value = column.get("metric_semantics") + if value is not None: + used.add(value) + assert used == OUTPUT_SCHEMA_METRIC_SEMANTICS + + def test_legacy_templates_remain_loadable_without_semantics() -> None: info = get_template_info("allocation") assert info is not None From 7478255befae35252d8cde15d3b3c249f73f5a3c Mon Sep 17 00:00:00 2001 From: codeasier Date: Sat, 19 Sep 2026 00:43:57 +0800 Subject: [PATCH 3/3] fix(query): type validate_output schema as dict[str, Any] output_schema now includes integer sentinels and list interpretation limits, so the str-only annotation was stale. --- src/pt_snap_cli/query/executor.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pt_snap_cli/query/executor.py b/src/pt_snap_cli/query/executor.py index 22e48f7..f178b7a 100644 --- a/src/pt_snap_cli/query/executor.py +++ b/src/pt_snap_cli/query/executor.py @@ -411,7 +411,7 @@ def list_templates(self) -> list[str]: def validate_output( self, result: list[dict[str, Any]], - schema: list[dict[str, str]], + schema: list[dict[str, Any]], ) -> bool: """Validate query result against output schema.