span-panel-api 3.0.0b2__tar.gz → 3.0.0b6__tar.gz

span_panel_api-3.0.0b6/.gitignore

@@ -0,0 +1,47 @@
+__pycache__/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.cursor/
+.cursorignore
+.cursor
+.cursorindexingignore
+xnotes/*
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.envrc
+.venv
+.vscode/settings.json
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# JetBrains
+.idea/
+
+/coverage.xml
+/.coverage
+coverage_output.log
+**/.DS_Store
+.local_coverage_data
+
+# Captures taken from a real panel. These carry the panel's serial (which is also
+# its MQTT username), the household's circuit names, and real consumption — none
+# 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.0b2 → span_panel_api-3.0.0b6}/CHANGELOG.md

@@ -4,6 +4,155 @@ 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.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.
+
+### Changed
+
+- **BREAKING — DER identity speaks v1.0's vocabulary on every device class.** `model` is the human designation and `part_number` the SKU, on `battery`, `evse` and `pv` alike. `product_name` is retired on all three. Flat is the inconsistent side, not v1.0:
+  it puts the SKU in `bess/model` and in `evse/part-number`, the same concept under two names, and gives PV neither. `schema_1` used to cross over (`info/part-number` → `battery.model`) to hold each entity's displayed meaning still, which worked and
+  permanently encoded flat's irregularity in the snapshot. `schema_0` now translates flat into the normalised shape instead of mirroring it. Measured: every EVSE identity field reads identically on both adapters, so for that device class identity stops
+  being a migration delta at all. **`battery.model` changes value for existing flat users at this upgrade** — it gains the designation where it carried the SKU. That is the deliberate trade: a change we schedule in a library release beats the same change
+  arriving unplanned during a firmware upgrade a user did not choose the timing of.
+- **Consumers reading `product_name` must move to `model` in the same release.** The Home Assistant integration builds its device-registry model from it; left unchanged, device cards go blank.
+
+### Added
+
+- **`SpanMidSnapshot`, and `SpanPanelSnapshot.mid`.** v1.0 publishes a Microgrid Interconnect Device and the enclosure model puts the `grid` capability on it rather than on the enclosure, so islanding state, grid state and the grid-forming entity live
+  there. Previously one of its five properties was read and the device discarded. Purely additive: no flat panel publishes a MID, so nothing existing changes. Presence is `snapshot.mid is not None` rather than a sentinel field, and identity is
+  `info/serial-number` rather than the Homie device id, which the proxy model warns is not stable across a proxy-to-native transition.
+
+### Fixed
+
+- **Adapter discovery no longer blocks the caller's event loop, and no longer imports adapters the panel will never use.** Two defects with one cause: discovery resolved the whole entry-point group up front, on the calling thread. A flat panel therefore
+  imported `schema_1` — and with it the eBus SDK and jsonschema — on every connection, for a parser it would not call. Home Assistant reported the whole sequence (`listdir`, `read_text`, `open`, `scandir`) as blocking calls inside the event loop and asked
+  for a bug report, with setup stalled 2.0s on a cold import cache. Enumeration and resolution are now separate: `installed_adapter_keys()` reads distribution metadata only, and an adapter is imported the first time a panel asks for that key. The async
+  paths run both in a thread. Resolution stays cached per key, which is what keeps the synchronous pre-rebuild callback free of I/O. **`discover_adapters()` is replaced by `installed_adapter_keys()`**, which returns registered names rather than a registry
+  of loaded classes — verifying every name would mean importing every package, which is the cost being removed. `SpanMqttClient.available_adapters` becomes `installed_adapters` for the same reason.
+- **A firmware upgrade to a schema generation this install cannot parse is reported instead of raised into a background task.** The redispatch path resolves the new adapter before touching any state, so a flat-only install that meets a v1.0 panel logs
+  which package is missing and keeps the parser it has. Previously `SpanPanelAdapterMissingError` escaped a fire-and-forget task as a bare traceback.
+- **`dsm_state` and `current_run_config` are read from the MID instead of reading `UNKNOWN`.** Both are existing entities that had degraded on v1.0 — not because a source vanished, but because `schema_0` _derives_ them and the derivation was never ported.
+  v1.0 states the answer, so the multi-signal heuristic is gone: sensed from a ready MID, falling back to the user's `shed/asserted-islanding-state` when it is not ready, then to a `power-flows/grid` heuristic when there is no MID at all, and unknown
+  otherwise. A missing MID never reports on-grid — it means SPAN is not the islanding authority, not that the site is on grid, and a generator-fed island is the counterexample. `PANEL_BACKUP` versus `PANEL_OFF_GRID` becomes authoritative rather than
+  guessed, because v1.0 names the forming device and its class is recoverable from the tree.
+- **`grid_islandable` is mapped to `grid-forming/capable`** over the BESS's inverter children, as the disjunction — a panel does not island, its DER does, and flat expressed a property of the DER as a property of the enclosure. It returns `None` rather
+  than `False` when nothing publishes it, so absence stays a gap instead of becoming a claim. No producer publishes it today, which is recorded rather than worked around.
+- **EVSE identity survives the migration.** The snapshot key and `node_id` — which a consumer builds a `unique_id` and a device-registry identifier from — were the v1.0 device id on `schema_1` and firmware's node name on `schema_0`, so every charger would
+  have orphaned and reappeared as a duplicate. Both are the Drive's serial now, which is what real flat firmware keys by.
+
 ## [3.0.0b2] - 08/2026
 
 Pre-release. Releases the reshaped `SchemaAdapter` protocol that `3.0.0b1` predates, and makes the mismatch between the two detectable rather than fatal at construction.

span_panel_api-3.0.0b2/README.md → span_panel_api-3.0.0b6/PKG-INFO

@@ -1,3 +1,22 @@
+Metadata-Version: 2.5
+Name: span-panel-api
+Version: 3.0.0b6
+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.0b2/PKG-INFO → span_panel_api-3.0.0b6/README.md

@@ -1,18 +1,3 @@
-Metadata-Version: 2.4
-Name: span-panel-api
-Version: 3.0.0b2
-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.0b2 → span_panel_api-3.0.0b6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.0.0b2"
+version = "3.0.0b6"
 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 —
@@ -45,7 +61,12 @@ dev = [
     "mypy",
     "pylint",
     "radon",
-    "twine",
+    # 7.0 or newer: hatchling emits `Metadata-Version: 2.5` and twine 6.2 rejects
+    # it as invalid. The build backend is resolved fresh at build time from an
+    # unpinned `[build-system] requires`, so the metadata version moves without
+    # anything in this repository changing -- which is how a green CI turned red
+    # on a commit that touched two changelogs and a dependency floor.
+    "twine>=7.0",
     "vulture>=2.14",
     "types-pyyaml>=6.0.12.20250915",
     "coverage",
@@ -67,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
@@ -215,6 +258,10 @@ disable = [
     "missing-class-docstring",
     "missing-function-docstring",
     "too-few-public-methods",
+    # The transport implements four protocols, so its public surface is set by
+    # how many the composition asks for rather than by anything a split would
+    # improve. Every sibling in this family is already off for the same reason.
+    "too-many-public-methods",
     "too-many-arguments",
     "too-many-instance-attributes",
     "too-many-locals",

{span_panel_api-3.0.0b2 → span_panel_api-3.0.0b6}/src/span_panel_api/__init__.py

@@ -31,16 +31,25 @@ 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,
     SpanCircuitSnapshot,
     SpanEvseSnapshot,
+    SpanMidSnapshot,
     SpanPanelSnapshot,
+    SpanPcsSnapshot,
     SpanPVSnapshot,
     V2AuthResponse,
     V2HomieSchema,
     V2StatusInfo,
+    is_discovery_path,
 )
 from .mqtt import MqttClientConfig, SpanMqttClient
 from .phase_validation import (
@@ -52,7 +61,9 @@ from .phase_validation import (
     validate_solar_tabs,
 )
 from .protocol import (
+    AdoptedControlProtocol,
     CircuitControlProtocol,
+    EvseControlProtocol,
     PanelCapability,
     PanelControlProtocol,
     SpanPanelClientProtocol,
@@ -64,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",
@@ -71,12 +93,28 @@ __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",
     "SpanEvseSnapshot",
+    "SpanMidSnapshot",
     "SpanPVSnapshot",
     "SpanPanelSnapshot",
+    "SpanPcsSnapshot",
     # Factory
     "create_span_client",
     # Detection