Roadmap: 在 G1 walk 与 motion tracking 跑通结构化、自动融合的 NumPy/Numba term

[TATP-233]

Owner summary

当前 G1 walk 与 motion tracking 的 numba_acceleration 是实验性 task-owned 手写路径：term 名单、NumPy dispatch、Numba 数学和整段融合内核分散维护，配置只能有限开关，新增 term 需要同步修改多处。本 roadmap 只在现有 NpEnv 生命周期内建立最小的结构化 term 定义、配置组合和自动 Numba 融合，并以 G1WalkFlat、G1MotionTracking 为双 pilot；不涉及 mjwarp、backend contract、manager、runner 或新 lifecycle。预计 5 个聚焦 child issue / PR。

为什么现在做

• src/unilab/envs/locomotion/g1/joystick.py 与 motion_tracking/common/rewards.py 已有两套字符串 key → NumPy callable dispatch。
• joystick_numba.py 与 motion_tracking/common/numba.py 各自维护固定 TERM_ORDER、per-env 数学和手写融合内核。
• env.numba_acceleration 已进入多个 owner YAML，但目前默认关闭；G1 walk Numba 仍不支持 observation noise。
• 现有局部 parity 测试证明双 pilot 可作为迁移基线，但当前测试使用明确容差，不宣称 bit parity。

最小目标

1. 一个轻量、backend-neutral 的 term 定义与冷路径 plan：稳定 key、类别、参数、输入/output/workspace 声明和 canonical order。
2. NumPy Tier 1 与 Numba Tier 2 消费同一注册项和同一配置；Numba 融合由 plan 自动组装，不再手写整段 if/固定 term 列表。
3. 配置决定已注册 term 的选择和权重；未知非零 term 在初始化/compile 边界 fail closed。
4. scale 保持运行时参数；零 scale 用显式运行时跳过，不声称编译期 DCE。
5. 先跑通 G1WalkFlat 与 G1MotionTracking，再决定是否推广到其他 task。

明确不做

• 与 mjwarp、MuJoCo/Motrix adapter、backend capability 或 support 等级相关的改动。
• 恢复 src/unilab/manager、TaskCompiler、PolicyABI、typed batch/mutation 或第二套 env lifecycle。
• 新 runner、训练入口、checkpoint 格式、sim2sim contract 或常规 CI gate。
• 在本 roadmap 中新增 history、通用 event/DR manager、keyed RNG 或 motion asset fingerprint。
• 一次迁移全部 task，或建设可覆盖所有未来 term 形态的完整大框架。

Owner boundary

• term registry/plan 只处理数组、标量参数和预绑定 workspace，不接收 env/backend 私有对象。
• NpEnv.step()、autoreset、terminal observation 与 task update_state() 编排保持不变。
• motion reference 获取、adaptive sampling、frame advance、clip-end teleport/truncation 继续由 MotionTrackingEnv owner 管理；term plan 只替换数值计算部分。
• asset、selector 和 workspace 仅在 init/plan materialization 冷路径解析或分配。

Child issues

1. Work: 建立最小结构化 term plan 与 NumPy Tier 1 runtime #919 — 建立最小结构化 term plan 与 NumPy Tier 1 runtime。
2. Work: 将 G1WalkFlat NumPy 路径迁移到配置驱动 term plan #920 — 将 G1WalkFlat NumPy 路径迁移到配置驱动 term plan。
3. Work: 将 motion tracking NumPy 路径迁移到配置驱动 term plan #921 — 将 motion tracking NumPy 路径迁移到配置驱动 term plan。
4. Work: 自动组装 Numba 融合内核并接入 G1WalkFlat #922 — 自动组装 Numba 融合内核并接入 G1WalkFlat。
5. Work: 接入 motion tracking 自动 Numba 融合并完成双 pilot 收口 #923 — 接入 motion tracking 自动 Numba 融合并完成双 pilot 收口。

依赖顺序固定为 #919 → #920 → #921 → #922 → #923。前三个是近期可执行项；#922/#923 只有在 Tier 1 contract、数值语义与维护收益得到确认后才启动。

所有 child PR 必须以 refactor/issue-902-mjwarp-squashed-delivery 为 base；不得直接向 main 提 PR。

规模与永久维护成本

• 5 个 child issue、5 个聚焦 PR；每个 child 默认不超过 15 个文件、800 行净手写改动。
• 永久代码：轻量 term registry/plan、NumPy executor、Numba assembler/cache，以及两个 pilot 的注册项。
• 永久测试：schema/fail-closed/canonical order、每个 term 的 NumPy↔Numba 对拍、双 pilot lifecycle parity 和局部 benchmark。
• 不增加专属 CI workflow、长期 raw benchmark artifact 或 issue-specific gate。

总体验收

• 两个 pilot 均由 owner config 选择已注册 reward/observation/termination term。
• 两个 tier 消费同一 resolved plan；未知 term、shape/dtype/workspace 不匹配在冷路径 fail closed。
• 自动融合路径替代两个 pilot 的手写整段 Numba kernel/固定名单维护方式。
• NumPy 与 Numba 的 reward/obs/termination 在冻结容差内一致，step/reset/clip-end 行为不变。
• N=2048/8192 的 Tier 2 SPS 不低于各自迁移前手写 Numba baseline 的 90%。
• 两个 pilot 的首次编译与 cache-hit 数据记录在对应 PR，不进入常规 CI gate。
• 所有 child 通过局部验证和 make test-all 后再创建/更新 PR。

Stop conditions

• 任一 child 超过 15 个文件或 800 行净手写改动。
• 需要修改 backend、runner、NpEnv lifecycle、训练 ABI 或常规 CI。
• 单一 source authoring 无法同时满足 NumPy 开发体验与 Numba 性能，且 paired implementation + 自动 parity 也不足以控制漂移。
• 自动融合在任一 pilot 上低于迁移前 baseline 的 90%，或编译/cache 成本不适合默认维护。
• 第二个 pilot 暴露的抽象需求会演变成通用 manager/compiler；此时暂停并重新确认产品方向。

Supersedes

• Supersedes Design: Typed Term Function (TTF) 协议——兼顾配置文件驱动与 Numba 融合加速的可组合 term 方案 #868；Design: Typed Term Function (TTF) 协议——兼顾配置文件驱动与 Numba 融合加速的可组合 term 方案 #868 保留为历史设计讨论，不再作为执行载体。

[TATP-233]

Roadmap 已完成，按既定依赖顺序交付的 5 个 child issue / PR 均已合入 refactor/issue-902-mjwarp-squashed-delivery：

1. Work: 建立最小结构化 term plan 与 NumPy Tier 1 runtime #919 / PR feat: add structured term plan runtime #924：最小结构化 term contract、resolved plan 与 NumPy Tier 1 runtime。
2. Work: 将 G1WalkFlat NumPy 路径迁移到配置驱动 term plan #920 / PR feat: migrate G1 walk numpy path to term plan #925：G1WalkFlat NumPy 路径迁移至 owner config 驱动 plan。
3. Work: 将 motion tracking NumPy 路径迁移到配置驱动 term plan #921 / PR feat: migrate motion tracking numpy path to term plan #926：G1MotionTracking NumPy reward/termination/actor+critic obs 迁移至同一 plan。
4. Work: 自动组装 Numba 融合内核并接入 G1WalkFlat #922 / PR feat: assemble G1 walk Numba kernel from term plan #927：自动 Numba assembler 接入 G1 walk，删除固定 term order/手写整段 aggregator。
5. Work: 接入 motion tracking 自动 Numba 融合并完成双 pilot 收口 #923 / PR feat: assemble motion tracking Numba plan #928：自动 Numba assembler 扩展 shared preamble/workspace 并接入 motion tracking，删除第二套手写 aggregator。

总体验收

• 两个 pilot 均由 owner config 选择注册 term；NumPy Tier 1 与 Numba Tier 2 消费同一 resolved plan。
• stable key、canonical config order、parameter/input/output/workspace schema、运行时 scale、zero-scale skip 与冷路径 fail-closed 已落地。
• 两个 pilot 的自动 fused prange 路径均替代了固定 TERM_ORDER 和手写 whole-kernel aggregator；noise 仍由 task owner 生成，actor noisy / critic clean。
• 生命周期边界保持：未迁移 NpEnv.step/reset/autoreset、motion reference/sampling、adaptive failure、frame advance、clip-end teleport/truncation 或 final observation。
• G1 walk 8 线程：N=2048 为 25.54M env/s（旧 baseline 116.7%），N=8192 为 29.80M env/s（275.0%）。
• Motion tracking 8 线程：N=2048 为 10.43M env/s（旧 baseline 97.3%），N=8192 为 12.24M env/s（105.5%）。四个 case 均超过 90% gate。
• G1 cold/cache：首次 JIT 3739.109 ms，cache-hit first execute 0.108 ms；Motion cold/cache：首次 JIT 11876.861 ms，cache-hit first execute 0.198 ms。
• 最终 PR feat: assemble motion tracking Numba plan #928 的 make test-all：1667 passed、37 skipped、280 deselected、1 xfailed；Ruff、mypy、Pyright 与 benchmark smoke 通过。
• 所有 child 均遵守单 PR、≤15 文件、≤800 行新增手写代码，并以指定 refactor 分支为 base。
• 未修改 backend contract、runner、训练 ABI、checkpoint、sim2sim 或常规 CI，也未推广到其他 task family。

#868 已关闭并由本 roadmap supersede。至此 #918 的双 pilot 目标全部完成；任何 support 升级、更多 task 推广或更完整框架应另行提出并重新确认，不属于本 roadmap 的隐含授权。

[TATP-233]

已按整理要求重新打开：原 #924–#928 已在 refactor 分支上通过 5 个可回溯 revert 提交撤销，refactor 当前文件树恢复到 #918 启动点 b8ecb79e。

新的独立开发分支 feat/issue-918-numba-independent 已从 b8ecb79e 创建，并将 #924–#928 的净变更压缩为一个提交，等待新的独立 PR review；本 issue 暂不自动关闭。