span-panel-api 3.1.1__tar.gz → 3.2.0__tar.gz

{span_panel_api-3.1.1 → span_panel_api-3.2.0}/.gitignore

@@ -40,8 +40,3 @@ coverage_output.log
 # of which belongs in a repository. The differential that reads them commits its
 # *verdict* only, never the capture, and skips when the file is absent.
 tests/fixtures/live_*.json
-
-# Peer checkouts. CI clones the eBus specification and SpanPanel/panelbench here so
-# the provenance checks have something to compare vendored bytes against; the same
-# layout works locally if you would rather not point .env at siblings.
-/peers/

{span_panel_api-3.1.1 → span_panel_api-3.2.0}/CHANGELOG.md

@@ -7,6 +7,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 Pre-releases are not listed separately. A beta is a step towards the next public version, so its changes are folded into that version's entry as they land and are described against the **last public release**, never against the beta before it. What one
 beta corrected in an earlier beta does not appear at all: from the point of view of somebody upgrading between released versions, it never happened.
 
+## [3.2.0]
+
+A consumer pinned to a panel's CA cannot currently tell a panel that has moved from something impersonating one, because the two produce the same verification failure. This release splits the question.
+
+### Added
+
+- **`build_panel_ssl_context` takes `check_hostname`**, so a caller can verify that a peer holds a key the pinned CA signed without also asserting that the certificate names the address it was dialled by.
+- **`leaf_names_host` decides the name binding on its own**, hand-written against `getpeercert()` because `ssl.match_hostname` was removed in Python 3.12, and stricter than that function was: no wildcards, no `commonName` fallback, and DNS and IP entries
+  that never stand in for one another.
+
 ## [3.1.1]
 
 A follow-up to 3.1.0's security work, with no API change and no adapter move required.

{span_panel_api-3.1.1 → span_panel_api-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.1.1
+Version: 3.2.0
 Summary: A client library for SPAN Panel API
 Project-URL: Homepage, https://github.com/SpanPanel/span-panel-api
 Project-URL: Issues, https://github.com/SpanPanel/span-panel-api/issues
@@ -554,11 +554,25 @@ The `PanelCapability` flag enum advertises transport features at runtime:
 
 ## Reference Payloads
 
-Captures of what a panel actually serves — the `GET /api/v2/homie/schema` document and a full 40-space parent/child retained-topic tree — live in [`tests/reference_payloads/`](tests/reference_payloads/README.md), with their provenance.
+Captures of what a panel actually serves — the `GET /api/v2/homie/schema` document and a full 40-space parent/child retained-topic tree — ship as package data of the adapter that parses each, and their provenance is documented in
+[`tests/reference_payloads/`](tests/reference_payloads/README.md) beside the loaders that read them.
 
-**They are fixtures of this repository, not package data.** Until 3.1.0 they sat inside the two source packages and were therefore carried in the wheels, which no runtime path ever read. `span_panel_api.reference_payloads` and
-`span_panel_api_schema_1.reference_payloads` no longer exist; a consumer that was importing them should vendor the bytes it needs and record the release it took them from, asserting that against `importlib.metadata.version(...)` so a moved pin that outruns
-the copy fails loudly instead of testing against a schema no panel runs.
+| Capture                  | Read from                                                  |
+| ------------------------ | ---------------------------------------------------------- |
+| `homie_schema.json`      | `span_panel_api_schema_0/reference/homie_schema.json`      |
+| `parent_child_tree.json` | `span_panel_api_schema_1/reference/parent_child_tree.json` |
+
+**Test-support data, and no runtime path reads either.** They ship so a downstream test suite pinned to a version of an adapter reads the same bytes that version was tested against, out of its own site-packages:
+
+```python
+from importlib.resources import files
+import json
+
+schema = json.loads((files("span_panel_api_schema_0") / "reference" / "homie_schema.json").read_text(encoding="utf-8"))
+```
+
+The bootstrap distribution ships neither: it registers no adapter and parses nothing. `span_panel_api.reference_payloads` and `span_panel_api_schema_1.reference_payloads` — the importable modules that existed until 3.1.0 — are still gone; these are data
+files read through `importlib.resources`, not an import surface.
 
 ## Project Structure
 
@@ -589,13 +603,15 @@ src/span_panel_api/          # distribution: span-panel-api (no parser)
 
 packages/schema-0/           # distribution: span-panel-api-schema-0
 └── src/span_panel_api_schema_0/
-                             # Flat parser: HomiePropertyAccumulator, HomieLifecycle,
+    ├── reference/           # homie_schema.json — test-support package data, not read at runtime
+    └── ...                  # Flat parser: HomiePropertyAccumulator, HomieLifecycle,
                              # HomieDeviceConsumer, field metadata, SCHEMA_ANCHOR
 
 packages/schema-1/           # distribution: span-panel-api-schema-1
-├── spec/                    # eBus capability catalogs, byte-copied; checked against, never parsed
+├── spec/                    # eBus capability catalogs, byte-copied from the emitter wheel; checked against, never parsed
 └── src/span_panel_api_schema_1/
-                             # Parent/child parser: ControllerRoutes, snapshot mapper,
+    ├── reference/           # parent_child_tree.json — test-support package data, not read at runtime
+    └── ...                  # Parent/child parser: ControllerRoutes, snapshot mapper,
                              # adoption, catalog validator, spec_lock.json
 ```
 

{span_panel_api-3.1.1 → span_panel_api-3.2.0}/README.md

@@ -527,11 +527,25 @@ The `PanelCapability` flag enum advertises transport features at runtime:
 
 ## Reference Payloads
 
-Captures of what a panel actually serves — the `GET /api/v2/homie/schema` document and a full 40-space parent/child retained-topic tree — live in [`tests/reference_payloads/`](tests/reference_payloads/README.md), with their provenance.
+Captures of what a panel actually serves — the `GET /api/v2/homie/schema` document and a full 40-space parent/child retained-topic tree — ship as package data of the adapter that parses each, and their provenance is documented in
+[`tests/reference_payloads/`](tests/reference_payloads/README.md) beside the loaders that read them.
 
-**They are fixtures of this repository, not package data.** Until 3.1.0 they sat inside the two source packages and were therefore carried in the wheels, which no runtime path ever read. `span_panel_api.reference_payloads` and
-`span_panel_api_schema_1.reference_payloads` no longer exist; a consumer that was importing them should vendor the bytes it needs and record the release it took them from, asserting that against `importlib.metadata.version(...)` so a moved pin that outruns
-the copy fails loudly instead of testing against a schema no panel runs.
+| Capture                  | Read from                                                  |
+| ------------------------ | ---------------------------------------------------------- |
+| `homie_schema.json`      | `span_panel_api_schema_0/reference/homie_schema.json`      |
+| `parent_child_tree.json` | `span_panel_api_schema_1/reference/parent_child_tree.json` |
+
+**Test-support data, and no runtime path reads either.** They ship so a downstream test suite pinned to a version of an adapter reads the same bytes that version was tested against, out of its own site-packages:
+
+```python
+from importlib.resources import files
+import json
+
+schema = json.loads((files("span_panel_api_schema_0") / "reference" / "homie_schema.json").read_text(encoding="utf-8"))
+```
+
+The bootstrap distribution ships neither: it registers no adapter and parses nothing. `span_panel_api.reference_payloads` and `span_panel_api_schema_1.reference_payloads` — the importable modules that existed until 3.1.0 — are still gone; these are data
+files read through `importlib.resources`, not an import surface.
 
 ## Project Structure
 
@@ -562,13 +576,15 @@ src/span_panel_api/          # distribution: span-panel-api (no parser)
 
 packages/schema-0/           # distribution: span-panel-api-schema-0
 └── src/span_panel_api_schema_0/
-                             # Flat parser: HomiePropertyAccumulator, HomieLifecycle,
+    ├── reference/           # homie_schema.json — test-support package data, not read at runtime
+    └── ...                  # Flat parser: HomiePropertyAccumulator, HomieLifecycle,
                              # HomieDeviceConsumer, field metadata, SCHEMA_ANCHOR
 
 packages/schema-1/           # distribution: span-panel-api-schema-1
-├── spec/                    # eBus capability catalogs, byte-copied; checked against, never parsed
+├── spec/                    # eBus capability catalogs, byte-copied from the emitter wheel; checked against, never parsed
 └── src/span_panel_api_schema_1/
-                             # Parent/child parser: ControllerRoutes, snapshot mapper,
+    ├── reference/           # parent_child_tree.json — test-support package data, not read at runtime
+    └── ...                  # Parent/child parser: ControllerRoutes, snapshot mapper,
                              # adoption, catalog validator, spec_lock.json
 ```
 

{span_panel_api-3.1.1 → span_panel_api-3.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.1.1"
+version = "3.2.0"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -78,6 +78,12 @@ dev = [
     # two distributions together, which is the configuration users will run.
     "span-panel-api-schema-0",
     "span-panel-api-schema-1",
+    # The producer of `span_panel_api_schema_1/reference/parent_child_tree.json`, pinned
+    # exactly because a reference capture is only evidence if what made it is
+    # known. Dependabot raises the bump on its own; the bump PR re-runs
+    # `scripts/capture_parent_child_reference.py` and the suite then says whether
+    # the wire moved.
+    "ebus-panel-sim==0.8.0",
     "pytest>=9.0.2",
     "pytest-asyncio>=1.3.0",
     "pytest-cov",
@@ -102,7 +108,7 @@ dev = [
     # transitive of `twine -> keyring -> secretstorage`, which is marked
     # `sys_platform == 'linux'` -- so the whole module ran in CI and silently
     # skipped on every macOS checkout, which reads in the summary line exactly
-    # like passing. See DEVELOPMENT.md, "A skip here is not a pass".
+    # like passing. See DEVELOPMENT.md, "A skip is still not a pass".
     #
     # Floored at 50.0.0 rather than at whatever the lock happens to hold: four
     # advisories cover the range below it (the highest first patched in 50.0.0),
@@ -153,8 +159,20 @@ include = [
 
 [tool.ruff]
 line-length = 125
+# `scripts/` is excluded file by file rather than as a directory, so that a new
+# script is linted by default and only the ones written before that was true are
+# grandfathered out. `capture_parent_child_reference.py` is the one in scope: it
+# produces a fixture the whole schema_1 suite is written against, and the rest are
+# hand-run tools.
 exclude = [
-    "scripts/",
+    "scripts/capture_flat_reference.py",
+    "scripts/capture_live_flat.py",
+    "scripts/coverage.py",
+    "scripts/format_markdown.py",
+    "scripts/test_live_auth.py",
+    "scripts/validate_lug_derivation/",
+    "scripts/verify_adapterless_install.py",
+    "scripts/verify_reconnect.py",
     ".*_cache/",
     "dist/",
     "venv/",
@@ -164,6 +182,10 @@ exclude = [
 [tool.ruff.lint.per-file-ignores]
 # Exclude tests from ALL linting checks (formatting still applies)
 "tests/**/*.py" = ["ALL"]
+# Its whole output is a report on stdout naming the producer, the device count and
+# where the capture landed, which is what an operator reads to decide whether to
+# adopt it. T20 is right for the library and wrong for a hand-run tool.
+"scripts/capture_parent_child_reference.py" = ["T201"]
 
 [tool.ruff.format]
 quote-style = "double"
@@ -217,8 +239,18 @@ warn_unused_configs = true
 disallow_untyped_defs = true
 explicit_package_bases = true
 mypy_path = "src"
+# Excluded by name for the reason `[tool.ruff]` gives above: the capture script is
+# checked like the library, and the hand-run tools written before that was expected
+# are not.
 exclude = [
-    "scripts/",
+    "scripts/capture_flat_reference.py",
+    "scripts/capture_live_flat.py",
+    "scripts/coverage.py",
+    "scripts/format_markdown.py",
+    "scripts/test_live_auth.py",
+    "scripts/validate_lug_derivation/",
+    "scripts/verify_adapterless_install.py",
+    "scripts/verify_reconnect.py",
     "tests/",
     "docs/",
     ".*_cache/",

{span_panel_api-3.1.1 → span_panel_api-3.2.0}/src/span_panel_api/__init__.py

@@ -6,7 +6,7 @@ supporting MQTT/Homie (v2) transport.
 
 from importlib.metadata import version as _pkg_version
 
-from ._ssl import build_panel_ssl_context, ca_fingerprint
+from ._ssl import build_panel_ssl_context, ca_fingerprint, leaf_names_host
 from .auth import (
     delete_fqdn,
     download_ca_cert,
@@ -154,6 +154,9 @@ __all__ = [  # noqa: RUF022
     # both live here rather than being reimplemented on the other side.
     "build_panel_ssl_context",
     "ca_fingerprint",
+    # Added 2026-08-28: the hostname half of verification, split out so a
+    # caller using a relaxed context can still establish the name binding.
+    "leaf_names_host",
     "delete_fqdn",
     "download_ca_cert",
     "get_fqdn",

span_panel_api-3.2.0/src/span_panel_api/_ssl.py

@@ -0,0 +1,223 @@
+"""The panel's trust anchor: building a context from it, and naming it.
+
+Both functions here take a CA in PEM form and nothing else. They make no network
+call and hold no state, which is the point -- a trust anchor that is fetched at
+the moment it is used is not an anchor, it is whatever answered. The fetching
+lives in ``auth.download_ca_cert``, and deciding whether a fetched PEM may be
+trusted lives with the caller.
+
+Public rather than private (``_ssl`` is a module-name convention here, and every
+name is re-exported from the package root) because the consumer needs all three:
+it builds the same context for its own HTTPS calls, it prints and compares the
+same fingerprint string, and it applies the same hostname rules when it has to
+judge a name binding for itself. Two implementations of a fingerprint that must
+agree byte-for-byte is a defect waiting for a firmware upgrade to find it, and
+the same is true of a hand-written hostname matcher -- more so, since that one
+is security-relevant and has no standard-library implementation left to defer
+to since ``ssl.match_hostname`` was removed in Python 3.12.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from collections.abc import Iterator, Mapping
+import hashlib
+import ipaddress
+import ssl
+
+from .exceptions import SpanPanelValidationError
+
+_PEM_HEADER = "-----BEGIN CERTIFICATE-----"
+_PEM_FOOTER = "-----END CERTIFICATE-----"
+
+
+def build_panel_ssl_context(ca_pem: str, *, check_hostname: bool = True) -> ssl.SSLContext:
+    """Build an SSLContext that trusts only the provided panel CA.
+
+    The panel issues a private CA and a server cert signed by it. We do
+    not want to trust system CAs for this connection, so the context is
+    built fresh rather than via ``ssl.create_default_context()``.
+
+    The panel's CA is a minimal self-signed certificate that omits the
+    Authority Key Identifier (AKI) X.509v3 extension. Python 3.13 enabled
+    ``VERIFY_X509_STRICT`` by default, and that flag rejects such a
+    certificate with "Missing Authority Key Identifier", which makes the
+    MQTTS handshake fail on otherwise healthy panels. The flag is cleared
+    here so the library keeps working across Python versions.
+
+    This does not weaken the parts of verification that matter for this
+    connection: the trust anchor is still only the panel's own CA, hostname
+    checking stays enabled by default, and signature/expiry validation is
+    unchanged.
+
+    ``check_hostname=False`` asks a narrower question: *does the peer hold a
+    private key whose certificate chains to this anchor?* The chain, the
+    signature and the expiry are still verified -- only the binding between
+    the certificate and the name used to dial it is left unasserted. That is
+    a real distinction and not a relaxation of trust: an attacker without a
+    CA-signed key cannot complete the handshake either way.
+
+    It exists because the two failures are otherwise indistinguishable, and
+    they call for opposite responses. A panel that has moved to a new DHCP
+    lease serves a perfectly good certificate that no longer names the
+    address it is reached at; something impersonating a panel serves one that
+    chains to nothing. Collapsing both into "verification failed" tells a
+    user their panel has been intercepted when its address merely changed.
+
+    Never pass ``check_hostname=False`` for a connection that carries data.
+    The name binding is what stops a validated certificate being replayed by
+    a host it was not issued to, so a relaxed context belongs only in code
+    that is deciding *which* host to talk to, paired with
+    :func:`leaf_names_host` to establish the binding separately.
+
+    Raises:
+        ssl.SSLError: ``ca_pem`` is not a certificate the ssl module accepts.
+        ValueError: ``ca_pem`` is malformed in a way ``ssl`` reports as such.
+    """
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    ctx.verify_mode = ssl.CERT_REQUIRED
+    ctx.check_hostname = check_hostname
+    ctx.verify_flags &= ~ssl.VERIFY_X509_STRICT
+    ctx.load_verify_locations(cadata=ca_pem)
+    return ctx
+
+
+def leaf_names_host(peer_cert: Mapping[str, object], host: str) -> bool:
+    """Whether a validated peer certificate names ``host`` in its SAN.
+
+    The hostname half of what ``check_hostname=True`` does in one step, split
+    out so a caller that built a relaxed context can still ask the question
+    and act on the answer. ``peer_cert`` is what ``SSLSocket.getpeercert()``
+    returns, which is populated only for a certificate the handshake already
+    validated -- so this function decides naming, never trust.
+
+    Hand-written because ``ssl.match_hostname`` was removed in Python 3.12
+    and nothing replaced it as public API. The rules here are deliberately
+    stricter than the ones it implemented, because a panel's leaf is
+    machine-generated from a fixed template and needs none of the latitude a
+    general-purpose matcher owes the public web:
+
+    - **No wildcards.** ``*.example.com`` is not matched against anything. A
+      panel names literal addresses, so a wildcard in one of its certificates
+      would be an anomaly rather than a case to support.
+    - **No ``commonName`` fallback.** Deprecated for two decades, and every
+      certificate this library meets carries a SAN.
+    - **IP and DNS entries are not interchangeable.** A host that parses as an
+      IP address is matched only against ``IP Address`` entries and a name
+      only against ``DNS`` entries, so a certificate naming the *string*
+      "10.0.0.5" in a DNS entry does not authorise the address 10.0.0.5.
+    - **Addresses compare parsed, names compare casefolded.** ``::1`` and
+      ``0:0:0:0:0:0:0:1`` are one address; ``Panel.local`` and ``panel.local``
+      are one name. A single trailing dot is insignificant on both sides.
+
+    Returns False for anything it cannot read -- a certificate with no SAN, a
+    malformed entry, an unparseable address. The caller's question is "may I
+    treat this name as bound to this certificate", and the honest answer to a
+    SAN that cannot be understood is no.
+    """
+    candidate = _without_root_dot(host)
+    if not candidate:
+        return False
+    entries = list(_san_entries(peer_cert))
+    try:
+        wanted = ipaddress.ip_address(candidate)
+    except ValueError:
+        return _names_dns(entries, candidate)
+    return _names_address(entries, wanted)
+
+
+def _without_root_dot(name: str) -> str:
+    """Strip surrounding space and a single root dot, which is not significant."""
+    stripped = name.strip()
+    return stripped[:-1] if stripped.endswith(".") else stripped
+
+
+def _san_entries(peer_cert: Mapping[str, object]) -> Iterator[tuple[str, str]]:
+    """Yield the readable ``(kind, value)`` pairs of a certificate's SAN.
+
+    Anything malformed is skipped rather than rejected wholesale, so one broken
+    entry cannot hide a good one sitting beside it.
+    """
+    san = peer_cert.get("subjectAltName")
+    if not isinstance(san, tuple | list):
+        return
+    for entry in san:
+        if not isinstance(entry, tuple | list) or len(entry) != 2:
+            continue
+        kind, value = entry
+        if isinstance(kind, str) and isinstance(value, str):
+            yield kind, value
+
+
+def _names_address(entries: list[tuple[str, str]], wanted: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:
+    """Whether an ``IP Address`` entry denotes ``wanted``, compared as addresses."""
+    for kind, value in entries:
+        if kind != "IP Address":
+            continue
+        try:
+            if ipaddress.ip_address(value.strip()) == wanted:
+                return True
+        except ValueError:
+            continue
+    return False
+
+
+def _names_dns(entries: list[tuple[str, str]], candidate: str) -> bool:
+    """Whether a ``DNS`` entry equals ``candidate``, casefolded and exact."""
+    folded = candidate.casefold()
+    for kind, value in entries:
+        if kind != "DNS":
+            continue
+        named = _without_root_dot(value)
+        if named and named.casefold() == folded:
+            return True
+    return False
+
+
+def ca_fingerprint(ca_pem: str) -> str:
+    """SHA-256 over the certificate's DER bytes, lowercase hex, no separators.
+
+    The identity of a trust anchor, in a form a user can compare by eye against
+    what the panel's label or another install reports, and a consumer can store
+    in a config entry.
+
+    Taken over the DER rather than over the PEM text on purpose. PEM is a
+    presentation of the same bytes -- line width, line endings, surrounding
+    blank lines and any explanatory text a firmware chooses to put above the
+    header all vary without the certificate changing -- so a hash of the text
+    would report a rotation that did not happen. That is the worse error of the
+    two available: an integration that raises "your panel's CA changed" every
+    time a firmware reflows its PEM teaches its users to dismiss the one time it
+    matters.
+
+    Only the first certificate in the PEM is read. The panel serves a single
+    self-signed CA; if a future firmware appends a chain, the anchor is still the
+    first element, and silently hashing a concatenation would change the
+    fingerprint of an unchanged anchor.
+
+    Raises:
+        SpanPanelValidationError: no certificate block, or one whose body is not
+            valid base64. Distinct from an ``ssl`` error because nothing has been
+            asked of ``ssl`` yet -- this is a malformed input, and the caller
+            handling it has a different remedy from one whose certificate is
+            well-formed and unacceptable.
+    """
+    start = ca_pem.find(_PEM_HEADER)
+    if start == -1:
+        raise SpanPanelValidationError("No PEM certificate block found; cannot fingerprint the CA")
+    body_start = start + len(_PEM_HEADER)
+    end = ca_pem.find(_PEM_FOOTER, body_start)
+    if end == -1:
+        raise SpanPanelValidationError("PEM certificate block is not terminated; cannot fingerprint the CA")
+
+    # Every run of whitespace is dropped rather than only line breaks, so a PEM
+    # reflowed, re-indented or converted to CRLF fingerprints identically.
+    body = "".join(ca_pem[body_start:end].split())
+    try:
+        der = base64.b64decode(body, validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise SpanPanelValidationError("PEM certificate body is not valid base64; cannot fingerprint the CA") from exc
+    if not der:
+        raise SpanPanelValidationError("PEM certificate block is empty; cannot fingerprint the CA")
+    return hashlib.sha256(der).hexdigest()

{span_panel_api-3.1.1 → span_panel_api-3.2.0}/src/span_panel_api/protocol.py

@@ -275,11 +275,12 @@ class SchemaAdapter(Protocol):
         under the flat schema, `$settable` on `load-shed/priority` under v1.0 --
         which is the same reading `SpanCircuitSnapshot.is_never_backup` reports.
 
-        None also where the panel carries no circuit under that id, and where
-        the device carries no shed priority to write: under v1.0 an absent
-        `$settable` on a *declared* `load-shed/priority` means settable, but a
-        device that declares no such property has offered no such control, and
-        the two are not the same absence.
+        Under v1.0 the lock is announced by *omitting* `$settable`, which is
+        Homie 5's default for the attribute and what a conforming publisher
+        emits for a control that accepts no write. A device that declares no
+        `load-shed/priority` at all answers None for the plainer reason that it
+        has offered no such control -- as does a panel carrying no circuit under
+        that id.
         """
 
     def has_circuit(self, circuit_id: str) -> bool:

{span_panel_api-3.1.1 → span_panel_api-3.2.0}/tests/conftest.py

@@ -26,15 +26,15 @@ _DOTENV = Path(__file__).parent.parent / ".env"
 def _load_dotenv() -> None:
     """Populate the environment from `.env`, without overriding what is set.
 
-    Read directly rather than through python-dotenv: this supplies developer
-    defaults for the optional provenance checks (`EBUS_SPEC_DIR`,
-    `PANELBENCH_DIR`), and taking a dependency to parse two lines would put a
-    package in the test path to save nothing.
+    Read directly rather than through python-dotenv: this supplies the credentials
+    for the one check that needs a real panel (`LIVE_PANEL_*`), and taking a
+    dependency to parse four lines would put a package in the test path to save
+    nothing.
 
     `setdefault`, never assignment. An exported value is a deliberate choice for
-    this run — pointing at a different checkout to reproduce something — and a
-    file silently winning over it is the kind of surprise that costs an
-    afternoon. See `.env.example`; absence is fine, the checks skip.
+    this run — pointing at a second panel to reproduce something — and a file
+    silently winning over it is the kind of surprise that costs an afternoon. See
+    `.env.example`; absence is fine, `test_live_flat_differential.py` skips.
     """
     if not _DOTENV.exists():
         return