span-panel-api-schema-1 0.1.0b1__tar.gz

span_panel_api_schema_1-0.1.0b1/.gitignore

@@ -0,0 +1,36 @@
+__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

span_panel_api_schema_1-0.1.0b1/CHANGELOG.md

@@ -0,0 +1,45 @@
+# 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.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_schema_1-0.1.0b1/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: span-panel-api-schema-1
+Version: 0.1.0b1
+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
+Author: SpanPanel
+License-Expression: MIT
+Requires-Python: <4.0,>=3.10
+Requires-Dist: ebus-sdk<1.0,>=0.18.0
+Requires-Dist: span-panel-api<4.0,>=3.0.0b1
+Description-Content-Type: text/markdown
+
+# span-panel-api-schema-1
+
+Parent/child schema parser (`data-model-version` 1.x, SPAN firmware r202633+) for [span-panel-api](https://github.com/SpanPanel/span-panel-api).
+
+**Status: incomplete.** This distribution does not yet register a `schema_1` adapter, so installing it does not make a parent/child panel work. A 1.x panel still raises `SpanPanelAdapterMissingError` naming `schema_1`, which is the honest answer until the
+parser can build a snapshot.
+
+What exists today is `BridgeControllerTransport` — an `ebus_sdk.MqttControllerTransport` backed by span-panel-api's own MQTT connection, so the eBus SDK can parse the parent/child tree while the connection to the panel's broker stays ours.

span_panel_api_schema_1-0.1.0b1/README.md

@@ -0,0 +1,8 @@
+# span-panel-api-schema-1
+
+Parent/child schema parser (`data-model-version` 1.x, SPAN firmware r202633+) for [span-panel-api](https://github.com/SpanPanel/span-panel-api).
+
+**Status: incomplete.** This distribution does not yet register a `schema_1` adapter, so installing it does not make a parent/child panel work. A 1.x panel still raises `SpanPanelAdapterMissingError` naming `schema_1`, which is the honest answer until the
+parser can build a snapshot.
+
+What exists today is `BridgeControllerTransport` — an `ebus_sdk.MqttControllerTransport` backed by span-panel-api's own MQTT connection, so the eBus SDK can parse the parent/child tree while the connection to the panel's broker stays ours.

span_panel_api_schema_1-0.1.0b1/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "span-panel-api-schema-1"
+version = "0.1.0b1"
+description = "Parent/child schema (data-model-version 1.x) parser for span-panel-api"
+authors = [
+    {name = "SpanPanel"}
+]
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10,<4.0"
+dependencies = [
+    "span-panel-api>=3.0.0b1,<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",
+]
+
+[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. Dispatch resolves `schema_1` for a 1.x
+# panel by discovering this group, never by importing this package.
+#
+# Held back until the parser could answer for a panel end to end — mapper,
+# field metadata, command topics, and recovery from a real broker outage.
+# Installing this package remains the opt-in: a 1.x panel without it still gets
+# the named SpanPanelAdapterMissingError rather than a silent misparse.
+[project.entry-points."span_panel_api.schema_adapters"]
+schema_1 = "span_panel_api_schema_1:SchemaOneAdapter"
+
+[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_1"]

span_panel_api_schema_1-0.1.0b1/src/span_panel_api_schema_1/__init__.py

@@ -0,0 +1,6 @@
+"""Parent/child schema (data-model-version 1.x) parser for span-panel-api."""
+
+from span_panel_api_schema_1.adapter import SchemaOneAdapter
+from span_panel_api_schema_1.transport import ControllerRoutes
+
+__all__ = ["ControllerRoutes", "SchemaOneAdapter"]

span_panel_api_schema_1-0.1.0b1/src/span_panel_api_schema_1/adapter.py

@@ -0,0 +1,255 @@
+"""Parent/child adapter: `ebus_sdk.Controller` behind the `SchemaAdapter` protocol.
+
+The SDK does the Homie work — walking `$description.children`, gating each
+child's subscription on its parent reaching `ready`, and cascading state down
+the tree. This adapter supplies the transport it parses over, sorts the result
+into a `SpanPanelSnapshot`, and builds the topics the transport publishes
+commands to.
+
+**It never touches the connection.** `SchemaAdapter` instances are built before
+one exists, so `Controller` is given a route table (`ControllerRoutes`) that
+records its subscriptions instead of making them, and this adapter asks for one
+broad subscription up front through `topics_to_subscribe()`. Every message then
+arrives via `handle_message` and is routed to whichever SDK callback wanted it.
+A reconnect re-subscribes that same static list, the broker replays the retained
+tree, and the SDK repopulates — so there is no resync hook to wire or forget.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from ebus_sdk import Controller
+
+from span_panel_api_schema_1.const import (
+    HOMIE_DOMAIN,
+    HOMIE_VERSION,
+    NODE_INFO,
+    NODE_LOAD_SHED,
+    NODE_SWITCH,
+    PROP_MODEL,
+    PROP_NAME,
+    PROP_PRIORITY,
+    PROP_RELAY,
+    STATE_READY,
+)
+from span_panel_api_schema_1.field_metadata import build_field_metadata
+from span_panel_api_schema_1.snapshot import TreeRoles, build_snapshot, device_type
+from span_panel_api_schema_1.transport import ControllerRoutes
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from ebus_sdk.homie import DiscoveredDevice
+
+    from span_panel_api.models import FieldMetadata, SpanPanelSnapshot, V2HomieSchema
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class SchemaOneAdapter:
+    """Parser for the parent/child schema (data-model-version 1.x)."""
+
+    schema_major = "schema_1"
+    SUPPORTS_DATA_MODEL_VERSIONS: tuple[str, str] = (">=1.0", "<2.0")
+
+    def __init__(self, serial_number: str, schema: V2HomieSchema) -> None:
+        self._serial_number = serial_number
+        self._schema = schema
+        self._routes = ControllerRoutes()
+        self._controller = Controller(root_device_id=serial_number, mqttc=self._routes)
+        self._property_callbacks: list[Callable[[str, str, str, str | None], None]] = []
+        self._awaiting: tuple[str, ...] = ()
+        self._controller.set_on_property_changed_callback(self._on_property_changed)
+        # Records the subscriptions the tree walk needs; nothing reaches the
+        # wire, because this object has no connection to reach it with.
+        self._controller.start_discovery()
+
+    # -- SchemaAdapter -----------------------------------------------------
+
+    def topics_to_subscribe(self) -> list[str]:
+        """One subscription covering the whole tree.
+
+        Deliberately broader than the SDK's own per-device subscriptions,
+        because the adapter is asked this once at connect and again after a
+        reconnect — it has no way to add one when a child announces later. The
+        flat adapter takes the same approach with `ebus/5/{serial}/#`; here the
+        wildcard spans devices, since children are peers of the panel in the
+        topic tree rather than nodes beneath it.
+        """
+        return [f"{HOMIE_DOMAIN}/{HOMIE_VERSION}/#"]
+
+    def handle_message(self, topic: str, payload: str) -> None:
+        self._routes.dispatch(topic, payload)
+
+    def is_ready(self) -> bool:
+        """Ready when the whole declared tree has described itself.
+
+        The flat schema gets its entire topology in one `$description`, so
+        "described" and "complete" are the same event. Under parent/child the
+        topology arrives as one description per device, and the root's says
+        ready as soon as *its own* arrives — while its children are still
+        landing. Treating that as ready hands the transport a panel with a
+        handful of circuits and no model, which it reports as a healthy
+        connection. So readiness waits for every device the tree declares.
+
+        Child *state* is deliberately not required. A commissioned DER that is
+        currently offline publishes `lost` but keeps its retained description,
+        and a panel should not fail to connect because a battery is unplugged.
+
+        The model is required only when the root's description declares it: the
+        panel's size comes from nowhere else, and a snapshot built a moment too
+        early reports zero spaces, which erases every unmapped position rather
+        than merely mis-stating a number. Asking only for what the panel itself
+        promised keeps a firmware that omits the property connectable — it
+        falls back to the drift warning in `panel_size_from_model`.
+        """
+        root = self._controller.get_root(self._serial_number)
+        if root is None or root.state != STATE_READY or not root.description:
+            return False
+        if self._awaiting_descriptions(root):
+            return False
+        return self._model_arrived(root)
+
+    def build_snapshot(self) -> SpanPanelSnapshot:
+        root = self._require_root()
+        return build_snapshot(root, self._children())
+
+    def build_field_metadata(self) -> dict[str, FieldMetadata]:
+        root = self._controller.get_root(self._serial_number)
+        devices = [] if root is None else [root, *self._children()]
+        return build_field_metadata(devices)
+
+    def circuit_nodes_missing_names(self) -> list[str]:
+        """Devices whose retained identity has not arrived yet.
+
+        The transport polls this during connect so the first snapshot carries
+        real names rather than falling back to identifiers.
+
+        Readiness proves the tree's *shape* — every device the tree declares
+        has described itself. It cannot prove the tree's *labels*: a
+        description says which properties exist, and their retained values
+        arrive as separate messages that may land after the last description
+        does. That gap exists under the flat schema too; it just matters more
+        here, because a DER is its own device and the integration registers it
+        from this first snapshot.
+
+        Named for the flat schema's circuits, where a missing name was the only
+        way to get a placeholder. Under parent/child every mapped device has
+        the same exposure, so a DER missing the model it declared is reported
+        alongside a circuit missing its name.
+        """
+        roles = TreeRoles(self._children())
+        missing = [circuit.device_id for circuit in roles.circuits if not circuit.get_property(NODE_INFO, PROP_NAME)]
+        ders = (roles.bess, roles.pv, *roles.evse)
+        missing.extend(
+            device.device_id
+            for device in ders
+            if device is not None
+            and PROP_MODEL in device.get_node_properties(NODE_INFO)
+            and device.get_property(NODE_INFO, PROP_MODEL) is None
+        )
+        return missing
+
+    def find_node_by_type(self, type_str: str) -> str | None:
+        """Return the id of the first device declaring `type_str`.
+
+        Named for the flat schema's nodes; under parent/child the same question
+        is asked of devices, and the answer is a device id.
+        """
+        for device in self._children():
+            if device_type(device) == type_str:
+                return device.device_id
+        return None
+
+    # -- Command topics ----------------------------------------------------
+    #
+    # The adapter names the topic and the transport publishes it, so commanding
+    # a panel needs no connection here either.
+
+    def set_circuit_relay_topic(self, circuit_id: str) -> str:
+        return self._set_topic(circuit_id, NODE_SWITCH, PROP_RELAY)
+
+    def set_circuit_priority_topic(self, circuit_id: str) -> str:
+        return self._set_topic(circuit_id, NODE_LOAD_SHED, PROP_PRIORITY)
+
+    def set_dominant_power_source_topic(self) -> str | None:
+        """No v1.0 equivalent, so no topic.
+
+        `dominant-power-source` split into `grid-forming-entity` and
+        `asserted-islanding-state`, which are different controls on different
+        devices rather than a renamed one. Returning None makes the transport
+        reject the command instead of publishing to a topic nothing serves —
+        and which successor to expose is a product decision, tracked in the
+        entity and config deltas write-up.
+        """
+        return None
+
+    def register_property_callback(self, callback: Callable[[str, str, str, str | None], None]) -> Callable[[], None]:
+        """Subscribe to per-property updates; returns an unregister callable."""
+        self._property_callbacks.append(callback)
+
+        def _unregister() -> None:
+            if callback in self._property_callbacks:
+                self._property_callbacks.remove(callback)
+
+        return _unregister
+
+    # -- internals ---------------------------------------------------------
+
+    def _set_topic(self, device_id: str, node: str, prop: str) -> str:
+        return f"{HOMIE_DOMAIN}/{HOMIE_VERSION}/{device_id}/{node}/{prop}/set"
+
+    def _require_root(self) -> DiscoveredDevice:
+        """The root, or a clear error if discovery has not finished.
+
+        Checks readiness rather than existence: `start_discovery` pre-creates
+        the root entry so descendants have somewhere to attach, so the device
+        object exists from construction and proves nothing on its own.
+        """
+        root = self._controller.get_root(self._serial_number)
+        if root is None or not self.is_ready():
+            raise RuntimeError(f"Device tree for {self._serial_number!r} is not ready; build_snapshot called too early")
+        return root
+
+    def _children(self) -> list[DiscoveredDevice]:
+        return list(self._controller.get_descendants(self._serial_number))
+
+    def _awaiting_descriptions(self, root: DiscoveredDevice) -> tuple[str, ...]:
+        """Devices the tree declares that have not described themselves yet.
+
+        Walks declarations rather than discoveries, and at any depth: a child
+        may declare children of its own, and those count too. Logged when the
+        set changes, because the alternative diagnostic for a tree that never
+        completes is a bare 30-second connect timeout.
+        """
+        described = {device.device_id: device for device in self._children() if device.description is not None}
+        awaiting = {
+            child_id
+            for device in (root, *described.values())
+            for child_id in device.children_ids
+            if child_id not in described
+        }
+        pending = tuple(sorted(awaiting))
+        if pending != self._awaiting:
+            self._awaiting = pending
+            if pending:
+                _LOGGER.debug("Waiting on %d declared devices: %s", len(pending), ", ".join(pending))
+        return pending
+
+    def _model_arrived(self, root: DiscoveredDevice) -> bool:
+        """Whether the panel has published the model it said it would."""
+        if PROP_MODEL not in root.get_node_properties(NODE_INFO):
+            return True
+        return root.get_property(NODE_INFO, PROP_MODEL) is not None
+
+    def _on_property_changed(self, device_id: str, node_id: str, property_id: str, value: str, _old: str | None) -> None:
+        """Fan a Controller property change out to registered consumers.
+
+        Signature adapts the SDK's five arguments to the protocol's four: the
+        protocol has no place for the previous value, and consumers that need
+        one keep it themselves.
+        """
+        for callback in list(self._property_callbacks):
+            callback(device_id, node_id, property_id, value)

span_panel_api_schema_1-0.1.0b1/src/span_panel_api_schema_1/circuits.py

@@ -0,0 +1,177 @@
+"""Map a v1.0 circuit device onto ``SpanCircuitSnapshot``.
+
+The snapshot's field names come from the v1 REST API and are preserved so the
+integration's entities do not move. Three of them no longer have a property to
+read, because v1.0 consolidated four flat mechanisms into two. Their
+derivations are defined by the migration guide, not invented here:
+
+======================  ===========================================================
+Flat property           v1.0 source
+======================  ===========================================================
+``always-on``           ``switch/relay-controllable``, inverted
+``never-backup``        ``$settable`` on ``load-shed/priority``, inverted
+``sheddable``           computed: ``priority != NEVER and relay-controllable``
+======================  ===========================================================
+
+Sign and direction are unchanged from the flat schema, and both are the reverse
+of what the property names suggest. Values are in the enclosure's reference
+frame: a normal load reads **negative** ``active-power`` and accumulates
+``exported-energy`` (the panel exported it *to* the circuit). The snapshot
+reports consumption as positive, so power is negated and the two energy
+accumulators are swapped.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from span_panel_api.models import SpanCircuitSnapshot
+from span_panel_api_schema_1.const import (
+    ATTR_SETTABLE,
+    NODE_BREAKER,
+    NODE_INFO,
+    NODE_LOAD_SHED,
+    NODE_METER,
+    NODE_SWITCH,
+    PRIORITY_NEVER,
+    PROP_ACTIVE_POWER,
+    PROP_CURRENT,
+    PROP_EXPORTED_ENERGY,
+    PROP_IMPORTED_ENERGY,
+    PROP_NAME,
+    PROP_POLES,
+    PROP_PRIORITY,
+    PROP_RATING,
+    PROP_RELAY,
+    PROP_RELAY_CONTROLLABLE,
+    PROP_RELAY_REQUESTER,
+    PROP_SPACES,
+    UNKNOWN,
+)
+
+if TYPE_CHECKING:
+    from ebus_sdk.homie import DiscoveredDevice
+
+
+def _text(device: DiscoveredDevice, node: str, prop: str, default: str = "") -> str:
+    value = device.get_property(node, prop)
+    return default if value is None else str(value)
+
+
+def _number(device: DiscoveredDevice, node: str, prop: str) -> float | None:
+    """Read a numeric property, or None when it is absent or unparseable.
+
+    Unparseable is treated as absent rather than as an error: a single
+    malformed value must not take down a whole snapshot, and the field it
+    feeds is optional.
+    """
+    raw = device.get_property(node, prop)
+    if raw is None or raw == "":
+        return None
+    try:
+        return float(raw)
+    except (TypeError, ValueError):
+        return None
+
+
+def _flag(device: DiscoveredDevice, node: str, prop: str, *, default: bool) -> bool:
+    """Read a Homie boolean. Absent means `default`, which is not always False.
+
+    `relay-controllable` absent has to mean *controllable*, because the
+    property exists to mark the exception (an always-on circuit). Defaulting it
+    to False would silently make every circuit uncontrollable on a panel that
+    omits it.
+    """
+    raw = device.get_property(node, prop)
+    if raw is None or raw == "":
+        return default
+    return str(raw).strip().lower() == "true"
+
+
+def _tabs(device: DiscoveredDevice) -> list[int]:
+    """Breaker spaces from ``info/spaces``.
+
+    v1.0 publishes the occupied spaces literally (``"36,38"``), where the flat
+    schema published one space plus a `dipole` flag and left the consumer to
+    infer the second as ``space + 2``. Reading the list means a 3-pole breaker
+    reports three tabs instead of being silently truncated to two.
+    """
+    raw = _text(device, NODE_INFO, PROP_SPACES)
+    if not raw:
+        return []
+    tabs: list[int] = []
+    for part in raw.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        try:
+            tabs.append(int(part))
+        except ValueError:
+            continue
+    return tabs
+
+
+def _priority_is_settable(device: DiscoveredDevice) -> bool:
+    """Whether ``load-shed/priority`` is user-settable on this circuit.
+
+    This is the successor to the flat ``never-backup`` boolean, and it is read
+    from the description rather than from a value topic — v1.0 expresses
+    never-backup as *mutability*, so the signal is the Homie ``$settable``
+    attribute on the property definition.
+
+    Absent means settable: locking is the exception a panel announces, so
+    treating an unannounced circuit as locked would mark every circuit
+    never-backup on a panel that does not publish the attribute.
+    """
+    definition = device.get_node_properties(NODE_LOAD_SHED).get(PROP_PRIORITY)
+    if not isinstance(definition, dict):
+        return True
+    settable = definition.get(ATTR_SETTABLE)
+    if settable is None:
+        return True
+    if isinstance(settable, bool):
+        return settable
+    return str(settable).strip().lower() != "false"
+
+
+def build_circuit(
+    device: DiscoveredDevice, device_type: str = "circuit", relative_position: str = ""
+) -> SpanCircuitSnapshot:
+    """Build one circuit snapshot from its v1.0 device."""
+    raw_power = _number(device, NODE_METER, PROP_ACTIVE_POWER) or 0.0
+    # Negate so positive means consumption. The guard keeps -0.0 out of the
+    # snapshot, where it would compare equal to 0.0 but format as "-0.0".
+    instant_power_w = 0.0 if raw_power == 0.0 else -raw_power
+
+    relay_controllable = _flag(device, NODE_SWITCH, PROP_RELAY_CONTROLLABLE, default=True)
+    priority = _text(device, NODE_LOAD_SHED, PROP_PRIORITY, UNKNOWN)
+    priority_settable = _priority_is_settable(device)
+
+    return SpanCircuitSnapshot(
+        circuit_id=device.device_id,
+        name=_text(device, NODE_INFO, PROP_NAME),
+        relay_state=_text(device, NODE_SWITCH, PROP_RELAY, UNKNOWN),
+        instant_power_w=instant_power_w,
+        # The panel *imported* this energy from the circuit, so the circuit
+        # produced it. Named from the panel's perspective, reported from the
+        # circuit's.
+        produced_energy_wh=_number(device, NODE_METER, PROP_IMPORTED_ENERGY) or 0.0,
+        consumed_energy_wh=_number(device, NODE_METER, PROP_EXPORTED_ENERGY) or 0.0,
+        tabs=_tabs(device),
+        priority=priority,
+        # `always-on` is `not relay-controllable`, and the flat schema derived
+        # user-controllability from `always-on` — so this is the same answer by
+        # a shorter route.
+        is_user_controllable=relay_controllable,
+        is_sheddable=priority != PRIORITY_NEVER and relay_controllable,
+        is_never_backup=not priority_settable,
+        device_type=device_type,
+        relative_position=relative_position,
+        is_240v=(_number(device, NODE_BREAKER, PROP_POLES) or 1) >= 2,
+        current_a=_number(device, NODE_METER, PROP_CURRENT),
+        breaker_rating_a=_number(device, NODE_BREAKER, PROP_RATING),
+        always_on=not relay_controllable,
+        relay_requester=_text(device, NODE_SWITCH, PROP_RELAY_REQUESTER, UNKNOWN),
+        relay_state_target=device.get_property_target(NODE_SWITCH, PROP_RELAY),
+        priority_target=device.get_property_target(NODE_LOAD_SHED, PROP_PRIORITY),
+    )