diff --git a/docs/en/querying.md b/docs/en/querying.md index 14dba95..d30fa8b 100644 --- a/docs/en/querying.md +++ b/docs/en/querying.md @@ -177,7 +177,7 @@ live at `event_id` are also included: ### 3. Attribute active memory to callstacks at that event ```bash -pt-snap query --template-use active_memory_callstack_at_event --params '{"event_id": 1234, "include_static": true, "top_n": 20}' +pt-snap query --template-use active_memory_callstack_at_event --params '{"event_id": 1234, "include_static": true, "top_n": 20}' -n 22 --json ``` This query: @@ -188,8 +188,21 @@ This query: - emits static and preexisting memory as dedicated groups instead of inventing a callstack `top_n` only bounds dynamic callstack groups; `static` and -`preexisting_live_at_event` groups are always returned and are never pushed out -by larger dynamic groups. +`preexisting_live_at_event` groups, when included and present, are exempt from +that inner filter. The outer `-n` cap still applies to all output rows and can +drop special groups or dynamic top groups. For finite positive `top_n=N` with +`include_static=true`, use `-n N+2` (substitute the computed integer: `top_n=1` +needs `-n 3`, and `top_n=20` needs `-n 22`). This preserves the ranked result, +not necessarily the full dynamic set. The representative block query has its +own `limit` / `-n` cap; it does not need two extra rows. + +At fixed `top_n`, increasing `-n` preserves common rows and their percentages: +the denominator is the included groups' bytes after inner ranking but before +the outer row cap. A clipped listing need not sum to 100%. Increasing `top_n` +can change the denominator. Check completeness flags before claiming full +coverage; a full ranking window conservatively sets `has_more=true` even when +there are exactly N dynamic groups. Widen the window or use `--exact-total` +to resolve that uncertainty. ### 4. Compare peak event gaps across metrics @@ -283,7 +296,9 @@ use the [complete candidate window](#retrieving-a-complete-candidate-window) workflow above. Increasing `-n` replaces the earlier window rather than fetching a disjoint next page. `has_more` does not imply offset support. `active_memory_callstack_at_event` has no `offset`; `-n` cannot raise the -CTE `top_n` cap. Continue that template by increasing `top_n`. +CTE `top_n` cap. Widen that template by increasing `top_n`, keeping `-n` at +least `top_n + 2` with static inclusion. Replace the previous ranked result; +do not concatenate or sum overlapping windows. On `--json` failure, stdout is empty. stderr is: diff --git a/docs/en/snapshot-analyzer-api.md b/docs/en/snapshot-analyzer-api.md index a9694d0..728a526 100644 --- a/docs/en/snapshot-analyzer-api.md +++ b/docs/en/snapshot-analyzer-api.md @@ -174,8 +174,8 @@ The result contains: | --- | --- | | `total` | Matching-row `COUNT` when `exact_total=True`; otherwise the returned-row count | | `returned` | Number of rows included in `rows` | -| `has_more` | True when a later page exists (extra-row probe on a trailing `LIMIT`, or a full inner `top_n` window) | -| `truncated` | True when this response is not the complete matching set | +| `has_more` | True when more rows exist, or conservatively when an inner `top_n` window is full (even if exactly N groups exist) | +| `truncated` | True when this response is incomplete or completeness is unconfirmed by a full inner ranking window | | `total_is_exact` | True when `total` is a `COUNT`, or when the page is the complete matching set | | `timeout_s` | Effective execution timeout in seconds, or `None` when unbounded | | `device_id` | Device selected for execution | @@ -193,8 +193,14 @@ is a wall-clock budget for one `execute_query()` call in seconds (or `PT_SNAP_QUERY_TIMEOUT`); the page query and optional COUNT share it. The same environment variable applies to every template query, including `report peak-memory`. It does not change the row cap. Continue -`active_memory_callstack_at_event` by increasing `top_n`; `-n` cannot -raise that CTE cap. +`active_memory_callstack_at_event` by increasing `top_n`; `max_rows` (CLI `-n`) +cannot raise that CTE cap. For finite positive `top_n=N` with +`include_static=True`, set `max_rows=N+2` to retain up to two special groups +alongside the dynamic top N. This prevents outer truncation, not inner ranking +incompleteness. A full window alone does not prove more groups exist; widen it +or use `exact_total=True` to check. Replace earlier windows rather than summing +them. At fixed `top_n`, changing `max_rows` does not change common rows' +percentages; changing `top_n` can change their denominator. Rows contain raw SQLite values. Template `output_schema` metadata is not applied automatically; use the optional [ResultMapper API](result-mapper-api.md) when diff --git a/docs/zh/querying.md b/docs/zh/querying.md index 422b72c..98de48b 100644 --- a/docs/zh/querying.md +++ b/docs/zh/querying.md @@ -165,7 +165,7 @@ pt-snap query --template-use active_blocks_at_event --params '{"event_id": 1234, ### 3. 对该时刻的活跃内存做调用栈归因 ```bash -pt-snap query --template-use active_memory_callstack_at_event --params '{"event_id": 1234, "include_static": true, "top_n": 20}' +pt-snap query --template-use active_memory_callstack_at_event --params '{"event_id": 1234, "include_static": true, "top_n": 20}' -n 22 --json ``` 这个查询会: @@ -175,7 +175,18 @@ pt-snap query --template-use active_memory_callstack_at_event --params '{"event_ - 按分配调用栈做聚合 - 对静态内存和 preexisting 内存单独分组,而不是伪造调用栈 -`top_n` 只限制动态调用栈分组的数量;`static` 和 `preexisting_live_at_event` 分组始终返回,不会被更大的动态分组挤出结果。 +`top_n` 只限制动态调用栈分组的数量;启用包含且实际存在的 `static` 和 +`preexisting_live_at_event` 分组不受这层内部筛选限制。外层 `-n` 仍限制所有 +输出行,可能裁掉特殊组或动态 top 组。对于有限正整数 `top_n=N` 且 +`include_static=true`,使用 `-n N+2`(代入计算后的整数:`top_n=1` 配 +`-n 3`,`top_n=20` 配 `-n 22`)。这只保证排名结果不被二次裁剪,不保证 +动态全集完整。代表 block 查询有独立的 `limit` / `-n` 上限,不需要额外两行。 + +固定 `top_n` 时,增大 `-n` 不改变共有行及其百分比:分母是内部排名后、 +外层行数截断前所包含分组的字节数。裁剪后的列表百分比之和可能不足 100%。 +增大 `top_n` 则可能改变分母。宣称完整覆盖前应检查完整性标志;排名窗口已满 +会保守地设置 `has_more=true`,即使动态组恰好只有 N 个。扩大窗口或使用 +`--exact-total` 可消除这种不确定性。 ### 4. 比较不同指标的峰值与 gap @@ -260,7 +271,8 @@ QueryService 调用的共享预算(页面查询与可选 COUNT 共用),作 [完整候选窗口流程](#获取完整候选窗口)。增大 `-n` 是替换先前窗口,不是获取 不重叠的下一页。`has_more` 不代表支持 offset。 `active_memory_callstack_at_event` 没有 `offset`,`-n` -也无法突破 CTE 内的 `top_n`;该模板应增大 `top_n` 续页。 +也无法突破 CTE 内的 `top_n`;该模板应增大 `top_n` 扩大窗口,并在包含静态组时 +保持 `-n` 至少为 `top_n + 2`。新排名结果替换旧结果,不要拼接或累加重叠窗口。 `--json` 失败时 stdout 为空,stderr 为: diff --git a/docs/zh/snapshot-analyzer-api.md b/docs/zh/snapshot-analyzer-api.md index 4d5c5bf..08fa5b1 100644 --- a/docs/zh/snapshot-analyzer-api.md +++ b/docs/zh/snapshot-analyzer-api.md @@ -161,8 +161,8 @@ for row in result["rows"]: | --- | --- | | `total` | `exact_total=True` 时为匹配集合的 `COUNT`;否则等于已返回行数 | | `returned` | `rows` 中实际返回的行数 | -| `has_more` | 还有后续页时为 true(尾部 `LIMIT` 多取一行,或内部 `top_n` 窗口已满) | -| `truncated` | 本次响应不是完整匹配集合时为 true | +| `has_more` | 存在更多行时为 true;内部 `top_n` 窗口已满时也会保守地设为 true(即使恰好只有 N 个组) | +| `truncated` | 本次响应不完整,或内部排名窗口已满而完整性未确认时为 true | | `total_is_exact` | `total` 来自 `COUNT`,或本页就是完整匹配集合时为 true | | `timeout_s` | 生效的执行超时秒数;未限制时为 `None` | | `device_id` | 本次执行选择的设备 | @@ -178,8 +178,12 @@ analyzer 设备;未设置显式 analyzer 数据库时,再使用已解析项 `execute_query()` 调用的墙钟预算(秒),也可由 `PT_SNAP_QUERY_TIMEOUT` 提供;页面查询与可选 COUNT 共用该预算。该环境变量作用于所有模板查询, 包括 `report peak-memory`。它不改变行数上限。 -`active_memory_callstack_at_event` 应增大 `top_n` 续页,`-n` 无法突破 -CTE 上限。 +`active_memory_callstack_at_event` 应增大 `top_n` 扩大窗口,`max_rows`(CLI `-n`) +无法突破 CTE 上限。对于有限正整数 `top_n=N` 且 `include_static=True`,设置 +`max_rows=N+2` 可在动态 top N 之外保留最多两个特殊组。这可避免外层二次截断, +但不保证内部排名完整。窗口已满本身不证明存在更多组;扩大窗口或使用 +`exact_total=True` 可确认。新窗口替换旧窗口,不要累加。固定 `top_n` 时, +改变 `max_rows` 不改变共有行的百分比;改变 `top_n` 则可能改变分母。 查询行包含原始 SQLite 值,不会自动应用模板的 `output_schema` metadata。需要转换后的值 或模型映射时,使用可选的 [ResultMapper API](result-mapper-api.md)。 diff --git a/skills/pt-snap-memory-peak-breakdown/SKILL.md b/skills/pt-snap-memory-peak-breakdown/SKILL.md index df6ea65..f66ea2d 100644 --- a/skills/pt-snap-memory-peak-breakdown/SKILL.md +++ b/skills/pt-snap-memory-peak-breakdown/SKILL.md @@ -30,8 +30,16 @@ Require one coherent database/device pair: Also obtain: -- ``: maximum callstack groups and representative blocks. Default to 20 - only when the user has not requested another value. +- ``: finite positive dynamic callstack group cap (`top_n`, or report + `--limit`). Default to 20 only when the user has not requested another value. +- ``: total callstack query output row cap (`-n`). With + `include_static=true`, compute ` + 2` before command substitution to + reserve space for up to two special groups (20 dynamic groups → 22 rows; + 1 dynamic group → 3 rows). This prevents outer truncation of the ranked result, + but does not guarantee that all dynamic groups fit within `top_n`. +- ``: separate finite positive representative block cap (template + `limit` and `-n`). Default to 20 unless the user requests another value; the + callstack query's two extra rows do not apply to this block listing. - ``: the metric whose event needs representative blocks. If the user requests all three metrics, inspect each metric's own event. - Optional inclusive `` and `` for a bounded event range. @@ -46,9 +54,11 @@ observations. Validate every value before substituting it into a command: -- ``, ``, ``, ``, and every `` must +- ``, ``, ``, ``, ``, ``, and every `` must match `^[0-9]+$` after trimming whitespace. Reject any other value and ask the user or the query output again. +- Require ``, ``, and `` to be greater than zero. + Substitute the computed `` as decimal digits, not shell arithmetic. - Treat `` as an opaque filesystem path. Reject values containing quotes, `$`, backticks, or other shell metacharacters instead of escaping them. - Prefer argument-array execution where the host agent supports it; otherwise @@ -192,12 +202,12 @@ Use `active_blocks_at_event` at the chosen metric's peak event, not at the end o the trace and not at another metric's event: ```bash -pt-snap query "" --device --template-use active_blocks_at_event --params '{"event_id": , "include_static": true, "limit": }' -n +pt-snap query "" --device --template-use active_blocks_at_event --params '{"event_id": , "include_static": true, "limit": }' -n --json ``` If all three peaks need block examples, run this once per distinct metric event and label the event/metric association. Reuse results when metrics share an -event. Prefer `--json`. Keep `` and `-n` positive; if `has_more` or +event. Keep `` and `-n` positive; if `has_more` or `truncated` is true, do not treat the listing as complete. Default `total` equals `returned` unless `--exact-total` is set. @@ -221,14 +231,24 @@ Choose the requested metric's returned event, then run point-in-time attribution there: ```bash -pt-snap query "" --device --template-use active_memory_callstack_at_event --params '{"event_id": , "include_static": true, "top_n": }' -n -pt-snap query "" --device --template-use active_blocks_at_event --params '{"event_id": , "include_static": true, "limit": }' -n +pt-snap query "" --device --template-use active_memory_callstack_at_event --params '{"event_id": , "include_static": true, "top_n": }' -n --json +pt-snap query "" --device --template-use active_blocks_at_event --params '{"event_id": , "include_static": true, "limit": }' -n --json ``` `active_memory_callstack_at_event` has no `offset`, and `-n` cannot raise the -CTE `top_n` cap. If `has_more` or `truncated` is true on that template, -increase `top_n` (keep `-n` at least as large) instead of treating the ranked -page as the full dynamic set. +CTE `top_n` cap. Check `has_more`, `truncated`, and `total_is_exact` after every +query. If completeness is unconfirmed, first ensure `-n` is at least `top_n + 2` +with static inclusion, then increase `top_n` and recompute `` when +full dynamic coverage is needed. A full ranking window sets `has_more=true` +conservatively: it does not prove that more groups exist. Widen the window or +use `--exact-total` to resolve that uncertainty; a count equal to `returned` +can clear the signal. Each wider query replaces the earlier ranked window; +do not concatenate or sum overlapping results. + +At fixed `top_n`, raising `-n` preserves common rows and their percentages. +The percentage denominator includes the inner-ranked groups before the outer +row cap, so a clipped listing need not sum to 100%. Increasing `top_n` can +change that denominator; do not carry percentages across ranking windows. The selected event must be one returned by the bounded `memory_peak` and `allocator_gap` results. The point-in-time queries do not accept range bounds; @@ -266,10 +286,12 @@ their event ID carries the range selection forward. treat those as unknown dynamic attribution rather than dropping them. Use `category` to distinguish synthetic groups; a display label alone is not a unique group identity (captured literal labels remain separate). -- The callstack template always returns `static` and - `preexisting_live_at_event` groups regardless of `top_n`; when dynamic groups - exceed `top_n`, the smallest dynamic groups are dropped while these special - groups remain in the output. +- With `include_static=true`, eligible `static` and + `preexisting_live_at_event` groups are exempt from the inner `top_n` filter. + This is not an exemption from the outer `-n` row cap, which can drop special + groups or dynamic top groups according to the final size ordering. Reserve + up to two extra output rows using ``; absent special categories + are not fabricated. ### Claims @@ -289,7 +311,8 @@ their event ID carries the range selection forward. Return a concise report with these sections: 1. **Scope**: absolute SnapshotDB path, device, full trace or inclusive event - range, static inclusion, limit, and selected metric/event. + range, static inclusion, dynamic group cap, total group row cap, + representative block cap, completeness flags, and selected metric/event. 2. **Separate peaks**: active, allocated, and reserved values with each metric's own earliest peak event ID. 3. **Same-event gaps**: counters and `reserved - active` / `reserved - allocated` @@ -324,5 +347,5 @@ and do not run point-in-time attribution with a fabricated event ID. callstack strings. - Do not turn point-in-time active-block attribution into leak, fragmentation, cache-ownership, or OOM root-cause claims. -- Keep listing queries bounded with `` and `-n`. Prefer `--json` and do +- Keep listing queries bounded with their separate group/block caps and `-n`. Prefer `--json` and do not treat a page as complete when `has_more` or `truncated` is true. diff --git a/src/pt_snap_cli/bundled_skills/pt-snap-memory-peak-breakdown/SKILL.md b/src/pt_snap_cli/bundled_skills/pt-snap-memory-peak-breakdown/SKILL.md index df6ea65..f66ea2d 100644 --- a/src/pt_snap_cli/bundled_skills/pt-snap-memory-peak-breakdown/SKILL.md +++ b/src/pt_snap_cli/bundled_skills/pt-snap-memory-peak-breakdown/SKILL.md @@ -30,8 +30,16 @@ Require one coherent database/device pair: Also obtain: -- ``: maximum callstack groups and representative blocks. Default to 20 - only when the user has not requested another value. +- ``: finite positive dynamic callstack group cap (`top_n`, or report + `--limit`). Default to 20 only when the user has not requested another value. +- ``: total callstack query output row cap (`-n`). With + `include_static=true`, compute ` + 2` before command substitution to + reserve space for up to two special groups (20 dynamic groups → 22 rows; + 1 dynamic group → 3 rows). This prevents outer truncation of the ranked result, + but does not guarantee that all dynamic groups fit within `top_n`. +- ``: separate finite positive representative block cap (template + `limit` and `-n`). Default to 20 unless the user requests another value; the + callstack query's two extra rows do not apply to this block listing. - ``: the metric whose event needs representative blocks. If the user requests all three metrics, inspect each metric's own event. - Optional inclusive `` and `` for a bounded event range. @@ -46,9 +54,11 @@ observations. Validate every value before substituting it into a command: -- ``, ``, ``, ``, and every `` must +- ``, ``, ``, ``, ``, ``, and every `` must match `^[0-9]+$` after trimming whitespace. Reject any other value and ask the user or the query output again. +- Require ``, ``, and `` to be greater than zero. + Substitute the computed `` as decimal digits, not shell arithmetic. - Treat `` as an opaque filesystem path. Reject values containing quotes, `$`, backticks, or other shell metacharacters instead of escaping them. - Prefer argument-array execution where the host agent supports it; otherwise @@ -192,12 +202,12 @@ Use `active_blocks_at_event` at the chosen metric's peak event, not at the end o the trace and not at another metric's event: ```bash -pt-snap query "" --device --template-use active_blocks_at_event --params '{"event_id": , "include_static": true, "limit": }' -n +pt-snap query "" --device --template-use active_blocks_at_event --params '{"event_id": , "include_static": true, "limit": }' -n --json ``` If all three peaks need block examples, run this once per distinct metric event and label the event/metric association. Reuse results when metrics share an -event. Prefer `--json`. Keep `` and `-n` positive; if `has_more` or +event. Keep `` and `-n` positive; if `has_more` or `truncated` is true, do not treat the listing as complete. Default `total` equals `returned` unless `--exact-total` is set. @@ -221,14 +231,24 @@ Choose the requested metric's returned event, then run point-in-time attribution there: ```bash -pt-snap query "" --device --template-use active_memory_callstack_at_event --params '{"event_id": , "include_static": true, "top_n": }' -n -pt-snap query "" --device --template-use active_blocks_at_event --params '{"event_id": , "include_static": true, "limit": }' -n +pt-snap query "" --device --template-use active_memory_callstack_at_event --params '{"event_id": , "include_static": true, "top_n": }' -n --json +pt-snap query "" --device --template-use active_blocks_at_event --params '{"event_id": , "include_static": true, "limit": }' -n --json ``` `active_memory_callstack_at_event` has no `offset`, and `-n` cannot raise the -CTE `top_n` cap. If `has_more` or `truncated` is true on that template, -increase `top_n` (keep `-n` at least as large) instead of treating the ranked -page as the full dynamic set. +CTE `top_n` cap. Check `has_more`, `truncated`, and `total_is_exact` after every +query. If completeness is unconfirmed, first ensure `-n` is at least `top_n + 2` +with static inclusion, then increase `top_n` and recompute `` when +full dynamic coverage is needed. A full ranking window sets `has_more=true` +conservatively: it does not prove that more groups exist. Widen the window or +use `--exact-total` to resolve that uncertainty; a count equal to `returned` +can clear the signal. Each wider query replaces the earlier ranked window; +do not concatenate or sum overlapping results. + +At fixed `top_n`, raising `-n` preserves common rows and their percentages. +The percentage denominator includes the inner-ranked groups before the outer +row cap, so a clipped listing need not sum to 100%. Increasing `top_n` can +change that denominator; do not carry percentages across ranking windows. The selected event must be one returned by the bounded `memory_peak` and `allocator_gap` results. The point-in-time queries do not accept range bounds; @@ -266,10 +286,12 @@ their event ID carries the range selection forward. treat those as unknown dynamic attribution rather than dropping them. Use `category` to distinguish synthetic groups; a display label alone is not a unique group identity (captured literal labels remain separate). -- The callstack template always returns `static` and - `preexisting_live_at_event` groups regardless of `top_n`; when dynamic groups - exceed `top_n`, the smallest dynamic groups are dropped while these special - groups remain in the output. +- With `include_static=true`, eligible `static` and + `preexisting_live_at_event` groups are exempt from the inner `top_n` filter. + This is not an exemption from the outer `-n` row cap, which can drop special + groups or dynamic top groups according to the final size ordering. Reserve + up to two extra output rows using ``; absent special categories + are not fabricated. ### Claims @@ -289,7 +311,8 @@ their event ID carries the range selection forward. Return a concise report with these sections: 1. **Scope**: absolute SnapshotDB path, device, full trace or inclusive event - range, static inclusion, limit, and selected metric/event. + range, static inclusion, dynamic group cap, total group row cap, + representative block cap, completeness flags, and selected metric/event. 2. **Separate peaks**: active, allocated, and reserved values with each metric's own earliest peak event ID. 3. **Same-event gaps**: counters and `reserved - active` / `reserved - allocated` @@ -324,5 +347,5 @@ and do not run point-in-time attribution with a fabricated event ID. callstack strings. - Do not turn point-in-time active-block attribution into leak, fragmentation, cache-ownership, or OOM root-cause claims. -- Keep listing queries bounded with `` and `-n`. Prefer `--json` and do +- Keep listing queries bounded with their separate group/block caps and `-n`. Prefer `--json` and do not treat a page as complete when `has_more` or `truncated` is true. diff --git a/tests/query/test_query_completeness.py b/tests/query/test_query_completeness.py index 245eb88..e98c1aa 100644 --- a/tests/query/test_query_completeness.py +++ b/tests/query/test_query_completeness.py @@ -5,12 +5,14 @@ import json import sqlite3 import time +from contextlib import closing from pathlib import Path from unittest.mock import patch import pytest from typer.testing import CliRunner +from pt_snap_cli.api import SnapshotAnalyzer from pt_snap_cli.cli import app from pt_snap_cli.config import Config from pt_snap_cli.context import Context @@ -92,8 +94,8 @@ def _trace_db(tmp_path: Path, rows: list[tuple[int, int, int]]) -> Path: return db_path -def _ranked_callstack_db(tmp_path: Path, dynamic_count: int = 4) -> Path: - """v1 SnapshotDB with ``dynamic_count`` live callstack groups plus specials.""" +def _ranked_callstack_db(tmp_path: Path, dynamic_count: int = 4, layout: str = "v1") -> Path: + """SnapshotDB with ``dynamic_count`` live callstack groups plus specials.""" db_path = tmp_path / "ranked.db" conn = sqlite3.connect(str(db_path)) conn.execute("CREATE TABLE dictionary (`table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT)") @@ -147,6 +149,12 @@ def _ranked_callstack_db(tmp_path: Path, dynamic_count: int = 4) -> Path: """, blocks, ) + if layout == "v2": + conn.execute("CREATE TABLE callstack (id INTEGER PRIMARY KEY, callstack TEXT)") + conn.execute("INSERT INTO callstack SELECT id, callstack FROM trace_entry_0") + conn.execute("ALTER TABLE trace_entry_0 ADD COLUMN callstackId INTEGER") + conn.execute("UPDATE trace_entry_0 SET callstackId = id") + conn.execute("ALTER TABLE trace_entry_0 DROP COLUMN callstack") conn.commit() conn.close() return db_path @@ -412,6 +420,103 @@ def test_top_n_window_is_not_reported_complete_by_default(tmp_path: Path) -> Non assert exact_full_window.total_is_exact is True +@pytest.mark.parametrize("layout", ["v1", "v2"]) +@pytest.mark.parametrize("top_n", [1, 20]) +@pytest.mark.parametrize("extra_groups", [0, 1], ids=["exact-window", "overflow"]) +@pytest.mark.parametrize("large_specials", [False, True], ids=["specials-last", "specials-first"]) +def test_peak_group_row_cap_preserves_ranked_rows_and_denominator( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + layout: str, + top_n: int, + extra_groups: int, + large_specials: bool, +) -> None: + """The skill's N+2 outer cap preserves inner top N plus both special groups.""" + monkeypatch.setattr(Path, "home", lambda: tmp_path) + dynamic_count = top_n + extra_groups + db_path = _ranked_callstack_db(tmp_path, dynamic_count, layout) + if large_specials: + with closing(sqlite3.connect(db_path)) as conn, conn: + conn.execute("UPDATE block_0 SET size = 100000, requestedSize = 100000 WHERE id = -10") + conn.execute("UPDATE block_0 SET size = 40000, requestedSize = 40000 WHERE id = -11") + + with SnapshotAnalyzer(db_path, device_id=0) as analyzer: + + def query(rank_cap: int, row_cap: int, exact: bool = False) -> dict: + params = {"event_id": 50, "include_static": True, "top_n": rank_cap} + args = [ + "query", + str(db_path), + "--device", + "0", + "--template-use", + "active_memory_callstack_at_event", + "--params", + json.dumps(params), + "-n", + str(row_cap), + "--json", + ] + if exact: + args.append("--exact-total") + result = runner.invoke(app, args) + assert result.exit_code == 0, result.output + payload = json.loads(result.stdout) + api = analyzer.execute_query( + "active_memory_callstack_at_event", + params=params, + max_rows=row_cap, + exact_total=exact, + ) + for key in ("rows", "returned", "total", "has_more", "truncated", "total_is_exact"): + assert payload[key] == api[key] + return payload + + clipped = query(top_n, top_n) + ranked = query(top_n, top_n + 2) + counted = query(top_n, top_n + 2, exact=True) + widened = query(top_n + 2, top_n + 4) + + assert clipped["returned"] == top_n + assert clipped["rows"] == ranked["rows"][:top_n] + if top_n == 1: + assert clipped["rows"][0]["category"] == ( + "static" if large_specials else "dynamic_live_at_event" + ) + categories = [row["category"] for row in ranked["rows"]] + assert categories.count("dynamic_live_at_event") == top_n + assert categories.count("static") == categories.count("preexisting_live_at_event") == 1 + assert ranked["returned"] == top_n + 2 + ranked_bytes = sum(row["size_bytes"] for row in ranked["rows"]) + expected_bytes = 1000 * sum(range(extra_groups + 1, dynamic_count + 1)) + expected_bytes += 140000 if large_specials else 90 + assert ranked_bytes == expected_bytes + for row in ranked["rows"]: + assert row["percent_of_active_blocks"] == pytest.approx( + round(100 * row["size_bytes"] / expected_bytes, 4) + ) + assert sum(row["percent_of_active_blocks"] for row in ranked["rows"]) == pytest.approx( + 100, abs=0.002 + ) + assert sum(row["percent_of_active_blocks"] for row in clipped["rows"]) < 100 + # A full inner window is conservative even when it contains every dynamic group. + for payload in (clipped, ranked): + assert payload["has_more"] is True + assert payload["truncated"] is True + assert payload["total_is_exact"] is False + assert payload["total"] == payload["returned"] + assert counted["rows"] == ranked["rows"] + assert counted["total"] == dynamic_count + 2 + assert counted["total_is_exact"] is True + assert counted["has_more"] is bool(extra_groups) + assert counted["truncated"] is bool(extra_groups) + assert widened["returned"] == dynamic_count + 2 + assert widened["has_more"] is widened["truncated"] is False + assert widened["total_is_exact"] is True + assert not (tmp_path / ".pt-snap").exists() + + def test_inner_top_n_without_category_uses_row_count(tmp_path: Path) -> None: db_path = _trace_db(tmp_path, [(1, 0x1000, 100), (2, 0x2000, 100), (3, 0x3000, 50)]) Config().write_project_focus(db_path, device_id=0) diff --git a/tests/skills/test_memory_peak_breakdown_contract.py b/tests/skills/test_memory_peak_breakdown_contract.py index 2065e53..674f568 100644 --- a/tests/skills/test_memory_peak_breakdown_contract.py +++ b/tests/skills/test_memory_peak_breakdown_contract.py @@ -48,7 +48,8 @@ def test_skill_references_current_report_and_templates() -> None: assert f" {name}:" in path.read_text(encoding="utf-8") assert f"`{name}`" in skill.split("## Full-Trace Workflow")[0] assert "has_more" in skill - assert "-n " in skill + assert "-n --json" in skill + assert "-n --json" in skill assert "increase `top_n`" in skill @@ -157,7 +158,7 @@ def test_range_fallback_and_peak_event_semantics_are_explicit() -> None: assert "Never fabricate an event ID,\nsubstitute a full-trace value" in skill -def test_preexisting_live_blocks_are_attributed_and_exempt_from_truncation() -> None: +def test_special_groups_are_exempt_only_from_inner_ranking() -> None: normalized = _normalized_skill() assert "Attribution covers three categories returned by the templates" in _skill() @@ -166,11 +167,26 @@ def test_preexisting_live_blocks_are_attributed_and_exempt_from_truncation() -> ) assert "no captured allocation event" in normalized assert "Keep `static`, `preexisting_live_at_event`, and `dynamic_live_at_event`" in _skill() + assert "groups are exempt from the inner `top_n` filter" in normalized + assert "not an exemption from the outer `-n` row cap" in normalized + assert "absent special categories are not fabricated" in normalized + + +def test_group_and_block_caps_and_conservative_completeness_are_distinct() -> None: + skill = _skill() + normalized = _normalized_skill() + + assert '"top_n": }\' -n --json' in skill + assert '"limit": }\' -n --json' in skill + assert "compute ` + 2` before command substitution" in normalized + assert "20 dynamic groups → 22 rows; 1 dynamic group → 3 rows" in normalized + assert "does not guarantee that all dynamic groups fit within `top_n`" in normalized + assert "does not prove that more groups exist" in normalized + assert "use `--exact-total` to resolve that uncertainty" in normalized assert ( - "always returns `static` and `preexisting_live_at_event` groups regardless of `top_n`" - in normalized + "At fixed `top_n`, raising `-n` preserves common rows and their percentages" in normalized ) - assert "the smallest dynamic groups are dropped while these special groups remain" in normalized + assert "do not concatenate or sum overlapping results" in normalized def test_attribution_caveats_prevent_reserved_and_static_overclaim() -> None: