Implement the Python SDK with full spec conformance

.github/workflows/ci.yml

@@ -37,6 +37,28 @@ jobs:
       - name: Run pytest
         run: uv run pytest -q
 
+      # Blocking requirement-traceability audit. Collection-only run: the
+      # TraceabilityPlugin (registered in the root conftest) collects every
+      # @pytest.mark.req(...) marker, writes the matrix artifact, and — because
+      # DEXPACE_TRACEABILITY_GATE is set — fails the run if any MUST-level
+      # requirement in an enabled subsystem is neither covered by a marker nor
+      # listed N/A in docs/traceability-na-ids.txt (the deviations-ledger bridge).
+      - name: Run traceability audit (blocking)
+        env:
+          DEXPACE_TRACEABILITY_ENABLE: "seams,http,bodies,io,context,pipeline,recovery,redirect,retry,auth,xcut,serde,pagination,sse,observability,config,transport,async,nfr"
+          DEXPACE_TRACEABILITY_NA: docs/traceability-na-ids.txt
+          DEXPACE_TRACEABILITY_MATRIX: build/traceability-matrix.json
+          DEXPACE_TRACEABILITY_GATE: "1"
+        run: uv run pytest -q --co
+
+      - name: Upload traceability matrix
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: traceability-matrix-py${{ matrix.python-version }}
+          path: build/traceability-matrix.json
+          if-no-files-found: error
+
       - name: Run mypy
         run: uv run mypy --strict
 
@@ -45,3 +67,223 @@ jobs:
 
       - name: Run ruff format --check
         run: uv run ruff format --check
+
+      - name: Run import-linter
+        run: uv run lint-imports
+
+  packaging:
+    name: packaging invariants
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Check namespace layout
+        run: uv run --no-project python tools/check_namespace_packages.py
+
+      - name: Check MIT headers
+        run: uv run --no-project python tools/check_mit_headers.py
+
+      - name: Check runtime dependency budget
+        run: uv run --no-project python tools/check_dependency_audit.py
+
+      - name: Build core + stdlib wheels
+        run: |
+          uv build --package dexpace-sdk-core --wheel -o dist
+          uv build --package dexpace-sdk-http-stdlib --wheel -o dist
+
+      - name: Smoke-import wheels in a fresh venv
+        run: |
+          uv venv /tmp/wheel-smoke
+          uv pip install --python /tmp/wheel-smoke \
+            dist/dexpace_sdk_core-*.whl \
+            dist/dexpace_sdk_http_stdlib-*.whl
+          /tmp/wheel-smoke/bin/python tools/smoke_wheel_import.py
+
+  coverage:
+    name: coverage gate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Sync workspace
+        run: uv sync
+
+      # Blocking aggregate line+branch coverage gate. The 80% floor lives in
+      # [tool.coverage.report].fail_under in pyproject.toml; pytest-cov exits
+      # non-zero when the total drops below it.
+      - name: Run coverage gate
+        run: uv run pytest -q --cov --cov-report=term-missing
+
+  typecheck-divergence:
+    name: typecheck divergence (pyright, non-blocking)
+    runs-on: ubuntu-latest
+    # Advisory early-warning lane: pyright cross-checks mypy's verdict so a
+    # divergence between the two checkers surfaces early. This is NOT a gate —
+    # `mypy --strict` in the `test` job remains the sole blocking type check.
+    # `continue-on-error` at both the job and step level keeps a red result
+    # (e.g. pyright's stricter completeness scoring) from ever failing CI.
+    # pyright is layered in per-run via `uv run --with`, so it stays out of the
+    # committed dependency set and uv.lock.
+    continue-on-error: true
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+          python-version: "3.14"
+
+      - name: Sync workspace
+        run: uv sync
+
+      - name: pyright --verifytypes (advisory)
+        continue-on-error: true
+        run: uv run --with pyright pyright --verifytypes dexpace.sdk.core --ignoreexternal
+
+      - name: pyright typing-conformance corpus (advisory)
+        continue-on-error: true
+        run: uv run --with pyright pyright packages/dexpace-sdk-core/tests/typing_conformance.py
+
+  version-skew:
+    name: version skew (Python ${{ matrix.python-version }}, ${{ matrix.resolution }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+        resolution: ["highest", "lowest-direct"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      # Resolve the workspace at either edge of its declared dependency window.
+      # `highest` exercises the newest adapters against head core (the standard
+      # release runtime). `lowest-direct` pins every *direct* dependency to its
+      # declared floor: core to the compatible-release lower bound each adapter
+      # and the TCK pin (dexpace-sdk-core>=0.1,<0.2) and each transport to its
+      # minimum (httpx>=0.27, aiohttp>=3.9, requests>=2.32, furl>=2.1.3). Running
+      # both edges across Python 3.12-3.14 turns the forward-compatibility
+      # promise -- newest adapters and the generated petstore canary run against
+      # the oldest supported core -- into a passing pipeline, not a prose claim.
+      - name: Sync workspace (${{ matrix.resolution }} resolution)
+        run: uv sync --resolution ${{ matrix.resolution }}
+
+      # Newest adapters (built from HEAD) plus the TCK conformance battery, run
+      # against the resolved core. `--no-sync` keeps the environment exactly as
+      # the resolution step left it rather than re-resolving to the default edge.
+      - name: Adapters + TCK conformance
+        run: >
+          uv run --no-sync pytest -q
+          packages/dexpace-sdk-http-stdlib/tests
+          packages/dexpace-sdk-http-httpx/tests
+          packages/dexpace-sdk-http-aiohttp/tests
+          packages/dexpace-sdk-http-requests/tests
+          packages/dexpace-sdk-tck/src/dexpace/sdk/tck
+
+      # The petstore canary is the "generated at vN.M runs on vN.x" proof: a
+      # generated SDK driven end to end over the certified core. Running it at
+      # both dependency edges proves the generated output keeps working against
+      # both head core and the oldest supported core.
+      - name: Petstore canary
+        run: uv run --no-sync pytest -q examples/petstore/tests
+
+  free-threaded:
+    name: free-threaded CPython (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13t", "3.14t"]
+    # Exercises the codebase's explicit-lock claims (no GIL assumption) on a real
+    # GIL-disabled interpreter, not just under code review. Only the
+    # lock-sensitive core suites run here, and each spins real threads: the
+    # single-use body once-guards, the single-flight token cache, the
+    # ContextStore cap-drain, the emit-once logger latch, and the SSE
+    # cross-thread close. Core is pure Python (only furl), so the environment
+    # holds core plus the test runner alone -- no C-extension transports, which
+    # do not yet ship free-threaded wheels.
+    env:
+      # Fail loudly if an imported extension would force the GIL back on rather
+      # than silently re-enabling it and voiding the exercise.
+      PYTHON_GIL: "0"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+
+      - name: Install free-threaded interpreter
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Create free-threaded environment
+        run: uv venv --python ${{ matrix.python-version }} .venv-ft
+
+      # `--only-binary hypothesis` uses its universal wheel instead of building
+      # its sdist, whose build pulls a Rust/PyO3 toolchain with no free-threaded
+      # support yet. hypothesis is imported by the core test conftest.
+      - name: Install core + test runner
+        run: >
+          uv pip install --python .venv-ft --only-binary hypothesis
+          ./packages/dexpace-sdk-core
+          pytest pytest-asyncio hypothesis
+
+      - name: Verify the interpreter is GIL-disabled
+        run: .venv-ft/bin/python -c "import sys; assert not sys._is_gil_enabled(), 'GIL is enabled'; print(sys.version)"
+
+      - name: Run lock-sensitive suites (GIL disabled)
+        run: >
+          .venv-ft/bin/python -m pytest -q
+          packages/dexpace-sdk-core/tests/http/test_single_use_bodies.py
+          packages/dexpace-sdk-core/tests/auth/test_token_cache.py
+          packages/dexpace-sdk-core/tests/context/test_context_store.py
+          packages/dexpace-sdk-core/tests/instrumentation/test_logger.py
+          packages/dexpace-sdk-core/tests/sse/test_connection_lifecycle.py
+
+  version-source:
+    name: single version train
+    runs-on: ubuntu-latest
+    # One version train for every published package (NFR-14): the version lives
+    # once in each pyproject and is mirrored in uv.lock, and a built wheel
+    # carries that real version -- never a placeholder such as 0.0.0 or
+    # "unknown" (NFR-15). A bump touches all published packages together or this
+    # gate fails.
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Build a wheel to inspect its metadata version
+        run: uv build --package dexpace-sdk-core --wheel -o dist
+
+      - name: Verify one version train (pyproject + uv.lock + wheel)
+        run: uv run --no-project python tools/check_version_train.py --wheel-dir dist

.github/workflows/release.yml

@@ -0,0 +1,105 @@
+name: Release
+
+# Publishes the whole version train to PyPI via trusted publishing (OIDC), with
+# PEP 740 attestations and reproducible, byte-stable wheels. A tag push builds
+# and publishes; a manual run defaults to a dry run that builds and verifies the
+# artifacts without uploading anything.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Build and verify only; skip the PyPI upload."
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build + verify artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        # Full history so the commit timestamp is available for a reproducible
+        # SOURCE_DATE_EPOCH.
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      # Reproducible builds (NFR-12): pin every archive timestamp to the tagged
+      # commit's authored date and fix the hash seed so the build carries no
+      # run-to-run entropy. hatchling honours SOURCE_DATE_EPOCH and writes wheel
+      # entries in a stable order, so identical inputs yield byte-identical
+      # wheels.
+      - name: Pin reproducible-build environment
+        run: |
+          echo "SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)" >> "$GITHUB_ENV"
+          echo "PYTHONHASHSEED=0" >> "$GITHUB_ENV"
+
+      # Build each published distribution explicitly so the unpublished
+      # workspace root never lands in dist/. Sdists ship alongside wheels.
+      - name: Build wheels + sdists
+        run: |
+          for pkg in \
+            dexpace-sdk-core \
+            dexpace-sdk-http-stdlib \
+            dexpace-sdk-http-httpx \
+            dexpace-sdk-http-aiohttp \
+            dexpace-sdk-http-requests \
+            dexpace-sdk-tck; do
+            uv build --package "$pkg" --out-dir dist
+          done
+
+      # NFR-14/15: every artifact carries the single, real train version -- never
+      # a placeholder. Blocks the upload if any wheel disagrees.
+      - name: Verify one version train (pyproject + uv.lock + wheels)
+        run: uv run --no-project python tools/check_version_train.py --wheel-dir dist
+
+      - name: List artifacts
+        run: ls -1 dist | sort
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: publish to PyPI (trusted publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    # A tag push publishes; a manual run publishes only when dry_run is turned
+    # off. The default manual run is a build-and-verify dry run.
+    if: >-
+      github.event_name == 'push' ||
+      (github.event_name == 'workflow_dispatch' && github.event.inputs.dry_run == 'false')
+    environment:
+      name: pypi
+      url: https://pypi.org/project/dexpace-sdk-core/
+    permissions:
+      # OIDC token for PyPI trusted publishing; no long-lived API token needed.
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # PEP 740 provenance attestations, signed with the OIDC identity
+          # (NFR-16).
+          attestations: true
+          print-hash: true

.gitignore

@@ -83,3 +83,6 @@ dmypy.json
 
 # Cython debug symbols
 cython_debug/
+
+# Subagent-driven-development scratch (progress ledger, task briefs/reports)
+.superpowers/