From 6216b17b6cd449e471c967d60a116856c7876ca0 Mon Sep 17 00:00:00 2001 From: codeasier Date: Sat, 19 Sep 2026 16:28:54 +0800 Subject: [PATCH 1/2] feat: add capabilities and overview commands to cut agent probe calls Give agents one-shot catalog and read-only database orientation so leak diagnosis no longer needs per-template --template-info or sqlite3 CLI fallbacks. Fixes #142 --- AGENTS.md | 2 +- CHANGELOG.md | 5 +- README.md | 4 +- README_zh.md | 4 +- docs/en/AGENTS.md | 2 +- docs/en/database.md | 7 +- docs/en/querying.md | 6 +- docs/en/skills.md | 2 +- docs/en/snapshot-analyzer-api.md | 30 +++++- docs/zh/AGENTS.md | 2 +- docs/zh/database.md | 5 +- docs/zh/querying.md | 6 +- docs/zh/skills.md | 2 +- docs/zh/snapshot-analyzer-api.md | 29 ++++- skills/AGENTS.md | 2 +- skills/pt-snap-helper/SKILL.md | 21 ++-- skills/pt-snap-memory-leak/SKILL.md | 62 ++++------- src/pt_snap_cli/AGENTS.md | 4 +- src/pt_snap_cli/api.py | 25 +++++ .../bundled_skills/pt-snap-helper/SKILL.md | 21 ++-- .../pt-snap-memory-leak/SKILL.md | 62 ++++------- src/pt_snap_cli/cli.py | 79 ++++++++++++++ src/pt_snap_cli/context.py | 19 ++++ src/pt_snap_cli/core/AGENTS.md | 2 + src/pt_snap_cli/core/__init__.py | 10 ++ src/pt_snap_cli/core/capability_service.py | 37 +++++++ src/pt_snap_cli/core/models.py | 22 ++++ src/pt_snap_cli/core/overview_service.py | 88 +++++++++++++++ src/pt_snap_cli/core/query_service.py | 29 ++++- .../business/freed_block_lifetime.yaml | 43 ++++++++ .../templates/business/preexisting_live.yaml | 36 +++++++ tests/core/AGENTS.md | 2 + tests/core/test_capability_service.py | 33 ++++++ tests/core/test_overview_service.py | 79 ++++++++++++++ tests/query/AGENTS.md | 1 + tests/query/test_leak_fallback_templates.py | 100 ++++++++++++++++++ tests/query/test_peak_memory_templates.py | 4 + tests/query/test_registry.py | 15 ++- tests/query/test_template_semantics.py | 2 + .../cases/address-reuse.yaml | 2 +- .../cases/allocator-cache.yaml | 2 +- .../cases/pending-free.yaml | 2 +- .../suites/pt-snap-memory-leak/suite.yaml | 6 +- tests/skills/test_grader.py | 2 +- tests/skills/test_helper_contract.py | 6 ++ tests/skills/test_memory_leak_contract.py | 32 +++--- tests/test_api.py | 22 ++++ tests/test_cli.py | 26 +++++ tests/test_cli_json.py | 27 +++++ tests/test_context.py | 8 ++ tests/test_contract_cli_api.py | 24 +++++ 51 files changed, 929 insertions(+), 134 deletions(-) create mode 100644 src/pt_snap_cli/core/capability_service.py create mode 100644 src/pt_snap_cli/core/overview_service.py create mode 100644 src/pt_snap_cli/query/templates/business/freed_block_lifetime.yaml create mode 100644 src/pt_snap_cli/query/templates/business/preexisting_live.yaml create mode 100644 tests/core/test_capability_service.py create mode 100644 tests/core/test_overview_service.py create mode 100644 tests/query/test_leak_fallback_templates.py diff --git a/AGENTS.md b/AGENTS.md index b164f8d..5f3ca65 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,7 +51,7 @@ when they exist. | Surface | Entry point | Responsibility | | --- | --- | --- | -| CLI | `src/pt_snap_cli/cli.py` via `pt_snap_cli.cli:_safe_call` | Typer commands for focus, import, split, metadata, query, reports, config, and skill install/list | +| CLI | `src/pt_snap_cli/cli.py` via `pt_snap_cli.cli:_safe_call` | Typer commands for focus, import, split, metadata, capabilities, overview, query, reports, config, and skill install/list | | Python API | `src/pt_snap_cli/api.py` (`SnapshotAnalyzer`) | Programmatic focus, query, and metadata facade | | Product services | `src/pt_snap_cli/core/` | Shared focus, import, split, query, report, metadata, and error semantics | | Database access | `src/pt_snap_cli/context.py` | Read-only SQLite validation, connection management, and device discovery | diff --git a/CHANGELOG.md b/CHANGELOG.md index 915fba1..66a0bc0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,9 @@ ### 新增 +- 新增 `pt-snap capabilities`:一次输出 CLI 版本、全部查询模板/参数契约(含字段语义)和技能清单。`--json` 使用 #138 成功信封,替代逐个 `--template-info` 探测。 +- 新增 `pt-snap overview`:只读输出设备列表、各设备首/末 event id,以及导入 metadata 状态。`--json` 使用同一信封;分析路径不写数据库、不持久化 focus。 +- 新增 `preexisting_live` 与 `freed_block_lifetime` 查询模板,泄漏技能不再依赖 `sqlite3` CLI 回退。诊断前置探测从 7 次(`metadata` + 六个 `--template-info`)降为 2 次(`capabilities` + `overview`)。helper 引导「先概览、再诊断」。 - `focus`、`import`、`split`、`query`、`config` 支持 `--json`。成功结果带 `schema_version` / `ok` 信封,以及 `db_path`、`focus_source`、`device_id`、`template`、`effective_params` 等上下文。`query --list` / `--template-info` / 执行共用该选项;`--template-info --json` 透出 #147 字段语义。 - JSON 模式失败时 stdout 为空,stderr 为带稳定错误码的结构化对象(如 `TEMPLATE_NOT_FOUND`、`INVALID_PARAMETER`、`DATABASE_NOT_FOUND`、`DEVICE_NOT_FOUND`),退出码非零。`pt-snap` 控制台入口返回 Typer/Click 的退出码(不再丢弃非 standalone 返回值),在检测到 `--json` 时也会把 Click 用法/解析错误写成 `INVALID_PARAMETER` 信封(退出码 2),并把 Ctrl-C / EOF 写成 `ERROR` / `Aborted!`。解析失败时的 `--json` 判定是 argv 词法扫描(best-effort):忽略 `--` 之后的词,`--opt=value` 与数字词不吞后续参数。`query --json` 的 `effective_params.limit` 是尾部 SQL `LIMIT`(模板 `limit` 与 `-n` 的合并,或追加的 `-n`);CTE 内的 `top_n` 仍是独立参数。 - `split --json` 只控制 stdout 清单,与 `--format json` 的分片文件格式相互独立。`focus --session --json` 返回验证结果与 `PT_SNAP_DB_PATH` 赋值信息,不暗示已修改父 shell。 @@ -12,7 +15,7 @@ ### 兼容性提示 - 文本模式保持原样:人类可读输出不变,`_error()` 与查询/报告说明行仍写 stdout。缺失模板的 `query --template-info` 已在 0.4.0 以退出码 1 失败。数据库无设备时,文本模式查询仍退出 0;JSON 模式改为 `DEVICE_NOT_FOUND` 且退出码非零。 -- 已有 `metadata --json`、`report peak-memory --json` 与 `skill list/install/upgrade/uninstall --json` 成功字段保持兼容,不包进新信封。它们在 `--json` 失败时改走 stderr 错误信封。 +- 已有 `metadata --json`、`report peak-memory --json` 与 `skill list/install/upgrade/uninstall --json` 成功字段保持兼容,不包进新信封。它们在 `--json` 失败时改走 stderr 错误信封。新的 `capabilities --json` 与 `overview --json` 使用 #138 成功/失败信封。 - 查询默认 `total` 不再在触达 `-n` 时自动变成匹配集合 `COUNT`。依赖该旧语义的调用方必须显式传 `--exact-total` / `exact_total=True`。 ## [0.4.0] - Unreleased diff --git a/README.md b/README.md index 026d87a..86ad394 100644 --- a/README.md +++ b/README.md @@ -60,12 +60,14 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough. | `pt-snap import ` | Import a PyTorch memory snapshot pickle into a SnapshotDB | | `pt-snap split ` | Create replayable per-device snapshot slices | | `pt-snap metadata [database.db]` | Inspect SnapshotDB import provenance and compatibility metadata | +| `pt-snap capabilities` | List CLI version, query template contracts, and bundled skills | +| `pt-snap overview [database.db]` | Read-only device list, per-device event-id bounds, and import-metadata status | | `pt-snap query` | Run memory analysis queries | | `pt-snap report` | Generate higher-level memory analysis reports | | `pt-snap config` | Manage global configuration | | `pt-snap skill` | List and install bundled agent skills | -`pt-snap --help` includes an agent hint: prefer `--json` on the command that supports it, start with the `pt-snap-helper` skill, and check availability with `pt-snap skill list --json`. `focus`, `import`, `split`, `query`, `config`, `metadata`, `report peak-memory`, and `skill list/install/upgrade/uninstall` accept `--json`. +`pt-snap --help` includes an agent hint: prefer `--json` on the command that supports it, start with the `pt-snap-helper` skill, use `pt-snap capabilities --json` and `pt-snap overview --json` before diagnosing, and check availability with `pt-snap skill list --json`. `focus`, `import`, `split`, `query`, `config`, `capabilities`, `overview`, `metadata`, `report peak-memory`, and `skill list/install/upgrade/uninstall` accept `--json`. ## Agent Skills diff --git a/README_zh.md b/README_zh.md index 72e24f1..6492873 100644 --- a/README_zh.md +++ b/README_zh.md @@ -55,12 +55,14 @@ pt-snap split snapshot.pkl --slices 4 --output snapshot-slices | `pt-snap import ` | 将 PyTorch 原始内存快照导入 SnapshotDB | | `pt-snap split ` | 创建可回放的逐设备快照切片 | | `pt-snap metadata [database.db]` | 查看 SnapshotDB 的导入来源与兼容性 metadata | +| `pt-snap capabilities` | 列出 CLI 版本、查询模板契约和随包 skill | +| `pt-snap overview [database.db]` | 只读输出设备列表、各设备 event id 边界和导入 metadata 状态 | | `pt-snap query` | 运行内存分析查询 | | `pt-snap report` | 生成高层内存分析报告 | | `pt-snap config` | 管理全局配置 | | `pt-snap skill` | 列出并安装随包 agent skill | -`pt-snap --help` 含 Agent 提示:在支持该选项的命令上优先使用 `--json`,从 `pt-snap-helper` skill 开始,并用 `pt-snap skill list --json` 检查是否已安装。`focus`、`import`、`split`、`query`、`config`、`metadata`、`report peak-memory` 和 `skill list/install/upgrade/uninstall` 均接受 `--json`。 +`pt-snap --help` 含 Agent 提示:在支持该选项的命令上优先使用 `--json`,从 `pt-snap-helper` skill 开始,诊断前先用 `pt-snap capabilities --json` 和 `pt-snap overview --json`,并用 `pt-snap skill list --json` 检查是否已安装。`focus`、`import`、`split`、`query`、`config`、`capabilities`、`overview`、`metadata`、`report peak-memory` 和 `skill list/install/upgrade/uninstall` 均接受 `--json`。 ## Agent Skills diff --git a/docs/en/AGENTS.md b/docs/en/AGENTS.md index ebea246..67e6d54 100644 --- a/docs/en/AGENTS.md +++ b/docs/en/AGENTS.md @@ -15,7 +15,7 @@ | `splitting.md` | Snapshot slicing strategies, output formats, replay validation, and publication guarantees. | | `skills.md` | Bundled agent-skill listing, helper entry, install destinations, and status meanings. | | `database.md` | Snapshot SQLite table/schema reference. | -| `snapshot-analyzer-api.md` | High-level Python API for focus, template discovery, queries, and import metadata. | +| `snapshot-analyzer-api.md` | High-level Python API for focus, template discovery, capabilities, overview, queries, and import metadata. | | `result-mapper-api.md` | Result mapping API documentation. | ## Subdirectories diff --git a/docs/en/database.md b/docs/en/database.md index ef339f8..14c32cc 100644 --- a/docs/en/database.md +++ b/docs/en/database.md @@ -41,6 +41,10 @@ existing target only when the full source SHA-256, import format version, and de Package version changes alone do not invalidate the cache. ```bash +# Inspect devices, trace bounds, and import-metadata status +pt-snap overview snapshot.pkl.db +pt-snap overview snapshot.pkl.db --json + # Inspect provenance and compatibility metadata pt-snap metadata snapshot.pkl.db pt-snap metadata snapshot.pkl.db --json @@ -77,7 +81,8 @@ pt-snap query --template-use memory_peak pt-snap query --template-use block --params '{"min_size": 1048576}' ``` -Use `pt-snap query --list` and `pt-snap query --template-info ` to inspect +Use `pt-snap capabilities --json` for the full template catalog, or +`pt-snap query --list` and `pt-snap query --template-info ` to inspect the supported query surface. `event`, `callstack_analysis`, and `active_memory_callstack_at_event` work on both the current deduplicated callstack schema and older inline-text databases; see diff --git a/docs/en/querying.md b/docs/en/querying.md index 5f11166..be4c3a3 100644 --- a/docs/en/querying.md +++ b/docs/en/querying.md @@ -30,7 +30,7 @@ pt-snap query [DB_PATH] [--template-use ] [--params ] \ ## Query Templates -Templates are organized into three categories. Use `pt-snap query --list` to see them all, or filter with `--category`. +Templates are organized into three categories. Use `pt-snap capabilities --json` for the full catalog (CLI version, every template contract, and bundled skills), or `pt-snap query --list` to see names and descriptions. Filter with `--category`. ### Basic Queries @@ -65,6 +65,8 @@ Domain-specific analysis. |----------|-------------| | `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 | +| `preexisting_live` | Count preexisting-live blocks at an event (`allocEventId=-1` still live, including `freeEventId IS NULL`) | +| `freed_block_lifetime` | Bucket successfully freed blocks by `freeEventId - allocEventId` distance (not elapsed time) | ## Leak Detection @@ -206,6 +208,8 @@ and prints either a human-readable summary or JSON. | Execute | `db_path`, `focus_source`, `device_id`, `template`, `effective_params`, `semantics_version`, `total`, `returned`, `has_more`, `truncated`, `total_is_exact`, `timeout_s`, `rows` | | `--list` | `category`, `templates` (`name`, `description`, `category`) | | `--template-info` | Template metadata matching `get_template_info()`, plus `template` | +| `capabilities` | `cli_version`, full `templates` contracts, and `skills` | +| `overview` | `db_path`, `focus_source`, `devices` (`device_id`, `first_event_id`, `last_event_id`), `import_metadata` | `-n` still caps `rows` and `returned`. By default `total` equals `returned` (this page's row count) and `total_is_exact` is true only when the page is diff --git a/docs/en/skills.md b/docs/en/skills.md index 64452f2..bffe8c0 100644 --- a/docs/en/skills.md +++ b/docs/en/skills.md @@ -84,7 +84,7 @@ After an install, upgrade, or uninstall that changes skill files, restart the ag | Skill | Use when | |-------|----------| -| `pt-snap-helper` | Choosing the next skill from the user goal and input type | +| `pt-snap-helper` | Choosing the next skill from the user goal and input type; for an existing SnapshotDB, start with `capabilities` then `overview` before diagnosis | | `pt-snap-setup` | Installing or verifying `pt-snap-cli` in the active Python environment | | `pt-snap-ascend-npu-collect` | Collecting an Ascend NPU memory snapshot pickle | | `pt-snap-memory-leak` | Diagnosing live allocations and leak candidates in a SnapshotDB | diff --git a/docs/en/snapshot-analyzer-api.md b/docs/en/snapshot-analyzer-api.md index 9243440..8cda4fd 100644 --- a/docs/en/snapshot-analyzer-api.md +++ b/docs/en/snapshot-analyzer-api.md @@ -3,8 +3,9 @@ [中文](../zh/snapshot-analyzer-api.md) | English `SnapshotAnalyzer` is the high-level Python facade for focus inspection, -template discovery, query execution, and SnapshotDB import metadata. Import it -from `pt_snap_cli.api`; it is not re-exported from the package root. +template discovery, capability listing, database overview, query execution, and +SnapshotDB import metadata. Import it from `pt_snap_cli.api`; it is not +re-exported from the package root. ## Create an Analyzer @@ -68,6 +69,19 @@ explicit `db_path`, a validated device-only analyzer override is reported by See [Focus Management](focus-management.md) for the complete resolution and persistence model. +## List Capabilities + +```python +catalog = analyzer.list_capabilities() +print(catalog["cli_version"]) +print([item["name"] for item in catalog["templates"]]) +print([item["name"] for item in catalog["skills"]]) +``` + +`list_capabilities()` returns the same catalog as `pt-snap capabilities --json` +without the CLI envelope: `cli_version`, full template contracts (matching +`get_template_info()`), and bundled skill listings. + ## Discover Templates ```python @@ -139,6 +153,18 @@ Rows contain raw SQLite values. Template `output_schema` metadata is not applied automatically; use the optional [ResultMapper API](result-mapper-api.md) when converted values or model mapping are required. +## Inspect Database Overview + +```python +overview = analyzer.get_database_overview() +print(overview["devices"]) +print(overview["import_metadata"]["status"]) +``` + +`get_database_overview()` is the read-only orientation used by +`pt-snap overview`: device list, per-device first/last event id, and import +metadata status. It does not persist focus or write the database. + ## Inspect Import Metadata ```python diff --git a/docs/zh/AGENTS.md b/docs/zh/AGENTS.md index 7652dda..76a94a6 100644 --- a/docs/zh/AGENTS.md +++ b/docs/zh/AGENTS.md @@ -15,7 +15,7 @@ | `splitting.md` | Chinese guide to snapshot slicing, formats, replay validation, and publication. | | `skills.md` | Chinese guide to bundled agent-skill listing, helper entry, and installation. | | `database.md` | Chinese snapshot SQLite schema reference. | -| `snapshot-analyzer-api.md` | Chinese guide to the high-level focus, query, and metadata Python API. | +| `snapshot-analyzer-api.md` | Chinese guide to the high-level focus, query, capabilities, overview, and metadata Python API. | | `result-mapper-api.md` | Chinese result mapping API guide. | ## Subdirectories diff --git a/docs/zh/database.md b/docs/zh/database.md index 1d06f05..94fdec2 100644 --- a/docs/zh/database.md +++ b/docs/zh/database.md @@ -40,6 +40,8 @@ pt-snap query --list 才会复用已有 DB;仅升级 `pt-snap-cli` 包版本不会让缓存失效。 ```bash +pt-snap overview snapshot.pkl.db +pt-snap overview snapshot.pkl.db --json pt-snap metadata snapshot.pkl.db pt-snap metadata snapshot.pkl.db --json pt-snap import snapshot.pkl --force @@ -69,7 +71,8 @@ pt-snap query --template-use memory_peak pt-snap query --template-use block --params '{"min_size": 1048576}' ``` -使用 `pt-snap query --list` 和 `pt-snap query --template-info ` 查看受支持的 +使用 `pt-snap capabilities --json` 查看完整模板清单,或用 +`pt-snap query --list` 和 `pt-snap query --template-info ` 查看受支持的 查询入口。`event`、`callstack_analysis` 和 `active_memory_callstack_at_event` 同时支持当前去重调用栈结构和旧版内联文本库;见 [调用栈布局兼容](database.md#调用栈布局兼容)。完整流程见[运行查询](querying.md)。 diff --git a/docs/zh/querying.md b/docs/zh/querying.md index ab51c78..fdbd909 100644 --- a/docs/zh/querying.md +++ b/docs/zh/querying.md @@ -30,7 +30,7 @@ pt-snap query [DB_PATH] [--template-use ] [--params ] \ ## 查询模板 -模板分为三个分类。使用 `pt-snap query --list` 查看所有模板,或用 `--category` 过滤。 +模板分为三个分类。用 `pt-snap capabilities --json` 一次查看完整清单(CLI 版本、全部模板契约和随包 skill),或用 `pt-snap query --list` 查看名称与描述。用 `--category` 过滤。 ### Basic Queries @@ -65,6 +65,8 @@ pt-snap query [DB_PATH] [--template-use ] [--params ] \ |------|------| | `leak_detection` | 查找已采集分配且没有释放完成记录的候选(不是已确认泄漏) | | `active_memory_callstack_at_event` | 对某个事件时刻的活跃内存块按分配调用栈做聚合,并单独标识静态与 preexisting 内存 | +| `preexisting_live` | 统计某个事件时刻仍存活的 preexisting 块(`allocEventId=-1`,包含 `freeEventId IS NULL`) | +| `freed_block_lifetime` | 按 `freeEventId - allocEventId` 距离分桶统计已成功释放的块(不是经过时间) | ## 泄漏检测 @@ -198,6 +200,8 @@ pt-snap report peak-memory /path/to/snapshot.db --json | 执行 | `db_path`、`focus_source`、`device_id`、`template`、`effective_params`、`semantics_version`、`total`、`returned`、`has_more`、`truncated`、`total_is_exact`、`timeout_s`、`rows` | | `--list` | `category`、`templates`(`name`、`description`、`category`) | | `--template-info` | 与 `get_template_info()` 对齐的模板元数据,另加 `template` | +| `capabilities` | `cli_version`、完整 `templates` 契约、`skills` | +| `overview` | `db_path`、`focus_source`、`devices`(`device_id`、`first_event_id`、`last_event_id`)、`import_metadata` | `-n` 仍然限制 `rows` 与 `returned`。默认 `total` 等于 `returned`(本页行数); 仅当本页就是完整匹配集合(`has_more` 为 false 且 `offset` 为 0)时 diff --git a/docs/zh/skills.md b/docs/zh/skills.md index 1a85960..7def3ff 100644 --- a/docs/zh/skills.md +++ b/docs/zh/skills.md @@ -84,7 +84,7 @@ pt-snap skill uninstall --project --target cursor | Skill | 适用场景 | |-------|----------| -| `pt-snap-helper` | 根据用户目标和输入类型选择下一步 skill | +| `pt-snap-helper` | 根据用户目标和输入类型选择下一步 skill;已有 SnapshotDB 时先 `capabilities` 再 `overview`,然后才诊断 | | `pt-snap-setup` | 在当前 Python 环境安装或验证 `pt-snap-cli` | | `pt-snap-ascend-npu-collect` | 采集昇腾 NPU 内存快照 pickle | | `pt-snap-memory-leak` | 在 SnapshotDB 中诊断仍存活分配和泄漏候选 | diff --git a/docs/zh/snapshot-analyzer-api.md b/docs/zh/snapshot-analyzer-api.md index c6425ac..3fa6291 100644 --- a/docs/zh/snapshot-analyzer-api.md +++ b/docs/zh/snapshot-analyzer-api.md @@ -2,8 +2,9 @@ [English](../en/snapshot-analyzer-api.md) | 中文 -`SnapshotAnalyzer` 是用于查看 focus、发现模板、执行查询和检查 SnapshotDB 导入 -metadata 的高层 Python 门面。应从 `pt_snap_cli.api` 导入;包根目录不会重新导出它。 +`SnapshotAnalyzer` 是用于查看 focus、发现模板、列出能力清单、查看数据库概览、 +执行查询和检查 SnapshotDB 导入 metadata 的高层 Python 门面。应从 +`pt_snap_cli.api` 导入;包根目录不会重新导出它。 ## 创建 Analyzer @@ -62,6 +63,19 @@ focus 中的设备。没有显式 `db_path` 时,已验证的 analyzer 设备 完整解析和持久化模型见 [Focus 管理](focus-management.md)。 +## 列出能力清单 + +```python +catalog = analyzer.list_capabilities() +print(catalog["cli_version"]) +print([item["name"] for item in catalog["templates"]]) +print([item["name"] for item in catalog["skills"]]) +``` + +`list_capabilities()` 返回与 `pt-snap capabilities --json` 相同的清单(不含 CLI +信封):`cli_version`、完整模板契约(与 `get_template_info()` 一致)以及随包 +skill 列表。 + ## 发现模板 ```python @@ -128,6 +142,17 @@ CTE 上限。 查询行包含原始 SQLite 值,不会自动应用模板的 `output_schema` metadata。需要转换后的值 或模型映射时,使用可选的 [ResultMapper API](result-mapper-api.md)。 +## 检查数据库概览 + +```python +overview = analyzer.get_database_overview() +print(overview["devices"]) +print(overview["import_metadata"]["status"]) +``` + +`get_database_overview()` 是 `pt-snap overview` 使用的只读概览:设备列表、各设备 +首/末 event id,以及导入 metadata 状态。它不会持久化 focus,也不会写入数据库。 + ## 检查导入 Metadata ```python diff --git a/skills/AGENTS.md b/skills/AGENTS.md index 165b03e..aa5386f 100644 --- a/skills/AGENTS.md +++ b/skills/AGENTS.md @@ -13,7 +13,7 @@ surfaces against existing SnapshotDB data without writes. ## Scope | Path | Responsibility | | --- | --- | -| `pt-snap-helper/SKILL.md` | Routes by user goal and input type to the five skills; checks `pt-snap skill list --json`; does not install, import, or persist focus. | +| `pt-snap-helper/SKILL.md` | Routes by user goal and input type to the five skills; checks `pt-snap skill list --json`; points SnapshotDB work at `capabilities` then `overview` before diagnosis; does not install, import, or persist focus. | | `pt-snap-setup/SKILL.md` | Detect the active interpreter, verify CLI ownership, request install approval, and re-verify the same environment. | | `pt-snap-ascend-npu-collect/SKILL.md` | Collect Ascend NPU pickles via native APIs, framework config, or OOM env; inventory artifacts without import or diagnosis. | | `pt-snap-memory-leak/SKILL.md` | Diagnose end-of-trace live allocations, peak survival, callstack attribution, and release evidence without persisting analysis state. | diff --git a/skills/pt-snap-helper/SKILL.md b/skills/pt-snap-helper/SKILL.md index d3cd9be..a99d624 100644 --- a/skills/pt-snap-helper/SKILL.md +++ b/skills/pt-snap-helper/SKILL.md @@ -64,6 +64,8 @@ on `pt-snap`; add the option to the specific command: - `pt-snap skill install --json` - `pt-snap skill upgrade --json` - `pt-snap skill uninstall --json` +- `pt-snap capabilities --json` +- `pt-snap overview '' --json` - `pt-snap metadata '' --json` - `pt-snap report peak-memory '' --device --json` - `pt-snap focus --json` @@ -92,7 +94,10 @@ value; `--opt=value` and numeric tokens do not consume the next argument). Text mode still writes `Error:` lines to stdout. This skill itself does not run analysis queries. The diagnostic skills own -those commands. +those commands. For an existing SnapshotDB, point the next skill at +`pt-snap capabilities --json` and `pt-snap overview '' --json` +before diagnosis so it does not need per-template `--template-info` or a +separate metadata probe. ## Routing matrix @@ -124,13 +129,17 @@ A SnapshotDB is a pt-snap SQLite database (typically `.db`) with a `dictionary` table. When the user already has one: 1. Confirm the goal is leak, peak, or fragmentation. -2. Hand off to the matching diagnostic skill. Pass the database path and - device if the user supplied them. -3. Do not run `pt-snap focus ` to persist a new focus from this +2. Tell the next skill to start with `pt-snap capabilities --json` and + `pt-snap overview '' --json` (overview first, then diagnose). + Pass the database path and device if the user supplied them. +3. Hand off to the matching diagnostic skill. Do not run leak, peak, or + fragmentation query templates from this helper. +4. Do not run `pt-snap focus ` to persist a new focus from this skill. Diagnostic skills may read the current focus with no arguments. -This helper may mention that `pt-snap metadata '' --json` exists. -Running that check belongs to the diagnostic skill. +This helper may mention that `pt-snap overview '' --json` and +`pt-snap capabilities --json` exist. Running those orientation commands +belongs to the diagnostic skill. Do not import pickle or persist focus. ### Only pickle diff --git a/skills/pt-snap-memory-leak/SKILL.md b/skills/pt-snap-memory-leak/SKILL.md index 3a7ce31..065c1be 100644 --- a/skills/pt-snap-memory-leak/SKILL.md +++ b/skills/pt-snap-memory-leak/SKILL.md @@ -56,21 +56,22 @@ Do not run `pt-snap focus ` or otherwise persist focus from this This skill accepts SnapshotDB files only. Do not run `pt-snap import` or deserialize a pickle snapshot. If the user has only a pickle file, stop and explain that importing requires a separate, explicit trusted-input decision because pickle loading is not a sandbox. -### 3. Verify the database and required templates +### 3. Verify capabilities and the database in two calls Run: ```bash -pt-snap metadata '' --json -pt-snap query --template-info memory_peak -pt-snap query --template-info allocator_gap -pt-snap query --template-info event -pt-snap query --template-info block -pt-snap query --template-info leak_detection -pt-snap query --template-info active_memory_callstack_at_event +pt-snap capabilities --json +pt-snap overview '' --json ``` -If database validation or a required template fails, stop and report the exact failure. Do not silently substitute raw SQL for a missing core template. +`capabilities --json` is the catalog: CLI version, every template contract (parameters, `output_schema`, field semantics), and the skill list. Do not probe templates one-by-one with `--template-info`. + +`overview --json` is the read-only database orientation: device list, per-device first/last event id, and import-metadata status. Do not persist focus. + +Prerequisite probe budget: previously 7 calls (`metadata` plus six `--template-info` probes). Now 2 calls (`capabilities` + `overview`). Record that reduction when evaluating this skill. + +Confirm these templates exist in the capabilities catalog before diagnosis: `memory_peak`, `allocator_gap`, `event`, `block`, `leak_detection`, `active_memory_callstack_at_event`, `preexisting_live`, `freed_block_lifetime`. If the catalog or overview fails, stop and report the exact failure. Do not silently substitute raw SQL for a missing core template. ## Diagnostic Workflow @@ -100,7 +101,7 @@ when a matching-row count is required. `--timeout` is independent of `-n`. pt-snap query '' --device --template-use leak_detection --params '{"min_size":}' -n 100 --json ``` -`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. +`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 the `leak_detection` entry in `pt-snap capabilities --json`; 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`. @@ -116,7 +117,7 @@ This template has no `offset`, and `-n` cannot raise the CTE `top_n` cap. If `has_more` or `truncated` is true, increase `top_n` instead of concluding from the first ranked page. -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`. +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 the `active_memory_callstack_at_event` entry in `pt-snap capabilities --json` 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 @@ -134,21 +135,13 @@ Before claiming that the same blocks persisted across the peak: The template separates blocks without a captured allocation event into their own groups instead of attributing them to callstacks: `[static] allocEventId=-1, freeEventId=-1`, and `[preexisting live] allocEventId=-1` for blocks allocated before tracing that were still live at the analyzed event because their recorded free event came later or does not exist. Pre-tracing blocks whose free event precedes the analyzed event are correctly absent because they were no longer live. Report each group separately instead of absorbing it into a callstack group. -For an exact cross-check of the `[preexisting live]` bucket — for example against a database imported before this grouping existed — do not scan with the packaged `block` filters: they compare `freeEventId` numerically and cannot express the `freeEventId IS NULL` case that the template counts as preexisting-live, so any filtered scan risks an incomplete bucket. Instead, validate that `` is a non-negative decimal integer matching `^[0-9]+$`, then run one read-only aggregate through `sqlite3 -readonly`: +For an exact cross-check of the `[preexisting live]` bucket — for example against a database imported before this grouping existed — do not scan with the packaged `block` filters: they compare `freeEventId` numerically and cannot express the `freeEventId IS NULL` case that `active_memory_callstack_at_event` counts as preexisting-live, so any filtered scan risks an incomplete bucket. Use the packaged `preexisting_live` template instead: ```bash -sqlite3 -readonly '' " -SELECT COUNT(*) AS block_count, COALESCE(SUM(size), 0) AS size_bytes -FROM block_ -WHERE allocEventId = -1 - AND ( - freeEventId IS NULL - OR freeEventId > - OR (freeEventId < 0 AND freeEventId <> -1) - );" +pt-snap query '' --device --template-use preexisting_live --params '{"event_id":}' ``` -The predicate mirrors the template's `[preexisting live]` condition exactly: pre-tracing allocations whose free event is missing (`NULL`), comes later than the analyzed event, or is negative other than the static sentinel `-1`. The aggregate returns a single row, so no row limit applies and nothing is silently undercounted; report the count and bytes next to the static group. +The template uses the same predicate as the `[preexisting live]` group: pre-tracing allocations whose free event is missing (`NULL`), comes later than the analyzed event, or is negative other than the static sentinel `-1`. The aggregate returns a single row, so no row limit applies and nothing is silently undercounted; report the count and bytes next to the static group. Occupancy that stays high across both events strengthens retention evidence but does not by itself prove a leak. @@ -171,28 +164,13 @@ Do not use `block.state` as evidence for dynamic blocks. Its documented lifecycl ### 6. Optionally establish a freed-block lifetime baseline -The packaged templates do not aggregate `freeEventId - allocEventId` into lifetime buckets. Only when this baseline is needed, and only when the `sqlite3` CLI is available, use a read-only fallback after validating that `` is a non-negative decimal integer: +When a lifetime baseline is needed, use the packaged `freed_block_lifetime` template: ```bash -sqlite3 -readonly '' " -SELECT CASE - WHEN freeEventId - allocEventId < 1000 THEN '<1k' - WHEN freeEventId - allocEventId < 5000 THEN '1k-5k' - WHEN freeEventId - allocEventId < 20000 THEN '5k-20k' - WHEN freeEventId - allocEventId < 100000 THEN '20k-100k' - ELSE '>=100k' - END AS lifetime_events, - COUNT(*) AS block_count, - SUM(size) AS size_bytes -FROM block_ -WHERE allocEventId >= 0 AND freeEventId >= allocEventId -GROUP BY lifetime_events -ORDER BY MIN(freeEventId - allocEventId);" +pt-snap query '' --device --template-use freed_block_lifetime ``` -This baseline describes successfully freed blocks. It does not classify end-of-trace candidates and must not be generalized to real elapsed time. - -If `sqlite3` is unavailable or read-only mode cannot be verified, skip this optional step and list the lifetime distribution as unknown. Do not use a writable connection. +This baseline describes successfully freed blocks, bucketed by `freeEventId - allocEventId` distance (`<1k`, `1k-5k`, `5k-20k`, `20k-100k`, `>=100k`). It does not classify end-of-trace candidates and must not be generalized to real elapsed time. Read those limits from the `freed_block_lifetime` entry in `pt-snap capabilities --json`. ### 7. Classify findings conservatively @@ -226,7 +204,7 @@ Useful validation experiments include repeated snapshots at equivalent workload - Keep SnapshotDB access read-only. Never run `create`, `insert`, `update`, `delete`, `drop`, `alter`, `replace`, `attach`, `detach`, `reindex`, or `vacuum` SQL. - Do not persist focus, configuration, reports, exports, scratch databases, or readiness files. - Do not import or deserialize pickle snapshots. -- Prefer packaged `pt-snap` templates. Use raw SQLite only for the two documented read-only aggregates that templates do not expose: the freed-block lifetime baseline (Step 6) and the exact `[preexisting live]` total (Step 4). +- Prefer packaged `pt-snap` templates. Do not use the `sqlite3` CLI or hand-assembled SQL. The exact `[preexisting live]` total is `preexisting_live` (Step 4) and the freed-block lifetime baseline is `freed_block_lifetime` (Step 6). - Do not call every allocation without a free event a leak. - Separate cumulative allocation volume from memory simultaneously live at an event. - Keep static memory separate from dynamic candidates. @@ -245,7 +223,7 @@ Useful validation experiments include repeated snapshots at equivalent workload - End-of-trace dynamic candidates and static memory were reported separately. - Active-peak and final-event callstack attribution used the same device. - Peak-versus-final comparisons were reported as occupancy, and persistence claims relied on identity-matched blocks. -- Preexisting-live memory was reported separately from static and dynamic groups, with exact totals taken only from the documented read-only aggregates. +- Preexisting-live memory was reported separately from static and dynamic groups, with exact totals taken from `preexisting_live`. - Address-event listings stayed bounded with paging or event-ID windows, and `has_more` was honored. - Database paths were single-quoted or passed through argument arrays without shell re-parsing. - Representative lifecycle events were checked for address reuse and ambiguous pairing. diff --git a/src/pt_snap_cli/AGENTS.md b/src/pt_snap_cli/AGENTS.md index 95174ad..d489ae5 100644 --- a/src/pt_snap_cli/AGENTS.md +++ b/src/pt_snap_cli/AGENTS.md @@ -11,7 +11,7 @@ |------|-------------| | `__init__.py` | Package exports and version wiring. | | `api.py` | High-level `SnapshotAnalyzer` API for library callers. | -| `cli.py` | Typer CLI entrypoint for focus, import, split, metadata, query, report, config, and skill commands. | +| `cli.py` | Typer CLI entrypoint for focus, import, split, metadata, capabilities, overview, query, report, config, and skill commands. | | `completion.py` | Shell completion helpers for templates, categories, and device IDs. | | `config.py` | Atomic focus persistence and resolution across explicit paths, environment, project focus, and legacy global config. | | `context.py` | Read-only SQLite context with schema validation and device discovery. | @@ -20,7 +20,7 @@ ## Subdirectories | Directory | Purpose | |-----------|---------| -| `core/` | Shared focus, import, split, metadata, query, and report services (see `core/AGENTS.md`). | +| `core/` | Shared focus, import, split, metadata, capability, overview, query, and report services (see `core/AGENTS.md`). | | `models/` | Domain models for snapshot blocks, events, and enums (see `models/AGENTS.md`). | | `query/` | Query builders, config loading, execution, mapping, registry, and templates (see `query/AGENTS.md`). | | `snapshot/` | Snapshot representation, replay, database adaptors, and slicing for explicitly trusted inputs (see `snapshot/AGENTS.md`). | diff --git a/src/pt_snap_cli/api.py b/src/pt_snap_cli/api.py index eaf6706..2fa2e32 100644 --- a/src/pt_snap_cli/api.py +++ b/src/pt_snap_cli/api.py @@ -8,11 +8,13 @@ from pt_snap_cli.config import Config from pt_snap_cli.core import ( + CapabilityService, DatabaseMissingError, DatabaseSchemaError, FocusNotConfiguredError, FocusService, ImportMetadataService, + OverviewService, QueryService, TemplateNotFoundError, ) @@ -53,6 +55,14 @@ def __init__( self._context_cache = context_cache if context_cache is not None else ContextCache() self._query_service = QueryService(self._focus_service, context_cache=self._context_cache) self._metadata_service = ImportMetadataService() + self._capability_service = CapabilityService( + query_service=self._query_service, + ) + self._overview_service = OverviewService( + self._focus_service, + metadata_service=self._metadata_service, + context_cache=self._context_cache, + ) @property def context_cache(self) -> ContextCache: @@ -176,6 +186,21 @@ def execute_query( "timeout_s": result.timeout_s, } + def list_capabilities(self) -> dict[str, Any]: + return self._capability_service.catalog_to_dict(self._capability_service.catalog()) + + def get_database_overview(self, db_path: str | None = None) -> dict[str, Any]: + resolved_path = db_path if db_path is not None else self._db_path + try: + overview = self._overview_service.inspect(resolved_path) + except FocusNotConfiguredError as exc: + raise RuntimeError("No database configured. Call set_focus() first.") from exc + except DatabaseMissingError as exc: + raise FileNotFoundError(str(exc)) from exc + except DatabaseSchemaError as exc: + raise ValueError(str(exc)) from exc + return self._overview_service.overview_to_dict(overview) + def get_database_metadata(self, db_path: str | None = None) -> dict[str, Any]: resolved = self._focus_service.resolve_focus( explicit_db_path=db_path if db_path is not None else self._db_path, diff --git a/src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md b/src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md index d3cd9be..a99d624 100644 --- a/src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md +++ b/src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md @@ -64,6 +64,8 @@ on `pt-snap`; add the option to the specific command: - `pt-snap skill install --json` - `pt-snap skill upgrade --json` - `pt-snap skill uninstall --json` +- `pt-snap capabilities --json` +- `pt-snap overview '' --json` - `pt-snap metadata '' --json` - `pt-snap report peak-memory '' --device --json` - `pt-snap focus --json` @@ -92,7 +94,10 @@ value; `--opt=value` and numeric tokens do not consume the next argument). Text mode still writes `Error:` lines to stdout. This skill itself does not run analysis queries. The diagnostic skills own -those commands. +those commands. For an existing SnapshotDB, point the next skill at +`pt-snap capabilities --json` and `pt-snap overview '' --json` +before diagnosis so it does not need per-template `--template-info` or a +separate metadata probe. ## Routing matrix @@ -124,13 +129,17 @@ A SnapshotDB is a pt-snap SQLite database (typically `.db`) with a `dictionary` table. When the user already has one: 1. Confirm the goal is leak, peak, or fragmentation. -2. Hand off to the matching diagnostic skill. Pass the database path and - device if the user supplied them. -3. Do not run `pt-snap focus ` to persist a new focus from this +2. Tell the next skill to start with `pt-snap capabilities --json` and + `pt-snap overview '' --json` (overview first, then diagnose). + Pass the database path and device if the user supplied them. +3. Hand off to the matching diagnostic skill. Do not run leak, peak, or + fragmentation query templates from this helper. +4. Do not run `pt-snap focus ` to persist a new focus from this skill. Diagnostic skills may read the current focus with no arguments. -This helper may mention that `pt-snap metadata '' --json` exists. -Running that check belongs to the diagnostic skill. +This helper may mention that `pt-snap overview '' --json` and +`pt-snap capabilities --json` exist. Running those orientation commands +belongs to the diagnostic skill. Do not import pickle or persist focus. ### Only pickle 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 3a7ce31..065c1be 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 @@ -56,21 +56,22 @@ Do not run `pt-snap focus ` or otherwise persist focus from this This skill accepts SnapshotDB files only. Do not run `pt-snap import` or deserialize a pickle snapshot. If the user has only a pickle file, stop and explain that importing requires a separate, explicit trusted-input decision because pickle loading is not a sandbox. -### 3. Verify the database and required templates +### 3. Verify capabilities and the database in two calls Run: ```bash -pt-snap metadata '' --json -pt-snap query --template-info memory_peak -pt-snap query --template-info allocator_gap -pt-snap query --template-info event -pt-snap query --template-info block -pt-snap query --template-info leak_detection -pt-snap query --template-info active_memory_callstack_at_event +pt-snap capabilities --json +pt-snap overview '' --json ``` -If database validation or a required template fails, stop and report the exact failure. Do not silently substitute raw SQL for a missing core template. +`capabilities --json` is the catalog: CLI version, every template contract (parameters, `output_schema`, field semantics), and the skill list. Do not probe templates one-by-one with `--template-info`. + +`overview --json` is the read-only database orientation: device list, per-device first/last event id, and import-metadata status. Do not persist focus. + +Prerequisite probe budget: previously 7 calls (`metadata` plus six `--template-info` probes). Now 2 calls (`capabilities` + `overview`). Record that reduction when evaluating this skill. + +Confirm these templates exist in the capabilities catalog before diagnosis: `memory_peak`, `allocator_gap`, `event`, `block`, `leak_detection`, `active_memory_callstack_at_event`, `preexisting_live`, `freed_block_lifetime`. If the catalog or overview fails, stop and report the exact failure. Do not silently substitute raw SQL for a missing core template. ## Diagnostic Workflow @@ -100,7 +101,7 @@ when a matching-row count is required. `--timeout` is independent of `-n`. pt-snap query '' --device --template-use leak_detection --params '{"min_size":}' -n 100 --json ``` -`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. +`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 the `leak_detection` entry in `pt-snap capabilities --json`; 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`. @@ -116,7 +117,7 @@ This template has no `offset`, and `-n` cannot raise the CTE `top_n` cap. If `has_more` or `truncated` is true, increase `top_n` instead of concluding from the first ranked page. -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`. +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 the `active_memory_callstack_at_event` entry in `pt-snap capabilities --json` 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 @@ -134,21 +135,13 @@ Before claiming that the same blocks persisted across the peak: The template separates blocks without a captured allocation event into their own groups instead of attributing them to callstacks: `[static] allocEventId=-1, freeEventId=-1`, and `[preexisting live] allocEventId=-1` for blocks allocated before tracing that were still live at the analyzed event because their recorded free event came later or does not exist. Pre-tracing blocks whose free event precedes the analyzed event are correctly absent because they were no longer live. Report each group separately instead of absorbing it into a callstack group. -For an exact cross-check of the `[preexisting live]` bucket — for example against a database imported before this grouping existed — do not scan with the packaged `block` filters: they compare `freeEventId` numerically and cannot express the `freeEventId IS NULL` case that the template counts as preexisting-live, so any filtered scan risks an incomplete bucket. Instead, validate that `` is a non-negative decimal integer matching `^[0-9]+$`, then run one read-only aggregate through `sqlite3 -readonly`: +For an exact cross-check of the `[preexisting live]` bucket — for example against a database imported before this grouping existed — do not scan with the packaged `block` filters: they compare `freeEventId` numerically and cannot express the `freeEventId IS NULL` case that `active_memory_callstack_at_event` counts as preexisting-live, so any filtered scan risks an incomplete bucket. Use the packaged `preexisting_live` template instead: ```bash -sqlite3 -readonly '' " -SELECT COUNT(*) AS block_count, COALESCE(SUM(size), 0) AS size_bytes -FROM block_ -WHERE allocEventId = -1 - AND ( - freeEventId IS NULL - OR freeEventId > - OR (freeEventId < 0 AND freeEventId <> -1) - );" +pt-snap query '' --device --template-use preexisting_live --params '{"event_id":}' ``` -The predicate mirrors the template's `[preexisting live]` condition exactly: pre-tracing allocations whose free event is missing (`NULL`), comes later than the analyzed event, or is negative other than the static sentinel `-1`. The aggregate returns a single row, so no row limit applies and nothing is silently undercounted; report the count and bytes next to the static group. +The template uses the same predicate as the `[preexisting live]` group: pre-tracing allocations whose free event is missing (`NULL`), comes later than the analyzed event, or is negative other than the static sentinel `-1`. The aggregate returns a single row, so no row limit applies and nothing is silently undercounted; report the count and bytes next to the static group. Occupancy that stays high across both events strengthens retention evidence but does not by itself prove a leak. @@ -171,28 +164,13 @@ Do not use `block.state` as evidence for dynamic blocks. Its documented lifecycl ### 6. Optionally establish a freed-block lifetime baseline -The packaged templates do not aggregate `freeEventId - allocEventId` into lifetime buckets. Only when this baseline is needed, and only when the `sqlite3` CLI is available, use a read-only fallback after validating that `` is a non-negative decimal integer: +When a lifetime baseline is needed, use the packaged `freed_block_lifetime` template: ```bash -sqlite3 -readonly '' " -SELECT CASE - WHEN freeEventId - allocEventId < 1000 THEN '<1k' - WHEN freeEventId - allocEventId < 5000 THEN '1k-5k' - WHEN freeEventId - allocEventId < 20000 THEN '5k-20k' - WHEN freeEventId - allocEventId < 100000 THEN '20k-100k' - ELSE '>=100k' - END AS lifetime_events, - COUNT(*) AS block_count, - SUM(size) AS size_bytes -FROM block_ -WHERE allocEventId >= 0 AND freeEventId >= allocEventId -GROUP BY lifetime_events -ORDER BY MIN(freeEventId - allocEventId);" +pt-snap query '' --device --template-use freed_block_lifetime ``` -This baseline describes successfully freed blocks. It does not classify end-of-trace candidates and must not be generalized to real elapsed time. - -If `sqlite3` is unavailable or read-only mode cannot be verified, skip this optional step and list the lifetime distribution as unknown. Do not use a writable connection. +This baseline describes successfully freed blocks, bucketed by `freeEventId - allocEventId` distance (`<1k`, `1k-5k`, `5k-20k`, `20k-100k`, `>=100k`). It does not classify end-of-trace candidates and must not be generalized to real elapsed time. Read those limits from the `freed_block_lifetime` entry in `pt-snap capabilities --json`. ### 7. Classify findings conservatively @@ -226,7 +204,7 @@ Useful validation experiments include repeated snapshots at equivalent workload - Keep SnapshotDB access read-only. Never run `create`, `insert`, `update`, `delete`, `drop`, `alter`, `replace`, `attach`, `detach`, `reindex`, or `vacuum` SQL. - Do not persist focus, configuration, reports, exports, scratch databases, or readiness files. - Do not import or deserialize pickle snapshots. -- Prefer packaged `pt-snap` templates. Use raw SQLite only for the two documented read-only aggregates that templates do not expose: the freed-block lifetime baseline (Step 6) and the exact `[preexisting live]` total (Step 4). +- Prefer packaged `pt-snap` templates. Do not use the `sqlite3` CLI or hand-assembled SQL. The exact `[preexisting live]` total is `preexisting_live` (Step 4) and the freed-block lifetime baseline is `freed_block_lifetime` (Step 6). - Do not call every allocation without a free event a leak. - Separate cumulative allocation volume from memory simultaneously live at an event. - Keep static memory separate from dynamic candidates. @@ -245,7 +223,7 @@ Useful validation experiments include repeated snapshots at equivalent workload - End-of-trace dynamic candidates and static memory were reported separately. - Active-peak and final-event callstack attribution used the same device. - Peak-versus-final comparisons were reported as occupancy, and persistence claims relied on identity-matched blocks. -- Preexisting-live memory was reported separately from static and dynamic groups, with exact totals taken only from the documented read-only aggregates. +- Preexisting-live memory was reported separately from static and dynamic groups, with exact totals taken from `preexisting_live`. - Address-event listings stayed bounded with paging or event-ID windows, and `has_more` was honored. - Database paths were single-quoted or passed through argument arrays without shell re-parsing. - Representative lifecycle events were checked for address reuse and ambiguous pairing. diff --git a/src/pt_snap_cli/cli.py b/src/pt_snap_cli/cli.py index ff6628b..bca044c 100644 --- a/src/pt_snap_cli/cli.py +++ b/src/pt_snap_cli/cli.py @@ -36,7 +36,9 @@ ) from pt_snap_cli.config import ENV_DB_PATH from pt_snap_cli.core import ( + CapabilityService, DatabaseMissingError, + DatabaseOverview, DatabaseSchemaError, FocusFileInvalidError, FocusNotConfiguredError, @@ -52,6 +54,7 @@ InvalidDeviceError, InvalidSkillTargetError, JsonValue, + OverviewService, PeakMemoryReport, QueryExecutionError, QueryService, @@ -90,6 +93,7 @@ AGENT_HELP_EPILOG = ( "Agents: prefer --json where supported. " "Start with the pt-snap-helper skill; " + "use pt-snap capabilities --json and pt-snap overview --json before diagnosing; " "check availability with pt-snap skill list --json." ) @@ -1309,6 +1313,81 @@ def show_config( typer.echo(f" {key}: {value}") +@app.command("capabilities") +def show_capabilities( + json_output: Annotated[bool, _json_flag()] = False, +) -> None: + """List CLI version, query template contracts, and bundled skills.""" + service = CapabilityService() + catalog = service.catalog() + if json_output: + _emit_json(json_success(**service.catalog_to_dict(catalog))) + return + typer.echo(f"CLI version: {catalog.cli_version}") + typer.echo() + typer.echo(f"Templates ({len(catalog.templates)}):") + for info in catalog.templates: + category = info.category if info.category is not None else "unknown" + typer.secho(f" {info.name} ({category})", fg=typer.colors.GREEN, bold=True) + typer.echo(f" {info.description}") + if info.parameters: + names = ", ".join(info.parameters) + typer.echo(f" parameters: {names}") + typer.echo() + typer.echo("Use --json for full parameter contracts, output schemas, and field semantics.") + typer.echo() + if not catalog.skills: + typer.echo("Skills: none") + return + typer.echo(f"Skills ({len(catalog.skills)}):") + _print_skill_listings(catalog.skills) + + +@app.command("overview") +def show_database_overview( + db_path: Annotated[ + Path | None, typer.Argument(help="Path to database file (optional if configured)") + ] = None, + json_output: Annotated[bool, _json_flag()] = False, +) -> None: + """Show read-only SnapshotDB devices, trace bounds, and import metadata status.""" + service = OverviewService(_focus_service()) + try: + overview = service.inspect(db_path) + except ( + FocusFileInvalidError, + FocusNotConfiguredError, + DatabaseMissingError, + DatabaseSchemaError, + ) as e: + _error_from_exc(e) + + if json_output: + _emit_json(json_success(**service.overview_to_dict(overview))) + return + _print_database_overview(overview) + + +def _print_database_overview(overview: DatabaseOverview) -> None: + inspection = overview.metadata + typer.echo(f"Database: {overview.db_path}") + typer.echo(f"Focus source: {overview.focus_source}") + typer.echo(f"Import metadata: {inspection.status}") + if inspection.reason is not None: + typer.echo(f"Metadata reason: {inspection.reason}") + if not overview.devices: + typer.echo("Devices: none") + return + typer.echo("Devices:") + for device in overview.devices: + if device.first_event_id is None or device.last_event_id is None: + typer.echo(f" {device.device_id}: no events") + else: + typer.echo( + f" {device.device_id}: events {device.first_event_id}..{device.last_event_id}" + ) + + def _echo_callstack_layout(layout: str | None, error: str | None = None) -> None: if layout == "v1": typer.echo("Callstack layout: v1 (inline text)") diff --git a/src/pt_snap_cli/context.py b/src/pt_snap_cli/context.py index f15118d..9341d23 100644 --- a/src/pt_snap_cli/context.py +++ b/src/pt_snap_cli/context.py @@ -195,6 +195,25 @@ def discover_devices(self) -> list[int]: """ return self.device_ids + def device_trace_bounds(self) -> list[tuple[int, int | None, int | None]]: + """Return ``(device_id, first_event_id, last_event_id)`` for each device. + + Bounds come from ``MIN(id)`` / ``MAX(id)`` on ``trace_entry_``. + Empty tables report ``None`` for both ends. The connection stays + read-only (``mode=ro``). + """ + bounds: list[tuple[int, int | None, int | None]] = [] + with self.connect() as conn: + cursor = conn.cursor() + for device_id in self.device_ids: + table = f"trace_entry_{device_id}" + cursor.execute(f"SELECT MIN(id), MAX(id) FROM {_quote_ident(table)}") + row = cursor.fetchone() + first = int(row[0]) if row is not None and row[0] is not None else None + last = int(row[1]) if row is not None and row[1] is not None else None + bounds.append((device_id, first, last)) + return bounds + def _discover_device_ids(self) -> list[int]: """Discover device IDs from database table names.""" device_ids = set() diff --git a/src/pt_snap_cli/core/AGENTS.md b/src/pt_snap_cli/core/AGENTS.md index 9b99df7..bc5ee8f 100644 --- a/src/pt_snap_cli/core/AGENTS.md +++ b/src/pt_snap_cli/core/AGENTS.md @@ -19,6 +19,8 @@ | `import_metadata.py` | Import metadata schema, inspection, hashing, validation, and cache decisions. | | `models.py` | Dataclasses for focus, import, split, template, query, and report service boundaries. | | `query_service.py` | Template listing/info and query execution orchestration using resolved focus and `QueryExecutor`. | +| `capability_service.py` | Read-only CLI version, full template contracts, and bundled skill listing for `pt-snap capabilities`. | +| `overview_service.py` | Read-only device list, per-device event-id bounds, and import-metadata status for `pt-snap overview`. | | `report_service.py` | Higher-level reports composed from shared query services. | | `snapshot_import_backend.py` | Adapter from trusted snapshot runtime replay to staged SnapshotDB output. | | `split_service.py` | Argument/device validation, replay-safe slicing, staging cleanup, and exclusive publication. | diff --git a/src/pt_snap_cli/core/__init__.py b/src/pt_snap_cli/core/__init__.py index c97131c..a5b523e 100644 --- a/src/pt_snap_cli/core/__init__.py +++ b/src/pt_snap_cli/core/__init__.py @@ -1,3 +1,4 @@ +from pt_snap_cli.core.capability_service import CapabilityService from pt_snap_cli.core.error_codes import classify_error from pt_snap_cli.core.errors import ( DatabaseMissingError, @@ -36,6 +37,9 @@ to_jsonable, ) from pt_snap_cli.core.models import ( + CapabilityCatalog, + DatabaseOverview, + DeviceTraceBounds, FocusState, ImportMetadata, ImportOptions, @@ -53,6 +57,7 @@ TemplateParameter, TemplateSummary, ) +from pt_snap_cli.core.overview_service import OverviewService from pt_snap_cli.core.query_service import QueryService from pt_snap_cli.core.report_service import ReportService from pt_snap_cli.core.skill_service import SkillService @@ -98,6 +103,9 @@ "SkillSpec", "SkillListing", "SkillInstallReport", + "DeviceTraceBounds", + "DatabaseOverview", + "CapabilityCatalog", "classify_error", "JSON_SCHEMA_VERSION", "JsonValue", @@ -112,4 +120,6 @@ "ImportService", "SplitService", "SkillService", + "CapabilityService", + "OverviewService", ] diff --git a/src/pt_snap_cli/core/capability_service.py b/src/pt_snap_cli/core/capability_service.py new file mode 100644 index 0000000..fa52b58 --- /dev/null +++ b/src/pt_snap_cli/core/capability_service.py @@ -0,0 +1,37 @@ +from __future__ import annotations + +from typing import Any + +from pt_snap_cli import __version__ +from pt_snap_cli.core.models import CapabilityCatalog +from pt_snap_cli.core.query_service import QueryService +from pt_snap_cli.core.skill_service import SkillService + + +class CapabilityService: + """Read-only catalog of CLI version, template contracts, and bundled skills.""" + + def __init__( + self, + query_service: QueryService | None = None, + skill_service: SkillService | None = None, + ) -> None: + self._query_service = query_service or QueryService() + self._skill_service = skill_service or SkillService() + + def catalog(self) -> CapabilityCatalog: + return CapabilityCatalog( + cli_version=__version__, + templates=self._query_service.list_template_contracts(), + skills=self._skill_service.list_skills(), + ) + + def catalog_to_dict(self, catalog: CapabilityCatalog) -> dict[str, Any]: + listed = self._skill_service.listing_to_dict(catalog.skills) + return { + "cli_version": catalog.cli_version, + "templates": [ + self._query_service.template_info_to_dict(info) for info in catalog.templates + ], + "skills": listed["skills"], + } diff --git a/src/pt_snap_cli/core/models.py b/src/pt_snap_cli/core/models.py index 755474e..0bc5cb4 100644 --- a/src/pt_snap_cli/core/models.py +++ b/src/pt_snap_cli/core/models.py @@ -240,3 +240,25 @@ class SkillInstallResult: @dataclass(frozen=True) class SkillInstallReport: results: list[SkillInstallResult] + + +@dataclass(frozen=True) +class DeviceTraceBounds: + device_id: int + first_event_id: int | None + last_event_id: int | None + + +@dataclass(frozen=True) +class DatabaseOverview: + db_path: Path + focus_source: FocusSource + devices: list[DeviceTraceBounds] + metadata: MetadataInspection + + +@dataclass(frozen=True) +class CapabilityCatalog: + cli_version: str + templates: list[TemplateInfo] + skills: list[SkillListing] diff --git a/src/pt_snap_cli/core/overview_service.py b/src/pt_snap_cli/core/overview_service.py new file mode 100644 index 0000000..51b8c54 --- /dev/null +++ b/src/pt_snap_cli/core/overview_service.py @@ -0,0 +1,88 @@ +from __future__ import annotations + +import sqlite3 +from pathlib import Path +from typing import Any + +from pt_snap_cli.context import Context, DatabaseNotFoundError, SchemaVersionError +from pt_snap_cli.core.context_cache import ContextCache +from pt_snap_cli.core.errors import ( + DatabaseMissingError, + DatabaseSchemaError, + FocusNotConfiguredError, +) +from pt_snap_cli.core.focus_service import FocusService +from pt_snap_cli.core.import_metadata import ImportMetadataService +from pt_snap_cli.core.models import DatabaseOverview, DeviceTraceBounds + + +class OverviewService: + """Read-only SnapshotDB orientation: devices, trace bounds, import metadata.""" + + def __init__( + self, + focus_service: FocusService | None = None, + metadata_service: ImportMetadataService | None = None, + *, + context_cache: ContextCache | None = None, + ) -> None: + self._focus_service = focus_service or FocusService() + self._metadata_service = metadata_service or ImportMetadataService() + self._context_cache = context_cache if context_cache is not None else ContextCache() + + def inspect( + self, + db_path: Path | str | None = None, + start_dir: Path | None = None, + ) -> DatabaseOverview: + resolved = self._focus_service.resolve_focus( + explicit_db_path=db_path, + start_dir=start_dir, + ) + if resolved.db_path is None: + raise FocusNotConfiguredError("No database path specified and no database configured.") + + db_path = resolved.db_path.expanduser().resolve() + ctx = self._validated_context(db_path) + devices = [ + DeviceTraceBounds( + device_id=device_id, + first_event_id=first_event_id, + last_event_id=last_event_id, + ) + for device_id, first_event_id, last_event_id in ctx.device_trace_bounds() + ] + return DatabaseOverview( + db_path=db_path, + focus_source=resolved.source, + devices=devices, + metadata=self._metadata_service.inspect(db_path), + ) + + def overview_to_dict(self, overview: DatabaseOverview) -> dict[str, Any]: + inspection = self._metadata_service.inspection_to_dict(overview.metadata) + return { + "db_path": str(overview.db_path), + "focus_source": overview.focus_source, + "devices": [ + { + "device_id": device.device_id, + "first_event_id": device.first_event_id, + "last_event_id": device.last_event_id, + } + for device in overview.devices + ], + "import_metadata": { + "status": inspection["status"], + "reason": inspection["reason"], + "metadata": inspection["metadata"], + }, + } + + def _validated_context(self, db_path: Path) -> Context: + try: + return self._context_cache.get(db_path) + except DatabaseNotFoundError as exc: + raise DatabaseMissingError(str(exc)) from exc + except (SchemaVersionError, sqlite3.DatabaseError) as exc: + raise DatabaseSchemaError(str(exc)) from exc diff --git a/src/pt_snap_cli/core/query_service.py b/src/pt_snap_cli/core/query_service.py index 8d68085..e4fbdfc 100644 --- a/src/pt_snap_cli/core/query_service.py +++ b/src/pt_snap_cli/core/query_service.py @@ -126,7 +126,7 @@ def get_template_info(self, name: str) -> TemplateInfo: devices = info["devices"] if isinstance(devices, list): - devices = ", ".join(devices) + devices = ", ".join(str(item) for item in devices) return TemplateInfo( name=info["name"], @@ -152,6 +152,33 @@ def get_template_info(self, name: str) -> TemplateInfo: ), ) + def list_template_contracts(self, category: str | None = None) -> list[TemplateInfo]: + """Return full template contracts, matching ``get_template_info`` per name.""" + return [self.get_template_info(item.name) for item in self.list_templates(category)] + + @staticmethod + def template_info_to_dict(info: TemplateInfo) -> dict[str, Any]: + """Serialize a template contract for CLI/API JSON adapters.""" + return { + "name": info.name, + "description": info.description, + "category": info.category, + "devices": info.devices, + "parameters": { + param_name: { + "type": param.type, + "default": param.default, + "required": param.required, + "description": param.description, + "choices": param.choices, + } + for param_name, param in info.parameters.items() + }, + "output_schema": info.output_schema, + "semantics_version": info.semantics_version, + "interpretation_limits": list(info.interpretation_limits), + } + def execute_query( self, template: str, diff --git a/src/pt_snap_cli/query/templates/business/freed_block_lifetime.yaml b/src/pt_snap_cli/query/templates/business/freed_block_lifetime.yaml new file mode 100644 index 0000000..290078e --- /dev/null +++ b/src/pt_snap_cli/query/templates/business/freed_block_lifetime.yaml @@ -0,0 +1,43 @@ +version: "1.0" +queries: + freed_block_lifetime: + description: Bucket successfully freed blocks by freeEventId-allocEventId distance + devices: + - all + semantics_version: 1 + interpretation_limits: + - "Buckets are event-ID distances (freeEventId - allocEventId), not elapsed time." + - "Only successfully freed blocks (allocEventId >= 0 and freeEventId >= allocEventId) are included." + - "This baseline does not classify end-of-trace candidates and must not be generalized to wall-clock lifetime." + query: | + SELECT CASE + WHEN freeEventId - allocEventId < 1000 THEN '<1k' + WHEN freeEventId - allocEventId < 5000 THEN '1k-5k' + WHEN freeEventId - allocEventId < 20000 THEN '5k-20k' + WHEN freeEventId - allocEventId < 100000 THEN '20k-100k' + ELSE '>=100k' + END AS lifetime_events, + COUNT(*) AS block_count, + COALESCE(SUM(size), 0) AS size_bytes + FROM {{ device_block_table }} + WHERE allocEventId >= 0 AND freeEventId >= allocEventId + GROUP BY lifetime_events + ORDER BY MIN(freeEventId - allocEventId) + output_schema: + - column: lifetime_events + type: str + units: text + metric_semantics: classification + scope: captured_range + interpretation_limits: + - "Label is an event-ID distance bucket, not a duration." + - column: block_count + type: int + units: count + scope: captured_range + - column: size_bytes + type: int + units: bytes + scope: captured_range + interpretation_limits: + - "Sum of sizes of successfully freed blocks in the bucket, not live occupancy." diff --git a/src/pt_snap_cli/query/templates/business/preexisting_live.yaml b/src/pt_snap_cli/query/templates/business/preexisting_live.yaml new file mode 100644 index 0000000..e87fcf6 --- /dev/null +++ b/src/pt_snap_cli/query/templates/business/preexisting_live.yaml @@ -0,0 +1,36 @@ +version: "1.0" +queries: + preexisting_live: + description: Count preexisting-live blocks at an event (pre-tracing allocations still live) + devices: + - all + semantics_version: 1 + interpretation_limits: + - "Counts only allocEventId=-1 blocks that are still live at event_id, using the same predicate as the [preexisting live] group in active_memory_callstack_at_event." + - "The packaged block filters cannot express freeEventId IS NULL, so this aggregate is the exact bucket total." + - "Event IDs are ordering markers, not elapsed time." + - "This is an occupancy aggregate, not a leak confirmation." + parameters: + event_id: + type: int + required: true + description: Trace event ID used as the point-in-time lifecycle boundary + query: | + SELECT COUNT(*) AS block_count, COALESCE(SUM(size), 0) AS size_bytes + FROM {{ device_block_table }} + WHERE allocEventId = -1 + AND ( + freeEventId IS NULL + OR freeEventId > {{ event_id|int }} + OR (freeEventId < 0 AND freeEventId <> -1) + ) + output_schema: + - column: block_count + type: int + units: count + scope: preexisting + - column: size_bytes + type: int + units: bytes + metric_semantics: instantaneous_occupancy + scope: preexisting diff --git a/tests/core/AGENTS.md b/tests/core/AGENTS.md index 029cf89..756d61d 100644 --- a/tests/core/AGENTS.md +++ b/tests/core/AGENTS.md @@ -14,6 +14,8 @@ | `test_import_*.py` | Tests import models/errors, metadata/cache decisions, safe publication, reuse, and failure handling. | | `test_json_codec.py` | Tests Path/dataclass JSON serialization and success/error envelopes. | | `test_query_service.py` | Tests query service template listing/info, focus resolution, execution, row limiting, and error translation. | +| `test_capability_service.py` | Tests the read-only capability catalog (version, template contracts, skills). | +| `test_overview_service.py` | Tests read-only device bounds and import-metadata status. | | `test_report_service.py` | Tests higher-level report composition and normalized results. | | `test_split_service.py` | Tests split contracts, devices, formats, replay validation, cleanup, races, and publication. | | `test_skill_service.py` | Tests skill catalog discovery, install status, host destinations, and conflict handling. | diff --git a/tests/core/test_capability_service.py b/tests/core/test_capability_service.py new file mode 100644 index 0000000..39c4f63 --- /dev/null +++ b/tests/core/test_capability_service.py @@ -0,0 +1,33 @@ +from pathlib import Path +from unittest.mock import patch + +import pytest + +from pt_snap_cli.core.capability_service import CapabilityService +from pt_snap_cli.query.registry import QueryRegistry + + +@pytest.fixture(autouse=True) +def _isolate(tmp_path: Path, monkeypatch: pytest.MonkeyPatch): + monkeypatch.chdir(tmp_path) + monkeypatch.delenv("PT_SNAP_SKILLS_DIR", raising=False) + with patch.object(Path, "home", return_value=tmp_path): + QueryRegistry.reset() + yield + QueryRegistry.reset() + + +def test_catalog_includes_version_template_contracts_and_skills() -> None: + catalog = CapabilityService().catalog() + payload = CapabilityService().catalog_to_dict(catalog) + + assert payload["cli_version"] == catalog.cli_version + names = {item["name"] for item in payload["templates"]} + assert {"leak_detection", "preexisting_live", "freed_block_lifetime"} <= names + leak = next(item for item in payload["templates"] if item["name"] == "leak_detection") + assert leak["semantics_version"] == 1 + assert "min_size" in leak["parameters"] + assert "device_id" not in leak["parameters"] + skill_names = {item["name"] for item in payload["skills"]} + assert "pt-snap-helper" in skill_names + assert "pt-snap-memory-leak" in skill_names diff --git a/tests/core/test_overview_service.py b/tests/core/test_overview_service.py new file mode 100644 index 0000000..41594c1 --- /dev/null +++ b/tests/core/test_overview_service.py @@ -0,0 +1,79 @@ +import sqlite3 +from pathlib import Path +from unittest.mock import patch + +import pytest + +from pt_snap_cli.core import FocusNotConfiguredError, OverviewService +from pt_snap_cli.core.import_metadata import ImportMetadataService + + +@pytest.fixture(autouse=True) +def _isolate(tmp_path: Path, monkeypatch: pytest.MonkeyPatch): + monkeypatch.chdir(tmp_path) + monkeypatch.delenv("PT_SNAP_DB_PATH", raising=False) + with patch.object(Path, "home", return_value=tmp_path): + yield + + +def _overview_db(path: Path) -> Path: + conn = sqlite3.connect(str(path)) + conn.execute("CREATE TABLE dictionary (`table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT)") + for device_id, event_ids in {0: (1, 4, 9), 1: (10, 12)}.items(): + conn.execute(f""" + CREATE TABLE trace_entry_{device_id} ( + id INTEGER PRIMARY KEY, action INTEGER, address INTEGER, size INTEGER, + stream INTEGER, allocated INTEGER, active INTEGER, reserved INTEGER, callstack TEXT + ) + """) + conn.executemany( + f"INSERT INTO trace_entry_{device_id} (id, action) VALUES (?, 4)", + [(event_id,) for event_id in event_ids], + ) + conn.commit() + conn.close() + return path + + +def test_overview_reports_devices_bounds_and_missing_metadata(tmp_path: Path) -> None: + db_path = _overview_db(tmp_path / "overview.db") + payload = OverviewService().overview_to_dict(OverviewService().inspect(db_path)) + + assert payload["db_path"] == str(db_path.resolve()) + assert payload["focus_source"] == "explicit" + assert payload["devices"] == [ + {"device_id": 0, "first_event_id": 1, "last_event_id": 9}, + {"device_id": 1, "first_event_id": 10, "last_event_id": 12}, + ] + assert payload["import_metadata"]["status"] == "unavailable" + assert payload["import_metadata"]["reason"] == "metadata_missing" + + +def test_overview_includes_available_import_metadata(tmp_path: Path) -> None: + db_path = _overview_db(tmp_path / "with_meta.db") + source = tmp_path / "snapshot.pkl" + source.write_bytes(b"snapshot") + service = ImportMetadataService() + digest = service.calculate_sha256(source) + service.write(db_path, service.build_metadata(source, digest, None)) + + payload = OverviewService().overview_to_dict(OverviewService().inspect(db_path)) + assert payload["import_metadata"]["status"] == "available" + assert payload["import_metadata"]["metadata"]["source_sha256"] == digest + + +def test_overview_requires_a_database() -> None: + with pytest.raises(FocusNotConfiguredError): + OverviewService().inspect() + + +def test_overview_empty_device_has_null_bounds(tmp_path: Path) -> None: + db_path = tmp_path / "empty.db" + conn = sqlite3.connect(str(db_path)) + conn.execute("CREATE TABLE dictionary (`table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT)") + conn.execute("CREATE TABLE trace_entry_0 (id INTEGER PRIMARY KEY)") + conn.commit() + conn.close() + + payload = OverviewService().overview_to_dict(OverviewService().inspect(db_path)) + assert payload["devices"] == [{"device_id": 0, "first_event_id": None, "last_event_id": None}] diff --git a/tests/query/AGENTS.md b/tests/query/AGENTS.md index 1ab801a..88635b8 100644 --- a/tests/query/AGENTS.md +++ b/tests/query/AGENTS.md @@ -22,6 +22,7 @@ | `test_query_completeness.py` | Tests `has_more` extra-row probing, inner `top_n` completeness, `total` vs `--exact-total`, event/block/allocation/`leak_detection` stable pagination, and query timeout. | | `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. | +| `test_leak_fallback_templates.py` | Tests `preexisting_live` and `freed_block_lifetime` replacements for leak-skill sqlite3 fallbacks. | ## Subdirectories | Directory | Purpose | diff --git a/tests/query/test_leak_fallback_templates.py b/tests/query/test_leak_fallback_templates.py new file mode 100644 index 0000000..44f887d --- /dev/null +++ b/tests/query/test_leak_fallback_templates.py @@ -0,0 +1,100 @@ +"""Packaged replacements for the leak-skill sqlite3 fallbacks.""" + +from __future__ import annotations + +import sqlite3 +from pathlib import Path + +import pytest + +from pt_snap_cli.context import Context +from pt_snap_cli.query.executor import QueryExecutor +from pt_snap_cli.query.registry import QueryRegistry, _load_all_templates, get_query + + +@pytest.fixture(autouse=True) +def _reload_query_templates() -> None: + QueryRegistry.reset() + _load_all_templates() + + +@pytest.fixture +def leak_fallback_db(tmp_path: Path) -> Path: + db_path = tmp_path / "leak_fallback.db" + conn = sqlite3.connect(str(db_path)) + conn.execute("CREATE TABLE dictionary (`table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT)") + conn.execute(""" + CREATE TABLE trace_entry_0 ( + id INTEGER PRIMARY KEY, action INTEGER, address INTEGER, size INTEGER, + stream INTEGER, allocated INTEGER, active INTEGER, reserved INTEGER, callstack TEXT + ) + """) + conn.execute(""" + CREATE TABLE block_0 ( + id INTEGER PRIMARY KEY, address INTEGER, size INTEGER, requestedSize INTEGER, + state INTEGER, allocEventId INTEGER, freeEventId INTEGER + ) + """) + conn.executemany( + """ + INSERT INTO block_0 + (id, address, size, requestedSize, state, allocEventId, freeEventId) + VALUES (?, ?, ?, ?, ?, ?, ?) + """, + [ + (-10, 0xA000, 8192, 8000, 1, -1, -1), + (-11, 0xB000, 2048, 2000, 1, -1, 8), + (-12, 0xC000, 1024, 1000, 1, -1, None), + (-13, 0xD000, 512, 500, 1, -1, -2), + (-14, 0xE000, 256, 200, 1, -1, 3), + (1, 0x1000, 4096, 4000, 1, 1, 50), + (2, 0x2000, 2048, 2000, 1, 2, 3000), + (3, 0x3000, 1024, 1000, 1, 3, 12000), + (4, 0x4000, 512, 500, 1, 4, 40000), + (5, 0x5000, 256, 200, 1, 5, 150000), + (6, 0x6000, 128, 100, 1, 6, -1), + ], + ) + conn.commit() + conn.close() + return db_path + + +def _execute(db_path: Path, name: str, params: dict[str, object] | None = None) -> list[dict]: + return QueryExecutor(Context(db_path)).execute_template(name, params or {}, device_id=0) + + +def test_preexisting_live_matches_hardened_predicate(leak_fallback_db: Path) -> None: + template = get_query("preexisting_live") + assert template is not None + assert template.semantics_version == 1 + assert template.category == "business" + + rows = _execute(leak_fallback_db, "preexisting_live", {"event_id": 4}) + assert rows == [{"block_count": 3, "size_bytes": 3584}] + + +def test_preexisting_live_excludes_static_and_already_freed(leak_fallback_db: Path) -> None: + later = _execute(leak_fallback_db, "preexisting_live", {"event_id": 8}) + assert later == [{"block_count": 2, "size_bytes": 1536}] + + +def test_freed_block_lifetime_buckets_event_id_distance(leak_fallback_db: Path) -> None: + template = get_query("freed_block_lifetime") + assert template is not None + assert template.semantics_version == 1 + rows = _execute(leak_fallback_db, "freed_block_lifetime") + by_bucket = {row["lifetime_events"]: row for row in rows} + assert by_bucket["<1k"]["block_count"] == 1 + assert by_bucket["<1k"]["size_bytes"] == 4096 + assert by_bucket["1k-5k"]["block_count"] == 1 + assert by_bucket["1k-5k"]["size_bytes"] == 2048 + assert by_bucket["5k-20k"]["block_count"] == 1 + assert by_bucket["20k-100k"]["block_count"] == 1 + assert by_bucket[">=100k"]["block_count"] == 1 + assert "lifetime_events" in {column["column"] for column in template.output_schema} + + +def test_freed_block_lifetime_excludes_unfreed_and_static(leak_fallback_db: Path) -> None: + rows = _execute(leak_fallback_db, "freed_block_lifetime") + assert sum(row["block_count"] for row in rows) == 5 diff --git a/tests/query/test_peak_memory_templates.py b/tests/query/test_peak_memory_templates.py index 6915680..670d28b 100644 --- a/tests/query/test_peak_memory_templates.py +++ b/tests/query/test_peak_memory_templates.py @@ -116,10 +116,14 @@ def test_new_templates_are_registered_in_correct_categories() -> None: assert "active_blocks_at_event" in list_by_category("statistical") assert "allocator_gap" in list_by_category("statistical") assert "active_memory_callstack_at_event" in list_by_category("business") + assert "preexisting_live" in list_by_category("business") + assert "freed_block_lifetime" in list_by_category("business") assert get_query("active_blocks_at_event") is not None assert get_query("allocator_gap") is not None assert get_query("active_memory_callstack_at_event") is not None + assert get_query("preexisting_live") is not None + assert get_query("freed_block_lifetime") is not None def test_active_blocks_at_event_includes_static_when_enabled(peak_memory_db: Path) -> None: diff --git a/tests/query/test_registry.py b/tests/query/test_registry.py index 1849673..23c7646 100644 --- a/tests/query/test_registry.py +++ b/tests/query/test_registry.py @@ -4,9 +4,10 @@ import pytest -from pt_snap_cli.query.config import QueryParameter, QueryTemplate +from pt_snap_cli.query.config import QueryConfig, QueryParameter, QueryTemplate from pt_snap_cli.query.registry import ( QueryRegistry, + _infer_category, _load_all_templates, _load_yaml_templates, get_query, @@ -247,8 +248,20 @@ def test_packaged_sql_fragment_parameters_declare_choices(self): database. Every packaged template that exposes them must bound them with ``choices`` drawn from its own output columns. """ + packaged_dir = ( + Path(__file__).resolve().parents[2] / "src" / "pt_snap_cli" / "query" / "templates" + ) + packaged_names: set[str] = set() + for yaml_file in packaged_dir.glob("**/*.yaml"): + config = QueryConfig.load_yaml( + yaml_file, default_category=_infer_category(yaml_file, packaged_dir) + ) + packaged_names.update(config.queries) + checked = 0 for name in list_queries(): + if name not in packaged_names: + continue template = get_query(name) assert template is not None columns = {column["column"] for column in template.output_schema} diff --git a/tests/query/test_template_semantics.py b/tests/query/test_template_semantics.py index 02a504b..5d19de4 100644 --- a/tests/query/test_template_semantics.py +++ b/tests/query/test_template_semantics.py @@ -24,6 +24,8 @@ def setup_function() -> None: "memory_peak", "allocator_gap", "active_memory_callstack_at_event", + "preexisting_live", + "freed_block_lifetime", ) diff --git a/tests/skills/suites/pt-snap-memory-leak/cases/address-reuse.yaml b/tests/skills/suites/pt-snap-memory-leak/cases/address-reuse.yaml index a86a569..96cfe55 100644 --- a/tests/skills/suites/pt-snap-memory-leak/cases/address-reuse.yaml +++ b/tests/skills/suites/pt-snap-memory-leak/cases/address-reuse.yaml @@ -19,7 +19,7 @@ fixture: expected_tools: actions: - id: validate_database - operation: pt_snap.metadata + operation: pt_snap.overview match: {database: /fixtures/address-reuse.db, json: true} - id: inspect_candidates operation: pt_snap.query diff --git a/tests/skills/suites/pt-snap-memory-leak/cases/allocator-cache.yaml b/tests/skills/suites/pt-snap-memory-leak/cases/allocator-cache.yaml index 862b078..1967d6b 100644 --- a/tests/skills/suites/pt-snap-memory-leak/cases/allocator-cache.yaml +++ b/tests/skills/suites/pt-snap-memory-leak/cases/allocator-cache.yaml @@ -18,7 +18,7 @@ fixture: expected_tools: actions: - id: validate_database - operation: pt_snap.metadata + operation: pt_snap.overview match: {database: /fixtures/cache.db, json: true} - id: inspect_peaks operation: pt_snap.query diff --git a/tests/skills/suites/pt-snap-memory-leak/cases/pending-free.yaml b/tests/skills/suites/pt-snap-memory-leak/cases/pending-free.yaml index 2462baa..85d26ed 100644 --- a/tests/skills/suites/pt-snap-memory-leak/cases/pending-free.yaml +++ b/tests/skills/suites/pt-snap-memory-leak/cases/pending-free.yaml @@ -18,7 +18,7 @@ fixture: expected_tools: actions: - id: validate_database - operation: pt_snap.metadata + operation: pt_snap.overview match: {database: /fixtures/pending-free.db, json: true} - id: inspect_candidates operation: pt_snap.query diff --git a/tests/skills/suites/pt-snap-memory-leak/suite.yaml b/tests/skills/suites/pt-snap-memory-leak/suite.yaml index 2b56eff..60cebbd 100644 --- a/tests/skills/suites/pt-snap-memory-leak/suite.yaml +++ b/tests/skills/suites/pt-snap-memory-leak/suite.yaml @@ -7,6 +7,8 @@ metadata: description: > Evaluate read-only routing, evidence collection, tool use, conservative classification, and uncertainty handling for memory retention diagnosis. + Prerequisite probes should be capabilities + overview (2 calls) instead of + metadata plus six --template-info probes (7 calls). skill: path: skills/pt-snap-memory-leak/SKILL.md @@ -73,14 +75,16 @@ defaults: tool_policy: allowed: - pt_snap.focus_read + - pt_snap.capabilities + - pt_snap.overview - pt_snap.metadata - pt_snap.template_info - pt_snap.query - - sqlite.readonly forbidden: - pt_snap.import - pt_snap.focus_write - pt_snap.split + - sqlite.readonly - sqlite.write - filesystem.write - package.install diff --git a/tests/skills/test_grader.py b/tests/skills/test_grader.py index b9ee995..dc4c025 100644 --- a/tests/skills/test_grader.py +++ b/tests/skills/test_grader.py @@ -12,7 +12,7 @@ def _passing_allocator_cache_run() -> RunRecord: tool_calls=( ToolCall( "call-1", - "pt_snap.metadata", + "pt_snap.overview", {"database": "/fixtures/cache.db", "json": True}, output={"status": "unavailable", "reason": "metadata_missing", "metadata": None}, ), diff --git a/tests/skills/test_helper_contract.py b/tests/skills/test_helper_contract.py index f12eecf..700dd94 100644 --- a/tests/skills/test_helper_contract.py +++ b/tests/skills/test_helper_contract.py @@ -28,6 +28,8 @@ ("import",), ("split",), ("config",), + ("capabilities",), + ("overview",), ) @@ -69,6 +71,8 @@ def test_helper_skill_uses_current_json_capability() -> None: skill = _skill() assert "Prefer `--json` where supported" in skill + assert "pt-snap capabilities --json" in skill + assert "pt-snap overview '' --json" in skill assert "pt-snap metadata '' --json" in skill assert "pt-snap report peak-memory '' --device --json" in skill assert "pt-snap query --list --json" in skill @@ -90,6 +94,7 @@ def test_helper_skill_routes_by_goal_and_input_type() -> None: assert "## Routing matrix" in skill assert "Existing SnapshotDB" in skill + assert "overview first, then diagnose" in skill assert "Only pickle" in skill assert "`pt-snap` missing" in skill assert "Need Ascend NPU capture" in skill @@ -105,6 +110,7 @@ def test_helper_skill_keeps_pickle_import_and_focus_as_handoffs() -> None: assert "Do not run `pt-snap import`." in skill assert "Do not run `pt-snap focus` with a database path." in skill assert "Do not persist focus" in skill + assert "overview first, then diagnose" in skill assert "This helper must not run that command or change focus." in skill assert "pt-snap import --json" in skill assert "That command currently has no `--json` option." not in skill diff --git a/tests/skills/test_memory_leak_contract.py b/tests/skills/test_memory_leak_contract.py index 885774d..f540dba 100644 --- a/tests/skills/test_memory_leak_contract.py +++ b/tests/skills/test_memory_leak_contract.py @@ -17,8 +17,12 @@ def test_memory_leak_skill_uses_current_pt_snap_surfaces() -> None: "block", "leak_detection", "active_memory_callstack_at_event", + "preexisting_live", + "freed_block_lifetime", ): assert f"--template-use {template}" in skill or f"--template-info {template}" in skill + assert "pt-snap capabilities --json" in skill + assert "pt-snap overview '' --json" in skill def test_memory_leak_skill_preserves_diagnostic_boundaries() -> None: @@ -95,19 +99,15 @@ def test_memory_leak_skill_cross_checks_preexisting_bucket_exactly() -> None: skill = SKILL_PATH.read_text() assert "cannot express the `freeEventId IS NULL` case" in skill - assert "non-negative decimal integer matching `^[0-9]+$`" in skill - assert "COALESCE(SUM(size), 0) AS size_bytes" in skill - assert "freeEventId IS NULL" in skill - assert "OR freeEventId > " in skill - assert "(freeEventId < 0 AND freeEventId <> -1)" in skill + assert "--template-use preexisting_live" in skill + assert '"event_id":' in skill + assert "sqlite3 -readonly" not in skill assert "returns a single row" in skill assert "nothing is silently undercounted" in skill - - guardrail = "two documented read-only aggregates that templates do not expose" - assert guardrail in skill - assert "only for the optional lifetime aggregate" not in skill - assert "the freed-block lifetime baseline (Step 6)" in skill - assert "the exact `[preexisting live]` total (Step 4)" in skill + assert "--template-use freed_block_lifetime" in skill + assert "Do not use the `sqlite3` CLI or hand-assembled SQL" in skill + assert "`preexisting_live` (Step 4)" in skill + assert "`freed_block_lifetime` (Step 6)" in skill def test_memory_leak_skill_has_no_incomplete_bucket_scan() -> None: @@ -134,6 +134,14 @@ 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 "--template-info active_memory_callstack_at_event" in skill + assert "active_memory_callstack_at_event` entry in `pt-snap capabilities --json" 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 + + +def test_memory_leak_skill_records_reduced_prerequisite_probes() -> None: + skill = SKILL_PATH.read_text() + + assert "previously 7 calls" in skill + assert "Now 2 calls" in skill + assert "Do not probe templates one-by-one with `--template-info`" in skill diff --git a/tests/test_api.py b/tests/test_api.py index 094acdd..a45c960 100644 --- a/tests/test_api.py +++ b/tests/test_api.py @@ -302,3 +302,25 @@ def test_get_database_metadata_available(self, valid_db: Path) -> None: assert result["status"] == "available" assert result["metadata"]["source_sha256"] == digest source.unlink() + + def test_list_capabilities(self) -> None: + payload = SnapshotAnalyzer().list_capabilities() + assert "cli_version" in payload + names = {item["name"] for item in payload["templates"]} + assert "leak_detection" in names + assert "preexisting_live" in names + assert "freed_block_lifetime" in names + skill_names = {item["name"] for item in payload["skills"]} + assert "pt-snap-helper" in skill_names + + def test_get_database_overview(self, valid_db: Path) -> None: + payload = SnapshotAnalyzer(db_path=valid_db).get_database_overview() + assert payload["db_path"] == str(valid_db.resolve()) + assert payload["devices"] == [ + {"device_id": 0, "first_event_id": None, "last_event_id": None} + ] + assert payload["import_metadata"]["status"] == "unavailable" + + def test_get_database_overview_requires_focus(self) -> None: + with pytest.raises(RuntimeError, match="No database configured"): + SnapshotAnalyzer().get_database_overview() diff --git a/tests/test_cli.py b/tests/test_cli.py index ced0c9c..dd477e5 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -206,6 +206,8 @@ def test_help_flag(self) -> None: result = runner.invoke(app, ["--help"]) assert result.exit_code == 0 assert "PyTorch Memory Snapshot Analysis Tool" in result.stdout + assert "capabilities" in result.stdout + assert "overview" in result.stdout def test_short_help_flag(self) -> None: """Test -h flag.""" @@ -1665,3 +1667,27 @@ def test_skill_dir_rejects_project(self, tmp_path: Path) -> None: ) assert result.exit_code == 1 assert "--dir cannot be combined with --project" in unstyle(result.stdout) + + +class TestCapabilitiesAndOverviewCommands: + def test_capabilities_text_lists_templates_and_skills(self) -> None: + result = runner.invoke(app, ["capabilities"]) + assert result.exit_code == 0 + assert "CLI version:" in result.stdout + assert "leak_detection" in result.stdout + assert "preexisting_live" in result.stdout + assert "freed_block_lifetime" in result.stdout + assert "pt-snap-helper" in result.stdout + assert "Use --json for full parameter contracts" in result.stdout + + def test_overview_text_reports_devices_and_metadata(self, sample_db: Path) -> None: + result = runner.invoke(app, ["overview", str(sample_db)]) + assert result.exit_code == 0 + assert f"Database: {sample_db.resolve()}" in result.stdout + assert "Import metadata: unavailable" in result.stdout + assert "0: events 1..1" in result.stdout + + def test_overview_requires_database(self) -> None: + result = runner.invoke(app, ["overview"]) + assert result.exit_code == 1 + assert "No database path specified" in unstyle(result.stdout) diff --git a/tests/test_cli_json.py b/tests/test_cli_json.py index 8f1fbfb..e100caf 100644 --- a/tests/test_cli_json.py +++ b/tests/test_cli_json.py @@ -666,3 +666,30 @@ def test_text_mode_errors_still_use_stdout(tmp_path: Path) -> None: assert result.exit_code == 1 assert "Error: Template 'does_not_exist' not found" in result.stdout assert result.stderr == "" or "TEMPLATE_NOT_FOUND" not in result.stderr + + +def test_capabilities_json_uses_success_envelope() -> None: + result = runner.invoke(app, ["capabilities", "--json"]) + payload = _assert_clean_json_success(result) + assert "cli_version" in payload + names = {item["name"] for item in payload["templates"]} + assert {"leak_detection", "preexisting_live", "freed_block_lifetime"} <= names + leak = next(item for item in payload["templates"] if item["name"] == "leak_detection") + assert leak["semantics_version"] == 1 + assert "min_size" in leak["parameters"] + skill_names = {item["name"] for item in payload["skills"]} + assert "pt-snap-helper" in skill_names + + +def test_overview_json_uses_success_envelope(sample_db: Path) -> None: + result = runner.invoke(app, ["overview", str(sample_db), "--json"]) + payload = _assert_clean_json_success(result) + assert payload["db_path"] == str(sample_db.resolve()) + assert payload["focus_source"] == "explicit" + assert payload["devices"] == [{"device_id": 0, "first_event_id": 1, "last_event_id": 1}] + assert payload["import_metadata"]["status"] == "unavailable" + + +def test_overview_json_error_uses_stderr_envelope() -> None: + result = runner.invoke(app, ["overview", "--json"]) + _assert_json_error(result, "FOCUS_NOT_CONFIGURED") diff --git a/tests/test_context.py b/tests/test_context.py index 9ff48e6..8135a8c 100644 --- a/tests/test_context.py +++ b/tests/test_context.py @@ -119,6 +119,14 @@ def test_device_ids_discovery(self, valid_db: Path) -> None: ctx = Context(valid_db) assert ctx.device_ids == [0] + def test_device_trace_bounds_empty_and_populated(self, valid_db: Path) -> None: + ctx = Context(valid_db) + assert ctx.device_trace_bounds() == [(0, None, None)] + with sqlite3.connect(str(valid_db)) as conn: + conn.execute("INSERT INTO trace_entry_0 (id, action) VALUES (3, 4), (9, 4)") + conn.commit() + assert Context(valid_db).device_trace_bounds() == [(0, 3, 9)] + def test_device_filter(self, valid_db: Path) -> None: """Test device filtering.""" ctx = Context(valid_db, devices=[0]) diff --git a/tests/test_contract_cli_api.py b/tests/test_contract_cli_api.py index 3ec9d14..a29b3d4 100644 --- a/tests/test_contract_cli_api.py +++ b/tests/test_contract_cli_api.py @@ -640,3 +640,27 @@ def test_json_error_contract_keeps_text_errors_on_stdout(contract_db: Path) -> N error = json.loads(json_result.stderr)["error"] assert error["code"] == "TEMPLATE_NOT_FOUND" assert "does_not_exist" in error["message"] + + +def test_capabilities_contract_matches_cli_and_api_semantics(analyzer: SnapshotAnalyzer) -> None: + cli_result = runner.invoke(app, ["capabilities", "--json"]) + payload = _json_stdout(cli_result) + api = analyzer.list_capabilities() + assert payload["cli_version"] == api["cli_version"] + assert payload["templates"] == api["templates"] + assert payload["skills"] == api["skills"] + assert {item["name"] for item in api["templates"]} >= { + "leak_detection", + "preexisting_live", + "freed_block_lifetime", + } + + +def test_overview_contract_matches_cli_and_api_semantics(contract_db: Path) -> None: + cli_result = runner.invoke(app, ["overview", str(contract_db), "--json"]) + payload = _json_stdout(cli_result) + api = _focused_analyzer(contract_db).get_database_overview() + assert payload["db_path"] == api["db_path"] + assert payload["devices"] == api["devices"] + assert payload["import_metadata"] == api["import_metadata"] + assert payload["focus_source"] == "explicit" From 2fbf5cbf73479da326a44d7e832b4b63ca495d0b Mon Sep 17 00:00:00 2001 From: codeasier Date: Sat, 19 Sep 2026 17:53:50 +0800 Subject: [PATCH 2/2] fix: keep capabilities/overview failures in the JSON envelope Review of #154 found traceback leaks and a preexisting_live static-block edge case that broke the #138 agent contract and the template's own predicate claim. Map those paths to stable errors and one shared template-info serializer. --- CHANGELOG.md | 4 +- docs/en/snapshot-analyzer-api.md | 8 ++- docs/zh/snapshot-analyzer-api.md | 4 ++ src/pt_snap_cli/api.py | 23 ++------- src/pt_snap_cli/cli.py | 25 ++-------- src/pt_snap_cli/context.py | 8 +-- src/pt_snap_cli/core/overview_service.py | 6 ++- .../templates/business/preexisting_live.yaml | 2 +- tests/core/test_overview_service.py | 28 ++++++++++- tests/query/test_leak_fallback_templates.py | 7 +++ tests/test_api.py | 7 +++ tests/test_cli_json.py | 44 ++++++++++++++++ tests/test_context.py | 12 +++++ tests/test_contract_cli_api.py | 50 +++++++++++++++++++ 14 files changed, 176 insertions(+), 52 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 66a0bc0..86188ed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ - 新增 `pt-snap capabilities`:一次输出 CLI 版本、全部查询模板/参数契约(含字段语义)和技能清单。`--json` 使用 #138 成功信封,替代逐个 `--template-info` 探测。 - 新增 `pt-snap overview`:只读输出设备列表、各设备首/末 event id,以及导入 metadata 状态。`--json` 使用同一信封;分析路径不写数据库、不持久化 focus。 -- 新增 `preexisting_live` 与 `freed_block_lifetime` 查询模板,泄漏技能不再依赖 `sqlite3` CLI 回退。诊断前置探测从 7 次(`metadata` + 六个 `--template-info`)降为 2 次(`capabilities` + `overview`)。helper 引导「先概览、再诊断」。 +- 新增 `preexisting_live` 与 `freed_block_lifetime` 查询模板,泄漏技能不再依赖 `sqlite3` CLI 回退。`preexisting_live` 排除 `freeEventId = -1` 的 static 块,与 `active_memory_callstack_at_event` 的 `[preexisting live]` 分组一致。诊断前置探测从 7 次(`metadata` + 六个 `--template-info`)降为 2 次(`capabilities` + `overview`)。helper 引导「先概览、再诊断」。 - `focus`、`import`、`split`、`query`、`config` 支持 `--json`。成功结果带 `schema_version` / `ok` 信封,以及 `db_path`、`focus_source`、`device_id`、`template`、`effective_params` 等上下文。`query --list` / `--template-info` / 执行共用该选项;`--template-info --json` 透出 #147 字段语义。 - JSON 模式失败时 stdout 为空,stderr 为带稳定错误码的结构化对象(如 `TEMPLATE_NOT_FOUND`、`INVALID_PARAMETER`、`DATABASE_NOT_FOUND`、`DEVICE_NOT_FOUND`),退出码非零。`pt-snap` 控制台入口返回 Typer/Click 的退出码(不再丢弃非 standalone 返回值),在检测到 `--json` 时也会把 Click 用法/解析错误写成 `INVALID_PARAMETER` 信封(退出码 2),并把 Ctrl-C / EOF 写成 `ERROR` / `Aborted!`。解析失败时的 `--json` 判定是 argv 词法扫描(best-effort):忽略 `--` 之后的词,`--opt=value` 与数字词不吞后续参数。`query --json` 的 `effective_params.limit` 是尾部 SQL `LIMIT`(模板 `limit` 与 `-n` 的合并,或追加的 `-n`);CTE 内的 `top_n` 仍是独立参数。 - `split --json` 只控制 stdout 清单,与 `--format json` 的分片文件格式相互独立。`focus --session --json` 返回验证结果与 `PT_SNAP_DB_PATH` 赋值信息,不暗示已修改父 shell。 @@ -15,7 +15,7 @@ ### 兼容性提示 - 文本模式保持原样:人类可读输出不变,`_error()` 与查询/报告说明行仍写 stdout。缺失模板的 `query --template-info` 已在 0.4.0 以退出码 1 失败。数据库无设备时,文本模式查询仍退出 0;JSON 模式改为 `DEVICE_NOT_FOUND` 且退出码非零。 -- 已有 `metadata --json`、`report peak-memory --json` 与 `skill list/install/upgrade/uninstall --json` 成功字段保持兼容,不包进新信封。它们在 `--json` 失败时改走 stderr 错误信封。新的 `capabilities --json` 与 `overview --json` 使用 #138 成功/失败信封。 +- 已有 `metadata --json`、`report peak-memory --json` 与 `skill list/install/upgrade/uninstall --json` 成功字段保持兼容,不包进新信封。它们在 `--json` 失败时改走 stderr 错误信封。新的 `capabilities --json` 与 `overview --json` 使用 #138 成功/失败信封。`capabilities` 在技能目录不可读时走 `SKILL_ERROR`;`overview` 把损坏的设备表/边界查询翻译为 `DATABASE_SCHEMA_INVALID`,并把损坏的 focus 文件翻译为 `FOCUS_FILE_INVALID`。 - 查询默认 `total` 不再在触达 `-n` 时自动变成匹配集合 `COUNT`。依赖该旧语义的调用方必须显式传 `--exact-total` / `exact_total=True`。 ## [0.4.0] - Unreleased diff --git a/docs/en/snapshot-analyzer-api.md b/docs/en/snapshot-analyzer-api.md index 8cda4fd..3120632 100644 --- a/docs/en/snapshot-analyzer-api.md +++ b/docs/en/snapshot-analyzer-api.md @@ -163,7 +163,10 @@ print(overview["import_metadata"]["status"]) `get_database_overview()` is the read-only orientation used by `pt-snap overview`: device list, per-device first/last event id, and import -metadata status. It does not persist focus or write the database. +metadata status. It does not persist focus or write the database. Missing +focus raises `RuntimeError`; a missing file raises `FileNotFoundError`; an +invalid SnapshotDB schema or a damaged `.pt-snap/focus.json` raises +`ValueError`. ## Inspect Import Metadata @@ -188,6 +191,9 @@ metadata schema version returns `status="invalid"`. - `execute_query()` raises `RuntimeError` when no database can be resolved; query, parameter, device, and database errors otherwise follow the shared service-layer exceptions. +- `get_database_overview()` raises `RuntimeError` without a resolved database, + `FileNotFoundError` for a missing file, and `ValueError` for an invalid schema + or an invalid `.pt-snap/focus.json`. - `get_database_metadata()` raises `RuntimeError` without a resolved database, `FileNotFoundError` for a missing file, and `ValueError` for an invalid schema. - `SnapshotAnalyzer` does not import or split raw pickle snapshots and does not diff --git a/docs/zh/snapshot-analyzer-api.md b/docs/zh/snapshot-analyzer-api.md index 3fa6291..3febe2e 100644 --- a/docs/zh/snapshot-analyzer-api.md +++ b/docs/zh/snapshot-analyzer-api.md @@ -152,6 +152,8 @@ print(overview["import_metadata"]["status"]) `get_database_overview()` 是 `pt-snap overview` 使用的只读概览:设备列表、各设备 首/末 event id,以及导入 metadata 状态。它不会持久化 focus,也不会写入数据库。 +未配置 focus 时抛出 `RuntimeError`;文件不存在时抛出 `FileNotFoundError`; +SnapshotDB schema 无效或 `.pt-snap/focus.json` 损坏时抛出 `ValueError`。 ## 检查导入 Metadata @@ -173,6 +175,8 @@ other_metadata = analyzer.get_database_metadata("/path/to/other.db") 设置设备会抛出 `RuntimeError`。 - `execute_query()` 在无法解析数据库时抛出 `RuntimeError`;其他查询、参数、设备和数据库 错误遵循共享 service 层异常。 +- `get_database_overview()` 在没有已解析数据库时抛出 `RuntimeError`,文件不存在时抛出 + `FileNotFoundError`,schema 无效或 `.pt-snap/focus.json` 损坏时抛出 `ValueError`。 - `get_database_metadata()` 在没有已解析数据库时抛出 `RuntimeError`,文件不存在时抛出 `FileNotFoundError`,schema 无效时抛出 `ValueError`。 - `SnapshotAnalyzer` 不负责导入或拆分原始 pickle,也不生成 report。相关工作流应使用 diff --git a/src/pt_snap_cli/api.py b/src/pt_snap_cli/api.py index 2fa2e32..e8e5b7d 100644 --- a/src/pt_snap_cli/api.py +++ b/src/pt_snap_cli/api.py @@ -11,6 +11,7 @@ CapabilityService, DatabaseMissingError, DatabaseSchemaError, + FocusFileInvalidError, FocusNotConfiguredError, FocusService, ImportMetadataService, @@ -131,25 +132,7 @@ def get_template_info(self, name: str) -> dict[str, Any] | None: except TemplateNotFoundError: return None - return { - "name": info.name, - "description": info.description, - "category": info.category, - "devices": info.devices, - "parameters": { - param_name: { - "type": param.type, - "default": param.default, - "required": param.required, - "description": param.description, - "choices": param.choices, - } - for param_name, param in info.parameters.items() - }, - "output_schema": info.output_schema, - "semantics_version": info.semantics_version, - "interpretation_limits": info.interpretation_limits, - } + return self._query_service.template_info_to_dict(info) def execute_query( self, @@ -195,6 +178,8 @@ def get_database_overview(self, db_path: str | None = None) -> dict[str, Any]: overview = self._overview_service.inspect(resolved_path) except FocusNotConfiguredError as exc: raise RuntimeError("No database configured. Call set_focus() first.") from exc + except FocusFileInvalidError as exc: + raise ValueError(str(exc)) from exc except DatabaseMissingError as exc: raise FileNotFoundError(str(exc)) from exc except DatabaseSchemaError as exc: diff --git a/src/pt_snap_cli/cli.py b/src/pt_snap_cli/cli.py index bca044c..4d4439b 100644 --- a/src/pt_snap_cli/cli.py +++ b/src/pt_snap_cli/cli.py @@ -185,25 +185,7 @@ def _split_json(result: SplitResult) -> dict[str, JsonValue]: def _template_info_dict(info: TemplateInfo) -> dict[str, object]: - return { - "name": info.name, - "description": info.description, - "category": info.category, - "devices": info.devices, - "parameters": { - param_name: { - "type": param.type, - "default": param.default, - "required": param.required, - "description": param.description, - "choices": param.choices, - } - for param_name, param in info.parameters.items() - }, - "output_schema": info.output_schema, - "semantics_version": info.semantics_version, - "interpretation_limits": list(info.interpretation_limits), - } + return QueryService.template_info_to_dict(info) def _effective_query_params( @@ -1319,7 +1301,10 @@ def show_capabilities( ) -> None: """List CLI version, query template contracts, and bundled skills.""" service = CapabilityService() - catalog = service.catalog() + try: + catalog = service.catalog() + except SkillCatalogError as e: + _error_from_exc(e) if json_output: _emit_json(json_success(**service.catalog_to_dict(catalog))) return diff --git a/src/pt_snap_cli/context.py b/src/pt_snap_cli/context.py index 9341d23..6fe8bb0 100644 --- a/src/pt_snap_cli/context.py +++ b/src/pt_snap_cli/context.py @@ -218,13 +218,7 @@ def _discover_device_ids(self) -> list[int]: """Discover device IDs from database table names.""" device_ids = set() with self.connect() as conn: - cursor = conn.cursor() - cursor.execute( - "SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'trace_entry_%'" - ) - for row in cursor.fetchall(): - table_name = row[0] - device_id = int(table_name.split("_")[-1]) + for device_id, _table_name in _trace_entry_tables(conn.cursor()): if self._devices is None or device_id in self._devices: device_ids.add(device_id) return sorted(device_ids) diff --git a/src/pt_snap_cli/core/overview_service.py b/src/pt_snap_cli/core/overview_service.py index 51b8c54..d24dde7 100644 --- a/src/pt_snap_cli/core/overview_service.py +++ b/src/pt_snap_cli/core/overview_service.py @@ -44,13 +44,17 @@ def inspect( db_path = resolved.db_path.expanduser().resolve() ctx = self._validated_context(db_path) + try: + raw_bounds = ctx.device_trace_bounds() + except (ValueError, sqlite3.DatabaseError) as exc: + raise DatabaseSchemaError(str(exc)) from exc devices = [ DeviceTraceBounds( device_id=device_id, first_event_id=first_event_id, last_event_id=last_event_id, ) - for device_id, first_event_id, last_event_id in ctx.device_trace_bounds() + for device_id, first_event_id, last_event_id in raw_bounds ] return DatabaseOverview( db_path=db_path, diff --git a/src/pt_snap_cli/query/templates/business/preexisting_live.yaml b/src/pt_snap_cli/query/templates/business/preexisting_live.yaml index e87fcf6..cd84650 100644 --- a/src/pt_snap_cli/query/templates/business/preexisting_live.yaml +++ b/src/pt_snap_cli/query/templates/business/preexisting_live.yaml @@ -21,7 +21,7 @@ queries: WHERE allocEventId = -1 AND ( freeEventId IS NULL - OR freeEventId > {{ event_id|int }} + OR (freeEventId > {{ event_id|int }} AND freeEventId <> -1) OR (freeEventId < 0 AND freeEventId <> -1) ) output_schema: diff --git a/tests/core/test_overview_service.py b/tests/core/test_overview_service.py index 41594c1..8d8bcf3 100644 --- a/tests/core/test_overview_service.py +++ b/tests/core/test_overview_service.py @@ -4,7 +4,7 @@ import pytest -from pt_snap_cli.core import FocusNotConfiguredError, OverviewService +from pt_snap_cli.core import DatabaseSchemaError, FocusNotConfiguredError, OverviewService from pt_snap_cli.core.import_metadata import ImportMetadataService @@ -77,3 +77,29 @@ def test_overview_empty_device_has_null_bounds(tmp_path: Path) -> None: payload = OverviewService().overview_to_dict(OverviewService().inspect(db_path)) assert payload["devices"] == [{"device_id": 0, "first_event_id": None, "last_event_id": None}] + + +def test_overview_missing_id_column_is_schema_error(tmp_path: Path) -> None: + db_path = tmp_path / "no-id.db" + conn = sqlite3.connect(str(db_path)) + conn.execute("CREATE TABLE dictionary (`table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT)") + conn.execute("CREATE TABLE trace_entry_0 (action INTEGER)") + conn.commit() + conn.close() + + with pytest.raises(DatabaseSchemaError): + OverviewService().inspect(db_path) + + +def test_overview_skips_non_numeric_trace_entry_suffix(tmp_path: Path) -> None: + db_path = tmp_path / "mixed.db" + conn = sqlite3.connect(str(db_path)) + conn.execute("CREATE TABLE dictionary (`table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT)") + conn.execute("CREATE TABLE trace_entry_foo (id INTEGER PRIMARY KEY)") + conn.execute("CREATE TABLE trace_entry_0 (id INTEGER PRIMARY KEY)") + conn.execute("INSERT INTO trace_entry_0 (id) VALUES (3)") + conn.commit() + conn.close() + + payload = OverviewService().overview_to_dict(OverviewService().inspect(db_path)) + assert payload["devices"] == [{"device_id": 0, "first_event_id": 3, "last_event_id": 3}] diff --git a/tests/query/test_leak_fallback_templates.py b/tests/query/test_leak_fallback_templates.py index 44f887d..537c2dc 100644 --- a/tests/query/test_leak_fallback_templates.py +++ b/tests/query/test_leak_fallback_templates.py @@ -79,6 +79,13 @@ def test_preexisting_live_excludes_static_and_already_freed(leak_fallback_db: Pa assert later == [{"block_count": 2, "size_bytes": 1536}] +def test_preexisting_live_excludes_static_at_negative_event_ids(leak_fallback_db: Path) -> None: + at_alloc_sentinel = _execute(leak_fallback_db, "preexisting_live", {"event_id": -1}) + before_alloc_sentinel = _execute(leak_fallback_db, "preexisting_live", {"event_id": -2}) + assert at_alloc_sentinel == [{"block_count": 4, "size_bytes": 3840}] + assert before_alloc_sentinel == [{"block_count": 4, "size_bytes": 3840}] + + def test_freed_block_lifetime_buckets_event_id_distance(leak_fallback_db: Path) -> None: template = get_query("freed_block_lifetime") assert template is not None diff --git a/tests/test_api.py b/tests/test_api.py index a45c960..a049884 100644 --- a/tests/test_api.py +++ b/tests/test_api.py @@ -324,3 +324,10 @@ def test_get_database_overview(self, valid_db: Path) -> None: def test_get_database_overview_requires_focus(self) -> None: with pytest.raises(RuntimeError, match="No database configured"): SnapshotAnalyzer().get_database_overview() + + def test_get_database_overview_invalid_focus_file(self, tmp_path: Path) -> None: + focus_dir = tmp_path / ".pt-snap" + focus_dir.mkdir() + (focus_dir / "focus.json").write_text("not-json", encoding="utf-8") + with pytest.raises(ValueError): + SnapshotAnalyzer().get_database_overview() diff --git a/tests/test_cli_json.py b/tests/test_cli_json.py index e100caf..a12d76d 100644 --- a/tests/test_cli_json.py +++ b/tests/test_cli_json.py @@ -693,3 +693,47 @@ def test_overview_json_uses_success_envelope(sample_db: Path) -> None: def test_overview_json_error_uses_stderr_envelope() -> None: result = runner.invoke(app, ["overview", "--json"]) _assert_json_error(result, "FOCUS_NOT_CONFIGURED") + + +def test_capabilities_json_skill_catalog_error_uses_envelope( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + poison = tmp_path / "not-a-catalog" + poison.write_text("not a skill catalog", encoding="utf-8") + monkeypatch.setenv("PT_SNAP_SKILLS_DIR", str(poison)) + result = runner.invoke(app, ["capabilities", "--json"]) + _assert_json_error(result, "SKILL_ERROR") + + +def test_overview_json_missing_database_uses_envelope(tmp_path: Path) -> None: + result = runner.invoke(app, ["overview", str(tmp_path / "missing.db"), "--json"]) + _assert_json_error(result, "DATABASE_NOT_FOUND") + + +def test_overview_json_invalid_schema_uses_envelope(tmp_path: Path) -> None: + db_path = tmp_path / "no-dictionary.db" + conn = sqlite3.connect(str(db_path)) + conn.execute("CREATE TABLE other_table (id INTEGER PRIMARY KEY)") + conn.commit() + conn.close() + result = runner.invoke(app, ["overview", str(db_path), "--json"]) + _assert_json_error(result, "DATABASE_SCHEMA_INVALID") + + +def test_overview_json_missing_id_column_uses_envelope(tmp_path: Path) -> None: + db_path = tmp_path / "no-id.db" + conn = sqlite3.connect(str(db_path)) + conn.execute("CREATE TABLE dictionary (`table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT)") + conn.execute("CREATE TABLE trace_entry_0 (action INTEGER)") + conn.commit() + conn.close() + result = runner.invoke(app, ["overview", str(db_path), "--json"]) + _assert_json_error(result, "DATABASE_SCHEMA_INVALID") + + +def test_overview_json_invalid_focus_file_uses_envelope(tmp_path: Path) -> None: + focus_dir = tmp_path / ".pt-snap" + focus_dir.mkdir() + (focus_dir / "focus.json").write_text("not-json", encoding="utf-8") + result = runner.invoke(app, ["overview", "--json"]) + _assert_json_error(result, "FOCUS_FILE_INVALID") diff --git a/tests/test_context.py b/tests/test_context.py index 8135a8c..e77fa6d 100644 --- a/tests/test_context.py +++ b/tests/test_context.py @@ -119,6 +119,18 @@ def test_device_ids_discovery(self, valid_db: Path) -> None: ctx = Context(valid_db) assert ctx.device_ids == [0] + def test_device_ids_skip_non_numeric_suffix(self, tmp_path: Path) -> None: + db_path = tmp_path / "mixed.db" + conn = sqlite3.connect(str(db_path)) + conn.execute( + "CREATE TABLE dictionary (`table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT)" + ) + conn.execute("CREATE TABLE trace_entry_foo (id INTEGER PRIMARY KEY)") + conn.execute("CREATE TABLE trace_entry_0 (id INTEGER PRIMARY KEY)") + conn.commit() + conn.close() + assert Context(db_path).device_ids == [0] + def test_device_trace_bounds_empty_and_populated(self, valid_db: Path) -> None: ctx = Context(valid_db) assert ctx.device_trace_bounds() == [(0, None, None)] diff --git a/tests/test_contract_cli_api.py b/tests/test_contract_cli_api.py index a29b3d4..c36d6d7 100644 --- a/tests/test_contract_cli_api.py +++ b/tests/test_contract_cli_api.py @@ -664,3 +664,53 @@ def test_overview_contract_matches_cli_and_api_semantics(contract_db: Path) -> N assert payload["devices"] == api["devices"] assert payload["import_metadata"] == api["import_metadata"] assert payload["focus_source"] == "explicit" + + +def test_capabilities_template_matches_template_info_json(analyzer: SnapshotAnalyzer) -> None: + capabilities = _json_stdout(runner.invoke(app, ["capabilities", "--json"])) + info = _json_stdout( + runner.invoke(app, ["query", "--template-info", "preexisting_live", "--json"]) + ) + entry = next(item for item in capabilities["templates"] if item["name"] == "preexisting_live") + shared = {key: info[key] for key in entry} + assert shared == entry + assert analyzer.get_template_info("preexisting_live") == entry + + +def test_overview_error_contract_maps_four_domain_failures(tmp_path: Path) -> None: + missing = runner.invoke(app, ["overview", str(tmp_path / "missing.db"), "--json"]) + missing_error = json.loads(missing.stderr)["error"] + assert missing.exit_code == 1 + assert missing_error["code"] == "DATABASE_NOT_FOUND" + with pytest.raises(FileNotFoundError): + SnapshotAnalyzer().get_database_overview(str(tmp_path / "missing.db")) + + bad_db = tmp_path / "no-dictionary.db" + conn = sqlite3.connect(str(bad_db)) + conn.execute("CREATE TABLE other_table (id INTEGER PRIMARY KEY)") + conn.commit() + conn.close() + schema = runner.invoke(app, ["overview", str(bad_db), "--json"]) + schema_error = json.loads(schema.stderr)["error"] + assert schema.exit_code == 1 + assert schema_error["code"] == "DATABASE_SCHEMA_INVALID" + with pytest.raises(ValueError): + SnapshotAnalyzer().get_database_overview(str(bad_db)) + + focus_dir = tmp_path / ".pt-snap" + focus_dir.mkdir() + (focus_dir / "focus.json").write_text("not-json", encoding="utf-8") + invalid = runner.invoke(app, ["overview", "--json"]) + invalid_error = json.loads(invalid.stderr)["error"] + assert invalid.exit_code == 1 + assert invalid_error["code"] == "FOCUS_FILE_INVALID" + with pytest.raises(ValueError): + SnapshotAnalyzer().get_database_overview() + + (focus_dir / "focus.json").unlink() + unconfigured = runner.invoke(app, ["overview", "--json"]) + unconfigured_error = json.loads(unconfigured.stderr)["error"] + assert unconfigured.exit_code == 1 + assert unconfigured_error["code"] == "FOCUS_NOT_CONFIGURED" + with pytest.raises(RuntimeError, match="No database configured"): + SnapshotAnalyzer().get_database_overview()