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

.github/copilot-instructions.md

@@ -15,6 +15,11 @@ This file is the canonical instruction set for Copilot behavior in this reposito
 - Use source-of-truth files for mutable details.
 - Do not invent or hardcode versions/flags/matrices.
 - Avoid `std::iostream` in performance-critical headers.
+- Add a file only where the nearest `AGENTS.md` purpose line covers its kind and its role; otherwise it belongs in the directory whose purpose line matches.
+- A comment states why the code has to be this way and what breaks if it changes, not what the line does; a documentation block on a public entity states that entity's contract. When a change alters code a comment describes, fix or delete that comment in the same change.
+- Where code encodes a constraint a reader cannot infer — a platform-specific guard, a derived numeric bound, a warning suppression — comment the reason and what breaks without it. Standard idioms such as a floating-point tolerance need no justification.
+- Delete code a change makes dead rather than committing it disabled: commented-out statements, unused variables, branches the change makes unreachable. A conditional-compilation path is not dead merely because no CI job selects it. Code deliberately left inert carries a comment saying why.
+- A path that cannot satisfy a request fails with a diagnostic naming the unsupported input and the bound or set it violated, rather than substituting a different configuration; a preprocessor or dispatch chain ends in a catch-all that errors instead of assuming the last case holds.
 
 ## Contribution expectations
 - Preserve backward compatibility for public API (`include/svs/`)

.github/instructions/bindings.instructions.md

@@ -0,0 +1,8 @@
+---
+applyTo: "bindings/**"
+---
+
+# Bindings Instructions for GitHub Copilot
+
+- A binding reports failure through its own error channel and lets nothing escape across the boundary: an entry point that cannot propagate an exception is marked `noexcept` and returns its error type. Each binding has its own channel — do not assume another's.
+- A binding does not restate a default, policy, or limit the core library already selects; pass the core's own sentinel or value through, so the binding cannot drift from it.

.github/instructions/build-system.instructions.md

@@ -1,10 +1,11 @@
 ---
-applyTo: "{CMakeLists.txt,cmake/**}"
+applyTo: "{CMakeLists.txt,cmake/**,.github/workflows/**}"
 ---
 
 # Build System Instructions for GitHub Copilot
 
-- Use existing option/target patterns; avoid introducing parallel build paths.
+- Use existing option/target patterns; avoid introducing parallel build paths. Before adding a compile flag, option, or CI setup step, check whether an existing one already covers the condition; where the same block genuinely exists in more than one file, either change every copy or factor it into one included file.
 - Keep configuration values referenced from existing CMake modules.
+- Return a computed value another module consumes from a `function()` via `PARENT_SCOPE`, or publish it as a cache entry; a bare `set()` at file scope is not an interface, and a later module setting the same name collides with it silently.
 - Do not hardcode versions/toolchain assumptions in instructions or comments.
 - For behavior changes, suggest updating/validating CI workflows in `.github/workflows/`.

.github/instructions/documentation.instructions.md

@@ -0,0 +1,7 @@
+---
+applyTo: "{bindings/**/*.md,**/docs/**/*.md,README.md}"
+---
+
+# Documentation Instructions for GitHub Copilot
+
+- State a policy, requirement, or API description in one place and reference it from the others. A second copy silently drops the parts that matter — a compatibility contract, a constraint — and then diverges from the original.

.github/instructions/library-code.instructions.md

@@ -0,0 +1,13 @@
+---
+applyTo: "include/svs/**"
+---
+
+# Library Code Instructions for GitHub Copilot
+
+- Emit diagnostics through `svs::logging`, never to stdout or stderr. An API whose declared purpose is writing a report to a caller-supplied stream is not a diagnostic and is exempt.
+- Document every parameter of a public entity, including what a default resolves to and which level of a nested structure it governs. A placeholder standing for "let the library choose" is used only where the default really is computed at call time, and says so; where the default is a fixed value, state that value.
+- Do not widen a type's public surface so another layer can compute something from its internals; the layer that owns a quantity owns the operation on it. Forwarding to an owned member is fine.
+- A helper, cast, or constant that more than one component needs belongs in one shared header rather than copied into each user, and a defaulted parameter is preferred over a near-duplicate overload. A type more than one component references is declared where all of them can reach it, not nested inside the first one that needed it.
+- A conditional-compilation guard is a claim about what the code inside it depends on, so make the condition exactly that: not a narrower feature flag standing in for the broader platform, and not a higher instruction-set level than the surrounding path targets. Deleting such a guard removes a configuration; do not delete one as cleanup without confirming nothing builds that way.
+- Name an entity for the role it plays, not the value it holds or the one algorithm that currently uses it.
+- Express a requirement where the compiler enforces it — a `concept` on a template parameter, `constexpr` for a value fixed at compile time — rather than as a runtime check or a comment.

.github/instructions/multi-arch.instructions.md

@@ -0,0 +1,7 @@
+---
+applyTo: "include/svs/multi-arch/**"
+---
+
+# Multi-Arch Instructions for GitHub Copilot
+
+- Include the header that defines any macro which expands into a translation unit's own declarations or definitions. This covers code-generating macros, not inline annotations such as a force-inline, unused, or forwarding marker. A generating macro whose defining header is absent hides what the file actually defines, so its contents cannot be determined by reading the file alone.

.github/instructions/testing.instructions.md

@@ -1,10 +1,12 @@
 ---
-applyTo: "tests/**"
+applyTo: "{tests/**,bindings/*/tests/**}"
 ---
 
 # Testing Instructions for GitHub Copilot
 
 - Add regression tests for bug fixes.
-- Keep tests deterministic and scoped to changed behavior.
-- Prefer smallest test surface that proves correctness.
+- Keep tests deterministic.
+- Prefer the smallest test surface that proves correctness for a given variant, then cover every variant the subject documents — each index type, each dataset or quantization kind the shared reference helpers accept — rather than the default alone.
+- Drive the subject into the state under test rather than only calling the API that would reach it: enough input to cross a batch boundary for per-batch behaviour, a mutation before the save/load round trip for a structure that supports mutation.
+- A new test goes through the existing shared fixture or parametrized helper for its subject rather than reimplementing the setup. Where no helper covers the subject, or where reusing one would defeat what the test asserts, bespoke setup is correct.
 - Refer to repository test/build configuration as source of truth rather than duplicating values.

.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.