2026.11.8.1: mtest's test protocol in mcpp test, tests without main, one std module builder per entry, lock targets per plan, identity-key manifests

.agents/docs/README.md

@@ -18,7 +18,7 @@ superseded_by: 2026-09-07-....md  # when status is superseded
 ---
 ```
 
-353 records.
+355 records.
 
 ## By subject
 
@@ -75,6 +75,8 @@ Records that declare one. Everything else is listed by date below.
 
 ### ecosystem
 
+- [生态顶层方案：#885 收尾之后的工作流、原则与依赖](2026-11-08-ecosystem-top-level-design.md) — active
+- [#885 收尾补充方案：目标角色、平台事实、系统接口与版本书写](2026-11-08-ecosystem-885-supplement-design.md) — active
 - [生态 #885 收尾设计：核心、插件、openkal、语言服务与编辑器的一轮闭合](2026-11-07-ecosystem-885-closeout-design.md) — active
 - [生态设计 part 2：openkal 的最小原子与二进制映像、其上的 `mcpplibs.os`，以及 part 1 的收尾与回归记录](2026-10-26-ecosystem-part2-os-library-over-openkal-design.md) — active
 - [控制契约、并发与性能、单一 C++ 运行时，以及 IDE 生态（生态级，#838、#839）](2026-10-26-control-contract-runtime-and-ide-ecosystem-design.md) — active
@@ -177,6 +179,8 @@ Records that declare one. Everything else is listed by date below.
 
 ### 2026-11
 
+- [生态顶层方案：#885 收尾之后的工作流、原则与依赖](2026-11-08-ecosystem-top-level-design.md) — active
+- [#885 收尾补充方案：目标角色、平台事实、系统接口与版本书写](2026-11-08-ecosystem-885-supplement-design.md) — active
 - [生态 #885 收尾设计：核心、插件、openkal、语言服务与编辑器的一轮闭合](2026-11-07-ecosystem-885-closeout-design.md) — active
 - [Launch configuration and named test runners](2026-11-06-launch-configuration-and-named-test-runners.md) — active
 - [Compiler attempt lifetime and output recovery](2026-11-06-compiler-attempt-recovery.md) — active

.github/actions/e2e-mtest/action.yml

@@ -0,0 +1,92 @@
+name: e2e-mtest
+description: >
+  mtest for the e2e suite (design 2026-11-08 W8; tests/e2e/mtest.toml): the
+  release this action pins, its sha256 checked, and the stores main's last
+  successful CI run kept for this host, taken into tests/e2e/.mtest so that
+  `--shard` divides the suite by measured time and a run orders its tests
+  longest first. Exports E2E_MTEST for run_all.sh. A run with no store of main
+  divides by count, and its own store becomes the next run's history.
+
+inputs:
+  host:
+    description: the host's name in the stores' artifact names (linux, macos, windows)
+    required: true
+  version:
+    description: the mtest release
+    required: false
+    default: '0.4.0'
+  sha256:
+    description: sha256 of mtest-<version>-openkal-bundle-all.tar.gz
+    required: false
+    default: 'b62e4ac7cd76b20dbdc48a5d041d377444e8815ee7a4ff1e7686145d13acc925'
+  token:
+    description: a token that reads this repository's actions
+    required: false
+    default: ${{ github.token }}
+
+runs:
+  using: composite
+  steps:
+    - name: mtest
+      shell: bash
+      env:
+        MTEST_VERSION: ${{ inputs.version }}
+        MTEST_SHA256: ${{ inputs.sha256 }}
+      run: |
+        set -euo pipefail
+        archive="mtest-$MTEST_VERSION-openkal-bundle-all.tar.gz"
+        temp="$RUNNER_TEMP"; python=python3
+        if [ "$RUNNER_OS" = Windows ]; then temp=$(cygpath -u "$RUNNER_TEMP"); python=python; fi
+        curl -fsSL --retry 5 --retry-all-errors --retry-delay 5 -o "$temp/$archive" \
+          "https://github.com/mcpp-community/mtest/releases/download/v$MTEST_VERSION/$archive"
+        actual=$("$python" -c "import hashlib,sys; print(hashlib.sha256(open(sys.argv[1],'rb').read()).hexdigest())" "$temp/$archive")
+        [ "$actual" = "$MTEST_SHA256" ] || { echo "::error::$archive: sha256 $actual, the action pins $MTEST_SHA256"; exit 1; }
+        mkdir -p "$temp/mtest" && tar xzf "$temp/$archive" -C "$temp/mtest"
+        launcher="$temp/mtest/mtest-$MTEST_VERSION-openkal-bundle-all/bin/mtest"
+        [ "$RUNNER_OS" = Windows ] && launcher="$launcher.exe"
+        "$launcher" --version
+        echo "E2E_MTEST=$launcher" >> "$GITHUB_ENV"
+    # The pull request's change, for the `pr` set: the base's tip and HEAD's
+    # parents, so that `git diff <base>...HEAD` has its merge base. When they
+    # cannot be fetched, mtest selects every test and says why.
+    - name: The base of the change
+      if: github.base_ref != ''
+      shell: bash
+      run: |
+        git fetch --no-tags --depth=1 origin "+refs/heads/${{ github.base_ref }}:refs/remotes/origin/${{ github.base_ref }}" || true
+        git fetch --no-tags --deepen=1 origin || true
+    - name: The stores of main's last CI run
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        HOST: ${{ inputs.host }}
+      run: |
+        set -euo pipefail
+        run=$(gh run list -R "$GITHUB_REPOSITORY" --workflow ci.yml --branch main --status success --limit 1 \
+                --json databaseId -q '.[0].databaseId' 2>/dev/null || true)
+        if [ -z "$run" ]; then echo "no successful run of main: the suite is divided by count"; exit 0; fi
+        rm -rf "$RUNNER_TEMP/e2e-stores"
+        if ! gh run download "$run" -R "$GITHUB_REPOSITORY" -p "e2e-store-$HOST-*" -D "$RUNNER_TEMP/e2e-stores" 2>/dev/null; then
+          echo "main's run $run kept no store for $HOST: the suite is divided by count"; exit 0
+        fi
+        for store in "$RUNNER_TEMP"/e2e-stores/*/; do
+          (cd tests/e2e && "$E2E_MTEST" store import --from "$store")
+        done
+        echo "history of main's run $run: $(ls "$RUNNER_TEMP/e2e-stores" | wc -l) store(s)"
+    # The coverage map of the last nightly measurement (e2e-coverage.yml), on
+    # the host it was measured on: the sources each test's run executed there.
+    # Another host's own sources (src/native/windows/...) run on no Linux test,
+    # so its suite has no map and every test of it is affected.
+    - name: The coverage map
+      if: inputs.host == 'linux'
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+      run: |
+        set -euo pipefail
+        run=$(gh run list -R "$GITHUB_REPOSITORY" --workflow e2e-coverage.yml --status success --limit 1 \
+                --json databaseId -q '.[0].databaseId' 2>/dev/null || true)
+        if [ -z "$run" ]; then echo "no coverage map: every test is affected"; exit 0; fi
+        rm -rf "$RUNNER_TEMP/e2e-coverage"
+        gh run download "$run" -R "$GITHUB_REPOSITORY" -n e2e-coverage-linux -D "$RUNNER_TEMP/e2e-coverage" || exit 0
+        (cd tests/e2e && "$E2E_MTEST" coverage import --from "$RUNNER_TEMP/e2e-coverage/coverage.json")

.github/tools/check_e2e_coverage.py

@@ -30,9 +30,15 @@
 An exception for a test that ran, or for a test that does not exist, also fails
 the check, so that the list cannot outlive the reason it records.
 
+Some claims need a test to pass on particular hosts, not on some host: docs/21
+calls a target row `verified` when CI builds and runs its artefact, and the
+`*-openkal` rows claim that for every system. tests/e2e/host-requirements.tsv
+lists such a test with the hosts its result must come from; a listed test that
+did not pass on one of them, or that does not exist, fails the check.
+
 With --timings-out DIR it writes `<host>.tsv`, the measured duration of every
 test that ran, merged across that host's shards, in the format run_all.sh reads
-from E2E_TIMINGS; refreshing tests/e2e/timings/ is copying those files. A report
+from E2E_TIMINGS (a run without mtest; CI's shards divide by mtest's history). A report
 file is named `e2e-report-<host>-<shard>.tsv`.
 
 Usage:
@@ -64,6 +70,19 @@ def read_reports(directory: Path):
             yield m["host"], int(m["shard"]), parts[0], parts[1], ms, parts[3] if len(parts) > 3 else ""
 
 
+def read_host_requirements(path: Path) -> dict[str, set[str]]:
+    """`<test>\t<host> <host> ...\t<reason>` lines: the hosts a test must pass on."""
+    out: dict[str, set[str]] = {}
+    if not path.exists():
+        return out
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if not line.strip() or line.startswith("#"):
+            continue
+        parts = line.split("\t")
+        out[parts[0].strip()] = set(parts[1].split()) if len(parts) > 1 else set()
+    return out
+
+
 def read_exceptions(path: Path) -> dict[str, str]:
     out: dict[str, str] = {}
     if not path.exists():
@@ -109,8 +128,10 @@ def main() -> int:
     workflows = workflow_tokens([p.read_text(encoding="utf-8")
                                  for p in sorted((root / ".github" / "workflows").glob("*.yml"))])
     exceptions = read_exceptions(root / "tests" / "e2e" / "coverage-exceptions.tsv")
+    required = read_host_requirements(root / "tests" / "e2e" / "host-requirements.tsv")
 
     ran: dict[str, set[str]] = defaultdict(set)
+    passed: dict[str, set[str]] = defaultdict(set)
     skipped: dict[str, set[str]] = defaultdict(set)
     shard_ms: dict[tuple[str, int], int] = defaultdict(int)
     timings: dict[str, dict[str, int]] = defaultdict(dict)
@@ -119,6 +140,8 @@ def main() -> int:
         reports += 1
         if status in RAN:
             ran[test].add(host)
+            if status == "pass":
+                passed[test].add(host)
             shard_ms[(host, shard)] += ms
             timings[host][test] = ms
         elif status == "skip":
@@ -143,6 +166,15 @@ def main() -> int:
     for test in exceptions:
         if test not in tests:
             stale.append(f"{test} is excused but does not exist")
+    unmet = []
+    for test, hosts in sorted(required.items()):
+        if test not in tests:
+            stale.append(f"{test} is required on hosts but does not exist")
+            continue
+        for host in sorted(hosts - passed[test]):
+            why = [d for d in skipped[test] if d.startswith(f"{host}: ")]
+            unmet.append(f"{test} did not pass on {host}"
+                         f"{' (' + '; '.join(why) + ')' if why else (' (it ran and did not pass)' if host in ran[test] else ' (no report of it there)')}")
 
     print(f"{len(tests)} tests: {counts['ran']} ran on a shard, {counts['job']} run by a "
           f"dedicated job, {counts['excused']} excused, {len(uncovered)} uncovered")
@@ -152,14 +184,16 @@ def main() -> int:
         print(f"UNCOVERED: {line}")
     for line in stale:
         print(f"STALE EXCEPTION: {line}")
+    for line in unmet:
+        print(f"REQUIRED ON HOST: {line}")
 
     if args.timings_out:
         out = Path(args.timings_out)
         out.mkdir(parents=True, exist_ok=True)
         for host, table in timings.items():
             (out / f"{host}.tsv").write_text(
                 "".join(f"{t}\t{ms}\n" for t, ms in sorted(table.items())), encoding="utf-8")
-    return 1 if uncovered or stale else 0
+    return 1 if uncovered or stale or unmet else 0
 
 
 if __name__ == "__main__":

.github/tools/check_include_regions.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
-# check_include_regions.sh — headers are included only where a system has no
-# module for what is needed (design 2026-11-07 D10).
+# check_include_regions.sh — headers are included, and the preprocessor
+# chooses, only where a system has no module for what is needed (design
+# 2026-11-07 D10; design 2026-11-08 S4).
 #
 # mcpp imports the standard library (`import std`), its dependencies as modules
 # (nlohmann.json, mcpplibs.os, the mwrap wrappers of zlib, zstd, xz and of the
@@ -10,6 +11,11 @@
 # directive anywhere else is a header a module should provide: depend on the
 # package that wraps it, or wrap it (mcpp-index docs/mwrap.md).
 #
+# The same holds for a conditional directive (`#if`, `#ifdef`, `#ifndef`,
+# `#elif`) and a macro definition (`#define`): a platform is chosen by
+# `if constexpr` over mcpplibs.os and by the per-system sources of mcpp.toml,
+# never by the preprocessor.
+#
 # Text that only looks like a directive is not one: a raw string (the source
 # mcpp writes for a launcher or a template) and a comment are skipped. Tests
 # (`tests/`, a module's `tests/`) are outside the rule.
@@ -20,10 +26,11 @@ import re, sys
 from pathlib import Path
 
 ALLOWED = {Path("src/native/posix/lock.cpp"), Path("src/native/windows/lock.cpp")}
+DIRECTIVE = re.compile(r'#\s*(include|if|ifdef|ifndef|elif|elifdef|elifndef|define)\b')
 RAW = re.compile(r'(?:u8|u|U|L)?R"([^()\\ ]{0,16})\(')
 
 def directives(text):
-    """Line numbers of `#include` directives outside comments and raw strings."""
+    """(line, directive) of each preprocessor directive outside comments and raw strings."""
     out, i, n, line = [], 0, len(text), 1
     at_line_start = True
     while i < n:
@@ -45,7 +52,8 @@ def directives(text):
                 j += 2 if text[j] == '\\' else 1
             i = j + 1; at_line_start = False; continue
         if at_line_start and c == '#':
-            if re.match(r'#\s*include\b', text[i:]): out.append(line)
+            d = DIRECTIVE.match(text, i)
+            if d: out.append((line, d.group(1)))
         if not c.isspace(): at_line_start = False
         i += 1
     return out
@@ -54,8 +62,9 @@ bad = 0
 for path in sorted(list(Path("src").rglob("*.cpp*")) + list(Path("modules").rglob("*.cpp*"))):
     if "tests" in path.parts or "test" in path.parts or path in ALLOWED:
         continue
-    for line in directives(path.read_text(encoding="utf-8", errors="replace")):
-        print(f"{path}:{line}: #include outside the system lock files; import a module instead")
+    for line, d in directives(path.read_text(encoding="utf-8", errors="replace")):
+        hint = "import a module instead" if d == "include" else "choose with if constexpr or a per-system source"
+        print(f"{path}:{line}: #{d} outside the system lock files; {hint}")
         bad += 1
 for path in ALLOWED:
     if not path.exists():

.github/tools/check_modules_wiring.sh

@@ -10,7 +10,8 @@
 # when they are forgotten:
 #
 #   1. modules/<x>/mcpp.toml          the package itself
-#   2. mcpp.toml [dependencies.mcpp]  what makes it importable
+#   2. mcpp.toml [dependencies]       `mcpp.<x> = { path = "modules/<x>" }`,
+#                                     what makes it importable
 #   3. mcpp.toml [workspace] members  what makes `-p` and `mcpp test` see it
 #   4. the two xmake source lists     the bootstrap and the benchmark, which
 #                                     have no package manager and compile the
@@ -62,8 +63,9 @@ for d in "${dirs[@]}"; do
         || bad "$d/mcpp.toml has namespace = \"${ns:-<none>}\"; modules of this project use \"mcpp\" so they do not squat bare registry names"
 
     # (2) importable
-    grep -qE "^[[:space:]]*$name[[:space:]]*=[[:space:]]*\{[[:space:]]*path[[:space:]]*=[[:space:]]*\"modules/$name\"" mcpp.toml \
-        || bad "mcpp.toml [dependencies.mcpp] has no entry for '$name' — it will not be importable"
+    grep -qE "^[[:space:]]*mcpp\.$name[[:space:]]*=[[:space:]]*\{[[:space:]]*path[[:space:]]*=[[:space:]]*\"modules/$name\"" \
+            <(sed -n '/^\[dependencies\]/,/^\[/p' mcpp.toml) \
+        || bad "mcpp.toml [dependencies] has no 'mcpp.$name = { path = \"modules/$name\" }' — it will not be importable"
 
     # (3) addressable
     grep -qF "\"modules/$name\"" <(sed -n '/^\[workspace\]/,/^\[/p' mcpp.toml) \

.github/workflows/ci-linux-e2e.yml

@@ -1,10 +1,10 @@
 name: ci-linux-e2e
 
 # The e2e suite (tests/e2e/run_all.sh) on Linux, called by ci.yml beside
-# ci-linux.yml after the Linux build. Six shards, assigned by measured
-# duration (tests/e2e/timings/linux.tsv, rule R4 of the 2026-10-02 CI record):
-# the table holds about 72 minutes of tests (2026-10-30, with the target-set
-# and packaging tests of 2026.10.30.1), about 12 a shard,
+# ci-linux.yml after the Linux build. Eight shards, divided by mtest by the
+# measured history of main's stores (design 2026-11-08 W8; rule R4 of the
+# 2026-10-02 CI record): about 94 minutes of tests (2026-11-08), about 12 a
+# shard one test at a time and about 6 two at a time,
 # each running the one binary build.yml produced (use-built-mcpp, rule R1).
 # Each shard writes a per-test report that the e2e-coverage job of ci.yml reads
 # (rule R5).
@@ -17,16 +17,21 @@ on:
 
 jobs:
   e2e:
-    name: e2e ${{ matrix.shard }}/6 (linux x86_64, self-host)
+    name: e2e ${{ matrix.shard }}/8 (linux x86_64, self-host)
     runs-on: ubuntu-24.04
     timeout-minutes: 45
     strategy:
       fail-fast: false
       matrix:
-        shard: [1, 2, 3, 4, 5, 6]
+        shard: [1, 2, 3, 4, 5, 6, 7, 8]
     env:
-      E2E_SHARD: ${{ matrix.shard }}/6
-      E2E_TIMINGS: tests/e2e/timings/linux.tsv
+      E2E_SHARD: ${{ matrix.shard }}/8
+      # By mtest (design 2026-11-08 W8; .github/actions/e2e-mtest): parts by
+      # the measured history of main's stores, two tests at a time (measured on
+      # one Linux shard: 220 s against 424 s one at a time, three no faster),
+      # and on a pull request the tests its change affects.
+      E2E_JOBS: '2'
+      E2E_SET: ${{ github.event_name == 'pull_request' && 'pr' || '' }}
       E2E_REPORT: ${{ github.workspace }}/e2e-report-linux-${{ matrix.shard }}.tsv
       MCPP_HOME: /home/runner/.mcpp
       # NOTE: do NOT force MCPP_VERBOSE here. The e2e suite includes tests that
@@ -79,6 +84,10 @@ jobs:
           XLINGS_HOME="$MCPP_HOME/registry" "$MCPP_VENDORED_XLINGS" install \
               mcpplibs:[email protected] mcpplibs:[email protected] -y
 
+      - uses: ./.github/actions/e2e-mtest
+        with:
+          host: linux
+
       - name: E2E suite
         # About twice the shard's budget of ten minutes (R4): reached only by a
         # hang. The per-test 600 s limit in run_all.sh names the test that hung.
@@ -98,6 +107,18 @@ jobs:
           "$MCPP" self config
           bash tests/e2e/run_all.sh
 
+      # The shard's store: main's are the history the next runs divide the suite by.
+      - name: Upload the shard's store
+        if: always()
+        timeout-minutes: 5
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-store-linux-${{ matrix.shard }}
+          path: tests/e2e/.mtest
+          include-hidden-files: true
+          if-no-files-found: ignore
+          retention-days: 14
+
       # One file, no glob: the report the e2e-coverage job of ci.yml reads.
       - name: Upload the shard's report
         if: always()

.github/workflows/ci-linux.yml

@@ -48,9 +48,20 @@ jobs:
         with:
           host: linux-x86_64
 
+      # A pull request runs the tests its change affects (`mcpp test --since`,
+      # docs/08; design 2026-11-08 W8): the base's tip is fetched, and when it
+      # cannot be, every test runs.
+      - name: The base of the change
+        if: github.base_ref != ''
+        shell: bash
+        run: |
+          if git fetch --no-tags --depth=1 origin "+refs/heads/$GITHUB_BASE_REF:refs/remotes/origin/$GITHUB_BASE_REF"; then
+            echo "MCPP_TEST_SINCE=origin/$GITHUB_BASE_REF" >> "$GITHUB_ENV"
+          fi
+
       - name: Unit + integration tests via `mcpp test`
         run: |
-          "$MCPP_FRESH" test
+          "$MCPP_FRESH" test ${MCPP_TEST_SINCE:+--since "$MCPP_TEST_SINCE"}
 
       # Each package under `modules/` carries its own tests, and they are built
       # as that package ALONE -- a configuration the root suite never produces,
@@ -81,7 +92,7 @@ jobs:
           echo "members: $(echo $members | tr '\n' ' ')"
           for m in $members; do
             echo "::group::mcpp test -p $m"
-            "$MCPP_FRESH" test -p "$m"
+            "$MCPP_FRESH" test -p "$m" ${MCPP_TEST_SINCE:+--since "$MCPP_TEST_SINCE"}
             echo "::endgroup::"
           done