[WARP] Cleanup Part 2: Make the Warp frontend mask-first

AGENTS.md

@@ -322,3 +322,38 @@ To debug Warp kernel behavior:
 1. **Write a standalone reproduction script** and run it directly with `./isaaclab.sh -p -c "..."` or `./isaaclab.sh -p script.py`. This keeps stdout visible and avoids the test framework entirely.
 2. **Use high-precision format strings** for floating-point debugging (e.g., `wp.printf("val=%.15e\n", x)`) — the default `%f` format hides values smaller than ~1e-6 that can still affect control flow.
 3. **Remove all `wp.printf` calls before committing.**
+
+### Warp mask-first boundaries
+
+Boolean environment masks are the canonical selection in Warp-first code; host-side
+mask-to-ID compaction (`nonzero()` on device data) is a GPU-to-host synchronization
+with a data-dependent shape, which both stalls the pipeline and permanently
+disqualifies the containing code path from CUDA graph capture.
+
+1. **Syncs only inside named, sanctioned boundary helpers.** Host syncs
+   (`nonzero`, `argwhere`, `item`, `cpu`, `tolist`, `numpy`) on the mask-native
+   path live in small single-purpose functions listed in
+   `SANCTIONED_BOUNDARIES` of
+   `source/isaaclab_experimental/test/utils/test_mask_boundary_gate.py` — no
+   inline marker comments. The gate scans the experimental production tree in
+   full and `*mask*`-named functions in core/Newton; the list is exact, so
+   adding or removing a boundary is a conscious, reviewable test change.
+   Legitimate boundaries are host consumers: recorders, legacy compatibility
+   fallbacks, checkpoint/restore, and empty-reset predicates.
+2. **Runtime backstop: `ISAACLAB_SYNC_DEBUG=1`.** Warp stages then execute under
+   `torch.cuda.set_sync_debug_mode("error")` (see `WarpGraphCache`), so a hidden
+   sync in any term — including future ones — raises at the exact call site.
+   Zero cost when the variable is unset.
+3. **Capturability is annotated with `@WarpCapturable(False, reason=...)`** (the
+   single decorator form; works on term functions and class terms). Every
+   opt-out is pinned by the inventory test next to the gate. Unannotated terms
+   default to capturable and are covered by the runtime backstop.
+4. **Mask-native Torch means elementwise masked ops.** Use `masked_fill_` or
+   `torch.where`; boolean advanced indexing (`buf[:, mask] = 0`) gathers indices
+   with a data-dependent allocation and is not capture-safe.
+5. **Dual reset APIs.** Keep the ID-based `reset(env_ids)` signature untouched and
+   add a sibling `reset_mask(env_mask)`; the base-class fallback compacts (a
+   sanctioned boundary), mask-native implementations override it. Backends whose
+   assets accept but ignore `env_mask` (classic PhysX, a develop-era condition)
+   are a documented hazard on `InteractiveScene.reset`, not guarded machinery —
+   the warp env only drives Newton scenes.

docs/source/overview/core-concepts/physical-backends/newton/warp-environments.rst

@@ -31,52 +31,59 @@ Available Environments
 Direct Warp Environments
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-- ``Isaac-Cartpole-Direct-Warp-v0`` — Cartpole balance
-- ``Isaac-Ant-Direct-Warp-v0`` — Ant locomotion
-- ``Isaac-Humanoid-Direct-Warp-v0`` — Humanoid locomotion
-- ``Isaac-Reorient-Cube-Allegro-Direct-Warp-v0`` — Allegro hand cube reorient
-
-
-Manager-Based Warp Environments
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-**Classic**
-
-- ``Isaac-Cartpole-Warp-v0``
-- ``Isaac-Ant-Warp-v0``
-- ``Isaac-Humanoid-Warp-v0``
-
-**Locomotion (Flat)**
-
-- ``Isaac-Velocity-Flat-AnymalB-Warp-v0``
-- ``Isaac-Velocity-Flat-AnymalC-Warp-v0``
-- ``Isaac-Velocity-Flat-AnymalD-Warp-v0``
-- ``Isaac-Velocity-Flat-Cassie-Warp-v0``
-- ``Isaac-Velocity-Flat-G1-Warp-v0``
-- ``Isaac-Velocity-Flat-G1-Warp-v1``
-- ``Isaac-Velocity-Flat-H1-Warp-v0``
-- ``Isaac-Velocity-Flat-UnitreeA1-Warp-v0``
-- ``Isaac-Velocity-Flat-UnitreeGo1-Warp-v0``
-- ``Isaac-Velocity-Flat-UnitreeGo2-Warp-v0``
-
-**Manipulation**
-
-- ``Isaac-Reach-Franka-Warp-v0``
-- ``Isaac-Reach-UR10-Warp-v0``
+Direct tasks share the stable task configuration: the stable registration
+declares its warp implementation through the ``warp_entry_point`` kwarg
+(mirroring ``env_cfg_entry_point``), and ``--frontend warp`` swaps only the
+environment class. Stable tasks with a declared warp implementation:
+
+- ``Isaac-Cartpole-Direct`` — Cartpole balance
+- ``Isaac-Ant-Direct`` — Ant locomotion
+- ``Isaac-Humanoid-Direct`` — Humanoid locomotion
+- ``Isaac-Reorient-Cube-Allegro-Direct`` — Allegro hand cube reorient
+
+
+Manager-Based Warp Execution (``--frontend warp``)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Manager-based tasks do not need a parallel warp registration: the shared RL
+CLI exposes ``--frontend {torch,warp}``, and ``--frontend warp`` adapts the
+*stable* task configuration onto the warp runtime at build time (swapping each
+MDP term for its warp twin). Select the Newton solver explicitly with
+``presets=newton_mjwarp``. Stable tasks with full twin coverage:
+
+- ``Isaac-Cartpole``
+- ``Isaac-Ant``
+- ``Isaac-Humanoid``
+- ``Isaac-Reach-Franka``, ``Isaac-Reach-UR10``
+- ``Isaac-Velocity-Flat-AnymalD``, ``-Cassie``, ``-G1``, ``-H1``, ``-UnitreeGo2``
+  (and their ``-Play`` variants)
+- ``Isaac-Velocity-Rough-AnymalD``, ``-Cassie``, ``-G1``, ``-H1``, ``-UnitreeGo2``
+  (and their ``-Play`` variants) — the terrain-levels curriculum runs as a
+  Warp-native update on the :class:`~isaaclab.terrains.TerrainImporter` Warp
+  origin views
+
+A missing twin is a hard error listing the affected terms, so a partially
+covered task fails at build time rather than silently changing behavior.
+``Isaac-Velocity-Rough-Digit`` is the one rough task not yet covered: its
+``desired_contacts`` reward term has no Warp twin.
 
 
 Quick Start
 ~~~~~~~~~~~
 
 .. code-block:: bash
 
-    # Direct workflow
+    # Direct workflow: stable task, warp env implementation
     ./isaaclab.sh train --rl_library rsl_rl \
-        --task Isaac-Cartpole-Direct-Warp-v0 --num_envs 4096
+        --task Isaac-Cartpole-Direct --frontend warp presets=newton_mjwarp --num_envs 4096
 
-    # Manager-based workflow
+    # Manager-based workflow: stable task on the warp runtime
     ./isaaclab.sh train --rl_library rsl_rl \
-        --task Isaac-Velocity-Flat-AnymalC-Warp-v0 --num_envs 4096
+        --task Isaac-Cartpole --frontend warp presets=newton_mjwarp --num_envs 4096
+
+    # Manager-based workflow: velocity task on the warp runtime
+    ./isaaclab.sh train --rl_library rsl_rl \
+        --task Isaac-Velocity-Flat-AnymalD --frontend warp presets=newton_mjwarp --num_envs 4096
 
 All RL libraries with warp-compatible wrappers are supported: RSL-RL, RL Games, SKRL, and
 Stable-Baselines3.
@@ -143,16 +150,6 @@ both running on the Newton physics backend. Measured over 300 iterations with 40
      - 11,458
      - 7,813
      - -31.83%
-   * - AnymalB
-     - Manager
-     - 29,188
-     - 21,781
-     - -25.38%
-   * - AnymalC
-     - Manager
-     - 30,938
-     - 22,228
-     - -28.15%
    * - AnymalD
      - Manager
      - 32,294
@@ -173,17 +170,7 @@ both running on the Newton physics backend. Measured over 300 iterations with 40
      - 22,202
      - 15,864
      - -28.55%
-   * - A1
-     - Manager
-     - 15,257
-     - 9,907
-     - -35.07%
-   * - Go1
-     - Manager
-     - 16,515
-     - 11,869
-     - -28.13%
-   * - Go2
+   * - UnitreeGo2
      - Manager
      - 15,221
      - 9,966
@@ -200,7 +187,7 @@ overhead. Reading the table above:
 - **Manager-based classic RL** (Cartpole, Ant) — biggest gains (-52% to -54%). Many small
   reward / observation terms with low compute per term, so per-launch CPU overhead dominated
   the stable baseline.
-- **Manager-based locomotion** (Anymal, G1, H1, Cassie, Unitree) — consistent -25% to -38%
+- **Manager-based locomotion** (AnymalD, G1, H1, Cassie, UnitreeGo2) — consistent -21% to -38%
   range. The MDP has more terms but the underlying physics step is heavier, so the relative
   Python savings shrink.
 - **Direct workflow** — gains scale with how much the env's step body was Python (Ant -51%,
@@ -228,7 +215,7 @@ specific to warp envs; for Newton physics limitations see :doc:`supported-featur
   ``class_type`` fields resolve to ``isaaclab_physx.*`` classes that depend on
   ``omni.physics.tensors`` (a Kit module the warp runtime does not initialise), and several
   warp APIs (env-mask reset, CUDA graph capture) require the Newton articulation. Configure
-  the cfg with a Newton physics block (or ``physics=newton_mjwarp``).
+  the cfg with a Newton physics block (or ``presets=newton_mjwarp``).
 
 **MDP coverage**
 
@@ -266,33 +253,40 @@ to estimate the gain for your own task before committing to a migration.
 
 **Single-task A/B**
 
+Run the same stable task id twice, differing only in ``--frontend``. Pass
+``presets=newton_mjwarp`` to *both* runs so the physics backend is identical and the
+measured difference isolates the frontend (manager pipeline + CUDA graph capture):
+
 .. code-block:: bash
 
-    # Stable variant
+    # Torch frontend (stable managers)
     uv run isaaclab benchmark training \
         --rl_library rsl_rl \
-        --task <Task-Name>-v0 \
+        --task <Task-Name> \
         --num_envs 4096 \
         --max_iterations 500 \
         --benchmark_formatter summary \
-        --output_path benchmarks/stable
+        --output_path benchmarks/torch \
+        presets=newton_mjwarp
 
-    # Warp variant — same task with -Warp- suffix
+    # Warp frontend (warp managers, CUDA-graph captured) — same task id
     uv run isaaclab benchmark training \
         --rl_library rsl_rl \
-        --task <Task-Name>-Warp-v0 \
+        --task <Task-Name> \
+        --frontend warp \
         --num_envs 4096 \
         --max_iterations 500 \
         --benchmark_formatter summary \
-        --output_path benchmarks/warp
+        --output_path benchmarks/warp \
+        presets=newton_mjwarp
 
 The ``summary`` formatter prints step time (min / mean / max) and total throughput. Compare
 "step time" between the two runs to estimate the gain per env step.
 
 **Sweep across all available tasks**
 
 Run ``isaaclab benchmark training`` for each task in the stable set (cartpole, ant, humanoid,
-locomotion, manipulation) and again with the ``-Warp-`` suffixed task ids, then diff the two output
+locomotion, manipulation) and again with ``--frontend warp``, then diff the two output
 directories.
 
 **What to look at in the output**