Roadmap: MJWarp collector CUDA graph execution route

目标

把 MJWarp 的完整 collector 生命周期从单 control-step、Python dispatch、部分 host-gated 的执行方式，推进到可审计的 fixed-shape / device-resident / public-contract / bounded CUDA graph 执行：

action
→ physics step
→ termination / reset flags
→ reward / metrics
→ event / command update
→ fixed-width reset
→ observation rebuild
→ replay / inference publication

本 issue 是 roadmap umbrella：只负责串联依赖、记录阶段状态和防止重复开题；每个可实施单元仍必须有独立 issue/PR、验收和当前 head 证据。

固定治理约束

• Manager-Based runtime 仍是唯一训练入口。
• UniLab 不调用 backend-private API；新能力必须先进入 public SimBackend contract。
• 不恢复 legacy NumPy runtime、hidden fallback 或 tensor_runtime switch。
• production reset 必须 fixed-width / mask-driven，不支持 dynamic row topology。
• Torch RNG 语义、transition/replay ordering、episode 统计不能用吞吐结果替代语义验证。
• E2E 性能只使用 run_summary.json:tail_env_steps_per_sec 的 last-100 aggregate；final 单次值只作 diagnostic。
• collector-only benchmark 只能归因，不能作为 E2E acceptance。
• graph capture 的 eager fallback / disable reason 必须进入 run manifest。
• 语义等价和 dependency provenance 不满足时，不得宣称 graph-ready。

当前状态（2026-10-12 第四次更新）

Integration baseline

• UniLab main head：8542371a。
• Production reset 已是 fixed-width mask flow：
  • PR perf(reset): quantify mask-driven reset flow #2287 完成 corrected-head equal-semantics A/B/C 证据；
  • PR perf(reset): remove production dynamic row flow #2292 / perf(reset): replace dynamic rows with packed masks #2294 删除 dynamic reset row lifecycle；
  • perf(mjwarp): quantify removing dynamic reset row flow for CUDA graph safety #2285 / perf(reset): remove production dynamic reset row flow #2288 完成。
• perf(reset): quantify mask-driven reset flow #2287 authoritative evidence：
  • evidence head 4020575b；
  • 36/36 valid canonical/reset-heavy runs；
  • canonical B/A：SAC walk +4.82%，FlashSAC motion +7.16%；
  • reset-heavy B/A：SAC walk +3.95%，FlashSAC motion +7.37%；
  • durable evidence：evidence-2285-current-head，SHA-256 f546d1e6eab5571b31e75d8992bb935b5ee2f330160fd87912dda2c4e09d0961。
• Four canonical SAC/FlashSAC training paths fail after packed-reset integration #2296 暴露并修复 packed reset integration 的四个 canonical entrypoint 失败：
  • unisim fix: make benchmark smoke checks reliable #364 在 MuJoCo HOST_BRIDGE 上实现 production mask-selected reset；
  • unisim CI test job is too heavy for ubuntu-slim and times out on dependency install #365 发布 v1.7.17；
  • UniLab fix(base): stabilize packed mask reset paths #2300 消费 unisim-core>=1.7.17，normalize MJWarp root/motion payload，并修复 MuJoCo PD-gain composition；
  • 四条 SAC/FlashSAC × MuJoCo/MJWarp entrypoint 均已到达 active training。
• diagnostics(runtime): persist MJWarp CUDA graph state in run manifest #2278 graph observability 已完成：
  • feat(training): persist backend tensor runtime diagnostics in run manifest #2298 增加 TorchEnv.get_backend_runtime_diagnostics()；
  • unilab_rl fix: support motrix backend for g1 motion tracking #105 / v1.4.12 将 runtime_manifest.backend_diagnostics 写入 run summary；
  • chore(deps): bump unilab-rl to 1.4.12 in the ROCm profile #2301 的 20,000-iteration MJWarp E2E 显示 cuda_graph enabled；
  • diagnostics(runtime): persist MJWarp CUDA graph state in run manifest #2278 已关闭。
• test(runtime): add CUDA Manager carrier placement contracts #2279 CUDA Manager carrier placement contracts 已由 test(runtime): add CUDA Manager carrier placement contracts #2297 完成并关闭。
• release: publish 100-iteration tail unilab-rl and update UniLab dependency #2281 release/pin 验收已完成：
  • unilab-rl v1.4.12 发布；
  • default 与 ROCm profiles 均 pin 1.4.12；
  • chore(deps): bump unilab-rl to 1.4.12 in the ROCm profile #2301 完成 released-dependency MJWarp E2E；
  • release: publish 100-iteration tail unilab-rl and update UniLab dependency #2281 已关闭。

上游状态

unisim

• 当前依赖：unisim-core>=1.7.17。
• v1.7.16 包含：
  • fixed-width MJWarp mask reset research/production boundary 的初始整合；
  • public packed reset lifecycle；
  • legacy NumPy public training API removal；
  • semantic boundary cleanup。
• v1.7.17 包含：
  • production mask_selected_reset contract；
  • MuJoCo authoritative in-process HOST_BRIDGE mask reset；
  • false-row preservation、selected time/persistent channel reset、authoritative publication；
  • eager full refresh capability；
  • MJWarp production wording / retained device-resident graph implementation。

仍有一个非技术路线 blocker 的 release 文档 caveat：v1.7.16 changelog 写明 2.0.0 是 legacy API removal boundary，但实际移除 public API 的 tag 是 1.7.16。需要上游确认是 changelog 表述错误还是版本策略错误；UniLab 当前按实际发布的 1.7.17 floor 消费。

unilab_rl

• 当前依赖：unilab-rl==1.4.12。
• v1.4.12 包含：
  • last-100 tail throughput summary producer；
  • collector-side runtime_manifest.backend_diagnostics transport；
  • fail-closed runtime manifest schema validation。
• chore(deps): bump unilab-rl to 1.4.12 in the ROCm profile #2301 完成 FlashSAC / G1 motion / MJWarp 20,000 iterations：
  • status completed；
  • tail env steps/s 89,359；
  • backend_diagnostics 显示 mjwarp available，cuda_graph enabled。

当前直接前置：#2306 / Phase 4A hot-path profiling

已关闭的直接前置 #2275 / PR #2302：packed reset ownership

• PR：refactor(reset): sink reset composition into UniSim packed transaction #2302 refactor(reset): sink reset composition into UniSim packed transaction
• head：a61891ba0a573f5d61ea50a4b713526cc2079d5a
• merge commit：f9d744c6；PR / refactor(reset): migrate or sink ResetStateTransaction host composer #2275 已合并并关闭。
• 实现内容：
  • UniSim public packed transaction 成为 reset composition 唯一 owner；
  • 删除 UniLab NumPy-authoritative composer 与 non-packed fallback；
  • 删除 UniLab 对 set_state_tensor_mask / mask_selected_reset / mask_selected_reset_full_refresh 的 composition 依赖；
  • ManagerBasedRlEnv 要求 packed_reset + device_reset_randomization，缺失 fail closed；
  • default 与 ROCm profiles 均使用 unisim-core>=1.7.17、unilab-rl==1.4.12。
• PR body 记录 final head make check / make test / make test-all 通过。

#2302 已满足 Phase 2 的 packed-only ownership / fail-closed / false-row preservation / PD-gain 语义边界。

已关闭的直接前置 #2303 / PR #2305：G1 walk reset 语义回归

PR #2305 已修复并合并：

• 修复 head：7ce25e40；
• merge commit：8542371a；
• G1WalkResetOwnerCfg 现在有效声明 owns_observation_reset=False，G1GaitPhase.reset() 按 mask 执行，恢复 selected-row phase diversity；
• Manager-owned observation/action/reward/metric/curriculum/event/termination reset state 在 post-reset observation 计算前清理，reset row 的 last_action 为零、false row 保持原值；
• focused regression 7 passed；final head make test-all 通过；current-head remote CI / Docs 全部通过；
• Bug: G1 walk reset owner skips phase observation reset and publishes stale action observation #2303 已关闭。

治理结论：fixed-width reset topology 与 reset semantic correctness gate 均已恢复。当前没有任何已知的 reset ownership / reset semantics 直接 blocker，roadmap 进入 #2306 / Phase 4A profiling。

执行路线与当前阶段

Phase 0 — evidence 与 release 基线

状态：完成。

• perf(mjwarp): quantify removing dynamic reset row flow for CUDA graph safety #2285 / PR perf(reset): quantify mask-driven reset flow #2287 corrected-head equal-semantics A/B/C rerun。
• 发布并接入 unilab-rl v1.4.12 last-100 producer。
• chore(deps): bump unilab-rl to 1.4.12 in the ROCm profile #2301 default + ROCm released-pin E2E。
• refactor(entity): shrink public NumPy host surface to explicit adapter internals #2276 / refactor(mdp): fail closed when packed production views are missing #2277 验收关闭。
• Four canonical SAC/FlashSAC training paths fail after packed-reset integration #2296 packed reset integration failure 修复。
• 非阻塞 governance caveat：上游确认 1.7.16 / 2.0.0 legacy API removal 版本口径。

Phase 1 — production fixed-width mask reset

状态：完成。

• PR perf(reset): remove production dynamic row flow #2292 / perf(reset): replace dynamic rows with packed masks #2294：production autoreset 直接使用 done mask。
• perf(reset): remove production dynamic reset row flow #2288：删除 production dynamic reset row lifecycle。
• commands / actions / events / curriculum / observations / root reset / motion reset / metrics / recorders / owner state 迁移到 fixed-width mask semantics。
• unisim fix: make benchmark smoke checks reliable #364 / CI test job is too heavy for ubuntu-slim and times out on dependency install #365 与 UniLab fix(base): stabilize packed mask reset paths #2300 修复 MuJoCo HOST_BRIDGE 与 MJWarp packed reset production path。
• perf(mjwarp): quantify removing dynamic reset row flow for CUDA graph safety #2285 / perf(reset): remove production dynamic reset row flow #2288 / Four canonical SAC/FlashSAC training paths fail after packed-reset integration #2296 关闭。
• fix(env): restore G1 reset observation boundaries #2305 / Bug: G1 walk reset owner skips phase observation reset and publishes stale action observation #2303：修复 G1 observation-reset ownership / phase diversity 与 post-reset last_action ordering，并补齐 partial-mask regression。

注意： reset topology 与已识别的 reset semantic regression 均已收口；这不等于 collector graph-ready，Phase 4 的 host gates 仍存在。

Phase 2 — public packed reset ownership

状态：完成。

已完成：

• unisim public packed reset lifecycle。
• unisim v1.7.17 released。
• PR feat(base): consume packed reset transaction #2289 初步消费 packed transaction。
• fix(base): stabilize packed mask reset paths #2300 修复 production packed reset payload / host-bridge 语义。
• default 与 ROCm dependency profiles 对齐 1.7.17 / 1.4.12。

已由 #2302 完成：

• owner review / merge。
• current-head remote CI 完成（全部通过）。
• 删除 UniLab NumPy-authoritative reset composer。
• 删除 non-packed fallback。
• 确认 selected state、model fields、PD merge、mocap、persistent channels、startup promotion、committed baseline 全部由 public packed transaction 承担。
• refactor(reset): migrate or sink ResetStateTransaction host composer #2275 关闭。

Phase 2 exit criteria

• reset composition 只有 UniSim public packed transaction 一个 owner。
• 缺 capability/method 时 construction-time fail closed。
• CPU HOST_BRIDGE transfer 只在 backend public owner 内发生。
• refactor(reset): sink reset composition into UniSim packed transaction #2302 merge 后 reset/E2E smoke：PR final head 已通过 reset-focused tests、MuJoCo E2E spot check 与 make test-all；fix(env): restore G1 reset observation boundaries #2305 final head 在包含 refactor(reset): sink reset composition into UniSim packed transaction #2302 的 main 上再次通过 focused regressions 与 make test-all。

Phase 3 — graph / placement observability

状态：完成。

• feat(training): persist backend tensor runtime diagnostics in run manifest #2298：TorchEnv.get_backend_runtime_diagnostics() public cold-path boundary。
• unilab_rl fix: support motrix backend for g1 motion tracking #105 / v1.4.12：runtime_manifest.backend_diagnostics。
• chore(deps): bump unilab-rl to 1.4.12 #2299 / chore(deps): bump unilab-rl to 1.4.12 in the ROCm profile #2301：default 与 ROCm pin unilab-rl==1.4.12。
• chore(deps): bump unilab-rl to 1.4.12 in the ROCm profile #2301：代表性 MJWarp run summary 显示真实 cuda_graph.enabled。
• schema malformed diagnostics fail-closed tests。
• test(runtime): add CUDA Manager carrier placement contracts #2297：observation per-env scale、row indexing、alive carrier、noise buffer、packed views/default tables 等 CUDA placement contracts。
• diagnostics(runtime): persist MJWarp CUDA graph state in run manifest #2278 / test(runtime): add CUDA Manager carrier placement contracts #2279 关闭。

后续若 unisim 新增 graph version / eager fallback count，现有 dataclasses.asdict serialization 应自然前向兼容；需要时再补 schema/docs。

Phase 4 — capture 边界内 hot-path 收口

状态：当前 active phase。

Production dynamic rows 已删除，但当前 main 仍有：

• TorchEnv.step() 的 bool(done.any())；
• _reset_done_envs_mask() 的 bool(done.any()) 与 done.sum().item()；
• metrics / termination episode publication 的 masked_select + cpu/item；
• reward log .cpu().tolist()；
• Manager finite validation 的 host bool reduction；
• observation/reward invalid-row diagnostics 的 nonzero()；
• event interval / circular buffer 等 data-dependent row branch；
• Python term-by-term dispatch、timing instrumentation、临时 allocation。

Phase 4A — 当前 production head profiling（下一步）

• perf(mjwarp): establish Phase 4A collector hot-path profiling baseline #2306 建立独立 child issue，固定 profiling head、硬件、driver、CUDA、PyTorch、Warp / MJWarp、unisim 与 unilab-rl 版本记录要求。
• 用 diagnostics(runtime): persist MJWarp CUDA graph state in run manifest #2278 diagnostics 确认真实 cuda_graph.enabled 与 eager fallback 状态。
• 同时采集 training.cuda_process_sharing=null 与 validated mps 两个独立 attribution arm；两种模式的 manifest、latency 分布和 go/no-go 结论不得混用。
• 明确记录 effective collector action block K；当前 SAC / FlashSAC off-policy 语义基线是 K=1，首个 graph candidate 不得隐式改变 action dependency。
• 用 profiler / timing attribution 对齐 collector 生命周期：
  • policy action publication；
  • action apply；
  • physics step；
  • observation / reward / termination / metrics；
  • events / commands；
  • reset mask；
  • packed reset；
  • post-reset observation；
  • replay publication。
• 按 sync kind 分类：bool(any)、.item()、.cpu()、masked_select、nonzero()、global synchronize、allocation、Python branch。
• 输出 ranked bottleneck 表，并明确哪些在候选 capture boundary 内、哪些可以移到 interval/cold path。
• collector-only 结果只用于归因；不作为 E2E acceptance。

Phase 4B — device-resident counters / interval publication

• 将 reset count、episode termination/metrics 聚合改为 device-resident counters 与 interval publication。
• 将 reward/command/curriculum/log publication 移出 capture boundary 或做成 fixed-shape device pack。
• 将 validation 改为 graph-safe，或明确放在 capture 边界外。

Phase 4C — fixed-shape lifecycle packs

• 消除 capture 边界内 data-dependent Python control flow。
• 消除 capture 内 allocation。
• 为 G1 walk / motion 补齐 observation、command、reset、reward、termination fused lifecycle packs。

Phase 4D — profiler 复测与 Phase 5 go/no-go

• 复测 current head，确认 capture candidate 中没有 dynamic-shape op、D2H、host sync、data-dependent Python branch。
• 若 collector 外围开销或 E2E last-100 收益不显著，停止 graph MVP 扩张，保留 hot-path 收口成果。
• 若证据成立，进入 public multi-step / graph lifecycle ADR。

原执行步骤保留为验收导向：

• refactor(reset): sink reset composition into UniSim packed transaction #2302 合并与 Bug: G1 walk reset owner skips phase observation reset and publishes stale action observation #2303 修复完成；基于 diagnostics(runtime): persist MJWarp CUDA graph state in run manifest #2278 diagnostics + profiler 重新归因当前 production head。
• 将 reset count、episode termination/metrics 聚合改为 device-resident counters 与 interval publication。
• 将 reward/command/curriculum/log publication 移出 capture boundary 或做成 fixed-shape device pack。
• 将 validation 改为 graph-safe，或明确放在 capture 边界外。
• 消除 capture 边界内 data-dependent Python control flow。
• 消除 capture 内 allocation。
• 为 G1 walk / motion 补齐 observation、command、reset、reward、termination fused lifecycle packs。

Phase 4 exit criteria

• profiled capture candidate 中没有 dynamic-shape op、D2H、host sync、data-dependent Python branch。
• 语义日志与 episode 统计仍可发布，不能用删除语义换 graph eligibility。
• 每个 fused pack 有 term-level parity 测试。

Phase 5 — public multi-step / graph lifecycle contract

状态：未开始实施；仍是 ADR-level 结构决策。

必须设计：

• public multi-step action carrier，例如 [steps, num_envs, action_dim]。
• per-step done/reset mask 与一个 public completion boundary。
• per-step transition / replay publication 语义。
• inference dependency policy：
  • 预提交 action sequence / rollout replay，或
  • explicit inference overlap policy。
• Warp graph replay、Torch kernels、inference IPC events、replay ingress、learner/collector streams 的 stream/event ownership。
• model/data replacement、model randomization、view rebuild、capacity/sensor inventory 变化的 versioned invalidation。
• Torch RNG graph 消费顺序与 failure semantics。
• fixed K / fixed shape 下的 eager fallback 与 fail-closed 规则。
• CUDA context / MPS 调度与 graph replay 的关系。
• ADR、support matrix、capability report、UniLab/unisim contract tests。

Phase 5 exit criteria

• public API 与 ADR 获得 UniLab/unisim owner 批准。
• multi-step 与 step-by-step 的 transition/reward/reset/replay ordering 有等价性测试设计。
• 无 backend-private probing 或 backend-name branch。

Phase 6 — bounded collector CUDA graph MVP

状态：未开始。

• 固定 K、固定 shape、固定 action dependency policy。
• 先覆盖一个 canonical workload，再扩展第二个。
• unsupported capability / graph invalidation fail closed 或显式 eager fallback。
• graph state、version、fallback 原因进入 diagnostics(runtime): persist MJWarp CUDA graph state in run manifest #2278 manifest contract。
• 语义测试覆盖 transition ordering、episode boundary、final observation、replay ingress、RNG、reset publication。
• stream/event race、非法 capture、pointer invalidation focused tests。
• E2E last-100 aggregate 与 baseline repeated interleaved 比较。
• make check / make test / make test-all。

Phase 6 exit criteria

• graph replay 的语义等价与性能收益均有 released dependencies、当前 head、真实 manifest 证据。
• 无 residual collector process，eager fallback 可解释。
• 性能阈值实施前预注册，不事后调整。

Phase 7 — production closeout

状态：未开始。

• refactor(reset): sink reset composition into UniSim packed transaction #2302 / refactor(reset): migrate or sink ResetStateTransaction host composer #2275 合并关闭。
• 上游确认 unisim breaking-release 版本口径。
• 更新 ADR、用户文档、support matrix、troubleshooting、changelog。
• 用 released environment 重跑两个 canonical workload 与 reset-heavy scenario。
• hot-path / multi-step / graph child issues 关闭。
• roadmap: MJWarp collector CUDA graph execution route #2274 以 roadmap completion 关闭；不得把未实现的 multi-step/graph scope 标记为完成。

Dependency map（当前）

Completed foundation
├── #2124 / #2273 Torch-only runtime
├── #2286 → #2276 / #2277 packed MDP + Entity boundary
├── PR #2287 → #2285 corrected-head mask reset evidence
├── PR #2292 / #2294 → #2288 production fixed-width reset
├── unisim #359/#360/#361/#362/#363 → 1.7.16
├── unisim #364/#365 + UniLab #2300 → #2296 production packed reset fix
├── PR #2289 / #2290 → #2280 tensor-only + packed reset consumption
├── PR #2297 → #2279 CUDA placement contracts
├── PR #2298 + unilab_rl #105 + PR #2299/#2301 → #2278/#2281 diagnostics & release baseline
└── PR #2301 → default/ROCm released-pin MJWarp E2E

Active roadmap
├── #2306 Phase 4A current-head profiler / sync-and-allocation attribution [active]
├── Phase 4B device counters + interval publication
├── Phase 4C fixed-shape lifecycle packs
└── Phase 4D go/no-go before multi-step ADR

Recently completed direct blockers
├── PR #2302 → #2275 packed-only reset composition owner
└── PR #2305 → #2303 G1 observation/action reset semantics

当前 open issue 分类

直接属于本 roadmap

已完成的 direct item：#2275 / PR #2302（Phase 2 packed reset ownership）、#2303 / PR #2305（Phase 1 semantic gate）均已关闭。#2274 继续作为 umbrella，不计入独立 direct implementation item。

不属于本 roadmap 的当前 open issues

• unilab.rl 与 uni_rl 重复实现（dp_launcher / rsl_rl 助手）的漂移风险：需明确属主并加契约测试 #1623、测试耦合 uni_rl 私有符号 _discover_physical_cpu_groups #1589、algo_capabilities 静默缺省：确认有意还是遗漏 #1588、为 uni_rl env 契约增加 runtime_checkable 符合性测试 #1587、跨边界重复工具模块需明确唯一属主（nan_guard/tensor/seed/device） #1586：uni_rl / PPO 边界与契约技术债。
• 标准化 play variant：play_profile 扩展到 DR/noise/push/curriculum 剥离并覆盖全部 play 入口（roadmap #1252 第 3 点遗留） #1499：play variant 标准化。
• drake 后端 contact force 传感器输出世界系净力，与 contact-frame 契约不一致 #1471：Drake contact force 契约。
• docs: 文档以契约规范为导向，用户遇到实际问题仍需读源码——建立用户参考手册层 #706：docs 信息架构。
• perf: Motrix reset 热路径 Rust/motrixsim 边界优化（#679 延伸） #682：Motrix reset 热路径优化。
• Work: add batched exteroceptive sensor support for terrain and parkour tasks #675：batched exteroceptive sensor feature。
• Work: G1 procedural slope rough terrain (Phase 1) #596：G1 procedural slope terrain feature。

这些 issue 不阻塞 MJWarp collector CUDA graph；若后续结果影响本路线，再更新本 dependency map。