refactor: 统一物理后端 contract 收敛 Phase 1 (#888)

[TATP-233]

Summary

执行 #888(#882 Roadmap Phase 1):收敛统一物理后端 contract,建立未来可提取为独立 unisim package 的 owner 边界(只整理边界,不创建独立 package)。

contract 收敛

• 解除 manager runtime 对 NpEnvState 的反向依赖:新增 manager 层 ManagedEnvState(镜像 NpEnvState 字段,归属 manager 层),manager/runtime.py 不再 import np_env;
• 精简 SimBackend 公共 surface:apply_body_linear_velocity_delta 无外部调用方,下沉为 mujoco/motrix adapter 私有方法;
• 措辞 backend-neutral 化:normalize_play_render_mode 错误消息不再引用 training.play_render_mode;get_motion_body_ids 去掉 "MuJoCo-style";BackendTerrainSpawnData 去掉 spawn-manager 措辞;
• placement 语义清理:删除单成员 ExecutionProfile 下不可达的 MemorySpace.DEVICE 死分支(batch.py/mutation.py);placement 保持纯 buffer 属性,各 backend 的 fail-closed profile 守卫保留;
• run_playback(env, ...) 经调查三个实现深度依赖 env wrapper(cfg/playback model/physics-state getter),保守保留签名,docstring 标注为已知边界(列入后续 issue)。

owner 边界机械化(tools/backend_isolation.py)

• import audit(新):src/unilab/base/backend/** 禁止 import hydra/omegaconf/unilab.envs/unilab.training/unilab.algos/unilab.manager/unilab.ipc(运行期与 TYPE_CHECKING 同样禁止);允许依赖进入带注释的 allowlist(dr.types/base.scene/terrains/dtype_config/base.base(TYPE_CHECKING-only)/visualization),每项注明 unisim 提取待决策;
• private-access audit:caller 扫描从 envs/、dr/、np_env.py 扩展到 manager/、training/、scripts/;visitor 精化(getattr 别名追踪、scripts 冷路径公开名带 fallback 探测放行、runtime 层保持严格);两个 manip_loco 诊断脚本全部迁移到公开 SimBackend API(IK 脚本行为实测逐位等价);
• sibling runtime audit:从仅扫 backend.py/batch.py 扩展到包内全部文件;两个既有 sibling 冷路径依赖(drake→mujoco.playback、mjwarp→mujoco.xml)进入文档化例外,迁移留给后续 issue。

conformance suite(新 tests/base/test_backend_conformance.py)

• factory-only 构造断言(AST 扫描 src/,四个 backend 类无绕过 create_backend 的直接实例化);
• 参数化 legacy contract:create_backend → step → set_state → state read(mujoco 全过、motrix 实跑通过、drake 不可用 skip、mjwarp slow 车道);
• 参数化 typed contract:bind_task_io → read_state_batch → bind_mutation_plan+reset_batch → step_batch;motrix/drake 断言干净抛 NotImplementedError(fail-closed 即 conformant);
• 真实仓库 audit_backend_isolation 集成断言。

Acceptance Criteria 对照

• 所有 backend 经由同一个公开 physics contract 构造、bind、step 和 reset(conformance suite 机械化;typed 入口未实现的 backend fail-closed);
• Host/device placement 是同一 API 的 buffer 属性,不产生第二套 manager、env、runner 或 training lifecycle(Phase 0 已删 device lifecycle,本 PR 清理残留死分支);
• Physics layer 不依赖 Hydra、task、reward、learner、runner 或 manager,并由 import audit 验证(真实仓库零违规);
• Manager、env 和 training 不访问 backend 私有 model/data/runtime,并由机械化检查验证(扫描覆盖 manager/env/training/scripts,零违规);
• 小型 backend conformance suite 建立并通过;
• 当前 physics boundary 具备未来提取为 unisim 的单向依赖结构;本 PR 不创建独立 package。

Validation

• 核心测试(沿用用户对本任务序列的指示,跳过 make test-all 中无关测试):tests/base、manager、training、tools、config、envs/locomotion/g1、scripts、dr、utils 共 1123 passed / 0 failed(23 skipped 为 motrix/drake 不可用与 slow 车道 deselect);
• ruff check src/ scripts/ tests/ 通过;mypy src/unilab 267 文件零 issue;
• audit_backend_isolation 真实仓库直跑:ok=True,0 violations(runtime_modules=19, contract_files=126);
• conformance 实测:mujoco legacy+typed 全过,motrix legacy 实跑通过,drake skip,mjwarp slow 车道 deselect(GPU 车道沿用既有 marker);
• make test-all 未完整运行(用户明确指示本任务序列只跑核心测试)。

留给后续 issue(代码注释已标注)

• scene_visual_model_file/scene_artifacts_dir 提升为 SimBackend contract 成员后,收紧 scripts probe 规则;
• drake→mujoco.playback、mjwarp→mujoco.xml 两个冷路径共享工具迁移到 backend-neutral 位置;
• allowlist 各项(dr.types、dtype_config、visualization 等)的 unisim 提取决策;
• run_playback 的 env 依赖重设计(playback contract 归位)。

ADR 关联(契约改动必备)

• ADR-0001(runtime model and layer boundaries):manager/env/backend 分层边界;
• ADR-0002(backend capability boundary for play and snapshot):backend capability 边界与 fail-closed;
• 本 PR 不引入 ADR 未覆盖的新结构决策,无需新增 ADR。

平台/后端行为说明

• mujoco:行为不变(contract 措辞与私有方法下沉,无运行期语义变化);conformance legacy+typed 全过;
• motrix:行为不变,legacy conformance 实跑通过;typed 入口保持既有 fail-closed;
• drake:本机不可用 skip,contract surface 改动对其同为 fail-closed 默认;
• macOS/Linux:仅源码层改动,无平台相关路径变化;audit 与 conformance 为纯静态/CPU 检查。

Refs #888, #882, #705