release: span-panel-api 3.0.0 with schema-0 and schema-1 adapters at 1.0.0

.env.example

@@ -0,0 +1,59 @@
+# 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 *here*. Without it the suite runs in full and the
+# checks that need a sibling checkout skip themselves rather than fail. 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.
+#
+# CI is not optional: it clones both peers at the commits spec_lock.json pins, and
+# those checks fail rather than skip when `CI` is set. A skip reads in a summary line
+# exactly like a pass, and that is how a stale vendored capture went unnoticed for
+# nine days. See DEVELOPMENT.md, "A skip here is not a pass".
+
+# 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=

.github/actions/peer-checkouts/action.yml

@@ -0,0 +1,96 @@
+name: Peer checkouts
+description: >
+  Clone the two repositories the schema_1 provenance checks verify against — the eBus
+  specification and SpanPanel/panelbench — and export EBUS_SPEC_DIR / PANELBENCH_DIR
+  for the steps that follow.
+
+  Every value comes out of packages/schema-1/src/span_panel_api_schema_1/spec_lock.json,
+  which is the single home of the pin. A workflow that restated a commit here would
+  give the pin a second home, and the two would agree right up until the day someone
+  re-vendored and updated only one.
+
+inputs:
+  panelbench-ref:
+    description: >
+      Which panelbench to clone, and it decides which question the job asks.
+
+      "pin" clones the exact commit peer.commit records, so the byte comparison asks
+      "do our vendored captures match the commit we claim they came from?" — a
+      deterministic question with a deterministic answer, safe to block a merge on.
+
+      "default" clones peer.ref, the branch the producer develops on, so the same
+      comparison asks "has the producer moved past the pin?". That answer changes
+      because someone else pushed, so it must never gate a pull request.
+    required: false
+    default: pin
+
+outputs:
+  panelbench-pin:
+    description: The commit spec_lock.json pins, whichever ref was cloned.
+    value: ${{ steps.pins.outputs.panelbench-commit }}
+  panelbench-repo:
+    description: The panelbench repository, as owner/name.
+    value: ${{ steps.pins.outputs.panelbench-repo }}
+  panelbench-checkout:
+    description: The ref actually cloned — the pinned commit, or the producer's branch.
+    value: ${{ steps.pins.outputs.panelbench-checkout }}
+
+runs:
+  using: composite
+  steps:
+    - name: Read the peer pins out of spec_lock.json
+      id: pins
+      shell: bash
+      env:
+        PANELBENCH_REF_MODE: ${{ inputs.panelbench-ref }}
+      run: |
+        python3 - <<'PY' >> "$GITHUB_OUTPUT"
+        import json
+        import os
+
+        with open("packages/schema-1/src/span_panel_api_schema_1/spec_lock.json") as handle:
+            lock = json.load(handle)
+        peer = lock["peer"]
+
+        def slug(url: str) -> str:
+            """owner/name, which is what actions/checkout wants."""
+            return url.removeprefix("https://github.com/").removesuffix(".git")
+
+        mode = os.environ["PANELBENCH_REF_MODE"]
+        if mode not in ("pin", "default"):
+            raise SystemExit(f"::error::panelbench-ref must be 'pin' or 'default', got {mode!r}")
+
+        print(f"spec-repo={slug(lock['spec_repo'])}")
+        print(f"spec-commit={lock['synced_commit']}")
+        print(f"panelbench-repo={slug(peer['repo'])}")
+        print(f"panelbench-commit={peer['commit']}")
+        print(f"panelbench-checkout={peer['commit'] if mode == 'pin' else peer['ref']}")
+        PY
+
+    # Both are public, so no token is involved. If either ever goes private this is
+    # the step that starts failing, and the fix is a PAT with read access in `token:`
+    # rather than anything about the pin.
+    - name: Check out the eBus specification at synced_commit
+      uses: actions/checkout@v7
+      with:
+        repository: ${{ steps.pins.outputs.spec-repo }}
+        ref: ${{ steps.pins.outputs.spec-commit }}
+        path: peers/specification
+
+    - name: Check out panelbench
+      uses: actions/checkout@v7
+      with:
+        repository: ${{ steps.pins.outputs.panelbench-repo }}
+        ref: ${{ steps.pins.outputs.panelbench-checkout }}
+        # History only where it is read: the drift job counts commits between the pin
+        # and the branch head, which a shallow clone cannot do.
+        fetch-depth: ${{ inputs.panelbench-ref == 'default' && '0' || '1' }}
+        path: peers/panelbench
+
+    - name: Point the provenance checks at them
+      shell: bash
+      run: |
+        {
+          echo "EBUS_SPEC_DIR=$GITHUB_WORKSPACE/peers/specification"
+          echo "PANELBENCH_DIR=$GITHUB_WORKSPACE/peers/panelbench"
+        } >> "$GITHUB_ENV"

.github/workflows/ci.yml

@@ -17,6 +17,11 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
+        # One entry because `requires-python` is `>=3.14`: the declared floor and
+        # the version tested are the same, which is the only arrangement where a
+        # green run actually proves the range. Widen `requires-python` and this
+        # list has to grow with it -- a floor no job runs is a claim, not a
+        # guarantee.
         python-version: ["3.14"]
 
     steps:
@@ -28,21 +33,44 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
+    # The schema_1 provenance checks compare vendored bytes against the two
+    # repositories they were copied from, and skip when neither is reachable. They
+    # skipped in every run this workflow has ever done, which reads in the summary
+    # line exactly like passing -- see DEVELOPMENT.md, "A skip here is not a pass".
+    # Cloning both at the commits spec_lock.json pins turns them into a question with
+    # a deterministic answer: do our vendored bytes match the commit we say they came
+    # from? Whether the *producer* has moved past that pin is a different question
+    # with a moving answer, and it lives in peer-drift.yml so it cannot fail a pull
+    # request for something the author did not do.
+    #
+    # CI is set by the runner, and tests/test_schema_one_conformance.py fails rather
+    # than skips when it is -- so removing this step breaks the build instead of
+    # quietly switching the checks back off.
+    - name: Check out the peers the provenance checks verify against
+      uses: ./.github/actions/peer-checkouts
+
     - name: Install uv
       uses: astral-sh/setup-uv@v7
       with:
         enable-cache: true
 
     - name: Install dependencies
-      run: uv sync
+      run: uv sync --all-packages
 
     - name: Run pre-commit hooks
       run: |
         uv run pre-commit run --all-files
 
+    # -rs so a skip that does survive is named in the log rather than counted. The
+    # only ones expected here are test_live_flat_differential.py, which needs a
+    # capture from a real panel that is deliberately gitignored.
     - name: Run tests with pytest
       run: |
-        uv run pytest tests/ -v --cov=src/span_panel_api --cov-report=xml --cov-report=term-missing
+        uv run pytest tests/ -v -rs \
+          --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-report=xml --cov-report=term-missing
 
 
 
@@ -63,11 +91,11 @@ jobs:
         enable-cache: true
 
     - name: Install dependencies
-      run: uv sync
+      run: uv sync --all-packages
 
     - name: Run Bandit security scan
       run: |
-        uv run bandit -r src/ -f json -o bandit-report.json || true
+        uv run bandit -r src/ packages/ -f json -o bandit-report.json || true
 
     - name: Upload Bandit scan results
       uses: actions/upload-artifact@v7
@@ -92,14 +120,40 @@ jobs:
         enable-cache: true
 
     - name: Install dependencies
-      run: uv sync
+      run: uv sync --all-packages
 
-    - name: Build package
-      run: uv build
+    - name: Build packages
+      run: uv build --all-packages
 
-    - name: Check package
+    - 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: