Work: 单 GPU gpu_resident replay 改为 device-authoritative bounded ingress

[TATP-233]

Parent: #933
Work type: infra
Area: other
Scope: Standard，1 PR；实施前需单独确认本 issue

一句话问题

单 GPU gpu_resident 仍要求 collector 写完整 CPU shared ReplayBuffer._storage，learner 再增量复制到同容量 _gpu_storage；host R 无法释放。

为什么现在做

#901 已确认完整 replay 在 host/device 各分配一次。当前 src/unilab/ipc/replay_buffer.py 负责 collector add，src/unilab/ipc/replay_pipelines/gpu_resident.py 只镜像 host ring；因此不能靠改默认配置消除 host R。PR #806/#898 也表明现有吞吐依赖下一批 replay 工作与当前 learner update 重叠，改存储 owner 不能把 add/H2D/sample 串回 learner 边界。

最小交付结果

单 GPU CUDA/MPS 的 gpu_resident 使用一份完整 device-authoritative replay。collector 只写固定深度、容量无关的 transition ingress slots；device copy 完成后才提交 ptr/size。本 PR 保留旧 CPU pipeline 与配置分支，作为迁移期 fallback。

In scope

• 在 replay owner layer 分离 packed transition 组装、bounded ingress 与完整 device ring；host allocation 只随单次 collection chunk/in-flight slot 数增长，不随 replay capacity 增长。
• collector 在发布 slot 前完成 terminal next obs/critic patch；learner 按 ring span 写 device storage，completion event 完成后再推进 committed pointer，并以 backpressure 防止 slot 被提前复用。
• 保持单 GPU synchronized 与 no_sync_collection 两种现有 collection 模式；保留 learning-start、freshness、ring wrap、seed、hot/cold batch、graph packed layout 行为。
• reward normalization、trace、logger counter 与 NaN 诊断改从 ingress/committed metadata 获取所需数据，不得保留隐藏的 host full replay。
• 保持稳态 add(N+1) → H2D/commit → sample/gather(N+1) 与 update(N) overlap；CUDA 使用安全 side stream/background submission，MPS 仍只由 learner thread 提交 device work。
• 更新 replay 内存预算、定向测试与本 issue 所需的 CUDA/MPS 对比记录；不新增永久 benchmark gate。

Non-goals

• 不处理多 GPU；不删除 cpu_pinned_double_buffer、training.replay_pipeline 或旧测试。
• 不改变 replay freshness、batch schema、learner update、checkpoint、runner lifecycle 或 collection 同步语义。
• 不承诺加速或收敛提升；但相对当前 main gpu_resident 端到端吞吐不退化是合并 gate。
• 不用后台 Metal submission 绕过 MPS learner-thread 约束。

Owner 与预计改动

主 owner：src/unilab/ipc/replay_buffer.py、src/unilab/ipc/replay_pipelines/gpu_resident.py；相邻 owner：off-policy worker/单 GPU runner、memory budget 和对应测试。预计 10–14 个文件、600–800 行净手写改动、1 PR。永久维护项是一个 bounded ingress 状态与 CUDA/MPS 两种已有提交方式，不新增公共 runner contract。

Acceptance criteria

• 改变 replay capacity 的分配测试证明 host replay bytes 不变，device 仅有一份完整 R；首次大额分配前预算分别检查 device R 与 bounded host slots。
• 定向测试覆盖发布顺序、slot backpressure、ring wrap、terminal patch、未 commit 行不可采样、freshness、seed，以及同步/异步 collection。
• trace 证明稳态下一批 add、H2D/commit、sample/gather 落在当前 learner update 窗口；下一 tick 边界不新增同步 add/copy/sample critical path。
• 在固定 commit、同硬件/config/seed/warm-up 下，当前 main 与新实现于单 CUDA和真实 MPS 各至少 5 次越过 ring wrap 的对比；报告逐 run 数据、中位数/IQR。新实现中位数 Steps/s 不低于基线、iteration wall 不高于基线，且 replay boundary wait 不增长。
• 现有 CPU pipeline 仍可选且行为不变；本 PR 通过定向测试和 make test-all。

Stop conditions

若需要 host O(capacity) storage、新 runner/lifecycle 或独立同步协议，预计超过 15 文件/800 行，任一目标硬件稳定吞吐退化，或 MPS 无法同时满足 learner-thread submission 与无退化，暂停并回到 #933 决策，不扩张本 issue。

[TATP-233]

待办：在真实 Mac/MPS 设备上完成 #934 验证

候选实现已推送：

• 分支：feat/issue-934-device-authoritative-replay
• 候选提交：86140391b68e39ff8ae86349e6755c54164b5ffa
• 对比基线：d0adf55cf33bb752d79e258a316a3daf0b3e5866

请在真实 Apple Silicon Mac 上执行以下任务；Linux 主机的 PyTorch 未构建 MPS，不能代替该 gate。

• 确认 torch.backends.mps.is_built() 和 torch.backends.mps.is_available() 均为 True。
• 在候选提交上运行 make test-all。
• 使用同一台设备、配置、seed 和 warm-up，分别对基线与候选各跑 5 次越过 replay ring wrap 的稳态训练。建议与 CUDA 记录保持一致：SAC / G1WalkFlat / MuJoCo、seed 1、512 envs、batch 1024、replay_buffer_n=8、updates_per_step=4、30 iterations、compile disabled、同步 collection。
• 每次取最后 20 iter 的 perf/steps_per_sec、perf/iter_ms、timing/learner_replay_batch_wait_ms 中位数，并报告全部逐 run 数据及组间中位数/IQR。
• 保存 Perfetto trace，确认 MPS device work 仅由 learner thread 提交，稳态下一批 add → device copy/commit → sample/gather 位于当前 learner update 窗口，下一 tick 边界没有新增同步 critical path。
• 补充同步与 training.no_sync_collection=true 的真实 MPS smoke 结果。

通过条件：候选 Steps/s 中位数不低于基线、iteration wall 不高于基线、replay boundary wait 不增长。若 MPS learner-thread submission 无法隐藏工作、吞吐退化，或必须使用后台 Metal submission 才能通过，请停止并在本 issue 报告原始结果，不要绕过约束。

[TATP-233]

真实 Mac/MPS 验证结果（纯 replay IPC）

这里修正验证口径：本次性能结论只覆盖 replay IPC，不把 env/collector 吞吐混进来，也不以 perf/steps_per_sec 或整轮 perf/iter_ms 作为本改动的性能 gate。

环境与回归

• 候选：86140391b68e39ff8ae86349e6755c54164b5ffa
• 基线：d0adf55cf33bb752d79e258a316a3daf0b3e5866
• Apple M5 Max / 128 GB / macOS 26.5.2 / AC power
• PyTorch 2.7.0；torch.backends.mps.is_built() == True，is_available() == True
• 候选 make test-all 通过，耗时 76.36 s：主 pytest 1634 passed, 65 skipped, 1 xfailed；benchmark import smoke 为 32/32 modules、33/33 scripts
• 额外真实 MPS owner tests：28 passed，其中 MPS-specific 8 passed
• 同步 collection 与 training.no_sync_collection=true 各做了 2 iteration 生命周期 smoke，均 exit 0；它们只作为 smoke，不进入下述性能比较

为什么不使用建议的整轮训练数据

建议命令里的 replay_buffer_n=8 与 G1WalkFlat/MuJoCo owner 配置不相容：learning_starts=10、512 envs，训练启动阈值为 10 × 512 = 5120 rows，但 replay capacity 只有 8 × 512 = 4096 rows。learner 因而永远不会开始更新，collector 只会持续覆盖 ring。该次尝试已中止并从结果中排除；它不能产生有效的 Steps/s、iteration wall 或 replay wait 对比。

纯 IPC 方法

无 env、无 MuJoCo、无 collector；直接向 ReplayBuffer 写入固定 seed 的合成 transition，再由 GPUResidentReplayPipeline 执行 copy/commit/gather：

• G1 packed shape：obs 98、action 29、critic 101，合计 430 个 float32
• 每 tick ingress 512 rows，depth 2，capacity 4096
• 配置 batch 1024，symmetry multiplier 2 后实际 replay rows/update 为 512；updates_per_step=4，所以每 tick gather 2048 rows
• seed 1；每个提交各 5 runs × 30 ticks；最后 20 ticks 取稳态中位数
• 每 run 最终 ptr 15360，越过 ring wrap 3 次

串行 IPC：add → copy/commit → gather

单位均为 ms；每格是该 run 最后 20 ticks 的中位数。

Run	基线 total	候选 total	基线 add	候选 add	基线 H2D submit	候选 H2D submit
1	0.89865	0.82642	0.23792	0.20079	0.24702	0.23735
2	0.80231	0.77238	0.22108	0.20204	0.20652	0.20577
3	0.86869	0.68073	0.22040	0.19673	0.24237	0.18621
4	0.82781	0.86017	0.21040	0.21213	0.22538	0.23752
5	0.75708	0.66660	0.20563	0.19733	0.20471	0.17673

组间汇总（5 个 run 中位数 / IQR）：

Metric	基线	候选
total IPC	0.82781 / 0.06638	0.77238 / 0.14569
add	0.22040 / 0.01069	0.20079 / 0.00471
prepare/submit	0.60965 / 0.07021	0.21344 / 0.05142
wait/consume	0.01558 / 0.00188	0.35069 / 0.09335
reported H2D submit	0.22538 / 0.03585	0.20577 / 0.05115

串行总 IPC 中位数候选低约 6.7%。候选把工作从 prepare 阶段移到了 consume，因此串行 wait/consume 单项变大；是否形成下一 tick critical path 由下面的 one-tick prefetch 测试判断。

One-tick prefetch / learner update window

每 tick 在 4 个合成 learner update step（每步 1 ms）期间调用 progress()，并发 synthetic ingress；下一 tick 测量首次 boundary call。逐 run 稳态 boundary call 中位数：

Run	基线 ms	候选 ms
1	1.67638	0.00613
2	1.85383	0.00606
3	1.92271	0.00708
4	2.08250	0.00923
5	1.95144	0.00775
Median / IQR	1.92271 / 0.09760	0.00708 / 0.00162

候选五个 run 的稳态 tick 均为 20/20 在边界调用内立即 ready，且每 tick committed_ptr == visible_ptr。边界调用中位数相对基线下降约 99.6%，没有新增同步 critical path。

Perfetto / 线程归属

保存的 trace：logs/issue934_mps_validation_20260809/perfetto_replay_ipc_overlap_mps.json。

• 29/29 次 synthetic replay/add 与 learner/update_window 时间区间重叠
• 30/30 次 replay_pipeline/ingress_commit 在 learner/main thread；除预热外 29/29 次位于 update window
• 30/30 次 replay_pipeline/gpu_batch_gather_submit 在 learner/main thread；除首批外 29/29 次位于 update window
• transfer manifest 为 device_submission_thread=learner；没有后台 Metal submission thread

Storage

Capacity	实现	Host bytes	MPS device bytes
4096	基线 full-ring host mirror	7,045,120	7,045,120
4096	候选 bounded ingress	1,761,280	7,045,120
8192	候选 bounded ingress	1,761,280	14,090,240

候选 host storage 在 capacity 翻倍时保持不变；4096 capacity 下比基线减少 75%。

结论

候选通过本次真实 MPS 纯 replay IPC gate：串行总 IPC 未退化，prefetch 后下一 tick replay boundary wait 未增长，copy/commit/gather submission 均由 learner thread 在 update window 内完成，并且 host storage 符合 bounded-ingress 目标。

本结果不声称已经完成 collector-dominated 的端到端 Steps/s gate；上述无效整轮配置也未被拿来支持结论。

[TATP-233]

Completed by PR #939, merged into dev/issue-933-gpu-resident-replay at ba47bbb. Linux/CUDA and real Mac/MPS validation evidence is recorded in the PR and issue comments.