test: consume indexed JSON in the openkal cross matrix

Author: speak-agent

.agents/docs/2026-10-08-llvm-2313-linux-aarch64-ecosystem-part2-design.md

@@ -637,3 +637,20 @@ ARM64 原生门在 286 中复用已解析的依赖和缓存，构建并运行同
 线程源码。发布后的 CN SubOS 门执行相同原生检查，并将线程交叉
 产物交给三个目标系统运行。此补充属于验收要求，跨平台通过结果
 另由执行记录陈述。
+
+### 14.5 2026-10-08 代表性索引库交叉验收补充
+
+第 14.3 节第 5 项的交叉路径以 `nlohmann.json@3.12.0` 为代表库。
+现有托管线程应用增加真实 `nlohmann.json` 模块依赖，验证 JSON 的
+序列化、解析、字面量及 ordered_json 键序。模块由实际 mcpp-index
+配方和经哈希核对的上游源码生成，未以测试内的模拟模块替代。
+
+四宿主构建分别记录 mcpp-index 提交，并在目标运行门比较来源；
+应用仍按三个目标构建且由对应系统运行。原生 ARM64 与发布后的
+CN SubOS 使用实际索引 checkout 供应同一依赖。库行为与 TLS/
+线程行为各有独立成功行，目标门要求两者均出现。
+
+原生 GNU 门中的 cjson、sqlite3、fmtlib.fmt、nlohmann.json 四成员
+继续保留。其结果不扩展为四库均可在所有 openkal 目标运行；本轮
+代表性库交叉声明仅覆盖上述 JSON 模块。其他库所需的平台接口、
+文件锁、网络或 TLS provider 按其能力契约另行验证。

.agents/docs/2026-10-08-llvm-2313-part2-execution-and-dependencies.md

@@ -400,3 +400,30 @@ helper 在 Windows 的 Bash 环境中先用 `cygpath -u` 规范输出路径，
 按 PATH 查找。运行时目录由 `cd` 与 `pwd` 获取。该更正不改变
 引擎、线程源码或 GNU 单测发现，其 Windows 实际验证仍由随后 CI
 承担。
+
+## 18. 2026-10-08 代表性索引库交叉覆盖补充
+
+生态复核确认第 14.3 节第 5 项尚有缺口：四个真实索引成员在
+原生 GNU 上通过，不能证明代表性库的 openkal 交叉路径。现有
+托管应用增加真实 `nlohmann.json@3.12.0` 模块和行为检查，复用
+既有构建与目标运行 job。四宿主记录实际 mcpp-index 提交，目标
+门同时检查 JSON 与线程成功行。原生门及正式 CN SubOS 使用实际
+索引 checkout 供应同一库，原有上游 same-source 示例保留。
+
+本地使用 mcpp-index 提交 `5fc151e0abed68788d9fa7b47e6e3ccb50607706`
+与 openkal-llvm-runtime 提交 `b4198d346cf0682c95dc0e51b5c32b096843ee83`，
+真实 JSON 模块与应用构建成功。原生应用实际运行 JSON 序列化、
+解析、字面量、键序及 TLS/线程检查，286 的静态闭包与双成功行
+检查通过。macOS ARM64 与 Windows x64 交叉编译链接分别在
+10.70 秒与 7.08 秒完成，其产物架构及 OS 依赖闭包通过检查；
+这两份产物的目标系统运行仍须后续 CI 验证。
+
+本地线程应用源码模板 SHA256 为
+`cc93548236b09d1d6ea388753782069fc847642b98678c2db94b74c4054c6a6b`。
+该记录区分第三方模块的实际消费与仅构建 openkal/标准库的旧样例，
+不声明未经此门验证的其他库交叉兼容性。
+
+新增库补充提交前，路径修正提交 `3341ae5e` 的 Windows openkal
+job `113112389601` 已成功，实际完成原有样例与线程应用的三个
+目标构建，验证第 17 节原生 Windows 路径规范化更正。该 job 使用
+新增 JSON 行为检查之前的线程源码，不替代本节新增库的最终 CI。

.github/tools/check_openkal_hosted_threads.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 # Build a hosted companion beside an existing runtime checkout/cache. Running
 # the resulting binary belongs to the target runner, which needs no toolchain.
+# MCPP_OPENKAL_INDEX optionally selects the actual nlohmann recipe checkout.
 set -euo pipefail
 if [ "$#" -lt 2 ] || [ "$#" -gt 3 ]; then
     echo "usage: $0 RUNTIME_CHECKOUT TARGET [OUTPUT_BINARY_PATH_FILE]" >&2
@@ -34,6 +35,23 @@ fixture="$runtime_root/examples/mcpp-hosted-threads"
 mkdir -p "$fixture/src"
 cp "$repo_root/tests/fixtures/openkal-hosted-threads/mcpp.toml" "$fixture/mcpp.toml"
 cp "$repo_root/tests/fixtures/openkal-hosted-threads/src/main.cpp.in" "$fixture/src/main.cpp"
+if [ -n "${MCPP_OPENKAL_INDEX:-}" ]; then
+    index_path="$MCPP_OPENKAL_INDEX"
+    manifest_path="$fixture/mcpp.toml"
+    if command -v cygpath >/dev/null 2>&1; then
+        index_path=$(cygpath -m "$index_path")
+        manifest_path=$(cygpath -m "$manifest_path")
+    fi
+    python3 - "$manifest_path" "$index_path" <<'PYINDEX'
+import json, os, pathlib, sys
+manifest = pathlib.Path(sys.argv[1]).resolve()
+index = pathlib.Path(sys.argv[2]).resolve()
+assert (index / "pkgs/n/nlohmann.json.lua").is_file(), index
+relative = os.path.relpath(index, manifest.parent)
+with manifest.open("a") as output:
+    output.write("\n[indices]\nnlohmann = { path = " + json.dumps(relative) + " }\n")
+PYINDEX
+fi
 cd "$fixture"
 "$mcpp_bin" build --target "$target" --toolchain "$llvm_toolchain"
 binaries=()

.github/tools/check_published_arm64_cn_ecosystem.sh

@@ -76,14 +76,16 @@ grep -q "Hello from $project!" "$work/deployed.log"
 cd "$work"
 git clone --depth 1 --branch "v$version" https://github.com/mcpp-community/mcpp mcpp-source
 git -C mcpp-source rev-parse HEAD | tee "$work/mcpp-source-sha.txt"
+git clone --depth 1 https://github.com/mcpp-community/mcpp-index index-source
+git -C index-source rev-parse HEAD | tee "$work/index-source-sha.txt"
+export MCPP_OPENKAL_INDEX="$work/index-source"
 cd mcpp-source
 bash tests/e2e/286_the_openkal_stack_still_builds.sh | tee "$work/openkal-native.log"
 ! grep -q 'SKIP' "$work/openkal-native.log"
 grep -qF 'OK: the openkal stack builds, links statically and runs' "$work/openkal-native.log"
 grep -qxF 'openkal hosted threads: isolation, destructors and concurrent unwind ok' "$work/openkal-native.log"
+grep -qxF 'openkal indexed JSON: dump, parse, literals and ordered_json ok' "$work/openkal-native.log"
 cd "$work"
-git clone --depth 1 https://github.com/mcpp-community/mcpp-index index-source
-git -C index-source rev-parse HEAD | tee "$work/index-source-sha.txt"
 export CN_PROBE_MCPP="$MCPP" CN_PROBE_TARGET="$native" CN_PROBE_WORK="$work"
 cat > "$work/llvm-consumer" <<'ADAPTER'
 #!/usr/bin/env bash
@@ -113,6 +115,7 @@ cd "$work/openkal-source/examples/same-source"
 readobj="$MCPP_HOME/registry/data/xpkgs/xim-x-llvm/23.1.3/bin/llvm-readobj"
 [[ -x "$readobj" ]] || { echo 'LLVM readobj unavailable'; exit 1; }
 mkdir -p "$work/cross"
+cp "$work/index-source-sha.txt" "$work/cross/index-source-sha.txt"
 sha256sum "$work/mcpp-source/tests/fixtures/openkal-hosted-threads/src/main.cpp.in" | cut -d ' ' -f 1 > "$work/cross/threads-source-sha256.txt"
 for target in x86_64-linux-gnu aarch64-macos x86_64-windows-gnu; do
     rm -rf target

.github/workflows/ci-aarch64-fresh-install.yml

@@ -388,10 +388,12 @@ jobs:
           MCPP_E2E_EXPECT_ARCH: aarch64
         run: |
           set -euo pipefail
+          export MCPP_OPENKAL_INDEX="$GITHUB_WORKSPACE/_native-mcpp-index"
           bash tests/e2e/286_the_openkal_stack_still_builds.sh 2>&1 | tee "$RUNNER_TEMP/native-llvm-arm64/openkal.log"
           ! grep -q '^SKIP:' "$RUNNER_TEMP/native-llvm-arm64/openkal.log"
           grep -qF 'OK: the openkal stack builds, links statically and runs' "$RUNNER_TEMP/native-llvm-arm64/openkal.log"
           grep -qxF 'openkal hosted threads: isolation, destructors and concurrent unwind ok' "$RUNNER_TEMP/native-llvm-arm64/openkal.log"
+          grep -qxF 'openkal indexed JSON: dump, parse, literals and ordered_json ok' "$RUNNER_TEMP/native-llvm-arm64/openkal.log"
       - uses: actions/upload-artifact@v4
         if: always()
         with:

.github/workflows/ci-arm64-published-cn.yml

@@ -91,6 +91,7 @@ jobs:
           sha256sum -c SHA256SUMS
           grep -Eq '^[0-9a-f]{40}$' source-sha.txt
           grep -Eq '^[0-9a-f]{40}$' engine-release-sha.txt
+          grep -Eq '^[0-9a-f]{40}$' index-source-sha.txt
           grep -Eq '^[0-9a-f]{64}$' threads-source-sha256.txt
           chmod +x "$TARGET_FILE"
           if [ "$TARGET_SYSTEM" = macos ]; then
@@ -113,6 +114,7 @@ jobs:
           "./$threads_file" > threads.log 2>&1
           cat threads.log
           grep -qxF 'openkal hosted threads: isolation, destructors and concurrent unwind ok' threads.log
+          grep -qxF 'openkal indexed JSON: dump, parse, literals and ordered_json ok' threads.log
       - uses: actions/upload-artifact@v4
         if: always()
         with:

.github/workflows/openkal-cross.yml

@@ -251,9 +251,13 @@ jobs:
           "$GITHUB_WORKSPACE/.github/tools/git_clone_retry.sh" \
             --quiet --depth 1 -b "$OPENKAL_BRANCH" \
             https://github.com/mcpplibs/openkal-llvm-runtime "$RUNNER_TEMP/okl"
+          "$GITHUB_WORKSPACE/.github/tools/git_clone_retry.sh" \
+            --quiet --depth 1 https://github.com/mcpp-community/mcpp-index "$RUNNER_TEMP/openkal-index"
+          export MCPP_OPENKAL_INDEX="$RUNNER_TEMP/openkal-index"
           cd "$RUNNER_TEMP/okl/examples/same-source"
           mkdir -p "$RUNNER_TEMP/out"
           git -C "$RUNNER_TEMP/okl" rev-parse HEAD > "$RUNNER_TEMP/out/source-sha.txt"
+          git -C "$MCPP_OPENKAL_INDEX" rev-parse HEAD > "$RUNNER_TEMP/out/index-source-sha.txt"
           echo "openkal-llvm-runtime source SHA: $(cat "$RUNNER_TEMP/out/source-sha.txt")"
           python3 - "$GITHUB_WORKSPACE/tests/fixtures/openkal-hosted-threads/src/main.cpp.in" "$RUNNER_TEMP/out/threads-source-sha256.txt" <<'PYHASH'
           import hashlib, pathlib, sys
@@ -459,6 +463,7 @@ jobs:
           fail=0
           source_sha=""
           threads_sha=""
+          index_sha=""
           mkdir -p run-evidence
           for host in linux linux-aarch64 macos windows; do
             sha_file="art/openkal-built-on-$host/source-sha.txt"
@@ -474,6 +479,10 @@ jobs:
               echo "::error::$host built source $sha, expected $source_sha"; fail=1; continue
             fi
             echo "openkal-llvm-runtime source SHA: $sha"
+            index_commit=$(tr -d '\r\n' < "art/openkal-built-on-$host/index-source-sha.txt")
+            [[ "$index_commit" =~ ^[0-9a-f]{40}$ ]] || { echo '::error::invalid index source SHA'; exit 1; }
+            if [ -z "$index_sha" ]; then index_sha="$index_commit"; fi
+            [ "$index_commit" = "$index_sha" ] || { echo '::error::index sources differ'; exit 1; }
             probe_sha=$(tr -d '\r\n' < "art/openkal-built-on-$host/threads-source-sha256.txt")
             [[ "$probe_sha" =~ ^[0-9a-f]{64}$ ]] || { echo '::error::invalid hosted probe digest'; exit 1; }
             if [ -z "$threads_sha" ]; then threads_sha="$probe_sha"; fi
@@ -516,6 +525,7 @@ jobs:
             "./$threads_bin" > "run-evidence/$host.threads.log" 2>&1
             cat "run-evidence/$host.threads.log"
             grep -qxF 'openkal hosted threads: isolation, destructors and concurrent unwind ok' "run-evidence/$host.threads.log"
+            grep -qxF 'openkal indexed JSON: dump, parse, literals and ordered_json ok' "run-evidence/$host.threads.log"
           done
           [ "$fail" = 0 ] || exit 1
           echo "four builds, one system, identical sources, exceptions and hosted TLS/threads"
@@ -722,6 +732,12 @@ jobs:
         with:
           host: linux-aarch64
 
+      - uses: actions/checkout@v4
+        with:
+          repository: mcpp-community/mcpp-index
+          ref: main
+          path: _openkal-native-index
+
       - name: Native platform and graph stack
         env:
           MCPP_VENDORED_XLINGS: ${{ env.XLINGS_BIN }}
@@ -731,17 +747,22 @@ jobs:
           set -euo pipefail
           test "$(uname -m)" = aarch64
           export MCPP="$MCPP_FRESH"
+          export MCPP_OPENKAL_INDEX="$GITHUB_WORKSPACE/_openkal-native-index"
+          git -C "$MCPP_OPENKAL_INDEX" rev-parse HEAD | tee native-openkal-index-sha.txt
           "$MCPP" toolchain install llvm 23.1.3
           # The existing test builds real openkal-musl and LLVM runtime packages,
           # verifies every graph layer, checks static ELF closure and runs it.
           bash tests/e2e/286_the_openkal_stack_still_builds.sh 2>&1 | tee native-openkal.log
           grep -qF "ok  native aarch64 ELF" native-openkal.log
           grep -qF "OK: the openkal stack builds, links statically and runs" native-openkal.log
           grep -qxF 'openkal hosted threads: isolation, destructors and concurrent unwind ok' native-openkal.log
+          grep -qxF 'openkal indexed JSON: dump, parse, literals and ordered_json ok' native-openkal.log
 
       - uses: actions/upload-artifact@v4
         if: always()
         with:
           name: openkal-native-arm64
-          path: native-openkal.log
+          path: |
+            native-openkal.log
+            native-openkal-index-sha.txt
           if-no-files-found: warn

tests/e2e/286_the_openkal_stack_still_builds.sh

@@ -49,8 +49,27 @@ default = "llvm@${LLVM_VERSION}"
 [dependencies]
 openkal-musl = "0.3.5"
 openkal-llvm-runtime = "0.1.3"
+nlohmann.json = "3.12.0"
 TOML
 
+if [ -n "${MCPP_OPENKAL_INDEX:-}" ]; then
+    index_path="$MCPP_OPENKAL_INDEX"
+    manifest_path="$PWD/mcpp.toml"
+    if command -v cygpath >/dev/null 2>&1; then
+        index_path=$(cygpath -m "$index_path")
+        manifest_path=$(cygpath -m "$manifest_path")
+    fi
+    python3 - "$manifest_path" "$index_path" <<'PYINDEX'
+import json, os, pathlib, sys
+manifest = pathlib.Path(sys.argv[1]).resolve()
+index = pathlib.Path(sys.argv[2]).resolve()
+assert (index / "pkgs/n/nlohmann.json.lua").is_file(), index
+relative = os.path.relpath(index, manifest.parent)
+with manifest.open("a") as output:
+    output.write("\n[indices]\nnlohmann = { path = " + json.dumps(relative) + " }\n")
+PYINDEX
+fi
+
 cat > src/main.cpp <<'CPP'
 #include <cstdio>
 #include <string>
@@ -160,7 +179,8 @@ if ! out="$("$bin" 2>&1)"; then
     echo "FAIL: the hosted threads companion did not run: $out"
     exit 1
 fi
-expected="openkal hosted threads: isolation, destructors and concurrent unwind ok"
+expected="openkal indexed JSON: dump, parse, literals and ordered_json ok
+openkal hosted threads: isolation, destructors and concurrent unwind ok"
 [ "$out" = "$expected" ] || { echo "FAIL: wrong hosted threads output: $out"; exit 1; }
 echo "$out"
 

tests/fixtures/openkal-hosted-threads/mcpp.toml

@@ -4,3 +4,4 @@ version = "0.1.0"
 
 [dependencies]
 openkal-llvm-runtime = { path = "../.." }
+nlohmann.json = "3.12.0"

tests/fixtures/openkal-hosted-threads/src/main.cpp.in

@@ -1,4 +1,5 @@
 import std;
+import nlohmann.json;
 
 namespace {
 std::atomic<unsigned> arrived{0};
@@ -40,6 +41,17 @@ void worker(unsigned bit) {
 }
 
 int main() {
+    using namespace nlohmann::literals;
+    const auto value = R"({"answer":42,"items":[2,4,7]})"_json;
+    const auto parsed = nlohmann::json::parse(value.dump());
+    const auto ordered = nlohmann::ordered_json::parse(R"({"z":1,"a":2})");
+    if (parsed != value || parsed["answer"].get<int>() != 42
+        || parsed["items"][2].get<int>() != 7
+        || ordered.dump() != R"({"z":1,"a":2})") {
+        std::println("openkal indexed JSON: FAILED");
+        return 1;
+    }
+    std::println("openkal indexed JSON: dump, parse, literals and ordered_json ok");
     local.value = 4;
     std::thread first(worker, 1);
     std::thread second(worker, 2);