This is a great writeup, thanks!
To test the code with and without naked pointers, I had to switch between OCaml 4.14 and OCaml 5.
This should not be necessary. Recent versions of OCaml 4 offer a “naked pointer checker” that will create alarms if it finds naked pointers, which I think suffices to port programs to the no-naked-pointer mode without using OCaml 5. (So: the program should behave as standard OCaml 4 releases that allow naked pointers, but print warning messages when it actually encounters them at runtime.)
The naked pointer checker (nnpchecker) was introduced in [ANN] A dynamic checker for detecting naked pointers , and can be configure in OCaml 4.12 or later 4.x releases by selecting the opam compiler option ocaml-option-nnpchecker.
Maintaining the bindings require an understanding of the OCaml runtime to a level that currently isn’t reflected in documentation, but instead relies on institutional knowledge imparted by past contributors.
Idle question: have you considered reverting to the “naive” approach that follows the manual guidelines to the letter, adding more macros in case where they might be deemed unnecessary with low-level reasoning? Is the worry that doing this would have a noticeable performance cost? This could make maintenance easier in the future by reducing the dependency on runtime knowledge.