modules: the protocol wrappers cross the boundary, via the purview

clang rejected the first attempt and was right:

    error: using declaration referring to 'wl_surface_attach' with internal
           linkage cannot be exported

wayland-scanner emits the protocol wrappers `static inline`, and C++ forbids
exporting an entity with internal linkage. GCC accepted it, which is why the
first green was meaningless — mcpp-index's llvm leg caught it.

Same-name forwarders in module purview do not work either (they clash with the
global-module declarations), and neither does giving them external linkage while
the originals are still visible. What does work is not declaring the originals
at all in this translation unit: the global module fragment includes only
wayland-<side>-core.h, and a copy of the generated protocol header with
`static inline` -> `inline` is included INSIDE the module purview. Every
declaration in it is inside `extern "C"`, so it keeps C language linkage, is
not attached to the module, and still matches wayland-protocol.c's definitions.

What still cannot cross is now exact rather than approximate: the `static
inline` helpers in the GMF headers themselves — wl_fixed_* (4) and wl_signal_*
(5). A consumer needing those includes the header next to the import, which the
README states.

Both toolchains build all four members, and CI re-runs the generator and diffs
so the wrappers cannot drift from the headers.

Author: speak-agent

.github/workflows/ci.yml

@@ -130,6 +130,18 @@ jobs:
           done
           echo "generated code matches wayland.xml and this scanner"
 
+      - name: the module wrappers match the generator
+        run: |
+          # The .cppm files and the -module.h copies are generated from the
+          # public headers. Checked in, so they can drift; this stops it.
+          python3 mcpp/tools/genmod.py .
+          if ! git diff --quiet; then
+            echo "::error::module wrappers are out of date — run mcpp/tools/genmod.py ."
+            git diff --stat
+            exit 1
+          fi
+          echo "module wrappers match"
+
       - name: every module produced an interface
         run: |
           for m in wayland.client wayland.server wayland.util; do

README.mcpp.md

@@ -25,6 +25,26 @@ code written against the C headers ports by swapping one line.
 The export lists are **generated from the public headers** rather than kept by
 hand, so a version bump cannot quietly drop a name.
 
+## What crosses the module boundary, and what does not
+
+`export` names entities, and it cannot name one with **internal linkage**. That
+rule decides the whole layout here:
+
+- **Types, `wl_proxy_*` / `wl_display_*` / `wl_resource_*`, the interface
+  objects, the enums** — external linkage, re-exported with `using ::name;`.
+- **The protocol wrappers** (`wl_surface_attach`, `wl_data_device_send_drop`, …)
+  — wayland-scanner emits them `static inline`. A copy of the generated header
+  with `static inline` changed to `inline` is included *inside the module
+  purview*, which gives them external linkage; everything in it sits inside
+  `extern "C"`, so it keeps C language linkage and still matches
+  `wayland-protocol.c`'s definitions. GCC accepts the naive `using ::name;`
+  here and clang rejects it — clang is right, and CI runs both.
+- **`wl_fixed_to_double` and friends, `wl_signal_*`** — `static inline` in
+  `wayland-util.h` / `wayland-server-core.h`, which the module includes in its
+  global module fragment. Those cannot be reached, so a consumer that needs them
+  includes the header next to the import. Four and five names respectively.
+- **Macros** — not entities at all; see below.
+
 ## Macros are the one thing that could not cross
 
 `export` names entities, and a macro is not one. Wayland's public surface has