build: harden 1.0 release validation

.github/workflows/build-and-test.yml

@@ -4,11 +4,11 @@ on:
   pull_request:
     branches:
       - main
-      - release/0.9.0
+      - release/1.0.0
   push:
     branches:
       - main
-      - release/0.9.0
+      - release/1.0.0
   workflow_dispatch:
 
 permissions:
@@ -23,11 +23,18 @@ jobs:
     name: Offline tests - Python ${{ matrix.python-version }}
     runs-on: ubuntu-latest
     strategy:
+      # Report every interpreter result instead of cancelling the matrix on the
+      # first failure, so a single-version incompatibility is easy to isolate.
+      fail-fast: false
+      # Python 3.15 is intentionally absent: it is still a prerelease during the
+      # 1.0 release work and is not claimed as a supported version.
       matrix:
         python-version:
           - "3.10"
           - "3.11"
           - "3.12"
+          - "3.13"
+          - "3.14"
 
     steps:
       - uses: actions/checkout@v4
@@ -55,10 +62,10 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python 3.12
+      - name: Set up Python 3.14
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: "3.14"
       - name: Install Poetry
         uses: snok/install-poetry@v1
         with:
@@ -70,8 +77,12 @@ jobs:
         run: |
           rm -rf dist
           poetry build
-      # Validates the built artifacts and a clean wheel installation.
-      # Runs outside the Poetry environment so the smoke test cannot import
-      # the repository checkout instead of the installed distribution.
+      # Validates artifact metadata, source-distribution contents, and a clean
+      # install of both the wheel and the source distribution. Runs outside the
+      # Poetry environment so the smoke tests cannot import the repository
+      # checkout instead of the installed distribution artifact.
       - name: Validate release artifacts
         run: python scripts/validate_release.py
+      # Metadata rendering check only; nothing is ever uploaded from CI.
+      - name: Twine check artifacts
+        run: poetry run twine check dist/*

README.md

@@ -39,6 +39,17 @@ For detailed documentation, check out the [Wiki](https://github.com/zero-sum-sea
 python3 -m pip install python-mlb-statsapi
 ```
 
+### Python support
+
+| Claim | Value |
+| --- | --- |
+| Minimum declared Python version (`Requires-Python`) | `>=3.10` |
+| CI-validated versions | 3.10, 3.11, 3.12, 3.13, 3.14 |
+
+The minimum declared Python version is 3.10 and the CI-validated versions are
+3.10 through 3.14. There is no upper Python bound. Prerelease interpreters are
+excluded from the required test matrix and are not claimed as supported.
+
 ## Quick Start
 ```python
 >>> import mlbstatsapi
@@ -480,9 +491,10 @@ poetry run pytest tests/
 rm -rf dist
 poetry build
 python3 scripts/validate_release.py
+poetry run twine check dist/*
 ```
 
-`scripts/validate_release.py` is the same release check offline CI runs. It inspects the built wheel and source distribution, installs the wheel into a temporary virtual environment, and runs a public-import smoke test against the installed package. It never contacts the MLB API.
+`scripts/validate_release.py` is the same release check offline CI runs. It inspects the built wheel and source distribution, clean-installs each artifact into its own temporary virtual environment, and runs the same public-API smoke test against both installed artifacts. The smoke test verifies the declared metadata, the supported package-root imports, the strict HTTP default, explicit strict and compatibility modes, the versioned `User-Agent`, and injected-Session ownership. Every response it observes comes from an injected fake Session, so it never contacts the MLB API.
 
 Offline CI is the normal pull-request gate. External tests are available manually, on a weekly schedule, and before releases.
 

docs/public-api.md

@@ -332,12 +332,18 @@ Caller-injected Session
 | Claim | Value |
 | --- | --- |
 | Minimum declared Python version (`Requires-Python`) | `>=3.10` |
-| Actively validated CI versions on this release branch | 3.10, 3.11, 3.12 |
+| CI-validated versions | 3.10, 3.11, 3.12, 3.13, 3.14 |
 | Later Python versions | May work, but are not claimed as CI-validated unless added to the matrix |
 
-Version 1.0 does not add an upper Python bound. Absence of Python 3.13 (or
-newer) CI coverage should be tracked under the release-validator / CI issue
-stream rather than silently claimed here.
+The minimum declared Python version is 3.10 and the CI-validated versions are
+3.10 through 3.14. Every version in that range runs the deterministic offline
+suite on each pull request and push to a watched branch. Prerelease
+interpreters are deliberately excluded from the required matrix and are not
+claimed as supported until they reach a stable release.
+
+Version 1.0 does not add an upper Python bound, and the declared runtime
+requirement stays `>=3.10`. Adding a new interpreter is a compatible change:
+extend the CI matrix and update this table in the same pull request.
 
 ## Mlb endpoint methods
 

docs/releases/1.0.0.md

@@ -186,8 +186,40 @@ Deterministic offline coverage documents the version 1.0 HTTP contract,
 including the strict default, explicit compatibility mode, warning behavior,
 404 return shapes, Session ownership, and retry exhaustion.
 
-`scripts/validate_release.py` remains the packaging smoke check for the built
-wheel and source distribution. It never contacts the MLB API.
+`scripts/validate_release.py` is the packaging check for the built artifacts. It
+clean-installs the wheel and the source distribution into separate throwaway
+virtual environments and runs the same installed-package smoke test against
+each, so a broken sdist build, a missing runtime dependency, or an omitted
+package file cannot hide behind a working wheel.
+
+Against the installed artifact the smoke test verifies:
+
+```text
+Declared metadata matches the built version
+Supported package-root imports resolve
+Strict HTTP handling is the default for Mlb() and MlbDataAdapter()
+A final 403 raises MlbHttpError with status, reason, method, URL, and payload
+strict_http=False returns the historical empty result and warns exactly once
+A library-created Session carries the versioned User-Agent and retry policy
+A caller-injected Session keeps its headers, adapters, and ownership
+```
+
+Every response the smoke test observes is produced by an injected fake Session,
+so release validation never contacts the MLB API. Continuous integration builds
+the artifacts, runs the validator, and runs `twine check` on both artifacts. No
+ordinary pull request or push path publishes anything.
+
+### Python support
+
+| Claim | Value |
+| --- | --- |
+| Minimum declared Python version (`Requires-Python`) | `>=3.10` |
+| CI-validated versions | 3.10, 3.11, 3.12, 3.13, 3.14 |
+
+The minimum declared Python version is 3.10 and the CI-validated versions are
+3.10 through 3.14. Version 1.0.0 adds no upper Python bound and does not change
+the declared runtime requirement. Prerelease interpreters are excluded from the
+required matrix and are not claimed as supported.
 
 ## Migration guidance