span-panel-api 3.0.0b3__tar.gz → 3.0.0b7__tar.gz

{span_panel_api-3.0.0b3 → span_panel_api-3.0.0b7}/.gitignore

@@ -40,3 +40,8 @@ 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.0.0b3 → span_panel_api-3.0.0b7}/CHANGELOG.md

@@ -4,6 +4,127 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0b7]
+
+### Changed
+
+- **`SpanMqttClient` accepts an `httpx_client`, and so does `create_span_client`.** Four config-flow-facing entry points already took an injected client; the runtime path was the one that did not, so every schema read built a throwaway — including the
+  retry loop that runs during a firmware upgrade, which built one per attempt at exactly the moment the panel was mid-reboot. Optional and defaulted, so nothing outside Home Assistant changes. The ownership rule is the one the existing entry points already
+  state: a client handed in is never closed here, and its timeouts, limits and headers are the caller's, which is why the per-call `timeout` defaults are ignored when one is given. Home Assistant's shared client carries httpx's default timeout rather than
+  this library's 10 s, and that is the caller exercising the policy it owns rather than a setting being lost.
+
+## [3.0.0b6]
+
+### Added
+
+- **`SpanPanelSnapshot.lugs_at_service_entrance`, saying whether this enclosure's upstream lugs are the utility connection point.** `instant_grid_power_w` is those lugs' `meter/active-power`, and the name holds only at the service entrance: a BESS wired
+  ahead of the main lugs, or an enclosure fed by another enclosure, leaves the lugs metering panel-side flow while the utility side differs by whatever that device contributes or absorbs. `power_flow_grid` stays site-level and correct in both, so the two
+  legitimately disagree — and before this a consumer seeing them disagree could not tell a topology from a fault. Sourced from the lugs' `connection/fed-by-device-id`, which `power-flows` 0.3 names as the detection mechanism when it qualifies its own
+  negation table; this library already read that property and then discarded it, so no consumer could compute this for itself. Defaults `True` because flat firmware predates chaining and a flat panel's lugs really are its service entrance, so schema_0
+  leaves it alone. Additive, so it costs no protocol member and no contract bump. Worth knowing: the reference capture publishes `fed-by-device-id: bess` on its upstream lugs, so the reference panel reports `False`.
+
+- **An adopted device carries the proxy link it declares: `AdoptedDevice.parent` and `AdoptedDevice.proxied`.** Carried rather than acted on — an adopted device is still registered under the enclosure — because a _proxied_ unmodelled device is a real shape
+  that would otherwise be flattened away unrecorded. The reference tree already contains one: `bess-mid` declares `parent: bess`, the `{proxier-id}-{proxied-id}` naming of `devices/proxy.md`. `proxied` is derived against the tree `root` in the adapter,
+  because device ids are opaque and a consumer holding one device cannot tell the enclosure's id from a sibling's.
+- **The nesting is deliberately not built yet.** [python-sdk#49](https://github.com/electrification-bus/python-sdk/issues/49#issuecomment-5359203067) records that proxied ids differ by design and that consumers correlate by `info/serial-number` rather than
+  by device id, and `ebus-sdk` 0.21.0 shipped `DeviceSpec`/`DeviceTreeBuilder` ([python-sdk#57](https://github.com/electrification-bus/python-sdk/issues/57)) with the graph builder still to be reconciled against it. The tree model is being reshaped
+  upstream, so the fields capture the evidence and the topology waits.
+
+- **A settable property on an adopted device can be written, and the write cannot reach anything else: `AdoptedProperty.set_topic` and `SpanMqttClient.set_adopted_property`.** The topic is populated only for a settable property on a device `is_modelled`
+  rejects, so it is the scoping that authorises the write rather than a check a caller has to remember. The transport resolves the property against the current snapshot's `adopted_devices` and publishes to the topic that property carries; no topic is
+  accepted from the caller, and a device this library models produces no `AdoptedDevice` to find.
+- **The alternative was a `set_property_topic` member on `SchemaAdapter`, and it was rejected for two independent reasons.** It would have put every curated control one argument away, and two of them do real work on the way out —
+  `dominant_power_source_payload` translates `GRID` into the `ON_GRID` the v1.0 islanding assertion accepts, and `evse_charge_limit_payload` refuses a value above the commissioned ceiling because publishing past it is the one write with a physical
+  consequence. It would also have been required of every adapter package, since `_derive_required_members` derives the required set from the protocol, so an installation carrying an older adapter wheel would have failed at _discovery_ rather than losing
+  one feature.
+- **No translation and no bounds check on an adopted write, deliberately.** Both exist on curated controls because this library knows what those properties mean. It knows nothing about an adopted one beyond its declaration, and inventing a bound would be
+  inventing a fact about somebody else's hardware. The consumer constrains the value to the declared `format`; the panel stays the authority on whether to accept it.
+- **`AdoptedControlProtocol`**, so a consumer asks `isinstance` before offering the control, exactly as it does for circuit, panel and EVSE control.
+
+- **A device type this adapter models nothing for is reported whole rather than ignored: `SpanPanelSnapshot.adopted_devices`.** `TreeRoles` sorts the tree into the roles the snapshot needs, and anything that matches none of them has always fallen off the
+  end silently — a panel publishing a device nobody modelled produced no field, no metadata row and no sign it was there. The schema is explicitly vendor-extensible, so that is an expected arrival rather than a hypothetical one. `AdoptedDevice` carries the
+  device's identity and its readings; `span_panel_api_schema_1.adoption` builds one per unmodelled child.
+- **The unit is a device, never a property, and that is the whole design.** A new property on a device this adapter already models is a curation task with a short turnaround, and surfacing it automatically spends a consumer's entity identity permanently on
+  a shape a human would likely have chosen differently — the sixteen `pcs` properties that curation collapsed into one entity and thirteen attributes are the worked example. An unmodelled _type_ is the opposite case: no curation is coming, so the silence
+  is the only alternative. Extra instances of a modelled type are deliberately not adopted either: a second BESS is a multiplicity limit, not an unmodelled device, and adopting it would stand a machine-named record beside a curated one for the same
+  hardware.
+- **`info` and `connection` resolve away from readings, by node rather than by property name.** `info` is a device's build identity and becomes the card fields `AdoptedDevice` carries; `connection` is topology and becomes the device link. The partition is
+  keyed on the node because the catalogs carry no marker for "this string is a device reference", which leaves a hard-coded name list as the only alternative — and such a list goes stale silently: `ebus-sdk`'s own `topology.py` covers `feeds-device-id` and
+  `fed-by-device-id` and omits `grid-forming-entity`, which lives on the `grid` capability. A node is what the vocabulary defines, so keying on it cannot go stale the same way.
+- **`AdoptedProperty` carries the value; `DiscoveredMetadata` still must not.** The two answer opposite questions and are separate types so that conflating them is a type error. Discovery rows are built to be forwarded in consumer diagnostics, which leave
+  the machine, so they carry declarations only. An adopted property exists to become an entity on the machine that built it, so it carries the reading — along with the declared `format` and `settable` flag, which are together the value domain a consumer
+  needs to build a control rather than a reading.
+- **Additive, and deliberately not a protocol member.** `adopted_devices` defaults to `()`, so schema_0 — which has no device tree to find an unmodelled device in — is untouched, and `ADAPTER_CONTRACT_VERSION` does not move. `SchemaAdapter` derives its
+  required members from itself, so a member there would be required of every adapter package and would invalidate built wheels.
+
+- **The capability catalogs are used as a validator, not just as a vocabulary list: `span_panel_api_schema_1.catalog`.** Sixteen catalogs have been vendored since v1.0 landed and were read only to assert that a catalog _exists_ for every node the adapter
+  addresses. Nothing compared a declared `unit` or `datatype` against the catalog's definition of the same property, which is the comparison that catches a mislabel — and the one mislabel this repository has met (`meter/active-power` declared `kW` while
+  the values are watts, a 1000x error) was found because a person noticed a sibling device declaring the same quantity differently. The new module compares one declaration against one catalog definition and classifies the result;
+  `tests/test_catalog_divergence.py` runs it across all four vendored producer captures and holds the outcome against an acknowledged-divergence register.
+- **Agreement is silence; disagreement is surfaced, never silently resolved.** A finding is not a licence to change a wire reader to match the catalog, nor to assume the catalog is right — both sides have been wrong. It is recorded in `_REGISTER` with what
+  the wire says, what the catalog says, which producers show it, a reason and a date, and the baseline fails in both directions: a new divergence fails until somebody records it, and a recorded divergence that has **disappeared** fails until its line is
+  removed. That second direction is what keeps the register self-cleaning rather than a suppression list.
+- **An abstract unit is a dimension, and comparing it as a string would report conformance as the defect.** `soc/soe`, `soc/total-energy-storage`, `soc/loadup-headroom` and `info/nameplate-capacity` are all `unit: "energy"`, which the specification
+  requires a publisher to substitute a real unit for — a BESS in kWh, a water heater in Wh. `UNIT_FAMILIES` enumerates membership rather than deriving it from an SI-prefix rule, so a member is silent, echoing the placeholder back is a finding, and an
+  energy unit nobody enumerated is a question for a human. A catalog unit token that is neither a known family nor a known concrete unit fails until it is classified, so a new abstract family upstream cannot arrive as sixty false findings.
+- **An absence is terminal and is reported once.** A property no catalog defines — the EVSE's `config` node, which is not an eBus capability at all, and the `status`/`meter`/`info` extensions SPAN publishes — has no definition to disagree with, so it is
+  reported as absent rather than as every field mismatching against nothing. That keeps `_SPAN_EXTENSIONS` the single home for the read-set half of that question instead of duplicating its judgements here.
+- **The flat schema document is surveyed too, and it is where the known mislabel lives.** It declares properties per device type with no capability node to look a catalog up by, so its properties reach the catalogued vocabulary through the snapshot field
+  path both adapters' metadata tables already name — derived from those tables rather than restated, so the join cannot outlive them. The join is admitted only where the two sides spell the property identically: fifteen flat properties reach a catalogued
+  property under a different name (`dipole` for `breaker/poles`, `software-version` for `info/firmware-version`), and comparing across a rename would invent divergences out of the pre-catalog spelling that having two adapters already handles.
+
+- **Per-DER connection health reaches the snapshot: `SpanEvseSnapshot.connected` and `SpanPVSnapshot.connected`.** `battery.connected` has carried the enclosure's view of the link to the BESS since v1.0 landed, from the upstream lugs'
+  `connection/fed-by-device-status`. The other half of the same capability — a circuit's `connection/feeds-device-status`, which is how the enclosure reports the link to a PV or a charger — reached nothing, so only one of a panel's three DER classes had a
+  link-health field. Both new fields are `bool | None` and mirror `battery.connected` exactly, read by `build_pv` and `build_evse` through the new `feed_connection_statuses`.
+- **`None` is the specification's "unknown", and it is load-bearing.** The enum is `OK,LOST,DEGRADED` with no `UNKNOWN` member, so an unpublished property is the only way a panel can say it does not know — and `distribution-enclosure.md` states that a
+  mixed-load or unsurveyed circuit publishes no connection record at all, which is the normal state for most of a panel's circuits. So absence is never a fault: a DER no circuit claims, or one whose circuit publishes an id without a status, reports `None`
+  rather than `False`. `DEGRADED` collapses to `False`, because the question this field answers is whether the enclosure can talk to the device.
+- **The charger's link is not the charger's session.** `evse.status` is the OCPP-style state the charger reports about the cable in front of it; `evse.connected` is the enclosure reporting whether it can reach the charger at all. A charger mid-session over
+  a lost link publishes `CHARGING` and `connected=False` at once, and the two fields stay separate for the same reason `battery.connected` and `battery.communication_state` do.
+- **`_PROPERTY_FIELD_MAP` rows for both**, from `(circuit, connection, feeds-device-status)` — the one place a row's device type and its field path deliberately differ, because v1.0 states the relationship on the circuit and the field belongs to the DER.
+  One property carries two rows, since one circuit's record describes a PV and another's a charger. Both buy the datatype the circuit's own `$description` declares plus the three-way resolution contract.
+
+- **The BESS's own meter and link health reach the snapshot: `SpanBatterySnapshot.power_w` and `SpanBatterySnapshot.communication_state`.** The battery device has published `meter/active-power` and `status/communication-state` all along and neither reached
+  a field, so a consumer could show the enclosure's arbitrated `power_flow_battery` and nothing the BESS itself reports. Both are `None` on a BESS that publishes no such node, and on every flat panel — the flat schema's BESS device class declares neither
+  property, so this is new surface rather than a re-sourcing, and nothing that exists today changes.
+- **`power_w` is discharge-positive, and the wire is not.** The enclosure meters the BESS the way it meters a circuit it feeds, so a _discharging_ battery publishes a negative `meter/active-power`; `build_battery` negates it, exactly as `build_circuit`
+  does for a load. Positive therefore means power flowing _out of_ the battery. This entry said charge-positive until the direction was settled by measurement rather than by reading: with the producer driven into self-consumption and the grid at exactly
+  zero — PV 4181 W plus battery 1917 W meeting a 6099 W load, so the battery can only be discharging — the snapshot reported `+1917.49`. `_charge_positive` was renamed `_discharge_positive` in the same pass. No published value changed; the negation was
+  always there and always right, and only the name and this note asserted a direction the code did not hold.
+- The asymmetry with `panel.power_flow_battery` is real and unchanged: the enclosure's own arbitrated figure is passed through untouched by both adapters and is charge-positive, so it reads negative for the same discharging battery that makes `power_w`
+  positive. The two describe the same physical power in opposite frames, and a consumer rendering both negates one of them — which is what the Home Assistant integration does, landing both of its entities on discharge-positive.
+- **`communication_state` stays the published enum string** (`OK`/`DEGRADED`/`LOST`/`UNKNOWN`) rather than collapsing to a bool: `DEGRADED` is neither `OK` nor `LOST`, and a bool would have to pick one. It is deliberately not merged into
+  `battery.connected`, which is the _enclosure's_ `connection/fed-by-device-status` view of the same link. One is the device speaking about itself and the other the panel speaking about it, and the migration guide warns against conflating them.
+- **`_PROPERTY_FIELD_MAP` rows for both**, which buys them the unit and datatype the BESS's own `$description` declares plus the three-way resolution contract — a BESS that publishes the node while omitting the property reports degradation rather than
+  absent hardware. The row describes the property; the sign flip the mapper applies is not a unit change.
+
+- **`shed-forecast` reaches the snapshot: five new `SpanPanelSnapshot` fields.** `shed_time_to_priority_shed_min`, `shed_total_time_remaining_min`, `shed_full_charge_time_to_priority_shed_min`, `shed_full_charge_total_time_remaining_min` and
+  `shed_forecast_confidence`. The enclosure has published `energy.ebus.capability.shed-forecast` 0.1 since r202633 and nothing read it — the backup-planning numbers ("how long before my battery starts shedding circuits", "how long before it is exhausted")
+  were on the wire and stopped at the transport. All four times are `integer` minutes as the capability declares, parsed through `panel.integer` so a publisher that serialises a whole number with a decimal point still resolves; `confidence` stays the raw
+  `LOW`/`MEDIUM`/`HIGH` string, because it qualifies the four times rather than standing alone. Every field is `None` when the panel publishes no such node, and `None` is load-bearing: zero minutes is a legitimate reading — shedding starts now — so a
+  defaulted zero would be indistinguishable from the worst forecast the capability can report. Purely additive; a panel that publishes nothing here is unchanged.
+- **`_PROPERTY_FIELD_MAP` rows for the two live estimates**, `panel.shed_time_to_priority_shed_min` and `panel.shed_total_time_remaining_min`. That buys them the unit and datatype the device's own `$description` declares, and with it the three-way
+  resolution contract: a panel that publishes the node while omitting one of the two reports degradation rather than absent hardware. The `full-charge-*` pair and `confidence` deliberately get no row — a consumer renders them beside the two live estimates
+  rather than as readings of their own, so there is no unit surface for a row to describe.
+- **`shed-forecast` 0.1 vendored under `packages/schema-1/spec/catalogs/`** and pinned in `spec_lock.json`, byte-copied from the specification at the recorded `synced_commit`. The conformance suite requires a catalog for every capability node the adapter
+  addresses, so a node read without one would be unchecked while looking checked.
+
+## [3.0.0b5] - 08/2026
+
+Pre-release. Publishes the captured schema document consumers were copying by hand.
+
+### Added
+
+- **`span_panel_api.reference_payloads`, shipping `homie_schema.json` as package data.** The captured `GET /api/v2/homie/schema` response moves out of `tests/fixtures/v2/` and into the wheel, reached by `homie_schema()` and `homie_schema_types()` rather
+  than by path. It was already being consumed outside this repository: the Home Assistant integration checks the field paths it declares against what an adapter can actually produce, which needs a real schema document, so it vendored a byte copy with a
+  README explaining where the copy came from. A copy has no version — it goes stale in silence, and a stale one turns the integration's conformance gate into a check against a schema no panel runs. Shipped, the payload carries the version of the release it
+  came with: pin `span-panel-api==3.0.0b5` and you read the bytes that release was written against, with nothing left to keep in sync. `homie_schema_types()` returns `HomieSchemaTypes` — precisely what
+  `span_panel_api_schema_0.field_metadata.build_field_metadata` accepts — so a caller building metadata never reaches into an untyped document to get it. This distribution owns the schema document rather than an adapter one because it is the response of
+  `get_homie_schema()` here, modelled by `V2HomieSchema` here, and dispatch reads its `data_model_version` to decide which adapter parses the panel at all. The parent/child device tree is the other half and ships from `span-panel-api-schema-1`, with the
+  parser that can interpret it.
+- **This suite reads the payload through the same accessor.** `test_schema_provenance.py` and `test_detection_auth.py` no longer open a path, so the schema anchor is checked against the bytes a consumer installs rather than against a file that exists only
+  in a checkout.
+
 ## [3.0.0b3] - 08/2026
 
 Pre-release. Normalises DER identity onto v1.0's vocabulary, and stops deriving the grid answers that v1.0 states outright.

span_panel_api-3.0.0b3/README.md → span_panel_api-3.0.0b7/PKG-INFO

@@ -1,3 +1,22 @@
+Metadata-Version: 2.5
+Name: span-panel-api
+Version: 3.0.0b7
+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
+Author: SpanPanel
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: <4.0,>=3.10
+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.0.0b5; extra == 'schema-0'
+Provides-Extra: schema-1
+Requires-Dist: span-panel-api-schema-1>=0.1.0b6; extra == 'schema-1'
+Description-Content-Type: text/markdown
+
 # SPAN Panel API
 
 [![GitHub Release](https://img.shields.io/github/v/release/SpanPanel/span-panel-api?style=flat-square)](https://github.com/SpanPanel/span-panel-api/releases)
@@ -120,7 +139,15 @@ async def main():
 
         # Get a point-in-time snapshot
         snapshot = await client.get_snapshot()
-        print(f"Grid power: {snapshot.instant_grid_power_w}W")
+        # The upstream lugs' own meter. That is grid flow only where the lugs are
+        # the utility connection point; a BESS wired ahead of them, or a panel fed
+        # by another panel, makes it this panel's feed instead. `power_flow_grid`
+        # is the site-level figure in every topology.
+        if snapshot.lugs_at_service_entrance:
+            print(f"Grid power: {snapshot.instant_grid_power_w}W")
+        else:
+            print(f"Panel feed: {snapshot.instant_grid_power_w}W")
+            print(f"Grid power: {snapshot.power_flow_grid}W")
         print(f"Firmware: {snapshot.firmware_version}")
         print(f"Circuits: {len(snapshot.circuits)}")
 
@@ -377,6 +404,29 @@ The `PanelCapability` flag enum advertises transport features at runtime:
 | `CIRCUIT_CONTROL` | Can set relay state and shed priority |
 | `BATTERY_SOE`     | Battery state-of-energy available     |
 
+## Reference Payloads
+
+Captures of what a panel actually serves, shipped as package data so a consumer can check its own assumptions against real bytes without vendoring a copy that silently goes stale:
+
+```python
+from span_panel_api.reference_payloads import homie_schema, homie_schema_types
+
+document = homie_schema()        # the captured GET /api/v2/homie/schema response
+types = homie_schema_types()     # its `types` map, typed as HomieSchemaTypes
+```
+
+`homie_schema_types()` returns exactly what `span_panel_api_schema_0.field_metadata.build_field_metadata` accepts, so building real adapter metadata to compare against is two lines and no file handling.
+
+The parent/child device tree is the schema_1 counterpart and ships from that adapter, with the parser that can interpret it:
+
+```python
+from span_panel_api_schema_1.reference_payloads import devices_from_tree, parent_child_tree
+
+devices = devices_from_tree(parent_child_tree())
+```
+
+Each payload carries the version of the release it shipped in. Pin a version and you read the bytes that version was written against.
+
 ## Project Structure
 
 ```text
@@ -390,6 +440,7 @@ src/span_panel_api/
 ├── models.py            # Snapshot dataclasses (panel, circuit, battery, PV)
 ├── phase_validation.py  # Electrical phase utilities
 ├── protocol.py          # PEP 544 protocols + PanelCapability flags
+├── reference_payloads/  # Captured wire payloads shipped as package data
 └── mqtt/
     ├── __init__.py
     ├── accumulator.py   # HomiePropertyAccumulator (Homie v5 protocol layer)

span_panel_api-3.0.0b3/PKG-INFO → span_panel_api-3.0.0b7/README.md

@@ -1,18 +1,3 @@
-Metadata-Version: 2.5
-Name: span-panel-api
-Version: 3.0.0b3
-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
-Author: SpanPanel
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: <4.0,>=3.10
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: paho-mqtt<3.0.0,>=2.0.0
-Requires-Dist: pyyaml>=6.0.0
-Description-Content-Type: text/markdown
-
 # SPAN Panel API
 
 [![GitHub Release](https://img.shields.io/github/v/release/SpanPanel/span-panel-api?style=flat-square)](https://github.com/SpanPanel/span-panel-api/releases)
@@ -135,7 +120,15 @@ async def main():
 
         # Get a point-in-time snapshot
         snapshot = await client.get_snapshot()
-        print(f"Grid power: {snapshot.instant_grid_power_w}W")
+        # The upstream lugs' own meter. That is grid flow only where the lugs are
+        # the utility connection point; a BESS wired ahead of them, or a panel fed
+        # by another panel, makes it this panel's feed instead. `power_flow_grid`
+        # is the site-level figure in every topology.
+        if snapshot.lugs_at_service_entrance:
+            print(f"Grid power: {snapshot.instant_grid_power_w}W")
+        else:
+            print(f"Panel feed: {snapshot.instant_grid_power_w}W")
+            print(f"Grid power: {snapshot.power_flow_grid}W")
         print(f"Firmware: {snapshot.firmware_version}")
         print(f"Circuits: {len(snapshot.circuits)}")
 
@@ -392,6 +385,29 @@ The `PanelCapability` flag enum advertises transport features at runtime:
 | `CIRCUIT_CONTROL` | Can set relay state and shed priority |
 | `BATTERY_SOE`     | Battery state-of-energy available     |
 
+## Reference Payloads
+
+Captures of what a panel actually serves, shipped as package data so a consumer can check its own assumptions against real bytes without vendoring a copy that silently goes stale:
+
+```python
+from span_panel_api.reference_payloads import homie_schema, homie_schema_types
+
+document = homie_schema()        # the captured GET /api/v2/homie/schema response
+types = homie_schema_types()     # its `types` map, typed as HomieSchemaTypes
+```
+
+`homie_schema_types()` returns exactly what `span_panel_api_schema_0.field_metadata.build_field_metadata` accepts, so building real adapter metadata to compare against is two lines and no file handling.
+
+The parent/child device tree is the schema_1 counterpart and ships from that adapter, with the parser that can interpret it:
+
+```python
+from span_panel_api_schema_1.reference_payloads import devices_from_tree, parent_child_tree
+
+devices = devices_from_tree(parent_child_tree())
+```
+
+Each payload carries the version of the release it shipped in. Pin a version and you read the bytes that version was written against.
+
 ## Project Structure
 
 ```text
@@ -405,6 +421,7 @@ src/span_panel_api/
 ├── models.py            # Snapshot dataclasses (panel, circuit, battery, PV)
 ├── phase_validation.py  # Electrical phase utilities
 ├── protocol.py          # PEP 544 protocols + PanelCapability flags
+├── reference_payloads/  # Captured wire payloads shipped as package data
 └── mqtt/
     ├── __init__.py
     ├── accumulator.py   # HomiePropertyAccumulator (Homie v5 protocol layer)

{span_panel_api-3.0.0b3 → span_panel_api-3.0.0b7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.0.0b3"
+version = "3.0.0b7"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -10,18 +10,34 @@ license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.10,<4.0"
 dependencies = [
-    "httpx>=0.28.1",
+    # Bounded, and the bound is load-bearing. httpx 1.0 is an API rewrite that
+    # removes `AsyncClient` -- 1.0.dev1..dev4 are on PyPI now, and every
+    # distribution of this library is a prerelease, so `pip install --pre`, the
+    # verb RELEASE.md itself prescribes, resolves them. `paho-mqtt` has been
+    # bounded from the start; this was the one unbounded runtime dependency, and
+    # a ceiling cannot be added to a version already published.
+    "httpx>=0.28.1,<1.0",
     "paho-mqtt>=2.0.0,<3.0.0",
     "pyyaml>=6.0.0",
 ]
 
+[project.optional-dependencies]
+# Not runtime dependencies: this distribution still registers no adapter and
+# imports none, and `scripts/verify_adapterless_install.py` holds that line.
+# These exist so `pip install -U --pre "span-panel-api[schema-0,schema-1]"` has a
+# correct upgrade path, because the dependency arrow runs the other way -- an
+# adapter floors on the bootstrap, the bootstrap requires no adapter -- so
+# upgrading the bootstrap alone leaves stale adapter wheels that
+# `_derive_required_members` then rejects at discovery, with pip reporting
+# success. An extra is the only thing pip can act on, and extras cannot be added
+# to a version after it is published.
+schema-0 = ["span-panel-api-schema-0>=1.0.0b5"]
+schema-1 = ["span-panel-api-schema-1>=0.1.0b6"]
+
 [project.urls]
 Homepage = "https://github.com/SpanPanel/span-panel-api"
 Issues = "https://github.com/SpanPanel/span-panel-api/issues"
 
-[project.scripts]
-format-markdown = "scripts.format_markdown:main"
-
 # No [project.entry-points."span_panel_api.schema_adapters"] block here, and that
 # absence is the point of Phase 1: this distribution registers no adapter and
 # imports none. Adapters are separate distributions that register themselves —
@@ -72,7 +88,29 @@ span-panel-api-schema-0 = { workspace = true }
 span-panel-api-schema-1 = { workspace = true }
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/span_panel_api", "scripts"]
+# `scripts/` is deliberately absent. Shipping it put `scripts/__init__.py` at the
+# top level of every consumer's site-packages, so an unrelated `import scripts`
+# in a Home Assistant venv resolved to this distribution, and it installed a
+# markdown formatter as a console script for every user. It is a dev tool;
+# `scripts/format.sh` runs it by path.
+packages = ["src/span_panel_api"]
+
+[tool.hatch.build.targets.sdist]
+# Explicit, because the default swept the whole tree: the root sdist contained
+# packages/schema-0 and packages/schema-1 in full, contradicting the one
+# invariant this distribution is built around -- that it registers no adapter and
+# imports none. Anyone auditing the bootstrap sdist found both parsers inside it.
+# Anchored with a leading slash: an unanchored "README.md" is a glob that matches
+# at any depth, which pulled each adapter's own README, CHANGELOG and pyproject
+# back in and left the bootstrap sdist still naming both parsers.
+include = [
+    "/src/span_panel_api",
+    "/tests",
+    "/README.md",
+    "/CHANGELOG.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]
 
 [tool.ruff]
 line-length = 125

{span_panel_api-3.0.0b3 → span_panel_api-3.0.0b7}/src/span_panel_api/__init__.py

@@ -31,6 +31,12 @@ from .exceptions import (
 )
 from .factory import create_span_client
 from .models import (
+    ADOPTION_IDENTITY_NODE,
+    ADOPTION_TOPOLOGY_NODE,
+    DISCOVERY_NAMESPACE,
+    AdoptedDevice,
+    AdoptedProperty,
+    DiscoveredMetadata,
     FieldMetadata,
     HomieSchemaTypes,
     SpanBatterySnapshot,
@@ -38,10 +44,12 @@ from .models import (
     SpanEvseSnapshot,
     SpanMidSnapshot,
     SpanPanelSnapshot,
+    SpanPcsSnapshot,
     SpanPVSnapshot,
     V2AuthResponse,
     V2HomieSchema,
     V2StatusInfo,
+    is_discovery_path,
 )
 from .mqtt import MqttClientConfig, SpanMqttClient
 from .phase_validation import (
@@ -53,7 +61,9 @@ from .phase_validation import (
     validate_solar_tabs,
 )
 from .protocol import (
+    AdoptedControlProtocol,
     CircuitControlProtocol,
+    EvseControlProtocol,
     PanelCapability,
     PanelControlProtocol,
     SpanPanelClientProtocol,
@@ -65,6 +75,17 @@ __version__ = _pkg_version("span-panel-api")
 __all__ = [  # noqa: RUF022
     # Protocols
     "CircuitControlProtocol",
+    # Added 2026-08-19: the charge-current ceiling on a commissioned EV charger,
+    # the first settable property outside the panel and its circuits. Purely
+    # additive -- a consumer that never asks for it is unaffected, and flat
+    # firmware publishes no such property, so the flat adapter answers None and
+    # the transport refuses.
+    "EvseControlProtocol",
+    # Added 2026-08-20 with device-scoped adoption: the first control whose
+    # subject this library does not understand. Additive, and authorised by the
+    # snapshot rather than by its arguments -- a device the adapter models
+    # produces no AdoptedDevice and so cannot be addressed through it.
+    "AdoptedControlProtocol",
     "PanelCapability",
     "PanelControlProtocol",
     "SpanPanelClientProtocol",
@@ -72,6 +93,20 @@ __all__ = [  # noqa: RUF022
     # Metadata
     "FieldMetadata",
     "HomieSchemaTypes",
+    # Added 2026-08-20: runtime discovery. Purely additive -- an adapter that
+    # emits no discovered rows is indistinguishable from one built before the
+    # namespace existed, and a consumer that never partitions on the namespace
+    # sees exactly the curated rows it saw before.
+    "DISCOVERY_NAMESPACE",
+    "DiscoveredMetadata",
+    "is_discovery_path",
+    # Added 2026-08-20: device-scoped adoption. Additive in the same way --
+    # `SpanPanelSnapshot.adopted_devices` defaults empty, so an adapter that
+    # adopts nothing and a consumer that reads the field are both unaffected.
+    "ADOPTION_IDENTITY_NODE",
+    "ADOPTION_TOPOLOGY_NODE",
+    "AdoptedDevice",
+    "AdoptedProperty",
     # Snapshots
     "SpanBatterySnapshot",
     "SpanCircuitSnapshot",
@@ -79,6 +114,7 @@ __all__ = [  # noqa: RUF022
     "SpanMidSnapshot",
     "SpanPVSnapshot",
     "SpanPanelSnapshot",
+    "SpanPcsSnapshot",
     # Factory
     "create_span_client",
     # Detection

{span_panel_api-3.0.0b3 → span_panel_api-3.0.0b7}/src/span_panel_api/factory.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+from typing import TYPE_CHECKING
 
 from .adapters import resolve_adapter
 from .auth import get_homie_schema, register_v2
@@ -17,6 +18,9 @@ from .exceptions import SpanPanelAuthError
 from .mqtt.client import SpanMqttClient
 from .mqtt.models import MqttClientConfig
 
+if TYPE_CHECKING:
+    import httpx
+
 _LOGGER = logging.getLogger(__name__)
 
 _V2_CLIENT_NAME = "span-panel-api"
@@ -28,6 +32,7 @@ async def create_span_client(
     mqtt_config: MqttClientConfig | None = None,
     serial_number: str | None = None,
     port: int = 80,
+    httpx_client: httpx.AsyncClient | None = None,
 ) -> SpanMqttClient:
     """Create a SPAN Panel MQTT client.
 
@@ -37,6 +42,10 @@ async def create_span_client(
         mqtt_config: Pre-built MQTT broker configuration.
         serial_number: Panel serial number (extracted from detection/registration if omitted).
         port: HTTP port of the panel bootstrap API used for registration and detection.
+        httpx_client: Optional shared ``httpx.AsyncClient``, used for every request this
+            makes and handed to the client it builds. Not closed here; its timeouts and
+            limits are the caller's, which is why the per-call ``timeout`` defaults are
+            ignored when one is given.
 
     Returns:
         A connected-ready SpanMqttClient instance.
@@ -54,7 +63,7 @@ async def create_span_client(
     if mqtt_config is None:
         if passphrase is None:
             raise SpanPanelAuthError("Neither mqtt_config nor passphrase provided")
-        auth_response = await register_v2(host, _V2_CLIENT_NAME, passphrase, port=port)
+        auth_response = await register_v2(host, _V2_CLIENT_NAME, passphrase, port=port, httpx_client=httpx_client)
         mqtt_config = MqttClientConfig(
             broker_host=auth_response.ebus_broker_host,
             username=auth_response.ebus_broker_username,
@@ -68,7 +77,7 @@ async def create_span_client(
 
     if serial_number is None:
         # Try to detect from panel status
-        result = await detect_api_version(host, port=port)
+        result = await detect_api_version(host, port=port, httpx_client=httpx_client)
         if result.status_info is not None:
             serial_number = result.status_info.serial_number
 
@@ -80,7 +89,7 @@ async def create_span_client(
     # flat-versus-parent/child signal, mirroring MQTT's `info/data-model-version`
     # — so the parser is chosen before a single message is consumed, rather than
     # a wrong parser being discovered by its output.
-    schema = await get_homie_schema(host, port=port)
+    schema = await get_homie_schema(host, port=port, httpx_client=httpx_client)
     adapter_key, dispatch_reason = select_adapter_key(schema.data_model_version)
     # In a thread: resolution reads distribution metadata and imports the adapter
     # package, and this is the first call in the process to do either. See
@@ -96,6 +105,7 @@ async def create_span_client(
         data_model_version=schema.data_model_version,
         schema_dispatch_reason=dispatch_reason,
         schema=schema,
+        httpx_client=httpx_client,
     )
     await client.connect()
     return client