docs/20: whether the island header is required, and what omitting it costs

Not required by the language: the seam can declare the entry point and the
island can define it, with no header, and that builds and runs. What the header
buys is that the declaration exists once.

Stated because the failure it prevents is the worst one available here. C
language linkage does not mangle, so two copies that disagree are one symbol:
the link is clean and each side reads the arguments by its own ABI. The property
that forces this boundary to be extern "C" is the same property that makes a
split declaration undetectable, and the three alternatives that would remove the
header are listed with why none does.

Both languages.

Author: speak-agent

docs/20-heterogeneous-builds.md

@@ -147,6 +147,39 @@ links libstdc++ puts a second copy of the C++ runtime into a program whose own
 copy came from mcpp's toolchain.
 
 
+#### Is the `extern "C"` header required?
+
+Not by the language. The seam can declare the entry point itself and the island
+can define it, with no header anywhere, and that builds and links and runs.
+
+What the header buys is that the declaration exists **once**. Without it there
+are two copies in two compilers, and they can disagree silently:
+
+```cpp
+// the seam
+extern "C" int saxpy_device(float a, const float* x, const float* y,
+                            float* out, unsigned n);
+// the island, after someone widened the count
+extern "C" int saxpy_device(float a, const float* x, const float* y,
+                            float* out, std::size_t n);
+```
+
+C language linkage does not mangle, so those are one symbol. The link is clean
+and each side reads the arguments by its own ABI: no compile error, no link
+error, and a run that reads past the end of the arguments. The same mistake
+across a C++ boundary is caught by mangling at link time.
+
+So the property that forces this boundary to be `extern "C"` -- the two sides do
+not share a C++ ABI -- is the same property that makes a split declaration
+undetectable. The header is the smallest artefact both a module and a device
+compiler can read, which is the whole of its reason for existing.
+
+Three alternatives were considered and none removes it: the island cannot
+include the seam (a `.cppm` is not something nvcc parses), generating the header
+from some single source is a header with an extra step, and a module's global
+module fragment exports nothing the island could reach even if its compiler
+could read a BMI.
+
 ### Two kinds of lane, and only one of them has a generated interface
 
 The seam above is written by hand, and the shader lane's equivalent is

docs/zh/20-heterogeneous-builds.md

@@ -118,6 +118,35 @@ tarball 已经发出去了。设备源文件必须被显式点名。
 自身运行时来自 mcpp 工具链的程序里。
 
 
+#### 那个 `extern "C"` 头文件是必须的吗?
+
+语言上不是。接缝可以自己声明入口点、岛自己定义它,一个头文件都不写,照样编得过、链得上、
+跑得起来。
+
+头文件买来的是**那份声明只有一份**。没有它就有两份副本分属两个编译器,而它们可以静默地
+不一致:
+
+```cpp
+// 接缝里
+extern "C" int saxpy_device(float a, const float* x, const float* y,
+                            float* out, unsigned n);
+// 岛里,在有人把计数加宽之后
+extern "C" int saxpy_device(float a, const float* x, const float* y,
+                            float* out, std::size_t n);
+```
+
+C 语言链接不做名字修饰,所以这两个是同一个符号。链接是干净的,而两侧各按自己的 ABI 解释
+参数:没有编译错误,没有链接错误,只有一次读过了参数末尾的运行。同样的错误发生在 C++
+边界上会被名字修饰在链接期挡下。
+
+所以**迫使这条边界必须是 `extern "C"` 的那条性质 —— 两侧不共享 C++ ABI —— 正是让声明
+分裂无法被发现的同一条性质**。一个普通头文件是模块和设备编译器都能读的最小共同物,这就
+是它存在的全部理由。
+
+三条替代都试过,没有一条能去掉它:岛不能包含接缝(`.cppm` 不是 nvcc 解析的东西);从某个
+单一来源生成头文件就是头文件多加一步;而模块的 global module fragment 什么都不导出,即使
+岛的编译器能读 BMI 也够不到。
+
 ### 两类 lane,只有一类的接口是生成的
 
 上面那个接缝是手写的,而 shader 那条 lane 的对应物是生成的。这不是不一致 ——