diff --git a/docs/en/querying.md b/docs/en/querying.md index 60d92ed..776a946 100644 --- a/docs/en/querying.md +++ b/docs/en/querying.md @@ -148,13 +148,18 @@ marked, never guessed by address/local stack ID and never asserted as proved lea Dataset reads detach batches before foreign-owner lookups, using the borrowed bounded Context LRU. One diminishing deadline includes all shards, sources, grouping and exact -totals; reports explicitly share **one** budget across their three queries. Cumulative +totals; reports explicitly share **one** budget across peak selection and attribution. Cumulative fetched/output work is limited to **100000 rows / 64 MiB serialized values**, including repeated source reads. Exceeding either fails the entire operation, never an alleged complete partial result. Materialization/sort are bounded by this work ceiling, **not** by max_rows. This is not a process RSS limit: Python/SQLite, one batch and individual -cells have overhead. Manifest hashing/validation remains proportional to artifact size -and phase-checked, not hard-preempted. No temporary merge DB, repair or artifact write. +cells have overhead. Strong manifest/member validation and hashing remain the default +and share that deadline: hash chunks, Python row batches and SQLite progress handlers +check cancellation. Individual filesystem calls are not OS-level hard-preempted. +`PT_SNAP_DATASET_CACHE=immutable` explicitly opts into process-local validation reuse +only when the caller guarantees immutable finalized files and reliable filesystem +change times; see [dataset validation and cache contracts](sharded-snapshotdb.md). +No temporary merge DB, repair or artifact write. ## Dataset point-event attribution @@ -209,9 +214,10 @@ bytes **after dynamic top_n but before max_rows**, not the dataset active counte Exact totals ignore row/rank caps, but do not change that percentage denominator. One call shares its deadline across source batches, grouping and exact totals. -Manifest validation/hash and Context setup elapsed time are charged, but synchronous -filesystem I/O/validation is checked at phase boundaries, not hard-preempted; no -OS-level time guarantee is claimed. SQL uses cleared-on-exit progress handlers. +Manifest validation/hash and Context setup elapsed time are charged. Validation checks +cancellation between hash chunks and Python row batches, and within SQLite via +cleared-on-exit progress handlers. Individual filesystem calls are not hard-preempted; +no OS-level time guarantee is claimed. The Context LRU remains bounded (default four) and borrowed caches remain caller-owned. No merged temporary database is created. `ReportService.event_attribution(E, ...)` reuses this same query path for a supplied event. Dataset-global queries and reports @@ -454,17 +460,23 @@ pt-snap report peak-memory /path/to/snapshot.db --json The report command combines: -- `memory_peak` -- `allocator_gap` +- `allocator_gap`, whose result also supplies the six existing `peak_*` fields - `active_memory_callstack_at_event` and prints either a human-readable summary or JSON. `--start-id/--end-id` restrict peak selection; attribution still resolves the complete active set at that selected event, including earlier allocations. `--timeout` (or `PT_SNAP_QUERY_TIMEOUT`) is -one diminishing **report-wide** deadline, not three reset per-query timeouts. +one diminishing **report-wide** deadline, never reset between queries. JSON adds peak `scope`, separate attribution `source_coverage`, `timeout_s`, and `budget_scope="report_composition"`. +A dataset report inspects the dataset once and reuses that validated fingerprint +for peak selection and attribution. Changes to the manifest or members detected +between or during these steps reject the whole report; this is a generation check, +not a concurrent-writer lock. Counter peaks are computed once for the selected +range. Attribution still consumes the same cumulative work budget, so a very large +active set can legitimately exceed that budget even when a peak-only query succeeds. + The existing `callstack_groups` and `percent_of_active_blocks` values are preserved. JSON also exposes attribution `has_more`, `truncated`, `total_is_exact`, and `effective_params` (`event_id`, `include_static`, `min_size`, `top_n`). A full diff --git a/docs/en/sharded-snapshotdb.md b/docs/en/sharded-snapshotdb.md index a0e59b5..53f7ae4 100644 --- a/docs/en/sharded-snapshotdb.md +++ b/docs/en/sharded-snapshotdb.md @@ -245,10 +245,8 @@ addresses all matching files even for a cross-slice range, but does not execute By default **every independent inspection** fully validates the finalized contract and hashes the manifest/members. File metadata alone is not content-integrity proof: unknown or coarse filesystems may expose unchanged `ctime_ns` after a write. -Each query, including each query step within a multi-step report, calls `inspect` -again. Reports do not currently pin one `ResolvedDataset` across their steps or -invoke `ResolvedDataset.require_unchanged()`; there is no additional report-level -content-hash guard. +Pinned report-operation guards also rehash content by default, without repeating +row validation. `PT_SNAP_DATASET_CACHE=immutable` explicitly opts into a process-wide LRU of at most 16 validated generations, without open connections. Set it only when you control @@ -260,14 +258,13 @@ the tool. Unset it to retain strong validation; unknown values also use strong m Windows and platforms without a usable POSIX change token remain in strong mode. With that explicit opt-in, new resolver/service instances can reuse validated -results. Every cache hit during inspection still rechecks canonical paths, +results. Every hit and pinned-operation guard still rechecks canonical paths, sidecars, native membership and each file's device, inode, size, mtime, **ctime**, mode and link count. These conservative checks catch ordinary replacements and in-place edits with restored mtime, but do not replace the immutable-file contract. For a fixed shard count, an opted-in hit performs no row scans or whole-file hashes: -work is O(shards), independent of event/block counts. This metadata-only reuse also -applies to report query steps; a cache hit does not rehash content. Default inspections -and cache misses remain proportional to content. Explicit `validate_dataset` / +work is O(shards), independent of event/block counts. Default inspections and cache +misses remain proportional to content. Explicit `validate_dataset` / `validate_native_dataset` calls always validate fully. Native admission verifies hashes before and after validation and reuses the verified hashes for its fingerprint, avoiding a third member-hash pass. diff --git a/docs/zh/querying.md b/docs/zh/querying.md index 69c243e..473d1e8 100644 --- a/docs/zh/querying.md +++ b/docs/zh/querying.md @@ -128,11 +128,14 @@ exactness 标记诚实。`has_more/truncated` 描述窗口,不表示来源/范 独立。未证明历史身份按片局部单独表达,不按地址/局部栈 ID 猜合并,不断言为已证明泄漏。 数据集读取先分离批次再查外片来源,使用借用的有界 Context LRU。所有片、来源、分组、 -精确总数共用递减 deadline;报告三条查询明确共用**一个**预算。累计取回/输出工作上限为 +精确总数共用递减 deadline;报告的峰值选择与归因明确共用**一个**预算。累计取回/输出工作上限为 **100000 行 / 64 MiB 序列化值**,含重复来源读取;超限整体失败,不返回冒充完整的部分 结论。物化/排序由工作上限约束,**不由 max_rows 约束**;不是进程 RSS 上限,Python/ -SQLite、一个批次及单个 cell 有额外开销。manifest hash/校验仍与产物大小成正比且仅在 -阶段边界检查,不硬抢占。不生成合并临时 DB、不修复或写产物。 +SQLite、一个批次及单个 cell 有额外开销。默认仍对 manifest/成员执行完整校验和 hash, +并共用该 deadline:hash 分块、Python 行批次及 SQLite progress handler 都检查取消。 +单个文件系统调用不提供 OS 级硬抢占。仅当调用方保证最终产物不可变且文件系统变更时间 +可靠时,才可通过 `PT_SNAP_DATASET_CACHE=immutable` 显式启用进程内校验复用;参见 +[数据集校验与缓存合同](sharded-snapshotdb.md)。不生成合并临时 DB、不修复或写产物。 ## 数据集定点事件归因 @@ -176,8 +179,9 @@ max_rows 之前**所含字节,不是数据集 active 计数器。精确总数 不改变百分比分母。 一次调用的来源批次、分组和精确总数共用 deadline。manifest 校验/hash 及 Context -设置耗时计入预算,但同步文件 I/O/校验只在阶段边界检查,不硬抢占,不保证 OS 级 -时间上限。SQL progress handler 退出即清除。Context LRU 有界(默认四个),借用 +设置耗时计入预算。校验在 hash 分块与 Python 行批次之间检查取消,SQLite 通过退出即 +清除的 progress handler 检查取消。单个文件系统调用不硬抢占,不保证 OS 级时间上限。 +Context LRU 有界(默认四个),借用 cache 仍由调用者所有。不生成合并临时数据库。`ReportService.event_attribution(E, ...)` 对给定事件复用同一路径。数据集全局查询及报告遵循上文明确支持矩阵;任意 SQL/ 自定义 override 不会因使用内建名字就继承全局合并语义。 @@ -397,15 +401,19 @@ pt-snap report peak-memory /path/to/snapshot.db --json 这个 report 命令会组合: -- `memory_peak` -- `allocator_gap` +- `allocator_gap`,其结果同时提供原有的六个 `peak_*` 字段 - `active_memory_callstack_at_event` 并输出人类可读摘要或 JSON。`--start-id/--end-id` 限制峰值选择;归因仍解析所选事件 完整活跃集合,包含更早分配。`--timeout`(或 `PT_SNAP_QUERY_TIMEOUT`)是递减的 -**报告整体** deadline,不是重置三次的逐查询超时。JSON 新增峰值 `scope`、独立归因 +**报告整体** deadline,不会在查询之间重置。JSON 新增峰值 `scope`、独立归因 `source_coverage`、`timeout_s` 与 `budget_scope="report_composition"`。 +数据集报告只检查一次数据集,峰值选择与归因复用同一个已验证 fingerprint。 +若在步骤之间或执行期间检测到 manifest 或成员变化,整个报告会失败;这是版本检查, +不是并发写入锁。所选区间只计算一次 counter 峰值。归因仍消耗同一个累计工作预算, +因此活跃集合很大时,即使单独峰值查询成功,报告仍可能合理地超出预算。 + 原有 `callstack_groups` 和 `percent_of_active_blocks` 数值保持不变。JSON 还会 返回归因的 `has_more`、`truncated`、`total_is_exact` 和 `effective_params` (`event_id`、`include_static`、`min_size`、`top_n`)。动态分组恰好填满 `top_n` diff --git a/docs/zh/sharded-snapshotdb.md b/docs/zh/sharded-snapshotdb.md index ad3c1d1..c2ee244 100644 --- a/docs/zh/sharded-snapshotdb.md +++ b/docs/zh/sharded-snapshotdb.md @@ -200,9 +200,7 @@ selector。输出 `scope` 标识实际 DB/device/slice、受限真实区间、 (单库返回 `None`);其 `paths(QueryScope(...))` 可寻址跨片范围的全部文件,但不执行查询。 默认**每次独立 inspect 都完整校验**最终化合同,并对 manifest/成员取内容哈希。文件元数据 本身不是内容完整性证明:未知或低精度文件系统可能在写入后仍返回相同 `ctime_ns`。 -每次查询(包括多步报告中的每个查询步骤)都会再次调用 `inspect`。报告目前不会跨步骤 -固定同一个 `ResolvedDataset`,也不会调用 `ResolvedDataset.require_unchanged()`; -没有额外的报告级内容哈希守卫。 +已固定 generation 的报告操作默认也重新哈希内容,但不重复逐行校验。 `PT_SNAP_DATASET_CACHE=immutable` 显式启用最多 16 个已校验 generation 的进程级 LRU, 不保留连接。仅在你控制最终化、不可变发布,且信任文件系统内核 change-time 语义时启用。 @@ -210,12 +208,11 @@ selector。输出 `scope` 标识实际 DB/device/slice、受限真实区间、 不得启用**。这是调用方责任合同,不代表工具已检测文件系统能力。不设置该变量即保留强校验, 未知取值也使用强校验;Windows 或没有可用 POSIX change token 的平台始终使用强校验。 -显式启用后,新建 resolver/service 可复用已校验结果。每次 inspect 缓存命中仍验证 +显式启用后,新建 resolver/service 可复用已校验结果。每次命中及报告 generation 检查仍验证 规范路径、sidecar、原生成员集合,以及文件的设备号、inode、size、mtime、**ctime**、mode 和硬链接数。这些保守检查可检测常规替换及恢复 mtime 的原地修改,但不能代替不可变文件 合同。固定分片数时,显式启用后的命中不扫描行、不做整文件哈希,工作量为 O(分片数), -不随 event/block 数增长。报告中的查询步骤也适用这种仅检查元数据的复用;命中时不会 -重新哈希内容。默认 inspect 及未命中仍与内容规模成正比。显式 `validate_dataset` +不随 event/block 数增长。默认 inspect 及未命中仍与内容规模成正比。显式 `validate_dataset` / `validate_native_dataset` 始终完整校验。原生准入保留校验前后两遍哈希,fingerprint 直接 复用已验证摘要,不再做第三遍成员哈希。 diff --git a/skills/pt-snap-memory-peak-breakdown/SKILL.md b/skills/pt-snap-memory-peak-breakdown/SKILL.md index 1d7a275..791ec41 100644 --- a/skills/pt-snap-memory-peak-breakdown/SKILL.md +++ b/skills/pt-snap-memory-peak-breakdown/SKILL.md @@ -244,19 +244,25 @@ pt-snap report peak-memory "" --device --metric reserved --include- Keep the JSON in the response. The report composes these product templates: -- `memory_peak` finds the active, allocated, and reserved peak values and event - IDs. -- `allocator_gap` returns each metric's counters and gaps at that same metric's - peak event. +- `allocator_gap` runs once to find the active, allocated, and reserved peak + values and event IDs, plus each metric's same-event counters and gaps. The + report projects its six-field `peak` section from this result, preserving + `memory_peak` semantics without running a separate `memory_peak` query. - `active_memory_callstack_at_event` groups blocks active at the report's selected metric event by allocation callstack. -From the three results, record each metric's own peak value and event ID. Peak -ties resolve to the earliest event ID. Record same-event counters and gaps from +Both steps share one resolved database/device, budget, and dataset generation. +If the selected metric has no peak value or event ID, the report returns empty +attribution without running the attribution query; never invent an event for an +empty range or an all-NULL counter. Other metrics can still have valid peaks. + +From the three metric reports, record each metric's own peak value and event ID. +Peak ties resolve to the earliest event ID. Record same-event counters and gaps from `allocator_gap`; never subtract independently occurring peak values as if they -occurred together. The repeated `peak` and `allocator_gap` sections should agree -across all three reports; the metric-specific `event_id` and `callstack_groups` -are the selected-event breakdown. +occurred together. The repeated `peak` sections should agree across all three +reports. For metrics with a valid peak, the `allocator_gap` sections also agree; +an empty-attribution report has `allocator_gap: null`. The metric-specific +`event_id` and `callstack_groups` are the selected-event breakdown. Read report `has_more`, `truncated`, `total_is_exact`, and `effective_params` before claiming a complete composition. A full dynamic `top_n` window means 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 1d7a275..791ec41 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 @@ -244,19 +244,25 @@ pt-snap report peak-memory "" --device --metric reserved --include- Keep the JSON in the response. The report composes these product templates: -- `memory_peak` finds the active, allocated, and reserved peak values and event - IDs. -- `allocator_gap` returns each metric's counters and gaps at that same metric's - peak event. +- `allocator_gap` runs once to find the active, allocated, and reserved peak + values and event IDs, plus each metric's same-event counters and gaps. The + report projects its six-field `peak` section from this result, preserving + `memory_peak` semantics without running a separate `memory_peak` query. - `active_memory_callstack_at_event` groups blocks active at the report's selected metric event by allocation callstack. -From the three results, record each metric's own peak value and event ID. Peak -ties resolve to the earliest event ID. Record same-event counters and gaps from +Both steps share one resolved database/device, budget, and dataset generation. +If the selected metric has no peak value or event ID, the report returns empty +attribution without running the attribution query; never invent an event for an +empty range or an all-NULL counter. Other metrics can still have valid peaks. + +From the three metric reports, record each metric's own peak value and event ID. +Peak ties resolve to the earliest event ID. Record same-event counters and gaps from `allocator_gap`; never subtract independently occurring peak values as if they -occurred together. The repeated `peak` and `allocator_gap` sections should agree -across all three reports; the metric-specific `event_id` and `callstack_groups` -are the selected-event breakdown. +occurred together. The repeated `peak` sections should agree across all three +reports. For metrics with a valid peak, the `allocator_gap` sections also agree; +an empty-attribution report has `allocator_gap: null`. The metric-specific +`event_id` and `callstack_groups` are the selected-event breakdown. Read report `has_more`, `truncated`, `total_is_exact`, and `effective_params` before claiming a complete composition. A full dynamic `top_n` window means diff --git a/src/pt_snap_cli/core/query_service.py b/src/pt_snap_cli/core/query_service.py index c02d6ed..92e8476 100644 --- a/src/pt_snap_cli/core/query_service.py +++ b/src/pt_snap_cli/core/query_service.py @@ -4,6 +4,7 @@ import os import sqlite3 import time +from dataclasses import dataclass from pathlib import Path from typing import Any @@ -12,7 +13,7 @@ from pt_snap_cli.core.dataset_attribution import event_attribution, summarize_dataset_stacks from pt_snap_cli.core.dataset_contract import QueryScope from pt_snap_cli.core.dataset_global import global_query -from pt_snap_cli.core.dataset_resolver import DatasetResolver +from pt_snap_cli.core.dataset_resolver import DatasetResolver, ResolvedDataset from pt_snap_cli.core.dataset_sources import DatasetSourceResolver, QueryBudget from pt_snap_cli.core.dataset_support import dataset_support from pt_snap_cli.core.errors import ( @@ -28,7 +29,13 @@ TemplateRenderError, ) from pt_snap_cli.core.focus_service import FocusService -from pt_snap_cli.core.models import QueryResult, TemplateInfo, TemplateParameter, TemplateSummary +from pt_snap_cli.core.models import ( + QueryResult, + ResolvedFocus, + TemplateInfo, + TemplateParameter, + TemplateSummary, +) from pt_snap_cli.core.stack_summary import summarize_stacks from pt_snap_cli.query.executor import QueryExecutionError as ExecutorQueryExecutionError from pt_snap_cli.query.executor import QueryExecutor @@ -69,6 +76,15 @@ def resolve_query_timeout(explicit: float | None) -> float | None: return value if value > 0 else None +@dataclass(frozen=True) +class _ResolvedQuery: + """One composition's focus and inspected generation, shared by every step.""" + + focus: ResolvedFocus + dataset: ResolvedDataset | None + explicit_device_id: int | None + + class QueryService: def __init__( self, @@ -217,6 +233,7 @@ def execute_query( timeout_s: float | None = None, slice_index: int | None = None, _budget: QueryBudget | None = None, + _resolved: _ResolvedQuery | None = None, ) -> QueryResult: budget = ( _budget @@ -225,21 +242,19 @@ def execute_query( ) timeout_s, started = budget.timeout_s, budget.started budget.remaining() - resolved = self._focus_service.resolve_focus( - explicit_db_path=db_path, - explicit_device_id=device_id, - start_dir=start_dir, - ) - if resolved.db_path is None: - raise FocusNotConfiguredError("No database path specified and no database configured.") - - dataset = DatasetResolver().inspect(resolved.db_path, budget=budget) + resolution = _resolved or self._resolve_query(db_path, device_id, start_dir, budget) + resolved, dataset = resolution.focus, resolution.dataset + assert resolved.db_path is not None budget.remaining() scope: dict[str, object] | None = None query_params = params or {} sources: DatasetSourceResolver | None = None if dataset is not None: - selected = dataset.device(device_id if device_id is not None else resolved.device_id) + selected = dataset.device( + resolution.explicit_device_id + if resolution.explicit_device_id is not None + else resolved.device_id + ) sources = DatasetSourceResolver( dataset, selected.device_id, self._context_cache, budget ) @@ -282,12 +297,18 @@ def execute_query( if isinstance(stack_bytes, int) and stack_bytes >= 0: summarize_dataset_stacks(result.rows, stack_bytes) budget.remaining() + if _resolved is not None: + # Inspection establishes the baseline. Reject changed contents + # after each composed step, before any report can be returned. + dataset.require_unchanged(budget) return result else: if slice_index is not None: raise InvalidParameterError("slice_index requires a manifest dataset.") ctx = self._validated_context(resolved.db_path) - target_device = self._resolve_device_id(ctx, resolved.device_id, device_id) + target_device = self._resolve_device_id( + ctx, resolved.device_id, resolution.explicit_device_id + ) executor = self._get_executor(ctx) try: @@ -350,6 +371,25 @@ def execute_query( scope=scope, ) + def _resolve_query( + self, + db_path: Path | str | None, + device_id: int | None, + start_dir: Path | None, + budget: QueryBudget, + ) -> _ResolvedQuery: + budget.remaining() + resolved = self._focus_service.resolve_focus( + explicit_db_path=db_path, + explicit_device_id=device_id, + start_dir=start_dir, + ) + if resolved.db_path is None: + raise FocusNotConfiguredError("No database path specified and no database configured.") + dataset = DatasetResolver().inspect(resolved.db_path, budget=budget) + budget.remaining() + return _ResolvedQuery(resolved, dataset, device_id) + def _get_executor(self, ctx: Context) -> QueryExecutor: """Reuse the executor while its cached database context remains valid. diff --git a/src/pt_snap_cli/core/report_service.py b/src/pt_snap_cli/core/report_service.py index 69a3090..6a823a5 100644 --- a/src/pt_snap_cli/core/report_service.py +++ b/src/pt_snap_cli/core/report_service.py @@ -7,7 +7,7 @@ from pt_snap_cli.core.dataset_sources import QueryBudget from pt_snap_cli.core.focus_service import FocusService from pt_snap_cli.core.models import PeakMemoryReport, QueryResult -from pt_snap_cli.core.query_service import QueryService, resolve_query_timeout +from pt_snap_cli.core.query_service import QueryService, _ResolvedQuery, resolve_query_timeout PeakMetric = Literal["active", "allocated", "reserved"] @@ -17,6 +17,15 @@ "reserved": "peak_reserved_event_id", } +_PEAK_FIELDS = ( + "peak_allocated", + "peak_allocated_event_id", + "peak_active", + "peak_active_event_id", + "peak_reserved", + "peak_reserved_event_id", +) + _ACTIVE_COUNTER_BY_METRIC = { "active": "peak_active", "allocated": "active_at_allocated_peak", @@ -45,6 +54,7 @@ def event_attribution( start_dir: Path | None = None, timeout_s: float | None = None, _budget: QueryBudget | None = None, + _resolved: _ResolvedQuery | None = None, ) -> QueryResult: """Reuse core point-event attribution, also for externally selected peaks. @@ -65,6 +75,7 @@ def event_attribution( start_dir=start_dir, timeout_s=timeout_s, _budget=_budget, + _resolved=_resolved, ) def peak_memory_report( @@ -87,17 +98,26 @@ def peak_memory_report( ) budget = QueryBudget(resolve_query_timeout(timeout_s), time.monotonic()) + resolution = self._query_service._resolve_query(db_path, device_id, start_dir, budget) range_params = {"start_id": start_id, "end_id": end_id} - peak_result = self._query_service.execute_query( - "memory_peak", + gap_result = self._query_service.execute_query( + "allocator_gap", params=range_params, _budget=budget, + _resolved=resolution, db_path=db_path, device_id=device_id, start_dir=start_dir, ) - peak = peak_result.rows[0] if peak_result.rows else {} - # memory_peak selects an INTEGER event ID (or NULL for an empty trace). + gap = gap_result.rows[0] if gap_result.rows else None + # allocator_gap selects the same independent, earliest-tie peak events + # for non-NULL counters. Preserve memory_peak's six-field contract, + # including NULL event IDs when a standalone counter is entirely NULL. + peak = {field: gap.get(field) for field in _PEAK_FIELDS} if gap else {} + for peak_metric, event_field in _EVENT_ID_BY_METRIC.items(): + if peak and peak[f"peak_{peak_metric}"] is None: + peak[event_field] = None + # No attribution event exists for an empty trace or a NULL peak. event_id = cast(int | None, peak.get(_EVENT_ID_BY_METRIC[metric])) attribution_params: dict[str, object] = { "event_id": event_id, @@ -109,7 +129,7 @@ def peak_memory_report( if event_id is None: return PeakMemoryReport( - device_id=peak_result.device_id, + device_id=gap_result.device_id, metric=metric, event_id=None, peak=peak, @@ -117,18 +137,10 @@ def peak_memory_report( callstack_groups=[], total_is_exact=True, effective_params=attribution_params, - scope=peak_result.scope, + scope=gap_result.scope, timeout_s=budget.timeout_s, ) - gap_result = self._query_service.execute_query( - "allocator_gap", - params=range_params, - _budget=budget, - db_path=db_path, - device_id=device_id, - start_dir=start_dir, - ) callstack_result = self.event_attribution( event_id, db_path, @@ -138,9 +150,8 @@ def peak_memory_report( stack_bytes=stack_bytes, start_dir=start_dir, _budget=budget, + _resolved=resolution, ) - - gap = gap_result.rows[0] if gap_result.rows else None # allocator_gap supplies the active counter at this metric's event, # not the independently occurring active high-water value. active_bytes = cast(int | None, (gap or {}).get(_ACTIVE_COUNTER_BY_METRIC[metric])) @@ -153,8 +164,9 @@ def peak_memory_report( else None ) + budget.remaining() return PeakMemoryReport( - device_id=peak_result.device_id, + device_id=gap_result.device_id, metric=metric, event_id=event_id, peak=peak, @@ -167,7 +179,7 @@ def peak_memory_report( included_bytes=included_bytes, active_bytes_at_event=active_bytes, coverage_percent=coverage, - scope=peak_result.scope, + scope=gap_result.scope, timeout_s=budget.timeout_s, source_coverage=cast( dict[str, object] | None, (callstack_result.scope or {}).get("source_coverage") diff --git a/tests/core/test_report_reuse.py b/tests/core/test_report_reuse.py new file mode 100644 index 0000000..9a53565 --- /dev/null +++ b/tests/core/test_report_reuse.py @@ -0,0 +1,270 @@ +"""Report composition reuses one inspected generation and one cumulative budget.""" + +import dataclasses +import json +import sqlite3 +from contextlib import closing + +import pytest + +import pt_snap_cli.core.query_service as query_service_module +from pt_snap_cli.core.dataset_resolver import DatasetResolver +from pt_snap_cli.core.dataset_sources import QueryBudget +from pt_snap_cli.core.errors import DatabaseSchemaError, QueryExecutionError, QueryTimeoutError +from pt_snap_cli.core.focus_service import FocusService +from pt_snap_cli.core.import_service import ImportService +from pt_snap_cli.core.query_service import QueryService +from pt_snap_cli.core.report_service import ReportService +from tests.core.test_dataset_attribution import case +from tests.core.test_dataset_import import source_options +from tests.test_dataset_focus import make_dataset + +PEAK_FIELDS = { + "peak_allocated", + "peak_allocated_event_id", + "peak_active", + "peak_active_event_id", + "peak_reserved", + "peak_reserved_event_id", +} + + +def cycle_dataset(tmp_path, count): + root = make_dataset(tmp_path / "cycles", devices=(0,), slices=2) + width = count // 2 + manifest = json.loads((root / "manifest.json").read_text()) + manifest["eventsPerSlice"] = width + manifest["devices"]["0"]["eventCount"] = count + for index, record in enumerate(manifest["devices"]["0"]["slices"]): + start, end = index * width, (index + 1) * width - 1 + record.update(startEventId=start, endEventId=end) + with closing(sqlite3.connect(root / record["file"])) as conn, conn: + conn.execute("DELETE FROM trace_entry_0") + conn.executemany( + "INSERT INTO trace_entry_0 VALUES (?,?,?,?,?,?,?,?,?)", + ( + ( + event, + (4, 5, 6)[event % 3], + 1048576 + 64 * (event - event % 3), + 64, + 0, + 64 if event % 3 == 0 else 0, + 64 if event % 3 < 2 else 0, + 128, + "work.py:42:run", + ) + for event in range(start, end + 1) + ), + ) + conn.executemany( + "INSERT INTO block_0 VALUES (?,?,?,?,?,?,?)", + ( + (event, 1048576 + 64 * event, 64, 64, -1, event, event + 2) + for event in range(start, end + 1, 3) + ), + ) + (root / "manifest.json").write_text(json.dumps(manifest)) + return root + + +@pytest.mark.parametrize("count", [6000, 60000]) +def test_report_inspects_once_and_scans_counters_once(tmp_path, monkeypatch, count): + root = cycle_dataset(tmp_path, count) + inspect, execute = DatasetResolver.inspect, QueryService.execute_query + inspections, calls, focuses = [], [], [] + resolve_focus = FocusService.resolve_focus + + def tracked_focus(self, *args, **kwargs): + result = resolve_focus(self, *args, **kwargs) + focuses.append(result) + return result + + def tracked_inspect(self, path, **kwargs): + result = inspect(self, path, **kwargs) + inspections.append(result) + return result + + def tracked_execute(self, template, *args, **kwargs): + calls.append((template, kwargs.get("_budget"), kwargs.get("_resolved"))) + return execute(self, template, *args, **kwargs) + + monkeypatch.setattr(FocusService, "resolve_focus", tracked_focus) + monkeypatch.setattr(DatasetResolver, "inspect", tracked_inspect) + monkeypatch.setattr(QueryService, "execute_query", tracked_execute) + service = ReportService() + try: + result = service.peak_memory_report(root, timeout_s=10) + finally: + service.close() + assert len(inspections) == len(focuses) == 1 + assert [name for name, _, _ in calls] == ["allocator_gap", "active_memory_callstack_at_event"] + assert len({id(budget) for _, budget, _ in calls}) == 1 + assert len({id(resolution) for _, _, resolution in calls}) == 1 + assert calls[0][2].dataset is inspections[0] + assert 0 < calls[0][1].work_rows < count + 20 + assert result.scope["fingerprint"] == inspections[0].fingerprint + assert set(result.peak) == PEAK_FIELDS + assert result.event_id == 0 and result.active_bytes_at_event == 64 + assert result.included_bytes == 64 and result.coverage_percent == 100 + + +@pytest.mark.parametrize( + "metric,event,active", [("allocated", 3, 60), ("active", 4, 90), ("reserved", 1, 20)] +) +def test_report_projects_independent_earliest_peaks_and_same_event_counters( + tmp_path, metric, event, active +): + root = case(tmp_path, devices=(0,)) + counters = {1: (10, 20, 900), 3: (80, 60, 100), 4: (30, 90, 100), 15: (80, 90, 900)} + for path in root.glob("device_0/*.db"): + with closing(sqlite3.connect(path)) as conn, conn: + conn.execute("UPDATE trace_entry_0 SET allocated=1,active=1,reserved=1") + for event_id, values in counters.items(): + conn.execute( + "UPDATE trace_entry_0 SET allocated=?,active=?,reserved=? WHERE id=?", + (*values, event_id), + ) + service = ReportService() + try: + result = service.peak_memory_report(root, metric=metric) + finally: + service.close() + assert set(result.peak) == PEAK_FIELDS + assert result.peak == { + "peak_allocated": 80, + "peak_allocated_event_id": 3, + "peak_active": 90, + "peak_active_event_id": 4, + "peak_reserved": 900, + "peak_reserved_event_id": 1, + } + assert result.event_id == event and result.active_bytes_at_event == active + assert ( + result.allocator_gap[f"reserved_active_gap_at_{metric}_peak"] == counters[event][2] - active + ) + + +def test_report_attribution_keeps_real_work_limit(tmp_path): + root = cycle_dataset(tmp_path, 60000) + with closing(sqlite3.connect(root / "device_0/slice_00000.db")) as conn, conn: + conn.executemany( + "INSERT INTO block_0 VALUES (?,?,?,?,?,?,?)", + ((-100000 - index, 2000000 + index, 1, 1, 1, -1, -1) for index in range(100001)), + ) + service = ReportService() + try: + with pytest.raises(QueryExecutionError, match="work budget"): + service.peak_memory_report(root) + finally: + service.close() + + +def test_report_deadline_is_not_restarted_for_attribution(tmp_path, monkeypatch): + root = cycle_dataset(tmp_path, 6000) + consume = QueryBudget.consume + + def expire_after_gap(self, rows): + consume(self, rows) + if rows and "peak_allocated" in rows[0]: + self.started -= 100 + + monkeypatch.setattr(QueryBudget, "consume", expire_after_gap) + service = ReportService() + try: + with pytest.raises(QueryTimeoutError): + service.peak_memory_report(root, timeout_s=10) + finally: + service.close() + + +@pytest.mark.parametrize("changed", ["member", "manifest"]) +def test_report_rejects_a_generation_change_between_steps(tmp_path, monkeypatch, changed): + root = cycle_dataset(tmp_path, 6000) + execute = QueryService.execute_query + calls = [] + + def mutate_after_gap(self, template, *args, **kwargs): + result = execute(self, template, *args, **kwargs) + calls.append(template) + if template == "allocator_gap": + if changed == "member": + with closing(sqlite3.connect(root / "device_0/slice_00000.db")) as conn, conn: + conn.execute("UPDATE trace_entry_0 SET active=999 WHERE id=0") + else: + path = root / "manifest.json" + path.write_text(path.read_text() + "\n") + return result + + monkeypatch.setattr(QueryService, "execute_query", mutate_after_gap) + service = ReportService() + try: + with pytest.raises(DatabaseSchemaError, match="changed"): + service.peak_memory_report(root) + finally: + service.close() + assert calls == ["allocator_gap"] + + +def test_report_empty_trace_retains_six_fields_without_attribution(tmp_path, monkeypatch): + root = cycle_dataset(tmp_path, 6000) + member = root / "device_0/slice_00000.db" + with closing(sqlite3.connect(member)) as conn, conn: + conn.execute("DELETE FROM trace_entry_0") + conn.execute("DELETE FROM block_0") + service = ReportService() + + def unexpected_attribution(*args, **kwargs): + pytest.fail("Empty peak must not invent an attribution event") + + monkeypatch.setattr(service, "event_attribution", unexpected_attribution) + try: + result = service.peak_memory_report(member) + finally: + service.close() + assert result.peak == dict.fromkeys(PEAK_FIELDS) + assert result.event_id is None and result.allocator_gap is None + assert result.callstack_groups == [] and result.total_is_exact + + +@pytest.mark.parametrize("empty", [False, True]) +def test_native_report_matches_standalone_and_preserves_empty_range(tmp_path, empty): + request = dataclasses.replace(source_options(tmp_path), set_focus=False) + importer = ImportService() + root = importer.import_snapshot(request).db_path + single = importer.import_snapshot(dataclasses.replace(request, events_per_slice=None)).db_path + service = ReportService() + params = {"start_id": 18, "end_id": 26} if empty else {} + try: + actual = service.peak_memory_report(root, **params) + expected = service.peak_memory_report(single, **params) + finally: + service.close() + assert actual.peak == expected.peak + assert actual.allocator_gap == expected.allocator_gap + assert actual.event_id == expected.event_id + assert actual.active_bytes_at_event == expected.active_bytes_at_event + assert actual.included_bytes == expected.included_bytes + assert set(actual.peak) == PEAK_FIELDS + if empty: + assert actual.event_id is None and actual.callstack_groups == [] + assert actual.scope["actual_range"]["real_event_count"] == 0 + + +def test_report_rejects_generation_change_during_peak_step(tmp_path, monkeypatch): + root = cycle_dataset(tmp_path, 6000) + global_query = query_service_module.global_query + + def mutate_after_scan(*args, **kwargs): + result = global_query(*args, **kwargs) + path = root / "manifest.json" + path.write_text(path.read_text() + "\n") + return result + + monkeypatch.setattr(query_service_module, "global_query", mutate_after_scan) + service = ReportService() + try: + with pytest.raises(DatabaseSchemaError, match="changed"): + service.peak_memory_report(root) + finally: + service.close() diff --git a/tests/core/test_report_service.py b/tests/core/test_report_service.py index 88e2a83..e692970 100644 --- a/tests/core/test_report_service.py +++ b/tests/core/test_report_service.py @@ -1,10 +1,12 @@ """Tests for peak memory report service.""" import sqlite3 +from contextlib import closing from pathlib import Path import pytest +from pt_snap_cli.core.query_service import QueryService from pt_snap_cli.core.report_service import ReportService from pt_snap_cli.query.registry import QueryRegistry, _load_all_templates @@ -121,6 +123,56 @@ def test_peak_memory_report_can_exclude_static(report_db: Path) -> None: } +@pytest.mark.parametrize("metric", [None, "active", "allocated", "reserved"]) +@pytest.mark.parametrize("bounded", [False, True]) +def test_null_peak_matches_memory_peak_without_attribution( + report_db: Path, monkeypatch, metric, bounded: bool +) -> None: + selected_metric = metric or "active" + bounds = {"start_id": 2, "end_id": 3} if bounded else {} + with closing(sqlite3.connect(report_db)) as conn, conn: + where = " WHERE id BETWEEN 2 AND 3" if bounded else "" + conn.execute(f"UPDATE trace_entry_0 SET {selected_metric} = NULL{where}") + expected = QueryService().execute_query("memory_peak", params=bounds, db_path=report_db) + service = ReportService() + calls = [] + execute = service._query_service.execute_query + + def tracked_execute(template, *args, **kwargs): + calls.append(template) + return execute(template, *args, **kwargs) + + def unexpected_attribution(*args, **kwargs): + pytest.fail("A NULL peak must not invent an attribution event") + + monkeypatch.setattr(service._query_service, "execute_query", tracked_execute) + monkeypatch.setattr(service, "event_attribution", unexpected_attribution) + report = service.peak_memory_report( + report_db, **bounds, **({"metric": metric} if metric is not None else {}) + ) + + assert report.peak == expected.rows[0] + assert report.event_id is None and report.allocator_gap is None + assert report.callstack_groups == [] and report.total_is_exact + assert report.effective_params["event_id"] is None + assert not report.has_more and not report.truncated + assert calls == ["allocator_gap"] + + +@pytest.mark.parametrize("active", [None, 0]) +def test_report_preserves_null_unselected_peak_and_zero_peak(report_db: Path, active) -> None: + with closing(sqlite3.connect(report_db)) as conn, conn: + conn.execute("UPDATE trace_entry_0 SET active = ?", (active,)) + expected = QueryService().execute_query("memory_peak", db_path=report_db) + metric = "reserved" if active is None else "active" + report = ReportService().peak_memory_report(report_db, metric=metric) + + assert report.peak == expected.rows[0] + assert report.event_id == (3 if active is None else 1) + assert report.allocator_gap is not None + assert report.callstack_groups + + def test_peak_memory_report_rejects_invalid_metric(report_db: Path) -> None: with pytest.raises(ValueError, match="Invalid metric"): ReportService().peak_memory_report(report_db, metric="invalid") # type: ignore[arg-type] diff --git a/tests/skills/test_memory_peak_breakdown_contract.py b/tests/skills/test_memory_peak_breakdown_contract.py index c6f6505..034c64c 100644 --- a/tests/skills/test_memory_peak_breakdown_contract.py +++ b/tests/skills/test_memory_peak_breakdown_contract.py @@ -141,6 +141,20 @@ def test_full_trace_workflow_runs_all_metrics_with_static_limit_and_json() -> No assert "active_blocks_at_event` at the chosen metric's peak event" in skill +def test_report_workflow_documents_reused_peak_query_and_null_semantics() -> None: + normalized = _normalized_skill() + + assert "`allocator_gap` runs once" in normalized + assert "without running a separate `memory_peak` query" in normalized + assert ( + "Both steps share one resolved database/device, budget, and dataset generation" + in normalized + ) + assert "empty attribution without running the attribution query" in normalized + assert "empty range or an all-NULL counter" in normalized + assert "an empty-attribution report has `allocator_gap: null`" in normalized + + def test_range_fallback_and_peak_event_semantics_are_explicit() -> None: skill = _skill() normalized = _normalized_skill() diff --git a/tests/test_peak_report_completeness.py b/tests/test_peak_report_completeness.py index ef91130..6495e4c 100644 --- a/tests/test_peak_report_completeness.py +++ b/tests/test_peak_report_completeness.py @@ -129,6 +129,39 @@ def test_report_completeness_and_same_event_coverage( assert ("Increase --limit" in result.stdout) == partial +@pytest.mark.parametrize("bounded", [False, True]) +@pytest.mark.parametrize("json_output", [True, False]) +def test_default_report_has_no_attribution_for_null_active_peak( + attribution_db: Path, bounded: bool, json_output: bool +) -> None: + bounds = {"start_id": 2, "end_id": 3} if bounded else {} + with closing(sqlite3.connect(attribution_db)) as conn, conn: + where = " WHERE id BETWEEN 2 AND 3" if bounded else "" + conn.execute(f"UPDATE trace_entry_0 SET active = NULL{where}") + args = ["report", "peak-memory", str(attribution_db)] + if bounded: + args += ["--start-id", "2", "--end-id", "3"] + result = CliRunner().invoke(app, args + (["--json"] if json_output else [])) + assert result.exit_code == 0, result.output + if json_output: + payload = json.loads(result.stdout) + with SnapshotAnalyzer(attribution_db) as analyzer: + peak = analyzer.execute_query("memory_peak", params=bounds) + assert payload["peak"] == peak["rows"][0] + assert payload["metric"] == "active" + assert payload["event_id"] is None and payload["allocator_gap"] is None + assert payload["callstack_groups"] == [] + assert payload["included_bytes"] == 0 + assert payload["active_bytes_at_event"] is None + assert payload["coverage_percent"] is None + assert payload["effective_params"]["event_id"] is None + assert payload["total_is_exact"] is True + assert payload["has_more"] is False and payload["truncated"] is False + else: + assert "Attribution: unavailable (no peak event)" in result.stdout + assert "No active memory callstack groups found" in result.stdout + + @pytest.mark.parametrize("state", ["empty", "null", "zero"]) @pytest.mark.parametrize("json_output", [True, False]) def test_report_unknown_coverage(attribution_db: Path, state: str, json_output: bool) -> None: