ci.yml

name: CI

on:
  push:
    branches: [main]
    # Release tags (pushed by release-plz via the GitHub App token) so the
    # docker job can publish a version-tagged image, e.g. sd2k/eryx-server:0.5.0.
    tags: ['eryx-v[0-9]+.[0-9]+.[0-9]+']
  pull_request:
    branches: [main]

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  CARGO_TERM_COLOR: always
  RUST_BACKTRACE: 1

jobs:
  # Detect which paths changed to skip unnecessary jobs.
  # Each downstream job has an explicit 'github.event_name == push' override
  # so that all jobs always run on pushes to main.
  changes:
    name: Detect Changes
    runs-on: ubuntu-latest
    permissions:
      pull-requests: read
    outputs:
      core: ${{ steps.filter.outputs.core }}
      server: ${{ steps.filter.outputs.server }}
      python: ${{ steps.filter.outputs.python }}
      book: ${{ steps.filter.outputs.book }}
      examples: ${{ steps.filter.outputs.examples }}
      js: ${{ steps.filter.outputs.js }}
      demo: ${{ steps.filter.outputs.demo }}
    steps:
      - uses: actions/checkout@v7
      - uses: dorny/paths-filter@v4
        id: filter
        with:
          filters: |
            core:
              - 'crates/eryx-core/**'
              - 'crates/eryx/**'
              - 'crates/eryx-vfs/**'
              - 'crates/eryx-wasm-runtime/**'
              - 'crates/eryx-runtime/**'
              - 'crates/eryx-precompile/**'
              - 'Cargo.lock'
              - 'Cargo.toml'
              - '.github/workflows/ci.yml'
              - '.github/actions/**'
              # Tool versions and the cargo-rail config drive what every Rust
              # job actually runs. Without these, a Renovate bump that touches
              # only mise.toml skips all of CI and merges green — which is how
              # cargo-rail 0.8.1 -> 0.21.0 (#297) landed and broke main.
              - 'mise.toml'
              - '.config/rail.toml'
            server:
              - 'crates/eryx-server/**'
            python:
              - 'crates/eryx-python/**'
            book:
              - 'book/**'
            examples:
              - 'examples/**'
            js:
              - 'js/**'
            demo:
              - 'demo/**'

  # Fast check for dependency drift - runs in parallel with build
  unify-check:
    name: Dependency Check
    runs-on: ubuntu-latest
    needs: changes
    if: >-
      github.event_name == 'push'
      || needs.changes.outputs.core == 'true'
    steps:
      - uses: actions/checkout@v7

      - uses: ./.github/actions/setup-rust

      - name: Check dependency unification
        run: cargo rail unify --check

  # Build eryx-wasm-runtime and precompile it - other jobs depend on this.
  # Runs when core paths change, or when any downstream job needs WASM artifacts.
  build-eryx-runtime:
    name: Build eryx-runtime
    runs-on: ubuntu-latest
    needs: changes
    if: >-
      github.event_name == 'push'
      || needs.changes.outputs.core == 'true'
      || needs.changes.outputs.python == 'true'
      || needs.changes.outputs.book == 'true'
      || needs.changes.outputs.examples == 'true'
      || needs.changes.outputs.server == 'true'
      || needs.changes.outputs.js == 'true'
      || needs.changes.outputs.demo == 'true'
    steps:
      - uses: actions/checkout@v7

      - name: Cache WASM runtime artifacts
        id: wasm-cache
        uses: actions/cache@v6
        with:
          path: |
            crates/eryx-runtime/runtime.wasm
            crates/eryx-runtime/runtime.cwasm
            crates/eryx-runtime/prebuilt/
            crates/eryx-wasm-runtime/target/liberyx_runtime.so
          # NOTE: this key does not cover the cwasm's CPU-feature configuration,
          # which comes from `ERYX_CPU_FEATURES` below and the flag lists in
          # crates/eryx/src/wasm.rs (compiled into the `precompile` example).
          # Changing either without busting the version prefix silently reuses a
          # cwasm built with the old settings. Bumped v2 -> v3 for the VNNI flags
          # added under wasmtime 48.
          key: wasm-runtime-v3-${{ hashFiles('crates/eryx-wasm-runtime/src/**', 'crates/eryx-wasm-runtime/clock_stubs.c', 'crates/eryx-wasm-runtime/Cargo.toml', 'crates/eryx-runtime/build.rs', 'crates/eryx-runtime/wit/runtime.wit', 'crates/eryx-runtime/libs/*.zst', 'Cargo.lock') }}

      - name: Touch cached artifacts
        if: steps.wasm-cache.outputs.cache-hit == 'true'
        run: |
          # Touch all cached files so mise/make consider them current
          touch crates/eryx-runtime/runtime.wasm
          touch crates/eryx-runtime/runtime.cwasm
          touch crates/eryx-runtime/prebuilt/*
          touch crates/eryx-wasm-runtime/target/liberyx_runtime.so

      - name: Upload WASM artifacts (cache hit)
        if: steps.wasm-cache.outputs.cache-hit == 'true'
        uses: actions/upload-artifact@v7
        with:
          name: wasm-runtime
          path: |
            crates/eryx-runtime/runtime.wasm
            crates/eryx-runtime/runtime.cwasm
            crates/eryx-runtime/prebuilt/
            crates/eryx-wasm-runtime/target/liberyx_runtime.so
          retention-days: 1

      - uses: ./.github/actions/setup-rust
        if: steps.wasm-cache.outputs.cache-hit != 'true'

      - name: Configure Rust cache
        if: steps.wasm-cache.outputs.cache-hit != 'true'
        uses: Swatinem/rust-cache@v2

      - name: Install nightly toolchain
        run: rustup toolchain install nightly --component rust-src

      - name: Force rebuild (cache may have stale timestamps)
        if: steps.wasm-cache.outputs.cache-hit != 'true'
        run: |
          # Touch ALL sources to ensure mise doesn't skip build due to cached timestamps
          # The Rust cache may restore .rlib files with newer timestamps than sources
          find crates/eryx-wasm-runtime/src -name "*.rs" -exec touch {} +
          touch crates/eryx-wasm-runtime/clock_stubs.c
          touch crates/eryx-wasm-runtime/Cargo.toml
          # Remove outputs (mise checks mtime, not existence)
          rm -f crates/eryx-runtime/runtime.wasm crates/eryx-runtime/runtime.cwasm
          # Clean nested build-std target dirs to avoid stale std artifacts
          # when the nightly toolchain updates between runs
          rm -rf target/release/build/eryx-runtime-*/out/wasm-runtime-target

      - name: Build eryx-runtime
        if: steps.wasm-cache.outputs.cache-hit != 'true'
        run: mise run build-eryx-runtime

      - name: Copy prebuilt late-linking artifacts
        if: steps.wasm-cache.outputs.cache-hit != 'true'
        run: |
          # Find the OUT_DIR that actually contains the built artifacts
          # (not just any OUT_DIR - the preinit build creates a new one without .so files)
          OUT_DIR=$(find target/release -path "*/eryx-runtime-*/out/liberyx_runtime.so" -type f | head -1 | xargs dirname)
          echo "Found OUT_DIR: $OUT_DIR"
          mkdir -p crates/eryx-runtime/prebuilt
          cp "$OUT_DIR/liberyx_runtime.so.zst" crates/eryx-runtime/prebuilt/
          cp "$OUT_DIR/liberyx_bindings.so.zst" crates/eryx-runtime/prebuilt/
          # Also copy liberyx_runtime.so for eryx-wasm-runtime tests now, before preinit build
          mkdir -p crates/eryx-wasm-runtime/target
          cp "$OUT_DIR/liberyx_runtime.so" crates/eryx-wasm-runtime/target/
          ls -la crates/eryx-runtime/prebuilt/
          ls -la crates/eryx-wasm-runtime/target/

      - name: Set up python-stdlib for preinit
        if: steps.wasm-cache.outputs.cache-hit != 'true'
        run: mise run setup-eryx-runtime-tests

      - name: Precompile WASM with preinit
        if: steps.wasm-cache.outputs.cache-hit != 'true'
        run: |
          # Use preinit feature for faster sandbox instantiation in downstream jobs
          # (pre-initializes Python interpreter in the snapshot)
          cargo run -p eryx --example precompile --features preinit --release
        env:
          ERYX_PRECOMPILE_BOOTSTRAP: "1"
          # Use x86-64-v2 for portable cwasm across runner types
          ERYX_CPU_FEATURES: "x86-64-v2"

      - name: Upload WASM artifacts (cache miss)
        if: steps.wasm-cache.outputs.cache-hit != 'true'
        uses: actions/upload-artifact@v7
        with:
          name: wasm-runtime
          path: |
            crates/eryx-runtime/runtime.wasm
            crates/eryx-runtime/runtime.cwasm
            crates/eryx-runtime/prebuilt/
            crates/eryx-wasm-runtime/target/liberyx_runtime.so
          retention-days: 1

  lint:
    name: Lint
    runs-on: ubuntu-latest
    needs: [changes, build-eryx-runtime]
    if: >-
      github.event_name == 'push'
      || needs.changes.outputs.core == 'true'
      || needs.changes.outputs.server == 'true'
    steps:
      - uses: actions/checkout@v7

      - name: Install protoc
        uses: arduino/setup-protoc@v3
        with:
          version: "36.0"
          repo-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Download WASM artifacts
        uses: actions/download-artifact@v8
        with:
          name: wasm-runtime
          path: crates/

      - uses: ./.github/actions/mark-wasm-current

      - uses: ./.github/actions/setup-rust

      - name: Configure Rust cache
        uses: Swatinem/rust-cache@v2

      - name: Check formatting
        run: cargo fmt --all -- --check

      - name: Run clippy
        # Use --all-features now that prebuilt artifacts are available
        run: cargo clippy --workspace --all-targets --all-features -- -D warnings

  test:
    name: Test
    runs-on: ubuntu-latest
    needs: [changes, build-eryx-runtime]
    if: >-
      github.event_name == 'push'
      || needs.changes.outputs.core == 'true'
      || needs.changes.outputs.server == 'true'
    steps:
      - uses: actions/checkout@v7

      - name: Download WASM artifacts
        uses: actions/download-artifact@v8
        with:
          name: wasm-runtime
          path: crates/

      - uses: ./.github/actions/mark-wasm-current

      - name: Set up eryx-wasm-runtime test artifacts
        run: |
          # Extract python stdlib for eryx-wasm-runtime tests (from checked-in archive)
          mkdir -p crates/eryx-wasm-runtime/tests/python-stdlib
          tar -xf crates/eryx/python-stdlib.tar.zst -C crates/eryx-wasm-runtime/tests/
          # Create empty site-packages directory (tests expect it)
          mkdir -p crates/eryx-wasm-runtime/tests/site-packages
          ls -la crates/eryx-wasm-runtime/target/
          ls crates/eryx-wasm-runtime/tests/python-stdlib/ | head -10

      - name: Install protoc
        uses: arduino/setup-protoc@v3
        with:
          version: "36.0"
          repo-token: ${{ secrets.GITHUB_TOKEN }}

      # No apt anywhere in this workflow, deliberately. Beyond the dpkg-lock
      # hang that took protoc off apt in #337, `azure.archive.ubuntu.com` is
      # slow often enough to matter: on #339 `apt-get update` pulled 11.4 MB of
      # package indexes at 47 kB/s, taking 4m01s, then spent another 38s and
      # four `Ign:` retries fetching mold before falling back to
      # archive.ubuntu.com — 4m51s against this step's 5m timeout, for a 2.5 MB
      # linker. setup-mold fetches a prebuilt release from GitHub instead, the
      # same trade as arduino/setup-protoc above.
      #
      # Nothing else was needed from apt: the runner image already ships clang
      # and gcc, and `-fuse-ld=mold` works with the default gcc driver, so no
      # `linker =` override is required either.
      - name: Install mold linker
        uses: rui314/setup-mold@v1

      - name: Configure mold linker
        run: |
          mkdir -p .cargo
          cat >> .cargo/config.toml << 'EOF'
          [target.x86_64-unknown-linux-gnu]
          rustflags = ["-C", "link-arg=-fuse-ld=mold"]
          EOF

      - uses: ./.github/actions/setup-rust

      - name: Configure Rust cache
        uses: Swatinem/rust-cache@v2

      - name: Run tests
        # Use --all-features to test everything. This works because:
        # - runtime.wasm and runtime.cwasm are provided by artifacts
        # - prebuilt/liberyx_*.so.zst are provided for late-linking feature
        # - liberyx_runtime.so and python-stdlib are provided for eryx-wasm-runtime tests
        # Use --profile ci for longer timeouts on slow WASM component tests
        run: cargo nextest run --workspace --all-features --profile ci

  msrv:
    name: MSRV
    runs-on: ubuntu-latest
    needs: changes
    if: >-
      github.event_name == 'push'
      || needs.changes.outputs.core == 'true'
    steps:
      - uses: actions/checkout@v7

      - name: Install mise
        uses: jdx/mise-action@v4
        with:
          mise_toml: |
            [tools]
            rust = "1.98"

      - name: Configure Rust cache
        uses: Swatinem/rust-cache@v2

      - name: Check MSRV
        # Exclude crates that require WASM artifacts or WASI SDK
        run: cargo check --workspace --exclude eryx-python --exclude eryx-precompile --exclude eryx-server

  platform-check:
    name: ${{ matrix.os == 'windows-latest' && 'Windows' || 'macOS' }} Check
    runs-on: ${{ matrix.os }}
    needs: changes
    if: >-
      github.event_name == 'push'
      || needs.changes.outputs.core == 'true'
    strategy:
      matrix:
        os: [windows-latest, macos-latest]
    steps:
      - uses: actions/checkout@v7

      - name: Configure Rust cache
        uses: Swatinem/rust-cache@v2

      - name: Install Rust
        # Install the pinned toolchain rather than trusting the runner image's
        # preinstalled Rust, which lags: the macos-latest image shipped 1.97.1
        # while the workspace MSRV was 1.98.0, so `cargo check` refused to build
        # ("rustc 1.97.1 is not supported by the following packages"). Reading
        # mise.toml keeps this following the same pin as every other job, which
        # Renovate bumps as one "Rust toolchain" group.
        shell: bash
        run: |
          RUST_VERSION=$(sed -n 's/^rust = { version = "\([^"]*\)".*/\1/p' mise.toml)
          if [ -z "$RUST_VERSION" ]; then
            echo "could not read the rust pin from mise.toml" >&2
            exit 1
          fi
          rustup toolchain install "$RUST_VERSION" --profile minimal
          rustup default "$RUST_VERSION"
          rustup show active-toolchain

      - name: Check compilation
        # Exclude crates that need WASI SDK, Python, or WASM artifacts
        run: cargo check --workspace --exclude eryx-python --exclude eryx-precompile --exclude eryx-wasm-runtime --exclude eryx-server

  doc:
    name: Documentation
    runs-on: ubuntu-latest
    needs: [changes, build-eryx-runtime]
    if: >-
      github.event_name == 'push'
      || needs.changes.outputs.core == 'true'
    steps:
      - uses: actions/checkout@v7

      - name: Install protoc
        uses: arduino/setup-protoc@v3
        with:
          version: "36.0"
          repo-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Download WASM artifacts
        uses: actions/download-artifact@v8
        with:
          name: wasm-runtime
          path: crates/

      - uses: ./.github/actions/mark-wasm-current

      - uses: ./.github/actions/setup-rust

      - name: Configure Rust cache
        uses: Swatinem/rust-cache@v2

      - name: Build documentation
        # Use --all-features now that prebuilt artifacts are available
        run: cargo doc --workspace --no-deps --all-features
        env:
          RUSTDOCFLAGS: -D warnings

  # Simulate docs.rs build (no WASM artifacts needed)
  docsrs:
    name: docs.rs
    runs-on: ubuntu-latest
    needs: changes
    if: >-
      github.event_name == 'push'
      || needs.changes.outputs.core == 'true'
    steps:
      - uses: actions/checkout@v7

      - name: Install nightly toolchain
        run: rustup toolchain install nightly

      - name: Configure Rust cache
        uses: Swatinem/rust-cache@v2

      - name: Build docs (docs.rs simulation)
        run: DOCS_RS=1 cargo +nightly doc -p eryx -p eryx-runtime --all-features --no-deps
        env:
          RUSTDOCFLAGS: "--cfg docsrs -D warnings"

  # Check that all feature combinations compile
  check-features:
    name: Check Feature Combinations
    runs-on: ubuntu-latest
    needs: [changes, build-eryx-runtime]
    if: >-
      github.event_name == 'push'
      || needs.changes.outputs.core == 'true'
    steps:
      - uses: actions/checkout@v7

      - name: Download WASM artifacts
        uses: actions/download-artifact@v8
        with:
          name: wasm-runtime
          path: crates/

      - uses: ./.github/actions/mark-wasm-current

      - uses: ./.github/actions/setup-rust

      - name: Configure Rust cache
        uses: Swatinem/rust-cache@v2

      - name: Check all feature combinations
        # cargo-all-features checks the powerset of feature combinations.
        # The Cargo.toml config skips preinit/native-extensions for local dev (no artifacts),
        # but in CI we have artifacts, so we check those separately.
        run: |
          echo "=== Checking feature powerset (excluding preinit/native-extensions) ==="
          cargo check-all-features -- -p eryx

          echo "=== Checking features that require runtime artifacts ==="
          cargo check -p eryx --features preinit
          cargo check -p eryx --features embedded,preinit
          cargo check -p eryx --features native-extensions
          cargo check -p eryx --features embedded,native-extensions

  # Run examples to ensure they don't bitrot
  examples:
    name: Examples
    runs-on: ubuntu-latest
    needs: [changes, build-eryx-runtime]
    if: >-
      github.event_name == 'push'
      || needs.changes.outputs.core == 'true'
      || needs.changes.outputs.examples == 'true'
    steps:
      - uses: actions/checkout@v7

      - name: Download WASM artifacts
        uses: actions/download-artifact@v8
        with:
          name: wasm-runtime
          path: crates/

      - uses: ./.github/actions/mark-wasm-current

      - uses: ./.github/actions/setup-rust

      - name: Configure Rust cache
        uses: Swatinem/rust-cache@v2

      - name: Run examples
        run: |
          echo "=== simple ==="
          cargo run --package eryx --example simple --features embedded --release
          echo "=== parallel_callbacks ==="
          cargo run --package eryx --example parallel_callbacks --features embedded --release
          echo "=== with_tracing ==="
          cargo run --package eryx --example with_tracing --features embedded --release
          echo "=== error_handling ==="
          cargo run --package eryx --example error_handling --features embedded --release
          echo "=== resource_limits ==="
          cargo run --package eryx --example resource_limits --features embedded --release
          echo "=== custom_library ==="
          cargo run --package eryx --example custom_library --features embedded --release
          echo "=== session_reuse ==="
          cargo run --package eryx --example session_reuse --features embedded --release
          echo "=== runtime_callbacks ==="
          cargo run --package eryx --example runtime_callbacks --features embedded --release
          echo "=== precompile ==="
          cargo run --package eryx --example precompile --features embedded --release
          echo "=== embedded_runtime ==="
          cargo run --package eryx --example embedded_runtime --features embedded --release
          echo "=== trace_events ==="
          cargo run --package eryx --example trace_events --features embedded --release

  # Test Python bindings
  python-bindings:
    name: Python Bindings
    runs-on: ubuntu-latest
    needs: [changes, build-eryx-runtime]
    if: >-
      github.event_name == 'push'
      || needs.changes.outputs.core == 'true'
      || needs.changes.outputs.python == 'true'
    steps:
      - uses: actions/checkout@v7

      - name: Download WASM artifacts
        uses: actions/download-artifact@v8
        with:
          name: wasm-runtime
          path: crates/

      - uses: ./.github/actions/mark-wasm-current

      - uses: ./.github/actions/setup-rust

      - name: Configure Rust cache
        uses: Swatinem/rust-cache@v2

      - uses: actions/setup-python@v7
        with:
          python-version: "3.14"

      - name: Install uv
        uses: astral-sh/setup-uv@v10.0.1

      - name: Build and install eryx-python with dev dependencies
        working-directory: crates/eryx-python
        run: |
          uv venv ../../.venv
          source ../../.venv/bin/activate
          uv pip install maturin
          maturin develop --release
          uv export --extra dev --no-dev --no-hashes --no-emit-project --frozen | uv pip install -r -

      - name: Run Python tests
        working-directory: crates/eryx-python
        run: |
          source ../../.venv/bin/activate
          pytest tests/ -v

      - name: Run Python examples
        working-directory: crates/eryx-python
        run: |
          source ../../.venv/bin/activate
          echo "=== simple.py ==="
          python examples/simple.py
          echo "=== error_handling.py ==="
          python examples/error_handling.py
          echo "=== resource_limits.py ==="
          python examples/resource_limits.py

  # Test book examples
  book-tests:
    name: Book Tests
    runs-on: ubuntu-latest
    needs: [changes, build-eryx-runtime]
    if: >-
      github.event_name == 'push'
      || needs.changes.outputs.core == 'true'
      || needs.changes.outputs.book == 'true'
      || needs.changes.outputs.python == 'true'
    steps:
      - name: Free disk space
        run: |
          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc /opt/hostedtoolcache/CodeQL
          sudo docker image prune --all --force

      - uses: actions/checkout@v7

      - name: Download WASM artifacts
        uses: actions/download-artifact@v8
        with:
          name: wasm-runtime
          path: crates/

      - uses: ./.github/actions/mark-wasm-current

      - uses: ./.github/actions/setup-rust

      - name: Configure Rust cache
        uses: Swatinem/rust-cache@v2

      - name: Install mdbook tools
        run: |
          cargo binstall -y mdbook
          cargo binstall -y mdbook-langtabs

      - name: Build project
        run: |
          # `mdbook test -L <dir>` points rustdoc at a whole directory instead of
          # naming artifacts, so that directory must hold exactly one copy of
          # each crate. Two separate things break that in target/debug/deps:
          #
          #  1. Cargo legitimately compiles some crates twice in one build --
          #     once for the target graph and once for the host graph (build
          #     scripts, proc macros and their dependencies), which
          #     resolver = "2" deliberately does not feature-unify. Both land in
          #     target/debug/deps and rustdoc cannot choose:
          #       error[E0464]: multiple candidates for `rlib` dependency `serde`
          #     Rust 1.97 produces two more such units than 1.92 did, which is
          #     why this surfaced on the toolchain bump and not before.
          #  2. The Rust cache is keyed per job, so artifacts from earlier runs
          #     under a different Cargo.lock linger alongside current ones.
          #
          # Building with an explicit --target fixes (1): target-side artifacts
          # go to target/<triple>/debug/deps and the host graph stays out.
          # Assembling the link directory from cargo's own artifact list fixes
          # (2): only what this build resolved to is copied in.
          TRIPLE=$(rustc -vV | sed -n 's/^host: //p')
          echo "building for $TRIPLE"

          cargo clean -p eryx -p eryx-runtime --target "$TRIPLE" 2>/dev/null || true
          cargo build -p eryx --features embedded,macros --target "$TRIPLE" \
            --message-format=json-render-diagnostics \
            > "$RUNNER_TEMP/cargo-build.json"

          BOOK_DEPS=target/book-deps
          rm -rf "$BOOK_DEPS" && mkdir -p "$BOOK_DEPS"
          jq -r 'select(.reason == "compiler-artifact") | .filenames[]?' \
            "$RUNNER_TEMP/cargo-build.json" \
            | grep "/$TRIPLE/debug/deps/" | grep -E '\.(rlib|rmeta)$' \
            | while read -r f; do cp -n "$f" "$BOOK_DEPS/"; done

          # Cargo reports the *root* package's rlib at its uplifted path
          # (target/<triple>/debug/liberyx.rlib) rather than the hashed one
          # under deps/, so the loop above copies eryx's .rmeta but not its
          # .rlib. rustdoc loads the hashed .rmeta and then looks for a .rlib
          # with the matching hash beside it -- the unhashed uplifted copy does
          # not satisfy it, and every example fails with
          #   error: crate `eryx` required to be available in rlib format
          # Pick up the sibling .rlib for each .rmeta already copied. Keying off
          # the rmeta keeps this restricted to crates cargo actually named, so
          # leftovers from an earlier Cargo.lock still cannot slip in.
          for m in "$BOOK_DEPS"/*.rmeta; do
            [ -e "$m" ] || continue
            sib="target/$TRIPLE/debug/deps/$(basename "$m" .rmeta).rlib"
            [ -e "$sib" ] && cp -n "$sib" "$BOOK_DEPS/" || true
          done

          # Proc macros are host artifacts, so --target keeps them out of the
          # target directory -- but rustdoc still needs them to expand derives,
          # or every example using one fails with
          #   error[E0463]: can't find crate for `serde_derive`
          # They are dylibs, so they cannot collide with the rlibs above.
          jq -r 'select(.reason == "compiler-artifact")
                 | select(.target.kind[]? == "proc-macro") | .filenames[]?' \
            "$RUNNER_TEMP/cargo-build.json" \
            | while read -r f; do cp -n "$f" "$BOOK_DEPS/"; done

          echo "assembled $(ls "$BOOK_DEPS" | wc -l) artifacts into $BOOK_DEPS"

      - name: Test Rust code blocks
        run: mdbook test -L ../target/book-deps
        working-directory: book

      - uses: actions/setup-python@v7
        with:
          python-version: '3.14'

      - name: Create virtualenv and install dependencies
        run: |
          python -m venv .venv
          source .venv/bin/activate
          pip install maturin pytest

      - name: Build and install eryx-python
        working-directory: crates/eryx-python
        run: |
          source ../../.venv/bin/activate
          maturin develop --release

      - name: Test Python code blocks
        working-directory: book
        run: |
          source ../.venv/bin/activate
          python scripts/test_examples.py

  # Deploy book to GitHub Pages (only on main)
  deploy-book:
    name: Deploy Book
    runs-on: ubuntu-latest
    needs: book-tests
    if: github.ref == 'refs/heads/main'
    permissions:
      contents: write
      pages: write
      id-token: write
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0  # Need full history for version detection

      - name: Install cargo-binstall
        run: curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash

      - name: Install mdbook tools
        run: |
          cargo binstall -y mdbook
          cargo binstall -y mdbook-langtabs

      - name: Detect version
        id: version
        run: |
          VERSION=$(grep '^version = ' Cargo.toml | head -1 | sed 's/version = "\(.*\)"/\1/')
          echo "version=v$VERSION" >> $GITHUB_OUTPUT
          echo "Detected version: v$VERSION"

      - name: Build book
        working-directory: book
        run: mdbook build

      - name: Prepare deployment directory
        run: |
          mkdir -p deploy/latest/book
          mkdir -p deploy/${{ steps.version.outputs.version }}/book
          cp -r book/book/* deploy/latest/book/
          cp -r book/book/* deploy/${{ steps.version.outputs.version }}/book/
          echo "docs.eryx.run" > deploy/CNAME
          cat > deploy/index.html << 'HTMLEOF'
          <!DOCTYPE html>
          <html>
          <head>
            <meta charset="utf-8">
            <title>Eryx Documentation</title>
            <meta http-equiv="refresh" content="0; url=latest/book/">
          </head>
          <body>
            <p>Redirecting to <a href="latest/book/">latest documentation</a>...</p>
          </body>
          </html>
          HTMLEOF

      - name: Setup Pages
        uses: actions/configure-pages@v6

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: 'deploy'

      - name: Deploy to GitHub Pages
        uses: actions/deploy-pages@v5

  # Deploy browser demo to Cloudflare Pages.
  # - On main: production deployment (custom domain)
  # - On PRs: preview deployment (<branch>.eryx-demo.pages.dev)
  deploy-demo:
    name: Deploy Demo (Cloudflare)
    runs-on: ubuntu-latest
    needs: [changes, build-eryx-runtime]
    if: >-
      github.event.pull_request.head.repo.fork != true
      && github.actor != 'dependabot[bot]'
      && github.ref_type != 'tag'
      && (github.event_name == 'push'
      || needs.changes.outputs.core == 'true'
      || needs.changes.outputs.js == 'true'
      || needs.changes.outputs.demo == 'true')
    permissions:
      contents: read
      deployments: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v7

      - name: Download WASM artifacts
        uses: actions/download-artifact@v8
        with:
          name: wasm-runtime
          path: crates/

      - uses: ./.github/actions/mark-wasm-current

      - uses: ./.github/actions/setup-rust

      - name: Configure Rust cache
        uses: Swatinem/rust-cache@v2

      - name: Install wasm32-unknown-unknown target
        run: rustup target add wasm32-unknown-unknown

      - name: Build JavaScript bindings
        working-directory: js
        run: mise run build

      - name: Build linker WASM + copy base libs
        run: |
          mise run build-linker-wasm
          mise run copy-base-libs

      - name: Download example packages for demo
        working-directory: js/demo/public
        run: |
          mkdir -p examples
          curl -fSL -o examples/humanize-4.15.0-py3-none-any.whl \
            "https://files.pythonhosted.org/packages/c5/7b/bca5613a0c3b542420cf92bd5e5fb8ebd5435ce1011a091f66bb7693285e/humanize-4.15.0-py3-none-any.whl"
          curl -fSL -o examples/numpy-wasi.tar.gz \
            "https://github.com/eryx-org/eryx/releases/download/demo-assets/numpy-wasi.tar.gz"
          ls -lh examples/

      - name: Install eryx dependencies
        run: npm ci --prefix js/eryx

      - name: Build demo site
        working-directory: js/demo
        run: |
          npm install
          npx vite build

      - name: Deploy to Cloudflare Pages
        id: deploy
        uses: cloudflare/wrangler-action@v4
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy js/demo/dist --project-name=eryx-demo --branch=${{ github.head_ref || github.ref_name }} --commit-dirty=true

      - name: Comment preview URL on PR
        if: github.event_name == 'pull_request'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          BODY="🌐 **Demo preview:** ${{ steps.deploy.outputs.pages-deployment-alias-url }}
          📌 **This deploy:** ${{ steps.deploy.outputs.deployment-url }}"
          gh pr comment ${{ github.event.pull_request.number }} \
            --body "$BODY" --edit-last || \
          gh pr comment ${{ github.event.pull_request.number }} \
            --body "$BODY"

  # Gate job for the "Deploy Demo" required status check.
  # The actual deploy is skipped for fork PRs (no secrets), but GitHub
  # treats skipped required checks as failing. This job passes when the
  # deploy is skipped, so fork/dependabot PRs aren't blocked.
  deploy-demo-status:
    name: Deploy Demo
    runs-on: ubuntu-latest
    needs: [deploy-demo]
    if: always()
    steps:
      - name: Check deploy result
        run: |
          result="${{ needs.deploy-demo.result }}"
          if [ "$result" = "success" ] || [ "$result" = "skipped" ]; then
            echo "Deploy demo: $result"
          else
            echo "Deploy demo: $result"
            exit 1
          fi

  # Build Docker image for the gRPC server.
  # Uses the pre-built runtime.cwasm from build-eryx-runtime to skip the
  # expensive WASM precompilation step inside Docker. Only pushes on main.
  docker:
    name: Docker
    runs-on: ubuntu-latest
    needs: [changes, build-eryx-runtime]
    if: >-
      github.event.pull_request.head.repo.fork != true
      && (github.event_name == 'push'
      || needs.changes.outputs.core == 'true'
      || needs.changes.outputs.server == 'true')
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7

      - name: Download WASM artifacts
        uses: actions/download-artifact@v8
        with:
          name: wasm-runtime
          path: crates/

      - name: Prepare runtime.cwasm for Docker build context
        run: cp crates/eryx-runtime/runtime.cwasm crates/eryx-server/runtime.cwasm

      - name: Log in to Docker Hub
        if: github.event_name == 'push'
        uses: docker/login-action@v4
        with:
          username: sd2k
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Docker meta
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: sd2k/eryx-server
          # On main: sha + branch + latest. On a release tag (eryx-v0.5.0):
          # the version tags 0.5.0 and 0.5 (type=match strips the eryx-v prefix).
          # latest stays tied to main and is not moved by tag builds.
          tags: |
            type=sha,prefix=
            type=ref,event=branch
            type=raw,value=latest,enable={{is_default_branch}}
            type=match,pattern=\d+.\d+.\d+,group=0
            type=match,pattern=\d+.\d+,group=0

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          context: .
          file: crates/eryx-server/Dockerfile
          build-args: |
            RUNTIME_SOURCE=custom
            RUNTIME_CWASM=crates/eryx-server/runtime.cwasm
          push: ${{ github.event_name == 'push' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}