feat(cpg): add an explicit environment switch for the engine session (M2 11.3)

A measured run needs to enable the transport without changing any default. The
switch reads as enabled only for the exact value "1"; unset, empty, "0", "true"
and anything else leave the disposable path in place, and an explicit constructor
argument still wins in both directions.

1,396 tests passed, nine skipped.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01EmM1j46qgKMh3zqD1QMwEo

src/openultrasast/cpg/backend.py

@@ -58,6 +58,8 @@ QUERY_TIMEOUT_ENV = "OPENULTRASAST_CPG_QUERY_TIMEOUT"
 # first repository measurements unreproducible: runs were killed under memory pressure at different
 # points, so the numbers described the host, not the engine. Bound it, and let the operator raise it.
 CPG_HEAP_MB = 2048
+# Explicit opt-in for the transaction-owned engine session (M2). Unset means the disposable path.
+SESSION_ENV = "OUSAST_ENGINE_SESSION"
 HEAP_ENV = "OPENULTRASAST_CPG_HEAP_MB"
 
 # `joern-parse` detects the language and then shells out to a frontend, and on a large tree it can fail where
@@ -324,7 +326,9 @@ class JoernBackend:
     # M2 11.3: opt-in transport. Off by default, so shipped behaviour stays the disposable
     # invocation this project has measured. A session that cannot answer falls back to it rather
     # than reporting a zero, and what a session returns is the same payload or nothing at all.
-    session_transport: bool = False
+    # The environment switch exists so a measured run can enable it without changing any default;
+    # anything other than "1" leaves it off.
+    session_transport: bool = field(default_factory=lambda: os.environ.get(SESSION_ENV, "").strip() == "1")
     _diagnostics: list[str] = field(default_factory=list, init=False, repr=False)
     _scratch: list[Path] = field(default_factory=list, init=False, repr=False)
     _cancel_deadline: float | None = field(default=None, init=False, repr=False)

tests/test_cpg_session.py

@@ -263,3 +263,18 @@ def _completed(stdout):
     import subprocess
 
     return subprocess.CompletedProcess(["joern"], 0, stdout, "")
+
+
+def test_the_session_switch_is_explicit_and_defaults_off(monkeypatch):
+    """M2 11.3: a measured run can enable the transport without changing any default."""
+    from openultrasast.cpg.backend import SESSION_ENV, JoernBackend
+
+    monkeypatch.delenv(SESSION_ENV, raising=False)
+    assert JoernBackend().session_transport is False
+    for value in ("", "0", "true", "yes", "2"):
+        monkeypatch.setenv(SESSION_ENV, value)
+        assert JoernBackend().session_transport is False, value
+    monkeypatch.setenv(SESSION_ENV, "1")
+    assert JoernBackend().session_transport is True
+    # An explicit argument still wins over the environment in both directions.
+    assert JoernBackend(session_transport=False).session_transport is False