docs(norm): reconcile the C1 norm page, docstrings and gated tests with the stacked C1 branch

Carried over from the former merge of the C1 branch into this one: the decoder-norm page again states the registration and the check_operator command, the gated tests use the contract's reduction tolerances through _forward_tol, and the reference docstrings name the gated page. Same final tree as before the re-stack.

Signed-off-by: Wenbo Ji <36562829+fusheng-ji@users.noreply.github.com>

Author: fusheng-ji

docs/operators/qwen3-next-rms-norm.md

@@ -49,11 +49,11 @@ y = rmsnorm_cuda(x, weight, eps=1e-6, weight_offset=1.0)
 
 ## Dispatch Behavior
 
-Not registered on this branch: there is no `qwen3_next_rms_norm` gtest spec and no
-registry entry yet. Both arrive with the gated-norm PR. Until then, construct the
-ops directly as in "Entry Point". The CUDA op validates the compiled symbols in
-`__init__`, so on a build without the extension construction raises instead of
-handing out an op that fails at call time.
+Registered as the `qwen3_next_rms_norm` gtest operator. On CUDA the registry
+prefers `Qwen3NextRMSNormCudaOp`; every other platform resolves to the PyTorch
+reference. The CUDA op validates the compiled symbols in `__init__`, so on a build
+without the extension construction raises and the registry falls through to the
+reference rather than handing out an op that fails at call time.
 
 ## Accuracy
 
@@ -102,16 +102,16 @@ element and no extra memory traffic.
 
 ```bash
 python -m pytest tests/test_qwen3_next_norm.py -v
+python scripts/check_operator.py --op qwen3_next_rms_norm --candidate cuda \
+    --device cuda --dtype bf16 --check-grad
 ```
 
 ## Known Limitations
 
 - CUDA only; no ROCm, Ascend or Triton backend.
-- Not registered as a gtest operator or in the registry on this branch (see
-  "Dispatch Behavior").
 - Not bitwise against vLLM (see Accuracy). An L2 claim needs a single source of
   truth for the forward on both sides, per RFC #428 §0 item 1.
 - The gated pair (`Qwen3NextRMSNormGatedOp`, `Qwen3NextRMSNormGatedHFOp`) is
-  documented with its CUDA kernel in the gated-norm PR, not on this page.
+  documented with its CUDA kernel on [Gated RMSNorm](qwen3-next-rms-norm-gated.md).
 - Measured on sm_100 (B200). Per RFC #428 §2.2 no claim carries across
   H100/H200/B100/B200.

rl_engine/kernels/ops/pytorch/norm/qwen3_next_rms_norm.py

@@ -22,7 +22,8 @@
 All three reuse :func:`shape_invariant_rstd`, a fixed-order reduction. They
 reproduce the weight convention and cast order, not vLLM's reduction tree, and are
 not bitwise equal to any vLLM path probed so far. Claim levels, measurements and
-limitations are in ``docs/operators/qwen3-next-rms-norm.md``.
+limitations are in ``docs/operators/qwen3-next-rms-norm.md`` and, for the gated
+pair, ``docs/operators/qwen3-next-rms-norm-gated.md``.
 """
 
 from __future__ import annotations
@@ -61,7 +62,7 @@ class Qwen3NextRMSNormGatedOp:
     ``out = (x * rstd * weight) * silu(gate)``, with every multiply in fp32 and
     a single cast on the way out. This is the convention vLLM's ``RMSNormGated``
     uses with ``norm_before_gate=True``. Which gated convention is the strict
-    default is still open; see the operator page.
+    default is still open; see ``docs/operators/qwen3-next-rms-norm-gated.md``.
 
     Not a subclass of the plain op: it takes an extra tensor and its epilogue
     differs, so it is not a drop-in substitute for one.

tests/test_qwen3_next_norm.py

@@ -475,9 +475,6 @@ def test_cuda_zero_centred_backward_is_offset_aware():
     not _HAS_CUDA_GATED, reason="gated RMSNorm CUDA extension is not available"
 )
 
-# tolerance_contract.json, judgments/forward_accuracy/by_op_class/reduction/bfloat16
-_BF16_ATOL, _BF16_RTOL = 2e-2, 1.6e-2
-
 
 def _gated_cuda_inputs(seed=0, rows=512, hidden=_HEAD_V_DIM, dtype=torch.bfloat16):
     g = torch.Generator(device="cuda").manual_seed(seed)
@@ -494,7 +491,7 @@ def test_cuda_gated_matches_golden_within_contract():
     x, w, gate = _gated_cuda_inputs()
     got = Qwen3NextRMSNormGatedCudaOp().forward(x, w, gate, eps=_EPS)
     ref = Qwen3NextRMSNormGatedOp().forward_fp32(x, w, gate, eps=_EPS)
-    torch.testing.assert_close(got.float(), ref, atol=_BF16_ATOL, rtol=_BF16_RTOL)
+    torch.testing.assert_close(got.float(), ref, **_forward_tol(torch.bfloat16))
 
 
 @requires_cuda_gated
@@ -551,7 +548,7 @@ def test_cuda_gated_unit_weight_is_plain_norm_times_silu():
     ones = torch.ones(_HEAD_V_DIM, device="cuda", dtype=x.dtype)
     got = Qwen3NextRMSNormGatedCudaOp().forward(x, ones, gate, eps=_EPS).float()
     ref = rmsnorm_cuda(x, ones, eps=_EPS).float() * F.silu(gate.float())
-    torch.testing.assert_close(got, ref, atol=_BF16_ATOL, rtol=_BF16_RTOL)
+    torch.testing.assert_close(got, ref, **_forward_tol(torch.bfloat16))
 
 
 @requires_cuda_gated
@@ -561,7 +558,7 @@ def test_cuda_gated_sigmoid_activation():
     x, w, gate = _gated_cuda_inputs()
     got = rmsnorm_gated_cuda(x, w, gate, eps=_EPS, activation="sigmoid").float()
     ref = rmsnorm_cuda(x, w, eps=_EPS).float() * torch.sigmoid(gate.float())
-    torch.testing.assert_close(got, ref, atol=_BF16_ATOL, rtol=_BF16_RTOL)
+    torch.testing.assert_close(got, ref, **_forward_tol(torch.bfloat16))
 
 
 @requires_cuda_gated