phase: 34_radiance_llm_engine

Everything is verified and green. Final report:

**Phase 34 final verification pass — complete**

- Verified all 6 completed tasks' work against the live fleet and hermetic suite: `llm:radiance` job registered, `llm_engines()` registry drives 404 gate / history defaults / `/api/config` (additive, byte-identical gufo/vllm keys), radiance field map + `/stats` sidecar + 7-position spec curve, `/llm` strip/curve/rows.
- **Defect found & fixed (pre-existing, task 05):** the vLLM-only sentence "vLLM exposes no per-slot JSON…" rendered on the **radiance** panel (`slotSection`'s non-gufo branch). Fix: vLLM line gated to `engine === 'vllm'`; radiance's panel slot section renders nothing (its session home is the strip) — `page-llm.js` + the served-byte pin in `tests/test_api.py` (now asserts the radiance branch is empty and the sentence can't leak). Browser-verified; re-shot `data/logs/34-llm-radiance-rest.png` (the 4.5-min wait found no in-flight request, so the busy shot remains the earlier pass's — its strip rows still stand; only the panel text predates the fix).
- Tests: `uv run pytest` → **2031 passed, 19 skipped** (100%); `uv run pytest --cov` → **98.73%** (floor 94%; config 100%, llm 99%, collectors 98%, api 99%); `uv run ruff check src tests agent && uv run pyright` → clean; `node --check` OK; `uv pip list --outdated` → empty.
- `uv run pytest -m live --live` → **13 passed, 2 skipped** (vLLM unset — correct; live-write opt-in — correct); the read-only radiance test passed.
- Completion criteria: (1) engines `gufo`+`radiance`, `fleet.engines_live` 2, `config.llm.radiance.enabled` true — **pass (live curl)**; (2) unset → 404 no-dial + no job — **pass (spy-pinned, green)**; (3) fixtures present, both families (79 `radiance:` / 198 `vllm:` lines), drift pin — **pass**; (4) panel/curve/rows — **pass (re-shot rest screenshot)**; (5) live radiance test — **pass**; (6) suite/coverage/lint/`bash .agents/validate.sh` (exit 0) — **pass**; (7) docs — below; (8) gufo/vLLM behaviour unchanged — **pass (existing pins untouched)**.
- Documentation: **README.md** full review — env table, LLM-engines section, architecture diagram, capture-script and `/llm` section all name radiance correctly; no inconsistencies found, no changes needed. **AGENTS.md** — the three task-06 fixes (fleet line, route row, module bullets) are in place and all other statements match reality; no changes needed.
- Dev server healthy (`./scripts/dev-server.sh status`: all sources ok, `llm:radiance` answering); all changes left in the working tree for the harness.
- Next pending phase: none — 34 was the last phase in `todo/`.

tests/test_config.py

@@ -6,11 +6,14 @@ import os
 from dataclasses import FrozenInstanceError, fields
 from typing import Any
 
+import httpx
 import pytest
 
 from dashboards import config
 from dashboards.auth import PBKDF2_ITERATIONS
+from dashboards.collectors import llm_jobs
 from dashboards.config import Settings, parse_targets
+from dashboards.rates import RateEstimator
 
 
 def test_parses_whitespace_and_comma_separated_targets() -> None:
@@ -397,3 +400,92 @@ def test_the_pbkdf2_knob_is_for_tests_and_not_a_performance_tune(
     assert config._int("DASH_PBKDF2_ITERATIONS", 600_000) == 600_000
     monkeypatch.setenv("DASH_PBKDF2_ITERATIONS", "1000")
     assert config._int("DASH_PBKDF2_ITERATIONS", 600_000) == 1000
+
+
+# ---- the llm engine registry (phase 34 task 02) --------------------------- #
+
+def test_radiance_defaults_to_unset_the_way_the_other_engines_do() -> None:
+    """Unset means "this deployment does not run it" (invariant 3), like `gufo_url`.
+
+    It must be invisible to `any_source_enabled` too: a deployment that runs no source at
+    all is `empty`, not broken, and an unset engine is the half of the page that
+    disappears, never a red panel.
+    """
+    settings = Settings()
+    assert settings.radiance_url == ""
+    assert settings.radiance_api_key == ""
+    assert settings.any_source_enabled is False
+
+
+def test_radiance_settings_come_from_the_environment(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("RADIANCE_BASE_URL", " http://driveripper.example.net:8000/ ")
+    monkeypatch.setenv("RADIANCE_API_KEY", "  engine-key  ")
+    reloaded = importlib.reload(config)
+    try:
+        assert reloaded.SETTINGS.radiance_url == "http://driveripper.example.net:8000", "`_base_url` strips whitespace and the trailing slash"
+        assert reloaded.SETTINGS.radiance_api_key == "engine-key", "_env() strips"
+        assert reloaded.SETTINGS.any_source_enabled is True
+    finally:
+        for name in ("RADIANCE_BASE_URL", "RADIANCE_API_KEY"):
+            monkeypatch.delenv(name)
+        importlib.reload(config)
+
+
+def test_llm_engines_is_the_one_registry_in_its_stable_three_engine_order() -> None:
+    """The order `gufo`, `vllm`, `radiance` is the contract: the UI's card order and the
+    history defaults follow it, so a reordered registry is a page change, not a list edit.
+    `key` is the history DB's host key and the job id; `display` is what a health record
+    and a page print; the api key travels verbatim into the dial's `Authorization` header.
+    """
+    settings = Settings(gufo_url="http://gufo.example.net:8731", gufo_api_key="gufo-key",
+                       vllm_url="http://vllm.example.net:8000", vllm_api_key="vllm-key",
+                       radiance_url="http://driveripper.example.net:8000",
+                       radiance_api_key="radiance-key")
+    assert settings.llm_engines() == [
+        ("gufo", "gufo", "http://gufo.example.net:8731", "gufo-key"),
+        ("vllm", "vLLM", "http://vllm.example.net:8000", "vllm-key"),
+        ("radiance", "radiance", "http://driveripper.example.net:8000", "radiance-key"),
+    ]
+
+
+def test_llm_engines_lists_an_unset_engine_with_an_empty_url() -> None:
+    """The registry is the full fleet the way `parse_targets` keeps the host list: an
+    unset engine is *listed*, with an empty `url` — configured-ness is the call site's
+    `bool(url)` test (the `nut_enabled` shape), never a missing entry, so a site that
+    iterates the list cannot silently read a two-engine world.
+    """
+    entries = Settings().llm_engines()
+    assert [key for key, _display, _url, _api_key in entries] == ["gufo", "vllm", "radiance"]
+    assert [display for _key, display, _url, _api_key in entries] == ["gufo", "vLLM", "radiance"]
+    assert [url for _key, _display, url, _api_key in entries] == ["", "", ""]
+
+
+def _llm_job_keys(settings: Settings) -> list[str]:
+    """The job ids `llm_jobs` would build, from the registry, for one settings object.
+
+    The client is never touched by the construction (the jobs close over it for their
+    own poll loops), so a bare, never-entered `AsyncClient` is the right fake — and an
+    unentered one warns nothing and needs no closing.
+    """
+    client = httpx.AsyncClient()
+    return [job.key for job in llm_jobs(settings, client, RateEstimator())]
+
+
+def test_radiance_unset_gets_no_job_and_changes_nothing_about_the_source() -> None:
+    """No job, and `any_source_enabled` is unchanged by it: an unconfigured engine is never
+    dialled and never shows a red record (invariant 3)."""
+    settings = Settings()
+    assert settings.any_source_enabled is False
+    assert _llm_job_keys(settings) == []
+
+
+def test_radiance_set_gets_its_job_and_enables_the_source() -> None:
+    """One `llm:radiance` job, in the registry's position, and the same job set a three-engine
+    deployment already had before the third engine existed (gufo/vllm byte-identical)."""
+    settings = Settings(radiance_url="http://driveripper.example.net:8000")
+    assert settings.any_source_enabled is True
+    assert _llm_job_keys(settings) == ["llm:radiance"]
+    settings = Settings(gufo_url="http://gufo.example.net:8731",
+                       vllm_url="http://vllm.example.net:8000",
+                       radiance_url="http://driveripper.example.net:8000")
+    assert _llm_job_keys(settings) == ["llm:gufo", "llm:vllm", "llm:radiance"]