span-panel-api 3.6.1b1__tar.gz → 3.7.0b1__tar.gz

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

@@ -7,21 +7,55 @@ 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]
+## [Unreleased]
 
-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.
+Snapshot fields that held a fabricated constant can now be unknown, and with `span-panel-api-schema-0` and `span-panel-api-schema-1` 1.3.0 or newer the parsers report them as unknown and stop synthesising unoccupied positions.
+
+### Added
+
+- **`V2StatusInfo.hardware_version` reports the hardware version string from `GET /api/v2/status`.**
 
 ### 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.
+- **BREAKING FOR CONSUMERS: `SpanPanelSnapshot.proximity_proven` becomes `bool | None`**, and with `span-panel-api-schema-0` and `span-panel-api-schema-1` 1.3.0 or newer it is always `None`, where it was effectively a constant `True`, because neither MQTT
+  schema publishes a proximity property and the panel's own answer is `V2StatusInfo.proximity_proven`.
+- **BREAKING FOR CONSUMERS: `SpanPanelSnapshot.uptime_s` becomes `int | None`**, and with those parsers it is `None` on a parent/child panel and before a flat panel first reports ready, where it was a constant `0`.
+- **BREAKING FOR CONSUMERS: `SpanCircuitSnapshot.instant_power_update_time_s` and `energy_accum_update_time_s` become `int | None` and default to `None`**, and with those parsers they are `None` until the reading has arrived and always on a parent/child
+  panel, where they were `0`.
+- **The `schema-0` and `schema-1` extras require `span-panel-api-schema-0` and `span-panel-api-schema-1` 1.3.0 or newer**, the adapters that report these values as unknown.
 
-## [3.6.0] [YANKED]
+### Removed
+
+- **BREAKING: with `span-panel-api-schema-0` and `span-panel-api-schema-1` 1.3.0 or newer, snapshots no longer include synthesised `unmapped_tab_N` entries for unoccupied breaker positions, which carried no measured data**, so `SpanPanelSnapshot.circuits`
+  holds only real circuits and `panel_size` alone states the panel's total positions.
+
+### Fixed
+
+- **`V2HomieSchema.types_schema_hash` on data model 1.0 is the panel's published `deviceClassesSchemaHash`, or a hash of `deviceClasses` when none is published, where it was one constant for every such panel**; a flat panel's value is unchanged, and a
+  value stored from 3.6.x differs once on a data model 1.0 panel.
+
+## [3.6.2]
+
+A reconnect waits for the panel's labels before handing out a snapshot, as connecting always has.
+
+### Changed
+
+- **`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.
+
+### 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 +63,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]
 
@@ -467,8 +507,7 @@ Everything below is additive. Each field is `None` or empty on a panel that publ
   `MQTT_FULL_REBUILD_AFTER_FAILURES` (3) consecutive failures, or immediately on any `ssl.SSLError`. The previous behavior pinned the panel's CA certificate into the paho client once at `connect()` time and re-used it across all reconnect attempts; if the
   panel rotated its private CA — most plausibly during a firmware upgrade — every subsequent reconnect raised `ssl.SSLCertVerificationError` (caught by the broad `OSError` clause and silently retried) and the bridge could not recover without a config-entry
   reload. The rebuild mirrors what a manual reload does without going through HA's `config_entry` teardown, so entities stay registered and the integration's grace-period logic continues to apply unchanged. The threshold-cadence design (counter reset on
-  every rebuild attempt, success or fail) keeps the recovery path active throughout extended outages — multi-day disconnections recover whenever the panel becomes usable again, including if the CA rotates a second time mid-outage. See
-  `SpanPanel_Docs/span-panel-api/2026-05-17-mqtt-ca-refresh-on-reconnect-design.md` for the full design.
+  every rebuild attempt, success or fail) keeps the recovery path active throughout extended outages — multi-day disconnections recover whenever the panel becomes usable again, including if the CA rotates a second time mid-outage.
 
 ### Added
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.6.1b1
+Version: 3.7.0b1
 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
@@ -20,9 +20,9 @@ Requires-Dist: httpx<1.0,>=0.28.1
 Requires-Dist: paho-mqtt<3.0.0,>=2.0.0
 Requires-Dist: pyyaml>=6.0.0
 Provides-Extra: schema-0
-Requires-Dist: span-panel-api-schema-0>=1.2.0; extra == 'schema-0'
+Requires-Dist: span-panel-api-schema-0>=1.3.0b1; 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.3.0b1; extra == 'schema-1'
 Description-Content-Type: text/markdown
 
 # SPAN Panel API
@@ -175,8 +175,8 @@ transport-specific classes.
 
 All panel state is represented as immutable, frozen dataclasses:
 
-- **`SpanPanelSnapshot`**: complete panel state. Identity (serial, firmware, vendor, model, hardware version), panel size, main breaker rating, main relay, door and proximity state, uptime, network links with the Wi-Fi SSID and vendor cloud, grid and
-  feedthrough power and energy, grid/DSM state, run configuration, dominant power source, grid islandability, per-leg voltages, power flows, lugs current and whether the lugs are the service entrance, shed policy and forecast. It holds `circuits`,
+- **`SpanPanelSnapshot`**: complete panel state. Identity (serial, firmware, vendor, model, hardware version), panel size, main breaker rating, main relay, door state, connection uptime on a flat panel, network links with the Wi-Fi SSID and vendor cloud,
+  grid and feedthrough power and energy, grid/DSM state, run configuration, dominant power source, grid islandability, per-leg voltages, power flows, lugs current and whether the lugs are the service entrance, shed policy and forecast. It holds `circuits`,
   `battery`, `pv`, `pv_inverters`, `evse`, `mid`, `pcs`, `adopted_devices` and `extension_properties`.
 - **`SpanCircuitSnapshot`**: one circuit. Id, name, relay state and requester, power, energy and their update times, tabs, 240 V, breaker rating, current, priority, user controllability, sheddable / never-backup / always-on flags, device type, relative
   position, PCS management and priority, and the `$target` pending state for relay and priority.
@@ -195,6 +195,9 @@ see the changelog, because `battery.model` changes value for existing flat users
 
 `mid`, `pcs`, `adopted_devices`, `extension_properties` and the per-DER link-health fields exist only under the parent/child schema. They are `None` or empty on a flat panel rather than absent, so a consumer reads the same snapshot type either way.
 
+`uptime_s` and a circuit's update times are the reverse: only the flat parser measures them, and they are `None` under the parent/child schema. Neither schema publishes proximity, so `SpanPanelSnapshot.proximity_proven` is always `None`; the panel's own
+answer is `V2StatusInfo.proximity_proven`, from `GET /api/v2/status`.
+
 ## Usage
 
 ### Factory Pattern (Recommended)

{span_panel_api-3.6.1b1 → span_panel_api-3.7.0b1}/README.md

@@ -148,8 +148,8 @@ transport-specific classes.
 
 All panel state is represented as immutable, frozen dataclasses:
 
-- **`SpanPanelSnapshot`**: complete panel state. Identity (serial, firmware, vendor, model, hardware version), panel size, main breaker rating, main relay, door and proximity state, uptime, network links with the Wi-Fi SSID and vendor cloud, grid and
-  feedthrough power and energy, grid/DSM state, run configuration, dominant power source, grid islandability, per-leg voltages, power flows, lugs current and whether the lugs are the service entrance, shed policy and forecast. It holds `circuits`,
+- **`SpanPanelSnapshot`**: complete panel state. Identity (serial, firmware, vendor, model, hardware version), panel size, main breaker rating, main relay, door state, connection uptime on a flat panel, network links with the Wi-Fi SSID and vendor cloud,
+  grid and feedthrough power and energy, grid/DSM state, run configuration, dominant power source, grid islandability, per-leg voltages, power flows, lugs current and whether the lugs are the service entrance, shed policy and forecast. It holds `circuits`,
   `battery`, `pv`, `pv_inverters`, `evse`, `mid`, `pcs`, `adopted_devices` and `extension_properties`.
 - **`SpanCircuitSnapshot`**: one circuit. Id, name, relay state and requester, power, energy and their update times, tabs, 240 V, breaker rating, current, priority, user controllability, sheddable / never-backup / always-on flags, device type, relative
   position, PCS management and priority, and the `$target` pending state for relay and priority.
@@ -168,6 +168,9 @@ see the changelog, because `battery.model` changes value for existing flat users
 
 `mid`, `pcs`, `adopted_devices`, `extension_properties` and the per-DER link-health fields exist only under the parent/child schema. They are `None` or empty on a flat panel rather than absent, so a consumer reads the same snapshot type either way.
 
+`uptime_s` and a circuit's update times are the reverse: only the flat parser measures them, and they are `None` under the parent/child schema. Neither schema publishes proximity, so `SpanPanelSnapshot.proximity_proven` is always `None`; the panel's own
+answer is `V2StatusInfo.proximity_proven`, from `GET /api/v2/status`.
+
 ## Usage
 
 ### Factory Pattern (Recommended)

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

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.6.1b1"
+version = "3.7.0b1"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -62,9 +62,14 @@ dependencies = [
 # so a 1.1.x adapter is still accepted, but it fills neither `pv_inverters` nor
 # 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.3.0b1 for 3.7.0b1: that adapter reports the unknown values this
+# bootstrap's snapshot fields now accept, and stops synthesising unoccupied positions.
+schema-0 = ["span-panel-api-schema-0>=1.3.0b1"]
+# 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.
+# Raised to 1.3.0b1 for 3.7.0b1, for the same reason as schema-0's.
+schema-1 = ["span-panel-api-schema-1>=1.3.0b1"]
 
 [project.urls]
 Homepage = "https://github.com/SpanPanel/span-panel-api"
@@ -243,7 +248,11 @@ warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true
 explicit_package_bases = true
-mypy_path = "src"
+# `tests` because the suite imports its support packages top-level
+# (`from reference_payloads.schema_one import ...`), the way pytest's rootdir puts
+# `tests/` on `sys.path`; the support packages the mypy hook checks resolve the same
+# way here.
+mypy_path = "src:tests"
 # 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.

{span_panel_api-3.6.1b1 → span_panel_api-3.7.0b1}/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.7.0b1}/src/span_panel_api/auth.py

@@ -9,7 +9,7 @@ client (which only covers v1 endpoints).
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Collection
+from collections.abc import Collection, Mapping
 import hashlib
 import json
 import logging
@@ -454,6 +454,32 @@ async def download_ca_cert(
     raise SpanPanelAPIError(f"Failed to download CA cert: HTTP {last_status}")
 
 
+def _schema_hash(data: Mapping[str, object]) -> str:
+    """The schema hash ``V2HomieSchema.types_schema_hash`` reports.
+
+    A parent/child panel publishes its schema as ``deviceClasses``, with its own
+    ``deviceClassesSchemaHash`` over that block, in place of flat firmware's
+    ``types``. Hashing ``types`` there hashed an absent block, so every such
+    panel got one constant key. The published hash is taken as is when it is a
+    non-empty string; otherwise ``deviceClasses`` is hashed here.
+
+    SPAN's public API changelog states that ``deviceClassesSchemaHash`` is
+    computed over the new structure, so it differs from a ``typesSchemaHash``
+    even where the property content is unchanged, and that a cached
+    ``typesSchemaHash`` is not to be compared against it. A key held from a
+    release that hashed ``types`` therefore differs once on such a panel.
+
+    A flat panel's key is exactly what earlier releases computed, so a value
+    stored for a flat panel still matches.
+    """
+    published = data.get("deviceClassesSchemaHash")
+    if isinstance(published, str) and published:
+        return published
+    hashed = data["deviceClasses"] if "deviceClasses" in data else data.get("types", {})
+    canonical = json.dumps(hashed, sort_keys=True)
+    return "sha256:" + hashlib.sha256(canonical.encode()).hexdigest()[:16]
+
+
 async def get_homie_schema(
     host: str,
     timeout: float = 10.0,
@@ -527,15 +553,9 @@ async def get_homie_schema(
             if isinstance(props, dict):
                 types[str(type_name)] = {str(k): v for k, v in props.items()}
 
-    # Compute schema hash from types key names for change detection
-    # The panel provides this implicitly via the firmware version + types structure
-    # We derive a hash for caching; the fixture README documents the expected value
-    types_json = json.dumps(data.get("types", {}), sort_keys=True)
-    schema_hash = "sha256:" + hashlib.sha256(types_json.encode()).hexdigest()[:16]
-
     # Read before anything else interprets the payload. A parent/child response
-    # carries `deviceClasses` where this one reads `types`, so every field below
-    # degrades to empty for such a panel — which is harmless only because this
+    # carries `deviceClasses` where this one reads `types`, so `types` degrades
+    # to empty for such a panel — which is harmless only because this
     # value routes it to a different parser before those fields are used.
     # Absence is the flat signal and must stay distinct from an empty string.
     raw_data_model_version = data.get("dataModelVersion")
@@ -543,7 +563,7 @@ async def get_homie_schema(
 
     return V2HomieSchema(
         firmware_version=str(data.get("firmwareVersion", "")),
-        types_schema_hash=schema_hash,
+        types_schema_hash=_schema_hash(data),
         types=types,
         data_model_version=data_model_version,
     )

{span_panel_api-3.6.1b1 → span_panel_api-3.7.0b1}/src/span_panel_api/models.py

@@ -49,8 +49,12 @@ class SpanCircuitSnapshot:
     breaker_rating_a: float | None = None
     always_on: bool = False  # v2 new: circuit/always-on
     relay_requester: str = "UNKNOWN"  # v2 new: circuit/relay-requester
-    energy_accum_update_time_s: int = 0  # v1: poll timestamp | v2: MQTT arrival time
-    instant_power_update_time_s: int = 0  # v1: poll timestamp | v2: MQTT arrival time
+    # Epoch seconds at which the reading last changed, as received over MQTT.
+    # Flat only: the tree adapter records no such time, and a reading that has
+    # not arrived has no time either, so both are `None` rather than a `0` that
+    # reads as 1970.
+    energy_accum_update_time_s: int | None = None  # flat: MQTT receipt time
+    instant_power_update_time_s: int | None = None  # flat: MQTT receipt time
     relay_state_target: str | None = None  # v2: $target for relay (desired state)
     priority_target: str | None = None  # v2: $target for shed-priority (desired state)
 
@@ -210,8 +214,10 @@ class SpanMidSnapshot:
 
     The raw value above is a Homie device id, which means nothing on a dashboard — it is
     not a Home Assistant device id, and an opaque string is worse than none. This is the
-    device's own `$description.name` (`Battery`, `Solar`, `SPAN Drive - Garage`), which
-    is the part a person can read. The literal stays available beside it.
+    device's own `$description.name` (`Battery`, `Solar`, `SPAN Drive - Garage`) where
+    that is not the id itself, else its vendor and model (`Tesla Powerwall 2 AC`), which
+    is the part a person can read; `None` when it publishes nothing that names it. The
+    literal stays available beside it.
     """
 
 
@@ -616,6 +622,7 @@ class V2StatusInfo:
     serial_number: str
     firmware_version: str
     proximity_proven: bool | None = None  # Added in firmware 202609; None on older panels
+    hardware_version: str | None = None  # Added in firmware r202639: `1.2`, `2.0` or `UNKNOWN`; None on older panels
 
     @classmethod
     def from_status_payload(cls, payload: Mapping[str, object]) -> V2StatusInfo:
@@ -633,16 +640,21 @@ class V2StatusInfo:
         panel that may not fully support it, so a partial body is information,
         not a failure.
 
-        ``proximity_proven`` is the exception and stays ``None`` unless the panel
+        ``proximity_proven`` is an exception and stays ``None`` unless the panel
         published a real boolean. Absent and false are different facts there —
         firmware below 202609 does not report it at all — and coercing whatever
-        arrived would turn a string ``"false"`` into ``True``.
+        arrived would turn a string ``"false"`` into ``True``. ``hardware_version``
+        is likewise ``None`` unless the panel published a real string: firmware
+        below r202639 omits it, and a stringified number or object would read as
+        a version the panel never reported.
         """
         raw_proximity = payload.get("proximityProven")
+        raw_hardware_version = payload.get("hardwareVersion")
         return cls(
             serial_number=str(payload.get("serialNumber", "")),
             firmware_version=str(payload.get("firmwareVersion", "")),
             proximity_proven=raw_proximity if isinstance(raw_proximity, bool) else None,
+            hardware_version=raw_hardware_version if isinstance(raw_hardware_version, str) else None,
         )
 
 
@@ -654,7 +666,10 @@ class V2HomieSchema:
     """Response from GET /api/v2/homie/schema."""
 
     firmware_version: str
-    types_schema_hash: str  # SHA-256, first 16 hex chars
+    # SHA-256, first 16 hex chars, compared by the client between connects: over
+    # ``types`` on a flat panel, and over ``deviceClasses`` on parent/child, where
+    # the panel's own ``deviceClassesSchemaHash`` is used when it publishes one.
+    types_schema_hash: str
     types: HomieSchemaTypes
     # The flat-vs-parent/child discriminator, and the reason this endpoint is
     # fetched before MQTT is opened rather than during connect(). Absent on flat
@@ -1072,8 +1087,16 @@ class SpanPanelSnapshot:
 
     # Hardware status — v1 field names preserved
     door_state: str  # v1: direct | v2: core/door
-    proximity_proven: bool  # v1: proximity sensor | v2: MQTT auth + $state==ready
-    uptime_s: int  # v1: panel uptime | v2: connection uptime since $state==ready
+    # Neither MQTT schema publishes a proximity property, so a snapshot never
+    # knows: always `None`. Being connected and ready proves the client holds
+    # broker credentials, not that anyone stood at the panel. The panel's own
+    # answer is `V2StatusInfo.proximity_proven`, from the REST status endpoint.
+    proximity_proven: bool | None
+    # Seconds since this client last saw the panel's `$state` turn `ready`: a
+    # connection uptime measured here, not the panel's own uptime, which no
+    # schema publishes. Flat only; `None` from the tree adapter, and before the
+    # first `ready`.
+    uptime_s: int | None
     eth0_link: bool  # v1: direct | v2: core/ethernet
     wlan_link: bool  # v1: direct | v2: core/wifi
     wwan_link: bool  # v1: direct | v2: vendor-cloud == "CONNECTED"

{span_panel_api-3.6.1b1 → span_panel_api-3.7.0b1}/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.7.0b1}/src/span_panel_api/mqtt/connection.py

@@ -846,8 +846,7 @@ class AsyncMqttBridge:
         retrying with it.
 
         Recovery target: CA rotation (firmware upgrade), stale paho client
-        internal state, stuck Homie accumulator. See the design doc at
-        SpanPanel_Docs/span-panel-api/2026-05-17-mqtt-ca-refresh-on-reconnect-design.md.
+        internal state, stuck Homie accumulator.
         """
         if self._loop is None:
             return False

span_panel_api-3.7.0b1/tests/adapter_fidelity/__init__.py

@@ -0,0 +1,5 @@
+"""Adapter fidelity: captured device trees replayed through the schema-1 adapter.
+
+`harness` measures one capture and names no panel, model or capture; `rules`
+documents why each measured outcome is right; the test modules pick captures.
+"""