span-panel-api-schema-0 1.0.0__tar.gz

span_panel_api_schema_0-1.0.0/.gitignore

@@ -0,0 +1,47 @@
+__pycache__/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.cursor/
+.cursorignore
+.cursor
+.cursorindexingignore
+xnotes/*
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.envrc
+.venv
+.vscode/settings.json
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# JetBrains
+.idea/
+
+/coverage.xml
+/.coverage
+coverage_output.log
+**/.DS_Store
+.local_coverage_data
+
+# Captures taken from a real panel. These carry the panel's serial (which is also
+# its MQTT username), the household's circuit names, and real consumption — none
+# of which belongs in a repository. The differential that reads them commits its
+# *verdict* only, never the capture, and skips when the file is absent.
+tests/fixtures/live_*.json
+
+# Peer checkouts. CI clones the eBus specification and SpanPanel/panelbench here so
+# the provenance checks have something to compare vendored bytes against; the same
+# layout works locally if you would rather not point .env at siblings.
+/peers/

span_panel_api_schema_0-1.0.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to `span-panel-api-schema-0` 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 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.
+
+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.0.0]
+
+First release as a standalone distribution. Requires `span-panel-api` 3.0.0 or newer.
+
+### Added
+
+- **The flat-schema parser, extracted from `span-panel-api` 2.6.4.** Relocated from `span_panel_api._impl.schema_0` to `span_panel_api_schema_0`, and registered as `schema_0` under the `span_panel_api.schema_adapters` entry-point group, which is the only
+  way `span-panel-api` reaches it — the bootstrap never imports this package. Installing it is what makes flat-schema panels work; `span-panel-api` alone connects and then raises `SpanPanelAdapterMissingError` naming the adapter it could not find.
+- **`HomieLifecycle`, `HomiePropertyAccumulator` and `HomieDeviceConsumer` live here now.** All three left the bootstrap because they are flat-schema-specific rather than Homie-convention-level: the accumulator filters every topic against a single device's
+  prefix and stores `node → prop`, and `HomieLifecycle`'s members are not Homie 5 `$state` values but a consumer-side progression encoding "one description received ⇒ ready".
+- **`SCHEMA_ANCHOR`** (`sha256:d347556a07d98f40`, firmware `spanos2/r202603/05`) — the schema revision every hardcoded fact in this package was read from, with `SCHEMA_ANCHOR_FIELD` naming the field it comes from (`typesSchemaHash`). The field is
+  per-adapter: parent/child firmware renames it to `deviceClassesSchemaHash` along with the block it covers, so `schema_1` declares its own rather than inheriting one that does not exist on its firmware.
+- **`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.
+- **`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.
+- **`set_evse_charge_limit_topic` and `evse_charge_limit_payload`.** Both are required of every adapter, because `_derive_required_members` makes each public protocol member mandatory of every adapter wheel — an adapter without them is rejected at
+  discovery no matter which panel it would have parsed. Flat firmware publishes no charge-limit surface, so this distribution answers for the absence rather than for a topic; the point is that answering is not optional.
+- **`adopted_devices` reports empty.** Adoption is a parent/child idea: a flat panel is one device with no unmodelled children to adopt, so the honest answer is a stable empty tuple rather than an unimplemented member. `set_adopted_property` therefore
+  raises on a flat panel for the same reason it raises for a device that does not exist, which is what makes the snapshot lookup an authorization rather than a lookup.
+- **Panel size is derived here**, by reading the circuit `space` format out of the flat schema's `types` block — knowledge that belongs to this package rather than to the transport, which previously did it on every adapter's behalf.
+- **Provenance tests** asserting that all 64 hardcoded `(node_type, property_id)` pairs still resolve against the captured schema, that `HOMIE_DOMAIN` / `HOMIE_VERSION` still match it, and that the two lugs subtypes real firmware publishes remain absent
+  from the schema _and_ present in the metadata alias table. This is the only signal that catches schema drift before release; every other symptom reaches production as a silent absence.
+- **A `py.typed` marker**, so consumers type-check against this package's real annotations rather than resolving everything it exports as `Any`.
+
+### Changed
+
+- **BREAKING — DER identity is translated into the parent/child 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. Mirroring that would have permanently encoded flat's irregularity in the snapshot, so this adapter 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.
+
+### Known deviations from the published schema
+
+- **Circuit `active-power` is treated as watts, though the schema declares kilowatts.** Real panels publish watts; this was established against live hardware and the 1000× correction was removed accordingly. A test asserts the schema still says `kW`, so
+  the day SPAN corrects it we find out rather than discovering it as a factor-of-1000 error.
+- **`energy.ebus.device.lugs.upstream` / `.downstream` are parsed but undeclared.** Firmware publishes these node types in `$description`; the schema declares only the base `energy.ebus.device.lugs`. Property metadata for them resolves through an alias to
+  the base type.
+
+### Retirement
+
+SPAN retires the flat schema in the same firmware release that introduces the parent/child model (`r202633`; fleet rollout projected, not committed, for the first two weeks of September 2026). This package stops being published once the fleet has moved.
+Published versions remain on PyPI for anyone still running older firmware.

span_panel_api_schema_0-1.0.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.5
+Name: span-panel-api-schema-0
+Version: 1.0.0
+Summary: Flat-schema (data-model-version absent) 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
+Author: SpanPanel
+License-Expression: MIT
+Requires-Python: <4.0,>=3.14
+Requires-Dist: span-panel-api<4.0,>=3.0.0
+Description-Content-Type: text/markdown
+
+# span-panel-api-schema-0
+
+The **flat-schema** parser for [`span-panel-api`](https://github.com/SpanPanel/span-panel-api): the single-device Homie model published by SPAN firmware `r202603` through `r202627`, which carries no `data-model-version`.
+
+## Why this is a separate distribution
+
+`span-panel-api` is a transport and a dispatcher. It knows how to connect to a panel's MQTT broker, route messages, and choose a parser — but it contains no parsing code and no Homie type strings. Each wire format ships as its own distribution and
+registers itself under the `span_panel_api.schema_adapters` entry-point group.
+
+That split exists because the two halves break on different axes. The wire format changes when SPAN ships firmware; the library API changes when we do. Separate distributions let each carry its own version, so a consumer can pin them independently and add
+support for a new panel schema by installing a package rather than by upgrading the transport.
+
+## Installation
+
+```console
+pip install "span-panel-api[schema-0]"
+```
+
+Installing this package is what makes flat-schema panels work. `span-panel-api` on its own will connect and then raise `SpanPanelAdapterMissingError` naming the adapter it could not find.
+
+A consumer that wants to support panels on either schema installs both adapters:
+
+```console
+pip install "span-panel-api[schema-0,schema-1]"
+```
+
+Dispatch happens at runtime, per panel, from the `data-model-version` the panel reports. The extras are the recommended spelling because they give `pip install -U` a correct upgrade path — the dependency arrow runs from adapter to bootstrap, so upgrading
+the bootstrap alone would otherwise leave a stale adapter wheel that discovery then rejects, with pip reporting success. Naming the distributions directly works too.
+
+## Retirement
+
+SPAN retires the flat schema in the same release that introduces the parent/child model (`r202633`, fleet rollout projected for early September 2026). When the fleet has moved, consumers drop this package from their requirements. Published versions stay on
+PyPI for anyone still running older firmware.

span_panel_api_schema_0-1.0.0/README.md

@@ -0,0 +1,33 @@
+# span-panel-api-schema-0
+
+The **flat-schema** parser for [`span-panel-api`](https://github.com/SpanPanel/span-panel-api): the single-device Homie model published by SPAN firmware `r202603` through `r202627`, which carries no `data-model-version`.
+
+## Why this is a separate distribution
+
+`span-panel-api` is a transport and a dispatcher. It knows how to connect to a panel's MQTT broker, route messages, and choose a parser — but it contains no parsing code and no Homie type strings. Each wire format ships as its own distribution and
+registers itself under the `span_panel_api.schema_adapters` entry-point group.
+
+That split exists because the two halves break on different axes. The wire format changes when SPAN ships firmware; the library API changes when we do. Separate distributions let each carry its own version, so a consumer can pin them independently and add
+support for a new panel schema by installing a package rather than by upgrading the transport.
+
+## Installation
+
+```console
+pip install "span-panel-api[schema-0]"
+```
+
+Installing this package is what makes flat-schema panels work. `span-panel-api` on its own will connect and then raise `SpanPanelAdapterMissingError` naming the adapter it could not find.
+
+A consumer that wants to support panels on either schema installs both adapters:
+
+```console
+pip install "span-panel-api[schema-0,schema-1]"
+```
+
+Dispatch happens at runtime, per panel, from the `data-model-version` the panel reports. The extras are the recommended spelling because they give `pip install -U` a correct upgrade path — the dependency arrow runs from adapter to bootstrap, so upgrading
+the bootstrap alone would otherwise leave a stale adapter wheel that discovery then rejects, with pip reporting success. Naming the distributions directly works too.
+
+## Retirement
+
+SPAN retires the flat schema in the same release that introduces the parent/child model (`r202633`, fleet rollout projected for early September 2026). When the fleet has moved, consumers drop this package from their requirements. Published versions stay on
+PyPI for anyone still running older firmware.

span_panel_api_schema_0-1.0.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "span-panel-api-schema-0"
+version = "1.0.0"
+description = "Flat-schema (data-model-version absent) parser for span-panel-api"
+authors = [
+    {name = "SpanPanel"}
+]
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14,<4.0"
+dependencies = [
+    # Stated as a stable version rather than as the prerelease the floor tracked
+    # during development: naming a prerelease in a specifier is pip's own signal
+    # that prereleases are acceptable for that requirement.
+    "span-panel-api>=3.0.0,<4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/SpanPanel/span-panel-api"
+Issues = "https://github.com/SpanPanel/span-panel-api/issues"
+
+# The whole point of this distribution. The bootstrap finds this adapter by
+# discovering the group, never by importing this package.
+[project.entry-points."span_panel_api.schema_adapters"]
+schema_0 = "span_panel_api_schema_0:SchemaZeroAdapter"
+
+# Resolve the bootstrap from the workspace when developing here. Published
+# wheels are unaffected: this table is uv-only metadata and the dependency
+# above is what a consumer installing from PyPI sees.
+[tool.uv.sources]
+span-panel-api = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/span_panel_api_schema_0"]

span_panel_api_schema_0-1.0.0/src/span_panel_api_schema_0/__init__.py

@@ -0,0 +1,11 @@
+"""Flat-schema adapter package (data-model-version absent)."""
+
+from span_panel_api_schema_0.adapter import SchemaZeroAdapter
+
+# Re-exported from the adapter rather than restated. The protocol requires the
+# range as a class attribute, so the class is the source of truth; a second
+# literal here would be free to drift, and nothing would notice until a panel
+# reported a version this adapter claims — falsely — to support.
+SUPPORTS_DATA_MODEL_VERSIONS: tuple[str, str] = SchemaZeroAdapter.SUPPORTS_DATA_MODEL_VERSIONS
+
+__all__ = ["SUPPORTS_DATA_MODEL_VERSIONS", "SchemaZeroAdapter"]

span_panel_api_schema_0-1.0.0/src/span_panel_api_schema_0/accumulator.py

@@ -0,0 +1,274 @@
+"""Homie v5 property accumulator with lifecycle state machine.
+
+Generic Homie protocol layer that knows nothing about SPAN-specific
+concepts. Stores property values, tracks lifecycle, and exposes a
+query API for higher-level consumers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+import enum
+import json
+import logging
+import time
+
+from span_panel_api.mqtt.const import HOMIE_STATE_DISCONNECTED, HOMIE_STATE_LOST, HOMIE_STATE_READY
+from span_panel_api_schema_0.const import TOPIC_PREFIX
+
+_LOGGER = logging.getLogger(__name__)
+
+# Callback signature: (node_id, prop_id, value, old_value)
+PropertyCallback = Callable[[str, str, str, str | None], None]
+
+
+class HomieLifecycle(enum.Enum):
+    """Homie device lifecycle states."""
+
+    DISCONNECTED = "disconnected"
+    CONNECTED = "connected"
+    DESCRIPTION_RECEIVED = "description_received"
+    READY = "ready"
+
+
+class HomiePropertyAccumulator:
+    """Accumulate Homie v5 property values and track device lifecycle.
+
+    Topic prefix: ``ebus/5/{serial_number}``
+
+    All methods must be called from the asyncio event loop thread.
+    """
+
+    def __init__(self, serial_number: str) -> None:
+        self._serial_number = serial_number
+        self._topic_prefix = f"{TOPIC_PREFIX}/{serial_number}"
+
+        # Lifecycle
+        self._lifecycle = HomieLifecycle.DISCONNECTED
+        self._received_state_ready = False
+        self._received_description = False
+        self._ready_since: float = 0.0
+
+        # Property storage
+        self._property_values: dict[str, dict[str, str]] = {}
+        self._property_timestamps: dict[str, dict[str, int]] = {}
+        self._target_values: dict[str, dict[str, str]] = {}
+
+        # Node type mapping from $description
+        self._node_types: dict[str, str] = {}
+
+        # Dirty tracking
+        self._dirty_nodes: set[str] = set()
+
+        # Callbacks
+        self._property_callbacks: list[PropertyCallback] = []
+
+    # -- Public properties ---------------------------------------------------
+
+    @property
+    def serial_number(self) -> str:
+        """Serial number this accumulator tracks."""
+        return self._serial_number
+
+    @property
+    def lifecycle(self) -> HomieLifecycle:
+        """Current lifecycle state."""
+        return self._lifecycle
+
+    @property
+    def ready_since(self) -> float:
+        """Monotonic timestamp of the last READY transition, 0.0 if never ready."""
+        return self._ready_since
+
+    def is_ready(self) -> bool:
+        """True when lifecycle is READY."""
+        return self._lifecycle == HomieLifecycle.READY
+
+    # -- Message routing -----------------------------------------------------
+
+    def handle_message(self, topic: str, payload: str) -> None:
+        """Route an MQTT message to the appropriate handler."""
+        prefix_with_sep = f"{self._topic_prefix}/"
+        if not topic.startswith(prefix_with_sep):
+            return
+
+        suffix = topic[len(prefix_with_sep) :]
+
+        if suffix == "$state":
+            self._handle_state(payload)
+        elif suffix == "$description":
+            self._handle_description(payload)
+        elif suffix.endswith("/set"):
+            return  # ignore /set topics
+        elif "/" in suffix:
+            parts = suffix.split("/", 1)
+            node_id = parts[0]
+            prop_part = parts[1]
+            if prop_part.endswith("/$target"):
+                # Target value: {node_id}/{prop_id}/$target
+                prop_id = prop_part[: -len("/$target")]
+                self._handle_target(node_id, prop_id, payload)
+            else:
+                # Reported value: {node_id}/{prop_id}
+                self._handle_property(node_id, prop_part, payload)
+
+    # -- Query API -----------------------------------------------------------
+
+    def get_prop(self, node_id: str, prop_id: str, default: str = "") -> str:
+        """Get a property's reported value."""
+        return self._property_values.get(node_id, {}).get(prop_id, default)
+
+    def get_timestamp(self, node_id: str, prop_id: str) -> int:
+        """Get the epoch timestamp of a property's last update."""
+        return self._property_timestamps.get(node_id, {}).get(prop_id, 0)
+
+    def get_target(self, node_id: str, prop_id: str) -> str | None:
+        """Get a property's target value, or None if no target set."""
+        return self._target_values.get(node_id, {}).get(prop_id)
+
+    def has_target(self, node_id: str, prop_id: str) -> bool:
+        """True if a target value exists for the given property."""
+        return prop_id in self._target_values.get(node_id, {})
+
+    def find_node_by_type(self, type_str: str) -> str | None:
+        """Find the first node ID matching a given type string."""
+        for node_id, node_type in self._node_types.items():
+            if node_type == type_str:
+                return node_id
+        return None
+
+    def nodes_by_type(self, type_str: str) -> list[str]:
+        """Return all node IDs matching a given type string."""
+        return [nid for nid, ntype in self._node_types.items() if ntype == type_str]
+
+    def get_node_type(self, node_id: str) -> str:
+        """Get the type string for a node, or empty string if unknown."""
+        return self._node_types.get(node_id, "")
+
+    def all_node_types(self) -> dict[str, str]:
+        """Return a copy of the node_id → type mapping."""
+        return dict(self._node_types)
+
+    def dirty_node_ids(self) -> frozenset[str]:
+        """Return the set of node IDs with changed properties since last mark_clean."""
+        return frozenset(self._dirty_nodes)
+
+    def mark_clean(self) -> None:
+        """Clear the dirty set."""
+        self._dirty_nodes.clear()
+
+    def register_property_callback(self, callback: PropertyCallback) -> Callable[[], None]:
+        """Register a callback fired on property value changes.
+
+        Callback signature: (node_id, prop_id, new_value, old_value).
+        Only fires when the value actually changes, not on every message.
+
+        Returns an unregister function.
+        """
+        self._property_callbacks.append(callback)
+
+        def unregister() -> None:
+            try:
+                self._property_callbacks.remove(callback)
+            except ValueError:
+                _LOGGER.debug("Callback already unregistered")
+
+        return unregister
+
+    # -- Internal handlers ---------------------------------------------------
+
+    def _handle_state(self, payload: str) -> None:
+        """Handle $state topic and drive lifecycle transitions."""
+        if payload == HOMIE_STATE_READY:
+            self._received_state_ready = True
+            if self._received_description:
+                self._transition_to_ready()
+            else:
+                # State ready but no description yet
+                if self._lifecycle == HomieLifecycle.DISCONNECTED:
+                    self._lifecycle = HomieLifecycle.CONNECTED
+        elif payload in (HOMIE_STATE_DISCONNECTED, HOMIE_STATE_LOST):
+            self._lifecycle = HomieLifecycle.DISCONNECTED
+            self._received_state_ready = False
+            self._received_description = False
+        else:
+            # init, sleeping, alert, etc. — connected but not ready
+            if self._lifecycle == HomieLifecycle.DISCONNECTED:
+                self._lifecycle = HomieLifecycle.CONNECTED
+            self._received_state_ready = False
+
+        _LOGGER.debug("Homie $state: %s → lifecycle=%s", payload, self._lifecycle.value)
+
+    def _handle_description(self, payload: str) -> None:
+        """Parse $description JSON and extract node type mappings."""
+        try:
+            desc = json.loads(payload)
+        except json.JSONDecodeError:
+            _LOGGER.warning("Invalid $description JSON")
+            return
+
+        self._received_description = True
+        self._node_types.clear()
+
+        nodes = desc.get("nodes", {})
+        if isinstance(nodes, dict):
+            for node_id, node_def in nodes.items():
+                if isinstance(node_def, dict):
+                    node_type = node_def.get("type", "")
+                    if isinstance(node_type, str):
+                        self._node_types[str(node_id)] = node_type
+
+        # Mark all known nodes dirty
+        self._dirty_nodes.update(self._node_types.keys())
+
+        _LOGGER.debug("Parsed $description with %d nodes", len(self._node_types))
+
+        # Lifecycle transition
+        if self._received_state_ready:
+            self._transition_to_ready()
+        elif self._lifecycle in (HomieLifecycle.DISCONNECTED, HomieLifecycle.CONNECTED):
+            self._lifecycle = HomieLifecycle.DESCRIPTION_RECEIVED
+
+    def _handle_property(self, node_id: str, prop_id: str, value: str) -> None:
+        """Handle a reported property value update."""
+        now_s = int(time.time())
+
+        if node_id not in self._property_values:
+            self._property_values[node_id] = {}
+            self._property_timestamps[node_id] = {}
+
+        old_value = self._property_values[node_id].get(prop_id)
+
+        if old_value == value:
+            return  # no change — no dirty, no callbacks, no timestamp bump
+
+        self._property_values[node_id][prop_id] = value
+        self._property_timestamps[node_id][prop_id] = now_s
+        self._dirty_nodes.add(node_id)
+
+        self._fire_callbacks(node_id, prop_id, value, old_value)
+
+    def _handle_target(self, node_id: str, prop_id: str, value: str) -> None:
+        """Handle a $target property value."""
+        if node_id not in self._target_values:
+            self._target_values[node_id] = {}
+
+        old_target = self._target_values[node_id].get(prop_id)
+        if old_target == value:
+            return  # no change
+
+        self._target_values[node_id][prop_id] = value
+        self._dirty_nodes.add(node_id)
+
+    def _transition_to_ready(self) -> None:
+        """Transition lifecycle to READY."""
+        self._lifecycle = HomieLifecycle.READY
+        self._ready_since = time.monotonic()
+
+    def _fire_callbacks(self, node_id: str, prop_id: str, value: str, old_value: str | None) -> None:
+        """Fire all registered property callbacks, catching exceptions."""
+        for cb in self._property_callbacks:
+            try:
+                cb(node_id, prop_id, value, old_value)
+            except Exception:  # pylint: disable=broad-exception-caught
+                _LOGGER.debug("Property callback error for %s/%s", node_id, prop_id, exc_info=True)

span_panel_api_schema_0-1.0.0/src/span_panel_api_schema_0/adapter.py

@@ -0,0 +1,115 @@
+"""Flat-schema (data-model-version absent) adapter.
+
+Composes the existing accumulator + consumer and owns the flat wire format:
+a single Homie device whose node ids are circuit UUIDs and capability names.
+Nothing outside this package constructs a flat-schema topic.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from span_panel_api_schema_0.accumulator import HomiePropertyAccumulator
+from span_panel_api_schema_0.const import PROPERTY_SET_TOPIC_FMT, TYPE_CORE, WILDCARD_TOPIC_FMT
+from span_panel_api_schema_0.consumer import HomieDeviceConsumer
+from span_panel_api_schema_0.field_metadata import build_field_metadata
+
+if TYPE_CHECKING:
+    from span_panel_api.models import FieldMetadata, SpanPanelSnapshot, V2HomieSchema
+
+
+class SchemaZeroAdapter:
+    """Parser for the flat single-device schema (firmware r202603-r202627)."""
+
+    # A literal, deliberately not imported from span_panel_api.protocol: a value
+    # read from the installed bootstrap would agree with every bootstrap, which
+    # is the disagreement the check exists to find. Bump when this adapter is
+    # rebuilt against a new contract, never to match what happens to be installed.
+    ADAPTER_CONTRACT: int = 1
+    schema_major = "schema_0"
+    SUPPORTS_DATA_MODEL_VERSIONS: tuple[str, str] = (">=0", "<1.0")
+
+    def __init__(self, serial_number: str, schema: V2HomieSchema) -> None:
+        self._serial_number = serial_number
+        # `panel_size` is derived here rather than handed in, because deriving
+        # it means reading the flat schema's `types` block for the circuit
+        # `space` format — knowledge that belongs to this package. The
+        # transport used to do this on every adapter's behalf, which only
+        # worked while every adapter was this one.
+        self._schema = schema
+        self._accumulator = HomiePropertyAccumulator(serial_number)
+        self._consumer = HomieDeviceConsumer(self._accumulator, schema.panel_size)
+
+    def topics_to_subscribe(self) -> list[str]:
+        return [WILDCARD_TOPIC_FMT.format(serial=self._serial_number)]
+
+    def handle_message(self, topic: str, payload: str) -> None:
+        self._consumer.handle_message(topic, payload)
+
+    def is_ready(self) -> bool:
+        return self._consumer.is_ready()
+
+    def build_snapshot(self) -> SpanPanelSnapshot:
+        return self._consumer.build_snapshot()
+
+    def build_field_metadata(self) -> dict[str, FieldMetadata]:
+        return build_field_metadata(self._schema.types)
+
+    def circuit_nodes_missing_names(self) -> list[str]:
+        return self._consumer.circuit_nodes_missing_names()
+
+    def find_node_by_type(self, type_str: str) -> str | None:
+        return self._consumer.find_node_by_type(type_str)
+
+    def set_circuit_relay_topic(self, circuit_id: str) -> str:
+        return PROPERTY_SET_TOPIC_FMT.format(serial=self._serial_number, node=circuit_id, prop="relay")
+
+    def set_circuit_priority_topic(self, circuit_id: str) -> str:
+        return PROPERTY_SET_TOPIC_FMT.format(serial=self._serial_number, node=circuit_id, prop="shed-priority")
+
+    def set_dominant_power_source_topic(self) -> str | None:
+        core_node = self._consumer.find_node_by_type(TYPE_CORE)
+        if core_node is None:
+            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 set_evse_charge_limit_topic(self, node_id: str) -> str | None:  # pylint: disable=unused-argument
+        """None: flat firmware publishes no charge-current ceiling to write.
+
+        The flat `energy.ebus.device.evse` type carries `advertised-current` —
+        what the charger is offering the vehicle, read-only — and nothing that
+        sets it. There is no property to aim a set topic at, so the transport
+        refuses the command rather than publishing to a topic no panel of this
+        generation subscribes to.
+
+        `node_id` is accepted and unused for the same reason
+        `set_dominant_power_source_topic` takes no arguments and still returns
+        None on a panel with no core node: the answer does not depend on which
+        charger is asked.
+        """
+        return None
+
+    def evse_charge_limit_payload(self, node_id: str, amps: int) -> str | None:  # pylint: disable=unused-argument
+        """None, for the same reason: no property, so no representable value."""
+        return None
+
+    def register_property_callback(self, callback: Callable[[str, str, str, str | None], None]) -> Callable[[], None]:
+        return self._consumer.register_property_callback(callback)