Skip to content

[FEATURE] 将 MemSnapDump 完整收编为 pt-snap-cli 一等模块(#74 子任务) #80

Closed

Description

@codeasier

功能描述

将 MemSnapDump v0.1.0(SHA 87ea207372e0985790e1a28dab499dccf3c3b9a4)的完整运行能力收编到 pt-snap-cli,由 pt_snap_cli.snapshot 作为一等领域模块维护。

本任务需要:

  • 将当前 pt_snap_cli.vendor.memsnapdump 闭包迁移为 first-party 代码;
  • 补入当前 vendor 闭包缺失的 replay-aware snapshot slicing 能力;
  • 新增正式产品命令 pt-snap split;
  • 迁入有效的上游测试、fixtures 和中英文文档;
  • 删除旧 vendor 目录、vendor lint 排除和不准确的 byte-identical attribution;
  • 不保留 memsnapdump package、console script、module entrypoint 或兼容 shim。

本 Issue 是 #74 的阻塞子任务。完成收编后,#74 的 replay 性能优化应基于新的 pt_snap_cli.snapshot 命名空间继续实施。

使用场景

MemSnapDump 将停止独立演进并关闭公开仓库。当前 pt-snap-cli 只包含最小 vendor 闭包,缺少切片能力、完整测试和准确的治理信息;同时 vendor 树已经包含 SQLite PRAGMA 和查询索引等本地修改,不再符合“无本地修改、与固定 SHA 字节一致”的声明。

如果继续直接在 vendor 树实施 #74,会进一步扩大代码归属、测试覆盖和后续维护风险。先完成一等模块收编,可以建立清晰的所有权、质量门禁和性能优化基线。

期望的实现方式

  • 新建 src/pt_snap_cli/snapshot/,首阶段保留原 base/、simulate/、tools/、util/ 内部结构。
  • 保留现有 pt-snap import 的缓存、metadata、源文件变化检测、临时数据库和原子替换语义。
  • 新增 SplitService 和 pt-snap split,输出可再次 replay 的 pickle/JSON 切片。
  • 从上游固定 SHA 补入 tools/slice_dump,但不迁入旧 Typer/argparse CLI 和独立 packaging。
  • 迁入上游有效行为测试和 5 个真实 snapshot fixtures;删除只验证旧包入口的测试。
  • 新增 PROVENANCE.md,记录原仓库、tag、固定 SHA、MIT 权利确认和本地修改。
  • 将 snapshot 模块纳入 Ruff、Black 和正常 CI 门禁。
  • 本阶段只做行为等价迁移,不顺带修复 allocator、数据库生命周期或参数校验问题。

示例

pt-snap import snapshot.pkl
pt-snap split snapshot.pkl --device 0 --slices 4 --max-entries 15000 --output ./slices

参考资源

验收标准

  • src/pt_snap_cli/vendor/memsnapdump 被完整移除
  • 完整运行能力迁入 pt_snap_cli.snapshot
  • 不提供旧 memsnapdump package、命令或 Python API 兼容层
  • pt-snap import 的现有行为和数据库契约不回退
  • 新增 pt-snap split,pickle/JSON 切片可再次完整 replay
  • 普通、expandable、empty-cache、workspace 和 multi-device 行为通过测试
  • 有效上游测试与 5 个 fixtures 完成迁移
  • 中英文 replay、split、数据库文档完成整合,并提示 pickle 仅用于可信输入
  • provenance、MIT 许可和本地修改记录准确
  • pytest、ruff check .、black --check . 通过
  • 构建 wheel 后,pt-snap import 与 pt-snap split smoke test 通过
  • [FEATURE] 优化 import 路径数据结构,消除 segment/blocks 操作的 O(N²) 退化(子任务 #72-2) #74 benchmark harness 可在新命名空间继续运行

非目标

Activity

  1. codeasier commented on Jul 29, 2026

    @codeasier
    OwnerAuthor

    Verdict: 实质合理,证据充分。

    实测确认

    1. vendor 已不再"字节一致"于固定 SHA

    对照上游 87ea207 拉取对应提交,src/pt_snap_cli/vendor/memsnapdump/tools/adaptors/database/snapshot_db.py 与上游存在未在 ATTRIBUTION.md 中声明的本地改动:

    • __init__ 内追加 PRAGMA journal_mode = MEMORY、PRAGMA synchronous = OFF、PRAGMA cache_size = -65536
    • create_trace_entry_table / create_block_table 各加了一组 create_index(allocated/active/reserved、alloc_event_id/free_event_id/size)

    vendor/memsnapdump/ATTRIBUTION.md 当前明文写"None. The vendored code is intended to be byte-identical",与现状不符——这正是本 Issue 要消解的 attribution 漂移。

    2. 闭包确实缺 replay-aware slicing 能力

    上游同 SHA 下还有 src/memsnapdump/tools/slice_dump/{__init__.py,dump.py,hooker.py} 与 src/memsnapdump/tools/split.py,vendor 闭包内完全没有这两条路径。Issue 中"补入 tools/slice_dump,但不迁入旧 Typer/argparse CLI 和独立 packaging"的范围与上游结构对得上——上游 cli.py、tools/dump2db.py 被显式排除。

    3. fixtures 与 vendor 测试目前不在仓内

    • tests/fixtures/snapshots/ 仅 4 个:memory0.pickle、snapshot_16k_94layers.pickle、snapshot_with_empty_cache.pkl、snapshot_with_multi_devices.pkl。Issue 验收要求的 5 个真实 fixtures(普通/expandable/empty-cache/workspace/multi-device)尚未到齐。
    • tests/ 下没有 tools/、base/、simulate/、util/ 子目录,无任何 vendor 测试文件;上游对应位置有 tests/tools/test_slice_dump*.py 等。

    4. pt-snap import 契约保护到位

    core/import_service.py + core/snapshot_import_backend.py 是稳定适配层(缓存、SHA 校验、原子替换、finalize_temp_db)。把 run_dump_to_db 从 pt_snap_cli.vendor.memsnapdump.tools.adaptors.snapshot2db 改到 pt_snap_cli.snapshot... 是纯路径重写,行为等价迁移可行;Issue 也明确"不修复 strict format、正数参数校验或数据库显式 close",边界合理。

    5. 与 #74 的依赖顺序成立

    #74 的三处优化都打在 vendor/memsnapdump/simulate/{snapshot_mutator,snapshot_lookup,simulated_caching_allocator}.py 上;迁出 vendor 后这些文件不再受"字节一致"约束,#74 的 PRAGMA/索引式改动也不会再被 ATTRIBUTION.md 误标。

    边界核对

    Issue 中"不提供旧 memsnapdump package、命令或 Python API 兼容层"是有意为之——pyproject.toml 里 pt-snap 是唯一 console script,memsnapdump 这个名字从未在 API 表面出现过,无需保留兼容层。

    建议(仅 PR 描述层面,不改代码)

  2. codeasier commented on Aug 5, 2026

    @codeasier
    OwnerAuthor

    Superseded by #81 (merged in 717e3ca).

    PR #81 已合入 main,对照本 Issue 的 12 条验收标准逐项核对均满足:

    • src/pt_snap_cli/vendor/memsnapdump 已完整移除,运行能力迁入 pt_snap_cli.snapshot 一等模块
    • 不保留旧 memsnapdump package、命令或兼容层
    • pt-snap import 行为通过 tests/core/test_import_service.py 验证未回退
    • 新增 pt-snap split(core/split_service.py + CLI),切片可再次 replay,由 tests/core/test_split_service.py 覆盖
    • 普通/expandable/empty-cache/workspace/multi-device 行为通过 tests/snapshot/ 下 14 个测试文件 + 5 类 fixtures 验证
    • 上游有效测试与 5 个 fixtures 完成迁移
    • 中英文 docs/{en,zh}/splitting.md + quickstart 双语文档整合,含 pickle 仅用于可信输入提示
    • src/pt_snap_cli/snapshot/PROVENANCE.md + docs/legal/memsnapdump-mit-relicensing.md + provenance CI 脚本记录准确
    • pytest / ruff check . / black --check . 通过(PR 描述:565 passed, 1 xfail)
    • wheel smoke test 在 Python 3.10-3.13 通过
    • benchmarks/baseline_import.py 已建立 first-party 命名空间基线,[FEATURE] 优化 import 路径数据结构,消除 segment/blocks 操作的 O(N²) 退化(子任务 #72-2) #74 可基于此继续实施

    PR review 提出的 3 条 finding 已由后续 fix commit(d00053d、fcaabda)处理。

    本 Issue 作为 #74 的阻塞子任务已完成,关闭以解锁 #74 后续推进。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions