feat: support native Linux ARM64 with LLVM 23.1.3

Add the ARM64 first-run pin, native GNU host row and runtime paths; preserve explicit musl and existing user defaults. Add cold payload admission, complete xcode-27 shards, respect MCPP_HOME and capture Windows compiler failure evidence.

Prepare release 2026.10.8.1. Native ARM64 remains preview until the coordinated resources and client release pass the measured integration gates.

Refs: #784, #783

Author: speak-agent

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

@@ -0,0 +1,77 @@
+---
+subject: toolchain
+status: active
+---
+
+# LLVM 23.1.3 Part 2：任务依赖与生态交付记录
+
+本记录落实 [Part 2 方案](2026-10-08-llvm-2313-linux-aarch64-ecosystem-part2-design.md)。
+状态只根据代码、构建进程、CI、发布资源和真实消费结果更新。未执行的门不计为完成。
+维护者已授权实现、每仓库集中 PR、CI 修复、发布、CN 镜像补传、SubOS 实测及已完成 issue 的关闭。
+
+## 1. 架构边界与任务依赖
+
+```mermaid
+flowchart TD
+    A[当前事实与问题复现] --> B[原生 ARM64 配套资源构建]
+    A --> C[xlings 元数据架构上下文修复]
+    A --> D[mcpp 引擎与 review 缺口修正]
+    B --> E[LLVM ARM64 carve 与准入]
+    C --> F[xlings 三平台 CI与发布]
+    F --> G[索引客户端与架构资源接线]
+    E --> G
+    G --> H[索引双镜像和原生消费 CI]
+    H --> I[mcpp 全矩阵与 openkal 联测]
+    D --> I
+    I --> J[生态自审与合入]
+    J --> K[mcpp 发布与索引传播]
+    K --> L[CN SubOS与生态闭环审计]
+```
+
+LLVM 与 glibc 是原生 aarch64 的新默认组合；x86_64 保持 GCC，显式旧配置保留。
+资源选择按客户端进程 ABI，不能以硬件架构替代；这保持 Rosetta、WOW64 和 Linux emulation 的一致性。
+同一 glibc loader 与核心库来源绑定是稳定性门。libc++ 与 libstdc++ 的 C++ ABI 不混用。
+
+## 2. 仓库交付与责任
+
+| 任务 | 仓库与跟踪 | 依赖 | 验收依据 | 当前状态 |
+|---|---|---|---|---|
+| T1 review 修正与引擎默认 | [mcpp #784](https://github.com/mcpp-community/mcpp/issues/784)，沿用 #781 | T4 公开资源后完整 CI | 冷 home、默认双轴、GNU native、自举、modules、Windows 诊断 | 实现中 |
+| T2 ARM64 配套与 carve | [xim-pkgindex #937](https://github.com/openxlings/xim-pkgindex/issues/937) | 原生构建机 | 架构、来源摘要、loader/runtime、编译运行 | 原生构建已启动 |
+| T3 配方元数据上下文 | [xlings #646](https://github.com/openxlings/xlings/issues/646) | 现有 libxpkg LoaderContext | metadata 与 install 相同架构；三平台回归 | 已复现并实现，构建中 |
+| T4 索引接线与镜像 | [xim-pkgindex #938](https://github.com/openxlings/xim-pkgindex/pull/938) | T2、T3 发布 | 每架构哈希、旧版本拒绝、双镜像 GET、消费门 | draft |
+| T5 原生与生态消费 | mcpp、xlings、mcpp-index、openkal | T1、T4 | 原生 ARM64、CN SubOS sandbox、真实 build/test/run/pack | 待资源与客户端就绪 |
+| T6 自审与发布 | mcpp、xlings、资源与索引 | T1–T5 | 最终头 CI、发版产物、指针传播、消费审计 | 待前置门 |
+
+单个仓库的实现集中在一个 PR：mcpp 沿用 #781，索引使用 #938；xlings 因实测发现客户端缺陷而新增必要 PR。
+发布版本同时纳入相应实现 PR。发布后生成的资源索引更新依赖已发布摘要，若不能纳入尚未合入的索引 PR，
+使用必要的自动索引收尾 PR；bootstrap pin 也只在资源已公开且索引传播后前移。该依赖不能通过提前填写未来版本规避。
+
+## 3. 多角度验收
+
+| 角度 | 约束 | 可验证证据 |
+|---|---|---|
+| 架构 | runtime、target、client ABI 分别命名 | ELF、LoaderContext、GNU/musl target 与解析报告 |
+| 稳定性 | loader 与 libc 同源、私有共享库闭包 | NEEDED、INTERP、RUNPATH、运行与 relocation 探针 |
+| 简洁性 | 使用现有 host row、两包 carve、统一 recipe loader | 无新 toolchain 语法、无第二套资源解析器 |
+| 用户体验 | 新安装不要求手工装配依赖 | new/build/run 冷安装及诊断 |
+| 兼容性 | 旧配置与历史版本保持事实边界 | 旧 LLVM 在 ARM64 不误报可装，旧 x86 recipe 不回归 |
+| 跨平台 | 只扩展已发布架构，不扩大 GNU cross 承诺 | 各宿主矩阵与具名 refusal |
+| 一致性 | 元数据读取与 install 使用同一上下文 | live recipe、catalog、安装对照测试 |
+| 升级 | 保留声明，说明双轴差异，不悄悄改 ABI | fresh 与 retained defaultTarget、prebuilt/BMI 失效检查 |
+| 覆盖 | capability、分片和缓存前提必须可观察 | 按镜像完整分片，890 冷安装，candidate 精确钉 |
+| 生态 | 索引与发布版客户端实际协作 | CN sandbox、mcpp-index、openkal 运行与 pack |
+
+## 4. 已取得的证据
+
+2026-10-08：发布版 xlings 2026.10.4.1 在隔离 XLINGS_HOME 中通过 add-xpkg 和 info
+读取 `description = os.arch()` 的 live recipe，输出 `recipe architecture: unknown`。
+代码核查确认 catalog 元数据读取省略 LoaderContext，install 则传入平台与进程架构。
+T3 将两者统一；这项必要客户端修复应在新 ARM64 loader metadata 公开前发布。
+
+索引原生资源构建：[run 37684733504](https://github.com/openxlings/xim-pkgindex/actions/runs/37684733504)，
+ubuntu-24.04-arm，生成 UAPI、zlib、libxml2、gcc-runtime、glibc 和 LLVM 双包。
+这是运行中的构建，尚无资源通过或发布结论。
+
+本地测试按变更契约聚焦执行，避免用重复测试占据资源制作与集成时间。
+最终闭环审计仍须逐项覆盖方案 G0–G9；局部通过不能替代整个生态已可用。

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

@@ -18,7 +18,7 @@ superseded_by: 2026-09-07-....md  # when status is superseded
 ---
 ```
 
-328 records.
+330 records.
 
 ## By subject
 
@@ -97,6 +97,8 @@ Records that declare one. Everything else is listed by date below.
 
 ### toolchain
 
+- [LLVM 23.1.3 Part 2：任务依赖与生态交付记录](2026-10-08-llvm-2313-part2-execution-and-dependencies.md) — active
+- [LLVM 23.1.3 Part 2：Linux aarch64 默认工具链与 glibc 生态闭环](2026-10-08-llvm-2313-linux-aarch64-ecosystem-part2-design.md) — active
 - [LLVM 23.1.3 全平台统一默认:跨仓库联动方案(mcpp × xim-pkgindex)](2026-10-07-llvm-2313-unified-default-cross-repo-design.md) — active
 
 ### triage
@@ -122,6 +124,8 @@ Records that declare one. Everything else is listed by date below.
 
 ### 2026-10
 
+- [LLVM 23.1.3 Part 2：任务依赖与生态交付记录](2026-10-08-llvm-2313-part2-execution-and-dependencies.md) — active
+- [LLVM 23.1.3 Part 2：Linux aarch64 默认工具链与 glibc 生态闭环](2026-10-08-llvm-2313-linux-aarch64-ecosystem-part2-design.md) — active
 - [LLVM 23.1.3 全平台统一默认:跨仓库联动方案(mcpp × xim-pkgindex)](2026-10-07-llvm-2313-unified-default-cross-repo-design.md) — active
 - [2026.10.5.3 发布方案：32 位 x86 的架构词汇、资源编译器的识别与增量（#776 后续）](2026-10-06-windows-x86-arch-vocabulary-and-rc-follow-ups-design.md) — active
 - [下一个版本的发布方案：标准库模块、原生 MSVC LTO 与导出发现、共享库的链接配置、Windows 参数引号（#768 后续、#770、#771）](2026-10-05-std-module-pair-msvc-lto-and-export-discovery-design.md) — active

.agents/docs/README.md

@@ -29,6 +29,19 @@ fi
 # The toolchain mcpp.toml names for this host is the one the build used, so it
 # is the one whose payloads hold the binary's runtime.
 manifest_toolchain() {
+    # Native ARM64 overrides the platform-wide GCC pin. Consumers must install
+    # the same payload used by build.yml, including the first launch's runtime.
+    if [ "$host" = linux-aarch64 ]; then
+        local native
+        native="$(awk '
+            /^\[/ { in_tc = ($0 == "[target.aarch64-linux-gnu]"); next }
+            in_tc && $1 == "toolchain" { gsub(/"/, "", $3); print $3; exit }
+        ' mcpp.toml)"
+        if [ -n "$native" ]; then
+            printf '%s\n' "$native"
+            return
+        fi
+    fi
     local key
     case "$host" in
         macos-*)   key=macos ;;

.github/actions/use-built-mcpp/use.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Positive admission for the native Linux ARM64 LLVM payload.
+set -euo pipefail
+[[ "$(uname -s)" == Linux && "$(uname -m)" == aarch64 ]] || {
+    echo 'FAIL: this gate requires a native Linux aarch64 host'; exit 1;
+}
+MCPP="${MCPP:-mcpp}"
+"$MCPP" toolchain install llvm 23.1.3
+MCPP_E2E_LLVM_VERSION=23.1.3 source tests/e2e/_toolchain_env.sh
+[[ -x "$LLVM_ROOT/bin/clang++" ]] || { echo 'FAIL: LLVM frontend missing'; exit 1; }
+file -L "$LLVM_ROOT/bin/clang++" | grep -q 'ARM aarch64' || {
+    echo 'FAIL: LLVM frontend is not native ARM64'; exit 1;
+}
+"$LLVM_ROOT/bin/clang++" --version
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+export MCPP_HOME="$work/mcpp-home"
+"$MCPP" self config --mirror "${MCPP_E2E_MIRROR:-GLOBAL}"
+"$MCPP" self env --format json | python3 -c 'import json,sys; d=json.load(sys.stdin); assert d["data"]["defaultToolchain"] == "llvm@23.1.3", d'
+"$MCPP" new "$work/native-probe"
+cd "$work/native-probe"
+"$MCPP" build
+"$MCPP" run
+binary="$(find target/aarch64-linux-gnu -type f -path '*/bin/native-probe' | head -1)"
+[[ -n "$binary" ]] || { echo 'FAIL: default did not produce a native GNU artifact'; exit 1; }
+readelf -l "$binary" | grep -q 'ld-linux-aarch64.so.1' || {
+    echo 'FAIL: native default is not glibc-linked'; exit 1;
+}
+"$MCPP" build --target aarch64-linux-musl --toolchain gcc@16.1.0-musl
+"$MCPP" run --target aarch64-linux-musl --toolchain gcc@16.1.0-musl
+printf '%s\n' 'PASS: native ARM64 LLVM installs, builds and runs'

.github/tools/check_aarch64_llvm_deferral.sh

@@ -44,6 +44,13 @@ def expected_phrases(spec: str, os_name: str, arch: str) -> dict[str, list[str]]
                 "docs/20-toolchains.md": [f"- Linux x86_64 uses {s}"],
                 "docs/zh/20-toolchains.md": [f"- Linux x86_64 使用面向原生 glibc ABI 的 {s}"],
             }
+        if arch in ("aarch64", "arm64"):
+            return {
+                "docs/01-getting-started.md": [f"| Linux aarch64 | {s} |"],
+                "docs/zh/01-getting-started.md": [f"| Linux aarch64 | {s} |"],
+                "docs/20-toolchains.md": [f"- Linux aarch64 uses {s}"],
+                "docs/zh/20-toolchains.md": [f"- Linux aarch64 使用面向原生 glibc ABI 的 {s}"],
+            }
         return {
             "docs/01-getting-started.md": [f"| other Linux architectures | {s} |"],
             "docs/zh/01-getting-started.md": [f"| 其它 Linux 架构 | {s} |"],

.github/tools/check_aarch64_llvm_payload.sh

@@ -224,12 +224,27 @@ def last_statement(script: str) -> str:
     return stmts[-1] if stmts else ""
 
 
+def incomplete_shards(matrix_text: str) -> list[str]:
+    """Each explicitly declared image runs every shard exactly once."""
+    rows = re.findall(r"- image:\s*(\S+)\s+shard:\s*(\d+)\s+shards:\s*(\d+)", matrix_text)
+    grouped: dict[str, list[tuple[int, int]]] = {}
+    for image, shard, total in rows:
+        grouped.setdefault(image, []).append((int(shard), int(total)))
+    problems = []
+    for image, entries in grouped.items():
+        totals = {n for _, n in entries}
+        if len(totals) != 1 or sorted(s for s, _ in entries) != list(range(1, entries[0][1] + 1)):
+            problems.append(f"W4 image {image}: incomplete or duplicate shard coverage {entries}")
+    return problems
+
+
 def check(workflows: list[Path], check_open: bool) -> list[str]:
     problems: list[str] = []
     known_red: list[tuple[str, str, int]] = []
     for path in workflows:
         wf = parse(path)
         for job in wf.jobs:
+            problems.extend(f"{p} ({path}:{job.line})" for p in incomplete_shards(job.matrix_text))
             for step in job.steps:
                 where = f"{path}:{step.line} ({job.key} / {step.name or 'unnamed step'})"
                 shell = effective_shell(wf, job, step)

.github/tools/check_default_toolchain_docs.py

@@ -37,6 +37,9 @@ jobs:
           - image: xcode-27
             shard: 1
             shards: 2
+          - image: xcode-27
+            shard: 2
+            shards: 2
     runs-on: ${{ matrix.image }}
     timeout-minutes: 60
     env:

.github/tools/check_workflow_assertions.py

@@ -99,12 +99,12 @@ jobs:
           done
           [ "$fail" = 0 ] || exit 1
 
-      # A DEFERRAL NOBODY RECHECKS IS INDISTINGUISHABLE FROM A DEFECT. This
-      # step fails when its reason STOPS holding — the day an aarch64 llvm is
-      # published — which is the opposite of what a check usually does.
-      - name: The aarch64 llvm deferral still has its reason
+      - name: Native ARM64 LLVM payload admission
         if: matrix.host == 'linux-aarch64'
-        run: bash .github/tools/check_aarch64_llvm_deferral.sh
+        env:
+          MCPP: ${{ env.MCPP_UNDER_TEST }}
+          MCPP_VENDORED_XLINGS: ${{ env.XLINGS_BIN }}
+        run: bash .github/tools/check_aarch64_llvm_payload.sh
 
       - name: Each invariant RAN
         run: |
@@ -162,7 +162,7 @@ jobs:
               "OK: a capability pin is not a preference" \
               "gcc is not installed here" || fail=1
           fi
-          if [ "${{ matrix.host }}" = linux-x86_64 ]; then
+          if [[ "${{ matrix.host }}" = linux-* ]]; then
             check 298_overriding_a_convention_requires_replacing_it.sh \
               "OK: a convention may be overridden, but not merely removed" || fail=1
           else
@@ -308,6 +308,9 @@ jobs:
           want="$(awk -F'\t' -v h='${{ matrix.host }}' \
                     'NF>=11 && $2==h {print $4}' tests/matrix/expected.tsv \
                   | sort -u)"
+          if [ "${{ matrix.host }}" = linux-aarch64 ]; then
+            want="$(printf '%s\n' "$want" llvm@23.1.3 | sort -u)"
+          fi
           if [ -z "$want" ]; then
             echo "  ?   ${{ matrix.host }} 尚无期望行 —— 扫描它现有的工具链"
             exit 0
@@ -343,6 +346,9 @@ jobs:
           MATRIX_COMPILERS="$(awk -F'\t' -v h='${{ matrix.host }}' \
                                 'NF>=11 && $2==h {print $4}' tests/matrix/expected.tsv \
                               | sort -u | tr '\n' ' ')"
+          if [ "${{ matrix.host }}" = linux-aarch64 ]; then
+            MATRIX_COMPILERS="$MATRIX_COMPILERS llvm@23.1.3"
+          fi
           export MATRIX_COMPILERS
           echo "declared compiler axis: ${MATRIX_COMPILERS:-<none — scanning what is installed>}"
           # 两种体系各自成表。scan 把 mode 写进第一列,而比对必须按 mode 分开