[teeny] Phase B3: pushpull pull/push/count/grad import via tny::from_dlpack

[balbasty]

Agent:claude-fastfields-to-teeny

Phase B3 of the tensor-native-boundaries umbrella (fastfields-lib#57) — the cpu-lib half.

This is one logical change split across two repos only because GitHub cannot span them: the impl half is fastfields/fastfields-cpu-impl#68, which converts the four entry points to take carriers. Neither PR compiles without the other — please review them together (same split convention as Phase A's cpu-impl#60 / cpu-lib#74).

Convention reference: fastfields-lib/TEENY-MIGRATION.md §9. Template: the merged Phase A distance.cpp shims (#74).

Closes#77

---

What changed

Each of the four exported entry points ran the explode-and-reassemble round trip — ContiguousStrides normalisation, VOIDPTR/CVOIDPTR byte-offset folds, 22 copy_if_needed calls across the leaf wrappers, and a use_32bits ternary in every dtype leaf — feeding impl signatures that immediately rebuilt the three carriers with as_anyrank. tny::from_dlpack does all three parts by construction, so the carrier is built once, in the existing dtype dispatch, and handed straight down:

template <int D, int O, bound_t B, typenamescalar_t>
inlinevoid_pull(DLTensor & out, const DLTensor & inp, const DLTensor & grid,
int extrapolate, bound_t bnd)
{
auto ao = tny::from_dlpack< scalar_t>(&out );
auto ai = tny::from_dlpack<constscalar_t>(&inp ); // R4 const-element carriersauto ag = tny::from_dlpack<constscalar_t>(&grid);
pushpull::pull<D, O, B, reduce_t>(ao, ai, ag, extrapolate, bnd);
}

• D1/R5: the use_32bits ? …int32_t… : …int64_t… ternaries collapse to int64 and CANUSE32BITS is deleted. Instantiation count halves, as expected — the full-matrix pushpull.o drops from 34.2 MB to 17.5 MB (clang -O2) and 57.4 MB to 30.4 MB (g++ -O2), and compiles 2.6–4.2× faster.
• Every copy_if_needed/free_if_needed/VOIDPTR/CVOIDPTR/ContiguousStrides use in this file is gone, and with them the file's #include "autocast.h" (nothing else in this TU used it — canUse32BitIndexMath lives in impl/kernels/utils.h, already included). autocast.h itself is untouched, per the last-user rule at the umbrella; other modules still use it.
• The shims stay rather than collapsing into the dispatch arms: the macro pyramid supplies D/O/B/ABS and scalar_t as explicit template arguments, and its shape and exact rejection messages are behavioural ABI. They are no longer void* re-casts — the import is their whole body.

---

Preserved behaviour — each item checked, not assumed

1. Exported signatures byte-for-byte unchanged.pushpull.h is untouched; the exported symbols are identical before and after (diff of the two symbol lists is empty):

_ZN2ff3cpu4pullER8DLTensorRKS1_S4_aaai _ZN2ff3cpu4pushER8DLTensorRKS1_S4_aaai
_ZN2ff3cpu5countER8DLTensorRKS1_aaai _ZN2ff3cpu4gradER8DLTensorRKS1_S4_aaabi

2. Every CHECK_* stays verbatim — message, argument order and evaluation order. Including:

• CHECK_RANK_FITS, which must keep rejecting a > TNY_MAX_RANK tensor with its std::invalid_argument in a release build (from_dlpack's own rank guard is a debug _TNY_CHECK, so removing this would have turned a clean throw into UB);
• CHECK_SAME_SPATIAL, the equality the per-tensor decode relies on — the impl trusts it, so it must keep throwing here (see the judgment-call section of the impl PR);
• the lanes, dtype-pair, rank and batch checks, all still evaluated before any import, so a rejection is still reached without ever building a carrier.

3. The dispatch pyramid and FF_TEST_SPARSE structure stay as-is (R1) — only the dtype leaf lost its offset-width ternary.

4. strides == NULL and byte_offset != 0 still work — and are now actually tested. They were handled by ContiguousStrides and VOIDPTR/CVOIDPTR, and no pushpull test exercised either one. Rather than delete the code that handled them and lose the coverage silently, test_pushpull gains test_descriptor_variants: six cases (NULL strides / non-zero byte_offset / both, × float and double) each running all four entry points and requiring the variant descriptor to reproduce the fully-explicit descriptor's answer element-for-element, plus a sentinel assertion that the padding in front of byte_offset is not written on any of the six buffers — so a mis-folded offset fails loudly instead of reading right and writing left. That is 1704 checks, 326 → 2030.

Crucially, those 1704 checks also pass against the pre-refactor code — verified by building the new test file against the old ContiguousStrides/VOIDPTR implementation, which gives the identical 2030 / 0. They pin existing behaviour; they do not encode the new implementation.

5. DLPack include order (R7).<teeny/dlpack.h> is included after this repo's vendored "dlpack.h", so the TU stays on fastfields' DLPack v1.2 throughout (teeny vendors v1.1; same include guard, first one wins). A comment records why the order matters.

---

The Phase B3 gate — all criteria, with evidence

Measured on one machine, clang++ 18.1.3 and g++ 13.3.0, -std=c++17 -DTNY_MAX_RANK=64, in the library configuration (full order × bound matrix, no -DFF_TEST_SPARSE).

Measurement hygiene. Sibling agents were concurrently editing the shared /home/user checkouts of these repos (Phase B2/posdef had already switched both onto its own branches with uncommitted edits). All measurements were therefore taken in dedicated git worktrees branched off origin/teeny, with the submodule symlink nesting rewired to the isolated copies.

1. Kernel instantiations byte-identical at -O2 (int64 arms) — ✅

vox::* are static inline and emit no standalone symbol on either compiler (fully inlined), so criterion 1 is measured on the kernel-layer helpers that do survive as symbols — _make_axis, _make_axis_g, _axes_from, _push_rec, _grad_rec, gather_sep, _sepgather — and the vox:: bodies fall to criterion 2. Comparison is relocation-aware (raw section bytes plus every relocation inside the symbol, normalised to offset/type/target).

build	common	differing bytes	differing relocs	resolve to same constant
clang++ -O2	225	0	16 500	16 500 / 16 500
clang++ -O3	210	0	16 514	16 514 / 16 514
g++ -O2	91	13 ¹	21 906	21 828 + 78 ²
g++ -O3	—	—	—	g++ inlines every kernel helper at -O3 in both objects

Baseline-only symbols are exactly the deleted int32 arms (R5); new-only symbols: 0. Differing relocations point into the merged constant pool or at clang's anonymous .LCPI#### labels, which shift because the TU holds half as many functions; each is resolved to the constant it names and compared — 100 % identical on clang.

¹ All 13 are _axes_from, each with identical byte size, identical instruction count and identical mnemonic multiset (register allocation / scheduling only — the accepted g++ whole-TU jitter, measured rather than asserted). ² Those 78 offset shifts are confined entirely to the same 13 symbols; across the 78 byte-identical g++ symbols, all 19 912 differing relocations resolve to the same constant, zero exceptions.

2. Driver loops: no new per-voxel instruction; the cur_b cache survives — ✅ (clang) / measured and explained (g++)

Loops are located structurally (backward branch → body [target, branch]) because the driver's mangled name deliberately changes; branch/call operands are blanked, every other operand compared literally.

build	baseline loop bodies (int64 arm)	after	verdict
clang++ -O2	1440 syms / 30 465	1440 / 30 465	IDENTICAL multiset
clang++ -O3	1440 syms / 34 788	1440 / 34 788	IDENTICAL multiset

The drivers can also be paired per instantiation — both manglings still carry (op, D, O, bound, ABS, dtype):

build	paired	byte-identical	same count+opcode mix	new LARGER	new SMALLER
clang++ -O2	1440	1440 (100 %)	0	0	0
clang++ -O3	1440	1440 (100 %)	0	0	0
g++ -O2	1236	551	27	5	653
g++ -O3	1396	—	—	20	—

On clang the entire driver — per-voxel loops, inlined kernel and all — is byte-for-byte unchanged at both optimisation levels, which is the compiler-independent statement that this source change is codegen-neutral.

g++, stated plainly. g++ re-inlines a TU that just halved and does not reproduce byte identity. Net it emits less code (at -O2: 35 783 fewer instructions, 790 fewer integer divisions across the paired set), but a minority grow and I am not rounding that away: 5/1236 at -O2 (+120/+116/+46/+7/+4, extra opcodes almost entirely mov spills and NOP padding) and 20/1396 at -O3 (max +45, mov/lea/add/sub/NOPs). 17 of 1396 instantiations at g++ -O3 gained exactly one in-loop integer division — the one item I could not make identical. It is not the failure this criterion guards against: had the cur_b cache stopped eliding the per-voxel peel_front_at<-(D+1)>, every instantiation would have gained a whole mixed-radix batch decode (a per-axis loop with a division per axis), not one division in 1.2 % of them — and at -O2 the same measurement moves the other way. See the impl PR for the full reasoning.

Harness validated in both directions (self-comparison 16 409/16 409 identical; -O2 vs -O3 negative control correctly reports differences), and three independent implementations of the loop comparison agree exactly on the clang -O2 figure.

3. Oracle: test_pushpull unchanged at 326 with the original test file — ✅

326 / 0 at baseline on both compilers; still exactly 326 / 0 after the refactor with the original test file. The committed suite adds the 1704 descriptor-variant checks → 2030 / 0 on both compilers, and those also pass against the pre-refactor code.

Every run had a verifiedmake clean (cpu-lib#56's trap): post-clean counts recorded each time, all four lib-objects/libs/deps=0 test-objects/deps=0 test-binaries=0.

4. ASan + UBSan — ✅

-fsanitize=address,undefined, detect_leaks=1, halt_on_error=1, print_stacktrace=1: 2030 checks, 0 failures, 0 sanitizer reports, exit 0 (g++; this box has no clang libclang_rt.asan, as in Phase A).

5. Whole suite green, unchanged counts on every other module — ✅

All 12 binaries, both compilers, verified clean between. diff of the baseline vs post-change listing gives exactly one differing line per compiler — test_pushpull — and the clang and g++ listings are identical to each other.

binary	baseline	after
test_distance	3067	3067
test_distance_mesh	4622	4622
test_distance_spline	704	704
test_posdef	5092	5092
test_pushpull	326	2030
test_reg_dispatch	6030	6030
test_reg_field	525	525
test_reg_flow	1123	1123
test_reg_op	186	186
test_resize	4130	4130
test_restrict	191	191
test_splinc	4577	4577
total	30 573	32 277

---

Judgment calls

The int32 arm is deleted outright, not kept behind a flag. That is D1/R5, and the check counts confirm it is behaviour-neutral: the test_inflated_stride case (an inp batch stride ≥ INT32_MAX, which used to force the int64 arm) and every small-tensor case now both run the int64 instantiation, with identical results.

A new (benign) failure mode, same as Phase A.from_dlpack debug-asserts that the tensor's device_type matches the carrier's memory space, so a kDLCUDA tensor handed to ff::cpu::pull now trips that assert in a non-NDEBUG build where previously it would have dereferenced a device pointer on the host. Strictly an improvement, and unreachable in practice (fastfields-lib dispatches on device before reaching ff::cpu), but it is a behaviour change.

The spatial-extent equality stays enforced only here. The impl trusts CHECK_SAME_SPATIAL rather than re-asserting it; the reasoning is in the impl PR's judgment-call section.

[balbasty]

Merged as 77f9a21 (impl half: cpu-impl#68, 3f90eb6).

Independently reviewed with a from-scratch toolchain (custom ELF64 reader, relocation-aware disassembly diff, canonical driver-name pairing across 5,760 symbols per build) — full report on the impl PR's thread. Summary: approved, clang side byte-for-byte identical across the entire driver+kernel set at both -O2/-O3 (5,760/5,760), g++ side explained mechanically rather than statistically (the flagged 17-division delta at -O3 is one peel_front_at cell-builder callee migrating from out-of-line to inlined per case, not new work — traced via call-relocation count 4→3 on all 17). Oracle, ASan/UBSan (on both compilers, including clang — the review's box had a working clang ASan runtime the implementer's didn't), and whole-suite counts all independently reproduced exact.

One mechanical note for the record: this branch predated Phase B1 (#79) and Phase B2 (#80) merging into teeny, so the merge required reconciling the impl submodule pin (both sides had moved it) — resolved by merging origin/teeny in and keeping this PR's pin (3f90eb6), confirmed to have both B1's and B2's cpu-impl SHAs as ancestors. Full suite re-verified green post-merge (test_pushpull at 2030 as expected) before squashing.

Closing #77.

---

Generated by Claude Code