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

span_panel_api-3.0.0b3/.env.example

@@ -0,0 +1,54 @@
+# Local-developer environment variables for span-panel-api.
+#
+# Copy to `.env` and fill in. `.env` is gitignored and must stay that way.
+#
+# `tests/conftest.py` reads this file directly, so no direnv or dotenv package is
+# needed. A value already exported in your shell wins over anything here — the
+# file supplies defaults, it does not override an intentional choice.
+#
+# Everything below is optional. Without it the suite runs in full and the checks
+# that need a sibling checkout skip themselves rather than fail, which is what CI
+# does. They are the *provenance* half of the schema_1 conformance suite: they
+# verify that the vendored copies still match their sources. The conformance and
+# coverage checks, which are the ones that catch real defects, run regardless.
+
+# A checkout of the eBus specification.
+#
+#   git clone https://github.com/electrification-bus/specification
+#
+# Enables the byte comparison of `packages/schema-1/spec/catalogs/*.json` against
+# the specification's `capabilities/`. Position the checkout at the commit
+# `spec_lock.json` pins (`synced_commit`) before believing a failure — a checkout
+# on a newer HEAD reports differences that are drift, not corruption.
+#EBUS_SPEC_DIR=/path/to/specification
+
+# A checkout of SpanPanel/panelbench, the publisher this parser is developed
+# against.
+#
+#   git clone git@github.com:SpanPanel/panelbench.git
+#
+# Enables verifying the two vendored captures and the recorded peer pins against
+# the producer itself. The tree capture is compared byte for byte; the wire
+# capture is compared on shape, because its values are perturbed by the
+# simulator's `noise_factor` and an advancing clock.
+#PANELBENCH_DIR=/path/to/panelbench
+
+# ---------------------------------------------------------------------------
+# A live SPAN panel running flat firmware (optional, and nothing needs it)
+# ---------------------------------------------------------------------------
+#
+# Enables `scripts/capture_live_flat.py`, which takes a retained capture from a
+# real panel so the frozen flat simulator can be measured against firmware rather
+# than trusted. Without it, `test_live_flat_differential.py` skips.
+#
+# The username IS the panel serial, so treat both of these as secrets and keep
+# them here. The capture the script writes is gitignored for the same reason: it
+# carries the serial, the household's circuit names and real consumption. Only the
+# differential's verdict is ever committed.
+#
+# TLS is on and certificate validation is off: the panel presents a self-signed
+# certificate.
+#LIVE_PANEL_HOST=192.168.1.50
+#LIVE_PANEL_PORT=8883
+#LIVE_PANEL_USERNAME=your-panel-serial
+#LIVE_PANEL_PASSWORD=

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

@@ -34,3 +34,9 @@ dmypy.json
 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

{span_panel_api-3.0.0b2 → span_panel_api-3.0.0b3}/.markdownlint-cli2.jsonc

@@ -36,6 +36,12 @@
   },
   "globs": ["**/*.md"],
   "ignores": [
+    // Byte copies of the eBus specification, verified by byte comparison in
+    // tests/test_schema_one_conformance.py. Upstream's line lengths are not
+    // ours to correct, and a fix here would invalidate that comparison.
+    // `globs` above scans the tree directly, so pre-commit's `exclude` cannot
+    // filter this out -- it has to be ignored here.
+    "packages/schema-1/spec/**",
     ".venv/**",
     "venv/**",
     "node_modules/**",

{span_panel_api-3.0.0b2 → span_panel_api-3.0.0b3}/.pre-commit-config.yaml

@@ -3,10 +3,15 @@ repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:
+      # `packages/schema-1/spec/` holds byte copies of the eBus specification,
+      # verified by byte comparison in tests/test_schema_one_conformance.py. Any
+      # hook that rewrites a file must skip it: a "fix" there would silently
+      # invalidate the comparison that makes the copies trustworthy. Non-mutating
+      # checks (check-json) deliberately still run, since a corrupt copy should fail.
       - id: trailing-whitespace
-        exclude: '^src/span_panel_api/generated_client/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*'
+        exclude: '^src/span_panel_api/generated_client/.*|^packages/schema-1/spec/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*'
       - id: end-of-file-fixer
-        exclude: '^src/span_panel_api/generated_client/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*'
+        exclude: '^src/span_panel_api/generated_client/.*|^packages/schema-1/spec/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*'
       - id: check-yaml
         exclude: '^src/span_panel_api/generated_client/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*'
       - id: check-toml
@@ -20,7 +25,7 @@ repos:
         exclude: '^src/span_panel_api/generated_client/.*|generate_client\.py|scripts/.*|tests/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*|^examples/.*'
       - id: mixed-line-ending
         args: ['--fix=lf']
-        exclude: '^src/span_panel_api/generated_client/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*'
+        exclude: '^src/span_panel_api/generated_client/.*|^packages/schema-1/spec/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*'
 
   # Ruff for formatting and linting
   - repo: https://github.com/astral-sh/ruff-pre-commit
@@ -55,7 +60,7 @@ repos:
       - id: prettier
         types: [markdown]
         args: ['--config', '.prettierrc.json']
-        exclude: '^src/span_panel_api/generated_client/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*|node_modules/.*|htmlcov/.*'
+        exclude: '^src/span_panel_api/generated_client/.*|^packages/schema-1/spec/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*|node_modules/.*|htmlcov/.*'
 
   # Markdownlint for markdown files (after Prettier formatting)
   - repo: https://github.com/DavidAnson/markdownlint-cli2
@@ -63,7 +68,7 @@ repos:
     hooks:
       - id: markdownlint-cli2
         args: ['--config', '.markdownlint-cli2.jsonc']
-        exclude: '^src/span_panel_api/generated_client/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*|node_modules/.*|htmlcov/.*'
+        exclude: '^src/span_panel_api/generated_client/.*|^packages/schema-1/spec/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*|node_modules/.*|htmlcov/.*'
 
   # MyPy for type checking
   - repo: https://github.com/pre-commit/mirrors-mypy
@@ -80,7 +85,7 @@ repos:
           # schema-1 parses the parent/child tree with the eBus SDK, which
           # ships py.typed — so the hook needs it installed to resolve those
           # types rather than silently reporting import-not-found.
-          - ebus-sdk>=0.18.0
+          - ebus-sdk>=0.19.0
         args: ['--config-file=pyproject.toml']
         exclude: '^src/span_panel_api/generated_client/.*|scripts/.*|tests/.*|docs/.*|examples/.*|\..*_cache/.*|dist/.*|venv/.*'
 
@@ -98,7 +103,7 @@ repos:
           - paho-mqtt
           # schema-1 imports the eBus SDK; without it here the hook reports
           # import-error for a dependency that is correctly declared.
-          - ebus-sdk>=0.18.0
+          - ebus-sdk>=0.19.0
         exclude: '^src/span_panel_api/generated_client/.*|tests/.*|generate_client\.py|scripts/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*|^examples/.*'
 
   # Check for common security issues

{span_panel_api-3.0.0b2 → span_panel_api-3.0.0b3}/CHANGELOG.md

@@ -4,6 +4,43 @@ 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.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 → span_panel_api-3.0.0b3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.0.0b2
+Version: 3.0.0b3
 Summary: A client library for SPAN Panel API
 Project-URL: Homepage, https://github.com/SpanPanel/span-panel-api
 Project-URL: Issues, https://github.com/SpanPanel/span-panel-api/issues

{span_panel_api-3.0.0b2 → span_panel_api-3.0.0b3}/RELEASE.md

@@ -162,9 +162,9 @@ CI going green proves the build, not the install. The seam this repository is bu
 # 1. The bootstrap alone must fail by name, not with ModuleNotFoundError
 python3 -m venv .solo && ./.solo/bin/pip install --pre span-panel-api
 ./.solo/bin/python -c "
-from span_panel_api.adapters import discover_adapters, resolve_adapter, DEFAULT_ADAPTER_KEY
+from span_panel_api.adapters import installed_adapter_keys, resolve_adapter, DEFAULT_ADAPTER_KEY
 from span_panel_api.exceptions import SpanPanelAdapterMissingError
-print('adapters:', sorted(discover_adapters()))
+print('adapters:', installed_adapter_keys())
 try:
     resolve_adapter(DEFAULT_ADAPTER_KEY, 'release check')
 except SpanPanelAdapterMissingError as exc:
@@ -174,8 +174,8 @@ except SpanPanelAdapterMissingError as exc:
 # 2. Both packages: the adapter resolves through discovery
 python3 -m venv .both && ./.both/bin/pip install --pre span-panel-api span-panel-api-schema-0
 ./.both/bin/python -c "
-from span_panel_api.adapters import discover_adapters
-print('adapters:', sorted(discover_adapters()))
+from span_panel_api.adapters import installed_adapter_keys
+print('adapters:', installed_adapter_keys())
 "
 ```
 

{span_panel_api-3.0.0b2 → span_panel_api-3.0.0b3}/packages/schema-0/CHANGELOG.md

@@ -7,6 +7,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 Note that this package versions on the **library-API axis**, not the wire-format axis. The wire format it parses is fixed — the flat single-device schema, SPAN firmware `r202603` through `r202627` — and is identified by `SUPPORTS_DATA_MODEL_VERSIONS`
 rather than by this version number. A release here means this parser changed, never that the panel did.
 
+## [1.0.0b3] - 08/2026
+
+Pre-release. Requires `span-panel-api` 3.0.0b2 or newer — unchanged, because nothing added here reaches for anything newer.
+
+### Changed
+
+- **BREAKING — DER identity is translated into v1.0's vocabulary rather than mirroring flat's names.** `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
+  irregular side: 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 to preserve each entity's displayed meaning, which worked and permanently encoded flat's
+  irregularity in the snapshot. This adapter now normalises instead: `bess/model` → `part_number`, `bess/product-name` → `model`. **`battery.model` changes value for existing flat users at this upgrade.** Measured: every EVSE identity field now reads
+  identically on both adapters, so for that device class identity stops being a migration delta at all.
+
+### Added
+
+- **`dominant_power_source_payload`.** Flat already speaks this vocabulary, so the value passes through — the method exists because `schema_1` must translate, and a caller should not have to know which schema is underneath. Validated rather than passed
+  blindly: an unrecognised value returns `None` and the transport refuses the command, matching `schema_1` rather than putting a string outside the enum on the wire.
+
 ## [1.0.0b2] - 08/2026
 
 Pre-release. Follows the reshaped `SchemaAdapter` protocol released in `span-panel-api` 3.0.0b2.

{span_panel_api-3.0.0b2 → span_panel_api-3.0.0b3}/packages/schema-0/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api-schema-0"
-version = "1.0.0b2"
+version = "1.0.0b3"
 description = "Flat-schema (data-model-version absent) parser for span-panel-api"
 authors = [
     {name = "SpanPanel"}

{span_panel_api-3.0.0b2 → span_panel_api-3.0.0b3}/packages/schema-0/src/span_panel_api_schema_0/adapter.py

@@ -74,5 +74,22 @@ class SchemaZeroAdapter:
             return None
         return PROPERTY_SET_TOPIC_FMT.format(serial=self._serial_number, node=core_node, prop="dominant-power-source")
 
+    def dominant_power_source_payload(self, value: str) -> str | None:
+        """Flat speaks this vocabulary already, so the caller's value passes through.
+
+        The method exists because `schema_1` has to translate — its successor
+        property accepts `NONE`/`ON_GRID`/`OFF_GRID`, not a source class — and a
+        caller should not have to know which schema it is talking to. Here the
+        translation is the identity.
+
+        Validated rather than passed blindly: an unrecognised value returns None
+        and the transport refuses the command, which matches `schema_1`'s
+        behaviour and is better than putting a string outside the enum on the
+        wire.
+        """
+        allowed = {"GRID", "BATTERY", "PV", "GENERATOR", "NONE", "UNKNOWN"}
+        candidate = value.strip().upper()
+        return candidate if candidate in allowed else None
+
     def register_property_callback(self, callback: Callable[[str, str, str, str | None], None]) -> Callable[[], None]:
         return self._consumer.register_property_callback(callback)

{span_panel_api-3.0.0b2 → span_panel_api-3.0.0b3}/packages/schema-0/src/span_panel_api_schema_0/consumer.py

@@ -322,8 +322,12 @@ class HomieDeviceConsumer:
             soe_percentage=_parse_float(soc_str) if soc_str else None,
             soe_kwh=_parse_float(soe_str) if soe_str else None,
             vendor_name=vn if vn else None,
-            product_name=pn if pn else None,
-            model=mdl if mdl else None,
+            # Flat is the irregular side: it puts the SKU in `model` on the BESS and in
+            # `part-number` on the EVSE, for the same concept. The snapshot speaks v1.0's
+            # vocabulary now, so translate rather than mirror -- `product-name` is the
+            # designation and flat's `bess/model` is the SKU.
+            model=pn if pn else None,
+            part_number=mdl if mdl else None,
             serial_number=sn if sn else None,
             software_version=sw if sw else None,
             nameplate_capacity_kwh=_parse_float(nc) if nc else None,
@@ -344,7 +348,7 @@ class HomieDeviceConsumer:
 
         return SpanPVSnapshot(
             vendor_name=vn if vn else None,
-            product_name=pn if pn else None,
+            model=pn if pn else None,
             nameplate_capacity_w=_parse_float(nc) if nc else None,
             feed_circuit_id=normalize_circuit_id(feed) if feed else None,
             relative_position=rel_pos.upper() if rel_pos else None,
@@ -367,7 +371,7 @@ class HomieDeviceConsumer:
                 lock_state=self._acc.get_prop(node_id, "lock-state") or "UNKNOWN",
                 advertised_current_a=_parse_float(adv) if adv else None,
                 vendor_name=self._acc.get_prop(node_id, "vendor-name") or None,
-                product_name=self._acc.get_prop(node_id, "product-name") or None,
+                model=self._acc.get_prop(node_id, "product-name") or None,
                 part_number=self._acc.get_prop(node_id, "part-number") or None,
                 serial_number=self._acc.get_prop(node_id, "serial-number") or None,
                 software_version=self._acc.get_prop(node_id, "software-version") or None,

{span_panel_api-3.0.0b2 → span_panel_api-3.0.0b3}/packages/schema-0/src/span_panel_api_schema_0/field_metadata.py

@@ -82,8 +82,12 @@ _PROPERTY_FIELD_MAP: tuple[tuple[str, str, str], ...] = (
     (TYPE_BESS, "soc", "battery.soe_percentage"),
     (TYPE_BESS, "soe", "battery.soe_kwh"),
     (TYPE_BESS, "vendor-name", "battery.vendor_name"),
-    (TYPE_BESS, "product-name", "battery.product_name"),
-    (TYPE_BESS, "model", "battery.model"),
+    # Flat's irregularity, translated rather than mirrored: it puts the designation in
+    # `product-name` and the SKU in `model` on the BESS, where the EVSE puts the SKU in
+    # `part-number`. The snapshot speaks v1.0's vocabulary, so both land on the field
+    # that matches the concept.
+    (TYPE_BESS, "product-name", "battery.model"),
+    (TYPE_BESS, "model", "battery.part_number"),
     (TYPE_BESS, "serial-number", "battery.serial_number"),
     (TYPE_BESS, "software-version", "battery.software_version"),
     (TYPE_BESS, "nameplate-capacity", "battery.nameplate_capacity_kwh"),
@@ -91,7 +95,7 @@ _PROPERTY_FIELD_MAP: tuple[tuple[str, str, str], ...] = (
     (TYPE_BESS, "grid-state", "panel.grid_state"),
     # --- PV → pv.* -----------------------------------------------------------
     (TYPE_PV, "vendor-name", "pv.vendor_name"),
-    (TYPE_PV, "product-name", "pv.product_name"),
+    (TYPE_PV, "product-name", "pv.model"),
     (TYPE_PV, "nameplate-capacity", "pv.nameplate_capacity_w"),
     (TYPE_PV, "feed", "pv.feed_circuit_id"),
     (TYPE_PV, "relative-position", "pv.relative_position"),  # IN_PANEL | UPSTREAM | DOWNSTREAM
@@ -100,7 +104,7 @@ _PROPERTY_FIELD_MAP: tuple[tuple[str, str, str], ...] = (
     (TYPE_EVSE, "lock-state", "evse.lock_state"),
     (TYPE_EVSE, "advertised-current", "evse.advertised_current_a"),
     (TYPE_EVSE, "vendor-name", "evse.vendor_name"),
-    (TYPE_EVSE, "product-name", "evse.product_name"),
+    (TYPE_EVSE, "product-name", "evse.model"),
     (TYPE_EVSE, "part-number", "evse.part_number"),
     (TYPE_EVSE, "serial-number", "evse.serial_number"),
     (TYPE_EVSE, "software-version", "evse.software_version"),

span_panel_api-3.0.0b3/packages/schema-1/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+All notable changes to `span-panel-api-schema-1` are 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).
+
+Note that this package versions on the **library-API axis**, not the wire-format axis. The wire format it parses is the parent/child device tree SPAN firmware `r202633+` publishes, identified by `SUPPORTS_DATA_MODEL_VERSIONS` rather than by this version
+number. A release here means this parser changed, never that the panel did.
+
+## [0.1.0b3] - 08/2026
+
+Pre-release. **Requires `span-panel-api` 3.0.0b3 or newer** — see Fixed.
+
+### Added
+
+- **Spec conformance checking.** `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. It is the consumer counterpart to the simulator's publisher lockfile, and both are pinned to the same specification commit — though the anchor shared between them is the **firmware range**, not that commit, because the specification says what
+  a device class _may_ publish while a panel publishes one specific tree.
+- **The 13 capability catalogs this adapter addresses**, byte-copied under `spec/` along with the device-types registry. Vendored rather than depended on because the specification is a git repository of versioned documents, not a package. They exist to be
+  checked against, never parsed in production: units and datatypes still come from each device's `$description`, since the catalog is the superset across all hardware rather than a statement about the panel in front of us. Formatting hooks are excluded
+  from `spec/`, because a lint fix there would quietly invalidate the byte comparison that makes the copies worth having.
+- **`tests/test_schema_one_conformance.py`**, which asks the consumer's question rather than the publisher's. A publisher asks whether everything it emits is legal, and for it an omission is unremarkable. This asks whether every name the adapter _reads_ is
+  one the specification defines — because a consumer addressing a name that no longer exists does not fail, it goes quiet: the property never arrives, metadata lookup returns `None`, and an entity disappears. `ebus-sdk` 0.18.0 removing the `battery`
+  capability key in favour of `soc`, with no alias, is exactly that shape.
+- **An explicit SPAN extension allowlist.** Fourteen of the forty-two properties this adapter reads are absent from every catalog — per-phase meter readings, panel link states, circuit `spaces`, the EVSE surface. All are legal, since the specification
+  permits properties it has never heard of. They are enumerated with reasons so that a name missing from the catalog must be a deliberate claim about SPAN's vocabulary rather than an unnoticed typo; at runtime the two are indistinguishable. Tests also fail
+  when an extension is later adopted upstream, or when one is declared for a property nothing reads.
+- **A peer record and simulator coverage check.** `spec_lock.json` now records the producer this parser is developed against — the SPAN simulator, `role: publisher` — with the specification commit and firmware range it pins, and a captured copy of the tree
+  it publishes is vendored alongside the catalogs. Two sides reading different vocabularies is now a test failure rather than something noticed later, and the anchor asserted between them is the **firmware range**, since the specification says what a
+  device class may publish while a panel publishes one specific tree.
+- **An explicit record of what the producer does not exercise.** Of the 42 `(capability, property)` pairs this adapter reads, the simulator's captured tree declares 41. The exception is `grid/islanding-state`: the simulator models a MID but its tracked
+  config publishes none, so `grid_state` — corrected in `0.1.0b2` to read `islanding-state` rather than `grid-state` — is the single mapping the producer gives no evidence for. Recorded rather than left implicit, because a passing suite otherwise reads as
+  coverage it does not have. The entry is rejected once the simulator starts publishing it.
+- **The parser is now driven end to end from what the producer actually publishes.** Every other test in this package runs on a fixture captured off the upstream _generic_ eBus panel simulator, which by construction never carries SPAN's own vocabulary.
+  `spec/fixtures/simulator_wire.json` is a capture from SPAN's publisher instead — descriptions, `$state` and all 494 property values across 37 devices — fed in sorted topic order, the way a retained store replays it rather than the way a tree is walked.
+  The parser reaches ready on it, sizes the panel from `MAIN_40`, and parses all 30 circuits. Values are deliberately not asserted: the producer's config carries `noise_factor` and its clock advances, so pinning a wattage would fail on every recapture for
+  a reason nobody could act on.
+- **Two producer-side gaps are pinned rather than left to be noticed.** `grid_state` stays `None` because nothing instantiates a MID, and every DER — BESS, PV and both EVSEs — declares `info/model` in its `$description` and never publishes a value (PV
+  declares five `info` properties and publishes one). The second breaks the single standing obligation eBus places on a publisher, to declare accurately what it publishes, and is invisible to a conformance checker: comparing declarations against catalogs
+  cannot see a declaration nothing fulfils. Only a capture carrying values can, which is the argument for this fixture existing. Both are asserted as current expectations, so closing either fails the test that describes it.
+
+Provenance (byte comparison against a specification or simulator checkout) is skipped unless `EBUS_SPEC_DIR` / `PANELBENCH_DIR` are set, so conformance and coverage run everywhere while the byte checks stay opportunistic. The wire capture is compared on
+shape rather than bytes for the same reason its values are not asserted. Provenance proves the right bytes were copied; it cannot prove they were understood, which is what the other two are for.
+
+### Fixed
+
+- **The conformance check was reading the wrong set of names.** Built from `_PROPERTY_FIELD_MAP` alone, it covered only properties that carry field metadata and silently skipped everything the snapshot mapper reads directly — the MID, `connection`
+  feeds/fed-by, `info/direction`. `grid_state`, the most recently corrected mapping in this package, was among them. The read set is now derived from the source itself, so it cannot fall behind the code; that immediately surfaced `info/direction` as a
+  fifteenth undeclared extension.
+- **The bootstrap floor is raised to 3.0.0b3**, which is where it should always have been: this parser imports `SpanMidSnapshot`, and 3.0.0b2 does not define it. The declared `>=3.0.0b2` let a resolver pair this wheel with 3.0.0b2 and fail on import.
+  Caught before the first release that would have shipped it. `schema-0` keeps its b2 floor; every name it imports is present there, checked rather than assumed.
+
+## [0.1.0b2] - 08/2026
+
+Pre-release. Corrects the dependency floor `0.1.0b1` shipped with, and follows the reshaped `SchemaAdapter` protocol released in `span-panel-api` 3.0.0b2.
+
+### Added
+
+- **`ADAPTER_CONTRACT = 1`**, declaring which version of the bootstrap-to-adapter contract this parser was built against. Declared as a literal rather than imported from `span_panel_api.protocol`: a value read from the installed bootstrap would agree with
+  every bootstrap, which is exactly the disagreement the check exists to find.
+
+### Fixed
+
+- **The `span-panel-api` floor was `>=3.0.0b1`, which no published bootstrap could satisfy in practice.** `0.1.0b1` was built against a bootstrap that reads the panel's `data-model-version` and constructs adapters with the whole schema; the only bootstrap
+  on PyPI at the time did neither. Its `V2HomieSchema` had no `data_model_version` field at all, so a `1.x` panel could not even be represented, and its factory hardcoded the version to `None` — meaning this adapter was discoverable and never selectable.
+  The floor is now `>=3.0.0b2`, the first release where both hold. Nothing was installed against the old floor; the combination was unreachable rather than broken in the field.
+
+## [0.1.0b1] - 08/2026
+
+Pre-release. First release as a standalone distribution, and the first parser for the parent/child data model.
+
+### Added
+
+- **`SchemaOneAdapter`**, registered as `schema_1` under the `span_panel_api.schema_adapters` entry-point group. A panel reporting `data-model-version` `1.x` resolves to it; a panel without this package installed still gets the named
+  `SpanPanelAdapterMissingError`, so installing it is the opt-in.
+- **`ControllerRoutes`** — an `ebus_sdk.MqttControllerTransport` that records `Controller`'s subscriptions instead of making them, so the SDK parses the tree over span-panel-api's own connection to the panel's broker. The adapter is built before a
+  connection exists and never receives one; a single wildcard subscription made by the transport layer covers the whole tree, and this routes each message to whichever SDK callback asked for it.
+- **The snapshot mapper.** Sorts the tree by declared device type — never by device id — and maps it onto `SpanPanelSnapshot`: circuits, both lugs, the MID, and the BESS/PV/EVSE devices.
+- **Panel size from `info/model`** via `PANEL_SIZE_BY_MODEL`, which is what restores the unmapped-position entries the integration builds from the difference between total and occupied spaces. `info/spaces` has no format and the panel publishes no size
+  property, so the model is the only source; `panel_model_drift()` reports a model the panel declares that we have no size for, because the alternative is a user noticing missing positions.
+- **Field metadata read from each device's `$description`** rather than a schema document. The same capability type exposes different properties on different device classes — `meter` is voltage on the panel, power and energy on a circuit, both currents on
+  lugs — so the per-device description is what this panel actually has.
+- **A `py.typed` marker**, so consumers type-check against this package's real annotations.
+
+### Known deviations and deliberate gaps
+
+- **`set_dominant_power_source_topic()` returns `None`.** The v1.0 property split into `grid-forming-entity` and `asserted-islanding-state`, which are different controls on different devices rather than a rename. `None` makes the transport reject the
+  command instead of publishing where nothing listens; which successor to expose is a product decision.
+- **`dsm_state`, `current_run_config`, `grid_islandable` and `pv.relative_position`** have no direct v1.0 equivalent and are left to the product decisions tracked separately. Fields the mapper declines carry no metadata row, so the integration never
+  validates against a field nothing populates.
+
+### Fixed before first release
+
+Both found by verifying reconnect against a live broker, and both presented as a healthy connection.
+
+- **Messages arriving before the SDK registered a route for them were dropped.** `Controller` learns its topics as it walks the tree, but one subscription delivers the whole tree at once in whatever order the broker replays its retained store. Seeded
+  children-first, a 40-space panel parsed as zero circuits. Unrouted messages are now held and released when the matching route appears — the value a per-device subscription would have been given at subscribe time — with a ceiling so an unclaimed subtree
+  cannot leak.
+- **Readiness asked only about the root**, so a connection completed with a fraction of its circuits and no panel size. It now waits for every declared device to describe itself, at any depth. Child _state_ is deliberately not required, so an offline DER
+  does not block a connection; the model is required only when the root's description declares it.
+- **`grid_state` read the wrong one of the MID's two grid properties.** The MID publishes both `grid/islanding-state` (`ON_GRID`/`OFF_GRID`/`UNKNOWN`) and `grid/grid-state` (`UP`/`DOWN`/`DEGRADED`/`UNKNOWN`). The flat schema's `grid_state` was the BESS's
+  `grid-state`, an islanding answer, so its successor is `islanding-state`; `grid/grid-state` asks whether the utility supply is healthy and is new in v1.0 with no flat equivalent. Matching on the property name rather than the value set put `UP` where a
+  consumer expects `ON_GRID` — an entity keeping its id and history while its vocabulary silently changed. `grid/grid-state` is left unmapped, being a new signal rather than a replacement for an existing field.

{span_panel_api-3.0.0b2 → span_panel_api-3.0.0b3}/packages/schema-1/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api-schema-1"
-version = "0.1.0b2"
+version = "0.1.0b3"
 description = "Parent/child schema (data-model-version 1.x) parser for span-panel-api"
 authors = [
     {name = "SpanPanel"}
@@ -9,12 +9,17 @@ readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10,<4.0"
 dependencies = [
-    "span-panel-api>=3.0.0b2,<4.0",
+    # b3, not b2: this parser imports `SpanMidSnapshot`, which 3.0.0b2 does not
+    # define. A `>=3.0.0b2` floor lets a resolver pair this wheel with 3.0.0b2 and
+    # fail on import -- the precise hazard RELEASE.md warns about under "Releasing
+    # every distribution". schema-0 keeps its b2 floor; every name it imports is
+    # present there, checked rather than assumed.
+    "span-panel-api>=3.0.0b3,<4.0",
     # Only this distribution depends on the eBus SDK. The bootstrap and
     # schema-0 stay clean, so a flat-panel install never pulls it in — which is
     # what bounds the release coupling this dependency introduces to panels on
     # r202633+.
-    "ebus-sdk>=0.18.0,<1.0",
+    "ebus-sdk>=0.19.0,<1.0",
 ]
 
 [project.urls]

span_panel_api-3.0.0b3/packages/schema-1/spec/catalogs/breaker.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://ebus.energy/schemas/property-catalog.json",
+  "schema_version": "property-schema-v1",
+  "kind": "capability-catalog",
+  "capability": "energy.ebus.capability.breaker",
+  "version": "0.1",
+  "status": "DRAFT",
+  "date": "2026-07-11",
+  "properties": {
+    "rating": {
+      "datatype": "integer",
+      "unit": "A",
+      "req": "SHOULD",
+      "description": "Continuous current rating."
+    },
+    "poles": {
+      "datatype": "integer",
+      "req": "MAY",
+      "description": "Number of poles (1-4). A US split-phase 240 V breaker is `2`."
+    },
+    "interrupting-rating": {
+      "datatype": "integer",
+      "unit": "kA",
+      "req": "MAY",
+      "description": "Interrupting capacity (kAIC), e.g. `10`, `65`, `100`."
+    },
+    "protection-functions": {
+      "datatype": "enum",
+      "format": "OVERCURRENT,SHORT_CIRCUIT,GROUND_FAULT,ARC_FAULT",
+      "req": "MAY",
+      "description": "Multi-valued set of the protections this breaker provides: `OVERCURRENT`, `SHORT_CIRCUIT`, `GROUND_FAULT` (GFCI), `ARC_FAULT` (AFCI)."
+    },
+    "trip-curve": {
+      "datatype": "enum",
+      "format": "B,C,D,K",
+      "req": "MAY",
+      "description": "Instantaneous trip curve: `B`, `C`, `D`, `K`, …"
+    },
+    "trip-state": {
+      "datatype": "enum",
+      "format": "OK,TRIPPED,STUCK,UNKNOWN,CLOSED",
+      "req": "SHOULD",
+      "description": "`OK`, `TRIPPED`, `STUCK`, `UNKNOWN`. A tripped breaker carries no current even if a co-located `switch/relay` reads `CLOSED`, so `trip-state` is not a relay state."
+    },
+    "trip-cause": {
+      "datatype": "enum",
+      "format": "OVERCURRENT,SHORT_CIRCUIT,GROUND_FAULT,ARC_FAULT,OVERVOLTAGE,UNKNOWN",
+      "req": "MAY",
+      "description": "Cause of the most recent trip: `OVERCURRENT`, `SHORT_CIRCUIT`, `GROUND_FAULT`, `ARC_FAULT`, `OVERVOLTAGE`, `UNKNOWN`."
+    }
+  }
+}

span_panel_api-3.0.0b3/packages/schema-1/spec/catalogs/connection.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://ebus.energy/schemas/property-catalog.json",
+  "schema_version": "property-schema-v1",
+  "kind": "capability-catalog",
+  "capability": "energy.ebus.capability.connection",
+  "version": "0.1",
+  "status": "DRAFT",
+  "date": "2026-07-05",
+  "properties": {
+    "feeds-device-id": {
+      "datatype": "string",
+      "req": "MAY",
+      "description": "Homie device ID of the device wired *downstream* of this connection point. Published only when the specific downstream device is known. Omitted when unknown, when mixed-load with no commissioned downstream device, or when nothing is connected."
+    },
+    "feeds-device-type": {
+      "datatype": "string",
+      "req": "MAY",
+      "description": "`$description.type` of the downstream device (e.g. `energy.ebus.device.bess`, `.pv`, `.evse`, `.water-heater`, `.distribution-enclosure`, or a DER sub-device such as `.battery`). Published when the class is known even if the specific ID is not."
+    },
+    "feeds-device-status": {
+      "datatype": "enum",
+      "format": "OK,LOST,DEGRADED",
+      "req": "MAY",
+      "description": "Publisher's view of communication-link health to the downstream device: `OK`, `LOST`, `DEGRADED`. Published only when `feeds-device-id` is published and the publisher has a communication integration with that device."
+    },
+    "fed-by-device-id": {
+      "datatype": "string",
+      "req": "MAY",
+      "description": "Homie device ID of the device wired *upstream* of this connection point. Published only when known (e.g. an upstream BESS wired between the utility and the enclosure, or an upstream sister enclosure in a chain). Omitted when the upstream side is the utility, an implicit busbar, or unknown."
+    },
+    "fed-by-device-type": {
+      "datatype": "string",
+      "req": "MAY",
+      "description": "`$description.type` of the upstream device. Published with `fed-by-device-id`."
+    },
+    "fed-by-device-status": {
+      "datatype": "enum",
+      "format": "OK,LOST,DEGRADED",
+      "req": "MAY",
+      "description": "Publisher's view of communication-link health to the upstream device. Same value domain and applicability as `feeds-device-status`."
+    },
+    "backed-up": {
+      "datatype": "enum",
+      "format": "BACKED_UP,NOT_BACKED_UP,UNKNOWN",
+      "req": "MAY",
+      "description": "Whether this path is on the backup (island) side of a microgrid interconnect device, and so stays energized off-grid: `BACKED_UP`, `NOT_BACKED_UP`, `UNKNOWN`. A wiring fact (which side of the interconnect), distinct from `load-shed/priority` (a shedding *policy*) and `grid/islanding-state` (the present *state*)."
+    },
+    "feeds-role": {
+      "datatype": "enum",
+      "format": "LOADS,SUBPANEL,SOLAR,STORAGE,GENERATOR,MIXED,UNUSED",
+      "req": "MAY",
+      "description": "Summary role of a downstream node that is **not** published as its own eBus device, or that is surveyed-empty: `LOADS`, `SUBPANEL`, `SOLAR`, `STORAGE`, `GENERATOR`, `MIXED`, `UNUSED`. `UNUSED` positively records \"surveyed, nothing connected\" (which absence cannot express). Complements `feeds-device-*`, which is used when the downstream *is* an eBus device."
+    },
+    "service-rating": {
+      "datatype": "integer",
+      "unit": "A",
+      "req": "MAY",
+      "description": "Utility service rating (service size) at a service-entrance connection point. Distinct from `pcs/feed-import-limit` (a PCS enforcement limit) and `breaker/rating` (a main breaker)."
+    },
+    "overcurrent-protection": {
+      "datatype": "integer",
+      "unit": "A",
+      "req": "MAY",
+      "description": "Overcurrent-protection rating at a connection point that is not itself a breaker-protected circuit (for example a feeder conductor landing in unprotected lugs). Where the connection point *is* a breaker-protected circuit, the rating is `breaker/rating` instead."
+    },
+    "count": {
+      "datatype": "integer",
+      "req": "MAY",
+      "description": "When the connected node aggregates multiple physical units behind a *single* connection point (e.g. 6 battery packs in one BESS, or 4 microinverters on one AC string reported as one solar device), how many."
+    }
+  }
+}