python-test.yml

name: Python test / linting

permissions:
  contents: read

env:
  RUSTFLAGS: -C debuginfo=0
  RUST_BACKTRACE: 1
  PYTHONUTF8: 1
  LLVM_VERSION: "21.1"
  LLVM_RELEASE_VERSION: "21.1.8"
  # Force the MWPF decoder feature on in CI so we exercise the cmake-dependent
  # build path and catch regressions. GitHub-hosted runners ship cmake.
  PECOS_BUILD_MWPF: "1"
  CARGO_HTTP_MULTIPLEXING: "false"
  CARGO_NET_GIT_FETCH_WITH_CLI: "true"
  CARGO_NET_RETRY: "10"

on:
  push:
    tags: [ "py-*", "jl-*", "rs-*" ]
    branches: [ "main", "master", "development", "dev" ]
    paths:
      - 'python/**'
      - 'examples/**'
      - 'crates/**'
      - 'exp/zlup/**'
      - 'exp/zluppy/**'
      - 'Cargo.toml'
      - 'Cargo.lock'
      - 'pyproject.toml'
      - 'uv.lock'
      - 'Justfile'
      - 'scripts/ci/**'
      - 'scripts/win-msvc-bootstrap.ps1'
      - 'scripts/check_python_workspace.py'
      - '.github/uv.toml'
      - '.github/workflows/python-test.yml'
  pull_request:
    branches: [ "main", "master", "development", "dev" ]
    paths:
      - 'python/**'
      - 'examples/**'
      - 'crates/**'
      - 'exp/zlup/**'
      - 'exp/zluppy/**'
      - 'Cargo.toml'
      - 'Cargo.lock'
      - 'pyproject.toml'
      - 'uv.lock'
      - 'Justfile'
      - 'scripts/ci/**'
      - 'scripts/win-msvc-bootstrap.ps1'
      - 'scripts/check_python_workspace.py'
      - '.github/uv.toml'
      - '.github/workflows/python-test.yml'
  workflow_dispatch:
  # Measured 5-9 h delays shift this stagger outside working hours;
  # spread runner demand across the repository's five macOS slots.
  schedule:
    - cron: "37 21 * * *"

concurrency:
  # Pull requests cancel superseded runs. Every other event (a push to a main
  # branch, a schedule, a dispatch) gets its own group so no trunk commit loses
  # its validation or cache save to a later merge.
  group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
  cancel-in-progress: true

defaults:
  run:
    shell: bash

jobs:
  python-lint:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
    - name: Harden the runner (egress audit)
      uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
      with:
        egress-policy: audit

    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      with:
        persist-credentials: false

    - name: Set up Python
      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
      with:
        python-version: "3.12"

    - name: Install the latest version of uv
      uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      with:
        version-file: ".github/uv.toml"
        enable-cache: true
        save-cache: ${{ github.event_name == 'push' && contains(fromJSON('["main", "master", "development", "dev"]'), github.ref_name) }}

    - name: Set up Rust
      run: |
        bash scripts/ci/ensure-rust.sh stable minimal
        export PATH="$HOME/.cargo/bin:$PATH"
        rustup show

    - name: Install just
      uses: taiki-e/install-action@8cca0918f8471c33515202b73f56ab27f2bed283 # v2.87.29
      with:
        tool: just@1.59.0
        fallback: none

    - name: Cache Rust
      uses: Swatinem/rust-cache@c8037a86dde8214a8310e9f54a8fc61ab362aa31 # v2
      with:
        cache-bin: false
        prefix-key: v1-rust-no-bin
        # Restore-only: python-core (above) saves this key on dev pushes.
        save-if: false
        # The rslib crates are members of the root Cargo workspace and build
        # into the top-level target/, so cache the root workspace (the default)
        # and share the python-core key: same crates, same profile, same env.
        shared-key: python-core

    - name: Cache LLVM ${{ env.LLVM_VERSION }}
      id: cache-llvm
      uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
      with:
        path: ~/.pecos/deps/llvm-21.1
        key: llvm-${{ env.LLVM_RELEASE_VERSION }}-${{ runner.os }}-${{ runner.arch }}-v3

    - name: Ensure LLVM ${{ env.LLVM_VERSION }}
      run: just ci-env

    - name: Save LLVM ${{ env.LLVM_VERSION }} cache
      if: steps.cache-llvm.outputs.cache-hit != 'true' && github.event_name == 'push' && contains(fromJSON('["main", "master", "development", "dev"]'), github.ref_name)
      uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
      with:
        path: ~/.pecos/deps/llvm-21.1
        key: ${{ steps.cache-llvm.outputs.cache-primary-key }}

    - name: Sync Python dependencies
      run: just python-ci-sync-lint

    - name: Verify Rust source distributions
      run: uv run --frozen --no-sync python scripts/ci/check_rust_sdists.py

    - name: Run linting
      run: just python-ci-lint

  python-core:
    # Post-merge only. Pull requests get this suite from the required PR core gate
    # and the lockfile checks from python-lint.
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    # Use the same complete partition as the PR gate: the unsharded suite
    # exceeds 75 minutes on trunk. Keep every shard running after a failure.
    strategy:
      fail-fast: false
      matrix:
        shard: [qec-surface-harvest, qec-surface, qec-guppy, rest]
    timeout-minutes: 75
    steps:
    - name: Harden the runner (egress audit)
      uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
      with:
        egress-policy: audit

    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      with:
        persist-credentials: false

    - name: Set up Python
      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
      with:
        python-version: "3.12"

    - name: Install the latest version of uv
      uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      with:
        version-file: ".github/uv.toml"
        enable-cache: true
        save-cache: ${{ github.event_name == 'push' && contains(fromJSON('["main", "master", "development", "dev"]'), github.ref_name) }}

    - name: Set up Rust
      run: |
        bash scripts/ci/ensure-rust.sh stable minimal
        export PATH="$HOME/.cargo/bin:$PATH"
        rustup show

    - name: Verify cmake is available (MWPF decoder build)
      run: cmake --version

    - name: Install just
      uses: taiki-e/install-action@8cca0918f8471c33515202b73f56ab27f2bed283 # v2.87.29
      with:
        tool: just@1.59.0
        fallback: none

    - name: Cache Rust
      uses: Swatinem/rust-cache@c8037a86dde8214a8310e9f54a8fc61ab362aa31 # v2
      with:
        cache-bin: false
        prefix-key: v1-rust-no-bin
        save-if: ${{ github.event_name == 'push' && contains(fromJSON('["main", "master", "development", "dev"]'), github.ref_name) && matrix.shard == 'rest' }}
        # All shards share the same build; only rest publishes its cache.
        # The cache saved here is what pr-core-python (pr-core-gate.yml)
        # restores on every PR. The default (root) workspace is the right one:
        # the rslib crates are members of the root Cargo workspace and build
        # into the top-level target/.
        shared-key: python-core

    - name: Cache LLVM ${{ env.LLVM_VERSION }}
      id: cache-llvm
      uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
      with:
        path: ~/.pecos/deps/llvm-21.1
        key: llvm-${{ env.LLVM_RELEASE_VERSION }}-${{ runner.os }}-${{ runner.arch }}-v3

    - name: Ensure LLVM ${{ env.LLVM_VERSION }}
      run: just ci-env

    - name: Save LLVM ${{ env.LLVM_VERSION }} cache
      if: steps.cache-llvm.outputs.cache-hit != 'true' && github.event_name == 'push' && contains(fromJSON('["main", "master", "development", "dev"]'), github.ref_name)
      uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
      with:
        path: ~/.pecos/deps/llvm-21.1
        key: ${{ steps.cache-llvm.outputs.cache-primary-key }}

    - name: Build the Python packages the core lane needs
      run: just python-ci-build-test

    - name: Run core Python tests (${{ matrix.shard }} shard)
      run: just pytest-ci-core-shard ${{ matrix.shard }}

  python-compat-smoke-build:
    runs-on: ${{ matrix.os }}
    # The || guard keeps a future entry that forgets job-timeout at the
    # historical 20 minutes instead of GitHub's 360-minute default.
    timeout-minutes: ${{ matrix.job-timeout || 20 }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-latest
            python-version: "3.12"
            artifact-name: python-compat-smoke-ubuntu
            build-llvm: true
            build-quantum-pecos: true
            job-timeout: 20
          # 30 minutes: Windows runner preparation (disk cleanup) varies by
          # several minutes and the pecos-rslib wheel compile alone takes
          # 10-12, so 20 minutes cancelled a healthy build (issue #360).
          - os: windows-2022
            python-version: "3.12"
            artifact-name: python-compat-smoke-windows
            build-llvm: false
            build-quantum-pecos: false
            job-timeout: 30
          - os: macOS-latest
            python-version: "3.12"
            artifact-name: python-compat-smoke-macos
            build-llvm: true
            build-quantum-pecos: false
            # Include QIS executor tests so macOS runtime failures block PRs.
            job-timeout: 30

    steps:
    - name: Harden the runner (egress audit)
      if: runner.os == 'Linux'
      uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
      with:
        egress-policy: audit

    - name: Free Disk Space (Windows)
      if: runner.os == 'Windows'
      shell: pwsh
      run: |
        Remove-Item -Path "C:\Android" -Recurse -Force -ErrorAction SilentlyContinue
        Remove-Item -Path "C:\Program Files\dotnet" -Recurse -Force -ErrorAction SilentlyContinue
        Remove-Item -Path "C:\hostedtoolcache\CodeQL" -Recurse -Force -ErrorAction SilentlyContinue

    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
      with:
        python-version: ${{ matrix.python-version }}

    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      with:
        persist-credentials: false

    - name: Install the latest version of uv
      uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      with:
        version-file: ".github/uv.toml"
        enable-cache: true
        save-cache: ${{ github.event_name == 'push' && contains(fromJSON('["main", "master", "development", "dev"]'), github.ref_name) }}

    - name: Set up Rust (Windows)
      if: runner.os == 'Windows'
      shell: pwsh
      run: |
        rustup set default-host x86_64-pc-windows-msvc
        rustup toolchain install stable --profile minimal
        rustup default stable
        "$HOME\.cargo\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
        $env:Path += ";$HOME\.cargo\bin"
        rustup show

    - name: Set up Rust (Unix)
      if: runner.os != 'Windows'
      run: |
        bash scripts/ci/ensure-rust.sh stable minimal
        export PATH="$HOME/.cargo/bin:$PATH"
        rustup default stable
        rustup show

    - name: Install just
      uses: taiki-e/install-action@8cca0918f8471c33515202b73f56ab27f2bed283 # v2.87.29
      with:
        tool: just@1.59.0
        fallback: none

    - name: Cache Rust
      uses: Swatinem/rust-cache@c8037a86dde8214a8310e9f54a8fc61ab362aa31 # v2
      with:
        cache-bin: false
        prefix-key: v1-rust-no-bin
        # Windows and macOS: this job is the only python-core writer. Linux:
        # restore-only, because python-core builds a superset (mwpf feature,
        # experimental bindings) and the first save to a key is final.
        save-if: ${{ runner.os != 'Linux' && github.event_name == 'push' && contains(fromJSON('["main", "master", "development", "dev"]'), github.ref_name) }}
        # The rslib crates are members of the root Cargo workspace and build
        # into the top-level target/, so cache the root workspace (the default)
        # and share the python-core key: same crates, same profile, same env.
        shared-key: python-core

    - name: Cache LLVM ${{ env.LLVM_VERSION }}
      id: cache-llvm
      uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
      with:
        path: ~/.pecos/deps/llvm-21.1
        key: llvm-${{ env.LLVM_RELEASE_VERSION }}-${{ runner.os }}-${{ runner.arch }}-v3

    - name: Ensure LLVM ${{ env.LLVM_VERSION }}
      run: just ci-env

    - name: Save LLVM ${{ env.LLVM_VERSION }} cache
      if: steps.cache-llvm.outputs.cache-hit != 'true' && github.event_name == 'push' && contains(fromJSON('["main", "master", "development", "dev"]'), github.ref_name)
      uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
      with:
        path: ~/.pecos/deps/llvm-21.1
        key: ${{ steps.cache-llvm.outputs.cache-primary-key }}

    # Keep this after ci-env: its GITHUB_ENV exports take effect in this step.
    # Exercise latest stable with the actual build environment (#566).
    - name: Check stable Rust in the PECOS build environment
      if: runner.os == 'macOS'
      run: bash scripts/ci/check-rust-build-env.sh

    - name: Install Python build tooling
      run: uv pip install --system maturin

    # Build one artifact the way an isolated PEP 517 frontend does: outside the
    # checkout and without Cargo exporting the workspace's LLVM prefix. The
    # installed-wheel smoke test below then exercises Guppy -> QIS -> Selene,
    # catching both LLVM toolchain fallback and native-library ABI mismatches.
    - name: Build pecos-rslib wheel from an isolated frontend
      if: runner.os == 'Linux'
      env:
        RUSTUP_TOOLCHAIN: stable
      run: |
        mkdir -p "$GITHUB_WORKSPACE/dist/pecos-rslib"
        cd "$RUNNER_TEMP"
        env -u LLVM_SYS_211_PREFIX uv build --wheel \
          "$GITHUB_WORKSPACE/python/pecos-rslib" \
          --config-setting 'build-args=--locked --profile dev' \
          --out-dir "$GITHUB_WORKSPACE/dist/pecos-rslib"

    - name: Build pecos-rslib wheel
      if: runner.os != 'Linux'
      env:
        RUSTUP_TOOLCHAIN: stable
      run: |
        mkdir -p dist/pecos-rslib
        uv build --wheel python/pecos-rslib \
          --config-setting 'build-args=--locked --profile dev' --out-dir dist/pecos-rslib

    - name: Build pecos-rslib-llvm wheel
      if: matrix.build-llvm
      env:
        RUSTUP_TOOLCHAIN: stable
      run: |
        mkdir -p dist/pecos-rslib-llvm
        maturin build --locked --manifest-path python/pecos-rslib-llvm/Cargo.toml --out dist/pecos-rslib-llvm

    - name: Test QIS executor recovery and runtime symbol binding
      if: runner.os == 'macOS' || runner.os == 'Windows'
      run: |
        cargo +stable test --locked -p pecos-qis-ffi --lib
        cargo +stable test --locked -p pecos-qis --lib executor::tests

    - name: Test StabVec numerical reference contract
      run: cargo +stable test --locked -p pecos-simulators --test stab_vec_correctness

    - name: Test canonical stabilizer amplitudes
      run: cargo +stable test --locked -p pecos-stab-tn --lib stab_mps::canonical_ket::tests

    - name: Build quantum-pecos wheel
      if: matrix.build-quantum-pecos
      run: |
        mkdir -p dist/quantum-pecos
        cd python/quantum-pecos
        uv build --wheel --out-dir ../../dist/quantum-pecos

    - name: Upload Python compatibility smoke artifacts
      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
      with:
        name: ${{ matrix.artifact-name }}
        path: |
          dist/pecos-rslib/*.whl
          dist/pecos-rslib-llvm/*.whl
          dist/quantum-pecos/*.whl
        if-no-files-found: error

  python-compat-smoke:
    needs: python-compat-smoke-build
    runs-on: ${{ matrix.os }}
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-latest
            artifact-name: python-compat-smoke-ubuntu
            python-version: "3.12"
            include-llvm: true
            include-pecos: true
          - os: ubuntu-latest
            artifact-name: python-compat-smoke-ubuntu
            python-version: "3.14"
            include-llvm: true
            include-pecos: true
          - os: windows-2022
            artifact-name: python-compat-smoke-windows
            python-version: "3.12"
            include-llvm: false
            include-pecos: false
          - os: windows-2022
            artifact-name: python-compat-smoke-windows
            python-version: "3.14"
            include-llvm: false
            include-pecos: false
          - os: macOS-latest
            artifact-name: python-compat-smoke-macos
            python-version: "3.12"
            include-llvm: true
            include-pecos: false
          - os: macOS-latest
            artifact-name: python-compat-smoke-macos
            python-version: "3.14"
            include-llvm: true
            include-pecos: false

    steps:
    - name: Harden the runner (egress audit)
      if: runner.os == 'Linux'
      uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
      with:
        egress-policy: audit

    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
      with:
        python-version: ${{ matrix.python-version }}

    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      with:
        persist-credentials: false

    - name: Install the latest version of uv
      uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      with:
        version-file: ".github/uv.toml"
        enable-cache: true
        save-cache: ${{ github.event_name == 'push' && contains(fromJSON('["main", "master", "development", "dev"]'), github.ref_name) }}

    - name: Set up Rust (Windows)
      if: runner.os == 'Windows' && matrix.include-llvm
      shell: pwsh
      run: |
        rustup set default-host x86_64-pc-windows-msvc
        rustup toolchain install stable --profile minimal
        rustup default stable
        "$HOME\.cargo\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
        $env:Path += ";$HOME\.cargo\bin"
        rustup show

    - name: Set up Rust (Unix)
      if: runner.os != 'Windows' && matrix.include-llvm
      run: |
        bash scripts/ci/ensure-rust.sh stable minimal
        export PATH="$HOME/.cargo/bin:$PATH"
        rustup show

    - name: Install just
      if: matrix.include-llvm
      uses: taiki-e/install-action@8cca0918f8471c33515202b73f56ab27f2bed283 # v2.87.29
      with:
        tool: just@1.59.0
        fallback: none

    - name: Cache LLVM ${{ env.LLVM_VERSION }}
      id: cache-llvm
      if: matrix.include-llvm
      uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
      with:
        path: ~/.pecos/deps/llvm-21.1
        key: llvm-${{ env.LLVM_RELEASE_VERSION }}-${{ runner.os }}-${{ runner.arch }}-v3

    - name: Ensure LLVM ${{ env.LLVM_VERSION }}
      if: matrix.include-llvm
      run: just ci-env

    - name: Save LLVM ${{ env.LLVM_VERSION }} cache
      if: matrix.include-llvm && steps.cache-llvm.outputs.cache-hit != 'true' && github.event_name == 'push' && contains(fromJSON('["main", "master", "development", "dev"]'), github.ref_name)
      uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
      with:
        path: ~/.pecos/deps/llvm-21.1
        key: ${{ steps.cache-llvm.outputs.cache-primary-key }}

    - name: Download Python compatibility smoke artifacts
      uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
      with:
        name: ${{ matrix.artifact-name }}
        path: ./python-compat-smoke-artifacts

    - name: Install Python compatibility smoke artifacts
      run: |
        uv pip install --system --force-reinstall ./python-compat-smoke-artifacts/pecos-rslib/pecos_rslib-*.whl
        if [ "${{ matrix.include-llvm }}" = "true" ]; then
          shopt -s nullglob
          llvm_wheels=(./python-compat-smoke-artifacts/pecos-rslib-llvm/pecos_rslib_llvm-*.whl)
          if [ "${#llvm_wheels[@]}" -eq 0 ]; then
            echo "Expected pecos-rslib-llvm wheel for include-llvm matrix entry, but none was found."
            exit 1
          fi
          uv pip install --system --force-reinstall "${llvm_wheels[0]}"
        fi
        if [ "${{ matrix.include-pecos }}" = "true" ]; then
          # One resolver invocation: the freshly built quantum-pecos wheel plus
          # the already-installed local native wheels (re-passed so they satisfy
          # its exact pecos-rslib/-llvm pins, which do not exist on PyPI for
          # unreleased versions). All other dependencies resolve from the
          # wheel's own Requires-Dist -- no hand-maintained pin list that can
          # drift from the package metadata.
          uv pip install --system --force-reinstall \
            ./python-compat-smoke-artifacts/pecos-rslib/pecos_rslib-*.whl \
            ./python-compat-smoke-artifacts/pecos-rslib-llvm/pecos_rslib_llvm-*.whl \
            ./python-compat-smoke-artifacts/quantum-pecos/quantum_pecos-*.whl
          uv pip check --system
        fi

    - name: Run Python compatibility smoke test
      # Each module's __version__ is injected from its own pyproject.toml at build time, so
      # this is where that wiring is checked against a real installation's metadata.
      run: |
        if [ "${{ matrix.include-pecos }}" = "true" ]; then
          python scripts/ci/check_module_versions.py pecos pecos_rslib pecos_rslib_llvm
        else
          # Exercise the LLVM extension itself: package metadata cannot detect
          # loading the wrong LLVM library or a broken runtime search path.
          if [ "$(uname)" = "Darwin" ] && [ "${{ matrix.include-llvm }}" = "true" ]; then
            python scripts/ci/check_module_versions.py pecos_rslib pecos_rslib_llvm
            python -c 'from pecos_rslib_llvm import ir, binding; module = ir.Module("ci_smoke"); parsed = binding.parse_assembly(str(module)); assert parsed.as_bitcode()[:2] == b"BC"'
          else
            python scripts/ci/check_module_versions.py pecos_rslib
          fi
        fi

    - name: Execute installed-wheel Guppy QIS smoke test
      if: matrix.include-pecos
      run: |
        python_bin="$(command -v python)"
        isolated_home="$RUNNER_TEMP/qis-smoke-home"
        llvm_shadow="$RUNNER_TEMP/qis-smoke-path"
        mkdir -p "$isolated_home" "$llvm_shadow"
        printf '#!/usr/bin/env sh\nexit 86\n' > "$llvm_shadow/llvm-as"
        chmod +x "$llvm_shadow/llvm-as"
        cp scripts/ci/smoke_guppy_qis.py "$RUNNER_TEMP/smoke_guppy_qis.py"
        cd "$RUNNER_TEMP"
        env -u LLVM_SYS_211_PREFIX \
          HOME="$isolated_home" \
          PATH="$llvm_shadow:$PATH" \
          "$python_bin" -I smoke_guppy_qis.py

    - name: Execute WASM compatibility smoke test
      run: python scripts/ci/smoke_wasm_foreign_object.py

  # Post-merge lane excluded from the PR fast path: the slow integration tests.
  python-slow-postmerge:
    # All admitted non-PR events validate the slow suite. Dispatch also lets a
    # branch get a signal before landing; PRs keep their fast checks.
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    timeout-minutes: 90
    env:
      PECOS_BUILD_MWPF: "1"
    steps:
    - name: Harden the runner (egress audit)
      uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
      with:
        egress-policy: audit

    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      with:
        persist-credentials: false

    - name: Set up Python
      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
      with:
        python-version: "3.14"

    - name: Install the latest version of uv
      uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      with:
        version-file: ".github/uv.toml"
        enable-cache: true
        save-cache: ${{ github.event_name == 'push' && contains(fromJSON('["main", "master", "development", "dev"]'), github.ref_name) }}

    - name: Set up Rust
      run: |
        bash scripts/ci/ensure-rust.sh stable minimal
        export PATH="$HOME/.cargo/bin:$PATH"
        rustup show

    - name: Verify cmake is available (MWPF decoder build)
      run: cmake --version

    - name: Install just
      uses: taiki-e/install-action@8cca0918f8471c33515202b73f56ab27f2bed283 # v2.87.29
      with:
        tool: just@1.59.0
        fallback: none

    - name: Cache Rust
      uses: Swatinem/rust-cache@c8037a86dde8214a8310e9f54a8fc61ab362aa31 # v2
      with:
        cache-bin: false
        prefix-key: v1-rust-no-bin
        # Restore-only: python-core (above) saves this key on dev pushes.
        save-if: false
        # The rslib crates are members of the root Cargo workspace and build
        # into the top-level target/, so cache the root workspace (the default)
        # and share the python-core key: same crates, same profile, same env.
        shared-key: python-core

    - name: Cache LLVM ${{ env.LLVM_VERSION }}
      id: cache-llvm
      uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
      with:
        path: ~/.pecos/deps/llvm-21.1
        key: llvm-${{ env.LLVM_RELEASE_VERSION }}-${{ runner.os }}-${{ runner.arch }}-v3

    - name: Ensure LLVM ${{ env.LLVM_VERSION }}
      run: just ci-env

    - name: Save LLVM ${{ env.LLVM_VERSION }} cache
      if: steps.cache-llvm.outputs.cache-hit != 'true' && github.event_name == 'push' && contains(fromJSON('["main", "master", "development", "dev"]'), github.ref_name)
      uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
      with:
        path: ~/.pecos/deps/llvm-21.1
        key: ${{ steps.cache-llvm.outputs.cache-primary-key }}

    - name: Build core Python packages
      # python-ci-build-test, not python-ci-build: its uv sync also selects
      # pecos-rslib-exp, so the environment is resolved for every package the
      # lane imports. pytest COLLECTION imports every module under tests/, and
      # tests/qec imports pecos_rslib_exp at module level.
      run: just python-ci-build-test

    - name: Run slow Python tests
      run: just pytest-slow

  zluppy-postmerge:
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    timeout-minutes: 90
    env:
      PECOS_BUILD_MWPF: "1"
    steps:
    - name: Harden the runner (egress audit)
      uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
      with:
        egress-policy: audit

    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      with:
        persist-credentials: false

    - name: Set up Python
      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
      with:
        python-version: "3.14"

    - name: Install the latest version of uv
      uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      with:
        version-file: ".github/uv.toml"
        enable-cache: true
        save-cache: ${{ github.event_name == 'push' && contains(fromJSON('["main", "master", "development", "dev"]'), github.ref_name) }}

    - name: Set up Rust
      run: |
        bash scripts/ci/ensure-rust.sh stable minimal
        export PATH="$HOME/.cargo/bin:$PATH"
        rustup show

    - name: Verify cmake is available (MWPF decoder build)
      run: cmake --version

    - name: Install just
      uses: taiki-e/install-action@8cca0918f8471c33515202b73f56ab27f2bed283 # v2.87.29
      with:
        tool: just@1.59.0
        fallback: none

    - name: Cache Rust
      uses: Swatinem/rust-cache@c8037a86dde8214a8310e9f54a8fc61ab362aa31 # v2
      with:
        cache-bin: false
        prefix-key: v1-rust-no-bin
        save-if: ${{ github.event_name == 'push' && contains(fromJSON('["main", "master", "development", "dev"]'), github.ref_name) }}
        # zluppy is built by uv sync through PEP 517, which is a release build,
        # so it cannot share the debug python-core cache. Own key; the crate is
        # a root-workspace member and builds into the top-level target/, so the
        # default (root) workspace is the right one.

    - name: Cache LLVM ${{ env.LLVM_VERSION }}
      id: cache-llvm-zluppy
      uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
      with:
        path: ~/.pecos/deps/llvm-21.1
        key: llvm-${{ env.LLVM_RELEASE_VERSION }}-${{ runner.os }}-${{ runner.arch }}-v3

    - name: Ensure LLVM ${{ env.LLVM_VERSION }}
      run: just ci-env

    - name: Save LLVM ${{ env.LLVM_VERSION }} cache
      if: steps.cache-llvm-zluppy.outputs.cache-hit != 'true' && github.event_name == 'push' && contains(fromJSON('["main", "master", "development", "dev"]'), github.ref_name)
      uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
      with:
        path: ~/.pecos/deps/llvm-21.1
        key: ${{ steps.cache-llvm-zluppy.outputs.cache-primary-key }}

    - name: Run zluppy Python tests
      run: just pytest-zluppy

  windows-vanilla-cargo:
    name: Windows vanilla cargo (crates.io consumer contract)
    runs-on: windows-2022
    timeout-minutes: 45
    steps:
      - name: Harden the runner (egress audit)
        if: runner.os == 'Linux'
        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
        with:
          egress-policy: audit

      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          persist-credentials: false

      - name: Set up Rust (MSVC)
        shell: pwsh
        run: |
          rustup set default-host x86_64-pc-windows-msvc
          rustup toolchain install stable --profile minimal
          rustup default stable
          "$HOME\.cargo\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
          rustup show

      - name: Assert no generated .cargo/config.toml (fail closed)
        shell: pwsh
        run: |
          if (Test-Path .cargo/config.toml) {
            Write-Error "repo .cargo/config.toml exists; the crates.io contract must hold WITHOUT it"
            exit 1
          }

      # pecos-build (where the toml_edit work lives) and pecos-core are
      # publishable and need no LLVM/FFI/external toolchain -- the right
      # minimal canary. LLVM-needing crates additionally require the upstream
      # llvm-sys LLVM_SYS_211_PREFIX (a universal llvm-sys requirement, not a
      # PECOS workaround) and are out of scope for this contract lane.
      - name: Vanilla cargo check (publishable crates, no just/bootstrap)
        shell: pwsh
        run: |
          $maxAttempts = 3
          for ($attempt = 1; $attempt -le $maxAttempts; $attempt++) {
            cargo check --locked -p pecos-build -p pecos-core
            if ($LASTEXITCODE -eq 0) {
              break
            }
            if ($attempt -eq $maxAttempts) {
              throw "Vanilla cargo check failed after $maxAttempts attempts"
            }
            Start-Sleep -Seconds (5 * $attempt)
            Write-Host "Retrying vanilla cargo check (attempt $($attempt + 1)/$maxAttempts)..."
          }