open-standards/.github/workflows/wai-quantum-landscape.yml

name: wai-quantum energy-landscape jobs

# A job that states an energy over variables of three states (extensions/quantum-landscape.md):
# the program reader, the two kernels, the exhaustive truth, the answer and its statement of joules, the
# classical methods and the table (wai_quantum::quantum_landscape), and the command line's verb.
#
# The kernels and every worked example give the same bits on every platform: a test pins a digest over them,
# and this workflow runs it on x86_64 Linux, arm64 Linux, arm64 macOS and wasm32-wasip2 (wasmtime), and compares
# the browser build's answers with the command line's, byte for byte, over many seeds. The conformance set is held to the
# code, and the stated result (quantum-conformance/landscape/stated-result.md) is checked by the script a reader runs.
# The browser build also runs its own digest in wai-web-wasm.yml.

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

on:
  push:
    branches: [main]
    paths:
      - 'wai/wai-quantum/src/quantum_landscape/**'
      - 'wai/wai-quantum/src/quantum_landscape.rs'
      - 'wai/wai-quantum/src/quantum_qio.rs'
      - 'wai/wai-quantum/src/repro.rs'
      - 'wai/wai-quantum/src/repro/**'
      - 'wai/wai-quantum/src/engine/receipt.rs'
      - 'wai/wai-quantum/src/engine/schema.rs'
      - 'wai/wai-quantum/schemas/landscape.v1.json'
      - 'wai/wai-quantum/tests/landscape_conformance.rs'
      - 'wai/wai-quantum/tests/landscape_float_read.rs'
      - 'wai/wai-quantum/Cargo.toml'
      - 'wai/wai-quantum/Cargo.lock'
      - 'wai/quantum-conformance/landscape/**'
      - 'wai/wai-quantum-cli/src/landscape.rs'
      - 'wai/wai-quantum-cli/src/main.rs'
      - 'wai/wai-quantum-cli/Cargo.toml'
      - 'wai/wai-quantum-cli/Cargo.lock'
      - 'wai/wai-web/src/quantum_engine.rs'
      - 'wai/wai-rs/src/sink_meter.rs'
      - 'wai/wai-rs/src/sink_energy.rs'
      - 'wai/wai-rs/src/energy_report.rs'
      - 'wai/wai-rs/Cargo.toml'
      - 'wai/wai-rs/Cargo.lock'
      - 'wai/wai-quantum/src/quantum_fabric.rs'
      - 'wai/wai-quantum/src/quantum_energy.rs'
      - 'wai/wai-web/Cargo.toml'
      - 'wai/wai-web/Cargo.lock'
      - 'wai/wai-web/demo/verify_landscape_wasm.mjs'
      - 'rust-toolchain.toml'
      - '.github/workflows/wai-quantum-landscape.yml'
  pull_request:
    paths:
      - 'wai/wai-quantum/src/quantum_landscape/**'
      - 'wai/wai-quantum/src/quantum_landscape.rs'
      - 'wai/wai-quantum/src/quantum_qio.rs'
      - 'wai/wai-quantum/src/repro.rs'
      - 'wai/wai-quantum/src/repro/**'
      - 'wai/wai-quantum/src/engine/receipt.rs'
      - 'wai/wai-quantum/src/engine/schema.rs'
      - 'wai/wai-quantum/schemas/landscape.v1.json'
      - 'wai/wai-quantum/tests/landscape_conformance.rs'
      - 'wai/wai-quantum/tests/landscape_float_read.rs'
      - 'wai/wai-quantum/Cargo.toml'
      - 'wai/wai-quantum/Cargo.lock'
      - 'wai/quantum-conformance/landscape/**'
      - 'wai/wai-quantum-cli/src/landscape.rs'
      - 'wai/wai-quantum-cli/src/main.rs'
      - 'wai/wai-quantum-cli/Cargo.toml'
      - 'wai/wai-quantum-cli/Cargo.lock'
      - 'wai/wai-web/src/quantum_engine.rs'
      - 'wai/wai-rs/src/sink_meter.rs'
      - 'wai/wai-rs/src/sink_energy.rs'
      - 'wai/wai-rs/src/energy_report.rs'
      - 'wai/wai-rs/Cargo.toml'
      - 'wai/wai-rs/Cargo.lock'
      - 'wai/wai-quantum/src/quantum_fabric.rs'
      - 'wai/wai-quantum/src/quantum_energy.rs'
      - 'wai/wai-web/Cargo.toml'
      - 'wai/wai-web/Cargo.lock'
      - 'wai/wai-web/demo/verify_landscape_wasm.mjs'
      - 'rust-toolchain.toml'
      - '.github/workflows/wai-quantum-landscape.yml'

jobs:
  relevant:
    name: does this change touch it
    runs-on: linux
    outputs:
      run: ${{ steps.gate.outputs.run }}
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - id: gate
        run: |
          set -euo pipefail
          r=$(python3 scripts/pr-touches-paths.py .github/workflows/wai-quantum-landscape.yml \
                "${{ github.event.pull_request.base.sha }}" \
                "${{ github.event.pull_request.head.sha }}")
          echo "this change touches energy-landscape jobs: $r"
          echo "run=$r" >> "$GITHUB_OUTPUT"

  native:
    name: reader, kernels, answers and the stated result · linux, release
    needs: relevant
    if: needs.relevant.outputs.run == 'true'
    runs-on: linux
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v5
      - name: Install Rust 1.99.1
        shell: bash
        run: |
          export PATH="$HOME/.cargo/bin:$PATH"
          command -v rustup >/dev/null 2>&1 || \
            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain 1.99.1
          rustup toolchain install 1.99.1 --profile minimal
          rustup default 1.99.1
          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
      # A module filter is satisfied by any one test of the module, so the
      # count is pinned and each test is required by name to have run and passed.
      - name: The module's tests
        shell: bash
        working-directory: wai/wai-quantum
        run: |
          set -euo pipefail
          cargo test --locked --release --features full --lib -- quantum_landscape:: 2>&1 | tee "$RUNNER_TEMP/landscape.log"
          grep -qE '^test result: ok\. 95 passed; 0 failed' "$RUNNER_TEMP/landscape.log" || { echo "::error::the landscape tests did not all pass (95 expected)"; exit 1; }
          for t in quantum_landscape::classical::tests::a_solver_keeps_to_its_budget_and_repeats_itself \
                   quantum_landscape::classical::tests::each_solver_finds_the_exact_lowest_on_small_instances_with_a_generous_budget \
                   quantum_landscape::classical::tests::with_no_budget_a_solver_misses \
                   quantum_landscape::conformance::tests::a_state_s_index_is_its_digits \
                   quantum_landscape::conformance::tests::the_reference_kernel_samples_every_workload_s_exact_law \
                   quantum_landscape::energy::tests::a_resting_state_is_one_no_single_change_improves \
                   quantum_landscape::energy::tests::quantising_keeps_signs_drops_the_small_and_says_so \
                   quantum_landscape::energy::tests::the_default_temperature_is_the_root_of_the_mean_couplings \
                   quantum_landscape::energy::tests::the_energy_is_the_formula \
                   quantum_landscape::energy::tests::the_lowered_energy_is_the_declared_one \
                   quantum_landscape::energy::tests::the_regime_reads_the_cost_against_the_couplings \
                   quantum_landscape::job::tests::a_bad_request_is_refused_plainly \
                   quantum_landscape::job::tests::a_job_goes_to_the_first_member_that_takes_it \
                   quantum_landscape::job::tests::a_member_never_runs_what_it_declines \
                   quantum_landscape::job::tests::a_member_that_fails_a_job_passes_it_on \
                   quantum_landscape::job::tests::an_uncertified_kernel_is_never_placed \
                   quantum_landscape::job::tests::every_answer_says_who_ran_it_at_what_parity \
                   quantum_landscape::job::tests::a_member_may_decline_only_what_does_not_fit_32_bits \
                   quantum_landscape::job::tests::a_sealed_answer_verifies_and_follows_its_schema \
                   quantum_landscape::job::tests::a_seed_keeps_all_64_bits \
                   quantum_landscape::job::tests::a_temperature_in_text_keeps_every_bit \
                   quantum_landscape::job::tests::a_temperature_string_follows_the_grammar \
                   quantum_landscape::job::tests::an_answer_s_energy_is_recomputed_from_its_program_alone \
                   quantum_landscape::job::tests::an_answer_says_what_it_is \
                   quantum_landscape::job::tests::checks_are_bounded \
                   quantum_landscape::job::tests::each_failure_fails_for_its_stated_reason \
                   quantum_landscape::job::tests::every_example_says_what_it_is_there_to_show \
                   quantum_landscape::job::tests::every_platform_gives_the_same_bits \
                   quantum_landscape::job::tests::junk_never_panics \
                   quantum_landscape::job::tests::quantised_weights_stay_within_the_field_bound \
                   quantum_landscape::job::tests::steps_and_restarts_are_bounded_before_anything_runs \
                   quantum_landscape::job::tests::the_examples_that_fail_fail_at_every_seed_tried \
                   quantum_landscape::job::tests::the_examples_that_work_solve_at_every_seed_tried \
                   quantum_landscape::job::tests::the_grammar_is_ascii_and_strict \
                   quantum_landscape::job::tests::the_most_negative_whole_number_is_refused \
                   quantum_landscape::job::tests::the_sweep_mean_does_not_overflow \
                   quantum_landscape::job::tests::the_talks_are_solved_against_every_arrangement \
                   quantum_landscape::member::tests::a_member_earns_its_parity_and_names_itself_properly \
                   quantum_landscape::member::tests::the_classes_are_the_fabric_s \
                   quantum_landscape::member::tests::the_reference_says_what_it_is \
                   quantum_landscape::price::tests::a_small_job_says_it_prices_low_and_by_how_much \
                   quantum_landscape::price::tests::above_zero_has_its_own_rate_about_two_and_a_half_times_the_other \
                   quantum_landscape::price::tests::numbers_are_written_to_the_figures_they_have \
                   quantum_landscape::price::tests::the_line_says_priced_and_never_calls_a_run_measured \
                   quantum_landscape::program::tests::a_pin_outvotes_everything \
                   quantum_landscape::program::tests::a_program_means_the_landscape_its_builder_calls_stand_for \
                   quantum_landscape::program::tests::a_typo_gets_a_plain_message_with_its_line_and_a_suggestion \
                   quantum_landscape::program::tests::each_refusal_names_its_line_where_one_means_anything \
                   quantum_landscape::program::tests::notes_are_read_and_checks_grade_both_ways \
                   quantum_landscape::program::tests::temperatures \
                   quantum_landscape::program::tests::warnings_come_when_a_program_is_read \
                   quantum_landscape::program::tests::weights_go_through_quantisation_and_say_what_was_lost \
                   quantum_landscape::reach::tests::a_table_holds_only_what_the_cells_can_reach \
                   quantum_landscape::reach::tests::a_table_is_bounded_by_the_smaller_of_the_two_forms \
                   quantum_landscape::reach::tests::a_window_ends_at_its_work_or_at_its_table \
                   quantum_landscape::reach::tests::no_job_can_outgrow_a_table \
                   quantum_landscape::reach::tests::the_table_is_the_reference_s_cut_points \
                   quantum_landscape::run::tests::a_comparison_gives_every_solver_the_same_budget \
                   quantum_landscape::run::tests::a_job_runs_on_another_member_and_its_answer_names_it \
                   quantum_landscape::run::tests::a_member_is_held_to_its_ending \
                   quantum_landscape::run::tests::a_member_s_bad_answer_is_refused \
                   quantum_landscape::run::tests::a_member_s_claim_of_parity_is_not_taken_on_its_word \
                   quantum_landscape::run::tests::a_run_s_reading_is_its_calls_added_up \
                   quantum_landscape::run::tests::a_run_too_big_is_refused_before_it_starts \
                   quantum_landscape::run::tests::a_sweep_keeps_the_budget_and_the_cold_row_of_a_minimize_runs_once \
                   quantum_landscape::run::tests::the_same_seed_gives_the_same_answer_and_another_seed_another_run \
                   quantum_landscape::run::tests::the_temperature_picks_the_mode_and_the_rate \
                   quantum_landscape::sample::tests::a_cell_samples_its_boltzmann_weights \
                   quantum_landscape::sample::tests::a_chain_at_temperature_zero_is_the_deterministic_sweep \
                   quantum_landscape::sample::tests::a_cold_cell_at_a_tie_is_uniform_over_the_tied_states \
                   quantum_landscape::sample::tests::a_cold_cell_away_from_a_tie_is_the_threshold \
                   quantum_landscape::sample::tests::starts_use_all_three_states \
                   quantum_landscape::sample::tests::the_cut_points_are_the_spec_s_formula \
                   quantum_landscape::sample::tests::the_cut_points_are_the_weights \
                   quantum_landscape::sample::tests::the_generator_is_splitmix64 \
                   quantum_landscape::sample::tests::the_schedule_ends_at_zero_and_a_chain_repeats_itself \
                   quantum_landscape::sample::tests::the_schedule_is_the_spec_s_formula \
                   quantum_landscape::sample::tests::two_coupled_cells_sample_their_joint_distribution \
                   quantum_landscape::sample::tests::without_zero_the_cell_is_the_two_state_cell \
                   quantum_landscape::settle::tests::a_tie_goes_to_zero_and_the_cost_widens_it \
                   quantum_landscape::settle::tests::four_recall_vectors_are_pinned \
                   quantum_landscape::settle::tests::the_digest_tells_every_state_of_three_cells_apart \
                   quantum_landscape::settle::tests::the_move_is_the_cell_s_lowest_energy \
                   quantum_landscape::settle::tests::the_three_endings_are_told_apart \
                   quantum_landscape::table::tests::a_hidden_group_really_is_the_lowest_state \
                   quantum_landscape::table::tests::a_printed_instance_is_the_same_landscape \
                   quantum_landscape::table::tests::the_table_is_the_same_on_one_thread_and_many \
                   quantum_landscape::table::tests::the_tally_counts_what_it_says \
                   quantum_landscape::trial::tests::the_grid_s_lowest_states_are_as_the_text_says \
                   quantum_landscape::trial::tests::the_two_value_cell_picks_the_lower_energy_when_cold \
                   quantum_landscape::truth::tests::a_known_answer_two_cells_that_must_oppose \
                   quantum_landscape::truth::tests::the_declared_weights_are_checked_too \
                   quantum_landscape::truth::tests::the_fast_walk_agrees_with_the_plain_one \
                   quantum_landscape::truth::tests::the_lowest_states_are_graded_against_the_checks \
                   quantum_landscape::truth::tests::too_large_is_none_and_the_largest_is_walked_whole; do
            grep -q "^test $t \.\.\. ok$" "$RUNNER_TEMP/landscape.log" || { echo "::error::$t did not run and pass"; exit 1; }
          done
      - name: The conformance set, read as a member's checker reads it
        shell: bash
        working-directory: wai/wai-quantum
        run: |
          set -euo pipefail
          cargo test --locked --release --features quantum_landscape --test landscape_conformance 2>&1 | tee "$RUNNER_TEMP/conformance.log"
          grep -qE '^test result: ok\. 12 passed; 0 failed' "$RUNNER_TEMP/conformance.log" || { echo "::error::the conformance tests did not all pass (12 expected)"; exit 1; }
      # With the module's feature alone: a temperature given as a JSON number is read to the nearest double.
      - name: Numbers read to the nearest double
        shell: bash
        working-directory: wai/wai-quantum
        run: |
          set -euo pipefail
          cargo test --locked --release --no-default-features --features quantum_landscape --test landscape_float_read 2>&1 | tee "$RUNNER_TEMP/float.log"
          grep -qE '^test result: ok\. 1 passed; 0 failed' "$RUNNER_TEMP/float.log" || { echo "::error::the float reading test did not pass"; exit 1; }
      # The bridge that makes a run meter of an on-chip counter, which a GPU member reads.
      - name: The meter bridge (wai-rs sink_meter::RunCounter)
        shell: bash
        working-directory: wai/wai-rs
        run: |
          set -euo pipefail
          cargo test --locked --release --no-default-features --features sink_energy,quantum_fabric --lib -- sink_meter::tests::a_counter_meters_a_run_only_where_it_was_live_and_says_what_it_covers 2>&1 | tee "$RUNNER_TEMP/meter.log"
          grep -qE '^test result: ok\. 1 passed; 0 failed' "$RUNNER_TEMP/meter.log" || { echo "::error::the meter bridge's test did not run and pass"; exit 1; }
      - name: The command line's verb
        shell: bash
        working-directory: wai/wai-quantum-cli
        run: |
          set -euo pipefail
          cargo test --locked --release --bin wai-quantum -- landscape:: 2>&1 | tee "$RUNNER_TEMP/verb.log"
          grep -qE '^test result: ok\. 2 passed; 0 failed' "$RUNNER_TEMP/verb.log" || { echo "::error::the verb's tests did not all pass (2 expected)"; exit 1; }
      # The script a reader runs. It exits 0 only if every stated value is what this machine gets.
      - name: The stated result
        shell: bash
        run: sh wai/quantum-conformance/landscape/reproduce.sh
      # Without warnings: a feature gate that leaves code unreachable or a
      # value unused in one feature set shows here.
      - name: Each feature set that holds the module builds, without warnings
        shell: bash
        working-directory: wai/wai-quantum
        env:
          RUSTFLAGS: -D warnings
        run: |
          set -euo pipefail
          cargo check --locked --no-default-features --features quantum_landscape --lib
          cargo check --locked --no-default-features --features quantum_engine --lib
          cargo check --locked --no-default-features --features quantum_engine,quantum_receipt --lib

  # The same bits on other processors and operating systems.
  bits:
    name: the same bits · ${{ matrix.label }}
    needs: relevant
    if: needs.relevant.outputs.run == 'true'
    strategy:
      fail-fast: false
      matrix:
        label: [linux-arm64, macos]
    runs-on: ${{ matrix.label }}
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v5
      # launchd's PATH omits cargo on the macOS host runner.
      - name: Install Rust 1.99.1
        shell: bash
        run: |
          export PATH="$HOME/.cargo/bin:$PATH"
          command -v rustup >/dev/null 2>&1 || \
            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain 1.99.1
          rustup toolchain install 1.99.1 --profile minimal
          rustup default 1.99.1
          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
      - name: The pinned digest and the conformance set, in a debug build and a release build
        shell: bash
        working-directory: wai/wai-quantum
        run: |
          set -euo pipefail
          export PATH="$HOME/.cargo/bin:$PATH"
          for profile in "" "--release"; do
            nice -n 10 cargo test --locked $profile --no-default-features --features quantum_landscape --lib -- \
              quantum_landscape::job::tests::every_platform_gives_the_same_bits \
              quantum_landscape::settle::tests::four_recall_vectors_are_pinned 2>&1 | tee "$RUNNER_TEMP/bits.log"
            grep -qE '^test result: ok\. 2 passed; 0 failed' "$RUNNER_TEMP/bits.log" || { echo "::error::the pinned bits differ here ($(uname -sm), ${profile:-debug})"; exit 1; }
            nice -n 10 cargo test --locked $profile --no-default-features --features quantum_landscape --test landscape_conformance 2>&1 | tee "$RUNNER_TEMP/vectors.log"
            grep -qE '^test result: ok\. 12 passed; 0 failed' "$RUNNER_TEMP/vectors.log" || { echo "::error::the conformance set differs here ($(uname -sm), ${profile:-debug})"; exit 1; }
          done

  wasip2:
    name: the module under wasm32-wasip2 (wasmtime)
    needs: relevant
    if: needs.relevant.outputs.run == 'true'
    runs-on: linux
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v5
      - name: Install Rust 1.99.1 with the wasm32-wasip2 target
        shell: bash
        run: |
          export PATH="$HOME/.cargo/bin:$PATH"
          command -v rustup >/dev/null 2>&1 || \
            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain 1.99.1
          rustup toolchain install 1.99.1 --profile minimal
          rustup default 1.99.1
          rustup target add --toolchain 1.99.1 wasm32-wasip2
          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
      # The release binary, pinned by version and SHA-256, as every WAI workflow that runs wasmtime pins it
      # (scripts/check-wasmtime-pin.py), and every run passes the two settings that fix its floats.
      - name: Install wasmtime 50.0.1
        shell: bash
        run: |
          set -euo pipefail
          [ "$(uname -m)" = x86_64 ] || { echo "::error::the pinned wasmtime archive is x86_64; this host is $(uname -m)"; exit 1; }
          if ! command -v xz >/dev/null 2>&1; then
            SUDO=""; [ "$(id -u)" -ne 0 ] && SUDO="sudo"
            $SUDO apt-get update -qq
            $SUDO apt-get install -y -qq xz-utils
          fi
          v=50.0.1
          f="wasmtime-v$v-x86_64-linux.tar.xz"
          curl --proto '=https' --tlsv1.2 -sSfL -o "$RUNNER_TEMP/$f" \
            "https://github.com/bytecodealliance/wasmtime/releases/download/v$v/$f"
          echo "685466455dd42a14774a86c36c8f2e45cbb9bd6d92a850139315df60a75498a5  $RUNNER_TEMP/$f" | sha256sum -c -
          tar -xJf "$RUNNER_TEMP/$f" -C "$RUNNER_TEMP"
          echo "$RUNNER_TEMP/wasmtime-v$v-x86_64-linux" >> "$GITHUB_PATH"
      # A debug build, so integer overflow panics instead of wrapping.
      - name: The module's tests under wasmtime, to the pinned bits
        shell: bash
        working-directory: wai/wai-quantum
        env:
          CARGO_TARGET_WASM32_WASIP2_RUNNER: wasmtime run -W nan-canonicalization=y -W relaxed-simd-deterministic=y
        run: |
          set -euo pipefail
          cargo test --locked --target wasm32-wasip2 --no-default-features --features quantum_engine,quantum_receipt --lib -- quantum_landscape:: 2>&1 | tee "$RUNNER_TEMP/wasip2.log"
          grep -qE '^test result: ok\. 94 passed; 0 failed' "$RUNNER_TEMP/wasip2.log" || { echo "::error::the landscape tests did not all pass under wasip2 (94 expected)"; exit 1; }

  # The browser build's answers against the command line's, byte for byte, in Node.
  parity:
    name: native against WebAssembly, over many seeds
    needs: relevant
    if: needs.relevant.outputs.run == 'true'
    runs-on: linux
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v5
      - name: Install Rust 1.99.1 with the wasm32 target
        shell: bash
        run: |
          export PATH="$HOME/.cargo/bin:$PATH"
          command -v rustup >/dev/null 2>&1 || \
            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain 1.99.1
          rustup toolchain install 1.99.1 --profile minimal
          rustup default 1.99.1
          rustup target add wasm32-unknown-unknown
          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
      # Pinned to the wasm-bindgen version in wai-web/Cargo.lock: the CLI and the crate must match exactly.
      - name: wasm-bindgen CLI 0.2.127
        shell: bash
        run: cargo install --locked wasm-bindgen-cli --version 0.2.127
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: The same answers, byte for byte
        shell: bash
        run: |
          set -euo pipefail
          (cd wai/wai-web && cargo build --locked --release --target wasm32-unknown-unknown --features quantum_engine \
            && wasm-bindgen --target nodejs --out-dir demo/pkg-node --out-name wai_web target/wasm32-unknown-unknown/release/wai_web.wasm)
          (cd wai/wai-quantum-cli && cargo build --locked --release)
          node wai/wai-web/demo/verify_landscape_wasm.mjs wai/wai-web/demo/pkg-node/wai_web.js wai/wai-quantum-cli/target/release/wai-quantum 200