span-panel-api 3.0.1__tar.gz → 3.1.0__tar.gz

{span_panel_api-3.0.1 → span_panel_api-3.1.0}/CHANGELOG.md

@@ -7,6 +7,175 @@ 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.1.0]
+
+A security release. Three things a caller could not previously find out — whether a control command was delivered, whether the panel's bootstrap traffic was encrypted, and whether the CA behind the MQTT broker is still the one that was there yesterday —
+now have answers. **Install the matching adapter**: this release replaces four `SchemaAdapter` members and adds one, so `span-panel-api-schema-0` / `-1` must move to 1.1.0 at the same time. The extras (`span-panel-api[schema-0]`) carry the floor; a direct
+install of the adapter distribution does not, and a 1.0.0 adapter against this bootstrap is rejected at discovery with a named error rather than misbehaving.
+
+### Fixed
+
+- **A meter reading the panel has not sent is reported as absent instead of as zero.** Every energy and power field on `SpanCircuitSnapshot` and the six panel-level ones read off the lugs were filled with `0.0` whenever the property behind them carried no
+  value. A retained-topic replay hands a subscriber `$description` before the values it declares, so there is a window — on every connect, and again after every broker reconnect, because the adapter is rebuilt from a clean accumulator — in which every
+  circuit on the panel exists, is described, and has reported nothing. Throughout that window the snapshot stated that each of them was drawing no power and had accumulated no energy since it was installed.
+
+  **On a cumulative counter that is destructive rather than cosmetic.** A consumer cannot tell the fabricated zero from a meter that genuinely reads zero, and the reading a lifetime counter drops to when firmware resets it _is_ zero — so a consumer
+  compensating for counter resets books the entire counter as a compensation offset, and does it again on the next replay. `SpanPanel/span#259` is that failure on real hardware: an "energy dip" reported against essentially every circuit on each restart,
+  each dip equal to that circuit's whole lifetime counter, offsets reaching 8.18 MWh on a single circuit and roughly 10 MWh of fictional energy pushed into long-term statistics across one panel.
+
+  The fix is the discrimination rather than a new default: an unreported reading is `None`, a reported `0` is `0.0`, and the two no longer collapse into each other. It is per-property, so a circuit that has published half its meter reports the half it has.
+  **A synthesised `unmapped_tab_*` entry still reads zero** — an unoccupied breaker position genuinely draws nothing, and that is an assertion the adapter is entitled to make rather than a reading it failed to receive.
+
+  Two further consequences fall out of the same rule. **The panel-level fields were the worst case, not an edge case**: both lugs devices declare the same type and are told apart by the `info/direction` value they publish, so until that one property
+  arrives neither role resolves and all six fields — the whole site's import and export — were fabricated together. And **`dsm_state` no longer infers islanding from silence**: its fallback heuristic asks whether power is crossing the service entrance and
+  read "no power" out of "nothing has reported", declaring a site off-grid on the strength of a measurement nobody had made. With neither grid signal reported it now answers `UNKNOWN`, which the same function already returns when it cannot tell.
+
+- **A relay or shed-priority command aimed at a circuit the panel declares non-commandable is refused instead of published.** `set_circuit_relay_target` and `set_circuit_priority_target` were pure string formatting from a circuit id and consulted no
+  declaration at all, so both setters published to a circuit commissioned always-on or never-backup — while the same adapters were already reading exactly that refusal into `SpanCircuitSnapshot.is_user_controllable` and `.is_never_backup`. Both now return
+  `ControlTarget | None`, matching the two controls that already refused, and `set_circuit_relay` / `set_circuit_priority` raise `SpanPanelServerError` the way `set_evse_charge_limit` does.
+
+  Nothing was user-visible, because the Home Assistant integration gates entity creation on `is_user_controllable`. That is not sufficient for two reasons. **Settability changes at runtime** — re-commissioning a circuit in place cycles that child device's
+  `$state` and republishes its `$description` with a new `$settable`, so an entity can outlive its own controllability and a setup-time gate cannot see it. And `set_circuit_relay` is **public API**: any caller can reach it without an entity, and the
+  library is where the refusal contract belongs.
+
+  **The refusal is the eBus specification's rule, not either adapter's.** `switch` 0.3 declares `relay` "Settable when `relay-controllable = true`" and defines `relay-controllable` false as "locked (for example a circuit commissioned as permanently on)",
+  so a consumer publishing to a locked circuit is writing to a property the specification says is not settable on that device. Under the parent/child schema both halves of the condition are on the wire and the relay refuses when **either** says no —
+  `$settable` absent from `switch/relay`, or `switch/relay-controllable` published `false`. The redundancy is deliberate: SPAN reports a firmware defect in which the `$settable` re-toggle on the runtime re-commissioning path is skipped until the service
+  restarts, so a consumer can meet a panel whose declaration is stale while the value is current, and the panel rejects an out-of-policy write regardless of what `$settable` last advertised. Across the two production enclosures captured — 27 circuits — the
+  two agree without exception. The flat schema predates capability nodes and declares settability per device _type_, so it cannot vary per circuit; it spells the same fact `always-on`, and the priority's `never-backup`. Each is the same reading the
+  snapshot already exposes.
+
+  A locked relay keeps a settable priority, which is the combination real panels publish and which `switch` 0.3 and `load-shed` 0.3 scope separately.
+
+  **Both adapters also refuse a circuit id the panel never published**, where the flat one used to build a topic for it. Its lookup read an unpublished value as the empty string, which parses as "not always-on" and read as permission, so any id at all was
+  writable on any panel — including the synthetic `unmapped_tab_*` keys the snapshot itself invents. The two adapters answer the same question and now answer it the same way, and `SchemaAdapter` states the guarantee rather than leaving it to each
+  implementation.
+
+  **And a device that declares no such property is refused as well**, which is not the same absence as a declared property carrying no `$settable`. Under the parent/child schema an absent `$settable` on `load-shed/priority` means settable — that is the
+  documented case where firmware declares the property and omits the attribute — but a BESS, a MID or the lugs declare no `load-shed` node at all, and reading their silence as permission resolved a write topic for a control those devices never offered.
+
+- **A refused circuit command names the refusal it actually made.** An id the panel carries no circuit under was refused with "declares its relay non-commandable" and audited as `relay not commandable`, which asserts something about a circuit that does not
+  exist: it sends whoever reads it to a panel's commissioning to explain a mistyped id. The two cases now carry distinct messages and distinct `detail` values (`no such circuit`), and the distinction matters most in the audit trail, because `detail`
+  reaches `after_publish` and the Home Assistant integration writes it into a security log where it is read as a fact about the panel. `SchemaAdapter` gains `has_circuit` for it — consulted only once a target has already been refused, so it can relabel a
+  refusal but never cause one.
+
+  **`has_circuit` is a required protocol member**, and therefore the third adapter-contract change in this release alongside the four `set_*_topic` renames and the widened return types: `_derive_required_members` makes every public `SchemaAdapter` member
+  mandatory of every adapter wheel, so an adapter without it is rejected at discovery. That is not a new mismatch anyone can hit — a 1.0.0 adapter was already rejected by the renames — and the rejection names this member alongside them, with the same
+  remedy. `ADAPTER_CONTRACT_VERSION` still does not move: an added member is caught by name at discovery, which is what the constant's own docstring reserves it for.
+
+- **A control the library refused before resolving an address is no longer invisible to `ControlInterceptor`.** `after_publish` is contracted to see every command, refusals included, but five refusals happened while resolving the target and therefore never
+  reached the publish path at all: a relay declared non-commandable, a priority declared locked, a charger with no settable limit, a panel with no islanding control, and an adopted property that is not settable. A consumer building a security audit on
+  `after_publish` — which is what the Home Assistant integration does — would have had a hole in it exactly where the interesting cases are, the highest-consequence control in the system among them.
+
+  Those now produce an `after_publish` record with `PublishState.FAILED` and a `detail` naming the refusal, before the `SpanPanelServerError` is raised. `before_publish` is deliberately **not** consulted for them: there is nothing to authorise, and a veto
+  would replace a specific reason with "vetoed".
+
+- **A control command that was never sent no longer looks like one that succeeded.** All five setters returned `None` on three separate paths that published nothing: after `close()` (the adapter survives, the bridge does not, so the setter returned having
+  done nothing at all), with no paho client, and — the one that matters — while the broker was unreachable. A caller had no way to tell any of them from a breaker that actually opened.
+- **A publish while the broker is known to be down is refused instead of queued.** paho keeps a QoS-1 publish in its outbound queue across a disconnect and sends it when the connection returns, reusing the same client, so a relay command issued during an
+  outage fired whenever the broker came back — minutes later, against a panel nobody was watching, with nothing in the UI having said so. The bridge now checks its connection **before** handing the message to paho, which is the only point at which refusing
+  is still possible. A message the transport declines is reported `FAILED`, and `FAILED` is a promise that nothing will be delivered later.
+
+  The refusal is bounded by what the transport can know: the check is only as fresh as paho's disconnect detection, which is a socket close or the keepalive. A broker that stops answering _without_ closing its socket leaves the connection looking healthy
+  for up to a keepalive interval and a half, and a publish in that window is still handed over and queued. That caller is told `UNCONFIRMED`, which promises nothing about delivery in either direction, so the outcome remains truthful — but "refused rather
+  than queued" describes a detected disconnect, not every disconnect.
+
+- **A discarded command settles instead of waiting out its deadline.** Rebuilding the paho client — or tearing it down — empties the outbound queue; anything still awaiting acknowledgement used to wait out its full deadline (five seconds, for a relay) for
+  a PUBACK that could no longer arrive. Those now resolve immediately with an explicit "the transport discarded this message; delivery is unknown", so an audit trail carries a terminal state rather than a gap.
+- **A failed authentication no longer puts the rejected passphrase in the exception message.** `register_v2` interpolated the response body into `SpanPanelAuthError`, and the panel's validation layer answers a bad passphrase with a 422 that echoes the
+  submitted credential back. Home Assistant shows that message in the UI, writes it to the config-flow log, and captures it in a diagnostics download. The exception now carries the status code only; the body goes to `DEBUG` with every credential-valued key
+  replaced, found by a recursive walk rather than a top-level scan — the 422 nests the echo two levels down, so a top-level scan would redact nothing in exactly the response most likely to hold a secret. A body that is not JSON is described by length and
+  content-type rather than shown.
+- **A TLS failure during reconnect no longer re-anchors trust to whatever is answering.** The reconnect path refetched the panel's CA over unauthenticated HTTP and built its trust store from the result, so a panel presenting a certificate from a
+  _different_ CA was silently accepted. With `ca_pem` configured (below) neither connect nor rebuild fetches anything.
+
+### Added
+
+- **`PublishOutcome`, returned by every setter, saying how far a command got.** Four states, because the differences are ones a person acts on differently: `CONFIRMED` (the property reported the requested value on its own topic), `ACCEPTED` (the broker
+  acknowledged it, no transition seen), `UNCONFIRMED` (handed over, nothing came back before the deadline) and `FAILED` (never handed to the broker, and will not be delivered).
+
+  `UNCONFIRMED` **is not an error and does not raise.** It is the expected result of writing a value that is already current, and it is indistinguishable from a silent policy rejection until SPAN ships a reason code. A write whose value already matches
+  short-circuits to `UNCONFIRMED` with `no_op=True` immediately, compared in the panel's vocabulary rather than the caller's, so an automation that rewrites the same value on every run does not burn a deadline discovering that.
+
+  `CONFIRMED` is strong evidence and not proof: the panel coalesces every API client into a single `USER` requester, so an observed transition cannot be attributed to one specific write. Nothing is retried — a relay write is not idempotent in its physical
+  effect, and a racing external change may have legitimately reverted it.
+
+- **`ca_pem` on `MqttClientConfig` — pin the panel CA instead of refetching it.** Supply it and the trust anchor is a configured value: no network call on connect, none on rebuild. Left unset, the previous behaviour stands (so this remains a minor release)
+  with one `WARNING` per bridge saying the anchor was obtained unauthenticated.
+
+  A pinned handshake that fails is **not** assumed to mean the CA rotated, because it usually does not: an expired leaf after a panel's clock reset, or a hostname mismatch after the panel moved, produce the identical `SSLCertVerificationError`, and `ssl`
+  exposes no peer chain on a verification failure. The library performs a separate, display-only fetch of the panel's advertised CA and compares fingerprints. Same fingerprint, or the fetch failed — keep retrying, because a panel reachable on 8883 and not
+  on its HTTP port is a panel mid-reboot and declaring a permanent failure on missing evidence would convert a transient into an outage. Different fingerprint — `SpanPanelCAChangedError`, on the initial connect as well as in the reconnect loop.
+
+- **`build_panel_ssl_context(ca_pem)` and `ca_fingerprint(ca_pem)` are public.** A consumer that pins the CA needs the identical context and the identical fingerprint string on its own side of the pin; two implementations would drift, and the one that
+  drifted would be the security check.
+
+- **`register_fatal_error_callback` — a typed channel for a transport that has stopped for good.** The reconnect loop is fire-and-forget, so an exception raised inside it killed the task invisibly and a consumer learned nothing. Distinct from the
+  connection callback on purpose: "disconnected" is what an ordinary outage looks like and waiting through it is correct, while this fires only for a failure no amount of waiting fixes. A consumer that registers nothing is still not left guessing —
+  `ping()` and `get_snapshot()` re-raise the terminal error.
+
+- **`ControlInterceptor` — one veto-and-observe point covering all five setters.** `before_publish` may raise to refuse a command, and **the exception propagates unchanged**: the interceptor owns its type and its message, which is what lets a consumer
+  raise a framework-specific error with a translated message and have it reach the user intact. `after_publish` receives every command including the refusals (an audit that silently omits refusals is worse than no audit) and is fired as a task rather than
+  awaited, so a sink that merely hangs cannot stall every control call — the price being that ordering across commands is not guaranteed.
+
+  **This is a boundary against callers of this library and nothing more.** It does not constrain anything holding the broker credential: such a process publishes to the panel's broker directly and never reaches this code.
+
+- **HTTPS for the bootstrap REST calls.** Every `auth.py` and `detection.py` function taking `host`/`port` now accepts `ssl_context`, as do `create_span_client` and `MqttClientConfig` (the MQTT client refetches the schema over HTTP at connect and on every
+  redispatch). Supplying one moves the call to `https://`; omitting it is byte-identical to 3.0.1. `download_ca_cert` is the one exception and stays on `http://` — it is the bootstrap, fetching the anchor everything else is checked against, so it has
+  nothing to check itself against. Its docstring now says so plainly, and it takes an `ssl_context` only for the caller that _already_ holds the anchor and wants a verified second copy.
+
+### Changed
+
+- **BREAKING FOR CONSUMERS: the energy and power fields on `SpanCircuitSnapshot` and `SpanPanelSnapshot` become `float | None`.** `instant_power_w`, `produced_energy_wh` and `consumed_energy_wh` on a circuit; `instant_grid_power_w`, `feedthrough_power_w`
+  and the four `*_energy_*_wh` on the panel. `None` means the panel has not reported that reading — see the entry under **Fixed** for why the previous `0.0` was not a safe stand-in. Anything doing arithmetic straight off one of these fields is the code
+  that has to change, and mypy names every site rather than leaving it to a runtime `TypeError`. Coalescing with `or 0` is rarely the right repair: it reintroduces exactly the fabrication this removes, one layer further out. A consumer rendering a value
+  should render "unknown"; a consumer accumulating one should skip the sample.
+
+  `ADAPTER_CONTRACT_VERSION` does not move. It guards the bootstrap-to-adapter calling convention — an `__init__` arity or a member whose meaning changed under its own name — and both adapters ship this change with the bootstrap in the same unpublished
+  release, so no adapter carrying the old behaviour is reachable. The already-published 1.0.0 adapters are refused at discovery on the existing floor.
+
+- **`ControlCommand.topic` and `PublishOutcome.topic` become `str | None`.** A refusal made while resolving the address has no topic, and a command reported with one would name a string nothing was ever going to publish to. `None` appears only alongside
+  `PublishState.FAILED`. Additive for a consumer that only reads `state` and `detail`; an interceptor that passes `command.topic` somewhere expecting a `str` is the one that has to change, and does so under mypy rather than silently.
+
+- **BREAKING FOR IMPLEMENTERS: `set_circuit_relay_target` and `set_circuit_priority_target` return `ControlTarget | None`.** `SchemaAdapter` declares the wider type, joining `set_dominant_power_source_target` and `set_evse_charge_limit_target`, which have
+  always refused this way. `ADAPTER_CONTRACT_VERSION` does not move, and the direction is why: an adapter still returning a bare `ControlTarget` satisfies the wider declaration — a narrower return is a valid implementation — and simply never exercises the
+  refusal, which is the pre-fix behaviour and no worse than it. The direction the contract version does not protect, a newer adapter against an older bootstrap, is unchanged by this.
+
+- **BREAKING FOR IMPLEMENTERS: the five control-protocol setters return `PublishOutcome` instead of `None`.** `CircuitControlProtocol`, `PanelControlProtocol`, `EvseControlProtocol` and `AdoptedControlProtocol` all move. **This is additive for callers** —
+  a call site that ignores the return value compiles and behaves exactly as before — **and breaking for implementers**: any class type-checked against one of these protocols with `-> None` stops conforming. Test fakes, simulators, and any
+  `Callable[..., Awaitable[None]]` typed against a setter are precisely that, and they must be updated in the same upgrade.
+
+- **BREAKING FOR IMPLEMENTERS: `SpanPanelClientProtocol` gains `register_fatal_error_callback`.** Same class of breakage as the setters and it needs the same treatment: additive for callers, but any fake, simulator or alternate transport implementing this
+  protocol stops conforming until it grows the method — under mypy, and at runtime too, since the protocol is `runtime_checkable` and a consumer that asks `isinstance` before offering a feature will silently stop offering it. It is declared on the protocol
+  rather than only on `SpanMqttClient` because the consumer codes against protocols, never against transport-specific classes, and it now depends on this channel.
+
+- **BREAKING FOR ADAPTERS: `set_*_topic` becomes `set_*_target`, returning a `ControlTarget`.** Verifying a write means matching the topic it went to against the property that reports it, and only the adapter knows both — the two schemas spell the same
+  control differently (flat's relay is `(serial, circuit_id, "relay")`, parent/child's is `(circuit_id, "switch", "relay")`), and parsing them back out of a topic string would put wire-format knowledge in the transport, which is the one component whose job
+  is not to have any. `ControlTarget` carries the topic and that triple together, produced by one call so they cannot disagree.
+
+  The rename is deliberate rather than a return-type change under the old name. An adapter built for the old contract would keep the old name, pass discovery on presence, and then fail deep inside a setter with an `AttributeError` on a `str`; under a new
+  name it is rejected at discovery, where the remedy — upgrade the bootstrap and the adapter together — can still be named. `ADAPTER_CONTRACT_VERSION` stays **1**: the contract gained members and lost members, which discovery already detects by name,
+  rather than redefining one.
+
+- **`port` is `int | None` on every bootstrap call, defaulting to `None`.** With a plain `int = 80` there is no way to distinguish an omitted port from one a caller deliberately set to 80, and the two need opposite answers once a scheme is in play: `None`
+  resolves to 80 without an `ssl_context` and 443 with one. An explicit `port=80` **together with** an `ssl_context` raises `SpanPanelValidationError` naming both values rather than guessing — it is exactly what a consumer that stored a port before it
+  pinned a CA produces, and both readings are defensible.
+
+- **A supplied `ssl_context` now takes precedence over an injected `httpx.AsyncClient`.** httpx fixes `verify=` at construction, so a context cannot be applied to a client somebody else built; the previous behaviour of yielding an injected client untouched
+  would have meant a caller passing both got system trust while believing it had pinned the panel CA — a security control that appears to be on and is off. When both are supplied, a dedicated client is built for the call and closed after it. The cost is
+  named rather than hidden: those calls lose the injected client's connection pool, timeout and header policy. Acceptable because every caller here is bootstrap — registration, detection, schema, FQDN, status — a handful of calls per config entry.
+
+### Removed
+
+- **BREAKING: `span_panel_api.reference_payloads` is gone, and the wheel no longer carries `homie_schema.json`.** The captured `GET /api/v2/homie/schema` response is a fixture of this repository's test suite now, at
+  `tests/reference_payloads/homie_schema.json`, read through `homie_schema()` / `homie_schema_types()` there. Anyone importing the module from an installed distribution has to vendor the bytes instead — and should record which release they were taken from,
+  asserting that against `importlib.metadata.version("span-panel-api")`, so a pin that moves past a stale copy fails loudly rather than checking declarations against a schema no panel runs. That version claim is available to any consumer without a
+  checkout, which is what makes vendoring safe and is the whole reason this can be removed.
+
+  It shipped in the first place to spare consumers a copy that goes stale in silence, which was a real problem badly solved: no runtime path ever read the file, so every install of both distributions paid for test data it could not use, and the import
+  surface committed each distribution to a promise it never meant to make. Nothing declared the payloads as package data — a directory inside a package directory ships whether or not a manifest names it, which is exactly why this was easy to miss.
+  `tests/test_packaging.py` now fails if a capture reappears inside a shipped package, and CI asserts the same against every built wheel. See #162.
+
 ## [3.0.1]
 
 ### Fixed

{span_panel_api-3.0.1 → span_panel_api-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.0.1
+Version: 3.1.0
 Summary: A client library for SPAN Panel API
 Project-URL: Homepage, https://github.com/SpanPanel/span-panel-api
 Project-URL: Issues, https://github.com/SpanPanel/span-panel-api/issues
@@ -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.0.0; extra == 'schema-0'
+Requires-Dist: span-panel-api-schema-0>=1.1.0; extra == 'schema-0'
 Provides-Extra: schema-1
-Requires-Dist: span-panel-api-schema-1>=1.0.0; extra == 'schema-1'
+Requires-Dist: span-panel-api-schema-1>=1.1.0; extra == 'schema-1'
 Description-Content-Type: text/markdown
 
 # SPAN Panel API
@@ -150,21 +150,25 @@ This ensures that the first `get_snapshot()` after connect returns human-readabl
 
 The library defines structural subtyping protocols (PEP 544). All are `runtime_checkable`, so a consumer asks `isinstance` before offering a control rather than assuming the panel in front of it supports one:
 
-| Protocol                   | Purpose                                                                                    |
-| -------------------------- | ------------------------------------------------------------------------------------------ |
-| `SpanPanelClientProtocol`  | Core lifecycle: `connect`, `close`, `ping`, `get_snapshot`, `register_connection_callback` |
-| `CircuitControlProtocol`   | Relay and shed-priority control: `set_circuit_relay`, `set_circuit_priority`               |
-| `PanelControlProtocol`     | Panel-level control: `set_dominant_power_source`                                           |
-| `EvseControlProtocol`      | Per-charger control: `set_evse_charge_limit(node_id, amps)`                                |
-| `AdoptedControlProtocol`   | Write to a settable property of a device this library models nothing for                   |
-| `StreamingCapableProtocol` | Push-based updates: `register_snapshot_callback`, `start_streaming`, `stop_streaming`      |
+| Protocol                      | Purpose                                                                                    |
+| ----------------------------- | ------------------------------------------------------------------------------------------ |
+| `SpanPanelClientProtocol`     | Core lifecycle: `connect`, `close`, `ping`, `get_snapshot`, `register_connection_callback` |
+| `CircuitControlProtocol`      | Relay and shed-priority control: `set_circuit_relay`, `set_circuit_priority`               |
+| `PanelControlProtocol`        | Panel-level control: `set_dominant_power_source`                                           |
+| `EvseControlProtocol`         | Per-charger control: `set_evse_charge_limit(node_id, amps)`                                |
+| `AdoptedControlProtocol`      | Write to a settable property of a device this library models nothing for                   |
+| `ControlInterceptionProtocol` | Install one veto-and-observe point for every control command: `set_control_interceptor`    |
+| `StreamingCapableProtocol`    | Push-based updates: `register_snapshot_callback`, `start_streaming`, `stop_streaming`      |
 
 The first five differ in subject, not just in name. `EvseControlProtocol` is separate from `PanelControlProtocol` because several chargers may be commissioned at once and every call names which one. `AdoptedControlProtocol` differs in kind: the curated
 setters name a control this library understands and translate or bound the value on the way out, while this one names a property by its wire address and passes the value through, because the declaration is all anybody here knows about it. That write is
 authorised by the snapshot rather than by its arguments — the transport resolves the property against the current `adopted_devices` and refuses anything it does not find carrying a set topic, so a device this library _does_ model cannot be addressed
 through it.
 
-A seventh protocol, `SchemaAdapter`, is the bootstrap-to-parser contract rather than a consumer-facing one; it is what an adapter distribution implements and what discovery checks. Integration code programs against the protocols above, not against
+`ControlInterceptionProtocol` is separate from the four control protocols rather than a member of them because adding it there would break every implementer of those protocols a second time in one release, and separate from `StreamingCapableProtocol`
+because a transport could reasonably offer one and not the other.
+
+One further protocol, `SchemaAdapter`, is the bootstrap-to-parser contract rather than a consumer-facing one; it is what an adapter distribution implements and what discovery checks. Integration code programs against the protocols above, not against
 transport-specific classes.
 
 ### Snapshots
@@ -352,13 +356,77 @@ client.set_snapshot_interval(0)
 
 ```python
 # Set circuit relay (OPEN/CLOSED)
-await client.set_circuit_relay("circuit-uuid", "OPEN")
+outcome = await client.set_circuit_relay("circuit-uuid", "OPEN")
 await client.set_circuit_relay("circuit-uuid", "CLOSED")
 
 # Set circuit shed priority (NEVER / SOC_THRESHOLD / OFF_GRID)
 await client.set_circuit_priority("circuit-uuid", "NEVER")
 ```
 
+Every setter returns a `PublishOutcome` saying how far the command got. Ignoring it is fine and behaves as it always did; reading it is how a caller tells a breaker that opened from a command that was never sent.
+
+| `outcome.state`            | What it means                                                                   |
+| -------------------------- | ------------------------------------------------------------------------------- |
+| `PublishState.CONFIRMED`   | The property reported the requested value on its own topic                      |
+| `PublishState.ACCEPTED`    | The broker acknowledged the message; no transition observed before the deadline |
+| `PublishState.UNCONFIRMED` | Handed over, and nothing came back before the deadline                          |
+| `PublishState.FAILED`      | Never handed to the broker, and will not be delivered                           |
+
+`UNCONFIRMED` **is not an error and does not raise.** It is the expected result of writing a value that is already current — that case short-circuits immediately with `outcome.no_op` set rather than burning the deadline — and it is indistinguishable from a
+silent policy rejection by the panel until SPAN ships a reason code. `FAILED` is the one state that is a promise about the future, which is why the transport refuses to publish while the broker is unreachable instead of letting paho queue the message and
+deliver it minutes later. `CONFIRMED` is strong evidence rather than proof: the panel coalesces every API client into a single `USER` requester, so an observed transition cannot be attributed to one specific write. Nothing is retried — a relay write is not
+idempotent in its physical effect.
+
+**A control the panel declares non-commandable raises rather than returning an outcome**, because there is no topic to publish to and so nothing to report on. `SpanPanelServerError` is raised for a relay on a circuit commissioned always-on, for the shed
+priority of a circuit commissioned never-backup, and for a charger with no settable charge-current limit. The same facts are on the snapshot ahead of the call — `SpanCircuitSnapshot.is_user_controllable` and `.is_never_backup` — so a consumer that offers
+the control only where the panel offers it will not meet this; it is the backstop for the case a setup-time gate cannot see, since re-commissioning a circuit in place changes its settability while an entity built from the earlier snapshot is still alive.
+
+### Control Interception
+
+A consumer with a notion of who is asking can refuse a command before it is published, and record every command in one place rather than in five setters that will drift:
+
+```python
+class Gate:
+    async def before_publish(self, command: ControlCommand) -> None:
+        if not authorised(command):
+            raise PermissionError(f"not allowed to write {command.property_id}")
+
+    async def after_publish(self, command: ControlCommand, outcome: PublishOutcome) -> None:
+        audit.record(command, outcome.state)
+
+client.set_control_interceptor(Gate())
+```
+
+One interceptor at a time, replaceable; pass `None` to remove it. A veto's exception propagates to the caller **unchanged**, so a consumer raising a framework-specific error with a translated message gets it through intact. `after_publish` fires for
+refusals too — with `FAILED` and a `vetoed` detail — because an audit that silently omits refusals is worse than no audit; it runs as a task rather than being awaited, so a sink that hangs cannot stall every control call, and ordering across commands is
+therefore not guaranteed.
+
+That includes the refusals this library makes on the panel's behalf, which never reach a topic at all: a relay the panel declares non-commandable arrives at `after_publish` with `FAILED`, a `detail` naming the refusal, and `command.topic` set to `None`.
+`before_publish` is not consulted for those — there is nothing to authorise, and a veto would replace a specific reason with "vetoed" — so an interceptor must treat `topic` as optional and read `state` and `detail` as the machine-readable half.
+
+**This is a boundary against callers of this library and nothing more.** Anything holding the broker credential publishes to the panel directly and never reaches this code.
+
+### Pinning the Panel CA
+
+By default the MQTT bridge fetches the panel's CA over unauthenticated HTTP on every connect and trusts whatever answers, which also means a reconnect can silently re-anchor trust to a different CA. Supply the PEM instead and the anchor becomes a
+configured value — no network call on connect or on rebuild:
+
+```python
+config = MqttClientConfig(..., ca_pem=stored_pem)
+
+# The same context and the same fingerprint string the library uses, so a
+# consumer's own HTTPS calls and its own pin cannot drift from the library's.
+context = build_panel_ssl_context(stored_pem)
+fingerprint = ca_fingerprint(stored_pem)
+```
+
+Leaving `ca_pem` unset keeps the previous behaviour, with one `WARNING` per bridge recording that the anchor was obtained unauthenticated. With it set, a certificate-verification failure is diagnosed rather than assumed: an expired leaf after a panel's
+clock reset and a hostname mismatch after the panel moved both produce the identical error, so the library refetches the advertised CA for comparison only and keeps retrying unless the fingerprint has actually changed — at which point it raises
+`SpanPanelCAChangedError` carrying both fingerprints and stops. Register `register_fatal_error_callback` to be told; a consumer that registers nothing still cannot mistake a dead bridge for a healthy one, because `ping()` and `get_snapshot()` re-raise.
+
+The bootstrap REST calls take an `ssl_context` for the same purpose. `download_ca_cert` is the one exception and stays on plain HTTP — it fetches the anchor everything else is checked against, so it has nothing to check itself against, and its result must
+be fingerprint-confirmed out of band before it is trusted.
+
 ### Pending-State Detection
 
 When the panel publishes Homie `$target` properties, `SpanCircuitSnapshot` exposes the desired state alongside the actual state:
@@ -486,26 +554,11 @@ The `PanelCapability` flag enum advertises transport features at runtime:
 
 ## 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())
-```
+Captures of what a panel actually serves — the `GET /api/v2/homie/schema` document and a full 40-space parent/child retained-topic tree — live in [`tests/reference_payloads/`](tests/reference_payloads/README.md), with their provenance.
 
-Each payload carries the version of the release it shipped in. Pin a version and you read the bytes that version was written against.
+**They are fixtures of this repository, not package data.** Until 3.1.0 they sat inside the two source packages and were therefore carried in the wheels, which no runtime path ever read. `span_panel_api.reference_payloads` and
+`span_panel_api_schema_1.reference_payloads` no longer exist; a consumer that was importing them should vendor the bytes it needs and record the release it took them from, asserting that against `importlib.metadata.version(...)` so a moved pin that outruns
+the copy fails loudly instead of testing against a schema no panel runs.
 
 ## Project Structure
 
@@ -526,7 +579,6 @@ src/span_panel_api/          # distribution: span-panel-api (no parser)
 ├── phase_validation.py      # Electrical phase utilities
 ├── protocol.py              # PEP 544 protocols, SchemaAdapter, PanelCapability flags
 ├── schema_drift.py          # Reporting a panel that outruns what we can read
-├── reference_payloads/      # Captured GET /api/v2/homie/schema, shipped as package data
 └── mqtt/
     ├── __init__.py
     ├── async_client.py      # NullLock + AsyncMQTTClient (HA core pattern)
@@ -544,7 +596,7 @@ packages/schema-1/           # distribution: span-panel-api-schema-1
 ├── spec/                    # eBus capability catalogs, byte-copied; checked against, never parsed
 └── src/span_panel_api_schema_1/
                              # Parent/child parser: ControllerRoutes, snapshot mapper,
-                             # adoption, catalog validator, spec_lock.json, reference payloads
+                             # adoption, catalog validator, spec_lock.json
 ```
 
 ## Development

{span_panel_api-3.0.1 → span_panel_api-3.1.0}/README.md

@@ -123,21 +123,25 @@ This ensures that the first `get_snapshot()` after connect returns human-readabl
 
 The library defines structural subtyping protocols (PEP 544). All are `runtime_checkable`, so a consumer asks `isinstance` before offering a control rather than assuming the panel in front of it supports one:
 
-| Protocol                   | Purpose                                                                                    |
-| -------------------------- | ------------------------------------------------------------------------------------------ |
-| `SpanPanelClientProtocol`  | Core lifecycle: `connect`, `close`, `ping`, `get_snapshot`, `register_connection_callback` |
-| `CircuitControlProtocol`   | Relay and shed-priority control: `set_circuit_relay`, `set_circuit_priority`               |
-| `PanelControlProtocol`     | Panel-level control: `set_dominant_power_source`                                           |
-| `EvseControlProtocol`      | Per-charger control: `set_evse_charge_limit(node_id, amps)`                                |
-| `AdoptedControlProtocol`   | Write to a settable property of a device this library models nothing for                   |
-| `StreamingCapableProtocol` | Push-based updates: `register_snapshot_callback`, `start_streaming`, `stop_streaming`      |
+| Protocol                      | Purpose                                                                                    |
+| ----------------------------- | ------------------------------------------------------------------------------------------ |
+| `SpanPanelClientProtocol`     | Core lifecycle: `connect`, `close`, `ping`, `get_snapshot`, `register_connection_callback` |
+| `CircuitControlProtocol`      | Relay and shed-priority control: `set_circuit_relay`, `set_circuit_priority`               |
+| `PanelControlProtocol`        | Panel-level control: `set_dominant_power_source`                                           |
+| `EvseControlProtocol`         | Per-charger control: `set_evse_charge_limit(node_id, amps)`                                |
+| `AdoptedControlProtocol`      | Write to a settable property of a device this library models nothing for                   |
+| `ControlInterceptionProtocol` | Install one veto-and-observe point for every control command: `set_control_interceptor`    |
+| `StreamingCapableProtocol`    | Push-based updates: `register_snapshot_callback`, `start_streaming`, `stop_streaming`      |
 
 The first five differ in subject, not just in name. `EvseControlProtocol` is separate from `PanelControlProtocol` because several chargers may be commissioned at once and every call names which one. `AdoptedControlProtocol` differs in kind: the curated
 setters name a control this library understands and translate or bound the value on the way out, while this one names a property by its wire address and passes the value through, because the declaration is all anybody here knows about it. That write is
 authorised by the snapshot rather than by its arguments — the transport resolves the property against the current `adopted_devices` and refuses anything it does not find carrying a set topic, so a device this library _does_ model cannot be addressed
 through it.
 
-A seventh protocol, `SchemaAdapter`, is the bootstrap-to-parser contract rather than a consumer-facing one; it is what an adapter distribution implements and what discovery checks. Integration code programs against the protocols above, not against
+`ControlInterceptionProtocol` is separate from the four control protocols rather than a member of them because adding it there would break every implementer of those protocols a second time in one release, and separate from `StreamingCapableProtocol`
+because a transport could reasonably offer one and not the other.
+
+One further protocol, `SchemaAdapter`, is the bootstrap-to-parser contract rather than a consumer-facing one; it is what an adapter distribution implements and what discovery checks. Integration code programs against the protocols above, not against
 transport-specific classes.
 
 ### Snapshots
@@ -325,13 +329,77 @@ client.set_snapshot_interval(0)
 
 ```python
 # Set circuit relay (OPEN/CLOSED)
-await client.set_circuit_relay("circuit-uuid", "OPEN")
+outcome = await client.set_circuit_relay("circuit-uuid", "OPEN")
 await client.set_circuit_relay("circuit-uuid", "CLOSED")
 
 # Set circuit shed priority (NEVER / SOC_THRESHOLD / OFF_GRID)
 await client.set_circuit_priority("circuit-uuid", "NEVER")
 ```
 
+Every setter returns a `PublishOutcome` saying how far the command got. Ignoring it is fine and behaves as it always did; reading it is how a caller tells a breaker that opened from a command that was never sent.
+
+| `outcome.state`            | What it means                                                                   |
+| -------------------------- | ------------------------------------------------------------------------------- |
+| `PublishState.CONFIRMED`   | The property reported the requested value on its own topic                      |
+| `PublishState.ACCEPTED`    | The broker acknowledged the message; no transition observed before the deadline |
+| `PublishState.UNCONFIRMED` | Handed over, and nothing came back before the deadline                          |
+| `PublishState.FAILED`      | Never handed to the broker, and will not be delivered                           |
+
+`UNCONFIRMED` **is not an error and does not raise.** It is the expected result of writing a value that is already current — that case short-circuits immediately with `outcome.no_op` set rather than burning the deadline — and it is indistinguishable from a
+silent policy rejection by the panel until SPAN ships a reason code. `FAILED` is the one state that is a promise about the future, which is why the transport refuses to publish while the broker is unreachable instead of letting paho queue the message and
+deliver it minutes later. `CONFIRMED` is strong evidence rather than proof: the panel coalesces every API client into a single `USER` requester, so an observed transition cannot be attributed to one specific write. Nothing is retried — a relay write is not
+idempotent in its physical effect.
+
+**A control the panel declares non-commandable raises rather than returning an outcome**, because there is no topic to publish to and so nothing to report on. `SpanPanelServerError` is raised for a relay on a circuit commissioned always-on, for the shed
+priority of a circuit commissioned never-backup, and for a charger with no settable charge-current limit. The same facts are on the snapshot ahead of the call — `SpanCircuitSnapshot.is_user_controllable` and `.is_never_backup` — so a consumer that offers
+the control only where the panel offers it will not meet this; it is the backstop for the case a setup-time gate cannot see, since re-commissioning a circuit in place changes its settability while an entity built from the earlier snapshot is still alive.
+
+### Control Interception
+
+A consumer with a notion of who is asking can refuse a command before it is published, and record every command in one place rather than in five setters that will drift:
+
+```python
+class Gate:
+    async def before_publish(self, command: ControlCommand) -> None:
+        if not authorised(command):
+            raise PermissionError(f"not allowed to write {command.property_id}")
+
+    async def after_publish(self, command: ControlCommand, outcome: PublishOutcome) -> None:
+        audit.record(command, outcome.state)
+
+client.set_control_interceptor(Gate())
+```
+
+One interceptor at a time, replaceable; pass `None` to remove it. A veto's exception propagates to the caller **unchanged**, so a consumer raising a framework-specific error with a translated message gets it through intact. `after_publish` fires for
+refusals too — with `FAILED` and a `vetoed` detail — because an audit that silently omits refusals is worse than no audit; it runs as a task rather than being awaited, so a sink that hangs cannot stall every control call, and ordering across commands is
+therefore not guaranteed.
+
+That includes the refusals this library makes on the panel's behalf, which never reach a topic at all: a relay the panel declares non-commandable arrives at `after_publish` with `FAILED`, a `detail` naming the refusal, and `command.topic` set to `None`.
+`before_publish` is not consulted for those — there is nothing to authorise, and a veto would replace a specific reason with "vetoed" — so an interceptor must treat `topic` as optional and read `state` and `detail` as the machine-readable half.
+
+**This is a boundary against callers of this library and nothing more.** Anything holding the broker credential publishes to the panel directly and never reaches this code.
+
+### Pinning the Panel CA
+
+By default the MQTT bridge fetches the panel's CA over unauthenticated HTTP on every connect and trusts whatever answers, which also means a reconnect can silently re-anchor trust to a different CA. Supply the PEM instead and the anchor becomes a
+configured value — no network call on connect or on rebuild:
+
+```python
+config = MqttClientConfig(..., ca_pem=stored_pem)
+
+# The same context and the same fingerprint string the library uses, so a
+# consumer's own HTTPS calls and its own pin cannot drift from the library's.
+context = build_panel_ssl_context(stored_pem)
+fingerprint = ca_fingerprint(stored_pem)
+```
+
+Leaving `ca_pem` unset keeps the previous behaviour, with one `WARNING` per bridge recording that the anchor was obtained unauthenticated. With it set, a certificate-verification failure is diagnosed rather than assumed: an expired leaf after a panel's
+clock reset and a hostname mismatch after the panel moved both produce the identical error, so the library refetches the advertised CA for comparison only and keeps retrying unless the fingerprint has actually changed — at which point it raises
+`SpanPanelCAChangedError` carrying both fingerprints and stops. Register `register_fatal_error_callback` to be told; a consumer that registers nothing still cannot mistake a dead bridge for a healthy one, because `ping()` and `get_snapshot()` re-raise.
+
+The bootstrap REST calls take an `ssl_context` for the same purpose. `download_ca_cert` is the one exception and stays on plain HTTP — it fetches the anchor everything else is checked against, so it has nothing to check itself against, and its result must
+be fingerprint-confirmed out of band before it is trusted.
+
 ### Pending-State Detection
 
 When the panel publishes Homie `$target` properties, `SpanCircuitSnapshot` exposes the desired state alongside the actual state:
@@ -459,26 +527,11 @@ The `PanelCapability` flag enum advertises transport features at runtime:
 
 ## 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())
-```
+Captures of what a panel actually serves — the `GET /api/v2/homie/schema` document and a full 40-space parent/child retained-topic tree — live in [`tests/reference_payloads/`](tests/reference_payloads/README.md), with their provenance.
 
-Each payload carries the version of the release it shipped in. Pin a version and you read the bytes that version was written against.
+**They are fixtures of this repository, not package data.** Until 3.1.0 they sat inside the two source packages and were therefore carried in the wheels, which no runtime path ever read. `span_panel_api.reference_payloads` and
+`span_panel_api_schema_1.reference_payloads` no longer exist; a consumer that was importing them should vendor the bytes it needs and record the release it took them from, asserting that against `importlib.metadata.version(...)` so a moved pin that outruns
+the copy fails loudly instead of testing against a schema no panel runs.
 
 ## Project Structure
 
@@ -499,7 +552,6 @@ src/span_panel_api/          # distribution: span-panel-api (no parser)
 ├── phase_validation.py      # Electrical phase utilities
 ├── protocol.py              # PEP 544 protocols, SchemaAdapter, PanelCapability flags
 ├── schema_drift.py          # Reporting a panel that outruns what we can read
-├── reference_payloads/      # Captured GET /api/v2/homie/schema, shipped as package data
 └── mqtt/
     ├── __init__.py
     ├── async_client.py      # NullLock + AsyncMQTTClient (HA core pattern)
@@ -517,7 +569,7 @@ packages/schema-1/           # distribution: span-panel-api-schema-1
 ├── spec/                    # eBus capability catalogs, byte-copied; checked against, never parsed
 └── src/span_panel_api_schema_1/
                              # Parent/child parser: ControllerRoutes, snapshot mapper,
-                             # adoption, catalog validator, spec_lock.json, reference payloads
+                             # adoption, catalog validator, spec_lock.json
 ```
 
 ## Development

{span_panel_api-3.0.1 → span_panel_api-3.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.0.1"
+version = "3.1.0"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -53,8 +53,13 @@ dependencies = [
 # is pip's own signal that prereleases are acceptable for that requirement, so a
 # `>=1.0.0b5` floor here would leave a released install willing to resolve a
 # future beta of the adapter without anyone asking for one.
-schema-0 = ["span-panel-api-schema-0>=1.0.0"]
-schema-1 = ["span-panel-api-schema-1>=1.0.0"]
+# Raised to 1.1.0 for 3.1.0, and this floor is not cosmetic. The `SchemaAdapter`
+# protocol replaced `set_*_topic` with `set_*_target`, and `_derive_required_members`
+# makes every public protocol member mandatory of every adapter wheel — so a 1.0.0
+# adapter installed against this bootstrap is rejected at discovery rather than
+# working in a degraded way. The two must move together.
+schema-0 = ["span-panel-api-schema-0>=1.1.0"]
+schema-1 = ["span-panel-api-schema-1>=1.1.0"]
 
 [project.urls]
 Homepage = "https://github.com/SpanPanel/span-panel-api"