Refine stack metal seams and ROS batch publishing

Author: AIFlowML

PORT_TO_MLX_TODO.md

@@ -79,7 +79,7 @@ without pausing for replanning after every small success.
 - `DONE` Synthetic cartpole RGB/depth camera slices landed as eval-only mac-native tasks with deterministic analytic `100x100` observations, public MLX wrapper exposure, sensor benchmark coverage, and CI smoke coverage
 - `DONE` Locomotion hotpaths now combine a true Metal-backed root-step kernel with compiled MLX contact/support helpers, and benchmark/semantic reports surface `hotpath: "mlx-metal-root-step"` for the ANYmal-C and H1 slices while Franka keeps its own family-specific hotpath label
 - `DONE` Benchmark coverage for the current mac-native task set now lives behind a stable `current-mac-native` benchmark group enforced by tests and CI
-- `IN PROGRESS` UR10 long-suction and short-suction stack slices are threaded through the public manifest, benchmark runner, direct CLI scripts, README table, and semantic-drift expectations; validation is currently blocked by an import-time `NameError` in `source/isaaclab/isaaclab/backends/mac_sim/manipulation.py` because `MacUR10StackRgbEnv` is defined before its `MacFrankaStackRgbEnv` base class
+- `DONE` UR10 long-suction and short-suction stack slices are threaded through the public manifest, benchmark runner, direct CLI scripts, README table, semantic-drift expectations, and direct train/eval smokes with an honest reduced `7`-action / `40`-observation contract
 - `DONE` Checkpoint/resume and replay contracts are now explicitly covered across the current mac-native task slices
 - `DONE` Maintained kernel inventory now maps the next real Warp/CUDA families to source files, target task classes, and replacement strategies
 - `DONE` Shared MLX task CLIs now cover train and replay/eval flows across the current mac-native slices
@@ -108,6 +108,9 @@ without pausing for replanning after every small success.
 - `DONE` Two more trainable reduced deployment/manipulation slices landed for `Isaac-Deploy-GearAssembly-UR10e-2F140-v0` and `Isaac-Deploy-GearAssembly-UR10e-2F85-v0`, with insertion-aware 19D policy observations, honest `semantic_contract="reduced-analytic-assembly"` metadata, public MLX wrapper/CLI support, benchmark coverage, semantic baseline refresh to `task_count=28`, and a broad backend regression ring at `285 passed, 21 warnings`
 - `DONE` Five more upstream-compatible manipulation aliases now resolve to existing reduced canonical slices without changing the public counts or benchmark groups: `Isaac-Deploy-Reach-UR10e-ROS-Inference-v0` maps to `ur10e-deploy-reach`; `Isaac-Stack-Cube-Franka-IK-Rel-Blueprint-v0` / `Isaac-Stack-Cube-Franka-IK-Rel-Skillgen-v0` map to `franka-stack`; and `Isaac-Stack-Cube-Franka-IK-Rel-Visuomotor-v0` / `Isaac-Stack-Cube-Franka-IK-Rel-Visuomotor-Cosmos-v0` map to `franka-stack-rgb` with explicit reduced-contract metadata across the lazy registry, parsed configs, public wrapper, and installed CLI
 - `DONE` Two new reduced analytic UR10 suction-stack slices landed for `Isaac-Stack-Cube-UR10-Long-Suction-IK-Rel-v0` and `Isaac-Stack-Cube-UR10-Short-Suction-IK-Rel-v0`, with honest 7D action / 40D observation contracts, explicit `semantic_contract="reduced-analytic-suction-stack"` metadata across the lazy registry and public MLX wrapper, corrected three-cube terminal benchmark signatures, a refreshed semantic baseline at `task_count=30`, and a focused UR10 public-surface ring at `139 passed, 21 warnings`
+- `DONE` The reduced pick-place surrogate family now includes `Isaac-PickPlace-GR1T2-Abs-v0` alongside the waist-enabled, G1, nut-pour, and exhaust-pipe aliases, all mapped honestly onto the existing `franka-bin-stack` substrate through the lazy registry, parsed env configs, public MLX wrapper, and installed CLI without inflating the canonical public task counts
+- `DONE` Franka stack family hotpaths now carry dedicated family-specific Metal labels across backend diagnostics, benchmarks, and semantic drift: `franka-stack` reports `mlx-metal-franka-stack`, while `franka-stack-rgb` and `franka-bin-stack` report `mlx-metal-franka-stack-rgb` instead of reusing the generic Franka end-effector label
+- `DONE` Planner/ROS batch helpers now explicitly reject mixed topic-root batches in tests, keeping `batch_index` ordering semantics honest for both planner world-state and joint-trajectory envelopes
 
 ## Phase A: Import And Packaging Safety
 

README.md

@@ -42,14 +42,14 @@ What works today:
 - a runnable `MLX + mac-sim` H1 rough locomotion slice with procedural wave terrain, analytic height scans, deterministic replay coverage, and corrected rough observation sizing for the shared H1 policy path
 - trainable rough locomotion slices for ANYmal-C and H1 with shared PPO/checkpoint contracts, replay support, and CI smoke coverage
 - a Metal-backed locomotion root-step helper for the ANYmal-C and H1 slices, with benchmark and semantic-drift diagnostics that report `hotpath: "mlx-metal-root-step"` when that narrow kernel is active
-- trainable `MLX + mac-sim` Franka reach, cube-lift, teddy-bear lift, instance-randomized two-cube stack, two-cube stack, three-cube stack, bin-anchored three-cube stack, cabinet-drawer, and open-drawer slices with deterministic analytic kinematics, lightweight grasp/open/stack logic, and benchmark diagnostics that now report `hotpath: "mlx-metal-ee"` for the shared Franka end-effector path when the Metal kernel is available
+- trainable `MLX + mac-sim` Franka reach, cube-lift, teddy-bear lift, instance-randomized two-cube stack, two-cube stack, three-cube stack, bin-anchored three-cube stack, cabinet-drawer, and open-drawer slices with deterministic analytic kinematics, lightweight grasp/open/stack logic, and family-specific benchmark diagnostics that now distinguish `hotpath: "mlx-metal-ee"` for the shared Franka end-effector path, `hotpath: "mlx-metal-franka-stack"` for the two-cube stack seam, and `hotpath: "mlx-metal-franka-stack-rgb"` for the three-cube/bin-stack seam when those narrow Metal helpers are available
 - trainable `MLX + mac-sim` OpenArm reach, bimanual reach, cube-lift, and open-drawer slices with explicit reduced-contract metadata, deterministic analytic surrogate kinematics, and replay/checkpoint support through the same public MLX wrapper and installed CLI surface
 - trainable `MLX + mac-sim` UR10 reach and UR10e deploy-reach slices with deterministic analytic pose tracking, reduced-contract metadata (`semantic_contract="reduced-analytic-pose"`), benchmark coverage, and replay/checkpoint support through the same public MLX wrapper and installed CLI surface
 - trainable `MLX + mac-sim` UR10e gear-assembly slices for the Robotiq 2F-140 and 2F-85 grippers with explicit reduced-contract metadata (`semantic_contract="reduced-analytic-assembly"`), insertion-aware policy observations, benchmark coverage, and replay/checkpoint support through the same public MLX wrapper and installed CLI surface
 - upstream-compatible Franka reach/lift/stack/open-drawer controller variants now resolve through the lazy task registry, public `isaaclab_rl.mlx` wrapper, and installed MLX CLI onto the existing reduced mac-native slices instead of failing on macOS import/runtime seams
 - upstream-compatible `Isaac-Deploy-Reach-UR10e-v0`, `Isaac-Deploy-Reach-UR10e-Play-v0`, and `Isaac-Deploy-Reach-UR10e-ROS-Inference-v0` identifiers now resolve through the same lazy registry, public wrapper, and installed CLI onto the canonical `ur10e-deploy-reach` slice while keeping the reduced-contract metadata explicit
 - upstream-compatible `Isaac-Deploy-GearAssembly-UR10e-2F140-v0`, `Isaac-Deploy-GearAssembly-UR10e-2F140-Play-v0`, `Isaac-Deploy-GearAssembly-UR10e-2F85-v0`, and `Isaac-Deploy-GearAssembly-UR10e-2F85-Play-v0` identifiers now resolve through the same lazy registry, public wrapper, and installed CLI onto the canonical `ur10e-gear-assembly-2f140` and `ur10e-gear-assembly-2f85` slices while keeping the reduced-contract metadata explicit
-- upstream-compatible `Isaac-Stack-Cube-Franka-IK-Rel-Blueprint-v0`, `Isaac-Stack-Cube-Franka-IK-Rel-Skillgen-v0`, `Isaac-Stack-Cube-Franka-IK-Rel-Visuomotor-v0`, and `Isaac-Stack-Cube-Franka-IK-Rel-Visuomotor-Cosmos-v0` now resolve through the same lazy registry, public wrapper, and installed CLI onto the canonical `franka-stack` or `franka-stack-rgb` slices with explicit reduced-contract metadata instead of pretending blueprint / skillgen / visuomotor / Cosmos subsystem parity; the upstream `Isaac-Stack-Cube-Bin-Franka-IK-Rel-Mimic-v0` alias remains the reduced public `franka-bin-stack` exception with explicit `semantic_contract="reduced-no-mimic"` metadata
+- upstream-compatible `Isaac-Stack-Cube-Franka-IK-Rel-Blueprint-v0`, `Isaac-Stack-Cube-Franka-IK-Rel-Skillgen-v0`, `Isaac-Stack-Cube-Franka-IK-Rel-Visuomotor-v0`, and `Isaac-Stack-Cube-Franka-IK-Rel-Visuomotor-Cosmos-v0` now resolve through the same lazy registry, public wrapper, and installed CLI onto the canonical `franka-stack` or `franka-stack-rgb` slices with explicit reduced-contract metadata instead of pretending blueprint / skillgen / visuomotor / Cosmos subsystem parity; the upstream `Isaac-Stack-Cube-Bin-Franka-IK-Rel-Mimic-v0` alias and the reduced pick-place surrogates `Isaac-PickPlace-GR1T2-Abs-v0`, `Isaac-PickPlace-GR1T2-WaistEnabled-Abs-v0`, `Isaac-PickPlace-G1-InspireFTP-Abs-v0`, `Isaac-NutPour-GR1T2-Pink-IK-Abs-v0`, and `Isaac-ExhaustPipe-GR1T2-Pink-IK-Abs-v0` remain explicit reduced-contract exceptions instead of pretending scene parity
 - a first mac-native analytic terrain raycast / height-scan sensor substrate for locomotion tasks
 - eval-only synthetic cartpole RGB/depth camera slices with deterministic analytic `100x100` observations, upstream-aligned reset ranges, and sensor benchmark coverage
 - a backend-local macOS external stereo camera discovery/capture path for UVC devices such as ZED 2i, including a live Terminal-hosted `zed-sdk-mlx` validation path for macOS TCC-safe raw capture
@@ -121,7 +121,7 @@ The kernel backend isolates Warp and future Metal custom-kernel paths:
 
 Today the public MLX tasks mostly use pure MLX ops plus compiled MLX helpers. The explicit kernel selection seam now has narrow Metal-backed helpers on both the Franka end-effector path and the shared locomotion root-step path, so future kernels can keep landing without rewriting task-facing APIs again.
 
-For the current locomotion slices, the shared root-step integrator now runs through a Metal-backed MLX kernel and benchmark diagnostics surface that as `hotpath: "mlx-metal-root-step"` when that narrow helper is active, while the remaining locomotion contact/support helpers stay on compiled MLX. For the Franka manipulation slices, the shared analytic end-effector kinematics helper continues to surface `hotpath: "mlx-metal-ee"` when that narrow helper is active, otherwise each family falls back to its compiled MLX helper path.
+For the current locomotion slices, the shared root-step integrator now runs through a Metal-backed MLX kernel and benchmark diagnostics surface that reports `hotpath: "mlx-metal-root-step"` when that narrow helper is active, while the remaining locomotion contact/support helpers stay on compiled MLX. For the Franka manipulation slices, the shared analytic end-effector helper still reports `hotpath: "mlx-metal-ee"` for reach/lift/cabinet/open-drawer tasks, while the two-cube stack seam reports `hotpath: "mlx-metal-franka-stack"` and the three-cube/bin-stack seam reports `hotpath: "mlx-metal-franka-stack-rgb"` when those dedicated Metal helpers are active.
 
 ## MLX Quick Start
 
@@ -833,10 +833,10 @@ The cartpole path preserves the important upstream task semantics:
 - Franka open-drawer preserves the reduced analytic drawer substrate while exposing the manager-style public task ID, deterministic handle-distance/open-distance terminal metrics, and the same train/replay/checkpoint contract as the other Franka slices
 - OpenArm open-drawer preserves the reduced analytic drawer workflow with OpenArm-surrogate reduced-contract metadata, deterministic handle-distance/open-distance terminal metrics, and the same train/replay/checkpoint contract as the other manipulation slices
 - upstream-compatible reach/lift/stack/open-drawer controller variants plus the `Isaac-Deploy-Reach-UR10e-v0` / `Isaac-Deploy-Reach-UR10e-Play-v0` / `Isaac-Deploy-Reach-UR10e-ROS-Inference-v0` deploy aliases now normalize to canonical MLX task keys in the public wrapper and installed CLI, so the mac-native surface stays recognizable without pretending separate controller-physics or deployment-runtime parity
-- upstream task IDs that name heavier policy, model, or process layers now either normalize to explicit reduced-contract aliases or stay isaacsim-only. The supported reduced aliases here are `Isaac-Stack-Cube-Franka-IK-Rel-Blueprint-v0`, `Isaac-Stack-Cube-Franka-IK-Rel-Skillgen-v0`, `Isaac-Stack-Cube-Franka-IK-Rel-Visuomotor-v0`, `Isaac-Stack-Cube-Franka-IK-Rel-Visuomotor-Cosmos-v0`, `Isaac-Deploy-Reach-UR10e-ROS-Inference-v0`, and `Isaac-Stack-Cube-Bin-Franka-IK-Rel-Mimic-v0`; all keep explicit reduced-contract metadata instead of pretending blueprint / skillgen / visuomotor / Cosmos / ROS-inference parity
+- upstream task IDs that name heavier policy, model, or process layers now either normalize to explicit reduced-contract aliases or stay isaacsim-only. The supported reduced aliases here are `Isaac-Stack-Cube-Franka-IK-Rel-Blueprint-v0`, `Isaac-Stack-Cube-Franka-IK-Rel-Skillgen-v0`, `Isaac-Stack-Cube-Franka-IK-Rel-Visuomotor-v0`, `Isaac-Stack-Cube-Franka-IK-Rel-Visuomotor-Cosmos-v0`, `Isaac-Deploy-Reach-UR10e-ROS-Inference-v0`, `Isaac-Stack-Cube-Bin-Franka-IK-Rel-Mimic-v0`, `Isaac-PickPlace-GR1T2-Abs-v0`, `Isaac-PickPlace-GR1T2-WaistEnabled-Abs-v0`, `Isaac-PickPlace-G1-InspireFTP-Abs-v0`, `Isaac-NutPour-GR1T2-Pink-IK-Abs-v0`, and `Isaac-ExhaustPipe-GR1T2-Pink-IK-Abs-v0`; all keep explicit reduced-contract metadata instead of pretending blueprint / skillgen / visuomotor / Cosmos / ROS-inference / pick-place scene parity
 - the first mac-native sensor slice is an analytic terrain raycast / height-scan path for locomotion benchmarks
 - the `sensor-mac-native` benchmark rows now cover the synthetic cartpole RGB/depth camera tasks plus `height_scan_enabled=True` variants of the ANYmal-C and H1 flat locomotion tasks
-- benchmark and semantic drift reports now surface `hotpath: "mlx-metal-root-step"` for the locomotion root-step seam when active, `hotpath: "mlx-metal-ee"` for the Franka reach/lift/stack/stack-RGB/cabinet slices when the Metal end-effector helper is active, and keep the remaining helpers explicit when they stay on compiled MLX
+- benchmark and semantic drift reports now surface `hotpath: "mlx-metal-root-step"` for the locomotion root-step seam when active, `hotpath: "mlx-metal-ee"` for the Franka reach/lift/cabinet/open-drawer seam, `hotpath: "mlx-metal-franka-stack"` for the two-cube stack seam, and `hotpath: "mlx-metal-franka-stack-rgb"` for the three-cube/bin-stack seam when those dedicated helpers are active, while keeping the remaining helpers explicit when they stay on compiled MLX
 - the first backend-local mac camera slice is a UVC/AVFoundation discovery path plus raw stereo YUYV depth smoke, with live hardware validation kept host-specific
 
 ## Bootstrapping Upstream Sources

scripts/benchmarks/mlx/baselines/semantic-baseline.json

@@ -1,5 +1,5 @@
 {
-  "generated_at": "2026-03-20T02:04:47Z",
+  "generated_at": "2026-03-20T02:44:39Z",
   "git_sha": null,
   "hardware_label": "darwin-arm64",
   "parameters": {
@@ -204,7 +204,7 @@
     "franka-bin-stack": {
       "contract": {
         "action_dim": 8,
-        "hotpath": "mlx-metal-ee",
+        "hotpath": "mlx-metal-franka-stack-rgb",
         "observation_dim": 45,
         "output_signature": {
           "final_active_is_top_ratio": 0.0,
@@ -331,7 +331,7 @@
     "franka-stack": {
       "contract": {
         "action_dim": 8,
-        "hotpath": "mlx-metal-ee",
+        "hotpath": "mlx-metal-franka-stack",
         "observation_dim": 33,
         "output_signature": {
           "final_cube_distance_mean": 0.4998617172241211,
@@ -360,7 +360,7 @@
     "franka-stack-instance-randomize": {
       "contract": {
         "action_dim": 8,
-        "hotpath": "mlx-metal-ee",
+        "hotpath": "mlx-metal-franka-stack",
         "observation_dim": 35,
         "output_signature": {
           "final_cube_distance_mean": 0.4969131052494049,
@@ -391,7 +391,7 @@
     "franka-stack-rgb": {
       "contract": {
         "action_dim": 8,
-        "hotpath": "mlx-metal-ee",
+        "hotpath": "mlx-metal-franka-stack-rgb",
         "observation_dim": 42,
         "output_signature": {
           "final_active_is_top_ratio": 0.0,

scripts/benchmarks/mlx/benchmark_mac_tasks.py

@@ -25,6 +25,7 @@
     detect_cpu_fallback,
     get_runtime_state,
 )
+from isaaclab.backends.mac_sim.hotpath import get_franka_stack_hotpath_backend
 from isaaclab.backends.mac_sim import (
     DEFAULT_HEIGHT_SCAN_OFFSETS,
     MacAnymalCFlatEnv,
@@ -378,6 +379,14 @@ def _franka_output_signature(env: Any, trace: Any) -> dict[str, float]:
     return payload
 
 
+def _franka_stack_diagnostics(env: Any, trace: Any) -> dict[str, Any]:
+    """Capture diagnostics for stack tasks with the stack-specific hotpath label."""
+
+    diagnostics = mac_env_diagnostics(env, rollout_summary=trace.summary())
+    diagnostics["sim_backend"]["subsystems"]["hotpath"] = get_franka_stack_hotpath_backend()
+    return diagnostics
+
+
 def _openarm_bi_output_signature(env: Any, trace: Any) -> dict[str, float]:
     """Capture compact semantic signatures for the reduced bimanual OpenArm reach slice."""
 
@@ -994,7 +1003,7 @@ def benchmark_franka_stack(num_envs: int, steps: int, seed: int) -> dict[str, An
             "observation_dim": env.cfg.observation_space,
             "action_dim": env.cfg.action_space,
             "output_signature": _franka_output_signature(env, trace),
-            "diagnostics": mac_env_diagnostics(env, rollout_summary=trace.summary()),
+            "diagnostics": _franka_stack_diagnostics(env, trace),
         },
     )
 
@@ -1021,7 +1030,7 @@ def benchmark_franka_stack_instance_randomize(num_envs: int, steps: int, seed: i
             "observation_dim": env.cfg.observation_space,
             "action_dim": env.cfg.action_space,
             "output_signature": _franka_output_signature(env, trace),
-            "diagnostics": mac_env_diagnostics(env, rollout_summary=trace.summary()),
+            "diagnostics": _franka_stack_diagnostics(env, trace),
         },
     )