test: optional-dep import boundary (ROADMAP §9 PR R0.2)

Lock invariant #1 from CLAUDE.md — `import genelab.rl` must succeed
without `rsl_rl` / `skrl` / `stable_baselines3` / `tensordict`
installed. Library imports are function-local inside each backend.

Each of the four load-bearing entry points (`genelab.rl`,
`genelab.rl.backends.{rsl_rl,skrl,sb3}`) is imported in a fresh
subprocess with the four optional libs poisoned via
`sys.modules[name] = None`. A non-zero exit code from the import
surfaces any top-level dependency that should have been function-
local — that's exactly the regression class R7's importlinter
contract (ADR-0009 §Decision contract 1) will catch statically once
flipped to blocking.

Verified on dev today: all four targets import cleanly under poison.
Negative control: `genelab.rl.skrl_models` (which intentionally has a
top-level `from skrl.models.torch import ...` and is imported lazily
inside `backends/skrl.py:112` only) does correctly fail the
mechanism, confirming the test catches real leaks.

No production code touched.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: KraHsu

CHANGELOG.md

@@ -8,6 +8,16 @@ trajectory so breaking changes can land in any minor release until the 1.0 stabi
 
 ### Added
 
+- `tests/test_optional_deps.py` — runtime guard for invariant #1
+  (`import genelab.rl` must succeed without `rsl_rl` / `skrl` /
+  `stable_baselines3` / `tensordict` installed). Each of the four
+  load-bearing entry points (`genelab.rl`, `genelab.rl.backends.rsl_rl`,
+  `genelab.rl.backends.skrl`, `genelab.rl.backends.sb3`) is imported
+  in a fresh subprocess with the four optional libs poisoned via
+  `sys.modules[name] = None`; a non-zero exit code surfaces any
+  top-level import that should have been function-local. Pairs with
+  the R7 importlinter contract (ADR-0009) which catches the same class
+  of regression statically. Lands as ROADMAP §9 PR R0.2.
 - `tests/test_cli_help_snapshots.py` + `tests/snapshots/help-*.txt` —
   frozen baseline of every Typer command's `--help` output (root, cache,
   prof, list, info, play, eval, export, train, project, project new). The

tests/test_optional_deps.py

@@ -0,0 +1,82 @@
+"""Optional-dep boundary test (ROADMAP §9 Phase R0.2).
+
+Locks invariant #1 from ``CLAUDE.md``::
+
+    import genelab.rl  # must succeed without any of:
+                       #   rsl_rl, skrl, stable_baselines3, tensordict
+                       # Library imports are function-local inside each backend.
+
+Each test spawns a fresh subprocess, poisons the four optional RL
+libraries by setting ``sys.modules[name] = None`` (which makes any
+subsequent ``import name`` raise ``ImportError`` per Python's
+documented behaviour for sentinel ``None`` entries), then attempts to
+import one target module.  A non-zero exit code means the target leaks
+one of the optional libraries at module-load time and must move the
+offending import into a function body before R7 can flip
+``import-linter`` from lint-only to blocking.
+
+The four targets are the load-bearing entry points: ``genelab.rl``
+itself (re-exports the configs, the backend registry, the runner) plus
+each concrete backend module under ``genelab.rl.backends/``.  None of
+them should pull ``rsl_rl`` / ``skrl`` / ``stable_baselines3`` /
+``tensordict`` at module level; library-specific code lives behind
+function-local imports inside the backend methods (``train`` /
+``play`` / ``make_inference_setup`` and helpers).
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+import pytest
+
+# Optional RL libraries that ``import genelab.rl`` must not pull
+# transitively.  See ``CLAUDE.md`` §"Architectural invariants" #1.
+OPTIONAL_LIBS: tuple[str, ...] = (
+    "rsl_rl",
+    "skrl",
+    "stable_baselines3",
+    "tensordict",
+)
+
+# Modules whose load path must stay clear of the optional libraries.
+# ``genelab.rl`` is the public surface end-users import; the three
+# backend modules are loaded by ``genelab.rl.backends._ensure_loaded``
+# on first ``select_backend()`` call and must themselves import without
+# their RL library being installed (library-specific imports happen
+# inside method bodies).
+TARGETS: tuple[str, ...] = (
+    "genelab.rl",
+    "genelab.rl.backends.rsl_rl",
+    "genelab.rl.backends.skrl",
+    "genelab.rl.backends.sb3",
+)
+
+_WRAPPER = (
+    "import sys\n"
+    "for _lib in {libs!r}:\n"
+    "    sys.modules[_lib] = None\n"
+    "import {target}\n"
+)
+
+
+@pytest.mark.parametrize("target", TARGETS)
+def test_import_with_optional_deps_poisoned(target: str) -> None:
+    """``import {target}`` must succeed with the four optional RL libs absent."""
+    code = _WRAPPER.format(libs=OPTIONAL_LIBS, target=target)
+    proc = subprocess.run(
+        [sys.executable, "-c", code],
+        env={**os.environ, "PYTHONDONTWRITEBYTECODE": "1"},
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert proc.returncode == 0, (
+        f"`import {target}` failed when {list(OPTIONAL_LIBS)} are poisoned.\n"
+        f"This means one of those libraries is imported at module-load time "
+        f"somewhere on the import chain — find the offending top-level "
+        f"`import` and move it into a function body.\n"
+        f"stdout:\n{proc.stdout}\nstderr:\n{proc.stderr}"
+    )