feat(dispatch): Validate the dispatch-surface declaration at configure time

.github/scripts/check_dispatch_surface.sh

@@ -0,0 +1,111 @@
+#!/bin/bash
+# Copyright 2026 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Runs cmake/validate-dispatch-surface.cmake over the fixtures in
+# tests/cmake/dispatch-surface and checks each verdict.
+#
+#   valid-*.cmake    must be accepted.
+#   invalid-*.cmake  must be rejected, with a message containing the substring
+#                    given by that fixture's `# EXPECT-ERROR:` line.
+#
+# Needs nothing but cmake -- no compiler, no dependencies, no build directory.
+
+set -uo pipefail
+
+root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
+fixtures="${root}/tests/cmake/dispatch-surface"
+validator="${root}/cmake/validate-dispatch-surface.cmake"
+x86_src_dir="${root}/include/svs/multi-arch/x86"
+
+if [[ ! -d ${fixtures} ]]; then
+    echo "no fixture directory: ${fixtures}" >&2
+    exit 1
+fi
+
+# The default declaration must itself be valid -- checked as its own case so that
+# a broken default is reported here rather than only at configure time.
+run_validator() {
+    cmake "-DSVS_DISPATCH_SURFACE_FILE=$1" "-DSVS_X86_SRC_DIR=${x86_src_dir}" \
+        -P "${validator}" 2>&1
+}
+
+# CMake indents and line-wraps error text, so compare against a whitespace-
+# collapsed copy of the output.
+flatten() { tr '\n' ' ' | tr -s '[:space:]' ' '; }
+
+failures=0
+checked=0
+
+check_accepted() {
+    local fixture=$1 name=$2 output status
+    output=$(run_validator "${fixture}")
+    status=$?
+    if ((status != 0)); then
+        echo "FAIL ${name}: expected to be accepted, but validation failed:" >&2
+        echo "${output}" | sed 's/^/    /' >&2
+        ((failures++))
+    else
+        echo "ok   ${name}: accepted"
+    fi
+    ((checked++))
+}
+
+check_rejected() {
+    local fixture=$1 name=$2 expected output status
+    expected=$(sed -n 's/^# EXPECT-ERROR: *//p' "${fixture}")
+    if [[ -z ${expected} ]]; then
+        echo "FAIL ${name}: fixture has no '# EXPECT-ERROR:' line" >&2
+        ((failures++))
+        ((checked++))
+        return
+    fi
+
+    output=$(run_validator "${fixture}")
+    status=$?
+    if ((status == 0)); then
+        echo "FAIL ${name}: expected rejection, but validation succeeded" >&2
+        ((failures++))
+    elif [[ $(printf '%s' "${output}" | flatten) != *"${expected}"* ]]; then
+        echo "FAIL ${name}: rejected, but not for the stated reason." >&2
+        echo "    expected: ${expected}" >&2
+        echo "${output}" | sed 's/^/    actual:   /' >&2
+        ((failures++))
+    else
+        echo "ok   ${name}: rejected (${expected})"
+    fi
+    ((checked++))
+}
+
+check_accepted "${root}/cmake/dispatch-surface.cmake" "dispatch-surface.cmake (default)"
+
+for fixture in "${fixtures}"/*.cmake; do
+    name=$(basename "${fixture}")
+    case ${name} in
+    valid-*) check_accepted "${fixture}" "${name}" ;;
+    invalid-*) check_rejected "${fixture}" "${name}" ;;
+    *)
+        echo "FAIL ${name}: fixture name must start with valid- or invalid-" >&2
+        ((failures++))
+        ((checked++))
+        ;;
+    esac
+done
+
+echo
+if ((failures != 0)); then
+    echo "${failures} of ${checked} dispatch-surface checks failed" >&2
+    exit 1
+fi
+echo "all ${checked} dispatch-surface checks passed"

.github/workflows/dispatch-surface.yml

@@ -0,0 +1,106 @@
+# Copyright 2026 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# The set of distance kernels compiled ahead of time is declared once, in
+# cmake/dispatch-surface.cmake, and generated from there. Two things have to stay
+# true for that to be worth anything: the declaration must be checked rather than
+# trusted, and it must be genuinely configurable -- a knob nobody turns is a knob
+# that quietly stops working.
+
+name: Dispatch Surface
+
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  declaration:
+    name: declaration is checked, committed header is current
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v6
+
+    # Every fixture in tests/cmake/dispatch-surface, plus the default
+    # declaration. Needs nothing but cmake.
+    - name: Accept and reject declarations
+      run: .github/scripts/check_dispatch_surface.sh
+
+    # include/svs/core/distance/dispatch_surface.h is generated but committed, so
+    # that a bare `-I include` compile works without cmake. A configure refreshes
+    # it; if that produces a diff, either the declaration changed without a
+    # reconfigure or the header was edited by hand.
+    - name: Configure with the default surface
+      run: |
+        cmake -B "${{ runner.temp }}/build" -S "${GITHUB_WORKSPACE}" \
+              -DCMAKE_BUILD_TYPE=Release \
+              -DSVS_BUILD_TESTS=NO \
+              -DSVS_BUILD_BINARIES=NO
+
+    - name: Committed header matches the declaration
+      run: |
+        if ! git diff --exit-code -- include/svs/core/distance/dispatch_surface.h; then
+            echo "::error::include/svs/core/distance/dispatch_surface.h is stale." \
+                 "It is generated from cmake/dispatch-surface.cmake -- re-run cmake" \
+                 "and commit the result. Do not edit it by hand."
+            exit 1
+        fi
+
+  non-default-surface:
+    name: builds and tests with a non-default surface
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v6
+
+    # valid-reduced.cmake shares no extent with the default declaration, so a
+    # build that silently fell back to the committed header would fail to
+    # compile rather than pass by accident.
+    - name: Configure
+      run: |
+        cmake -B "${{ runner.temp }}/build" -S "${GITHUB_WORKSPACE}" \
+              -DCMAKE_BUILD_TYPE=Release \
+              -DSVS_BUILD_TESTS=YES \
+              -DSVS_BUILD_BINARIES=NO \
+              -DSVS_DISPATCH_SURFACE_FILE="${GITHUB_WORKSPACE}/tests/cmake/dispatch-surface/valid-reduced.cmake"
+
+    - name: Build
+      working-directory: ${{ runner.temp }}/build
+      run: make -j$(nproc)
+
+    # Correctness must not depend on which extents have a fixed-extent kernel:
+    # an extent without one is served by the svs::Dynamic kernel instead. The
+    # long-running tests are covered by the default-surface build.
+    - name: Run tests
+      env:
+        CTEST_OUTPUT_ON_FAILURE: 1
+      working-directory: ${{ runner.temp }}/build/tests
+      run: ctest -C Release -LE long
+
+    # Overriding the surface for one build must not rewrite the committed header.
+    - name: Committed header was left alone
+      run: |
+        if ! git diff --exit-code -- include/svs/core/distance/dispatch_surface.h; then
+            echo "::error::A build with an overridden dispatch surface rewrote the" \
+                 "committed header. Only the default declaration may refresh it."
+            exit 1
+        fi

.pre-commit-config.yaml

@@ -34,3 +34,14 @@ repos:
         args: [--markdown-linebreak-ext=md]
         exclude: .*\.svg$
       - id: mixed-line-ending
+
+  - repo: local
+    hooks:
+      # Cheap enough to run on every touch of the declaration, and it needs
+      # nothing but cmake -- no compiler, no build directory.
+      - id: dispatch-surface
+        name: dispatch surface declaration
+        entry: .github/scripts/check_dispatch_surface.sh
+        language: script
+        pass_filenames: false
+        files: ^(cmake/(dispatch-surface|validate-dispatch-surface)\.cmake|tests/cmake/dispatch-surface/.*\.cmake|\.github/scripts/check_dispatch_surface\.sh)$

cmake/generate-dispatch-surface.cmake

@@ -27,12 +27,11 @@ set(SVS_DISPATCH_SURFACE_FILE "${SVS_DEFAULT_DISPATCH_SURFACE_FILE}"
     CACHE FILEPATH
     "Declaration of the ahead-of-time distance-kernel dispatch surface"
 )
-if(NOT EXISTS "${SVS_DISPATCH_SURFACE_FILE}")
-    message(FATAL_ERROR
-        "SVS_DISPATCH_SURFACE_FILE does not exist: ${SVS_DISPATCH_SURFACE_FILE}"
-    )
-endif()
-include("${SVS_DISPATCH_SURFACE_FILE}")
+
+# Reads the declaration and rejects it if it is malformed. Also runnable on its
+# own -- see .github/scripts/check_dispatch_surface.sh.
+set(SVS_X86_SRC_DIR "${PROJECT_SOURCE_DIR}/include/svs/multi-arch/x86")
+include("${CMAKE_CURRENT_LIST_DIR}/validate-dispatch-surface.cmake")
 
 file(REAL_PATH "${SVS_DISPATCH_SURFACE_FILE}" svs_surface_real)
 file(REAL_PATH "${SVS_DEFAULT_DISPATCH_SURFACE_FILE}" svs_default_surface_real)
@@ -54,123 +53,40 @@ set_property(
 )
 
 #####
-##### Validate the extent list
-#####
-
-if(NOT SVS_SUPPORTED_DIMS)
-    message(FATAL_ERROR
-        "SVS_SUPPORTED_DIMS is empty in ${SVS_DISPATCH_SURFACE_FILE}. At least "
-        "one fixed extent is required."
-    )
-endif()
-
-foreach(dim IN LISTS SVS_SUPPORTED_DIMS)
-    if(NOT dim MATCHES "^[1-9][0-9]*$")
-        message(FATAL_ERROR
-            "SVS_SUPPORTED_DIMS contains '${dim}', which is not a positive "
-            "integer. svs::Dynamic is required and is appended automatically, "
-            "so it must not be listed."
-        )
-    endif()
-endforeach()
-
-set(svs_dims_sorted ${SVS_SUPPORTED_DIMS})
-list(REMOVE_DUPLICATES svs_dims_sorted)
-list(LENGTH SVS_SUPPORTED_DIMS svs_dims_given)
-list(LENGTH svs_dims_sorted svs_dims_unique)
-if(NOT svs_dims_given EQUAL svs_dims_unique)
-    message(FATAL_ERROR
-        "SVS_SUPPORTED_DIMS contains duplicate extents. Every extent must "
-        "appear exactly once."
-    )
-endif()
-
-# svs::Dynamic is mandatory: it is what serves every dimensionality without a
-# fixed-extent kernel, and the library is incorrect without it.
-set(svs_dim_list ${SVS_SUPPORTED_DIMS} "svs::Dynamic")
-list(LENGTH svs_dim_list SVS_GEN_DIM_COUNT)
-
-#####
-##### Validate the ISA levels
-#####
-
-if(NOT SVS_ISA_LEVELS)
-    message(FATAL_ERROR "SVS_ISA_LEVELS is empty in ${SVS_DISPATCH_SURFACE_FILE}.")
-endif()
-
-set(svs_seen_levels)
-set(svs_seen_infixes)
-foreach(level_spec IN LISTS SVS_ISA_LEVELS)
-    string(REPLACE "|" ";" level_fields "${level_spec}")
-    list(LENGTH level_fields nfields)
-    if(NOT nfields EQUAL 3)
-        message(FATAL_ERROR
-            "Malformed SVS_ISA_LEVELS entry '${level_spec}': expected exactly "
-            "three '|'-separated fields <enumerator>|<instruction budget>|<TU infix>."
-        )
-    endif()
-    list(GET level_fields 0 level)
-    list(GET level_fields 1 arch)
-    list(GET level_fields 2 infix)
-    foreach(field level arch infix)
-        if(NOT ${field})
-            message(FATAL_ERROR
-                "Malformed SVS_ISA_LEVELS entry '${level_spec}': ${field} is empty."
-            )
-        endif()
-    endforeach()
-    if(level IN_LIST svs_seen_levels)
-        message(FATAL_ERROR "Duplicate ISA level '${level}' in SVS_ISA_LEVELS.")
-    endif()
-    if(infix IN_LIST svs_seen_infixes)
-        message(FATAL_ERROR
-            "Duplicate TU infix '${infix}' in SVS_ISA_LEVELS; infixes name "
-            "generated files and must be unique."
-        )
-    endif()
-    list(APPEND svs_seen_levels ${level})
-    list(APPEND svs_seen_infixes ${infix})
-endforeach()
-
-#####
-##### Generate the header
+##### Build the macro bodies
 #####
 
 # Line continuations are emitted with a trailing backslash; the generated macros
 # are one logical line each.
+set(SVS_GEN_DIM_COUNT ${SVS_DIM_COUNT})
+
 set(SVS_GEN_DIM_LOOP "\\\n")
-foreach(dim IN LISTS svs_dim_list)
+foreach(dim IN LISTS SVS_DIM_LIST)
     string(APPEND SVS_GEN_DIM_LOOP "    M(${dim}) \\\n")
 endforeach()
 string(APPEND SVS_GEN_DIM_LOOP "    /* end */")
 
 set(SVS_GEN_TARGET_LOOP "\\\n")
 set(SVS_GEN_LEVEL_LOOP "\\\n")
 set(SVS_DISPATCH_TU_SPECS)
-set(svs_x86_src_dir "${PROJECT_SOURCE_DIR}/include/svs/multi-arch/x86")
 foreach(level_spec IN LISTS SVS_ISA_LEVELS)
     string(REPLACE "|" ";" level_fields "${level_spec}")
     list(GET level_fields 0 level)
     list(GET level_fields 1 arch)
     list(GET level_fields 2 infix)
 
     string(APPEND SVS_GEN_LEVEL_LOOP "    M(${level}) \\\n")
-    foreach(dim IN LISTS svs_dim_list)
+    foreach(dim IN LISTS SVS_DIM_LIST)
         string(APPEND SVS_GEN_TARGET_LOOP "    M(${dim}, ${level}) \\\n")
     endforeach()
 
     # One translation unit per level, named after the level's infix. The file
     # itself is short -- it loops over the generated extent list -- but it is
-    # committed rather than generated, because the private repository compiles
-    # these sources by path.
-    set(tu_src "${svs_x86_src_dir}/${infix}.cpp")
-    if(NOT EXISTS "${tu_src}")
-        message(FATAL_ERROR
-            "ISA level '${level}' has no translation unit: expected ${tu_src}. "
-            "Adding a level to SVS_ISA_LEVELS requires creating that file."
-        )
-    endif()
-    list(APPEND SVS_DISPATCH_TU_SPECS "${tu_src}|${level}|${arch}|${infix}")
+    # committed rather than generated, because the downstream repository compiles
+    # these sources by path. Its existence was checked during validation.
+    list(APPEND SVS_DISPATCH_TU_SPECS
+        "${SVS_X86_SRC_DIR}/${infix}.cpp|${level}|${arch}|${infix}"
+    )
     list(APPEND svs_level_report
         "AVX_AVAILABILITY::${level} -march=${arch} ${infix}.cpp"
     )
@@ -217,7 +133,7 @@ endif()
 list(LENGTH SVS_ISA_LEVELS svs_level_count)
 string(REPLACE ";" " " svs_dims_display "${SVS_SUPPORTED_DIMS}")
 message(STATUS
-    "Dispatch surface: ${SVS_GEN_DIM_COUNT} extents x ${svs_level_count} ISA levels"
+    "Dispatch surface: ${SVS_DIM_COUNT} extents x ${svs_level_count} ISA levels"
 )
 message(STATUS "  extents: ${svs_dims_display} svs::Dynamic")
 foreach(entry IN LISTS svs_level_report)