span-panel-api 3.6.1b1__tar.gz → 3.6.2__tar.gz

{span_panel_api-3.6.1b1 → span_panel_api-3.6.2}/CHANGELOG.md

@@ -7,21 +7,28 @@ 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.6.1b1]
+## [3.6.2]
 
-3.6.0 was withdrawn from PyPI; this release carries its changes, listed under 3.6.0 below, except how `pv` is chosen, which this release replaces.
+A reconnect waits for the panel's labels before handing out a snapshot, as connecting always has.
 
 ### Changed
 
-- **`SpanPanelSnapshot.pv` is documented as the lone inverter or the inverters together**, and the `schema-1` extra requires `span-panel-api-schema-1` 1.2.1 or newer.
+- **`get_snapshot()` raises `SpanPanelStaleDataError` while a rebuilt tree's names and feed links are still arriving**, as it already did while the tree itself was, and for at most the same wait connecting allows.
+- **`connect()` no longer raises an adapter's error from its wait for the panel's labels**, logging it at ERROR and serving the tree as it is, and only connect warns about labels that never arrive, while a reconnect logs that timeout at DEBUG.
+- **The `schema-1` extra requires `span-panel-api-schema-1` 1.2.2 or newer**, the adapter that restarts its feed-link wait correctly.
 
-## [3.6.0] [YANKED]
+### Fixed
+
+- **A reconnect no longer produces a snapshot in which a PV inverter is keyed by its device id or its feeding circuit reads as a load**, because after the broker connection is rebuilt no snapshot is dispatched until the replayed tree's circuit names and
+  feed links have arrived.
+
+## [3.6.1]
 
 The snapshot carries every PV inverter a panel commissions, and registration copes with a panel that cannot read its own passphrase.
 
 ### Added
 
-- **`SpanPanelSnapshot.pv_inverters`** carries every commissioned PV inverter, keyed by its feeding circuit's id, which stays put when firmware r202639 renames a panel's inverters, or by its device id where no circuit feeds it.
+- **`SpanPanelSnapshot.pv_inverters`** carries every commissioned PV inverter, keyed by its feeding circuit's id, which stays put when firmware r202639 changes a panel's PV device ids, or by its device id where no circuit feeds it.
 - **`SpanPVSnapshot.serial_number`, `device_id` and `node_id`** give an inverter's serial number when one is published, its id on the wire, and its key in `pv_inverters`.
 - **`SpanEvseSnapshot.effective_charge_current_limit_a`** is the charge-current limit a charger is applying, its user limit when one is published and its ceiling otherwise, since from firmware r202639 a SPAN Drive publishes a user limit only once someone
   sets one.
@@ -29,10 +36,16 @@ The snapshot carries every PV inverter a panel commissions, and registration cop
 
 ### Changed
 
+- **`SpanPanelSnapshot.pv` describes the inverters together when more than one is commissioned**, carrying only their shared vendor and model, the sum of their installed DC sizes and a link that is down if any is down, rather than whichever one the adapter
+  met first.
+- **`SpanPVSnapshot.nameplate_capacity_w` is documented as the array's DC size recorded at installation**, an informational figure and never a ceiling on PV power.
 - **`V2AuthResponse.ebus_broker_password` and `hop_passphrase` are `str | None`**, `None` when a panel on firmware r202639 or later cannot read its passphrase yet still issues a valid access token.
 - **`register_v2` raises `SpanPanelServerError` with `status_code` for any 5xx**, including the 503 a panel on firmware r202639 answers until it knows its serial number, where it raised a plain `SpanPanelAPIError`.
-- **`SpanPanelSnapshot.pv` is the inverter on the lowest breaker space when more than one is commissioned**, rather than whichever one the adapter met first.
-- **`SpanPVSnapshot.nameplate_capacity_w` is documented as the array's DC size recorded at installation**, an informational figure and never a ceiling on PV power.
+- **The `schema-0` and `schema-1` extras require `span-panel-api-schema-0` 1.2.0 and `span-panel-api-schema-1` 1.2.1 or newer**, the adapters that fill `pv_inverters`.
+
+## [3.6.0] [YANKED]
+
+Withdrawn from PyPI; 3.6.1 replaces it.
 
 ## [3.5.0]
 

{span_panel_api-3.6.1b1 → span_panel_api-3.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.6.1b1
+Version: 3.6.2
 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
@@ -22,7 +22,7 @@ Requires-Dist: pyyaml>=6.0.0
 Provides-Extra: schema-0
 Requires-Dist: span-panel-api-schema-0>=1.2.0; extra == 'schema-0'
 Provides-Extra: schema-1
-Requires-Dist: span-panel-api-schema-1>=1.2.1b1; extra == 'schema-1'
+Requires-Dist: span-panel-api-schema-1>=1.2.2; extra == 'schema-1'
 Description-Content-Type: text/markdown
 
 # SPAN Panel API

{span_panel_api-3.6.1b1 → span_panel_api-3.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.6.1b1"
+version = "3.6.2"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -63,8 +63,10 @@ dependencies = [
 # the inverter identity fields 3.6.0 adds. Upgrading through the extra is what
 # brings the adapters that do.
 schema-0 = ["span-panel-api-schema-0>=1.2.0"]
-# Raised to 1.2.1b1 for 3.6.1b1: that adapter stops ranking one inverter as pv.
-schema-1 = ["span-panel-api-schema-1>=1.2.1b1"]
+# Raised to 1.2.1 for 3.6.1: that adapter builds the `pv` that `SpanPanelSnapshot.pv` now documents.
+# Raised to 1.2.2 for 3.6.2: the readiness gate every snapshot passes asks that
+# adapter what is still missing, and 1.2.2 restarts its feed grace correctly.
+schema-1 = ["span-panel-api-schema-1>=1.2.2"]
 
 [project.urls]
 Homepage = "https://github.com/SpanPanel/span-panel-api"

{span_panel_api-3.6.1b1 → span_panel_api-3.6.2}/src/span_panel_api/__init__.py

@@ -211,7 +211,7 @@ __all__ = [  # noqa: RUF022
     # Added 2026-10-02 (3.5.0): a 403 from a reduced-privilege token. A subclass
     # of SpanPanelAuthError, so every existing except clause keeps its meaning.
     "SpanPanelInsufficientPrivilegeError",
-    # Added 2026-10-06 (3.6.0): registration reached a panel that cannot read its own
+    # Added 2026-10-06 (3.6.1): registration reached a panel that cannot read its own
     # passphrase. A subclass of SpanPanelAPIError, so existing except clauses
     # keep their meaning; deliberately not a SpanPanelAuthError, because the
     # passphrase the user supplied may be correct.

{span_panel_api-3.6.1b1 → span_panel_api-3.6.2}/src/span_panel_api/mqtt/client.py

@@ -193,6 +193,16 @@ class SpanMqttClient:
         self._schema_change_callbacks: list[Callable[[str | None, str | None], None]] = []
         self._live = False
         self._ready_event: asyncio.Event | None = None
+        # The readiness gate's latch. A tree is dispatchable once it is complete
+        # *and* its labels have settled, and the second half is a wait rather than
+        # a predicate: `_settle` polls the adapter until nothing is missing or the
+        # wait runs out, then records the adapter it settled here. Keyed on the
+        # adapter instance, so every new tree -- connect, a bridge rebuild, a
+        # generation swap -- starts unsettled without anything having to reset it.
+        self._settled_adapter: SchemaAdapter | None = None
+        self._settling_adapter: SchemaAdapter | None = None
+        self._settle_task: asyncio.Task[None] | None = None
+        self._has_settled = False
         self._loop: asyncio.AbstractEventLoop | None = None
         self._background_tasks: set[asyncio.Task[None]] = set()
         self._snapshot_timer: asyncio.TimerHandle | None = None
@@ -513,12 +523,19 @@ class SpanMqttClient:
             await self.close()
             raise SpanPanelConnectionError(f"Timed out waiting for Homie device ready ({self._serial_number})") from exc
 
-        _LOGGER.debug("MQTT: Homie device ready, waiting for circuit names...")
+        _LOGGER.debug("MQTT: Homie device ready, waiting for its labels...")
 
-        # Wait for circuit name properties to arrive (retained messages
-        # may arrive after $state=ready). Without this, the first snapshot
-        # has empty circuit names and entities are created without labels.
-        await self._wait_for_circuit_names(timeout=_CIRCUIT_NAMES_TIMEOUT_S)
+        # The tree's labels arrive as retained values that may land after it is
+        # complete. The ready edge in `_on_message` started the one wait every
+        # tree goes through, so connect returns only once the first snapshot a
+        # caller can take carries them.
+        # `wait` rather than awaiting the task: `close()` cancels it, and that must
+        # end this wait rather than surface here as a cancellation of connect().
+        settle = self._settle_task
+        if settle is not None:
+            await asyncio.wait([settle])
+            if not settle.cancelled():
+                settle.result()
 
         self._assert_transports_agree_on_schema_generation()
         _LOGGER.debug("MQTT: Connection fully established")
@@ -755,6 +772,8 @@ class SpanMqttClient:
             raise SpanPanelStaleDataError("MQTT broker disconnected")
         if not self._adapter.is_ready():
             raise SpanPanelStaleDataError("Homie device not ready")
+        if not self._snapshot_ready(self._adapter):
+            raise SpanPanelStaleDataError("Homie device not ready: its labels are still arriving")
         return self._adapter.build_snapshot()
 
     # -- CircuitControlProtocol --------------------------------------------
@@ -1370,11 +1389,13 @@ class SpanMqttClient:
         adapter.handle_message(topic, payload)
 
         # Check if device just became ready
-        if not was_ready and adapter.is_ready() and self._ready_event is not None:
-            self._ready_event.set()
+        if not was_ready and adapter.is_ready():
+            if self._ready_event is not None:
+                self._ready_event.set()
+            self._start_settling(adapter)
 
         # Dispatch snapshot callbacks if streaming
-        if self._streaming and adapter.is_ready() and self._loop is not None:
+        if self._streaming and self._snapshot_ready(adapter) and self._loop is not None:
             if self._snapshot_interval <= 0:
                 # Real-time mode — dispatch immediately, no debounce.
                 self._create_dispatch_task()
@@ -1693,6 +1714,8 @@ class SpanMqttClient:
         old paho client is torn down and the new one is wired up. Discards
         any stale `$state=disconnected` cached during the outage so the
         new subscription's retained messages repopulate from a clean slate.
+        The fresh adapter is unsettled by construction, so nothing is
+        dispatched from it until its labels have passed the readiness gate.
 
         Schema-derived state (`_schema`, `_schema_hash`,
         `_previous_schema_types`) is intentionally preserved — the Homie
@@ -1719,29 +1742,122 @@ class SpanMqttClient:
         _LOGGER.debug("Pre-rebuild — resetting Homie accumulator")
         self._build_adapter(self._schema)
 
-    async def _wait_for_circuit_names(self, timeout: float) -> None:
-        """Wait for all circuit-like nodes to have a ``name`` property.
+    # -- The readiness gate ------------------------------------------------
+    #
+    # One gate for every snapshot this client hands out, whichever path built the
+    # tree it comes from. A tree is complete once every device has described
+    # itself; its labels -- circuit names, DER models, the feed links that key an
+    # inverter and type its circuit -- are separate retained values that a broker
+    # may replay after the last description. `connect()` used to wait those out
+    # on its own, so the first snapshot after a bridge rebuild was dispatched from
+    # a tree that had its shape and not its labels: an inverter keyed by its
+    # device id, and its feeding circuit read as a load, for one dispatch.
+    #
+    # The adapter answers what is still missing (`circuit_nodes_missing_names`,
+    # which also bounds the feed wait with its own grace). The waiting itself
+    # lives here, once, and runs for every tree from its ready edge.
+
+    def _snapshot_ready(self, adapter: SchemaAdapter) -> bool:
+        """Whether `adapter`'s tree may be handed out: complete, and its labels settled."""
+        return adapter.is_ready() and self._settled_adapter is adapter
+
+    def _start_settling(self, adapter: SchemaAdapter) -> None:
+        """Start the label wait for `adapter`'s tree, unless it is settled or already settling.
+
+        Called on every ready edge. A tree can drop out of readiness and return
+        within one adapter's life -- a device commissioned mid-session is
+        undescribed for a moment -- and that is not a new tree, so it neither
+        restarts a wait in progress nor reopens a settled one.
+        """
+        if self._loop is None or self._settled_adapter is adapter or self._settling_adapter is adapter:
+            return
+        self._settling_adapter = adapter
+        task = self._loop.create_task(self._settle(adapter), name="span_mqtt_settle_labels")
+        self._settle_task = task
+        self._background_tasks.add(task)
+        task.add_done_callback(self._background_tasks.discard)
+
+    async def _settle(self, adapter: SchemaAdapter) -> None:
+        """Wait out `adapter`'s labels, open the gate for it, and dispatch what it now holds.
+
+        A tree replaced while this waited -- a second rebuild, a generation swap --
+        is left unsettled: its successor has a wait of its own.
 
-        Retained MQTT messages may arrive after the Homie device transitions
-        to ready. This polls the schema adapter at short intervals and
-        returns as soon as all circuit names are populated, or when the
-        timeout elapses (non-fatal — entities will use fallback names).
+        The dispatch is not optional. The replay is a burst, and a panel can be
+        quiet once it ends; without it a streaming consumer would see nothing from
+        the rebuilt tree until some value happened to change.
+
+        The gate always opens. A wait that times out serves the tree as it is, and
+        an adapter that raises is waited out to the same deadline (see
+        `_wait_for_circuit_names`). The guard here is the last resort behind that:
+        nothing awaits a rebuild's settle, so an exception escaping the wait itself
+        would close the gate for the tree's whole life without a word.
+        Cancellation is not a failure and still propagates; `close()` relies on it.
+
+        Only the client's first wait, which is connect's, reports a timeout as a
+        warning. A label that is never published would otherwise be warned about
+        again on every broker reconnect, and the user can act on it once.
+        """
+        first = not self._has_settled
+        self._has_settled = True
+        try:
+            await self._wait_for_circuit_names(
+                adapter,
+                timeout=_CIRCUIT_NAMES_TIMEOUT_S,
+                timeout_level=logging.WARNING if first else logging.DEBUG,
+            )
+        except Exception:  # pylint: disable=broad-exception-caught
+            _LOGGER.error("Could not tell whether the panel's labels have arrived; serving its tree as it is", exc_info=True)
+        if self._adapter is not adapter:
+            return
+        self._settled_adapter = adapter
+        if self._streaming:
+            self._create_dispatch_task()
+
+    async def _wait_for_circuit_names(self, adapter: SchemaAdapter, timeout: float, timeout_level: int) -> None:
+        """Wait until `adapter` reports nothing missing, or the timeout elapses.
+
+        Polls `circuit_nodes_missing_names` at short intervals rather than
+        reacting to messages, because the adapter's feed grace is measured on
+        its own clock and must be able to expire while the panel is silent.
+        A timeout is not fatal: entities fall back to placeholder names, and
+        what is still missing is logged at `timeout_level`.
+
+        A poll that raises counts as one that found labels missing, and the
+        wait goes on to its deadline. A transient fault then costs nothing, and
+        cannot open the gate early on whatever names happen to have arrived --
+        which, on a first install, a consumer turns into permanent entity ids.
+        The fault is reported at ERROR once per wait, with its exception.
         """
-        adapter = self._require_adapter()
         deadline = time.monotonic() + timeout
-        while time.monotonic() < deadline:
-            missing = adapter.circuit_nodes_missing_names()
-            if not missing:
+        fault_reported = False
+        while True:
+            missing: list[str] | None
+            try:
+                missing = adapter.circuit_nodes_missing_names()
+            except Exception:  # pylint: disable=broad-exception-caught
+                missing = None
+                if not fault_reported:
+                    _LOGGER.error(
+                        "Could not ask the parser which of the panel's labels are missing; waiting them out",
+                        exc_info=True,
+                    )
+                    fault_reported = True
+            if missing is not None and not missing:
                 _LOGGER.debug("All circuit names received")
                 return
+            if time.monotonic() >= deadline:
+                break
             await asyncio.sleep(_CIRCUIT_NAMES_POLL_INTERVAL_S)
 
-        still_missing = adapter.circuit_nodes_missing_names()
-        if still_missing:
-            _LOGGER.warning(
+        if missing is None:
+            _LOGGER.log(timeout_level, "Timed out waiting for circuit names (the parser could not say which are missing)")
+        else:
+            _LOGGER.log(
+                timeout_level,
                 "Timed out waiting for circuit names (%d still missing): %s",
-                len(still_missing),
-                still_missing[:5],
+                len(missing),
+                missing[:5],
             )
 
     def _create_dispatch_task(self) -> None:
@@ -1783,18 +1899,19 @@ class SpanMqttClient:
         """Build snapshot and send to all registered callbacks.
 
         Guarded by the same liveness predicate as get_snapshot() — if the
-        bridge has disconnected or the Homie device is not ready, no
-        dispatch occurs. This prevents a pending debounce timer that was
-        scheduled just before a disconnect from delivering a stale
-        snapshot to subscribers after the fact.
+        bridge has disconnected, or the tree is not ready or its labels have
+        not settled, no dispatch occurs. This prevents a pending debounce timer
+        that was scheduled just before a disconnect or a rebuild from delivering
+        a stale or half-replayed snapshot to subscribers after the fact.
         """
         bridge = self._bridge
         adapter = self._adapter
-        if bridge is None or not bridge.is_connected() or adapter is None or not adapter.is_ready():
+        if bridge is None or not bridge.is_connected() or adapter is None or not self._snapshot_ready(adapter):
             _LOGGER.debug(
-                "Skipping stale snapshot dispatch (bridge_connected=%s, homie_ready=%s)",
+                "Skipping stale snapshot dispatch (bridge_connected=%s, homie_ready=%s, labels_settled=%s)",
                 bridge is not None and bridge.is_connected(),
                 adapter is not None and adapter.is_ready(),
+                adapter is not None and self._settled_adapter is adapter,
             )
             return
         snapshot = adapter.build_snapshot()

{span_panel_api-3.6.1b1 → span_panel_api-3.6.2}/tests/test_mqtt_client_connection.py

@@ -71,6 +71,9 @@ class _FakeAdapter:
     def topics_to_subscribe(self) -> list[str]:
         return [WILDCARD_TOPIC_FMT.format(serial="test-serial")]
 
+    def circuit_nodes_missing_names(self) -> list[str]:
+        return []
+
 
 class TestRegisterConnectionCallback:
     """Callback subscription API — structural only (fan-out is tested in Task 4)."""
@@ -325,10 +328,22 @@ class TestGetSnapshotLiveness:
         client = _make_client()
         client._bridge = _FakeBridge(connected=True)
         client._adapter = _FakeAdapter(ready=True, snapshot=sentinel)
+        # Ready and labelled: the readiness gate opens for it.
+        await client._settle(client._adapter)
 
         snapshot = await client.get_snapshot()
         assert snapshot is sentinel
 
+    async def test_raises_stale_while_labels_are_still_arriving(self) -> None:
+        """A complete tree whose labels have not passed the readiness gate is not handed out."""
+        client = _make_client()
+        client._bridge = _FakeBridge(connected=True)
+        client._adapter = _FakeAdapter(ready=True, snapshot=_make_sentinel_snapshot())
+
+        with pytest.raises(SpanPanelStaleDataError) as exc_info:
+            await client.get_snapshot()
+        assert "labels" in str(exc_info.value).lower()
+
     async def test_raised_exception_is_span_panel_error(self) -> None:
         client = _make_client()
         client._bridge = None
@@ -403,6 +418,8 @@ class TestStaleSnapshotDispatchGuard:
         client = _make_client()
         client._bridge = _FakeBridge(connected=True)
         client._adapter = _FakeAdapter(ready=True, snapshot=snapshot_sentinel)
+        # Ready and labelled: the readiness gate opens for it.
+        await client._settle(client._adapter)
 
         calls: list[SpanPanelSnapshot] = []
 

{span_panel_api-3.6.1b1 → span_panel_api-3.6.2}/tests/test_mqtt_homie.py

@@ -1146,6 +1146,9 @@ class TestSpanMqttClientSnapshot:
         client._adapter.handle_message(f"{PREFIX}/$state", "ready")
         client._adapter.handle_message(f"{PREFIX}/$description", _make_description(_core_description()))
         client._adapter.handle_message(f"{PREFIX}/core/software-version", "test-fw")
+        # Fed directly rather than through `_on_message`, so the readiness gate
+        # is passed explicitly.
+        await client._settle(client._adapter)
 
         snapshot = await client.get_snapshot()
         assert snapshot.serial_number == SERIAL

{span_panel_api-3.6.1b1 → span_panel_api-3.6.2}/tests/test_public_api_unchanged.py

@@ -161,7 +161,7 @@ EXPECTED_PUBLIC_API = {
     # Added 2026-10-02 (3.5.0): a 403 from a reduced-privilege token. A subclass
     # of SpanPanelAuthError, so every existing except clause keeps its meaning.
     "SpanPanelInsufficientPrivilegeError",
-    # Added 2026-10-06 (3.6.0): registration reached a panel that cannot read its own
+    # Added 2026-10-06 (3.6.1): registration reached a panel that cannot read its own
     # passphrase. Additive, and a SpanPanelAPIError subclass rather than a
     # SpanPanelAuthError, so no existing except clause starts telling a user
     # their passphrase is wrong.

{span_panel_api-3.6.1b1 → span_panel_api-3.6.2}/tests/test_schema_one_adapter.py

@@ -517,6 +517,46 @@ def test_the_feed_grace_starts_only_once_everything_else_has_arrived() -> None:
     assert SOLAR_CIRCUIT in adapter.circuit_nodes_missing_names()
 
 
+def test_the_feed_grace_restarts_once_every_inverter_has_been_placed() -> None:
+    """A grace is spent on one wait, not carried into the next.
+
+    The first inverter's feed is waited on and arrives. Later the panel
+    commissions a second inverter whose feed has not landed yet; that wait gets
+    a full grace of its own rather than inheriting the first one's start time,
+    which has long since run out and would key the new inverter by its device id
+    the moment it appears.
+    """
+    second_circuit = "5be1d2c3a4f5061728394a5b6c7d8e9f"
+    second_pv = "pv-2"
+    now = [100.0]
+    adapter = SchemaOneAdapter(PANEL, _schema(), clock=lambda: now[0])
+    _feed(adapter, omit=("connection/feeds-device-id",))
+    assert SOLAR_CIRCUIT in adapter.circuit_nodes_missing_names()
+    adapter.handle_message(
+        f"ebus/5/{SOLAR_CIRCUIT}/connection/feeds-device-id", _TREE[SOLAR_CIRCUIT]["connection/feeds-device-id"]
+    )
+    assert adapter.circuit_nodes_missing_names() == []
+
+    now[0] += FEED_GRACE_S + 1
+    description = json.loads(_TREE[PANEL]["$description"])
+    description["children"] = [*description["children"], second_circuit, second_pv]
+    tree = {
+        PANEL: {**_TREE[PANEL], "$description": json.dumps(description)},
+        second_pv: {**_TREE["pv"], "info/model": "SE7600H-B"},
+        second_circuit: {
+            topic: value for topic, value in _TREE[SOLAR_CIRCUIT].items() if topic != "connection/feeds-device-id"
+        }
+        | {"info/name": "Garage Solar", "info/spaces": "5,7"},
+    }
+    _feed(adapter, [PANEL, second_pv, second_circuit], tree=tree)
+    assert {inverter.device_id for inverter in adapter.build_snapshot().pv_inverters.values()} == {
+        "pv",
+        second_pv,
+    }, "precondition: the second inverter was commissioned"
+
+    assert second_circuit in adapter.circuit_nodes_missing_names()
+
+
 def test_the_panel_firmware_version_is_waited_on_when_a_battery_is_declared() -> None:
     """The release build in the panel's firmware version decides the BESS meter's frame.
 

span_panel_api-3.6.2/tests/test_schema_one_undeclared_devices.py

@@ -0,0 +1,166 @@
+"""A device the panel no longer declares is not part of the panel, whatever it left behind.
+
+Firmware r202639 renames a panel's inverters once it publishes more than one: the
+single inverter's `<panel>-se7600h-us` becomes `<panel>-se7600h-us-<n>`, one per
+inverter. The upgrade does not clear the old device's retained topics, so the
+broker keeps replaying a `$description` that still names the panel as its root
+and parent, beside the new devices, until something removes it.
+
+Membership comes from the parent's `$description.children` alone. The SDK
+subscribes to a child only once its parent declares it (and drops one the parent
+stops declaring), and `ControllerRoutes` holds a message no route has asked for
+rather than delivering it. A stale device's own claim to a parent is never read.
+These tests pin that through the adapter's real `handle_message` path, so an
+`ebus-sdk` upgrade that changed how the tree is walked would fail here rather than
+surface as a ghost inverter.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from reference_payloads.schema_one import RetainedTopicTree, parent_child_tree
+from span_panel_api.models import V2HomieSchema
+from span_panel_api_schema_1 import SchemaOneAdapter
+
+PANEL = "example-40t-001"
+SOLAR_CIRCUIT = "573066aaddd7b75114c4563ce3af18c4"
+SECOND_SOLAR_CIRCUIT = "5be1d2c3a4f5061728394a5b6c7d8e9f"
+
+# Illustrative ids in the shape firmware r202639 uses.
+STALE_PV = f"{PANEL}-se7600h-us"
+FIRST_PV = f"{PANEL}-se7600h-us-1"
+SECOND_PV = f"{PANEL}-se7600h-us-2"
+STALE_MODEL = "SE7600H-STALE"
+
+
+def _schema() -> V2HomieSchema:
+    return V2HomieSchema(
+        firmware_version="spanos2/r202639/01",
+        types_schema_hash="sha256:test",
+        types={},
+        data_model_version="1.0",
+    )
+
+
+def _with_children(tree: dict[str, dict[str, str]], children: list[str]) -> None:
+    description = json.loads(tree[PANEL]["$description"])
+    description["children"] = children
+    tree[PANEL] = {**tree[PANEL], "$description": json.dumps(description)}
+
+
+def _upgraded_tree(stale_state: str | None) -> dict[str, dict[str, str]]:
+    """Two declared inverters, each fed by its own circuit; and, unless `stale_state` is None,
+    the old inverter's retained topics, which the panel no longer declares."""
+    tree = {device_id: dict(topics) for device_id, topics in parent_child_tree().items()}
+    pv = tree.pop("pv")
+    declared = [child for child in json.loads(tree[PANEL]["$description"])["children"] if child != "pv"]
+    _with_children(tree, [*declared, SECOND_SOLAR_CIRCUIT, FIRST_PV, SECOND_PV])
+    tree[FIRST_PV] = dict(pv)
+    tree[SECOND_PV] = {**pv, "info/model": "SE7600H-B"}
+    tree[SOLAR_CIRCUIT]["connection/feeds-device-id"] = FIRST_PV
+    tree[SECOND_SOLAR_CIRCUIT] = {
+        **tree[SOLAR_CIRCUIT],
+        "connection/feeds-device-id": SECOND_PV,
+        "info/name": "Garage Solar",
+        "info/spaces": "5,7",
+    }
+    if stale_state is not None:
+        tree[STALE_PV] = {**pv, "$state": stale_state, "info/model": STALE_MODEL}
+    return tree
+
+
+def _replay(adapter: SchemaOneAdapter, tree: RetainedTopicTree, order: list[str]) -> None:
+    """Deliver each device's retained topics as the broker would, in `order`."""
+    for device_id in order:
+        topics = tree[device_id]
+        prefix = f"ebus/5/{device_id}"
+        adapter.handle_message(f"{prefix}/$description", topics["$description"])
+        adapter.handle_message(f"{prefix}/$state", topics["$state"])
+        for topic, value in topics.items():
+            if not topic.startswith("$"):
+                adapter.handle_message(f"{prefix}/{topic}", value)
+
+
+def _without_stale() -> SchemaOneAdapter:
+    tree = _upgraded_tree(None)
+    adapter = SchemaOneAdapter(PANEL, _schema())
+    _replay(adapter, tree, [PANEL, *[device_id for device_id in tree if device_id != PANEL]])
+    return adapter
+
+
+def _assert_stale_pv_is_absent(adapter: SchemaOneAdapter) -> None:
+    """Nothing the adapter reports differs from a broker that never held the stale device."""
+    reference = _without_stale()
+    snapshot = adapter.build_snapshot()
+
+    assert adapter.is_ready()
+    assert snapshot == reference.build_snapshot()
+    assert adapter.build_field_metadata() == reference.build_field_metadata()
+    # Spelled out as well, so a failure names what leaked.
+    assert {key: inverter.device_id for key, inverter in snapshot.pv_inverters.items()} == {
+        SOLAR_CIRCUIT: FIRST_PV,
+        SECOND_SOLAR_CIRCUIT: SECOND_PV,
+    }
+    assert snapshot.pv.model is None
+    assert all(device.device_id != STALE_PV for device in snapshot.adopted_devices)
+
+
+@pytest.mark.parametrize("stale_state", ["ready", "init", "disconnected", "lost"])
+@pytest.mark.parametrize("stale_first", [True, False], ids=["stale-replayed-first", "stale-replayed-last"])
+def test_a_pv_device_the_panel_no_longer_declares_never_reaches_the_snapshot(stale_state: str, stale_first: bool) -> None:
+    """Whatever its retained `$state` -- `ready` included -- and whenever the broker replays it."""
+    tree = _upgraded_tree(stale_state)
+    others = [device_id for device_id in tree if device_id not in (PANEL, STALE_PV)]
+    adapter = SchemaOneAdapter(PANEL, _schema())
+
+    _replay(adapter, tree, [STALE_PV, PANEL, *others] if stale_first else [PANEL, *others, STALE_PV])
+
+    _assert_stale_pv_is_absent(adapter)
+
+
+def _before_the_upgrade() -> dict[str, dict[str, str]]:
+    """The panel before r202639: one inverter, declared, under the id the upgrade retires."""
+    tree = {device_id: dict(topics) for device_id, topics in parent_child_tree().items()}
+    tree[STALE_PV] = {**tree.pop("pv"), "info/model": STALE_MODEL}
+    declared = json.loads(tree[PANEL]["$description"])["children"]
+    _with_children(tree, [STALE_PV if child == "pv" else child for child in declared])
+    tree[SOLAR_CIRCUIT]["connection/feeds-device-id"] = STALE_PV
+    return tree
+
+
+def test_a_declared_pv_device_does_reach_the_snapshot() -> None:
+    """The control: the same device, declared, is read -- so the tests above can see a leak."""
+    tree = _before_the_upgrade()
+    adapter = SchemaOneAdapter(PANEL, _schema())
+
+    _replay(adapter, tree, [PANEL, *[device_id for device_id in tree if device_id != PANEL]])
+
+    snapshot = adapter.build_snapshot()
+    assert {key: inverter.device_id for key, inverter in snapshot.pv_inverters.items()} == {SOLAR_CIRCUIT: STALE_PV}
+    assert snapshot.pv.model == STALE_MODEL
+
+
+@pytest.mark.parametrize("republished", ["through-init", "while-ready"])
+def test_a_pv_device_the_panel_stops_declaring_mid_session_leaves_the_snapshot(republished: str) -> None:
+    """An adapter running across the upgrade drops the inverter the new `$description` no longer names.
+
+    The panel either passes through `init` before announcing its new tree, or
+    republishes its `$description` while staying `ready`; both must drop it.
+    """
+    before = _before_the_upgrade()
+    adapter = SchemaOneAdapter(PANEL, _schema())
+    _replay(adapter, before, [PANEL, *[device_id for device_id in before if device_id != PANEL]])
+    after = _upgraded_tree("ready")
+
+    if republished == "through-init":
+        adapter.handle_message(f"ebus/5/{PANEL}/$state", "init")
+    adapter.handle_message(f"ebus/5/{PANEL}/$description", after[PANEL]["$description"])
+    if republished == "through-init":
+        adapter.handle_message(f"ebus/5/{PANEL}/$state", "ready")
+    # Then everything else retained, the stale inverter included.
+    _replay(adapter, after, [device_id for device_id in after if device_id != PANEL])
+
+    _assert_stale_pv_is_absent(adapter)