From e7671a04ff0192b399808082eba0ea1f11aa199e Mon Sep 17 00:00:00 2001 From: codeasier Date: Mon, 24 Aug 2026 00:05:08 +0800 Subject: [PATCH 1/2] feat: add pt-snap memory fragmentation skill --- AGENTS.md | 4 +- skills/AGENTS.md | 15 +- skills/pt-snap-memory-fragmentation/SKILL.md | 314 +++++++++++++++++++ tests/AGENTS.md | 1 + tests/test_memory_fragmentation_skill.py | 140 +++++++++ 5 files changed, 468 insertions(+), 6 deletions(-) create mode 100644 skills/pt-snap-memory-fragmentation/SKILL.md create mode 100644 tests/test_memory_fragmentation_skill.py diff --git a/AGENTS.md b/AGENTS.md index ac8ee37..67cfe3c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,7 +35,7 @@ that local environment is intentionally available. | Package source | [src/AGENTS.md](src/AGENTS.md) | Installable package boundaries and source-layout rules | | Tests | [tests/AGENTS.md](tests/AGENTS.md) | Cross-surface contracts, service/query/runtime suites, and reviewed executable fixtures | | Benchmarks | [benchmarks/AGENTS.md](benchmarks/AGENTS.md) | Import and SQLite performance measurement with temporary outputs | -| Agent skills | [skills/AGENTS.md](skills/AGENTS.md) | Installation approval and read-only memory-diagnostic boundaries | +| Agent skills | [skills/AGENTS.md](skills/AGENTS.md) | Environment setup and read-only memory-diagnostic workflows | ## Runtime Topology @@ -112,7 +112,7 @@ templates under category subdirectories are included by | Snapshot import or metadata | `src/pt_snap_cli/core/import_service.py`, `src/pt_snap_cli/core/import_metadata.py`, `src/pt_snap_cli/core/snapshot_import_backend.py` | `tests/core/test_import_*.py`, `tests/test_snapshot_db.py` | | Snapshot splitting or replay | `src/pt_snap_cli/core/split_service.py`, `src/pt_snap_cli/snapshot/` | `tests/core/test_split_service.py`, `tests/snapshot/` | | Reports | `src/pt_snap_cli/core/report_service.py`, report commands in `src/pt_snap_cli/cli.py` | `tests/core/test_report_service.py`, report cases in `tests/test_cli.py` | -| Agent setup or peak-memory diagnostic skills | `skills/` and the referenced CLI/query surfaces | `tests/test_setup_skill.py`, `tests/test_memory_peak_breakdown_skill.py` | +| Agent setup, peak breakdown or fragmentation skills | `skills/` and the referenced CLI/query surfaces | `tests/test_setup_skill.py`, `tests/test_memory_peak_breakdown_skill.py`, `tests/test_memory_fragmentation_skill.py` | | Packaging or release | `pyproject.toml`, `.github/workflows/` | `tests/test_package.py`, `tests/test_release_workflow.py` | | Executable fixtures | `tests/fixtures/snapshots/` | `tests/test_fixture_provenance.py` before any deserializing suite | diff --git a/skills/AGENTS.md b/skills/AGENTS.md index df02e5a..f79a27c 100644 --- a/skills/AGENTS.md +++ b/skills/AGENTS.md @@ -3,16 +3,16 @@ # skills ## Purpose -`skills` contains agent workflows shipped with the repository. The setup skill -has an independent side-effect boundary because it may install packages into the -user's active Python environment after explicit approval; diagnostic skills use -existing SnapshotDB data without writes. +`skills` contains agent workflows shipped with the repository. Setup owns the +only Python-environment mutation boundary; diagnostic skills consume installed +`pt-snap` surfaces and keep snapshot analysis read-only. ## Scope | Path | Responsibility | | --- | --- | | `pt-snap-setup/SKILL.md` | Detect the active interpreter, verify CLI ownership, request install approval, and re-verify the same environment. | | `pt-snap-memory-peak-breakdown/SKILL.md` | Explain active memory at active, allocated, or reserved peak events without leak, fragmentation, or OOM overclaims. | +| `pt-snap-memory-fragmentation/SKILL.md` | Diagnose allocator gaps, runtime segment retention/churn, and fragmentation-consistent pressure without persisting analysis state. | ## Invariants - Preserve the selected `sys.executable` path for every Python and pip command; canonical paths are only for ownership comparison. @@ -20,7 +20,14 @@ existing SnapshotDB data without writes. - Keep `editable` and PyPI choices explicit, and obtain confirmation before every install attempt. - Do not add setup steps that write reports or modify pt-snap focus/configuration. - Keep memory diagnostics SnapshotDB-only and read-only; pass database/device explicitly and delegate missing tooling to `pt-snap-setup`. +- Diagnostic skills must not install packages, import pickle snapshots, persist + focus, or turn allocator gaps into definitive fragmentation claims. +- Prefer packaged query templates for diagnostics. Any raw SQLite fallback must + document why a template is insufficient and enforce read-only access. ## Focused Tests - Run `pytest tests/test_setup_skill.py` after setup-skill changes. The current executable test covers active-interpreter path preservation; review the remaining approval and reporting instructions statically. - Run `pytest tests/test_memory_peak_breakdown_skill.py` after peak-breakdown skill changes; it locks command/template references, range fallback, and attribution caveats. +- Run `pytest tests/test_memory_fragmentation_skill.py` after fragmentation-skill + changes; it checks current command/template references, read-only boundaries, + runtime segment coverage, and conservative classifications. diff --git a/skills/pt-snap-memory-fragmentation/SKILL.md b/skills/pt-snap-memory-fragmentation/SKILL.md new file mode 100644 index 0000000..3e59f68 --- /dev/null +++ b/skills/pt-snap-memory-fragmentation/SKILL.md @@ -0,0 +1,314 @@ +--- +name: pt-snap-memory-fragmentation +description: Diagnose suspected PyTorch allocator fragmentation, cache pressure, or segment churn from an existing SnapshotDB when reserved memory stays above active or allocated memory, peaks diverge, or OOM-like pressure needs conservative allocator evidence. +--- + +# pt-snap-memory-fragmentation + +## Overview + +Use this skill to gather read-only SnapshotDB evidence about allocator gaps, +segment retention, and segment churn. The workflow can identify pressure that is +consistent with fragmentation, but it cannot prove fragmentation from a +SnapshotDB alone. + +SnapshotDB does not contain free-region topology, size-bin history, or the +largest contiguous free region. Therefore, `reserved - active` is not pure +fragmentation, and no definitive fragmentation ratio or OOM root cause can be +derived from this workflow. + +## Required Inputs + +- A SnapshotDB path, supplied explicitly or resolved from the current + `pt-snap focus`. +- A device ID, supplied explicitly or already selected by the current focus. + +Optional inputs: + +- An event range to investigate. +- A positive page size for timeline and event pagination; default `1000`. +- Selected peak or pressure event IDs for active-block attribution. + +Replace ``, ``, ``, ``, and event-range +placeholders with validated values before running commands. Quote the database +path in every command. + +## Prerequisite Phase + +### 1. Verify pt-snap + +Run: + +```bash +command -v pt-snap +pt-snap --help +``` + +If either command fails, stop and direct the user to `pt-snap-setup`. Never +install, upgrade, repair, or switch Python environments from this skill. + +### 2. Resolve scope without persisting focus + +If either input was not supplied, inspect the current state: + +```bash +pt-snap focus +``` + +Use the displayed database and focused device only when both are present. If +either remains absent or ambiguous, ask the user to select it and stop until it +is explicit. Do not run `pt-snap focus `, use `--session`, or +otherwise persist or modify focus. After resolving the scope, pass both the +database and device explicitly to every diagnostic query and report command. + +This skill accepts SnapshotDB files only. Do not run `pt-snap import`, open a +pickle, or deserialize a pickle. If only a pickle is available, stop and explain +that conversion requires a separate trusted-input decision because pickle +loading is not a sandbox. + +### 3. Verify metadata and required templates before diagnosis + +Run these checks before any diagnostic query: + +```bash +pt-snap metadata "" --json +pt-snap query --template-info memory_peak +pt-snap query --template-info allocator_gap +pt-snap query --template-info allocation +pt-snap query --template-info event +``` + +Stop on invalid database metadata/schema or a missing required template, and +report the exact failure. A compatible legacy database may report metadata as +unavailable; record that provenance limitation rather than treating it as +import metadata. Do not replace a missing required template with raw SQL. + +Before using the optional attribution phase, also verify its surfaces: + +```bash +pt-snap query --template-info active_memory_callstack_at_event +pt-snap report peak-memory --help +``` + +## Diagnostic Workflow + +### 1. Establish separate peaks and same-event gaps + +Run: + +```bash +pt-snap query "" --device --template-use memory_peak +pt-snap query "" --device --template-use allocator_gap +``` + +Use `memory_peak` for the separate allocated, active, and reserved peak values +and their event IDs. These peaks may occur at different events, so never +subtract one peak value from another. Use `allocator_gap` for +`reserved - active` and `reserved - allocated` comparisons at the same selected +peak event. + +Treat the gaps as allocator/cache pressure indicators. They include effects +such as reusable cache, inactive blocks, allocator bookkeeping, and possibly +unusable free regions; they are not a direct measurement of fragmentation. + +### 2. Read the event-ordered memory curve in bounded pages + +Run `allocation` with a positive page size, `min_id=0`, and increasing offsets: + +```bash +pt-snap query "" --device --template-use allocation --params '{"min_id":0,"order_by":"id","order_dir":"ASC","limit":,"offset":}' +``` + +Start with offset `0`, increase it by ``, and stop when a page has no +rows. Preserve event order while examining the allocated, active, and reserved +curve. Use the optional `max_id` parameter consistently on every page when the +scope has an upper event bound. + +Look for sustained rather than isolated gaps, reserved plateaus after active +memory falls, repeated reserve growth, and whether later allocation activity +reuses an existing reserved plateau. Event IDs establish ordering, not time; +event-ID differences are not durations or rates. + +### 3. Inspect both runtime segment operation pairs + +Query all four segment actions with `min_id=0`, bounded pages, and event order: + +```bash +pt-snap query "" --device --template-use event --params '{"min_id":0,"action":0,"order_by":"id","order_dir":"ASC","limit":,"offset":}' +pt-snap query "" --device --template-use event --params '{"min_id":0,"action":1,"order_by":"id","order_dir":"ASC","limit":,"offset":}' +pt-snap query "" --device --template-use event --params '{"min_id":0,"action":2,"order_by":"id","order_dir":"ASC","limit":,"offset":}' +pt-snap query "" --device --template-use event --params '{"min_id":0,"action":3,"order_by":"id","order_dir":"ASC","limit":,"offset":}' +``` + +Interpret the operation pairs separately: + +- `0=segment_map` and `1=segment_unmap` describe runtime expandable-segment + mapping operations. +- `2=segment_alloc` and `3=segment_free` describe runtime segment acquisition + and release operations. + +Repeat pagination for each action until no rows remain. The `min_id=0` filter is +mandatory here because negative IDs are synthetic reconstruction events for +segments that existed before collection; they are not runtime segment +operations. + +Compare the operation ordering with the memory curve. Repeated map/unmap or +alloc/free activity can support a segment-churn inference, while reserve growth +without corresponding release can support segment-retention or cache-pressure +inferences. Event size sums are operation volume, not retained bytes or +reserved deltas. Do not subtract summed map/unmap or alloc/free sizes and call +the result retained memory. + +### 4. Optionally aggregate operations or locate maximum observed gaps + +Packaged templates expose ordered event rows and same-event gaps at peak events, +but they do not aggregate segment operation counts/sizes or locate maximum gaps +over the full runtime range. Only when one of those aggregates is needed, and +only when the `sqlite3` CLI is available, use this read-only fallback. + +First validate `` as a non-negative decimal integer matching +`^[0-9]+$`; reject signs, whitespace, separators, and every other character +before interpolating it into a table name. Then run only `SELECT`/`WITH SELECT` +statements through `sqlite3 -readonly`: + +```bash +device_id='' +case "$device_id" in + ''|*[!0-9]*) printf '%s\n' 'device ID must be a non-negative decimal integer' >&2; exit 1 ;; +esac +sqlite3 -readonly "" " +SELECT action, + COUNT(*) AS operation_count, + COALESCE(SUM(size), 0) AS operation_volume_bytes, + MAX(size) AS largest_operation_bytes +FROM trace_entry_${device_id} +WHERE id >= 0 AND action IN (0, 1, 2, 3) +GROUP BY action +ORDER BY action; + +SELECT id, allocated, active, reserved, + reserved - active AS reserved_active_gap +FROM trace_entry_${device_id} +WHERE id >= 0 +ORDER BY reserved_active_gap DESC, id ASC +LIMIT 1; + +SELECT id, allocated, active, reserved, + reserved - allocated AS reserved_allocated_gap +FROM trace_entry_${device_id} +WHERE id >= 0 +ORDER BY reserved_allocated_gap DESC, id ASC +LIMIT 1;" +``` + +The SQL remains subject to the same limitations: operation sums measure churn +volume, maximum counter gaps do not reveal free-region topology, and neither is +a fragmentation ratio. If read-only mode is unavailable or device validation +fails, skip this phase and list the aggregate as unknown. No writable SQL is +permitted. + +### 5. Optionally describe active blocks at selected events + +After verifying the optional surfaces, use either or both of these commands: + +```bash +pt-snap report peak-memory "" --device --metric active --limit 20 --json +pt-snap query "" --device --template-use active_memory_callstack_at_event --params '{"event_id":,"include_static":true,"min_size":0,"top_n":20}' +``` + +Use these results only to describe active blocks at a selected event. They do +not attribute reserved bytes, cached bytes, or the `reserved - active` gap to +those callstacks. Keep static and dynamic active-block groups distinct. + +Do not use `callstack_analysis` as segment-source attribution. Its query has no +action filter, so it mixes event types and cannot identify which callstack +caused segment mapping, acquisition, retention, cache bytes, or fragmentation. + +### 6. Classify evidence conservatively + +Choose one or more classifications and assign `low`, `medium`, or `high` +confidence based on the stated evidence and unknowns: + +- `allocator/cache pressure`: reserved memory stays materially above active or + allocated memory, without enough topology evidence to isolate fragmentation. +- `segment retention/churn`: runtime segment operations and the ordered curve + show repeated mapping/acquisition activity or limited release; this describes + allocator behavior, not exact retained bytes. +- `fragmentation-consistent pressure`: sustained same-event gaps and allocation + pressure coexist with segment behavior that is compatible with unusable free + regions. This is a hypothesis, never proof of fragmentation. +- `normal allocator behavior`: reserve reuse and segment caching are stable and + consistent with expected allocator caching, with no corroborating pressure. +- `inconclusive`: missing topology, incomplete capture scope, absent operation + pairs, coarse event ordering, or external device-memory evidence prevents a + stronger classification. + +Do not claim a definitive fragmentation ratio or OOM root cause. Even high +confidence applies only to the selected classification and observed scope, not +to facts the SnapshotDB cannot represent. + +## Output Template + +Report each section separately and in this order: + +1. `Scope`: database path, device ID, event range, page size, metadata status, + and templates verified. +2. `Evidence`: separate peaks/event IDs, same-event gaps, ordered curve + behavior, and both segment operation pairs. Label SQL sums as operation + volume. +3. `Inference`: patterns supported by the evidence without restating them as + measured facts. +4. `Unknowns`: free-region topology, size-bin history, largest contiguous free + region, wall-clock timing, device-global consumers, and missing capture + context. +5. `Classifications and confidence`: category, confidence, supporting evidence, + contradictory evidence, and scope limitations. +6. `Validation experiments`: a targeted experiment for each leading inference + and what outcome would support or reject it. + +Useful validation experiments include repeating captures at equivalent workload +milestones, extending capture through expected cleanup, synchronizing before a +comparison point, comparing controlled allocator configurations, and measuring +whether subsequent allocations reuse reserved memory. Allocator cache cleanup +may lower reserved memory, but that does not prove fragmentation or release of +application references. Use external allocator/runtime telemetry when an +experiment needs size-bin or contiguous-free-region evidence. + +## Guardrails + +- Keep every SnapshotDB access read-only. +- Never install packages or switch Python environments; delegate setup to + `pt-snap-setup` and stop. +- Never import or deserialize pickle input. +- Never persist focus or configuration. +- Never write reports, exports, scratch databases, focus files, or readiness + files; keep results on standard output and do not redirect them to files. +- Prefer packaged templates. Raw SQLite is optional only for segment operation + counts/sizes or maximum observed gaps that packaged templates cannot provide. +- Validate the device ID as a non-negative decimal integer before table-name + interpolation, use `sqlite3 -readonly`, and run no writable SQL. +- Keep separate-event peaks distinct and use `allocator_gap` for same-event + comparisons. +- Exclude negative synthetic reconstruction events from runtime segment + analysis with `min_id=0` or `id >= 0`. +- Treat operation counts and size sums as operation volume, not retained bytes. +- Event IDs are ordering markers, not timestamps. +- Separate evidence, inference, unknowns, classifications/confidence, and + validation experiments. + +## Verification Checklist + +- `pt-snap` availability was verified without installation or environment + changes. +- An explicit database and device were resolved without changing focus. +- Metadata and required templates were verified before diagnosis. +- Separate peaks came from `memory_peak`; same-event gaps came from + `allocator_gap`. +- The allocated/active/reserved curve used paginated, event-ordered `allocation` + queries. +- Runtime `segment_map`/`segment_unmap` and `segment_alloc`/`segment_free` were + both inspected with synthetic events excluded. +- Optional raw SQL, if used, stayed read-only and within the aggregate boundary. +- Active-block callstacks were not presented as reserved/cache attribution. +- Conclusions used conservative classifications, explicit confidence, unknowns, + and validation experiments. diff --git a/tests/AGENTS.md b/tests/AGENTS.md index 9ea91c1..3cce773 100644 --- a/tests/AGENTS.md +++ b/tests/AGENTS.md @@ -20,6 +20,7 @@ | `test_fixture_provenance.py` | Non-deserializing coverage, SHA-256, size, and Git LFS pointer validation for executable fixtures. | | `test_governance.py` | Snapshot provenance and repository governance contracts. | | `test_mcp_server.py` | MCP server tool/resource/prompt behavior tests. | +| `test_memory_fragmentation_skill.py` | Verifies the fragmentation skill's current command/template references, runtime segment coverage, conservative classifications, and read-only boundaries. | | `test_models.py` | Package-level model behavior tests. | | `test_package.py` | Package metadata/import/version tests. | | `test_release_workflow.py` | Release workflow and package publication contract tests. | diff --git a/tests/test_memory_fragmentation_skill.py b/tests/test_memory_fragmentation_skill.py new file mode 100644 index 0000000..467fb5c --- /dev/null +++ b/tests/test_memory_fragmentation_skill.py @@ -0,0 +1,140 @@ +import re +from pathlib import Path + +SKILL_PATH = Path("skills/pt-snap-memory-fragmentation/SKILL.md") +TEMPLATE_ROOT = Path("src/pt_snap_cli/query/templates") +CLI_PATH = Path("src/pt_snap_cli/cli.py") + + +def test_memory_fragmentation_skill_uses_current_pt_snap_surfaces() -> None: + skill = SKILL_PATH.read_text() + cli = CLI_PATH.read_text() + templates = { + "memory_peak": TEMPLATE_ROOT / "statistical/memory_peak.yaml", + "allocator_gap": TEMPLATE_ROOT / "statistical/allocator_gap.yaml", + "allocation": TEMPLATE_ROOT / "basic/allocation.yaml", + "event": TEMPLATE_ROOT / "basic/event.yaml", + "active_memory_callstack_at_event": ( + TEMPLATE_ROOT / "business/active_memory_callstack_at_event.yaml" + ), + } + + assert "name: pt-snap-memory-fragmentation" in skill + assert "`pt-snap-setup`" in skill + assert "readiness.json" not in skill + assert 'pt-snap metadata "" --json' in skill + assert "pt-snap report peak-memory" in skill + for command in ('@app.command("focus")', '@app.command("metadata")', '@app.command("query")'): + assert command in cli + assert '@report_app.command("peak-memory")' in cli + + for template, path in templates.items(): + assert path.is_file() + assert f" {template}:" in path.read_text() + assert f"--template-info {template}" in skill + assert f"--template-use {template}" in skill + + +def test_memory_fragmentation_skill_uses_paginated_runtime_evidence() -> None: + skill = SKILL_PATH.read_text() + + allocation_command = ( + '--template-use allocation --params \'{"min_id":0,"order_by":"id",' + '"order_dir":"ASC","limit":,"offset":}\'' + ) + assert allocation_command in skill + + for action in range(4): + event_params = ( + f'--template-use event --params \'{{"min_id":0,"action":{action},' + '"order_by":"id","order_dir":"ASC","limit":,' + '"offset":}\'' + ) + assert event_params in skill + + assert "`0=segment_map` and `1=segment_unmap`" in skill + assert "`2=segment_alloc` and `3=segment_free`" in skill + assert "negative IDs are synthetic reconstruction events" in skill + assert "Event size sums are operation volume, not retained bytes or" in skill + + +def test_memory_fragmentation_skill_limits_raw_sql_to_read_only_aggregates() -> None: + skill = SKILL_PATH.read_text() + raw_sql = skill.split('sqlite3 -readonly "" "', maxsplit=1)[1].split( + "\n```", maxsplit=1 + )[0] + + assert 'sqlite3 -readonly ""' in skill + assert "non-negative decimal integer matching" in skill + assert "before interpolating it into a table name" in skill + assert "WHERE id >= 0 AND action IN (0, 1, 2, 3)" in skill + assert "only for segment operation" in skill + assert "counts/sizes or maximum observed gaps" in skill + assert "No writable SQL is" in skill + assert "Do not replace a missing required template with raw SQL." in skill + for statement in ( + "alter", + "attach", + "create", + "delete", + "detach", + "drop", + "insert", + "reindex", + "replace", + "update", + "vacuum", + ): + assert re.search(rf"\b{statement}\b", raw_sql, re.IGNORECASE) is None + + +def test_memory_fragmentation_skill_preserves_snapshotdb_boundaries() -> None: + skill = SKILL_PATH.read_text() + + for guardrail in ( + "Do not run `pt-snap focus `", + "Do not run `pt-snap import`", + "Never import or deserialize pickle input.", + "Never write reports, exports, scratch databases, focus files, or readiness", + "pass both the", + "database and device explicitly to every diagnostic query", + "Event IDs are ordering markers, not timestamps.", + ): + assert guardrail in skill + + +def test_memory_fragmentation_skill_prevents_fragmentation_overclaims() -> None: + skill = SKILL_PATH.read_text() + + for limitation in ( + "free-region topology", + "size-bin history", + "largest contiguous free region", + "`reserved - active` is not pure", + "fragmentation, and no definitive fragmentation ratio", + "no definitive fragmentation ratio or OOM root cause", + "not attribute reserved bytes, cached bytes", + "Do not use `callstack_analysis` as segment-source attribution.", + "Its query has no", + "action filter, so it mixes event types", + ): + assert limitation in skill + + for classification in ( + "allocator/cache pressure", + "segment retention/churn", + "fragmentation-consistent pressure", + "normal allocator behavior", + "inconclusive", + ): + assert f"`{classification}`" in skill + + for section in ( + "`Scope`", + "`Evidence`", + "`Inference`", + "`Unknowns`", + "`Classifications and confidence`", + "`Validation experiments`", + ): + assert section in skill From adba1c6b3946f5faf5172510a7ca5494a4b19322 Mon Sep 17 00:00:00 2001 From: codeasier Date: Mon, 24 Aug 2026 17:53:53 +0800 Subject: [PATCH 2/2] fix: propagate validated event range through fragmentation skill --- skills/pt-snap-memory-fragmentation/SKILL.md | 73 +++++++++++++------- tests/test_memory_fragmentation_skill.py | 35 ++++++++-- 2 files changed, 77 insertions(+), 31 deletions(-) diff --git a/skills/pt-snap-memory-fragmentation/SKILL.md b/skills/pt-snap-memory-fragmentation/SKILL.md index 3e59f68..dda40b2 100644 --- a/skills/pt-snap-memory-fragmentation/SKILL.md +++ b/skills/pt-snap-memory-fragmentation/SKILL.md @@ -25,13 +25,16 @@ derived from this workflow. Optional inputs: -- An event range to investigate. +- An event range to investigate, expressed as the `` and + `` event IDs. Use `0` as `` unless a validated + explicit lower bound applies. Omit every upper-bound parameter while the + scope has no validated upper bound. - A positive page size for timeline and event pagination; default `1000`. - Selected peak or pressure event IDs for active-block attribution. -Replace ``, ``, ``, ``, and event-range -placeholders with validated values before running commands. Quote the database -path in every command. +Replace ``, ``, ``, ``, ``, +and `` placeholders with validated values before running commands. +Quote the database path in every command. ## Prerequisite Phase @@ -97,10 +100,16 @@ pt-snap report peak-memory --help Run: ```bash -pt-snap query "" --device --template-use memory_peak -pt-snap query "" --device --template-use allocator_gap +pt-snap query "" --device --template-use memory_peak --params '{"start_id":}' +pt-snap query "" --device --template-use allocator_gap --params '{"start_id":}' ``` +The `start_id` filter keeps peak events inside the validated runtime range; +with the default `0` it excludes negative synthetic reconstruction rows, which +could otherwise win a peak and whose IDs cannot drive dynamic attribution +later. When the scope has a validated upper bound, add `"end_id":` +to both parameter objects. + Use `memory_peak` for the separate allocated, active, and reserved peak values and their event IDs. These peaks may occur at different events, so never subtract one peak value from another. Use `allocator_gap` for @@ -113,16 +122,17 @@ unusable free regions; they are not a direct measurement of fragmentation. ### 2. Read the event-ordered memory curve in bounded pages -Run `allocation` with a positive page size, `min_id=0`, and increasing offsets: +Run `allocation` with a positive page size, `min_id=`, and +increasing offsets: ```bash -pt-snap query "" --device --template-use allocation --params '{"min_id":0,"order_by":"id","order_dir":"ASC","limit":,"offset":}' +pt-snap query "" --device --template-use allocation --params '{"min_id":,"order_by":"id","order_dir":"ASC","limit":,"offset":}' ``` Start with offset `0`, increase it by ``, and stop when a page has no rows. Preserve event order while examining the allocated, active, and reserved -curve. Use the optional `max_id` parameter consistently on every page when the -scope has an upper event bound. +curve. Add `"max_id":` consistently on every page when the scope has +an upper event bound. Look for sustained rather than isolated gaps, reserved plateaus after active memory falls, repeated reserve growth, and whether later allocation activity @@ -131,15 +141,19 @@ event-ID differences are not durations or rates. ### 3. Inspect both runtime segment operation pairs -Query all four segment actions with `min_id=0`, bounded pages, and event order: +Query all four segment actions with `min_id=`, bounded pages, and +event order: ```bash -pt-snap query "" --device --template-use event --params '{"min_id":0,"action":0,"order_by":"id","order_dir":"ASC","limit":,"offset":}' -pt-snap query "" --device --template-use event --params '{"min_id":0,"action":1,"order_by":"id","order_dir":"ASC","limit":,"offset":}' -pt-snap query "" --device --template-use event --params '{"min_id":0,"action":2,"order_by":"id","order_dir":"ASC","limit":,"offset":}' -pt-snap query "" --device --template-use event --params '{"min_id":0,"action":3,"order_by":"id","order_dir":"ASC","limit":,"offset":}' +pt-snap query "" --device --template-use event --params '{"min_id":,"action":0,"order_by":"id","order_dir":"ASC","limit":,"offset":}' +pt-snap query "" --device --template-use event --params '{"min_id":,"action":1,"order_by":"id","order_dir":"ASC","limit":,"offset":}' +pt-snap query "" --device --template-use event --params '{"min_id":,"action":2,"order_by":"id","order_dir":"ASC","limit":,"offset":}' +pt-snap query "" --device --template-use event --params '{"min_id":,"action":3,"order_by":"id","order_dir":"ASC","limit":,"offset":}' ``` +When the scope has a validated upper bound, add `"max_id":` to every +page of all four actions. + Interpret the operation pairs separately: - `0=segment_map` and `1=segment_unmap` describe runtime expandable-segment @@ -147,10 +161,10 @@ Interpret the operation pairs separately: - `2=segment_alloc` and `3=segment_free` describe runtime segment acquisition and release operations. -Repeat pagination for each action until no rows remain. The `min_id=0` filter is -mandatory here because negative IDs are synthetic reconstruction events for -segments that existed before collection; they are not runtime segment -operations. +Repeat pagination for each action until no rows remain. The non-negative +`min_id` filter is mandatory here because negative IDs are synthetic +reconstruction events for segments that existed before collection; they are not +runtime segment operations. Compare the operation ordering with the memory curve. Repeated map/unmap or alloc/free activity can support a segment-churn inference, while reserve growth @@ -164,7 +178,10 @@ the result retained memory. Packaged templates expose ordered event rows and same-event gaps at peak events, but they do not aggregate segment operation counts/sizes or locate maximum gaps over the full runtime range. Only when one of those aggregates is needed, and -only when the `sqlite3` CLI is available, use this read-only fallback. +only when the `sqlite3` CLI is available, use this read-only fallback. Scope +these aggregates to the same validated range: substitute `` for +the literal `0` in the predicates below, and append `AND id <= ` to +every statement when the scope has a validated upper bound. First validate `` as a non-negative decimal integer matching `^[0-9]+$`; reject signs, whitespace, separators, and every other character @@ -182,21 +199,21 @@ SELECT action, COALESCE(SUM(size), 0) AS operation_volume_bytes, MAX(size) AS largest_operation_bytes FROM trace_entry_${device_id} -WHERE id >= 0 AND action IN (0, 1, 2, 3) +WHERE id >= AND action IN (0, 1, 2, 3) GROUP BY action ORDER BY action; SELECT id, allocated, active, reserved, reserved - active AS reserved_active_gap FROM trace_entry_${device_id} -WHERE id >= 0 +WHERE id >= ORDER BY reserved_active_gap DESC, id ASC LIMIT 1; SELECT id, allocated, active, reserved, reserved - allocated AS reserved_allocated_gap FROM trace_entry_${device_id} -WHERE id >= 0 +WHERE id >= ORDER BY reserved_allocated_gap DESC, id ASC LIMIT 1;" ``` @@ -290,7 +307,12 @@ experiment needs size-bin or contiguous-free-region evidence. - Keep separate-event peaks distinct and use `allocator_gap` for same-event comparisons. - Exclude negative synthetic reconstruction events from runtime segment - analysis with `min_id=0` or `id >= 0`. + analysis with the validated non-negative `min_id`/`start_id` (default `0`) + or `id >= `. +- Apply one validated event range across every phase so peaks, the curve, + segment operations, optional aggregates, and attribution inputs share a + single scope; reject negative peak event IDs before attribution instead of + attributing them. - Treat operation counts and size sums as operation volume, not retained bytes. - Event IDs are ordering markers, not timestamps. - Separate evidence, inference, unknowns, classifications/confidence, and @@ -304,6 +326,9 @@ experiment needs size-bin or contiguous-free-region evidence. - Metadata and required templates were verified before diagnosis. - Separate peaks came from `memory_peak`; same-event gaps came from `allocator_gap`. +- The same validated event range was applied consistently to peaks, the + ordered curve, segment operation pairs, optional aggregates, and + attribution inputs. - The allocated/active/reserved curve used paginated, event-ordered `allocation` queries. - Runtime `segment_map`/`segment_unmap` and `segment_alloc`/`segment_free` were diff --git a/tests/test_memory_fragmentation_skill.py b/tests/test_memory_fragmentation_skill.py index 467fb5c..642dead 100644 --- a/tests/test_memory_fragmentation_skill.py +++ b/tests/test_memory_fragmentation_skill.py @@ -39,22 +39,23 @@ def test_memory_fragmentation_skill_uses_paginated_runtime_evidence() -> None: skill = SKILL_PATH.read_text() allocation_command = ( - '--template-use allocation --params \'{"min_id":0,"order_by":"id",' - '"order_dir":"ASC","limit":,"offset":}\'' + '--template-use allocation --params \'{"min_id":,' + '"order_by":"id","order_dir":"ASC","limit":,' + '"offset":}\'' ) assert allocation_command in skill for action in range(4): event_params = ( - f'--template-use event --params \'{{"min_id":0,"action":{action},' - '"order_by":"id","order_dir":"ASC","limit":,' - '"offset":}\'' + f'--template-use event --params \'{{"min_id":,' + f'"action":{action},"order_by":"id","order_dir":"ASC",' + '"limit":,"offset":}\'' ) assert event_params in skill assert "`0=segment_map` and `1=segment_unmap`" in skill assert "`2=segment_alloc` and `3=segment_free`" in skill - assert "negative IDs are synthetic reconstruction events" in skill + assert "negative IDs are synthetic reconstruction events" in " ".join(skill.split()) assert "Event size sums are operation volume, not retained bytes or" in skill @@ -67,7 +68,7 @@ def test_memory_fragmentation_skill_limits_raw_sql_to_read_only_aggregates() -> assert 'sqlite3 -readonly ""' in skill assert "non-negative decimal integer matching" in skill assert "before interpolating it into a table name" in skill - assert "WHERE id >= 0 AND action IN (0, 1, 2, 3)" in skill + assert "WHERE id >= AND action IN (0, 1, 2, 3)" in skill assert "only for segment operation" in skill assert "counts/sizes or maximum observed gaps" in skill assert "No writable SQL is" in skill @@ -88,6 +89,26 @@ def test_memory_fragmentation_skill_limits_raw_sql_to_read_only_aggregates() -> assert re.search(rf"\b{statement}\b", raw_sql, re.IGNORECASE) is None +def test_memory_fragmentation_skill_applies_one_validated_event_range() -> None: + skill = SKILL_PATH.read_text() + + for template in ("memory_peak", "allocator_gap"): + command = f"--template-use {template} --params " "'{\"start_id\":}'" + assert command in skill + + for limitation in ( + "Omit every upper-bound parameter", + "excludes negative synthetic reconstruction rows", + "cannot drive dynamic attribution", + '"end_id":', + '"max_id":', + "AND id <= ", + "reject negative peak event IDs before attribution", + "The same validated event range was applied consistently to peaks", + ): + assert limitation in skill + + def test_memory_fragmentation_skill_preserves_snapshotdb_boundaries() -> None: skill = SKILL_PATH.read_text()