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

span_panel_api_schema_0-1.0.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_0-1.0.0b1/CHANGELOG.md

@@ -0,0 +1,34 @@
+# 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.
+
+## [1.0.0b1] - 08/2026
+
+Pre-release. First release as a standalone distribution.
+
+### Added
+
+- **The flat-schema parser, extracted from `span-panel-api` 2.6.4.** Relocated verbatim from `span_panel_api._impl.schema_0` to `span_panel_api_schema_0`; only import statements changed. Registers itself 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.
+- **`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 a future `schema_1` declares its own rather than inheriting one that does not exist on its firmware.
+- **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`.
+
+### 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.0b1/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: span-panel-api-schema-0
+Version: 1.0.0b1
+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.10
+Requires-Dist: span-panel-api<4.0,>=3.0.0b1
+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 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 span-panel-api-schema-0 span-panel-api-schema-1
+```
+
+Dispatch happens at runtime, per panel, from the `data-model-version` the panel reports.
+
+## 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.0b1/README.md

@@ -0,0 +1,32 @@
+# 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 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 span-panel-api-schema-0 span-panel-api-schema-1
+```
+
+Dispatch happens at runtime, per panel, from the `data-model-version` the panel reports.
+
+## 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.0b1/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "span-panel-api-schema-0"
+version = "1.0.0b1"
+description = "Flat-schema (data-model-version absent) 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",
+]
+
+[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.0b1/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.0b1/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.0b1/src/span_panel_api_schema_0/adapter.py

@@ -0,0 +1,67 @@
+"""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, HomieSchemaTypes, SpanPanelSnapshot
+
+
+class SchemaZeroAdapter:
+    """Parser for the flat single-device schema (firmware r202603-r202627)."""
+
+    schema_major = "schema_0"
+    SUPPORTS_DATA_MODEL_VERSIONS: tuple[str, str] = (">=0", "<1.0")
+
+    def __init__(self, serial_number: str, panel_size: int) -> None:
+        self._serial_number = serial_number
+        self._accumulator = HomiePropertyAccumulator(serial_number)
+        self._consumer = HomieDeviceConsumer(self._accumulator, 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, schema_types: HomieSchemaTypes) -> dict[str, FieldMetadata]:
+        return build_field_metadata(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 register_property_callback(self, callback: Callable[[str, str, str, str | None], None]) -> Callable[[], None]:
+        return self._consumer.register_property_callback(callback)

span_panel_api_schema_0-1.0.0b1/src/span_panel_api_schema_0/const.py

@@ -0,0 +1,83 @@
+"""Constants for the flat-schema (Homie v5) parsing implementation."""
+
+# ---------------------------------------------------------------------------
+# Provenance anchor — the schema revision every fact in this module was read
+# from. `tests/test_schema_provenance.py` fails when a captured schema reports a
+# different one, which is the only pre-release signal that this adapter has
+# drifted from the wire it claims to parse.
+#
+# The field name is per-adapter, not per-bootstrap: flat firmware publishes
+# `typesSchemaHash` over a `types` block, while parent/child renames it to
+# `deviceClassesSchemaHash` over `deviceClasses` — the hash is renamed with the
+# block it covers, so schema_1 declares its own.
+#
+# Content-derived, not build-derived: SPAN defines it as the SHA-256 of the
+# canonicalized schema object and states the schema "may remain unchanged across
+# multiple firmware releases". So it moves when the schema moves, not on every
+# release — which is what makes it usable as an anchor rather than noise.
+# ---------------------------------------------------------------------------
+SCHEMA_ANCHOR_FIELD = "typesSchemaHash"
+SCHEMA_ANCHOR = "sha256:d347556a07d98f40"
+SCHEMA_ANCHOR_FIRMWARE = "spanos2/r202603/05"
+
+# Homie v5 topic structure
+HOMIE_VERSION = 5
+HOMIE_DOMAIN = "ebus"
+TOPIC_PREFIX = f"{HOMIE_DOMAIN}/{HOMIE_VERSION}"
+
+# Topic patterns (serial_number substituted at runtime).
+# The adapter subscribes with the wildcard and publishes with the set pattern;
+# per-topic read formats are not needed because every message arrives through
+# the one wildcard subscription.
+PROPERTY_SET_TOPIC_FMT = f"{TOPIC_PREFIX}/{{serial}}/{{node}}/{{prop}}/set"
+WILDCARD_TOPIC_FMT = f"{TOPIC_PREFIX}/{{serial}}/#"
+
+# ---------------------------------------------------------------------------
+# Homie type strings.
+#
+# Two namespaces that are easy to conflate and are NOT the same set:
+#
+#   * the `types` block of GET /api/v2/homie/schema, which declares the
+#     properties, units and datatypes available to a type; and
+#   * the `type` string a node actually carries in its $description on the wire.
+#
+# Every constant below is a node type observed on the wire. The ones in the
+# first group are also declared in the schema, so metadata lookup finds them
+# directly. See tests/test_schema_provenance.py, which asserts that.
+# ---------------------------------------------------------------------------
+TYPE_CORE = "energy.ebus.device.distribution-enclosure.core"
+TYPE_LUGS = "energy.ebus.device.lugs"
+TYPE_CIRCUIT = "energy.ebus.device.circuit"
+TYPE_BESS = "energy.ebus.device.bess"
+TYPE_PV = "energy.ebus.device.pv"
+TYPE_EVSE = "energy.ebus.device.evse"
+TYPE_POWER_FLOWS = "energy.ebus.device.power-flows"
+
+# Wire-only subtypes: real node types published by real firmware (confirmed
+# against a live panel in 1eef0dc), but NOT declared in the schema's `types`
+# block, which carries only the base `energy.ebus.device.lugs`. Firmware uses
+# one convention or the other — typed nodes, or generic nodes plus a
+# `direction` property — and _find_lugs_node handles both.
+#
+# Because the schema does not declare them, every one of these needs an entry
+# in field_metadata._LUGS_FALLBACK mapping it to a declared type, or property
+# metadata silently comes back empty for those nodes. The provenance test
+# asserts that pairing rather than trusting it.
+TYPE_LUGS_UPSTREAM = "energy.ebus.device.lugs.upstream"
+TYPE_LUGS_DOWNSTREAM = "energy.ebus.device.lugs.downstream"
+
+# Lugs direction values
+LUGS_UPSTREAM = "UPSTREAM"
+LUGS_DOWNSTREAM = "DOWNSTREAM"
+
+
+def normalize_circuit_id(node_id: str) -> str:
+    """Strip dashes from Homie UUID for entity stability."""
+    return node_id.replace("-", "")
+
+
+def denormalize_circuit_id(circuit_id: str) -> str:
+    """Restore dashes to a 32-char dashless UUID (8-4-4-4-12 format)."""
+    if len(circuit_id) == 32 and "-" not in circuit_id:
+        return f"{circuit_id[:8]}-{circuit_id[8:12]}-{circuit_id[12:16]}-{circuit_id[16:20]}-{circuit_id[20:]}"
+    return circuit_id