refactor: de-duplicate the dispatch helpers into shared headers

[balbasty]

De-duplicates the copy-pasted helper macros and functions in the two
dtype-dispatch layers and the hub into shared headers, giving them
collision-safe FF_ names as they move.

This is PR 1 of 2. The follow-up
(refactor/prefix-public-macros) prefixes the remaining unprefixed public
macros, FF itself included. De-dup first, because it is the smaller and more
substantive change, and separating them makes a regression trivially
bisectable.

What was duplicated

macro / function	copies	where
VOIDPTR, CANUSE32BITS, CHECK_NO_LANES	19 each	src/lib-cpu (8–10) + src/lib-cuda (9) + both api/*/pushpull_dispatch.h
CHECK_SAME, CHECK_SAME_DTYPE	17 each	same
CVOIDPTR	11	same
CHECK_SAME_BATCH	10	same
CHECK_SAME_SHAPE	9	same
IS_CPU, IS_CUDA	9 each	src/lib (hub)
as_weights(), _reg_stream()	3, 4	reg_field* / reg_flow*

Note the counts are 19/17, not the 17/15 in the original audit: VOIDPTR and
friends were already on the installed public surface via
include/fastfields/api/{cpu,cuda}/pushpull_dispatch.h. They were never purely
TU-private, which strengthens rather than weakens the case for the rename.

Three of them had genuinely diverged

Not formatting — behaviour:

macro	the divergence	now
CVOIDPTR	posdef.cppalone guards a null data; an absent optional operand arrives as a descriptor with data == nullptr, and offsetting a null pointer is UB	FF_CVOIDPTR_OR_NULL
CHECK_SAME_BATCH	distance.cpp / posdef.cppalone also reject ndim < D — they derive D from an operand's own ndim and would otherwise read past the end of shape[]	FF_CHECK_SAME_BATCH_ND
CHECK_SAME_SHAPE	two different macros sharing one name — a 2-arg whole-shape check in distance.cpp, a 3-arg leading-D check in the regularisers and solve_field	FF_CHECK_SAME_SHAPE / FF_CHECK_SAME_SHAPE_N

The last one is the argument for doing this at all. With 17 private copies, one
name silently meant two things, and nothing in the tree could have told you.
Each divergence keeps its own name so the difference is visible at the call
site rather than hiding in one file's prologue.

(CHECK_NO_LANES and CHECK_SAME_DTYPE also had two spellings each — those
really are line-wrapping only, and the proof below confirms it.)

Where things went, and why

Placement is by audience, and the audience question that bites is which
compiler sees the code.

new/changed	contents	why there
include/fastfields/core/dispatch.h(new)	FF_VOIDPTR, FF_CVOIDPTR, FF_CVOIDPTR_OR_NULL, FF_CANUSE32BITS, the FF_CHECK_* family, as_weights()	src/lib-cuda is compiled by nvcc while src/lib-cpu and src/lib use the host compiler. Anything all three share must be backend-agnostic, and core/ is the only directory that is so by contract. api/checks.h is host-only and was the wrong home.
include/fastfields/api/cuda/stream.h(new)	_reg_stream()	Names cudaStream_t, so CUDA-only by construction. Also keeps CI's path filter honest — in core/ it would have triggered the CPU legs for nothing.
include/fastfields/api/checks.h(extended)	is_cpu() / is_cuda() inline functions	Used only by the host-compiled hub. A function in ff:: is collision-safe with no prefix at all, so these two macros are deleted rather than renamed.

core/dispatch.h deliberately does not wrap the checks in
do { … } while (0), and says so: the 17 copies did not, and wrapping them
would silently change which statements a brace-less
if (cond) FF_CHECK_…(…); guards. Tightening that is a behaviour change and
belongs in its own commit, measured against the CPU suite.

The naming rule applied

Every macro that survives preprocessing of a header under include/ — every
#define not #undef'd before the end of the header that defined it — must
be spelled FF_*.

Macros private to a single .cpp are exempt: they never leave the translation
unit. But the moment one is hoisted into a header it stops being private —
which is exactly why de-duplicating and prefixing are one change and not two.
Where an inline function will do, prefer it and delete the macro outright
(IS_CPU/IS_CUDA here; uchar_t in PR 2).

Evidence: proved, not asserted

tools/macro-equivalence.py preprocesses every (file, macro) pair on both
sides of the change and compares token streams:

$ git worktree add --detach /tmp/base HEAD~1
$ python3 tools/macro-equivalence.py /tmp/base .
OK(parens) src/lib-cpu/posdef.cpp CVOIDPTR -> FF_CVOIDPTR_OR_NULL
OK(parens) src/lib-cuda/posdef.cpp CVOIDPTR -> FF_CVOIDPTR_OR_NULL
121 macro expansions compared across 23 files: 119 exact, 2 balanced-paren-only, 0 MISMATCHED

The two non-exact ones are FF_CVOIDPTR_OR_NULL, which composes FF_CVOIDPTR
and so carries one extra balanced parenthesis pair; the tool only accepts
that after checking the token streams are identical once parentheses are
removed. Everything else matches exactly.

A whole-translation-unit token diff was tried first and is the wrong
instrument — core/dispatch.h pulls in <vector> and makes as_weights()
visible everywhere, which swamps the signal with additive, behaviour-free
noise. Comparing the expansions in isolation asks the question that matters.

Reviewing this

Do not read 1100 renamed call sites. Re-derive them:

git checkout HEAD~1 -- include src
python3 tools/dedup-dispatch-helpers.py
git diff # must be empty

Both scripts are committed and idempotent for exactly this reason.

Validation

• make test CXX=clang++ — the CPU suite, 59,886 checks across 13 suites,
  0 failures, unchanged. (Results are in the review comment below once the
  clean-worktree run finishes.)
• codespell clean.
• CUDA is compile+link only, as always — no GPU here, so build-cuda in CI is
  the bar. core/dispatch.h correctly triggers the full matrix.

Note on the clang-format check

It will report against this PR, and its report will be empty. The job is
broken, independently of this change: git-clang-format-18 --diff exits 1
when the diff is non-empty, and the step runs it under set -euo pipefail in a
command substitution, so the script dies at the assignment before reaching
the case that would print the diff. That is why #85 (docs-only) shows a bare
exit 1 with no output. It is continue-on-error: true, so it does not block.
Reproduced locally; details in the task report. Not fixed here — the workflow
file is already being edited by #87.

For the record, the tree is not clang-format-clean on main either
(src/lib-cpu/splinc.cpp alone differs by 154 lines), which is why that job is
advisory in the first place.

---

Generated by Claude Code

[balbasty]

Gate: unmoved

test-cpu (clang-dynamic) on this PR, per-suite, straight from the job log:

suite	checks	failures
distance	2352	0
distance_mesh	4622	0
distance_spline	704	0
posdef	4012	0
pushpull	308	0
pushpull_backward	6381	0
reg_field	19250	0
reg_flow	16347	0
reg_op	186	0
resize	630	0
restrict	65	0
solve_field	452	0
splinc	4577	0
13 suites	59 886	0

Every row matches tools/test-baseline.expected exactly. Not just "the suite
passed" — the check counts are identical, which is the property that would
catch an assertion silently disappearing.

test-hub green too (5 + 9 = 14 assertions), and compile-probe-cuda green —
so nvcc accepts the changed headers.

Layered evidence

1. Macro expansions — 121 (file, macro) pairs preprocessed on both sides,
   token streams compared: 119 exact, 2 balanced-paren-only, 0 mismatched.
   Re-runnable: python3 tools/macro-equivalence.py <old-tree> .
2. The rewrite — re-derivable: git checkout HEAD~1 -- include src && python3 tools/dedup-dispatch-helpers.py && git diff is empty.
3. The gate — the table above.
4. CUDA — compile + link only, as always. No GPU here; nothing about
   runtime CUDA behaviour is claimed.

The clang-format check is broken — independently of this PR

It reports failure here with no diff printed, same as on #85 (docs-only).
Root cause, reproduced locally with the pinned clang-format 18:

$ git-clang-format --diff --extensions h,hpp,inl,cpp,cu,cuh HEAD~1
EXIT=1 outlen=406 # exits 1 when the diff is NON-EMPTY
$ bash -c 'set -euo pipefail; o=$(git-clang-format --diff ... HEAD~1); echo "CASE REACHED"'
ci-construct exit=1 # "CASE REACHED" never prints

The step runs out=$(git-clang-format-18 --diff …) under set -euo pipefail.
git-clang-format --diff exits 1 whenever it has something to say, so the
script dies at the assignment before reaching the case that would echo
$out. The job therefore reports a formatting failure while showing you
nothing — the one thing that would let you act on it.

One-line fix, for whoever owns it: out=$(… || true), or bracket the
assignment with set +e / set -e. Not done here — .github/workflows/ci.yml
is already being edited by #87, and this is not that PR's business either way.

It is continue-on-error: true, so it blocks nothing. Worth knowing that the
tree is not clang-format-clean on main regardless (src/lib-cpu/splinc.cpp
alone differs by 154 lines), which is why the job is advisory — a mechanical
rename in a hand-column-aligned tree was always going to light it up.

---

Generated by Claude Code

[balbasty]

Local clean-worktree run finished, confirming the CI numbers on a second machine and toolchain invocation:

$ make -j2 test CXX=clang++ # clean tree, dedicated worktree
MAKE_EXIT=0
13 suites | 59886 checks | 0 failures

Per-suite, identical to tools/test-baseline.expected row for row:
2352 / 4622 / 704 / 4012 / 308 / 6381 / 19250 / 16347 / 186 / 630 / 65 / 452 / 4577.

Also verified: core/dispatch.h, api/cuda/stream.h and api/checks.h each
compile standalone (clang++ -fsyntax-only on a TU that includes only that
header), so the new headers are genuinely self-contained rather than relying on
their first includer.

---

Generated by Claude Code

[balbasty]

Validation status at hand-off

gate	#90	#91
test-cpu (clang-static)	✅	✅
test-cpu (clang-dynamic)	✅	✅
test-cpu (clang-cuda-default)	✅	✅
test-cpu (gcc-static)	✅	✅
test-cpu (sanitize asan+ubsan)	✅	✅
test-hub	✅	✅
compile-probe-cuda (nvcc)	✅	✅
lint (codespell)	✅	✅
lint (clang-format)	❌ — job is broken, see above	❌ — same
build-cuda (compile + link)	still running	still running
local make test (clean worktree)	✅ 13 / 59 886 / 0	✅ 13 / 59 886 / 0

All four boundary/spline compile policies agree with the reference oracle, ASan

• UBSan are clean, and nvcc already accepts the changed impl/kernels and
  impl/cuda headers via compile-probe-cuda.

build-cuda is the one gate not yet observed green — it is the ~35-minute
full nvcc compile+link of src/lib-cuda, and it was still running at hand-off.
It is the leg that matters most for these headers (half the de-duplicated
macros live in nvcc-compiled sources), so please confirm it on the PR rather
than taking the rest of this table as sufficient. No claim is made about CUDA
runtime behaviour — there is no GPU in CI and compile+link is the accepted
bar.

---

Generated by Claude Code