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

span_panel_api-3.0.0b3/.env.example

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

{span_panel_api-3.0.0b1 → span_panel_api-3.0.0b3}/.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.0b3}/.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.0b3}/.gitignore

@@ -34,3 +34,9 @@ dmypy.json
 coverage_output.log
 **/.DS_Store
 .local_coverage_data
+
+# Captures taken from a real panel. These carry the panel's serial (which is also
+# its MQTT username), the household's circuit names, and real consumption — none
+# of which belongs in a repository. The differential that reads them commits its
+# *verdict* only, never the capture, and skips when the file is absent.
+tests/fixtures/live_*.json

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

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

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

@@ -3,10 +3,15 @@ repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:
+      # `packages/schema-1/spec/` holds byte copies of the eBus specification,
+      # verified by byte comparison in tests/test_schema_one_conformance.py. Any
+      # hook that rewrites a file must skip it: a "fix" there would silently
+      # invalidate the comparison that makes the copies trustworthy. Non-mutating
+      # checks (check-json) deliberately still run, since a corrupt copy should fail.
       - id: trailing-whitespace
-        exclude: '^src/span_panel_api/generated_client/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*'
+        exclude: '^src/span_panel_api/generated_client/.*|^packages/schema-1/spec/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*'
       - id: end-of-file-fixer
-        exclude: '^src/span_panel_api/generated_client/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*'
+        exclude: '^src/span_panel_api/generated_client/.*|^packages/schema-1/spec/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*'
       - id: check-yaml
         exclude: '^src/span_panel_api/generated_client/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*'
       - id: check-toml
@@ -20,7 +25,7 @@ repos:
         exclude: '^src/span_panel_api/generated_client/.*|generate_client\.py|scripts/.*|tests/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*|^examples/.*'
       - id: mixed-line-ending
         args: ['--fix=lf']
-        exclude: '^src/span_panel_api/generated_client/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*'
+        exclude: '^src/span_panel_api/generated_client/.*|^packages/schema-1/spec/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*'
 
   # Ruff for formatting and linting
   - repo: https://github.com/astral-sh/ruff-pre-commit
@@ -55,7 +60,7 @@ repos:
       - id: prettier
         types: [markdown]
         args: ['--config', '.prettierrc.json']
-        exclude: '^src/span_panel_api/generated_client/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*|node_modules/.*|htmlcov/.*'
+        exclude: '^src/span_panel_api/generated_client/.*|^packages/schema-1/spec/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*|node_modules/.*|htmlcov/.*'
 
   # Markdownlint for markdown files (after Prettier formatting)
   - repo: https://github.com/DavidAnson/markdownlint-cli2
@@ -63,7 +68,7 @@ repos:
     hooks:
       - id: markdownlint-cli2
         args: ['--config', '.markdownlint-cli2.jsonc']
-        exclude: '^src/span_panel_api/generated_client/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*|node_modules/.*|htmlcov/.*'
+        exclude: '^src/span_panel_api/generated_client/.*|^packages/schema-1/spec/.*|\..*_cache/.*|dist/.*|venv/.*|\.venv/.*|node_modules/.*|htmlcov/.*'
 
   # MyPy for type checking
   - repo: https://github.com/pre-commit/mirrors-mypy
@@ -77,6 +82,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.19.0
         args: ['--config-file=pyproject.toml']
         exclude: '^src/span_panel_api/generated_client/.*|scripts/.*|tests/.*|docs/.*|examples/.*|\..*_cache/.*|dist/.*|venv/.*'
 
@@ -92,6 +101,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.19.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 +120,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 +143,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.0b3}/CHANGELOG.md

@@ -4,6 +4,73 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0b3] - 08/2026
+
+Pre-release. Normalises DER identity onto v1.0's vocabulary, and stops deriving the grid answers that v1.0 states outright.
+
+### Changed
+
+- **BREAKING — DER identity speaks v1.0's vocabulary on every device class.** `model` is the human designation and `part_number` the SKU, on `battery`, `evse` and `pv` alike. `product_name` is retired on all three. Flat is the inconsistent side, not v1.0:
+  it puts the SKU in `bess/model` and in `evse/part-number`, the same concept under two names, and gives PV neither. `schema_1` used to cross over (`info/part-number` → `battery.model`) to hold each entity's displayed meaning still, which worked and
+  permanently encoded flat's irregularity in the snapshot. `schema_0` now translates flat into the normalised shape instead of mirroring it. Measured: every EVSE identity field reads identically on both adapters, so for that device class identity stops
+  being a migration delta at all. **`battery.model` changes value for existing flat users at this upgrade** — it gains the designation where it carried the SKU. That is the deliberate trade: a change we schedule in a library release beats the same change
+  arriving unplanned during a firmware upgrade a user did not choose the timing of.
+- **Consumers reading `product_name` must move to `model` in the same release.** The Home Assistant integration builds its device-registry model from it; left unchanged, device cards go blank.
+
+### Added
+
+- **`SpanMidSnapshot`, and `SpanPanelSnapshot.mid`.** v1.0 publishes a Microgrid Interconnect Device and the enclosure model puts the `grid` capability on it rather than on the enclosure, so islanding state, grid state and the grid-forming entity live
+  there. Previously one of its five properties was read and the device discarded. Purely additive: no flat panel publishes a MID, so nothing existing changes. Presence is `snapshot.mid is not None` rather than a sentinel field, and identity is
+  `info/serial-number` rather than the Homie device id, which the proxy model warns is not stable across a proxy-to-native transition.
+
+### Fixed
+
+- **Adapter discovery no longer blocks the caller's event loop, and no longer imports adapters the panel will never use.** Two defects with one cause: discovery resolved the whole entry-point group up front, on the calling thread. A flat panel therefore
+  imported `schema_1` — and with it the eBus SDK and jsonschema — on every connection, for a parser it would not call. Home Assistant reported the whole sequence (`listdir`, `read_text`, `open`, `scandir`) as blocking calls inside the event loop and asked
+  for a bug report, with setup stalled 2.0s on a cold import cache. Enumeration and resolution are now separate: `installed_adapter_keys()` reads distribution metadata only, and an adapter is imported the first time a panel asks for that key. The async
+  paths run both in a thread. Resolution stays cached per key, which is what keeps the synchronous pre-rebuild callback free of I/O. **`discover_adapters()` is replaced by `installed_adapter_keys()`**, which returns registered names rather than a registry
+  of loaded classes — verifying every name would mean importing every package, which is the cost being removed. `SpanMqttClient.available_adapters` becomes `installed_adapters` for the same reason.
+- **A firmware upgrade to a schema generation this install cannot parse is reported instead of raised into a background task.** The redispatch path resolves the new adapter before touching any state, so a flat-only install that meets a v1.0 panel logs
+  which package is missing and keeps the parser it has. Previously `SpanPanelAdapterMissingError` escaped a fire-and-forget task as a bare traceback.
+- **`dsm_state` and `current_run_config` are read from the MID instead of reading `UNKNOWN`.** Both are existing entities that had degraded on v1.0 — not because a source vanished, but because `schema_0` _derives_ them and the derivation was never ported.
+  v1.0 states the answer, so the multi-signal heuristic is gone: sensed from a ready MID, falling back to the user's `shed/asserted-islanding-state` when it is not ready, then to a `power-flows/grid` heuristic when there is no MID at all, and unknown
+  otherwise. A missing MID never reports on-grid — it means SPAN is not the islanding authority, not that the site is on grid, and a generator-fed island is the counterexample. `PANEL_BACKUP` versus `PANEL_OFF_GRID` becomes authoritative rather than
+  guessed, because v1.0 names the forming device and its class is recoverable from the tree.
+- **`grid_islandable` is mapped to `grid-forming/capable`** over the BESS's inverter children, as the disjunction — a panel does not island, its DER does, and flat expressed a property of the DER as a property of the enclosure. It returns `None` rather
+  than `False` when nothing publishes it, so absence stays a gap instead of becoming a claim. No producer publishes it today, which is recorded rather than worked around.
+- **EVSE identity survives the migration.** The snapshot key and `node_id` — which a consumer builds a `unique_id` and a device-registry identifier from — were the v1.0 device id on `schema_1` and firmware's node name on `schema_0`, so every charger would
+  have orphaned and reappeared as a duplicate. Both are the Drive's serial now, which is what real flat firmware keys by.
+
+## [3.0.0b2] - 08/2026
+
+Pre-release. Releases the reshaped `SchemaAdapter` protocol that `3.0.0b1` predates, and makes the mismatch between the two detectable rather than fatal at construction.
+
+### 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.0b3}/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/README.md → span_panel_api-3.0.0b3/PKG-INFO

@@ -1,3 +1,18 @@
+Metadata-Version: 2.5
+Name: span-panel-api
+Version: 3.0.0b3
+Summary: A client library for SPAN Panel API
+Project-URL: Homepage, https://github.com/SpanPanel/span-panel-api
+Project-URL: Issues, https://github.com/SpanPanel/span-panel-api/issues
+Author: SpanPanel
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: <4.0,>=3.10
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: paho-mqtt<3.0.0,>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Description-Content-Type: text/markdown
+
 # SPAN Panel API
 
 [![GitHub Release](https://img.shields.io/github/v/release/SpanPanel/span-panel-api?style=flat-square)](https://github.com/SpanPanel/span-panel-api/releases)
@@ -23,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/PKG-INFO → span_panel_api-3.0.0b3/README.md

@@ -1,18 +1,3 @@
-Metadata-Version: 2.4
-Name: span-panel-api
-Version: 3.0.0b1
-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
-Author: SpanPanel
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: <4.0,>=3.10
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: paho-mqtt<3.0.0,>=2.0.0
-Requires-Dist: pyyaml>=6.0.0
-Description-Content-Type: text/markdown
-
 # SPAN Panel API
 
 [![GitHub Release](https://img.shields.io/github/v/release/SpanPanel/span-panel-api?style=flat-square)](https://github.com/SpanPanel/span-panel-api/releases)
@@ -38,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.0b3/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 installed_adapter_keys, resolve_adapter, DEFAULT_ADAPTER_KEY
+from span_panel_api.exceptions import SpanPanelAdapterMissingError
+print('adapters:', installed_adapter_keys())
+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 installed_adapter_keys
+print('adapters:', installed_adapter_keys())
+"
+```
+
+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.0b3}/packages/schema-0/CHANGELOG.md

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

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api-schema-0"
-version = "1.0.0b1"
+version = "1.0.0b3"
 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]