Add checked_apply helper for forwarding configclass fields onto upstream dataclasses

When an Isaac Lab configclass mirrors an upstream library's dataclass
(for example NewtonShapeCfg → Newton's ShapeConfig), bare setattr
loops are fragile: if upstream renames or removes a field, every
write becomes a silent no-op (the failure mode PR isaac-sim#5289 fixed for
ShapeConfig.contact_margin → margin).

Add isaaclab.utils.checked_apply(src, target):
  - Iterates fields(src) — single source of truth for declared fields
  - Raises AttributeError if target lacks a declared field — failure
    surfaces at startup, not at runtime
  - One-line apply at the call site, no per-field setattr noise

Documents the IL pattern of 'wrap upstream cfg + checked_apply' in
AGENTS.md so future cross-dep writes adopt it.

Author: hujc7

AGENTS.md

@@ -41,6 +41,21 @@
 
 - **Avoid adding new required dependencies.** IsaacLab's core should remain lightweight and minimize external requirements.
 - **Strongly prefer not adding new optional dependencies.** If additional functionality requires a new package, carefully consider whether the benefit justifies the added complexity and maintenance burden. When possible, implement functionality using existing dependencies, including Warp functions and kernels, NumPy, or the standard library.
+- **Mirror upstream library configs with an Isaac Lab wrapper, then forward via :func:`isaaclab.utils.checked_apply`.** Plain ``@dataclass`` types and modules silently accept unknown attribute writes, so an upstream rename turns a bare ``setattr`` into a dead no-op (see PR #5289). Define an IL wrapper that lists only the fields you override, then call ``checked_apply`` once at the apply site:
+
+  ```python
+  # IL wrapper (source of truth for IL defaults)
+  @configclass
+  class NewtonShapeCfg:
+      gap: float = 0.01
+      margin: float = 0.0
+
+  # apply site
+  from isaaclab.utils import checked_apply
+  checked_apply(cfg.default_shape_cfg, builder.default_shape_cfg)
+  ```
+
+  ``checked_apply`` raises :class:`AttributeError` if upstream renames or removes a declared field, so the failure surfaces at startup instead of silently degrading runtime behavior.
 
 ## Tooling: prefer `./isaaclab.sh -p` for running, testing, and benchmarking
 

source/isaaclab/config/extension.toml

@@ -1,7 +1,7 @@
 [package]
 
 # Note: Semantic Versioning is used: https://semver.org/
-version = "4.6.12"
+version = "4.6.13"
 
 # Description
 title = "Isaac Lab framework for Robot Learning"

source/isaaclab/docs/CHANGELOG.rst

@@ -1,6 +1,21 @@
 Changelog
 ---------
 
+4.6.13 (2026-04-24)
+~~~~~~~~~~~~~~~~~~~
+
+Added
+^^^^^
+
+* Added :func:`~isaaclab.utils.checked_apply` for forwarding declared
+  fields from an Isaac Lab configclass onto an external dataclass
+  (typically an upstream library config object). Raises
+  :class:`AttributeError` if the target is missing a declared field, so
+  upstream renames surface at startup instead of as silent no-ops.
+  Documents the IL pattern of "wrapper + checked_apply" in ``AGENTS.md``
+  for cross-dep config writes.
+
+
 4.6.12 (2026-04-23)
 ~~~~~~~~~~~~~~~~~~~
 

source/isaaclab/isaaclab/utils/__init__.pyi

@@ -56,6 +56,7 @@ __all__ = [
     "compare_versions",
     "configclass",
     "resolve_cfg_presets",
+    "checked_apply",
 ]
 
 from .timer import Timer
@@ -106,4 +107,4 @@ from .string import (
 )
 from .types import ArticulationActions
 from .version import has_kit, get_isaac_sim_version, compare_versions
-from .configclass import configclass, resolve_cfg_presets
+from .configclass import checked_apply, configclass, resolve_cfg_presets

source/isaaclab/isaaclab/utils/configclass.py

@@ -10,6 +10,7 @@
 import types
 from collections.abc import Callable
 from copy import deepcopy
+import dataclasses
 from dataclasses import MISSING, Field, dataclass, field, replace
 from typing import Any, ClassVar
 
@@ -633,3 +634,37 @@ def resolve_cfg_presets(cfg: object) -> object:
         else:
             resolve_cfg_presets(value)
     return cfg
+
+
+def checked_apply(src: Any, target: Any) -> None:
+    """Forward every declared field on ``src`` (a dataclass) onto ``target``.
+
+    Used by Isaac Lab configclasses that mirror an upstream/external dataclass
+    (for example, Newton's ``ShapeConfig``): declare the overridable fields
+    once on the wrapper, then forward them to the upstream object via this
+    helper instead of writing ``setattr`` lines per field.
+
+    Raises :class:`AttributeError` if ``target`` is missing a field declared
+    on ``src``. The two structures must match — the check guards against
+    silent no-ops when the upstream API drifts (the bug class PR #5289 fixed
+    for Newton ``ShapeConfig.contact_margin`` → ``margin``).
+
+    Args:
+        src: Dataclass instance whose declared fields will be forwarded.
+            Field names live here; this is the single source of truth.
+        target: Object to receive the field values. Must already expose
+            an attribute for every declared field on ``src``.
+
+    Raises:
+        AttributeError: If ``target`` does not already have an attribute
+            matching one of ``src``'s declared field names.
+    """
+    if not hasattr(src, "__dataclass_fields__"):
+        raise TypeError(f"checked_apply: src must be a dataclass, got {type(src).__name__}")
+    for f in dataclasses.fields(src):
+        if not hasattr(target, f.name):
+            target_path = f"{type(target).__module__}.{type(target).__name__}"
+            raise AttributeError(
+                f"{target_path} has no attribute `{f.name}`. {type(src).__name__} is out of sync with target."
+            )
+        setattr(target, f.name, getattr(src, f.name))

source/isaaclab/test/utils/test_configclass.py

@@ -1145,3 +1145,66 @@ class ChildCfg(ParentCfg):
     assert _field_module_dir(child, "class_type") == "some_package.sub_package"
     # extra should resolve to the child's module dir
     assert _field_module_dir(child, "extra") == "test_some_feature"
+
+
+# =============================================================================
+# Tests: checked_apply
+# =============================================================================
+
+
+def test_checked_apply_forwards_all_fields():
+    """checked_apply forwards every declared field on src onto target."""
+    from dataclasses import dataclass as plain_dataclass
+
+    from isaaclab.utils import checked_apply
+
+    @configclass
+    class WrapperCfg:
+        gap: float = 0.01
+        margin: float = 0.0
+
+    @plain_dataclass
+    class UpstreamLike:
+        gap: float = 99.0
+        margin: float = 99.0
+        unrelated: str = "keep me"
+
+    src = WrapperCfg(margin=0.005)
+    target = UpstreamLike()
+    checked_apply(src, target)
+
+    assert target.gap == 0.01
+    assert target.margin == 0.005
+    # fields not declared on src are not touched
+    assert target.unrelated == "keep me"
+
+
+def test_checked_apply_raises_on_missing_target_field():
+    """checked_apply fails loudly when target lacks a declared field."""
+    from dataclasses import dataclass as plain_dataclass
+
+    from isaaclab.utils import checked_apply
+
+    @configclass
+    class WrapperCfg:
+        margin: float = 0.01
+        renamed_in_upstream: float = 0.0
+
+    @plain_dataclass
+    class UpstreamMissingField:
+        margin: float = 0.0
+        # 'renamed_in_upstream' was renamed/removed upstream
+
+    with pytest.raises(AttributeError, match="renamed_in_upstream"):
+        checked_apply(WrapperCfg(), UpstreamMissingField())
+
+
+def test_checked_apply_rejects_non_dataclass_src():
+    """checked_apply requires src to be a dataclass."""
+    from isaaclab.utils import checked_apply
+
+    class NotADataclass:
+        margin = 0.01
+
+    with pytest.raises(TypeError, match="must be a dataclass"):
+        checked_apply(NotADataclass(), object())