roadmap: 扩大 Numba 优化并继续降低 Manager-Based update_state 开销

[TATP-233]

Owner summary

继续降低 Manager-Based update_state 的开销，目标是让真实训练 collector 在 MuJoCo 和 MJWarp 上都受益。#1314 的同机 8192-env 复测显示，当前最大 manager 分区是 command_manager.compute（MuJoCo/MJWarp 约 7.25/6.71 ms）、command_manager.post_compute（4.23/4.21 ms）和 observation_manager.compute（4.37/3.85 ms）。推荐按这三个阶段各做一个可独立审查、验证和回退的 child PR：只在现有 task/manager owner 层复用已证明的 Numba 方式；任何 Numba 替代都删除对应 runtime NumPy 数学实现，测试可保留独立 oracle。MJWarp 的 GPU→CPU host-cache D2H/同步已经发生在 backend.step，会纳入真实 env_step_total_ms / step_core_ms，同时单列 backend_host_cache_refresh_ms，不把它重复计入 update_state_ms。本 roadmap 不改 main、dev/issue-1042-manager-based-api、runner/lifecycle、配置 contract、Motrix 或新的通用执行器。预计 3 个 child PR + 1 个集成 PR；永久维护项只有共享 Numba 数学实现、必要的 manager 缓冲和跨后端 parity/benchmark 测试。

为什么现在做

• 评估：Manager-based API 下用 Numba 加速 collector 后处理与 reset 的可行性（基于 #932 复盘） #1292/perf(profiling): motion tracking update_state/reset_done 逐 term profiling（#1292 杠杆 1） #1293 的 profiling 和 perf(managers): Numba 热点、body-state 与 update_state 加速 (#1304, #1316) #1314 的 exact-head 复测已经把剩余大头定位到三个 manager 阶段，而不是此前已优化的五个 motion reward/body-state copy。
• perf(managers): Numba 热点、body-state 与 update_state 加速 (#1304, #1316) #1314 后五个目标 term 合计约占 update_state 6–7%；继续只优化它们的边际收益很小。
• MJWarp 物理很快，manager host 数值路径在真实 collector 中占比更高；忽略 D2H/PCIe 会高估 GPU 后端吞吐。

最小方案与长期边界

1. command_manager.compute：以 g1_motion_tracking 的 MotionCommand metrics/command update 为首个 owner-layer 目标，融合已确认的逐环境数值循环；保留 reset 行为和 CommandTerm contract。
2. command_manager.post_compute：融合 motion relative/body-frame 变换与输出 buffer 写入；删除被替代的 runtime NumPy 数学路径，MuJoCo/MJWarp 共用实现。
3. observation_manager.compute：只优化已由 profiling 证明的批量 copy/clip/scale/concat 或固定 observation owner 路径；不改变 noise、delay、history、NaN policy 或返回 shape contract。

如果一个阶段需要新的公共 backend contract、通用 fused executor、GPU-resident observation/reward、改变 manager lifecycle，立即停止并另开决策 issue；不在本 roadmap 内顺手引入。

MJWarp 统计规则

当前 src/unilab/base/backend/mjwarp/backend.py::_execute_host_step() 的 _refresh_host_cache() 对 pinned host buffers 的 D2H copy 和 synchronize_device() 位于 backend.step() 内，因此 NpEnv.step 的 step_core_ms 与 env_step_total_ms 已包含 GPU→CPU 传输等待。现有 backend_physics_ms 只表示 device step + synchronize，不代表完整后端成本。三个 child 的 benchmark acceptance 必须同时报告：

• env_step_total_ms、step_core_ms、update_state_ms；
• backend_physics_ms；
• backend_host_cache_refresh_ms（D2H/PCIe + host-cache barrier）；
• step_core_ms - backend_physics_ms，并注明其中包含 transfer/upload 等非 physics 成本。

只有在代码证据显示某条统计路径漏掉这段等待时才修改计时实现；不能为了“把 PCIe 算进 update_state”而重复计数。

Child issues（按顺序）

1. #1317：command_manager.compute：MotionCommand metrics/command update 的 Numba-only 批量化（本 roadmap 第一个实施项）。
2. #1318：command_manager.post_compute：relative/body-frame 变换的单一 Numba 数学实现与旧 NumPy 路径删除。
3. #1319：observation_manager.compute：批量 observation pipeline 的有限范围优化，保持 temporal/noise/NaN contract。

每个 child 只承担一个主要结果，从最新 integration branch 派生一个 feat/ 或 perf/ 分支，PR base 为该 integration branch；完成后合入 integration，再从最新 integration 派生下一个 child。每个 PR 创建/更新前在最终 head 运行本地 make test-all；这些 PR 的 base 不是 main，按 #1313 治理规则不等待远程 CI。最终集成 PR 也只进入本 roadmap 的 declared base，不直接写入受保护分支。

Branch declaration

• Declared base branch：dev/issue-1304-motion-numba-body-state，base commit 9cca010d2c97910a6704a3da80b0d7f347103591。
• Planned integration branch：dev/issue-1316-update-state-numba。
• Final destination：后续由现有 perf(managers): Numba 热点、body-state 与 update_state 加速 (#1304, #1316) #1314 流程处理；本 roadmap 执行期间不 checkout、push、merge 或改写 main / dev/issue-1042-manager-based-api。

Non-goals

• 不维护 NumPy + Numba 两套 runtime 数学实现；独立 NumPy 测试 oracle 不属于 runtime fallback。
• 不优化 Motrix，不升级 MotrixSim，不改变 backend support claim。
• 不改 reward/termination 数值语义、Hydra owner/config、runner/lifecycle、learner 或 replay 协议。
• 不新增常规 CI、永久 benchmark 服务、通用编译器或第二套执行路径。

Owner / 规模 / 永久维护

• Owner layer：src/unilab/managers/、src/unilab/tasks/motion_tracking/common/、必要的 scripts/benchmark/rl/ timing/reporting。
• 预计 3 个 Small/Standard child（每个约 3–10 文件、≤600 行净手写改动、1 个 PR）+ 1 个 integration PR；超出预算或跨层时暂停拆分。
• 永久维护：Numba 直接依赖、每个已合入数学 kernel 的唯一生产实现、预分配 buffer、MuJoCo/MJWarp parity 测试和可复现 benchmark 记录。

Acceptance criteria

• 三个 child 各自只改声明的 manager 阶段，并有近风险 parity/contract 测试。
• g1_motion_tracking 的 MuJoCo 与 MJWarp 在同一 host、8192 envs、warmup 10 / measure 100 下给出前后阶段及端到端数据；MJWarp 显式包含并报告 D2H/PCIe 等待。
• 被 Numba 替代的 runtime NumPy 数学实现被移除；没有第二个 production execution path。
• 每个最终 child head 的本地 make test-all 通过，PR body 记录实际命令、base branch 和远程 CI 路由。
• 数值、dtype、输出复用、partial reset、noise/delay/history/NaN policy 与现有 contract 保持一致；若无法保持则停止并回到 maintainer 决策。

Stop conditions

• 预计/实际超出单 child 文件或 LOC 预算，或需要新的公共 contract、runner/lifecycle、GPU resident path。
• 优化只在单一 backend 有效且 MuJoCo/MJWarp 出现稳定回退，或 transfer 统计无法证明没有漏计/重复计数。
• 为了通过测试必须保留第二套 runtime 数学实现，或出现任务/配置范围扩张。

Tracking

• Parent roadmap：本 issue。
• Child issues：#1317、#1318、#1319。
• Milestone：M2 - Manager update_state throughput。
• Related evidence：#1292、#1313、#1314。

[TATP-233]

Roadmap 已完成：#1317/#1320、#1318/#1321、#1319/#1322 均完成本地 make test-all 后合入 integration branch，最终由 #1323 merge 到声明的 base dev/issue-1304-motion-numba-body-state（merge commit 4fa6631a）。

同机 8192-env、warmup 10 / measure 100、固定 seed、三轮直接交错 A/B（9cca010d → final tree）：

• MuJoCo：command_manager.compute -71.30%，command_manager.post_compute -83.60%，observation_manager.compute -5.22%，update_state 19.417 → 10.322 ms（-46.84%），env_step_total 84.087 → 76.056 ms（-9.55%）。
• MJWarp：上述三阶段分别 -74.01% / -86.23% / -5.94%，update_state 17.763 → 8.971 ms（-49.49%），env_step_total 49.853 → 40.943 ms（-17.87%）。
• MJWarp D2H/PCIe host-cache barrier 0.658934 → 0.659782 ms，稳定且已包含在 backend.step()、step_core 和 env total 内，没有重复计入 update_state。

两个数值热点只保留 Numba production 实现，旧 runtime NumPy 数学已移除；observation pipeline 没有适合独立 Numba 调度的数学循环，因此直接减少 ownership copy、finite scan 和 RNG/sanitize 临时数组，没有新增第二条执行路径。Motrix、公共 contract、runner/lifecycle 和配置未改。

最终 integration head d09d05aa 的本地 make test-all：2309 passed、28 skipped、281 deselected、1 xfailed；Ruff、mypy、pyright 和 benchmark import smoke 通过。按 #1313 的 non-main 路由跳过远程 CI。