refactor: spell the public interface <fastfields/...>

[balbasty]

Sweep 2 of two independent mechanical sweeps, deferred until the macro work (#90, #91) merged. The other one — header guards — is #145, deliberately kept separate.

What the tree looked like

Re-counted on 85fdac7 (the brief said 406; the merges since added some):

• 437 includes spell the public prefix as "fastfields/…"
• 0 use <fastfields/…>
• ~135 genuinely relative includes ("../utils.h", "flow/2d.h", "utils.h")
• 264 standard-library / third-party includes, all already <>

Carryover, not a decision: the consolidation script rewrote the path in every #include and left the delimiter, because that was the minimal textual change.

The convention

<fastfields/…> for the public interface, "…" for headers private to the component.

include/fastfields/ is the public installed interface — what gets copied to an install prefix, and what fastfields-dlpack puts on the compiler's include path via include_dirs. The ordinary convention spells a dependency found on the include path with <> and one found next to the includer with ""; this tree was writing both categories the same way.

The clearest evidence that the result reads wrong is downstream, in fastfields-dlpack/src/ext.cpp, which writes <nanobind/nanobind.h> and "fastfields/api/distance.h" ten lines apart — two spellings for the same category of dependency.

The ~135 relative includes are left exactly as they are. They are private to their component and correctly quoted already.

Why this changes nothing at compile time — verified, not asserted

"" searches the including file's own directory first and then falls back to exactly the <> search, so the two differ only when a quoted include is resolved by that first step.

make/common.mk has

INCLUDES += -I$(ROOTDIR)/include

and that is the entire include configuration: all four Makefiles compile with $(INCLUDES) and nothing else, and there is no -iquote anywhere in the tree (checked across make/, the four Makefiles and both workflows). So "" and <> share one search path here.

The script does not ask you to take that on trust — --check re-derives it from the sources. It verifies:

1. no fastfields/… include is still quoted;
2. every quoted include resolves beside its includer — so no quoted include was ever being resolved by the include path, which is exactly the property that makes the rewrite incapable of changing which file any include names;
3. no angle-bracket include of ours resolves beside its includer, i.e. nothing private has been promoted to the public spelling.

Invariants 2 and 3 already held on main before this commit. That is the mechanical safety argument, and it is re-checkable on every rebase rather than being a claim in a PR description.

Not touched

tools/consolidate.sh and tools/dedup-dispatch-helpers.py contain quoted-include literals — '#include "fastfields/api/checks.h"' and the consolidation's own rewrite rules. Those describe the tree at their own parent commit, and their documented contract is to be replayed against that parent, not against today's main. Rewriting the literals would break the replay, so they are deliberately left alone. Flagging it explicitly because a grep for the old spelling will still hit them.

core/dlpack.h is vendored and in the script's skip set (it includes nothing of ours in any case).

Reproducibility

tools/normalise-include-delimiters.py is committed, following tools/rename-macros.py and tools/dedup-dispatch-helpers.py, so a 147-file / 437-line rewrite can be replayed instead of read:

git checkout HEAD~1 -- include src tests
python3 tools/normalise-include-delimiters.py
git diff # empty

Verified. And:

$ python3 tools/normalise-include-delimiters.py --check
0 file(s) would change
every public include uses <fastfields/...> and every quoted include resolves beside its includer.

Not wired into CI, matching the precedent set by rename-macros.py — and because both of these sweeps would otherwise collide in ci.yml. One-line follow-up if you want it as a gate.

Validation

• tools/test-baseline.sh --tree . --legs all --check tools/test-baseline.expected — row-for-row match, 59,886 checks / 13 suites / 0 failures, unmoved. (Note: --legs default,lib cannot be --checked against the recorded file — the script compares whole reports and refuses a leg subset as "NOT COMPARABLE". The full-leg run is what is quoted here.)
• tools/rename-macros.py --check clean.
• make CXX=clang++ clean.
• CUDA is compile+link only, with no GPU in CI: build-cuda and compile-probe-cuda are the bar, and no runtime claim is made. This sweep touches src/lib-cuda/*.cpp and tests/impl-cuda/compile_probe_mesh.cu, so both legs need to be green.

Notes

• CLAUDE.md records the rule beside the FF_-prefix rule from refactor: prefix every remaining public macro with FF_ #91.
• Independent of refactor: #pragma once in every header #145 — they touch disjoint lines except in CLAUDE.md, where each adds one bullet; whichever lands second may need a one-line rebase there.
• Avoided make/, the per-library Makefiles and the dispatch layer (the per-backend 32-bit-offset work). This PR reads the include flags but changes no build file.
• Downstream, fastfields-dlpack/src/ext.cpp can follow suit whenever convenient — nothing here requires it to.

---

Generated by Claude Code