build: install CI dependencies from a lockfile

.github/workflows/ci.yml

@@ -13,18 +13,29 @@ jobs:
         python-version: ['3.11', '3.12']
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+
+      # Dependencies come from uv.lock, so every run installs the same versions
+      # until the lock is deliberately refreshed (`uv lock --upgrade`). uv itself
+      # is pinned for the same reason: an unpinned toolchain is what turned CI
+      # red twice on an otherwise unchanged tree.
+      # Pinned to the exact release: setup-uv publishes no floating major tag
+      # above v7, and an exact tag is what this workflow is arguing for anyway.
+      - uses: astral-sh/setup-uv@v9.0.0
         with:
+          version: '0.11.32'
           python-version: ${{ matrix.python-version }}
+          enable-cache: true
 
-      - name: Install (core + dev + geo)
-        run: pip install -e ".[dev,geo]"
+      # --locked fails if uv.lock is stale with respect to pyproject.toml, so a
+      # dependency change cannot land without a refreshed lock.
+      - name: 'Install — locked (core + dev + geo)'
+        run: uv sync --locked --extra dev --extra geo
 
       - name: Lint (ruff)
-        run: ruff check .
+        run: uv run --no-sync ruff check .
 
       - name: Type-check (mypy)
-        run: mypy src
+        run: uv run --no-sync mypy src
 
       - name: Test (pytest)
-        run: pytest -q
+        run: uv run --no-sync pytest -q

CHANGELOG.md

@@ -8,6 +8,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **`uv.lock` — CI installs locked dependencies instead of resolving them.** The
+  workflow now runs `uv sync --locked --extra dev --extra geo`, and `--locked`
+  fails if the lock is stale with respect to `pyproject.toml`, so a dependency
+  change cannot land without a refreshed lock. The lock is universal and records a
+  resolution per Python version, which this project needs: numpy resolves to 2.4
+  on 3.11 and 2.5 on 3.12. uv and the setup-uv action are pinned exactly for the
+  same reason the ruff pin exists. Local `pip install -e ".[dev]"` is unaffected;
+  see [`docs/development.md`](docs/development.md#dependency-locking).
 - **`RasterKind.SEMANTIC`** — Effigies' per-pixel class field
   (`odm_semantic/orthophoto_semantic.tif`) is now a first-class intake product.
   It is tagged and deliberately not consumed; consuming it as a prior for the

docs/development.md

@@ -29,6 +29,31 @@ pytest              # tests
 
 Run all three before opening a pull request.
 
+## Dependency locking
+
+CI does not resolve dependencies. It installs from `uv.lock` with
+`uv sync --locked --extra dev --extra geo`, so a run is reproducible until the
+lock is deliberately refreshed. The lock is universal: it records a resolution
+per Python version, which matters here because numpy resolves differently on 3.11
+and 3.12.
+
+`--locked` fails if `uv.lock` is stale with respect to `pyproject.toml`. So when
+you change a dependency, refresh the lock in the same commit:
+
+```bash
+uv lock                     # after editing dependencies in pyproject.toml
+uv lock --upgrade           # deliberately pull newer versions
+uv lock --upgrade-package ruff
+```
+
+The local `pip install -e ".[dev]"` flow above still works and is not locked —
+convenient for day-to-day work, but CI is the authority on versions. If a lint or
+type error reproduces in CI and not locally, compare versions first.
+
+Toolchain versions (`ruff`, `uv`, the setup-uv action) are pinned exactly rather
+than by range. Linters change their rule sets between releases, and an unpinned
+one turned CI red twice on a tree nobody had touched.
+
 ## Project layout
 
 ```