ci: install gating jobs from a constraints file exported from uv.lock (#194)

* ci: install gating jobs from a constraints file exported from uv.lock

CI resolved dependencies fresh on every run, so an upstream release could
turn main red overnight (numpy 2.5 broke median imputation this way), and
uv.lock had silently drifted from pyproject.toml since July.

- Refresh uv.lock (bumping the yanked build==1.5.1 pin) and export it as
  constraints/ci.txt (uv export --no-hashes --all-extras --no-emit-project).
- quality-fast, truthbench, nightly-online-large, large-data-status,
  coverage-badge and performance-large install with -c constraints/ci.txt.
- quality-fast type-checks after the tests, downgrading to numpy<2.5 only
  for mypy (NumPy 2.5 stubs need Python 3.12; mypy targets 3.10).
- test-matrix stays unpinned as the early warning for upstream breakage.
- New lockfile job fails when uv.lock or constraints/ci.txt is stale;
  `make constraints` refreshes both.

* test: expect the constraints install in the large performance workflow contract

The contract test asserted the exact pre-constraints install line in
performance-large.yml, so every test lane failed once the workflow began
installing with -c constraints/ci.txt.

Author: kevincostner17

.github/workflows/ci.yml

@@ -17,7 +17,30 @@ concurrency:
 permissions:
   contents: read
 
+# Dependency pinning: the gating jobs install with `-c constraints/ci.txt`
+# (exported from uv.lock), so an upstream release cannot turn CI red overnight.
+# test-matrix deliberately floats to the latest compatible releases: it is the
+# early warning for upstream breakage. Regenerate with `make constraints`.
+
 jobs:
+  lockfile:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - name: uv.lock and constraints/ci.txt are up to date
+        run: |
+          python -m pip install "uv==0.12.10"
+          uv lock --check
+          uv export --frozen --no-hashes --all-extras --no-emit-project --quiet -o constraints/ci.txt
+          if ! git diff --exit-code -- constraints/ci.txt; then
+            echo "::error::constraints/ci.txt is stale; run 'make constraints' and commit the result"
+            exit 1
+          fi
+
   quality-fast:
     runs-on: ubuntu-latest
     timeout-minutes: 20
@@ -30,14 +53,17 @@ jobs:
       - name: Install
         run: |
           python -m pip install --upgrade pip
-          # mypy targets Python 3.10; NumPy 2.5+ stubs require Python 3.12.
-          pip install -e ".[dev,ml]" "numpy<2.5"
+          pip install -c constraints/ci.txt -e ".[dev,ml]"
       - name: Lint
         run: ruff check .
-      - name: Typecheck
-        run: mypy src/freshdata
       - name: Test (required fast lane)
         run: pytest -m "not online and not large"
+      - name: Typecheck
+        # mypy targets Python 3.10; NumPy 2.5+ stubs require Python 3.12, so the
+        # type check runs against numpy<2.5 after the tests used the locked pin.
+        run: |
+          pip install "numpy<2.5"
+          mypy src/freshdata
 
   truthbench:
     runs-on: ubuntu-latest
@@ -51,7 +77,7 @@ jobs:
       - name: Install
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev,ml]"
+          pip install -c constraints/ci.txt -e ".[dev,ml]"
       - name: TruthBench PR ratchet
         # PRs must not regress any gate that passes in the committed
         # baseline.json; the known-red gates are release blockers and are
@@ -86,6 +112,8 @@ jobs:
           python-version: ${{ matrix.python-version }}
           cache: pip
       - name: Install
+        # Intentionally unpinned (no constraints file): this matrix tracks the
+        # latest releases each Python version resolves to.
         run: |
           python -m pip install --upgrade pip
           pip install -e ".[dev,ml]"
@@ -113,7 +141,7 @@ jobs:
       - name: Install
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev,ml]"
+          pip install -c constraints/ci.txt -e ".[dev,ml]"
       - name: Nightly online/large drift checks
         # --no-cov: this lane deliberately runs ~20 tests, so the repo-wide
         # --cov-fail-under=93 inherited from addopts can never be met here.
@@ -159,7 +187,7 @@ jobs:
       - name: Install
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev,ml]"
+          pip install -c constraints/ci.txt -e ".[dev,ml]"
       - name: Assert the large/online lane still collects tests
         run: |
           N=$(pytest -m "online or large or tier1" --collect-only -q -o addopts="" \
@@ -210,7 +238,7 @@ jobs:
       - name: Install
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev,ml]"
+          pip install -c constraints/ci.txt -e ".[dev,ml]"
       - name: Compute coverage and write badge JSON
         run: |
           pytest -m "not online and not large and not tier1" \

.github/workflows/performance-large.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Install benchmark dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev,bench,ml]"
+          pip install -c constraints/ci.txt -e ".[dev,bench,ml]"
 
       - name: Run large performance matrix
         id: benchmark

Makefile

@@ -6,7 +6,8 @@ PY ?= python
 # cannot be .PHONY; the delegated targets are .PHONY inside training/Makefile).
 .PHONY: help benchmark benchmark-ci benchmark-report benchmark-fixtures benchmark-test \
         cleanbench-full truthbench-release truthbench-pr automation-pr performance-ci \
-        performance-baseline performance-profile performance-report coverage-report
+        performance-baseline performance-profile performance-report coverage-report \
+        constraints
 
 help:
 	@echo "Targets:"
@@ -25,6 +26,13 @@ help:
 	@echo "  performance-report Analyze and render compact performance evidence"
 	@echo "  coverage-report     Show per-module coverage for the fast test lane"
 	@echo "  training-*          Phase-5 training pipeline (see training/Makefile)"
+	@echo "  constraints         Refresh uv.lock and the pinned constraints/ci.txt CI installs with"
+
+# Refresh the lockfile and the pip constraints the gating CI jobs install with.
+# The CI `lockfile` job fails when either is stale; commit both after running.
+constraints:
+	uv lock
+	uv export --frozen --no-hashes --all-extras --no-emit-project --quiet -o constraints/ci.txt
 
 # Run the same test scope as the required PR lane and print uncovered lines for
 # every measured module so contributors can identify useful testing targets.