Make find_best_match selection explicit opt-in; add prefilter and SWAR32 finders

[BrianPugh]

Part 1 of 5 splitting the stm32h7-optimizations performance campaign into reviewable pieces (compressor match finders → decompressor fast paths → fuzz coverage → QEMU profiler → device harnesses). The original branch remains as the experiment-history archive; the stack's final tree is byte-identical to it.

What this does

The core sources no longer auto-select the 64-bit desktop matcher via #if __x86_64__ ... — the vendored trio now defaults to portable code everywhere, and each build system opts into its platform's measured configuration. setup.py opts wheels into TAMP_USE_DESKTOP_MATCH=1 on 64-bit hosts, so shipped wheels are unchanged.

• New common.h "Platform performance tuning" section: the TAMP_ARMV7EM profile knob and the TAMP_USE_{EMBEDDED,SWAR32,DESKTOP,PREFILTER}_MATCH selection. Selections are mutually exclusive including TAMP_ESP32 (the espidf component provides find_best_match via extern); conflicts are a compile error, guarded by must-NOT-compile entries in the new c-compile-matrix target.
• New first-byte prefilter finder: 1.36x compression on Cortex-M7 vs the portable scan (the TAMP_ARMV7EM default; ~0.5x on out-of-order 64-bit hosts, hence not the desktop choice).
• New experimental SWAR32 finder (opt-in only; measured 0.93x on M7 — kept for upcoming Cortex-M33/RP2350 evaluation).
• Desktop finder refactored onto a shared static inline tamp_match_extend; compressed output is byte-identical to the previous implementation (verified old-vs-new on enwik8 + text + random-compressible inputs across window bits 8–15).
• Tests: c-test now pins the desktop matcher (what wheels ship), new c-test-prefilter leg behaviorally covers the ARMV7EM matcher on host (wired into CI), c-test-embedded keeps covering the portable scan.

Behavior note for vendoring users

Projects that vendor common.c/compressor.c/decompressor.c and compiled on x86_64/aarch64 previously got the desktop matcher automatically; they now get the portable scan (correct output, slower compression) unless they define TAMP_USE_DESKTOP_MATCH=1. This is the intended contract — the core never self-selects architecture-specific code — and is documented in common.h and CLAUDE.md; worth a release-note line.

Verification

• All three C test legs pass 35/35 under ASan/UBSan (desktop, embedded, prefilter).
• c-compile-matrix passes, including the two must-NOT-compile conflict configs.
• Desktop-matcher output equivalence proven against main's implementation (24/24 input×window combinations byte-identical).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR makes find_best_match selection an explicit build-time opt-in (rather than auto-selected by architecture in core sources) and adds new match-finder variants plus CI coverage to keep the vendored C trio compiling and tested under the intended configurations.

Changes:

• Introduces explicit, mutually-exclusive match-finder selection flags in common.h (including treating TAMP_ESP32 as a selection) and updates documentation accordingly.
• Adds an inline first-byte prefilter matcher and a new experimental SWAR32 matcher, and refactors the desktop matcher to share common helper logic.
• Updates build/test tooling to pin the desktop matcher for c-test, add a c-test-prefilter CI leg, and add a compile-matrix target.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tamp/_c_src/tamp/compressor.c	Adds shared SWAR helper utilities and implements the inline prefilter matcher; switches selection logic to explicit flags.
tamp/_c_src/tamp/compressor_find_match_swar32.c	New experimental 32-bit SWAR match finder included by compressor.c when selected.
tamp/_c_src/tamp/compressor_find_match_desktop.c	Refactors desktop matcher to use shared helpers defined in compressor.c.
tamp/_c_src/tamp/common.h	Adds “Platform performance tuning” section and enforces mutually-exclusive match-finder selection flags.
setup.py	Opts Cython wheels into TAMP_USE_DESKTOP_MATCH=1 on 64-bit hosts to keep shipped behavior unchanged.
Makefile	Pins c-test to desktop matcher, adds c-test-prefilter, and adds c-compile-matrix compile coverage.
CLAUDE.md	Updates repository guidance to match the new explicit selection/standalone vendoring contract.
.github/workflows/tests.yaml	Adds CI leg to run make c-test-prefilter.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

[BrianPugh]

Closing in favor of splitting this into four smaller PRs — the four concerns here are independent, and bundling them meant the one part with consequences for existing consumers (the selection change) was reviewed alongside 350 lines of new matcher code.

The split, in dependency order:

1. Make find_best_match selection an explicit build-system opt-in #362 — pr1a-match-selection (+121/−18): the build-system policy change. Removes the 64-bit auto-detect from the core sources, adds the opt-in flags and the mutual-exclusion guard, c-compile-matrix. Both win32 CI fixes from this PR are folded in. Open as a draft.
2. pr1b-shared-swar-helpers (+86/−71): pure refactor hoisting tamp_ctzll / tamp_has_zero_byte / tamp_match_extend / TAMP_MATCH_UPDATE out of the desktop finder into compressor.c, replacing the EXTEND_MATCH do/while+flag macro. Net smaller than what it replaces.
3. pr1c-prefilter-match (+159/−7): the first-byte prefilter finder, TAMP_ARMV7EM, c-test-prefilter leg + CI job.
4. pr1d-swar32-match (+192/−6): the experimental 32-bit SWAR finder, opt-in only.

Nothing was dropped or changed in the split: git diff --quiet pr1-match-finders pr1d-swar32-match is clean, so the four branches' trees together are byte-identical to this PR's. The pr1-match-finders branch is being kept as the pre-split reference rather than deleted.

The review feedback on this PR (the win32 wheel gate, the shared tamp_ctzll 32-bit-MSVC guard, the matrix coverage and test-runner dependency fixes) all carried across — the guard lives in pr1b with the shared helper block it belongs to, the rest in pr1a.

Each branch was verified independently: all three C test legs 35/35 under ASan/UBSan, plus a per-branch differential confirming compressed output is byte-identical across every finder over the first 100 KB of enwik8 at each window size 8..15.