feat(toolchain): the three iOS tiers move, each on its own reading

MEASURED ON macos-15 (Xcode 16.4, iPhoneOS and iPhoneSimulator 18.5,
`ios_deployment_target = "18.0"`), through mcpp built from this branch:

  aarch64-ios-sim  verified  arm64  platform 7 (IOSSIMULATOR)  minos 18.0
                             mcpp run --target aarch64-ios-sim  ->  1-2-3
  aarch64-ios      preview   arm64  platform 2 (IOS)           minos 18.0
  x86_64-ios-sim   preview   x86_64 platform 7 (IOSSIMULATOR)  minos 18.0

The simulator row ran through the SUPPORTED PATH -- the `runner` a manifest
declares and the program `xim:apple-simulator-tools` provides -- and not only
under a hand-written `simctl spawn`. This repository has a standing note that
publishing and verifying an asset is not the same as being able to use it
through a supported path, and the difference here was a defect: the program was
at the payload root and mcpp searched only `<payload>/bin`.

NEITHER `preview` IS WORK NOT YET DONE. `aarch64-ios` cannot be run off a
device without a signature the developer owns, which is not something a build
tool or a package can supply; `x86_64-ios-sim` cannot be run on an
Apple-silicon host, because a simulator runs the HOST's architecture. Both are
tiers bounded by a fact rather than by a gap, and the rows say so.

`platform 2` AGAINST `platform 7` IS THE PAIR WORTH HAVING A READING FOR. A
successful build cannot tell them apart, and an artefact reporting
IOSSIMULATOR from the device row is one no later step refuses.

A NEW REFUSAL CODE, BECAUSE THE MATRIX COMPARES REASONS AND NOT ONLY OUTCOMES.
`apple-sdk-absent` is distinct from `host-cannot-serve`, which says no payload
here produces the target and waits for the graph in case a package supplies the
system -- an Apple SDK is not redistributable, so no package can and nothing a
later step learns changes the answer. It is distinct from `tier-planned`, which
says the row is not wired: these rows are. Without a code the refusal would be
recorded as `other`, which `check_matrix_reasons.sh` refuses on the ground that
it freezes an unnamed branch into the expected table.

THE TIER MOVE REACHES SIX PLACES AND A SEVENTH THAT WOULD HAVE STAYED GREEN.
The engine's table, both READMEs (where one combined row became three, because
the three tiers now differ), both copies of docs/21 -- including the per-host
columns, which said `planned` everywhere and now say `SDK` on macos-arm64 and
`—` elsewhere -- the test's one-line pairs, and `examples/13`'s matrix. The
seventh is e2e 641, whose simulator case asserted `tier-planned`: it would have
gone green on an expectation the table had left behind, which is the shape
`check_target_tiers.py` was written for one axis over.

Author: speak-agent

README.md

@@ -422,7 +422,9 @@ list` reports for this machine):
 | `wasm32-emscripten` | `emsdk@6.0.9` — Emscripten ships its own sysroot and its own libc++ module surface; `mcpp run` executes the module with `node` | verified |
 | `x86_64-linux-android` | `android-ndk@30.0.16248370` — bionic from the NDK, one payload for both ABIs; ran on an API 24 x86_64 emulator image | verified |
 | `aarch64-linux-android` | the same payload and the same build; ran under qemu-user over the system image's own bionic, which the platform emulator cannot do from an x86_64 host | verified |
-| `aarch64-ios` · `aarch64-ios-sim` · `x86_64-ios-sim` | the iPhoneOS and iPhoneSimulator SDKs ship inside Xcode and are not redistributable, so the blocker is a licence rather than a payload | planned |
+| `aarch64-ios-sim` | llvm 22 plus the machine's iPhoneSimulator SDK, which mcpp locates rather than installs; ran on a simulator through `simctl-run` ³ | verified |
+| `aarch64-ios` | the same split for the device; the artefact names the iOS platform, and running it off a device needs a signature the developer owns ³ | preview |
+| `x86_64-ios-sim` | the same build; nothing ran it, because a simulator runs the host's architecture and the machine measured was Apple silicon ³ | preview |
 
 `verified` an image has been built **and run** for the row, qemu and wine
 included · `preview` it builds and links, and no emulator run has been recorded
@@ -449,6 +451,14 @@ such a target is refused rather than attempted.
 > payload produces these targets. The C library, startup code, memory layout
 > and emulator travel with a board-support package rather than with mcpp — see
 > [40 — Bare-Metal and Freestanding Targets](docs/40-baremetal.md).
+>
+> ³ The three iOS rows need a macOS host, and the compiler is still the
+> ecosystem's: `xim:llvm` emits arm64 Mach-O for an iOS deployment target. What
+> the machine supplies is the SDK, which ships inside Xcode and is not
+> redistributable, so mcpp locates it through `xcrun` exactly as it has always
+> located the macOS SDK — and refuses, naming the SDK, when it cannot. The
+> simulator session belongs to `xim:apple-simulator-tools`. See
+> [20 — Toolchain Management](docs/20-toolchains.md).
 
 ## Documentation
 

README.zh-CN.md

@@ -409,7 +409,9 @@ mcpp 的身份模型是两条正交轴:**工具链** = `family@version`(family 
 | `wasm32-emscripten` | `emsdk@6.0.9` —— Emscripten 自带 sysroot 和它自己的 libc++ 模块面;`mcpp run` 用 `node` 把模块跑起来 | verified |
 | `x86_64-linux-android` | `android-ndk@30.0.16248370` —— bionic 来自 NDK,一个载荷服务两个 ABI;在 API 24 的 x86_64 模拟器镜像上跑过 | verified |
 | `aarch64-linux-android` | 同一个载荷、同样的构建;在 qemu-user 上、配系统镜像自带的 bionic 跑过 —— 这是平台模拟器从 x86_64 宿主做不到的 | verified |
-| `aarch64-ios` · `aarch64-ios-sim` · `x86_64-ios-sim` | iPhoneOS 与 iPhoneSimulator 的 SDK 在 Xcode 里且不可再分发,所以阻塞项是许可而不是载荷 | planned |
+| `aarch64-ios-sim` | llvm 22 加上机器自己的 iPhoneSimulator SDK,mcpp 定位而不安装它;经 `simctl-run` 在模拟器上跑过 ³ | verified |
+| `aarch64-ios` | 真机取同一种切分;产物命名 iOS 平台,而把它跑在一台设备上需要开发者自己拥有的签名 ³ | preview |
+| `x86_64-ios-sim` | 同一次构建;没有东西跑过它,因为模拟器跑宿主的架构,而被测的那台是 Apple 芯片 ³ | preview |
 
 `verified` 该行的镜像已被构建**并运行**过,qemu 与 wine 都算 · `preview` 可构建
 可链接,未记录过模拟器运行 · `planned` 已登记在词表中,尚未接线 —— 面向这类目标
@@ -431,6 +433,12 @@ mcpp 的身份模型是两条正交轴:**工具链** = `family@version`(family 
 > LLVM 载荷的宿主都能产出这些目标。C 库、启动代码、内存布局与模拟器随板级支持包
 > 走,而不随 mcpp 走 —— 见
 > [40 — 裸机与 freestanding 目标](docs/zh/40-baremetal.md)。
+>
+> ³ 三条 iOS 行需要一台 macOS 宿主,而编译器仍然是生态的:`xim:llvm` 能为一个 iOS
+> 部署目标产出 arm64 Mach-O。机器供给的是 SDK —— 它在 Xcode 里且不可再分发,所以
+> mcpp 通过 `xcrun` 定位它,与它一直以来定位 macOS SDK 的方式完全相同 —— 并在找不到
+> 时点名那个 SDK 拒绝。模拟器那次会话属于 `xim:apple-simulator-tools`。见
+> [20 —— 工具链管理](docs/zh/20-toolchains.md)。
 
 ## 文档
 

docs/21-the-target-triple.md

@@ -487,9 +487,9 @@ other's rows.
 | `armv7a-none-eabihf` | verified | `llvm@22.1.8` | payload | payload | payload | payload |
 | `aarch64-linux-android` | verified | `android-ndk@30.0.16248370` | payload | payload | payload | — |
 | `x86_64-linux-android` | verified | `android-ndk@30.0.16248370` | payload | payload | payload | — |
-| `aarch64-ios` | planned | — | planned | planned | planned | planned |
-| `aarch64-ios-sim` | planned | — | planned | planned | planned | planned |
-| `x86_64-ios-sim` | planned | — | planned | planned | planned | planned |
+| `aarch64-ios` | preview | `llvm@22.1.8` | — | — | SDK | — |
+| `aarch64-ios-sim` | verified | `llvm@22.1.8` | — | — | SDK | — |
+| `x86_64-ios-sim` | preview | `llvm@22.1.8` | — | — | SDK | — |
 | `wasm32-emscripten` | verified | `emsdk@6.0.9` | payload | payload | payload | payload |
 
 `payload` a toolchain payload here produces it · `graph` no payload, but a

docs/zh/21-the-target-triple.md

@@ -437,9 +437,9 @@ CRT;图供给时是 `musl`。一个目标字符串,两个不同的 C 库 ——
 | `armv7a-none-eabihf` | verified | `llvm@22.1.8` | 载荷 | 载荷 | 载荷 | 载荷 |
 | `aarch64-linux-android` | verified | `android-ndk@30.0.16248370` | payload | payload | payload | — |
 | `x86_64-linux-android` | verified | `android-ndk@30.0.16248370` | payload | payload | payload | — |
-| `aarch64-ios` | planned | — | planned | planned | planned | planned |
-| `aarch64-ios-sim` | planned | — | planned | planned | planned | planned |
-| `x86_64-ios-sim` | planned | — | planned | planned | planned | planned |
+| `aarch64-ios` | preview | `llvm@22.1.8` | — | — | SDK | — |
+| `aarch64-ios-sim` | verified | `llvm@22.1.8` | — | — | SDK | — |
+| `x86_64-ios-sim` | preview | `llvm@22.1.8` | — | — | SDK | — |
 | `wasm32-emscripten` | verified | `emsdk@6.0.9` | payload | payload | payload | payload |
 
 `载荷` 这里有工具链载荷产出它 · `图` 没有载荷,但依赖可以供给系统 ·

examples/13-platform-targets/README.md

@@ -178,6 +178,6 @@ error: target aarch64-ios needs the iphoneos SDK, which this machine does not pr
 | `wasm32-emscripten` | verified | `emsdk@6.0.9` | 是，`node` |
 | `x86_64-linux-android` | verified | `android-ndk@30.0.16248370` | 是，平台模拟器 |
 | `aarch64-linux-android` | verified | `android-ndk@30.0.16248370` | 是，`qemu-aarch64-static` + 从镜像取出的 bionic |
-| `aarch64-ios` | planned | `llvm@22.1.8` | 否 —— 真机需要开发者自己的签名 |
-| `aarch64-ios-sim` | planned | `llvm@22.1.8` | 是，`simctl-run`（macos-15） |
-| `x86_64-ios-sim` | planned | `llvm@22.1.8` | 否 —— 模拟器跑宿主架构，而那台宿主是 arm64 |
+| `aarch64-ios` | preview | `llvm@22.1.8` | 否 —— 真机需要开发者自己的签名 |
+| `aarch64-ios-sim` | verified | `llvm@22.1.8` | 是，`simctl-run`（macos-15） |
+| `x86_64-ios-sim` | preview | `llvm@22.1.8` | 否 —— 模拟器跑宿主架构，而那台宿主是 arm64 |

modules/toolchain-model/src/triple.cppm

@@ -746,7 +746,24 @@ inline constexpr TargetInfo kKnownTargets[] = {
     // The simulator is deliberately not a row. It has its own SDK and produces
     // its own object, so folding it in would make two targets share an
     // identity -- the mistake `x86_64-windows-musl` was added to undo.
-    { "aarch64-ios",           "planned",   "",    "llvm@22.1.8","",                            false },
+    //
+    // `preview`: BUILT, AND NOT RUN, AND NOTHING HERE CAN RUN IT. Measured
+    // 2026-09-11 on macos-15 (Xcode 16.4, iPhoneOS 18.5,
+    // `ios_deployment_target = "18.0"`):
+    //
+    //   Mach-O 64-bit executable arm64
+    //   LC_BUILD_VERSION  platform 2 (IOS)  minos 18.0  sdk 18.5
+    //
+    // `platform 2` against the simulator rows' `platform 7` is the reading
+    // worth having: a successful build cannot tell them apart, and an artefact
+    // reporting IOSSIMULATOR from this row is one no later step refuses.
+    //
+    // The row keeps `runner` unset and will stay `preview`. An artefact cannot
+    // be run off an iOS device without a signature the developer owns, which
+    // is not something a build tool or a package can supply -- so this is a
+    // tier bounded by a fact about the platform rather than by work not yet
+    // done.
+    { "aarch64-ios",           "preview",   "",    "llvm@22.1.8","",                            false },
     // THE SIMULATOR'S TWO ROWS. Not a convenience and not a runner: a
     // simulator build has its own SDK (`iPhoneSimulator.sdk`), produces its own
     // object, and takes `-mios-simulator-version-min` rather than
@@ -759,13 +776,26 @@ inline constexpr TargetInfo kKnownTargets[] = {
     // an Intel one needs `x86_64`. A single row would describe a simulator half
     // the machines cannot run.
     //
-    // `planned`, and the blocker is the same licence question as the device
-    // row -- the simulator SDK ships inside Xcode and is no more
-    // redistributable than the iPhoneOS one. What these rows buy today is that
-    // `mcpp build --target aarch64-ios-sim` answers `tier-planned` naming the
-    // row, instead of `unknown target`, which was false.
-    { "aarch64-ios-sim",       "planned",   "",    "llvm@22.1.8","",                            false },
-    { "x86_64-ios-sim",        "planned",   "",    "llvm@22.1.8","",                            false },
+    // ONE `verified` AND ONE `preview`, AND THE DIFFERENCE IS THE HOST'S
+    // ARCHITECTURE RATHER THAN ANYTHING ABOUT THE ROWS.
+    //
+    // `aarch64-ios-sim` was built AND RUN. Measured 2026-09-11 on macos-15
+    // (Xcode 16.4, iPhoneSimulator 18.5, `ios_deployment_target = "18.0"`):
+    //
+    //   artefact  Mach-O 64-bit executable arm64
+    //             LC_BUILD_VERSION  platform 7 (IOSSIMULATOR)  minos 18.0
+    //   run       xcrun simctl spawn <udid> <artefact>  ->  1-2-3
+    //
+    // with no bundle, no signature and no Info.plist -- the measurement that
+    // made `simctl-run` a boot-and-spawn wrapper rather than a bundle builder.
+    //
+    // `x86_64-ios-sim` builds and its artefact is correct -- Mach-O x86_64,
+    // the same `platform 7`, the same floor -- and nothing ran it, because a
+    // SIMULATOR RUNS THE HOST'S ARCHITECTURE and the runner is Apple silicon.
+    // That is a property of the machine the measurement was taken on, so the
+    // row stays `preview` until an Intel host takes it.
+    { "aarch64-ios-sim",       "verified",  "",    "llvm@22.1.8","",                            false },
+    { "x86_64-ios-sim",        "preview",   "",    "llvm@22.1.8","",                            false },
 
     // WEB IS THE OUTLIER, AND IT IS THE ONLY ONE OF THE THREE THAT CHANGES THE
     // MODEL RATHER THAN EXTENDING A TABLE. A new arch (`wasm32`), a new os

src/build/prepare.cppm

@@ -2493,6 +2493,11 @@ prepare_build(bool print_fingerprint,
                 : mcpp::platform::macos::sdk_iphoneos;
             appleSdkLocated = mcpp::platform::macos::sdk_path(which);
             if (!appleSdkLocated) {
+                // A CODE, BECAUSE THE MATRIX COMPARES REASONS AND NOT ONLY
+                // OUTCOMES. A refusal with no code is recorded as `other`,
+                // which `check_matrix_reasons.sh` refuses on the ground that
+                // it freezes an unnamed branch into the expected table.
+                refusal::record(refusal::Code::AppleSdkAbsent);
                 return std::unexpected(std::format(
                     "target {} needs the {} SDK, which this machine does not "
                     "provide.\n"

src/build/refusal.cppm

@@ -93,6 +93,13 @@ enum class Code {
     // hold. Distinct from VersionFloorUnmet, which is about the machine: this
     // one is about two manifests disagreeing over a tool.
     ToolVersionConflict,
+    // An Apple SDK this target needs is not on this machine. Distinct from
+    // HostCannotServe, which says no PAYLOAD here produces the target and
+    // waits for the graph in case a package supplies the system: an Apple SDK
+    // is not redistributable, so no package can supply it and nothing a later
+    // step learns changes the answer. Distinct from TierPlanned, which says
+    // the row is not wired at all -- these rows are.
+    AppleSdkAbsent,
     Other,                 // a refusal that has not been given a code yet
 };
 
@@ -104,6 +111,7 @@ constexpr std::string_view name(Code c) {
         case Code::CompilerRequirementConflict:
                                          return "compiler-requirement-conflict";
         case Code::TierPlanned:          return "tier-planned";
+        case Code::AppleSdkAbsent:       return "apple-sdk-absent";
         case Code::HostCannotServe:      return "host-cannot-serve";
         case Code::CapabilityPin:        return "capability-pin";
         case Code::ConventionUnreplaced: return "convention-unreplaced";

tests/e2e/641_the_android_rows_are_wired_and_the_simulator_is_a_row.sh

@@ -60,23 +60,48 @@ for target in aarch64-linux-android x86_64-linux-android; do
     fi
 done
 
-# 3. THE SIMULATOR IS A ROW, so its spelling resolves. Before it existed,
-#    `--target aarch64-ios-sim` answered `unknown target`, which was false: the
-#    vocabulary has the device row and the simulator is a different target, not
-#    an unspellable one.
+# 3. THE SIMULATOR IS A ROW, so its spelling resolves -- and the reason it is
+#    refused on this host moved when the tier did.
+#
+#    Before the rows existed, `--target aarch64-ios-sim` answered `unknown
+#    target`, which was false. Then it answered `tier-planned`, which was true
+#    while nothing had built one. It now answers the SDK gate, because the rows
+#    are `verified` and `preview` and the thing this machine lacks is the SDK.
+#
+#    ALL THREE ANSWERS ARE ASSERTED AGAINST, not just the first: `unknown
+#    target` is a lie about the vocabulary, and `tier-planned` after the tier
+#    moved would mean the table and the gate disagree.
 for target in aarch64-ios-sim x86_64-ios-sim; do
     d="$t/sim-$target"; pkg "$d"
     out=$( cd "$d" && MCPP_NO_AUTO_INSTALL=1 "$MCPP" build --target "$target" 2>&1 ) || true
-    if grep -q "unknown target" <<<"$out"; then
-        echo "FAIL: $target reported as unknown; it is a registered row"
-        fail=1
-    elif grep -q "not yet supported (planned)" <<<"$out"; then
-        echo "  ok: $target says planned, naming the row"
-    else
-        echo "FAIL: $target refused for neither reason"
-        grep -m2 -E "^error" <<<"$out" | sed 's/^/    /'
-        fail=1
-    fi
+    case "$(uname -s)" in
+      Darwin)
+        # On a machine that has the SDK the row is simply built, and nothing
+        # here asserts the artefact -- ci-macos-ios.yml does that.
+        if grep -qE "unknown target|not yet supported \(planned\)" <<<"$out"; then
+            echo "FAIL: $target refused on a machine that can build it"
+            grep -m2 -E "^error" <<<"$out" | sed 's/^/    /'
+            fail=1
+        else
+            echo "  ok: $target is not refused on macOS"
+        fi
+        ;;
+      *)
+        if grep -q "unknown target" <<<"$out"; then
+            echo "FAIL: $target reported as unknown; it is a registered row"
+            fail=1
+        elif grep -q "not yet supported (planned)" <<<"$out"; then
+            echo "FAIL: $target still says planned; the table says otherwise"
+            fail=1
+        elif grep -q "needs the iphonesimulator SDK" <<<"$out"; then
+            echo "  ok: $target is refused for the SDK, naming the simulator one"
+        else
+            echo "FAIL: $target refused for none of the three known reasons"
+            grep -m2 -E "^error" <<<"$out" | sed 's/^/    /'
+            fail=1
+        fi
+        ;;
+    esac
 done
 
 # 4. AN EFFECTIVE TRIPLE mcpp PRINTS ITSELF MUST PARSE BACK.
@@ -164,8 +189,14 @@ done
 #    No payload is needed: the SDK is located before the toolchain is resolved,
 #    which is itself a property worth asserting -- a machine without Xcode used
 #    to download a 700 MB compiler before being told the compiler was not what
-#    was missing. Hence MCPP_NO_AUTO_INSTALL=1 and the explicit override, which
-#    opens the tier gate so that this gate is the one that answers.
+#    was missing. Hence MCPP_NO_AUTO_INSTALL=1.
+#
+#    THE OVERRIDE IS KEPT AND NO LONGER LOAD-BEARING. It opened the tier gate
+#    while the rows were `planned`; they are not any more, so this case would
+#    reach the SDK gate without it. It stays because the claim it makes is
+#    stronger with it: declaring a toolchain says which compiler and says
+#    nothing about where the headers are, so the SDK gate must refuse even a
+#    project that has named its own.
 for target in aarch64-ios aarch64-ios-sim; do
     d="$t/sdk-$target"
     pkg "$d" "" "[target.$target]" 'toolchain = "llvm@22.1.8"'