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).

The line move (single PR per SPEC-009 §10.6):
- kKnownTargets: the 17 llvm rows move 22.1.8 -> 23.1.3; the gcc rows stay.
- Host defaults: macOS and Windows-with-MSVC move to llvm@23.1.3, resolving
  the [toolchain] macos/windows deviations (SPEC-009 §12). Linux keeps
  gcc@16.1.0 by design — native glibc ABI — now recorded as a §4.1 reason
  at the single pin site, with the gcc@15.1.0-musl reason beside it.
- All four known-red legs (#669) become unconditional normal legs; the
  known-red floor assertion moves to zero. The xcode-27 legs went green on
  rerun and #669 is closed.
- Readers move with the tables: workflows, the macOS action, CI tools, e2e
  fixtures, tests/matrix/expected.tsv, examples, user docs (en/zh); SPEC-009
  v0.4 records the move.
- libc++ 23 adaptation the gate caught: _LIBCPP_BEGIN_NAMESPACE_STD opens
  under the ODR-signature abi_tag pragma, and clang refuses to add abi_tag
  on a redeclaration — e2e 133's verbose_abort override now spells the
  namespaces by hand.

The #782 repair: a held unserved-target diagnosis no longer skips the
toolchain install. A declared or --target toolchain resolves and installs
even when no payload here serves the target — a retargetable clang plus a
graph package supplying the target's system is the arrangement the openkal
rows exist for, and the skip fired before the graph release could run the
moment the suite stopped installing the pinned version out of band
(measured on the openkal macos leg, twice). When the install itself fails
and the diagnosis stands, it releases there. e2e 890 pins the contract on
the mac/windows legs.

The e2e toolchain-version abstraction: tests/e2e/_toolchain_env.sh is the
one place a test learns a toolchain version — override, newest installed,
fallback constant, per family — and the llvm family's ~90 literals across
38 scripts now read it. The next line move edits one file here. _llvm_env.sh
becomes an alias shim.

Closes #780. Closed #669 (xcode-27 legs green on rerun). Files #782 as the
remaining openkal macos regression this repair addresses.

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