roadmap: motion tracking Numba 热点与统一 body-state copy 收敛

[TATP-233]

Owner summary

motion tracking 的四个 body reward 已证明是可并行的纯 CPU 数值热点；同时，manager 路径仍对四组 robot body state 做重复 full-batch gather。推荐用三个聚焦 PR 依次收敛：先让四个 reward 与 anchor termination 只走 Numba，再通过统一 Entity/SimBackend copy contract 同时优化 MuJoCo、MJWarp，并暂时适配 Motrix；MotrixSim 发布 selected-body fused 接口后删除临时适配。只改 motion 数值与 body-state 读取，不改 reward 语义、runner/lifecycle、配置或 CI。永久维护项是统一 copy contract、共享 Numba kernel 和数值测试；Motrix 专用 kernel 不是永久责任。

为什么值得做

• perf(profiling): motion tracking update_state/reset_done 逐 term profiling（#1292 杠杆 1） #1293 在 8192 envs 上把 termination/anchor_pos 与四个 reward/motion_body_* 定位为 update_state top5；四个 reward 合计约 4.7–5.0 ms/vector-step。
• 当前 Numba A/B 中，MuJoCo/Motrix/MJWarp 的 update_state 分别下降 13.7%/7.0%/11.1%，说明固定热点值得保留窄口径实现。
• MotionCommand._refresh_robot_state() 当前先经 Entity 的四个 getter 产生高级索引结果，再四次 np.take(out=)。8192×14 的固定输入 probe 为 5.153 ms；直接 combined copy 为 0.718 ms，fused Numba copy 为 0.131 ms。
• SimBackend.copy_body_state_w() 已存在，MuJoCo/Motrix 已有 adapter；缺口是 manager Entity facade 没有消费该 contract，MJWarp 也没有专用 copy 实现。

已确认的方案边界

1. motion_body_pos、motion_body_ori、motion_body_lin_vel、motion_body_ang_vel 的生产路径只保留 Numba 实现；不保留 NumPy runtime fallback。测试可以保留独立 NumPy oracle。
2. MuJoCo 与 MJWarp body-state 优化必须在同一个 child issue 中完成并验证，避免只优化一个 backend。
3. Motrix 在上游接口可用前允许一个明确标注待删除的临时 adapter/kernel；它不形成长期 support contract。上游接口发布后必须通过最后一个 child 删除并收敛到统一 SimBackend copy 路径。
4. 不新增通用 fused executor、第二套 reward execution path、runner/lifecycle、常规 CI 或 support claim。

Issue tree 与执行顺序

上游依赖（UniLab issue）：

• feat(motrix): 提供 selected-body fused world-state 读取接口 #1305：MotrixSim 提供 selected-body fused world-state 接口。它不是 UniLab 临时 kernel 的长期替代实现 PR，而是 child 3 的 blocker。

Implementation sub-issues：

1. perf(motion): 固定五个 update_state 热点改为 Numba-only #1306：Numba-only fixed hot terms。五个固定 term 的唯一生产实现、预热、buffer 复用、数值契约和三后端 benchmark。
2. perf(body-state): 接通统一 copy contract 并同步优化 MuJoCo/MJWarp #1307：Unified body-state copy。仅在 perf(motion): 固定五个 update_state 热点改为 Numba-only #1306 合并且 maintainer 再次确认后开始；新增冷路径 Entity binding，接通 SimBackend.copy_body_state_w()，同步优化 MuJoCo/MJWarp，Motrix 只保留受 feat(motrix): 提供 selected-body fused world-state 读取接口 #1305/refactor(motrix): 接入 fused body-state 接口并删除临时 kernel #1308 约束的临时 adapter。
3. refactor(motrix): 接入 fused body-state 接口并删除临时 kernel #1308：Motrix convergence。Blocked by feat(motrix): 提供 selected-body fused world-state 读取接口 #1305 和 perf(body-state): 接通统一 copy contract 并同步优化 MuJoCo/MJWarp #1307；MotrixSim 接口发布后升级依赖，删除临时 kernel/TODO，统一到正式 copy contract。

每个 child 合并后都必须停止；roadmap 的批准不授权自动执行下一个 child。

分支与 PR

• Integration branch：从当前 dev/issue-1042-manager-based-api 创建 dev/issue-1304-motion-numba-body-state。
• Child 1：perf/issue-1306-motion-hot-numba。
• Child 2：perf/issue-1307-body-state-copy。
• Child 3：refactor/issue-1308-motrix-body-state-convergence。
• 每个 child 从最新 integration branch 新建，一个 child 对应一个 PR，PR base 为 integration branch。
• 每个 PR 最终提交前本地运行 make test-all。按 maintainer 本次明确 override，不等待或要求远程 CI；PR body 必须记录该 override 与本地结果。
• 所有 child 完成后，integration branch 再以单独 PR 回到 dev/issue-1042-manager-based-api。

Non-goals

• 不改变 Hydra reward/config、body subset、termination 或 observation 数值语义。
• 不把 task reward 数学下沉到 backend。
• 不用 Numba 重写 MotrixSim Rust 计算，也不新增 GPU/device-resident reward 路径。
• 不顺带优化 reset、manager finite scan、其他 task 或其他 reward。

预计规模与永久维护成本

• 3 个 implementation issue / 3 个 child PR + 1 个最终 integration PR，另有 1 个 UniLab 上游依赖 issue。
• 每个 child 默认不超过 15 个文件、800 行净手写改动；超限即停止拆分。
• perf(motion): 固定五个 update_state 热点改为 Numba-only #1306：预计 5 文件、≤550 行。
• perf(body-state): 接通统一 copy contract 并同步优化 MuJoCo/MJWarp #1307：预计 8–12 文件、≤700 行。
• refactor(motrix): 接入 fused body-state 接口并删除临时 kernel #1308：预计 4–7 文件、≤400 行。
• 永久维护：Numba 主依赖、四个 reward + anchor kernel、一个 Entity body-state copy contract、MuJoCo/MJWarp 共享 host-copy kernel及 parity/benchmark 测试。
• 临时维护：Motrix adapter/kernel，仅存在到 feat(motrix): 提供 selected-body fused world-state 读取接口 #1305 交付并由 refactor(motrix): 接入 fused body-state 接口并删除临时 kernel #1308 删除；必须带删除 TODO 和 blocker 链接。

Roadmap acceptance

• 四个 body reward 无 NumPy runtime fallback，数值与 body subset contract 有测试。
• MuJoCo/MJWarp 同时走统一的 optimized body-state copy；Motrix 最终无单独 Numba kernel。
• 三后端在 8192 envs、warmup 10 / measure 100 的同机 A/B 有 update_state 与 env/s 报告。
• 每个 child 的本地 make test-all 通过，PR 清楚记录远程 CI override。

Stop conditions

• 任一 child 超过 15 文件或 800 行净手写改动。
• 需要改变 manager/runner lifecycle、reward/config contract 或新增通用执行器。
• Motrix 临时方案开始形成独立长期 API/support claim。
• 数值 parity 无法在明确容差内成立，或三后端 e2e 出现稳定回退。

[TATP-233]

Autonomous execution status（2026-08-25）：

• perf(motion): 固定五个 update_state 热点改为 Numba-only #1306 已由 perf(motion): 固定五个 update_state 热点改为 Numba-only #1309 合入 integration，完成。
• perf(body-state): 接通统一 copy contract 并同步优化 MuJoCo/MJWarp #1307 已由 perf(body-state): fuse selected body cache copies (#1307) #1310 合入 integration，完成。
• feat(motrix): 提供 selected-body fused world-state 读取接口 #1305 曾因发现 MotrixSim 0.10.0 的 get_link_states(indices, out=packed) 而关闭；真实 collector A/B 证明 packed→四输出拆包触发 refactor(motrix): 接入 fused body-state 接口并删除临时 kernel #1308 性能 stop condition，现已重新打开并要求 direct multi-out/wxyz API。
• refactor(motrix): 接入 fused body-state 接口并删除临时 kernel #1308 候选分支 refactor/issue-1308-motrix-body-state-convergence 已完成 0.10.0 pin、正式 API 接入和临时 kernel 删除的本地实验，数值/近风险测试 46 passed；但不会创建 PR，因为 8192-env 三次中位数 update_state 29.718 ms，相对 perf(body-state): 接通统一 copy contract 并同步优化 MuJoCo/MJWarp #1307 的 27.773 ms 回退 7.0%。详细证据见 refactor(motrix): 接入 fused body-state 接口并删除临时 kernel #1308 comment 与 feat(motrix): 提供 selected-body fused world-state 读取接口 #1305。
• integration branch 上的临时 Motrix kernel 仍保留且受 TODO(feat(motrix): 提供 selected-body fused world-state 读取接口 #1305, refactor(motrix): 接入 fused body-state 接口并删除临时 kernel #1308) 约束；没有把候选实验合入。
• 最终指向 dev/issue-1042-manager-based-api 的 integration PR 尚未创建，待 feat(motrix): 提供 selected-body fused world-state 读取接口 #1305 真正交付、refactor(motrix): 接入 fused body-state 接口并删除临时 kernel #1308 通过性能 gate 后才会创建，并仍只留给 maintainer 审批/手动 merge。

[TATP-233]

Scope amendment（2026-08-26，maintainer 明确决定）：

• 本轮跳过 MotrixSim 后端，最终加速与 benchmark acceptance 只覆盖 MuJoCo 和 MJWarp。
• feat(motrix): 提供 selected-body fused world-state 读取接口 #1305、refactor(motrix): 接入 fused body-state 接口并删除临时 kernel #1308 已按 not planned 关闭；不再等待/要求 MotrixSim direct multi-out API，也不升级其依赖。
• 新增替代 cleanup child refactor(motrix): 移除临时 body-state kernel 并退出本轮加速范围 #1311：删除 perf(body-state): 接通统一 copy contract 并同步优化 MuJoCo/MJWarp #1307 留下的 Motrix 专用临时 Numba kernel，恢复正确的非加速 adapter。统一 SimBackend/Entity copy contract 保留，但 Motrix 不形成本轮 performance/support claim。
• perf(motion): 固定五个 update_state 热点改为 Numba-only #1306/perf(motion): 固定五个 update_state 热点改为 Numba-only #1309 与 perf(body-state): 接通统一 copy contract 并同步优化 MuJoCo/MJWarp #1307/perf(body-state): fuse selected body cache copies (#1307) #1310 已完成的 MuJoCo/MJWarp reward + body-state 优化保持不变。
• 最终 integration acceptance：本地 make test-all；同机 8192 envs、warmup 10 / measure 100、各三次 MuJoCo/MJWarp 数据；最终 PR 指向 dev/issue-1042-manager-based-api，只待 maintainer 审批和手动 merge。按既有明确 override 跳过远程 CI。