Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 33 additions & 1 deletion docs/en/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ across devices and there is no shared cross-device event order.
| `preexisting_live` | Owner-event preexisting occupancy, not a leak count |
| `block` | Merge proved allocation-event lifetimes and stable negative tokens once, then apply filters/order/page; latest containing-shard state is an observation, not state at arbitrary E |
| `freed_block_lifetime` | Deduplicated captured allocations with a proved `free_completed` source; event-ID distance buckets, not time |
| `leak_detection` | Captured dynamic lifetimes still present without completion in the **terminal dataset shard**, not union of per-shard unfreed lists; survival is only a candidate, not a confirmed leak; `--slice` is rejected |
| `leak_detection` | Proved captured dynamic lifetimes observed as active/pending-free (`state IN (0,1)`) without completion in the **terminal dataset shard**, not union of per-shard unfreed lists; survival is only a candidate, not a confirmed leak; `--slice` is rejected |
| `callstack_analysis` | All real stack-bearing trace actions, including free/segment/workspace, merged by full canonical source identity before global thresholds/ranking; weighted `avg_size=total_size/alloc_count` |
| Runtime overrides/custom templates/arbitrary SQL | Explicitly unsupported on datasets, even when named after a built-in; pass an explicit standalone member to use local SQL |

Expand Down Expand Up @@ -146,6 +146,38 @@ involved `slice_indices`, device, fingerprint and boundary exclusion. Source cov
is separate. Unproved historical lifecycle identities are shard-local, explicitly
marked, never guessed by address/local stack ID and never asserted as proved leaks.

### Leak candidates and lifecycle identity

`leak_detection` retains an intentional scope difference at semantics version **1**:

- **Standalone SQL** selects `allocEventId >= 0` with a NULL/negative `freeEventId`
(and the size filter). It does not filter stored `state` or verify the referenced
allocation action. An explicit dataset member is queried with this local contract.
- **Dataset scope** requires a proved real allocation action from its owning shard,
a terminal-shard observation with `state=1` (`active_allocated`) or `state=0`
(`active_pending_free`), and a NULL/negative completion reference after merging
any proved completion. Inactive (`state=-1`) or earlier-only observations are
excluded even when `freeEventId=-1`. A free request is not a completed free;
absence of a completion does not override the state or allocation-proof checks.

Thus an inactive block with a proved allocation and unknown free can appear in
standalone results but not dataset results. This is a schema-valid synthetic
counterexample, not evidence that real replay generates it or that replay is
defective. ATTACH, private scratch reduction and bounded Python fallback implement
the same dataset contract. Neither scope confirms a leak.

Dataset `block` identity is separate from terminal survival. A proved allocation
event merges its observations across shards; `allocEventId=-1` with a negative
block ID uses a stable preexisting token, not allocation proof. Negative boundary
events never provide allocation proof. Other unproved observations retain
`unproved:slice:<index>:block:<id>` identities even if block ID, address and
allocation reference collide across shards. They remain visible in `block`, with
`identity_status=unproved_shard_local` and missing allocation source, but are
excluded from dataset leak candidates. Merging them requires new cross-shard
identity evidence; equal addresses or unproved references alone are insufficient.
`source_coverage.unproved_identities` counts these shard-local identities before
filters/pages, independently of `has_more`/`truncated`.

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 peak selection and attribution. Cumulative
Expand Down
29 changes: 28 additions & 1 deletion docs/zh/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ pt-snap query '<db_path>' --device 0 --template-use event --params '{"id":123}'
| `preexisting_live` | 所有者事件的 preexisting 占用,不是泄漏数 |
| `block` | 已证明的分配事件生命周期及稳定负 token 去重后筛选/排序/分页;最新出现片 state 是观察,不是任意 E 的状态 |
| `freed_block_lifetime` | 已采集分配与已证明 `free_completed` 来源的去重生命周期;event-ID 距离桶,不是时间 |
| `leak_detection` | **数据集终片**中仍存在且无完成释放的已采集动态生命周期,不拼接逐片未释放列表;存活仅为候选,不证明泄漏;拒绝 `--slice` |
| `leak_detection` | **数据集终片**中观察为活跃/待释放(`state IN (0,1)`)且无完成释放、分配已证明的已采集动态生命周期,不拼接逐片未释放列表;存活仅为候选,不证明泄漏;拒绝 `--slice` |
| `callstack_analysis` | 全部带栈真实 trace action(含 free/segment/workspace),完整 canonical 来源身份合并后再做全局阈值/排名;加权 `avg_size=total_size/alloc_count` |
| runtime override/自定义模板/任意 SQL | 数据集明确不支持,即使命名为内建模板;需显式传单库 member 使用局部 SQL |

Expand Down Expand Up @@ -127,6 +127,33 @@ exactness 标记诚实。`has_more/truncated` 描述窗口,不表示来源/范
请求区间、适用时实际真实事件覆盖、涉及 `slice_indices`、设备、指纹及边界排除;来源覆盖
独立。未证明历史身份按片局部单独表达,不按地址/局部栈 ID 猜合并,不断言为已证明泄漏。

### 泄漏候选与生命周期身份

`leak_detection` 在语义版本 **1** 中保留有意的作用域差异:

- **单库 SQL** 选择 `allocEventId >= 0` 且 `freeEventId` 为 NULL/负数的行
(并应用大小筛选),不按存储的 `state` 筛选,也不验证引用的分配 action。
显式查询数据集成员文件时采用此局部合同。
- **数据集作用域** 要求在所属片证明真实 allocation action,终片观察为
`state=1`(`active_allocated`)或 `state=0`(`active_pending_free`),且归并
已证明的完成释放后,完成释放引用仍为 NULL/负数。即使 `freeEventId=-1`,
inactive(`state=-1`)或仅较早分片出现的观察也排除。释放请求不等于完成释放;
缺少完成释放不能取代 state 或分配来源证明检查。

因此,分配已证明、释放未知的 inactive block 可出现在单库结果中,却不出现在数据集
结果中。这是符合 schema 的合成差分反例,不证明真实 replay 会生成此组合,也不证明
replay 存在缺陷。ATTACH、私有 scratch 归约和受预算约束的 Python fallback 实现同一
数据集合同。两种作用域都不确认泄漏。

数据集 `block` 身份与终片存活相互独立。已证明的分配事件跨片归并其观察;
`allocEventId=-1` 且 block ID 为负数时采用稳定的 preexisting token,但不构成分配证明。
负边界事件从不提供分配证明。其他未证明观察保留
`unproved:slice:<index>:block:<id>` 身份,即使跨片 block ID、地址和分配引用相同也不归并。
这些观察仍可在 `block` 中看到,标记为 `identity_status=unproved_shard_local`、分配来源
缺失,但不进入数据集泄漏候选。归并需要新的跨片身份证据;仅地址或未证明引用相同不足以
支持归并。`source_coverage.unproved_identities` 在筛选/分页前统计这些按片身份,与
`has_more`/`truncated` 独立。

数据集读取先分离批次再查外片来源,使用借用的有界 Context LRU。所有片、来源、分组、
精确总数共用递减 deadline;报告的峰值选择与归因明确共用**一个**预算。累计取回/输出工作默认上限为
**100000 行 / 64 MiB 序列化值**,含重复来源读取;超限整体失败,不返回冒充完整的部分
Expand Down
2 changes: 1 addition & 1 deletion src/pt_snap_cli/query/templates/basic/block.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ queries:
units: text
metric_semantics: identifier
scope: captured_range
interpretation_limits: ["Dataset only, optional: generation/device/proved allocation-event or stable negative lifetime token; unproved histories use a separate shard-local identity. Never address or local stack identity."]
interpretation_limits: ["Dataset only, optional: generation/device/proved allocation-event or stable negative lifetime token; unproved histories retain separate unproved:slice:<index>:block:<id> identities even when block IDs, addresses and unproved allocation references coincide across shards. Never address or local stack identity."]
- column: identity_status
type: str
units: text
Expand Down
2 changes: 2 additions & 0 deletions src/pt_snap_cli/query/templates/business/leak_detection.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ queries:
semantics_version: 1
interpretation_limits:
- "Rows are candidates still without a free-completion event in the captured range; end-of-trace survival is not a confirmed leak."
- "Standalone SQL checks allocEventId >= 0 and a NULL/negative freeEventId, without state filtering or allocation-action proof."
- "Dataset scope additionally requires a proved real allocation and a terminal-shard active_allocated/active_pending_free observation (state IN (0,1)); inactive plus unknown-free and earlier-only observations are excluded. ATTACH, scratch and bounded fallback share this contract."
- "Event IDs and ID distances are ordering markers, not elapsed time."
query: |
SELECT id, address, size, allocEventId
Expand Down
Loading
Loading