Skip to content

Architecture: 统一物理后端抽象、manager-based API 与 mjwarp-uni #882

Closed
2 of 2 issues completed
Closed
Architecture: 统一物理后端抽象、manager-based API 与 mjwarp-uni#882
2 of 2 issues completed
Labels
roadmap

Description

@TATP-233
TATP-233
opened on Aug 3, 2026

Work type

architecture / refactor / cleanup / manager API / backend contract

Area

manager-based task API / unified physics backend abstraction / mjwarp-uni / backend adapters / repository and CI simplification

Objective

本 issue 建立 UniLab 下一阶段的统一架构主线：

  1. 收敛统一物理后端抽象，使所有 backend 遵循同一套公开 contract；
  2. 以该物理抽象服务 manager-based task API；
  3. 将 mjwarp-uni 定位为统一 contract 的适配案例和 mjlab 迁移控制变量；
  4. 删除 Work: 统一规划 manager-based task API 与独立 mjwarp 后端 #705 中偏离上述目标的 production device path、性能工程和验收基础设施；
  5. 保持 UniLab 的核心方向：CPU physics simulation 与 accelerator learner 解耦的异构 RL infrastructure。

统一物理后端抽象未来计划独立为名为 unisim 的 package。本 issue 不创建或发布独立 unisim package，也不拆仓库；本 issue 只在 UniLab 内建立清晰、可机械验证、可在未来直接提取的 owner 边界。

Target Architecture

Hydra task owner / registry
            |
            v
UniLab manager-based task API
- TaskSpec / term registry / Typed Term Function
- TaskCompiler / immutable CompiledTaskPlan
- task lifecycle / task state / reference signal
- observation / reward / termination / truncation / event
- policy ABI / history / curriculum
            |
            v
Unified Physics Backend Contract
future extraction target: unisim
- backend identity and capability
- scene materialization
- state/control binding
- placement-aware batch views
- step/reset/mutation
- stable public diagnostics
            |
     +------+------+------+
     |      |      |      |
  mujoco  motrix  drake  mjwarp-uni

所有 backend 经由同一个 factory、binding、step 和 reset contract 工作。Host 与 device buffer 可以具有不同 placement，但不得形成不同的 task、env、runner 或 training lifecycle。

Architectural Principles

One physics contract

  • SimBackend 及其 backend-neutral typed state/control/reset/mutation 类型构成统一物理接口。
  • shared env 与 manager 只能调用公开 physics contract。
  • backend capability 必须显式声明；unsupported 路径 fail closed。
  • backend 不得向 manager 暴露 raw model、data、Warp object 或私有 runtime。
  • backend-specific graph、stream、storage 和 materialization 实现留在 adapter owner 层。
  • 如果某项能力只对一个 backend 有意义且不属于公共物理语义，不将其提升为永久共享 contract。

One task lifecycle

Manager 拥有并统一编排：

  • action preparation；
  • pre-physics event；
  • physics step；
  • terminal state；
  • reward、termination 与 truncation；
  • terminal observation；
  • reset state；
  • task-state、command、curriculum 与 history reset；
  • next-policy observation。

不得为 mjwarp 建立独立 runner、独立 env lifecycle、DeviceManagedRuntime 或 device-only training adapter。

Config-driven manager API

  • term 选择由 owner config 表达；
  • term 实现通过稳定 key 注册；
  • selector、workspace、term order 和 execution tier 在 cold path 编译；
  • term 不接收 env/backend 私有对象；
  • hot path 使用预绑定 state/task/workspace views；
  • Python vectorized Tier 1 用于开发与验证；
  • Numba fused Tier 2 服务 UniLab CPU simulation 主性能路径。

Evidence proportional to stable risk

  • contract、owner boundary、config compose 和 lifecycle 使用小型 owner-level tests；
  • GPU benchmark 和长训练进入手动或定时流程；
  • 不提交大型 raw benchmark/training artifact；
  • 不建立 issue-specific claim inventory、freshness receipt 或永久 Phase gate；
  • 标准 CI 不被单一 backend 的硬件性能结果阻塞。

Owner Boundaries

Unified physics layer owns

  • backend identity、factory protocol 和 versioned capability；
  • scene/materialization 输入；
  • cold-path metadata 与 selector resolution 所需的公开接口；
  • backend-neutral state/control specs；
  • placement、ownership、mutability 和 lifetime；
  • bound state/control/reset/mutation plan；
  • step、reset、state read 和最小 mutation semantic；
  • fail-closed 默认实现与稳定 diagnostics。

该层不得依赖：

  • Hydra 或 owner YAML；
  • UniLab env/task modules；
  • reward、observation、termination term；
  • RSL-RL、learner、checkpoint 或训练脚本；
  • manager policy ABI、task DAG 或 task lifecycle。

本 issue 在当前仓库内整理该边界，并以 import audit 和 private-access audit 保证依赖方向。独立 unisim package 的创建、版本和发布由后续 issue 负责。

Manager layer owns

  • TaskSpec、TermDefinition、TermFuncRegistry 和 PreambleRegistry；
  • TaskCompiler 与 immutable CompiledTaskPlan；
  • semantic selector 到 physics requirements 的编译；
  • task state、reference signal、commands、curriculum 和 history；
  • action、observation、reward、termination、truncation 和 event 编排；
  • terminal/reset/next-policy observation 生命周期；
  • policy ABI、task fingerprint 和 config-driven term composition。

Backend adapter owns

  • 将统一 physics contract 翻译到具体 runtime；
  • 只声明真实支持的 capability；
  • native model/data、stream、graph、cache 和 materialization；
  • runtime 错误到公共 backend 错误的转换；
  • 不通过专属 runner、env hook 或 training entrypoint 绕开统一 lifecycle。

#881 Merge Resolution

#881 的有效架构结论已合并进入本 issue，并以 superseded 关闭。保留内容：

  • MjwarpBackend 应是统一 physics contract 下的薄 adapter；
  • native model/data、stream/event、graph、cache、field materialization 与 recompute 属于 adapter/runtime owner，不向 manager 泄漏；
  • runtime import 不得引入完整 mjlab task/manager/training lifecycle 或顶层副作用；
  • capability、placement/lifetime 与稳定 diagnostics 只有具有公共物理语义时才进入共享 contract；
  • 使用 import/private-access audit 与小型 conformance/differential tests 机械化保护边界。

相对 #881 原方案，本 issue 明确撤销以下前提：

#881 中的 backend 能力比较和 runtime 调研继续作为历史设计依据；后续执行与验收只维护在本 issue。

mjwarp-uni Scope

mjwarp-uni 是统一 physics contract 下的普通 backend adapter。公开 backend identity 继续使用 mjwarp，mjwarp-uni 表示实现与 owner 边界，不新增一套 CLI/config identity。

用途：

  1. 为 mjlab / mujoco-warp 工作迁移提供控制变量；
  2. 验证统一 physics contract 能覆盖 GPU-resident backend；
  3. 作为 manager-based API 的代表性 backend 适配案例。

首期能力范围：

  • scene/model materialization；
  • manager pilot 所需的 state/control binding；
  • placement-aware step 与 selected-row reset；
  • 最小、明确的 capability manifest；
  • 小型 correctness differential；
  • unsupported feature 的显式 fail-closed。

首期不承诺：

  • 优于 mjlab 的性能；
  • Recommended production training path；
  • native render/playback；
  • terrain、Jacobian 或完整 DR；
  • 完整 graph/controller/transfer telemetry 产品面；
  • 独立 mjwarp runtime package。

mjwarp support 等级固定为仓库既有 taxonomy 中的 Configured。不得使用未定义的 Experimental 等级，也不得从单个 pilot 外推更多 task、algorithm 或 backend capability。

#868 Independent Scope

#868 独立保留，作为 Typed Term Function 协议、实现与验收的唯一 owner；本 issue 不复制其详细设计，也不以 umbrella 身份关闭 #868。

本 issue 只约束 #868 与统一物理层的集成边界：

Roadmap

Phase 0: Scope reset and repository cleanup

从 #705 feature branch 开始，删除偏离最终架构的代码和基础设施：

  • Issue Work: 统一规划 manager-based task API 与独立 mjwarp 后端 #705 专属 acceptance manifests、claim inventory、freshness receipts 和 raw artifacts；
  • Issue Work: 统一规划 manager-based task API 与独立 mjwarp 后端 #705 专属 audit/capture/validate 工具及配套 tests；
  • issue-specific full-CI、shard 和 dependency plumbing；
  • host/device/DR/PPO/training-behavior performance gate；
  • mjwarp Recommended support promotion；
  • rsl_rl_device、device runner adapter、DeviceManagedRuntime 和 device-only G1 runtime；
  • runtime_impl: mjwarp_device_v1 路由；
  • train/play/export 中只服务该并行路径的特判；
  • 只服务 production mjwarp graph/controller/transfer/DR performance claim 的代码与测试。

保留：

  • backend-neutral manager spec、registry、compiler、plan、fingerprint 和 reference runtime；
  • backend-neutral physics contract seed；
  • MuJoCo host reference；
  • mjwarp identity、construction 和最小 correctness adapter；
  • backend isolation、public selector、lifecycle 和 numerical parity owner tests。

删除旧 device_resident 路径后，旧 owner YAML、checkpoint、resume 和 playback 请求必须得到显式退役诊断，不得产生 obscure import、attribute 或 shape error。

Phase 0 history rewrite

仅重写 #705 feature branch 历史，不修改 main 或其他远程分支：

  1. 在隔离 clone 中为原 feature branch 创建离线 bundle 备份；
  2. 使用 git filter-repo 或等效工具，仅重写 feat/issue-705-manager-mjwarp 的可达历史；
  3. 清除已提交的大型 raw artifact 路径和已删除的 issue-specific generated evidence；
  4. 保持正常源码提交的顺序与内容；
  5. force-push 更新 Work: 统一规划 manager-based task API 与独立 mjwarp 后端 #705 feature branch 和现有 PR；
  6. 通知该 feature branch 的协作者重新 fetch/reset；
  7. 验证 main 与其他远程分支引用未变化；
  8. 验证重写后 feature branch 的最终 tree 与清理结果一致。

Phase 1: Unified physics contract convergence

  • 精简 SimBackend 公共 surface；
  • 将 typed state/control/reset/mutation 类型保持 backend-neutral；
  • 移除 policy、runner、manager lifecycle 泄漏；
  • 明确 host/device placement 是同一 API 的 buffer 属性，不是执行路径选择器；
  • 所有 backend 使用同一 factory、bind、step、reset 入口；
  • 解除 manager runtime 对 NpEnvState 的反向依赖；
  • 增加 import audit：physics layer 不得 import Hydra、env、training、algo 或 manager；
  • 增加 private-access audit：manager/env/training 不得访问 backend 私有 runtime；
  • 建立小型 backend conformance suite。

该阶段只建立未来 unisim 的可提取边界，不创建独立 package。

Phase 2: mjwarp-uni conformance adapter

  • 将 mjwarp 收敛为统一 physics contract 的普通实现；
  • 删除 manager/device-runner 特有入口；
  • 保留 manager pilot 所需的最小 state/control/reset 能力；
  • 用相同的 placement-aware batch API承载 GPU buffer；
  • 将 mujoco-warp 细节封装在 adapter owner 层；
  • 建立小型 MuJoCo/mjwarp correctness differential；
  • 将 support evidence 与文档统一为 Configured；
  • unsupported feature 在 compile/materialization 边界 fail closed。

Phase 3: Integrate independent #868 TTF Tier 1

Phase 4: Integrate independent #868 TTF Tier 2

Phase 5: CI and extraction readiness

  • 常规 CI 只保留公共 contract、owner tests、import/private-access audit、类型检查和基本 smoke；
  • GPU/mjwarp benchmark 与长训练进入手动或定时 workflow；
  • 删除 issue-specific claim/freshness/provenance infrastructure；
  • 文档 support claim 与 registry/config/test 证据一致；
  • 记录未来提取 unisim 所需的模块清单和依赖图；
  • 独立 unisim package 的创建、版本、发布与拆仓由后续 issue 决策。

Acceptance Criteria

  • 所有 backend 经由同一个公开 physics contract 构造、bind、step 和 reset。
  • Host/device placement 不产生第二套 manager、env、runner 或 training lifecycle。
  • mjwarp-uni 不使用 DeviceManagedRuntime、device-only runner 或专属 task lifecycle。
  • Physics layer 不依赖 Hydra、task、reward、learner、runner 或 manager，并由 import audit 验证。
  • Manager、env 和 training 不访问 backend 私有 model/data/runtime，并由机械化检查验证。
  • Design: Typed Term Function (TTF) 协议——兼顾配置文件驱动与 Numba 融合加速的可组合 term 方案 #868 独立验收完成，且其 TTF/双 pilot 只通过公开 physics contract 与 backend 交互。
  • mjwarp support 为 Configured，不声明 Recommended 或优于 mjlab。
  • 旧 device-resident owner/checkpoint/resume/playback 请求产生显式退役诊断。
  • 标准 CI 不依赖 Work: 统一规划 manager-based task API 与独立 mjwarp 后端 #705 Phase artifact、硬件 fingerprint 或大型 benchmark receipt。
  • 大型 raw evidence 和 issue-specific project-management infrastructure 从当前 tree 删除。
  • 仅 Work: 统一规划 manager-based task API 与独立 mjwarp 后端 #705 feature branch 历史被重写，main 与其他远程分支不变。
  • 当前 physics boundary 具备未来提取为 unisim 的单向依赖结构；本 issue 不创建独立 package。

Non-goals

  • 不创建或发布独立 unisim package。
  • 不拆分仓库。
  • 不将 UniLab 变成另一个 mjlab。
  • 不以 mjwarp GPU simulation 作为 UniLab 异构架构的主要性能卖点。
  • 不保留 Work: 统一规划 manager-based task API 与独立 mjwarp 后端 #705 的 production device-resident profile。
  • 不建立独立 mjwarp runtime package。
  • 不直接引入完整 mjlab.ManagerBasedRlEnv。
  • 不在首轮迁移全部 task 或追求全部 backend feature parity。
  • 不实现 motion-tracking mid-episode teleport。
  • 不建立新的 V2 backend/runner hierarchy。

Related

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    roadmap

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions