roadmap: Genesis 物理后端接入（遵循现有 UniLab 契约）

[TATP-233]

Scope level

roadmap

Work type / area

• Work type: feature + sim
• Area: backend / config / env contract
• Proposed owner: Backend maintainer，协同 Config/Env maintainer（暂不指派）

Owner summary

本 roadmap 只交付 Genesis World 作为 UniLab 一个可选物理后端的正式接入。目标是在不改变现有 NpEnvState、SimBackend、Hydra task owner、registry、env/runner/learner lifecycle 和 checkpoint contract 的前提下，让一个已有 task 能够选择 genesis、完成构造、reset、step，并按已声明的 capability 进行 play/eval。首期只使用现有 g1_walk_flat 作为集成 fixture，不新增 task、不迁移算法、不改其他 backend 的行为。跨物理后端评测、算法/checkpoint 迁移、N-way sim2sim 审计和通用 benchmark/evidence 基础设施是后续独立 roadmap，不属于本 issue。预计 3 个 child issue / PR、约 15–30 个文件、2k–4k 手写 LOC。长期责任是 Genesis adapter、可选依赖与安装诊断、runtime 生命周期、asset/state 映射、能力边界测试和文档。需要 maintainer 确认 Genesis 的支持等级及进程内/隔离进程方案。

推荐方案

采用一个薄的 GenesisBackend 适配层，复用当前 UniLab contract：

1. Genesis 只作为可选 backend identity：task owner 通过 task={task}/{backend} 选择，training.sim_backend 仍只是 owner YAML 的身份字段。
2. adapter 位于 src/unilab/base/backend/genesis/，env/manager 只调用正式 SimBackend，不接触 Genesis 私有对象。
3. Genesis 的 model/asset/name/index 解析只在 init/materialization/cache 完成；step、reset 和 domain randomization 热路径只使用缓存的数值 view。
4. 需要的能力优先复用 SimBackend 现有方法；若发现必须新增公共方法，先暂停并单独更新 ADR/contract issue，不把公共接口塞进 Genesis child。
5. 缺失的 sensor、DR、render 或 playback 能力在最近的冷路径显式 NotImplementedError/contract error；不 warning、no-op、返回零值或回退到其他 backend。

Genesis runtime 方案

建议 Child 1 先比较以下选项，默认优先验证 A。UniLab backend identity 是 genesis，上游包名是 genesis-world。

方案	用户价值	规模与长期成本	建议
A. 进程内薄 adapter	与当前 Python 范围重叠，最少改动即可复用现有 env/runner/play 路径	需处理 Genesis/Quadrants 全局生命周期、设备数组与 NumPy 边界、可选依赖体积	首选
B. 独立 worker/subprocess	隔离全局 runtime、依赖冲突和崩溃	新增 IPC schema、worker 生命周期、设备分配和诊断	仅在 A 被证据否决时采用
C. tensor-native 新 env/runner path	可能减少 host 搬运	新增公共 execution path，违反本 issue 的 contract 边界	排除，另立架构 roadmap

问题与仓库证据

• src/unilab/base/backend/base.py 已定义统一 NumPy SimBackend，涵盖 state、control、sensor、DR、playback 和冷路径 metadata；Genesis 尚未实现该 contract。
• src/unilab/base/backend/init.py 的 create_backend 目前没有 genesis 分支，src/unilab/base/registry.py 的支持 backend 列表也没有 genesis；因此现有 task owner 不能通过正常 Hydra/registry 路径选择 Genesis。
• 现有 task owner 约定是 conf/{algo}/task/{task}/{backend}.yaml，不能通过单独 override training.sim_backend 绕过 owner。
• tests/base/test_backend_conformance.py、tests/base/test_registry.py 和 tests/envs/test_manager_based_rl_env.py 已提供接入后应复用的近风险测试边界。
• scripts/benchmark/physics/benchmark_physics_step_genesis.py 已能用 uv run --with genesis-world 测量 Genesis scene.step()；它只是 Genesis-only physics probe，不等价于 SimBackend、完整 env 或训练支持。已关闭的 benchmark: add cross-backend physics_step throughput coverage for genesis, isaacgym, and mujoco_warp #251 只作为历史 benchmark 记录，不在本 roadmap 重启或扩展。
• 现有 Genesis benchmark 在 scene 之间显式调用 gs.destroy()/gs.init() 并处理 runtime pool 释放，说明 lifecycle 是 adapter 的必测边界。
• Genesis World upstream（2026-08-27 检查 main HEAD 46afc00d，package genesis-world 1.3.3；来源 https://github.com/Genesis-Embodied-AI/genesis-world）声明 Python >=3.10,<3.14、Apache-2.0、MJCF/URDF 导入及 batched simulation；其 Quadrants、MuJoCo 和网格/渲染依赖仍须与 UniLab 验证，不能据此直接声称支持。
• 现有 IsaacGym roadmap roadmap: IsaacGym 后端接入的可行性分析与方案建议 #1332 是独立工作，本 issue 不纳入其他 backend、task 或其 child 的实现。

集成交付结果

完成本 roadmap 后，仓库应能从已有 contract 事实回答：

• GenesisBackend 实现了哪些现有 SimBackend 方法，哪些能力明确 unsupported；
• 一个已有 task（首期为 g1_walk_flat）是否能通过正常 owner YAML/registry 路径构造 Genesis env；
• reset() 是否仍返回 (obs_dict, info_dict)，NpEnvState.obs 是否仍为 dict，step 的 action/state/sensor shape 和 dtype 是否稳定；
• Genesis runtime 缺失、asset 不兼容或能力缺失时，用户是否获得明确的冷路径诊断；
• 现有 MuJoCo、MJWarp、Motrix、Drake、runner、learner 和 checkpoint 行为没有回归。

这项 roadmap 不回答 Genesis 与其他物理后端谁更快、checkpoint 能否跨后端迁移或任务质量是否相同；这些问题留给后续独立 roadmap。

预期数据流：

CLI --algo/--task/--sim
  -> Hydra task owner YAML
  -> registry
  -> ManagerBasedRlEnv / NpEnvState
  -> SimBackend
  -> GenesisBackend
  -> genesis-world runtime

交付边界

In scope

• Child 1 对 genesis-world 版本、安装方式、Python/CUDA/设备组合、MJCF/URDF 导入、batch state、actuator/body/sensor 命名和 cleanup 做可复现 feasibility 研究，并形成逐方法 contract matrix。
• Child 2 实现 src/unilab/base/backend/genesis/ 下的 GenesisBackend，接入现有 factory/registry 和必要的 EnvCfg backend 参数；依赖采用 lazy optional import，不把 Genesis 加入基础安装。
• Child 2 补 fake/mock runtime 测试、SimBackend conformance 参数化、state/control/ sensor/reset/cleanup 的近风险测试；无 Genesis runtime 的机器必须能清晰 skip 或报可操作安装诊断。
• Child 3 只为一个已有 task owner（建议 g1_walk_flat）增加 genesis owner 配置并验证 compose、构造、reset、step 和已有 play/eval 生命周期；不新增 task、reward、算法或 scene family。
• 对现有 Genesis-only physics probe 只做必要的入口/诊断修正；不建设跨 backend benchmark 或新的 evidence/manifest 系统。
• 增加 Genesis 后端安装/运行边界文档，明确 experimental/configured/tested 状态、不支持能力和复现命令。

Out of scope

• 跨物理后端性能评测、任务质量对比、sim2sim checkpoint 迁移或算法迁移。
• N-way sim2sim audit、DENYLIST/WARNING_LIST 重构、通用 benchmark manifest、support evidence 基础设施或新的支持等级。
• IsaacGym、Isaac Sim、Brax 或其他新 backend 的接入；不重写 roadmap: IsaacGym 后端接入的可行性分析与方案建议 #1332。
• 新增 task、reward、command、terrain、algorithm、policy network 或训练超参数 migration；g1_walk_flat 只作为已有 contract 的 fixture。
• 新建 tensor-native env/runner、collector/learner、IPC、checkpoint 格式或权重同步协议。
• Genesis FEM/MPM/粒子多物理、Nyx/其他 renderer、differentiable simulation、全量 camera、完整 DR 或跨平台 production support。
• 把 physics-only probe、短 smoke 或配置存在写成 production support。
• 将 Genesis 私有 model/entity/runtime 对象暴露给 env、manager、runner 或 scripts；热路径不解析 asset/model metadata，也不使用 getattr/hasattr 探测能力。

Child issue 与依赖顺序

本次只创建总体 roadmap；child issue 在 maintainer 确认边界后再逐项创建。依赖顺序为 Child 1 → Child 2 → Child 3；不创建其他 backend/task child。

Child 1 — Research: Genesis runtime 与 SimBackend contract feasibility

主要结果：可复现的 capability matrix 和 go/no-go 决策，不注册 production backend。

• 固定 genesis-world version/commit、安装命令、硬件/驱动/Python 矩阵。
• 逐项验证现有 SimBackend 的 model、actuator、root state、body/link、sensor、control、set_state、reset、DR、materialize、cleanup 和 playback 边界。
• 对比进程内 A 与隔离进程 B；测量必要的 Genesis device array ↔ NumPy 拷贝。
• 明确 MJCF/URDF、keyframe、actuator/body/sensor/index 映射；解析只在冷路径完成。
• 预计 2–6 个文件、≤600 手写 LOC、1 个 research PR/报告。
• Stop：需要新增 runner/env/IPC/checkpoint contract、热路径 asset 解析，或 runtime 无法稳定回收；回到 roadmap 由 maintainer 选择 B、缩小范围或 no-go。

Child 2 — Feature: GenesisBackend contract adapter

主要结果：在不改变 SimBackend 公共接口的前提下，Genesis 可由 factory/registry 构造，且无运行时机器仍可测试。

• 新增 src/unilab/base/backend/genesis/，封装 Genesis import、scene materialize、batch stepping、state/sensor view 和 cleanup。
• 接入 create_backend、supported backend registry、env_backend_kwargs（仅必要字段）和 lazy optional dependency；不修改其他 backend 的数值路径。
• mock/fake runtime 覆盖 action/control、state round-trip、shape/dtype/finite、selected reset、lifecycle 和错误诊断；真实 runtime 测试按环境显式标记。
• 未实现的 capability 在 construction/materialization/playback 最近边界 fail-closed。
• 预计 10–18 个文件、1,200–2,500 手写 LOC、1 个 feature PR。
• Scope review：任何新增 SimBackend 方法、公共异常、IPC 或 tensor-native path 必须先拆 contract/ADR issue。

Child 3 — Config/docs: 一个已有 task 的 Genesis owner 验证

主要结果：现有 g1_walk_flat（或 maintainer 指定的单一已有 task）可通过 task={existing_task}/genesis 选择并完成 env smoke；不新增 task。

• 增加一棵最小 owner YAML，显式声明现有策略 I/O 相关字段；不改算法定义。
• 验证 Hydra compose、registry lookup、ManagerBasedRlEnv 构造、reset/step 和 NpEnvState/env wrapper contract。
• 对 play/eval 只验证已有 lifecycle 能安全进入；Genesis 不支持的 render/play 模式明确报错，不添加新的 playback protocol。
• 更新中英文 backend 文档和必要的支持矩阵现有条目；不建设新的跨 backend 证据系统。
• 预计 5–10 个文件、400–900 手写 LOC、1 个 config/docs PR。

后续方向（不属于本 issue）

Genesis backend 稳定后，另立总体 roadmap 决定是否开展：

1. MuJoCo/Motrix/MJWarp/Drake/Genesis 的统一 physics/env/task benchmark；
2. checkpoint sim2sim 与算法迁移评估；
3. 多 backend 支持矩阵、manifest 和 N-way contract audit；
4. 第二个及后续物理 backend。

上述方向不作为本 issue 的 child、验收条件或开发授权。

Roadmap relationship 与 target branch

• Related architecture roadmap: Roadmap: 将 UniLab 迁移为社区通用的 Manager-Based API #1042
• Existing independent backend roadmap: roadmap: IsaacGym 后端接入的可行性分析与方案建议 #1332（IsaacGym；不纳入本 issue）
• ADR 关联：ADR-0002（backend capability/play）、ADR-0003（task owner/config compose）、ADR-0004（registry bootstrap）；任何新增公共 contract 需另立 ADR/issue。
• Declared base branch: dev/issue-1042-manager-based-api
• Declared base head at proposal time: 59d8251（授权实施前必须重新同步并确认最新 head）
• Planned integration branch after explicit development authorization: dev/issue-1339-genesis-backend
• 每个 child 从最新集成分支创建类型化分支，PR base 指向本 roadmap 集成分支。
• 本 roadmap 最终 PR base 为非 main 的 declared base，因此以最终本地 make test-all + review 为完整 gate；若 declared base 在实施前进入 main，先更新记录再建分支。

规模与 review 计划

子项	文件	手写 LOC	Review owner
Genesis feasibility research	2–6	≤600	Backend/runtime
GenesisBackend adapter	10–18	1,200–2,500	Backend + Env
Existing-task owner/docs smoke	5–10	400–900	Config/Env + docs
合计	约 15–30	约 2k–4k	3 个聚焦 PR

新增公共 SimBackend contract、execution path、IPC 或常规 CI 不计入上述预算，必须单独 issue/ADR 并重新确认范围。

永久维护成本

若 maintainer 将 Genesis 从 experimental/configured 升级为 production，UniLab 将长期承担：

• GenesisBackend 与锁定的 genesis-world version window、lazy optional dependency、安装诊断和上游升级/下线流程；
• Genesis/Quadrants 初始化、销毁、device selection、进程/fork 兼容性和资源回收；
• MJCF/URDF scene、actuator、body、sensor、root state 和 keyframe 的冷路径映射；
• Genesis device array 与 NumPy SimBackend view 的数据搬运、shape/finite 检查和性能回归；
• 已支持 task owner 的 compose、conformance、真实 runtime 测试和中英文文档；
• 明确记录 unsupported capability，不以静默 fallback 维持表面兼容。

本 issue 不承诺常规 GPU CI、全平台支持或跨 backend 维护；若不愿承担上述责任，Genesis 应保持为 research/benchmark adapter，不标 production。

Acceptance criteria

• Maintainer 确认本 issue 只覆盖 Genesis backend，以及 experimental/configured/ tested/production 中的目标等级。
• Child 1 形成固定版本和环境下的 contract capability matrix，并作出 A/B go/no-go。
• 若 go，create_backend("genesis", ...) 通过现有 factory/registry 可用；缺运行时时给出明确、可操作的安装诊断。
• 一个已有 task（默认 g1_walk_flat）可通过正常 owner YAML 路径选择 genesis，完成构造、materialize、reset、step 和 cleanup；不新增 task。
• reset()、NpEnvState.obs、action/state/sensor shape/dtype/finite 与现有 contract 保持一致；现有 backend/runner/learner 无回归。
• Genesis 不支持的 sensor/DR/render/play 能力在最近冷路径 fail-closed。
• env/manager/runner/scripts 不调用 Genesis 私有对象；热路径不解析 asset/model metadata，不使用 getattr/hasattr 探测 backend 能力。
• 中英文文档说明安装、运行命令、支持等级和明确的 unsupported 边界。
• 每个 child 最终 head 运行近风险测试和 make test-all；roadmap 集成 head 再次运行 make test-all。本规划 issue 本身不宣称已通过实现 gate。

Validation plan

• 规划阶段：核对 SimBackend、factory、registry、owner YAML、conformance 测试、Genesis-only probe 和 upstream version evidence。
• Child 1：固定 commit、硬件、驱动、seed 和命令，保存 capability matrix 与失败诊断。
• Child 2：无 Genesis runtime 用 fake/mock 覆盖 contract；有 runtime 再执行真实 materialize/reset/step/cleanup smoke。
• Child 3：对单一已有 task 验证 Hydra compose、registry lookup、env return contract 和已有 play/eval lifecycle；不进行跨 backend 对比。
• 本 issue 只做规划和 issue 管理，不修改代码、不创建 production dependency，也不运行或声称通过最终 PR gate。

Dependencies / blockers / scope review

• genesis-world、Quadrants、PyTorch/CUDA/驱动与现有 UniLab lock/optional extras 的兼容性。
• Genesis 对现有 task-level MJCF/URDF、actuator、sensor、floating root、keyframe、batch state 和 reset 的真实支持。
• Genesis runtime 是否可在同一进程稳定 init/destroy；若不可，是否值得承担 worker lifecycle。
• 可复现实验所需的 Genesis 运行机器；没有 runtime 时必须仍能运行 mock contract tests。

以下发现必须暂停 child 并更新本 roadmap：

• 需要新的 env/runner/learner execution path、checkpoint/IPC protocol 或公共接口；
• 需要引入其他 backend、task、algorithm 或第二个 task fixture；
• 需要跨 backend benchmark、sim2sim、N-way audit、manifest 或常规 GPU CI；
• adapter 规模或永久维护责任明显超过上表；
• Genesis upstream 能力不足，或更小的现有 adapter 方案已经足够。

Authorization

当前请求只提供规划授权：收缩并维护本总体 roadmap issue、记录 Genesis 研究边界和拟议 child。它不授权创建 child issue、集成分支、修改仓库、接入其他任务/后端、安装 production dependency 或开始 Genesis adapter 实现。maintainer 确认 scope、支持等级和 runtime 方案后，才按 roadmap 集成分支工作流创建 Child 1。

[TATP-233]

补充调研：genesis-world 接口事实、执行路径细化与 genesislab 借鉴点

基于 genesis-world 上游源码（本地 checkout main HEAD 19f56d65，package 1.3.3；注意该提交刚拆分 rigid entity 静态描述与运行时状态，属 breaking change，Child 1 的版本钉扎必须精确到 commit）与 genesislab（master 0f2e4d9）的逐文件调研，补充以下设计依据。

一、方案 A（进程内薄 adapter）的上游生命周期证据

• gs.init()（genesis/__init__.py:57）：已初始化再调直接 raise；gs.destroy() 幂等，支持 init→destroy→init 循环（上游单测即此模式），上游自带 atexit.register(destroy)。scene 经 weakref registry 管理，destroy 会回收所有存活 scene 与 quadrants 运行时。多 scene 串行构造/销毁是上游原生支持的用法，方案 A 无生命周期层面的否决项。
• 但有两个必须在 Child 1 实测的宿主副作用：
  1. gs.init 执行 torch.set_default_device(device) 与 torch.set_default_dtype(...)（__init__.py:215-216），会污染宿主进程全局 torch 状态——UniLab learner 与 Genesis 同进程时需评估影响范围与恢复策略。
  2. CPU backend 默认强制 cpu_max_num_threads=1（__init__.py:243-254，可用 QD_NUM_THREADS 覆盖），且 _para_level=NEVER 串行执行；上游明确建议 CPU 上"多进程、每进程单线程"。单进程大批量 env 的 CPU 吞吐定位与 MuJoCo/Motrix 后端不同，需实测后才能写进支持矩阵。
• torch 是硬依赖但不在 install_requires（import 失败即 raise，需 torch>=2.8 手动安装）——Genesis backend 的 lazy optional import 边界（仿 mjwarp 的 dependencies.py 钉版本 + 专属 DependencyError）是必选项，不能省。

二、SimBackend → Genesis API 逐方法映射（Child 1 contract matrix 骨架）

SimBackend 面	Genesis 对应 API	结论
step(ctrl, nsteps)	scene.step()（全局步进，无 per-env step）+ entity.control_dofs_force/position(envs_idx)	可行；与 runner 语义一致
set_state(env_indices, qpos, qvel)	entity.set_qpos / set_dofs_velocity / zero_all_dofs_velocity(envs_idx=...) + set_pos/set_quat(zero_velocity=True)；envs_idx 支持 bool mask	可行
root state 读取	entity.get_pos/get_quat/get_vel/get_ang	可行；注意 relative=True 默认剥离 morph offset
body 运动学	entity.get_links_pos/quat/vel/ang(links_idx_local, envs_idx)	可行
名称→索引	entity.get_joint(name).dofs_idx_local、get_link(name).idx_local	可行，冷路径一次性解析
get_keyframe_qpos	缺口：Genesis 不解析 MJCF <keyframe>（全仓无 key_qpos），初始姿态只读 joint ref/qpos0（genesis/utils/mjcf.py:369）	adapter 须在冷路径用 mujoco 自行解析 mj.key_qpos——与 isaacgym backend 父进程侧 sensors.py 元数据扫描同模式，不引入新契约
actuator/PD	MJCF general actuator 直接导入（gain/bias/gear/forcerange/ctrlrange，utils/mjcf.py:438-495）；control_dofs_position 语义 = kp·(target−pos) − kv·vel	可行；dyntype/非 affine bias 仅 warning，需在 capability matrix 标注
DR	开启 RigidOptions(batch_links_info/batch_dofs_info=True) 后：set_links_mass/COM/inertia、set_dofs_kp/kv/frictionloss/damping/armature、set_friction_ratio(...) per-env；apply_links_external_wrench(...) 单步外力 push	主干可行；batch_*_info 是 build 期开关，属 materialize 冷路径决策，需在 owner YAML 显式声明
sensor	ContactForceSensor / IMUSensor / RaycasterSensor（genesis/engine/sensors/）+ 轻量 get_links_net_contact_force	可行；height scanner 可用 Raycaster grid pattern 或 fail-closed
数组边界	get/set 一律返回 torch.Tensor	见下方搬运策略

另两个配置层事实：MJCF 内的全局 option（timestep/integrator/solver flag）被 Genesis 丢弃（morphs.py:883-886 注释），必须经 owner YAML 显式映射到 SimOptions/RigidOptions——这与 UniLab"backend 旋钮走 owner YAML"的约定天然契合，但也意味着 Child 3 的 owner YAML 必须显式声明这些字段；RigidOptions(enable_mujoco_compatibility=True)（solvers.py:641）提供 MuJoCo 对照模式，Child 1 应用它验证 g1_walk_flat 与 MuJoCo 后端的数值对齐程度。

三、数组搬运策略（执行路径关键决策）

Genesis 是 torch 引擎、UniLab 是 NumPy dict 契约，不要逐 getter 做 tensor.cpu().numpy()。最贴近的范本是现有 mjwarp backend：

• 预分配固定形状 host cache，只在 step/reset 屏障后一次性刷新（_refresh_host_cache），getter 只读 cache、永不触发隐式设备传输；
• 上传/下载集中在显式 _upload/_download/_synchronize 边界。

Genesis 在 zerocopy 模式下部分 get 返回内部 buffer view，CPU backend 下转换成本主要是 torch→numpy 的 dtype/device 边界，Child 1 需实测单次 obs 组装的拷贝开销并写进 go/no-go 证据。

四、控制律归属：Child 1 需要回答的开放问题

两条路径都有上游支持，建议 Child 1 用 g1 数值实测后定：

1. Genesis 内置 actuator（control_dofs_position）：MJCF 导入无损，实现最薄；
2. adapter 侧显式 PD（control_dofs_force + adapter 计算 PD/力矩限制）：控制律与引擎解耦，跨后端数值行为更易对齐。

默认建议优先验证路径 1；若与 MuJoCo 后端的 action 语义（action_scale、PD 增益）对齐有偏差，再退到路径 2。不引入新的 SimBackend 公共方法——两条路径都只用 step(ctrl) 现有面。

五、genesislab 值得借鉴的机制设计（取机制，不取实现）

genesislab 是 Isaac Lab manager 架构在 Genesis 上的轻量复刻（master 0f2e4d9），与本 issue 的 backend adapter 定位不同（它是 tensor-native 全栈），但以下机制设计可直接吸收：

1. init 期一次性名称解析：SceneEntityCfg.resolve() 在建 manager 时把 body/joint regex 一次性解析成 index，全选时降级 slice(None)（components/scene_entity_cfg.py:218）——与 UniLab"asset 元数据只在冷路径"原则完全一致，GenesisBackend 的名称→dofs_idx_local/idx_local 解析应照此收敛在 ctor/materialize 一处。
2. action 处理全 init 预计算：scale/offset/clip 的 regex dict 建 term 时编译成 tensor，热路径只剩一次 affine + clamp。
3. event 三 mode 机制（startup / reset / interval + per-env 计时 + min_step_count_between_reset 节流）：比"reset 时做所有 DR"更通用；Genesis 的 per-env DR API（set_links_mass 等）与该机制的 interval mode 天然匹配，可作为未来 DR plan 映射的参考。
4. actuator 抽象把控制律与引擎解耦：框架侧算 PD/DC motor/延迟/力矩限制，引擎只暴露力接口——对应上文路径 2 的现成参考实现。
5. 算法适配层极薄：env 契约与算法库契约的差异收敛在单个 wrapper 文件（obs dict→TensorDict、dones = terminated | time_outs），UniLab 现有 wrapper 已是此模式，保持即可。

六、genesislab 的反面教训（与本 issue 红线直接对应）

1. 静默 no-op 的 DR 比"不支持"更危险：其 envs/mdp/events/randomization.py 的 randomize_rigid_body_material/mass/com 全是空壳占位，task 配置却照常声明非零随机化范围——配置了但不生效，无任何报错。本 issue 的 fail-closed 原则（缺失能力在最近冷路径显式 NotImplementedError，不 warning、不 no-op）正是对此类问题的正确回答，必须在 GenesisBackend 的 get_dr_capabilities() 中只声明实测生效的能力。
2. 引擎布局常量散落各层：浮动基 base_offset=6（且 Euler 而非 quat）硬编码在 entity data、actuator、scene controller 多处——这是 feature leakage 的典型形态。Genesis 的 qpos 布局（浮动基表达、四元数约定）必须锁在 GenesisBackend 内，对外只暴露 get_root_state_layout 声明的布局。
3. hasattr/getattr 能力探测与 __getattr__ 透传：LabScene.__getattr__ 把未知属性整体透传给底层 gs.Scene，任何上层代码都能摸到引擎私有 API。本 issue 已明确禁止，adapter 内部也不应出现对 Genesis 对象的 hasattr 探测——能力分支只看 RigidOptions 等显式配置。
4. lazy property 直摸引擎、无 step 边界 snapshot：其 LabEntityData 每个 property 每次都调 raw_entity.get_*()。NumPy dict 契约下必须在 step 屏障一次性物化（见第三节），MDP 函数不直接接触后端对象——UniLab 现有架构已满足，adapter 不要破例。
5. init 时真跑 term func 推断维度：要求 env 完全 build 好才能拿 shape，对延迟初始化后端不友好；UniLab 的 obs_groups_spec 声明式维度已是更优解，保持不变。

七、go/no-go 预判（待 Child 1 实证确认）

主干能力（生命周期、batch + envs_idx、MJCF/URDF、PD 三模式控制、per-env DR、contact/IMU/raycaster sensor）在上游 1.3.3 全部存在，方案 A 无明显上游否决项。三大实测风险按优先级排序：

1. gs.init 的宿主 torch 全局污染 + CPU backend 单线程定位（决定 A 是否成立、支持矩阵怎么写）；
2. torch 硬依赖与 UniLab 基础安装的隔离（dependencies.py 懒加载 + extra 的实测安装诊断）；
3. MJCF <keyframe> 缺口（adapter 冷路径用 mujoco 解析 mj.key_qpos 补偿，方案明确、成本低）。

以上调研不改变本 issue 的交付边界与 child 划分，仅为 Child 1 的 capability matrix 提供更具体的验证清单和 Child 2 的结构参照（包骨架仿 src/unilab/base/backend/mjwarp/：__init__ 懒导出 + backend.py + materialization.py + dependencies.py）。

[TATP-233]

开发授权已收到，开始执行。实施前记录更新：

• Declared base branch 不变：dev/issue-1042-manager-based-api；最新 head 已从 proposal 时的 59d82518 重新同步确认为 01f939ed（含 roadmap: IsaacGym 后端接入的可行性分析与方案建议 #1332 IsaacGym 集成分支的合入）。
• 集成分支已创建并推送：dev/issue-1339-genesis-backend（自上述 head）。
• Child 1（feasibility research）issue 已创建：research: Genesis runtime 与 SimBackend contract feasibility（#1339 Child 1） #1372，将按 A/B 对比与 capability matrix 交付 research PR。

支持等级与 runtime 方案仍按 roadmap 建议执行：目标 experimental/configured，Child 1 默认优先验证方案 A（进程内薄 adapter），B 仅在 A 被证据否决时启用。