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

{span_panel_api-3.0.0b1 → span_panel_api-3.0.0b2}/.github/workflows/ci.yml

@@ -5,6 +5,12 @@ on:
     branches: [ main, develop ]
   pull_request:
     branches: [ main, develop ]
+  # Push and pull_request both arrive by webhook, so a dropped delivery leaves a
+  # commit with no run at all -- which reads the same as a commit that passed.
+  # Dispatch re-runs this against any ref on demand.
+  #
+  #   gh workflow run ci.yml --ref develop
+  workflow_dispatch:
 
 jobs:
   lint-and-test:

{span_panel_api-3.0.0b1 → span_panel_api-3.0.0b2}/.github/workflows/release.yml

@@ -3,6 +3,18 @@ name: Release
 on:
   release:
     types: [published]
+  # A `release: published` event reaches this workflow only through webhook
+  # delivery, and a dropped delivery is silent: the release exists, the tag
+  # exists, nothing publishes, and the run list looks the same as it did before.
+  # Dispatch goes through the API instead, so a release can always be driven to
+  # PyPI by hand.
+  #
+  #   gh workflow run release.yml --ref schema-1-v0.1.0b1
+  #
+  # Dispatch a tag, never a branch. The steps below read the distribution and
+  # version out of the tag name, so a branch ref carries neither; it falls
+  # through to the error case rather than being guessed at.
+  workflow_dispatch:
 
 # This repo publishes two distributions that version independently: the
 # bootstrap (span-panel-api) and each schema adapter (span-panel-api-schema-N).

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

@@ -77,6 +77,10 @@ repos:
           - pytest
           - types-PyYAML
           - paho-mqtt
+          # 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
         args: ['--config-file=pyproject.toml']
         exclude: '^src/span_panel_api/generated_client/.*|scripts/.*|tests/.*|docs/.*|examples/.*|\..*_cache/.*|dist/.*|venv/.*'
 
@@ -92,6 +96,9 @@ repos:
           - pytest
           - pyyaml
           - 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
         exclude: '^src/span_panel_api/generated_client/.*|tests/.*|generate_client\.py|scripts/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*|^examples/.*'
 
   # Check for common security issues
@@ -108,7 +115,7 @@ repos:
     hooks:
       - id: vulture
         name: vulture
-        entry: bash -c 'uv run vulture src/span_panel_api/ packages/schema-0/src/span_panel_api_schema_0/ --min-confidence 80'
+        entry: bash -c 'uv run vulture src/span_panel_api/ packages/schema-0/src/span_panel_api_schema_0/ packages/schema-1/src/span_panel_api_schema_1/ --min-confidence 80'
         language: system
         types: [python]
         pass_filenames: false
@@ -131,6 +138,6 @@ repos:
         name: coverage summary
         entry: bash
         language: system
-        args: ['-c', 'output=$(uv run pytest tests/ --cov=src/span_panel_api --cov=packages/schema-0/src/span_panel_api_schema_0 --cov-config=pyproject.toml --cov-fail-under=85 -q 2>&1); status=$?; echo "$output"; exit "$status"']
+        args: ['-c', 'output=$(uv run pytest tests/ --cov=src/span_panel_api --cov=packages/schema-0/src/span_panel_api_schema_0 --cov=packages/schema-1/src/span_panel_api_schema_1 --cov-config=pyproject.toml --cov-fail-under=85 -q 2>&1); status=$?; echo "$output"; exit "$status"']
         pass_filenames: false
         verbose: true

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

@@ -4,6 +4,36 @@ 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.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.
+
+### Added
+
+- **Adapter contract versioning.** `SchemaAdapter` now requires an `ADAPTER_CONTRACT` integer, and discovery rejects any adapter that does not declare this package's `ADAPTER_CONTRACT_VERSION`. Member presence was never the whole contract: a Protocol
+  cannot express signatures at runtime, so an adapter carrying every required name and the previous `__init__` arity passed discovery and failed much later inside the transport, as a bare `TypeError` about an argument count — the least actionable moment to
+  learn that two installed packages were built against different versions of each other. Adapters must declare the value as a **literal**; one read from the installed bootstrap would agree with every bootstrap, which is the disagreement being looked for.
+- **`SpanPanelAdapterIncompatibleError`**, raised when the adapter a panel needs is installed but unusable. Distinct from `SpanPanelAdapterMissingError` because the remedy inverts: missing means install something, incompatible means installing more cannot
+  help. Reporting the second as the first sends someone to install a package they already have. Discovery still only _logs_ a rejection, so one unusable third-party adapter cannot take down a panel whose own adapter is fine; the error surfaces only when
+  the rejected adapter turns out to be the one required.
+
+### Fixed
+
+- **`data-model-version` dispatch is live.** The factory hardcoded `None`, so the guard that refuses a parent/child panel was written, tested and never invoked — every panel resolved to the flat parser regardless of what it reported. The Homie schema is
+  now fetched over REST **before** the broker is opened and the version drives adapter selection, which SPAN confirmed is a reliable flat-versus-parent/child signal on that endpoint. A `1.0` panel now raises `SpanPanelAdapterMissingError` naming the
+  adapter to install, instead of dying inside the flat parser on a missing `energy.ebus.device.circuit/space` property.
+- **A directly constructed `SpanMqttClient` dispatches too.** Building a client without `create_span_client` previously always resolved the flat adapter, so it carried the same defect the factory path had. Dispatch now happens wherever a parser is built,
+  and fills in `data_model_version` / `schema_dispatch_reason` rather than leaving them reading `"not dispatched"`.
+
+### Changed
+
+- **BREAKING: `SchemaAdapter.__init__` takes the schema, not a panel size.** `adapter_cls(serial_number, schema)` replaces `adapter_cls(serial_number, panel_size)`. `panel_size` is read out of a block only the flat schema has, so the bootstrap had to
+  understand a wire format it is meant to know nothing about, and an adapter whose schema is shaped differently had no way to say so. Each adapter now reads what its own format defines.
+- **BREAKING: `SchemaAdapter.build_field_metadata()` takes no arguments.** It previously received `schema.types` — again a flat-shaped parameter on a format-agnostic protocol. The adapter holds the schema it was constructed with.
+- **`V2HomieSchema.data_model_version`** carries the `dataModelVersion` field, `None` when the panel omits it. Absence is the flat signal and stays distinct from an empty string.
+- **Tier 1 dispatch moved to `span_panel_api.dispatch.select_adapter_key`** from the private `factory._select_adapter_key`, so the transport can dispatch without importing the factory. `adapters.py` continues to answer "what is installed"; the new module
+  answers "what does this panel need".
+
 ## [3.0.0b1] - 08/2026
 
 Pre-release. `span-panel-api` becomes a transport and a dispatcher that contains **no parser**. Wire formats ship as separate distributions and register themselves via entry points, so support for a new panel schema arrives by installing a package rather

{span_panel_api-3.0.0b1 → span_panel_api-3.0.0b2}/DEVELOPMENT.md

@@ -70,6 +70,28 @@ To install pre-commit hooks:
 
 This installs dependencies (if needed) and configures git pre-commit hooks.
 
+## Workspace layout
+
+This repository is a uv workspace publishing more than one distribution: the bootstrap (`span-panel-api`, at the root) and one parser package per panel schema (`packages/schema-N/`). `uv sync` installs the workspace, so the test suite runs against every
+distribution together.
+
+To work with the packages individually:
+
+```bash
+# Install the workspace including every member
+uv sync --all-packages
+
+# Build every distribution
+uv build --all-packages
+
+# Build just one
+uv build --package span-panel-api-schema-0
+```
+
+## Releasing
+
+See [RELEASE.md](RELEASE.md) — each distribution versions and publishes independently, and the tag name selects which one is published.
+
 ## Contributing
 
 1. Fork and clone the repository

{span_panel_api-3.0.0b1 → span_panel_api-3.0.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: span-panel-api
-Version: 3.0.0b1
+Version: 3.0.0b2
 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
@@ -38,10 +38,17 @@ A Python client library for the SPAN Panel v2 API, using MQTT/Homie for real-tim
 
 ## Installation
 
+Two packages: the transport, and a parser for your panel's schema. `span-panel-api` contains no parser — installing it alone gives a client that connects and then raises `SpanPanelAdapterMissingError`.
+
 ```bash
-pip install span-panel-api
+pip install span-panel-api span-panel-api-schema-0
 ```
 
+`span-panel-api-schema-0` parses the flat schema used by firmware `r202603` through `r202627`, which is every panel in the field today. Panels reporting a `data-model-version` need the adapter for that schema major instead; the error names the one it could
+not find and lists what is installed.
+
+Parsers are discovered through the `span_panel_api.schema_adapters` entry-point group, so support for a new panel schema arrives by installing a package rather than by upgrading the transport. The two version independently — see [RELEASE.md](RELEASE.md).
+
 ### Dependencies
 
 - `httpx` — v2 authentication and detection endpoints

{span_panel_api-3.0.0b1 → span_panel_api-3.0.0b2}/README.md

@@ -23,10 +23,17 @@ A Python client library for the SPAN Panel v2 API, using MQTT/Homie for real-tim
 
 ## Installation
 
+Two packages: the transport, and a parser for your panel's schema. `span-panel-api` contains no parser — installing it alone gives a client that connects and then raises `SpanPanelAdapterMissingError`.
+
 ```bash
-pip install span-panel-api
+pip install span-panel-api span-panel-api-schema-0
 ```
 
+`span-panel-api-schema-0` parses the flat schema used by firmware `r202603` through `r202627`, which is every panel in the field today. Panels reporting a `data-model-version` need the adapter for that schema major instead; the error names the one it could
+not find and lists what is installed.
+
+Parsers are discovered through the `span_panel_api.schema_adapters` entry-point group, so support for a new panel schema arrives by installing a package rather than by upgrading the transport. The two version independently — see [RELEASE.md](RELEASE.md).
+
 ### Dependencies
 
 - `httpx` — v2 authentication and detection endpoints

span_panel_api-3.0.0b2/RELEASE.md

@@ -0,0 +1,193 @@
+# Releasing
+
+This repository publishes **more than one PyPI distribution** from a single source tree. That makes releasing less obvious than `git tag && push`, so this document is the reference: what lives where, how a tag selects what gets published, and what an
+administrator has to do to release everything.
+
+## Layout
+
+One repository, one [uv workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/), independent distributions:
+
+| Distribution              | Directory            | Manifest                           | Purpose                                                                 |
+| ------------------------- | -------------------- | ---------------------------------- | ----------------------------------------------------------------------- |
+| `span-panel-api`          | repository root      | `pyproject.toml`                   | The **bootstrap** — transport, dispatch, protocols. Contains no parser. |
+| `span-panel-api-schema-0` | `packages/schema-0/` | `packages/schema-0/pyproject.toml` | Flat-schema parser (firmware `r202603`–`r202627`)                       |
+
+Adapters are discovered at runtime through the `span_panel_api.schema_adapters` entry-point group. The bootstrap never imports an adapter, and adding an adapter to the field is an install, not an upgrade. Future adapters follow the same pattern under
+`packages/schema-N/`.
+
+Consequences for releasing:
+
+- **Each distribution has its own version number** in its own manifest.
+- **Each distribution is its own PyPI project**, with its own trusted publisher.
+- **A release publishes exactly one distribution.** Releasing "the repo" means cutting one release per distribution.
+
+## Two version axes
+
+The bootstrap and the adapters do not share a version, and this is deliberate rather than an oversight.
+
+- **The bootstrap** versions on its own library API — the transport and the `SchemaAdapter` protocol.
+- **An adapter** versions on _its_ library API. The wire format it parses is fixed and is declared by `SUPPORTS_DATA_MODEL_VERSIONS`, not by the version number. A release of `span-panel-api-schema-0` means the parser changed, never that the panel did.
+
+So `span-panel-api 3.0.0` and `span-panel-api-schema-0 1.0.0` are unrelated numbers, and either can move without the other.
+
+Adapters declare a floor on the bootstrap (`span-panel-api>=3.0.0b1,<4.0`). That dependency is why the versions committed in the manifests are load-bearing: they participate in resolution, so they are not placeholders that a release process may overwrite.
+
+## How a tag selects a distribution
+
+`.github/workflows/release.yml` runs on `release: published` and derives everything from the tag name. There is no lookup table — the manifest path is computed by convention:
+
+| Tag               | Distribution published    | Manifest read                      |
+| ----------------- | ------------------------- | ---------------------------------- |
+| `vX.Y.Z`          | `span-panel-api`          | `pyproject.toml`                   |
+| `schema-N-vX.Y.Z` | `span-panel-api-schema-N` | `packages/schema-N/pyproject.toml` |
+
+Worked example for `schema-0-v1.0.0b1`:
+
+```text
+TAG                 = schema-0-v1.0.0b1
+${TAG#schema-}      → 0-v1.0.0b1          strip leading "schema-"
+${SCHEMA%%-v*}      → 0                   strip trailing "-v…"      ⇒ schema number
+PACKAGE             = span-panel-api-schema-0
+MANIFEST            = packages/schema-0/pyproject.toml
+VERSION             = ${TAG#schema-0-v} → 1.0.0b1
+```
+
+Because the schema number is _extracted_ rather than enumerated, a future `schema-1-v0.1.0` resolves to `packages/schema-1/pyproject.toml` with no change to the workflow.
+
+A tag matching neither form (`1.2.3`, `nightly`) fails immediately with a message naming both accepted forms.
+
+## The tag does not set the version
+
+The workflow **verifies** the version; it does not write it.
+
+```text
+tag  schema-0-v1.0.0b1
+  ⇒ packages/schema-0/pyproject.toml must declare version = "1.0.0b1"
+  ⇒ otherwise the job fails without publishing
+```
+
+This means the release ritual is **bump, commit, then tag** — never tag-and-let-CI-stamp. Earlier versions of this workflow rewrote the version from the tag with `sed`, which cannot work here: there is no single manifest to stamp, and the adapter's
+dependency floor on the bootstrap means a stamped version could silently disagree with what resolution actually uses.
+
+A mismatch is a hard failure with both numbers in the message, so the common mistake — tagging before committing the bump — is caught before anything reaches PyPI.
+
+## Releasing one distribution
+
+1. **Bump the version** in that distribution's manifest, and add a `CHANGELOG.md` entry (the root one for the bootstrap, `packages/schema-N/CHANGELOG.md` for an adapter).
+2. **Merge to `develop`** (or `main`, once this work is no longer prototype) and let CI go green.
+3. **Create a GitHub Release:**
+   - **Tag** — `vX.Y.Z` or `schema-N-vX.Y.Z`, per the table above.
+   - **Target** — the branch holding the bump. This defaults to the repository's default branch, which is the easiest thing to get wrong; a tag cut from the wrong branch builds the wrong version and fails the verification step.
+   - **Set as a pre-release** — tick this for any `aN` / `bN` / `rcN` version.
+4. **Watch the run.** `gh run watch "$(gh run list --workflow=release.yml --limit 1 --json databaseId -q '.[0].databaseId')"`
+
+The job prints exactly what it resolved, which is the first thing to read if something looks wrong:
+
+```text
+Tag 'schema-0-v1.0.0b1' releases span-panel-api-schema-0 1.0.0b1 from packages/schema-0/pyproject.toml
+Version 1.0.0b1 confirmed.
+```
+
+## Releasing every distribution
+
+There is no "release everything" button, and that is intentional — the distributions version independently, so a coordinated release is a sequence of single-distribution releases rather than one action.
+
+To release the whole workspace:
+
+1. Bump every manifest that changed, in one branch, with its changelog entry.
+2. If the bootstrap's version moved and adapters need the new floor, update `span-panel-api>=…` in each adapter manifest **in the same branch**. Do not release an adapter whose floor points at a bootstrap version that is not yet on PyPI.
+3. Merge and let CI go green.
+4. Cut the releases **bootstrap first, then each adapter**:
+
+   ```text
+   v3.0.0b1              → span-panel-api
+   schema-0-v1.0.0b1     → span-panel-api-schema-0
+   schema-1-v0.1.0       → span-panel-api-schema-1
+   ```
+
+   PyPI accepts them in any order, but bootstrap-first means there is never a window in which an adapter is installable and its dependency is not.
+
+5. Verify from PyPI rather than from CI — see below.
+
+Only bump and release what actually changed. A distribution with no changes does not need a release just because a sibling had one.
+
+## Adding a new adapter
+
+When `packages/schema-N/` lands, the workflow needs no edit — but PyPI does, and this is the step that will be forgotten:
+
+1. **Create the PyPI project and its trusted publisher before the first release.** Because the project does not exist yet, this is a _pending publisher_, added from account/organization publishing settings rather than from the (non-existent) project page:
+
+   | Field             | Value                     |
+   | ----------------- | ------------------------- |
+   | PyPI Project Name | `span-panel-api-schema-N` |
+   | Owner             | `SpanPanel`               |
+   | Repository name   | `span-panel-api`          |
+   | Workflow name     | `release.yml`             |
+   | Environment name  | `release`                 |
+
+   Every field except the project name is identical across all distributions here, since they all publish from the same repository and workflow. Once the project exists, the same entry is visible and editable at
+   `https://pypi.org/manage/project/<name>/settings/publishing/`.
+
+2. **Add the package to the workspace** — it is matched by `members = ["packages/*"]` automatically, but the root `[tool.uv.sources]` and the dev dependency group need an entry if the test suite is to exercise it.
+3. **Ship a `py.typed` marker** in the new package. CI fails the build without it.
+
+Trusted publishing verifies repository, workflow filename, and environment — it cannot distinguish _which_ distribution a run is building. That is inherent to a monorepo, and it is why the workflow builds only the tagged package: `dist/` never contains a
+sibling that could be uploaded by accident.
+
+## What the workflow checks
+
+In order, all before anything is uploaded:
+
+1. **Tag names a known distribution** — otherwise fail, naming both accepted forms.
+2. **The derived manifest exists** — catches a `schema-N` tag with no matching directory.
+3. **The tag version equals the committed version** — read with `tomllib`, compared exactly.
+4. **Only the tagged package is built** — `uv build --package <name>`, so `dist/` holds exactly one distribution.
+5. **Every built wheel ships `py.typed`** — a fully annotated distribution that omits it resolves as `Any` for every downstream consumer, silently undoing the strict typing this repository maintains.
+
+| Failure                                     | Meaning                                                                                                         |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `Tag '…' names no distribution`             | Tag is malformed. Use `vX.Y.Z` or `schema-N-vX.Y.Z`.                                                            |
+| `resolves to '…', which does not exist`     | Tag names a schema whose directory is not in this commit — usually a tag cut from the wrong branch.             |
+| `declares version 'A' but the tag says 'B'` | The bump was not committed, or the release targets the wrong branch.                                            |
+| `ships no py.typed marker`                  | The new package is missing the marker file.                                                                     |
+| OIDC / trusted publishing rejection         | The PyPI publisher for that project is missing or does not match. Nothing was uploaded; fix and re-run the job. |
+
+A failed release is safe. Every check runs before upload, so a failure means nothing reached PyPI and the same tag can be re-run once the cause is fixed.
+
+## Verifying a release
+
+CI going green proves the build, not the install. The seam this repository is built around — a bootstrap that finds a parser it never imports — can only be exercised across a real package boundary, so verify from PyPI:
+
+```bash
+# 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.exceptions import SpanPanelAdapterMissingError
+print('adapters:', sorted(discover_adapters()))
+try:
+    resolve_adapter(DEFAULT_ADAPTER_KEY, 'release check')
+except SpanPanelAdapterMissingError as exc:
+    print('raised as designed:', exc.needed, exc.available)
+"
+
+# 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()))
+"
+```
+
+Expected: `adapters: []` then a named `SpanPanelAdapterMissingError` in the first, `adapters: ['schema_0']` in the second.
+
+Drop `--pre` once the versions being verified are not pre-releases.
+
+## Pre-releases
+
+Versions like `3.0.0b1` are pre-releases in both places that matter:
+
+- **PyPI** will not install them without `--pre`, so `pip install span-panel-api` continues to resolve the last stable release.
+- **GitHub** should have "Set as a pre-release" ticked, which keeps them out of the repository's "Latest release" slot.
+
+The publish workflow itself does not care — `on: release: published` fires either way.

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

@@ -7,6 +7,23 @@ 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.0b2] - 08/2026
+
+Pre-release. 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.
+
+### Changed
+
+- **BREAKING: `SchemaZeroAdapter(serial_number, schema)`** replaces `SchemaZeroAdapter(serial_number, panel_size)`, following the protocol change in `span-panel-api`. Panel size is now 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 was previously doing it on every adapter's behalf.
+- **`build_field_metadata()` takes no arguments**, reading the schema this adapter was constructed with.
+- **The `span-panel-api` floor is now `>=3.0.0b2`.** `1.0.0b1` declared `>=3.0.0b1`, which admitted a bootstrap that constructs adapters with `panel_size` — a pairing that could not work. Installing that combination now fails by name at discovery rather
+  than on argument count inside the transport, but the floor is what stops a resolver reaching it at all.
+
 ## [1.0.0b1] - 08/2026
 
 Pre-release. First release as a standalone distribution.

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

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api-schema-0"
-version = "1.0.0b1"
+version = "1.0.0b2"
 description = "Flat-schema (data-model-version absent) parser for span-panel-api"
 authors = [
     {name = "SpanPanel"}
@@ -9,7 +9,7 @@ readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10,<4.0"
 dependencies = [
-    "span-panel-api>=3.0.0b1,<4.0",
+    "span-panel-api>=3.0.0b2,<4.0",
 ]
 
 [project.urls]

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

@@ -16,19 +16,30 @@ 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
+    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, panel_size: int) -> None:
+    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, panel_size)
+        self._consumer = HomieDeviceConsumer(self._accumulator, schema.panel_size)
 
     def topics_to_subscribe(self) -> list[str]:
         return [WILDCARD_TOPIC_FMT.format(serial=self._serial_number)]
@@ -42,8 +53,8 @@ class SchemaZeroAdapter:
     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 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()

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

@@ -0,0 +1,60 @@
+# 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.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/packages/schema-1/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-3.0.0b2/packages/schema-1/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "span-panel-api-schema-1"
+version = "0.1.0b2"
+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.0b2,<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-3.0.0b2/packages/schema-1/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"]