0.25.2: the suite keeps the surface under a discarding link; the tests in mtest's layout (unit, e2e, cts, bench)

.agents/docs/2026-11-15-tests-in-mtest-layout-design.md

@@ -0,0 +1,34 @@
+# 规范仓库的测试：mtest 标准布局（0.25.2，负责人 2026-11-15 确认）
+
+## 结论
+
+| 目录 | 类型 | 内容 |
+|---|---|---|
+| `tests/unit/` | UTest | 版本：`KAL_VERSION_*` 由编译器读取，与清单版本一致 |
+| `tests/e2e/headers.cpp` | E2E | 宏的模块拼写、C 形式在 `-nostdinc` 下编译（cc、clang）、无后端类型及其反证 |
+| `tests/e2e/abi.cpp` | E2E | 冻结布局在 riscv32 与 riscv64 上编译（`tests/e2e/data/abi`） |
+| `tests/e2e/substitution.cpp` | E2E | 一份源码对两个实现、表面检查拒绝新增名字、接口列表取自产物 |
+| `tests/cts/` | CTS、Bench | 一致性套件（原 `conformance/`），独立成员包 |
+| `kit/tests/` | UTest | openkal-kit 的用例，随包走 |
+
+## 约束与取舍
+
+- **cts 不使用 mtest 的 C++ 库。** 库依赖 `import std`，而套件要在没有 C 库的实现上运行（固件、裸机、DOS）。
+  套件自己实现协议（L2：cts 用例、bench 用例、选择、列出）。bench 留在套件内，与各节共享状态，所有平台都有成本数据。
+- **检查用 C++ 驱动工具。** `tools/` 下的脚本同时供实现仓库使用，保持不变。用例在自己的临时目录里操作副本
+  （头文件副本、示例副本、生成到临时文件的 `macros.cppm`），不写检出目录，因此无需串行。
+  缺少的编译器作为能力（capability）声明，相应用例跳过并给出原因。
+- **CI 收敛。** `tests` 作业在 Linux（gcc、llvm）与 macOS（llvm）上执行 `mtest run --set full`；
+  `declarations` 作业在五行上只构建模块形式。这些用例的对象是文本、头文件和工具，与消费者使用的工具链无关，
+  所以不必在每一行上运行。
+- **兼容。** `tools/run-conformance.sh` 的参数不变，实现仓库的调用方式不变。套件的存储变为
+  `tests/cts/.mtest`；读取该存储的实现仓库 CI（linux、macos、windows、posix、emscripten）和 freebsd 的
+  独立运行脚本在本版合入后同步路径。
+
+## 生态侧发现
+
+- mcpp：默认的 `tests/**/*.cpp` 会把成员包 `tests/cts/src/*.cpp` 当作根包测试。mcpp 2026.11.14.1 规定，
+  包根之下含 `mcpp.toml` 的目录是另一个包，不参与发现。本仓库显式声明 `[test] discover = ["tests/*/*.cpp"]`，
+  不依赖该版本。CI 的 mcpp 固定为 2026.11.14.1。
+- mtest 0.8.5：库在 macOS 的 LLVM 20 libc++（`import std`）下无法编译（`lib/src/mtest.cpp` 中
+  `directory_iterator` 的比较未经 std 模块导出）。`tests` 作业的 macOS 行因此使用 LLVM 22。

README.md

@@ -64,7 +64,7 @@ words become types that cannot be mixed.
 | --- | --- |
 | `tools/check-declarations.sh` | compiles a translation unit naming every entity, with `-nostdinc` — because the consumer the header exists for is compiled that way |
 | a test in each implementation | the same list, reached through `import openkal.*` |
-| `conformance/src/declarations.c` | the same list again, compiled by every toolchain that builds the suite |
+| `tests/cts/src/declarations.c` | the same list again, compiled by every toolchain that builds the suite |
 
 The header includes nothing. openkal must be usable on a freestanding target,
 and a consumer compiled with `-nostdinc` has nothing to include.
@@ -88,6 +88,15 @@ observed (entry 60). The conformance suite reports to a test runner by the mtest
 protocol, and checks that an implementation's manifest, `kal_interfaces()` and its
 exported names state the same interfaces.
 
+0.25.2 changes no clause. The suite reaches every name of the surface without
+requiring it, so a link that discards unreached definitions keeps the surface
+it compares (entry 63), and reports each interface's measured cost as a `bench`
+case beside its `cts` case. The tests of this repository are written with mtest
+0.8.5 in its layout (`mtest.toml`): `tests/unit` and `tests/e2e` hold the
+version, the headers through the tools, the 32-bit layout and substitution
+(`mtest run --set checks`, `--set substitution`), `tests/cts` is the suite, and
+openkal-kit's tests use the mtest library; each CI run reports them together.
+
 ## How a program uses openkal
 
 A program declares two dependencies. The first fixes the version of the contract
@@ -96,7 +105,7 @@ conditional on the target.
 
 ```toml
 [dependencies]
-openkal = "0.25.1"
+openkal = "0.25.2"
 
 [target.'cfg(os = "linux")'.dependencies]
 openkal-linux = "0.26.1"
@@ -235,7 +244,7 @@ clause 6.2 tabulates, and the earliest at which the question can be answered —
 source that asks the same question with `#ifdef` asks it during preprocessing,
 which is earlier than any answer exists.
 
-**The behaviour.** [`conformance/`](conformance/) is a program an implementation
+**The behaviour.** [`tests/cts/`](tests/cts/) is a program an implementation
 runs against itself — 193 observations across fifteen interfaces, in four kinds:
 behaviour, ABI, stability and cost.
 

SPEC.md

@@ -1,4 +1,4 @@
-# openkal Specification, version 0.25.1
+# openkal Specification, version 0.25.2
 
 ## 1. Scope
 
@@ -2224,6 +2224,13 @@ The following are recorded so that they are not mistaken for oversights.
     what an image of such an architecture is, were not written down. No
     declaration changes.
 
+63. **The surface the conformance suite links.** **Changed in 0.25.2**; no
+    clause and no declaration changes. A link that discards definitions nothing
+    reaches kept of an implementation only what the suite calls, and the
+    comparison of clause 9 then reported an interface absent whose definitions
+    the implementation holds. The suite now reaches every name without
+    requiring it, so a defined name is kept and an absent one is null.
+
 ## 12. Images
 
 A program written against this specification is built for an environment: its

examples/portable/mcpp.toml

@@ -9,7 +9,7 @@ name    = "portable"
 version = "0.1.0"
 
 [dependencies]
-openkal = "0.25.1"
+openkal = "0.25.2"
 
 # AND THE VERSIONS HAVE TO FOLLOW THE SOURCE, which is the reason this example
 # is a criterion rather than an assumption.

include/openkal/version.h

@@ -43,7 +43,7 @@
  * consumer actually asks for was checked by nobody. */
 #define KAL_VERSION_MAJOR 0u
 #define KAL_VERSION_MINOR 25u
-#define KAL_VERSION_PATCH 1u
+#define KAL_VERSION_PATCH 2u
 
 #define KAL_VERSION_MAKE(major, minor, patch)             \
     (((kal_u64)(major) << 32) | ((kal_u64)(minor) << 16) | \

kit/mcpp.toml

@@ -97,5 +97,10 @@ openkal = "0.25.0"
 # tools/run-conformance.sh already does for the conformance suite --- and for the
 # same reason: a change spanning the specification and an implementation must be
 # tested against both halves as written, not against whichever half is published.
+# The tests are written with mtest, so that a runner lists, selects and
+# reports each observation as a case.
+[dev-dependencies]
+mcpplibs.mtest = "0.8.5"
+
 [target.'cfg(os = "linux")'.dev-dependencies]
-openkal-linux = { version = "0.26.0", features = ["standalone"] }
+openkal-linux = { version = "0.26.0" }