span-panel-api-schema-1 1.1.2__tar.gz → 1.1.4__tar.gz

{span_panel_api_schema_1-1.1.2 → span_panel_api_schema_1-1.1.4}/.gitignore

@@ -40,8 +40,3 @@ coverage_output.log
 # of which belongs in a repository. The differential that reads them commits its
 # *verdict* only, never the capture, and skips when the file is absent.
 tests/fixtures/live_*.json
-
-# Peer checkouts. CI clones the eBus specification and SpanPanel/panelbench here so
-# the provenance checks have something to compare vendored bytes against; the same
-# layout works locally if you would rather not point .env at siblings.
-/peers/

{span_panel_api_schema_1-1.1.2 → span_panel_api_schema_1-1.1.4}/CHANGELOG.md

@@ -9,6 +9,30 @@ number. A release here means this parser changed, never that the panel did.
 
 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.
 
+## [1.1.4]
+
+The parser reports the islanding state the panel is acting on, and refuses islanding writes the panel would ignore. Reported and fixed by [@dcj](https://github.com/dcj) in [#179](https://github.com/SpanPanel/span-panel-api/pull/179), from issue
+[#178](https://github.com/SpanPanel/span-panel-api/issues/178).
+
+### Fixed
+
+- **An islanding assertion in force is now the reported islanding state even while the MID is ready.** `resolve_islanding_state` returned the MID's sensed value whenever the MID was ready and read `shed/asserted-islanding-state` only when it was not, so
+  `dsm_state` could disagree with the state the panel was acting on. `ON_GRID` or `OFF_GRID` asserted now wins; otherwise the ready MID's value, then the existing fallback.
+- **`set_dominant_power_source_target` returns None unless the panel declares `shed/asserted-islanding-state` settable**, the same refusal `set_circuit_relay_target` makes.
+- **`dominant_power_source_payload` refuses `NONE` and `UNKNOWN`** instead of publishing `NONE`, which the panel ignores. An assertion clears itself once the panel's link to the battery recovers.
+
+## [1.1.3]
+
+`spec_lock.json` ships inside this wheel, so its shape changing is a release here even though the parser did not change.
+
+### Added
+
+- **`span_panel_api_schema_1/reference/parent_child_tree.json`** — the reference capture, shipped as package data so a downstream test suite replays the bytes its pinned version was tested against instead of vendoring a copy.
+
+### Changed
+
+- **`spec_lock.json` loses its `peers` block** — the producer this parser is developed against is now an ordinary pinned dev dependency of the repository rather than a peer recorded in the lockfile.
+
 ## [1.1.2]
 
 A refreshed peer pin: `spec_lock.json` ships inside this wheel, so the reference capture's producer moving is a release here even though the parser did not change.

{span_panel_api_schema_1-1.1.2 → span_panel_api_schema_1-1.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api-schema-1
-Version: 1.1.2
+Version: 1.1.4
 Summary: Parent/child schema (data-model-version 1.x) parser 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
@@ -54,16 +54,28 @@ span-panel-api's transport covers the whole tree and each message is routed to w
 
 ## Conformance
 
-`spec_lock.json` ships with the package and records what this parser targets: the firmware range, the eBus specification commit its vocabulary was read from, and the version of every capability, device and registry it implements. The capability catalogs it
-addresses are byte-copied under `spec/`.
+`spec_lock.json` ships with the package and is this parser's declaration as a consumer: the firmware range it reads, the eBus specification commit its vocabulary was read from, and the version of every capability, device and registry it implements. The
+capability catalogs it addresses are byte-copied into the repository under `spec/`, and the repository checks them against the copies the eBus emitter carries in its own wheel.
 
 Those copies exist to be **checked against, never parsed in production** — units and datatypes come from each device's `$description`, since a catalog is the superset across all hardware rather than a statement about the panel in front of you. The suite
 asks the consumer's question rather than the publisher's: is every name this adapter _reads_ one the specification defines? A consumer addressing a name that no longer exists does not fail loudly, it goes quiet — the property never arrives, metadata lookup
 returns `None`, and an entity disappears.
 
-## Reference payloads
+## Reference payload
 
-A retained-topic capture of a full 40-space parent/child panel, and the replay that turns it back into devices, are fixtures of the repository's test suite at `tests/reference_payloads/`.
+`span_panel_api_schema_1/reference/parent_child_tree.json` ships in this wheel: a retained-topic capture of a full 40-space parent/child panel — 14 devices, `{device_id: {topic: payload}}`, every value a string exactly as a broker retains it.
 
-**`span_panel_api_schema_1.reference_payloads` no longer exists.** It was package data until 1.1.0 — carried in this wheel because it sat inside the package directory, though no runtime path read it. A consumer that was importing it should vendor the bytes
-it needs and record the release it took them from, asserting that against `importlib.metadata.version("span-panel-api-schema-1")` so a moved pin that outruns the copy fails loudly instead of testing against a tree no panel publishes.
+**Test-support data, and no runtime path reads it.** It ships so a downstream test suite pinned to a version of this adapter replays the bytes that version was built and tested against, out of its own site-packages:
+
+```python
+from importlib.resources import files
+import json
+
+tree = json.loads((files("span_panel_api_schema_1") / "reference" / "parent_child_tree.json").read_text(encoding="utf-8"))
+```
+
+Vendoring a copy instead means also maintaining a guard to keep the copy honest, which is what this replaces. It was package data until 1.1.0, a fixture of the repository's test suite for 1.1.2, and package data again from 1.1.3 — for the cost, not for the
+principle: no runtime path has ever read it.
+
+The bytes are produced by `ebus-panel-sim`, pinned in the repository's dev dependencies, and the repository's suite regenerates the capture in-process on every run and compares it, so a tree the pinned producer does not reproduce is a test failure rather
+than a claim in a document.

{span_panel_api_schema_1-1.1.2 → span_panel_api_schema_1-1.1.4}/README.md

@@ -41,16 +41,28 @@ span-panel-api's transport covers the whole tree and each message is routed to w
 
 ## Conformance
 
-`spec_lock.json` ships with the package and records what this parser targets: the firmware range, the eBus specification commit its vocabulary was read from, and the version of every capability, device and registry it implements. The capability catalogs it
-addresses are byte-copied under `spec/`.
+`spec_lock.json` ships with the package and is this parser's declaration as a consumer: the firmware range it reads, the eBus specification commit its vocabulary was read from, and the version of every capability, device and registry it implements. The
+capability catalogs it addresses are byte-copied into the repository under `spec/`, and the repository checks them against the copies the eBus emitter carries in its own wheel.
 
 Those copies exist to be **checked against, never parsed in production** — units and datatypes come from each device's `$description`, since a catalog is the superset across all hardware rather than a statement about the panel in front of you. The suite
 asks the consumer's question rather than the publisher's: is every name this adapter _reads_ one the specification defines? A consumer addressing a name that no longer exists does not fail loudly, it goes quiet — the property never arrives, metadata lookup
 returns `None`, and an entity disappears.
 
-## Reference payloads
+## Reference payload
 
-A retained-topic capture of a full 40-space parent/child panel, and the replay that turns it back into devices, are fixtures of the repository's test suite at `tests/reference_payloads/`.
+`span_panel_api_schema_1/reference/parent_child_tree.json` ships in this wheel: a retained-topic capture of a full 40-space parent/child panel — 14 devices, `{device_id: {topic: payload}}`, every value a string exactly as a broker retains it.
 
-**`span_panel_api_schema_1.reference_payloads` no longer exists.** It was package data until 1.1.0 — carried in this wheel because it sat inside the package directory, though no runtime path read it. A consumer that was importing it should vendor the bytes
-it needs and record the release it took them from, asserting that against `importlib.metadata.version("span-panel-api-schema-1")` so a moved pin that outruns the copy fails loudly instead of testing against a tree no panel publishes.
+**Test-support data, and no runtime path reads it.** It ships so a downstream test suite pinned to a version of this adapter replays the bytes that version was built and tested against, out of its own site-packages:
+
+```python
+from importlib.resources import files
+import json
+
+tree = json.loads((files("span_panel_api_schema_1") / "reference" / "parent_child_tree.json").read_text(encoding="utf-8"))
+```
+
+Vendoring a copy instead means also maintaining a guard to keep the copy honest, which is what this replaces. It was package data until 1.1.0, a fixture of the repository's test suite for 1.1.2, and package data again from 1.1.3 — for the cost, not for the
+principle: no runtime path has ever read it.
+
+The bytes are produced by `ebus-panel-sim`, pinned in the repository's dev dependencies, and the repository's suite regenerates the capture in-process on every run and compares it, so a tree the pinned producer does not reproduce is a test failure rather
+than a claim in a document.

{span_panel_api_schema_1-1.1.2 → span_panel_api_schema_1-1.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api-schema-1"
-version = "1.1.2"
+version = "1.1.4"
 description = "Parent/child schema (data-model-version 1.x) parser for span-panel-api"
 authors = [
     {name = "SpanPanel"}

{span_panel_api_schema_1-1.1.2 → span_panel_api_schema_1-1.1.4}/src/span_panel_api_schema_1/adapter.py

@@ -40,7 +40,7 @@ from span_panel_api_schema_1.const import (
     STATE_READY,
     TYPE_CIRCUIT,
 )
-from span_panel_api_schema_1.description import device_type
+from span_panel_api_schema_1.description import declared_settable, device_type, node_properties
 from span_panel_api_schema_1.field_metadata import build_field_metadata
 from span_panel_api_schema_1.panel import integer
 from span_panel_api_schema_1.snapshot import TreeRoles, build_snapshot, harmonised_evse_keys
@@ -275,9 +275,23 @@ class SchemaOneAdapter:
         the BESS stops discharging. Returning None here, as this did until the
         successor was decided, left that recovery unavailable during an outage.
 
+        **The panel decides whether a write takes effect, by its own link to the
+        battery.** It accepts `ON_GRID` or `OFF_GRID` only while the battery's
+        `status/communication-state` is not `OK`; otherwise it ignores the write
+        and the published value does not change. A lost MID alone does not make
+        the write eligible. `NONE` is always ignored.
+
+        **None unless the panel declares the assertion `$settable`**, the same
+        refusal `set_circuit_relay_target` makes. Absence of the declaration,
+        or of the property, authorizes nothing (see
+        `description.declared_settable`).
+
         Payload translation is not optional: the flat enum this protocol speaks
         is not the one the panel accepts. See `dominant_power_source_payload`.
         """
+        root = self._controller.get_root(self._serial_number)
+        if not declared_settable(node_properties(root, NODE_SHED).get(PROP_ASSERTED_ISLANDING_STATE)):
+            return None
         return self._target(self._serial_number, NODE_SHED, PROP_ASSERTED_ISLANDING_STATE)
 
     def dominant_power_source_payload(self, value: str) -> str | None:
@@ -291,17 +305,19 @@ class SchemaOneAdapter:
 
         The narrowing loses nothing, because the six values were a *source
         class* pressed into service as a manual override and the job only ever
-        needed on-grid, off-grid, or no assertion. Anything not recognised
-        returns None rather than guessing, so the transport refuses the command
-        instead of asserting something the user did not ask for.
+        needed on-grid or off-grid. Anything not recognized returns None rather
+        than guessing, so the transport refuses the command instead of
+        asserting something the user did not ask for.
+
+        **`NONE` and `UNKNOWN` are refused too.** The panel ignores a written
+        `NONE`, so publishing one would report a clear that never happened. An
+        assertion clears itself once the panel's link to the battery recovers.
         """
         return {
             "GRID": "ON_GRID",
             "BATTERY": "OFF_GRID",
             "PV": "OFF_GRID",
             "GENERATOR": "OFF_GRID",
-            "NONE": "NONE",
-            "UNKNOWN": "NONE",
         }.get(value.strip().upper())
 
     def set_evse_charge_limit_target(self, node_id: str) -> ControlTarget | None:

{span_panel_api_schema_1-1.1.2 → span_panel_api_schema_1-1.1.4}/src/span_panel_api_schema_1/field_metadata.py

@@ -472,8 +472,8 @@ _CONSUMED_OFF_SNAPSHOT: dict[tuple[str, str, str], str] = {
         "parses the tree, so it is consumed before any snapshot exists"
     ),
     (TYPE_PANEL, NODE_SHED, "asserted-islanding-state"): (
-        "tier 2 of resolve_islanding_state (panel.py), shadowed wherever a MID answers "
-        "at tier 1, and the write target of set_dominant_power_source_target"
+        "tier 1 of resolve_islanding_state (panel.py), which returns a non-NONE "
+        "assertion first, and the write target of set_dominant_power_source_target"
     ),
     (TYPE_LUGS, NODE_CONNECTION, "feeds-device-id"): (
         "the downstream-lugs feedthrough branch of resolve_relative_position "

{span_panel_api_schema_1-1.1.2 → span_panel_api_schema_1-1.1.4}/src/span_panel_api_schema_1/panel.py

@@ -600,7 +600,6 @@ _GRID_POWER_EPSILON_W = 1.0
 
 ISLANDING_ON_GRID = "ON_GRID"
 ISLANDING_OFF_GRID = "OFF_GRID"
-ASSERTION_NONE = "NONE"
 
 
 def resolve_islanding_state(mid: DiscoveredDevice | None, panel: DiscoveredDevice) -> str | None:
@@ -608,17 +607,19 @@ def resolve_islanding_state(mid: DiscoveredDevice | None, panel: DiscoveredDevic
 
     | tier | condition | source |
     | --- | --- | --- |
-    | 1 | MID `$state` is `ready` and `islanding-state` present | sensed |
-    | 2 | MID not `ready` | `shed/asserted-islanding-state`, when not `NONE` |
+    | 1 | `shed/asserted-islanding-state` is `ON_GRID` or `OFF_GRID` | asserted |
+    | 2 | MID `$state` is `ready` and `islanding-state` present | sensed |
     | 3 | no MID at all | `power-flows/grid` heuristic |
     | 4 | none of the above | unknown |
 
-    **Tier 2 is the reason the assertion control exists.** When comms to the BESS or MID
-    are lost and the grid returns, the user asserts the grid is up so the BESS stops
-    discharging. Declining to read it here would wire the control and then ignore it at
-    exactly the moment it matters. Nothing is hidden by doing so: the MID is a device, so
-    it goes *unavailable* in Home Assistant when it stops publishing, and the assertion is
-    itself visible as the control the user set.
+    **An assertion in force is the effective state, so it outranks the MID.** When the
+    panel's link to the battery is not healthy (the battery's `status/communication-state`
+    is not `OK`) and the grid returns, the user asserts the grid is up so the BESS stops
+    discharging, and the panel acts on that assertion until it clears. The panel ignores
+    the write while that link is healthy.
+    Reading the MID first would report the sensed value while the panel is acting on a
+    different one. The assertion clears itself back to `NONE` once the battery link
+    recovers, so the MID's answer returns without anything here having to expire it.
 
     **Tier 3 never answers `OFF_GRID`, and never asserts on-grid from a missing MID.** An
     earlier draft reasoned that no MID means no islanding authority means on-grid. That is
@@ -627,14 +628,15 @@ def resolve_islanding_state(mid: DiscoveredDevice | None, panel: DiscoveredDevic
     counterexample. Grid power flowing is positive evidence of being on-grid; its absence
     is not evidence of the opposite.
     """
+    asserted = text(panel, NODE_SHED, PROP_ASSERTED_ISLANDING_STATE)
+    if asserted in (ISLANDING_ON_GRID, ISLANDING_OFF_GRID):
+        return asserted
+
     if mid is not None:
         if mid.state == "ready":
             sensed = text(mid, NODE_GRID, PROP_ISLANDING_STATE)
             if sensed:
                 return sensed
-        asserted = text(panel, NODE_SHED, PROP_ASSERTED_ISLANDING_STATE)
-        if asserted and asserted != ASSERTION_NONE:
-            return asserted
         return None
 
     grid_power = number(panel, NODE_POWER_FLOWS, "grid")