fix(ci): improve mypyc build testing and failure detection (#461)

* fix(ci): build Windows + macOS mypyc wheels natively; harden smoke install

v0.47.0 release (run 26351509901) failed every Windows + macOS test-wheels
job because `build-wheels-mypyc` ran on ubuntu-latest, where cibuildwheel
silently ignores `CIBW_ARCHS_WINDOWS` / `CIBW_ARCHS_MACOS`. Only Linux
wheels have ever been published; the test step then fell back to PyPI
(`uv pip install --find-links` permits index fallback when no local wheel
matches), installed pure-Python 0.46.3, and `mypyc_smoke.py --require-compiled`
(added in PR #446) correctly reported every module as interpreted and exit 1.

Changes
- publish.yml: split build-wheels-mypyc into a per-OS matrix
  (ubuntu × macos × windows) × (3.10-3.14). QEMU gated to Linux only.
  Linux + macOS keep three-stage PGO; macOS PGO blocks finally execute.
  Windows runs plain mypyc (MSVC PGO is not validated here).
  Artifacts now named `wheels-mypyc-<os>-py<ver>`.
- publish.yml + test-build.yml test-wheels: install with `--no-index`
  so missing wheels fail loudly. Assert `sqlspec.__version__` matches
  the release tag (or pyproject.toml on PRs) before running smoke.
- test-build.yml: mirror the per-OS matrix; PR-default (`test_matrix=subset`)
  stays ubuntu-only for fast feedback; `workflow_dispatch test_matrix=full`
  exercises all 15 build legs + 9 test legs.
- All workflows: enable `setup-uv@v7` cache keyed on `uv.lock`.
- publish.yml + test-build.yml: cache pip downloads + the pinned
  `HATCH_MYPYC_BUILD_DIR` per (OS, python). PGO profile data is not cached.
- ci.yml: cache the pre-pulled docker image tarball
  (`docker save`/`docker load`) keyed on the ci.yml hash.

Beads: sqlspec-tt2h (epic), sqlspec-8xun (T1) / sqlspec-1jv0 (T2)
       / sqlspec-2xh7 (T3) / sqlspec-qr1u (T4) / sqlspec-b5mq (T5)
       / sqlspec-v9mb (T6)

* fix(ci): fall back to pyproject.toml for publish.yml version assert

`Resolve expected version` reads `github.event.release.tag_name`, which is
empty when publish.yml is triggered via workflow_dispatch. The empty value
made the install string `sqlspec==` (malformed) and broke manual reruns.

Fall back to the version in pyproject.toml when no release tag is present.
The `release: published` path is unchanged.

* ci: auto-promote test-build.yml to full matrix on build-infra PRs

Subset mode (linux x py3.12) stays the default for fast PR feedback, but a
preflight detect-mode job now promotes the build + test matrix to full
(3 OS x 5 py builds, 3 OS x 3 py tests) when the PR diff touches any of:

  .github/workflows/*.yml
  pyproject.toml
  uv.lock
  tools/scripts/pgo_training.py
  tools/scripts/mypyc_smoke.py

That's the exact set of files where a matrix-shape regression like the
0.47.0 release (Linux-only wheels published) could land. workflow_dispatch
test_matrix=full still works as an explicit override.

* fix(ci): use {project} placeholder in CIBW_BEFORE_BUILD on macOS

cibuildwheel runs Linux builds inside a container that mounts the source
at /project. macOS and Windows run natively on the host with no such
mount, so `/project/build-constraints.txt` and `/project/tools/...` do
not exist there. The macOS PGO BEFORE_BUILD block had four such literals;
it was latent until the per-OS matrix split started actually executing
on a macOS runner, where pip would fail with "Could not find file".

Switch every `/project/` inside CIBW_BEFORE_BUILD_{LINUX,MACOS} to the
cibuildwheel `{project}` placeholder, which resolves to /project inside
the Linux container and to the host project path on macOS. Same change
mirrored into test-build.yml.

The PyPI publish URL (https://pypi.org/project/sqlspec/) is unrelated
and untouched.

* fix(ci): drop PGO from macOS + Windows; Linux keeps three-stage PGO

macOS PGO consistently failed at `llvm-profdata merge` because
pgo_training.py's workloads report "filters not installed" (the script's
optional filter deps aren't present in the cibuildwheel BEFORE_BUILD env)
→ instrumented binary never emits .profraw files → merge has no input.

Rather than debug the filter import path, drop PGO from macOS + Windows:
both now use the base CIBW_BEFORE_BUILD (install hatch-mypyc + hatchling)
and a plain mypyc env with HATCH_BUILD_HOOKS_ENABLE + MYPYC_* flags.
macOS still pins HATCH_MYPYC_BUILD_DIR so the mypyc compile cache
(actions/cache, T5) still hits across runs.

Linux retains the full three-stage PGO build unchanged — that's where
the perf benefit measured in CI is and stays.

* fix(ci): unpin macOS mypyc build dir; pre-warm Defender on Windows

macOS:
  hatch_mypyc.plugin.initialize() calls os.mkdir(BUILD_DIR/build) — not
  os.makedirs — so the parent must already exist. The Linux PGO
  BEFORE_BUILD creates it explicitly; the (now removed) macOS PGO
  BEFORE_BUILD did the same. With both gone, pinning
  HATCH_MYPYC_BUILD_DIR=/tmp/sqlspec-mypyc-build pointed hatch-mypyc at
  a missing parent and the build crashed with FileNotFoundError. Unpin
  the var — hatch-mypyc falls back to its default per-project temp dir,
  which it creates as needed. Also drop macOS from the actions/cache
  step since the pinned path is no longer used there.

Windows:
  virtualenv's interpreter discovery times out at ~10s on the freshly
  extracted nuget-cpython python.exe because Windows Defender real-time
  protection scans the binary on its first invocation. Add Defender
  exclusions for cibuildwheel's cache dir, the runner temp dir, and
  python.exe via a Windows-only pre-step. -ErrorAction SilentlyContinue
  so future tamper-protection changes don't break the job.

* ci: trim mypyc wheel matrix to python 3.12 across all 3 OSes

15 build legs (3 OS × 5 py) was too much CI footprint for an initial
release that's first turning on Windows + macOS. Trim to 3 build legs
(linux py3.12, macos py3.12, windows py3.12) + 3 test legs. Users on
other Python versions install the pure-Python sqlspec-*-py3-none-any.whl
fallback that build-wheels-standard still produces.

Same trim mirrored into test-build.yml (full mode is now identical to
subset's py3.12 baseline for python-version; only the os list differs).
Expand back to 3.10–3.14 once py3.12 is known stable across all 3 OSes.

* ci: split matrices — full sweep on release, single-py on PR (configurable)

publish.yml (release):
  Restore full sweep — 3 OS × 5 py for builds (3.10–3.14), 3 OS × 3 py
  for test-wheels (3.10/3.12/3.14 sampling matches the pre-trim shape).
  Every published release exercises every supported Python.

test-build.yml (PR / workflow_dispatch):
  Stay on a single Python version per run (default 3.12). Add a new
  `python_version` workflow_dispatch input with a choice of 3.10–3.14
  for manual overrides when you want to validate a specific interpreter.
  Build + test matrices read the input, falling back to '3.12' for
  pull_request triggers (where workflow_dispatch inputs are empty).
  detect-mode's OS auto-promotion (linux subset vs full 3-OS) is
  unchanged — orthogonal to the python-version choice.

* ci: cancel in-flight runs on the same ref to stop wasting runner minutes

Pre-existing gap (main never had concurrency either): pushing a new
commit to a PR branch left the previous Tests And Linting + Test Build
Configuration runs queued/running alongside the new ones. With several
quick pushes during a debugging session that compounded into 3–5
parallel runs per workflow per branch.

Add concurrency: { group: ${{ github.workflow }}-${{ github.ref }},
cancel-in-progress: true } to ci.yml, test-build.yml, docs.yml.

NOT applied to publish.yml: a release upload mid-cancel could leave
PyPI in a partial state (some wheels uploaded, others not). Releases
stay all-or-nothing as before — see the `needs:` chain on
publish-release. pgo-validate.yml and pr-title.yml left alone too
(manual-only / quick lint, low impact).

* ci(windows): exclude wheelhouse + workspace from Defender

Defender's real-time scan was holding the freshly-built .whl file handle
when actions/upload-artifact@v7 opened it for chunked upload, causing
the step to silently terminate after pre-flight validation with no
error logged. macOS used the same action version and succeeded.

Extend the pre-warm exclusion list to cover GITHUB_WORKSPACE and the
wheelhouse output directory so the artifact file isn't being scanned
when the action reads it.

* ci(test-build): drop aarch64 from PR validation matrix

aarch64 cross-build under QEMU + PGO three-stage hangs for >1h per leg
on PR runners. publish.yml already covers the full cross-arch matrix
at release time, so PR validation is pure duplication.

Strip QEMU setup and force host-arch-only builds: x86_64 on Linux,
arm64 on macos-latest (now Apple Silicon native), AMD64 on Windows.

* ci(publish): build aarch64 on native ARM runner instead of QEMU

The aarch64 cross-build under QEMU + PGO three-stage hangs for hours
per leg, putting every Linux publish job at risk of the 6-hour cap.
GitHub now offers ubuntu-24.04-arm (native ARM runner, free for
public repos), making QEMU emulation unnecessary.

Add ubuntu-24.04-arm to the build matrix and make CIBW_ARCHS_LINUX
conditional on which runner is executing. Drop the QEMU setup step.
Drop macOS x86_64 (macos-latest is Apple Silicon native; x86_64
would need Rosetta and isn't worth the build minutes — pure-Python
wheel covers Intel Macs). Add ubuntu-24.04-arm to test-wheels so
the ARM wheel is actually validated before publish.

Build matrix grows from 15 → 20 legs but each leg now runs at native
speed (~10–20 min) instead of QEMU-emulated hours.

* ci(test-wheels): resolve transitive deps from PyPI

Splitting the install into two steps preserves the no-silent-fallback
guarantee for sqlspec itself while letting runtime deps like
mypy-extensions, sqlglot, etc. resolve from PyPI.

Step 1: --no-index --no-deps --find-links — sqlspec wheel MUST come
from the local artifact bundle (this is the safety check).

Step 2: same install without --no-index — fills in transitive runtime
deps from PyPI; sqlspec itself is already installed and won't reresolve.

Author: cofin

.github/workflows/ci.yml

@@ -6,6 +6,13 @@ on:
     branches:
       - main
 
+# Cancel in-flight runs of this workflow on the same ref when a newer
+# commit lands. Saves runner minutes during a churn of PR pushes. Not
+# applied to publish.yml — releases must never be cancelled mid-upload.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   validate:
     runs-on: ubuntu-latest
@@ -14,6 +21,9 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
 
       - name: Set up Python
         run: uv python install 3.11
@@ -41,6 +51,9 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
 
       - name: Set up Python
         run: uv python install 3.11
@@ -58,6 +71,9 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
 
       - name: Set up Python
         run: uv python install 3.11
@@ -75,6 +91,9 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
 
       - name: Set up Python
         run: uv python install 3.11
@@ -98,14 +117,29 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
 
       - name: Set up Python
         run: uv python install ${{ matrix.python-version }}
 
       - name: Install dependencies
         run: uv sync --all-extras --dev
 
+      - name: Cache docker images
+        id: docker-image-cache
+        uses: actions/cache@v5
+        with:
+          path: /tmp/docker-images
+          key: docker-images-v1-${{ hashFiles('.github/workflows/ci.yml') }}
+
+      - name: Load cached docker images
+        if: steps.docker-image-cache.outputs.cache-hit == 'true'
+        run: docker load -i /tmp/docker-images/sqlspec-test-images.tar
+
       - name: Pre-pull docker images
+        if: steps.docker-image-cache.outputs.cache-hit != 'true'
         run: |
           set -eu
           images=(
@@ -121,6 +155,8 @@ jobs:
             rustfs/rc:latest
           )
           printf '%s\n' "${images[@]}" | xargs -P 4 -I{} docker pull {}
+          mkdir -p /tmp/docker-images
+          docker save "${images[@]}" -o /tmp/docker-images/sqlspec-test-images.tar
 
       - name: Test
         id: pytest
@@ -230,6 +266,9 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
 
       - name: Set up Python
         run: uv python install 3.12

.github/workflows/docs.yml

@@ -8,6 +8,13 @@ on:
 permissions:
   contents: read
 
+# Cancel in-flight runs of this workflow on the same ref when a newer
+# commit lands. Saves runner minutes during a churn of PR pushes. Not
+# applied to publish.yml — releases must never be cancelled mid-upload.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -16,6 +23,9 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
 
       - name: Set up Python
         run: uv python install 3.12

.github/workflows/publish.yml

@@ -15,6 +15,9 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
 
       - name: Set up Python
         run: uv python install 3.12
@@ -40,6 +43,9 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
 
       - name: Set up Python 3.12
         run: uv python install 3.12
@@ -57,65 +63,97 @@ jobs:
           path: dist/*.whl
 
   build-wheels-mypyc:
-    name: Build MyPyC+PGO wheels for all platforms
-    runs-on: ubuntu-latest
+    name: Build MyPyC wheels (${{ matrix.os }} py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
+        os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest, windows-latest]
         python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
       - name: Check out repository
         uses: actions/checkout@v6
 
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4
-        with:
-          platforms: all
-
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
 
       - name: Export build constraints from uv.lock
         run: uv export --frozen --no-emit-project --no-hashes --format requirements.txt --output-file build-constraints.txt
 
+      - name: Cache pip downloads
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cache/pip
+            ~/Library/Caches/pip
+            ~\AppData\Local\pip\Cache
+          key: pip-${{ runner.os }}-py${{ matrix.python-version }}-${{ hashFiles('build-constraints.txt') }}
+          restore-keys: |
+            pip-${{ runner.os }}-py${{ matrix.python-version }}-
+
+      # mypyc compile cache only useful on PGO hosts where HATCH_MYPYC_BUILD_DIR
+      # is pinned. Windows + macOS build without PGO and without a pinned build dir.
+      - name: Cache mypyc build dir
+        if: startsWith(matrix.os, 'ubuntu')
+        uses: actions/cache@v5
+        with:
+          path: /tmp/sqlspec-mypyc-build
+          key: mypyc-${{ matrix.os }}-py${{ matrix.python-version }}-${{ hashFiles('sqlspec/**/*.py', 'pyproject.toml') }}
+          restore-keys: |
+            mypyc-${{ matrix.os }}-py${{ matrix.python-version }}-
+
+      - name: Pre-warm Windows Defender exclusions
+        if: matrix.os == 'windows-latest'
+        shell: pwsh
+        run: |
+          # Defender's real-time scan on the freshly-extracted nuget-cpython
+          # python.exe blocks virtualenv discovery past its 10s timeout.
+          Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\pypa\cibuildwheel" -ErrorAction SilentlyContinue
+          Add-MpPreference -ExclusionPath "$env:TEMP" -ErrorAction SilentlyContinue
+          Add-MpPreference -ExclusionPath "$env:GITHUB_WORKSPACE" -ErrorAction SilentlyContinue
+          Add-MpPreference -ExclusionPath "$env:GITHUB_WORKSPACE\wheelhouse" -ErrorAction SilentlyContinue
+          Add-MpPreference -ExclusionProcess "python.exe" -ErrorAction SilentlyContinue
+
       - name: Install cibuildwheel
         run: python -m pip install cibuildwheel
 
       - name: Build wheels with cibuildwheel
         run: python -m cibuildwheel --output-dir wheelhouse
         env:
-          # Configure cibuildwheel
           CIBW_BUILD: "cp${{ matrix.python-version == '3.10' && '310' || matrix.python-version == '3.11' && '311' || matrix.python-version == '3.12' && '312' || matrix.python-version == '3.13' && '313' || matrix.python-version == '3.14' && '314' }}-*"
           CIBW_BUILD_VERBOSITY: 1
 
-          # Platform configuration - comprehensive coverage with QEMU emulation
-          CIBW_ARCHS_LINUX: "x86_64 aarch64"
-          CIBW_ARCHS_MACOS: "x86_64 arm64"
+          # Native host arch only — Linux aarch64 builds on ubuntu-24.04-arm,
+          # macOS arm64 on macos-latest (Apple Silicon). No QEMU emulation.
+          CIBW_ARCHS_LINUX: ${{ matrix.os == 'ubuntu-24.04-arm' && 'aarch64' || 'x86_64' }}
+          CIBW_ARCHS_MACOS: "arm64"
           CIBW_ARCHS_WINDOWS: "AMD64"
 
-          # Skip problematic combinations
           CIBW_SKIP: "cp39-win_arm64 *-musllinux*"
 
-          # Install build dependencies (base, overridden per-platform below).
-          # build-constraints.txt is produced from uv.lock so hatch-mypyc / mypy / hatchling
-          # versions match the locked dev environment and can't drift on each cibw run.
-          CIBW_BEFORE_BUILD: "pip install -c /project/build-constraints.txt hatch-mypyc hatchling"
+          # Base build deps; PGO blocks below override on Linux + macOS.
+          # build-constraints.txt is produced from uv.lock so hatch-mypyc / mypy /
+          # hatchling versions track the locked dev environment.
+          CIBW_BEFORE_BUILD: "pip install -c {project}/build-constraints.txt hatch-mypyc hatchling"
 
-          # Test the built wheels
           CIBW_TEST_REQUIRES: "cloud-sql-python-connector google-cloud-alloydb-connector"
           CIBW_TEST_COMMAND: >-
-            python /project/tools/scripts/mypyc_smoke.py --require-compiled
+            python {project}/tools/scripts/mypyc_smoke.py --require-compiled
 
           # ── Linux (GCC): PGO three-stage build ──
           # Stage 1 (instrumented build) + Stage 2 (training) run in BEFORE_BUILD.
           # Stage 3 (optimized build) is the main cibuildwheel build with -fprofile-use.
           # HATCH_MYPYC_BUILD_DIR pins the build directory so profile data paths match.
           CIBW_BEFORE_BUILD_LINUX: >-
-            pip install -c /project/build-constraints.txt hatch-mypyc hatchling &&
+            pip install -c {project}/build-constraints.txt hatch-mypyc hatchling &&
             PGO_DIR=/tmp/sqlspec-pgo &&
             BUILD_DIR=/tmp/sqlspec-mypyc-build &&
             mkdir -p "$PGO_DIR" "$BUILD_DIR" &&
@@ -125,7 +163,7 @@ jobs:
             MYPYC_OPT_LEVEL=3 MYPYC_DEBUG_LEVEL=0 MYPYC_MULTI_FILE=1
             pip install {package} --no-build-isolation &&
             pip install anyio pyarrow aiosqlite duckdb adbc-driver-sqlite adbc-driver-manager &&
-            python /project/tools/scripts/pgo_training.py &&
+            python {project}/tools/scripts/pgo_training.py &&
             pip uninstall -y sqlspec &&
             rm -rf "$BUILD_DIR/build" "$BUILD_DIR/tmp"
 
@@ -135,57 +173,62 @@ jobs:
             MYPYC_OPT_LEVEL=3 MYPYC_DEBUG_LEVEL=0 MYPYC_MULTI_FILE=1
             CFLAGS="-fprofile-use=/tmp/sqlspec-pgo -fprofile-correction -Wno-error=missing-profile -Wno-error=coverage-mismatch"
 
-          # ── macOS (Clang): PGO three-stage build ──
-          CIBW_BEFORE_BUILD_MACOS: >-
-            pip install -c /project/build-constraints.txt hatch-mypyc hatchling &&
-            PGO_DIR=/tmp/sqlspec-pgo &&
-            BUILD_DIR=/tmp/sqlspec-mypyc-build &&
-            mkdir -p "$PGO_DIR" "$BUILD_DIR" &&
-            CFLAGS="-fprofile-instr-generate=$PGO_DIR/default_%m.profraw"
-            HATCH_BUILD_HOOKS_ENABLE=1
-            HATCH_MYPYC_BUILD_DIR="$BUILD_DIR"
-            MYPYC_OPT_LEVEL=3 MYPYC_DEBUG_LEVEL=0 MYPYC_MULTI_FILE=1
-            pip install {package} --no-build-isolation &&
-            pip install anyio pyarrow aiosqlite duckdb adbc-driver-sqlite adbc-driver-manager &&
-            python /project/tools/scripts/pgo_training.py &&
-            xcrun llvm-profdata merge -o "$PGO_DIR/merged.profdata" "$PGO_DIR"/*.profraw &&
-            pip uninstall -y sqlspec &&
-            rm -rf "$BUILD_DIR/build" "$BUILD_DIR/tmp"
-
+          # ── macOS (Clang): plain mypyc, no PGO ──
+          # PGO was attempted but pgo_training.py needs optional filter deps
+          # that are absent in the cibuildwheel BEFORE_BUILD env (every workload
+          # logs "skipped (filters not installed)" → no .profraw files emitted
+          # → llvm-profdata merge fails). Falls back to the base CIBW_BEFORE_BUILD,
+          # which just installs hatch-mypyc + hatchling and lets cibuildwheel
+          # run the normal frontend build with the mypyc env below.
           CIBW_ENVIRONMENT_MACOS: >-
             HATCH_BUILD_HOOKS_ENABLE=1
-            HATCH_MYPYC_BUILD_DIR=/tmp/sqlspec-mypyc-build
             MYPYC_OPT_LEVEL=3 MYPYC_DEBUG_LEVEL=0 MYPYC_MULTI_FILE=1
-            CFLAGS="-fprofile-instr-use=/tmp/sqlspec-pgo/merged.profdata"
 
-          # ── Windows (MSVC): No PGO, standard mypyc build ──
+          # ── Windows (MSVC): plain mypyc, no PGO ──
           CIBW_ENVIRONMENT_WINDOWS: >-
             HATCH_BUILD_HOOKS_ENABLE=1
             MYPYC_OPT_LEVEL=3 MYPYC_DEBUG_LEVEL=0 MYPYC_MULTI_FILE=1
 
       - name: Upload wheel artifacts
         uses: actions/upload-artifact@v7
         with:
-          name: wheels-mypyc-py${{ matrix.python-version }}
+          name: wheels-mypyc-${{ matrix.os }}-py${{ matrix.python-version }}
           path: wheelhouse/*.whl
 
-
   test-wheels:
     name: Test ${{ matrix.os }} py${{ matrix.python-version }}
     needs: [build-wheels-standard, build-wheels-mypyc]
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
+        os: [ubuntu-latest, ubuntu-24.04-arm, windows-latest, macos-latest]
         python-version: ["3.10", "3.12", "3.14"]
 
     runs-on: ${{ matrix.os }}
     steps:
       - name: Check out repository
         uses: actions/checkout@v6
 
+      # Route untrusted release tag through an env var (not direct ${{ … }}
+      # interpolation into the shell) to avoid command injection. Fall back
+      # to pyproject.toml when triggered via workflow_dispatch (no release
+      # context) so manual reruns still have a version to assert against.
+      - name: Resolve expected version
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          tag="${RELEASE_TAG#v}"
+          if [ -z "$tag" ]; then
+            tag=$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+          fi
+          echo "SQLSPEC_EXPECTED_VERSION=$tag" >> "$GITHUB_ENV"
+
       - name: Install uv
         uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
 
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
@@ -203,16 +246,26 @@ jobs:
           merge-multiple: true
           path: dist-mypyc/
 
+      # Install sqlspec from local wheels only (--no-index + --no-deps) so any
+      # missing host wheel fails loudly instead of silently grabbing a stale
+      # PyPI release. Transitive deps resolve from PyPI in a separate step.
+      # The version assert catches drift between pyproject.toml and the wheel.
       - name: Test standard wheel installation
+        shell: bash
         run: |
           uv venv test-standard --python ${{ matrix.python-version }}
-          uv pip install --python test-standard --find-links dist-standard/ sqlspec
+          uv pip install --python test-standard --no-index --no-deps --find-links dist-standard/ "sqlspec==${SQLSPEC_EXPECTED_VERSION}"
+          uv pip install --python test-standard "sqlspec==${SQLSPEC_EXPECTED_VERSION}" --find-links dist-standard/
+          uv run --no-project --python test-standard python -I -c "import sqlspec, os, sys; v=sqlspec.__version__; e=os.environ['SQLSPEC_EXPECTED_VERSION']; sys.exit(0 if v == e else (sys.stderr.write(f'version mismatch: got {v}, expected {e}\n') or 1))"
           uv run --no-project --python test-standard python -I -c "import sqlspec; print('Standard wheel OK')"
 
       - name: Test mypyc wheel installation
+        shell: bash
         run: |
           uv venv test-mypyc --python ${{ matrix.python-version }}
-          uv pip install --python test-mypyc --find-links dist-mypyc/ sqlspec
+          uv pip install --python test-mypyc --no-index --no-deps --find-links dist-mypyc/ "sqlspec==${SQLSPEC_EXPECTED_VERSION}"
+          uv pip install --python test-mypyc "sqlspec==${SQLSPEC_EXPECTED_VERSION}" --find-links dist-mypyc/
+          uv run --no-project --python test-mypyc python -I -c "import sqlspec, os, sys; v=sqlspec.__version__; e=os.environ['SQLSPEC_EXPECTED_VERSION']; sys.exit(0 if v == e else (sys.stderr.write(f'version mismatch: got {v}, expected {e}\n') or 1))"
           uv run --no-project --python test-mypyc python -I tools/scripts/mypyc_smoke.py --require-compiled
 
   publish-release:
@@ -228,6 +281,9 @@ jobs:
     steps:
       - name: Install uv
         uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
 
       - name: Download all artifacts
         uses: actions/download-artifact@v7