refactor(dispatch): Generate and validate the dispatch surface from a single declaration

.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,21 @@ 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
+        # (?x) ignores the layout below; without it the alternation is one
+        # unreadable line and every edit to it risks silently matching nothing.
+        files: |
+          (?x)^(
+            cmake/(dispatch-surface|validate-dispatch-surface)\.cmake
+            |tests/cmake/dispatch-surface/.*\.cmake
+            |\.github/scripts/check_dispatch_surface\.sh
+          )$

CMakeLists.txt

@@ -135,6 +135,17 @@ install(
     DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
     FILES_MATCHING PATTERN "*.h"
 )
+
+# Install the generated dispatch-surface header over the committed one. They are
+# identical for the default declaration; if the surface was overridden, the
+# installed headers must describe what the library was actually built with. This
+# must be declared after the directory install above so that it wins.
+if(DEFINED SVS_GENERATED_DISPATCH_HEADER)
+    install(
+        FILES "${SVS_GENERATED_DISPATCH_HEADER}"
+        DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/svs/core/distance"
+    )
+endif()
 install(
     EXPORT svs-targets
     NAMESPACE "svs::"

cmake/AGENTS.md

@@ -9,7 +9,8 @@ Build modules, dependency wiring, and feature toggles.
 
 ## Intel-specific modules
 - **`cmake/mkl.cmake`:** MKL linkage (static vs dynamic threading). Do not hardcode MKL versions. When changing linkage mode, validate threading behavior in tests.
-- **`cmake/multi-arch.cmake`:** AVX-512 / SIMD ISA dispatch. Do not hardcode `-march` or ISA flags outside this file. Changes must align with `include/svs/multi-arch/` runtime dispatch code.
+- **`cmake/multi-arch.cmake`:** AVX-512 / SIMD ISA dispatch wiring. Changes must align with `include/svs/multi-arch/` runtime dispatch code.
+- **`cmake/dispatch-surface.cmake`:** The declared x86 dispatch surface — fixed extents, ISA levels, and their `-march` budgets. Edit it, never the generated `include/svs/core/distance/dispatch_surface.h`, which every configure overwrites. `tests/multi-arch/dispatch-checks/` holds the ctest checkers that hold the built binary to this declaration.
 - **`cmake/numa.cmake`:** NUMA-aware memory allocation. Respect NUMA topology assumptions in performance-critical code.
 - **`cmake/openmp.cmake`:** Threading model. Do not assume specific OpenMP version or runtime without checking source-of-truth.
 

cmake/dispatch-levels.cmake

@@ -0,0 +1,56 @@
+# 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.
+
+include_guard(GLOBAL)
+
+## A function captures the policy stack where it is defined, so CMP0007 is set here rather
+## than by the caller: under OLD an empty field vanishes and a row with one is called malformed.
+cmake_policy(PUSH)
+cmake_policy(SET CMP0007 NEW)
+
+# Parses an ISA level spec from SVS_ISA_LEVELS and returns the three fields.
+# The spec format is <level>|<arch>|<infix>.
+function(svs_parse_isa_level spec out_level out_arch out_infix)
+  string(REPLACE "|" ";" fields "${spec}")
+  list(LENGTH fields n)
+  if(NOT n EQUAL 3)
+    message(FATAL_ERROR "Malformed ISA level '${spec}': expected <level>|<arch>|<infix>.")
+  endif()
+  list(GET fields 0 v0)
+  list(GET fields 1 v1)
+  list(GET fields 2 v2)
+  set(${out_level} "${v0}" PARENT_SCOPE)
+  set(${out_arch}  "${v1}" PARENT_SCOPE)
+  set(${out_infix} "${v2}" PARENT_SCOPE)
+endfunction()
+
+# Parses a translation unit spec from SVS_DISPATCH_TU_SPECS and returns the four fields.
+# The spec format is <src>|<level>|<arch>|<infix>.
+function(svs_parse_tu_spec spec out_src out_level out_arch out_infix)
+  string(REPLACE "|" ";" fields "${spec}")
+  list(LENGTH fields n)
+  if(NOT n EQUAL 4)
+    message(FATAL_ERROR "Malformed TU spec '${spec}': expected <src>|<level>|<arch>|<infix>.")
+  endif()
+  list(GET fields 0 v0)
+  list(GET fields 1 v1)
+  list(GET fields 2 v2)
+  list(GET fields 3 v3)
+  set(${out_src}    "${v0}" PARENT_SCOPE)
+  set(${out_level}  "${v1}" PARENT_SCOPE)
+  set(${out_arch}   "${v2}" PARENT_SCOPE)
+  set(${out_infix}  "${v3}" PARENT_SCOPE)
+endfunction()
+
+cmake_policy(POP)