span-panel-api 2.6.4__tar.gz → 3.0.0b2__tar.gz

span_panel_api-3.0.0b2/.github/workflows/ci.yml

@@ -0,0 +1,136 @@
+name: CI
+
+on:
+  push:
+    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:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.14"]
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v7
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v7
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      run: uv sync --all-packages
+
+    - name: Run pre-commit hooks
+      run: |
+        uv run pre-commit run --all-files
+
+    - name: Run tests with pytest
+      run: |
+        uv run pytest tests/ -v \
+          --cov=src/span_panel_api \
+          --cov=packages/schema-0/src/span_panel_api_schema_0 \
+          --cov-report=xml --cov-report=term-missing
+
+
+
+  security-scan:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v7
+
+    - name: Set up Python
+      uses: actions/setup-python@v7
+      with:
+        python-version: "3.14"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      run: uv sync --all-packages
+
+    - name: Run Bandit security scan
+      run: |
+        uv run bandit -r src/ packages/ -f json -o bandit-report.json || true
+
+    - name: Upload Bandit scan results
+      uses: actions/upload-artifact@v7
+      with:
+        name: bandit-report
+        path: bandit-report.json
+
+  build-check:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v7
+
+    - name: Set up Python
+      uses: actions/setup-python@v7
+      with:
+        python-version: "3.14"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      run: uv sync --all-packages
+
+    - name: Build packages
+      run: uv build --all-packages
+
+    - name: Check packages
+      run: uv run twine check dist/*
+
+    # Every distribution here is fully annotated, so every distribution has to
+    # carry the marker that lets a consumer's type checker see those annotations.
+    # Without it the package resolves to Any downstream and the typing is inert.
+    - name: Verify every wheel ships a py.typed marker
+      run: |
+        python -c "
+        import glob, sys, zipfile
+        wheels = glob.glob('dist/*.whl')
+        if not wheels:
+            sys.exit('::error::no wheels were built')
+        for wheel in wheels:
+            if not any(n.endswith('/py.typed') for n in zipfile.ZipFile(wheel).namelist()):
+                sys.exit(f'::error::{wheel} ships no py.typed marker; downstream type checking would resolve it as Any')
+            print(f'{wheel}: py.typed present')
+        "
+
+    # The configuration entry-point discovery exists to support, and the one
+    # nothing else in CI exercises: the bootstrap wheel installed with no
+    # adapter present. It must import, and it must fail by name rather than
+    # with ModuleNotFoundError.
+    - name: Verify the bootstrap installs without an adapter
+      run: |
+        uv venv /tmp/bootstrap-only
+        VIRTUAL_ENV=/tmp/bootstrap-only uv pip install dist/span_panel_api-*.whl
+        VIRTUAL_ENV=/tmp/bootstrap-only uv run --no-project python scripts/verify_adapterless_install.py
+
+    - name: Upload build artifacts
+      uses: actions/upload-artifact@v7
+      with:
+        name: dist
+        path: dist/

span_panel_api-3.0.0b2/.github/workflows/release.yml

@@ -0,0 +1,119 @@
+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).
+# One release publishes exactly one of them, chosen by the tag prefix:
+#
+#   v3.0.0b1            -> span-panel-api            (the historical convention)
+#   schema-0-v1.0.0b1   -> span-panel-api-schema-0
+#
+# The version lives in the distribution's own pyproject.toml and this workflow
+# only verifies the tag agrees. It deliberately does not rewrite the version at
+# release time: the adapter declares a floor on the bootstrap
+# (span-panel-api>=X), so the committed versions are load-bearing for resolution
+# and cannot be treated as placeholders that a release stamps over.
+#
+# Publishing uses PyPI trusted publishing, which is configured per project. A
+# distribution released here for the first time needs a pending publisher
+# created on PyPI beforehand (project name, this repo, workflow `release.yml`,
+# environment `release`); without it the publish step fails on an otherwise
+# correct build.
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # For trusted publishing to PyPI
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v7
+
+    - name: Set up Python
+      uses: actions/setup-python@v7
+      with:
+        python-version: "3.14"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        enable-cache: true
+
+    - name: Resolve the distribution from the tag
+      id: target
+      run: |
+        TAG=${GITHUB_REF#refs/tags/}
+        case "$TAG" in
+          schema-*-v*)
+            SCHEMA=${TAG#schema-}
+            SCHEMA=${SCHEMA%%-v*}
+            PACKAGE="span-panel-api-schema-$SCHEMA"
+            MANIFEST="packages/schema-$SCHEMA/pyproject.toml"
+            VERSION=${TAG#schema-$SCHEMA-v}
+            ;;
+          v*)
+            PACKAGE="span-panel-api"
+            MANIFEST="pyproject.toml"
+            VERSION=${TAG#v}
+            ;;
+          *)
+            echo "::error::Tag '$TAG' names no distribution. Use 'vX.Y.Z' for the bootstrap or 'schema-N-vX.Y.Z' for an adapter."
+            exit 1
+            ;;
+        esac
+        if [ ! -f "$MANIFEST" ]; then
+          echo "::error::Tag '$TAG' resolves to '$MANIFEST', which does not exist."
+          exit 1
+        fi
+        echo "Tag '$TAG' releases $PACKAGE $VERSION from $MANIFEST"
+        echo "package=$PACKAGE" >> "$GITHUB_OUTPUT"
+        echo "manifest=$MANIFEST" >> "$GITHUB_OUTPUT"
+        echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+    - name: Verify the tag matches the committed version
+      run: |
+        DECLARED=$(python -c "import sys, tomllib; print(tomllib.load(open(sys.argv[1], 'rb'))['project']['version'])" "${{ steps.target.outputs.manifest }}")
+        if [ "$DECLARED" != "${{ steps.target.outputs.version }}" ]; then
+          echo "::error::${{ steps.target.outputs.manifest }} declares version '$DECLARED' but the tag says '${{ steps.target.outputs.version }}'. Commit the version bump before tagging."
+          exit 1
+        fi
+        echo "Version $DECLARED confirmed."
+
+    # Only the tagged distribution is built, so dist/ holds exactly what this
+    # release publishes and the publish step cannot pick up a sibling package.
+    - name: Build package
+      run: uv build --package "${{ steps.target.outputs.package }}"
+
+    - name: Verify the wheel ships a py.typed marker
+      run: |
+        python -c "
+        import glob, sys, zipfile
+        wheels = glob.glob('dist/*.whl')
+        if not wheels:
+            sys.exit('::error::no wheel was built')
+        for wheel in wheels:
+            if not any(n.endswith('/py.typed') for n in zipfile.ZipFile(wheel).namelist()):
+                sys.exit(f'::error::{wheel} ships no py.typed marker; downstream type checking would resolve it as Any')
+            print(f'{wheel}: py.typed present')
+        "
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        print-hash: true

{span_panel_api-2.6.4 → 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/ --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-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-2.6.4 → span_panel_api-3.0.0b2}/CHANGELOG.md

@@ -4,6 +4,86 @@ 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
+than by upgrading the transport. This is prototype work being proven end to end before any decision to land it on `main`.
+
+### Removed
+
+- **BREAKING: `span-panel-api` no longer contains a parser.** Installing it alone gives a client that connects and then raises `SpanPanelAdapterMissingError`. Flat-schema panels (firmware `r202603`–`r202627`) need **`span-panel-api-schema-0`** installed
+  alongside it:
+
+  ```console
+  pip install span-panel-api span-panel-api-schema-0
+  ```
+
+- **BREAKING: `HomieLifecycle`, `HomiePropertyAccumulator` and `HomieDeviceConsumer` are no longer exported** from `span_panel_api` or `span_panel_api.mqtt`. All three are flat-schema-specific rather than Homie-convention-level: the accumulator filters
+  every topic against a single device's prefix and stores `node → prop`, which drops nearly every message under the parent/child model; `HomieLifecycle`'s members are not Homie 5 `$state` values but a consumer-side progression encoding "one description
+  received ⇒ ready", which is the flat readiness model. They now live in `span_panel_api_schema_0`.
+- **Removed dead constants** `DEVICE_TOPIC_FMT`, `STATE_TOPIC_FMT`, `DESCRIPTION_TOPIC_FMT`, `PROPERTY_TOPIC_FMT` (unreferenced before the Phase 0 relocation) and `TYPE_PCS` (a real schema type this library does not consume).
+
+### Added
+
+- **`span_panel_api.adapters.resolve_adapter(key, reason)`** — the single place a missing adapter becomes a named error, used by both Tier 1 dispatch and the transport's default path.
+- **`SpanPanelSchemaVersionError`**, raised when a panel reports a `data-model-version` whose schema major cannot be determined. Distinct from `SpanPanelAdapterMissingError` because the remedy differs: a missing adapter is a known schema with no installed
+  parser, while this is a schema no adapter can even be named for.
+- **`SpanPanelAdapterMissingError` and `SpanPanelSchemaVersionError` are now exported** from the top-level package — both are errors a user sees when their panel outruns their install, so catching them should not require reaching into a private module.
+- **`SchemaAdapter.__init__` is declared on the protocol.** Construction was always part of the contract (the transport resolves an adapter class from the registry and calls it), but was previously typed only as a `Callable`, leaving the signature
+  unchecked against implementations.
+- **Entry-point validation.** `discover_adapters()` now verifies each loaded object is a class implementing the protocol before registering it, and skips it with a logged reason otherwise. One broken third-party adapter cannot take down a panel whose own
+  adapter is fine.
+- **`scripts/verify_adapterless_install.py`** and a CI step that runs it against a venv holding only the bootstrap wheel.
+
+### Changed
+
+- **`SpanMqttClient(adapter_factory=...)` is now optional.** When omitted, the parser is resolved through entry-point discovery at `_build_adapter()` rather than imported. Resolution is lazy by design: constructing a client must not require an adapter to
+  be installed, only building a parser must.
+- **Dispatch refuses an unreadable `data-model-version` instead of assuming flat.** Absence still means the flat schema — that is a real signal, since the property was introduced by the firmware that introduced parent/child. A value whose major _can_ be
+  read but whose form is non-canonical (`1`, `1.0-beta`) dispatches on that major and logs the deviation. A value with no extractable major now raises. Previously all three fell through to the flat parser, which does not fail — it produces plausible but
+  wrong power and energy figures.
+- **Dispatch diagnostics travel through the `SpanMqttClient` constructor**, removing the window where a connected client reported a selected adapter alongside `schema_dispatch_reason='not dispatched'`.
+- **Releases are now per-distribution and the tag no longer sets the version.** A tag selects which distribution to publish — `vX.Y.Z` for `span-panel-api`, `schema-N-vX.Y.Z` for an adapter — and the release fails unless the tagged version matches the one
+  committed in that distribution's `pyproject.toml`. The previous workflow rewrote the root version from the tag and built only the root package, which under a two-distribution layout would have published the bootstrap with no adapter alongside it. Version
+  numbers are now load-bearing between the two (the adapter declares a floor on the bootstrap), so they belong in the repository rather than being stamped at release time.
+
+### Fixed
+
+- **Adapter distributions ship a `py.typed` marker.** Without it a consumer's type checker refuses to read the adapter's annotations and resolves every symbol it exports as `Any`, silently erasing the strict typing at the wheel boundary. CI now fails any
+  wheel built without one.
+- **Protocol conformance checking no longer depends on member kind.** The required-member set is derived from every public member `SchemaAdapter` declares, not only the callable ones — a `property` or `classmethod` object is not callable, so the previous
+  derivation would have quietly stopped requiring such a member the day the protocol declared one.
+
 ## [2.6.4] - 05/2026
 
 ### Fixed

{span_panel_api-2.6.4 → 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-2.6.4 → span_panel_api-3.0.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: span-panel-api
-Version: 2.6.4
+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-2.6.4 → 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.