Move the LLVM line to 23.1.3 and the macOS/Windows host defaults with it

23.1.3 is the first point release carrying the macOS 27 arm64e.x1 ld64.lld
fix (llvm-project#222721, backported to release/23.x as ee66426) — the
release #669 was blocked on. clang 23.1.0's MSVC STL std-module defect was
fixed in 23.1.1 (#640, llvm-project#218152).

- kKnownTargets: the 17 llvm rows move 22.1.8 -> 23.1.3; the gcc rows
  (x86_64-linux-musl, aarch64-linux-musl, x86_64-windows-gnu) stay put.
- Host defaults: macOS and Windows-with-MSVC move to llvm@23.1.3, which
  also resolves the [toolchain] macos/windows deviations from their rows'
  defaults (SPEC-009 §12). Linux keeps gcc@16.1.0 by design — native glibc
  ABI, system libraries — now recorded as a §4.1 reason at the single pin
  site, together with the gcc@15.1.0-musl reason for non-x86_64 hosts.
- The xcode-27 legs become unconditional normal legs: the 22.1.8-era known
  red (#669) cannot happen on 23.1.3, so a change can change the outcome
  there again; the known-red input retires.
- Readers move with the tables: workflows, the macOS action, the CI tools,
  e2e fixtures, tests/matrix/expected.tsv, examples, and the user docs in
  both languages; check_default_toolchain_docs.py derives its phrases from
  the engine and needed no edits.
- SPEC-009 v0.4 records the move (§4.1, §6.2, §8.3, §12).

Closes #780. The xcode-27 legs going green closes #669.

Author: speak-agent

.agents/docs/2026-10-07-llvm-2313-unified-default-cross-repo-design.md

@@ -18,7 +18,7 @@ superseded_by: 2026-09-07-....md  # when status is superseded
 ---
 ```
 
-327 records.
+328 records.
 
 ## By subject
 
@@ -95,6 +95,10 @@ Records that declare one. Everything else is listed by date below.
 - [SDK toolchains, the payload/engine seam, and openkal across iOS, Android and Web](2026-09-11-sdk-toolchains-and-ios-local-verification.md) — landed
 - [Where a platform's knowledge belongs: iOS, Android and Web across the engine, the index and the plugins](2026-09-11-platform-targets-design-review.md) — active
 
+### toolchain
+
+- [LLVM 23.1.3 全平台统一默认:跨仓库联动方案(mcpp × xim-pkgindex)](2026-10-07-llvm-2313-unified-default-cross-repo-design.md) — active
+
 ### triage
 
 - [Eight reports after 2026.9.27.1: what each one is, where it belongs, and one optimisation plan](2026-09-27-eight-reports-by-home-and-one-optimisation-plan.md) — active
@@ -118,6 +122,7 @@ Records that declare one. Everything else is listed by date below.
 
 ### 2026-10
 
+- [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
 - [`mcpp run` hands the terminal to the program, and the follow-ups of #761, #763 and #765 (#766)](2026-10-05-run-terminal-handoff-and-766-follow-ups-design.md) — landed

.agents/docs/README.md

@@ -72,7 +72,7 @@ runs:
         # latest-first: test binaries now link the toolchain's own libc++
         # (A1 root fix in flags.cppm), so new llvm releases are
         # self-consistent — the macOS job is the proof for each new default.
-        xlings install llvm -y || xlings install llvm@20.1.7 -y
+        xlings install llvm@23.1.3 -y || xlings install llvm -y
         LLVM_ROOT=$(find "$HOME/.xlings" -path "*/xpkgs/xim-x-llvm/*/bin/clang++" | head -1 | xargs dirname | xargs dirname)
         ls "$LLVM_ROOT/bin/clang++"
         "$LLVM_ROOT/bin/clang++" --version

.github/actions/setup-macos-llvm/action.yml

@@ -30,7 +30,7 @@ BUILD=(
     # Built here for one reason worth the cost: it is the only example whose
     # CPU-only configuration exercises `cfg(accelerator = "none")` and two rule
     # packages in one build program, and both of those are engine paths that a
-    # description cannot cover. Its `[toolchain] default = "llvm@22.1.8"` means
+    # description cannot cover. Its `[toolchain] default = "llvm@23.1.3"` means
     # this job installs an LLVM payload it otherwise would not -- the CUDA leg
     # takes the clang route, because the nvcc route on the 12.9 line is refused
     # by nvcc's own front end and the 13.x line raises the driver floor to r580.

.github/tools/build_examples.sh

@@ -28,16 +28,16 @@
 # WHAT THIS NEEDS
 #
 # A compile database that names BMIs explicitly (-fmodule-file=...), which
-# only a build actually produces: `mcpp build --toolchain llvm@22.1.8` writes
+# only a build actually produces: `mcpp build --toolchain llvm@23.1.3` writes
 # compile_commands.json at the project root. This script does not build it:
 # the caller runs that build first. check_file_lengths.sh needs no such
 # division because it reads the tree.
 #
 # IN CI SINCE 2026.9.28.2 (#729). ci-linux.yml's "toolchain: musl + llvm" job
-# builds mcpp with llvm@22.1.8 -- failing on the build's own status, which it
+# builds mcpp with llvm@23.1.3 -- failing on the build's own status, which it
 # did not do while it built with llvm@20.1.7 and read only the resolution line
 # -- and runs this script after it, over the compile database that build
-# writes. By hand: `mcpp build --toolchain llvm@22.1.8`, then this script.
+# writes. By hand: `mcpp build --toolchain llvm@23.1.3`, then this script.
 #
 # clang-tidy itself is not part of the plain xim:llvm payload mcpp resolves
 # for `--toolchain llvm@...` (measured: xim-x-llvm/22.1.8/bin has clang,
@@ -67,7 +67,7 @@ FAIL: $CDB does not exist.
   This check reads clang-tidy's own function boundaries, which needs a
   compile database that names every imported module's BMI explicitly.
   Produce one first:
-      mcpp build --toolchain llvm@22.1.8
+      mcpp build --toolchain llvm@23.1.3
   (any installed LLVM row works; the database is written at the project
   root regardless of the row's exact version).
 EOF

.github/tools/check_function_sizes.sh

@@ -62,7 +62,7 @@ check_bytes() {
 }
 
 rows=(
-    'llvm|[toolchain]\nwindows = "llvm@20.1.7"|'
+    'llvm|[toolchain]\nwindows = "llvm@23.1.3"|'
     'msvc|[toolchain]\nwindows = "msvc@system"|'
     'mingw|[toolchain]\ndefault = "gcc@16.1.0"|--target x86_64-windows-gnu'
 )
@@ -97,7 +97,7 @@ done
 # and the header found at the directory the program printed.
 dir="$ROOT/$CJK/buildprogram"
 mkdir -p "$dir/src" "$dir/inc"
-printf '[package]\nname    = "unicodebp"\nversion = "0.1.0"\n\n[toolchain]\nwindows = "llvm@20.1.7"\n' > "$dir/mcpp.toml"
+printf '[package]\nname    = "unicodebp"\nversion = "0.1.0"\n\n[toolchain]\nwindows = "llvm@23.1.3"\n' > "$dir/mcpp.toml"
 printf '#define UNICODE_BP 42\n' > "$dir/inc/unicode_bp.h"
 cat > "$dir/build.mcpp" <<'EOF'
 #include <cstdio>

.github/tools/check_unicode_paths.sh

@@ -6,7 +6,7 @@
 
 #729: the step "Toolchain: LLVM -- build mcpp" ran
 
-    "$MCPP" build 2>&1 | tee build.log; grep -q "Resolved llvm@20.1.7" build.log
+    "$MCPP" build 2>&1 | tee build.log; grep -q "Resolved llvm@23.1.3" build.log
 
 A pipeline's status is its last command's. Under GitHub's default shell for a
 `run:` block with no `shell:` key (`bash -e {0}`, no pipefail) the build's

.github/tools/check_workflow_assertions.py

@@ -41,7 +41,7 @@ jobs:
 
       - name: Install LLVM + xmake
         run: |
-          xlings install llvm -y || xlings install llvm@20.1.7 -y
+          xlings install llvm@23.1.3 -y || xlings install llvm -y
           brew install xmake
           LLVM_ROOT=$(find "$HOME/.xlings" -path "*/xpkgs/xim-x-llvm/*/bin/clang++" | head -1 | xargs dirname | xargs dirname)
           echo "LLVM_ROOT=$LLVM_ROOT" >> "$GITHUB_ENV"

.github/workflows/bootstrap-macos.yml

@@ -59,7 +59,7 @@ concurrency:
 
 jobs:
   # ──────────────────────────────────────────────────────────────────
-  # Linux: gcc@16.1.0, musl-gcc@16.1.0, llvm@20.1.7
+  # Linux: gcc@16.1.0, musl-gcc@16.1.0, llvm@23.1.3
   # ──────────────────────────────────────────────────────────────────
   # A4: post-release runs race the xim-pkgindex bump (a PR a maintainer
   # merges asynchronously) — the 0.0.85 fresh-install failed with
@@ -226,16 +226,16 @@ jobs:
 
       - name: "LLVM: mcpp new → run"
         run: |
-          mcpp toolchain install llvm 20.1.7
-          mcpp toolchain default llvm@20.1.7
+          mcpp toolchain install llvm 23.1.3
+          mcpp toolchain default llvm@23.1.3
           cd "$(mktemp -d)"
           mcpp new hello_llvm
           cd hello_llvm
           mcpp run
 
       - name: "LLVM: build mcpp"
         run: |
-          mcpp toolchain default llvm@20.1.7
+          mcpp toolchain default llvm@23.1.3
           mcpp clean
           mcpp run
 
@@ -356,11 +356,11 @@ jobs:
           esac
 
   # ──────────────────────────────────────────────────────────────────
-  # macOS: llvm@20.1.7
+  # macOS: llvm@23.1.3
   # ──────────────────────────────────────────────────────────────────
   macos-fresh:
     needs: [wait-index]
-    name: macOS fresh install (${{ matrix.image }}${{ matrix.known_red != '' && format(', known red {0}', matrix.known_red) || '' }})
+    name: macOS fresh install (${{ matrix.image }})
     if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success' }}
     # Two images, the two ends of the supported range.
     #
@@ -379,16 +379,12 @@ jobs:
       matrix:
         include:
           - image: macos-14
-            known_red: ''
           - image: xcode-27
-            known_red: '#669'
     runs-on: ${{ matrix.image }}
-    # KNOWN RED, MACHINE-READABLY (the 2026-09-28 design, WS7). A leg whose
-    # failure has a tracked external cause carries that issue in `known_red`:
-    # the leg may fail without failing the workflow, its own result and log
-    # stay visible, and .github/tools/check_workflow_assertions.py requires
-    # the issue to be open. The leg leaves the list when #669 closes.
-    continue-on-error: ${{ matrix.known_red != '' }}
+    # While the line was on LLVM 22.1.8 the xcode-27 leg was known red (#669,
+    # the arm64e.x1 .tbd stubs, continue-on-error per the 2026-09-28 WS7
+    # design). The 23.1.3 line move removed the cause, so both images are
+    # plain required legs again.
     timeout-minutes: 30
     env:
       # The one derived value (see the header comment): every install job names
@@ -488,7 +484,7 @@ jobs:
   #   channel healthy the entire time. So the trust gate itself is asserted
   #   from BOTH sides: refused before `brew trust`, accepted after.
   macos-brew-fresh:
-    name: macOS fresh install (Homebrew, ${{ matrix.image }}${{ matrix.known_red != '' && format(', known red {0}', matrix.known_red) || '' }})
+    name: macOS fresh install (Homebrew, ${{ matrix.image }})
     if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success' }}
     # Same two images as macos-fresh: the formula declares `depends_on macos:
     # :sonoma` + arm64, macos-14 is the oldest image satisfying it, and
@@ -498,16 +494,12 @@ jobs:
       matrix:
         include:
           - image: macos-14
-            known_red: ''
           - image: xcode-27
-            known_red: '#669'
     runs-on: ${{ matrix.image }}
-    # KNOWN RED, MACHINE-READABLY (the 2026-09-28 design, WS7). A leg whose
-    # failure has a tracked external cause carries that issue in `known_red`:
-    # the leg may fail without failing the workflow, its own result and log
-    # stay visible, and .github/tools/check_workflow_assertions.py requires
-    # the issue to be open. The leg leaves the list when #669 closes.
-    continue-on-error: ${{ matrix.known_red != '' }}
+    # While the line was on LLVM 22.1.8 the xcode-27 leg was known red (#669,
+    # the arm64e.x1 .tbd stubs, continue-on-error per the 2026-09-28 WS7
+    # design). The 23.1.3 line move removed the cause, so both images are
+    # plain required legs again.
     timeout-minutes: 30
     steps:
       - name: Environment
@@ -601,7 +593,7 @@ jobs:
           fi
 
   # ──────────────────────────────────────────────────────────────────
-  # Windows WITH Visual Studio: llvm@20.1.7 + MSVC STL
+  # Windows WITH Visual Studio: llvm@23.1.3 + MSVC STL
   #
   # Two images, because the OS version is a real variable for a tool that
   # touches the UCRT, the Windows SDK and long paths. GitHub publishes no

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

@@ -67,7 +67,7 @@ jobs:
           # skip on every runner; measured 2026-10-01, seventeen such tests ran
           # nowhere. Warm runs re-install nothing.
           "$MCPP" toolchain install gcc 16.1.0-musl
-          "$MCPP" toolchain install llvm 22.1.8
+          "$MCPP" toolchain install llvm 23.1.3
           "$MCPP" toolchain install mingw-cross 16.1.0
           XLINGS_HOME="$MCPP_HOME/registry" "$MCPP_VENDORED_XLINGS" install xim:nasm -y
 
@@ -173,7 +173,7 @@ jobs:
           export MCPP_E2E_TOOLCHAIN_MIRROR=GLOBAL
           # llvm is the toolchain a freestanding target pins; install it
           # explicitly rather than relying on whatever the sandbox cache holds.
-          "$MCPP" toolchain install llvm 22.1.8
+          "$MCPP" toolchain install llvm 23.1.3
           # Run the two scripts DIRECTLY rather than through run_all.sh.
           # They are standalone (they take $MCPP and nothing else), run_all.sh
           # accepts no filter — it would run the whole 250-test suite here for
@@ -383,7 +383,7 @@ jobs:
           cd "$(mktemp -d)"
           "$MCPP" new hello195
           cd hello195
-          printf '\n[toolchain]\nlinux = "llvm@22.1.8"\n' >> mcpp.toml
+          printf '\n[toolchain]\nlinux = "llvm@23.1.3"\n' >> mcpp.toml
           printf 'import std;\nint main() { std::println("hello {}", 195); return 0; }\n' > src/main.cpp
           "$MCPP" run