build: make the 32-bit index axis a per-backend option (FF_INDEX32), default unchanged

[balbasty]

Makes the 32-bit index axis a build option, per backend, defaulting to
today's behaviour on both. Nothing about the shipping libraries changes; what
changes is that the axis can be turned off for one backend without touching the
other, and that both positions are now built by CI.

Follow-up to the measurement in #94 (draft, not merged). It takes that PR's
FF_INDEX32 mechanism only — not the dispatch-driver experiment, and not the
struct-wrapping that re-indents whole files.

The axis, and what it costs

Every templated kernel below the dispatch layer is templated on offset_t,
which has exactly two values chosen per call by canUse32BitIndexMath:
int32_t when every operand's largest element offset fits in 32 bits,
int64_t otherwise. So the narrow path is exactly ×2 instantiations of
everything underneath — on CUDA, ×2 device code, ×2 SASS, ×2 ptxas memory.
core/autocast.h exists solely to feed that second instantiation.

The spelling, and why

FF_INDEX32 — one macro in core/dispatch.h — plus INDEXFLAGS, one make
variable defaulted separately in src/lib-cpu/Makefile and
src/lib-cuda/Makefile.

That is the BOUNDFLAGS/SPLINEFLAGS pattern verbatim, and the per-library
default is the per-backend mechanism: FF_STATIC_BOUNDS is also one macro,
and only differs between backends because the two Makefiles say so. An
FF_INDEX32_CPU / FF_INDEX32_CUDA pair would instead force
core/dispatch.h to branch on __CUDACC__ — putting the policy in the source,
in the one directory that is backend-agnostic by contract — and any third
consumer would have to know both names. INDEXFLAGS also stays outside
CXXFLAGS, for the reason the other two do: CUDA CI overrides CXXFLAGS to
force -O1 and must not silently drop a policy while doing it.

The type the narrow arm names is a typedef, ff::off32_t, not a macro —
CLAUDE.md's own guidance ("prefer an inline function to a macro where one
will do; a name in ff:: is collision-safe without any prefix"). It is also
exactly as wide as int32_t, so the 140-line source change is a pure token
swap and not one line-continuation backslash moves.

Default unmoved — object-level proof

All ten src/lib-cpu modules compiled from main (85fdac7) and from this
branch at the default produce byte-identical objects:

distance IDENTICAL posdef IDENTICAL resize IDENTICAL restrict IDENTICAL
splinc IDENTICAL pushpull IDENTICAL pushpull_backward IDENTICAL
reg_field IDENTICAL reg_flow IDENTICAL solve_field IDENTICAL

(clang++ -std=c++11 -O1 -fPIC -DFF_STATIC_BOUNDS=0 -DFF_STATIC_SPLINES=0,
cmp on the .o.)

Gate, locally, make test-lib-cpu: 13 suites, 59,886 checks, 0 failures, in
both positions. In CI the four pre-existing test-cpu legs, sanitize and
tsan are all green, and test-cpu (clang-index64)'s per-suite counts sum
row-for-row to tools/test-baseline.expected (2352 + 4622 + 704 + 4012 + 308 +
6381 + 19250 + 16347 + 186 + 630 + 65 + 452 + 4577 = 59,886).

tools/rename-macros.py --check → 0 file(s) would change, include/ is clean. codespell clean.

Both positions build and pass

CI gains the two legs that make this an option rather than a claim:

• test-cpu (clang-index64) — the whole suite with FF_INDEX32=0. Green.
• build-cuda becomes a two-leg matrix, index32 (shipping, the gate) and
  index64. Both green, both through the full compile + hub link +
  ldd -r check. The off leg is the cheaper of the two (~19 min vs ~38), and
  it turns the FFMEM table into a direct measurement of the axis on the
  backend where it costs the most.

Numbers

CPU — clang++ -O3 -fPIC, BOUNDFLAGS/SPLINEFLAGS at the CUDA shipping
policy. "instantiations" = defined weak symbols in the object.

module	instantiations	object	peak RSS
reg_flowmain	10,219	18,952 KB	1,120 MB
reg_flowFF_INDEX32=0	5,123 (−49.9%)	9,658 KB (−49.0%)	624 MB (−44.3%)
reg_fieldmain	9,655	19,075 KB	1,044 MB
reg_fieldFF_INDEX32=0	4,857 (−49.7%)	9,570 KB (−49.8%)	602 MB (−42.3%)
pushpull_backwardmain	5,248	11,213 KB	958 MB
pushpull_backwardFF_INDEX32=0	2,656 (−49.4%)	5,479 KB (−51.1%)	562 MB (−41.3%)
posdefmain	420	671 KB	167 MB
posdefFF_INDEX32=0	252 (−40.0%)	383 KB (−42.9%)	150 MB (−10.2%)

Reproduces #94's table (it measured 18,952 KB / 1,126 MB for reg_flow on
main and 9,661 KB / 624 MB with the axis off).

Whole libfastfields-cpu.so, all-Dynamic policy:

	exported symbols	size
FF_INDEX32=1	27,491	30.5 MiB
FF_INDEX32=0	14,051 (−48.9%)	15.6 MiB (−49.0%)

The off-position symbol set is a strict subset: 13,440 symbols disappear,
0 appear, and every one that disappears is an offset_t = int32_t template
instantiation. No public entry point changes — the exported ABI is the same
library with half the template bodies.

CUDA — both legs of one build-cuda run, nvcc -O1 -j2, shipping
bound/spline policy. Peak nvcc RSS (GiB) / wall per module:

module	FF_INDEX32=1	FF_INDEX32=0	Δ RSS
reg_flow	12.97 / 1023 s	5.69 / 497 s	−56.1%
reg_field	8.09 / 791 s	3.76 / 343 s	−53.5%
reg_field_rls	7.07 / 701 s	3.42 / 353 s	−51.7%
resize	2.00 / 193 s	1.08 / 113 s	−46.2%
reg_flow_rls	1.90 / 155 s	1.01 / 89 s	−46.9%
pushpull_backward	1.51 / 167 s	0.80 / 102 s	−46.9%
pushpull	1.48 / 158 s	0.79 / 97 s	−46.6%
restrict	1.30 / 120 s	0.68 / 72 s	−47.4%
distance	0.80 / 118 s	0.54 / 61 s	−33.1%
splinc	0.42 / 68 s	0.27 / 37 s	−35.5%
posdef	0.37 / 40 s	0.35 / 28 s	−6.9%
total nvcc CPU	3532 s	1791 s	−49.3%
job wall clock	~38 min	~19 min

CUDA is worse than the host-compiler extrapolation implied, not better:
reg_flow sheds 56.1% rather than the 44.6% clang showed. This table is now
recorded above MODULES in src/lib-cuda/Makefile.

Two things worth flagging from the left-hand column, since the existing note
there claims the heavy modules reproduce to better than 0.1%: reg_flow does
(12.97 vs the recorded 12.98 GiB), reg_field does not (8.09 vs a recorded
8.93). Recorded rather than silently overwritten.

What the stated preference costs — plainly

The decision on #94 is to keep 32-bit dispatch, with a per-backend option
because "it's probably more important on CUDA than on CPU". The
register-pressure instinct is very likely right. The consequence is worth
seeing in one place, without argument:

• CUDA is the backend whose build budget is exhausted.reg_flow peaks at
  12.97 GiB of a 16 GB runner; build-cuda gates at FF_MEM_BUDGET_KB = 14 GiB
  (ci(cuda): gate nvcc peak memory on a budget, and record why -j2 is not headroom #95); under -j2reg_field + reg_flow peaks sum to over the limit and
  the build is green only because the two spikes have not yet coincided.
• CPU is the backend with room to spare, 64-bit integer units, and no
  register file to protect.
• So keeping the axis on CUDA and dropping it on CPU relieves the backend that
  is not constrained and leaves the constrained one exactly where it is.
  After this PR the CUDA build still sits at ~13 GiB against a 16 GB runner,
  and anything that makes a regulariser heavier — -arch/-gencode flags,
  half/bf16, a new energy term — spends from that same ~1 GiB of margin.

That is not an argument against the decision. It is the reason the knob is
worth having: the position is now reversible by one make variable, and the
numbers for the other position are on the record instead of being guessed at.

The benchmark that would settle it — scoped, not run

The narrow path is an ATen inheritance and, as far as anyone can tell, has
never been benchmarked in this repository. There is no GPU in CI and no nvcc
on the machine this was prepared on, so it cannot be settled here. The spec is
#144: which ops, which shapes, which ncu metrics, and a decision rule
fixed in advance so the result is not re-litigated afterwards. An afternoon's
work once hardware exists.

One related cost, noted and not chased: on CUDA the narrow path is paid for
with a cudaMallocHost + cudaFreeHost per array per call
(core/autocast.h), justified in that header as enabling an async H2D copy —
but 363 of the 391 upload sites under include/fastfields/impl/cuda/ call
the synchronouscopyToDevice (only distance_{euclidean,l1,mesh}.h use
copyToDeviceAsync), so for almost every op there is no async copy for the
pinning to enable. If that cost is real it comes off whatever the register win
is worth, worst exactly where the kernel is cheapest. #144 says to measure it
alongside and report it separately.

Cost of this PR

The build-cuda matrix roughly doubles that job's runner-minutes on
CUDA-triggering changes — but the second leg is the cheaper one (~19 min of the
~57 total), the two run in parallel so wall clock is unchanged, and it is the
only thing that makes the off position a supported configuration rather than an
untested claim.

lint (clang-format, changed lines) is red; it is continue-on-error and
cannot report its own findings (#89), and the source diff here is a
same-width token swap that moves no formatting.